fix(objectql)!: a user field's declared deleteBehavior takes effect when the user is deleted (#29253) - #29368

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql, touching 7 documentable anchor(s).

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

• content/docs/api/data-api.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/data-modeling/field-types.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/data-modeling/fields.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/data-modeling/validation-rules.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/deployment/cli.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/deployment/troubleshooting.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/protocol/objectql/types.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))

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

• content/docs/releases/v15.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))
• content/docs/releases/v17/17-1.mdx (via set_null (literal, a string literal in DECLARED_DELETE_BEHAVIORS; a string literal in a comment in cascadeRelationBehavior))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin af739b179eae0b0e3faf4dac464144a785dbf826 && git checkout af739b179eae0b0e3faf4dac464144a785dbf826
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin eef116e4d1dd3b01d68371df4f775b0c77227ef0 4a0ed134f4d43b1fd9079c2cb3e60e27b1d70a02 && git checkout -B drift-repro eef116e4d1dd3b01d68371df4f775b0c77227ef0 && git merge --no-ff 4a0ed134f4d43b1fd9079c2cb3e60e27b1d70a02

node scripts/docs-audit/affected-docs.mjs --json eef116e4d1dd3b01d68371df4f775b0c77227ef0

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 eef116e4d1dd3b01d68371df4f775b0c77227ef0 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#5 · os-steve · session_01ADHkmQKwKFCp1m6Pb6Q8c1

Contract-review-claim: session_01ADHkmQKwKFCp1m6Pb6Q8c1 · head 4a0ed13 · 2026-11-02T14:07Z

The narrowing face is reviewed at CONTRACT_REVIEW_TIER by this seat, which dispatched the card, through an at-tier reviewer that is not the drafter. The scope is every path of the diff outside the prose faces.

domain:server#5 · os-steve · session_01ADHkmQKwKFCp1m6Pb6Q8c1

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 4a0ed134f4d43b1fd9079c2cb3e60e27b1d70a02
Local-runs: none
Scope: packages/objectql/src/engine.ts, packages/objectql/src/engine-cascade-delete-user-field.test.ts, packages/objectql/src/federated-injected-column-readers.test.ts + packages/spec/src/data/field.zod.ts (deleteBehavior, the .overwrite tail, the user reference refusal, Field.user), packages/spec/src/data/field-value.zod.ts (referenceTargetOf, referenceCarrierOf, MULTI_CAPABLE_TYPES), packages/objectql/src/engine-referential-integrity.ts (the write-side check; the delete walk is not there), packages/plugins/plugin-auth/src/identity-write-guard.ts, packages/plugins/plugin-auth/src/objectql-adapter.ts (withSystemContext, delete/deleteMany, rethrowAsBetterAuthError), packages/plugins/plugin-auth/src/auth-manager.ts (runSubjectErasureAtomically), packages/plugins/plugin-auth/src/session-tombstone.ts (SESSION_ERASURE_PATHS), packages/spec/src/data/injected-system-column-provenance.ts (owner_id), packages/platform-objects/src/identity/sys-user.object.ts, packages/verify/src/delete-behavior.ts, packages/spec/src/migrations/entries/semantic/18.user-field-foreign-reference-refused.ts, packages/spec/src/migrations/entries/semantic/18.field-master-detail-set-null-refused.ts, .changeset/29253-user-field-delete-behavior.md, scripts/check-adr-0087-registration.mjs, scripts/check-changeset-no-major.mjs. The prose faces (content/docs/data-modeling/fields.mdx, the changeset body as prose) are the seat's ACCEPT; the changeset's declaration lines and semver level are judged in ②.

Inputs read: card #29253 (body, triage 6575476068, claims 6575764728 / 6575797254 / 6575850669 / 6575856999, os-dev-report 6578157141), PR #29368 (body, file list, net diff origin/main...4a0ed134), the check-runs on the head. Not read as inputs: the dispatch order or the dispatching seat's conclusions. The dev's report was treated as claims and each one was checked in the tree.

Check-runs on this head: every run is completed. Every check is success or skipped, with one exception. Check Changeset has three runs on this head: run 41452481747 (13:22Z) failed at the step "Guard against accidental major bumps (launch window)", and runs 41458196936 (14:02Z) and 41458906013 (14:07Z) succeeded. That step reads the PR body as the declaration input (--event), and the PR body was edited between the runs. The newest run of that check on this head is green, so the gate verdict on the head is green; the earlier red is not a merge-base signature and is not re-judged here. The PR is a draft with no auto-merge armed.

① Derived judgments

1. Accept set of what an author may write: unchanged. FieldSchema on main accepts deleteBehavior on any type and returns an authored value verbatim (the === undefined guard in the .overwrite tail). The diff touches no packages/spec/** file. Right.
2. Runtime meaning of an authored deleteBehavior on a user field: from inert to enforced. statesDeleteSemantics admits a user field when, and only when, deleteBehavior is one of set_null / cascade / restrict; the field then runs the lookup path with its authored value. restrict and a required set_null refuse the user delete with 409 DELETE_RESTRICTED where it answered 200. This is the narrowing. Right, and the only runtime change the diff makes.
3. A bare user field: unchanged. The spec's parse materializes set_null on lookup and tree only (field.zod.ts, if (field.deleteBehavior === undefined && (field.type === 'lookup' || field.type === 'tree'))), so a parsed user field carries no key, and the engine invents none (DELETE_SEMANTICS_REFERENCE_TYPES still lists master_detail, lookup, tree; the || 'set_null' fallback is unreachable for user). Pinned by four controls and ablation 3. Right.
4. deleteWalkTargetOf: the carrier is still read through referenceCarrierOf (an unreadable carrier throws; absence answers undefined); a user field answers referenceTargetOf, which is sys_user by IMPLICIT_REFERENCE_TARGETS whatever the carrier says. So { type: 'user', deleteBehavior: 'restrict' } with no reference takes part. Right; it follows the one arbiter the spec already publishes.
5. planCascadeAtomicity('sys_user'): answers 'atomic' (or 'split' across datasources) instead of 'none' once a registered object declares a user field with a deleteBehavior. A user delete then runs inside a transaction where none was opened. Right, and required: the pinned "restrict after cascade rolls the cascade back" depends on it. The driver-without-beginTransaction degrade is the inherited ADR-0119 D1 one.
6. getCascadeDeleteObjects / the metadata read's cascadeDeleteObjects (Delete confirm: an object can word its Delete confirmation, or the confirmation names what a cascade will delete #28001) reads through cascadeRelationBehavior, so an object whose user field declares cascade is now named. Right (same reader, one answer). The published describe strings still enumerate only master_detail / lookup / tree: see ④ finding B.
7. Reader ledger (federated-injected-column-readers.test.ts): the two referenceCarrierOf() rows under cascadeRelationBehavior and planCascadeAtomicity are replaced by two not-a-read rows under deleteWalkTargetOf (referenceCarrierOf() and referenceTargetOf()). Both callers keep their own isFederatedUnprovisionedInjectedColumn() rows and, in the code, still ask the skip after the reference match. Right; Test Core on the head is green, so the source scan agrees with the table.
8. Public surface: no export, type, schema key or error code moves. USER_REFERENCE_TYPE, DECLARED_DELETE_BEHAVIORS, statesDeleteSemantics and deleteWalkTargetOf are module-private. DELETE_RESTRICTED / 409 is the walk's existing envelope. Right.
9. Doors, as the dev measured and as read here: better-auth's delete / deleteMany in the adapter call dataEngine.delete(objectName, { where: { id: record.id } }) under withSystemContext (isSystem: true, attribution added), which is the engine's by-id branch, so the walk runs. identity-write-guard registers beforeDelete at priority 10 and refuses a caller-context delete of any managedBy: 'better-auth' object (sys_user declares it). /delete-user, /delete-user/callback and /admin/remove-user are in SESSION_ERASURE_PATHS and run under runSubjectErasureAtomically. Ban is an update. No driver.delete of sys_user exists outside the engine (grep of non-test sources). Right.
10. The repo-wide claim "no platform object or example declares deleteBehavior on a user field": checked by listing every non-test, non-spec file that declares Field.user( or type: 'user' and counting deleteBehavior in it; only engine.ts hits (its comments). The injected owner_id column is a lookup to sys_user (already in the walk), not a user field; sys_user.manager_id is a lookup. Right.
11. os verify --delete-behaviors: packages/verify/src/delete-behavior.ts reads REFERENCE_VALUE_TYPES, so a user field with an authored value is a case; its target sys_user is not an app-declared object, so it is graded not-derivable, never contradicted. The dev's claim holds; that family does not start failing apps.

② Semver level

• '@objectstack/objectql': minor. Right under the launch-window rule in check-changeset-no-major.mjs: the level follows the metadata protocol alone; a semantic kind grades minor; breaking ships as minor with the BREAKING banner and an ADR-0087 disposition as the carriers.
• Clause-②: no (narrowing) on the PR body (line 6) and the changeset (line 7). Right. Nothing is widened; at the user-delete door an existing declaration turns a 200 into a 409, which is the narrowing arm's definition. The title carries the bang. The dispatch claims (6575764728 / 6575856999) said Clause-②: no and Metadata-protocol: none; the seat re-ruled after round 1 (PR body, Acceptance notes). The re-ruling is the right reading; see ③ flag 1.
• Metadata-protocol: semantic. Right: no key is added or narrowed; an accepted key's meaning changes on one type.
• The ADR-0087 marker, adr-0087: not-required (no-migration-prescription) with its why-text. Mechanically valid (the gate's prescription regexes look for framed arrows and table rows, and the body has none; the head's Check Changeset passed the disposition step). Judged on substance it is the weaker of two honest answers, for three reasons. (a) The ledger's SemanticMigration kind exists for exactly this class, and two 18.x entries on main are the precedent: field-master-detail-set-null-refused (an accepted deleteBehavior whose enforcement changed, no key moved) and user-field-foreign-reference-refused (which says a user field's delete behaviour "is owed by the author"). (b) The changeset itself states the consumer judgment owed ("remove it or change it to what you want enforced") and names a stored population that must be reviewed (pre-FieldSchema.deleteBehavior defaults set_null onto EVERY field type, so built artifacts ship the key on text/datetime/number fields #9784 materialized set_null on user fields), while the marker text says "there is no stored value for a conversion to rewrite". The two statements contradict each other inside one changeset; the honest form is "no conversion, one semantic entry", as the two precedents spell it. (c) Only a ledger entry reaches objectstack migrate meta and the generated upgrade guide; the changeset banner does not. The dev could not write the entry: the claim's file surface forbids packages/spec/**. Finding A in ④, should-fix: a domain:spec follow-up registers a semantic entry, and the disposition becomes registered.

③ Boundary flags

1. open_questions[0], the Clause-② reading (dev recommended A: no; seat ruled B: no (narrowing)). Answer: B. The arm is read at the consumer's door, not at the authoring face. An author's accept set is unchanged, but a deployment's user-delete request that succeeded is refused on this head with an existing declaration. That is a narrowing. Resolved on this head: bang, arm on body and changeset, banner, and the dogfood run the body reports.
2. open_questions[1], rows stored before FieldSchema.deleteBehavior defaults set_null onto EVERY field type, so built artifacts ship the key on text/datetime/number fields #9784 (the dev recommends A: accept). Answer: A for set_null on a non-required user field, because clearing a deleted user's id is the only effect and it is what the same declaration does on a lookup. For a required user field that carries the era's materialized set_null, the user delete becomes a 409 nobody authored. That is a consumer judgment with no mechanical answer, which is what the ledger's semantic kind records. Escalated to domain:spec as part of finding A. The changeset states the population; it cannot be measured from this container, and I did not re-measure.
3. Dev flag, forced edit of the reader ledger. Answer: right (① item 7).
4. Dev flag, main moved 25 commits after the one merge. The head's checks ran on the PR merge ref and are green; no re-judgment owed here.
5. Dev flag, the harness asked for an assignee and a review request via MCP and the dev declined. Procedural; the seat's.
6. Dev out_of_scope finding, stale spec prose. Confirmed, and wider than the two sites named. On main: the field.zod.ts .overwrite comment ("user ... sits outside the delete walk's family ... exactly like text"); the user reference refusal message ("a user field never did"); the D3 entry user-field-foreign-reference-refused ("which a user field never did"); hook.zod.ts referentialFieldClear / referentialCascadeDelete describes (name lookup and tree only); contracts/objectql-engine.ts getCascadeDeleteObjects docblock and api/protocol.zod.ts cascadeDeleteObjects describe (enumerate master_detail / lookup / tree). Describe strings are the published spec. Finding B in ④, should-fix, one domain:spec card together with A.
7. Also read: field.form.ts and object.form.ts show deleteBehavior only when data.type == 'lookup' or 'master_detail'. Studio cannot author the key on a user field, and cannot clear a pre-FieldSchema.deleteBehavior defaults set_null onto EVERY field type, so built artifacts ship the key on text/datetime/number fields #9784 stored value through the form either. This supports the dev's blast-radius claim (the authored population is code, JSON and YAML authors plus era artifacts) and belongs to the domain:spec card: whether the form shows the key on user now that it is honoured.
8. Skills-docs follow-up: skills(objectstack-data): a user field's declared deleteBehavior now takes effect when the user is deleted (#29253) — the field-type and relationship rules should say so #29400 exists, is open, and names the two skill files. Noted.
9. PR user.login is objectstack-fleet[bot]; no out-of-relay author note is owed.
10. Check-runs: the one red Check Changeset run is superseded by two later green runs on the same head (preamble). No gate on the head is red.

④ Design judgment

The narrowing against the published spec on main. The spec accepts and round-trips deleteBehavior on a user field, describes the key as "What happens if referenced record is deleted", declares no default for user (the .overwrite tail materializes on lookup and tree only), and its own D3 entry says "deleteBehavior has no value that means 'leave it' ... a delete-behaviour judgement is owed by the author". The diff makes an authored value do what the key says, and keeps absence as "leave it". That is the spec's own declaration made real. The one capability it takes away at the consumer is deleting a user that an authored restrict (or a required set_null) holds, which is what the author declared. Verdict: the narrowing holds. Each case the brief names, read in the tree:

• A user delete through a door that skips the walk. None found. better-auth deletes by id through the adapter into engine.delete; the generic data doors refuse a caller-context sys_user delete in identity-write-guard; a system-context generic delete (a flow's elevated write, a seed) still goes through engine.delete, by id or by predicate, and both arms run the walk (objectql: a predicate delete (multi: true with a filter) skips the referential walk, so a flow's bulk delete_record bypasses restrict, master_detail cascade and set_null #26871). SCIM DELETE /Users/{id} is a deactivation update on 1.7.2 (auth-manager.ts docblock). No raw driver.delete of sys_user outside the engine. Residual, pre-existing and outside this card: the guard's isUserContextWrite needs a userId, so a sessionless caller context passes it; such a delete still reaches the walk, so the narrowing holds for it too.
• Cascade loops. A user field on sys_user itself would be a self-reference; collectCascadeDeleteSet does not expand a record already in the set and the recursion is bounded by MAX_CASCADE_DEPTH, the same terms a tree cycle has. On main sys_user.manager_id is a lookup (already in the walk) and no object declares a user field with a deleteBehavior. Holds.
• A multi-valued user field. user is in MULTI_CAPABLE_TYPES, so declaredMultiValued is true: the probe uses the $contains limb and the exact storedReferenceIncludes narrowing, set_null removes the member and writes [] for an emptied set, and the required escalation is decided per row. Pinned for restrict, cascade and set_null. Holds.
• set_null on a required field. Single-valued escalates to restrict before the probe (409, pinned); multi-valued escalates per row after it (a row that keeps another member takes the removal). The same rule a required lookup has. Holds.
• A user field with no declared behaviour. Stays out; four controls pinned (parsed single, parsed multi, raw, required); ablation 3 shows the arm is live. Holds.
• A field naming no reference. deleteWalkTargetOf answers sys_user through referenceTargetOf; pinned (uf_bare_ref). A raw user registration naming a foreign reference (refused at parse) follows sys_user, which is referenceTargetOf's contract on main. Holds.
• restrict surfacing through the auth door with a correct rollback. The walk throws DELETE_RESTRICTED inside the by-id transaction, which joins the ambient transaction runSubjectErasureAtomically opened (ADR-0067 D2 handle). withValidationErrorMapping maps it to APIError('CONFLICT') with code DELETE_RESTRICTED, developerMessage, dependentObject and dependentCount (the admin-lifecycle: remove-user is non-atomic and can never succeed — 409 leaks as a bodyless HTTP 500, credential rows deleted without rollback #7724 arm, type-agnostic). better-auth returns the 409; a response status of 400 or above throws SubjectErasureRollback, and the session and account rows deleted before the user row roll back. Holds on a driver with beginTransaction; a driver without one has the declared ADR-0119 D1 degrade the auth-manager docblock already states. The engine half is pinned on this PR (committed has length 0); the adapter half is read, not re-pinned here, and is already pinned by the admin-lifecycle: remove-user is non-atomic and can never succeed — 409 leaks as a bodyless HTTP 500, credential rows deleted without rollback #7724 tests for a lookup.
• Tenancy and cross-org rows. sys_user is platform-global; holders are organization-scoped. The probe runs as { ...context, isSystem: true }; the adapter's context carries no tenantId, so buildDriverOptions forwards none and the probe spans every organization. A restrict holder in any organization refuses the delete; cascade deletes holders in every organization; set_null clears them everywhere. That is the right reading for a global row: a holder in another organization would otherwise dangle. dependentCount is disclosed because the adapter's context is system, so the auth caller sees a count across organizations; the admin plugin is platform-level, and the count discloses nothing the envelope did not already carry for a lookup to sys_user. Holds.

Findings:

• A, should-fix. ADR-0087 disposition. The right disposition is registered with a SemanticMigration entry (surface: object.fields[].deleteBehavior on type: 'user'; replacement: declare the value you want enforced or drop the key; reason: an accepted declaration is now honoured, and pre-FieldSchema.deleteBehavior defaults set_null onto EVERY field type, so built artifacts ship the key on text/datetime/number fields #9784 stored rows may carry a materialized set_null; acceptance: every user field's deleteBehavior is authored on purpose, and a required one does not carry set_null). The entry belongs to domain:spec (the card's file surface forbade packages/spec/**), so this is a follow-up card, not a change to this PR. The marker's "there is no stored value" clause and the "Rows stored before FieldSchema.deleteBehavior defaults set_null onto EVERY field type, so built artifacts ship the key on text/datetime/number fields #9784" paragraph should be reconciled when the entry lands. Not a must-fix: the marker is mechanically valid, and the banner plus the fix line carry the signal during the launch window.
• B, should-fix. Published spec prose that enumerates the walk's family or says a user field never joins it (③ flag 6 lists the six sites). One domain:spec card with A. Not a must-fix: describe strings, no accept-set or runtime effect.
• Note, not graded. DECLARED_DELETE_BEHAVIORS is a second spelling of the spec's z.enum(['set_null', 'cascade', 'restrict']); the spec exports no constant for it, so there is nothing to import today. A raw user registration with an off-enum value is silently out of the walk, where the same value on a lookup falls to the set_null branch. Both are around-the-parse shapes; the user reading is the more conservative one and matches the file's "no default is invented here" rule.

No must-fix. The tree matches the PR body's account on every point checked; nothing was judged from the account.

Implemented-by: claude/project-thread-u66mdq
Reviewed-by: session_01ADHkmQKwKFCp1m6Pb6Q8c1

VERDICT: PASS

domain:server#5 · os-steve · session_01ADHkmQKwKFCp1m6Pb6Q8c1

维护者速读

• 改了什么：user 字段上写明的 deleteBehavior 现在在删除用户时生效。restrict 拒绝删除(409),cascade 连带删除，set_null 清空(多值字段只移除该成员)。没写 deleteBehavior 的 user 字段不变。
• 为什么改：spec 接受并保留这个声明，但引擎的删除联动不认 user 字段，声明一直是摆设。
• 风险与回滚：收紧(BREAKING,objectql minor,Metadata-protocol semantic)。写了 restrict 或 required+set_null 的应用，删除被引用用户从 200 变 409。仓内无此类字段。回滚即 revert。
• 先看:packages/objectql/src/engine.ts 的 statesDeleteSemantics / deleteWalkTargetOf。
• 两分钟验证:pnpm --filter @objectstack/objectql exec vitest run src/engine-cascade-delete-user-field.test.ts,16 条全绿。
• 需要你做的：无，席位落地。

席位意见：契约复审 PASS(本 PR 上的记录,head 4a0ed134)。两条 should-fix 都要改 packages/spec/**,已立 spec 卡 #29415,不阻塞本 PR。

席位核对

ACCEPT · domain:server seat 5 · os-steve · session_01ADHkmQKwKFCp1m6Pb6Q8c1 · 2026-11-02T14:23Z · head 4a0ed134f4 · Fixes #29253

1. Shape: draft against main, Fixes #29253. A minor changeset for @objectstack/objectql with a BREAKING banner. Clause-②: no (narrowing), Metadata-protocol: semantic, and a Skills-docs: line pointing at skills(objectstack-data): a user field's declared deleteBehavior now takes effect when the user is deleted (#29253) — the field-type and relationship rules should say so #29400. Not governed: 478 changed lines, 5 files.
2. Against the order: a declared deleteBehavior on a user field joins the delete walk. Bare user fields stay out. Read in the diff and confirmed by the at-tier contract review (PASS).
3. Accepted deviations: the seat ruled the Clause-② arm (narrowing) in place of the dev's no. The changeset and body follow it.
4. Gates: check-runs on this head: Lint & Repo Gates, TypeScript Type Check and Check Changeset (the last two runs) are green. An early Check Changeset run failed before the body edit; the later runs on the same head passed. Nothing is red or running.
5. Out of scope: the ADR-0087 semantic entry and the spec prose → spec(migrations): register the user-field deleteBehavior enforcement (#29253) as an ADR-0087 semantic entry and stop the spec prose saying a user field never joins the delete walk #29415 (spec). Skills → skills(objectstack-data): a user field's declared deleteBehavior now takes effect when the user is deleted (#29253) — the field-type and relationship rules should say so #29400.
6. Landing: pr_ready + automerge_enable through the relay. objectql: a plain lookup write accepts a target the writer cannot read — the reference check probes it elevated, and only master_detail asks the caller's read door #29029 opens its PR after this merges.