create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/services/person.ts

@@ -1,1211 +0,0 @@
-/**
- * @file person.ts
- * @description Person — one client of one workspace (#852, spec
- * docs/specs/852-person-the-per-workspace-client-spec.md D3, D5, D6). This
- * file is the ONLY writer of `Person`:
- *
- *   - `findOrCreatePerson` — the one creator, called by lead capture
- *     (`lead-routing.ts`), the hub's own Stripe checkout webhook (through
- *     `recordCheckoutPerson` below), appointment creation
- *     (`scheduling/appointments.ts`) and the Admin inbox accept
- *     (`inbox-messages.ts`).
- *   - `stampPersonUser` — links a Person to a User, only on a verified-email
- *     match, never overwriting a link.
- *   - `recordCheckoutPerson` — the webhook's step: the Person of a completed
- *     hub checkout, with its live-mode customer id.
- *     `resolveCheckoutPerson` is the same step answering that Person too, for
- *     the checkout's terms grant (#8765 D14); the webhook calls it, and
- *     `recordCheckoutPerson` stays as its outcome-only form for the #852
- *     suites that pin that outcome.
- *   - `resolveMemberPersonId` — the member reads' Person (#7877 D8): the one
- *     linked to the caller, else the one whose email is the caller's
- *     verified email, linked on first read by `stampPersonUser`'s rule. That
- *     first link — and no other — releases the Person's held checkout plan
- *     (#8793 D2).
- *   - `resolveCallerBillingCustomerId` — the customer id the hub vouches for
- *     in `GET /v1/hub-sign-in/me` (#7961, spec 7894 D13): that same Person's,
- *     only while its `userId` is the caller.
- *   - `setPersonPlanOffering` — the plan's only writer (#7877 D8), called by
- *     the Admin's plan route and `releaseHeldCheckoutPlan`.
- *   - `releaseHeldCheckoutPlan` and `checkoutPlanKey` — the checkout plan
- *     rule (#7877 D10, #8793 D1–D4). A spoke's checkout lead never writes a
- *     plan: it holds it (`lead-routing.ts`), because its email is whatever
- *     the buyer typed at Stripe Checkout. The hold is released once, at the
- *     Person's first member-path link to the user whose VERIFIED email is the
- *     Person's own, into a blank plan only, and only when every held purchase
- *     under that email names the same plan key.
- *   - the contact details (#8435): `findOrCreatePerson` fills BLANK contact
- *     fields of an uncurated Person (D4); `updatePersonContact` (the
- *     operator's save), `ensureMemberPerson` and `setOwnPersonContact` (the
- *     client's save) overwrite and stamp who confirmed them (D9, D11).
- *
- * ## Match order (D3) — fixed, and there is no merge
- *
- * 1. Normalize the email (trim ASCII whitespace, lowercase ASCII letters);
- *    not storable → `invalid_email`, before any read.
- * 2. A customer id given → the oldest Person of this workspace carrying it.
- *    A hit is returned with NO write — its email is never rewritten.
- * 3. The Person of this workspace with this email. A hit gains the customer
- *    id only when it has none AND is linked to no user (first writer wins,
- *    else `billing: "kept"`), and a name only when it has none. The email is
- *    whatever the caller typed, never verified here, so it never pins a
- *    customer on a Person whose `userId` the verified-email stamp set
- *    (SEC-7894-6, decided on #7961 2026-10-09).
- * 4. No hit → `createMany({ skipDuplicates })` — Postgres INSERT … ON
- *    CONFLICT DO NOTHING — then a re-read that finds the winner of any
- *    concurrent create. The duplicate is absorbed IN THE DATABASE, never as
- *    a caught P2002: the appointment path calls this inside an interactive
- *    transaction, where a raised unique violation aborts the transaction
- *    (C4). One implementation serves both.
- *
- * ## Why public, and what it may import (D3)
- *
- * The base-tree `lead-routing.ts` imports this file, so it ships in every
- * build and must never reach the paid import closure: it imports
- * `lib/prisma.js`, `verified-email.js`, `planOfferingSchema` from the
- * base-tree kernel `@working-theory/validation` and types only — never
- * `lead-promotion.ts`, `owner-workspaces.ts`, `lead-accept-user.ts` (whose
- * find-or-create shape it mirrors) or `lib/tenant-db.ts`.
- * `packages/create-ailk/__tests__/paid-module-exclusions.test.ts` holds this
- * file and `lead-routing.ts` in `MUST_SHIP`.
- *
- * ## Tenancy
- *
- * Every `Person` statement is scoped by a server-resolved `workspaceId`;
- * there is no `Person` list read here (the reads are
- * `tenantDb(tenant).people`). The one list read is `releaseHeldCheckoutPlan`'s
- * (#8793 D3): the newest 51 `spokeCheckout` leads of a Person just linked to
- * the caller, by `(workspaceId, personId)`, the workspace the member read
- * resolved.
- * `recordCheckoutPerson`'s two other reads are by a server-minted
- * `FlowCheckout` id from a signature-verified webhook, matched on that
- * session's own `stripeSessionId`, then that row's lead scoped by the row's
- * own `workspaceId`. `resolveMemberPersonId` reads by `(workspaceId, userId)`
- * and by `(workspaceId, email)`, and `resolveCallerBillingCustomerId` by
- * `(id, workspaceId, userId)`, the workspace server-resolved and the user
- * the authenticated caller. `architecture.yaml` names this file as an
- * exclusion with that reason.
- *
- * ## Errors and logs
- *
- * A store error is caught and returned as a bare kind; no Prisma message is
- * returned or logged (SEC-006). These functions log nothing: each caller
- * logs the outcome kind, never an email, a name or a customer id. The
- * exceptions are `resolveMemberPersonId`, whose `null` hides a refused stamp,
- * and `resolveCallerBillingCustomerId`, whose `null` hides a failed read: each
- * logs that outcome's kind through the logger its caller passes.
- */
-
-import type { Prisma } from "@working-theory/database";
-import type { Id } from "@working-theory/ids";
-import { planOfferingSchema, type PersonContactPatch } from "@working-theory/validation";
-
-import { prisma } from "../lib/prisma.js";
-
-import { findVerifiedEmail } from "./verified-email.js";
-
-// ─── Normalization ────────────────────────────────────────────────────────────
-
-/** The ASCII whitespace the backfill's btrim set names: SP, HT, LF, CR, FF, VT. */
-const EDGE_WHITESPACE = /^[ \t\n\r\f\v]+|[ \t\n\r\f\v]+$/g;
-/** Printable ASCII, one `@`, a non-empty side each — the `people_email_normalized` CHECK. */
-const STORABLE_EMAIL = /^[!-?A-~]+@[!-?A-~]+$/;
-const MAX_EMAIL_LENGTH = 254;
-const MAX_NAME_CODE_POINTS = 200;
-const MAX_CUSTOMER_ID_LENGTH = 255;
-/** C0 and C1 controls and the bidi controls, removed from a name (SEC-852-I). */
-// eslint-disable-next-line no-control-regex -- the control-character range is exactly what a stored name must not carry.
-const NAME_STRIP = /[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
-
-/**
- * Trim ASCII whitespace, then lowercase ASCII letters only — the same value
- * Postgres computes as `lower(btrim(x, E' \t\n\r\f\x0B') COLLATE "C")`.
- */
-export function normalizePersonEmail(raw: string): string {
-  return raw
-    .replace(EDGE_WHITESPACE, "")
-    .replace(/[A-Z]/g, (c) => c.toLowerCase());
-}
-
-/**
- * Printable ASCII, one `@` with a non-empty side each, at most 254
- * characters — the `people_email_normalized` CHECK's regex. ASCII only, so
- * the TypeScript length and the Postgres length agree.
- */
-export function isStorablePersonEmail(email: string): boolean {
-  return email.length <= MAX_EMAIL_LENGTH && STORABLE_EMAIL.test(email);
-}
-
-/**
- * A name as stored: controls and bidi controls removed, trimmed of spaces, cut
- * to 200 code points; empty → `null`.
- */
-export function normalizePersonName(raw: unknown): string | null {
-  if (typeof raw !== "string") return null;
-  // Spaces only, as the backfill's `btrim(x)` trims, so a live-written
-  // name and a backfilled one agree.
-  const cleaned = Array.from(raw.replace(NAME_STRIP, "").replace(/^ +| +$/g, ""))
-    .slice(0, MAX_NAME_CODE_POINTS)
-    .join("");
-  return cleaned === "" ? null : cleaned;
-}
-
-// ─── Contact normalization (#8435 D3) ────────────────────────────────────────
-
-export type PersonAddress = {
-  addressLine1: string;
-  addressLine2: string | null;
-  city: string;
-  region: string;
-  postalCode: string;
-  country: string;
-};
-
-export type PersonContact = {
-  givenName: string | null;
-  familyName: string | null;
-  telephone: string | null;
-  address: PersonAddress | null;
-  companyName: string | null;
-  jobTitle: string | null;
-};
-
-/**
- * What a capture offers, as untrusted `unknown` values: the magnet's tagged
- * answers or a caller's explicit contact (`RouteLeadOptions.contact`).
- */
-export type LeadContact = {
-  name?: unknown;
-  givenName?: unknown;
-  familyName?: unknown;
-  phone?: unknown;
-  address?: unknown;
-  company?: unknown;
-  jobTitle?: unknown;
-};
-
-/** The widths of the person-level text columns, in code points. */
-const CONTACT_MAX = {
-  givenName: 100,
-  familyName: 100,
-  companyName: 200,
-  jobTitle: 100,
-} as const;
-/** The address parts' widths — `ADDRESS_PART_MAX_LENGTHS` in `packages/validation`. */
-const ADDRESS_MAX = {
-  addressLine1: 100,
-  addressLine2: 60,
-  city: 60,
-  region: 40,
-  postalCode: 20,
-} as const;
-const E164 = /^\+[1-9]\d{6,14}$/;
-const SHORT_REGION = /^[A-Za-z0-9]{1,3}$/;
-const ALPHA2 = /^[A-Z]{2}$/;
-/**
- * The code-point ranges `CONTACT_STRIP` removes (SEC-8435-L): `NAME_STRIP`'s
- * C0/C1 and bidi controls plus the zero-width characters U+200B–U+200D and
- * U+FEFF and the separators U+2028/U+2029. Numbers, not a regex literal, so no
- * tool can rewrite a separator into a line break inside it. The same set
- * `packages/validation`'s `people-contact.ts` strips on the wire.
- */
-const CONTACT_STRIPPED: ReadonlyArray<readonly [number, number]> = [
-  [0x0000, 0x001f],
-  [0x007f, 0x009f],
-  [0x200b, 0x200f],
-  [0x2028, 0x2029],
-  [0x202a, 0x202e],
-  [0x2066, 0x2069],
-  [0xfeff, 0xfeff],
-];
-
-function stripContactChars(raw: string): string {
-  let out = "";
-  for (const ch of raw) {
-    const cp = ch.codePointAt(0) ?? 0;
-    if (!CONTACT_STRIPPED.some(([lo, hi]) => cp >= lo && cp <= hi)) out += ch;
-  }
-  return out;
-}
-
-const cutToCodePoints = (value: string, max: number): string =>
-  Array.from(value).slice(0, max).join("");
-
-/** Stripped, trimmed, cut to `max` code points; empty or not a string → `null`. */
-function normalizeContactText(raw: unknown, max: number): string | null {
-  if (typeof raw !== "string") return null;
-  const cleaned = cutToCodePoints(stripContactChars(raw).trim(), max);
-  return cleaned === "" ? null : cleaned;
-}
-
-/**
- * Strip spaces, `( ) . -` (and the invisible characters), then the result
- * must be an E.164 number — else `null`.
- */
-export function normalizeTelephone(raw: unknown): string | null {
-  if (typeof raw !== "string") return null;
-  const compact = stripContactChars(raw)
-    .replace(/[ ().-]/g, "")
-    .trim();
-  return E164.test(compact) ? compact : null;
-}
-
-/**
- * An address as stored: whole or not at all. Every required part must be a
- * non-empty string within its width after stripping; a short region is
- * upper-cased (C3); the country must be an upper-case alpha-2 code.
- */
-function normalizeAddress(raw: unknown): PersonAddress | null {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-    return null;
-  const value = raw as Record<string, unknown>;
-  const part = (key: keyof typeof ADDRESS_MAX): string | null => {
-    const field = value[key];
-    if (typeof field !== "string") return null;
-    const cleaned = stripContactChars(field).trim();
-    return cleaned === "" || Array.from(cleaned).length > ADDRESS_MAX[key]
-      ? null
-      : cleaned;
-  };
-  const addressLine1 = part("addressLine1");
-  const city = part("city");
-  const region = part("region");
-  const postalCode = part("postalCode");
-  const country = value["country"];
-  if (
-    addressLine1 === null ||
-    city === null ||
-    region === null ||
-    postalCode === null ||
-    typeof country !== "string" ||
-    !ALPHA2.test(country)
-  ) {
-    return null;
-  }
-  const line2Raw = value["addressLine2"];
-  const line2 = part("addressLine2");
-  // An over-long or non-string second line makes the address unusable; an
-  // absent or blank one is simply null.
-  if (line2 === null && line2Raw !== undefined && line2Raw !== null) {
-    if (
-      typeof line2Raw !== "string" ||
-      stripContactChars(line2Raw).trim() !== ""
-    )
-      return null;
-  }
-  return {
-    addressLine1,
-    addressLine2: line2,
-    city,
-    region: SHORT_REGION.test(region) ? region.toUpperCase() : region,
-    postalCode,
-    country,
-  };
-}
-
-/** Capture-side: every usable field, each normalized; unusable ones dropped. */
-export function normalizeCapturedContact(
-  raw: LeadContact,
-): Partial<PersonContact> {
-  const out: Partial<PersonContact> = {};
-  const givenName = normalizeContactText(raw.givenName, CONTACT_MAX.givenName);
-  if (givenName !== null) out.givenName = givenName;
-  const familyName = normalizeContactText(
-    raw.familyName,
-    CONTACT_MAX.familyName,
-  );
-  if (familyName !== null) out.familyName = familyName;
-  const telephone = normalizeTelephone(raw.phone);
-  if (telephone !== null) out.telephone = telephone;
-  const address = normalizeAddress(raw.address);
-  if (address !== null) out.address = address;
-  const companyName = normalizeContactText(
-    raw.company,
-    CONTACT_MAX.companyName,
-  );
-  if (companyName !== null) out.companyName = companyName;
-  const jobTitle = normalizeContactText(raw.jobTitle, CONTACT_MAX.jobTitle);
-  if (jobTitle !== null) out.jobTitle = jobTitle;
-  return out;
-}
-
-// ─── The contact columns, as rows and as the wire's shape ───────────────────
-
-/** The thirteen contact columns a read names (`select`). */
-export const PERSON_CONTACT_SELECT = {
-  givenName: true,
-  familyName: true,
-  telephone: true,
-  addressLine1: true,
-  addressLine2: true,
-  addressCity: true,
-  addressRegion: true,
-  addressPostalCode: true,
-  addressCountry: true,
-  companyName: true,
-  jobTitle: true,
-  contactConfirmedAt: true,
-  contactConfirmedBy: true,
-} as const;
-
-export type PersonContactRow = {
-  givenName: string | null;
-  familyName: string | null;
-  telephone: string | null;
-  addressLine1: string | null;
-  addressLine2: string | null;
-  addressCity: string | null;
-  addressRegion: string | null;
-  addressPostalCode: string | null;
-  addressCountry: string | null;
-  companyName: string | null;
-  jobTitle: string | null;
-  contactConfirmedAt: Date | null;
-  contactConfirmedBy: string | null;
-};
-
-/** The wire's contact: every key present, `null` where blank, the address whole or `null`. */
-export function personContactFromRow(row: PersonContactRow): PersonContact {
-  // `?? null` so a row that does not carry a column reads as blank, never as
-  // `undefined` on the wire.
-  const line1 = row.addressLine1 ?? null;
-  const city = row.addressCity ?? null;
-  const region = row.addressRegion ?? null;
-  const postalCode = row.addressPostalCode ?? null;
-  const country = row.addressCountry ?? null;
-  const address: PersonAddress | null =
-    line1 !== null && city !== null && region !== null && postalCode !== null && country !== null
-      ? {
-          addressLine1: line1,
-          addressLine2: row.addressLine2 ?? null,
-          city,
-          region,
-          postalCode,
-          country,
-        }
-      : null;
-  return {
-    givenName: row.givenName ?? null,
-    familyName: row.familyName ?? null,
-    telephone: row.telephone ?? null,
-    address,
-    companyName: row.companyName ?? null,
-    jobTitle: row.jobTitle ?? null,
-  };
-}
-
-/** Who last saved the contact by hand, and when — `null` while only captures have written it. */
-export function contactConfirmedFromRow(
-  row: Pick<PersonContactRow, "contactConfirmedAt" | "contactConfirmedBy">,
-): { by: "operator" | "client"; at: string } | null {
-  if (row.contactConfirmedAt === null || row.contactConfirmedAt === undefined)
-    return null;
-  if (
-    row.contactConfirmedBy !== "operator" &&
-    row.contactConfirmedBy !== "client"
-  )
-    return null;
-  return {
-    by: row.contactConfirmedBy,
-    at: row.contactConfirmedAt.toISOString(),
-  };
-}
-
-type AddressColumns = {
-  addressLine1: string | null;
-  addressLine2: string | null;
-  addressCity: string | null;
-  addressRegion: string | null;
-  addressPostalCode: string | null;
-  addressCountry: string | null;
-};
-
-/** The six address columns for an address — all six `null` for `null`. */
-function addressColumns(address: PersonAddress | null): AddressColumns {
-  return {
-    addressLine1: address?.addressLine1 ?? null,
-    addressLine2: address?.addressLine2 ?? null,
-    addressCity: address?.city ?? null,
-    addressRegion: address?.region ?? null,
-    addressPostalCode: address?.postalCode ?? null,
-    addressCountry: address?.country ?? null,
-  };
-}
-
-/** The scalar contact fields, each its own column of the same name. */
-const SCALAR_CONTACT_FIELDS = [
-  "givenName",
-  "familyName",
-  "telephone",
-  "companyName",
-  "jobTitle",
-] as const;
-
-/** Every supplied contact field as insert columns. */
-function contactInsertColumns(
-  contact: Partial<PersonContact>,
-): Record<string, string | null> {
-  const columns: Record<string, string | null> = {};
-  for (const field of SCALAR_CONTACT_FIELDS) {
-    const value = contact[field];
-    if (value !== undefined && value !== null) columns[field] = value;
-  }
-  if (contact.address) Object.assign(columns, addressColumns(contact.address));
-  return columns;
-}
-
-/** `"Ada" + "Lovelace"` → `"Ada Lovelace"`, `"Ada"` alone → `"Ada"`, neither → `null`. */
-function joinedName(contact: Partial<PersonContact>): string | null {
-  return normalizePersonName(
-    [contact.givenName, contact.familyName].filter((part) => part).join(" "),
-  );
-}
-
-function usableCustomerId(raw: string | null | undefined): string | null {
-  return typeof raw === "string" &&
-    raw.length > 0 &&
-    raw.length <= MAX_CUSTOMER_ID_LENGTH
-    ? raw
-    : null;
-}
-
-/** A Stripe customer id: `cus_` and letters or digits only, no separator. */
-const STRIPE_CUSTOMER_ID = /^cus_[A-Za-z0-9]+$/;
-
-/**
- * The Stripe Dashboard link to one customer (#9349 DD5). Pure: the caller
- * reads the mode. `null` unless `customerId` is a well-formed `cus_` id of
- * at most 255 characters, so a stored value can never add a path segment,
- * a query or a fragment to the fixed Dashboard host.
- */
-export function stripeCustomerDashboardUrl(
-  customerId: string,
-  mode: "test" | "live",
-): string | null {
-  if (
-    customerId.length > MAX_CUSTOMER_ID_LENGTH ||
-    !STRIPE_CUSTOMER_ID.test(customerId)
-  ) {
-    return null;
-  }
-  const segment = mode === "test" ? "test/customers" : "customers";
-  return `https://dashboard.stripe.com/${segment}/${customerId}`;
-}
-
-// ─── findOrCreatePerson ───────────────────────────────────────────────────────
-
-/** The one delegate this file writes through — the shared client or a transaction's. */
-export type PersonDb = Pick<Prisma.TransactionClient, "person">;
-
-export type FindOrCreatePersonResult =
-  | {
-      ok: true;
-      value: {
-        personId: Id<"person">;
-        created: boolean;
-        billing: "written" | "kept" | "unchanged";
-      };
-    }
-  | { ok: false; error: { kind: "invalid_email" | "internal_error" } };
-
-type MatchedPerson = {
-  id: string;
-  name: string | null;
-  userId: string | null;
-  billingCustomerId: string | null;
-  // #8435 D4.4 — the blank-sentinels the contact fill reads. A value reading
-  // `undefined` (a test double that does not carry the key) is "not blank",
-  // and an undefined `contactConfirmedAt` is "confirmed": no fill runs.
-  givenName?: string | null;
-  familyName?: string | null;
-  telephone?: string | null;
-  addressLine1?: string | null;
-  companyName?: string | null;
-  jobTitle?: string | null;
-  contactConfirmedAt?: Date | null;
-};
-
-const MATCH_SELECT = {
-  id: true,
-  name: true,
-  userId: true,
-  billingCustomerId: true,
-  givenName: true,
-  familyName: true,
-  telephone: true,
-  addressLine1: true,
-  companyName: true,
-  jobTitle: true,
-  contactConfirmedAt: true,
-} as const;
-
-/**
- * Step 3's writes on an email match: the customer id only when the Person
- * has none and is linked to no user, the name only when it has none — each
- * one guarded `updateMany`, so a concurrent writer's value, or a stamp that
- * lands between the read and the write, is never overwritten or bypassed.
- */
-async function enrichMatched(
-  db: PersonDb,
-  workspaceId: string,
-  person: MatchedPerson,
-  name: string | null,
-  customerId: string | null,
-): Promise<"written" | "kept" | "unchanged"> {
-  let billing: "written" | "kept" | "unchanged" = "unchanged";
-  if (customerId !== null) {
-    if (person.billingCustomerId !== null || person.userId !== null) {
-      billing = "kept";
-    } else {
-      const written = await db.person.updateMany({
-        where: { id: person.id, workspaceId, userId: null, billingCustomerId: null },
-        data: { billingProvider: "stripe", billingCustomerId: customerId },
-      });
-      billing = written.count === 1 ? "written" : "kept";
-    }
-  }
-  if (name !== null && person.name === null) {
-    await db.person.updateMany({
-      where: { id: person.id, workspaceId, name: null },
-      data: { name },
-    });
-  }
-  return billing;
-}
-
-/**
- * The contact fill on an email match (#8435 D4.3): for each supplied field
- * whose stored value is `null`, one guarded `updateMany`; the address is one
- * statement guarded on `addressLine1: null` writing all six. It runs ONLY
- * while the Person is uncurated — linked to no user and never saved by hand
- * (`contactConfirmedAt` null) — and every guard repeats that condition, so a
- * link or a save that lands between the read and the write still wins
- * (SEC-8435-A). A stored value, whoever wrote it, is never overwritten.
- * Best-effort: a failed write is swallowed, never refusing the capture.
- */
-async function fillBlankContact(
-  db: PersonDb,
-  workspaceId: string,
-  person: MatchedPerson,
-  contact: Partial<PersonContact>,
-  plainName: string | null,
-): Promise<void> {
-  if (person.userId !== null || person.contactConfirmedAt !== null) return;
-  const uncurated = { id: person.id, workspaceId, userId: null, contactConfirmedAt: null };
-  try {
-    for (const field of SCALAR_CONTACT_FIELDS) {
-      const value = contact[field];
-      if (value !== undefined && value !== null && person[field] === null) {
-        await db.person.updateMany({
-          where: { ...uncurated, [field]: null } as Prisma.PersonWhereInput,
-          data: { [field]: value } as Prisma.PersonUpdateManyMutationInput,
-        });
-      }
-    }
-    if (contact.address && person.addressLine1 === null) {
-      await db.person.updateMany({
-        where: { ...uncurated, addressLine1: null },
-        data: addressColumns(contact.address),
-      });
-    }
-    // The display name from given + family, only when nothing named it.
-    if (plainName === null && person.name === null) {
-      const derived = joinedName(contact);
-      if (derived !== null) {
-        await db.person.updateMany({ where: { ...uncurated, name: null }, data: { name: derived } });
-      }
-    }
-  } catch {
-    // A contact fill never changes the capture's outcome.
-  }
-}
-
-/**
- * Find this workspace's Person for an email, or create it.
- *
- * @param workspaceId the SERVER-RESOLVED workspace id — never a request value.
- * @param input.email the raw address; normalized here.
- * @param input.name an optional display name, from anonymous text.
- * @param input.billingCustomerId an optional provider customer id.
- * @param input.contact optional, already-normalized contact fields
- *   (`normalizeCapturedContact`): a created Person carries them all; a matched
- *   uncurated Person gains only the ones it has blank (#8435 D4).
- * @param db the shared client by default; the appointment path passes its
- *   transaction client so the step runs on the lock's own connection.
- */
-export async function findOrCreatePerson(
-  workspaceId: string,
-  input: {
-    email: string;
-    name?: string | null;
-    billingCustomerId?: string | null;
-    contact?: Partial<PersonContact>;
-  },
-  db: PersonDb = prisma,
-): Promise<FindOrCreatePersonResult> {
-  const email =
-    typeof input.email === "string" ? normalizePersonEmail(input.email) : "";
-  if (!isStorablePersonEmail(email)) {
-    return { ok: false, error: { kind: "invalid_email" } };
-  }
-  const name = normalizePersonName(input.name);
-  const customerId = usableCustomerId(input.billingCustomerId);
-  const contact = input.contact ?? {};
-  const hasContact = Object.keys(contact).length > 0;
-
-  try {
-    // Step 2 — a customer id names its Person; nothing is written.
-    if (customerId !== null) {
-      const byCustomer = await db.person.findFirst({
-        where: { workspaceId, billingCustomerId: customerId },
-        orderBy: [{ createdAt: "asc" }, { id: "asc" }],
-        select: { id: true },
-      });
-      if (byCustomer) {
-        return {
-          ok: true,
-          value: {
-            personId: byCustomer.id as Id<"person">,
-            created: false,
-            billing: "unchanged",
-          },
-        };
-      }
-    }
-
-    // Step 3 — the email's Person.
-    const byEmail = await db.person.findFirst({
-      where: { workspaceId, email },
-      select: MATCH_SELECT,
-    });
-    if (byEmail) {
-      const billing = await enrichMatched(db, workspaceId, byEmail, name, customerId);
-      if (hasContact) await fillBlankContact(db, workspaceId, byEmail, contact, name);
-      return {
-        ok: true,
-        value: { personId: byEmail.id as Id<"person">, created: false, billing },
-      };
-    }
-
-    // Step 4 — insert, absorbing a concurrent duplicate in the database.
-    const inserted = await db.person.createMany({
-      data: [
-        {
-          workspaceId,
-          email,
-          // A supplied name wins; else given + family joined (#8435 D4.2).
-          name: name ?? joinedName(contact),
-          ...(customerId !== null && {
-            billingProvider: "stripe",
-            billingCustomerId: customerId,
-          }),
-          ...(hasContact && contactInsertColumns(contact)),
-        },
-      ],
-      skipDuplicates: true,
-    });
-    const winner = await db.person.findFirst({
-      where: { workspaceId, email },
-      select: MATCH_SELECT,
-    });
-    if (!winner) return { ok: false, error: { kind: "internal_error" } };
-    if (inserted.count === 1) {
-      return {
-        ok: true,
-        value: {
-          personId: winner.id as Id<"person">,
-          created: true,
-          billing: customerId !== null ? "written" : "unchanged",
-        },
-      };
-    }
-    // A concurrent create won the race: treat its row as an email match.
-    const billing = await enrichMatched(db, workspaceId, winner, name, customerId);
-    if (hasContact) await fillBlankContact(db, workspaceId, winner, contact, name);
-    return {
-      ok: true,
-      value: { personId: winner.id as Id<"person">, created: false, billing },
-    };
-  } catch {
-    return { ok: false, error: { kind: "internal_error" } };
-  }
-}
-
-// ─── stampPersonUser (D5) ─────────────────────────────────────────────────────
-
-export type StampPersonUserOutcome =
-  | "stamped"
-  | "already_linked"
-  | "user_unverified"
-  | "email_mismatch"
-  | "linked_to_other_user"
-  | "user_on_other_person"
-  | "not_found"
-  | "internal_error";
-
-function isUniqueViolation(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    (err as { code?: unknown }).code === "P2002"
-  );
-}
-
-/**
- * Link a Person to a User — only when the User's VERIFIED email normalizes
- * to the Person's (`verified-email.ts`'s rule), and never over an existing
- * link. Creating a Person never calls this: no verified email is needed to
- * exist. Runs outside any transaction, so catching a P2002 is safe here.
- */
-export async function stampPersonUser(
-  workspaceId: string,
-  personId: string,
-  userId: string,
-): Promise<StampPersonUserOutcome> {
-  try {
-    const person = await prisma.person.findFirst({
-      where: { id: personId, workspaceId },
-      select: { email: true, userId: true },
-    });
-    if (!person) return "not_found";
-    if (person.userId === userId) return "already_linked";
-    if (person.userId !== null) return "linked_to_other_user";
-
-    const verified = await findVerifiedEmail(userId);
-    if (!verified.ok) return "user_unverified";
-    if (normalizePersonEmail(verified.value.email) !== person.email) {
-      return "email_mismatch";
-    }
-
-    let count: number;
-    try {
-      ({ count } = await prisma.person.updateMany({
-        where: { id: personId, workspaceId, userId: null },
-        data: { userId },
-      }));
-    } catch (err) {
-      if (isUniqueViolation(err)) return "user_on_other_person";
-      throw err;
-    }
-    if (count === 1) return "stamped";
-
-    const reread = await prisma.person.findFirst({
-      where: { id: personId, workspaceId },
-      select: { userId: true },
-    });
-    if (!reread) return "not_found";
-    return reread.userId === userId ? "already_linked" : "linked_to_other_user";
-  } catch {
-    return "internal_error";
-  }
-}
-
-// ─── recordCheckoutPerson (D6) ────────────────────────────────────────────────
-
-export type CheckoutPersonOutcome =
-  | "person_written"
-  | "person_kept"
-  | "person_unchanged"
-  | "person_skipped"
-  | "person_failed";
-
-/** `recordCheckoutPerson`'s outcome plus the Person it found or created (#8765 D14). */
-export type CheckoutPersonResult = {
-  outcome: CheckoutPersonOutcome;
-  /** The checkout's Person, or `null` when the step skipped or failed. */
-  person: { workspaceId: string; personId: string } | null;
-};
-
-/**
- * The hub webhook's Person step for a paid `checkout.session.completed` of
- * its OWN site carrying `metadata.flowCheckoutId`.
- *
- * Reads the checkout row THIS session completed (`stripeSessionId` must be
- * this session's id and the row `completed`), so a session that merely names
- * another checkout's id matches nothing (SEC-852-H); then that row's lead,
- * scoped by the row's workspace. The customer id's one source is
- * `session.customer`, and it is passed only for a LIVE-mode event: a
- * test-mode checkout typed with someone else's email cannot pin a customer
- * id on their Person (SEC-852-A). Never throws.
- */
-export async function recordCheckoutPerson(input: {
-  flowCheckoutId: string;
-  stripeSessionId: string | null | undefined;
-  customer: unknown;
-  livemode: boolean;
-}): Promise<CheckoutPersonOutcome> {
-  return (await resolveCheckoutPerson(input)).outcome;
-}
-
-/**
- * `recordCheckoutPerson`, also answering the Person it found or created —
- * the subject of the checkout's terms grant (#8765 D14), which reads the
- * flow checkout's Person from here and never creates one itself.
- */
-export async function resolveCheckoutPerson(input: {
-  flowCheckoutId: string;
-  stripeSessionId: string | null | undefined;
-  customer: unknown;
-  livemode: boolean;
-}): Promise<CheckoutPersonResult> {
-  const skipped = { outcome: "person_skipped", person: null } as const;
-  if (typeof input.stripeSessionId !== "string" || input.stripeSessionId === "") {
-    return skipped;
-  }
-  try {
-    const checkout = await prisma.flowCheckout.findFirst({
-      where: {
-        id: input.flowCheckoutId,
-        stripeSessionId: input.stripeSessionId,
-        status: "completed",
-      },
-      select: { leadId: true, workspaceId: true },
-    });
-    if (!checkout) return skipped;
-
-    const lead = await prisma.lead.findFirst({
-      where: { id: checkout.leadId, workspaceId: checkout.workspaceId },
-      select: { email: true },
-    });
-    if (!lead) return skipped;
-
-    const customerId =
-      input.livemode === true && typeof input.customer === "string"
-        ? input.customer
-        : undefined;
-    const result = await findOrCreatePerson(checkout.workspaceId, {
-      email: lead.email,
-      ...(customerId !== undefined && { billingCustomerId: customerId }),
-    });
-    if (!result.ok) {
-      return result.error.kind === "invalid_email"
-        ? skipped
-        : { outcome: "person_failed", person: null };
-    }
-    const person = {
-      workspaceId: checkout.workspaceId,
-      personId: result.value.personId,
-    };
-    switch (result.value.billing) {
-      case "written":
-        return { outcome: "person_written", person };
-      case "kept":
-        return { outcome: "person_kept", person };
-      default:
-        return { outcome: "person_unchanged", person };
-    }
-  } catch {
-    return { outcome: "person_failed", person: null };
-  }
-}
-
-// ─── The member area (#7877 D8) ───────────────────────────────────────────────
-
-/**
- * The Person a member read answers for: this workspace's Person linked to
- * the caller, else the one whose email is the caller's VERIFIED email —
- * linked now through `stampPersonUser` (its rule, unchanged) and the answer
- * only on `stamped` or `already_linked`. `null` is "not a client here";
- * every other stamp outcome, and a store error, is `null` too, logged by its
- * kind only. Never throws.
- *
- * A fresh `stamped` link — and only that — releases the Person's held
- * checkout plan (#8793 D2, `releaseHeldCheckoutPlan`): the caller has just
- * proven they own the email the purchases were made under. A Person linked
- * earlier, a refused stamp and every other caller of `stampPersonUser` (the
- * Inbox accept above all) release nothing. The release never changes the
- * answer; an `ambiguous` or `internal_error` release is logged by its kind
- * only, as `{ event: "checkout-plan-release", outcome }`.
- *
- * @param workspaceId the SERVER-RESOLVED workspace (the calling spoke's).
- * @param userId the authenticated caller.
- * @param verifiedEmail the caller's verified address, read by the caller.
- */
-export async function resolveMemberPersonId(
-  workspaceId: string,
-  userId: string,
-  verifiedEmail: string,
-  log?: { warn: (obj: object, msg: string) => void },
-): Promise<string | null> {
-  let byEmail: { id: string } | null;
-  try {
-    const linked = await prisma.person.findFirst({
-      where: { workspaceId, userId },
-      select: { id: true },
-    });
-    if (linked) return linked.id;
-
-    byEmail = await prisma.person.findFirst({
-      where: { workspaceId, email: normalizePersonEmail(verifiedEmail) },
-      select: { id: true },
-    });
-  } catch {
-    // A store error is "not a client here" for this read: never thrown.
-    log?.warn({ event: "member-person-stamp", outcome: "internal_error" }, "[person] member read failed");
-    return null;
-  }
-  if (!byEmail) return null;
-
-  const outcome = await stampPersonUser(workspaceId, byEmail.id, userId);
-  if (outcome === "stamped") {
-    const release = await releaseHeldCheckoutPlan(
-      workspaceId,
-      byEmail.id,
-      userId,
-      normalizePersonEmail(verifiedEmail),
-    );
-    if (release === "ambiguous" || release === "internal_error") {
-      log?.warn({ event: "checkout-plan-release", outcome: release }, "[person] held checkout plan not released");
-    }
-    return byEmail.id;
-  }
-  if (outcome === "already_linked") return byEmail.id;
-  log?.warn({ event: "member-person-stamp", outcome }, "[person] member link refused");
-  return null;
-}
-
-/**
- * The customer id the hub vouches for to a spoke's buy route (#7961, spec
- * 7894 D13): the `billingCustomerId` of the Person `resolveMemberPersonId`
- * answers for (workspace, caller), read only while that Person's `userId` is
- * the caller — never a Person matched by email alone (SEC-7894-6). `null` is
- * "no customer to reuse"; a store error is `null` too, logged by its kind
- * only. Never throws.
- *
- * @param workspaceId the SERVER-RESOLVED workspace (the calling spoke's).
- * @param userId the authenticated caller.
- * @param verifiedEmail the caller's verified address, read by the caller.
- */
-export async function resolveCallerBillingCustomerId(
-  workspaceId: string,
-  userId: string,
-  verifiedEmail: string,
-  log?: { warn: (obj: object, msg: string) => void },
-): Promise<string | null> {
-  const personId = await resolveMemberPersonId(workspaceId, userId, verifiedEmail, log);
-  if (personId === null) return null;
-  try {
-    const person = await prisma.person.findFirst({
-      where: { id: personId, workspaceId, userId },
-      select: { billingCustomerId: true },
-    });
-    return person?.billingCustomerId ?? null;
-  } catch {
-    log?.warn({ event: "buyer-customer-read", outcome: "internal_error" }, "[person] buyer read failed");
-    return null;
-  }
-}
-
-export type SetPlanOfferingOutcome = "set" | "not_found" | "internal_error";
-
-/**
- * Set — or, with `null`, clear — a Person's plan: the ONE writer of
- * `Person.planOffering`, called by the Admin's plan route and the held
- * checkout plan's release (#8793). One `updateMany` scoped by the
- * server-resolved workspace; no row → `not_found`. Never throws.
- *
- * With a `guard` (#8793 D5, the release's own write) the statement also
- * requires a blank plan and the Person still linked to `guard.linkedUserId`,
- * so a plan already set — or one the operator PUTs at the same moment — wins
- * and the answer is `not_found`. Without one it is the operator's overwrite.
- */
-export async function setPersonPlanOffering(
-  workspaceId: string,
-  personId: string,
-  planOffering: string | null,
-  guard?: { linkedUserId: string },
-): Promise<SetPlanOfferingOutcome> {
-  try {
-    const { count } = await prisma.person.updateMany({
-      where: {
-        id: personId,
-        workspaceId,
-        ...(guard !== undefined && { planOffering: null, userId: guard.linkedUserId }),
-      },
-      data: { planOffering },
-    });
-    return count === 0 ? "not_found" : "set";
-  } catch {
-    return "internal_error";
-  }
-}
-
-// ─── The held checkout plan (#8793 D3, D4) ───────────────────────────────────
-
-/**
- * A spoke checkout's plan key: the offering minus a leading `<site>_` (when
- * the site is a string), answered only when `planOfferingSchema` — the key
- * the operator's PUT accepts — admits it; else `null`. Shared by the
- * checkout's hold (`lead-routing.ts`) and the release below.
- */
-export function checkoutPlanKey(offering: unknown, site: unknown): string | null {
-  if (typeof offering !== "string") return null;
-  const prefix = typeof site === "string" ? `${site}_` : null;
-  const key = prefix !== null && offering.startsWith(prefix) ? offering.slice(prefix.length) : offering;
-  return planOfferingSchema.safeParse(key).success ? key : null;
-}
-
-export type HeldPlanOutcome = "set" | "none" | "ambiguous" | "kept" | "internal_error";
-
-/** The most held purchases a release weighs; one more is `ambiguous`. */
-const HELD_PURCHASES_READ = 50;
-
-/**
- * Release a Person's held checkout plan (#8793 D3) — called only by
- * `resolveMemberPersonId` on a fresh `stamped` link, so `verifiedEmail` (the
- * caller's, normalized) is the Person's own. The Person's marked spoke
- * checkout leads (`Lead.spokeCheckout`, newest 51) under that email are taken
- * as a SET: one distinct plan key is written to a blank plan through the
- * guarded `setPersonPlanOffering` (`set`, or `kept` when the guard matched
- * nothing — a plan was already there, or the Person is no longer linked to
- * `userId`); no key is `none`; more than one key, or more than 50 leads, is
- * `ambiguous` and writes nothing — the operator sets the plan. So a
- * stranger's purchase under the owner's email can deny the automatic plan,
- * never choose it (SEC-8793-A). A store error is `internal_error`. Never
- * throws, and logs nothing: the caller logs the kind.
- */
-export async function releaseHeldCheckoutPlan(
-  workspaceId: string,
-  personId: string,
-  userId: string,
-  verifiedEmail: string,
-): Promise<HeldPlanOutcome> {
-  try {
-    const rows = await prisma.lead.findMany({
-      where: { workspaceId, personId, spokeCheckout: true },
-      orderBy: [{ createdAt: "desc" }, { id: "desc" }],
-      take: HELD_PURCHASES_READ + 1,
-      select: { email: true, payload: true },
-    });
-    if (rows.length > HELD_PURCHASES_READ) return "ambiguous";
-
-    const keys = new Set<string>();
-    for (const row of rows) {
-      // The purchase read's own rule: a purchase is its Person's only under
-      // the Person's own email.
-      if (normalizePersonEmail(row.email) !== verifiedEmail) continue;
-      const payload = (row.payload ?? {}) as Record<string, unknown>;
-      const key = checkoutPlanKey(payload["offering"], payload["site"]);
-      if (key !== null) keys.add(key);
-    }
-    if (keys.size > 1) return "ambiguous";
-    const [key] = keys;
-    if (key === undefined) return "none";
-
-    const written = await setPersonPlanOffering(workspaceId, personId, key, { linkedUserId: userId });
-    if (written === "set") return "set";
-    return written === "not_found" ? "kept" : "internal_error";
-  } catch {
-    return "internal_error";
-  }
-}
-
-// ─── The two human edits of the contact (#8435 D9, D11) ───────────────────────
-
-export type SavedContact = {
-  contact: PersonContact;
-  confirmed: { by: "operator" | "client"; at: string } | null;
-};
-
-export type SaveContactOutcome =
-  | { kind: "saved"; value: SavedContact }
-  | { kind: "not_found" | "internal_error" };
-
-/** The columns a patch writes: only the keys present; the address key writes (or clears) all six. */
-function patchColumns(patch: PersonContactPatch): Record<string, string | null> {
-  const columns: Record<string, string | null> = {};
-  for (const field of SCALAR_CONTACT_FIELDS) {
-    const value = patch[field];
-    if (value !== undefined) columns[field] = value;
-  }
-  if (patch.address !== undefined) Object.assign(columns, addressColumns(patch.address));
-  return columns;
-}
-
-async function readSavedContact(workspaceId: string, personId: string): Promise<SaveContactOutcome> {
-  const row = await prisma.person.findFirst({
-    where: { id: personId, workspaceId },
-    select: PERSON_CONTACT_SELECT,
-  });
-  if (!row) return { kind: "not_found" };
-  return { kind: "saved", value: { contact: personContactFromRow(row), confirmed: contactConfirmedFromRow(row) } };
-}
-
-/**
- * The operator's save (#8435 D9): one `updateMany` scoped by the
- * server-resolved workspace, writing only the keys present plus the
- * confirmation stamp (`operator`). No row → `not_found`. Never throws.
- */
-export async function updatePersonContact(
-  workspaceId: string,
-  personId: string,
-  patch: PersonContactPatch,
-): Promise<SaveContactOutcome> {
-  try {
-    const { count } = await prisma.person.updateMany({
-      where: { id: personId, workspaceId },
-      data: {
-        ...patchColumns(patch),
-        contactConfirmedAt: new Date(),
-        contactConfirmedBy: "operator",
-      } as Prisma.PersonUpdateManyMutationInput,
-    });
-    if (count === 0) return { kind: "not_found" };
-    return await readSavedContact(workspaceId, personId);
-  } catch {
-    return { kind: "internal_error" };
-  }
-}
-
-/**
- * The Person a client's first contact save belongs to (#8435 D11): the
- * caller's VERIFIED email's Person in this workspace, found or created, and
- * linked to the caller through `stampPersonUser`'s own rule. Anything but a
- * stamped or already-linked outcome is `unavailable` — nothing is written for
- * the contact. Never throws.
- */
-export async function ensureMemberPerson(
-  workspaceId: string,
-  userId: string,
-): Promise<{ ok: true; personId: string } | { ok: false }> {
-  try {
-    const verified = await findVerifiedEmail(userId);
-    if (!verified.ok) return { ok: false };
-    const person = await findOrCreatePerson(workspaceId, { email: verified.value.email });
-    if (!person.ok) return { ok: false };
-    const outcome = await stampPersonUser(workspaceId, person.value.personId, userId);
-    if (outcome !== "stamped" && outcome !== "already_linked") return { ok: false };
-    return { ok: true, personId: person.value.personId };
-  } catch {
-    return { ok: false };
-  }
-}
-
-/**
- * The client's save (#8435 D11): ONE `updateMany` guarded on `{ id,
- * workspaceId, userId }` — only the caller's own linked Person is ever
- * written — replacing all six contact keys with the body and stamping
- * `client`, so no value the client never saw survives it (SEC-8435-B). No
- * row → `not_found`. Never throws.
- */
-export async function setOwnPersonContact(
-  workspaceId: string,
-  personId: string,
-  userId: string,
-  contact: PersonContactPatch,
-): Promise<SaveContactOutcome> {
-  try {
-    const { count } = await prisma.person.updateMany({
-      where: { id: personId, workspaceId, userId },
-      data: {
-        ...patchColumns(contact),
-        contactConfirmedAt: new Date(),
-        contactConfirmedBy: "client",
-      } as Prisma.PersonUpdateManyMutationInput,
-    });
-    if (count === 0) return { kind: "not_found" };
-    return await readSavedContact(workspaceId, personId);
-  } catch {
-    return { kind: "internal_error" };
-  }
-}