Declare a first-class `ctx.referentialFieldClear` on HookContextSchema — apps can only tell the engine's `set_null` cleanup write from a user edit by reading the operation-private `__referentialFieldClear`, or by sniffing write shape

[os-trump]

Platform ask from an app that has now paid for the workaround three times over. Filed from objectstack-ai/hotcrm#1165; nothing is broken on the platform today, so this is a contract gap, not a defect.

The situation

The engine implements deleteBehavior: 'set_null' by UPDATING the row that HOLDS the lookup. So "delete the contact" arrives at the holder's beforeUpdate looking exactly like an ordinary user edit — and any app guard that freezes settled records refuses it, which makes a frozen record able to keep the person it references undeletable forever (a GDPR erasure with no way to carry it out). HotCRM hit this in its three freeze guards on crm_lead, crm_opportunity and crm_quote.

The engine already knows the difference. ObjectQL.cascadeDeleteRelations builds:

const referentialCtx = { ...context ?? {}, __referentialFieldClear: true };

But that key is operation-private, and there is no declared way for a hook to ask "is this write the engine's own reference cleanup?".

Measured on 17.1.0

Re-measured on @objectstack/* 17.1.0 (originally on 17.0.0 GA) by registering a probe hook at priority 199, immediately ahead of each guard, on all three objects, and walking the context of the engine's cleanup write against a user's hand-clear of the SAME lookup:

 cascade (engine) hand-clear (user)
api.executionContext keys
 [__referentialFieldClear, transaction] [isSystem, userId]
MARKER true undefined
ctx.user undefined { id: THE_CALLER }
ctx.session undefined { userId: THE_CALLER, isSystem: true }
ctx.input { id, LINK: null, updated_at } { id, LINK: null, updated_at, updated_by }
ctx.provenance undefined undefined

Identical on crm_opportunity, crm_quote and crm_lead.

So the marker IS reachable today, at ctx.api.executionContext.__referentialFieldClear. The app deliberately does not read it, and both reasons are exactly why a declared key is worth adding:

1. It is an operation-private key. The __ prefix is the platform's own convention for "not part of the contract" — the same convention buildSession enforces when it builds ctx.session field by field from a fixed, named allow-list that no __-prefixed key is in. An app building correctness on it has an undeclared dependency that can vanish in a patch release without anyone calling it a break.
2. Reachability through the shipped path is unproven. That reading was taken in a kernel rig, where handlers run natively and ctx.api is the engine's own ScopedContext (keys measured as [engine, executionContext, joinedHandles]). In production a hook body runs body-only inside QuickJS, and ctx.api there is whatever buildSandboxApi hands it: engineCtx.api when that exposes object(), and otherwise a shim of { object } carrying no executionContext at all. A predicate reading the marker could be green in the rig and silently false in production — the worst available outcome for a guard. Same family as ctx.dispatch?.mode === 'per-row' (objectstack#11552), which this app has already paid for once.

Note the fallback the app is left with is not sound either — it just fails safe rather than silently. The two writes differ in shape only because the engine happens to omit updated_by on the cascade; nothing declares that, and both writes clear the same declared link from a value to null with the referenced row readable from either.

Reading !ctx.session is not an alternative discriminator: buildSession's own contract makes undefined mean "no identity envelope was supplied", which is equally true of any bare-kernel or programmatic write.

The ask

A first-class, declared marker on the hook context:

• ctx.referentialFieldClear (boolean), declared on HookContextSchema in packages/spec;
• populated on every reference-cleanup write the engine issues;
• and, being declared, carried across the sandbox boundary by contract rather than by luck — which is the half __referentialFieldClear cannot offer at any level of care on the app side.

What it buys, concretely

In HotCRM specifically, and already quantified:

• three verbatim copies of a shape predicate (lead_automation, opportunity_lifecycle, quote_workflow) collapse into one honest read. They are copies rather than a shared helper because hook bodies run body-only and cannot reach module scope, so the app also carries a drift pin asserting the three copies stay byte-identical;
• the narrowness caveats that hotcrm#720 had to write down stop being load-bearing;
• the REFERENCE_FIELDS-completeness pin (which exists only because a lookup added to an object and not to the app's hand-maintained field list would silently go on blocking deletes) becomes unnecessary.

Generalises to any app with a freeze/lock/approval guard on an object that is the target of a set_null lookup — the guard has to yield to the engine's cleanup and has no declared way to recognise it.

Back-link: objectstack-ai/hotcrm#1165 (carries the original 17.0.0 GA measurement and the app-side ruling to keep sniffing shape until this lands).

---

Generated by Claude Code

[os-trump]

⚠️ Correction from the filer — the measurement table above is a rig artefact. The ask stands and gets stronger.

I filed this card. A re-measurement in the downstream app (objectstack-ai/hotcrm#1412, recorded as objectstack-ai/hotcrm#1424) shows the "Measured on 17.1.0" table in the body is wrong in three of its five rows, and that the paragraph beginning "the fallback the app is left with is not sound either" draws a false conclusion from them. Correcting it here rather than quietly, because anyone designing against this card would be designing against a bad reading.

What the table got wrong

The engine builds the cleanup write as { ...callerContext, transaction, __referentialFieldClear: true } — it inherits whatever identity the caller supplied. The original reading varied nothing and happened to be taken with a DELETE carrying no userId. Varying only that:

context passed to the DELETE	cascade executionContext keys	ctx.user	ctx.session	cascade ctx.input
{ userId, isSystem } — what a REST DELETE carries	[userId, isSystem, transaction, __referentialFieldClear]	the CALLER	{ userId, isSystem }	{ id, LINK: null, updated_at, updated_by }
{ isSystem }	[isSystem, transaction, __referentialFieldClear]	undefined	{ isSystem }	{ id, LINK: null, updated_at }
none at all	[transaction, __referentialFieldClear]	undefined	undefined	{ id, LINK: null, updated_at }

The body's table is row 3. On the path a real request takes — row 1 — ctx.user, ctx.session and ctx.input are identical between the engine's cascade and a user's hand-clear. updated_by and the identity are one fact, not two: both appear exactly when the DELETE carried a userId. Verified identically on crm_opportunity, crm_quote and crm_lead, including through a two-level master-detail cascade.

The sentence to strike, and why it inverts the argument

The two writes differ in shape only because the engine happens to omit updated_by on the cascade

They do not differ in shape at all on the real path. And updated_by would not have helped even where it differs — it is a system field that no app guard's predicate reads.

This makes the ask more necessary, not less. The card as written said the shape fallback is unsound-but-fails-safe, resting on an undeclared omission. The truth is worse: on the path that matters there is no discriminator available to an app at all except the operation-private __referentialFieldClear. An app guard must either read a __-prefixed key that the platform's own convention says is not part of the contract, or accept a predicate that cannot distinguish the two writes and therefore yields to any caller clearing a declared link on a settled record.

What is unchanged and still measured

• The marker is reachable at ctx.api.executionContext.__referentialFieldClear — true on every cascade, undefined on every hand-clear. Confirmed on 17.1.0.
• Both reasons the app declines to read it stand: it is operation-private (an undeclared dependency that can vanish in a patch release), and reachability through the shipped QuickJS path is unproven — buildSandboxApi passes engineCtx.api only when it exposes object(), and otherwise a shim with no executionContext at all. Green in a kernel rig, silently false in production, is the worst outcome a guard can have.
• The ask itself is unchanged: a declared ctx.referentialFieldClear on HookContextSchema, populated on every reference-cleanup write, carried across the sandbox boundary by contract rather than by luck. That last clause is the half __referentialFieldClear cannot offer at any level of care on the app side, and it is the whole point of the card.

Method note, since this card is an argument from measurement: the corrected reading came from a probe hook at priority 199 immediately ahead of each guard, varying only the context handed to the DELETE. The original reading's error was not a mistake in what it saw — it was holding one variable fixed without noticing it was a variable.

---

Generated by Claude Code

[os-warren]

Triage: needs-user-decision + domain:spec(HookContextSchema)+ type Feature。人工地板命中(公开契约面新增声明键)⇒ 恒交维护者,⛔ 分诊不代裁。

⚠️ 鲜度门:裁决时请读评论区的更正,⛔ 不要读正文那张表

立卡人自己发了更正:正文「Measured on 17.1.0」那张表是测试台产物,五行里三行错;正文里那句 "the two writes differ in shape only because the engine happens to omit updated_by" 结论是反的。⇒ 任何按正文那张表做的设计都是按坏读数做的。

更正后的事实(本席采信,理由:它变的是一个被固定住而没被意识到是变量的输入 —— 引擎把 cleanup 写构造成 {...callerContext, transaction, __referentialFieldClear: true},继承调用方身份;原测量恰好是在不带 userId 的 DELETE 上取的):

在真实请求走的那条路上(REST DELETE 携带 userId),ctx.user / ctx.session / ctx.input 在引擎 cascade 与用户手动清空之间完全相同。

⇒ 更正让这张卡更有必要,不是更没必要。 app 侧今天没有任何可用的判别器,除了那个 operation-private 的 __referentialFieldClear。

四棱分析

棱	读数
实际业务需求	⭐ 拉动实测且带用户可见后果:deleteBehavior:'set_null' 的清理写抵达持有方 beforeUpdate 时与普通用户编辑无法区分 ⇒ 任何冻结已结算记录的 app 守卫都会拒绝它 ⇒ 一条被冻结的记录能让它引用的那个人永远无法删除 —— 卡点名这是「一次 GDPR 抹除,而没有办法执行」。HotCRM 在 crm_lead / crm_opportunity / crm_quote 三处守卫上都撞到。⭐ 且已量化:三份逐字复制的形状谓词 + 一个断言三份保持字节相同的漂移 pin + 一个 REFERENCE_FIELDS 完整性 pin,全都只为绕过这个缺口而存在。
项目长远合理性	⭐ 支持声明。引擎已经知道这个区别(cascadeDeleteRelations 构造 __referentialFieldClear: true),缺的只是把它声明出来。这正是 contract-first:一个平台已经掌握的事实,要么声明给消费者,要么消费者只能去嗅探。⚠️ 而 __ 前缀是本平台自己的「不属于契约」约定(buildSession 按固定白名单逐字段构造 ctx.session,任何 __ 键都不在其中)⇒ 平台一边生产这个信号,一边用自己的约定宣告它不可依赖。
防 AI 写错	⭐⭐ 本棱最强。当前状态强迫 app 在两个坏选项间选:(a) 读一个平台约定说「不是契约」的 __ 键 —— 未声明依赖,可以在一次补丁发布里消失而不算破坏;(b) 接受一个无法区分两种写入的谓词,于是对任何清空已结算记录上声明链接的调用方都让行(即守卫失效)。⭐⭐ 而更狠的一条卡也测了:跨 sandbox 边界的可达性未经证明 —— buildSandboxApi 只在 engineCtx.api 暴露 object() 时传它,否则给一个不带 executionContext 的 shim。⇒ 在 kernel 测试台里绿、在生产里静默为假,这是一个守卫能有的最坏结局,与 ctx.dispatch?.mode === 'per-row'(#11552)同族,该 app 已经为那一次付过账。
创业阶段不扩散需求	⚖️ 本棱不强烈反对。这不是新能力,是把一个已存在的内部事实提升为声明 —— 一个布尔键,零新机制、零新运行时。⚠️ 唯一的扩散风险是它进入公开契约后就要长期维护(每条引用清理写都必须填,漏填即静默回到今天的状态)⇒ 若采纳,populate 面必须有 pin,⛔ 不能只加 schema 键。

推荐:采纳(声明 ctx.referentialFieldClear),四棱同向偏采纳。

⚠️ 但恒交维护者 —— 人工地板(公开契约面扩大)是排除项不是权重,四棱同向不构成代裁资格。且落地时走条款②契约复审档位(改的是已发布契约面)。

若采纳,两个必须同批的条件(⛔ 缺一即回到今天的形状,只是多了一个看起来能用的键):

1. 跨 sandbox 边界按契约传递 —— 这是 __referentialFieldClear 在 app 侧再小心也拿不到的那一半,也是本卡的全部要点;
2. populate 面的 pin —— 断言每一条引用清理写都带上它,⛔ 不是只 pin schema 里有这个键。

---

Generated by Claude Code

[huangyiirene]

⚖️ 裁决记录 — 采纳:在 HookContextSchema 上声明一等公民 ctx.referentialFieldClear

出处:维护者 2026-08-31,live PM chat,总监席第 7 场决裁批 #18,逐字:「其他同意」(本卡呈报推荐为采纳 + 两个必做件)。录裁:director seat, session session_01KGtaLpkW1mycWgkbSb3H6t。

裁定内容

1. 采纳:ctx.referentialFieldClear(boolean)声明进 packages/spec 的 HookContextSchema,由引擎在每一条引用清理写(deleteBehavior: 'set_null' 的 cascade)上填充。
2. 必做件一 — 跨 sandbox 边界按契约传递:声明键必须经 buildSandboxApi 路径可达 QuickJS 内的 hook 体,以钉断言,⛔ 不是「kernel 测试台里读得到」—— 这正是 __referentialFieldClear 在 app 侧再小心也拿不到的那一半([hooks] ADR-0058 Addendum II D3 names three routes out of the batch-scoped payload, and a body-only hook can reach none of them — the sandbox context carries no per-row signal (declared ≠ observable) #11552 同族教训),也是本卡的全部要点。
3. 必做件二 — populate 面 pin:断言每一条引用清理写都携带它;⛔ 只加 schema 键不 pin populate 面 = 只是多了一个看起来能用的键,漏填即静默回到今天。
4. 鲜度门记录:裁决所依事实以评论区立卡人更正为准(正文测量表是测试台产物 —— cleanup 写继承调用方身份,真实 REST 路径上两种写入完全同形,app 侧无任何可用判别器)。该更正让本卡更必要:四棱同向采纳。
5. 落地为已发布契约面扩大 ⇒ 条款② yes,PR 停放走契约复审档。

状态转移(同笔)

needs-user-decision → pm:queue(domain:spec)。

---

Generated by Claude Code