docs(#241): document the D1 FK-cascade; remove the refusal known-limitation

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

Author: dmealing

CHANGELOG.md

@@ -5,6 +5,33 @@ here. The format follows [Keep a Changelog](https://keepachangelog.com/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 (pre-1.0; MINOR bumps may introduce breaking changes with notice).
 
+## [Unreleased]
+
+**npm-only** — the changed code is all in `migrate-ts` (D1 is a TS-only dialect);
+PyPI / NuGet / Maven Central are unchanged.
+
+### Added — D1 auto-cascade for rebuilding foreign-key-referenced tables (#241)
+
+npm-only (`migrate-ts` — D1 is a TS-only dialect). `meta migrate --dialect d1` no
+longer refuses when a change would rebuild a table that another table's foreign key
+references ([#226](https://github.com/metaobjectsdev/metaobjects/issues/226)) — it now
+**auto-generates an appliable cascade** instead. The emitter rebuilds the referenced
+table together with every table that transitively references it, in one pass: the
+affected tables are dropped referrers-first and recreated parents-first, under `PRAGMA
+defer_foreign_keys = ON` so every foreign-key check defers to the end of D1's implicit
+transaction rather than firing mid-rebuild. The cascade is built over the **union of
+the actual (live) and expected (target) schemas' foreign-key graphs**, closing #226's
+residual under-refuse gap: a single migration that both rebuilds a referenced table
+*and* drops the referencing foreign key in the same run is now detected and handled
+correctly (a target-schema-only check missed this). A **multi-table foreign-key cycle**
+(two or more tables referencing each other in a loop) has no parents-first rebuild
+order and is still refused at generation time with actionable guidance; a
+self-referencing table is not a cycle and is rebuilt by the cascade like any other
+table. Migrations that do not rebuild a foreign-key-referenced table are
+**byte-identical**. Gated by a real-libSQL-engine convergence round-trip across every
+cascade topology (linear chain, diamond, self-reference), the #226 gap scenario, and
+the cycle-refusal case.
+
 ## [0.20.7] — 2026-07-28
 
 **npm-only** — the changed code is all in `cli` / `migrate-ts`; PyPI / NuGet / Maven

docs/features/migrations-and-drift.md

@@ -63,28 +63,36 @@ new migration from the metadata-vs-DB diff before applying it. `apply-pending` j
 the pending already-committed files, making it idempotent; `--dry-run` lists what would
 run. postgres/sqlite only — on D1 use `wrangler d1 migrations apply`.
 
-#### D1 limitation: rebuilding a foreign-key-referenced table
+#### D1: rebuilding a foreign-key-referenced table
 
 Cloudflare D1 applies each migration inside its own implicit transaction, and SQLite
 ignores `PRAGMA foreign_keys` while a transaction is open. The SQLite table-rebuild
 recipe (used for a `CHECK`, column type/nullability/default, foreign-key, or
 `field.enum` values change) relies on `PRAGMA foreign_keys = OFF` taking effect before
 it drops and recreates the table — which does not happen on remote D1.
 
-To avoid emitting a migration that would fail against a populated production database
-with `FOREIGN KEY constraint failed`, `meta migrate --dialect d1` **refuses at
-generation time** when a change would rebuild a table that another table's foreign key
-references. Apply such a change by hand-writing the migration: rebuild the referencing
-table to temporarily drop its foreign key, rebuild the referenced table, then restore
-the foreign key — or make the change on an unreferenced table. (Auto-generating this
-cascade is tracked as a follow-up, [#241](https://github.com/metaobjectsdev/metaobjects/issues/241).)
-
-**Known limitation of the current refusal:** it is computed from the *target* schema's
-foreign keys. A single migration that **both** rebuilds a referenced table **and** drops
-the referencing foreign key in the same run is therefore not detected, and can still fail
-on remote D1 (the parent's `DROP TABLE` can be emitted before the referencing table is
-rebuilt). Split such a change into two migrations, or hand-write it. Closing this gap
-requires the actual-schema foreign-key graph and rides the same follow-up (#241).
+`meta migrate --dialect d1` handles this by **auto-generating a cascade**
+([#241](https://github.com/metaobjectsdev/metaobjects/issues/241), closing
+[#226](https://github.com/metaobjectsdev/metaobjects/issues/226)'s residual
+under-refuse gap below) instead of refusing outright. When a change would rebuild a
+table that another table's foreign key references, the emitter rebuilds that table
+together with every table that transitively references it, in one pass: the affected
+tables are dropped referrers-first and recreated parents-first, under `PRAGMA
+defer_foreign_keys = ON` so every foreign-key check defers to the end of D1's implicit
+transaction instead of firing mid-rebuild. The result applies cleanly against a
+populated production database and re-converges — a follow-up `meta verify`/`meta
+migrate` sees no drift. The cascade is built over the **union of the actual (live) and
+expected (target) schemas' foreign-key graphs**, so it also covers the case a
+target-schema-only check would miss: a single migration that both rebuilds a
+referenced table *and* drops the referencing foreign key in the same run.
+
+The one case still hand-written: a **multi-table foreign-key cycle** (table A
+references B references … references A, two or more tables). A cycle has no
+parents-first rebuild order, so `meta migrate --dialect d1` still **refuses at
+generation time** — hand-write the migration (drop the foreign key on one side of the
+cycle, rebuild the tables, then restore it) or break the cycle in your metadata. A
+self-referencing table (a table whose own foreign key targets itself) is not a cycle
+in this sense and is handled by the cascade like any other rebuild.
 
 ### Java