create-ailk 0.18.0 → 0.19.1

package/templates/database/inbox/schema.prisma

@@ -81,6 +81,18 @@ model Lead {
   // Backfilled by database/migrations/20261010121000_person_backfill.
   personId String? @map("person_id")
 
+  // #8185 D1 — the hub's conclusion, at write time, that this lead is a
+  // spoke's LIVE paid checkout: the submit carried a registered spoke's key,
+  // was not relayed for a visitor, and passed the #7877 checkout plan rule's
+  // own predicate (a `cs_live_` Idempotency-Key and the checkout shape).
+  // Written only by `apps/api/src/services/lead-routing.ts`'s submit create
+  // and never updated; read only by `apps/api/src/lib/member-store.ts`'s
+  // `listMemberPurchases`, which serves a marked lead as a purchase. A lead
+  // written before the column existed reads false: `viaSpoke` was never
+  // stored, so its provenance cannot be proven (no backfill). No index: the
+  // read filters by the already-indexed `personId`.
+  spokeCheckout Boolean @default(false) @map("spoke_checkout")
+
   // #7869 — the idempotency guarantee, scoped per workspace so a key can
   // never reach another tenant's row.
   @@unique([workspaceId, idempotencyKey])
@@ -115,19 +127,41 @@ model Lead {
 /// writer wins. `planOffering` is written by a later phase (Epic 2's
 /// checkout-lead rule); this slice only carries the column.
 model Person {
-  id                String   @id @default(dbgenerated("('person_'::text || (uuidv7())::text)")) @db.Text
-  workspaceId       String   @map("workspace_id")
-  email             String   @db.VarChar(254)
-  name              String?  @db.VarChar(200)
-  userId            String?  @map("user_id")
-  billingProvider   String?  @map("billing_provider") @db.VarChar(32)
-  billingCustomerId String?  @map("billing_customer_id") @db.VarChar(255)
-  planOffering      String?  @map("plan_offering") @db.VarChar(100)
-  createdAt         DateTime @default(now()) @map("created_at")
-  updatedAt         DateTime @updatedAt @map("updated_at")
+  id                 String    @id @default(dbgenerated("('person_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId        String    @map("workspace_id")
+  email              String    @db.VarChar(254)
+  name               String?   @db.VarChar(200)
+  userId             String?   @map("user_id")
+  billingProvider    String?   @map("billing_provider") @db.VarChar(32)
+  billingCustomerId  String?   @map("billing_customer_id") @db.VarChar(255)
+  planOffering       String?   @map("plan_offering") @db.VarChar(100)
+  // #8435 D1 — contact details, to the standard (option A). Every column is
+  // nullable: a capture fills only a blank one (D4), an edit overwrites (D9,
+  // D11). The address is the magnet's six parts, stored whole or not at all
+  // (people_address_complete).
+  givenName          String?   @map("given_name") @db.VarChar(100)
+  familyName         String?   @map("family_name") @db.VarChar(100)
+  telephone          String?   @db.VarChar(16)
+  addressLine1       String?   @map("address_line1") @db.VarChar(100)
+  addressLine2       String?   @map("address_line2") @db.VarChar(60)
+  addressCity        String?   @map("address_city") @db.VarChar(60)
+  addressRegion      String?   @map("address_region") @db.VarChar(40)
+  addressPostalCode  String?   @map("address_postal_code") @db.VarChar(20)
+  addressCountry     String?   @map("address_country") @db.Char(2)
+  companyName        String?   @map("company_name") @db.VarChar(200)
+  jobTitle           String?   @map("job_title") @db.VarChar(100)
+  // Who last saved the contact by hand — "operator" (the Person page) or
+  // "client" (their account) — and when. NULL until a human saves it; while
+  // NULL and `userId` is NULL, a capture may fill a blank field (D4).
+  contactConfirmedAt DateTime? @map("contact_confirmed_at")
+  contactConfirmedBy String?   @map("contact_confirmed_by") @db.VarChar(16)
+  createdAt          DateTime  @default(now()) @map("created_at")
+  updatedAt          DateTime  @updatedAt @map("updated_at")
 
   pieces       Piece[]
   interactions Interaction[]
+  callbacks    Callback[]
+  subscribers  Subscriber[]
 
   @@unique([workspaceId, email])
   @@unique([workspaceId, userId])
@@ -144,36 +178,92 @@ model Person {
 /// tenantDb(tenant).memberArea; read by a client only through
 /// lib/member-store.ts. `stage` is one of the workspace's declared stages
 /// (WorkspacePieceStages), checked at write time, never an enum.
+///
+/// #8168 D5 — `approvedAt` is set in the same transaction as an `approved`
+/// review of the latest PieceVersion and freezes review: once set, no further
+/// review lands. Approval is a piece-level fact; the version's own `review`
+/// records which version was approved.
 model Piece {
-  id          String   @id @default(dbgenerated("('piece_'::text || (uuidv7())::text)")) @db.Text
-  workspaceId String   @map("workspace_id")
-  personId    String   @map("person_id")
-  title       String   @db.VarChar(200)
-  stage       String   @db.VarChar(40)
-  needsClient Boolean  @default(false) @map("needs_client")
-  updatedBy   String   @map("updated_by")
-  createdAt   DateTime @default(now()) @map("created_at")
-  updatedAt   DateTime @updatedAt @map("updated_at")
+  id          String    @id @default(dbgenerated("('piece_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String    @map("workspace_id")
+  personId    String    @map("person_id")
+  title       String    @db.VarChar(200)
+  stage       String    @db.VarChar(40)
+  needsClient Boolean   @default(false) @map("needs_client")
+  updatedBy   String    @map("updated_by")
+  approvedAt  DateTime? @map("approved_at")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  updatedAt   DateTime  @updatedAt @map("updated_at")
 
-  person Person @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "pieces_person_fk")
+  person   Person         @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "pieces_person_fk")
+  versions PieceVersion[]
 
   @@index([workspaceId, personId, createdAt])
+  // #8168 D1 — redundant with the PK, load-bearing as the target of
+  // piece_versions_piece_fk: a version names a piece of THIS Person in THIS
+  // workspace, as one database fact.
+  @@unique([id, personId, workspaceId])
   @@map("pieces")
 }
 
-/// Interaction — one message on a client's record (#7877): the original CRM
-/// spec's Interaction cut to one channel and one direction. An inbound reply
-/// is a later second `direction` value on this table. `readAt` is when a
-/// member read FIRST served the row to the client's spoke — a delivery
-/// stamp, not proof a human read it.
+/// PieceVersion — one delivery of a piece to its client (#8168 D1, D2): a
+/// file (`assetId`, a private library asset of the same workspace) or a link
+/// (`link`, https only), never both, numbered from 1 per piece. The client's
+/// review of it (`review`, `reviewComment`, `reviewedAt`) is recorded on the
+/// version itself. There is NO round count, limit or remaining-count column,
+/// by design (#8140 disposition 3).
+///
+/// Its one relation is the three-column FK onto `pieces(id, person_id,
+/// workspace_id)`, so the piece, its Person and the workspace are all one
+/// database fact. `assetId` and `deliveredBy` name rows of other namespaces:
+/// plain columns with format CHECKs, no foreign key (ADR 0009).
+model PieceVersion {
+  id            String    @id @default(dbgenerated("('pver_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId   String    @map("workspace_id")
+  personId      String    @map("person_id")
+  pieceId       String    @map("piece_id")
+  version       Int
+  assetId       String?   @map("asset_id")
+  link          String?   @db.VarChar(2048)
+  note          String?   @db.Text
+  deliveredBy   String    @map("delivered_by")
+  deliveredAt   DateTime  @default(now()) @map("delivered_at")
+  review        String?   @db.VarChar(24)
+  reviewComment String?   @map("review_comment") @db.Text
+  reviewedAt    DateTime? @map("reviewed_at")
+
+  piece Piece @relation(fields: [pieceId, personId, workspaceId], references: [id, personId, workspaceId], onDelete: Restrict, map: "piece_versions_piece_fk")
+
+  @@unique([pieceId, version])
+  // A client's artifacts: workspace_id = $1 AND person_id = $2 ORDER BY delivered_at DESC.
+  @@index([workspaceId, personId, deliveredAt])
+  // The public asset read's "is this asset a version file" check (AC-MAA-21).
+  @@index([assetId])
+  @@map("piece_versions")
+}
+
+/// Interaction — one entry on a client's record (#7877): the original CRM
+/// spec's Interaction cut to one channel. `readAt` is when a member read
+/// FIRST served the row to the client's spoke — a delivery stamp, not proof a
+/// human read it.
+///
+/// #8168 D3/D4 — `direction` is `outbound` (an operator's message, #7877) or
+/// `inbound` (a client's own write); `kind` is `message`, `quote` or
+/// `review`. An outbound row is always a `message` with no `payload`
+/// (`interactions_outbound_shape`); a `quote` or `review` row carries the
+/// stored payload `packages/validation`'s member.ts types. Every existing
+/// reader filters to `direction: "outbound"`, so an inbound row is invisible
+/// to them until a reader opts in.
 model Interaction {
   id          String    @id @default(dbgenerated("('intx_'::text || (uuidv7())::text)")) @db.Text
   workspaceId String    @map("workspace_id")
   personId    String    @map("person_id")
   channel     String    @db.VarChar(16)
   direction   String    @db.VarChar(16)
+  kind        String    @default("message") @db.VarChar(16)
   subject     String    @db.VarChar(200)
   body        String    @db.Text
+  payload     Json?
   assetId     String?   @map("asset_id")
   createdBy   String    @map("created_by")
   createdAt   DateTime  @default(now()) @map("created_at")
@@ -201,9 +291,14 @@ model Subscriber {
   email     String
   source    String
   createdAt DateTime @default(now()) @map("created_at")
+  // #8435 D1/D5 — the Person this subscription belongs to; composite FK onto
+  // people(id, workspace_id), the #7877 shape. NULL is not checked.
+  personId  String?  @map("person_id")
+  person    Person?  @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "subscribers_person_fk")
 
   @@unique([siteId, email])
   @@index([siteId])
+  @@index([personId])
   @@index([workspaceId])
   @@map("subscribers")
 }
@@ -270,7 +365,14 @@ model Callback {
   /// that update IS the durable idempotency key.
   paidAt                  DateTime? @map("paid_at")
 
+  // #8435 D1/D5 — the Person this request belongs to (its payload.email, or
+  // the buyer email at confirm). Composite FK onto people(id, workspace_id):
+  // "a Person of the same workspace" is a database fact. NULL is not checked.
+  personId                String?   @map("person_id")
+  person                  Person?   @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "callbacks_person_fk")
+
   @@index([siteId])
+  @@index([personId])
   @@index([createdAt])
   @@index([stripePaymentLinkId])
   @@index([stripeInvoiceId])
@@ -338,6 +440,13 @@ model FlowDefinition {
   // across the namespace boundary, so this is a plain string — but a stated
   // one rather than a coincidence.
   listingId String?  @map("listing_id")
+  /// #8168 D7 — whether a signed-in client may submit this magnet from the
+  /// member area. A column, not a config block, because a spoke seed refuses
+  /// non-seedable config (#7876); `upsertFlowDefinition` never names it, so a
+  /// seed never changes it. Independent of `status`: the seeded
+  /// `request-quote` magnet is `draft` (never served anonymously) with
+  /// `customersEnabled = true`.
+  customersEnabled Boolean @default(false) @map("customers_enabled")
   createdAt DateTime @default(now()) @map("created_at")
   updatedAt DateTime @updatedAt @map("updated_at")
 
@@ -1168,6 +1277,18 @@ model ConsentGrant {
   locale        String
   statement     String   @db.Text
   statementHash String   @map("statement_hash")
+  // #8438 D2 — the Person this row counts toward. A plain scalar with no
+  // foreign key (this table's own D10 posture): a row about a visitor or a
+  // listing has none, and a ledger row must outlive anything it names.
+  personId      String?  @map("person_id")
+  // #8438 D2 — where the answer came from (CONSENT_SOURCES). NOT NULL with no
+  // default after the migration: every new row must say. Rows stored before
+  // this column read `legacy`.
+  source        String   @db.Text
+  // The magnet slug when `source` is `magnet`.
+  sourceRef     String?  @map("source_ref") @db.VarChar(200)
+  // The registry's policy version the person read. NULL only for `legacy` rows.
+  policyVersion Int?     @map("policy_version")
   createdAt     DateTime @default(now()) @map("created_at")
 
   // "What did this subject agree to" — every row for one subject, newest last.
@@ -1175,9 +1296,29 @@ model ConsentGrant {
   // "Who agreed to this purpose" — the cross-surface count the id exists for (D1/D2).
   @@index([siteId, purposeId])
   @@index([workspaceId])
+  // #8438 D2 — "current state per purpose" for one Person (DISTINCT ON).
+  @@index([workspaceId, personId, purposeId, createdAt])
   @@map("consent_grants")
 }
 
+// #8438 D2 — links a banner visitor (a random browser-held id) to the Person a
+// later form or sign-in identifies, so the Person's cookie history can include
+// the visitor's own rows without ever editing them. Append-only like the
+// ledger: a database trigger refuses any change to a stored row. No relation
+// directive (ADR-0009 invariant #1); no IP, user-agent or device column.
+model ConsentVisitorLink {
+  id          String   @id @default(dbgenerated("('cvlink_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String   @map("workspace_id")
+  visitorId   String   @map("visitor_id")
+  personId    String   @map("person_id")
+  source      String   @db.Text
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  @@unique([workspaceId, visitorId, personId])
+  @@index([workspaceId, personId])
+  @@map("consent_visitor_links")
+}
+
 /// Appointment — a Cal.com booking, normalized from the webhook receiver (#6085, brief H7).
 ///
 /// siteId-scoped with no FK, like every other inbox model (ADR 0009 D2). The

package/templates/database/migrations/20261012120000_member_contract/migration.sql

@@ -0,0 +1,192 @@
+-- #8168 — the member area data model (spec
+-- docs/specs/8168-member-area-data-model-spec.md D1–D3, D5, D7–D9, D12).
+--
+--   piece_versions (inbox)          — one delivery of a piece to its client:
+--                                     a private library file OR an https
+--                                     link, numbered from 1 per piece, with
+--                                     the client's review recorded on it.
+--                                     NO round count, limit or remaining
+--                                     column (#8140 disposition 3).
+--   pieces.approved_at              — set with an `approved` review; freezes
+--                                     review (D5).
+--   pieces_id_person_id_workspace_id_key — a unique index over a triple the
+--                                     PK already makes unique: the target of
+--                                     piece_versions_piece_fk, so "a piece of
+--                                     THIS Person in THIS workspace" is one
+--                                     database fact (D1).
+--   interactions.kind / .payload    — `message` · `quote` · `review`, and the
+--                                     stored payload of a quote or review;
+--                                     `inbound` joins `outbound` (D3). An
+--                                     outbound row stays a payload-free
+--                                     `message` — #7877's rows, unchanged.
+--   flow_definitions.customers_enabled — whether a signed-in client may submit
+--                                     the magnet from the member area (D7).
+--   the `request-quote` magnet      — one draft `contact` magnet with
+--                                     customers_enabled = true, backfilled
+--                                     into EVERY existing workspace (D8).
+--
+-- The only new foreign key stays inside the inbox namespace (ADR 0009
+-- invariant 1). asset_id and delivered_by name rows of other namespaces:
+-- plain columns with format CHECKs, no foreign key. The backfill reads
+-- "workspaces" (auth namespace) in SQL only — no relation.
+--
+-- ADDITIVE: every ADD COLUMN is nullable or carries a constant default, so no
+-- existing row fails a new CHECK — every existing interaction is an outbound
+-- `message` with no payload, which the replaced and added CHECKs admit
+-- (interactions_body_length keeps its 1–10000 rule for a `message`). The
+-- unique index on "pieces" builds under the file's transaction, holding a
+-- SHARE lock on "pieces" for one scan of a table that is a few rows per
+-- client. The backfill inserts one row per workspace and NEVER overwrites a
+-- workspace's existing (site_id, slug) row (ON CONFLICT DO NOTHING) —
+-- re-running the block adds nothing.
+--
+-- Rollout: deploy this migration BEFORE any code that writes piece_versions,
+-- pieces.approved_at, an inbound interaction, interactions.kind/payload or
+-- flow_definitions.customers_enabled. Code written before it never names the
+-- new columns, so it keeps working against the migrated database.
+--
+-- Rollback (safe while nothing but #8168's siblings use the new surface):
+--   DELETE FROM "flow_definitions" WHERE "slug" = 'request-quote' AND "status" = 'draft' AND "customers_enabled";
+--   ALTER TABLE "flow_definitions" DROP COLUMN "customers_enabled";
+--   DELETE FROM "interactions" WHERE "direction" = 'inbound';
+--   ALTER TABLE "interactions" DROP CONSTRAINT "interactions_kind_allowed",
+--     DROP CONSTRAINT "interactions_outbound_shape", DROP CONSTRAINT "interactions_payload_by_kind",
+--     DROP CONSTRAINT "interactions_payload_size", DROP CONSTRAINT "interactions_body_length",
+--     DROP CONSTRAINT "interactions_direction_allowed";
+--   ALTER TABLE "interactions" DROP COLUMN "kind", DROP COLUMN "payload";
+--   then re-add #7877's interactions_direction_allowed (direction = 'outbound')
+--   and interactions_body_length (1–10000 once trimmed) from
+--   20261011120000_member_area;
+--   DROP TABLE "piece_versions"; DROP INDEX "pieces_id_person_id_workspace_id_key";
+--   ALTER TABLE "pieces" DROP COLUMN "approved_at";
+-- The first DELETE also removes an operator's own edits to a still-draft
+-- seeded magnet; check for those before rolling back.
+
+-- AlterTable
+ALTER TABLE "flow_definitions" ADD COLUMN     "customers_enabled" BOOLEAN NOT NULL DEFAULT false;
+
+-- AlterTable
+-- Existing rows and #7877's writer (which names no kind) stay `message`.
+ALTER TABLE "interactions" ADD COLUMN     "kind" VARCHAR(16) NOT NULL DEFAULT 'message',
+ADD COLUMN     "payload" JSONB;
+
+-- AlterTable
+ALTER TABLE "pieces" ADD COLUMN     "approved_at" TIMESTAMP(3);
+
+-- CreateTable
+CREATE TABLE "piece_versions" (
+    "id" TEXT NOT NULL DEFAULT ('pver_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "person_id" TEXT NOT NULL,
+    "piece_id" TEXT NOT NULL,
+    "version" INTEGER NOT NULL,
+    "asset_id" TEXT,
+    "link" VARCHAR(2048),
+    "note" TEXT,
+    "delivered_by" TEXT NOT NULL,
+    "delivered_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "review" VARCHAR(24),
+    "review_comment" TEXT,
+    "reviewed_at" TIMESTAMP(3),
+
+    CONSTRAINT "piece_versions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- A client's artifacts: workspace_id = $1 AND person_id = $2 ORDER BY delivered_at DESC.
+CREATE INDEX "piece_versions_workspace_id_person_id_delivered_at_idx" ON "piece_versions"("workspace_id", "person_id", "delivered_at");
+
+-- CreateIndex
+-- The public asset read's "is this asset a version file" check (AC-MAA-21).
+CREATE INDEX "piece_versions_asset_id_idx" ON "piece_versions"("asset_id");
+
+-- CreateIndex
+-- A version number is a fact per piece; the writer numbers, this is the backstop.
+CREATE UNIQUE INDEX "piece_versions_piece_id_version_key" ON "piece_versions"("piece_id", "version");
+
+-- CreateIndex
+-- Redundant with the PK; piece_versions_piece_fk needs it as its target.
+CREATE UNIQUE INDEX "pieces_id_person_id_workspace_id_key" ON "pieces"("id", "person_id", "workspace_id");
+
+-- AddForeignKey
+-- A version names a piece of THIS Person in THIS workspace (the piece's own
+-- FK already ties it to a Person of its workspace); deleting a piece with a
+-- version is refused.
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_piece_fk" FOREIGN KEY ("piece_id", "person_id", "workspace_id") REFERENCES "pieces"("id", "person_id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- ADR-0031 rule 3 — piece_versions: pver_ (registered in
+-- packages/ids/src/registry.ts; this migration's path is added to
+-- migration-sync.test.ts's PK_CHECK_MIGRATIONS). Each reference column
+-- carries the format CHECK of the entity it names, in the #7877 shape.
+ALTER TABLE "piece_versions" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "piece_versions" ALTER COLUMN "id" SET DEFAULT ('pver_'::text || (uuidv7())::text);
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_id_format" CHECK ("id" ~ '^pver_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_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}$');
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_person_id_format" CHECK ("person_id" ~ '^person_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_piece_id_format" CHECK ("piece_id" ~ '^piece_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_asset_id_format" CHECK ("asset_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 "piece_versions" ADD CONSTRAINT "piece_versions_delivered_by_format" CHECK ("delivered_by" ~ '^user_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+-- D2 — a version's shape is held here, not by the writer alone.
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_version_positive"
+  CHECK ("version" >= 1);
+-- A delivery is a file or a link: exactly one.
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_one_target"
+  CHECK (("asset_id" IS NULL) <> ("link" IS NULL));
+-- An https scheme, a host with no userinfo, no whitespace anywhere — the
+-- database floor under packages/validation's isHttpsLink (SEC-8168-5).
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_link_https"
+  CHECK ("link" IS NULL OR ("link" ~ '^https://[^[:space:]/?#@]+([/?#][^[:space:]]*)?$' AND char_length("link") <= 2048));
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_note_length"
+  CHECK ("note" IS NULL OR char_length(btrim("note")) BETWEEN 1 AND 2000);
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_review_allowed"
+  CHECK ("review" IS NULL OR "review" IN ('approved', 'changes-requested'));
+-- A review and its timestamp are set together or not at all.
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_review_stamped"
+  CHECK (("review" IS NULL) = ("reviewed_at" IS NULL));
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_comment_needs_review"
+  CHECK ("review_comment" IS NULL OR "review" IS NOT NULL);
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_changes_need_comment"
+  CHECK ("review" IS DISTINCT FROM 'changes-requested' OR char_length(btrim(coalesce("review_comment", ''))) >= 1);
+ALTER TABLE "piece_versions" ADD CONSTRAINT "piece_versions_comment_length"
+  CHECK ("review_comment" IS NULL OR char_length("review_comment") <= 5000);
+
+-- D3 — the second direction and the kinds. Replaced IN PLACE under the same
+-- names, so #7877's tests keep naming the same constraints.
+ALTER TABLE "interactions" DROP CONSTRAINT "interactions_direction_allowed";
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_direction_allowed"
+  CHECK ("direction" IN ('outbound', 'inbound'));
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_kind_allowed"
+  CHECK ("kind" IN ('message', 'quote', 'review'));
+-- An outbound row is a payload-free `message` — #7877's rows, unchanged.
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_outbound_shape"
+  CHECK ("direction" <> 'outbound' OR ("kind" = 'message' AND "payload" IS NULL));
+-- A quote or a review always carries its stored payload.
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_payload_by_kind"
+  CHECK ("kind" = 'message' OR "payload" IS NOT NULL);
+-- 64 items of a 200-character label and a 2000-character value fit with room (SEC-8168-4).
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_payload_size"
+  CHECK ("payload" IS NULL OR octet_length("payload"::text) <= 262144);
+-- A message body stays 1–10000 characters once trimmed; a quote or review
+-- body may be empty; no body exceeds 10000.
+ALTER TABLE "interactions" DROP CONSTRAINT "interactions_body_length";
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_body_length"
+  CHECK (
+    char_length("body") <= 10000
+    AND ("kind" <> 'message' OR char_length(btrim("body")) BETWEEN 1 AND 10000)
+  );
+
+-- D8/D9 — the request-quote magnet in every existing workspace. The config
+-- literal below is test-held to `requestQuoteFlowConfig`
+-- (packages/validation/src/schemas/flow.ts) by
+-- database/__tests__/member-contract-migration.test.ts, and the block is
+-- re-executed verbatim by member-contract.db.test.ts to prove it idempotent.
+-- Do not edit one without the other.
+-- BEGIN request-quote backfill
+INSERT INTO "flow_definitions" ("site_id", "workspace_id", "slug", "config", "kind", "title", "status", "customers_enabled", "updated_at")
+SELECT w."id", w."id", 'request-quote',
+  '{"slug":"request-quote","defaultLocale":"en","steps":[{"key":"request","type":"field","copy":{"title":{"en":"Request a quote"}},"fields":[{"name":"need","inputType":"textarea","required":true,"copy":{"label":{"en":"What do you need?"}}},{"name":"timing","inputType":"text","copy":{"label":{"en":"When do you need it?"}}},{"name":"budget","inputType":"text","copy":{"label":{"en":"Budget range"},"help":{"en":"A rough range is fine."}}},{"name":"link","inputType":"url","copy":{"label":{"en":"Link"},"help":{"en":"A brief, a document or an example. Must start with https://."}}}]}]}'::jsonb,
+  'contact', 'Request a quote', 'draft', true, CURRENT_TIMESTAMP
+FROM "workspaces" w
+ON CONFLICT ("site_id", "slug") DO NOTHING;
+-- END request-quote backfill

package/templates/database/migrations/20261013120000_lead_spoke_checkout/migration.sql

@@ -0,0 +1,20 @@
+-- #8185 — record, at the moment the hub writes it, that a lead is a spoke's
+-- live paid checkout (spec docs/specs/8185-spoke-checkout-purchases-spec.md
+-- D1, D6, D10).
+--
+--   leads.spoke_checkout — set true by apps/api/src/services/lead-routing.ts
+--                          only for a spoke-keyed, unrelayed submit passing
+--                          the #7877 checkout plan rule's predicate. Written
+--                          at creation, never updated. NOT NULL with a
+--                          constant default, so existing rows read false and
+--                          nothing is rewritten; they are deliberately NOT
+--                          backfilled (D6: no stored fact proves an older
+--                          lead's provenance).
+--
+-- Rollout order (D10): apply this migration to a deployment's database BEFORE
+-- deploying the API that writes the column. The old API is unaffected by it;
+-- the new API's marked create fails without it.
+--
+-- Rollback: ALTER TABLE "leads" DROP COLUMN "spoke_checkout";
+
+ALTER TABLE "leads" ADD COLUMN "spoke_checkout" BOOLEAN NOT NULL DEFAULT false;

package/templates/database/migrations/20261014120000_consent_ledger/migration.sql

@@ -0,0 +1,122 @@
+-- #8438 — the consent ledger (spec docs/specs/8438-consent-registry-and-ledger-step-spec.md D2).
+--
+--   consent_grants (inbox)        — the existing append-only table (#5275)
+--                                   becomes THE ledger. It gains the Person a
+--                                   row counts toward, the source it came
+--                                   from, the magnet slug, and the policy
+--                                   version read. Every row stored before this
+--                                   migration reads source = 'legacy' with no
+--                                   policy version, honestly: those rows
+--                                   recorded neither. Every row written after
+--                                   it must name its source and version.
+--   consent_visitor_links (inbox) — a banner visitor id linked to the Person a
+--                                   later form or sign-in identifies. A second
+--                                   append-only table, so a visitor's own rows
+--                                   are never edited to point at a Person.
+--
+-- Both tables are APPEND-ONLY, and now the database says so: a trigger refuses
+-- any change to a stored row and any truncation. The triggers bind the
+-- application's database role; a table owner can still disable them. A later
+-- migration that must rewrite or erase rows disables them explicitly inside its
+-- own transaction, which makes the act a reviewed migration rather than
+-- something application code can do.
+--
+-- person_id is a plain scalar with no foreign key, the table's own posture
+-- (ADR 0009 invariant 1, #5275 D10): a row about a visitor or a listing has no
+-- Person, and a ledger row must outlive anything it names. Neither table
+-- carries any network or browser evidence column (spec section 2.3).
+--
+-- ADDITIVE: ADD COLUMN with a constant default, then the default dropped, so no
+-- existing row fails a new CHECK. Deploy this migration BEFORE any code that
+-- writes the new columns; code written before it never names them.
+--
+-- Rollback (safe while nothing but #8438 writes the new surface):
+--   DROP TABLE "consent_visitor_links";
+--   ALTER TABLE "consent_grants" DISABLE TRIGGER USER;
+--   ALTER TABLE "consent_grants"
+--     DROP COLUMN "person_id", DROP COLUMN "source", DROP COLUMN "source_ref", DROP COLUMN "policy_version";
+--   ALTER TABLE "consent_grants" ENABLE TRIGGER USER;  -- after dropping the three triggers and the function
+--   DROP FUNCTION "consent_ledger_append_only"();
+
+-- AlterTable
+-- source: every row already stored reads 'legacy'; the default is dropped
+-- straight after, so every new row has to say where it came from.
+ALTER TABLE "consent_grants" ADD COLUMN     "person_id" TEXT,
+ADD COLUMN     "source" TEXT NOT NULL DEFAULT 'legacy',
+ADD COLUMN     "source_ref" VARCHAR(200),
+ADD COLUMN     "policy_version" INTEGER;
+ALTER TABLE "consent_grants" ALTER COLUMN "source" DROP DEFAULT;
+
+-- CreateIndex
+-- "Current state per purpose" for one Person: DISTINCT ON (purpose_id) over
+-- workspace_id = $1 AND person_id = $2 ORDER BY purpose_id, created_at DESC.
+CREATE INDEX "consent_grants_workspace_id_person_id_purpose_id_created_at_idx" ON "consent_grants"("workspace_id", "person_id", "purpose_id", "created_at");
+
+-- The source vocabulary is packages/validation CONSENT_SOURCES. 'legacy' is
+-- read-only in practice: only the default above ever writes it.
+ALTER TABLE "consent_grants" ADD CONSTRAINT "consent_grants_source_known"
+  CHECK ("source" IN ('cookie_banner', 'sign_up', 'magnet', 'account_settings', 'email_unsubscribe', 'api', 'legacy'));
+-- A new row records the policy version it was read at; only a legacy row may not.
+ALTER TABLE "consent_grants" ADD CONSTRAINT "consent_grants_policy_version_present"
+  CHECK ("source" = 'legacy' OR "policy_version" IS NOT NULL);
+ALTER TABLE "consent_grants" ADD CONSTRAINT "consent_grants_policy_version_positive"
+  CHECK ("policy_version" IS NULL OR "policy_version" >= 1);
+ALTER TABLE "consent_grants" ADD CONSTRAINT "consent_grants_person_id_format"
+  CHECK ("person_id" IS NULL OR "person_id" ~ '^person_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+-- CreateTable
+CREATE TABLE "consent_visitor_links" (
+    "id" TEXT NOT NULL DEFAULT ('cvlink_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "visitor_id" TEXT NOT NULL,
+    "person_id" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "consent_visitor_links_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- A repeat link is a no-op: the writer inserts and ignores a conflict here.
+CREATE UNIQUE INDEX "consent_visitor_links_workspace_id_visitor_id_person_id_key" ON "consent_visitor_links"("workspace_id", "visitor_id", "person_id");
+
+-- CreateIndex
+-- A Person's linked visitors: workspace_id = $1 AND person_id = $2.
+CREATE INDEX "consent_visitor_links_workspace_id_person_id_idx" ON "consent_visitor_links"("workspace_id", "person_id");
+
+-- ADR-0031 rule 3 — consent_visitor_links: cvlink_ (registered in
+-- packages/ids/src/registry.ts ENTITY_PREFIX.consentVisitorLink; this
+-- migration's path is added to migration-sync.test.ts's PK_CHECK_MIGRATIONS).
+-- Each reference column carries the format CHECK of the entity it names.
+ALTER TABLE "consent_visitor_links" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "consent_visitor_links" ALTER COLUMN "id" SET DEFAULT ('cvlink_'::text || (uuidv7())::text);
+ALTER TABLE "consent_visitor_links" ADD CONSTRAINT "consent_visitor_links_id_format" CHECK ("id" ~ '^cvlink_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "consent_visitor_links" ADD CONSTRAINT "consent_visitor_links_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}$');
+ALTER TABLE "consent_visitor_links" ADD CONSTRAINT "consent_visitor_links_person_id_format" CHECK ("person_id" ~ '^person_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+-- A visitor id is a random version-4 UUID the site's own server minted.
+ALTER TABLE "consent_visitor_links" ADD CONSTRAINT "consent_visitor_links_visitor_id_format" CHECK ("visitor_id" ~ '^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "consent_visitor_links" ADD CONSTRAINT "consent_visitor_links_source_known"
+  CHECK ("source" IN ('magnet', 'api', 'account_settings'));
+
+-- SEC-8438-7 — append-only, enforced. One function, three triggers per table.
+CREATE FUNCTION "consent_ledger_append_only"() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION '% is append-only', TG_TABLE_NAME
+    USING ERRCODE = 'restrict_violation';
+END;
+$$;
+
+CREATE TRIGGER "consent_grants_no_update" BEFORE UPDATE ON "consent_grants"
+  FOR EACH ROW EXECUTE FUNCTION "consent_ledger_append_only"();
+CREATE TRIGGER "consent_grants_no_delete" BEFORE DELETE ON "consent_grants"
+  FOR EACH ROW EXECUTE FUNCTION "consent_ledger_append_only"();
+CREATE TRIGGER "consent_grants_no_truncate" BEFORE TRUNCATE ON "consent_grants"
+  FOR EACH STATEMENT EXECUTE FUNCTION "consent_ledger_append_only"();
+
+CREATE TRIGGER "consent_visitor_links_no_update" BEFORE UPDATE ON "consent_visitor_links"
+  FOR EACH ROW EXECUTE FUNCTION "consent_ledger_append_only"();
+CREATE TRIGGER "consent_visitor_links_no_delete" BEFORE DELETE ON "consent_visitor_links"
+  FOR EACH ROW EXECUTE FUNCTION "consent_ledger_append_only"();
+CREATE TRIGGER "consent_visitor_links_no_truncate" BEFORE TRUNCATE ON "consent_visitor_links"
+  FOR EACH STATEMENT EXECUTE FUNCTION "consent_ledger_append_only"();