cadet-agent 0.20.2 → 0.24.0

package/src/harness/util.mjs

@@ -0,0 +1,149 @@
+/**
+ * Shared harness primitives: UUIDv4, SHA-256 over UTF-8 bytes, tree hashing,
+ * deterministic JSON serialization, and UTC timestamps.
+ *
+ * Contract: docs/core/HarnessContract.md §2 (identifiers, hashes).
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+/** UUIDv4 identifier. */
+export function newId() {
+  return randomUUID();
+}
+
+export function isUuid(value) {
+  return typeof value === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
+}
+
+/** SHA-256 hex digest over UTF-8 bytes. */
+export function sha256(value) {
+  return createHash('sha256').update(value, 'utf-8').digest('hex');
+}
+
+/** SHA-256 hex digest over raw bytes (Buffers are hashed as-is). */
+export function sha256Bytes(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/** Hash of a file's exact bytes, or null when the file is missing. */
+export function hashFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return sha256Bytes(readFileSync(path));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deterministic hash of a set of `(relativePath, fileHash)` pairs.
+ * Pairs are sorted by path so the hash is order-independent and stable across
+ * platforms. Files without a resolvable hash are recorded as `missing`.
+ */
+export function hashTree(pairs) {
+  const normalized = [...pairs]
+    .map(({ path, hash }) => ({
+      path: String(path).replace(/\\/g, '/'),
+      hash: hash || 'missing',
+    }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return sha256(JSON.stringify(normalized));
+}
+
+/**
+ * Hash an acceptance-criteria document or list. `criteria` may be a string or an
+ * array of strings; a stable serialization is used either way.
+ */
+export function hashCriteria(criteria) {
+  if (criteria === null || criteria === undefined) return sha256('[]');
+  const arr = Array.isArray(criteria) ? criteria.map(String) : [String(criteria)];
+  return sha256(JSON.stringify(arr));
+}
+
+/** ISO-8601 UTC timestamp for a Date or "now". */
+export function timestamp(at = new Date()) {
+  return (at instanceof Date ? at : new Date(at)).toISOString();
+}
+
+/** Current time provider; injectable for deterministic tests. */
+export function nowMs() {
+  return Date.now();
+}
+
+/**
+ * Canonical JSON with sorted keys. Used for stable hashes and for comparing
+ * evidence records without key-order noise.
+ */
+export function canonicalJson(value) {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[key]);
+    return out;
+  }
+  return value;
+}
+
+export { canonicalJson as stableStringify };
+
+/**
+ * List the files changed in the working tree relative to HEAD, using git.
+ * Returns forward-slash relative paths. Returns an empty array when git is
+ * unavailable or the directory is not a repository — callers must not assume
+ * freshness coverage in that case; use `gitChangedFiles` when the distinction
+ * between "no changes" and "no git" matters.
+ */
+export function changedFiles(cwd, { runner = defaultGitRunner } = {}) {
+  return gitChangedFiles(cwd, { runner }).files;
+}
+
+/**
+ * List changed files and report whether git was actually queryable.
+ * Returns `{ available, files, reason }`. `available: false` means freshness
+ * coverage could not be established and callers must fail safe.
+ */
+export function gitChangedFiles(cwd, { runner = defaultGitRunner } = {}) {
+  let res;
+  try {
+    res = runner('git', ['-C', cwd, 'status', '--porcelain', '--untracked-files=all']);
+  } catch (err) {
+    return { available: false, files: [], reason: `git invocation failed: ${err.message}` };
+  }
+  if (!res) {
+    return { available: false, files: [], reason: 'git is not available' };
+  }
+  if (res.error || res.status === null) {
+    return { available: false, files: [], reason: 'git is not installed or could not be executed' };
+  }
+  if (res.status !== 0) {
+    // Not a repository, or git refused the query.
+    return { available: false, files: [], reason: String(res.stderr || '').trim() || `git exited ${res.status}` };
+  }
+  const files = new Set();
+  for (const line of String(res.stdout || '').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    // Porcelain v1: XY<space>path (rename: "old -> new").
+    let path = line.slice(3).trim();
+    if (path.includes(' -> ')) path = path.split(' -> ').pop().trim();
+    path = path.replace(/^"|"$/g, '');
+    if (path) files.add(path.replace(/\\/g, '/'));
+  }
+  return { available: true, files: [...files].sort(), reason: null };
+}
+
+function defaultGitRunner(cmd, args) {
+  try {
+    return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true });
+  } catch {
+    return null;
+  }
+}
+

package/src/harness/verification.mjs

@@ -0,0 +1,490 @@
+/**
+ * Cadet-Agent verification runner.
+ *
+ * Deterministic, bounded verification with a single retry classifier. Skills may
+ * supply policy (commands, flaky signatures) but may not invent classifications.
+ *
+ * Contract: docs/core/HarnessContract.md §4 (retry classifier), §5 (commands), §6 (loop).
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createEvidence, computeInputTreeHash } from './state.mjs';
+import { hashCriteria, sha256Bytes, timestamp, newId } from './util.mjs';
+import { BudgetTracker, budgetExhaustedResult, evaluateHardStop } from './budget.mjs';
+import { redactString } from './redaction.mjs';
+
+export const RETRY_CLASSES = Object.freeze(['deterministic', 'transient', 'repair', 'unknown']);
+export const RESULT_STATUSES = Object.freeze(['passed', 'failed', 'flaky', 'blocked', 'timed-out']);
+
+/** Backoff schedule for transient retries (ms). */
+export const TRANSIENT_BACKOFF_MS = Object.freeze([250, 1000, 4000]);
+
+/** Default flaky signatures (configurable via policy.estimation? no — via verification policy). */
+export const DEFAULT_FLAKY_SIGNATURES = Object.freeze([
+  'econnreset',
+  'etimedout',
+  'socket hang up',
+  'connection refused',
+  'temporarily unavailable',
+  'service unavailable',
+  'process launch failed',
+  'eaddrnotavail',
+]);
+
+const DETERMINISTIC_SIGNATURES = Object.freeze([
+  'assertionerror',
+  'expected',
+  'syntaxerror',
+  'compile error',
+  'compilationerror',
+  'cs0',
+  'analyzer',
+  'unt',
+  'invalid input',
+  'usage:',
+  'unknown option',
+  'no such file',
+  'cannot find module',
+  'unhandled rejection',
+]);
+
+const TRANSIENT_SIGNATURES = DEFAULT_FLAKY_SIGNATURES;
+
+/**
+ * Classify a command result. The classifier is the single source of truth for
+ * retry behavior — nothing else may decide to retry.
+ *
+ * Returns `{ retryClass, reason, retryable }`.
+ */
+export function classifyResult({ exitCode = null, timedOut = false, stdout = '', stderr = '', errorMessage = '', flakySignatures = DEFAULT_FLAKY_SIGNATURES } = {}) {
+  const haystack = `${errorMessage}\n${stderr}\n${stdout}`.toLowerCase();
+
+  if (timedOut) {
+    // A timeout is deterministic unless its signature is explicitly configured flaky.
+    if (flakySignatures.some((s) => haystack.includes(s))) {
+      return { retryClass: 'transient', reason: 'timeout with a configured flaky signature', retryable: true };
+    }
+    return { retryClass: 'deterministic', reason: 'reproducible timeout does not retry automatically', retryable: false };
+  }
+
+  if (TRANSIENT_SIGNATURES.some((s) => haystack.includes(s))) {
+    return { retryClass: 'transient', reason: `matched transient signature`, retryable: true };
+  }
+
+  if (exitCode === 0) {
+    return { retryClass: 'deterministic', reason: 'success', retryable: false };
+  }
+
+  if (DETERMINISTIC_SIGNATURES.some((s) => haystack.includes(s))) {
+    return { retryClass: 'deterministic', reason: 'matched a deterministic failure signature', retryable: false };
+  }
+
+  if (exitCode !== null && exitCode !== 0) {
+    return { retryClass: 'unknown', reason: `unrecognized failure (exit ${exitCode}); escalate`, retryable: false };
+  }
+
+  return { retryClass: 'unknown', reason: 'unrecognized result; escalate', retryable: false };
+}
+
+/** A `repair` retry is only valid when it references the failed evidence and changed files. */
+export function classifyRepair({ failedEvidenceId, changedFiles = [] } = {}) {
+  if (!failedEvidenceId) {
+    return { retryClass: 'unknown', reason: 'repair retry requires a failed evidence reference', retryable: false };
+  }
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return { retryClass: 'unknown', reason: 'repair retry requires changed files', retryable: false };
+  }
+  return { retryClass: 'repair', reason: 'code/config repair followed by a rerun', retryable: true, failedEvidenceId, changedFiles };
+}
+
+/**
+ * Run a command and capture bounded output. Never buffers unbounded output:
+ * output beyond `maxInlineBytes` is written to an artifact.
+ *
+ * Returns `{ exitCode, signal, timedOut, stdout, stderr, durationMs, outputBytes, artifactPath, artifactHash, preview }`.
+ */
+export function runCommand(command, {
+  cwd = process.cwd(),
+  env = {},
+  timeoutMs = 30 * 60 * 1000,
+  maxInlineBytes = 64 * 1024,
+  previewBytes = 4 * 1024,
+  artifactDir = null,
+  shell = true,
+  spawnImpl = spawn,
+} = {}) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    let child;
+    try {
+      child = spawnImpl(command, { cwd, env: { ...process.env, ...env }, shell, windowsHide: true });
+    } catch (err) {
+      resolve({
+        exitCode: null, signal: null, timedOut: false, stdout: '', stderr: '',
+        durationMs: Date.now() - startedAt, outputBytes: 0, artifactPath: null,
+        artifactHash: null, preview: '', errorMessage: err.message,
+      });
+      return;
+    }
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let timedOut = false;
+    let finished = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+    }, timeoutMs);
+
+    child.stdout?.on('data', (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes <= maxInlineBytes) stdoutChunks.push(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes <= maxInlineBytes) stderrChunks.push(chunk);
+    });
+
+    const finish = (exitCode, signal, errorMessage = '') => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      const durationMs = Date.now() - startedAt;
+      const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+      const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+      const outputBytes = stdoutBytes + stderrBytes;
+
+      let artifactPath = null;
+      let artifactHash = null;
+      if (outputBytes > maxInlineBytes && artifactDir) {
+        try {
+          mkdirSync(artifactDir, { recursive: true });
+          const full = join(artifactDir, `output-${newId()}.log`);
+          // Redact before persisting: the artifact must never contain secrets,
+          // even though the in-memory copy is kept raw for classification.
+          const body = redactString(`${stdout}\n${stderr}`);
+          writeFileSync(full, body, 'utf-8');
+          artifactPath = full;
+          // Hash covers the exact persisted (redacted) bytes.
+          artifactHash = sha256Bytes(Buffer.from(body, 'utf-8'));
+        } catch {
+          artifactPath = null;
+        }
+      }
+      const preview = redactString((stdout + stderr).slice(0, previewBytes));
+      resolve({
+        exitCode, signal, timedOut, stdout, stderr, durationMs, outputBytes,
+        artifactPath, artifactHash, preview, errorMessage,
+      });
+    };
+
+    child.on('error', (err) => finish(null, null, err.message));
+    child.on('close', (code, signal) => finish(code, signal));
+  });
+}
+
+/**
+ * Build a verification command descriptor for a gate.
+ * Project-specific commands (analyzer/compile/test) come from `.cadet/harness.json`.
+ */
+export function commandForGate(gate, { projectPath = '.', policy = null, unityAvailable = false } = {}) {
+  switch (gate) {
+    case 'testsPassed':
+      return policy?.testCommand
+        ? { command: policy.testCommand, tool: 'test', automated: true }
+        : { command: 'npm test', tool: 'test', automated: true };
+    case 'compileCheckConfirmed':
+      if (policy?.compileCommand) {
+        return { command: policy.compileCommand, tool: 'unity-build', automated: true };
+      }
+      if (unityAvailable) {
+        return {
+          command: `unity build ${projectPath} --target StandaloneWindows64 -o "${join(projectPath, 'Temp', 'cadet-build')}" --format json`,
+          tool: 'unity-build',
+          automated: true,
+        };
+      }
+      return { command: null, tool: 'manual-confirmation', automated: false, reason: 'Unity CLI unavailable' };
+    case 'unityAnalyzerClean':
+      if (policy?.analyzerCommand) {
+        return {
+          command: `unity run ${projectPath} --command ${policy.analyzerCommand} --format json`,
+          tool: 'unity-analyzer',
+          automated: true,
+        };
+      }
+      return { command: null, tool: 'unity-analyzer', automated: false, reason: 'analyzer command not declared in .cadet/harness.json' };
+    default:
+      return { command: null, tool: 'agent-owned', automated: false, reason: `${gate} is agent-owned` };
+  }
+}
+
+/** Detect zero `UNT*` diagnostics in a Unity analyzer JSON envelope. */
+export function analyzerClean(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    const text = JSON.stringify(parsed);
+    return !/UNT\d+/.test(text);
+  } catch {
+    // Non-JSON: treat any UNT token in the raw text as a finding.
+    return !/UNT\d+/.test(stdout);
+  }
+}
+
+/**
+ * The verification loop contract (contract §6). Runs a command once, classifies,
+ * retries only when the class is retryable and budget remains, and records every
+ * attempt. No attempt ever overwrites a previous one.
+ *
+ * `runner` is injectable for tests: `async (attempt) => { exitCode, ... }`.
+ */
+export async function runVerificationLoop({
+  gate,
+  command,
+  workItemId,
+  phase,
+  acceptanceCriterionId = null,
+  relevantFiles = [],
+  criteria = [],
+  rootDir = process.cwd(),
+  policy,
+  budgets,
+  runCommandImpl = runCommand,
+  sleepImpl = (ms) => new Promise((r) => setTimeout(r, ms)),
+  maxAttemptsOverride = null,
+  tool = 'test',
+  maxInlineBytes,
+  previewBytes,
+  artifactDir = null,
+  flakySignatures = DEFAULT_FLAKY_SIGNATURES,
+  priorEvidence = [],
+  requireRedFirst = null,
+  now = () => new Date(),
+} = {}) {
+  const tracker = budgets || new BudgetTracker(policy);
+  const attempts = [];
+  const inputTreeHash = computeInputTreeHash(rootDir, relevantFiles);
+  const criteriaHash = hashCriteria(criteria);
+  const perStepLimit = maxAttemptsOverride ?? (policy?.budgets?.maxRetriesPerStep?.hard ?? 2) + 1;
+
+  // Red-before-green: a testable gate must not be satisfied by green evidence
+  // unless a prior failed (red) record exists for the same work item and gate.
+  // `requireRedFirst` may be set explicitly; otherwise it applies to
+  // `testsPassed` by default.
+  const redFirstRequired = requireRedFirst === null ? gate === 'testsPassed' : requireRedFirst === true;
+  const priorRed = Array.isArray(priorEvidence)
+    && priorEvidence.some((e) => e && e.gate === gate && e.workItemId === workItemId && e.status === 'failed');
+
+  let lastResult = null;
+  let stopped = false;
+
+  for (let attempt = 1; attempt <= perStepLimit; attempt++) {
+    const startedAt = now();
+    const result = await runCommandImpl(command, { cwd: rootDir, timeoutMs: policy?.budgets?.maxWallClockMs?.hard, maxInlineBytes, previewBytes, artifactDir });
+    tracker.add('toolCalls', 1);
+    tracker.add('wallClockMs', result.durationMs || 0);
+    // Command output counts against the output-token budget (estimated from the
+    // UTF-8 byte length), so the output budget is enforced rather than advisory.
+    const bytesPerToken = policy?.estimation?.bytesPerToken || 3;
+    tracker.add('outputTokens', Math.ceil((result.outputBytes || 0) / bytesPerToken));
+
+    // Hard budgets are enforceable, not advisory: if this attempt pushed a hard
+    // limit (tool calls, wall-clock, output tokens, cost), stop immediately and
+    // never report a passing gate.
+    const hardStop = evaluateHardStop(tracker, { policy });
+
+    const classification = classifyResult({ ...result, flakySignatures });
+    const passed = result.exitCode === 0 && !result.timedOut;
+    let gatePassed = passed;
+    if (gate === 'unityAnalyzerClean' && passed) {
+      gatePassed = analyzerClean(result.stdout);
+    }
+    // A gate can never be satisfied when a hard budget was exceeded, or when a
+    // configured budget (e.g. cost) could not be measured.
+    if (hardStop.exhausted || hardStop.blocked) gatePassed = false;
+
+    const evidence = createEvidence({
+      evidenceId: newId(),
+      workItemId,
+      acceptanceCriterionId,
+      phase,
+      gate,
+      status: hardStop.exhausted || hardStop.blocked
+        ? 'blocked'
+        : (gatePassed ? 'passed' : (result.timedOut ? 'blocked' : 'failed')),
+      command,
+      result: hardStop.exhausted
+        ? `budget-exhausted: ${hardStop.reason}`
+        : (hardStop.blocked ? `budget-blocked: ${hardStop.reason}` : describeResult(result)),
+      exitCode: result.exitCode,
+      artifactPath: result.artifactPath,
+      artifactHash: result.artifactHash,
+      inputTreeHash,
+      criteriaHash,
+      relevantFiles,
+      createdAt: startedAt,
+      source: 'automated',
+    });
+
+    attempts.push({
+      attempt,
+      spanId: newId(),
+      tool,
+      command,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      outputBytes: result.outputBytes,
+      artifactPath: result.artifactPath,
+      artifactHash: result.artifactHash,
+      status: result.timedOut ? 'timed-out' : (gatePassed ? 'passed' : 'failed'),
+      retryClass: classification.retryClass,
+      retryReason: classification.reason,
+      evidence,
+    });
+
+    lastResult = result;
+
+    if (hardStop.exhausted || hardStop.blocked) {
+      return finalize({
+        status: 'failed',
+        attempts,
+        tracker,
+        inputTreeHash,
+        criteriaHash,
+        stopReason: hardStop.exhausted ? 'budget-exhausted' : 'budget-blocked',
+        diagnostic: hardStop.reason,
+      });
+    }
+
+    if (gatePassed) {
+      // Enforce red-before-green for testable gates. A red record may come from
+      // prior state or from an earlier failed attempt in this same loop.
+      const inLoopRed = attempts.slice(0, -1).some((a) => a.status === 'failed');
+      if (redFirstRequired && !priorRed && !inLoopRed) {
+        return finalize({
+          status: 'failed',
+          attempts,
+          tracker,
+          inputTreeHash,
+          criteriaHash,
+          stopReason: 'red-required',
+          diagnostic: 'a failing (red) record is required before a green testsPassed result; run the test against the unimplemented behavior first',
+        });
+      }
+      return finalize({ status: 'passed', attempts, tracker, inputTreeHash, criteriaHash });
+    }
+    if (result.timedOut) {
+      if (classification.retryable && tracker.checkStepRetries(attempt - 1).status !== 'exhausted') {
+        // fall through to retry
+      } else {
+        return finalize({ status: 'timed-out', attempts, tracker, inputTreeHash, criteriaHash });
+      }
+    }
+    if (!classification.retryable) {
+      return finalize({
+        status: 'failed',
+        attempts,
+        tracker,
+        inputTreeHash,
+        criteriaHash,
+        stopReason: classification.retryClass,
+        diagnostic: classification.reason,
+      });
+    }
+
+    // Retryable — check both the per-step and total retry budgets.
+    // `attempt` counts executions; retries performed so far = attempt - 1.
+    const stepCheck = tracker.checkStepRetries(attempt - 1);
+    if (stepCheck.status === 'exhausted') {
+      return finalize({ status: 'failed', attempts, tracker, inputTreeHash, criteriaHash, stopReason: 'retry-exhausted', diagnostic: 'retry budget exhausted' });
+    }
+    const runCheck = tracker.check('retries');
+    if (runCheck.status === 'exhausted') {
+      return finalize({ status: 'failed', attempts, tracker, inputTreeHash, criteriaHash, stopReason: 'retry-exhausted', diagnostic: 'total retry budget exhausted' });
+    }
+    const timeCheck = tracker.check('wallClockMs');
+    if (timeCheck.status === 'exhausted') {
+      return finalize({ status: 'failed', attempts, tracker, inputTreeHash, criteriaHash, stopReason: 'budget-exhausted', diagnostic: 'wall-clock budget exhausted' });
+    }
+
+    tracker.add('retries', 1);
+    const backoff = TRANSIENT_BACKOFF_MS[Math.min(attempt - 1, TRANSIENT_BACKOFF_MS.length - 1)];
+    if (attempt < perStepLimit) {
+      await sleepImpl(backoff);
+    }
+    stopped = false;
+  }
+
+  return finalize({
+    status: 'failed',
+    attempts,
+    tracker,
+    inputTreeHash,
+    criteriaHash,
+    stopReason: 'retry-exhausted',
+    diagnostic: 'retry limit reached',
+  });
+}
+
+function describeResult(result) {
+  if (result.timedOut) return 'timed-out';
+  if (result.exitCode === 0) return 'exit 0';
+  return `exit ${result.exitCode}`;
+}
+
+function finalize({ status, attempts, tracker, inputTreeHash, criteriaHash, stopReason = null, diagnostic = null }) {
+  const flattened = ['passed', 'flaky'].includes(status) ? status : status;
+  return {
+    status,
+    ok: status === 'passed',
+    gateSatisfied: status === 'passed',
+    stopReason,
+    diagnostic,
+    attempts,
+    evidence: attempts.map((a) => a.evidence),
+    finalEvidence: attempts.length ? attempts[attempts.length - 1].evidence : null,
+    inputTreeHash,
+    criteriaHash,
+    budget: tracker.result(),
+  };
+}
+
+/**
+ * Build a manual-confirmation evidence record when automation is unavailable.
+ * Recorded as a user-owned decision, never imitated as automated evidence.
+ */
+export function manualConfirmation({
+  gate, workItemId, phase, projectPath, editorVersion, scope, acceptanceCriterionId = null,
+  relevantFiles = [], criteria = [], rootDir = process.cwd(), approvedBy = 'user', at = new Date(),
+} = {}) {
+  const inputTreeHash = computeInputTreeHash(rootDir, relevantFiles);
+  const evidence = createEvidence({
+    evidenceId: newId(),
+    workItemId,
+    acceptanceCriterionId,
+    phase,
+    gate,
+    status: 'manual-confirmation',
+    command: null,
+    result: `manual confirmation: project=${projectPath} editor=${editorVersion} scope=${scope}`,
+    exitCode: null,
+    inputTreeHash,
+    criteriaHash: hashCriteria(criteria),
+    relevantFiles,
+    createdAt: at,
+    source: 'manual-confirmation',
+  });
+  return { evidence, approvedBy, projectPath, editorVersion, scope, recordedAt: timestamp(at) };
+}
+
+/** Convenience: is the verification result an exhaustion that must not read as success? */
+export function isBudgetExhaustion(result) {
+  return result?.stopReason === 'budget-exhausted';
+}
+
+export { budgetExhaustedResult };