docs(adr): ADR-0104 附录修订 —— D2 在 17.0 默认严格；D1 保持按部署并接入升级路径 - #4199
Merged
Conversation
… 17.0, not 18.0 (#3438) Maintainer review of the 2026-07-30 addendum surfaced the amortisation argument the first draft missed: every 16.x deployment performs one planned, tested 16→17 upgrade anyway, and spreading this ADR's breaks across two majors charges that ceremony twice. The revision asks, per half, what withholding the version-wide flip actually protects: - D2 action params: nothing — no records at stake, rejections are loud 400s to the party who can fix them, R3's dangerous half is already closed by ACTION_PARAM_BUILTIN_KEYS, and v17 itself ships harsher zero-window flips (allowExport, undeclared-handler refusal). So strict becomes the 17.0 default; OS_ACTION_PARAMS_STRICT_ENABLED (RC-only, never on latest) is deleted before GA rather than shipped as a redundant knob; OS_ALLOW_LAX_ACTION_PARAMS is the single escape hatch. - D1 references + structured JSON: records — the read-modify-write hazard over data written years ago, one slice of it authored faithfully against the spec's own wrong LocationCoordinatesSchema. The per-deployment scan gate stays, and gains upgrade-path advertisement (os migrate meta epilogue + boot-log line) so clean deployments get 'one upgrade, done' by default. The earlier draft's 'no warn window served yet' framing is corrected in place: it bounds which gates are available, it does not argue for postponement. Design doc only — releases nothing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016zgA8CQMJeJbFEjnbib1Uv
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/m
documentation
…s, not edits The Check Changeset gate diffs with --diff-filter=A against the base, so revising the previous PR's still-pending changeset counts as zero. The empty-frontmatter file is the sanctioned 'releases nothing' declaration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016zgA8CQMJeJbFEjnbib1Uv
os-zhuang
marked this pull request as ready for review
July 30, 2026 15:21
This was referenced Jul 30, 2026
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.
按维护者对 #4188 的评审意见修订 2026-07-30 附录（#3438）
评审提出的摊销论证成立（「反正要从 16.0 升级，一次到位」），首稿漏掉了它。修订版把问题按半边分别问一遍——扣住版本级翻转到底保护了什么——两边答案不同：
D2 动作参数：改为 17.0 默认严格（首稿定在 18.0，已纠正）
扣住翻转什么都保护不了：没有数据处于风险中；拒绝是响亮的 400，点名违规参数，落在能修它的人（开发者/AI）手上；R3 里真正危险的那一半（dispatch 自己注入的
recordId/objectName被误判为未知键）已被ACTION_PARAM_BUILTIN_KEYSallowlist 关闭；而且 v17 自己就装着更狠的零窗口翻转（allowExport未设置→拒绝、未声明 handler 直接 404 且无任何开关）。对比之下把更温和的 D2 单独推迟一个大版本，不是谨慎，是不一致。顺带白赚一个简化：
OS_ACTION_PARAMS_STRICT_ENABLED只存在于 17.0 RC 窗口内、从未上过latest——17.0 翻转意味着这个变量在进 GA 之前直接删除，不留赘余开关、不背弃用债、不需要readEnvWithDeprecation。推到 18.0 反而要先把它稳定发布再兼容一版。唯一开关变成逃生阀OS_ALLOW_LAX_ACTION_PARAMS。D1 引用 + 结构化 JSON：保持按部署门禁（维护者已确认）
这边扣住版本级翻转保护的是记录，不是调用方：失败形态是 read-modify-write——应用读记录、改一个字段、整条写回，多年前写入的畸形
location跟着回写，应用自己正确的代码开始失败，且不给扫描器连「哪几行」都无法枚举。其中一部分脏数据是我们自己的责任：spec 曾导出声明{latitude, longitude}的LocationCoordinatesSchema而实际存储是{lat, lng}——照我们文档写的 app，数据正好是版本级翻转要拒绝的形状。同时把「一次到位」做成干净部署的默认体验：
os migrate meta --from 16（16→17 本来就要跑）结尾列出两个数据迁移及其门禁状态；≥17 启动时若有覆盖字段且无标记，boot 日志打一行说明 warn 模式生效及结束它的命令。数据干净的部署跑完扫描当场 strict——与版本级翻转不可区分。其余不变
扫描门禁设计、新库创建时记账、
OS_ALLOW_LAX_VALUE_SHAPES优先级、sys_migration复用——均保持 #4188 合并版原样。首稿「warn 窗口一天没服完」的论证在文中原地更正：它只约束哪些门禁可用，不构成推迟的理由。changeset（仍 pending、未被版本消费）文案同步更新。
🤖 Generated with Claude Code
https://claude.ai/code/session_016zgA8CQMJeJbFEjnbib1Uv
Generated by Claude Code