harness-everything 0.36.2 → 0.36.4

package/ci/prep/doc-reconciliation-red.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+'use strict';
+
+// #325 Phase 3b preparation: strict and expected-RED replay over the real CLI, hook and Stop entry points.
+//
+//   node ci/prep/doc-reconciliation-red.js --strict      exits 1 on any desired-contract gap or control failure
+//   node ci/prep/doc-reconciliation-red.js --expect-red  exits 0 only when every gap is qualified by the registry
+//   node ci/prep/doc-reconciliation-red.js --recapture-candidate <file> --baseline-sha <40-hex>
+//                                                        writes a candidate registry for review; never the registry
+//
+// Optional: --case <id> (repeatable), --cases <file>, --registry <file>, --json (print the report), --log <file>.
+// Exit 2 means infrastructure or registry error (replay crash, malformed registry, unreadable file, a spawn error,
+// a signal, an exit outside the action's expectExit policy, or missing required output).
+//
+// This file is not discovered by filename. The preparation suite invokes --expect-red and parses the report.
+// A qualified gap is an ON assertion that fails today and matches a registry entry exactly (case, assertion,
+// distribution, actual and desired). Infrastructure faults are decided first and never qualify as gaps.
+// Qualification is bound to the runtime fingerprint of the shared runtime files, not to the commit: a registry
+// entry is valid only while those files are byte-identical to the capture.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const fx = require('../lib/doc-reconciliation-prep-fixtures');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PREP_DIR = path.join(ROOT, 'ci', 'fixtures', 'doc-obligations', 'reconciliation-prep');
+const DEFAULT_CASES = path.join(PREP_DIR, 'cases.json');
+const DEFAULT_REGISTRY = path.join(PREP_DIR, 'pending-red.json');
+const LEGS = ['source', 'packaged'];
+const MODES = ['off', 'on'];
+const BLOCKER = '#341 E0';
+const ENTRY_KEYS = ['caseId', 'assertionId', 'distribution', 'baselineSha', 'actual', 'desired', 'blocker', 'reasonCode'];
+// Shared runtime files whose bytes define what the registry describes. Every P01-P08 replay loads the first
+// three (verified by a preload probe, see h3.md). doc-evidence.js is not loaded by any replay, so it is excluded:
+// #341 0B refactors it, and including it would turn this suite red for an unrelated reason.
+const FINGERPRINT_FILES = [
+  'hooks/scripts/lib/workflow-obligations.js',
+  'hooks/scripts/workflow-disposition.js',
+  'hooks/scripts/workflow-stop-gate.js'
+];
+const CANDIDATE_FILE = 'ci/fixtures/doc-obligations/reconciliation-prep/pending-red.candidate.json';
+const UNREVIEWED_REASON = 'needs-reason';
+
+class RegistryError extends Error {}
+
+function fingerprint() {
+  const hash = crypto.createHash('sha256');
+  for (const rel of FINGERPRINT_FILES) {
+    hash.update(`${rel}\0`);
+    hash.update(fs.readFileSync(path.join(ROOT, rel)));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+// Read-only: the commit named in the re-capture command. Falls back to a visible placeholder.
+function currentCommit() {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: ROOT, encoding: 'utf8' });
+  return result.status === 0 && /^[0-9a-f]{40}$/.test(result.stdout.trim()) ? result.stdout.trim() : '<commit>';
+}
+
+function recaptureCommand(commit) {
+  return `node ci/prep/doc-reconciliation-red.js --recapture-candidate ${CANDIDATE_FILE} --baseline-sha ${commit}`;
+}
+
+function parseArgs(argv) {
+  const args = {
+    mode: null, cases: [], casesFile: DEFAULT_CASES, registryFile: DEFAULT_REGISTRY,
+    json: false, log: null, candidateFile: null, baselineSha: null
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = argv[i];
+    if (item === '--strict' || item === '--expect-red') args.mode = item.slice(2);
+    else if (item === '--json') args.json = true;
+    else if (item === '--case') args.cases.push(argv[++i]);
+    else if (item === '--cases') args.casesFile = argv[++i];
+    else if (item === '--registry') args.registryFile = argv[++i];
+    else if (item === '--log') args.log = argv[++i];
+    else if (item === '--recapture-candidate') { args.mode = 'recapture'; args.candidateFile = argv[++i]; }
+    else if (item === '--baseline-sha') args.baselineSha = argv[++i];
+    else throw new RegistryError(`unknown argument ${item}`);
+  }
+  if (!args.mode) throw new RegistryError('choose --strict, --expect-red, or --recapture-candidate <file>');
+  if (args.mode === 'recapture') {
+    if (!/^[0-9a-f]{40}$/.test(args.baselineSha || '')) throw new RegistryError('--recapture-candidate needs --baseline-sha <40-hex commit>');
+    if (!args.candidateFile) throw new RegistryError('--recapture-candidate needs a file path');
+  }
+  for (const value of [args.casesFile, args.registryFile]) {
+    if (value === undefined) throw new RegistryError('a file argument is missing its value');
+  }
+  return args;
+}
+
+// Structural validation of the registry against the corpus. Any violation is a registry error (exit 2).
+function validateRegistry(registry, corpus) {
+  if (!registry || typeof registry !== 'object') throw new RegistryError('registry must be a JSON object');
+  if (registry.schemaVersion !== 1) throw new RegistryError('registry schemaVersion must be 1');
+  if (!/^[0-9a-f]{40}$/.test(registry.baselineSha || '')) throw new RegistryError('registry baselineSha must be a 40-hex commit');
+  if (!/^[0-9a-f]{64}$/.test(registry.runtimeFingerprint || '')) throw new RegistryError('registry runtimeFingerprint must be a sha256');
+  if (!Array.isArray(registry.entries)) throw new RegistryError('registry entries must be an array');
+  const cases = new Map(corpus.cases.map(item => [item.id, item]));
+  const seen = new Set();
+  for (const [index, entry] of registry.entries.entries()) {
+    const where = `entries[${index}]`;
+    if (!entry || typeof entry !== 'object') throw new RegistryError(`${where} must be an object`);
+    const keys = Object.keys(entry).sort();
+    if (JSON.stringify(keys) !== JSON.stringify([...ENTRY_KEYS].sort())) {
+      throw new RegistryError(`${where} must have exactly the keys ${ENTRY_KEYS.join(', ')}`);
+    }
+    const item = cases.get(entry.caseId);
+    if (!item) throw new RegistryError(`${where} names unknown case ${entry.caseId}`);
+    const onId = String(entry.assertionId || '').startsWith(`${entry.caseId}.on.`)
+      ? entry.assertionId.slice(`${entry.caseId}.on.`.length)
+      : null;
+    if (!onId || !item.expectations.on.some(assertion => assertion.id === onId)) {
+      throw new RegistryError(`${where} names ${entry.assertionId}, which is not an ON assertion of ${entry.caseId}`);
+    }
+    if (!LEGS.includes(entry.distribution)) throw new RegistryError(`${where} distribution must be source or packaged`);
+    if (entry.baselineSha !== registry.baselineSha) throw new RegistryError(`${where} baselineSha differs from the registry capture`);
+    if (entry.blocker !== BLOCKER) throw new RegistryError(`${where} blocker must be ${BLOCKER}`);
+    if (typeof entry.reasonCode !== 'string' || !entry.reasonCode.trim()) throw new RegistryError(`${where} reasonCode must be non-empty`);
+    if (entry.reasonCode === UNREVIEWED_REASON) throw new RegistryError(`${where} reasonCode is ${UNREVIEWED_REASON}; a reviewer must replace it`);
+    if (entry.actual === undefined || entry.desired === undefined) throw new RegistryError(`${where} needs actual and desired values`);
+    const identity = `${entry.caseId}|${entry.assertionId}|${entry.distribution}`;
+    if (seen.has(identity)) throw new RegistryError(`${where} duplicates ${identity}`);
+    seen.add(identity);
+  }
+}
+
+const sameJson = (left, right) => JSON.stringify(fx.normalize(left)) === JSON.stringify(fx.normalize(right));
+
+function comparable(root) {
+  return Object.fromEntries(Object.entries(root.actions).map(([id, action]) => [id, {
+    exitCode: action.exitCode,
+    signal: action.signal,
+    stdout: action.json === null ? action.stdout : null,
+    json: fx.normalize(action.json),
+    stderr: action.stderr,
+    state: fx.normalize(action.state)
+  }]).concat([['$final', fx.normalize(root.state)]]));
+}
+
+// Classifies one case. `replays` holds the scrubbed roots: off/on for each leg.
+function classifyCase(item, replays, registryEntries) {
+  // Infrastructure first: a faulted replay can never qualify as a gap, and parity is not meaningful for it. A replay
+  // that fail-fast did not run is absent from `replays`, so only the replays that ran are judged.
+  const found = [];
+  let actionsRun = 0;
+  for (const mode of MODES) {
+    for (const leg of LEGS) {
+      const root = replays[mode][leg];
+      if (!root) continue;
+      actionsRun += Object.keys(root.actions).length;
+      for (const { actionId, message } of fx.infrastructureFaults(item, root, mode)) {
+        found.push({ leg, mode, actionId, message, text: `${leg}.${mode}.${actionId}: ${message}` });
+      }
+    }
+  }
+  if (found.length) {
+    const first = found[0];
+    return {
+      caseId: item.id,
+      status: 'INFRASTRUCTURE',
+      qualifiedGaps: 0,
+      parity: 'not-evaluated',
+      reason: first.text,
+      offending: { leg: first.leg, mode: first.mode, actionId: first.actionId, fault: first.message },
+      infrastructure: found.map(entry => entry.text),
+      actionsRun,
+      assertions: []
+    };
+  }
+  const assertions = [];
+  let failed = false;
+  let qualifiedGaps = 0;
+  for (const leg of LEGS) {
+    for (const mode of ['off', 'on']) {
+      const root = replays[mode][leg];
+      for (const result of fx.evaluateAll(root, item.expectations[mode])) {
+        const assertionId = `${item.id}.${mode}.${result.id}`;
+        if (mode === 'off') {
+          if (!result.pass) failed = true;
+          assertions.push({ leg, mode, id: assertionId, status: result.pass ? 'pass' : 'control-fail', actual: result.actual });
+          continue;
+        }
+        const entry = registryEntries.find(candidate => candidate.assertionId === assertionId && candidate.distribution === leg);
+        if (result.pass) {
+          if (entry) { failed = true; assertions.push({ leg, mode, id: assertionId, status: 'unexpected-pass', actual: result.actual }); }
+          else assertions.push({ leg, mode, id: assertionId, status: 'pass', actual: result.actual });
+          continue;
+        }
+        if (!entry) {
+          failed = true;
+          assertions.push({ leg, mode, id: assertionId, status: 'gap-unqualified', actual: result.actual, desired: result.expected });
+        } else if (sameJson(entry.actual, result.actual) && sameJson(entry.desired, result.expected)) {
+          qualifiedGaps += 1;
+          assertions.push({ leg, mode, id: assertionId, status: 'gap-qualified', actual: result.actual, desired: result.expected });
+        } else {
+          failed = true;
+          assertions.push({ leg, mode, id: assertionId, status: 'gap-mismatch', actual: result.actual, desired: result.expected, registered: entry.actual });
+        }
+      }
+    }
+  }
+  // Parity: the two legs must agree on every normalized replay of this case.
+  let parity = 'match';
+  for (const mode of ['off', 'on']) {
+    if (!sameJson(comparable(replays[mode].source), comparable(replays[mode].packaged))) {
+      parity = 'mismatch';
+      failed = true;
+    }
+  }
+  const status = failed ? 'FAIL' : qualifiedGaps > 0 ? 'EXPECTED_RED' : 'CONTROL_PASS';
+  return { caseId: item.id, status, qualifiedGaps, parity, assertions };
+}
+
+// Both legs, both modes, for one case. Fresh replays every time; nothing is reused between cases or legs. The first
+// replay with an infrastructure fault ends the case: the replays after it are not run and are absent from the result.
+function replayAll(item) {
+  const replays = { off: {}, on: {} };
+  for (const mode of MODES) {
+    for (const leg of LEGS) {
+      replays[mode][leg] = fx.scrubReplay(fx.replayCase(item, leg, mode === 'on' ? { pilot: '1' } : undefined));
+      if (fx.infrastructureFaults(item, replays[mode][leg], mode).length) return replays;
+    }
+  }
+  return replays;
+}
+
+function countReplays(replays) {
+  return MODES.reduce((total, mode) => total + Object.keys(replays[mode]).length, 0);
+}
+
+// A case the corpus-level fail-fast did not reach. It is named, so the report never looks complete.
+function notRun(item, infrastructureCaseId) {
+  return {
+    caseId: item.id,
+    status: 'NOT_RUN',
+    qualifiedGaps: 0,
+    parity: 'not-evaluated',
+    reason: `not run: ${infrastructureCaseId} is INFRASTRUCTURE`,
+    assertions: []
+  };
+}
+
+// The one exit-code rule. Infrastructure (replay faults, policy and output violations) is 2, ahead of RED results.
+function exitCodeFor(report, mode) {
+  if (report.cases.some(item => item.status === 'INFRASTRUCTURE')) return 2;
+  const failed = report.cases.some(item => item.status === 'FAIL');
+  const gaps = report.cases.some(item => item.assertions.some(entry => entry.status.startsWith('gap')));
+  if (mode === 'strict') return failed || gaps ? 1 : 0;
+  return failed ? 1 : 0;
+}
+
+function loadRegistry(file) {
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new RegistryError(`registry unreadable: ${error.message.split('\n')[0]}`);
+  }
+  return registry;
+}
+
+function run(args) {
+  const corpus = fx.readCaseCorpus(args.casesFile);
+  const registry = loadRegistry(args.registryFile);
+  validateRegistry(registry, corpus);
+  const runtime = fingerprint();
+  const cases = corpus.cases.filter(item => args.cases.length === 0 || args.cases.includes(item.id));
+  if (args.cases.length && cases.length !== args.cases.length) throw new RegistryError('a --case names no corpus case');
+  const report = {
+    schemaVersion: 1,
+    mode: args.mode,
+    baselineSha: registry.baselineSha,
+    runtimeFingerprintMatches: registry.runtimeFingerprint === runtime,
+    pilotCredit: false,
+    replaysRun: 0,
+    cases: []
+  };
+  for (const [index, item] of cases.entries()) {
+    const replays = replayAll(item);
+    report.replaysRun += countReplays(replays);
+    const result = classifyCase(item, replays, registry.entries.filter(entry => entry.caseId === item.id));
+    if (registry.runtimeFingerprint !== runtime && result.status !== 'INFRASTRUCTURE') {
+      result.status = 'FAIL';
+      result.reason = 'runtime fingerprint differs from the registry capture';
+    }
+    report.cases.push(result);
+    if (result.status === 'INFRASTRUCTURE') {
+      // Fail fast across the corpus: once a case is infrastructure, the remaining cases are not replayed.
+      for (const skipped of cases.slice(index + 1)) report.cases.push(notRun(skipped, item.id));
+      break;
+    }
+  }
+  if (!report.runtimeFingerprintMatches) report.recaptureCommand = recaptureCommand(currentCommit());
+  return report;
+}
+
+// Candidate registry from the observed gaps on the current runtime. The committed registry is never written.
+// Reason codes carry over by identity; a gap that is new to the registry gets the unreviewed marker.
+function recapture(args) {
+  const corpus = fx.readCaseCorpus(args.casesFile);
+  const existing = fs.existsSync(args.registryFile) ? loadRegistry(args.registryFile).entries || [] : [];
+  const known = new Map(existing.map(entry => [`${entry.assertionId}|${entry.distribution}`, entry.reasonCode]));
+  const entries = [];
+  const problems = [];
+  const cases = corpus.cases.filter(item => args.cases.length === 0 || args.cases.includes(item.id));
+  for (const item of cases) {
+    const result = classifyCase(item, replayAll(item), []);
+    if (result.status === 'INFRASTRUCTURE') {
+      // Refuse, and stop: no candidate is written once a replay is infrastructure, so later cases are not replayed.
+      problems.push(`${item.id} infrastructure: ${result.reason}`);
+      break;
+    }
+    for (const assertion of result.assertions) {
+      if (assertion.status === 'control-fail') problems.push(`${item.id} control fails: ${assertion.id}`);
+      if (assertion.status === 'gap-unqualified') {
+        entries.push({
+          caseId: item.id,
+          assertionId: assertion.id,
+          distribution: assertion.leg,
+          baselineSha: args.baselineSha,
+          actual: assertion.actual,
+          desired: assertion.desired,
+          blocker: BLOCKER,
+          reasonCode: known.get(`${assertion.id}|${assertion.leg}`) || UNREVIEWED_REASON
+        });
+      }
+    }
+    if (result.parity === 'mismatch') problems.push(`${item.id} source and packaged legs disagree`);
+  }
+  if (problems.length) return { ok: false, problems };
+  return {
+    ok: true,
+    candidate: { schemaVersion: 1, phase: '325-3b-H2', baselineSha: args.baselineSha, runtimeFingerprint: fingerprint(), entries }
+  };
+}
+
+function summarize(report) {
+  const lines = report.cases.map(item => {
+    const gaps = item.assertions.filter(entry => entry.status.startsWith('gap')).length;
+    const reason = item.reason ? ` (${item.reason})` : '';
+    return `${item.caseId.padEnd(30)} ${item.status.padEnd(13)} gaps=${gaps} parity=${item.parity}${reason}`;
+  });
+  return lines.join('\n');
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[doc-reconciliation-red] ${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (args.mode === 'recapture') {
+    let outcome;
+    try {
+      outcome = recapture(args);
+    } catch (error) {
+      console.error(`[doc-reconciliation-red] infrastructure: ${error.message.split('\n')[0]}`);
+      process.exitCode = 2;
+      return;
+    }
+    if (!outcome.ok) {
+      console.error(`[doc-reconciliation-red] candidate not written:\n  ${outcome.problems.join('\n  ')}`);
+      process.exitCode = 1;
+      return;
+    }
+    const target = path.resolve(ROOT, args.candidateFile);
+    fs.writeFileSync(target, `${JSON.stringify(outcome.candidate, null, 2)}\n`, 'utf8');
+    const unreviewed = outcome.candidate.entries.filter(entry => entry.reasonCode === UNREVIEWED_REASON).length;
+    console.log(`candidate written: ${args.candidateFile} (${outcome.candidate.entries.length} entries, ${unreviewed} unreviewed)`);
+    console.log('review it against pending-red.json; replace the committed registry only after review, then delete the candidate.');
+    process.exitCode = 0;
+    return;
+  }
+  let report;
+  try {
+    report = run(args);
+  } catch (error) {
+    console.error(`[doc-reconciliation-red] infrastructure: ${error.message.split('\n')[0]}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (args.log) fs.writeFileSync(args.log, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else console.log(summarize(report));
+  if (report.recaptureCommand) {
+    console.error(`[doc-reconciliation-red] runtime fingerprint changed since the registry capture. Re-capture deliberately; nothing is auto-accepted:\n` +
+      `  1. ${report.recaptureCommand}\n` +
+      `  2. review ${CANDIDATE_FILE} against ci/fixtures/doc-obligations/reconciliation-prep/pending-red.json (entries, reasonCode, actual, desired)\n` +
+      '  3. replace pending-red.json with the reviewed candidate and delete the candidate file');
+  }
+  process.exitCode = exitCodeFor(report, args.mode);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  fingerprint, validateRegistry, classifyCase, replayAll, run, recapture, exitCodeFor, parseArgs, recaptureCommand,
+  RegistryError, FINGERPRINT_FILES, CANDIDATE_FILE
+};

package/ci/stress-341-boundary-control.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+'use strict';
+
+// Local/on-demand stress lane: four real C00 controls plus four bounded CPU workers.
+// Kept on-demand rather than in every gate: CPU saturation multiplies CI load.
+// The preload makes an unrelated sensitivity child unavailable deterministically;
+// selecting N01d must not run that child, even when the selected assertion passed.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+if (process.argv.includes('--worker')) {
+  const { runChecks } = require('./mutation-check');
+  const [result] = runChecks({ root: ROOT, timeoutMs: 60000, legacyAssertions: {}, checks: [{
+    label: 'parallel selected boundary control', target: 'ci/lib/doc-evidence-boundary-check.js',
+    mutantId: 'C00-noop-boundary', test: 'ci/mechanism-341-boundary-enforcement.test.js',
+    caseId: 'C1-N01d-canonical',
+    assertionId: 'C1-N01d-canonical.boundary.intended-code-CONTEXT_ALIAS_OR_COMPUTED_USE',
+  }] });
+  console.log(JSON.stringify(result));
+  assert.equal(result.verdict, 'SURVIVED', result.reason);
+} else {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-341-control-stress-'));
+  const preload = path.join(temp, 'sensitivity-pressure.cjs');
+  fs.writeFileSync(preload, `
+const cp = require('node:child_process');
+const original = cp.spawnSync;
+cp.spawnSync = function (exe, args, options) {
+  if (args && args.includes('--c1-isolation-child') && typeof options?.input === 'string') {
+    console.error('stress: pipe-fed isolation child reached');
+    return original(exe, ['-e', 'setTimeout(() => {}, 10000)'], { ...options, timeout: 25 });
+  }
+  if (args && /doc-evidence-boundary-check-baseline\\.js$/.test(args[0] || '')) {
+    // Simulate a starved, UNSELECTED child at the actual subprocess boundary.
+    console.error('stress: unselected sensitivity baseline reached');
+    return original(exe, ['-e', 'setTimeout(() => {}, 10000)'], { ...options, timeout: 25 });
+  }
+  return original(exe, args, options);
+};
+`);
+  const children = new Set();
+  const timer = setTimeout(() => {
+    for (const child of children) child.kill('SIGKILL');
+  }, 150000);
+  const env = { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --require=${JSON.stringify(preload)}`.trim() };
+  const run = args => new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { cwd: ROOT, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    children.add(child);
+    let output = '';
+    child.stdout.on('data', chunk => { output += chunk; });
+    child.stderr.on('data', chunk => { output += chunk; });
+    child.on('error', reject);
+    child.on('close', (status, signal) => {
+      children.delete(child);
+      process.stdout.write(output);
+      resolve({ status, signal });
+    });
+  });
+  const burners = [];
+  for (let i = 0; i < 4; i++) {
+    const child = spawn(process.execPath, ['-e', 'const end = Date.now() + 140000; while (Date.now() < end) {}'], {
+      stdio: 'ignore',
+    });
+    burners.push(child);
+    children.add(child);
+    child.on('error', () => {});
+    child.on('close', () => children.delete(child));
+  }
+  Promise.all(Array.from({ length: 4 }, () => run([__filename, '--worker'])))
+    .then(results => {
+      assert.ok(results.every(result => result.status === 0 && !result.signal),
+        `parallel C00 controls must survive: ${JSON.stringify(results)}`);
+      console.log('PASS four parallel C00 controls under CPU load and input/selection isolation');
+    })
+    .catch(error => { console.error(error.message); process.exitCode = 1; })
+    .finally(() => {
+      clearTimeout(timer);
+      for (const child of children) child.kill('SIGKILL');
+      fs.rmSync(temp, { recursive: true, force: true });
+    });
+}

package/docs/doc-evidence-baseline-binding.md

@@ -5,6 +5,90 @@ the phase 3a `doc-change` / `requirement-sync` producer in
 [`document-lifecycle.md`](document-lifecycle.md). It does not reconcile evidence with workflow
 disposition (#325 phase 3b/3c), add a lock, or add a router/provider path.
 
+## Phase 0 read-boundary contract (#341)
+
+Phase 0 preserves the public `checkDocObligations()` result and the current reads. A read role
+captures facts at most once **per its existing role-specific identity and scope**; consumers of
+that same role (validation, binding, stale diagnostics, and audit where applicable) reuse the
+capture. Consumers are not roles, so separating consumers does not permit another caller-object
+read. Detached immutable internal views are a Phase 0B implementation requirement; they must not
+be obtained by freezing or retaining mutable caller-owned objects. An internally consistent
+snapshot proves agreement with the supplied values, not their external truth or provenance.
+
+The private `ReadResult<T>` contract for the later capture layer distinguishes:
+
+```ts
+type ReadResult<T> =
+  | { kind: 'present'; value: T }
+  | { kind: 'absent' }
+  | { kind: 'inherited' }
+  | { kind: 'unknown'; reason: string };
+```
+
+`present` includes an own property whose value is `undefined`; field validation decides whether
+that value is valid, and it must not be collapsed into `absent`. `absent` means no own key exists.
+`inherited` records that a value is reachable only through the prototype chain and cannot satisfy
+an own-key evidence requirement. `unknown` covers throwing or otherwise uninspectable input. An
+unknown read is not a completed obligation and cannot produce a pass; mandatory baseline evidence
+that is invalid or unknown fails closed with a structured diagnostic. This representation does
+not change existing field policy or the public output schema.
+
+The read roles and compatibility traces are fixed to their existing identities:
+
+| ID | Identity and read rule | Consumers / compatibility behavior |
+| --- | --- | --- |
+| R1 — whole-baseline digest | Invocation. Read once before the obligation loop only if `baseline` passes the plain-object check; otherwise zero reads. | Reused across obligations. This does not claim that the caller's baseline is externally attested. |
+| R2 — candidate-inventory classification | Invocation, lazy. At most one prototype inspection, only when an applicable baseline-declaring obligation needs it. | The same classification is shared across obligations as today. Inapplicable and non-baseline lanes do not trigger it. |
+| R3 — rename-destination validation | Obligation × declaring entry. One own-digest read for each declaring entry that reaches it; accepted entries must agree. | A rejected destination is poisoned: never reread, later declarations fail closed, and the failed snapshot takes precedence in audit over an earlier success. Distinct declaring entries remain separate observations. |
+| R4 — baseline-entry metadata and source own-key absence | Obligation × entry. Capture `path`, `reason`, own `renameTo` presence/value, and source absence once for reuse. | The tested candidate descriptor budget combines R3 and R4: two inspections for a rename (destination presence and source absence), one for a deletion. |
+| R5 — per-path baseline digest | Obligation × path. Capture once during metadata validation. | Audit mirror, stale diagnostics, and baseline binding reuse that validated value. |
+| R6 — ordinary candidate capture | Obligation × path, applicable baseline-annotated lane. | Preserve today's `artifact()` access trace (up to three digest-property reads), seed from a successful R3 value, and reuse the capture for binding, audit, and stale diagnostics. |
+| C1 — legacy audit lane | Obligation × path for N/A, unknown, or non-baseline cases. | Preserve today's `artifact()` reads; this is a compatibility trace, not a once-only guarantee. N/A and unknown do not consume R3. |
+| C2 — evidence-record consumption | Obligation × record identity × field. | Preserve today's decision and provenance field read counts, including `paths`, `baseDigest`, `artifactDigests`, and `baselineArtifacts`; a single record must still bind both rename endpoints. |
+| C3 — invocation-level ingestion | Invocation × record / obligation, before evaluation, including when there are no obligations. | Preserve `isRecord()` reads of `id` / `obligationId` (up to two each in the current guard/short-circuit order, twice each for an admitted stable record), `knownIds` reads of obligation `id` / `capability`, and the waiver scan reads of review-record `kind` / `obligationId`. |
+| C4 — stale-diagnostic record paths | Obligation × record path. | Preserve iteration over `record.paths`; a path without a scoped capture falls back to the legacy `artifact()` read, including for applicable baseline-bound obligations. |
+| C5 — requirement-sync PRD-set enumeration | Conditional obligation check. | Preserve own-key enumeration and `artifact()` reads for each `docs/prd/` path, including out-of-scope PRDs, only when envelope verification reaches that check. |
+
+**Closure rule.** Any caller-object access not listed in R1–R6 remains a compatibility trace by
+default: preserve its existing timing, count, and decision effect until a separately approved
+change says otherwise. This does not permit a new access. A caller-object access absent from the
+current implementation has a budget of zero in Phase 0. Phase 0A records ordered `get`, `ownKeys`,
+`getOwnPropertyDescriptor`, and `getPrototypeOf` events across every factory-known caller object
+and pins the complete trace per observed case and distribution, including symbol properties,
+result category/identity, and thrown markers. Tracing must be transparent: the traced and unwrapped
+controls must agree on outputs, exceptions, identity relationships, semantic read counts, and
+caller-input integrity. The tracer must respect Proxy invariants for frozen objects and nested
+non-configurable properties. A trace proves completeness for its observed case; it does not
+establish branch coverage or replace Phase 0C's structural/API boundary and negative controls. Any
+observed unclassified access is added to the contract before Phase 0B. The applicability gate
+protects R2, R3, and scoped candidate capture; it does not gate every baseline, metadata, or
+pre-evaluation ingestion read (R1 and C3 retain their stated timing). C2, C4, C5, and C3's
+pre-evaluation ingestion are explicit compatibility lanes; their bounded reads must remain
+isolated or be documented as narrow exceptions to the Phase 0C boundary.
+
+### Phase limits
+
+Phase 0A defines this contract and builds the RED replay corpus, exact read traces, and qualified
+mutation controls. Each corpus case compares the full public result (`observation`, `outcome`,
+diagnostics, `artifactDigest`, `baseDigest`, `baselineArtifacts`, provenance, and `recordRefs`),
+role-specific counts/traces, and input integrity against canonical and packaged implementations.
+Phase 0A does not change evaluator behavior. Phase 0B introduces the smallest private
+capture layer as a pure refactor, preserving outputs, decision semantics, audit identity, read
+order/counts, input integrity, and canonical/package parity. Phase 0C enforces the normalized
+applicable baseline-bound boundary and qualifies mutation gates, including negative controls.
+Those phases and relevant CI on the final merged SHA are required for Gate E0. Phase 0A alone is
+not E0 and does not authorize runtime Evidence Reconciliation. Snapshot consistency is not external
+VCS/provenance attestation; that remains in #325 Phase 3b/3c.
+
+The C1 isolation trial rejected 9 of 11 weakened-boundary controls per distribution, while N05 and
+N06 survived with complete coverage and no diagnostics. The C2 AST/source supplement now rejects
+all 11 frozen controls in both distributions, including N05/N06 under `COMP-C2-BOUND`; its pinned
+whole-module and named-target fingerprints fail closed on unreviewed structural changes. This is
+deterministic mechanism evidence, not E0 qualification. C3 mutation/compatibility qualification and
+the final merged-SHA gates remain required. See
+[`doc-evidence-boundary.md`](doc-evidence-boundary.md) for the C1/C2 policy, trial results, and
+evidence boundary.
+
 ## Data shape
 
 The trusted baseline keeps its existing whole-tree identity and may add per-path SHA256 values:
@@ -39,9 +123,9 @@ scope = {
 - `reason: 'rename-from'` describes the old endpoint of an identified content-identical move.
   The destination is named by `renameTo` and must itself be a member of the same
   `scope.paths`. A `renameTo` outside the scope is malformed and fails the obligation closed.
-- Every `baselinePaths` entry's fields (`path`, `reason`, and the own-key `renameTo` presence) are
-  snapshotted through one guarded inspection, and each field result is carried exactly once. An
-  entry whose field getter or descriptor trap throws is a metadata error (`baseline-path-invalid`)
+- Under R4, each `baselinePaths` entry's fields (`path`, `reason`, and the own-key `renameTo`
+  presence) are snapshotted through one guarded inspection per obligation/entry, then reused by
+  consumers. An entry whose field getter or descriptor trap throws is a metadata error (`baseline-path-invalid`)
   and fails the entry closed instead of escaping the checker; a field accessor that throws only on
   a later read cannot abort the audit mirror; the mirror is built from the metadata-validated
    snapshot (validated path and captured digest) and is never a second read of the raw entry
@@ -74,7 +158,8 @@ A deleted path is satisfied only when one observed record:
 4. carries **no** `artifactDigests` entry for that path, and the candidate artifact map has **no
    own-key entry** for that path.
 
-The trusted per-path value is validated once during metadata validation and then **captured**.
+The trusted per-path value is validated and captured once for its R5 obligation/path identity
+during metadata validation.
 The audit mirror, the stale-baseline diagnostics, and baseline binding compare against that
 captured value and never re-read the caller-owned `baseline.artifacts` map during evidence
 evaluation: a stateful own getter cannot satisfy a record with a value it started returning only
@@ -84,14 +169,14 @@ different or unusable value later is factored out entirely. A baseline per-path
 throws during validation is a `baseline-artifact-invalid` metadata error and fails the path
 closed instead of escaping the checker. The audit mirror is likewise keyed by the **validated**
 path snapshot rather than a re-read of `baselinePaths[].path`, so a stateful `path` accessor is
-read exactly once and a passing result always describes the baseline identity that validated and
-bound the evidence.
+read once within its R4 obligation/entry snapshot and a passing result always describes the
+baseline identity that validated and bound the evidence.
 
-The whole-baseline identity `baseline.digest` follows the same discipline: it is read exactly
-once and that same scalar is validated, so a stateful value cannot be inspected as A while every
-evidence comparison uses B. The rename destination's own digest is also read exactly once during
-its validated snapshot, and the captured value drives the metadata cache, binding, the stale
-diagnostics, and the audit identity.
+The whole-baseline identity `baseline.digest` follows R1: the invocation-level read, when eligible,
+is the scalar validated and reused by every obligation. A rename destination's own digest follows
+R3: each declaring entry that reaches validation has its own read, with shared-destination
+agreement and poisoned-snapshot precedence. Consumers of each accepted snapshot reuse its captured
+value for metadata, binding, stale diagnostics, and audit identity.
 
 Per-path evidence must be carried explicitly. Inherited properties in `baseline.artifacts` or a
 record's `baselineArtifacts` are not own-key evidence and never satisfy a path; the trusted
@@ -116,11 +201,11 @@ candidate digest — the same one used by ordinary candidate binding, the audit
 stale diagnostics. The destination is therefore never read again through the candidate map during
 capture or binding: a nested `digest` that throws or changes after validation cannot make a stale
 destination pair bind while the audit/stale verdicts still describe the captured value. The same
-read-once guarantee extends to rejected destination snapshots: when the destination's own digest
-read throws or returns an unusable value, that failed snapshot ('') is recorded and all later
-reads for that destination path are suppressed as well — the entry's single metadata read remains
-its only digest read, and the failed path contributes `path=missing` to `artifactDigest` instead
-of a later, different value. The same
+R3 also governs rejected destination snapshots: when a declaring entry's own-digest read throws or
+returns an unusable value, that failed snapshot ('') is recorded and later declarations in the
+same obligation's metadata loop do not reread the poisoned destination — the rejected entry's
+metadata read remains its only digest read, and the failed path contributes `path=missing` to
+`artifactDigest` instead of a later, different value. The same
 record can cover both endpoints. Destination-only evidence, source-only tombstones, split endpoint
 records, and stale destination digests do not satisfy the source. A deletion tombstone therefore
 cannot stand in for a known rename. This destination validation and the snapshot it produces are
@@ -129,9 +214,10 @@ evidence, so they do not consume the destination digest getter during metadata v
 audit identity keeps the un-gated legacy candidate read, and a stateful accessor therefore reports
 the same first legacy value to them that it would report without baseline binding.
 
-Metadata validation is the single candidate snapshot for a baseline-only path. Once a declared
-baseline path has been confirmed to have **no** own-key candidate entry, that validated absence is
-carried on the entry; binding and the `artifactDigest` audit identity reuse it instead of
+For an applicable baseline-only path, R4 metadata validation captures candidate own-key absence
+once for that obligation/entry. Once a declared baseline path has been confirmed to have **no**
+own-key candidate entry, that validated absence is carried on the entry; binding and the
+`artifactDigest` audit identity reuse it instead of
 re-inspecting the candidate map, so a `Proxy` that answers own-property or `get` inspection
 consistently during validation cannot later abort the check or change the audit key. A
 baseline-only path therefore contributes `path=missing` to `artifactDigest` from the validated