create-ailk 0.20.0 → 0.22.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/checkout-buyer.ts

@@ -1,7 +1,10 @@
 /**
  * @file checkout-buyer.ts
  * @description Resolves a signed-in user into the Checkout buyer
- * `POST /v1/checkout/sessions` pins and stamps (#6866 D3).
+ * `POST /v1/checkout/sessions` pins and stamps (#6866 D3), and — the other
+ * way round — a completed Checkout Session into its buyer's Person, the
+ * subject of the terms grant the hub webhook records (#8765 D14,
+ * `checkoutBuyerPerson`).
  *
  * A buyer is a user whose email is VERIFIED — the customer created for them
  * carries the account email, and it must never carry an unproven one — and
@@ -11,13 +14,18 @@
  * never re-points a non-null `billingCustomerId` (#6113), so a new stamped
  * customer could only be an orphan.
  *
- * Base tree (N4): imports only `verified-email.ts` and `lib/prisma.ts`, never
- * the commerce overlay's `services/subscription.ts`. The billing read selects
- * no email, so `tools/lint-email-authz.ts` has nothing to flag.
+ * Base tree (N4): imports only `verified-email.ts`, `person.ts`,
+ * `lib/site.ts`, `lib/proposal-paid-store.ts` and `lib/prisma.ts` — all base
+ * tree — never the commerce
+ * overlay's `services/subscription.ts`. The billing read selects no email, so
+ * `tools/lint-email-authz.ts` has nothing to flag.
  */
 
 import { prisma } from "../lib/prisma.js";
+import { proposalPersonId } from "../lib/proposal-paid-store.js";
+import { resolveSiteWorkspaceId } from "../lib/site.js";
 
+import { findOrCreatePerson } from "./person.js";
 import { findVerifiedEmail } from "./verified-email.js";
 
 export type CheckoutBuyer = {
@@ -70,3 +78,91 @@ export async function resolveCheckoutBuyer(
     },
   };
 }
+
+// ─── The buyer's Person (#8765 D14) ──────────────────────────────────────────
+
+/** What `checkoutBuyerPerson` reads of a signed `checkout.session.completed`. */
+export type CheckoutBuyerSession = {
+  payment_status?: string | null;
+  customer_details?: { email?: string | null } | null;
+  metadata?: Record<string, string> | null;
+};
+
+export type CheckoutBuyerPerson = { workspaceId: string; personId: string };
+
+function metadataString(
+  metadata: Record<string, string> | null | undefined,
+  key: string,
+): string | null {
+  const value: unknown = metadata?.[key];
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+/**
+ * The Person a completed Checkout Session's terms grant belongs to, or
+ * `null` (the webhook's `person_unresolved`). In order:
+ *
+ *   - a proposal session (`metadata.ailk_proposal` + `ailk_workspace`): that
+ *     piece's Person, when the proposal exists in that workspace;
+ *   - a flow checkout (`metadata.flowCheckoutId`): `flowPerson`, the Person
+ *     the webhook's Person step found or created for it — read, never
+ *     created here.
+ *     Neither falls through to the payer's typed email below;
+ *   - a signed-in buyer (`metadata.ailk_user_id`, which
+ *     `POST /v1/checkout/sessions` stamps only for a verified buyer, #6866):
+ *     the Person of that user's VERIFIED email in the site workspace, found
+ *     or created — in test mode too, since a verified email is the user's
+ *     own; a user with no verified email is `null`, never the payer's typed
+ *     email (SEC-8765-F);
+ *   - any other paid LIVE-mode session with `customer_details.email`: that
+ *     email's Person in the site workspace, found or created. A test-mode
+ *     session never takes this branch, so a sandbox cannot mint a Person
+ *     from a typed email.
+ *
+ * The site workspace is `resolveSiteWorkspaceId()`; `null` there is `null`
+ * here. Never throws — a store failure is `null`.
+ *
+ * @param session the signature-verified event's session object.
+ * @param livemode the signed event's `livemode`.
+ * @param flowPerson a flow checkout's Person, from `resolveCheckoutPerson`.
+ */
+export async function checkoutBuyerPerson(
+  session: CheckoutBuyerSession,
+  livemode: boolean,
+  flowPerson: CheckoutBuyerPerson | null = null,
+): Promise<CheckoutBuyerPerson | null> {
+  const metadata = session.metadata;
+  try {
+    const pieceId = metadataString(metadata, "ailk_proposal");
+    const proposalWorkspaceId = metadataString(metadata, "ailk_workspace");
+    if (pieceId !== null && proposalWorkspaceId !== null) {
+      const personId = await proposalPersonId(proposalWorkspaceId, pieceId);
+      return personId === null
+        ? null
+        : { workspaceId: proposalWorkspaceId, personId };
+    }
+    if (metadataString(metadata, "flowCheckoutId") !== null) return flowPerson;
+
+    const buyerUserId = metadataString(metadata, "ailk_user_id");
+    let email: string;
+    if (buyerUserId !== null) {
+      const verified = await findVerifiedEmail(buyerUserId);
+      if (!verified.ok) return null;
+      email = verified.value.email;
+    } else {
+      const payerEmail = session.customer_details?.email;
+      const paid =
+        session.payment_status === "paid" ||
+        session.payment_status === "no_payment_required";
+      if (!livemode || !paid || typeof payerEmail !== "string") return null;
+      email = payerEmail;
+    }
+
+    const workspaceId = await resolveSiteWorkspaceId();
+    if (workspaceId === null) return null;
+    const person = await findOrCreatePerson(workspaceId, { email });
+    return person.ok ? { workspaceId, personId: person.value.personId } : null;
+  } catch {
+    return null;
+  }
+}

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

@@ -34,6 +34,7 @@ import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { Prisma } from "@working-theory/database";
 import { logger } from "@working-theory/observability";
 import {
+  ACCOUNT_TERMS_PURPOSE_ID,
   consentPolicyHref,
   consentPurposeById,
   consentPurposeKind,
@@ -52,6 +53,7 @@ import {
   effectiveConsent,
   latestVisitorChoice,
   ownConsentRows,
+  personHasCheckoutGrant,
   userPlatformRows,
   type PurposeConsentState,
 } from "../lib/consent-store.js";
@@ -507,6 +509,99 @@ export async function recordPersonConsent(
   });
 }
 
+export type RecordCheckoutConsentOutcome =
+  "recorded" | "unchanged" | "purpose_unknown" | "version_changed";
+
+/**
+ * `<purposeId>@<policyVersion>` of the account terms as the registry reads
+ * them now, and that version — the only stamp a checkout grant is recorded
+ * for (SEC-8765-E). A spoke purchase's lead names the stamp it accepted
+ * (#8778); derived, never written down, so a version bump retires every
+ * older stamp.
+ */
+export function currentAccountTermsStamp(): {
+  stamp: string;
+  policyVersion: number;
+} | null {
+  const purpose = consentPurposeById(
+    SITE_CONSENT_CONFIG_DEFAULTS,
+    ACCOUNT_TERMS_PURPOSE_ID,
+  );
+  return purpose
+    ? {
+        stamp: `${purpose.id}@${purpose.policyVersion}`,
+        policyVersion: purpose.policyVersion,
+      }
+    : null;
+}
+
+/**
+ * The buyer's grant from a completed Stripe Checkout whose terms box was
+ * accepted (#8765 D14): ONE `account_terms` row, subject `person` /
+ * `personId`, source `checkout`, `sourceRef` the Checkout Session id, locale
+ * `en`, and the registry's current statement, hash and policy version — the
+ * statement the box showed once its link keys were resolved (D12).
+ *
+ * One transaction whose first statement is an advisory lock on
+ * `ailk:consent:<workspaceId>:checkout:<sessionId>`; then, when this Person
+ * already holds this session's `checkout` row, nothing is written (NFR7) — so
+ * a webhook redelivery, even after a restart, adds no row. The row goes
+ * through `recordConsent` on the transaction client. A `checkout` row is
+ * unverified (D13): it reaches only the operator's any-source reading.
+ * When the site registry's `account_terms` version is not the version the
+ * session was stamped with, nothing is written (`version_changed`): the row
+ * would otherwise record terms the box never showed.
+ *
+ * @param input.workspaceId the server-resolved workspace of the buyer's Person.
+ * @param input.personId the buyer's Person, resolved by `checkoutBuyerPerson`.
+ * @param input.sessionId the signed event's Checkout Session id.
+ * @param input.policyVersion the version the session's `ailk_terms` stamp names.
+ */
+export async function recordCheckoutConsent(input: {
+  workspaceId: string;
+  personId: string;
+  sessionId: string;
+  policyVersion: number;
+}): Promise<RecordCheckoutConsentOutcome> {
+  const config = await consentConfigForSite(input.workspaceId);
+  const purpose = consentPurposeById(config, ACCOUNT_TERMS_PURPOSE_ID);
+  if (!purpose) return "purpose_unknown";
+  if (purpose.policyVersion !== input.policyVersion) return "version_changed";
+
+  return prisma.$transaction(async (tx) => {
+    await lockConsent(
+      tx,
+      `ailk:consent:${input.workspaceId}:checkout:${input.sessionId}`,
+    );
+    if (
+      await personHasCheckoutGrant(
+        input.workspaceId,
+        input.personId,
+        purpose.id,
+        input.sessionId,
+        tx,
+      )
+    ) {
+      return "unchanged" as const;
+    }
+    await recordConsent(
+      {
+        siteId: input.workspaceId,
+        subjectType: "person",
+        subjectId: input.personId,
+        personId: input.personId,
+        source: "checkout",
+        sourceRef: input.sessionId,
+        locale: "en",
+        config,
+        consents: { [purpose.id]: true },
+      },
+      tx,
+    );
+    return "recorded" as const;
+  });
+}
+
 /**
  * One registry purpose as a settings screen reads it (D6): the wording in
  * `locale`, the policy link, and the caller's OWN state. `state` is `null`