fix(objectql): a preserveAudit by-id update no longer hands the primary key to the driver

[os-zhuang]

Fixes#8215

What

isPreservableUnderAudit (packages/objectql/src/validation/rule-validator.ts) now excludes the row's own primary key before consulting the preserveAudit whitelist:

• Before: a platform object's id is readonly: true with no system flag (sys_user_preference: Field.text({ label: 'Preference ID', required: true, readonly: true })), so the second limb (def.system !== true) read it as an author-declared business field like closed_at. On a preserveAudit by-id update the strip KEPT id, and the driver received SET id = 'rec_1' WHERE id = 'rec_1' — a no-op on SQL, an outright rejection on stores with immutable primary keys. The REST ingress folds the path id into every update body (REST PATCH /data/:object/:id:请求体里的标量 id 压过路径 :id,存在性探测/OCC 判在一行、写落在另一行、响应报第三个说法 #6479), so a bulk historical import hit this without ever sending an id itself.
• After: the predicate returns false for SystemFieldName.ID before either limb. The primary key is the ADDRESS of the write, not a fact a historical import restores (data import: a "historical" import can't preserve original timestamps / audit fields — updated_at is stamped now, readonly fields stripped on upsert (#3479 follow-up) #3493 scoped the flag to "reinstate the original timeline"), and the strip protects that one column for a store-portability reason, not an authorship one.

Keyed on SystemFieldName.ID (@objectstack/spec/system) — the registry's sanctioned "canonical spelling of the column that plays role X" use — because there is no per-field primaryKey marker in the spec for a def-based test to read: the driver provisions id as the primary key on every physical table, unconditionally (resolveInjectedSystemColumns reports it even under systemFields: false), and the engine's whole by-id addressing (idAddressesThisRow, addressKey: 'id') reads that name. The primaryKey: true spellings in test fixtures are inert runtime decoration (register-object-authored-shape.pin.ts pins that the key is not a spec Field key).

Both directions pinned

• stripReadonlyFields: a readonly id is stripped even under preserveAudit, with and without addressKey (and with addressKey: 'id' the address stays out of the LOG as well as the payload — The read-only strip still logs a WARN calling the addressed row's own id a forged caller write, on every single-record update of a platform object #8141 composes).
• The flag keeps doing its actual job: the audit/timestamp family (created_* / updated_*) and author-declared business readonly fields (closed_at) still ride through beside the stripped id, and organization_id stays stripped and loud (no tenancy backdoor).
• stripRuntimeOwnedFields (shared predicate, insert side): an autonumber primary key seeded under a preserveAudit insert is now stripped; the business autonumber identifier (account_number) remains preservable — [17.0-rc2验收] autonumber 字段可被普通调用者改写:POST 提交显式值绕过序列、PATCH 直接改号落库 —— readonly 剥离不保护 type:'autonumber' #5503's actual case.
• The warn line no longer offers { context: { preserveAudit: true } } for a stripped id — post-fix the flag would not keep it, so offering it would be the readonlyStripWarning promises a commit that strict mode refuses, and omits the preserveAudit remedy its own strip implements #8214 false-remedy shape. preserveAuditApplies derives from the same predicate, so the remedy text moved with the verdict, by construction.

The pin this card exists to turn red

The #8216 pin ("composes with preserveAudit rather than overriding it") captured pre-fix behaviour as observed, deliberately. Rewritten as "composes with preserveAudit — and the primary key is stripped even under the flag (#8215)", pointed at #8215 rather than #6435, and its load-bearing facts are asserted as literals (toHaveLength, toContain on field-name substrings, a literal out object) rather than derived from the composer, so a reworded message cannot keep both sides green.

Doc clause (cross-seat: content/docs/**, domain:devx#6023 — declared on the card by the PM)

content/docs/protocol/objectql/state-machine.mdx:113 already described the narrower whitelist ("author-declared businessreadonly fields"); one clause is added so the prose stays the correct half instead of inverting into the loose half: "— but never the record's own primary key (id), which is the address of the write rather than a fact being restored (#8215)."

Blast radius, measured

• @objectstack/objectql: full suite 196 files / 3454 tests green; tsc --noEmit green.
• @objectstack/rest (read and run, not edited — domain:cli[PM seat] domain:cli — 🟢 os-zhuang #6024's package): full suite 109 files / 1809 tests green; the three named surfaces re-run verbose: import-runner-historical.test.ts (data import: mid-lifecycle rows rejected by state_machine.initialStates — historical-data migration blocked (#3433 sibling) #3479/data import: a "historical" import can't preserve original timestamps / audit fields — updated_at is stamped now, readonly fields stripped on upsert (#3479 follow-up) #3493), import-runner-historical-readonly-insert.test.ts ([观察] stripReadonlyForInsert 完全不读 preserveAudit —— readonly 的历史导入豁免在 INSERT 侧是 declared ≠ enforced #6640), import-job-integration.test.ts — 20/20 green. Their fixtures either declare id without readonly (the strip never examines it) or exercise closed_at.
• @objectstack/metadata-protocol (owns the REST PATCH /data/:object/:id:请求体里的标量 id 压过路径 :id,存在性探测/OCC 判在一行、写落在另一行、响应报第三个说法 #6479 fold and the [观察] stripReadonlyForInsert 完全不读 preserveAudit —— readonly 的历史导入豁免在 INSERT 侧是 declared ≠ enforced #6640 insert-ingress warn): full suite 77 files / 1117 tests green.
• @objectstack/runtime: preserve-audit-real-driver.integration.test.ts (real SQLite end-to-end) 3/3 green, re-run against the restored fix.
• Insert-side ingress (stripReadonlyForInsert, 安全/设计:静态 readonly 的 INSERT 豁免让审批/状态字段可在创建时被直接播种(比 #3003 少一步) #3043) is untouched: preserveAudit static-readonly relaxation is update-only ([观察] stripReadonlyForInsert 完全不读 preserveAudit —— readonly 的历史导入豁免在 INSERT 侧是 declared ≠ enforced #6640), and the ingress warn lists stripped fields without re-deriving this predicate — no drift copy exists.
• Reverse verification (direction decided in advance: red, exactly the 5 new/updated cases): fix committed first, rule-validator.ts restored to origin/main under the new tests — measured 5 failed / 163 passed, the five being exactly the A preserveAudit by-id update hands the primary key to the driver: isPreservableUnderAudit reinstates a platform object's own id #8215 cases; the fix was then restored from the commit and proven byte-identical (git hash-object equals the HEAD blob).

Out of ruled scope, unchanged

• The read-only strip still logs a WARN calling the addressed row's own id a forged caller write, on every single-record update of a platform object #8141's byte-identical payload-to-driver invariant holds for every non-preserveAudit path; the address-silence rule is unchanged.
• An object whose id is NOT readonly still carries id into the SET clause — removing it there is update 的 **by-id** 路径同样把非标量 data.id 交给驱动写主键列(#6262 的孪生形状,where.id 胜出时) #6435's explicitly separate decision.
• update 的 **by-id** 路径同样把非标量 data.id 交给驱动写主键列(#6262 的孪生形状,where.id 胜出时) #6435's truthy-scalar data.id dispatch rules are untouched.

Changeset: patch for @objectstack/objectql (behaviour fix on a documented flag; nothing authorable removed, so no ADR-0087 entry — the changeset is not declared-breaking).

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 13, 2026 5:08am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

15 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx(via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx(via @objectstack/objectql)
• content/docs/deployment/vercel.mdx(via @objectstack/objectql)
• content/docs/kernel/contracts/data-engine.mdx(via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx(via packages/objectql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/objectql)
• content/docs/kernel/services.mdx(via @objectstack/objectql)
• content/docs/permissions/authentication.mdx(via @objectstack/objectql)
• content/docs/permissions/system-context.mdx(via packages/objectql)
• content/docs/plugins/index.mdx(via @objectstack/objectql)
• content/docs/plugins/packages.mdx(via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx(via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx(via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx(via @objectstack/objectql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.