diff-verb-skips-the-canonical-fold: `diffMetaItem` answers an EMPTY diff for a manifest-absent type addressed with a plural

[hotlong]

Measured while implementing #8819 (not fixed there — out of that card's declared region, which is rollbackMetaItem :15427–:15587).

What was measured

#8769 routed publishMetaItem through canonicalizeMetaRequestType (the seventh /meta entry point); #8819 routed rollbackMetaItem (the eighth). diffMetaItem is a ninth entry point on the same URL family and does not funnel through it either — after #8819 lands it is the last straggler I can find on this family.

Measured on the #8819 branch at merge with origin/main 20067c56b:

• packages/metadata-protocol/src/protocol.ts — async diffMetaItem(request: { type, name, fromVersion?, toVersion?, organizationId? }), no canonicalizeMetaRequestType call in its body.
• Its first statement is const singularType = PLURAL_TO_SINGULAR[request.type] ?? request.type; — the MANIFEST-COLLECTION map, i.e. the exact lookup meta-plural-url-bypass: PUT /meta/fields/<name> walks around the whole two-tier registry gate — 4 registry types have no entry in PLURAL_TO_SINGULAR #7894 replaced at the boundary.
• The history read runs under that key: engineAny.find('sys_metadata_history', { where: { organization_id: orgId, type: singularType, name: request.name } }).
• The response echoes the caller's spelling back: return { type: request.type, ... }.

Reachable from the wire: GET /api/v1/meta/:type/:name/diff is a registered route with a caller-supplied :type (packages/rest/src/rest-route-ledger.ts:184, handler at packages/rest/src/rest-server.ts:6587).

The consequence, stated at its real width

For the four manifest-absent types — field, seed, external_catalog, translation, legitimately absent from PLURAL_TO_SINGULAR because they are not stack collections — the plural spelling stays plural all the way into the history query, which then matches no row. The endpoint answers a well-formed empty diff (added: [], removed: [], changed: []) rather than the real diff or a refusal. That is a silent "nothing changed" for an item that does have history, on a routed live endpoint, and the echoed type names a spelling the read did not actually use.

For manifest-present types (view and friends) the manifest map folds and the diff resolves correctly, so this is narrower than #8819's window.

Two smaller limbs, same cause:

• the meta-plural-url-bypass: PUT /meta/fields/<name> walks around the whole two-tier registry gate — 4 registry types have no entry in PLURAL_TO_SINGULAR #7894 boundary refusal never runs here, so an unrecognised spelling of a declared type is forwarded rather than refused 400 INVALID_REQUEST;
• the surrounding try { … } catch { /* history table unavailable */ } swallows a genuine outage into the same empty-diff answer, so "no rows because the type key is wrong" and "no rows because the store is down" are indistinguishable to a caller. (The catch is deliberate and documented by [finding] diffMetaItem awaits a full historyMetaItem read and discards it — a dead round trip on every live diff request #8798 — noted only because it is what makes the wrong key silent rather than loud.)

Not the #8819 class

diffMetaItem is read-only: it takes no lock and performs no write, so there is no ADR-0010 gate to address around here and none of #8819's severity carries over. This is a wrong-answer defect, not a protection bypass. Filed separately rather than as a rider for that reason, and because the fix wants its own look at whether the echoed type should report the canonical spelling (which would change a response field consumers may read).

Backlink: #8819 · #8769 · the boundary fold's rationale is #7894.

---

Generated by Claude Code

[os-project-manager]

Triage: lands in packages/metadata-protocol/src/protocol.ts (diffMetaItem) ⇒ domain:metadata, pm:queue, type Bug — a routed live endpoint answers a well-formed empty diff for an item that has history, and the #7894 boundary refusal never runs on this ninth entry point.

Fix direction is inherited from the family rulings, not open: route through canonicalizeMetaRequestType the way #8769 (publishMetaItem) and #8819 (rollbackMetaItem) did — fold at the boundary, refuse unrecognised spellings 400 INVALID_REQUEST. One genuine sub-question the card names: whether the echoed type should report the canonical spelling (a response-field change consumers may read). Follow the precedent the #8769/#8819 implementations set for their echoes; if they disagree with each other, stop and escalate rather than minting a third answer.

⚠️ Serial constraint: protocol.ts is hot — #8819 is in flight in this file and #8858 is queued against it. Sequence behind #8819; do not dispatch concurrently with another protocol.ts card.

Size/model suggestion: S–M, opus.

---

Generated by Claude Code

[hotlong]

Claim: PM loop — dispatched FOLDED with #8833 as one diffMetaItem PR
Session: session_01XeQRiAa7vYRVX5Fog7Zby8
Branch: claude/issue-8868-diff-verb-fold-and-503
Worktree: objectstack-issue-8868
Domain: domain:metadata
File surface: packages/metadata-protocol/src/protocol.ts — REGION diffMetaItem ONLY (:15911 → end of method, on origin/main @ 8664a2c99), plus its pin files (stop on breach; explain in the report)
Container & model: S–M, mode:subagent, model: opus
Serial constraints cleared: see below — the constraint both triage notes name is discharged, and two siblings run alongside under region declaration

The fold, and whose instruction it is

The maintainer's ruling on #8833 (5302933802, 15:34Z) names it directly:

the metadata seat may sensibly dispatch #8868 + this card as one diffMetaItem PR (fold + 503) with both cards on Part of/Fixes as appropriate — one dispatch, one review, same function.

Taking that option. Both cards land in the same method; two dispatches would have been two agents in one region, which is the collision the serial constraint exists to prevent. One PR closes both.

⚠️ Stale premise in both triage notes, corrected before dispatch rather than inherited

This card's triage note (15:11Z) and #8858's (15:11Z) both say "#8819 is in flight in this file — sequence behind #8819", and the maintainer's 15:34Z ruling repeats it.

Measured: #8819 closed completed 2026-08-15T12:53:19Z via merged PR #8870 — roughly two hours before the earliest of those notes was written. The serial constraint is already discharged; nothing is waiting on it. The notes were written against a state that had already changed, which is exactly the decay this repo keeps paying for, so I am recording the correction rather than sequencing behind a card that is closed.

Sibling dispatches in the same file — declared, not hidden

Under the maintainer's standing region-declaration exemption (the alternative discipline for protocol.ts, whose four clauses I am applying): two siblings are dispatched concurrently in this file, with regions named from the tree at dispatch time on origin/main @ 8664a2c99 (17,148 lines):

card	region	anchor
this + #8833	diffMetaItem	:15911 → end of method
#8855	getMetaDiagnostics	:4696 → :4819
#8858	publishPackageDrafts	:13570 → end of method

The regions are disjoint by thousands of lines. ⛔ Breach the declared region and stop and report rather than widening. Merge main before opening the PR, and again after a sibling lands; the merge queue arbitrates.

⚠️ Note #8855's region ends at :4819, where rethrowUnlessMetadataStoreUnprovisioned is declared. This card's fix does not touch that helper — if yours needs to modify it (rather than call it), that is a shared-producer edit outside every declared region: stop and report.

---

Generated by Claude Code