codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14.1

package/src/gateway-handshake.ts

@@ -0,0 +1,95 @@
+import { PROTOCOL_VERSION, STATE_SCHEMA_VERSION } from './contracts.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+
+export interface GatewayHandshake {
+  packageName: typeof PACKAGE_NAME;
+  packageVersion: typeof PACKAGE_VERSION;
+  protocolVersion: typeof PROTOCOL_VERSION;
+  stateSchemaVersion: typeof STATE_SCHEMA_VERSION;
+  capabilities: string[];
+}
+
+export function gatewayHandshake(): GatewayHandshake {
+  return {
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    stateSchemaVersion: STATE_SCHEMA_VERSION,
+    capabilities: workflowCapabilities(),
+  };
+}
+
+export function workflowCapabilities(): string[] {
+  return [
+    'project-memory-v1',
+    'graph-binding-v1',
+    'local-state-v1',
+    'milestone-lifecycle-v1',
+    'milestone-human-final-gate-v1',
+    'delegated-approval-v1',
+    'task-knowledge-rebind-v1',
+    'task-context-refresh-v1',
+    'corrective-plan-audit-v1',
+    'safe-update-preflight-v1',
+    'bounded-dependency-provenance-recovery-v1',
+    'task-local-dependency-provenance-recovery-v1',
+    'root-cause-corrective-replan-dirty-carryover-v1',
+    'stop-override-context-rebind-v1',
+    'stop-override-context-rebind-chain-v1',
+    'stop-override-post-audit-dependency-revision-v1',
+    'retained-reviewed-history-recovery-v1',
+    'historical-step-provenance-recovery-v1',
+    'milestone-progress-projection-v1',
+    'bounded-plan-integrity-recovery-v1',
+    'check-support-scope-augmentation-v1',
+    'historical-check-support-scope-adoption-v1',
+    'historical-check-support-dirty-carryover-v1',
+    'downstream-proof-predecessor-recovery-v1',
+    'active-downstream-proof-dependency-recovery-v1',
+    'task-mechanical-feasibility-v1',
+    'task-human-gate-lease-release-v1',
+    'strict-reviewer-v1',
+    'legacy-snapshot-v1',
+    'plan-risk-audit-sidecar-v1',
+    'step-strict-review-sidecar-v1',
+    'step-remediation-circuit-breaker-sidecar-v1',
+    'milestone-scope-change-sidecar-v1',
+    'milestone-membership-integrity-v1',
+    'milestone-task-dependency-dag-v1',
+    'milestone-initial-plan-transaction-v1',
+    'task-c1-handoff-sidecar-v1',
+    'semantic-plan-risk-audit-v2',
+    'guarded-remediation-continuation-v1',
+    'cause-bound-rolling-refinement-v1',
+    'failed-step-continuation-transaction-v1',
+    'host-safe-credential-reference-v1',
+    'structural-production-edge-contract-v1',
+    'structural-production-edge-authority-v1',
+    'observed-route-matrix-v2',
+    'compact-status-v1',
+    'reviewer-runtime-preflight-v1',
+    'explicit-review-mode-v1',
+    'app-owned-operational-preflight-v1',
+    'milestone-reverse-membership-integrity-v1',
+    'task-c1-handoff-bundle-v2',
+    'alpha6-adoption-posture-v1',
+    'milestone-initial-assembly-v1',
+    'milestone-initial-assembly-navigation-v2',
+    'milestone-autonomy-contract-v1',
+    'milestone-autonomy-content-refresh-v1',
+    'milestone-autonomous-membership-evolution-v1',
+    'audited-remediation-topology-v1',
+    'audited-remediation-dependency-knowledge-refresh-v1',
+    'corrective-derived-task-authority-v1',
+    'task-c1-derived-worker-actor-v1',
+    'guarded-corrective-auditor-routing-v1',
+    'corrective-decision-context-recovery-v1',
+    'plan-proof-obligations-v1',
+    'structural-task-replacement-disabled-v1',
+    'project-composite-transaction-journal-v1',
+    'corrective-yield-journal-v1',
+    'corrective-replan-journal-v1',
+    'corrective-replan-human-gate-v1',
+    'corrective-replan-protocol-v2',
+  ];
+}

package/src/git.ts

@@ -0,0 +1,183 @@
+import { spawnSync } from 'node:child_process';
+import { WorkflowError } from './errors.js';
+import { runCheckCommands, type CheckExecutionOptions } from './checks/runner.js';
+import { changedFiles, currentBranch, headCommit, isClean, runGit } from './repository.js';
+import { pathAllowed } from './domain/validation.js';
+import type { TaskState } from './contracts.js';
+
+const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'staging', 'production']);
+
+export function startLocalTaskBranch(
+  repositoryRoot: string,
+  branch: string,
+  baseBranch: string,
+  expectedBaseCommit: string | null = null,
+): string {
+  if (!isClean(repositoryRoot)) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Task start requires a clean checkout.', {
+      changedFiles: changedFiles(repositoryRoot),
+    });
+  }
+  if (PROTECTED_BRANCHES.has(branch)) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Task branch is protected: ${branch}`);
+  }
+  const baseCommit = runGit(repositoryRoot, ['rev-parse', baseBranch]);
+  if (expectedBaseCommit !== null && baseCommit !== expectedBaseCommit) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Task start base moved after execution authorization.', {
+      baseBranch,
+      authorizedBaseCommit: expectedBaseCommit,
+      currentBaseCommit: baseCommit,
+    });
+  }
+  runGit(repositoryRoot, ['switch', '-c', branch, baseBranch]);
+  return baseCommit;
+}
+
+export interface CheckResult {
+  command: string;
+  passed: boolean;
+  exitCode: number;
+  output: string;
+}
+
+/** Only ordinary exited checks can enter product failure/remediation evidence. */
+export function runChecks(repositoryRoot: string, commands: string[], options: CheckExecutionOptions = {}): CheckResult[] {
+  const configured: CheckExecutionOptions = { ...options };
+  const envNumber = (name: string): number | undefined => {
+    const value = process.env[name];
+    if (value === undefined) return undefined;
+    const parsed = Number(value);
+    if (!value.trim() || !Number.isSafeInteger(parsed) || parsed <= 0) {
+      throw new WorkflowError('INVALID_ARGUMENT', `${name} must be a positive integer.`);
+    }
+    return parsed;
+  };
+  if (configured.timeoutMs === undefined) {
+    const value = envNumber('CODEX_WORKFLOW_CHECK_TIMEOUT_MS');
+    if (value !== undefined) configured.timeoutMs = value;
+  }
+  if (configured.totalTimeoutMs === undefined) {
+    const value = envNumber('CODEX_WORKFLOW_CHECK_TOTAL_TIMEOUT_MS');
+    if (value !== undefined) configured.totalTimeoutMs = value;
+  }
+  if (configured.cancellationFile === undefined && process.env.CODEX_WORKFLOW_CHECK_CANCEL_FILE !== undefined) {
+    configured.cancellationFile = process.env.CODEX_WORKFLOW_CHECK_CANCEL_FILE;
+  }
+  const results = runCheckCommands(repositoryRoot, commands, configured);
+  if (results.some(result => result.outcome === 'infra')) {
+    throw new WorkflowError('CHECK_INFRASTRUCTURE_FAILED',
+      'Check execution ended with an infrastructure failure. Product failure and corrective replanning were not inferred.', {
+        checks: results,
+        retryRequiresFreshObservation: true,
+        automaticRetry: false,
+      });
+  }
+  return results.map(result => {
+    if (result.exitCode === null || result.signal !== null || result.error !== null || !result.cleanupComplete) {
+      throw new WorkflowError('CHECK_INFRASTRUCTURE_FAILED', 'Check result lacks a verified ordinary exit.', { checks: results });
+    }
+    return { command: result.command, passed: result.outcome === 'passed', exitCode: result.exitCode, output: result.output };
+  });
+}
+
+export function commitStep(
+  repositoryRoot: string,
+  taskId: string,
+  stepId: string,
+  title: string,
+  allowedWrites: string[],
+): { commitSha: string; files: string[] } {
+  const files = changedFiles(repositoryRoot);
+  if (files.length === 0) throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} has no changed files.`);
+  const unexpected = files.filter((file) => !pathAllowed(file, allowedWrites));
+  if (unexpected.length > 0) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `${stepId} changed files outside allowedWrites.`, { unexpected });
+  }
+  runGit(repositoryRoot, ['add', '--', ...files]);
+  runGit(repositoryRoot, [
+    'commit',
+    '-m',
+    `${taskId}/${stepId}: ${title}`,
+    '-m',
+    `Task: ${taskId}\nStep: ${stepId}`,
+  ]);
+  return { commitSha: headCommit(repositoryRoot), files };
+}
+
+export function mergeTaskBranch(repositoryRoot: string, taskBranch: string, baseBranch: string): string {
+  if (!isClean(repositoryRoot)) throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Merge requires a clean checkout.');
+  if (currentBranch(repositoryRoot) !== taskBranch) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Expected current task branch ${taskBranch}.`);
+  }
+  runGit(repositoryRoot, ['switch', baseBranch]);
+  const result = spawnSync('git', ['-C', repositoryRoot, 'merge', '--no-ff', taskBranch, '-m', `${taskBranch}: merge task`], {
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    spawnSync('git', ['-C', repositoryRoot, 'merge', '--abort'], { encoding: 'utf8' });
+    runGit(repositoryRoot, ['switch', taskBranch]);
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Merge conflict while merging ${taskBranch}.`, {
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    });
+  }
+  return headCommit(repositoryRoot);
+}
+
+export function syncBaseIntoTask(
+  repositoryRoot: string,
+  taskBranch: string,
+  baseBranch: string,
+): { baseCommit: string; syncCommit: string } {
+  if (!isClean(repositoryRoot)) throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Base sync requires a clean checkout.');
+  if (currentBranch(repositoryRoot) !== taskBranch) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Expected current task branch ${taskBranch}.`);
+  }
+  const result = spawnSync('git', ['-C', repositoryRoot, 'merge', '--no-edit', baseBranch], { encoding: 'utf8' });
+  if (result.status !== 0) {
+    const abort = spawnSync('git', ['-C', repositoryRoot, 'merge', '--abort'], { encoding: 'utf8' });
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', `Base sync conflict from ${baseBranch}.`, {
+      cleanAbortVerified: abort.status === 0 && isClean(repositoryRoot),
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    });
+  }
+  return {
+    baseCommit: runGit(repositoryRoot, ['rev-parse', baseBranch]),
+    syncCommit: headCommit(repositoryRoot),
+  };
+}
+
+export function validateTaskHistory(
+  repositoryRoot: string,
+  task: TaskState,
+  historyBoundary = 'HEAD',
+): void {
+  if (!task.baseCommit) throw new WorkflowError('STATE_CORRUPT', `Task ${task.id} has no base commit.`);
+  const boundaryCommit = runGit(repositoryRoot, ['rev-parse', historyBoundary]);
+  const actualOutput = runGit(repositoryRoot, ['rev-list', '--reverse', `${task.baseCommit}..${boundaryCommit}`]);
+  const actual = actualOutput ? actualOutput.split('\n') : [];
+  const expected = [...new Set([
+    ...task.steps.flatMap((step) => (step.evidence ? [step.evidence.commitSha] : [])),
+    ...task.systemCommits,
+    ...(task.invalidatedStepCommits ?? []),
+    ...(task.historicalStepProvenanceRecoveries ?? []).map((recovery) => recovery.commitSha),
+    ...(task.dependencyProvenanceRecoveries ?? []).flatMap((recovery) => recovery.retainedHistoricalCommits ?? []),
+  ])];
+  const missing = expected.filter((commit) => !actual.includes(commit));
+  const unexpected = actual.filter((commit) => !expected.includes(commit));
+  if (missing.length > 0 || unexpected.length > 0 || actual.length !== expected.length) {
+    throw new WorkflowError(
+      'GIT_PRECONDITION_FAILED',
+      'Task branch history contains commits not recorded by Workflow V2. Workers must leave Step changes uncommitted and let task step-complete create the commit. Stop and request coordinator-led Git recovery; do not create another commit or edit workflow state.',
+      {
+        missing,
+        unexpected,
+        baseCommit: task.baseCommit,
+        headCommit: headCommit(repositoryRoot),
+        historyBoundary: boundaryCommit,
+        recovery: 'Restore the pre-commit working changes under coordinator control, then invoke task step-complete.',
+      },
+    );
+  }
+}

package/src/graph.ts

@@ -0,0 +1,342 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STATE_SCHEMA_VERSION, PROTOCOL_VERSION } from './contracts.js';
+import type {
+  GraphBinding,
+  GraphBindingSnapshot,
+  GraphKind,
+  GraphMode,
+  GraphRefreshEvidence,
+  GraphRefreshRequest,
+} from './contracts.js';
+import { WorkflowError } from './errors.js';
+import { writeJsonAtomic } from './fs-utils.js';
+import { headCommit } from './repository.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+
+export interface GraphManifest {
+  packageName: string;
+  packageVersion: string;
+  protocolVersion: number;
+  stateSchemaVersion: number;
+  createdAt: string;
+  files: Array<{ path: string; sha256: string }>;
+}
+
+const WORKFLOW_GRAPH_SOURCE_ROOTS = ['src', 'roles', 'references', 'schemas', 'plugins/codex-workflow-gateway'] as const;
+
+export function graphViewRoot(): string {
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(codexHome, 'workflow-cache', 'codex-workflow', PACKAGE_VERSION);
+}
+
+export function prepareGraphView(target = graphViewRoot()): { root: string; manifest: GraphManifest } {
+  const packageRoot = resolvePackageRoot();
+  const temporary = `${target}.tmp-${randomUUID()}`;
+  rmSync(temporary, { recursive: true, force: true });
+  mkdirSync(temporary, { recursive: true, mode: 0o700 });
+  try {
+    for (const relative of ['dist/src', 'roles', 'references', 'schemas']) {
+      const source = path.join(packageRoot, relative);
+      if (!existsSync(source)) {
+        throw new WorkflowError('NOT_FOUND', `Graph source is missing from package: ${relative}`);
+      }
+      copyTreeWithoutSymlinks(source, path.join(temporary, relative));
+    }
+    const files = listFiles(temporary).map((file) => ({
+      path: path.relative(temporary, file).replaceAll('\\', '/'),
+      sha256: createHash('sha256').update(readFileSync(file)).digest('hex'),
+    }));
+    const manifest: GraphManifest = {
+      packageName: PACKAGE_NAME,
+      packageVersion: PACKAGE_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
+      stateSchemaVersion: STATE_SCHEMA_VERSION,
+      createdAt: new Date().toISOString(),
+      files,
+    };
+    writeJsonAtomic(path.join(temporary, 'manifest.json'), manifest);
+    rmSync(target, { recursive: true, force: true });
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    renameSync(temporary, target);
+    return { root: target, manifest };
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+export function inspectGraphView(target = graphViewRoot()): { present: boolean; current: boolean; root: string } {
+  const manifestFile = path.join(target, 'manifest.json');
+  if (!existsSync(manifestFile)) return { present: false, current: false, root: target };
+  try {
+    const manifest = JSON.parse(readFileSync(manifestFile, 'utf8')) as GraphManifest;
+    return {
+      present: true,
+      current:
+        manifest.packageName === PACKAGE_NAME &&
+        manifest.packageVersion === PACKAGE_VERSION &&
+        manifest.protocolVersion === PROTOCOL_VERSION &&
+        manifest.stateSchemaVersion === STATE_SCHEMA_VERSION,
+      root: target,
+    };
+  } catch {
+    return { present: true, current: false, root: target };
+  }
+}
+
+export function createGraphRefreshRequest(
+  repositoryRoot: string,
+  projectId: string,
+  graphKind: GraphKind,
+  mode: GraphMode = 'moderate',
+  now: Date = new Date(),
+): GraphRefreshRequest {
+  if (graphKind === 'product') {
+    const sourceRoot = path.resolve(repositoryRoot);
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      requestId: randomUUID(),
+      projectId,
+      graphKind,
+      sourceRoot,
+      rootFingerprint: createHash('sha256').update(`${projectId}\0${sourceRoot}`).digest('hex'),
+      indexedHead: headCommit(sourceRoot),
+      packageVersion: null,
+      manifestHash: null,
+      mode,
+      persistence: false,
+      issuedAt: now.toISOString(),
+    };
+  }
+  const packageRoot = resolvePackageRoot();
+  const manifest = workflowPackageGraphManifest(packageRoot, now);
+  const manifestHash = hashGraphManifest(manifest);
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    requestId: randomUUID(),
+    projectId,
+    graphKind,
+    sourceRoot: packageRoot,
+    rootFingerprint: createHash('sha256').update(`${PACKAGE_NAME}\0${PACKAGE_VERSION}\0${manifestHash}`).digest('hex'),
+    indexedHead: null,
+    packageVersion: PACKAGE_VERSION,
+    manifestHash,
+    mode,
+    persistence: false,
+    issuedAt: now.toISOString(),
+  };
+}
+
+function workflowPackageGraphManifest(packageRoot: string, now: Date): GraphManifest {
+  const files = WORKFLOW_GRAPH_SOURCE_ROOTS.flatMap((relative) => {
+    const source = path.join(packageRoot, relative);
+    if (!existsSync(source)) {
+      throw new WorkflowError('NOT_FOUND', `Workflow graph source is missing from package: ${relative}`);
+    }
+    return listFiles(source).map((file) => ({
+      path: path.relative(packageRoot, file).replaceAll('\\', '/'),
+      sha256: createHash('sha256').update(readFileSync(file)).digest('hex'),
+    }));
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    stateSchemaVersion: STATE_SCHEMA_VERSION,
+    createdAt: now.toISOString(),
+    files,
+  };
+}
+
+export function bindGraphEvidence(
+  projectId: string,
+  request: GraphRefreshRequest,
+  evidence: GraphRefreshEvidence,
+  existing: GraphBinding | null,
+  now: Date = new Date(),
+): GraphBinding {
+  validateGraphEvidence(request, evidence);
+  const timestamp = now.toISOString();
+  const snapshot: GraphBindingSnapshot = {
+    projectKey: evidence.projectKey,
+    rootFingerprint: evidence.rootFingerprint,
+    indexedHead: evidence.indexedHead,
+    packageVersion: evidence.packageVersion,
+    manifestHash: evidence.manifestHash,
+    mode: evidence.mode,
+    status: evidence.status,
+    nodeCount: evidence.nodeCount,
+    edgeCount: evidence.edgeCount,
+    observedAt: evidence.observedAt,
+    evidenceHash: createHash('sha256').update(JSON.stringify(evidence)).digest('hex'),
+    fallbackReason: null,
+  };
+  const retainPrevious = request.graphKind === 'workflow' && existing?.packageVersion !== snapshot.packageVersion;
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    revision: existing?.revision ?? 0,
+    id: `GRAPH-${request.graphKind}`,
+    projectId,
+    createdAt: existing?.createdAt ?? timestamp,
+    updatedAt: timestamp,
+    kind: 'graph-binding',
+    graphKind: request.graphKind,
+    provider: 'codebase-memory-mcp',
+    ...snapshot,
+    previous: retainPrevious && existing ? graphSnapshot(existing) : existing?.previous ?? null,
+  };
+}
+
+export function fallbackGraphBinding(
+  projectId: string,
+  request: GraphRefreshRequest,
+  reason: string,
+  existing: GraphBinding | null,
+  now: Date = new Date(),
+): GraphBinding {
+  if (!reason.trim()) throw new WorkflowError('INVALID_ARGUMENT', 'Graph fallback requires a reason.');
+  const timestamp = now.toISOString();
+  const evidenceHash = createHash('sha256')
+    .update(JSON.stringify({ requestId: request.requestId, reason: reason.trim(), observedAt: timestamp }))
+    .digest('hex');
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    revision: existing?.revision ?? 0,
+    id: `GRAPH-${request.graphKind}`,
+    projectId,
+    createdAt: existing?.createdAt ?? timestamp,
+    updatedAt: timestamp,
+    kind: 'graph-binding',
+    graphKind: request.graphKind,
+    provider: 'codebase-memory-mcp',
+    projectKey: existing?.projectKey ?? null,
+    rootFingerprint: request.rootFingerprint,
+    indexedHead: request.indexedHead,
+    packageVersion: request.packageVersion,
+    manifestHash: request.manifestHash,
+    mode: request.mode,
+    status: 'fallback',
+    nodeCount: existing?.nodeCount ?? null,
+    edgeCount: existing?.edgeCount ?? null,
+    observedAt: timestamp,
+    evidenceHash,
+    fallbackReason: reason.trim(),
+    previous: existing?.previous ?? null,
+  };
+}
+
+export function inspectGraphBinding(binding: GraphBinding, request: GraphRefreshRequest): GraphBinding {
+  const stale =
+    binding.rootFingerprint !== request.rootFingerprint ||
+    binding.mode !== request.mode ||
+    binding.indexedHead !== request.indexedHead ||
+    binding.packageVersion !== request.packageVersion ||
+    binding.manifestHash !== request.manifestHash;
+  return stale && binding.status === 'ready' ? { ...binding, status: 'stale' } : binding;
+}
+
+export function validateGraphRequestCurrent(request: GraphRefreshRequest, current: GraphRefreshRequest): void {
+  const fields: Array<keyof GraphRefreshRequest> = [
+    'projectId',
+    'graphKind',
+    'sourceRoot',
+    'rootFingerprint',
+    'indexedHead',
+    'packageVersion',
+    'manifestHash',
+    'mode',
+    'persistence',
+  ];
+  const stale = fields.filter((field) => request[field] !== current[field]);
+  if (request.protocolVersion !== PROTOCOL_VERSION || stale.length > 0) {
+    throw new WorkflowError('STATE_CONFLICT', 'Graph refresh request is stale or incompatible.', { stale });
+  }
+}
+
+export function hashGraphManifest(manifest: GraphManifest): string {
+  return createHash('sha256').update(JSON.stringify({
+    packageName: manifest.packageName,
+    packageVersion: manifest.packageVersion,
+    protocolVersion: manifest.protocolVersion,
+    stateSchemaVersion: manifest.stateSchemaVersion,
+    files: manifest.files,
+  })).digest('hex');
+}
+
+function validateGraphEvidence(request: GraphRefreshRequest, evidence: GraphRefreshEvidence): void {
+  const invalid =
+    evidence.requestId !== request.requestId ||
+    evidence.provider !== 'codebase-memory-mcp' ||
+    evidence.rootFingerprint !== request.rootFingerprint ||
+    evidence.indexedHead !== request.indexedHead ||
+    evidence.packageVersion !== request.packageVersion ||
+    evidence.manifestHash !== request.manifestHash ||
+    evidence.mode !== request.mode;
+  if (invalid || !evidence.projectKey.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Graph evidence does not match the refresh request.');
+  }
+}
+
+function graphSnapshot(binding: GraphBinding): GraphBindingSnapshot {
+  return {
+    projectKey: binding.projectKey,
+    rootFingerprint: binding.rootFingerprint,
+    indexedHead: binding.indexedHead,
+    packageVersion: binding.packageVersion,
+    manifestHash: binding.manifestHash,
+    mode: binding.mode,
+    status: binding.status,
+    nodeCount: binding.nodeCount,
+    edgeCount: binding.edgeCount,
+    observedAt: binding.observedAt,
+    evidenceHash: binding.evidenceHash,
+    fallbackReason: binding.fallbackReason,
+  };
+}
+
+function resolvePackageRoot(): string {
+  let cursor = path.dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 4; depth += 1) {
+    const packageFile = path.join(cursor, 'package.json');
+    if (existsSync(packageFile)) {
+      const parsed = JSON.parse(readFileSync(packageFile, 'utf8')) as { name?: string };
+      if (parsed.name === PACKAGE_NAME) return cursor;
+    }
+    cursor = path.dirname(cursor);
+  }
+  throw new WorkflowError('NOT_FOUND', `Cannot resolve installed ${PACKAGE_NAME} package root.`);
+}
+
+function copyTreeWithoutSymlinks(source: string, destination: string): void {
+  const metadata = lstatSync(source);
+  if (metadata.isSymbolicLink()) {
+    throw new WorkflowError('STATE_CORRUPT', `Graph source must not be a symlink: ${source}`);
+  }
+  if (metadata.isDirectory()) {
+    mkdirSync(destination, { recursive: true, mode: 0o700 });
+    for (const entry of readdirSync(source)) {
+      copyTreeWithoutSymlinks(path.join(source, entry), path.join(destination, entry));
+    }
+    return;
+  }
+  copyFileSync(source, destination);
+}
+
+function listFiles(root: string): string[] {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const target = path.join(root, entry.name);
+    return entry.isDirectory() ? listFiles(target) : [target];
+  }).sort();
+}