bareloop 0.1.0 → 0.3.0

package/src/validate.js

@@ -11,10 +11,24 @@
 
 import { COMPRESS_LEVELS, KINDS, WRITE_KINDS } from 'litectx';
 
-export const LOOP_SHAPES = ['refine', 'plan'];
-export const SLOTS = ['before-attempt', 'after-red', 'on-green'];
-export const VERBS = ['recall', 'compress', 'stash', 'remember'];
+export const LOOP_SHAPES = Object.freeze(['refine', 'plan']);
+export const SLOTS = Object.freeze(['before-attempt', 'after-red', 'on-green']);
+export const VERBS = Object.freeze(['recall', 'compress', 'stash', 'remember']);
 const TOP_FIELDS = ['schema', 'loop', 'memory', 'hooks', 'gate', 'escalation'];
+// Unknown-field guard, PER SECTION — not just at the top (F17). The arbiter
+// split is guarded "both directions by inexpressibility": the drafted config
+// must be UNABLE to say certain things. A guard that stops at the top level
+// does not deliver that — `gate: { judged: {...} }` (the close's own honesty
+// check) validated green, as would `gate.maxCostUsd`. Nothing consumed those
+// keys, so nothing broke; the guarantee is that nothing ever can. Hook ops are
+// guarded separately by VERB_PARAMS.
+const SECTION_FIELDS = Object.freeze({
+  loop: ['shape', 'maxIterations'],
+  memory: ['store', 'recall', 'compressLevel'],
+  'memory.recall': ['k', 'kinds'],
+  gate: ['budgetUsd', 'writeScope'],
+  escalation: ['mode'],
+});
 const MAX_OPS_PER_SLOT = 2;
 
 // per-verb parameter contracts: name → check(value) (op field itself excluded).
@@ -22,7 +36,7 @@ const MAX_OPS_PER_SLOT = 2;
 // (the set remember() itself validates against — adaptlearn F5's drift lesson:
 // the export you bind can be wider than the function you call), minus doc:
 // the doc/upload axis stays gated out deliberately.
-const REMEMBER_KINDS = WRITE_KINDS.filter((k) => k !== 'doc');
+export const REMEMBER_KINDS = WRITE_KINDS.filter((k) => k !== 'doc'); // exported: the drafting prompt advertises THIS menu (one source, no drift)
 const VERB_PARAMS = {
   recall: { k: (v) => Number.isInteger(v) && v >= 1 && v <= 20, kinds: isKinds },
   compress: { level: (v) => COMPRESS_LEVELS.includes(v) },
@@ -40,7 +54,23 @@ const VERB_PARAMS = {
  * @param {string} scope
  */
 export function globToPrefix(scope) {
-  return scope.replace(/\/\*\*?$/, '');
+  // One canonical spelling for equivalent paths — leading "./", interior "/./",
+  // doubled "//", trailing "/" all collapse — so the legality rule, the fence
+  // comparison, and bareguard enforcement agree on what a scope NAMES. Without
+  // this, a validateJob-green fence like "src/" would reject every workflow
+  // scope inside it (the F9 red-class across two documents).
+  //
+  // Order is load-bearing: "//" collapses and interior "/./" drops BEFORE the
+  // leading "./" strip, so ".//src" → "src" and never "/src". Stripping first
+  // would MINT an absolute prefix from a relative scope — a design-law-#1
+  // containment escape (resolve(workdir, "/src") ignores workdir entirely).
+  //
+  // Deliberately NOT path.posix.normalize: it resolves ".." segments
+  // (normalize("src/../etc") === "etc"), which must stay VISIBLE so
+  // scopeContained can reject them — the whole point of the containment law.
+  let p = scope.replace(/\/\*\*?$/, '');
+  p = p.replace(/\/{2,}/g, '/').replace(/\/\.(?=\/|$)/g, '').replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
+  return p;
 }
 
 /**
@@ -48,15 +78,35 @@ export function globToPrefix(scope) {
  * resolve to a PROPER subdirectory of the run directory. Absolute paths and
  * ".." segments escape it; "." / "./**" cover the whole run directory — where
  * the close suite lives. Windows spellings ("..\", "C:\") count as escapes.
+ * Exported for the job validator: the operator's outer fence obeys the SAME
+ * law through the same code — two containment transforms would be the F9
+ * red-class one level up.
  * @param {string} s
  */
-function scopeContained(s) {
+export function scopeContained(s) {
   if (s.startsWith('/') || s.includes('\\') || /^[a-zA-Z]:/.test(s)) return false;
   const prefix = globToPrefix(s);
-  if (prefix === '' || prefix === '.') return false;
+  // Belt: reject a prefix that is empty, the run dir, absolute, or a drive —
+  // checked on the NORMALIZED prefix, not just the raw string, so a spelling
+  // that normalizes to something absolute can never pass (defense in depth
+  // against a future globToPrefix regression; the un-gameable gate, law #1).
+  if (prefix === '' || prefix === '.' || prefix.startsWith('/') || /^[a-zA-Z]:/.test(prefix)) return false;
   return prefix.split('/').every((seg) => seg !== '..');
 }
 
+/**
+ * The per-entry write-scope legality law, one home for all three call sites
+ * (workflow gate.writeScope, the job fence, the operator's job-v1 writeScope):
+ * a non-empty string, no mid-path wildcard (enforcement is prefix-containment,
+ * F9), contained under the run dir (law #1). The chains that need per-check
+ * reds still spell the three steps; fenceOk uses this so a fence can never be
+ * blessed that the job validator would reject.
+ * @param {unknown} s
+ */
+function legalScopeEntry(s) {
+  return isNonEmptyString(s) && !globToPrefix(s).includes('*') && scopeContained(s);
+}
+
 // Each verb is legal ONLY in the slot where it has effect: recall/compress
 // build the attempt context (consumed by before-attempt only), stash parks the
 // gap (which exists only after-red), remember is verdict-gated retention
@@ -69,17 +119,90 @@ const VERB_SLOT = { recall: 'before-attempt', compress: 'before-attempt', stash:
 function isKinds(v) {
   return Array.isArray(v) && v.length > 0 && v.every((k) => KINDS.includes(k));
 }
-function isObj(v) {
+/** Shared with the job validator — one definition of "a JSON object" for both
+ * documents (the sibling-validator drift class).
+ * @param {unknown} v */
+export function isObj(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
+/** @param {unknown} v @returns {v is string} */
+export function isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+// Secrets never enter the tree/spine/configs (hard line) — BOTH config
+// documents get the same sweep: the agent-authored workflow config is the
+// riskier entry point (machine-written), the operator's job spec the other.
+// Known token shapes only, left-bounded so hyphenated words ("flask-sqlalchemy")
+// never red — defense-in-depth; env-only loading is the law, not this regex.
+// ONE shape inventory for the whole system: detection (this sweep) and the
+// spine redactor (interpret wires these into bareguard's redact) must never
+// disagree on what a secret looks like — a shape the validator reds but the
+// redactor passes is a leak on the very output the validator was guarding.
+export const SECRET_PATTERNS = [
+  /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{16,}/,
+  /(?<![A-Za-z0-9_-])ghp_[A-Za-z0-9]{20,}/,
+  /(?<![A-Za-z0-9_-])github_pat_[A-Za-z0-9_]{20,}/,
+  /(?<![A-Za-z0-9_-])AKIA[0-9A-Z]{16}/,
+  /(?<![A-Za-z0-9_-])xox[bap]-[A-Za-z0-9-]{10,}/,
+];
+const SECRET_RE = new RegExp(SECRET_PATTERNS.map((r) => r.source).join('|'));
+
+/**
+ * Scan a RAW text stream (a spine file, a close's output, a transcript) for
+ * known secret shapes and return the literal matches. The ONE spelling of the
+ * text-side scan, for the same reason SECRET_PATTERNS is the ONE inventory: a
+ * hand-rolled copy that misses a shape is a leak on the very output it guards
+ * (seven copies of this expression lived in scripts/ before it landed here).
+ * `sweepSecretLiterals` is the config-tree twin — same shapes, tree walk.
+ * Never throws; returns [] for a missing stream.
+ * @param {unknown} raw
+ * @returns {string[]} every match, in stream order per pattern
+ */
+export function scanSecrets(raw) {
+  const text = String(raw ?? '');
+  // a fresh global clone per call: a shared /g regex carries lastIndex between
+  // calls and would skip matches on the next stream
+  return SECRET_PATTERNS.flatMap((re) => text.match(new RegExp(re.source, `${re.flags.replace('g', '')}g`)) ?? []);
+}
+
+/**
+ * Red every string in a config tree that carries a known secret-token shape.
+ * @param {any} root
+ * @param {(code: string, path: string, detail?: string) => void} red
+ */
+export function sweepSecretLiterals(root, red) {
+  (/** @type {(node: any, at: string) => void} */
+  function sweep(node, at) {
+    if (typeof node === 'string') {
+      if (SECRET_RE.test(node)) red('secret-literal', at, 'secrets load from the environment; an append-only record that captures a key captures it forever');
+      return;
+    }
+    if (Array.isArray(node)) node.forEach((v, i) => sweep(v, `${at}.${i}`));
+    else if (isObj(node)) {
+      for (const [k, v] of Object.entries(node)) {
+        const path = at ? `${at}.${k}` : k;
+        // keys too: inside free-form values (a gold expected, a conditions map)
+        // a key is unconstrained, so a token can ride a KEY onto the spine
+        if (SECRET_RE.test(k)) red('secret-literal', path, 'secrets load from the environment; an append-only record that captures a key captures it forever');
+        sweep(v, path);
+      }
+    }
+  })(root, '');
+}
 
 /**
- * Validate a workflow config against schema v1.
+ * Validate a workflow config against schema v1. Returns the parsed config on
+ * ok (single parse — callers never re-parse; null on any red).
  * @param {object|string} input parsed config, or raw JSON text (parse failures are a red)
- * @param {{ shellCapUsd?: number }} [opts] the shell's cap — a config may tighten it, never exceed it
- * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}> }}
+ * @param {{ shellCapUsd?: number, jobWriteScope?: string[] }} [opts] the shell's
+ *   ceilings — a config may tighten either, never exceed. `shellCapUsd`: at N2+
+ *   the shell passes min(shell cap, job budgetUsd) — the ceiling chain
+ *   workflow ≤ job ≤ shell. `jobWriteScope`: the job spec's outer fence
+ *   (operator law, job-v1) — every workflow scope must fit inside it.
+ * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}>, config: object|null }}
  */
-export function validateConfig(input, { shellCapUsd = 2 } = {}) {
+export function validateConfig(input, { shellCapUsd = 2, jobWriteScope } = {}) {
   /** @type {Array<{code: string, path: string, detail?: string}>} */
   const reds = [];
   /** @type {(code: string, path: string, detail?: string) => void} */
@@ -88,10 +211,10 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
   let c = input;
   if (typeof c === 'string') {
     try { c = JSON.parse(c); } catch (e) {
-      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }] };
+      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }], config: null };
     }
   }
-  if (!isObj(c)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'config must be a JSON object' }] };
+  if (!isObj(c)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'config must be a JSON object' }], config: null };
 
   // 1. shape — unknown top-level fields red here (smuggled close/provider included)
   for (const key of Object.keys(c)) {
@@ -128,7 +251,7 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
   }
   if (gate.writeScope === undefined) red('missing-required', 'gate.writeScope');
   else if (!(Array.isArray(gate.writeScope) && gate.writeScope.length > 0
-             && gate.writeScope.every((s) => typeof s === 'string' && s.length > 0))) {
+             && gate.writeScope.every(isNonEmptyString))) {
     red('invalid-value', 'gate.writeScope', 'non-empty array of glob strings');
   } else if (!gate.writeScope.every((s) => !globToPrefix(s).includes('*'))) {
     // adaptlearn F9: enforcement (bareguard fs.writeScope) is prefix-containment — a wildcard
@@ -139,6 +262,29 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
     // A scope that can reach the arbiter's inputs is the config-level
     // fit-to-pass surface (design law #1). Reds-before-tokens.
     red('invalid-value', 'gate.writeScope', 'must be a proper subdirectory of the run directory — no absolute paths, no ".." segments, not the run dir itself (design law #1)');
+  } else if (jobWriteScope !== undefined && jobWriteScope !== null) {
+    // Two-layer fence: the job spec's writeScope is operator law; the authored
+    // config may tighten it, never exceed it (the budget pattern, on paths).
+    // null/undefined are the legitimate "no fence" spellings (job optional at
+    // N2, and the only forms that survive JSON transit) — the layer is skipped,
+    // never a deadlock. A PRESENT-but-malformed fence fails CLOSED with its own
+    // red, attributed to jobWriteScope (NOT the innocent workflow field — the
+    // ledger's contrast attribution must not charge the agent's config for the
+    // operator's broken spec).
+    const fenceOk = Array.isArray(jobWriteScope) && jobWriteScope.length > 0 && jobWriteScope.every(legalScopeEntry);
+    if (!fenceOk) {
+      const shown = JSON.stringify(jobWriteScope).slice(0, 200); // bound: a malformed fence is untrusted caller input, and this rides the append-only spine (ralph's 2000-char precedent)
+      red('fence-invalid', 'jobWriteScope', `not a validateJob-green fence (${shown}) — validate the job spec before threading its fence`);
+    } else {
+      // Boundary-aware: "src2" is not inside "src" — prefix means PATH prefix.
+      const fence = jobWriteScope.map(globToPrefix);
+      const inside = (/** @type {string} */ p) => fence.some((f) => p === f || p.startsWith(f + '/'));
+      gate.writeScope.forEach((/** @type {string} */ s, /** @type {number} */ i) => {
+        if (!inside(globToPrefix(s))) {
+          red('scope-escape', `gate.writeScope.${i}`, `"${s}" is outside the job's fence [${jobWriteScope.join(', ')}] — the workflow may tighten the operator's bound, never exceed it`);
+        }
+      });
+    }
   }
 
   const escalation = isObj(c.escalation) ? c.escalation : {};
@@ -173,7 +319,20 @@ export function validateConfig(input, { shellCapUsd = 2 } = {}) {
     }
   }
 
-  return { ok: reds.length === 0, reds };
+  // 4b. inexpressibility, at every depth the arbiter can be reached from
+  for (const [section, allowed] of Object.entries(SECTION_FIELDS)) {
+    const obj = section === 'memory.recall' ? memory.recall : c[section];
+    if (!isObj(obj)) continue;
+    for (const key of Object.keys(obj)) {
+      if (!allowed.includes(key)) red('unknown-field', `${section}.${key}`);
+    }
+  }
+
+  // 5. secrets sweep — same guard as the job spec (the agent-authored document
+  // is the riskier one; a green config is a ledger fact and inherits forever)
+  sweepSecretLiterals(c, red);
+
+  return { ok: reds.length === 0, reds, config: reds.length === 0 ? c : null };
 }
 
 /**

package/types/extract.d.ts

@@ -5,7 +5,9 @@
  * @param {object} opts.provider a bareagent provider — SHELL-owned, sealed
  * @param {string[]|null} opts.priorRules the lineage's current rules, if any
  * @param {string[]} [opts.revisionDiff] changed config paths, when the run recovered mid-run
- * @returns {Promise<{rules: string[]|null, valid: boolean, reds: Array<object>, costUsd: number, raw: string}>}
+ * @returns {Promise<{rules: string[]|null, valid: boolean, reds: Array<object>, costUsd: number|null, raw: string}>}
+ *   costUsd is null when the spend could not be priced — the explicit-unknown
+ *   signal (F6: unpriced is never free); callers must not coerce it to 0
  */
 export function extractRules({ config, provider, priorRules, revisionDiff }: {
     config: object;
@@ -16,7 +18,7 @@ export function extractRules({ config, provider, priorRules, revisionDiff }: {
     rules: string[] | null;
     valid: boolean;
     reds: Array<object>;
-    costUsd: number;
+    costUsd: number | null;
     raw: string;
 }>;
 export const MAX_RULES: 5;

package/types/index.d.ts

@@ -1,5 +1,8 @@
 export { makeSpine } from "./spine.js";
-export { ralph, runClose } from "./ralph.js";
-export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
+export { runJob } from "./run.js";
+export { ralph, runClose, CLOSE_FAULTS } from "./ralph.js";
+export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
+export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS } from "./job.js";
 export { interpret, STALL_REDS } from "./interpret.js";
 export { extractRules, MAX_RULES, MAX_RULE_CHARS } from "./extract.js";
+export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";

package/types/interpret.d.ts

@@ -4,13 +4,30 @@
  * @param {object|string} configRaw schema v1 config (object or raw JSON text)
  * @param {object} opts
  * @param {string} opts.task implement instruction shown to the worker
- * @param {string} opts.target absolute path the artifact is written to
+ * @param {string} [opts.target] absolute path the artifact is written to —
+ *        required in text mode; unused in tool mode (the worker writes through
+ *        the gated tools, wherever the fence allows)
  * @param {string[]} opts.close argv whose exit code is truth (shell-owned)
+ * @param {number} [opts.closeExpect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.closeJudged] the signed spec's
+ *   judgment-rendered signal — proof the close actually judged something before
+ *   its exit code is believed in EITHER direction (PRD v1.11; the drafted config
+ *   cannot express it, and must not: it is the arbiter's own honesty check)
+ * @param {string} [opts.closeGapKeep] the signed spec's kept-failures pattern (F28):
+ *   close-output lines matching it survive the gap bound, so a large suite's
+ *   `not ok` names reach the worker instead of being elided into "N fail" — also
+ *   arbiter territory, inexpressible in the drafted config
  * @param {string} opts.workdir run directory (litectx root, gate audit, scope base)
  * @param {number} opts.capRuns shell iteration budget; the config may tighten via loop.maxIterations, never exceed
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {object} opts.provider a bareagent provider — SHELL-owned binding (adaptlearn F8: an unsealed binding is a gate bypass)
- * @param {number} [opts.shellCapUsd=2] the shell's USD cap; config budgetUsd is clamped by validation
+ * @param {number} [opts.shellCapUsd=2] the shell's USD cap; a config budgetUsd above it REDS at validation (bounds — no silent clamping)
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap, threaded to the shell
+ *        (shell/operator territory — the workflow config cannot express it)
+ * @param {string[]} [opts.jobWriteScope] the job spec's outer write fence (operator law,
+ *        job-v1) — enforced HERE, the one choke point where a config becomes a Gate:
+ *        every workflow scope must fit inside it (scope-escape config-red otherwise),
+ *        on entry validation and on every revision candidate alike
  * @param {(o: {config: object, gaps: string[], policy: any, onLlmResult: any}) => Promise<{candidate: object|null, parseError?: string|null, costUsd?: number}>} [opts.revisor]
  *        optional mid-run revision seam. Fires ONCE per run after STALL_REDS consecutive
  *        close reds. The interpreter — never the revisor — owns acceptance: the candidate
@@ -18,17 +35,34 @@
  *        (arbiter-touch / cap-touch revision-reds otherwise; the run continues on the old
  *        config). Revisor spend rides the run's own gate handlers — same budget axis as
  *        the worker.
+ * @param {string} [opts.closeState] the close's CURRENT output on the tree as it stands
+ *        (the shell's pre-token close check, F13) — shown to the first attempt only, and
+ *        never framed as an attempt: the worker cannot run the close itself (`run` is a
+ *        locked verb), so without this it is asked to fix a failure it cannot see
+ * @param {'text'|'tools'} [opts.mode] middle mode (2b): 'text' (default) writes the ONE
+ *        target from the response artifact; 'tools' gives the worker Gate-governed file
+ *        tools — SPEC-side territory (the step declares it; the config cannot express it)
+ * @param {string[]} [opts.tools] the spec's tool grant (subset of read|grep|write,
+ *        job-v1 validated); defaults to the full menu in tool mode
  * @returns {Promise<'green'|'escalated'|'config-red'>}
  */
-export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, revisor }: {
+export function interpret(configRaw: object | string, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd, jobWriteScope, revisor, closeTimeoutMs, mode, tools, closeState, closeExpect, closeJudged, closeGapKeep }: {
     task: string;
-    target: string;
+    target?: string | undefined;
     close: string[];
+    closeExpect?: number | undefined;
+    closeJudged?: {
+        pattern: string;
+        min: number;
+    } | undefined;
+    closeGapKeep?: string | undefined;
     workdir: string;
     capRuns: number;
     emit: (type: string, data?: object) => object;
     provider: object;
     shellCapUsd?: number | undefined;
+    closeTimeoutMs?: number | undefined;
+    jobWriteScope?: string[] | undefined;
     revisor?: ((o: {
         config: object;
         gaps: string[];
@@ -39,14 +73,18 @@ export function interpret(configRaw: object | string, { task, target, close, wor
         parseError?: string | null;
         costUsd?: number;
     }>) | undefined;
+    closeState?: string | undefined;
+    mode?: "text" | "tools" | undefined;
+    tools?: string[] | undefined;
 }): Promise<"green" | "escalated" | "config-red">;
-/** @typedef {Error & {category?: string}} CategorizedError the failure map's carrier: ralph relays by `category` */
+/** @typedef {Error & {category?: string, lib?: string}} CategorizedError the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose) */
 export const STALL_REDS: 2;
 /**
- * the failure map's carrier: ralph relays by `category`
+ * the failure map's carrier: ralph relays by `category`, and by `lib` when the thrower knows which library owns the failure (the ledger prefers it over prose)
  */
 export type CategorizedError = Error & {
     category?: string;
+    lib?: string;
 };
 /**
  * litectx recall hit — body present only with `{body: true}`

package/types/job.d.ts

@@ -0,0 +1,88 @@
+/** @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
+ * JSON text or plain parsed data — the ingest contract; a live object with a
+ * hostile accessor is outside it. Every failure is a named red. Returns the
+ * parsed spec on ok (single parse), null on any red.
+ * @param {object|string} input parsed spec, or raw JSON text (parse failures are a red)
+ * @param {{ shellCapUsd?: number }} [opts] the shell's hard ceiling — the job
+ *   budget may tighten it, never exceed it (ceiling chain: workflow ≤ job ≤ shell)
+ * @returns {{ ok: boolean, reds: Red[], job: object|null }}
+ */
+export function validateJob(input: object | string, { shellCapUsd }?: {
+    shellCapUsd?: number;
+}): {
+    ok: boolean;
+    reds: Red[];
+    job: object | null;
+};
+/**
+ * Content hash of a job spec — what an approval record binds to. Any edit to
+ * the spec changes the hash, so an edited spec is unapproved by construction
+ * (interview decision #1: human signs, always, once per spec VERSION).
+ * @param {object} job
+ * @returns {string} sha256 hex
+ */
+export function jobSpecHash(job: object): string;
+/**
+ * Does an approval record cover this exact spec version? Pure predicate — the
+ * N2 runner refuses to run without it; nothing here writes or prompts. The
+ * approval record lives OUTSIDE the document it signs (a spec never contains
+ * its own signature) and is shell/human territory, never agent-writable.
+ * @param {object} job
+ * @param {unknown} approvals array of { specHash, signer, ts } records
+ * @returns {boolean}
+ */
+export function checkApproval(job: object, approvals: unknown): boolean;
+export const CLOSE_TYPES: readonly string[];
+export const CLASSES: readonly string[];
+/** the hierarchy: which verdict classes a close type may claim (PRD §7) */
+export const CLASS_BY_CLOSE: Readonly<{
+    predicate: readonly string[];
+    gold: readonly string[];
+    rubric: readonly string[];
+    hitl: readonly string[];
+}>;
+export const GOLD_COMPARE: readonly string[];
+/** step middle modes (2b): text = single-target artifact; tools = Gate-governed file tools */
+export const STEP_MODES: readonly string[];
+/** 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: readonly string[];
+/** 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: readonly string[];
+export const CADENCE_UNITS: readonly string[];
+export const PROVIDERS: readonly string[];
+/** V3 environment label: declared keys only — every field is a lineage-key
+ * candidate at N3. `provider` is part of the key by definition (top-level,
+ * not duplicated here). */
+export const CONDITION_KEYS: readonly string[];
+/**
+ * — `verb` rides request-reds as structured data (the ledger keys on it, never on prose)
+ */
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+    verb?: string;
+};

package/types/ledger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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: any[], { spine }?: {
+    spine?: string;
+}): Occurrence[];
+/**
+ * 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: any[]): Record<string, FoldEntry>;
+/**
+ * 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: Record<string, FoldEntry>, occurrences: Occurrence[]): object[];
+/**
+ * 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 }: {
+    ledgerFile: string;
+    spineFiles: string[];
+}): {
+    appended: object[];
+    fold: Record<string, FoldEntry>;
+};
+/** severity order, worst-first (the fold's display order; frequency ranks within) */
+export const LEDGER_CLASSES: readonly string[];
+export type Sample = {
+    spine: string;
+    seq: number;
+};
+export type Occurrence = {
+    key: string;
+    class: string;
+    lib: string;
+    verb: string;
+    sig: string;
+    detail: string;
+    sample: Sample;
+};
+export type FoldEntry = {
+    key: string;
+    lib: string;
+    verb: string;
+    class: string;
+    sig: string;
+    detail: string;
+    occurrences: number;
+    samples: Sample[];
+    suggestedAsk: string;
+    status: string;
+    ref?: string;
+};