@coreplane/switchboard 1.252.0 → 1.254.0

package/dist/assets/src/core/plane/decide.ts

@@ -0,0 +1,203 @@
+// The plane's decider (docs/reference/specs/orchestration-plane.md, the
+// decider items; record 0064, "Where it lives"): one pure function over a
+// closed event union and a closed effect union. The ledger object reads its
+// state, calls `decide` and commits the writes and the effects inside ONE
+// `transactionSync`, so a decision and its consequences land together or not
+// at all. Node-free by design, like `table.ts`: no clock, no io, no ids it
+// did not derive from its inputs — the same event over the same state is the
+// same answer, which is what the shadow comparison and the tests rest on.
+
+/** The three stages an ask is judged at (record 0064): the bot's admission
+ *  door, the plan runner's seed door, the resident's seat. this unit decides the
+ *  admission stage alone; the others' conditions arrive with their units. */
+export type PlaneStage = "admission" | "runner" | "resident";
+
+/** A queue condition: what must become true before the row may run. Each is
+ *  flipped by an event the plane already sees, never polled. The union grows
+ *  one member per stage as the later units land. */
+export type PlaneCondition = { kind: "thread_free"; threadKey: string; met: boolean };
+
+/** One queued ask: the `plane_queue` row. `position` counts the waiting rows
+ *  ahead of it on the same conditions when it queued — the number a person is
+ *  told, never recomputed for them. */
+export interface PlaneQueueRow {
+  runId: string;
+  requester: string;
+  threadKey: string;
+  stage: PlaneStage;
+  /** The stored request, replayed verbatim when the row is admitted (the transport unit). */
+  request: Record<string, unknown>;
+  conditions: PlaneCondition[];
+  position: number;
+  queuedAt: number;
+  state: "waiting" | "admitted" | "withdrawn";
+}
+
+/** What the decider knows: the queue and the threads with a live run. The
+ *  object builds it from its own tables inside the same transaction that
+ *  commits the answer. */
+export interface PlaneState {
+  queue: PlaneQueueRow[];
+  liveThreads: string[];
+}
+
+export function emptyPlaneState(): PlaneState {
+  return { queue: [], liveThreads: [] };
+}
+
+/** The closed event union. `ask`: may this run start now; `sealed`: a thread's
+ *  live run ended (the ledger's seal, the event that flips `thread_free`);
+ *  `withdraw`: the requester gave the wait up (`runs stop` on a queued id, the transport unit). */
+export interface PlaneAskEvent {
+  kind: "ask";
+  at: number;
+  runId: string;
+  requester: string;
+  threadKey: string;
+  stage: PlaneStage;
+  request: Record<string, unknown>;
+}
+export type PlaneEvent =
+  PlaneAskEvent | { kind: "sealed"; at: number; threadKey: string } | { kind: "withdraw"; at: number; runId: string };
+
+/** The closed effect union: what the bot is asked to do, offered on its
+ *  heartbeat and reclaim answers and acknowledged by id (`/plane/ack`). The
+ *  id is derived from the run, so a duplicate offer after a roll is the same
+ *  effect, acknowledged once. The transport unit adds execution; this one only shapes and stores. */
+export type PlaneEffect = {
+  id: string;
+  kind: "admit";
+  runId: string;
+  threadKey: string;
+  request: Record<string, unknown>;
+};
+
+/** What the object must persist beside the returned state — the decider names
+ *  the rows, the object owns the SQL, both inside one `transactionSync`. */
+export type PlaneWrite =
+  | { table: "plane_queue"; op: "put"; row: PlaneQueueRow }
+  | { table: "plane_queue"; op: "state"; runId: string; state: PlaneQueueRow["state"] }
+  | { table: "plane_effects"; op: "offer"; effect: PlaneEffect; at: number };
+
+/** The bot's own outcome for one dispatch, posted to `POST /plane/outcome`
+ *  under `plane.admission: shadow` (orchestration-plane item 8): `proceeded`, `refused:<code>` or
+ *  `fell_cold:<token>` — the ledger object logs the decider's word beside it.
+ *  `runId` is absent when the dispatch never minted one (a refusal). */
+export interface PlaneOutcomePost {
+  runId?: string;
+  requester: string;
+  threadKey: string;
+  stage: PlaneStage;
+  outcome: string;
+}
+
+/** How the bot answers an offered effect (orchestration-plane item 7): `done` and `skipped` close it,
+ *  `deferred` leaves it on the next heartbeat or reclaim answer. */
+export type PlaneAckOutcome = "done" | "skipped" | "deferred";
+
+export interface PlaneDecision {
+  state: PlaneState;
+  effects: PlaneEffect[];
+  writes: PlaneWrite[];
+}
+
+/** One event in, the next state out, with the writes and effects that carry
+ *  it — and nothing else: no transition, no writes (the state comes back as
+ *  given). Never throws: an event about a run or thread the state does not
+ *  know is a no-op, because the object replays outcomes from a bot whose view
+ *  can be older than the tables. */
+export function decide(state: PlaneState, event: PlaneEvent): PlaneDecision {
+  switch (event.kind) {
+    case "ask":
+      return onAsk(state, event);
+    case "sealed":
+      return onSealed(state, event);
+    case "withdraw":
+      return onWithdraw(state, event);
+  }
+}
+
+/** The shadow word for an ask the decider just judged (orchestration-plane item 8): `queued` when the
+ *  decision holds a waiting row for the run, `proceed` when it holds none —
+ *  what the object logs beside the bot's own outcome. */
+export function planeAskWordOf(decision: PlaneDecision, runId: string): "proceed" | "queued" {
+  const row = decision.state.queue.find((r) => r.runId === runId);
+  return row && row.state === "waiting" ? "queued" : "proceed";
+}
+
+function onAsk(state: PlaneState, event: PlaneAskEvent): PlaneDecision {
+  const threadLive = state.liveThreads.includes(event.threadKey);
+  if (!threadLive) return { state, effects: [], writes: [] };
+  const waitingAhead = state.queue.filter((r) => r.state === "waiting" && r.threadKey === event.threadKey).length;
+  const row: PlaneQueueRow = {
+    runId: event.runId,
+    requester: event.requester,
+    threadKey: event.threadKey,
+    stage: event.stage,
+    request: event.request,
+    conditions: [{ kind: "thread_free", threadKey: event.threadKey, met: false }],
+    position: waitingAhead + 1,
+    queuedAt: event.at,
+    state: "waiting",
+  };
+  return {
+    state: { ...state, queue: [...state.queue, row] },
+    effects: [],
+    writes: [{ table: "plane_queue", op: "put", row }],
+  };
+}
+
+function onSealed(state: PlaneState, event: { kind: "sealed"; at: number; threadKey: string }): PlaneDecision {
+  const liveThreads = state.liveThreads.filter((t) => t !== event.threadKey);
+  if (liveThreads.length === state.liveThreads.length && !hasWaiting(state, event.threadKey))
+    return { state, effects: [], writes: [] };
+  return walk({ ...state, liveThreads }, event.at);
+}
+
+function onWithdraw(state: PlaneState, event: { kind: "withdraw"; at: number; runId: string }): PlaneDecision {
+  const row = state.queue.find((r) => r.runId === event.runId && r.state === "waiting");
+  if (!row) return { state, effects: [], writes: [] };
+  const queue = state.queue.map((r) => (r === row ? { ...r, state: "withdrawn" as const } : r));
+  return {
+    state: { ...state, queue },
+    effects: [],
+    writes: [{ table: "plane_queue", op: "state", runId: event.runId, state: "withdrawn" }],
+  };
+}
+
+function hasWaiting(state: PlaneState, threadKey: string): boolean {
+  return state.queue.some((r) => r.state === "waiting" && r.threadKey === threadKey);
+}
+
+/** The queue walk (record 0064): oldest first, and the state is re-evaluated
+ *  after each admission — an admitted run's thread is live again, so a second
+ *  row on the same thread keeps waiting for the next seal. */
+function walk(state: PlaneState, at: number): PlaneDecision {
+  let next = state;
+  const effects: PlaneEffect[] = [];
+  const writes: PlaneWrite[] = [];
+  for (;;) {
+    const row = next.queue.find((r) => r.state === "waiting" && conditionsMet(next, r));
+    if (!row) break;
+    const admitted: PlaneQueueRow = { ...row, state: "admitted" };
+    const effect: PlaneEffect = {
+      id: `admit:${row.runId}`,
+      kind: "admit",
+      runId: row.runId,
+      threadKey: row.threadKey,
+      request: row.request,
+    };
+    next = {
+      queue: next.queue.map((r) => (r === row ? admitted : r)),
+      liveThreads: [...next.liveThreads, row.threadKey],
+    };
+    effects.push(effect);
+    writes.push({ table: "plane_queue", op: "state", runId: row.runId, state: "admitted" });
+    writes.push({ table: "plane_effects", op: "offer", effect, at });
+  }
+  return { state: next, effects, writes };
+}
+
+function conditionsMet(state: PlaneState, row: PlaneQueueRow): boolean {
+  return row.conditions.every((c) => !state.liveThreads.includes(c.threadKey));
+}

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

@@ -155,8 +155,19 @@ export interface ProviderConfig {
   apiKeyEnv?: string;
   /** Base URL for openai-compatible providers (e.g. http://localhost:11434/v1). */
   baseUrl?: string;
+  /** The invoice API the biller's daily tie-out reads (docs/reference/specs/costs.md
+   *  item 4d): Anthropic's cost report, OpenRouter's activity endpoint, or
+   *  OpenAI's organization costs. Requires `invoiceKeyEnv`. */
+  invoiceApi?: InvoiceApi;
+  /** Env var holding that API's key — an admin or management key, never the
+   *  block's inference key (`apiKeyEnv`). Requires `invoiceApi`. */
+  invoiceKeyEnv?: string;
 }
 
+/** The invoice APIs a provider block may name (`invoiceApi`). */
+export const INVOICE_APIS = ["anthropic-cost-report", "openrouter-activity", "openai-costs"] as const;
+export type InvoiceApi = (typeof INVOICE_APIS)[number];
+
 /** The wire a block speaks: its `wire` when declared, else its legacy `type`. */
 export function wireOf(block: Pick<ProviderConfig, "type" | "wire">): Wire {
   return block.wire ?? WIRE_ALIASES[block.type] ?? "openai-chat";

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

@@ -207,6 +207,13 @@ export type RunNoteKind =
    *  the summary names the branch. Published by the post-step, so a unit
    *  that ends without a pull request says why on the record and the card. */
   | "pr_not_opened"
+  /** A coding run's pull request was opened or edited, but its head moved
+   *  before the post-step's head pin and the second identity rewrite answered
+   *  `unreadable` (docs/reference/specs/agent-coding.md item 2, record 0062):
+   *  the open cannot be undone, so the summary names the reason the new tip's
+   *  identities could not be verified and the reply carries the same warning.
+   *  Published by the post-step. */
+  | "pr_head_unverified"
   /** A review run's post-step posted nothing to the pull request — a guard's
    *  refusal, an opt-out, no pull request resolved, GitHub's own error — and
    *  the summary names the pull request (when one was resolved) and the
@@ -275,6 +282,14 @@ export type RunNoteKind =
    *  there was nothing to push), so a re-issue starts from the partial work
    *  (docs/reference/specs/agent-ship.md item 8). */
   | "budget_salvage"
+  /** A pi run's compaction failed for good — the provider refused the summary
+   *  (harness-pi.md item 7) — and the run loop treated it as a checkpoint
+   *  signal: the tracked changes were committed and pushed to the run's own
+   *  branch (a `pushed_head` event, `by: "salvage"`), or the note says plainly
+   *  that the tree held nothing, so a context that overflows before the
+   *  wind-down loses no work. The summary names the compaction failure.
+   *  Published by the run loop's hook, which the pi harness awaits. */
+  | "compaction_salvage"
   /** The loop's end found a tool call in flight and ended it, so the write-up
    *  keeps its allowance (decision 0046, unit seven; harness-pi item 6). The
    *  summary names the tools. Published by the harness beside the budget note. */
@@ -323,6 +338,7 @@ export const RUN_NOTE_KINDS = [
   "work_left_behind",
   "workspace_torn_down",
   "pr_not_opened",
+  "pr_head_unverified",
   "review_not_posted",
   "compacted",
   "harness_error",
@@ -333,6 +349,7 @@ export const RUN_NOTE_KINDS = [
   "tool_unnamed",
   "directory_reached",
   "budget_salvage",
+  "compaction_salvage",
   "stuck_loop",
   "decline_cascade",
 ] as const satisfies readonly RunNoteKind[];
@@ -405,7 +422,11 @@ export type ShipRoundOutcome =
   | "stopped"
   /** The coding round ended at its lease with the unit unfinished and the row
    *  showing progress, and the grant renewed: the next segment opens (decision 0046). */
-  | "continued";
+  | "continued"
+  /** The unit idles instead of ending (record 0051): emitted once the wake
+   *  lands (that plan's fifth unit); in the vocabulary now so rows written
+   *  then read beside today's — the old kinds stay for rows already written. */
+  | "idle";
 
 /**
  * One event in a run's stream. `seq` is stamped by `RunRegistry.publish` — a
@@ -844,6 +865,10 @@ export type RunEvent =
        *  its own branches past the tree (docs/reference/specs/resident-repos.md
        *  item 16). Absent from an event a build before it recorded. */
       head?: string;
+      /** How many of the run's commits the identity rewrite re-authored before
+       *  the open (record 0062; docs/reference/specs/agent-coding.md item 2).
+       *  Absent when none were, and from an event a build before it recorded. */
+      rewritten?: number;
       seq?: number;
       at?: number;
     }
@@ -1003,6 +1028,37 @@ export type RunEvent =
       seq?: number;
       at?: number;
     }
+  /** The operator's decision beside the routed request ([record 0057](../../docs/decisions/0057-the-operator-is-the-one-door-a-model-binds-every-chat-input-and-deterministic-code-authorizes-fences-and-executes.md);
+   *  the one-door plan's operator unit; run-history item 60): one per admitted chat
+   *  event under `routing.operator: shadow` or `on`, published beside the
+   *  `route` event. The decision is binds, a question or a refusal; a bind's
+   *  `line` is redacted and cut like the receipt (`ROUTE_RECEIPT_CAP`), never
+   *  the message text; `intake` carries the intake gate's verdict when the
+   *  gate is present; `latencyMs` and `outputTokens` feed the replay's median
+   *  rows. Under `shadow` nothing runs from it. Additive: unknown → ignored. */
+  | {
+      type: "operator";
+      mode: "shadow" | "on";
+      outcome: "binds" | "question" | "refusal";
+      reason: string;
+      binds?: ReadonlyArray<{ line: string; reason: string }>;
+      question?: string;
+      /** A question's proposed line, redacted and cut like the receipt — what
+       *  the next turn's "yes" binds (`bindFromAnswer`). */
+      proposal?: string;
+      refusalCause?: string;
+      refusalText?: string;
+      /** A refusal the seam itself produced (a non-decision answer, a wrong
+       *  tool, a transport failure) — never the model's decision: under `on`
+       *  the dispatcher falls back to the readers' route for that event, this
+       *  event recorded on the run that then runs. */
+      fallback?: true;
+      intake?: { verdict: string; reason: string };
+      latencyMs?: number;
+      outputTokens?: number;
+      seq?: number;
+      at?: number;
+    }
   /** A refusal the door made ([record 0054](../../docs/decisions/0054-a-refusal-the-person-caused-is-one-question-with-a-best-guess.md),
    *  as amended: every refusal is a run record; run-history.md item 2): the
    *  code, its one cause, and the sentence the person read — redacted and

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

@@ -431,6 +431,7 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       ev.type === "ship_round" ||
       ev.type === "ship_unit" ||
       ev.type === "route" ||
+      ev.type === "operator" ||
       ev.type === "refusal" ||
       ev.type === "reference" ||
       ev.type === "lease" ||

package/dist/assets/src/core/runLedger/transcript.ts

@@ -125,8 +125,24 @@ export interface AssembledCompaction {
 }
 
 export type AssembledTranscript =
-  | { complete: true; turns: number; messages: ChatMessage[]; compactions: AssembledCompaction[] }
-  | { complete: false; turns: number; messages: ChatMessage[]; compactions: AssembledCompaction[]; gap: string };
+  | {
+      complete: true;
+      turns: number;
+      messages: ChatMessage[];
+      compactions: AssembledCompaction[];
+      /** Each message's author (`StoredPart.actor`), aligned with `messages`;
+       *  present only when at least one row carries one — the verifier selects
+       *  the author's own turns by it (record 0057). */
+      actors?: (string | undefined)[];
+    }
+  | {
+      complete: false;
+      turns: number;
+      messages: ChatMessage[];
+      compactions: AssembledCompaction[];
+      actors?: (string | undefined)[];
+      gap: string;
+    };
 
 /** Rows (any order) → the turns, contiguous from `base` (a log index; 0 for a
  *  run's own object), as a conversation counted from 0. `turns` counts every
@@ -150,6 +166,8 @@ export function assembleTranscript(
   }
   const messages: ChatMessage[] = [];
   const compactions: AssembledCompaction[] = [];
+  const actorList: (string | undefined)[] = [];
+  const actorsOrNone = () => (actorList.some((a) => a !== undefined) ? { actors: actorList } : {});
   /** The `messages` index each turn index landed at (a compaction row lands nowhere). */
   const messageIndexOf = new Map<number, number>();
   const gap = (why: string): AssembledTranscript => ({
@@ -157,6 +175,7 @@ export function assembleTranscript(
     turns: messages.length + compactions.length,
     messages,
     compactions,
+    ...actorsOrNone(),
     gap: why,
   });
   const turnCount = byTurn.size === 0 ? 0 : Math.max(...byTurn.keys()) + 1;
@@ -187,11 +206,12 @@ export function assembleTranscript(
     }
     messageIndexOf.set(idx, messages.length);
     messages.push({ role: role ?? "user", content });
+    actorList.push(first && !("compaction" in first) ? first.actor : undefined);
   }
   for (const c of compactions) {
     if (c.entry.keptFrom === undefined) continue;
     const kept = messageIndexOf.get(c.entry.keptFrom - base);
     if (kept !== undefined) c.keptBefore = kept;
   }
-  return { complete: true, turns: messages.length + compactions.length, messages, compactions };
+  return { complete: true, turns: messages.length + compactions.length, messages, compactions, ...actorsOrNone() };
 }

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

@@ -0,0 +1,237 @@
+import { FRICTION_CATEGORIES, type CategoryTotals, type FrictionCategory } from "./runFriction.js";
+import { llmUsdOfUsage, type ModelPriceTable } from "./modelPricing.js";
+import { emptyUsage, UNKNOWN_AGENT } from "./runUsage.js";
+import { utf8ByteLength, type RunRecord } from "./runRecord.js";
+
+// Run metrics (docs/reference/specs/run-metrics.md; docs/decisions/0063-every-finished-run-writes-one-metrics-point-and-a-metrics-page-reads-the-trend.md):
+// one flat point per finished run, written to a Workers Analytics Engine
+// dataset beside the record's commit. This file is the point's contract, shared
+// by both sides of the wire — the bot's store/ledger clients compute the point
+// (`pointOf`), the state Worker validates it (`isRunMetricsPoint`) and decides
+// whether the row turned final (`pointTurnsFinal`) — so it is node-free like
+// `runRecord.ts`: no Node built-ins, no I/O, no clock.
+
+/** A point as the platform's `writeDataPoint` takes it: one index (the
+ *  sampling key), positional string blobs and positional doubles. */
+export interface RunMetricsPoint {
+  indexes: [string];
+  blobs: string[];
+  doubles: number[];
+}
+
+/** The platform's byte cap per blob (and per index); `pointOf` truncates. */
+export const MAX_POINT_BLOB_BYTES = 96;
+
+/** The point's schema word, `blob1` — bump it when a position changes meaning. */
+export const POINT_SCHEMA = "1";
+
+const BLOB_NAMES = [
+  "schema",
+  "agent",
+  "preset",
+  "model",
+  "status",
+  "failure kind",
+  "dominant friction",
+  "channel",
+  "repository",
+  "machine class",
+  "route class",
+  "reply",
+  "lineage",
+  "requester",
+  "identity",
+  "run id",
+] as const;
+
+const DOUBLE_NAMES = [
+  "wall",
+  "getting ready",
+  "thinking",
+  "tools",
+  "finishing up",
+  "overhead",
+  "not recorded",
+  "not loaded",
+  "turns",
+  "input tokens",
+  "output tokens",
+  "cache read tokens",
+  "cache write tokens",
+  "dollars",
+  "steps",
+  "tool calls",
+  "events",
+  "unpriced tokens",
+  "minutes",
+  "finished at",
+] as const;
+
+export type PointBlobName = (typeof BLOB_NAMES)[number];
+export type PointDoubleName = (typeof DOUBLE_NAMES)[number];
+
+/** The ONE ordered table naming every position once: `blobs[i]` is the meaning
+ *  of `blob<i+1>`, `doubles[i]` of `double<i+1>`, `index[0]` of `index1`. The
+ *  writer builds from it (`pointOf` fills a `Record<name, value>` and maps it
+ *  through this order, so a position added here without a value fails to
+ *  compile) and the reader's SQL aliases from it — a query names a column
+ *  through its name here, never a magic number. */
+export const POINT_COLUMNS = {
+  index: ["agent"] as const,
+  blobs: BLOB_NAMES,
+  doubles: DOUBLE_NAMES,
+};
+
+/** The 1-based platform column of a named blob: `"status"` → `"blob5"`. */
+export function blobColumn(name: PointBlobName): string {
+  return `blob${POINT_COLUMNS.blobs.indexOf(name) + 1}`;
+}
+
+/** The 1-based platform column of a named double: `"dollars"` → `"double14"`. */
+export function doubleColumn(name: PointDoubleName): string {
+  return `double${POINT_COLUMNS.doubles.indexOf(name) + 1}`;
+}
+
+/** A point's blob by its `POINT_COLUMNS` name — the tests' and readers' accessor. */
+export function blobOf(point: RunMetricsPoint, name: PointBlobName): string {
+  return point.blobs[POINT_COLUMNS.blobs.indexOf(name)];
+}
+
+/** A point's double by its `POINT_COLUMNS` name. */
+export function doubleOf(point: RunMetricsPoint, name: PointDoubleName): number {
+  return point.doubles[POINT_COLUMNS.doubles.indexOf(name)];
+}
+
+/** Truncate to the platform's per-blob byte cap (multi-byte safe: cut by
+ *  characters until the UTF-8 size fits — blob values are ids and enum words,
+ *  so the loop is theoretical). */
+function capBlob(s: string): string {
+  let out = s;
+  while (utf8ByteLength(out) > MAX_POINT_BLOB_BYTES) out = out.slice(0, -1);
+  return out;
+}
+
+const isFinite_ = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+
+/** The dominant friction category of a stored diagnosis: the `FrictionCategory`
+ *  with the largest `durationMs` among those with a count (first in
+ *  `FRICTION_CATEGORIES` order on a tie); empty when no category has a count. */
+export function dominantFriction(byCategory: Partial<Record<FrictionCategory, CategoryTotals>>): FrictionCategory | "" {
+  let best: FrictionCategory | "" = "";
+  let bestMs = -1;
+  for (const c of FRICTION_CATEGORIES) {
+    const t = byCategory[c];
+    if (!t || t.count <= 0) continue;
+    if (t.durationMs > bestMs) {
+      best = c;
+      bestMs = t.durationMs;
+    }
+  }
+  return best;
+}
+
+/**
+ * The record's metrics point, or `undefined` for a record still in its
+ * provisional window (`provisional: true`) — and for nothing else: a final
+ * record whose `finishedAt` equals its `startedAt` is counted with a zero
+ * wall. Reads ONLY the record's typed dimensions and counters — never
+ * `activity`, `label`, `events`, `verdict`, `handoff`, `dispositions` or
+ * `diagnosis.verdict` — so no free text reaches the dataset. Dollars are
+ * priced at finish through the same table `RunsService` prices reads with
+ * (`llmUsdOfUsage`); an unpriced model's tokens land in `unpriced tokens`,
+ * never in `dollars` as $0.
+ */
+export function pointOf(record: RunRecord, prices?: ModelPriceTable): RunMetricsPoint | undefined {
+  if (record.provisional === true) return undefined;
+  const usage = record.usage ?? emptyUsage();
+  const priced = llmUsdOfUsage(usage, prices);
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  for (const m of Object.values(usage.byModel)) {
+    inputTokens += m.inputTokens;
+    outputTokens += m.outputTokens;
+    cacheReadTokens += m.cacheReadTokens;
+    cacheWriteTokens += m.cacheWriteTokens;
+  }
+  const shape = record.diagnosis.shape;
+  const blobs: Record<PointBlobName, string> = {
+    schema: POINT_SCHEMA,
+    agent: record.agent ?? "",
+    preset: record.profile?.preset ?? "",
+    model: record.model ?? "",
+    status: record.status,
+    "failure kind": record.failure?.kind ?? "",
+    "dominant friction": dominantFriction(record.diagnosis.byCategory),
+    channel: record.channelId,
+    repository: record.repo ?? "",
+    "machine class": record.profile?.machine ?? "",
+    "route class": record.route !== undefined ? "routed" : "chosen",
+    reply: record.replyOk === true ? "ok" : record.replyOk === false ? "failed" : "none",
+    lineage: record.parentRunId !== undefined ? "child" : "root",
+    requester: record.userId,
+    identity: record.profile?.identity ?? "",
+    "run id": record.id,
+  };
+  const doubles: Record<PointDoubleName, number> = {
+    wall: record.finishedAt - (record.receivedAt ?? record.startedAt),
+    "getting ready": shape?.gettingReadyMs ?? 0,
+    thinking: shape?.thinkingMs ?? 0,
+    tools: shape?.toolsMs ?? 0,
+    "finishing up": shape?.finishingUpMs ?? 0,
+    overhead: shape?.overheadMs ?? 0,
+    "not recorded": shape?.notRecordedMs ?? 0,
+    "not loaded": shape?.notLoadedMs ?? 0,
+    turns: usage.turns,
+    "input tokens": inputTokens,
+    "output tokens": outputTokens,
+    "cache read tokens": cacheReadTokens,
+    "cache write tokens": cacheWriteTokens,
+    dollars: priced.usd,
+    steps: record.stepCount ?? 0,
+    "tool calls": isFinite_(record.diagnosis.toolCalls) ? record.diagnosis.toolCalls : 0,
+    events: record.eventCount,
+    "unpriced tokens": priced.unpricedTokens,
+    minutes: record.profile?.minutes ?? 0,
+    "finished at": record.finishedAt,
+  };
+  return {
+    indexes: [capBlob(record.agent ?? UNKNOWN_AGENT)],
+    blobs: POINT_COLUMNS.blobs.map((n) => capBlob(blobs[n])),
+    doubles: POINT_COLUMNS.doubles.map((n) => doubles[n]),
+  };
+}
+
+/** Structural check on a point from outside the process (the `/runs/put` and
+ *  `/runs/finish` bodies): exactly one index, exactly `POINT_COLUMNS.blobs.length`
+ *  strings each at most `MAX_POINT_BLOB_BYTES` bytes, exactly
+ *  `POINT_COLUMNS.doubles.length` finite numbers — and nothing else. */
+export function isRunMetricsPoint(v: unknown): v is RunMetricsPoint {
+  if (typeof v !== "object" || v === null) return false;
+  const p = v as Record<string, unknown>;
+  if (!Array.isArray(p.indexes) || p.indexes.length !== 1) return false;
+  const index = p.indexes[0];
+  if (typeof index !== "string" || utf8ByteLength(index) > MAX_POINT_BLOB_BYTES) return false;
+  if (!Array.isArray(p.blobs) || p.blobs.length !== POINT_COLUMNS.blobs.length) return false;
+  if (!p.blobs.every((b) => typeof b === "string" && utf8ByteLength(b) <= MAX_POINT_BLOB_BYTES)) return false;
+  if (!Array.isArray(p.doubles) || p.doubles.length !== POINT_COLUMNS.doubles.length) return false;
+  return p.doubles.every(isFinite_);
+}
+
+/**
+ * The emission rule's one question, answered inside the store's transaction:
+ * did this write turn the run's row final? True exactly when the stored record
+ * is final (`provisional` absent) and the existing row was absent or itself
+ * provisional. There is deliberately no `finishedAt > startedAt` term: a plain
+ * `put` of an `interrupted` record over no row is a run counted once, and a
+ * final rewrite over a final row (the review artifact, an identical retry) is
+ * false however its stamps compare.
+ */
+export function pointTurnsFinal(
+  existing: { provisional?: boolean } | undefined,
+  stored: Pick<RunRecord, "provisional">,
+): boolean {
+  if (stored.provisional === true) return false;
+  return existing === undefined || existing.provisional === true;
+}