create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,768 @@
+// oss: false
+/**
+ * @file usage-metering.test.ts
+ * @description Unit tests for the usage-metering service (ADR 0009 D3
+ * service-layer pattern; spec docs/specs/3705-s1-usage-metering-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 the
+ *     FEAT-047 P1 model namespaces (usageEvent/usagePeriod/llmModel/
+ *     llmModelPricing/aiMarkupConfig — #3709/#3710, not yet in the generated
+ *     Prisma client this package compiles against) plus `$transaction`.
+ *     `usage-metering.ts` casts `prisma` to a local structural delegate type
+ *     (`UsageMeteringPrismaDelegates`); this test does the same so the mock's
+ *     `jest.fn()` methods type-check the same way the service's calls do —
+ *     this test harness stands in for the not-yet-existing live AI call
+ *     (AC-UB-02 service-level, per the spec's §1 scope-reality note).
+ *
+ * `aiMarkupConfig.findFirst` is given a REALISTIC filtering implementation
+ * over an in-memory fixture "table" (mirroring lead-promotion.test.ts's
+ * `seedLeadTable` pattern) so the hierarchy tests (AC-2) exercise the actual
+ * precedence the service resolves, not just a static per-call stub.
+ *
+ * `$transaction` is likewise given REALISTIC commit/rollback semantics over an
+ * in-memory `committedEvents` store (`installAtomicDb`), while the BASE client's
+ * `usageEvent.create` models an AUTO-COMMIT write. That asymmetry is what makes
+ * the H3 atomicity test load-bearing: a non-transactional implementation (write
+ * the event, THEN upsert) commits the event immediately, so a failing upsert
+ * strands an orphan row in `committedEvents` and the test fails. Only writes
+ * routed through `$transaction` roll back.
+ *
+ * Security-review coverage (PR #3727): every High/Medium finding carries a test
+ * that fails without its fix. H1/H2 (per-event `ceil` to whole cents) are
+ * deliberately NOT addressed — a spec-level billing-fairness decision escalated
+ * to Sam — so the 360¢ expectation below still encodes the current rounding.
+ */
+
+// 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 type { Id } from "@working-theory/ids";
+
+import { prisma } from "../../lib/prisma.js";
+import type { TenantContext } from "../tenant-context.js";
+import {
+  calculateProviderCost,
+  recordUsageEvent,
+  type ModelPricing,
+  type RecordUsageEventInput,
+  type RecordUsageResult,
+  type UsageMeteringPrismaDelegates,
+  type UsageWriteClient,
+} from "../usage-metering";
+
+// The generated Prisma client doesn't carry the FEAT-047 P1 models yet
+// (#3709/#3710 unmerged) — 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 P1 model delegates (usageEvent/usagePeriod/llmModel/llmModelPricing/aiMarkupConfig, #3709/#3710) don't exist on it yet, so the intermediate `unknown` widening is required, not gratuitous — mirrors the identical cast in usage-metering.ts.
+const db = prisma as unknown as UsageMeteringPrismaDelegates;
+
+/** 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_ID = "org_00000000-0000-7000-8000-0000000000a1" as Id<"organization">;
+const WORKSPACE_ID = "wksp_00000000-0000-7000-8000-0000000000b1" as Id<"workspace">;
+const USER_ID = "user_00000000-0000-7000-8000-0000000000c1" as Id<"user">;
+const PROVIDER = "anthropic";
+const MODEL = "claude-fable";
+
+/** The resolved tenant grain — what `resolveActiveTenant` hands the service (H5). */
+const TENANT: TenantContext = {
+  userId: USER_ID,
+  organizationId: ORG_ID,
+  workspaceId: WORKSPACE_ID,
+  role: "owner",
+};
+
+function baseInput(overrides?: Partial<RecordUsageEventInput>): RecordUsageEventInput {
+  return {
+    tenant: TENANT,
+    provider: PROVIDER,
+    model: MODEL,
+    inputTokensNoCacheWrite: 1_000_000,
+    cacheReadTokens: 0,
+    outputTokens: 0,
+    ...overrides,
+  };
+}
+
+/** The in-memory "committed rows" store the atomicity assertions read (H3). */
+let committedEvents: unknown[];
+
+/**
+ * Forges a tenant grain that did NOT come from `resolveActiveTenant` — the H5
+ * bypass (a caller casting around the branded `Id<>` types, or a route stuffing
+ * request-supplied strings into the grain). The double assertion is the point of
+ * the test, not an accident: it reproduces exactly the shape the service's
+ * runtime id-grammar check must reject. "Fixing the type at the boundary" would
+ * delete the test.
+ */
+function forgedTenant(overrides: Record<string, string>): TenantContext {
+  // eslint-disable-next-line no-restricted-syntax -- see the docblock above: the unbranded cast IS the attack under test (H5).
+  return { ...TENANT, ...overrides } as unknown as TenantContext;
+}
+
+/**
+ * Installs a DB double with REAL transactional semantics:
+ *   - `$transaction(fn)` stages writes and commits them only if `fn` resolves;
+ *     a throw discards the staged rows (ROLLBACK).
+ *   - the BASE client's `usageEvent.create` commits IMMEDIATELY (auto-commit) —
+ *     modelling what a non-transactional implementation would do.
+ * Both base delegates keep recording their calls, so `toHaveBeenCalled*`
+ * assertions work regardless of which path a write took.
+ */
+function installAtomicDb(options?: { upsertError?: Error }) {
+  mockOf(db.usageEvent.create).mockImplementation(
+    async (args: { data: Record<string, unknown> }) => {
+      committedEvents.push(args.data); // auto-commit — nothing can roll this back
+      return { id: "evt_1" };
+    },
+  );
+  mockOf(db.usagePeriod.upsert).mockImplementation(async () => {
+    if (options?.upsertError) {
+      throw options.upsertError;
+    }
+    return {};
+  });
+
+  mockOf(db.$transaction).mockImplementation(
+    async (fn: (tx: UsageWriteClient) => Promise<unknown>) => {
+      const staged: unknown[] = [];
+      const tx: UsageWriteClient = {
+        usageEvent: {
+          create: async (args) => {
+            // Record the call on the base mock (so call assertions still work),
+            // but STAGE the row — it is only committed if the callback resolves.
+            mockOf(db.usageEvent.create).mock.calls.push([args]);
+            staged.push(args.data);
+            return { id: "evt_1" };
+          },
+        },
+        usagePeriod: {
+          upsert: async (args) =>
+            mockOf(db.usagePeriod.upsert)(args) as Promise<unknown>,
+        },
+      };
+      const result = await fn(tx);
+      committedEvents.push(...staged); // COMMIT (a throw above skips this → ROLLBACK)
+      return result;
+    },
+  );
+}
+
+/** Seeds aiMarkupConfig.findFirst with a realistic hierarchy-precedence filter. */
+function seedMarkupTable(
+  rows: Array<{
+    provider: string | null;
+    model: string | null;
+    markupPercent: unknown;
+  }>,
+) {
+  mockOf(db.aiMarkupConfig.findFirst).mockImplementation(
+    async (args: {
+      where: { organizationId: string; provider: string | null; model: string | null };
+    }) => {
+      const { organizationId, provider, model } = args.where;
+      if (organizationId !== ORG_ID) return null;
+      const row = rows.find((r) => r.provider === provider && r.model === model);
+      return row ? { markupPercent: row.markupPercent } : null;
+    },
+  );
+}
+
+function seedModel(overrides?: Record<string, unknown>) {
+  mockOf(db.llmModel.findFirst).mockResolvedValue({
+    tier: "BASE",
+    isAutoModel: false,
+    chargeExtendedContextAt2x: false,
+    consumptionMultiplier: 1,
+    ...overrides,
+  });
+}
+
+function seedPricing(overrides?: Record<string, unknown>) {
+  mockOf(db.llmModelPricing.findFirst).mockResolvedValue({
+    inputPricePerMillion: 1,
+    outputPricePerMillion: 1,
+    cachedInputPricePerMillion: null,
+    ...overrides,
+  });
+}
+
+/** The persisted `UsageEvent` data of the Nth create call. */
+function createdEventData(call = 0): Record<string, unknown> {
+  return mockOf(db.usageEvent.create).mock.calls[call]?.[0]?.data as Record<
+    string,
+    unknown
+  >;
+}
+
+/** The `usagePeriod.upsert` args of the Nth upsert call. */
+function upsertArgs(call = 0): {
+  create: Record<string, unknown>;
+  update: Record<string, unknown>;
+} {
+  return mockOf(db.usagePeriod.upsert).mock.calls[call]?.[0] as {
+    create: Record<string, unknown>;
+    update: Record<string, unknown>;
+  };
+}
+
+function expectInvalidInput(result: RecordUsageResult) {
+  expect(result.ok).toBe(false);
+  const err = result as Extract<RecordUsageResult, { ok: false }>;
+  expect(err.error.kind).toBe("invalid_input");
+  expect(err.error.persisted).toBe(false);
+}
+
+describe("calculateProviderCost", () => {
+  // ── AC-1: standard path ────────────────────────────────────────────────────
+  it("standard path — no context window / at-or-below 200K", () => {
+    const pricing: ModelPricing = {
+      inputPricePerMillion: 3,
+      outputPricePerMillion: 15,
+      cachedInputPricePerMillion: 0.3,
+    };
+    const cost = calculateProviderCost(1_000_000, 500_000, 200_000, pricing);
+    // inputCost=1*3=3, cachedInputCost=0.5*0.3=0.15, outputCost=0.2*15=3
+    expect(cost).toBeCloseTo(6.15, 6);
+  });
+
+  it("cached input defaults to half the input rate when unset", () => {
+    const pricing: ModelPricing = { inputPricePerMillion: 4, outputPricePerMillion: 20 };
+    const cost = calculateProviderCost(1_000_000, 1_000_000, 0, pricing);
+    // inputCost=1*4=4, cachedInputCost=1*(4*0.5)=2
+    expect(cost).toBeCloseTo(6, 6);
+  });
+
+  // ── AC-1: extended-context 2x split ────────────────────────────────────────
+  it("extended-context path — only when chargeExtendedAt2x AND contextWindowSize>200_000", () => {
+    const pricing: ModelPricing = {
+      inputPricePerMillion: 1,
+      outputPricePerMillion: 1,
+      cachedInputPricePerMillion: 1,
+    };
+    // 800K context: standardRatio=200K/800K=0.25, extendedRatio=0.75
+    // factor = 0.25*1 + 0.75*2 = 1.75
+    const cost = calculateProviderCost(1_000_000, 0, 0, pricing, 800_000, true);
+    expect(cost).toBeCloseTo(1.75, 6);
+  });
+
+  it("chargeExtendedAt2x=false skips the surcharge regardless of contextWindowSize", () => {
+    const pricing: ModelPricing = { inputPricePerMillion: 1, outputPricePerMillion: 1 };
+    const cost = calculateProviderCost(1_000_000, 0, 0, pricing, 800_000, false);
+    expect(cost).toBeCloseTo(1, 6);
+  });
+
+  it("contextWindowSize <= 200_000 skips the surcharge even when chargeExtendedAt2x=true", () => {
+    const pricing: ModelPricing = { inputPricePerMillion: 1, outputPricePerMillion: 1 };
+    const cost = calculateProviderCost(1_000_000, 0, 0, pricing, 200_000, true);
+    expect(cost).toBeCloseTo(1, 6);
+  });
+
+  it("contextWindowSize omitted defaults to 0 — extended pricing skipped (don't guess)", () => {
+    const pricing: ModelPricing = { inputPricePerMillion: 1, outputPricePerMillion: 1 };
+    const cost = calculateProviderCost(1_000_000, 0, 0, pricing, undefined, true);
+    expect(cost).toBeCloseTo(1, 6);
+  });
+});
+
+describe("recordUsageEvent", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(console, "warn").mockImplementation(() => undefined);
+    jest.spyOn(console, "error").mockImplementation(() => undefined);
+    committedEvents = [];
+    installAtomicDb();
+    seedModel();
+    seedPricing();
+    seedMarkupTable([]);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  // ── AC-3 (AC-UB-02 service-level): write UsageEvent then upsert UsagePeriod ─
+  it("AC-3: writes the UsageEvent (grain + costs + attribution=0) then upserts the UsagePeriod", async () => {
+    seedModel({ tier: "PREMIUM" });
+    seedPricing({ inputPricePerMillion: 3, outputPricePerMillion: 15 });
+
+    const result = await recordUsageEvent(baseInput());
+
+    // providerCost = 1M/1e6 * 3 = 3; billedCost = 3 * 1.2 = 3.6
+    expect(result.ok).toBe(true);
+    const okResult = result as Extract<RecordUsageResult, { ok: true }>;
+    expect(okResult.eventId).toBe("evt_1");
+    expect(okResult.billedCostUsd).toBeCloseTo(3.6, 6);
+
+    expect(createdEventData()).toEqual(
+      expect.objectContaining({
+        organizationId: ORG_ID,
+        workspaceId: WORKSPACE_ID,
+        userId: USER_ID,
+        provider: PROVIDER,
+        model: MODEL,
+        providerCostUsd: 3,
+        markupPercent: 20,
+        billedCostUsd: expect.closeTo(3.6, 6),
+        modelTier: "PREMIUM",
+        wasAutoModel: false,
+        includedPortionCents: 0,
+        creditBalancePortionCents: 0,
+        onDemandPortionCents: 0,
+        completionStatus: "success",
+      }),
+    );
+
+    // H1/H2 (per-event ceil to whole cents) are DELIBERATELY unchanged — this
+    // 360¢ expectation encodes the current, spec-mandated rounding, pending Sam's
+    // billing-fairness decision.
+    expect(upsertArgs().create).toEqual(
+      expect.objectContaining({
+        organizationId: ORG_ID,
+        tokensConsumed: 1_000_000,
+        usageSpendCents: 360, // ceil(3.6 * 100)
+        premiumTokensConsumed: 1_000_000,
+      }),
+    );
+    expect(upsertArgs().update).toEqual(
+      expect.objectContaining({
+        tokensConsumed: { increment: 1_000_000 },
+        usageSpendCents: { increment: 360 },
+        premiumTokensConsumed: { increment: 1_000_000 },
+      }),
+    );
+  });
+
+  // ── Tier-column selection (BASE / FRONTIER) ────────────────────────────────
+  it.each([
+    ["BASE", "baseTokensConsumed"],
+    ["FRONTIER", "frontierTokensConsumed"],
+  ] as const)("upserts the %s tier column (%s)", async (tier, column) => {
+    seedModel({ tier });
+
+    await recordUsageEvent(baseInput());
+
+    expect(upsertArgs().create).toEqual(
+      expect.objectContaining({ [column]: 1_000_000 }),
+    );
+    expect(upsertArgs().update).toEqual(
+      expect.objectContaining({ [column]: { increment: 1_000_000 } }),
+    );
+  });
+
+  // ── AC-2: markup hierarchy ─────────────────────────────────────────────────
+  it("AC-2: markup resolves the model-specific row first", async () => {
+    seedMarkupTable([
+      { provider: PROVIDER, model: MODEL, markupPercent: 5 },
+      { provider: PROVIDER, model: null, markupPercent: 10 },
+      { provider: null, model: null, markupPercent: 8 },
+    ]);
+
+    const result = (await recordUsageEvent(baseInput())) as Extract<
+      RecordUsageResult,
+      { ok: true }
+    >;
+
+    expect(result.billedCostUsd).toBeCloseTo(1.05, 6); // providerCost=1 * (1+5/100)
+  });
+
+  it("AC-2: markup falls back to the provider-wide row", async () => {
+    seedMarkupTable([
+      { provider: PROVIDER, model: null, markupPercent: 10 },
+      { provider: null, model: null, markupPercent: 8 },
+    ]);
+
+    const result = (await recordUsageEvent(baseInput())) as Extract<
+      RecordUsageResult,
+      { ok: true }
+    >;
+
+    expect(result.billedCostUsd).toBeCloseTo(1.1, 6);
+  });
+
+  it("AC-2: markup falls back to the organization-default row", async () => {
+    seedMarkupTable([{ provider: null, model: null, markupPercent: 8 }]);
+
+    const result = (await recordUsageEvent(baseInput())) as Extract<
+      RecordUsageResult,
+      { ok: true }
+    >;
+
+    expect(result.billedCostUsd).toBeCloseTo(1.08, 6);
+  });
+
+  it("AC-2: markup falls back to the 20% system default", async () => {
+    seedMarkupTable([]);
+
+    const result = (await recordUsageEvent(baseInput())) as Extract<
+      RecordUsageResult,
+      { ok: true }
+    >;
+
+    expect(result.billedCostUsd).toBeCloseTo(1.2, 6);
+  });
+
+  // ── Unknown model → safe defaults, no crash ────────────────────────────────
+  it("an unresolvable model defaults to BASE / non-auto / no extended surcharge", async () => {
+    mockOf(db.llmModel.findFirst).mockResolvedValue(null);
+
+    // A large context window would trigger the surcharge IF chargeExtendedAt2x
+    // resolved true — for an unknown model it must default false.
+    const result = (await recordUsageEvent(
+      baseInput({ contextWindowSize: 800_000 }),
+    )) as Extract<RecordUsageResult, { ok: true }>;
+
+    expect(result.billedCostUsd).toBeCloseTo(1.2, 6); // no 2x surcharge
+    expect(createdEventData()).toEqual(
+      expect.objectContaining({ modelTier: "BASE", wasAutoModel: false }),
+    );
+  });
+
+  // ── PII non-leak — the result never carries token content ──────────────────
+  it("PII/content non-leak — the result carries only ids and computed costs", async () => {
+    const result = await recordUsageEvent(baseInput());
+
+    expect(Object.keys(result)).toEqual(
+      expect.arrayContaining(["ok", "eventId", "billedCostUsd"]),
+    );
+    expect(JSON.stringify(result).length).toBeLessThan(200);
+  });
+
+  // ══ H3 — atomicity: the event + the aggregate are ONE transaction ══════════
+  describe("H3 — atomic write (no double-billing on retry)", () => {
+    it("a failed UsagePeriod upsert persists NO UsageEvent — a retry cannot double-bill", async () => {
+      // The P2002 upsert race: two concurrent calls create the same
+      // (organizationId, periodStart) row; the loser throws.
+      installAtomicDb({
+        upsertError: new Error(
+          "Unique constraint failed on the fields: (`organizationId`,`periodStart`)",
+        ),
+      });
+
+      const result = await recordUsageEvent(baseInput());
+
+      expect(result.ok).toBe(false);
+      // THE assertion: a non-transactional implementation commits the event
+      // before the upsert runs, stranding an orphan row here — and the caller's
+      // retry then writes a SECOND event, billing the org twice for one AI call.
+      expect(committedEvents).toHaveLength(0);
+    });
+
+    it("a write failure reports persisted:false — a retry is always safe", async () => {
+      installAtomicDb({ upsertError: new Error("connection reset") });
+
+      const result = await recordUsageEvent(baseInput());
+
+      const err = result as Extract<RecordUsageResult, { ok: false }>;
+      expect(err.error.kind).toBe("write_failed");
+      expect(err.error.persisted).toBe(false);
+    });
+
+    it("both writes go through $transaction — neither is reachable off the base client", async () => {
+      // A transaction that cannot even be opened must produce ZERO writes:
+      // proof that the writes live only inside the transaction callback.
+      mockOf(db.$transaction).mockImplementation(async () => {
+        throw new Error("could not start transaction");
+      });
+
+      const result = await recordUsageEvent(baseInput());
+
+      expect(result.ok).toBe(false);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+      expect(db.usagePeriod.upsert).not.toHaveBeenCalled();
+      expect(committedEvents).toHaveLength(0);
+      expect(db.$transaction).toHaveBeenCalledTimes(1);
+    });
+
+    it("the happy path commits exactly one event, through the transaction", async () => {
+      const result = await recordUsageEvent(baseInput());
+
+      expect(result.ok).toBe(true);
+      expect(db.$transaction).toHaveBeenCalledTimes(1);
+      expect(committedEvents).toHaveLength(1);
+    });
+  });
+
+  // ══ H4 — boundary validation: no negative/NaN/Infinity reaches cost or DB ══
+  describe("H4 — input validation (invalid_input)", () => {
+    it("a NEGATIVE token count is rejected — it cannot decrement the org's spend", async () => {
+      const result = await recordUsageEvent(
+        baseInput({ inputTokensNoCacheWrite: -1_000_000 }),
+      );
+
+      expectInvalidInput(result);
+      // The attack: a negative cost → a negative usageSpendCents increment →
+      // the org's metered spend is DECREMENTED (its bill zeroed out).
+      expect(db.$transaction).not.toHaveBeenCalled();
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+      expect(db.usagePeriod.upsert).not.toHaveBeenCalled();
+      expect(committedEvents).toHaveLength(0);
+    });
+
+    it("NaN is rejected — Postgres double precision accepts it and the aggregate is poisoned forever", async () => {
+      const result = await recordUsageEvent(baseInput({ outputTokens: Number.NaN }));
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+      expect(db.usagePeriod.upsert).not.toHaveBeenCalled();
+    });
+
+    it("Infinity is rejected", async () => {
+      const result = await recordUsageEvent(
+        baseInput({ outputTokens: Number.POSITIVE_INFINITY }),
+      );
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+    });
+
+    it("a non-integer token count is rejected", async () => {
+      const result = await recordUsageEvent(baseInput({ outputTokens: 1.5 }));
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+    });
+
+    it("an absurd token magnitude is rejected (overflow guard)", async () => {
+      const result = await recordUsageEvent(
+        baseInput({ inputTokensNoCacheWrite: 1e15 }),
+      );
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+    });
+
+    it("a negative contextWindowSize is rejected", async () => {
+      const result = await recordUsageEvent(baseInput({ contextWindowSize: -1 }));
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+    });
+
+    it("the error names the offending field", async () => {
+      const result = await recordUsageEvent(baseInput({ outputTokens: -5 }));
+
+      const err = result as Extract<RecordUsageResult, { ok: false }>;
+      expect(err.error.message).toContain("outputTokens");
+    });
+  });
+
+  // ══ H5 — tenant grain: branded ids, validated at the boundary ══════════════
+  describe("H5 — tenant grain", () => {
+    it("rejects a MISMATCHED grain — a workspace id smuggled into the organization slot", async () => {
+      // organizationId keys BOTH the markup lookup and the spend increment, so a
+      // wrong id here bills the wrong tenant (and leaks its markup back).
+      const badTenant = forgedTenant({ organizationId: WORKSPACE_ID });
+
+      const result = await recordUsageEvent(baseInput({ tenant: badTenant }));
+
+      expectInvalidInput(result);
+      expect(db.$transaction).not.toHaveBeenCalled();
+      expect(db.aiMarkupConfig.findFirst).not.toHaveBeenCalled();
+    });
+
+    it("rejects an arbitrary caller-supplied string as an organization id", async () => {
+      const badTenant = forgedTenant({ organizationId: "victim-org" });
+
+      const result = await recordUsageEvent(baseInput({ tenant: badTenant }));
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+    });
+
+    it("rejects a malformed workspace id", async () => {
+      const badTenant = forgedTenant({ workspaceId: "wksp_not-a-uuid" });
+
+      const result = await recordUsageEvent(baseInput({ tenant: badTenant }));
+
+      expectInvalidInput(result);
+      expect(db.usageEvent.create).not.toHaveBeenCalled();
+    });
+
+    it("persists the tenant grain exactly as resolved", async () => {
+      await recordUsageEvent(baseInput());
+
+      expect(createdEventData()).toEqual(
+        expect.objectContaining({
+          organizationId: ORG_ID,
+          workspaceId: WORKSPACE_ID,
+          userId: USER_ID,
+        }),
+      );
+    });
+  });
+
+  // ══ M1 — totalTokens is DERIVED, never caller-supplied ═════════════════════
+  describe("M1 — totalTokens derived server-side", () => {
+    it("derives totalTokens from the buckets — a caller cannot bill without burning quota", async () => {
+      await recordUsageEvent(
+        baseInput({
+          inputTokensCacheWrite: 1_000,
+          inputTokensNoCacheWrite: 10_000,
+          cacheReadTokens: 2_000,
+          outputTokens: 500,
+          thinkingTokens: 100,
+        }),
+      );
+
+      const total = 1_000 + 10_000 + 2_000 + 500 + 100; // 13_600
+      expect(createdEventData()).toEqual(
+        expect.objectContaining({ totalTokens: total }),
+      );
+      // The quota surface: tokensConsumed + the tier column track the derived sum.
+      expect(upsertArgs().create).toEqual(
+        expect.objectContaining({
+          tokensConsumed: total,
+          baseTokensConsumed: total,
+        }),
+      );
+      expect(upsertArgs().update).toEqual(
+        expect.objectContaining({
+          tokensConsumed: { increment: total },
+          baseTokensConsumed: { increment: total },
+        }),
+      );
+    });
+  });
+
+  // ══ M2 — markup + pricing range validation ═════════════════════════════════
+  describe("M2 — markup/pricing range validation", () => {
+    it("a NULL markup column does not become a silent 0% (lost revenue) — falls through to 20%", async () => {
+      seedMarkupTable([{ provider: PROVIDER, model: MODEL, markupPercent: null }]);
+
+      const result = (await recordUsageEvent(baseInput())) as Extract<
+        RecordUsageResult,
+        { ok: true }
+      >;
+
+      // Number(null) === 0 would bill at cost. The system default must win.
+      expect(result.billedCostUsd).toBeCloseTo(1.2, 6);
+      expect(createdEventData()).toEqual(
+        expect.objectContaining({ markupPercent: 20 }),
+      );
+    });
+
+    it("a NEGATIVE markup row never bills below provider cost", async () => {
+      seedMarkupTable([{ provider: PROVIDER, model: MODEL, markupPercent: -50 }]);
+
+      const result = (await recordUsageEvent(baseInput())) as Extract<
+        RecordUsageResult,
+        { ok: true }
+      >;
+
+      expect(result.billedCostUsd).toBeCloseTo(1.2, 6);
+    });
+
+    it("a non-numeric markup row falls through to the default", async () => {
+      seedMarkupTable([
+        { provider: PROVIDER, model: MODEL, markupPercent: "not-a-number" },
+      ]);
+
+      const result = (await recordUsageEvent(baseInput())) as Extract<
+        RecordUsageResult,
+        { ok: true }
+      >;
+
+      expect(result.billedCostUsd).toBeCloseTo(1.2, 6);
+      expect(Number.isFinite(createdEventData().markupPercent as number)).toBe(true);
+    });
+
+    it("an unusable model-specific row falls through the chain to the provider-wide row", async () => {
+      seedMarkupTable([
+        { provider: PROVIDER, model: MODEL, markupPercent: null },
+        { provider: PROVIDER, model: null, markupPercent: 10 },
+      ]);
+
+      const result = (await recordUsageEvent(baseInput())) as Extract<
+        RecordUsageResult,
+        { ok: true }
+      >;
+
+      expect(result.billedCostUsd).toBeCloseTo(1.1, 6);
+    });
+
+    it("a corrupt pricing rate never reaches the cost math (no NaN in the DB)", async () => {
+      seedPricing({ inputPricePerMillion: "corrupt" });
+
+      const result = (await recordUsageEvent(baseInput())) as Extract<
+        RecordUsageResult,
+        { ok: true }
+      >;
+
+      expect(result.billedCostUsd).toBe(0);
+      expect(Number.isFinite(createdEventData().providerCostUsd as number)).toBe(true);
+      expect(Number.isFinite(upsertArgs().create.usageSpendCents as number)).toBe(true);
+    });
+  });
+
+  // ══ M3 — unvalidated tier → an "undefined" column key ══════════════════════
+  describe("M3 — tier validation", () => {
+    it("an out-of-union tier defaults to BASE — never an 'undefined' upsert key", async () => {
+      seedModel({ tier: "LEGENDARY" }); // a tier the catalog should never hold
+
+      const result = await recordUsageEvent(baseInput());
+
+      expect(result.ok).toBe(true);
+      expect(upsertArgs().create).toEqual(
+        expect.objectContaining({ baseTokensConsumed: 1_000_000 }),
+      );
+      expect(upsertArgs().create).not.toHaveProperty("undefined");
+      expect(upsertArgs().update).not.toHaveProperty("undefined");
+      expect(createdEventData()).toEqual(
+        expect.objectContaining({ modelTier: "BASE" }),
+      );
+    });
+  });
+
+  // ══ M4 — missing pricing is MARKED, not silent ═════════════════════════════
+  describe("M4 — missing pricing", () => {
+    it("meters at $0 without blocking, and MARKS the event so it can be re-priced", async () => {
+      mockOf(db.llmModelPricing.findFirst).mockResolvedValue(null);
+
+      const result = await recordUsageEvent(baseInput());
+
+      expect(result).toEqual<RecordUsageResult>({
+        ok: true,
+        eventId: "evt_1",
+        billedCostUsd: 0,
+      });
+      const data = createdEventData();
+      expect(data).toEqual(
+        expect.objectContaining({ providerCostUsd: 0, billedCostUsd: 0 }),
+      );
+      // Distinguishable from a genuine $0 call — and the caller's status survives.
+      expect(data.completionStatus).toBe("pricing_missing:success");
+    });
+
+    it("a priced call carries the caller's status unmarked", async () => {
+      await recordUsageEvent(baseInput({ completionStatus: "error" }));
+
+      expect(createdEventData().completionStatus).toBe("error");
+    });
+  });
+
+  // ══ M5 — raw DB error text is never returned ═══════════════════════════════
+  describe("M5 — error propagation", () => {
+    it("does not leak the raw Prisma message (which embeds ids + token counts)", async () => {
+      // A Prisma validation error embeds the whole `data` argument.
+      const leaky = new Error(
+        `Invalid \`prisma.usageEvent.create()\` invocation: { organizationId: "${ORG_ID}", userId: "${USER_ID}", inputTokensNoCacheWrite: 1000000 }`,
+      );
+      installAtomicDb({ upsertError: leaky });
+
+      const result = await recordUsageEvent(baseInput());
+
+      const err = result as Extract<RecordUsageResult, { ok: false }>;
+      expect(err.error.kind).toBe("write_failed");
+      expect(err.error.message).toBe("usage event write failed");
+      expect(err.error.message).not.toContain(ORG_ID);
+      expect(err.error.message).not.toContain(USER_ID);
+      expect(err.error.message).not.toContain("prisma");
+      // The detail is still available to operators — server-side only.
+      expect(console.error).toHaveBeenCalled();
+    });
+  });
+});