main since RC4, regenerated on every build of the site: the in-progress app notes and REST API 1.303.0 to 1.339.1 (29 versions).
From the in-app What's new for Apiome 08-2026 RC5.
.avdl) import and exportscripts/generate_rest_reference_docs.py renders openapi.yaml into
apiome-docs/docs/reference/rest/ — one page per tag (plus untagged) with every operation's
parameters, request body, responses and the schemas it uses. The index records the document's
SHA-256 (openapi_sha256), and yarn docs:check fails when openapi.yaml changes without
regenerating; --check and tests/test_rest_reference_docs.py fail on stale pages. Rendering
lives in app.rest_reference_doc. No API change; the OpenAPI version moves to 1.204.1.docsPage the API
returns now names a page of the Docusaurus site instead of the retired docs/guide/ folder —
e.g. GET /v1/lint/rules → "docsPage": "apiome-docs/docs/build/lint-rules.md". The value is
still a monorepo-relative source path; apiome-ui resolves it to
https://apiome.github.io/apiome/build/lint-rules. Affected fields: lint-rule catalog and
style-guide docsPage, blocking-rule docs_page (schema → build/lint-rules, MCP →
govern/mcp-*-rules), axis algorithmDocsPage (build/axis-score) and import-preflight rule
links. Blocking schema-rule reference URLs now point at the site
(https://apiome.github.io/apiome/build/lint-rules#<rule>).
app.docs_site builds those paths, the site URLs and the pages' front matter.scripts/generate_lint_rule_docs.py, generate_supported_formats_doc.py and
generate_format_counts.py write into apiome-docs/docs/**; generated pages open with front
matter and mark rule / format anchors as heading ids (### rule.id {#rule-id}).info.version 1.204.0 (description text only).Agent toolset description enrichment (#4531, AGX-1.3): flags tools an agent will struggle with, and lets the copilot propose better descriptions that a person reviews before any agent sees them.
curl -sX POST "$APIOME/v1/tenants/acme/agent-toolsets/$TOOLSET/enrichment" -H "Authorization: Bearer $JWT"
curl -sX PATCH "$APIOME/v1/tenants/acme/agent-toolsets/$TOOLSET/enrichment/$PROPOSAL" \
-H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"decision": "accept"}'
curl -s "$APIOME/v1/tenants/acme/agent-toolsets/$TOOLSET/compiled" -H "Authorization: Bearer $JWT"
missing-description,
thin-description, missing-examples, undocumented-errors,
missing-parameter-description, thin-parameter-description. They feed AGX-4.4.APIOME_AGENT_ENRICHMENT_MODEL; unset means
flag-only), written only from the spec's own documentation. The pass is idempotent and asks
about at most 20 operations per run.accept (optionally edited) or reject. Only accepted text is compiled, and
only while the toolset's new descriptionEnrichment setting is on (the default). V273 adds
agent_toolset_enrichments; its CHECK makes accepted text without a review unrepresentable.GET …/compiled returns the toolset as agents are served it.agent.toolset.enrichment.run / agent.toolset.enrichment.review (metadata only).app.ollama_chat: the stdlib Ollama chat client for REST-side copilot features.docs/agent_toolset_enrichment.md.Agent toolsets: tool selection & curation (#4530, AGX-1.2): a tenant decides which operations of a published version its AI agents may call as MCP tools. Safe by default: reads on, write operations opt-in, each with an explicit confirmation.
curl -sX POST "$APIOME/v1/tenants/acme/agent-toolsets" \
-H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
-d '{"versionId": "'"$VERSION"'"}'
curl -sX PATCH "$APIOME/v1/tenants/acme/agent-toolsets/$TOOLSET/tools/$TOOL" \
-H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
-d '{"enabled": true, "confirmWriteOp": true}'
agent_toolsets: one per published version, with enabled and
target (prod | mock, consumed by AGX-2.4). agent_toolset_tools: one row per callable
operation, holding the canonical operation key, the AGX-1.1 compiled tool name, write_op,
enabled, and who confirmed an enabled write op and when.GET/HEAD operations and GraphQL queries
(deprecated ones excepted). Every other operation is a write op and starts disabled. Enabling
one without confirmWriteOp: true is a 422 agent-toolset-write-op-unconfirmed, and a
database CHECK makes an enabled but unconfirmed write op unrepresentable./v1/tenants/{t}/agent-toolsets: list (?versionId), create, get
(with tools), PATCH (enabled / target), DELETE, GET …/{id}/tools, and
PATCH …/{id}/tools/{toolId}. Guarded by the existing api_keys permissions; no new RBAC
resource.agent.toolset.create, agent.toolset.update (before/after),
agent.toolset.delete and agent.toolset.tool.update (operation, write-op flag, enabled
before/after, confirmation time), with metadata only.docs/agent_toolsets.md.toolset_id columns a (tenant_id, toolset_id) foreign
key to agent_toolsets with ON DELETE CASCADE. Deleting a toolset now deletes its upstream
credentials and agent keys. POST /agent-keys and the upstream-credential list/create routes
answer 404 agent-toolset-not-found for a toolset that is not in the caller's tenant.toolset_enabled_tools), instead of failing closed on every request.Agent keys (#4537, AGX-3.1): a new kind of API key for AI agents. Each one is bound to one agent toolset, limited to an explicit tool allowlist, and can expire. It is the credential an agent presents to the MCP agent runtime, and the identity that quotas (AGX-3.2) and usage analytics (AGX-3.3 / 3.4) will attach to.
curl -sX POST "$APIOME/v1/tenants/acme/agent-keys" \
-H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
-d '{"name": "claude-desktop", "toolsetId": "'"$TOOLSET"'",
"toolAllowlist": ["listPets", "getPetById"], "expiresAt": "2026-12-31T00:00:00Z"}'
api_keys extended (V269). kind (workspace | agent; existing rows are
workspace), toolset_id and tool_allowlist (a JSON array of AGX-1.1 tool names, at most
1024, no wildcard). expires_at is reused. CHECKs keep the two kinds exclusive and pin agent
keys to the scope agent:invoke./v1/tenants/{t}/agent-keys: list (?toolsetId, ?includeRevoked),
create, get, PUT …/{id}/allowlist, and DELETE …/{id} (revoke, idempotent). Guarded by the
existing api_keys view / create / edit / delete permissions; no new RBAC resource.ak_ + 64 hex characters, returned only by create. Rows
store a bcrypt hash and the usual lookup prefix; no response carries the hash.agent.key.create, agent.key.allowlist_update (the list before and after) and
agent.key.revoke go to the access audit, with metadata only.apiome_mcp.agent_access.AgentAccessMiddleware narrows
tools/list and tools/call to the toolset's enabled tools ∩ the allowlist. A revoke,
expiry or allowlist edit applies to the agent's next request. Until AGX-1.2 (#4530) supplies
toolset curation, it fails closed.toolset_id has no foreign key yet (agent_toolsets is AGX-1.2). Docs:
docs/agent_keys.md.validate_api_key now selects
kind = 'workspace' keys only, and falls back to the older queries on a pre-V269 database.
Separately, no REST scope-allowlist entry accepts agent:invoke, so an agent key would get a
403 on every route even if the kind filter were bypassed.Upstream auth vault (#4534, AGX-2.2) — agents must never hold real API credentials. A tenant now stores the upstream credential a managed MCP toolset presents to its real API, and the AGX-2.1 invocation proxy injects it server-side; the agent only ever holds its Apiome key.
curl -sX POST "$APIOME/v1/tenants/acme/agent-toolsets/$TOOLSET/upstream-credentials" \
-H "X-API-Key: $APIOME_KEY" -H 'Content-Type: application/json' \
-d '{"serverUrl": "https://api.example.com/v1", "kind": "apiKey",
"in": "header", "name": "X-Api-Key", "secret": {"value": "sk_live_…"}}'
apiome.upstream_credentials (V268) holds ciphertext only, sealed by
the shared envelope cipher under its own key map (APIOME_UPSTREAM_CREDENTIAL_ENCRYPTION_KEYS)
and vault magic. No key configured ⇒ storing is a 503 and nothing is written in the clear.GET lists metadata (binding, kind, placement, key version, whether it still
opens, created / rotated / last-used); create, rotate (POST …/{id}/rotate) and delete accept
a secret and never return one. A test sweeps every GET route in the app for any rendering of
a stored secret or its ciphertext. The router's 422s no longer echo a submitted body
(app.redacted_validation_route).https:// origin plus base path, stored normalized;
a secret is only opened for a request with the same scheme, host and port whose path sits
under the base path — never for a look-alike host, a downgrade, userinfo or an encoded
traversal. Kinds: apiKey (header or query, configurable name), bearer, basic.UPDATE; concurrent resolves see the old secret or
the new one, never neither, and in-flight invocations keep the secret they opened.upstream_credential_uses ledger (which
credential, which toolset, when, injected / unavailable); create / rotate / delete land in
the access audit as agent.upstream_credential.*. A bound credential that won't open fails
the call closed.api_keys permission (view / create / edit / delete); no new RBAC
resource. toolset_id gains its foreign key in AGX-1.2 (#4530). See
docs/upstream_credential_vault.md.API change check suite (#4740, GNC-3.1) — a pull request that changed an API used to collect
a wall of checks (lint, diff, breaking-change gate, contract test, SDK build), each with its own
log, and a reviewer who read none of them. The platform already knew every answer; the suite
turns them into one verdict — pending, pass, fail or skipped — recorded as an
evaluation, reported on the pull request as the apiome/api-change check (replacing the pending
check GNC-2.2's webhook seeded), and optionally required before publish.
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/versions/2.0.0/check-suite" \
-H "X-API-Key: $APIOME_KEY" -H 'Content-Type: application/json' \
-d "{\"commit_sha\": \"$GITHUB_SHA\", \"pr_number\": 42}"
lint (the stored-first lint report;
error-severity violations fail it, as they fail publish), breaking and consumers (the CTG
classification against the previous published revision and CTG-4.2's per-consumer verdicts for
that same diff), contract (the newest ECA contract run of this revision, counted only while
recompiling its own reference still yields the digest it executed) and sdk (the SDK kit
manifest built from the draft). The three CTG-4.5 components are judged by the deploy gate's
own evaluators and thresholds, so the pull request and the deploy gate cannot disagree.required, advisory
or off; the required ones reduce with GNC-2.2's precedence (a failure fails, an unfinished
component holds, a set of skips is a skip). Missing evidence holds a required component
pending and skips an advisory one; unreadable evidence is pending, never green; a version
with no captured source skips contract and sdk rather than waiting forever.skipped (spec-unchanged) when it does
not touch the bound specification, otherwise pending (draft-not-synchronized).200 replay of
the same evaluation with the same evidence ids, and the provider is not called again.GET …/check-suite/runs/{id} names every component's evidence (ids,
digests, counts), a link to it, and the rule behind it, plus snapshots of both policies. The
pull-request summary is the same thing as markdown. Consumer names are redacted for readers
without consumer_contracts:view.requiredForPublish on the suite policy refuses (422,
apiCheckSuiteGate) a version whose current content has no passing evaluation under the
component requirements and thresholds in force; force-publish stays the escape, and every
judged publish is audited as version.api_check_suite_gate.POST/GET …/projects/{project}/versions/{version}/check-suite, GET …/runs,
GET …/projects/{project}/check-suite/runs/{run_id}, and GET/PUT/DELETE of
…/governance/check-suite-policy and …/projects/{project}/check-suite-policy (tenant
administrators only for changes). The latest-evaluation read is allowlisted for diff:read /
lint:read CI keys. CLI: apiome checks run|show.apiome.api_check_suite_policy (one row per scope, mutable — every
evaluation snapshots the policy it was judged under) and apiome.api_check_suite_runs
(append-only except the ON DELETE SET NULL of its author; a placeholder can never pass or
fail), plus an index on ECA-1.3 runs by source->>'revision_id'.(check_run_id, request_fingerprint), so a verdict's failed attempt took
the slot its successful retry needed: the retry reached the provider, collided in the ledger,
and never wrote the provider's check-run id back — so every later publish POSTed a new check
run onto the pull request. V267 re-keys the ledger per outcome and the lookup reads a verdict's
dispatch first; a verdict is still dispatched at most once.Three-way spec synchronization (#4739, GNC-2.3) — a bound draft has three descriptions of the same API — the repository at the commit it is synchronized with (the base), the repository at the commit its branch has moved to (Git), and the version as this platform has it (the draft) — and they drift apart independently. Copying either repository side over the draft destroys whatever somebody was editing and invalidates whatever reviewers already decided. A semantic three-way merge now measures both sides against the base, applies the incoming changes that touch nothing the draft touched, and hands back every overlap as an explicit conflict.
# The branch moved. What would land, and what collides?
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/versions/2.0.0/binding/sync" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'
# Decide one collision. `git` takes the repository's value; `draft` keeps the version's.
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/sync-plans/$PLAN/conflicts/$CONFLICT" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"resolution":"git","note":"the rename was agreed in review"}'
versions, or to a review — not in the store, not in the accessors, and not
in the schema. Computing a merge writes one row; settling a conflict records which side a person
chose. Both leave the draft exactly where it was, which is what makes it safe for a webhook to
raise a candidate and for anyone at all to merge it.apiome.draft_sync_plans (one merge per binding and trio of documents,
recording the base, Git and draft digests it was computed from, what merged and how much did
not, with the identity frozen by a trigger and a CHECK that keeps the status and the two counts
from disagreeing) and apiome.draft_sync_conflicts (one row per overlap, carrying all three
values with the repository file and line it lives at, settled once towards git or draft).app.spec_sync (vocabulary, models, the merge engine, the plan fingerprint and the
YAML/JSON line locator — all pure), app.spec_sync_store (the rules), app.spec_sync_routes
(four endpoints), and the accessors at the end of database.py, whose sync.planned /
sync.conflict_resolved audit rows are written inside each write's transaction.document/path/operation/component/schema grouping every other change list in the
product uses, what each side did to the base, all three values, and the repository file, 1-based
line and link at the commit. Lines come from composing the incoming document rather than
loading it, and a mapping entry reports its key's line — in block YAML the value of summary:
starts on the next line, which is not where anybody would look. A value too large to send to a
browser is replaced by its size, and a merge that collides in more places than one result holds
says so on the row — a result that quietly dropped findings would read as less conflicted than
it is.403 binding-repository-forbidden rather than merged from a guess. And the base is re-read and
re-hashed first: if it no longer matches the digest the binding recorded, history was rewritten
underneath the merge base and the request refuses with sync-base-drifted instead of guessing
which side changed what.stale.guard — none,
review_decided (an open review's current round already holds a decision) or
version_published. A guard never refuses the merge: knowing exactly what would collide is
precisely what such a reader needs.apiome-rest/docs/spec_sync.md. This ticket deliberately writes nothing back to
Git and applies nothing to a draft; the merged document is computed and proven
deterministic, but turning it into an edit is a separate, explicit act with no storage here.Provider webhook and status adapter (#4738, GNC-2.2) — GNC-2.1 gave a draft a durable relationship to a repository ref, but nothing could answer the provider: a pull request that changed an API showed no verdict from this platform, because there was nowhere to record one and nothing to send it with. Both halves now exist — a normalized check model that belongs to the platform rather than to any provider, and one status adapter interface with GitHub, GitLab and Bitbucket behind it.
# Record a verdict about the commit this draft is bound to, and put it on the pull request.
# (binding, commit, name) identifies the check, so the same call twice is one verdict.
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/versions/2.0.0/binding/checks" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"apiome/api-change","state":"fail","title":"2 breaking changes",
"summary":"`GET /pets` lost a required field.","details_url":"https://…"}'
# What did the provider actually do with it?
curl -s "$APIOME/v1/tenants/acme/projects/pets/checks/$CHECK_ID" \
-H "Authorization: Bearer $TOKEN"
pending / pass / fail / skipped. The three
providers disagree about what a status even is — GitHub splits it into status and
conclusion, GitLab has one commit state, Bitbucket has build states in capitals and no
skipped at all — so storing any one of them would make the other two lossy translations.
Only pass ever maps to a provider's passing status: a skip is "we did not look", which is not
"we looked and it is fine".apiome.provider_check_runs (one verdict per binding, commit and check
name, backed by a unique index — the re-run idempotency — with completed_at tied to the state
by a CHECK and the identity frozen by a trigger) and apiome.provider_check_deliveries (an
append-only publish ledger, one row per distinct verdict sent, which may not claim a reach it
did not have).app.provider_checks (vocabulary, models, codes, the provider spelling tables and
the fingerprint — all pure), app.provider_status_adapter (one StatusAdapter contract;
GitHub check runs, GitLab commit statuses, Bitbucket build statuses), app.provider_check_store
(the rules), app.provider_check_routes (four endpoints), and the accessors at the end of
database.py, whose check.recorded / check.published audit rows are written inside each
write's transaction.failed row to the publish ledger and the verdict
stands. A check recorded and not published is evidence; a check published and not recorded is a
green tick with nothing behind it.pending check beside GNC-2.1's sync candidate, through the existing
REPO-4.3 endpoint and deliberately outside its tracked-branch gate. Authorized means the binding
is active and its repository registration still exists — that registration is the credential a
verdict is published with. Both halves are best-effort: neither can turn a verified delivery
into a 500 the provider would retry forever. The acceptance audit carries checksSeeded.APIOME_PROVIDER_CHECKS_ENABLED (publish kill switch — recording is never
gated), APIOME_PROVIDER_CHECKS_WEBHOOK_SEED, APIOME_PROVIDER_CHECKS_DETAILS_BASE_URL.apiome-rest/docs/provider_checks.md. This ticket produces no verdicts — it
carries them; the check suite that decides one is GNC-3.1. Making a check required stays a
provider-side branch protection setting, which is the repository owner's to make.Branch-to-draft binding (#4737, GNC-2.1) — repository import creates a snapshot; it does not create a durable review unit. A binding now pins one draft version to one provider, repository, ref and source path, together with the digest of the source it is synchronized with, and every observed movement of that ref becomes an explicit, auditable sync candidate instead of quietly rewriting the draft.
# Bind a draft to a branch. The ref is resolved and the selection read through a STORED
# credential first: that read is the authorization check, and it produces the commit and digest.
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/versions/2.0.0/binding" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"repository_id":"…","ref":"main","path":"spec/openapi.yaml"}'
# Has the branch moved? A moved ref records a candidate; nothing about the draft changes.
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/versions/2.0.0/binding/check" \
-H "Authorization: Bearer $TOKEN"
# Decide: `applied` re-reads the source at that commit and advances the binding's base;
# `dismissed` leaves it exactly where it is. A candidate settles once.
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/versions/2.0.0/binding/candidates/$ID" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"status":"dismissed","note":"not ours to take"}'
apiome.draft_repository_bindings (one active binding per draft, backed by
a partial unique index; released rows kept as history and frozen by a trigger) and
apiome.draft_binding_sync_candidates (idempotent per target commit and per provider
delivery, settling exactly once). What a binding names never changes — only the synchronized
pair (commit_sha, source_digest) moves, and only while it is active.app.draft_bindings (vocabulary, models, codes, the digest — all pure),
app.draft_binding_store (the rules), app.draft_binding_routes (seven endpoints), and the
accessors at the end of database.py, whose binding.* audit rows are written inside each
write's transaction.repository_removed.Database._insert_review_audit was generalized to _insert_workflow_audit_tx; COL-2.1's five
call sites are unchanged in behaviour.apiome-rest/docs/draft_bindings.md. Writing back to the provider (check runs, PR
status) is GNC-2.2; merging repository changes into a draft is GNC-2.3, which will settle the
same candidates once it can reconcile without silent overwrite.Notification model & fan-out (#4521, COL-3.1) — the collaboration roadmap stops depending on people polling pages. Every mention, review request, decision, thread resolution and publish now writes one inbox row per person it concerns, in the same transaction as the event itself, and three endpoints read that inbox.
# The bell badge
curl -s "$APIOME/v1/tenants/acme/notifications/unread-count" -H "Authorization: Bearer $TOKEN"
# {"total":3,"by_type":{"mention":2,"review_requested":1,"review_decision":0,…}}
# The list behind the notification centre
curl -s "$APIOME/v1/tenants/acme/notifications?unread=true&limit=20" -H "Authorization: Bearer $TOKEN"
# Clearing it
curl -sX POST "$APIOME/v1/tenants/acme/notifications/read" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"all": true}'
notifications — recipient, tenant, type, payload jsonb,
read_at, plus the actor and the project/version the row points at, so a deleted destination
takes its dead links with it while "somebody mentioned you" survives that somebody leaving.mention (an edit notifies only the members it newly names),
review_requested (every round's reviewers), review_decision (the member who asked for the
review), thread_resolved (everyone who took part), version_published (the version's
collaborators — its review and thread participants). Nobody is ever notified of their own
action, and a recipient set is bounded at 200.notify callable and runs it inside its
own transaction, so a committed event always has its rows and a refused one leaves none. The
insert joins users, so a recipient deleted mid-flight is skipped rather than rolling the
event back.GET /v1/tenants/{tenantSlug}/notifications (filters unread, type, paged),
GET …/notifications/unread-count (total and per type, zeroes included), and
POST …/notifications/read (ids or all, idempotent, answering with the new count). All
three need only authentication — an inbox is the caller's own, which no resource:action can
express — and listing never marks anything read.docs/notifications.md. Per-type delivery preferences are not stored yet;
COL-3.2 needs them and should filter on read, not at write time.Approval policy & publish gate (#4519, COL-2.3) — review outcomes become binding at publish time. A tenant can require n approvals (optionally from a named role) before a draft version may be published; publishing without them is refused, and the force-publish escape is audited.
# Arm the gate on the governing style guide
curl -sX PUT "$APIOME/v1/style-guides/acme/$GUIDE_ID/policy" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"requiredApprovals": 2, "requiredReviewerRole": "release-manager"}'
# A publish that has not collected them is refused with 422 + the verdict
curl -sX POST "$APIOME/v1/versions/acme/pets/$REVISION/publish" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"shortMessage": "Ship it"}'
style_guides.required_approvals (0 = off, the default,
capped at the 20-reviewer limit) and style_guides.required_reviewer_role (a roles.slug,
nullable). Both resolve through the GOV-1.4 guide chain — project assignment → tenant
assignment → tenant default — beside the CTG-3.4 breaking-publish level, and both are frozen
into each style_guide_revisions snapshot. Read/written at
GET/PUT /v1/style-guides/{tenantSlug}/{guideId}/policy, where requiredReviewerRole is
the one field for which omitted (leave alone) and null (clear) differ.reason for no-review, changes-requested, spec-changed (the content moved
since the round was requested, so its approvals are stale — COL-2.1's spec_changed),
insufficient-approvals, and missing-required-role. A reviewer's role is their effective
RBAC slug, so a tenant administrator resolves to owner.{"detail": {"message": …, "approvalGate": {…}}}, the same shape the
breaking-publish guardrail and the verification policy use. Force-publishing
(skipPublishChecks + forcePublishReason) gets past it, exactly as it does for them.version.approval_policy_gate
workflow_audit row with action of satisfied, forced, or unavailable — passing
verdicts included, so the trail can answer "who signed off on this release?".unavailable and never block a publish; the degradation is audited rather
than silent.docs/approval_publish_gate.md; 46 tests in
tests/test_approval_publish_gate.py.Comment anchor resilience (#4516, COL-1.4) — a comment thread no longer silently disappears when its element is deleted, and renames and moves are proven to keep it in place.
# Threads whose element was deleted, with the element's last-known label
curl -s "$APIOME/v1/tenants/acme/projects/pets/comment-threads?version=1.0.0&status=orphaned" \
-H "Authorization: Bearer $TOKEN"
# Re-attach one to another element of the same version
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/comment-threads/<thread id>/relink" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"anchor_type": "property", "anchor_id": "<class property id>"}'
status gains orphaned, with anchor_label (the element's
name when it was deleted — Customer, Customer.email, /customers/{id}, GET /customers/{id})
and orphaned_at. Database triggers orphan threads on every delete path: the class, property,
path, and operation DELETE routes, a whole-version source-change rewrite, and foreign-key cascades
(a class takes its properties' threads, a path its operations'). A resolved thread keeps its
resolution while orphaned.POST …/comment-threads/{thread_id}/relink {anchor_type, anchor_id} re-attaches an
orphaned thread to an element of its own version (or to the version). It comes back resolved
if it was, open otherwise. 404 comment-anchor-not-found for a target outside the version,
409 comment-thread-not-orphaned for a thread that is not orphaned. Requires projects:view.409 comment-thread-orphaned. Replies still work.docs/comments.md.Comment threads (#4513, COL-1.1) — discussion now lives next to the specification instead of in Slack screenshots. Open a thread on a class, property, path, operation, or a whole version; reply in Markdown; mention teammates; resolve and reopen.
# Ask about a class on version 1.0.0 and mention a teammate
curl -sX POST "$APIOME/v1/tenants/acme/projects/pets/comment-threads" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"version": "1.0.0", "anchor_type": "class", "anchor_id": "<class id>", "body": "Nullable, @bob.brown?"}'
# Everything open on that version that mentions me
curl -s "$APIOME/v1/tenants/acme/projects/pets/comment-threads?version=1.0.0&status=open&mentions_me=true" \
-H "Authorization: Bearer $TOKEN"
comment_threads (tenant, project, version, anchor_type +
anchor_id, status, resolution stamps, last_activity_at) and comments (thread_id,
author_id, Markdown body, mentions uuid[], edited_at). A thread is anchored by the
element's primary key, never canvas coordinates, and the element must exist in the named
version when the thread is opened.…/projects/{project_ref}/comment-threads: list (filters version, status,
anchor_type, anchor_id, mentions_me; paged with a total; each row carries its opening
comment), open, read, delete, resolve, reopen, and …/comments to reply, edit, and delete.
Deleting a thread's last comment deletes the thread.projects:view is enough to read, comment, resolve, and
reopen. Editing or deleting a comment is limited to its author or a tenant administrator, and
deleting a thread to whoever opened it or a tenant administrator (403 comment-forbidden).APIOME_COMMENT_CREATE_RATE_LIMIT_PER_MINUTE (default 30); over it returns
429 comment-rate-limited. Documented in docs/comments.md.Auto-regen on publish (#4497, SDK-4.3) — watch mode for SDKs. Subscribe a project's SDK once, and every published version regenerates it and ships it: an SDK-4.1 registry publish, an SDK-4.2 pull request, or both. Nobody has to remember.
# Every publish of widgets: publish the npm SDK, then open a PR carrying that same version
curl -sX PUT "$APIOME/v1/projects/acme/widgets/sdk-regen-subscriptions/npm" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"deliveryMode": "registry_and_git"}'
# What each publish did — and the dead letter
curl -s "$APIOME/v1/projects/acme/widgets/sdk-regen-runs?status=dead_letter" -H "Authorization: Bearer $TOKEN"
sdk_regen_subscriptions) — one per project per ecosystem,
with a deliveryMode of registry, git or registry_and_git, options and active.
deliveryMode has no default, because publishing to a public registry is irreversible.
options is a closed vocabulary: dryRun (registry modes only, default false) rehearses every
release, and an unknown option is refused, so a misspelt one can never silently publish. Listing
is projects:view. Subscribing or re-enabling needs projects:edit and versions:publish,
because a subscription publishes on the tenant's behalf on every later publish. Disabling or
unsubscribing needs only projects:edit.sdk_regen_runs) and one pending job per active
subscription (sdk_regen_jobs) in one statement, as a background task that never fails the
publish. A project with no active subscription gains no rows.app.sdk_regen_worker, ticking every APIOME_SDK_REGEN_INTERVAL) calls SDK-4.1's
publish() and SDK-4.2's deliver() unchanged, so an automatic release and a manual one are
identical. In registry_and_git mode the pull request is pinned to the version the publish just
claimed. Jobs are claimed with FOR UPDATE SKIP LOCKED, so replicas share the queue. A
subscription's publishes run in order, and one subscription's failure never blocks another's.sdk.regen.dead_lettered push-webhook event and is
retried with POST …/sdk-regen-jobs/{jobId}/retry (versions:publish). A step that succeeded
is never repeated: a retry after a publish only delivers, and the registry result is written
to the job before the git step starts, so this holds even if the worker dies. A job still running
past APIOME_SDK_REGEN_LEASE_SECONDS is dead-lettered (sdk-regen-worker-lost), never retried
automatically, since it may already have published. A fresh claim token per attempt stops a stale
worker from overwriting a job that was retried since.cancelled, and a removed subscription's dead letters can no longer be
retried. Runs, jobs, packages and pull requests already produced are kept (ON DELETE SET NULL).PublishOutcome.retryable (SDK-4.1, in-process only) now carries the registry's own
RegistryUploadError.retryable, mirroring SDK-4.2's DeliveryOutcome.retryable.APIOME_SDK_REGEN_ENABLED (kill switch), APIOME_SDK_REGEN_INTERVAL,
APIOME_SDK_REGEN_BATCH_SIZE, APIOME_SDK_REGEN_LEASE_SECONDS. No new RBAC resource and no new
credential. Documented in docs/sdk_regen_on_publish.md.Git delivery, PR mode (#4496, SDK-4.2) — registry publishing serves an SDK's consumers; git delivery serves its owners. A regenerated SDK now arrives as a pull request against the tenant's own repository, where their normal review and CI apply.
# Point the project's npm SDK at a repository already registered with Apiome
curl -sX PUT "$APIOME/v1/projects/acme/widgets/sdk-git-delivery-targets/npm" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"repositoryId": "5f0c…", "baseBranch": "main", "targetPath": "sdks/typescript"}'
# Deliver version 1.4.2 — opens (or updates) apiome/sdk-regen-1.4.2-widgets-npm
curl -sX POST "$APIOME/v1/projects/acme/widgets/sdk-git-delivery" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"ecosystem": "npm", "version": "1.4.2"}'
sdk_git_delivery_targets: one
per project per ecosystem — repository, base branch, target path) names a repository registered
through a linked GitHub account, and a delivery pushes with that repository's existing
linked-account token. There is no token column in V257. A repository registered from a public
URL, or hosted outside GitHub, is refused with the reason.app.sdk_publish_pipeline now exposes resolve_release_branding,
resolve_release_series and build_release_distribution), carrying the version the next
registry publish of the series would claim, and commits it under the target path through
GitHub's Git Database API — no clone, no git binary, no token on disk.Apiome-Revision / Apiome-Version-Line / Apiome-Package / Apiome-Generator trailers.apiome/sdk-regen-<version>-<project>-<ecosystem> — the ticket's apiome/sdk-regen-<version>
plus the project and ecosystem, so several SDKs can share a repository without overwriting each
other's pull requests. Every delivery is rebuilt on the latest base branch and force-updates the
branch; re-running updates the open pull request (updated), writes nothing when it already
carries this SDK (unchanged) or when the base already contains it (up_to_date), and only
opens one when none is open (opened)..apiome/sdk-delivery.json manifest beside the SDK
lists what Apiome generated; the next delivery removes files that list named and the new one
does not, and never touches anything else under the target path.sdk_git_delivery_runs; a missing or revoked credential, a read-only token, a rejected push, a
refused pull request or a package that cannot be built is a failed run with a stable
errorCode, a message naming the fix, and a step log redacted of the repository token.
POST …/sdk-git-delivery answers 200 with the run either way.app.sdk_run_log.RunLog (with a
per-pipeline redaction marker) so both release pipelines redact through one implementation.projects:view; saving one is projects:edit and imports:edit (a
target decides what Apiome pushes into a repository with that repository's credential);
delivering is versions:publish; history is versions:view. No new RBAC resource. Documented
in docs/sdk_git_delivery.md.Package publishing pipelines (#4495, SDK-4.1) — downloading a zip is not how SDKs are
consumed at scale, so a published version can now be released as a package a consumer installs:
npm install @acme/widgets-sdk, pip install acme-widgets.
# Store the workspace's token once (write-only; never returned by any route)
curl -sX PUT "$APIOME/v1/tenants/acme/governance/sdk-registry-credentials/npm" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"token": "npm_..."}'
# Validate a release without publishing anything (the default)
curl -sX POST "$APIOME/v1/projects/acme/widgets/sdk-publish" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"ecosystem": "npm", "version": "1.4.2"}'
sdk_registry_credentials as ciphertext only, sealed with AES-256-GCM envelope encryption
under APIOME_SDK_REGISTRY_CREDENTIAL_ENCRYPTION_KEYS. The scheme MCAT-6.2 already used was
extracted to app.envelope_crypto rather than copied, and the SDK vault seals under its own
magic so a blob cannot be moved between the two even on a shared key. A credential is
write-only — every read returns the ecosystem, the registry, the token's public scheme
prefix, its length and a truncated digest, and no route returns a token. A project credential
replaces the workspace one whole (unlike SDK-3.4's settings, a token is atomic), and both
scopes are managed at …/sdk-registry-credentials.POST /v1/projects/{t}/{project}/sdk-publish defaults to
dryRun: true: it resolves the branding, resolves and decrypts the credential, computes the
version the next real publish would claim, builds the exact archive that publish would upload
and reports its SHA-256 — and uploads nothing. Because the build is byte-deterministic, the
digest a dry run reports is the digest a publish uploads. Sending dryRun: false is the
deliberate act; a default that published would make a mis-typed request a public release.major.minor.<counter>, where major.minor come from the revision's version line and the
counter is how many releases that line's release series has already had: 1.4 → 1.4.0,
1.4.1, 1.4.2…; v3 → 3.0.0; 2026-01-04 → 2026.1.0. The counter is allocated per
series rather than per line, so 1.4.2 and 1.4.3 cannot both claim 1.4.0. A prerelease
line stays a prerelease (npm 1.5.0-beta.2, PyPI 1.5.0b2), and a line with no leading
number (latest, draft) is refused rather than given an invented ordering. The counter is
derived from the run ledger, never stored on a project row, and a partial unique index
makes that safe under concurrency — a run is inserted in_progress holding its version before
the upload, and a publish that loses the race takes the next number.package.json carries an apiome object and
PyPI's core metadata carries Project-URL entries naming the revision id (not merely the
label — a label can be re-published, a revision cannot), the version line, the release series,
the regen counter, the renderer and the SDK-3.4 settings fingerprint. An installed package
therefore traces back to its spec with nothing but the package manager.gomod is deliberately not
publishable — it names a module path, and a Go module is released by pushing a tag (SDK-4.2).GET …/sdk-publish-runs[/{run_id}] lists every attempt, dry runs included, with
the version it claimed, the digest it uploaded and its redacted event log.projects:view / projects:edit; publishing — including a dry run —
is versions:publish. No new RBAC resource, for the reason CTG-4.4, CTG-4.5 and SDK-3.4 all
gave. Documented in docs/sdk_package_publishing.md.Go client generator (#4488, SDK-2.4) — Go was the most-requested third language for infra
buyers, and the client kit now carries one: a complete, dependency-free Go module generated
from the published contract, sitting in the kit's go/ directory beside the snippets.
curl -sO -J "$APIOME/v1/browse/tenants/$TENANT/projects/$PROJECT/versions/1.0.0/sdk/download"
unzip -q petstore-1.0.0-sdk.zip && cd go && go build ./... && go vet ./...
go.mod (standard library only — a generated SDK that pulls in a
dependency tree is a liability), a net/http transport behind an injectable Doer with
WithHTTPClient / WithBaseURL / WithUserAgent / WithHeader / WithRequestEditor,
exported types for every schema the contract declares, one context.Context-first method per
HTTP operation, auth options derived from the model's security schemes, a typed error per
declared error response, a README.md, and a runnable examples/<group>/main.go per operation
group. The tenant's SDK-3.4 licence header is commented onto every .go file and its
user-agent is baked in as DefaultUserAgent.app.go_client_generator is a pure function of the persisted canonical model and its output
rides the existing client kit rather than an artifact store — so the download stays
byte-deterministic and keeps its content-addressed ETag.gomod, a third SDK-3.4 package ecosystem. A tenant configures the go.mod module path
their consumers go get, with the same tenant → project merge and {tenant}/{project}
tokens as the npm and PyPI patterns. Unconfigured, it falls back to
example.com/<tenant>/<project>-go — example.com is IANA-reserved, so a default module path
can never point at somebody's real repository.go_client block (module path, package name, Go version, method and
type counts, auth options, example groups, per-method coordinates and skips), and the public
SDK info route gained a go_client object so the browse panel can name the module without
paying to generate it.tests/test_go_client_generator.py runs go build ./...,
go vet ./..., gofmt -l and a go test that drives the generated client against a live
httptest server — path, query, cookie, auth header, user-agent, JSON decoding and the typed
404 over an actual HTTP round trip — whenever a Go toolchain is on PATH, and skips otherwise.app.canonical_security (#4488). The canonical model has no
first-class security field, so importers record auth in two extras shapes that mean different
things: operation.extras["security"] is a per-operation requirement, while
api.extras["inferred_auth_schemes"] is only an observation that the API was seen using a
scheme. Three emitters now need that distinction, so AUTH_SCHEME_HEADERS and both readers live
in one module; app.http_file_emitter and app.llm_tools_emitter delegate to it. Behaviour is
unchanged.app.snippet_render helpers became public — upper_snake_token, request_message and
pick_content_type — so the Go generator asks the same questions the snippets do rather than
keeping a second copy of the answers. license_comment_block learned the go comment prefix.Public "Get SDK" surface (#4493, SDK-3.3) — the browse portal is where API consumers land, and until now a published spec page offered them no path to a working client. It now offers two, both behind one per-project switch that is off by default.
# Opt a project in, then take the kit.
curl -sX PUT -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
"$APIOME/v1/projects/$TENANT/$PROJECT/sdk-settings" \
-d '{"settings":{"publicSdkEnabled":true}}' > /dev/null
curl -sO -J "$APIOME/v1/browse/tenants/$TENANT/projects/$PROJECT/versions/1.0.0/sdk/download"
GET /v1/browse/tenants/{t}/projects/{p}/versions/{v}/sdk describes what is on offer (the
resolved package names and their install commands, the languages, the operation counts, the
settings fingerprint), and …/sdk/download serves the archive itself as application/zip.
Both share the MFX-7.3 public-export rate limit; the download reuses its size cap.sdk.client-kit.v1 archive built from what did ship — the SDK-2.3 renderer — carrying a
README, the published contract verbatim, and one runnable snippet per operation in
ts/python/curl. It is built per request, so there is no artifact lifecycle to retain or
expire.publicSdkEnabled, a new key on the SDK-3.4 sdk.generation-settings.v1 body. It merges
tenant → project key by key like every other setting, so a workspace can open every project at
once and one project can override either way. It is the only setting that is an access control
rather than branding, so it defaults to false rather than null — for a permission, "not
configured" and "not allowed" are the same answer — and an unreadable settings row also reads
as false: the gate fails closed. Only a real boolean is accepted; 1 is refused.403 would confirm that the project exists and merely declined.manifest.json records the version record id,
version label, source format, renderer, API version and merged settings fingerprint, and
digests every entry. Building twice from the same inputs yields byte-identical archives, which
is what lets an unstored download carry a strong content-addressed ETag (with If-None-Match
→ 304) and a Digest over its exact bytes.skipped list rather than failing the kit, and the work is capped at 250 renderable operations
with truncated reported.GET /v1/browse/tenants/{t}/projects/{p}/versions/{v}/snippets/{operation_id} is part of the
same consumer-facing SDK surface as the Get SDK download, so it now answers 404 for a project
whose publicSdkEnabled is not set. Since the setting defaults to off, public snippet URLs
that worked in 1.314.0 return 404 until a workspace or project owner opts in. The
authenticated snippet route is unchanged — it is tenant-scoped, not public exposure.publicSdkEnabled therefore changes the digest the same settings produce. Stored row
fingerprints are untouched until their row is next saved; the ones responses report changed
immediately.ExportSource now carries the revision's captured source_text and source_format, so a bundle
can ship the contract alongside what was derived from it. Additive; existing callers are
unaffected.app.export_job_engine to a shared
app.zip_bundle, so the export bundle and the client kit cannot drift apart on the pinned
timestamp their reproducibility depends on.SDK generation settings & branding (#4494, SDK-3.4) — an organisation wants the code Apiome hands its consumers to carry the organisation's identity: packages under its own npm scope / PyPI naming pattern, its licence header on the source, its own user-agent on the traffic those clients generate. None of that is a property of any version, project row or generated file, so it now has one durable home and one set of rules.
curl -sX PUT -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
"$APIOME/v1/tenants/$TENANT/governance/sdk-generation-settings" \
-d '{"settings":{"packageNamePatterns":{"npm":"@acme/{project}-sdk"},
"userAgent":"acme-sdk/{version}"}}' | jq -r .resolved.packageNames
GET|PUT|DELETE /v1/tenants/{t}/governance/sdk-generation-settings and
GET|PUT|DELETE /v1/projects/{t}/{project}/sdk-settings. A GET never materialises a row —
a scope with nothing saved answers source: "default" — and a DELETE returns the settings
now in force rather than a bare 204.packageNamePatterns merges one ecosystem at a
time. This is the one place SDK-3.4 departs from CTG-4.5's whole-body override, and the reason
a stored body carries only the keys its author named: an absent key inherits the next scope
up, an explicit null is deliberately none and blocks that inheritance.@acme/{project}-sdk is not itself a legal npm
name, so patterns are checked by substituting probe values and validating the result. At read
time a package pattern whose tokens the scope cannot fill is omitted rather than resolved
approximately — a package name is an exact identifier, and a nearly-right one is worse than
none. Tokens: {tenant}, {project}, {version}, {year}.*/),
and report both back in a new branding field alongside the resolved package names.
Rendering with no branding is byte-identical to before, which is what keeps FMT-2.4's bulk
request-file emitter — which shares synthesize_request and render_curl — unchanged.projects:view to read, projects:edit to change: no new RBAC resource and no new API-key
scope. Both writes are audited as governance.sdk_generation_settings.update / .clear,
with the licence header recorded by length rather than verbatim.sdk_generation_settings, two partial unique indexes, one JSONB
body). Docs: apiome-rest/docs/sdk_generation_settings.md.Deploy-gating status API (#4502, CTG-4.5) — a CD pipeline asks one question, can I promote this API version?, and the answer lived in five places: the GOV lint grade on the revision, CTG-3.1's breaking classification, CTG-4.2's per-consumer verdicts, CTG-4.3's conformance report and CTG-4.4's freshness. Every team that wanted a gate scripted its own multi-call version, and every one of them decided the combination rules differently.
curl -sH "X-API-Key: $KEY" "$APIOME/v1/projects/$TENANT/$PROJECT/gate" | jq -r .status
GET /v1/projects/{tenant_slug}/{project_ref}/gate returns pass / warn / fail plus a
per-signal breakdown, each signal carrying a stable reason code, a human sentence, a link to its
evidence, and the facts the judgment was made from. No analysis was added: every signal is a
read of something an earlier ticket already stored — the gate never re-lints (#5259's stored
reports) and never re-diffs (the stored ctg.changelog.v1 payload is rehydrated into the
classified diff CTG-4.2's consumer_impact_for_diff already takes, because a changelog entry and
a classified change carry the same fields).
Partial inputs are the normal case, so there are five per-signal statuses rather than three.
A signal with nothing behind it reports not_configured; one that exists but could not be read
reports unknown. Both are excluded from the verdict — the endpoint has to ship before all four
sources exist everywhere — and both are counted apart, because "nobody has registered a consumer",
"I could not read the registry" and "no consumer is broken" are three different facts.
evaluatedSignals is how a strict pipeline tells an empty gate from a real pass.
The status is always 200. A 409 on a failing build would make a network fault and a breaking
change look identical to a pipeline's error handling; the verdict is in the body and the caller
owns the exit code, exactly as the CLX-4.2 lint gate does.
Thresholds are two-rung and tenant- or project-scoped. Each signal carries a warn threshold
and a fail threshold, either of which may be null to disable that rung, which is what lets one
vocabulary come out of four very different measurements without a per-signal "action" dial:
warn below B, fail below D says the whole lint policy in five words. A rung that could never
fire is refused with a 422 listing every problem at once.
GET|PUT|DELETE /v1/tenants/{tenant}/governance/deploy-gate-policy and the per-project
…/gate/policy configure it, resolving project → tenant → documented default, with policy.source
on every response saying which one applied. Unlike the other policy surfaces these rows are
mutable rather than append-only — the gate stores no verdict, so there is no past judgment for a
version history to explain; attribution lives in access_audit.
Unlike every other policy default in the platform, this one has teeth: it fails on a breaking change and on a broken consumer, and warns on a lint grade below B or a verification older than a day. The advisory defaults elsewhere exist because those gates hang off flows that already existed and a blocking default would break people who never asked for one; nothing hangs off this one.
Every signal fails soft, on its own. A store that is unreachable or a payload this release
cannot parse costs that signal — unknown, reason signal-unavailable — and nothing else. A gate
that returned 500 because one of four inputs was briefly unavailable would stop every pipeline in
the tenant. The policy read degrades the same way, flagging policy.degraded so "nothing is
configured" stays distinguishable from "I could not read what is".
A schedule is matched to the gated revision however its reference was spelled (…/1.2.0,
…/<uuid>, …/latest); across several, freshness is the most recent clean run and the status is
the worst, so a failing staging check is never averaged away by a passing production one. When
nothing schedules the version, the signal falls back to a manual CTG-4.3 report, read by resolved
artifact coordinates — and a failing report never becomes the freshness anchor.
No new RBAC resource and no new API-key scope. Reading a gate is versions:view (what a CI
runner resolves to); moving the bar is verification_targets:edit, the same class of decision
V211 already keeps out of an Editor's hands. The consumer signal is gated inside the response on
consumer_contracts:view, reported unknown rather than leaked or silently passed. The gate is
allowlisted for either CTG-2.3 CI read scope (diff:read or lint:read), since it aggregates
inputs both of those already grant.
apiome-db V254 adds deploy_gate_policy (one row per scope, two partial unique indexes) plus
the artifact index the report fallback reads. See docs/deploy_gate.md.
Consumer-aware breaking analysis (#4480, CTG-4.2) — "breaking" is a claim about somebody.
A whole-spec verdict ("47 breaking changes") forces a provider to treat every change as an
incident and tells a consumer nothing. POST /v1/diff/{tenant}/classified with
consumers: true now intersects the CTG-1.1 classified changes with what each registered
consumer declared it uses (CTG-4.1) and answers the question that actually gates a release:
breaks 2 of 7 consumers: billing-service, mobile-app
Nothing was added to the database. A verdict is derived from a stored contract and a diff, and
both already existed; what was missing was the join. app.consumer_impact is pure (pointer
algebra, attribution rules, markdown), app.consumer_impact_service is the one place the
registry is read for an analysis, and CTG-4.5's deploy gate calls the same seam.
The exclusion is the point. A change inside a body schema, on an operation whose consumer
declared which fields it reads, attributes only when one of those fields is met — removing a
field nobody reads breaks nobody. Two exceptions keep that from under-reporting: an operation
declared with no fields is operation-wide throughout (nothing finer was declared, so nothing
finer is claimed), and a /parameters/… change is always operation-wide, because a newly
required query parameter breaks every caller whether or not they declared it. Root security,
servers and securitySchemes changes reach every declared consumer.
Pointer overlap is segment-aware, unlike the starts_with narrowing query behind
db.find_consumer_contracts_by_pointers: /components/schemas/Pet no longer "touches"
/components/schemas/PetFood. The SQL only narrows the candidate set; this renders the verdict.
The denominator is honest. A consumer registered without a current contract cannot be
counted as safe, so it is reported beside the fraction (2 registered consumers have declared no surface) with verdict undeclared, never inside it. Each verdict also carries
contractMatchesBase, so a surface resolved against a different revision is flagged rather
than silently equated.
Changes touching nobody stay globally classified and are flagged: each change gains a
consumers array ([] = no registered consumer affected, null = not analysed), and the
report's attribution list is exact even when a consumer's impacts enumeration is capped.
Markdown responses gain a Consumer impact section, and apiome diff --consumers prints
breaks billing-service lines in text, JSON and markdown. The CI exit code is unchanged —
--fail-on still grades the whole specification, so a build never passes merely because nobody
has registered as a consumer yet.
See apiome-rest/docs/consumer_impact.md.
Provider verification against a live deployment (#4489, CTG-4.3) — a published specification
can be perfectly versioned and still lie. POST /v1/tenants/{tenant}/contracts/{version_ref}/ verify-provider executes the version's compiled contract suite against a registered deployment
and returns a conformance report: per-operation verdicts, every schema violation located by
its JSON Pointer into the response body, and coverage measured against every operation the
specification declares.
Nothing here re-implements execution. ECA-1.1 compiles the requests, ECA-1.2 holds the target and its credential reference, ECA-2.1 sends them and validates responses, ECA-1.3 stores the run. What was missing was the judgment: coverage had no denominator (a run recorded the cases it executed, never the operations it did not reach), drift had no location (the validator's JSON Pointers were computed and then discarded), mutation was an all-or-nothing target flag, and there was no report object a deploy gate could fetch.
Safe by default. Only GET/HEAD/OPTIONS are sent. A mutating case runs only when the
target policy permits mutation, and the run opts in, and a tenant-supplied fixture names the
operation — because "you may write" and "here is the row you may write to" are different
permissions. A run can narrow what the registry permits and never widen it; a fixture supplies the
request but never the expectation, so it cannot make a failing case pass; a fixture carrying a
credential header is refused; and a fixture never overwrites a negative case's body or restores
the parameter that case exists to omit. A fixture that matches nothing is reported, not dropped.
Coverage is honest. The denominator counts operations the suite compiler could not compile, so a coverage number cannot be inflated by a document half of which was skipped, and every operation the report does not vouch for is named with its reason.
Reports are persisted write-once beside their evidence (apiome-db V252,
provider_verification_report) with the coverage numbers and verdict as indexed columns, so
CTG-4.4 (scheduled verification) and CTG-4.5 (deploy gating) can ask "is the newest report for
this version passing?" without parsing a report body. No new RBAC resource: a conformance report
is verification evidence. See docs/provider_verification.md.
app/contract_runner.py (ECA-2.1) now records one assertion per located schema violation
alongside the existing headline verdict, with the instance JSON Pointer as the assertion subject,
and accepts an optional per-case decisions map so a caller can hold a case back or substitute a
request without reimplementing the runner. Both are additive: omitting decisions is exactly the
previous behaviour, and the headline assertion's shape is unchanged.There is now one mock engine (#5532, MSC-2.2) — the mock implementation that lived inside apiome-rest is deleted, and every mock request is resolved by apiome-mock.
There were two. This one served /v1/mock/{id}/… — the short-lived sandbox instances the hosted
Mock Server (#3615) and the Export Studio's test drive (MFX-44.5) provision — from
mock_instances.config, a list of scenarios with rules. apiome-mock served
/{tenant}/{project}/{version}/… and portable bundles from versions.mock_settings, a dict
keyed by scenario name. They shared three routing symbols and reimplemented everything
downstream, so a feature built in one was invisible in the other: sandboxes had no templates, no
match predicates, no stateful CRUD, no fixture packs and no chaos, and every future mock feature
would have had to be written twice.
A sandbox request now takes one internal hop. apiome-rest keeps what a sandbox is — does the
instance exist, has it expired, is the caller inside its rate limit, what goes in the request
log — builds the instance's portable mock bundle, and asks apiome-mock's new /__sandbox__
endpoint to serve it through serve_compiled_request, the same function the hosted data plane
and the portable runtime call. Sandboxes gain every feature they lacked as a side effect.
There is deliberately no local fallback: a deployment that has not configured
APIOME_MOCK_INTERNAL_BASE_URL / APIOME_MOCK_INTERNAL_TOKEN answers 503 on the data plane
and says which switch is missing, rather than inventing an answer from a second engine.
The built-in scenarios still resolve, everywhere (#5532) — happy-path, server-error,
not-found and slow are written into client code by name, so all four are now defined on
every version, supplied by the runtime and merged into whatever the version stores. A stored
scenario of the same name wins outright, exactly as the retired engine's normalize_scenarios
resolved the same collision.
Two additions to the scenario schema (#5532) — both needed to express the built-ins and the migrated rules, and both available to any authored scenario:
"*", which applies to every operation a scenario does not name explicitly
(an exact key always wins). Its canned bodies are not checked against the spec at save time,
because a wildcard covers operations with different response schemas; status, media type,
headers and template syntax still are;status, which pins the response status but leaves the body to the spec,
resolved as a request sending ?__status= resolves it. A canned response with no body would
serve an empty one, and freezing a synthesized body into settings would stop it tracking the
spec.migrationNotes on a mock instance (#5532) — every rule in a pre-fold config that could
not be translated is reported on the instance and stored in mock_instances.migration_notes:
one that matched no operation in the frozen spec, one an earlier rule had already made
unreachable, one that set nothing, or one whose latency was clamped to the 30 s ceiling. The
acceptance criterion is that untranslatable rules are reported, never silently dropped.
V250__mock_instance_engine_fold_5532.sql adds mock_instances.settings (the
apiome-mock-shaped configuration an instance is served from) and migration_notes. settings is
NULL until an instance is folded; either plane folds a row the first time it reads one, so no
maintenance window is required. apiome-rest/scripts/fold_mock_instance_configs.py folds the
whole estate at once and prints the report (--dry-run translates without writing).
The translation (app.mock_instance_config) is spec-aware, because three legacy behaviours
cannot be reproduced from the stored shapes alone: a body-only rule served the operation's own
default success status; precedence was first-matching-rule-wins per operation, which inverts in
the keyed shape where an exact key beats the wildcard; and a rule matching nothing in the frozen
spec did nothing. active_scenario lands on activeScenario, the key #5531 introduced — the two
spellings of one concept are now one. The legacy config column is kept, unread, as the pre-fold
record a migrated instance is diffed against.
app.mock_engine and app.mock_data_generator (#5532) — the retired engine's resolver
(resolve_response, normalize_scenarios, resolve_active_scenario_name, BUILTIN_SCENARIOS)
and its data generator, superseded by apiome_mock's resolver and its format-aware
schema_synthesizer. What both packages genuinely shared — MockOperation,
extract_operations, match_operation and the path-template compiler — moved to
app.mock_routing, whose name says that it is routing and not an engine. The one piece of
mock_data_generator with no runtime counterpart, validate_value, moved to
app.mock_schema_validation.The version's active scenario is now a mock setting the hosted runtime honours (#5531,
MSC-2.1) — GET/PUT .../mock/scenarios carry activeScenario, the scenario the mock serves
when a request sends no X-Mock-Scenario header. It is stored in versions.mock_settings
alongside the scenarios it names, travels inside a portable mock bundle, and is a section of the
MSC-1.4 configuration document.
Until now the control plane could store and switch an active scenario that nothing in the hosted
data plane read: grep -rn "active_scenario" apiome-mock/src returned nothing, and the runtime
selected a scenario from the request header alone. Switching a mock to server-error and then
calling the hosted URL returned happy-path responses, with nothing to indicate why. A shipped
control that changes nothing is a correctness problem, not a nicety.
The precedence is explicit: request header → stored activeScenario → no scenario. The
header stays an outright override, and a version with no stored value behaves byte-identically
to before. Every response served while a scenario is in effect now names it in the
X-Mock-Scenario response header — including responses for operations the scenario does not
override, because a caller who sent no header cannot otherwise tell what answered them.
activeScenario must name one of the scenarios saved with it, so a version can never store a
default that means nothing; the runtime, by contrast, is lenient with a stored name that stops
resolving (a renamed or deleted scenario) — it logs mock_active_scenario_unknown and serves the
default flow, because an unresolvable default must never take a serving mock down.
Unlike scenarios and chaos, the field is preserved when a PUT omits it and cleared only
when it is sent as null, so an editor written before the field existed cannot silently switch a
version's mock back to its default flow.
activeScenario (#5531) — a bundle exported from a version defaults to
the same scenario the hosted mock does, asserted response-by-response by the PMR-3.1 parity
harness.scenarioSource — "header" or "config" — so a preview
says why a scenario applied, not merely that one did.?dryRun=true on the version mock-settings write routes (#5530, MSC-1.4) — PUT .../mock/scenarios, PUT .../mock/correlation and PUT .../mock/fixture-packs accept
?dryRun=true: the same validation runs, the response describes what would be stored, and
nothing is written.
It exists so that a mock configuration held as a file — apiome mock config push --dry-run —
can be checked in CI against the authoritative validators rather than a second copy of them,
and so that a real push can validate every section before any of them is stored. Without it a
document whose scenarios are valid and whose correlation block is not would leave a version
half-configured, and would report only the first problem rather than all of them.
The dry-run response is built by the very readers the write path reports with, so it cannot
describe an outcome the write would not produce — operation keys normalize the same way, fixture
packs gain the same format defaults, and a cleared correlation block reports as null. It
reports validation, not ownership: the creator/administrator gate lives in the write itself and
cannot be exercised without writing.
The parameter defaults to off, so every existing caller is unaffected.
Mock authoring catalogue endpoint (#5529, MSC-1.3) — GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/operations describes a version
the way a mock editor needs it: every operation it has, with its path, query and header
parameters (each carrying the ready-to-insert {{request.*}} expression), the JSON Pointers the
success response body actually has, the top-level request-body field names, and the fixture names
{{fixture.<name>}} can read on this version.
The part that makes response correlation trustworthy is bindings: which response properties
the path-params and inferred passes would bind, and to what, projected before anything is
saved. Those are not a second implementation of inference — the name-matching rules moved into
the new app.mock_correlation_rules, which apiome_mock.correlation now imports, the same call
app.mock_match and app.mock_template already made. So the editor's preview cannot promise a
binding the runtime declines to make.
Two limits follow from projecting over a response schema rather than a rendered body, and are
reported rather than hidden: a pointer inside an array names member 0 and is flagged
repeated (the runtime binds every member), and a oneOf/anyOf schema is projected through
its first branch. The walk is bounded — depth 6, 200 pointers per operation, and a $ref cycle
guard — so a recursive schema terminates.
Read-only and cheap: it generates the version's OpenAPI document and walks it, needs only
versions:view, writes nothing, and answers for a version whose mock is switched off —
which is when correlation is usually configured for the first time.
Mock response preview endpoint (#5528, MSC-1.2) — POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/preview answers the question a
mock author actually has: given this request, what does the mock return? Send a synthetic
request (method, path, headers, query, body, plus scenario/seed shorthands) and get
back the status, headers, media type and body the mock would serve — with no mock enabled, no
instance provisioned, and no live request.
Every response carries a decision trace naming which layer produced the body: scenario
(with the matched rule's zero-based index), stateful, correlation (with the mode and the
JSON Pointers it bound), example or synthesis — plus forced-status, request-invalid,
no-operation, method-not-allowed, unknown-scenario, not-acceptable and template-limit
for the paths that produce no ordinary body. Without it an author can see that a value
appeared but not why, which is most of the value of a preview.
The render is not re-implemented here. REST authenticates and authorizes the caller, builds
the version's portable mock bundle, and asks apiome-mock's internal /__preview__ endpoint to
render it through serve_compiled_request — the same function its data plane and the portable
runtime call. A preview therefore cannot disagree with the served response, and apiome-mock's
suite asserts exactly that by rendering one correlated request both ways.
An optional settings override previews an unsaved draft: it overlays the stored settings
per key (scenarios, chaos, fixture packs, callbacks, correlation), is canonicalized and validated
with the same rules its save route applies — so a draft that could never be saved is a 422 rather
than a silently ignored no-op — and persists nothing. It requires versions:edit; previewing the
stored settings needs only versions:view.
Preview never writes: session state lives and dies inside the render, no callback is delivered,
and no usage, audit or provisioning row is touched. Chaos is reported rather than applied, so a
preview never sleeps for a configured latency or randomly answers 500. Renders are rate limited
per version (APIOME_MOCK_PREVIEW_RATE_LIMIT_PER_MINUTE, default 120) and the synthetic body is
capped (APIOME_MOCK_PREVIEW_MAX_BODY_BYTES, default 256 KiB).
Configuration: APIOME_MOCK_INTERNAL_BASE_URL (the mock service's internal address) and
APIOME_MOCK_INTERNAL_TOKEN (shared with apiome-mock). Both are required — with either unset the
endpoint fails closed with 503. The token is deliberately not INTERNAL_SERVICE_TOKEN:
rendering a preview should not carry the secret that unseals auth-provider credentials. See
docs/guide/mock-response-preview.md.
Request-correlated mock responses (#5527, MSC-1.1) — GET/PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/correlation read and write a
responseCorrelation block in versions.mock_settings, alongside the existing scenarios,
chaos, fixturePacks and callbacks keys. The block makes the mock's default response
path answer with the request's own values — with no request header, so a generated SDK or a
browser app gets it too, where scenario overrides (X-Mock-Scenario) and stateful CRUD
(X-Mock-Session) could never reach.
Four modes: off (the default — byte-identical to today), path-params (a response property
named after a path parameter takes the request's value, at every depth and inside array
members), inferred (that plus echoing request-body fields back on POST/PUT/PATCH, while
id/createdAt/updatedAt and anything absent from the request stay synthesized), and
explicit (only a per-operation map of response JSON Pointer to template expression). The
pointer map applies in every mode except off and always wins for the pointer it names.
Expressions are the existing bounded {{ … }} language, validated on save with
validate_template_value, so a bad expression is a 422 rather than a serve-time surprise;
operation keys must name a real operation in the version's generated OpenAPI document; bindings
saved with mode: "off" are refused rather than silently ignored. Limits: 200 operations, 50
pointers each, 64 KiB. responseCorrelation is a bundled settings key, so a portable bundle
correlates identically offline (the PMR-3.1 parity harness asserts it). See
docs/guide/mock-response-correlation.md.
mock_settings.fixtures reader (#5527) — apiome_mock.fixture_data.parse_fixtures
read a flat fixtures map that nothing in apiome-rest ever wrote; only fixture packs are wired.
A configuration surface that silently did nothing was dropped rather than given a writer.
Hosted template fixture data comes from fixturePacks alone; the bundle path is unchanged.legacy; the weekly screenshot refresh lists the
legacy screens that changed, and docs:check requires the callout on any page that shows one.apiome-ui/examples/, and Apiome's own MCP
server for the MCP example.FEATURE_GITLIKE badge: they are switched off in every shipped build.yarn docs:check runs on every pull
request — not only those that touch the docs — so a change to a product screen or an endpoint
cannot merge with its page, screenshot or reference behind it.
(#5630)
unlisted) fails.sources field.The image serves the static site with nginx on port 8080, answers a /healthz health check, and is
published from main tagged with the docs version, latest and the commit SHA.
The existing guides move onto the site over the RC6 documentation epic, together with screenshots of every screen that regenerate from the product, generated REST / CLI / MCP reference and a release-notes page per release.
]]>openapi.yaml changed without regenerating the REST pages.diff-action and mock-action READMEs.signed-out entries capture a page such as sign-in without a
session.docs/guide/ folder are now pages on this site, grouped
by job: Bring in, Build, Ship (with its own Mocks
section), Govern and Reference. (#5619)
docs/guide/README.md
maps each old file to its new page, and a lint result that still names a docs/guide/ page opens
the new one.docs/archive/, 253 kept (package READMEs and changelogs, skills, test fixtures, runbooks, and the
contributor references code points at), 3 migrated — with the site page that now covers each
archived note's area.xms_edov claim and GitLab's read_user scope — are now on
Sign-in providers..md under apiome-*/docs/;
Contribute to the docs says where docs go instead.#1234 linked to its issue and the milestone's issue list one click away.main.RC6 opens a pull request with the RC6 post.screens.json lists each screen: its route, what to wait for, and what to mask.
yarn docs:screenshots captures it at 1440 × 900 with the clock fixed, so reruns match pixel for
pixel.yarn docs:check fails when a page shows a screenshot that has no light or dark image.Contribute to the docs has the recipe for adding one.
]]>apiome command, and the Reference for the
REST API, MCP, the mock runtime and CI.
appTheme.From the in-app What's new for Apiome 07-2026 RC4.
operationRef/operationId links to the matching operation when that OpenAPI spec was imported in the same scan, and an unresolved reference keeps its raw value with a warning instead of being droppedblock (the default; nothing is fetched and the file is flagged with exactly which references are missing), inline (permitted references are fetched once and snapshotted into the scanned spec), or proxy-fetch (the same, restricted to an allowlist of hostnames, wildcards like *.acme.com included). Every fetch is recorded in the audit trailmeta endpoint, Atlassian's for Bitbucket — are fetched daily and cached, so the list stays right as the providers move; your workspace can add its own ranges for a self-hosted runner or an egress gateway, and each one records why it exists. The page states in a sentence whether the filter is actually protecting anything right now, rather than leaving you to combine three switches, and flags a provider whose range list has stopped refreshing. Turning the filter off for your workspace is a tenant-administrator action and asks for a reason, which goes into the audit trailPOST /v1/access/{tenant_slug}/members/{user_id}/resend-invite.
Apiome does not mail invitations: an invitee already holds an account and their pending
membership flips to active the next time they sign in. Re-issuing therefore renews the
invitation rather than re-sending a message — the membership row is re-stamped
(touch_pending_membership, scoped to status = 'pending' in SQL so an invitation accepted
in between cannot be un-accepted) and the renewal is written to the access ledger as
member.invite_resent, which the existing ?filter=member audit tab already covers.
Gated on members:create; consumes no seat, because the pending membership already holds
one. Answers 404 when the user has no membership in the tenant and 409 when their
membership is not pending.GET /v1/access/{tenant_slug}/members carries three more facts per member (#5305) —
joined_at (tenant_users.created_at, when the membership was first written, as distinct
from the existing member_since = updated_at, which moves with every status change),
last_active (users.last_login_at, V070) and two_factor_enabled (the Better Auth
users."twoFactorEnabled" flag, V201). All three read columns that already existed; the
response is additive, so existing clients are unaffected.Project versions were re-linted when listed (#5259) — the Versions screen rendered a
lint badge per row that called GET .../{version}/lint for every revision, and for any
revision without a stored report (hand-authored, forked, pushed, pre-V160) that endpoint
rebuilt the OpenAPI document, ran the linter and the external validation pack — on
every list render, N times over. Fifty revisions meant fifty concurrent lints.
The report now lives on the version record and is served from there.
GET /v1/versions/{tenant_slug}/{project_id} carries each row's stored qualityScore /
qualityGrade (VersionSchema; get_versions_for_project / get_version_by_id select the
V124 columns), so the list renders from the record and issues no lint requests.
GET .../lint serves the stored quality_report whenever it is current; the persisted
report now carries a source_fingerprint (sha256 of the reconstructed OpenAPI document,
app.version_quality_capture.openapi_source_fingerprint), and freshness is decided by
rebuilding the document and comparing — never by re-linting. A revision with no stored
report, or whose content changed since capture, is linted once and the result persisted
(persist_version_lint_report), so the next read is a plain read; a baseRevisionId
comparison is computed live and never stored. Reports without a fingerprint (pre-#5259,
canonical-model imports) are served as-is; a legacy native import re-linted from its
canonical model is stored on first open too.
Linting runs on version changes and imports only. Push (POST /v1/versions/{t}/{p})
and fork schedule the shared capture (capture_version_quality_score, moved out of
spec_import_engine) as a background task; the publish precheck stores the report it
already computed; import/conversion captures gained the fingerprint + guide context
(persistable_lint_report). Stored reports echo the guide they were scored under
(guideId / guideName / guideSource) so the read path has the same context as a live run.
Bounded primitives search (DWX-3.1, private-suite#2683) — GET /v1/primitives/{tenant_slug} has always answered with every primitive a tenant
can see. A tenant that has imported a standard library has thousands of rows, and
the unified workspace's type picker — a 320px rail — cannot be built on a read like
that. The endpoint now takes q, scope, namespace, limit and cursor, and
answers those with at most limit rows plus the four type-picker tab counts
(app.primitives_search_store, PrimitiveSearchPage).
Both shapes, one path. A caller that asks none of the five bounded parameters
gets the classic JSON array, from the same get_primitives_for_tenant read, with
category working exactly as before — the classic property dialogs are unaffected
and keep working until private-suite's DWX-8.3 retires their callers. Asking any one
of the five switches the response to the paged envelope. The two shapes list the
same catalog: the same visibility scope (is_system ∪ the caller's own rows) and
the same (namespace, name) deduplication, so a primitive is never reachable
through one and not the other.
The scope classification is the client's rule, in three places that must agree.
The four tabs — Standard, Core, Tenant, Custom — are derived in the designer today
by classifyPrimitive. A server that filtered by scope while the client grouped by
its own rule would silently hide types, so the rule is now written three times over
one shared fixture (tests/fixtures/primitive_scope_cases.json): the TypeScript
original, classify_scope in Python, and SCOPE_EXPRESSION in SQL. pytest checks
Python against the fixture and SQL against Python over real rows; the designer's jest
suite checks the TypeScript half against its copy of the same cases.
The cursor is keyset, not an offset. It carries the sort key of the last row
handed out, so a primitive created mid-scroll cannot shift a page boundary and make
a row repeat or vanish; a live-DB test walks 5,000 rows and asserts each is visited
exactly once. It is opaque, and a token this endpoint did not mint is a 400 rather
than a silently ignored parameter that would restart a paging client at page one
forever. An unknown scope is likewise a 400 — a misspelling that quietly listed
every tab would make an unbounded read look like a bounded one.
Tenancy is unchanged and enforced by construction: another tenant's private types
are not filtered out of the result, they are never in the visibility CTE, so no
query, namespace, cursor or $ref reaches one.
apiome-db/scripts/V244__primitives_bounded_search_indexes_2683.sql adds the
read-path indexes: a (namespace, name, tenant_id) b-tree for the dedupe and the
cursor ordering, an (is_system, source, namespace) b-tree for the scope
classification, and pg_trgm GIN indexes so a leading-wildcard ILIKE is not a
sequential scan of the registry. Nothing there changes a column, a constraint or a
value, and — as in V230 — the trigram block degrades to a NOTICE where the
migration role cannot install contrib extensions.
Programmable custom palette actions (DUW-5.5, private-suite#2592) — The ⌘K
palette's Actions band has been a fixed registry of five built-ins since DUW-5.4;
"programmable" means a tenant defining its own rows — Open runbook for {subject}
against every class whose name contains Invoice — and that needs the definitions
stored somewhere durable and tenant-scoped. apiome.workspace_custom_actions (V243)
and the CRUD surface under /v1/workspace/{tenant_slug}/custom-actions are that
storage.
A definition is a declaration, never a script. Its matcher is a subject kind
(class, path, property, any) plus an optional case-insensitive label
substring; its effects are an ordered list drawn from a closed vocabulary —
hydrate-set, lens-switch, open-inspector-tab, run-consumption-query,
open-url — each element validated down to exactly the fields its type declares
(workspace_custom_action_rules). Unknown keys are rejected rather than ignored, so
a typo cannot become an effect that silently does less than its author meant;
open-url accepts absolute https:// URLs only, with no embedded credentials,
because javascript: and data: are not effects, they are payloads. Anything
resembling SDK-script execution stays out of scope by design and defers to the
DUW-7.4 sandbox. The database independently pins the outer shape — a JSON array of
1–5 elements under 16KB — so no write path can park a script here even if it skipped
the service schema.
Tenancy comes from the token, never the URL: every statement is scoped by the
caller's tenant, so another tenant's action is a 404 — whether it exists is not
something this API confirms. Reads are open to any authenticated member (the palette
performs one for everyone); writes require an attributable user holding
VERSIONS/EDIT, the same gate the domain folders use for reorganizing what everyone
sees. Deletes are soft, and a live action's name is unique per tenant
case-insensitively — two rows both drawn as Open runbook… in one band would be
indistinguishable to the reader. The management page that will wrap this API is
DUW-8.2 (private-suite#2602); until it lands, these routes are the management
surface, which is why every 422 names the offending field as a pointer
(effects[1].lens).
Response status codes on the scoped path read (DUW-4.3, private-suite#2583) —
The unified workspace's paths lens draws every operation as a lane, and a lane ends
in the codes it answers with (200·400·401), coloured by method. Those codes were
the one thing on the lane the scoped read did not carry: GET /v1/workspace/{tenant}/version/{version_id}/paths shipped each operation's
operation_id, summary and deprecated flag and left everything about a response
with the per-path /full endpoint. That is right for a response body — schemas,
content types and examples are inspector-sized data for one selected operation — but
a status code is a label the canvas prints on every lane it draws, and there is no
number of round trips between "one" and "one per operation" that answers it.
Each operation now carries response_codes: the status codes it declares, as
strings, ascending (default sorts after the numbers), empty when it declares none.
They come from a lateral aggregate over path_operation_response_link →
shared_path_response on the statement that was already reading the operations, so
a page of paths costs the same two statements it did before, whatever its size. The
codes are per operation, not per path: responses are shared per path in this schema
and linked per operation, so a read that rolled up by path would give every verb on
/customers the same list. Response bodies stay exactly where they were.
Schema↔path consumption index (DUW-1.4, private-suite#2571) — Five surfaces
of the unified workspace need to know which operations consume which classes and
how: the combined lens's edges (solid amber for a schema named directly by a
request or response, dashed rose for one reached through a parent class), the
tree's per-path Schemas rows (Customer 200, Address nested), the palette's
"find every path that consumes X" action, the inspector's Consumes list, and
the status bar's N schema↔path links chip. Today's derivation is the designer's
createAllEdges — O(classes×properties) over a full-catalog fetch, and
schema↔schema only; it has never known that an operation consumes anything.
GET /v1/workspace/{tenant}/version/{version_id}/consumption answers it from
the server, in seven statements.
Every edge names both members, how the consumption arrives (request,
parameter, response.<status>) and — for a nested one — the chain of classes
it hangs off, so one response drives all five surfaces. The facts arrive twice:
flat in edges, the shape the canvas draws, and rolled up per path in paths,
the shape the tree nests under a path with the badge each row prints.
link_count counts operation↔class edges, path_link_count distinct path↔class
pairs.
Five decisions are load-bearing:
A reference is a $ref anywhere in a payload. The catalog stores an
operation's schemas as a class_id column, an inline schema or a legacy data
blob, and a class's own references as $ref, items.$ref,
allOf/anyOf/oneOf, or any of those nested inside another. Enumerating the
shapes would mean re-deriving the emitter's rules in reverse and losing an edge
whenever they gained a case, so the resolver walks the JSON and collects every
$ref — exactly the set of names the emitted document carries. Only the tables
the emitter reads are indexed (shared_path_response(_content),
shared_path_request_body_content, shared_path_parameter); the V028-era
tables V031–V034 superseded are read by nothing, and indexing them would invent
edges no exported document contains.
Nesting is resolved per class, not per operation, and breadth-first. Two
operations returning Customer reach the same descendants through the same
edges, so the walk runs once per class and is memoized — walking per operation
would be the client-side derivation moved to the server and multiplied by the
operation count. Breadth-first makes via the shortest parent chain, and
ties break on class name, so "nested via X" is a property of the catalog rather
than of row order. Cycles terminate by construction: the visited set includes
the root, so a self-referencing class and a mutual pair are each walked once
and the root is never nested under itself. Depth is capped at 6 hops
(depth_cap) and a graph continuing past it says so through depth_capped.
A directly named class is never also nested. The canvas draws one line between two nodes, and the solid one is the truthful description.
The scope narrows paths; the graph is always whole. domain_id and
path_ids are mutually exclusive path selectors; class_ids narrows the class
side and composes with either, because "which of these classes does
customers/ consume" is a real question. The class filter is applied after
the walk — filtering the graph first would drop the very parents a nested edge
is reached through, so "every path that consumes Address" would miss every
path that reaches it through Customer, which is most of them. A
domain-scoped answer therefore still names classes outside the domain, which is
what "nested via parent" means.
Caching is content-addressed. The index is computed on read and never
persisted (no table in v1); the response carries a strong ETag digested from
the body, which keys it on version content by construction and on the scope —
something a stored version-content hash would not do — so a repeat read is a
304 until the index actually changes. Same convention as the APX-3.4 agent
outputs.
Bounded and honest about it: edge_limit caps the edge list at 5000 with
truncated set, and there is no cursor, because an edge means nothing without
both members it connects. Unresolvable path or class ids come back in
missing_ids rather than being silently absent, and the two id selectors share
the DUW-1.2 cap of 200 per request. Verified against a seeded 218-path /
250-class catalog under pg_virtualenv: the mockup's
Customer/Address/ContactMethod × 4 operations reproduced edge for edge including
nested via parent and the status bar's six path↔class pairs, a self-referencing
class and a mutual pair terminating on stored rows, seven statements whatever the
scope, and p95 ≈ 5.3 ms against the epic's 300 ms budget. No migration: V242's
domain_id indexes and the existing version_id indexes cover the reads. The
BFF routes and typed client are DUW-1.5.
Domain summary & counts API (DUW-1.3, private-suite#2570) — The workspace
tree draws a badge on every domain folder before anything is hydrated —
customers/ 3·4, billing/ 5·9, shared/ 8 — and each lens badges the same
folder with a different number (3 classes in the schemas lens, 4 ops in the
paths lens). Deriving any of that in the browser would mean fetching the whole
catalog first, which is the read DUW-1.2 exists to eliminate.
GET /v1/workspace/{tenant}/version/{version_id}/summary answers it in one
round trip: every folder with class_count, path_count, op_count and
enum_count, plus shallow member lists — class rows (id, name, kind, version
badge) and path rows carrying their operations (verb, operation_id,
summary, deprecated) — which is every field the three tree lens panels
draw.
Counts are exhaustive; member lists are not. A badge that is only right for the
first page is not a badge, so each count covers the folder's whole membership,
while the rows beside it are capped per folder by member_limit (default 50,
clamped to 200, 0 for badges alone) and a folder that was cut reports
classes_truncated / paths_truncated, continuing through DUW-1.2's paged
reads. class_count and enum_count partition a folder's classes rather
than overlapping, matching the mockup's customers/ 3 classes above three
objects and one enum; each row carries a kind of object/enum/union read
from the stored schema column, so the Schemas and Enums & unions groups
need no second pass, and objects sort first so a truncated list is cut from the
enum group upward. The v2.1 badge is the version's own label repeated per
class row — a class has no version of its own — so a tree row renders without
consulting the envelope.
The cost is four statements whatever the version holds: a window function
carries each domain's totals onto its own member rows, so a 40-folder catalog
costs what a one-folder catalog does. A per-domain count query would be exactly
the N+1 this endpoint exists to prevent, and would pass every functional test.
The shared/ bucket is joined with IS NOT DISTINCT FROM, because NULL = NULL would silently drop the largest folder in most catalogs, and empty
folders are listed with zeroes so a newly created one cannot look like a failed
write. Reads commit, matching the scoped reads: psycopg2 opens a transaction
for a bare SELECT too. Verified against a seeded 218-path / 250-class catalog
under pg_virtualenv — every badge checked against its own SELECT COUNT(*),
the mockup's numbers reproduced, and p95 ≈ 3.5 ms against the ticket's 300 ms
budget. No migration: V242's domain_id indexes and the existing version_id
indexes cover the aggregates. The per-path schema rows the combined lens nests
under an operation remain DUW-1.4.
GET /v1/classes/{tenant}/version/{version_id}/with-properties-tags, three
queries with no LIMIT that return the whole catalog. Twelve designer call
sites use it, /editor fires it twice on mount and again after every
single-class edit, and that is the direct cause of the browser choking on a
large catalog. /v1/workspace/{tenant}/version/{version_id}/classes and
…/paths answer the question the canvas actually asks: these items, or
this folder, never this version. A selection is mandatory — omitting both
class_ids and domain_id is a 400 rather than a convenience default,
because that default would be the very read this endpoint exists to replace,
and supplying both is a 400 too rather than a guess about which one wins. The
server cap is enforced two different ways for one reason: a page size over 200
is clamped, since a domain listing hands back a cursor and the client has a
working continuation, while an id list over 200 is refused, since there is no
cursor for an arbitrary id set and quietly answering a different question than
the one asked would be undetectable. Both bounds are echoed in every response
and documented in the OpenAPI parameter descriptions, so a client never has to
trigger a 400 to discover them. A bounded read is still a bulk read: three
statements hydrate a page of classes and two hydrate a page of paths, whatever
the page size, so cost tracks the selection rather than the catalog. Ids that
no longer resolve — a class deleted since the selection was made, one
belonging to another version, one that is not a UUID at all — come back in
missing_ids rather than as a silently short response that would leave an
unexplained hole on the canvas. Every query is scoped by version_id even in
id mode, which is the tenancy boundary: the version is resolved against the
caller's tenant first, so an id from another tenant's catalog matches nothing.
total is the size of the whole selection rather than of the page, which is
what the workspace sizes its node budget against, and pagination reuses the
same opaque cursor format the export and import manifest surfaces already
speak. Paths carry their operations with each operation's operation_id,
summary and deprecated flag, because the mockup's paths lens draws the
operationId beside every verb; parameters, request bodies and responses stay
with the per-path /full endpoint, which is inspector-sized data for one
selected operation. The legacy full-version read is deliberately unchanged —
exports, scoring and readiness sweeps really do want every class — but now
carries a deprecation note pointing here. No migration: V242's domain_id
indexes were added for exactly these reads.ORDER BY name ASC. Tags and canvas groups are not that hierarchy —
tags are project-scoped, many-to-many and for filtering; canvas groups are
per-layout visual furniture. A folder that scopes a fetch has to be exactly
one per item, version-scoped, and stored beside the item it groups, so V242
(apiome-db) adds apiome.domains plus a nullable domain_id on
apiome.classes and apiome.version_path. /v1/domains lists, creates,
renames and deletes them, and moves a class or a path between them.
shared/ is deliberately not a row: a member with domain_id IS NULL is
in it, so the bucket always exists, cannot be renamed or deleted, and is
synthesized into the list response with id: null and virtual: true. The
slug shared is reserved by a CHECK so no stored domain can draw the same
folder. Deleting a domain never deletes its contents — the delete is a soft
delete, and V242's trg_domains_soft_delete_release releases every member to
shared/ in the same statement, with ON DELETE SET NULL covering a hard
delete too; the response reports how many classes and paths moved. A database
trigger, not a service-layer check, rejects a domain assignment that crosses
versions or targets a deleted domain, because a foreign key can constrain
domain_id but knows nothing about version_id on either side. Existing
catalogs are backfilled: paths seed domains from their first meaningful path
segment — skipping templated segments (/{customerId} names an instance) and
API version prefixes (/v1/ is on every path, so it partitions nothing) — and
classes follow a project tag whose name slugifies to a seeded domain. Anything
unmatched stays in shared/, which is the honest outcome for a catalog with no
path structure and no tags. Per-domain counts for the tree badges are DUW-1.2 /
DUW-1.3, not this release./v1/slate: attach a hostname to a lane and get back the exact DNS rows to
publish, verify ownership against the tenant's live records, probe the host to
see what certificate it is actually serving, make a host canonical, park
renewal, and detach. A subdomain is delegated with one CNAME; an apex is
proven with a TXT record and pointed with ALIAS/ANAME, because RFC 1034
forbids a CNAME beside the SOA and NS records every apex carries. A failed
check reports what the resolver found, not merely that it failed.
app.slate_dns is a dependency-free DNS client (the stdlib resolver discards
the CNAME chain and every TXT record — the two things verification needs);
app.slate_tls_probe completes a verified TLS handshake and reads the peer
certificate, so every certificate field is an observation of the live host at
a stated instant and a renewal is detected (the serial changes) rather than
assumed. Nothing here issues, stores or renews a certificate: the edge does
(deploy/Caddyfile, Caddy on-demand TLS against Let's Encrypt), and
GET /v1/slate/tls/authorize?domain= is the gate it asks first — a single
conjunction (row exists, ownership verified, renewal on), unauthenticated
because the caller is a TLS handshake with no session to present. Requires
V241 (apiome-db), which adds the verification/certificate lifecycle columns
and CHECKs that make "verified with no timestamp" and "active with no expiry"
unrepresentable. New settings: APIOME_SLATE_DOMAIN_DNS_TARGET,
APIOME_SLATE_DOMAIN_RESERVED_ZONE,
APIOME_SLATE_DOMAIN_VERIFICATION_SECRET (fails closed in production).app.snippet_render):
GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/snippets/{operation_id}?lang=
(authenticated, published revisions only) and
GET /v1/browse/tenants/{t}/projects/{p}/versions/{v}/snippets/{operation_id}?lang=
(anonymous, published+public with uniform 404s, sharing the public-export
rate limit). Languages: ts (built-in fetch), python (httpx, with a
pip install httpx install line), and curl, plus browse-vocabulary
aliases fetch/httpx. Output shape, escaping, and $API_KEY-style
secret placeholders mirror the client-side Try It generators; request
bodies are minimal valid instances synthesized deterministically from the
payload schema, so responses are content-addressed (ETag / 304). The
structured response carries the resolved operation, the synthesized
request, and a placeholder inventory so consumers need no post-processing.
Snippets derive from the canonical spec directly — the original SDK-2.1/2.2
template dependency was dropped when those tickets were cancelled.wit
ImportSource adapter makes WIT packages importable (file, URL, paste, or a
multi-file package fileset). Worlds and interfaces normalize to canonical
services on the RPC paradigm, functions to operations (a top-of-return
result<ok, err> becomes the RESPONSE/ERROR message pair; option<t> maps to
canonical nullability, list<t> to list nesting), and the WIT type system to
canonical types: record → RECORD, enum → ENUM, variant → UNION with case
payloads preserved, flags → ENUM with bitset semantics flagged, type
aliases → ALIAS, resource → RECORD carrying its constructor and methods in
extras.use resolution — Archive/git filesets merge every .wit
member into one package, so use iface.{type} statements resolve against
sibling files; a use naming another package is recorded as an external
reference (inferred / source_incomplete ledger row), never fabricated or
dropped.borrow<…> handle semantics, tuples,
nested results, stream/future wrappers) are preserved in extras and
reported on the import preview coverage ledger as partially-mapped
capability limits; declared parser limits (include expansion, secondary
nested package blocks) carry not-parsed-by-adapter registry entries.ImportSource
adapters make gateway configs importable: kong (Kong declarative / deck
YAML-JSON, single file or split fileset) and gateway-api (Kubernetes Gateway
API HTTPRoute manifests, single document, multi-document stream, or manifest
directory). Routes normalize to canonical REST operations — hosts, path
patterns (regex paths become inferred {param} templates with the original
pattern preserved as evidence), methods, header/query matches, and backends.
Kong auth plugins map to canonical security where a mapping exists
(key-auth → apiKey, jwt → bearer, oauth2, basic-auth, mtls-auth,
openid-connect) and are preserved as unmapped hints otherwise; Gateway API
filters are preserved verbatim in extras.inferred / source_incomplete — a capability limit of the source
format, never a drop.kong joins the
always-enforced intake secret-scrub formats, and a secrets-kong.yaml
adversarial fixture guards the pipeline end to end.app/openapi_overlay.py).
update deep-merges into object targets (nested objects
merge recursively; primitives and arrays replace), appends to array targets,
and replaces primitive targets in place; remove: true deletes the selected
nodes (list indices deleted highest-first so survivors never shift under the
removal). Targets are JSONPath, evaluated through the custom-rule DSL's hardened
Spectral-compatible parser (parse_jsonpath_expression, now public).InputKind.FILESET) — members classified by version marker (exactly one
openapi/swagger base; every overlay: 1.x member applied in member-path
order, each seeing the previous one's result, so a chain's last writer wins);
unclassified members (e.g. $ref targets) ride along untouched and are listed
as ignored.extras["overlay"], rendered by the import preview
coverage ledger as document-scoped mapped rows — capped at 500 records with a
declared-truncation row, never a silent cut.INPUT_OVERLAY_BASE_MISSING, whose remediation prompts for the base document —
instead of an obscure parse error. A fileset with overlays but no base gets the
same code.update nor remove, invalid
JSONPath, type-mismatched update, root removal), surface as new registered
warning rules intake.overlay-unmatched-target / intake.overlay-action-invalid
merged into the import lint report (tenant-governable like any registered rule).openapi/34-overlay-basic-set/ (add + update + remove in one
overlay), openapi/35-overlay-chain-set/ (two-overlay chain with a last-writer
override), and negative openapi/negative/06-bare-overlay.yaml
(INPUT_OVERLAY_BASE_MISSING), with canonical goldens; the openapi multi-file
rung waiver is retired.app/graphql_federation.py, docs in docs/graphql_federation.md).
join-spec directives
(@join__type / @join__field, external: true references excluded); a subgraph
set derives ownership from file boundaries (@external stubs excluded). Recorded as
extras["federation"] on the artifact and extras["subgraphs"] on every owned
type/field/service/operation, so ownership participates in the fingerprint.@key/@shareable/
@link without defining them; the parser injects exactly the missing Federation v2
definitions before validate_sdl (author definitions never overridden).GraphQlDiffLabeler — the first provider on the MFI-3.x
DiffLabeler SPI — labels every change with its owning subgraph(s)
(owned by subgraph 'reviews', subgraph ownership: products → reviews).composition category in the GraphQL rule pack —
graphql.composition-invalid-key, graphql.composition-non-shareable-field,
graphql.composition-unresolvable-selection (pure checks over the subgraph set), and
graphql.composition-error surfacing the bundled rover supergraph compose verdict
captured at import time (worker-loop bridge; degrades to "no verdict" when the tool
or its composition plugin is unavailable). Every finding names the offending
subgraph. Federation spec-machinery names (join__Graph, …) are exempt from the
GraphQL naming rules.print_schema_with_directives restores them on the parser's canonical SDL and the
normalizer's raw["sdl"], and the emitter rebuilds custom directive definitions
(extras["directive_definitions"]) as real GraphQLDirectives and re-attaches the
per-entity extras["directives"] applications onto the printed SDL with validation
fallback. A GraphQL→GraphQL supergraph round-trip is canonical-diff clean.graphql/13-federation-set/ (products/reviews/inventory,
multi-file rung) and graphql/14-federation-supergraph.graphql (composition
rung), with canonical goldens.FileDescriptorSet (or a buf image), not a .proto
source tree; the gRPC adapter now imports that artifact directly.
ImportSource.accepts_bytes / parse_bytes): the import
pipeline consults the adapter before decoding an upload to text and routes claimed
binary payloads to parse_bytes under the same IXH-6.5 size/time/memory stage guards
(the raw-bytes ceiling applies before the parse ever runs). Text-only adapters are
unaffected (default declines).parse_bytes decodes a FileDescriptorSet / buf image with the
pure MFI-9.1 read layer — dependencies resolve from within the set, with no
filesystem, network, or buf toolchain access — and feeds the existing Protobuf
normalizer. Payloads are claimed by content sniff (sniff_file_descriptor_set) or by
conventional suffix (.binpb/.desc/.protoset), so malformed descriptor uploads
fail with descriptor-specific taxonomy codes (INPUT_MALFORMED, or INPUT_TRUNCATED
when the wire stream is cut off mid-element via a top-level wire walk) instead of
INPUT_ENCODING_INVALID. The Connect-RPC adapter delegates the same seam.DetectionInput gains optional undecoded data bytes; the gRPC
adapter and the registry sniffer claim descriptor-set bytes at 0.9 confidence, so
binary uploads auto-detect and pre-flight routes them to the grpc importer.protobuf/07-inventory-source.proto and the descriptor
set / buf image compiled from it (08/09-*.binpb) must import to the same
canonical model and fingerprint; binary negatives assert the truncated/malformed
codes through the real pipeline. The corpus harness reads binary entries as bytes and
drives parse_bytes.parse_bytes completes the pairing by importing the same
descriptor bytes reflection returns.app/import_export_metrics.py, in-process/per-replica like the rest of the
/v1/ops/metrics plane): per-stage duration histograms + byte totals, terminal job totals
keyed adapter/target × format × outcome, and failure counters keyed by the IXH-6.4
taxonomy code. Every tag comes from a closed vocabulary (registered adapters/targets, the
engine stage names, the two taxonomies) with out-of-vocabulary values clamped to other —
no per-tenant or per-job tags exist. Each record also emits one structured log line
(import_export.stage|job|failure).PHASE_TIMING events (the
exact shape the tsx worker always emitted, including a failed outcome for interrupted
stages), ingested into the metrics at the engine's event-dedupe seam so both paths feed
the same aggregates; the export engine times its five stages at the _publish funnel.
Timing events persist per job inside async_job.status, so durable evidence survives
restarts even though the aggregates are per-replica.correlation_id fields): captured from the middleware's
X-Request-ID at schedule time, stamped onto every stored import/export job status and —
structurally — onto SpecImportJobError/ExportJobError, bound into every job log line
(explicitly on the export engine's thread loop), and therefore returned to the caller on
failure: the 202's X-Request-ID equals every subsequent poll's correlation_id.GET /v1/ops/import-export (platform-admin) rendering the
aggregates plus the complete documented tag set; /v1/ops/metrics/status carry the
snapshot under import_export; the ops dashboard gains Import/Export jobs and
Import/Export failures cards. Documented in docs/import_export_observability.md./v1/tenants/{tenant}/schema-suites persists
named, tenant-scoped suites — payloads plus expected verdicts in the IXH-1.1
validity_class vocabulary — attached to a stable schema reference that survives
revisions ({kind}/{artifact}[/{type}]; a 5.1-shaped reference's version segment is
discarded; registry/… is rejected because it has no revisions to regress across).
POST …/{id}/runs) execute every payload through the IXH-5.1 validator
against one revision — resolved once and pinned, so a moving latest cannot split a
run — judge each verdict exactly like the CLI (passed/failed/error), and record
the run plus per-payload results (apiome-db V240). An unresolvable reference records a
status: error run: that history is the product, not an exception.passed → failed flags the
result and the run; passed → error deliberately does not (no verdict was produced),
staying visible via previous_status. Listings carry each suite's newest run summary
so the catalog and version detail surfaces can badge regressions from one query.GET …/{id}/export produces an IXH-1.1 corpus manifest plus
payload files, directly consumable by apiome schema test --suite once materialized;
POST …/schema-suites/import reads the same envelope back losslessly.docs/schema_test_suites.md): payloads per suite
(APIOME_SCHEMA_SUITE_MAX_PAYLOADS, 50), 256 KiB per payload (V240 CHECK), findings
per result (APIOME_SCHEMA_SUITE_RESULT_FINDINGS_CAP, 20); run history pruned on
write beyond APIOME_SCHEMA_SUITE_RUN_MAX_PER_SUITE (200) and by age on the IXH-6.3
retention tick (APIOME_SCHEMA_SUITE_RUN_RETENTION_DAYS, 180) — always keeping each
suite's newest APIOME_SCHEMA_SUITE_RUN_KEEP_MIN (20) so a rarely-run suite never
loses its regression baseline.app/cross_format_conformance.py
answers it empirically, per emit target and per entity.
validate_json_instance), Avro (fastavro), protobuf (buf compile +
json_format.ParseDict), GraphQL input types (graphql-core input coercion), and XSD
(xmllint) — the IXH-5.2 source-valid instances (minimal, full, branch; never mutants)
are validated against the actually emitted schema. Failures are reported per entity
with the target-side constraint that rejected the instance.app/conformance_transcoding.py): base64 →
Avro binary, canonical-model-driven JSON → XML documents mirroring the emitted XSD
grammar, and the proto3 canonical JSON mapping. Transcode failures are a separate
failure kind — they never masquerade as a pass or a conformance verdict.buf, xmllint) reports not validated with the
reason, mirroring the export_validation honesty contract.POST …/export/preflight accepts
include_conformance, attaches each target's verdict beside its structural fidelity
envelope, demotes a ready target to caution when its emitted schema rejected
source-valid instances, re-ranks, and refreshes the ranking fingerprint.POST /v1/export/{tenant}/roundtrip runs the same loop, on demand, for one
(source revision, target, options): a read-only emit via the dispatch primitive (so the
verdict and the Studio's fidelity surfaces describe one snapshot), re-import through the
matrix's own adapter join, canonical_diff against the source, and the matrix's
reconcile against the fidelity report. Nothing is persisted — no artifact, no job row,
no field-identity rows.matched (each explained difference paired with the
fidelity finding covering it — expected loss), unexplained, and overclaims (ok
findings reality contradicts) — the latter two flagging a fidelity bug worth reporting,
with reproduction provenance (model fingerprints + emitter/apiome/registry versions,
never source content) inline.status: unsupported), never silently; a re-import failure is reported as a fail
verdict rather than a 500. app/export_roundtrip.py holds the composition; the verdict
vocabulary is the 1.7 matrix's, so Studio results reconcile with the published grid for
corpus entries.POST /v1/tenants/{tenant}/import/bundle-inventory unpacks the candidate through the same
MFI-29.1 archive intake the commit uses and runs the same IXH-2.1 pre-flight the quality step
already ran (so it rides that cached run rather than parsing the bundle twice), then returns per
file: its role (entry-point / dependency / unreferenced / ignored — always with the reason —
/ unreadable), its verdict plus the parse diagnostic naming it, its resolved
import/include edges and incoming references, and the canonical entities it appears to
contribute.provided instead of being reported missing.app/intake_bundle_graph.py holds the pure half: a per-suffix directive table (proto, Thrift,
FlatBuffers, Cap'n Proto, TypeSpec, GraphQL, RAML, Avro IDL, JSON/YAML $ref, XSD/WSDL/EDMX),
include-root resolution, role classification, and the declaration-scan attribution — whose
method is carried on the response (attribution) so its evidence quality is never overstated
as parser provenance.resolve_fileset_root decides
with; overriding is a plain re-run against archive_root. An ambiguous root and a failed parse
both still return the complete file list.unpack_archive_members(ignored=…)),
and its skip normalisation is fixed: lstrip("./") stripped characters, so .git/ internals
and a top-level .DS_Store were never actually being skipped despite both rules existing.apiome.quality_rank_observations (V239) records one
row every time a grade is produced — an import pre-flight, a committed import, an export
pre-flight ranking, a delivery gate decision — keyed by tenant, format, adapter and
style-guide version (the guide's content fingerprint, which is what actually moves a
score), plus the policy version, the gate outcome, and the severity tally.intake.* findings
(an external $ref never resolved or refused) are adapter-attributable, everything else is
spec-attributable and classed by the rule id's namespace. An unrecognised rule is
spec-attributable by construction — the opposite default would blame the adapter for every
new rule anybody adds. The adapter's declared parser limits
(import_preview_manifest.KNOWN_PARSER_LIMITS) ride alongside as a separate count and are
never folded into the finding tallies.GET /v1/lint/workspace/quality-ranks groups the window by (scope, format)
and returns each group's grade distribution, average score, drift (scoreDelta), outcome
tally, attribution split, style-guide versions, and a per-day point series. A day with no
observation is a gap (averageScore: null), never a zero. Rendered in the lint workspace
as a new Quality ranks tab with a selectable 7/30/90/180-day window.truncated rather than dropping rows silently; and the series is pruned
by APIOME_QUALITY_RANK_RETENTION_DAYS (default 180) on the IXH-6.3 retention sweep tick,
which is already the deployment's retention worker.origin
(hand-authored | derived | captured, absent means hand-authored), source_url (the
upstream document a derived entry came from) and anonymization (how a captured payload was
scrubbed before commit). Both loaders expose them — corpus_loader.CorpusEntry.effective_origin
plus a load_corpus(origin=…) filter, and the same in apiome-ui/lib/corpus/corpus.ts.scripts/check_corpus_provenance.py is a stdlib-only CI check: every
entry with a non-empty source must declare a license, that license must be on a reviewed
SPDX allowlist (copyleft, share-alike and non-commercial terms fail), origin and source
must agree, derived entries must link their upstream, and captured entries must carry an
anonymization statement under a license the contributor can actually grant. It runs as its own
lightweight workflow (.github/workflows/corpus-provenance.yml) so a manifest-only pull
request is gated even though the corpus lives under apiome-ui/.docs/CORPUS_CONTRIBUTOR_GUIDE.md documents the tiers and the six-rung ladder,
every manifest field, the licensing rules (including what to do when the upstream license is
not acceptable — reconstruct, do not vendor), the anonymization rule for captured payloads,
the end-to-end add-an-example workflow, and the reviewer checklist. The generated examples
README links it and now publishes the corpus's licensing bill of materials by origin.tests/test_corpus_provenance.py fires every rule against a purpose-built bad
entry, asserts the committed corpus is clean, and pins the guide/README linkage.scripts/generate_scale_corpus.py is a committed spec of six large,
deterministic, valid documents — one per paradigm and one for the mainframe half: a
550-path OpenAPI 3.1 spec, a 1500-method OpenRPC service, a CloudEvents envelope with a
15000-attribute payload, a 900-type Avro snapshot, a 1500-transaction-set X12 interchange,
and a 7500-item COBOL copybook. The bytes are built at test time, so repository size stays
flat (the IXH-1.4 rule). Every fixture stays under the 10 MiB intake ceiling and uses an
adapter with no external toolchain, so none of them can silently skip.tests/scale_benchmark.py drives each fixture through
parse → normalize → fingerprint → lint → persist and
load-source → analyze-fidelity → emit → validate → package, calling the same functions
the running pipelines call, and records per-stage wall-clock plus peak allocation
(tracemalloc, which is attributable per stage) alongside the process peak RSS. The two
database-straddling stages are measured up to the row write — persist is the source
capture and secret scrub, load-source the full re-parse/re-normalize — because a
Postgres round-trip's cost cannot be attributed to a code change.tests/scale/scale_budgets.json is the one
committed baseline, carrying the margins, the noise floors, and the machine it was measured
on. A stage fails only when it is both over baseline × margin and over an absolute
floor, so a 2 ms stage tripling is ignored while a 30 % slowdown of a two-second stage
fails. SCALE_REGRESSION_MARGIN / SCALE_MEMORY_MARGIN override per run, and absolute
ceilings (180 s, 1 GiB per stage) fail regardless of any baseline. Refresh with
pytest tests/test_scale_corpus.py --update-scale-budgets.tests/test_scale_corpus.py runs only under
--scale / RUN_SCALE_SUITE=1; .github/workflows/apiome-rest-scale.yml runs it weekly
and on dispatch, uploading reports/scale-benchmark.json — a machine-readable per-stage
report with each budget, ratio, and the environment measured in. tests/test_scale_harness.py
runs on every PR and keeps the spec, the baseline, and the comparison rules honest between
scheduled runs.docs/scale_benchmarks.md.initial cannot dodge the guardrail, and the check runs after the
allowBreaking gate — a publisher who opted into shipping breaking changes is exactly the
one it exists for.style_guides.breaking_publish_policy (migration V237) is
off / warn (default) / block, resolved through the GOV-1.4 chain (project → tenant →
default) and editable at PUT …/style-guides/{tenantSlug}/{guideId}/policy beside the
CLX-1.3 gates. Under block, publish is refused with 422 carrying the full assessment;
force-publish (skipPublishChecks + reason) gets past it exactly as it does for style-guide
errors, per GOV-2.5. The level is frozen into each GOV-1.6 guide revision, so escalating to
block is auditable history.GET /v1/versions/{tenantSlug}/{projectId}/{versionRecordId}/breaking-publish-guardrail
returns the same payload read-only: status, the breaking changes (capped at 50, with
truncated and a true breakingCount), majorBumped, and the recommendedVersion a
compliant bump would use.null, which warns but never blocks, since that tenant
has not committed a semver violation. Every fault (unbuildable spec, missing baseline, DB
error, unknown policy value) degrades to status: unavailable or the warn default: a
guardrail that failed closed on its own bugs would be worse than the violation it guards
against.version.breaking_publish_guardrail workflow
audit row with action: warned | forced, the force reason, and the full assessment. The
forced case is assessed after publish, since skipPublishChecks skips the prechecks
wholesale — precisely the case where the trail matters most.docs/breaking_publish_guardrail.md; 50 tests in
test_breaking_publish_guardrail.py plus guide-policy and revision-snapshot coverage.apiome.style_guide_revisions (migration V236)
is append-only and write-once (the shared V128 UPDATE-forbid trigger). Creating a guide,
renaming it, saving the rule catalog, saving the custom-rules YAML, or changing policy gates
each append one row carrying the guide's whole state — name, description, external lint
profile, every rule row (enable flag, severity, custom definition) and the draft gates —
plus a changeKind and the actor. A save that changed nothing appends nothing: the two
fingerprints on each revision separate "the rules moved" (contentFingerprint) from
"anything moved" (snapshotFingerprint). Assigning a guide changes no content and is
therefore an audit event, not a revision.GET …/{versionRecordId}/lint now returns
guideRevisionId alongside guideId / guideName, and every immutable lint evidence row
(lint_evidence_runs.guide_revision_id) records the same pin at capture time, so
import-time scores are as explainable as live recomputes. The pin is exact rather than
heuristic: a revision's contentFingerprint is produced by the same function that stamps
the compiled guide's fingerprint, so matching content is provably the same ruleset.GET /v1/style-guides/{tenantSlug}/{guideId}/revisions
lists the history newest-first with rule rollups; GET …/revisions/{revisionId} returns the
frozen rules and gates behind any past score. Both are readable by any tenant member —
compliance review is not an admin-only activity. Guides that predate this feature are
captured on first read/edit/lint, and every edit path captures the pre-edit state first,
so what an edit replaced is preserved rather than lost.style_guide.created, .updated, .deleted,
.rules_updated, .custom_rules_updated, .policy_updated, .assigned and .unassigned
append to the existing hash-chained apiome.access_audit ledger — one ledger for a
reviewer to read — filterable with GET /v1/access/{tenantSlug}/audit?filter=styleGuide.
Only changes that actually happened are recorded, and history/audit capture is best-effort
by contract: a ledger or capture failure can never fail the guide change it describes.docs/guide/style-guide-revisions.md; 48 tests across
test_style_guide_revisions.py and test_style_guide_routes.py..spectral.yaml holding years of org
standards. Re-authoring every rule by hand was a real switching cost, so
POST /v1/lint/custom-rules/import now reads that file — pasted/uploaded via content, or
fetched from a url through the existing SSRF-guarded ingestion boundary (256 KiB cap,
redirects re-validated) — and translates it into Apiome governance state. Nothing is
persisted: the response is a review-then-store payload whose yaml is exactly what
PUT /v1/style-guides/{tenantSlug}/{guideId}/custom-rules accepts and whose builtinRules
are exactly what PUT …/rules accepts.
rules.<id> entry of the source lands in exactly
one outcome, so the report accounts for the whole document: builtin (resolved onto the
GOV-1.2 rule catalog via the extends: spectral:oas map — info-description,
operation-description, and the four valid-*-example rules), custom (translated into
the GOV-1.3 DSL and validated by that module, so anything emitted is guaranteed storable
and evaluable), or unsupported.js_function,
unsupported_function (Spectral's schema / alphabetical / xor / falsy /
unreferencedReusableObject), unsupported_extends, unmapped_builtin, unknown_rule,
unsupported_severity, invalid_definition, malformed_rule, unknown_alias,
rule_limit — each with a human detail and, for DSL rejections, the pointer to the
offending node (rules.my-rule.then.functionOptions.separator).notes: a dropped message template or formats restriction, resolved: false,
severity: hint folded to info, a normalized rule id (an id that would shadow a built-in
becomes imported.<id>). Rules the source turned off (off / false /
recommended: false) are reported with enabled: false and deliberately left out of the
emitted YAML, so applying an import never silently switches a rule on. Document-level
notes cover ignored overrides, parserOptions, and unknown top-level keys.error/warn/info/hint/off,
booleans, numeric DiagnosticSeverity including YAML 1.1 resolving bare off to false),
extends as a scalar/list/[target, modifier] pair (off inherits everything disabled),
and simple aliases (including #Alias.suffix expansion) all resolve.tests/fixtures/spectral/zalando-style.spectral.yaml
— a 27-rule Zalando-style ruleset — imports at 81.5% coverage, above the ≥70% bar, and
its output round-trips through POST /v1/lint/custom-rules/validate. Documented in
docs/guide/spectral-import.md; 84 tests across test_spectral_import.py and
test_spectral_import_routes.py.apiome.versions (protocol,
source_format), backed by that migration's partial facet indexes.
GET /v1/browse/tenants and
GET /v1/browse/tenants/{slug}/projects accept protocol (the canonical ApiParadigm:
rest, rpc, event, graph, data_schema, agent) and format (the specific source
format key an adapter recorded at import: openapi-3.1, protobuf, graphql, …). Matching is
case- and punctuation-insensitive — data-schema, event-driven and graphql all resolve —
and an unrecognised value narrows to nothing rather than erroring, the same contract the
existing search/domain filters have. The two axes compose with AND, and an entry matches
when any of its listed versions carries the value.facets block — {protocols, formats}, each a
list of {value, label, count}. Counts honour the listing's other filters (search,
domain) but deliberately ignore the facet selection itself, so a chip row always answers
"what else could I pick" instead of collapsing to what is already selected. Protocols come
back in canonical paradigm order; formats by descending count, ties broken by key.protocols / formats
(the distinct values across its listed versions) and every version row carries its own
protocol / source_format, so a listing stays readable once a facet has narrowed it.app/browse_facets.py owns the normalization and the
labelling; format labels come from the import-source registry (so a newly registered adapter
labels its own chips) with a versioned-key rule that keeps openapi-3.0, openapi-3.1 and
swagger-2.0 distinguishable. An unknown key still renders — as itself.overwrite lets the refresh supersede
the hand edit — the divergence is still detected and reported, it just does not stop the
refresh; hold-for-review (the default) skips the refresh and flags the file diverged;
new-branch leaves the current version untouched and lands the refresh on a side branch
so neither the edit nor the upstream change is lost.tenant_repositories.refresh_conflict_policy is
NOT NULL DEFAULT 'hold-for-review', so every existing repository keeps the behaviour it
has today. Opting into a policy that can lose work not held in the repository is an
explicit act, never a migration side-effect — and every degradation path (an unrecognised
token, a missing row, a blank value) falls back toward that same safe default rather than
failing a refresh.apiome.repository_conflict_policy_override holds one row per file that deviates, keyed on
the same (repository_id, branch, path) lineage tuple as RAR-1.1's repository_import_spec.
A file with no row inherits its repository's policy, so the table stays tiny and clearing an
override is a delete — the file then follows whatever the repository says next, not a
frozen copy of today's setting. The table is separate from tenant_repository_files
deliberately: that one is rewritten by every scan, and policy must outlive the scan index.app/repository_conflict_policy.py resolves
per-file → repository → default, runs the RAR-4.4 guard under the resolved policy, and
returns a ConflictOutcome carrying the action (apply / hold / new-branch), whether
a manual edit was detected, the reason code, the policy and where it came from. Branch
names for the new-branch policy are deterministic
(apiome-refresh/<branch>/<file stem>-<short sha>), so a refresh that runs twice for one
commit targets one branch rather than accumulating near-duplicates. Like RAR-4.1–4.4 the
module is pure and DB-free; acting on the outcome remains the EPIC-4 dispatcher's job.GET/PUT /v1/tenants/{slug}/repositories/{id}/conflict-policy reads and sets the
repository policy; PUT …/conflict-policy/file sets an override, or clears it with
"policy": null. Both the read and every mutation return the same projection — policy,
default, accepted tokens and overrides — so a settings panel cannot drift from stored
state. An unrecognised token is a 400 that lists what is accepted, not a 500 from the
column's CHECK. The repository policy is also patchable through the existing dashboard
PATCH /v1/tenants/{slug}/repositories/{id} as refreshConflictPolicy.docs/repository_conflict_policy.md.POST /v1/repositories/webhook/{provider} is the one repository route with no bearer token,
so the HMAC signature is its only authentication. That check is sound and it is reached by
anyone who can open a socket: every unsigned POST on the internet buys a subscription
lookup, a constant-time comparison against a real secret, and a ledger row. The allowlist
filters on the source address before any of that runs.
403 and is never verified. The guard runs in the route,
ahead of ingest_webhook_delivery, so a refused source never reaches verify_signature
at all — the ticket's defense-in-depth requirement, and the reason this is not a branch
inside the dispatcher. The response body says only that the source was refused; naming the
allowlist, the tenant or the matched range would turn the endpoint into a probe for the
deployment's network policy.hooks array from
api.github.com/meta and Bitbucket's entries from ip-ranges.atlassian.com are refreshed
on a daily cadence into apiome.webhook_provider_ip_range, shared across replicas so
every process filters on the same list. Due-ness is measured from the last success, so a
provider whose endpoint is failing is retried on the next hourly tick rather than
tomorrow. GitLab.com publishes no machine-readable list; its ranges come from
APIOME_REPOSITORY_WEBHOOK_IP_RANGES_GITLAB, and the same setting exists for the other
two providers for self-hosted instances.enforcement_enabled = false on
apiome.tenant_webhook_ip_policy turns the filter off for one tenant's repositories;
setting it, and adding a range, both require a signed-in tenant administrator (API keys
are refused) and both write to apiome.workflow_audit. Disabling without a stated reason
is a 400.APIOME_REPOSITORY_WEBHOOK_IP_ALLOWLIST), so an upgrade changes nothing. A provider with
no cached ranges allows and logs rather than rejecting everything;
..._IP_ALLOWLIST_STRICT flips that to fail-closed. An empty provider fetch is treated as
a failure and leaves the previous cache standing. An unidentifiable client address blocks
— unless the owning tenant has bypassed enforcement, which is exactly the escape hatch
that case calls for.X-Forwarded-For is worth what the deployment says it is.
APIOME_REPOSITORY_WEBHOOK_TRUSTED_PROXY_HOPS (default 0) decides how many hops in to
read; at 0 the header is ignored entirely, since honouring it unverified would let any
caller name its own source address. A header shorter than the configured chain is refused
rather than guessed at.GET|POST|PATCH|DELETE|PUT /v1/tenants/{slug}/repository-webhook-ip-allowlist[...] back
the admin panel. The read needs only import-view permission — seeing the filter is how
anyone diagnoses "our webhooks stopped" — while every mutation needs the admin role. Every
mutation answers with the whole allowlist, so a panel can never drift from what was
stored.apiome.repository_webhook_event ledger with the
rejected outcome and an ip-not-allowed reason, and are audited per owning tenant as
repository.webhook.ip_blocked — which carries the repository. prefix, so it appears in
the REPO-7.5 compliance export with no further wiring.GET /v1/tenants/{slug}/repository-audit-export?from=&to=&format=csv|json streams every
repository.* row of apiome.workflow_audit (refresh cycles, webhook registrations /
deliveries / secret rotations, external-ref fetches, …) in the inclusive created_at
range, oldest first, served as an attachment with a range-stamped filename
(repository-audit-export_20260101-20260731.csv).(created_at, id) keyset
cursor in 1,000-row batches, so an export far beyond 10k rows holds one batch in memory
and every batch costs the same — no OFFSET cliff, and rows appended mid-export cannot
shift between batches.detail
JSON-encoded in its cell; JSON is a single document — an export metadata envelope, the
entries array streamed element by element, and a trailing rowCount — that only parses
when the download ran to completion, so a truncated artifact is detectably incomplete
instead of silently short.repository.audit_exported row to the same ledger: success with the exact row count on
completion, failure with the partial count when the stream errors or the client
disconnects mid-download. Because the action carries the repository. prefix, each
export shows up in the next one. Recording is best-effort, so audit bookkeeping can never
break the download it describes.apiome.workflow_audit is reused unchanged.apiome.repository_quota_window, V233):
polls, polls_deferred and files_deferred bucket hourly (matching the REPO-4.6 quota
window); scans and bytes_scanned bucket daily. Aggregates, not events — a workspace
polling 600 times an hour costs one row an hour, not 600.polls says how much refreshing happened;
polls_deferred / files_deferred say how much the quota pushed into a later window.
Folding them together would erase the one signal the dashboard exists to show.(tenant_id, metric, window_start), so two
replicas sweeping the same tenant in the same window converge on one row rather than each
creating their own and halving every subsequent read.GET /v1/tenants/{slug}/repository-quota-telemetry?days=7 returns the trailing series
alongside the tenant's current quota position, so a dashboard renders "42 of 600 used this
hour" and "here is the last week" from one request. Every metric is present and zero-filled
across the whole range, so a workspace that has never been deferred sees a flat line rather
than a missing panel. A counter read that fails comes back available: false with zeros —
the flag is what stops "we could not read this" being shown as "nothing happened".APIOME_REPOSITORY_QUOTA_WINDOW_RETENTION_DAYS (default 120, comfortably longer than the
90-day maximum range the API serves). 0 keeps them forever.repository.refresh.* namespace subscribers
already route on: auto_paused (scheduled refresh has stopped and must be resumed by hand),
breaking_change (a sync produced a version whose change report classifies as breaking), and
repeated_failures (the warning shot — failing repeatedly but not paused yet).apiome.repository_notification_preference holds
exceptions, not enrolments: a repository with no rows is subscribed to everything, and only an
explicit enabled = FALSE mutes an event, so a partial preference set fails open. A
preference read that errors mutes nothing — failing closed would silence a repository during
the incident that broke the read.apiome.repository_notification_throttle, so the decision and
the timestamp write are the same statement and two sweep workers racing on one repository
cannot both win. A losing claim bumps suppressed_count instead, which is how "quiet because
nothing happened" is later told apart from "quiet because we muffled 400 of them". A tenant
with no channels does not burn its hourly slot.text/blocks message (Slack rejects a body without
text), every other endpoint receives the structured JSON. One dead channel never takes the
rest of the fan-out down with it.GET/PUT /v1/tenants/{slug}/repositories/{id}/notification-preferences report and set the
opt-outs. The read always lists every event type, with a one-sentence description of what
muting it would cost and the throttle state for that pair. The write is partial (events it
does not mention keep their state) and rejects unknown or repeated event types with a 400
rather than returning 200 for an opt-out that mutes nothing.healthy / warnings / error is rolled up from the scan
success rate over the last 30 days, the count of discovered specs on the default branch whose
REPO-2.8 quality attempt errored or could not parse, and the health of the linked account's
access token (REPO-7.4). Below 50% of scans succeeding is an error, below 90% a warnings;
parse errors are a warnings until ten of them, at which point the repository is not usable
as an import source; a disconnected account, a missing token or an expired one is an error,
and a token expiring within seven days is a warnings.warnings. A repository Apiome can no longer
authenticate to never reads as healthy, however spotless its scan history. Every token factor
is emitted at warnings-or-worse and the roll-up clamps as well, so the guarantee survives a
future factor being added at the wrong level.primary_factor is the most recently observed factor, which is what the
badge tooltip leads with; the full list is ordered most severe first. A standing condition
with no event behind it ("this token expires soon") never displaces something that actually
happened.healthy rather than
manufacturing an alarm out of missing data. Public-URL repositories are read anonymously and
so always have perfect token health.Database.get_repository_health_signals answers the
whole batch with two correlated laterals, and V231 indexes both: (repository_id, created_at DESC) INCLUDE (status, finished_at) on the scan queue turns the trailing window into a
bounded range scan, and a partial index on the file table holding only rows that actually
failed to parse — empty on a healthy monorepo. The migration adds indexes only.GET /v1/tenants/{slug}/repositories and GET /v1/tenants/{slug}/repositories/{id} (and the
PATCH / refresh-resume reads that return the same record) gain a health object.GET /v1/tenants/{slug}/repository-files. One tenant-wide, server-paginated listing of
every discovered spec across every registered repository. Free-text q matches the file
path, its detected kind, the repository's full name and the mapped project's name; format,
repository_id, project_id and status narrow it further; sort orders by repository,
path, format, status or recent activity. Search, filtering, ordering and pagination all
evaluate in SQL, so the response carries only the requested page.needs_attention (quality
scoring errored, or the last scan left external $refs unresolved), imported, mapped
(bound to a project, no import yet) or discovered, in that precedence. The status is
projected and filtered by the same SQL expression, so a row can never be listed under a
value it cannot be filtered by.include_facets=true returns the filter dropdown options — formats,
statuses, repositories and projects, each with a catalog-wide count. Facets are computed
over the whole catalog rather than the filtered page, so picking one filter never hides the
others. The catalog page requests them once on mount.node_modules, vendor, .git) and
dot-directories are always excluded; only each repository's default branch is listed unless
all_branches=true; only classified spec types unless importable_only=false.pg_trgm GIN index makes the substring search
indexable, and a (repository_id, branch, path, created_at DESC) index answers the
latest-import lookup with one backwards scan. The trigram block degrades to a notice where
the migration role cannot install contrib extensions — the catalog stays correct, just
sequential.apiome.api_workflows and
apiome.api_workflow_steps hang off the version's api_artifacts row like every other
canonical child, so a re-import replaces the previous orchestration instead of accumulating
duplicates. Each workflows[] entry becomes one workflow row (workflowId, summary,
description, inputs, outputs) plus N step rows in source order.operationRef resolution. A step that points at an OpenAPI operation imported in the same
scan resolves to that internal path_operation id. "The same scan" is concrete: with git
provenance it is every project repository_import_spec links to the same repository and
branch; otherwise it is the importing project. Every reference spelling in the wild is
handled — operationId, $sourceDescriptions.<name>.<operationId>, an operationRef
JSON-pointer (…#/paths/~1pets~1{petId}/get), and Arazzo 1.0.0's operationPath route
pointer, which resolves only when the route carries exactly one operation.resolution_reason (unknown-operation, ambiguous-operation,
no-operation-target, …) plus a human-readable warning. A step that calls a sibling workflow
is not_applicable rather than "unknown"; a step that cannot be read at all is isolated as
parse_error and its siblings still import. Workflow persistence is an enrichment over the
catalog item, so a failure there never fails an import whose source bytes are already stored.parameters, successCriteria, onFailure, outputs and
dependsOn are stored exactly as written — Arazzo's runtime-expression grammar
($response.body#/id, $steps.foo.outputs.bar) is never re-parsed, which keeps round-trip
honest.tests/fixtures/arazzo carries the OAI example
documents verbatim (pet-coupons, LoginAndRetrievePets, oauth); they round-trip
normalize → map → persist → load with identical workflows and steps.parse → normalize → lint — which for OpenAPI is the native
path/schema linter (schema_lint.lint_openapi_spec: the PATH-QUALITY and SCHEMA-QUALITY rule
groups) and for every other format the canonical-model rule packs behind ImportSource.lint.
A repository file and an imported revision therefore land on one comparable scale, and a rule
added to either engine shows up here for free.unknown_spec files — no detected_kind, or a generic container
kind like json-candidate on a package.json — are never scored, selected by the same
importable predicate the Files browser filters on. A classified format with no adapter yet
(Prisma, SQL DDL, DBML) is skipped for its own distinct, labelled reason.apiome.tenant_repository_files gains quality_score,
quality_grade, quality_status (scored | skipped | error), quality_reason,
quality_scored_at and quality_scored_blob_sha (V222). All nullable, so every
already-indexed repository reads as "not scored yet" and no re-scan is required.repository_quality_sweep.process_repository_spec_quality_batch), not inside the REPO-2.5
tree walk, so a monorepo scan keeps its current cost. Each tick claims at most
APIOME_REPOSITORY_QUALITY_BATCH_SIZE (default 10) due files every
APIOME_REPOSITORY_QUALITY_INTERVAL seconds (default 30); set
APIOME_REPOSITORY_QUALITY_SCORING=false to disable it entirely.GET /v1/tenants/{slug}/repositories/{id}/files returns quality_score, quality_grade,
quality_status and quality_reason per row, and the Repository detail Files tab renders
them in a new Quality column (REPO-6.2).recursive=1 GitHub Trees call, buffered every blob in memory, and turned
GitHub's own truncated: true size signal into the hard failure "repository too large for
this scan pass". The walk is now bounded and resumable.
walk_github_tree_in_chunks hands entries to its sink in batches of
at most 1000 (repository_scan_budget.MAX_WALK_CHUNK_SIZE, capped regardless of
APIOME_REPOSITORY_SCAN_CHUNK_SIZE), written through the new upserting
Database.append_tenant_repository_files instead of one whole-branch statement.truncated recursive response now switches the walk
to a breadth-first per-directory descent over the non-recursive Trees API, so only a queue
of unvisited directories is ever held in memory.tenants.repository_scan_budget_seconds (default 300 =
5 min) bounds one scan pass, clamped at read time into
[APIOME_REPOSITORY_SCAN_BUDGET_MIN, APIOME_REPOSITORY_SCAN_BUDGET_MAX]. A pass that spends
its budget stores its position and comes back incomplete rather than being killed.apiome.tenant_repository_scan_cursors holds one cursor per
(repository, branch) — the pinned tree SHA, the RAR-2.1 branch-tip anchors, the walk mode and
the pending sub-tree queue. A paused pass, or one interrupted by a transient provider failure
(network error, 429, 5xx), re-queues its scan job instead of failing it, and the next sweep
tick continues from the cursor. The tree SHA is pinned so a resumed pass keeps indexing the
same snapshot even if the branch moves.COALESCE(requeued_at, created_at), so a
monorepo needing twenty passes yields to other repositories between them instead of owning
the scan worker for the whole walk.number from decimal's base chain
showed "No types reference this primitive yet" while decimal plainly referenced it.
apiome.primitives.refs records only a type's outgoing edges, so nothing ever answered
the reverse question; the field was declared on the detail page and never populated.
GET /v1/primitives/{tenant}/{id} now returns dependents, the reverse index built by
scanning the visible types' edge lists for the viewed type's $id
(Database.get_dependent_primitives).
resolved_target (the form V218 normalized to), so a
dependent is found however its relative $ref was written, and an edge still flagged
unresolved by a stale resolver run is still listed — the target exists, so the
dependency is real.ref_location_label over the new iter_ref_locations walk): money shows up under
decimal as amount, while decimal under number carries no property because the
$ref is the whole type. Read scope is unchanged — system-core ∪ the caller's own
(#3453) — and per-tenant seeded copies of a core dependent collapse to one row.PrimitiveSchema.dependents added; existing fields unchanged).docs/guide/catalog-format-details.md (Format details tab: status vocabulary,
value-visibility/redaction, analysis bounds, X12 and copybook inspector boundaries, the
absence-category table) and docs/guide/convert-to-openapi.md (conversion walkthrough:
projection-graph legend, status and reason-code vocabulary with remediations, safe
defaults, acknowledgement gating, historical-vs-fresh evidence, CLI/REST surfaces), with
authoritative X12 and IBM COBOL references.
tests/test_cpdo_docs_guide.py couples the prose to the code registries: every
analysis status/reason, value-visibility level, conversion status, projection reason
code, and absence-category label must appear in the guides, the required primary
references must stay linked, and every external link must be https. The UI-side twin
(apiome-ui/tests/cpdo-guide-terminology.test.ts) holds the guides to the exact labels
and symbols the UI renders.