create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/services/deliverable-fulfillment.ts

@@ -1,755 +0,0 @@
-/**
- * @file deliverable-fulfillment.ts
- * @description The deliverable-fulfillment service (#3961 D3/D4/D5/D7;
- * extended #3998 D1/D3/D5; extended FEAT-074 U4b, #4718 D4).
- *
- * NOT marked `oss: false` and NOT in signal-collectors's `ownedFiles`
- * (module-architecture.ts), despite D-48/D6 placing this file with
- * signal-collectors — `services/recommender-capture.ts` imports it directly
- * and is itself reached from `server.ts` by a plain, unconditional static
- * import today (commerce/#5364 has not yet landed the gate around it).
- * Marking or excluding this file broke both the OSS-strip and the create-ailk
- * starter snapshot for EVERY module, not just signal-collectors (spec §5.4
- * escalation boundary; see module-architecture.ts's comment on this file).
- * Revert once #5364 lands.
- *
- * `fulfillDeliverable` is the one entry point, called from flow-engine's
- * completion branch after `routeLead` succeeds and only when the session's
- * `configSnapshot` carries a `deliverables` block (D4 — the block is opt-in
- * per flow; flow-engine.ts itself gates the call on the block's presence).
- * Resolves the request-local segment against the flow's `deliverables`
- * asset map (D3), mints a capability-token grant (D5), and sends the
- * lead-facing delivery email (D7) — every non-happy path is a log-and-skip,
- * never a throw, so a caller that DOES let an exception escape (a DB error)
- * is the only case its own wrapping needs to catch (flow-engine.ts's D4
- * "the submission still succeeds" posture).
- *
- * An `entry.assetKey` prefixed `playbook:` (FEAT-074 U4b, #4718 D4) is a
- * VIRTUAL asset — a per-lead COMPILED `PlaybookInstance`, never an
- * operator-uploaded `DeliverableAsset` row — so it skips the asset lookup
- * entirely, requires at least one instance for `(siteId, leadId,
- * experimentKey)` (else `playbook_missing`, the `asset_missing` posture's
- * virtual-asset twin), and mints the grant with `assetId = entry.assetKey`
- * itself (the column is a plain string with no `@relation`, D4 — no schema
- * change). Every other `assetKey` follows the unchanged operator-uploaded
- * path below.
- *
- * `resendDeliverableGrant` and `listSendlessGrants` (#3998) are the
- * `deliverable:resend` CLI's two modes. Both share the extracted post-mint
- * "resolve copy → build link → send → stamp + log" tail with
- * `fulfillDeliverable` (#3998 D5) — the ONE place a delivery email is ever
- * sent and its outcome stamped. The resend path never mints a grant (#3998
- * D3) — it looks the grant up and reuses its id, producing a byte-identical
- * download link to the original.
- *
- * PII boundary: logs carry only `{ siteId, flowSlug, sessionId, outcome }` —
- * never email/asset-key/copy values (mirrors flow-engine.ts's + abandon-
- * email.ts's boundary).
- *
- * #6310 D1/D2/D4/D5/D15 — a non-`playbook:` `assetKey` now resolves against
- * the workspace-scoped `Asset` store FIRST, via the named boundary
- * `lib/deliverable-asset-store.ts` (never a raw `prisma.asset` call here —
- * that access is banned by architecture.yaml's tenant-scope
- * `forbidden_pattern`), falling back to the LEGACY `DeliverableAsset` store
- * on a miss (D3 — existing rows keep delivering, unmigrated). The workspace
- * is read from the magnet's own `FlowDefinition.workspaceId`, ONE
- * `findUnique` issued only on this branch (never for a `playbook:` key, and
- * never before the `no_entry` exit) — a `null`/absent value skips the
- * `Asset` lookup entirely and falls straight to the legacy arm, never
- * guessing a workspace (D5, mirroring #6155 D3's posture). The grant is
- * minted with `workspaceId` ONLY on the `Asset` arm — the same value that
- * authorized the resolution — restoring the download route's serve-time
- * tenancy re-check for this new grant class (D15).
- */
-
-import { sendDeliverableEmail } from "@working-theory/email";
-import { logger } from "@working-theory/observability";
-import { flowConfigSchema, type FlowConfig } from "@working-theory/validation";
-
-import { findDeliverableAssetIdByKey } from "../lib/deliverable-asset-store.js";
-import { prisma } from "../lib/prisma.js";
-import { resolveWorkspaceIdForAlias } from "../lib/site.js";
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-export type FulfillDeliverableInput = {
-  siteId: string;
-  flowSlug: string;
-  configSnapshot: FlowConfig;
-  /** The request-local segment (#3959 D3) — undefined for an N=1 flow. */
-  segment?: string;
-  leadId: string;
-  sessionId: string;
-  email: string;
-  locale: string;
-};
-
-type DeliverableAssetRow = {
-  id: string;
-  siteId: string;
-  key: string;
-};
-
-// Derived from the schema type (not hand-rolled) so it never drifts from
-// `deliverableAssetMapEntrySchema`'s actual Zod-inferred optional shape.
-type DeliverableEntry = NonNullable<
-  FlowConfig["deliverables"]
->["assets"][number];
-
-// Same derivation discipline for the copy block (#3998) — never hand-rolled,
-// so it can never drift from `deliverableCopySchema`'s actual shape.
-type DeliverableCopy = NonNullable<FlowConfig["deliverables"]>["copy"];
-
-// ─── PII-safe outcome logging (mirrors abandon-email.ts's logOutcome) ──────────
-
-type FulfillmentOutcome =
-  | "sent"
-  | "no_entry"
-  | "asset_missing"
-  | "playbook_missing"
-  | "sender_unconfigured"
-  | "send_failed";
-
-// The exact post-mint subset (#3998 D1) — derived from FulfillmentOutcome,
-// not a second hand-rolled union, so it can never drift. A grant only ever
-// exists for one of these three; `no_entry`/`asset_missing`/
-// `playbook_missing` (FEAT-074 U4b, #4718 — the virtual-asset analog of
-// `asset_missing`) all occur before a grant is minted and are never
-// stamped.
-type PostMintOutcome = Extract<
-  FulfillmentOutcome,
-  "sent" | "send_failed" | "sender_unconfigured"
->;
-
-const OUTCOME_MESSAGE: Record<FulfillmentOutcome, string> = {
-  sent: "[deliverable-fulfillment] delivery email sent",
-  no_entry: "[deliverable-fulfillment] no matching asset-map entry — skipped",
-  asset_missing: "[deliverable-fulfillment] asset row not found — skipped",
-  playbook_missing:
-    "[deliverable-fulfillment] no PlaybookInstance for this lead/experiment — skipped",
-  sender_unconfigured:
-    "[deliverable-fulfillment] no from-address configured — skipped",
-  send_failed: "[deliverable-fulfillment] email send failed",
-};
-
-function logOutcome(
-  input: { siteId: string; flowSlug: string; sessionId: string },
-  outcome: FulfillmentOutcome,
-): void {
-  logger.info(
-    {
-      siteId: input.siteId,
-      flowSlug: input.flowSlug,
-      sessionId: input.sessionId,
-      outcome,
-    },
-    OUTCOME_MESSAGE[outcome],
-  );
-}
-
-// ─── D7 — copy resolution ───────────────────────────────────────────────────────
-
-/**
- * `copy[locale] ?? copy[defaultLocale]` (D7). `defaultLocale` is a required
- * key on every `deliverables.copy` LocalizedString the `deliverablesSchema`
- * superRefine walk enforces, so the final fallback is always resolvable
- * against a schema-valid config.
- */
-function resolveCopy(
-  copy: Record<string, string>,
-  locale: string,
-  defaultLocale: string,
-): string {
-  return copy[locale] ?? copy[defaultLocale] ?? "";
-}
-
-// ─── D3 — segment → entry resolution ────────────────────────────────────────────
-
-/**
- * `entry = assets.find(a => a.segment === segment) ?? assets.find(a =>
- * a.segment === undefined)` (D3) — the default entry, if declared, is the
- * fallback for a derivation miss; a map with segment entries but no default
- * relies on the #3959 band map's totality guarantee for the happy path.
- */
-function resolveEntry(
-  assets: DeliverableEntry[],
-  segment: string | undefined,
-): DeliverableEntry | undefined {
-  return (
-    assets.find((a) => a.segment === segment) ??
-    assets.find((a) => a.segment === undefined)
-  );
-}
-
-// ─── FEAT-074 U4b (#4718) D4 — the `playbook:` virtual asset ────────────────
-
-const PLAYBOOK_ASSET_PREFIX = "playbook:";
-
-/**
- * `entry.assetKey`'s `experimentKey` suffix when it names the `playbook:`
- * virtual asset (spec D4), else `undefined` — the one branch point every
- * other `assetKey` (an operator-uploaded `DeliverableAsset` key) never
- * takes.
- */
-function playbookExperimentKey(assetKey: string): string | undefined {
-  return assetKey.startsWith(PLAYBOOK_ASSET_PREFIX)
-    ? assetKey.slice(PLAYBOOK_ASSET_PREFIX.length)
-    : undefined;
-}
-
-// ─── #3998 D1 — send-outcome stamp ───────────────────────────────────────────────
-
-/**
- * Stamps the post-mint outcome on the grant row (#3998 D1). Caught and
- * logged, never escalated (#3998 D5) — a stamp write failing must not become
- * a new way to fail a submission or a resend; the existing `logOutcome` log
- * line is the audit trail of record either way.
- */
-async function stampOutcome(
-  grantId: string,
-  outcome: PostMintOutcome,
-  now: Date,
-): Promise<void> {
-  try {
-    // fence: global-key — `DeliverableGrant.id`, the capability token itself
-    // (#3961 D5: the grant IS the token). Every caller reaches this line
-    // inside an already-scoped frame — `fulfillDeliverable` has just MINTED
-    // this id under the session's workspace, and `resendDeliverableGrant` has
-    // just read the row back by the same opaque id — so the id is the row's
-    // own primary key, not a tenant selector, and a `workspaceId` term here
-    // could only re-state what the mint already fenced. It would also stop
-    // stamping LEGACY grants, whose `workspaceId` is NULL by the #6254 § 10.1
-    // Q2 carve-out, turning a post-mint audit stamp into a silent no-op.
-    await prisma.deliverableGrant.update({
-      where: { id: grantId },
-      data: { sendStatus: outcome, sendAt: now },
-    });
-  } catch (err) {
-    logger.warn(
-      {
-        grantId,
-        outcome,
-        err: err instanceof Error ? err.message : "Unknown error",
-      },
-      "[deliverable-fulfillment] failed to stamp send outcome",
-    );
-  }
-}
-
-// ─── #7519 D6 — the sender address ──────────────────────────────────────────────
-
-/**
- * The From address every email this service sends carries:
- * `AILK_DELIVERABLE_EMAIL_FROM`, else `AILK_LEAD_NOTIFICATION_FROM`,
- * `undefined` when neither is set — an empty value counts as unset (#7519 D6). One resolver for the send paths
- * (`sendAndStamp`, `sendCompletionEmail`) and the Admin's read
- * (`GET /v1/workspaces/:workspaceId/general` `emailFrom`), so the address
- * the Admin shows can never differ from the address the engine sends from.
- */
-export function deliverableSenderAddress(): string | undefined {
-  // `||`, not `??`: an env var set to "" names no sender, so it falls
-  // through to the next, and "" never reaches a From header or the Admin.
-  return (
-    process.env.AILK_DELIVERABLE_EMAIL_FROM ||
-    process.env.AILK_LEAD_NOTIFICATION_FROM ||
-    undefined
-  );
-}
-
-// ─── #3998 D5 — the shared post-mint tail ────────────────────────────────────────
-
-type SendAndStampInput = {
-  siteId: string;
-  flowSlug: string;
-  sessionId: string;
-  grantId: string;
-  email: string;
-  locale: string;
-  defaultLocale: string;
-  copy: DeliverableCopy;
-};
-
-/**
- * The post-mint tail shared by `fulfillDeliverable` and
- * `resendDeliverableGrant` (#3998 D5): resolve copy → build link → send →
- * stamp + log. The ONE place a delivery email is ever sent and its outcome
- * stamped — extracted so the resend CLI never carries a second copy of the
- * copy-resolution / link-building logic to drift.
- */
-async function sendAndStamp(input: SendAndStampInput): Promise<PostMintOutcome> {
-  const { siteId, flowSlug, sessionId, grantId, email, locale, defaultLocale, copy } =
-    input;
-  const logCtx = { siteId, flowSlug, sessionId };
-
-  const fromAddress = deliverableSenderAddress();
-
-  if (!fromAddress) {
-    await stampOutcome(grantId, "sender_unconfigured", new Date());
-    logOutcome(logCtx, "sender_unconfigured");
-    return "sender_unconfigured";
-  }
-
-  const subject = resolveCopy(copy.subject, locale, defaultLocale);
-  const body = resolveCopy(copy.body, locale, defaultLocale);
-  const cta = copy.cta ? resolveCopy(copy.cta, locale, defaultLocale) : undefined;
-
-  // D5 (#3961): no PII in link params — the link carries the opaque grant id
-  // and nothing else. D3 (#3998): this is the SAME expression on both the
-  // fulfillment path and the resend path, so a resend's link is
-  // byte-identical to the original.
-  const base = process.env.AILK_PUBLIC_API_URL ?? "";
-  const downloadLink = `${base}/v1/deliverables/${grantId}`;
-
-  const sendResult = await sendDeliverableEmail({
-    to: email,
-    fromAddress,
-    subject,
-    body,
-    downloadLink,
-    ...(cta !== undefined && { cta }),
-  });
-
-  const outcome: PostMintOutcome = sendResult.ok ? "sent" : "send_failed";
-  await stampOutcome(grantId, outcome, new Date());
-  logOutcome(logCtx, outcome);
-  return outcome;
-}
-
-// ─── #7519 D5 — the completion email (a flow with no deliverable) ──────────────
-
-type CompletionEmailCopy = NonNullable<FlowConfig["completionEmail"]>;
-
-export type SendCompletionEmailInput = {
-  siteId: string;
-  flowSlug: string;
-  sessionId: string;
-  /** The lead's address — `undefined` when the flow asked for none. */
-  email: string | undefined;
-  locale: string;
-  defaultLocale: string;
-  copy: CompletionEmailCopy;
-};
-
-type CompletionOutcome =
-  | "sent"
-  | "send_failed"
-  | "sender_unconfigured"
-  | "no_recipient";
-
-const COMPLETION_OUTCOME_MESSAGE: Record<CompletionOutcome, string> = {
-  sent: "[deliverable-fulfillment] completion email sent",
-  send_failed: "[deliverable-fulfillment] completion email send failed",
-  sender_unconfigured:
-    "[deliverable-fulfillment] no from-address configured — completion email skipped",
-  no_recipient:
-    "[deliverable-fulfillment] no email answer — completion email skipped",
-};
-
-/**
- * Sends a flow's `completionEmail` to the lead (#7519 D5) — the email a
- * newsletter, contact, waitlist or diagnostic sends on completion, where
- * there is no asset to deliver. The same sender, copy resolution and email
- * function as the deliverable path, with no download link: it mints no
- * grant and stamps nothing. Its outcome is logged with the
- * `{ siteId, flowSlug, sessionId }` context the deliverable outcomes use.
- * Never throws on its own business-logic misses; the caller's try/catch is
- * the residual net for a genuine error.
- */
-export async function sendCompletionEmail(
-  input: SendCompletionEmailInput,
-): Promise<CompletionOutcome> {
-  const { siteId, flowSlug, sessionId, email, locale, defaultLocale, copy } =
-    input;
-  const outcome = await sendCompletion();
-  logger.info(
-    { siteId, flowSlug, sessionId, outcome },
-    COMPLETION_OUTCOME_MESSAGE[outcome],
-  );
-  return outcome;
-
-  async function sendCompletion(): Promise<CompletionOutcome> {
-    if (!email) return "no_recipient";
-    const fromAddress = deliverableSenderAddress();
-    if (!fromAddress) return "sender_unconfigured";
-    const cta = copy.cta ? resolveCopy(copy.cta, locale, defaultLocale) : undefined;
-    const sendResult = await sendDeliverableEmail({
-      to: email,
-      fromAddress,
-      subject: resolveCopy(copy.subject, locale, defaultLocale),
-      body: resolveCopy(copy.body, locale, defaultLocale),
-      ...(cta !== undefined && { cta }),
-    });
-    return sendResult.ok ? "sent" : "send_failed";
-  }
-}
-
-// ─── fulfillDeliverable ─────────────────────────────────────────────────────────
-
-export async function fulfillDeliverable(
-  input: FulfillDeliverableInput,
-): Promise<{ grantId: string } | undefined> {
-  const {
-    siteId,
-    flowSlug,
-    configSnapshot,
-    segment,
-    leadId,
-    sessionId,
-    email,
-    locale,
-  } = input;
-
-  // D4: the block is opt-in per flow. Callers (flow-engine.ts) already gate
-  // the call on this being present; re-checking here is defense in depth,
-  // never load-bearing for the "no block → no call" AC4 regression floor.
-  const block = configSnapshot.deliverables;
-  if (!block) return undefined;
-
-  const logCtx = { siteId, flowSlug, sessionId };
-
-  // D3: no entry (segment derived but unmapped AND no default) — never fail
-  // the submission, just skip fulfillment.
-  const entry = resolveEntry(block.assets, segment);
-  if (!entry) {
-    logOutcome(logCtx, "no_entry");
-    return undefined;
-  }
-
-  // FEAT-074 U4b (#4718) D4 — the `playbook:` virtual asset: a per-lead
-  // COMPILED PlaybookInstance, never an operator-uploaded DeliverableAsset
-  // row. Skips the asset lookup entirely; requires at least one instance
-  // for (siteId, leadId, experimentKey) — the SAME log-and-skip,
-  // no-grant-minted posture `asset_missing` already has for an
-  // un-uploaded key (D4).
-  const playbookKey = playbookExperimentKey(entry.assetKey);
-
-  let assetId: string;
-  // #6310 D15 — written ONLY on the Asset arm; stays undefined (no column
-  // written) for a playbook: or legacy dasset_ grant.
-  let grantWorkspaceId: string | undefined;
-
-  if (playbookKey !== undefined) {
-    // #6257 — `siteId` is the session's own, resolved by the route that
-    // opened it (#6254/#6374 AC-7), so `workspaceId` rides beside it: a lead
-    // id and an experiment key alone would select a row whose tenant the
-    // query never stated.
-    const instance = await prisma.playbookInstance.findFirst({
-      where: { siteId, workspaceId: siteId, leadId, experimentKey: playbookKey },
-      select: { id: true },
-    });
-    if (!instance) {
-      logOutcome(logCtx, "playbook_missing");
-      return undefined;
-    }
-    assetId = entry.assetKey;
-  } else {
-    // #6310 D4 — resolve the workspace from the magnet's own live
-    // FlowDefinition, ONE query, issued only on this branch. D5 — a null or
-    // absent workspaceId skips the Asset lookup entirely; it is never
-    // guessed.
-    const definition = (await prisma.flowDefinition.findUnique({
-      where: { siteId_slug: { siteId, slug: flowSlug } },
-      select: { workspaceId: true },
-    })) as { workspaceId: string | null } | null;
-    const workspaceId = definition?.workspaceId ?? null;
-
-    const resolvedAssetId =
-      workspaceId !== null
-        ? await findDeliverableAssetIdByKey(workspaceId, entry.assetKey)
-        : null;
-
-    if (resolvedAssetId !== null && workspaceId !== null) {
-      // #6310 D2 — Asset resolves first; D15 — the grant carries the SAME
-      // workspaceId that authorized this resolution.
-      assetId = resolvedAssetId;
-      grantWorkspaceId = workspaceId;
-    } else {
-      // #8848 D3 (SEC-8848-B) — a `deliverable` flow resolves against the
-      // Asset store only: it is new, so it has no legacy key to keep, and the
-      // legacy store also holds the founders' signup CSVs.
-      if (configSnapshot.deliverable !== undefined) {
-        logOutcome(logCtx, "asset_missing");
-        return undefined;
-      }
-      // #6310 D2/D3 — legacy fallback. A missing row (config references an
-      // un-uploaded key) → same skip-and-log posture as before.
-      // #6257 — the LEGACY store's read, scoped by the same resolved
-      // workspace id the `Asset` arm above already resolves through
-      // `lib/deliverable-asset-store.ts`. The compound `[siteId, key]` names
-      // one row; `workspaceId` is what makes the tenant the QUERY's statement.
-      const asset = (await prisma.deliverableAsset.findUnique({
-        where: { siteId_key: { siteId, key: entry.assetKey }, workspaceId: siteId },
-      })) as DeliverableAssetRow | null;
-
-      if (!asset) {
-        logOutcome(logCtx, "asset_missing");
-        return undefined;
-      }
-      assetId = asset.id;
-    }
-  }
-
-  // D5: the grant IS the token — minted before the send is attempted so a
-  // later email-config gap or send failure never wastes it (a later
-  // manual/operator resend can reuse the same grant id).
-  const grant = (await prisma.deliverableGrant.create({
-    data: {
-      siteId,
-      assetId,
-      leadId,
-      sessionId,
-      // #6374 D4 / AC-8 — the SECOND DeliverableGrant mint site. The column
-      // stays NULLABLE for LEGACY rows (NULL is the serve path's fail-closed
-      // sentinel, #6254 § 10.1 Q2) and the migration touches none of them —
-      // but a grant minted HERE always knows its workspace, so it is never
-      // left to fail closed.
-      //
-      // `grantWorkspaceId` is #6310 D15's value, resolved from the magnet's
-      // own FlowDefinition on the `asset_` arm; that read is scoped by
-      // `siteId`, and the keystone's `flow_definitions_workspace_site_agree`
-      // CHECK makes `workspaceId = siteId` on that row, so the two are the
-      // SAME value and the `??` is a fallback for the legacy `dasset_` and
-      // virtual `playbook:` arms rather than a choice between two scopes.
-      // The new `deliverable_grants_workspace_site_agree` CHECK would reject
-      // a disagreement loudly either way.
-      //
-      // This does NOT change which bytes the download route serves: that
-      // route branches on the `assetId` PREFIX, and consults
-      // `grant.workspaceId` only on the `asset_` arm, where this value is
-      // what it already was.
-      workspaceId: grantWorkspaceId ?? siteId,
-    },
-    select: { id: true },
-  })) as { id: string };
-
-  // #3998 D5: resolve copy → build link → send → stamp + log, shared with
-  // the resend path.
-  await sendAndStamp({
-    siteId,
-    flowSlug,
-    sessionId,
-    grantId: grant.id,
-    email,
-    locale,
-    defaultLocale: configSnapshot.defaultLocale,
-    copy: block.copy,
-  });
-  return { grantId: grant.id };
-}
-
-// ─── #3998 D3 — resend: reuses the existing grant id, never mints ───────────────
-
-export type ResendGrantError = {
-  kind:
-    | "grant_not_found"
-    | "lead_not_found"
-    | "session_not_found"
-    | "invalid_config_snapshot"
-    | "no_deliverables_block";
-  message: string;
-};
-
-export type ResendGrantResult =
-  | { ok: true; outcome: PostMintOutcome }
-  | { ok: false; error: ResendGrantError };
-
-type DeliverableGrantRow = {
-  id: string;
-  siteId: string;
-  leadId: string;
-  sessionId: string;
-};
-
-type LeadRow = { email: string };
-
-type FlowSessionConfigRow = {
-  flowSlug: string;
-  configSnapshot: unknown;
-  locale: string | null;
-};
-
-/**
- * Re-sends the delivery email for an existing grant (#3998 D3/D4). Reuses
- * `grant.id` — this function contains no `deliverableGrant.create` call, so
- * a resend can never mint a second capability token for one lead. Resolves
- * copy from the session's PINNED `configSnapshot` (never a live
- * `FlowDefinition` lookup, #3998 D3) — a mid-flight config edit must never
- * change what a resend delivers.
- */
-export async function resendDeliverableGrant(
-  grantId: string,
-): Promise<ResendGrantResult> {
-  // fence: global-key — `DeliverableGrant.id`, the capability token itself
-  // (#3961 D5). This is the resolver: the operator hands the
-  // `deliverable:resend` CLI one opaque grant id and nothing else, and the
-  // WORKSPACE is what this read produces (`grant.siteId`, carried into
-  // `sendAndStamp` below), so a tenant term here would have to come from the
-  // answer it is computing. Holding the id is the capability, exactly as it
-  // is for the download route this resend re-sends a link to.
-  const grant = (await prisma.deliverableGrant.findUnique({
-    where: { id: grantId },
-    select: { id: true, siteId: true, leadId: true, sessionId: true },
-  })) as DeliverableGrantRow | null;
-
-  if (!grant) {
-    return {
-      ok: false,
-      error: {
-        kind: "grant_not_found",
-        message: `No deliverable grant found for id "${grantId}".`,
-      },
-    };
-  }
-
-  const lead = (await prisma.lead.findUnique({
-    where: { id: grant.leadId },
-    select: { email: true },
-  })) as LeadRow | null;
-
-  if (!lead) {
-    return {
-      ok: false,
-      error: {
-        kind: "lead_not_found",
-        message: `Grant "${grantId}" references lead "${grant.leadId}", which no longer exists.`,
-      },
-    };
-  }
-
-  const session = (await prisma.flowSession.findUnique({
-    where: { id: grant.sessionId },
-    select: { flowSlug: true, configSnapshot: true, locale: true },
-  })) as FlowSessionConfigRow | null;
-
-  if (!session) {
-    return {
-      ok: false,
-      error: {
-        kind: "session_not_found",
-        message: `Grant "${grantId}" references session "${grant.sessionId}", which no longer exists.`,
-      },
-    };
-  }
-
-  // #3998 D3: re-parse the pinned snapshot through flowConfigSchema — a
-  // snapshot that no longer parses is reported and skipped, never thrown.
-  const parsed = flowConfigSchema.safeParse(session.configSnapshot);
-  if (!parsed.success) {
-    return {
-      ok: false,
-      error: {
-        kind: "invalid_config_snapshot",
-        message:
-          parsed.error.issues[0]?.message ??
-          "The session's configSnapshot failed schema validation.",
-      },
-    };
-  }
-
-  const config = parsed.data;
-  const block = config.deliverables;
-  if (!block) {
-    return {
-      ok: false,
-      error: {
-        kind: "no_deliverables_block",
-        message: `The session's pinned configSnapshot for grant "${grantId}" carries no deliverables block.`,
-      },
-    };
-  }
-
-  const outcome = await sendAndStamp({
-    siteId: grant.siteId,
-    flowSlug: session.flowSlug,
-    sessionId: grant.sessionId,
-    grantId: grant.id,
-    email: lead.email,
-    locale: session.locale ?? config.defaultLocale,
-    defaultLocale: config.defaultLocale,
-    copy: block.copy,
-  });
-
-  return { ok: true, outcome };
-}
-
-// ─── #3998 D4 — list: sendless grants for one site ──────────────────────────────
-
-export type SendlessGrantRow = {
-  grantId: string;
-  createdAt: Date;
-  sessionId: string;
-};
-
-export type ListSendlessGrantsOptions = {
-  siteId: string;
-  since?: Date;
-  limit?: number;
-};
-
-type DeliverableGrantListRow = {
-  id: string;
-  createdAt: Date;
-  sessionId: string;
-};
-
-/**
- * Lists grants whose post-mint send never completed (`sendStatus IS NULL`,
- * #3998 D1's selection term) for one site, oldest first. Read-only — this is
- * the `deliverable:resend` CLI's default (no-`--grant`) mode.
- */
-export async function listSendlessGrants(
-  opts: ListSendlessGrantsOptions,
-): Promise<SendlessGrantRow[]> {
-  // #6257 — `opts.siteId` is the one value in this service that arrives as a
-  // RAW ALIAS: the `deliverable:resend` CLI passes `--site` through verbatim.
-  // It is resolved here, once, the way `dunning-policy.ts` resolves its own
-  // parameter — an alias that names no workspace lists nothing rather than
-  // falling back to the unscoped read it used to make.
-  const workspaceId = await resolveWorkspaceIdForAlias(opts.siteId);
-  if (workspaceId === null) {
-    logger.warn(
-      { siteId: opts.siteId, outcome: "site_unresolved" },
-      "[deliverable-fulfillment] --site names no workspace — listing nothing",
-    );
-    return [];
-  }
-
-  // #6257 — LEGACY grants are NOT in this list, and the narrowing is stated
-  // rather than left for an operator to discover. Two terms exclude them: the
-  // `workspaceId` filter below (their column is NULL by the #6254 § 10.1 Q2
-  // carve-out) and the resolved `siteId` (the keystone migration deliberately
-  // does NOT normalize `deliverable_grants.site_id` — migration.sql:1059 — so
-  // a legacy row on a `"default"`-aliased deployment still carries the alias).
-  //
-  // This is a genuine TIGHTENING beyond the serve path, not parity with it:
-  // `routes/deliverables/index.ts` consults `grant.workspaceId` only on the
-  // `asset_` arm, so a legacy `dasset_` or `playbook:` grant still downloads.
-  // The fence forces it — AC-2 forbids keying this read on the raw alias the
-  // CLI was given, and a legacy row carries no workspace key to resolve — so
-  // the list is narrower by construction and the recovery path for such a row
-  // is `deliverable:resend --grant <id>`, which is unaffected.
-  logger.info(
-    { siteId: workspaceId, outcome: "legacy_grants_excluded" },
-    "[deliverable-fulfillment] grants with no workspace key are NOT listed — resend one by id with --grant",
-  );
-
-  const rows = (await prisma.deliverableGrant.findMany({
-    where: {
-      siteId: workspaceId,
-      // #6257 — the fence term. See the note above for what it excludes and
-      // why that is a tightening rather than serve-path parity.
-      workspaceId,
-      sendStatus: null,
-      ...(opts.since !== undefined && { createdAt: { gte: opts.since } }),
-    },
-    orderBy: { createdAt: "asc" },
-    select: { id: true, createdAt: true, sessionId: true },
-    ...(opts.limit !== undefined && { take: opts.limit }),
-  })) as DeliverableGrantListRow[];
-
-  return rows.map((row) => ({
-    grantId: row.id,
-    createdAt: row.createdAt,
-    sessionId: row.sessionId,
-  }));
-}