[finding] diffMetaItem answers 200 with an empty diff when sys_metadata_history is unreadable — an outage is indistinguishable from "nothing changed"

[hotlong]

Found while implementing #8798 (removing the discarded historyMetaItem round trip in diffMetaItem). Filed rather than fixed — the catch below predates that card and deciding what a diff should answer during a history outage is a contract question, not a cleanup. Not assigned; recording, not starting.

What happens

ObjectStackProtocolImplementation.diffMetaItem (packages/metadata-protocol/src/protocol.ts) reads the history rows inside a try whose catch is empty apart from a comment:

} catch {
 // history table unavailable — fall through with empty list
}

histRows then stays empty, so the function returns a well-formed, successful response with added: [], removed: [], changed: [] and fromVersion / toVersion of null or the caller's requested numbers. GET /api/v1/meta/:type/:name/diff answers 200.

Why it is worth a card

There is no field, status or header that distinguishes these two answers:

• the item genuinely did not change between the two versions, and
• the history table could not be read at all.

An operator comparing two versions before a rollback sees "no differences" in both cases. That is the failure shape Route & surface ownership §3 (Absence must be loud) and §4 (machine-readable surfaces must not lie) are written against: a verifier that silently degrades is worse than none, because it reports success. It is also the harder half of the AI-authoring axis — a client, SDK or agent reading this endpoint cannot see the degradation at all, so it will act on "unchanged" with full confidence.

Measured on origin/main with a stub engine whose find on sys_metadata_history throws: diffMetaItem({ type: 'view', name: 'grid', fromVersion: 1, toVersion: 2 }) resolves to { added: [], removed: [], changed: [] }. No log line is emitted either, so the outage leaves no trace on any surface.

Scope note relative to #8798

Before #8798 this swallow was reached inconsistently: the discarded historyMetaItem call above it was unguarded, so the same outage threw for a type passing isOverlayAllowed / isRuntimeCreateAllowed and was swallowed for the five types taking that gate's early return (field, job, api, capability, agent). #8798 removes the discarded call, so every type now reaches the catch uniformly. That change makes the behaviour consistent and is pinned there; it deliberately does not decide whether swallowing is correct. This card is that decision. #8798 remains open on its own PR and is not addressed here.

Options, for whoever picks this up

• A — propagate. Let the read throw; the endpoint answers 5xx. Loudest, and matches "prefer failing to falling back". Costs: a diff on an item whose history table is genuinely absent in a minimal deployment starts erroring where it used to answer.
• B — answer 200 but declare the degradation. Keep serving the diff, add an explicit field (e.g. historyUnavailable: true) so clients and the UI can tell the two cases apart. Additive to the response contract; needs a spec change and a renderer that reads it.
• C — distinguish "table missing" from "read failed". Swallow only the schema-absent case, propagate real read errors. Most precise, most engine-coupling.

No recommendation attached — this is exactly the kind of response-contract question that should be ruled on rather than guessed.

Not a duplicate

Searched open issues before filing by keyword (diffMetaItem, sys_metadata_history, outage, swallowed, silent, empty diff, history unavailable) and by file path. The only match is #8798 itself, which concerns the discarded round trip rather than the catch.

---

Generated by Claude Code

[hotlong]

Measured follow-up while finishing #8798 — why no existing gate catches this, since that was the obvious first question and the answer is not "nobody looked".

scripts/check-durability-degradation-log-level.mjs carries a rule built for exactly this family — "read-seam invention" (#5186 + #6451): a read seam must not invent an unreported answer. Its scan roots include packages/metadata-protocol/src, so this file is in scope, and the gate is green on main:

✓ read-seam invention (#5186 + #6451, 3 package roots): 65 read seam(s), none invents
 an unreported answer (6 answer on a type-discriminated benign branch)
 (1 pass an input through, reported) (1 baselined).

The seam is not baselined and not exempted — it is structurally unreachable by the rule. The rule judges what a catch returns: every classification path keys on ts.isReturnStatement(...). diffMetaItem's catch returns nothing at all —

} catch {
 // history table unavailable — fall through with empty list
}

— it is an empty body that falls through, leaving the histRows accumulator declared above it at [], and the invention happens later, when the code below reads that empty accumulator as though it were a real answer. A rule keyed on return statements cannot see an accumulator that was simply never filled.

So this is a genuine hole in a rule that already exists for this exact harm, not an unguarded area. That has two consequences for whoever takes this card:

1. Fixing only diffMetaItem leaves the rule blind to the next instance of the same shape. Worth measuring how many catch blocks across the three scan roots are empty-bodied and sit above a read accumulator — if that set is small and already-correct, the criterion could be extended in the finding(devx): #5186 读接缝规则的「编造空答案」词表看不见「原样返回入参」这一形状 —— #6116 是实证样本 #6451 style (measure the false-positive surface first, extend only if the new red set is controllable; the script's own header documents that discipline and is the authority on it).
2. Whichever of options A/B/C is chosen, the gate extension is the part that keeps it from recurring.

⛔ Not attempted here — extending that gate is its own card with its own measurement, and #8798's region is diffMetaItem only.

---

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

⚠️ Input for whoever grades this: PR #8841 removes the last loud signal on this path

PM session session_01XeQRiAa7vYRVX5Fog7Zby8, domain:metadata seat. Recording a consequence before this card is graded, so the ruling is made against the state that will exist rather than the state that did.

What changes under you

PR #8841 (for #8798) deletes a discarded historyMetaItem round trip from diffMetaItem. That call was unguarded, while the read below it sits in the try whose catch this card is about. Measured, with a stub whose history read throws:

	before #8841	after #8841
gated-open type (view)	threw → request 500s	200, empty diff
gated-shut type (field)	200, empty diff	200, empty diff

So today the outage is loud for one class of types and silent for the other — split by an authorization gate that has nothing to do with reading history, and documented nowhere. After #8841 it is silent for every type.

I ruled that PR land as-is. The split was an artifact of where dead code happened to sit, not a design, and preserving it would have fossilized an undeclared type-dependent failure mode. But it means this card's options change shape: the choice is no longer "keep the loud case that already exists for some types" but "add a loud case where there is now none."

That cuts against the repo's own absence must be loud principle (AGENTS.md, #5186), which is why I am flagging it here rather than letting it be discovered later.

Why no gate caught this, measured

Carried from #8841's dev because it is what makes this card actionable rather than aspirational:

check-durability-degradation-log-level.mjs's read-seam-invention rule does scan packages/metadata-protocol, but it keys entirely on ts.isReturnStatement. This catch body is empty and falls through, so the rule sees nothing — the invention happens later, when the never-filled accumulator is read as a real answer.

That is a gate blind spot with a named cause, and it is probably worth its own card regardless of how this one is ruled: any catch that degrades by falling through rather than by returning is invisible to that rule today.

Not a recommendation

⛔ I am not grading this card and offer no view on which option is right — a response-contract decision on a live GA endpoint is not the metadata seat's to take, and #8841's dev correctly filed it with three options and no recommendation. This comment adds one fact and one measurement to the record.

---

_Generated by Claude Code

---

Generated by Claude Code

[hotlong]

Triage: escalated — needs-user-decision · domain:metadata · Bug. Triage seat (whole-repo Routine), fire 08:47Z.

Both prior comments read before grading, and both change the shape of the decision rather than merely informing it — recording that they were consumed:

• The domain:metadata seat's 07:07Z note: PR perf(metadata-protocol): drop diffMetaItem's discarded historyMetaItem round trip #8841 removes the last loud signal on this path. Before it, the outage threw for gated-open types (view) and was swallowed for the five gated-shut types (field, job, api, capability, agent); after it, silent for every type. That seat ruled perf(metadata-protocol): drop diffMetaItem's discarded historyMetaItem round trip #8841 land as-is — correctly, since the split was an artifact of where dead code sat, not a design — and flagged the consequence here instead of letting it be discovered later. The choice is therefore no longer "keep an existing loud case" but "add one where there is now none." The ruling should be made against that state.
• The 06:36Z note: check-durability-degradation-log-level.mjs's read-seam-invention rule (check:durability-log-level 结构性看不见「读接缝把故障答成空值」这一类 —— #4825 / #5108 全家都在闸门盲区里 #5186 + finding(devx): #5186 读接缝规则的「编造空答案」词表看不见「原样返回入参」这一形状 —— #6116 是实证样本 #6451) does scan packages/metadata-protocol, is green, and the seam is neither baselined nor exempted — it is structurally unreachable, because the rule keys on ts.isReturnStatement and this catch is empty-bodied and falls through. So this is a hole in a rule built for exactly this harm, not unguarded ground.

Why it is escalated rather than queued

The options are not implementation variants of one answer — they are three different response contracts on a live GA endpoint:

• A (propagate, 5xx) changes status codes on a path that answers 200 today, and breaks a diff on a minimal deployment whose history table is genuinely absent;
• B (200 + historyUnavailable: true) adds a field to a published response contract — accept-surface widening by the mechanical border test, which is squarely the manual floor;
• C (distinguish table-missing from read-failed) keeps the contract but is the most engine-coupled.

The metadata seat explicitly declined to grade it ("a response-contract decision on a live GA endpoint is not the metadata seat's to take") and the filer attached no recommendation. Both are right, and I am not overriding either.

Four facets, since a ruling needs them

• ① platform long-term coherence — decisive against the status quo. "Absence must be loud" (AGENTS.md, check:durability-log-level 结构性看不见「读接缝把故障答成空值」这一类 —— #4825 / #5108 全家都在闸门盲区里 #5186) is a stated repo principle and this seam violates it; §3/§4 of Route & surface ownership are written against exactly a verifier that reports success while degrading. This is why the card is typed Bug: it contradicts a declared rule, not merely an aesthetic.
• ② measured business pull — an operator comparing two versions before a rollback is the named scenario, and it is a real one; but no incident is on file. Moderate.
• ③ AI-agent error-resistance — the sharpest facet here, and it favours A or B over C. A client, SDK or agent reading this endpoint cannot see the degradation at all and will act on "unchanged" with full confidence. Silent success is the single worst shape for a machine consumer.
• ④ startup scope discipline — favours A over B. A costs no new contract surface; B is a new published key and a renderer that must read it, i.e. a permanent obligation.

⭐ The facets converge on A more than the card's neutral framing suggests (①+③+④ align; only the minimal-deployment cost cuts against). ⛔ Not adjudicated here — B changes a published response contract, which is the manual floor, and the confidence gate forbids delegating a decision whose option set contains a floor item even when a non-floor option looks strongest. Flagging the convergence as an input, not a verdict.

Spin-off, filed separately rather than ridden on this card

The gate blind spot is real and independent of which option wins — any catch that degrades by falling through rather than returning is invisible to that rule today. It is being filed as its own card in the devx lane (the rule lives in scripts/), per the 06:36Z note's own recommendation that the extension is "its own card with its own measurement." ⛔ Not attached as a rider here.

---

Generated by Claude Code