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

package/src/alpha6/mechanical-feasibility.ts

@@ -0,0 +1,488 @@
+import { spawnSync } from 'node:child_process';
+import type {
+  MechanicalFeasibilityAnalyzer,
+  MechanicalFeasibilityEvidence,
+  MechanicalFeasibilityFinding,
+  TaskState,
+} from '../contracts.js';
+import { pathAllowed } from '../domain/validation.js';
+import { WorkflowError } from '../errors.js';
+import { currentBranch, gitIsAncestor, headCommit, runGit } from '../repository.js';
+import {
+  hasRequiredSelector,
+  inspectRequiredSelectorContract,
+  parseNpmRunCheck,
+} from './npm-check-contract.js';
+import { inspectCheckSupportAnchors } from './check-support-anchor.js';
+import { canonicalJsonStringify, sha256Hex } from './store-sidecars.js';
+
+export const MECHANICAL_FEASIBILITY_ANALYZERS: readonly MechanicalFeasibilityAnalyzer[] = [
+  { analyzerId: 'wf2.root-npm-script', analyzerVersion: 1 },
+  { analyzerId: 'wf2.root-npm-script-arguments', analyzerVersion: 1 },
+  { analyzerId: 'wf2.check-support-anchor', analyzerVersion: 1 },
+  { analyzerId: 'wf2.exact-output-path', analyzerVersion: 1 },
+  { analyzerId: 'wf2.exact-predecessor-path', analyzerVersion: 1 },
+] as const;
+
+const EXACT_PATH = /^path:([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)$/;
+
+interface EvaluationSource {
+  sourceKind: MechanicalFeasibilityEvidence['sourceKind'];
+  sourceBranch: string;
+  evaluatedHead: string;
+  baseCommit: string | null;
+}
+
+export function mechanicalFeasibilityAnalyzerSetHash(): string {
+  return sha256Hex(canonicalJsonStringify({ analyzers: MECHANICAL_FEASIBILITY_ANALYZERS }));
+}
+
+export function mechanicalFeasibilityAnalyzerInputHash(task: TaskState): string {
+  return sha256Hex(canonicalJsonStringify({
+    steps: task.steps.map((step) => ({
+      id: step.id,
+      dependencies: step.dependencies,
+      expectedOutputs: step.expectedOutputs,
+      allowedWrites: step.allowedWrites,
+      checks: step.checks,
+    })),
+  }));
+}
+
+export function hashMechanicalFeasibilityEvidence(evidence: MechanicalFeasibilityEvidence): string {
+  return sha256Hex(canonicalJsonStringify(evidence));
+}
+
+export function evaluateMechanicalFeasibility(
+  repositoryRoot: string,
+  task: TaskState,
+  briefHash: string,
+  planHash: string,
+): MechanicalFeasibilityEvidence {
+  const source = selectEvaluationSource(repositoryRoot, task);
+  const packageJson = readGitPath(repositoryRoot, source.evaluatedHead, 'package.json');
+  const manifest = parseRootManifest(packageJson);
+  const byId = new Map(task.steps.map((step) => [step.id, step]));
+  const findings: MechanicalFeasibilityFinding[] = [];
+
+  for (const step of task.steps) {
+    const predecessorIds = transitivePredecessorIds(step.id, byId);
+    const manifestWriters = [step.id, ...predecessorIds]
+      .filter((stepId) => pathAllowed('package.json', requireStep(byId, stepId).allowedWrites))
+      .sort();
+
+    for (const check of step.checks) {
+      const invocation = parseNpmRunCheck(check);
+      if (!invocation) {
+        findings.push(finding(
+          'wf2.root-npm-script',
+          'unverified',
+          step.id,
+          check,
+          'Check is outside the exact root npm grammar.',
+          'UNSUPPORTED_CHECK_SYNTAX',
+        ));
+        continue;
+      }
+      const script = invocation.script;
+      const scriptCommand = manifest.scripts.get(script) ?? null;
+      if (scriptCommand !== null) {
+        findings.push(finding(
+          'wf2.root-npm-script',
+          'pass',
+          step.id,
+          check,
+          `Root package.json at ${source.evaluatedHead} declares script ${script}.`,
+          'ROOT_NPM_SCRIPT_PRESENT',
+        ));
+        const selectorContract = inspectRequiredSelectorContract(
+          scriptCommand,
+          (runnerPath) => readGitPath(repositoryRoot, source.evaluatedHead, runnerPath),
+        );
+        if (selectorContract) {
+          const runnerWriters = [step.id, ...predecessorIds]
+            .filter((stepId) => pathAllowed(selectorContract.runnerPath, requireStep(byId, stepId).allowedWrites))
+            .sort();
+          if (hasRequiredSelector(invocation.forwardedArguments)) {
+            findings.push(finding(
+              'wf2.root-npm-script-arguments',
+              'pass',
+              step.id,
+              check,
+              `Repository-local affected runner ${selectorContract.runnerPath} receives an explicit base, head, or files selector.`,
+              'ROOT_NPM_SCRIPT_REQUIRED_SELECTOR_PRESENT',
+            ));
+          } else if (runnerWriters.length > 0) {
+            findings.push(finding(
+              'wf2.root-npm-script-arguments',
+              'unverified',
+              step.id,
+              check,
+              `Repository-local affected runner ${selectorContract.runnerPath} currently requires a selector but is writable by ${runnerWriters.join(', ')}.`,
+              'ROOT_NPM_SCRIPT_REQUIRED_SELECTOR_MAY_CHANGE',
+            ));
+          } else {
+            findings.push(finding(
+              'wf2.root-npm-script-arguments',
+              'blocked',
+              step.id,
+              check,
+              `Repository-local affected runner ${selectorContract.runnerPath} requires --base, --head, or --files, but the check forwards no selector and no responsible Step may change the runner.`,
+              'ROOT_NPM_SCRIPT_REQUIRED_SELECTOR_MISSING',
+            ));
+          }
+        }
+        const supportConflicts = inspectCheckSupportAnchors({
+          step,
+          scripts: manifest.scripts,
+          readFile: (relativePath) => {
+            const content = readGitPath(repositoryRoot, source.evaluatedHead, relativePath);
+            return { content, hash: content === null ? null : sha256Hex(content) };
+          },
+          pathExists: (relativePath) => gitPathExists(repositoryRoot, source.evaluatedHead, relativePath),
+        });
+        for (const conflict of supportConflicts) {
+          findings.push(finding(
+            'wf2.check-support-anchor',
+            'blocked',
+            step.id,
+            check,
+            `${conflict.runnerPath} directly imports checksum/catalog authority ${conflict.supportPath}; absent output ${conflict.expectedOutputPaths.join(', ')} requires that support authority to change, but ${step.id} cannot write it.`,
+            conflict.reasonCode,
+          ));
+        }
+        continue;
+      }
+      if (manifestWriters.length > 0) {
+        findings.push(finding(
+          'wf2.root-npm-script',
+          'unverified',
+          step.id,
+          check,
+          `Script ${script} is absent at ${source.evaluatedHead}; package.json is writable by ${manifestWriters.join(', ')}.`,
+          'ROOT_NPM_SCRIPT_MAY_BE_CREATED',
+        ));
+        continue;
+      }
+      findings.push(finding(
+        'wf2.root-npm-script',
+        'blocked',
+        step.id,
+        check,
+        manifest.state === 'valid'
+          ? `Script ${script} is absent from root package.json at ${source.evaluatedHead}, and no responsible Step may write package.json.`
+          : `Root package.json is ${manifest.state} at ${source.evaluatedHead}, and no responsible Step may write package.json.`,
+        manifest.state === 'valid' ? 'ROOT_NPM_SCRIPT_MISSING' : `ROOT_PACKAGE_JSON_${manifest.state.toUpperCase()}`,
+      ));
+    }
+
+    for (const output of step.expectedOutputs) {
+      const relativePath = decodeExactPath(output);
+      if (relativePath === null) {
+        findings.push(finding(
+          'wf2.exact-output-path',
+          'unverified',
+          step.id,
+          output,
+          'Expected output is outside the exact path:<repository-relative POSIX path> grammar.',
+          'UNSUPPORTED_OUTPUT_SYNTAX',
+        ));
+        continue;
+      }
+      if (gitPathExists(repositoryRoot, source.evaluatedHead, relativePath)) {
+        findings.push(finding(
+          'wf2.exact-output-path',
+          'pass',
+          step.id,
+          output,
+          `${relativePath} exists at ${source.evaluatedHead}.`,
+          'EXACT_OUTPUT_PRESENT',
+        ));
+        continue;
+      }
+      if (pathAllowed(relativePath, step.allowedWrites)) {
+        findings.push(finding(
+          'wf2.exact-output-path',
+          'pass',
+          step.id,
+          output,
+          `${step.id} may write absent exact output ${relativePath}.`,
+          'EXACT_OUTPUT_WRITABLE',
+        ));
+        continue;
+      }
+      const providers = predecessorIds
+        .filter((predecessorId) => {
+          const predecessor = requireStep(byId, predecessorId);
+          return predecessor.expectedOutputs.some((candidate) => decodeExactPath(candidate) === relativePath)
+            && pathAllowed(relativePath, predecessor.allowedWrites);
+        })
+        .sort();
+      if (providers.length > 0) {
+        findings.push(finding(
+          'wf2.exact-predecessor-path',
+          'pass',
+          step.id,
+          output,
+          `Transitive declared predecessor ${providers.join(', ')} owns and may write ${relativePath}.`,
+          'EXACT_PREDECESSOR_OUTPUT_AVAILABLE',
+        ));
+        continue;
+      }
+      findings.push(finding(
+        'wf2.exact-output-path',
+        'blocked',
+        step.id,
+        output,
+        `${relativePath} is absent at ${source.evaluatedHead}, outside ${step.id} write bounds, and has no exact writable declared predecessor.`,
+        'EXACT_OUTPUT_UNSATISFIABLE',
+      ));
+    }
+  }
+
+  findings.sort(compareFindings);
+  return {
+    schemaVersion: 1,
+    taskId: task.id,
+    evaluatedTaskRevision: task.revision,
+    briefHash,
+    planHash,
+    ...source,
+    analyzerSetHash: mechanicalFeasibilityAnalyzerSetHash(),
+    analyzerInputHash: mechanicalFeasibilityAnalyzerInputHash(task),
+    analyzers: MECHANICAL_FEASIBILITY_ANALYZERS.map((analyzer) => ({ ...analyzer })),
+    findings,
+    decision: findings.some((candidate) => candidate.result === 'blocked') ? 'blocked' : 'clear',
+  };
+}
+
+export function assertMechanicalFeasibilityFresh(
+  repositoryRoot: string,
+  task: TaskState,
+  evidence: MechanicalFeasibilityEvidence,
+  briefHash: string,
+  planHash: string,
+): void {
+  assertEvidenceShape(evidence, task.id);
+  const currentAnalyzerSetHash = mechanicalFeasibilityAnalyzerSetHash();
+  const currentAnalyzerInputHash = mechanicalFeasibilityAnalyzerInputHash(task);
+  if (
+    evidence.taskId !== task.id
+    || evidence.briefHash !== briefHash
+    || evidence.planHash !== planHash
+    || evidence.analyzerSetHash !== currentAnalyzerSetHash
+    || evidence.analyzerInputHash !== currentAnalyzerInputHash
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Mechanical-feasibility authorization binding is stale.', {
+      taskId: task.id,
+      authorizedBriefHash: evidence.briefHash,
+      currentBriefHash: briefHash,
+      authorizedPlanHash: evidence.planHash,
+      currentPlanHash: planHash,
+      authorizedAnalyzerSetHash: evidence.analyzerSetHash,
+      currentAnalyzerSetHash,
+      authorizedAnalyzerInputHash: evidence.analyzerInputHash,
+      currentAnalyzerInputHash,
+      requiredAction: 'Record a fresh execution authorization.',
+    });
+  }
+  if (evidence.decision !== 'clear' || evidence.findings.some((findingValue) => findingValue.result === 'blocked')) {
+    throw new WorkflowError('STATE_CORRUPT', 'Approved mechanical-feasibility evidence is not clear.', {
+      taskId: task.id,
+      decision: evidence.decision,
+    });
+  }
+
+  if (task.baseCommit === null) {
+    const currentBaseHead = runGit(repositoryRoot, ['rev-parse', task.baseBranch]);
+    if (
+      evidence.sourceKind !== 'pre-start-base'
+      || evidence.sourceBranch !== task.baseBranch
+      || evidence.baseCommit !== null
+      || evidence.evaluatedHead !== currentBaseHead
+    ) {
+      throw staleSourceError(task, evidence, currentBaseHead);
+    }
+    return;
+  }
+
+  if (!task.taskBranch) {
+    throw new WorkflowError('STATE_CORRUPT', `Started Task ${task.id} has no Task branch.`);
+  }
+  const branch = currentBranch(repositoryRoot);
+  if (branch !== task.taskBranch) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Mechanical-feasibility freshness requires the owned Task branch.', {
+      taskId: task.id,
+      expectedBranch: task.taskBranch,
+      currentBranch: branch,
+    });
+  }
+  const currentTaskHead = headCommit(repositoryRoot);
+  let sourceMatches = false;
+  if (evidence.sourceKind === 'pre-start-base') {
+    sourceMatches = evidence.sourceBranch === task.baseBranch
+      && evidence.baseCommit === null
+      && task.baseCommit === evidence.evaluatedHead;
+  } else if (evidence.sourceKind === 'corrective-task-workspace') {
+    sourceMatches = evidence.sourceBranch === task.taskBranch
+      && evidence.baseCommit === task.baseCommit;
+  }
+  if (!sourceMatches || !gitIsAncestor(repositoryRoot, evidence.evaluatedHead, currentTaskHead)) {
+    throw staleSourceError(task, evidence, currentTaskHead);
+  }
+}
+
+function selectEvaluationSource(repositoryRoot: string, task: TaskState): EvaluationSource {
+  if (task.baseCommit === null) {
+    return {
+      sourceKind: 'pre-start-base',
+      sourceBranch: task.baseBranch,
+      evaluatedHead: runGit(repositoryRoot, ['rev-parse', task.baseBranch]),
+      baseCommit: null,
+    };
+  }
+  if (!task.taskBranch) {
+    throw new WorkflowError('STATE_CORRUPT', `Started Task ${task.id} has no Task branch.`);
+  }
+  const branch = currentBranch(repositoryRoot);
+  if (branch !== task.taskBranch) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Mechanical feasibility must be evaluated in the owned Task workspace.', {
+      taskId: task.id,
+      expectedBranch: task.taskBranch,
+      currentBranch: branch,
+    });
+  }
+  return {
+    sourceKind: 'corrective-task-workspace',
+    sourceBranch: task.taskBranch,
+    evaluatedHead: headCommit(repositoryRoot),
+    baseCommit: task.baseCommit,
+  };
+}
+
+function parseRootManifest(content: string | null): { state: 'valid' | 'missing' | 'invalid'; scripts: Map<string, string> } {
+  if (content === null) return { state: 'missing', scripts: new Map() };
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { state: 'invalid', scripts: new Map() };
+    }
+    const scriptsValue = (parsed as Record<string, unknown>).scripts;
+    if (!scriptsValue || typeof scriptsValue !== 'object' || Array.isArray(scriptsValue)) {
+      return { state: 'valid', scripts: new Map() };
+    }
+    return {
+      state: 'valid',
+      scripts: new Map(Object.entries(scriptsValue)
+        .filter((entry): entry is [string, string] => typeof entry[1] === 'string')),
+    };
+  } catch {
+    return { state: 'invalid', scripts: new Map() };
+  }
+}
+
+function decodeExactPath(subject: string): string | null {
+  const match = EXACT_PATH.exec(subject);
+  if (!match) return null;
+  const relativePath = match[1]!;
+  const segments = relativePath.split('/');
+  if (segments.some((segment) => segment === '.' || segment === '..')) return null;
+  return relativePath;
+}
+
+function transitivePredecessorIds(
+  stepId: string,
+  byId: ReadonlyMap<string, TaskState['steps'][number]>,
+): string[] {
+  const found = new Set<string>();
+  const visit = (candidateId: string): void => {
+    const candidate = requireStep(byId, candidateId);
+    for (const dependencyId of candidate.dependencies) {
+      if (found.has(dependencyId)) continue;
+      requireStep(byId, dependencyId);
+      found.add(dependencyId);
+      visit(dependencyId);
+    }
+  };
+  visit(stepId);
+  return [...found].sort();
+}
+
+function requireStep(
+  byId: ReadonlyMap<string, TaskState['steps'][number]>,
+  stepId: string,
+): TaskState['steps'][number] {
+  const step = byId.get(stepId);
+  if (!step) throw new WorkflowError('STATE_CORRUPT', `Mechanical-feasibility input references missing Step ${stepId}.`);
+  return step;
+}
+
+function finding(
+  analyzerId: MechanicalFeasibilityAnalyzer['analyzerId'],
+  result: MechanicalFeasibilityFinding['result'],
+  stepId: string,
+  subject: string,
+  evidence: string,
+  reasonCode: string,
+): MechanicalFeasibilityFinding {
+  return { analyzerId, analyzerVersion: 1, result, stepId, subject, evidence, reasonCode };
+}
+
+function compareFindings(left: MechanicalFeasibilityFinding, right: MechanicalFeasibilityFinding): number {
+  return left.stepId.localeCompare(right.stepId)
+    || left.analyzerId.localeCompare(right.analyzerId)
+    || left.subject.localeCompare(right.subject)
+    || left.result.localeCompare(right.result);
+}
+
+function readGitPath(repositoryRoot: string, commit: string, relativePath: string): string | null {
+  const result = spawnSync('git', ['-C', repositoryRoot, 'show', `${commit}:${relativePath}`], { encoding: 'utf8' });
+  if (result.status === 0) return result.stdout;
+  if (result.status === 128) return null;
+  throw new WorkflowError('COMMAND_FAILED', `Unable to read ${relativePath} at ${commit}.`, {
+    stderr: result.stderr.trim(),
+    exitCode: result.status,
+  });
+}
+
+function gitPathExists(repositoryRoot: string, commit: string, relativePath: string): boolean {
+  const result = spawnSync('git', ['-C', repositoryRoot, 'cat-file', '-e', `${commit}:${relativePath}`], { encoding: 'utf8' });
+  if (result.status === 0) return true;
+  if (result.status === 128) return false;
+  throw new WorkflowError('COMMAND_FAILED', `Unable to inspect ${relativePath} at ${commit}.`, {
+    stderr: result.stderr.trim(),
+    exitCode: result.status,
+  });
+}
+
+function assertEvidenceShape(evidence: MechanicalFeasibilityEvidence, taskId: string): void {
+  const analyzersCanonical = canonicalJsonStringify(evidence.analyzers);
+  const currentAnalyzersCanonical = canonicalJsonStringify(MECHANICAL_FEASIBILITY_ANALYZERS);
+  const sortedFindings = [...evidence.findings].sort(compareFindings);
+  if (
+    evidence.schemaVersion !== 1
+    || analyzersCanonical !== currentAnalyzersCanonical
+    || canonicalJsonStringify(evidence.findings) !== canonicalJsonStringify(sortedFindings)
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', 'Mechanical-feasibility evidence shape or canonical order is invalid.', {
+      taskId,
+    });
+  }
+}
+
+function staleSourceError(
+  task: TaskState,
+  evidence: MechanicalFeasibilityEvidence,
+  currentHead: string,
+): WorkflowError {
+  return new WorkflowError('TRANSITION_BLOCKED', 'Mechanical-feasibility evaluation source is stale.', {
+    taskId: task.id,
+    sourceKind: evidence.sourceKind,
+    sourceBranch: evidence.sourceBranch,
+    evaluatedHead: evidence.evaluatedHead,
+    currentHead,
+    authorizedBaseCommit: evidence.baseCommit,
+    currentBaseCommit: task.baseCommit,
+    requiredAction: 'Record a fresh execution authorization.',
+  });
+}