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

package/src/state/corrective-replan-public.ts

@@ -0,0 +1,908 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { types as utilTypes } from 'node:util';
+import type { SidecarEventRecord, TaskPlanInput, TaskState } from '../contracts.js';
+import { readTaskC1Posture } from '../alpha6/handoff.js';
+import { readCorrectivePlanningAudit, readFailedStepPlanningRecovery } from '../alpha6/failed-step-planning-recovery.js';
+import {
+  findCurrentGuardedRemediationPosture,
+  effectiveStepAllowedWrites,
+  readCorrectiveDecisionEvents,
+  readRemediationEvents,
+} from '../alpha6/remediation.js';
+import { pathAllowed, validatePlan } from '../domain/validation.js';
+import { WorkflowError } from '../errors.js';
+import { hashKnowledgeMap } from '../memory.js';
+import { changedFiles, headCommit } from '../repository.js';
+import { hashDirtyWorktree } from '../alpha6/downstream-proof.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { GuardedTransitionCatalog } from '../lifecycle/catalog.js';
+import { correctiveReplanBindingManifest } from '../lifecycle/corrective-replan-binding-manifest.js';
+import {
+  createCorrectiveReplanCredentialKernel,
+  type CorrectiveReplanCredentialKernel,
+  type HumanChallengeHandle,
+  type PlanValidationHandle,
+  type ReceiptHandle,
+  type StoredPlanValidationEventHandle,
+  type VerifiedConfirmationHandle,
+} from '../lifecycle/corrective-replan-credential-core.js';
+import { correctiveReplanCredentialSchemaValidators } from '../lifecycle/corrective-replan-credential-schema.js';
+import {
+  evaluateTaskCorrectiveReplanAvailability,
+  evaluateTaskCorrectiveReplanAdmission,
+  evaluateTaskCorrectiveReplanCandidate,
+  identifyCorrectiveReplanPosture,
+  prepareCorrectiveReplanCandidate,
+  taskCorrectiveReplanDefinition,
+} from '../lifecycle/corrective-replan.js';
+import { hashCanonical } from '../lifecycle/fingerprint.js';
+import { deepFreeze } from '../lifecycle/immutable.js';
+import { LIFECYCLE_EPOCH } from '../lifecycle/types.js';
+import {
+  correctiveReplanExecutionKeyHash,
+  correctiveReplanRiskAuditHash,
+  correctiveReplanStepSetHash,
+  createCorrectiveReplanExecutor,
+  type CorrectiveReplanExecutionResult,
+  type CorrectiveReplanRiskAuditInput,
+} from './corrective-replan-executor.js';
+import {
+  assertTaskTransactionBoundary,
+  CorrectiveReplanTaskTransactionStore,
+} from './corrective-replan-transaction.js';
+import { assertCorrectiveYieldTaskTransactionBoundary } from './corrective-yield-transaction.js';
+import { inspectWriterLease, listCoreTaskOperationMutexes } from './lock.js';
+import {
+  assertCorrectiveReplanPublicOutput,
+  validateCorrectiveReplanPublicValue,
+} from './corrective-replan-public-schema.js';
+import type { FileStateStore } from './store.js';
+
+type JsonRecord = Record<string, unknown>;
+const HASH = /^[a-f0-9]{64}$/;
+const TTL_MS = 900_000;
+const OWNED_JSON_MAX_NODES = 4096;
+const OWNED_JSON_MAX_BYTES = 262_144;
+const correctiveCatalogHash = new GuardedTransitionCatalog([taskCorrectiveReplanDefinition]).catalogHash;
+
+export interface CorrectiveReplanAuthorityPresentation {
+  readonly planAuthorIdentityHash: string;
+  readonly planValidatorIdentityHash: string;
+  readonly riskAuditorIdentityHash: string;
+  readonly actorIdentityHash: string;
+  readonly actorRole: 'delivery-coordinator' | 'technical-planner';
+  readonly humanPrincipalIdentityHash: string;
+}
+
+export interface CorrectiveReplanValidationEvidence {
+  readonly validatorContextHash: string;
+  readonly findings: readonly Readonly<{
+    findingId: string;
+    severity: 'low' | 'medium' | 'high';
+    requirementRef: string;
+    evidenceHash: string;
+  }>[];
+  readonly dispositions: readonly Readonly<{
+    findingId: string;
+    decision: 'resolved' | 'accepted-documented-limitation';
+    evidenceHash: string;
+  }>[];
+}
+
+export interface CorrectiveReplanPublicCandidate {
+  readonly plan: TaskPlanInput;
+  readonly validation: CorrectiveReplanValidationEvidence;
+  readonly riskAudit: CorrectiveReplanRiskAuditInput;
+  readonly authority: CorrectiveReplanAuthorityPresentation;
+}
+
+export interface CorrectiveReplanHumanGate {
+  readonly kind: 'corrective-replan-human-gate';
+  readonly version: 1;
+  readonly taskId: string;
+  readonly preparedAtMs: number;
+  readonly expiresAtMs: number;
+  readonly candidatePlanHash: string;
+  readonly bindingSha256: string;
+  readonly attestationId: string;
+  readonly attestationHash: string;
+  readonly challengeId: string;
+  readonly runtimeFingerprint: string;
+  readonly catalogHash: string;
+  readonly lifecycleEpoch: number;
+  readonly preparationSha256: string;
+}
+
+export interface CorrectiveReplanHumanGateResult {
+  readonly kind: 'corrective-replan-human-gate-result';
+  readonly gate: CorrectiveReplanHumanGate;
+  readonly delivery: Readonly<{
+    kind: 'corrective-replan-human-challenge-delivery';
+    version: 1;
+    challengeId: string;
+    confirmationCode: string;
+    expiresAtMs: number;
+  }>;
+}
+
+export interface CorrectiveReplanPublicCredential {
+  readonly kind: 'corrective-replan-public-credential';
+  readonly version: 1;
+  readonly gate: CorrectiveReplanHumanGate;
+  readonly receipt: Readonly<JsonRecord>;
+  readonly planValidationEvent: Readonly<JsonRecord>;
+}
+
+export interface CorrectiveReplanPublicController {
+  prepare(input: { taskId: string; candidate: CorrectiveReplanPublicCandidate }): CorrectiveReplanHumanGateResult;
+  confirm(input: {
+    taskId: string;
+    candidate: CorrectiveReplanPublicCandidate;
+    gate: CorrectiveReplanHumanGate;
+    confirmationCode: string;
+  }): CorrectiveReplanPublicCredential;
+  execute(input: {
+    taskId: string;
+    candidate: CorrectiveReplanPublicCandidate;
+    credential: CorrectiveReplanPublicCredential;
+  }): CorrectiveReplanExecutionResult;
+  recover(input: { taskId: string; transactionId: string }): CorrectiveReplanExecutionResult;
+}
+
+interface ControllerOptions {
+  readonly store: FileStateStore;
+  readonly projectId: string;
+  readonly repositoryRoot: string;
+  readonly now?: () => Date;
+}
+
+interface Chain {
+  readonly kernel: CorrectiveReplanCredentialKernel;
+  readonly clock: { set(value: number): void };
+  readonly gate: CorrectiveReplanHumanGate;
+  readonly delivery: JsonRecord;
+  readonly planValidation: PlanValidationHandle;
+  readonly challenge: HumanChallengeHandle;
+  readonly enableTaskOperationRevalidation: () => void;
+}
+
+interface ConfirmedChain extends Chain {
+  readonly confirmation: VerifiedConfirmationHandle;
+  readonly receipt: ReceiptHandle;
+  readonly receiptValue: JsonRecord;
+  readonly event: StoredPlanValidationEventHandle;
+  readonly eventValue: JsonRecord;
+}
+
+export function createCorrectiveReplanPublicController(options: ControllerOptions): CorrectiveReplanPublicController {
+  const now = options.now ?? (() => new Date());
+  const taskRoot = (taskId: string) => options.store.taskRoot(options.projectId, taskId);
+  const executor = (taskId: string, kernel: CorrectiveReplanCredentialKernel) => createCorrectiveReplanExecutor({
+    taskRoot: taskRoot(taskId),
+    locksRoot: options.store.lockRoot(options.projectId),
+    trustedRoot: options.store.root,
+    credentialKernel: kernel,
+    now,
+    admissionCheck: (input) => assertCanonicalAdmission(options, taskId, input, candidateForAdmission.get(kernel)),
+  });
+  const candidateForAdmission = new WeakMap<object, CorrectiveReplanPublicCandidate>();
+
+  const prepare = (input: { taskId: string; candidate: CorrectiveReplanPublicCandidate }): CorrectiveReplanHumanGateResult => {
+    const owned = ownRequest(input);
+    assertPublicCandidate(owned.candidate);
+    const preparedAtMs = now().getTime();
+    const chain = buildChain(options, owned.taskId, owned.candidate, preparedAtMs);
+    return assertCorrectiveReplanPublicOutput('humanGateResult', deepFreeze({
+      kind: 'corrective-replan-human-gate-result',
+      gate: chain.gate,
+      delivery: chain.delivery as CorrectiveReplanHumanGateResult['delivery'],
+    }));
+  };
+
+  const confirm = (input: {
+    taskId: string;
+    candidate: CorrectiveReplanPublicCandidate;
+    gate: CorrectiveReplanHumanGate;
+    confirmationCode: string;
+  }): CorrectiveReplanPublicCredential => {
+    const owned = ownRequest(input);
+    assertPublicCandidate(owned.candidate);
+    assertGateTime(owned.gate, now().getTime());
+    const chain = buildChain(options, owned.taskId, owned.candidate, owned.gate.preparedAtMs);
+    if (!same(chain.gate, owned.gate)) throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan Human gate is stale or malformed.');
+    const confirmedAtMs = now().getTime();
+    chain.clock.set(confirmedAtMs);
+    const confirmation = accepted(chain.kernel.confirmHuman({
+      challenge: chain.challenge,
+      confirmation: {
+        kind: 'corrective-replan-human-confirmation',
+        version: 1,
+        challengeId: chain.delivery.challengeId,
+        confirmationCode: owned.confirmationCode,
+      },
+    }), 'Human confirmation was rejected.');
+    const receipt = accepted(chain.kernel.issueReceipt({
+      planValidation: chain.planValidation,
+      confirmation: confirmation.handle,
+    }), 'Corrective-replan receipt issuance was rejected.');
+    const event = accepted(chain.kernel.materializeStoredEvent({ receipt: receipt.handle }), 'Plan Validation event materialization was rejected.');
+    return assertCorrectiveReplanPublicOutput('credential', deepFreeze({
+      kind: 'corrective-replan-public-credential',
+      version: 1,
+      gate: chain.gate,
+      receipt: receipt.receipt as JsonRecord,
+      planValidationEvent: event.event as JsonRecord,
+    }));
+  };
+
+  const execute = (input: {
+    taskId: string;
+    candidate: CorrectiveReplanPublicCandidate;
+    credential: CorrectiveReplanPublicCredential;
+  }): CorrectiveReplanExecutionResult => {
+    const owned = ownRequest(input);
+    assertPublicCandidate(owned.candidate);
+    assertPublicCredential(owned.taskId, owned.credential);
+    const receipt = record(owned.credential.receipt);
+    const binding = record(receipt.binding);
+    const transactionId = correctiveReplanExecutionKeyHash(binding);
+    const transactions = new CorrectiveReplanTaskTransactionStore({
+      taskRoot: taskRoot(owned.taskId),
+      locksRoot: options.store.lockRoot(options.projectId),
+      trustedRoot: options.store.root,
+      now,
+    });
+    if (existsSync(transactions.journalPath(transactionId))) {
+      const journal = transactions.read(transactionId);
+      if (journal.receiptHash !== receipt.receiptHash) throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan replay receipt mismatch.');
+      if (journal.phase !== 'completed') {
+        throw new WorkflowError('TASK_RECOVERY_REQUIRED', 'Corrective-replan transaction requires explicit recovery.', {
+          taskId: owned.taskId,
+          transactionId,
+        });
+      }
+      return assertCorrectiveReplanPublicOutput('executionResult', executor(owned.taskId, inertKernel()).replay({
+        taskId: owned.taskId,
+        transactionId,
+        receiptHash: string(receipt.receiptHash),
+      }));
+    }
+    assertGateTime(owned.credential.gate, now().getTime());
+    const predecessor = validatedEventPredecessor(options.store, taskRoot(owned.taskId), owned.credential.planValidationEvent);
+    const chain = confirmChain(options, owned.taskId, owned.candidate, owned.credential, predecessor);
+    candidateForAdmission.set(chain.kernel as object, owned.candidate);
+    chain.enableTaskOperationRevalidation();
+    chain.clock.set(now().getTime());
+    return assertCorrectiveReplanPublicOutput('executionResult', executor(owned.taskId, chain.kernel).execute({
+      projectId: options.projectId,
+      taskId: owned.taskId,
+      receipt: chain.receipt,
+      candidateReceipt: owned.credential.receipt,
+      planValidationEvent: chain.event,
+      candidatePlanValidationEvent: owned.credential.planValidationEvent,
+      plan: owned.candidate.plan,
+      riskAudit: owned.candidate.riskAudit,
+    }));
+  };
+
+  const recover = (input: { taskId: string; transactionId: string }): CorrectiveReplanExecutionResult => {
+    const owned = ownRequest(input);
+    return assertCorrectiveReplanPublicOutput('executionResult', executor(owned.taskId, inertKernel()).recover({ taskId: owned.taskId, transactionId: owned.transactionId }));
+  };
+
+  return deepFreeze({ prepare, confirm, execute, recover });
+}
+
+function assertCanonicalAdmission(
+  options: ControllerOptions,
+  taskId: string,
+  input: Readonly<{
+    task: TaskState;
+    plan: TaskPlanInput;
+    riskAudit: CorrectiveReplanRiskAuditInput;
+    receiptVerified: true;
+    validationEventVerified: true;
+    taskOperationLockHeld: true;
+  }>,
+  candidate: CorrectiveReplanPublicCandidate | undefined,
+): void {
+  if (!candidate || candidate.plan !== input.plan && !same(candidate.plan, input.plan)) {
+    throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan admission candidate identity is missing.');
+  }
+  const audit = readCorrectivePlanningAudit(options.store, input.task);
+  const decisions = readCorrectiveDecisionEvents(options.store, input.task);
+  const remediations = readRemediationEvents(options.store, input.task);
+  const classified = audit ? findCurrentGuardedRemediationPosture(options.store, input.task, audit) : null;
+  const posture = classified?.posture === 'replan-required'
+    ? classified
+    : audit ? identifyCorrectiveReplanPosture(input.task, audit.reviewRequiredStepIds, decisions, remediations) : null;
+  if (!posture || posture.posture !== 'replan-required' || !posture.correctiveDecision) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-replan posture changed before execution.');
+  }
+  const evaluation = evaluateTaskCorrectiveReplanAdmission(
+    input.task,
+    posture,
+    prepareCorrectiveReplanCandidate(input.task, input.plan),
+    {
+      actorRoleEligible: ['delivery-coordinator', 'technical-planner'].includes(candidate.authority.actorRole),
+      c1ClaimAbsent: readTaskC1Posture(options.store, input.task).state === 'none',
+      writerLeaseAbsent: input.taskOperationLockHeld,
+      planValidationPassed: input.validationEventVerified,
+      receiptValid: input.receiptVerified,
+      riskAuditPassed: input.riskAudit.decision === 'approved' || input.riskAudit.decision === 'approved-with-rationale',
+    },
+  );
+  if (!evaluation.allowed || evaluation.pendingGuardIds.length > 0) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Canonical corrective-replan admission rejected execution.', {
+      taskId,
+      guardResults: evaluation.guardResults,
+    });
+  }
+}
+
+function buildChain(
+  options: ControllerOptions,
+  taskId: string,
+  candidate: CorrectiveReplanPublicCandidate,
+  preparedAtMs: number,
+  previousEventHashOverride?: string | null,
+): Chain {
+  if (!Number.isSafeInteger(preparedAtMs) || preparedAtMs < 0) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan preparation time is invalid.');
+  const initialSnapshot = trustedSnapshot(options, taskId, candidate, preparedAtMs);
+  const preparationSeed = hashCanonical({
+    domain: 'codex-workflow/corrective-replan-public-preparation/v1',
+    projectId: options.projectId,
+    taskId,
+    preparedAtMs,
+    snapshot: { ...initialSnapshot, bindingManifest: correctiveReplanBindingManifest.manifestSha256 },
+  });
+  let clockMs = preparedAtMs;
+  const clock = { set(value: number) { clockMs = value; } };
+  const ids = (kind: string): string => {
+    const prefix: Record<string, string> = {
+      'plan-validation-attestation': 'PVA',
+      'human-challenge': 'HCH',
+      receipt: 'RCP',
+      'plan-validation-event': 'PVE',
+    };
+    return `${prefix[kind] ?? 'ID'}-${hashCanonical({ preparationSeed, kind, clockMs }).slice(0, 32)}`;
+  };
+  const baseValues = record(initialSnapshot.baseValues);
+  const code = publicConfirmationCode({
+    taskId,
+    preparedAtMs,
+    candidatePlanHash: string(baseValues.candidatePlanHash),
+    runtimeFingerprint: string(baseValues.runtimeFingerprint),
+    catalogHash: string(baseValues.catalogHash),
+    lifecycleEpoch: number(baseValues.lifecycleEpoch),
+  });
+  let allowTaskOperationRevalidation = false;
+  const kernel = createCorrectiveReplanCredentialKernel({
+    snapshotSource: { readCorrectiveReplanSnapshot(requestedTaskId: string) {
+      return requestedTaskId === taskId
+        ? trustedSnapshot(options, taskId, candidate, preparedAtMs, allowTaskOperationRevalidation)
+        : null;
+    } },
+    coreClock: { nowMs: () => clockMs },
+    idSource: { nextId: ids },
+    challengeCodeSource: { issueConfirmationCode: () => code },
+    validationEventTailSource: { readPlanValidationTail(requestedTaskId: string) {
+      if (requestedTaskId !== taskId) return null;
+      const tail = previousEventHashOverride === undefined
+        ? currentValidationTail(options.store, options.store.taskRoot(options.projectId, taskId))
+        : previousEventHashOverride;
+      return tail === null ? null : { eventHash: tail };
+    } },
+  });
+  const validation = accepted(kernel.issuePlanValidation({ taskId, draft: validationDraft(initialSnapshot, candidate.validation) }), 'Plan Validation issuance was rejected.');
+  const challenge = accepted(kernel.issueHumanChallenge({ planValidation: validation.handle }), 'Human challenge issuance was rejected.');
+  const delivery = record(challenge.delivery);
+  const binding = record(validation.binding);
+  const attestation = record(validation.attestation);
+  const values = record(binding.values);
+  const gateBase = {
+    kind: 'corrective-replan-human-gate' as const,
+    version: 1 as const,
+    taskId,
+    preparedAtMs,
+    expiresAtMs: number(delivery.expiresAtMs),
+    candidatePlanHash: string(values.candidatePlanHash),
+    bindingSha256: string(binding.bindingSha256),
+    attestationId: string(attestation.attestationId),
+    attestationHash: string(attestation.attestationHash),
+    challengeId: string(delivery.challengeId),
+    runtimeFingerprint: string(values.runtimeFingerprint),
+    catalogHash: string(values.catalogHash),
+    lifecycleEpoch: number(values.lifecycleEpoch),
+  };
+  const gate = deepFreeze({ ...gateBase, preparationSha256: hashCanonical(gateBase) });
+  return {
+    kernel,
+    clock,
+    gate,
+    delivery,
+    planValidation: validation.handle as PlanValidationHandle,
+    challenge: challenge.handle as HumanChallengeHandle,
+    enableTaskOperationRevalidation() { allowTaskOperationRevalidation = true; },
+  };
+}
+
+function confirmChain(
+  options: ControllerOptions,
+  taskId: string,
+  candidate: CorrectiveReplanPublicCandidate,
+  credential: CorrectiveReplanPublicCredential,
+  previousEventHash: string | null,
+): ConfirmedChain {
+  const chain = buildChain(options, taskId, candidate, credential.gate.preparedAtMs, previousEventHash);
+  if (!same(chain.gate, credential.gate)) throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan Human gate no longer matches current state.');
+  const receiptCandidate = record(credential.receipt);
+  const confirmedAtMs = number(get(receiptCandidate, '/human/confirmedAtMs'));
+  const issuedAtMs = number(receiptCandidate.issuedAtMs);
+  if (!Number.isSafeInteger(confirmedAtMs) || confirmedAtMs !== issuedAtMs) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan receipt time is invalid.');
+  chain.clock.set(confirmedAtMs);
+  const confirmation = accepted(chain.kernel.confirmHuman({
+    challenge: chain.challenge,
+    confirmation: {
+      kind: 'corrective-replan-human-confirmation', version: 1,
+      challengeId: chain.delivery.challengeId,
+      confirmationCode: deterministicCode(chain.gate),
+    },
+  }), 'Human confirmation reconstruction was rejected.');
+  const receipt = accepted(chain.kernel.issueReceipt({
+    planValidation: chain.planValidation,
+    confirmation: confirmation.handle,
+  }), 'Receipt reconstruction was rejected.');
+  if (!same(receipt.receipt, credential.receipt)) throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan receipt is not the exact Core materialization.');
+  const eventCandidate = record(credential.planValidationEvent);
+  const recordedAtMs = number(eventCandidate.recordedAtMs);
+  if (!Number.isSafeInteger(recordedAtMs) || recordedAtMs !== issuedAtMs) throw new WorkflowError('INVALID_ARGUMENT', 'Plan Validation event time is invalid.');
+  chain.clock.set(recordedAtMs);
+  const event = accepted(chain.kernel.materializeStoredEvent({ receipt: receipt.handle }), 'Plan Validation event reconstruction was rejected.');
+  if (!same(event.event, credential.planValidationEvent)) throw new WorkflowError('STATE_CONFLICT', 'Plan Validation event is not the exact Core materialization.');
+  return {
+    ...chain,
+    confirmation: confirmation.handle as VerifiedConfirmationHandle,
+    receipt: receipt.handle as ReceiptHandle,
+    receiptValue: receipt.receipt as JsonRecord,
+    event: event.handle as StoredPlanValidationEventHandle,
+    eventValue: event.event as JsonRecord,
+  };
+}
+
+function trustedSnapshot(
+  options: ControllerOptions,
+  taskId: string,
+  candidate: CorrectiveReplanPublicCandidate,
+  preparedAtMs: number,
+  allowTaskOperationRevalidation = false,
+): JsonRecord {
+  const projectRoot = options.store.projectRoot(options.projectId);
+  assertTaskTransactionBoundary(projectRoot, options.store.root, taskId);
+  assertCorrectiveYieldTaskTransactionBoundary(projectRoot, options.store.root, taskId);
+  const taskOperation = listCoreTaskOperationMutexes(options.store.lockRoot(options.projectId), options.store.root)
+    .find((operation) => operation.entityId === taskId);
+  if (taskOperation && !allowTaskOperationRevalidation) {
+    throw new WorkflowError('LOCKED', 'A Core Task operation already owns corrective-replan preparation.', {
+      taskId,
+      operationId: taskOperation.operationId,
+      transitionId: taskOperation.transitionId,
+      expiresAt: taskOperation.expiresAt,
+    });
+  }
+  const task = options.store.readTask(options.projectId, taskId);
+  validateCandidate(task, candidate);
+  const taskRoot = options.store.taskRoot(options.projectId, taskId);
+  if (options.store.hashArtifact(taskRoot, 'brief.md') !== task.briefHash
+    || !task.planHash || options.store.hashArtifact(taskRoot, 'plan.md') !== task.planHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-replan Task artifact binding is stale.');
+  }
+  const knowledge = options.store.readKnowledgeMap(options.projectId);
+  const knowledgeHash = hashKnowledgeMap(knowledge);
+  if (candidate.plan.knowledgeMapRevision !== knowledge.revision || candidate.plan.knowledgeMapHash !== knowledgeHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-replan candidate does not bind the active Project Knowledge Map.');
+  }
+  const gitHead = headCommit(options.repositoryRoot);
+  const audit = readCorrectivePlanningAudit(options.store, task);
+  if (!audit) throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective replan requires a current Plan Risk Audit.');
+  const classified = findCurrentGuardedRemediationPosture(options.store, task, audit);
+  const decisions = readCorrectiveDecisionEvents(options.store, task);
+  const remediations = readRemediationEvents(options.store, task);
+  const posture = classified?.posture === 'replan-required'
+    ? classified
+    : identifyCorrectiveReplanPosture(task, audit.reviewRequiredStepIds, decisions, remediations);
+  if (!posture || posture.posture !== 'replan-required' || !posture.correctiveDecision) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Task is not in the exact corrective-replan posture.');
+  }
+  if (readTaskC1Posture(options.store, task).state !== 'none') {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective replan requires corrective-yield before preparation.');
+  }
+  const writerLease = inspectWriterLease(options.store.lockRoot(options.projectId), task.id, options.store.root);
+  if (writerLease) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective replan requires the active writer lease to be released before preparation.', {
+      taskId: task.id,
+      leaseOwner: writerLease.owner,
+      expiresAt: writerLease.expiresAt,
+    });
+  }
+  const availability = evaluateTaskCorrectiveReplanAvailability(task, posture);
+  if (!availability.allowed) throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-replan availability guards failed.', { guardResults: availability.guardResults });
+  const prepared = prepareCorrectiveReplanCandidate(task, candidate.plan);
+  const candidateEvaluation = evaluateTaskCorrectiveReplanCandidate(task, posture, prepared);
+  if (!candidateEvaluation.allowed) throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-replan candidate guards failed.', { guardResults: candidateEvaluation.guardResults });
+  const worktree = guardedStepWorktreeSnapshot(options.store, options.repositoryRoot, task, candidate.plan, posture.stepId, gitHead);
+  const matchingRemediations = remediations.filter((event) => event.stepId === posture.stepId);
+  const remediationTail = matchingRemediations.at(-1);
+  if (!remediationTail || matchingRemediations.length !== posture.attemptCount) throw new WorkflowError('STATE_CORRUPT', 'Corrective-replan remediation tail is ambiguous.');
+  assertCorrectiveReplanKnowledgeTransition(
+    options.repositoryRoot,
+    task,
+    posture.stepId,
+    gitHead,
+    matchingRemediations.map((event) => event.eventId),
+    knowledge.revision,
+    knowledgeHash,
+  );
+  const planningRecovery = readFailedStepPlanningRecovery(options.store, task);
+  const activeGrant = planningRecovery ? [planningRecovery.priorAuthorization] : task.authorizations.filter((authorization) => authorization.kind === 'execution'
+    && authorization.decision === 'approved' && authorization.planHash === task.planHash && authorization.briefHash === task.briefHash);
+  if (activeGrant.length !== 1) throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective replan requires one exact prior Plan authorization.');
+  const authority = candidate.authority;
+  const baseValues: JsonRecord = {
+    transitionId: 'task.plan.corrective-replan',
+    runtimeFingerprint: taskCorrectiveReplanDefinition.runtimeSemanticFingerprint,
+    catalogHash: correctiveCatalogHash,
+    lifecycleEpoch: LIFECYCLE_EPOCH,
+    taskId: task.id,
+    revision: task.revision,
+    currentPlanHash: task.planHash,
+    briefHash: task.briefHash,
+    knowledgeRevision: task.knowledgeMapRevision,
+    knowledgeHash: task.knowledgeMapHash,
+    targetKnowledgeRevision: knowledge.revision,
+    targetKnowledgeHash: knowledgeHash,
+    gitHead,
+    guardedStepId: posture.stepId,
+    correctiveDecisionEventId: posture.correctiveDecision.eventId,
+    correctiveDecisionHash: posture.correctiveDecision.eventHash,
+    attemptCount: posture.attemptCount,
+    remediationTailHash: remediationTail.eventHash,
+    candidatePlanHash: prepared.planHash,
+    candidateStepSetHash: correctiveReplanStepSetHash(prepared.stepIds),
+    planAuthorIdentityHash: authority.planAuthorIdentityHash,
+    planValidatorIdentityHash: authority.planValidatorIdentityHash,
+    riskAuditHash: '',
+    riskAuditorIdentityHash: authority.riskAuditorIdentityHash,
+    actorIdentityHash: authority.actorIdentityHash,
+    actorRole: authority.actorRole,
+    humanPrincipalIdentityHash: authority.humanPrincipalIdentityHash,
+    capabilityId: 'capability.task.corrective-replan',
+    capabilityVersion: 1,
+  };
+  baseValues.riskAuditHash = correctiveReplanRiskAuditHash(baseValues, candidate.riskAudit);
+  const requirements = coverage(task.requirements, candidate.plan.requirements, 'requirements');
+  const acceptance = coverage(task.acceptance, candidate.plan.acceptance, 'acceptance');
+  const architecture = {
+    sourceHash: hashCanonical({ domain: 'codex-workflow/corrective-replan-architecture-source/v1',
+      baseBranch: task.baseBranch, baseCommit: task.baseCommit, briefHash: task.briefHash, currentPlanHash: task.planHash }),
+    compatibilityHash: hashCanonical({ domain: 'codex-workflow/corrective-replan-architecture-compatibility/v1',
+      graphUse: candidate.plan.graphUse, knowledgeTargets: candidate.plan.knowledgeTargets,
+      steps: candidate.plan.steps.map(({ id, dependencies, allowedWrites, forbiddenScope }) => ({ id, dependencies, allowedWrites, forbiddenScope })) }),
+    passed: true,
+  };
+  const plannerContextHash = hashCanonical({
+    domain: 'codex-workflow/corrective-replan-planner-context/v1',
+    taskId: task.id,
+    revision: task.revision,
+    candidatePlanHash: prepared.planHash,
+    planAuthorIdentityHash: authority.planAuthorIdentityHash,
+  });
+  return {
+    snapshotVersion: 2,
+    bindingManifest: correctiveReplanBindingManifest,
+    worktree,
+    baseValues,
+    validationExpectation: {
+      source: {
+        taskId: task.id, revision: task.revision, currentPlanHash: task.planHash,
+        briefHash: task.briefHash, knowledgeRevision: task.knowledgeMapRevision,
+        knowledgeHash: task.knowledgeMapHash, gitHead,
+        guardedStepId: posture.stepId, correctiveDecisionHash: posture.correctiveDecision.eventHash,
+        remediationTailHash: remediationTail.eventHash,
+      },
+      candidate: { planHash: prepared.planHash, stepSetHash: correctiveReplanStepSetHash(prepared.stepIds) },
+      requirements,
+      acceptance,
+      architecture,
+      planAuthor: { identityHash: authority.planAuthorIdentityHash },
+      plannerContext: { contextHash: plannerContextHash, capturedAtMs: preparedAtMs },
+      validator: { identityHash: authority.planValidatorIdentityHash },
+    },
+    priorPlanAuthorization: { grantHash: hashCanonical(activeGrant[0]), requiredDisposition: 'superseded' },
+  };
+}
+
+function assertCorrectiveReplanKnowledgeTransition(
+  repositoryRoot: string,
+  task: TaskState,
+  stepId: string,
+  gitHead: string,
+  remediationEventIds: readonly string[],
+  targetKnowledgeRevision: number,
+  targetKnowledgeHash: string,
+): void {
+  if (task.knowledgeMapRevision === targetKnowledgeRevision && task.knowledgeMapHash === targetKnowledgeHash) return;
+  const compatibility = [...(task.dependencyProvenanceRecoveries ?? [])].reverse().find((record) =>
+    record.commitSha === gitHead
+    && record.packageVersion === PACKAGE_VERSION
+    && task.systemCommits.includes(record.commitSha)
+    && record.planIntegrity?.stepId === stepId
+    && record.planIntegrity.planHash === task.planHash
+    && same(record.planIntegrity.remediationEventIds, remediationEventIds)
+    && same(record.planIntegrity.dirtyFiles, changedFiles(repositoryRoot).sort())
+    && record.planIntegrity.dirtyWorktreeHash === hashDirtyWorktree(
+      repositoryRoot,
+      record.planIntegrity.dirtyFiles,
+    ));
+  if (!compatibility) {
+    throw new WorkflowError(
+      'TRANSITION_BLOCKED',
+      'Corrective-replan source and target Project Knowledge bindings differ without exact Plan-integrity update compatibility.',
+      {
+        taskId: task.id,
+        sourceKnowledgeRevision: task.knowledgeMapRevision,
+        targetKnowledgeRevision,
+      },
+    );
+  }
+}
+
+function guardedStepWorktreeSnapshot(
+  store: FileStateStore,
+  repositoryRoot: string,
+  task: TaskState,
+  candidatePlan: TaskPlanInput,
+  guardedStepId: string,
+  gitHead: string,
+): JsonRecord {
+  const currentStep = task.steps.find((step) => step.id === guardedStepId);
+  const candidateStep = candidatePlan.steps.find((step) => step.id === guardedStepId);
+  if (!currentStep || !candidateStep) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Corrective replan must retain guarded Step ${guardedStepId}.`);
+  }
+  const files = changedFiles(repositoryRoot).sort();
+  const currentAllowedWrites = effectiveStepAllowedWrites(store, task, guardedStepId);
+  const unexpected = files.filter((file) => !pathAllowed(file, currentAllowedWrites)
+    || !pathAllowed(file, candidateStep.allowedWrites)
+    || pathAllowed(file, currentStep.forbiddenScope)
+    || pathAllowed(file, candidateStep.forbiddenScope));
+  if (unexpected.length > 0) {
+    throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Corrective replan found changes outside the guarded Step boundary.', {
+      taskId: task.id,
+      stepId: guardedStepId,
+      changedFiles: unexpected,
+    });
+  }
+  const entries = files.map((file) => {
+    const absolute = path.resolve(repositoryRoot, file);
+    const relative = path.relative(repositoryRoot, absolute).replaceAll('\\', '/');
+    if (!relative || relative.startsWith('../') || path.isAbsolute(relative)) {
+      throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Corrective replan found an invalid changed path.', { file });
+    }
+    if (!existsSync(absolute)) return { path: relative, disposition: 'deleted' };
+    const stat = lstatSync(absolute);
+    if (!stat.isFile()) {
+      throw new WorkflowError('GIT_PRECONDITION_FAILED', 'Corrective replan accepts only regular-file Step changes.', { file: relative });
+    }
+    return {
+      path: relative,
+      disposition: 'present',
+      executable: (stat.mode & 0o111) !== 0,
+      contentSha256: createHash('sha256').update(readFileSync(absolute)).digest('hex'),
+    };
+  });
+  return {
+    kind: 'guarded-step-worktree',
+    version: 1,
+    gitHead,
+    changeSha256: hashCanonical({ domain: 'codex-workflow/corrective-replan-worktree/v1', entries }),
+    entries,
+  };
+}
+
+function validateCandidate(task: TaskState, candidate: CorrectiveReplanPublicCandidate): void {
+  validatePlan(candidate.plan);
+  for (const requirement of task.requirements) if (!candidate.plan.requirements.includes(requirement)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Replacement Plan omits Task requirement ${requirement}.`);
+  }
+  for (const acceptance of task.acceptance) if (!candidate.plan.acceptance.includes(acceptance)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Replacement Plan omits Task acceptance ${acceptance}.`);
+  }
+  const authority = candidate.authority;
+  const identities = [authority.planAuthorIdentityHash, authority.planValidatorIdentityHash, authority.riskAuditorIdentityHash,
+    authority.actorIdentityHash, authority.humanPrincipalIdentityHash];
+  if (!identities.every((value) => HASH.test(value))
+    || !['delivery-coordinator', 'technical-planner'].includes(authority.actorRole)
+    || authority.planAuthorIdentityHash === authority.planValidatorIdentityHash
+    || authority.planAuthorIdentityHash === authority.riskAuditorIdentityHash
+    || authority.planAuthorIdentityHash === authority.humanPrincipalIdentityHash) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-replan authority tuple is invalid.');
+  }
+  const dispositions = new Map(candidate.validation.dispositions.map((entry) => [entry.findingId, entry.decision]));
+  if (candidate.validation.findings.some((finding) => finding.severity === 'high'
+    && dispositions.get(finding.findingId) !== 'resolved')) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'High-severity Plan Validation findings must be resolved.');
+  }
+}
+
+function assertPublicCandidate(candidate: unknown): asserts candidate is CorrectiveReplanPublicCandidate {
+  if (!validateCorrectiveReplanPublicValue('candidate', candidate)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan candidate is invalid.');
+  }
+}
+
+function validationDraft(snapshot: JsonRecord, evidence: CorrectiveReplanValidationEvidence): JsonRecord {
+  const expected = record(snapshot.validationExpectation);
+  return {
+    schemaVersion: 1,
+    requirements: structuredClone(expected.requirements),
+    acceptance: structuredClone(expected.acceptance),
+    architecture: structuredClone(expected.architecture),
+    validatorContext: { contextHash: evidence.validatorContextHash },
+    passed: true,
+    findings: structuredClone(evidence.findings),
+    dispositions: structuredClone(evidence.dispositions),
+  };
+}
+
+function coverage(required: readonly string[], candidate: readonly string[], kind: string): JsonRecord {
+  return {
+    sourceHash: hashCanonical({ domain: `codex-workflow/corrective-replan-${kind}-source/v1`, values: [...required] }),
+    coverageHash: hashCanonical({ domain: `codex-workflow/corrective-replan-${kind}-coverage/v1`, required: [...required], candidate: [...candidate] }),
+    passed: true,
+  };
+}
+
+function assertPublicCredential(taskId: string, credential: CorrectiveReplanPublicCredential): void {
+  if (!validateCorrectiveReplanPublicValue('credential', credential)
+    || !exactKeys(credential, ['kind', 'version', 'gate', 'receipt', 'planValidationEvent'])
+    || credential.kind !== 'corrective-replan-public-credential' || credential.version !== 1
+    || credential.gate.taskId !== taskId
+    || validateSchema('schema.corrective-replan-receipt', credential.receipt) !== true
+    || validateSchema('schema.corrective-replan-stored-plan-validation-event', credential.planValidationEvent) !== true) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan public credential is invalid.');
+  }
+}
+
+function assertGateTime(gate: CorrectiveReplanHumanGate, nowMs: number): void {
+  if (!validateCorrectiveReplanPublicValue('humanGate', gate)
+    || !exactKeys(gate, ['kind', 'version', 'taskId', 'preparedAtMs', 'expiresAtMs', 'candidatePlanHash', 'bindingSha256',
+    'attestationId', 'attestationHash', 'challengeId', 'runtimeFingerprint', 'catalogHash', 'lifecycleEpoch', 'preparationSha256'])) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan Human gate is malformed.');
+  }
+  const { preparationSha256, ...base } = gate;
+  if (preparationSha256 !== hashCanonical(base) || !Number.isSafeInteger(nowMs)
+    || nowMs < gate.preparedAtMs || nowMs >= gate.expiresAtMs || gate.expiresAtMs - gate.preparedAtMs > TTL_MS) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-replan Human gate is expired or invalid.');
+  }
+}
+
+function validatedEventPredecessor(store: FileStateStore, taskRoot: string, candidate: unknown): string | null {
+  const event = record(candidate);
+  const previous = event.previousEventHash;
+  if (!(previous === null || HASH.test(string(previous)))) throw new WorkflowError('INVALID_ARGUMENT', 'Plan Validation event predecessor is invalid.');
+  const events = validationEvents(store, taskRoot);
+  const tail = events.at(-1) as unknown as JsonRecord | undefined;
+  if ((tail?.eventHash ?? null) === previous) return previous as string | null;
+  if (tail?.eventHash === event.eventHash && same(tail, event)) return previous as string | null;
+  throw new WorkflowError('STATE_CONFLICT', 'Plan Validation event predecessor no longer matches current evidence.');
+}
+
+function currentValidationTail(store: FileStateStore, taskRoot: string): string | null {
+  return stringOrNull((validationEvents(store, taskRoot).at(-1) as unknown as JsonRecord | undefined)?.eventHash ?? null);
+}
+
+function validationEvents(store: FileStateStore, taskRoot: string): SidecarEventRecord[] {
+  return store.readSidecarEvents(taskRoot, 'plan-validations.jsonl', {
+    validateEvent(event) {
+      if (validateSchema('schema.corrective-replan-stored-plan-validation-event', event) !== true) {
+        throw new WorkflowError('STATE_CORRUPT', 'Stored Plan Validation event is invalid.');
+      }
+    },
+  });
+}
+
+function validateSchema(id: string, value: unknown): boolean {
+  return correctiveReplanCredentialSchemaValidators.find((entry) => entry.id === id)?.callable(value) === true;
+}
+
+function deterministicCode(gate: CorrectiveReplanHumanGate): string {
+  return publicConfirmationCode(gate);
+}
+
+function publicConfirmationCode(gate: Pick<CorrectiveReplanHumanGate,
+  'taskId' | 'preparedAtMs' | 'candidatePlanHash' | 'runtimeFingerprint' | 'catalogHash' | 'lifecycleEpoch'>): string {
+  // The public code is an audited same-principal acknowledgement, not an authentication secret.
+  // Reconstructing it is deliberately confined to the Core controller and never emitted after prepare.
+  const seed = hashCanonical({
+    domain: 'codex-workflow/corrective-replan-public-preparation/v1',
+    taskId: gate.taskId,
+    preparedAtMs: gate.preparedAtMs,
+    candidatePlanHash: gate.candidatePlanHash,
+    runtimeFingerprint: gate.runtimeFingerprint,
+    catalogHash: gate.catalogHash,
+    lifecycleEpoch: gate.lifecycleEpoch,
+  });
+  return String(Number.parseInt(seed.slice(0, 12), 16) % 1_000_000).padStart(6, '0');
+}
+
+function inertKernel(): CorrectiveReplanCredentialKernel {
+  return createCorrectiveReplanCredentialKernel({
+    snapshotSource: { readCorrectiveReplanSnapshot: () => null },
+    coreClock: { nowMs: () => 0 },
+    idSource: { nextId: () => 'unreachable' },
+    challengeCodeSource: { issueConfirmationCode: () => '000000' },
+    validationEventTailSource: { readPlanValidationTail: () => null },
+  });
+}
+
+function accepted(value: unknown, message: string): JsonRecord {
+  const result = value as { ok?: boolean; value?: JsonRecord | null; issues?: unknown };
+  if (result.ok !== true || !result.value) throw new WorkflowError('TRANSITION_BLOCKED', message, { issues: result.issues ?? [] });
+  return result.value;
+}
+
+function ownRequest<T>(input: T): T {
+  const copied = copyOwned(input, new Set<object>(), 0, { nodes: 0, bytes: 0 });
+  if (copied === null) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan request must be a bounded plain JSON value.');
+  return copied as T;
+}
+
+function copyOwned(
+  value: unknown,
+  active: Set<object>,
+  depth: number,
+  budget: { nodes: number; bytes: number },
+): unknown | null {
+  if (++budget.nodes > OWNED_JSON_MAX_NODES || (budget.bytes += 8) > OWNED_JSON_MAX_BYTES || depth > 32) return null;
+  if (typeof value === 'string') {
+    budget.bytes += Buffer.byteLength(value, 'utf8');
+    return budget.bytes > OWNED_JSON_MAX_BYTES ? null : value;
+  }
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isSafeInteger(value) ? value : null;
+  if (typeof value !== 'object' || utilTypes.isProxy(value) || active.has(value)) return null;
+  const isArray = Array.isArray(value);
+  if (isArray && value.length > OWNED_JSON_MAX_NODES) return null;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== (isArray ? Array.prototype : Object.prototype) && prototype !== null) return null;
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(value).filter((key) => !isArray || key !== 'length');
+  if (keys.some((key) => typeof key !== 'string') || (isArray && keys.length !== value.length)) return null;
+  const output: unknown[] | JsonRecord = isArray ? [] : Object.create(null);
+  active.add(value);
+  for (const key of keys as string[]) {
+    const descriptor = descriptors[key];
+    budget.bytes += Buffer.byteLength(key, 'utf8');
+    if (budget.bytes > OWNED_JSON_MAX_BYTES) return null;
+    if (!descriptor?.enumerable || !('value' in descriptor)) return null;
+    const copied = copyOwned(descriptor.value, active, depth + 1, budget);
+    if (copied === null && descriptor.value !== null) return null;
+    (output as JsonRecord)[key] = copied;
+  }
+  active.delete(value);
+  return output;
+}
+
+function exactKeys(value: unknown, keys: readonly string[]): value is JsonRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).sort().join('\0') === [...keys].sort().join('\0');
+}
+function record(value: unknown): JsonRecord { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : {}; }
+function get(value: unknown, pointer: string): unknown { return pointer.split('/').filter(Boolean).reduce((current: unknown, key) => record(current)[key], value); }
+function same(left: unknown, right: unknown): boolean { try { return hashCanonical(left) === hashCanonical(right); } catch { return false; } }
+function string(value: unknown): string { return typeof value === 'string' ? value : ''; }
+function number(value: unknown): number { return typeof value === 'number' ? value : Number.NaN; }
+function stringOrNull(value: unknown): string | null { return value === null ? null : string(value); }