feat(spec)!: the ADR-0087 migration chain leaves the root entry for @objectstack/spec/migrations (#20646) (#20695)

Fixes #20646

Clause-②: yes (narrowing — the ADR-0087 migration chain and
change-manifest names, 17 values and 16 types, leave the package root
`@objectstack/spec` for the new `@objectstack/spec/migrations` entry;
the conversion layer stays on the root)

This is the source-side payback of the maintainer's ruling on
objectui#11088 (decision 1, letter A: raise the console first-screen
ceiling now, pay it back at the source). It builds the shape the
`domain:spec` seat ruled on the card (comment 5891704646, option A),
under the claim amendment that allows exactly one change to
`migrations/registry.ts`: the generated D3 block for this narrowing's
own ADR-0087 entry.

## Why the root carried the text

`sideEffects: false` was already declared, so it was not the cause. Each
entry ships as one flat module (tsup `splitting: false`). Inside it, a
consumer's bundler has to keep every top-level call it cannot prove
pure, and the migration registry computes things when its module loads:
the list of majors, each step's rationale and step 18's conversion ids.
So the whole registry (mostly the `os migrate meta` guidance text) rode
in every bundle of the root, whatever the consumer imported. Rolldown
(Vite 8's bundler, which the console uses), esbuild and rollup all
agree.

The conversion layer cannot leave the root chunk: `defineStack` and
`normalizeStackInput` call `applyConversions`, which reads
`ALL_CONVERSIONS` at run time. Measured on the round-1 base 0cb72cf,
dropping the conversions re-export as well moved the root by 1,828
bytes. It stays.

## Byte table

Before is the merge base `1a75e39d4a`, built in a separate worktree;
after is this head. Both are tsup JS builds, gzip -9.

| artifact | before (raw / gzip) | after (raw / gzip) |
| --- | --- | --- |
| `dist/index.js` (CommonJS root) | 3,780,033 / 1,067,061 | 2,009,810 /
565,386 (-46.8% raw) |
| `dist/index.mjs` | 3,766,221 / 1,065,949 | 1,996,676 / 564,356 |
| `dist/browser/index.mjs` (the ESM root a browser bundler pulls) |
3,764,293 / 1,065,388 | 1,994,748 / 563,787 |
| console-root probe: rolldown 1.0.3, platform browser, minified; the
entry imports the 10 names objectui's non-test code imports from the
root at the pinned `.objectui-sha` | 2,261,622 / 700,884 | 1,024,463 /
301,287 |
| light-consumer probe: rolldown, the entry imports only
`findClosestMatches` | 2,203,744 / 681,199 | 966,581 / 282,176 |

- **Source-map attribution of the root `index.mjs`:**
`migrations/registry.ts` went from 1,761,987 bytes to 0.
`conversions/registry.ts` stays at 321,050.
- **The new entry:** `dist/migrations/index.js` is 2,280,591 raw /
616,800 gzip. It carries the chain plus the conversion registry it
reads.
- **Console acceptance:** on the console-root probe the payback is
399,597 bytes gzip, against objectui#11088's 413.8 KB overage.
objectui's own eager-closure budget reading is objectui's to take once
its pin moves.

## What changed

- **Root entry:** `packages/spec/src/index.ts` stops re-exporting
`./migrations/index.js`. `packages/spec/package.json` gains the
`./migrations` export (import/require/types, no `browser` condition),
and `tsup.config.ts` gains the entry. `check:browser-reachable-entries`
measured the entry as linking no Node builtin and no server-only
package, so no browser condition is needed.
`browser-reachable-entries.json` lists it under `unjudged`.
- **ADR-0087 D3 entry:** `entries/semantic/18.migrations-entry-split.ts`
(form D, no tracker number), concatenated by `gen:migration-registry`.
The registry diff against the merge base is that block only: 52
insertions, 0 deletions. `conversions/registry.ts` is byte-identical.
`gen:spec-changes` and `gen:upgrade-guide` produce no diff, because
major 18 is not yet in their window.
- **Importers moved to the subpath:**
- the one runtime importer, `packages/cli/src/commands/migrate/meta.ts`;
- four tests: `packages/cli/test/migrate-meta-default-range.test.ts`,
`packages/cli/test/migrate-meta-engine-guidance.test.ts`,
`packages/metadata-protocol/src/protocol.stored-migration.test.ts`, and
`packages/services/service-automation/src/builtin/decision-overlapping-edge-conditions.pin.test.ts`
(only `applyMetaMigrations` moves; `ALL_CONVERSIONS` stays on the root
import).
- This is the complete list: a TypeScript-AST census of every file
naming one of the 53 exports of the two `index.ts` files, covering
static, dynamic, namespace and type imports. Repo gates import the
registry modules by relative path, so none moves. objectui at the pin
imports none of the moved names; `cloud` was not measured.
- **Generated artifacts:** `api-surface/` and `export-origins/` have a
new `migrations.json` shard, and 33 names leave `root.json` in each.
- **Pin:** `packages/spec/src/root-entry-migrations-split.pin.test.ts`
checks four things, each negative with a positive control:
  - the root module exports none of the 17 moved values;
- `./migrations` exports all of them, and nothing it exports is on the
root;
- the root api-surface shard lists none of the 33 names, while the
`migrations` shard lists all of them;
- the root's static value-import graph does not reach `migrations/` at
all (the edge a bundler follows), and the exports map publishes
`./migrations` to the built files.
  No new gate, no byte ceiling.
- **Riders the gates forced** (details in Acceptance notes):
- `content/docs/deployment/troubleshooting.mdx`'s ordered subpath
sentence gains `migrations` (`check:docs-spec-enumerations`).
- `CATEGORY_TITLES.migrations` becomes `Migrations Entry`, following the
`api-assembled` precedent, so the migrations subpath is counted as a
subpath and not as a 16th protocol namespace; the `schema-closure` pin
and its docblock follow.
  - `scripts/export-origins.test.ts`'s entry list gains `./migrations`.
- Stale comments are updated in the `build-migration-registry.ts` header
and the `tsup.config.ts` entry-count note.
- **Changesets:** `@objectstack/spec` `minor` with a BREAKING banner,
the FROM to TO table and the `registered migrations-entry-split`
disposition; `@objectstack/cli` `patch`.

## Verification record

Heads named per reading. The final head is `8558334ab5`, merged with
`origin/main` `1a75e39d4a`.

- **Reverse verification of the pin**, committed first, mutated through
`scripts/ablation-replace.mjs`, at `c4fdf1105e`:
- Mutation: the root re-export was re-added ('mutation landed: anchor 1
to 0').
- Result: the pin went red as predicted, 3 failed / 5 passed of 8. The
failures were: the root exports none of the moved values; nothing
`./migrations` exports is on the root; the root graph does not reach the
registry.
- Restore: 'blob == HEAD (36e34ad) and git diff HEAD is empty'. The
pin is green again, 8/8.
- **Tests:**

  | suite | head | result |
  | --- | --- | --- |
| `@objectstack/spec` local project, full | `c4fdf1105e` | 575 files,
16926 tests passed |
| `@objectstack/spec` repo project, 42 of 43 files | `c4fdf1105e` | 674
tests passed |
| `@objectstack/spec` `build-schemas-check-mode.test.ts`, the four
registry-copying blocks | `c4fdf1105e` | 24 passed |
| pin, `src/migrations`, `export-origins` and `schema-closure` tests |
`8558334ab5` | 206 passed |
| `@objectstack/cli` unit project, full | `c4fdf1105e` | 234 files, 3347
tests passed |
| `@objectstack/cli` integration: the two touched `migrate-meta` files |
`c4fdf1105e` | 10 passed, 1 skipped |
| `@objectstack/metadata-protocol` stored-migration test | `c4fdf1105e`
| 39 passed |
| `@objectstack/service-automation` decision pin | `c4fdf1105e` | 22
passed |
| `@objectstack/runtime` spec-subpath alias-coverage pin | `c4fdf1105e`
| 6 passed |

NOT MEASURED locally: the other 63 tests of
`build-schemas-check-mode.test.ts` (the file alone runs about 14
minutes, past the foreground cap); CI runs it.
- **Typecheck:** `@objectstack/spec` passed at `c1dcebf255`.
`@objectstack/cli`, `@objectstack/metadata-protocol` and
`@objectstack/service-automation` passed at `c4fdf1105e`.
- **Gates:**
- Derived: `node scripts/pm/dispatch-gates.mjs --commands` derives 132
families on the final head. `--ran` reconciles them as 131 run and 1 NOT
MEASURED, with exit codes recorded.
- Heads: gates 1 to 72 of the first derivation ran at `5936236fb7`, 73
to 110 at `c1dcebf255`, and on `8558334ab5` the ratchet and
generated-artifact set was re-run together with the 22 docs families the
docs rider added.
- The four named gates, all exit 0: `check:api-surface`,
`check:published-files`, `check:dual-build-cjs-loads` (105 require entry
points across 66 packages load) and `check:entry-nameability` (494 call
probes across 19 public entries).
- Also exit 0: `check:generated` (all 15 artifacts current),
`check:adr-0087-registration` ('registered migrations-entry-split (new
here)') and `check:browser-reachable-entries`.
- Two reds, both fixed and re-run green: `check:docs-spec-enumerations`
(fixed by the docs rider) and `check:dual-build-cjs-loads` (PREREQUISITE
NOT MET, cleared by a full build).
- NOT MEASURED: `check:pm-dispatch-gates`. Its self-test alone outran
the 590-second foreground cap twice on the shared box, and every case it
printed passed. The diff does not touch `dispatch-gates.mjs`.
- **Lint:** narrowed and proven, at `8558334ab5`:
- Scope: `eslint --no-inline-config --format json` over the 16 changed
`.ts`/`.mjs` files, which is every changed file in eslint's population
(`**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` minus `NEVER_LINTED`).
  - Result: 16 files, 0 errors, 0 warnings.
- Why the narrowing excludes nothing: `eslint.config.mjs` enables no
type-aware linting (no `parserOptions.project`, no typed rules), so this
diff cannot move any untouched file's verdict. The full-tree `pnpm lint`
is CI's.

## Acceptance notes

- **The docs rider is a classification call the reviewer may want to
see.** Keeping `migrations: 'Migrations Protocol'` would have required
listing Migrations as a 16th protocol namespace in the glossary,
`plugins/packages.mdx` and four count claims. I followed the
`api-assembled` precedent instead: a published entry that is not a
metadata protocol domain is titled `Entry`. `schema-closure.test.ts` had
pinned `CATEGORY_TITLES.migrations` to contain `Protocol` as
corroboration that migrations is NOT declared schema-free. That
assertion now pins `toBe('Migrations Entry')` and
`not.toContain('Vocabulary')`. The substantive half,
`schemaClosureAbsenceIsDeclared('migrations') === false`, is untouched.
- **Conversions stay on the root, and they still ride in every root
bundle.** `ALL_CONVERSIONS` is computed at import time
(`conversions/registry.ts`), so the conversion registry (321,050 bytes
of the root) stays in every root bundle, even for a consumer that never
calls `defineStack` or `normalizeStackInput`. On the light-consumer
probe that is about 40 KB gzip. That would need an edit to the
conversion registry, which this card excluded. Carrier: objectui#11101's
seat. Noted, not filed.
- **Upgrade guide:** the D3 entry lands in major 18's `semantic` list.
`spec-changes.json` and the upgrade guide do not project major 18 yet,
so they are unchanged; they pick the entry up when the protocol major
moves.

---
_Generated by [Claude
Code](https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/20646-cli-migrate-meta-migrations-entry.md

@@ -0,0 +1,7 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): `os migrate meta` takes the migration chain from `@objectstack/spec/migrations` (#20646)
+
+`@objectstack/spec` moved the ADR-0087 migration chain and change-manifest names (`applyMetaMigrations`, `composeSpecChanges`, `MigrationFloorError`, `MIGRATION_MAJORS`, `MIGRATION_SUPPORT_FLOOR`, …) off the package root into the new `@objectstack/spec/migrations` entry, so the command now imports them from there. It replays the same chain and prints the same guidance; nothing a user types or reads changes.

.changeset/20646-migrations-entry-split.md

@@ -0,0 +1,49 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: the ADR-0087 migration chain leaves the package root for the new `@objectstack/spec/migrations` entry (#20646)
+
+**BREAKING** — the migration chain and change-manifest names (ADR-0087 D3/D4), with their types, are no longer exported from the package root `@objectstack/spec`. They are exported, unchanged, from the new entry `@objectstack/spec/migrations`.
+
+A `major`-class change — an existing import path stops resolving for these names — recorded as `minor` under the launch-window convention.
+
+**Why.** The migration registry is mostly the guidance text `objectstack migrate meta` prints, and the root re-exported it. The registry does work when its module loads (the list of majors and each step's rationale are computed then), so no bundler could prove it unused, and all of that text rode in every bundle of the root, whatever the consumer imported. This is the source-side payback of the Studio console's first-screen ceiling raise that the maintainer ruled on the 17.5.0 upgrade. Measured on the splitting PR against its merge base `1a75e39d4a` (tsup build, gzip -9):
+
+| | before | after |
+| --- | --- | --- |
+| `dist/index.js` (CommonJS root) | 3,780,033 B / 1,067,061 B gzip | 2,009,810 B / 565,386 B gzip |
+| `dist/browser/index.mjs` (the ESM root a browser bundler pulls) | 3,764,293 B / 1,065,388 B gzip | 1,994,748 B / 563,787 B gzip |
+| a browser bundle of the ten names the Studio console imports from the root (rolldown, minified) | 700,884 B gzip | 301,287 B gzip |
+
+The ADR-0087 **conversion layer stays on the root**: `defineStack` and `normalizeStackInput` read it at run time, so its names (`ALL_CONVERSIONS`, `CONVERSIONS_BY_MAJOR`, `applyConversions`, `applyConversionsToFlow`, `applyConversionsToStoredItem`, `collectConversionNotices`, the `CONVERSION_*_CODE` constants and their types) import from `@objectstack/spec` exactly as before.
+
+### FROM → TO
+
+| removed from `@objectstack/spec` | import instead from |
+| --- | --- |
+| `MIGRATIONS_BY_MAJOR`, `MIGRATION_MAJORS`, `MIGRATION_SUPPORT_FLOOR` | `@objectstack/spec/migrations` |
+| `RETIRED_KEYS_BY_MAJOR`, `RETIRED_DEFS_BY_MAJOR` | `@objectstack/spec/migrations` |
+| `applyMetaMigrations`, `composeMigrationChain`, `MigrationFloorError` | `@objectstack/spec/migrations` |
+| `composeSpecChanges`, `composeReleaseChanges` | `@objectstack/spec/migrations` |
+| `SpecChangesSchema`, `SpecConvertedSchema`, `SpecMigratedSchema`, `SpecSurfaceAddSchema`, `SpecSurfaceRemoveSchema`, `SpecReleaseChangesSchema`, `SpecReleaseSurfaceSchema` | `@objectstack/spec/migrations` |
+| types `MigrationStep`, `MigrationApplication`, `MigrationChainResult`, `MigrationHopResult`, `MigrationTodo`, `SemanticMigration`, `SpecChanges`, `SpecConverted`, `SpecMigrated`, `SpecSurfaceAdd`, `SpecSurfaceRemove`, `SpecReleaseChanges`, `SpecReleaseSurface`, `SurfaceDiff`, `ReleaseSurfaceDiff`, `PreviousReleaseRegistries` | `@objectstack/spec/migrations` |
+
+**The one-line fix: change the import path.**
+
+```ts
+// before
+import { applyMetaMigrations, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec';
+// after
+import { applyMetaMigrations, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec/migrations';
+```
+
+The compiler finds every site: `TS2305` ("Module '"@objectstack/spec"' has no exported member …"); at run time the binding is `undefined`. Nothing else changes: the chain, its steps and semantic entries, the retired-key and retired-def tables and the change-manifest schemas are the same objects, and `objectstack migrate meta` replays the same chain.
+
+⚠️ **Out-of-repo consumers are NOT MEASURED beyond objectui.** Inside this repository the moved names had five importers — `os migrate meta` (the only runtime one) and four tests — all moved in the same PR. objectui at the pinned `.objectui-sha` imports none of the moved names from anywhere. The `cloud` repository was not measured.
+
+The ADR-0087 D3 semantic entry `migrations-entry-split` carries the judgement: an import path is TypeScript source, not metadata, so there is no source a D2 conversion could rewrite.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered migrations-entry-split -->

content/docs/deployment/troubleshooting.mdx

@@ -345,7 +345,7 @@ import { FieldSchema } from '@objectstack/spec/data';
 import { ErrorResponseSchema } from '@objectstack/spec/api';
 ```
 
-Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `api-assembled`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`.
+Available subpaths (the `./*` entries of the package's `exports` map, in its order): `data`, `system`, `kernel`, `ai`, `automation`, `api`, `api-assembled`, `ui`, `contracts`, `integration`, `security`, `studio`, `marketplace`, `qa`, `identity`, `shared`, `meta-spelling`, `migrations`.
 
 ---
 

packages/cli/src/commands/migrate/meta.report-order.test.ts

@@ -35,15 +35,13 @@
 
 import { stripVTControlCharacters } from 'node:util';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ObjectStackDefinitionSchema, formatZodIssue, normalizeStackInput } from '@objectstack/spec';
 import {
-  ObjectStackDefinitionSchema,
   applyMetaMigrations,
-  formatZodIssue,
-  normalizeStackInput,
   MIGRATION_MAJORS,
   MIGRATION_SUPPORT_FLOOR,
   type MigrationChainResult,
-} from '@objectstack/spec';
+} from '@objectstack/spec/migrations';
 import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
 import { printMigrationReport, type MigrationReport } from './meta.js';
 

packages/cli/src/commands/migrate/meta.ts

@@ -5,17 +5,15 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import chalk from 'chalk';
+import { ObjectStackDefinitionSchema, formatZodIssue, normalizeStackInput } from '@objectstack/spec';
 import {
-  ObjectStackDefinitionSchema,
   applyMetaMigrations,
   composeSpecChanges,
-  formatZodIssue,
-  normalizeStackInput,
   MigrationFloorError,
   MIGRATION_MAJORS,
   MIGRATION_SUPPORT_FLOOR,
   type MigrationChainResult,
-} from '@objectstack/spec';
+} from '@objectstack/spec/migrations';
 import { PROTOCOL_MAJOR, PROTOCOL_VERSION } from '@objectstack/spec/kernel';
 import { FILE_REFERENCE_TYPES, REFERENCE_VALUE_TYPES, STRUCTURED_JSON_TYPES } from '@objectstack/spec/data';
 import { FILE_REFERENCES_MIGRATION_ID, VALUE_SHAPES_MIGRATION_ID } from '@objectstack/spec/system';

packages/cli/test/migrate-meta-default-range.test.ts

@@ -51,7 +51,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { MIGRATIONS_BY_MAJOR, MIGRATION_MAJORS, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec';
+import { MIGRATIONS_BY_MAJOR, MIGRATION_MAJORS, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec/migrations';
 import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
 import { childEnv } from './helpers/serve-process.js';
 

packages/cli/test/migrate-meta-engine-guidance.test.ts

@@ -59,7 +59,7 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { MIGRATIONS_BY_MAJOR, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec';
+import { MIGRATIONS_BY_MAJOR, MIGRATION_SUPPORT_FLOOR } from '@objectstack/spec/migrations';
 import { childEnv } from './helpers/serve-process.js';
 
 const execFileP = promisify(execFile);

packages/metadata-protocol/src/protocol.stored-migration.test.ts

@@ -26,7 +26,7 @@ import { describe, expect, it } from 'vitest';
 // of this package's (file, verb) pairs sat in the gate's DEBT ledger until
 // #5619 sank the two predicates into a package both sides already depend on.
 import { assertEngineDeleteDispatch, assertEngineUpdateDispatch, assertEngineFindOnePredicate } from '@objectstack/metadata-core';
-import { applyMetaMigrations } from '@objectstack/spec';
+import { applyMetaMigrations } from '@objectstack/spec/migrations';
 import { ObjectStackProtocolImplementation } from './protocol.js';
 import {
     DECISION_MODE_REVIEW_CONVERSION_ID,

packages/services/service-automation/src/builtin/decision-overlapping-edge-conditions.pin.test.ts

@@ -1,7 +1,8 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { ALL_CONVERSIONS, applyMetaMigrations } from '@objectstack/spec';
+import { ALL_CONVERSIONS } from '@objectstack/spec';
+import { applyMetaMigrations } from '@objectstack/spec/migrations';
 import { AutomationEngine } from '../engine.js';
 import { registerLogicNodes } from './logic-nodes.js';
 

packages/spec/api-surface/migrations.json

@@ -0,0 +1,39 @@
+{
+  "description": "Every exported `name (kind)` of one published entry point of @objectstack/spec — the breadth half of the ADR-0059 backward-compatibility gate. Sharded by entry point (#5837) so two PRs touching different entry points never share a file. Reads the BUILT dist/*.d.ts: regenerate with `pnpm --filter @objectstack/spec gen:api-surface` after a real build.",
+  "entry": "./migrations",
+  "exports": [
+    "MIGRATIONS_BY_MAJOR (const)",
+    "MIGRATION_MAJORS (const)",
+    "MIGRATION_SUPPORT_FLOOR (const)",
+    "MigrationApplication (interface)",
+    "MigrationChainResult (interface)",
+    "MigrationFloorError (class)",
+    "MigrationHopResult (interface)",
+    "MigrationStep (interface)",
+    "MigrationTodo (interface)",
+    "PreviousReleaseRegistries (interface)",
+    "RETIRED_DEFS_BY_MAJOR (const)",
+    "RETIRED_KEYS_BY_MAJOR (const)",
+    "ReleaseSurfaceDiff (interface)",
+    "SemanticMigration (interface)",
+    "SpecChanges (type)",
+    "SpecChangesSchema (const)",
+    "SpecConverted (type)",
+    "SpecConvertedSchema (const)",
+    "SpecMigrated (type)",
+    "SpecMigratedSchema (const)",
+    "SpecReleaseChanges (type)",
+    "SpecReleaseChangesSchema (const)",
+    "SpecReleaseSurface (type)",
+    "SpecReleaseSurfaceSchema (const)",
+    "SpecSurfaceAdd (type)",
+    "SpecSurfaceAddSchema (const)",
+    "SpecSurfaceRemove (type)",
+    "SpecSurfaceRemoveSchema (const)",
+    "SurfaceDiff (interface)",
+    "applyMetaMigrations (function)",
+    "composeMigrationChain (function)",
+    "composeReleaseChanges (function)",
+    "composeSpecChanges (function)"
+  ]
+}