@@ -0,0 +1,27 @@
+---
+'@objectstack/cli': minor
+'@objectstack/spec': patch
+---
+
+feat(cli)!: the v18 upgrade carries stored comment reactions — `os migrate comment-reactions` turns each reaction stored in the retired `sys_comment.reactions` column into a `sys_comment_reaction` record, and `os migrate apply --allow-destructive` refuses to drop that column until the conversion is verified
+
+Clause-②: no (narrowing) — `os migrate apply --allow-destructive` now refuses the `sys_comment.reactions` drop it accepted before, until a verified conversion is recorded; the conversion itself only writes records of an existing object, so nothing widens.
+
+<!-- adr-0087: not-required (already-registered sys-comment-reactions-column-retired) The narrowed input is the drop of the column that semantic entry retired, and the entry already reaches every upgrading deployment through `os migrate meta` and the upgrade guide. This changeset's prescription (convert, verify, then drop) is carried by that entry: this PR rewrites its replacement, reason and acceptance criteria to name the conversion and order it before the drop, with its id and surface unchanged. No spec key, export or stored shape moves. -->
+
+**BREAKING** (an accept-set narrowing), shipped as `minor` under the launch-window convention for breaking changes.
+
+**What the upgrade now carries.** A database upgraded from 17.x keeps `sys_comment.reactions` and every emoji reaction stored in it (schema sync is additive). Those reactions are no longer lost. `os migrate comment-reactions` converts them into records:
+
+- **One record per stored reaction.** Each (comment, emoji, user) in a stored map becomes one `sys_comment_reaction` row with the same comment, emoji and user, in the comment's organization, owned by the user who reacted. That user can remove it like any reaction made on v18. A user id listed twice under one emoji is one reaction.
+- **Nothing is guessed.** A stored value that is not JSON or not a map of emoji to user-id lists, an entry that is not a user id, an emoji longer than a reaction record holds, and a user id that names no `sys_user` row are each listed in the report with their comment id. Nothing is written for them. The readable entries of the same comment still convert.
+- **Idempotent.** A reaction that already has its record is skipped, so a second run writes nothing, and re-running finishes an interrupted run.
+- **Dry run by default.** `--apply` writes the records, reads the column back, and records the run in `sys_migration`. The run is recorded as verified only when every readable reaction has its record and no stored value is left unreadable. `--json` gives the full report. A run that lists an unreadable value or fails a write exits `1`, and so does an `--apply` run whose read-back finds anything unconverted.
+
+**The column drop waits for the conversion (the narrowing).** Until a verified run is recorded, `os migrate apply --allow-destructive` refuses to drop `sys_comment.reactions` and exits `1` (`--json`: `message: "refused_comment_reactions_unconverted"`, with the recorded run under `conversion`). Nothing else is applied on that run. This also covers the boot drift line, which names that command as the remedy for the orphaned column. What to do when it refuses: run the conversion below until it reports the run verified, then re-run the apply.
+
+**`os migrate apply --json` exits `1` when the `sys_account.issuer` retirement pre-flight refuses.** Its two refusals, `refused_account_issuer_collisions` and `refused_account_issuer_preflight_unreadable`, emitted their document with exit code `0`, so a caller gating on the status read a refused apply as a successful one. They now exit `1`, as the same refusals do without `--json`. The document is unchanged.
+
+**Upgrade order:** take a backup, run `os migrate comment-reactions`, then `os migrate comment-reactions --apply`. If it lists unreadable values, correct each one in the database so it reads as a map of emoji to user ids, or clear it if it holds nothing to keep, and run `--apply` again. Once the run is verified, run `os migrate apply --allow-destructive` to drop the column. Run these with the flags and environment the deployment boots with (an auth secret set), so the audit plugin's objects are composed.
+
+This supersedes the "stored reactions are not migrated" sentence in the entry that retired the column. `@objectstack/spec`: the protocol-18 semantic entry `sys-comment-reactions-column-retired` now names the conversion in its replacement, reason and acceptance criteria, and orders it before the drop. `os migrate meta` and the upgrade guide carry that text. Its id and surface are unchanged.
@@ -1153,6 +1153,7 @@ where the data lives.
 | `os migrate files-to-references` | Convert legacy file-field values to `sys_file` references, verify the ownership ledger, and record the deployment's migration flag |
 | `os migrate value-shapes` | Scan stored reference and structured-JSON field values against the platform's value contract, and record the deployment's migration flag when clean |
 | `os migrate summary-nulls` | Backfill roll-up `count` / `sum` columns still stored as `NULL` on parent rows created before the insert-time seed. Repairs values; no flag, nothing depends on it having run |
+| `os migrate comment-reactions` | Carry the emoji reactions a 17.x deployment stored in the retired `sys_comment.reactions` column into `sys_comment_reaction` records, list every stored value that does not read, and record the verified run that lets `os migrate apply --allow-destructive` drop the column |
 | `os migrate meta --stored` | Replay the metadata conversion chain over this deployment's `sys_metadata` rows and rewrite the ones still carrying a pre-protocol shape. Hygiene, not a gate — nothing depends on it having run |
 | `os migrate security-catalog-overlays` | List the environment-wide permission-set and position rows (the legacy plurals `permissions` / `positions` included) stored over a name a configured package holds — the rows a v18 cold boot refuses — each with the package that holds its name; `--apply` deletes them, one history tombstone per row. Run it before the first v18 boot, with the flags and environment the deployment boots with: the platform security plugin's sets are held only where `os serve` composes it (an auth secret set, and the `auth` tier on), and the step takes `serve`'s `--preset` and `--dev` with `serve`'s meaning. Adopts nothing; exits 1 while it lists a row |
 | `os migrate duplicates` | Report business identifiers already minted twice across the organization partitions, and the rows blocking the boot-time NULL-safe index tightenings — a read-only inventory as JSON on stdout. Renumbers nothing and writes no row and no schema; run it before the boot-time tenancy repair, which overwrites part of the evidence |
@@ -1349,6 +1350,49 @@ A deployment whose database was seeded fresh on this version has nothing to do
 here: its parents were created with the value already in place, and the run
 reports zero.
 
+#### `os migrate comment-reactions`
+
+v18 retired `sys_comment.reactions`, the JSON column that held every emoji
+reaction to a comment as one map of emoji to user ids. A reaction is now its
+reactor's own `sys_comment_reaction` record. Schema sync is additive, so a
+database upgraded from 17.x keeps the column and every reaction stored in it,
+and nothing reads it any more. This command carries those reactions over.
+
+```bash
+os migrate comment-reactions                    # Dry run: full report, writes no rows
+os migrate comment-reactions --apply            # Write the records and record the run (prompts)
+os migrate comment-reactions --apply --yes --json   # CI / scripts
+```
+
+**Each stored reaction becomes one record**: the same comment, emoji and user,
+in the comment's organization, and owned by the user who reacted, so that user
+can remove it like any reaction made on v18. A user id listed twice under one
+emoji is one reaction. **A value that does not read is listed, never guessed
+at**: a value that is not JSON, one that is not a map of emoji to user-id lists,
+an entry that is not a user id, an emoji longer than a reaction record holds, or
+a user id that names no `sys_user` row. Each is reported with its comment id
+and converted into nothing, while the readable entries of the same comment
+still convert. The report quotes up to 200 characters of each value; the column
+keeps the whole of it.
+
+**Idempotent**: a reaction that already has its record is skipped, so a second
+run writes nothing, and re-running is how an interrupted run is finished.
+
+**Convert, verify, then drop.** An `--apply` run reads the column again after
+writing, and records a verified run in `sys_migration` only when every readable
+reaction has its record and no stored value is left unreadable. Until it has,
+`os migrate apply --allow-destructive` refuses to drop `sys_comment.reactions`,
+and says why, because the drop would delete the reactions. The boot's drift
+line names that drop as the remedy for the orphaned column, so following it
+first is safe. When a value is listed as unreadable, correct it in the database
+so it reads as a map of emoji to user ids, or clear it if it holds nothing to
+keep, then run `--apply` again.
+
+A run that lists an unreadable value or fails a write exits `1`, and so does an
+`--apply` run whose read-back finds anything unconverted.
+A database created on v18 never had the column: the run finds nothing, and
+there is no drop to wait for.
+
 #### A database created by this version needs no migration
 
 A deployment whose database the platform **creates from empty** records these
 
@@ -204,7 +204,7 @@
       "title": "os migrate: bare command is a read-only plan, apply is safe-by-default, re-runs are idempotent, and --json exits 0 on success (#4873)",
       "since": "v15",
       "status": "active",
-      "revision": 3,
+      "revision": 4,
       "priority": "P1",
       "surface": "cli",
       "personas": ["operator (local shell)"],
@@ -285,14 +285,17 @@
         "account-issuer",
         "audit-metadata-bodies",
         "multi-value-columns",
-        "unmapped-columns"
+        "unmapped-columns",
+        "organization-ownership",
+        "security-catalog-overlays",
+        "comment-reactions"
       ],
       "traps": ["stale-dist"],
       "automated": { "kind": "unit", "ref": "packages/cli/src/utils/format.exit-code.test.ts" },
       "source": [
         "packages/cli/src/commands/migrate/index.ts + plan.ts (#2186 bare-command-is-plan; #3917 enforced never-mutates; occupancy warning) + apply.ts (--allow-destructive / --force / --yes / in_sync)",
         "packages/cli/src/utils/format.ts#CliExitCode (CliExitCode narrows the emitJson exit slot — the #4873 fix, commit 83df2fd)",
-        "packages/cli/src/commands/migrate/ (the 13 registered subcommands under `os migrate`, besides the bare command, enumerated as variants — oclif pattern strategy, one default-exported Command per non-test file)",
+        "packages/cli/src/commands/migrate/ (the 16 registered subcommands under `os migrate`, besides the bare command, enumerated as variants — oclif pattern strategy, one default-exported Command per non-test file)",
         "sibling item cli.migrate-duplicates-inventory (the duplicates subcommand's own contract — cross-referenced, not duplicated)"
       ],
       "history": [
@@ -303,6 +306,12 @@
           "date": "2026-10-04",
           "change": "A5 / step 4 re-pointed: an in-sync showcase answers in_sync_partial (its federated showcase_external objects have no managed table and are never examined), and plan prints the PARTIAL warning rather than the in-sync line; plain in_sync is the answer only when nothing is unexamined (apply.ts / plan.ts in-sync early returns, schema-migration-plugins.ts coverage). Also the subcommand count: 13 registered under `os migrate`, not nine — the four missing (account-issuer, audit-metadata-bodies, multi-value-columns, unmapped-columns) are added to variants. Stale clause. Source 6c6157af05 (#13057)",
           "ref": "#21735"
+        },
+        {
+          "revision": 4,
+          "date": "2026-10-13",
+          "change": "variants re-measured against the tree: `os migrate --help` lists 16 registered subcommands and the item named 13. Added the three it lacked: organization-ownership, security-catalog-overlays and comment-reactions (the v18 conversion of stored sys_comment.reactions into sys_comment_reaction records, whose verified run `apply --allow-destructive` waits for before dropping the column). The source note's count moves from 13 to 16 with them",
+          "ref": "#23281"
         }
       ]
     },