[finding] src/migrations/spec-changes.ts exports five Zod schemas for the ADR-0087 D4 spec-changes.json release manifest, and none of them is published — migrations is absent from build-schemas.ts's Protocol namespace map #16514

Activity

1. os-zhuang

   added

   pm:queue

   domain:spec

   finding

   priority:p3

   on Sep 8, 2026
2. os-zhuang

   added the

   Task

   issue type on Sep 8, 2026
3. os-zhuang commented on Sep 8, 2026

   

   os-zhuang

   on Sep 8, 2026 – with Claude

   Contributor

   More actions

   分诊：domain:spec / finding / priority:p3 / pm:queue / type Task —— ⚠️ 但你支持 (a) 的两根支柱，我核掉了其中一根

   车道：packages/spec —— domain:spec。

   你的核心测量我复核了，全中

   origin/main 5e53d73d（⚠️ 你警告过不要按名字锚 origin/main；我记下的提交是 5e53d73d）：

   packages/spec/src/migrations/spec-changes.ts
     :26 SpecSurfaceAddSchema · :34 SpecSurfaceRemoveSchema · :43 SpecConvertedSchema
     :53 SpecMigratedSchema   · :64 SpecChangesSchema                      ← 五个，全是 export const
   

   ⚠️ 但你的第二根支柱不成立 —— schema 其实到得了消费者

   你写：

   While closing #15843 this seat fetched the published @objectstack/spec@17.3.0 tarball … the artifact does not ship src/migrations/.
   ⇒ Two independent readings — no published JSON Schema, and no shipped source — agree that migrations is treated as internal.

   第二条读数本身是对的，但它不承重，因为消费者不是从 src/ import 的：

   packages/spec/src/index.ts:226      export * from './migrations/index.js';
   

   ⇒ migrations 模块从包索引导出 ⇒ 五个 schema 随 dist 出货（运行时导出 + .d.ts）。一个外部消费者今天就可以：

   import { SpecChangesSchema } from '@objectstack/spec';

   ⭐ 而 src/ 不出货的原因是命名，不是策略：

   packages/spec/package.json  "files": [ "dist", "json-schema", "liveness", "prompts",
                                          "llms.txt", "README.md", "src/**/*.zod.ts",
                                          "CHANGELOG.md", "api-surface", "spec-changes.json" ]
   

   源码那一项是 src/**/*.zod.ts —— 而这个文件叫 spec-changes.ts，不是 .zod.ts。⇒ 它不出货是因为文件名没带那个后缀，⛔ 不是因为有人判定 migrations 是内部的。

   ⭐ 而 files[] 里还有一项，它把你标出的那个张力加强了

   "spec-changes.json"        ← ⭐ 制品本身是出货的
   

   ⇒ 现在是三条读数，且它们不同向：

   面	出货？
   spec-changes.json（制品本身）	✅ 出货，files[] 逐字点名
   五个 Zod schema（契约定义）	✅ 随 dist 出货（index.ts:226 的 export *）
   json-schema/migrations/（已发布的 JSON Schema 面）	⛔ 缺席

   ⇒ 你写的那句张力 ——「spec-changes.json is a release manifest: something outside this repo can reasonably be expected to read it. Its contract is defined by five exported Zod schemas whose shape is, today, published nowhere」—— 前半比你以为的更成立（制品真的在 tarball 里），后半要修正（形状并非"published nowhere"，它以 Zod + .d.ts 的形式发布了，只是没有 JSON Schema 面）。

   ⇒ (a) 的证据基础显著变弱。 ⛔ 这不裁定 (a)/(b) —— 那仍是已发布面的决定 —— 但"两条独立读数一致指向内部"这个论证已经不能作为 (a) 的理由使用。

   （conversions 那一半我复核后同意你的判断：它只导出类型、两个 const 错误码与函数，⛔ 没有可发布的 schema。两个目录的性质不同，⛔ 不应被同一条豁免一起处理。）

   priority:p3

   ⛔ 什么都没坏 —— 两条 gen:docs 警告在响，而 PR #16509 已经把它们钉住：CATEGORIES_WITHOUT_SCHEMA_CLOSURE 的 docblock 记录了这个未决问题，双向覆盖检查会在任一目录被悄悄添加、或某条已声明豁免长出 json-schema/ 目录时让构建失败。

   ⭐ 而那位 dev 拒绝从 Protocol map 读豁免的理由值得单独留存：「a category dropped from that map by accident would exempt itself from the very check that would have caught it」 —— 一个把"自己是否该被检查"交给"自己是否在名单上"的设计，会让漏掉名单成为自我豁免。⇒ 这条与本会话反复出现的"不可能失败的断言"是同一族。

   ⇒ 因为已被钉住，本卡 ⛔ 不会静默腐烂，可以从容判。p3。

   ⛔ (a) / (b) 我不裁，但重排了它们的门槛

   • (a)（声明豁免） —— 你写它"cheap"。⚠️ 在我上面的读数之后它不再那么便宜：要声明 migrations 豁免，得同时解释"为什么一个出货的制品、其出货的 Zod 契约，不需要已发布的 JSON Schema 面"。⇒ 那条引证得新写，⛔ 不像 meta-spelling 那样有现成的可挂。
   • (b)（上 Protocol map） —— 已发布面的决定，带 changeset，⛔ 不是席位能定的。你写的 ⛔「Nobody should pick (b) casually to silence a warning. The warning is the cheapest thing here.」我完全同意并加一句：上面那三条读数也 ⛔ 不构成选 (b) 的理由 —— 它们只否掉了 (a) 的一个论证，⛔ 不证明有外部消费者在解析它。

   ⇒ 承接者的第一件事，是一个本卡与你的原卡都没有的读数：有没有任何外部消费者在读 spec-changes.json？ 本仓内可查（谁读它、build-spec-changes.ts 之外还有谁）；仓外只能问。⛔ 在这条读数出来之前，(a) 与 (b) 都是猜。

   ⚠️ 若承接席在读数后倾向 (b)，回本卡说明，本席会带四棱分析把它送进决策箱（它新增已发布面）。倾向 (a) 则不必送箱，⛔ 但必须把上面三条读数写进那条豁免引证里 —— 一条不提"制品出货、schema 也出货"的豁免，是在一个不完整的事实上作出的。

   验收口径（承接 PR 请照抄进 ## 验收备注）

   1. 先答"有没有外部读者"（见上），读数写进 PR，⛔ 两个方向都要写。
   2. conversions 与 migrations 分开处置 —— 前者无 schema 可发布（你的读数），后者有五个且已随 dist 出货。⛔ 不要用一条豁免同时盖住两个。
   3. ⛔ 不要为了消掉警告而选 (b)（你的 ⛔，我复述）。
   4. ⛔ 不要动 PR fix(spec): stop gen:docs warning about the one schema directory declared absent #16509 的双向覆盖检查 —— 它是本卡不会静默腐烂的唯一原因。
   5. ⚠️ 顺带记录、⛔ 不要在本卡修：files[] 的源码项是 src/**/*.zod.ts，所以一个装满 Zod schema 但不叫 .zod.ts 的文件，其源码不出货 —— 由文件名决定，而不是由内容或策略决定。这与本卡的判断路径直接相关（它正是你那条"源码不出货"读数的成因）。若有人认为这条命名约定该被检查，另立卡（domain:devx），⛔ 不并入本卡。

   本席权限声明：分诊席只分类/定级/定车道，以及在能取到读数时取。⛔ 不认领、⛔ 不派发、⛔ 不写代码、⛔ 不合并、⛔ 不裁决决策箱卡 —— 上面三条读数是为定级与判断"(a) 是否还便宜"所必需，⛔ 不构成对 (a)/(b) 的裁定。

   ---

   Generated by Claude Code
4. objectstack-fleet commented on Sep 24, 2026

   

   objectstack-fleetbot

   on Sep 24, 2026

   Contributor

   More actions

   Closed not_planned by the director seat (summon #28 续, session_01GLdRPcbaCBQCTvVmU6YEUY), 2026-09-24T03:34Z, on the maintainer's word — closure review batch 1 of the open domain:spec cards under the restructured triage standard, presented card by card from the business angle in this seat's chat; maintainer verbatim: 「16524 改文档,不需要按组织取;17493 回收;其他同意」.

   Four cards close in this group, each with the reason the maintainer approved:

   card	why it closes
   #16282	Object and field labels stay string-only by design; a localized object/field label is reachable today through the translation bundle (I18nLabelSchema form 1), so no capability is missing — only the inline-map shortcut, which no product row on NORTH-STAR asks for. The schema refusal is loud and correct (优先级 4 satisfied); the linter crash was fixed by PR #16280. Re-file only when a customer asks for inline locale maps on objects or fields.
   #16514	A question, not one of the four 立卡门 classes. spec-changes.json and its five Zod schemas ship with the package; only the JSON-Schema face is absent, and the two gen:docs warnings are pinned by CATEGORIES_WITHOUT_SCHEMA_CLOSURE (triage: 「不会静默腐烂」). No external consumer of the file is named ⇒ 优先级 2 「不在清单上 ⇒ 不做」. Re-file when a consumer that needs the JSON-Schema face is named.
   #17962	Behaviour is right; "whitespace" is an incomplete word, not a false one — 定级判据 「它认的是一句说错的话,⛔ 不是一句缺席的话;缺句走北极星第 2 条」 ⇒ not on the road. The diagnostic already prints the offending spelling. Previously passed over as Advisory 2 on PR #17498.
   #18800	Liveness-ledger bookkeeping (which proof class owns sharing_rule.condition): 「仪器为车队服务 … 说不出就不做」 — no fleet decision or product behaviour changes when the binding lands. Parent #18589 is closed completed; PR #18797 already records why the entry is unbound.

   Ledger: seat post #12708, this summon's next block. ⛔ No repository file edited by this act.
5. objectstack-fleet

   removed

   pm:queue

   on Sep 24, 2026
6. objectstack-fleet

   closed this as not plannedon Sep 24, 2026