no-mistakes(document): Docs updated for shadow-db drift path: CLI README, CHANGELOG 1.2.0 heading, drift table row.

Author: dmealing

CHANGELOG.md

@@ -8,7 +8,7 @@ promises the **software** surface, `metamodelVersion` promises the **metadata**
 `^1.0.0` accepts a MINOR — so **a release that moves `metamodelVersion` says so in its entry
 here.**
 
-## [Unreleased]
+## [1.2.0] — Unreleased
 
 ### Docs
 

docs/features/migrations-and-drift.md

@@ -13,7 +13,7 @@ There are **7 drift sources**, and the toolchain has a guard for each.
 |---|---|---|
 | **Code-vs-DB** | Codegen — the generated SQL DDL is emitted from the same metadata as the entity / table code. | Build time |
 | **Code-vs-API-doc** | Cross-port codegen from the same metadata. | Build time |
-| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. Includes modeled projection **view bodies** (a changed `CREATE VIEW` is drift, reported with what differs: the first differing excerpt of the text on SQLite/D1, a fingerprint mismatch on Postgres). A view `meta migrate` drops and recreates only because the migration alters a table it reads, with its definition unchanged, is not drift and is not reported; a hand-authored *unmodeled* view is unmanaged and never flagged. A schema concern owned by the Node toolchain regardless of server language; on the JVM ports the runtime auto-create/validator path was removed (ADR-0015) and the `metaobjects:verify` Maven goal is not available. Cloudflare D1 has no client wire protocol, so it can't go through `--db`'s Kysely-driver introspection — use `meta verify --dialect d1 [--d1 <binding>] [--remote]` instead (the same wrangler-shelled-out path `meta migrate --dialect d1` uses); `--remote` is required to check the *deployed* database, not the local `wrangler dev` shadow copy. Pointing `--db file:` at wrangler's local D1 state directory (`.wrangler/state/**/d1/**`) still runs, but only verifies that local copy — `verify` warns when it detects this. | CI on every PR |
+| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. Includes modeled projection **view bodies** (a changed `CREATE VIEW` is drift, reported with what differs: the first differing excerpt of the text on SQLite/D1, the deparsed body on Postgres's scratch-database path, a fingerprint mismatch otherwise). A view `meta migrate` drops and recreates only because the migration alters a table it reads, with its definition unchanged, is not drift and is not reported; a hand-authored *unmodeled* view is unmanaged and never flagged. A schema concern owned by the Node toolchain regardless of server language; on the JVM ports the runtime auto-create/validator path was removed (ADR-0015) and the `metaobjects:verify` Maven goal is not available. Cloudflare D1 has no client wire protocol, so it can't go through `--db`'s Kysely-driver introspection — use `meta verify --dialect d1 [--d1 <binding>] [--remote]` instead (the same wrangler-shelled-out path `meta migrate --dialect d1` uses); `--remote` is required to check the *deployed* database, not the local `wrangler dev` shadow copy. Pointing `--db file:` at wrangler's local D1 state directory (`.wrangler/state/**/d1/**`) still runs, but only verifies that local copy — `verify` warns when it detects this. | CI on every PR |
 | **Migration-vs-metadata** | The Node `meta migrate` emits migrations FROM metadata diffs — they cannot drift from metadata by construction. Schema migrations for **every** port are owned by this Node toolchain (`@metaobjectsdev/cli migrate`, ADR-0015); the C# and Python migrate surfaces were removed. | Build time |
 | **Generated-edited** | `@generated` headers in emitted code + a committed hash manifest that refuses an edited file by name; in TypeScript only, a three-way merge also preserves hand-edits on the machine that generated the file. | Code review |
 | **Prompt-vs-payload** | FR-004 `Renderer.verify` parses `{{...}}` references in templates and checks each one exists on the payload VO. | Build time + runtime |

server/typescript/packages/cli/README.md

@@ -173,6 +173,7 @@ Flags:
 - `--db <url>` (required or via `$DATABASE_URL` or `.metaobjects/config.json`)
   - Supported schemes: `file:`, `libsql:`, `postgres:`, `postgresql:`
 - `--dialect sqlite|postgres|d1` — auto-detected from URL scheme; use `d1` for Cloudflare D1
+- `--shadow-db <url>` — Postgres scratch database the expected schema is applied to for `--from-db` / `--apply` drift (also `SHADOW_DATABASE_URL` or `migrate.shadowDatabaseUrl`). Read [How CHECK constraints and expression indexes are compared](../../../../docs/features/migrations-and-drift.md#how-check-constraints-and-expression-indexes-are-compared) for the three paths.
 - `--out-dir <path>` (default `./.metaobjects/migrations`)
 - `--slug <name>` — required when changes are pending (e.g., `add-user-shipping`)
 - `--allow <csv>` — destructive-change permissions: `drop-column,drop-table,type-change,drop-index,drop-fk,drop-check,drop-view,drop-view-cascade,adopt-view,nullable-to-not-null,drop-identity-default,drop-unmanaged,drop-comment`

server/typescript/packages/cli/test/integration/shadow-catalog-pg.test.ts

@@ -78,7 +78,7 @@ describe("shadow catalog: snapshot versions and undeclared comments (env-gated)"
     mkdirSync(join(root, "metaobjects"), { recursive: true });
     writeFileSync(join(root, "metaobjects", "meta.catalog.json"), MODEL, "utf8");
     // Day 1: the table, with its comments and a GENERATED identity, and a v4 snapshot of it.
-    expect((await captured(args("migrate", "--from-db", "--slug", "init", "--apply"))).exit).toBe(0);
+    expect((await captured(args("migrate", "--from-db", "--slug", "shadow-catalog", "--apply"))).exit).toBe(0);
   });
   afterAll(async () => {
     await pool.query(`DROP TABLE IF EXISTS ${TABLE} CASCADE`);

server/typescript/packages/cli/test/integration/shadow-default-drift-pg.test.ts

@@ -70,7 +70,7 @@ describe("shadow path: live default drift and an unreachable explicit shadow (en
     root = mkdtempSync(join(tmpdir(), "shadow-default-drift-pg-"));
     mkdirSync(join(root, "metaobjects"), { recursive: true });
     writeFileSync(join(root, "metaobjects", "meta.events.json"), MODEL, "utf8");
-    expect((await captured(args("migrate", "--from-db", "--slug", "init", "--apply"))).exit).toBe(0);
+    expect((await captured(args("migrate", "--from-db", "--slug", "shadow-default-drift", "--apply"))).exit).toBe(0);
   });
   afterAll(async () => {
     await pool.query(`DROP TABLE IF EXISTS ${TABLE} CASCADE`);