create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,941 @@
+/**
+ * @file usage-aggregation.test.ts
+ * @description Unit tests for the usage-aggregation service (ADR 0009 D3
+ * service-layer pattern; spec
+ * docs/specs/3705-s2-usage-aggregation-service-spec.md §5).
+ *
+ * External dependency boundary mocked:
+ *   - apps/api/src/lib/prisma — the repo-standard `__mocks__/prisma.ts`
+ *     manual mock (`jest.mock("../../lib/prisma.js")`), extended with
+ *     `usageEvent.aggregate` + `usageBillingReport.upsert` (#3714, FEAT-047
+ *     P2.S2 — not yet in the generated Prisma client this package compiles
+ *     against; `aggregate` since #3739 M2, was `findMany`). `usage-aggregation.ts`
+ *     casts `prisma` to a local structural delegate type
+ *     (`UsageAggregationPrismaDelegates`); this test does the same so the
+ *     mock's `jest.fn()` methods type-check the same way the service's calls
+ *     do.
+ *
+ * `usageEvent.aggregate` is given a REALISTIC `_sum`/`_count` implementation
+ * over an in-memory fixture "table" (mirroring `usage-metering.test.ts`'s
+ * `seedMarkupTable` pattern) so the org-isolation (AC-4/AC-UB-10) and
+ * period-window tests exercise the actual query-boundary filtering the
+ * service relies on, not just a static per-call stub — the fixture applies
+ * the SAME `where` filter a real Postgres aggregate would, then sums the
+ * matching rows itself (standing in for the DB's SUM).
+ *
+ * `usageBillingReport.upsert` is given REALISTIC upsert semantics over an
+ * in-memory table keyed by the compound `(organizationId, periodStart,
+ * periodEnd)` unique constraint, so the idempotency test (AC-2) proves no
+ * duplicate row is ever created on re-run — not merely that `upsert` was
+ * called twice.
+ *
+ * COLUMN-WIDTH ENFORCEMENT (#3738 H2 — load-bearing). The upsert fixture parses
+ * the REAL `database/content/schema.prisma` at test time, derives each persisted
+ * column's representable range from its declared type (`@db.Decimal(p,s)` /
+ * `Int` / `BigInt`), and THROWS the same errors Postgres would on overflow
+ * (`numeric field overflow`, `integer out of range`).
+ *
+ * This is what makes the $10k-month / 2.15B-token tests real rather than
+ * decorative. With a plain `jest.fn()` upsert an overflow is INVISIBLE — the
+ * mock happily accepts any JS number — so the H2 defect (aggregate columns
+ * sized for a single event: `Decimal(10,6)` = max $9,999.999999, `Int` = max
+ * 2.15B tokens) would sail through a mocked suite untouched, which is exactly
+ * how it reached `main`. By grounding the fixture in the actual schema file,
+ * the overflow tests FAIL against the pre-fix columns and pass only once the
+ * migration widens them — and they can never drift from the schema, because
+ * they read it.
+ */
+
+// 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 { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { prisma } from "../../lib/prisma.js";
+import {
+  aggregateUsagePeriod,
+  type AggregateResult,
+  type UsageAggregationPrismaDelegates,
+} from "../usage-aggregation";
+
+// The generated Prisma client doesn't carry the FEAT-047 P1 models yet
+// (#3709/#3710) — see the file docblock. Same structural cast the service
+// source uses.
+// eslint-disable-next-line no-restricted-syntax -- prisma's TS type resolves to the real (not-yet-augmented) PrismaClient; the FEAT-047 content-namespace delegates (usageEvent/usageBillingReport, #3709) don't exist on it yet, so the intermediate `unknown` widening is required, not gratuitous — mirrors the identical cast in usage-aggregation.ts.
+const db = prisma as unknown as UsageAggregationPrismaDelegates;
+
+/** The delegate methods are typed as plain functions; the mock behind them is a jest.Mock. */
+const mockOf = (fn: unknown): jest.Mock => fn as jest.Mock;
+
+const ORG_A = "org_00000000-0000-7000-8000-0000000000a1";
+const ORG_B = "org_00000000-0000-7000-8000-0000000000b2";
+
+/** March 2026 (UTC) — the test period. */
+const PERIOD_START = new Date(Date.UTC(2026, 2, 1));
+const PERIOD_END = new Date(Date.UTC(2026, 3, 1)); // April 1, UTC — exclusive upper bound
+/** Any timestamp within the period; the service normalizes to the month start. */
+const MID_PERIOD_DATE = new Date(Date.UTC(2026, 2, 1));
+
+// ── Schema-grounded column limits (#3738 H2) ─────────────────────────────────
+// Parsed from the REAL schema so the fixture's overflow behaviour can never
+// drift from the migration. See the file docblock for why this is load-bearing.
+
+const SCHEMA_PATH = resolve(
+  __dirname,
+  "../../../../../database/content/schema.prisma",
+);
+
+/** The `UsageBillingReport` model block, verbatim from database/content/schema.prisma. */
+function readReportModelBlock(): string {
+  const schema = readFileSync(SCHEMA_PATH, "utf8");
+  const match = schema.match(/model\s+UsageBillingReport\s*\{([\s\S]*?)\n\}/);
+  if (!match?.[1]) {
+    throw new Error(
+      `Could not locate the UsageBillingReport model in ${SCHEMA_PATH}`,
+    );
+  }
+  return match[1];
+}
+
+/** Max value a Postgres `numeric(p, s)` column can hold: 10^(p-s) - 10^-s. */
+function decimalMax(precision: number, scale: number): number {
+  return 10 ** (precision - scale) - 10 ** -scale;
+}
+
+const INT4_MAX = 2_147_483_647;
+const INT8_MAX = 9_223_372_036_854_775_807n;
+
+type ColumnLimit =
+  | { kind: "decimal"; max: number }
+  | { kind: "int4"; max: number }
+  | { kind: "int8"; max: bigint };
+
+/**
+ * Derives the representable range of a `UsageBillingReport` field from the
+ * live schema — `@db.Decimal(p,s)` -> numeric bounds; bare `Int` -> int4;
+ * `BigInt` -> int8.
+ */
+function columnLimit(field: string): ColumnLimit {
+  const block = readReportModelBlock();
+  const line = block
+    .split("\n")
+    .find((l) => new RegExp(`^\\s*${field}\\s+\\w`).test(l));
+  if (!line) {
+    throw new Error(`Field ${field} not found on UsageBillingReport`);
+  }
+
+  const dec = line.match(/@db\.Decimal\((\d+)\s*,\s*(\d+)\)/);
+  if (dec) {
+    return { kind: "decimal", max: decimalMax(Number(dec[1]), Number(dec[2])) };
+  }
+  if (/^\s*\w+\s+BigInt\b/.test(line)) return { kind: "int8", max: INT8_MAX };
+  if (/^\s*\w+\s+Int\b/.test(line)) return { kind: "int4", max: INT4_MAX };
+  throw new Error(`Unrecognised column type for ${field}: ${line.trim()}`);
+}
+
+/** The persisted columns the service writes, with their schema-derived limits. */
+const PERSISTED_COLUMNS = [
+  "totalProviderCost",
+  "totalMarkupAmount",
+  "totalBilledAmount",
+  "totalTokens",
+  "eventCount",
+] as const;
+
+/**
+ * Throws exactly as Postgres would when a written value exceeds its column.
+ * This is the check a `jest.fn()` upsert silently skips — and the reason the
+ * H2 overflow reached `main`.
+ */
+function assertFitsColumns(data: Record<string, unknown>): void {
+  for (const field of PERSISTED_COLUMNS) {
+    if (!(field in data)) continue;
+    const raw = data[field];
+    if (raw === undefined || raw === null) continue;
+
+    const limit = columnLimit(field);
+    const value = typeof raw === "bigint" ? raw : Number(raw);
+
+    if (limit.kind === "decimal") {
+      if (Math.abs(Number(value)) > limit.max) {
+        throw new Error(
+          `numeric field overflow: a field with precision limit ${limit.max} ` +
+            `cannot hold ${String(value)} (column ${field})`,
+        );
+      }
+    } else if (limit.kind === "int4") {
+      if (Math.abs(Number(value)) > limit.max) {
+        throw new Error(`integer out of range (column ${field})`);
+      }
+    } else {
+      const asBig =
+        typeof value === "bigint" ? value : BigInt(Math.trunc(Number(value)));
+      if (asBig > limit.max || asBig < -limit.max) {
+        throw new Error(`bigint out of range (column ${field})`);
+      }
+    }
+  }
+}
+
+type FixtureEvent = {
+  organizationId: string;
+  completionStatus: string;
+  createdAt: Date;
+  providerCostUsd: unknown;
+  billedCostUsd: unknown;
+  totalTokens: unknown;
+};
+
+/** The in-memory "usage_events" fixture table `aggregate` sums over. */
+let eventTable: FixtureEvent[];
+/** The in-memory "usage_billing_reports" table, keyed by the compound unique constraint. */
+let reportTable: Map<string, Record<string, unknown> & { id: string }>;
+let reportIdCounter: number;
+
+function reportKey(organizationId: string, periodStart: Date, periodEnd: Date): string {
+  return `${organizationId}|${periodStart.toISOString()}|${periodEnd.toISOString()}`;
+}
+
+/**
+ * Coerces a fixture row's value the same way a real Postgres NOT NULL
+ * Decimal/Int column would have to (the fixture's inputs are already
+ * numeric or Decimal-shaped by construction — `seedEvent`'s type only
+ * accepts those) — mirrors the service's own `toNumber` for Decimal-like
+ * `{ toNumber() }` fixture rows (#3738 M1's coercion tests).
+ */
+function fixtureToNumber(value: unknown): number {
+  if (typeof value === "number") return 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;
+}
+
+/** Installs realistic aggregate() _sum/_count filtering + realistic upsert (insert-or-update, no duplicates). */
+function installFixtureDb() {
+  // #3739 M2 — stands in for Postgres's SUM: filters the in-memory table by
+  // the same `where` clause a real aggregate query would apply, then sums
+  // the matching rows' three columns and reports the count. Returns `null`
+  // per `_sum` field when zero rows match (Prisma's own convention), so
+  // callers exercise the same null-coalescing path production hits.
+  mockOf(db.usageEvent.aggregate).mockImplementation(
+    async (args: {
+      where: {
+        organizationId: string;
+        completionStatus: string;
+        createdAt: { gte: Date; lt: Date };
+      };
+    }) => {
+      const { organizationId, completionStatus, createdAt } = args.where;
+      const matching = eventTable.filter(
+        (e) =>
+          e.organizationId === organizationId &&
+          e.completionStatus === completionStatus &&
+          e.createdAt.getTime() >= createdAt.gte.getTime() &&
+          e.createdAt.getTime() < createdAt.lt.getTime(),
+      );
+      if (matching.length === 0) {
+        return {
+          _sum: { providerCostUsd: null, billedCostUsd: null, totalTokens: null },
+          _count: 0,
+        };
+      }
+      let providerCostUsd = 0;
+      let billedCostUsd = 0;
+      let totalTokens = 0;
+      for (const row of matching) {
+        providerCostUsd += fixtureToNumber(row.providerCostUsd);
+        billedCostUsd += fixtureToNumber(row.billedCostUsd);
+        totalTokens += fixtureToNumber(row.totalTokens);
+      }
+      return {
+        _sum: { providerCostUsd, billedCostUsd, totalTokens },
+        _count: matching.length,
+      };
+    },
+  );
+
+  mockOf(db.usageBillingReport.upsert).mockImplementation(
+    async (args: {
+      where: {
+        organizationId_periodStart_periodEnd: {
+          organizationId: string;
+          periodStart: Date;
+          periodEnd: Date;
+        };
+      };
+      create: Record<string, unknown>;
+      update: Record<string, unknown>;
+    }) => {
+      const { organizationId, periodStart, periodEnd } =
+        args.where.organizationId_periodStart_periodEnd;
+      const key = reportKey(organizationId, periodStart, periodEnd);
+      const existing = reportTable.get(key);
+      if (existing) {
+        // Postgres validates the written values against the column types —
+        // so does this fixture (#3738 H2).
+        assertFitsColumns(args.update);
+        const updated = { ...existing, ...args.update };
+        reportTable.set(key, updated);
+        return { id: existing.id };
+      }
+      assertFitsColumns(args.create);
+      reportIdCounter += 1;
+      const id = `rpt_${reportIdCounter}`;
+      const created = { id, ...args.create };
+      reportTable.set(key, created);
+      return { id };
+    },
+  );
+}
+
+/** The system-default markup usage-metering falls back to (20%). */
+const DEFAULT_MARKUP = 1.2;
+
+/**
+ * Seeds one UsageEvent. When `billedCostUsd` is not pinned explicitly it is
+ * DERIVED from `providerCostUsd` at the default markup, so the fixture always
+ * produces a COHERENT event (billed >= provider), exactly as `recordUsageEvent`
+ * writes it.
+ *
+ * Previously the default was a flat `billedCostUsd: 1.2`, which — paired with
+ * an explicit `providerCostUsd: 3` / `999` — silently produced INVERTED events
+ * (billed < provider: billing below cost). Those are impossible in production
+ * and are now correctly rejected by the money invariants (#3738 M1), so the
+ * fixture must model a real event rather than an impossible one. A test that
+ * WANTS an inverted row still pins `billedCostUsd` explicitly.
+ */
+function seedEvent(overrides: Partial<FixtureEvent>): void {
+  const merged = {
+    organizationId: ORG_A,
+    completionStatus: "success",
+    createdAt: MID_PERIOD_DATE,
+    providerCostUsd: 1,
+    totalTokens: 1_000,
+    ...overrides,
+  };
+
+  const billedCostUsd =
+    "billedCostUsd" in overrides
+      ? overrides.billedCostUsd
+      : typeof merged.providerCostUsd === "number"
+        ? merged.providerCostUsd * DEFAULT_MARKUP
+        : DEFAULT_MARKUP;
+
+  eventTable.push({ ...merged, billedCostUsd });
+}
+
+function expectInvalidInput(result: AggregateResult) {
+  expect(result.ok).toBe(false);
+  const err = result as Extract<AggregateResult, { ok: false }>;
+  expect(err.error.kind).toBe("invalid_input");
+}
+
+describe("aggregateUsagePeriod", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(console, "warn").mockImplementation(() => undefined);
+    jest.spyOn(console, "error").mockImplementation(() => undefined);
+    eventTable = [];
+    reportTable = new Map();
+    reportIdCounter = 0;
+    installFixtureDb();
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  // ── AC-1: SUM successful UsageEvents into the totals ──────────────────────
+  it("AC-1: SUMs successful UsageEvents into provider/markup/billed/tokens/eventCount", async () => {
+    seedEvent({ providerCostUsd: 3, billedCostUsd: 3.6, totalTokens: 1_000_000 });
+    seedEvent({ providerCostUsd: 2, billedCostUsd: 2.4, totalTokens: 500_000 });
+
+    const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+    expect(result.ok).toBe(true);
+    const ok = result as Extract<AggregateResult, { ok: true }>;
+    expect(ok.totals).toEqual({
+      totalProviderCost: 5,
+      totalMarkupAmount: 1,
+      totalBilledAmount: 6,
+      totalTokens: 1_500_000,
+      eventCount: 2,
+      includedCents: 0,
+      creditBalanceCents: 0,
+      onDemandCents: 0,
+    });
+  });
+
+  it("AC-1: filters out non-success completionStatus (D2) — an error/pricing_missing event is excluded", async () => {
+    seedEvent({ providerCostUsd: 3, billedCostUsd: 3.6, totalTokens: 1_000 });
+    seedEvent({
+      completionStatus: "error",
+      providerCostUsd: 100,
+      billedCostUsd: 120,
+      totalTokens: 999_999,
+    });
+    seedEvent({
+      completionStatus: "pricing_missing:success",
+      providerCostUsd: 0,
+      billedCostUsd: 0,
+      totalTokens: 999_999,
+    });
+
+    const result = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+      AggregateResult,
+      { ok: true }
+    >;
+
+    expect(result.totals.eventCount).toBe(1);
+    expect(result.totals.totalProviderCost).toBe(3);
+    expect(result.totals.totalTokens).toBe(1_000);
+  });
+
+  it("AC-1: excludes events outside the period window (before periodStart / at-or-after periodEnd)", async () => {
+    seedEvent({
+      createdAt: new Date(PERIOD_START.getTime() - 1),
+      providerCostUsd: 10,
+    }); // just before the window
+    seedEvent({ createdAt: PERIOD_START, providerCostUsd: 1 }); // inclusive lower bound
+    seedEvent({ createdAt: PERIOD_END, providerCostUsd: 10 }); // exclusive upper bound — excluded
+    seedEvent({
+      createdAt: new Date(PERIOD_END.getTime() - 1),
+      providerCostUsd: 1,
+    }); // just inside the window
+
+    const result = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+      AggregateResult,
+      { ok: true }
+    >;
+
+    expect(result.totals.eventCount).toBe(2);
+    expect(result.totals.totalProviderCost).toBe(2);
+  });
+
+  it("a periodStart mid-month normalizes to the calendar-month window", async () => {
+    seedEvent({ createdAt: MID_PERIOD_DATE, providerCostUsd: 5 });
+
+    const midMonth = new Date(Date.UTC(2026, 2, 17, 8, 30));
+    const result = (await aggregateUsagePeriod(ORG_A, midMonth)) as Extract<
+      AggregateResult,
+      { ok: true }
+    >;
+
+    expect(result.totals.eventCount).toBe(1);
+    expect(result.totals.totalProviderCost).toBe(5);
+  });
+
+  // ── AC-2: idempotent getOrCreateReport ─────────────────────────────────────
+  describe("AC-2: idempotency", () => {
+    it("a second invocation for the same (org, period) UPDATES the same report — no duplicate", async () => {
+      seedEvent({ providerCostUsd: 1, billedCostUsd: 1.2, totalTokens: 100 });
+
+      const first = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      // A second event lands before the re-run — the re-run must reflect it.
+      seedEvent({ providerCostUsd: 2, billedCostUsd: 2.4, totalTokens: 200 });
+      const second = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      expect(second.reportId).toBe(first.reportId);
+      expect(reportTable.size).toBe(1); // no duplicate row
+      expect(second.totals.eventCount).toBe(2);
+      expect(second.totals.totalProviderCost).toBe(3);
+      expect(db.usageBillingReport.upsert).toHaveBeenCalledTimes(2);
+    });
+
+    it("status stays PENDING across a re-run (P2 never advances it)", async () => {
+      seedEvent({ providerCostUsd: 1, billedCostUsd: 1.2, totalTokens: 100 });
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      const [record] = Array.from(reportTable.values());
+      // The service never writes `status` — the DB default (PENDING) stands,
+      // and a re-run's `update` payload must not carry the key either.
+      const updateCall = mockOf(db.usageBillingReport.upsert).mock.calls[1]?.[0] as {
+        update: Record<string, unknown>;
+      };
+      expect(updateCall.update).not.toHaveProperty("status");
+      expect(record).not.toHaveProperty("status");
+    });
+
+    it("a re-run does not clobber attribution cents a later phase (P3/P4) may have set", async () => {
+      seedEvent({ providerCostUsd: 1, billedCostUsd: 1.2, totalTokens: 100 });
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      // Simulate P3/P4 having since applied attribution to the persisted row.
+      const [key] = Array.from(reportTable.keys());
+      const existing = reportTable.get(key!)!;
+      reportTable.set(key!, { ...existing, includedCents: 500 });
+
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      const updated = reportTable.get(key!)!;
+      expect(updated.includedCents).toBe(500);
+    });
+  });
+
+  // ── AC-3 (AC-UB-03a): reconciliation over a full test period ───────────────
+  describe("AC-3: reconciliation (AC-UB-03a)", () => {
+    it("report totals equal the SUM of source events, and totalBilled == totalProvider * (1 + markup) within tolerance", async () => {
+      const MARKUP = 0.2; // 20% — matches the system-default markup usage-metering falls back to
+      const events = [
+        { providerCostUsd: 3, tokens: 1_000_000 },
+        { providerCostUsd: 2, tokens: 500_000 },
+        { providerCostUsd: 7.5, tokens: 2_250_000 },
+        { providerCostUsd: 0.333333, tokens: 10_000 },
+      ];
+      let expectedProvider = 0;
+      let expectedBilled = 0;
+      let expectedTokens = 0;
+      for (const e of events) {
+        const billed = e.providerCostUsd * (1 + MARKUP);
+        seedEvent({
+          providerCostUsd: e.providerCostUsd,
+          billedCostUsd: billed,
+          totalTokens: e.tokens,
+        });
+        expectedProvider += e.providerCostUsd;
+        expectedBilled += billed;
+        expectedTokens += e.tokens;
+      }
+
+      const result = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      expect(result.totals.totalProviderCost).toBeCloseTo(expectedProvider, 6);
+      expect(result.totals.totalBilledAmount).toBeCloseTo(expectedBilled, 6);
+      expect(result.totals.totalTokens).toBe(expectedTokens);
+      expect(result.totals.eventCount).toBe(events.length);
+
+      // AC-UB-03a — the reconciliation identity, within tolerance.
+      expect(result.totals.totalBilledAmount).toBeCloseTo(
+        result.totals.totalProviderCost * (1 + MARKUP),
+        6,
+      );
+      // totalBilled == totalProvider + totalMarkup holds exactly by construction.
+      expect(
+        result.totals.totalProviderCost + result.totals.totalMarkupAmount,
+      ).toBeCloseTo(result.totals.totalBilledAmount, 10);
+    });
+
+    it("an empty period reconciles to all-zero totals, not a missing/undefined report", async () => {
+      const result = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      expect(result.totals).toEqual({
+        totalProviderCost: 0,
+        totalMarkupAmount: 0,
+        totalBilledAmount: 0,
+        totalTokens: 0,
+        eventCount: 0,
+        includedCents: 0,
+        creditBalanceCents: 0,
+        onDemandCents: 0,
+      });
+    });
+  });
+
+  // ── AC-4 (AC-UB-10): org isolation ─────────────────────────────────────────
+  describe("AC-4: org isolation (AC-UB-10)", () => {
+    it("org A's aggregation never includes org B's events", async () => {
+      seedEvent({ organizationId: ORG_A, providerCostUsd: 3, totalTokens: 100 });
+      seedEvent({ organizationId: ORG_B, providerCostUsd: 999, totalTokens: 999_999 });
+
+      const resultA = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      expect(resultA.totals.eventCount).toBe(1);
+      expect(resultA.totals.totalProviderCost).toBe(3);
+      expect(resultA.totals.totalTokens).toBe(100);
+    });
+
+    it("the query is organizationId-scoped at the boundary, not filtered client-side", async () => {
+      seedEvent({ organizationId: ORG_A });
+
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(db.usageEvent.aggregate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          where: expect.objectContaining({ organizationId: ORG_A }),
+        }),
+      );
+    });
+
+    it("org A and org B get separate reports for the same period", async () => {
+      seedEvent({ organizationId: ORG_A, providerCostUsd: 1 });
+      seedEvent({ organizationId: ORG_B, providerCostUsd: 2 });
+
+      const resultA = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+      const resultB = (await aggregateUsagePeriod(ORG_B, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      expect(resultA.reportId).not.toBe(resultB.reportId);
+      expect(reportTable.size).toBe(2);
+    });
+  });
+
+  // ── AC-5: discriminated result, PII-safe logging, invalid-input handling ──
+  describe("AC-5: boundary validation + result shape", () => {
+    it("rejects a malformed organizationId", async () => {
+      const result = await aggregateUsagePeriod("not-an-org-id", PERIOD_START);
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.aggregate).not.toHaveBeenCalled();
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("rejects an invalid Date", async () => {
+      const result = await aggregateUsagePeriod(ORG_A, new Date(NaN));
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.aggregate).not.toHaveBeenCalled();
+    });
+
+    it("the error names the offending field", async () => {
+      const result = await aggregateUsagePeriod("not-an-org-id", PERIOD_START);
+
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.message).toContain("organizationId");
+    });
+
+    it("PII/content non-leak — the ok result carries only ids/counts/computed totals", async () => {
+      seedEvent({});
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(Object.keys(result)).toEqual(
+        expect.arrayContaining(["ok", "reportId", "totals"]),
+      );
+      const ok = result as Extract<AggregateResult, { ok: true }>;
+      expect(Object.keys(ok.totals).sort()).toEqual(
+        [
+          "creditBalanceCents",
+          "eventCount",
+          "includedCents",
+          "onDemandCents",
+          "totalBilledAmount",
+          "totalMarkupAmount",
+          "totalProviderCost",
+          "totalTokens",
+        ].sort(),
+      );
+    });
+  });
+
+  // ── Non-finite guard — a corrupt row must never poison the persisted report ─
+  describe("non-finite guard (fails closed, never persists a poisoned total)", () => {
+    it("a NaN-valued stored event fails the aggregation rather than writing NaN", async () => {
+      seedEvent({ providerCostUsd: Number.NaN, billedCostUsd: 1, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregation_failed");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a corrupt Decimal-shaped row (unparseable) fails the aggregation, never persists", async () => {
+      seedEvent({ providerCostUsd: "not-a-number", billedCostUsd: 1, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregation_failed");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a Prisma-Decimal-like row (object with toNumber()) coerces correctly on the happy path", async () => {
+      seedEvent({
+        providerCostUsd: { toNumber: () => 4 },
+        billedCostUsd: { toNumber: () => 4.8 },
+        totalTokens: 1_000,
+      });
+
+      const result = (await aggregateUsagePeriod(ORG_A, PERIOD_START)) as Extract<
+        AggregateResult,
+        { ok: true }
+      >;
+
+      expect(result.ok).toBe(true);
+      expect(result.totals.totalProviderCost).toBe(4);
+      expect(result.totals.totalBilledAmount).toBe(4.8);
+    });
+  });
+
+  // ── write_failed — the report write itself throws ─────────────────────────
+  describe("write_failed", () => {
+    it("a report-write failure returns write_failed and does not leak the raw error", async () => {
+      seedEvent({ providerCostUsd: 1, billedCostUsd: 1.2, totalTokens: 1 });
+      const leaky = new Error(
+        `Invalid \`prisma.usageBillingReport.upsert()\` invocation: { organizationId: "${ORG_A}" }`,
+      );
+      mockOf(db.usageBillingReport.upsert).mockRejectedValueOnce(leaky);
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("write_failed");
+      expect(err.error.message).not.toContain(ORG_A);
+      expect(err.error.message).not.toContain("prisma");
+      expect(console.error).toHaveBeenCalled();
+    });
+  });
+
+  // ── H1 (#3738): the READ path is inside the error guard ───────────────────
+  // Before the fix, the read (findMany, then aggregate since #3739 M2) sat
+  // OUTSIDE the try/catch, so a DB read error rejected the promise instead of
+  // returning the discriminated union the docblock promises ("Never
+  // throws"). #3717's route will trust that union.
+  describe("H1: read-path error guard (the union contract holds on a read failure)", () => {
+    it("a DB read failure returns a discriminated result rather than throwing", async () => {
+      mockOf(db.usageEvent.aggregate).mockRejectedValueOnce(
+        new Error("connection pool timeout"),
+      );
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("read_failed");
+      // Fails closed — a failed read must never write a (zeroed) report.
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a read failure does not leak the tenant id or the raw Prisma error", async () => {
+      // Prisma read errors embed the `where` clause — which carries the org id.
+      const leaky = new Error(
+        `Invalid \`prisma.usageEvent.aggregate()\` invocation: { where: { organizationId: "${ORG_A}" } }`,
+      );
+      mockOf(db.usageEvent.aggregate).mockRejectedValueOnce(leaky);
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.message).not.toContain(ORG_A);
+      expect(err.error.message).not.toContain("prisma");
+      // The detail is logged server-side only.
+      expect(console.error).toHaveBeenCalled();
+    });
+  });
+
+  // ── H2a (#3738): the aggregate columns can represent a real month ─────────
+  // These are the load-bearing tests. The upsert fixture enforces the REAL
+  // schema's column widths (see the file docblock), so both cases FAIL against
+  // the pre-fix `Decimal(10,6)` / `Int` columns — the exact defect that stalls
+  // billing forever for the largest tenants.
+  describe("H2a: aggregate columns hold a large month (schema-grounded)", () => {
+    it("a $10,000+ provider-cost month aggregates and persists", async () => {
+      // 3 × $4,000 = $12,000 provider — past the old Decimal(10,6) ceiling
+      // ($9,999.999999), which made the upsert throw and permanently stall the
+      // report for this org.
+      for (let i = 0; i < 3; i += 1) {
+        seedEvent({
+          providerCostUsd: 4_000,
+          billedCostUsd: 4_800,
+          totalTokens: 1_000,
+        });
+      }
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(true);
+      const ok = result as Extract<AggregateResult, { ok: true }>;
+      expect(ok.totals.totalProviderCost).toBe(12_000);
+      expect(ok.totals.totalBilledAmount).toBe(14_400);
+      expect(ok.totals.totalMarkupAmount).toBe(2_400);
+      // The report row actually exists — billing did not stall.
+      expect(reportTable.size).toBe(1);
+    });
+
+    it("a >2.15B-token month aggregates and persists", async () => {
+      // 3 × 800M = 2.4B tokens — past the old int4 ceiling (2,147,483,647).
+      // ~700k requests at 3k tokens: one busy tenant.
+      for (let i = 0; i < 3; i += 1) {
+        seedEvent({
+          providerCostUsd: 1,
+          billedCostUsd: 1.2,
+          totalTokens: 800_000_000,
+        });
+      }
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(true);
+      const ok = result as Extract<AggregateResult, { ok: true }>;
+      expect(ok.totals.totalTokens).toBe(2_400_000_000);
+      expect(reportTable.size).toBe(1);
+    });
+
+    it("totalTokens is written as a BigInt (the widened int8 column)", async () => {
+      seedEvent({ totalTokens: 3_000_000_000 });
+
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      const createCall = mockOf(db.usageBillingReport.upsert).mock
+        .calls[0]?.[0] as { create: Record<string, unknown> };
+      expect(typeof createCall.create.totalTokens).toBe("bigint");
+      expect(createCall.create.totalTokens).toBe(3_000_000_000n);
+    });
+
+    it("the schema itself declares aggregate-sized columns (guards against a schema regression)", () => {
+      // Asserted directly against database/content/schema.prisma so a future
+      // narrowing of these columns fails here, not in production billing.
+      const provider = columnLimit("totalProviderCost");
+      const billed = columnLimit("totalBilledAmount");
+      const markup = columnLimit("totalMarkupAmount");
+      const tokens = columnLimit("totalTokens");
+
+      // Must comfortably clear a $10k month (the old ceiling).
+      for (const usd of [provider, billed, markup]) {
+        expect(usd.kind).toBe("decimal");
+        expect(usd.max as number).toBeGreaterThan(1_000_000);
+      }
+      // Must be int8 — int4 tops out at 2.15B tokens.
+      expect(tokens.kind).toBe("int8");
+    });
+  });
+
+  // ── H2b (#3738): a pre-write bounds assertion, LOUD and alertable ─────────
+  // Fail-closed is right, but the failure must be DISTINGUISHABLE — a generic
+  // `write_failed` + a bare console.error is how silent, permanent,
+  // largest-customer revenue loss goes unnoticed.
+  describe("H2b: bounds assertion fails closed with a distinct, alertable kind", () => {
+    it("a total beyond the representable range returns aggregate_overflow, not write_failed", async () => {
+      // Past the service's own MAX_TOTAL_USD cap. Reached here via two large
+      // rows; in production, via a corrupt row or an org past the cap. Either
+      // way the guard protects the TOTAL, however it is arrived at.
+      seedEvent({ providerCostUsd: 6e8, billedCostUsd: 7e8, totalTokens: 1 });
+      seedEvent({ providerCostUsd: 6e8, billedCostUsd: 7e8, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregate_overflow");
+      // Distinct from the generic write failure — this is the alertable signal.
+      expect(err.error.kind).not.toBe("write_failed");
+      // Never persists a truncated/overflowed total.
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a token total beyond MAX_SAFE_INTEGER returns aggregate_overflow", async () => {
+      seedEvent({ totalTokens: 9e15 });
+      seedEvent({ totalTokens: 9e15 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregate_overflow");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("the overflow is logged as an alertable event, not a bare generic error", async () => {
+      seedEvent({ providerCostUsd: 6e8, billedCostUsd: 7e8 });
+      seedEvent({ providerCostUsd: 6e8, billedCostUsd: 7e8 });
+
+      await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      // The log line must name the overflow so it can be alerted on.
+      const logged = mockOf(console.error).mock.calls.flat().map(String).join(" ");
+      expect(logged).toMatch(/overflow/i);
+    });
+
+    it("the assertion fires BEFORE the column limit, so Postgres never overflows", async () => {
+      // The service's cap ($1B) sits far below the column capacity
+      // (Decimal(20,6) ≈ $1e14), so the loud assertion is always the gate —
+      // the DB's silent numeric overflow is unreachable.
+      const cap = columnLimit("totalProviderCost");
+      expect(cap.kind).toBe("decimal");
+      expect(cap.max as number).toBeGreaterThan(1e9);
+    });
+  });
+
+  // ── M1 (#3738): the money guard checks non-negative, not just finite ──────
+  // A negative total is FINITE — it sails through a finite-only guard and
+  // persists as a credit. This is the class that produced the sibling's bug.
+  describe("M1: non-negative + reconciliation guard", () => {
+    it("a negative provider cost fails closed rather than persisting a credit", async () => {
+      seedEvent({ providerCostUsd: -5, billedCostUsd: 1, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregation_failed");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a billed total below the provider total (negative markup) fails closed", async () => {
+      seedEvent({ providerCostUsd: 10, billedCostUsd: 5, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregation_failed");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("a negative token count fails closed", async () => {
+      seedEvent({ totalTokens: -100 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── L1 (#3738): toNumber must not coerce an unusable value to a silent 0 ──
+  describe("L1: unusable column values fail closed, never coerce to a silent zero", () => {
+    it("a null money column fails the aggregation rather than underbilling as 0", async () => {
+      // `Number(null) === 0` — the old coercion silently DROPPED the row's cost
+      // (an underbill) instead of the NaN the docblock claimed it produced.
+      seedEvent({ providerCostUsd: null, billedCostUsd: 1, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      expect(result.ok).toBe(false);
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregation_failed");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+
+    it("an empty-string money column fails the aggregation (Number('') === 0)", async () => {
+      seedEvent({ providerCostUsd: "", billedCostUsd: 1, totalTokens: 1 });
+
+      const result = await aggregateUsagePeriod(ORG_A, PERIOD_START);
+
+      const err = result as Extract<AggregateResult, { ok: false }>;
+      expect(err.error.kind).toBe("aggregation_failed");
+      expect(db.usageBillingReport.upsert).not.toHaveBeenCalled();
+    });
+  });
+});