docs(cli): the read-only data commands' missing-table edge, and the changeset

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016GiHYRmLSNWTfbX9gVQkpz

Author: claude

.changeset/21529-absent-database-empty-work.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/cli": patch
+"@objectstack/runtime": patch
+---
+
+`os migrate resume`, `os migrate recorded-by` and `os migrate value-shapes` answer a project whose database does not exist yet with empty work and exit 0, instead of exiting 1 with "The database refused to run this query" (#21529)
+
+Clause-②: no
+
+Each of these commands boots read-only by default: the schema sync is held back, and a missing SQLite file is opened as an empty in-memory stand-in. That boot already measures which tables the database lacks, because the held-back sync lists each one as a table to create. Each command then read the very tables it had just found missing. On a never-booted database (or a `--database-url` that points at one), every default run failed:
+
+- `os migrate resume` exited 1, naming `sys_migration_journal`;
+- `os migrate recorded-by` exited 1, naming `sys_metadata_history`;
+- `os migrate value-shapes` reported every scanned object as unreadable, kept the gate closed and exited 1, over data that does not exist.
+
+Each command now reads only the tables its boot found present. A table that does not exist holds nothing, so:
+
+- `os migrate resume` lists no interrupted runs (`{"interrupted": [], "count": 0}`), exit 0;
+- `os migrate recorded-by` reports `pending: 0`, nothing to convert, exit 0;
+- `os migrate value-shapes` completes a clean scan of zero records, exit 0, and names the objects it did not read because they have no table yet (on stderr under `--json`).
+
+Human mode says the table is not there yet, instead of implying the command looked through one. `--json` documents have the same shape as on a booted database with nothing to do. The write modes (`--run`, `--apply`) are unchanged: they boot with the schema sync, so their tables exist before they read.
+
+`MigrationRecoveryPlugin` (`@objectstack/runtime`), which every one of these boots composes, scans the migration journal at boot. On such a database it logged "Migration journal scan failed; interrupted migrations (if any) were NOT detected" on every run. It now treats a missing journal table as "no runs" and says nothing. It recognises that case only with the shared `isMissingTableError` predicate, asked about `sys_migration_journal` itself. Any other failure of the scan still warns.
+
+There is nothing to migrate.

content/docs/deployment/cli.mdx

@@ -1053,10 +1053,14 @@ your app to read its metadata. Without `--apply`, that boot is read-only, the sa
 loaded, and a SQLite file that does not exist is not created. With `--apply`, the boot
 creates missing tables and columns so the migration has somewhere to write, but it
 still loads no seed data: the only rows that change are the migration's own.
-One edge follows from the read-only boot. A dry run pointed at a database that lacks a
-table it reads (a never-booted database, or the wrong `--database-url`) can fail and exit
-1, naming the table, where it used to create the table and report nothing to do. Point
-`--database-url` at the deployment's database, or boot the deployment once first.
+One edge follows from the read-only boot: it finds out which tables the database lacks
+(a never-booted database, or the wrong `--database-url`) instead of creating them.
+`os migrate value-shapes` does not read a table it found missing, since that table
+holds nothing: the scan is clean over zero records, exits 0, and names the objects it
+did not read. `os migrate recorded-by` and `os migrate resume` answer the same way
+(nothing to convert, no interrupted runs). Another dry run that reads a missing table
+can still fail and exit 1, naming the table. Point `--database-url` at the
+deployment's database, or boot the deployment once first.
 
 ```bash
 os migrate files-to-references            # Dry run: full report, writes nothing