shapeup-sdlc 1.6.3 → 3.0.0

package/kernel/report/export.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+// export-run — freeze a run's records into fact tables before the tier that holds them is wiped.
+//
+// WHY THIS EXISTS (from the storage design, not from a preference for tooling).
+//
+// Every record this exports already exists. Orders, results, journal rows, trial rows, T0
+// verdicts, criterion verdicts and hook decisions are all written during a normal run, all as
+// JSON, all schema-registered. They live in `.shapeup/<slug>/` — the LOCAL tier, which ADR-0001
+// defines as gitignored, machine-local and REGENERABLE. That definition is correct for run state
+// and fatal for measurement: the trial-row contract says it out loud — a measurement left there
+// "answers the question exactly once and then deletes itself".
+//
+// So the harness has been producing a complete dataset and discarding it. Not losing it to a bug;
+// discarding it by design, because nothing ever read it before the directory was cleaned. This
+// script is the read that was missing, and it is deliberately a SEPARATE STEP rather than a write
+// added to the pipeline: the run's writers stay exactly as they are, ``harness reduce ingest`` remains
+// the sole writer of shared state, and an export can be re-run against a trace at any point
+// without touching it.
+//
+// WHAT IT DOES NOT DO, said plainly rather than left to be discovered. It does not make the
+// records cross a machine boundary on its own. The default destination is `.shapeup/exports/`,
+// which survives a per-slug wipe but is still gitignored — because committing per-run structured
+// data and a machine id is precisely what ADR-0001 moved the metrics shards out of git to prevent.
+// A cross-machine warehouse is `--out <dir>` to a destination the operator owns and chooses. The
+// export makes the evidence DURABLE and PORTABLE; where it travels stays a human decision.
+//
+// READ-ONLY, AND FAIL-OPEN PER RECORD. Nothing here writes into the run trace. A file that will
+// not parse is skipped and COUNTED in the manifest rather than aborting the export — a warehouse
+// loader that dies on one bad line loses the other nine thousand, and the count is what tells an
+// analyst their table is short. It never grades: every column is an id, a count, a duration or a
+// copied enum, per the rule ``harness probe stats`` states in its own header.
+//
+// USAGE
+//   node `harness report export` [--slug <slug>] [--cwd <dir>] [--out <dir>] [--all] [--format jsonl|json]
+//
+//   --slug     the run to export; defaults to the active-scope pointer's slug
+//   --all      export every run under the LOCAL root that has a readable receipt
+//   --out      destination root (default: .shapeup/exports/); each run lands in <out>/<run_id>/
+//   --format   jsonl (default — one object per line, what a warehouse reads natively) or json
+//
+// Prints the manifest(s) on stdout. Exit 0 on success, 2 on a usage error, 3 when there is
+// nothing to export.
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { splitFrontmatter } from "../lib/contract.mjs";
+import { runIdFromReceipt, readReceipt } from "../lib/paths.mjs";
+import { TABLES, runRow, agentCallRow, dispatchFacts, economics } from "./facts.mjs";
+import {
+  localDir, activeScope, receipt as receiptPath, harnessRun, ordersDir, resultsDir,
+  workflowRunDir, trials as trialsPath, verdictsDir, evaluationDir, decisions as decisionsPath,
+  exportsDir, exportRunDir,
+} from "../lib/paths.mjs";
+
+export const EXPORT_SCHEMA_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Readers — every one of them returns data plus a defect count, never throws
+// ---------------------------------------------------------------------------
+
+/** A read tally threaded through every reader so the manifest can report what did not parse. */
+const tally = () => ({ skipped: 0 });
+
+/**
+ * Parse a JSON file, counting rather than throwing on failure.
+ * @param {string} path - File to read.
+ * @param {{skipped:number}} t - Defect tally, incremented on a parse or read failure.
+ * @returns {(*|null)} The parsed value, or null.
+ */
+function readJson(path, t) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { t.skipped++; return null; }
+}
+
+/**
+ * Parse a JSONL file into rows, skipping (and counting) lines that do not parse.
+ * @param {string} path - File to read; a missing file is not a defect, it is an empty table.
+ * @param {{skipped:number}} t - Defect tally.
+ * @returns {Array<object>} The parsed rows, in file order.
+ */
+function readJsonl(path, t) {
+  if (!existsSync(path)) return [];
+  let text;
+  try { text = readFileSync(path, "utf8"); } catch { t.skipped++; return []; }
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { t.skipped++; }
+  }
+  return out;
+}
+
+/**
+ * Read every `*.json` in a directory, sorted by name so an export is byte-stable across runs.
+ * @param {string} dir - Directory to scan; absent → empty.
+ * @param {{skipped:number}} t - Defect tally.
+ * @returns {Array<object>} Parsed documents, name-sorted.
+ */
+function readJsonDir(dir, t) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(".json")).sort()) {
+    const doc = readJson(join(dir, f), t);
+    if (doc) out.push(doc);
+  }
+  return out;
+}
+
+/**
+ * Flatten a T0 verdict artifact into one fact row, dropping the nested arms (they are the
+ * `CommandResult` detail, and belong to the artifact, not to a column).
+ * @param {object} a - A parsed T0Artifact.
+ * @param {(string|null)} runId - Run key for artifacts written before the field existed.
+ * @returns {object} A flat `t0_verdict` row.
+ */
+function t0Row(a, runId) {
+  const fixtures = Array.isArray(a?.fixtures) ? a.fixtures : [];
+  return {
+    run_id: a?.run_id ?? runId ?? null,
+    scope_id: a?.scope_id ?? null,
+    round: a?.round ?? null,
+    attempt: a?.attempt ?? null,
+    trial: a?.trial ?? null,
+    at: a?.at ?? null,
+    overall: a?.overall ?? null,
+    regression: a?.regression ?? null,
+    fixtures_green: a?.fixtures_green ?? null,
+    db_probe_green: a?.db_probe_green ?? null,
+    seesaw_green: a?.seesaw_green ?? null,
+    fixtures_total: fixtures.length,
+    fixtures_passed: fixtures.filter((f) => f?.pass === true).length,
+    seesaw_ran: a?.seesaw?.ran ?? null,
+    seesaw_failing: Array.isArray(a?.seesaw?.failing) ? a.seesaw.failing.length : null,
+    discovered_tasks: Array.isArray(a?.discovered_tasks) ? a.discovered_tasks.length : 0,
+  };
+}
+
+/**
+ * Collect every criterion-verdict row across the evaluator's per-target ledgers.
+ * @param {string} dir - The run's `evaluation/` directory.
+ * @param {(string|null)} runId - Run key to stamp (the ledger line carries none).
+ * @param {{skipped:number}} t - Defect tally.
+ * @returns {Array<object>} Flat `criterion_verdict` rows, each tagged with its target ledger.
+ */
+function criterionRows(dir, runId, t) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const f of readdirSync(dir).filter((x) => x.startsWith(".verdicts-") && x.endsWith(".jsonl")).sort()) {
+    const target = f.replace(/^\.verdicts-/, "").replace(/\.jsonl$/, "");
+    for (const row of readJsonl(join(dir, f), t)) {
+      out.push({
+        run_id: runId ?? null, target,
+        run: row?.run ?? null,
+        dimension: row?.dimension ?? null,
+        criterion: row?.criterion ?? null,
+        verdict: row?.verdict ?? null,
+        confidence: row?.confidence ?? null,
+        reprobed: row?.reprobed ?? null,
+        has_evidence: !!(row?.evidence && String(row.evidence).trim()),
+        at: row?.at ?? null,
+      });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The export itself
+// ---------------------------------------------------------------------------
+
+/**
+ * Read one run's trace and project it into fact tables. Pure-ish: reads the run trace, writes
+ * nothing.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - The feature slug whose run to export.
+ * @returns {(object|null)} `{run_id, slug, tables:{…}, economics, defects}` — or null when the
+ *   slug has no readable receipt, which is the definition of "not a run".
+ */
+export function collectRun(cwd, slug) {
+  const t = tally();
+  const rec = readReceipt(receiptPath(cwd, slug));
+  if (!rec) return null;
+  const runId = runIdFromReceipt(rec);
+
+  let ledger = {};
+  try { ledger = splitFrontmatter(readFileSync(harnessRun(cwd, slug), "utf8")).meta || {}; } catch { /* no ledger yet */ }
+
+  const orders = readJsonDir(ordersDir(cwd, slug), t);
+  const results = readJsonDir(resultsDir(cwd, slug), t);
+  const journal = readJsonl(join(workflowRunDir(cwd, slug), "journal.jsonl"), t);
+
+  const { dispatch, ac_result, discovery, file_touched } = dispatchFacts({ orders, results, journal, runId });
+  const agent_call = journal.map((j) => agentCallRow(j, runId));
+  const run = runRow({ receipt: rec, ledger, runId });
+
+  // Hook decisions are checkout-wide, so they are FILTERED to this run rather than read from a
+  // per-run file. Rows with a null key belong to no run (a hook that fired outside one) and are
+  // correctly excluded here — they are not this run's, and claiming them would inflate its
+  // enforcement counts with ambient activity.
+  const hook_decision = readJsonl(decisionsPath(cwd), t).filter((d) => runId && d?.run_id === runId);
+
+  return {
+    run_id: runId,
+    slug,
+    tables: {
+      run: run ? [run] : [],
+      dispatch, ac_result, discovery, file_touched, agent_call,
+      trial: readJsonl(trialsPath(cwd, slug), t).map((r) => ({ ...r, run_id: r.run_id ?? runId ?? null })),
+      t0_verdict: readJsonDir(verdictsDir(cwd, slug), t).map((a) => t0Row(a, runId)),
+      criterion_verdict: criterionRows(evaluationDir(cwd, slug), runId, t),
+      hook_decision,
+    },
+    economics: economics({ agent_call, dispatch, run }),
+    defects: { records_skipped: t.skipped },
+  };
+}
+
+/**
+ * Write one collected run's tables to disk and return its manifest.
+ * @param {object} collected - Output of {@link collectRun}.
+ * @param {string} outDir - Destination directory for this run's tables.
+ * @param {string} format - `jsonl` (one object per line) or `json` (one array per file).
+ * @returns {object} The manifest, which is also written to `<outDir>/manifest.json`.
+ */
+export function writeRun(collected, outDir, format = "jsonl") {
+  mkdirSync(outDir, { recursive: true });
+  const ext = format === "json" ? "json" : "jsonl";
+  const rows = {};
+  for (const name of TABLES) {
+    const table = collected.tables[name] || [];
+    rows[name] = table.length;
+    const body = format === "json"
+      ? JSON.stringify(table, null, 2) + "\n"
+      : table.map((r) => JSON.stringify(r)).join("\n") + (table.length ? "\n" : "");
+    writeFileSync(join(outDir, `${name}.${ext}`), body, "utf8");
+  }
+  const manifest = {
+    schema_version: EXPORT_SCHEMA_VERSION,
+    run_id: collected.run_id,
+    slug: collected.slug,
+    generated_at: new Date().toISOString(),
+    format: ext,
+    tables: TABLES.map((name) => ({ name, file: `${name}.${ext}`, rows: rows[name] })),
+    rows_total: Object.values(rows).reduce((a, b) => a + b, 0),
+    // The defect count is a first-class manifest field, not a log line. A short table with no
+    // record of why is indistinguishable from a short run.
+    records_skipped: collected.defects.records_skipped,
+    economics: collected.economics,
+  };
+  writeFileSync(join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  return manifest;
+}
+
+/**
+ * Every slug under the LOCAL root that has a readable receipt — i.e. every run, discovered from
+ * the filesystem rather than from a list someone has to maintain.
+ * @param {string} cwd - Project root.
+ * @returns {string[]} Slugs, sorted.
+ */
+export function discoverRuns(cwd) {
+  const root = localDir(cwd);
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const e of readdirSync(root)) {
+    try { if (!statSync(join(root, e)).isDirectory()) continue; } catch { continue; }
+    if (existsSync(receiptPath(cwd, e))) out.push(e);
+  }
+  return out.sort();
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/** The typed argv contract (see `./lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "harness.mjs report export [--slug <slug>] [--all] [--cwd <dir>] [--out <dir>] [--format jsonl|json]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  cwd: { type: "path" },
+  slug: { type: "str" },
+  out: { type: "path" },
+  all: { type: "flag" },
+  format: { type: "enum", values: ["jsonl", "json"], default: "jsonl" },
+};
+
+/**
+ * Project a run's records as fact tables under the exports tier.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+
+  let slugs = [];
+  if (args.all) slugs = discoverRuns(cwd);
+  else if (args.slug) slugs = [args.slug];
+  else {
+    // The active-scope pointer, same as every other run-scoped tool resolves through.
+    const active = readJson(activeScope(cwd), tally());
+    if (active?.slug) slugs = [active.slug];
+  }
+  if (!slugs.length) {
+    console.error("✋ export-run: no run to export — pass --slug <slug>, or --all, or open a run first.");
+    process.exit(3);
+  }
+
+  const outRoot = args.out ? resolve(cwd, args.out) : exportsDir(cwd);
+  const manifests = [];
+  for (const slug of slugs) {
+    const collected = collectRun(cwd, slug);
+    if (!collected) { console.error(`export-run: ${slug} has no readable receipt — skipped (not a run)`); continue; }
+    // Keyed by RUN ID, not by slug: two runs of the same feature are two datasets, and filing them
+    // under the slug would make the second silently overwrite the first — the exact collision the
+    // run key exists to end.
+    const dir = args.out ? join(outRoot, String(collected.run_id ?? slug)) : exportRunDir(cwd, collected.run_id ?? slug);
+    manifests.push(writeRun(collected, dir, args.format));
+  }
+  if (!manifests.length) process.exit(3);
+  console.log(JSON.stringify(manifests.length === 1 ? manifests[0] : manifests, null, 2));
+}
+

package/kernel/report/facts.mjs

@@ -0,0 +1,347 @@
+// facts — the harness's records, projected into fact tables. Pure: no I/O, no clock, no grading.
+//
+// WHY THIS FILE EXISTS.
+//
+// The pipeline already writes JSON at every boundary — an order in, a result out, a journal row
+// per agent call, a decision row per hook evaluation, a trial row per T0 run. What it never had
+// was a way to READ them together. Each record answers a question about itself; none of them
+// answers "what did this run do, and what did it cost", because that question needs a join and
+// nothing on disk was joinable (see `mintRunId` in `lib/paths.mjs` for why).
+//
+// This module is the projection half. It takes parsed records and returns flat rows — a star
+// schema whose grain is the DISPATCH, which is the finest unit the harness actually plans in:
+// one compiled order, one worker, one result. Everything else either rolls up to it
+// (`agent_call`, via the join below) or hangs off it as a child table (`ac_result`,
+// `discovery`, `file_touched`).
+//
+// TWO RULES, INHERITED, AND NEITHER IS STYLISTIC.
+//
+//   1. FACTS ONLY — the rule ``harness probe stats`` states in its own header. Every field below is a count,
+//      a duration, a copied enum or an id. No field here is a score, a rate of quality, or a
+//      judgement, because a computed grade in the read plane is a second judge behind
+//      spec-evaluator and the architecture forbids one. `n_ac_fail` is a fact; "AC health" is not.
+//
+//   2. NEVER FABRICATE A JOIN. The agent-call join (below) is real but partial, so every dispatch
+//      row carries `agent_join` naming HOW it was joined — or `null` when it wasn't. An analyst
+//      summing `cost_usd` must be able to see what share of dispatches had no cost row at all,
+//      because the alternative is a total that silently under-reports and looks authoritative.
+//      This is the same defect shape as `allow` with no receipt: an absent value and a zero value
+//      must not share a signature.
+//
+// THE AGENT-CALL JOIN, stated exactly. `journal.jsonl` is the only record carrying `cost_usd` and
+// wall-clock, and its rows name no order — the launcher is generic and never parsed the prompt it
+// was given. But the workflow's dispatch prompt asks the worker for a `result_path`, and that path
+// is `<run root>/results/<stem>.json`, whose stem is the order id's suffix. So a journal row whose
+// returned object carries `result_path` joins to exactly one order, deterministically, with no
+// heuristics. Rows without it — the mechanical `set-active-order` couriers, a failed dispatch that
+// returned nothing — join to no order and are counted as unattributed rather than dropped.
+
+/** Every fact table this module can produce, in dependency order. Exported so the writer, the
+ * manifest and the tests enumerate one list instead of three. */
+export const TABLES = [
+  "run", "dispatch", "ac_result", "discovery", "file_touched",
+  "agent_call", "trial", "t0_verdict", "criterion_verdict", "hook_decision",
+];
+
+/** Coerce anything to a finite number, or null. Keeps `0` and rejects `NaN`/`""`/undefined. */
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/** Sum a list of numbers, returning null when NOTHING in it was a number — an absent total and a
+ * zero total are different facts and must not share a representation. */
+function sumOrNull(values) {
+  let seen = false, total = 0;
+  for (const v of values) { const n = num(v); if (n !== null) { seen = true; total += n; } }
+  return seen ? total : null;
+}
+
+/**
+ * The order id's file stem — the name its order and result files share.
+ * @param {string} orderId - e.g. `checkout/sc-01-r1-a2`.
+ * @returns {(string|null)} e.g. `sc-01-r1-a2`, or null when the id has no `/`.
+ */
+export function orderStem(orderId) {
+  const s = String(orderId ?? "");
+  const i = s.indexOf("/");
+  return i === -1 ? null : s.slice(i + 1) || null;
+}
+
+/**
+ * The round/attempt/scope an order's stem encodes, parsed back out.
+ *
+ * Read from the id rather than from the payload deliberately: the id is what every other record
+ * references, so a fact table keyed on it must agree with it even if a payload disagrees.
+ *
+ * @param {string} orderId - The order id.
+ * @returns {{scope_id:(string|null), round:(number|null), attempt:(number|null)}} Nulls where the
+ *   stem carries no such term (a non-build operation has no round or attempt).
+ */
+export function parseOrderStem(orderId) {
+  const stem = orderStem(orderId) || "";
+  const m = stem.match(/^(?:(.*)-)?r(\d+)-a(\d+)$/);
+  if (m) return { scope_id: m[1] || null, round: Number(m[2]), attempt: Number(m[3]) };
+  const opRound = stem.match(/^(.*)-r(\d+)$/);
+  if (opRound) return { scope_id: null, round: Number(opRound[2]), attempt: null };
+  return { scope_id: null, round: null, attempt: null };
+}
+
+/**
+ * The order stem a journal row refers to, via the `result_path` its schema'd reply carries.
+ * @param {object} row - One `journal.jsonl` row.
+ * @returns {(string|null)} The stem, or null when the row named no result path.
+ */
+export function journalOrderStem(row) {
+  const p = row?.result?.result_path;
+  if (typeof p !== "string" || !p) return null;
+  const base = p.split(/[/\\]/).pop() || "";
+  return base.replace(/\.json$/i, "") || null;
+}
+
+/**
+ * Project the run dimension — one row, the thing every fact table's `run_id` points at.
+ * @param {object} o - Sources (destructured):
+ * @param {(object|null)} o.receipt - Parsed `receipt.json`.
+ * @param {(object|null)} [o.ledger] - Parsed `harness-run.md` frontmatter (a flat scalar map).
+ * @param {(string|null)} [o.runId] - The run key, when already resolved.
+ * @returns {(object|null)} The run row, or null when there is no receipt to describe.
+ */
+export function runRow({ receipt, ledger = null, runId = null }) {
+  if (!receipt) return null;
+  const c = receipt.config || {};
+  const fm = ledger || {};
+  return {
+    run_id: runId ?? receipt.run_id ?? null,
+    slug: receipt.slug ?? null,
+    started_at: receipt.started_at ?? null,
+    closed_at: fm.closed_at && fm.closed_at !== "~" ? fm.closed_at : null,
+    intake_sha256: receipt.intake_sha256 ?? null,
+    intake_chars: num(receipt.intake_chars),
+    intake_lines: num(receipt.intake_lines),
+    auto_level: c.auto_level ?? null,
+    lens: c.lens ?? null,
+    lane: c.fit?.lane ?? null,
+    lane_overridden_from: c.fit?.overridden_from ?? null,
+    max_rounds: num(c.max_rounds),
+    attempt_budget: num(c.attempt_budget),
+    wall_clock_budget_s: num(c.wall_clock_budget_s),
+    eval_dimensions: Array.isArray(c.eval_dimensions) ? c.eval_dimensions.join(" ") : null,
+    // Copied from the ledger, never re-derived: the run's own status line is the harness's answer,
+    // and a read plane that recomputed it would be asserting a second one.
+    status: fm.status ?? null,
+    final_verdict: fm.final_verdict && fm.final_verdict !== "~" ? fm.final_verdict : null,
+    rounds_used: num(Number(fm.rounds_used)),
+  };
+}
+
+/**
+ * Project one agent-call row from a journal row.
+ * @param {object} row - One `journal.jsonl` row.
+ * @param {(string|null)} runId - The run key to stamp when the row itself carries none.
+ * @returns {object} A flat `agent_call` fact row.
+ */
+export function agentCallRow(row, runId = null) {
+  const sessions = Array.isArray(row?.sessions) ? row.sessions : [];
+  return {
+    run_id: row?.run_id ?? runId ?? null,
+    seq: num(row?.seq),
+    phase: row?.phase ?? null,
+    label: row?.label ?? null,
+    model: row?.model ?? null,
+    permission_mode: row?.permission_mode ?? null,
+    started_at: row?.started_at ?? null,
+    wall_ms: num(row?.wall_ms),
+    // The launcher retries a schema-invalid reply once, so `attempts` > 1 is a fact about the
+    // WORKER's compliance and is kept distinct from `ok`, which is about the final outcome.
+    attempts: num(row?.attempts),
+    ok: typeof row?.ok === "boolean" ? row.ok : null,
+    cost_usd: sumOrNull(sessions.map((s) => s?.cost_usd)),
+    sessions: sessions.length,
+    errored: sessions.some((s) => s?.is_error === true),
+    killed: sessions.some((s) => s?.killed === true),
+    order_stem: journalOrderStem(row),
+  };
+}
+
+/**
+ * Project the dispatch fact table and its three child tables.
+ *
+ * One row per ORDER — orders are the spine, because an order with no result is the fact you most
+ * need (a dispatch that never came back), and a result with no order cannot exist by construction.
+ *
+ * @param {object} o - Sources (destructured):
+ * @param {Array<object>} o.orders - Parsed WorkOrders.
+ * @param {Array<object>} [o.results] - Parsed WorkResults; joined on `order_id`.
+ * @param {Array<object>} [o.journal] - Parsed journal rows; joined on the result-path stem.
+ * @param {(string|null)} [o.runId] - Run key for orders that carry none (pre-v1.8 traces).
+ * @returns {{dispatch:Array<object>, ac_result:Array<object>, discovery:Array<object>,
+ *   file_touched:Array<object>}} The fact table and its children, each row already carrying
+ *   `run_id` + `order_id` so every table stands alone in the warehouse.
+ */
+export function dispatchFacts({ orders, results = [], journal = [], runId = null }) {
+  const byOrderId = new Map();
+  for (const r of results) if (r?.order_id) byOrderId.set(r.order_id, r);
+  const byStem = new Map();
+  for (const j of journal) {
+    const stem = journalOrderStem(j);
+    // Last write wins: a dispatch retried after a failure legitimately produces two journal rows
+    // for one order, and the one that finished it is the one whose cost the dispatch carries. The
+    // discarded row is NOT lost — it remains its own `agent_call` row, so the retry is still
+    // visible and the two totals differ by exactly the retries.
+    if (stem) byStem.set(stem, j);
+  }
+
+  const dispatch = [], ac_result = [], discovery = [], file_touched = [];
+
+  for (const order of orders) {
+    if (!order?.order_id) continue;
+    const id = order.order_id;
+    const rid = order.run_id ?? runId ?? null;
+    const stem = orderStem(id);
+    const { scope_id, round, attempt } = parseOrderStem(id);
+    const result = byOrderId.get(id) || null;
+    const call = stem ? byStem.get(stem) || null : null;
+    const agent = call ? agentCallRow(call, rid) : null;
+    const taskResults = Array.isArray(result?.task_results) ? result.task_results : [];
+    const discoveries = Array.isArray(result?.discoveries) ? result.discoveries : [];
+    const filesTouched = Array.isArray(result?.files_touched) ? result.files_touched : [];
+
+    let acPass = 0, acFail = 0, acSkip = 0;
+    for (const tr of taskResults) {
+      for (const ac of Array.isArray(tr?.ac_results) ? tr.ac_results : []) {
+        if (ac?.result === "pass") acPass++;
+        else if (ac?.result === "fail") acFail++;
+        else acSkip++;
+        ac_result.push({
+          run_id: rid, order_id: id,
+          task_id: tr?.task_id ?? null,
+          ac: ac?.ac ?? null,
+          result: ac?.result ?? null,
+          // The evidence TEXT is the worker's prose and belongs in the result file, not in a fact
+          // table. Whether it exists at all is the fact — "no evidence = fail by the worker's own
+          // hand" is a contract the warehouse can then check without re-reading every envelope.
+          has_evidence: !!(ac?.evidence && String(ac.evidence).trim()),
+        });
+      }
+    }
+    for (const d of discoveries) {
+      discovery.push({
+        run_id: rid, order_id: id,
+        marker: d?.marker ?? null,
+        lens: d?.lens ?? null,
+        severity_hint: d?.severity_hint ?? null,
+        test_gap: d?.test_gap ?? null,
+        contradicts: d?.contradicts ?? null,
+        has_repro: !!(d?.repro && String(d.repro).trim()),
+        line: d?.line ?? null,
+      });
+    }
+    for (const f of filesTouched) {
+      file_touched.push({
+        run_id: rid, order_id: id,
+        path: f?.path ?? null,
+        change: f?.change ?? null,
+        lines: num(f?.lines),
+      });
+    }
+
+    dispatch.push({
+      run_id: rid,
+      order_id: id,
+      slug: id.split("/")[0] || null,
+      stem,
+      worker: order.worker ?? null,
+      operation: order.operation ?? null,
+      mode: order.mode ?? null,
+      scope_id: scope_id ?? order.payload?.scope_contract?.scope_id ?? null,
+      round, attempt,
+      compiled_at: order.compiled_at ?? null,
+      tasks_ordered: Array.isArray(order.payload?.tasks) ? order.payload.tasks.length : 0,
+      digested_errors: Array.isArray(order.payload?.digested_errors) ? order.payload.digested_errors.length : 0,
+      // `null`, not `"missing"`: a dispatch with no result file is the single most important row
+      // in this table, and it must be filterable as an absence rather than as a status value that
+      // sorts alongside real ones.
+      result_status: result?.status ?? null,
+      answered: !!result,
+      task_results: taskResults.length,
+      ac_pass: acPass, ac_fail: acFail, ac_skipped: acSkip,
+      discoveries: discoveries.length,
+      files_touched: filesTouched.length,
+      lines_touched: sumOrNull(filesTouched.map((f) => f?.lines)),
+      has_verdict: !!result?.verdict,
+      verdict_overall: result?.verdict?.overall ?? null,
+      assumptions: Array.isArray(result?.assumptions) ? result.assumptions.length : 0,
+      deviations: Array.isArray(result?.deviations) ? result.deviations.length : 0,
+      // The agent-call leg. Present only where the join held; `agent_join` says which.
+      agent_seq: agent?.seq ?? null,
+      model: agent?.model ?? null,
+      wall_ms: agent?.wall_ms ?? null,
+      cost_usd: agent?.cost_usd ?? null,
+      agent_attempts: agent?.attempts ?? null,
+      agent_ok: agent?.ok ?? null,
+      agent_join: agent ? "result_path" : null,
+    });
+  }
+  return { dispatch, ac_result, discovery, file_touched };
+}
+
+/**
+ * The run-economics projection — measurement-table row 4, computed from records the harness
+ * already writes.
+ *
+ * Every field is a count, a sum or a duration over recorded rows. Nothing here is normalised
+ * against a baseline, because no baseline dataset exists: this reports what a run cost, never
+ * whether that was good, which would be a grade.
+ *
+ * @param {object} o - Sources (destructured):
+ * @param {Array<object>} o.agent_call - Rows from {@link agentCallRow}.
+ * @param {Array<object>} [o.dispatch] - Rows from {@link dispatchFacts}; supplies the first write.
+ * @param {(object|null)} [o.run] - The run row; supplies `started_at` for the latency measures.
+ * @returns {object} `{agent_calls, cost_usd, cost_attributed_usd, cost_unattributed_usd,
+ *   wall_ms_total, calls_to_first_write, seconds_to_first_write, by_model[], retried_calls,
+ *   failed_calls, dispatches, dispatches_answered, dispatches_costed}` — with nulls, never zeros,
+ *   wherever the underlying record was absent.
+ */
+export function economics({ agent_call, dispatch = [], run = null }) {
+  const calls = Array.isArray(agent_call) ? agent_call : [];
+  const wroteBy = new Set(dispatch.filter((d) => (d.files_touched || 0) > 0).map((d) => d.stem));
+
+  // "Turns to first write" — the harness's own definition of the metric the design doc names but
+  // has never had an instrument for. Measured in AGENT CALLS, because a call is the unit that
+  // costs money; the seconds figure is reported beside it so a run that is slow and a run that is
+  // chatty stay distinguishable.
+  const ordered = [...calls].sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+  const firstWriteIdx = ordered.findIndex((c) => c.order_stem && wroteBy.has(c.order_stem));
+  const firstWrite = firstWriteIdx === -1 ? null : ordered[firstWriteIdx];
+  const startMs = run?.started_at ? Date.parse(run.started_at) : NaN;
+  const firstMs = firstWrite?.started_at ? Date.parse(firstWrite.started_at) : NaN;
+
+  const byModel = new Map();
+  for (const c of calls) {
+    const k = c.model || "(unnamed)";
+    const m = byModel.get(k) || { model: k, calls: 0, cost_usd: null, wall_ms: null };
+    m.calls++;
+    if (num(c.cost_usd) !== null) m.cost_usd = (m.cost_usd ?? 0) + c.cost_usd;
+    if (num(c.wall_ms) !== null) m.wall_ms = (m.wall_ms ?? 0) + c.wall_ms;
+    byModel.set(k, m);
+  }
+
+  const costed = new Set(dispatch.filter((d) => num(d.cost_usd) !== null).map((d) => d.order_id));
+  return {
+    agent_calls: calls.length,
+    cost_usd: sumOrNull(calls.map((c) => c.cost_usd)),
+    // The unattributed share is reported, never hidden: it is what the dispatch table's cost
+    // column is MISSING, and an analyst who cannot see it will read a partial total as a full one.
+    cost_attributed_usd: sumOrNull(calls.filter((c) => c.order_stem).map((c) => c.cost_usd)),
+    cost_unattributed_usd: sumOrNull(calls.filter((c) => !c.order_stem).map((c) => c.cost_usd)),
+    wall_ms_total: sumOrNull(calls.map((c) => c.wall_ms)),
+    calls_to_first_write: firstWriteIdx === -1 ? null : firstWriteIdx + 1,
+    seconds_to_first_write: Number.isFinite(startMs) && Number.isFinite(firstMs)
+      ? Math.round((firstMs - startMs) / 1000) : null,
+    retried_calls: calls.filter((c) => (c.attempts ?? 0) > 1).length,
+    failed_calls: calls.filter((c) => c.ok === false).length,
+    killed_calls: calls.filter((c) => c.killed).length,
+    dispatches: dispatch.length,
+    dispatches_answered: dispatch.filter((d) => d.answered).length,
+    dispatches_costed: costed.size,
+    by_model: [...byModel.values()].sort((a, b) => a.model.localeCompare(b.model)),
+  };
+}