feat(spec,objectql,runtime): declare ctx.referentialFieldClear on HookContextSchema, populate every set_null cleanup write, and carry it across the QuickJS sandbox boundary

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers

.changeset/hook-ctx-referential-field-clear.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec,objectql,runtime): declare `ctx.referentialFieldClear` on `HookContextSchema`, populate it on every `set_null` reference-cleanup write, and carry it across the QuickJS sandbox boundary by contract (#13644)
+
+Adopted by maintainer ruling 2026-08-31 (issue #13644, decision record on the
+card): a first-class, declared marker for the engine's own reference-cleanup
+writes, with both mandated conditions in the same landing — the sandbox carry
+and the populate-surface pin.
+
+The engine implements `deleteBehavior: 'set_null'` by UPDATING the row that
+HOLDS the lookup, and it builds that cleanup write's context by inheriting the
+caller's envelope — so on the path a real request takes (a `DELETE` carrying a
+`userId`), `ctx.user`, `ctx.session` and `ctx.input` are identical between the
+engine's cascade and a user's hand-clear of the same lookup. An app guard that
+freezes settled records had no declared way to yield to the cleanup: the only
+prior signal was the operation-private `__referentialFieldClear`, which the
+platform's own `__` convention declares outside the contract and which the
+sandbox marshalling never carried.
+
+- **spec (minor):** `HookContextSchema` declares `referentialFieldClear`
+ (boolean, optional) — `true` exactly when the write is the engine's own
+ reference cleanup (clearing the slot, or removing the deleted member from a
+ `multiple: true` lookup); absent on every other dispatch. Widens the accept
+ set by one optional engine-produced key on the deliberately non-strict
+ runtime context shape; nothing previously valid changes meaning.
+- **objectql (minor):** `update()`'s hook-context assembly projects the marker
+ from the operation envelope onto the declared key, both phases and the
+ per-row fan-out included. Pinned write site by write site (scalar clear and
+ multi-value member removal, each beside a hand-clear control under the same
+ caller identity, plus an envelope-consistency leg) in
+ `engine-cascade-delete.test.ts`.
+- **runtime (minor):** the QuickJS marshalling carries the declared key into a
+ shipped body (`buildSandboxContext` / `installCtx`), so
+ `ctx.referentialFieldClear === true` is readable from inside the VM —
+ pinned from inside a real QuickJS run in
+ `referential-field-clear-signal.integration.test.ts` (⛔ not a kernel-rig
+ read; the #11552 declared≠observable family is the reason the ruling makes
+ this a condition of adoption).
+
+The operation-private `__referentialFieldClear` stays: it remains the
+engine/middleware authorization channel (plugin-security's ownership-anchor
+exemption keys on it before any hook runs). The declared key is its read-only
+hook-context projection — one fact, two faces, pinned together.

content/docs/permissions/system-context.mdx

@@ -109,18 +109,18 @@ that silently does not happen.
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10882` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11044` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9747` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10914` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11076` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9772` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1737` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9784`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5705` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3574`, `:3584`, `:3611` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9809`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5730` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3599`, `:3609`, `:3636` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6403` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11630` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11559` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6428` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11662` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11591` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
 | 62 | `objectql/src/engine.ts:3406` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:13971` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 63 | `objectql/src/engine.ts:14011` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9730`–`9747` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9755`–`9772` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |

content/docs/references/data/hook.mdx

@@ -36,6 +36,7 @@ const result = HookContextSchema.parse(data);
 | **dispatch** | `{ mode: Enum<'record' \| 'per-row'>; index: integer; scope: Record<string, any> }` | optional | How this hook call relates to the caller's write (engine-produced) |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; accessToken?: string; … }` | optional | Current session context |
 | **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **referentialFieldClear** | `boolean` | optional | Engine-produced marker: true exactly when this write is the engine's own referential cleanup (the set_null cascade UPDATE clearing — or, for multiple: true, removing the deleted member from — a lookup that references a record being deleted). Absent on every other write, including a user hand-clearing the same lookup; read as `ctx.referentialFieldClear === true`. The declared projection of the operation-private `__referentialFieldClear`, carried across the sandbox boundary by contract; server-derived and never client-supplied. |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (IScopedContext — `object(name)` + `transaction(cb)`) |

packages/core/src/security/operation-private-keys.ts

@@ -24,7 +24,12 @@
  * `__expandRead` marks a read as a lookup EXPANSION sub-read (it no longer
  * relaxes any gate — #7626 removed that waiver — but it still travels with
  * one operation and must not be inherited by another), `__referentialFieldClear`
- * authorizes the referential-clear write.
+ * authorizes the referential-clear write. [#13644] The latter also has a
+ * DECLARED, read-only projection — `HookContext.referentialFieldClear`
+ * (`@objectstack/spec/data`), populated by objectql's `update()` assembly
+ * and carried across the sandbox boundary by contract — which is what an
+ * APP reads; the `__` key here remains the engine/middleware authorization
+ * channel, and this file's stripping rule is unchanged by the projection.
  *
  * plugin-security is the PRODUCER of that vocabulary and would be the most
  * honest owner of the rule for consuming it, but none of the three consumers