create-ailk 0.5.0 → 0.6.1

package/templates/apps/api/src/lib/require-commerce-claim.ts

@@ -0,0 +1,250 @@
+/**
+ * Commerce license-claim guard for the commerce PRIMITIVES that live in the
+ * base tree (DECISION-LOG D-64, epic #5770, #5796).
+ *
+ * The checkout launcher, the Stripe webhook receiver, customer mapping and
+ * `lib/stripe.ts` ship unconditionally now — they are no longer registered
+ * behind `isModuleEnabled("commerce")`. What decides whether they SERVE is the
+ * JWT `features[]` claim `commerce`, read at CALL time through `checkLicense()`
+ * from `@working-theory/license`.
+ *
+ * This is the same shape as `./require-paid-tier.ts` — that file is the
+ * PATTERN, not the code (D-64): this gate reads
+ * `result.features.includes("commerce")` and never looks at `result.tier` as
+ * the claim test. A `commerce` claim can ride any paid level, so a tier test
+ * would be the wrong question.
+ *
+ * Response without the claim: the SAME module-disabled response the
+ * module-conditional path produced — a 404. `server.ts`'s root-endpoint
+ * comment (§ `deriveRootEndpoints`) documents that a build with commerce off
+ * simply does not advertise these routes and answers 404 on them, and
+ * `src/__tests__/module-exclusion.test.ts` measures exactly that status. The
+ * body is `notFoundError()` from `./errors.ts` — this repo's one reusable 404
+ * body — rather than a newly invented `module_disabled` code, which exists
+ * nowhere in the tree. The message deliberately does not mention commerce: a
+ * site without the claim is indistinguishable from a site built without the
+ * module, which is the point.
+ *
+ * ── TRI-STATE, not a boolean ────────────────────────────────────────────────
+ *
+ * Security review 2026-09-16, High; widened by the operator in round 2. A
+ * single `false` for "no claim" and "could not tell" is a data-loss bug on the
+ * webhook: a signed `checkout.session.completed` on a live commerce site whose
+ * licence read merely FAILED would be acked 200 and dropped, Stripe would
+ * record success and never retry, and the charge would never be mapped.
+ *
+ * So `resolveCommerceClaim()` answers `claimed | unclaimed | undetermined`:
+ *
+ *   claimed      — read successfully; `features[]` carries `commerce`.
+ *   unclaimed    — a positively-established "no": either a licence that reads
+ *                  successfully and simply lacks the claim, or a KEYLESS
+ *                  deployment that configures no licence at all.
+ *   undetermined — the read established no "no". These states reach it:
+ *                    1. `checkLicense()` threw.
+ *                    2. `revoked === true` — a revoked licence is still a
+ *                       PAYING site inside its JWT window (ADR 0014).
+ *                    3. a licence IS configured yet resolves free — the JWT
+ *                       expired, or no longer verifies.
+ *                    4. (3) also absorbs a configured-but-unparseable key.
+ *                    5. the licence STORAGE FILE could not be read — EACCES,
+ *                       EIO, EMFILE, a directory at its path (#5820).
+ *
+ * Why (3) needs the env read. `checkLicense()` returns the SAME `FREE_RESULT`
+ * for expired, invalid and keyless alike (`check-license.ts` — `expiresAt` is
+ * `null` and `revoked` is `false` in all three), so nothing on `LicenseResult`
+ * separates "this deployment's licence stopped verifying" from "this
+ * deployment never had one". The one signal that does is whether a licence is
+ * CONFIGURED at all, which is an env read this app already makes elsewhere
+ * (`services/enrichment-shim.ts`). No JWT is parsed here and no verification
+ * is re-implemented — presence is the entire test.
+ *
+ * ── The storage file, read for what it actually says (#5820) ────────────────
+ *
+ * A licence sourced from the refresh STORAGE FILE is covered on both axes.
+ * `readStoredJwtState()` — added to `@working-theory/license` for this gate —
+ * answers `absent | unreadable | present` where `readStoredJwt()` answered one
+ * `null` for the first two. Only `absent` (no file, or a file holding nothing
+ * but whitespace) is evidence that a deployment is unlicensed; a file that
+ * merely could not be READ is evidence of nothing, so it holds. An EXPIRED
+ * storage licence (`present`, resolving free) holds too.
+ *
+ * Before that distinction existed, a transient EACCES on a storage-licensed
+ * site read as keyless: a signed `checkout.session.completed` arriving in that
+ * window was acked 200, Stripe never redelivered it, and the charge was never
+ * mapped. `readStoredJwt()`'s own contract is untouched — `checkLicense()` and
+ * every other caller still see `null` for both states.
+ *
+ * ── Why the two routes answer differently ───────────────────────────────────
+ *
+ * The checkout launcher answers the module-disabled 404 on BOTH non-serving
+ * states: a checkout that cannot be started loses nothing, so there is no call
+ * to leak a "configured but unreadable" shape on it. The webhook receiver
+ * holds an `undetermined` event with a retryable 503 + `Retry-After`, because
+ * by the time it arrives the buyer's money has already moved.
+ *
+ * Usage as a Fastify preHandler (the checkout launcher):
+ *
+ *   fastify.post("/path", { preHandler: requireCommerceClaim }, handler);
+ *
+ * The Stripe webhook receiver does NOT use the preHandler: D3 puts signature
+ * verification BEFORE the claim check, so it consults `resolveCommerceClaim()`
+ * from inside its handler. See `routes/webhooks/README.md` § Commerce claim.
+ */
+
+import {
+  checkLicense,
+  readStoredJwtState,
+  type ProFeature,
+} from "@working-theory/license";
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { notFoundError } from "./errors.js";
+
+/** The claim the commerce primitives serve behind (`ProFeature`, verify-jwt.ts). */
+export const COMMERCE_FEATURE: ProFeature = "commerce";
+
+const MODULE_DISABLED_MESSAGE = "Not found";
+
+/**
+ * What the licence read actually established. See the header for the four
+ * states that reach `undetermined`.
+ */
+export type CommerceClaimState = "claimed" | "unclaimed" | "undetermined";
+
+/** The module-disabled response — a 404, the canonical `not_found` body. */
+export function commerceDisabledResponse() {
+  return notFoundError(MODULE_DISABLED_MESSAGE);
+}
+
+/**
+ * The retryable answer for `undetermined` on the webhook. A local error
+ * vocabulary (`{ error: "..." }`), matching what `routes/webhooks/stripe.ts`
+ * already emits for its own failure modes, rather than `errors.ts`'s closed
+ * `ErrorCode` set, which has no service-unavailable member and whose MCP twin
+ * would have to grow one too.
+ *
+ * `Retry-After` is in SECONDS and is read by Stripe: five minutes is long
+ * enough for a transient licence-read failure or a refresh round-trip to
+ * clear, and short enough that a queued `checkout.session.completed` is mapped
+ * well inside Stripe's three-day redelivery window.
+ */
+export const LICENSE_UNDETERMINED_STATUS = 503;
+export const LICENSE_UNDETERMINED_BODY = { error: "license-undetermined" };
+export const LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS = 300;
+
+/**
+ * What this deployment's licence CONFIGURATION says — three answers, not two.
+ *
+ *   configured — an env key is set, or the storage file holds a token.
+ *   absent     — no env key, and the storage file is genuinely not there (or
+ *                holds nothing but whitespace). The only state that is
+ *                evidence of an unlicensed site.
+ *   unreadable — no env key, and the storage file could not be read at all.
+ *
+ * Presence only — the token is never parsed, verified or logged. This is the
+ * one signal that separates an EXPIRED/unverifiable licence from a keyless
+ * site, because `checkLicense()` collapses both into the same free result.
+ *
+ * It asks the question the SAME WAY `check-license.ts#resolveToken` does —
+ * `AILK_LICENSE_KEY`, else the refresh storage file — because that is where
+ * `checkLicense()` itself just looked. An env-only test would miss a
+ * deployment licensed purely from storage, so an EXPIRED storage licence would
+ * read as keyless and its already-charged events would be dropped.
+ *
+ * `unreadable` is kept separate from `absent` rather than folded into
+ * `configured` so the caller can LOG why it is holding (#5820): "this site has
+ * no licence" and "this site's licence could not be read" are different
+ * operator problems, and only the first is a fact.
+ */
+type LicenseConfigurationState = "configured" | "absent" | "unreadable";
+
+async function resolveLicenseConfiguration(): Promise<LicenseConfigurationState> {
+  const key = process.env["AILK_LICENSE_KEY"];
+  if (typeof key === "string" && key.length > 0) return "configured";
+
+  const stored = await readStoredJwtState();
+  if (stored.state === "present") return "configured";
+  if (stored.state === "absent") return "absent";
+
+  // `console.warn` rather than a request logger: `resolveCommerceClaim()` is
+  // called from the webhook handler with no logger threaded through, and the
+  // routes are out of scope for this change. The cause's `code` is the whole
+  // point of the line — EACCES and EISDIR are different operator fixes. The
+  // token is never in scope here, so nothing secret can reach the log.
+  const code =
+    (stored.cause as NodeJS.ErrnoException | undefined)?.code ?? "UNKNOWN";
+  console.warn(
+    "commerce-claim: licence storage file unreadable — holding rather than dropping",
+    { outcome: "license_storage_unreadable", code },
+  );
+  return "unreadable";
+}
+
+/**
+ * Resolve what this deployment's licence says about `commerce`.
+ *
+ * Never throws: a failed read is a state, not an exception, because both
+ * callers must be able to tell "no" from "could not tell".
+ */
+export async function resolveCommerceClaim(): Promise<CommerceClaimState> {
+  let result;
+  try {
+    result = await checkLicense();
+  } catch {
+    // The read FAILED. Not a "no" — callers hold rather than drop.
+    return "undetermined";
+  }
+
+  // A revoked licence keeps verifying locally until JWT `exp` (ADR 0014), so
+  // this is a PAYING commerce site mid-window whose events are still real.
+  // Closing the gate is right; DROPPING them is the security review's High
+  // under a different label.
+  if (result.revoked === true) return "undetermined";
+
+  if (result.features.includes(COMMERCE_FEATURE)) return "claimed";
+
+  if (result.tier === "free") {
+    const configuration = await resolveLicenseConfiguration();
+    // A licence is configured yet resolved free: expired, or no longer
+    // verifying. `checkLicense()` cannot say which, and neither is a "no".
+    if (configuration === "configured") return "undetermined";
+    // The storage file could not be read (#5820). An unreadable file is not
+    // evidence of a keyless site, and dropping a signed Stripe event needs
+    // evidence — so this holds and Stripe retries.
+    if (configuration === "unreadable") return "undetermined";
+    // `absent` — no env key and no storage file. A positively-established
+    // "no", and the only state on this path that may drop an event.
+  }
+
+  return "unclaimed";
+}
+
+/**
+ * Fastify preHandler for the checkout launcher: serve only with the claim.
+ *
+ * Both non-serving states answer the module-disabled 404 — see the header:
+ * an unstartable checkout loses nothing, so the route stays indistinguishable
+ * from a build without the module rather than advertising that a licence
+ * exists but could not be read. The `undetermined` case is still logged, so
+ * an operator can tell a lapsed licence from a deliberate free build.
+ *
+ * Returns void (proceed) with the claim and short-circuits with `reply.send`
+ * otherwise, matching Fastify's preHandler contract.
+ */
+export async function requireCommerceClaim(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const state = await resolveCommerceClaim();
+  if (state === "claimed") return;
+
+  if (state === "undetermined") {
+    request.log.warn(
+      { outcome: "license_undetermined" },
+      "commerce licence could not be read — checkout answering the module-disabled response",
+    );
+  }
+
+  const err = commerceDisabledResponse();
+  return reply.status(err.status).send(err.body);
+}

package/templates/apps/api/src/lib/site.ts

@@ -1,16 +1,215 @@
 /**
  * @file site.ts
- * @description The current-site resolution helper (#3958 §3.2).
- *
- * Extracted verbatim from `routes/flows/index.ts`'s private
- * `currentSiteId()` so the flow-preset seed (`services/flow-engine.ts` →
- * `bin/seed-presets.ts`) resolves the SAME site id the `/v1/flows/*` routes
- * resolve — a seed hard-coding `"default"` would write presets the API
- * cannot find whenever `AILK_SITE_ID` is set (a silent, environment-dependent
- * 404). Behavior is byte-identical to the pre-extraction helper: same env
- * var, same fallback, same call sites.
+ * @description The current-site resolution helper (#3958 §3.2), extended by
+ * #6155 (spec D2/D5/D6, ownership brief
+ * `docs/internal/decisions/workspace-owns-data-surfaces-render.md`) with the
+ * ALIAS -> WORKSPACE resolution the brief requires: `currentSiteId()`'s
+ * env-var alias is resolved to a real `workspaces.id` ONCE at startup,
+ * memoized, and ASSERTED — so a misconfigured deployment refuses to boot
+ * instead of serving empty lists (AC-5).
+ *
+ * `currentSiteId()` is extracted verbatim from `routes/flows/index.ts`'s
+ * private `currentSiteId()` so the flow-preset seed
+ * (`services/flow-engine.ts` -> `bin/seed-presets.ts`) resolves the SAME
+ * site id the `/v1/flows/*` routes resolve — a seed hard-coding `"default"`
+ * would write presets the API cannot find whenever `AILK_SITE_ID` is set (a
+ * silent, environment-dependent 404). Behavior is byte-identical to the
+ * pre-extraction helper: same env var, same fallback, same call sites.
+ * `currentSiteId()` stays SYNCHRONOUS and byte-identical (#6155 D5) — the
+ * new resolution is async (it reads the database), and making
+ * `currentSiteId()` async would edit every one of its dozen non-test call
+ * sites across routes/services/bins, including the two route files NFR1
+ * requires to stay byte-unchanged.
  */
+import { resolvedAdapterKind } from "@working-theory/content-adapters";
+import {
+  DEFAULT_WORKSPACE_ID,
+  DEFAULT_WORKSPACE_SLUG,
+  resolveSentinelWorkspaceRow,
+} from "@working-theory/database/tenancy";
+import { logger } from "@working-theory/observability";
+
+import { prisma } from "./prisma.js";
 
 export function currentSiteId(): string {
   return process.env.AILK_SITE_ID ?? "default";
 }
+
+/**
+ * The resolved workspace id, memoized after the first SUCCESSFUL resolution
+ * ("resolves the alias once at startup", ownership brief § Layer 2 / #6155
+ * D5). `null` is never cached — a failed resolution has already thrown from
+ * `build()` (D6), so there is no negative-cache case to hold, and a later
+ * retry (a test, a re-seeded database) is free to resolve on its next call.
+ */
+let cachedWorkspaceId: string | null = null;
+
+/**
+ * Resolves `currentSiteId()`'s alias to a real `workspaces.id`, per the
+ * two-and-only-two rule (#6155 spec D2):
+ *
+ *  1. The literal alias `"default"` resolves to the seeded sentinel
+ *     workspace — `DEFAULT_WORKSPACE_ID` — IFF that row exists and hangs
+ *     off the sentinel Organization
+ *     (`@working-theory/database/tenancy`'s `resolveSentinelWorkspaceRow`,
+ *     which carries NO `workspace.count()` gate — unlike
+ *     `resolveDefaultWorkspaceRow`, whose single-tenancy meaning this unit
+ *     must NOT widen; see D2's "why a NEW resolver"). This is what lets a
+ *     correctly-configured MULTI-workspace deployment that has not pinned
+ *     `AILK_SITE_ID` still resolve — `resolveDefaultWorkspaceRow`'s count
+ *     gate would refuse it.
+ *  2. Any OTHER alias resolves ONLY by exact `workspaces.id` equality.
+ *  3. Anything that resolves neither way is `null` — never a fallback,
+ *     never a guess (`assertSiteAliasResolves` below is what turns a `null`
+ *     into a startup refusal).
+ *
+ * Memoized (D5): the SECOND call issues zero Prisma queries once the first
+ * has resolved successfully. `__resetSiteWorkspaceCacheForTests()` clears
+ * the memo for test isolation.
+ */
+export async function resolveSiteWorkspaceId(): Promise<string | null> {
+  if (cachedWorkspaceId !== null) {
+    return cachedWorkspaceId;
+  }
+
+  const resolved = await resolveWorkspaceIdForAlias(currentSiteId());
+  if (resolved !== null) {
+    cachedWorkspaceId = resolved;
+  }
+  return resolved;
+}
+
+/**
+ * The two-and-only-two resolution rule (#6155 spec D2), extracted so a
+ * write site holding an EXPLICIT `siteId` parameter (not necessarily
+ * `currentSiteId()` — e.g. a `ProjectListing` resolved through its own
+ * `SiteListingConfig.siteId`) can resolve it the same way
+ * `resolveSiteWorkspaceId()` resolves the env alias, without going through
+ * that function's `currentSiteId()`-only memo (#6254 spec D1a): the write
+ * paths that still stamp a raw, unresolved alias resolve it first, through
+ * this resolver, before it ever reaches a `workspace_id NOT NULL` /
+ * `CHECK (workspace_id = site_id)` column.
+ *
+ *  1. The literal alias `"default"` resolves to the seeded sentinel
+ *     workspace IFF that row exists (`resolveSentinelWorkspaceRow`).
+ *  2. Any OTHER alias resolves ONLY by exact `workspaces.id` equality.
+ *  3. Anything that resolves neither way is `null` — never a fallback,
+ *     never a guess.
+ *
+ * Not memoized — callers passing a per-request `siteId` would otherwise
+ * share a cache keyed on nothing. `resolveSiteWorkspaceId()` above keeps
+ * its own single-value memo for the hot, env-alias-only path.
+ */
+export async function resolveWorkspaceIdForAlias(
+  alias: string,
+): Promise<string | null> {
+  if (alias === DEFAULT_WORKSPACE_SLUG) {
+    const row = await resolveSentinelWorkspaceRow(prisma);
+    return row?.id ?? null;
+  }
+  const row = await prisma.workspace.findUnique({ where: { id: alias } });
+  return row ? alias : null;
+}
+
+/**
+ * Asserts `currentSiteId()`'s alias resolves to a real workspace — the
+ * misconfigured-deployment refusal AC-5 requires (D6). Awaited from
+ * `build()` (`apps/api/src/server.ts`), beside the two startup assertions
+ * already there; `apps/api/src/index.ts` already catches, logs and
+ * `process.exit(1)`s on a `build()` throw, so this is a loud refusal to
+ * start with no new exit-path code.
+ *
+ * THE CARVE-OUT (D6): when the alias genuinely CANNOT be checked — or NEED
+ * not be — this logs a warning and returns rather than throwing: a
+ * "database-less dev boot," never a misconfiguration. Three arms feed it, and
+ * ALL THREE are presence checks made BEFORE any query is attempted — never a
+ * catch around a query that already ran, which would just as readily swallow a
+ * genuine connection failure as it would an absent delegate (code-review
+ * finding, #6155):
+ *
+ *  0. **The content adapter is not `database`** (#6228) — the one arm that is
+ *     "need not," not "cannot." The alias→workspace resolution exists so a
+ *     database-backed content read has a workspace to read within; under
+ *     `mdx` or `projection` NO read takes a `workspaceId` at all, so the
+ *     assertion guards nothing and its only effect is to require a REACHABLE
+ *     database of a deployment that never queries one. That is the #6228
+ *     defect: `create-ailk`'s scaffold check sets a placeholder
+ *     `DATABASE_URL` (presence is all `validateConfig()` wants, and Prisma
+ *     connects lazily), so arm 1 does not fire, and the generated MDX site
+ *     crashed at boot on `Can't reach database server`. Read through
+ *     `resolvedAdapterKind()` — the ONE switch over `CONTENT_ADAPTER`
+ *     (`packages/content-adapters/src/resolve.ts`) — rather than a second,
+ *     drifting read of the env var here.
+ *
+ *  1. **No `DATABASE_URL` configured** — the literal `requireDb()` guard
+ *     `apps/api/src/services/flow-engine.ts` uses for the flow services:
+ *     presence, not reachability. (`apps/api/src/config/index.ts`'s own
+ *     eager `validateConfig()` already refuses a real `apps/api` boot with
+ *     `DATABASE_URL` unset before `build()` is ever reached, so this arm is
+ *     for any OTHER caller of `build()`.)
+ *  2. **`prisma.workspace.findUnique` is not even a function** — the case
+ *     that surfaced this arm: `apps/api`'s shared/global prisma mocks
+ *     (`lib/__mocks__/prisma-client.js`, the module-map-level double every
+ *     test gets; the many hand-rolled hoisted factories in route/service
+ *     suites that never touch tenancy) predate this unit and declare no
+ *     `workspace` delegate at all — the FIRST real Prisma read `build()`
+ *     itself has ever issued. Widening dozens of unrelated test files'
+ *     prisma doubles to add a resolving `workspace.findUnique` has a far
+ *     larger and harder-to-audit blast radius than making THIS one
+ *     assertion resilient to "the check itself is unavailable." A resolution
+ *     that could not even be ATTEMPTED is not a misconfiguration to fail
+ *     loudly about — but a resolution that WAS attempted and threw (a real
+ *     connection error, a permissions error, a bug in the resolver) is
+ *     exactly the class D6/AC-5 exist to surface, so it is deliberately NOT
+ *     caught here: it propagates out of `resolveSiteWorkspaceId()` and
+ *     crashes the boot, the same as any other unhandled `build()` throw.
+ *
+ * A reachable database with no matching workspace is the failure case, and
+ * it throws. A reachable database that ERRORS mid-query throws too — that is
+ * NOT the carve-out, it is the misconfiguration AC-5 asks to fail loudly
+ * about.
+ */
+export async function assertSiteAliasResolves(): Promise<void> {
+  const adapterKind = resolvedAdapterKind();
+  if (adapterKind !== "database") {
+    logger.warn(
+      { alias: currentSiteId(), contentAdapter: adapterKind },
+      "[site] content adapter is not `database` — skipping the site-alias workspace assertion (no read takes a workspaceId on this boot)",
+    );
+    return;
+  }
+
+  if (!process.env.DATABASE_URL) {
+    logger.warn(
+      { alias: currentSiteId() },
+      "[site] DATABASE_URL not set — skipping the site-alias workspace assertion (database-less boot)",
+    );
+    return;
+  }
+
+  if (typeof prisma.workspace?.findUnique !== "function") {
+    logger.warn(
+      { alias: currentSiteId() },
+      "[site] prisma.workspace is unavailable — skipping the site-alias workspace assertion (the resolution could not be attempted)",
+    );
+    return;
+  }
+
+  const resolved = await resolveSiteWorkspaceId();
+  if (resolved !== null) {
+    return;
+  }
+
+  const alias = currentSiteId();
+  throw new Error(
+    `AILK_SITE_ID="${alias}" names no workspace. The site alias must be an ` +
+      'existing workspaces.id, or the literal "default" (the seeded ' +
+      `sentinel workspace ${DEFAULT_WORKSPACE_ID}). Run \`pnpm db:seed\`, or ` +
+      "set AILK_SITE_ID to a workspace this database holds.",
+  );
+}
+
+/** Test-only: clears the memoized resolution (#6155 D5). */
+export function __resetSiteWorkspaceCacheForTests(): void {
+  cachedWorkspaceId = null;
+}

package/templates/apps/api/src/lib/stripe.ts

@@ -0,0 +1,66 @@
+/**
+ * apps/api Stripe shim.
+ *
+ * Re-exports @working-theory/stripe-client's public surface for use by routes and
+ * services under apps/api. This is the SOLE Stripe-touching file in apps/api.
+ *
+ * Future routes import from here (`from '../lib/stripe'`), not directly from
+ * '@working-theory/stripe-client' — single chokepoint for AILK-internal ergonomics
+ * (logger context, request-id propagation) without touching every consumer.
+ */
+import { getStripeClient } from "@working-theory/stripe-client";
+
+export {
+  assertSandboxKey,
+  createAdHocPrice,
+  createBillingPortalSession,
+  createCheckoutSession,
+  createPaymentLink,
+  createQuotedCheckoutSession,
+  getStripeClient,
+  // Checkout session read (#6084 D9) — re-exported through this sole
+  // Stripe-touching chokepoint, same as every other Stripe call here.
+  retrieveCheckoutSession,
+  STRIPE_API_VERSION,
+  StripeConfigError,
+  StripeWebhookSignatureError,
+  toSubscriptionLifecycleStatus,
+  UnknownProductCodeError,
+  UnknownSessionError,
+  verifyWebhookSignature,
+  WEBHOOK_TOLERANCE_SECONDS,
+} from "@working-theory/stripe-client";
+
+export type {
+  CheckoutSessionLineItem,
+  CreateAdHocPriceInput,
+  CreateAdHocPriceOutput,
+  CreateBillingPortalSessionInput,
+  CreateBillingPortalSessionOutput,
+  CreatePaymentLinkInput,
+  CreatePaymentLinkOutput,
+  CreateCheckoutSessionInput,
+  CreateCheckoutSessionOutput,
+  CreateCheckoutSessionParams,
+  CreateQuotedCheckoutSessionInput,
+  CreateQuotedCheckoutSessionOutput,
+  RetrieveCheckoutSessionInput,
+  RetrieveCheckoutSessionOutput,
+  Stripe,
+  StripeCheckoutSession,
+  StripeWebhookEvent,
+} from "@working-theory/stripe-client";
+
+/**
+ * Expire a Checkout Session (#4912 FR7/D7).
+ *
+ * The compensation the recommender's attach-miss branch owes: the Stripe
+ * session already exists, its id never reached the `FlowCheckout` row, and
+ * nothing will ever join the two — so the session is closed rather than left
+ * live and payable (#4863). Built on the already-re-exported
+ * `getStripeClient`, whose construction asserts the `sk_test_` allow-list, so
+ * this call inherits the test-mode gate like every other Stripe call here.
+ */
+export async function expireCheckoutSession(stripeSessionId: string): Promise<void> {
+  await getStripeClient().checkout.sessions.expire(stripeSessionId);
+}