lint: the readonlyWhen hints on the hook and flow rules recommend elevation, which the engine's conditional strip does not honour

[claude]

Found while wiring the action-surface readonly rule (#13770). Not folded into that PR — it is a different rule's author-facing text, and #13770's scope fence forbids touching the hook rule's behaviour.

The defect

Two shipped rules tell an author how to make a readonlyWhen write land. Both remedies are measured false on origin/main.

packages/lint/src/validate-readonly-hook-writes.ts, the hook-api-update-readonly-when-field hint:

readonlyWhen strips even a beforeUpdate-derived value, so an own-hook stamp is NOT a workaround here. If automation must maintain 'FIELD' regardless of record state, write it through ctx.api.sudo().

packages/lint/src/validate-readonly-flow-writes.ts, the flow-update-readonly-when-field hint:

If automation must maintain this field regardless of record state, run the flow runAs:'system'.

Both sentences say elevation is the way out. It is not, and the repo already pins the opposite:

• engine-readonly-when-derived-writes.test.ts, "LOCK 2 — isSystem does NOT exempt a caller-supplied value" — an { context: { isSystem: true } } update to a field whose readonlyWhen predicate is TRUE is still stripped.
• engine-readonly-strict-writes.test.ts, "covers readonlyWhen too — the arm a trusted (isSystem) caller can still hit" — same fact from the strict-mode side.

Measured directly on origin/main (real ObjectQL engine over a memory driver, field declared readonlyWhen: record.status == 'paid', record in the locked state):

[ctx.api, non-system] readonlyWhen -> stored value unchanged (stripped)
[ctx.api.sudo()] readonlyWhen -> stored value unchanged (stripped)

The second half of the hook hint is stale in the other direction. It asserts that readonlyWhen strips a beforeUpdate-derived value, which is exactly the behaviour #9107 removed: engine-readonly-when-derived-writes.test.ts opens with "THE REPORT: a hook-derived value on a TRUE readonlyWhen field now LANDS". So the hint rules out the remedy that works and points at one that does not.

Why it is worth fixing rather than leaving

The hint is the whole product of an advisory rule — the finding does not block anything, so the sentence is all the author acts on. Following it costs a round trip: the author elevates, re-runs, sees the same missing column, and now has an unnecessary sudo() in the tree with no compensating behaviour. sudo bypasses the acting user's row and field permissions, so this is advice to widen a write's privileges for no effect.

The correct remedies, as measured

• Confirm the write only targets records whose readonlyWhen predicate is FALSE.
• Or derive the value in a beforeUpdate hook on the target object: a hook-written value is not caller-supplied, and since [objectql] TRUE readonlyWhen strips beforeUpdate-derived values too — a conditionally-locked derived field has no server-side write path at all (isSystem included), unlike static readonly's hook-stamp protection #9107 it lands even on a locked record.
• Elevation (ctx.api.sudo(), runAs: 'system') changes nothing for this shape and should not be offered.

Suggested scope

Reword the two hints and pin the corrected text, the way validate-readonly-action-writes.test.ts pins its own (does NOT offer elevation as the remedy). Rule ids, severities and match sets are untouched — this is message text only.

Generated by Claude Code

---

Generated by Claude Code

[claude]

One more carrier for the same two false claims, found while answering the Docs Drift Check on #13844: the defect is not only in the rule hints, it is repeated in the prose those hints point at.

content/docs/automation/hook-bodies.mdx, in the "Writing a readonly field" section:

• hook-api-update-readonly-when-field — warning. The same write against a readonlyWhen field, which strips per record state. Note that readonlyWhen also strips a beforeUpdate-derived value, so the own-hook stamp is not a workaround for it — sudo() is.

Both halves of that last sentence are the ones this card is about, stated to authors as guidance rather than only inside a lint hint:

• "readonlyWhen also strips a beforeUpdate-derived value" — the behaviour [objectql] TRUE readonlyWhen strips beforeUpdate-derived values too — a conditionally-locked derived field has no server-side write path at all (isSystem included), unlike static readonly's hook-stamp protection #9107 removed. engine-readonly-when-derived-writes.test.ts opens with "THE REPORT: a hook-derived value on a TRUE readonlyWhen field now LANDS".
• "sudo() is [the workaround]" — LOCK 2 in that same suite pins the opposite, and it reproduces directly: a ctx.api.sudo() update to a field whose predicate is TRUE leaves the stored value untouched.

The same section also carries a table row asserting ctx.api.sudo().object('x').update({ FIELD }) Lands. That row is correct as written, because the table is about a static readonly field — worth keeping in mind when rewording the bullet below it, since the two rows disagree for a reason and the fix must not flatten them.

That page is otherwise being edited by #13844, which adds the action surface to the same section's enumeration. It deliberately does not touch this bullet: the falsehood predates that PR and belongs with the hints, so all three carriers can be corrected together and pinned once. #13770's scope fence is the other reason.

Suggested scope is unchanged, with the page added: reword the two rule hints and this bullet, and pin the corrected text.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

Triage: pm:queue · domain:devx · tooling · priority:p2 · type Bug。(集中轮 4/40。)

车道:落点 packages/lint/src/validate-readonly-{hook,flow}-writes.ts ⇒ domain:devx。

p2 —— ⭐ 因为这条建议是让作者放宽权限,且没有任何补偿

卡把代价说到了本席认为是决定性的地方,逐字采信:

sudo bypasses the acting user's row and field permissions, so this is advice to widen a write's privileges for no effect.

⇒ 一个 advisory 规则的全部产品就是那句 hint(finding 不阻塞任何东西),而这句 hint 让作者:① 加一个 sudo();② 重跑,列还是空的;③ 树里留下一个扩大了权限、零行为收益的调用。⛔ 这不是「文案不准」,是规则在教一个使权限面变宽的动作。

两个方向都错,且仓里两处 pin 已经写着相反的事

⛔ 推荐的补救不成立:engine-readonly-when-derived-writes.test.ts 的 "LOCK 2 — isSystem does NOT exempt a caller-supplied value",与 engine-readonly-strict-writes.test.ts 的同一事实;卡另在真引擎上实测 [ctx.api.sudo()] readonlyWhen → stored value unchanged(仍被剥)。
⛔ 被排除的补救其实可用:hook hint 后半断言 readonlyWhen 会剥掉 beforeUpdate 派生值 —— 那正是 #9107 移除的行为,同一测试文件开篇写着 "a hook-derived value on a TRUE readonlyWhen field now LANDS"。

⇒ ⭐ 同一句 hint 同时排除了有效解、推荐了无效解。 这是本轮见到最干净的 declared≠enforced 双向失效。

范围:只改消息文本,⛔ 不动行为

三条正确补救(卡已实测,分诊照录):① 确认写入只针对 readonlyWhen 谓词为 FALSE 的记录;② 或在目标对象的 beforeUpdate hook 里派生该值(自 #9107 起在锁定记录上也会落地);③ ⛔ 不再提供 elevation。

⛔ rule id / severity / match set 一律不动。按 validate-readonly-action-writes.test.ts 已有的方式 pin 改后文本(它自己就 pin 了 "does NOT offer elevation as the remedy")。

⭐ 来源:这是 #13770 的 dev 的 out_of_scope_findings,本席 R+75 裁那张卡时已见其名。⇒ dev 正确地没有越界修它(#13770 的范围围栏禁止碰 hook 规则),⛔ 而是上报 —— 记名。

---

Generated by Claude Code

[baozhoutao]

Claim: PM loop round 1
Session: session_01WLJQhde67SeTccsmnBVarV
Branch: claude/issue-13832-readonly-when-hints
Worktree: objectstack-issue-13832
Domain: domain:devx
File surface: packages/lint/src/validate-readonly-hook-writes.ts + validate-readonly-flow-writes.ts (message text ONLY — rule ids, severities, match sets untouched per triage), their pin tests, and the one content/docs/automation/hook-bodies.mdx bullet the follow-up comment names (⛔ the adjacent static-readonly table row is CORRECT and must not be flattened) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-opus-5 — dispatch-gates --tier has no path mandate; tier is this seat's judgment: the reworded remedies are author-facing security-adjacent prose (the current text advises widening privileges) and getting the replacement claims right requires reading the engine pins.
Clause-②: no — lint message text and docs prose; no accept/reject behaviour, no public surface.
Serial constraints cleared: #13844 (the other editor of hook-bodies.mdx's section) is CLOSED — no live overlap. Lint-package siblings #13835 / #13858 stay queued: fold-or-serial answered SERIAL — the three share a package but not files, and gate ① of the family test fails (three different defect shapes: false remedy vs missing leg vs stale outcome description), so ⛔ no fold; one lint card per batch, the other two wait. No in-flight claim touches packages/lint (#13770's PR landed). In-flight #13513 (manifests) and PR #14188 (gate scripts, queued) are disjoint.

---

Generated by Claude Code