create-ailk 0.15.0 → 0.17.0

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

@@ -0,0 +1,553 @@
+/**
+ * @file person.test.ts
+ * @description `findOrCreatePerson`, `stampPersonUser` and
+ * `recordCheckoutPerson` (#852, spec
+ * docs/specs/852-person-the-per-workspace-client-spec.md D3, D5, D6;
+ * AC-2, AC-4's API half, AC-5), and the member area's two additions,
+ * `resolveMemberPersonId` and `setPersonPlanOffering` (#7877 D8; AC-3, AC-5),
+ * and the hub's buyer read, `resolveCallerBillingCustomerId`, with the
+ * stamped-Person guard on the customer-id write (#7961, spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D13, SEC-7894-6; AC-8).
+ *
+ * Runs over `createInMemoryPrisma()`, whose `person` delegate enforces the
+ * declared `(workspaceId, email)` and `(workspaceId, userId)` keys the way
+ * Postgres does: `createMany({ skipDuplicates })` skips a conflict, and an
+ * `updateMany` that would put one user on two Persons of a workspace throws
+ * `P2002`. The database half of each claim — the CHECKs, the real ON
+ * CONFLICT race, the backfill SQL — is `database/__tests__/person.db.test.ts`.
+ *
+ * External dependency boundary mocked:
+ *   - apps/api/src/lib/prisma — the in-memory, where-clause-honouring double.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); the in-memory double is the repo-standard where-honouring test double for it.
+jest.mock("../../lib/prisma.js", () =>
+  jest
+    .requireActual<typeof import("../../__tests__/factories/in-memory-prisma")>(
+      "../../__tests__/factories/in-memory-prisma",
+    )
+    .createInMemoryPrisma(),
+);
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { prisma } from "../../lib/prisma.js";
+import {
+  findOrCreatePerson,
+  isStorablePersonEmail,
+  normalizePersonEmail,
+  recordCheckoutPerson,
+  resolveCallerBillingCustomerId,
+  resolveMemberPersonId,
+  setPersonPlanOffering,
+  stampPersonUser,
+} from "../person";
+
+type Row = Record<string, unknown>;
+// The in-memory double's own surface (`__db`, `__calls`) is not on the
+// PrismaClient type the import carries, so it is named here once.
+// eslint-disable-next-line no-restricted-syntax -- justified above
+const store = prisma as unknown as {
+  __db: Record<string, Row[]>;
+  __calls: Array<{ model: string; op: string }>;
+  person: Record<string, jest.Mock>;
+};
+
+const WS_A1 = "wksp_00000000-0000-7000-8000-0000000000a1";
+const WS_A2 = "wksp_00000000-0000-7000-8000-0000000000a2";
+
+/** A 255-character address — one past the 254 bound. */
+const LONG_255 = `${"a".repeat(244)}@example.io`;
+
+const people = () => (store.__db["person"] ??= []);
+const personCalls = () => store.__calls.filter((c) => c.model === "person");
+
+function reset(): void {
+  for (const key of Object.keys(store.__db)) delete store.__db[key];
+  store.__calls.length = 0;
+}
+
+function seedPerson(row: Row): Row {
+  const full: Row = {
+    id: `person_00000000-0000-7000-8000-${String(people().length + 900).padStart(12, "0")}`,
+    workspaceId: WS_A1,
+    name: null,
+    userId: null,
+    billingProvider: null,
+    billingCustomerId: null,
+    planOffering: null,
+    createdAt: new Date(Date.UTC(2026, 0, 1 + people().length)),
+    updatedAt: new Date(),
+    ...row,
+  };
+  people().push(full);
+  return full;
+}
+
+beforeEach(() => {
+  reset();
+  jest.restoreAllMocks();
+});
+
+describe("findOrCreatePerson (#852 D3, AC-2)", () => {
+  it("normalizes the email: a padded, mixed-case address and its plain form are one Person per workspace", async () => {
+    const first = await findOrCreatePerson(WS_A1, { email: " Ada@Example.COM\t" });
+    const second = await findOrCreatePerson(WS_A1, { email: "ada@example.com" });
+    expect(first).toEqual({ ok: true, value: expect.objectContaining({ created: true }) });
+    expect(second.ok && second.value).toEqual(
+      expect.objectContaining({ created: false, personId: first.ok && first.value.personId }),
+    );
+    expect(people()).toHaveLength(1);
+    expect(people()[0]!["email"]).toBe("ada@example.com");
+
+    const other = await findOrCreatePerson(WS_A2, { email: "ada@example.com" });
+    expect(other.ok && other.value.created).toBe(true);
+    expect(people()).toHaveLength(2);
+  });
+
+  it("a customer-id match returns that Person, creates nothing and never rewrites its email", async () => {
+    const p = seedPerson({ email: "a@x.io", billingProvider: "stripe", billingCustomerId: "cus_1" });
+    const result = await findOrCreatePerson(WS_A1, { email: "b@x.io", billingCustomerId: "cus_1" });
+    expect(result).toEqual({
+      ok: true,
+      value: { personId: p["id"], created: false, billing: "unchanged" },
+    });
+    expect(people()).toHaveLength(1);
+    expect(people()[0]!["email"]).toBe("a@x.io");
+    expect(personCalls().map((c) => c.op)).toEqual(["findFirst"]);
+  });
+
+  it("an email match writes the customer id only when the Person has none; the first writer is kept", async () => {
+    seedPerson({ email: "c@x.io" });
+    const written = await findOrCreatePerson(WS_A1, { email: "c@x.io", billingCustomerId: "cus_2" });
+    expect(written.ok && written.value.billing).toBe("written");
+    const kept = await findOrCreatePerson(WS_A1, { email: "c@x.io", billingCustomerId: "cus_3" });
+    expect(kept.ok && kept.value.billing).toBe("kept");
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ billingProvider: "stripe", billingCustomerId: "cus_2" }),
+    );
+  });
+
+  it("an email match never writes a customer id onto a Person already linked to a user (SEC-7894-6)", async () => {
+    seedPerson({ email: "d@x.io", userId: "user_00000000-0000-7000-8000-000000000021" });
+    const result = await findOrCreatePerson(WS_A1, { email: "D@x.io", billingCustomerId: "cus_payer" });
+    expect(result.ok && result.value).toEqual(expect.objectContaining({ created: false, billing: "kept" }));
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ billingProvider: null, billingCustomerId: null }),
+    );
+    expect(personCalls().filter((c) => c.op === "updateMany")).toHaveLength(0);
+  });
+
+  it("a Person linked between the match and the write keeps no customer id (the write is guarded on userId)", async () => {
+    seedPerson({ email: "e@x.io", userId: "user_00000000-0000-7000-8000-000000000022" });
+    // Step 2's customer-id read finds nothing; the email match read saw the
+    // Person before the stamp landed.
+    store.person["findFirst"]!.mockResolvedValueOnce(null).mockResolvedValueOnce({
+      id: people()[0]!["id"],
+      name: null,
+      userId: null,
+      billingCustomerId: null,
+    });
+    const result = await findOrCreatePerson(WS_A1, { email: "e@x.io", billingCustomerId: "cus_payer" });
+    expect(result.ok && result.value.billing).toBe("kept");
+    expect(people()[0]!["billingCustomerId"]).toBeNull();
+  });
+
+  it("a new Person given a customer id is created with it", async () => {
+    const result = await findOrCreatePerson(WS_A1, { email: "new@x.io", billingCustomerId: "cus_9" });
+    expect(result.ok && result.value).toEqual(expect.objectContaining({ created: true, billing: "written" }));
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ billingProvider: "stripe", billingCustomerId: "cus_9" }),
+    );
+  });
+
+  it("an email match gains a name only when it has none", async () => {
+    seedPerson({ email: "named@x.io", name: "First" });
+    seedPerson({ email: "nameless@x.io" });
+    await findOrCreatePerson(WS_A1, { email: "named@x.io", name: "Second" });
+    await findOrCreatePerson(WS_A1, { email: "nameless@x.io", name: "Given" });
+    expect(people().map((p) => p["name"])).toEqual(["First", "Given"]);
+  });
+
+  it.each([
+    ["not-an-email"],
+    [""],
+    ["a@b@c.io"],
+    ["zoë@x.io"],
+    ["zero\u200Bwidth@x.io"],
+    [LONG_255],
+  ])("refuses %p as invalid_email with zero person delegate calls", async (email) => {
+    const result = await findOrCreatePerson(WS_A1, { email });
+    expect(result).toEqual({ ok: false, error: { kind: "invalid_email" } });
+    expect(personCalls()).toEqual([]);
+  });
+
+  it("the long case is exactly 255 characters", () => {
+    expect(LONG_255).toHaveLength(255);
+  });
+
+  it("strips control and bidi characters from a name, trims it and cuts it to 200 code points", async () => {
+    await findOrCreatePerson(WS_A1, {
+      email: "n@x.io",
+      name: `  Ad\u202Ea\u0007 ${"😀".repeat(250)}`,
+    });
+    const name = people()[0]!["name"] as string;
+    expect(name.startsWith("Ada ")).toBe(true);
+    const codePoints = Array.from(name, (c) => c.codePointAt(0)!);
+    expect(codePoints.filter((cp) => cp < 0x20 || cp === 0x202e)).toEqual([]);
+    expect(Array.from(name)).toHaveLength(200);
+  });
+
+  it("an empty-after-cleaning name is stored as null", async () => {
+    await findOrCreatePerson(WS_A1, { email: "blank@x.io", name: " \u200E\u0001 " });
+    expect(people()[0]!["name"]).toBeNull();
+  });
+
+  it("a createMany that loses a concurrent race (count 0) answers the re-read's Person with created: false", async () => {
+    store.person["createMany"]!.mockImplementationOnce(async () => {
+      seedPerson({ email: "race@x.io" });
+      return { count: 0 };
+    });
+    const result = await findOrCreatePerson(WS_A1, { email: "race@x.io" });
+    expect(result).toEqual({
+      ok: true,
+      value: { personId: people()[0]!["id"], created: false, billing: "unchanged" },
+    });
+    expect(people()).toHaveLength(1);
+  });
+
+  it("uses createMany with skipDuplicates (ON CONFLICT DO NOTHING), never a caught P2002", async () => {
+    await findOrCreatePerson(WS_A1, { email: "skip@x.io" });
+    expect(store.person["createMany"]).toHaveBeenCalledWith(
+      expect.objectContaining({ skipDuplicates: true }),
+    );
+  });
+
+  it("a delegate that throws answers internal_error with no message", async () => {
+    store.person["findFirst"]!.mockRejectedValueOnce(new Error("relation people does not exist: secret detail"));
+    const result = await findOrCreatePerson(WS_A1, { email: "boom@x.io" });
+    expect(result).toEqual({ ok: false, error: { kind: "internal_error" } });
+    expect(JSON.stringify(result)).not.toContain("secret");
+  });
+
+  it("runs on the client it is handed (the appointment path's transaction)", async () => {
+    const tx = { person: { ...store.person } };
+    const spy = jest.fn(store.person["findFirst"]!);
+    tx.person["findFirst"] = spy;
+    await findOrCreatePerson(WS_A1, { email: "tx@x.io" }, tx as never);
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it("never reads a User: a Person is created with no verified email at all", async () => {
+    await findOrCreatePerson(WS_A1, { email: "nouser@x.io" });
+    expect(store.__calls.filter((c) => c.model === "user")).toEqual([]);
+    expect(people()[0]!["userId"] ?? null).toBeNull();
+  });
+
+  it("imports none of the paid closure or tenant-db", () => {
+    const source = readFileSync(join(__dirname, "..", "person.ts"), "utf8");
+    expect(source).not.toMatch(
+      /from ['"](\.\/lead-promotion|\.\/owner-workspaces|\.\/lead-accept-user|\.\.\/lib\/tenant-db)/,
+    );
+  });
+});
+
+describe("the backfill fixture, API half (#852 AC-4)", () => {
+  type Fixture = {
+    workspaces: Record<string, string>;
+    input: {
+      leads: Array<{ key: string; workspace: string; email: string }>;
+      flowCheckouts: Array<{ workspace: string; lead: string }>;
+      appointments: Array<{ workspace: string; attendeeEmail: string }>;
+    };
+    emails: Array<{ raw: string; normalized: string; storable: boolean }>;
+    expected: {
+      people: Array<{ workspace: string; email: string; name: string | null; billingCustomerId: string | null }>;
+    };
+  };
+  const fixture = JSON.parse(
+    readFileSync(
+      join(__dirname, "..", "..", "..", "..", "..", "database", "__tests__", "fixtures", "person-backfill.json"),
+      "utf8",
+    ),
+  ) as Fixture;
+
+  it("normalizePersonEmail and isStorablePersonEmail agree with every pair the fixture lists (the SQL half is person.db.test.ts)", () => {
+    expect(fixture.emails.map((e) => e.raw)).toEqual(
+      expect.arrayContaining(["vic@x.dev", "\u000Bdana@x.io\u000B", " Eve@X.IO\t"]),
+    );
+    for (const e of fixture.emails) {
+      const n = normalizePersonEmail(e.raw);
+      expect({ raw: e.raw, n, storable: isStorablePersonEmail(n) }).toEqual({
+        raw: e.raw,
+        n: e.normalized,
+        storable: e.storable,
+      });
+    }
+  });
+
+  it("findOrCreatePerson on every raw input email over the backfilled Persons creates zero rows", async () => {
+    for (const p of fixture.expected.people) {
+      seedPerson({
+        workspaceId: fixture.workspaces[p.workspace],
+        email: p.email,
+        name: p.name,
+        billingProvider: p.billingCustomerId === null ? null : "stripe",
+        billingCustomerId: p.billingCustomerId,
+      });
+    }
+    const before = people().length;
+    const leadsByKey = new Map(fixture.input.leads.map((l) => [l.key, l]));
+    const calls: Array<[string, string]> = [
+      ...fixture.input.leads.map((l): [string, string] => [l.workspace, l.email]),
+      ...fixture.input.flowCheckouts.map((c): [string, string] => [c.workspace, leadsByKey.get(c.lead)!.email]),
+      ...fixture.input.appointments.map((a): [string, string] => [a.workspace, a.attendeeEmail]),
+    ];
+    const created: string[] = [];
+    for (const [workspace, email] of calls) {
+      const result = await findOrCreatePerson(fixture.workspaces[workspace]!, { email });
+      if (result.ok && result.value.created) created.push(email);
+    }
+    expect(created).toEqual([]);
+    expect(people()).toHaveLength(before);
+  });
+});
+
+describe("stampPersonUser (#852 D5, AC-5)", () => {
+  const users = () => (store.__db["user"] ??= []);
+  const seedUser = (id: string, email: string, emailVerified: boolean) =>
+    users().push({ id, email, emailVerified });
+  const U = "user_00000000-0000-7000-8000-000000000001";
+  const V = "user_00000000-0000-7000-8000-000000000002";
+
+  it("a verified user whose email normalizes to the Person's is stamped; a second call is already_linked", async () => {
+    const p = seedPerson({ email: "ada@example.com" });
+    seedUser(U, " ADA@example.com", true);
+    expect(await stampPersonUser(WS_A1, p["id"] as string, U)).toBe("stamped");
+    expect(people()[0]!["userId"]).toBe(U);
+    expect(await stampPersonUser(WS_A1, p["id"] as string, U)).toBe("already_linked");
+  });
+
+  it("an unverified user, and a verified user with another email, write nothing", async () => {
+    const p = seedPerson({ email: "ada@example.com" });
+    seedUser(U, "ada@example.com", false);
+    seedUser(V, "someone@example.com", true);
+    expect(await stampPersonUser(WS_A1, p["id"] as string, U)).toBe("user_unverified");
+    expect(await stampPersonUser(WS_A1, p["id"] as string, V)).toBe("email_mismatch");
+    expect(people()[0]!["userId"]).toBeNull();
+  });
+
+  it("a Person already linked to U, stamped with V, stays U", async () => {
+    const p = seedPerson({ email: "ada@example.com", userId: U });
+    seedUser(V, "ada@example.com", true);
+    expect(await stampPersonUser(WS_A1, p["id"] as string, V)).toBe("linked_to_other_user");
+    expect(people()[0]!["userId"]).toBe(U);
+  });
+
+  it("U already on P1 cannot be stamped onto P2 of the same workspace (P2002) — P2 unchanged", async () => {
+    seedPerson({ email: "first@example.com", userId: U });
+    const p2 = seedPerson({ email: "ada@example.com" });
+    seedUser(U, "ada@example.com", true);
+    expect(await stampPersonUser(WS_A1, p2["id"] as string, U)).toBe("user_on_other_person");
+    expect(people()[1]!["userId"]).toBeNull();
+  });
+
+  it("a Person of another workspace is not_found", async () => {
+    const p = seedPerson({ workspaceId: WS_A2, email: "ada@example.com" });
+    seedUser(U, "ada@example.com", true);
+    expect(await stampPersonUser(WS_A1, p["id"] as string, U)).toBe("not_found");
+    expect(people()[0]!["userId"]).toBeNull();
+  });
+
+  it("a store error is internal_error", async () => {
+    store.person["findFirst"]!.mockRejectedValueOnce(new Error("down"));
+    expect(await stampPersonUser(WS_A1, "person_x", U)).toBe("internal_error");
+  });
+});
+
+describe("recordCheckoutPerson (#852 D6)", () => {
+  const SESSION = "cs_live_852";
+  const CHECKOUT = "flchk_00000000-0000-7000-8000-000000000001";
+  const LEAD = "lead_00000000-0000-7000-8000-000000000001";
+
+  function seedCheckout(overrides: Row = {}): void {
+    (store.__db["flowCheckout"] ??= []).push({
+      id: CHECKOUT,
+      leadId: LEAD,
+      workspaceId: WS_A1,
+      stripeSessionId: SESSION,
+      status: "completed",
+      ...overrides,
+    });
+    (store.__db["lead"] ??= []).push({ id: LEAD, workspaceId: WS_A1, email: " Buyer@X.io" });
+  }
+
+  it("live mode: the Person of the checkout's lead, with session.customer", async () => {
+    seedCheckout();
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: SESSION, customer: "cus_9", livemode: true }),
+    ).toBe("person_written");
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ workspaceId: WS_A1, email: "buyer@x.io", billingCustomerId: "cus_9" }),
+    );
+  });
+
+  it("live mode onto a Person already linked to a user: the checkout completes and the Person keeps no customer id", async () => {
+    seedCheckout();
+    seedPerson({ email: "buyer@x.io", userId: "user_00000000-0000-7000-8000-000000000023" });
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: SESSION, customer: "cus_9", livemode: true }),
+    ).toBe("person_kept");
+    expect(people()).toHaveLength(1);
+    expect(people()[0]!["billingCustomerId"]).toBeNull();
+  });
+
+  it("test mode: the Person, with no customer id", async () => {
+    seedCheckout();
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: SESSION, customer: "cus_9", livemode: false }),
+    ).toBe("person_unchanged");
+    expect(people()[0]!["billingCustomerId"] ?? null).toBeNull();
+  });
+
+  it("a session naming a checkout another session completed matches nothing", async () => {
+    seedCheckout({ stripeSessionId: "cs_other" });
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: SESSION, customer: "cus_9", livemode: true }),
+    ).toBe("person_skipped");
+    expect(people()).toEqual([]);
+  });
+
+  it("a checkout not yet completed matches nothing", async () => {
+    seedCheckout({ status: "created" });
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: SESSION, customer: "cus_9", livemode: true }),
+    ).toBe("person_skipped");
+  });
+
+  it("a missing session id is skipped before any read; a store error is person_failed", async () => {
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: undefined, customer: null, livemode: true }),
+    ).toBe("person_skipped");
+    expect(store.__calls).toEqual([]);
+    seedCheckout();
+    store.person["findFirst"]!.mockRejectedValueOnce(new Error("down"));
+    expect(
+      await recordCheckoutPerson({ flowCheckoutId: CHECKOUT, stripeSessionId: SESSION, customer: "cus_9", livemode: true }),
+    ).toBe("person_failed");
+  });
+});
+
+describe("resolveMemberPersonId (#7877 D8, AC-3)", () => {
+  const users = () => (store.__db["user"] ??= []);
+  const U = "user_00000000-0000-7000-8000-000000000011";
+  const V = "user_00000000-0000-7000-8000-000000000012";
+  const log = { warn: jest.fn() };
+
+  beforeEach(() => log.warn.mockClear());
+
+  it("answers the Person already linked to the caller, with no stamp", async () => {
+    const p = seedPerson({ email: "cleo@x.io", userId: U });
+    expect(await resolveMemberPersonId(WS_A1, U, "cleo@x.io", log)).toBe(p["id"]);
+    expect(personCalls().filter((c) => c.op === "updateMany")).toHaveLength(0);
+  });
+
+  it("stamps an unlinked Person whose email is the caller's verified email (case and padding differ)", async () => {
+    const p = seedPerson({ email: "cleo@x.io" });
+    users().push({ id: U, email: "  CLEO@x.io ", emailVerified: true });
+    expect(await resolveMemberPersonId(WS_A1, U, "  CLEO@x.io ", log)).toBe(p["id"]);
+    expect(people()[0]!["userId"]).toBe(U);
+  });
+
+  it("a Person linked to another user is not stamped and not served; the refusal is logged by kind", async () => {
+    seedPerson({ email: "cleo@x.io", userId: V });
+    users().push({ id: U, email: "cleo@x.io", emailVerified: true });
+    expect(await resolveMemberPersonId(WS_A1, U, "cleo@x.io", log)).toBeNull();
+    expect(people()[0]!["userId"]).toBe(V);
+    expect(log.warn).toHaveBeenCalledWith(
+      { event: "member-person-stamp", outcome: "linked_to_other_user" },
+      expect.any(String),
+    );
+    expect(JSON.stringify(log.warn.mock.calls)).not.toContain("cleo@x.io");
+  });
+
+  it("no Person in this workspace is null — another workspace's Person is never answered", async () => {
+    seedPerson({ workspaceId: WS_A2, email: "cleo@x.io", userId: U });
+    expect(await resolveMemberPersonId(WS_A1, U, "cleo@x.io", log)).toBeNull();
+  });
+});
+
+describe("resolveCallerBillingCustomerId (#7961, spec 7894 D13, AC-8)", () => {
+  const users = () => (store.__db["user"] ??= []);
+  const U = "user_00000000-0000-7000-8000-000000000031";
+  const V = "user_00000000-0000-7000-8000-000000000032";
+  const log = { warn: jest.fn() };
+
+  beforeEach(() => log.warn.mockClear());
+
+  it("answers the customer id of the Person linked to the caller", async () => {
+    seedPerson({ email: "fay@x.io", userId: U, billingProvider: "stripe", billingCustomerId: "cus_fay" });
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBe("cus_fay");
+  });
+
+  it("links an unlinked Person whose email is the caller's verified email, then answers its id", async () => {
+    seedPerson({ email: "fay@x.io", billingProvider: "stripe", billingCustomerId: "cus_fay" });
+    users().push({ id: U, email: "Fay@x.io", emailVerified: true });
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "Fay@x.io", log)).toBe("cus_fay");
+    expect(people()[0]!["userId"]).toBe(U);
+  });
+
+  it("a Person matched by email alone is never answered: an unverified caller, and a Person linked to another user, are null", async () => {
+    seedPerson({ email: "fay@x.io", billingProvider: "stripe", billingCustomerId: "cus_fay" });
+    users().push({ id: U, email: "fay@x.io", emailVerified: false });
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBeNull();
+    expect(people()[0]!["userId"]).toBeNull();
+
+    reset();
+    seedPerson({ email: "fay@x.io", userId: V, billingProvider: "stripe", billingCustomerId: "cus_fay" });
+    users().push({ id: U, email: "fay@x.io", emailVerified: true });
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBeNull();
+  });
+
+  it("a linked Person with no customer id, no Person, and another workspace's Person are all null", async () => {
+    seedPerson({ email: "fay@x.io", userId: U });
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBeNull();
+
+    reset();
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBeNull();
+
+    seedPerson({ workspaceId: WS_A2, email: "fay@x.io", userId: U, billingCustomerId: "cus_fay" });
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBeNull();
+  });
+
+  it("a store error is null, never a throw, and logs no id or email", async () => {
+    seedPerson({ email: "fay@x.io", userId: U, billingCustomerId: "cus_fay" });
+    store.person["findFirst"]!
+      .mockResolvedValueOnce({ id: people()[0]!["id"] })
+      .mockRejectedValueOnce(new Error("down"));
+    expect(await resolveCallerBillingCustomerId(WS_A1, U, "fay@x.io", log)).toBeNull();
+    expect(JSON.stringify(log.warn.mock.calls)).not.toMatch(/cus_fay|fay@x\.io|user_/);
+  });
+});
+
+describe("setPersonPlanOffering (#7877 D8, AC-4, AC-5)", () => {
+  it("sets and clears the plan, scoped to the workspace", async () => {
+    const p = seedPerson({ email: "cleo@x.io" });
+    expect(await setPersonPlanOffering(WS_A1, p["id"] as string, "retainer")).toBe("set");
+    expect(people()[0]!["planOffering"]).toBe("retainer");
+    expect(await setPersonPlanOffering(WS_A1, p["id"] as string, null)).toBe("set");
+    expect(people()[0]!["planOffering"]).toBeNull();
+  });
+
+  it("another workspace's Person is not_found and unchanged", async () => {
+    const p = seedPerson({ workspaceId: WS_A2, email: "cleo@x.io" });
+    expect(await setPersonPlanOffering(WS_A1, p["id"] as string, "retainer")).toBe("not_found");
+    expect(people()[0]!["planOffering"]).toBeNull();
+  });
+
+  it("a store error is internal_error, never a throw", async () => {
+    store.person["updateMany"]!.mockRejectedValueOnce(new Error("down"));
+    expect(await setPersonPlanOffering(WS_A1, "person_x", "retainer")).toBe("internal_error");
+  });
+});