create-ailk 0.19.0 → 0.20.0

package/templates/apps/api/src/services/__tests__/consent-ledger.test.ts

@@ -0,0 +1,503 @@
+/**
+ * @file consent-ledger.test.ts
+ * @description The consent ledger's writers (#8438 D3) — `recordCookieChoice`,
+ * `recordPersonConsent`, `linkConsentVisitor`, the unsubscribe token, and the
+ * `source` contract of `recordConsent`.
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper -> prisma-client.js mock;
+ *     prisma singleton via __mocks__/prisma.ts)
+ *
+ * The ledger is modelled in memory: `$transaction` runs its callback on the
+ * mocked client, `consentGrant.createMany` appends, and `$queryRaw` answers
+ * the way the store's `DISTINCT ON` queries would — newest row per purpose —
+ * so the "writes only when the answer changes" rule is exercised end to end.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+import {
+  PLATFORM_CONSENT_CONFIG,
+  resolveConsentStatement,
+  SITE_CONSENT_CONFIG_DEFAULTS,
+  siteConsentConfigSchema,
+} from "@working-theory/validation";
+
+import {
+  armConsentLedger,
+  type LedgerRow,
+  type LinkRow,
+} from "../../lib/__tests__/consent-ledger-double.js";
+import { prisma } from "../../lib/prisma.js";
+
+import {
+  ConsentLinkSecretMissing,
+  consentLinkSecretConfigured,
+  consentUnsubscribeToken,
+  linkConsentVisitor,
+  recordConsent,
+  recordCookieChoice,
+  recordPersonConsent,
+  verifyConsentUnsubscribeToken,
+} from "../consent";
+
+const WS = "wksp_01920000-0000-7000-8000-0000000000a1";
+const PERSON = "person_01920000-0000-7000-8000-0000000000a1";
+const VISITOR = "0192a000-0000-4000-8000-0000000000a1";
+
+type Row = LedgerRow;
+
+const CONFIG = siteConsentConfigSchema.parse({
+  policies: { terms: "/terms", privacy: "/privacy" },
+  purposes: [
+    {
+      id: "service_terms",
+      required: true,
+      kind: "agreement",
+      policy: "terms",
+      label: { en: "You agree." },
+    },
+    {
+      id: "product_news",
+      kind: "preference",
+      area: "communications",
+      label: { en: "Product news." },
+    },
+    {
+      id: "share_data",
+      kind: "consent",
+      area: "data",
+      label: { en: "Share usage data." },
+    },
+    {
+      id: "analytics_cookies",
+      kind: "consent",
+      area: "cookies",
+      label: { en: "Analytics cookies." },
+    },
+  ],
+});
+
+/** The in-memory ledger every case appends to (`lib/__tests__/consent-ledger-double.ts`). */
+let ledger: Row[] = [];
+let links: LinkRow[] = [];
+
+function newest(rows: Row[], purposeId?: string): Row | null {
+  const matching = rows.filter((r) => purposeId === undefined || r.purposeId === purposeId);
+  return matching.length === 0 ? null : matching[matching.length - 1]!;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  const double = armConsentLedger(prisma);
+  ledger = double.ledger;
+  links = double.links;
+});
+
+describe("recordConsent carries the ledger fields (#8438 D3)", () => {
+  it("stamps personId, source, sourceRef and the purpose's policy version on every row", async () => {
+    await recordConsent({
+      siteId: WS,
+      subjectType: "lead",
+      subjectId: "lead_1",
+      personId: PERSON,
+      source: "magnet",
+      sourceRef: "free-guide",
+      locale: "en",
+      config: CONFIG,
+      consents: { service_terms: true, share_data: false },
+    });
+    expect(ledger).toHaveLength(2);
+    expect(ledger[0]).toMatchObject({
+      personId: PERSON,
+      source: "magnet",
+      sourceRef: "free-guide",
+      policyVersion: 1,
+    });
+  });
+
+  it("is a type error to write a row with no source", async () => {
+    await recordConsent(
+      // @ts-expect-error -- `source` is required: every writer must say where the answer came from.
+      {
+        siteId: WS,
+        subjectType: "lead",
+        subjectId: "lead_1",
+        personId: null,
+        locale: "en",
+        config: CONFIG,
+        consents: { service_terms: true },
+      },
+    );
+  });
+});
+
+describe("recordPersonConsent (#8438 D3)", () => {
+  const base = {
+    workspaceId: WS,
+    personId: PERSON,
+    locale: "en",
+    config: CONFIG,
+    subject: { subjectType: "person", subjectId: PERSON },
+  };
+  const settings = (purposeId: string, granted: boolean) =>
+    recordPersonConsent({
+      ...base,
+      purposeId,
+      granted,
+      source: "account_settings",
+    });
+
+  it("grant -> withdraw -> grant leaves three rows, newest granted", async () => {
+    await settings("share_data", true);
+    await settings("share_data", false);
+    await settings("share_data", true);
+    expect(ledger.map((r) => r.granted)).toEqual([true, false, true]);
+    expect(newest(ledger, "share_data")?.source).toBe("account_settings");
+  });
+
+  it("writes nothing for a repeat of the same answer", async () => {
+    await settings("share_data", true);
+    const again = await settings("share_data", true);
+    expect(again).toEqual({ ok: true, changed: false });
+    expect(ledger).toHaveLength(1);
+  });
+
+  it("treats a preference as on until withdrawn: granting it first writes nothing", async () => {
+    expect(await settings("product_news", true)).toEqual({
+      ok: true,
+      changed: false,
+    });
+    expect(ledger).toHaveLength(0);
+    expect(await settings("product_news", false)).toEqual({
+      ok: true,
+      changed: true,
+    });
+    expect(ledger).toHaveLength(1);
+  });
+
+  it("records the statement the registry resolves, never one from the caller", async () => {
+    await settings("share_data", true);
+    const purpose = CONFIG.purposes.find((p) => p.id === "share_data")!;
+    expect(ledger[0]?.["statement"]).toBe(
+      resolveConsentStatement(purpose, "en").statement,
+    );
+  });
+
+  it("asks an agreement once per policy version and refuses to withdraw it", async () => {
+    expect(await settings("service_terms", true)).toEqual({
+      ok: true,
+      changed: true,
+    });
+    expect(await settings("service_terms", true)).toEqual({
+      ok: true,
+      changed: false,
+    });
+    expect(await settings("service_terms", false)).toEqual({
+      ok: false,
+      code: "agreement_not_withdrawable",
+    });
+    expect(ledger).toHaveLength(1);
+  });
+
+  it("re-asks an agreement when its policy version is bumped", async () => {
+    await settings("service_terms", true);
+    const bumped = siteConsentConfigSchema.parse({
+      ...CONFIG,
+      purposes: CONFIG.purposes.map((p) =>
+        p.id === "service_terms" ? { ...p, policyVersion: 2 } : p,
+      ),
+    });
+    const result = await recordPersonConsent({
+      ...base,
+      config: bumped,
+      purposeId: "service_terms",
+      granted: true,
+      source: "account_settings",
+    });
+    expect(result).toEqual({ ok: true, changed: true });
+    expect(newest(ledger, "service_terms")?.policyVersion).toBe(2);
+  });
+
+  it("refuses an unknown purpose and the cookie purpose", async () => {
+    expect(await settings("nope", true)).toEqual({
+      ok: false,
+      code: "purpose_unknown",
+    });
+    expect(await settings("analytics_cookies", true)).toEqual({
+      ok: false,
+      code: "cookie_purpose",
+    });
+    expect(ledger).toHaveLength(0);
+  });
+
+  it("takes the (subject, purpose) advisory lock before it reads", async () => {
+    await settings("share_data", true);
+    const lock = (prisma.$executeRaw as jest.Mock).mock.calls[0]!;
+    expect(String(lock[0].join("?"))).toContain("pg_advisory_xact_lock");
+    expect(lock[1]).toBe(`ailk:consent:${WS}:person:${PERSON}:share_data`);
+  });
+
+  it("an unsubscribe withdraws a grant an anonymous form made, and only once", async () => {
+    // A magnet row the person never confirmed themself: own reading says
+    // 'not granted', any-source says granted.
+    ledger.push({
+      id: "cnsnt_00000000-0000-7000-8000-0000000000f1",
+      workspaceId: WS,
+      subjectType: "lead",
+      subjectId: "lead_1",
+      personId: PERSON,
+      purposeId: "share_data",
+      granted: true,
+      source: "magnet",
+      sourceRef: "free-guide",
+      policyVersion: 1,
+      locale: "en",
+      statement: "Share usage data.",
+      createdAt: new Date("2026-10-12T00:00:00Z"),
+    });
+    const first = await recordPersonConsent({
+      ...base,
+      purposeId: "share_data",
+      granted: false,
+      source: "email_unsubscribe",
+    });
+    const second = await recordPersonConsent({
+      ...base,
+      purposeId: "share_data",
+      granted: false,
+      source: "email_unsubscribe",
+    });
+    expect(first).toEqual({ ok: true, changed: true });
+    expect(second).toEqual({ ok: true, changed: false });
+    expect(ledger.filter((r) => r.source === "email_unsubscribe")).toHaveLength(
+      1,
+    );
+  });
+
+  it("an unsubscribe still withdraws an own grant that a newer anonymous decline hides", async () => {
+    await settings("share_data", true);
+    ledger.push({
+      id: "cnsnt_00000000-0000-7000-8000-0000000000f2",
+      workspaceId: WS,
+      subjectType: "lead",
+      subjectId: "lead_2",
+      personId: PERSON,
+      purposeId: "share_data",
+      granted: false,
+      source: "magnet",
+      sourceRef: "free-guide",
+      policyVersion: 1,
+      locale: "en",
+      statement: "Share usage data.",
+      createdAt: new Date(Date.now() + 60_000),
+    });
+    const result = await recordPersonConsent({
+      ...base,
+      purposeId: "share_data",
+      granted: false,
+      source: "email_unsubscribe",
+    });
+    expect(result).toEqual({ ok: true, changed: true });
+    expect(ledger.filter((r) => r.source === "email_unsubscribe")).toHaveLength(
+      1,
+    );
+  });
+
+  it("writes the owner's platform consents against subject user with no Person", async () => {
+    const result = await recordPersonConsent({
+      workspaceId: WS,
+      personId: null,
+      purposeId: "wt_product_data",
+      granted: true,
+      source: "account_settings",
+      locale: "en",
+      config: PLATFORM_CONSENT_CONFIG,
+      subject: { subjectType: "user", subjectId: "user_1" },
+    });
+    expect(result).toEqual({ ok: true, changed: true });
+    expect(ledger[0]).toMatchObject({ subjectType: "user", personId: null });
+  });
+});
+
+describe("recordCookieChoice (#8438 D3)", () => {
+  const choice = (c: "accepted" | "declined") =>
+    recordCookieChoice(
+      { workspaceId: WS, visitorId: VISITOR, choice: c, locale: "en" },
+      CONFIG,
+    );
+
+  it("writes one visitor row stamped with the banner source and the registry statement", async () => {
+    expect(await choice("accepted")).toEqual({ recorded: true });
+    expect(ledger).toHaveLength(1);
+    expect(ledger[0]).toMatchObject({
+      subjectType: "visitor",
+      subjectId: VISITOR,
+      purposeId: "analytics_cookies",
+      granted: true,
+      source: "cookie_banner",
+      policyVersion: 1,
+      personId: null,
+    });
+  });
+
+  it("logs a change of choice and not a replay", async () => {
+    await choice("accepted");
+    expect(await choice("accepted")).toEqual({ recorded: false });
+    expect(await choice("declined")).toEqual({ recorded: true });
+    expect(ledger.map((r) => r.granted)).toEqual([true, false]);
+  });
+
+  it("writes nothing when the registry declares no cookie purpose", async () => {
+    const none = siteConsentConfigSchema.parse({
+      policies: {},
+      purposes: [{ id: "a", label: { en: "a" } }],
+    });
+    expect(
+      await recordCookieChoice(
+        {
+          workspaceId: WS,
+          visitorId: VISITOR,
+          choice: "accepted",
+          locale: "en",
+        },
+        none,
+      ),
+    ).toEqual({ recorded: false });
+    expect(ledger).toHaveLength(0);
+  });
+
+  it("uses the platform default registry when none is passed", async () => {
+    expect(
+      await recordCookieChoice({
+        workspaceId: WS,
+        visitorId: VISITOR,
+        choice: "declined",
+        locale: "en",
+      }),
+    ).toEqual({ recorded: true });
+    expect(ledger[0]?.["purposeId"]).toBe(
+      SITE_CONSENT_CONFIG_DEFAULTS.purposes.find((p) => p.area === "cookies")
+        ?.id,
+    );
+  });
+});
+
+describe("linkConsentVisitor (#8438 C5)", () => {
+  it("inserts and ignores a duplicate", async () => {
+    (prisma.consentVisitorLink.createMany as jest.Mock).mockResolvedValue({
+      count: 1,
+    });
+    await linkConsentVisitor({
+      workspaceId: WS,
+      visitorId: VISITOR,
+      personId: PERSON,
+      source: "magnet",
+    });
+    expect(prisma.consentVisitorLink.createMany).toHaveBeenCalledWith({
+      data: [
+        {
+          workspaceId: WS,
+          visitorId: VISITOR,
+          personId: PERSON,
+          source: "magnet",
+        },
+      ],
+      skipDuplicates: true,
+    });
+  });
+
+  it("never throws: a failure is swallowed so a link cannot fail a lead", async () => {
+    (prisma.consentVisitorLink.createMany as jest.Mock).mockRejectedValue(
+      new Error("down"),
+    );
+    await expect(
+      linkConsentVisitor({
+        workspaceId: WS,
+        visitorId: VISITOR,
+        personId: PERSON,
+        source: "api",
+      }),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("the unsubscribe token (#8438 D3, SEC-8438-9)", () => {
+  const SECRET = "x".repeat(40);
+  const claims = {
+    workspaceId: WS,
+    personId: PERSON,
+    purposeId: "product_news",
+  };
+  let saved: string | undefined;
+
+  beforeEach(() => {
+    saved = process.env["AILK_CONSENT_LINK_SECRET"];
+    process.env["AILK_CONSENT_LINK_SECRET"] = SECRET;
+  });
+  afterEach(() => {
+    if (saved === undefined) delete process.env["AILK_CONSENT_LINK_SECRET"];
+    else process.env["AILK_CONSENT_LINK_SECRET"] = saved;
+  });
+
+  it("round-trips and has the v1.<payload>.<mac> shape", () => {
+    const token = consentUnsubscribeToken(claims);
+    expect(token).toMatch(/^v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/);
+    expect(verifyConsentUnsubscribeToken(token)).toEqual(claims);
+  });
+
+  it("refuses a token with one flipped character", () => {
+    const token = consentUnsubscribeToken(claims);
+    const flipped = token.slice(0, -1) + (token.endsWith("A") ? "B" : "A");
+    expect(verifyConsentUnsubscribeToken(flipped)).toBeNull();
+    const body = token.split(".");
+    body[1] = body[1]!.slice(0, -1) + (body[1]!.endsWith("A") ? "B" : "A");
+    expect(verifyConsentUnsubscribeToken(body.join("."))).toBeNull();
+  });
+
+  it("refuses a token older than 400 days, and a future-dated one", () => {
+    const now = new Date("2026-10-12T00:00:00Z");
+    const old = consentUnsubscribeToken(
+      claims,
+      new Date(now.getTime() - 401 * 86_400_000),
+    );
+    const fresh = consentUnsubscribeToken(
+      claims,
+      new Date(now.getTime() - 399 * 86_400_000),
+    );
+    const future = consentUnsubscribeToken(
+      claims,
+      new Date(now.getTime() + 3_600_000),
+    );
+    expect(verifyConsentUnsubscribeToken(old, now)).toBeNull();
+    expect(verifyConsentUnsubscribeToken(fresh, now)).toEqual(claims);
+    expect(verifyConsentUnsubscribeToken(future, now)).toBeNull();
+  });
+
+  it("refuses a wrong version, garbage, and a token signed with another secret", () => {
+    const token = consentUnsubscribeToken(claims);
+    expect(
+      verifyConsentUnsubscribeToken(token.replace(/^v1/, "v2")),
+    ).toBeNull();
+    expect(verifyConsentUnsubscribeToken("nonsense")).toBeNull();
+    expect(verifyConsentUnsubscribeToken("a.b.c")).toBeNull();
+    process.env["AILK_CONSENT_LINK_SECRET"] = "y".repeat(40);
+    expect(verifyConsentUnsubscribeToken(token)).toBeNull();
+  });
+
+  it("throws on mint, and refuses on verify, with the secret unset or under 32 bytes", () => {
+    const token = consentUnsubscribeToken(claims);
+    delete process.env["AILK_CONSENT_LINK_SECRET"];
+    expect(consentLinkSecretConfigured()).toBe(false);
+    expect(() => consentUnsubscribeToken(claims)).toThrow(
+      ConsentLinkSecretMissing,
+    );
+    expect(verifyConsentUnsubscribeToken(token)).toBeNull();
+    process.env["AILK_CONSENT_LINK_SECRET"] = "short";
+    expect(consentLinkSecretConfigured()).toBe(false);
+    expect(() => consentUnsubscribeToken(claims)).toThrow(
+      ConsentLinkSecretMissing,
+    );
+  });
+});

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

@@ -38,7 +38,12 @@ import {
 } from "../consent";
 
 const SITE_ID = "site-1";
-const SUBJECT = { subjectType: "project_listing", subjectId: "prjl_00000000-0000-7000-8000-000000000001" };
+const SUBJECT = {
+  subjectType: "project_listing",
+  subjectId: "prjl_00000000-0000-7000-8000-000000000001",
+  personId: null,
+  source: "api" as const,
+};
 
 /** Two purposes, one of them bilingual — the fixture every locale case reads from. */
 const CONFIG = siteConsentConfigSchema.parse({
@@ -220,6 +225,10 @@ describe("recordLegacyConsent (#5275 D11)", () => {
       locale: UNRECOVERABLE_CONSENT_LOCALE,
       statement: UNRECOVERABLE_CONSENT_STATEMENT,
       statementHash: consentStatementHash(UNRECOVERABLE_CONSENT_STATEMENT),
+      // #8438 D2 — the ledger fields: no Person, no magnet slug, and the
+      // registry's policy version in force.
+      sourceRef: null,
+      policyVersion: 1,
     });
     expect(rows[0]!["purposeId"]).toBe("service_terms");
     expect(rows[0]!["locale"]).toBe("und");
@@ -266,13 +275,19 @@ describe("consentConfigForSite", () => {
 });
 
 describe("requiredConsentUnmet (#5275, security review Medium 1)", () => {
-  const config = {
+  const config = siteConsentConfigSchema.parse({
     policies: {},
     purposes: [
       { id: "service_terms", required: true, label: { en: "a" } },
       { id: "marketing", required: false, label: { en: "b" } },
     ],
-  };
+  });
+
+  it("does not demand a sign-up agreement of a form that cannot show it (#8438 D13)", () => {
+    expect(
+      requiredConsentUnmet(SITE_CONSENT_CONFIG_DEFAULTS, { service_terms: true }),
+    ).toBeUndefined();
+  });
 
   it("names a required purpose that is declined OR absent, and passes when every required one is true", () => {
     expect(requiredConsentUnmet(config, { service_terms: false })).toBe("service_terms");

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");