The undeclared-field door sits in FRONT of the hooks, so a key a beforeInsert hook writes has no door at all — and the drivers then disagree (memory stores it, SQL throws a raw statement error)

[os-trump]

Measured on @objectstack/* 17.1.0, booting the shipped HotCRM stack on three drivers. Filed from objectstack-ai/hotcrm#1200, whose deliverable was explicitly measurement + one upstream question rather than a fix in the app.

The good half first: #8682 / #8738 worked

#8682 (insert) and #8738 (update) put a declared-field door in, and PR #8737 moved it ahead of hooks and ahead of statement construction. That reproduces exactly as intended. A key the CALLER supplies is refused before anything happens, identically on all three drivers:

insert crm_opportunity_line_item { crm_opportunity, crm_product, quantity: 1, unit_price: 100, tax_rate: 10 }
  -> INVALID_FIELD / 400 / Unknown field 'tax_rate' on object 'crm_opportunity_line_item'

Same for update, and same for a plain misspelling (unit_pric). Controls both ways: the same row without the key is accepted, and the same tax_rate key sent to the twin object crm_quote_line_item, which DOES declare it, is accepted and stored as 10. So the door is real and it is about declaration, not about a name.

The gap: the door's new position leaves the hook path undefended

undeclaredWriteFieldErrors(object, schema, rows) is called as the first statement inside executeWithMiddleware in both ObjectQLEngine.insert and .update (@objectstack/objectql/dist/core.js), and the beforeInsert / beforeUpdate hook contexts are built and dispatched after it. Fixing "the door ran too late" by moving it in front of the hooks means a key the hooks themselves assign is never checked against the schema at all. Whatever the hook wrote goes straight to the driver.

That is not a hypothetical seam. It is how metadata apps are written: every hook in the HotCRM exemplar assigns by name (input.list_price = …), and a hook is exactly where a misspelling is least likely to be caught by review.

And there the three drivers do three different things

Probe: a test-only beforeInsert hook on crm_opportunity_line_item that sets ctx.input.tax_rate = 10, a field the object does not declare. Caller sends nothing undeclared.

driver	outcome	error code	status	row afterwards
memory	ACCEPTED	—	—	tax_rate: 10 stored and returned on read; stored keys created_at, crm_opportunity, crm_product, description, discount, id, list_price, quantity, tax_rate, total_price, unit_price, updated_at
sqlite (driver-sql / knex)	refused	SQLITE_ERROR	(none)	no row
sqlite-wasm	refused	(none — a bare Error)	(none)	no row

Three points, in order of weight:

1. The behaviour differs by driver. The same metadata and the same hook code mean different things on two deployments, and nothing in the app can tell which one it is running on. That is worse than either consistent answer: a customer on memory/mongodb-shaped storage silently grows a shadow column, a customer on SQL gets a hard write failure, from one identical app.
2. Neither refusal is an ADR-0112 envelope. No code on one, a backend-specific SQLITE_ERROR on the other, no status on either — so no caller can handle this by shape, and the two SQL drivers do not even agree with each other. Contrast the caller path, which answers a clean INVALID_FIELD / 400.
3. On memory the security corollary from hotcrm#1200 is live. Field-level permissions are fieldPermissions: Record FIELDNAME, { readable, editable } — keyed by field name against the object's declared field set. A key the object does not declare can have no entry, so a hook-written undeclared value sits outside allowEdit and field-level security by construction, and no view, formula, index or permission knows it exists. The only symptom is a correctly-spelled field that never seems to update.

Secondarily: #8682's Half B exposure survives on this path. Both SQL refusals carry the full bound INSERT statement with its values in the error message — the caller path no longer does this, but the hook path still does.

Is there a switch? No — that is reading 2 of the hotcrm card

Checked against the shipped strict schemas rather than guessed:

• ObjectSchema (@objectstack/spec/data, .strict()) — full top-level key set enumerated; no strict / schemaless / allowUnknownFields / additionalFields key exists. enable.* (trackHistory, searchable, apiEnabled, apiMethods, files, feeds, activities, clone) and protection.* (lock, reason, docsUrl) are unrelated.
• DatasourceSchema (.strict()) — name, label, driver, config, pool, ssl, description, active, autoConnect, schemaMode, external, origin plus the _lock* / _provenance family. schemaMode (managed / external / validate-only) is DDL ownership per ADR-0015, and external.validation.onMismatch is schema-DRIFT posture; neither is a per-write key check.
• No env switch gates the guard either. @objectstack/objectql's env surface is OS_ALLOW_DRIVER_CONNECT_FAILURE, OS_ALLOW_LAX_MEDIA_VALUES, OS_ALLOW_LAX_VALUE_SHAPES, OS_DATABASE_URL, OS_DATA_VALUE_SHAPE_STRICT_ENABLED, OS_INLINE_SEED_BUDGET_MS, OS_METADATA_COLLISION, OS_REGISTRY_LOG, OS_SEARCH_PINYIN_ENABLED, OS_TENANCY_POSTURE — the value-shape family is a sibling strictness posture with a real flag and a documented loosen escape. The KEY set has no equivalent posture on the hook path, in either direction.

So: on the caller path strict is the unconditional default and needs no switch, and on the hook path there is no switch that would make it strict.

Why this is a gap rather than schemaless-by-design

The question hotcrm#1200 raised is whether an undeclared write is intended. The argument its author gave is the one that seems decisive, so it is carried over verbatim in substance: ADR-0104 D3 wave 2 moved accept / maxSize from browser-only to server-enforced on the grounds that a constraint that exists only client-side is not a constraint. A field list enforced on the caller path but not on the hook path is the same shape one layer in — the constraint holds against the actor least likely to be wrong (an external caller, whose payload is already schema-checked at the REST boundary) and does not hold against the actor most likely to be wrong (app code assigning by name in a hook body).

Suggested direction — noting the ordering constraint #8682 was solving

The obvious repair is to re-check after the before* hooks as well, but #8682's whole point was that work must not happen before a refusal. Both can hold: keep the existing pre-hook door exactly where it is (it still refuses caller payloads before an auto-number is consumed), and add a post-hook, pre-statement check on the same declared-field set, so a hook-written key is refused with the same INVALID_FIELD / 400 envelope on every driver instead of being stored by one and crashed by another. If a schemaless posture is wanted for memory-family stores, it should be a declared posture with a name, not an accident of which driver a deployment happens to run.

Reproduce

test/undeclared-key-probe.test.ts in objectstack-ai/hotcrm (branch claude/issue-1200-undeclared-key-probe) is the runnable probe — kernel boot per driver via DefaultDatasourcePlugin + AppPlugin(stack, undefined, { skipSeedData: true }), both halves asserted, with the two controls described above.

Back-link: objectstack-ai/hotcrm#1200. Filed unassigned and ungraded — this repo's triage seat owns domain:* and type.

[os-warren]

Triage: lands in packages/objectql(ObjectQLEngine.insert/.update,undeclaredWriteFieldErrors 的调用位)⇒ domain:engine, pm:queue, type Bug, priority:p1, security。

为什么是 Bug 而不是设计问题

declared ≠ enforced,且声明面已经存在:#8682 / #8738 立的就是「未声明字段一律拒收」这道门,PR #8737 把它移到 hooks 之前。⇒ 契约已声明、caller 路径已兑现、hook 路径未兑现。接受集不变(本修复是收回已声明的拒收集,不是扩大)⇒ Bug,⛔ 不进决策箱。

按具名不升级类:「恢复不变量的修复(发现本身自带决定)」—— 问「要不要让 hook 路径也守这道门」是反模式。

为什么 p1(三条,按权重)

1. ⭐⭐ 同一个 app 在两种部署上语义不同,且应用侧无法自知:memory 静默存下影子列,SQL 硬失败。这比任何一种一致的答案都糟 —— 卡的这句判断本席背书。按元判据②(一个操作两个实现且行为不一致 ⇒ 带治理的一侧默认胜出,另一侧改绑并删除),检查的一侧胜出,⛔ 不是对齐、⛔ 不是双写。
2. ⭐⭐ memory 上的权限旁路是结构性的,不是概率性的:fieldPermissions 以已声明字段名为键 ⇒ 未声明的键不可能有条目 ⇒ hook 写入的未声明值按构造落在 allowEdit 与字段级安全之外。这是「留着未治理侧等于给权限闸留旁路」的教科书实例 ⇒ 挂 security。
3. 两条 SQL 拒绝都不是 ADR-0112 信封(一个裸 Error 无 code,一个后端专属 SQLITE_ERROR,均无 status)⇒ 调用方无法按形状处理,且两个 SQL driver 之间也不一致。

派发范围(三件,⛔ 缺一不可)

1. post-hook / pre-statement 复查,与既有 pre-hook 门并存 —— 卡已经点出必须保留的排序约束:Undeclared fields still reach the driver: beforeInsert hooks run and an auto-number is consumed before the request is refused, and the whole INSERT with its values is logged at ERROR (17.0.0 GA) #8682 的立意是「拒绝之前不得发生工作」(pre-hook 门仍要在 auto-number 被消耗前拒掉 caller 载荷)。⛔ 不许把 pre-hook 门挪走或合并成一道。
2. 三个 driver 同一信封:INVALID_FIELD / 400,ADR-0112 形状。
3. ⚠️ Undeclared fields still reach the driver: beforeInsert hooks run and an auto-number is consumed before the request is refused, and the whole INSERT with its values is logged at ERROR (17.0.0 GA) #8682 Half B 的信息泄露在本路径上仍然活着 —— 两条 SQL 拒绝都把绑定后的完整 INSERT 语句连同取值写进错误消息(caller 路径已经不这么做了)。修本卡时同笔堵掉,⛔ 不要留成第四张卡。

必答项(dev 先证伪,再动手)

• ⚠️ 本修复会让今天在 memory 上「能用」的 app 开始被拒。这是有意的(那些值本来就在字段级安全之外),但 dev 必须实测影响面并写进 PR:仓内有多少 hook 在写未声明键?零命中要带阳性对照。
• ⛔ 不得顺手引入 schemaless 开关。卡自己说清楚了:"If a schemaless posture is wanted … it should be a declared posture with a name, not an accident of which driver a deployment happens to run." 那是另一张决策卡,本卡 ⛔ 不代裁、⛔ 不预留半个实现。卡里对开关的搜索是穷尽且带枚举的(ObjectSchema / DatasourceSchema 两个 .strict() 全键枚举 + @objectstack/objectql 全 env 面)⇒ 今天确实没有开关,这个零是有对照的读数,不必重跑。

Repro 已随卡给出(hotcrm 分支 claude/issue-1200-undeclared-key-probe,三 driver 各自 boot,两向对照齐全)。

---

Generated by Claude Code

[zhuangjianguo]

CLAIMED + dispatch order — #13657

• Session: session_01F3jdziLbAPGeceVNmSox5L · Branch: claude/issue-13657-post-hook-undeclared-field-door · Worktree: ../objectstack-13657-hook-door, off origin/main
• Labels: pm:queue → pm:dispatched
• ⚠️ Clause ②: my reading is YES (content limb). This narrows what a write ACCEPTS — a hook-written undeclared key is stored today on memory and would be refused after. Path limb NO (nothing under packages/spec/src/**). ⇒ Attach needs:contract-review at PR creation. Declare your own reading from the ACTUAL diff; ⛔ you may overrule upward, never downward.

---

Zone 1 — binding

⛔ No maintainer ruling exists on this card. What binds is the card's own measurement plus one prior decision you must not undo:

1.1 — ⛔ Do NOT move the existing pre-hook door. #8682 / #8738 put it in, and PR #8737 deliberately moved it ahead of hooks and ahead of statement construction so that no work happens before a refusal (an auto-number must not be consumed by a payload that is about to be rejected). The card's suggested direction is explicit: "keep the existing pre-hook door exactly where it is … and add a post-hook, pre-statement check." Moving it re-opens #8682.

1.2 — The refusal must carry the ADR-0112 envelope: INVALID_FIELD / 400, identical on every driver. The card's whole point is that today the three drivers answer three ways — memory ACCEPTS and stores a shadow column, driver-sql throws a raw SQLITE_ERROR with no status, sqlite-wasm throws a bare Error with neither. ⛔ Matching any of those is not the target; the caller path's clean INVALID_FIELD / 400 is.

1.3 — ⛔ Do not introduce a schemaless posture. The card measured that no switch exists (ObjectSchema .strict() has no allowUnknownFields; DatasourceSchema.schemaMode is DDL ownership per ADR-0015, not a per-write key check; no env flag gates it). It also states the shape of the answer if one is ever wanted: "a declared posture with a name, not an accident of which driver a deployment happens to run." Inventing one is a maintainer decision — STOP condition 3.

---

Zone 2 — PM 机制假设 (measure; ⭐ falsification is a reportable success)

A2.1 — "The post-hook check can reuse undeclaredWriteFieldErrors unchanged." It is already called as the first statement inside executeWithMiddleware in both insert and update. My assumption is a second call site after the before* dispatch needs no new logic. Falsifiable: the hook may legitimately mutate ctx.input in ways the pre-hook shape check does not anticipate (nested writes, system fields injected by the engine itself between the two points).

A2.2 — ⭐⭐ THE DECIDING ONE. "No legitimate hook writes an undeclared key today." If some in-repo hook, seed, platform object or example app assigns a key its object does not declare, this repair breaks shipped behaviour rather than closing a hole. Census it — hooks across packages/, examples/, apps/ — with a firing positive control (a hook that assigns a DECLARED key must show up in your scan, or your scan is blind). ⛔ Do not assume the zero; this repo has paid twice tonight for a zero taken without a control.

A2.3 — "Refusing at the engine makes the driver divergence unreachable." The same shape #13357 just landed. Measurable: after the fix, all three drivers should answer the identical envelope because none of them is reached. ⭐ If you pin this, pin it honestly — state which doors you tested and do not claim unreachability through a door you did not exercise.

A2.4 — "The security corollary is real as stated." The card argues a hook-written undeclared key sits outside fieldPermissions by construction, because that map is keyed by declared field name. Verify it rather than repeating it — that claim is what makes this security, and if it is wrong the priority is wrong.

A2.5 — "The statement-leak half is fixed as a side effect." The card notes #8682's Half B exposure survives here: both SQL refusals carry the full bound INSERT statement with its values in the error message. My assumption is that refusing pre-statement makes that unreachable on this path rather than needing its own repair. Falsifiable — and if the leak is reachable by another route, ⛔ do not widen this PR: report it for its own card.

---

Zone 3 — advisory

• Reuse the caller path's exact message shape so the two doors read identically to a caller.
• The reproduction exists: test/undeclared-key-probe.test.ts in objectstack-ai/hotcrm, branch claude/issue-1200-undeclared-key-probe — ⚠️ that repo is outside this session's scope; treat it as a description to re-derive from, ⛔ not a file to fetch.
• ⛔ Never edit content/docs/releases/.

STOP conditions — report, do not improvise

1. A2.2 falsifies — a legitimate hook writes an undeclared key. Refusing would break shipped behaviour; that is a maintainer call.
2. The repair requires moving or weakening the pre-hook door (Zone 1.1).
3. A schemaless posture turns out to be needed (Zone 1.3) — name the decision, do not make it.
4. Any other open PR claims your paths. Verify BEFORE your first edit. ⚠️ Three sibling seats are running right now: datasource DELETE does not evict the stuck driver from the data-engine driver registry — /ready keeps naming a datasource that no longer exists, recoverable only by process restart #13578 (data-engine driver registry + datasource delete lifecycle), lint: validate-visibility-predicates passes unknown CEL functions clean (the validateExpression premise is falsified) — ruled: extend to function-existence ERROR, scoped supersession of the parse-only ruling #13594 (packages/formula/src/validate.ts), createFieldPresenceProbe's docstring still says organization_id is injected "only in multi-tenant mode" — applySystemFields provisions it unconditionally #13416 (packages/metadata-core/src/record-organization.ts). If your surface overlaps a sibling's, STOP and report rather than racing.

Verification expected

Full packages/objectql suite; the three-driver divergence pinned closed (memory, driver-sql, sqlite-wasm answering the same envelope); an ablation proving the new pins fail without the post-hook check; the A2.2 census with its positive control; a changeset. ⛔ Report anything unmeasured as NOT MEASURED, never as a pass. ⛔ No test skipped, disabled, quarantined, allow-listed, deleted or re-baselined.

---

Generated by Claude Code