create-ailk 0.15.0 → 0.17.0

package/templates/database/inbox/schema.prisma

@@ -73,6 +73,14 @@ model Lead {
   // `FlowCheckout.idempotencyKey` (#4912).
   idempotencyKey String? @map("idempotency_key")
 
+  // #852 D1 — the Person this lead belongs to: one client of this workspace,
+  // stamped at creation by `apps/api/src/services/lead-routing.ts` through
+  // `findOrCreatePerson`. Plain scalar, no @relation (the inbox house style,
+  // `FlowCheckout.leadId`). NULL only when the email is not a storable
+  // address or the Person step failed — a Person step never refuses a lead.
+  // Backfilled by database/migrations/20261010121000_person_backfill.
+  personId String? @map("person_id")
+
   // #7869 — the idempotency guarantee, scoped per workspace so a key can
   // never reach another tenant's row.
   @@unique([workspaceId, idempotencyKey])
@@ -91,9 +99,93 @@ model Lead {
   // `'flow:' + <magnet slug>` value, not the `handledAt` index's allowlist
   // `IN` — a distinct query shape that composite does not serve.
   @@index([workspaceId, source])
+  @@index([personId])
   @@map("leads")
 }
 
+/// Person — one client of one workspace (#852). Created only by
+/// apps/api/src/services/person.ts's findOrCreatePerson. Plain scalars, no
+/// @relation (ADR 0009): workspaceId and userId name rows in the auth
+/// namespace.
+///
+/// `email` is the lowercased, trimmed address (the `people_email_normalized`
+/// CHECK holds it to printable ASCII). `userId` is written only on a verified
+/// email match (`stampPersonUser`) and never overwritten. `billingCustomerId`
+/// is NOT unique — the spokes share one Stripe account — and the first
+/// 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")
+
+  pieces       Piece[]
+  interactions Interaction[]
+
+  @@unique([workspaceId, email])
+  @@unique([workspaceId, userId])
+  // #7877 D1 — redundant with the PK, load-bearing as the target of the
+  // composite (person_id, workspace_id) FKs from pieces and interactions:
+  // "a Person of the same workspace" is a database fact.
+  @@unique([id, workspaceId])
+  @@index([workspaceId, billingCustomerId])
+  @@index([workspaceId, createdAt])
+  @@map("people")
+}
+
+/// Piece — one deliverable for one client (#7877). Written only through
+/// 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.
+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")
+
+  person Person @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "pieces_person_fk")
+
+  @@index([workspaceId, personId, createdAt])
+  @@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.
+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)
+  subject     String    @db.VarChar(200)
+  body        String    @db.Text
+  assetId     String?   @map("asset_id")
+  createdBy   String    @map("created_by")
+  createdAt   DateTime  @default(now()) @map("created_at")
+  readAt      DateTime? @map("read_at")
+
+  person Person @relation(fields: [personId, workspaceId], references: [id, workspaceId], onDelete: Restrict, map: "interactions_person_fk")
+
+  @@index([workspaceId, personId, createdAt])
+  @@index([assetId])
+  @@map("interactions")
+}
+
 /// Subscriber — newsletter subscription (Phase B subscribe_newsletter tool / B6 route)
 model Subscriber {
   id        String   @id @default(dbgenerated("('subscr_'::text || (uuidv7())::text)")) @db.Text
@@ -1137,11 +1229,17 @@ model Appointment {
   noShowEventAt       DateTime? @map("no_show_event_at")
   createdAt           DateTime  @default(now()) @map("created_at")
   updatedAt           DateTime  @updatedAt @map("updated_at")
+  /// #852 D1 — the Person of the attendee, in this row's workspace. Stamped
+  /// at create (and on a spoke bind's move) by appointments.ts through
+  /// findOrCreatePerson. Plain scalar, no @relation. NULL when the attendee
+  /// email is not a storable address.
+  personId            String?   @map("person_id")
 
   @@unique([siteId, provider, providerBookingUid])
   @@index([siteId, startTime])
   @@index([createdAt])
   @@index([workspaceId])
+  @@index([personId])
   @@map("appointments")
 }
 

package/templates/database/migrations/20261010120000_person/migration.sql

@@ -0,0 +1,106 @@
+-- #852 — Person, the per-workspace client record (spec
+-- docs/specs/852-person-the-per-workspace-client-spec.md D1, D2).
+--
+--   people (inbox) — one client of one workspace, keyed on a lowercased,
+--                    trimmed email unique per workspace. Created only by
+--                    apps/api/src/services/person.ts's findOrCreatePerson.
+--                    workspace_id and user_id are plain columns with no
+--                    foreign key (ADR 0009): they name auth-namespace rows.
+--   leads.person_id, appointments.person_id — the Person each row belongs
+--                    to, stamped at creation by the intake paths.
+--
+-- PURELY ADDITIVE, DDL ONLY: one new table with its indexes and CHECKs, and
+-- one nullable column with no default on each of "leads" and "appointments",
+-- so Postgres changes only the catalog for those two. No existing row's
+-- values change here — the backfill is the next migration,
+-- 20261010121000_person_backfill, split out so its row updates never run
+-- under the exclusive locks these ALTER TABLEs take (SEC-852-E). Prisma runs
+-- this file as one transaction, so each ALTER TABLE's ACCESS EXCLUSIVE lock
+-- is held until the file commits — through the plain CREATE INDEX on the new
+-- column — blocking reads AND writes of "leads" and "appointments" (lead
+-- capture included) for one heap scan of each. Accepted: the scan is short
+-- next to the backfill it is split from.
+--
+-- Rollout: deploy this migration (and the backfill) BEFORE the API code that
+-- writes person_id; code without the column fails every lead write.
+--
+-- Rollback: ALTER TABLE "leads" DROP COLUMN "person_id"; ALTER TABLE
+-- "appointments" DROP COLUMN "person_id"; DROP TABLE "people"; (the indexes
+-- and CHECKs go with them). Safe while nothing but #852's own code reads them.
+
+-- AlterTable
+ALTER TABLE "appointments" ADD COLUMN     "person_id" TEXT;
+
+-- AlterTable
+ALTER TABLE "leads" ADD COLUMN     "person_id" TEXT;
+
+-- CreateTable
+CREATE TABLE "people" (
+    "id" TEXT NOT NULL DEFAULT ('person_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "email" VARCHAR(254) NOT NULL,
+    "name" VARCHAR(200),
+    "user_id" TEXT,
+    "billing_provider" VARCHAR(32),
+    "billing_customer_id" VARCHAR(255),
+    "plan_offering" VARCHAR(100),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "people_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- The webhook's first match: a customer id within one workspace (D3 step 2).
+-- NOT unique — the spokes share one Stripe account.
+CREATE INDEX "people_workspace_id_billing_customer_id_idx" ON "people"("workspace_id", "billing_customer_id");
+
+-- CreateIndex
+-- The People list: workspace_id = $1 ORDER BY created_at DESC (D7).
+CREATE INDEX "people_workspace_id_created_at_idx" ON "people"("workspace_id", "created_at");
+
+-- CreateIndex
+-- One Person per address per workspace — what findOrCreatePerson's
+-- INSERT … ON CONFLICT DO NOTHING absorbs a concurrent duplicate on.
+CREATE UNIQUE INDEX "people_workspace_id_email_key" ON "people"("workspace_id", "email");
+
+-- CreateIndex
+-- One Person per User per workspace. NULLs are distinct, so any number of
+-- unlinked Persons fit.
+CREATE UNIQUE INDEX "people_workspace_id_user_id_key" ON "people"("workspace_id", "user_id");
+
+-- CreateIndex
+CREATE INDEX "appointments_person_id_idx" ON "appointments"("person_id");
+
+-- CreateIndex
+CREATE INDEX "leads_person_id_idx" ON "leads"("person_id");
+
+-- ADR-0031 rule 3 — people: person_ (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 agents-migration shape.
+ALTER TABLE "people" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "people" ALTER COLUMN "id" SET DEFAULT ('person_'::text || (uuidv7())::text);
+ALTER TABLE "people" ADD CONSTRAINT "people_id_format" CHECK ("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 "people" ADD CONSTRAINT "people_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 "people" ADD CONSTRAINT "people_user_id_format" CHECK ("user_id" ~ '^user_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+-- The stored address is already normalized: printable ASCII only (no
+-- whitespace, no control or invisible character), exactly one @ with a
+-- non-empty side each, lower case. findOrCreatePerson's
+-- isStorablePersonEmail applies the same rule before any write (D3).
+ALTER TABLE "people" ADD CONSTRAINT "people_email_normalized"
+  CHECK ("email" = lower("email" COLLATE "C") AND "email" ~ '^[!-?A-~]+@[!-?A-~]+$');
+
+-- A provider and its customer id are written together or not at all — the
+-- same provider-agnostic pair User and Organization carry.
+ALTER TABLE "people" ADD CONSTRAINT "people_billing_pair"
+  CHECK (("billing_provider" IS NULL) = ("billing_customer_id" IS NULL));
+
+-- The two new reference columns carry the person_ format CHECK, added NOT
+-- VALID and then validated: the file runs as one transaction, so the ALTER
+-- TABLE's lock is still held, and the scan is of an all-NULL column.
+ALTER TABLE "leads" ADD CONSTRAINT "leads_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}$') NOT VALID;
+ALTER TABLE "leads" VALIDATE CONSTRAINT "leads_person_id_format";
+ALTER TABLE "appointments" ADD CONSTRAINT "appointments_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}$') NOT VALID;
+ALTER TABLE "appointments" VALIDATE CONSTRAINT "appointments_person_id_format";

package/templates/database/migrations/20261010121000_person_backfill/migration.sql

@@ -0,0 +1,132 @@
+-- #852 — the Person backfill (spec
+-- docs/specs/852-person-the-per-workspace-client-spec.md D2, D4).
+--
+-- Fills "people" from the rows the hub already holds and stamps
+-- leads.person_id and appointments.person_id, so the People list is not
+-- empty on the day it ships. Set-based and idempotent: every insert is
+-- ON CONFLICT DO NOTHING and every update is guarded by IS NULL, so running
+-- this text twice changes nothing the first run wrote.
+--
+-- THE SAME TEXT, byte for byte, is database/scripts/person-backfill.sql. The
+-- previous deployment keeps writing leads and appointments without a
+-- person_id between this migration and the cutover to the new code; run
+-- that script ONCE against the hub database after the cutover to stamp them.
+-- database/__tests__/person.db.test.ts asserts the two files are identical
+-- and that a second run changes no row.
+--
+-- Normalization — the SQL twin of apps/api/src/services/person.ts's
+-- normalizePersonEmail / isStorablePersonEmail:
+--   N(x)     = lower(btrim(x, E' \t\n\r\f\x0B') COLLATE "C")
+--              (\x0B is vertical tab; an E-string has no \v escape — E'\v'
+--              is the letter v, which would strip the v of every .dev)
+--   VALID(e) = e ~ '^[!-?A-~]+@[!-?A-~]+$' AND length(e) <= 254
+--   NAME(x)  = C0/C1 controls and bidi controls removed, trimmed, cut to
+--              200 characters; empty → NULL
+-- A row whose email is not VALID makes no Person and keeps person_id NULL.
+--
+-- Sources, in order: leads (oldest first), then completed hub FlowCheckouts
+-- through their lead (the customer id, first writer wins), then appointments
+-- by attendee email. Subscriber is NOT a source; FlowSession, ProjectListing
+-- and DeliverableGrant reach a Person through their lead at read time.
+-- The join to "users" reads the auth namespace inside this one-off
+-- statement only; it adds no foreign key (ADR 0009 invariant 1).
+--
+-- Rollback: nothing to undo on its own — dropping 20261010120000_person's
+-- table and columns removes everything this wrote.
+
+-- 1. Leads, oldest first: one Person per (workspace, normalized email). The
+--    name is the oldest lead's payload.name when it is a JSON string.
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+       l."workspace_id",
+       lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+       CASE WHEN jsonb_typeof(l."payload" -> 'name') = 'string'
+            THEN NULLIF(left(btrim(regexp_replace(l."payload" ->> 'name', '[\x01-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]', '', 'g')), 200), '')
+       END,
+       l."created_at",
+       now()
+FROM "leads" l
+WHERE lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"), l."created_at" ASC, l."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 2. Hub FlowCheckouts, through their lead (same workspace): the oldest
+--    completed checkout with a customer id writes it onto a Person that has
+--    none. First writer wins — oldest by completed_at, then created_at, then id.
+UPDATE "people" p
+SET "billing_provider" = 'stripe',
+    "billing_customer_id" = c."stripe_customer_id",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (fc."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+         fc."workspace_id",
+         lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") AS "email",
+         fc."stripe_customer_id"
+  FROM "flow_checkouts" fc
+  JOIN "leads" l ON l."id" = fc."lead_id" AND l."workspace_id" = fc."workspace_id"
+  WHERE fc."status" = 'completed'
+    AND fc."stripe_customer_id" IS NOT NULL
+    AND fc."stripe_customer_id" <> ''
+    AND length(fc."stripe_customer_id") <= 255
+  ORDER BY fc."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+           fc."completed_at" ASC NULLS LAST, fc."created_at" ASC, fc."id" ASC
+) c
+WHERE p."workspace_id" = c."workspace_id"
+  AND p."email" = c."email"
+  AND p."billing_customer_id" IS NULL;
+
+-- 3. Appointments, by attendee email: a Person a lead already made keeps its
+--    lead-derived name and created_at (ON CONFLICT DO NOTHING).
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (a."workspace_id", lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"))
+       a."workspace_id",
+       lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"),
+       NULLIF(left(btrim(regexp_replace(a."attendee_name", '[\x01-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]', '', 'g')), 200), ''),
+       a."created_at",
+       now()
+FROM "appointments" a
+WHERE lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY a."workspace_id", lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"), a."created_at" ASC, a."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 4. Stamps: every lead and appointment with a storable email points at its
+--    workspace's Person; a row already stamped is left alone.
+UPDATE "leads"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "leads"."person_id" IS NULL
+  AND p."workspace_id" = "leads"."workspace_id"
+  AND p."email" = lower(btrim("leads"."email", E' \t\n\r\f\x0B') COLLATE "C");
+
+UPDATE "appointments"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "appointments"."person_id" IS NULL
+  AND p."workspace_id" = "appointments"."workspace_id"
+  AND p."email" = lower(btrim("appointments"."attendee_email", E' \t\n\r\f\x0B') COLLATE "C");
+
+-- 5. user_id, verified only: the oldest promoted lead (by promoted_at, then
+--    created_at, then id) whose user is email-verified and whose verified
+--    address normalizes to the Person's. An unverified or differing user is
+--    never copied — the rule stampPersonUser applies to new rows.
+UPDATE "people" p
+SET "user_id" = c."user_id",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+         l."workspace_id",
+         lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") AS "email",
+         l."promoted_user_id" AS "user_id"
+  FROM "leads" l
+  JOIN "users" u ON u."id" = l."promoted_user_id"
+  WHERE l."promoted_user_id" IS NOT NULL
+    AND u."email_verified" = true
+    AND lower(btrim(u."email", E' \t\n\r\f\x0B') COLLATE "C") = lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C")
+  ORDER BY l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+           l."promoted_at" ASC NULLS LAST, l."created_at" ASC, l."id" ASC
+) c
+WHERE p."workspace_id" = c."workspace_id"
+  AND p."email" = c."email"
+  AND p."user_id" IS NULL;

package/templates/database/migrations/20261010130000_agent_grants_people_read/migration.sql

@@ -0,0 +1,20 @@
+-- #852 — an agent key may be granted people-read (spec
+-- docs/specs/852-person-the-per-workspace-client-spec.md D9).
+--
+-- Widens the agents_grants_allowed CHECK from the five #7864 permissions to
+-- six. The CHECK names the same six as @working-theory/validation's
+-- AGENT_GRANTABLE_PERMISSIONS; database/__tests__/agents.db.test.ts reads
+-- this file and fails if the two lists differ (SEC-7864-G).
+--
+-- PURELY ADDITIVE in effect: the new CHECK admits every row the old one
+-- admitted, so re-adding it cannot fail on existing data. No row changes.
+--
+-- Rollback: ALTER TABLE "agents" DROP CONSTRAINT "agents_grants_allowed";
+-- then re-add the five-id CHECK from 20261009120000_agent_grants. That
+-- re-add FAILS while any row holds people-read — remove those grants first.
+
+ALTER TABLE "agents" DROP CONSTRAINT "agents_grants_allowed";
+
+-- Only the six grantable permissions may be stored.
+ALTER TABLE "agents" ADD CONSTRAINT "agents_grants_allowed"
+  CHECK ("grants" <@ ARRAY['content-edit','content-publish','assets-write','magnets-manage','meeting-types-manage','people-read']::TEXT[]);

package/templates/database/migrations/20261011120000_member_area/migration.sql

@@ -0,0 +1,158 @@
+-- #7877 — the member area contract (spec
+-- docs/specs/7877-the-member-area-contract-a-spec.md D1, D2, D3).
+--
+--   pieces (inbox)       — one deliverable for one client: a title, a stage
+--                          drawn from the workspace's declared list, a
+--                          needs-client flag. Written only through
+--                          apps/api's tenantDb(tenant).memberArea.
+--   interactions (inbox) — one outbound message on the 'member' channel to
+--                          one client, optionally carrying a workspace
+--                          library asset. The original CRM spec's
+--                          Interaction table cut to one channel and one
+--                          direction; an inbound reply is a later second
+--                          direction value on this table.
+--   workspace_piece_stages (config) — a workspace's declared piece stages,
+--                          in order, one row per workspace. No row means the
+--                          product default, which lives in apps/api only.
+--   people_id_workspace_id_key — a unique index over a pair the PK already
+--                          makes unique: the target of the composite
+--                          (person_id, workspace_id) foreign keys, so "a
+--                          Person of the same workspace" is a database fact.
+--
+-- Both foreign keys stay inside the inbox namespace (ADR 0009 invariant 1).
+-- workspace_id, asset_id, created_by and updated_by name rows of other
+-- namespaces: plain columns with format CHECKs, no foreign key. Neither new
+-- inbox table carries an email.
+--
+-- PURELY ADDITIVE, DDL ONLY: three new tables and one unique index on
+-- "people". No existing row changes. The unique index builds under the
+-- file's transaction, holding a SHARE lock on "people" (writes wait, reads do
+-- not) for one scan of a table that is one row per client.
+--
+-- Rollout: deploy this migration BEFORE the API code that reads or writes
+-- these tables; code without them fails every member-area read and write.
+--
+-- Rollback: DROP TABLE "interactions"; DROP TABLE "pieces"; DROP TABLE
+-- "workspace_piece_stages"; DROP INDEX "people_id_workspace_id_key"; (the
+-- indexes, foreign keys and CHECKs go with them). Safe while nothing but
+-- #7877's own code reads them.
+
+-- CreateTable
+CREATE TABLE "workspace_piece_stages" (
+    "id" TEXT NOT NULL DEFAULT ('pstages_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "stages" TEXT[],
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "workspace_piece_stages_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "pieces" (
+    "id" TEXT NOT NULL DEFAULT ('piece_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "person_id" TEXT NOT NULL,
+    "title" VARCHAR(200) NOT NULL,
+    "stage" VARCHAR(40) NOT NULL,
+    "needs_client" BOOLEAN NOT NULL DEFAULT false,
+    "updated_by" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "pieces_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "interactions" (
+    "id" TEXT NOT NULL DEFAULT ('intx_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "person_id" TEXT NOT NULL,
+    "channel" VARCHAR(16) NOT NULL,
+    "direction" VARCHAR(16) NOT NULL,
+    "subject" VARCHAR(200) NOT NULL,
+    "body" TEXT NOT NULL,
+    "asset_id" TEXT,
+    "created_by" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "read_at" TIMESTAMP(3),
+
+    CONSTRAINT "interactions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- One stage list per workspace — the WorkspaceMeetings shape.
+CREATE UNIQUE INDEX "workspace_piece_stages_workspace_id_key" ON "workspace_piece_stages"("workspace_id");
+
+-- CreateIndex
+-- A client's pieces: workspace_id = $1 AND person_id = $2 ORDER BY created_at DESC.
+CREATE INDEX "pieces_workspace_id_person_id_created_at_idx" ON "pieces"("workspace_id", "person_id", "created_at");
+
+-- CreateIndex
+-- A client's messages, the same read shape as pieces.
+CREATE INDEX "interactions_workspace_id_person_id_created_at_idx" ON "interactions"("workspace_id", "person_id", "created_at");
+
+-- CreateIndex
+-- The public asset read's "is this asset attached to any message" count (D18).
+CREATE INDEX "interactions_asset_id_idx" ON "interactions"("asset_id");
+
+-- CreateIndex
+-- Redundant with the PK; the composite foreign keys below need it as their target.
+CREATE UNIQUE INDEX "people_id_workspace_id_key" ON "people"("id", "workspace_id");
+
+-- AddForeignKey
+-- A piece names a Person of ITS OWN workspace; deleting a Person with a piece is refused.
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_person_fk" FOREIGN KEY ("person_id", "workspace_id") REFERENCES "people"("id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+-- The same rule for a message.
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_person_fk" FOREIGN KEY ("person_id", "workspace_id") REFERENCES "people"("id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- ADR-0031 rule 3 — pieces: piece_, interactions: intx_,
+-- workspace_piece_stages: pstages_ (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 person-migration
+-- shape.
+ALTER TABLE "pieces" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "pieces" ALTER COLUMN "id" SET DEFAULT ('piece_'::text || (uuidv7())::text);
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_id_format" CHECK ("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 "pieces" ADD CONSTRAINT "pieces_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 "pieces" ADD CONSTRAINT "pieces_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 "pieces" ADD CONSTRAINT "pieces_updated_by_format" CHECK ("updated_by" ~ '^user_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+ALTER TABLE "interactions" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "interactions" ALTER COLUMN "id" SET DEFAULT ('intx_'::text || (uuidv7())::text);
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_id_format" CHECK ("id" ~ '^intx_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_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 "interactions" ADD CONSTRAINT "interactions_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 "interactions" ADD CONSTRAINT "interactions_created_by_format" CHECK ("created_by" ~ '^user_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_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 "workspace_piece_stages" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "workspace_piece_stages" ALTER COLUMN "id" SET DEFAULT ('pstages_'::text || (uuidv7())::text);
+ALTER TABLE "workspace_piece_stages" ADD CONSTRAINT "workspace_piece_stages_id_format" CHECK ("id" ~ '^pstages_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "workspace_piece_stages" ADD CONSTRAINT "workspace_piece_stages_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}$');
+
+-- A piece's title is 1–200 characters once trimmed; a stage is a slug. Which
+-- slugs a workspace accepts is its declared list, checked at write time by
+-- the API — never an enum here or in packages/validation.
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_title_length"
+  CHECK (char_length(btrim("title")) BETWEEN 1 AND 200);
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_stage_format"
+  CHECK ("stage" ~ '^[a-z0-9][a-z0-9-]{0,39}$');
+
+-- One channel and one direction in this slice. An inbound reply widens
+-- interactions_direction_allowed in its own migration.
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_channel_allowed"
+  CHECK ("channel" = 'member');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_direction_allowed"
+  CHECK ("direction" = 'outbound');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_subject_length"
+  CHECK (char_length(btrim("subject")) BETWEEN 1 AND 200);
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_body_length"
+  CHECK (char_length(btrim("body")) BETWEEN 1 AND 10000);
+
+-- A declared list holds 1–20 stages (never NULL: no row is the default).
+ALTER TABLE "workspace_piece_stages" ADD CONSTRAINT "workspace_piece_stages_count"
+  CHECK ("stages" IS NOT NULL AND cardinality("stages") BETWEEN 1 AND 20);

package/templates/database/migrations/20261011130000_agent_grants_member_pieces_manage/migration.sql

@@ -0,0 +1,21 @@
+-- #7878 — an agent key may be granted member-pieces-manage: a client's
+-- pieces, plan and outbound messages (#7877's operator writes).
+--
+-- Widens the agents_grants_allowed CHECK from the six #852 permissions to
+-- seven. The CHECK names the same seven as @working-theory/validation's
+-- AGENT_GRANTABLE_PERMISSIONS; database/__tests__/agents.db.test.ts reads
+-- this file and fails if the two lists differ (SEC-7864-G).
+--
+-- PURELY ADDITIVE in effect: the new CHECK admits every row the old one
+-- admitted, so re-adding it cannot fail on existing data. No row changes.
+--
+-- Rollback: ALTER TABLE "agents" DROP CONSTRAINT "agents_grants_allowed";
+-- then re-add the six-id CHECK from 20261010130000_agent_grants_people_read.
+-- That re-add FAILS while any row holds member-pieces-manage — remove those
+-- grants first.
+
+ALTER TABLE "agents" DROP CONSTRAINT "agents_grants_allowed";
+
+-- Only the seven grantable permissions may be stored.
+ALTER TABLE "agents" ADD CONSTRAINT "agents_grants_allowed"
+  CHECK ("grants" <@ ARRAY['content-edit','content-publish','assets-write','magnets-manage','meeting-types-manage','people-read','member-pieces-manage']::TEXT[]);

package/templates/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@working-theory/database",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"