@coreplane/switchboard 1.252.0 → 1.253.0

package/dist/assets/src/core/coordinator/contract.ts

@@ -8,9 +8,10 @@
 // parent record the spawn route reads the requester from, and the names the
 // routes decide on.
 //
-import type { Grant, GrantSource } from "../budgets.js";
+import { IDLE_DAYS_MAX, type Grant, type GrantSource } from "../budgets.js";
 import { isVerbosity, type Verbosity } from "../verbosity.js";
 import { isAddressSeverity, type AddressSeverity, type AddressSeveritySource } from "../ship/coordinator.js";
+import { isHandoffShape, type Handoff } from "../ship/handoff.js";
 
 // A coordinator is a Workflow instance in the shim Worker whose children are
 // ordinary `dispatch()` runs as the requesting user. It holds no credential of
@@ -329,6 +330,11 @@ export interface CoordinatorInstance {
    *  the unit threads it owns — the unit-ending report's asides and the
    *  segment lines are `verbose` material. Absent reads as `quiet`. */
   verbosity?: Verbosity;
+  /** The idle flag (record 0051; agent-ship item 8): `ship.idleDays` as the
+   *  ship fork resolved it (user > channel > org), written here beside the
+   *  grant and answered by the plan route — above zero, an idling ending
+   *  becomes `idle`; absent reads as zero, today's endings. */
+  idleDays?: number;
   /** The pipeline's caps as the profile gate clipped them: the rounds cap and the wall clock per unit. */
   caps?: { maxRounds: number; maxMinutes: number };
   /** The status card in the requesting thread, when the channel has one — what
@@ -350,6 +356,24 @@ export interface UnitSegment {
   at: number;
 }
 
+/** The longest `why` an idle carries: an ending kind's name, never prose —
+ *  the route refuses a longer one at the door, the row validator at the store. */
+export const IDLE_WHY_MAX = 64;
+
+/** The idle on a unit's row (record 0051): what a continuation needs, and the
+ *  wakes spent against `IDLE_WAKES_MAX`. */
+export interface UnitIdle {
+  /** The old ending kind the idle stands in for (`wall_clock_cap`, `stopped`, `continued`, …). */
+  why: string;
+  at: number;
+  renewalsLeft: number;
+  from?: string;
+  runId?: string;
+  spendUsd: number | null;
+  handoff?: Handoff;
+  wakes: number;
+}
+
 /** One unit of the plan an instance runs (a task string is a generated plan of
  *  one unit, `U1`): its branch, the units it waits on, and — as the runner
  *  reaches it — its thread, its pull request, the round boundaries the card
@@ -398,6 +422,15 @@ export interface CoordinatorUnit {
    *  renews the same segment twice. `from` is the sha the segment continues
    *  from, `runId` the coding run whose write-up briefs it. */
   segments?: UnitSegment[];
+  /** The unit idles (record 0051; run-history item 50): written by `unit-end`
+   *  on an `idle` ending in place of `ending`, so the unit stays unfinished
+   *  and keeps owning its thread. `why` is the old kind, `renewalsLeft` what
+   *  the grant still holds (the wake spends one — this plan's fifth unit),
+   *  `from` the head a continuation opens from, `runId` the last coding
+   *  child's run (absent when none ran), `spendUsd` the session's dollars
+   *  (null once any run's cost is unknown), `handoff` that child's lists, and
+   *  `wakes` how many wakes this idle has answered — zero at the write. */
+  idle?: UnitIdle;
   /** The round boundaries the coordinator reported, oldest first (the `ship_round`
    *  vocabulary). `gate` rides an approve the machine's severity check caught
    *  carrying a finding at or above the level in force ([agent-ship](../../../docs/reference/specs/agent-ship.md)
@@ -450,6 +483,11 @@ export function isCoordinatorInstance(v: unknown): v is CoordinatorInstance {
   if (r.caps !== undefined && !(isObject(r.caps) && isFinite(r.caps.maxRounds) && isFinite(r.caps.maxMinutes)))
     return false;
   if (r.card !== undefined && !(isObject(r.card) && isText(r.card.channel) && isText(r.card.ts))) return false;
+  if (
+    r.idleDays !== undefined &&
+    !(Number.isInteger(r.idleDays) && (r.idleDays as number) >= 0 && (r.idleDays as number) <= IDLE_DAYS_MAX)
+  )
+    return false;
   if (!isOptionalText(r.runId) || !isOptionalText(r.label)) return false;
   if (r.verbosity !== undefined && !isVerbosity(r.verbosity)) return false;
   if (r.attempt !== undefined && !(Number.isInteger(r.attempt) && (r.attempt as number) >= 2)) return false;
@@ -464,6 +502,17 @@ const isRoundGate = (v: unknown): boolean =>
   Array.isArray(v.findings) &&
   v.findings.every((f) => typeof f === "string");
 
+const isUnitIdle = (v: unknown): boolean =>
+  isObject(v) &&
+  isText(v.why, IDLE_WHY_MAX) &&
+  isFinite(v.at) &&
+  isCount(v.renewalsLeft) &&
+  (v.from === undefined || isText(v.from)) &&
+  (v.runId === undefined || isText(v.runId)) &&
+  (v.spendUsd === null || isFinite(v.spendUsd)) &&
+  (v.handoff === undefined || isHandoffShape(v.handoff)) &&
+  isCount(v.wakes);
+
 const isSegment = (v: unknown): boolean =>
   isObject(v) &&
   typeof v.index === "number" &&
@@ -486,6 +535,7 @@ export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
   if (r.resume !== undefined && !isResume(r.resume)) return false;
   if (r.lastPush !== undefined && !isText(r.lastPush)) return false;
   if (r.segments !== undefined && (!Array.isArray(r.segments) || !r.segments.every(isSegment))) return false;
+  if (r.idle !== undefined && !isUnitIdle(r.idle)) return false;
   if (
     !Array.isArray(r.rounds) ||
     r.rounds.length > MAX_ROUNDS ||

package/dist/assets/src/core/coordinator/driver.ts

@@ -33,7 +33,7 @@
 // plan's re-issue. A task string's ship branch waits for a person. Node-free:
 // the shim Worker imports this by relative path.
 
-import { DEFAULT_GRANT, GRANT_RENEWALS_MAX, type Grant, type GrantSource } from "../budgets.js";
+import { DEFAULT_GRANT, GRANT_RENEWALS_MAX, IDLE_DAYS_MAX, type Grant, type GrantSource } from "../budgets.js";
 import { DEFAULT_VERBOSITY, isVerbosity, type Verbosity } from "../verbosity.js";
 import {
   applyReturn,
@@ -42,6 +42,8 @@ import {
   openPlanCursor,
   openUnitPipeline,
   readyUnits,
+  type PlanCursor,
+  type UnitStatus,
   renderUnitReport,
   settleUnit,
   startUnit,
@@ -163,8 +165,18 @@ export function readBotAnswer(
 }
 
 /** The answers the bot itself calls a passing condition — the step is asked
- *  again, under the policy. Everything else, refusals included, is the machine's. */
-const TRANSIENT = new Set(["github_unavailable", "no_channel", "thread_failed", "unit_not_started", "not_host"]);
+ *  again, under the policy. Everything else, refusals included, is the machine's.
+ *  `queued` is the plane's hold on a spawn (record 0064, "The queue"): a `409`
+ *  saying the child's admission waits on an event — the step re-asks until the
+ *  child is admitted, and the instance is never failed over a full plane. */
+const TRANSIENT = new Set([
+  "github_unavailable",
+  "no_channel",
+  "thread_failed",
+  "unit_not_started",
+  "not_host",
+  "queued",
+]);
 export function transientRefusal(answer: BotAnswer): string | undefined {
   const { ok, error, message } = answer.body;
   if (ok !== false || typeof error !== "string" || !TRANSIENT.has(error)) return undefined;
@@ -191,6 +203,8 @@ interface PlanFacts {
   grantSource: GrantSource;
   /** The request's verbosity as the plan route answers it (routing-and-config item 28): what the unit threads hear. */
   verbosity: Verbosity;
+  /** The idle flag beside the grant (record 0051): above zero, an idling ending becomes `idle`. */
+  idleDays: number;
   /** The instance's mark as the plan route answers it: a generated one-unit plan (a `plan` with no `path`). */
   generated: boolean;
   /** The runs page base the bot answered: the report links a child's write-up to its run page with it. */
@@ -220,6 +234,12 @@ function readGrant(raw: unknown): Grant {
   return { renewals: raw.renewals, ...(typeof cap === "number" && cap > 0 ? { costCapUsd: cap } : {}) };
 }
 
+/** The idle flag as the plan route answers it (record 0051): an integer from 0
+ *  to the module's cap; anything unreadable is 0 — nothing idles on a guess. */
+function readIdleDays(raw: unknown): number {
+  return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 && raw <= IDLE_DAYS_MAX ? raw : 0;
+}
+
 function readPlan(a: BotAnswer): PlanFacts {
   const b = a.body;
   if (b.ok !== true) throw new UnreadableAnswer("plan", a, "not ok");
@@ -240,6 +260,7 @@ function readPlan(a: BotAnswer): PlanFacts {
     grantSource:
       b.grantSource === "run" || b.grantSource === "user" || b.grantSource === "channel" ? b.grantSource : "org",
     verbosity: isVerbosity(b.verbosity) ? b.verbosity : DEFAULT_VERBOSITY,
+    idleDays: readIdleDays(b.idleDays),
     generated: b.generated === true,
     ...(typeof b.runPageBase === "string" && b.runPageBase.length > 0 ? { runPageBase: b.runPageBase } : {}),
     repo: b.repo,
@@ -662,6 +683,7 @@ async function runUnit(
       grant: plan.grant,
       grantSource: plan.grantSource,
       verbosity: plan.verbosity,
+      idleDays: plan.idleDays,
       generated: plan.generated,
       ...(plan.runPageBase !== undefined ? { runPageBase: plan.runPageBase } : {}),
       ...(resume !== undefined ? { resume } : {}),
@@ -734,13 +756,28 @@ async function runUnit(
             kind: note.ending.kind,
             report: renderUnitReport(state, endFacts),
             threadReport: renderUnitReport(state, endFacts, state.input.verbosity ?? DEFAULT_VERBOSITY),
+            // An idle ending carries its continuation facts (record 0051): the
+            // bot writes them on the row's `idle` in place of an ending, with
+            // the coding run id it already receives below.
+            ...(note.ending.kind === "idle"
+              ? {
+                  why: note.ending.why,
+                  renewalsLeft: note.ending.renewalsLeft,
+                  ...(note.ending.from !== undefined ? { from: note.ending.from } : {}),
+                  spendUsd: note.ending.spendUsd,
+                  ...(note.ending.handoff !== undefined ? { handoff: note.ending.handoff } : {}),
+                }
+              : {}),
           },
           ...(state.pr !== undefined ? { pr: state.pr } : {}),
           // A review_pending ending names the child's own last push so the next
-          // attempt's pre-check can start at the review round (the row's lastPush).
+          // attempt's pre-check can start at the review round (the row's lastPush)
+          // — an idled one the same, off the idle's `from` (record 0051).
           ...(note.ending.kind === "review_pending" && note.ending.headSha !== undefined
             ? { headSha: note.ending.headSha }
-            : {}),
+            : note.ending.kind === "idle" && note.ending.why === "review_pending" && note.ending.from !== undefined
+              ? { headSha: note.ending.from }
+              : {}),
           ...(state.lastCodingRunId !== undefined ? { codingRunId: state.lastCodingRunId } : {}),
           // A continued ending is a segment's end, not the unit's: the bot
           // writes the renewal as a row keyed by the next segment's index
@@ -768,12 +805,9 @@ function blockedReport(unit: string, dep: string, depEnding: string): string {
   return `⛔ Blocked: ${unit} waits on ${dep}, which ended ${depEnding}${person ? " — a person's merge" : ""}. Re-issue the plan naming the remaining units once it is ${person ? "merged" : "resolved"}.`;
 }
 
-/** The plan: its units one at a time in dependency order, then the endings of the units it never reached. */
-async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string): Promise<PlanRunSummary> {
-  const plan = readPlan(
-    answerOf("plan", await step.do("plan", STEP_CONFIG, () => call(bot, "plan", { parentInstanceId: instanceId }))),
-  );
-  const graph: PlanGraph = {
+/** The graph as one plan answer carries it: the instance's unit rows, in the plan's order. */
+function graphOf(plan: PlanFacts, instanceId: string): PlanGraph {
+  return {
     planId: plan.planId ?? instanceId,
     units: plan.units.map((u) => ({
       id: u.unit,
@@ -783,6 +817,54 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
       dependsOn: u.dependsOn,
     })),
   };
+}
+
+/** The cursor over a freshly read selection (the orchestration-plane plan's
+ *  re-read requirement): a surviving unit keeps its standing, a row appended
+ *  mid-walk joins pending — walked after the current unit — and a row gone from the selection
+ *  was merged by hand: it is walked as merged with nothing run and nothing
+ *  told (`gone`), a dependency on it counted satisfied like any dependency
+ *  outside the selection. `blocked` is derived state, so it is recomputed over
+ *  the fresh graph rather than carried — a blocked unit whose failing
+ *  dependency left the selection is in play again. */
+function rereadCursor(cursor: PlanCursor, fresh: PlanGraph): { cursor: PlanCursor; gone: string[] } {
+  const gone = cursor.order.filter((id) => !fresh.units.some((u) => u.id === id));
+  const order = fresh.units.map((u) => u.id);
+  const status: Record<string, UnitStatus> = {};
+  for (const id of order) {
+    const prior = cursor.status[id];
+    status[id] = prior === undefined || prior === "blocked" ? "pending" : prior;
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const u of fresh.units) {
+      if (status[u.id] !== "pending") continue;
+      if (u.dependsOn.some((d) => d in status && (status[d] === "failed" || status[d] === "blocked"))) {
+        status[u.id] = "blocked";
+        changed = true;
+      }
+    }
+  }
+  return { cursor: { order, status }, gone };
+}
+
+/** The plan: its units one at a time in dependency order, then the endings of the units it never reached. */
+async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string): Promise<PlanRunSummary> {
+  // The selection is read at every unit boundary (the orchestration-plane plan): the first read opens
+  // the cursor, and each boundary's — its own durable step, `plan/<n>`, so a
+  // replay meets the same read — rebuilds it, so a later bot can append a unit
+  // to a live instance or drop one merged by hand without killing it.
+  let reads = 0;
+  const readSelection = async (): Promise<PlanFacts> => {
+    reads += 1;
+    const name = reads === 1 ? "plan" : `plan/${reads}`;
+    return readPlan(
+      answerOf("plan", await step.do(name, STEP_CONFIG, () => call(bot, "plan", { parentInstanceId: instanceId }))),
+    );
+  };
+  let plan = await readSelection();
+  let graph = graphOf(plan, instanceId);
   let cursor = openPlanCursor(graph);
   const endings: Record<string, string> = {};
   for (;;) {
@@ -809,7 +891,16 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
     endings[next] = ending.kind;
     // A unit is done for its dependents when the base carries its scope: the
     // runner's merge, or a scope that had already landed before the attempt.
+    // An `idle` ending settles the unit `failed` for now: nothing waits yet —
+    // the indexed wait and the wake land with the fifth unit of record 0051's
+    // plan — so the walk is unchanged until then and the flag ships at zero.
     cursor = settleUnit(graph, cursor, next, isSettledDone(ending.kind) ? "done" : "failed");
+    // The unit boundary's re-read (the orchestration-plane plan): the fresh rows are the selection now.
+    plan = await readSelection();
+    graph = graphOf(plan, instanceId);
+    const reread = rereadCursor(cursor, graph);
+    cursor = reread.cursor;
+    for (const id of reread.gone) endings[id] ??= "merged";
   }
   // Blocked units, in the plan's order: each told its own ending, so the rows
   // and the summary say why it never ran. Every blocked unit's ending is known

package/dist/assets/src/core/memory/engine.ts

@@ -59,15 +59,25 @@ export function planEviction(active: MemoryRecord[], cap: number): MemoryRecord[
     .slice(0, excess);
 }
 
-/** What a store must do for one candidate. `dedup`: bump `target.useCount`,
- *  insert nothing. `insert`: append `record` (already minted) and, when
- *  `supersede` is set, flip that record to `superseded`. */
+/** What a store must do for one candidate. `restate`: bump `target.useCount`,
+ *  set its `lastUsedAt` to the store's now and its confidence to `confidence`
+ *  when the plan carries one (the higher of the two sides), insert nothing.
+ *  `dedup`: bump `target.useCount`, insert nothing. `insert`: append `record`
+ *  (already minted) and, when `supersede` is set, flip that record to
+ *  `superseded`. */
 export type WritePlan =
-  { action: "dedup"; target: MemoryRecord } | { action: "insert"; record: MemoryRecord; supersede?: MemoryRecord };
+  | { action: "restate"; target: MemoryRecord; confidence?: number }
+  | { action: "dedup"; target: MemoryRecord }
+  | { action: "insert"; record: MemoryRecord; supersede?: MemoryRecord };
 
 /**
  * Decide how one candidate lands among a scope's ACTIVE records (docs/reference/specs/
  * memory.md §8):
+ * - **Restate target** = the active same-scope record whose id equals
+ *   `cand.restates`: the fact re-teaches a shown record, so that record is
+ *   refreshed — usage bumped, confidence the higher of the two — and nothing
+ *   is inserted, whatever the candidate's wording. A missing or non-active
+ *   target falls through to the rules below (today's dedup-or-insert).
  * - **Supersede target** = the active same-scope record whose id equals
  *   `cand.supersedes`; an unknown/foreign id resolves to nothing (the new
  *   record still lands, superseding nothing).
@@ -86,6 +96,17 @@ export function planWrite(
   cand: MemoryCandidate,
   mint: (cand: MemoryCandidate) => MemoryRecord,
 ): WritePlan {
+  if (cand.restates) {
+    const restated = active.find((r) => r.status === "active" && r.id === cand.restates);
+    if (restated) {
+      const confidences = [restated.confidence, cand.confidence].filter((c): c is number => c !== undefined);
+      return {
+        action: "restate",
+        target: restated,
+        ...(confidences.length > 0 ? { confidence: Math.max(...confidences) } : {}),
+      };
+    }
+  }
   const norm = normalizeText(cand.text);
   const target = cand.supersedes ? active.find((r) => r.status === "active" && r.id === cand.supersedes) : undefined;
   const dedupPool = cand.supersedes ? (target ? [target] : []) : active.filter((r) => r.status === "active");

package/dist/assets/src/core/memory/types.ts

@@ -54,12 +54,16 @@ export interface MemoryCandidate {
   sourceRunId?: string;
   confidence?: number;
   supersedes?: string;
+  /** id of a shown record this fact restates: the store bumps that record
+   *  (`useCount`, `lastUsedAt`, the higher `confidence`) instead of inserting
+   *  a twin; a target that is missing or not active falls through to the
+   *  plain dedup-or-insert path. */
+  restates?: string;
 }
 
 /** What one `write` batch actually did, per candidate action — the seam's
  *  receipt (the counters on the `[memory]` outcome line are these plus the
- *  parse gate's own). `restated` stays 0 until the restate action lands on the
- *  write plan; it is on the shape now so every store answers the same fields. */
+ *  parse gate's own). */
 export interface WriteCounts {
   /** Candidates minted as new active records. */
   inserted: number;

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

@@ -405,7 +405,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
@@ -1003,6 +1007,32 @@ 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;
+      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/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;
+}