[objectstack-fleet]

Requested by Steedos · project thread

Fixes #25767

Clause-②: no (narrowing: a key retired at or below protocol 16.x is refused as a strict unknown key without its own prescription in the error, and os migrate meta --from 16 refuses at the support floor instead of replaying step 17)
Metadata-protocol: narrowed

Tier H — governed path docs/adr/0087-metadata-protocol-upgrade-contract.md (amended in place) and a diff over 3000 lines (generated entries, surface files and ledgers included). Held draft for a GOVERNED_APPROVERS review.

What this PR does

Maintainer ruling on #25767, D2 = A: a retirement kit — the retiredKey() tombstone, its RETIRED_KEYS_BY_MAJOR / RETIRED_DEFS_BY_MAJOR rows, its semantic entry and its D2 conversion — lives through the protocol major after the one it retired in and leaves when the next major is cut. At 18 that keeps the 17.x and 18.x kits and removes everything retired at or below 16.x; 19 repeats the move one major on.

• Removed (derived from the registry rows and the liveness ledger, not from prose): 50 D2 conversions with retiredAfter at or below 16.x (5 at 15.0.0, 45 at 16.1.0) and their fixtures; 55 tombstones already [RETIRED] at @objectstack/spec@17.0.0 whose container is a strictObject; the 159 major-17 entry files (29 retired-key rows, 53 retired-def rows, 77 semantic entries) and the chain's step 17; 61 [RETIRED] lines of the authorable surface and their 36 liveness-ledger rows.
• Kept on purpose: 58 same-age tombstones whose container strips unknown keys (mapping.transform, rest-server.requireAuth, connector.rateLimitConfig, book.translations and kin) — deleting one would turn a refusal into a silent strip; the four inline-credential refusals, which are not retirements; the 17.x kits, which leave when 19 is cut.
• The refusal: a removed key now meets the strict unknown-key refusal, which carries one more sentence after its fix channels and ahead of its history sentence (RETIRED_KEY_UPGRADE_GUIDE_SENTENCE, exported with PROTOCOL_UPGRADE_GUIDE_URL from @objectstack/spec): keys retired before the previous major are no longer prescribed in the error — see the protocol upgrade guide, https://objectstack.ai/docs/protocol-upgrade. The strictObject 的 history 句夹在「哪个键错了」与「该写什么」之间,在单行 error 显示位上把修法推到 222 字符之后(#5762 实测) #5955 "history last" order is unchanged.
• The floor: MIGRATION_SUPPORT_FLOOR is 17; os migrate meta --from 16 and below answer MigrationFloorError, whose message names the floor and the guide, and rewrite nothing. packages/cli examples, pins and fixtures follow the floor.
• The deletion gate: check:authorable-surface proof 1 ages a tombstone one major (was two). A deleted [RETIRED] line is dated by an exact registry row or, new, by the previous major's release tag (@objectstack/spec@17.0.0 here): a line already [RETIRED] on the surface at that tag was retired before that cut. The tag is immutable, so neither a row a PR writes nor one it deletes moves the clock; when the tag cannot be read the gate dates by the registry alone and says so. No gate was added.
• The paper trail: ADR-0087 amended in place ("never deleted" / "permanent" / "forever" now read "one major past retirement"), the same permanence text in registry.ts.template's docblock, docs/protocol-upgrade-guide.md says where an aged-out kit's prescription lives (the release that carried it), content/docs/upgrading.mdx and the generated references follow, one changeset (minor for spec and cli, patch for lint and metadata-core).

Acceptance notes (read before approving)

1. 17.x load-path kits are rows, not steps. 17 conversions dated retiredAfter: 17.7.0 (datasource-driver-mongo-to-mongodb, retry-policy-converged, the flow-node aliases, sharing-rule-access-level-full-to-edit, …) stay registered for the data-at-rest seams (stored-row rehydration, the artifact door), but their chain step (17) is below the floor: os migrate meta --from 17 does not replay them. This is the template's own rule ("a step the floor no longer reaches retires"), the same move that retired steps 11–16 at the first floor move; their prescriptions already name the hand edit. Three protocol-18 semantic entries (spec(conversions): eight ADR-0087 D2 conversions stay on the 18 load path after #23487 — five families each need a ruling before they can retire #23543 F1/F2/F3: the mongo alias, the flow sibling-block lifts, the job retry default) declared a conversionIds link to one of those step-17 conversions and promised that os migrate meta lists the edit; the link is dropped and the prose names the hand edit, the shape the F4/F5 entries already have for protocol-11/15 conversions. The chain is one hop now (18) and stays one hop under the one-major rule; the cli report-order pin counts hops off the floor, and a new pin refuses a link to a conversion the floor does not reach.
2. Stored rows still in a ≤16.x shape are no longer rewritten at read; canonicalize once with os migrate meta --stored --apply on 18.1 or earlier. app-hidden-to-unpublished is among the removed conversions, so a pre-split hidden: true app row is no longer rewritten by any seam; the artifact door's refusal of it by id is removed as moot (@objectstack/metadata-core).
3. ADR-0104 data-migration advice is unreachable from the command. pendingDataMigrations keys on a run crossing into 17; no run does now. The field stays in the JSON ([]) and the code stays; the cli e2e pins only the silence. A ruling on deleting it is a residual on the card.
4. Unknown-key guidance tables are untouched. TOOL_RETIRED_KEY_GUIDANCE, CAPABILITIES_RETIRED_KEY_GUIDANCE, RETIRED_DATASOURCE_BLOCKS, JOB_ID_RETIRED, the app AREA_* aliases and kin are not ledger tombstones (no row, no entry); their house sentence is respelled to name the floor. Whether they age out with the kits is a residual on the card.
5. Fuzzy "Did you mean" can now point an aged-out key at a near spelling (retryDelayMs → maxRetryDelayMs, aria → areas); the guide sentence follows in the same message.
6. Tag offline: the gate's tag proof reads git show @objectstack/spec@17.0.0:…; a checkout without the tag dates by the registry alone and prints that it did.
7. No live ≤16.x reader found. Measured at 963e504cf5: no examples/**, ui/ or hotcrm source writes a removed key (the ui/ hits are the console's own same-named props and type mirrors).

File surface beyond the claim

The claim named packages/spec/src/conversions/registry.ts, the *.zod.ts tombstone files, suggestions.zod.ts, registry.ts.template, cli/.../meta.ts, ADR-0087, the releases page and one changeset. The diff also touches, each as a consequence of the removal and nothing more:

• packages/spec/src/migrations/entries/** (159 major-17 entry files deleted), chain.ts (floor + guide link in the error), shared/protocol-upgrade-guide.ts (new, the sentence and URL), shared/retired-key.ts (docblock), scripts/build-schemas.ts + scripts/lib/renamed-defs.ts (the one-major gate), the generated authorable-surface/*.json, api-surface/shared.json, export-origins/shared.json, liveness/*.json + state-counts/*.md, content/docs/references/** (all by the generators; check:generated is the proof).
• Spec, cli, lint and metadata-core tests whose pins named a removed kit (rewritten to the strict refusal + guide, or re-targeted to a surviving 17.x/18.x kit); packages/lint/src/validate-*.ts and packages/metadata-core/src/*.ts where a removed key or conversion id was read. The lint's field-rule walk no longer reads conditionalRequired (its tombstone left FieldSchema), its liveness pin for the dashboard walk rides the refreshInterval row, and the ADR-0032 dispatch-key tests accept the script contract's per-key refusals beside the lint's own prescription.
• docs/qa/platform-checklist/areas/ai.json: one lost anchor (skill.zod.ts#triggerPhrases) re-pointed, revision 7.
• docs/adr/0072-reference-scope-and-resolvability.md and docs/adr/0142-ownership-queue-membership-claim-and-assignment-rules.md: one symbol anchor each named a removed tombstone (flow.zod.ts#outputSchema) or a removed major-17 entry; re-pointed to the file / to prose, no other change. scripts/check-spec-docblock-symbol-anchors.mjs: the one CENSUS_RESIDUAL row whose citation left with a removed conversion's docblock is deleted, as the gate asks.
• packages/cli/test/package-owned-command-readers.test.ts: the [finding] cli(serve): os serve resolves capability providers from a multi-package artifact's top-level requires only — a package's requires: ['automation'] is not loaded at boot #22288 proof that os migrate meta reads every package's body rode the ADR-0104 listing, unreachable now; it rides a retired key on the service package's object instead, in a fixture pair of its own.
• .claude/skills/spec-property-retirement/SKILL.md: the aging clock and the second dating source, +4 lines (file 337 → 341, pack 1104 → 1108).
• Releases page: content/docs/releases/ is release-owned, so the "16 and below: refusal + link" note lives in the changeset (which the release notes are cut from), content/docs/upgrading.mdx and the upgrade guide.

维护者速读(草稿)

改了什么。 按你在 #25767 的裁决(D2 = A):退役套件只活到退役所在 major 的下一个 major。本 PR 在 18 上删掉所有 ≤16.x 退役的套件:50 个 D2 conversion、55 个墓碑、159 个 17 号 migration 条目和链上的第 17 步;被删的键现在由 strict 容器当未知键拒绝,错误里多一句指向升级指南(https://objectstack.ai/docs/protocol-upgrade),处方不再内嵌。os migrate meta 的支持底线从 16 升到 17,--from 16 直接拒绝并给链接。ADR-0087 原地修订,门禁的老化时钟从两个 major 改为一个,不新增门禁。

为什么改。 每个 major 都在累积墓碑和 conversion(17 号条目就有 159 个文件),它们既占 spec 体积也占每次升级的审阅面;业务上,升级者真正需要的是「我这把键该改成什么」,这句话放在升级指南和当时的 release notes 里就够了,不必让每个 strict schema 永远背着。

风险与代价(含回滚)。 ① 还停在 16 方言的源码不再拿到逐键处方,只拿到未知键拒绝 + 链接;它需要先在 ≤18.1 的 cli 上跑一次 os migrate meta --from 16。② sys_metadata 里仍是 ≤16.x 形状的行不再在读取时改写,要在 ≤18.1 上用 --stored --apply 规范化一次。③ 17.7.0 从加载路径退役的 17 个 conversion 没有可重放的步,靠处方手改(模板本身的规则)。④ ADR-0104 的数据迁移提示从命令里不可达了,代码留着待裁。回滚:revert 本 PR 即恢复全部套件与第 17 步;没有数据写入,没有不可逆动作。

席位意见。 (留空,席位定稿)

你要做的。 作为 GOVERNED_APPROVERS 批准本 PR(Tier H:ADR 原地修订 + >3000 行),或指出不认可的点;另有两个残留问题在卡片上等你一句话(guidance 表是否随套件老化;pendingDataMigrations 是否删除)。

---

Generated by Claude Code

[objectstack-fleet]

Maintainer ruling relayed: B, and it ships in 18.2 · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-26T14:12Z

⛔ Not a review, ⛔ not a claim. A relay of the maintainer's word for the holder of this PR and for the 18.2.0 release owner.

The maintainer's words (triage thread, 2026-10-26, verbatim): 「B，进 18.2」, answering two questions. Is a customer's ≤16.x metadata project still upgradeable after this PR? It is, through @objectstack/cli@18.1.0. And should the path be made prominent (B) and land in 18.2.0? Yes to both.

What B asks of this PR (text only, no code)

Put one prominent block, "Upgrading from protocol 16 or earlier", in two places. The changeset is one, because the release notes are cut from it, so it lands at the top of the 18.2.0 notes. The top of docs/protocol-upgrade-guide.md (or the protocol-18 page) is the other. The block carries, in this order:

1. Source metadata project: run the first hop on 18.1's CLI, the last release whose floor is 16:

   npx @objectstack/cli@18.1.0 migrate meta --from 16
   npx @objectstack/cli@18.1.0 migrate meta --from 16 --apply

   Work the to-do list it prints, then move the dependencies to 18.2 and run os migrate meta --from 17, os validate and os build.
2. Stored metadata (sys_metadata, Studio-authored), before the runtime moves:

   npx @objectstack/cli@18.1.0 migrate meta --stored --apply

   Say plainly that this must run before the deployment's image or dependencies move to 18.2. 18.2 no longer rewrites a ≤16.x row at read, so a row left behind is refused by the strict parse until it is migrated.
3. One line on what 18.2 does if step 1 is skipped: --from 16 refuses with MigrationFloorError and rewrites nothing, and a ≤16.x key meets the strict unknown-key refusal with the guide link.

content/docs/upgrading.mdx already carries this at its floor note (around :242–251). B makes it the first thing a reader of the 18.2.0 notes sees.

"Ships in 18.2"

• This PR lands before the 18.2.0 Version PR (chore: version packages #25640) is merged, so its changeset (spec and cli minor) is in that release. Tier H as stated, so the maintainer's review and landing apply.
• For the release owner: 18.2.0 is the first release in which a ≤16.x project must pass through 18.1. The B block is that release's upgrade note.

---

Generated by Claude Code

[objectstack-fleet]

Addendum to the B block: lead with "one major at a time" · triage seat · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-26T14:16Z

⛔ Not a review, ⛔ not a claim. This refines the relay above with the maintainer's follow-up (triage thread, 2026-10-26, verbatim): 「我先用 v17 的升级工具，然后再用 v18的升级工具，这个是通常能理解的流程吧」.

Verified on the release tag: @objectstack/cli@17.7.0 (published on npm) has MIGRATION_SUPPORT_FLOOR = 16 (packages/spec/src/migrations/registry.ts:79) and carries migrate meta --stored. So the stepwise path works as the maintainer describes, and it is the one readers already expect.

So the B block leads with it, and the 18.1 one-shot follows as an alternative:

1. One major at a time (the default, and the rule that generalizes to 19):

   npx @objectstack/cli@17.7.0 migrate meta --from 16 --apply   # 16 → 17
   npx @objectstack/cli@17.7.0 migrate meta --stored --apply    # stored rows, before the runtime moves
   # move the dependencies / image to 18.2, then
   os migrate meta --from 17 --apply                             # 17 → 18
   os validate && os build

2. Alternative: @objectstack/cli@18.1.0 still runs --from 16 through both hops in one command.
3. Unchanged: stored sys_metadata rows are migrated before the deployment's runtime moves to 18.2, and the line on what 18.2 does when step 1 is skipped stays.

The block can then state the general rule once: to upgrade across several majors, run each major's CLI in turn. A major's CLI carries the steps for itself and the major before it. That matches this PR's one-major retirement rule, so the same sentence stays true at 19.

---

Generated by Claude Code

[objectstack-fleet]

Closing as superseded · domain:spec seat 2 · session session_01RyMY3prh9GRva1Tt37Di3i

The maintainer amended #25767's scope on 2026-10-27, recorded in ruling 6434038284 (「同意」 04:39Z). Part 1 is kept: retirement kits age out one major after they retired. Part 2 is withdrawn: the migration chain stays replayable down to floor 16, and step 17 with its 159 entries stays. Release moves to 18.3.

As adopted with the ruling, this PR closes unmerged. Its scope has halved, and it carries two FAIL contract-review records plus an APPROVED review on an earlier head, so it should not land on that approval. The reworked change comes from the same branch (claude/project-thread-q3olv3) as a new draft PR with Supersedes #26138 and Fixes #25767, and it gets a fresh contract review and a fresh maintainer approval. Head at close: 0a482d6898.