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.
Reachability (tools/reachaudit, epic archie-core-06ag) answers "is this code
in a shipped binary?". It cannot answer the complementary question: "does
every declared contract surface have a consumer, or a declaration that it
has none?". ratelimit was in the binary closure and called by nothing, which
reachability could not see.
tools/contractaudit classifies each subject of each declared surface as
CONSUMED, DECLARED-UNCONSUMED, UNDECLARED-UNCONSUMED, or STALE-DECLARATION,
and only the last two are findings. The declaration allowlist must match
reality exactly: a missing entry fails and so does an entry that outlived
its subject, because a stale allowlist is how a gate quietly stops checking
anything.
Surfaces: the two gRPC services, whose consumption is derived by scanning
adapter bodies for calls through the generated client, and the dashboard
HTTP API, matched between the registerXRoutes call sites and the path
literals the bundled client calls.
Findings on the current tree, all deliberate and now declared:
ListCaptures and ListUndispatchedCaptures are superseded by their streaming
variants -- staterpc's client calls StreamCaptures -- so no production
client reaches the unary RPCs.
Three bugs this tool found in itself, each recorded because each is the
class of error that makes a conformance check worse than none:
- Joining RPCs to adapter methods by name silently reported live RPCs as
unconsumed, because adapters do not map one-to-one: StoreClient.Get calls
GetSession, List calls ListSessions.
- Reflecting over the client value rather than the pointer reported zero
methods, hence the whole surface unconsumed.
- Treating the asset mount and the health probes as dashboard API routes
reported four healthy routes as undeclared; they have different consumers
and are out of scope for this surface.
The consumer extractor fails loudly on a call shape it cannot parse rather
than under-reporting, and every check is negative-tested: a route, an RPC,
and a removed consumer are each injected, confirmed to fail for the right
reason, and reverted. The declaration staleness rule is tested too.
Advisory when run directly; task check runs it -strict. See
docs/prds/contract-conformance-audit.md.