bareloop 0.0.1 → 0.1.0

package/src/extract.js

@@ -0,0 +1,95 @@
+// The rules extractor — the lineage's inheritance representation. One sealed
+// LLM call after a green run distills/updates the lineage's rules list from
+// LEDGER FACTS only: the green config, the prior rules, and the revision diff
+// if the run recovered mid-run (the diff is the lesson — failure-transition
+// evidence, free in the event log). It never sees the close, the tests, or the
+// worker's code: rules describe the WORKFLOW, and showing the judge would open
+// the config-level fit-to-pass surface (PRD §2).
+//
+// N3 extends this with the contrast-bit rule (design law #3: verdict admits,
+// contrast attributes — the extractor may claim a knob only with ≥1
+// ledger-counted contrast bit; adaptlearn F16/F18 showed bare greens lose
+// working features). At N0 the extractor is the adaptlearn-proven distiller.
+//
+// Honesty invariants:
+// - One shot, no retry: malformed output is a red as DATA — the caller keeps
+//   the lineage's prior rules; there is never a silent empty inheritance.
+// - The ≤MAX_RULES/≤MAX_RULE_CHARS bound is stated to the model but ENFORCED
+//   mechanically post-call, and enforcement rejects whole — never trims
+//   (rejecting a half-applicable output beats silently part-applying it).
+// - Extractor spend is carried in costUsd and lands on the run's cost line —
+//   a representation whose upkeep rides free corrupts the ranking (design
+//   law #4: green gates, cost ranks).
+
+import { createRequire } from 'node:module';
+
+import { stripFences } from './text.js';
+
+const require = createRequire(import.meta.url);
+const { Loop } = require('bare-agent');
+
+export const MAX_RULES = 5;
+export const MAX_RULE_CHARS = 200;
+
+/**
+ * Distill/update a lineage's rules from one green run's ledger facts.
+ * @param {object} opts
+ * @param {object} opts.config the config that went green
+ * @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}>}
+ */
+export async function extractRules({ config, provider, priorRules, revisionDiff }) {
+  const loop = new Loop({ provider, system: 'You emit exactly one JSON document and nothing else.' });
+  const prompt = `An automated coding workflow just completed a run that PASSED its hidden judgement.
+You maintain this workflow lineage's inherited rules: short, general lessons about how to
+configure the workflow for this task family. You never see the tasks' tests or code — only
+workflow facts.
+
+The config that went green:
+${JSON.stringify(config, null, 2)}
+${revisionDiff && revisionDiff.length > 0 ? `
+This run stalled and recovered after revising these config paths mid-run (the revision that
+turned red into green — strong evidence about what mattered):
+${revisionDiff.join(', ')}
+` : ''}${priorRules && priorRules.length > 0 ? `
+The lineage's current rules — revise them: keep what still holds, drop what this run
+contradicts, add at most what this run actually evidences:
+${JSON.stringify(priorRules, null, 2)}
+` : `
+The lineage has no rules yet. Write only what this single run actually evidences.
+`}
+Output ONLY a JSON array of strings: at most ${MAX_RULES} rules, each at most ${MAX_RULE_CHARS}
+characters. No markdown fences, no commentary.`;
+
+  // Never throw (the module contract): a provider blip during post-green
+  // extraction must not lose the green run's bookkeeping — it degrades to a
+  // red as data and the caller keeps the lineage's prior rules. Loop defaults
+  // throwOnError: true, so a transient 500 WOULD reject without this.
+  let r;
+  try {
+    r = await loop.run([{ role: 'user', content: prompt }]);
+  } catch (e) {
+    return { rules: null, valid: false, reds: [{ code: 'provider-error', detail: String(/** @type {Error} */ (e).message ?? e) }], costUsd: 0, raw: '' };
+  }
+  const costUsd = r.metrics?.costUsd ?? r.cost ?? 0;
+  const raw = stripFences(r.text ?? '');
+  if (r.error) {
+    return { rules: null, valid: false, reds: [{ code: 'provider-error', detail: String(r.error) }], costUsd, raw };
+  }
+  /** @type {(code: string, detail: string) => {rules: null, valid: false, reds: Array<object>, costUsd: number, raw: string}} */
+  const red = (code, detail) => ({ rules: null, valid: false, reds: [{ code, detail }], costUsd, raw });
+
+  let rules;
+  try { rules = JSON.parse(raw); } catch (e) {
+    return red('parse-error', String(/** @type {Error} */ (e).message));
+  }
+  if (!Array.isArray(rules) || rules.length === 0 || !rules.every((x) => typeof x === 'string')) {
+    return red('rules-shape', 'expected a non-empty JSON array of strings');
+  }
+  if (rules.length > MAX_RULES || rules.some((x) => x.length > MAX_RULE_CHARS)) {
+    return red('rules-bound', `max ${MAX_RULES} rules of ${MAX_RULE_CHARS} chars — rejected whole, never trimmed`);
+  }
+  return { rules, valid: true, reds: [], costUsd, raw };
+}

package/src/index.js

@@ -0,0 +1,9 @@
+// bareloop public surface — grows one rung at a time (PRD §10). N0: the
+// token-free spine. The five modules compose bottom-up: makeSpine feeds ralph,
+// interpret is the only config reader, extractRules distills a green run.
+
+export { makeSpine } from './spine.js';
+export { ralph, runClose } from './ralph.js';
+export { validateConfig, diffPaths, globToPrefix, LOOP_SHAPES, SLOTS, VERBS } from './validate.js';
+export { interpret, STALL_REDS } from './interpret.js';
+export { extractRules, MAX_RULES, MAX_RULE_CHARS } from './extract.js';

package/src/interpret.js

@@ -0,0 +1,228 @@
+// The interpreter — the ONLY code that reads a workflow config (PRD §4's
+// emergent middle, executed). It composes the suite, never invents: litectx is
+// the store, bareguard is the leash, bareagent is the worker loop (design law
+// #10). The provider arrives from the SHELL (never the config — it is
+// arbiter-adjacent), and the close never runs here: the shell runs it and
+// feeds the verdict back as `gap`.
+//
+// Two traps this encodes, both paid for in adaptlearn: `onLlmResult` is a Loop
+// CONSTRUCTOR option — passed to run() it is silently ignored and the budget
+// axis goes blind (F3); and a budget-exhausted gate deny must surface as
+// cap-halt, its own category, never a generic error (design law #8).
+
+import { createRequire } from 'node:module';
+import { writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { Gate } from 'bareguard';
+import { LiteCtx, compress } from 'litectx';
+import { validateConfig, diffPaths, globToPrefix } from './validate.js';
+import { ralph } from './ralph.js';
+
+/** @typedef {Error & {category?: string}} CategorizedError the failure map's carrier: ralph relays by `category` */
+
+// consecutive close reds that count as a stall; one revision per run
+export const STALL_REDS = 2;
+
+const require = createRequire(import.meta.url);
+const { Loop, wireGate, HaltError } = require('bare-agent');
+
+import { stripFences } from './text.js';
+
+/** @typedef {{body?: string|null, text?: string|null}} RecallHit litectx recall hit — body present only with `{body: true}` */
+
+const PERSONA = 'You are a senior engineer. Reply with ONLY the complete contents of the requested JavaScript file — no markdown fences, no commentary. ESM.';
+
+/**
+ * Execute a workflow config against one task under the dumb shell.
+ *
+ * @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.close argv whose exit code is truth (shell-owned)
+ * @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 {(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
+ *        must validate, and gate/escalation/loop.maxIterations must be unchanged
+ *        (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.
+ * @returns {Promise<'green'|'escalated'|'config-red'>}
+ */
+export async function interpret(configRaw, { task, target, close, workdir, capRuns, emit, provider, shellCapUsd = 2, revisor }) {
+  const v = validateConfig(configRaw, { shellCapUsd });
+  emit('config-validate', { ok: v.ok, reds: v.reds });
+  if (!v.ok) {
+    for (const r of v.reds) emit('config-red', r);
+    emit('run-end', { outcome: 'config-red', iterations: 0 });
+    return 'config-red';
+  }
+  let config = typeof configRaw === 'string' ? JSON.parse(configRaw) : configRaw;
+
+  const lc = new LiteCtx({ root: workdir });
+  const gate = new Gate({
+    // bareguard fs.writeScope is prefix-containment, not glob (adaptlearn F4); globToPrefix
+    // is the ONE transform shared with the validator's legality rule — mid-path wildcards
+    // and workdir-escaping scopes were already rejected up front (adaptlearn F9, law #1).
+    fs: { writeScope: config.gate.writeScope.map((/** @type {string} */ g) => resolve(workdir, globToPrefix(g))) },
+    budget: { maxCostUsd: config.gate.budgetUsd },
+    limits: { maxTurns: 8 * (capRuns + 1) },
+    audit: { path: join(workdir, 'gate-audit.jsonl') },
+    humanChannel: async () => ({ decision: 'terminate' }), // no human mid-run: a tripped cap terminates → decision-ready escalation
+  });
+  await gate.init();
+  const { policy, onLlmResult } = wireGate(gate);
+  const loop = new Loop({ provider, system: PERSONA, policy, onLlmResult });
+
+  /** @param {string} slot */
+  const slotOps = (slot) => config.hooks?.[slot] ?? [];
+  /** @param {{kinds?: string[]}} op */
+  const recallKinds = (op) => op.kinds ?? config.memory.recall?.kinds ?? ['fact'];
+
+  /** @param {string} prompt */
+  async function ask(prompt) {
+    let r;
+    try {
+      r = await loop.run([{ role: 'user', content: prompt }]);
+    } catch (e) {
+      if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt'; // belt: bare-agent's contract could change
+      throw e;
+    }
+    // bare-agent NEVER throws HaltError out of run() — a governance halt comes
+    // back as an error RETURN ({text: '', error: 'halt:<rule>'}; loop.js: "no
+    // throw even when throwOnError: true"). Read it, or the failure map goes
+    // blind and a cap story masquerades as a worker result (design law #8).
+    if (r.error) {
+      const err = /** @type {CategorizedError} */ (new Error(`worker loop: ${r.error}`));
+      err.category = r.error.startsWith('halt:') ? 'cap-halt' : 'interpreter-red';
+      throw err;
+    }
+    return r;
+  }
+
+  /**
+   * @param {string} slot
+   * @param {{iteration?: number, gap?: string, context?: any}} o
+   */
+  async function runOps(slot, { iteration, gap, context }) {
+    for (const op of slotOps(slot)) {
+      if (op.op === 'recall') {
+        /** @type {RecallHit[]} */
+        const hits = [];
+        for (const kind of recallKinds(op)) {
+          hits.push(...await lc.recall(task, { kind, n: op.k ?? config.memory.recall?.k ?? 5, body: true }));
+        }
+        context.text = hits.map((h) => h.body ?? h.text ?? '').filter(Boolean).join('\n');
+        context.level = null;
+        emit('hook-op', { slot, op: 'recall', hits: hits.length, iteration });
+      } else if (op.op === 'compress') {
+        const level = op.level ?? config.memory.compressLevel ?? 'verbatim';
+        if (context.text) context.text = await compress({ text: context.text, format: 'js' }, { level });
+        emit('hook-op', { slot, op: 'compress', level, iteration });
+      } else if (op.op === 'stash') {
+        if (gap) lc.stash(`gap-${iteration}`, gap);
+        emit('hook-op', { slot, op: 'stash', iteration });
+      } else if (op.op === 'remember') {
+        await lc.remember(`green-${iteration ?? 'final'}-${target.split('/').at(-1)}`, readFileSync(target, 'utf8'), { kind: op.kind ?? 'fact' });
+        emit('hook-op', { slot, op: 'remember' });
+      }
+    }
+  }
+
+  // Mid-run revision: interpreter-owned acceptance — a revisor cannot vouch for
+  // its own output. The gate is already constructed and the iteration budget
+  // already snapshotted, so gate/escalation (arbiter) and loop.maxIterations
+  // (cap) must be byte-identical; anything else that validates is a legal
+  // free-axis revision.
+  /** @param {any} candidate */
+  const acceptRevision = (candidate) => {
+    if (!candidate) return { code: 'parse-error' };
+    const cv = validateConfig(candidate, { shellCapUsd });
+    if (!cv.ok) return { code: 'validation', reds: cv.reds };
+    if (JSON.stringify(candidate.gate) !== JSON.stringify(config.gate)
+        || JSON.stringify(candidate.escalation) !== JSON.stringify(config.escalation)) {
+      return { code: 'arbiter-touch' };
+    }
+    if (candidate.loop?.maxIterations !== config.loop.maxIterations) return { code: 'cap-touch' };
+    return null;
+  };
+
+  /** @type {string[]} */
+  const gaps = [];
+  let revised = false;
+  /**
+   * @param {number} iteration
+   * @param {string} [gap]
+   */
+  const middle = async (iteration, gap) => {
+    if (gap) gaps.push(gap);
+    if (revisor && !revised && gaps.length >= STALL_REDS) {
+      emit('stall-detected', { iteration, consecutiveReds: gaps.length });
+      revised = true; // one revision per run, spent even if rejected
+      let rv;
+      try {
+        // the run's own gate handlers ride along: revisor spend hits the same
+        // budget axis as the worker; a budget halt mid-revision is a cap story,
+        // not a revision bug
+        rv = await revisor({ config, gaps: [...gaps], policy, onLlmResult });
+      } catch (e) {
+        if (e instanceof HaltError) /** @type {CategorizedError} */ (e).category = 'cap-halt';
+        throw e;
+      }
+      const red = acceptRevision(rv.candidate);
+      if (red) {
+        emit('revision-red', { iteration, ...red, detail: rv.parseError ?? undefined, costUsd: rv.costUsd ?? 0 });
+      } else {
+        emit('revision-accepted', { iteration, changedPaths: diffPaths(config, rv.candidate), costUsd: rv.costUsd ?? 0 });
+        config = rv.candidate;
+      }
+    }
+    if (gap) await runOps('after-red', { iteration, gap, context: {} });
+    const context = {};
+    await runOps('before-attempt', { iteration, context });
+    const parts = [task, context.text && `Possibly relevant notes:\n${context.text}`, gap && `Previous attempt failed the test suite:\n${gap}`];
+
+    if (config.loop.shape === 'plan') {
+      // plan-then-execute: one call to decompose, one to implement following the plan
+      const p = await ask([`Produce a SHORT numbered implementation plan (2-4 steps) for this task. Plan only, no code.`, ...parts.slice(1), parts[0]].filter(Boolean).join('\n\n'));
+      emit('worker-plan', { iteration, costUsd: p.metrics?.costUsd ?? p.cost ?? null }); // metrics.costUsd carries the honest null when unpriced; cost sums priced rounds only
+      parts.push(`Follow this plan:\n${p.text}`);
+    }
+    const r = await ask(parts.filter(Boolean).join('\n\n'));
+    emit('worker-result', { iteration, costUsd: r.metrics?.costUsd ?? r.cost ?? null, tokens: r.usage?.outputTokens ?? null });
+
+    const decision = await gate.check({ type: 'write', path: target, args: { bytes: r.text.length } });
+    if (decision.outcome !== 'allow') {
+      const err = /** @type {CategorizedError} */ (new Error(`gate ${decision.outcome} write to ${target} (${decision.rule ?? 'no rule'})`));
+      err.category = decision.severity === 'halt' ? 'cap-halt' : 'gate-red';
+      throw err;
+    }
+    writeFileSync(target, stripFences(r.text));
+    emit('artifact-written', { iteration, path: target });
+  };
+
+  // the config may tighten the shell's iteration budget, never exceed it (mirrors budgetUsd)
+  const effectiveCap = Math.min(capRuns, config.loop.maxIterations ?? capRuns);
+  const outcome = await ralph({ middle, close, capRuns: effectiveCap, emit });
+  if (outcome === 'green') {
+    // The close already passed — a retention hiccup must not un-green a real
+    // green (it would corrupt the learning curve). It degrades loudly:
+    // retention-red on the spine means this green mints NO inheritance, but
+    // the delivery stands (adaptlearn F5).
+    try {
+      await runOps('on-green', {});
+    } catch (e) {
+      emit('retention-red', { category: 'retention-red', detail: String(/** @type {Error} */ (e).message || e) });
+    }
+  }
+  // Design law #2 (adaptlearn F18): the run-as-executed record. A mid-run
+  // revision changes `config`; without this event the revised config dies with
+  // the run and every inheritance channel reads only the config-as-authored.
+  emit('config-final', { config, revised });
+  return outcome;
+}

package/src/ralph.js

@@ -0,0 +1,109 @@
+// 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).
+ * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
+ */
+export function runClose(close) {
+  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.
+  return { verdict: 'needs_revision', gap: (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
+ * @returns {Promise<'green'|'escalated'>}
+ */
+export async function ralph({ middle, close, capRuns, emit }) {
+  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);
+    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*$/, '');