feat(spec)!: retire BatchOptions.validateOnly — a dry-run flag never implemented (#4052) - #4057
Merged
Merged
Conversation
…implemented (#4052) `BatchOptions.validateOnly` promised a dry-run ("validate records without persisting changes") but no batch surface ever read it — updateManyData / deleteManyData / batchData all persist regardless. A caller sending `options.validateOnly: true` to PREVIEW a mutation got it executed: a declared flag lying about a data-safety guarantee, the dangerous direction of "declared ≠ enforced" (PD #10). Retired rather than half-implemented — a real no-commit batch has its own design space (cascade / constraint semantics under rollback, a per-row would-succeed response contract) and should be reintroduced deliberately, not back-filled to match a promise nothing kept. - Tombstone `validateOnly` with `retiredKey()` in BatchOptionsSchema so writing it fails with the prescription instead of being silently stripped (ADR-0104 / #3733). The BatchOptions type's key becomes `never`. - HTTP-only (never stored in stack metadata), so recorded as a semantic migration on the protocol-18 chain step (`batch-options-validate-only-retired`) — a TODO for API callers, not a stack conversion. - Regenerated authorable-surface, references docs; major changeset. Also fixes a dangling doc reference: the /createMany route named `requestSchema: 'CreateManyRequestSchema'`, a schema no module ever exported — pointed at the real `CreateManyDataRequestSchema`. Closes #4052. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TzLE9cw4gZKNyPN2ZP4iTt
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 105 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…#4052) The docs-drift-check flagged four hand-written references that still presented `validateOnly` as a working dry-run option — a `data-api` / `wire-format` batch example, a `client-sdk` example, and the client-sdk Batch Options table row ("Dry-run mode — validate without persisting"). The key is retired and now 400s, so these advertised a feature that no longer exists. Removed the key from the three examples (fixing JSON trailing commas) and deleted the table row. The generated references already carry the [REMOVED] prescription. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TzLE9cw4gZKNyPN2ZP4iTt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4052。承 #3963 一线的"声明 ≠ 强制"(PD #10)清扫,收两处批量 API 的悬空契约。
主项:退役
BatchOptions.validateOnlyvalidateOnly声明了 dry-run —— "validate records without persisting changes" —— 但运行时没有任何一处读它。updateManyData/deleteManyData/batchData全部无条件落库。一个调用者发options.validateOnly: true想预演一次改动,实际会被执行。对比同组三个兄弟(都真实生效),唯独它悬空:
atomicprotocol.ts:3482+rest-server.ts:6607returnRecordsprotocol.ts:3501continueOnErrorprotocol.ts:3486,3610validateOnly这是 PD #10 里危害最高的一类:不是能力缺失,而是契约主动误导数据安全。选择退役而非仓促实现 —— 真正的 no-commit 批量有独立设计空间(rollback 下的 cascade/约束语义、逐行 would-succeed 的响应契约),应在有真实需求时单独立项做对。
破坏性变更
BatchOptionsSchema里validateOnly→retiredKey()墓碑:写它 → 解析报错并给出处方,而非静默剥除(ADR-0104 / ComputedFieldCacheSchema 是 2026-06 字段剪除留下的第二个孤儿(#3726 表格误记为「已清理」) #3733)。BatchOptions类型该键变为never。batch-options-validate-only-retired)—— 与analytics-query-request-format-retired同型:声明但从未实现、无存储可改写,是给 API 调用者的 semantic TODO 而非 stack conversion。authorable-surface.json([RETIRED] 标记)、content/docs/references/api/{batch,protocol}.mdx;major changeset(仅@objectstack/spec,随同一未发布的 major 18)。顺带:#2 悬空文档引用
plugin-rest-api.zod.ts:918的/createMany路由声明requestSchema: 'CreateManyRequestSchema'—— 从未有 schema 导出此名(真实契约是protocol.zod.ts的CreateManyDataRequestSchema)。该字符串运行时和 OpenAPI 生成都不消费,是文档字符串失真。改指向真实存在的CreateManyDataRequestSchema。迁移
停止在
/batch、/updateMany、/deleteMany上发送options.validateOnly。它从不预演任何东西,删掉不改变任何行为。若确需"校验不落库",跟进 #4052 单独设计一个真正的 no-commit 预览。测试
packages/spec全绿:266 文件 / 6937 测试通过(含batch.test.ts新增的"退役键被拒并给出处方"断言、migrations链重放、conversions)。check:authorable-surface/check:api-surface(surface 无变化)/check:spec-changes(major 18 未发布,不投影,与 feat(auth)!: retire the api.requireAuth opt-out — anonymous data access is always denied (#3963 step 2) #4043 一致)/check:upgrade-guide/check:docs/check:skill-docs/check:skill-refs。validateOnly仅出现在batch.zod.ts与batch.test.ts,类型变never不影响任何构造点。审阅指引
packages/spec/src/api/batch.zod.ts(retiredKey 墓碑)。packages/spec/src/migrations/registry.ts的step18.semantic[]。packages/spec/src/api/plugin-rest-api.zod.ts:918。🤖 Generated with Claude Code
https://claude.ai/code/session_01TzLE9cw4gZKNyPN2ZP4iTt
Generated by Claude Code