Found while repairing the organization forwarding on this same door (#13753); recorded rather than fixed, because it is a different defect class and changes what an operator reads on the wire.
What is wrong
GET /api/v1/meta/:type/:name/references can refuse in two ways, and the two answers do not agree on either the envelope or the message.
Refusal A — the protocol cannot answer for this target type (REFERENCE_SITES.unanswerableTargetTypes, today exactly field). findReferencesToMeta throws an Error carrying code: 'NOT_IMPLEMENTED' / status: 501 and a deliberately prescriptive message that names the answerable question:
References to a 'field' item cannot be computed. A 'field' is addressed by the composite key ... Ask the owning object instead: GET /api/v1/meta/object/account/references.
Measured on main (driven through the real route in packages/rest/src/rest-server-meta-read-org-scope.test.ts), what reaches the caller is:
501 {"error":"Internal server error","code":"NOT_IMPLEMENTED"}
The prescriptive sentence is gone. handleRouteError routes any producer-declared 5xx through declaredServerFaultAnswer (packages/rest/src/error-response.ts), which keeps status and code and replaces the prose with INTERNAL_ERROR_MESSAGE — correct and argued for a server FAULT (#11718, #5582), and this refusal is not one.
Refusal B — the resolved kernel has no findReferencesToMeta at all (#9326). The same route hand-builds the ADR-0112 NESTED envelope and its message survives:
501 {"error":{"code":"NOT_IMPLEMENTED","message":"protocol.findReferencesToMeta() is not available in this kernel"}}
Why it matters
Both refusals exist for the SAME reason: this route backs the admin "Used by" panel, whose empty case renders "Nothing in the metadata graph points at this item. Safe to delete." to an operator about to delete something, so "the question was never asked" must never be answered as "nothing depends on it" (ADR-0110 D3, #8896). The A-refusal's message is the part that tells the operator what to ask INSTEAD — reference-sites.ts says so in as many words: the message is prescriptive per ADR-0110 D3 because a field's dependents are reachable through the object that owns it. On the wire that instruction is replaced by "Internal server error".
Second, the two shapes disagree on where the code lives: body.error.code reads the code on B and undefined on A. The door's own comment for B warns against exactly that ("never the bare-string or sibling-code dialects, which make body.error.code read undefined") — and A is that dialect, arriving by a different path.
Reproduce
pnpm --filter @objectstack/rest exec vitest run src/rest-server-meta-read-org-scope.test.ts -t 'unanswerable-target'
That pin reads the code through BOTH dialects on purpose, so it stays green either way; it is a pin on this route's refusal, not on this finding.
Not decided here
Whether the repair is (a) a deliberate refusal being distinguished from a server fault at the relay — a producer-declared 5xx that is a REFUSAL keeps its prose — or (b) this route's protocol-raised refusal being caught and re-answered in the nested envelope the sibling already uses, or (c) the refusal moving off 5xx entirely. Any of the three changes an observable wire answer, which is why this is filed rather than ridden along on #13753.
Out of scope for #13753
That card is the organization the door forwards to the reference sweep; nothing in it moves a status code, a response field, or a refusal message.
Generated by Claude Code
Found while repairing the organization forwarding on this same door (#13753); recorded rather than fixed, because it is a different defect class and changes what an operator reads on the wire.
What is wrong
GET /api/v1/meta/:type/:name/referencescan refuse in two ways, and the two answers do not agree on either the envelope or the message.Refusal A — the protocol cannot answer for this target type (
REFERENCE_SITES.unanswerableTargetTypes, today exactlyfield).findReferencesToMetathrows anErrorcarryingcode: 'NOT_IMPLEMENTED'/status: 501and a deliberately prescriptive message that names the answerable question:Measured on
main(driven through the real route inpackages/rest/src/rest-server-meta-read-org-scope.test.ts), what reaches the caller is:The prescriptive sentence is gone.
handleRouteErrorroutes any producer-declared 5xx throughdeclaredServerFaultAnswer(packages/rest/src/error-response.ts), which keepsstatusandcodeand replaces the prose withINTERNAL_ERROR_MESSAGE— correct and argued for a server FAULT (#11718, #5582), and this refusal is not one.Refusal B — the resolved kernel has no
findReferencesToMetaat all (#9326). The same route hand-builds the ADR-0112 NESTED envelope and its message survives:Why it matters
Both refusals exist for the SAME reason: this route backs the admin "Used by" panel, whose empty case renders "Nothing in the metadata graph points at this item. Safe to delete." to an operator about to delete something, so "the question was never asked" must never be answered as "nothing depends on it" (ADR-0110 D3, #8896). The A-refusal's message is the part that tells the operator what to ask INSTEAD —
reference-sites.tssays so in as many words: the message is prescriptive per ADR-0110 D3 because a field's dependents are reachable through the object that owns it. On the wire that instruction is replaced by "Internal server error".Second, the two shapes disagree on where the code lives:
body.error.codereads the code on B andundefinedon A. The door's own comment for B warns against exactly that ("never the bare-string or sibling-codedialects, which makebody.error.codereadundefined") — and A is that dialect, arriving by a different path.Reproduce
That pin reads the code through BOTH dialects on purpose, so it stays green either way; it is a pin on this route's refusal, not on this finding.
Not decided here
Whether the repair is (a) a deliberate refusal being distinguished from a server fault at the relay — a producer-declared 5xx that is a REFUSAL keeps its prose — or (b) this route's protocol-raised refusal being caught and re-answered in the nested envelope the sibling already uses, or (c) the refusal moving off 5xx entirely. Any of the three changes an observable wire answer, which is why this is filed rather than ridden along on #13753.
Out of scope for #13753
That card is the organization the door forwards to the reference sweep; nothing in it moves a status code, a response field, or a refusal message.
Generated by Claude Code