@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/verification/inflight.js

@@ -0,0 +1,205 @@
+'use strict';
+
+// 088 G.4, IC-017: synchronous, local-host coordination, never a completed-result cache.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { defaultIsAlive } = require('../../state/run-lock.js');
+
+const TOKEN = /^[0-9a-f]{32}$/;
+const KEY = /^[0-9a-f]{16}$/;
+const RESULT_TTL_MS = 2 * 60 * 1000;
+const SCRATCH_TTL_MS = 10 * 60 * 1000;
+const MAX_STREAM_CHARS = 2000;
+const wait = (ms        )       => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+
+function validLock(lock     )          {
+  return lock?.v === 1 && TOKEN.test(lock.token) && Number.isSafeInteger(lock.pid) && lock.pid > 0
+    && Number.isSafeInteger(lock.startedAt) && Number.isSafeInteger(lock.deadlineAt)
+    && lock.deadlineAt >= lock.startedAt;
+}
+
+/** Only the execution fields the runner consumes cross the process boundary, never pid/argv. */
+function execution(result     )      {
+  if (!result || !(result.status === null || (Number.isInteger(result.status) && result.status >= 0))
+    || typeof result.stdout !== 'string' || typeof result.stderr !== 'string'
+    || !(result.signal == null || typeof result.signal === 'string')
+    || (result.error && typeof result.error.message !== 'string')) throw new Error('Invalid execution result');
+  return {
+    status: result.status,
+    stdout: result.bounded === true ? result.stdout : result.stdout.slice(0, MAX_STREAM_CHARS),
+    stderr: result.bounded === true ? result.stderr : result.stderr.slice(0, MAX_STREAM_CHARS),
+    truncated: result.truncated === true || result.stdout.length > MAX_STREAM_CHARS || result.stderr.length > MAX_STREAM_CHARS,
+    signal: result.signal ?? null,
+    ...(result.error ? { error: { message: result.error.message, code: result.error.code ?? null } } : {}),
+    ...(result.bounded === true ? {
+      bounded: true,
+      tests: result.tests,
+      testsFailed: result.testsFailed,
+      ...(result.failedTests ? { failedTests: result.failedTests } : {}),
+      ...(result.failedFiles ? { failedFiles: result.failedFiles } : {}),
+      ...(Object.hasOwn(result, 'logPath') ? { logPath: result.logPath } : {}),
+    } : {}),
+  };
+}
+
+/** All removers use a per-instance claim, including the leader. Without this, a sweeper that
+ * inspected an old lock could unlink a new leader between its token read and unlink. Claims
+ * are never waited for or taken over; an orphan costs sharing, never correctness. */
+function removeLock(io     , file        , token        , expired         , now              )       {
+  const claim = `${file}.${token}.claim`;
+  io.writeFileSync(claim, '', { flag: 'wx', mode: 0o600 });
+  try {
+    const current = JSON.parse(io.readFileSync(file, 'utf8'));
+    if (validLock(current) && current.token === token && (!expired || now() > current.deadlineAt)) {
+      io.unlinkSync(file);
+    }
+  } finally {
+    io.unlinkSync(claim);
+  }
+}
+
+function sweepInflight(dir        , { fsImpl = fs, now = Date.now }      = {})       {
+  for (const name of fsImpl.readdirSync(dir)) {
+    const result = /^inflight-[0-9a-f]{16}\.[0-9a-f]{32}\.result\.json$/.test(name);
+    const lock = /^inflight-[0-9a-f]{16}\.lock$/.test(name);
+    const scratch = /^inflight-[0-9a-f]{16}(?:\.[0-9a-f]{32}\.tmp|\.lock\.[0-9a-f]{32}\.claim)$/.test(name);
+    if (!result && !lock && !scratch) continue;
+    const file = path.join(dir, name);
+    try {
+      if (scratch) {
+        if (now() - fsImpl.statSync(file).mtimeMs > SCRATCH_TTL_MS) fsImpl.unlinkSync(file);
+        continue;
+      }
+      const raw = fsImpl.readFileSync(file, 'utf8');
+      let record     ;
+      try {
+        record = JSON.parse(raw);
+        if (result ? record?.v !== 1 || !Number.isSafeInteger(record.finishedAt) : !validLock(record)) {
+          throw new Error('Invalid inflight record');
+        }
+      } catch {
+        // Fresh empty locks still get the follower's bounded retry. Only malformed
+        // records use mtime: valid locks always require the token-bound removal claim.
+        if (now() - fsImpl.statSync(file).mtimeMs > RESULT_TTL_MS) fsImpl.unlinkSync(file);
+        continue;
+      }
+      if (result) {
+        if (now() - record.finishedAt > RESULT_TTL_MS) fsImpl.unlinkSync(file);
+      } else {
+        if (now() > record.deadlineAt) removeLock(fsImpl, file, record.token, true, now);
+      }
+    } catch {
+      // A raced, inaccessible or claimed entry never disables unrelated sharing.
+    }
+  }
+}
+
+/** Returns spawnSync's execution plus out-of-report telemetry. A coordination fault executes
+ * locally; exceptions from execute itself are left to the runner's ordinary FAIL handling. */
+function runInflight({ dir, key, timeoutMs, execute, summarize, fsImpl = fs, now = Date.now,
+  isAlive = defaultIsAlive, sleep = wait, monotonic = () => process.hrtime.bigint(), mintToken = () => crypto.randomBytes(16).toString('hex') }     )      {
+  const unshared = () => ({ result: execute(), shared: 'none', sharedRef: null });
+  if (typeof key !== 'string' || !KEY.test(key) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 0) return unshared();
+  let token        ;
+  let lockFile        ;
+  let temp                    ;
+  let tempOwned = false;
+  let owner = false;
+  let follower      = null;
+  let arrival = 0;
+  let arrivalNs                    ;
+  try {
+    fsImpl.mkdirSync(dir, { recursive: true });
+    sweepInflight(dir, { fsImpl, now });
+    token = mintToken();
+    if (!TOKEN.test(token)) throw new Error('Invalid token');
+    lockFile = path.join(dir, `inflight-${key}.lock`);
+    temp = path.join(dir, `inflight-${key}.${token}.tmp`);
+    const startedAt = now();
+    const record = { v: 1, token, pid: process.pid, startedAt, deadlineAt: startedAt + timeoutMs + 30000 };
+    if (!validLock(record)) throw new Error('Invalid clock');
+    fsImpl.writeFileSync(temp, JSON.stringify(record), { flag: 'wx', mode: 0o600 });
+    tempOwned = true;
+    try {
+      fsImpl.linkSync(temp, lockFile);
+      owner = true;
+    } catch (error     ) {
+      if (error.code !== 'EEXIST') throw error;
+      arrival = now();
+      if (!Number.isSafeInteger(arrival)) throw new Error('Invalid arrival clock');
+      arrivalNs = monotonic();
+    }
+    fsImpl.unlinkSync(temp);
+    tempOwned = false;
+    temp = undefined;
+    if (!owner) {
+      // Bound retries by count as well as clock: a stalled wall clock must not hang verification.
+      for (let attempt = 0; attempt <= 4; attempt++) {
+        let raw = '';
+        try { raw = fsImpl.readFileSync(lockFile, 'utf8'); } catch (error     ) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+        if (raw) { follower = JSON.parse(raw); break; }
+        if (attempt === 4 || now() - arrival >= 1000) break;
+        sleep(250);
+      }
+      if (!validLock(follower)) throw new Error('Invalid follower lock');
+    }
+  } catch {
+    if (tempOwned && temp) { try { fsImpl.unlinkSync(temp); } catch { /* local temp only */ } }
+    if (owner) { try { removeLock(fsImpl, lockFile , token , false, now); } catch { /* never remove an unknown owner */ } }
+    return unshared();
+  }
+
+  if (!owner) {
+    try {
+      const resultFile = path.join(dir, `inflight-${key}.${follower.token}.result.json`);
+      const maxPolls = Math.ceil((timeoutMs + 30000) / 250) + 1;
+      for (let attempt = 0; attempt < maxPolls; attempt++) {
+        let raw                = null;
+        try { raw = fsImpl.readFileSync(resultFile, 'utf8'); } catch (error     ) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+        if (raw !== null) {
+          const record = JSON.parse(raw);
+          if (record?.v !== 1 || record.token !== follower.token || !Number.isSafeInteger(record.finishedAt)
+            || arrival > record.finishedAt || record.finishedAt < follower.startedAt) throw new Error('Unrelated result');
+          return { result: execution(record.result), shared: 'follower', sharedRef: follower.token, durationMs: Math.max(0, Number(monotonic() - arrivalNs ) / 1e6) };
+        }
+        const current = JSON.parse(fsImpl.readFileSync(lockFile , 'utf8'));
+        if (!validLock(current) || current.token !== follower.token || !isAlive(follower.pid)
+          || now() > follower.deadlineAt) break;
+        sleep(250);
+      }
+    } catch { /* any result, lock, liveness or wait fault runs locally */ }
+    return unshared();
+  }
+
+  let result     ;
+  let shared = 'leader';
+  try {
+    result = execute();
+    if (summarize) result = summarize(result);
+    const persisted = execution(result);
+    const finishedAt = now();
+    if (!Number.isSafeInteger(finishedAt)) throw new Error('Invalid result clock');
+    const resultFile = path.join(dir, `inflight-${key}.${token }.result.json`);
+    temp = path.join(dir, `inflight-${key}.${token }.tmp`);
+    fsImpl.writeFileSync(temp, JSON.stringify({ v: 1, token: token , finishedAt, result: persisted }), { flag: 'wx', mode: 0o600 });
+    tempOwned = true;
+    fsImpl.renameSync(temp, resultFile);
+    tempOwned = false;
+    temp = undefined;
+  } catch (error) {
+    // Execution already happened locally. Publication faults do not replace its verdict.
+    shared = 'none';
+    if (result === undefined) throw error;
+  } finally {
+    if (tempOwned && temp) { try { fsImpl.unlinkSync(temp); } catch { /* local temp only */ } }
+    try { removeLock(fsImpl, lockFile , token , false, now); } catch { shared = 'none'; }
+  }
+  return { result, shared, sharedRef: shared === 'leader' ? token  : null };
+}
+
+module.exports = { runInflight, sweepInflight };

package/src/runtime/verification/registry.js

@@ -16,6 +16,7 @@ const path = require('node:path');
 const nodeFs = require('node:fs');
 const { parseYamlFile } = require('../capability-router.js');
 const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { configHome } = require('../config-home.js');
 
 const REGISTRY_FILENAME = 'verification.json';
 
@@ -107,8 +108,22 @@ function loadVerificationRegistry(options      = {})      {
   // of the registry, so it is checkable here instead of being re-asserted in prose.
   assert(firstModelOrder > lastNonModelOrder, 'every model-based tier must be ordered after every deterministic tier');
 
+  assert(data.levels && typeof data.levels === 'object', 'levels must be an object');
+  const l0 = data.levels.L0;
+  assert(l0 && typeof l0 === 'object', 'levels.L0 must be an object');
+  assert(Array.isArray(l0.tiers) && l0.tiers.length > 0, 'levels.L0.tiers must be a non-empty array');
+  for (const t of l0.tiers) {
+    assert(seen.has(t), `levels.L0 tier '${t}' must exist in tiers`);
+  }
+
   for (const [level, def] of Object.entries(data.riskLevels)                   ) {
     assert(def && Array.isArray(def.requiredTiers), `risk level '${level}' needs requiredTiers`);
+    for (let i = 0; i < l0.tiers.length; i++) {
+      assert(
+        def.requiredTiers[i] === l0.tiers[i],
+        `risk level '${level}' requiredTiers must begin with L0 tiers [${l0.tiers.join(', ')}]`,
+      );
+    }
     for (const id of def.requiredTiers.concat(def.advisoryTiers || [])) {
       assert(seen.has(id), `risk level '${level}' references unknown tier '${id}'`);
     }
@@ -118,13 +133,174 @@ function loadVerificationRegistry(options      = {})      {
     );
   }
 
+  const levelNames = ['L1', 'L2', 'L3']         ;
+  const riskLevelsInLevels = new Map                ();
+  for (const lvl of levelNames) {
+    const entry = data.levels[lvl];
+    assert(entry && typeof entry === 'object', `levels.${lvl} must be an object`);
+    assert(Array.isArray(entry.riskLevels), `levels.${lvl}.riskLevels must be an array`);
+    for (const r of entry.riskLevels) {
+      assert(typeof r === 'string' && r !== '', `levels.${lvl}.riskLevels entries must be non-empty strings`);
+      assert(Object.hasOwn(data.riskLevels, r), `levels.${lvl} references unknown risk level '${r}'`);
+      assert(!riskLevelsInLevels.has(r), `risk level '${r}' is declared in multiple levels ('${riskLevelsInLevels.get(r)}' and '${lvl}')`);
+      riskLevelsInLevels.set(r, lvl);
+    }
+  }
+  for (const r of Object.keys(data.riskLevels)) {
+    assert(riskLevelsInLevels.has(r), `risk level '${r}' must be assigned to exactly one of L1..L3`);
+  }
+
+  assert(policy.v0 && typeof policy.v0 === 'object', 'policy.v0 must be an object');
+  assert(Array.isArray(policy.v0.levels), 'policy.v0.levels must be an array');
+  const allowedV0Levels = new Set(['L1', 'L2']);
+  for (const lvl of policy.v0.levels) {
+    assert(allowedV0Levels.has(lvl), `policy.v0.levels must be a subset of ['L1', 'L2']: found '${lvl}'`);
+  }
+
+  // 089 IC-008: the reuse policy is data (levels that may reuse, age bound, declared ignored inputs).
+  assert(policy.reuse && typeof policy.reuse === 'object', 'policy.reuse must be an object');
+  assert(Array.isArray(policy.reuse.levels), 'policy.reuse.levels must be an array');
+  for (const lvl of policy.reuse.levels) {
+    assert(allowedV0Levels.has(lvl), `policy.reuse.levels must be a subset of ['L1', 'L2']: found '${lvl}'`);
+  }
+  assert(
+    Number.isInteger(policy.reuse.maxAgeMs) && policy.reuse.maxAgeMs > 0,
+    'policy.reuse.maxAgeMs must be a positive integer',
+  );
+  assert(Array.isArray(policy.reuse.ignoredInputs), 'policy.reuse.ignoredInputs must be an array');
+  for (const input of policy.reuse.ignoredInputs) {
+    assert(
+      typeof input === 'string' && input !== '' && !input.includes('\0')
+        && !path.isAbsolute(input) && !path.win32.isAbsolute(input)
+        && !input.split(/[\\/]+/).includes('..'),
+      `policy.reuse.ignoredInputs entries must be relative paths without '..': found '${String(input)}'`,
+    );
+  }
+
+  // 095b IC-003: the review depth policy is data. An invalid block is a load error, never a default.
+  const depthPolicy = data.reviewDepth;
+  assert(isPlainObject(depthPolicy), 'reviewDepth must be an object');
+  for (const key of Object.keys(depthPolicy)) {
+    assert(REVIEW_DEPTH_KEYS.includes(key), `reviewDepth has an unknown key '${key}' (allowed: ${REVIEW_DEPTH_KEYS.join(', ')})`);
+  }
+  assert(Array.isArray(depthPolicy.singleRisks), 'reviewDepth.singleRisks must be an array');
+  for (const risk of depthPolicy.singleRisks) {
+    assert(
+      typeof risk === 'string' && Object.hasOwn(data.riskLevels, risk),
+      `reviewDepth.singleRisks must be a subset of the riskLevels keys: found '${String(risk)}'`,
+    );
+  }
+  assert(
+    Array.isArray(depthPolicy.lightPaths) && depthPolicy.lightPaths.length > 0,
+    'reviewDepth.lightPaths must be a non-empty array',
+  );
+  for (const entry of depthPolicy.lightPaths) {
+    assert(
+      typeof entry === 'string' && entry !== '' && !entry.includes('\0')
+        && !entry.startsWith('/') && !entry.split(/[\\/]+/).includes('..')
+        && !entry.startsWith('./') && !entry.includes('\\'),
+      `reviewDepth.lightPaths entries must be non-empty '/'-separated strings without a '..' segment, a leading '/' or './', or a backslash: found '${String(entry)}'`,
+    );
+  }
+
   return data;
 }
 
+/** The keys a `reviewDepth` block may carry (095b IC-003); anything else can never take effect. The seat counts
+ * live in core/registry/protocols.json (119 D-4), so a `depths` key is refused here as unknown. */
+const REVIEW_DEPTH_KEYS = ['description', 'singleRisks', 'lightPaths'];
+
+function isPlainObject(value     )          {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * The validated review depth policy (095b IC-003): `{ description, singleRisks, lightPaths }`.
+ * Throws when the registry carries no such block; `loadVerificationRegistry` already guarantees it for a loaded registry.
+ */
+function reviewDepthPolicy(registry     )      {
+  assert(isPlainObject(registry?.reviewDepth), 'reviewDepth must be an object');
+  return registry.reviewDepth;
+}
+
+/**
+ * Maps a risk level ('LOW', 'MEDIUM', 'HIGH', 'CRITICAL') to its verification level ('L1' | 'L2' | 'L3').
+ * Returns null if the risk level is unknown, null, or undefined.
+ */
+function levelOf(registry     , risk                           )                            {
+  if (!registry?.levels || typeof risk !== 'string') return null;
+  for (const lvl of ['L1', 'L2', 'L3']         ) {
+    const riskLevels = registry.levels[lvl]?.riskLevels;
+    if (Array.isArray(riskLevels) && riskLevels.includes(risk)) {
+      return lvl;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns whether V0 behavior applies to the given risk level under the registry policy.
+ * True when the risk level maps to a level listed in policy.v0.levels.
+ */
+function v0Applies(registry     , risk                           )          {
+  const level = levelOf(registry, risk);
+  if (!level) return false;
+  const v0Levels = registry?.policy?.v0?.levels;
+  return Array.isArray(v0Levels) && v0Levels.includes(level);
+}
+
+/**
+ * Returns whether result reuse may apply to the given risk level (089 IC-008).
+ * True when the risk level maps to a level listed in policy.reuse.levels.
+ */
+function reuseApplies(registry     , risk                           )          {
+  const level = levelOf(registry, risk);
+  if (!level) return false;
+  const reuseLevels = registry?.policy?.reuse?.levels;
+  return Array.isArray(reuseLevels) && reuseLevels.includes(level);
+}
+
+/**
+ * Resolves whether V0 behavior is enabled (IC-015, DD-8).
+ * False if env.DOFLOW_VERIFY_V0 === 'off', else false if <configDir>/verify-v0.off exists, else true.
+ * A stat fault counts as absent (on). Read once per verify command (handleVerifyCommand).
+ *
+ * @param {Object} [env=process.env]
+ * @param {string|null} [configDir] directory containing verify-v0.off sentinel; falls back to configHome(env).dir
+ * @param {Object} [fsImpl=nodeFs]
+ * @returns {boolean}
+ */
+function v0Enabled(env      = process.env, configDir                , fsImpl      = nodeFs)          {
+  if (env && env.DOFLOW_VERIFY_V0 === 'off') {
+    return false;
+  }
+  const dir = configDir !== undefined ? configDir : configHome(env).dir;
+  if (!dir) {
+    return true;
+  }
+  const io = fsImpl || nodeFs;
+  try {
+    const stat = io.statSync(path.join(dir, 'verify-v0.off'));
+    if (typeof stat.isFile === 'function' ? stat.isFile() : true) {
+      return false;
+    }
+  } catch {
+    // A stat fault counts as absent (on).
+    return true;
+  }
+  return true;
+}
+
 module.exports = {
   loadVerificationRegistry,
+  reviewDepthPolicy,
+  levelOf,
+  v0Applies,
+  reuseApplies,
+  v0Enabled,
   TIER_RESOLUTIONS,
   TIER_STATUSES,
   RECOVERY_OUTCOMES,
   REGISTRY_FILENAME,
 };
+

package/src/runtime/verification/reuse.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { loadStorageRegistry } = require('../storage/registry.js');
+const { resolveRoots, resolveStorePath } = require('../storage/roots.js');
+
+const KEY = /^[0-9a-f]{16}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const REF = /^[0-9a-f]{32}$/;
+const LEVELS = new Set(['L1', 'L2', 'L3']);
+/** The report's bounded excerpt (2,000 kept characters plus the elision marker, at most about 2,060) must fit whole,
+ * so a reused check shows exactly what the executed one showed (089 DEVIATION from IC-002's 2,000). */
+const MAX_STREAM_CHARS = 2200;
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+
+function isObject(value     )          { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function exactKeys(value     , required          , optional           = [])          {
+  if (!isObject(value)) return false;
+  const keys = Object.keys(value);
+  return required.every((key) => Object.hasOwn(value, key))
+    && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+function optionalCount(value     )          { return value === null || Number.isSafeInteger(value) && value >= 0; }
+
+/** IC-002: validate the closed record/result schemas before any cached PASS is trusted. */
+function validRecord(record     )          {
+  if (!exactKeys(record, ['v', 'key', 'payloadDigest', 'ref', 'recordedAt', 'level', 'result'])) return false;
+  if (record.v !== 1 || typeof record.key !== 'string' || !KEY.test(record.key)
+    || typeof record.payloadDigest !== 'string' || !DIGEST.test(record.payloadDigest)
+    || typeof record.ref !== 'string' || !REF.test(record.ref)
+    || !Number.isSafeInteger(record.recordedAt) || !LEVELS.has(record.level)) return false;
+  const result = record.result;
+  if (!exactKeys(result, ['status', 'exitCode', 'stdout', 'stderr', 'truncated'], ['tests', 'testsFailed'])) return false;
+  if (result.status !== 'PASS' || result.exitCode !== 0
+    || typeof result.stdout !== 'string' || result.stdout.length > MAX_STREAM_CHARS
+    || typeof result.stderr !== 'string' || result.stderr.length > MAX_STREAM_CHARS
+    || typeof result.truncated !== 'boolean') return false;
+  if (Object.hasOwn(result, 'tests') && !optionalCount(result.tests)) return false;
+  if (Object.hasOwn(result, 'testsFailed') && !optionalCount(result.testsFailed)) return false;
+  return true;
+}
+
+/** IC-008: resolve the declared project-state store through the shared storage registry. */
+function reuseDir({ projectRoot, configDir, env = process.env, fsImpl = fs }      = {})                {
+  try {
+    const root = typeof projectRoot === 'string' ? projectRoot
+      : typeof configDir === 'string' ? path.dirname(configDir) : process.cwd();
+    const registry = loadStorageRegistry({ repoRoot: REPO_ROOT, fsImpl });
+    const store = registry.stores.find((entry     ) => entry.id === 'verification-reuse');
+    if (!store) return null;
+    const roots = resolveRoots({ registry, projectRoot: root, env });
+    return resolveStorePath({ store, roots, fsImpl });
+  } catch {
+    return null;
+  }
+}
+
+/** IC-003: look up one trusted, current PASS record. Invalid inputs and filesystem faults fail closed. */
+function lookupReuse(options      = {})      {
+  try { return lookupReuseOptions(options || {}); } catch { return { hit: false, reason: 'fault' }; }
+}
+
+function lookupReuseOptions({ dir, key, payloadDigest, maxAgeMs, now = Date.now, fsImpl = fs, uid }      = {})      {
+  if (typeof dir !== 'string' || typeof key !== 'string' || !KEY.test(key)
+    || typeof payloadDigest !== 'string' || !DIGEST.test(payloadDigest)
+    || !Number.isSafeInteger(maxAgeMs) || maxAgeMs < 0 || typeof now !== 'function') {
+    return { hit: false, reason: 'invalid' };
+  }
+  const file = path.join(dir, `reuse-${key}.json`);
+  let stat     ;
+  try { stat = fsImpl.lstatSync(file); } catch (error     ) {
+    return { hit: false, reason: error?.code === 'ENOENT' ? 'absent' : 'fault' };
+  }
+  try {
+    if (!stat || typeof stat.isFile !== 'function' || !stat.isFile()
+      || typeof stat.isSymbolicLink === 'function' && stat.isSymbolicLink()) {
+      return { hit: false, reason: 'untrusted' };
+    }
+    if (process.platform !== 'win32') {
+      const expectedUid = typeof uid === 'number' ? uid : (process       ).getuid?.();
+      if ((stat.mode & 0o077) !== 0) return { hit: false, reason: 'untrusted' };
+      if (expectedUid !== undefined && stat.uid !== expectedUid) return { hit: false, reason: 'untrusted' };
+    }
+  } catch {
+    return { hit: false, reason: 'fault' };
+  }
+  // 089 re-review S-1: a process that cannot evict from this store (evictReuse ignores EACCES) must
+  // not reuse from it either, or an executed FAIL it could not remove is followed by a reused PASS.
+  try { fsImpl.accessSync(dir, fs.constants.W_OK); } catch {
+    return { hit: false, reason: 'unwritable' };
+  }
+
+  let raw        ;
+  try { raw = fsImpl.readFileSync(file, 'utf8'); } catch {
+    return { hit: false, reason: 'fault' };
+  }
+  let record     ;
+  try { record = JSON.parse(raw); } catch {
+    return { hit: false, reason: 'invalid' };
+  }
+  if (!validRecord(record)) return { hit: false, reason: 'invalid' };
+  if (record.key !== key || record.payloadDigest !== payloadDigest) return { hit: false, reason: 'digest-mismatch' };
+  let current        ;
+  try { current = now(); } catch { return { hit: false, reason: 'fault' }; }
+  if (!Number.isSafeInteger(current)) return { hit: false, reason: 'fault' };
+  if (record.recordedAt > current) return { hit: false, reason: 'future' };
+  if (current - record.recordedAt > maxAgeMs) return { hit: false, reason: 'stale' };
+  return { hit: true, record };
+}
+
+/** IC-002/IC-003: publish only a PASS through an owner-only temp file and atomic rename. */
+function storeReuse(options      = {})                                          {
+  try { return storeReuseOptions(options || {}); } catch { return { stored: false, ref: null }; }
+}
+
+function storeReuseOptions({ dir, key, payloadDigest, level, result, now = Date.now, fsImpl = fs,
+  mintRef = () => crypto.randomBytes(16).toString('hex') }      = {})                                          {
+  let temp                = null;
+  let ownsTemp = false;
+  try {
+    if (typeof dir !== 'string' || typeof key !== 'string' || !KEY.test(key)
+      || typeof payloadDigest !== 'string' || !DIGEST.test(payloadDigest)
+      || !LEVELS.has(level) || typeof now !== 'function' || typeof mintRef !== 'function'
+      || !isObject(result) || result.status !== 'PASS' || result.exitCode !== 0
+      || typeof result.stdout !== 'string' || typeof result.stderr !== 'string'
+      || typeof result.truncated !== 'boolean') return { stored: false, ref: null };
+    if (Object.hasOwn(result, 'tests') && !optionalCount(result.tests)) return { stored: false, ref: null };
+    if (Object.hasOwn(result, 'testsFailed') && !optionalCount(result.testsFailed)) return { stored: false, ref: null };
+    const recordedAt = now();
+    if (!Number.isSafeInteger(recordedAt)) return { stored: false, ref: null };
+    const ref = mintRef();
+    if (typeof ref !== 'string' || !REF.test(ref)) return { stored: false, ref: null };
+    const stdout = result.stdout.slice(0, MAX_STREAM_CHARS);
+    const stderr = result.stderr.slice(0, MAX_STREAM_CHARS);
+    const savedResult      = {
+      status: 'PASS',
+      exitCode: 0,
+      stdout,
+      stderr,
+      truncated: result.truncated || result.stdout.length > MAX_STREAM_CHARS || result.stderr.length > MAX_STREAM_CHARS,
+    };
+    if (Object.hasOwn(result, 'tests')) savedResult.tests = result.tests;
+    if (Object.hasOwn(result, 'testsFailed')) savedResult.testsFailed = result.testsFailed;
+    const record = { v: 1, key, payloadDigest, ref, recordedAt, level, result: savedResult };
+    if (!validRecord(record)) return { stored: false, ref: null };
+
+    fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const directory = fsImpl.lstatSync(dir);
+    if (!directory.isDirectory() || directory.isSymbolicLink()) return { stored: false, ref: null };
+    fsImpl.chmodSync(dir, 0o700);
+    const file = path.join(dir, `reuse-${key}.json`);
+    temp = path.join(dir, `reuse-${key}.${ref}.tmp`);
+    fsImpl.writeFileSync(temp, JSON.stringify(record), { flag: 'wx', mode: 0o600 });
+    ownsTemp = true;
+    fsImpl.chmodSync(temp, 0o600);
+    fsImpl.renameSync(temp, file);
+    ownsTemp = false;
+    return { stored: true, ref };
+  } catch {
+    if (ownsTemp && temp) { try { fsImpl.unlinkSync(temp); } catch { /* only this call's unique temp */ } }
+    return { stored: false, ref: null };
+  }
+}
+
+/**
+ * IC-003 (089 review C-2): remove the stored record for a key after an executed non-PASS, so a
+ * failure is never followed by a reused PASS. Only `reuse-<hex16>.json` is touched; a symlink
+ * there is unlinked itself, never followed. Any fault is ignored; it never throws.
+ */
+function evictReuse({ dir, key, fsImpl = fs }      = {})                       {
+  try {
+    if (typeof dir !== 'string' || typeof key !== 'string' || !KEY.test(key)) return { evicted: false };
+    const file = path.join(dir, `reuse-${key}.json`);
+    fsImpl.lstatSync(file);
+    fsImpl.unlinkSync(file);
+    return { evicted: true };
+  } catch {
+    return { evicted: false };
+  }
+}
+
+module.exports = { lookupReuse, storeReuse, evictReuse, reuseDir };