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

package/src/alpha6/downstream-proof.ts

@@ -0,0 +1,520 @@
+import type { DownstreamProofInvalidationEvent, DownstreamProofReplanRecoveryEvent, TaskState } from '../contracts.js';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from '../errors.js';
+import { pathAllowed } from '../domain/validation.js';
+import {
+  changedFiles,
+  currentBranch,
+  headCommit,
+} from '../repository.js';
+import { validateTaskHistory } from '../git.js';
+import type { FileStateStore } from '../state/store.js';
+import { createUlid } from '../ulid.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { prepareSidecarAppend } from './store-sidecars.js';
+import { effectiveStepAllowedWrites } from './remediation.js';
+
+const SIDECAR = 'downstream-proof-invalidations.jsonl';
+const REPLAN_RECOVERY_SIDECAR = 'downstream-proof-replan-recoveries.jsonl';
+const HASH_64 = /^[a-f0-9]{64}$/;
+const GIT_HASH = /^[a-f0-9]{40}$/;
+const EVENT_ID = /^DPI-[0-9A-HJKMNP-TV-Z]{26}$/;
+const REPLAN_EVENT_ID = /^DPR-[0-9A-HJKMNP-TV-Z]{26}$/;
+
+export interface DownstreamProofInvalidatedStep {
+  stepId: string;
+  evidenceCommit: string;
+  triggerFiles: string[];
+}
+
+export interface DownstreamProofRecoveryAssessment {
+  applicable: boolean;
+  eligible: boolean;
+  activeStepId: string | null;
+  dirtyFiles: string[];
+  outsideActiveStepFiles: string[];
+  invalidatedSteps: DownstreamProofInvalidatedStep[];
+  preservedHeadCommit: string | null;
+  dirtyWorktreeHash: string | null;
+  blockers: string[];
+}
+
+export interface PreparedDownstreamProofInvalidation {
+  event: DownstreamProofInvalidationEvent;
+  postimage: string;
+}
+
+export interface DownstreamProofCarryoverAssessment {
+  applicable: boolean;
+  eligible: boolean;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string | null;
+  invalidationEventId: string | null;
+  blockers: string[];
+}
+
+export function assessDownstreamProofRecovery(
+  store: FileStateStore,
+  repositoryRoot: string,
+  task: TaskState,
+  options: {
+    historyBoundary?: string;
+    preservedHeadCommit?: string;
+  } = {},
+): DownstreamProofRecoveryAssessment {
+  readDownstreamProofInvalidations(store, task);
+  const activeStep = task.steps.find((step) => step.status === 'in_progress') ?? null;
+  if (task.status !== 'in_progress' || !activeStep) return emptyAssessment();
+
+  const dirtyFiles = changedFiles(repositoryRoot).sort();
+  let dirtyWorktreeHash: string | null = null;
+  try {
+    dirtyWorktreeHash = hashDirtyWorktree(repositoryRoot, dirtyFiles);
+  } catch (error) {
+    return {
+      ...emptyAssessment(),
+      applicable: true,
+      activeStepId: activeStep.id,
+      dirtyFiles,
+      blockers: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+  const activeAllowedWrites = effectiveStepAllowedWrites(store, task, activeStep.id);
+  const outsideActiveStepFiles = dirtyFiles.filter((file) => !pathAllowed(file, activeAllowedWrites));
+  if (outsideActiveStepFiles.length === 0) {
+    return {
+      ...emptyAssessment(),
+      activeStepId: activeStep.id,
+      dirtyFiles,
+      dirtyWorktreeHash,
+    };
+  }
+
+  const blockers: string[] = [];
+  if (task.workspaceOwner !== 'local') {
+    blockers.push('Recovery requires a local Task workspace because the dirty file set is repository-local evidence.');
+  }
+  if (!task.taskBranch || currentBranch(repositoryRoot) !== task.taskBranch) {
+    blockers.push(`Current branch must equal the recorded Task branch ${task.taskBranch ?? '<missing>'}.`);
+  }
+  if (!task.planHash) blockers.push('Task has no current Plan hash.');
+  if (activeStep.evidence !== null) {
+    blockers.push(`Active Step ${activeStep.id} already has completion evidence and must use strict-review recovery.`);
+  }
+
+  const predecessorIds = transitivePredecessors(task, activeStep.id, blockers);
+  const seedIds = new Set<string>();
+  for (const file of outsideActiveStepFiles) {
+    const owners = task.steps.filter((step) =>
+      step.status === 'completed'
+      && predecessorIds.has(step.id)
+      && pathAllowed(file, step.allowedWrites),
+    );
+    if (owners.length === 0) {
+      blockers.push(`${file} is outside ${activeStep.id} and is not owned by a completed transitive predecessor.`);
+      continue;
+    }
+    for (const owner of owners) seedIds.add(owner.id);
+  }
+
+  const invalidatedIds = completedDependentClosure(task, seedIds, predecessorIds);
+  const invalidatedSteps = task.steps
+    .filter((step) => invalidatedIds.has(step.id))
+    .map((step) => {
+      if (!step.evidence) {
+        blockers.push(`Completed predecessor ${step.id} has no completion evidence.`);
+      }
+      return {
+        stepId: step.id,
+        evidenceCommit: step.evidence?.commitSha ?? '',
+        triggerFiles: outsideActiveStepFiles.filter((file) => pathAllowed(file, step.allowedWrites)),
+      };
+    });
+  if (invalidatedSteps.length === 0) blockers.push('No completed predecessor completion authority can be invalidated.');
+
+  try {
+    validateTaskHistory(repositoryRoot, task, options.historyBoundary);
+  } catch (error) {
+    blockers.push(error instanceof Error ? error.message : String(error));
+  }
+
+  return {
+    applicable: true,
+    eligible: blockers.length === 0,
+    activeStepId: activeStep.id,
+    dirtyFiles,
+    outsideActiveStepFiles,
+    invalidatedSteps,
+    preservedHeadCommit: options.preservedHeadCommit ?? headCommit(repositoryRoot),
+    dirtyWorktreeHash,
+    blockers,
+  };
+}
+
+export function prepareDownstreamProofInvalidation(
+  store: FileStateStore,
+  resultTask: TaskState,
+  assessment: DownstreamProofRecoveryAssessment,
+  input: {
+    previousTaskRevision: number;
+    actor: string;
+    reason: string;
+  },
+  now: Date,
+): PreparedDownstreamProofInvalidation {
+  if (!assessment.applicable || !assessment.eligible || !assessment.activeStepId || !assessment.preservedHeadCommit) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Downstream proof recovery assessment is not eligible.', {
+      blockers: assessment.blockers,
+    });
+  }
+  const actor = normalizeRequired(input.actor, 'Recovery actor');
+  const reason = normalizeRequired(input.reason, 'Recovery reason');
+  if (!resultTask.planHash) throw new WorkflowError('STATE_CORRUPT', 'Recovered Task has no Plan hash.');
+  if (resultTask.revision !== input.previousTaskRevision + 1) {
+    throw new WorkflowError('STATE_CONFLICT', 'Recovered Task revision does not advance exactly once.');
+  }
+  const events = readDownstreamProofInvalidations(store, resultTask);
+  const prepared = prepareSidecarAppend<DownstreamProofInvalidationEvent>(events, {
+    eventId: `DPI-${createUlid(now.getTime())}`,
+    recordedAt: now.toISOString(),
+    taskId: resultTask.id,
+    previousTaskRevision: input.previousTaskRevision,
+    resultTaskRevision: resultTask.revision,
+    planHash: resultTask.planHash,
+    activeStepId: assessment.activeStepId,
+    invalidatedSteps: assessment.invalidatedSteps.map((step) => ({
+      stepId: step.stepId,
+      evidenceCommit: step.evidenceCommit,
+      triggerFiles: [...step.triggerFiles],
+    })),
+    dirtyFiles: [...assessment.dirtyFiles],
+    dirtyWorktreeHash: assessment.dirtyWorktreeHash!,
+    preservedHeadCommit: assessment.preservedHeadCommit,
+    actor,
+    reason,
+    packageVersion: PACKAGE_VERSION,
+  }, {
+    validateEvent: (event) => validateInvalidationEvent(event, resultTask),
+  });
+  return { event: prepared.event, postimage: prepared.content };
+}
+
+export function readDownstreamProofInvalidations(
+  store: FileStateStore,
+  task: TaskState,
+): DownstreamProofInvalidationEvent[] {
+  return store.readSidecarEvents<DownstreamProofInvalidationEvent>(
+    store.taskRoot(task.projectId, task.id),
+    SIDECAR,
+    { validateEvent: (event) => validateInvalidationEvent(event, task) },
+  );
+}
+
+export function downstreamProofInvalidationSidecar(): string {
+  return SIDECAR;
+}
+
+export function readDownstreamProofReplanRecoveries(
+  store: FileStateStore,
+  task: TaskState,
+): DownstreamProofReplanRecoveryEvent[] {
+  return store.readSidecarEvents<DownstreamProofReplanRecoveryEvent>(
+    store.taskRoot(task.projectId, task.id),
+    REPLAN_RECOVERY_SIDECAR,
+    { validateEvent: (event) => validateReplanRecoveryEvent(event, task) },
+  );
+}
+
+export function assessDownstreamProofCarryover(
+  store: FileStateStore,
+  repositoryRoot: string,
+  task: TaskState,
+  stepId: string,
+): DownstreamProofCarryoverAssessment {
+  const invalidation = readDownstreamProofInvalidations(store, task).at(-1) ?? null;
+  if (!invalidation || !task.planHash || task.planHash === invalidation.planHash) {
+    return {
+      applicable: false,
+      eligible: false,
+      dirtyFiles: [],
+      dirtyWorktreeHash: null,
+      invalidationEventId: null,
+      blockers: [],
+    };
+  }
+  const recovery = [...readDownstreamProofReplanRecoveries(store, task)]
+    .reverse()
+    .find((event) => event.invalidationEventId === invalidation.eventId) ?? null;
+  const sourceBinding = [...(task.dependencyProvenanceRecoveries ?? [])]
+    .reverse()
+    .map((record) => record.activeDownstreamProof)
+    .find((binding) => binding?.planHash === invalidation.planHash
+      && JSON.stringify([...binding.dirtyFiles].sort()) === JSON.stringify(invalidation.dirtyFiles)) ?? null;
+  const expectedDirtyHash = recovery?.dirtyWorktreeHash
+    ?? invalidation.dirtyWorktreeHash
+    ?? sourceBinding?.dirtyWorktreeHash
+    ?? null;
+  const expectedHead = recovery?.preservedHeadCommit ?? invalidation.preservedHeadCommit;
+  const dirtyFiles = changedFiles(repositoryRoot).sort();
+  let dirtyWorktreeHash: string | null = null;
+  const blockers: string[] = [];
+  try {
+    dirtyWorktreeHash = hashDirtyWorktree(repositoryRoot, dirtyFiles);
+  } catch (error) {
+    blockers.push(error instanceof Error ? error.message : String(error));
+  }
+  const step = task.steps.find((candidate) => candidate.id === stepId) ?? null;
+  if (!step || step.status !== 'planned' || step.evidence !== null) {
+    blockers.push('The replacement carryover Step must be planned and have no completion evidence.');
+  }
+  if (task.steps.some((candidate) => candidate.status === 'in_progress' || candidate.evidence !== null)) {
+    blockers.push('No replacement Plan Step may already be running or completed.');
+  }
+  if (JSON.stringify(dirtyFiles) !== JSON.stringify(invalidation.dirtyFiles)) {
+    blockers.push('Dirty files changed after downstream-proof recovery.');
+  }
+  if (!expectedDirtyHash) {
+    blockers.push('No hash-bound downstream-proof dirty-worktree evidence is available.');
+  } else if (dirtyWorktreeHash !== expectedDirtyHash) {
+    blockers.push('Dirty file content changed after downstream-proof recovery.');
+  }
+  if (step && dirtyFiles.some((file) => !pathAllowed(file, effectiveStepAllowedWrites(store, task, step.id)))) {
+    blockers.push('The replacement Step does not own the complete preserved dirty set.');
+  }
+  if (headCommit(repositoryRoot) !== expectedHead) {
+    blockers.push('Git HEAD changed after downstream-proof recovery.');
+  }
+  if (task.workspaceOwner !== 'local' || !task.taskBranch || currentBranch(repositoryRoot) !== task.taskBranch) {
+    blockers.push('Carryover execution requires the unchanged recorded local Task branch.');
+  }
+  try {
+    validateTaskHistory(repositoryRoot, task);
+  } catch (error) {
+    blockers.push(error instanceof Error ? error.message : String(error));
+  }
+  return {
+    applicable: true,
+    eligible: blockers.length === 0,
+    dirtyFiles,
+    dirtyWorktreeHash,
+    invalidationEventId: invalidation.eventId,
+    blockers,
+  };
+}
+
+function emptyAssessment(): DownstreamProofRecoveryAssessment {
+  return {
+    applicable: false,
+    eligible: false,
+    activeStepId: null,
+    dirtyFiles: [],
+    outsideActiveStepFiles: [],
+    invalidatedSteps: [],
+    preservedHeadCommit: null,
+    dirtyWorktreeHash: null,
+    blockers: [],
+  };
+}
+
+export function hashDirtyWorktree(repositoryRoot: string, dirtyFiles: readonly string[]): string {
+  const hash = createHash('sha256');
+  for (const file of [...dirtyFiles].sort()) {
+    const absolute = path.resolve(repositoryRoot, file);
+    const relative = path.relative(repositoryRoot, absolute);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new WorkflowError('GIT_PRECONDITION_FAILED', `Dirty path escapes the repository boundary: ${file}`);
+    }
+    hash.update(`path\0${file}\0`);
+    if (!existsSync(absolute)) {
+      hash.update('deleted\0');
+      continue;
+    }
+    const stat = lstatSync(absolute);
+    if (stat.isSymbolicLink()) {
+      hash.update(`symlink\0${readlinkSync(absolute)}\0`);
+    } else if (stat.isFile()) {
+      hash.update('file\0');
+      hash.update(readFileSync(absolute));
+      hash.update('\0');
+    } else {
+      throw new WorkflowError('GIT_PRECONDITION_FAILED', `Dirty path is not a regular file or symlink: ${file}`);
+    }
+  }
+  return hash.digest('hex');
+}
+
+function transitivePredecessors(task: TaskState, stepId: string, blockers: string[]): Set<string> {
+  const byId = new Map(task.steps.map((step) => [step.id, step]));
+  const result = new Set<string>();
+  const visiting = new Set<string>();
+  const visit = (candidateId: string): void => {
+    if (result.has(candidateId)) return;
+    if (visiting.has(candidateId)) {
+      blockers.push(`Step dependency cycle reaches ${candidateId}.`);
+      return;
+    }
+    const candidate = byId.get(candidateId);
+    if (!candidate) {
+      blockers.push(`Step dependency references missing Step ${candidateId}.`);
+      return;
+    }
+    visiting.add(candidateId);
+    for (const dependency of candidate.dependencies) {
+      visit(dependency);
+      result.add(dependency);
+    }
+    visiting.delete(candidateId);
+  };
+  visit(stepId);
+  result.delete(stepId);
+  return result;
+}
+
+function completedDependentClosure(
+  task: TaskState,
+  seedIds: ReadonlySet<string>,
+  predecessorIds: ReadonlySet<string>,
+): Set<string> {
+  const result = new Set(seedIds);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const step of task.steps) {
+      if (step.status !== 'completed' || !predecessorIds.has(step.id) || result.has(step.id)) continue;
+      if (step.dependencies.some((dependency) => result.has(dependency))) {
+        result.add(step.id);
+        changed = true;
+      }
+    }
+  }
+  return result;
+}
+
+function validateInvalidationEvent(event: DownstreamProofInvalidationEvent, task: TaskState): void {
+  const requiredKeys = [
+    'activeStepId', 'actor', 'dirtyFiles', 'eventHash', 'eventId', 'invalidatedSteps', 'packageVersion',
+    'planHash', 'preservedHeadCommit', 'previousEventHash', 'previousTaskRevision', 'reason', 'recordedAt',
+    'resultTaskRevision', 'taskId',
+  ];
+  const actualKeys = Object.keys(event).sort();
+  const expectedLegacyKeys = [...requiredKeys].sort();
+  const expectedCurrentKeys = [...requiredKeys, 'dirtyWorktreeHash'].sort();
+  if (!event || typeof event !== 'object' || Array.isArray(event)
+    || (JSON.stringify(actualKeys) !== JSON.stringify(expectedLegacyKeys)
+      && JSON.stringify(actualKeys) !== JSON.stringify(expectedCurrentKeys))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation event contains unexpected fields.');
+  }
+  if (typeof event.eventId !== 'string' || !EVENT_ID.test(event.eventId)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation eventId is invalid.');
+  }
+  if (event.taskId !== task.id) throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation Task identity mismatch.');
+  if (!Number.isInteger(event.previousTaskRevision) || event.previousTaskRevision < 1
+    || event.resultTaskRevision !== event.previousTaskRevision + 1
+    || event.resultTaskRevision > task.revision) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation revision binding is invalid.');
+  }
+  if (typeof event.planHash !== 'string' || !HASH_64.test(event.planHash)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation planHash is invalid.');
+  }
+  if (typeof event.preservedHeadCommit !== 'string' || !GIT_HASH.test(event.preservedHeadCommit)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation preservedHeadCommit is invalid.');
+  }
+  for (const [value, label] of [
+    [event.activeStepId, 'activeStepId'],
+    [event.actor, 'actor'],
+    [event.reason, 'reason'],
+    [event.packageVersion, 'packageVersion'],
+  ] as const) {
+    if (typeof value !== 'string' || !value.trim()) {
+      throw new WorkflowError('STATE_CORRUPT', `Downstream proof invalidation ${label} is required.`);
+    }
+  }
+  if (!Array.isArray(event.dirtyFiles) || event.dirtyFiles.length === 0
+    || event.dirtyFiles.some((file) => typeof file !== 'string' || !file.trim())
+    || new Set(event.dirtyFiles).size !== event.dirtyFiles.length
+    || JSON.stringify(event.dirtyFiles) !== JSON.stringify([...event.dirtyFiles].sort())) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation dirtyFiles are invalid.');
+  }
+  if (event.dirtyWorktreeHash !== undefined
+    && (typeof event.dirtyWorktreeHash !== 'string' || !HASH_64.test(event.dirtyWorktreeHash))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation dirtyWorktreeHash is invalid.');
+  }
+  if (!Array.isArray(event.invalidatedSteps) || event.invalidatedSteps.length === 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidation must identify invalidated Steps.');
+  }
+  const stepIds = new Set<string>();
+  for (const step of event.invalidatedSteps) {
+    if (!step || typeof step !== 'object' || Array.isArray(step)
+      || JSON.stringify(Object.keys(step).sort()) !== JSON.stringify(['evidenceCommit', 'stepId', 'triggerFiles'])) {
+      throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidated Step contains unexpected fields.');
+    }
+    if (typeof step.stepId !== 'string' || !step.stepId.trim() || stepIds.has(step.stepId)
+      || typeof step.evidenceCommit !== 'string' || !GIT_HASH.test(step.evidenceCommit)
+      || !(task.invalidatedStepCommits ?? []).includes(step.evidenceCommit)
+      || !Array.isArray(step.triggerFiles)
+      || new Set(step.triggerFiles).size !== step.triggerFiles.length
+      || step.triggerFiles.some((file) => typeof file !== 'string' || !event.dirtyFiles.includes(file))) {
+      throw new WorkflowError('STATE_CORRUPT', 'Downstream proof invalidated Step evidence is invalid.');
+    }
+    stepIds.add(step.stepId);
+  }
+}
+
+function validateReplanRecoveryEvent(event: DownstreamProofReplanRecoveryEvent, task: TaskState): void {
+  const expectedKeys = [
+    'actor', 'dependencyRecoveryCommit', 'dirtyFiles', 'dirtyWorktreeHash', 'eventHash', 'eventId',
+    'invalidationEventId', 'invalidationPlanHash', 'knowledgeRebindRecordedAt', 'packageVersion',
+    'preservedHeadCommit', 'previousEventHash', 'previousTaskRevision', 'reason', 'reboundPlanHash',
+    'recordedAt', 'resultTaskRevision', 'taskId',
+  ];
+  if (!event || typeof event !== 'object' || Array.isArray(event)
+    || JSON.stringify(Object.keys(event).sort()) !== JSON.stringify(expectedKeys.sort())) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery event contains unexpected fields.');
+  }
+  if (typeof event.eventId !== 'string' || !REPLAN_EVENT_ID.test(event.eventId)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery eventId is invalid.');
+  }
+  if (event.taskId !== task.id
+    || !Number.isInteger(event.previousTaskRevision)
+    || event.previousTaskRevision < 1
+    || event.resultTaskRevision !== event.previousTaskRevision + 1
+    || event.resultTaskRevision > task.revision) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery Task/revision binding is invalid.');
+  }
+  if (typeof event.invalidationEventId !== 'string' || !EVENT_ID.test(event.invalidationEventId)
+    || typeof event.invalidationPlanHash !== 'string' || !HASH_64.test(event.invalidationPlanHash)
+    || typeof event.reboundPlanHash !== 'string' || !HASH_64.test(event.reboundPlanHash)
+    || typeof event.dirtyWorktreeHash !== 'string' || !HASH_64.test(event.dirtyWorktreeHash)
+    || typeof event.preservedHeadCommit !== 'string' || !GIT_HASH.test(event.preservedHeadCommit)
+    || (event.dependencyRecoveryCommit !== null
+      && (typeof event.dependencyRecoveryCommit !== 'string' || !GIT_HASH.test(event.dependencyRecoveryCommit)))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery hash binding is invalid.');
+  }
+  if (!Number.isFinite(Date.parse(event.knowledgeRebindRecordedAt))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery knowledge rebind timestamp is invalid.');
+  }
+  if (!Array.isArray(event.dirtyFiles) || event.dirtyFiles.length === 0
+    || event.dirtyFiles.some((file) => typeof file !== 'string' || !file.trim())
+    || new Set(event.dirtyFiles).size !== event.dirtyFiles.length
+    || JSON.stringify(event.dirtyFiles) !== JSON.stringify([...event.dirtyFiles].sort())) {
+    throw new WorkflowError('STATE_CORRUPT', 'Downstream-proof replan recovery dirtyFiles are invalid.');
+  }
+  for (const [value, label] of [
+    [event.actor, 'actor'],
+    [event.reason, 'reason'],
+    [event.packageVersion, 'packageVersion'],
+  ] as const) {
+    if (typeof value !== 'string' || !value.trim()) {
+      throw new WorkflowError('STATE_CORRUPT', `Downstream-proof replan recovery ${label} is required.`);
+    }
+  }
+}
+
+function normalizeRequired(value: string, label: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} is required.`);
+  }
+  return value.trim();
+}

package/src/alpha6/failed-step-planning-recovery.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import type { TaskState } from '../contracts.js';
+import type { FileStateStore } from '../state/store.js';
+import { WorkflowError } from '../errors.js';
+import { hashKnowledgeMap } from '../memory.js';
+import { canonicalJsonStringify, sha256Hex } from './store-sidecars.js';
+import { readCurrentPlanRiskAudit, readCurrentPlanningObstructionAudit, readPlanRiskAuditEvents } from './plan-risk.js';
+import { assertKnowledgeBindingOnlyPlanChange } from '../alpha7/corrective-recovery.js';
+
+/** A stopped rebound Plan is evidence for repair, never execution authority. */
+export function readFailedStepPlanningRecovery(store: FileStateStore, task: TaskState) {
+  if (task.status !== 'awaiting_execution_authorization' || !task.planHash
+    || task.workspaceOwner === null || !task.steps.some(step => step.status === 'failed')
+    || task.steps.some(step => step.status === 'in_progress')) return null;
+  const current = readCurrentPlanningObstructionAudit(store, task);
+  if (!current || current.audit.decision !== 'stop-escalate') return null;
+  const fail = (message: string): never => { throw new WorkflowError('TRANSITION_BLOCKED', message, { taskId: task.id }); };
+  const map = store.readKnowledgeMap(task.projectId);
+  if (map.status !== 'active' || map.revision !== task.knowledgeMapRevision || hashKnowledgeMap(map) !== task.knowledgeMapHash)
+    fail('Planning recovery requires the current active Knowledge binding.');
+  const audits = readPlanRiskAuditEvents(store, task);
+  const root = store.taskRoot(task.projectId, task.id);
+  let hash = task.planHash;
+  let knowledgeRevision = task.knowledgeMapRevision;
+  let knowledgeHash = task.knowledgeMapHash;
+  const visited = new Set<string>();
+  const plan = (h: string) => {
+    const text = readFileSync(h === task.planHash ? path.join(root, 'plan.md') : path.join(root, '.versions', `plan.md.${h}`), 'utf8');
+    if (sha256Hex(text) !== h) fail('Planning recovery Plan artifact hash mismatch.');
+    return text;
+  };
+  while (!visited.has(hash)) {
+    visited.add(hash);
+    const links = task.knowledgeRebinds.filter(record => record.reboundPlanHash === hash);
+    if (links.length !== 1) return fail('Planning recovery requires an unambiguous Knowledge rebind chain.');
+    const link = links[0]!;
+    if (link.toKnowledgeMapRevision !== knowledgeRevision || link.toKnowledgeMapHash !== knowledgeHash
+      || !link.previousPlanHash) fail('Planning recovery Knowledge rebind endpoints are stale.');
+    const before = plan(link.previousPlanHash), after = plan(hash);
+    assertKnowledgeBindingOnlyPlanChange(before, after);
+    if (!before.includes(`- Knowledge map: revision ${link.fromKnowledgeMapRevision}, hash ${link.fromKnowledgeMapHash}\n`)
+      || !after.includes(`- Knowledge map: revision ${link.toKnowledgeMapRevision}, hash ${link.toKnowledgeMapHash}\n`))
+      fail('Planning recovery artifact Knowledge endpoints differ from the recorded rebind.');
+    hash = link.previousPlanHash;
+    knowledgeRevision = link.fromKnowledgeMapRevision;
+    knowledgeHash = link.fromKnowledgeMapHash;
+    const baseline = audits.filter(a => a.planHash === hash && a.briefHash === task.briefHash
+      && a.knowledgeMapRevision === knowledgeRevision && a.knowledgeMapHash === knowledgeHash
+      && ['approved', 'approved-with-rationale'].includes(a.decision)
+      && audits.indexOf(a) < audits.findIndex(event => event.eventHash === current.audit.eventHash)
+      && task.authorizations.some(grant => grant.kind === 'execution' && grant.decision === 'superseded'
+        && grant.planHash === a.planHash && grant.briefHash === a.briefHash
+        && Date.parse(grant.recordedAt) >= Date.parse(a.recordedAt))).at(-1);
+    if (!baseline) continue;
+    // A negative audit may append an observed counterexample without erasing the
+    // historical proof. Prefix preservation is NOT proof of semantic strengthening:
+    // both audits remain planning evidence, and replacement requires its own gates.
+    const obstructionClassifications = structuredClone(current.audit.stepClassifications);
+    for (const [stepIndex, classification] of obstructionClassifications.entries()) {
+      const original = baseline.stepClassifications[stepIndex];
+      if (!original) return fail('Planning recovery must preserve the approved Step classification ordering.');
+      const proofs = classification.proofObligations ?? [], originalProofs = original.proofObligations ?? [];
+      if (proofs.length !== originalProofs.length)
+        fail('Planning recovery must preserve the approved proof tuple count and ordering.');
+      for (const [proofIndex, proof] of proofs.entries()) {
+        const originalProof = originalProofs[proofIndex]!;
+        for (const field of ['counterexample', 'expectedResult'] as const) {
+          if (!proof[field].startsWith(originalProof[field]))
+            fail('Planning recovery cannot truncate or replace historical proof narratives.');
+          proof[field] = originalProof[field];
+        }
+      }
+    }
+    if (canonicalJsonStringify(baseline.stepClassifications) !== canonicalJsonStringify(obstructionClassifications))
+      fail('Planning recovery must preserve the approved risk classifications and proof tuples.');
+    const grants = task.authorizations.filter(a => a.kind === 'execution' && a.decision === 'superseded'
+      && a.planHash === baseline.planHash && a.briefHash === baseline.briefHash
+      && Date.parse(a.recordedAt) >= Date.parse(baseline.recordedAt));
+    if (grants.length !== 1) fail('Planning recovery requires one historical superseded Plan authorization.');
+    return { current, baseline, priorAuthorization: grants[0]!, authority: 'planning-only' as const };
+  }
+  return fail('Planning recovery Knowledge rebind chain contains a cycle.');
+}
+
+export function readCorrectivePlanningAudit(store: FileStateStore, task: TaskState) {
+  return readFailedStepPlanningRecovery(store, task)?.current ?? readCurrentPlanRiskAudit(store, task);
+}