create-ailk 0.4.0 → 0.6.0

package/templates/database/__tests__/fence-fan-out.db.test.ts

@@ -0,0 +1,711 @@
+/**
+ * @file fence-fan-out.db.test.ts
+ *
+ * LIVE-DATABASE proof of the #6374 fence fan-out constraints (AC-4, AC-5).
+ * Named after — and modelled line-for-line on — its sibling
+ * `composite-fence.db.test.ts`, which proves the same shape for the #6254
+ * keystone's four already-keyed models. Requires DATABASE_URL pointing at a
+ * Postgres with the migrations applied (`prisma migrate deploy`); the whole
+ * suite SKIPS when DATABASE_URL is unset, matching every other `.db.test.ts`
+ * here and keeping the workspace Jest run DB-free.
+ *
+ * Raw SQL through `pg`, for the same reason those files give: the generated
+ * Prisma client is ESM-only and cannot load under this package's CJS ts-jest
+ * transform.
+ *
+ * What it proves (spec § 6 AC-4 / AC-5):
+ *
+ *   AC-4, for EACH of the eleven `site_id` tables the amendment fences:
+ *     1. an insert with `workspace_id` NULL is rejected — 23502;
+ *     2. an insert whose `workspace_id` differs from its `site_id` is
+ *        rejected BY `<table>_workspace_site_agree` — 23514, and the
+ *        constraint is named in the assertion, so a row rejected by some
+ *        OTHER constraint cannot pass this test;
+ *     3. an insert where the two AGREE succeeds — without this, assertion 2
+ *        would also pass against a table that rejects everything;
+ *     4. no row carries `site_id = 'default'` after the migration — the
+ *        normalization (D1 step 2) actually ran.
+ *
+ *   AC-5, the four shapes that are NOT the eleven-table pattern:
+ *     5. `site_settings` is keyed by (workspace_id, key), not by key alone
+ *        (D3): two workspaces may each hold `feature_flags`; a SECOND one in
+ *        ONE workspace is rejected — 23505.
+ *     6. `listing_csv_sends` rejects a NULL `workspace_id` (D2) — it has no
+ *        `site_id`, so it takes NOT NULL + the format CHECK and no equality
+ *        CHECK.
+ *     7. `deliverable_grants` (D4) stays NULL-TOLERANT — NULL is the serve
+ *        path's fail-closed sentinel — while a STAMPED grant may never
+ *        disagree with its site.
+ *     8. Deleting a `workspaces` row leaves that workspace's `consent_grants`
+ *        rows in place: the fence is a CHECK, never a foreign key (NFR1,
+ *        ADR-0009 invariant #1). A cascade here would be silent data loss.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+/**
+ * The SHIPPED migration text. AC-14's two cases execute the guard block out of
+ * this file rather than a re-typed copy, so an edit to the guard that changed
+ * its classification would fail here — the same technique
+ * `composite-fence.db.test.ts` uses to pin the sentinel literal.
+ */
+const MIGRATION_SQL = readFileSync(
+  join(__dirname, "..", "migrations", "20260922120000_tenancy_fence", "migration.sql"),
+  "utf-8",
+);
+
+/**
+ * The WHOLE `site_settings` attribution sequence (AC-14), extracted from the
+ * shipped migration: the abort-not-guess guard, then the sentinel UPDATE,
+ * then the post-backfill assertion — the migration's first, second and third
+ * statements after the marker, in order.
+ *
+ * Slicing through the SECOND `END $$;` rather than the first is what makes the
+ * non-abort cases meaningful: the guard alone only proves a row was not
+ * REJECTED, while the guard-plus-UPDATE proves it was actually ATTRIBUTED, and
+ * to which workspace. A slice that stopped at the first block would pass
+ * identically whether the UPDATE backfilled the sentinel or did nothing at all.
+ */
+function siteSettingsGuardSql(): string {
+  const marker = "-- ── ABORT, NEVER GUESS";
+  const start = MIGRATION_SQL.indexOf(marker);
+  if (start < 0) throw new Error("AC-14 guard block not found in migration.sql");
+  const doStart = MIGRATION_SQL.indexOf("DO $$", start);
+  if (doStart < 0) throw new Error("AC-14 guard DO block malformed");
+  const END = "END $$;";
+  // The guard's own terminator, then the post-backfill assertion's.
+  const firstEnd = MIGRATION_SQL.indexOf(END, doStart);
+  const secondEnd = firstEnd < 0 ? -1 : MIGRATION_SQL.indexOf(END, firstEnd + END.length);
+  if (firstEnd < 0 || secondEnd < 0) {
+    throw new Error("AC-14 slice malformed — expected two DO blocks after the marker");
+  }
+  const sql = MIGRATION_SQL.slice(doStart, secondEnd + END.length);
+  // Fail loudly if the migration is reshaped so the slice no longer spans the
+  // UPDATE — otherwise the non-abort cases would silently stop proving it.
+  if (!sql.includes('UPDATE "site_settings"')) {
+    throw new Error("AC-14 slice no longer spans the sentinel UPDATE");
+  }
+  return sql;
+}
+
+/** Postgres's own error shape carries `code` as a 5-character SQLSTATE. */
+type PgError = { code?: string; constraint?: string };
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+/** A run-unique suffix so repeated local runs never collide. */
+const RUN = randomUUID().slice(0, 8);
+
+/** The seeded sentinel workspace — `database/tenancy.ts`'s DEFAULT_WORKSPACE_ID. */
+const SENTINEL_WORKSPACE_ID = "wksp_00000000-0000-7000-8000-000000000001";
+
+/**
+ * The eleven `site_id` tables of spec § 1.1, each with the columns its own
+ * NOT NULLs require BESIDES `site_id`/`workspace_id`. `cols` and `vals` are
+ * positional twins: `vals` starts at `$3` because `$1`/`$2` are always
+ * `site_id`/`workspace_id`, which every case below supplies itself.
+ */
+interface FenceTable {
+  /** The Postgres table name — also the constraint-name stem. */
+  table: string;
+  /** Extra NOT NULL columns, already quoted-safe (plain lower_snake). */
+  cols: string[];
+  /** One value per `cols` entry, in order. */
+  vals: () => unknown[];
+}
+
+const TABLES: FenceTable[] = [
+  {
+    table: "subscribers",
+    cols: ["email", "source"],
+    vals: () => [`sub-${RUN}-${randomUUID()}@example.com`, `6374-${RUN}`],
+  },
+  {
+    table: "callbacks",
+    cols: ["name", "phone", "payload"],
+    vals: () => [`6374 ${RUN}`, "+10000000000", "{}"],
+  },
+  {
+    table: "consent_grants",
+    cols: [
+      "subject_type",
+      "subject_id",
+      "purpose_id",
+      "granted",
+      "locale",
+      "statement",
+      "statement_hash",
+    ],
+    vals: () => [
+      "subscriber",
+      `subj-${RUN}-${randomUUID()}`,
+      `purpose-${RUN}`,
+      true,
+      "en",
+      "I agree",
+      `hash-${RUN}`,
+    ],
+  },
+  {
+    table: "appointments",
+    cols: [
+      "provider_booking_uid",
+      "start_time",
+      "end_time",
+      "attendee_name",
+      "attendee_email",
+      "status",
+      "lifecycle_event_at",
+      "updated_at",
+    ],
+    vals: () => [
+      `uid-${RUN}-${randomUUID().slice(0, 8)}`,
+      new Date("2026-10-01T10:00:00Z"),
+      new Date("2026-10-01T11:00:00Z"),
+      "Attendee",
+      `appt-${RUN}@example.com`,
+      "confirmed",
+      new Date("2026-09-22T00:00:00Z"),
+      new Date("2026-09-22T00:00:00Z"),
+    ],
+  },
+  {
+    table: "deliverable_assets",
+    cols: ["key", "filename", "content_type", "bytes", "size", "updated_at"],
+    vals: () => [
+      `key-${RUN}-${randomUUID().slice(0, 8)}`,
+      "file.pdf",
+      "application/pdf",
+      Buffer.from("bytes"),
+      5,
+      new Date("2026-09-22T00:00:00Z"),
+    ],
+  },
+  {
+    table: "flow_checkouts",
+    cols: [
+      "flow_slug",
+      "experiment_key",
+      "session_id",
+      "lead_id",
+      "offer_key",
+      "seats",
+      "period",
+      "credit_stop",
+      "amount_minor",
+      "currency",
+      "quote",
+      "permalink",
+      "status",
+      "updated_at",
+    ],
+    vals: () => [
+      `flow-${RUN}`,
+      `exp-${RUN}`,
+      `sess-${RUN}-${randomUUID().slice(0, 8)}`,
+      `lead-${RUN}-${randomUUID().slice(0, 8)}`,
+      "offer",
+      1,
+      "monthly",
+      "{}",
+      1000,
+      "usd",
+      "{}",
+      "permalink",
+      "created",
+      new Date("2026-09-22T00:00:00Z"),
+    ],
+  },
+  {
+    table: "waitlist_experiments",
+    cols: ["key", "mode", "status", "config", "updated_at"],
+    vals: () => [
+      `exp-${RUN}-${randomUUID().slice(0, 8)}`,
+      "lead-capture",
+      "live",
+      "{}",
+      new Date("2026-09-22T00:00:00Z"),
+    ],
+  },
+  {
+    table: "waitlist_scores",
+    cols: [
+      "lead_id",
+      "experiment_key",
+      "waitlist_key",
+      "tier",
+      "score",
+      "category_scores",
+      "rule_trace",
+      "updated_at",
+    ],
+    vals: () => [
+      `lead-${RUN}-${randomUUID().slice(0, 8)}`,
+      `exp-${RUN}`,
+      `wl-${RUN}`,
+      "a",
+      10,
+      "{}",
+      "{}",
+      new Date("2026-09-22T00:00:00Z"),
+    ],
+  },
+  {
+    table: "waitlist_followup_sends",
+    cols: ["lead_id", "follow_up_key", "sent_at", "status"],
+    vals: () => [
+      `lead-${RUN}-${randomUUID().slice(0, 8)}`,
+      `fu-${RUN}`,
+      new Date("2026-09-22T00:00:00Z"),
+      "sent",
+    ],
+  },
+  {
+    table: "playbook_instances",
+    cols: [
+      "lead_id",
+      "experiment_key",
+      "score_id",
+      "tier",
+      "level",
+      "rule_trace",
+      "source",
+      "markdown",
+    ],
+    vals: () => [
+      `lead-${RUN}-${randomUUID().slice(0, 8)}`,
+      `exp-${RUN}`,
+      `score-${RUN}-${randomUUID().slice(0, 8)}`,
+      "a",
+      1,
+      "{}",
+      "{}",
+      "# playbook",
+    ],
+  },
+  {
+    table: "site_listing_configs",
+    cols: ["data", "updated_at"],
+    vals: () => ["{}", new Date("2026-09-22T00:00:00Z")],
+  },
+];
+
+/** `INSERT INTO t (site_id, workspace_id, …) VALUES ($1, $2, …)`. */
+function insertSql(spec: FenceTable): string {
+  const cols = ['"site_id"', '"workspace_id"', ...spec.cols.map((c) => `"${c}"`)];
+  const params = cols.map((_, i) => `$${i + 1}`);
+  return `INSERT INTO "${spec.table}" (${cols.join(", ")}) VALUES (${params.join(", ")})`;
+}
+
+/** The same INSERT with `workspace_id` omitted entirely — the NULL case. */
+function insertSqlWithoutWorkspace(spec: FenceTable): string {
+  const cols = ['"site_id"', ...spec.cols.map((c) => `"${c}"`)];
+  const params = cols.map((_, i) => `$${i + 1}`);
+  return `INSERT INTO "${spec.table}" (${cols.join(", ")}) VALUES (${params.join(", ")})`;
+}
+
+describeDb("the #6374 fence fan-out constraints (live DB)", () => {
+  let db: Client;
+  let workspaceAId: string;
+  let workspaceBId: string;
+  /** A workspace used ONLY by the cascade proof, so its delete is unblocked. */
+  let workspaceCId: string;
+  let orgId: string;
+
+  async function makeWorkspace(label: string): Promise<string> {
+    const row = await db.query<{ id: string }>(
+      `INSERT INTO "workspaces" ("organization_id", "name", "slug", "updated_at")
+       VALUES ($1, $2, $3, now()) RETURNING "id"`,
+      [orgId, `6374 Workspace ${label} ${RUN}`, `6374-ws-${label}-${RUN}`],
+    );
+    return row.rows[0]!.id;
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+
+    // Two REAL, distinct workspaces — A and B — so a "disagreement" insert
+    // names two values that both actually exist, not a real one versus
+    // garbage (which the FORMAT CHECK, not the equality CHECK, would catch;
+    // the assertions below name the equality constraint for that reason).
+    orgId = (
+      await db.query<{ id: string }>(
+        `INSERT INTO "organizations" ("name", "slug", "updated_at")
+         VALUES ($1, $2, now()) RETURNING "id"`,
+        [`6374 Org ${RUN}`, `6374-org-${RUN}`],
+      )
+    ).rows[0]!.id;
+
+    workspaceAId = await makeWorkspace("a");
+    workspaceBId = await makeWorkspace("b");
+    workspaceCId = await makeWorkspace("c");
+  });
+
+  afterAll(async () => {
+    // Every statement here is best-effort and the connection is closed in a
+    // `finally`: when an assertion above has already failed because a column
+    // or constraint this unit adds is ABSENT, the cleanup statement naming it
+    // fails too — and an un-ended `pg` Client is an open handle that hangs
+    // the whole Jest run instead of reporting the real failure.
+    const cleanup = [
+      ...TABLES.map(
+        (spec) =>
+          [
+            `DELETE FROM "${spec.table}" WHERE "site_id" = ANY($1)`,
+            [[workspaceAId, workspaceBId, workspaceCId]],
+          ] as const,
+      ),
+      [
+        `DELETE FROM "listing_csv_sends" WHERE "listing_id" = $1`,
+        [`listing-${RUN}`],
+      ] as const,
+      [
+        `DELETE FROM "deliverable_grants" WHERE "site_id" = ANY($1)`,
+        [[workspaceAId, workspaceBId]],
+      ] as const,
+      [
+        `DELETE FROM "site_settings" WHERE "workspace_id" = ANY($1)`,
+        [[workspaceAId, workspaceBId]],
+      ] as const,
+      [`DELETE FROM "workspaces" WHERE "slug" LIKE $1`, [`6374-ws-%-${RUN}`]] as const,
+      [`DELETE FROM "organizations" WHERE "slug" = $1`, [`6374-org-${RUN}`]] as const,
+    ];
+
+    try {
+      for (const [sql, params] of cleanup) {
+        try {
+          await db.query(sql, params as unknown[]);
+        } catch {
+          // Best-effort — see the note above.
+        }
+      }
+    } finally {
+      await db.end();
+    }
+  });
+
+  describe.each(TABLES.map((spec) => [spec.table, spec] as const))(
+    "AC-4 — %s",
+    (table, spec) => {
+      it("rejects an insert with workspace_id NULL (23502)", async () => {
+        await expect(
+          db.query(insertSqlWithoutWorkspace(spec), [
+            workspaceAId,
+            ...spec.vals(),
+          ]),
+        ).rejects.toMatchObject<PgError>({ code: "23502" });
+      });
+
+      it(`rejects workspace_id <> site_id, BY ${table}_workspace_site_agree (23514)`, async () => {
+        await expect(
+          db.query(insertSql(spec), [
+            workspaceAId,
+            workspaceBId,
+            ...spec.vals(),
+          ]),
+        ).rejects.toMatchObject<PgError>({
+          code: "23514",
+          constraint: `${table}_workspace_site_agree`,
+        });
+      });
+
+      it("accepts an insert where workspace_id AGREES with site_id", async () => {
+        const result = await db.query(
+          `${insertSql(spec)} RETURNING "id"`,
+          [workspaceAId, workspaceAId, ...spec.vals()],
+        );
+        expect(result.rows).toHaveLength(1);
+      });
+
+      it("carries no row with site_id = 'default' after the migration", async () => {
+        const result = await db.query<{ count: string }>(
+          `SELECT count(*)::text AS count FROM "${table}" WHERE "site_id" = 'default'`,
+        );
+        expect(result.rows[0]!.count).toBe("0");
+      });
+    },
+  );
+
+  describe("AC-5 — site_settings is keyed by (workspace_id, key), not by key alone (D3)", () => {
+    it("two DIFFERENT workspaces may each hold a feature_flags row", async () => {
+      const a = await db.query(
+        `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+         VALUES ($1, $2, '{}'::jsonb, now()) RETURNING "id"`,
+        [workspaceAId, "feature_flags"],
+      );
+      const b = await db.query(
+        `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+         VALUES ($1, $2, '{}'::jsonb, now()) RETURNING "id"`,
+        [workspaceBId, "feature_flags"],
+      );
+      expect(a.rows).toHaveLength(1);
+      expect(b.rows).toHaveLength(1);
+    });
+
+    it("a SECOND feature_flags row in ONE workspace is rejected (23505)", async () => {
+      await expect(
+        db.query(
+          `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+           VALUES ($1, $2, '{}'::jsonb, now())`,
+          [workspaceAId, "feature_flags"],
+        ),
+      ).rejects.toMatchObject<PgError>({ code: "23505" });
+    });
+
+    it("rejects a site_settings row with workspace_id NULL (23502)", async () => {
+      await expect(
+        db.query(
+          `INSERT INTO "site_settings" ("key", "value", "updated_at")
+           VALUES ($1, '{}'::jsonb, now())`,
+          [`nullws-${RUN}`],
+        ),
+      ).rejects.toMatchObject<PgError>({ code: "23502" });
+    });
+  });
+
+  describe("AC-5 — listing_csv_sends takes NOT NULL + the format CHECK, and no equality CHECK (D2)", () => {
+    it("rejects an insert with workspace_id NULL (23502)", async () => {
+      await expect(
+        db.query(
+          `INSERT INTO "listing_csv_sends" ("listing_id", "sent_at", "row_count", "grant_id")
+           VALUES ($1, now(), 1, $2)`,
+          [`listing-${RUN}`, `grant-${RUN}`],
+        ),
+      ).rejects.toMatchObject<PgError>({ code: "23502" });
+    });
+
+    it("accepts an insert stamped with a well-formed workspace_id", async () => {
+      const result = await db.query(
+        `INSERT INTO "listing_csv_sends"
+           ("listing_id", "workspace_id", "sent_at", "row_count", "grant_id")
+         VALUES ($1, $2, now(), 1, $3) RETURNING "id"`,
+        [`listing-${RUN}`, workspaceAId, `grant-${RUN}`],
+      );
+      expect(result.rows).toHaveLength(1);
+    });
+
+    it("has NO <table>_workspace_site_agree constraint — it carries no site_id (D2)", async () => {
+      const result = await db.query<{ conname: string }>(
+        `SELECT c.conname FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid
+          WHERE t.relname = 'listing_csv_sends'
+            AND c.conname = 'listing_csv_sends_workspace_site_agree'`,
+      );
+      expect(result.rows).toHaveLength(0);
+    });
+  });
+
+  describe("AC-5 — deliverable_grants stays NULL-tolerant but never disagreeing (D4)", () => {
+    it("ACCEPTS a row with workspace_id NULL — the serve path's fail-closed sentinel", async () => {
+      const result = await db.query(
+        `INSERT INTO "deliverable_grants" ("site_id", "asset_id", "lead_id", "session_id")
+         VALUES ($1, $2, $3, $4) RETURNING "id"`,
+        [
+          workspaceAId,
+          `dasset-${RUN}`,
+          `lead-${RUN}`,
+          `sess-${RUN}-${randomUUID().slice(0, 8)}`,
+        ],
+      );
+      expect(result.rows).toHaveLength(1);
+    });
+
+    it("rejects a STAMPED row whose workspace_id differs from its site_id (23514)", async () => {
+      await expect(
+        db.query(
+          `INSERT INTO "deliverable_grants"
+             ("site_id", "workspace_id", "asset_id", "lead_id", "session_id")
+           VALUES ($1, $2, $3, $4, $5)`,
+          [
+            workspaceAId,
+            workspaceBId,
+            `asset-${RUN}`,
+            `lead-${RUN}`,
+            `sess-${RUN}-${randomUUID().slice(0, 8)}`,
+          ],
+        ),
+      ).rejects.toMatchObject<PgError>({
+        code: "23514",
+        constraint: "deliverable_grants_workspace_site_agree",
+      });
+    });
+
+    it("accepts a STAMPED row whose workspace_id agrees with its site_id", async () => {
+      const result = await db.query(
+        `INSERT INTO "deliverable_grants"
+           ("site_id", "workspace_id", "asset_id", "lead_id", "session_id")
+         VALUES ($1, $1, $2, $3, $4) RETURNING "id"`,
+        [
+          workspaceAId,
+          `asset-${RUN}`,
+          `lead-${RUN}`,
+          `sess-${RUN}-${randomUUID().slice(0, 8)}`,
+        ],
+      );
+      expect(result.rows).toHaveLength(1);
+    });
+  });
+
+  describe("AC-14 — site_settings: abort, never guess (the key carries the tenant)", () => {
+    /** The sentinel Organization the sentinel workspace must hang off. */
+    const SENTINEL_ORGANIZATION_ID = "org_00000000-0000-7000-8000-000000000001";
+
+    // Every case runs inside a transaction that is ROLLED BACK, and each first
+    // drops NOT NULL on `workspace_id` so the PRE-migration row shape (an
+    // unattributed row) can exist at all. Nothing escapes the rollback.
+    async function withPreMigrationShape<T>(
+      body: () => Promise<T>,
+    ): Promise<T> {
+      await db.query("BEGIN");
+      try {
+        await db.query(
+          `ALTER TABLE "site_settings" ALTER COLUMN "workspace_id" DROP NOT NULL`,
+        );
+        return await body();
+      } finally {
+        await db.query("ROLLBACK");
+      }
+    }
+
+    /**
+     * The sentinel UPDATE joins to `workspaces`, so a database without the
+     * sentinel row backfills NOTHING and the post-backfill assertion aborts.
+     * A fresh `prisma migrate deploy` seeds no sentinel, so the non-abort
+     * cases create it here — inside the same rolled-back transaction.
+     */
+    async function ensureSentinelWorkspace(): Promise<void> {
+      await db.query(
+        `INSERT INTO "organizations" ("id", "name", "slug", "updated_at")
+         VALUES ($1, $2, $3, now()) ON CONFLICT DO NOTHING`,
+        [SENTINEL_ORGANIZATION_ID, `Sentinel Org ${RUN}`, `sentinel-org-${RUN}`],
+      );
+      await db.query(
+        `INSERT INTO "workspaces" ("id", "organization_id", "name", "slug", "updated_at")
+         VALUES ($1, $2, $3, $4, now()) ON CONFLICT DO NOTHING`,
+        [
+          SENTINEL_WORKSPACE_ID,
+          SENTINEL_ORGANIZATION_ID,
+          `Sentinel WS ${RUN}`,
+          `sentinel-ws-${RUN}`,
+        ],
+      );
+    }
+
+    /** The `workspace_id` the one row carrying `key` ended up attributed to. */
+    async function attributedWorkspaceOf(key: string): Promise<string | null> {
+      const rows = await db.query<{ workspace_id: string | null }>(
+        `SELECT "workspace_id" FROM "site_settings" WHERE "key" = $1`,
+        [key],
+      );
+      expect(rows.rows).toHaveLength(1);
+      return rows.rows[0]!.workspace_id;
+    }
+
+    it("(a) ABORTS on an unattributed row whose key embeds a NON-sentinel workspace id", async () => {
+      await withPreMigrationShape(async () => {
+        await ensureSentinelWorkspace();
+        await db.query(
+          `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+           VALUES (NULL, $1, '{}'::jsonb, now())`,
+          [`commerce.dunning_policy:${workspaceAId}`],
+        );
+
+        // workspaceAId is a real, well-formed, NON-sentinel wksp id — exactly
+        // the row the sentinel assignment would misfile. The guard aborts
+        // BEFORE the UPDATE, so a sentinel workspace being available here
+        // changes nothing.
+        // No explicit type argument here: `PgError` declares no `message`,
+        // and pinning one would force a cast. The matcher checks both the
+        // SQLSTATE and that the exception names the table it is about, so a
+        // P0001 raised by some other block cannot satisfy this.
+        await expect(db.query(siteSettingsGuardSql())).rejects.toMatchObject({
+          code: "P0001",
+          message: expect.stringContaining("site_settings"),
+        });
+      });
+    });
+
+    it("(b) ATTRIBUTES an unattributed row whose key embeds NO workspace id to the sentinel", async () => {
+      const aliasKey = `commerce.dunning_policy:default-${RUN}`;
+      const plainKey = `feature_flags-${RUN}`;
+      await withPreMigrationShape(async () => {
+        await ensureSentinelWorkspace();
+        // Both shapes the guard must let through: the bare alias the
+        // single-tenant build writes, and an ordinary config key naming no
+        // site at all.
+        await db.query(
+          `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+           VALUES (NULL, $1, '{}'::jsonb, now()), (NULL, $2, '{}'::jsonb, now())`,
+          [aliasKey, plainKey],
+        );
+
+        await expect(db.query(siteSettingsGuardSql())).resolves.toBeDefined();
+
+        // The slice ran guard -> UPDATE -> assertion, so these are ATTRIBUTED,
+        // not merely un-rejected.
+        expect(await attributedWorkspaceOf(aliasKey)).toBe(SENTINEL_WORKSPACE_ID);
+        expect(await attributedWorkspaceOf(plainKey)).toBe(SENTINEL_WORKSPACE_ID);
+      });
+    });
+
+    it("(c) ATTRIBUTES an unattributed row whose key embeds the SENTINEL id to the sentinel", async () => {
+      const key = `commerce.dunning_policy:${SENTINEL_WORKSPACE_ID}`;
+      await withPreMigrationShape(async () => {
+        await ensureSentinelWorkspace();
+        await db.query(
+          `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+           VALUES (NULL, $1, '{}'::jsonb, now())`,
+          [key],
+        );
+
+        await expect(db.query(siteSettingsGuardSql())).resolves.toBeDefined();
+
+        // A key already naming the sentinel is not a misfiling risk — it
+        // backfills to exactly the workspace its key names.
+        expect(await attributedWorkspaceOf(key)).toBe(SENTINEL_WORKSPACE_ID);
+      });
+    });
+
+    it("(d) is INERT on an already-migrated database — the verbatim re-run stays a no-op (NFR2)", async () => {
+      // No transaction and no DROP NOT NULL: this is the real, migrated table,
+      // where every row carries a workspace_id. The `IS NULL` guard makes the
+      // check match nothing, the UPDATE match nothing, and the assertion pass
+      // — which is what keeps AC-3's re-run clean even on a database whose
+      // keys embed non-sentinel ids.
+      const key = `commerce.dunning_policy:${workspaceAId}`;
+      await db.query(
+        `INSERT INTO "site_settings" ("workspace_id", "key", "value", "updated_at")
+         VALUES ($1, $2, '{}'::jsonb, now())`,
+        [workspaceAId, key],
+      );
+
+      await expect(db.query(siteSettingsGuardSql())).resolves.toBeDefined();
+
+      // Untouched: still its OWN workspace, never rewritten to the sentinel.
+      expect(await attributedWorkspaceOf(key)).toBe(workspaceAId);
+    });
+  });
+
+  describe("AC-5 — the fence is a CHECK, never a foreign key (NFR1)", () => {
+    it("deleting a workspaces row leaves that workspace's consent_grants rows in place", async () => {
+      await db.query(
+        `INSERT INTO "consent_grants"
+           ("site_id", "workspace_id", "subject_type", "subject_id", "purpose_id",
+            "granted", "locale", "statement", "statement_hash")
+         VALUES ($1, $1, 'subscriber', $2, $3, true, 'en', 'I agree', $4)`,
+        [workspaceCId, `cascade-${RUN}`, `purpose-${RUN}`, `hash-${RUN}`],
+      );
+
+      await db.query(`DELETE FROM "workspaces" WHERE "id" = $1`, [workspaceCId]);
+
+      const remaining = await db.query<{ count: string }>(
+        `SELECT count(*)::text AS count FROM "consent_grants" WHERE "site_id" = $1`,
+        [workspaceCId],
+      );
+      expect(remaining.rows[0]!.count).toBe("1");
+    });
+  });
+});