create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/usage-credits.test.ts

@@ -0,0 +1,588 @@
+/**
+ * @file usage-credits.test.ts
+ * @description Unit tests for the credit consumption waterfall
+ * (FEAT-047 P3.S1, buckets 1–2 — included plan credits + carry-forward
+ * balance). Spec: docs/specs/3730-credit-waterfall-atomicity-spec.md.
+ *
+ * Mocks the module-level `prisma` singleton via the repo's manual-mock
+ * convention (`jest.mock("../../lib/prisma.js")` →
+ * `apps/api/src/lib/__mocks__/prisma.ts`), per lead-routing.test.ts /
+ * usage-metering.test.ts. DB-free (spec §2.2).
+ *
+ * ─── Why the mock MODELS STATE (spec D8) ────────────────────────────────────
+ * The two tests this file replaced asserted `included + balance + uncovered
+ * === cost` and `update).toHaveBeenCalledTimes(1)`. BOTH pass straight through
+ * the TOCTOU double-spend and the negative-availability inversion they were
+ * meant to catch (#3730: the sum invariant holds in every broken case —
+ * `-4000 + 4100 + 0 = 100`; and the write always WAS one statement). A mock
+ * built from static `mockResolvedValue` + sequential `await`s cannot express
+ * interleaving, so no amount of test-writing in that style can surface the
+ * race. They were deleted, not extended (AC-9).
+ *
+ * `installStatefulDb` instead keeps an in-memory Organization row (the
+ * `lead-promotion.test.ts:73` in-memory-"table" convention) and gives the two
+ * write paths DIFFERENT semantics — the asymmetry that makes the atomicity
+ * test load-bearing (mirrors `usage-metering.test.ts:24-29`):
+ *
+ *   - `organization.update`     → an UNCONDITIONAL AUTO-COMMIT. This is the
+ *                                 PRE-FIX write path. It exists so the pre-fix
+ *                                 read-then-write code actually RUNS and
+ *                                 DOUBLE-SPENDS against this mock.
+ *   - `organization.updateMany` → a COMPARE-AND-SWAP. Returns `{ count: 0 }`
+ *                                 when any guarded column in `where` no longer
+ *                                 matches the live row, so the fixed code sees
+ *                                 the conflict and retries.
+ *
+ * ⚠️ DO NOT DELETE THE `update` MOCK PATH — IT IS NOT DEAD CODE. ⚠️
+ * Once the fix landed, production calls only `updateMany`, so `update` is
+ * unreferenced by the passing suite and looks exactly like dead code to
+ * `/simplify`. Deleting it does not fail a single test — it silently converts
+ * AC-2's RED step into a VACUOUS one: without it, the pre-fix implementation
+ * would "fail" this suite merely because the mock lacks the method it calls
+ * (an API-shape mismatch), not because the double-spend invariant broke. That
+ * is precisely the false-assurance class this file exists to delete. The
+ * `update` path is the only thing standing between a future cleanup and a
+ * re-opened double-spend.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+import type { Id } from "@working-theory/ids";
+
+import { prisma } from "../../lib/prisma.js";
+import { consumeCredits, getCreditStatus, MAX_COST_CENTS } from "../usage-credits";
+
+const ORG_A = "org_00000000-0000-7000-8000-0000000000aa" as Id<"organization">;
+const ORG_MISSING = "org_00000000-0000-7000-8000-0000000000bb" as Id<"organization">;
+
+/** A workspace-shaped id forced into the org slot — the M2 bypass under test. */
+// eslint-disable-next-line no-restricted-syntax -- the unbranded cast IS the attack (a route stuffing request input into the org slot); "fixing the type" would delete the test.
+const WORKSPACE_SHAPED = "wksp_00000000-0000-7000-8000-0000000000b1" as unknown as Id<"organization">;
+// eslint-disable-next-line no-restricted-syntax -- see above.
+const MALFORMED_ID = "not-an-org-id" as unknown as Id<"organization">;
+
+type OrgRow = {
+  includedCreditsCents: number;
+  includedCreditsUsedCents: number;
+  onDemandCreditBalanceCents: number;
+};
+
+const CAS_COLUMNS = [
+  "includedCreditsCents",
+  "includedCreditsUsedCents",
+  "onDemandCreditBalanceCents",
+] as const;
+
+const mockOf = (fn: unknown): jest.Mock => fn as jest.Mock;
+
+/** Applies a Prisma `data` payload ({increment}/{decrement}/scalar) to the row. */
+function applyData(row: OrgRow, data: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(data)) {
+    const col = key as keyof OrgRow;
+    if (value !== null && typeof value === "object") {
+      const op = value as { increment?: number; decrement?: number };
+      if (typeof op.increment === "number") row[col] += op.increment;
+      else if (typeof op.decrement === "number") row[col] -= op.decrement;
+    } else if (typeof value === "number") {
+      row[col] = value;
+    }
+  }
+}
+
+type StatefulDbOptions = {
+  /** Hold every read until N reads have arrived — forces a true interleave. */
+  readBarrier?: number;
+  /** A concurrent writer that lands right AFTER the Nth read returns its snapshot. */
+  afterRead?: (row: OrgRow, readIndex: number) => void;
+  failRead?: Error;
+  failWrite?: Error;
+};
+
+function installStatefulDb(initial: OrgRow, options: StatefulDbOptions = {}) {
+  const row: OrgRow = { ...initial };
+  let reads = 0;
+
+  let releaseBarrier: () => void = () => {};
+  const barrier = new Promise<void>((resolve) => {
+    releaseBarrier = resolve;
+  });
+
+  mockOf(prisma.organization.findUnique).mockImplementation(
+    async (args: { where: { id: string } }) => {
+      if (options.failRead) throw options.failRead;
+      if (args.where.id !== ORG_A) return null;
+
+      reads += 1;
+      const readIndex = reads;
+      const snapshot: OrgRow = { ...row };
+
+      if (options.readBarrier) {
+        if (reads >= options.readBarrier) releaseBarrier();
+        await barrier; // resolved barrier ⇒ later reads pass straight through
+      }
+      // The concurrent writer lands AFTER this caller took its snapshot —
+      // the window the CAS `where` exists to detect.
+      options.afterRead?.(row, readIndex);
+
+      return snapshot;
+    },
+  );
+
+  // PRE-FIX write path — UNCONDITIONAL AUTO-COMMIT. See the file docblock:
+  // this is deliberately not dead code. It lets the read-then-write
+  // implementation run and double-spend, so AC-2's RED failure is the
+  // INVARIANT breaking rather than a missing mock method.
+  mockOf(prisma.organization.update).mockImplementation(
+    async (args: { data: Record<string, unknown> }) => {
+      if (options.failWrite) throw options.failWrite;
+      applyData(row, args.data); // nothing can stop this — no predicate
+      return { ...row };
+    },
+  );
+
+  // FIXED write path — COMPARE-AND-SWAP over the whole observed read-set.
+  mockOf(prisma.organization.updateMany).mockImplementation(
+    async (args: {
+      where: Record<string, unknown>;
+      data: Record<string, unknown>;
+    }) => {
+      if (options.failWrite) throw options.failWrite;
+      if (args.where.id !== ORG_A) return { count: 0 };
+
+      for (const col of CAS_COLUMNS) {
+        const guarded = args.where[col];
+        if (guarded !== undefined && guarded !== row[col]) {
+          return { count: 0 }; // a concurrent writer moved it — CAS misses
+        }
+      }
+      applyData(row, args.data);
+      return { count: 1 };
+    },
+  );
+
+  return { row };
+}
+
+describe("consumeCredits", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  // ─── Waterfall precedence (regression floor) ──────────────────────────────
+
+  it("charges included credits first when they fully cover the cost", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 200,
+      onDemandCreditBalanceCents: 500,
+    });
+
+    await expect(consumeCredits(ORG_A, 300)).resolves.toEqual({
+      ok: true,
+      includedPortionCents: 300,
+      creditBalancePortionCents: 0,
+      onDemandPortionCents: 0,
+      uncoveredCents: 0,
+    });
+  });
+
+  it("spills into carry-forward once included credits are exhausted", async () => {
+    const db = installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 900, // 100 remaining
+      onDemandCreditBalanceCents: 500,
+    });
+
+    await expect(consumeCredits(ORG_A, 250)).resolves.toEqual({
+      ok: true,
+      includedPortionCents: 100,
+      creditBalancePortionCents: 150,
+      onDemandPortionCents: 0,
+      uncoveredCents: 0,
+    });
+    expect(db.row.includedCreditsUsedCents).toBe(1000);
+    expect(db.row.onDemandCreditBalanceCents).toBe(350);
+  });
+
+  it("leaves the remainder uncovered once included + carry-forward are exhausted", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 1000,
+      onDemandCreditBalanceCents: 50,
+    });
+
+    await expect(consumeCredits(ORG_A, 200)).resolves.toEqual({
+      ok: true,
+      includedPortionCents: 0,
+      creditBalancePortionCents: 50,
+      onDemandPortionCents: 0,
+      uncoveredCents: 150,
+    });
+  });
+
+  // ─── AC-2 — H1, the TOCTOU double-spend ───────────────────────────────────
+
+  it("AC-2 (H1): two interleaved callers can never together consume more than the included allowance", async () => {
+    // Both callers read `used=0` before either writes — the exact race.
+    const db = installStatefulDb(
+      {
+        includedCreditsCents: 100,
+        includedCreditsUsedCents: 0,
+        onDemandCreditBalanceCents: 0,
+      },
+      { readBarrier: 2 },
+    );
+
+    const [a, b] = await Promise.all([
+      consumeCredits(ORG_A, 100),
+      consumeCredits(ORG_A, 100),
+    ]);
+
+    // STATE, not call-shape: the allowance cannot be over-consumed.
+    expect(db.row.includedCreditsUsedCents).toBeLessThanOrEqual(
+      db.row.includedCreditsCents,
+    );
+    expect(db.row.includedCreditsUsedCents).toBe(100);
+    expect(db.row.onDemandCreditBalanceCents).toBeGreaterThanOrEqual(0);
+
+    // ...and the loser's overage is BILLED, not silently attributed "covered".
+    // Pre-fix BOTH returned uncoveredCents: 0 against a 100¢ allowance.
+    const totalDebited = [a, b].reduce(
+      (sum, r) =>
+        sum + (r.ok ? r.includedPortionCents + r.creditBalancePortionCents : 0),
+      0,
+    );
+    expect(totalDebited).toBe(100);
+
+    const covered = [a, b].filter((r) => r.ok && r.uncoveredCents === 0);
+    expect(covered).toHaveLength(1);
+    const uncovered = [a, b].filter((r) => r.ok && r.uncoveredCents === 100);
+    expect(uncovered).toHaveLength(1);
+  });
+
+  // ─── AC-2b — the CAS hole: allowance drift ────────────────────────────────
+
+  it("AC-2b: a concurrent plan change to includedCreditsCents ALONE defeats the CAS and forces a fresh recompute", async () => {
+    // The two COUNTERS never move — only the ALLOWANCE does. A CAS guarding
+    // just the counters still matches, and commits amounts computed from a
+    // stale allowance. Read-set ≡ CAS-set is what this proves.
+    const db = installStatefulDb(
+      {
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 900, // stale availability: 100
+        onDemandCreditBalanceCents: 500,
+      },
+      {
+        afterRead: (row, readIndex) => {
+          if (readIndex === 1) row.includedCreditsCents = 2000; // plan upgrade
+        },
+      },
+    );
+
+    const result = await consumeCredits(ORG_A, 250);
+
+    // Fresh availability = 2000 − 900 = 1100 ⇒ the whole 250 rides `included`.
+    expect(result).toEqual({
+      ok: true,
+      includedPortionCents: 250,
+      creditBalancePortionCents: 0,
+      onDemandPortionCents: 0,
+      uncoveredCents: 0,
+    });
+    // The carry-forward balance is UNTOUCHED. With the allowance absent from
+    // the `where`, the stale compute (included 100 / balance 150) would have
+    // committed and drained 150¢ of real credits.
+    expect(db.row.onDemandCreditBalanceCents).toBe(500);
+    expect(db.row.includedCreditsUsedCents).toBe(1150);
+  });
+
+  it("returns conflict once the bounded retry budget is exhausted", async () => {
+    // A writer moves the row after EVERY read — the CAS can never land.
+    const db = installStatefulDb(
+      {
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 0,
+        onDemandCreditBalanceCents: 500,
+      },
+      { afterRead: (row) => { row.includedCreditsUsedCents += 1; } },
+    );
+
+    const result = await consumeCredits(ORG_A, 100);
+
+    expect(result).toEqual({
+      ok: false,
+      error: { kind: "conflict", message: expect.any(String) },
+    });
+    expect(mockOf(prisma.organization.updateMany)).toHaveBeenCalledTimes(3);
+    expect(db.row.onDemandCreditBalanceCents).toBe(500); // nothing debited
+  });
+
+  // ─── AC-3 — H2/H4/M1, boundary validation ─────────────────────────────────
+
+  it.each([
+    ["NaN (NaN <= 0 is false — the original bypass)", NaN],
+    ["+Infinity (drains the entire credit position)", Number.POSITIVE_INFINITY],
+    ["-Infinity", Number.NEGATIVE_INFINITY],
+    ["negative (-50 — .int() alone ACCEPTS this; proves .min(0))", -50],
+    ["fractional (10.5 cents)", 10.5],
+    ["above MAX_COST_CENTS", MAX_COST_CENTS + 1],
+  ])(
+    "AC-3: rejects %s with invalid_input, reading and writing nothing",
+    async (_label, costCents) => {
+      installStatefulDb({
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 200,
+        onDemandCreditBalanceCents: 500,
+      });
+
+      await expect(consumeCredits(ORG_A, costCents)).resolves.toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.organization.findUnique).not.toHaveBeenCalled();
+      expect(prisma.organization.update).not.toHaveBeenCalled();
+      expect(prisma.organization.updateMany).not.toHaveBeenCalled();
+    },
+  );
+
+  it("AC-3: zero cost keeps the all-zero fast path with no read and no write", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 200,
+      onDemandCreditBalanceCents: 500,
+    });
+
+    await expect(consumeCredits(ORG_A, 0)).resolves.toEqual({
+      ok: true,
+      includedPortionCents: 0,
+      creditBalancePortionCents: 0,
+      onDemandPortionCents: 0,
+      uncoveredCents: 0,
+    });
+    expect(prisma.organization.findUnique).not.toHaveBeenCalled();
+    expect(prisma.organization.updateMany).not.toHaveBeenCalled();
+  });
+
+  // ─── AC-4 — H3, the zero-clamp ────────────────────────────────────────────
+
+  it("AC-4 (H3): zero-clamps a downgraded org — no allowance refund, no 41x overcharge", async () => {
+    // Plan downgrade: used (5000) legitimately exceeds included (1000).
+    const db = installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 5000,
+      onDemandCreditBalanceCents: 9000,
+    });
+
+    const result = await consumeCredits(ORG_A, 100);
+
+    // Pre-fix: includedPortion = min(-4000, 100) = -4000 ⇒ REFUNDS 4000¢ of
+    // allowance and drains 4100¢ to pay for a 100¢ call.
+    expect(result).toEqual({
+      ok: true,
+      includedPortionCents: 0,
+      creditBalancePortionCents: 100,
+      onDemandPortionCents: 0,
+      uncoveredCents: 0,
+    });
+    expect(db.row.includedCreditsUsedCents).toBe(5000); // NOT refunded
+    expect(db.row.onDemandCreditBalanceCents).toBe(8900); // 9000 − 100, not −4100
+  });
+
+  it("AC-4 (H3 inverse): a negative carry-forward balance never INCREASES on a debit", async () => {
+    const db = installStatefulDb({
+      includedCreditsCents: 0,
+      includedCreditsUsedCents: 0,
+      onDemandCreditBalanceCents: -50, // what H1's race produces
+    });
+
+    const result = await consumeCredits(ORG_A, 100);
+
+    // Pre-fix: min(-50, 100) = -50 ⇒ decrement -50 ⇒ balance rises to 0.
+    // Free credits on every subsequent call, forever.
+    expect(result).toEqual({
+      ok: true,
+      includedPortionCents: 0,
+      creditBalancePortionCents: 0,
+      onDemandPortionCents: 0,
+      uncoveredCents: 100,
+    });
+    expect(db.row.onDemandCreditBalanceCents).toBe(-50);
+  });
+
+  // ─── AC-6 — M2, the branded tenant id ─────────────────────────────────────
+
+  it.each([
+    ["a malformed", MALFORMED_ID],
+    ["a wrong-entity (workspace-shaped)", WORKSPACE_SHAPED],
+  ])(
+    "AC-6 (M2): rejects %s organizationId with invalid_input and never reads",
+    async (_label, organizationId) => {
+      installStatefulDb({
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 0,
+        onDemandCreditBalanceCents: 0,
+      });
+
+      await expect(consumeCredits(organizationId, 100)).resolves.toEqual({
+        ok: false,
+        error: { kind: "invalid_input", message: expect.any(String) },
+      });
+      expect(prisma.organization.findUnique).not.toHaveBeenCalled();
+    },
+  );
+
+  // ─── AC-7 — L1/L2, wrapped write + no oracle ──────────────────────────────
+
+  it("AC-7 (L2): a throwing read returns db_error and never throws", async () => {
+    installStatefulDb(
+      {
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 0,
+        onDemandCreditBalanceCents: 0,
+      },
+      { failRead: new Error(`P2021 relation missing; data: { id: "${ORG_A}" }`) },
+    );
+
+    const result = await consumeCredits(ORG_A, 100);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("db_error");
+      // Prisma embeds the full `data` argument — never echo it.
+      expect(result.error.message).not.toContain("P2021");
+      expect(result.error.message).not.toContain(ORG_A);
+    }
+  });
+
+  it("AC-7 (L2): a throwing write returns db_error and never throws", async () => {
+    installStatefulDb(
+      {
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 0,
+        onDemandCreditBalanceCents: 0,
+      },
+      { failWrite: new Error("P1001 cannot reach database server") },
+    );
+
+    const result = await consumeCredits(ORG_A, 100);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("db_error");
+      expect(result.error.message).not.toContain("P1001");
+    }
+  });
+
+  it("AC-7 (L1): org_not_found does not echo the organization id", async () => {
+    mockOf(prisma.organization.findUnique).mockResolvedValue(null);
+
+    const result = await consumeCredits(ORG_MISSING, 100);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("org_not_found");
+      // The house route pattern returns error.message verbatim to the client —
+      // echoing the id makes this an org-existence oracle.
+      expect(result.error.message).not.toContain(ORG_MISSING);
+    }
+    expect(prisma.organization.updateMany).not.toHaveBeenCalled();
+  });
+});
+
+describe("getCreditStatus", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("returns includedRemaining + creditBalance + effectiveRemaining", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 400,
+      onDemandCreditBalanceCents: 250,
+    });
+
+    await expect(getCreditStatus(ORG_A)).resolves.toEqual({
+      ok: true,
+      includedRemaining: 600,
+      creditBalance: 250,
+      effectiveRemaining: 850,
+    });
+  });
+
+  it("zero-clamps a downgraded org's negative availability (consistent with the debit)", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 5000, // downgrade
+      onDemandCreditBalanceCents: 250,
+    });
+
+    // Pre-fix: includedRemaining = -4000, effectiveRemaining = -3750.
+    await expect(getCreditStatus(ORG_A)).resolves.toEqual({
+      ok: true,
+      includedRemaining: 0,
+      creditBalance: 250,
+      effectiveRemaining: 250,
+    });
+  });
+
+  it("zero-clamps a negative carry-forward balance", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 1000,
+      onDemandCreditBalanceCents: -50,
+    });
+
+    await expect(getCreditStatus(ORG_A)).resolves.toEqual({
+      ok: true,
+      includedRemaining: 0,
+      creditBalance: 0,
+      effectiveRemaining: 0,
+    });
+  });
+
+  it("AC-6 (M2): rejects a workspace-shaped organizationId with invalid_input", async () => {
+    installStatefulDb({
+      includedCreditsCents: 1000,
+      includedCreditsUsedCents: 0,
+      onDemandCreditBalanceCents: 0,
+    });
+
+    await expect(getCreditStatus(WORKSPACE_SHAPED)).resolves.toEqual({
+      ok: false,
+      error: { kind: "invalid_input", message: expect.any(String) },
+    });
+    expect(prisma.organization.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("AC-7: a throwing read returns db_error and never throws", async () => {
+    installStatefulDb(
+      {
+        includedCreditsCents: 1000,
+        includedCreditsUsedCents: 0,
+        onDemandCreditBalanceCents: 0,
+      },
+      { failRead: new Error("P1001 cannot reach database server") },
+    );
+
+    const result = await getCreditStatus(ORG_A);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("db_error");
+      expect(result.error.message).not.toContain("P1001");
+    }
+  });
+
+  it("AC-7 (L1): org_not_found does not echo the organization id", async () => {
+    mockOf(prisma.organization.findUnique).mockResolvedValue(null);
+
+    const result = await getCreditStatus(ORG_MISSING);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("org_not_found");
+      expect(result.error.message).not.toContain(ORG_MISSING);
+    }
+  });
+});