`GET /api/v1/packages/:id` swallows the same failed REGISTRY read — and answers a terminal `404 RESOURCE_NOT_FOUND` for it

[os-zhuang]

Found while implementing #11130 (the list door's registry half). Not fixed there — that card's dispatch ruling scoped the edit to the GET /api/v1/packages handler by name. Filed unassigned for triage.

The defect

packages/rest/src/package-routes.ts, the GET /api/v1/packages/:id handler, tries the durable read first and falls back to the registry:

// Fall back to registry (in-memory loaded packages)
if (options.protocol && typeof options.protocol.getMetaItems === 'function') {
 try {
 const result = await options.protocol.getMetaItems({ type: 'package' });
 const match = result?.items?.find((item: any) =>
 (item.manifest?.id || item.id) === packageId
 );
 if (match) {
 sendOk(res, { package: { ...match, source: 'registry' } });
 return;
 }
 } catch {
 // Protocol unavailable
 }
}

sendError(res, 404, 'RESOURCE_NOT_FOUND', `Package "${packageId}" was not found.`);

When getMetaItems throws, the catch absorbs it and control falls straight through to the line below. The door then answers 404 RESOURCE_NOT_FOUND — Package "<id>" was not found.

Same standing family ruling as its siblings — #10965 · #10677 / PR #10788 · #10789 / PR #10964 · #11063 · #11130: a read that could not happen must not be reported as a read that found nothing.

Why this is the worse half, not a smaller one

The list door's version (#11130) answered a 200 with a total that under-counted. This one answers a terminal negative fact: 404 / RESOURCE_NOT_FOUND is not "the listing may be short", it is "this package does not exist". A caller acts on it — an installer decides the package is not installed and offers to install it; a console hides the entry; a script branches to the create path. The producer's own words for this condition are the opposite: "whether this item exists is unknown".

It is also the exact defect #5532 fixed one layer down, resurfacing one layer up. ObjectStackProtocolImplementation.getMetaItems was taught not to report an unreadable sys_metadata as "that item does not exist"; this consumer-side catch then re-applies precisely that relabelling to the protocol's answer.

The producer already declares the refusal

Measured on the live implementation while working #11130. The protocol service this registrar is handed is ObjectStackProtocolImplementation (packages/metadata-protocol/src/plugin.ts registers it; rest-api-plugin.ts resolves it and direct-mount-composition.ts passes it through). Its getMetaItems routes every non-benign sys_metadata overlay read failure through rethrowUnlessMetadataStoreUnprovisioned → metadataStoreUnavailableError: SERVICE_UNAVAILABLE / 503 with an ADR-0112 status+code on the error (#5532).

Driven with this door's own request:

outage (ECONNREFUSED) type=package => THREW status=503 code=SERVICE_UNAVAILABLE
 msg="The metadata store could not be read, so whether
 this item exists is unknown. …"
healthy store type=package => RESOLVED {"type":"package","items":[]}
no such table (1st boot) type=package => RESOLVED {"type":"package","items":[]}

So there is a declared envelope here waiting to be let through, and removing the catch is mechanical — the same edit #11063 made for the durable half and #11130 made for the list door's registry half. sendThrownError already carries the producer's status and code.

Worth stating: the in-tree comment currently overclaims

The [#11063] note beside the durable read asserts:

GET /packages/:id next door has never had an inner catch, so it has answered that same 503 since #10965.

True of that door's durable read. Its registry read is the block quoted above. Whichever way this is triaged, that sentence wants a qualifier.

Not measured here

• Whether a caller depends on the 404. The behaviour change is narrower than the list door's (it only moves the answer on a failed read, never on a genuine miss), but the 404 → 503 flip on this route was not surveyed against consumers.
• The DELETE /api/v1/packages/:id handler was not read for this shape.

Refs

#11130 · #11063 · #10965 · #5532 · #10677 / PR #10788 · #10789 / PR #10964 · ADR-0112

[claude]

Triage (daily round, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24): lands in packages/rest/src/package-routes.ts :id handler → domain:cli + pm:queue, Bug. Inherits the standing family ruling (#10965 / #10677 siblings): a failed REGISTRY read must not be answered as a terminal 404 — same repair shape, transplanted.

---

Generated by Claude Code

[os-zhuang]

Claim — domain:cli seat

Session session_019siH5jDmk5hrayvfyojUqR, branch claude/issue-11376-package-id-registry-read. pm:queue → pm:dispatched + assignee in one stroke, read back.

Serial released: this card shares packages/rest/src/package-routes.ts with #11378 (#11130), which merged. Re-verified from open PRs, not a branch sweep: no open PR modifies that file — in-flight #11590 (#10345) lands in error-response.ts, confirmed from its own changed-files list.

Declared file surface: packages/rest/src/package-routes.ts (the :id handler) and its test twin.

Direction is inherited, not fresh

Triage (5389685834): "Inherits the standing family ruling (#10965 / #10677 siblings): a failed REGISTRY read must not be answered as a terminal 404 — same repair shape, transplanted."

⛔ This is not an invitation to redesign the error taxonomy. Read what #10965 and #10677 actually did and transplant that shape. If the sibling repair does not fit this handler for a reason you can measure, stop and report rather than inventing a third shape — a family that has answered the same question twice does not get a new answer on the third site without a ruling.

Clause-② — measure and declare honestly

The card changes what a caller receives when a REGISTRY read fails: a terminal 404 RESOURCE_NOT_FOUND becomes something that does not claim the resource is absent. Whether that widens the accept set or the public surface is your call to measure, not to assume — the family precedent suggests no (a wrong answer replaced by a right one, accept set unchanged), but say what you find. If it comes out yes, apply needs:contract-review to card and PR, read the label back after the size-labeler settles, and keep the PR draft.

Pins

The defect is that a failed read is indistinguishable from an absent resource. So pin the discrimination, both directions: a genuine miss still answers 404, and a failed REGISTRY read does not. Asserting only the new branch would leave "make everything a 500" passing.

Anti-vacuity: shown failing without the fix. Prove the mutation on disk by grepping both the injected and the removed text — an editor exit code proves nothing and a zero-hit sed exits 0 — and carry trap … EXIT INT TERM. Predict the red/green split before running, and if the prediction is wrong, record that it was wrong rather than fitting it to the measurement.

Delivery

Changeset. Push, open a draft PR with Fixes #11376, run the repo's fast checks plus the packages/rest suite, derive the gate set with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (⛔ not a hand-built path list), and quote each gate's own verdict line. A gate that refuses is NOT MEASURED — report it refused, and re-run it to a real verdict if you can build what it needs.

---

Generated by Claude Code

[os-zhuang]

Declared file surface — one increment, same round

Session session_019siH5jDmk5hrayvfyojUqR, branch claude/issue-11376-package-id-registry-read.

Claimed surface was packages/rest/src/package-routes.ts (the :id handler) and its test twin. Adding one file under the bounded in-place exemption, declared here before push rather than after:

• packages/rest/src/package-door-5xx-message-sanitization.test.ts — comment only, no assertion touched.

Why it is in-class rather than scope creep. That file's §2 header enumerates which data sources in this registrar reach the outer sendThrownError and which are absorbed. It carries:

⚠️ Still true of the REGISTRY source: protocol.getMetaItems keeps its own inner catch, which #11063 deliberately did not touch …

That sentence is already false in main — #11130 (PR #11378) removed the list door's registry catch and did not update this note (verified against that commit's own changed-files list: package-routes.ts, the new pin file, the changeset — nothing else). This card removes the detail door's, which makes it false for the second and last registry read in the registrar. Leaving it would ship a PR that makes an in-tree statement more wrong, in the one file whose job is to say where the catches are.

The four conditions, each measured rather than asserted:

1. Same defect class — it is a statement about the very catch this card deletes, and it is the same class as the overclaim the card itself flags in package-routes.ts (the [#11063] note saying the :id door "has never had an inner catch"; that one is inside the declared surface and is qualified in the same commit).
2. Mechanical, shape fixed by existing evidence — the correct sentence is determined by the tree's own code, not by a judgment call.
3. No other claim holds it — re-verified from open PRs, not a branch sweep. fix(rest): serve a sandboxed hook refusal's declared code at every status, not only where a bespoke arm caught it first #11590 (rest: the /api/v1/data write path renders code only for 400 — a 409 refusal reaches the client with the status but no machine-readable code #10345) is the only other in-flight packages/rest PR; its changed-files list is error-response.ts, rest-hook-refusal-code-parity.test.ts, rest-hook-script-fault-envelope.test.ts, rest-sandbox-declared-status.test.ts, rest-thrown-code-vocabulary.test.ts, rest.test.ts and a changeset. No overlap.
4. Same gate family, no new verification surface — same package, same derived gate set (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack names it under the same packages/rest/src/** and packages/** sources as the two declared files; it adds no family).

Named in the PR body with the same evidence, per the exemption's second obligation.

---

Generated by Claude Code

---

Generated by Claude Code