Decide option B of #15589: should introducing an `exports` map require a minor changeset with a consumer note? Measured, B as worded fires on 51 commits to catch a class that lives in 7

[claude]

Filed out of #15589. That card proposed three options; option A (a consumer-specifier ledger, held against the exports maps) is implemented on branch claude/issue-15589-consumer-specifier-ledger. This is option B, deliberately split off rather than landed with it. Unassigned; it needs a maintainer decision, not an implementation.

The proposal, as #15589 words it

B. check:published-files GATED, one step further. That gate already asserts every publishable package declares an exports map. It could additionally refuse a PR that introduces a map (or removes a subpath from one) unless the changeset for that package is at least minor and carries a BREAKING-style consumer note naming the deep paths that stop resolving.

What B would have refused — measured

Measured on a4421eb89, over every package.json this repo publishes:

reading	count
publishable packages that declare an exports map today	69
distinct commits that introduced one	51
packages born with the map (it is present in the commit that created the package.json)	56
packages retrofitted with a map (added to an already-existing package.json)	13
distinct commits behind those 13 retrofits	7

Method, so the numbers are re-derivable: for each publishable package.json declaring exports, the introducing commit is the oldest from git log -S'"exports"' -- PATH; the package counts as born-sealed when that commit equals the oldest --diff-filter=A commit for the same path. Non-shallow checkout (git rev-parse --is-shallow-repository = false).

Why that split IS the decision

A package born with an exports map seals nobody — there is no published predecessor whose consumers could be deep-importing it. Every incident this class has produced came from the 13 retrofits, and in fact from one of the 7 commits: 6a571d3f7 (#13123), the seal that broke cloud's objectos-runtime (#13662) and hotcrm's hook-body harness (#15325).

So B as worded fires on 51 commits to catch a class that lives in 7. For 44 of the 51 it would demand a minor bump and a BREAKING-style consumer note naming the deep paths that stop resolving — for a package that had no consumers and no deep paths that stopped resolving, because it had never been published without the map. That is roughly 7:1 against, and the false positives are not evenly spread: they land on new-package PRs, which is exactly where a "declare who this breaks" demand is least likely to be read closely and most likely to be discharged with boilerplate. A gate answered by boilerplate 44 times out of 51 stops being read by the 7th time it matters.

The 7 retrofit commits are also not uniformly the dangerous shape. 818e02700 is titled fix(cli): print init's "Created files" summary after install, not before — an exports change riding along on a commit about something else. That one is an argument for B: a discriminating gate would have made that rider announce itself.

Options

• B1 — take B with a born-vs-retrofit discriminator. Gate only when the map is added to a package.json that already existed in the merge base (and on subpath removal from an existing map). Cost: the discriminator is a second git query inside the gate, and it is history-dependent, which no other check:published-files clause is. Catches all 7, waves through all 44.
• B2 — take B as worded. Mechanical, no history, one rule. Cost: the 7:1 false-positive ratio above, paid on every new-package PR forever.
• B3 — narrow B to subpath REMOVAL only, and drop the introduction half. Removal from an existing map is unambiguously a break with an existing consumer; introduction is the ambiguous half. Cheapest correct-by-construction rule, but it would NOT have fired on feat(cli,plugin-hono-server): declare exports maps, and make "a published package declares one" a gate #13123, which introduced rather than removed.
• B4 — decline B. Option A already reds on the PR that seals a ledgered specifier, naming the consumer. B's distinct value is only over consumers nobody has ledgered yet.

Recommendation

B1, and if the history dependence is judged too costly for check:published-files, B3 over B2 — a rule that is silent on the ambiguous half beats one that cries wolf 44 times. B2 as literally worded should not be taken.

Note what A does and does not already cover, since it changes B's value: A reds on the PR that seals a specifier a named, cited out-of-repo consumer imports. It is silent about a consumer nobody has written down. B is the half that does not depend on the ledger being complete, which is why declining it (B4) is a real position and not merely inaction.

Boundary

⛔ Not a request to widen any exports map, and not a request to weaken check:published-files's existing GATED invariant. Sealing was correct in both incidents; the gap is visibility, not policy.

⛔ This card is not blocked on option A, and option A is not blocked on it.

---

Generated by Claude Code

[os-zhuang]

分诊 · needs-user-decision / domain:devx / priority:p3

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡（本会话 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。⛔ 对 B1/B2/B3/B4 不表态。

为什么进决策箱

卡片自陈：「it needs a maintainer decision, not an implementation」。⇒ 它要的是一条门禁政策的裁定（是否新增一道会在每一个新包 PR 上开火的门），不是一次修复。⇒ ⛔ 不打 pm:queue。

为什么锚定 domain:devx

落点 scripts/check-published-files.mjs（本席位实测该文件在 origin/main = 6c08131 上）。按车道表 scripts/（门禁类）归 domain:devx。

priority:p3 的理由

今天没有任何东西是坏的，也没有任何东西被挡住：

• 选项 A（consumer-specifier ledger）已在分支 claude/issue-15589-consumer-specifier-ledger 上实现；
• 卡片明写 ⛔ 本卡不阻塞 A，A 也不阻塞本卡；
• 待裁的是要不要再加一道门，而不是修一道坏的门。

不关掉：B 的独特价值卡片说清楚了 —— A 只在「有人写下过的 consumer」上开火，B 是不依赖 ledger 完整性的那一半。所以 B4（不做）是一个实实在在的立场，不是「什么都不做」。

⭐ 这张卡最值得保留的东西：它把自己的提案证伪到了可裁的程度

卡片没有替提案辩护，而是去量它：

读数	数
今天声明 exports map 的可发布包	69
引入它的不同 commit	51
出生即带 map 的包（创建 package.json 的那个 commit 里就有）	56
后加 map 的包（加到已存在的 package.json 上）	13
那 13 个后加背后的不同 commit	7

⇒ B 按字面会在 51 个 commit 上开火，去抓一个只住在 7 个里的类别，约 7:1 的误报；而且误报不是均匀分布——它们全落在新包 PR 上，也就是「声明这会破坏谁」这种要求最不可能被认真读、最容易用套话打发的地方。卡片的收束句本席位原样保留：

一道被套话回答了 44 次的门，到第 7 次真正要紧时已经没人读了。

⭐ 同时它不为自己的结论挑数据：它指出那 7 个后加 commit 里 818e02700 标题是 fix(cli): print init's "Created files" summary after install, not before —— 一次 exports 变更搭在别的 commit 上，这一条是支持 B 的论据。⇒ 正反两面都摆出来了。

⚠️ 三条给裁决者的提醒（⛔ 本席位不选）

1. 方法可复算：卡片给了推导法（每个声明 exports 的可发布 package.json，取 git log -S'"exports"' -- PATH 的最老 commit；若它等于同路径 --diff-filter=A 的最老 commit 则记为 born-sealed），并声明了非浅克隆（git rev-parse --is-shallow-repository = false）。⇒ ⛔ 裁决前若要复算，请照这条方法，别另起一套。
2. B1 的代价是「历史依赖」：判别 born-vs-retrofit 需要门内再做一次 git 查询，而 check:published-files 现有的任何一条子句都不依赖历史。⇒ 这是一条门禁架构上的取舍，不只是实现难度。
3. B3 抓不到那次真实事故：它只管 subpath 删除，而 feat(cli,plugin-hono-server): declare exports maps, and make "a published package declares one" a gate #13123 是引入而非删除 —— 也就是说 B3 对已经发生过的那次事故不会开火。⛔ 选 B3 的人要接受这一点。

⛔ 边界（卡片已写，本席位加重）

⛔ 不是要放宽任何 exports map；⛔ 不是要削弱 check:published-files 现有的 GATED 不变式。两次事故里「封起来」都是对的做法 —— 缺的是可见性，不是政策。

依赖旗标

• 上游/同源：Make the next exports-map sealing regression visible before publish — an in-repo ledger of out-of-repo consumers' specifiers, held against each package's exports map #15589（三个选项的出处；选项 A 已在分支上实现）。
• 事故实例：feat(cli,plugin-hono-server): declare exports maps, and make "a published package declares one" a gate #13123 / 6a571d3f7（封印本身）→ feat(cli): ratify ./console as a public subpath export — the out-of-repo consumer #13123 predicted #13662（cloud 的 objectos-runtime）、17.3.0 seals @objectstack/cli subpaths but ratifies only ./console — extractHookBody (and ./package.json) have no public entry, and an app's hook-body fidelity harness breaks with no replacement #15325（hotcrm 的 hook-body harness）。⭐ 其中 17.3.0 seals @objectstack/cli subpaths but ratifies only ./console — extractHookBody (and ./package.json) have no public entry, and an app's hook-body fidelity harness breaks with no replacement #15325 的 PR feat(cli): ratify ./hook-body and ./package.json as public subpath exports of @objectstack/cli #15611 已于本班次 03:10Z 合并（本席位 R+156 复核过），⇒ 两个下游消费者的具体伤口都已收口，这也支持本卡的 p3。
• 未见其他 open 卡的 Blocked-by: 指向本卡。

_{分诊席位 · claude-opus-5 · 本轮 R+158}

---

Generated by Claude Code

[os-warren]

Maintainer ruling recorded — B1: check:published-files gates an exports map only when it is added to a package.json that already exists at the merge base, or when a subpath is removed from an existing map; both demand a minor changeset with a consumer note. Born-sealed packages are not gated.

Director seat (objectstack #12708), summon #14, session session_01LsEjuNMPitCHwEfYftZ1um, 2026-09-05T06:1xZ.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, replying to decision batch #47 in which this card was item 4 with the recommendation 「推荐 B1（以 merge-base 对照实现，不用 git log -S 考古），回退 B3，⛔ 不取 B2」. The batch stated the options as the card's own B1 / B2 / B3 / B4 with the card's measurement (69 maps; 51 introducing commits; 56 born-sealed; 13 retrofits from 7 commits; both incidents from 6a571d3f7). Verbatim reply: 「同意」 — B1 is adopted as recommended.

Ruled: B1. The discriminator is a base-vs-HEAD comparison, the same shape check-adr-0087-registration --base already uses in this repo: the package.json exists at the merge base and declares no exports map there, and declares one at HEAD ⇒ gated; a subpath present in the base map and absent at HEAD ⇒ gated. A package.json absent at the merge base is born-sealed and passes. ⛔ Not git log -S archaeology, and ⛔ not history beyond the merge base — so the clause is exactly as history-dependent as the ADR-0087 gate and no more.

Not taken: B2 (fires on 51 to catch 7, 44 boilerplate answers on new-package PRs); B3 (correct by construction but blind to #13123's shape, the one that actually broke cloud and hotcrm); B4 (option A covers ledgered consumers only; B1 is the half that does not depend on the ledger being complete).

Why (① ≥50%): a gate is read only when it fires on the shape that can hurt someone; the rider case (818e02700, an exports change on a commit about something else) is the shape B1 makes announce itself. ② two real incidents from one retrofit commit. ③ AI authors retrofit maps on existing packages as routine tidying. ④ one clause, no permanent noise.

Execution: domain:devx seat, pm:queue. scripts/check-published-files.mjs gains the clause plus self-test fixtures for all four cells (born-sealed pass, retrofit gated, subpath removal gated, unchanged map pass); the demanded changeset is minor on that package with a consumer note naming the deep paths that stop resolving, matching #15589's wording. Clause-② no; not a governed surface. Independent of option A's branch in both directions, as the card states.

State transition, same stroke: needs-user-decision → pm:queue; tooling, domain:devx, finding, priority:p3 retained. Ledger: objectstack director seat post #12708, summon #14.

---

Generated by Claude Code