create-ailk 0.23.0 → 0.25.1

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

@@ -1,516 +0,0 @@
-/**
- * @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",
-      },
-    };
-  }
-}