@optitransfer/proofline 0.0.0-stage → 0.2.0-next.1

package/src/isolate.mjs

@@ -0,0 +1,123 @@
+// Opt-in isolation for command, red-green and metric checks.
+// Off unless the caller passes isolated, or the process was started with --isolated.
+// The image digest lives in the contract under test (a fixture in the TB-06 test), never invented here.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DIGEST = /^node:22\.11\.0@sha256:[0-9a-f]{64}$/;
+
+/** Evasions the static checks do not catch. Each fixture directory uses one of these names. */
+export const COVERAGE_LIMITS = [
+  'computed-dynamic-import',
+  'env-dependent-test',
+  'benchmark-code-edited',
+  'timeout-raised-through-config',
+  'test-removed-by-rename',
+  'test-weakened-by-snapshot',
+  'suite-command-wrapper',
+  'network-dependent-pass',
+  'pre-generated-cache',
+  'check-reads-contract',
+];
+
+export function imageDigest(contract) {
+  const image = contract?.env?.image;
+  return typeof image === 'string' && DIGEST.test(image) ? image : null;
+}
+
+function hasBin(bin) {
+  const r = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 5000 });
+  return r.status === 0;
+}
+
+export function runtimeName() {
+  if (hasBin('docker')) return 'docker';
+  if (hasBin('podman')) return 'podman';
+  if (hasBin('bwrap')) return 'bwrap';
+  return null;
+}
+
+function result(cmd, cwd, started, child) {
+  const ms = Math.round(performance.now() - started);
+  const timedOut = child.error?.code === 'ETIMEDOUT';
+  return {
+    cmd, cwd, ms, timedOut,
+    exit: timedOut ? 124 : (child.status ?? 1),
+    stdout: child.stdout || '',
+    stderr: (child.stderr || '') + (child.error && !timedOut ? String(child.error) : ''),
+  };
+}
+
+function bwrapArgs(cmd, cwd, extra, writable) {
+  const args = ['--unshare-net', '--die-with-parent', '--ro-bind', '/', '/', '--tmpfs', '/tmp', '--clearenv', '--setenv', 'HOME', '/tmp', '--setenv', 'PATH', '/usr/local/bin:/usr/bin:/bin'];
+  if (cwd) {
+    args.push('--ro-bind', cwd, '/work', '--chdir', '/work');
+    for (const rel of writable) args.push('--bind', path.resolve(cwd, rel), path.posix.join('/work', rel));
+  } else {
+    args.push('--chdir', '/tmp');
+  }
+  for (const [k, val] of extra) args.push('--setenv', k, String(val));
+  args.push('--', 'sh', '-c', cmd);
+  return args;
+}
+
+function dockerArgs(cmd, cwd, image, extra, writable) {
+  const args = ['run', '--rm', '--network', 'none', '--read-only', '--tmpfs', '/tmp', '-e', 'HOME=/tmp'];
+  if (cwd) {
+    args.push('-v', `${cwd}:/work:ro`, '-w', '/work');
+    for (const rel of writable) args.push('-v', `${path.resolve(cwd, rel)}:/work/${rel}:rw`);
+  }
+  for (const [k, val] of extra) args.push('-e', `${k}=${val}`);
+  args.push('--entrypoint', 'sh', image, '-c', cmd);
+  return args;
+}
+
+/** One copy under the home directory, which a desktop runtime can mount when the work tree is not shared. */
+function stageCopy(cwd) {
+  const parent = path.join(os.homedir(), '.cache', 'proofline-isolate');
+  fs.mkdirSync(parent, { recursive: true });
+  const dest = fs.mkdtempSync(path.join(parent, 'work-'));
+  fs.cpSync(cwd, dest, { recursive: true, dereference: false });
+  return dest;
+}
+
+/** Run cmd with no network, a fresh HOME, and the repo read-only except declared paths. */
+export function runInSandbox(cmd, { cwd, timeoutS = 600, env, image, runtime, writable = [] } = {}) {
+  const started = performance.now();
+  const extra = Object.entries(env || {}).filter(([k]) => k !== 'NODE_TEST_CONTEXT');
+  const argsFor = (dir) => runtime === 'bwrap'
+    ? bwrapArgs(cmd, dir, extra, writable)
+    : dockerArgs(cmd, dir, image, extra, writable);
+  const spawn = (args) => spawnSync(runtime, args, { encoding: 'utf8', timeout: timeoutS * 1000, maxBuffer: 64 << 20 });
+  let child = spawn(argsFor(cwd));
+  if (cwd && runtime !== 'bwrap' && /Mounts denied/.test(child.stderr || '')) {
+    const staged = stageCopy(cwd);
+    try {
+      child = spawn(argsFor(staged));
+    } finally {
+      fs.rmSync(staged, { recursive: true, force: true });
+    }
+  }
+  return result(cmd, cwd, started, child);
+}
+
+/**
+ * Isolation for one verify. Missing env.image refuses and names that item.
+ * A runtime is probed only after the caller asked for isolation and the digest is present.
+ */
+export function resolveIsolation(contract, opts = {}) {
+  const requested = opts.isolated === true || (opts.isolated !== false && process.argv.includes('--isolated'));
+  if (!requested) return { isolated: false, env_digest: null, block: null, sandbox: null };
+  const image = imageDigest(contract);
+  if (!image) return { isolated: false, env_digest: null, block: 'env.image is required for --isolated', sandbox: null };
+  const runtime = runtimeName();
+  if (!runtime) return { isolated: false, env_digest: null, block: 'no container runtime for --isolated', sandbox: null };
+  const sandbox = (cmd, o) => runInSandbox(cmd, { ...o, image, runtime, writable: o.writable || [] });
+  // The version probe does not need the work tree. Mounting it fails where the desktop runtime cannot see that path.
+  const ver = sandbox('node --version', { timeoutS: 60 });
+  const nodeVer = (ver.stdout || '').trim().split('\n')[0] || 'unknown';
+  const env_digest = `${image} runtime=${runtime} node=${nodeVer}`;
+  return { isolated: true, env_digest, block: null, sandbox };
+}

package/src/mcp.mjs

@@ -0,0 +1,70 @@
+// Minimal MCP server (JSON-RPC 2.0 over newline-delimited stdio). Zero dependencies.
+import readline from 'node:readline';
+import * as P from './index.mjs';
+import { verifyReceipt } from './verify-receipt.mjs';
+import { buildReceipt } from './receipt.mjs';
+
+const BASE = { type: 'string', description: 'The revision the task started from. Needed in a fresh clone unless task_next pinned it or HEAD carries a Proofline-Base: trailer.' };
+const FRESH = { type: 'boolean', description: 'Run every check again, ignoring results reused under defaults.reuse_results.' };
+const OWNER = { type: 'string', description: "Only this owner's tasks and unowned ones; never another owner's." };
+const TOOLS = [
+  { name: 'contract_create', description: 'Add a task contract (id, title, phase, depends_on, scope, criteria with deterministic verifiers). Returns validity problems; a task without verifiers cannot pass.', inputSchema: { type: 'object', properties: { task: { type: 'object' } }, required: ['task'] } },
+  { name: 'task_next', description: 'Return the single next task (phase- and dependency-gated) with its full brief. Call this before starting any work.', inputSchema: { type: 'object', properties: { owner: OWNER } } },
+  { name: 'evidence_record', description: 'Record agent-side evidence (notes, commands you ran). Stored hash-chained, but never used to pass a gate: verify re-runs everything itself.', inputSchema: { type: 'object', properties: { type: { type: 'string' }, data: { type: 'object' } }, required: ['type'] } },
+  { name: 'verify', description: 'Independently run every acceptance check for a task, plus forbidden-action, scope, wiring and claim checks. Returns decision and a corrective prompt.', inputSchema: { type: 'object', properties: { task: { type: 'string' }, claims: { type: 'string', description: 'Your status line(s): TASK-ID | status | commit | tests | measured vs target | missing' }, base: BASE, fresh: FRESH }, required: ['task'] } },
+  { name: 'gate', description: 'Release decision PASS/FAIL/BLOCKED with Markdown+JSON evidence report.', inputSchema: { type: 'object', properties: { task: { type: 'string' }, claims: { type: 'string' }, base: BASE, fresh: FRESH }, required: ['task'] } },
+  { name: 'report', description: 'Latest gate report for a task (Markdown).', inputSchema: { type: 'object', properties: { task: { type: 'string' } }, required: ['task'] } },
+  { name: 'status', description: 'Task and phase status, evidence-chain integrity.', inputSchema: { type: 'object', properties: { owner: OWNER } } },
+  { name: 'receipt', description: 'Infer a receipt from the base revision. Returns the same JSON the CLI prints with --json.', inputSchema: { type: 'object', properties: { task: { type: 'string' }, base: { type: 'string', description: 'The revision the receipt is inferred from.' }, role: { type: 'string' }, vault: { type: 'boolean', description: 'Attach a hivevault digest and write the note when the daemon answers.' } } } },
+  { name: 'verify_receipt', description: 'Check a DSSE receipt envelope offline. Returns the same JSON verify-receipt prints with --json.', inputSchema: { type: 'object', properties: { path: { type: 'string' }, recompute: { type: 'boolean' }, base: BASE }, required: ['path'] } },
+];
+
+
+
+export function handle(root, msg) {
+  const { id, method, params = {} } = msg;
+  const ok = (result) => ({ jsonrpc: '2.0', id, result });
+  if (method === 'initialize') return ok({ protocolVersion: params.protocolVersion || '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'proofline', version: '0.1.0' } });
+  if (method === 'ping') return ok({});
+  if (method === 'tools/list') return ok({ tools: TOOLS });
+  if (method === 'tools/call') {
+    const a = params.arguments || {};
+    try {
+      let r;
+      switch (params.name) {
+        case 'contract_create': r = P.contractCreate(root, a.task); break;
+        case 'task_next': r = P.taskNext(root, { owner: a.owner }); break;
+        case 'evidence_record': r = P.evidenceRecord(root, a.type, a.data || {}); break;
+        case 'verify': { const g = P.E.verifyTask(root, a.task, { claims: a.claims, base: a.base, fresh: a.fresh === true }); r = { ...g, corrective_prompt: P.E.steer(g, P.C.load(root)) }; break; }
+        case 'gate': r = P.E.gate(root, a.task, { claims: a.claims, base: a.base, fresh: a.fresh === true }); break;
+        case 'report': r = P.report(root, a.task); break;
+        case 'status': r = P.status(root, { owner: a.owner }); break;
+        case 'receipt':
+          return buildReceipt(root, a).then((got) => ok({ content: [{ type: 'text', text: JSON.stringify(got, null, 2) }], isError: false })).catch((e) => ok({ content: [{ type: 'text', text: `error: ${e.message}` }], isError: true }));
+        case 'verify_receipt':
+          return verifyReceipt(a.path, { root, recompute: a.recompute === true, base: a.base }).then((got) => ok({ content: [{ type: 'text', text: JSON.stringify(got, null, 2) }], isError: false })).catch((e) => ok({ content: [{ type: 'text', text: `error: ${e.message}` }], isError: true }));
+        default: return { jsonrpc: '2.0', id, error: { code: -32601, message: `unknown tool ${params.name}` } };
+      }
+      const text = r.brief ? r.brief + '\n\n' + JSON.stringify({ task: r.task, phase: r.phase }) : r.corrective_prompt ? `DECISION: ${r.decision}\n\n${r.corrective_prompt}\n\n${JSON.stringify({ decision: r.decision, failing: r.failing, blocked: r.blocked, measured: r.measured })}` : r.markdown || JSON.stringify(r, null, 2);
+      return ok({ content: [{ type: 'text', text }], isError: false });
+    } catch (e) { return ok({ content: [{ type: 'text', text: `error: ${e.message}` }], isError: true }); }
+  }
+  if (id === undefined) return null; // notification
+  return { jsonrpc: '2.0', id, error: { code: -32601, message: `method not found: ${method}` } };
+}
+
+export function serve(root) {
+  const rl = readline.createInterface({ input: process.stdin });
+  let chain = Promise.resolve();
+  rl.on('line', (line) => {
+    chain = chain.then(async () => {
+      if (!line.trim()) return;
+      let msg;
+      try { msg = JSON.parse(line); }
+      catch { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }) + '\n'); return; }
+      const r = await Promise.resolve(handle(root, msg));
+      if (r) process.stdout.write(JSON.stringify(r) + '\n');
+    });
+  });
+  return new Promise((res) => rl.on('close', () => chain.then(res)));
+}

package/src/receipt.mjs

@@ -0,0 +1,17 @@
+// One receipt for a revision range. A missing daemon leaves the receipt unchanged.
+import { receiptZeroConfig } from './infer.mjs';
+import { attachMemory, probeDigest, receiptNote, writeReceiptNote } from './vault.mjs';
+
+export async function buildReceipt(root, a = {}) {
+  const receipt = receiptZeroConfig(root, { base: a.base });
+  if (a.vault !== true) return receipt;
+  const digest = await probeDigest();
+  const attached = attachMemory(receipt, digest);
+  const note = receiptNote({
+    receipt: attached.receipt,
+    role: typeof a.role === 'string' && a.role ? a.role : 'agent',
+    subject: typeof a.task === 'string' ? a.task : '',
+  });
+  await writeReceiptNote(note, { vault: true });
+  return attached.receipt;
+}

package/src/signature.mjs

@@ -0,0 +1,110 @@
+// Owner signature over the canonical contract. The public key is read from guard/owner.pub only.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import * as C from './contract.mjs';
+import { git, sha256 } from './util.mjs';
+
+export const PAYLOAD_TYPE = 'application/vnd.proofline.contract-sha256';
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function canonicalHash(root) {
+  return sha256(canonical(JSON.parse(fs.readFileSync(C.contractPath(root), 'utf8'))));
+}
+
+function pae(payloadType, body) {
+  const t = Buffer.from(payloadType);
+  const b = Buffer.from(body);
+  return Buffer.concat([Buffer.from(`DSSEv1 ${t.length} `), t, Buffer.from(` ${b.length} `), b]);
+}
+
+function agentkeyBin(env) {
+  for (const dir of String(env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const f = path.join(dir, 'agentkey');
+    try {
+      const st = fs.statSync(f);
+      if (st.isFile() && (st.mode & 0o111)) return f;
+    } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+/** Armed only when guard/owner.pub is present. A missing pin is reported, and no other key path is opened. */
+export function verifyContractSignature(root) {
+  const pubPath = path.join(root, 'guard', 'owner.pub');
+  let pem;
+  try { pem = fs.readFileSync(pubPath, 'utf8'); }
+  catch { return { ok: false, armed: false, detail: 'guard/owner.pub is missing' }; }
+  let envelope;
+  try { envelope = JSON.parse(fs.readFileSync(path.join(root, 'proofline.json.sig'), 'utf8')); }
+  catch { return { ok: false, armed: true, detail: 'proofline.json.sig is missing or not a signature' }; }
+  if (!envelope || envelope.payloadType !== PAYLOAD_TYPE || typeof envelope.payload !== 'string') {
+    return { ok: false, armed: true, detail: 'proofline.json.sig is not an owner signature' };
+  }
+  let payload;
+  try { payload = Buffer.from(envelope.payload, 'base64').toString('utf8'); }
+  catch { return { ok: false, armed: true, detail: 'signature payload is not base64' }; }
+  const hash = canonicalHash(root);
+  if (payload !== hash) return { ok: false, armed: true, detail: 'signature is not over the current contract' };
+  const sig = envelope.signatures?.[0]?.sig;
+  if (typeof sig !== 'string') return { ok: false, armed: true, detail: 'signature is missing' };
+  try {
+    const key = crypto.createPublicKey(pem);
+    const ok = crypto.verify(null, pae(PAYLOAD_TYPE, Buffer.from(payload)), key, Buffer.from(sig, 'base64'));
+    if (!ok) return { ok: false, armed: true, detail: 'signature does not verify against guard/owner.pub' };
+  } catch {
+    return { ok: false, armed: true, detail: 'guard/owner.pub is not a usable public key' };
+  }
+  return { ok: true, armed: true, detail: 'owner signature matches' };
+}
+
+/** Owner laptop: agentkey signs the canonical hash. AGENTKEY_HOME is required, so the default key directory is never opened. */
+export function signContract(root, env = process.env) {
+  const home = env.AGENTKEY_HOME;
+  if (typeof home !== 'string' || !home.trim()) {
+    throw new Error('AGENTKEY_HOME is not set, so no key directory was opened\nNext step: proofline contract sign');
+  }
+  const bin = agentkeyBin(env);
+  if (!bin) throw new Error('agentkey is not on PATH\nNext step: proofline contract sign');
+  const hash = canonicalHash(root);
+  const r = spawnSync(bin, ['sign', 'owner', '--type', PAYLOAD_TYPE], {
+    input: hash, encoding: 'utf8', env: { ...env, AGENTKEY_HOME: home },
+  });
+  if (r.error || r.status !== 0) throw new Error(`agentkey sign owner failed\nNext step: proofline contract sign`);
+  JSON.parse(r.stdout);
+  fs.writeFileSync(path.join(root, 'proofline.json.sig'), r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
+  return `${hash}\n`;
+}
+
+function unified(before, after) {
+  const a = path.join(os.tmpdir(), `pl-sig-a-${process.pid}`);
+  const b = path.join(os.tmpdir(), `pl-sig-b-${process.pid}`);
+  fs.writeFileSync(a, before);
+  fs.writeFileSync(b, after);
+  const r = spawnSync('diff', ['-u', a, b], { encoding: 'utf8' });
+  fs.rmSync(a, { force: true });
+  fs.rmSync(b, { force: true });
+  return r.stdout || '';
+}
+
+/** The agent path: write proposals/<sha256>.diff and print the hash. It does not change proofline.json. */
+export function proposeContract(root) {
+  const current = fs.readFileSync(C.contractPath(root));
+  const shown = git(['show', 'HEAD:proofline.json'], root);
+  const diff = unified(shown.ok ? shown.out : '', current);
+  const hex = sha256(diff);
+  const dir = path.join(root, '.proofline', 'proposals');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${hex}.diff`), diff);
+  return `${hex}\n`;
+}

package/src/util.mjs

@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+/** Owner marker for these exact bytes. The directory comes from `init --approvals`. A symlink is not a regular file. */
+export function approvalMarker(root, bytes) {
+  let dir = null;
+  try {
+    const c = JSON.parse(fs.readFileSync(path.join(root, '.proofline', 'config.json'), 'utf8'));
+    if (typeof c.approvals === 'string' && c.approvals.trim()) dir = c.approvals;
+  } catch { dir = null; }
+  if (!bytes) return { hex: null, marker: null, approved: false };
+  const hex = sha256(bytes);
+  const marker = dir ? path.join(dir, hex) : null;
+  let approved = false;
+  if (marker) { try { approved = fs.lstatSync(marker).isFile(); } catch { approved = false; } }
+  return { hex, marker, approved };
+}
+
+/** Stable JSON (sorted keys) so hashes are reproducible. */
+export function canon(v) {
+  if (Array.isArray(v)) return '[' + v.map(canon).join(',') + ']';
+  if (v && typeof v === 'object') return '{' + Object.keys(v).sort().filter((k) => v[k] !== undefined).map((k) => JSON.stringify(k) + ':' + canon(v[k])).join(',') + '}';
+  return JSON.stringify(v ?? null);
+}
+
+/** Run a shell command; never throws. */
+export function run(cmd, { cwd, timeoutS = 600, env } = {}) {
+  const t = performance.now();
+  // NODE_TEST_CONTEXT leaks from an enclosing `node --test` and makes a nested `node --test` exit 0 regardless of failures.
+  const e = { ...process.env, ...env }; delete e.NODE_TEST_CONTEXT;
+  // A pre-push hook exports GIT_DIR. A test or command that inits its own repository must not use it.
+  for (const k of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY', 'GIT_NAMESPACE', 'GIT_QUARANTINE_PATH']) delete e[k];
+  const r = spawnSync('bash', ['-c', cmd], { cwd, encoding: 'utf8', timeout: timeoutS * 1000, env: e, maxBuffer: 64 << 20 });
+  const ms = Math.round(performance.now() - t);
+  const timedOut = r.error?.code === 'ETIMEDOUT';
+  return { cmd, cwd, exit: timedOut ? 124 : (r.status ?? 1), stdout: r.stdout || '', stderr: (r.stderr || '') + (r.error && !timedOut ? String(r.error) : ''), ms, timedOut };
+}
+
+export function git(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 << 20 });
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() };
+}
+
+/** Where commit `sha` stands against <remote>/<branch>. { ok: false, err } when the remote cannot be read; otherwise
+ * { ok: true, tip, at, contains, behind, unknown }. A tip this repository lacks is fetched by the branch's name with no ref
+ * written (--refmap= keeps the remote-tracking ref, --no-write-fetch-head keeps FETCH_HEAD), so a commit under the tip is
+ * found without a fetch beforehand. `unknown`: the tip could not be fetched, so whether it holds the commit is not known. */
+export function onRemote(root, sha, remote, branch) {
+  const ls = git(['ls-remote', remote, `refs/heads/${branch}`], root);
+  if (!ls.ok) return { ok: false, err: ls.err || `git ls-remote ${remote} failed` };
+  const tip = ls.out.split(/\s/)[0] || '';
+  if (!tip) return { ok: true, tip: '', at: false, contains: false, behind: null, unknown: false };
+  if (tip === sha) return { ok: true, tip, at: true, contains: true, behind: 0, unknown: false };
+  const have = () => git(['cat-file', '-e', `${tip}^{commit}`], root).ok;
+  if (!have()) git(['fetch', '-q', '--no-tags', '--refmap=', '--no-write-fetch-head', remote, `refs/heads/${branch}`], root);
+  if (!have()) return { ok: true, tip, at: false, contains: false, behind: null, unknown: true };
+  const contains = git(['merge-base', '--is-ancestor', sha, tip], root).ok;
+  return { ok: true, tip, at: false, contains, behind: contains ? Number(git(['rev-list', '--count', `${sha}..${tip}`], root).out) : null, unknown: false };
+}
+
+export const tail = (s, n = 1500) => (s.length > n ? '…' + s.slice(-n) : s);
+
+/** Minimal glob → RegExp: ** , * , ? */
+export function globRe(g) {
+  let re = '';
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === '*' && g[i + 1] === '*') { re += '.*'; i++; if (g[i + 1] === '/') i++; }
+    else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp('^' + re + '$');
+}
+export const matchAny = (p, globs) => globs.some((g) => globRe(g).test(p));
+
+/** Read a dotted path like "latency.p50" from an object. */
+export const pick = (o, p) => p.split('.').reduce((a, k) => (a == null ? undefined : a[k]), o);
+
+export function readJson(f, d) { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } }
+export function writeJson(f, v) { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, JSON.stringify(v, null, 2) + '\n'); }
+
+/** Last JSON object found in a text (bench scripts print JSON as the last line). */
+export function lastJson(text) {
+  const lines = text.trim().split('\n').reverse();
+  for (const l of lines) { const s = l.trim(); if (s.startsWith('{')) { try { return JSON.parse(s); } catch {} } }
+  try { return JSON.parse(text); } catch { return undefined; }
+}

package/src/vault.mjs

@@ -0,0 +1,109 @@
+// Attach a hivevault digest to a receipt, and write the note when asked.
+// A missing daemon leaves the receipt unchanged. The probe gives up after 2 seconds.
+import crypto from 'node:crypto';
+
+const DIGEST_PATH = '/v1/state/digest';
+
+function sha256(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+/** GET the digest. Returns null when the daemon is absent, refuses, or exceeds the timeout. */
+export async function probeDigest(url, token, { timeout = 2000 } = {}) {
+  const base = url || process.env.HIVEVAULT_URL || 'http://127.0.0.1:7788';
+  const bearer = token ?? process.env.HIVEVAULT_TOKEN ?? '';
+  try {
+    const res = await fetch(new URL(DIGEST_PATH, base), {
+      headers: bearer ? { authorization: `Bearer ${bearer}` } : {},
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (!body || typeof body.digest !== 'string') return null;
+    return body;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Copy a digest onto a receipt.
+ * L1 gets memory.vault_digest and memory.frontier.
+ * mode `ci` (an L2 receipt) gets only memory_commitment, so a replica id stays inside the hash.
+ * No digest: the receipt is returned without a memory field, and exitCode is unchanged.
+ */
+export function attachMemory(receipt, digest, { mode = 'local', vaultId = '' } = {}) {
+  const exitCode = receipt?.exitCode ?? 0;
+  if (!digest) {
+    const next = { ...receipt };
+    delete next.memory;
+    delete next.memory_commitment;
+    return { receipt: next, exitCode };
+  }
+  if (mode === 'ci' || receipt?.level === 'L2') {
+    const commitment = sha256(`${vaultId || digest.vault_id || digest.replica || ''}${digest.digest}${JSON.stringify(digest.frontier ?? null)}`);
+    const next = { ...receipt, memory_commitment: commitment };
+    delete next.memory;
+    return { receipt: next, exitCode };
+  }
+  const next = {
+    ...receipt,
+    memory: { vault_digest: digest.digest, frontier: digest.frontier ?? null },
+  };
+  delete next.memory_commitment;
+  return { receipt: next, exitCode };
+}
+
+export function receiptNotePath({ date, role = 'agent', sha }) {
+  const day = (date instanceof Date ? date : new Date(date || Date.now())).toISOString().slice(0, 10);
+  const short = String(sha || '').slice(0, 7);
+  return `work/receipts/${day}-${role}-${short}.md`;
+}
+
+export function receiptNote({ receipt, role = 'agent', subject = '', agent = '', summary = '', envelopeSha = '', date } = {}) {
+  const level = receipt?.level || 'L1';
+  const frontmatter = {
+    kind: 'proof-receipt',
+    level,
+    subject,
+    agent,
+    predicate_type: 'https://proofline.dev/receipt/v1',
+    summary,
+    envelope_sha256: envelopeSha,
+    origin: 'proofline',
+  };
+  const lines = ['| field | value |', '| --- | --- |', `| level | ${level} |`, `| subject | ${subject} |`];
+  if (receipt?.memory) lines.push(`| vault_digest | ${receipt.memory.vault_digest} |`);
+  if (receipt?.memory_commitment) lines.push('| memory_commitment | present |');
+  const body = `${lines.join('\n')}\n\n\`\`\`json\n${JSON.stringify(receipt, null, 2)}\n\`\`\`\n`;
+  const rel = receiptNotePath({ date, role, sha: envelopeSha });
+  const fm = ['---', ...Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`), '---', ''].join('\n');
+  return { path: rel, frontmatter, body, text: fm + body };
+}
+
+/** PUT the note. origin is proofline. Returns null when the write does not land. */
+export async function writeReceiptNote(note, { url, token, timeout = 2000, vault = false } = {}) {
+  const base = url || process.env.HIVEVAULT_URL || 'http://127.0.0.1:7788';
+  const bearer = token ?? process.env.HIVEVAULT_TOKEN ?? '';
+  if (process.env.PROOFLINE_VAULT !== '1' && vault !== true) return null;
+  try {
+    const res = await fetch(new URL(`/v1/notes/${note.path}`, base), {
+      method: 'PUT',
+      headers: {
+        'content-type': 'application/json',
+        ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+      },
+      body: JSON.stringify({
+        frontmatter: note.frontmatter,
+        body: note.body,
+        origin: 'proofline',
+        commit_message: `proofline receipt ${note.path}`,
+      }),
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!res.ok) return null;
+    return { path: note.path, status: res.status };
+  } catch {
+    return null;
+  }
+}

package/src/verify-receipt.mjs

@@ -0,0 +1,109 @@
+// Verify a receipt envelope. Offline unless --sigstore is asked for, and that import is lazy.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { receiptZeroConfig } from './infer.mjs';
+
+const STATEMENT = 'https://in-toto.io/Statement/v1';
+const PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+const PREDICATE_TYPE = 'https://proofline.dev/receipt/v1';
+
+export function pae(payloadType, payload) {
+  const t = Buffer.from(payloadType);
+  const b = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  return Buffer.concat([Buffer.from(`DSSEv1 ${t.length} `), t, Buffer.from(` ${b.length} `), b]);
+}
+
+function fromB64(s) {
+  if (typeof s !== 'string' || !/^[A-Za-z0-9+/_=-]+$/.test(s)) return null;
+  return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}
+
+function loadKeys(dir) {
+  const out = new Map();
+  if (!dir || !fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.pem')) continue;
+    const pem = fs.readFileSync(path.join(dir, name), 'utf8');
+    out.set(name.slice(0, -4), crypto.createPublicKey(pem));
+  }
+  return out;
+}
+
+function schemaProblem(statement) {
+  if (!statement || statement._type !== STATEMENT) return 'statement _type';
+  if (statement.predicateType !== PREDICATE_TYPE) return 'predicateType';
+  const p = statement.predicate;
+  if (!p || typeof p !== 'object') return 'predicate';
+  if (!['L0', 'L1', 'L2'].includes(p.level)) return 'predicate.level';
+  if (p.agent != null && typeof p.agent !== 'object') return 'predicate.agent';
+  return null;
+}
+
+function result(exitCode, message, extra = {}) {
+  return { exitCode, message, differences: extra.differences || [], level: extra.level || null, ...extra };
+}
+
+function verifySignatures(envelope, keys) {
+  if (!envelope || typeof envelope.payloadType !== 'string' || typeof envelope.payload !== 'string' || !Array.isArray(envelope.signatures) || !envelope.signatures.length) {
+    return { problem: 'schema', detail: 'a DSSE envelope needs payloadType, payload and one signature' };
+  }
+  const body = fromB64(envelope.payload);
+  if (!body) return { problem: 'schema', detail: 'payload is not base64' };
+  const data = pae(envelope.payloadType, body);
+  let verified = 0;
+  let unknown = 0;
+  let failed = 0;
+  for (const s of envelope.signatures) {
+    const id = typeof s?.keyid === 'string' ? s.keyid : '';
+    const sig = fromB64(s?.sig || '');
+    const key = keys.get(id);
+    if (!key || !sig) { unknown++; continue; }
+    const ok = crypto.verify(null, data, key, sig);
+    if (ok) verified++;
+    else failed++;
+  }
+  return { body, verified, unknown, failed };
+}
+
+/**
+ * @param {string} envelopePath
+ * @param {{ root?: string, keys?: string, sigstore?: boolean, recompute?: boolean, base?: string, suite?: boolean }} [opts]
+ */
+export async function verifyReceipt(envelopePath, opts = {}) {
+  if (!envelopePath) return result(3, 'usage: verify-receipt <envelope>');
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(envelopePath, 'utf8')); }
+  catch { return result(1, 'envelope is not JSON'); }
+  if (opts.sigstore) return verifySigstore(raw);
+  const keys = loadKeys(opts.keys || (process.env.AGENTKEY_HOME ? path.join(process.env.AGENTKEY_HOME, 'keys') : ''));
+  const sig = verifySignatures(raw, keys);
+  if (sig.problem) return result(1, sig.detail);
+  if (sig.failed) return result(1, 'signature failed');
+  if (!sig.verified) return result(2, 'unknown key');
+  let statement;
+  try { statement = JSON.parse(sig.body.toString('utf8')); }
+  catch { return result(1, 'payload is not a statement'); }
+  if (raw.payloadType !== PAYLOAD_TYPE) return result(1, 'payloadType is not an in-toto statement');
+  const schema = schemaProblem(statement);
+  if (schema) return result(1, `schema: ${schema}`);
+  const level = statement.predicate.level;
+  if (!opts.recompute) return result(0, `verified\nlevel ${level}`, { level });
+  if (!opts.base) return result(3, '--recompute needs --base');
+  const live = receiptZeroConfig(opts.root || process.cwd(), { base: opts.base });
+  const recomputed = live.exitCode === 0 && live.level === 'L1' && live.suites.every((s) => s.status === 'pass');
+  const differences = [];
+  if (Boolean(statement.predicate.green_on_head) !== recomputed) {
+    differences.push(`green_on_head: envelope ${Boolean(statement.predicate.green_on_head)} recomputed ${recomputed}`);
+  }
+  if (differences.length) return result(1, differences.join('\n'), { level, differences });
+  return result(0, `verified\nlevel ${level}`, { level });
+}
+
+async function verifySigstore(bundle) {
+  const sigs = bundle?.verificationMaterial?.tlogEntries || bundle?.signatures || [];
+  if (sigs.length !== 1) return result(1, 'a sigstore bundle carries exactly one signature');
+  try { await import('sigstore'); }
+  catch { return result(2, 'sigstore verifier is not available'); }
+  return result(2, 'sigstore verification is not confirmed offline');
+}