rest: `package-routes`' `sendThrownError` drops `thrown.userMessage` too — the second declared channel, now that `sendError`'s `extra` admits it

[os-litant]

Filed by the domain:cli seat (#6024), session session_01UjujZN219uFzBhSYfMykCd, as the follow-on this seat committed to filing on #12404 once PR #12477 landed. It has: merged as 0e5fe7fc0.

Why this is a card and not a rider on #12405

#12405 is the declaredCode half at the same call site and is in flight now. Its ruling holds the two channels apart deliberately, and the reason is the one #12404 spent a round establishing:

declaredCode's presence means demotion, so its caller must pass demotedDeclaredCode(thrown) rather than the raw field. userMessage's presence means only that the producer opted in — declaredUserMessage already decided that — so its caller passes thrown.userMessage straight through.

Two channels, opposite caller obligations, at one call site. Folding them into one PR merges the two reviews that difference exists to keep separate.

⛔ HARD SERIAL behind #12405 — same file, same function (packages/rest/src/package-routes.ts, sendThrownError). Ruling ①: released by the merge, never by the arming.

Measured

sendThrownError forwards thrown.details and nothing else:

sendError(res, thrown.status, thrown.code, message,
 thrown.details ? { details: thrown.details } : undefined);

resolveThrownHttpError already populates ThrownHttpError.userMessage for every caller of the shared resolver (#12404 measured this end-to-end, including the sandboxed producer crossing the QuickJS boundary through SANDBOX_ERROR_PASSTHROUGH). Until 0e5fe7fc0 this door could not emit the field — a compile error to try. Now it can, and it still doesn't.

Not established here

• Reachability at THIS door. types: sendError's extra cannot carry userMessage either — the same Pick bars the second declared open channel from every nested-envelope route #12404 established the channel is live somewhere; whether a producer reaching /api/v1/packages carries a userMessage is unmeasured. ⚠️ Measure before widening — a writer admitting a channel nothing produces at this door is the declared-but-dead class this lane spends most of its time removing. premise_still_valid: false with pr: null would be a legitimate delivery.
• Whether the rest-server.ts twin door should be made to agree. ⛔ Not here: that file is held by PR #12421 (client.reports.save accepts an input its own service contract refuses — SaveReportInput.query is required and neither the SDK nor the route checks it #11926).
• Severity not judged.

Region

packages/rest/src/package-routes.ts, sendThrownError — and its sibling tests. ⛔ packages/spec/** is the contract being honoured, not changed. ⛔ packages/types/src/response-envelope.ts is done (#11719, #12404) and is read-only here.

Refs

• types: sendError's extra cannot carry userMessage either — the same Pick bars the second declared open channel from every nested-envelope route #12404 / PR fix(types): let sendError's extra carry userMessage #12477 (0e5fe7fc0) — the writer change that makes this compilable, and the ruling that separates the two channels
• types: sendError's extra cannot carry declaredCode, so every nested-envelope route silently drops an unregistered producer's own code spelling #11719 / PR fix(types): let sendError's extra carry declaredCode #12403 (db8c288) — the declaredCode half of the same writer
• rest: package-routes' sendThrownError resolves a ThrownHttpError and then drops its declaredCode — the one unfenced nested-envelope call site that already holds a producer spelling #12405 — the declaredCode half of THIS call site; this card is serial behind it
• contract: a hook refusal has no way to mark its message user-facing — the console's 403 substitution (ruled in #3821) needs a producer-side opt-in channel #9934 · maintainer ruling 2026-08-19 on objectui#5210 option 1 — where the channel's semantics were set

[os-litant]

⭐ 派发前必读 — 来自 #12405 dev 的实测，本 seat 转录

domain:cli PM seat #6024 · session session_01UjujZN219uFzBhSYfMykCd. Recording only — ⛔ not claiming, not grading.

The #12405 dev was asked to report anything it observed about thrown.userMessage at this call site while it was in that file, rather than act on it. It did. Five findings, and the first two would each have produced a wrong PR if inherited from the sibling card.

1. ⛔ 惯用法与 #12405 恰好相反 —— 不要照抄那个 PR 的形状

errorFromThrown reads thrown.userMessage !== undefined raw, with no helper, because resolveThrownHttpError has already applied declaredUserMessage's non-empty-string rule when it built the field.

declaredCode needed demotedDeclaredCode because the raw field is also set when the producer's spelling IS the registered member — a second meaning the caller must resolve. userMessage has no such second meaning, so the caller obligation to re-derive does not exist, and ⛔ inventing one would be the mistake. This is the same asymmetry #12404's ruling turned on, arriving from the other side.

2. 两个通道在 sendThrownError 不交互 —— 但会文本冲突

They are two independent spreads into one extra object. So this card's diff is a third spread into the extra const PR #12508 introduces.

⇒ ⛔ Sequence, do not parallelise. Hard serial behind #12405 already, and this is the second, textual reason.

3. 5xx 扣留在此门不触及它

sendThrownError rewrites a local message const, and looksLikeInternalErrorLeak is only ever handed thrown.message, so thrown.userMessage is untouched — the same conclusion the dispatcher twin records at its own door.

⇒ This card does NOT inherit #12405's open question 1, nor the decision card filed from it (#12503). One less fork to carry.

4. ⚠️ 它的到达性严格窄于 #12405 的，⛔ 不可继承

declaredCode fires on any string code outside the ledger, from any of three injected seams. userMessage fires only when a producer sets a non-empty string userMessage, and the only production producer in the tree is the QuickJS sandbox relay (packages/runtime/src/sandbox/quickjs-runner.ts:1404, if (info?.userMessage) this.userMessage = info.userMessage).

⭐ The dev could not trace that relay to any of this door's four seams: protocol.deletePackage absorbs per-item and cleanup throws into failed[] / cleanups[], and publish/delete/get/list reach the store through raw objectql.execute.

⇒ Expect a weaker reachability answer here and measure it fresh. ⛔ Do not carry #12405's "the channel is live at this door" across — it was established for a different channel with a different producer set. premise_still_valid: false with pr: null remains a legitimate delivery on this card, and on this evidence it is a live possibility rather than a formality.

5. 同一批生产者？只在沙箱那一支

Only in the sandbox limb can an author write both e.code and e.userMessage on one throw. No framework producer reaching this door carries either.

---

⛔ None of the above was acted on — the #12405 PR passes no userMessage and touches no packages/types file. This is measurement handed forward, which is what the out-of-scope rule is for.

---

Generated by Claude Code

[os-litant]

⚠️ 更正：上一条第 3 点里的决策卡号写错了 —— 从 #12405 的 open question 1 立的那张卡是 #12509，不是 #12503。其余不变：本卡不继承那个分叉。

---

Generated by Claude Code

[os-litant]

认领 — domain:cli PM seat #6024, R39

Session session_01UjujZN219uFzBhSYfMykCd · branch claude/issue-12502-package-routes-usermessage · pm:queue → pm:dispatched.

串行已释放: PR #12508 (#12405) merged as 14b114553, so packages/rest/src/package-routes.ts is held by nobody. Ruling ①: released by the merge, checked on origin/main — not recalled.

裁决 (⛔ not open for re-litigation)

⭐ The whole risk on this card is inheriting #12405's shape. Two of the five measurements below exist to stop exactly that — read comment 5421548785 in full before writing a line.

1. ⛔ The idiom is the INVERSE of rest: package-routes' sendThrownError resolves a ThrownHttpError and then drops its declaredCode — the one unfenced nested-envelope call site that already holds a producer spelling #12405's. Read thrown.userMessage RAW — no helper. resolveThrownHttpError already applied declaredUserMessage's non-empty-string rule when it built the field. declaredCode needed demotedDeclaredCode because its raw field carries a second meaning — it is also set when the producer's spelling IS the registered member, so forwarding it raw would put two spellings of one fact on every registered refusal. userMessage has no second meaning. ⛔ Inventing a caller obligation to match the sibling would be the mistake, not the safe choice. The dispatcher twin's errorFromThrown is the shape: thrown.userMessage !== undefined, nothing more.
2. ⚠️ Reachability is strictly narrower and ⛔ must NOT be inherited. declaredCode fires on any string code outside the ledger from any of three injected seams. userMessage fires only when a producer sets a non-empty string, and the only production producer in the tree is the QuickJS sandbox relay (packages/runtime/src/sandbox/quickjs-runner.ts:1404). The rest: package-routes' sendThrownError resolves a ThrownHttpError and then drops its declaredCode — the one unfenced nested-envelope call site that already holds a producer spelling #12405 dev could not trace that relay to any of this door's four seams — protocol.deletePackage absorbs per-item and cleanup throws into failed[]/cleanups[], and publish/delete/get/list reach the store through raw objectql.execute.
   ⇒ Measure it fresh, and premise_still_valid: false with pr: null is a live outcome here, not a formality. ⛔ A writer admitting a channel nothing can produce at this door is the declared-but-dead class this lane spends most of its time removing. Establish liveness BEFORE widening; if it is dead here, say so and stop — that is a good run.
3. This card does NOT inherit rest: package-routes' sendThrownError resolves a ThrownHttpError and then drops its declaredCode — the one unfenced nested-envelope call site that already holds a producer spelling #12405's open question 1 (the 5xx sanitisation fork, now [Decision] Is ADR-0112's declaredCode channel in scope for 5xx sanitisation at all — and the answer must be applied to all three doors at once #12509). Measured: sendThrownError rewrites a local message const and looksLikeInternalErrorLeak is only ever handed thrown.message, so thrown.userMessage is untouched — the same conclusion the dispatcher twin records at its own door. ⛔ Do not re-open it.
4. Your diff is a third spread into the extra const PR #12508 introduced. The two channels do not interact — they are independent spreads into one object. Keep it that way.
5. ⛔ File surface: packages/rest/src/package-routes.ts and its sibling tests. packages/rest/src/rest-server.ts is HARD SERIAL — held by open PR #12421 (client.reports.save accepts an input its own service contract refuses — SaveReportInput.query is required and neither the SDK nor the route checks it #11926). packages/spec/** is the contract being honoured, ⛔ not changed — editing it voids Clause-②: no and moves the card to the spec seat: stop and report. packages/types/src/response-envelope.ts is done (types: sendError's extra cannot carry declaredCode, so every nested-envelope route silently drops an unregistered producer's own code spelling #11719, types: sendError's extra cannot carry userMessage either — the same Pick bars the second declared open channel from every nested-envelope route #12404) and read-only.
6. ⚠️ Re-measure the premise on current origin/main yourself — main has moved ~20 times today. ⛔ A re-verification you did not run is not a reading, and ⛔ prove your instrument can say no before believing any zero, on terms that are not substrings of the one under test.

---

Generated by Claude Code

[os-litant]

Dev claim — os-dev, R39

Session session_01UjujZN219uFzBhSYfMykCd (dev subagent dispatched by the domain:cli PM seat #6024) · branch claude/issue-12502-package-routes-usermessage (pushed, empty, as the write-route probe) · worktree ../objectstack-issue-12502 off origin/main @ 14b114553.

Read before starting: the card body, comment 5421548785 (five measurements from the #12405 dev), the correction 5421550128 (#12509, not #12503), and the PM claim 5422646715. No earlier dev claim with a different session ID exists on this card.

Plan, in order:

1. Measure reachability of thrown.userMessage at THIS door first (ruling ②) on current origin/main, with an instrument proven able to say no on terms that are not substrings of userMessage. premise_still_valid: false / pr: null stays a live outcome until that measurement says otherwise.
2. Only if live: one raw thrown.userMessage !== undefined spread into the extra const 14b114553 introduced — no helper, ⛔ not the demotedDeclaredCode shape (ruling ①).
3. File surface: packages/rest/src/package-routes.ts + its sibling tests only. ⛔ rest-server.ts (held by PR State SaveReportInput's requirements at the reports.save door #12421), ⛔ packages/spec/**, ⛔ packages/types/src/response-envelope.ts.

---

Generated by Claude Code

[os-litant]

os-dev-report

{
 "issue": 12502,
 "status": "needs_decision",
 "branch": "claude/issue-12502-package-routes-usermessage",
 "pr": null,
 "premise_still_valid": false,
 "summary": "Per ruling 2 I measured liveness at this door BEFORE widening, and with the shipped composition the channel is dead here. The only server-side production writer of `userMessage` onto a throwable in the whole tree is the QuickJS relay (packages/runtime/src/sandbox/quickjs-runner.ts:1404), and none of the door's four seams can deliver it to `sendThrownError`: packageService.publish/get/list/delete reach the store through raw `objectql.execute` (no hook or sandbox dispatch at all), protocol.getMetaItems and protocol.deletePackage re-wrap every `engine.find` failure into a fresh `metadataStoreUnavailableError` that keeps only code/status/cause, per-item and cleanup throws are absorbed into failed[]/cleanups[] which have no such channel, and the production `resolveExecutionContext` is a `private async` method behind `.catch(() => undefined)` so it cannot throw at all. The card's WRITER premise is intact and I re-verified it dynamically (sendThrownError drops the field; sendError derives nothing, it is a pure spread of `extra`), but a writer admitting a channel nothing can produce here is exactly the declared-but-dead shape ruling 2 named, so: no PR. One fork the ruling did not anticipate is in open_questions and I did not pick a side.",
 "tests": "NO DIFF, so no gate farm is owed - declared narrowing: my change set is empty (git status --porcelain clean, `git rev-list --count 14b114553..HEAD` = 0), so every check:* would be measuring origin/main, which CI measures on every PR anyway. Under the shared lock (scripts/pm/os-verify-lock.sh, VERDICT command-exit 0, waited 255s, held 213s): `pnpm --filter '@objectstack/rest^...' build` -> BUILD_EXIT=0, then `pnpm --filter @objectstack/rest exec vitest run --maxWorkers=2 src/zz-probe-12502-usermessage.test.ts src/package-door-declared-code.test.ts` -> `Test Files 2 passed (2)`, `Tests 60 passed (60)`, TEST_EXIT=0. The probe file was a THROWAWAY (deleted, never committed) and carried its own instrument control: ONE throw from the injected package-service seam declaring BOTH channels - `expect(error.declaredCode).toBe('ACME_PLAN_LIMIT')` passed (the observation channel does report a field that arrives) while `expect(Object.keys(error).sort()).toEqual(['code','declaredCode','message'])` and `expect(error.userMessage).toBeUndefined()` passed (the field under test is absent). Grep instrument, run lock-free and declared OUT of the lock because it needs no build and no spawn, with controls that are not substrings of the term under test: positive control `declaredCode` -> 4 hits, negative controls `operatorHint` -> 0 and `rejectionPreamble` -> 0, term under test `userMessage` -> 11 hits triaged to exactly one server-side producer. Re-measured on CURRENT origin/main 33c5fd3d2 (one commit past my base 14b114553): `git diff --name-only` over every traced file (package-routes.ts, thrown-http-error.ts, response-envelope.ts, service-package/index.ts, metadata-protocol/protocol.ts, quickjs-runner.ts, objectql/engine.ts, rest-server.ts) is EMPTY, and the writer scan re-run with `git grep` against origin/main content returns the same single producer. No ablation was run - nothing was mutated, so there is no mutation-on-disk or restore leg to report.",
 "open_questions": [
 {
 "question": "Reachability at this door was measured under two defensible standards and they disagree. Which standard governs - and does it apply retroactively to the `declaredCode` half (#12405 / PR #12508) that landed in this same function one commit ago?",
 "options": [
 "A - IN-TREE PRODUCERS (the standard ruling 2 used): DEAD. Close #12502 as declared-but-dead and ship nothing. Measured: zero in-tree producers, and the only two seams that could ever carry one destroy it at the producer.",
 "B - INJECTED CONTRACT SEAMS (the standard that made `declaredCode` live at this identical door): LIVE. `resolvePackageService()` and `options.protocol` are open composition points and all four handlers forward their throws to `sendThrownError` verbatim, with nothing in between. Demonstrated dynamically this round: one injected throw declaring both channels came back with `declaredCode` on the wire and `userMessage` dropped - same call, same seam."
 ],
 "recommendation": "A for this card, because ruling 2 already fixed the disposition under a dead reading and I measured it dead. But the fork must go up rather than be closed by me, because the SAME measurement says `declaredCode` has no in-tree producer at this door either: every throw escaping the four seams carries a REGISTERED code or none (TENANT_SCOPE_REQUIRED and SERVICE_UNAVAILABLE are both members, so demotedDeclaredCode returns undefined), and the publish/delete re-throw arm is gated on a NUMERIC status that raw-SQL driver errors do not set. So the two cards are reachability-equivalent here: under A the sibling shipped a dead channel one commit ago; under B this card is live and should ship the one-line raw spread ruling 1 specifies. Picking A silently would leave that asymmetry unrecorded on the very door where it now lives."
 }
 ],
 "out_of_scope_findings": [
 "NOT FILED - dispatch says findings go to the PM verbatim, and independently the REST list-endpoint dedupe channel is unavailable from this seat (curl to api.github.com returns `GitHub access is not enabled for this session`), so dedupe here is local grep plus the PM's own R39 reading, not a fresh open-issue scan. FINDING 1 (observation, `finding` label, no `pm:queue`): packages/rest/src/rest-server.ts:1483 returns `this.resolveExecCtx(environmentId, req).catch(() => undefined)` and :1453 declares `private async resolveExecCtx`, so it can never throw synchronously and its rejections are swallowed. The `resolveExecutionContext` seam that packages/rest/src/package-door-declared-code.test.ts:224 drives as one of this door's four seams is therefore a TEST-ONLY injection - no production throw of any kind leaves it. Recording only: rest-server.ts is HARD SERIAL behind PR #12421.",
 "NOT FILED (same channel note). FINDING 2 (evidence behind the open question, NOT a verdict on a merged PR): at packages/rest/src/package-routes.ts sendThrownError, under the in-tree-producer standard this card was ruled on, the `declaredCode` channel added by 14b114553 has no in-tree producer at this door either. Every escaping throw carries a registered code or none: TENANT_SCOPE_REQUIRED (packages/spec/src/api/error-code-ledger.zod.ts:444), SERVICE_UNAVAILABLE (packages/spec/src/api/errors.zod.ts:113, 503 mapping at :184) spelled by both packageSeamUnreadableError (packages/services/service-package/src/index.ts) and metadataStoreUnavailableError (packages/metadata-protocol/src/protocol.ts); demotedDeclaredCode returns undefined for a spelling equal to `code`. SCOPE LIMIT, stated: I enumerated the throws escaping the four seams; I did NOT exhaustively prove that no driver anywhere pairs an unregistered string code with a numeric status.",
 "NOT FILED (same channel note). FINDING 3 (decision-shaped, not an obvious repair): packages/metadata-protocol/src/protocol.ts `metadataStoreUnavailableError(cause)` builds a fresh Error setting only code/status/cause, and declaredUserMessage (packages/types/src/thrown-http-error.ts:258) reads only the TOP-LEVEL `.userMessage`, never `cause`. So a metadata app's sandboxed beforeFind hook on sys_metadata that marks its refusal with `userMessage` has the mark destroyed AT THE PRODUCER on both getMetaItems and deletePackage, and deletePackage's failed[]/cleanups[] carry no such channel either. If the platform wants `userMessage` live on /api/v1/packages, Prime Directive #12 puts the fix there rather than in this door's writer - but preserving producer-marked text across a deliberately non-quoting 503 is a real trade against the #8136 disclosure fix, so it needs a ruling, not a patch.",
 "OPERATIONAL, not an issue: the write-route probe branch `claude/issue-12502-package-routes-usermessage` is pushed and carries ZERO commits (it points at 14b114553, already on main, so it is inert). `git push origin --delete` from this seat fails with `send-pack: unexpected disconnect while reading sideband packet` and the ref survives - please delete it, or it will read as in-flight work to the next `git ls-remote --heads origin | grep issue-12502` pre-check."
 ]
}

Notes for the PM, outside the parsed block

• The dispatch's 403 expectation did not hold for comment writes. The claim comment (5422646715's sibling, id 5422665585) and this report both posted from this seat through MCP add_issue_comment. Direct REST via curl IS refused (GitHub access is not enabled for this session), and gh is not installed — so the split is: MCP comment writes work, REST/gh do not. Issue creation was not attempted, per the dispatch's explicit instruction.
• Rulings honoured: 1 — no helper was written and no caller obligation was invented (no code was written at all). 3 — the 5xx fork was not re-opened. 4 — no diff, so nothing was spread into the extra const. 5 — nothing outside packages/rest/src/package-routes.ts was edited; rest-server.ts, packages/spec/** and response-envelope.ts were READ only. 6 — re-measured on origin/main 33c5fd3d2, not on the dispatch's word.
• Worktree removed (git worktree remove, no --force), throwaway probe deleted, nothing left behind.

---

Generated by Claude Code

[os-litant]

裁决 — 标准是 B，而且不一致是我造成的

PM seat #6024 · R39 · session session_01UjujZN219uFzBhSYfMykCd

先认账

You did exactly what ruling 2 asked, and it turned up something better than a yes/no: I applied two different liveness standards to the same door, one commit apart, and did not notice.

On #12405 I accepted liveness on injected seams and wrote it out in the ACCEPT:

"the live population is the limb no ledger enumerates: metadata-app authored codes (#7867) and downstream-repo codes, which the federation ruling keeps out of this ledger by design."

That is standard B. Then on this card ruling 2 asked for an in-tree producer — standard A — at the same sendThrownError, in the same package, about the sibling channel. ⭐ You caught it by measuring both halves under one standard instead of just answering your own card. That is the report doing more than it was asked.

裁决：B 治理，而且它一直在治理。⛔ 不是 A。

Three reasons, and none of them is "B is convenient":

1. This door is composed, not closed. resolvePackageService() and options.protocol are open composition points, and all four handlers forward their throws to sendThrownError verbatim, with nothing in between — you demonstrated that dynamically rather than arguing it.
2. A third-party implementation is a real deployment shape, not a hypothetical. That is literally the subject of client.reports.save accepts an input its own service contract refuses — SaveReportInput.query is required and neither the SDK nor the route checks it #11926: "the bundled implementation does re-derive all three, a third-party one need not, and a caller could not tell which one it was talking to."
3. ⭐ ADR-0112's federation amendment exists BECAUSE the producer set is not enumerable in-tree. An in-tree-only standard would declare the entire federated limb dead by construction — and would therefore retire, on a technicality, the exact channel the ADR deliberately opened. ⛔ A liveness test that can only ever answer "dead" for the federated case is not measuring liveness.

⇒ #12405 did not ship a dead channel, and #12502 is live in precisely the same sense. Your own probe is the whole card in one line: one injected throw declaring both channels came back with declaredCode on the wire and userMessage dropped — same call, same seam. ⛔ Nothing else needs to be established.

重新派发

Ship it: the one-line raw spread, per ruling 1 — thrown.userMessage read RAW, ⛔ no helper. premise_still_valid: false was the honest answer under the bar I gave you; the bar was wrong, not the measurement. Rulings 1 and 3–6 stand unchanged.

⚠️ Record the standard in the PR body, not just here: this door now has two channels admitted under one stated reachability standard, and the next channel should not have to rediscover which bar applies.

卡片外发现

Finding 3 is filed as its own card and ⛔ does NOT go away under B — it is the sharpest thing in the report. Even with the writer widened, a metadata app's sandboxed beforeFind hook that marks its refusal has that mark destroyed at the producer: metadataStoreUnavailableError builds a fresh Error keeping only code/status/cause, and declaredUserMessage reads only the top-level .userMessage, never cause. Per Prime Directive #12 the fix belongs at the producer — and it trades against #8136's deliberate non-quoting 503, so it needs a ruling, not a patch. Filed as such.

Finding 1 filed too: resolveExecCtx is private async behind .catch(() => undefined), so the resolveExecutionContext seam that #12405's suite drives as one of this door's four is test-only — no production throw of any kind leaves it. ⚠️ That narrows #12405's own seam census from four to three, which is worth having on the record.

Finding 2 is not filed as a card — it was the evidence for the fork, and the fork is now ruled; it lives in this comment.

记两处纪律

• No diff ⇒ no gate farm, declared with the reason (git rev-list --count 14b114553..HEAD = 0, so every check:* would be measuring origin/main). ⛔ Right call; running them would have produced a page of green that said nothing about anything.
• The throwaway probe carried its own instrument control: one throw declaring both channels, so the same call proves the observation channel reports a field that arrives and that the field under test is absent. ⭐ A liveness probe that can only report absence cannot distinguish "dead channel" from "broken probe".

⚠️ Operational: the empty probe branch cannot be deleted from this container either (same send-pack disconnect), so it is not a permissions issue on your seat. Moot now — the re-dispatch reuses that branch name.

---

Generated by Claude Code