feat(hub): usage fact ledger for run-scoped cost attribution (ADR-0026) (#4)

Co-authored-by: Hong Jiarong <me@jrhim.com>
Co-committed-by: Hong Jiarong <me@jrhim.com>

hub/src/org/usage.ts

@@ -1,8 +1,14 @@
 /**
- * Org / project usage rollups from AgentRun cost facts (ADR-0021).
+ * Org / project usage rollups from the UsageFact ledger (ADR-0021, ADR-0026).
  * Operational usage accounting, not payment collection. Organizations may use
  * either their own provider credentials or a distinct platform-managed
  * connection; commercial billing remains outside the pilot scope.
+ *
+ * The truth is in `UsageFact`; `AgentRun.costUsd / inputTokens / outputTokens`
+ * are a derived rollup cache. This service reads `UsageFact` directly so that
+ * external-capability consumption (PDF→MD, ASR, …) is attributed correctly,
+ * not just the main model loop. A run with no cost-bearing fact is
+ * `runsWithoutCost` — ADR-0022: missing cost ≠ zero.
  */
 import type { Prisma, PrismaClient } from "@prisma/client";
 
@@ -32,6 +38,53 @@ export interface UsageReport {
   };
 }
 
+type FactRow = {
+  readonly inputTokens: number | null;
+  readonly outputTokens: number | null;
+  readonly costUsd: unknown;
+};
+
+type RunWithFacts = {
+  readonly projectId: string;
+  readonly usageFacts: readonly FactRow[];
+};
+
+/** A run is "recorded with cost" if any of its facts carries a known costUsd. */
+function runHasRecordedCost(facts: readonly FactRow[]): boolean {
+  return facts.some((f) => f.costUsd !== null && f.costUsd !== undefined);
+}
+
+/** Decimal→number for Prisma Decimal; null/undefined → null. */
+function factCostUsdToNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+interface RunRollup {
+  readonly hasCost: boolean;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly costUsd: number | null;
+}
+
+function rollupRun(facts: readonly FactRow[]): RunRollup {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let costUsd: number | null = null;
+  let hasCost = false;
+  for (const f of facts) {
+    inputTokens += f.inputTokens ?? 0;
+    outputTokens += f.outputTokens ?? 0;
+    const c = factCostUsdToNumber(f.costUsd);
+    if (c !== null) {
+      hasCost = true;
+      costUsd = (costUsd ?? 0) + c;
+    }
+  }
+  return { hasCost, inputTokens, outputTokens, costUsd };
+}
+
 export async function getOrgUsage(
   prisma: PrismaClient,
   input: {
@@ -54,8 +107,9 @@ export async function getOrgUsage(
     return emptyReport(input.from, input.to);
   }
 
+  const projectIds = projects.map((p) => p.id);
   const runWhere: Prisma.AgentRunWhereInput = {
-    projectId: { in: projects.map((p) => p.id) },
+    projectId: { in: projectIds },
     ...(input.from !== undefined || input.to !== undefined
       ? {
           startedAt: {
@@ -66,20 +120,25 @@ export async function getOrgUsage(
       : {}),
   };
 
+  // Date range filters by run.startedAt, matching the pre-ADR-0026 semantics:
+  // a run is in or out of the window based on when it started, and all of its
+  // facts come along. Filtering facts by occurredAt independently would let a
+  // run contribute partial cost to a window it doesn't belong to.
   const runs = await prisma.agentRun.findMany({
     where: runWhere,
     select: {
       projectId: true,
-      inputTokens: true,
-      outputTokens: true,
-      costUsd: true,
+      usageFacts: {
+        select: { inputTokens: true, outputTokens: true, costUsd: true },
+        orderBy: { occurredAt: "asc" },
+      },
     },
   });
 
   type MutableRow = {
-    projectId: string;
-    projectName: string;
-    folderId: string | null;
+    readonly projectId: string;
+    readonly projectName: string;
+    readonly folderId: string | null;
     runCount: number;
     runsWithCost: number;
     runsWithoutCost: number;
@@ -103,22 +162,33 @@ export async function getOrgUsage(
     });
   }
 
-  for (const run of runs) {
+  for (const run of runs as readonly RunWithFacts[]) {
     const row = byProject.get(run.projectId);
     if (row === undefined) continue;
+    const roll = rollupRun(run.usageFacts);
     row.runCount += 1;
-    row.inputTokens += run.inputTokens ?? 0;
-    row.outputTokens += run.outputTokens ?? 0;
-    if (run.costUsd === null) {
-      row.runsWithoutCost += 1;
-    } else {
+    if (roll.hasCost) {
       row.runsWithCost += 1;
-      const cost = Number(run.costUsd);
-      row.costUsd = (row.costUsd ?? 0) + cost;
+      row.costUsd = (row.costUsd ?? 0) + (roll.costUsd ?? 0);
+    } else {
+      row.runsWithoutCost += 1;
     }
+    row.inputTokens += roll.inputTokens;
+    row.outputTokens += roll.outputTokens;
   }
 
-  const projectsOut: ProjectUsageRow[] = [...byProject.values()];
+  const projectsOut: ProjectUsageRow[] = [...byProject.values()].map((r) => ({
+    projectId: r.projectId,
+    projectName: r.projectName,
+    folderId: r.folderId,
+    runCount: r.runCount,
+    runsWithCost: r.runsWithCost,
+    runsWithoutCost: r.runsWithoutCost,
+    inputTokens: r.inputTokens,
+    outputTokens: r.outputTokens,
+    costUsd: r.costUsd,
+  }));
+
   let runCount = 0;
   let runsWithCost = 0;
   let runsWithoutCost = 0;