create-ailk 0.19.0 → 0.20.0

package/templates/database/inbox/schema.prisma

@@ -127,19 +127,49 @@ 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)
+  // #8514 D1 — the team's private note on this client: one per Person, never
+  // served to the client. Who last saved it (a user id of the auth namespace,
+  // no foreign key — ADR 0009) and when; both NULL until the first save.
+  // When an agent saved it, which agent (its person is notesUpdatedBy).
+  notes               String?   @db.VarChar(5000)
+  notesUpdatedAt      DateTime? @map("notes_updated_at")
+  notesUpdatedBy      String?   @map("notes_updated_by")
+  notesUpdatedByAgent String?   @map("notes_updated_by_agent")
+  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])
@@ -152,7 +182,7 @@ model Person {
   @@map("people")
 }
 
-/// Piece — one deliverable for one client (#7877). Written only through
+/// Piece — one deliverable or proposal for one client (#7877, #8516). 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.
@@ -162,16 +192,32 @@ model Person {
 /// 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")
-  approvedAt  DateTime? @map("approved_at")
-  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")
+  // #8516 D1 — what the piece is: a `deliverable` (every row before #8516) or a
+  // `proposal` the client approves or sends back. Never changes after create.
+  kind              String    @default("deliverable") @db.VarChar(16)
+  // A proposal's price, in minor units of a two-decimal currency; both or
+  // neither, and only on a proposal.
+  priceAmount       Int?      @map("price_amount")
+  priceCurrency     String?   @map("price_currency") @db.Char(3)
+  // The client's current Stripe Checkout Session (#8516 D11) — its id, URL and
+  // expiry. Never served to the operator. Replaced once five minutes or less
+  // remain; the replaced session is expired at Stripe.
+  checkoutSessionId String?   @unique @map("checkout_session_id")
+  checkoutUrl       String?   @map("checkout_url") @db.VarChar(2048)
+  checkoutExpiresAt DateTime? @map("checkout_expires_at")
+  // When Stripe reported the proposal paid, and the session that paid it (D13).
+  paidAt            DateTime? @map("paid_at")
+  paidSessionId     String?   @map("paid_session_id")
+  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")
   versions PieceVersion[]
@@ -227,7 +273,9 @@ model PieceVersion {
 ///
 /// #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`
+/// `review`. An outbound row is always a `message` whose `payload` is null
+/// or, since #8515 D6, exactly `{ "action": "onboarding" }` — the one outbound
+/// action, rendered by the client's site as a link to `/account/onboarding`
 /// (`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
@@ -269,9 +317,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")
 }
@@ -338,7 +391,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])
@@ -1243,6 +1303,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.
@@ -1250,9 +1322,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/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"();

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

@@ -0,0 +1,231 @@
+-- #8435 — contact details on the client record (spec
+-- docs/specs/8435-contact-details-on-the-client-spec.md D1, D2).
+--
+--   people (13 columns) — given name, family name, an E.164 telephone, the
+--                    magnet's six-part address, a company name, a job title,
+--                    and the confirmation pair (who last saved the contact by
+--                    hand, and when). Every column is nullable and has no
+--                    default, so Postgres changes only the catalog.
+--   callbacks.person_id, subscribers.person_id — the Person a request or a
+--                    subscription belongs to: a composite foreign key onto
+--                    people(id, workspace_id), the #7877 shape, so "a Person
+--                    of the row's own workspace" is a database fact. NULL is
+--                    not checked (MATCH SIMPLE).
+--
+-- PURELY ADDITIVE, DDL ONLY. No existing row's values change here: the
+-- backfill is the next migration, 20261014121000_person_contact_backfill,
+-- split out so its row updates never run under the exclusive locks these
+-- ALTER TABLEs take. Prisma runs this file as one transaction, so each ALTER
+-- TABLE's ACCESS EXCLUSIVE lock on "people", "callbacks" and "subscribers"
+-- is held until the file commits. Every CHECK and foreign key below is added
+-- NOT VALID and then VALIDATEd over an all-NULL column or a table with no
+-- person_id yet, and none of the three is the large "leads" table; the window
+-- is accepted, as #852 accepted the same on "leads" (SEC-852-E, SEC-8435-C).
+--
+-- Rollout: deploy this migration BEFORE the API code that writes the columns;
+-- code without them fails every callback and subscription write.
+--
+-- Rollback: ALTER TABLE "callbacks" DROP CONSTRAINT "callbacks_person_fk",
+-- DROP COLUMN "person_id"; ALTER TABLE "subscribers" DROP CONSTRAINT
+-- "subscribers_person_fk", DROP COLUMN "person_id"; ALTER TABLE "people"
+-- DROP COLUMN "given_name", DROP COLUMN "family_name", DROP COLUMN
+-- "telephone", DROP COLUMN "address_line1", DROP COLUMN "address_line2",
+-- DROP COLUMN "address_city", DROP COLUMN "address_region", DROP COLUMN
+-- "address_postal_code", DROP COLUMN "address_country", DROP COLUMN
+-- "company_name", DROP COLUMN "job_title", DROP COLUMN "contact_confirmed_at",
+-- DROP COLUMN "contact_confirmed_by"; (the indexes and CHECKs go with them).
+
+-- AlterTable
+ALTER TABLE "people" ADD COLUMN     "address_city" VARCHAR(60),
+ADD COLUMN     "address_country" CHAR(2),
+ADD COLUMN     "address_line1" VARCHAR(100),
+ADD COLUMN     "address_line2" VARCHAR(60),
+ADD COLUMN     "address_postal_code" VARCHAR(20),
+ADD COLUMN     "address_region" VARCHAR(40),
+ADD COLUMN     "company_name" VARCHAR(200),
+ADD COLUMN     "contact_confirmed_at" TIMESTAMP(3),
+ADD COLUMN     "contact_confirmed_by" VARCHAR(16),
+ADD COLUMN     "family_name" VARCHAR(100),
+ADD COLUMN     "given_name" VARCHAR(100),
+ADD COLUMN     "job_title" VARCHAR(100),
+ADD COLUMN     "telephone" VARCHAR(16);
+
+-- AlterTable
+ALTER TABLE "callbacks" ADD COLUMN     "person_id" TEXT;
+
+-- AlterTable
+ALTER TABLE "subscribers" ADD COLUMN     "person_id" TEXT;
+
+-- CreateIndex
+CREATE INDEX "callbacks_person_id_idx" ON "callbacks"("person_id");
+
+-- CreateIndex
+CREATE INDEX "subscribers_person_id_idx" ON "subscribers"("person_id");
+
+-- A stored telephone is E.164 (the form the phone field posts) or NULL.
+ALTER TABLE "people" ADD CONSTRAINT "people_telephone_e164"
+  CHECK ("telephone" IS NULL OR "telephone" ~ '^\+[1-9][0-9]{6,14}$') NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_telephone_e164";
+
+-- The country is the upper-case ISO 3166-1 alpha-2 code.
+ALTER TABLE "people" ADD CONSTRAINT "people_address_country_format"
+  CHECK ("address_country" IS NULL OR "address_country" ~ '^[A-Z]{2}$') NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_address_country_format";
+
+-- An address is stored whole or not at all: all six parts NULL, or every
+-- part but the optional second line present.
+ALTER TABLE "people" ADD CONSTRAINT "people_address_complete"
+  CHECK (
+    ("address_line1" IS NULL AND "address_line2" IS NULL AND "address_city" IS NULL AND "address_region" IS NULL AND "address_postal_code" IS NULL AND "address_country" IS NULL)
+    OR
+    ("address_line1" IS NOT NULL AND "address_city" IS NOT NULL AND "address_region" IS NOT NULL AND "address_postal_code" IS NOT NULL AND "address_country" IS NOT NULL)
+  ) NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_address_complete";
+
+-- The confirmation pair is written together, and the actor is one of two.
+ALTER TABLE "people" ADD CONSTRAINT "people_contact_confirmed"
+  CHECK (
+    ("contact_confirmed_at" IS NULL AND "contact_confirmed_by" IS NULL)
+    OR
+    ("contact_confirmed_at" IS NOT NULL AND "contact_confirmed_by" IS NOT NULL AND "contact_confirmed_by" IN ('operator', 'client'))
+  ) NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_contact_confirmed";
+
+-- The two new reference columns carry the person_ format CHECK (the #852
+-- shape), added NOT VALID and then validated over an all-NULL column.
+ALTER TABLE "callbacks" ADD CONSTRAINT "callbacks_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 "callbacks" VALIDATE CONSTRAINT "callbacks_person_id_format";
+ALTER TABLE "subscribers" ADD CONSTRAINT "subscribers_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 "subscribers" VALIDATE CONSTRAINT "subscribers_person_id_format";
+
+-- AddForeignKey
+-- A callback / subscriber names a Person of ITS OWN workspace; deleting a
+-- Person with one is refused (the pieces_person_fk shape, #7877).
+ALTER TABLE "callbacks" ADD CONSTRAINT "callbacks_person_fk" FOREIGN KEY ("person_id", "workspace_id") REFERENCES "people"("id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE NOT VALID;
+ALTER TABLE "callbacks" VALIDATE CONSTRAINT "callbacks_person_fk";
+ALTER TABLE "subscribers" ADD CONSTRAINT "subscribers_person_fk" FOREIGN KEY ("person_id", "workspace_id") REFERENCES "people"("id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE NOT VALID;
+ALTER TABLE "subscribers" VALIDATE CONSTRAINT "subscribers_person_fk";
+
+-- ===== #8435 contact backfill (idempotent; runs after the DDL above) =====
+-- #8435 — the contact backfill (spec
+-- docs/specs/8435-contact-details-on-the-client-spec.md D2).
+--
+-- Gives every newsletter subscriber and every callback that carries a
+-- storable email a Person, stamps subscribers.person_id and
+-- callbacks.person_id, and fills a Person's blank telephone from the oldest
+-- callback phone that is already E.164 once spaces and punctuation are
+-- removed. 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.
+--
+--
+-- Normalization — the SQL twin of apps/api/src/services/person.ts's
+-- normalizePersonEmail / isStorablePersonEmail (#852's expressions verbatim):
+--   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.
+--
+-- A callback's email is its payload.email when that is a JSON string and
+-- VALID, else its buyer_email when VALID — the order the live code links in
+-- (capture first, the confirm step only when capture left it NULL;
+-- SEC-8435-G).
+--
+-- Rollback: nothing to undo on its own — dropping 20261014120000_person_contact's
+-- columns removes the stamps and the telephones this wrote; the Persons it
+-- created are ordinary Persons and are left in place.
+
+-- 1. Subscribers, oldest first: one Person per (workspace, normalized email).
+INSERT INTO "people" ("workspace_id", "email", "created_at", "updated_at")
+SELECT DISTINCT ON (s."workspace_id", lower(btrim(s."email", E' \t\n\r\f\x0B') COLLATE "C"))
+       s."workspace_id",
+       lower(btrim(s."email", E' \t\n\r\f\x0B') COLLATE "C"),
+       s."created_at",
+       now()
+FROM "subscribers" s
+WHERE lower(btrim(s."email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(s."email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY s."workspace_id", lower(btrim(s."email", E' \t\n\r\f\x0B') COLLATE "C"), s."created_at" ASC, s."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 2. Callbacks, oldest first: one Person per (workspace, normalized email),
+--    named from the callback's own name. A Person a lead or a subscriber
+--    already made keeps its name and created_at (ON CONFLICT DO NOTHING).
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (ce."workspace_id", ce."email_n")
+       ce."workspace_id",
+       ce."email_n",
+       NULLIF(left(btrim(regexp_replace(ce."name", '[\x01-\x1F\x7F-\x9F‎‏‪-‮⁦-⁩]', '', 'g')), 200), ''),
+       ce."created_at",
+       now()
+FROM (
+  SELECT c."id", c."workspace_id", c."name", c."phone", c."created_at",
+         (
+           SELECT v."e"
+           FROM (VALUES
+             (1, lower(btrim(CASE WHEN jsonb_typeof(c."payload" -> 'email') = 'string' THEN c."payload" ->> 'email' END, E' \t\n\r\f\x0B') COLLATE "C")),
+             (2, lower(btrim(c."buyer_email", E' \t\n\r\f\x0B') COLLATE "C"))
+           ) v("ord", "e")
+           WHERE v."e" ~ '^[!-?A-~]+@[!-?A-~]+$' AND length(v."e") <= 254
+           ORDER BY v."ord"
+           LIMIT 1
+         ) AS "email_n"
+  FROM "callbacks" c
+) ce
+WHERE ce."email_n" IS NOT NULL
+ORDER BY ce."workspace_id", ce."email_n", ce."created_at" ASC, ce."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 3. Stamps: every subscriber and callback with a storable email points at
+--    its workspace's Person; a row already stamped is left alone.
+UPDATE "subscribers"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "subscribers"."person_id" IS NULL
+  AND p."workspace_id" = "subscribers"."workspace_id"
+  AND p."email" = lower(btrim("subscribers"."email", E' \t\n\r\f\x0B') COLLATE "C");
+
+UPDATE "callbacks"
+SET "person_id" = p."id"
+FROM (
+  SELECT c."id" AS "callback_id", c."workspace_id",
+         (
+           SELECT v."e"
+           FROM (VALUES
+             (1, lower(btrim(CASE WHEN jsonb_typeof(c."payload" -> 'email') = 'string' THEN c."payload" ->> 'email' END, E' \t\n\r\f\x0B') COLLATE "C")),
+             (2, lower(btrim(c."buyer_email", E' \t\n\r\f\x0B') COLLATE "C"))
+           ) v("ord", "e")
+           WHERE v."e" ~ '^[!-?A-~]+@[!-?A-~]+$' AND length(v."e") <= 254
+           ORDER BY v."ord"
+           LIMIT 1
+         ) AS "email_n"
+  FROM "callbacks" c
+  WHERE c."person_id" IS NULL
+) ce
+JOIN "people" p ON p."workspace_id" = ce."workspace_id" AND p."email" = ce."email_n"
+WHERE "callbacks"."id" = ce."callback_id"
+  AND "callbacks"."person_id" IS NULL;
+
+-- 4. Telephone: for an uncurated Person (no linked user, never confirmed by
+--    hand — the rule a capture obeys, D4) with no telephone, the oldest
+--    stamped callback's phone with spaces and punctuation removed, when that
+--    is E.164. A national-format phone fills nothing.
+UPDATE "people" p
+SET "telephone" = c."tel",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (cb."person_id")
+         cb."person_id",
+         regexp_replace(cb."phone", '[ ().-]', '', 'g') AS "tel"
+  FROM "callbacks" cb
+  WHERE cb."person_id" IS NOT NULL
+    AND regexp_replace(cb."phone", '[ ().-]', '', 'g') ~ '^\+[1-9][0-9]{6,14}$'
+  ORDER BY cb."person_id", cb."created_at" ASC, cb."id" ASC
+) c
+WHERE p."id" = c."person_id"
+  AND p."telephone" IS NULL
+  AND p."user_id" IS NULL
+  AND p."contact_confirmed_at" IS NULL;

package/templates/database/migrations/20261015120000_person_notes/migration.sql

@@ -0,0 +1,77 @@
+-- #8514 — the client record's private notes (spec
+-- docs/specs/8514-redesign-the-person-record-page-spec.md D1, D2).
+--
+--   people (4 columns) — the team's one note on a client (never served to the
+--                    client), who last saved it (a user id of the auth
+--                    namespace, no foreign key — ADR 0009, the
+--                    piece_versions.delivered_by precedent), when, and which
+--                    agent when an agent saved it. Every column is nullable
+--                    and has no default, so Postgres changes only the catalog.
+--
+-- DDL first, then one data statement (D2b, below the marker): the DDL adds
+-- columns and CHECKs only; the data half removes inert client grants from
+-- agents of members. One directory, per the one-migration-per-milestone
+-- check (the #8435 person_contact shape). Prisma runs this file as one
+-- transaction; each CHECK below is added NOT VALID and then VALIDATEd over an
+-- all-NULL column, and the data half touches "agents" alone.
+--
+-- Rollout: deploy this migration BEFORE the API code that reads and writes the
+-- notes and gives members the client rows; code without the columns fails
+-- every notes read, and code before the grant reset would switch the inert
+-- grants on (SEC-8514-B).
+--
+-- Rollback: ALTER TABLE "people" DROP COLUMN "notes", DROP COLUMN
+-- "notes_updated_at", DROP COLUMN "notes_updated_by", DROP COLUMN
+-- "notes_updated_by_agent"; (the CHECKs go with them). The grant reset needs
+-- none: every grant it removes was inert.
+
+-- AlterTable
+ALTER TABLE "people" ADD COLUMN     "notes" VARCHAR(5000),
+ADD COLUMN     "notes_updated_at" TIMESTAMP(3),
+ADD COLUMN     "notes_updated_by" TEXT,
+ADD COLUMN     "notes_updated_by_agent" TEXT;
+
+-- The editor is a user id of the auth namespace (the delivered_by shape).
+ALTER TABLE "people" ADD CONSTRAINT "people_notes_updated_by_format"
+  CHECK ("notes_updated_by" IS NULL OR "notes_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}$') NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_notes_updated_by_format";
+
+-- The agent, when one saved it, is an agent id (the agents_id_format shape).
+ALTER TABLE "people" ADD CONSTRAINT "people_notes_updated_by_agent_format"
+  CHECK ("notes_updated_by_agent" IS NULL OR "notes_updated_by_agent" ~ '^agent_[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 "people" VALIDATE CONSTRAINT "people_notes_updated_by_agent_format";
+
+-- Who and when are written together.
+ALTER TABLE "people" ADD CONSTRAINT "people_notes_edit_pair"
+  CHECK (("notes_updated_at" IS NULL) = ("notes_updated_by" IS NULL)) NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_notes_edit_pair";
+
+-- An agent's save always names the agent's person.
+ALTER TABLE "people" ADD CONSTRAINT "people_notes_agent_has_person"
+  CHECK ("notes_updated_by_agent" IS NULL OR "notes_updated_by" IS NOT NULL) NOT VALID;
+ALTER TABLE "people" VALIDATE CONSTRAINT "people_notes_agent_has_person";
+
+-- ===== #8514 D2b member agent grant reset (data only; runs after the DDL above) =====
+-- #8514 — dormant client grants cleared from agents of members (spec
+-- docs/specs/8514-redesign-the-person-record-page-spec.md D2b, SEC-8514-B).
+--
+-- Until #8514 a member held neither people-read nor member-pieces-manage, so
+-- the agent clamp (`can(personTenant.role, p)`) dropped either grant stored on
+-- a member's agent: it was inert. #8514 gives members both by role, and the
+-- clamp would then switch those stored grants on with no admin action. This
+-- removes them first, so a member's agent holds either only once an owner or
+-- admin grants it after the deploy.
+--
+-- DATA ONLY. Changes no effective permission at the time it runs (every grant
+-- it removes is inert). Idempotent: a second run matches no row.
+--
+-- Rollout: in the same deploy as, and BEFORE, the #8514 API code.
+--
+-- Rollback: none needed — every removed grant was inert.
+
+UPDATE "agents" a
+SET "grants" = array_remove(array_remove(a."grants", 'people-read'), 'member-pieces-manage')
+FROM "memberships" m
+WHERE m."id" = a."responsible_membership_id"
+  AND m."role" = 'member'
+  AND a."grants" && ARRAY['people-read', 'member-pieces-manage']::text[];