@@ -71,7 +71,7 @@ node -e "console.log(require('fs').readFileSync(require.resolve('@objectstack/sp
 # 3 · acceptance — all four, not three
 os validate                      # green (compare against validate-before.txt)
 tsc --noEmit                     # tombstones type the retired keys as `never`
-os migrate meta --from 17 --json # `applied` must be [] (see §3.3)
+os migrate meta --from 16 --to 18 --json   # `applied` [] and no `replayedNothing` (see §3.3)
 # → write .upgrade/REPORT.md (template in §3.4)
 ```
 
@@ -159,8 +159,6 @@ it prints:
   Layer 2's input, not a warning to dismiss.
 - **`Migrated stack is schema-valid`** — or the warning that it is not yet,
   which means a residue item is still blocking the parse.
-- **Pending data migrations**, when the chain crosses into a major with
-  per-deployment data gates — see below.
 
 ### ⚠ The one fact that surprises every operator
 
@@ -391,22 +389,25 @@ that output as the control.
 > Some conversions are **migration-chain-only**: the loader deliberately does
 > not apply them and no tombstone rejects the old shape, because the change is a
 > default flip rather than a rename — auto-applying it would stamp a constraint
-> onto sources that deliberately omit it. The 16 → 17 crossing has one:
-> `field-required-notnull-explicit`, which writes the physical `storage.notNull`
-> that `required` used to imply on its own.
+> onto sources that deliberately omit it. This build ships none (every
+> conversion it carries is tombstoned, so the parse refuses the old shape too),
+> but a later one can, and the chain, not the parse, is what knows.
 >
-> A project carrying only that shape validates **green** while the chain still
+> A project carrying only such a shape validates **green** while the chain still
 > has work. So `validate` green is necessary and not sufficient, and the
-> criterion that closes the gap is the replay:
+> criterion that closes the gap is a replay of the whole range you ported:
 >
 > ```bash
-> os migrate meta --from <target-major> --json   # `applied` must be []
+> os migrate meta --from <authored-major> --to <target-major> --json
+> # `applied` must be [] and `replayedNothing` absent
 > ```
 >
-> Read `applied`, not the headline: `--to` defaults to the highest major this
-> build carries a step for, which is one PAST the installed major for most of a
-> release line, so `todos` carries the next major's semantic residue — real, but
-> not this upgrade's business.
+> `--from <target-major>` proves nothing: `--to` defaults to the highest major
+> this build carries a step for, so the range is empty — no step runs, `applied`
+> is `[]` whatever the metadata holds, and the JSON says so with
+> `replayedNothing` (its `widestRange` is `null` there: no wider range exists
+> from that `--from`) — or it holds only the next major's step. `todos` is
+> semantic residue, Layer 2's business, not a failure.
 
 → Moved verbatim to [references/examples-upgrade.md](./references/examples-upgrade.md) § 3.4 The report — the human half.
 
@@ -434,7 +435,7 @@ got — "it passed" is a different fact in every row:
 |:--|:--|:--|
 | Rejected, error carries the fix-it text | A tombstoned key. Not "unrecognized key", not a deprecation label — the prescription *is* the error. | The refusal itself, quoted. |
 | Accepted, and the chain rewrites it | A conversion with a live load-path acceptance window. | The chain's diff — not the parse gate. |
-| Accepted, and `validate` stays green | A migration-chain-only conversion ([3.3](#33-validate)). | Only the replay from the target major sees this class. |
+| Accepted, and `validate` stays green | A migration-chain-only conversion ([3.3](#33-validate)). | Only the acceptance replay sees this class. |
 
 ### 3.6 Stored rows: assert them, do not believe them
 
@@ -460,10 +461,9 @@ recognises it and answers `0`. Nothing gates on it having run.
 
 | Symptom | What it actually is | Fix |
 |:--|:--|:--|
-| `migrate meta` reports changes, but the files are unchanged | Working as designed — the default run only lists. | Pass `--write`, or port the printed edits by hand; then replay from the target major to confirm 0 changes. |
-| Replay from the target major still applies changes | The port is incomplete, or a source builds metadata at runtime from a shape the chain never saw. | Diff against `--out`; grep for the `conversionId`'s surface in code that constructs metadata dynamically. |
+| `migrate meta` reports changes, but the files are unchanged | Working as designed — the default run only lists. | Pass `--write`, or port the printed edits by hand; then replay the ported range to confirm 0 changes. |
+| The acceptance replay still applies changes | The port is incomplete, or a source builds metadata at runtime from a shape the chain never saw. | Diff against `--out`; grep for the `conversionId`'s surface in code that constructs metadata dynamically. |
 | `validate` green, but a feature silently stopped working | An R2 residue item: code reading a renamed key now reads `undefined`. | Exercise the path for real. A green parse says nothing about a `??` chain in the project's own code. |
-| `validate` green from the start, so "there was nothing to upgrade" | A migration-chain-only conversion — no tombstone rejects it, so nothing complains. | Replay the chain anyway. `validate` green is necessary, not sufficient; see [3.3](#33-validate). |
 | `validate` reports findings that have nothing to do with retired keys | The author-time rule pass, not the schema pass. | Diff against the pre-upgrade `validate` control. Pre-existing findings are not this upgrade's scope. |
 | A retired key round-trips without error | The schema carrying it is not strict and the key is being stripped, or the key still has a live load-path window. | Determine which — the two need different acceptance evidence. See [the reverse check](#reverse-check). |
 | `--apply` refused / stored-only flag rejected | `--apply`, `--yes`, `--force`, `--type`, `--database-url` mean something only with `--stored`. | Add `--stored`, or drop the flag; the authored-source chain writes only `--out` and, with `--write`, the sources. |
 
@@ -4,7 +4,7 @@
     {
       "id": 1,
       "prompt": "把这个项目升级到 v17。objectstack.config.ts 的 manifest 里写着 engines: { protocol: '^16' }。",
-      "expected_output": "Preflight: `--from 16` read off `manifest.engines.protocol` (the floor of the range, never guessed from the installed spec); keep `os validate > .upgrade/validate-before.txt` as the control. Mechanical: `os migrate meta --from 16 --step`, `--json`, and `--out .upgrade/migrated.stack.json` — the command rewrites nothing on disk, so port the printed `path: from → to (conversionId)` edits into the sources, one `conversionId` per commit, then replay `os migrate meta --from 17 --json` until `applied` is `[]`. Acceptance: `os validate` green, `tsc --noEmit` green, and `.upgrade/REPORT.md` with the mechanical table, decided residue, open decisions and pending per-deployment gates.",
+      "expected_output": "Preflight: `--from 16` read off `manifest.engines.protocol` (the floor of the range, never guessed from the installed spec); keep `os validate > .upgrade/validate-before.txt` as the control. Mechanical: `os migrate meta --from 16 --step`, `--json`, and `--out .upgrade/migrated.stack.json` — the command rewrites nothing on disk, so port the printed `path: from → to (conversionId)` edits into the sources, one `conversionId` per commit, then replay the ported hop, `os migrate meta --from 16 --to 17 --json`, until `applied` is `[]` with no `replayedNothing` (`--from 17` names an empty range and checks nothing). Acceptance: `os validate` green, `tsc --noEmit` green, and `.upgrade/REPORT.md` with the mechanical table, decided residue, open decisions and pending per-deployment gates.",
       "files": [],
       "assertions": {
         "must_contain": ["os migrate meta --from 16", "--out", "tsc --noEmit", "REPORT.md", "applied"],
@@ -34,10 +34,10 @@
     {
       "id": 4,
       "prompt": "We bumped @objectstack/spec 16 → 17 and `os validate` is green, so there was nothing to upgrade, right? Production also has `sys_metadata` rows written under 16.",
-      "expected_output": "No: `validate` green is necessary, not sufficient — migration-chain-only conversions (16 → 17 has `field-required-notnull-explicit`) reject nothing at parse. Replays `os migrate meta --from 17 --json` and reads `applied` (must be `[]`). Stored rows rehydrate through `applyConversionsToStoredItem` only while the installed release carries their conversions (18.3 drops those retired at or below 16.x), so before moving past 18.2 it runs `os migrate meta --stored` (read-only) then `os migrate meta --stored --apply --yes` (`--yes` is mandatory in a non-TTY), and never hand-edits `sys_metadata`. Any per-deployment data-migration gates the run prints go into the report as pending, by name.",
+      "expected_output": "No: `validate` green is necessary, not sufficient — migration-chain-only conversions reject nothing at parse (this build ships none, but the chain, not the parse, is the authority). Replays the ported hop, `os migrate meta --from 16 --to 17 --json`, and reads `applied` (must be `[]`) with `replayedNothing` absent — `--from 17` alone names an empty range, so its `applied: []` proves nothing. Stored rows rehydrate through `applyConversionsToStoredItem` only while the installed release carries their conversions (18.3 drops those retired at or below 16.x), so before moving past 18.2 it runs `os migrate meta --stored` (read-only) then `os migrate meta --stored --apply --yes` (`--yes` is mandatory in a non-TTY), and never hand-edits `sys_metadata`. Any per-deployment data-migration gates the run prints go into the report as pending, by name.",
       "files": [],
       "assertions": {
-        "must_contain": ["applied", "--stored", "--yes", "field-required-notnull-explicit", "applyConversionsToStoredItem"],
+        "must_contain": ["applied", "replayedNothing", "--stored", "--yes", "applyConversionsToStoredItem"],
         "must_not_contain": ["UPDATE sys_metadata"]
       }
     },
 
@@ -45,13 +45,13 @@ maintainer can read in five minutes and a year from now. Write
 
 **Status:** complete | complete with N open decisions
 **Spec:** <installed @objectstack/spec version>  ·  **Chain:** 16 → 18
-**Verified:** `os validate` green · `tsc --noEmit` green · replay-from-17 applies 0 mechanical changes
+**Verified:** `os validate` green · `tsc --noEmit` green · replay 16 → 18 applies 0 mechanical changes
 
 ## 1 · Mechanical (applied by the chain)
 
 | Site | Change | Conversion |
 |:--|:--|:--|
-| `objects[crm_lead].fields.name` | `required: true` → `+ storage.notNull: true` | `field-required-notnull-explicit` |
+| `sharingRules[0].accessLevel` | `'full'` → `'edit'` | `sharing-rule-access-level-full-to-edit` |
 | … | | |
 
 _N sites, M conversions. Ported into sources from `os migrate meta --out`._