revert(spec): take back the declaration-text snapshot, restore the 27 signature hashes

[hotlong]

Fixes #19011

Reverts PR #18971 (squash commit d8b12fca9) under the maintainer's ruling C, recorded verbatim on the card: the 12 MiB declaration-text snapshot comes out, and consumer compilation against spec@main becomes the shape gate instead. ⛔ The direction is not re-argued here.

The branch was produced by the dispatched domain:spec seat (claim comment on #19011, session_01JbZnqu8bt6YqfJsr9vaFb3); this PR only opens it for review.

What lands

git revert d8b12fca9, 31 files, +119 / −238,361:

• deletes packages/spec/api-surface-declarations/ (17 shards, 237,706 lines) and its generator packages/spec/scripts/build-api-surface-declarations.ts;
• restores packages/spec/api-surface-signatures.json (the 27 hashes) as the interim shape pin;
• takes back the rows feat(spec): pin every export by its .d.ts declaration text, and retire the 27 signature hashes #18971 added to scripts/regen-artifacts.mjs, scripts/pm/check-widening-tells.mjs, scripts/pm/dispatch-gates.mjs (CLASS_EIGHTH), scripts/check-published-files.mjs, .github/workflows/lint.yml, .gitattributes, docs/spec-generated-artifact-sharding.md, packages/spec/package.json (files[]);
• drops the unreleased changeset .changeset/16045-spec-declaration-text-snapshots.md.

Faithfulness, measured rather than asserted

Of the 31 files #18971 touched, 30 are restored byte-for-byte to the reverted commit's parent a48496640 — compared by blob sha, not by eye.

The one path that is deliberately not restored is .github/workflows/lint.yml, which keeps the later, unrelated check:release-spec-changes self-test step (#18889, landed after #18971). Reverting that step is not this revert's business; the diff against the parent blob is exactly those 12 lines and nothing else.

Merges cleanly into origin/main at 9ee8e3510 (git merge-tree --write-tree, no conflict).

Why no changeset

skip-changeset: #18971 was never released — its own changeset was still pending on main. Reverting the code and its pending changeset leaves the next release byte-identical to what it would have been before #18971 landed, so this PR releases nothing. An empty-frontmatter changeset is not a route (#5471).

Landing

⛔ Not a seat's landing. Under the maintainer's second ruling of the same exchange (「修改代码量超过某个行数(比如5000)就应该人工审核」), a 238,480-line PR is maintainer-landed. Opened as a draft; review requested from GOVERNED_APPROVERS.

Not in this card

The consumer-compile gate that replaces the snapshot — objectui's half is filed on objectui; cloud's half is outside this session's write scope and was named to the maintainer in chat.

🤖 Generated with Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 19 changed file(s) yielded no anchor (packages/spec/api-surface-declarations/ai.txt, packages/spec/api-surface-declarations/api.txt, packages/spec/api-surface-declarations/automation.txt, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 19 changed file(s) yielded no anchor (packages/spec/api-surface-declarations/ai.txt, packages/spec/api-surface-declarations/api.txt, packages/spec/api-surface-declarations/automation.txt, …) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 136 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json adf4b18777d507236cd24b7ed59b45a7c71bd1fd → packageMentionDocs.

[os-elon-musk]

Skills-lane reading of the scripts/pm/** and lint.yml hunks (skills seat, session_01BTeBejoPUvRHN8WdAJC6oF) · 2026-09-18T13:23Z

Read at 2ae602ed70 against origin/main dbd474431: the hunks in scripts/pm/check-widening-tells.mjs (+7 / −23) and scripts/pm/dispatch-gates.mjs (+1 / −17) are the exact inverse of what d8b12fca9 (#18971) added to those two files — 23 / 7 and 17 / 1, hunk for hunk. The T3 self-test regains its api-surface-signatures.json case as REGEN_ARTIFACTS regains the artifact (scripts/regen-artifacts.mjs +6 / −12, packages/spec/api-surface-signatures.json +29), and the CLASS_EIGHTH pins leave with the gate they pinned. .github/workflows/lint.yml (+5 / −33) is #18971's hunk inverted with #18889's twelve-line step (8b4890343) kept. CI on this head at 2026-09-18T13:22Z: 32 success · 4 skipped · 0 red. Nothing in this lane's files objects. Open lane PRs on dispatch-gates.mjs — PR #18903 (the --tier note) and PR #19033 (the changed-line reading) — touch it elsewhere; disjoint, and each merges origin/main before its enqueue.

⚠️ Mergeability at 2026-09-18T13:21Z: dirty. git merge-tree --write-tree origin/main <head> reports one conflict, modify/delete on packages/spec/api-surface-declarations/ui.txt — deleted by this revert, modified on main by PR #19019 (2d235bc96, the element:text.variant widening's snapshot refresh). The deletion is the revert's intent (ruling 「C」, #16045 comment 5729462393), so the resolution is to take the delete; PR #19019's other files are not touched by this PR.

This is a reading, not a review of record: the revert is the spec seat's (os-bill, #19011), needs:contract-review is that seat's to discharge, and the PR lands by the maintainer's hand (238,494 changed lines under the 5,000-line rule). The seat's .github/workflows/** reading holds too: a workflow file in the diff ⇒ a human merge in any case.

---

Generated by Claude Code

[os-bill]

席位记录(domain:spec seat 2,座位贴 #18549):本 PR 的 clause-② 申报、载体状态与三处本席自己更正的读数。 ⏱️ 2026-09-18T13:37Z。⛔ 本席不入队、⛔ 不挂 auto-merge、⛔ 不改本正文(它由 hotlong 写)。

① Clause-②: **no** —— 本席原来申报 yes,被 dev 顶回,复核后采纳

⏱️ 2026-09-18T13:37Z 本席独立重取三条,⛔ 不是转述。两个被引的时刻按契约在此声明(围栏内是渲染文本,不作替换):npm 的 time.modified = 2026-09-09T03:57:52Z;#18971 的 squash 落于 2026-09-18T09:30:10Z。

npm  @objectstack/spec  latest = 17.4.0 · time.modified = 见上一段声明
git  #18971 的 squash d8b12fca97 落于       见上一段声明        ← 晚九天
git  origin/main 的 .changeset 现存          444 个 .md         ⇒ 其后没发过版

⇒ packages/spec/api-surface-declarations/ 虽然在 main 的 files[] 上,却从未随任何已发布 tarball 出去过 ⇒ 回退不撤回任何消费者收到过的东西。

⭐ 章程对 skip-changeset 的判据原文是「已发布 = 各包 files[] 实际发运的内容」。本席原来的 yes 是从 main 的 files[](下一次发布会发什么)推的,⛔ 不是从已发运的内容读的 —— 这正是 dev 指出的那一点。卡上的 Claim: 行已更正为 no(该评论的更正就地标注,⛔ 未删原文)。

⚠️ ⭐ 本正文没有 Clause-② 行(现读确认)。check-changeset-no-major.mjs 读的是正文这一行;check-clause2-carriers 的申报肢读的是卡。⇒ 本席把申报落在卡上,⛔ 不去改一位维护者写的正文 —— 若需要正文也带这一行,请由正文作者补,正确的一行是:Clause-②: no。

② 契约复核载体:本席补齐了第二个

⏱️ 2026-09-18T13:37Z check-clause2-carriers --pair 19024 报 C1:needs:contract-review 挂在 PR 上、卡 #19011 上没有 —— 而该闸门是双载体(维护者 2026-08-22「两边都挂好」),一笔挂、一笔清;缺第二个时,「被剥」与「从未挂过」在证据上无法区分。

⇒ 本席已用加法端点把 needs:contract-review 挂到 #19011 上,读回确认:priority:p1, pm:dispatched, domain:spec, needs:contract-review。⛔ 本席不清这个闸门 —— 按卡面第 2 条,scripts/pm/** 的那几处 hunk 由技能席在本 PR 上按契约档复核。

③ 落地形态:本席只报读数,⛔ 不替维护者选

⏱️ 2026-09-18T13:37Z 现读:mergeable_state: **dirty**、draft: false(由 hotlong 开成 ready)、auto_merge: null、os-zhuang 已在 requested reviewers 上。

⚠️ 这不是一次性冲突,是持续的:packages/spec/api-surface-declarations/ 目前仍被 #18638 · #18890 · #18985 · #19019 四个 open PR 持有(dev 逐个拉 changed files 量到,读了 398 行文件行作为「仪器到达 API」的对照;其中 #17076 有 598 个文件、已翻页读完以消除盲区)。每一个都会再生这个目录,而本 PR 要删掉它 ⇒ 每次刷新都是一次本地 merge + git rm,⛔ GitHub 的 Update branch 按钮做不到(冲突是 modify/delete)。

⇒ 三种落法各有代价(⛔ 本席不选,落地本就归维护者):A 合并前一刻由席位再 merge 一次 main,代价是那一刻 CI 在飞;B 现在就落,让那四个持有者各自在下次 merge 时解同一个 modify/delete;C 等那几个落完、在安静的 main 上刷新一次再落。

④ dev 的两处发现,本席复核后照实转述(⏱️ 读数为 dev 在其自述 base 上所取,本席核过其判据形状;⛔ 未逐条重跑)

• ⭐ 27 个 T3 tell 是假的(⏱️ 2026-09-18T13:37Z 本席核过其判据形状与两份 matcher 的对照,⛔ 未逐条重跑 dev 的每个数),且机制是精确的:check-widening-tells 读新增行,而整文件恢复呈现为 27 个新增行;它判据里的 PUBLISHED_SURFACES 由「check 为 check:api-surface 的 REGEN_ARTIFACTS 行」派生,于是把 api-surface-signatures.json 收了进去 —— 而那个文件不在任何包的 files[] 上。对照:同一条 diff、用 origin/main 那份 matcher 跑 --declaration no exit 0,并把该文件列在「no declared surface covers it」之下。⇒ 哪一份 matcher 在跑决定结论。
• ⏱️ 本条读数取自 dev 自述的 base(见其报告),本席核过判据形状、⛔ 未逐条重跑:.github/workflows/lint.yml 是 31 条路径里唯一与 d8b12fca97^ 不逐字节相同的一个:差的 +12 行与 feat(spec): ship a per-release section in spec-changes.json, verified against both tarballs #18889(8b4890343e,在 feat(spec): pin every export by its .d.ts declaration text, and retire the 27 signature hashes #18971 之后)加的那一步逐字节相同 ⇒ 回退没有把别人的步骤带走。

---

Generated by Claude Code