create-ailk 0.18.0 → 0.19.1

package/templates/apps/api/src/services/__tests__/lead-routing.test.ts

@@ -1014,12 +1014,121 @@ describe("#852 — the lead's Person (AC-3)", () => {
     expect(createData()).toEqual(expect.objectContaining({ personId: MOCK_PERSON_ID }));
   });
 
-  it("subscribe and callback make no person call", async () => {
+  // ── #8435 D5 (AC-3) — subscribers and callbacks link to their Person ─────
+  const LINKED = {
+    ok: true as const,
+    value: { personId: MOCK_PERSON_ID as never, created: false, billing: "unchanged" as const },
+  };
+  const findSpies: jest.SpyInstance[] = [];
+  const spyFind = () => {
+    const spy = jest.spyOn(personService, "findOrCreatePerson");
+    findSpies.push(spy);
+    return spy;
+  };
+  afterEach(() => {
+    while (findSpies.length > 0) findSpies.pop()?.mockRestore();
+  });
+  const subscriberData = () =>
+    jest.mocked(prisma.subscriber.create).mock.calls[0]?.[0].data as Record<string, unknown>;
+  const callbackData = () =>
+    jest.mocked(prisma.callback.create).mock.calls[0]?.[0].data as Record<string, unknown>;
+
+  it("a subscribe calls findOrCreatePerson(siteId, { email }) once and writes that personId", async () => {
     (prisma.subscriber.create as jest.Mock).mockResolvedValue({ id: "subscr_x" });
-    (prisma.callback.create as jest.Mock).mockResolvedValue({ id: "callbk_x" });
+    const find = spyFind().mockResolvedValue(LINKED);
     await routeLead(subscribeInput, sourceMeta);
-    await routeLead(callbackInput, sourceMeta);
+    expect(find).toHaveBeenCalledTimes(1);
+    expect(find).toHaveBeenCalledWith("site-abc", { email: "subscriber@example.com" });
+    expect(subscriberData()).toEqual(expect.objectContaining({ personId: MOCK_PERSON_ID }));
+  });
+
+  it("a subscribe whose Person is invalid_email writes personId: null and one person-skipped warn with no email", async () => {
+    (prisma.subscriber.create as jest.Mock).mockResolvedValue({ id: "subscr_x" });
+    jest
+      .spyOn(personService, "findOrCreatePerson")
+      .mockResolvedValueOnce({ ok: false, error: { kind: "invalid_email" } });
+    const result = await routeLead(subscribeInput, sourceMeta);
+    expect(result).toMatchObject({ ok: true, id: "subscr_x", persisted: "db" });
+    expect(subscriberData()).toEqual(expect.objectContaining({ personId: null }));
+    const skipped = warn.mock.calls.filter(([fields]) => (fields as { event?: string }).event === "person-skipped");
+    expect(skipped).toHaveLength(1);
+    expect(JSON.stringify(warn.mock.calls)).not.toContain("example.com");
+  });
+
+  it("a subscribe whose Person step fails (internal_error or a throw) answers exactly like a linked one", async () => {
+    (prisma.subscriber.create as jest.Mock).mockResolvedValue({ id: "subscr_x" });
+    const find = spyFind().mockResolvedValue(LINKED);
+    const linked = await routeLead(subscribeInput, sourceMeta);
+    jest.mocked(prisma.subscriber.create).mockClear();
+
+    find.mockResolvedValueOnce({ ok: false, error: { kind: "internal_error" } });
+    const failed = await routeLead(subscribeInput, sourceMeta);
+    expect(failed).toEqual(linked);
+    expect(subscriberData()).toEqual(expect.objectContaining({ personId: null }));
+    expect(error.mock.calls.map(([fields]) => fields)).toContainEqual({ event: "person-failed", siteId: "site-abc" });
+    jest.mocked(prisma.subscriber.create).mockClear();
+
+    find.mockRejectedValueOnce(new Error("boom"));
+    const thrown = await routeLead(subscribeInput, sourceMeta);
+    expect(thrown).toEqual(linked);
+    expect(subscriberData()).toEqual(expect.objectContaining({ personId: null }));
+  });
+
+  it("a duplicate subscribe (P2002) makes no second Person call", async () => {
+    (prisma.subscriber.create as jest.Mock).mockRejectedValue(Object.assign(new Error("dup"), { code: "P2002" }));
+    (prisma.subscriber.findUnique as jest.Mock).mockResolvedValue({ id: "subscr_existing" });
+    const find = spyFind().mockResolvedValue(LINKED);
+    const result = await routeLead(subscribeInput, sourceMeta);
+    expect(result).toMatchObject({ ok: true, id: "subscr_existing" });
+    expect(find).toHaveBeenCalledTimes(1);
+  });
+
+  it("a callback with payload.email and a spaced phone links its Person, carrying the E.164 telephone", async () => {
+    (prisma.callback.create as jest.Mock).mockResolvedValue({ id: "callbk_x" });
+    const find = spyFind().mockResolvedValue(LINKED);
+    await routeLead(
+      { ...callbackInput, phone: "+1 415 555 0123", payload: { email: "c@x.io" } },
+      sourceMeta,
+    );
+    expect(find).toHaveBeenCalledWith("site-abc", {
+      email: "c@x.io",
+      name: "Alice",
+      contact: { telephone: "+14155550123" },
+    });
+    expect(callbackData()).toEqual(expect.objectContaining({ personId: MOCK_PERSON_ID }));
+  });
+
+  it.each([
+    ["no payload.email", { notes: "urgent" }],
+    ["a numeric payload.email", { email: 12345 }],
+  ])("a callback with %s makes no person delegate call and writes no personId key", async (_label, payload) => {
+    (prisma.callback.create as jest.Mock).mockResolvedValue({ id: "callbk_x" });
+    await routeLead({ ...callbackInput, payload }, sourceMeta);
     expect(personCalls()).toBe(0);
+    expect(Object.keys(callbackData())).not.toContain("personId");
+  });
+
+  // ── #8435 D5 (AC-4) — a submit's explicit contact ────────────────────────
+  it("a submit with options.contact.name passes that name over payload.name, and the normalized contact", async () => {
+    const find = spyFind().mockResolvedValue(LINKED);
+    await routeLead(
+      { ...leadInput, payload: { name: "Bob" } },
+      sourceMeta,
+      { contact: { name: "Ann", givenName: "Ann", phone: "+1 (415) 555-0123" } },
+    );
+    expect(find).toHaveBeenCalledWith("site-abc", {
+      email: "test@example.com",
+      name: "Ann",
+      contact: { givenName: "Ann", telephone: "+14155550123" },
+    });
+    // the lead's payload is the raw answers, unchanged
+    expect(createData()["payload"]).toEqual({ name: "Bob" });
+  });
+
+  it("a submit with no options.contact passes payload.name and no contact, as before", async () => {
+    const find = spyFind().mockResolvedValue(LINKED);
+    await routeLead({ ...leadInput, payload: { name: "Bob" } }, sourceMeta);
+    expect(find).toHaveBeenCalledWith("site-abc", { email: "test@example.com", name: "Bob" });
   });
 
   it("an invalid_email Person result writes the lead with personId: null and one person-skipped warn with no email", async () => {
@@ -1060,7 +1169,9 @@ describe("#852 — the lead's Person (AC-3)", () => {
 
     const failed = await routeLead(leadInput, sourceMeta);
 
-    expect(failed).toEqual(ok);
+    // The answer is the same as a successful capture, apart from the internal
+    // `personId` (#8438 D11) the route never puts on a wire.
+    expect(failed).toEqual({ ...ok, personId: null });
     expect(failed).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db", email: { ok: true } });
     expect(createData()).toEqual(expect.objectContaining({ personId: null }));
     const lines = error.mock.calls.filter(([fields]) => (fields as { event?: string }).event === "person-failed");
@@ -1198,6 +1309,64 @@ describe("#7877 — the checkout lead sets the plan (AC-5)", () => {
     expect(planLines()).toEqual([]);
   });
 
+  // #8185 — the hub stores its conclusion that a lead is a spoke's live paid
+  // checkout (`Lead.spokeCheckout`): the plan rule's own predicate, plus "not
+  // relayed". An unmarked create names no `spokeCheckout` key at all.
+  const createData = () =>
+    (prisma.lead.create as jest.Mock).mock.calls[0][0].data as Record<string, unknown>;
+
+  it("a live spoke checkout lead is created with spokeCheckout true and still sets the plan once", async () => {
+    await routeLead(checkoutLead, spokeMeta, { idempotencyKey: KEY });
+    expect(createData()).toMatchObject({ spokeCheckout: true });
+    expect(setPlan).toHaveBeenCalledTimes(1);
+  });
+
+  it("the same lead relayed for a visitor is created with no spokeCheckout key and still sets the plan", async () => {
+    await routeLead(checkoutLead, { ...spokeMeta, relayed: true }, { idempotencyKey: KEY });
+    expect(createData()).not.toHaveProperty("spokeCheckout");
+    expect(setPlan).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["an anonymous lead (viaSpoke false)", checkoutLead, sourceMeta, KEY],
+    ["a test-mode session key", checkoutLead, spokeMeta, "cs_test_a1B2c3"],
+    [
+      "amountTotal 0",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, amountTotal: 0 } },
+      spokeMeta,
+      KEY,
+    ],
+    [
+      "a negative amountTotal",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, amountTotal: -5 } },
+      spokeMeta,
+      KEY,
+    ],
+    ["a key that is not a session id", checkoutLead, spokeMeta, "abcdefghijklmnop"],
+    ["no key", checkoutLead, spokeMeta, undefined],
+    ["source contact", { ...checkoutLead, source: "contact" }, spokeMeta, KEY],
+    [
+      "page contact",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, page: "contact" } },
+      spokeMeta,
+      KEY,
+    ],
+    [
+      "a numeric offering",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, offering: 42 } },
+      spokeMeta,
+      KEY,
+    ],
+  ] as const)("no spokeCheckout key in the create data for %s", async (_label, input, meta, key) => {
+    await routeLead(
+      input as typeof checkoutLead,
+      meta,
+      key === undefined ? {} : { idempotencyKey: key },
+    );
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(createData()).not.toHaveProperty("spokeCheckout");
+  });
+
   it("an offering that is not a key after the strip logs skipped and makes no plan call", async () => {
     await routeLead(
       { ...checkoutLead, payload: { ...checkoutLead.payload, offering: "Wendi_Retainer!" } },

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

@@ -33,15 +33,24 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { prisma } from "../../lib/prisma.js";
+import { personContactPatchSchema } from "@working-theory/validation";
+
 import {
+  contactConfirmedFromRow,
+  ensureMemberPerson,
   findOrCreatePerson,
   isStorablePersonEmail,
+  normalizeCapturedContact,
   normalizePersonEmail,
+  normalizeTelephone,
+  personContactFromRow,
   recordCheckoutPerson,
   resolveCallerBillingCustomerId,
   resolveMemberPersonId,
+  setOwnPersonContact,
   setPersonPlanOffering,
   stampPersonUser,
+  updatePersonContact,
 } from "../person";
 
 type Row = Record<string, unknown>;
@@ -77,6 +86,20 @@ function seedPerson(row: Row): Row {
     billingProvider: null,
     billingCustomerId: null,
     planOffering: null,
+    // #8435 — the contact columns, blank the way Postgres reads them back.
+    givenName: null,
+    familyName: null,
+    telephone: null,
+    addressLine1: null,
+    addressLine2: null,
+    addressCity: null,
+    addressRegion: null,
+    addressPostalCode: null,
+    addressCountry: null,
+    companyName: null,
+    jobTitle: null,
+    contactConfirmedAt: null,
+    contactConfirmedBy: null,
     createdAt: new Date(Date.UTC(2026, 0, 1 + people().length)),
     updatedAt: new Date(),
     ...row,
@@ -531,6 +554,375 @@ describe("resolveCallerBillingCustomerId (#7961, spec 7894 D13, AC-8)", () => {
   });
 });
 
+const ADDRESS = {
+  addressLine1: "1 Main St",
+  addressLine2: null,
+  city: "Austin",
+  region: "TX",
+  postalCode: "78701",
+  country: "US",
+};
+const ADDRESS_COLUMNS = {
+  addressLine1: "1 Main St",
+  addressLine2: null,
+  addressCity: "Austin",
+  addressRegion: "TX",
+  addressPostalCode: "78701",
+  addressCountry: "US",
+};
+
+describe("findOrCreatePerson fills blank contact fields (#8435 D4, AC-2)", () => {
+  const contactCalls = () =>
+    store.__calls.filter((c) => c.model === "person" && c.op === "updateMany");
+
+  it("a new email with a contact creates one Person carrying it, named from given + family", async () => {
+    const result = await findOrCreatePerson(WS_A1, {
+      email: "new@x.io",
+      contact: { givenName: "Ada", familyName: "Lovelace", telephone: "+442071234567" },
+    });
+    expect(result.ok && result.value.created).toBe(true);
+    expect(people()).toHaveLength(1);
+    expect(people()[0]).toEqual(
+      expect.objectContaining({
+        givenName: "Ada",
+        familyName: "Lovelace",
+        telephone: "+442071234567",
+        name: "Ada Lovelace",
+      }),
+    );
+  });
+
+  it("given name alone names the Person; a supplied name wins over given + family", async () => {
+    await findOrCreatePerson(WS_A1, { email: "a@x.io", contact: { givenName: "Ada" } });
+    await findOrCreatePerson(WS_A1, {
+      email: "b@x.io",
+      name: "Countess",
+      contact: { givenName: "Ada", familyName: "Lovelace" },
+    });
+    expect(people().map((p) => p["name"])).toEqual(["Ada", "Countess"]);
+  });
+
+  it("a matched Person's stored value is never overwritten; its blank fields are filled", async () => {
+    seedPerson({ email: "m@x.io", telephone: "+15550000001" });
+    await findOrCreatePerson(WS_A1, {
+      email: "m@x.io",
+      contact: { telephone: "+15550000002", companyName: "Acme" },
+    });
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ telephone: "+15550000001", companyName: "Acme" }),
+    );
+  });
+
+  it("a stored address is left whole; a Person with none gains all six parts", async () => {
+    seedPerson({
+      email: "has@x.io",
+      addressLine1: "9 Old Rd",
+      addressCity: "Leeds",
+      addressRegion: "WYK",
+      addressPostalCode: "LS1",
+      addressCountry: "GB",
+    });
+    seedPerson({ email: "none@x.io" });
+    await findOrCreatePerson(WS_A1, { email: "has@x.io", contact: { address: ADDRESS } });
+    await findOrCreatePerson(WS_A1, { email: "none@x.io", contact: { address: ADDRESS } });
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ addressLine1: "9 Old Rd", addressCity: "Leeds", addressCountry: "GB" }),
+    );
+    expect(people()[1]).toEqual(expect.objectContaining(ADDRESS_COLUMNS));
+  });
+
+  it("a name already on the Person is not replaced by given + family", async () => {
+    seedPerson({ email: "n@x.io", name: "A. L." });
+    await findOrCreatePerson(WS_A1, {
+      email: "n@x.io",
+      contact: { givenName: "Ada", familyName: "Lovelace" },
+    });
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ name: "A. L.", givenName: "Ada", familyName: "Lovelace" }),
+    );
+  });
+
+  it("a nameless uncurated Person gains the joined name", async () => {
+    seedPerson({ email: "n@x.io" });
+    await findOrCreatePerson(WS_A1, {
+      email: "n@x.io",
+      contact: { givenName: "Ada", familyName: "Lovelace" },
+    });
+    expect(people()[0]!["name"]).toBe("Ada Lovelace");
+  });
+
+  it("a customer-id hit (step 2) writes nothing — contact included", async () => {
+    seedPerson({ email: "c@x.io", billingProvider: "stripe", billingCustomerId: "cus_1" });
+    await findOrCreatePerson(WS_A1, {
+      email: "other@x.io",
+      billingCustomerId: "cus_1",
+      contact: { telephone: "+15550000003" },
+    });
+    expect(contactCalls()).toHaveLength(0);
+    expect(people()[0]!["telephone"]).toBeNull();
+  });
+
+  it("a double whose matched row carries no contact keys triggers no contact write", async () => {
+    seedPerson({ email: "d@x.io" });
+    store.person["findFirst"]!.mockResolvedValueOnce({
+      id: people()[0]!["id"],
+      name: null,
+      userId: null,
+      billingCustomerId: null,
+    });
+    await findOrCreatePerson(WS_A1, { email: "d@x.io", contact: { telephone: "+15550000004" } });
+    expect(contactCalls()).toHaveLength(0);
+  });
+
+  describe("only an uncurated Person is filled (SEC-8435-A)", () => {
+    it("a Person linked to a user is not filled", async () => {
+      seedPerson({ email: "u@x.io", userId: "user_00000000-0000-7000-8000-0000000000e1" });
+      await findOrCreatePerson(WS_A1, { email: "u@x.io", contact: { telephone: "+15550000005" } });
+      expect(people()[0]!["telephone"]).toBeNull();
+      expect(contactCalls()).toHaveLength(0);
+    });
+
+    it("a Person a human saved is not filled — a field they cleared is not refilled", async () => {
+      seedPerson({ email: "h@x.io", contactConfirmedAt: new Date(), contactConfirmedBy: "client" });
+      await findOrCreatePerson(WS_A1, { email: "h@x.io", contact: { telephone: "+15550000006" } });
+      expect(people()[0]!["telephone"]).toBeNull();
+      expect(contactCalls()).toHaveLength(0);
+    });
+
+    it("an uncurated Person is filled", async () => {
+      seedPerson({ email: "free@x.io" });
+      await findOrCreatePerson(WS_A1, { email: "free@x.io", contact: { telephone: "+15550000007" } });
+      expect(people()[0]!["telephone"]).toBe("+15550000007");
+    });
+
+    it("a link that lands between the match read and the fill wins: the guarded write matches nothing", async () => {
+      seedPerson({ email: "race@x.io" });
+      const read = store.person["findFirst"]!.getMockImplementation()!;
+      store.person["findFirst"]!.mockImplementationOnce(async (args: unknown) => {
+        const row = await read(args);
+        people()[0]!["userId"] = "user_00000000-0000-7000-8000-0000000000e2";
+        return row;
+      });
+      await findOrCreatePerson(WS_A1, { email: "race@x.io", contact: { telephone: "+15550000008" } });
+      expect(people()[0]!["telephone"]).toBeNull();
+    });
+  });
+
+  it("a failing fill never changes the capture's outcome", async () => {
+    seedPerson({ email: "fail@x.io" });
+    store.person["updateMany"]!.mockRejectedValueOnce(new Error("down"));
+    const result = await findOrCreatePerson(WS_A1, {
+      email: "fail@x.io",
+      contact: { telephone: "+15550000009" },
+    });
+    expect(result.ok && result.value.created).toBe(false);
+  });
+});
+
+describe("the contact normalizers (#8435 D3, AC-2)", () => {
+  it.each([
+    ["+1 (415) 555-0123", "+14155550123"],
+    ["+44 20 7123 4567", "+442071234567"],
+    ["+1.415.555.0123", "+14155550123"],
+    ["415-555-0123", null],
+    ["+0 123", null],
+    ["+1234567890123456", null],
+    ["", null],
+    [4155550123, null],
+    [null, null],
+  ])("normalizeTelephone(%p) → %p", (raw, expected) => {
+    expect(normalizeTelephone(raw)).toBe(expected);
+  });
+
+  it("strips bidi, zero-width, separator and control characters from a given name", () => {
+    expect(normalizeCapturedContact({ givenName: "A‮d​a
\u0007" }).givenName).toBe("Ada");
+  });
+
+  it("cuts a 300-character company to 200 code points", () => {
+    const company = normalizeCapturedContact({ company: "c".repeat(300) }).companyName;
+    expect(Array.from(company ?? "")).toHaveLength(200);
+  });
+
+  it("stores a short region upper-cased, a full region as typed, and drops an address missing a part whole", () => {
+    const base = { addressLine1: "1 Main", city: "Albany", postalCode: "12207", country: "US" };
+    expect(normalizeCapturedContact({ address: { ...base, region: "ny" } }).address?.region).toBe("NY");
+    expect(normalizeCapturedContact({ address: { ...base, region: "New York" } }).address?.region).toBe(
+      "New York",
+    );
+    expect(normalizeCapturedContact({ address: { ...base, region: "NY", postalCode: undefined } }).address).toBeUndefined();
+    expect(normalizeCapturedContact({ address: { ...base, region: "NY", country: "us" } }).address).toBeUndefined();
+  });
+
+  it("drops a non-string value and an empty-after-cleaning one", () => {
+    expect(
+      normalizeCapturedContact({ givenName: 12, familyName: "​  ", company: {}, jobTitle: null, phone: "555" }),
+    ).toEqual({});
+  });
+
+  describe("the capture normalizer and the wire's edit schema agree on one table", () => {
+    // (field, raw) — within its width, so a capture would keep every character.
+    const TABLE: Array<[string, string]> = [
+      ["givenName", "Ada"],
+      ["givenName", "  Ada  "],
+      ["givenName", "A‮d​a
\u0007"],
+      ["givenName", "\u{1D56B}".repeat(100)],
+      ["givenName", "​  "],
+      ["familyName", "Lovelace"],
+      ["companyName", "c".repeat(200)],
+      ["jobTitle", "Founder"],
+      ["telephone", "+1 (415) 555-0123"],
+      ["telephone", "415-555-0123"],
+      ["telephone", "+1 415 555 0123"],
+    ];
+    const CAPTURE_KEY: Record<string, string> = {
+      givenName: "givenName",
+      familyName: "familyName",
+      companyName: "company",
+      jobTitle: "jobTitle",
+      telephone: "phone",
+    };
+
+    it.each(TABLE)("%s %j", (field, raw) => {
+      const captured = normalizeCapturedContact({ [CAPTURE_KEY[field]!]: raw }) as Record<string, unknown>;
+      const parsed = personContactPatchSchema.safeParse({ [field]: raw });
+      if (parsed.success) {
+        expect(captured[field]).toBe((parsed.data as Record<string, unknown>)[field]);
+      } else {
+        expect(captured[field]).toBeUndefined();
+      }
+    });
+
+    it("an address and its short region agree", () => {
+      const address = { addressLine1: "1 Main", city: "Albany", region: "ny", postalCode: "12207", country: "US" };
+      const captured = normalizeCapturedContact({ address }).address;
+      const parsed = personContactPatchSchema.parse({ address }).address;
+      expect(captured).toEqual(parsed);
+    });
+  });
+});
+
+describe("the two human edits of the contact (#8435 D9, D11)", () => {
+  const U = "user_00000000-0000-7000-8000-0000000000f1";
+  const users = () => (store.__db["user"] ??= []);
+
+  it("updatePersonContact writes only the keys present, stamps the operator and serves the saved contact", async () => {
+    const p = seedPerson({ email: "o@x.io", companyName: "Keep" });
+    const outcome = await updatePersonContact(WS_A1, p["id"] as string, {
+      telephone: "+14155550123",
+      address: ADDRESS,
+    });
+    expect(outcome.kind).toBe("saved");
+    expect(people()[0]).toEqual(
+      expect.objectContaining({
+        telephone: "+14155550123",
+        companyName: "Keep",
+        contactConfirmedBy: "operator",
+        ...ADDRESS_COLUMNS,
+      }),
+    );
+    expect(people()[0]!["contactConfirmedAt"]).toBeInstanceOf(Date);
+    if (outcome.kind !== "saved") return;
+    expect(outcome.value.confirmed?.by).toBe("operator");
+    expect(outcome.value.contact.address).toEqual(ADDRESS);
+    expect(outcome.value.contact.companyName).toBe("Keep");
+  });
+
+  it("an address of null clears all six parts", async () => {
+    const p = seedPerson({ email: "o@x.io", ...ADDRESS_COLUMNS });
+    await updatePersonContact(WS_A1, p["id"] as string, { address: null });
+    expect(people()[0]).toEqual(
+      expect.objectContaining({ addressLine1: null, addressCity: null, addressCountry: null }),
+    );
+  });
+
+  it("another workspace's Person, and an absent one, are not_found and unchanged", async () => {
+    const p = seedPerson({ workspaceId: WS_A2, email: "o@x.io" });
+    expect((await updatePersonContact(WS_A1, p["id"] as string, { jobTitle: "x" })).kind).toBe("not_found");
+    expect((await updatePersonContact(WS_A1, "person_nope", { jobTitle: "x" })).kind).toBe("not_found");
+    expect(people()[0]!["jobTitle"]).toBeNull();
+  });
+
+  it("a store error is internal_error, never a throw", async () => {
+    store.person["updateMany"]!.mockRejectedValueOnce(new Error("down"));
+    expect((await updatePersonContact(WS_A1, "person_x", { jobTitle: "x" })).kind).toBe("internal_error");
+  });
+
+  it("setOwnPersonContact replaces all six keys on the caller's own Person only", async () => {
+    const mine = seedPerson({ email: "me@x.io", userId: U, companyName: "Capture-filled", jobTitle: "Boss" });
+    const other = seedPerson({ email: "other@x.io", userId: "user_00000000-0000-7000-8000-0000000000f2" });
+    const outcome = await setOwnPersonContact(WS_A1, mine["id"] as string, U, {
+      givenName: "Me",
+      familyName: null,
+      telephone: "+14155550123",
+      address: null,
+      companyName: null,
+      jobTitle: null,
+    });
+    expect(outcome.kind).toBe("saved");
+    expect(people()[0]).toEqual(
+      expect.objectContaining({
+        givenName: "Me",
+        companyName: null,
+        jobTitle: null,
+        contactConfirmedBy: "client",
+      }),
+    );
+    expect(people()[1]).toBe(other);
+    expect(people()[1]!["givenName"]).toBeNull();
+  });
+
+  it("setOwnPersonContact is not_found for a Person linked to someone else, or of another workspace", async () => {
+    const linkedElsewhere = seedPerson({ email: "a@x.io", userId: "user_00000000-0000-7000-8000-0000000000f3" });
+    const otherWorkspace = seedPerson({ workspaceId: WS_A2, email: "me@x.io", userId: U });
+    const body = { givenName: "X", familyName: null, telephone: null, address: null, companyName: null, jobTitle: null };
+    expect((await setOwnPersonContact(WS_A1, linkedElsewhere["id"] as string, U, body)).kind).toBe("not_found");
+    expect((await setOwnPersonContact(WS_A1, otherWorkspace["id"] as string, U, body)).kind).toBe("not_found");
+    expect(people().map((p) => p["givenName"])).toEqual([null, null]);
+  });
+
+  it("ensureMemberPerson creates the verified email's Person and links it", async () => {
+    users().push({ id: U, email: "  Me@X.io ", emailVerified: true });
+    const result = await ensureMemberPerson(WS_A1, U);
+    expect(result.ok).toBe(true);
+    expect(people()).toHaveLength(1);
+    expect(people()[0]).toEqual(expect.objectContaining({ email: "me@x.io", userId: U }));
+  });
+
+  it("ensureMemberPerson finds the existing Person of that email and links it", async () => {
+    const p = seedPerson({ email: "me@x.io" });
+    users().push({ id: U, email: "me@x.io", emailVerified: true });
+    const result = await ensureMemberPerson(WS_A1, U);
+    expect(result).toEqual({ ok: true, personId: p["id"] });
+    expect(people()).toHaveLength(1);
+    expect(people()[0]!["userId"]).toBe(U);
+  });
+
+  it("ensureMemberPerson is unavailable for an unverified caller and for a Person linked to another user", async () => {
+    users().push({ id: U, email: "me@x.io", emailVerified: false });
+    expect(await ensureMemberPerson(WS_A1, U)).toEqual({ ok: false });
+    users()[0]!["emailVerified"] = true;
+    seedPerson({ email: "me@x.io", userId: "user_00000000-0000-7000-8000-0000000000f4" });
+    expect(await ensureMemberPerson(WS_A1, U)).toEqual({ ok: false });
+    expect(people()[0]!["userId"]).toBe("user_00000000-0000-7000-8000-0000000000f4");
+  });
+
+  it("personContactFromRow serves a whole address or none, and every key even from a sparse row", () => {
+    expect(personContactFromRow({ ...(seedPerson({ email: "r@x.io", ...ADDRESS_COLUMNS }) as never) }).address).toEqual(ADDRESS);
+    expect(personContactFromRow({} as never)).toEqual({
+      givenName: null,
+      familyName: null,
+      telephone: null,
+      address: null,
+      companyName: null,
+      jobTitle: null,
+    });
+    expect(contactConfirmedFromRow({ contactConfirmedAt: null, contactConfirmedBy: null })).toBeNull();
+    expect(
+      contactConfirmedFromRow({ contactConfirmedAt: new Date("2026-10-12T00:00:00.000Z"), contactConfirmedBy: "client" }),
+    ).toEqual({ by: "client", at: "2026-10-12T00:00:00.000Z" });
+  });
+});
+
 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" });