yay-layer 1.0.0-rc.1

package/src/durable.js

@@ -0,0 +1,152 @@
+'use strict';
+// P4 — DURABLE MODE + governance. Standard mode keeps specs/attestations/grants forever (the tiny
+// bespoke sha256 store) and leans on git for the bulk SOURCE. Durable mode additionally keeps an
+// encrypted, self-contained archive of the signed source, so "what the code actually was when it was
+// signed" survives even if git history is lost, rebased, or the remote disappears (regulated / audit
+// settings). Per the locked design (D10, D12):
+//   • Trust anchor = OUR sha256 over the PLAINTEXT bytes (not git SHA-1) — content-addressed.
+//   • Source is encrypted AES-256-GCM under a PROJECT-HELD key YayLayer never stores (from
+//     $YAY_ARCHIVE_KEY or a passphrase, scrypt-derived). We hold ciphertext + clear, signed metadata.
+//   • Metadata (cell id, file, plaintext hash, size, time) stays CLEAR + signed → auditable without
+//     decrypting; only the body is sealed.
+//   • Pre-archive SECRET SCAN → refuse to seal code containing obvious secrets (they'd be preserved
+//     forever). Deletion is honest: a signed TOMBSTONE replaces a blob, never a silent rewrite.
+//
+// This is a self-contained encrypted store (the bespoke core extended to code). A git-bundle bulk
+// transport is a later storage optimization; the guarantees above are what Durable mode promises.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const C = require('./crypto');
+const { canonical } = require('./util');
+
+const SCRYPT = { N: 16384, r: 8, p: 1, keylen: 32 };
+
+function archiveDir(p) { return path.join(p.yay, 'archive'); }
+function archiveManifestPath(p) { return path.join(p.yay, 'archive.json'); }
+function blobPath(p, hash) { const h = String(hash); return path.join(archiveDir(p), h.slice(0, 2), h.slice(2)); }
+
+// Resolve the project-held archive key. From $YAY_ARCHIVE_KEY (raw or base64) or a passphrase
+// (scrypt with a per-project salt kept in the archive manifest). Returns a 32-byte Buffer. YayLayer
+// never persists the key or passphrase.
+function resolveKey(passphrase, salt) {
+  const env = process.env.YAY_ARCHIVE_KEY;
+  if (env) { const b = Buffer.from(env, /^[A-Za-z0-9+/=]+$/.test(env) && env.length >= 43 ? 'base64' : 'utf8'); return b.length === 32 ? b : crypto.scryptSync(env, salt || 'yay-archive', SCRYPT.keylen, SCRYPT); }
+  if (!passphrase) throw new Error('Durable archive needs a key — set $YAY_ARCHIVE_KEY or pass a passphrase (never stored by YayLayer).');
+  return crypto.scryptSync(passphrase, salt || 'yay-archive', SCRYPT.keylen, SCRYPT);
+}
+
+function encryptBlob(plaintext, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(Buffer.from(plaintext, 'utf8')), cipher.final()]);
+  return { v: 1, alg: 'aes-256-gcm', iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ct: ct.toString('base64') };
+}
+function decryptBlob(blob, key) {
+  const d = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(blob.iv, 'base64'));
+  d.setAuthTag(Buffer.from(blob.tag, 'base64'));
+  try { return Buffer.concat([d.update(Buffer.from(blob.ct, 'base64')), d.final()]).toString('utf8'); }
+  catch (_) { throw new Error('wrong archive key, or the blob is corrupt'); }
+}
+
+// ── pre-archive secret scan ────────────────────────────────────────────────────────────────────
+// Conservative: catch the obvious, high-confidence leaks (a false miss is better than crying wolf on
+// every file, but these patterns are specific enough to rarely false-positive). Returns [{line,kind}].
+const SECRET_PATTERNS = [
+  ['AWS access key id', /\bAKIA[0-9A-Z]{16}\b/],
+  ['private key block', /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/],
+  ['generic api/secret assignment', /\b(?:api[_-]?key|secret|token|passwd|password)\b\s*[:=]\s*['"][^'"]{12,}['"]/i],
+  ['Slack token', /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/],
+  ['Google API key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['bearer/JWT-ish', /\bey[JA][0-9A-Za-z_-]{10,}\.[0-9A-Za-z_-]{10,}\.[0-9A-Za-z_-]{6,}\b/],
+];
+function secretScan(text) {
+  const out = [];
+  const lines = String(text).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    for (const [kind, re] of SECRET_PATTERNS) { if (re.test(lines[i])) out.push({ line: i + 1, kind }); }
+  }
+  return out;
+}
+
+function loadArchive(p) {
+  try { return JSON.parse(fs.readFileSync(archiveManifestPath(p), 'utf8')); } catch (_) { return null; }
+}
+function saveArchive(p, arc) { fs.mkdirSync(p.yay, { recursive: true }); fs.writeFileSync(archiveManifestPath(p), JSON.stringify(arc, null, 2) + '\n'); }
+
+// Archive one plaintext body: anchor by sha256(plaintext), encrypt, write the blob. Idempotent
+// (same content → same anchor → write-once). Returns { hash, size, existed }.
+function putBlob(p, plaintext, key) {
+  const hash = C.sha256(String(plaintext));
+  const bp = blobPath(p, hash);
+  const existed = fs.existsSync(bp);
+  if (!existed) { fs.mkdirSync(path.dirname(bp), { recursive: true }); fs.writeFileSync(bp, JSON.stringify(encryptBlob(plaintext, key))); }
+  return { hash, size: Buffer.byteLength(plaintext, 'utf8'), existed };
+}
+// Read + decrypt a blob by its plaintext anchor; verifies the decrypted bytes re-hash to the anchor.
+function getBlob(p, hash, key) {
+  const bp = blobPath(p, hash);
+  if (!fs.existsSync(bp)) return null;
+  const blob = JSON.parse(fs.readFileSync(bp, 'utf8'));
+  const pt = decryptBlob(blob, key);
+  if (C.sha256(pt) !== String(hash)) throw new Error('archive blob failed its content check (anchor mismatch) — tampered');
+  return pt;
+}
+
+// Replace a blob with a signed TOMBSTONE — honest erasure that never rewrites history: the entry
+// stays, its status becomes "deliberately removed" with who/when/why. The ciphertext is deleted.
+function tombstone(p, hash, reason, signer) {
+  const bp = blobPath(p, hash);
+  try { if (fs.existsSync(bp)) fs.unlinkSync(bp); } catch (_) {}
+  return { contentHash: String(hash), status: 'deliberately removed', deletedAt: new Date().toISOString(), reason: reason || null, by: signer || null };
+}
+
+// ── reconstructable snapshots (the reverify substrate) ──────────────────────────────────────────
+// Blobs are content-addressed and never deleted, but arc.files only holds the LATEST path→hash map,
+// so a HISTORICAL tree can't be rebuilt without an index of "which blobs composed the tree at moment N".
+// recordSnapshot captures exactly that — the file→blob-hash map for one archived state, tied to the
+// verification it captured (codeTreeHash + the attestation hash). This is capture-going-forward: only
+// states archived after this exists become fully reconstructable. Append-only, deduped by codeTreeHash.
+function recordSnapshot(p, snap) {
+  const arc = loadArchive(p);
+  if (!arc) return null;
+  arc.snapshots = arc.snapshots || [];
+  const dup = arc.snapshots.find((s) => s.codeTreeHash && s.codeTreeHash === snap.codeTreeHash && s.specSetHash === (snap.specSetHash || s.specSetHash));
+  if (dup) return dup;
+  const rec = {
+    at: snap.at || null,
+    codeTreeHash: snap.codeTreeHash || null,
+    specSetHash: snap.specSetHash || null,
+    attest: snap.attest || null,
+    capability: snap.capability || null,
+    files: snap.files || {},
+  };
+  arc.snapshots.push(rec);
+  saveArchive(p, arc);
+  return rec;
+}
+function listSnapshots(p) { const arc = loadArchive(p); return (arc && arc.snapshots) || []; }
+
+// Materialize a snapshot's exact source into destDir from the encrypted blobs. Throws on a
+// tombstoned/missing/tampered blob (getBlob anchor-checks). Returns { dir, files: [rel…] }.
+function reconstructSnapshot(p, snap, key, destDir) {
+  const files = (snap && snap.files) || {};
+  const written = [];
+  for (const rel of Object.keys(files)) {
+    const hash = files[rel];
+    const pt = getBlob(p, hash, key);
+    if (pt == null) throw new Error('cannot reconstruct — blob ' + String(hash).slice(0, 12) + '… for ' + rel + ' is missing or tombstoned');
+    const abs = path.join(destDir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, pt);
+    written.push(rel);
+  }
+  return { dir: destDir, files: written };
+}
+
+module.exports = {
+  archiveDir, archiveManifestPath, blobPath, resolveKey, encryptBlob, decryptBlob,
+  secretScan, SECRET_PATTERNS, loadArchive, saveArchive, putBlob, getBlob, tombstone,
+  recordSnapshot, listSnapshots, reconstructSnapshot,
+};

package/src/e2e.js

@@ -0,0 +1,67 @@
+'use strict';
+// End-to-end encryption for the hosted relay path — TweetNaCl secretbox
+// (XSalsa20-Poly1305), byte-for-byte compatible with the phone page's nacl.secretbox.
+// The laptop and phone share a 32-byte key carried in the QR URL #fragment (never sent
+// to the relay), so the relay only ever stores/forwards opaque {n,c} ciphertext.
+const nacl = require('./vendor/tweetnacl.min.js');
+
+const b64 = (u) => Buffer.from(u).toString('base64');
+function b64url(u) { return b64(u).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); }
+function fromB64url(s) { s = String(s).replace(/-/g, '+').replace(/_/g, '/'); while (s.length % 4) s += '='; return new Uint8Array(Buffer.from(s, 'base64')); }
+
+function newKey() { return nacl.randomBytes(32); }            // Uint8Array(32)
+function newChannel() { return b64url(nacl.randomBytes(18)); } // 24 url-safe chars (matches the relay's channel regex)
+
+// seal(key, obj) → { n, c } base64 (nonce, ciphertext+tag). open() returns the object or null.
+function seal(key, obj) {
+  const n = nacl.randomBytes(24);
+  const c = nacl.secretbox(Buffer.from(JSON.stringify(obj), 'utf8'), n, key);
+  return { n: b64(n), c: b64(c) };
+}
+function open(key, blob) {
+  try {
+    const m = nacl.secretbox.open(new Uint8Array(Buffer.from(blob.c, 'base64')), new Uint8Array(Buffer.from(blob.n, 'base64')), key);
+    return m ? JSON.parse(Buffer.from(m).toString('utf8')) : null;
+  } catch (_) { return null; }
+}
+
+// ── Sealed box: encrypt to a signer's EXISTING ed25519 key, converted to X25519
+// (the standard birational map, as libsodium sealed boxes / age / Signal do). Lets us
+// address a request so ONLY the recipient can read it — no extra key, no roster change.
+const ll = nacl.lowlevel;
+const gf1 = ll.gf([1]);
+const u8 = (s) => new Uint8Array(Buffer.from(s, 'base64'));
+// bytes → field element (little-endian, top bit cleared)
+function unpack25519(o, n) { for (let i = 0; i < 16; i++) o[i] = n[2 * i] + (n[2 * i + 1] << 8); o[15] &= 0x7fff; }
+// modular inverse mod 2^255-19, by exponentiation to p-2 (tweetnacl's ladder)
+function inv25519(o, i) { const c = ll.gf(); let a; for (a = 0; a < 16; a++) c[a] = i[a]; for (a = 253; a >= 0; a--) { ll.S(c, c); if (a !== 2 && a !== 4) ll.M(c, c, i); } for (a = 0; a < 16; a++) o[a] = c[a]; }
+// ed25519 public key (raw 32) → X25519 public key: u = (1+y)/(1-y) mod p
+function edPubToX(edPub32) { const y = ll.gf(), a = ll.gf(), b = ll.gf(), z = new Uint8Array(32); unpack25519(y, edPub32); ll.A(a, gf1, y); ll.Z(b, gf1, y); inv25519(b, b); ll.M(a, a, b); ll.pack25519(z, a); return z; }
+// ed25519 secret key (64 = seed||pub) → X25519 secret: clamp(SHA-512(seed)[0..32])
+function edSecToX(edSec64) { const h = nacl.hash(edSec64.subarray(0, 32)); const s = h.slice(0, 32); s[0] &= 248; s[31] &= 127; s[31] |= 64; return s; }
+// Roster pubs are stored as SPKI (12-byte header + 32-byte key); take the raw key.
+function edPubRaw(spkiB64) { const uu = u8(spkiB64); return uu.length === 32 ? uu : uu.subarray(uu.length - 32); }
+
+// Each signer's INBOX channel is a deterministic hash of their (SPKI) public key —
+// public, so anyone can address them; only they can decrypt (below).
+function inboxChannel(pubB64) { return b64url(nacl.hash(Buffer.from('yay-inbox:v1:' + pubB64, 'utf8')).subarray(0, 18)); }
+
+// Seal `obj` so ONLY the holder of `pubB64`'s key can open it (anonymous sealed box:
+// an ephemeral X25519 keypair does a box to the recipient's converted pubkey).
+function sealTo(pubB64, obj) {
+  const xpub = edPubToX(edPubRaw(pubB64));
+  const eph = nacl.box.keyPair();
+  const n = nacl.randomBytes(24);
+  const c = nacl.box(Buffer.from(JSON.stringify(obj), 'utf8'), n, xpub, eph.secretKey);
+  return { epk: b64(eph.publicKey), n: b64(n), c: b64(c) };
+}
+// Open a sealed box with the recipient's ed25519 SECRET (64 bytes). Returns obj or null.
+function openSealed(secB64, sealed) {
+  try {
+    const xsec = edSecToX(u8(secB64));
+    const m = nacl.box.open(u8(sealed.c), u8(sealed.n), u8(sealed.epk), xsec);
+    return m ? JSON.parse(Buffer.from(m).toString('utf8')) : null;
+  } catch (_) { return null; }
+}
+
+module.exports = { newKey, newChannel, b64url, fromB64url, seal, open, inboxChannel, sealTo, openSealed, edPubToX, edSecToX };

package/src/extract.js

@@ -0,0 +1,179 @@
+'use strict';
+// Find YayLayer spec blocks in source, parse their fields, and grab the code
+// body of the unit they sit above (so verify can do static code⇔spec checks).
+
+const fs = require('fs');
+const { MARK_BEGIN, MARK_END, langOf } = require('./util');
+
+// Parse the "key: value" lines inside a spec block. Continuation lines (comment
+// lines with no "key:") append to the previous field.
+function parseSpec(blockLines) {
+  const fields = {};
+  let last = null;
+  for (const raw of blockLines) {
+    // Comment-agnostic: strip ANY leading comment punctuation (// # -- ; % ! ' (* <!-- *)
+    // and any trailing block-comment closer (*/ *) -->). This is what lets a spec
+    // block live in essentially any language's comments, not just // and #.
+    const line = raw
+      .replace(/^\s*(?:\/\/+|#+|--+|;+|%+|!+|'+|\(\*|<!--|\*+)\s?/, '')
+      .replace(/\s*(?:\*\/|\*\)|-->)\s*$/, '')
+      .trim();
+    if (!line || line.startsWith('∷YAY')) continue;
+    const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (m) {
+      last = m[1].toLowerCase();
+      fields[last] = m[2].trim();
+    } else if (last) {
+      fields[last] += ' ' + line;
+    }
+  }
+  return fields;
+}
+
+// The JS/TS declaration pattern (unchanged): function decls and const/let/var
+// (arrow/function) assignments. Kept precise so JS/TS analysis behaves exactly as before.
+const JS_DECL = /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)|(?:export\s+)?(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=/;
+
+// For the generic brace grabber: a keyword that introduces a unit by name, a
+// type/container keyword, and identifier-before-`(` (a definition or a call). We
+// EXCLUDE control-flow keywords from the identifier-before-`(` case so `if (`,
+// `for (`, `return foo(` etc. are never mistaken for a unit.
+const FN_KW = /\b(?:fn|def|defp|func|fun|function|sub)\s+(?:self\.)?([A-Za-z_][A-Za-z0-9_]*)/;
+const TYPE_KW = /\b(?:class|struct|interface|enum|record|trait|impl|contract|library|module|namespace|object|protocol|actor)\s+([A-Za-z_][A-Za-z0-9_]*)/;
+const CALLISH = /([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+const CONTROL = new Set(['if', 'for', 'while', 'switch', 'catch', 'foreach', 'return', 'new', 'sizeof', 'typeof', 'nameof', 'await', 'throw', 'using', 'lock', 'fixed', 'with', 'do', 'else', 'when', 'unless', 'case', 'elif', 'elsif', 'match', 'require', 'import', 'package', 'use', 'and', 'or', 'not', 'in', 'is', 'as']);
+
+// Brace-match from line `i` to the line closing its first `{` block; returns the
+// end line index. `body` includes the signature so file line numbers line up.
+function braceEnd(lines, i) {
+  let depth = 0, started = false, end = i;
+  for (let j = i; j < lines.length; j++) {
+    for (const ch of lines[j]) {
+      if (ch === '{') { depth++; started = true; }
+      else if (ch === '}') { depth--; }
+    }
+    end = j;
+    if (started && depth <= 0) break;
+    if (!started && j >= i + 2) break; // no block body on this decl
+  }
+  return end;
+}
+
+// JS/TS grabber (declaration + brace) — unchanged behaviour.
+function grabJsBody(lines, fromLine) {
+  for (let i = fromLine; i < Math.min(lines.length, fromLine + 6); i++) {
+    const m = lines[i].match(JS_DECL);
+    if (!m) continue;
+    const end = braceEnd(lines, i);
+    return { name: m[1] || m[2], startLine: i, body: lines.slice(i, end + 1).join('\n') };
+  }
+  return null;
+}
+
+// Generic C-family grabber (Go, Java, C/C++, Kotlin, Swift, PHP, Scala, Dart, C#,
+// Solidity, Rust, …). Body content isn't used for non-JS checks, so precision of
+// the body doesn't matter — we only need the unit's NAME and that it EXISTS.
+function grabGenericBraceBody(lines, fromLine) {
+  for (let i = fromLine; i < Math.min(lines.length, fromLine + 6); i++) {
+    const line = lines[i];
+    let name = null;
+    const fk = line.match(FN_KW);
+    if (fk) name = fk[1];
+    if (!name) {
+      CALLISH.lastIndex = 0; let m;
+      while ((m = CALLISH.exec(line))) { if (!CONTROL.has(m[1])) { name = m[1]; break; } }
+    }
+    if (!name) { const tk = line.match(TYPE_KW); if (tk) name = tk[1]; }
+    if (!name) continue;
+    const end = braceEnd(lines, i);
+    return { name, startLine: i, body: lines.slice(i, end + 1).join('\n') };
+  }
+  return null;
+}
+
+// Indentation grabber (Python): block continues while indented deeper than the
+// `def`/`class` line; blank lines belong to the block.
+function grabPythonBody(lines, fromLine) {
+  const decl = /^(\s*)(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)|^(\s*)class\s+([A-Za-z_][A-Za-z0-9_]*)/;
+  for (let i = fromLine; i < Math.min(lines.length, fromLine + 6); i++) {
+    const m = lines[i].match(decl);
+    if (!m) continue;
+    const indent = (m[1] !== undefined ? m[1] : m[3]).length;
+    const name = m[2] || m[4];
+    let end = i;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (!lines[j].trim()) { end = j; continue; } // blank line → still inside the block
+      const ind = (lines[j].match(/^(\s*)/)[1] || '').length;
+      if (ind <= indent) break;
+      end = j;
+    }
+    return { name, startLine: i, body: lines.slice(i, end + 1).join('\n') };
+  }
+  return null;
+}
+
+// def…end grabber (Ruby, Elixir): from `def name` to the matching `end` at the
+// same-or-lower indent. Best-effort — body precision isn't needed for these langs.
+function grabEndBody(lines, fromLine) {
+  const decl = /^(\s*)(?:def|defp)\s+(?:self\.)?([A-Za-z_][A-Za-z0-9_?!]*)/;
+  for (let i = fromLine; i < Math.min(lines.length, fromLine + 6); i++) {
+    const m = lines[i].match(decl);
+    if (!m) continue;
+    const indent = m[1].length;
+    const endRe = new RegExp('^\\s{0,' + indent + '}end\\b');
+    let end = i;
+    for (let j = i + 1; j < lines.length; j++) { end = j; if (endRe.test(lines[j])) break; }
+    return { name: m[2], startLine: i, body: lines.slice(i, end + 1).join('\n') };
+  }
+  return null;
+}
+
+// Grab the body of the first unit at or after `fromLine`, by body-FAMILY. JS keeps
+// its precise grabber; css/html/other reuse it (same as before, matches nothing new).
+function grabUnitBody(lines, fromLine, family) {
+  if (family === 'python') return grabPythonBody(lines, fromLine);
+  if (family === 'ruby') return grabEndBody(lines, fromLine);
+  if (family === 'brace') return grabGenericBraceBody(lines, fromLine);
+  return grabJsBody(lines, fromLine);
+}
+
+// Extract every Cell from one file.
+function extractFile(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  const lines = text.split(/\r?\n/);
+  const lang = langOf(file);
+  const cells = [];
+  for (let i = 0; i < lines.length; i++) {
+    const b = lines[i].match(MARK_BEGIN);
+    if (!b) continue;
+    const id = b[1];
+    const block = [lines[i]];
+    let end = -1;
+    for (let j = i + 1; j < lines.length; j++) {
+      block.push(lines[j]);
+      const e = lines[j].match(MARK_END);
+      if (e) { end = j; break; }
+    }
+    if (end === -1) {
+      cells.push({ id, file, startLine: i + 1, endLine: lines.length, malformed: 'missing ∷YAY-END marker' });
+      continue;
+    }
+    // normalized spec text (markers + inner lines, trailing ws stripped) → hashed later
+    const normalized = block.map((l) => l.replace(/\s+$/, '')).join('\n');
+    const spec = parseSpec(block);
+    const unit = grabUnitBody(lines, end + 1, lang);
+    cells.push({
+      id, file, startLine: i + 1, endLine: end + 1,
+      normalized, spec,
+      unitName: spec.unit || (unit && unit.name) || null,
+      detectedUnit: (unit && unit.name) || null, // the ACTUAL name found in the code (any language) — lets verify flag a spec⇔code rename in Python/Ruby/brace files too, not just via the JS AST
+      unitBody: unit ? unit.body : null,
+      unitBodyStart: unit ? unit.startLine : null,
+      unitFound: !!unit,
+    });
+    i = end;
+  }
+  return cells;
+}
+
+module.exports = { extractFile, parseSpec, grabUnitBody };

package/src/foundation.js

@@ -0,0 +1,143 @@
+'use strict';
+// The FOUNDATION SEAL — an owner-signed baseline of a project's fixed core, so that any
+// change to it is REVEALED at verify time. It watches two things:
+//
+//   1. CONTENT drift — the hash of each sealed core file (for the AI-rule files, only the
+//      YAYLAYER block, so the owner's own surrounding notes stay free).
+//   2. STRUCTURAL drift — the set of TRACKED files in watched zones (repo root, .github, the
+//      .yaylayer config), so a NEW or REMOVED file (a dropped payload, a rogue workflow) shows.
+//
+// It is CAUSE-AGNOSTIC: a hijacked AI, a disk/bit-rot corruption, a bad merge, or a fat-fingered
+// edit all surface the same way — the current bytes no longer match what the Owner last vouched
+// for. This is detection, not prevention: the human investigates and re-seals (owner key only).
+//
+// Pure + testable: the exported functions take a root and a caller-supplied list of tracked
+// files (so the git dependency lives in the CLI, and the smoke tests can drive it directly).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+// Owner-chosen exclusions (globs) for TRACKED files that legitimately churn inside a watched
+// zone (e.g. a committed CHANGELOG or version file). Gitignored files (.env…) are already out
+// (the seal watches only the tracked set), so this is only for committed-but-churning files.
+// The list is stored INSIDE the signed seal, so an exclusion is an owner-vouched act — the AI
+// cannot add "ignore my-payload.js" without the phone key. Each exclusion is a signed blind spot.
+function globToRe(g) {
+  const esc = String(g).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, ' ').replace(/\*/g, '[^/]*').replace(/ /g, '.*');
+  return new RegExp('^' + esc + '$');
+}
+function isIgnored(rel, globs) {
+  const f = String(rel).replace(/\\/g, '/');
+  return (globs || []).some((g) => { try { return globToRe(g).test(f); } catch (_) { return false; } });
+}
+
+// The BEGIN/END markers `yay constitution` wraps the managed rules block in. Content-sealing a
+// rule file hashes ONLY this block, so a project's own additions around it never trip the seal.
+const BLOCK_BEGIN = '<!-- YAYLAYER:BEGIN';
+const BLOCK_END = '<!-- YAYLAYER:END -->';
+function extractBlock(text) {
+  const i = text.indexOf(BLOCK_BEGIN);
+  if (i < 0) return null;
+  const j = text.indexOf(BLOCK_END, i);
+  if (j < 0) return null;
+  return text.slice(i, j + BLOCK_END.length);
+}
+
+// AI-rule files — content-sealed on their YAYLAYER block only (blockOnly:true).
+const RULE_FILES = [
+  'CLAUDE.md', 'AGENTS.md', '.cursorrules', 'GEMINI.md', '.windsurfrules', '.clinerules',
+  '.github/copilot-instructions.md',
+];
+// Other core files — content-sealed whole (they have no managed block).
+// `.gitignore` is sealed on purpose: it controls the structural blind spot (a rogue AI could
+// add `payload.js` to it to make the file untracked → invisible to the zone watch), so any
+// change to what's hidden is itself revealed and needs a re-seal.
+const CORE_FILES = [
+  // CI gate config across the common hosts (only the ones that exist are sealed).
+  '.github/workflows/yaylayer.yml', '.gitea/workflows/yaylayer.yml', 'azure-pipelines.yml', '.gitlab-ci.yml', 'bitbucket-pipelines.yml',
+  '.yaylayerignore', '.gitignore', 'CONSTITUTION.md', 'standard/STANDARD.md',
+  // `.gitattributes` sets the ledgers' union-merge driver — sealed so a rogue change to how the
+  // append-only records merge (e.g. silencing conflicts) is itself revealed.
+  '.gitattributes',
+];
+// Zones whose TRACKED file-set should stay stable — a new/removed file here is revealed.
+// Root is watched at TOP LEVEL only (depth 0); the others recurse.
+const WATCH_ZONES = [
+  { dir: '.', recurse: false },
+  { dir: '.github', recurse: true },
+  { dir: '.yaylayer', recurse: false },
+];
+
+// Digest one sealed file. blockOnly → hash just the YAYLAYER block. Returns null if absent
+// (a MISSING sealed file is itself a finding, surfaced by compareSeal, not an error here).
+function fileDigest(root, rel, blockOnly) {
+  let text;
+  try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch (_) { return null; }
+  if (blockOnly) { const b = extractBlock(text); return b == null ? null : sha256(b); }
+  return sha256(text);
+}
+
+// Restrict a caller-supplied tracked-file list to a zone's own files (posix-relative paths).
+function filesInZone(tracked, zone) {
+  const prefix = zone.dir === '.' ? '' : zone.dir.replace(/\\/g, '/').replace(/\/$/, '') + '/';
+  return (tracked || []).map((f) => f.replace(/\\/g, '/')).filter((f) => {
+    if (zone.dir === '.') return !f.includes('/'); // top-level only
+    if (!f.startsWith(prefix)) return false;
+    return zone.recurse ? true : !f.slice(prefix.length).includes('/');
+  }).sort();
+}
+
+// Build the seal payload the Owner signs. `tracked` is the repo's tracked-file list (e.g. from
+// `git ls-files`); `opts.files`/`opts.zones` override the defaults (owner --add/--remove).
+function buildSeal(root, tracked, opts = {}) {
+  const ruleFiles = opts.ruleFiles || RULE_FILES;
+  const coreFiles = opts.coreFiles || CORE_FILES;
+  const zones = opts.zones || WATCH_ZONES;
+  const ignore = opts.ignore || [];
+  const extra = opts.extra || []; // owner-added globs (`yay protect --add`): content-seal matching tracked files
+  const files = {};
+  // Only seal rule/core files that actually exist — you can't vouch for what's not there.
+  for (const rel of ruleFiles) { if (isIgnored(rel, ignore)) continue; const d = fileDigest(root, rel, true); if (d) files[rel] = { hash: d, block: true }; }
+  for (const rel of coreFiles) { if (isIgnored(rel, ignore)) continue; const d = fileDigest(root, rel, false); if (d) files[rel] = { hash: d, block: false }; }
+  // Owner-added extras: any tracked file matching an --add glob (whole-file hash).
+  if (extra.length) for (const rel of (tracked || []).map((f) => f.replace(/\\/g, '/'))) {
+    if (files[rel] || isIgnored(rel, ignore) || !isIgnored(rel, extra)) continue; // reuse glob-match via isIgnored
+    const d = fileDigest(root, rel, false); if (d) files[rel] = { hash: d, block: false };
+  }
+  const zoneSets = {};
+  for (const z of zones) zoneSets[z.dir] = { recurse: !!z.recurse, files: filesInZone(tracked, z).filter((f) => !isIgnored(f, ignore)) };
+  return { version: 1, files, zones: zoneSets, ignore, extra };
+}
+
+// Compare the CURRENT tree against a signed seal → the findings a human should see.
+//   changed[]      — a sealed file whose bytes/block no longer match
+//   missing[]      — a sealed file that has vanished
+//   addedFiles[]   — a tracked file that appeared in a watched zone since sealing
+//   removedFiles[] — a tracked file that vanished from a watched zone
+function compareSeal(root, seal, tracked) {
+  const ignore = (seal && seal.ignore) || []; // the SIGNED exclusions — applied to the current tree too
+  const changed = [], missing = [];
+  for (const rel of Object.keys((seal && seal.files) || {})) {
+    const want = seal.files[rel];
+    const now = fileDigest(root, rel, !!want.block);
+    if (now == null) missing.push(rel);
+    else if (now !== want.hash) changed.push(rel);
+  }
+  const addedFiles = [], removedFiles = [];
+  // Structural check needs the tracked-file list; skip it (content-only) when it's unavailable,
+  // so we never report false "removed" for every zone file.
+  if (Array.isArray(tracked)) for (const dir of Object.keys((seal && seal.zones) || {})) {
+    const z = seal.zones[dir];
+    const before = new Set(z.files || []);
+    const after = new Set(filesInZone(tracked, { dir, recurse: z.recurse }).filter((f) => !isIgnored(f, ignore)));
+    for (const f of after) if (!before.has(f)) addedFiles.push(f);
+    for (const f of before) if (!after.has(f)) removedFiles.push(f);
+  }
+  const clean = !changed.length && !missing.length && !addedFiles.length && !removedFiles.length;
+  return { clean, changed, missing, addedFiles: addedFiles.sort(), removedFiles: removedFiles.sort() };
+}
+
+module.exports = { buildSeal, compareSeal, fileDigest, extractBlock, filesInZone, sha256, RULE_FILES, CORE_FILES, WATCH_ZONES };