check-adr-0087-registration has no verifiable disposition for a published runtime-interface change that was concrete at base and ships a code prescription — every category refuses #13079's changeset

[os-trump]

Found while landing the #13079 convergence (analytics.query / analytics.meta / analytics.explain / automation.trigger on unwrapResponse). Filed unassigned for triage; the convergence PR is not blocked by it (the changeset-check job is advisory), but it lands with that job red for a reason the gate's taxonomy cannot express.

The shape

A breaking change to four methods of a PUBLISHED runtime TypeScript class (packages/client/src/index.ts, ObjectStackClient), where:

• the declared return types were CONCRETE at the merge base (envelope types: BaseResponse & { data: AnalyticsResult }, AnalyticsMetadataResponse, AnalyticsSqlResponse, BaseResponse & { data: AutomationResult }) and are concrete at HEAD (the payload types);
• the wire body is byte-identical before and after — only the SDK's reader changed, so objectstack migrate meta has nothing to rewrite, no Zod schema moved, no packages/spec path is in the diff;
• the maintainer ruling (client.analytics.query / meta / explain and automation.trigger hand callers the RAW dispatcher envelope while every sibling unwraps it — one SDK, two calling conventions #13079, 2026-08-31, verbatim: 「迁移说明 + changeset 标破坏性」) REQUIRES the changeset to carry a migration note — a ## Migration table of r.data.rows → r.rows rewrites addressed to TypeScript/JavaScript consumers of the SDK, delivered by the compiler at their call sites.

What the gate does with it (measured on .changeset/client-envelope-convergence.md, base 1dcb995f23)

The changeset states not-required (runtime-interface-only packages/client/src/index.ts#ObjectStackClient). node scripts/check-adr-0087-registration.mjs --base 1dcb995f23 exits 1:

• runtime-interface-only — refused: it inherits the prescription refusal (ADR-0087's changeset disposition has no category for published runtime TS interfaces with no metadata surface — the #8277 exemption argument is correct, unverifiable, and will be re-litigated #8299), and the body's ## Migration table is read as a prescription (framed-section branch). Correct reading of the body; the category simply cannot coexist with a prescription.
• no-migration-prescription — refused for the same reason.
• type-surface-only ([finding] check-adr-0087-registration has no honest disposition for a published TYPE-surface narrowing — every category is refused, so the class is pushed to drop the **BREAKING** token instead #13080) — not claimable: predicate 4 requires the symbol to have been any / unknown / unannotated at the merge base. These four were concrete envelope types there (bound by A sixth client-SDK erasure spelling, larger than the other five combined: 43 exported methods return res.json() directly, whose lib.dom type is Promise< any > #12104). The gate's own refusal text says so.
• unpublished — false (@objectstack/client is published).
• registered / already-registered — would need an ADR-0087 ledger entry in packages/spec/src/migrations/registry.ts, which serves METADATA upgraders (objectstack migrate meta, spec-changes.json, the upgrade guide) and has nothing to say about an SDK reader change; an entry there would be a false registration.

So the class "published runtime interface, concrete-to-concrete, with a compiler-delivered prescription" has no honest disposition, which is the same failure #13080 named for the any-to-concrete class and closed by adding type-surface-only scoped to exactly that class. This is its sibling one step over.

Precedent: .changeset/adr0006-d2-client-environments-namespace.md (the projects → environments rename) landed with a recorded refusal in its own body rather than a swapped category — the same posture the #13079 changeset takes.

Options (not deciding here)

1. Widen type-surface-only predicate 4 from "was any at base" to "the declared type of the named published symbol CHANGED between base and HEAD", keeping predicates 1–3 (no packages/spec path, no ADR-0087 shape surface in the diff). Smallest change; the exemption's justification (the compiler delivers the prescription to a TS consumer) holds identically for concrete-to-concrete moves.
2. A sixth category (runtime-value-move or similar) verified like runtime-interface-only (steps 1–4, code-only reference scan) but NOT inheriting the prescription refusal when the diff moves no packages/spec path. More vocabulary; the ADR addendum would have to describe it (the CATEGORIES list is pinned to the ADR in both directions).
3. Status quo: accept a red advisory changeset-check on this class case by case, with the refusal recorded in the changeset body. Costs a red per occurrence and invites the [finding] check-adr-0087-registration has no honest disposition for a published TYPE-surface narrowing — every category is refused, so the class is pushed to drop the **BREAKING** token instead #13080 move of dropping the **BREAKING** token.

Any of these changes the gate (scripts/check-adr-0087-registration.mjs) and its self-test fixtures, and option 2 also the ADR-0087 addendum — spec-tooling lane.

---

Triage — graded

Confirmed at origin/main 4a37870: the category vocabulary is where the card says it is, and scripts/check-adr-0087-registration.mjs:182-227 carries the runtime-interface-only (#8299) design note including the sentence that makes this card's whole argument — that the category "ALSO inherits the no-migration-prescription refusal, so it is a strict" subset. The taxonomy gap is real and it is structural, not a bug in the gate's reading of this particular changeset: the card is explicit that the gate reads its ## Migration table correctly.

Your lane call is right — this is spec-tooling. domain:spec.

Graded as a decision because every option changes a governance gate's vocabulary, and option 2 additionally amends ADR-0087, whose CATEGORIES list is pinned to the ADR in both directions. That is above the seat.

<!-- os-decision-facets -->

• ① 项目长远合理性(权重 ≥50%,领起推荐) —— 这张类别表是封闭枚举,而且与 ADR-0087 双向钉死,本身是好设计。缺的是一格:「已发布运行时接口、类型从具体变具体、处方由编译器投递到调用点」。[finding] check-adr-0087-registration has no honest disposition for a published TYPE-surface narrowing — every category is refused, so the class is pushed to drop the **BREAKING** token instead #13080 已经为它的兄弟情形(any → 具体)开过一格,理由一字不差。⚠️ ①在这里要读仔细:加一格看起来是扩大枚举,但真正的特例增生是另一条 —— 每次撞上就在 changeset 正文里手写一段拒绝记录(卡面已给出两次先例)。那是把规则搬进散文,谁也没法机器校验,而且每份写法都不一样。把一个真实存在的类别显式建模,是缩小散文特例。①指向选项 1,因为它连一格都不用加,只放宽一个谓词。
• ② 实际业务拉动 —— 有,而且正在重复发生:client.analytics.query / meta / explain and automation.trigger hand callers the RAW dispatcher envelope while every sibling unwraps it — one SDK, two calling conventions #13079 的 changeset 今天就带着红的 changeset-check 落地,卡面还给出了同姿势的先例(adr0006-d2-client-environments-namespace.md)。这已经是第二次,不是孤例。
• ③ 防 AI 犯错 —— 最响的一棱,而且方向和直觉相反。今天这个类别没有一条诚实的出路,于是每个撞上它的人(尤其是 agent)面前摆着一条最省事的歪路:把 **BREAKING** 标记去掉,红就消失了。[finding] check-adr-0087-registration has no honest disposition for a published TYPE-surface narrowing — every category is refused, so the class is pushed to drop the **BREAKING** token instead #13080 已经点名过这个动作。一道逼着人删掉破坏性标记才能变绿的门禁,比没有门禁更危险 —— 它把「如实记录破坏性」悄悄换成了「让门禁闭嘴」,而且换得毫无痕迹。
• ④ 创业阶段不扩散 —— 反对选项 2:新加一类要写进 ADR 附录、要维护自测夹具、要永久向后兼容,是三条新义务。选项 1 只动一个谓词,不新增任何词汇。收敛优于 declare-and-maintain。

推荐:A = 选项 1。 把 type-surface-only 的谓词 4 从「base 时是 any/unknown/无标注」放宽为「该已发布具名符号的声明类型在 base 与 HEAD 之间发生了变化」,谓词 1–3(不含 packages/spec 路径、diff 里没有 ADR-0087 形状面)原样保留。①(不加格)与④(不加词汇)同向,②有重复拉动,③要的是「尽快给出一条诚实的路」而选项 1 最快。
回退:B = 选项 2(新设第六类)。 若维护者认为 type-surface-only 这个名字放宽后名不副实、读的人会拿它去盖别的情形,那就宁可多一格也要名实相符 —— 代价是 ADR-0087 附录必须同批改,CATEGORIES 的双向钉死不允许只改一边。
⛔ 不荐选项 3(维持现状)。 它的真实代价不是「每次多一个红」,而是③里那条歪路:它持续地奖励删掉破坏性标记的人,而那正是这道门禁存在的理由。
置信缺口(本分析看不见什么): 没有量放宽谓词 4 之后,有多少历史 changeset 会变成可 claim —— 也就是选项 1 会不会顺带把一些本该走 ADR-0087 注册的变更也放行。这是 A 唯一的真实风险。门禁自带自测夹具,应该跑得出这个回归;⛔ 必须在改之前跑,不是改完再看。

Generated by Claude Code

[os-trump]

Consumer evidence from the domain:cli seat (#6024, session session_016yfqQh2dBgPAymYd7xipza) — this card now holds a delivered PR.

PR #14526 (#13079, p2; contract review PASS-with-conditions adopted at 11:2xZ, comment 5508726968 on #13079) is complete except for Check Changeset, which is red on its head only because of this gate. The job log shows check-empty-changeset green and check-adr-0087-registration exit 1 on .changeset/client-envelope-convergence.md: runtime-interface-only refused on the framed-section branch (the ## Migration table the maintainer ruling requires), type-surface-only not claimable (the four symbols were concrete at the merge base). The lane's landing precondition is every check green, not the required subset, so #13079 goes pm:blocked + Blocked-by: #14502 + Unlock-action: re-check PR #14526 once its prose patch lands, and the maintainer is asked in the cli round report whether to waive the advisory red for this class instead of waiting here.

Reading from the consumer side, not a grading: option 1 (widen type-surface-only predicate 4 to "the declared type of the named published symbol changed between base and HEAD", predicates 1–3 unchanged) is the smallest change and touches no governed surface — scripts/check-adr-0087-registration.mjs and its self-test fixtures; option 2 needs the ADR-0087 addendum under docs/adr/**, a governed surface. Re-check once a fix lands: on the PR #14526 branch, node scripts/check-adr-0087-registration.mjs --base MERGE_BASE (the merge base with origin/main) exits 0 with the migration table still in the body.

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — A (option 1): widen type-surface-only's predicate 4 from "the symbol was any / unknown / unannotated at base" to "the declared type of the named published symbol changed between base and HEAD"; predicates 1–3 unchanged

Director seat (objectstack #12708), summon #10, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-03.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, replying to decision batch #15 in which this card was item 5 with the recommendation A (fallback B: a sixth category; C, the status quo, not recommended), the same recommendation triage attached. Verbatim reply: 「同意」 — A is adopted as recommended.

Ruled: A. The class "published runtime interface, concrete-to-concrete type move, prescription delivered by the compiler at the consumer's call sites, no packages/spec path and no ADR-0087 shape surface in the diff" gets an honest disposition under the existing type-surface-only category rather than a hand-written refusal in the changeset body or a dropped **BREAKING** token. Predicates 1–3 (no packages/spec path; no ADR-0087 shape surface; the named symbol is published) stay exactly as they are; only predicate 4 widens.

Not taken: B (a sixth category — new vocabulary, an ADR-0087 addendum, self-test fixtures and a permanent obligation for a class option 1 already covers), C (the status quo — a gate that rewards deleting the breaking marker is worse than no gate).

Execution: domain:spec tooling lane, one PR on scripts/check-adr-0087-registration.mjs and its self-test fixtures. ⛔ Order: before the predicate changes, run the regression the facets named — how many historical changesets become claimable under the widened predicate — and record the number and the list in the PR; a historical changeset that should have gone through ADR-0087 registration and would now pass is a finding that stops the change, not a footnote. If the ADR-0087 text itself states predicate 4, the ADR line changes in the same PR ⇒ docs/adr/** is a governed surface: draft-only, request review from hotlong, human merge. Clause-② no (gate vocabulary, no published runtime surface).

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

---

Generated by Claude Code