create-ailk 0.23.0 → 0.25.1

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

@@ -1,941 +0,0 @@
-/**
- * @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();
-    });
-  });
-});