testguard-cli 0.16.0 → 0.17.0

package/src/probe/runners/shared.mjs

@@ -1,4 +1,6 @@
 import { spawn, spawnSync } from 'node:child_process';
+import { registerChild, assertNotCancelled } from './lifecycle.mjs';
+import { readBoundedJsonFile } from './discovery.mjs';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
@@ -16,7 +18,7 @@ export const NODE_NOISE = /MODULE_TYPELESS_PACKAGE_JSON|ExperimentalWarning|--tr
 
 function descendantPids(rootPid) {
   if (process.platform === 'win32') return [];
-  const result = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8' });
+  const result = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8', timeout: 1000, maxBuffer: 4 * 1024 * 1024 });
   if (result.status !== 0) return [];
   const children = new Map();
   for (const line of result.stdout.split('\n')) {
@@ -43,7 +45,7 @@ export const TIMEOUT_CLEANUP_WARNING = 'cleanup-unverified: TestGuard hard-kille
 export function terminateProcessTree(child) {
   if (!child.pid) return;
   if (process.platform === 'win32') {
-    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', timeout: 1000 });
     try { child.kill('SIGKILL'); } catch {}
     return;
   }
@@ -147,11 +149,12 @@ export function checkRunner({ projectDir, pkg, bin, budgetMs = 60_000, env = pro
     } catch (e) {
       return resolve({ ok: false, message: e.message });
     }
+    registerChild(child, () => terminateProcessTree(child));
     let out = '';
     let err = '';
     child.on('error', () => resolve({ ok: false, message: `${pkg} is not installed in the project and \`${bin}\` is not on PATH (npm i -D ${pkg})` }));
-    child.stdout.on('data', (d) => (out += d));
-    child.stderr.on('data', (d) => (err += d));
+    child.stdout.on('data', (d) => (out = (out + d).slice(-65536)));
+    child.stderr.on('data', (d) => (err = (err + d).slice(-65536)));
     const timer = setTimeout(() => terminateProcessTree(child), budgetMs);
     child.on('close', (code) => {
       clearTimeout(timer);
@@ -239,6 +242,7 @@ export function parseReport(report, durationMs) {
  * override it.
  */
 export function runProcess({ projectDir, files, budgetMs = 120_000, command, commandTemplate, argv, env = {}, parse = parseReport }) {
+  assertNotCancelled();
   const outFile = join(tmpdir(), `testguard-run-${randomBytes(6).toString('hex')}.json`);
   const [cmd, ...args] = command
     ?? (commandTemplate ? expandCommand(commandTemplate, files, outFile) : argv(files, outFile));
@@ -248,11 +252,13 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
 
   return new Promise((resolve) => {
     const child = spawn(cmd, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: { ...process.env, CI: '1', FORCE_COLOR: '0', ...extraEnv } });
+    registerChild(child, () => terminateProcessTree(child));
+    child.stdout.resume(); // Reports are read from the file; drain logs to prevent pipe backpressure.
     let stderr = '';
     // Node prints MODULE_TYPELESS_PACKAGE_JSON (and friends) for the PROBED
     // project's config, not for anything the fault did. Keep it out of the
     // stream and out of `loadMessage`, which names the cause of a load error.
-    child.stderr.on('data', (d) => (stderr += String(d).split('\n').filter((l) => !NODE_NOISE.test(l)).join('\n')));
+    child.stderr.on('data', (d) => (stderr = (stderr + String(d).split('\n').filter((l) => !NODE_NOISE.test(l)).join('\n')).slice(-65536)));
     child.on('error', (e) => (stderr += e.message));
     let killed = false;
     const timer = setTimeout(() => {
@@ -270,7 +276,7 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
         result = { run: { outcome: 'error', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs }, timeouts: 0, loadMessage: stderr.trim().split('\n').filter(Boolean).slice(-1)[0] ?? 'runner produced no report', failedTests: [] };
       } else {
         try {
-          result = parse(JSON.parse(readFileSync(outFile, 'utf8')), durationMs);
+          result = parse(readBoundedJsonFile(outFile), durationMs);
         } catch (e) {
           result = { run: { outcome: 'error', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs }, timeouts: 0, loadMessage: `unreadable report: ${e.message}`, failedTests: [] };
         }

package/src/probe/runners/vitest.mjs

@@ -10,7 +10,7 @@ const DISCOVERY_CONFIG_FILES = [
   'vitest.workspace.json',
 ];
 /** Ask Vitest itself to load config and enumerate the files it would collect. */
-export const discoveryArgvFor = (projectDir) => [...runnerArgv(projectDir, 'vitest', 'vitest'), 'list', '--filesOnly', '--passWithNoTests'];
+export const discoveryArgvFor = (projectDir) => [...runnerArgv(projectDir, 'vitest', 'vitest'), 'list', '--filesOnly', '--passWithNoTests', '--maxWorkers=1'];
 
 export function parseDiscoveryOutput(stdout) {
   if (typeof stdout !== 'string') throw new TypeError('Vitest discovery output must be text');
@@ -27,8 +27,8 @@ export async function discoverTests({ projectDir, version, timeoutMs, maxOutputB
 }
 // --serial: one file at a time in one process, so a contended machine cannot turn a slow suite into a TIMEOUT verdict.
 /** The command line, as data. Exported so it is falsifiable without spawning anything. */
-export const argvFor = (projectDir, files, outFile, { serial = false } = {}) =>
-  [...runnerArgv(projectDir, 'vitest', 'vitest'), 'run', ...files, '--reporter=json', `--outputFile=${outFile}`, ...(serial ? ['--no-file-parallelism'] : [])];
+export const argvFor = (projectDir, files, outFile, { serial = false, workers = 1 } = {}) =>
+  [...runnerArgv(projectDir, 'vitest', 'vitest'), 'run', ...files, '--reporter=json', `--outputFile=${outFile}`, `--maxWorkers=${serial ? 1 : workers}`, ...(serial || workers === 1 ? ['--no-file-parallelism'] : [])];
 export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => argvFor(opts.projectDir, files, outFile, opts) });
 
 /**

package/src/probe/universe.mjs

@@ -0,0 +1,47 @@
+import { sha256 } from '../util/hash.mjs';
+import { selectRunner, discoverRunnerManifest, OWNED_RUNNERS } from './runners/index.mjs';
+import { createDiscoveryManifest, DiscoveryError } from './runners/discovery.mjs';
+
+/** The same adapter/configuration universe used by probing, never a file-glob guess. */
+export function hashNativeTestUniverse(manifests) {
+  const entries = [...manifests];
+  if (!entries.length) throw new DiscoveryError('a native test universe requires runner manifests');
+  if (!entries.some(([, manifest]) => manifest?.files?.length)) throw new DiscoveryError('a native test universe must contain test files');
+  const names = new Set();
+  const bound = entries.map(([runner, manifest]) => {
+    if (!runner?.name || names.has(runner.name) || !manifest?.runner) throw new DiscoveryError('native universe runner identities must be unique');
+    names.add(runner.name);
+    const canonical = createDiscoveryManifest({ runner: manifest.runner.name, version: manifest.runner.version, files: manifest.files, configFiles: manifest.configFiles, source: manifest.source });
+    if (canonical.testUniverseHash !== manifest.testUniverseHash || runner.name !== manifest.runner.name) throw new DiscoveryError('native universe manifest binding is inconsistent');
+    return { runner: runner.name, hash: manifest.testUniverseHash };
+  }).sort((a, b) => a.runner.localeCompare(b.runner));
+  return sha256(JSON.stringify(bound));
+}
+
+/** Shared owning-adapter collection; check failures retain existing probe semantics. */
+export async function collectOwnedManifests(runner, primaryManifest, { projectDir, sourceDir, python, budgetMs, budgetFor, assertOpen = () => {} }) {
+  const owned = OWNED_RUNNERS.filter((r) => r !== runner
+    && !(r.name === 'python' && ['python', 'pytest', 'unittest'].includes(runner.name)));
+  const ownedChecked = new Map();
+  const manifests = new Map(primaryManifest ? [[runner, primaryManifest]] : []);
+  for (const r of owned) {
+    const check = await r.check({ projectDir, sourceDir, python, budgetMs: budgetFor ? budgetFor() : budgetMs, budgetFor });
+    assertOpen();
+    ownedChecked.set(r, check);
+    if (!check.ok) continue;
+    manifests.set(r, await discoverRunnerManifest(r, check, projectDir, budgetFor ? budgetFor() : budgetMs));
+    assertOpen();
+  }
+  return { owned, ownedChecked, manifests };
+}
+
+/** Fresh current-project collection for an explicitly requested policy boundary. */
+export async function readNativeTestUniverse(options) {
+  const selected = await selectRunner({ ...options, name: options.runnerName ?? 'auto' });
+  options.assertOpen?.();
+  if (selected.error) throw new DiscoveryError(selected.error);
+  const collection = await collectOwnedManifests(selected.runner, selected.manifest, options);
+  const primaryRunner = { name: selected.engine ?? selected.runner.name, version: selected.version };
+  const runners = [primaryRunner, ...[...collection.ownedChecked].filter(([, check]) => check.ok).map(([runner, check]) => ({ name: check.engine ?? runner.name, version: check.version }))];
+  return { ...collection, primary: selected.runner, primaryRunner, runners, testUniverseHash: hashNativeTestUniverse(collection.manifests) };
+}

package/src/probe/worktree.mjs

@@ -1,3 +1,4 @@
+import { registerCleanup } from './runners/lifecycle.mjs';
 import { existsSync, mkdtempSync, readdirSync, symlinkSync, mkdirSync, statSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative, dirname } from 'node:path';
@@ -53,6 +54,7 @@ export function createScratch({ repoRoot, projectDir, ref = 'HEAD', scratchBase
     throw new PreconditionError(ref === 'HEAD' ? 'repository has no commits; commit first, or run with --in-place' : `ref ${ref} does not resolve to a commit`);
   }
   const dest = mkdtempSync(join(scratchBase, 'testguard-'));
+  const unregister = registerCleanup(() => removeWorktree(repoRoot, dest));
   addWorktree(repoRoot, dest, sha);
   const links = findNodeModules(repoRoot);
   if (nodeModules) {
@@ -71,7 +73,7 @@ export function createScratch({ repoRoot, projectDir, ref = 'HEAD', scratchBase
     sha,
     root: dest,
     projectDir: join(dest, relative(repoRoot, projectDir)),
-    cleanup: () => removeWorktree(repoRoot, dest),
+    cleanup: () => { removeWorktree(repoRoot, dest); unregister(); },
   };
 }
 

package/src/render.mjs

@@ -1,5 +1,15 @@
+import { recordedOriginSummary } from '../spec/lib/origins.mjs';
+
 const ORDER = ['survived', 'nocover', 'unverifiable', 'fault-invalid', 'timeout', 'flaky-defender', 'killed'];
 
+/** Informational declarations only; never a verdict or an eligibility gate. */
+export function renderOrigins(origins) {
+  const split = (counts) => Object.entries(counts).filter(([, n]) => n > 0).map(([kind, n]) => `${kind}: ${n}`).join(', ') || 'none';
+  return `origins (${origins.basis}): ${origins.claims.total} distinct claims (${split(origins.claims.byKind)}; mixed: ${origins.claims.mixed})` +
+    (origins.records ? `; ${origins.records.total} records (${split(origins.records.byKind)})` : '') +
+    ' — declared origins, not authenticated independence';
+}
+
 /** Non-passing verdicts shout; the one pass does not. */
 export const formatVerdict = (v, provisional = false) => (v === 'killed' ? 'killed' : v.toUpperCase()) + (provisional ? '?' : '');
 
@@ -37,7 +47,13 @@ export function renderSummary(records, run) {
   const kills = records.filter((r) => r.verdict === 'killed');
   const coAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
   const quality = coAuthored ? `\n${coAuthorshipWarning(coAuthored, kills.length)}` : '';
-  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}${quality}`;
+  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}${quality}\n${renderOrigins(recordedOriginSummary(records))}`;
+}
+
+/** Distinguish current admission, offline audit and recorded-run policy. */
+export function renderOriginPolicy(policy, { basis = 'recorded' } = {}) {
+  const label = basis === 'offline' ? 'current declarations; offline freshness unavailable' : basis === 'current' ? 'current inputs' : 'recorded run';
+  return `origin policy (${label}): ${policy.state}; eligible declarations: ${policy.eligibleKinds.join(', ')}; ${policy.claims} claims / ${policy.faults} faults; ${policy.ineligibleClaims.length} ineligible claims; ${policy.nonKilledFaults.length} non-killed faults${policy.unavailableReasons.length ? `; unavailable: ${policy.unavailableReasons.join(', ')}` : ''} — declared origins, not authenticated independence${basis === 'recorded' ? '; not current freshness' : ''}`;
 }
 
 /** Survivors first, then by rank score; killed last. */

package/src/replay/replay.mjs

@@ -1,3 +1,4 @@
+import { resetInterpreterCache } from '../probe/runners/python.mjs';
 import { existsSync, rmSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -84,6 +85,8 @@ export async function replay({
   confirmRuns = 3,
   budgetMs = 120_000,
   commandBudget,
+  workers = 1,
+  serial = workers === 1,
   runnerCommand,
   runnerName = 'auto',
   nodeModules,
@@ -93,6 +96,7 @@ export async function replay({
   onProgress = () => {},
   onStage = () => {},
 }) {
+  resetInterpreterCache();
   commandBudget?.assertOpen();
   projectDir = realpathSync(resolve(projectDir));
   const root = repoRoot(projectDir);
@@ -142,7 +146,7 @@ export async function replay({
         }
         universe = buildReplayRunnerUniverse(runnerUsed, manifests);
       }
-      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
+      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
       records.push(record);
       onProgress(record);
     } finally {
@@ -209,7 +213,7 @@ export function partitionReplayDefenders(files, primary, universe) {
   return groups;
 }
 
-async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, commandTemplate, runner, universe, onStage, index, total }) {
+async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner, universe, onStage, index, total }) {
   // git reports paths from the REPOSITORY root; the runner and every file
   // operation here work inside the scratch worktree, relative to the PROJECT
   // directory. Map once, and refuse anything that would land outside the
@@ -325,12 +329,12 @@ async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, co
       // A custom command is one explicit execution boundary. Preserve that
       // contract exactly; TestGuard cannot infer several native engines from
       // an opaque user command.
-      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate });
+      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate, workers, serial });
     } else {
       const parts = [];
       for (const [configuredRunner, files] of partitionReplayDefenders(related, runner, universe)) {
         commandBudget?.assertOpen();
-        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs }));
+        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, workers, serial }));
         commandBudget?.assertOpen();
       }
       res = mergeRuns(parts);

package/src/scaffold/admission.mjs

@@ -0,0 +1,117 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { sha256 } from '../util/hash.mjs';
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const MAX_FILES = 32;
+const SUPPORTED = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
+const PROTECTED = new Set(['evidence.json', 'evidence-partial.json', 'evidence-provisional.json', 'baseline.json', 'sweep-evidence.json']);
+
+function refuse(reason) { throw new Error(`draft append admission refused: ${reason}`); }
+function identity(stat) { return { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, mode: stat.mode }; }
+function same(stat, expected) { return Object.entries(expected).every(([key, value]) => stat[key] === value); }
+
+function selectedPath(requestedRoot, file) {
+  if (typeof file !== 'string' || !file || file.includes('\0') || file.includes('\\') || file.split('/').some((part) => part === '.' || part === '..')) refuse('unsafe-path');
+  const rel = relative(requestedRoot, resolve(requestedRoot, file));
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) refuse('outside-project');
+  return rel.split(sep).join('/');
+}
+
+/** Repeat the complete in-checkout path walk; never authorize by existence. */
+function inspect(root, file) {
+  const base = lstatSync(root);
+  if (base.isSymbolicLink() || !base.isDirectory()) refuse('unsafe-root');
+  const parts = file.split('/');
+  let path = root;
+  for (let i = 0; i < parts.length; i++) {
+    path = join(path, parts[i]);
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) refuse('symlink');
+    if (i < parts.length - 1) {
+      if (!stat.isDirectory()) refuse('not-directory');
+      try { lstatSync(join(path, 'testguard.claims.json')); refuse('nested-project'); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    } else {
+      if (!stat.isFile() || stat.nlink !== 1) refuse('not-single-regular-file');
+      if (stat.size > MAX_FILE_BYTES) refuse('file-byte-limit');
+      return { path, stat };
+    }
+  }
+}
+
+function readInput(root, file, admitted) {
+  if (constants.O_NOFOLLOW === undefined) refuse('nofollow-unavailable');
+  const fd = openSync(admitted.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const expected = identity(admitted.stat);
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || !same(before, expected)) refuse('input-changed');
+    const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = readSync(fd, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    if (length > MAX_FILE_BYTES) refuse('file-byte-limit');
+    if (length !== expected.size || !same(fstatSync(fd), expected)) refuse('input-changed');
+    const current = inspect(root, file);
+    if (!same(current.stat, expected)) refuse('input-changed');
+    const bytes = buffer.subarray(0, length);
+    let source;
+    try { source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+    catch { refuse('invalid-utf8'); }
+    if (source.includes('\0')) refuse('invalid-encoding');
+    return { file, path: admitted.path, source, hash: sha256(bytes), identity: expected };
+  } finally { closeSync(fd); }
+}
+
+/** Explicit text input only: no statements, claims, provenance promotion or writes. */
+export function admitIntentDocument({ projectDir, file }) {
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  const name = selectedPath(requestedRoot, file);
+  if (name.split('/').some(part => ['.local', '.wolf', '.git', '.testguard', 'graphify-out'].includes(part))) refuse('excluded-document');
+  if (!['.md', '.txt', '.rst', '.adoc'].includes(extname(name))) refuse('unsupported-document');
+  const input = readInput(root, name, inspect(root, name));
+  Object.freeze(input.identity);
+  return Object.freeze(input);
+}
+
+/** Selected conforming marker only; neither claim contents nor scope authority are returned. */
+export function admitIntentProject({ projectDir }) {
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  if (root.split(sep).some(part => ['.local', '.wolf', '.git', '.testguard', 'graphify-out'].includes(part))) refuse('excluded-project');
+  const file = 'testguard.claims.json';
+  const input = readInput(root, file, inspect(root, file));
+  readSpecDoc('claims', input.path, { source: input.source });
+  const marker = Object.freeze({ file, hash: input.hash, identity: Object.freeze(input.identity) });
+  return Object.freeze({ projectDir: root, marker });
+}
+
+/** Internal read-only input snapshot. This is not publication authority. */
+export function admitDraftAppend({ projectDir, draftPath, files, claimId }) {
+  if (!Array.isArray(files) || !files.length || files.length > MAX_FILES) refuse('source-count-limit');
+  if (typeof claimId !== 'string' || !claimId.trim() || claimId !== claimId.trim() || claimId.includes(',')) refuse('claim-selection');
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  const draftFile = selectedPath(requestedRoot, draftPath);
+  if (basename(draftFile) === 'testguard.claims.json' || (draftFile.startsWith('.testguard/') && PROTECTED.has(basename(draftFile)))) refuse('protected-destination');
+  const names = files.map((file) => selectedPath(requestedRoot, file));
+  if (new Set(names).size !== names.length || names.includes(draftFile)) refuse('input-alias');
+  if (names.some((file) => !SUPPORTED.has(extname(file)))) refuse('unsupported-source');
+  const draftInput = readInput(root, draftFile, inspect(root, draftFile));
+  const doc = readSpecDoc('claims', draftInput.path, { source: draftInput.source });
+  if (doc.claims.filter((claim) => claim.id === claimId).length !== 1) refuse('unknown-claim');
+  const admitted = names.sort().map((file) => ({ file, ...inspect(root, file) }));
+  if (admitted.reduce((total, input) => total + input.stat.size, 0) > MAX_SOURCE_BYTES) refuse('source-byte-limit');
+  const sources = admitted.map((input) => readInput(root, input.file, input));
+  return { projectDir: root, claimId, draft: { ...draftInput, doc }, sources };
+}

package/src/scaffold/append.mjs

@@ -0,0 +1,41 @@
+import { validate } from '../../spec/lib/validate.mjs';
+
+const injection = (fault) => (fault.method ?? 'fault-injection') === 'fault-injection';
+// A different explicit defender selection is a different measurement, even
+// when the injected bytes match. Absence and explicit [] must stay distinct.
+const anchorKey = (fault) => JSON.stringify([
+  fault.file, fault.faultClass, fault.find, fault.replace,
+  fault.expectHits ?? 1, fault.occurrence ?? 1,
+  Object.hasOwn(fault, 'defendedBy') ? [...fault.defendedBy].sort() : null,
+]);
+
+function conforming(label, doc) {
+  const result = validate('claims', doc);
+  if (!result.ok) throw new Error(`non-conforming ${label}: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+}
+
+/** Pure draft merge only. The future CLI owns all file admission/publication. */
+export function appendDraft({ draft, proposals, claimId }) {
+  conforming('draft', draft);
+  conforming('proposals', proposals);
+  if (typeof claimId !== 'string' || !claimId) throw new Error('append requires one existing claim ID');
+  const doc = structuredClone(draft);
+  const target = doc.claims.find((claim) => claim.id === claimId);
+  if (!target) throw new Error('append selection does not name an existing draft claim');
+  const candidates = proposals.claims.flatMap((claim) => claim.faults);
+  if (candidates.some((fault) => !injection(fault))) throw new Error('append proposals require fault-injection methods');
+  const seen = new Set(target.faults.filter(injection).map(anchorKey));
+  const used = new Set(target.faults.map((fault) => fault.id));
+  let next = 1;
+  for (const candidate of candidates) {
+    const key = anchorKey(candidate);
+    if (seen.has(key)) continue;
+    while (used.has(`S${next}`)) next++;
+    const id = `S${next++}`;
+    used.add(id);
+    target.faults.push({ ...structuredClone(candidate), id });
+    seen.add(key);
+  }
+  conforming('appended draft', doc);
+  return doc;
+}

package/src/scaffold/apply-append.mjs

@@ -0,0 +1,71 @@
+import { fstatSync, fsyncSync, ftruncateSync, readSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { persistRecovery } from '../claims/annotation-placement.mjs';
+import { readSpecDoc, writeSpecDoc } from '../evidence/writer.mjs';
+import { admitDraftAppend } from './admission.mjs';
+import { openDraftAppend } from './open-append.mjs';
+
+/** Explicit internal draft publication. Partial writes never auto-rollback. */
+export function applyDraftAppend({ request, plan }) {
+  let handle, stage = 'preparation';
+  const report = { ok: false, state: 'refused', writeAttempted: false, bytesWritten: 0, failed: [] };
+  const fail = (error) => {
+    report.ok = false; report.state = report.writeAttempted ? 'write-unconfirmed' : 'refused';
+    report.failed.push({ stage, reason: error.message });
+  };
+  try {
+    handle = openDraftAppend({ request, plan }); report.recoveryDir = handle.recoveryDir;
+    if (handle.plan.changed) {
+      stage = 'spec-publication';
+      writeSpecDoc('claims', handle.plan.draft.path, handle.plan.doc, { publish: (output) => {
+        if (output !== handle.plan.output) throw new Error('draft append serialized output changed');
+        stage = 'started-journal';
+        persistRecovery(join(handle.recoveryDir, 'started.json'), Buffer.from(JSON.stringify({ draft: handle.plan.draft.file, state: 'started' })));
+        stage = 'write-preflight'; handle.assertCurrent();
+        const bytes = Buffer.from(output, 'utf8');
+        stage = 'draft-write'; report.writeAttempted = true;
+        while (report.bytesWritten < bytes.length) {
+          const offset = report.bytesWritten;
+          const count = writeSync(handle.fd, bytes, offset, bytes.length - offset, offset);
+          if (!Number.isInteger(count) || count <= 0 || count > bytes.length - offset) throw new Error('draft write made no valid progress');
+          report.bytesWritten += count;
+        }
+        stage = 'truncate'; ftruncateSync(handle.fd, bytes.length);
+        stage = 'draft-fsync'; fsyncSync(handle.fd);
+        stage = 'verification'; handle.assertOwned();
+        const stat = fstatSync(handle.fd), identity = handle.plan.draft.identity;
+        if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== identity.dev || stat.ino !== identity.ino || stat.mode !== identity.mode || stat.size !== bytes.length) throw new Error('draft descriptor verification failed');
+        const buffer = Buffer.alloc(bytes.length + 1); let length = 0;
+        while (length < buffer.length) {
+          const count = readSync(handle.fd, buffer, length, buffer.length - length, length);
+          if (!count) break;
+          length += count;
+        }
+        if (length !== bytes.length || !buffer.subarray(0, length).equals(bytes)) throw new Error('draft byte verification failed');
+        readSpecDoc('claims', handle.plan.draft.path, { source: buffer.subarray(0, length).toString('utf8') });
+        const current = admitDraftAppend(request);
+        if (current.projectDir !== handle.plan.projectDir || current.draft.source !== output || current.draft.identity.dev !== identity.dev || current.draft.identity.ino !== identity.ino || current.draft.identity.mode !== identity.mode || !isDeepStrictEqual(current.sources, handle.plan.sources)) throw new Error('draft or sources changed after write');
+        handle.assertOwned();
+      } });
+      report.state = 'updated';
+    } else { handle.assertCurrent(); report.state = 'unchanged'; }
+    report.ok = true;
+  } catch (error) {
+    if (error.recoveryDir) report.recoveryDir = error.recoveryDir;
+    if (error.lockRelease) report.release = error.lockRelease;
+    fail(error);
+  } finally {
+    if (handle) {
+      report.release = handle.release();
+      if (!report.release.released) { stage = 'release'; fail(new Error(report.release.reason || 'resource release failed')); }
+    }
+  }
+  if (report.recoveryDir) {
+    stage = 'result-journal';
+    try { persistRecovery(join(report.recoveryDir, 'result.json'), Buffer.from(JSON.stringify(report))); }
+    catch (error) { fail(error); }
+  }
+  report.failed.forEach(Object.freeze); Object.freeze(report.failed);
+  return Object.freeze(report);
+}

package/src/scaffold/fix-input.mjs

@@ -0,0 +1,119 @@
+import { spawnSync } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { devNull } from 'node:os';
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { parseFixChangedPaths, parseFixProjectMarkers, validateFixProjectPrefix } from './fix-paths.mjs';
+import { admitIntentProject } from './admission.mjs';
+
+const OBJECT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const MAX_BYTES = 128 * 1024;
+function refuse(reason) { throw new Error(`fix input refused: ${reason}`); }
+
+function localFixContext({ projectDir, commit, budgetMs = 5000 }) {
+  if (typeof commit !== 'string' || !OBJECT_ID.test(commit)) refuse('full-object-id-required');
+  if (!Number.isSafeInteger(budgetMs) || budgetMs < 1 || budgetMs > 5000) refuse('invalid-budget');
+  const started = performance.now();
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  const identity = lstatSync(root);
+  if (!identity.isDirectory()) refuse('unsafe-root');
+  const checkRoot = () => {
+    const current = lstatSync(requestedRoot);
+    if (current.isSymbolicLink() || !current.isDirectory() || current.dev !== identity.dev || current.ino !== identity.ino || realpathSync(requestedRoot) !== root) refuse('root-changed');
+  };
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+  Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: devNull, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', GIT_PAGER: 'cat', LC_ALL: 'C' });
+  let captured = 0;
+  const read = args => {
+    checkRoot();
+    const remaining = Math.floor(budgetMs - (performance.now() - started));
+    if (remaining < 1) refuse('deadline');
+    const run = spawnSync('git', ['--no-lazy-fetch', '--no-replace-objects', '-c', 'core.fsmonitor=false', '-c', `core.hooksPath=${devNull}`, ...args], {
+      cwd: root, env, shell: false, timeout: remaining, maxBuffer: MAX_BYTES,
+    });
+    if (run.error || run.signal || run.status !== 0 || performance.now() - started >= budgetMs) refuse('object-read-unavailable');
+    if (!Buffer.isBuffer(run.stdout) || run.stdout.length > MAX_BYTES) refuse('object-byte-limit');
+    captured += run.stdout.length;
+    if (captured > 512 * 1024) refuse('aggregate-byte-limit');
+    checkRoot();
+    return run.stdout;
+  };
+  const finish = () => {
+    checkRoot();
+    if (budgetMs <= performance.now() - started) refuse('deadline');
+  };
+  return { root, read, finish };
+}
+
+function commitMetadata(context, commit) {
+  const bytes = context.read(['cat-file', 'commit', commit]);
+  const hash = createHash(commit.length === 40 ? 'sha1' : 'sha256').update(`commit ${bytes.length}\0`).update(bytes).digest('hex');
+  if (hash !== commit) refuse('object-identity-mismatch');
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+  catch { refuse('invalid-utf8'); }
+  if (text.includes('\0')) refuse('invalid-encoding');
+  const separator = text.indexOf('\n\n');
+  if (separator < 0) refuse('malformed-commit');
+  const parents = text.slice(0, separator).split('\n').filter(line => line.startsWith('parent ')).map(line => line.slice(7));
+  if (parents.length !== 1 || !OBJECT_ID.test(parents[0]) || parents[0].length !== commit.length) refuse('single-parent-required');
+  const subject = text.slice(separator + 2).split('\n', 1)[0];
+  if (Buffer.byteLength(subject) > 1024 || /[\x00-\x1f\x7f-\x9f]/.test(subject)) refuse('unsafe-subject');
+  return Object.freeze({ commit, parent: parents[0], subject });
+}
+
+/** Local immutable metadata, not a bug claim or an authenticated intent source. */
+export function readFixCommitMetadata(options) {
+  const context = localFixContext(options);
+  const metadata = commitMetadata(context, options.commit);
+  context.finish();
+  return metadata;
+}
+
+/** Complete bounded historical diff for an exact worktree root, not current source authority. */
+export function readFixCommitInventory(options) { return fixInventory(options, false); }
+
+/** Explicit selected nested project; historical inventory is not current source authority. */
+export function readNestedFixCommitInventory(options) { return fixInventory(options, true); }
+
+/** Observe root/nested selection once, under one unchanged offline Git context. */
+export function readScopedFixCommitInventory(options) { return fixInventory(options, 'selected'); }
+
+function fixInventory(options, mode) {
+  const context = localFixContext(options);
+  let toplevel;
+  try { toplevel = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true }).decode(context.read(['rev-parse', '--show-toplevel'])); }
+  catch (error) { if (error instanceof TypeError) refuse('invalid-root-encoding'); throw error; }
+  const scoped = mode === 'selected';
+  const nested = scoped ? toplevel.endsWith('\n') && toplevel.slice(0, -1) !== context.root : mode;
+  let projectPrefix = '', selected;
+  if (!nested) {
+    if (!toplevel.endsWith('\n') || toplevel.slice(0, -1) !== context.root) refuse('project-root-required');
+  } else {
+    if (!toplevel.endsWith('\n')) refuse('project-root-required');
+    const repositoryRoot = realpathSync(toplevel.slice(0, -1));
+    const prefix = relative(repositoryRoot, context.root);
+    if (!prefix) refuse('nested-project-required');
+    if (isAbsolute(prefix) || prefix === '..' || prefix.startsWith(`..${sep}`)) refuse('outside-project');
+    projectPrefix = validateFixProjectPrefix(prefix.split(sep).join('/'));
+    selected = admitIntentProject({ projectDir: context.root });
+  }
+  const metadata = commitMetadata(context, options.commit);
+  const tree = id => context.read(['ls-tree', '-r', '--name-only', '-z', '--full-tree', id]);
+  const projects = parseFixProjectMarkers(tree(metadata.parent), tree(metadata.commit), { projectPrefix });
+  const args = ['diff-tree', '--raw', '--no-abbrev', '-z', '--no-renames', '--no-ext-diff', '--no-textconv', '-r', '--no-commit-id', metadata.parent, metadata.commit, '--'];
+  if (projectPrefix) args.push(`:(top,literal)${projectPrefix}/`);
+  const raw = context.read(args);
+  const inventory = parseFixChangedPaths(raw, { nestedProjects: projects, objectIdWidth: metadata.commit.length, projectPrefix });
+  if (selected) {
+    const current = admitIntentProject({ projectDir: context.root });
+    if (current.projectDir !== selected.projectDir || current.marker.hash !== selected.marker.hash ||
+      Object.entries(selected.marker.identity).some(([key, value]) => current.marker.identity[key] !== value)) refuse('project-marker-changed');
+  }
+  context.finish();
+  if (scoped) return Object.freeze({ scope: projectPrefix ? 'selected-nested-project' : 'project-root', ...metadata, ...inventory });
+  return Object.freeze({ ...metadata, ...inventory });
+}