create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/flow-engine.test.ts

@@ -0,0 +1,2840 @@
+/**
+ * @file flow-engine.test.ts
+ * @description Unit tests for the flow-engine service (#3956 D3).
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper → prisma-client.js mock; prisma singleton via __mocks__/prisma.ts)
+ *   - @working-theory/email sendLeadNotification (transitively, via lead-routing.ts's routeLead)
+ *     + sendDeliverableEmail (transitively, via ../deliverable-fulfillment.js's fulfillDeliverable, #3961)
+ *
+ * Internal modules run real:
+ *   - ../lead-routing (routeLead) — real, exercising the actual completion composition (AC4)
+ *   - ../deliverable-fulfillment (fulfillDeliverable) — real, exercising the actual D4 completion
+ *     seam; its own resolution/grant/email logic is covered directly by
+ *     deliverable-fulfillment.test.ts, so this file asserts only the CALL — that the
+ *     completion branch reaches the real service, with the request-local segment, under
+ *     the "no block → no call" gate, and that its failures never fail the submission
+ *   - apps/api/src/services/enrichment-shim — real; @working-theory/license catches + returns lead unchanged
+ *   - apps/api/src/lib/file-fallback — real; unused here since prisma.lead.create is mocked to succeed
+ *   - ../waitlist-scoring (scoreCompletedSignup, #4662 D6) — real, exercising the actual
+ *     completion-hook composition; its own evaluator/glue logic is covered directly by
+ *     packages/validation's + apps/api's own waitlist-scoring.test.ts, so this file
+ *     asserts only the CALL — that a snapshot carrying `configSnapshot.experiment`
+ *     reaches the real service (observed via the mocked prisma.waitlistExperiment /
+ *     prisma.waitlistScore boundary it reads/writes), that a snapshot without it never
+ *     touches that boundary, and that its failures never fail the submission
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- prisma is a DB boundary; __mocks__/prisma.ts activates the auto-mock (Jest requires explicit call for local files)
+jest.mock("../../lib/prisma.js");
+
+const mockSendDeliverableEmail = jest.fn().mockResolvedValue({
+  ok: true,
+  messageId: "msg-deliverable-test",
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({
+    ok: true,
+    messageId: "msg-test",
+  }),
+  sendDeliverableEmail: (...args: unknown[]) =>
+    mockSendDeliverableEmail(...args),
+}));
+
+jest.mock("@working-theory/license", () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: "free",
+    plan: null,
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  }),
+}));
+
+// #4663 D6 — mock the A4 score service so AC6 exercises the engine's own
+// trigger/persist orchestration without a real crawl. aeo-score.ts wraps
+// the SSRF-guarded external-URL crawler (a network boundary), the same
+// class of boundary the prisma.js mock above keeps this file off of.
+const mockScoreUrl = jest.fn();
+const mockLoadExampleScore = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- aeo-score.ts is a network boundary (external crawl), same class as the DB mock above
+jest.mock("../aeo-score.js", () => ({
+  scoreUrl: (...args: unknown[]) => mockScoreUrl(...args),
+  loadExampleScore: (...args: unknown[]) => mockLoadExampleScore(...args),
+  resolveScoreBudgetMs: (raw: string | undefined) => {
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 6000;
+  },
+}));
+
+import { Prisma } from "@working-theory/database";
+import { FLOW_PRESETS } from "@working-theory/database/flows/presets";
+import { flowConfigSchema } from "@working-theory/validation";
+
+import { prisma } from "../../lib/prisma.js";
+import {
+  serveFlow,
+  submitStep,
+  seedFlowPresets,
+  upsertFlowDefinition,
+  cleanupAbandonedSessions,
+} from "../flow-engine";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const en = (s: string) => ({ en: s });
+
+const sourceMeta = {
+  ip: "127.0.0.1",
+  userAgent: "jest",
+  receivedAt: new Date().toISOString(),
+};
+
+function contactFirstFlow() {
+  return {
+    slug: "get-a-quote",
+    defaultLocale: "en",
+    steps: [
+      {
+        key: "contact",
+        type: "field" as const,
+        copy: { title: en("Let's get started") },
+        fields: [
+          {
+            name: "email",
+            inputType: "email" as const,
+            required: true,
+            mapsTo: "email" as const,
+            copy: { label: en("Email") },
+          },
+          {
+            name: "company",
+            inputType: "text" as const,
+            copy: { label: en("Company") },
+          },
+        ],
+      },
+      {
+        key: "budget",
+        type: "segmentation" as const,
+        copy: { title: en("What's your budget?") },
+        questions: [
+          {
+            name: "budget",
+            options: [
+              { value: "small", label: en("Under $10k") },
+              { value: "large", label: en("$10k+") },
+            ],
+          },
+        ],
+      },
+      {
+        key: "thanks",
+        type: "message" as const,
+        copy: { title: en("Thanks!") },
+      },
+    ],
+  };
+}
+
+// contactFirstFlow() extended with an #4661 D4 experiment binding — the A2
+// (#4662 D6) scoring hook's opt-in gate.
+function contactFirstFlowWithExperiment() {
+  const flow = contactFirstFlow();
+  return {
+    ...flow,
+    experiment: { key: "ailk-founder-diagnostic", waitlist: "founder_diagnostic" },
+  };
+}
+
+// The `WaitlistExperiment.config` row scoreCompletedSignup (#4662 D6) loads
+// for the `ailk-founder-diagnostic` / `founder_diagnostic` binding above —
+// its questionSet mirrors contactFirstFlow()'s "budget" question exactly, so
+// the real evaluator scores the same payload the flow assembles. tier "hot"
+// at budget_points ≥ 5 (large=10, small=1) is a real, minimal WaitlistScoring
+// register — not a mock of the evaluator itself.
+function waitlistExperimentConfigForFixture() {
+  return {
+    key: "ailk-founder-diagnostic",
+    mode: "qualifying" as const,
+    status: "draft" as const,
+    waitlists: [{ key: "founder_diagnostic", flowSlug: "get-a-quote" }],
+    questionSet: {
+      version: 1 as const,
+      questions: [
+        {
+          id: "email",
+          prompt: en("Your email"),
+          answerType: "email" as const,
+          mapsTo: "email" as const,
+        },
+        {
+          id: "budget",
+          prompt: en("What's your budget?"),
+          answerType: "single" as const,
+          options: [
+            { value: "small", label: en("Under $10k") },
+            { value: "large", label: en("$10k+") },
+          ],
+        },
+      ],
+    },
+    scoring: {
+      version: 1 as const,
+      points: [
+        {
+          name: "budget_points",
+          question: "budget",
+          kind: "optionWeights" as const,
+          weights: { small: 1, large: 10 },
+        },
+      ],
+      scores: { total: { sum: ["budget_points"] } },
+      tiers: [
+        { key: "hot", when: { score: "total", gte: 5 } },
+        // Never matches its own `when` — reachable only via the default
+        // fall-through, so "small" (total 1) is distinguishable from
+        // "large" (total 10) in the persisted tier.
+        { key: "cold", when: { score: "total", lte: -1 } },
+      ],
+      default: "cold",
+    },
+    tracking: {
+      version: 1 as const,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { founder_diagnostic: { campaign: "launch", channels: ["organic"] } },
+    },
+    stripeConfigRef: null,
+  };
+}
+
+// contactFirstFlow() extended with a segments band map on the "budget"
+// question (#3959 D1) — small -> "starter", large -> "enterprise". A
+// "thanks" message step still follows, so landing "budget" alone does not
+// complete the session.
+function contactFirstFlowWithSegments() {
+  const flow = contactFirstFlow();
+  const budgetStep = flow.steps.find((s) => s.key === "budget")!;
+  (budgetStep as typeof budgetStep & { segments?: unknown }).segments = {
+    question: "budget",
+    bands: [
+      { key: "starter", values: ["small"] },
+      { key: "enterprise", values: ["large"] },
+    ],
+  };
+  return flow;
+}
+
+// The #3959 D3 terminal-segmentation-step fixture: segmentation is the
+// LAST step (no trailing message step), so ONE submission both lands the
+// band map AND completes the session — the exact shape that would surface
+// a stale-`session.segment` bug if completion read the row instead of the
+// request-local derived value.
+function contactThenBudgetOnlyFlowWithSegments() {
+  return {
+    slug: "get-a-quote",
+    defaultLocale: "en",
+    steps: [
+      {
+        key: "contact",
+        type: "field" as const,
+        copy: { title: en("Let's get started") },
+        fields: [
+          {
+            name: "email",
+            inputType: "email" as const,
+            required: true,
+            mapsTo: "email" as const,
+            copy: { label: en("Email") },
+          },
+        ],
+      },
+      {
+        key: "budget",
+        type: "segmentation" as const,
+        copy: { title: en("What's your budget?") },
+        questions: [
+          {
+            name: "budget",
+            options: [
+              { value: "small", label: en("Under $10k") },
+              { value: "large", label: en("$10k+") },
+            ],
+          },
+        ],
+        segments: {
+          question: "budget",
+          bands: [
+            { key: "starter", values: ["small"] },
+            { key: "enterprise", values: ["large"] },
+          ],
+        },
+      },
+    ],
+  };
+}
+
+// #3961 D4 — contactThenBudgetOnlyFlowWithSegments() extended with a
+// deliverables asset map keyed on the same "starter"/"enterprise" bands —
+// the segmentation-last single-submission fixture, so landing "budget"
+// both derives the segment AND fires fulfillment in the same request.
+function contactThenBudgetOnlyFlowWithDeliverables() {
+  const flow = contactThenBudgetOnlyFlowWithSegments();
+  return {
+    ...flow,
+    deliverables: {
+      assets: [
+        { segment: "starter", assetKey: "guide-starter" },
+        { segment: "enterprise", assetKey: "guide-enterprise" },
+      ],
+      copy: {
+        subject: en("Here's your guide"),
+        body: en("Thanks — your download is attached."),
+      },
+    },
+  };
+}
+
+// #4769 AC4 — a SERVED `mode: "recommending"` flow: one segmentation step
+// (no `mapsTo` field, mirroring `noEmailFlow()`'s D9 shape below) plus the
+// register's `offers`/`mode`/`recommendation` marker, exactly what
+// `compileWaitlistFlow` (packages/validation) carries verbatim under the
+// `mode === "recommending"` gate. Exercises the SERVED shape directly since
+// `flow-engine.ts` needs no production change (D1/D1a) — `locateStep`
+// already refuses an unknown `stepKey`, and `completeSubmission` already
+// completes without a Lead row when no field maps to email.
+function recommendingServedFlow() {
+  return {
+    slug: "ailk-recommender",
+    defaultLocale: "en",
+    steps: [
+      {
+        key: "q_team",
+        type: "segmentation" as const,
+        copy: { title: en("What best describes your team?") },
+        questions: [
+          {
+            name: "q_team",
+            options: [
+              { value: "solo", label: en("Just me") },
+              { value: "small_team", label: en("A small team") },
+            ],
+          },
+        ],
+        resultsReveal: true as const,
+      },
+    ],
+    mode: "recommending" as const,
+    offers: [
+      {
+        key: "free_oss",
+        copy: { name: en("Free (OSS)") },
+        price: { kind: "label" as const, label: en("Free — self-hosted") },
+        rules: [
+          {
+            when: { answer: "q_team", eq: "solo" },
+            reason: en("Solo builders get the substrate free."),
+          },
+        ],
+      },
+    ],
+    recommendation: {
+      key: "recommendation",
+      copy: { title: en("Your recommendation") },
+    },
+  };
+}
+
+// A flow with no mapsTo:'email' field (D9's legal-but-unused path).
+function noEmailFlow() {
+  return {
+    slug: "feedback",
+    defaultLocale: "en",
+    steps: [
+      {
+        key: "rating",
+        type: "segmentation" as const,
+        copy: { title: en("How was it?") },
+        questions: [
+          {
+            name: "rating",
+            options: [
+              { value: "good", label: en("Good") },
+              { value: "bad", label: en("Bad") },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const SITE_ID = "site-abc";
+const SESSION_ID = "flsess_00000000-0000-7000-8000-0000000000c1";
+const DEFINITION_ID = "flow_00000000-0000-7000-8000-0000000000d1";
+
+describe("flow-engine", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env.DATABASE_URL = "postgres://stub";
+  });
+
+  afterEach(() => {
+    delete process.env.DATABASE_URL;
+  });
+
+  // ── D5 — DB required ────────────────────────────────────────────────────
+
+  describe("flows_not_configured (D5)", () => {
+    it("serveFlow returns flows_not_configured when DATABASE_URL is unset", async () => {
+      delete process.env.DATABASE_URL;
+      const result = await serveFlow(SITE_ID, "get-a-quote");
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "flows_not_configured", message: expect.any(String) },
+      });
+      expect(prisma.flowDefinition.findUnique).not.toHaveBeenCalled();
+    });
+
+    it("submitStep returns flows_not_configured when DATABASE_URL is unset", async () => {
+      delete process.env.DATABASE_URL;
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: {},
+        },
+        sourceMeta,
+      );
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "flows_not_configured", message: expect.any(String) },
+      });
+    });
+  });
+
+  // ── serveFlow ────────────────────────────────────────────────────────────
+
+  describe("serveFlow", () => {
+    it("returns the validated FlowConfig for a stored definition", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        config: contactFirstFlow(),
+      });
+
+      const result = await serveFlow(SITE_ID, "get-a-quote");
+
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.config.slug).toBe("get-a-quote");
+        expect(result.config.steps.map((s) => s.type)).toEqual([
+          "field",
+          "segmentation",
+          "message",
+        ]);
+      }
+      expect(prisma.flowDefinition.findUnique).toHaveBeenCalledWith({
+        where: { siteId_slug: { siteId: SITE_ID, slug: "get-a-quote" } },
+      });
+    });
+
+    it("returns flow_not_found when no definition exists for the slug", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue(null);
+
+      const result = await serveFlow(SITE_ID, "missing");
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "flow_not_found", message: expect.any(String) },
+      });
+    });
+  });
+
+  // ── upsertFlowDefinition (D6) ────────────────────────────────────────────
+
+  describe("upsertFlowDefinition", () => {
+    it("validates + upserts a well-formed config", async () => {
+      (prisma.flowDefinition.upsert as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+      });
+
+      const result = await upsertFlowDefinition(SITE_ID, contactFirstFlow());
+
+      expect(result).toEqual({ ok: true, id: DEFINITION_ID });
+      expect(prisma.flowDefinition.upsert).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { siteId_slug: { siteId: SITE_ID, slug: "get-a-quote" } },
+        }),
+      );
+    });
+
+    it("rejects an invalid config without touching prisma", async () => {
+      const result = await upsertFlowDefinition(SITE_ID, { not: "a flow" });
+
+      expect(result.ok).toBe(false);
+      expect(prisma.flowDefinition.upsert).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── seedFlowPresets (#3958 §3.3 — reuse, do not duplicate) ──────────────
+
+  describe("seedFlowPresets", () => {
+    it("upserts each preset once, in order, through upsertFlowDefinition", async () => {
+      (prisma.flowDefinition.upsert as jest.Mock)
+        .mockResolvedValueOnce({ id: "flow_a" })
+        .mockResolvedValueOnce({ id: "flow_b" });
+
+      const presetA = { ...contactFirstFlow(), slug: "form" };
+      const presetB = { ...contactFirstFlow(), slug: "waitlist" };
+
+      const result = await seedFlowPresets(SITE_ID, [presetA, presetB]);
+
+      expect(result).toEqual({ ok: true, seeded: ["form", "waitlist"] });
+      expect(prisma.flowDefinition.upsert).toHaveBeenCalledTimes(2);
+      expect(prisma.flowDefinition.upsert).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          where: { siteId_slug: { siteId: SITE_ID, slug: "form" } },
+        }),
+      );
+      expect(prisma.flowDefinition.upsert).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          where: { siteId_slug: { siteId: SITE_ID, slug: "waitlist" } },
+        }),
+      );
+    });
+
+    it("stops at the first invalid preset and reports what seeded before it — never a silent partial success", async () => {
+      (prisma.flowDefinition.upsert as jest.Mock).mockResolvedValueOnce({
+        id: "flow_a",
+      });
+
+      const presetA = { ...contactFirstFlow(), slug: "form" };
+      const invalid = { not: "a flow" };
+
+      const result = await seedFlowPresets(SITE_ID, [presetA, invalid]);
+
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.seeded).toEqual(["form"]);
+        expect(result.error.kind).toBe("invalid_input");
+      }
+      // Only presetA's upsert fires — the invalid second preset stops the
+      // loop before a second (rejected) call is ever attempted.
+      expect(prisma.flowDefinition.upsert).toHaveBeenCalledTimes(1);
+    });
+
+    it("is idempotent — re-running upserts the same slug again rather than duplicating", async () => {
+      (prisma.flowDefinition.upsert as jest.Mock)
+        .mockResolvedValueOnce({ id: "flow_a" })
+        .mockResolvedValueOnce({ id: "flow_a" });
+
+      const preset = { ...contactFirstFlow(), slug: "form" };
+
+      const first = await seedFlowPresets(SITE_ID, [preset]);
+      const second = await seedFlowPresets(SITE_ID, [preset]);
+
+      expect(first).toEqual({ ok: true, seeded: ["form"] });
+      expect(second).toEqual({ ok: true, seeded: ["form"] });
+      expect(prisma.flowDefinition.upsert).toHaveBeenCalledTimes(2);
+      // Both calls target the SAME siteId_slug key — an upsert on re-run,
+      // never a second row for the same preset.
+      for (const call of (prisma.flowDefinition.upsert as jest.Mock).mock
+        .calls) {
+        expect(call[0]).toEqual(
+          expect.objectContaining({
+            where: { siteId_slug: { siteId: SITE_ID, slug: "form" } },
+          }),
+        );
+      }
+    });
+
+    it("the real FLOW_PRESETS array seeds cleanly end to end (every declared preset, whatever the current set is)", async () => {
+      // Derived from FLOW_PRESETS itself (DEF-007) — never a hardcoded
+      // enumeration of preset slugs, so adding a new preset (e.g. #3963's
+      // "roadmap") can't re-break this assertion the way a fixed
+      // ["form", "waitlist", "lead-magnet"] literal did (#4008 CI red).
+      (prisma.flowDefinition.upsert as jest.Mock).mockImplementation(
+        (args: { where: { siteId_slug: { slug: string } } }) =>
+          Promise.resolve({
+            id: `flow_${args.where.siteId_slug.slug.replace(/-/g, "_")}`,
+          }),
+      );
+
+      const result = await seedFlowPresets(SITE_ID, FLOW_PRESETS);
+
+      expect(result).toEqual({
+        ok: true,
+        seeded: FLOW_PRESETS.map((p) => p.slug),
+      });
+      expect(prisma.flowDefinition.upsert).toHaveBeenCalledTimes(
+        FLOW_PRESETS.length,
+      );
+    });
+  });
+
+  // ── submitStep — session creation + per-step persistence ────────────────
+
+  describe("submitStep — session lifecycle", () => {
+    it("creates a session on the first submission (no sessionId)", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "lead@example.com" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        sessionId: SESSION_ID,
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      });
+      expect(prisma.flowSession.create).toHaveBeenCalledTimes(1);
+      // The partial-state capture — persisted immediately, not batched.
+      expect(prisma.flowSession.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { id: SESSION_ID },
+          data: expect.objectContaining({
+            state: { contact: { email: "lead@example.com" } },
+            email: "lead@example.com",
+          }),
+        }),
+      );
+    });
+
+    it("returns flow_not_found when no sessionId AND no definition exists for the slug", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue(null);
+
+      const result = await submitStep(
+        { siteId: SITE_ID, slug: "missing", stepKey: "contact", values: {} },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "flow_not_found", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    });
+
+    it("reuses an in-progress session when sessionId is supplied", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        sessionId: SESSION_ID,
+        landed: "budget",
+        nextStepKey: "thanks",
+        completed: false,
+      });
+      expect(prisma.flowDefinition.findUnique).not.toHaveBeenCalled();
+      expect(prisma.flowSession.create).not.toHaveBeenCalled();
+    });
+
+    it("returns step_conflict for an unknown sessionId", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue(null);
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: "flsess_does-not-exist",
+          stepKey: "budget",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "step_conflict", message: expect.any(String) },
+      });
+    });
+
+    it("returns step_conflict when sessionId belongs to a different flow (flowSlug mismatch)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "feedback", // a DIFFERENT flow than the one being submitted to
+        configSnapshot: noEmailFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "step_conflict", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    });
+
+    it("returns step_conflict when resubmitting to an already-completed session", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {},
+        email: "lead@example.com",
+        leadId: "lead_x",
+        completedAt: new Date(),
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "step_conflict", message: expect.any(String) },
+      });
+    });
+
+    it("returns step_conflict for an unknown stepKey in the snapshot", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "does_not_exist",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "step_conflict", message: expect.any(String) },
+      });
+    });
+  });
+
+  // ── submitStep — recommending mode: no-PII completion + unsubmittable
+  // recommendation marker (#4769 AC4) ──────────────────────────────────────
+
+  describe("submitStep — recommending mode (#4769 AC4)", () => {
+    it("completes through submitStep on question answers alone, with no field mapping to email/name/phone submitted and no Lead row created", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "ailk-recommender",
+        configSnapshot: recommendingServedFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "ailk-recommender",
+          sessionId: SESSION_ID,
+          stepKey: "q_team",
+          values: { q_team: "solo" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(result.ok && result.leadId).toBeUndefined();
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+      expect(prisma.flowSession.update).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          where: { id: SESSION_ID },
+          data: { completedAt: expect.any(Date) },
+        }),
+      );
+    });
+
+    it("returns step_conflict, without throwing, when the recommendation marker's key is submitted", async () => {
+      const flow = recommendingServedFlow();
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "ailk-recommender",
+        configSnapshot: flow,
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "ailk-recommender",
+          sessionId: SESSION_ID,
+          stepKey: flow.recommendation.key,
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "step_conflict", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── submitStep — session locale persistence (#3962 D3) ──────────────────
+
+  describe("submitStep — session locale persistence (#3962 D3)", () => {
+    it("persists the explicit locale on session create", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "lead@example.com" },
+          locale: "pt-BR",
+        },
+        sourceMeta,
+      );
+
+      expect(prisma.flowSession.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ locale: "pt-BR" }),
+        }),
+      );
+    });
+
+    it("falls back to the config's defaultLocale when no locale is submitted", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(), // defaultLocale: "en"
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "lead@example.com" },
+        },
+        sourceMeta,
+      );
+
+      expect(prisma.flowSession.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ locale: "en" }),
+        }),
+      );
+    });
+
+    it("does not update locale when resuming an existing session (set once at create)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+          locale: "es",
+        },
+        sourceMeta,
+      );
+
+      expect(prisma.flowSession.create).not.toHaveBeenCalled();
+      for (const call of (prisma.flowSession.update as jest.Mock).mock.calls) {
+        expect(call[0].data).not.toHaveProperty("locale");
+      }
+    });
+  });
+
+  // ── submitStep — value validation ───────────────────────────────────────
+
+  describe("submitStep — required fields + select/segmentation membership (D3)", () => {
+    it("rejects a missing required field", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    });
+
+    it("rejects a malformed value for an email-typed field (so it can never fail routeLead silently at completion)", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "not-an-email" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    });
+
+    it("rejects an over-length email value (>254, leadSubmitSchema's own bound) rather than letting it fail routeLead silently at completion", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+
+      const overLengthEmail = `${"a".repeat(250)}@example.com`; // > 254 chars
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: overLengthEmail },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    });
+
+    it("accepts a normal-length text-field value", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "lead@example.com", company: "Acme Inc." },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true });
+      expect(prisma.flowSession.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            state: {
+              contact: { email: "lead@example.com", company: "Acme Inc." },
+            },
+          }),
+        }),
+      );
+    });
+
+    it("rejects an over-length text-field value (>256) — security-review finding: unbounded text values", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: {
+            email: "lead@example.com",
+            company: "a".repeat(257),
+          },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    });
+
+    it("rejects a non-string value for a text field — security-review finding: unbounded/untyped values", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "lead@example.com", company: { nested: "object" } },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    });
+
+    it("rejects a segmentation answer that is not one of the declared options", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        completedAt: null,
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "not-a-real-option" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+    });
+
+    it("drops an undeclared key from values rather than persisting it", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "lead@example.com", attackerField: "smuggled" },
+        },
+        sourceMeta,
+      );
+
+      expect(prisma.flowSession.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            state: { contact: { email: "lead@example.com" } },
+          }),
+        }),
+      );
+    });
+  });
+
+  // ── AC2 — the abandon-after-email partial lead ──────────────────────────
+
+  describe("AC2 — abandon after the email step persists a partial lead", () => {
+    it("landing the contact step denormalizes session.email and persists state; the session never completes on its own", async () => {
+      (prisma.flowDefinition.findUnique as jest.Mock).mockResolvedValue({
+        id: DEFINITION_ID,
+        config: contactFirstFlow(),
+      });
+      (prisma.flowSession.create as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          stepKey: "contact",
+          values: { email: "abandoner@example.com" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: false });
+      // Exactly one persist for this one landed step — the partial-state
+      // capture happens on landing, not batched at the (never-reached) end.
+      expect(prisma.flowSession.update).toHaveBeenCalledTimes(1);
+      expect(prisma.flowSession.update).toHaveBeenCalledWith({
+        where: { id: SESSION_ID },
+        data: {
+          state: { contact: { email: "abandoner@example.com" } },
+          // #4663 D1/D2 — flags is re-derived + persisted on EVERY landing;
+          // a flow declaring no `flags` always re-derives `{}`.
+          flags: {},
+          email: "abandoner@example.com",
+        },
+      });
+      // completedAt is never touched — routeLead/completion is never reached.
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── AC4 — completion composes routeLead ─────────────────────────────────
+
+  describe("AC4 — completion composes routeLead", () => {
+    beforeEach(() => {
+      process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+      process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    });
+
+    afterEach(() => {
+      delete process.env.AILK_LEAD_NOTIFICATION_TO;
+      delete process.env.AILK_LEAD_NOTIFICATION_FROM;
+    });
+
+    it("completing the final step creates a Lead via routeLead and stamps completedAt + leadId", async () => {
+      const leadRowId = "lead_00000000-0000-7000-8000-0000000000e1";
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {
+          contact: { email: "complete@example.com" },
+          budget: { budget: "large" },
+        },
+        email: "complete@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({ id: leadRowId });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "thanks",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        landed: "thanks",
+        nextStepKey: null,
+        completed: true,
+        leadId: leadRowId,
+      });
+
+      // routeLead composition (source-code contract, not a mock — the real
+      // service ran and persisted via prisma.lead.create).
+      expect(prisma.lead.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            siteId: SITE_ID,
+            source: "flow:get-a-quote",
+            email: "complete@example.com",
+            payload: expect.objectContaining({
+              email: "complete@example.com",
+              budget: "large",
+              flowSlug: "get-a-quote",
+              locale: "en",
+            }),
+          }),
+        }),
+      );
+
+      // The completion stamp is a SECOND, distinct update from the per-step
+      // state persist (the two writes D3 describes: land, then complete).
+      expect(prisma.flowSession.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { id: SESSION_ID },
+          data: expect.objectContaining({
+            completedAt: expect.any(Date),
+            leadId: leadRowId,
+          }),
+        }),
+      );
+    });
+
+    it("D9 — a flow with no email-mapped field completes without a Lead row (the session is the record)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "feedback",
+        configSnapshot: noEmailFlow(),
+        state: {},
+        email: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "feedback",
+          sessionId: SESSION_ID,
+          stepKey: "rating",
+          values: { rating: "good" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(result.ok && result.leadId).toBeUndefined();
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+      expect(prisma.flowSession.update).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          where: { id: SESSION_ID },
+          data: { completedAt: expect.any(Date) },
+        }),
+      );
+    });
+  });
+
+  // ── #3961 D4 — deliverable fulfillment call ──────────────────────────────
+
+  describe("submitStep — deliverable fulfillment call (#3961 D4)", () => {
+    beforeEach(() => {
+      process.env.AILK_DELIVERABLE_EMAIL_FROM = "deliverable@example.com";
+      process.env.AILK_PUBLIC_API_URL = "https://api.example.com";
+      (prisma.deliverableAsset.findUnique as jest.Mock).mockResolvedValue({
+        id: "dasset_00000000-0000-7000-8000-0000000000a1",
+        siteId: SITE_ID,
+        key: "guide-starter",
+      });
+      (prisma.deliverableGrant.create as jest.Mock).mockResolvedValue({
+        id: "dgrant_00000000-0000-7000-8000-0000000000g1",
+      });
+    });
+
+    afterEach(() => {
+      delete process.env.AILK_DELIVERABLE_EMAIL_FROM;
+      delete process.env.AILK_PUBLIC_API_URL;
+    });
+
+    it("calls the real fulfillDeliverable once with the request-local segment on the leadResult.ok completion path", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactThenBudgetOnlyFlowWithDeliverables(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000e2",
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        completed: true,
+        segment: "starter",
+      });
+      // The real fulfillDeliverable resolved "starter"'s entry (guide-starter),
+      // minted a grant for it, and sent via the real (email-package-mocked)
+      // sendDeliverableEmail — the observable trail through its own real
+      // boundaries (prisma, @working-theory/email), never a mock of the
+      // service itself.
+      expect(prisma.deliverableAsset.findUnique).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: {
+            siteId_key: { siteId: SITE_ID, key: "guide-starter" },
+          },
+        }),
+      );
+      expect(prisma.deliverableGrant.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            siteId: SITE_ID,
+            assetId: "dasset_00000000-0000-7000-8000-0000000000a1",
+            leadId: "lead_00000000-0000-7000-8000-0000000000e2",
+            sessionId: SESSION_ID,
+          }),
+        }),
+      );
+      expect(mockSendDeliverableEmail).toHaveBeenCalledWith(
+        expect.objectContaining({
+          to: "lead@example.com",
+          downloadLink:
+            "https://api.example.com/v1/deliverables/dgrant_00000000-0000-7000-8000-0000000000g1",
+        }),
+      );
+    });
+
+    it("no deliverables block → no call (AC4 regression floor)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {
+          contact: { email: "complete@example.com" },
+          budget: { budget: "large" },
+        },
+        email: "complete@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000e3",
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "thanks",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(prisma.deliverableAsset.findUnique).not.toHaveBeenCalled();
+      expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+      expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+    });
+
+    it("a genuine fulfillDeliverable failure (a DB boundary throw) does not fail the submission", async () => {
+      // A real, unexpected exception escaping fulfillDeliverable's own
+      // internal log-and-skip postures (which cover expected business
+      // misses, not exceptions) — the residual case flow-engine.ts's
+      // try/catch exists for (D4).
+      (prisma.deliverableAsset.findUnique as jest.Mock).mockRejectedValue(
+        new Error("boom"),
+      );
+
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactThenBudgetOnlyFlowWithDeliverables(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000e4",
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+      expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── #4662 D6 — waitlist scoring hook call ────────────────────────────────
+
+  describe("submitStep — waitlist scoring hook call (#4662 D6)", () => {
+    it("evaluates + persists exactly one waitlistScore row on a snapshot carrying `experiment`", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlowWithExperiment(),
+        state: {
+          contact: { email: "lead@example.com" },
+          budget: { budget: "large" },
+        },
+        email: "lead@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000f1",
+      });
+      (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+        config: waitlistExperimentConfigForFixture(),
+      });
+      (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_1" });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "thanks",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(prisma.waitlistExperiment.findUnique).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: { siteId_key: { siteId: SITE_ID, key: "ailk-founder-diagnostic" } },
+        }),
+      );
+      expect(prisma.waitlistScore.upsert).toHaveBeenCalledTimes(1);
+      expect(prisma.waitlistScore.upsert).toHaveBeenCalledWith(
+        expect.objectContaining({
+          // The composite key since #5036 D6d — one row per (lead, EXPERIMENT),
+          // not per lead, so a visitor who joins two founders' waitlists keeps
+          // both scores.
+          where: {
+            leadId_experimentKey: {
+              leadId: "lead_00000000-0000-7000-8000-0000000000f1",
+              experimentKey: "ailk-founder-diagnostic",
+            },
+          },
+          create: expect.objectContaining({
+            siteId: SITE_ID,
+            leadId: "lead_00000000-0000-7000-8000-0000000000f1",
+            experimentKey: "ailk-founder-diagnostic",
+            waitlistKey: "founder_diagnostic",
+            tier: "hot",
+            score: 10,
+            categoryScores: { total: 10 },
+          }),
+        }),
+      );
+    });
+
+    it("a thrown scoring error (a genuine DB boundary failure) still completes the submission with leadId", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlowWithExperiment(),
+        state: {
+          contact: { email: "lead2@example.com" },
+          budget: { budget: "small" },
+        },
+        email: "lead2@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000f2",
+      });
+      (prisma.waitlistExperiment.findUnique as jest.Mock).mockRejectedValue(
+        new Error("boom"),
+      );
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "thanks",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        completed: true,
+        leadId: "lead_00000000-0000-7000-8000-0000000000f2",
+      });
+      expect(prisma.waitlistScore.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a snapshot without `experiment` never touches waitlistExperiment/waitlistScore and yields a payload byte-identical to today (AC4 regression floor)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(),
+        state: {
+          contact: { email: "lead3@example.com" },
+          budget: { budget: "large" },
+        },
+        email: "lead3@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000f3",
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "thanks",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(prisma.waitlistExperiment.findUnique).not.toHaveBeenCalled();
+      expect(prisma.waitlistScore.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a smuggled tier submitted on an earlier step never influences the persisted evaluation (declared-names-only extraction, defense in depth)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlowWithExperiment(),
+        state: { contact: { email: "lead4@example.com" } },
+        email: "lead4@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      // "budget" is a segmentation step declaring only the "budget"
+      // question — a smuggled "tier" key in the same submission is dropped
+      // by extractStepValues's declared-names-only extraction before it
+      // ever reaches session.state, and therefore before it can reach the
+      // assembled `payload` the scorer receives.
+      const budgetResult = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "large", tier: "hot" },
+        },
+        sourceMeta,
+      );
+      expect(budgetResult).toMatchObject({ ok: true, completed: false });
+      const lastUpdateCall = (prisma.flowSession.update as jest.Mock).mock.calls.at(-1)![0] as {
+        data: { state: Record<string, Record<string, unknown>> };
+      };
+      expect(lastUpdateCall.data.state["budget"]).toEqual({ budget: "large" });
+      expect(lastUpdateCall.data.state["budget"]).not.toHaveProperty("tier");
+
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlowWithExperiment(),
+        state: {
+          contact: { email: "lead4@example.com" },
+          budget: { budget: "large" },
+        },
+        email: "lead4@example.com",
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.lead.create as jest.Mock).mockResolvedValue({
+        id: "lead_00000000-0000-7000-8000-0000000000f4",
+      });
+      (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+        config: waitlistExperimentConfigForFixture(),
+      });
+      (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_2" });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "thanks",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, completed: true });
+      expect(prisma.waitlistScore.upsert).toHaveBeenCalledTimes(1);
+      const [call] = (prisma.waitlistScore.upsert as jest.Mock).mock.calls;
+      const created = (call![0] as { create: { tier: string } }).create;
+      // "large" alone (no smuggled tier) evaluates to "hot" (total 10 ≥ 5) —
+      // the smuggled "tier":"hot" answer value made no difference because
+      // there is no mechanism that reads it: it is neither a declared field
+      // (dropped before session.state) nor a question the scorer's
+      // answersFromPayload maps to any answer.
+      expect(created.tier).toBe("hot");
+    });
+  });
+
+  // ── #3959 D3/D4 — segment derivation ─────────────────────────────────────
+
+  describe("submitStep — segment derivation (#3959 D3)", () => {
+    it("derives + persists the segment in the SAME write as state, on landing a segmentation step declaring a band map", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlowWithSegments(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({
+        ok: true,
+        completed: false,
+        segment: "starter",
+      });
+      // Exactly one write — state + segment persisted together, not two
+      // separate updates.
+      expect(prisma.flowSession.update).toHaveBeenCalledTimes(1);
+      expect(prisma.flowSession.update).toHaveBeenCalledWith({
+        where: { id: SESSION_ID },
+        data: {
+          state: {
+            contact: { email: "lead@example.com" },
+            budget: { budget: "small" },
+          },
+          flags: {},
+          segment: "starter",
+        },
+      });
+    });
+
+    it("an abandoned session (segmentation landed, no trailing step submitted) carries the segment with completedAt still null — only the per-step write ran", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlowWithSegments(),
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "large" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, segment: "enterprise" });
+      expect(prisma.lead.create).not.toHaveBeenCalled();
+      // Exactly one write — the per-step persist; no completion-stamping
+      // second write ran (the session never completed).
+      expect(prisma.flowSession.update).toHaveBeenCalledTimes(1);
+    });
+
+    it("no band map on the segmentation step derives nothing and submits unchanged (existing #3956 behavior)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowId: DEFINITION_ID,
+        flowSlug: "get-a-quote",
+        configSnapshot: contactFirstFlow(), // no segments block
+        state: { contact: { email: "lead@example.com" } },
+        email: "lead@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "get-a-quote",
+          sessionId: SESSION_ID,
+          stepKey: "budget",
+          values: { budget: "small" },
+        },
+        sourceMeta,
+      );
+
+      expect(result.ok && result.segment).toBeUndefined();
+      expect(prisma.flowSession.update).toHaveBeenCalledWith({
+        where: { id: SESSION_ID },
+        data: {
+          state: {
+            contact: { email: "lead@example.com" },
+            budget: { budget: "small" },
+          },
+          flags: {},
+        },
+      });
+    });
+
+    describe("completion — payload.segment (#3959 D4)", () => {
+      it("writes payload.segment LAST, from the request-local value; a smuggled `values.segment` never reaches state or payload", async () => {
+        (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+          id: SESSION_ID,
+          siteId: SITE_ID,
+          flowId: DEFINITION_ID,
+          flowSlug: "get-a-quote",
+          configSnapshot: contactFirstFlowWithSegments(),
+          state: {
+            contact: { email: "complete@example.com" },
+            budget: { budget: "large" },
+          },
+          email: "complete@example.com",
+          segment: "enterprise",
+          leadId: null,
+          completedAt: null,
+        });
+        (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+        (prisma.lead.create as jest.Mock).mockResolvedValue({
+          id: "lead_00000000-0000-7000-8000-0000000000e2",
+        });
+
+        const result = await submitStep(
+          {
+            siteId: SITE_ID,
+            slug: "get-a-quote",
+            sessionId: SESSION_ID,
+            stepKey: "thanks",
+            // "segment" is not a declared field/question on the "thanks"
+            // message step — extractStepValues drops it unconditionally.
+            values: { segment: "attacker-supplied" },
+          },
+          sourceMeta,
+        );
+
+        expect(result).toMatchObject({
+          ok: true,
+          completed: true,
+          segment: "enterprise",
+        });
+        expect(prisma.lead.create).toHaveBeenCalledWith(
+          expect.objectContaining({
+            data: expect.objectContaining({
+              payload: expect.objectContaining({ segment: "enterprise" }),
+            }),
+          }),
+        );
+      });
+
+      it("the terminal-segmentation-step case — ONE submission landing segmentation AND completion carries the request-local segment, never the stale pre-update session.segment", async () => {
+        (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+          id: SESSION_ID,
+          siteId: SITE_ID,
+          flowId: DEFINITION_ID,
+          flowSlug: "get-a-quote",
+          configSnapshot: contactThenBudgetOnlyFlowWithSegments(),
+          state: { contact: { email: "terminal@example.com" } },
+          email: "terminal@example.com",
+          // The row's segment is still null — this request must derive it
+          // FRESH and use the local value, not this stale read.
+          segment: null,
+          leadId: null,
+          completedAt: null,
+        });
+        (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+        (prisma.lead.create as jest.Mock).mockResolvedValue({
+          id: "lead_00000000-0000-7000-8000-0000000000e3",
+        });
+
+        const result = await submitStep(
+          {
+            siteId: SITE_ID,
+            slug: "get-a-quote",
+            sessionId: SESSION_ID,
+            stepKey: "budget",
+            values: { budget: "large" },
+          },
+          sourceMeta,
+        );
+
+        expect(result).toMatchObject({
+          ok: true,
+          completed: true,
+          segment: "enterprise",
+        });
+        expect(prisma.lead.create).toHaveBeenCalledWith(
+          expect.objectContaining({
+            data: expect.objectContaining({
+              payload: expect.objectContaining({ segment: "enterprise" }),
+            }),
+          }),
+        );
+        // The per-step persist wrote segment too — the same write that
+        // landed state.
+        expect(prisma.flowSession.update).toHaveBeenCalledWith(
+          expect.objectContaining({
+            where: { id: SESSION_ID },
+            data: expect.objectContaining({ segment: "enterprise" }),
+          }),
+        );
+      });
+
+      it("no band map anywhere in the flow — completion payload carries no segment key", async () => {
+        (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+          id: SESSION_ID,
+          siteId: SITE_ID,
+          flowId: DEFINITION_ID,
+          flowSlug: "get-a-quote",
+          configSnapshot: contactFirstFlow(),
+          state: {
+            contact: { email: "plain@example.com" },
+            budget: { budget: "large" },
+          },
+          email: "plain@example.com",
+          segment: null,
+          leadId: null,
+          completedAt: null,
+        });
+        (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+        (prisma.lead.create as jest.Mock).mockResolvedValue({
+          id: "lead_00000000-0000-7000-8000-0000000000e4",
+        });
+
+        const result = await submitStep(
+          {
+            siteId: SITE_ID,
+            slug: "get-a-quote",
+            sessionId: SESSION_ID,
+            stepKey: "thanks",
+            values: {},
+          },
+          sourceMeta,
+        );
+
+        expect(result.ok && result.segment).toBeUndefined();
+        const call = (prisma.lead.create as jest.Mock).mock.calls[0][0];
+        expect(call.data.payload).not.toHaveProperty("segment");
+      });
+    });
+
+    // ── #4661 D4 — the experiment binding composes the Lead payload ────────
+
+    describe("completion — payload.experimentKey/waitlistKey (#4661 D4, a Signup composes the Lead)", () => {
+      it("writes experimentKey + waitlistKey LAST (after segment), from the snapshot's experiment block — the same lead row /v1/leads/submit persists", async () => {
+        const flowWithExperiment = {
+          ...contactFirstFlowWithSegments(),
+          experiment: { key: "my-experiment", waitlist: "enterprise_list" },
+        };
+        (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+          id: SESSION_ID,
+          siteId: SITE_ID,
+          flowId: DEFINITION_ID,
+          flowSlug: "get-a-quote",
+          configSnapshot: flowWithExperiment,
+          state: {
+            contact: { email: "signup@example.com" },
+            budget: { budget: "large" },
+          },
+          email: "signup@example.com",
+          segment: "enterprise",
+          leadId: null,
+          completedAt: null,
+        });
+        (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+        (prisma.lead.create as jest.Mock).mockResolvedValue({
+          id: "lead_00000000-0000-7000-8000-0000000000f1",
+        });
+
+        const result = await submitStep(
+          {
+            siteId: SITE_ID,
+            slug: "get-a-quote",
+            sessionId: SESSION_ID,
+            stepKey: "thanks",
+            values: {},
+          },
+          sourceMeta,
+        );
+
+        expect(result).toMatchObject({ ok: true, completed: true });
+        // AC1 — no second signup store: this IS the same lead.create call
+        // /v1/leads/submit's routeLead path uses, carrying every landed
+        // answer plus experimentKey/waitlistKey inside the one payload.
+        expect(prisma.lead.create).toHaveBeenCalledWith(
+          expect.objectContaining({
+            data: expect.objectContaining({
+              email: "signup@example.com",
+              payload: expect.objectContaining({
+                email: "signup@example.com",
+                budget: "large",
+                segment: "enterprise",
+                experimentKey: "my-experiment",
+                waitlistKey: "enterprise_list",
+              }),
+            }),
+          }),
+        );
+        // Key order — experimentKey/waitlistKey land AFTER segment (D4:
+        // "after segment is written and as the FINAL assignments").
+        const call = (prisma.lead.create as jest.Mock).mock.calls[0][0];
+        const keys = Object.keys(call.data.payload);
+        expect(keys.indexOf("experimentKey")).toBeGreaterThan(
+          keys.indexOf("segment"),
+        );
+        expect(keys.indexOf("waitlistKey")).toBeGreaterThan(
+          keys.indexOf("segment"),
+        );
+      });
+
+      it("a flow with no experiment block completes with a payload byte-identical to today (regression floor)", async () => {
+        (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+          id: SESSION_ID,
+          siteId: SITE_ID,
+          flowId: DEFINITION_ID,
+          flowSlug: "get-a-quote",
+          configSnapshot: contactFirstFlow(), // no `experiment` block
+          state: {
+            contact: { email: "plain2@example.com", company: "Acme" },
+            budget: { budget: "small" },
+          },
+          email: "plain2@example.com",
+          segment: null,
+          leadId: null,
+          completedAt: null,
+        });
+        (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+        (prisma.lead.create as jest.Mock).mockResolvedValue({
+          id: "lead_00000000-0000-7000-8000-0000000000f2",
+        });
+
+        await submitStep(
+          {
+            siteId: SITE_ID,
+            slug: "get-a-quote",
+            sessionId: SESSION_ID,
+            stepKey: "thanks",
+            values: {},
+          },
+          sourceMeta,
+        );
+
+        const call = (prisma.lead.create as jest.Mock).mock.calls[0][0];
+        expect(call.data.payload).not.toHaveProperty("experimentKey");
+        expect(call.data.payload).not.toHaveProperty("waitlistKey");
+        expect(call.data.payload).toEqual({
+          email: "plain2@example.com",
+          company: "Acme",
+          budget: "small",
+          flowSlug: "get-a-quote",
+          locale: "en",
+        });
+      });
+    });
+  });
+
+  // ── cleanupAbandonedSessions — retention/cleanup policy (#3974 AC3) ──────
+
+  describe("cleanupAbandonedSessions", () => {
+    it("returns flows_not_configured when DATABASE_URL is unset", async () => {
+      delete process.env.DATABASE_URL;
+
+      const result = await cleanupAbandonedSessions();
+
+      expect(result).toEqual({
+        ok: false,
+        error: { kind: "flows_not_configured", message: expect.any(String) },
+      });
+      expect(prisma.flowSession.deleteMany).not.toHaveBeenCalled();
+    });
+
+    it("deletes abandoned sessions past the retention window and reports the count", async () => {
+      (prisma.flowSession.deleteMany as jest.Mock).mockResolvedValue({
+        count: 3,
+      });
+
+      const result = await cleanupAbandonedSessions();
+
+      expect(result).toEqual({ ok: true, deleted: 3 });
+      expect(prisma.flowSession.deleteMany).toHaveBeenCalledTimes(1);
+    });
+
+    it("only ever targets abandoned rows — completedAt: null is structural in the where clause", async () => {
+      (prisma.flowSession.deleteMany as jest.Mock).mockResolvedValue({
+        count: 0,
+      });
+
+      await cleanupAbandonedSessions();
+
+      expect(prisma.flowSession.deleteMany).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: expect.objectContaining({ completedAt: null }),
+        }),
+      );
+    });
+
+    it("computes the cutoff from the default 90-day retention window", async () => {
+      (prisma.flowSession.deleteMany as jest.Mock).mockResolvedValue({
+        count: 0,
+      });
+      const now = new Date("2026-08-11T00:00:00.000Z");
+
+      await cleanupAbandonedSessions({ now });
+
+      const expectedCutoff = new Date("2026-05-13T00:00:00.000Z"); // 90 days earlier
+      expect(prisma.flowSession.deleteMany).toHaveBeenCalledWith({
+        where: {
+          completedAt: null,
+          updatedAt: { lte: expectedCutoff },
+        },
+      });
+    });
+
+    it("honors a caller-supplied staleDays override", async () => {
+      (prisma.flowSession.deleteMany as jest.Mock).mockResolvedValue({
+        count: 0,
+      });
+      const now = new Date("2026-08-11T00:00:00.000Z");
+
+      await cleanupAbandonedSessions({ now, staleDays: 30 });
+
+      const expectedCutoff = new Date("2026-07-12T00:00:00.000Z"); // 30 days earlier
+      expect(prisma.flowSession.deleteMany).toHaveBeenCalledWith({
+        where: {
+          completedAt: null,
+          updatedAt: { lte: expectedCutoff },
+        },
+      });
+    });
+  });
+
+  // ─── #4663 — flow extensions (D1–D6) ──────────────────────────────────────
+
+  // A minimal branching fixture exercising every extension in one flow:
+  // contact (email) -> site (url, optional) -> site_score (aeo_score) ->
+  // note (showIf not pre_launch) -> interests (multi) -> q7 (single) ->
+  // q8 (showIf q7 = yes).
+  function branchingFlow() {
+    return {
+      slug: "branching",
+      defaultLocale: "en",
+      flags: [{ name: "pre_launch", when: { unanswered: "url" } }],
+      steps: [
+        {
+          key: "contact",
+          type: "field" as const,
+          copy: { title: en("Start") },
+          fields: [
+            {
+              name: "email",
+              inputType: "email" as const,
+              required: true,
+              mapsTo: "email" as const,
+              copy: { label: en("Email") },
+            },
+          ],
+        },
+        {
+          key: "site",
+          type: "field" as const,
+          copy: { title: en("Site") },
+          fields: [
+            {
+              name: "url",
+              inputType: "url" as const,
+              required: false,
+              copy: { label: en("URL") },
+            },
+          ],
+        },
+        {
+          key: "site_score",
+          type: "aeo_score" as const,
+          copy: { title: en("Scoring...") },
+          urlField: "url",
+        },
+        {
+          key: "note",
+          type: "field" as const,
+          copy: { title: en("Tell us more") },
+          showIf: { not: { flag: "pre_launch" } },
+          fields: [
+            {
+              name: "note",
+              inputType: "textarea" as const,
+              required: true,
+              minLength: 10,
+              copy: { label: en("Note") },
+            },
+          ],
+        },
+        {
+          key: "interests",
+          type: "segmentation" as const,
+          copy: { title: en("Interests") },
+          questions: [
+            {
+              name: "interests",
+              multi: true as const,
+              exclusiveValues: ["none"],
+              options: [
+                { value: "a", label: en("A") },
+                { value: "b", label: en("B") },
+                { value: "none", label: en("None") },
+              ],
+            },
+          ],
+        },
+        {
+          key: "q7",
+          type: "segmentation" as const,
+          copy: { title: en("Interested?") },
+          questions: [
+            {
+              name: "q7",
+              options: [
+                { value: "yes", label: en("Yes") },
+                { value: "no", label: en("No") },
+              ],
+            },
+          ],
+        },
+        {
+          key: "q8",
+          type: "segmentation" as const,
+          copy: { title: en("How much?") },
+          showIf: { answer: "q7", eq: "yes" },
+          questions: [
+            {
+              name: "q8",
+              options: [
+                { value: "small", label: en("Small") },
+                { value: "large", label: en("Large") },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  beforeEach(() => {
+    mockScoreUrl.mockReset();
+    mockLoadExampleScore.mockReset();
+  });
+
+  describe("AC1 — branch served server-side (D1)", () => {
+    it("serves q8 next when q7=yes, and 409s a submission for the now-hidden q8 after q7=no", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://example.com" },
+          site_score: {},
+          note: { note: "0123456789" },
+          interests: { interests: ["a"] },
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const yesResult = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "q7",
+          values: { q7: "yes" },
+        },
+        sourceMeta,
+      );
+      expect(yesResult).toMatchObject({
+        ok: true,
+        nextStepKey: "q8",
+        completed: false,
+      });
+
+      // Now simulate the session having landed q7=no instead (q8 hidden).
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://example.com" },
+          site_score: {},
+          note: { note: "0123456789" },
+          interests: { interests: ["a"] },
+          q7: { q7: "no" },
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+
+      const conflictResult = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "q8",
+          values: { q8: "small" },
+        },
+        sourceMeta,
+      );
+      expect(conflictResult).toEqual({
+        ok: false,
+        error: { kind: "step_conflict", message: expect.any(String) },
+      });
+    });
+  });
+
+  describe("AC2 — flag-driven skip, persisted with the signup (D2/D3)", () => {
+    it("derives pre_launch when url is unanswered", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: { contact: { email: "a@example.com" } },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      // Land "site" with NO value — derives pre_launch.
+      const siteResult = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site",
+          values: {},
+        },
+        sourceMeta,
+      );
+      expect(siteResult).toMatchObject({ ok: true, nextStepKey: "site_score" });
+      expect(prisma.flowSession.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ flags: { pre_launch: true } }),
+        }),
+      );
+    });
+  });
+
+  describe("AC3 — open text persists verbatim; bounds enforced (D5)", () => {
+    it("rejects a note shorter than minLength and a malformed url", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://example.com" },
+          site_score: {},
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+
+      const tooShort = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "note",
+          values: { note: "short" },
+        },
+        sourceMeta,
+      );
+      expect(tooShort).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+
+      const badUrl = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site",
+          values: { url: "not a url" },
+        },
+        sourceMeta,
+      );
+      expect(badUrl).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+
+      // Security-review finding (#4663, M3): under the installed zod 4.4.3,
+      // z.string().url() restricts neither hostname shape nor protocol, so a
+      // non-http(s) scheme would have passed this check and reached
+      // persistence (SSRF itself stays blocked downstream at assertUrlSafe —
+      // this asserts the separate, narrower value-boundary gap is closed).
+      const jsScheme = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site",
+          values: { url: "javascript:alert(1)" },
+        },
+        sourceMeta,
+      );
+      expect(jsScheme).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+    });
+  });
+
+  describe("AC5 — multi-select (D4)", () => {
+    it("accepts a non-exclusive multi-select and rejects none+other combined", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://example.com" },
+          site_score: {},
+          note: { note: "0123456789" },
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const ok = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "interests",
+          values: { interests: ["a", "b"] },
+        },
+        sourceMeta,
+      );
+      expect(ok).toMatchObject({ ok: true });
+
+      const rejected = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "interests",
+          values: { interests: ["a", "none"] },
+        },
+        sourceMeta,
+      );
+      expect(rejected).toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+    });
+  });
+
+  describe("AC6 — mid-flow AEO score (D6)", () => {
+    it("calls scoreUrl with the landed url, persists + returns aeoScore", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://example.com" },
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      const readyScore = {
+        status: "ready" as const,
+        score: 42,
+        dimensions: [],
+        lowestTwo: [],
+        meta: {
+          auditedAt: "2026-01-01T00:00:00.000Z",
+          pagesAudited: 1,
+          partial: false,
+          skipped: [],
+          schemaVersion: "1",
+          registryVersion: "1",
+        },
+      };
+      mockScoreUrl.mockResolvedValue(readyScore);
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site_score",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(mockScoreUrl).toHaveBeenCalledWith("https://example.com", {
+        budgetMs: 6000,
+      });
+      expect(result).toMatchObject({ ok: true, aeoScore: readyScore });
+      expect(prisma.flowSession.update).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({ aeoScore: readyScore }),
+        }),
+      );
+    });
+
+    it("calls loadExampleScore when the url was never landed", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: { contact: { email: "a@example.com" }, site: {} },
+        flags: { pre_launch: true },
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      const exampleScore = {
+        status: "unavailable" as const,
+        reason: "no_pages_fetched" as const,
+        message: "n/a",
+      };
+      mockLoadExampleScore.mockReturnValue(exampleScore);
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site_score",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(mockScoreUrl).not.toHaveBeenCalled();
+      expect(mockLoadExampleScore).toHaveBeenCalledTimes(1);
+      expect(result).toMatchObject({ ok: true, aeoScore: exampleScore });
+    });
+
+    it("a thrown scoreUrl error lands as unavailable with a GENERIC message — never the raw exception text (code-review finding)", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://example.com" },
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      mockScoreUrl.mockRejectedValue(
+        new Error("connect ECONNREFUSED 10.0.0.5:443 (internal DNS detail)"),
+      );
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site_score",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result.ok && result.aeoScore).toEqual({
+        status: "unavailable",
+        reason: "crawl_failed",
+        message: "Could not score this URL.",
+      });
+      const responseText = JSON.stringify(result);
+      expect(responseText).not.toContain("ECONNREFUSED");
+      expect(responseText).not.toContain("10.0.0.5");
+    });
+
+    // Security-review finding (#4663, M1): scoreUrl RETURNS (never throws) on
+    // an SSRF-guard rejection, so the "never forward a raw message" fix above
+    // — which only covers the catch/throw path — never fired for it. The
+    // returned message ("Host H resolves to a blocked address: A") disclosed
+    // a resolved private IP and was persisted into the lead record verbatim.
+    it("an ssrf_blocked scoreUrl RESULT (not a throw) lands with a GENERIC message — never the resolved-address disclosure", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://internal.example.com" },
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+      mockScoreUrl.mockResolvedValue({
+        status: "unavailable",
+        reason: "ssrf_blocked",
+        message:
+          "Host internal.example.com resolves to a blocked address: 169.254.169.254",
+      });
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site_score",
+          values: {},
+        },
+        sourceMeta,
+      );
+
+      expect(result.ok && result.aeoScore).toEqual({
+        status: "unavailable",
+        reason: "ssrf_blocked",
+        message: "This URL cannot be scored.",
+      });
+      const responseText = JSON.stringify(result);
+      expect(responseText).not.toContain("169.254.169.254");
+      expect(responseText).not.toContain("blocked address");
+    });
+
+    it("re-landing the url step with a changed value resets aeoScore to null and drops the score step's state", async () => {
+      (prisma.flowSession.findUnique as jest.Mock).mockResolvedValue({
+        id: SESSION_ID,
+        siteId: SITE_ID,
+        flowSlug: "branching",
+        configSnapshot: branchingFlow(),
+        state: {
+          contact: { email: "a@example.com" },
+          site: { url: "https://old.example.com" },
+          site_score: {},
+        },
+        flags: {},
+        email: "a@example.com",
+        segment: null,
+        leadId: null,
+        completedAt: null,
+        aeoScore: { status: "ready", score: 1 },
+      });
+      (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+      const result = await submitStep(
+        {
+          siteId: SITE_ID,
+          slug: "branching",
+          sessionId: SESSION_ID,
+          stepKey: "site",
+          values: { url: "https://new.example.com" },
+        },
+        sourceMeta,
+      );
+
+      expect(result).toMatchObject({ ok: true, nextStepKey: "site_score" });
+      const call = (prisma.flowSession.update as jest.Mock).mock.calls[0]![0] as {
+        data: { state: Record<string, unknown>; aeoScore: unknown };
+      };
+      expect(Object.keys(call.data.state)).not.toContain("site_score");
+      expect(call.data.aeoScore).toBe(Prisma.JsonNull);
+    });
+  });
+
+  // ── AC8 — Regression floor: FLOW_PRESETS schema-parse stability ──────────
+  //
+  // Spec 4663-flow-extensions-spec.md AC8, clause 1. `database/flows/presets.ts`
+  // is UNTOUCHED by #4663 (verified: `git diff origin/main..HEAD --
+  // database/flows/presets.ts` is empty) — so the only way this diff could
+  // regress an existing preset is if the EXTENDED flowConfigSchema silently
+  // injects a new default/coerced field into a config that declares none of
+  // the new grammar (showIf/flags/whenHidden/multi/exclusiveValues/url/
+  // minLength/aeo_score). A JSON round-trip of the parsed result deep-equal
+  // to a JSON round-trip of the raw preset proves no field was added, dropped,
+  // or coerced by the schema extension — this IS "parse deep-equals the
+  // pre-change parse" without needing a checked-out pre-change snapshot,
+  // because the input is provably unchanged and Zod parse is pure.
+  describe("AC8 — FLOW_PRESETS schema-parse stability (regression floor)", () => {
+    it.each(FLOW_PRESETS.map((p) => [p.slug, p] as const))(
+      "preset %s parses to a value deep-equal to its own raw JSON shape (no field added/dropped/coerced by the D1-D10 schema extension)",
+      (_slug, preset) => {
+        const parsed = flowConfigSchema.parse(preset);
+        expect(JSON.parse(JSON.stringify(parsed))).toEqual(
+          JSON.parse(JSON.stringify(preset)),
+        );
+      },
+    );
+
+    it("covers all four declared presets — never a stale hardcoded list (DEF-007, mirrors the seedFlowPresets test above)", () => {
+      expect(FLOW_PRESETS.map((p) => p.slug).sort()).toEqual(
+        ["form", "lead-magnet", "roadmap", "waitlist"].sort(),
+      );
+    });
+  });
+});