Files
archie/docs/contract-declarations.json
T
sam dacec700a6 fix(tools): stop contractaudit crediting dead paths as live consumers
Renaming the dashboard's request helper from req( to request( broke the
consumer extractor: it matched the call by name, so 16 live routes were
reported unconsumed. The extractor now keys on the call argument instead,
which survives a rename.

The first attempt at that fix was worse than the bug, and is recorded here
because the direction of the error is the whole point. Crediting any quoted
/api/... literal meant a comment, a retired-route array, or a display label
counted as proof a route was reachable -- so deleting every real request
still reported the surface as healthy. A false "unconsumed" is a loud,
fixable failure; a false "consumed" is a silent hole in the gate, which is
worse than having no gate at all.

A path now counts as a consumer only when it is the first argument of a call
in code. That excludes bare constants, dead arrays, object properties, and
commented-out calls, while still accepting any function name. Both halves are
pinned by tests: TestScanFileCreditsAnyCallSignature and
TestScanFileIgnoresNonCallLiterals, plus a surface-level
TestNegativeCommentedOutCallIsStillReported that the vacuous version fails.
Re-injecting either half of the bug fails the suite.

Requiring a call lost no real consumer: internal/webui still reads 49/49.
The remaining limits (path must be the first argument; template
interpolations unseen; routes credited per path rather than per verb) are
declared in docs/contract-declarations.json and the PRD rather than left
implicit.

Also corrects a measurement I had quoted inconsistently: proto/state/v1
declares 45 RPCs, not 43 or 46.
2026-09-15 13:49:47 +10:00

39 lines
3.0 KiB
JSON

{
"$comment": [
"Contract-conformance declarations. Every entry here is a declared-unconsumed",
"surface: a capability that exists, that no client reaches, and that is",
"deliberately left that way. It must match reality exactly -- a missing entry",
"is an undeclared finding and an entry that is no longer true is a stale one,",
"and both fail a -strict run. See docs/prds/contract-conformance-audit.md.",
"",
"Managed by tools/contractaudit. Reasons state the consequence, not 'TODO':",
"this file is the only place the debt is legible."
],
"surfaces": {
"proto/state/v1/state.proto": {
"StateStoreService/ListCaptures": {
"reason": "Superseded by StreamCaptures. The remote adapter's ListCaptures method (staterpc/client.go) calls StreamCaptures, not this unary RPC, so no production client reaches it. The server keeps it implemented as a compatibility surface for callers of the raw proto.",
"tracker": "archie-core-8cda.4"
},
"StateStoreService/ListUndispatchedCaptures": {
"reason": "Superseded by StreamUndispatchedCaptures, on the same terms as ListCaptures: the remote adapter's ListUndispatchedCaptures calls the streaming variant, leaving this unary RPC reachable only through the raw proto.",
"tracker": "archie-core-8cda.4"
}
}
},
"blindSpots": [
{
"surface": "internal/webui",
"reason": "A path counts as a consumer only when it is the first argument of a call in code. The function need not be named -- naming it broke on rename, when matching `req|fetch` reported 16 live routes as unconsumed after the dashboard's helper became `request(` -- but a bare constant, a dead array, an object property, or a commented-out call must not count, because crediting any quoted literal makes the surface pass on a file that issues no requests at all. Limits: a path passed as any argument other than the first is not seen (accepting a comma would start crediting array elements); a request inside a template-literal interpolation is not seen; a path built from a bare /api fragment is reported as unparsable; and a route is credited to every HTTP verb, so a route whose specific verb has no caller reads as consumed. Routes whose consumer is outside the dashboard (the asset mount, the health probes, the capture-intake webhook) are excluded from this surface by design: they have different consumers and are not part of the dashboard API contract."
},
{
"surface": "proto/state/v1/state.proto",
"reason": "Consumption is derived by scanning adapter bodies for calls through the generated client. An RPC reached only through runtime-loaded code (Yaegi) or reflection would read as unconsumed. No such path exists today."
},
{
"surface": "proto/gateway/v1/chat.proto",
"reason": "As above. Note that gatewayrpc is served by archie-gateway and consumed by archied and archie-ui; a consumer living outside this repository would be invisible here."
}
]
}