@walwal-harness/cli 7.1.40 → 7.1.42

package/apps/harness-dashboard/lib/brick/adapter.ts

@@ -0,0 +1,423 @@
+/* =============================================================
+   walwal-harness · BRICK OFFICE real-data adapter
+   Maps a real HarnessSnapshot onto the design's Contract shape.
+
+   Honesty over fake values: where the real feed has no granular
+   source (token/min, cost, cpu, per-task %, per-worker %), the
+   field is `null` and the UI renders "—". Nothing is fabricated.
+
+   This module is pure (no React, no DOM).
+   ============================================================= */
+
+import type {
+  HarnessSnapshot,
+  WorkerDocEntry,
+  MissionDoc,
+  CxxTodo,
+  HarnessEvent,
+  ActivitySample,
+  OwnerPromptEntry,
+} from "../types";
+import {
+  AGENT_DEFS,
+  AGENT_ROLES,
+  type AgentRole,
+  type AgentStatus,
+  type ContractState,
+  type ContractAgent,
+  type ContractWorker,
+  type ContractTask,
+  type ContractTasks,
+  type ContractEvent,
+  type ContractAlert,
+  type ContractMetrics,
+} from "./contract";
+
+/* ---- constants mirrored from Scene.tsx bucketing ---------------------- */
+const BUCKET_MS = 10 * 60_000; // 10-minute heat buckets (matches Scene heatmap)
+const SPARK_BUCKETS = 24; // 24 buckets of recent activity -> the bar sparkline
+const HOUR_MS = 60 * 60 * 1000;
+const CADENCE_BUCKETS = 24; // 24 hourly buckets of owner prompts
+const STALE_MS = 120_000; // running but no visible movement > 120s -> stale
+const THROUGHPUT_WINDOW_MS = 60_000; // events in the last 60s
+
+const ROLE_SET = new Set<string>(AGENT_ROLES);
+
+/* ---- helpers ---------------------------------------------------------- */
+
+/** Strip the `harness-` prefix and lowercase, returning a role or null. */
+function toRole(value: string | null | undefined): AgentRole | null {
+  const r = (value ?? "").toLowerCase().replace(/^harness-/, "").trim();
+  return ROLE_SET.has(r) ? (r as AgentRole) : null;
+}
+
+/** Parse an ISO timestamp to epoch ms, or null when unparseable. */
+function parseTs(ts: string | null | undefined): number | null {
+  if (!ts) return null;
+  const t = Date.parse(ts);
+  return Number.isFinite(t) ? t : null;
+}
+
+/** Strip leading YAML frontmatter from a markdown string. */
+export function stripFrontmatter(md: string | null | undefined): string {
+  if (!md) return "";
+  return md.replace(/^---[\s\S]*?---\n+/, "");
+}
+
+/** The active mission (active flag), else the first mission, else null. */
+function pickActiveMission(snapshot: HarnessSnapshot): MissionDoc | null {
+  return snapshot.missions.find((m) => m.active) ?? snapshot.missions[0] ?? null;
+}
+
+/** Read a role's report markdown off a mission doc. */
+function missionReportFor(
+  mission: MissionDoc | null,
+  role: AgentRole
+): string | undefined {
+  if (!mission) return undefined;
+  const raw = mission[role];
+  return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+
+/**
+ * Build a per-role spark array: SPARK_BUCKETS buckets of activitySamples,
+ * newest bucket last (mirrors Scene.tsx heat bucketing — x = nowMinute -
+ * sampleMinute, keep the strongest count seen in each bucket).
+ */
+function buildSpark(samples: ActivitySample[], role: AgentRole, nowMs: number): number[] {
+  const nowBucket = Math.floor(nowMs / BUCKET_MS);
+  const buckets = new Array<number>(SPARK_BUCKETS).fill(0);
+  for (const sample of samples) {
+    // A role owns its own lane (id === role) and all of its worker lanes
+    // (id === `${role}:...`). Both contribute to the role's activity spark.
+    const lane = sample.laneId;
+    if (lane !== role && !lane.startsWith(role + ":")) continue;
+    const t = parseTs(sample.ts);
+    if (t == null) continue;
+    const x = nowBucket - Math.floor(t / BUCKET_MS);
+    if (x < 0 || x >= SPARK_BUCKETS) continue;
+    // index SPARK_BUCKETS-1 = now (newest), index 0 = oldest visible bucket
+    const idx = SPARK_BUCKETS - 1 - x;
+    buckets[idx] = Math.max(buckets[idx], sample.count);
+  }
+  return buckets;
+}
+
+/** Newest activity epoch across a role's lanes + its workers + events. */
+function heartbeatFor(
+  snapshot: HarnessSnapshot,
+  role: AgentRole,
+  workers: WorkerDocEntry[],
+  eventEpochByRole: Map<AgentRole, number>
+): number | null {
+  let hb: number | null = null;
+  const bump = (t: number | null) => {
+    if (t != null && (hb == null || t > hb)) hb = t;
+  };
+  for (const sample of snapshot.activitySamples) {
+    const lane = sample.laneId;
+    if (lane === role || lane.startsWith(role + ":")) bump(parseTs(sample.ts));
+  }
+  for (const w of workers) bump(parseTs(w.updatedAt));
+  bump(eventEpochByRole.get(role) ?? null);
+  return hb;
+}
+
+/** Determine if the company loop is active for status/loop derivation. */
+function loopIsActive(snapshot: HarnessSnapshot): boolean {
+  const rt = snapshot.runtime;
+  const agentStatus = (rt.agentStatus ?? "").toLowerCase();
+  const conductor = (rt.conductorState ?? "").toLowerCase();
+  const agentDone = agentStatus === "completed" || agentStatus === "complete";
+  const conductorDone =
+    conductor === "completed" || conductor === "complete" || conductor === "blocked";
+  return !agentDone && !conductorDone;
+}
+
+/* ---- the adapter ------------------------------------------------------ */
+
+/**
+ * Map a real HarnessSnapshot onto the design Contract shape.
+ *
+ * @param snapshot  the real harness feed snapshot
+ * @param connected whether the SSE stream is currently open
+ * @param nowMs     the shell's ~1/s clock value (epoch ms)
+ */
+export function toContractState(
+  snapshot: HarnessSnapshot,
+  connected: boolean,
+  nowMs: number
+): ContractState {
+  const rt = snapshot.runtime;
+  const currentRole = toRole(rt.currentAgent);
+  const loopActive = loopIsActive(snapshot);
+  const activeMission = pickActiveMission(snapshot);
+
+  // Workers from the active mission(s) — index by role.
+  const activeMissions = snapshot.missions.filter((m) => m.active);
+  const missionsForWorkers = activeMissions.length > 0 ? activeMissions : snapshot.missions;
+  const workerEntries: Array<{ worker: WorkerDocEntry; mission: MissionDoc }> = [];
+  const workersByRole = new Map<AgentRole, WorkerDocEntry[]>();
+  for (const role of AGENT_ROLES) workersByRole.set(role, []);
+  for (const mission of missionsForWorkers) {
+    for (const worker of mission.workers) {
+      const role = toRole(worker.owner);
+      if (!role) continue;
+      workerEntries.push({ worker, mission });
+      workersByRole.get(role)!.push(worker);
+    }
+  }
+
+  // Events newest-first; capture per-role newest epoch for heartbeats.
+  const eventEpochByRole = new Map<AgentRole, number>();
+  const firstLaneRole = (): AgentRole | null => {
+    const s = snapshot.activitySamples[snapshot.activitySamples.length - 1];
+    return s ? toRole(s.laneId.split(":")[0]) : null;
+  };
+  for (const ev of snapshot.events) {
+    const role = toRole(ev.owner);
+    const t = parseTs(ev.ts);
+    if (role && t != null) {
+      const prev = eventEpochByRole.get(role);
+      if (prev == null || t > prev) eventEpochByRole.set(role, t);
+    }
+  }
+
+  // ---- agents --------------------------------------------------------
+  const hasRecentSample = (role: AgentRole): boolean =>
+    snapshot.activitySamples.some(
+      (s) => (s.laneId === role || s.laneId.startsWith(role + ":")) && s.count > 0
+    );
+  const runtimeBlocked =
+    (rt.agentStatus ?? "").toLowerCase() === "blocked" ||
+    (rt.conductorState ?? "").toLowerCase() === "blocked";
+
+  const agents: ContractAgent[] = AGENT_DEFS.map((def) => {
+    const role = def.id;
+    const isCurrent = role === currentRole;
+    const roleWorkers = workersByRole.get(role) ?? [];
+    const openTodos = snapshot.todos.filter(
+      (t) => toRole(t.owner) === role && !isTerminalTodo(t)
+    ).length;
+    const liveWorkers = roleWorkers.filter(
+      (w) => w.active || w.status === "IN_PROGRESS"
+    ).length;
+
+    let status: AgentStatus;
+    if (isCurrent && loopActive) status = "live";
+    else if (hasRecentSample(role)) status = "active";
+    else if (runtimeBlocked && isCurrent) status = "alert";
+    else status = "idle";
+
+    const loop = (isCurrent && loopActive) || openTodos > 0 ? "running" : "idle";
+    const work = isCurrent ? rt.currentAction ?? "—" : "—";
+
+    return {
+      id: role,
+      name: def.name,
+      role: def.role,
+      hue: def.hue,
+      status,
+      loop,
+      work,
+      todos: openTodos,
+      workers: liveWorkers,
+      spark: buildSpark(snapshot.activitySamples, role, nowMs),
+      heartbeat: heartbeatFor(snapshot, role, roleWorkers, eventEpochByRole),
+      report: missionReportFor(activeMission, role),
+    };
+  });
+
+  // ---- workers -------------------------------------------------------
+  const workers: ContractWorker[] = workerEntries.map(({ worker }) => {
+    const role = toRole(worker.owner)!;
+    const status: AgentStatus =
+      worker.status === "IN_PROGRESS" ? "active" : "idle";
+    return {
+      id: `${worker.owner}:${worker.name}`,
+      agent: role,
+      name: worker.displayName,
+      status,
+      started: parseTs(worker.updatedAt),
+      progress: worker.status === "COMPLETE" ? 100 : null,
+      report: stripFrontmatter(worker.content) || undefined,
+    };
+  });
+
+  // ---- tasks ---------------------------------------------------------
+  const tasks = buildTasks(snapshot.todos);
+
+  // ---- events --------------------------------------------------------
+  const events: ContractEvent[] = snapshot.events
+    .slice(-60)
+    .map((ev, i): ContractEvent => {
+      const role = toRole(ev.owner) ?? firstLaneRole() ?? "";
+      return {
+        id: eventId(ev, i),
+        at: parseTs(ev.ts),
+        agent: role,
+        worker: "",
+        verb: ev.type || ev.status || "",
+        obj: ev.title || ev.summary || ev.command || "",
+      };
+    });
+
+  // ---- cadence -------------------------------------------------------
+  const cadence = buildCadence(snapshot.ownerHistory, nowMs);
+
+  // ---- alerts (synthesized) -----------------------------------------
+  const alerts = buildAlerts(snapshot, agents, currentRole, runtimeBlocked, nowMs);
+
+  // ---- metrics -------------------------------------------------------
+  const throughput = snapshot.events.filter((ev) => {
+    const t = parseTs(ev.ts);
+    return t != null && nowMs - t <= THROUGHPUT_WINDOW_MS;
+  }).length;
+
+  const metrics: ContractMetrics = {
+    sse: connected ? "open" : "closed",
+    tokensPerMin: null,
+    costToday: null,
+    throughput,
+    cpu: null,
+    hotfix: snapshot.missions.filter((m) => m.type === "hotfix").length,
+    eventsTotal: snapshot.events.length,
+  };
+
+  return {
+    now: nowMs,
+    agents,
+    workers,
+    tasks,
+    events,
+    cadence,
+    alerts,
+    metrics,
+    mtrend: [],
+    ctrend: [],
+  };
+}
+
+/* ---- task building ---------------------------------------------------- */
+
+function isTerminalTodo(t: CxxTodo): boolean {
+  const s = (t.status ?? "").toLowerCase();
+  return s === "done" || s === "completed";
+}
+
+function buildTasks(todos: CxxTodo[]): ContractTasks {
+  const running: ContractTask[] = [];
+  const queued: ContractTask[] = [];
+  const done: ContractTask[] = [];
+
+  for (const t of todos) {
+    const role = ((t.owner ?? "").toLowerCase().replace(/^harness-/, "")) as AgentRole;
+    const status = (t.status ?? "").toLowerCase();
+    const at = parseTs(t.updatedAt);
+    const base: ContractTask = {
+      id: t.id,
+      owner: (t.owner ?? "").toUpperCase(),
+      title: t.title,
+      agent: role,
+      status: "queued",
+      progress: null,
+      started: at,
+      at,
+    };
+    if (status === "active") {
+      running.push({ ...base, status: "running" });
+    } else if (status === "pending" || status === "paused") {
+      queued.push({ ...base, status: "queued" });
+    } else if (status === "done" || status === "completed") {
+      done.push({ ...base, status: "done" });
+    }
+  }
+
+  // done: newest first, cap ~14
+  done.sort((a, b) => (b.at ?? 0) - (a.at ?? 0));
+  return { running, queued, done: done.slice(0, 14) };
+}
+
+/* ---- cadence building (mirrors Scene.tsx CadenceStrip) ---------------- */
+
+function buildCadence(ownerHistory: OwnerPromptEntry[], nowMs: number): number[] {
+  const buckets = new Array<number>(CADENCE_BUCKETS).fill(0);
+  for (const entry of ownerHistory) {
+    const t = parseTs(entry.ts);
+    if (t == null) continue;
+    const hoursAgo = Math.floor((nowMs - t) / HOUR_MS);
+    if (hoursAgo < 0 || hoursAgo >= CADENCE_BUCKETS) continue;
+    buckets[hoursAgo] += 1;
+  }
+  return buckets;
+}
+
+/* ---- alert synthesis -------------------------------------------------- */
+
+function buildAlerts(
+  snapshot: HarnessSnapshot,
+  agents: ContractAgent[],
+  currentRole: AgentRole | null,
+  runtimeBlocked: boolean,
+  nowMs: number
+): ContractAlert[] {
+  const alerts: ContractAlert[] = [];
+  const rt = snapshot.runtime;
+  let seq = 0;
+  const nextId = (k: string) => `alert-${k}-${seq++}`;
+
+  // runtime blocked OR ownerPrompt awaiting-authority -> attention
+  const awaiting = (rt.ownerPrompt?.status ?? "").toLowerCase() === "awaiting-authority";
+  if (runtimeBlocked || awaiting) {
+    const agent = currentRole ?? "ceo";
+    const msg =
+      rt.currentAction ?? rt.ownerPrompt?.summary ?? (runtimeBlocked ? "runtime blocked" : "awaiting authority");
+    alerts.push({
+      id: nextId("rt"),
+      level: "attention",
+      agent,
+      msg,
+      at: parseTs(rt.updatedAt) ?? nowMs,
+    });
+  }
+
+  // running-but-stale heartbeat -> stale
+  for (const a of agents) {
+    if (a.loop !== "running") continue;
+    if (a.heartbeat == null) continue;
+    if (nowMs - a.heartbeat > STALE_MS) {
+      alerts.push({
+        id: nextId("stale-" + a.id),
+        level: "stale",
+        agent: a.id,
+        msg: "running, but no recent visible movement",
+        at: a.heartbeat,
+      });
+    }
+  }
+
+  // protocolViolations -> attention
+  for (const mission of snapshot.missions) {
+    for (const v of mission.protocolViolations) {
+      const agent = currentRole ?? "ceo";
+      alerts.push({
+        id: nextId("pv"),
+        level: "attention",
+        agent,
+        msg: v,
+        at: parseTs(mission.ts) ?? nowMs,
+      });
+    }
+  }
+
+  return alerts;
+}
+
+/* ---- misc ------------------------------------------------------------- */
+
+function eventId(ev: HarnessEvent, i: number): string {
+  const t = ev.ts ?? "";
+  const owner = ev.owner ?? "";
+  const kind = ev.type ?? ev.status ?? "";
+  return `ev-${i}-${t}-${owner}-${kind}`;
+}

package/apps/harness-dashboard/lib/brick/contract.ts

@@ -0,0 +1,247 @@
+/* =============================================================
+   walwal-harness · BRICK OFFICE Data Contract
+   The single state shape every view renders from. Ported from the
+   design-handoff simulation (harness/sim.jsx, harness/ui.jsx) — but
+   here it is produced from REAL harness data by lib/brick/adapter.ts.
+
+   This module is pure (no React, no DOM). It exports:
+   - the Contract TypeScript interfaces
+   - AGENT_DEFS (the 6 CXX roles with id/name/role/hue)
+   - fmt utils (time, hm, ago, k, money)
+   - statusColor + STATUS_COLOR
+   ============================================================= */
+
+/** The role ids of the 6 exec agents, in canonical display order. */
+export type AgentRole = "ceo" | "coo" | "cdo" | "cto" | "cqo" | "ops";
+
+/**
+ * Status enum shared by agents and workers. The simulation used the full set
+ * (idle | typing | talking | active | alert | live); the real adapter only
+ * emits the subset {live, active, alert, idle}, but the renderer/statusColor
+ * still understands every value so the design's legend stays faithful.
+ */
+export type AgentStatus =
+  | "idle"
+  | "typing"
+  | "talking"
+  | "active"
+  | "alert"
+  | "live";
+
+/** The agent's autonomous loop state. */
+export type LoopState = "running" | "idle";
+
+/** Task lifecycle, as rendered by the task panel. */
+export type TaskStatus = "running" | "queued" | "done";
+
+/** Attention-queue severity. */
+export type AlertLevel = "stale" | "attention";
+
+/** A reference to a document the DocViewer can render. */
+export type DocTarget =
+  | { type: "agent"; agent: AgentRole }
+  | { type: "worker"; agent: AgentRole; worker: ContractWorker };
+
+/** Static, design-fixed definition of one exec agent. */
+export interface AgentDef {
+  id: AgentRole;
+  name: string;
+  role: string;
+  hue: string;
+}
+
+/** One exec agent row in the live state. */
+export interface ContractAgent {
+  id: AgentRole;
+  name: string;
+  role: string;
+  hue: string;
+  status: AgentStatus;
+  loop: LoopState;
+  /** One-line "current work" string. "—" when there is no live work string. */
+  work: string;
+  /** Open todo count. */
+  todos: number;
+  /** Count of live workers (derived from `workers` below). */
+  workers: number;
+  /** ~24 ints, recent activity, drives the bar sparkline. */
+  spark: number[];
+  /** epoch ms of last visible movement -> drives "stale"; null when unknown. */
+  heartbeat: number | null;
+  /** Full report markdown for this agent (mission[role]); undefined when none. */
+  report?: string;
+}
+
+/** One spawned worker across all agents. */
+export interface ContractWorker {
+  id: string;
+  agent: AgentRole;
+  name: string;
+  status: AgentStatus;
+  /** epoch ms; null when unknown. */
+  started: number | null;
+  /** 0..100, or null when there is no real granular progress source. */
+  progress: number | null;
+  /** Full worker report/brief markdown (worker.content); undefined when none. */
+  report?: string;
+}
+
+/** One task in the running/queued/done lanes. */
+export interface ContractTask {
+  id: string;
+  /** Owner display label, e.g. "CTO". */
+  owner: string;
+  title: string;
+  agent: AgentRole;
+  status: TaskStatus;
+  /** 0..100, or null — there is no real granular progress source. */
+  progress: number | null;
+  /** epoch ms the task started, or null. */
+  started?: number | null;
+  /** epoch ms the task completed (done lane only), or null. */
+  at?: number | null;
+}
+
+/** The three task lanes. */
+export interface ContractTasks {
+  running: ContractTask[];
+  queued: ContractTask[];
+  done: ContractTask[];
+}
+
+/** One activity-stream event. */
+export interface ContractEvent {
+  id: string;
+  /** epoch ms; null when unknown. */
+  at: number | null;
+  agent: AgentRole | "";
+  worker: string;
+  /** The verb; "COMPLETE"/"complete" renders green. */
+  verb: string;
+  /** The object the verb acted on. */
+  obj: string;
+}
+
+/** One attention-queue alert. */
+export interface ContractAlert {
+  id: string;
+  level: AlertLevel;
+  agent: AgentRole;
+  msg: string;
+  /** epoch ms; null when unknown. */
+  at: number | null;
+}
+
+/**
+ * System-health metrics. Values with no real telemetry source are `null`
+ * and MUST render as "—" (never a fabricated number).
+ */
+export interface ContractMetrics {
+  /** "open" when the SSE stream is connected, else "closed". */
+  sse: "open" | "closed";
+  /** Rolling tokens/min from /api/metrics ring buffer; null until sourced. */
+  tokensPerMin: number | null;
+  /** USD cost; an ESTIMATE from /api/metrics (see costEstimated); null when unsourced. */
+  costToday: number | null;
+  /** True when costToday is a price-table estimate (not a billed figure). */
+  costEstimated?: boolean;
+  /** 0..100 context-window occupancy of the most-active session; null when unknown. */
+  contextPct?: number | null;
+  /** Count of events in the last 60s (derived). */
+  throughput: number | null;
+  /** Summed %cpu of discovered company PIDs; null when no telemetry. */
+  cpu: number | null;
+  /** Count of missions of type 'hotfix'. */
+  hotfix: number;
+  /** Total events in the snapshot. */
+  eventsTotal: number;
+}
+
+/** The single source-of-truth state every view renders from. */
+export interface ContractState {
+  /** epoch ms, ticked ~1/s by the shell. */
+  now: number;
+  agents: ContractAgent[];
+  workers: ContractWorker[];
+  tasks: ContractTasks;
+  events: ContractEvent[];
+  /** 24 hourly buckets = owner prompts/hour -> heatmap. */
+  cadence: number[];
+  alerts: ContractAlert[];
+  metrics: ContractMetrics;
+  /** tokens/min sparkline samples; [] when no source. */
+  mtrend: number[];
+  /** cost sparkline samples; [] when no source. */
+  ctrend: number[];
+}
+
+/* ---- agent (exec) definitions -----------------------------------------
+   The 6 CXX roles in canonical order, with per-role accent hue.
+   Ported from sim.jsx AGENTS, with hues per the adapter spec. */
+export const AGENT_DEFS: readonly AgentDef[] = [
+  { id: "ceo", name: "CEO", role: "Chief Executive", hue: "#4cc2ff" },
+  { id: "coo", name: "COO", role: "Operations", hue: "#3fd17a" },
+  { id: "cdo", name: "CDO", role: "Design", hue: "#8b95a4" },
+  { id: "cto", name: "CTO", role: "Technology", hue: "#f0a23b" },
+  { id: "cqo", name: "CQO", role: "Quality", hue: "#c084fc" },
+  { id: "ops", name: "OPS", role: "Runtime Watch", hue: "#f97e4d" },
+] as const;
+
+/** The 6 role ids in canonical order. */
+export const AGENT_ROLES: readonly AgentRole[] = AGENT_DEFS.map((a) => a.id);
+
+/** Quick lookup by role id. */
+export const AGENT_DEF_BY_ID: Record<AgentRole, AgentDef> = AGENT_DEFS.reduce(
+  (acc, def) => {
+    acc[def.id] = def;
+    return acc;
+  },
+  {} as Record<AgentRole, AgentDef>
+);
+
+/* ---- status colors (ported from ui.jsx) ------------------------------- */
+export const STATUS_COLOR: Record<string, string> = {
+  live: "#3fd17a",
+  active: "#3fd17a",
+  typing: "#4cc2ff",
+  talking: "#c084fc",
+  idle: "#5a6472",
+  alert: "#f0506b",
+  running: "#3fd17a",
+  stale: "#f0a23b",
+};
+
+export const statusColor = (s: string): string => STATUS_COLOR[s] ?? "#5a6472";
+
+/* ---- fmt utils (ported from sim.jsx) ----------------------------------
+   Pure formatting helpers. `time`/`hm` take a Date; `ago` takes a ms delta;
+   `k`/`money` take numbers (and tolerate null -> "—" for honest blanks). */
+export const fmt = {
+  /** "HH:MM:SS" */
+  time: (d: Date): string => d.toTimeString().slice(0, 8),
+  /** "HH:MM" */
+  hm: (d: Date): string => d.toTimeString().slice(0, 5),
+  /** humanize a ms delta -> "Ns ago" / "Nm ago" / "Nh ago" */
+  ago: (ms: number): string => {
+    const s = Math.floor(ms / 1000);
+    if (s < 60) return s + "s ago";
+    const m = Math.floor(s / 60);
+    if (m < 60) return m + "m ago";
+    const h = Math.floor(m / 60);
+    return h + "h ago";
+  },
+  /** compact thousands: 11200 -> "11.2k"; null -> "—" */
+  k: (n: number | null | undefined): string => {
+    if (n == null || !Number.isFinite(n)) return "—";
+    return n >= 1000 ? (n / 1000).toFixed(1) + "k" : String(Math.round(n));
+  },
+  /** "$42.18"; null -> "—" */
+  money: (n: number | null | undefined): string => {
+    if (n == null || !Number.isFinite(n)) return "—";
+    return "$" + n.toFixed(2);
+  },
+};
+
+/** Render a possibly-null number as the design's em-dash blank. */
+export const dashIfNull = (n: number | null | undefined): string =>
+  n == null || !Number.isFinite(n) ? "—" : String(n);