create-ailk 0.14.0 → 0.16.0

package/templates/database/__tests__/person.db.test.ts

@@ -0,0 +1,584 @@
+/**
+ * @file person.db.test.ts
+ *
+ * LIVE-DATABASE proof of the Person record (#852, spec
+ * docs/specs/852-person-the-per-workspace-client-spec.md D1, D2, D4, D7;
+ * AC-1, AC-2's concurrency leg, AC-4's database half and AC-6's fallback
+ * semantics). Requires DATABASE_URL pointing at a Postgres with the
+ * migrations applied — every live suite SKIPS when DATABASE_URL is unset,
+ * keeping the workspace Jest run DB-free (the repo convention; the
+ * `apps/api Route Tests (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `agents.db.test.ts` does. What it proves
+ * that a mock cannot:
+ *   1. The people table's CHECKs and unique indexes (AC-1): a normalized,
+ *      printable-ASCII email unique per workspace; a user unique per
+ *      workspace with NULLs distinct; a NON-unique customer id; the billing
+ *      pair; the id format CHECKs on people, leads.person_id and
+ *      appointments.person_id.
+ *   2. INSERT … ON CONFLICT DO NOTHING absorbs a concurrent duplicate inside
+ *      two open transactions: one row, one id, neither aborts (AC-2).
+ *   3. The backfill (AC-4): the committed fixture, backfilled by the
+ *      migration's own text, yields exactly the expected Persons and stamps;
+ *      the post-cutover script is byte-identical, changes nothing on a
+ *      second run, and stamps a lead written after the first.
+ *   4. The timeline's email fallback (AC-6): the very SQL constants
+ *      `apps/api/src/lib/tenant-db.ts` runs match only pre-cutoff, lead-less
+ *      rows of this workspace by EXACT normalized equality — no wildcard, no
+ *      non-ASCII case fold.
+ *
+ * Two cases need no database and always run: the script and the migration
+ * are byte-identical, and the normalization pairs the fixture lists are what
+ * the fixture claims (their SQL twin runs live below).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+import {
+  PERSON_BACKFILL_MIGRATION,
+  PERSON_CUTOFF_SQL,
+  PERSON_FALLBACK_FLOW_SESSIONS_SQL,
+  PERSON_FALLBACK_PROJECT_LISTINGS_SQL,
+} from "../tenancy";
+
+type Fixture = {
+  workspaces: Record<string, string>;
+  input: {
+    users: Array<{ key: string; email: string; emailVerified: boolean }>;
+    leads: Array<{
+      key: string;
+      workspace: string;
+      email: string;
+      payload: Record<string, unknown>;
+      createdAt: string;
+      promotedUser?: string;
+      promotedAt?: string;
+    }>;
+    flowCheckouts: Array<{
+      key: string;
+      workspace: string;
+      lead: string;
+      status: string;
+      stripeCustomerId: string;
+      completedAt: string | null;
+      createdAt: string;
+    }>;
+    appointments: Array<{
+      key: string;
+      workspace: string;
+      attendeeEmail: string;
+      attendeeName: string;
+      createdAt: string;
+    }>;
+    subscribers: Array<{ workspace: string; email: string }>;
+  };
+  emails: Array<{ raw: string; normalized: string; storable: boolean }>;
+  expected: {
+    people: Array<{
+      workspace: string;
+      email: string;
+      name: string | null;
+      billingCustomerId: string | null;
+      user: string | null;
+    }>;
+    unstamped: string[];
+  };
+};
+
+const fixture = JSON.parse(
+  readFileSync(join(__dirname, "fixtures", "person-backfill.json"), "utf8"),
+) as Fixture;
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const BACKFILL_MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261010121000_person_backfill",
+  "migration.sql",
+);
+const BACKFILL_SCRIPT = join(__dirname, "..", "scripts", "person-backfill.sql");
+const PERSON_MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261010120000_person",
+  "migration.sql",
+);
+
+const N_SQL = `lower(btrim($1::text, E' \\t\\n\\r\\f\\x0B') COLLATE "C")`;
+const ID_TAIL = "[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+const PERSON_ID = new RegExp(`^person_${ID_TAIL}$`);
+
+describe("the Person backfill files (#852 D2)", () => {
+  it("the post-cutover script is byte-identical to the backfill migration", () => {
+    expect(readFileSync(BACKFILL_SCRIPT, "utf8")).toBe(
+      readFileSync(BACKFILL_MIGRATION, "utf8"),
+    );
+  });
+
+  it("the cutoff key names the backfill migration's folder", () => {
+    expect(PERSON_BACKFILL_MIGRATION).toBe("20261010121000_person_backfill");
+    expect(PERSON_CUTOFF_SQL).toContain(`'${PERSON_BACKFILL_MIGRATION}'`);
+  });
+
+  it("the Person model carries no phone, traits, brief, merge pointer or secondary email", () => {
+    const schema = readFileSync(join(__dirname, "..", "inbox", "schema.prisma"), "utf8");
+    const block = /^model Person \{[\s\S]*?^\}/m.exec(schema)?.[0] ?? "";
+    expect(block).not.toBe("");
+    expect(block).not.toMatch(/phone|traits|brief|merge|secondary/);
+    expect(readFileSync(PERSON_MIGRATION, "utf8")).not.toMatch(/"(phone|traits|brief)"/);
+  });
+});
+
+describeDb("the people table (#852 D1/D2, AC-1, live DB)", () => {
+  let db: Client;
+  const WS_1 = "wksp_01920000-0852-7000-8000-0000000000c1";
+  const WS_2 = "wksp_01920000-0852-7000-8000-0000000000c2";
+  const USER = "user_01920000-0852-7000-8000-0000000000c1";
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" IN ($1, $2)`, [WS_1, WS_2]);
+  });
+
+  afterAll(async () => {
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" IN ($1, $2)`, [WS_1, WS_2]);
+    await db.end();
+  });
+
+  type PersonCols = {
+    id?: string;
+    workspace_id?: string;
+    email: string;
+    user_id?: string | null;
+    billing_provider?: string | null;
+    billing_customer_id?: string | null;
+  };
+
+  const insertPerson = (cols: PersonCols) =>
+    db.query<{ id: string }>(
+      `INSERT INTO "people" ("id", "workspace_id", "email", "user_id", "billing_provider", "billing_customer_id", "updated_at")
+       VALUES (COALESCE($1, 'person_' || uuidv7()::text), $2, $3, $4, $5, $6, now()) RETURNING "id"`,
+      [
+        cols.id ?? null,
+        cols.workspace_id ?? WS_1,
+        cols.email,
+        cols.user_id ?? null,
+        cols.billing_provider ?? null,
+        cols.billing_customer_id ?? null,
+      ],
+    );
+
+  it("mints a person_ id and accepts a normalized address", async () => {
+    const { rows } = await insertPerson({ email: "first@example.com" });
+    expect(rows[0]!.id).toMatch(PERSON_ID);
+  });
+
+  it.each([
+    ["a mixed-case email", "Mixed@Example.com"],
+    ["a leading tab", "\ttab@example.com"],
+    ["a zero-width space inside", "zero\u200Bwidth@example.com"],
+    ["a non-ASCII letter", "zoë@example.com"],
+    ["two @", "a@b@example.com"],
+    ["an empty local part", "@example.com"],
+  ])("refuses %s (people_email_normalized)", async (_label, email) => {
+    await expect(insertPerson({ email })).rejects.toMatchObject({
+      code: "23514",
+      constraint: "people_email_normalized",
+    });
+  });
+
+  it("refuses a second Person with the same (workspace_id, email), admits it in another workspace", async () => {
+    await insertPerson({ email: "dup@example.com" });
+    await expect(insertPerson({ email: "dup@example.com" })).rejects.toMatchObject({
+      code: "23505",
+      constraint: "people_workspace_id_email_key",
+    });
+    await expect(insertPerson({ workspace_id: WS_2, email: "dup@example.com" })).resolves.toBeDefined();
+  });
+
+  it("refuses two Persons of one workspace with one user_id; admits any number of NULL user_ids", async () => {
+    await insertPerson({ email: "u1@example.com", user_id: USER });
+    await expect(insertPerson({ email: "u2@example.com", user_id: USER })).rejects.toMatchObject({
+      code: "23505",
+      constraint: "people_workspace_id_user_id_key",
+    });
+    await insertPerson({ email: "null-a@example.com" });
+    await expect(insertPerson({ email: "null-b@example.com" })).resolves.toBeDefined();
+  });
+
+  it("admits one customer id on two Persons (the spokes share one Stripe account)", async () => {
+    await insertPerson({ email: "c1@example.com", billing_provider: "stripe", billing_customer_id: "cus_shared" });
+    await expect(
+      insertPerson({ email: "c2@example.com", billing_provider: "stripe", billing_customer_id: "cus_shared" }),
+    ).resolves.toBeDefined();
+  });
+
+  it("refuses a customer id without a provider (people_billing_pair)", async () => {
+    await expect(
+      insertPerson({ email: "pair@example.com", billing_customer_id: "cus_alone" }),
+    ).rejects.toMatchObject({ code: "23514", constraint: "people_billing_pair" });
+  });
+
+  it.each([
+    ["id", { id: "lead_01920000-0852-7000-8000-0000000000c1", email: "f1@example.com" }, "people_id_format"],
+    ["workspace_id", { workspace_id: "org_01920000-0852-7000-8000-0000000000c1", email: "f2@example.com" }, "people_workspace_id_format"],
+    ["user_id", { user_id: "member_01920000-0852-7000-8000-0000000000c1", email: "f3@example.com" }, "people_user_id_format"],
+  ] as const)("refuses a malformed %s", async (_column, cols, constraint) => {
+    await expect(insertPerson(cols)).rejects.toMatchObject({ code: "23514", constraint });
+  });
+
+  it("leads.person_id and appointments.person_id accept a person_ id and refuse a lead_ one", async () => {
+    const good = "person_01920000-0852-7000-8000-0000000000c9";
+    const bad = "lead_01920000-0852-7000-8000-0000000000c9";
+    await db.query("BEGIN");
+    try {
+      await db.query(
+        `INSERT INTO "leads" ("site_id", "workspace_id", "source", "email", "payload", "person_id")
+         VALUES ($1, $1, 'p852-format', 'x@example.com', '{}', $2)`,
+        [WS_1, good],
+      );
+      await db.query(
+        `INSERT INTO "appointments" ("site_id", "workspace_id", "provider_booking_uid", "start_time", "end_time",
+                                     "attendee_name", "attendee_email", "status", "lifecycle_event_at", "updated_at", "person_id")
+         VALUES ($1::text, $1::text, 'p852-format', now(), now(), 'X', 'x@example.com', 'confirmed', now(), now(), $2)`,
+        [WS_1, good],
+      );
+    } finally {
+      await db.query("ROLLBACK");
+    }
+    await expect(
+      db.query(
+        `INSERT INTO "leads" ("site_id", "workspace_id", "source", "email", "payload", "person_id")
+         VALUES ($1, $1, 'p852-format', 'x@example.com', '{}', $2)`,
+        [WS_1, bad],
+      ),
+    ).rejects.toMatchObject({ code: "23514", constraint: "leads_person_id_format" });
+    await expect(
+      db.query(
+        `INSERT INTO "appointments" ("site_id", "workspace_id", "provider_booking_uid", "start_time", "end_time",
+                                     "attendee_name", "attendee_email", "status", "lifecycle_event_at", "updated_at", "person_id")
+         VALUES ($1::text, $1::text, 'p852-format', now(), now(), 'X', 'x@example.com', 'confirmed', now(), now(), $2)`,
+        [WS_1, bad],
+      ),
+    ).rejects.toMatchObject({ code: "23514", constraint: "appointments_person_id_format" });
+  });
+
+  it("two concurrent transactions inserting one (workspace_id, email) with ON CONFLICT DO NOTHING yield one row and one id, and neither aborts (AC-2)", async () => {
+    const a = new Client({ connectionString: process.env.DATABASE_URL });
+    const b = new Client({ connectionString: process.env.DATABASE_URL });
+    await a.connect();
+    await b.connect();
+    const insert = `INSERT INTO "people" ("workspace_id", "email", "updated_at") VALUES ($1, 'race@example.com', now())
+                    ON CONFLICT ("workspace_id", "email") DO NOTHING`;
+    const reread = `SELECT "id" FROM "people" WHERE "workspace_id" = $1 AND "email" = 'race@example.com'`;
+    try {
+      await a.query("BEGIN");
+      await b.query("BEGIN");
+      const insertedA = await a.query(insert, [WS_1]);
+      // B's insert waits on A's uncommitted row, then does nothing.
+      const pendingB = b.query(insert, [WS_1]);
+      const idA = (await a.query<{ id: string }>(reread, [WS_1])).rows[0]!.id;
+      await a.query("COMMIT");
+      const insertedB = await pendingB;
+      const idB = (await b.query<{ id: string }>(reread, [WS_1])).rows[0]!.id;
+      await b.query("COMMIT");
+
+      expect(insertedA.rowCount).toBe(1);
+      expect(insertedB.rowCount).toBe(0);
+      expect(idB).toBe(idA);
+      const { rows } = await db.query(reread, [WS_1]);
+      expect(rows).toHaveLength(1);
+    } finally {
+      await a.end();
+      await b.end();
+    }
+  });
+});
+
+describeDb("the Person backfill (#852 D4, AC-4, live DB)", () => {
+  let db: Client;
+  const WS = fixture.workspaces;
+  const WORKSPACES = Object.values(WS);
+  const userIds = new Map<string, string>();
+  const leadIds = new Map<string, string>();
+  const appointmentIds = new Map<string, string>();
+  const userEmails = fixture.input.users.map((u) => u.email);
+
+  async function cleanup(): Promise<void> {
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = ANY($1)`, [WORKSPACES]);
+    await db.query(`DELETE FROM "flow_checkouts" WHERE "workspace_id" = ANY($1)`, [WORKSPACES]);
+    await db.query(`DELETE FROM "leads" WHERE "workspace_id" = ANY($1)`, [WORKSPACES]);
+    await db.query(`DELETE FROM "appointments" WHERE "workspace_id" = ANY($1)`, [WORKSPACES]);
+    await db.query(`DELETE FROM "subscribers" WHERE "workspace_id" = ANY($1)`, [WORKSPACES]);
+    await db.query(`DELETE FROM "users" WHERE "email" = ANY($1)`, [userEmails]);
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+
+    for (const u of fixture.input.users) {
+      const { rows } = await db.query<{ id: string }>(
+        `INSERT INTO "users" ("email", "email_verified", "updated_at") VALUES ($1, $2, now()) RETURNING "id"`,
+        [u.email, u.emailVerified],
+      );
+      userIds.set(u.key, rows[0]!.id);
+    }
+    for (const lead of fixture.input.leads) {
+      const { rows } = await db.query<{ id: string }>(
+        `INSERT INTO "leads" ("site_id", "workspace_id", "source", "email", "payload", "created_at", "promoted_user_id", "promoted_at")
+         VALUES ($1, $1, 'p852', $2, $3, $4, $5, $6) RETURNING "id"`,
+        [
+          WS[lead.workspace],
+          lead.email,
+          JSON.stringify(lead.payload),
+          lead.createdAt,
+          lead.promotedUser ? userIds.get(lead.promotedUser) : null,
+          lead.promotedAt ?? null,
+        ],
+      );
+      leadIds.set(lead.key, rows[0]!.id);
+    }
+    for (const c of fixture.input.flowCheckouts) {
+      await db.query(
+        `INSERT INTO "flow_checkouts" ("site_id", "workspace_id", "flow_slug", "experiment_key", "session_id", "lead_id",
+                                       "offer_key", "seats", "period", "credit_stop", "amount_minor", "currency", "quote",
+                                       "permalink", "status", "stripe_customer_id", "completed_at", "created_at", "updated_at")
+         VALUES ($1, $1, 'p852', 'p852', 'p852-session', $2, 'pro', 1, 'month', '{}', 1900, 'usd', '{}',
+                 'p852-permalink', $3, $4, $5, $6, now())`,
+        [WS[c.workspace], leadIds.get(c.lead), c.status, c.stripeCustomerId, c.completedAt, c.createdAt],
+      );
+    }
+    for (const a of fixture.input.appointments) {
+      const { rows } = await db.query<{ id: string }>(
+        `INSERT INTO "appointments" ("site_id", "workspace_id", "provider_booking_uid", "start_time", "end_time",
+                                     "attendee_name", "attendee_email", "status", "lifecycle_event_at", "created_at", "updated_at")
+         VALUES ($1::text, $1::text, $2, $3::timestamp, $3::timestamp, $4, $5, 'confirmed', $3::timestamp, $3::timestamp, now()) RETURNING "id"`,
+        [WS[a.workspace], `p852-${a.key}`, a.createdAt, a.attendeeName, a.attendeeEmail],
+      );
+      appointmentIds.set(a.key, rows[0]!.id);
+    }
+    for (const s of fixture.input.subscribers) {
+      await db.query(
+        `INSERT INTO "subscribers" ("site_id", "workspace_id", "email", "source") VALUES ($1, $1, $2, 'p852')`,
+        [WS[s.workspace], s.email],
+      );
+    }
+
+    await db.query(readFileSync(BACKFILL_MIGRATION, "utf8"));
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  type PersonRow = {
+    id: string;
+    workspace_id: string;
+    email: string;
+    name: string | null;
+    billing_provider: string | null;
+    billing_customer_id: string | null;
+    user_id: string | null;
+  };
+
+  const readPeople = async () =>
+    (
+      await db.query<PersonRow>(
+        `SELECT "id", "workspace_id", "email", "name", "billing_provider", "billing_customer_id", "user_id"
+         FROM "people" WHERE "workspace_id" = ANY($1) ORDER BY "workspace_id", "email"`,
+        [WORKSPACES],
+      )
+    ).rows;
+
+  const snapshot = async () => ({
+    people: (
+      await db.query(
+        `SELECT * FROM "people" WHERE "workspace_id" = ANY($1) ORDER BY "id"`,
+        [WORKSPACES],
+      )
+    ).rows,
+    leads: (
+      await db.query(
+        `SELECT "id", "person_id" FROM "leads" WHERE "workspace_id" = ANY($1) ORDER BY "id"`,
+        [WORKSPACES],
+      )
+    ).rows,
+    appointments: (
+      await db.query(
+        `SELECT * FROM "appointments" WHERE "workspace_id" = ANY($1) ORDER BY "id"`,
+        [WORKSPACES],
+      )
+    ).rows,
+  });
+
+  it("the TypeScript-side normalization pairs match the SQL N(x) and VALID(e) on every fixture email", async () => {
+    for (const e of fixture.emails) {
+      const { rows } = await db.query<{ n: string; valid: boolean }>(
+        `SELECT ${N_SQL} AS n,
+                (${N_SQL} ~ '^[!-?A-~]+@[!-?A-~]+$' AND length(${N_SQL}) <= 254) AS valid`,
+        [e.raw],
+      );
+      expect({ raw: e.raw, n: rows[0]!.n, valid: rows[0]!.valid }).toEqual({
+        raw: e.raw,
+        n: e.normalized,
+        valid: e.storable,
+      });
+    }
+  });
+
+  it("makes exactly the expected Persons (email, name, customer id, user)", async () => {
+    const people = await readPeople();
+    expect(
+      people.map((p) => ({
+        workspace: Object.keys(WS).find((k) => WS[k] === p.workspace_id),
+        email: p.email,
+        name: p.name,
+        billingCustomerId: p.billing_customer_id,
+        user: p.user_id === null ? null : [...userIds].find(([, id]) => id === p.user_id)?.[0],
+      })),
+    ).toEqual(fixture.expected.people);
+    for (const p of people) {
+      expect(p.billing_provider).toBe(p.billing_customer_id === null ? null : "stripe");
+    }
+  });
+
+  it("stamps every lead and appointment with a storable email with its own workspace's Person; the rest stay NULL", async () => {
+    const people = await readPeople();
+    const personOf = (workspace: string, raw: string) =>
+      people.find(
+        (p) => p.workspace_id === WS[workspace] && p.email === fixture.emails.find((e) => e.raw === raw)?.normalized,
+      )?.id ?? null;
+    for (const l of fixture.input.leads) {
+      const { rows } = await db.query<{ person_id: string | null }>(
+        `SELECT "person_id" FROM "leads" WHERE "id" = $1`,
+        [leadIds.get(l.key)],
+      );
+      const expected = fixture.expected.unstamped.includes(l.key) ? null : personOf(l.workspace, l.email);
+      expect({ key: l.key, personId: rows[0]!.person_id }).toEqual({ key: l.key, personId: expected });
+      if (expected === null) expect(fixture.expected.unstamped).toContain(l.key);
+    }
+    for (const a of fixture.input.appointments) {
+      const { rows } = await db.query<{ person_id: string | null }>(
+        `SELECT "person_id" FROM "appointments" WHERE "id" = $1`,
+        [appointmentIds.get(a.key)],
+      );
+      const expected = fixture.expected.unstamped.includes(a.key) ? null : personOf(a.workspace, a.attendeeEmail);
+      expect({ key: a.key, personId: rows[0]!.person_id }).toEqual({ key: a.key, personId: expected });
+    }
+  });
+
+  it("makes no Person from a Subscriber", async () => {
+    const { rows } = await db.query(
+      `SELECT 1 FROM "people" WHERE "email" = $1`,
+      [fixture.input.subscribers[0]!.email],
+    );
+    expect(rows).toHaveLength(0);
+  });
+
+  it("the post-cutover script changes no row on a second run, then stamps a lead written after the first", async () => {
+    const before = await snapshot();
+    await db.query(readFileSync(BACKFILL_SCRIPT, "utf8"));
+    expect(await snapshot()).toEqual(before);
+
+    const { rows } = await db.query<{ id: string }>(
+      `INSERT INTO "leads" ("site_id", "workspace_id", "source", "email", "payload")
+       VALUES ($1, $1, 'p852', ' EVE@x.io', '{}') RETURNING "id"`,
+      [WS["A"]],
+    );
+    await db.query(readFileSync(BACKFILL_SCRIPT, "utf8"));
+    const stamped = await db.query<{ person_id: string | null }>(
+      `SELECT "person_id" FROM "leads" WHERE "id" = $1`,
+      [rows[0]!.id],
+    );
+    const eve = (await readPeople()).find((p) => p.workspace_id === WS["A"] && p.email === "eve@x.io");
+    expect(stamped.rows[0]!.person_id).toBe(eve!.id);
+    expect((await readPeople()).length).toBe(fixture.expected.people.length);
+  });
+});
+
+describeDb("the timeline's pre-migration email fallback (#852 D7, AC-6, live DB)", () => {
+  let db: Client;
+  const WS_1 = "wksp_01920000-0852-7000-8000-0000000000d1";
+  const WS_2 = "wksp_01920000-0852-7000-8000-0000000000d2";
+  const LEAD = "lead_01920000-0852-7000-8000-0000000000d1";
+  const T = new Date("2026-06-01T12:00:00.000Z");
+  const at = (offsetMs: number) => new Date(T.getTime() + offsetMs).toISOString();
+
+  async function cleanup(): Promise<void> {
+    await db.query(`DELETE FROM "flow_sessions" WHERE "workspace_id" IN ($1, $2)`, [WS_1, WS_2]);
+    await db.query(`DELETE FROM "project_listings" WHERE "workspace_id" IN ($1, $2)`, [WS_1, WS_2]);
+  }
+
+  const insertSession = async (workspaceId: string, email: string, createdAt: string, leadId: string | null = null) =>
+    (
+      await db.query<{ id: string }>(
+        `INSERT INTO "flow_sessions" ("site_id", "workspace_id", "flow_id", "flow_slug", "config_snapshot", "email", "lead_id", "created_at", "updated_at")
+         VALUES ($1, $1, 'p852-flow', 'p852', '{}', $2, $3, $4, now()) RETURNING "id"`,
+        [workspaceId, email, leadId, createdAt],
+      )
+    ).rows[0]!.id;
+
+  const insertListing = async (workspaceId: string, email: string, createdAt: string, leadId: string | null = null) =>
+    (
+      await db.query<{ id: string }>(
+        `INSERT INTO "project_listings" ("site_id", "workspace_id", "founder_name", "founder_email", "status", "lead_id", "created_at", "updated_at")
+         VALUES ($1, $1, 'Founder', $2, 'pending', $3, $4, now()) RETURNING "id"`,
+        [workspaceId, email, leadId, createdAt],
+      )
+    ).rows[0]!.id;
+
+  const fallback = async (sql: string, email: string, workspaceId: string) =>
+    (await db.query<{ id: string }>(sql, [email, workspaceId, T])).rows.map((r) => r.id);
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  it.each([
+    ["flow_sessions", PERSON_FALLBACK_FLOW_SESSIONS_SQL, insertSession],
+    ["project_listings", PERSON_FALLBACK_PROJECT_LISTINGS_SQL, insertListing],
+  ] as const)("%s: only a lead-less, pre-cutoff row of this workspace with the exact normalized address", async (_t, sql, insert) => {
+    const person = `ada-${_t}@x.io`;
+    const before = await insert(WS_1, ` ADA-${_t.toUpperCase()}@X.IO\t`, at(-1000));
+    await insert(WS_1, person, at(0)); // exactly T
+    await insert(WS_1, person, at(1000)); // after T
+    await insert(WS_1, person, at(-2000), LEAD); // has a lead
+    await insert(WS_2, person, at(-1000)); // another workspace
+    expect(await fallback(sql, person, WS_1)).toEqual([before]);
+
+    // No wildcard: `_` is a literal character.
+    await insert(WS_1, `john-${_t}@x.io`, at(-1000));
+    expect(await fallback(sql, `j_hn-${_t}@x.io`, WS_1)).toEqual([]);
+
+    // No non-ASCII case fold: a KELVIN SIGN (U+212A) is not `k`.
+    await insert(WS_1, `Kate-${_t}@x.io`, at(-1000));
+    expect(await fallback(sql, `kate-${_t}@x.io`, WS_1)).toEqual([]);
+  });
+
+  it("PERSON_CUTOFF_SQL returns the backfill migration's finished_at", async () => {
+    const { rows } = await db.query<{ finished_at: Date }>(PERSON_CUTOFF_SQL);
+    const direct = await db.query<{ finished_at: Date }>(
+      `SELECT "finished_at" FROM "_prisma_migrations" WHERE "migration_name" = $1`,
+      [PERSON_BACKFILL_MIGRATION],
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.finished_at).toBeInstanceOf(Date);
+    expect(rows[0]!.finished_at.getTime()).toBe(direct.rows[0]!.finished_at.getTime());
+  });
+});

package/templates/database/auth/schema.prisma

@@ -106,6 +106,9 @@ model Workspace {
   spokes       Spoke[]
   // #3591 — the agents bound to this workspace.
   agents       Agent[]
+  // #7803 — the people who last activated this workspace (User.lastWorkspaceId).
+  // Read and written only by apps/api/src/services/tenant-context.ts.
+  lastActiveUsers User[] @relation("UserLastWorkspace")
 
   @@unique([organizationId, slug])
   @@index([organizationId])
@@ -167,6 +170,17 @@ enum AgentPermissionLevel {
 /// deleting the creator does not delete the agents they made for others.
 /// `apps/api/src/lib/agent-store.ts` is the only file that names
 /// `prisma.agent`.
+///
+/// `grants` (#7864, spec docs/specs/7864-agent-key-grants-spec.md D2, D3)
+/// lists the permissions an owner or admin granted this agent one by one —
+/// only the seven `@working-theory/validation` names in
+/// `AGENT_GRANTABLE_PERMISSIONS` (content-edit, content-publish, assets-write,
+/// magnets-manage, meeting-types-manage, people-read since #852,
+/// member-pieces-manage since #7878), held to that set by the
+/// `agents_grants_allowed` CHECK. A grant never raises the ceiling above. The
+/// agent holds a stored grant only while its person's own role holds it too:
+/// the tenant guards clamp it on every request, so a demoted person's agent
+/// keeps the row but loses the permission.
 model Agent {
   id                      String               @id @default(dbgenerated("('agent_'::text || (uuidv7())::text)")) @db.Text
   organizationId          String               @map("organization_id")
@@ -174,6 +188,7 @@ model Agent {
   responsibleMembershipId String               @map("responsible_membership_id")
   name                    String               @db.VarChar(80)
   permissionLevel         AgentPermissionLevel @default(member) @map("permission_level")
+  grants                  String[]             @default([]) @map("grants")
   enabled                 Boolean              @default(true)
   credentialHash          String               @unique @map("credential_hash") @db.Char(64)
   credentialPrefix        String               @map("credential_prefix") @db.VarChar(24)
@@ -374,7 +389,16 @@ model User {
   memberships     Membership[]
   sentInvitations Invitation[] @relation("sent_invitations")
 
+  // #7803 — the workspace this person last activated, so a new sign-in lands
+  // there. Written only by activateWorkspace after its membership grant; read
+  // only by listTenancy, which reports it only when the workspace is in the
+  // caller's own listing (apps/api/src/services/tenant-context.ts). Deleting
+  // the workspace clears it. Never a Better Auth field, so no client can set it.
+  lastWorkspaceId String?    @map("last_workspace_id")
+  lastWorkspace   Workspace? @relation("UserLastWorkspace", fields: [lastWorkspaceId], references: [id], onDelete: SetNull)
+
   @@unique([billingProvider, billingCustomerId])
+  @@index([lastWorkspaceId])
   @@map("users")
 }
 

package/templates/database/config/schema.prisma

@@ -136,6 +136,19 @@ model WorkspaceMeetings {
   @@map("workspace_meetings")
 }
 
+/// WorkspacePieceStages — a workspace's declared piece stages, in order
+/// (#7877). One row per workspace, the WorkspaceMeetings shape; no row means
+/// the product default (apps/api, tenant-db.ts DEFAULT_PIECE_STAGES).
+model WorkspacePieceStages {
+  id          String   @id @default(dbgenerated("('pstages_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String   @unique @map("workspace_id")
+  stages      String[]
+  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  @@map("workspace_piece_stages")
+}
+
 /// SchedulingConnection — a workspace's own scheduling provider account
 /// (#7533 D1): the provider id, its credential and the per-connection webhook
 /// entry point + secret, so each workspace reads and receives bookings through