diff --git a/docs/requirements/api-artifacts.md b/docs/requirements/api-artifacts.md index 24d2a156..a73d13d5 100644 --- a/docs/requirements/api-artifacts.md +++ b/docs/requirements/api-artifacts.md @@ -187,6 +187,27 @@ grammatical without phantom operations; §7.5(k) becomes the kind-partition rule and new rule (l) checks the exclusion mirror (NF7). +Revision 9 (luna r8 residual NF1 + NF8/NF9): the §7.7(d)(5) default +inventory attributes by execution pipeline, never by configuration +scope alone — each response-emitting entry names its emitting +lifecycle stage, and its status attributes to framework-routed +routes plus exactly those raw-mounted routes whose dispatch point +executes after that stage; a pre-parsing raw hijack therefore never +carries a body-parsing rejection status, the body-size-limit probe +becomes a two-pipeline pair, and a body-limit status on a raw route +must have a status site in the route's own callback chain (NF1). +§7.3's content witness partitions by the §2.2 entry kind — surface +fields are checked on surface entries only; delegated-surface and +exclusion entries are checked for their own kinds' field content, +with the §4.4/§4.1 mirrors staying in §7.5(g)/(l) (NF8). The §7.2 +method partition gains a URL fall-through class: a path dominated +by the negation of the mount's URL-dispatch predicate may forward +only to the hook chain's continuation, emits nothing, needs no +method pinning, and contributes no record — the method partition +binds exactly the URL-accepted branch, and a URL-missed path +forwarding anywhere but the continuation is still a scan failure +(NF9). + 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). @@ -653,18 +674,37 @@ scanned source roots, and compared files. checker proves the callback's dispatch partitions its control flow. Every path from callback entry to a request-terminating action (a response emission or a forwarding of the request) is - classified as exactly one of: (i) an **acceptance path** — - dominated by positive equality tests of the request method + classified as exactly one of: (i) a **URL fall-through path** — + dominated by the NEGATION of the mount's URL-dispatch predicate + (the request does not match the dispatched prefix under the + boundary semantics above): it forwards the request ONLY to the + hook chain's continuation (the callback's done/next + continuation, handing the request to later hooks and the + framework router), emits nothing, needs no method pinning, and + contributes no raw record — the raw MCP hook's prefix-miss + branch that returns the request to the router is this class, + not a scan failure; a URL-missed path that instead forwards + into a handler, another dispatcher, or any package IS a scan + failure naming the site; (ii) an **acceptance path** — + dominated by the mount's URL-dispatch predicate holding AND + positive equality tests of the request method against string constants that pin the path to exactly one - method; that (prefix, method) pair carries a record; (ii) a + method; that (prefix, method) pair carries a record; (iii) a **refusal path** — the ONLY classification where a complement - test (`method !== X`) or an unguarded path is admissible: the + test (`method !== X`) or an unguarded method test is + admissible: the URL-dispatch predicate holds, and the path terminates in a constant-status refusal emission (by the §7.7(d)(4) emission-site rules) and forwards the request - nowhere; or (iii) a **scan failure** — a complement-guarded or + nowhere; or (iv) a **scan failure** — a URL-accepted + complement-guarded or unguarded path that forwards the request (into a handler, - another dispatcher, or any package) accepts an unbounded - method set and fails naming the site. One carve-out mirrors + another dispatcher, or any package — including back into the + hook continuation, which for a URL-accepted request would + double-dispatch it) accepts an unbounded + method set and fails naming the site. The method partition + therefore binds exactly the URL-accepted branch of the + callback; the URL-miss branch is bound only to forward to the + continuation and emit nothing. One carve-out mirrors the §7.7(d)(4) delegated-emission rule: a forwarding edge into a non-production package may instead carry a **declared external method contract** — the accepted-method set the @@ -762,10 +802,22 @@ handler)`, a computed decorator value) is a scan FAILURE naming 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 §2.2 entry grammar; +3. **Content and taxonomy witness:** the content check partitions by + the §2.2 entry kind, the same partition §7.5(k) enforces. A + **surface entry** carries the §2.2 surface fields — behavior, + operation links, authentication requirement, owning-contract + link, error semantics — presence-checked mechanically against + the §2.2 entry grammar. A **delegated-surface entry** carries + exactly `Summary:` and a `Delegated:` field whose four §2.2 + sub-items are each present and well-formed (their field-by-field + equality to the §4.4 allowlist is §7.5(g)'s check); the surface + fields are neither required of nor permitted on it. An + **exclusion entry** carries exactly `Summary:` and an + `Excluded:` field with at least one well-formed §2.2 sub-item + (the two-way mirror to the §4.1 script list is §7.5(l)'s + check). A content check that demands a surface field of a + non-surface entry, or that passes a non-surface entry whose own + kind's field content is missing or malformed, fails; every error response documented in `OPENAPI.yaml` uses a code from the contract 5 §4.2 closed enums **as exported from the shared types package** (contract 5 §4.1's package; the @@ -1026,10 +1078,27 @@ handler)`, a computed decorator value) is a scan FAILURE naming citation into the pinned version's source or documentation for that behavior AND a runtime probe that triggers the default and asserts the observed status; a response-emitting - entry missing its citation or its probe is a witness failure, - and each entry's status attributes to the routes the option's - scope covers (a server-wide option to every route on that - server). Every site's status argument must resolve + entry missing its citation or its probe is a witness failure. + Each entry's status attributes by the §7.7(d)(2) + execution-pipeline rule, never by configuration scope alone: + every response-emitting entry names its emitting pipeline + stage — the lifecycle point where the pinned version's + mechanism runs (connection handling, request-line/header + processing, body parsing, routing, response serialization) — + and the status attributes to framework-routed routes and to + exactly those raw-mounted routes whose §7.2 dispatch point + executes AFTER the emitting stage in the adapter's lifecycle. + A raw mount whose hook terminates or forwards the request + BEFORE a stage runs never carries that stage's status: the raw + MCP mount hijacks in a pre-parsing hook and hands the unparsed + request to the external transport, so the adapter's + body-parsing rejection cannot fire there, and attributing the + body-size-limit status to that route (or requiring it of the + route's record) is a phantom the bidirectional comparison + rejects. If a raw-mounted route's record declares a + body-limit-shaped status, the route's own callback chain must + contain a status site for it — a server-wide option is not + that site. Every site's status argument must resolve to a literal or compile-time constant; an unresolvable status is a FAILURE naming the site. Both directions: every resolved status is a member of the route's record response map, AND @@ -1055,8 +1124,13 @@ handler)`, a computed decorator value) is a scan FAILURE naming option key present in the pinned adapter options type but absent from the default inventory fails; a configured composition-root option key absent from the inventory fails; - the body-size-limit probe triggers the adapter rejection and - asserts its observed status; the + the body-size-limit probe is a PAIR driving one oversized + request down each pipeline: the framework-routed fixture + observes the adapter rejection status, and the pre-parsing + raw-mounted fixture observes NO adapter rejection (the request + reaches the raw callback unparsed) — with the body-limit + status attributed to (or required of) the raw route failing as + a phantom; the implicit default success status is attributed to the route and must appear in its response map; (e) **guard-equivalence** — for each `ApiAuthClass`, the witness asserts the derived @@ -1212,7 +1286,12 @@ severable: configured composition-root options, citation-plus-probe per emitting entry); and the §2.2 entry kinds with the `Delegated:`/`Excluded:` field syntax, the revised §7.5(k) - kind-partition rule, and the §7.5(l) exclusion mirror. + kind-partition rule, and the §7.5(l) exclusion mirror. The + revision-9 refinements: per-stage pipeline attribution of + inventory defaults with the two-pipeline body-size probe pair + (§7.7(d)(5)); the per-kind §7.3 content partition; and the + §7.2 URL fall-through classification scoping the method + partition to the URL-accepted branch. ## Ruling request