yay-layer 1.0.0-rc.1

package/src/mutate.js

@@ -0,0 +1,192 @@
+'use strict';
+// Generate small, systematic corruptions ("mutants") of a unit's source, to grade
+// how strong its `ensures` is. Each mutant is a copy of the source with ONE edit.
+// We locate edit sites via the AST (@babel/parser) but splice the source string
+// directly, so no code-generator dependency is needed.
+
+const babel = require('@babel/parser');
+const PLUGINS = ['estree', 'typescript', 'jsx', 'decorators-legacy'];
+
+// operator → what we flip it to (each flip is a distinct bug class)
+const ARITH = { '+': '-', '-': '+', '*': '/', '/': '*', '%': '*' };
+const CMP = { '<': '>=', '>': '<=', '<=': '>', '>=': '<' };
+const EQ = { '==': '!=', '!=': '==', '===': '!==', '!==': '===' };
+const LOGIC = { '&&': '||', '||': '&&' };
+
+function parse(src) {
+  try {
+    return babel.parse(src, {
+      sourceType: 'unambiguous', errorRecovery: true,
+      allowReturnOutsideFunction: true, allowImportExportEverywhere: true, plugins: PLUGINS,
+    }).program;
+  } catch (_) { return null; }
+}
+
+function mutants(src, cap = 30) {
+  const ast = parse(src);
+  if (!ast) return [];
+  const out = [];
+  const seen = new Set();
+  const add = (start, end, rep, op) => {
+    if (start == null || end == null || start < 0 || end > src.length) return;
+    const key = start + ':' + end + ':' + rep;
+    if (seen.has(key)) return; seen.add(key);
+    out.push({ code: src.slice(0, start) + rep + src.slice(end), op });
+  };
+
+  (function walk(node) {
+    if (!node || typeof node.type !== 'string') return;
+    const v = node.value;
+
+    if ((node.type === 'BinaryExpression' || node.type === 'LogicalExpression') && node.left && node.right) {
+      const o = node.operator;
+      const map = (o in ARITH) ? ARITH : (o in CMP) ? CMP : (o in EQ) ? EQ : (o in LOGIC) ? LOGIC : null;
+      if (map && map[o] != null && node.left.end != null && node.right.start != null) {
+        const gap = src.slice(node.left.end, node.right.start);
+        const i = gap.indexOf(o);
+        if (i >= 0) { const s = node.left.end + i; add(s, s + o.length, map[o], `${o} → ${map[o]}`); }
+      }
+    }
+    // literals (estree: Literal; babel: Numeric/String/BooleanLiteral)
+    if (node.type === 'Literal' || node.type === 'NumericLiteral' || node.type === 'StringLiteral' || node.type === 'BooleanLiteral') {
+      if (typeof v === 'number') add(node.start, node.end, String(v + 1), `num ${v} → ${v + 1}`);
+      else if (typeof v === 'string') add(node.start, node.end, JSON.stringify(v + 'X'), 'string +"X"');
+      else if (typeof v === 'boolean') add(node.start, node.end, String(!v), `bool → ${!v}`);
+    }
+    // template literal static parts: /pfps/ → /pfps/X
+    if (node.type === 'TemplateElement' && node.value && node.value.raw && node.start != null) {
+      add(node.start, node.end, src.slice(node.start, node.end) + 'X', 'template +"X"');
+    }
+    if (node.type === 'ReturnStatement' && node.argument && node.argument.start != null) {
+      add(node.argument.start, node.argument.end, 'null', 'return → null');
+    }
+    if (node.type === 'UnaryExpression' && node.operator === '!' && node.argument && node.argument.start != null) {
+      add(node.start, node.argument.start, '', 'drop !');
+    }
+
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'start' || k === 'end' || k === 'range') continue;
+      const c = node[k];
+      if (Array.isArray(c)) c.forEach(walk);
+      else if (c && typeof c.type === 'string') walk(c);
+    }
+  })(ast);
+
+  return out.slice(0, cap);
+}
+
+// ── deletion candidates (for the INERTNESS check) ───────────────────────────
+// The dual of mutation: instead of corrupting code and asking "does the ensures
+// notice?", we DELETE a branch and ask "does anything notice?". A branch that can be
+// removed with every spec-derived test still passing is semantically inert under the
+// promise — dead weight, ahead-of-spec scaffolding, or a dormant payload. Each entry
+// is one candidate: { code, desc, line, removed } where `removed` is the deleted
+// source (used for the throws:-guard exemption).
+function lineOf(src, idx) { let n = 1; for (let i = 0; i < idx && i < src.length; i++) if (src[i] === '\n') n++; return n; }
+function deletions(src, cap = 20) {
+  const ast = parse(src);
+  if (!ast) return [];
+  const out = [];
+  const seen = new Set();
+  const add = (start, end, rep, desc) => {
+    if (start == null || end == null || start < 0 || end > src.length || start >= end) return;
+    const key = start + ':' + end + ':' + rep;
+    if (seen.has(key)) return; seen.add(key);
+    out.push({ code: src.slice(0, start) + rep + src.slice(end), desc, line: lineOf(src, start), removed: src.slice(start, end) });
+  };
+  (function walk(node) {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'IfStatement' && node.start != null) {
+      if (!node.alternate) {
+        add(node.start, node.end, '', 'delete if-branch'); // guard / early-return / dormant gate
+      } else {
+        // keep else-body only (drop the test + consequent), and keep if-only (drop else)
+        if (node.alternate.start != null) add(node.start, node.alternate.start, '', 'delete if-arm (keep else)');
+        if (node.consequent && node.consequent.end != null) add(node.consequent.end, node.end, '', 'delete else-arm');
+      }
+    }
+    if (node.type === 'ConditionalExpression' && node.test && node.consequent && node.alternate) {
+      // t ? a : b → a   and   → b  (removes the condition's influence entirely)
+      const a = src.slice(node.consequent.start, node.consequent.end);
+      const b = src.slice(node.alternate.start, node.alternate.end);
+      add(node.start, node.end, a, 'ternary → then-value');
+      add(node.start, node.end, b, 'ternary → else-value');
+    }
+    // `cond && doThing()` / `cond || doThing()` as a bare statement — a gated action
+    if (node.type === 'ExpressionStatement' && node.expression && node.expression.type === 'LogicalExpression') {
+      add(node.start, node.end, '', 'delete gated statement');
+    }
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'start' || k === 'end' || k === 'range') continue;
+      const c = node[k];
+      if (Array.isArray(c)) c.forEach(walk);
+      else if (c && typeof c.type === 'string') walk(c);
+    }
+  })(ast);
+  return out.slice(0, cap);
+}
+
+// ── literal harvesting (for LITERAL-SEEDED TRIGGER HUNTING) ──────────────────
+// A dormant gate compares an input against a magic constant it hopes the tests never
+// produce (`if (s === 'xK9!')`, `if (items.length === 9 && items[0].price === 4.44)`).
+// Harvest those constants so the prover can feed them back in and trigger the branch.
+// Returns [{ root, kind, key, value }] — root = the base param identifier; kind =
+// 'eq' (param === lit) | 'prop' (param.KEY === lit) | 'length' (param.length === N) |
+// 'index-prop' (param[I].KEY === lit). Code-derived → a RED-ONLY hunt lane (never a pass).
+function litValue(node) {
+  if (!node) return { has: false };
+  if (node.type === 'Literal' && (typeof node.value === 'string' || typeof node.value === 'number' || typeof node.value === 'boolean')) return { has: true, value: node.value };
+  if (node.type === 'StringLiteral' || node.type === 'NumericLiteral' || node.type === 'BooleanLiteral') return { has: true, value: node.value };
+  if (node.type === 'UnaryExpression' && node.operator === '-' && node.argument && (node.argument.type === 'NumericLiteral' || node.argument.type === 'Literal') && typeof node.argument.value === 'number') return { has: true, value: -node.argument.value };
+  return { has: false };
+}
+function pathOf(node) {
+  if (!node) return null;
+  if (node.type === 'Identifier') return { root: node.name, kind: 'eq', key: null };
+  if (node.type === 'MemberExpression' && !node.computed && node.property && node.property.type === 'Identifier') {
+    const base = node.object;
+    if (base.type === 'Identifier') {
+      return node.property.name === 'length'
+        ? { root: base.name, kind: 'length', key: 'length' }
+        : { root: base.name, kind: 'prop', key: node.property.name };
+    }
+    if (base.type === 'MemberExpression' && base.computed && base.object && base.object.type === 'Identifier'
+      && base.property && (base.property.type === 'NumericLiteral' || base.property.type === 'Literal') && typeof base.property.value === 'number') {
+      return { root: base.object.name, kind: 'index-prop', key: { index: base.property.value, prop: node.property.name } };
+    }
+  }
+  return null;
+}
+function harvestLiterals(src, cap = 30) {
+  const ast = parse(src);
+  if (!ast) return [];
+  const out = [];
+  const seen = new Set();
+  const add = (p, value) => {
+    if (!p) return;
+    const k = p.root + '|' + p.kind + '|' + JSON.stringify(p.key) + '|' + JSON.stringify(value);
+    if (seen.has(k)) return; seen.add(k);
+    out.push({ root: p.root, kind: p.kind, key: p.key, value });
+  };
+  (function walk(node) {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'BinaryExpression' && /^(===|==|!==|!=)$/.test(node.operator)) {
+      let p = pathOf(node.left), l = litValue(node.right);
+      if (!p || !l.has) { p = pathOf(node.right); l = litValue(node.left); }
+      if (p && l.has) add(p, l.value);
+    }
+    if (node.type === 'SwitchStatement' && node.discriminant) {
+      const p = pathOf(node.discriminant);
+      if (p) for (const c of node.cases || []) { const l = litValue(c.test); if (l.has) add(p, l.value); }
+    }
+    for (const k of Object.keys(node)) {
+      if (k === 'loc' || k === 'start' || k === 'end' || k === 'range') continue;
+      const c = node[k];
+      if (Array.isArray(c)) c.forEach(walk);
+      else if (c && typeof c.type === 'string') walk(c);
+    }
+  })(ast);
+  return out.slice(0, cap);
+}
+
+module.exports = { mutants, deletions, harvestLiterals };

package/src/objects.js

@@ -0,0 +1,31 @@
+'use strict';
+// Append-only, content-addressed store in `.yaylayer/objects/` — the audit core that must never
+// blank. Objects are keyed by their own sha256 (hex), laid out git-style as objects/<first2>/<rest>,
+// deduped (identical content stored once). Spec blocks are archived here at sign time (keyed by
+// their specHash), so "as signed" reconstruction NEVER depends on git surviving. Committed with
+// the repo. (P2 will store signed verification attestations here too; P4 adds the Durable code
+// archive alongside.) Small + tiny volume, so no packing/GC needed — that's why it's bespoke here
+// while bulk code archival (Durable) leans on git.
+const fs = require('fs');
+const path = require('path');
+const { sha256 } = require('./crypto');
+
+const YAY_DIR = '.yaylayer';
+function objRoot(root) { return path.join(root, YAY_DIR, 'objects'); }
+function objPath(root, hash) { const h = String(hash); return path.join(objRoot(root), h.slice(0, 2), h.slice(2)); }
+
+// Store `content`, keyed by its sha256; returns the hash. Idempotent (write-once). Best-effort:
+// the seal in lock.json remains the source of truth, so a failed archive write never blocks signing.
+function putObject(root, content) {
+  const s = String(content); const h = sha256(s); const p = objPath(root, h);
+  try { fs.mkdirSync(path.dirname(p), { recursive: true }); if (!fs.existsSync(p)) fs.writeFileSync(p, s); } catch (_) { /* best effort */ }
+  return h;
+}
+// Read the object with this hash, but only if its content still hashes to the key (tamper check).
+function getObject(root, hash) {
+  try { const p = objPath(root, hash); if (!fs.existsSync(p)) return null; const c = fs.readFileSync(p, 'utf8'); return sha256(c) === String(hash) ? c : null; }
+  catch (_) { return null; }
+}
+function hasObject(root, hash) { try { return fs.existsSync(objPath(root, hash)); } catch (_) { return false; } }
+
+module.exports = { objRoot, objPath, putObject, getObject, hasObject };

package/src/phone.js

@@ -0,0 +1,188 @@
+'use strict';
+// Phone signing over the local network — the key lives only on the phone, the
+// laptop only ASKS. No third-party server: the laptop runs a tiny LAN HTTP
+// endpoint, the phone (same Wi-Fi) opens it, reviews the promises in plain
+// language, and signs with its own key. The laptop verifies the signature
+// against the enrolled public key and writes the seal.
+//
+// Wire format matches src/crypto.js exactly: public key = base64 SPKI-DER,
+// signature = base64 raw ed25519 over canonical(approval). The phone's WebCrypto
+// Ed25519 emits the same encodings, so it interoperates with `yay verify`.
+
+const http = require('http');
+const os = require('os');
+// Stable default port so the phone page keeps one origin (→ its saved key persists).
+// 48757 is a deliberately uncommon high port, clear of the usual dev ports
+// (React 3000, Vite 5173, Express 8080/3000, Rails 3000, webpack 4200/8000, …) so
+// it rarely collides. YAY_PHONE_PORT overrides it; set it to 0 to force a random port.
+const PHONE_PORT = (process.env.YAY_PHONE_PORT !== undefined && process.env.YAY_PHONE_PORT !== '')
+  ? Number(process.env.YAY_PHONE_PORT) : 48757;
+const C = require('./crypto');
+const { canonical } = require('./util');
+const { signerHTML } = require('./signer-page');
+
+function lanIP() {
+  const ifaces = os.networkInterfaces();
+  for (const name of Object.keys(ifaces)) {
+    for (const i of ifaces[name] || []) {
+      if (i.family === 'IPv4' && !i.internal) return i.address;
+    }
+  }
+  return '127.0.0.1';
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let b = '';
+    req.on('data', (c) => { b += c; if (b.length > 1e6) req.destroy(); });
+    req.on('end', () => { try { resolve(JSON.parse(b || '{}')); } catch (_) { resolve({}); } });
+    req.on('error', () => resolve({}));
+  });
+}
+function sendJSON(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { 'content-type': 'application/json', 'access-control-allow-origin': '*', 'cache-control': 'no-store' });
+  res.end(body);
+}
+function sendHTML(res, html) {
+  res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(html);
+}
+
+// Short human-verifiable code bound to the phone's public key (MITM guard):
+// if a different device pairs, its code won't match what the user's phone shows.
+function confirmCode(pubB64) {
+  return String(parseInt(C.sha256('yay-pair:' + pubB64).slice(0, 8), 16) % 1000000).padStart(6, '0');
+}
+
+// Serve a session until `done` resolves (the phone completed the action).
+// Returns { url, port, done: Promise, close() }.
+function serve(mode, project, sessionData, onPost, opts) {
+  let resolveDone;
+  const done = new Promise((r) => { resolveDone = r; });
+  // Final outcome the phone can poll after it submitted (pairing completes on the
+  // laptop, so the phone learns success/failure via GET /api/status). `settled`
+  // resolves once the phone has actually read that final status.
+  let final = null, resolveSettled;
+  const settled = new Promise((r) => { resolveSettled = r; });
+  const html = signerHTML({ mode, project });
+  // Auto-close if nobody completes it, so an abandoned server can't linger holding
+  // the stable port (which would push the next sign onto a new origin → lost key).
+  const timeoutMs = (opts && opts.timeoutMs) || Number(process.env.YAY_PHONE_TIMEOUT_MS) || 600000;
+  let timer = null;
+
+  const handler = async (req, res) => {
+    const url = req.url.split('?')[0];
+    if (req.method === 'OPTIONS') return sendJSON(res, 200, {});
+    if (req.method === 'GET' && (url === '/' || url === '/index.html')) return sendHTML(res, html);
+    if (req.method === 'GET' && url === '/api/session') return sendJSON(res, 200, { mode, project, ...sessionData });
+    if (req.method === 'GET' && url === '/api/status') { if (final) resolveSettled(); return sendJSON(res, 200, { final }); }
+    if (req.method === 'POST' && url === '/api/submit') {
+      const body = await readBody(req);
+      const result = onPost(body);
+      if (result && result.error) return sendJSON(res, 400, { error: result.error });
+      sendJSON(res, 200, result || { ok: true });
+      if (result && result.done) resolveDone(result.done);
+      return;
+    }
+    sendJSON(res, 404, { error: 'not found' });
+  };
+  // Pure-JS signer works over plain http; opt-in TLS (self-signed) encrypts transport.
+  const tls = opts && opts.tls;
+  const server = tls ? require('https').createServer({ key: tls.key, cert: tls.cert }, handler) : http.createServer(handler);
+  const scheme = tls ? 'https' : 'http';
+
+  // Bind a STABLE port so the phone URL's origin (host:port) stays constant across
+  // pair → sign sessions — otherwise localStorage (where the phone key lives) is
+  // scoped to a different origin each run and the phone "forgets" its key. Prefer
+  // PHONE_PORT, step through a few, and only fall back to a random port as a last
+  // resort (in which case the phone may need to restore from its recovery phrase).
+  return new Promise((resolve, reject) => {
+    const mk = (port) => ({
+      url: `${scheme}://${lanIP()}:${port}`, local: `${scheme}://localhost:${port}`, port, done, settled,
+      // fellBack: we could not get the stable port → the phone address changed and
+      // its saved key may be invisible (caller warns the user).
+      fellBack: PHONE_PORT !== 0 && port !== PHONE_PORT,
+      setFinal: (f) => { final = f; },
+      close: () => { if (timer) clearTimeout(timer); server.close(); },
+    });
+    const bind = (port, triesLeft) => {
+      const onErr = (e) => {
+        if ((e.code === 'EADDRINUSE' || e.code === 'EACCES') && triesLeft > 0) bind(triesLeft === 1 ? 0 : port + 1, triesLeft - 1);
+        else reject(e);
+      };
+      server.once('error', onErr);
+      server.listen(port, '0.0.0.0', () => {
+        server.removeListener('error', onErr);
+        timer = setTimeout(() => { resolveDone({ timedOut: true }); try { server.close(); } catch (_) {} }, timeoutMs);
+        if (timer.unref) timer.unref();
+        resolve(mk(server.address().port));
+      });
+    };
+    bind(PHONE_PORT, 6);
+  });
+}
+
+// Pairing: the phone creates its key and proves possession by signing our
+// challenge; we return its name + public key + the confirm code for the human.
+//
+// When `genesis` is supplied (no signed trust root exists yet), we run
+// PHONE-AS-GENESIS: the phone self-signs the genesis roster event, so its
+// signature IS the trust root. The laptop never holds a key. We rebuild the
+// event authoritatively from our own fields + the phone's name/pub, so a
+// tampered phone cannot smuggle a different role/nonce past us.
+async function pairOverLan({ project, tls, genesis, challenge }) {
+  challenge = challenge || (C.randomNonce() + C.randomNonce());
+  const session = genesis ? { challenge, genesis } : { challenge };
+  const s = await serve('pair', project, session, (body) => {
+    const { name, pubB64, proof } = body || {};
+    if (!name || !pubB64 || !proof) return { error: 'missing name/pubB64/proof' };
+    if (genesis) {
+      const ev = { ...genesis, name: String(name), pub: pubB64, by: String(name) };
+      if (!C.verify(canonical(ev), proof, pubB64)) return { error: 'genesis self-signature failed' };
+      const code = confirmCode(pubB64);
+      return { ok: true, code, done: { name: String(name), pubB64, code, genesisEvent: { ...ev, signature: proof } } };
+    }
+    if (!C.verify(challenge, proof, pubB64)) return { error: 'key possession proof failed' };
+    const code = confirmCode(pubB64);
+    return { ok: true, code, done: { name: String(name), pubB64, code } };
+  }, { tls });
+  return s; // { url, port, done, close }
+}
+
+// Signing: hand the phone the unsigned approval + a plain-language summary; it
+// signs canonical(approval) and posts the signature, which we verify.
+async function signOverLan({ project, approval, summary, tagPool, expectPubB64, tls }) {
+  const pubs = Array.isArray(expectPubB64) ? expectPubB64 : [expectPubB64]; // identity may hold several keys
+  const s = await serve('approve', project, { approval, summary, tagPool: tagPool || [] }, (body) => {
+    // Send back (§5): the signer declined and (optionally) said what to change / which tags. No signature.
+    if (body && body.rejected) return { ok: true, done: { rejected: true, reason: String(body.reason || '').trim(), tags: Array.isArray(body.tags) ? body.tags : undefined } };
+    const { signature } = body || {};
+    if (!signature) return { error: 'missing signature' };
+    // Legacy: an older phone may still post an edited Brief; verify against — and return — it.
+    let target = approval;
+    const editedBrief = (body.brief !== undefined && approval.brief);
+    if (editedBrief) target = { ...approval, brief: { ...approval.brief, text: String(body.brief).trim() } };
+    const canon = canonical(target);
+    if (!pubs.some((pub) => C.verify(canon, signature, pub))) return { error: 'signature did not verify against any enrolled key' };
+    return { ok: true, done: editedBrief ? { signature, brief: String(body.brief).trim() } : { signature } };
+  }, { tls });
+  return s;
+}
+
+// Roster authorization: an OWNER's phone signs a governance event (enroll / revoke
+// / reroot) so a phone-only owner can manage the roster with no key on the laptop.
+// The phone signs canonical(event) == eventBytes, verified against current owner keys.
+async function authorizeOverLan({ project, event, summary, ownerPubs, tls }) {
+  const canon = canonical(event);
+  const pubs = Array.isArray(ownerPubs) ? ownerPubs : [ownerPubs];
+  const s = await serve('authorize', project, { event, summary }, (body) => {
+    const { signature } = body || {};
+    if (!signature) return { error: 'missing signature' };
+    if (!pubs.some((pub) => pub && C.verify(canon, signature, pub))) return { error: 'not signed by a current owner key on this phone' };
+    return { ok: true, done: { signature } };
+  }, { tls });
+  return s;
+}
+
+module.exports = { pairOverLan, signOverLan, authorizeOverLan, lanIP, confirmCode };

package/src/plan.js

@@ -0,0 +1,141 @@
+'use strict';
+// `yay plan` — an LLM synthesizes a clean, high-level SYSTEM PLAN from the specs
+// (intent / ensures / feeds / blast-radius across all Cells). It runs at plan-time
+// only; the result is cached to .yaylayer/plan.json and baked into the offline map
+// as a static, presentation-grade "System Plan" poster. Needs the user's own
+// ANTHROPIC_API_KEY (from their .env); no key, no dependency added — just fetch.
+
+function trim(s, n) { return String(s == null ? '' : s).trim().slice(0, n || 200); }
+
+// A compact digest of the specs to feed the model (blast-sorted, capped).
+function buildDigest(manifest, project) {
+  const cells = manifest.cells || {};
+  const byModule = {};
+  for (const id of Object.keys(cells)) {
+    const c = cells[id];
+    if (c.contains && c.contains.length) continue; // skip container Cells
+    const m = c.module || 'other';
+    (byModule[m] = byModule[m] || []).push({
+      cell: id,
+      unit: c.unitName || '',
+      intent: trim(c.spec && c.spec.intent, 240),
+      ensures: trim(c.spec && c.spec.ensures, 160),
+      feeds: (c.feeds || []).slice(0, 8),
+      blast: c.blast || 0,
+      pure: /^yes\b/i.test((c.spec && c.spec.pure) || ''),
+    });
+  }
+  const modules = Object.keys(byModule).map((name) => {
+    const list = byModule[name].sort((a, b) => b.blast - a.blast);
+    return { name, total: list.length, units: list.slice(0, 40) };
+  });
+  return { project: project || 'project', modules, moduleFlows: manifest.moduleEdges || [] };
+}
+
+const SYSTEM_PROMPT = [
+  'You are a systems architect preparing a single conference slide that explains a software system.',
+  'You are given a DIGEST of the project\'s formal specs: each unit has an intent (what it does), optional ensures (a postcondition), feeds (data-flow to other Cells), and blast (how many units depend on it — higher = more load-bearing).',
+  'Synthesize a clean, high-level SYSTEM PLAN. Group the modules into a few LOGICAL subsystems (not necessarily one per module) that best explain the architecture to a newcomer.',
+  'Return ONLY a JSON object, no prose, no code fences, with exactly this shape:',
+  '{',
+  '  "system": string,            // 2-4 sentence plain-English overview of what the whole system is and does',
+  '  "subsystems": [ { "name": string, "modules": [string], "purpose": string, "role": "input"|"data"|"logic"|"output"|"ui"|"other" } ],',
+  '  "flows": [ { "from": string, "to": string, "what": string } ],   // subsystem-to-subsystem, "what" is a short data label',
+  '  "highlights": [ string ]      // 3-5 short bullets: load-bearing pieces, risks, notable design choices',
+  '}',
+  'Base everything ONLY on the digest. "from"/"to" in flows must be subsystem names you defined. Keep purposes to one line.',
+].join('\n');
+
+function stripToJSON(text) {
+  let t = String(text || '').trim();
+  const fence = t.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) t = fence[1].trim();
+  const a = t.indexOf('{'), b = t.lastIndexOf('}');
+  if (a >= 0 && b > a) t = t.slice(a, b + 1);
+  return JSON.parse(t);
+}
+
+async function callAnthropic(digest, { model, apiKey, maxTokens }) {
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify({ model, max_tokens: maxTokens || 2000, system: SYSTEM_PROMPT, messages: [{ role: 'user', content: 'DIGEST:\n' + JSON.stringify(digest) }] }),
+  });
+  if (!res.ok) throw new Error('Anthropic API ' + res.status + ': ' + (await res.text().catch(() => '')).slice(0, 240));
+  const data = await res.json();
+  return (data && data.content && data.content[0] && data.content[0].text) || '';
+}
+
+// OpenAI Chat Completions — also covers OpenAI-COMPATIBLE providers (Groq, Together,
+// OpenRouter, Ollama, LM Studio, …) via baseUrl. `tokenField` handles newer OpenAI
+// models that require max_completion_tokens instead of max_tokens.
+async function callOpenAICompat(digest, { model, apiKey, baseUrl, maxTokens }, tokenField) {
+  const url = (baseUrl || 'https://api.openai.com/v1').replace(/\/$/, '') + '/chat/completions';
+  const body = { model, messages: [{ role: 'system', content: SYSTEM_PROMPT }, { role: 'user', content: 'DIGEST:\n' + JSON.stringify(digest) }] };
+  body[tokenField || 'max_tokens'] = maxTokens || 2000;
+  const headers = { 'content-type': 'application/json' };
+  if (apiKey) headers.authorization = 'Bearer ' + apiKey; // local servers (Ollama/LM Studio) often need no key
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+  if (!res.ok) {
+    const errText = (await res.text().catch(() => '')).slice(0, 300);
+    // some models reject max_tokens and want max_completion_tokens — retry once
+    if (res.status === 400 && /max_completion_tokens/.test(errText) && (tokenField || 'max_tokens') === 'max_tokens') {
+      return callOpenAICompat(digest, { model, apiKey, baseUrl, maxTokens }, 'max_completion_tokens');
+    }
+    throw new Error('OpenAI-compatible API ' + res.status + ': ' + errText);
+  }
+  const data = await res.json();
+  return (data && data.choices && data.choices[0] && data.choices[0].message && data.choices[0].message.content) || '';
+}
+
+// provider: 'anthropic' | 'openai' (openai also = any OpenAI-compatible baseUrl).
+async function synthesize(digest, opts) {
+  if (typeof fetch !== 'function') throw new Error('global fetch unavailable — needs Node 18+');
+  const provider = opts.provider || 'anthropic';
+  const model = opts.model || (provider === 'anthropic' ? 'claude-sonnet-5' : 'gpt-4o');
+  const text = provider === 'anthropic'
+    ? await callAnthropic(digest, { ...opts, model })
+    : await callOpenAICompat(digest, { ...opts, model });
+  let plan;
+  try { plan = stripToJSON(text); } catch (e) { throw new Error('model did not return valid JSON'); }
+  plan.system = trim(plan.system, 1200) || 'No overview produced.';
+  plan.subsystems = Array.isArray(plan.subsystems) ? plan.subsystems : [];
+  plan.flows = Array.isArray(plan.flows) ? plan.flows : [];
+  plan.highlights = Array.isArray(plan.highlights) ? plan.highlights : [];
+  return plan;
+}
+
+// Generic one-shot chat (reused by the spec-only adversary). Same provider routing
+// as the plan; returns the raw text.
+async function chatAnthropic(system, user, { model, apiKey, maxTokens }) {
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST', headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify({ model, max_tokens: maxTokens || 1500, system, messages: [{ role: 'user', content: user }] }),
+  });
+  if (!res.ok) throw new Error('Anthropic API ' + res.status + ': ' + (await res.text().catch(() => '')).slice(0, 240));
+  const data = await res.json();
+  return (data && data.content && data.content[0] && data.content[0].text) || '';
+}
+async function chatOpenAICompat(system, user, { model, apiKey, baseUrl, maxTokens }, tokenField) {
+  const url = (baseUrl || 'https://api.openai.com/v1').replace(/\/$/, '') + '/chat/completions';
+  const body = { model, messages: [{ role: 'system', content: system }, { role: 'user', content: user }] };
+  body[tokenField || 'max_tokens'] = maxTokens || 1500;
+  const headers = { 'content-type': 'application/json' };
+  if (apiKey) headers.authorization = 'Bearer ' + apiKey;
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+  if (!res.ok) {
+    const errText = (await res.text().catch(() => '')).slice(0, 300);
+    if (res.status === 400 && /max_completion_tokens/.test(errText) && (tokenField || 'max_tokens') === 'max_tokens') return chatOpenAICompat(system, user, { model, apiKey, baseUrl, maxTokens }, 'max_completion_tokens');
+    throw new Error('OpenAI-compatible API ' + res.status + ': ' + errText);
+  }
+  const data = await res.json();
+  return (data && data.choices && data.choices[0] && data.choices[0].message && data.choices[0].message.content) || '';
+}
+async function chat(system, user, opts) {
+  if (typeof fetch !== 'function') throw new Error('global fetch unavailable — needs Node 18+');
+  const provider = opts.provider || 'anthropic';
+  const model = opts.model || (provider === 'anthropic' ? 'claude-sonnet-5' : 'gpt-4o');
+  return provider === 'anthropic' ? chatAnthropic(system, user, { ...opts, model }) : chatOpenAICompat(system, user, { ...opts, model });
+}
+
+module.exports = { buildDigest, synthesize, SYSTEM_PROMPT, chat };