ultra-builder-pro-cli 5.0.0 → 6.0.0

package/engine/expect.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+const path = require('node:path');
+const { Worker } = require('node:worker_threads');
+
+const signals = require('./signals.cjs');
+
+function expectOutput(expect, output) {
+  return new Promise((resolve, reject) => {
+    // Isolate the acceptance author's regexp so its backtracking has a 5-second limit.
+    const worker = new Worker(path.join(__dirname, 'expect-worker.cjs'),
+      { workerData: { expect, output } });
+    let finished = false;
+    const handlers = Object.entries(signals).map(([signal, exitCode]) =>
+      [signal, () => finish(null, Object.assign(new Error('Check interrupted.'), { exitCode }))]);
+    const finish = (result, error) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+      worker.terminate().then(() => error ? reject(error) : resolve(result), reject);
+    };
+    const timer = setTimeout(() => finish('expect-timeout'), 5000);
+    for (const [signal, handler] of handlers) process.on(signal, handler);
+    worker.once('message', (matches) => finish(matches ? 'exit-0' : 'expect-unmet'));
+    worker.once('error', (error) => finish(null, error));
+    worker.once('exit', (code) => {
+      if (!finished) finish(null, new Error(`Expect worker exited without a result (${code}).`));
+    });
+  });
+}
+
+module.exports = { expectOutput };

package/engine/formats.cjs

@@ -0,0 +1,189 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const strings = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string');
+const unique = (items) => [...new Set(items)];
+const problem = (code, message, hint) => ({ code, message, hint });
+
+function assertFile(ok, file, message) {
+  if (!ok) throw new Error(`${file}: ${message}`);
+}
+
+function read(root, file, optional = false) {
+  try { return fs.readFileSync(path.join(root, '.ultra', file), 'utf8'); }
+  catch (error) {
+    if (optional && error.code === 'ENOENT') return '';
+    throw new Error(`.ultra/${file}: ${error.message}`);
+  }
+}
+
+function readRecord(root, relative) {
+  const file = path.join(root, relative);
+  const result = { exists: true, bytes: null };
+  let fd;
+  try {
+    const entry = fs.lstatSync(file, { throwIfNoEntry: false });
+    result.exists = entry !== undefined;
+    if (!entry?.isFile()) return result;
+    const parent = fs.realpathSync(path.dirname(file));
+    const location = path.relative(fs.realpathSync(root), parent);
+    if (path.isAbsolute(location) || location === '..' || location.startsWith(`..${path.sep}`)) {
+      return result;
+    }
+    fd = fs.openSync(path.join(parent, path.basename(file)),
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    if (fs.fstatSync(fd).isFile()) result.bytes = fs.readFileSync(fd);
+  } catch (error) {
+    if (!['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) {
+      throw new Error(`${relative}: ${error.message}`);
+    }
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+  return result;
+}
+
+function parse(text, file) {
+  try { return JSON.parse(text); }
+  catch (error) { throw new Error(`${file}: ${error.message}`); }
+}
+
+function markdown(text, visit) {
+  let fence = null;
+  const lines = text.replace(/\r\n/gu, '\n').split('\n');
+  lines.forEach((line, index) => {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/u);
+    if (fence) {
+      visit(line, index + 1, false);
+      if (marker && marker[1][0] === fence.marker[0]
+          && marker[1].length >= fence.marker.length && !marker[2].trim()) fence = null;
+    } else if (marker && (marker[1][0] !== '`' || !marker[2].includes('`'))) {
+      fence = { marker: marker[1], line: index + 1 };
+      visit(line, index + 1, false);
+    } else visit(line, index + 1, true);
+  });
+  return fence?.line ?? null;
+}
+
+function requirements(text) {
+  const result = new Map();
+  const requirementText = new Map();
+  const shared = [];
+  let current = null;
+  const finish = () => {
+    if (!current) return;
+    const lines = current.lines.map((line) => line.trimEnd());
+    while (lines.length && lines.at(-1) === '') lines.pop();
+    while (lines.length && lines[0] === '') lines.shift();
+    const text = lines.join('\n');
+    result.set(current.id, hash(text));
+    requirementText.set(current.id, text);
+    current = null;
+  };
+  const unclosed = markdown(text, (line, number, outside) => {
+    const heading = outside && line.match(/^ {0,3}(#{1,2})(?:[ \t]+(.*)|[ \t]*)$/u);
+    const isRequirement = heading && heading[1] === '##' && heading[2]?.startsWith('REQ-');
+    if (outside && /^ {0,3}#+\s*REQ(?:[-_]|\s+\d)/iu.test(line) && !isRequirement) {
+      assertFile(false, `.ultra/spec.md:${number}`, `malformed requirement heading: ${line}`);
+    }
+    if (heading) {
+      finish();
+      const title = heading[2] || '';
+      if (heading[1] === '##' && title.startsWith('REQ-')) {
+        const id = title.split(/\s/u)[0];
+        const file = `.ultra/spec.md:${number}`;
+        assertFile(ID.test(id.slice(4)), file, `malformed requirement heading: ${line}`);
+        assertFile(!result.has(id), file, `duplicate requirement id ${id}`);
+        current = { id, lines: [] };
+      }
+    }
+    if (current) current.lines.push(line);
+    else if (line.trimEnd()) shared.push(line.trimEnd());
+  });
+  assertFile(!unclosed, `.ultra/spec.md:${unclosed}`, 'unclosed fence');
+  finish();
+  return { reqs: result, requirementText, shared: hash(shared.join('\n')) };
+}
+
+function validateCheck(item, valid) {
+  const invariant = Object.hasOwn(item, 'fix');
+  valid(!invariant || (typeof item.fix === 'string' && item.fix.trim().length > 0),
+    `${item.id}: fix must be a non-empty string`);
+  valid(invariant ? item.covers.length === 0 : item.covers.length > 0,
+    `${item.id}: invariants must cover nothing; other checks must cover a requirement`);
+  valid(item.run.trim().length > 0, `${item.id}: run must be non-empty`);
+  const timeout = item.timeout_sec === undefined ? 600 : item.timeout_sec;
+  valid(Number.isInteger(timeout) && timeout > 0 && timeout <= 86400,
+    `${item.id}: invalid timeout_sec`);
+  valid(typeof item.expect === 'string' && item.expect.length > 0,
+    `${item.id}: expect must be a non-empty regular expression string`);
+  let pattern;
+  try { pattern = new RegExp(item.expect, 'mu'); }
+  catch (error) { valid(false, `${item.id}: invalid expect: ${error.message}`); }
+  valid(!pattern.test(''), `${item.id}: expect must not match the empty string`);
+}
+
+function registry(root, file, kinds) {
+  const data = parse(read(root, file), `.ultra/${file}`);
+  const valid = (ok, message) => assertFile(ok, `.ultra/${file}`, message);
+  valid(object(data) && data.version === 1, 'expected an object with version 1');
+  if (file === 'plan.json' && Object.hasOwn(data, 'cleanup_every')) {
+    valid(Number.isInteger(data.cleanup_every) && data.cleanup_every > 0,
+      'cleanup_every must be a positive integer');
+  }
+  for (const [kind, fields] of Object.entries(kinds)) {
+    valid(Array.isArray(data[kind]), `${kind} must be an array`);
+    const ids = new Set();
+    for (const item of data[kind]) {
+      valid(object(item) && typeof item.id === 'string' && ID.test(item.id),
+        `invalid ${kind} id`);
+      valid(!ids.has(item.id), `duplicate id ${item.id}`);
+      ids.add(item.id);
+      for (const [field, type] of Object.entries(fields)) {
+        valid(type === 'array' ? strings(item[field]) : typeof item[field] === type,
+          `${item.id}: invalid or missing ${field}`);
+      }
+      if (kind === 'checks') validateCheck(item, valid);
+      if (kind === 'nodes' && item.scope !== undefined) {
+        valid(strings(item.scope), `${item.id}: scope must be an array of strings`);
+      }
+      if (kind === 'nodes' && Object.hasOwn(item, 'kind')) {
+        valid(item.kind === 'cleanup', `${item.id}: kind must be cleanup`);
+        valid(item.covers.length === 0, `${item.id}: a cleanup node must cover nothing`);
+      }
+      if (kind === 'milestones' && item.journey !== undefined) {
+        valid(typeof item.journey === 'string', `${item.id}: journey must be a string`);
+      }
+    }
+  }
+  return data;
+}
+
+function rulingProblems(text) {
+  const problems = [];
+  // Each part needs a character that is neither space nor punctuation, so matching finds a
+  // split where all have content. No gap after a part: it would multiply backtracking.
+  const gap = '[\\s\\p{P}]*';
+  const part = `${gap}[^\\s\\p{P}].*?`;
+  const ruling = new RegExp(`^- ${gap}\\d{4}-\\d{2}-\\d{2}${gap}L[0-4]${gap}裁决${part}因为`
+    + `(?!${gap}如果判断错了${gap}代价)${part}(?:如果判断错了${gap})?代价(?:是|(?!是))${part}$`, 'u');
+  const hint = 'Use: - YYYY-MM-DD L0–L4 裁决：decision — 因为 reason '
+    + '— 如果判断错了，代价是 cost';
+  const unclosed = markdown(text, (line, number, outside) => {
+    if (outside && /^\s*[-*+] /u.test(line) && !ruling.test(line)) {
+      problems.push(problem('malformed-ruling', `.ultra/rulings.md:${number}: ${line}`, hint));
+    }
+  });
+  if (unclosed) problems.push(problem('malformed-ruling',
+    `.ultra/rulings.md:${unclosed}: unclosed fence`, 'Close the fence opened on this line.'));
+  return problems;
+}
+
+module.exports = { ID, hash, object, strings, unique, problem, read, readRecord, markdown,
+  requirements, registry, rulingProblems };

package/engine/git-state.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { spawn, execFileSync } = require('node:child_process');
+const INTERRUPTS = require('./signals.cjs');
+let localVariables;
+const boundRoots = new Set();
+const mergeOptions = ['-c', 'maintenance.auto=false', '-c', 'gc.auto=0'];
+const bindGit = (root) => { boundRoots.add(root); return () => boundRoots.delete(root); };
+
+function gitEnvironment(root) {
+  localVariables ??= execFileSync('git', ['rev-parse', '--local-env-vars'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim().split('\n');
+  const env = { ...process.env };
+  for (const name of [...localVariables, 'GIT_LITERAL_PATHSPECS', 'GIT_GLOB_PATHSPECS',
+    'GIT_NOGLOB_PATHSPECS', 'GIT_ICASE_PATHSPECS']) delete env[name];
+  if (boundRoots.has(root)) env.GIT_CEILING_DIRECTORIES = path.dirname(root);
+  return env;
+}
+
+function gitFailure(args, error) {
+  const reason = String(error.stderr || '').split('\n').find((line) => line.trim());
+  error.message = `Git failed: ${args.join(' ')}` + (reason ? `: ${reason}` : '');
+  if (INTERRUPTS[error.signal]) error.exitCode = INTERRUPTS[error.signal];
+  return error;
+}
+
+function git(root, args) {
+  if (boundRoots.has(root)) args = [...mergeOptions, ...args];
+  try {
+    return execFileSync('git', args, { cwd: root, env: gitEnvironment(root), maxBuffer: Infinity,
+      stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (error) {
+    throw gitFailure(args, error);
+  }
+}
+
+function gitAsync(root, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd: root, env: gitEnvironment(root),
+      stdio: ['ignore', 'pipe', 'pipe'], ...options });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.on('error', (error) => reject(gitFailure(args, error)));
+    child.on('close', (code, signal) => {
+      if (code === 0) resolve(Buffer.concat(stdout));
+      else reject(gitFailure(args, Object.assign(new Error(),
+        { code, signal, stderr: Buffer.concat(stderr).toString('utf8') })));
+    });
+  });
+}
+
+const ownedFiles = new Set(['.ultra/spec.md', '.ultra/checks.json',
+  '.ultra/plan.json', '.ultra/rulings.md']);
+const ownedDirs = ['.ultra/ledger', '.ultra/records', '.ultra/.runtime'];
+const engineOwned = (name) => ownedFiles.has(name)
+  || ownedDirs.some((dir) => name === dir || name.startsWith(`${dir}/`));
+
+function fingerprintEntries(digest, tree, exclude) {
+  // ls-tree separates mode/type/object metadata from the unquoted path with a tab.
+  const PATH_SEPARATOR = 0x09;
+  let start = 0;
+  for (let end = tree.indexOf(0); end !== -1; end = tree.indexOf(0, start)) {
+    const entry = tree.subarray(start, end);
+    const name = entry.subarray(entry.indexOf(PATH_SEPARATOR) + 1).toString('utf8');
+    if (!exclude(name)) digest.update(tree.subarray(start, end + 1));
+    start = end + 1;
+  }
+}
+
+function codeState(root, exclude = engineOwned) {
+  const digest = createHash('sha256');
+  fingerprintEntries(digest, git(root, ['ls-tree', '--full-tree', '-z', 'HEAD']),
+    (name) => name === '.ultra');
+  fingerprintEntries(digest, git(root, ['ls-tree', '--full-tree', '-z', 'HEAD', '--',
+    '.ultra/']), engineOwned);
+  const changes = git(root, ['--no-optional-locks', 'status', '--porcelain', '-z',
+    `--untracked-files=${exclude === engineOwned ? 'normal' : 'all'}`])
+    .toString('utf8').split('\0');
+  let dirty = false;
+  for (let i = 0; i < changes.length; i++) {
+    if (!changes[i]) continue;
+    if (!exclude(changes[i].slice(3).replace(/\/$/u, ''))) dirty = true;
+    if (/[RC]/u.test(changes[i].slice(0, 2)) && !exclude(changes[++i])) dirty = true;
+  }
+  return { code: digest.digest('hex'), dirty };
+}
+
+function projectRoot(requested) {
+  const root = path.resolve(requested);
+  if (!fs.existsSync(root)) {
+    throw new Error(`--root ${root} does not exist. Choose an existing project directory.`);
+  }
+  let top;
+  try { top = git(root, ['rev-parse', '--show-toplevel']).toString('utf8').replace(/\n$/u, ''); }
+  catch (error) {
+    if (error.exitCode) throw error;
+    throw new Error(`${root} is not inside a Git work tree. Run git init first.`);
+  }
+  try { git(top, ['rev-parse', '--verify', 'HEAD']); }
+  catch (error) {
+    if (error.exitCode) throw error;
+    throw new Error(`${top} has no commit. Commit the code first.`);
+  }
+  return top;
+}
+
+module.exports = { git, gitAsync, gitEnvironment, bindGit, mergeOptions, codeState, projectRoot };

package/engine/ledger.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ID, object, strings, read } = require('./formats.cjs');
+
+const hashValue = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+const hashes = (value) => object(value) && Object.values(value).every(hashValue);
+const textFields = (record, fields) => fields.every((key) => typeof record[key] === 'string');
+const checkSnapshots = (value) => object(value) && Object.values(value).every((check) =>
+  object(check) && hashValue(check.fp) && strings(check.covers));
+const LEDGERS = ['evidence', 'plan-log', 'nodes', 'milestones', 'approvals'];
+const approvalItem = (value) => typeof value === 'string' && value.split('/').length === 2
+  && value.split('/').every((part) => ID.test(part));
+
+function validApproval(record) {
+  return strings(record.items) && record.items.length > 0
+    && record.items.every((item, i) => approvalItem(item) && (!i || record.items[i - 1] < item))
+    && object(record.owner) && typeof record.owner.words === 'string'
+    && record.owner.words.trim().length > 0 && typeof record.owner.proxy === 'boolean';
+}
+
+function validClosure(record) {
+  const fields = {
+    code: hashValue,
+    reqs: hashes,
+    journey: (v) => object(v) && textFields(v, ['check', 'run']),
+    review: (v) => object(v) && textFields(v, ['path']) && hashValue(v.sha256),
+    owner: (v) => object(v) && textFields(v, ['words']) && typeof v.proxy === 'boolean',
+  };
+  return typeof record.milestone === 'string'
+    && Object.entries(fields).every(([key, valid]) => !Object.hasOwn(record, key)
+      || valid(record[key]));
+}
+
+function recordTime(value) {
+  return typeof value === 'string'
+    && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+
+function validRecord(record, name) {
+  if (!object(record) || record.v !== 1 || !recordTime(record.at)) return false;
+  if (['evidence', 'plan-log', 'nodes'].includes(name)
+      && Object.hasOwn(record, 'shared') && !hashValue(record.shared)) return false;
+  if (name === 'evidence') {
+    return textFields(record, ['check', 'run', 'reason', 'log'])
+      && typeof record.dirty === 'boolean' && hashValue(record.code)
+      && hashValue(record.check_fp) && hashes(record.reqs)
+      && ['pass', 'fail', 'unknown'].includes(record.outcome)
+      && (record.exit_code === null || Number.isInteger(record.exit_code))
+      && Number.isInteger(record.duration_ms) && record.duration_ms >= 0
+      && (record.error_line === null || typeof record.error_line === 'string');
+  }
+  if (name === 'plan-log') {
+    const diff = record.diff;
+    return typeof record.milestone === 'string' && hashes(record.requirements)
+      && strings(record.nodes) && checkSnapshots(record.checks)
+      && (!object(diff) || !Object.hasOwn(diff, 'shared') || diff.shared === true)
+      && ['baseline', 'change', 'removed'].includes(record.type)
+      && (record.type !== 'removed' || (!Object.keys(record.requirements).length
+        && !record.nodes.length && !Object.keys(record.checks).length))
+      && (record.type === 'baseline' || (object(diff)
+        && ['added', 'removed', 'modified', 'nodes_added', 'nodes_removed',
+          'checks_added', 'checks_removed', 'checks_modified']
+          .every((key) => strings(diff[key]))));
+  }
+  if (name === 'nodes') return textFields(record, ['node']) && hashValue(record.code)
+    && hashes(record.reqs) && strings(record.runs);
+  if (name === 'approvals') return validApproval(record);
+  return name === 'milestones' && validClosure(record);
+}
+
+function ledger(root, name) {
+  const file = `ledger/${name}.jsonl`;
+  const text = read(root, file, true);
+  const lines = text.split('\n');
+  const records = [];
+  const warnings = [];
+  let repairEnd = null;
+  lines.forEach((line, index) => {
+    if (!line.trim()) return;
+    let record;
+    try { record = JSON.parse(line); } catch { /* validated below */ }
+    if (validRecord(record, name)) { records.push(record); return; }
+    const location = `.ultra/${file}:${index + 1}`;
+    if (index === lines.length - 1 && !text.endsWith('\n')) {
+      repairEnd = Buffer.byteLength(text.slice(0, text.lastIndexOf('\n') + 1));
+      warnings.push(`${location}: incomplete final ledger record ignored; repaired on next append`);
+    } else throw new Error(`${location}: malformed ledger record; remove or repair that line.`);
+  });
+  return { records, warnings, repairEnd, needsNewline: !!text && !text.endsWith('\n') };
+}
+
+function latest(records, field, id) {
+  let result;
+  for (const record of records) {
+    if (record[field] === id && (!result || record.at >= result.at)) result = record;
+  }
+  return result;
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) {
+    if (error.code === 'EPERM') return true;
+    if (error.code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+function lockPid(root, name) {
+  try {
+    const pid = Number(fs.readFileSync(path.join(root, '.ultra/.runtime', `${name}.lock`), 'utf8'));
+    return Number.isInteger(pid) && pid > 0 && alive(pid) ? pid : null;
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function removeOwnedLock(file, pid) {
+  try {
+    if (Number(fs.readFileSync(file, 'utf8')) === pid) fs.unlinkSync(file);
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+function breakDeadLock(file, pid) {
+  const breaker = `${file}.break`;
+  let fd;
+  try { fd = fs.openSync(breaker, 'wx'); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    try {
+      if (Date.now() - fs.statSync(breaker).mtimeMs > 10000) {
+        fs.unlinkSync(breaker);
+        return breakDeadLock(file, pid);
+      }
+    } catch (missing) { if (missing.code !== 'ENOENT') throw missing; }
+    return;
+  }
+  try {
+    // Only one breaker rechecks and removes a dead pid; other waiters cannot race it.
+    if (!alive(pid)) removeOwnedLock(file, pid);
+  } finally {
+    fs.closeSync(fd);
+    try { fs.unlinkSync(breaker); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}
+
+function acquireLock(root, name) {
+  const file = path.join(root, '.ultra', '.runtime', `${name}.lock`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd;
+    try { fd = fs.openSync(file, 'wx'); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+    if (fd !== undefined) {
+      try { fs.writeFileSync(fd, String(process.pid)); }
+      finally { fs.closeSync(fd); }
+      return () => removeOwnedLock(file, process.pid);
+    }
+    try {
+      const pid = Number(fs.readFileSync(file, 'utf8'));
+      if (Number.isInteger(pid) && pid > 0 && !alive(pid)) breakDeadLock(file, pid);
+      else return null;
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return null;
+}
+
+function withLock(root, action) {
+  const deadline = Date.now() + 30000;
+  while (true) {
+    const release = acquireLock(root, 'engine');
+    if (release) {
+      try { return action(); } finally { release(); }
+    }
+    if (Date.now() >= deadline) {
+      throw new Error('.ultra/.runtime/engine.lock: lock wait exceeded 30 s; check its holder.');
+    }
+    // Sleep without polling the filesystem in a busy loop while the holder works.
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+  }
+}
+
+function append(root, name, record, locked = false) {
+  const write = () => {
+    const ledgers = new Map(LEDGERS.map((key) => [key, ledger(root, key)]));
+    const state = ledgers.get(name);
+    // Read and advance under the same lock so clock rollback cannot hide a new record.
+    const greatest = [...ledgers.values()].flatMap((s) => s.records)
+      .reduce((time, r) => Math.max(time, Date.parse(r.at)), -1);
+    record.at = new Date(Math.max(Date.now(), greatest + 1)).toISOString();
+    if (!validRecord(record, name)) {
+      throw new Error(`.ultra/ledger/${name}.jsonl: refusing to append a malformed ledger record.`);
+    }
+    const file = path.join(root, '.ultra', 'ledger', `${name}.jsonl`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (state.repairEnd !== null) fs.truncateSync(file, state.repairEnd);
+    const prefix = state.repairEnd === null && state.needsNewline ? '\n' : '';
+    fs.appendFileSync(file, `${prefix}${JSON.stringify(record)}\n`);
+  };
+  return locked ? write() : withLock(root, write);
+}
+
+module.exports = { ledger, latest, withLock, acquireLock, lockPid, append, approvalItem };

package/engine/loading.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+const { hash, read, requirements, registry } = require('./formats.cjs');
+const { codeState, projectRoot } = require('./git-state.cjs');
+const { ledger } = require('./ledger.cjs');
+
+function load(requested) {
+  const root = projectRoot(requested);
+  const code = codeState(root);
+  const { reqs, requirementText, shared } = requirements(read(root, 'spec.md'));
+  const validated = registry(root, 'checks.json', { checks: { covers: 'array', run: 'string' } });
+  const checks = validated.checks.map((check) => {
+    const timeout = check.timeout_sec === undefined ? 600 : check.timeout_sec;
+    return { ...check, timeout, fp: hash(JSON.stringify([check.run, timeout, check.expect])) };
+  });
+  const { milestones, nodes, cleanup_every } = registry(root, 'plan.json', {
+    milestones: { title: 'string', requirements: 'array' },
+    nodes: { milestone: 'string', title: 'string', covers: 'array', depends: 'array' },
+  });
+  const history = ['evidence', 'plan-log', 'nodes', 'milestones', 'approvals']
+    .map((name) => ledger(root, name));
+  return { root, ...code, reqs, requirementText, shared, checks, milestones, nodes, cleanup_every,
+    rulings: read(root, 'rulings.md', true), warnings: history.flatMap((h) => h.warnings),
+    evidence: history[0].records, plans: history[1].records,
+    completions: history[2].records, closures: history[3].records, approvals: history[4].records };
+}
+
+module.exports = { load };