stack/docs/requirements/api-artifacts.md

# API Contract Artifacts Contract (S2 contract 9)

Status: DRAFT — awaiting ratification (webui-audit S2, contract 9 of 9).
Authority: `docs/API/README.md` declares the single API documentation
boundary: `docs/API/OPENAPI.yaml` as the canonical machine-readable
HTTP/WebSocket contract and `docs/API/ENDPOINTS.md` as the
human-readable endpoint, authentication, permission, and error index —
both declared, neither present (the webui-audit REPORT's prerequisite
9). `docs/SITEMAP.md` records that canonical scope requires maintainer
approval; ratification of this contract by the repository maintainer
supplies that approval for these two artifacts. Contract 5
(`tool-gateway-mapping.md`) §4 binds the per-operation
request/result/error/audit envelope; this contract binds only how the
two artifacts are produced, what they must cover, and how they are
kept true.

Revision 2 (luna review F1–F5): the generation model now defines its
complete input — a declared route-metadata layer every production
route must carry, with the generator failing closed on any route
lacking extractable metadata, and the migration of today's local-DTO,
inline-typed, and raw-handler routes named as implementing-PR scope
(F1). The §7.2 inventory is closed over the real surface: raw
framework mounts, delegated surfaces, conditional/tier-gated
controllers, SSE, and Socket.IO events in both directions, with an
explicit delegation/exclusion list (F2). The `ENDPOINTS.md`
no-duplication rule is reattributed as a new disclosed policy with a
structured entry format and a mechanical checker (F3). Witnesses are
added or made executable for 3.1 validity, family coverage in
`ENDPOINTS.md`, per-entry required content, and the retirement
equivalence algorithm (F4). §8 discloses every untraced binding rule,
and the SITEMAP approval claim is restated in the sitemap's own terms
(F5).

Revision 3 (luna re-review residuals + F6): the route-metadata layer
is now a defined closed record with a per-field completeness
predicate, and "production route" is a defined, decidable term (F1).
The §7.2 scans cover all production source with a named
registration-primitive list, a defined deployment-profile set, and a
literal-event-name rule backed by one typed event registry (F2).
`ENDPOINTS.md` gets an exact entry grammar and a repository checker
script with defined reject rules (F3). §7.4 enumerates its
normalization and comparison rules, defines covering-entry selection
and the legacy-derivation rule, and §7.6 pins a named validator (F4).
§8 discloses the §7 witness machinery itself (F5). Delegated surfaces
get a machine-checkable delegation allowlist with a below-prefix
boundary check (F6).

This contract binds the artifact definitions (§2), the production
model (§3), coverage obligations (§4), legacy migration (§5), phase
timing (§6), witnesses (§7), and disclosed drafting additions (§8).
Operation semantics stay with contract 5 and the owning S2 contracts;
documentation placement rules stay with the docs atlas
(`docs/README.md`).

## 1. Definitions

1. **The artifacts**: `docs/API/OPENAPI.yaml` and
   `docs/API/ENDPOINTS.md`, exactly as declared by `docs/API/README.md`.
2. **Coverage**: the set of Gateway HTTP routes (however registered),
   SSE routes, and Socket.IO events (both directions) the artifacts
   describe.
3. **Drift**: any difference between an artifact and the production
   surface it documents — an undocumented live route or event, a
   documented phantom, or a divergent schema/auth/error description.
4. **Delegated surface**: a mounted path prefix whose request handling
   is delegated wholesale to an embedded third-party engine (for
   example an auth engine's own route tree): the Gateway registers the
   mount; the engine defines the routes. Only a prefix listed in the
   §4.4 delegation allowlist is a delegated surface; any other prefix
   is ordinary surface, documented route-by-route.
5. **Production route**: any HTTP or SSE route, or Socket.IO event
   (either direction), registered by production source (`apps/` and
   `packages/`, tests excluded) under ANY deployment profile (§4.5),
   excluding only entries on the §4.1 exclusion list and routes below
   a §4.4 delegated prefix. The term is decidable: a route is a
   production route iff the §7.2 inventory emits it, and the §7.2
   scan definition — not intent — is the boundary.
6. **Route metadata record**: the closed per-route generator input
   (§3.1). Its fields, all REQUIRED: a unique operation id; the HTTP
   method and path template (or the SSE marker, or the Socket.IO
   event name and direction); the request schema reference (or an
   explicit no-body marker); the response map — every documented
   status code mapped to a schema reference, with at least one
   success entry; the authentication requirement, one value from the
   closed auth-class enumeration the implementing PR declares in the
   shared types package; the permission rule reference (owning
   contract plus rule identifier); and the error-code set, drawn from
   the contract 5 §4.2 closed taxonomy. **Completeness predicate**:
   every field present AND every reference resolvable, evaluated per
   field; a violation names the route and the exact failing field.

## 2. Artifact contract

1. **`OPENAPI.yaml`** is one file, valid OpenAPI 3.1 (witness §7.6),
   and the canonical machine-readable contract for the Gateway's HTTP
   surface. Socket.IO events, which OpenAPI cannot express natively,
   are documented in `ENDPOINTS.md` and referenced from the OpenAPI
   description block; inventing a pseudo-path encoding for them inside
   `OPENAPI.yaml` is non-conformant.
2. **`ENDPOINTS.md`** is the human index, in a structured entry
   format: one entry per endpoint family, carrying (a) the family's
   behavior summary, (b) its operations referenced by `operationId`
   link into `OPENAPI.yaml` — never by restated definition, (c) the
   authentication requirement, (d) the permission/authorization rule
   naming the owning contract (contract 2 for chain authorization, the
   SOT for workspace membership), (e) error semantics including the
   contract 5 §4.2 taxonomy, and (f) Socket.IO event entries (both
   directions) for event families. `ENDPOINTS.md` MUST NOT contain
   request/response schema definitions for any operation that exists
   in `OPENAPI.yaml` (mechanical rule: no `requestBody`/`responses`/
   schema-fragment blocks for such operations — witness §7.5). This
   no-duplication rule and the entry format are new policy disclosed
   in §8 (the `docs/API/README.md` boundary as written binds guide
   books, not `ENDPOINTS.md` itself).
3. Both artifacts are committed repository files, reviewed in PRs like
   any contract text; neither is a build output that exists only in CI.

## 3. Production model

1. **Generation (per the ruling).** `OPENAPI.yaml` is GENERATED from
   the Gateway source by a deterministic repository script whose
   input is the **route metadata record** (§1.6) of every production
   route (§1.5): route decorators plus typed request/response schemas
   (the contract 5 §4.1 shared DTOs where the operation is a mapped
   tool family; declared per-route schemas elsewhere), each record
   satisfying the §1.6 completeness predicate. **The generator fails
   closed:** it first computes the §7.2 inventory's route set, then
   requires a complete metadata record for every route in it; a
   missing record, a missing field, or an unresolvable reference is a
   generation error naming the route and field — never a silently
   omitted or partially emitted operation. Because the route set
   comes from the inventory and completeness is the per-field §1.6
   predicate, a byte-stable but incomplete artifact cannot pass: an
   unrecorded route fails generation, and a recorded route emits
   every §1.6 field into its OpenAPI operation (operation id,
   schemas, per-status responses, security requirement, and the
   permission reference and error-code set as declared extension
   fields). Today's local-DTO, inline-typed, and raw-handler routes
   therefore migrate to complete metadata records in the implementing
   PR. The generated output is committed, and CI regenerates and
   byte-compares it (§7.1). Hand edits to `OPENAPI.yaml` are
   non-conformant — a description that cannot be expressed from
   source annotations goes into the annotations, or into
   `ENDPOINTS.md`.
2. **Normative direction.** Generation documents the code; it does not
   ratify it. The S2 contracts and their witnesses remain the
   normative gates on what the surface may be; the artifacts make the
   measured surface visible and machine-checkable. A generated
   description of a non-conformant route is drift evidence against
   that route's owning contract, not authority for it.
3. `ENDPOINTS.md` is hand-authored (its content — permission
   rationale, cross-contract links, event semantics — is judgment, not
   extraction), against the §7.2 coverage and §7.3 content witnesses.

## 4. Coverage obligations

1. **Closure over the real surface.** Coverage extends to every
   production route however registered: framework-decorated
   controllers and gateways AND raw framework mounts registered
   outside them (the bootstrap's own route/hook registrations), SSE
   routes, and conditionally registered (deployment-tier-gated)
   controllers — documented in the union, each conditional route
   marked with its condition. **Delegated surfaces** (§1.4) are
   documented as delegated-surface entries naming the mount, the
   delegating engine, and that engine's own contract — not
   re-documented route-by-route. **Socket.IO events are covered in
   both directions:** subscribed (inbound handler) events and
   server-emitted events. Test-only and development-only surfaces are
   excluded via an exclusion list that is explicit in the generation
   script and enumerated in `ENDPOINTS.md`, never implicit. The
   exclusion and delegation lists are new policy disclosed in §8.
2. Every documented operation carries: its authentication requirement;
   its authorization rule by reference to the owning contract; its
   error responses drawn from the contract 5 §4.2 closed taxonomy.
   Where contract 2's no-existence-oracle rule applies, the
   documentation shows authorization refusal and not-found as
   indistinguishable on the wire — documenting a distinguishing
   response there is a coverage defect, not a documentation style
   choice.
3. New surface ships documented: a PR that adds or changes a Gateway
   route or event lands with the regenerated `OPENAPI.yaml` and any
   needed `ENDPOINTS.md` entry in the same PR, enforced by the §7.1
   drift gate — there is no "docs to follow" state.
4. **Delegation allowlist.** The generation script contains one
   machine-readable delegation allowlist; each entry names: the mount
   prefix; the delegating engine package (name and version
   constraint); a reference to the engine's own route contract (the
   engine package's published API document); and the one production
   module that registers the mount. The §7.2 witness enforces the
   boundary: any route registration whose path falls under an
   allowlisted prefix but does not originate from that entry's named
   registration module fails the witness — an app-owned handler
   cannot hide under a delegated prefix. `ENDPOINTS.md`'s
   delegated-surface entries mirror the allowlist one-to-one.
5. **Deployment profiles.** The authoritative profile set is the
   closed deployment-tier enumeration in the Gateway's configuration
   schema (the same enumeration the conditional registrations branch
   on); the implementing PR names it. The inventory is evaluated once
   per profile and unioned; each conditional operation carries a
   declared condition extension field naming the profile(s) it exists
   in. A conditional branch on anything outside the named enumeration
   fails the §7.2 witness.
6. **Event-name discipline.** Every Socket.IO event name, in both
   directions, is a literal member of one exported typed event
   registry in the shared types package; emitting or subscribing with
   a dynamically constructed name, or through a helper that does not
   take its name from the registry, is non-conformant (§7.2 scans for
   non-registry names). The registry is the comparison target for the
   event inventory.

## 5. Legacy migration

1. `docs/openapi-tess.yaml` (17 paths, Tess-scoped) remains labeled a
   scoped legacy artifact until the consolidated `OPENAPI.yaml`
   demonstrably covers it: the `docs/API/README.md` retirement rule
   (verify paths, schemas, authentication, permissions, error
   behavior, and generated/client references) is binding, witnessed by
   §7.4's equivalence algorithm.
2. Retirement is deletion in a reviewed PR after the §7.4 witness
   passes; until then no consumer may treat the legacy artifact as
   canonical for anything beyond its own 17 paths. (The
   deletion-in-reviewed-PR form and the interim-consumer restriction
   are disclosed in §8.)

## 6. Phase timing

1. The artifacts, the metadata migration (§3.1), and the generation
   script are produced by an implementing PR after this contract is
   ratified; they are S4-phase platform work, not part of any S2
   ruling PR.
2. From the first commit of `OPENAPI.yaml` onward, the §7.1 drift gate
   is a required CI check on the integration trunk; the §4.3
   same-PR rule binds every subsequent surface-changing PR.
3. The build-first tool families (A5 ranks, contracts 1–3, 5, 8) are
   documented as they land, under the same rule — the roll-up query,
   for example, ships with its OpenAPI operation and its
   `ENDPOINTS.md` entry in its implementing PR.
4. The phase placement and rollout sequencing in this section are
   disclosed in §8.

## 7. Verification requirements

Binding on the implementing PRs; each witness names its commands,
scanned source roots, and compared files.

1. **Drift witness:** CI regenerates `OPENAPI.yaml` with the
   repository script and fails on any byte difference from the
   committed file; the witness proves it can fail by a control run
   against a mutated copy. Fail-closed controls (§3.1): one control
   per §1.6 field class — a fixture route with the whole record
   absent, and fixture routes each missing one field class (operation
   id, schema reference, response map, auth requirement, permission
   reference, error-code set) — each makes generation fail naming the
   route and field, not emit a partial document.
2. **Coverage witness:** an independent surface inventory — static
   enumeration over ALL production code in `apps/` and `packages/`,
   tests excluded (the A5 §1.2 inventory style), not limited to the
   bootstrap module — covering: framework-decorated controllers and
   gateways; every raw registration primitive of the HTTP framework
   (the implementing PR enumerates the primitive list — route, hook,
   middleware-mount, and plugin-registration calls — and the witness
   asserts the list against the framework's registration API surface)
   wherever it occurs, including plugins and middleware modules; SSE
   routes; conditional registrations evaluated per §4.5 profile and
   unioned; and delegated-surface mounts, with the §4.4 boundary
   check that nothing app-owned registers below an allowlisted
   prefix. The inventory equals the documented set in both
   directions: no undocumented live route, no documented phantom,
   each conditional operation carrying its §4.5 condition field, each
   delegated surface present exactly once. Socket.IO events are
   inventoried in both directions — inbound subscription handlers by
   handler scan, server-emitted events by emit-call scan — with the
   §4.6 registry as the comparison target and a scan failure on any
   non-literal or non-registry event name. Additionally, every HTTP
   route family in `OPENAPI.yaml` has an `ENDPOINTS.md` entry, and
   every `ENDPOINTS.md` operation reference resolves to an existing
   `operationId` — both directions, mechanical.
3. **Content and taxonomy witness:** every `ENDPOINTS.md` entry
   carries the §2.2 required fields — behavior, operation links,
   authentication requirement, owning-contract link, error semantics
   — presence-checked mechanically against the structured entry
   format; every error response documented in `OPENAPI.yaml` uses a
   code from the contract 5 §4.2 closed enums, and each family's
   documented codes exactly match the enum in the shared types
   package; where the no-oracle rule applies, the documented refusal
   and not-found responses are identical in code, status, and shape.
4. **Retirement witness:** before `docs/openapi-tess.yaml` is deleted,
   an automated comparison proves each of its 17 paths is covered by
   `OPENAPI.yaml` under this equivalence algorithm, exactly:
   (a) canonicalize both documents — dereference every `$ref` with
   cycle detection, delete the annotation-only keywords
   (`description`, `summary`, `example`, `examples`, `title`,
   `deprecated`), rename path-template parameters positionally,
   lowercase HTTP methods, then sort all object keys; (b) per legacy
   path: deep structural equality of the canonicalized request and
   response schemas, equality of the security/authentication
   requirement sets, and equality of the documented error-code sets —
   a legacy error-code set is DERIVED as the legacy operation's
   documented non-2xx status codes plus any error-code enum values in
   its response schemas; where the legacy document does not express a
   dimension at all (permissions), the comparison target is the live
   §1.6 metadata record of the covering route instead; (c) the
   covering `ENDPOINTS.md` entry — selected as the entry containing
   the `operationId` link of the operation that matched the legacy
   path in (b) — must carry a permission rule reference equal
   (same owning contract, same rule identifier) to that covering
   route's §1.6 permission reference. The comparison emits the exact
   per-path differences on failure. A repository-wide reference scan
   shows no remaining consumer (including generated clients) resolves
   the legacy file.
5. **Boundary witness:** the repository checker script (shipped by
   the implementing PR and run in CI alongside §7.1) parses
   `ENDPOINTS.md` into the §2.2 entry structure via a Markdown AST
   and rejects, exactly: (a) an entry missing any §2.2 required
   field; (b) an operation mention that is not a Markdown link whose
   target is an `OPENAPI.yaml` `operationId` anchor and whose link
   text is that `operationId`; (c) a fenced code block, anywhere in
   the file, containing any of the OpenAPI schema keywords
   `requestBody`, `responses`, `parameters`, `schema`, or
   `properties` — schema content belongs only in `OPENAPI.yaml`;
   (d) an `operationId` link that does not resolve; (e) an event
   entry whose event name is not in the §4.6 registry. The witness
   proves it can fail with one control per reject rule. (Prose
   duplication a scanner cannot see is handled by review, but every
   structural duplication channel above is mechanical.)
6. **Validity witness:** `OPENAPI.yaml` parses and validates as
   OpenAPI 3.1 in CI under Redocly CLI (`redocly lint`), pinned as a
   repository devDependency (substituting a different validator is an
   amendment to this contract); the witness proves it can fail by a
   control run against an invalidated copy.

## 8. Drafting additions (PRD §12.1 disclosure)

The two artifacts, their roles, and the retirement verification
dimensions are traced to `docs/API/README.md` and `docs/SITEMAP.md`.
Proposed drafting additions, visible here for ratification, each
severable:

1. The generated-with-committed-output production model, the declared
   route-metadata layer with its fail-closed generator, the metadata
   migration scope, and the CI drift gate (§3.1, §7.1) — the ruling
   below.
2. The same-PR documentation rule for surface changes (§4.3).
3. The explicit exclusion list and the delegated-surface
   documentation form (§4.1).
4. The Socket.IO placement rule (events in `ENDPOINTS.md`, no
   pseudo-paths) and the both-direction event coverage (§2.1, §4.1).
5. The no-oracle documentation requirement (§4.2).
6. The `ENDPOINTS.md` structured entry format and its no-duplication
   rule with the mechanical boundary witness (§2.2, §7.5).
7. The committed-repository-file rule — neither artifact exists only
   in CI (§2.3).
8. The normative-direction rule — generation documents, never
   ratifies (§3.2).
9. The retirement deletion-in-reviewed-PR form and the
   interim-consumer restriction (§5.2), and the §7.4 equivalence
   algorithm.
10. The §6 phase placement: implementing-PR-after-ratification, the
    drift gate as a required trunk check from first commit, and the
    build-first documentation sequencing.
11. The §1.5/§1.6 definitions themselves — the production-route
    boundary and the closed route-metadata record with its per-field
    completeness predicate — and the §4.4 delegation allowlist with
    its below-prefix boundary rule, the §4.5 profile enumeration and
    condition field, and the §4.6 typed event registry with the
    literal-name rule.
12. The §7 witness machinery as such: the §7.2 independent inventory
    with its registration-primitive list and bidirectional
    family/operation checks, the §7.3 content and taxonomy witness,
    the §7.5 checker script with its five reject rules, the §7.6
    pinned validator (Redocly CLI), the per-field fail-closed
    controls in §7.1, and the §7.4 canonicalization/derivation/
    covering-entry algorithm.

## Ruling request

Ruling requested (one decision): shall `OPENAPI.yaml` be generated
from Gateway source through a declared, fail-closed route-metadata
layer with a committed output and a CI drift gate (recommended — the
45-controller surface already exists, so generation is the only route
that starts true and stays true, and fail-closed metadata makes
incompleteness a build error) — or hand-authored contract-first, with
code conformance to the hand-written contract enforced by witnesses
instead?