create-ailk 0.20.0 → 0.22.0

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

@@ -81,6 +81,43 @@
  * relies on the column default. The plan rule above is unchanged: it still
  * runs after the write, from the same candidate.
  *
+ * PURCHASE EMAIL AND INBOX MESSAGE (#8757 D14). After this request's own
+ * write of a lead marked `spokeCheckout` with a Person — so never on a
+ * replay, a test-mode or relayed checkout, or a lead with no Person — the
+ * buyer gets one outbound `member` `Interaction` on that Person
+ * (`createdBy: "system:checkout"`, subject "Your purchase", no link, payload
+ * or attachment) and, fired with `void`, one `sendPurchaseConfirmationEmail`.
+ * Both name the offering only when its stripped key is one
+ * `listPlanOfferings` lists for the workspace, else "your purchase" — never
+ * the spoke-supplied `payload.offering` (SEC-8757-G) — and both bodies are
+ * stripped of control and bidi characters. The email's "Open your account"
+ * link is `options.accountOrigin` (the route resolves it, as for the invite
+ * email) plus the hub sign-in path: a marked lead is always a registered
+ * spoke's. With no origin the email goes without the link. The email is
+ * capped per recipient: more than `PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY`
+ * marked leads of this workspace for the address (any case) in the last 24
+ * hours, this one included, skips it; and per workspace: more than
+ * `PURCHASE_EMAILS_PER_SITE_PER_HOUR` marked leads in the last hour skips
+ * it. The message is still written. Neither
+ * step ever throws or changes the lead's result, and their one log line,
+ * `{ event: "checkout-purchase", step, outcome }`, names no address or
+ * offering.
+ *
+ * CHECKOUT CONSENT GRANT (#8778). After the same first write of a marked
+ * lead with a Person, a lead whose `payload.termsAccepted` equals the current
+ * `account_terms@<version>` stamp (`currentAccountTermsStamp`) — the spoke's
+ * fulfilment sends the stamp of the terms the buyer ticked in Stripe's box,
+ * else `null` — records the buyer's checkout `ConsentGrant` through #8765's
+ * `recordCheckoutConsent`: one `account_terms` row for that Person, source
+ * `checkout`, `sourceRef` the Checkout Session id (the lead's
+ * `Idempotency-Key`), at most once per Person and session. A `null` or absent
+ * value writes nothing (`consent_absent`), as does any other value
+ * (`terms_unstamped`). A replay never reaches it, and the key is left out of
+ * the replay comparison (`comparablePayload`). Never throws and never
+ * changes the lead's result; its one log line,
+ * `{ event: "checkout-consent", outcome, siteId }` (plus `errName` on
+ * `failed`), names no address or Person.
+ *
  * VISITOR LINK (#8438 D11). When the request carried a valid consent visitor
  * id (`SourceMeta.consentVisitorId`, set by the leads and flows routes from
  * `x-ailk-consent-visitor` only when it is a v4 UUID) and the submit resolved
@@ -95,12 +132,17 @@ import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 
 import type { Prisma } from "@working-theory/database";
-import { sendLeadNotification } from "@working-theory/email";
+import { sendLeadNotification, sendPurchaseConfirmationEmail } from "@working-theory/email";
 import { logger } from "@working-theory/observability";
 import {
+  accountInvitePath,
+  isContactLeadSource,
   LEAD_SITE_MARKER_KEY,
   leadInputSchema,
+  PURCHASE_EMAIL_DEFAULTS,
+  PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY,
   planOfferingSchema,
+  stripPlainText,
 } from "@working-theory/validation";
 
 import { writeLeadFallback } from "../lib/file-fallback.js";
@@ -108,7 +150,12 @@ import { appendLeadRecord } from "../lib/lead-capture-store.js";
 import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
 import { prisma } from "../lib/prisma.js";
 
-import { linkConsentVisitor } from "./consent.js";
+import {
+  currentAccountTermsStamp,
+  linkConsentVisitor,
+  recordCheckoutConsent,
+  type RecordCheckoutConsentOutcome,
+} from "./consent.js";
 import { enrichLead } from "./enrichment-shim.js";
 import {
   findOrCreatePerson,
@@ -117,6 +164,7 @@ import {
   setPersonPlanOffering,
 } from "./person.js";
 import type { LeadContact, PersonContact } from "./person.js";
+import { listPlanOfferings } from "./plan-offerings.js";
 import { requestConfirmSupersedesNotification } from "./request-confirm.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -178,6 +226,12 @@ export type RouteLeadOptions = {
    * `payload` stays the raw answers.
    */
   contact?: LeadContact;
+  /**
+   * Where the buyer's account lives (#8757 D14): the origin the purchase
+   * email's "Open your account" link starts sign-in on, resolved by the route
+   * from the caller, never the body. Read for a marked checkout lead only.
+   */
+  accountOrigin?: string;
 };
 
 export type RouteLeadResult =
@@ -252,15 +306,46 @@ async function findLeadByKey(
   })) as KeyedRow | null;
 }
 
+/**
+ * A contact lead's `payload.consent` is written by the route on every request
+ * (#8730 D3) — its `acceptedAt` is that request's receive time — so it is left
+ * out of the replay comparison; every key the client sent still counts.
+ *
+ * A checkout lead's `payload.termsAccepted` (#8778) is left out too: a spoke
+ * updated between a stored attempt and Stripe's redelivery sends the key the
+ * stored body lacks, and a conflict there would fail every retry. A replay
+ * writes no grant, so the key decides nothing on one.
+ */
+function comparablePayload(payload: unknown, source: string): unknown {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return payload;
+  }
+  const record = payload as Record<string, unknown>;
+  if (isContactLeadSource(source)) {
+    const { consent: _serverWritten, ...rest } = record;
+    return rest;
+  }
+  if (record["page"] === "checkout") {
+    const { termsAccepted: _addedByUpdate, ...rest } = record;
+    return rest;
+  }
+  return payload;
+}
+
 /**
  * A stored row is a replay only when it carries this request's exact `email`
  * and `source` and a deep-equal `payload` (key order ignored, SEC-7869-3);
- * any other row is a conflict (#7869 D4).
+ * any other row is a conflict (#7869 D4). A contact lead's server-written
+ * `payload.consent` is not compared (#8730), nor a checkout lead's
+ * `payload.termsAccepted` (#8778).
  */
 function classifyKeyedRow(row: KeyedRow, input: SubmitInput): KeyedOutcome {
   return row.email === input.email &&
     row.source === input.source &&
-    isDeepStrictEqual(row.payload, input.payload)
+    isDeepStrictEqual(
+      comparablePayload(row.payload, row.source),
+      comparablePayload(input.payload, input.source),
+    )
     ? { kind: "replay", id: row.id }
     : { kind: "conflict" };
 }
@@ -381,6 +466,14 @@ function checkoutPlanCandidate(
   return { offering, site };
 }
 
+/** The candidate's offering minus a leading `<site>_` (#7877 D10). */
+function stripSitePrefix(candidate: { offering: string; site: string }): string {
+  const prefix = `${candidate.site}_`;
+  return candidate.offering.startsWith(prefix)
+    ? candidate.offering.slice(prefix.length)
+    : candidate.offering;
+}
+
 /**
  * Set the Person's plan from a qualifying checkout lead (#7877 D10). Never
  * throws and never changes the lead's result; logs the outcome kind and the
@@ -391,10 +484,7 @@ async function applyCheckoutPlan(
   personId: string,
   candidate: { offering: string; site: string },
 ): Promise<void> {
-  const prefix = `${candidate.site}_`;
-  const offering = candidate.offering.startsWith(prefix)
-    ? candidate.offering.slice(prefix.length)
-    : candidate.offering;
+  const offering = stripSitePrefix(candidate);
   let outcome: "set" | "skipped" | "failed";
   // The operator's PUT accepts the same keys (`planOfferingSchema`).
   if (!planOfferingSchema.safeParse(offering).success) {
@@ -412,12 +502,242 @@ async function applyCheckoutPlan(
   else logger.info(line, "checkout plan");
 }
 
+// ─── Purchase email and Inbox message (#8757 D14) ────────────────────────────
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+/**
+ * A workspace's purchase emails per hour, whatever the address (SEC review of
+ * #8770, M1): a marked lead's inputs are all the spoke's own, so the
+ * per-recipient cap alone would let a spoke key mail any number of distinct
+ * addresses. The invite email's per-site cap
+ * (`INVITE_EMAILS_PER_SITE_PER_HOUR`) has the same value.
+ */
+const PURCHASE_EMAILS_PER_SITE_PER_HOUR = 50;
+const GENERIC_PURCHASE_BODY = "Thanks for your purchase.";
+/** How long the lead write waits on the offering's name before it says "your purchase". */
+const OFFERING_NAME_BUDGET_MS = 1500;
+/**
+ * Stripe's special-case currencies, whose minor units differ from the ISO
+ * decimals `Intl` formats with: the amount is left out rather than misstated.
+ */
+const AMOUNT_UNSTATED_CURRENCIES = new Set(["HUF", "ISK", "TWD", "UGX"]);
+
+/**
+ * The purchase email's sender: every completion email's rule
+ * (`AILK_DELIVERABLE_EMAIL_FROM`, else `AILK_LEAD_NOTIFICATION_FROM`; `||`, so
+ * "" names none), the same as `magnet-completion.ts`'s `inviteSenderAddress`,
+ * kept here so the lead path does not load that module's graph.
+ */
+function purchaseSenderAddress(): string | undefined {
+  return (
+    process.env.AILK_DELIVERABLE_EMAIL_FROM ||
+    process.env.AILK_LEAD_NOTIFICATION_FROM ||
+    undefined
+  );
+}
+
+type PurchaseStep = "message" | "email";
+
+function logPurchase(siteId: string, step: PurchaseStep, outcome: string): void {
+  const line = { event: "checkout-purchase", step, outcome, siteId };
+  if (outcome === "failed") logger.error(line, "checkout purchase step failed");
+  else logger.info(line, "checkout purchase step");
+}
+
+/**
+ * The offering's listed name, or `null` when its stripped key is not listed,
+ * the read fails, or it outlasts `OFFERING_NAME_BUDGET_MS`.
+ */
+async function listedOfferingName(siteId: string, offering: string): Promise<string | null> {
+  let timer: NodeJS.Timeout | undefined;
+  const budget = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), OFFERING_NAME_BUDGET_MS);
+  });
+  try {
+    const listed = await Promise.race([listPlanOfferings(siteId), budget]);
+    if (!Array.isArray(listed)) return null;
+    const name = listed.find((item) => item.key === offering)?.name;
+    const clean = name === undefined ? "" : stripPlainText(name).trim();
+    return clean === "" ? null : clean;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** `amountTotal` (minor units) in `currency`, formatted, or `null` when either is unusable. */
+function formattedAmount(amountTotal: unknown, currency: unknown): string | null {
+  if (typeof amountTotal !== "number" || !Number.isInteger(amountTotal) || amountTotal <= 0) {
+    return null;
+  }
+  if (typeof currency !== "string" || !/^[A-Za-z]{3}$/.test(currency)) return null;
+  const code = currency.toUpperCase();
+  if (AMOUNT_UNSTATED_CURRENCIES.has(code)) return null;
+  try {
+    const format = new Intl.NumberFormat("en", { style: "currency", currency: code });
+    const digits = format.resolvedOptions().maximumFractionDigits ?? 2;
+    return format.format(amountTotal / 10 ** digits);
+  } catch {
+    return null;
+  }
+}
+
+/** The one plain-text body the email and the message share. */
+function purchaseBody(name: string | null, amount: string | null): string {
+  const sentence =
+    name === null ? GENERIC_PURCHASE_BODY : PURCHASE_EMAIL_DEFAULTS.body.replaceAll("{offering}", name);
+  return stripPlainText(amount === null ? sentence : `${sentence} Total: ${amount}.`);
+}
+
+/** The purchase email, capped per recipient (D14). Never throws; fired with `void`. */
+async function sendPurchaseEmail(
+  input: SubmitInput,
+  body: string,
+  accountOrigin: string | undefined,
+): Promise<void> {
+  let outcome: string;
+  try {
+    const recent = await prisma.lead.count({
+      where: {
+        workspaceId: input.siteId,
+        spokeCheckout: true,
+        email: { equals: input.email, mode: "insensitive" },
+        createdAt: { gte: new Date(Date.now() - DAY_MS) },
+      },
+    });
+    const siteHour = await prisma.lead.count({
+      where: {
+        workspaceId: input.siteId,
+        spokeCheckout: true,
+        createdAt: { gte: new Date(Date.now() - HOUR_MS) },
+      },
+    });
+    const fromAddress = purchaseSenderAddress();
+    if (recent > PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY) {
+      outcome = "capped_recipient";
+    } else if (siteHour > PURCHASE_EMAILS_PER_SITE_PER_HOUR) {
+      outcome = "capped_site";
+    } else if (!fromAddress) {
+      outcome = "sender_unconfigured";
+    } else {
+      let accountLink: string | undefined;
+      if (accountOrigin !== undefined) {
+        try {
+          accountLink = accountOrigin + accountInvitePath("hub", input.email);
+        } catch {
+          // An address the sign-in hint refuses: the email goes without the link.
+        }
+      }
+      const result = await sendPurchaseConfirmationEmail({
+        to: input.email,
+        fromAddress,
+        subject: PURCHASE_EMAIL_DEFAULTS.subject,
+        body,
+        cta: PURCHASE_EMAIL_DEFAULTS.cta,
+        ...(accountLink !== undefined && { accountLink }),
+      });
+      outcome = result.ok ? "sent" : "failed";
+    }
+  } catch {
+    outcome = "failed";
+  }
+  logPurchase(input.siteId, "email", outcome);
+}
+
+/**
+ * The buyer's Inbox message and purchase email for a marked checkout lead
+ * just written (D14). Never throws and never changes the lead's result.
+ */
+async function recordPurchase(
+  input: SubmitInput,
+  personId: string,
+  candidate: { offering: string; site: string },
+  accountOrigin: string | undefined,
+): Promise<void> {
+  // One guard around the whole step: it runs inside `routeLead`'s persist
+  // `try`, where a throw after the row is written would be read as a failed
+  // write and the lead captured a second time.
+  let body: string;
+  try {
+    const name = await listedOfferingName(input.siteId, stripSitePrefix(candidate));
+    body = purchaseBody(name, formattedAmount(input.payload["amountTotal"], input.payload["currency"]));
+  } catch {
+    logPurchase(input.siteId, "message", "failed");
+    return;
+  }
+  try {
+    await prisma.interaction.create({
+      data: {
+        workspaceId: input.siteId,
+        personId,
+        channel: "member",
+        direction: "outbound",
+        subject: PURCHASE_EMAIL_DEFAULTS.subject,
+        body,
+        createdBy: "system:checkout",
+      },
+    });
+    logPurchase(input.siteId, "message", "written");
+  } catch {
+    logPurchase(input.siteId, "message", "failed");
+  }
+  void sendPurchaseEmail(input, body, accountOrigin);
+}
+
+/**
+ * The buyer's checkout consent grant for a marked checkout lead just written
+ * (#8778). Never throws and never changes the lead's result.
+ */
+async function recordSpokeCheckoutConsent(
+  input: SubmitInput,
+  personId: string,
+  sessionId: string,
+): Promise<void> {
+  const accepted = input.payload["termsAccepted"];
+  let outcome:
+    | RecordCheckoutConsentOutcome
+    | "consent_absent"
+    | "terms_unstamped"
+    | "failed";
+  let errName: string | undefined;
+  try {
+    const expected = currentAccountTermsStamp();
+    if (accepted === undefined || accepted === null) {
+      outcome = "consent_absent";
+    } else if (expected === null || accepted !== expected.stamp) {
+      outcome = "terms_unstamped";
+    } else {
+      outcome = await recordCheckoutConsent({
+        workspaceId: input.siteId,
+        personId,
+        sessionId,
+        policyVersion: expected.policyVersion,
+      });
+    }
+  } catch (err) {
+    // The error's class only (a Prisma error's message can carry values).
+    outcome = "failed";
+    errName = err instanceof Error ? err.name : "UnknownError";
+  }
+  const line = {
+    event: "checkout-consent",
+    outcome,
+    siteId: input.siteId,
+    ...(errName !== undefined && { errName }),
+  };
+  if (outcome === "failed") logger.error(line, "checkout terms grant failed");
+  else logger.info(line, "checkout terms grant");
+}
+
 async function persistToDb(
   input: RouteLeadInput,
   idempotencyKey?: string,
   viaSpoke = false,
   relayed = false,
   contact?: LeadContact,
+  accountOrigin?: string,
 ): Promise<PersistResult> {
   if (input.kind === "submit") {
     const personId = await resolveLeadPersonId(input, contact);
@@ -473,6 +793,14 @@ async function persistToDb(
     // #7877 D10 — only after THIS request's own write, so a replay sets nothing.
     if (candidate !== null && personId !== null) {
       await applyCheckoutPlan(input, personId, candidate);
+      // #8757 D14 — the marked lead only: live, unrelayed, this write.
+      if (spokeCheckout) {
+        await recordPurchase(input, personId, candidate, accountOrigin);
+        // #8778 — a marked lead's key is its live Checkout Session id.
+        if (idempotencyKey !== undefined) {
+          await recordSpokeCheckoutConsent(input, personId, idempotencyKey);
+        }
+      }
     }
     return { ok: true, id: row.id, source: "db", skipEmail: false, personId };
   }
@@ -836,6 +1164,7 @@ export async function routeLead(
       sourceMeta.viaSpoke === true,
       sourceMeta.relayed === true,
       input.kind === "submit" ? options.contact : undefined,
+      input.kind === "submit" ? options.accountOrigin : undefined,
     );
     // #7869 D5 — a lost race answers like the lookup above: no capture
     // record, no notification.

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

@@ -0,0 +1,242 @@
+/**
+ * What happens after someone submits a magnet (#8757, spec
+ * docs/specs/8757-a-per-magnet-completion-setting-spec.md D6).
+ *
+ * `POST /v1/leads/submit` calls `magnetCompletionFor` after a `flow:<slug>`
+ * lead is written to the database. It reads the LIVE magnet at that slug
+ * (`lib/flow-completion-store.ts`) and answers the 201's `next`:
+ *
+ *   - `lead`, a missing or a draft magnet → `null` (the 201 is unchanged);
+ *   - `invite` → `{ completion: "invite" }`, only where the caller has an
+ *     account to sign in to (`accountTargetFor`); else `null` (NFR4);
+ *   - `checkout` → `{ completion: "checkout", checkoutOffering }`, re-checked
+ *     at submit time (SEC-8757-E): the `commerce` claim must read `claimed`
+ *     and the offering must still be listed. Anything else is `null`.
+ *
+ * `sendInviteConfirmation` is the invite email: one `sendDeliverableEmail` to
+ * the lead's address whose one link (`downloadLink`, labelled by `cta`) starts
+ * sign-in with that address prefilled. It never signs anyone in (NFR2). Two
+ * caps run first, counted in the database (SEC-8757-A, SEC-8757-B): one email
+ * per recipient per magnet per day — which also stops the second email of an
+ * unkeyed double submit — and fifty per magnet per hour. A capped send still
+ * leaves the page's link in place. Every outcome is one
+ * `{ event: "magnet-invite", outcome }` line that never names the address.
+ *
+ * Where the link points (`accountTargetFor`): a keyless caller gets
+ * `FRONTEND_URL`'s origin with the site sign-in path, and only on a build that
+ * has an account area (`workspace` or `multi-tenant`); a spoke gets the origin
+ * of its enabled sign-in client's registered callback with the hub sign-in
+ * path, `https:` unless `NODE_ENV` is `development` (SEC-8757-I). The origin is never
+ * taken from the request.
+ *
+ * Base tree (SEC-8757-D, NFR6): no `oss: false` marker and no `MODULE_SLICES`
+ * entry, and it imports none — the never-gate lead route imports it. So the
+ * sender is resolved here (`inviteSenderAddress`, the same rule as
+ * `deliverable-fulfillment.ts`'s `deliverableSenderAddress`, which
+ * `module-architecture.ts` holds out of a slice only until #5364), and
+ * `@working-theory/email` — the templates the lead route otherwise never
+ * loads — is imported on the first send, not with the route.
+ */
+import { logger } from "@working-theory/observability";
+import {
+  accountInvitePath,
+  completionEmailSchema,
+  INVITE_EMAIL_DEFAULTS,
+  INVITE_EMAILS_PER_RECIPIENT_PER_DAY,
+  INVITE_EMAILS_PER_SITE_PER_HOUR,
+  type AccountInviteProvider,
+  type CompletionEmailConfig,
+  type LeadSubmitNext,
+} from "@working-theory/validation";
+
+import { isModuleEnabled } from "../config/modules.js";
+import { inviteSendCounts, liveCompletionBySlug } from "../lib/flow-completion-store.js";
+import { findClientByClientId } from "../lib/hub-sign-in-store.js";
+import { resolveCommerceClaim } from "../lib/require-commerce-claim.js";
+
+import { listPlanOfferings } from "./plan-offerings.js";
+import type { CallerSite } from "./public-site-resolver.js";
+
+/**
+ * The invite email's sender: `AILK_DELIVERABLE_EMAIL_FROM`, else
+ * `AILK_LEAD_NOTIFICATION_FROM` — every completion email's sender. `||`, not
+ * `??`: an env var set to "" names no sender.
+ */
+export function inviteSenderAddress(): string | undefined {
+  return (
+    process.env.AILK_DELIVERABLE_EMAIL_FROM ||
+    process.env.AILK_LEAD_NOTIFICATION_FROM ||
+    undefined
+  );
+}
+
+/** Where an account link starts sign-in: the site's origin and its sign-in path. */
+export interface AccountTarget {
+  origin: string;
+  provider: AccountInviteProvider;
+}
+
+/** The origin of `raw` when it is `https:` (or `http:` in development), else `null`. */
+function linkOrigin(raw: string | undefined): string | null {
+  if (!raw) return null;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol === "https:") return url.origin;
+  if (url.protocol === "http:" && process.env.NODE_ENV === "development") return url.origin;
+  return null;
+}
+
+/** Where the caller's account link points, or `null` when it has nowhere to sign in. */
+export async function accountTargetFor(
+  caller: Exclude<CallerSite, { kind: "refused" }>,
+): Promise<AccountTarget | null> {
+  if (caller.kind === "spoke") {
+    const client = await findClientByClientId(caller.spokeId);
+    if (!client?.enabled) return null;
+    const origin = linkOrigin(client.redirectUris[0]);
+    return origin === null ? null : { origin, provider: "hub" };
+  }
+  // A build with no account area has no `/account` to land on.
+  if (!isModuleEnabled("workspace") && !isModuleEnabled("multi-tenant")) return null;
+  const origin = linkOrigin(process.env.FRONTEND_URL);
+  return origin === null ? null : { origin, provider: "site" };
+}
+
+/** A submit's completion: the 201's `next`, plus what the invite email needs. */
+export interface MagnetCompletion {
+  next: LeadSubmitNext;
+  title: string;
+  config: unknown;
+  target: AccountTarget | null;
+}
+
+/**
+ * How long the anonymous submit waits on `magnetCompletionFor` before it
+ * answers without `next`: the lead is already written, and a slow licence or
+ * content read must not turn it into a client-side timeout and a resubmit.
+ */
+export const MAGNET_COMPLETION_BUDGET_MS = 1500;
+
+/** `magnetCompletionFor`, or `null` once `MAGNET_COMPLETION_BUDGET_MS` has passed. */
+export async function magnetCompletionWithinBudget(
+  ...args: Parameters<typeof magnetCompletionFor>
+): Promise<MagnetCompletion | null> {
+  let timer: NodeJS.Timeout | undefined;
+  const budget = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), MAGNET_COMPLETION_BUDGET_MS);
+  });
+  try {
+    return await Promise.race([magnetCompletionFor(...args), budget]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The completion of a `flow:<slug>` lead just written to `workspaceId`, or `null` for `lead`. */
+export async function magnetCompletionFor(
+  workspaceId: string,
+  slug: string,
+  resolveTarget: () => Promise<AccountTarget | null>,
+): Promise<MagnetCompletion | null> {
+  const magnet = await liveCompletionBySlug(workspaceId, slug);
+  if (magnet === null) return null;
+  const { title, config } = magnet;
+  if (magnet.completion === "invite") {
+    const target = await resolveTarget();
+    return target === null ? null : { next: { completion: "invite" }, title, config, target };
+  }
+  if (magnet.completion === "checkout") {
+    // A claim or offerings read that fails is never a pass: it degrades to `lead`.
+    if ((await resolveCommerceClaim()) !== "claimed") return null;
+    const offerings = await listPlanOfferings(workspaceId);
+    if (!Array.isArray(offerings)) return null;
+    const offering = magnet.checkoutOffering;
+    if (!offerings.some((item) => item.key === offering)) return null;
+    return { next: { completion: "checkout", checkoutOffering: offering }, title, config, target: null };
+  }
+  return null;
+}
+
+export type InviteOutcome =
+  | "sent"
+  | "send_failed"
+  | "capped_recipient"
+  | "capped_site"
+  | "sender_unconfigured"
+  | "no_link";
+
+export interface InviteConfirmationInput {
+  workspaceId: string;
+  slug: string;
+  email: string;
+  locale: string | undefined;
+  completion: MagnetCompletion;
+  now: Date;
+}
+
+const fill = (template: string, title: string) => template.replaceAll("{title}", title);
+
+/**
+ * `copy[locale] ?? copy[defaultLocale]`, the completion email's own
+ * resolution. Own keys only: `locale` comes from the anonymous payload, and
+ * `"constructor"` must not read an inherited member.
+ */
+function resolveCopy(copy: Record<string, string>, locale: string, defaultLocale: string) {
+  const own = (key: string) => (Object.hasOwn(copy, key) ? copy[key] : undefined);
+  return own(locale) ?? own(defaultLocale) ?? Object.values(copy)[0] ?? "";
+}
+
+function declaredCopy(config: unknown): { copy: CompletionEmailConfig; defaultLocale: string } | null {
+  if (typeof config !== "object" || config === null) return null;
+  const record = config as { completionEmail?: unknown; defaultLocale?: unknown };
+  const parsed = completionEmailSchema.safeParse(record.completionEmail);
+  if (!parsed.success) return null;
+  const defaultLocale = typeof record.defaultLocale === "string" ? record.defaultLocale : "en";
+  return { copy: parsed.data, defaultLocale };
+}
+
+/**
+ * The invite email (D6). Never throws and never names the address in a log;
+ * the caller fires it with `void` after a first, unreplayed write.
+ */
+export async function sendInviteConfirmation(input: InviteConfirmationInput): Promise<InviteOutcome> {
+  const outcome = await send().catch(() => "send_failed" as const);
+  logger.info({ event: "magnet-invite", outcome }, "[magnet-completion] invite email");
+  return outcome;
+
+  async function send(): Promise<InviteOutcome> {
+    const { workspaceId, slug, email, locale, completion, now } = input;
+    if (completion.target === null) return "no_link";
+    const counts = await inviteSendCounts(workspaceId, slug, email, now);
+    if (counts.recipientDay > INVITE_EMAILS_PER_RECIPIENT_PER_DAY) return "capped_recipient";
+    if (counts.siteHour > INVITE_EMAILS_PER_SITE_PER_HOUR) return "capped_site";
+    const fromAddress = inviteSenderAddress();
+    if (!fromAddress) return "sender_unconfigured";
+
+    let downloadLink: string;
+    try {
+      downloadLink = completion.target.origin + accountInvitePath(completion.target.provider, email);
+    } catch {
+      return "no_link";
+    }
+    const declared = declaredCopy(completion.config);
+    const lang = locale ?? declared?.defaultLocale ?? "en";
+    const subject = declared
+      ? resolveCopy(declared.copy.subject, lang, declared.defaultLocale)
+      : fill(INVITE_EMAIL_DEFAULTS.subject, completion.title);
+    const body = declared
+      ? resolveCopy(declared.copy.body, lang, declared.defaultLocale)
+      : fill(INVITE_EMAIL_DEFAULTS.body, completion.title);
+    const cta = declared?.copy.cta
+      ? resolveCopy(declared.copy.cta, lang, declared.defaultLocale)
+      : INVITE_EMAIL_DEFAULTS.cta;
+
+    const { sendDeliverableEmail } = await import("@working-theory/email");
+    const result = await sendDeliverableEmail({ to: email, fromAddress, subject, body, cta, downloadLink });
+    return result.ok ? "sent" : "send_failed";
+  }
+}