yay-layer 1.0.0-rc.1

package/src/ratify.js

@@ -0,0 +1,28 @@
+'use strict';
+// Shared ratification helpers. The "reviewed bundle" is the exact set + content a human sees
+// before ratifying delegated (Autopilot) work; its hash lets `yay ratify --sign` prove it signs
+// PRECISELY what was reviewed (TOCTOU protection). One implementation, used by both the CLI and
+// the dashboard, so the render-time hash and the sign-time hash are computed identically.
+const { sha256 } = require('./crypto');
+const { canonical } = require('./util');
+
+// Cells whose current effective approval is a grant auto-approval (delegated, awaiting ratification).
+function autoCellIds(verified) {
+  const results = (verified && verified.results) || {};
+  return Object.keys(results).filter((id) => { const t = results[id].trust; return !!(t && t.auto); });
+}
+
+// A stable hash over {each delegated Cell's specHash + code hash + grant}. Any material change —
+// spec edited, code changed, the delegated set changed, a different grant — yields a different hash.
+function ratifyBundle(manifest, verified, autoIds) {
+  const ids = (autoIds || autoCellIds(verified)).slice().sort();
+  const per = {};
+  for (const id of ids) {
+    const c = (manifest.cells || {})[id] || {};
+    const t = ((verified.results || {})[id] || {}).trust || {};
+    per[id] = { spec: c.specHash || null, code: sha256(String(c.unitBody || '')), grant: t.grant || null };
+  }
+  return { ids, per, hash: sha256(canonical({ v: 1, cells: per })) };
+}
+
+module.exports = { autoCellIds, ratifyBundle };

package/src/record.js

@@ -0,0 +1,30 @@
+'use strict';
+// A recording stand-in for an EFFECT SURFACE (a canvas 2D context, a DOM node, a
+// logger…). Every method call and property assignment on it is appended to a shared
+// `trace`, so a spec can assert on WHAT a side-effecting function DID — e.g. which
+// `fillStyle` was set before which `fillRect` — instead of a return value it doesn't
+// have. Property READS return another recorder, so chains like `ctx.canvas.width`
+// don't crash; used as a value a recorder coerces to 0 / ''.
+//
+// trace entries: { type:'call', name, args } | { type:'set', name, value }
+function makeRecorder() {
+  const trace = [];
+  function node(prefix) {
+    return new Proxy(function () {}, {
+      get(_t, k) {
+        if (k === '__trace') return trace;
+        if (k === Symbol.toPrimitive) return () => 0;
+        if (k === 'then') return undefined;            // not a thenable
+        if (typeof k === 'symbol') return undefined;
+        return node(prefix ? prefix + '.' + String(k) : String(k));
+      },
+      set(_t, k, v) { trace.push({ type: 'set', name: (prefix ? prefix + '.' : '') + String(k), value: v }); return true; },
+      apply(_t, _this, args) { trace.push({ type: 'call', name: prefix || '(call)', args: args }); return node(prefix); },
+      construct() { return node(prefix); },
+      has() { return true; },
+    });
+  }
+  return { proxy: node(''), trace };
+}
+
+module.exports = { makeRecorder };

package/src/reverify.js

@@ -0,0 +1,212 @@
+'use strict';
+// Reverify engine — P1: re-run TODAY's verifier against a reconstructed HISTORICAL snapshot and report
+// the per-Cell verdict as the machine sees it NOW. This is the "replay the tape through today's better
+// reader" primitive. It assesses VERIFICATION only (code⇔spec) — the snapshot was an already-approved
+// state, and re-verification is the machine re-judging, independent of the human-authority axis (the
+// papers keep those two chains separate). P2/P3 will sweep every snapshot and diff against the original
+// attestation to produce the upgrade report; this is the single-state core they stand on.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const D = require('./durable');
+const A = require('./attest');
+const { buildManifest } = require('./manifest');
+const { verifyManifest } = require('./verify');
+const cap = require('./capability');
+
+// Reconstruct `snap` into a throwaway dir and verify it under the current verifier.
+// Returns { codeTreeHash, capability, fingerprint, counts, passed, cells:{id:{state,proven,predicate}} }
+// or { error } if the tree can't be faithfully rebuilt. `key` is the resolved Durable archive key.
+function reverifyState(p, snap, key, config, opts) {
+  opts = opts || {};
+  let dir = null;
+  try {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'yay-reverify-'));
+    D.reconstructSnapshot(p, snap, key, dir);
+    // Fidelity gate: a re-verdict is only meaningful if the rebuilt tree IS the recorded one.
+    const manifest = buildManifest(dir);
+    const rebuilt = A.codeTreeHashOf(manifest);
+    if (snap.codeTreeHash && rebuilt !== snap.codeTreeHash) {
+      return { error: 'reconstruction mismatch (rebuilt ' + rebuilt.slice(0, 12) + '… ≠ recorded ' + String(snap.codeTreeHash).slice(0, 12) + '…)' };
+    }
+    // Verification-only: assumeSigned (the snapshot was approved) so the state reflects the machine's
+    // code⇔spec judgment under today's checks, not the UNSIGNED gate (there is no lock in the temp dir).
+    const verified = verifyManifest(manifest, { approvals: [] }, config, { mutate: opts.mutate !== false, assumeSigned: true });
+    const cells = {};
+    for (const id of Object.keys(verified.results)) {
+      const r = verified.results[id];
+      cells[id] = {
+        state: r.state,
+        proven: !!r.proven,
+        predicate: !!(r.predicate && r.predicate.findings && r.predicate.findings.length),
+        coverage: (r.coverage && r.coverage.total) ? { exercised: r.coverage.exercised, total: r.coverage.total } : null,
+      };
+    }
+    // The signable verification object for this reconstructed historical tree, judged under TODAY's
+    // verifier. `yay reverify --attest` turns this into a signed, append-only reverification record
+    // (see reverificationObj). Built from the reconstructed manifest, so its code/spec hashes describe
+    // the HISTORICAL state, while its capability/fingerprint describe today's verifier.
+    const verObj = A.buildVerification(manifest, verified, { config });
+    return {
+      codeTreeHash: rebuilt,
+      capability: cap.CAPABILITY || null,
+      fingerprint: cap.capabilityFingerprint ? cap.capabilityFingerprint() : null,
+      counts: verified.counts,
+      passed: verified.passed,
+      cells,
+      verObj,
+    };
+  } catch (e) {
+    return { error: (e && e.message) || String(e) };
+  } finally {
+    if (dir) { try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) {} }
+  }
+}
+
+// ── P2: the sweep ───────────────────────────────────────────────────────────────────────────────
+// Replay every preserved snapshot through TODAY's verifier and diff each Cell against its ORIGINAL
+// recorded verdict, so a verifier upgrade turns into an "what changed" report. Never rewrites history —
+// the originals stand; this only computes deltas (and P3 will append reverification attestations).
+const RANK = { GREEN: 0, YELLOW: 1, RED: 2, PINK: 2, UNSIGNED: 2 };
+function classify(from, to) {
+  if (from == null) return 'no-baseline';
+  if (from === to) return 'unchanged';
+  const rf = RANK[from] != null ? RANK[from] : 2;
+  const rt = RANK[to] != null ? RANK[to] : 2;
+  return rt > rf ? 'regressed' : (rt < rf ? 'improved' : 'changed');
+}
+// The baseline for a snapshot = the per-Cell evidence + capability of its linked (signature-verified)
+// attestation. Pluggable so callers/tests can supply a baseline; default reads the real attestation.
+function defaultBaselineOf(p, config) {
+  return (snap) => {
+    if (!snap || !snap.attest) return null;
+    try { const att = A.loadAttestation(p, config, snap.attest); return att ? { capability: att.capability || null, evidence: att.evidence || null } : null; }
+    catch (_) { return null; }
+  };
+}
+// Sweep all snapshots (deduped by codeTreeHash — identical trees re-verified once). Returns a report:
+// { total, checked, deduped, errors, unchanged, improved, regressed, noBaseline, capability, fingerprint,
+//   regressions:[…], improvements:[…], states:[…] }.
+function reverifySweep(p, key, config, opts) {
+  opts = opts || {};
+  const baselineOf = opts.baselineOf || defaultBaselineOf(p, config);
+  const nowCap = cap.CAPABILITY || null;
+  const allSnaps = D.listSnapshots(p);
+  const cache = {};
+  const report = {
+    total: allSnaps.length, filtered: 0, checked: 0, deduped: 0, errors: 0,
+    unchanged: 0, improved: 0, regressed: 0, noBaseline: 0,
+    capability: nowCap, fingerprint: cap.capabilityFingerprint ? cap.capabilityFingerprint() : null,
+    regressions: [], improvements: [], states: [],
+  };
+  for (const snap of allSnaps) {
+    // Cheap pre-filters (no reconstruction needed): --since keeps snapshots at/after a date; --eligible
+    // keeps only those a capability change could actually re-judge (baseline capability ≠ today's).
+    if (opts.since && snap.at && String(snap.at) < String(opts.since)) { report.filtered++; continue; }
+    if (opts.eligibleOnly) {
+      const b = baselineOf(snap);
+      if (b && b.capability && b.capability === nowCap) { report.filtered++; continue; }
+    }
+    const ck = snap.codeTreeHash;
+    let rv;
+    if (ck && cache[ck]) { rv = cache[ck]; report.deduped++; }
+    else { rv = reverifyState(p, snap, key, config, opts); if (ck) cache[ck] = rv; }
+    if (rv.error) { report.errors++; report.states.push({ at: snap.at, error: rv.error }); continue; }
+    report.checked++;
+    const base = baselineOf(snap);
+    const baseCap = (base && base.capability) || null;
+    const baseEv = (base && base.evidence) || null;
+    const perCell = {};
+    for (const id of Object.keys(rv.cells)) {
+      const to = rv.cells[id].state;
+      const from = baseEv && baseEv[id] ? baseEv[id].state : null;
+      const verdict = classify(from, to);
+      perCell[id] = { from, to, verdict, predicate: rv.cells[id].predicate };
+      if (verdict === 'regressed') { report.regressed++; report.regressions.push({ at: snap.at, cell: id, from, to, fromCapability: baseCap, toCapability: rv.capability, predicate: rv.cells[id].predicate }); }
+      else if (verdict === 'improved') { report.improved++; report.improvements.push({ at: snap.at, cell: id, from, to, fromCapability: baseCap, toCapability: rv.capability }); }
+      else if (verdict === 'unchanged') report.unchanged++;
+      else if (verdict === 'no-baseline') report.noBaseline++;
+    }
+    // A state "changed" if any Cell moved against its baseline — this is what --attest mints a record for.
+    const changed = Object.keys(perCell).some((id) => perCell[id].verdict === 'regressed' || perCell[id].verdict === 'improved');
+    const st = { at: snap.at, codeTreeHash: ck, attest: snap.attest || null, fromCapability: baseCap, toCapability: rv.capability, changed, cells: perCell };
+    if (opts.keepVerObj) st.verObj = rv.verObj;
+    report.states.push(st);
+  }
+  return report;
+}
+
+// Turn a reconstructed state's verification object into a signable REVERIFICATION record: the same
+// canonical verification bytes (today's capability judging the historical code/spec), tagged as a
+// reverification and carrying a reference to the ORIGINAL attestation it re-assesses (Paper 3: append
+// a new immutable record beside the old, never rewrite). The caller signs it with the verifier key and
+// appends it to the same chain (A.signAttestation → A.appendAttestation).
+function reverificationObj(verObj, snap, baseline) {
+  return Object.assign({}, verObj, {
+    kind: 'reverification',
+    reassesses: (snap && snap.attest) || null,      // hash of the original attestation for this state
+    reassessedAt: (snap && snap.at) || null,        // when the original state was archived
+    originalCapability: (baseline && baseline.capability) || null,
+  });
+}
+
+// ── P4: the reverification posture (grandfathering) ──────────────────────────────────────────────
+// A project-level gate control — off / guarded / strict — in the same spirit as the foundation seal
+// posture (and, like it, NOT a per-Cell capability policy kind: it changes gate ENFORCEMENT of record
+// existence, never how any Cell's verdict is computed, so it stays out of the capability fingerprint).
+//   off      — preserved history is grandfathered (the default). A better verifier never blocks old work.
+//   guarded  — `yay verify` WARNS when preserved history predates the current verifier capability.
+//   strict   — the gate BLOCKS until each such state has a signed reverification under the current
+//              capability (`yay reverify --all --attest`). Enforces the EXISTENCE of the signed record —
+//              never key-possession at view time (the keyless report is always available).
+function reverifyPosture(config) {
+  const m = String((config && config.reverification) || 'off').toLowerCase();
+  return (m === 'guarded' || m === 'strict') ? m : 'off';
+}
+
+// Consult the posture against preserved history. Returns { posture, capability, subject, pending, satisfied }
+// where `pending` lists distinct preserved states whose ORIGINAL attestation predates the current
+// capability and that no reverification at the current capability yet covers. `opts.capability` overrides
+// the current capability (used in tests to simulate a bump without a live version change).
+function reverifyGate(p, config, opts) {
+  opts = opts || {};
+  const posture = opts.posture || reverifyPosture(config);
+  const cur = opts.capability || cap.CAPABILITY || null;
+  const out = { posture, capability: cur, subject: posture !== 'off', pending: [], satisfied: true };
+  if (posture === 'off') return out;
+  // Which original attestations already have a reverification at the CURRENT capability?
+  const led = A.loadLedger(p, config);
+  const covered = {};
+  for (const e of led.entries) {
+    const a = A.loadAttestation(p, config, e.hash);
+    if (a && a.kind === 'reverification' && a.capability === cur && a.reassesses) covered[a.reassesses] = true;
+  }
+  // Optional per-Cell scoping (P4b): when opts.scoped is set, only states that contained at least one
+  // in-scope Cell (an owner-signed `reverify: latest` match — opts.scopedIds is that Cell-id set) are
+  // subject; the rest stay grandfathered. Membership is read from the state's own attestation evidence,
+  // so scoping stays KEYLESS (no reconstruction needed to consult the posture).
+  const scoped = !!opts.scoped;
+  const scopedIds = opts.scopedIds || null;
+  if (scoped) out.scoped = true;
+  const seen = new Set();
+  for (const s of D.listSnapshots(p)) {
+    if (!s.attest) continue;                                   // never attested — no baseline capability to compare
+    if (s.codeTreeHash && seen.has(s.codeTreeHash)) continue;  // dedup identical trees
+    if (s.codeTreeHash) seen.add(s.codeTreeHash);
+    const orig = A.loadAttestation(p, config, s.attest);
+    const origCap = orig ? orig.capability : null;
+    if (!origCap || origCap === cur) continue;                 // already at the current capability
+    if (covered[s.attest]) continue;                           // a current-capability reverification covers it
+    if (scoped) {
+      const ev = (orig && orig.evidence) || {};
+      const inScope = Object.keys(ev).some((id) => scopedIds && scopedIds.has(id));
+      if (!inScope) continue;                                  // no in-scope Cell in this state — grandfathered
+    }
+    out.pending.push({ at: s.at, attest: s.attest, fromCapability: origCap, codeTreeHash: s.codeTreeHash });
+  }
+  out.satisfied = out.pending.length === 0;
+  return out;
+}
+
+module.exports = { reverifyState, reverifySweep, reverificationObj, classify, reverifyPosture, reverifyGate };

package/src/roster.js

@@ -0,0 +1,117 @@
+'use strict';
+// The SIGNED roster — who is allowed to sign, as a tamper-evident chain.
+//
+// Without this, anyone (a malignant AI) with repo write could add their own key
+// to the roster file and then "approve" their own code — defeating the whole
+// protocol. So the roster is not a plain file you trust: it is an append-only log
+// of events, each SIGNED by an existing OWNER's key (which lives on a phone, not
+// on the AI's machine). `deriveRoster` rebuilds the set of trusted signers using
+// ONLY events whose signatures check out — so an unsigned edit has no effect.
+//
+// Semantics: 1-of-N. Any enrolled signer may approve a Cell ALONE. Enrolling a
+// signer is itself an owner-signed act; it does not require co-approval.
+//
+// Bootstrapping truth: the first event (genesis) is self-signed — it IS the trust
+// root. If the AI can rewrite every file it could swap genesis too, so the root
+// must be anchored outside the repo (a fingerprint pinned in CI, or your eyes).
+// `deriveRoster` exposes rootFp and enforces an optional pin.
+
+const C = require('./crypto');
+const { canonical } = require('./util');
+
+// Bytes an event is signed over: the event minus its own signature.
+function eventBytes(event) {
+  const { signature, ...body } = event; // eslint-disable-line no-unused-vars
+  return canonical(body);
+}
+
+// Human-verifiable fingerprint of a public key (for pinning / eyeballing).
+function fingerprint(pub) {
+  const h = C.sha256(pub).slice(0, 16).toUpperCase();
+  return h.replace(/(.{4})(?=.)/g, '$1-'); // 3F2A-9C11-8D0E-1B44
+}
+
+// Replay the log into an effective roster, trusting only validly-signed events.
+// opts.root (optional) pins the expected genesis fingerprint.
+// Returns { roster:{name:[pub]}, roles:{name:'owner'|'signer'}, rootFp, problems, ok }.
+function deriveRoster(log, opts) {
+  const events = (log && log.events) || [];
+  const roster = {};
+  const roles = {};
+  const problems = [];
+  let rootFp = null;
+  let policy = { rules: [] }; // signing policy — set by owner-signed `policy` events (latest wins)
+  let foundation = null;      // foundation seal payload — set by owner-signed `foundation` events (latest wins)
+  let foundationMode = 'off'; // off | guarded | strict
+  let rootMeta = null;        // reroot provenance stamped into genesis (supersedes/rerootedAt/rerootReason)
+
+  const ownerKeys = () => {
+    const out = [];
+    for (const n of Object.keys(roles)) if (roles[n] === 'owner') out.push(...(roster[n] || []));
+    return out;
+  };
+  const addKey = (name, pub) => { (roster[name] = roster[name] || []); if (!roster[name].includes(pub)) roster[name].push(pub); };
+
+  if (!events.length) return { roster, roles, rootFp, problems: ['roster log is empty — no trust root established'], ok: false };
+
+  events.forEach((e, i) => {
+    if (i === 0) {
+      if (e.type !== 'genesis') { problems.push('first roster event must be genesis'); return; }
+      if (!e.name || !e.pub || !e.signature || !C.verify(eventBytes(e), e.signature, e.pub)) { problems.push('genesis signature invalid — trust root not established'); return; }
+      addKey(e.name, e.pub); roles[e.name] = 'owner'; rootFp = fingerprint(e.pub);
+      // A reroot stamps the rotation into the (signed) genesis — surfaced for the audit.
+      if (e.supersedes || e.rerootReason || e.rerootedAt) rootMeta = { supersedes: e.supersedes || null, rerootedAt: e.rerootedAt || e.at || null, rerootReason: e.rerootReason || null };
+      return;
+    }
+    if (!rootFp) { problems.push(`event ${e.id || i}: no valid trust root, ignored`); return; }
+    // Authority: the event must be signed by a CURRENT owner's key.
+    const authorized = e.signature && ownerKeys().some((k) => C.verify(eventBytes(e), e.signature, k));
+    if (!authorized) { problems.push(`event ${e.id || i} (${e.type} ${e.name || ''}) is not signed by an owner — REJECTED`); return; }
+    if (e.type === 'add-signer') {
+      if (!e.name || !e.pub) { problems.push(`event ${e.id || i}: add-signer missing name/pub`); return; }
+      addKey(e.name, e.pub);
+      if (!roles[e.name]) roles[e.name] = (e.role === 'owner' ? 'owner' : 'signer');
+    } else if (e.type === 'add-key') {
+      if (!roster[e.name]) { problems.push(`event ${e.id || i}: add-key for unknown identity "${e.name}"`); return; }
+      addKey(e.name, e.pub);
+    } else if (e.type === 'revoke-key') {
+      // Remove one compromised/rotated key; the identity survives if it has others.
+      // (Past seals stay attributed — this only governs who can sign going forward.)
+      if (!e.name || !e.pub) { problems.push(`event ${e.id || i}: revoke-key missing name/pub`); return; }
+      if (roster[e.name]) { roster[e.name] = roster[e.name].filter((k) => k !== e.pub); if (!roster[e.name].length) { delete roster[e.name]; delete roles[e.name]; } }
+    } else if (e.type === 'remove-signer') {
+      // Remove an identity entirely (all its keys). History remains attributed.
+      if (!e.name) { problems.push(`event ${e.id || i}: remove-signer missing name`); return; }
+      delete roster[e.name]; delete roles[e.name];
+    } else if (e.type === 'policy') {
+      // Owner-signed signing policy. The rules are inside eventBytes, so they're
+      // tamper-evident and chained like every other governance event. Latest wins;
+      // an empty ruleset returns to neutral.
+      policy = { rules: Array.isArray(e.rules) ? e.rules : [] };
+    } else if (e.type === 'foundation') {
+      // Owner-signed FOUNDATION SEAL — the baseline of the fixed core files (see foundation.js).
+      // Being an owner-signed, chained roster event makes it un-removable: deleting it breaks
+      // the pinned chain and is itself flagged. Latest wins; mode 'off' retires the seal.
+      foundationMode = ['guarded', 'strict', 'off'].includes(e.mode) ? e.mode : 'guarded';
+      foundation = (foundationMode === 'off') ? null : (e.seal || null);
+    } else {
+      problems.push(`event ${e.id || i}: unknown type "${e.type}"`);
+    }
+  });
+
+  // Safety: never let a revocation leave the project with no owner (governance lockout).
+  if (rootFp && !ownerKeys().length) problems.push('roster would have NO owner key left — governance locked out (revocation refused)');
+
+  const pinned = opts && opts.root ? String(opts.root).toUpperCase() : null;
+  if (pinned && rootFp && pinned !== rootFp) problems.push(`TRUST-ROOT MISMATCH: expected ${pinned}, found ${rootFp} — the roster may have been swapped`);
+
+  return { roster, roles, rootFp, problems, ok: problems.length === 0, policy, foundation, foundationMode, rootMeta };
+}
+
+// Next event id given a log.
+function nextEventId(log) {
+  const n = ((log && log.events) || []).length + 1;
+  return 'R-' + String(n).padStart(4, '0');
+}
+
+module.exports = { deriveRoster, eventBytes, fingerprint, nextEventId };