create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,340 @@
+/**
+ * @file usage-credits.ts
+ * @description Credit consumption waterfall (FEAT-047 P3.S1 — buckets 1-2).
+ * Spec: docs/specs/3730-credit-waterfall-atomicity-spec.md (hardening pass over
+ * the original docs/specs/3706-s1-credit-waterfall-service-spec.md).
+ *
+ * Charges a billed cost across the two non-overage buckets, in order:
+ *   1. included plan credits
+ *   2. carry-forward credit balance
+ * Bucket 3 (on-demand overage, pre-charge, spend limit) is P4 — this service
+ * leaves `onDemandPortionCents = 0` and returns any remainder as
+ * `uncoveredCents` rather than throwing. The caller (P2.S1's
+ * `recordUsageEvent`) stamps the returned split back onto the UsageEvent row —
+ * this service owns balances only.
+ *
+ * ─── The four invariants this file must hold (#3730) ────────────────────────
+ * The original implementation shipped unreviewed and violated all four. Each
+ * carries a test that fails without its fix (usage-credits.test.ts).
+ *
+ *  1. THE DEBIT IS ATOMIC (H1). The balance write is a conditional
+ *     `updateMany` COMPARE-AND-SWAP whose `where` carries every column value
+ *     the read observed; a concurrent writer that moved any of them makes the
+ *     predicate miss, the update match 0 rows, and this service re-read,
+ *     recompute, and retry (bounded — then `conflict`).
+ *
+ *     ⚠️ NOT a `$transaction`. The sibling `usage-metering.ts` uses one, which
+ *     makes it the locally-obvious reach — but wrapping the same
+ *     read-then-write in a Read-Committed transaction does NOT fix the TOCTOU.
+ *     Atomicity is not isolation. A single conditional UPDATE *is* the atomic
+ *     compare-and-swap and needs no transaction: Postgres re-evaluates the
+ *     `where` against the newly-committed row after the row lock releases
+ *     (EvalPlanQual) — exactly the semantics required (spec D1).
+ *
+ *     The `where` guards the WHOLE read-set — the ALLOWANCE
+ *     (`includedCreditsCents`) as well as the two counters. The debit math
+ *     reads the allowance, so a concurrent plan change that moves it while the
+ *     counters sit still would otherwise slip a STALE allowance past a
+ *     counters-only predicate. Read-set ≡ CAS-set (spec AC-2b).
+ *
+ *  2. AVAILABILITY IS ZERO-CLAMPED (H3). A plan DOWNGRADE legitimately leaves
+ *     `used > included`, so `included − used` goes negative — and an unclamped
+ *     `Math.min(negative, cost)` INVERTS the debit: it refunds consumed
+ *     allowance and drains real credits (a verified 41× overcharge). Both
+ *     derived availabilities are `Math.max(0, …)`.
+ *
+ *  3. THE BOUNDARY IS VALIDATED (H2/H4/M1/M2). `costCents` and
+ *     `organizationId` are zod-parsed BEFORE any read or math. `NaN <= 0` is
+ *     `false`, so the old guard let `NaN` through; `Infinity <= 0` is `false`
+ *     too, and `Infinity` yields VALID finite integers (`min(800, Infinity) =
+ *     800`) that silently zero a customer's entire credit position.
+ *     `z.number().int()` rejects `NaN`, `±Infinity`, and `10.5` — and `.min(0)`
+ *     is a SEPARATE, REQUIRED clause, because `.int()` alone ACCEPTS `-50`.
+ *
+ *  4. NOTHING THROWS, NOTHING LEAKS (L1/L2). Every failure is a discriminated
+ *     result. Raw DB error text is logged server-side and NEVER returned
+ *     (Prisma embeds the full `data` argument — org ids, amounts), and
+ *     `org_not_found` carries no org id: the house route pattern
+ *     (`routes/leads/index.ts`) returns `error.message` verbatim to the client,
+ *     which would make an echoed id an org-existence oracle.
+ *
+ * PII boundary: this service touches no PII — only organization ids and cent
+ * amounts. No Stripe call (P4).
+ */
+
+import { zOrganizationId, type Id } from "@working-theory/ids";
+import { z } from "zod";
+
+import { prisma } from "../lib/prisma.js";
+
+// ─── Boundary validation (H2/H4/M1/M2) ────────────────────────────────────────
+
+/**
+ * An ABSURDITY ceiling, not a business limit — so a corrupt caller cannot drive
+ * the debit to an absurd magnitude. $1,000,000 in cents. Mirrors
+ * `MAX_TOKENS_PER_EVENT` (usage-metering.ts).
+ */
+export const MAX_COST_CENTS = 100_000_000;
+
+/**
+ * A cent cost: finite, integral, non-negative, bounded.
+ * `.int()` rejects `NaN` and `±Infinity` (neither is an integer) and `10.5`.
+ * `.min(0)` is REQUIRED SEPARATELY — `.int()` alone accepts `-50`.
+ */
+const zCostCents = z
+  .number()
+  .int("costCents must be an integer")
+  .min(0, "costCents cannot be negative")
+  .max(MAX_COST_CENTS, "costCents exceeds the per-call maximum");
+
+const zConsumeInput = z.object({
+  organizationId: zOrganizationId,
+  costCents: zCostCents,
+});
+
+/** The bounded CAS retry budget (spec OQ-1). */
+const MAX_ATTEMPTS = 3;
+
+const CREDIT_SELECT = {
+  includedCreditsCents: true,
+  includedCreditsUsedCents: true,
+  onDemandCreditBalanceCents: true,
+} as const;
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type OrganizationCreditRow = {
+  includedCreditsCents: number;
+  includedCreditsUsedCents: number;
+  onDemandCreditBalanceCents: number;
+};
+
+type CreditSplit = {
+  includedPortionCents: number;
+  creditBalancePortionCents: number;
+  onDemandPortionCents: 0;
+  uncoveredCents: number;
+};
+
+/** Every failure this service can produce — no path throws. */
+type CreditErrorKind =
+  | "invalid_input"
+  | "org_not_found"
+  | "conflict"
+  | "db_error";
+
+type CreditError = { kind: CreditErrorKind; message: string };
+
+export type ConsumeResult =
+  | ({ ok: true } & CreditSplit)
+  | { ok: false; error: CreditError };
+
+export type CreditStatusResult =
+  | {
+      ok: true;
+      includedRemaining: number;
+      creditBalance: number;
+      effectiveRemaining: number;
+    }
+  | { ok: false; error: CreditError };
+
+const ALL_ZERO: { ok: true } & CreditSplit = {
+  ok: true,
+  includedPortionCents: 0,
+  creditBalancePortionCents: 0,
+  onDemandPortionCents: 0,
+  uncoveredCents: 0,
+};
+
+// ─── Internals ────────────────────────────────────────────────────────────────
+
+function invalidInput(error: z.ZodError): { ok: false; error: CreditError } {
+  // Field names + our own messages only — never the received value.
+  const message = error.issues
+    .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+    .join("; ");
+  return { ok: false, error: { kind: "invalid_input", message } };
+}
+
+/** L1 — no org id in the message; the route returns it verbatim to the client. */
+const ORG_NOT_FOUND: { ok: false; error: CreditError } = {
+  ok: false,
+  error: { kind: "org_not_found", message: "organization not found" },
+};
+
+/** L2 — log the detail server-side; NEVER return it (Prisma embeds `data`). */
+function dbError(
+  operation: string,
+  organizationId: Id<"organization">,
+  error: unknown,
+): { ok: false; error: CreditError } {
+  const detail = error instanceof Error ? error.message : String(error);
+  console.error("usage-credits: %s failed", operation, {
+    organizationId,
+    detail,
+  });
+  return {
+    ok: false,
+    error: { kind: "db_error", message: "credit operation failed" },
+  };
+}
+
+/**
+ * The waterfall, with BOTH availabilities zero-clamped (H3). The clamp is the
+ * correct expression of the invariant: a downgraded org has zero included
+ * availability, so the call spills straight to carry-forward — the right
+ * billing behaviour — instead of inverting the debit.
+ */
+function computeSplit(
+  org: OrganizationCreditRow,
+  costCents: number,
+): CreditSplit {
+  const includedAvailable = Math.max(
+    0,
+    org.includedCreditsCents - org.includedCreditsUsedCents,
+  );
+  const includedPortionCents = Math.min(includedAvailable, costCents);
+  const remainingAfterIncluded = costCents - includedPortionCents;
+
+  const balanceAvailable = Math.max(0, org.onDemandCreditBalanceCents);
+  const creditBalancePortionCents = Math.min(
+    balanceAvailable,
+    remainingAfterIncluded,
+  );
+
+  return {
+    includedPortionCents,
+    creditBalancePortionCents,
+    onDemandPortionCents: 0,
+    uncoveredCents: remainingAfterIncluded - creditBalancePortionCents,
+  };
+}
+
+// ─── Main exports ─────────────────────────────────────────────────────────────
+
+/**
+ * Charges `costCents` against `organizationId`'s included plan credits, then
+ * its carry-forward credit balance (buckets 1-2). Returns the attribution
+ * split; the caller stamps it onto the UsageEvent row.
+ */
+export async function consumeCredits(
+  organizationId: Id<"organization">,
+  costCents: number,
+): Promise<ConsumeResult> {
+  const parsed = zConsumeInput.safeParse({ organizationId, costCents });
+  if (!parsed.success) {
+    return invalidInput(parsed.error);
+  }
+
+  // A genuinely free call — no read, no write. (A NEGATIVE cost is a caller
+  // bug and is rejected above as `invalid_input`, not treated as free.)
+  if (parsed.data.costCents === 0) {
+    return ALL_ZERO;
+  }
+
+  const { organizationId: orgId, costCents: cost } = parsed.data;
+
+  try {
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      const org = await prisma.organization.findUnique({
+        where: { id: orgId },
+        select: CREDIT_SELECT,
+      });
+
+      if (!org) {
+        return ORG_NOT_FOUND;
+      }
+
+      const split = computeSplit(org, cost);
+
+      // Nothing to debit (exhausted, or a clamped-to-zero availability): the
+      // remainder is reported as uncovered and no write is needed, so there is
+      // no CAS to lose and no spurious `conflict`.
+      if (
+        split.includedPortionCents === 0 &&
+        split.creditBalancePortionCents === 0
+      ) {
+        return { ok: true, ...split };
+      }
+
+      // H1 — COMPARE-AND-SWAP. The `where` restates every value the read
+      // observed (allowance INCLUDED — spec AC-2b), so any concurrent writer
+      // makes this match 0 rows rather than committing stale amounts.
+      const { count } = await prisma.organization.updateMany({
+        where: {
+          id: orgId,
+          includedCreditsCents: org.includedCreditsCents,
+          includedCreditsUsedCents: org.includedCreditsUsedCents,
+          onDemandCreditBalanceCents: org.onDemandCreditBalanceCents,
+        },
+        data: {
+          includedCreditsUsedCents: { increment: split.includedPortionCents },
+          onDemandCreditBalanceCents: {
+            decrement: split.creditBalancePortionCents,
+          },
+        },
+      });
+
+      if (count > 0) {
+        return { ok: true, ...split };
+      }
+      // count === 0 — someone moved the row under us. Re-read and recompute.
+    }
+
+    // An honest `conflict` the caller can retry beats an unbounded spin on
+    // money code (spec OQ-1).
+    return {
+      ok: false,
+      error: {
+        kind: "conflict",
+        message: "credit balance changed concurrently; retry the request",
+      },
+    };
+  } catch (error) {
+    return dbError("debit", orgId, error);
+  }
+}
+
+/**
+ * Returns the current credit standing for `organizationId` across the two P3
+ * buckets. On-demand overage remaining is P4 — not surfaced here.
+ *
+ * Both availabilities are zero-clamped, so a downgraded org reads `0`
+ * remaining rather than a negative number — consistent with what the debit
+ * will actually charge.
+ */
+export async function getCreditStatus(
+  organizationId: Id<"organization">,
+): Promise<CreditStatusResult> {
+  const parsed = zOrganizationId.safeParse(organizationId);
+  if (!parsed.success) {
+    return invalidInput(parsed.error);
+  }
+  const orgId = parsed.data;
+
+  try {
+    const org = await prisma.organization.findUnique({
+      where: { id: orgId },
+      select: CREDIT_SELECT,
+    });
+
+    if (!org) {
+      return ORG_NOT_FOUND;
+    }
+
+    const includedRemaining = Math.max(
+      0,
+      org.includedCreditsCents - org.includedCreditsUsedCents,
+    );
+    const creditBalance = Math.max(0, org.onDemandCreditBalanceCents);
+
+    return {
+      ok: true,
+      includedRemaining,
+      creditBalance,
+      effectiveRemaining: includedRemaining + creditBalance,
+    };
+  } catch (error) {
+    return dbError("status read", orgId, error);
+  }
+}