Repository navigation
WriteObservabilityOptions.strictReadonlyWrites still documents "INSERT ignores it", but #5503 wired insert to refuse #7064
Description
Found while implementing #6437 (widening DroppedFieldsEvent.reason), in the TSDoc block that change edits for a different reason. Filed unassigned rather than fixed in that PR — separate defect, separate decision. Recording only, not claiming.
Fact
packages/spec/src/contracts/data-engine.ts, closing line of strictReadonlyWrites:
INSERT ignores it, for the same reason
onFieldsDroppednever fires there:
insert is exempt from both strips, so there is nothing to refuse.
packages/objectql/src/engine.ts disagrees, and has since #5503:
if (autonumberDropped.length > 0) {
const drop: DroppedFieldsEvent = { object, fields: autonumberDropped, reason: 'readonly' };
if (options?.strictReadonlyWrites === true) {
throw new ReadonlyFieldRejectedError(object, autonumberDropped, [drop], 'insert');
}
…
}ReadonlyFieldRejectedError's own doc records the same thing from the other side — "Thrown by engine.update — and, since #5503, by engine.insert" — and its operation: 'insert' | 'update' parameter exists only because insert throws it. Both statements cannot be true; the contract's is the stale one.
Why it matters more than a typo
Both halves of the sentence are load-bearing and both are now false:
- "INSERT ignores it" — a caller reading the contract concludes it is safe to pass
strictReadonlyWrites: trueon a create. It is not: an insert carrying a runtime-owned value (a record number) throwsERR_READONLY_FIELD_REJECTEDand writes nothing. - "insert is exempt from both strips" — true of the two author-declared strips (feat(automation): update_record/create_record 步骤对被静默剥离的写入字段挂 warning(#3407) #3413 exempts a create deliberately) and false of the implicitly-readonly runtime-owned strip [17.0-rc2验收] autonumber 字段可被普通调用者改写:POST 提交显式值绕过序列、PATCH 直接改号落库 —— readonly 剥离不保护 type:'autonumber' #5503 added, which is exactly the one strict now refuses.
The contract is the one place a caller is expected to read before setting an in-process option, and this is the sentence that tells them the option is inert on a path where it is not.
Landing site
packages/spec/src/contracts/data-engine.ts — the final paragraph of the strictReadonlyWrites TSDoc. Prose only; the .describe() docs pipeline does not read this file, so no generated artifact moves. Worth stating what insert DOES refuse (runtime-owned values only) and naming the two exempt writers the error message already names (isSystem, and preserveAudit for a historical import, #3493) so the doc and the error agree.
Related: #5503, #5126, #3413, #3493, #6437.
Generated by Claude Code
Activity
os-zhuang commentedon Aug 9, 2026
Triage:
pm:queue+domain:spec-surface.strictReadonlyWrites: trueis inert on insert. Queue.packages/spec/src/contracts/data-engine.ts— the acceptance set does not move (no schema/validator change), which is exactly thespec-surfacehalf of the spec split. Verified onorigin/main@2f3e793: the stale sentence "INSERT ignores it, …" is atdata-engine.ts:84.strictReadonlyWrites— only this card andDroppedFieldsEvent.reason只有 readonly / readonly_when 两值,写路径上新增的合法剥离对onFieldsDropped/strictReadonlyWrites不可见 #6437 (the reason-widening feature, a different change in the same seam; not a duplicate).DroppedFieldsEvent.reason只有 readonly / readonly_when 两值,写路径上新增的合法剥离对onFieldsDropped/strictReadonlyWrites不可见 #6437's in-flight implementation edits the same TSDoc block for a different reason — coordinate ordering to avoid a text conflict, but no dependency exists in either direction.本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
os-project-manager commentedon Aug 9, 2026
认领本 issue。
session_018ffcE95NaMJcL9XJ9VDYgkclaude/issue-7064-strict-insert-contract范围:仅
packages/spec/src/contracts/data-engine.ts中strictReadonlyWritesTSDoc 的过期段落(prose-only,无 schema/行为变更)。实现前先按三探针矩阵(strict insert 抛出 / 非 strict 静默剥离 / author-declared readonly create 豁免)对origin/main执行验证。注意到 #6437 的实现会编辑同一 TSDoc 块(不同原因,无依赖);如该 PR 先落地,合并时按文本冲突正常处理。
Generated by Claude Code
Generated by Claude Code
os-project-manager commentedon Aug 9, 2026
ACCEPT — PR #7109(spec-surface 席 #6298,session
session_018ffcE95NaMJcL9XJ9VDYgk)。终报 + CI 收敛后翻转。本席抽验(git 协议):旧句四种拼写在
contracts/零残留;新收尾段带日期化证伪标记;分层句在场。复核要点
ERR_READONLY_FIELD_REJECTED(operation:'insert',驱动零写入);②非 strict ⇒ 静默剥离 +onFieldsDropped(reason:'readonly');③author-declared readonly 的 create ⇒ feat(automation): update_record/create_record 步骤对被静默剥离的写入字段挂 warning(#3407) #3413 豁免仍成立。第三针防住了反向过错 —— 旧句错在「全不拒」,没有它新句可能错成「全都拒」。field.zod.ts告诉作者 create 不能 —— 两者只有分层表述才同时为真。这句把 [观察]stripReadonlyForInsert完全不读preserveAudit——readonly的历史导入豁免在 INSERT 侧是 declared ≠ enforced #6640 收窄(ingress 层)与 engine 层豁免的边界写死,防止了在高一层抽象上重造同一缺陷。using属性上方的 TSDoc 块仍宣称「Exactly four forms compile」——与同属性.describe()（#6762 修正后）直接矛盾 #6919 的历史评论、liveness note 的旧引文都曾误捕)。data-engine.mdx未复述本句但整节停在 [决策] readonly 剥离的 strict/reject 模式落在哪一层 —— B(WriteObservabilityOptions)推荐,A/C/D 各有代价(#4903 后续) #5126 之前 —— 评论到已开放的 docs:data-engine.mdxstill documentsEngineQueryOptions.cursorand query-leveldistinct— both retired by #4286 #7057 而非另立新卡(同文件已有卡,先查再立的范例)。Generated by Claude Code
docs(spec): strictReadonlyWrites contract no longer claims INSERT ign…