@optitransfer/proofline 0.2.0-next.0 → 0.2.0-next.1

package/src/infer.mjs

@@ -0,0 +1,173 @@
+// Zero-config suite inference. Commands come from the base revision, never from the change under test.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { git, run } from './util.mjs';
+
+const RULES = JSON.parse(fs.readFileSync(new URL('./inference.json', import.meta.url), 'utf8'));
+const CHANGED = RULES.changed_tests.map((s) => new RegExp(s));
+
+export function inferenceRules() { return RULES; }
+
+export function isChangedTest(file) {
+  return CHANGED.some((re) => re.test(file));
+}
+
+function rel(dir, name) { return dir ? `${dir}/${name}` : name; }
+
+function hasAt(root, base, file) {
+  return git(['cat-file', '-e', `${base}:${file}`], root).ok;
+}
+
+function show(root, base, file) {
+  const s = git(['show', `${base}:${file}`], root);
+  return s.ok ? s.out : null;
+}
+
+function readWorktree(root, file) {
+  try { return fs.readFileSync(path.join(root, file), 'utf8'); } catch { return null; }
+}
+
+export function nodeCommand(pkg) {
+  const script = pkg?.scripts?.test;
+  if (typeof script === 'string' && script.trim()) return script.trim();
+  const dev = pkg?.devDependencies || {};
+  if (dev.vitest) return RULES.node.fallback_commands.vitest;
+  if (dev.jest) return RULES.node.fallback_commands.jest;
+  return null;
+}
+
+function toolchainOk(bin) {
+  if (!bin) return true;
+  const r = spawnSync('bash', ['-lc', `command -v ${bin}`], { encoding: 'utf8' });
+  return r.status === 0;
+}
+
+function parseJson(text) {
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/** Suites declared by the manifests at `base`. `dir` is a repo-relative directory. */
+export function suitesFromBase(root, base, dir = '') {
+  const out = [];
+  const pkgPath = rel(dir, 'package.json');
+  if (hasAt(root, base, pkgPath)) {
+    const command = nodeCommand(parseJson(show(root, base, pkgPath)));
+    if (command) out.push({ id: 'node', manifest: pkgPath, command, toolchain: null });
+  }
+  const cargo = rel(dir, 'Cargo.toml');
+  if (hasAt(root, base, cargo)) out.push({ id: 'rust', manifest: cargo, command: RULES.rust.command, toolchain: RULES.rust.toolchain });
+  const pyIni = rel(dir, 'pytest.ini');
+  const pyProj = rel(dir, 'pyproject.toml');
+  const pyText = hasAt(root, base, pyProj) ? show(root, base, pyProj) : null;
+  if (hasAt(root, base, pyIni) || (pyText && /\[tool\.pytest/.test(pyText))) {
+    out.push({ id: 'python', manifest: hasAt(root, base, pyIni) ? pyIni : pyProj, command: RULES.python.command, toolchain: RULES.python.toolchain });
+  }
+  const gomod = rel(dir, 'go.mod');
+  if (hasAt(root, base, gomod)) out.push({ id: 'go', manifest: gomod, command: RULES.go.command, toolchain: RULES.go.toolchain });
+  const gradle = rel(dir, 'build.gradle');
+  if (hasAt(root, base, gradle)) out.push({ id: 'gradle', manifest: gradle, command: null, toolchain: null });
+  const tree = git(['ls-tree', '--name-only', base, dir || '.'], root);
+  if (tree.ok && tree.out.split('\n').some((n) => n.endsWith('.sln'))) {
+    const file = tree.out.split('\n').find((n) => n.endsWith('.sln'));
+    out.push({ id: 'dotnet', manifest: file, command: null, toolchain: null });
+  }
+  return out;
+}
+
+export function changedTests(root, base) {
+  const s = git(['diff', '--name-only', base], root);
+  const names = s.ok ? s.out.split('\n').filter(Boolean) : [];
+  return names.filter(isChangedTest);
+}
+
+function scriptOf(text) {
+  const v = parseJson(text)?.scripts?.test;
+  return typeof v === 'string' ? v : null;
+}
+
+/** A test-command change against `base`. The command that runs stays the base command. */
+export function testCommandFindings(root, base) {
+  const findings = [];
+  const push = (file, line) => findings.push({
+    rule: 'test_command_changed', file, line,
+    why: 'the test command is taken from the base revision',
+  });
+  const baseScript = scriptOf(show(root, base, 'package.json'));
+  const headScript = scriptOf(readWorktree(root, 'package.json'));
+  if (baseScript !== headScript && (baseScript !== null || headScript !== null)) {
+    push('package.json', `${baseScript ?? ''} -> ${headScript ?? ''}`);
+  }
+  for (const file of ['Cargo.toml', 'pytest.ini']) {
+    const old = show(root, base, file);
+    const now = readWorktree(root, file);
+    if (old === null && now === null) continue;
+    if ((old ?? '').trim() !== (now ?? '').trim()) push(file, 'manifest changed');
+  }
+  const diff = git(['diff', '--name-only', base, '--', '.github/workflows'], root);
+  for (const file of (diff.ok ? diff.out.split('\n').filter(Boolean) : [])) push(file, 'workflow changed');
+  return findings;
+}
+
+function runCmd(cwd, command) {
+  const r = run(command, { cwd, timeoutS: 180 });
+  return { exitCode: r.exit, ran: true };
+}
+
+function runAtBase(root, base, command) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pl-infer-'));
+  const add = git(['worktree', 'add', '--detach', '--quiet', dir, base], root);
+  if (!add.ok) { fs.rmSync(dir, { recursive: true, force: true }); return null; }
+  try { return runCmd(dir, command); }
+  finally {
+    git(['worktree', 'remove', '--force', dir], root);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Infer a receipt with no contract. Nothing inferable returns L0 and exit 2, and does not throw.
+ * A missing toolchain is `blocked`, not `pass`.
+ */
+export function receiptZeroConfig(root, { base } = {}) {
+  const l0 = (reason, extra = {}) => ({ level: 'L0', exitCode: 2, reason, suites: [], changed: [], findings: [], ...extra });
+  if (!base) return l0('no base revision');
+  let suites, changed, findings;
+  try {
+    suites = suitesFromBase(root, base);
+    changed = changedTests(root, base);
+    findings = testCommandFindings(root, base);
+  } catch (e) {
+    return l0(String(e?.message || e));
+  }
+  if (!suites.length) return { ...l0('nothing inferable'), findings };
+  const ran = [];
+  for (const s of suites) {
+    if (!s.command || (s.toolchain && !toolchainOk(s.toolchain))) {
+      ran.push({ ...s, status: 'blocked', ran: false, exitCode: null });
+      continue;
+    }
+    const head = runCmd(root, s.command);
+    const baseRun = runAtBase(root, base, s.command);
+    ran.push({
+      ...s,
+      status: head.exitCode === 0 ? 'pass' : 'fail',
+      ran: true,
+      exitCode: head.exitCode,
+      baseExitCode: baseRun ? baseRun.exitCode : null,
+    });
+  }
+  if (!ran.some((s) => s.ran)) {
+    return { level: 'L0', exitCode: 0, reason: 'nothing ran', suites: ran, changed, findings };
+  }
+  return {
+    level: 'L1',
+    exitCode: ran.some((s) => s.status === 'fail') ? 1 : 0,
+    reason: '',
+    suites: ran,
+    changed,
+    findings,
+  };
+}

package/src/inference.json

@@ -0,0 +1,20 @@
+{
+  "changed_tests": [
+    "(^|/)(test|tests)/",
+    "_test\\.[^/]+$",
+    "\\.test\\.[^/]+$",
+    "\\.spec\\.[^/]+$",
+    "(^|/)test_[^/]+\\.py$"
+  ],
+  "node": {
+    "manifest": "package.json",
+    "script": "scripts.test",
+    "fallback_dev_dependencies": ["vitest", "jest"],
+    "fallback_commands": { "vitest": "vitest run", "jest": "jest" }
+  },
+  "rust": { "manifest": "Cargo.toml", "command": "cargo test", "toolchain": "cargo" },
+  "python": { "manifests": ["pytest.ini", "pyproject.toml"], "command": "pytest", "toolchain": "pytest" },
+  "go": { "manifest": "go.mod", "command": "go test ./...", "toolchain": "go" },
+  "gradle": { "manifest": "build.gradle" },
+  "dotnet": { "glob": "*.sln" }
+}

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

@@ -1,6 +1,8 @@
 // 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.' };
@@ -13,8 +15,12 @@ const TOOLS = [
   { 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 });
@@ -33,6 +39,10 @@ export function handle(root, msg) {
         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);
@@ -45,11 +55,16 @@ export function handle(root, msg) {
 
 export function serve(root) {
   const rl = readline.createInterface({ input: process.stdin });
+  let chain = Promise.resolve();
   rl.on('line', (line) => {
-    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 = handle(root, msg);
-    if (r) process.stdout.write(JSON.stringify(r) + '\n');
+    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', res));
+  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/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;
+  }
+}