create-ailk 0.5.0 → 0.6.0

package/templates/database/jest.config.cjs

@@ -10,10 +10,12 @@ module.exports = {
     // ts-jest compiles it directly (#3958) — mirrors apps/api/jest.config.cjs's
     // identical mapping. The published dist is ESM-only and this package's
     // CJS ts-jest transform can't load it; database/flows/presets.ts's test
-    // needs the real flowConfigSchema value at runtime (a value import, not a
-    // type-only one — unlike ../tenancy.ts's `import type { Id }` from
-    // @working-theory/ids, which erases to nothing and needs no mapping).
+    // needs the real flowConfigSchema value at runtime.
     "^@working-theory/validation$": "<rootDir>/../packages/validation/src/index.ts",
+    // ../tenancy.ts's `isSentinel` import from @working-theory/ids became a
+    // VALUE import (#5876 spec D2/D11) — no longer type-only, so it DOES need
+    // a mapping now, same reason as the validation mapping above.
+    "^@working-theory/ids$": "<rootDir>/../packages/ids/src/index.ts",
     "^(\\.{1,2}/.*)\\.js$": "$1",
   },
   transform: {

package/templates/database/migrations/20260915120000_project_listing_solution/migration.sql

@@ -0,0 +1,15 @@
+-- The founder's "how are you solving it?" answer on `project_listings` (#5096).
+--
+-- `problem` (step five) has had a column since the surface shipped; its
+-- narrative other half has not, so samhenry PR #324's step six had nowhere to
+-- write.
+--
+-- ONE NULLABLE COLUMN, NO DEFAULT, NO BACKFILL, NO CHANGE TO ANY EXISTING ONE.
+-- Additive and opt-in: the field is absent from the platform's default
+-- `collectedFields` mask (#5096 DD1), so no existing site can have it written
+-- until that site names it. Every row written before this migration keeps a
+-- NULL here, which the row schema already allows for every application field
+-- (#5036 D1 — a half-filled draft is a legitimate row).
+--
+-- Rollback: ALTER TABLE "project_listings" DROP COLUMN "solution";
+ALTER TABLE "project_listings" ADD COLUMN "solution" TEXT;

package/templates/database/migrations/20260916120000_artifact_content_store/migration.sql

@@ -0,0 +1,158 @@
+-- #5800 — the Artifact content store: roadmap D1 (generalize `Artifact`) and
+-- D7 (`Asset`, workspace-scoped).
+--
+-- D1's one sentence: THE SESSION BECOMES PROVENANCE, THE WORKSPACE OWNS THE
+-- ARTIFACT. Today `artifacts.session_id` is NOT NULL behind an ON DELETE
+-- CASCADE, so deleting a conversation deletes the pages it produced. After this
+-- migration the column is nullable behind ON DELETE SET NULL: the session is
+-- where the artifact came from, not what keeps it alive.
+--
+-- The relaxation is bracketed by ZERO-ROW ASSERTIONS. It applies to an empty
+-- database and to a populated one, and each assertion names a specific way the
+-- relaxation could have lost data. A failed assertion aborts the transaction
+-- with a message that says which rows to look at — the migration never proceeds
+-- on a silent surprise, and it never backfills its way past one.
+--
+-- The rest is additive: four nullable-or-defaulted columns, two indexes, and a
+-- new `assets` table. `content_type` is BACKFILLED from the legacy `type`
+-- column rather than replacing it, because
+-- apps/api/src/routes/workspaces/sessions.ts (a hard-floor surface) reads
+-- `type` and must keep working unchanged; the two agree row-for-row when this
+-- migration commits, and retiring `type` belongs to the card that moves that
+-- route.
+--
+-- Rollback: drop the two indexes and the four columns, drop "assets", restore
+-- the FK as NOT NULL + ON DELETE CASCADE. That restore is only safe while no
+-- artifact has yet outlived its session.
+
+-- ── PRE-ASSERTIONS (zero rows, or this migration does not run) ──────────────
+DO $$
+DECLARE
+  already_null bigint;
+  orphaned     bigint;
+BEGIN
+  -- "session_id" is NOT NULL today. A non-zero count here means the column is
+  -- not the shape this migration was written against — stop rather than guess.
+  SELECT count(*) INTO already_null FROM "artifacts" WHERE "session_id" IS NULL;
+  IF already_null <> 0 THEN
+    RAISE EXCEPTION
+      '#5800 pre-assertion: % artifact row(s) already carry a NULL session_id before the FK was relaxed; the column was expected NOT NULL',
+      already_null;
+  END IF;
+
+  -- The outgoing FK is what guarantees this is zero. Proving it BEFORE the
+  -- swap is what lets the post-assertion below attribute any orphan to the
+  -- swap itself.
+  SELECT count(*) INTO orphaned
+    FROM "artifacts" a
+    LEFT JOIN "agent_sessions" s ON s."id" = a."session_id"
+   WHERE s."id" IS NULL;
+  IF orphaned <> 0 THEN
+    RAISE EXCEPTION
+      '#5800 pre-assertion: % artifact row(s) point at an agent_sessions row that does not exist',
+      orphaned;
+  END IF;
+END $$;
+
+-- The census the post-assertion compares against. ON COMMIT DROP: `prisma
+-- migrate` runs each migration in one transaction, so this disappears with it.
+CREATE TEMP TABLE "_5800_artifact_census" ON COMMIT DROP AS
+  SELECT count(*) AS n FROM "artifacts";
+
+-- ── The FK relaxation (D1) ─────────────────────────────────────────────────
+-- DropForeignKey
+ALTER TABLE "artifacts" DROP CONSTRAINT "artifacts_session_id_fkey";
+
+-- AlterTable
+ALTER TABLE "artifacts" ADD COLUMN     "content_type" TEXT NOT NULL DEFAULT 'text/document',
+ADD COLUMN     "locale" TEXT NOT NULL DEFAULT 'en',
+ADD COLUMN     "published_version_id" TEXT,
+ADD COLUMN     "slug" TEXT,
+ALTER COLUMN "session_id" DROP NOT NULL;
+
+-- AddForeignKey
+ALTER TABLE "artifacts" ADD CONSTRAINT "artifacts_session_id_fkey" FOREIGN KEY ("session_id") REFERENCES "agent_sessions"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- Backfill: the new discriminator starts life agreeing with the legacy one, so
+-- a pre-existing chat artifact reads identically through either column.
+UPDATE "artifacts" SET "content_type" = "type";
+
+-- ── POST-ASSERTIONS (zero rows lost, zero rows nulled, zero drift) ─────────
+DO $$
+DECLARE
+  before_n bigint;
+  after_n  bigint;
+  nulled   bigint;
+  drift    bigint;
+BEGIN
+  SELECT n INTO before_n FROM "_5800_artifact_census";
+  SELECT count(*) INTO after_n FROM "artifacts";
+  IF before_n <> after_n THEN
+    RAISE EXCEPTION
+      '#5800 post-assertion: artifact count changed across the FK relaxation (% -> %)',
+      before_n, after_n;
+  END IF;
+
+  -- Relaxing the constraint must not itself null anyone's provenance. Rows
+  -- become NULL later, one at a time, as sessions are deleted.
+  SELECT count(*) INTO nulled FROM "artifacts" WHERE "session_id" IS NULL;
+  IF nulled <> 0 THEN
+    RAISE EXCEPTION
+      '#5800 post-assertion: relaxing the FK left % artifact row(s) with a NULL session_id',
+      nulled;
+  END IF;
+
+  SELECT count(*) INTO drift
+    FROM "artifacts" WHERE "content_type" IS DISTINCT FROM "type";
+  IF drift <> 0 THEN
+    RAISE EXCEPTION
+      '#5800 post-assertion: % artifact row(s) disagree between content_type and the legacy type column',
+      drift;
+  END IF;
+END $$;
+
+-- ── Content-store identity + the list index (D1) ───────────────────────────
+-- CreateIndex
+CREATE INDEX "artifacts_workspace_id_content_type_updated_at_idx" ON "artifacts"("workspace_id", "content_type", "updated_at");
+
+-- CreateIndex
+-- `slug` is NULL until publish and NULLs never collide in a Postgres unique
+-- index, so a workspace may hold any number of unpublished drafts while
+-- exactly one artifact may claim a given published path.
+CREATE UNIQUE INDEX "artifacts_workspace_id_content_type_locale_slug_key" ON "artifacts"("workspace_id", "content_type", "locale", "slug");
+
+-- ── Asset (D7) ─────────────────────────────────────────────────────────────
+-- Shaped after `deliverable_assets` (20260811050000_add_deliverable_models):
+-- the bytes live in the row. Same CreateTable + CreateIndex + ADR-0031 rule-3
+-- id-format completion in ONE migration as
+-- 20260911180000_consent_grants, since the table is new and needs no retrofit.
+-- CreateTable
+CREATE TABLE "assets" (
+    "id" TEXT NOT NULL DEFAULT ('asset_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "filename" TEXT NOT NULL,
+    "content_type" TEXT NOT NULL,
+    "bytes" BYTEA NOT NULL,
+    "size" INTEGER NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "assets_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "assets_workspace_id_idx" ON "assets"("workspace_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "assets_workspace_id_key_key" ON "assets"("workspace_id", "key");
+
+-- ADR-0031 rule 3 — assets: asset_ (registered in
+-- packages/ids/src/registry.ts ENTITY_PREFIX.asset; this migration's path is
+-- added to migration-sync.test.ts's PK_CHECK_MIGRATIONS). workspace_id is a
+-- relation-free scope column (ADR-0009 invariant 1) and gets the same CHECK
+-- every other content-namespace table's does.
+ALTER TABLE "assets" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "assets" ALTER COLUMN "id" SET DEFAULT ('asset_'::text || (uuidv7())::text);
+ALTER TABLE "assets" ADD CONSTRAINT "assets_id_format" CHECK ("id" ~ '^asset_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "assets" ALTER COLUMN "workspace_id" TYPE text COLLATE "C";
+ALTER TABLE "assets" ADD CONSTRAINT "assets_workspace_id_format" CHECK ("workspace_id" ~ '^wksp_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');

package/templates/database/migrations/20260917120000_callback_request_confirm/migration.sql

@@ -0,0 +1,40 @@
+-- #5970 — request-and-confirm: the callback row gains a confirm/pay lifecycle
+-- (D-67 / SUB-100, spec docs/specs/5970-request-and-confirm-spec.md § 4.3).
+--
+-- Eleven nullable columns and two indexes on "callbacks". Every column is
+-- NULL-able with no default, so on Postgres this ALTER TABLE is metadata-only:
+-- no table rewrite, no backfill, no lock held for the length of a scan.
+--
+-- Nothing here relaxes a constraint and nothing here backfills, so — unlike
+-- 20260916120000_artifact_content_store — this migration carries no zero-row
+-- pre-assertion block: there is no way for it to lose a row.
+--
+-- The two indexes are the webhook stamp's `where` (spec § D8). Without them
+-- every checkout.session.completed carrying a payment_link would sequential-
+-- scan "callbacks" on a hot path. "stripe_checkout_session_id" carries no
+-- index deliberately: nothing queries by it — it is a support-lookup column.
+--
+-- Rollback: drop the two indexes and the eleven columns. Safe unconditionally
+-- while nothing but #5970's own code reads them.
+
+ALTER TABLE "callbacks"
+  ADD COLUMN "confirm_token_hash" TEXT,
+  ADD COLUMN "confirm_token_expires_at" TIMESTAMP(3),
+  ADD COLUMN "confirmed_at" TIMESTAMP(3),
+  ADD COLUMN "confirmed_time" TEXT,
+  ADD COLUMN "buyer_email" TEXT,
+  ADD COLUMN "amount_minor" INTEGER,
+  ADD COLUMN "currency" TEXT,
+  ADD COLUMN "stripe_payment_link_id" TEXT,
+  ADD COLUMN "stripe_checkout_session_id" TEXT,
+  ADD COLUMN "stripe_invoice_id" TEXT,
+  ADD COLUMN "paid_at" TIMESTAMP(3);
+
+-- The digest is unique: two rows sharing one is a mint bug, and the constraint
+-- is what turns that bug into a write failure instead of a silent cross-row
+-- credential.
+CREATE UNIQUE INDEX "callbacks_confirm_token_hash_key" ON "callbacks"("confirm_token_hash");
+
+CREATE INDEX "callbacks_stripe_payment_link_id_idx" ON "callbacks"("stripe_payment_link_id");
+
+CREATE INDEX "callbacks_stripe_invoice_id_idx" ON "callbacks"("stripe_invoice_id");

package/templates/database/migrations/20260918120000_add_appointment/migration.sql

@@ -0,0 +1,67 @@
+-- #6085 — the Appointment model: a Cal.com booking normalized from the new
+-- webhook receiver (brief H7, spec docs/specs/6085-appointments-from-cal-com-webhooks-spec.md § 4.3).
+--
+-- One new table, three indexes, in the house style of
+-- 20260903010000_add_playbook_instance (CreateTable + CreateIndex immediately
+-- followed by the ADR-0031 rule-3 id-format completion, in ONE migration
+-- since the table is new and needs no retrofit).
+--
+-- The unique index over (site_id, provider, provider_booking_uid) is the
+-- LOAD-BEARING line of this migration: it is the spec's own idempotency key
+-- (§ D4) — a table without it makes "exactly one Appointment row per booking
+-- uid" unenforceable, and § D7(a)'s guarded-write shape races on precisely
+-- this index.
+--
+-- No backfill, no constraint relaxed, no existing table touched, so this
+-- migration carries no zero-row pre-assertion block — there is no way for it
+-- to lose a row.
+--
+-- Rollback: DROP TABLE "appointments". Safe unconditionally while nothing but
+-- #6085's own code reads it.
+
+-- CreateTable
+CREATE TABLE "appointments" (
+    "id" TEXT NOT NULL DEFAULT ('appt_'::text || (uuidv7())::text),
+    "site_id" VARCHAR(200) NOT NULL,
+    "provider_booking_uid" VARCHAR(200) NOT NULL,
+    "provider" VARCHAR(32) NOT NULL DEFAULT 'cal',
+    "start_time" TIMESTAMP(3) NOT NULL,
+    "end_time" TIMESTAMP(3) NOT NULL,
+    "title" VARCHAR(300),
+    "attendee_name" VARCHAR(120) NOT NULL,
+    "attendee_email" VARCHAR(254) NOT NULL,
+    "attendee_time_zone" VARCHAR(64),
+    "status" VARCHAR(32) NOT NULL,
+    "paid" BOOLEAN NOT NULL DEFAULT false,
+    "payment_initiated_at" TIMESTAMP(3),
+    "no_show" BOOLEAN NOT NULL DEFAULT false,
+    "cancelled_at" TIMESTAMP(3),
+    "lifecycle_event_at" TIMESTAMP(3) NOT NULL,
+    "payment_event_at" TIMESTAMP(3),
+    "no_show_event_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "appointments_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- The idempotency key (§ D4) — see the file header. `provider` is included
+-- per § 9 SEC-10 so a second scheduling provider's uid space cannot collide
+-- with this one's (#4288).
+CREATE UNIQUE INDEX "appointments_site_id_provider_provider_booking_uid_key" ON "appointments"("site_id", "provider", "provider_booking_uid");
+
+-- CreateIndex
+-- The read's `where` + `order by` (§ D6). Without it every appointments page
+-- load sequential-scans "appointments".
+CREATE INDEX "appointments_site_id_start_time_idx" ON "appointments"("site_id", "start_time");
+
+-- CreateIndex
+CREATE INDEX "appointments_created_at_idx" ON "appointments"("created_at");
+
+-- ADR-0031 rule 3 — appointments: appt_ (registered in
+-- packages/ids/src/registry.ts ENTITY_PREFIX.appointment; this migration's
+-- path is added to migration-sync.test.ts's PK_CHECK_MIGRATIONS).
+ALTER TABLE "appointments" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "appointments" ALTER COLUMN "id" SET DEFAULT ('appt_'::text || (uuidv7())::text);
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_id_format" CHECK ("id" ~ '^appt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');

package/templates/database/migrations/20260918120000_asset_metadata_columns/migration.sql

@@ -0,0 +1,70 @@
+-- #6092 — S4's data tier: an asset carries title, description and tags.
+--
+-- Today `assets` holds bytes and a filename and nothing the owner wrote
+-- (decisions.html D10: "an asset has a filename and dimensions only"). The
+-- lightbox edits three things in place — a title, a description and a set of
+-- tags — so the table gains exactly those three columns.
+--
+-- STRICTLY ADDITIVE. Nothing is dropped, renamed, relaxed or backfilled. The
+-- `(workspace_id, key)` identity, the `assets_id_format` and
+-- `assets_workspace_id_format` CHECKs and the `asset_`+UUIDv7 default are all
+-- untouched, so a pre-existing row stays valid and an INSERT written before
+-- this migration keeps working unchanged.
+--
+-- `tags` is TEXT[] with an empty-array default rather than a nullable column:
+-- an untagged asset is an empty set, not an unknown one, and a NULL would give
+-- two spellings of the same state. It carries tag SLUGS, never the human
+-- labels, and it is deliberately UNCONSTRAINED — two vocabularies ride it (the
+-- twelve asset tags and D9's four document tags, since a document is a row in
+-- this same store), and the "fixed set" of D10 is a surface affordance. A tag
+-- whose slug a surface cannot resolve is that surface's problem to render, not
+-- a reason to reject an upload.
+--
+-- `title` and `description` are nullable with no default: NULL means the owner
+-- has not written one, which is distinct from an empty string meaning they
+-- cleared it. `title` is NOT backfilled from `filename` — they are different
+-- facts and the lightbox shows both.
+--
+-- Rollback: ALTER TABLE "assets" DROP COLUMN "tags", DROP COLUMN
+-- "description", DROP COLUMN "title". Safe unconditionally; the columns carry
+-- no constraint and nothing references them.
+
+-- The census the post-assertion compares against. ON COMMIT DROP: `prisma
+-- migrate` runs each migration in one transaction, so this disappears with it.
+CREATE TEMP TABLE "_6092_asset_census" ON COMMIT DROP AS
+  SELECT count(*) AS n FROM "assets";
+
+-- AlterTable
+ALTER TABLE "assets" ADD COLUMN     "title" TEXT,
+ADD COLUMN     "description" TEXT,
+ADD COLUMN     "tags" TEXT[] DEFAULT ARRAY[]::TEXT[];
+
+-- ── POST-ASSERTIONS (no row lost; every pre-existing row reads back empty) ──
+-- This is AC-1's second half, asserted against the rows the target database
+-- actually holds rather than against a fixture's.
+DO $$
+DECLARE
+  before_n bigint;
+  after_n  bigint;
+  written  bigint;
+BEGIN
+  SELECT n INTO before_n FROM "_6092_asset_census";
+  SELECT count(*) INTO after_n FROM "assets";
+  IF before_n <> after_n THEN
+    RAISE EXCEPTION
+      '#6092 post-assertion: asset count changed across a purely additive migration (% -> %)',
+      before_n, after_n;
+  END IF;
+
+  -- Adding the columns must not itself author metadata for anyone. Rows gain a
+  -- title, a description or a tag later, one at a time, from the lightbox.
+  SELECT count(*) INTO written FROM "assets"
+   WHERE "title" IS NOT NULL
+      OR "description" IS NOT NULL
+      OR "tags" IS DISTINCT FROM ARRAY[]::TEXT[];
+  IF written <> 0 THEN
+    RAISE EXCEPTION
+      '#6092 post-assertion: % pre-existing asset row(s) came out of the migration with metadata already set',
+      written;
+  END IF;
+END $$;

package/templates/database/migrations/20260919120000_flow_workspace_key/migration.sql

@@ -0,0 +1,181 @@
+-- #6155 — FlowDefinition and FlowSession gain a workspace isolation key.
+--
+-- The ownership brief (docs/internal/decisions/workspace-owns-data-surfaces-render.md)
+-- and AD-2 (docs/internal/decisions/flow-engine-admin-surface.md): a workspace
+-- owns data, and the flow engine's tenant-scope fence grows to cover it.
+-- `siteId` stays a legacy alias for the public path (unchanged); `workspaceId`
+-- is the isolation key every authenticated read/write will go through
+-- (apps/api/src/lib/tenant-db.ts's new `flows`/`flowSessions` accessors).
+--
+-- NULLABLE, no default (spec D3) — a row whose `siteId` matches no workspace
+-- is left UNSET rather than guessed, and stays invisible to every accessor
+-- rather than visible to the wrong tenant (the same "fails empty, never
+-- wide" posture apps/api/src/services/leads-inbox.ts already takes).
+--
+-- RE-RUNNABLE (NFR3): `ADD COLUMN IF NOT EXISTS` / `CREATE INDEX IF NOT
+-- EXISTS` cover the column and index. Postgres has no
+-- `ADD CONSTRAINT IF NOT EXISTS`, so each format CHECK is wrapped in its own
+-- existence-guarded `DO $$` block — the stated exception to NFR3's "in the
+-- house style of 20260918120000_asset_metadata_columns" note: that
+-- precedent (and 20260713192429_prefixed_uuid_entity_ids's own CHECK
+-- additions) rely on `prisma migrate`'s per-migration transaction and
+-- ledger, not on idempotent DDL — the guard below is this migration's own
+-- addition.
+--
+-- Rollback: DROP INDEX "flow_definitions_workspace_id_idx",
+-- "flow_sessions_workspace_id_idx"; ALTER TABLE "flow_definitions" DROP
+-- CONSTRAINT "flow_definitions_workspace_id_format", DROP COLUMN
+-- "workspace_id"; ALTER TABLE "flow_sessions" DROP CONSTRAINT
+-- "flow_sessions_workspace_id_format", DROP COLUMN "workspace_id". Safe
+-- unconditionally at this pin — nothing reads the column until #6156+.
+
+-- The census the post-assertions compare against. ON COMMIT DROP: `prisma
+-- migrate` runs each migration in one transaction, so this disappears with it.
+CREATE TEMP TABLE "_6155_flow_census" ON COMMIT DROP AS
+  SELECT (SELECT count(*) FROM "flow_definitions") AS d,
+         (SELECT count(*) FROM "flow_sessions")    AS s;
+
+-- AlterTable
+ALTER TABLE "flow_definitions" ADD COLUMN IF NOT EXISTS "workspace_id" TEXT;
+ALTER TABLE "flow_sessions"    ADD COLUMN IF NOT EXISTS "workspace_id" TEXT;
+
+-- Format CHECKs — NULL-permitting, in the exact shape of the CHECKs
+-- 20260713192429_prefixed_uuid_entity_ids/migration.sql:170-197 already
+-- applies to every other `workspace_id` column. Existence-guarded because
+-- Postgres has no `ADD CONSTRAINT IF NOT EXISTS`.
+DO $$ BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'flow_definitions_workspace_id_format'
+  ) THEN
+    ALTER TABLE "flow_definitions" ADD CONSTRAINT "flow_definitions_workspace_id_format"
+      CHECK ("workspace_id" IS NULL OR "workspace_id" ~ '^wksp_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+  END IF;
+END $$;
+
+DO $$ BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'flow_sessions_workspace_id_format'
+  ) THEN
+    ALTER TABLE "flow_sessions" ADD CONSTRAINT "flow_sessions_workspace_id_format"
+      CHECK ("workspace_id" IS NULL OR "workspace_id" ~ '^wksp_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+  END IF;
+END $$;
+
+-- CreateIndex
+CREATE INDEX IF NOT EXISTS "flow_definitions_workspace_id_idx" ON "flow_definitions"("workspace_id");
+CREATE INDEX IF NOT EXISTS "flow_sessions_workspace_id_idx" ON "flow_sessions"("workspace_id");
+
+-- ── Backfill (spec D2) ──────────────────────────────────────────────────────
+-- Both spellings of the alias, one statement per table. The literal alias
+-- "default" resolves to the seeded sentinel workspace
+-- (database/tenancy.ts DEFAULT_WORKSPACE_ID); every other alias resolves
+-- only by exact workspaces.id equality. An inner join to "workspaces" means a
+-- row whose alias resolves to nothing is simply not updated and stays NULL
+-- — the correct, stated behavior (D3), not an error.
+--
+-- The sentinel id is written as a literal because SQL cannot import
+-- database/tenancy.ts; database/__tests__/tenancy.test.ts pins the same
+-- literal against the exported constant so the two cannot drift.
+UPDATE "flow_definitions" f
+   SET "workspace_id" = w."id"
+  FROM "workspaces" w
+ WHERE f."workspace_id" IS NULL
+   AND w."id" = CASE WHEN f."site_id" = 'default'
+                      THEN 'wksp_00000000-0000-7000-8000-000000000001'
+                      ELSE f."site_id" END;
+
+UPDATE "flow_sessions" f
+   SET "workspace_id" = w."id"
+  FROM "workspaces" w
+ WHERE f."workspace_id" IS NULL
+   AND w."id" = CASE WHEN f."site_id" = 'default'
+                      THEN 'wksp_00000000-0000-7000-8000-000000000001'
+                      ELSE f."site_id" END;
+
+-- ── POST-ASSERTIONS ─────────────────────────────────────────────────────────
+-- AC-1's own enforcement: nothing lost, nothing guessed, nothing missed that
+-- was resolvable. The fourth check is a NOTICE, not an exception — an
+-- unpinned/unseeded deployment leaving rows NULL is the expected, documented
+-- case (spec § 1.3), never an error this migration should refuse to run over.
+DO $$
+DECLARE
+  before_d bigint;
+  before_s bigint;
+  after_d  bigint;
+  after_s  bigint;
+  guessed  bigint;
+  missed   bigint;
+  null_d   bigint;
+  null_s   bigint;
+BEGIN
+  SELECT d, s INTO before_d, before_s FROM "_6155_flow_census";
+  SELECT count(*) INTO after_d FROM "flow_definitions";
+  SELECT count(*) INTO after_s FROM "flow_sessions";
+
+  -- 1. Nothing lost: row counts unchanged on both tables.
+  IF before_d <> after_d OR before_s <> after_s THEN
+    RAISE EXCEPTION
+      '#6155 post-assertion: row count changed across a purely additive migration (flow_definitions % -> %, flow_sessions % -> %)',
+      before_d, after_d, before_s, after_s;
+  END IF;
+
+  -- 2. Nothing guessed: no row's workspace_id was set to a value absent
+  --    from "workspaces" (the inner-join backfill above cannot produce this
+  --    on its own, but a re-run against a database missing the sentinel row
+  --    must never leave a dangling reference).
+  SELECT count(*) INTO guessed FROM "flow_definitions" f
+   WHERE f."workspace_id" IS NOT NULL
+     AND NOT EXISTS (SELECT 1 FROM "workspaces" w WHERE w."id" = f."workspace_id");
+  IF guessed <> 0 THEN
+    RAISE EXCEPTION
+      '#6155 post-assertion: % flow_definitions row(s) carry a workspace_id absent from workspaces',
+      guessed;
+  END IF;
+  SELECT count(*) INTO guessed FROM "flow_sessions" f
+   WHERE f."workspace_id" IS NOT NULL
+     AND NOT EXISTS (SELECT 1 FROM "workspaces" w WHERE w."id" = f."workspace_id");
+  IF guessed <> 0 THEN
+    RAISE EXCEPTION
+      '#6155 post-assertion: % flow_sessions row(s) carry a workspace_id absent from workspaces',
+      guessed;
+  END IF;
+
+  -- 3. Nothing missed: no row whose site_id names a workspace that actually
+  --    exists came out of the backfill with workspace_id still NULL.
+  SELECT count(*) INTO missed FROM "flow_definitions" f
+   WHERE f."workspace_id" IS NULL
+     AND EXISTS (
+       SELECT 1 FROM "workspaces" w
+        WHERE w."id" = CASE WHEN f."site_id" = 'default'
+                             THEN 'wksp_00000000-0000-7000-8000-000000000001'
+                             ELSE f."site_id" END
+     );
+  IF missed <> 0 THEN
+    RAISE EXCEPTION
+      '#6155 post-assertion: % flow_definitions row(s) had a resolvable site_id but came out of the backfill NULL',
+      missed;
+  END IF;
+  SELECT count(*) INTO missed FROM "flow_sessions" f
+   WHERE f."workspace_id" IS NULL
+     AND EXISTS (
+       SELECT 1 FROM "workspaces" w
+        WHERE w."id" = CASE WHEN f."site_id" = 'default'
+                             THEN 'wksp_00000000-0000-7000-8000-000000000001'
+                             ELSE f."site_id" END
+     );
+  IF missed <> 0 THEN
+    RAISE EXCEPTION
+      '#6155 post-assertion: % flow_sessions row(s) had a resolvable site_id but came out of the backfill NULL',
+      missed;
+  END IF;
+
+  -- 4. A NOTICE, never an exception: an unpinned/unseeded deployment leaving
+  --    rows NULL is the expected, documented case (spec § 1.3).
+  SELECT count(*) INTO null_d FROM "flow_definitions" WHERE "workspace_id" IS NULL;
+  SELECT count(*) INTO null_s FROM "flow_sessions" WHERE "workspace_id" IS NULL;
+  IF null_d <> 0 OR null_s <> 0 THEN
+    RAISE NOTICE
+      '#6155: % flow_definitions row(s) and % flow_sessions row(s) left workspace_id unset — their site_id did not resolve to a workspace this database holds',
+      null_d, null_s;
+  END IF;
+END $$;