fix(cli): the multi-value-columns help, the occupancy changeset and the read-only arms' comments say no row instead of nothing

Patch round 1: the help description of os migrate multi-value-columns and the
unreleased occupancy-gate changeset's plan sentence say the run writes no row
or table; developer comments in the touched arms that said a dry run or plan
writes nothing say it writes no row.

Claude-Session: https://claude.ai/code/session_01Q9PZ5Pzqcus4woVvTZwWNU
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/23400-ownership-occupancy-gate.md

@@ -12,7 +12,7 @@ Clause-②: no (narrowing)
 
 **FROM.** `os migrate organization-ownership --apply` opened a SQLite database that another process held open (a running `os dev` or `os serve`, or a runtime's pooled connection) without checking for it, and ran the ceremony beside that process. `os migrate apply` and the other data migrations probe the database first; this command did not. One measured run of the plan and then `--apply` beside a runtime holding a connection left that runtime writing to a deleted `-wal` file, and a row it wrote afterwards never reached the database.
 
-**TO.** Before it boots the stack, the command probes the database the way its siblings do. Beside a holder, `--apply` is refused with exit 1: the ceremony boots nothing and writes nothing (the probe itself opens the file only briefly, to check). The check runs first, so a busy `--apply` that also lacks its plan file or its backup acknowledgement answers reason `database-busy` rather than `plan-file-required` or `backup-unacknowledged`; it is refused either way. The text output names the file and, when the probe can tell, the process holding it, then the remedy: stop the process using it and re-run. With `--json` the refusal uses this command's own envelope: `{ "error": "apply_refused", "reason": "database-busy", "database", "signal", "detail", "hint" }`. There is no `--force`: the ceremony has no flag that skips its reviewed plan or its backup either, and its refusal never names one. The plan (no `--apply`) writes nothing, so it still runs. Its text output warns that `--apply` will refuse until the database is free, and its `--json` document is unchanged.
+**TO.** Before it boots the stack, the command probes the database the way its siblings do. Beside a holder, `--apply` is refused with exit 1: the ceremony boots nothing and writes nothing (the probe itself opens the file only briefly, to check). The check runs first, so a busy `--apply` that also lacks its plan file or its backup acknowledgement answers reason `database-busy` rather than `plan-file-required` or `backup-unacknowledged`; it is refused either way. The text output names the file and, when the probe can tell, the process holding it, then the remedy: stop the process using it and re-run. With `--json` the refusal uses this command's own envelope: `{ "error": "apply_refused", "reason": "database-busy", "database", "signal", "detail", "hint" }`. There is no `--force`: the ceremony has no flag that skips its reviewed plan or its backup either, and its refusal never names one. The plan (no `--apply`) writes no row or table, so it still runs. Its text output warns that `--apply` will refuse until the database is free, and its `--json` document is unchanged.
 
 **Unchanged.** A PostgreSQL, MySQL or remote libSQL target is not probed. A probe that cannot tell (for example, the database file cannot be read) warns in the text output and proceeds; under `--json` it is silent. The probe reads the project's `.env` files, as the run itself does.
 

.changeset/23562-read-only-arms-journal-mode-note.md

@@ -6,13 +6,14 @@ fix(cli): the read-only `os migrate` arms say they write no row or table, and th
 
 **What was wrong.** These arms boot read-only: no DDL, no seed, SELECT statements only. But the boot still opens the database through the SQL driver, and the driver's connect switches a SQLite file to the journal mode it asks for: WAL, unless `OS_DATABASE_SQLITE_JOURNAL_MODE=delete` is set in the command's own environment or the project's `.env` (then a WAL file is switched back to a rollback journal). On a file still on a rollback journal, a plan or a dry run therefore rewrote the file's header (the journal-mode bytes and the change counter) while saying "writes nothing" or "nothing in the database was changed". No row or table changed, and nothing was lost.
 
-**What changed.** Each sentence below now claims no row or table, and is followed by one shared note: "Opening a SQLite file can still switch its journal mode (to WAL by default), which changes its header only."
+**What changed.** Each sentence below now claims no row or table, and each warning is followed by one shared note: "Opening a SQLite file can still switch its journal mode (to WAL by default), which changes its header only."
 
 - `os migrate organization-ownership` (the plan), beside a process holding the file. FROM: "The plan below writes nothing, but --apply will refuse until the database is free." This sentence has not been published: it arrives in this same release, with the occupancy gate the ceremony's `--apply` now takes. TO: "The plan below writes no row or table, but --apply will refuse until the database is free." and the note.
 - Its closing line. FROM: "Plan written to FILE — nothing in the database was changed." TO: "Plan written to FILE — no row or table in the database was changed." On a SQLite target the note follows; on PostgreSQL or MySQL the line ends there.
 - `os migrate plan`, beside a holder. FROM: "The plan below is still accurate — nothing is written — but "os migrate apply" will refuse until it is free (or you pass --force)." TO: "The plan below is still accurate — it writes no row or table — but …", the rest unchanged, and the note.
 - The dry runs of `os migrate audit-metadata-bodies`, `comment-reactions`, `files-to-references` and `summary-nulls`, beside a holder. FROM: "The dry run below writes nothing, but its counts may shift while that process is running." TO: "The dry run below writes no row or table, but its counts may shift while that process is running." and the note.
 - The dry run of `os migrate multi-value-columns`, beside a holder. FROM: "The dry run below writes nothing." TO: "The dry run below writes no row or table." and the note.
+- The help description of `os migrate multi-value-columns` (`os migrate multi-value-columns --help`). FROM: "… Dry-run by default: prints the exact statements and the database they would run against, and writes nothing." TO: "… and writes no row or table." The help text carries no note.
 - The preview of `os migrate meta --stored`, beside a holder. FROM: "The preview below writes nothing, but a live process may be saving metadata while it runs." TO: "The preview below writes no row or table, but a live process may be saving metadata while it runs." and the note.
 
 **Unchanged.** No exit code, `--json` document or refusal changes; the warnings are still printed in the text output only. What the driver does on connect is unchanged: once a file is in the mode the driver asks for, a read-only run leaves it byte-identical.

packages/cli/src/commands/migrate/audit-metadata-bodies.ts

@@ -54,7 +54,7 @@ async function confirm(question: string): Promise<boolean> {
  * withholds the hashes in those notes, in the same pass. Operators run it once
  * after upgrading, dry run first.
  *
- * Dry run by default (writes nothing), `--apply` to rewrite. Idempotent: a
+ * Dry run by default (writes no row), `--apply` to rewrite. Idempotent: a
  * second run finds nothing — a redacted copy has no credential and no hash
  * left — so re-running and reading a clean report is the verification. No
  * `sys_migration` flag is recorded: nothing gates irreversible behaviour on this

packages/cli/src/commands/migrate/files-to-references.ts

@@ -95,7 +95,7 @@ async function confirm(question: string): Promise<boolean> {
  * platform version) is what later opens released-file collection (#3459) and
  * strict media value-shape enforcement (#3438) on this deployment.
  *
- * Dry run by default, and a dry run writes NOTHING — not conversions, not the
+ * Dry run by default, and a dry run writes NO ROW — not conversions, not the
  * flag. Not run / not passed → files keep being retained forever: storage
  * cost, zero data loss.
  *
@@ -188,7 +188,7 @@ export default class MigrateFilesToReferences extends Command {
       return;
     }
     if (occupancy.status === 'busy' && !flags.json) {
-      // A dry run writes nothing, so it only ever warns — but it warns, because
+      // A dry run writes no row, so it only ever warns — but it warns, because
       // the numbers it reports are a moving target while another process writes.
       printWarning(apply
         ? `--force: ${describeOccupancy(occupancy)} Converting anyway — the live process may write records mid-scan.`

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

@@ -1486,7 +1486,7 @@ export default class MigrateMeta extends Command {
       // takes. A plain boot runs schema sync and the artifact's inline seed
       // loader, and the seed upserts every seeded row of the app's tables
       // (`updated_at` bumped, `organization_id` stamped, relative-date values
-      // re-evaluated) before the report says "writes nothing". `deferSchemaDdl`
+      // re-evaluated) before the report says "writes no row". `deferSchemaDdl`
       // holds the DDL back and suppresses the seed; `readOnlyProbe` keeps a
       // missing sqlite file from being created. `--apply` keeps the plain boot:
       // it is the writing mode, and its behaviour is unchanged.

packages/cli/src/commands/migrate/multi-value-columns.ts

@@ -331,7 +331,7 @@ export default class MigrateMultiValueColumns extends Command {
   static override description =
     'Migrate a stale varchar/text column to json where the field declares multiple: true; boot and ' +
     'os migrate plan only report such a column and never alter it unattended. ' +
-    'Dry-run by default: prints the exact statements and the database they would run against, and writes nothing.';
+    'Dry-run by default: prints the exact statements and the database they would run against, and writes no row or table.';
 
   static override examples = [
     '$ os migrate multi-value-columns',

packages/cli/src/commands/migrate/organization-ownership.ts

@@ -72,9 +72,9 @@ async function confirm(question: string): Promise<boolean> {
  * The boot is the family's read-only boot (`deferSchemaDdl` + `readOnlyProbe`:
  * no DDL, no seed, no database file brought into existence), and the plan
  * itself issues SELECT statements only (`../../utils/organization-ownership-plan.ts`).
- * The one thing it writes is the plan FILE, on the operator's disk, which the
- * ADR asks for: "the plan is written to a file the operator keeps". It never
- * overwrites one — a kept plan is evidence.
+ * It writes no row or table; the one thing it writes is the plan FILE, on the
+ * operator's disk, which the ADR asks for: "the plan is written to a file the
+ * operator keeps". It never overwrites one — a kept plan is evidence.
  *
  * ## Refusal
  *

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

@@ -52,7 +52,7 @@ import {
  * boot-time create-table / add-column sync that used to run before this command
  * printed a single line is now REPORTED as pending work instead of performed.
  * A database another process is using is reported too — as a warning, not a
- * refusal, since a plan writes nothing either way.
+ * refusal, since a plan writes no row either way.
  *
  * Since #6743 the dry run also stops short of CREATING the database. The
  * deferral #3917 introduced covered the DDL and the seed but not the open
@@ -140,7 +140,7 @@ export default class MigratePlan extends Command {
         jsonOutput: flags.json,
         databaseUrl: flags['database-url'],
         deferSchemaDdl: true,
-        // A plan writes nothing — so it must not bring a database file into
+        // A plan writes no row — so it must not bring a database file into
         // existence either (#6743). On a never-started project the target is
         // opened as an empty in-memory database: the plan below is unchanged
         // (an empty database is an empty database), and no file, `-wal` or

packages/cli/src/commands/migrate/summary-nulls.ts

@@ -51,7 +51,7 @@ async function confirm(question: string): Promise<boolean> {
  * A freshly seeded database has no such rows; this command is for the other
  * kind, and is needed exactly once per deployment.
  *
- * Dry run by default (writes nothing at all), `--apply` to backfill. Each
+ * Dry run by default (writes no row at all), `--apply` to backfill. Each
  * `NULL` row is RECOMPUTED — a pre-upgrade parent that has children is `NULL`
  * too and its correct value is the real aggregate, so writing 0 everywhere
  * would swap a missing value for a wrong one. Idempotent: a second run finds