`findReferencesToMeta` answers `{references: []}` for every target type absent from `REFERENCE_PATHS` — the "Used by" panel is silent by construction for 20+ declared types

[os-zhuang]

Surfaced while implementing #9157 (step ① of the #9180 ruling). ⚠️ Filed plainly and unassigned: the behaviour is documented in the method's own TSDoc, so this may well be triaged as working-as-declared. It is filed because the declaration and the consumer's reading of the answer disagree, not because I measured a live incident.

What was measured

packages/metadata-protocol/src/protocol.ts on origin/main @ 50900479f. findReferencesToMeta is driven entirely by the hand-curated REFERENCE_PATHS registry, which has exactly seven target keys:

object · view · tool · skill · flow · dashboard · page

Any other target type misses the registry and takes this limb:

const matchers = REFERENCE_PATHS[singularTarget];
if (!matchers || matchers.length === 0) {
 return { references: [] };
}

So GET /api/v1/meta/permission/sales_admin/references, .../field/..., .../translation/..., .../seed/..., .../external_catalog/..., .../agent/..., .../report/..., .../email_template/... — every declared type outside those seven — answer 200 with an empty list, always, on every deployment, whether or not anything depends on the item.

Why this is filed rather than shrugged at

The method's TSDoc calls it legitimate:

> A target type not present in the registry, and a SOURCE type this deployment does not declare, both simply produce no hits — neither is an error.

That is true as a statement about the registry. It is not how the answer is consumed. This response drives the admin UI's "Used by" panel, which is rendered before a rename / delete / type-narrowing, and #8896 already named the harm shape for this exact endpoint: an empty or short list reads as "nothing depends on this — safe to remove". #8896 closed the half where a read FAILURE was swallowed into that shape; this is the half where the registry simply has no entry, and the two are indistinguishable to the caller — same status, same body.

⛔ Explicitly not the same defect as #9157. That card was about the type KEY being spelled wrong (a plural reaching a lookup keyed on singulars), and it is fixed. This is about the lookup being empty for the key even when the key is perfectly canonical. #9157's pin the manifest-ABSENT class is NOT closed here, and that is stated rather than implied asserts this residue deliberately so it could not be quietly read as closed.

Dispositions worth weighing at triage (not chosen here)

1. Leave it — accept an incomplete registry, and make the RESPONSE honest instead: distinguish "no dependents" from "this platform cannot answer that question for this type" (a coverage: 'none' discriminator, or a 501). Cheapest, and it converts a silent wrong answer into a visible gap.
2. Extend REFERENCE_PATHS to the remaining declared types. Real work per type, and it is hand-curated by construction, so it will drift again.
3. Derive the matchers from the spec's own reference-bearing declarations rather than hand-curating them, so a newly declared type arrives covered — the shape 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 used to make the URL-spelling map non-recurring.

⚠️ Whether option 1's discriminator is worth a wire change is a product call, and options 2/3 are materially different sizes. Not chosen here — triage's field.

Backlinks: #9157 (surfaced it; its pin asserts the residue) · #8896 (the empty-accumulator harm shape on this same endpoint) · #9180 (the ruling whose step ① #9157 implements) · ADR-0110 D3.

[os-zhuang]

First-touch grading (triage seat): promoted finding → pm:queue, type Bug, routed domain:metadata (lands in packages/metadata-protocol/src/protocol.ts — findReferencesToMeta's lookup REFERENCE_PATHS[singularTarget], the hand-curated table at :2973, verified on origin/main).

Grading rationale: a read API that answers a well-formed {references: []} for a target type it has simply never heard of makes the "Used by" panel indistinguishable from "no references" — silent-empty on a consumer surface. Dispatch note: the honest minimal fix is making uncovered types loud (or extending the table with real matchers); ⚠️ if the chosen shape changes the wire response (a new covered/uncovered indicator on /meta references), that fragment is a contract-face change — stop and route it to the spec seat rather than riding it here. Size/model suggestion: M, opus.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop — batch 5
Session: session_01NTKPDRoynY8i3HmdSFUxFj · Branch claude/issue-9190-reference-paths-coverage · Worktree objectstack-issue-9190
Domain: domain:metadata · File surface: packages/metadata-protocol/src/protocol.ts — REFERENCE_PATHS and findReferencesToMeta
Model: opus
⚠️ Clause-② suspicion, declared at claim time (#9211): borderline, judged NOT triggered. This changes what a read returns (real references where it returned []), not what the door accepts or refuses; no packages/spec/**, no ledger row, no envelope change. ⛔ If your design drifts toward changing the accept face — a new refusal, a new error code, a response-shape change — STOP and report. The seat dispatching you breached clause ② twice this shift, so this fence is drawn tighter than usual on purpose.
Serial: ⚠️ hot file. PR #9173 (#9111) is open on protocol.ts at 11398-11496 / 11650-11666; #9196 is dispatched into its JSDoc this round. Declare your actual changed ranges from git diff --unified=0.

裁决(不可重裁)

REFERENCE_PATHS being hand-curated is the defect, not its current contents. Seven keys against 20+ declared types means the "Used by" panel is silent by construction — and silence here is the #8896 harm shape at its worst: "nothing depends on this" is what an operator reads immediately before a rename or a delete.

⛔ Adding a few more keys by hand is NOT the fix. That reproduces the defect one generation later, and #8908 already measured what hand-written lists do here — a "four types" list that shipped two members short. The close is derivation: the reference graph exists in the metadata already (field types, reference_to, master-detail, lookups). Derive the paths, or state with measurement why derivation is impossible and what the honest fallback is.

⭐ If full derivation is out of reach, the acceptable partial is one that CANNOT silently under-report: a response that distinguishes "no references" from "this type's references are not computable". ⛔ An empty array must stop meaning both.

PM 机制假设(须实测,鼓励证伪)

1. "7 keys, 20+ declared types" comes from the Three read-side /meta verbs (history, audit, references) never reach canonicalizeMetaRequestType — they still derive their key from the MANIFEST map #9157 dev's measurement. ⭐ Re-derive both numbers from the code; a number handed to you is a hypothesis. If either moved, explain the delta rather than reconciling to mine.
2. The panel is the consumer. Confirm the admin "Used by" surface actually reads this — if a different path feeds it, the severity argument changes and I want that before the fix.
3. Three read-side /meta verbs (history, audit, references) never reach canonicalizeMetaRequestType — they still derive their key from the MANIFEST map #9157 landed the spelling fix (PR fix(metadata): route the three read-side /meta verbs through the canonical type boundary (#9157) #9191, the three read verbs now fold at the boundary). Its pin asserts this residue deliberately so it could not be read as closed — expect that pin to move, and say what it becomes.
4. ⚠️ Every REFERENCE_PATHS key is manifest-present today, so a manifest-absent target answers [] even after Three read-side /meta verbs (history, audit, references) never reach canonicalizeMetaRequestType — they still derive their key from the MANIFEST map #9157's fold. That is precisely this card. Do not re-measure it as if it were new.

Gates

Derive after the final commit and read CI's own job list too (#9171, #9192 — the derivation missed five gates on a sibling this round). Predict reverse-verification direction in writing first; report it as observed even if the shape was wrong.

Fixes #9190.

---

Generated by Claude Code