create-ailk 0.5.0 → 0.6.1

package/templates/apps/api/src/services/dunning-policy.ts

@@ -0,0 +1,294 @@
+/**
+ * @file dunning-policy.ts
+ * @description The per-tenant dunning grace policy (#6034 §§ D4, D5) — one
+ * function that resolves how many days a `past_due`/`unpaid` subscription
+ * keeps access before a subsequent `canceled` revokes it, plus the two
+ * read-side predicates that decide whether a subscriber has lost access or
+ * merely needs to act.
+ *
+ * NOT marked `oss: false` (§ D1) — `routes/webhooks/stripe.ts`, this file's
+ * only caller, deliberately left `commerce.ownedFiles`
+ * (`packages/create-ailk/src/module-architecture.ts:1818-1846`) so a keyless
+ * scaffold still carries and registers it; gating happens at CALL time on the
+ * commerce claim already settled at `stripe.ts:174` (NFR-3), not at file
+ * presence.
+ *
+ * The policy blob lives in `SiteSetting` (`database/config/schema.prisma:15`)
+ * — a model with NO reader anywhere in the tree before this file (§ 1.7) and
+ * a globally-`@unique` `key` column with no `siteId` column of its own. Per-
+ * tenant scoping therefore lives in the key STRING:
+ * `commerce.dunning_policy:<siteId>` — never an unsuffixed fallback, which
+ * would let one site's policy silently govern another's money.
+ *
+ * The read never throws (AC-3) — see the resolution table on
+ * `dunningPolicyFor` below, which mirrors `listing-config.ts`'s
+ * absent/malformed → documented-default contract for the same reason: an
+ * anonymous webhook delivery must not 500 because an operator (or nothing at
+ * all) wrote a bad policy row.
+ */
+
+import { logger } from "@working-theory/observability";
+import { z } from "zod";
+
+import { isModuleEnabled } from "../config/modules.js";
+import { prisma } from "../lib/prisma.js";
+import { resolveWorkspaceIdForAlias } from "../lib/site.js";
+
+/** The lifecycle values this record persists. A narrower set than
+ * `SubscriptionLifecycleStatus` (`@working-theory/stripe-client`): `trialing`
+ * never persists on its own — an arriving `active` OR `trialing` status is
+ * always rewritten to a recorded `status: "active"` (#6034 § D7's clean-
+ * recovery contract), so the record's own vocabulary only ever needs three
+ * members. */
+export type DunningRecordedStatus = "past_due" | "active" | "canceled";
+
+/** One subscription's recorded dunning state (#6034 § D2). */
+export interface DunningEntry {
+  status: DunningRecordedStatus;
+  accessState: "granted" | "revoked";
+  /** ISO-8601, or `null` before the subscription has ever failed. Set once,
+   * on first entry into a failing state, and never moved while it stays
+   * failing (§ D5) — re-arming on every retry would slide the grace window
+   * forward with every Stripe attempt and it would never expire. */
+  dunningArmedAt: string | null;
+  /** ISO-8601, or `null` while nothing has scheduled a revocation. Present
+   * (possibly in the future) the instant a `canceled` event is recorded —
+   * the read-side lazily evaluates it rather than any scheduler waking up to
+   * flip the row (§ D5 — NFR-7 forbids one). */
+  accessRevokesAt: string | null;
+  /** Stripe `event.created`, seconds — the ordering watermark § D6's
+   * admission rule compares incoming events against. */
+  lastEventAt: number;
+  /** The durable twin of the in-process `hasSeen` map (§ D6 rule 1) — a
+   * replay of the SAME event id is a no-op even after a process restart. */
+  lastEventId: string;
+}
+
+/** The whole `UserData` blob for the reserved
+ * `commerce.subscription_dunning` key — one row per subscriber, keyed by
+ * Stripe subscription id because one customer can hold more than one
+ * subscription (§ D2 — the map is what stops a second subscription's
+ * `active` clobbering the first's `past_due`). */
+export interface DunningRecord {
+  v: 1;
+  subscriptions: Record<string, DunningEntry>;
+}
+
+/** The reserved `UserData` key this record lives at (§ D12 — refused on
+ * `GET`/`PUT`/`DELETE /v1/user/data/:key`; the subject of the access
+ * decision may not read, write or erase it). */
+export const DUNNING_USER_DATA_KEY = "commerce.subscription_dunning";
+
+/** The map is capped so a per-event read-and-rewrite of the whole blob
+ * doesn't grow with a customer's entire subscription history (§ D2, § 9
+ * SEC-08). Eviction is oldest-first by `lastEventAt`, skipping any entry
+ * that is not yet terminal-and-settled (`status: "active"` with
+ * `accessState: "granted"`) — an entry still being dunned is never evicted
+ * out from under an in-flight decision. */
+export const DUNNING_MAX_SUBSCRIPTIONS = 50;
+
+export interface DunningPolicy {
+  graceDays: number;
+}
+
+/** 14 days — chosen because Stripe's Smart Retries schedule runs up to
+ * roughly three weeks and the grace clock starts at the FIRST failure, not
+ * at cancellation (§ D5). A shorter default would have the platform cut a
+ * buyer off while Stripe is still actively recovering the payment. */
+export const DUNNING_POLICY_DEFAULTS: DunningPolicy = { graceDays: 14 };
+
+/** A tenant may not configure a grace window longer than this. Clamped, not
+ * rejected — an operator's out-of-range number is a mistake to correct, not
+ * grounds to fall back to a platform default that may be MORE permissive
+ * than what they wrote (`listing-config.ts:55-62`'s disposition). */
+export const DUNNING_GRACE_DAYS_MAX = 90;
+
+/** Validated shape of the `SiteSetting.value` blob. Accepts any object with
+ * unknown extra keys (`.passthrough()`) so the "is this a JSON object at
+ * all" check is separated from the fine-grained `graceDays` validation below
+ * — zod v4's own `z.number()` already refuses `NaN`/`Infinity` outright,
+ * which would collapse the resolution table's distinct `malformed` and
+ * `non_finite` outcomes into one, so `graceDays` is read as `unknown` here
+ * and narrowed by hand. Deliberately NOT promoted to
+ * `@working-theory/validation` (§ D4) — one consumer, no cross-package
+ * reader; promoting it now would widen the published surface for nothing. */
+const DunningPolicyBlobSchema = z.object({}).passthrough();
+
+/** Logged once per process, the first time a `multi-tenant` deployment reads
+ * the policy (§ D4) — an operator should learn that one grace window governs
+ * every seller from a log line, not from a wrongful revocation. Process
+ * restart re-arms it, mirroring `enrichment-shim.ts`'s pro-sentinel flag. */
+let deploymentWidePolicyWarned = false;
+
+/**
+ * Resolve `siteId`'s dunning grace policy. Never throws (AC-3) — every
+ * branch below resolves to a value, logged at the level the § D4 resolution
+ * table specifies:
+ *
+ *   no row                                   → default, info  "no_policy_row"
+ *   not a JSON object                        → default, error "malformed"
+ *   `graceDays` absent / wrong type           → default, error "malformed"
+ *   `graceDays` non-finite (e.g. `1e999`)     → default, error "non_finite"
+ *   `graceDays` negative and finite           → clamp 0,  error "clamped_low"
+ *   `graceDays` finite and > the ceiling      → clamp max, error "clamped_high"
+ *   `graceDays` non-integer (e.g. `7.5`)      → floored,  warn  "floored"
+ *   the query itself throws                  → default, error "read_failed"
+ *   a valid integer in `[0, DUNNING_GRACE_DAYS_MAX]` → that value, no log
+ *
+ * `siteId` is a PARAMETER, never read via `currentSiteId()` inside this
+ * function (§ D4) — a later per-seller resolution is then a caller change
+ * only, no signature churn.
+ */
+export async function dunningPolicyFor(siteId: string): Promise<DunningPolicy> {
+  // #6374 D3 — the key is built from the UNRESOLVED `siteId` parameter, and
+  // that is deliberate, not an oversight. `site_settings` never had a
+  // `site_id` column, so the site alias was embedded in the key STRING
+  // (`commerce.dunning_policy:default`); the migration's backfill leaves
+  // every `key` verbatim. Rebuilding it from the RESOLVED workspace id would
+  // match no row and hand every seller the built-in default policy —
+  // silently, which is the failure mode this whole function's log table
+  // exists to make visible.
+  const key = `commerce.dunning_policy:${siteId}`;
+
+  if (isModuleEnabled("multi-tenant") && !deploymentWidePolicyWarned) {
+    deploymentWidePolicyWarned = true;
+    logger.warn(
+      { key, outcome: "deployment_wide_policy" },
+      "[dunning-policy] this deployment's grace policy is shared by every seller — the multi-tenant module is enabled but the policy key carries no per-seller resolution yet",
+    );
+  }
+
+  // #6374 D3 — `site_settings` is now keyed by (workspace_id, key): `key`
+  // alone is no longer unique, because two sellers may each hold a
+  // `feature_flags` row. The WORKSPACE half is resolved from the alias here;
+  // the KEY half keeps its embedded alias (see the note above). An alias
+  // that resolves to nothing takes the same branch a missing row already
+  // takes — the built-in default policy — rather than throwing on a
+  // payment-webhook path.
+  const workspaceId = await resolveWorkspaceIdForAlias(siteId);
+  if (workspaceId === null) {
+    logger.info(
+      { siteId, key, outcome: "no_policy_row" },
+      "[dunning-policy] site alias resolves to no workspace — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  let row: { value: unknown } | null;
+  try {
+    row = await prisma.siteSetting.findUnique({
+      where: { workspaceId_key: { workspaceId, key } },
+      select: { value: true },
+    });
+  } catch (err) {
+    logger.error(
+      {
+        siteId,
+        key,
+        outcome: "read_failed",
+        errName: err instanceof Error ? err.name : "UnknownError",
+      },
+      "[dunning-policy] policy read failed — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  if (!row) {
+    logger.info(
+      { siteId, key, outcome: "no_policy_row" },
+      "[dunning-policy] no policy row — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  const parsed = DunningPolicyBlobSchema.safeParse(row.value);
+  if (!parsed.success) {
+    logger.error(
+      { siteId, key, outcome: "malformed" },
+      "[dunning-policy] stored policy is not a JSON object — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  const graceDaysRaw: unknown = (parsed.data as Record<string, unknown>)[
+    "graceDays"
+  ];
+  if (typeof graceDaysRaw !== "number") {
+    logger.error(
+      { siteId, key, outcome: "malformed" },
+      "[dunning-policy] stored graceDays is missing or not a number — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  // `Number.isFinite` covers both the reachable `1e999 → Infinity` overflow
+  // AND `NaN`, which cannot arrive from `jsonb` in the first place (there is
+  // no `NaN` literal in JSON) — one guard, both cases (§ 9 SEC-10).
+  if (!Number.isFinite(graceDaysRaw)) {
+    logger.error(
+      { siteId, key, outcome: "non_finite" },
+      "[dunning-policy] stored graceDays is not finite — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  if (graceDaysRaw < 0) {
+    logger.error(
+      { siteId, key, outcome: "clamped_low", stored: graceDaysRaw },
+      "[dunning-policy] stored graceDays is negative — clamped to 0",
+    );
+    return { graceDays: 0 };
+  }
+
+  if (graceDaysRaw > DUNNING_GRACE_DAYS_MAX) {
+    logger.error(
+      { siteId, key, outcome: "clamped_high", stored: graceDaysRaw },
+      "[dunning-policy] stored graceDays exceeds the ceiling — clamped",
+    );
+    return { graceDays: DUNNING_GRACE_DAYS_MAX };
+  }
+
+  if (!Number.isInteger(graceDaysRaw)) {
+    const floored = Math.floor(graceDaysRaw);
+    logger.warn(
+      { siteId, key, outcome: "floored", stored: graceDaysRaw },
+      "[dunning-policy] stored graceDays is not an integer — floored",
+    );
+    return { graceDays: floored };
+  }
+
+  return { graceDays: graceDaysRaw };
+}
+
+/**
+ * Access is gone for this subscription: either already stamped `revoked`, or
+ * the lazily-evaluated `accessRevokesAt` instant has passed. No scheduler
+ * flips this — every reader evaluates it fresh (§ D5, NFR-7).
+ */
+export function isSubscriberRevoked(
+  entry: DunningEntry,
+  now: number = Date.now(),
+): boolean {
+  return (
+    entry.accessState === "revoked" ||
+    (entry.accessRevokesAt !== null && now >= Date.parse(entry.accessRevokesAt))
+  );
+}
+
+/**
+ * The buyer must act — #6038's banner predicate (§ D5), exported so #6038
+ * CALLS it rather than re-deriving it. Deliberately WIDER than
+ * `status === "past_due"`: a subscription cancelled with its grace window
+ * still open carries `status: "canceled"`, `accessState: "granted"` — a
+ * buyer about to lose access who has not been told. Both cases are covered
+ * here; neither alone is (§ 9 SEC-09).
+ */
+export function isSubscriberActionRequired(
+  entry: DunningEntry,
+  now: number = Date.now(),
+): boolean {
+  return (
+    !isSubscriberRevoked(entry, now) &&
+    (entry.status === "past_due" || entry.accessRevokesAt !== null)
+  );
+}

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

@@ -17,6 +17,11 @@
  * spec builds NO metering engine (spec D5).
  */
 import type { Entitlements } from "@working-theory/license";
+import {
+  MAGNET_KIND_MIN_RANK,
+  planRank,
+  type FlowConfig,
+} from "@working-theory/validation";
 
 import { prisma } from "../lib/prisma.js";
 
@@ -66,6 +71,56 @@ export async function resolveEntitlements(
   };
 }
 
+/**
+ * #6287 — the org's plan RANK (never the deployment-wide `checkLicense()`),
+ * for the magnet routes' server-side plan gate. Composes `resolveEntitlements`
+ * above + `planRank` (`@working-theory/validation`, the same table the
+ * Admin's own UI-only gate reads) and NEVER throws: any failure (a DB
+ * error, or a tier string `planRank` doesn't recognize) collapses to
+ * `undefined` — the caller's fail-closed signal for a gated kind (spec D
+ * "the plan-rank resolver never throws").
+ */
+export async function resolveOrgPlanRank(
+  organizationId: string,
+): Promise<number | undefined> {
+  try {
+    const entitlements = await resolveEntitlements(organizationId);
+    return planRank(entitlements.limits.static.tier);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * #6305 — the minimum plan rank a GATED-SHAPE config requires, independent
+ * of the `kind` label the caller chose. Derived from `MAGNET_KIND_MIN_RANK`
+ * (never hand-duplicated) as the lowest non-zero rank in that table: today
+ * that is the same Pro-tier rank every gated kind already requires, so a
+ * gated-shape config on an ungated kind is refused exactly as a gated-kind
+ * refusal would be (#6305 AC-1).
+ */
+export const GATED_FLOW_SHAPE_MIN_RANK = Math.min(
+  ...Object.values(MAGNET_KIND_MIN_RANK).filter((rank) => rank > 0),
+);
+
+/**
+ * #6305 — whether a `FlowConfig` carries the shape the flow runtime actually
+ * branches on for gated (recommending-mode) behavior, regardless of which
+ * `kind` label the row carries. This is the SAME predicate family
+ * `deriveFlowKind`-style logic elsewhere in this codebase reads
+ * (`mode === "recommending"`, or the presence of `deliverables` / `offers` /
+ * `scoring`) — the label and the capability it confers can no longer diverge.
+ */
+export function configHasGatedShape(config: FlowConfig | undefined): boolean {
+  if (!config) return false;
+  return (
+    config.mode === "recommending" ||
+    config.deliverables !== undefined ||
+    config.offers !== undefined ||
+    config.scoring !== undefined
+  );
+}
+
 /**
  * The org's Stripe billing-customer identity (#3701 — the apps/api
  * predecessor to the org-billing UI, #3697).
@@ -100,3 +155,28 @@ export async function getOrgBillingIdentity(
 
   return { billingCustomerId: org?.billingCustomerId ?? null };
 }
+
+/**
+ * Whether ANY Organization row carries the given Stripe customer id (#6038
+ * D3.2, closes SA-4). Touches only `Organization.billingCustomerId` by
+ * explicit value — the same sanctioned-exception shape as
+ * `getOrgBillingIdentity` above (by id) and `resolveEntitlements` (by id),
+ * never an un-scoped tenant/content query.
+ *
+ * Exists because no code in this repo stamps `metadata.organizationId` onto
+ * a Stripe customer, so every `customer.created` takes the `User` branch
+ * (`webhooks/stripe.ts`'s `upsertBillingIdentity`) and a single `cus_…` can
+ * end up projected onto BOTH a `User` row and an `Organization` row. A
+ * caller resolving "the caller's own portal" from `User.billingCustomerId`
+ * alone would then risk opening the ORGANIZATION's billing record instead —
+ * this is the collision check that refuses that case.
+ */
+export async function isBillingCustomerAnOrganization(
+  billingCustomerId: string,
+): Promise<boolean> {
+  const org = await prisma.organization.findFirst({
+    where: { billingCustomerId },
+    select: { id: true },
+  });
+  return org !== null;
+}

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

@@ -24,6 +24,7 @@ import type { Id } from "@working-theory/ids";
 import { prisma } from "../lib/prisma.js";
 
 import { resolveOwnerWorkspaces } from "./owner-workspaces.js";
+import { findVerifiedEmail } from "./verified-email.js";
 
 /**
  * Workspace resolution moved to `owner-workspaces.ts` (#5678) so the leads
@@ -86,23 +87,21 @@ export async function promoteLeadsForVerifiedUser(params: {
   const { userId } = params;
 
   try {
-    const user = await prisma.user.findUnique({
-      where: { id: userId },
-      select: { id: true, email: true, emailVerified: true },
-    });
-
-    if (!user) {
-      return {
-        ok: false,
-        error: { kind: "user_not_found", message: "User not found" },
-      };
-    }
-
     // D2 — the verified-email gate is a service-level invariant, not a
-    // caller obligation: it cannot be bypassed by a wrong call-site.
-    if (!user.emailVerified) {
+    // caller obligation: it cannot be bypassed by a wrong call-site. The read
+    // and the refusal both live in `services/verified-email.ts` (#5701 D4),
+    // shared with the four other email-keyed paths.
+    const verified = await findVerifiedEmail(userId);
+    if (!verified.ok) {
+      if (verified.reason === "user_not_found") {
+        return {
+          ok: false,
+          error: { kind: "user_not_found", message: "User not found" },
+        };
+      }
       return { ok: true, count: 0, promoted: [] };
     }
+    const user = verified.value;
 
     // D3/D4 — resolve the verifying user's OWN workspaces through the one
     // shared resolution (`owner-workspaces.ts`). Role-agnostic here:

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

@@ -10,6 +10,18 @@
  *
  * PII boundary: only { siteId, kind, ip, persisted, emailKind } appear in logs.
  * Never log email, phone, name, or payload values.
+ *
+ * TENANCY (#6203). `input.siteId` is the caller's RESOLVED workspace id —
+ * `routes/leads/index.ts` resolves it server-side before calling `routeLead`
+ * and never a client-supplied value (see that file's header). `Lead` gets a
+ * `workspaceId` stamp of the same value, and since #6374 so do `Subscriber`
+ * and `Callback` — both gained a required `workspaceId` column in the fence
+ * fan-out, stamped from the same resolved id by the three `create` sites
+ * below. (This line previously said those two models had no such column;
+ * that stopped being true when the keystone migration landed, and the code
+ * under it already contradicted it.) The one READ in this file — the
+ * duplicate-subscriber lookup on the P2002 arm — is scoped by it too
+ * (#6257).
  */
 
 import { randomUUID } from "node:crypto";
@@ -23,6 +35,7 @@ import { appendLeadRecord } from "../lib/lead-capture-store.js";
 import { prisma } from "../lib/prisma.js";
 
 import { enrichLead } from "./enrichment-shim.js";
+import { requestConfirmSupersedesNotification } from "./request-confirm.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -103,6 +116,23 @@ async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
     const row = (await prisma.lead.create({
       data: {
         siteId: input.siteId,
+        // #6203/#6254 — the isolation key, equal to `siteId` by
+        // construction. `input.siteId` is the RESOLVED workspace id at
+        // EVERY `routeLead(kind: "submit")` caller now — the primary route
+        // (`routes/leads/index.ts`, never reads it from the body — see that
+        // file's header) and the three service-layer callers
+        // (`flow-engine.ts`'s `completeSubmission`,
+        // `recommender-capture.ts`'s `captureRecommenderChoice`,
+        // `project-listings.ts`'s `submitProjectListingDraft`) all resolve
+        // the site alias before calling in (#6254 AC-6/AC-10). `workspaceId`
+        // is NOT NULL as of
+        // database/migrations/20260922120000_tenancy_fence, so this can no
+        // longer stamp `null` for an unresolved alias the way it once did
+        // (spec D2's old rule) — a caller that somehow still passed one
+        // would instead hit the pre-existing `<table>_workspace_id_format`
+        // CHECK loudly, via the AC-11 re-raise below, rather than landing a
+        // silently-unfenced row.
+        workspaceId: input.siteId,
         source: input.source,
         email: input.email,
         payload: input.payload as Prisma.InputJsonValue,
@@ -117,6 +147,13 @@ async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
       const row = (await prisma.subscriber.create({
         data: {
           siteId: input.siteId,
+          // #6374 — the isolation key, equal to `siteId` by construction,
+          // exactly as `lead.create` above stamps it. `input.siteId` is the
+          // RESOLVED workspace id at every `routeLead` caller (see the
+          // `submit` branch's own note); a caller that somehow passed a raw
+          // alias would hit `subscribers_workspace_id_format` loudly rather
+          // than landing a silently-unfenced row. Never from a request body.
+          workspaceId: input.siteId,
           email: input.email,
           source: input.source,
         },
@@ -131,8 +168,15 @@ async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
         "code" in err &&
         (err as { code: string }).code === "P2002"
       ) {
+        // #6257 — the duplicate lookup is scoped by the same resolved
+        // workspace id the `create` above stamps (`input.siteId` is the
+        // RESOLVED id at every caller — see the `submit` branch's note), so a
+        // P2002 on another tenant's row can never resolve to its id.
         const existing = (await prisma.subscriber.findUnique({
-          where: { siteId_email: { siteId: input.siteId, email: input.email } },
+          where: {
+            siteId_email: { siteId: input.siteId, email: input.email },
+            workspaceId: input.siteId,
+          },
           select: { id: true },
         })) as DbRow | null;
         const existingId = existing?.id ?? "duplicate-no-id";
@@ -152,6 +196,10 @@ async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
   const row = (await prisma.callback.create({
     data: {
       siteId: input.siteId,
+      // #6374 — the isolation key, equal to `siteId` by construction; same
+      // resolution guarantee and same loud-failure posture as the two
+      // branches above. Never from a request body (AC-6).
+      workspaceId: input.siteId,
       name: input.name,
       phone: input.phone,
       ...(input.preferredTime !== undefined && {
@@ -164,6 +212,56 @@ async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
   return { ok: true, id: row.id, source: "db", skipEmail: false };
 }
 
+// ─── Constraint-violation detection (#6254 AC-11) ──────────────────────────────
+
+/**
+ * SQLSTATE class 23 — "integrity constraint violation" — covers a NOT NULL
+ * (23502), a CHECK (23514), a unique (23505) or a foreign-key (23503)
+ * violation. Two of Prisma's own mapped codes correspond to a class-23
+ * violation on a `.create()` call: P2002 (unique) and P2011 (null
+ * constraint) — both `PrismaClientKnownRequestError`s Prisma classifies
+ * from its OWN schema knowledge. The new `<table>_workspace_site_agree`
+ * CHECK (database/migrations/20260922120000_tenancy_fence) has no such
+ * schema-level representation — Prisma cannot classify a raw CHECK it does
+ * not know about, so the raw Postgres SQLSTATE is read defensively from
+ * wherever the error actually carries it: `error.meta.code` (some engine/
+ * adapter combinations thread it through there) or the error message text
+ * (every Postgres client library's message includes the SQLSTATE and/or the
+ * words "constraint"/"null value" verbatim).
+ */
+// P2000 (value too long) is deliberately excluded — a data-length validation
+// error, not a SQLSTATE class-23 integrity-constraint violation (security
+// review finding, PR #6360): it doesn't correspond to 23502/23503/23505/
+// 23514, so treating it as one would take this path for a case AC-11 does
+// not target.
+const PRISMA_CLASS_23_CODES = new Set(["P2002", "P2003", "P2004", "P2011"]);
+
+function isConstraintViolation(error: unknown): boolean {
+  if (error == null || typeof error !== "object") return false;
+
+  const code = (error as { code?: unknown }).code;
+  if (typeof code === "string" && PRISMA_CLASS_23_CODES.has(code)) return true;
+
+  const metaCode = (error as { meta?: { code?: unknown } }).meta?.code;
+  if (typeof metaCode === "string" && /^23\d{3}$/.test(metaCode)) return true;
+
+  const message = (error as { message?: unknown }).message;
+  if (typeof message === "string") {
+    // Labeled SQLSTATE only — "code: '23514'", "(SQLSTATE 23502)", etc. A
+    // bare `\b23\d{3}\b` anywhere in the message (security review finding,
+    // PR #6360) would also match a coincidental 5-digit number in a genuine
+    // outage's own text (a port, a byte count, a timeout in ms), stealing
+    // that case away from the file fallback it should still take.
+    if (/\b(?:sqlstate|code)[:\s]*['"]?23\d{3}['"]?/i.test(message)) return true;
+    if (/violates (check|not-null|unique|foreign key) constraint/i.test(message)) {
+      return true;
+    }
+    if (/null value in column/i.test(message)) return true;
+  }
+
+  return false;
+}
+
 // ─── Email ────────────────────────────────────────────────────────────────────
 
 type EmailResult =
@@ -174,7 +272,38 @@ type EmailResult =
 async function sendEmail(
   input: RouteLeadInput,
   id: string,
+  persisted: "db" | "file",
 ): Promise<EmailResult> {
+  // Request-and-confirm SUPERSEDES this notification for a callback (#5970
+  // D6). AC-1 requires the tenant to receive exactly one email, and the
+  // confirm message carries strictly more than this one does — the same
+  // request details, plus the link that confirms a time and a price. Sending
+  // both would be two; sending this one and not that one would lose the
+  // feature. `submit` and `subscribe` are untouched.
+  //
+  // The predicate lives in request-confirm.ts and is read by both sides, so
+  // the two cannot both fire. It does NOT by itself rule out zero — see that
+  // function's header for what the coupling does and does not guarantee, and
+  // for the `persisted` term below, which is what closed the one zero case
+  // that was reachable in production. With the feature unconfigured — the
+  // default, and what every existing leads suite runs under — this is false
+  // and every byte below is reached as before.
+  // `persisted === "db"` is load-bearing, not decoration (#5970 security
+  // review round 3, M1). The confirm message can only supersede this one if it
+  // is actually going to be sent, and it can only be sent against a ROW: the
+  // credential is minted by an `updateMany` on `callbacks`. On the FILE
+  // FALLBACK path — a DB outage, an unset DATABASE_URL, an exhausted pool —
+  // there is no row, so suppressing here would have produced ZERO operator
+  // emails for every callback captured during the outage, on the one surface
+  // whose whole purpose is that an outage must not lose a lead.
+  if (
+    input.kind === "callback" &&
+    persisted === "db" &&
+    requestConfirmSupersedesNotification()
+  ) {
+    return { skipped: true, reason: "request_confirm" };
+  }
+
   const to = process.env.AILK_LEAD_NOTIFICATION_TO;
   const from = process.env.AILK_LEAD_NOTIFICATION_FROM;
 
@@ -265,6 +394,36 @@ export async function routeLead(
     skipEmail = dbResult.skipEmail;
     skipReason = dbResult.skipReason;
   } catch (dbErr) {
+    // #6254 AC-11 (spec D6, SEC-02) — a constraint violation is OUR OWN
+    // derivation producing a row Postgres itself refuses (an unresolved
+    // workspaceId hitting NOT NULL, or a site<->workspace disagreement
+    // hitting the new equality CHECK) — a bug to surface, never an outage
+    // to degrade through. Falling back here would return a silent 201 while
+    // the Lead never lands in Postgres, invisible to the Inbox forever —
+    // the exact silent data loss AC-7 exists to close, merely relocated
+    // onto this never-gate surface.
+    //
+    // A DELIBERATE error response, not a bare re-raise (spec § 7's
+    // api-versioning waiver is conditioned on exactly this: "a documented
+    // error body, never a bare re-raise surfacing as an unhandled throw").
+    // `persist_failed` already maps to a 503 with a documented body
+    // (`routes/leads/index.ts`) — the SAME shape a genuine DB-outage
+    // failure (both DB and file fail) already returns, so this adds no new
+    // response shape, only a new path that reaches the existing one
+    // WITHOUT first trying — and losing time to — a file write for an
+    // error the file fallback can never fix.
+    //
+    // A GENUINE infrastructure failure (an unreachable DB, an exhausted
+    // pool, an unset DATABASE_URL) is NOT a constraint violation and still
+    // takes the file fallback below, unchanged.
+    if (isConstraintViolation(dbErr)) {
+      const dbMsg = dbErr instanceof Error ? dbErr.message : String(dbErr);
+      return {
+        ok: false,
+        error: { kind: "persist_failed", message: `db: ${dbMsg}` },
+      };
+    }
+
     // 5. File fallback
     // Include a UUID suffix so concurrent fallbacks produce unique IDs even
     // within the same millisecond. Format still matches /^[a-z0-9_-]{8,64}$/i.
@@ -331,7 +490,7 @@ export async function routeLead(
   if (skipEmail) {
     emailResult = { skipped: true, reason: skipReason ?? "skipped" };
   } else {
-    emailResult = await sendEmail(input, id!);
+    emailResult = await sendEmail(input, id!, persisted!);
   }
 
   return { ok: true, id: id!, persisted, email: emailResult };