@codedology/code-forge 0.1.0

package/src/ledger/report.mjs

@@ -0,0 +1,250 @@
+/**
+ * `code-forge report` (plan §6.2, R4): builds the 13 report sections from a run's ledger rows.
+ * Pure data, no I/O — terminal rendering + `--export` live in `src/cli/report.mjs`.
+ *
+ * Shadow rows (`row.source === 'shadow'`) are excluded everywhere here (plan §6.3: shadow-sampled
+ * answers are "never acted on" — must not move a single aggregate).
+ *
+ * Row conventions read here: `dispatch` {block,level,lane,lines}; `block.close`
+ * {block,status,lines_actual} — ANY `block.close` row marks the block completed (a stop is
+ * `block.stop`; B19); `review.plan` {block,tier,depth_unconstrained,depth_chosen,
+ * degrade_step}; `session` {block,role,provider,level,tokens_in,tokens_out,cost_usd?} — one row per
+ * coder/reviewer/judge/s2/author/facts spend; its dollars are `cost_usd` when the row carries it,
+ * else ESTIMATED from its tokens × `./prices.mjs` (B19: live session rows carry tokens only); `review.done` {block,file,context_mode,findings_by_severity,round}; `decision`
+ * {block,question,source}; `outcome` {block,missed_after_degrade}; `escalation` {block,trigger};
+ * `review.unavailable` {block,reason}; `proof` {block,duration_ms}; `run.stop` {reason}.
+ */
+
+import { estimateCostUsd } from './prices.mjs';
+
+const ROLE_BUCKET = Object.freeze({
+  coder: 'coderUsd',
+  author: 'coderUsd',
+  reviewer: 'reviewUsd',
+  judge: 'reviewUsd',
+  s2: 's1s2Usd',
+  facts: 'factsUsd',
+});
+
+/** @param {any[]} rows @param {(row: any) => string|undefined} keyOf */
+function countBy(rows, keyOf) {
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const row of rows) {
+    const key = keyOf(row);
+    if (key !== undefined) out[key] = (out[key] ?? 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * A session row's dollars: `cost_usd` when present, else tokens × the static price table; null when
+ * neither is known (no token count, or a provider/level the table does not price).
+ * @param {Record<string, any>} row @returns {number | null}
+ */
+export function sessionCostUsd(row) {
+  if (typeof row.cost_usd === 'number') return row.cost_usd;
+  const tokensIn = row.tokens_in ?? 0;
+  const tokensOut = row.tokens_out ?? 0;
+  if (row.tokens_in == null && row.tokens_out == null) return null;
+  try {
+    return estimateCostUsd({ provider: row.provider, level: row.level, tokensIn, tokensOut });
+  } catch {
+    return null;
+  }
+}
+
+/** Cost per SUCCESSFULLY COMPLETED block: review $ / coder $ / S1+S2 $ / facts $ / proof ms. */
+function costPerBlock(rows) {
+  /** @type {Map<string, any>} */
+  const byBlock = new Map();
+  for (const row of rows) {
+    if (!row.block) continue;
+    if (!byBlock.has(row.block)) {
+      byBlock.set(row.block, {
+        block: row.block,
+        level: null,
+        lane: null,
+        completed: false,
+        reviewUsd: 0,
+        coderUsd: 0,
+        s1s2Usd: 0,
+        factsUsd: 0,
+        otherUsd: 0,
+        proofTimeMs: 0,
+        totalUsd: 0,
+      });
+    }
+    const e = byBlock.get(row.block);
+    if (row.event === 'dispatch') {
+      e.level = row.level ?? e.level;
+      e.lane = row.lane ?? e.lane;
+    }
+    if (row.event === 'block.close') e.completed = true;
+    const cost = row.event === 'session' ? sessionCostUsd(row) : null;
+    if (cost !== null) {
+      // An unrecognized role still spent real money — bucket it as `otherUsd` instead of
+      // silently dropping it from every total (fix round 1: an unknown role must not make
+      // totalUsd under-report actual spend).
+      const bucket = ROLE_BUCKET[row.role] ?? 'otherUsd';
+      e[bucket] = (e[bucket] ?? 0) + cost;
+      e.totalUsd += cost;
+    }
+    if (row.event === 'proof' && typeof row.duration_ms === 'number') e.proofTimeMs += row.duration_ms;
+  }
+  const out = [...byBlock.values()].filter((e) => e.completed);
+  for (const e of out) {
+    for (const k of ['reviewUsd', 'coderUsd', 's1s2Usd', 'factsUsd', 'otherUsd', 'totalUsd']) e[k] = Math.round(e[k] * 10000) / 10000;
+  }
+  return out;
+}
+
+const laneDistribution = (rows) =>
+  rows.filter((r) => r.event === 'dispatch').map((r) => ({ block: r.block, lanePicked: r.lane ?? null, levelOpened: r.level ?? null }));
+
+const escalationsPerBlock = (rows) => rows.filter((r) => r.event === 'escalation').map((r) => ({ block: r.block, trigger: r.trigger }));
+
+const s1CallsPerBlock = (rows) =>
+  countBy(
+    rows.filter((r) => r.event === 'decision' && (r.source === 'jev' || r.source === 'rules')),
+    (r) => r.block,
+  );
+
+function s2RateAndOverrule(rows) {
+  const s2Rows = rows.filter((r) => r.event === 'decision' && (r.source === 's2' || r.source === 's2-fallback'));
+  return {
+    calls: countBy(s2Rows, (r) => r.question),
+    overrules: countBy(
+      s2Rows.filter((r) => r.overrule === true),
+      (r) => r.question,
+    ),
+  };
+}
+
+/**
+ * Review budget table (§4.10, R4 dataset): degrade count, `missed_after_degrade`, per-step plan
+ * counts. A file only counts as "degraded" when BOTH depth fields are present and differ — a row
+ * missing one of them is incomplete data, not evidence of degradation (`undefined !== 'full'` is
+ * true, which would otherwise silently count it). `missedAfterDegrade` counts DISTINCT
+ * `block::file` pairs that are BOTH flagged `missed_after_degrade: true` AND actually in the
+ * degraded set — this keeps a duplicate outcome row (a re-run `--scan-git`) or a stray flag on a
+ * file that was never degraded from inflating the count.
+ */
+function reviewBudgetTable(rows) {
+  const planRows = rows.filter((r) => r.event === 'review.plan');
+  const degradedRows = planRows.filter(
+    (r) => r.depth_unconstrained !== undefined && r.depth_chosen !== undefined && r.depth_unconstrained !== r.depth_chosen,
+  );
+  const degradedKeys = new Set(degradedRows.map((r) => `${r.block}::${r.file}`));
+  const missedKeys = new Set(
+    rows
+      .filter((r) => r.event === 'outcome' && r.missed_after_degrade === true && degradedKeys.has(`${r.block}::${r.file}`))
+      .map((r) => `${r.block}::${r.file}`),
+  );
+  return {
+    filesPlanned: planRows.length,
+    degradedCount: degradedRows.length,
+    missedAfterDegrade: missedKeys.size,
+    byDegradeStep: countBy(planRows, (r) => String(r.degrade_step ?? 0)),
+  };
+}
+
+function reviewDepthAndFindings(rows) {
+  const doneRows = rows.filter((r) => r.event === 'review.done');
+  /** @type {Record<string, number>} */
+  const findingsBySeverity = {};
+  for (const r of doneRows) {
+    for (const [sev, n] of Object.entries(r.findings_by_severity ?? {})) findingsBySeverity[sev] = (findingsBySeverity[sev] ?? 0) + n;
+  }
+  return { contextModeDistribution: countBy(doneRows, (r) => r.context_mode), findingsBySeverity };
+}
+
+/** Keyed by `<block>::<file>`, not `file` alone — the same path reviewed in two different blocks
+ * is two independent fix-round histories, not one collapsed max. */
+function fixRoundsPerFile(rows) {
+  /** @type {Record<string, number>} */
+  const maxRound = {};
+  for (const r of rows.filter((r) => r.event === 'review.done' && r.file)) {
+    const key = `${r.block}::${r.file}`;
+    maxRound[key] = Math.max(maxRound[key] ?? 0, r.round ?? 0);
+  }
+  return maxRound;
+}
+
+const reviewUnavailableByReason = (rows) =>
+  countBy(
+    rows.filter((r) => r.event === 'review.unavailable'),
+    (r) => r.reason,
+  );
+
+function proofTimePerBlock(rows) {
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const r of rows.filter((r) => r.event === 'proof')) out[r.block] = (out[r.block] ?? 0) + (r.duration_ms ?? 0);
+  return out;
+}
+
+function forecastVsActualLines(rows) {
+  const forecasts = new Map(rows.filter((r) => r.event === 'dispatch').map((r) => [r.block, r.lines]));
+  return rows
+    .filter((r) => r.event === 'block.close' && typeof r.lines_actual === 'number')
+    .map((r) => ({ block: r.block, forecast: forecasts.get(r.block) ?? null, actual: r.lines_actual }));
+}
+
+const blocksStoppedAtL3 = (rows) => rows.filter((r) => r.event === 'block.stop' && r.level === 'L3').map((r) => r.block);
+
+/** Distinct `block` (falling back to `run`, then a shared bucket) values among matching rows —
+ * `overspend`/`l3_fallback` can legitimately be stamped on more than one row for the SAME logical
+ * event (e.g. a session row and its `run.stop`/`block.stop`), so counting rows would double-count. */
+const distinctScopeCount = (rows) => new Set(rows.map((r) => r.block ?? r.run ?? 'unscoped')).size;
+
+const runStopCounts = (rows) => ({
+  overspend: distinctScopeCount(rows.filter((r) => r.overspend === true)),
+  l3Fallback: distinctScopeCount(rows.filter((r) => r.l3_fallback === true)),
+  noEngineStops: rows.filter((r) => r.event === 'run.stop' && r.reason === 'no_engine').length,
+});
+
+/** The exact, ordered set of section keys `buildReport` produces (plan §6.2: "13 sections") —
+ * exported so tests (and `--export`) can assert against ONE source of truth instead of a copy. */
+export const SECTION_NAMES = Object.freeze([
+  'cost_per_block',
+  'lane_distribution',
+  'escalations',
+  's1_calls_per_block',
+  's2_rate',
+  'review_budget',
+  'review_depth_and_findings',
+  'fix_rounds',
+  'review_unavailable',
+  'proof_time',
+  'forecast_vs_actual_lines',
+  'blocks_stopped_at_l3',
+  'run_stop_counts',
+]);
+
+/**
+ * @param {import('./write.mjs').LedgerRow[]} rows - raw ledger rows (`./write.mjs`'s `readAllRows`).
+ * @returns {{sections: Record<string, any>}} exactly the `SECTION_NAMES` sections (plan §6.2).
+ */
+export function buildReport(rows) {
+  const acted = rows.filter((r) => r.source !== 'shadow');
+  const builders = {
+    cost_per_block: costPerBlock,
+    lane_distribution: laneDistribution,
+    escalations: escalationsPerBlock,
+    s1_calls_per_block: s1CallsPerBlock,
+    s2_rate: s2RateAndOverrule,
+    review_budget: reviewBudgetTable,
+    review_depth_and_findings: reviewDepthAndFindings,
+    fix_rounds: fixRoundsPerFile,
+    review_unavailable: reviewUnavailableByReason,
+    proof_time: proofTimePerBlock,
+    forecast_vs_actual_lines: forecastVsActualLines,
+    blocks_stopped_at_l3: blocksStoppedAtL3,
+    run_stop_counts: runStopCounts,
+  };
+  /** @type {Record<string, any>} */
+  const sections = {};
+  for (const name of SECTION_NAMES) sections[name] = builders[name](acted);
+  return { sections };
+}

package/src/ledger/write.mjs

@@ -0,0 +1,279 @@
+/**
+ * The one place that appends to the ledger — JSON Lines, append-only, rotated at 10 MB (plan
+ * §6.4). Later blocks write rows by importing `appendRow` from here (C17 seam rule: this module is
+ * the collaborator B3/B8/B9/... pass around as a parameter, never imported by a batch-mate).
+ *
+ * Rotation is race-safe two ways (fix round 1, MAJOR): (1) a per-slug, per-process promise chain
+ * serializes every `appendRow` for the same slug, so two calls in THIS process never interleave;
+ * (2) the rotated name is claimed with `link()` + `unlink()`, not `rename()` — `link` fails atomically
+ * with EEXIST if the candidate name is taken, so even a SECOND process racing on the same slug
+ * can't silently clobber another rotation (a plain `rename` onto an existing path succeeds and
+ * silently destroys whatever was there). Fix round 2 closes the remaining gap in that pair: when
+ * TWO racers both successfully `link()` to different candidate names before either `unlink()`s the
+ * source (both still see the source as present), the loser now removes its OWN candidate instead
+ * of leaving two hardlinks to identical data around (which `readAllRows` would otherwise count
+ * twice) — see `claimRotatedName`'s second `catch`.
+ */
+
+import { appendFile, link, mkdir, open, readdir, readFile, stat, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { ledgerDir, ledgerPath } from './paths.mjs';
+
+/** @typedef {Record<string, any>} LedgerRow - a ledger row is intentionally schema-free in 0.1. */
+
+const DEFAULT_ROTATE_AT_BYTES = 10 * 1024 * 1024;
+
+const hasTokens = (row) => typeof row.tokens_in === 'number' || typeof row.tokens_out === 'number';
+const hasCost = (row) => typeof row.cost_usd === 'number';
+
+/**
+ * Stamp `ts` and make `tokens_source`/`cost_source` ALWAYS-present keys (plan §6.1: "Tokens are
+ * facts, dollars are estimates"). Neither defaults to a non-null value unconditionally: an unset
+ * `tokens_source` becomes `'estimated'` ONLY when the row carries a token count, and stays `null`
+ * (present, not omitted) otherwise; an unset `cost_source` becomes `'estimated'` ONLY when the row
+ * carries `cost_usd` (0.1's only cost source is the static price table, `./prices.mjs`), and stays
+ * `null` otherwise. The acceptance bar is "the key exists on every row", not "every row has a
+ * non-null value" — a `run.start` row with neither field is `{tokens_source: null, cost_source: null}`.
+ */
+function normalizeRow(row) {
+  if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+    throw new TypeError('appendRow: row must be a plain object');
+  }
+  if (typeof row.event !== 'string' || row.event.length === 0) {
+    throw new TypeError('appendRow: row.event must be a non-empty string');
+  }
+  return {
+    ...row,
+    ts: row.ts ?? new Date().toISOString(),
+    tokens_source: row.tokens_source ?? (hasTokens(row) ? 'estimated' : null),
+    cost_source: row.cost_source ?? (hasCost(row) ? 'estimated' : null),
+  };
+}
+
+/**
+ * Claim `<base>.<n>.jsonl` for `n = 1, 2, ...` atomically via `link()` (hardlink the still-full
+ * file under the rotated name, then unlink the original) instead of `rename()`.
+ * @param {string} file @param {string} dir @param {string} base
+ */
+export async function claimRotatedName(file, dir, base) {
+  let n = 1;
+  for (;;) {
+    const candidate = path.join(dir, `${base}.${n}.jsonl`);
+    try {
+      await link(file, candidate);
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        // Another racer already claimed THIS candidate name — try the next one.
+        n += 1;
+        continue;
+      }
+      if (err.code === 'ENOENT') return; // `file` vanished before we could link it — a racer already rotated it out
+      throw err;
+    }
+    try {
+      await unlink(file);
+      return;
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // We successfully linked `candidate` to the source's data, but ANOTHER racer's unlink beat
+        // ours to removing the source — that racer's own candidate is the one that "owns" this
+        // rotation. Ours is now a redundant hardlink to the identical data; remove it so
+        // `readAllRows` doesn't read (and count) the same rows twice via two different filenames.
+        await unlink(candidate).catch(() => {});
+        return;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Rotate `file` to the next free `<base>.<n>.jsonl` once it reaches `rotateAtBytes`. Rotation
+ * only — torn-final-line handling lives in `truncateTornTail`.
+ * @param {string} file @param {number} rotateAtBytes
+ */
+async function rotateIfNeeded(file, rotateAtBytes) {
+  let size;
+  try {
+    size = (await stat(file)).size;
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  if (size < rotateAtBytes) return;
+  await claimRotatedName(file, path.dirname(file), path.basename(file, '.jsonl'));
+}
+
+/**
+ * Recover from a torn final line (a crash or an overlapping write mid-append) by TRUNCATING the
+ * file back to the end of its last COMPLETE line, discarding the incomplete fragment — it was
+ * never a finished row, so there is nothing to preserve. This runs before every append, not just
+ * once: merely prefixing the next write with `\n` (isolating, not discarding, the fragment) fixes
+ * the FIRST torn write but leaves the fragment sitting in the middle of the file from then on,
+ * which `parseLines` correctly treats as real corruption and throws on — silently re-breaking the
+ * exact failure this recovery exists to prevent.
+ *
+ * Fix round 3: everything here is measured in BYTES. The cut point used to come from
+ * `lastIndexOf('\n')` on a UTF-8-DECODED string (UTF-16 code units) and was then passed to
+ * `truncate()` (bytes) — any non-ASCII row (`información`, an emoji) made the byte offset larger
+ * than the character offset, so the file was cut too early: complete rows lost and a fragment
+ * left mid-file. The common case (file ends in `\n`) now reads ONE byte, not the whole file; the
+ * full read happens only when the file really ends mid-line.
+ *
+ * Single-writer recovery: the per-slug chain serializes this process only. If the size changes
+ * between the read and the truncate (another process appended), the truncate is skipped rather
+ * than cutting that process's row; the next append retries the recovery.
+ * @param {string} file
+ */
+async function truncateTornTail(file) {
+  let handle;
+  try {
+    handle = await open(file, 'r+');
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  try {
+    const { size } = await handle.stat();
+    if (size === 0) return;
+    const last = Buffer.alloc(1);
+    await handle.read(last, 0, 1, size - 1);
+    if (last[0] === 0x0a) return; // ends with '\n' — nothing torn
+    const buf = Buffer.alloc(size);
+    const { bytesRead } = await handle.read(buf, 0, size, 0);
+    const cleanBytes = buf.subarray(0, bytesRead).lastIndexOf(0x0a) + 1; // 0 when no complete line
+    if ((await handle.stat()).size !== size) return; // a concurrent writer moved the tail — leave it
+    await handle.truncate(cleanBytes);
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Per-slug promise chain (in-process only — `claimRotatedName`'s `link`/`unlink` pair is what
+ * protects against a SECOND process). A failed task never wedges the chain: the stored promise
+ * always resolves, while the caller's own promise still rejects with the task's real error.
+ * @type {Map<string, Promise<any>>}
+ */
+const chains = new Map();
+
+/** @param {string} slug @param {() => Promise<any>} task */
+function enqueue(slug, task) {
+  const previous = (chains.get(slug) ?? Promise.resolve()).catch(() => {});
+  const result = previous.then(task);
+  chains.set(slug, result.catch(() => {}));
+  return result;
+}
+
+/**
+ * @param {LedgerRow} row - must carry a non-empty `event`; everything else is caller-defined.
+ * @param {{slug: string, rotateAtBytes?: number}} opts - `rotateAtBytes` defaults to 10 MB; tests
+ *   pass a tiny value to prove rotation without writing 10 MB of fixture data.
+ * @returns {Promise<LedgerRow>} the normalized row that was written.
+ */
+export async function appendRow(row, opts) {
+  // `async` (not a plain function returning a Promise) so a synchronous validation throw here
+  // — before the queue or disk are ever touched — still comes back as a REJECTED promise, not an
+  // exception thrown out of the call itself; a caller that always does
+  // `await appendRow(...)`/`assert.rejects(() => appendRow(...))` must see one consistent shape.
+  const { slug, rotateAtBytes = DEFAULT_ROTATE_AT_BYTES } = opts ?? {};
+  const normalized = normalizeRow(row); // validate before ever touching the queue/disk
+  ledgerPath(slug); // validates slug BEFORE mkdir/enqueue run at all — a bad slug must create nothing
+  if (!Number.isFinite(rotateAtBytes) || rotateAtBytes <= 0) {
+    throw new RangeError(`appendRow: rotateAtBytes must be a finite number > 0, got ${rotateAtBytes}`);
+  }
+  return enqueue(slug, async () => {
+    await mkdir(ledgerDir(), { recursive: true });
+    const file = ledgerPath(slug);
+    await rotateIfNeeded(file, rotateAtBytes);
+    await truncateTornTail(file);
+    await appendFile(file, `${JSON.stringify(normalized)}\n`, 'utf8');
+    return normalized;
+  });
+}
+
+/**
+ * Parse JSONL text tolerant of a TORN final line (a crash or an overlapping write mid-append can
+ * leave the last line incomplete) — that one line is skipped silently. A malformed line anywhere
+ * else is real corruption and throws, rather than silently dropping data from the middle of the
+ * file.
+ * @param {string} text
+ * @returns {LedgerRow[]}
+ */
+function parseLines(text) {
+  const lines = text.split('\n').filter((line) => line.length > 0);
+  const rows = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    try {
+      rows.push(JSON.parse(lines[i]));
+    } catch (err) {
+      if (i === lines.length - 1) continue; // torn final line — benign, skip
+      throw err; // corruption in the middle — surface it
+    }
+  }
+  return rows;
+}
+
+/**
+ * Read and parse the CURRENT (non-rotated) ledger file for `slug` only. Missing file ⇒ `[]`. Most
+ * callers want `readAllRows` instead — this is the low-level primitive rotation tests use to
+ * inspect one file directly.
+ * @param {string} slug
+ * @returns {Promise<LedgerRow[]>}
+ */
+export async function readRows(slug) {
+  let text;
+  try {
+    text = await readFile(ledgerPath(slug), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return parseLines(text);
+}
+
+/**
+ * Read and parse EVERY row for `slug`, across rotated files (`<slug>.1.jsonl`, `<slug>.2.jsonl`,
+ * ...) and the live file, oldest first. Rotation moves the oldest rows out of `<slug>.jsonl`, not
+ * out of the ledger — a caller building a report, calibration table, or `--scan-git` idempotency
+ * check must read the full history, or it silently drops everything before the last rotation.
+ *
+ * Matches rotated filenames EXACTLY (`^<escaped-slug>\.\d+\.jsonl$`), not by a bare `startsWith`
+ * prefix — `SLUG_PATTERN` (`paths.mjs`) forbids `.` in a slug today, so slug `proj` and a
+ * hypothetical slug `proj.x` can never collide in practice, but the exact match keeps that true by
+ * construction rather than by a coincidence of the current pattern (fix round 2).
+ * @param {string} slug
+ * @returns {Promise<LedgerRow[]>}
+ */
+export async function readAllRows(slug) {
+  ledgerPath(slug); // validates slug (throws TypeError on '..', '/', empty, etc.) — return value unused here
+  const dir = ledgerDir();
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const escapedSlug = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const rotatedExact = new RegExp(`^${escapedSlug}\\.(\\d+)\\.jsonl$`);
+  const rotated = entries
+    .map((f) => ({ f, m: rotatedExact.exec(f) }))
+    .filter((x) => x.m)
+    .map((x) => ({ f: x.f, n: Number(x.m[1]) }))
+    .sort((a, b) => a.n - b.n)
+    .map((x) => x.f);
+
+  const rows = [];
+  for (const file of [...rotated, `${slug}.jsonl`]) {
+    let text;
+    try {
+      text = await readFile(path.join(dir, file), 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw err;
+    }
+    rows.push(...parseLines(text));
+  }
+  return rows;
+}