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

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-support-ai]

Fixes#13644

Executes the 2026-08-31 adoption ruling (decision record: issue comment 5478756633): declare a first-class ctx.referentialFieldClear on HookContextSchema, populated by the engine on every reference-cleanup write (deleteBehavior: 'set_null' cascade), and carried across the sandbox boundary by contract — with BOTH mandated conditions landed as executable pins in this same PR.

Clause-②: yes — published contract-surface widening (one new optional, engine-produced key on HookContextSchema). Parked for the contract-review tier per the ruling; no enqueue from this seat.

Freshness gate honoured

Designed from the filer's correction comment (5474384377), not from the body's "Measured on 17.1.0" table (a rig artifact, per the ruling's own record). The engine builds the cleanup write's context by spreading the caller's envelope and adding the transaction handle and the operation-private marker — it inherits whatever identity the caller supplied — so on the path a real request takes (a REST 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. Consequences taken in this PR:

• every pin runs under a full REST-shaped caller envelope (userId plus isSystem), so the discriminator-erasing condition is in force inside the tests rather than dodged by an identity-less rig context;
• the identity-less shape (what the original card's rig happened to measure) is additionally pinned, proving the marker keys on the operation and not on any identity member.

What landed

• spec — packages/spec/src/data/hook.zod.ts: referentialFieldClear (boolean, optional) declared on HookContextSchema, placed with the other server-stamped write metadata (beside provenance). The doc block carries the one-fact-two-faces relationship to the operation-private key, the sandbox-carry contract, and the trust model (server-derived, never client-supplied). Parse pins added in packages/spec/src/data/hook.test.ts — load-bearing because this schema STRIPS undeclared keys on parse, so without the declaration a parsed context would silently lose the key.
• objectql — packages/objectql/src/engine.ts: new buildReferentialFieldClear (sibling of buildSession / buildProvenance) projects the operation envelope's private marker onto the declared key at update()'s hook-context assembly — a single site that covers both phases and the per-row fan-out, because the after phase reuses the assembled context and the per-row contexts spread it. Conditional spread keeps the key truly absent (never present-but-undefined) on every other write. The 属主守卫与级联 set_null 冲突:非特权删除 sys_user 时 owner_id 级联置空被 #3004 守卫拦截(级联中途失败) #3023 cascade-site comment now names the projection.
• runtime — packages/runtime/src/sandbox/script-runner.ts (ScriptContext.referentialFieldClear, documented), body-runner.ts (buildSandboxContext copies it, hook face only, only in its declared shape true), quickjs-runner.ts (installCtx installs it on the VM ctx).
• core — comment-only: packages/core/src/security/operation-private-keys.ts header now names the declared projection, so the operation-private registration cannot be misread as the app-facing channel. No behavior change, no changeset.
• changeset .changeset/hook-ctx-referential-field-clear.md (spec minor / objectql minor / runtime minor), citing the ruling.
• docs: content/docs/references/data/hook.mdx regenerated (gen:docs); content/docs/permissions/system-context.mdx re-anchored by the census gate's own --fix (pure line rot from the engine.ts insertions, 14 + 5 anchors, verified OK after).

Mandated condition 1 — sandbox reachability, pinned from inside the VM

packages/runtime/src/sandbox/referential-field-clear-signal.integration.test.ts — real ObjectQL + real SqlDriver (better-sqlite3) + real QuickJSScriptRunner behind hookBodyRunnerFactory, the same wiring AppPlugin performs. Every assertion lands on what the body OBSERVED (reported out through the log capability):

• on the cleanup write, ctx.referentialFieldClear === true inside the VM, in both phases, with the inherited caller identity present alongside;
• on the user's hand-clear of the SAME lookup under the SAME identity, the key is ABSENT (typeof reads 'undefined'), so the guard idiom reads false.

This is deliberately NOT a kernel-rig read — the ruling names the #11552 declared-vs-observable family as the reason sandbox reachability is a condition of adoption, and the operation-private spelling is exactly what a kernel rig could read and a shipped body could not (buildSandboxApi may hand a body an object shim with no executionContext at all).

Mandated condition 2 — populate surface, pinned write site by write site

New describe in packages/objectql/src/engine-cascade-delete.test.ts:

• scalar set_null clear: true in both phases, caller identity inherited, and the hand-clear control has NO key at all (absence asserted with an in check, not just an undefined read);
• multiple: true member removal — the second cleanup write site in cascadeDeleteRelations — same assertions against its own hand-edit control;
• an identity-less delete still marks its cleanup writes;
• the one-fact-two-faces consistency leg: middleware captures the operation-private marker on the same writes, and the declared face is true exactly where the envelope carries it, write for write (three ops asserted in order: hand-clear, restore, cleanup).

Derived judgments — each stated, none silently decided

1. Accept-set change: pure widening by one optional, engine-produced key on the deliberately non-strict runtime context shape. No previously valid context changes meaning; a context without the key parses exactly as before; the engine writes true or omits the key, never false.
2. Old operation-private key disposition: KEPT, unchanged.__referentialFieldClear remains the engine/middleware authorization channel — plugin-security's ownership-anchor exemption reads it off the operation context before any hook runs — and the operation-private-keys stripping rule is untouched. The declared key is a read-only projection, not a replacement; no dual-write transition is needed because the two faces have one producer site each and the projection is derived at assembly. The governance ledger needed no mechanical change (comment updated only).
3. Envelope-scoped semantics, flagged: the declared key faithfully projects the envelope fact. A write a hook itself issues through ctx.api DURING a cleanup dispatch runs on the same inherited envelope and therefore carries the marker too — this is the semantics the operation-private key has always had (and what plugin-security keys on), projected rather than quietly re-scoped. If a strictly per-write-site signal is ever wanted instead, that is a contract decision to take explicitly, not a default this PR assumes.
4. Populate site singular (update assembly only), flagged: every reference-cleanup write the engine issues is an update, so update()'s assembly is the complete populate surface. The find/insert/delete assemblies deliberately do NOT project the envelope — a delete or insert is never itself a reference-cleanup write, and advertising the envelope there would widen the key's meaning without a pull.
5. Semver: spec minor (declared contract-surface widening), objectql minor (the engine now populates a declared contract face), runtime minor (a new marshalled member of the sandbox contract). core is comment-only: no changeset.
6. ADR-0087: non-breaking addition — no disposition marker owed on a non-breaking changeset; check:adr-0087-registration green.

Tests and gates — real readings, final tree

All exit codes captured redirect-first (never through a pipe); heavy runs serialized through scripts/pm/os-verify-lock.sh. Final union re-run at HEAD 1108016dd (post-merge of origin/main, census deferral discharged):

• spec src/data/hook.test.ts: 79 passed (79) — includes the two new parse pins
• core src/security/operation-private-keys.test.ts: 8 passed (8)
• objectql src/engine-cascade-delete.test.ts + src/hook-input-shape-contract.test.ts: 35 passed (35)
• runtime src/sandbox/referential-field-clear-signal.integration.test.ts: 1 passed (real QuickJS; earlier full sandbox sweep also green: perrow-dispatch-signal.integration + body-runner + quickjs-runner = 101 passed (101))
• typecheck: spec, objectql, runtime all green on the merged tree (objectql's check:test-typecheck ratchet held at its ledgered count — one new TS2345 was introduced by the suite and fixed rather than ledgered). Note runtime's tsc --noEmit excludes test files by its tsconfig (pre-existing), so the new integration test is proven by execution, not by tsc.
• full workspace build: turbo 71/71 tasks successful (9m50s); check:dev-prereqs green after the post-merge spec rebuild ("built from the sources on disk"); pnpm check:dual-build-cjs-loads green (93 self-test cases + ledger)
• pnpm --filter @objectstack/spec check:generated: one stale artifact (check:docs) regenerated via --fix; full re-run green. check:authorable-surface green (data shard gained the one declared row)
• pnpm check:type-check-debt on the merged tree: "27 ledger entries re-measured, 1217 raw tsc errors total, none above its recorded number; surplus: none" — nothing raised
• gate families derived from the actual change set (node scripts/pm/dispatch-gates.mjs, no hand-fed paths, re-derived after fetching origin/main): all derived local gates green, including check:system-context-census (line-rot re-anchored via its own --fix, verified "109 sites, all anchored"), check:engine-split-ratio (after the gate's own deepen remedy), check:corpus-claim-drift, check:doc-anchors, check:kernel-hook-pairs, check:cross-package-test-inputs, check:test-source-alias, check:durability-log-level, and the spec-scoped family (docs/liveness/strictness-ledger/llms-txt/skill-refs/variant-docs/yaml-examples/empty-state/skill-examples)
• node scripts/check-test-completeness.mjs: exit 3 PREREQUISITE NOT MET — by its own text the local reading is NOT MEASURED (it grades a saved turbo test log CI produces); left to CI
• check:nul-bytes green (7751 files scanned)

Out of scope: #13331 remains open and untouched by this PR (its branch carries no commits; its lane escalated to a maintainer decision independently of this card).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/core, @objectstack/objectql, @objectstack/runtime, @objectstack/spec, touching 8 documentable anchor(s). ⚠️2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx(via ScriptContext (symbol, a top-level interface))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx(via HookContextSchema (symbol, a top-level const), cascadeDeleteRelations (symbol, a method of class ObjectQL))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/core/src/security/operation-private-keys.ts, packages/spec/authorable-surface/data.json) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 65 pages)
• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 139 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea363f033874f43918c13e0f1d6e8714fe3782ee — the merge of head 1108016ddda0e77ef797776bd9f8a2d146e4309f into base 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ea363f033874f43918c13e0f1d6e8714fe3782ee && git checkout ea363f033874f43918c13e0f1d6e8714fe3782ee
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 1108016ddda0e77ef797776bd9f8a2d146e4309f && git checkout -B drift-repro 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 && git merge --no-ff 1108016ddda0e77ef797776bd9f8a2d146e4309f
node scripts/docs-audit/affected-docs.mjs --json 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4d672c4ffe15b1fe2365e5efbf7251778f2c3e33 → pass the list as
args.docs, on the commit named under Which tree this was computed on.