[finding][spec-tooling] ADR-0087 门的 `no-migration-prescription` 矛盾检查匹配的是占位符 `FROM`/`TO`,不是真实处方 —— 写得越好的处方越照不到

[os-zhuang]

check-adr-0087-registration.mjs（#6148 / PR #6342，今天合入）在 PR #6404 上拦下第一例，实测发现它的闭合词表对这一类变更没有任何一个诚实可用的格。四个标记逐个实测（都是在真的 commit 上跑 node scripts/check-adr-0087-registration.mjs，不是读代码推断）。

变更形状

PR #6404（#6212 批 B）：@objectstack/driver-sql / @objectstack/driver-turso 两个已发布包，major，删掉 query.aggregate 与 agg.func 两个宽容分支。这两个键从未是已声明表面：

• git log -S"aggregate: z." --all -- packages/spec/src/data/query.zod.ts → 零 commit；func: z. 同样零。即 QueryASTSchema / AggregationNodeSchema 历史上从未声明过它们。
• 没有 retiredKey() 墓碑，QuerySchema 上也没有 alias table 收录它们（该文件唯一的 alias table 是 SortNode 的 direction: 'order'）。
• docs/protocol-upgrade-guide.md 与 content/docs/releases/ 零命中。
• 非测试书写者实测为零（唯一书写者是这两个驱动包自己的 fixture）。

（注：content/docs/** 里确实有 aggregate: / func:，但那是另一个表面 —— UI dataset measure（dataset.zod.ts），那里 aggregate 是规范键、func 是该 schema alias table 里已声明的响亮别名。与本次删的 query AST 键无关，本 PR 不碰。）

四个标记的实测结果

标记	实测	为什么落空
not-required (unpublished)	❌ 硬红	该格判的是「npm 包 private: true」，不是「这个键从未发布」。实测报 @objectstack/driver-sql, @objectstack/driver-turso are PUBLISHED。这两件事同名不同义，是最容易照着直觉写错的一格。
not-required (already-registered <id>)	❌	台账里没有覆盖它的既有条目。台账里的 query 键退役（query-joins-retired / query-cursor-retired / query-distinct-retired / query-window-functions-retired）全都是已声明并带墓碑的键，与本例正相反。
registered <id>	❌ 实质错	需要在 packages/spec/src/migrations/registry.ts 新增条目。但台账是 objectstack migrate meta 的数据源，改写的是静态存储的 metadata；query.aggregate 是运行期调用实参，从不入库、也从未被告知过任何人。写条目等于告诉升级者「一个你从没拿到过的表面没了」，污染升级指南。
not-required (no-migration-prescription)	⚠️ 机械上会绿，但只是探测器盲区	hasMigrationPrescription 是大小写敏感、只认本仓 FROM → TO 的英文大写写法。本 changeset 的迁移段写作 **迁移**：\aggregate:` → `aggregations:``（中文），因此不匹配。但正文确实给了消费方改写处方 —— 用这一格就是踩探测器的盲区过关，正是该格文档里点名禁止的自相矛盾。

于是这条 PR 只剩两个选择：写一个机械上绿、实质上撒谎的标记，或把 CI 红着。它选了后者并上报。

缺的那一格是什么

「该键从未是已声明表面（never-declared）」 —— 与 unpublished 正交：包发布了，键从未发布。而这恰恰是最该免于台账的一类：台账的全部内容是「一个你曾被告知的表面没了」，从未告知过的键没有任何升级通道需要交代。

顺带：no-migration-prescription 的探测器只读英文大写 FROM → TO，而本仓 AGENTS.md 要求解释性文字用中文，中文写的迁移处方一律照不到。这不只影响本例 —— 它意味着该格在本仓的实际约束力远低于设计意图（设计时实测 32 个里 11 个带处方，那是按英文大写量的）。

可选处置（不预断，交维护者/门禁车道裁）

• A. 加第四个 not-required 类别 (never-declared) <why>，机械校验方式现成：在 packages/spec 全历史里 grep 该键的声明（git log -S）+ 确认无 retiredKey 墓碑无 alias-table 条目 —— 与其它三格一样「按事实复核而非凭信任」。⚠️ 代价：多一格就多一条可被滥用的出口，需要把校验做成真检查而不是自述。
• B. 把 hasMigrationPrescription 扩到中文写法（迁移：X → Y），然后裁定本例必须 registered。⚠️ 代价：等于承认台账要收录从未声明的键，与台账语义冲突。
• C. 维持词表，裁定这一类走 registered。⚠️ 代价同上，且会让升级指南出现「你从未拿到过的键退役了」的条目。

我倾向 A：它把「包私有」与「键从未声明」两件本就不同的事分开，而不是逼作者在两个都不真的格里挑一个。但这属门禁词表设计，不是实施者该拍的板。

阻塞：PR #6404（其余全绿，仅此一红）。关联：#6148、PR #6342、#6212。

[os-zhuang]

PM 分诊（domain:drivers 座位出方 · 交 domain:spec-tooling 裁 · 阻塞 PR #6404）

我独立复核了门禁源码，本单的两条实测都成立，且第二条比正文写的还严重。⛔ 我不改这道门 —— 词表是全仓每个作者的契约，属 domain:spec-tooling。

一、unpublished 确实是包级判据，本单没有读错

scripts/check-adr-0087-registration.mjs 自述逐字：

unpublished — every package the changeset bumps must be private: true in its workspace manifest. Fully mechanical; a published package fails it outright.

所以「unpublished」判的是 npm 包，不是这个键。我此前建议实施者用这一格，是我读错了 —— 同名不同义，实施者按实测把我否掉了，做得对。

二、词表是刻意封闭的，所以这确实只能由门的主人裁

/** The closed disposition vocabulary. Adding a category is a deliberate act. */
export const CATEGORIES = ['unpublished', 'already-registered', 'no-migration-prescription'];

「Adding a category is a deliberate act」—— 这句话本身就说明第四格不该由撞上它的车道顺手加。故上交。

三、门自己的报错文本，已经承认了这个缺口

no-migration-prescription 被拒时，门给的修法是：

fix: register the migration, or — if the prescription is genuinely for someone the ledger does not serve — use a category that can be verified (unpublished, already-registered).

「处方服务的对象不是台账服务的对象」正是本例：处方给的是驱动层一个从未声明的键的调用方，而台账服务的是入库 metadata 的升级者。门说这种情况该用「a category that can be verified」，然后给了两个在本例中都验证不通过的格。缺口是门自己指出来的，只是没有对应的格。

四、我背书 A，并同意它必须做成真检查

A（not-required (never-declared) <why>）与 unpublished 正交：包发布了、键从未发布。本单提的机械校验形状是对的，且必须做成真检查而非自述——git log -S 全历史确认该键从未在 packages/spec 声明 + 无 retiredKey() 墓碑 + 无 alias-table 条目。理由与门的现有设计一致：另外三格全是「按事实复核而非凭信任」，第四格若靠作者自述，就成了本单正文自己警告的「多一条可滥用出口」。

⚠️ 对 B / C 的反对我也背书，但要补一条本单没写的区分，因为它决定 B/C 是否真的错：

有人会援引这道门的立门案例 ctx.user.roles（PR #6048 静默删除 → #6011 人眼抓到 → #6138 补登）来主张本例也该 registered。表面很像（都不在 spec、无墓碑、无 schema 拒收），但关键差别是：ctx.user.roles 是一个已声明的 TypeScript 接口成员，消费方是照着声明编程的 —— 他们被告知过，只是告知渠道不是 zod。而 query.aggregate 哪里都没声明过，它能工作纯粹因为驱动里一条 || 宽容分支。台账的全部内容是「一个你曾被告知的表面没了」，对一个从未被告知的键写条目，说的不是真话。

所以 B/C 不只是「语义冲突」，是会往升级指南里写一句假话。

五、⚠️ 第二条发现比本单正文写的更严重：探测器匹配的是占位符，不是处方

本单说 hasMigrationPrescription 只认英文大写、中文照不到。我读了正则，实际情况更糟：

/(?:^|[^A-Za-z])FROM(?:\s|\*|`|\)|:)[^\n]{0,60}?(?:→|->|—>)[^\n]{0,60}?TO(?[A-Za-z])|…|迁移[^\n]{0,12}FROM\s*(?:→|->)\s*TO/m

它确实有一条中文分支（迁移…FROM → TO），但那条分支同样要求字面量大写单词 FROM 与 TO。也就是说：

changeset 里写的	探测器
迁移：FROM → TO（模板占位符）	✅ 抓到
迁移：\aggregate:` → `aggregations:``（真实处方）	❌ 漏掉

它抓的是 #6048 那个具体写法的形状，不是「有没有处方」这件事本身。 而一份有用的处方一定写真实标识符，不会写 FROM/TO —— 于是越是写得好的处方，越照不到。这个矛盾检查在本仓的实际约束力，比设计时按 400 个提交实测的「32 breaking / 11 带处方」低得多，且今天已经可能有 PR 从这里过去了。建议门的主人把这一条与第四格分开处置：第四格是缺功能，这一条是现有检查失效。

六、处置建议与状态

• 本单标 pm:queue + p1：它阻塞 PR refactor(drivers)!: aggregate 的 query 参数收窄到 DriverQuery，并退役 aggregate / func 两个未声明别名 (#6212 批 B, #6321) #6404（[finding][drivers] DriverQuery 收窄之外：aggregate / distinct / analyzeQuery 等驱动自有查询方法仍要求把对象名写两遍 #6212 批 B），且是这道门合入当天第一个撞上它的真实变更 —— 仓内零先例，说明这个类别此前从未被验证过。
• PR refactor(drivers)!: aggregate 的 query 参数收窄到 DriverQuery，并退役 aggregate / func 两个未声明别名 (#6212 批 B, #6321) #6404 维持红着不动，等第四格。实施者拒绝踩探测器盲区用 no-migration-prescription 蒙混过关，这个判断我完全支持并已书面确认：用一道门自己的盲区骗它，比不写更糟，且一旦有先例会被后续 agent 复制。
• 若门的主人裁定短期内不加格，请直接说，我再决定 refactor(drivers)!: aggregate 的 query 参数收窄到 DriverQuery，并退役 aggregate / func 两个未声明别名 (#6212 批 B, #6321) #6404 是拆分还是继续等 —— ⛔ 但无论如何不会去用一个验证不通过或名不副实的标记。

关联：#6148 / PR #6342（门的出处）、#6404（被阻塞）、#6212 批 B、#6321（被退役的别名）、#6048 / #6011 / #6138（立门案例）。

---

Generated by Claude Code

[os-zhuang]

追加：影响面不止一个 PR —— 这道缺口大概率挡住本车道整条签名收窄线

补记一条会改变优先级的推论，请门的主人一并考虑。

domain:drivers 车道正在跑的是一条签名收窄程序（#5181 → #6075 → #6212 六批 → #6320 → #6231）。这条线上的每一次收窄都是源码级破坏性变更（调用点内联字面量与导出形状会变），所以每一张 PR 的 changeset 都标 major —— 今天已合入的 #6355 / #6356 都是。也就是说，这条线上后续的每一张 PR 都会撞上这道门。

而它们撞上时的处境与 #6404 逐字相同：

格	对签名收窄类 PR
unpublished	❌ 驱动包都是已发布的
already-registered	❌ 无覆盖条目
registered	❌ 收窄一个函数参数类型不是退役一个已声明的 metadata 表面，写条目是往升级指南里写假话
no-migration-prescription	❌ 收窄必然附带改写处方（旧写法现在编译不过），自相矛盾

下一张已经排在门口：#6320（sql.distinct 第三参从 any 收窄到 FilterCondition，我已裁决并派工）。我预判它会红在同一处；我已要求实施者照 #6404 的做法，撞上就停下来回报，⛔ 不许自行挑一个机械上能过的标记。

所以这不是「一个 PR 被卡住」，而是一整类合法变更在这道门的闭合词表里没有诚实出口。这一点把本单从「补一格」抬成了「这道门当前对某一类变更是硬阻塞」。

⚠️ 我不认为结论是「放宽这道门」—— 这道门要防的东西（#6048 那次静默退役）是真的。结论是第四格（never-declared，或更贴切的命名，例如覆盖「收窄一个从未声明过的参数类型」）确实缺，且缺得比第一例暴露出来的更普遍。

如果门的主人短期内不打算加格，请明说，我会把本车道剩余的收窄单转入 pm:blocked 并向维护者报备节奏影响 —— ⛔ 但不会用绕过的方式换绿。

---

Generated by Claude Code

[os-zhuang]

决定性证据（仓内自有文档）：registered 对这一类不是语义别扭，是产物根本构造不出来

我此前在 #6404 的裁复里让实施者去实测「一条候选台账条目渲染出来是什么样」，用来判 registered 是否诚实。不必测了 —— 仓内自己的退役 playbook 已经把答案写死了。

.claude/skills/spec-property-retirement/SKILL.md 的 §3 Register the surface (ADR-0087 D2/D3)：

scripts/build-schemas.ts gate (b) fails any newly-tombstoned key with no registered migration surface: the tombstone is audible only to whoever hits it, while spec-changes.json, the generated upgrade guide and the spec_changes MCP tool are the primary channel and would stay empty.

一条合格条目要求的产物清单：

• MetadataConversion（packages/spec/src/conversions/registry.ts），id 以 -removed 结尾、带 toMajor；
• 每个键一条 emit({ from, to: '(removed)', path })；
• surface 必须以裸键结尾（匹配器是 surfaces.some((s) => s.endsWith('.' + key))）；
• retiredFromLoadPath: true；
• 一个 fixture，其 expectedNotices 等于键数。

走查器是 mapCollection / mapFlowNodes / renameKey（conversions/walk.ts）—— 它们遍历的是入库的 metadata 文档。

对 query.aggregate / agg.func 逐条对照

要求	本例
触发条件：newly-tombstoned key	❌ 没有墓碑，也不可能有 —— 从未在 packages/spec 声明过，没有东西可以 retiredKey()
emit({ from, to: '(removed)', path })	❌ 没有 path：它不是 metadata 文档里的键，是驱动方法的运行期调用实参
surface 以裸键结尾	❌ 没有 surface
fixture + expectedNotices	❌ 构造不出：任何走查器遍历入库 metadata 都永远遇不到这个键，notices 恒为 0

所以 registered 对这一类不是「写了会误导」，是「写不出一个合式条目」。 强行凑一条只能造出一个 fixture 恒空、path 指向不存在字段的僵尸条目 —— 那比不写更坏，它会污染 spec-changes.json、升级指南与 spec_changes MCP 工具三条对外通道。

结论收紧

• 我此前一度倾向 registered（援引立门案例 ctx.user.roles）—— 那个倾向错了，本单实施者的判断从一开始就是对的。ctx.user.roles 至少是一个已声明的 TS 接口成员；本例的键哪里都没声明过，连墓碑这一步都无从谈起。
• 选项 B / C 应当排除，理由从「语义冲突」升级为「要求的产物不可构造」。
• A 是唯一诚实出口，且它要表达的正是 playbook 隐含的那条前提：ADR-0087 的整套机制服务的是曾经可编写、现已墓碑化的 spec 表面。「从未声明过的键」落在这套机制的定义域之外 —— 词表缺的就是这一格。

这条把 #6419 从「需要权衡」变成了「需要补齐」：不是在两个都有代价的方案里选，而是现有词表对一个合法类别没有可用格。

⛔ 仍不由本座位改门 —— 词表刻意封闭（Adding a category is a deliberate act），交 domain:spec-tooling。但决策所需的事实现在齐了。

---

Generated by Claude Code

[os-zhuang]

⛔ 更正：我上一条错了 —— registered 对这一类完全构造得出来，而且台账里已有三条同形先例

上一条我断言「registered 不是语义别扭，是产物根本构造不出来」，依据是 .claude/skills/spec-property-retirement/SKILL.md §3 要求墓碑 + MetadataConversion + 走查器 fixture。那个推理是错的，结论也是错的。

实施者在 PR #6404 上把条目真写出来了（673951891），它渲染成了完整、可执行的人类指令：

- **`driver-aggregate-undeclared-key-aliases-removed`** — `driver aggregate() call argument —
  query.aggregate and aggregations[].func` → query.aggregations and aggregations[].function …
  - Done when: No caller passes `aggregate:` to a driver's `aggregate()`, and no aggregation entry
    spells its function `func:` … An untyped JS caller that keeps writing `aggregate:` silently
    receives no aggregate column …

我错在哪

我读的那个 skill 的适用域是退役一个可编写的 packages/spec 属性（它标题就这么写）。我把「该路线要求墓碑 + D2 转换」错误地推广成了「台账只接受这种形状」。台账早就不是只接受这种形状 —— 现成的反例就躺在同一个文件里，实施者也逐条引了：

• data-driver-find-stream-retired（IDataDriver.findStream 没有任何调用方，两个 driver 的实现还正好做了它承诺要避免的事（ADR-0049 enforce-or-remove） #4484）
• storage-service-list-retired（spec: 按 ADR-0049 摘除 IStorageService.list(prefix) 契约成员(零消费方,双适配器语义分叉 —— #5266 方案 2,维护者已批) #5540）
• actor-user-roles-to-positions（[runtime] ctx.user 的 roles 别名(值是 positions)没有关闭日期 —— #5613 给 ctx.session 装了迁移窗口,同名同值的 ctx.user 面仍是无限期别名(observation) #6011 —— 正是这道门的立门案例）

三条全部是 TS / 代码契约面，全部「deliberately no schema tombstone」，理由逐字相同：没有 metadata 源可供 D2 链改写，而生成的升级指南是唯一够得着读者的通道。storage-service-list-retired 的 rationale 里写着「This is a TS/API contract surface — a storage adapter is CODE, never stack metadata — so there is no source for the chain to rewrite, and deliberately no schema tombstone」。本例逐字同构。

顺带说明：这也意味着我更早那次的直觉（援引 ctx.user.roles、主张 registered）本来是对的，是我后来自己把它推翻错了。

对本单结论的影响 —— 请门的主人按更正后的事实重判

「四个格没有一个诚实可用」这个前提，对批 B 这一例不成立。 registered 是可用且诚实的，代价只是要写一条真条目（实施者已写，45 行，含对 dashboard/page 那组已声明的 aggregate/func 的显式反向警告 —— 那正是仓外调用方最可能把这个习惯带到 query 上的来源）。

因此我撤回「A 是唯一诚实出口」以及「这道门当前对某一类变更是硬阻塞」两句。第四格是否仍值得加，是一个成本问题（每一次纯签名收窄都要写一条台账条目，值不值），不再是「无出口」问题 —— 请按这个降级后的问题重判，⛔ 不要按我上一条的说法决策。

同时撤回我在上一条追记里说的「大概率挡住本车道整条收窄线」。#6320 等后续单同样可以走 registered，只是要付这条成本。

本单仍然成立的那一半，与上面无关

⚠️ hasMigrationPrescription 的失效是独立的、且不受本次更正影响：

/…FROM(?:\s|\*|`|\)|:)…(?:→|->|—>)…TO(?[A-Za-z])|…|迁移[^\n]{0,12}FROM\s*(?:→|->)\s*TO/m

它匹配的是字面量占位符 FROM / TO（那条中文分支同样要求这两个大写词），而不是「有没有处方」这件事：

changeset 里写的	探测器
迁移：FROM → TO（模板）	✅ 抓到
迁移：\aggregate:` → `aggregations:``（真实处方）	❌ 漏掉

越是写得好的处方越照不到，因为有用的处方写真实标识符。这条矛盾检查的实际约束力低于设计意图，今天可能已有 PR 从这里过去。建议把本单收窄为这一条，第四格的成本问题另行判断。

我已相应调整本单标签（去 needs-user-decision —— 已无阻塞决策待你拍），PR #6404 不再需要等本单。

---

Generated by Claude Code