bareloop 0.2.0 → 0.4.0

package/src/job.js

@@ -24,6 +24,33 @@ export const CLASSES = Object.freeze(['hard', 'soft', 'hitl']);
 /** the hierarchy: which verdict classes a close type may claim (PRD §7) */
 export const CLASS_BY_CLOSE = Object.freeze({ predicate: Object.freeze(['hard']), gold: Object.freeze(['hard']), rubric: Object.freeze(['soft']), hitl: Object.freeze(['hitl']) });
 export const GOLD_COMPARE = Object.freeze(['exact', 'json-equal']);
+/** step middle modes (2b): text = single-target artifact; tools = Gate-governed file tools */
+export const STEP_MODES = Object.freeze(['text', 'tools']);
+/** the tool grant menu (2b interview #1): read/grep/write, plus the two litectx
+ * RETRIEVAL verbs (F19) — `run` stays locked-but-listed; a spec requesting it
+ * reds, and that red IS the request-red evidence admission waits on (curation
+ * doctrine, PRD F2).
+ *
+ * `recall`/`get` are READ-ONLY BY CONSTRUCTION, not by promise: `recall` returns
+ * pointers (path/symbol/line-range, no bodies) and `get` trades ONE pointer for
+ * ONE chunk — it refuses any range that is not a chunk boundary, so it cannot be
+ * widened into a whole-file read, and it is content-hash gated (a drifted file
+ * throws rather than serving a stale body). Admitting them does NOT weaken the
+ * `run` lock: the worker still cannot execute anything, so it still cannot run
+ * its own close (the arbiter). F19: `shell_read` starts at byte ZERO and cannot
+ * seek, so a pointer was INERT — the worker paged 1.37 MB of source through
+ * context to reach 8 lines. The ranged read is the pager.
+ *
+ * `edit` (BA-13, bare-agent 0.29.0) is the anchored exact-once replace — a
+ * WRITE-class verb judged by the SAME writeScope fence as `write` (bareguard
+ * action type 'edit'). Admitted because whole-file rewrite is measurably
+ * unreliable at size (F31: 4 of 5 big-file whole-writes broke the tree) and
+ * taxes output tokens ∝ file size. It admits no execution either. */
+export const TOOL_MENU = Object.freeze(['read', 'grep', 'write', 'edit', 'recall', 'get']);
+/** locked-but-listed tools: real capabilities deliberately outside the grant
+ * menu. Requesting one is a DISTINCT `request-red` (module 4) — the ledger
+ * counts admission demand, and a generic invalid-value would bury it as a typo. */
+export const LOCKED_TOOLS = Object.freeze(['run']);
 export const CADENCE_UNITS = Object.freeze(['hour', 'day', 'week']);
 export const PROVIDERS = Object.freeze(['anthropic-api']); // SP-2: API-first; local deferred (PRD §5/§8)
 /** V3 environment label: declared keys only — every field is a lineage-key
@@ -34,14 +61,14 @@ const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'c
 /** exact field set per close type — anything else is an unknown-field red
  * (freeform code, script bodies, and minting claims all land there) */
 const CLOSE_FIELDS = {
-  predicate: ['type', 'cmd', 'expect'],
+  predicate: ['type', 'cmd', 'expect', 'judged', 'gapKeep'],
   gold: ['type', 'expected', 'compare'],
   rubric: ['type', 'criteria'],
   hitl: ['type', 'prompt'],
 };
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
-/** @typedef {{code: string, path: string, detail?: string}} Red */
+/** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red — `verb` rides request-reds as structured data (the ledger keys on it, never on prose) */
 
 /**
  * Validate an operator-owned job spec (`schema: "job-v1"`). Never throws on
@@ -139,7 +166,33 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
       const at = `steps.${i}`;
       if (!isObj(s)) { red('invalid-value', at, 'step must be an object'); return; }
       for (const key of Object.keys(s)) {
-        if (!['id', 'close', 'class'].includes(key)) red('unknown-field', `${at}.${key}`);
+        if (!['id', 'close', 'class', 'mode', 'tools'].includes(key)) red('unknown-field', `${at}.${key}`);
+      }
+      // mode/tools — the spec-side tool grant (2b decision #2: the human job
+      // spec owns mode + menu; the drafted config cannot express either)
+      const isHitl = isObj(s.close) && s.close.type === 'hitl';
+      if ((s.mode !== undefined || s.tools !== undefined) && isHitl) {
+        red('invalid-value', `${at}.mode`, 'hitl steps run no loop — mode/tools do not apply');
+      } else {
+        if (s.mode !== undefined && !STEP_MODES.includes(s.mode)) red('invalid-value', `${at}.mode`, STEP_MODES.join('|'));
+        if (s.tools !== undefined) {
+          if (s.mode !== 'tools') red('invalid-value', `${at}.tools`, 'a tool grant requires mode "tools" — a grant without the mode is incoherent');
+          else if (!(Array.isArray(s.tools) && s.tools.length > 0
+                     && s.tools.every((/** @type {unknown} */ t) => typeof t === 'string')
+                     && new Set(s.tools).size === s.tools.length)) {
+            red('invalid-value', `${at}.tools`, `non-empty unique subset of ${TOOL_MENU.join('|')}`);
+          } else {
+            // locked-but-listed asks red DISTINCTLY: request-red is the admission
+            // evidence the ledger tallies (two-red routing); a typo stays invalid-value
+            for (const t of s.tools.filter((/** @type {string} */ t) => LOCKED_TOOLS.includes(t))) {
+              // verb as a structured field: the ledger keys admission demand on it;
+              // parsing it back out of the prose detail would break on a rewording
+              reds.push({ code: 'request-red', path: `${at}.tools`, verb: t, detail: `"${t}" is locked-but-listed — this red IS the admission evidence, never a grant; granted menu: ${TOOL_MENU.join('|')}` });
+            }
+            const unknown = s.tools.filter((/** @type {string} */ t) => !TOOL_MENU.includes(t) && !LOCKED_TOOLS.includes(t));
+            if (unknown.length) red('invalid-value', `${at}.tools`, `unknown tool(s) ${unknown.join(', ')} — menu: ${TOOL_MENU.join('|')}`);
+          }
+        }
       }
       if (!isNonEmptyString(s.id) || !SLUG_RE.test(s.id)) red('invalid-value', `${at}.id`, 'kebab-case slug');
       else if (seen.has(s.id)) red('duplicate-id', `${at}.id`, s.id);
@@ -157,7 +210,70 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
       // per-type contracts — fixed menus only
       if (close.type === 'predicate') {
         if (!isNonEmptyString(close.cmd)) red('missing-required', `${at}.close.cmd`);
+        // the runner executes cmd as whitespace-split argv with NO shell: quote
+        // characters imply shell semantics the split cannot honor — honest
+        // refusal beats silent misparse (N2 design default)
+        else if (/["']/.test(close.cmd)) red('invalid-value', `${at}.close.cmd`, 'quote characters are inexpressible: cmd runs as whitespace-split argv, no shell');
+        else if (close.cmd !== close.cmd.trim()) red('invalid-value', `${at}.close.cmd`, 'leading/trailing whitespace — argv splits on whitespace and an empty argv[0] cannot spawn; honest refusal beats a silent misparse');
         if (!Number.isInteger(close.expect)) red('invalid-value', `${at}.close.expect`, 'integer exit code');
+        // The judgment-rendered signal (PRD v1.11, optional). Exit code alone
+        // cannot separate "the suite ran and failed" from "the suite crashed at
+        // load" — they are byte-identical at the seam, and against `node --test`
+        // so are the raw counts (a crashed file is reported as ONE failing test).
+        // So the signal is a FLOOR, not a zero-check: a close declares how many
+        // things it must judge before its exit code means anything at all.
+        if (close.judged !== undefined) {
+          const j = close.judged;
+          if (!isObj(j)) red('invalid-value', `${at}.close.judged`, 'object {pattern, min} — proof the close actually judged something');
+          else {
+            for (const key of Object.keys(j)) {
+              if (!['pattern', 'min'].includes(key)) red('unknown-field', `${at}.close.judged.${key}`);
+            }
+            if (!isNonEmptyString(j.pattern)) red('missing-required', `${at}.close.judged.pattern`, 'regex over the close output with ONE capture group yielding the count');
+            else {
+              let groups = 0;
+              try {
+                // `p|` always matches the empty string, so exec() returns an array
+                // whose length is 1 + the number of capture groups — the only way
+                // to count groups without executing the pattern against real output.
+                groups = (new RegExp(`${j.pattern}|`).exec('')?.length ?? 1) - 1;
+              } catch {
+                red('invalid-value', `${at}.close.judged.pattern`, 'must compile as a RegExp');
+                groups = -1;
+              }
+              // A pattern with no capture group extracts nothing, so EVERY close
+              // would read as crashed — a dead arbiter that reds forever. Red the
+              // spec, not every run.
+              if (groups === 0) red('invalid-value', `${at}.close.judged.pattern`, 'no capture group — the count is read from group 1, so this pattern would crash every close');
+              // More than one is the same defect wearing a subtler hat: runClose
+              // reads group 1 ONLY, so an alternation whose other branch carries
+              // the count leaves group 1 undefined → NaN → judgedCount null →
+              // an exit-0 GREEN stamped 'crashed' (a fake crash, the mirror of
+              // the fake green this floor exists to catch). Alternation stays
+              // fully expressible with non-capturing branches: `(?:a|b) (\d+)`.
+              else if (groups > 1) red('invalid-value', `${at}.close.judged.pattern`, `${groups} capture groups — the count is read from group 1 only; use exactly one capture group and non-capturing (?:…) branches`);
+            }
+            if (!Number.isInteger(j.min) || j.min < 1) {
+              red('invalid-value', `${at}.close.judged.min`, 'integer >= 1 — a floor of 0 is satisfied by judging nothing, which is the check it is meant to make');
+            }
+          }
+        }
+        // The kept-failures pattern (F28, optional). ralph's gap bound head/tail-
+        // elides a large close stream, and a big TAP suite prints its `not ok`
+        // lines in the MIDDLE — so the failing-test NAMES (the causal navigation
+        // input the worker runs on) were deleted in transit and the worker was
+        // told "5 fail" and never WHICH. gapKeep is a regex SOURCE whose matching
+        // lines are PRESERVED in the gap in addition to head+tail. Same discipline
+        // as judged.pattern: a non-empty string that must compile as a RegExp, or
+        // it is a spec red before any tokens burn (reds-before-tokens) — an invalid
+        // keep pattern must never surface as a runtime crash inside the arbiter.
+        if (close.gapKeep !== undefined) {
+          if (!isNonEmptyString(close.gapKeep)) red('invalid-value', `${at}.close.gapKeep`, 'regex source string — lines matching it survive the gap bound (F28)');
+          else {
+            try { new RegExp(close.gapKeep, 'm'); }
+            catch { red('invalid-value', `${at}.close.gapKeep`, 'must compile as a RegExp'); }
+          }
+        }
       } else if (close.type === 'gold') {
         if (close.expected === undefined) red('missing-required', `${at}.close.expected`);
         if (!GOLD_COMPARE.includes(close.compare)) red('invalid-value', `${at}.close.compare`, GOLD_COMPARE.join('|'));

package/src/ledger.js

@@ -0,0 +1,266 @@
+// The upstream ledger (module 4) — reactive lib/primitive incident monitoring.
+// Design record: docs/plans/2026-07-11-upstream-ledger-design.md (adaptlearn
+// POC'd spec) + its 2026-07-13 addendum: the bareloop event mapping. One
+// append-only JSONL both the consumer (the panel, N6) and the maintainer read;
+// the A1/A2/A3 upstream-ask flow, mechanized — evidence in, human judgment out.
+//
+// Doctrine this encodes:
+// - Spines stay ground truth; the ledger is DERIVED and reconstructible
+//   (delete it, re-run the collector over the corpus: same fold). Current
+//   state is a fold, never a mutation — occurrence rows are cumulative deltas.
+// - Idempotence is the collector contract: pass the FULL spine corpus each
+//   time; counts are totals computed from what you pass, and a row appends
+//   only when a key is new or its count grew.
+// - suggestedAsk is a template seed for UPSTREAM-ASKS, never auto-filed —
+//   filing stays human (the arbiter line, maintainer form). Status rows
+//   (open → filed → fixed → consumed) are human-appended; this module only
+//   folds them.
+// - capability-gap (cap-halt + request-red in one spine) ships but is dormant
+//   in N2: a request-red is a job-validation red today, so the job never runs.
+//   It goes live when in-loop admission lands (2b deferral).
+
+import { readFileSync, appendFileSync, existsSync } from 'node:fs';
+import { basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import { VERBS } from './validate.js';
+
+/** severity order, worst-first (the fold's display order; frequency ranks within) */
+export const LEDGER_CLASSES = Object.freeze([
+  'silent-degradation', // A3: a degraded primitive throws nothing — only the known-answer smoke reds it
+  'runtime-red',        // a store/verb threw at runtime
+  'provider-red',       // the provider path failed (bare-agent territory)
+  'pricing-red',        // F6: a result carried no priced cost — the cap went blind
+  'capability-gap',     // a locked verb was requested AND the run cap-halted
+  'broken-close',       // consumer-attributed: the arbiter itself cannot run
+  'request-red',        // admission demand for a locked-but-listed verb
+  'retention-red',      // litectx retention failed on-green (green stands, mints nothing)
+  'config-red',         // drafting friction — bareloop's own schema/prompt indicted
+]);
+
+/** @typedef {{spine: string, seq: number}} Sample */
+/** @typedef {{key: string, class: string, lib: string, verb: string, sig: string, detail: string, sample: Sample}} Occurrence */
+/** @typedef {{key: string, lib: string, verb: string, class: string, sig: string, detail: string, occurrences: number, samples: Sample[], suggestedAsk: string, status: string, ref?: string}} FoldEntry */
+
+const DETAIL_MAX = 300;
+/** paths and numbers are run-local noise: normalize them so the same bug
+ * across runs dedupes and distinct bugs in one verb don't merge */
+const normalizeDetail = (/** @type {unknown} */ s) => String(s ?? '')
+  .replace(/(?:~|\.{1,2})?\/[^\s"'`):,]+/g, '<path>')
+  .replace(/\d+(?:\.\d+)?/g, '#')
+  .slice(0, DETAIL_MAX);
+const sigOf = (/** @type {string} */ normalized) => createHash('sha256').update(normalized).digest('hex').slice(0, 8);
+
+const VERB_RE = new RegExp(`\\b(${VERBS.join('|')})\\b`);
+const QUOTED_VERB_RE = /"([a-z0-9-]+)"/;
+
+/** The deliberate escalation exclusions as a RUNTIME set, not prose: anything
+ * outside {classified} ∪ {this} is an unmapped class and gets counted (see the
+ * escalation branch). Kept beside the doc comment on classifyIncidents, which
+ * explains WHY each one classifies to nothing. */
+const EXCLUDED_ESCALATIONS = new Set([
+  'cap-halt',           // a budget story, not a lib bug
+  'gate-red',           // governance working as intended
+  'smoke-red',          // already counted via primitive-smoke
+  'hitl-close',         // by design: a human is the close
+  'close-unsupported',  // honest refusal, by design
+  'close-timeout',      // close-verdict reds: the arbiter's own named terminals
+  'close-killed',       // (F17) — operator/environment stories, never a suite lib
+  'close-crashed',
+]);
+
+/** suggestedAsk templates — seeds for UPSTREAM-ASKS entries, never auto-filed */
+const ASKS = /** @type {Record<string, (o: {lib: string, verb: string, detail: string}) => string>} */ ({
+  'silent-degradation': (o) => `${o.lib}: \`${o.verb}\` failed its known-answer smoke — ${o.detail}`,
+  'runtime-red': (o) => `${o.lib}: \`${o.verb}\` threw at runtime — ${o.detail}`,
+  'provider-red': (o) => `bare-agent: the provider path failed — ${o.detail}`,
+  'pricing-red': (o) => `bare-agent: a provider result carried no priced cost (unpriced is never free, F6) — ${o.detail}`,
+  'capability-gap': (o) => `bare-agent: locked \`${o.verb}\` was requested and the run cap-halted — admission candidate`,
+  'broken-close': (o) => `job owner: the close itself cannot run — ${o.detail}`,
+  'request-red': (o) => `admission: locked \`${o.verb}\` requested by a job spec — demand evidence, never a grant`,
+  'retention-red': (o) => `litectx: on-green retention failed — ${o.detail}`,
+  'config-red': (o) => `bareloop: drafting friction at ${o.verb} — ${o.detail}`,
+});
+
+/**
+ * Classify one spine's events into incident occurrences (the design table in
+ * bareloop vocabulary). Deliberate exclusions — bare cap-halt (a budget story),
+ * close-verdict reds and artifact-red (worker stories, the §5b line), gate-red
+ * (governance working as intended), pr-red (operator environment, not a suite
+ * lib), smoke-red escalations (already counted via primitive-smoke), hitl-close
+ * and close-unsupported (by design) — classify to nothing.
+ * @param {any[]} events one spine's parsed events, in seq order
+ * @param {{spine?: string}} [opts] spine id stamped into samples
+ * @returns {Occurrence[]}
+ */
+export function classifyIncidents(events, { spine = 'spine' } = {}) {
+  /** @type {Occurrence[]} */
+  const occs = [];
+  let capHalted = false;
+  /** @type {(ev: any, cls: string, lib: string, verb: string, rawDetail: unknown) => void} */
+  const add = (ev, cls, lib, verb, rawDetail) => {
+    const detail = normalizeDetail(rawDetail);
+    const sig = sigOf(detail);
+    occs.push({ key: `${lib}:${verb}:${cls}:${sig}`, class: cls, lib, verb, sig, detail, sample: { spine, seq: ev.seq } });
+  };
+
+  for (const ev of events) {
+    if (ev.type === 'primitive-smoke' && ev.ok === false) {
+      add(ev, 'silent-degradation', ev.primitive ?? 'unknown', 'smoke', ev.detail);
+    } else if (ev.type === 'retention-red') {
+      add(ev, 'retention-red', 'litectx', 'remember', ev.detail);
+    } else if (ev.type === 'cap-halt') {
+      capHalted = true; // not an incident alone — see capability-gap below
+    } else if (ev.type === 'config-red') {
+      // in bareloop the config is model-drafted against OUR schema description:
+      // a repeated signature indicts the drafting prompt/schema, i.e. bareloop
+      add(ev, 'config-red', 'bareloop', String(ev.path ?? 'config').split('.')[0] || 'config', `${ev.code} at ${ev.path}: ${ev.detail ?? ''}`);
+    } else if (ev.type === 'job-red' && ev.code === 'request-red') {
+      // the structured field wins; the prose-quoted verb stays as the fallback
+      // for spines written before the field existed
+      add(ev, 'request-red', 'bare-agent', ev.verb ?? (String(ev.detail ?? '').match(QUOTED_VERB_RE) ?? [])[1] ?? 'unknown', ev.detail);
+    } else if (ev.type === 'escalation') {
+      if (ev.category === 'broken-close') {
+        add(ev, 'broken-close', 'consumer', 'close', ev.detail);
+      } else if (ev.category === 'provider-red') {
+        // the runner's transport-throw seam (design table: retry-exhausted seam)
+        add(ev, 'provider-red', 'bare-agent', 'provider', ev.detail ?? ev.decision);
+      } else if (ev.category === 'pricing-red') {
+        add(ev, 'pricing-red', 'bare-agent', 'pricing', ev.decision ?? ev.detail);
+      } else if (ev.category === 'interpreter-red') {
+        // the design split: a store verb in the detail → runtime-red (verb→lib
+        // map); a worker-loop/provider failure → provider-red; neither is
+        // still counted (runtime-red, lib unknown) — never silently dropped
+        const detail = String(ev.detail ?? '');
+        // The STRUCTURED field wins, prose stays the fallback for spines written
+        // before it existed (the request-red contract above). Prose alone
+        // misfiled deterministically: interpret.js prefixes every worker-loop
+        // error with "worker loop:", and the verb sniff ran first, so a
+        // bare-agent transport failure whose text merely said "recall" was
+        // billed to litectx — wrong upstream asked, real regression hidden.
+        if (ev.lib === 'bare-agent') add(ev, 'provider-red', 'bare-agent', 'provider', detail);
+        else if (ev.lib === 'litectx') add(ev, 'runtime-red', 'litectx', (detail.match(VERB_RE) ?? [])[1] ?? 'store', detail);
+        else {
+          const verb = (detail.match(VERB_RE) ?? [])[1];
+          if (verb || /\blitectx\b/.test(detail)) add(ev, 'runtime-red', 'litectx', verb ?? 'store', detail);
+          else if (/worker loop|provider/i.test(detail)) add(ev, 'provider-red', 'bare-agent', 'provider', detail);
+          else add(ev, 'runtime-red', 'unknown', 'middle', detail);
+        }
+      } else if (!EXCLUDED_ESCALATIONS.has(String(ev.category))) {
+        // The exclusions above are DELIBERATE and now executable (see the set):
+        // a category that is neither classified nor named there is a NEW or
+        // renamed failure class, and the four-way chain used to drop it into
+        // exactly the same silence as a deliberate skip — a whole class could
+        // leave the ledger with no red, no count, nothing to notice. Counted
+        // against bareloop: a stale emit→classify mapping is OUR bug.
+        add(ev, 'runtime-red', 'bareloop', 'escalation', `unclassified escalation category "${ev.category}": ${ev.detail ?? ev.decision ?? ''}`);
+      }
+    }
+  }
+
+  if (capHalted) {
+    // capability-gap: the run hit its cap in a spine that also asked for a
+    // locked verb — the strongest admission evidence there is (design table)
+    for (const verb of new Set(occs.filter((o) => o.class === 'request-red').map((o) => o.verb))) {
+      const halt = events.find((e) => e.type === 'cap-halt');
+      add(halt, 'capability-gap', 'bare-agent', verb, `locked "${verb}" requested and the run cap-halted`);
+    }
+  }
+  return occs;
+}
+
+/**
+ * Fold ledger rows to current state — latest cumulative count per key, latest
+ * human-appended status riding on top (default 'open'). A status row for a key
+ * with no incident row still folds (occurrences 0): a human note must never
+ * silently vanish.
+ * @param {any[]} rows parsed ledger rows, in seq order
+ * @returns {Record<string, FoldEntry>}
+ */
+export function foldLedger(rows) {
+  /** @type {Record<string, FoldEntry>} */
+  const fold = {};
+  for (const row of rows) {
+    if (row.type === 'lib-incident') {
+      const prev = fold[row.key];
+      const { seq: _seq, ts: _ts, type: _type, ...fields } = row;
+      // incident fields refresh; a human-appended status must ride on top
+      fold[row.key] = { ...fields, status: prev?.status ?? 'open', ...(prev?.ref !== undefined ? { ref: prev.ref } : {}) };
+    } else if (row.type === 'lib-incident-status') {
+      /** @type {FoldEntry} */
+      const prev = fold[row.key] ?? { key: row.key, lib: 'unknown', verb: 'unknown', class: 'unknown', sig: '', detail: '', occurrences: 0, samples: [], suggestedAsk: '', status: 'open' };
+      fold[row.key] = { ...prev, status: row.status, ref: row.ref };
+    }
+  }
+  return fold;
+}
+
+const SAMPLES_MAX = 5;
+
+/**
+ * Compute the append-only delta rows: group occurrences by key; a row is due
+ * only when the key is new or its corpus total grew past the folded count.
+ * detail is first-seen (the fold's wins); samples are the corpus's first few.
+ * @param {Record<string, FoldEntry>} fold current ledger state
+ * @param {Occurrence[]} occurrences the FULL corpus's occurrences
+ * @returns {object[]} lib-incident rows, unstamped (no seq/ts)
+ */
+export function ledgerDeltas(fold, occurrences) {
+  /** @type {Map<string, Occurrence[]>} */
+  const byKey = new Map();
+  for (const o of occurrences) {
+    const group = byKey.get(o.key) ?? [];
+    group.push(o);
+    byKey.set(o.key, group);
+  }
+  const rows = [];
+  for (const [key, group] of byKey) {
+    const prev = fold[key];
+    if (prev && group.length <= prev.occurrences) continue;
+    const first = group[0];
+    const detail = prev?.detail || first.detail;
+    rows.push({
+      type: 'lib-incident', key, lib: first.lib, verb: first.verb, class: first.class, sig: first.sig,
+      detail, occurrences: group.length, samples: group.slice(0, SAMPLES_MAX).map((o) => o.sample),
+      suggestedAsk: ASKS[first.class]({ lib: first.lib, verb: first.verb, detail }),
+    });
+  }
+  return rows;
+}
+
+/** @param {string} file @returns {any[]} */
+function readJsonl(file) {
+  const rows = [];
+  const lines = readFileSync(file, 'utf8').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    try { rows.push(JSON.parse(lines[i])); } catch {
+      // corruption in a derived file is never papered over — rebuild from spines
+      throw new Error(`${file} line ${i + 1}: malformed JSONL`);
+    }
+  }
+  return rows;
+}
+
+/**
+ * The collector: read the ledger, classify the FULL spine corpus, append the
+ * deltas (spine conventions: type first, ts stamped last, seq continuing
+ * monotonically across appends). Idempotent over the same corpus; the CLI
+ * wrapping this lands at N5, the panel reads the same file at N6.
+ * @param {{ledgerFile: string, spineFiles: string[]}} o spineFiles: the corpus
+ *   (pass ALL of it each time — counts are totals, not increments)
+ * @returns {{appended: object[], fold: Record<string, FoldEntry>}}
+ */
+export function updateLedger({ ledgerFile, spineFiles }) {
+  const rows = existsSync(ledgerFile) ? readJsonl(ledgerFile) : [];
+  const occurrences = spineFiles.flatMap((f) => classifyIncidents(readJsonl(f), { spine: basename(f).replace(/\.jsonl$/, '') }));
+  const deltas = ledgerDeltas(foldLedger(rows), occurrences);
+  let seq = rows.reduce((m, r) => Math.max(m, r.seq ?? 0), 0);
+  const appended = deltas.map((row) => {
+    /** @type {Record<string, unknown>} */
+    const stamped = { ...row, seq: ++seq };
+    stamped.ts = new Date().toISOString();
+    appendFileSync(ledgerFile, JSON.stringify(stamped) + '\n');
+    return stamped;
+  });
+  return { appended, fold: foldLedger(rows.concat(appended)) };
+}