This commit is contained in:
fred
@@ -0,0 +1,169 @@
|
|||||||
|
# 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; this contract's ratification is that approval path. 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.
|
||||||
|
|
||||||
|
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 and Socket.IO events
|
||||||
|
the artifacts describe.
|
||||||
|
3. **Drift**: any difference between an artifact and the production
|
||||||
|
surface it documents — an undocumented live route, a documented
|
||||||
|
phantom route, or a divergent schema/auth/error description.
|
||||||
|
|
||||||
|
## 2. Artifact contract
|
||||||
|
|
||||||
|
1. **`OPENAPI.yaml`** is one file, valid OpenAPI 3.1, 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: per endpoint family, the
|
||||||
|
behavior, authentication requirement, permission/authorization rule
|
||||||
|
(naming the owning contract — contract 2 for chain authorization,
|
||||||
|
the SOT for workspace membership), and error semantics including
|
||||||
|
the contract 5 §4.2 taxonomy. It links to owning contracts and to
|
||||||
|
`OPENAPI.yaml`; it does not duplicate endpoint definitions (the
|
||||||
|
`docs/API/README.md` authoring boundary).
|
||||||
|
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 (route decorators plus the shared request/result
|
||||||
|
DTOs of contract 5 §4.1) by a deterministic repository script; 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 witness.
|
||||||
|
|
||||||
|
## 4. Coverage obligations
|
||||||
|
|
||||||
|
1. Every production Gateway HTTP route appears in `OPENAPI.yaml`; every
|
||||||
|
route family appears in `ENDPOINTS.md`. Test-only and
|
||||||
|
development-only surfaces are excluded and the exclusion list is
|
||||||
|
explicit in the generation script, not implicit.
|
||||||
|
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` row in the same PR, enforced by the §7.1
|
||||||
|
drift gate — there is no "docs to follow" state.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
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.
|
||||||
|
|
||||||
|
## 6. Phase timing
|
||||||
|
|
||||||
|
1. The artifacts 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` row in its implementing PR.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
2. **Coverage witness:** an independent route inventory (static
|
||||||
|
enumeration of Gateway controllers and gateways over `apps/`,
|
||||||
|
production code, tests excluded — the A5 §1.2 inventory style)
|
||||||
|
equals the documented path set in both directions: no undocumented
|
||||||
|
live route, no documented phantom. Socket.IO events are inventoried
|
||||||
|
the same way against `ENDPOINTS.md`.
|
||||||
|
3. **Taxonomy witness:** 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` with equivalent schemas, auth, permissions, and
|
||||||
|
error behavior, and a repository-wide reference scan shows no
|
||||||
|
remaining consumer (including generated clients) resolves the
|
||||||
|
legacy file.
|
||||||
|
5. **Boundary witness:** `ENDPOINTS.md` contains no endpoint
|
||||||
|
definition duplicated from `OPENAPI.yaml` (machine-checkable:
|
||||||
|
no path+verb table row whose content restates the generated
|
||||||
|
operation instead of linking it), per the `docs/API/README.md`
|
||||||
|
authoring boundary.
|
||||||
|
|
||||||
|
## 8. Drafting additions (PRD §12.1 disclosure)
|
||||||
|
|
||||||
|
The two artifacts, their roles, the single-boundary rule, and the
|
||||||
|
legacy retirement conditions 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 and 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 for test/development surfaces (§4.1).
|
||||||
|
4. The Socket.IO placement rule (events in `ENDPOINTS.md`, no
|
||||||
|
pseudo-paths) (§2.1).
|
||||||
|
5. The no-oracle documentation requirement (§4.2).
|
||||||
|
|
||||||
|
## Ruling request
|
||||||
|
|
||||||
|
Ruling requested (one decision): shall `OPENAPI.yaml` be generated
|
||||||
|
from Gateway source 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) — or
|
||||||
|
hand-authored contract-first, with code conformance to the
|
||||||
|
hand-written contract enforced by witnesses instead?
|
||||||
Reference in New Issue
Block a user