A sandboxed hook body reaching through a caller-supplied readonly key aborts the whole write with a bare TypeError that names nothing actionable

[os-sam]

What an author sees

Since #16344 (PR #17195) a caller can no longer place a static readonly value on the hook's record. A sandboxed body that reaches through such a key — e.g. ctx.input.locked_meta.who = 'hook' where locked_meta is a caller-supplied readonly json key — now throws:

SandboxError: hook 'guard_task_body' threw: TypeError: cannot set property 'who' of undefined

A body's default onError is abort, so the caller's entire write is refused where it previously succeeded.

⚠️ The refusal itself is correct and is NOT what this card asks to change

What the refusal replaced is worse: the write succeeded and persisted a value derived from the caller's forged input. Trading a silent bad write for a loud refusal is the right direction, and #16344 exists precisely to close that laundering route.

⛔ Do not "fix" this by restoring the old behaviour. The defect here is the diagnostic, not the decision.

The defect

cannot set property 'who' of undefined names nothing an author can act on:

• it does not say which key was readonly;
• it does not say the value was withheld by the platform rather than absent by accident;
• it does not name the remedy;
• and it surfaces as a SandboxError wrapping a raw TypeError, which reads like a bug in the hook rather than a contract the platform is enforcing.

The remedy that exists is ctx.previous, and it is documented in PR #17195's changeset under Who is affected. An author hitting the raw TypeError has no path from the message to that remedy.

Why it was deliberately not fixed in PR #17195

Two reasons, both recorded there:

1. Scope. fix(objectql)!: beforeUpdate receives the persist image; the caller submission moves to ctx.submitted (#16344) #17195 already spans four packages under a maintainer-confirmed ruling (5582066157, confirmed 5582245356). Widening it again for a diagnostic would repeat, in the opposite direction, the fence error the seat made on that same card.
2. The obvious fix was measured and rejected on its merits. Marshalling ctx.submitted onto the sandbox face was considered and refused: that face is assembled key by key, and dispatch.scope is the standing precedent for that assembly discipline. ⛔ Whoever takes this card should not reach for that shape without re-arguing it against that precedent.

What a fix probably looks like

Not prescribed — the landing site is a measurement for whoever takes this. But the shape of a good answer is an error that names the key, says the platform withheld it because it is readonly, and points at ctx.previous. ⚠️ Re-derive the current behaviour on your own head before writing anything; ⛔ do not trust the message text quoted above to still be exact.

⚠️ One thing to check first

#17195 was still in contract review when this was filed. If that review changes the refusal semantics, this card's premise moves with it. ⛔ Read #17195's final verdict before starting.

Refs

#16344 / PR #17195 (the change that introduced it) · the seat ruling accepting the direction and deferring the diagnostic: PR #17195 comment 5606540131 · #14760 (the sandbox write-back provenance case whose test this surfaced through).

⛔ Unassigned and ungraded — domain:*, type and priority are triage's write.

_{Filed by the PM dispatch seat · domain:engine · session session_01XTBcV7zZHmokdyQgXjbyEU · R1}

[os-zhuang]

分诊

bug finding domain:engine priority:p3 pm:blocked · type Bug · 未指派

状态:pm:blocked,阻塞于 PR #17195

卡片自己的 ⚠️「#17195 was still in contract review when this was filed」我核了当前状态:PR #17195 仍是 open + draft,head 6375bc27,base c3756ff0,带 needs:contract-review,未合并;origin/main(0e45ee8c)上没有它的提交。

⇒ 本卡描述的行为在 main 上不存在。 这不是 pm:queue 能表达的状态 —— 队列里的卡应当可派发,而本卡的前提本身仍可能被契约评审改动。⇒ pm:blocked。

⛔ 派发席不要在 #17195 落地前派发本卡。⛔ 也不要把本卡当成 #17195 的评审意见塞回那条 PR —— 卡片已记录该 PR 刻意不修这一处,理由(范围;以及那个"显而易见的修法"已被实测否决)本席复核后同意。

⭐ 我为接手者找到的锚,以及它要求先做的一次测量

卡片引的报错串是 SandboxError: hook '...' threw: TypeError: ...。⚠️ 那是内部串,不必然是调用方收到的东西,而这件事有明确在案的裁定:

packages/rest/src/rest-hook-script-fault-envelope.test.ts:3-4 逐字(origin/main):

[#7543] A sandboxed hook body that CRASHES answers the sanitised server-fault envelope, not a 400 carrying its raw TypeError as the client-facing message.

该文件抬头还完整记录了链路:quickjs-runner.ts 把异常包成 SandboxError(内部串, userFacingMessage(...)),而 userFacingMessage 只剥掉开头的 Error: —— 也就是说 TypeError: … 曾经原样漏给调用方,#7543 正是为堵这个而立的。

⇒ 接手者的第一步不是写修复,是测量:#17195 落地后,一次「穿过被隐藏的 readonly 键」的写入,调用方在每道门(REST / 直调)上实际收到什么。 两种结局的修复落点不同:

• 若收到的是净化后的 server-fault 信封 —— 那比卡片假设的更糟:作者连 cannot set property 'who' of undefined 都看不到,只看到一个服务端故障,关于哪个键、为什么,一个字都没有。
• 若原样收到内部串 —— 那是卡片描述的情形,且与 A raw TypeError: not a function leaks in the 400 envelope for {"title": 12345} — no code, no fields[] #7543 的裁定不符,本身是第二个缺陷。

⛔ 不要沿用卡片引的那段串当作实测读数,卡片自己也警告过 ⚠️「do not trust the message text quoted above to still be exact」。

type Bug 的依据(⛔ 不是我最初想引的那条)

⚠️ 先记一条被我自己否掉的引证,免得下一个人重犯:我原打算引 AGENTS.md:920-926「an error owes ① the consequence ② the fix」。读回原处后不成立 —— 那条规则的射程是日志级 error 中的持久化/数据一致性降级,而 :930-932 明确写着「a failure handed to the CALLER is not a degradation at all」并给出第三条合法答案 errorFromThrown(e, 400)。⇒ 它不管调用方可见的报错质量,引它就是一次把受限子句读成通则。

成立的依据是分类:本仓有一套明确的「拒绝 vs 脚本故障」判别机制在跑 —— rest-hook-refusal-classification.test.ts、rest-hook-script-fault-envelope.test.ts、metadata-protocol/src/protocol.marked-refusal-classification.test.ts、runtime/src/domains/actions-fault-vs-rejection.test.ts。而在 #17195 之后:

平台刻意把那个键变成了 undefined,然后把由此产生的崩溃报告成了作者代码的故障。

机制上它确实是一次 crash,所以走 fault 通道并没有"走错管子";错的是因果归属 —— 一次平台自己的契约执行,在作者那里显示为他自己写错了。这就是卡片说的「reads like a bug in the hook rather than a contract the platform is enforcing」,而卡片没给出它在本仓的判别机制上有对应物。⇒ 违背已声明的判别契约 ⇒ Bug。

⇒ 也因此,好的修法方向是卡片说的那个:让"穿过被隐藏的键"这件事本身成为一次具名的拒绝,而不是任由它退化成一次匿名崩溃。⛔ 本席不指定落点。

车道 domain:engine,以及一条硬边界

「这个键是被平台按 readonly 扣下的」这条知识只存在于引擎(packages/objectql/src/engine.ts 的 hide pass,PR #17195 的 half 1)。沙箱只看得见一个 undefined,它没有能力说出"因为 readonly"。⇒ 能产出合格诊断的地方是引擎 ⇒ packages/objectql ⇒ domain:engine。这也与 #16344 / #17195 的既有席位一致。

⛔ 硬边界:packages/runtime/src/sandbox/** 属 domain:cli 行。若上面那次测量显示修复必须同时落在沙箱侧(例如信封分类要改),回来找分诊走跨域例外路径指定单一认领人并申报完整文件面,⛔ 不要自行跨包落地。

卡片两条 ⛔ 我复核后原样承接

1. ⛔ 不要用"恢复旧行为"来修这个。 拒绝的方向是对的,Update-side: a readonly field is stripped from persistence but still reaches beforeUpdate, so hook-derived columns persist values computed from data the row never contains #16344 正为堵那条洗白路径而存在 —— 卡片说得对,本卡只针对诊断。
2. ⛔ 不要伸手去把 ctx.submitted 铺到沙箱面上。 卡片记录该形状已被实测否决(那个面是逐键装配的,dispatch.scope 是该装配纪律的在案先例)。要用这个形状,先对着那条先例重新论证。

定级 priority:p3,并挂一条机械触发器

按"测量什么就定什么"的纪律:这个缺陷在 main 上此刻不存在,受影响的钩子数量也未测。⇒ p3。

⭐ 机械重新定级触发器(无需再判断):PR #17195 一旦合并,本卡立即升 priority:p2 并解除 pm:blocked 转 pm:queue。 届时它就是一次被拒的写入配一条不可行动的报错(body 的默认 onError 是 abort,调用方整笔写入被拒),那是生产面向调用方的行为,不再是一张假设卡。

反向触发器: 若契约评审推翻或实质改变 #17195 的拒绝语义,本卡前提随之移动 —— 届时重读卡片全文再定,⛔ 不要沿用本次定级;若拒绝语义被撤回,本卡直接关闭(承接者:无)。

---

Generated by Claude Code

[claude]

pm:blocked blocker discharged — PR #17195 merged. ⛔ No label changed; requesting a triage re-grade.

Triage set pm:blocked on 2026-09-09T18:52Z with: 「状态:pm:blocked,阻塞于 PR #17195 … PR #17195 仍是 open + draft … origin/main 上没有它的提交 ⇒ 本卡描述的行为在 main 上不存在」.

PR #17195 merged 06:09:26Z today — landing commit d2c1d19807, parent count 1 ⇒ squash. Re-measured on origin/main by symbol:

engine.ts  readonlyHiddenFromHooks ......... 5
packages/runtime/src/sandbox/hook-input-writeback-readonly-provenance.integration.test.ts ... PRESENT
control — a fabricated symbol ............... 0

⇒ The behaviour this card describes is now on main, and triage's stated reason for the hold — that it was not — is discharged.

⚠️ And the card's subject is named as a remainder in #17195's own delivery: a sandboxed body hook reaching through a hidden read-only key throws a raw TypeError, and body's default onError: abort rejects the caller's whole write. The direction was ruled correct; what this card asks for is the message, which names nothing actionable. ⛔ Deliberately not folded into #17195.

---

Generated by Claude Code

[claude]

Claim: PM loop round 2
Session: session_01XTBcV7zZHmokdyQgXjbyEU
Branch: claude/issue-17219-sandbox-readonly-diagnostic
Domain: domain:engine
Clause-②: no
Container & model: mode:subagent, model: opus

Dispatched by the domain:engine execution PM seat. The dev inherits this assignee and this claim and ⛔ posts no second one.

⭐ This card was pm:blocked until 06:3xZ today. Its hold was audited card-by-card and the blocker found discharged; the maintainer authorised the re-grade. The unblock evidence is the comment directly above this one.
File surface: the sandbox error path — packages/runtime/src/sandbox/** and whatever composes the SandboxError wrapper. ⚠️ Region-level: the landing site is a measurement this round takes. Report it before widening.

⚠️⚠️ SHARED FILE, DISJOINT REGION — and this one is measured, not assumed. #15719 is claimed in the same round and its sites are packages/objectql/src/engine.ts:10259 (the CREATE path, staticReadonlyInsertSubject) and packages/objectql/src/validation/rule-validator.ts:1515-1522. If your landing site turns out to be inside the create-path strip region, ⛔ stop and report — that is a serial conflict, ⛔ not something to edit around. ⛔ Re-derive every region by SYMBOL on your own head; the line numbers above are #15719's card's, taken at 66c580b0c, and origin/main has moved a great deal since.

Seat rulings, decided before dispatch

1. ⛔ The refusal is CORRECT and is not yours to change. The card says so and the seat confirms it: what the refusal replaced is a write that succeeded while persisting a value derived from the caller's forgery. ⛔ Do not restore the old behaviour. The defect is the DIAGNOSTIC.

2. ⛔ Do NOT marshal ctx.submitted onto the sandbox face. That face is assembled key by key and dispatch.scope is the standing precedent; a key added there is a second published contract with its own compatibility story. This was measured and refused on its merits in PR #17195 — ⛔ do not re-open it by implementing it.

3. Clause-②: no, with a HARD STOP. A better message on an EXISTING refusal is an envelope on a refusal, ⛔ not a widening. ⚠️ BUT — if your route registers a new error code in packages/spec's error-code-ledger.zod.ts, or adds any key to a published payload, that is a new published member and the declaration flips to yes: ⛔ stop and report before writing it, do not re-declare it yourself.

4. The remedy has to be reachable from the message. ctx.previous is the documented answer (PR #17195's changeset, Who is affected). An author who hits the raw TypeError today has no path from the message to it. Name the withheld key, say the platform withheld it, and name ctx.previous.

5. This card's premise landed 06:09:26Z today — PR #17195, commit d2c1d19807. ⛔ Do not measure against a main older than that; re-fetch first.

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 17219,
  "status": "done",
  "branch": "claude/issue-17219-sandbox-readonly-diagnostic",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/17327",
  "premise_still_valid": true,
  "summary": "Re-fetched origin/main first (ruling 5); premise commit d2c1d19807 is present, measured at 501959b72a. The card's quoted message is still exact at the direct door, but the REST door is the WORSE of the two outcomes triage allowed for: mapDataError classifies the leading 'TypeError:' as a script fault (#7543) and answers 500 {\"error\":\"Internal server error\",\"code\":\"INTERNAL_ERROR\"} -- the author is told nothing at all. A control fired in the same measurement (an authored throw still answers 400 with its own words), so the blank envelope is a real reading. LANDING SITE, reported as ordered: NOT the sandbox. The sandbox face is a plain JSON snapshot (unwrapProxyToPlain then a JSON marshal), so a withheld key is simply absent there and 'the platform took it away' is indistinguishable downstream from 'nobody sent it' -- which is exactly what ruling 4 requires the message to state. So the explanation is composed at the hide pass in packages/objectql: a new module plus three one-line wraps at the beforeUpdate dispatch sites inside the hide window. packages/runtime/src/sandbox/** gains NO production code; one test file there is tightened. The composed error names the withheld key, says the platform withheld it because the field is readonly:true, points at ctx.previous, carries the original fault text, and declares HTTP 400 -- measured to be the only thing that carries the message past the sanitiser (a ledgered code alone still answers 500). Rulings 1 and 2 held: the refusal is untouched and re-pinned in every case, and nothing was marshalled onto the sandbox face. LANE CONFLICT, flagged rather than silently chosen: triage called packages/runtime/src/sandbox/** the domain:cli lane needing a cross-domain exception, while the dispatch named it my expected surface. Resolved conservatively -- all production code landed in triage's lane (packages/objectql, domain:engine) and the runtime touch is a single test. PROCESS FAILURE, stated plainly: the first push (e94f8ae054) was red -- I opened the PR before running the package typecheck, and objectql#typecheck exited 2 on ErrorOptions / a two-argument super() under lib:ES2020. Fixed in 94193545fd by following the precedent already written in the same package (duplicate-record-error.ts declares readonly cause: unknown for exactly this reason), never a cast or a suppression. Head is now green: 35 success / 7 skipped / 3 in_progress / 0 red, with 'Type Check . workspace' success. Assignee was already set by the dispatch and I never wrote it; the newest Claim names my branch and I posted no second claim.",
  "tests": "ALL exit codes captured by redirect-then-$?, never across a pipe. TYPECHECK: pnpm --filter @objectstack/objectql typecheck exit 0 (tsc + tsconfig.scripts.json + check:test-typecheck); pnpm --filter @objectstack/runtime typecheck exit 0. SUITES (after a forced rebuild): objectql src/hook-withheld-readonly-fault.test.ts + src/engine-readonly-hook-input.test.ts exit 0, 28 passed; runtime src/sandbox/hook-input-writeback-readonly-provenance.integration.test.ts exit 0, 9 passed. ABLATION (reverse verification, from the COMMITTED state, real direction): mutate = git restore --source=BASE of packages/objectql/src/engine.ts (tree only, never the index), trap-restored, absolute paths. ON-DISK PROOF: marker occurrences 4 -> 0, blob efa1a3ba88 -> e54df038b6 (a non-empty HEAD blob hash compared, not an exit code). DIST PROOF (the runtime suite resolves @objectstack/objectql through exports to dist/, not src/): build --force exit 0, then ablation-dist-preflight --absent = 'absent from all 14 built files'. RED: objectql exit 1 -> 3 failed | 25 passed (28); runtime exit 1 -> 1 failed | 8 passed (9). Direction was predicted before running and held -- the 3 failures are exactly the 3 dispatch-site cases; the 3 CONTROL cases stayed GREEN (they assert pass-through, i.e. pre-fix behaviour) and so did the composer's unit suite (module in isolation, not its wiring). RESTORE leg: git checkout HEAD -- PATH; whole-tree git status --porcelain EMPTY; disk blob == HEAD blob; marker back to 4; build --force exit 0; preflight 'present in 4 built files' and 'tree clean'; objectql exit 0 28/28, runtime exit 0 9/9. GATES: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 64 families from the real change set; reconciled via --ran with every exit code recorded, so NOT-MEASURED is DERIVED not claimed: 64 derived, 62 run green, 2 NOT-MEASURED, 0 UNRUN. NOT MEASURED (exit 3 = PREREQUISITE NOT MET, NOT a pass and NOT a finding; neither names a file in this diff): check:dual-build-cjs-loads ('reads built output, and some package has no dist/', 38 packages unbuilt) and check:type-check-debt ('--re-measure cannot run: 2 workspace dependencies have no built type entry point on disk'). Both need a full workspace build, which is the repo-wide sweep the required 'Lint & Repo Gates' context performs after its own build step -- declared to CI, not skipped. LINT: the FULL population ran inside the foreground budget, so no narrowing needed justifying -- pnpm lint (eslint . --no-inline-config) exit 0 at 94193545fd, 6483 files (count read from --format json output length, i.e. from eslint's own config, not a guess), 0 errors / 0 warnings; .cache/ absent from this worktree so the objectui false positives cannot be in that count. CI on head 94193545fd: 35 success, 7 skipped, 3 in_progress, 0 red; 'Type Check . workspace' (the check that was red on the previous head) is success.",
  "mcp_calls": "0 - every GitHub read and write went through repo-scoped REST after a probe returned 200; no MCP GitHub call was made",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: a dedicated ERROR_CODE_LEDGER entry would let clients branch on this refusal by code instead of by status alone. Deliberately NOT written - ruling 3 declares a new ledger code a new published member that flips Clause-2 to yes, and re-declaring it is not mine. Carrier: whoever re-declares Clause-2 for this card.",
    "noted, not filed: ERR_READONLY_FIELD_REJECTED was considered for reuse and refused on its merits - that code names the strictReadonlyWrites refusal and carries `drops` as part of its contract, so borrowing it would make the error lie about which refusal happened. Recorded so the next author does not re-derive it. Carrier: none.",
    "noted, not filed: the hook-authoring docs describe the #16344 hide but do not describe what an author sees when a body reaches THROUGH the withheld key. No page states anything false - this is an addition, not a correction - so it is not a filing class (a), (b) or (c). Carrier: none; no queued PR or person touches content/docs/automation/hook-bodies.mdx.",
    "noted, not filed: the pre-existing assertion at the real sandbox door was rejects.toThrow(/locked_meta|cannot set property 'who' of undefined/), which stayed green through the entire defect because the raw TypeError matches the second arm. Tightened to an envelope assertion in this PR rather than carded, since it is the same card's subject.",
    "docs-drift advisory: 22 pages named. 3 are release-owned (content/docs/releases/v17/17-0, 17-1, 17-3) and were NOT touched - read-only by directive. The 19 hand-written pages were READ AND ARE UNAFFECTED: this change alters no behaviour any of them documents (the #16344 hide, the five strip rules, ctx.submitted, ctx.previous, onError: abort are all exactly as written). Two were checked closely as the only plausible staleness: api/error-catalog.mdx already carries the governing clause verbatim ('An error carrying its own `status` is served with it'), which is precisely the channel this fix uses, so it is correct as written rather than merely unmentioned; kernel/contracts/data-engine.mdx documents ERR_READONLY_FIELD_REJECTED, which was deliberately not reused, so its description stays true."
  ]
}

---

Generated by Claude Code

[claude]

Landed — PR #17327 MERGED. A hook that faults reaching THROUGH a withheld read-only key now names the key.

Confirmed with two readings, never one:

1. Queue membership — added_to_merge_queue 07:47:06Z, merged.

2. origin/main BY CONTENT, by SYMBOL — ⛔ not head-sha ancestry, ⛔ not the merged boolean:

   engine.ts:221     import { dispatchHooksExplainingWithheldReadonly } from './hook-withheld-readonly-fault.js';
   engine.ts:11714 / :11786 / :11819   all THREE dispatch sites wrapped
   hook-withheld-readonly-fault.ts:134  export class HookWithheldReadonlyFaultError
                                 :136   readonly status = 400
                                 :149   readonly cause: unknown
   

   ⭐ And the reading that shows the OLD shape is gone: the bare await this.triggerHooks('beforeUpdate', hookContext); now reads 0 — every site is wrapped, ⛔ not just the one the card quoted. Controls: a fabricated symbol 0, triggerHooks 24.

Landing commit 706ad0fcc4, parent count 1 ⇒ squash.

What landed

The refusal is unchanged — ⛔ that was never the defect. The message is: it names the withheld key, says the platform withheld it because the field is readonly: true, points at ctx.previous, carries the original fault text, and declares HTTP 400.

⚠️ The card understated the defect. At the direct door it was the raw TypeError; at the REST door it was 500 {"error":"Internal server error","code":"INTERNAL_ERROR"} — the author was told nothing at all, because mapDataError classifies a leading TypeError: as a script fault. The round measured that with a control that fired (an authored throw still answers 400 with its own words).

Where it landed, and why not where the dispatch said

⛔ Not the sandbox. That face is a plain JSON snapshot, so a withheld key is simply absent there and is indistinguishable from "nobody sent it" — which is precisely what the message has to state. ⇒ The explanation can only be composed at the hide pass, where the withheld set still exists.

⭐ And triage had already called packages/runtime/src/sandbox/** the domain:cli lane — my dispatch order named it as this lane's expected surface, which was wrong. The round flagged the conflict rather than silently picking, and resolved it conservatively: all production code in packages/objectql, one test file in packages/runtime. A dispatch order is not a licence to cross a lane boundary triage already drew.

Deliberately NOT done

⛔ No error code registered. The module's own header says why: a ERROR_CODE_LEDGER entry is a published member that flips clause ② to yes, and re-declaring that is not the implementer's. ⛔ And ERR_READONLY_FIELD_REJECTED was refused for reuse — it names the strictReadonlyWrites refusal and carries drops in its contract, so borrowing it would make the error lie about which refusal happened.

⛔ ctx.submitted was not marshalled onto the sandbox face — that face is assembled key by key and a key added there is a second published contract.

Graded patch

An envelope on an existing refusal. No published export moves (the three new exports are package-private — src/index.ts does not re-export the module, control: 38 re-export lines and no export * barrels), no ledger member, packages/spec untouched.

Worth keeping from the round

⭐ The ablation reached the built artefact: the runtime suite resolves @objectstack/objectql through exports to dist/, so a source-only ablation would have proved nothing about it — the round rebuilt and confirmed absence from all 14 built files. An ablation that does not reach the artefact under test is a no-op wearing an ablation's clothes.

⭐ It also declared its own process failure: it opened the PR before running the package typecheck and pushed red once. The fix followed a precedent already in the same package (duplicate-record-error.ts declares readonly cause: unknown for exactly this reason) — ⛔ not a cast, ⛔ not a suppression.

⭐ 19 hand-written docs read and found unaffected, with the two plausible candidates checked closely; ⛔ the 3 release-owned pages untouched.

---

Generated by Claude Code