@coreplane/switchboard 1.253.0 → 1.254.0

package/dist/assets/src/core/costs.ts

@@ -4,6 +4,8 @@ import {
   type AnthropicTokens,
   type ModelPriceTable,
 } from "./modelPricing.js";
+import { parseModelRef } from "./provider.js";
+import type { RunUsage } from "./runUsage.js";
 import { systemClock } from "./trace/clock.js";
 // Spend report: what a group of deployed pieces ("switchboard" = the bot
 // Worker + its containers, the resident/sandbox/memory Workers) costs per day,
@@ -511,6 +513,9 @@ export interface CostReport {
   /** The snapshot the report was built from (src/core/costsSnapshot.ts): when it was
    *  taken, by whom, how long the read took. Absent on a report built straight from the sources. */
   snapshot?: { takenAt: string; takenBy: string; durationMs: number };
+  /** Each biller's daily invoice tie-out (item 4d); absent when no provider block is known
+   *  (a report built without the wiring) or run history is off. */
+  billers?: BillerTieOut[];
 }
 
 /** What the report carries beyond the priced rows: the account behind the
@@ -729,6 +734,208 @@ export interface LlmCostSource {
   fetchDailyCost(range: DateRange): Promise<LlmCostRow[] | null>;
 }
 
+// ---- invoices per biller (costs.md item 4d) ---------------------------------------------
+
+/** One day of a biller's invoice, as its own billing API reports it. */
+export interface InvoiceDay {
+  date: string;
+  /** The biller's invoiced dollars for the day (an aggregator's fee + BYOK upstream). */
+  usd: number;
+  /** An aggregator's own charge (OpenRouter's `usage`) — what the summed `feeUsd` ties against. */
+  feeUsd?: number;
+  /** An aggregator's BYOK upstream half (`byok_usage_inference`) — what the remainder ties against. */
+  byokUsd?: number;
+}
+
+/** One invoice source per provider block that names an invoice API and an
+ *  `invoiceKeyEnv`: the biller's own billing figures, per UTC day. */
+export interface LlmInvoiceSource {
+  /** The provider block this invoice bills — the `biller` its `model.turn` rows carry. */
+  readonly biller: string;
+  fetchInvoice(range: DateRange): Promise<InvoiceDay[]>;
+}
+
+/** One day of a biller's tie-out: its invoice beside the summed `model.turn` rows. */
+export interface BillerTieOutDay {
+  date: string;
+  /** The biller's invoiced dollars; absent when the block names no source. */
+  invoiceUsd?: number;
+  invoiceFeeUsd?: number;
+  invoiceByokUsd?: number;
+  /** The summed `model.turn` dollars whose ref names this block. */
+  attributedUsd: number;
+  /** The summed BYOK fees — the half an aggregator's `usage` ties against. */
+  attributedFeeUsd?: number;
+  /** `attributedUsd − attributedFeeUsd` — the half `byok_usage_inference` ties against. */
+  attributedUpstreamUsd?: number;
+}
+
+/** One biller's daily tie-out over the range. */
+export interface BillerTieOut {
+  biller: string;
+  /** false = the block names no invoice source: it ties out against nothing and the page says "no invoice". */
+  invoice: boolean;
+  days: BillerTieOutDay[];
+  totals: { invoiceUsd: number; attributedUsd: number };
+}
+
+/** The block a ref bills to, or undefined for a ref that names none (`unknown`). */
+const billerOfRef = (ref: string): string | undefined => (ref.includes("/") ? parseModelRef(ref).provider : undefined);
+
+/**
+ * Pure: each biller's invoice compared with the summed `model.turn` rows whose
+ * ref names that block, per UTC day of the range. An aggregator's invoice
+ * halves (`feeUsd`, `byokUsd`) sit beside the summed fees and the remainder. A
+ * model whose `usd` is null or absent (unpriced, or from before the meter row)
+ * contributes nothing to `attributedUsd` — an understated side is honest, an
+ * invented one is not, so a day the source returned no row for keeps its
+ * invoice side absent (the page renders —): the source holds closed days only,
+ * and a trailing uninvoiced day beside real spend is not a $0 invoice. A day
+ * with neither an invoice row nor a nonzero attributed figure is dropped; a
+ * biller without a source (`invoice: false`) ties out against nothing.
+ */
+export function buildBillerTieOuts(
+  billers: ReadonlyArray<{ name: string; invoice: boolean }>,
+  invoices: Readonly<Record<string, InvoiceDay[]>>,
+  cells: ReadonlyArray<{ day: string; usage: RunUsage }>,
+  range: DateRange,
+): BillerTieOut[] {
+  return billers.map(({ name, invoice }) => {
+    const attributed = new Map<string, { usd: number; fee: number; hasFee: boolean }>();
+    for (const cell of cells) {
+      if (cell.day < range.from || cell.day > range.to) continue;
+      for (const [ref, m] of Object.entries(cell.usage.byModel)) {
+        if (billerOfRef(ref) !== name) continue;
+        const day = attributed.get(cell.day) ?? { usd: 0, fee: 0, hasFee: false };
+        if (typeof m.usd === "number") day.usd += m.usd;
+        if (m.feeUsd !== undefined) {
+          day.fee += m.feeUsd;
+          day.hasFee = true;
+        }
+        attributed.set(cell.day, day);
+      }
+    }
+    const invoiced = new Map<string, InvoiceDay>();
+    if (invoice)
+      for (const d of invoices[name] ?? []) if (d.date >= range.from && d.date <= range.to) invoiced.set(d.date, d);
+    const dates = [...new Set([...attributed.keys(), ...invoiced.keys()])].sort().filter((date) => {
+      const a = attributed.get(date);
+      return invoiced.has(date) || (a !== undefined && (a.usd !== 0 || a.hasFee));
+    });
+    const days: BillerTieOutDay[] = dates.map((date) => {
+      const a = attributed.get(date);
+      const inv = invoiced.get(date);
+      return {
+        date,
+        ...(inv ? { invoiceUsd: inv.usd } : {}),
+        ...(inv?.feeUsd !== undefined ? { invoiceFeeUsd: inv.feeUsd } : {}),
+        ...(inv?.byokUsd !== undefined ? { invoiceByokUsd: inv.byokUsd } : {}),
+        attributedUsd: a?.usd ?? 0,
+        ...(a?.hasFee ? { attributedFeeUsd: a.fee, attributedUpstreamUsd: a.usd - a.fee } : {}),
+      };
+    });
+    return {
+      biller: name,
+      invoice,
+      days,
+      totals: {
+        invoiceUsd: days.reduce((s, d) => s + (d.invoiceUsd ?? 0), 0),
+        attributedUsd: days.reduce((s, d) => s + d.attributedUsd, 0),
+      },
+    };
+  });
+}
+
+/** OpenRouter's activity endpoint (`GET /api/v1/activity`, a management key —
+ *  never the inference key): per-day, per-model rows whose `usage` is the
+ *  aggregator's own charge and `byok_usage_inference` the BYOK upstream cost.
+ *  Summed per day; the key travels only in the Authorization header and never
+ *  appears in errors. The endpoint holds roughly the last 30 days, one short of
+ *  the 31-day snapshot range: the oldest window day may come back with no row,
+ *  and the tie-out then leaves that day's invoice side absent (rendered —),
+ *  never an invented $0. */
+export const OPENROUTER_ACTIVITY_URL = "https://openrouter.ai/api/v1/activity";
+export class OpenRouterActivitySource implements LlmInvoiceSource {
+  readonly biller: string;
+  private readonly key: string;
+  private readonly fetchImpl: typeof fetch;
+  constructor(opts: { biller: string; managementKey: string; fetchImpl?: typeof fetch }) {
+    this.biller = opts.biller;
+    this.key = opts.managementKey;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  async fetchInvoice(range: DateRange): Promise<InvoiceDay[]> {
+    const res = await this.fetchImpl(OPENROUTER_ACTIVITY_URL, {
+      headers: { authorization: `Bearer ${this.key}` },
+    });
+    if (res.status !== 200) throw new Error(`openrouter activity ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    const body = (await res.json()) as {
+      data?: { date?: string; usage?: number; byok_usage_inference?: number }[];
+    };
+    const byDay = new Map<string, { fee: number; byok: number }>();
+    for (const r of body.data ?? []) {
+      const date = str(r.date).slice(0, 10);
+      if (!date || date < range.from || date > range.to) continue;
+      const d = byDay.get(date) ?? { fee: 0, byok: 0 };
+      d.fee += num(r.usage);
+      d.byok += num(r.byok_usage_inference);
+      byDay.set(date, d);
+    }
+    return [...byDay]
+      .sort(([a], [b]) => (a < b ? -1 : 1))
+      .map(([date, d]) => ({ date, usd: d.fee + d.byok, feeUsd: d.fee, byokUsd: d.byok }));
+  }
+}
+
+/** OpenAI's organization costs (`GET /v1/organization/costs`, an admin key):
+ *  daily buckets whose results carry `amount.value` dollars. Paginated like the
+ *  Anthropic report, a non-USD row refused the same way, the key never in errors. */
+export const OPENAI_COSTS_URL = "https://api.openai.com/v1/organization/costs";
+export class OpenAICostsSource implements LlmInvoiceSource {
+  readonly biller: string;
+  private readonly key: string;
+  private readonly fetchImpl: typeof fetch;
+  constructor(opts: { biller: string; adminKey: string; fetchImpl?: typeof fetch }) {
+    this.biller = opts.biller;
+    this.key = opts.adminKey;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  async fetchInvoice(range: DateRange): Promise<InvoiceDay[]> {
+    const byDay = new Map<string, number>();
+    let page: string | null = null;
+    for (let i = 0; ; i++) {
+      if (i >= MAX_COST_PAGES)
+        throw new Error(`openai organization costs: more than ${MAX_COST_PAGES} pages; refusing a truncated total`);
+      const url = new URL(OPENAI_COSTS_URL);
+      url.searchParams.set("start_time", String(Date.parse(`${range.from}T00:00:00Z`) / 1000));
+      url.searchParams.set("end_time", String(Date.parse(`${addDays(range.to, 1)}T00:00:00Z`) / 1000));
+      url.searchParams.set("limit", String(MAX_DAYS));
+      if (page) url.searchParams.set("page", page);
+      const res = await this.fetchImpl(url.toString(), { headers: { authorization: `Bearer ${this.key}` } });
+      if (res.status !== 200)
+        throw new Error(`openai organization costs ${res.status}: ${(await res.text()).slice(0, 300)}`);
+      const body = (await res.json()) as {
+        data?: { start_time?: number; results?: { amount?: { value?: number; currency?: string } }[] }[];
+        has_more?: boolean;
+        next_page?: string | null;
+      };
+      for (const bucket of body.data ?? []) {
+        const date = new Date(num(bucket.start_time) * 1000).toISOString().slice(0, 10);
+        for (const r of bucket.results ?? []) {
+          const currency = str(r.amount?.currency).toLowerCase();
+          if (currency !== "usd") throw new Error(`openai organization costs: unexpected currency ${currency || "?"}`);
+          byDay.set(date, (byDay.get(date) ?? 0) + num(r.amount?.value));
+        }
+      }
+      if (!body.has_more || !body.next_page) break;
+      page = body.next_page;
+    }
+    return [...byDay].sort(([a], [b]) => (a < b ? -1 : 1)).map(([date, usd]) => ({ date, usd }));
+  }
+}
+
 export class NullLlmCostSource implements LlmCostSource {
   fetchDailyCost(_range: DateRange): Promise<LlmCostRow[] | null> {
     return Promise.resolve(null);
@@ -917,14 +1124,26 @@ type UsageReportBody = {
  *  `estimated` — the page can then show today, and a 1-day range means
  *  something. Read live when this was written: fourteen hourly buckets for the
  *  open day, none at `1d`; the cost report's last bucket was the day before. */
-export class AnthropicCostReportSource implements LlmCostSource {
+export class AnthropicCostReportSource implements LlmCostSource, LlmInvoiceSource {
+  /** The provider block this cost report bills; `anthropic` unless a block renames it. */
+  readonly biller: string;
   private readonly adminKey: string;
   private readonly fetchImpl: typeof fetch;
-  constructor(opts: { adminKey: string; fetchImpl?: typeof fetch }) {
+  constructor(opts: { adminKey: string; biller?: string; fetchImpl?: typeof fetch }) {
+    this.biller = opts.biller ?? "anthropic";
     this.adminKey = opts.adminKey;
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
 
+  /** The biller's invoice per day: the cost report's closed days summed across
+   *  workspaces — the invoice, never the estimate (costs.md item 4d). */
+  async fetchInvoice(range: DateRange): Promise<InvoiceDay[]> {
+    const report = await this.fetchCostReport(range);
+    const byDay = new Map<string, number>();
+    for (const r of report.rows) byDay.set(r.date, (byDay.get(r.date) ?? 0) + r.amountUsd);
+    return [...byDay].sort(([a], [b]) => (a < b ? -1 : 1)).map(([date, usd]) => ({ date, usd }));
+  }
+
   async fetchDailyCost(range: DateRange): Promise<LlmCostRow[]> {
     const report = await this.fetchCostReport(range);
     // A bucket with no results is still a closed day: track buckets, not rows.

package/dist/assets/src/core/costsSnapshotStore.ts

@@ -1,4 +1,4 @@
-import type { CloudflareUsage, DateRange, LlmCostRow } from "./costs.js";
+import type { CloudflareUsage, DateRange, InvoiceDay, LlmCostRow } from "./costs.js";
 import { isRunUsageReport, type RunUsageReport } from "./runUsage.js";
 import {
   DEFAULT_STATE_WORKER_TOKEN_ENV,
@@ -46,6 +46,9 @@ export interface CostsSnapshot {
   usage: CloudflareUsage;
   /** Anthropic's daily cost rows (the open days estimated); null when no LLM source is configured. */
   llm: LlmCostRow[] | null;
+  /** Each configured biller's invoice days (costs.md item 4d); a biller whose source failed
+   *  is omitted (warned by name), and the field is absent on a snapshot from before it. */
+  invoices?: Record<string, InvoiceDay[]>;
   /** The run history's per-user usage over the window; null with run history off. */
   runUsage: RunUsageReport | null;
 }
@@ -102,6 +105,20 @@ function isLlmRows(v: unknown): v is LlmCostRow[] {
   );
 }
 
+function isInvoiceDays(v: unknown): v is InvoiceDay[] {
+  return (
+    Array.isArray(v) &&
+    v.every((row) => {
+      if (typeof row !== "object" || row === null) return false;
+      const r = row as Record<string, unknown>;
+      if (typeof r.date !== "string" || !ISO_DAY.test(r.date) || !isFiniteNumber(r.usd)) return false;
+      return (
+        (r.feeUsd === undefined || isFiniteNumber(r.feeUsd)) && (r.byokUsd === undefined || isFiniteNumber(r.byokUsd))
+      );
+    })
+  );
+}
+
 /** The fields the arithmetic reads, present and of the right kind; the rows are the sources'. */
 export function isCostsSnapshot(v: unknown): v is CostsSnapshot {
   if (typeof v !== "object" || v === null) return false;
@@ -113,6 +130,10 @@ export function isCostsSnapshot(v: unknown): v is CostsSnapshot {
   if (typeof usage !== "object" || usage === null) return false;
   if (!USAGE_DATASETS.every((name) => isDatedRows(usage[name]))) return false;
   if (s.llm !== null && !isLlmRows(s.llm)) return false;
+  if (s.invoices !== undefined) {
+    if (typeof s.invoices !== "object" || s.invoices === null || Array.isArray(s.invoices)) return false;
+    if (!Object.values(s.invoices).every(isInvoiceDays)) return false;
+  }
   return s.runUsage === null || isRunUsageReport(s.runUsage);
 }
 

package/dist/assets/src/core/pipelineStanding.ts

@@ -0,0 +1,294 @@
+import type { RunEvent, ShipRoundOutcome } from "./runEvents.js";
+import type { UnitEnding } from "./ship/coordinator.js";
+
+// The standing fold (record 0065): one pure, node-free reader of a hosted ship
+// parent's `ship_round` and `ship_unit` events, yielding the pipeline's
+// standing — per unit a stage from a closed vocabulary, its latest round, its
+// pull request and the stamp that set the stage. The registry
+// (`appendToBacklog`), the ledger view (`runsService.ts`) and the record
+// assembly (`dispatch/record.ts`) all call it, so the three row sources can
+// never disagree. Total over any event list; it never throws.
+
+/** The stage vocabulary (record 0065): what every surface says a unit is in. */
+export type Stage = "coding" | "review" | "fix" | "approved" | "merge-ready" | "merged" | "idle" | "ended";
+
+export const STAGES = [
+  "coding",
+  "review",
+  "fix",
+  "approved",
+  "merge-ready",
+  "merged",
+  "idle",
+  "ended",
+] as const satisfies readonly Stage[];
+
+/** The stages a unit is still open in: what `PipelineSummary.current` lists. */
+const OPEN_STAGES: ReadonlySet<Stage> = new Set(["coding", "review", "fix", "approved", "idle"]);
+
+/** One unit's standing: the stage, the latest round index bound to it, the
+ *  segment count (raised by a `continued` round and by a reopen from idle),
+ *  when the stage was set, and the latest pull request and thread seen. A
+ *  closed unit's `detail` names the ending kind the vocabulary folds to
+ *  `ended`. */
+export interface PipelineUnit {
+  unit: string;
+  stage: Stage;
+  round: number;
+  segment: number;
+  since: number;
+  pr?: number;
+  threadKey?: string;
+  detail?: string;
+}
+
+/** A round of an unnamed unit: a `ship_round` with no companion `ship_unit`
+ *  at its stamp — the shape of records written before `ship_unit` existed. */
+export interface RoundRow {
+  index: number;
+  agent: string;
+  outcome: string;
+  at: number;
+}
+
+/** One stage change the fold made — the pipeline page's log row. */
+export interface StandingChange {
+  at: number;
+  unit: string;
+  stage: Stage;
+  round?: number;
+  detail?: string;
+}
+
+/** What `pipelineStandingOf` returns: the units in order of first appearance,
+ *  the rounds no unit names, and the changes in event order. The plan's unit
+ *  total is not on the parent's stream and is not returned. */
+export interface PipelineStanding {
+  units: PipelineUnit[];
+  unnamedRounds: RoundRow[];
+  changes: StandingChange[];
+}
+
+/** The standing as the row sources carry it (`RunSummary.pipeline`,
+ *  `RunView.pipeline`, `RunRecord.pipeline`): the open units whole, a count
+ *  per stage, the units seen — and, for an older record whose rounds name no
+ *  unit, the newest unnamed round, so its row can still say
+ *  `round 2 · review` (record 0065, the pipeline row). */
+export interface PipelineSummary {
+  current: PipelineUnit[];
+  counts: Record<Stage, number>;
+  total: number;
+  lastRound?: RoundRow;
+}
+
+/** What a bound round does to its unit's stage, by outcome (record 0065's
+ *  mapping). `start` reads the agent and the index (`coding` at round 0, `fix`
+ *  at any higher index, `review` for the review agent); `continue` is `coding`
+ *  with the segment count raised; `hold` leaves the stage alone — the ending
+ *  will say. Pinned to the union: a new outcome fails the build here. */
+export const ROUND_STAGE = {
+  started: "start",
+  pr_opened: "review",
+  completed: "merged",
+  approve: "approved",
+  request_changes: "fix",
+  no_verdict: "hold",
+  checks_failed: "fix",
+  aborted: "hold",
+  stopped: "hold",
+  continued: "continue",
+  idle: "idle",
+} as const satisfies Record<ShipRoundOutcome, Stage | "start" | "continue" | "hold">;
+
+/** What an unbound `ship_unit` ending word does to its unit (record 0065):
+ *  `merged` and `already_landed` fold to `merged`, `merge_ready` to
+ *  `merge-ready`, `idle` stays open as `idle`, `continued` is not an ending
+ *  and holds the stage, and every other kind closes the unit as `ended` with
+ *  the kind as detail. `blocked` — a unit status the driver posts to
+ *  `unit-end` for a unit that never started — ends the same way. Pinned to
+ *  the union: a new ending kind fails the build here. */
+export const ENDING_STAGE = {
+  merged: "merged",
+  already_landed: "merged",
+  merge_ready: "merge-ready",
+  merge_refused: "ended",
+  round_cap: "ended",
+  wall_clock_cap: "ended",
+  review_pending: "ended",
+  stopped: "ended",
+  aborted: "ended",
+  continued: "hold",
+  no_verdict: "ended",
+  interrupted: "ended",
+  refused: "ended",
+  idle: "idle",
+  blocked: "ended",
+} as const satisfies Record<UnitEnding["kind"] | "blocked", Stage | "hold">;
+
+type ShipEvent = Extract<RunEvent, { type: "ship_round" } | { type: "ship_unit" }>;
+
+function isShipEvent(e: RunEvent): e is ShipEvent {
+  return e.type === "ship_round" || e.type === "ship_unit";
+}
+
+/** Fold a run's events into the pipeline's standing. One pass, `seq` order
+ *  assumed (every carrier's events are). A `ship_round` binds to the
+ *  `ship_unit` published next at the same stamp — the round route's own batch
+ *  contract — and that companion contributes only its pull request and thread
+ *  key, never a stage; a round with no companion is a round of an unnamed
+ *  unit. Total: an unknown word holds the stage, and the fold never throws. */
+export function pipelineStandingOf(events: readonly RunEvent[]): PipelineStanding {
+  const ship = events.filter(isShipEvent);
+  const units = new Map<string, PipelineUnit>();
+  const unnamedRounds: RoundRow[] = [];
+  const changes: StandingChange[] = [];
+
+  const setStage = (u: PipelineUnit, stage: Stage, at: number, detail?: string): void => {
+    if (u.stage === stage && u.detail === detail) return;
+    u.stage = stage;
+    u.since = at;
+    if (detail !== undefined) u.detail = detail;
+    else delete u.detail;
+    changes.push({ at, unit: u.unit, stage, round: u.round, ...(detail !== undefined ? { detail } : {}) });
+  };
+
+  /** The unit's row, created at first sight: at `coding` for a plain entry, or
+   *  already at a bound round's stage for a unit adopted mid-pipeline (a
+   *  resume at review skips round 0 — its first bound round says so). */
+  const enter = (name: string, at: number, stage: Stage, round: number, detail?: string): PipelineUnit => {
+    const existing = units.get(name);
+    if (existing) return existing;
+    const u: PipelineUnit = { unit: name, stage, round, segment: 1, since: at };
+    if (detail !== undefined) u.detail = detail;
+    units.set(name, u);
+    changes.push({ at, unit: name, stage, round, ...(detail !== undefined ? { detail } : {}) });
+    return u;
+  };
+
+  const takeFacts = (u: PipelineUnit, e: Extract<ShipEvent, { type: "ship_unit" }>): void => {
+    if (e.pr !== undefined) u.pr = e.pr;
+    if (e.threadKey !== undefined) u.threadKey = e.threadKey;
+  };
+
+  const consumed = new Set<number>();
+  for (let i = 0; i < ship.length; i++) {
+    if (consumed.has(i)) continue;
+    const e = ship[i]!;
+    const at = e.at ?? 0;
+    if (e.type === "ship_round") {
+      const next = ship[i + 1];
+      const companion = next !== undefined && next.type === "ship_unit" && (next.at ?? 0) === at ? next : undefined;
+      if (companion === undefined) {
+        unnamedRounds.push({ index: e.index, agent: e.agent, outcome: e.outcome, at });
+        continue;
+      }
+      consumed.add(i + 1);
+      const mapped = (ROUND_STAGE as Record<string, Stage | "start" | "continue" | "hold">)[e.outcome] ?? "hold";
+      const stage: Stage =
+        mapped === "start"
+          ? e.agent === "review"
+            ? "review"
+            : e.index >= 1
+              ? "fix"
+              : "coding"
+          : mapped === "continue"
+            ? "coding"
+            : mapped === "hold"
+              ? "coding" // a new unit's first word the mapping holds on: it is in play, and coding is the entry stage
+              : mapped;
+      const known = units.has(companion.unit);
+      const u = enter(companion.unit, at, stage, e.index);
+      takeFacts(u, companion); // the companion's pull request and thread only — never its state (record 0065)
+      u.round = e.index;
+      if (mapped === "continue" && known) u.segment += 1;
+      if (mapped !== "hold") setStage(u, stage, at);
+    } else {
+      const state = e.state;
+      if (state === "started") {
+        const existing = units.get(e.unit);
+        if (existing === undefined) {
+          const u = enter(e.unit, at, "coding", 0);
+          takeFacts(u, e);
+        } else {
+          // An idle or closed unit reopens at its next `started` — the next
+          // segment; a started while the unit is open holds where it stands.
+          if (existing.stage === "idle" || existing.stage === "ended") {
+            existing.segment += 1;
+            setStage(existing, "coding", at);
+          }
+          takeFacts(existing, e);
+        }
+        continue;
+      }
+      const mapped = (ENDING_STAGE as Record<string, Stage | "hold">)[state];
+      const u =
+        units.get(e.unit) ??
+        // An ending for a unit that never started (`blocked` with no prior,
+        // or a route that skipped `unit-start`): the row still enters.
+        enter(e.unit, at, mapped !== undefined && mapped !== "hold" ? mapped : "coding", 0, endedDetail(state, mapped));
+      takeFacts(u, e);
+      // A round-outcome word on an unbound `ship_unit` (a route that skipped
+      // its round) and any word the fold does not know hold the stage.
+      if (mapped !== undefined && mapped !== "hold") setStage(u, mapped, at, endedDetail(state, mapped));
+    }
+  }
+  return { units: [...units.values()], unnamedRounds, changes };
+}
+
+function endedDetail(state: string, mapped: Stage | "hold" | undefined): string | undefined {
+  return mapped === "ended" ? state : undefined;
+}
+
+/** The standing as the three row sources carry it: the open units whole, the
+ *  counts per stage (zero-filled — the shape is stable), the units seen, and
+ *  an older record's newest unnamed round. */
+export function summaryOfStanding(standing: PipelineStanding): PipelineSummary {
+  const counts = Object.fromEntries(STAGES.map((s) => [s, 0])) as Record<Stage, number>;
+  for (const u of standing.units) counts[u.stage]++;
+  const lastRound = standing.unnamedRounds.at(-1);
+  return {
+    current: standing.units.filter((u) => OPEN_STAGES.has(u.stage)),
+    counts,
+    total: standing.units.length,
+    ...(lastRound !== undefined ? { lastRound } : {}),
+  };
+}
+
+/** The one carrier helper: the fold's summary for a run's events, or nothing
+ *  for a run with no ship facts — so a model run's row never grows the field. */
+export function pipelineOfEvents(events: readonly RunEvent[]): PipelineSummary | undefined {
+  const standing = pipelineStandingOf(events);
+  if (standing.units.length === 0 && standing.unnamedRounds.length === 0) return undefined;
+  return summaryOfStanding(standing);
+}
+
+const isFinite_ = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+
+function isPipelineUnitShape(v: unknown): v is PipelineUnit {
+  if (typeof v !== "object" || v === null) return false;
+  const u = v as Record<string, unknown>;
+  if (typeof u.unit !== "string" || !STAGES.includes(u.stage as Stage)) return false;
+  if (!isFinite_(u.round) || !isFinite_(u.segment) || !isFinite_(u.since)) return false;
+  if (u.pr !== undefined && !isFinite_(u.pr)) return false;
+  if (u.threadKey !== undefined && typeof u.threadKey !== "string") return false;
+  if (u.detail !== undefined && typeof u.detail !== "string") return false;
+  return true;
+}
+
+/** Structural check on a stored summary (`RunRecord.pipeline`): the shape
+ *  above, nothing else — an older reader accepts a newer record's field. */
+export function isPipelineSummaryShape(v: unknown): v is PipelineSummary {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  if (!Array.isArray(s.current) || !s.current.every(isPipelineUnitShape)) return false;
+  if (typeof s.counts !== "object" || s.counts === null) return false;
+  if (!Object.values(s.counts).every(isFinite_)) return false;
+  if (!isFinite_(s.total)) return false;
+  if (s.lastRound !== undefined) {
+    if (typeof s.lastRound !== "object" || s.lastRound === null) return false;
+    const r = s.lastRound as Record<string, unknown>;
+    if (!isFinite_(r.index) || typeof r.agent !== "string" || typeof r.outcome !== "string" || !isFinite_(r.at))
+      return false;
+  }
+  return true;
+}