23 — OpenAPI Spec Index

Scope: The product contracts that turn internal route families into published, consumable APIs — what exists, who consumes it, and the parity discipline that keeps the contract honest. Audience: operator + developer. Status: As of 2026-11-09. Sources (cited inline): the seventeen runtime-tier API descriptions; the commercial product map; the claims-processing cover test and its sibling; the claims backlog item; the route-side sanitizer. Specifications are read-only product maps, not new schemas (source: product map, Rules).

1. The seventeen specifications

Each description carries a title and version parsed from its header, plus sample entry points. "Who consumes it" comes from the product map; where the map has no row, the BFF-internal consumer is the domain the title names, and that promotion is a mapping exercise rather than a new file (source: product map, Rules).

Cross-cutting compositions (no new file — they are recipes across the above):

• Capability → sourcing integrator — composes entities, organizations, sourcing, processing, requests, pack emissions, and monetization references; enforces the query profile and opaque adapter-class enums (source: product map, CAPSRC-01 DONE).
• Claims orchestration pilot — composes the claims-processing and lifelong-entities descriptions; the motor pack is soft-shipped while medical, home, and government packs remain spec-only (source: product map, CLAIMORCH items).
• Claims orchestration façade — optional and low-priority; only if developer experience demands it, and it must never fork insurance logic (source: product map, CLAIMGEN-11).

2. Scope of the 23-path claims contract

The claims-processing description is the contract example every reviewer should learn. Its 23 required paths are the live superset: every route the runtime tier serves for claim processing must appear in the description, so the contract cannot drift from reality (source: claims cover test, lines 21–45).

What the 23 paths cover by group:

• Lifecycle core — create/read, transitions, finalize, readiness, metrics.
• Governance — proof-of-execution requirement checks and guard evaluation.
• Panels — role listing and eligibility (organization + resource + affiliation; lookup values only).
• SLA — policy, evaluation, timeout (with a workflow-engine timeout step behind it).
• Quorum — bands, resolve, open (existing quorum plane).
• Value-added services — eligibility and check.
• Intake maps — map listing and preview (soft desk; the execution beans are still to deploy).
• Scenario packs — soft-apply.
• Journey — a single complete voyage view.

Template parameters ({claimId}, {scenarioId}, {mapId}, {voyageId}) are the description form; the live tier uses the equivalent colon forms (source: claims cover test).

The sibling contract for lifelong entities follows the same pattern with 38 required paths, plus a source-mirror test that scrapes the live route definitions and asserts every live path exists in the description (source: entity cover test).

Why 23 matters beyond the number: the claims description carries four cross-vertical compose recipes (claims with sourcing, with proof-of-execution checks, with quorum, with organizations) and a generalization rule — "if an implementation needs a branch on a specific vertical claim type, that is a defect" (source: claims-processing description). The 23 paths are therefore not a vertical API; they are a generic lifecycle contract that every vertical composes, never forks.

3. Parity rules (what the tests enforce)

3.1 Cover-test discipline

• Full-path parity, both directions. The test loads the description from disk and asserts each required path exists; the sibling also asserts the reverse — every live route is in the spec (source: both cover tests).
• OpenAPI shape. Standard version marker; the claims title must name the cross-vertical nature; at least two servers (development, verification, and a local laptop entry that is explicitly not for public code generation) (source: claims cover test; description servers).
• Operation identities. Every operation carries a unique operation identifier; the claims test requires a minimum count, the entity test requires roughly one per path (source: both cover tests).
• Required fields. Claim creation documents its three mandatory fields as required (source: claims cover test).
• Compose appendix. At least four recipes, and the joined text must reference organizations, sourcing, governance paths, and quorum (source: claims cover test).
• Generalization. Example claim types must span at least insurance plus community plus commerce/government (source: claims cover test).
• Dispatch validation. The dispatch description is validated offline by a standalone validator plus a smoke wrapper (source: dispatch smoke test).

3.2 Public-description hygiene

Public descriptions must not name third-party products. A quick-scan test enforces this, backed by a platform-wide sanitizer and an adapter-class allowlist test (source: sanitizer; allowlist test; cover tests). The operational rule is simple: use neutral capability language in any public description.

3.3 Route-authoring traps

• String arguments. Identifier-looking strings (actor ids, claim ids) must be emitted as quoted text, never as bare record literals — bare literals are coerced into record references and rejected (source: route-side helpers; the November fix that introduced the safe emission).
• Envelope detection. The row-extraction helper must distinguish a genuine response envelope from a row that merely has a status field (source: route implementation).
• Fetch-then-filter. Predicates belong in the query, not in JavaScript after over-fetching; the messaging relay fixed the same bug class by pushing its subject filter into the query (source: relay implementation).

4. How a route goes from design to published API

This is the checklist every contributor follows. The product-map rule behind it: new endpoints belong in the relevant existing description, never a new vertical description (source: product map, Rules).

1. Author the route in the runtime tier's route group — keeping static routes ahead of parameterized ones (a static lifecycle route must precede the :claimId family), so routing order never swallows a literal path (source: route ordering comments).
2. Add the spec path to the existing description: the path entry, a unique operation identifier, tags, a summary/description with no third-party product names, and required-field request bodies where applicable (source: product map; description format).
3. Update compose and generalization entries where the route composes across verticals — the cover test joins the recipes and checks for the organization/sourcing/governance/quorum references and the multi-type examples (source: claims cover test).
4. Cover test — add the path to the required-paths list so the suite asserts parity and the contract cannot drift again (source: claims backlog item for the v1.1.0 drift fix; cover test).
5. Product-map row — if the route changes the commercial surface, add its row to the product map; otherwise bump the description version (source: product map).
6. Run the suite before review — the cover test (and the offline validator for dispatch). A route that fails its cover test is not a route.

5. Deliverable state by consumer (product-map rows)

• Community + Starter ops + Safety (ICE) — one shared description; starter desk, dispatch, tenants, ops alerts, governance divergences, and safety incident/dispatch flows (source: product map).
• Agency (MARS) — the compliance and dispatch descriptions; compliance, truth-proxy, and governance families (source: product map).
• Sourcing — the gateway description plus sourcing routes (source: product map).
• Configuration fragments — the config family (source: product map).
• Vault / BBS+ — the vault description; file/present/share/verify (source: product map).
• Attestation (AaaS) — the manifest fragment; attestation family (source: product map).
• Claim processing (generic lifecycle) — the claims description; cross-vertical, with PoCE/quorum/sourcing/organization compose appendix (source: product map).
• Lifelong entities — the entities description; mint/changes/history/leases/packages/sourcing deltas/capability registry (source: product map).
• Capability → sourcing — compose map, not a new description (source: product map).
• Interaction requests — the unified requests description; no third-party product names (source: product map).
• Claims pilot + façade — compose items as in Section 1 (source: product map).

Descriptions with no product-map row keep their title-domain consumer from Section 1; promoting them is a mapping exercise, not a new file (source: product map, Rules).

6. Parity checklist for reviewers

1. Route added without touching its description → reject (product-map rule).
2. Public description names a third-party product → reject (hygiene scan).
3. Required-paths list misses a live route → reject (cover test).
4. Runtime code branches on a vertical claim type → reject (generalization defect definition).
5. Duplicate or insufficient operation identifiers → reject.
6. Fewer than four compose recipes or missing cross-references → reject.
7. Any bare-literal string argument → reject.

Servers note: the claims description lists development, verification, and local entries — the local one is labeled for laptop use only and must not be used for public code generation (source: claims-processing description).

7. Full rendered references (generated, in this set)

All 18 specs are rendered verbatim into the generated API reference set (613 operations across the renders — 610 unique method+path pairs, 3 defined in more than one spec: paths tables, per-operation parameters/request/response docs, plus each full spec JSON as an appendix, so this set is self-contained; measured implementation coverage is in the complete API inventory). api/ is GENERATED — edit the specs in the published OpenAPI specs and re-run node scripts/render-platform-map-api-docs.mjs; never hand-edit the renders.