create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,516 @@
+/**
+ * @file usage-aggregation.ts
+ * @description Usage aggregation + billing-report service — the "aggregate"
+ * half of FEAT-047's meter -> aggregate -> report MVP (ADR 0009 D3
+ * service-layer assembler; spec
+ * docs/specs/3705-s2-usage-aggregation-service-spec.md).
+ *
+ * The AILK analog of working-theory's `UsageBillingService.aggregateUsage`:
+ * given an organization + a period start, SUM the successful `UsageEvent`
+ * rows P2.S1's `recordUsageEvent` wrote for that org/period, then write (or
+ * update) the one `UsageBillingReport` row for `(organizationId, periodStart,
+ * periodEnd)`. Re-invoking for the same org/period UPDATES the same report —
+ * safe to run on a cadence without duplicating (spec D1).
+ *
+ * Reconciliation (AC-UB-03a) holds by construction: `totalBilledAmount` and
+ * `totalProviderCost` are independent SUMs of the SAME per-event columns
+ * `recordUsageEvent` wrote (`billedCostUsd = providerCostUsd * (1 +
+ * markupPercent/100)` at write time), so `totalMarkupAmount :=
+ * totalBilledAmount - totalProviderCost` makes `totalBilledAmount ==
+ * totalProviderCost + totalMarkupAmount` exact — which is the same identity
+ * as `totalBilledAmount == totalProviderCost * (1 + effectiveMarkup)` for
+ * whatever effective markup the period's event mix implies.
+ *
+ * Org-isolation (AC-UB-10) holds because the `UsageEvent` read is filtered by
+ * `organizationId` at the query boundary — never a wider read narrowed
+ * client-side.
+ *
+ * This is a MONEY-READING + MONEY-WRITING path. Two invariants hold it,
+ * mirroring the sibling `usage-metering.ts` (H4) and closing the class of
+ * defect flagged in `usage-credits.ts` (an unvalidated boundary + a
+ * read-then-write that isn't atomic, AILK#3730):
+ *
+ *   1. VALIDATED AT THE BOUNDARY. `organizationId` and `periodStart` are
+ *      parsed by `aggregateInputSchema` before either drives a query — a
+ *      malformed id or an invalid Date is rejected as `invalid_input` rather
+ *      than reaching Prisma or the cost math.
+ *   2. NON-FINITE VALUES NEVER REACH THE PERSISTED REPORT. Every summed
+ *      `UsageEvent` money/token column is coerced through a finite-number
+ *      guard; if the running total ever goes non-finite (a corrupt row —
+ *      NaN/Infinity survived somehow, or a future writer regresses H4), the
+ *      aggregation FAILS CLOSED (`aggregation_failed`) rather than persisting
+ *      a poisoned `UsageBillingReport` that every later re-run — and any P4
+ *      Stripe report derived from it — would inherit.
+ *
+ * Idempotency (AC-2, D1) is a single atomic `upsert` keyed on the DB's own
+ * `(organizationId, periodStart, periodEnd)` unique constraint — a full
+ * recompute-and-overwrite, not a read-modify-write increment, so there is no
+ * TOCTOU window: two concurrent runs for the same org/period each compute the
+ * SAME totals from the SAME source rows and upsert idempotently. The update
+ * branch deliberately does NOT touch `status` or the attribution cents — P2
+ * never advances status past its `PENDING` default, and a re-run must not
+ * clobber attribution P3/P4 has since applied to the same report row.
+ *
+ * PII boundary: only ids, counts, and computed cost totals ever appear in
+ * logs or in a returned error. Never token content.
+ *
+ * Schema note: `UsageEvent`/`UsageBillingReport` (database/content, #3709,
+ * merged) are read/written here entirely within the content namespace — no
+ * cross-namespace join needed (ADR-0009 invariant #2; spec §5.3 escalation
+ * boundary). `db` below is `prisma` structurally cast to the delegate shape
+ * this file needs, matching `usage-metering.ts`'s convention.
+ */
+
+import { zOrganizationId } from "@working-theory/ids";
+import { z } from "zod";
+
+import { prisma } from "../lib/prisma.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface AggregateTotals {
+  totalProviderCost: number;
+  totalMarkupAmount: number;
+  totalBilledAmount: number;
+  totalTokens: number;
+  eventCount: number;
+  /** Attribution split — always 0 in P2 (populated by the P3/P4 waterfall). */
+  includedCents: number;
+  creditBalanceCents: number;
+  onDemandCents: number;
+}
+
+export type AggregateErrorKind =
+  | "invalid_input"
+  /** A source row was unusable (non-finite, negative, or billed < provider). */
+  | "aggregation_failed"
+  /**
+   * A computed total exceeded the representable range (#3738 H2). DISTINCT from
+   * `write_failed` on purpose: an overflow means this org's report can never be
+   * written, so it is a revenue-stopping condition that must be ALERTED on, not
+   * buried in the generic write-failure bucket.
+   */
+  | "aggregate_overflow"
+  /** The UsageEvent read itself failed (#3738 H1). */
+  | "read_failed"
+  | "write_failed";
+
+export type AggregateResult =
+  | { ok: true; reportId: string; totals: AggregateTotals }
+  | {
+      ok: false;
+      error: { kind: AggregateErrorKind; message: string };
+    };
+
+// ─── Boundary validation ──────────────────────────────────────────────────────
+
+const aggregateInputSchema = z.object({
+  organizationId: zOrganizationId,
+  periodStart: z.date().refine((d) => Number.isFinite(d.getTime()), {
+    message: "periodStart must be a valid Date",
+  }),
+});
+
+// ─── Structural delegate shape for the FEAT-047 content-namespace models ──────
+// (See the file-header schema note — mirrors usage-metering.ts's cast.)
+
+/**
+ * The `_sum` shape Prisma's `aggregate()` returns for the three summed
+ * money/token columns. Each field is `null` when zero rows match the
+ * `where` clause (Prisma's convention — a SUM over zero rows is not `0`),
+ * so callers must coalesce before coercing.
+ */
+interface UsageEventAggregateSum {
+  providerCostUsd: unknown;
+  billedCostUsd: unknown;
+  totalTokens: unknown;
+}
+
+interface UsageBillingReportUpsertData {
+  organizationId: string;
+  periodStart: Date;
+  periodEnd: Date;
+  totalProviderCost: number;
+  totalMarkupAmount: number;
+  totalBilledAmount: number;
+  /**
+   * `bigint` — `total_tokens` is an int8 column (#3738 H2). The public
+   * `AggregateTotals.totalTokens` stays a `number` (JSON-safe for the #3717
+   * route); the conversion happens here, at the write boundary, where the value
+   * has already been asserted to be a safe integer.
+   */
+  totalTokens: bigint;
+  eventCount: number;
+  includedCents?: number;
+  creditBalanceCents?: number;
+  onDemandCents?: number;
+}
+
+export interface UsageAggregationPrismaDelegates {
+  usageEvent: {
+    /**
+     * DB-side SUM (#3739 M2 — the highest-leverage finding of the #3738
+     * security review, carried forward after H1/H2/M1/L1 landed separately).
+     * `findMany` + a JS accumulation loop materialised every matching
+     * `UsageEvent` row in the API process to sum three columns — a
+     * high-volume org (or anyone who can drive event creation) could turn a
+     * single aggregation call into a multi-hundred-MB allocation. `aggregate`
+     * pushes the SUM into Postgres: exact `numeric` addition (also closing
+     * the review's L3 float-accumulation finding), bounded response size
+     * regardless of event count, and one column-scan instead of a
+     * row-materialising fetch.
+     */
+    aggregate(args: {
+      where: {
+        organizationId: string;
+        completionStatus: string;
+        createdAt: { gte: Date; lt: Date };
+      };
+      _sum: {
+        providerCostUsd: true;
+        billedCostUsd: true;
+        totalTokens: true;
+      };
+      _count: true;
+    }): Promise<{ _sum: UsageEventAggregateSum; _count: number }>;
+  };
+  usageBillingReport: {
+    upsert(args: {
+      where: {
+        organizationId_periodStart_periodEnd: {
+          organizationId: string;
+          periodStart: Date;
+          periodEnd: Date;
+        };
+      };
+      create: UsageBillingReportUpsertData;
+      update: Omit<
+        UsageBillingReportUpsertData,
+        "organizationId" | "periodStart" | "periodEnd"
+      >;
+      select: { id: true };
+    }): Promise<{ id: string }>;
+  };
+}
+
+const db = prisma as unknown as UsageAggregationPrismaDelegates;
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Only successful calls drive billing (spec D2). */
+const BILLABLE_COMPLETION_STATUS = "success";
+
+// ─── Bounds (#3738 H2b) ──────────────────────────────────────────────────────
+//
+// The persisted columns are Decimal(20,6) (≈ $1e14) and int8 — deliberately far
+// WIDER than these caps. The caps are therefore always the binding gate, which
+// is the point: an out-of-range total fails LOUDLY here with an alertable
+// `aggregate_overflow` rather than reaching Postgres and dying as an opaque
+// `numeric field overflow` inside the generic write-failure path (the failure
+// mode that silently stalled billing forever for the largest tenants).
+//
+// $1B/org/month is ~100,000x the ceiling that used to break billing, and it
+// keeps the 6-decimal rounding below exact: 1e9 * 1e6 = 1e15 < 2^53.
+
+/** Max provider/billed/markup total for one org-month, in USD. */
+const MAX_TOTAL_USD = 1_000_000_000;
+/** Tokens are carried as a JS number; beyond 2^53 the count is no longer exact. */
+const MAX_TOTAL_TOKENS = Number.MAX_SAFE_INTEGER;
+/** `eventCount` remains an int4 column. */
+const MAX_EVENT_COUNT = 2_147_483_647;
+
+/** Rounds to the columns' 6-decimal scale, so the reconciliation identity
+ * (provider + markup == billed) holds EXACTLY in the persisted decimals. */
+function roundToScale6(value: number): number {
+  return Math.round(value * 1e6) / 1e6;
+}
+
+// ─── Period-window helpers ────────────────────────────────────────────────────
+
+function startOfMonthUtc(date: Date): Date {
+  return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1));
+}
+
+function startOfNextMonthUtc(periodStart: Date): Date {
+  return new Date(
+    Date.UTC(periodStart.getUTCFullYear(), periodStart.getUTCMonth() + 1, 1),
+  );
+}
+
+// ─── Safe numeric coercion ─────────────────────────────────────────────────────
+
+/**
+ * Coerces a DB-sourced numeric column (a plain number in tests; a Prisma
+ * `Decimal` instance — which exposes `.toNumber()` — in production) to a
+ * number. Never throws; an unusable value yields `NaN`, which the guard below
+ * catches, failing the aggregation closed.
+ *
+ * STRICT by design (#3738 L1). The previous implementation fell through to
+ * `Number(value)`, which maps `null`/`""`/`[]` to a silent **0** — dropping
+ * that row's cost from the total (an UNDERBILL) rather than the `NaN` its
+ * docblock claimed. That was inert only because every column read here is
+ * NOT NULL today; it would have become a live money bug the moment a column
+ * gained optionality or the `select` widened. Anything that is not a real
+ * number or a Decimal-shaped object is now `NaN` — i.e. it fails closed.
+ */
+function toNumber(value: unknown): number {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    "toNumber" in value &&
+    typeof (value as { toNumber: unknown }).toNumber === "function"
+  ) {
+    return (value as { toNumber(): number }).toNumber();
+  }
+  return Number.NaN;
+}
+
+// ─── Idempotent report write (D1) ──────────────────────────────────────────────
+
+/**
+ * One `UsageBillingReport` per `(organizationId, periodStart, periodEnd)` —
+ * `upsert` on the DB's own compound unique key. A re-run for the same
+ * org/period UPDATES the same row (never duplicates); `status` and the
+ * attribution cents are intentionally absent from `update` so a P2 re-run
+ * cannot clobber state a later phase (P4) has since applied.
+ */
+async function getOrCreateReport(
+  organizationId: string,
+  periodStart: Date,
+  periodEnd: Date,
+  totals: AggregateTotals,
+): Promise<{ id: string }> {
+  return db.usageBillingReport.upsert({
+    where: {
+      organizationId_periodStart_periodEnd: {
+        organizationId,
+        periodStart,
+        periodEnd,
+      },
+    },
+    create: {
+      organizationId,
+      periodStart,
+      periodEnd,
+      totalProviderCost: totals.totalProviderCost,
+      totalMarkupAmount: totals.totalMarkupAmount,
+      totalBilledAmount: totals.totalBilledAmount,
+      totalTokens: BigInt(totals.totalTokens),
+      eventCount: totals.eventCount,
+      includedCents: 0,
+      creditBalanceCents: 0,
+      onDemandCents: 0,
+    },
+    update: {
+      totalProviderCost: totals.totalProviderCost,
+      totalMarkupAmount: totals.totalMarkupAmount,
+      totalBilledAmount: totals.totalBilledAmount,
+      totalTokens: BigInt(totals.totalTokens),
+      eventCount: totals.eventCount,
+    },
+    select: { id: true },
+  });
+}
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * SUMs the successful `UsageEvent`s for `organizationId` over the calendar
+ * month containing `periodStart` into `totalProviderCost`/`totalMarkupAmount`/
+ * `totalBilledAmount`/`totalTokens`/`eventCount` (the attribution cents stay
+ * 0 — P2 scope, spec D3), then idempotently writes/updates the
+ * `UsageBillingReport` for that org/period.
+ *
+ * Never throws — EVERY path returns the discriminated union, including a failed
+ * read (#3738 H1). A malformed `organizationId`/`periodStart` ->
+ * `invalid_input`; a failed `UsageEvent` read -> `read_failed`; an unusable
+ * total (non-finite, negative, or billed < provider) -> `aggregation_failed`;
+ * a total beyond the representable range -> `aggregate_overflow` (distinct and
+ * ALERTABLE — it means this org's report can never be written); a report-write
+ * failure -> `write_failed`. Every failure mode fails CLOSED: no poisoned,
+ * truncated, or negative total is ever persisted.
+ */
+export async function aggregateUsagePeriod(
+  organizationId: string,
+  periodStart: Date,
+): Promise<AggregateResult> {
+  const parsed = aggregateInputSchema.safeParse({ organizationId, periodStart });
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const field = issue?.path.join(".") ?? "input";
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: `${field}: ${issue?.message ?? "invalid input"}`,
+      },
+    };
+  }
+
+  const orgId = parsed.data.organizationId;
+  const windowStart = startOfMonthUtc(parsed.data.periodStart);
+  const windowEnd = startOfNextMonthUtc(windowStart);
+
+  // The READ is inside the error guard (#3738 H1). Previously it sat outside,
+  // so a connection drop / pool exhaustion / statement timeout / missing-table
+  // error REJECTED the promise instead of returning the discriminated union
+  // this function's contract promises — and a Prisma read error embeds the
+  // `where` clause, which carries the tenant's organizationId. #3717's route
+  // trusts the union, so an escaping rejection would surface as a 500 that can
+  // leak that id.
+  //
+  // #3739 M2 — DB-side SUM via aggregate(), not findMany() + a JS
+  // accumulation loop. See the UsageAggregationPrismaDelegates doc comment
+  // for the full rationale (resource exhaustion + exact decimal addition).
+  let agg: { _sum: UsageEventAggregateSum; _count: number };
+  try {
+    agg = await db.usageEvent.aggregate({
+      where: {
+        organizationId: orgId,
+        completionStatus: BILLABLE_COMPLETION_STATUS,
+        createdAt: { gte: windowStart, lt: windowEnd },
+      },
+      _sum: { providerCostUsd: true, billedCostUsd: true, totalTokens: true },
+      _count: true,
+    });
+  } catch (error) {
+    // Log the detail server-side; NEVER return it (the raw error embeds the
+    // `where` clause, i.e. the org id).
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error("usage-aggregation: usage event read failed", {
+      organizationId: orgId,
+      periodStart: windowStart.toISOString(),
+      detail,
+    });
+    return {
+      ok: false,
+      error: { kind: "read_failed", message: "usage event read failed" },
+    };
+  }
+
+  // Prisma's aggregate `_sum` is `null` per field when zero rows match (a SUM
+  // over zero rows is not `0`) — coalesce before coercing. `toNumber` still
+  // guards against an unusable/non-numeric aggregate result (a corrupt mock,
+  // a future Prisma client change), mirroring #3738 L1's fail-closed intent;
+  // it is no longer defending against a per-row null, which the DB's NOT NULL
+  // column constraint already makes impossible upstream of this call.
+  const totalProviderCost = toNumber(agg._sum.providerCostUsd ?? 0);
+  const totalBilledAmount = toNumber(agg._sum.billedCostUsd ?? 0);
+  const totalTokens = toNumber(agg._sum.totalTokens ?? 0);
+  const eventCount = agg._count;
+
+  // Fail-closed money guard. FINITE ALONE IS NOT ENOUGH (#3738 M1): a negative
+  // cost is perfectly finite, sums cleanly, and would persist as a CREDIT — the
+  // precise class of defect that produced the sibling service's overcharge bug.
+  // So the guard also requires non-negative totals and billed >= provider (a
+  // negative markup is an inverted, unbillable report). Unchanged by the M2
+  // findMany -> aggregate migration: these checks apply to the FINAL summed
+  // totals either way, and Postgres's exact `numeric` SUM makes them more
+  // trustworthy, not less (closes the review's L3 float-accumulation finding
+  // as a side effect).
+  const invariantsHold =
+    Number.isFinite(totalProviderCost) &&
+    Number.isFinite(totalBilledAmount) &&
+    Number.isFinite(totalTokens) &&
+    totalProviderCost >= 0 &&
+    totalBilledAmount >= 0 &&
+    totalTokens >= 0 &&
+    totalBilledAmount >= totalProviderCost;
+
+  if (!invariantsHold) {
+    // A corrupt row must never reach the persisted report — writing a poisoned
+    // total here corrupts every future re-run AND the P4 Stripe report derived
+    // from it.
+    console.error("usage-aggregation: usage total failed the money invariants", {
+      organizationId: orgId,
+      periodStart: windowStart.toISOString(),
+      eventCount,
+    });
+    return {
+      ok: false,
+      error: {
+        kind: "aggregation_failed",
+        message:
+          "unusable value encountered while aggregating usage events (non-finite, negative, or billed < provider)",
+      },
+    };
+  }
+
+  // Round to the columns' 6-decimal scale BEFORE deriving markup, so the
+  // reconciliation identity (provider + markup == billed) holds exactly in the
+  // persisted decimals rather than only to within a float epsilon.
+  const providerTotal = roundToScale6(totalProviderCost);
+  const billedTotal = roundToScale6(totalBilledAmount);
+  const markupTotal = roundToScale6(billedTotal - providerTotal);
+
+  // ── Pre-write bounds assertion (#3738 H2b) ─────────────────────────────────
+  // The columns are far wider than these caps, so this LOUD, alertable failure
+  // is always the gate — Postgres's silent `numeric field overflow` (which used
+  // to land in the generic `write_failed` bucket and stall an org's billing
+  // permanently, with only a console.error to show for it) is unreachable.
+  const overflowed =
+    providerTotal > MAX_TOTAL_USD ||
+    billedTotal > MAX_TOTAL_USD ||
+    markupTotal > MAX_TOTAL_USD ||
+    totalTokens > MAX_TOTAL_TOKENS ||
+    !Number.isSafeInteger(totalTokens) ||
+    eventCount > MAX_EVENT_COUNT;
+
+  if (overflowed) {
+    console.error(
+      "usage-aggregation: ALERT aggregate_overflow — usage total exceeds the representable range; " +
+        "this organization's billing report CANNOT be written and revenue will stall until this is resolved",
+      {
+        organizationId: orgId,
+        periodStart: windowStart.toISOString(),
+        totalProviderCost: providerTotal,
+        totalBilledAmount: billedTotal,
+        totalTokens,
+        eventCount,
+        maxTotalUsd: MAX_TOTAL_USD,
+        maxTotalTokens: MAX_TOTAL_TOKENS,
+      },
+    );
+    return {
+      ok: false,
+      error: {
+        kind: "aggregate_overflow",
+        message: "usage total exceeds the representable range for a billing report",
+      },
+    };
+  }
+
+  const totals: AggregateTotals = {
+    totalProviderCost: providerTotal,
+    totalMarkupAmount: markupTotal,
+    totalBilledAmount: billedTotal,
+    totalTokens,
+    eventCount,
+    includedCents: 0,
+    creditBalanceCents: 0,
+    onDemandCents: 0,
+  };
+
+  try {
+    const report = await getOrCreateReport(orgId, windowStart, windowEnd, totals);
+    return { ok: true, reportId: report.id, totals };
+  } catch (error) {
+    // Log the detail server-side; NEVER return it (mirrors usage-metering.ts
+    // M5) — a Prisma validation error embeds the full `data` argument.
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error("usage-aggregation: report write failed", {
+      organizationId: orgId,
+      periodStart: windowStart.toISOString(),
+      detail,
+    });
+    return {
+      ok: false,
+      error: {
+        kind: "write_failed",
+        message: "usage billing report write failed",
+      },
+    };
+  }
+}