bareloop 0.0.1 → 0.2.0

package/src/job.js

@@ -0,0 +1,252 @@
+// Job-spec validator — the OPERATOR-owned half of the config story (N1,
+// design record: docs/plans/2026-07-12-n1-job-close-schema-design.md).
+// A job spec is the arbiter's rulebook: the close chain, the budget, the
+// outer write fence, the escalation route. It is pure declarative data —
+// no freeform code is expressible anywhere in it — and it validates
+// reds-before-tokens like its sibling validate.js (workflow, agent-authored).
+// The arbiter split is guarded from both sides by INEXPRESSIBILITY: the
+// workflow config cannot say close/provider (validate.js, shipped at N0);
+// the job spec cannot say hooks/loop/memory, any minting claim, or the
+// shell-owned retry cap — all unknown-field reds here.
+//
+// Close-authoring hierarchy (PRD §7) as a class menu keyed by close type:
+// verdict-class laundering (a rubric claiming hard) is a named red, never a
+// judgment call. Minting policy is product doctrine, not job-authorable.
+
+import { createHash } from 'node:crypto';
+import { globToPrefix, scopeContained, isObj, isNonEmptyString, sweepSecretLiterals } from './validate.js';
+
+// The menus below ARE the close-authoring hierarchy (PRD §7) and ship frozen:
+// they are read at call time, so a mutable export would let adopter code
+// enable verdict-class laundering process-wide with one push().
+export const CLOSE_TYPES = Object.freeze(['predicate', 'gold', 'rubric', 'hitl']);
+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']);
+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
+ * candidate at N3. `provider` is part of the key by definition (top-level,
+ * not duplicated here). */
+export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', 'taskFraming', 'scaffold']);
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'writeScope', 'steps', 'escalation'];
+/** 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'],
+  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 */
+
+/**
+ * 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, { shellCapUsd = 2 } = {}) {
+  /** @type {Red[]} */
+  const reds = [];
+  /** @type {(code: string, path: string, detail?: string) => void} */
+  const red = (code, path, detail) => { reds.push(detail ? { code, path, detail } : { code, path }); };
+
+  let j = input;
+  if (typeof j === 'string') {
+    try { j = JSON.parse(j); } catch (e) {
+      return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: String(/** @type {Error} */ (e).message) }], job: null };
+    }
+  }
+  if (!isObj(j)) return { ok: false, reds: [{ code: 'parse-error', path: '$', detail: 'job spec must be a JSON object' }], job: null };
+  const spec = /** @type {Record<string, any>} */ (j);
+
+  // 1. shape — unknown fields red here: hooks/loop/memory (agent domain),
+  // capRuns (shell domain), minting claims — inexpressibility is the guard.
+  for (const key of Object.keys(spec)) {
+    if (!JOB_FIELDS.includes(key)) red('unknown-field', key);
+  }
+  if (spec.schema === undefined) red('missing-required', 'schema');
+  else if (spec.schema !== 'job-v1') red('invalid-value', 'schema', `expected "job-v1", got ${JSON.stringify(spec.schema)}`);
+  if (!isNonEmptyString(spec.job) || !SLUG_RE.test(spec.job)) red('invalid-value', 'job', 'kebab-case slug');
+  if (!isNonEmptyString(spec.description)) red('missing-required', 'description');
+
+  if (spec.provider === undefined) red('missing-required', 'provider');
+  else if (!PROVIDERS.includes(spec.provider)) red('invalid-value', 'provider', `menu: ${PROVIDERS.join('|')}`);
+
+  // 2. the environment label (V3, design law #5): declared keys only
+  if (spec.conditions !== undefined) {
+    if (!isObj(spec.conditions)) red('invalid-value', 'conditions', 'flat object of declared condition keys');
+    else {
+      for (const [key, value] of Object.entries(spec.conditions)) {
+        if (!CONDITION_KEYS.includes(key)) red('unknown-field', `conditions.${key}`, `declared keys only: ${CONDITION_KEYS.join('|')} (every field is a lineage-key dimension, V3)`);
+        else if (!isNonEmptyString(value)) red('invalid-value', `conditions.${key}`, 'non-empty string');
+      }
+    }
+  }
+
+  if (spec.cadence === undefined) red('missing-required', 'cadence');
+  else if (!isObj(spec.cadence)) red('invalid-value', 'cadence', 'object of {unit, every}');
+  else {
+    const cad = spec.cadence;
+    for (const key of Object.keys(cad)) {
+      if (key !== 'unit' && key !== 'every') red('unknown-field', `cadence.${key}`, 'nested objects red unknown keys too — no smuggling level exists in a signed spec');
+    }
+    if (!CADENCE_UNITS.includes(cad.unit)) red('invalid-value', 'cadence.unit', CADENCE_UNITS.join('|'));
+    if (!(Number.isInteger(cad.every) && cad.every >= 1 && cad.every <= 30)) red('bounds', 'cadence.every', '1..30');
+  }
+
+  if (spec.budgetUsd === undefined) red('missing-required', 'budgetUsd');
+  else if (!(typeof spec.budgetUsd === 'number' && spec.budgetUsd > 0 && spec.budgetUsd <= shellCapUsd)) {
+    red('bounds', 'budgetUsd', `0 < budget <= shell cap ${shellCapUsd} (cap-not-estimate; no self-adjusted budgets, ever)`);
+  }
+
+  // 3. the outer write fence — operator law (interview decision #4), same
+  // containment rules as the workflow layer THROUGH THE SAME CODE (F9: two
+  // transforms would let a fence validate green and mean something else).
+  if (spec.writeScope === undefined) red('missing-required', 'writeScope', 'the fence is operator law — the workflow scope must fit inside it');
+  else if (!(Array.isArray(spec.writeScope) && spec.writeScope.length > 0
+             && spec.writeScope.every((/** @type {unknown} */ s) => isNonEmptyString(s)))) {
+    red('invalid-value', 'writeScope', 'non-empty array of glob strings');
+  } else if (!spec.writeScope.every((/** @type {string} */ s) => !globToPrefix(s).includes('*'))) {
+    red('invalid-value', 'writeScope', 'wildcards only as a trailing "/**" or "/*" (enforcement is prefix-containment, adaptlearn F9)');
+  } else if (!spec.writeScope.every(scopeContained)) {
+    red('invalid-value', 'writeScope', 'must be a proper subdirectory of the run directory — no absolute paths, no ".." segments, not the run dir itself (design law #1)');
+  }
+
+  if (spec.escalation === undefined) red('missing-required', 'escalation.mode', 'the pain channel is not optional (law #7)');
+  else {
+    const esc = isObj(spec.escalation) ? spec.escalation : {};
+    for (const key of Object.keys(esc)) {
+      if (key !== 'mode') red('unknown-field', `escalation.${key}`, 'nested objects red unknown keys too — no smuggling level exists in a signed spec');
+    }
+    if (esc.mode !== 'decision-ready') red('invalid-value', 'escalation.mode', 'must be "decision-ready"');
+  }
+
+  // 4. steps + the close chain
+  if (!Array.isArray(spec.steps) || spec.steps.length === 0) {
+    red('missing-required', 'steps', 'non-empty array — a job without closes is ungated spend');
+  } else {
+    const seen = new Set();
+    spec.steps.forEach((/** @type {any} */ s, /** @type {number} */ i) => {
+      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 (!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);
+      else seen.add(s.id);
+
+      if (s.class === undefined) red('missing-required', `${at}.class`);
+      else if (!CLASSES.includes(s.class)) red('invalid-value', `${at}.class`, CLASSES.join('|'));
+
+      if (!isObj(s.close)) { red('missing-required', `${at}.close`, 'every step names its close — a step without one is ungated spend'); return; }
+      const close = s.close;
+      if (!CLOSE_TYPES.includes(close.type)) {
+        red('close-type', `${at}.close.type`, `menu: ${CLOSE_TYPES.join('|')} — a close is data, never code`);
+        return;
+      }
+      // per-type contracts — fixed menus only
+      if (close.type === 'predicate') {
+        if (!isNonEmptyString(close.cmd)) red('missing-required', `${at}.close.cmd`);
+        if (!Number.isInteger(close.expect)) red('invalid-value', `${at}.close.expect`, 'integer exit code');
+      } 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('|'));
+      } else if (close.type === 'rubric') {
+        if (!isNonEmptyString(close.criteria)) red('missing-required', `${at}.close.criteria`);
+      } else if (close.type === 'hitl') {
+        if (!isNonEmptyString(close.prompt)) red('missing-required', `${at}.close.prompt`);
+      }
+      for (const key of Object.keys(close)) {
+        if (!CLOSE_FIELDS[close.type].includes(key)) {
+          red('unknown-field', `${at}.close.${key}`, `not a ${close.type} field (script bodies and minting claims land here)`);
+        }
+      }
+      // the hierarchy: one check covers both directions — a class outside the
+      // close type's menu is laundering (rubric-as-hard) or delegation
+      // (hitl-class on a script close); hitl ⇔ hitl falls out of the menus.
+      const legal = CLASS_BY_CLOSE[close.type];
+      if (CLASSES.includes(s.class) && !legal.includes(s.class)) {
+        red('close-hierarchy', `${at}.class`, `${close.type} close admits class ${legal.join('|')} only (a rubric can never be hard; a human IS the hitl close — PRD §7)`);
+      }
+    });
+  }
+
+  // 5. secrets sweep — the SAME shared guard the workflow validator runs
+  // (defense-in-depth against known token shapes; env-only loading is the law)
+  sweepSecretLiterals(spec, red);
+
+  return { ok: reds.length === 0, reds, job: reds.length === 0 ? spec : null };
+}
+
+/**
+ * Canonical JSON — recursive key sort, so the hash binds to CONTENT, not to
+ * the accident of key order a drafting UX or an editor produced.
+ * @param {any} v
+ * @returns {string}
+ */
+function canon(v) {
+  // Follow JSON.stringify semantics — the hash must equal the hash of the
+  // disk round-trip, or an approval minted in memory fails after save/reload
+  // (human-signs-always rejecting an unedited spec). That means honoring toJSON
+  // (a Date serializes to its ISO string, not walked as {}) and dropping
+  // undefined-valued keys, both of which JSON.stringify does. One divergence:
+  // a function/symbol-VALUED key canonizes as null where stringify drops it —
+  // reachable only on non-JSON specs, where a round-trip mismatch is correct.
+  if (v !== null && typeof v === 'object' && typeof (/** @type {any} */ (v).toJSON) === 'function') {
+    return canon(/** @type {any} */ (v).toJSON());
+  }
+  if (Array.isArray(v)) return `[${v.map((x) => (x === undefined ? 'null' : canon(x))).join(',')}]`;
+  if (isObj(v)) {
+    const obj = /** @type {Record<string, any>} */ (v);
+    return `{${Object.keys(obj).sort().filter((k) => obj[k] !== undefined).map((k) => `${JSON.stringify(k)}:${canon(obj[k])}`).join(',')}}`;
+  }
+  const s = JSON.stringify(v);
+  return s === undefined ? 'null' : s; // undefined/function/symbol leaf: not JSON-representable — 'null', never throw
+}
+
+/**
+ * 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) {
+  // NEVER throws: the N2 runner mints {specHash, signer, ts} by calling this
+  // directly on the raw job object, so a non-JSON value (BigInt, a cycle, a
+  // throwing getter) must yield a hash, not crash the signer. canon handles
+  // JSON-representable inputs; the guard covers cycles and hostile getters.
+  let c;
+  try { c = canon(job); } catch { c = '\u0000unhashable'; }
+  return createHash('sha256').update(c).digest('hex');
+}
+
+/**
+ * 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, approvals) {
+  if (!Array.isArray(approvals)) return false;
+  // NOT jobSpecHash: its un-hashable sentinel would make every un-hashable
+  // spec hash-equal — an approval minted for one would authorize any other.
+  // Here un-hashable simply means unapproved, full stop.
+  let c;
+  try { c = canon(job); } catch { return false; }
+  const h = createHash('sha256').update(c).digest('hex');
+  return approvals.some((a) => isObj(a) && /** @type {Record<string, unknown>} */ (a).specHash === h);
+}

package/src/ralph.js

@@ -0,0 +1,122 @@
+// The outer shell — fixed, deliberately dumb, permanent (PRD §4). It holds the
+// arbiter (the close: exit code = truth) and the iteration budget, and nothing
+// inside negotiates with either (design law #1: the agent never authors its
+// arbiter). Stateless across runs and stdlib-only by design: it must stay too
+// dumb to be gamed. Do not make it smarter.
+
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Run a close command; its exit code is the verdict (hard green, PRD §4).
+ * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ *
+ * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
+ * a spine event or a worker prompt — so a secret a checked command echoes
+ * (a 401 dumping an `Authorization: Bearer …` header) never enters the
+ * append-only spine (the hard line). It is INJECTED, not imported: the shell
+ * stays stdlib-only and un-gameable, and the redactor is a fixed shell
+ * primitive (bareguard's, wired by the interpreter), never an emergent
+ * component — so V4 holds. The shell's canonical emission IS the redacted text;
+ * a benign gap is returned byte-identical (default: identity).
+ * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
+ * @param {(s: string) => string} [redact] source scrubber; identity by default
+ */
+export function runClose(close, redact = (s) => s) {
+  const env = { ...process.env };
+  delete env.NODE_TEST_CONTEXT; // a `node --test` close inherits this from a test runner and silently no-ops — a fake green
+  const r = spawnSync(close[0], close.slice(1), { env, encoding: 'utf8', timeout: 120_000 });
+  if (r.error) return { verdict: 'failed', detail: String(r.error) };
+  if (r.status === 0) return { verdict: 'satisfied' };
+  // The gap must never be falsy: every consumer guards with `if (gap)` — an
+  // empty-output red would silently kill gap feedback, after-red hooks, AND
+  // stall detection, leaving the worker re-prompted byte-identically to the cap.
+  // Redact BEFORE slicing so a token straddling the 2000-char bound can't survive.
+  return { verdict: 'needs_revision', gap: redact(r.stderr || r.stdout || '').slice(0, 2000) || '(close exited nonzero with no output)', exitCode: r.status };
+}
+
+/**
+ * The loop: `while close-red and under-cap: run the middle`. Stops at first
+ * green (within-run tuning past a visible close is the fit-to-pass surface,
+ * PRD §2). The two honest terminals are green and a decision-ready escalation;
+ * cap-halt means "not under cap", its own category, never merged with "wrong"
+ * (design law #8). A broken close escalates immediately — a broken arbiter
+ * must not masquerade as a bad harness.
+ *
+ * A middle that throws is read through the failure map: a throw carrying
+ * `category: 'cap-halt'` (the USD gate tripping inside the middle) escalates
+ * as cap-halt; any other named category is relayed as-is; an unnamed throw is
+ * an interpreter-red — a broken interpreter must not masquerade as a bad
+ * harness. Ralph never interprets, only relays.
+ *
+ * @param {object} opts
+ * @param {(iteration: number, gap?: string) => void|Promise<void>} opts.middle the emergent middle; never sees close/cap
+ * @param {string[]} opts.close argv whose exit code is truth
+ * @param {number} opts.capRuns budget: max middle runs
+ * @param {(type: string, data?: object) => object} opts.emit a spine emitter
+ * @param {(s: string) => string} [opts.redact] source scrubber for close output
+ *   (secrets never enter the spine); injected so the shell stays stdlib-only
+ * @returns {Promise<'green'|'escalated'>}
+ */
+export async function ralph({ middle, close, capRuns, emit, redact }) {
+  emit('run-start', { capRuns, close: close.join(' ') });
+  const verdicts = [];
+  let gap;
+  for (let iteration = 1; iteration <= capRuns; iteration++) {
+    emit('iteration-start', { iteration });
+    try {
+      await middle(iteration, gap);
+    } catch (e) {
+      // dumb passthrough: the thrower names its category (cap-halt | gate-red | …)
+      const category = e && typeof e.category === 'string' ? e.category : 'interpreter-red';
+      if (category === 'cap-halt') emit('cap-halt', { category, meaning: 'not under cap — not "can\'t"', detail: String(e.message || e) });
+      const DECISIONS = {
+        'cap-halt': [`Budget gate tripped mid-run (${e && e.message}). Continue with a higher cap, change approach, or stop?`,
+          ['raise the cap and rerun', 'change the middle/harness', 'abandon the task']],
+        'gate-red': ['The gate denied an action mid-run — the harness asked for something outside its scope.',
+          ['widen the write scope deliberately', 'change the middle/harness', 'abandon the task']],
+      };
+      // Object.hasOwn, not bare lookup: a category named after an
+      // Object.prototype member ("toString") would return the inherited
+      // function, and destructuring it would crash the shell inside its own
+      // escalation path — the one place that must never break.
+      const [decision, options] = (Object.hasOwn(DECISIONS, category) ? DECISIONS[category] : undefined)
+        ?? ['The middle itself broke — no harness verdict is trustworthy until it is fixed.', ['fix the interpreter', 'abandon the task']];
+      emit('escalation', {
+        category, decisionReady: true, verdicts,
+        spend: { runs: iteration, capRuns },
+        decision, options, detail: String(e.message || e),
+      });
+      emit('run-end', { outcome: 'escalated', iterations: iteration });
+      return 'escalated';
+    }
+    emit('middle-done', { iteration });
+    const v = runClose(close, redact);
+    verdicts.push(v.verdict);
+    emit('close-verdict', { iteration, ...v });
+    if (v.verdict === 'satisfied') {
+      emit('run-end', { outcome: 'green', iterations: iteration });
+      return 'green';
+    }
+    if (v.verdict === 'failed') {
+      emit('escalation', {
+        category: 'broken-close', decisionReady: true, verdicts,
+        spend: { runs: iteration, capRuns },
+        decision: 'The close itself cannot run — no verdict is trustworthy until it is fixed.',
+        options: ['fix the close command', 'abandon the task'],
+        detail: v.detail,
+      });
+      emit('run-end', { outcome: 'escalated', iterations: iteration });
+      return 'escalated';
+    }
+    gap = v.gap; // feedback for the next middle run; the shell itself learns nothing
+  }
+  emit('cap-halt', { category: 'cap-halt', meaning: 'not under cap — not "can\'t"', capRuns });
+  emit('escalation', {
+    category: 'cap-halt', decisionReady: true, verdicts,
+    spend: { runs: capRuns, capRuns },
+    decision: `${capRuns}/${capRuns} runs spent, close still red. Continue, change approach, or stop?`,
+    options: ['raise the cap and rerun', 'change the middle/harness', 'abandon the task'],
+  });
+  emit('run-end', { outcome: 'escalated', iterations: capRuns });
+  return 'escalated';
+}

package/src/spine.js

@@ -0,0 +1,29 @@
+// The floor's event spine: append-only JSONL, one event per line (PRD §4).
+// Single source for every UI — the panel is a pure observer of this file.
+// Contract (carried from adaptlearn/relayfact — the pattern, not the code):
+// `seq` is monotonic per spine, `ts` is stamped last and is always the final
+// key, and consumers are pure listeners — nothing here reads the file back.
+// Secrets never enter the spine (PRD §4): an append-only record that captures
+// a key captures it forever.
+
+import { appendFileSync } from 'node:fs';
+
+/**
+ * Create an emitter bound to one JSONL file.
+ * @param {string} file absolute path; created on first emit
+ * @returns {(type: string, data?: object) => object} emit — returns the event as written
+ */
+export function makeSpine(file) {
+  let seq = 0;
+  return function emit(type, data = {}) {
+    // type/seq/ts are the envelope's, by mechanism not comment: callers spread
+    // foreign objects into events, and a payload that grows one of these keys
+    // must never relabel or mis-stamp a row in the append-only record.
+    const { type: _type, seq: _seq, ts: _ts, ...payload } = /** @type {Record<string, unknown>} */ (data);
+    /** @type {Record<string, unknown>} */
+    const ev = { type, ...payload, seq: ++seq };
+    ev.ts = new Date().toISOString();
+    appendFileSync(file, JSON.stringify(ev) + '\n');
+    return ev;
+  };
+}

package/src/text.js

@@ -0,0 +1,9 @@
+// Shared text helpers. stripFences is deliberately minimal at N0 (reference
+// parity): it strips ONE leading and ONE trailing markdown fence. The
+// fence-robust upgrade (prose-wrapped, mid-text fences — adaptlearn F21's
+// instrument caveat, filed in FINDINGS F2) lands here at N2, in one place:
+// interpret's artifact path and extract's rules path must never disagree
+// about what the same model output parses to.
+
+/** @param {string} t */
+export const stripFences = (t) => t.trim().replace(/^```[a-z]*\n?/i, '').replace(/\n?```\s*$/, '');