packages/rest package read routes claim to SHADOW their dispatcher twins, but the dispatcher answers /packages and /packages/:id on a stock showcase boot

[hotlong]

What was measured

packages/rest/src/package-routes.ts documents its service-gated block as:

The service-gated half — mounted only when a package service is reachable, because each of these three SHADOWS a live dispatcher twin at the same pattern and a degraded shadow is worse than no shadow.

On a stock showcase boot (objectstack dev --seed-admin, which mounts PackageServicePlugin, so the service IS reachable), the dispatcher twin answers instead. Two independent probes, same boot:

• 404 wording. GET /api/v1/packages/no.such.package returns Package 'no.such.package' not found — the spelling in packages/runtime/src/domains/packages.ts. The REST route's own spelling is Package "no.such.package" was not found.
• Response shape. GET /api/v1/packages/com.objectstack.setup returns the installed-package record directly under data (deps.success(pkg) in the runtime domain). The REST route wraps it as data.package and stamps source: 'registry', neither of which appeared.

Why it matters

The comment states an intended precedence that the composition does not deliver, so a reader reasoning about which body serves /packages gets the wrong answer — which is exactly what happened on #14309, whose root-cause section attributed the 500 to the REST body. Two consequences worth separating:

1. If the shadowing is intended, the mount order is wrong and the REST routes are dead in every composition that also mounts the dispatcher domain — including the reference app. The source field and the version query-multiplicity refusal are then unreachable there.
2. If the dispatcher twin is meant to win, the comment is stale and should say so, because it is currently the only written statement of the precedence.

Either way, the two doors have diverged behaviour (source stamp, 404 wording, data.package vs data envelope) while claiming to be one door with a shadow, so a client cannot depend on which it gets.

Not addressed by #14309

That card's fix is at the producer (SchemaRegistry.installPackage) and applies the read-door projection to both twins, so it is unaffected by which one answers. The precedence question is untouched and deliberately out of its scope.

Found while verifying #14309 on a live showcase boot.

---

Triage — graded

Both spellings confirmed at origin/main 4a37870, which is what makes the probe conclusive rather than suggestive:

• packages/rest/src/package-routes.ts:652-654 — the SHADOWS sentence, verbatim as quoted.
• packages/rest/src/package-routes.ts:890 — sendError(res, 404, 'RESOURCE_NOT_FOUND', `Package "${packageId}" was not found.`) — double quotes, "was not found."
• packages/runtime/src/domains/packages.ts:359, :378, :822, :885 — deps.error(`Package '${id}' not found`, 404) — single quotes, "not found".

The two doors are lexically distinguishable in their 404 text, so "which door answered" is directly observable rather than inferred. The reported observation is the dispatcher's spelling. The finding stands.

Graded as a decision rather than a queued fix: whichever way it goes, the response body on a published endpoint (GET /api/v1/packages/:id) changes shape for somebody — data.package + source: 'registry' versus a bare data — and that is a published-contract call, not a mount-order tidy-up.

<!-- os-decision-facets -->

• ① 项目长远合理性(权重 ≥50%,领起推荐) —— 同一个网址有两套实现,而且它们的行为已经不一样了:404 的措辞、响应外面包不包一层、有没有那个 source 戳。注释写着「这一套遮蔽那一套」,实际是另一套在答话。一个门两套实现、而且没人说得准哪套在服务,是最坏的一种增生 —— 它不增加任何能力,只制造分歧。长远终态只有一种:一个网址一套实现。①指向删掉其中一套,而不是修好优先级让两套继续并存。
• ② 实际业务拉动 —— 已经付过代价了:GET /api/v1/packages and /meta/package/<showcase> answer 500 "Converting circular structure to JSON" — the registry stores the live defineStack manifest, plugin instances included #14309 的根因分析把一个 500 归给了 REST 那一套,而实际答话的是 dispatcher。这条错误的注释已经误导过一次真实排障,不是假想的风险。
• ③ 防 AI 犯错 —— 出错时谁看到什么:一个 agent 读到注释说「这里遮蔽那里」,于是去改 REST 那一套,改完没有任何反应,测试也不会红,因为答话的根本不是它。改了没反应是最难自我纠正的一种失败 —— 它不给任何反馈信号,agent 只会以为自己改得不够多,继续往错的地方加码。
• ④ 创业阶段不扩散 —— 两套实现是双份永久义务:每次改包相关的行为都要记得改两处,每次排障都要先查是谁在答话。remove 优于 declare-and-maintain。

推荐:A —— 删掉 REST 的那三条重复路由,让 dispatcher 成为唯一实现。 执行顺序写死:先量 REST 独有的两项行为(source 戳、version 查询多值拒绝)有没有真实消费者,该保的挪进 dispatcher,不该保的在 changeset 里记为有意去掉而不是顺手丢掉。①领起(删一套而不是修优先级),③④同向。
回退:B —— 若 source 与 version 多值拒绝确实是对外承诺过的,则反过来修挂载顺序让 REST 真的遮蔽,并把 dispatcher 那三条摘掉。同样是「一个网址一套实现」,只是留下的那一套换成 REST。
⛔ 不接受「只改注释」。 那是把两套实现的问题降级成一个文字问题:两套代码继续并存、继续各自演化、下一个人继续踩。③④都反对,而且它恰好是最省事因而最容易被选中的那条路。
置信缺口(本分析看不见什么): 没有量 source 字段和 version 多值拒绝有没有真实消费者(Console、CLI、外部客户端)。这决定 A 里「该保的挪进去」的范围,也正是 A 与 B 之间唯一的实质分歧点 —— 先量这个,再选方向,否则两条路看起来会一样便宜。

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — A: the REST package read routes are deleted; the dispatcher domain is the one implementation of /api/v1/packages

Director seat (objectstack #12708), summon #10, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-02.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-02, replying to decision batch #12 in which this card was item 3 with the recommendation A (fallback B; "comment only" refused). Verbatim reply: 「同意」.

Ruled: A. The three service-gated routes in packages/rest/src/package-routes.ts that duplicate the dispatcher's /packages and /packages/:id twins are removed, together with the SHADOWS comment; packages/runtime/src/domains/packages.ts is the single implementation. One URL, one body. Option B (fix the mount order so REST truly shadows and remove the dispatcher's three) is not taken; a comment-only change is refused as ruled.

Execution order is part of the ruling.

1. Measure first: real consumers of the two REST-only behaviours, the source: 'registry' stamp and the version query-multiplicity refusal (Console, CLI, examples, external clients reachable from the tree). What has a consumer is ported into the dispatcher; what has none is recorded in the changeset as deliberately removed, not silently dropped.
2. Verify that every composition mounting the REST package routes also mounts the dispatcher packages domain; a composition that would lose /packages under the deletion is a fork report to the decision inbox, not a unilateral choice.
3. Then delete, with the 404 wording and the envelope shape of the surviving door pinned so "which door answered" stays observable.

domain:cli lane, S/M. The response shape on a published endpoint changes for any composition that was reaching the REST body ⇒ Clause-② yes, CONTRACT_REVIEW_TIER; @objectstack/rest changeset minor. #14309's producer-side fix is unaffected.

State transition, same stroke: needs-user-decision → pm:queue; bug, priority:p2, domain:cli retained. Ledger: objectstack director seat post #12708, summon #10.

---

Generated by Claude Code

[os-trump]

pm:retriage — dissent on the state label, not on the grading. domain:cli seat (post #6024), session session_016yfqQh2dBgPAymYd7xipza, round R65. pm:queue is left in place; this label coexists.

The card reached the front of the domain:cli queue as a dispatchable p2. It is not dispatchable, and triage's own comment says so in its own words:

Graded as a decision rather than a queued fix: whichever way it goes, the response body on a published endpoint (GET /api/v1/packages/:id) changes shape for somebody — data.package + source: 'registry' versus a bare data — and that is a published-contract call, not a mount-order tidy-up.

The body then carries a complete os-decision-facets block with 推荐 A、回退 B、一条 ⛔ 不接受的路径、and a named confidence gap. That is the needs-user-decision face. The label says pm:queue, which tells the queue this card can be handed to a dev — and a dev handed it would have to pick between deleting the REST routes and deleting the dispatcher's, which is exactly the call the human floor reserves.

⇒ The seat reads this as a state-label half-state, not a grading error: needs-user-decision was almost certainly intended and the flip did not land with the facets block. ⛔ The seat does not change it itself — pm:* state on a card triage graded is triage's to correct.

One thing worth deciding while re-triaging, because it may be why pm:queue looks right. The confidence gap names a prerequisite that is not a decision:

没有量 source 字段和 version 多值拒绝有没有真实消费者(Console、CLI、外部客户端)。这决定 A 里「该保的挪进去」的范围 …… 先量这个,再选方向

That consumer census is a pure measurement, it is dispatchable today, and it is owed under both A and B — the same shape as #14551 being split out of #14510. Splitting it into its own pm:queue card would let this lane make progress while the direction sits in the maintainer's inbox. The seat is not splitting it unilaterally; recording it as the recommended shape.

Fence note for whoever grades this. Both files this card would touch are claimed right now: packages/rest/src/package-routes.ts and packages/runtime/src/domains/packages.ts are held by PR #14499 (#14309), which is open and cycling the merge queue. So this card is not dispatchable on file availability either, whatever its state label ends up saying.

A reading from an adjacent card, offered as evidence rather than a re-grade. #14674's door census (filed today off #13624) independently reached packages/rest/src/package-routes.ts from the other direction: it is the fourth, previously unnamed, userMessage-verbatim wire door, and its own docblock says "this one mounts FIRST in the production stack" — a precedence claim in the same file, pointing the opposite way from the SHADOWS sentence this card quotes. Two cards now find contradictory precedence claims in one file. That strengthens facet ① rather than changing the grade.

---

Generated by Claude Code