fix(db): #1464 (Phase B) composite-aware engine — shared_schema FK/UNIQUE parity

The #1431 migration engine's snapshot was lossy: FKs per-column ({col: table}),
composite UNIQUE(tenant_id,id) flattened to a column set, indexes non-deduped. So
a shared_schema intra-tenant ref produced a simple (fk)→Parent(id) FK +
UNIQUE(id) + a bogus UNIQUE(tenant_id), and composite list indexes could
double-emit (DuplicateTable at upgrade).

schema_snapshot.project_schema now reads table-level ForeignKeyConstraints
(cols→reftable+refcols) + UniqueConstraint column-tuples + a deduped index set
(extracted to _table_fks/_table_uniques/_table_index_keys helpers, keeping CC<15);
schema_diff op models carry composite columns (+ _coerce_fks/_coerce_uniques
backward-compat for legacy embedded snapshots); schema_render emits the composite
FK/UNIQUE (was hard-coded ["id"]). Cross-tenant referential integrity
(tenant_id, fk)→Parent(tenant_id, id) is now enforced by the migration-built
schema, not just create_all.

Removed the #1464 xfail; baseline + new incremental-revision parity oracles GREEN
on real PG (now composite-aware via an independent pg_catalog read).

Adversarial review caught a CRITICAL FK-name mismatch (sa_schema fk_{entity}_{field}
vs engine fk_{entity}_{partition_key}_{field}) → aligned sa_schema so both paths
name composite FKs identically; + name-alignment regression test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: claude

.claude/CLAUDE.md

@@ -374,4 +374,4 @@ Example: `examples/ops_dashboard` has working `bar_chart` (FK `group_by: system`
 - **KG re-seeding**: `ensure_seeded()` checks a version key; bump it in `seed.py` when TOML data changes.
 
 ---
-**Version**: 0.85.1 | **Python**: 3.12+ | **Status**: Production Ready
+**Version**: 0.85.2 | **Python**: 3.12+ | **Status**: Production Ready

CHANGELOG.md

@@ -9,7 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.85.1] - 2026-06-24
+## [0.85.2] - 2026-06-24
+
+### Fixed
+- **#1464 (Phase B — engine fix) `db baseline` now reproduces shared_schema composite tenant-scoped constraints with full `create_all` parity.** The #1431 migration engine's snapshot model was lossy — FKs stored per-column (`{col: table}`, no referred columns), composite `UNIQUE(tenant_id, id)` flattened to a column set, indexes in a non-deduped list — so a shared_schema intra-tenant ref produced a *simple* `(fk) → Parent(id)` FK + `UNIQUE(id)` + a bogus, unusable `UNIQUE(tenant_id)` (one row per tenant), and composite "list" indexes could double-emit (`DuplicateTable` at upgrade). `schema_snapshot.project_schema` now reads table-level `ForeignKeyConstraint`s (constrained cols → referred table + referred cols) and `UniqueConstraint` column-tuples, and de-duplicates index keys; `schema_diff` op models (`AddForeignKey`/`DropForeignKey`/`AddUnique`/`DropUnique`) carry composite columns; `schema_render` emits the composite FK/UNIQUE (was hard-coded `["id"]`). Legacy embedded snapshots are upgraded in-place (`_coerce_fks`/`_coerce_uniques`) so an incremental `db revision` against a pre-#1464 baseline stays correct. **Cross-tenant referential integrity (`(tenant_id, fk) → Parent(tenant_id, id)`) is now structurally enforced by the migration-built schema, not just by `create_all`.** Verified on real Postgres (baseline + incremental-revision parity oracles, now composite-aware: they compare FK *structure* + UNIQUE column-tuples via an independent `pg_catalog` read). Adversarially reviewed: a CRITICAL constraint-name mismatch was caught and fixed — `sa_schema` named the composite FK `fk_{entity}_{field}` while the engine named it `fk_{entity}_{partition_key}_{field}`; both now agree, so the two provisioning paths produce byte-identical names (an engine drop/downgrade against a `create_all` DB would otherwise target a non-existent name).
+
+### Agent Guidance
+- **The migration engine's schema snapshot is composite-aware.** `project_schema` FKs are `[(constrained_cols, ref_table, ref_cols), ...]` and uniques are `[(col, ...), ...]` (tuples, embedded via `pprint`). When adding constraint handling, go through table-level `ForeignKeyConstraint`/`UniqueConstraint`, not per-column `.foreign_keys`/`col.unique`. Composite constraint names join all columns (`fk_{table}_{c1}_{c2}`); keep `sa_schema` (create_all) and `schema_render` (engine) naming aligned or the parity oracle's intent (byte-identical schemas) is lost.
 
 ### Added
 - **#1464 (Phase A — reproducer) engine-baseline parity oracle now detects shared_schema composite-constraint divergence.** The `db baseline ≡ create_all` parity gate (`tests/integration/test_engine_baseline_parity_pg.py`) was blind to composite tenant-scoped constraints: it compared FKs by `column→table` (not structure) and omitted UNIQUE constraints entirely, both via the engine's own lossy snapshot. Added an independent `pg_catalog`-based introspection (`_pg_constraint_shapes`) that captures composite FK structure (`(constrained cols) → table(referred cols)`) and UNIQUE column-tuples, plus an inline `shared_schema_intra_fk` corpus fixture (Workspace tenant-root; `Project.owner → Member` intra-tenant ref). The fixture reproduces #1464 — the engine baseline emits a simple `(owner) → Member` FK + `UNIQUE(id)` + bogus `UNIQUE(tenant_id)` instead of the composite `(tenant_id, owner) → Member(tenant_id, id)` + `UNIQUE(tenant_id, id)` — and is marked `xfail(strict=True)` so CI stays green while the gap is tracked in-repo. The engine fix (Phase B) flips it to pass.

ROADMAP.md

@@ -1,7 +1,7 @@
 # DAZZLE Development Roadmap
 
 **Last Updated**: 2026-06-16
-**Current Version**: v0.85.1
+**Current Version**: v0.85.2
 
 For past releases, see [CHANGELOG.md](CHANGELOG.md).
 

homebrew/dazzle.rb

@@ -10,10 +10,10 @@ class Dazzle < Formula
 
   desc "DSL-first application framework with LLM-assisted development"
   homepage "https://github.com/manwithacat/dazzle"
-  version "0.85.1"
+  version "0.85.2"
   license "MIT"
 
-  url "https://github.com/manwithacat/dazzle/archive/refs/tags/v0.85.1.tar.gz"
+  url "https://github.com/manwithacat/dazzle/archive/refs/tags/v0.85.2.tar.gz"
   sha256 "PLACEHOLDER_SOURCE_SHA256"
 
   # pydantic-core requires Rust to build from source, so use pre-built wheels

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dazzle-dsl"
-version = "0.85.1"
+version = "0.85.2"
 description = "DAZZLE — declarative SaaS framework with built-in compliance (SOC 2, ISO 27001), provable RBAC, and graph features"
 readme = "README.md"
 requires-python = ">=3.12"

src/dazzle/db/schema_diff.py

@@ -24,9 +24,11 @@ class AddTable:
 
     table: str
     columns: dict[str, Any]
-    fks: dict[str, str]
+    # #1464: composite-aware. fks = [(cols, ref_table, ref_cols), ...];
+    # uniques = [(col, ...), ...]. indexes = ["col[,col]", ...] (comma-joined).
+    fks: list[Any]
     indexes: list[str]
-    uniques: list[str]
+    uniques: list[Any]
 
 
 @dataclass(frozen=True)
@@ -84,20 +86,22 @@ class AlterColumn:
 
 @dataclass(frozen=True)
 class AddForeignKey:
-    """Add a foreign key constraint."""
+    """Add a (possibly composite) foreign key constraint (#1464)."""
 
     table: str
-    column: str
+    columns: tuple[str, ...]
     ref_table: str
+    ref_columns: tuple[str, ...]
 
 
 @dataclass(frozen=True)
 class DropForeignKey:
-    """Drop a foreign key constraint."""
+    """Drop a (possibly composite) foreign key constraint (#1464)."""
 
     table: str
-    column: str
+    columns: tuple[str, ...]
     ref_table: str
+    ref_columns: tuple[str, ...]
 
 
 @dataclass(frozen=True)
@@ -118,18 +122,18 @@ class DropIndex:
 
 @dataclass(frozen=True)
 class AddUnique:
-    """Add a unique constraint on a column."""
+    """Add a (possibly composite) unique constraint (#1464)."""
 
     table: str
-    column: str
+    columns: tuple[str, ...]
 
 
 @dataclass(frozen=True)
 class DropUnique:
-    """Drop a unique constraint on a column."""
+    """Drop a (possibly composite) unique constraint (#1464)."""
 
     table: str
-    column: str
+    columns: tuple[str, ...]
 
 
 SchemaOp = (
@@ -155,8 +159,11 @@ class DropUnique:
 #: ColSnap keys: type (str), nullable (bool), default (str|None), pk (bool)
 ColSnap = dict[str, Any]
 
-#: TableSnap keys: columns (dict[str, ColSnap]), fks (dict[str, str]),
-#:                 indexes (list[str]), uniques (list[str])
+#: TableSnap keys: columns (dict[str, ColSnap]),
+#:   fks (list[(cols, ref_table, ref_cols)] — composite-aware, #1464; legacy
+#:        dict[col, table] is accepted + upgraded by _coerce_fks),
+#:   uniques (list[(col, ...)] — legacy list[str] upgraded by _coerce_uniques),
+#:   indexes (list[str] — comma-joined columns)
 TableSnap = dict[str, Any]
 
 #: Snapshot: table-name → TableSnap
@@ -299,6 +306,32 @@ def _diff_columns(
     return add_ops, alter_ops, drop_ops
 
 
+def _coerce_fks(snap: TableSnap) -> set[tuple[tuple[str, ...], str, tuple[str, ...]]]:
+    """Normalize a snapshot's ``fks`` to the composite set shape (#1464).
+
+    Accepts both the current composite shape (``[(cols, ref_table, ref_cols), ...]``)
+    and the legacy per-column shape (``{col: ref_table}``) embedded in pre-#1464
+    baselines — the latter upgrades to single-column FKs referencing the PK ``id``
+    (what the old engine always assumed), so an incremental ``db revision`` against
+    an old baseline doesn't see a spurious drop+re-add of every FK.
+    """
+    raw = snap.get("fks", [])
+    if isinstance(raw, dict):  # legacy {col: ref_table}
+        return {((col,), tbl, ("id",)) for col, tbl in raw.items()}
+    return {(tuple(cols), tbl, tuple(refcols)) for cols, tbl, refcols in raw}
+
+
+def _coerce_uniques(snap: TableSnap) -> set[tuple[str, ...]]:
+    """Normalize a snapshot's ``uniques`` to a set of column tuples (#1464).
+
+    Accepts the current shape (``[(col, ...), ...]``) and the legacy flat shape
+    (``["col", ...]`` — single-column names), upgrading each bare name to a
+    one-column tuple.
+    """
+    raw = snap.get("uniques", [])
+    return {(c,) if isinstance(c, str) else tuple(c) for c in raw}
+
+
 def _diff_constraints(
     curr_tname: str,
     prev_snap: TableSnap,
@@ -313,12 +346,16 @@ def _diff_constraints(
     add_ops: list[SchemaOp] = []
     drop_ops: list[SchemaOp] = []
 
-    prev_fk_set = set(prev_snap.get("fks", {}).items())
-    curr_fk_set = set(curr_snap.get("fks", {}).items())
-    for col, ref in sorted(curr_fk_set - prev_fk_set):
-        add_ops.append(AddForeignKey(table=curr_tname, column=col, ref_table=ref))
-    for col, ref in sorted(prev_fk_set - curr_fk_set):
-        drop_ops.append(DropForeignKey(table=curr_tname, column=col, ref_table=ref))
+    prev_fk_set = _coerce_fks(prev_snap)
+    curr_fk_set = _coerce_fks(curr_snap)
+    for cols, ref, refcols in sorted(curr_fk_set - prev_fk_set):
+        add_ops.append(
+            AddForeignKey(table=curr_tname, columns=cols, ref_table=ref, ref_columns=refcols)
+        )
+    for cols, ref, refcols in sorted(prev_fk_set - curr_fk_set):
+        drop_ops.append(
+            DropForeignKey(table=curr_tname, columns=cols, ref_table=ref, ref_columns=refcols)
+        )
 
     prev_indexes = set(prev_snap.get("indexes", []))
     curr_indexes = set(curr_snap.get("indexes", []))
@@ -327,12 +364,12 @@ def _diff_constraints(
     for col in sorted(prev_indexes - curr_indexes):
         drop_ops.append(DropIndex(table=curr_tname, column=col))
 
-    prev_uniques = set(prev_snap.get("uniques", []))
-    curr_uniques = set(curr_snap.get("uniques", []))
-    for col in sorted(curr_uniques - prev_uniques):
-        add_ops.append(AddUnique(table=curr_tname, column=col))
-    for col in sorted(prev_uniques - curr_uniques):
-        drop_ops.append(DropUnique(table=curr_tname, column=col))
+    prev_uniques = _coerce_uniques(prev_snap)
+    curr_uniques = _coerce_uniques(curr_snap)
+    for cols in sorted(curr_uniques - prev_uniques):
+        add_ops.append(AddUnique(table=curr_tname, columns=cols))
+    for cols in sorted(prev_uniques - curr_uniques):
+        drop_ops.append(DropUnique(table=curr_tname, columns=cols))
 
     return add_ops, drop_ops
 
@@ -398,21 +435,25 @@ def diff(
     for tname in sorted(curr_tables - prev_tables):
         if tname not in table_prev_name:
             tsnap = curr[tname]
+            fk_specs = sorted(_coerce_fks(tsnap))
+            unique_specs = sorted(_coerce_uniques(tsnap))
             add_tables.append(
                 AddTable(
                     table=tname,
                     columns=dict(tsnap.get("columns", {})),
-                    fks=dict(tsnap.get("fks", {})),
+                    fks=fk_specs,
                     indexes=list(tsnap.get("indexes", [])),
-                    uniques=list(tsnap.get("uniques", [])),
+                    uniques=unique_specs,
                 )
             )
-            for col, ref in sorted(tsnap.get("fks", {}).items()):
-                add_table_constraints.append(AddForeignKey(table=tname, column=col, ref_table=ref))
+            for cols, ref, refcols in fk_specs:
+                add_table_constraints.append(
+                    AddForeignKey(table=tname, columns=cols, ref_table=ref, ref_columns=refcols)
+                )
             for idx_cols in sorted(tsnap.get("indexes", [])):
                 add_table_constraints.append(AddIndex(table=tname, column=idx_cols))
-            for col in sorted(tsnap.get("uniques", [])):
-                add_table_constraints.append(AddUnique(table=tname, column=col))
+            for cols in unique_specs:
+                add_table_constraints.append(AddUnique(table=tname, columns=cols))
 
     # --- 4. Diff columns + constraints for common/renamed table pairs -------
     add_details: list[SchemaOp] = []

src/dazzle/db/schema_render.py

@@ -187,8 +187,8 @@ def _col_snap_to_sa_column(name: str, snap: ColSnap) -> sa.Column[Any]:
 # ---------------------------------------------------------------------------
 
 
-def _fk_name(table: str, column: str) -> str:
-    return f"fk_{table}_{column}"
+def _fk_name(table: str, columns: tuple[str, ...]) -> str:
+    return f"fk_{table}_{'_'.join(columns)}"
 
 
 def _idx_name(table: str, column: str) -> str:
@@ -202,8 +202,8 @@ def _idx_columns(column: str) -> list[str]:
     return column.split(",")
 
 
-def _uq_name(table: str, column: str) -> str:
-    return f"uq_{table}_{column}"
+def _uq_name(table: str, columns: tuple[str, ...]) -> str:
+    return f"uq_{table}_{'_'.join(columns)}"
 
 
 # ---------------------------------------------------------------------------
@@ -519,13 +519,13 @@ def _type_change_execute_op(
 def _render_add_fk(
     op: AddForeignKey,
 ) -> tuple[aops.MigrateOperation, aops.MigrateOperation]:
-    name = _fk_name(op.table, op.column)
+    name = _fk_name(op.table, op.columns)
     create_op = aops.CreateForeignKeyOp(
         name,
         op.table,
         op.ref_table,
-        [op.column],
-        ["id"],
+        list(op.columns),
+        list(op.ref_columns),
     )
     drop_op = aops.DropConstraintOp(name, op.table, type_="foreignkey")
     return create_op, drop_op
@@ -534,14 +534,14 @@ def _render_add_fk(
 def _render_drop_fk(
     op: DropForeignKey,
 ) -> tuple[aops.MigrateOperation, aops.MigrateOperation]:
-    name = _fk_name(op.table, op.column)
+    name = _fk_name(op.table, op.columns)
     drop_op = aops.DropConstraintOp(name, op.table, type_="foreignkey")
     recreate_op = aops.CreateForeignKeyOp(
         name,
         op.table,
         op.ref_table,
-        [op.column],
-        ["id"],
+        list(op.columns),
+        list(op.ref_columns),
     )
     return drop_op, recreate_op
 
@@ -567,18 +567,18 @@ def _render_drop_index(
 def _render_add_unique(
     op: AddUnique,
 ) -> tuple[aops.MigrateOperation, aops.MigrateOperation]:
-    name = _uq_name(op.table, op.column)
-    create_op = aops.CreateUniqueConstraintOp(name, op.table, [op.column])
+    name = _uq_name(op.table, op.columns)
+    create_op = aops.CreateUniqueConstraintOp(name, op.table, list(op.columns))
     drop_op = aops.DropConstraintOp(name, op.table, type_="unique")
     return create_op, drop_op
 
 
 def _render_drop_unique(
     op: DropUnique,
 ) -> tuple[aops.MigrateOperation, aops.MigrateOperation]:
-    name = _uq_name(op.table, op.column)
+    name = _uq_name(op.table, op.columns)
     drop_op = aops.DropConstraintOp(name, op.table, type_="unique")
-    recreate_op = aops.CreateUniqueConstraintOp(name, op.table, [op.column])
+    recreate_op = aops.CreateUniqueConstraintOp(name, op.table, list(op.columns))
     return drop_op, recreate_op