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.
39 lines
3.0 KiB
JSON
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."
|
|
}
|
|
]
|
|
}
|