docs(objectql): carry the whitelist+readonly boundary and the persist-image rule where authors read them (#16344)

Contract-review findings F2, F3, and F4/F5 riding along.

F2 — the changeset now carries the ADR-0092 boundary the round report claimed
was already in it. An UPDATE-whitelisted field that is ALSO declared `readonly`
now answers 403 where it answered 200-having-written-nothing, and the refusal
reads `(—)` because a whitelisted key is excluded from the guard's refused list
by design. No in-repo object is on that boundary; `patch` for plugin-auth
stands. The self-assignment row is also corrected to the verdict that now
holds: a no-op, stored value standing, not a persisted `undefined`.

F3 — `content/docs/protocol/objectql/security.mdx` is the hand-authored
authority for the update-side strip and said nothing about this card. It gains
a fifth rule ("hooks are shown the persist image, not the submission") and a
migration callout naming `ctx.submitted`, `ctx.previous`, the self-assignment
no-op and the sandbox `body` exclusion. Rule 2's trailing paragraph is
corrected while there: "cannot rescue one the caller supplied" has been false
since #5591/#14088 — a hook that ASSIGNS a caller-sent key owns the value and
the strip keeps that write. `content/docs/automation/hooks.mdx` takes the
one-line cross-reference from "Mutate the incoming record".

F4 — the `submitted` TSDoc said "FROZEN by the producer" without qualifying
depth. It is a shallow spread shallow-frozen, so a nested object reached
through a key here is the caller's own mutable reference. Not a laundering
route, but not a deep guarantee either, and now it says so.

F5 — the hidden set is the update strip's own subject set: author-declared
`readonly: true` AND runtime-owned types (`autonumber`, #5503), not "statically
readonly" alone. Stated in the changeset and in the `input` contract note.

No generated artifact moves: the edited prose is TSDoc, and only the
`.describe()` string reaches `authorable-surface/data.json` and
`references/data/hook.mdx`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU

Author: claude

.changeset/hook-input-is-the-persist-image.md

@@ -8,7 +8,7 @@ fix(objectql)!: `beforeUpdate` receives the record the engine intends to persist
 
 <!-- adr-0087: not-required (no-migration-prescription) an enforcement-ORDER change plus one ADDITIVE optional key on a runtime context schema. No authorable key, spelling or stored shape moves, so a stored `sys_metadata` row needs no conversion and an upgrader has nothing to hand-edit. What changes is which image a `beforeUpdate` handler is shown; the remedy for a handler that depended on seeing a refused value is to read `ctx.submitted`, which is a code edit in the handler, not a metadata migration. Nothing is retired: `HookContext.submitted` is new and optional. -->
 
-**BREAKING** — what a `beforeUpdate` handler reads on `ctx.input.data` changes. A statically `readonly` field the caller supplied a value for is no longer there.
+**BREAKING** — what a `beforeUpdate` handler reads on `ctx.input.data` changes. A `readonly` field the caller supplied a value for is no longer there. The hidden set is the update strip's own subject set: author-declared `readonly: true` **and** the types whose value the runtime owns end to end (`autonumber`, implicitly read-only since #5503). `readonlyWhen` locks are deliberately not hidden.
 
 ## The defect
 
@@ -25,7 +25,7 @@ The row's own audit trail cites values the row does not hold. No error, no warni
 
 ## What changed
 
-**`ctx.input.data` on `beforeUpdate` is now the record the engine intends to persist.** Caller-supplied values for statically `readonly` fields are taken out of the hooks' view before the before phase is dispatched, and handed back at the engine's post-hook confluence — so the payload every engine-owned consumer below reads is byte-for-byte what it read before. `onFieldsDropped` reports the same fields with the same `readonly` reason, the read-only WARN says the same sentence, and `strictReadonlyWrites` refuses exactly the same writes.
+**`ctx.input.data` on `beforeUpdate` is now the record the engine intends to persist.** Caller-supplied values for `readonly` fields are taken out of the hooks' view before the before phase is dispatched, and handed back at the engine's post-hook confluence — so the payload every engine-owned consumer below reads is byte-for-byte what it read before. `onFieldsDropped` reports the same fields with the same `readonly` reason, the read-only WARN says the same sentence, and `strictReadonlyWrites` refuses exactly the same writes.
 
 **The caller's submission travels on a new `HookContext` member, `ctx.submitted`** (`@objectstack/spec`, `HookContextSchema`) — the payload as sent, snapshotted at engine entry before any middleware or hook stamp, frozen, and documented as *diagnostics only, never the persist image*. It is bound on the update verb, both phases, and every per-row dispatch of one caller write.
 
@@ -40,14 +40,16 @@ Ruled 2026-09-08 (maintainer, verbatim 「批 #87 同意」, director seat, deci
 
 ## Who is affected
 
-A `beforeUpdate` handler that **reads a statically `readonly` field out of `ctx.input.data`**, on a non-`isSystem` write. Three shapes, and the fix is one line each:
+A `beforeUpdate` handler that **reads a `readonly` field (declared, or runtime-owned) out of `ctx.input.data`**, on a non-`isSystem` write. Three shapes, and the fix is one line each:
 
 - **deriving a value from it** — this is the defect; the handler now derives from `ctx.previous`, or from `ctx.input.data` with the payload's absence meaning "unchanged", which is what it always meant for a field the caller never sent.
 - **reporting on what the caller sent** (a guard naming the offending key) — read `ctx.submitted`.
-- **a self-assignment** (`data.x = data.x`) on such a field — this used to promote the caller's forged value to hook-owned and commit it; it now writes `undefined`, because the key the hook reads is gone. That laundering route closing is intended, and it is re-pinned rather than removed.
+- **a self-assignment** (`data.x = data.x`) on such a field — this used to promote the caller's forged value to hook-owned and commit it. It is now a **no-op**: the key the hook reads is gone, so the line re-creates it holding `undefined`, and the engine treats set-to-undefined of a hidden read-only key as the no-op it is — deleting the key, dropping it from the hook-write record, and letting the ordinary hand-back put the caller's value back for the strip to judge. **The stored value stands**, and the write reports exactly as it would with no hook at all (stripped, `onFieldsDropped`, the WARN, `strictReadonlyWrites` refusing). Persisting the `undefined` instead would erase the stored value on the memory driver and hand knex an undefined binding on a SQL one — neither is the record the engine intends to persist. That laundering route closing is intended, and it is re-pinned in both directions rather than removed.
 
 ⚠️ **The sharpest edge is a sandboxed `body` hook, and it is a refusal rather than a quiet change.** A body that reaches *through* such a key — `ctx.input.locked_meta.who = 'hook'` — now dereferences `undefined` and throws, and a `body`'s default `onError` is `abort`, so the caller's **whole write is rejected** where it used to succeed. What that body used to do was persist a value derived from the caller's forgery, so refusing is the correct direction; but the message the author sees is a raw `TypeError` from their own dereference and names nothing actionable. Measured end to end through a real QuickJS sandbox and pinned in `packages/runtime/src/sandbox/hook-input-writeback-readonly-provenance.integration.test.ts`.
 
 A body hook cannot read `ctx.submitted`: it is deliberately not marshalled onto the sandbox face, for the reason `dispatch.scope` is not — that face is assembled key by key, and a key added there is a second published contract with its own compatibility story. A body deriving a column from a read-only field reads **`ctx.previous`**, the stored row, which is the correct source either way.
 
+⚠️ **One ADR-0092 boundary changes a status code, and no in-repo object hits it today.** On an object whose UPDATE whitelist admits a field that is ALSO declared `readonly`, a whitelist-only payload now answers **403** where it used to answer **200 having written nothing**. The identity write guard composes its refused list from what the engine left it, and a whitelisted key is excluded from that list by design, so the refusal reads `None of the submitted fields (—) are editable` — naming nothing. The write was already being dropped by the read-only strip before this change; what moves is that the caller is now told, and told imprecisely. `sys_user`'s three writable fields are not read-only, so nothing in this repository is on that boundary; an application that puts a `readonly` field in an UPDATE whitelist should take it out, which is what the whitelist meant either way.
+
 An `isSystem` caller sees no change at all: the strip has never applied to one, and neither does the hide.

content/docs/automation/hooks.mdx

@@ -181,6 +181,12 @@ record's fields **directly on `ctx.input`** (a flat view over the internal
 `{ data, options }` wrapper — reads and writes of record fields route through
 `ctx.input.data`):
 
+On **update**, "the incoming record" means *the record the engine intends to
+persist* — a caller-supplied value for a `readonly` field is not on it, and the
+caller's submission is on `ctx.submitted` instead (diagnostics only). See
+[Static `readonly` fields on the write path](/docs/protocol/objectql/security#static-readonly-fields-on-the-write-path)
+for the five rules and the migration.
+
 <Callout type="warn" title="`id` / `options` / `ast` / `data` are RESERVED on the flat `ctx.input` face">
 These four names always resolve to the envelope, never to a record field —
 even if your object declares a field with one of those names. A field named

content/docs/protocol/objectql/security.mdx

@@ -259,18 +259,45 @@ rejecting — the offending key is removed from the payload and the rest of the
 committed. The write therefore **succeeds** (REST answers `200`), and the read-only column
 simply keeps its stored value.
 
-Four rules decide whether a given value survives:
+Five rules decide whether a given value survives:
 
 | # | Rule | Effect |
 |:--|:---|:---|
 | 1 | **Trusted context is exempt** | A write carrying `context.isSystem === true` skips the strip entirely and may set read-only columns. |
 | 2 | **Only *caller-supplied* keys are candidates** | The engine snapshots the payload's keys at entry (`suppliedKeys`), *before* middleware and `beforeUpdate` hooks run. Only keys in that snapshot can be stripped. |
 | 3 | **Hook / middleware backfill survives** | A key a `beforeUpdate` hook *adds* to `data` is absent from the entry snapshot, so it is not a candidate — this is why the built-in `updated_by` / `updated_at` stamps land even though those columns are `readonly`. |
 | 4 | **`context.preserveAudit` admits a whitelist — on UPDATE only** | An opt-in historical import reinstates the audit/timestamp family and author-declared business `readonly` fields; platform-managed `system` columns (tenancy, generated) stay stripped. This exemption exists on the **UPDATE** path and nowhere else — see below. |
-
-Rule 2 is scoped to keys, not values: a key the caller sent stays a strip candidate even if
-a hook later overwrites its value. So a `beforeUpdate` hook can *backfill* a read-only
-field, but cannot *rescue* one the caller supplied.
+| 5 | **Hooks are shown the persist image, not the submission** (#16344) | On UPDATE, a caller-supplied value for a `readonly` field is hidden from `ctx.input.data` *before* `beforeUpdate` is dispatched, so a hook cannot derive a persisted column from a value the row will never hold. What the caller actually sent is on **`ctx.submitted`** — diagnostics only, never the persist image. |
+
+Rule 2 selects the *candidates*; rules 3 and 5 decide what a hook can do about one. A key
+the caller never sent is not a candidate at all, which is why the built-in `updated_by` /
+`updated_at` stamps land. A key the caller **did** send stays a candidate — but a hook that
+**assigns** it owns the value standing on it and the strip keeps that write (#5591 /
+#14088: authorship is *recorded* while the hook writes happen, not inferred from value
+equality afterwards). So a `beforeUpdate` hook can both *backfill* a read-only field and
+*overwrite* one the caller supplied; what it can no longer do is *rescue the caller's own
+value*, because since #16344 that value is not on `ctx.input.data` for it to echo back.
+
+<Callout type="warn" title="`beforeUpdate` no longer sees the caller's read-only values (#16344)">
+This is a **breaking** change to what a hook reads, not to what is stored: the accept /
+refuse set is unchanged, `onFieldsDropped` reports the same fields under the same
+`readonly` reason, the WARN says the same sentence, and `strictReadonlyWrites` refuses the
+same writes. What moved is the hook's view.
+
+- A handler **deriving** a column from a read-only field reads the stored row on
+  `ctx.previous`, or treats the key's absence as "unchanged" — which is what absence
+  always meant for a field the caller never sent.
+- A handler **reporting on what the caller sent** (a guard naming an offending key) reads
+  `ctx.submitted`.
+- A self-assignment (`data.x = data.x`) on such a field is now a **no-op** — the stored
+  value stands, and the write is stripped and reported exactly as an un-hooked one is.
+- `ctx.submitted` is **not** marshalled onto the sandboxed `body` face. A `body` deriving
+  from a read-only column reads `ctx.previous`, the stored row, which is the correct
+  source either way.
+
+`beforeInsert` is untouched (#14147), and `readonlyWhen` locks are deliberately still
+hook-writable (#9107).
+</Callout>
 
 <Callout type="warn">
 **`preserveAudit` is an UPDATE-path exemption. It does not apply on INSERT (#6640).**

packages/spec/src/data/hook.zod.ts

@@ -455,12 +455,24 @@ export const HookContextSchema = lazySchema(() => z.object({
    * decision batch #87, 2026-09-08)
    *
    * On the UPDATE verb `input.data` is **the record the engine intends to
-   * persist**, not the caller's submission. A statically `readonly` field the
-   * caller supplied a value for is stripped from it BEFORE the before phase is
+   * persist**, not the caller's submission. A `readonly` field the caller
+   * supplied a value for is stripped from it BEFORE the before phase is
    * dispatched, so no hook can derive a persisted column from a value the row
    * will never contain. What a hook that needs the caller's own words reads is
    * {@link HookContext.submitted} — the same payload as sent, diagnostics only.
    *
+   * WHICH fields, exactly: the subject set is the update strip's own
+   * (`stripReadonlyFields`), which is author-declared `readonly: true` AND the
+   * types whose value the runtime owns end to end — `autonumber` today
+   * (#5503), implicitly read-only whether or not the author wrote the flag.
+   * Deliberately the same set rather than a second opinion: a pass that hid a
+   * different set from the one enforced below would put the two out of step,
+   * which is the whole failure this ordering exists to remove.
+   *
+   * ⛔ NOT `readonlyWhen`. A conditional lock is judged against the prior
+   * record, per row on the predicate path, and #9107 leaves it hook-writable
+   * on purpose.
+   *
    * Two things this deliberately does NOT change: a hook's OWN write to a
    * read-only column still lands (#5591 / #14088 — the enforcement pass stays
    * after the hooks, where provenance is knowable), and `beforeInsert` is
@@ -659,11 +671,21 @@ export const HookContextSchema = lazySchema(() => z.object({
    *
    * Assigning to this record, or to a key on it, changes NOTHING about the
    * write — the engine reads `input.data` and nothing else on the way to the
-   * driver. The object is FROZEN by the producer, so an assignment throws in
-   * strict mode rather than silently editing a record of what a caller sent. A
-   * handler that wants to change what is written writes `input.data`; a
-   * handler that wants to REFUSE a write throws; a handler that wants to know
-   * what the caller asked for reads this.
+   * driver. The object is SHALLOW-frozen by the producer, so an assignment to
+   * one of ITS OWN keys throws in strict mode rather than silently editing a
+   * record of what a caller sent. A handler that wants to change what is
+   * written writes `input.data`; a handler that wants to REFUSE a write
+   * throws; a handler that wants to know what the caller asked for reads this.
+   *
+   * ⚠️ SHALLOW is the honest word and the depth matters. The snapshot is a
+   * shallow spread of the caller's payload, so a NESTED object reached through
+   * a key here is the caller's own reference and is mutable — `Object.freeze`
+   * does not travel. That is not a laundering route (a nested mutation on a
+   * hidden read-only key is handed back and stripped; the recorder never saw a
+   * hook write), but it is not a deep guarantee either, and a handler must not
+   * treat a nested read from here as tamper-proof. Deep-freezing was not
+   * chosen: it costs a full walk of every payload on every update, to harden a
+   * face documented as diagnostics-only.
    *
    * ⚠️ A value HERE and no matching key in `input.data` means precisely one
    * thing: the engine refused that field. It does not mean the field is