90 of 125 console API-response types are hand-copied with no guard, and 15 already disagree with the Worker

[serge-ivo]

72% of console API-response types are hand-copied from the Worker, and none is guarded

Measured while closing #608 AC4:

console-side API-response types : 125
parallel declarations           :  90  (72%)
with a drift guard              :   0
already disagreeing with the Worker : ≥15

A parallel declaration is a type the console writes out by hand to describe a body the Worker produces. Nothing compares the two. When they diverge, TypeScript is satisfied on both sides and the mismatch surfaces as a field that is silently undefined at runtime.

The already-broken subset is the argument for urgency, and its shape is the nastiest available: wrong field names on fields that are optional on both sides, so nothing throws and nothing logs.

console expects	Worker sends
KnowledgeDoc.createdAt	addedAt
Credential.history	recoveryHistory

A date that never renders and a history that is always empty, with no error anywhere.

#608's two instances were the harder subclass, not representative: their Worker shapes were anonymous literals, so no guard was possible until usage-shape.ts gave them a name. Most of the 90 have a named Worker type already and are therefore cheaper to fix than the two that prompted this.

Why this is the same defect as everything else this week

It is a claim about a contract that nothing compares to its source — the pattern behind #587 (a stored status nothing writes), #602 (docs stating counts the code disproves), #609 (a published vocabulary the enum lacks) and #610 (console capabilities MCP cannot reach). Here the claim is a type and the source is the producer.

#610 established the technique that fits: enumerate both sides, compare, ratchet a known-gap list, fail on anything unlisted, and print the denominator every build.

Acceptance criteria

1. Console response types derive from the Worker's declaration, or a check compares them. Prefer derivation — usage-shape.ts is the worked example from UsageSummary omits cache-token fields the aggregator returns, and JsonSchema.type is a scalar where the format uses an array #608 and removed four parallel declarations at once.
2. A ratcheted inventory of what is not yet converted, so the count can shrink but not silently grow. Unlisted divergence fails the build, per Everything the console can reach should be reachable over MCP, and nothing checks that — three projection losses in one week #610's shape.
3. Denominator printed every build: types compared, matching, known-divergent — so "checked and clean" is distinguishable from "not checked".
4. Red demonstrated by renaming a Worker field.
5. Where a Worker shape is an anonymous literal, note it — those need a name before they can be compared, and that is a real cost this issue should report rather than absorb silently.

Verified vs inferred

• Verified: all four counts; both field-name mismatches; that usage-shape.ts collapsed four parallel declarations.
• Inferred: that most of the 90 have named Worker types and are cheaper than UsageSummary omits cache-token fields the aggregator returns, and JsonSchema.type is a scalar where the format uses an array #608's pair. Stated by the agent that counted them; the split between named and anonymous was not itself counted — AC5 asks for it, because it is what determines the real size of this work.

[serge-ivo]

Closed by commit 213c93c.

What was done:

scripts/check-console-types.mjs adds the ratcheted guard #616 asked for.

AC1 (#617 already): The 17 confirmed divergences were fixed in #617, which also added compile-time Extra<Console, Worker> assertions in types.test.ts for named types.

AC2 — ratcheted inventory: KNOWN_ANONYMOUS records all 108 unique anonymous shapes. An unlisted shape fails. A dead entry fails. Only way down.

AC3 — denominator every build:
api<> call sites total : 168
anonymous (ratcheted) : 129 / 168 (76.8%)
named (no ratchet) : 39 / 168
unique shapes : 108

AC4 — demonstrated red: adding api<{ testOnlyField: string }>() to any console source file fails the build with hash + file:line.

AC5 — anonymous vs named split: 129 anonymous call sites (108 unique shapes) need a Worker-side named interface before types.test.ts can compare them. The KNOWN_ANONYMOUS comment explains the five-step path to close each entry.

ci.yml gains a new gate after check-mcp-parity.mjs.