create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/__tests__/magnet-completion.test.ts

@@ -0,0 +1,389 @@
+/**
+ * @file magnet-completion.test.ts
+ *
+ * #8757 D6 (spec docs/specs/8757-a-per-magnet-completion-setting-spec.md,
+ * AC-5's origin, link and copy): where a submitter's account link points,
+ * what the invite email says, and when a completion degrades to `lead`.
+ *
+ * Mocked at their own boundaries: the completion store, the sign-in client
+ * read, the commerce claim, the offerings lister and `@working-theory/email`.
+ */
+const mockLiveCompletionBySlug = jest.fn();
+const mockInviteSendCounts = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/flow-completion-store.js", () => ({
+  liveCompletionBySlug: (...args: unknown[]) => mockLiveCompletionBySlug(...args),
+  inviteSendCounts: (...args: unknown[]) => mockInviteSendCounts(...args),
+}));
+
+const mockFindClientByClientId = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/hub-sign-in-store.js", () => ({
+  findClientByClientId: (...args: unknown[]) => mockFindClientByClientId(...args),
+}));
+
+const mockResolveCommerceClaim = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/require-commerce-claim.js", () => ({
+  resolveCommerceClaim: () => mockResolveCommerceClaim(),
+}));
+
+const mockListPlanOfferings = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../plan-offerings.js", () => ({
+  listPlanOfferings: (...args: unknown[]) => mockListPlanOfferings(...args),
+}));
+
+const mockSendDeliverableEmail = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendDeliverableEmail: (...args: unknown[]) => mockSendDeliverableEmail(...args),
+}));
+
+import { deliverableSenderAddress } from "../deliverable-fulfillment.js";
+import {
+  accountTargetFor,
+  inviteSenderAddress,
+  MAGNET_COMPLETION_BUDGET_MS,
+  magnetCompletionFor,
+  magnetCompletionWithinBudget,
+  sendInviteConfirmation,
+  type MagnetCompletion,
+} from "../magnet-completion.js";
+
+const WS = "wksp_00000000-0000-7000-8000-0000000000c1";
+const S1 = "spoke_00000000-0000-7000-8000-0000000000d1";
+const NOW = new Date("2026-10-15T12:00:00.000Z");
+const originalEnv = process.env;
+
+const client = (redirectUri: string, enabled = true) => ({
+  id: "oauthc_1",
+  clientId: S1,
+  clientSecret: "x",
+  redirectUris: [redirectUri],
+  enabled,
+});
+
+const invite = (config: unknown = { defaultLocale: "en" }): MagnetCompletion => ({
+  next: { completion: "invite" },
+  title: "Request a quote",
+  config,
+  target: { origin: "https://site.example", provider: "site" },
+});
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = {
+    ...originalEnv,
+    FRONTEND_URL: "https://site.example/app",
+    AILK_ENABLED_MODULES: "multi-tenant",
+    AILK_DELIVERABLE_EMAIL_FROM: "hello@site.example",
+  };
+  mockInviteSendCounts.mockResolvedValue({ recipientDay: 1, siteHour: 1 });
+  mockSendDeliverableEmail.mockResolvedValue({ ok: true, messageId: "m1" });
+  mockResolveCommerceClaim.mockResolvedValue("claimed");
+  mockListPlanOfferings.mockResolvedValue([{ key: "retainer", name: "Retainer", type: "service" }]);
+});
+
+afterAll(() => {
+  process.env = originalEnv;
+});
+
+describe("accountTargetFor — the link's origin is never the request's", () => {
+  it("a keyless caller on a build with an account area gets FRONTEND_URL's origin and the site path", async () => {
+    expect(await accountTargetFor({ kind: "anonymous" })).toEqual({
+      origin: "https://site.example",
+      provider: "site",
+    });
+  });
+
+  it("a keyless caller on a build with no account area gets nothing", async () => {
+    process.env.AILK_ENABLED_MODULES = "signal-collectors";
+    expect(await accountTargetFor({ kind: "anonymous" })).toBeNull();
+  });
+
+  it("a spoke gets its enabled sign-in client's callback origin and the hub path", async () => {
+    mockFindClientByClientId.mockResolvedValue(client("https://spoke.example/api/hub-session/callback"));
+    expect(await accountTargetFor({ kind: "spoke", spokeId: S1, workspaceId: WS })).toEqual({
+      origin: "https://spoke.example",
+      provider: "hub",
+    });
+  });
+
+  it("a spoke with no client, a disabled one, or an http callback in production gets nothing", async () => {
+    const spoke = { kind: "spoke", spokeId: S1, workspaceId: WS } as const;
+    mockFindClientByClientId.mockResolvedValueOnce(null);
+    expect(await accountTargetFor(spoke)).toBeNull();
+    mockFindClientByClientId.mockResolvedValueOnce(client("https://spoke.example/cb", false));
+    expect(await accountTargetFor(spoke)).toBeNull();
+    process.env.NODE_ENV = "production";
+    mockFindClientByClientId.mockResolvedValueOnce(client("http://localhost:3000/api/hub-session/callback"));
+    expect(await accountTargetFor(spoke)).toBeNull();
+  });
+
+  it("an http loopback callback outside production is allowed (local development)", async () => {
+    process.env.NODE_ENV = "development";
+    mockFindClientByClientId.mockResolvedValue(client("http://localhost:3000/api/hub-session/callback"));
+    expect(await accountTargetFor({ kind: "spoke", spokeId: S1, workspaceId: WS })).toEqual({
+      origin: "http://localhost:3000",
+      provider: "hub",
+    });
+  });
+});
+
+describe("inviteSenderAddress — every completion email's sender", () => {
+  it.each([
+    [{ AILK_DELIVERABLE_EMAIL_FROM: "a@x.example", AILK_LEAD_NOTIFICATION_FROM: "b@x.example" }],
+    [{ AILK_DELIVERABLE_EMAIL_FROM: "", AILK_LEAD_NOTIFICATION_FROM: "b@x.example" }],
+    [{}],
+  ])("answers what deliverableSenderAddress answers for %j", (env) => {
+    delete process.env.AILK_DELIVERABLE_EMAIL_FROM;
+    delete process.env.AILK_LEAD_NOTIFICATION_FROM;
+    Object.assign(process.env, env);
+    expect(inviteSenderAddress()).toBe(deliverableSenderAddress());
+  });
+});
+
+describe("magnetCompletionWithinBudget — a slow read never holds the 201", () => {
+  it("answers null once the budget passes", async () => {
+    jest.useFakeTimers();
+    try {
+      mockLiveCompletionBySlug.mockReturnValue(new Promise(() => undefined));
+      const pending = magnetCompletionWithinBudget(WS, "contact", async () => null);
+      jest.advanceTimersByTime(MAGNET_COMPLETION_BUDGET_MS);
+      expect(await pending).toBeNull();
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+});
+
+describe("magnetCompletionFor", () => {
+  const target = { origin: "https://site.example", provider: "site" as const };
+  const live = (completion: string, checkoutOffering: string | null = null) =>
+    mockLiveCompletionBySlug.mockResolvedValue({
+      completion,
+      checkoutOffering,
+      title: "Contact form",
+      config: {},
+    });
+
+  it("lead, or no live magnet, is null and never resolves a target", async () => {
+    const resolveTarget = jest.fn().mockResolvedValue(target);
+    live("lead");
+    expect(await magnetCompletionFor(WS, "contact", resolveTarget)).toBeNull();
+    mockLiveCompletionBySlug.mockResolvedValue(null);
+    expect(await magnetCompletionFor(WS, "contact", resolveTarget)).toBeNull();
+    expect(resolveTarget).not.toHaveBeenCalled();
+  });
+
+  it("invite with a target answers next: invite; with none degrades to lead", async () => {
+    live("invite");
+    expect(await magnetCompletionFor(WS, "contact", async () => target)).toMatchObject({
+      next: { completion: "invite" },
+      title: "Contact form",
+      target,
+    });
+    expect(await magnetCompletionFor(WS, "contact", async () => null)).toBeNull();
+  });
+
+  it("checkout re-checks the claim and the listed offering, and never resolves a target", async () => {
+    const resolveTarget = jest.fn();
+    live("checkout", "retainer");
+    expect(await magnetCompletionFor(WS, "contact", resolveTarget)).toMatchObject({
+      next: { completion: "checkout", checkoutOffering: "retainer" },
+    });
+    expect(mockListPlanOfferings).toHaveBeenCalledWith(WS);
+    expect(resolveTarget).not.toHaveBeenCalled();
+  });
+});
+
+describe("sendInviteConfirmation — copy and link", () => {
+  it("sends the defaults with the title filled in and the prefilled sign-in link", async () => {
+    expect(
+      await sendInviteConfirmation({
+        workspaceId: WS,
+        slug: "request-quote",
+        email: "a+b@x.example",
+        locale: undefined,
+        completion: invite(),
+        now: NOW,
+      }),
+    ).toBe("sent");
+    expect(mockInviteSendCounts).toHaveBeenCalledWith(WS, "request-quote", "a+b@x.example", NOW);
+    expect(mockSendDeliverableEmail).toHaveBeenCalledWith({
+      to: "a+b@x.example",
+      fromAddress: "hello@site.example",
+      subject: "We received your Request a quote",
+      body: "Thanks — we have your Request a quote. You can follow it in your account.",
+      cta: "Track this in your account",
+      downloadLink: "https://site.example/sign-in?next=%2Faccount&email=a%2Bb%40x.example",
+    });
+  });
+
+  it("uses the magnet's completionEmail in the submitter's locale, else its default locale", async () => {
+    const config = {
+      defaultLocale: "en",
+      completionEmail: {
+        subject: { en: "Got it", fr: "Bien reçu" },
+        body: { en: "Thanks.", fr: "Merci." },
+        cta: { en: "Follow it", fr: "Suivre" },
+      },
+    };
+    await sendInviteConfirmation({
+      workspaceId: WS,
+      slug: "contact",
+      email: "a@b.example",
+      locale: "fr",
+      completion: invite(config),
+      now: NOW,
+    });
+    expect(mockSendDeliverableEmail.mock.calls[0][0]).toMatchObject({
+      subject: "Bien reçu",
+      body: "Merci.",
+      cta: "Suivre",
+    });
+    await sendInviteConfirmation({
+      workspaceId: WS,
+      slug: "contact",
+      email: "a@b.example",
+      locale: "de",
+      completion: invite(config),
+      now: NOW,
+    });
+    expect(mockSendDeliverableEmail.mock.calls[1][0]).toMatchObject({ subject: "Got it" });
+  });
+
+  it.each(["constructor", "toString", "__proto__"])(
+    "a payload locale of %s reads the default locale's copy, never an inherited member",
+    async (locale) => {
+      const config = {
+        defaultLocale: "en",
+        completionEmail: { subject: { en: "Got it" }, body: { en: "Thanks." } },
+      };
+      expect(
+        await sendInviteConfirmation({
+          workspaceId: WS,
+          slug: "contact",
+          email: "a@b.example",
+          locale,
+          completion: invite(config),
+          now: NOW,
+        }),
+      ).toBe("sent");
+      expect(mockSendDeliverableEmail.mock.calls[0][0]).toMatchObject({
+        subject: "Got it",
+        body: "Thanks.",
+      });
+    },
+  );
+
+  it("an email the hint schema refuses gets no email (no_link)", async () => {
+    expect(
+      await sendInviteConfirmation({
+        workspaceId: WS,
+        slug: "contact",
+        email: "x\r\n@y",
+        locale: undefined,
+        completion: invite(),
+        now: NOW,
+      }),
+    ).toBe("no_link");
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    [{ recipientDay: 2, siteHour: 2 }, "capped_recipient"],
+    [{ recipientDay: 1, siteHour: 51 }, "capped_site"],
+  ])("counts %j cap the send (%s)", async (counts, outcome) => {
+    mockInviteSendCounts.mockResolvedValue(counts);
+    expect(
+      await sendInviteConfirmation({
+        workspaceId: WS,
+        slug: "contact",
+        email: "a@b.example",
+        locale: undefined,
+        completion: invite(),
+        now: NOW,
+      }),
+    ).toBe(outcome);
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+  });
+
+  it("a send that fails or throws is send_failed, never a throw", async () => {
+    mockSendDeliverableEmail.mockResolvedValueOnce({ ok: false, error: { kind: "send_failed" } });
+    mockSendDeliverableEmail.mockRejectedValueOnce(new Error("down"));
+    const input = {
+      workspaceId: WS,
+      slug: "contact",
+      email: "a@b.example",
+      locale: undefined,
+      completion: invite(),
+      now: NOW,
+    };
+    expect(await sendInviteConfirmation(input)).toBe("send_failed");
+    expect(await sendInviteConfirmation(input)).toBe("send_failed");
+  });
+});
+
+// Read as text, never imported: an app does not import a package's source.
+const monorepoFs = jest.requireActual<typeof import("node:fs")>("node:fs");
+const monorepoPath = jest.requireActual<typeof import("node:path")>("node:path");
+const MONOREPO = monorepoPath.resolve(__dirname, "../../../../..");
+const SLICES = "packages/create-ailk/src/module-architecture.ts";
+// Monorepo-only: a scaffolded site carries no packages/create-ailk, and the
+// scaffold matrix runs this suite inside one (#8780), so the slice assertion
+// skips where the slice map does not exist rather than failing to load.
+const describeInMonorepo = monorepoFs.existsSync(monorepoPath.join(MONOREPO, SLICES))
+  ? describe
+  : describe.skip;
+
+describeInMonorepo("#8757 AC-3 / NFR6 — the lead path reaches only base-tree files", () => {
+  const fs = monorepoFs;
+  const path = monorepoPath;
+  const REPO = MONOREPO;
+  const read = (rel: string) => fs.readFileSync(path.join(REPO, rel), "utf8");
+  // Lazy: describe.skip still runs this body at collection time, so the slice
+  // map is read only inside a test, never while the suite loads.
+  let slicesCache: string | undefined;
+  const slicesText = () => (slicesCache ??= read(SLICES));
+  const sliceGlobs = () =>
+    [...slicesText().matchAll(/"(apps\/api\/src\/[^"]*)\/\*\*"/g)].map((m) => m[1]!);
+  const named = (rel: string) =>
+    slicesText().includes(`"${rel}"`) || sliceGlobs().some((dir) => rel.startsWith(`${dir}/`));
+
+  /** Every apps/api source file `entry` reaches through relative imports. */
+  function closure(entry: string): string[] {
+    const seen = new Set<string>();
+    const walk = (rel: string) => {
+      if (seen.has(rel)) return;
+      seen.add(rel);
+      for (const m of read(rel).matchAll(/^(?:import|export)[^;]*?from\s+["'](\.[^"']+)["']/gm)) {
+        const target = path.posix.normalize(
+          path.posix.join(path.posix.dirname(rel), m[1]!.replace(/\.js$/, ".ts")),
+        );
+        if (fs.existsSync(path.join(REPO, target))) walk(target);
+      }
+    };
+    walk(entry);
+    return [...seen];
+  }
+
+  const NEW_BASE_FILES = [
+    "apps/api/src/lib/flow-completion-store.ts",
+    "apps/api/src/services/plan-offerings.ts",
+    "apps/api/src/services/magnet-completion.ts",
+  ];
+
+  it("the three new files carry no oss: false marker and are named by no module slice", () => {
+    for (const rel of NEW_BASE_FILES) {
+      expect(read(rel).split("\n", 1)[0]).not.toMatch(/oss:\s*false/);
+      expect(named(rel)).toBe(false);
+    }
+  });
+
+  it("routes/leads/index.ts imports, directly or not, no file a module slice owns", () => {
+    const reached = closure("apps/api/src/routes/leads/index.ts");
+    for (const rel of NEW_BASE_FILES) expect(reached).toContain(rel);
+    expect(reached.filter(named)).toEqual([]);
+  });
+});

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

@@ -7,7 +7,10 @@
  * `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).
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D13, SEC-7894-6; AC-8),
+ * and the held checkout plan's release on a verified first link
+ * (#8793, spec docs/specs/8793-the-hub-s-checkout-plan-spec.md D2–D5;
+ * AC-1, AC-2, AC-6).
  *
  * Runs over `createInMemoryPrisma()`, whose `person` delegate enforces the
  * declared `(workspaceId, email)` and `(workspaceId, userId)` keys the way
@@ -36,6 +39,7 @@ import { prisma } from "../../lib/prisma.js";
 import { personContactPatchSchema } from "@working-theory/validation";
 
 import {
+  checkoutPlanKey,
   contactConfirmedFromRow,
   ensureMemberPerson,
   findOrCreatePerson,
@@ -45,6 +49,7 @@ import {
   normalizeTelephone,
   personContactFromRow,
   recordCheckoutPerson,
+  releaseHeldCheckoutPlan,
   resolveCallerBillingCustomerId,
   resolveMemberPersonId,
   setOwnPersonContact,
@@ -61,6 +66,7 @@ const store = prisma as unknown as {
   __db: Record<string, Row[]>;
   __calls: Array<{ model: string; op: string }>;
   person: Record<string, jest.Mock>;
+  lead: Record<string, jest.Mock>;
 };
 
 const WS_A1 = "wksp_00000000-0000-7000-8000-0000000000a1";
@@ -943,3 +949,228 @@ describe("setPersonPlanOffering (#7877 D8, AC-4, AC-5)", () => {
     expect(await setPersonPlanOffering(WS_A1, "person_x", "retainer")).toBe("internal_error");
   });
 });
+
+// ─── The held checkout plan (#8793) ──────────────────────────────────────────
+
+const leads = () => (store.__db["lead"] ??= []);
+const leadCalls = () => store.__calls.filter((c) => c.model === "lead");
+
+/** A spoke checkout lead on a Person, newest last unless `createdAt` says otherwise. */
+function seedMarkedLead(personId: string, row: Row = {}): Row {
+  const full: Row = {
+    id: `lead_00000000-0000-7000-8000-${String(leads().length + 700).padStart(12, "0")}`,
+    workspaceId: WS_A1,
+    personId,
+    email: "Ada@Example.com",
+    source: "web",
+    spokeCheckout: true,
+    payload: { site: "wendi", page: "checkout", offering: "wendi_retainer" },
+    createdAt: new Date(Date.UTC(2026, 1, 1 + leads().length)),
+    ...row,
+  };
+  leads().push(full);
+  return full;
+}
+
+describe("checkoutPlanKey (#8793 D4)", () => {
+  it("strips a leading <site>_ and answers a plan key, else null", () => {
+    expect(checkoutPlanKey("wendi_retainer", "wendi")).toBe("retainer");
+    expect(checkoutPlanKey("retainer", "wendi")).toBe("retainer");
+    expect(checkoutPlanKey("wendi_Not A Key!", "wendi")).toBeNull();
+    expect(checkoutPlanKey(42, "wendi")).toBeNull();
+  });
+});
+
+describe("setPersonPlanOffering's link guard (#8793 D5, AC-1, AC-6)", () => {
+  const U = "user_00000000-0000-7000-8000-000000000031";
+  const V = "user_00000000-0000-7000-8000-000000000032";
+
+  it("a guarded write never overwrites a set plan", async () => {
+    const p = seedPerson({ email: "ada@example.com", userId: U, planOffering: "premium" });
+    expect(
+      await setPersonPlanOffering(WS_A1, p["id"] as string, "x", { linkedUserId: U }),
+    ).toBe("not_found");
+    expect(people()[0]!["planOffering"]).toBe("premium");
+  });
+
+  it("a guarded write never reaches a Person linked to another user", async () => {
+    const p = seedPerson({ email: "ada@example.com", userId: U });
+    expect(
+      await setPersonPlanOffering(WS_A1, p["id"] as string, "x", { linkedUserId: V }),
+    ).toBe("not_found");
+    expect(people()[0]!["planOffering"]).toBeNull();
+  });
+
+  it("the operator's three-argument write still overwrites a set plan", async () => {
+    const p = seedPerson({ email: "ada@example.com", userId: U, planOffering: "premium" });
+    expect(await setPersonPlanOffering(WS_A1, p["id"] as string, "basic")).toBe("set");
+    expect(people()[0]!["planOffering"]).toBe("basic");
+  });
+});
+
+describe("releaseHeldCheckoutPlan (#8793 D3, AC-1)", () => {
+  const U = "user_00000000-0000-7000-8000-000000000041";
+  const EMAIL = "ada@example.com";
+  let personId: string;
+
+  const release = () => releaseHeldCheckoutPlan(WS_A1, personId, U, EMAIL);
+  const plan = () => people()[0]!["planOffering"];
+
+  beforeEach(() => {
+    personId = seedPerson({ email: EMAIL, userId: U })["id"] as string;
+  });
+
+  it("one marked lead sets its key", async () => {
+    seedMarkedLead(personId);
+    expect(await release()).toBe("set");
+    expect(plan()).toBe("retainer");
+  });
+
+  it("two marked leads naming one key, with and without the site prefix, set it", async () => {
+    seedMarkedLead(personId);
+    seedMarkedLead(personId, {
+      payload: { site: "wendi", page: "checkout", offering: "retainer" },
+    });
+    expect(await release()).toBe("set");
+    expect(plan()).toBe("retainer");
+  });
+
+  it.each([
+    ["the basic purchase is newer", 1, 2],
+    ["the retainer purchase is newer", 2, 1],
+  ])("two marked leads naming different keys are ambiguous whatever their order (%s)", async (_label, retainerDay, basicDay) => {
+    seedMarkedLead(personId, { createdAt: new Date(Date.UTC(2026, 2, retainerDay)) });
+    seedMarkedLead(personId, {
+      createdAt: new Date(Date.UTC(2026, 2, basicDay)),
+      payload: { site: "wendi", page: "checkout", offering: "wendi_basic" },
+    });
+    expect(await release()).toBe("ambiguous");
+    expect(plan()).toBeNull();
+  });
+
+  it("a marked lead under another email is ignored", async () => {
+    seedMarkedLead(personId);
+    seedMarkedLead(personId, {
+      email: "other@example.com",
+      payload: { site: "wendi", page: "checkout", offering: "wendi_basic" },
+    });
+    expect(await release()).toBe("set");
+    expect(plan()).toBe("retainer");
+  });
+
+  it("only unmarked leads are none", async () => {
+    seedMarkedLead(personId, { spokeCheckout: false });
+    expect(await release()).toBe("none");
+    expect(plan()).toBeNull();
+  });
+
+  it("only an offering that is no plan key is none", async () => {
+    seedMarkedLead(personId, {
+      payload: { site: "wendi", page: "checkout", offering: "wendi_Not A Key!" },
+    });
+    expect(await release()).toBe("none");
+    expect(plan()).toBeNull();
+  });
+
+  it("51 marked leads are ambiguous, even when they all agree", async () => {
+    for (let i = 0; i < 51; i += 1) seedMarkedLead(personId);
+    expect(await release()).toBe("ambiguous");
+    expect(plan()).toBeNull();
+  });
+
+  it("a plan already set is kept", async () => {
+    people()[0]!["planOffering"] = "premium";
+    seedMarkedLead(personId);
+    expect(await release()).toBe("kept");
+    expect(plan()).toBe("premium");
+  });
+
+  it("a failed lead read is internal_error, with no write", async () => {
+    seedMarkedLead(personId);
+    store.lead["findMany"]!.mockRejectedValueOnce(new Error("down"));
+    expect(await release()).toBe("internal_error");
+    expect(personCalls().filter((c) => c.op === "updateMany")).toHaveLength(0);
+    expect(plan()).toBeNull();
+  });
+});
+
+describe("resolveMemberPersonId releases a held plan on a fresh link only (#8793 D2, AC-2)", () => {
+  const users = () => (store.__db["user"] ??= []);
+  const U = "user_00000000-0000-7000-8000-000000000051";
+  const EMAIL = "ada@example.com";
+  const log = { warn: jest.fn() };
+  let personId: string;
+
+  const plan = () => people()[0]!["planOffering"];
+  const releaseLines = () =>
+    log.warn.mock.calls
+      .map(([fields]) => fields as Record<string, unknown>)
+      .filter((fields) => fields["event"] === "checkout-plan-release");
+
+  beforeEach(() => {
+    log.warn.mockClear();
+    personId = seedPerson({ email: EMAIL })["id"] as string;
+    seedMarkedLead(personId);
+  });
+
+  it("a verified caller's first link releases the held plan, logging nothing", async () => {
+    users().push({ id: U, email: EMAIL, emailVerified: true });
+    expect(await resolveMemberPersonId(WS_A1, U, EMAIL, log)).toBe(personId);
+    expect(people()[0]!["userId"]).toBe(U);
+    expect(plan()).toBe("retainer");
+    expect(releaseLines()).toEqual([]);
+  });
+
+  it("an unverified caller links nothing and releases nothing", async () => {
+    users().push({ id: U, email: EMAIL, emailVerified: false });
+    expect(await resolveMemberPersonId(WS_A1, U, EMAIL, log)).toBeNull();
+    expect(plan()).toBeNull();
+  });
+
+  it("a Person linked before the call is answered with no release and no lead read", async () => {
+    people()[0]!["userId"] = U;
+    expect(await resolveMemberPersonId(WS_A1, U, EMAIL, log)).toBe(personId);
+    expect(plan()).toBeNull();
+    expect(leadCalls()).toHaveLength(0);
+  });
+
+  it("a direct stamp (the inbox accept's and the consents route's path) releases nothing", async () => {
+    users().push({ id: U, email: EMAIL, emailVerified: true });
+    expect(await stampPersonUser(WS_A1, personId, U)).toBe("stamped");
+    expect(plan()).toBeNull();
+    expect(leadCalls()).toHaveLength(0);
+  });
+
+  it("a failed release still answers the Person and logs its kind only", async () => {
+    users().push({ id: U, email: EMAIL, emailVerified: true });
+    store.lead["findMany"]!.mockRejectedValueOnce(new Error("down"));
+    expect(await resolveMemberPersonId(WS_A1, U, EMAIL, log)).toBe(personId);
+    expect(plan()).toBeNull();
+    expect(releaseLines()).toEqual([
+      { event: "checkout-plan-release", outcome: "internal_error" },
+    ]);
+    const logged = JSON.stringify(log.warn.mock.calls);
+    expect(logged).not.toContain(EMAIL);
+    expect(logged).not.toContain("retainer");
+  });
+
+  it("disagreeing purchases release nothing and log ambiguous", async () => {
+    users().push({ id: U, email: EMAIL, emailVerified: true });
+    seedMarkedLead(personId, {
+      payload: { site: "wendi", page: "checkout", offering: "wendi_basic" },
+    });
+    expect(await resolveMemberPersonId(WS_A1, U, EMAIL, log)).toBe(personId);
+    expect(plan()).toBeNull();
+    expect(releaseLines()).toEqual([
+      { event: "checkout-plan-release", outcome: "ambiguous" },
+    ]);
+  });
+
+  it("a release that finds nothing to set logs nothing", async () => {
+    leads().length = 0;
+    users().push({ id: U, email: EMAIL, emailVerified: true });
+    expect(await resolveMemberPersonId(WS_A1, U, EMAIL, log)).toBe(personId);
+    expect(plan()).toBeNull();
+    expect(log.warn).not.toHaveBeenCalled();
+  });
+});