@zyaiting/keelson 0.4.0

package/src/lib/evidence.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { append, exists, read, readJson, walk, withLock, write } from './fs.js';
+import { runtimeDir } from './runtime-path.js';
+import { loadConfig, checkEntries } from './config.js';
+
+const { version } = createRequire(import.meta.url)('../../package.json');
+export const PAYLOAD_TYPE = 'application/vnd.in-toto+json';
+export const VERIFICATION_TYPE = 'https://github.com/Atingaii/keelson/verification/v1';
+export const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+const pae = (type, payload) => Buffer.concat([Buffer.from(`DSSEv1 ${Buffer.byteLength(type)} ${type} ${payload.length} `), payload]);
+
+export function contractFingerprint(root, changeDir) {
+  const cfgPath = path.join(root, '.keelson', 'config.yaml');
+  const cfg = loadConfig(cfgPath);
+  const locations = [
+    ['config', cfgPath], ['intent', path.join(root, '.keelson', 'INTENT.md')],
+    ['specs', path.resolve(root, cfg.paths.specs)], ['rules', path.join(root, '.keelson', 'rules')],
+    ['change', path.join(changeDir, 'change.md')], ['delta', path.join(changeDir, 'specs')],
+    ['decisions', path.join(changeDir, 'decisions.json')],
+  ];
+  const hash = crypto.createHash('sha256');
+  for (const [label, loc] of locations) {
+    hash.update(label).update('\0');
+    if (!exists(loc)) { hash.update('missing\0'); continue; }
+    const stat = fs.lstatSync(loc);
+    if (stat.isSymbolicLink()) throw new Error(`contract path must not be a symlink: ${loc}`);
+    const files = stat.isDirectory() ? walk(loc) : [''];
+    for (const rel of files) {
+      const file = rel ? path.join(loc, rel) : loc;
+      if (fs.lstatSync(file).isSymbolicLink()) throw new Error(`contract path must not be a symlink: ${file}`);
+      hash.update(rel).update('\0').update(fs.readFileSync(file)).update('\0');
+    }
+  }
+  return hash.digest('hex');
+}
+
+function signingKey(root) {
+  const keyFile = path.join(runtimeDir(root), 'attestation-key.pem');
+  return withLock(keyFile, () => {
+    if (!exists(keyFile)) {
+      const { privateKey } = crypto.generateKeyPairSync('ed25519');
+      write(keyFile, privateKey.export({ type: 'pkcs8', format: 'pem' }));
+      fs.chmodSync(keyFile, 0o600);
+    }
+    return crypto.createPrivateKey(read(keyFile));
+  });
+}
+
+export function recordStatement(root, dir, statement) {
+  const privateKey = signingKey(root);
+  const publicKey = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'pem' });
+  const payload = Buffer.from(JSON.stringify(statement));
+  const envelope = { payloadType: PAYLOAD_TYPE, payload: payload.toString('base64'), signatures: [{ keyid: sha256(publicKey), sig: crypto.sign(null, pae(PAYLOAD_TYPE, payload), privateKey).toString('base64') }] };
+  // Exported keys permit independent cryptographic checking, not automatic trust.
+  write(path.join(dir, 'evidence', 'public-key.pem'), publicKey);
+  write(path.join(dir, 'evidence', 'keys', `${sha256(publicKey)}.pem`), publicKey);
+  append(path.join(dir, 'ledger.jsonl'), `${JSON.stringify(envelope)}\n`);
+  return envelope;
+}
+
+export function verificationStatement({ tree, contract, results, claim, startedOn, unchanged, complete, model = null, host = null }) {
+  return {
+    _type: 'https://in-toto.io/Statement/v1',
+    subject: [{ name: 'worktree', digest: { [tree.length === 40 ? 'gitTree' : 'sha256']: tree } }, { name: 'contract', digest: { sha256: contract } }],
+    predicateType: VERIFICATION_TYPE,
+    predicate: { claim, startedOn, finishedOn: new Date().toISOString(), unchanged, complete, runs: results, runner: { keelson: version, host, model, attribution: 'caller-supplied' } },
+  };
+}
+
+/** Fail closed, using the last record (never search backwards for a passing run). */
+export function inspectEvidence(root, dir) {
+  const file = path.join(dir, 'ledger.jsonl');
+  if (!exists(file)) return { state: 'not-run', detail: 'no structured record; run `keelson check --record`' };
+  try {
+    const lines = read(file).trim().split('\n');
+    const envelopes = lines.map((line) => JSON.parse(line));
+    const keyFile = path.join(runtimeDir(root), 'attestation-key.pem');
+    if (!exists(keyFile)) return { state: 'untrusted', detail: 'record is from another machine; re-run `keelson check --record` here' };
+    const key = crypto.createPublicKey(crypto.createPrivateKey(read(keyFile)));
+    const keyid = sha256(key.export({ type: 'spki', format: 'pem' }));
+    let statement;
+    let locallyTrusted = false;
+    for (const envelope of envelopes) {
+      const payload = Buffer.from(envelope.payload ?? '', 'base64');
+      const valid = envelope.payloadType === PAYLOAD_TYPE && envelope.signatures?.filter((sig) => {
+        if (!/^[a-f0-9]{64}$/.test(sig.keyid)) return false;
+        const exported = path.join(dir, 'evidence', 'keys', `${sig.keyid}.pem`);
+        const publicKey = sig.keyid === keyid ? key : exists(exported) ? crypto.createPublicKey(read(exported)) : null;
+        return publicKey && sha256(publicKey.export({ type: 'spki', format: 'pem' })) === sig.keyid && crypto.verify(null, pae(PAYLOAD_TYPE, payload), publicKey, Buffer.from(sig.sig, 'base64'));
+      });
+      if (!valid?.length) throw new Error('signature mismatch');
+      const parsed = JSON.parse(payload);
+      if (parsed._type !== 'https://in-toto.io/Statement/v1') throw new Error('unknown statement schema');
+      if (parsed.predicateType === VERIFICATION_TYPE) { statement = parsed; locallyTrusted = valid.some((sig) => sig.keyid === keyid); }
+    }
+    if (!statement) return { state: 'not-run', detail: 'no verification statement' };
+    if (!locallyTrusted) return { state: 'untrusted', detail: 'latest verification was signed elsewhere; re-run checks locally' };
+    const p = statement.predicate;
+    const tree = Object.values(statement.subject.find((s) => s.name === 'worktree')?.digest ?? {})[0];
+    const contract = statement.subject.find((s) => s.name === 'contract')?.digest?.sha256;
+    if (!tree || !contract || !Array.isArray(p.runs) || !p.runs.length) throw new Error('incomplete statement');
+    for (const run of p.runs) {
+      if (!/^[a-f0-9]{64}$/.test(run.logDigest)) throw new Error('invalid log digest');
+      const log = path.join(dir, 'evidence', `${run.logDigest}.log`);
+      if (!exists(log) || fs.lstatSync(log).isSymbolicLink() || sha256(fs.readFileSync(log)) !== run.logDigest) throw new Error('missing or modified evidence log');
+    }
+    if (p.runs.some((r) => r.exit !== 0)) return { state: 'failed', detail: 'at least one recorded check failed', tree, contract };
+    if (!p.unchanged) return { state: 'stale', detail: 'worktree or contract changed during checking', tree, contract };
+    const configured = checkEntries(loadConfig(path.join(root, '.keelson', 'config.yaml'))).map((e) => e.command);
+    if (!p.complete || JSON.stringify(p.runs.map((r) => r.cmd)) !== JSON.stringify(configured)) return { state: 'partial', detail: 'record does not cover the configured check suite', tree, contract };
+    if (contract !== contractFingerprint(root, dir)) return { state: 'stale', detail: 'contract changed after verification', tree, contract };
+    return { state: 'passed', detail: 'locally signed record and log digests verified', tree, contract, statement };
+  } catch (error) { return { state: 'invalid', detail: `${error.message}; restore the intact evidence bundle, then re-run checks` }; }
+}
+
+export function trustCommands(root, commands, trusted = false) {
+  const file = path.join(runtimeDir(root), 'trusted-checks.json');
+  const digest = sha256(JSON.stringify(commands));
+  return withLock(file, () => {
+    if (readJson(file, null)?.digest === digest) return;
+    if (trusted) { write(file, JSON.stringify({ digest }) + '\n'); return; }
+    throw Object.assign(new Error(`check commands require local trust:\n${commands.map((c) => `  ${c}`).join('\n')}\nReview these commands, then run keelson check --trust --record. Trust is invalidated when commands change.`), { exitCode: 4 });
+  });
+}

package/src/lib/fs.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const exists = (p) => fs.existsSync(p);
+export const isDir = (p) => exists(p) && fs.statSync(p).isDirectory();
+export const read = (p) => fs.readFileSync(p, 'utf8');
+export const readOr = (p, fallback = '') => (exists(p) ? read(p) : fallback);
+export const write = (p, s) => {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = `${p}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    const mode = exists(p) ? fs.statSync(p).mode & 0o777 : 0o600;
+    const fd = fs.openSync(tmp, 'wx', mode);
+    try { fs.writeFileSync(fd, s); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    const deadline = Date.now() + 1000;
+    for (;;) {
+      try { fs.renameSync(tmp, p); break; }
+      catch (error) {
+        // Windows can briefly deny replacement while another process has the
+        // destination open. Keep the old file intact and retry the same atomic
+        // rename; never emulate replacement by unlinking the destination.
+        if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || Date.now() >= deadline) throw error;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+  } finally { fs.rmSync(tmp, { force: true }); }
+};
+export const mkdirp = (p) => fs.mkdirSync(p, { recursive: true });
+export const listDirs = (p) =>
+  isDir(p) ? fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort() : [];
+export const listFiles = (p) =>
+  isDir(p) ? fs.readdirSync(p, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort() : [];
+export const rmrf = (p) => fs.rmSync(p, { recursive: true, force: true });
+export const copyDir = (from, to, opts = {}) => fs.cpSync(from, to, { recursive: true, ...opts });
+
+/**
+ * Replace a generated directory without deleting the last good copy first.
+ * A fixed sibling backup makes an interrupted replacement recoverable on the next run.
+ */
+export function replaceDirSafe(dest, populate) {
+  const tmp = `${dest}.keelson-tmp`;
+  const bak = `${dest}.keelson-bak`;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+  if (!exists(dest) && exists(bak)) fs.renameSync(bak, dest);
+  if (exists(tmp)) rmrf(tmp);
+  if (exists(bak) && exists(dest)) rmrf(bak);
+
+  fs.mkdirSync(tmp, { recursive: true });
+  try {
+    populate(tmp);
+    if (exists(dest)) fs.renameSync(dest, bak);
+    fs.renameSync(tmp, dest);
+    if (exists(bak)) rmrf(bak);
+  } catch (error) {
+    if (exists(tmp)) rmrf(tmp);
+    if (!exists(dest) && exists(bak)) fs.renameSync(bak, dest);
+    throw error;
+  }
+}
+export const writeJson = (p, obj) => write(p, JSON.stringify(obj, null, 2) + '\n');
+export const readJson = (p, fallback = null, { strict = true } = {}) => {
+  if (!exists(p)) return fallback;
+  try {
+    return JSON.parse(read(p));
+  } catch (cause) {
+    if (strict) throw Object.assign(new Error(`cannot parse ${p}: ${cause.message}. Repair the file; it has not been overwritten.`), { exitCode: 5 });
+    return fallback;
+  }
+};
+
+/** Serialize a synchronous read/modify/write. A dead process lock is never guessed stale. */
+export function withLock(file, fn, { timeout = 10000 } = {}) {
+  const lock = `${file}.lock`;
+  mkdirp(path.dirname(lock));
+  const start = Date.now();
+  let fd;
+  for (;;) {
+    try { fd = fs.openSync(lock, 'wx', 0o600); break; }
+    catch (error) {
+      // A Windows lock file being closed/deleted may report a sharing error
+      // instead of EEXIST. Wait within the same bound; never remove its lock.
+      if (error.code !== 'EEXIST' && !(process.platform === 'win32' && ['EPERM', 'EACCES', 'EBUSY'].includes(error.code))) throw error;
+      if (Date.now() - start >= timeout) throw new Error(`lock timeout: ${lock}. Check for an active writer before removing an abandoned lock.`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  try { fs.writeFileSync(fd, `${process.pid}\n`); return fn(); }
+  finally {
+    fs.closeSync(fd);
+    const deadline = Date.now() + 1000;
+    for (;;) {
+      try { fs.unlinkSync(lock); break; }
+      catch (error) {
+        if (error.code === 'ENOENT') break;
+        // A competing Windows opener can briefly deny deletion too. Retry
+        // only removal of our acquired lock, never the completed callback.
+        if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || Date.now() >= deadline) throw error;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+  }
+}
+
+export function append(file, text) {
+  return withLock(file, () => {
+    const fd = fs.openSync(file, 'a', 0o600);
+    try { fs.writeFileSync(fd, text); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  });
+}
+
+/** Recursively list files under dir, returning relative posix paths. */
+export function walk(dir, { ignore = ['node_modules', '.git'] } = {}) {
+  const out = [];
+  const visit = (d, rel) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (ignore.includes(e.name)) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) visit(path.join(d, e.name), r);
+      else out.push(r);
+    }
+  };
+  if (isDir(dir)) visit(dir, '');
+  return out.sort();
+}

package/src/lib/git.js

@@ -0,0 +1,353 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { isUtf8 } from 'node:buffer';
+import { execFileSync } from 'node:child_process';
+import { walk } from './fs.js';
+
+export function git(root, args, { allowFail = true, env = {} } = {}) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, ...env } }).trim();
+  } catch (e) {
+    if (allowFail) return null;
+    throw e;
+  }
+}
+
+function gitBytes(root, args) {
+  return execFileSync('git', args, {
+    cwd: root,
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // The fallback below deliberately recognizes only Git's stable C locale
+    // diagnostic for an ordinary directory. Other Git failures are evidence
+    // that the input set cannot be established and must fail closed.
+    env: { ...process.env, LC_ALL: 'C', LANG: 'C', LANGUAGE: 'C' },
+  });
+}
+
+export const isGitRepo = (root) => git(root, ['rev-parse', '--is-inside-work-tree']) === 'true';
+export const headSha = (root) => git(root, ['rev-parse', '--short=10', 'HEAD']);
+export const currentBranch = (root) => git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+export const gitUserName = (root) => git(root, ['config', 'user.name']) || os.userInfo().username;
+
+export function gitStatusShort(root) {
+  const s = git(root, ['status', '--porcelain']);
+  return s === null ? null : s.split('\n').filter(Boolean);
+}
+
+export function recentCommits(root, n = 5) {
+  const s = git(root, ['log', `-${n}`, '--pretty=%h %s']);
+  return s ? s.split('\n') : [];
+}
+
+const KEELSON_DIR = Buffer.from('.keelson');
+const LENGTH_BUFFER = Buffer.allocUnsafe(8);
+
+function nulRecords(bytes) {
+  const records = [];
+  for (let start = 0; start < bytes.length;) {
+    const end = bytes.indexOf(0, start);
+    if (end === -1) break;
+    records.push(bytes.subarray(start, end));
+    start = end + 1;
+  }
+  return records;
+}
+
+function isKeelsonPath(file) {
+  return file.equals(KEELSON_DIR) || (file.length > KEELSON_DIR.length && file.subarray(0, KEELSON_DIR.length).equals(KEELSON_DIR) && file[KEELSON_DIR.length] === 0x2f);
+}
+
+function fingerprintPathResolver(root) {
+  const base = path.resolve(root);
+  const prefix = base.endsWith(path.sep) ? base : `${base}${path.sep}`;
+  const separators = path.sep === '\\' ? /[\\/]/ : /\//;
+  return (bytes) => {
+    if (!isUtf8(bytes)) throw new Error('cannot fingerprint a Git path that is not valid UTF-8');
+    const rel = bytes.toString('utf8');
+    // Git emits canonical relative names. Reject any escape component, then
+    // concatenate with the already-resolved root without a path.relative call
+    // for every entry in a large repository.
+    if (!rel || path.isAbsolute(rel) || rel.split(separators).includes('..')) {
+      throw new Error('cannot fingerprint a Git path outside the project root');
+    }
+    return `${prefix}${rel}`;
+  };
+}
+
+export function resolveFingerprintPath(root, bytes) {
+  return fingerprintPathResolver(root)(bytes);
+}
+
+function addGitEntries(entries, root, args, kind) {
+  const output = gitBytes(root, args);
+  for (const record of nulRecords(output)) {
+    const tab = kind === 'tracked' ? record.indexOf(0x09) : -1;
+    const metadata = tab === -1 ? null : record.subarray(0, tab).toString('ascii').split(' ');
+    const rawFile = tab === -1 ? record : record.subarray(tab + 1);
+    if (!rawFile.length || isKeelsonPath(rawFile)) continue;
+    entries.push({ kind, rawFile, indexMode: metadata ? Number.parseInt(metadata[0], 8) : null });
+  }
+}
+
+function hasGitMetadata(root) {
+  const device = fs.lstatSync(path.resolve(root)).dev;
+  const crossFilesystem = process.env.GIT_DISCOVERY_ACROSS_FILESYSTEM === '1';
+  for (let current = path.resolve(root);;) {
+    try {
+      fs.lstatSync(path.join(current, '.git'));
+      return true;
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    if (!crossFilesystem && fs.lstatSync(parent).dev !== device) return false;
+    current = parent;
+  }
+}
+
+function isOrdinaryNonGitDirectory(error, root) {
+  if (hasGitMetadata(root) || process.env.GIT_DIR) return false;
+  const stderr = Buffer.isBuffer(error?.stderr) ? error.stderr.toString('utf8') : String(error?.stderr ?? '');
+  const lines = stderr.trimEnd().split(/\r?\n/);
+  const ordinaryDirectory = /^fatal: not a git repository \(or any of the parent directories\): \.git$/;
+  const mountBoundary = /^fatal: not a git repository \(or any parent up to mount point .+\)$/;
+  const boundary = 'Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).';
+  return lines.some((line) => ordinaryDirectory.test(line) || mountBoundary.test(line))
+    && lines.every((line) => ordinaryDirectory.test(line) || mountBoundary.test(line) || line === boundary);
+}
+
+function updateField(hash, value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value));
+  LENGTH_BUFFER.writeBigUInt64BE(BigInt(bytes.length));
+  hash.update(LENGTH_BUFFER).update(bytes);
+}
+
+function contentDigest(value) {
+  return crypto.createHash('sha256').update(value).digest();
+}
+
+function prepareEntry(resolvePath, entry) {
+  const file = resolvePath(entry.rawFile);
+  if (!file) return null;
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    // A deleted tracked path is absent from the current worktree tree.
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw error;
+  }
+  entry.file = file;
+  entry.mode = stat.mode;
+  entry.type = stat.isDirectory() ? 'gitlink' : stat.isSymbolicLink() ? 'symlink' : stat.isFile() ? 'file' : 'other';
+  return entry;
+}
+
+function gitObjectDigests(root, entries) {
+  const digests = new Map();
+  const batched = [];
+  for (const entry of entries) {
+    // `--stdin-paths` is newline-delimited. Keep the rare newline names on
+    // the direct path so they cannot be split or silently omitted.
+    if (entry.file.includes('\n')) {
+      digests.set(entry, contentDigest(fs.readFileSync(entry.file)));
+    } else {
+      batched.push(entry);
+    }
+  }
+  if (!batched.length) return digests;
+  const input = Buffer.from(`${batched.map((entry) => entry.file).join('\n')}\n`);
+  const output = execFileSync('git', ['hash-object', '--no-filters', '--stdin-paths'], {
+    cwd: root,
+    input,
+    encoding: 'buffer',
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ['pipe', 'pipe', 'ignore'],
+  });
+  const lines = output.subarray(0, output.length && output[output.length - 1] === 0x0a ? -1 : output.length).toString('ascii').split('\n');
+  if (lines.length !== batched.length || lines.some((line) => !/^[a-f0-9]{40,64}$/.test(line))) {
+    throw new Error('git hash-object returned an invalid digest list');
+  }
+  for (let index = 0; index < batched.length; index++) {
+    // Git reads the current bytes once for this content-addressed blob ID;
+    // the outer worktree SHA-256 frames that digest with every path/mode.
+    digests.set(batched[index], Buffer.from(lines[index], 'ascii'));
+  }
+  return digests;
+}
+
+function hashGitEntries(hash, root, entries) {
+  const resolvePath = fingerprintPathResolver(root);
+  const prepared = entries.map((entry) => prepareEntry(resolvePath, entry)).filter(Boolean);
+  const regular = prepared.filter((entry) => entry.type === 'file');
+  const digests = gitObjectDigests(root, regular);
+  const slab = Buffer.allocUnsafe(512 * 1024);
+  const cachedStrings = new Map();
+  let offset = 0;
+  const stringBytes = (value) => {
+    let bytes = cachedStrings.get(value);
+    if (!bytes) {
+      bytes = Buffer.from(value);
+      cachedStrings.set(value, bytes);
+    }
+    return bytes;
+  };
+  const field = (value) => {
+    const bytes = Buffer.isBuffer(value) ? value : stringBytes(String(value));
+    if (offset + 8 + bytes.length > slab.length) {
+      if (offset) hash.update(slab.subarray(0, offset));
+      offset = 0;
+      if (8 + bytes.length > slab.length) {
+        updateField(hash, bytes);
+        return;
+      }
+    }
+    slab.writeUInt32BE(0, offset);
+    slab.writeUInt32BE(bytes.length, offset + 4);
+    offset += 8;
+    bytes.copy(slab, offset);
+    offset += bytes.length;
+  };
+  for (const entry of prepared) {
+    field(entry.kind);
+    field(entry.rawFile);
+    if (entry.type === 'gitlink') {
+      field('gitlink');
+      field(git(entry.file, ['rev-parse', '--verify', 'HEAD']) ?? 'missing');
+    } else if (entry.type === 'symlink') {
+      field('symlink');
+      field(contentDigest(fs.readlinkSync(entry.file, { encoding: 'buffer' })));
+    } else if (entry.type === 'file') {
+      field('file');
+      field(entry.mode & 0o111);
+      field(digests.get(entry));
+    } else {
+      field('other');
+      field(entry.mode);
+    }
+  }
+  if (offset) hash.update(slab.subarray(0, offset));
+}
+
+/**
+ * Fingerprint current inputs with `.keelson/` excluded, so a ledger append
+ * does not invalidate its own evidence. Git supplies the tracked and
+ * non-ignored path set; every included entry is freshly content-addressed on
+ * every call (regular files through Git's native reader). This deliberately
+ * avoids stat or filename caches, including same-mtime edits.
+ *
+ * Git fingerprints are SHA-256 rather than Git tree IDs. Existing 40-byte
+ * Git-tree records therefore become stale and must be re-recorded.
+ */
+function gitFingerprintEntries(root) {
+  const entries = [];
+  try {
+    addGitEntries(entries, root, ['ls-files', '-s', '-z'], 'tracked');
+    addGitEntries(entries, root, ['ls-files', '--others', '--exclude-standard', '-z'], 'untracked');
+  } catch (error) {
+    // Do not pay for rev-parse in normal Git projects. The legacy fallback
+    // remains for ordinary non-Git directories; an error inside a repository
+    // still propagates rather than silently omitting inputs.
+    if (error?.status === 128 && isOrdinaryNonGitDirectory(error, root)) return null;
+    throw error;
+  }
+  entries.sort((a, b) => Buffer.compare(a.rawFile, b.rawFile) || a.kind.localeCompare(b.kind));
+  return entries;
+}
+
+export function worktreeFingerprint(root) {
+  const entries = gitFingerprintEntries(root);
+  if (entries) {
+    const hash = crypto.createHash('sha256').update('keelson-worktree-v2\0');
+    hashGitEntries(hash, root, entries);
+    return hash.digest('hex');
+  }
+  const h = crypto.createHash('sha256').update('keelson-worktree-v2\0');
+  for (const f of walk(root, { ignore: ['node_modules', '.git', '.keelson'] })) {
+    const full = path.join(root, f);
+    const stat = fs.lstatSync(full);
+    updateField(h, 'non-git');
+    updateField(h, f);
+    if (stat.isSymbolicLink()) {
+      updateField(h, 'symlink');
+      updateField(h, contentDigest(fs.readlinkSync(full, { encoding: 'buffer' })));
+    } else {
+      updateField(h, 'file');
+      updateField(h, String(stat.mode & 0o111));
+      updateField(h, contentDigest(fs.readFileSync(full)));
+    }
+  }
+  return h.digest('hex');
+}
+
+export const lastTag = (root) => git(root, ['describe', '--tags', '--abbrev=0']);
+
+/** Names of change directories deleted (folded) since a ref, from git history. */
+export function foldedSince(root, ref) {
+  if (!isGitRepo(root) || !ref) return [];
+  const log = git(root, ['log', `${ref}..HEAD`, '--diff-filter=D', '--name-only', '--pretty=format:', '--', '.keelson/changes']);
+  if (!log) return [];
+  const names = new Set();
+  for (const line of log.split('\n')) {
+    const m = line.match(/^\.keelson\/changes\/([^/]+)\/change\.md$/);
+    if (m && m[1] !== 'archive') names.add(m[1]);
+  }
+  return [...names];
+}
+
+/** Ledgers of changes that were folded (deleted) — recovered from git history. */
+export function historicalLedgers(root) {
+  if (!isGitRepo(root)) return [];
+  const log = git(root, ['log', '--diff-filter=D', '--name-only', '--pretty=format:@@%H', '--', '.keelson/changes']);
+  if (!log) return [];
+  const out = [];
+  let commit = null;
+  for (const line of log.split('\n')) {
+    if (line.startsWith('@@')) {
+      commit = line.slice(2);
+      continue;
+    }
+    if (!commit || !/\.keelson\/changes\/[^/]+\/ledger\.md$/.test(line)) continue;
+    const content = git(root, ['show', `${commit}^:${line}`]);
+    if (content) out.push({ path: line, commit, content });
+  }
+  return out;
+}
+
+/** Files that import or require any of the given modules, by basename. Navigation, not proof. */
+export function importers(root, files) {
+  const names = [...new Set(files.map((f) => path.basename(f).replace(/\.(m?js|cjs|ts|tsx|jsx|py|go|rs|rb|java|kt|swift)$/, '')).filter(Boolean))];
+  if (!names.length) return [];
+  const pattern = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+  const re = `(import|require|from|include|use)\\b[^\\n]*\\b(${pattern})\\b`;
+  // Git uses platform ERE implementations. Keep its expression to POSIX ERE:
+  // GNU-only \b is not a word boundary there, and [^\n] excludes the letter n.
+  const gitRe = `(import|require|from|include|use)([^A-Za-z0-9_].*[^A-Za-z0-9_]|[^A-Za-z0-9_])(${pattern})([^A-Za-z0-9_]|$)`;
+  let matches = null;
+  if (isGitRepo(root)) {
+    try {
+      const out = execFileSync('git', ['grep', '--untracked', '--exclude-standard', '-z', '-l', '-E', '-I', '--', gitRe], { cwd: root, encoding: 'buffer', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+      matches = nulRecords(out).map((file) => file.toString('utf8'));
+    } catch (error) {
+      // `git grep` uses status 1 for a successful search with no matches.
+      if (error?.status === 1) matches = [];
+    }
+  }
+  if (matches === null) {
+    const hits = [];
+    const rx = new RegExp(re);
+    for (const f of walk(root, { ignore: ['node_modules', '.git', '.keelson', 'dist', 'build'] })) {
+      if (!/\.(m?js|cjs|ts|tsx|jsx|py|go|rs|rb|java|kt|swift|vue|svelte)$/.test(f)) continue;
+      try {
+        if (rx.test(fs.readFileSync(path.join(root, f), 'utf8'))) hits.push(f);
+      } catch {}
+    }
+    matches = hits;
+  }
+  const self = new Set(files.map((f) => f.replace(/\\/g, '/')));
+  return matches.filter((file) => file && !self.has(file));
+}

package/src/lib/glob.js

@@ -0,0 +1,54 @@
+/** Minimal glob → RegExp: supports **, *, ?, and {a,b}. Posix separators. */
+export function globToRegExp(glob) {
+  let re = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        // '**/' matches zero or more directories; bare '**' matches anything
+        if (glob[i + 2] === '/') {
+          re += '(?:.*/)?';
+          i += 3;
+        } else {
+          re += '.*';
+          i += 2;
+        }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else if (c === '{') {
+      const end = glob.indexOf('}', i);
+      if (end === -1) {
+        re += '\\{';
+        i += 1;
+      } else {
+        const alts = glob.slice(i + 1, end).split(',').map(escape);
+        re += `(?:${alts.join('|')})`;
+        i = end + 1;
+      }
+    } else {
+      re += escape(c);
+      i += 1;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+const escape = (s) => s.replace(/[.+^$()|[\]\\]/g, '\\$&');
+
+export function globMatch(glob, filePath) {
+  const p = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  const g = glob.replace(/^\.\//, '');
+  if (globToRegExp(g).test(p)) return true;
+  // A directory-style glob like "src/api/" or "src/api" matches everything beneath it.
+  if (!/[*?{]/.test(g)) {
+    const dir = g.replace(/\/$/, '');
+    return p === dir || p.startsWith(dir + '/');
+  }
+  return false;
+}