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

package/src/state/corrective-yield-executor.ts

@@ -0,0 +1,327 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { types as utilTypes } from 'node:util';
+import type { TaskState } from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import { prepareTaskCorrectiveYield, readTaskC1Posture } from '../alpha6/handoff.js';
+import { readCorrectivePlanningAudit } from '../alpha6/failed-step-planning-recovery.js';
+import {
+  findCurrentGuardedRemediationPosture,
+  deriveCurrentCauseDecision,
+  readCorrectiveDecisionEvents,
+  readRemediationEvents,
+} from '../alpha6/remediation.js';
+import {
+  identifyCorrectiveReplanPosture,
+  type CorrectiveReplanPosture,
+} from '../lifecycle/corrective-replan.js';
+import { hashCanonical } from '../lifecycle/fingerprint.js';
+import { deepFreeze } from '../lifecycle/immutable.js';
+import type { FileStateStore } from './store.js';
+import {
+  CoreTaskOperationLockManager,
+  WriterLockManager,
+  type CoreTaskOperationHandle,
+  type WriterLeaseHandle,
+} from './lock.js';
+import {
+  CorrectiveYieldTaskTransactionStore,
+  type CorrectiveYieldTaskTransactionJournal,
+} from './corrective-yield-transaction.js';
+
+const TRANSITION = 'task.coordination.corrective-yield' as const;
+const HASH = /^[a-f0-9]{64}$/;
+
+export type CorrectiveYieldCrashBoundary =
+  | 'after-intent'
+  | 'after-applying-phase'
+  | 'after-handoff-event'
+  | 'after-handoff-phase'
+  | 'after-lock-transfer'
+  | 'after-lock-phase'
+  | 'after-published-phase'
+  | 'after-domain-readback'
+  | 'after-completed-phase'
+  | 'after-lock-release'
+  | 'after-terminal-readback';
+
+export interface ExecuteCorrectiveYieldInput {
+  readonly projectId: string;
+  readonly taskId: string;
+  readonly expectedTaskRevision: number;
+  readonly actor: string;
+  readonly writerToken: string;
+  readonly reason: string;
+}
+
+export interface CorrectiveYieldExecutionResult {
+  readonly kind: 'corrective-yield-execution-result';
+  readonly disposition: 'yielded' | 'recovered' | 'replayed';
+  readonly taskId: string;
+  readonly transactionId: string;
+  readonly yieldEventHash: string;
+  readonly resultSha256: string;
+}
+
+export interface CorrectiveYieldExecutor {
+  execute(input: ExecuteCorrectiveYieldInput): CorrectiveYieldExecutionResult;
+  recover(input: { taskId: string; transactionId: string }): CorrectiveYieldExecutionResult;
+}
+
+export function createCorrectiveYieldExecutor(options: {
+  store: FileStateStore;
+  projectId: string;
+  now?: () => Date;
+  faultInjector?: (boundary: CorrectiveYieldCrashBoundary) => void;
+}): CorrectiveYieldExecutor {
+  const now = options.now ?? (() => new Date());
+  const projectRoot = options.store.projectRoot(options.projectId);
+  const locksRoot = options.store.lockRoot(options.projectId);
+  const writerLocks = new WriterLockManager(locksRoot, now, options.store.root);
+  const coreLocks = new CoreTaskOperationLockManager(locksRoot, now, options.store.root);
+  const fault = (boundary: CorrectiveYieldCrashBoundary): void => options.faultInjector?.(boundary);
+  const transactionStore = (taskId: string) => new CorrectiveYieldTaskTransactionStore({
+    taskRoot: options.store.taskRoot(options.projectId, taskId),
+    locksRoot,
+    trustedRoot: options.store.root,
+    now,
+  });
+
+  const recover = (input: { taskId: string; transactionId: string }): CorrectiveYieldExecutionResult => {
+    assertExact(input, ['taskId', 'transactionId'], 'Corrective-yield recovery input');
+    assertHash(input.transactionId, 'Corrective-yield transaction id');
+    const transactions = transactionStore(input.taskId);
+    const journal = transactions.read(input.transactionId);
+    if (journal.taskId !== input.taskId || journal.projectId !== options.projectId) {
+      throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield recovery identity mismatch.');
+    }
+    const lockFile = path.join(locksRoot, `${journal.taskId}.json`);
+    if (journal.phase === 'completed' && !existsSync(lockFile)) {
+      return result(journal, transactions.terminalReadback(journal.transactionId), 'replayed');
+    }
+    if (!existsSync(lockFile) && !transactions.handoffIsPostimage(journal)) {
+      throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield writer lease vanished before its handoff effect.');
+    }
+    const handle = coreLocks.acquireYieldRecovery({
+      entityId: journal.taskId,
+      operationId: journal.transactionId,
+      transitionId: TRANSITION,
+      expectedWriterContentSha256: journal.writerLeaseContentSha256,
+      expectedWriterTokenSha256: journal.writerLeaseTokenSha256,
+    });
+    let released = false;
+    try {
+      const completed = driveCore(transactions, handle, journal.transactionId, fault);
+      coreLocks.release(handle);
+      released = true;
+      fault('after-lock-release');
+      const resultSha256 = transactions.terminalReadback(journal.transactionId);
+      fault('after-terminal-readback');
+      return result(completed, resultSha256, journal.phase === 'completed' ? 'replayed' : 'recovered');
+    } finally {
+      if (!released) {
+        // A failed post-intent operation deliberately retains its Core mutex until explicit stale recovery.
+      }
+    }
+  };
+
+  const execute = (input: ExecuteCorrectiveYieldInput): CorrectiveYieldExecutionResult => {
+    assertExact(input, ['actor', 'expectedTaskRevision', 'projectId', 'reason', 'taskId', 'writerToken'], 'Corrective-yield input');
+    if (input.projectId !== options.projectId || !Number.isSafeInteger(input.expectedTaskRevision) || input.expectedTaskRevision < 1
+      || typeof input.actor !== 'string' || !input.actor.trim() || input.actor.length > 256
+      || typeof input.writerToken !== 'string' || !input.writerToken
+      || typeof input.reason !== 'string' || !input.reason.trim() || input.reason.length > 2048) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield input is invalid.');
+    }
+    const task = options.store.readTask(options.projectId, input.taskId);
+    if (task.revision !== input.expectedTaskRevision) throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield Task revision is stale.');
+    const posture = requireCorrectiveReplanPosture(options.store, task);
+    const claim = readTaskC1Posture(options.store, task);
+    if (claim.state !== 'claimed') throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective yield requires an active C1 claim.');
+    const writerHandle = writerLocks.prove(task.id, input.writerToken);
+    const proof = writerLocks.proofBinding(writerHandle);
+    if (proof.owner !== input.actor.trim() || claim.claimant !== input.actor.trim()
+      || claim.writerLeaseTokenHash !== proof.tokenSha256) {
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective yield requires the exact claimant-owned writer lease.');
+    }
+    const transactionId = yieldExecutionKey(task, posture, claim.latestEvent.eventHash, input.actor.trim(), proof.tokenSha256, input.reason.trim());
+    const prepared = prepareTaskCorrectiveYield(options.store, task, {
+      actor: input.actor,
+      writerToken: input.writerToken,
+      reason: input.reason,
+      eventId: `HOF-${transactionId}`,
+    }, now());
+    const transactions = transactionStore(task.id);
+    const stateBytes = readFileSync(path.join(options.store.taskRoot(task.projectId, task.id), 'state.json'));
+    let journal = transactions.createIntent(writerHandle, {
+      projectId: task.projectId,
+      taskId: task.id,
+      transactionId,
+      taskStateSha256: sha256(stateBytes),
+      actor: input.actor.trim(),
+      writerLeaseTokenSha256: proof.tokenSha256,
+      writerLeaseContentSha256: proof.contentSha256,
+      writerLeaseExpiresAt: proof.expiresAt,
+      handoffPostimage: prepared.postimage,
+    });
+    fault('after-intent');
+    journal = transactions.advanceWithWriter(writerHandle, transactionId, 'intent', journal.phaseRevision, 'applying', 0);
+    fault('after-applying-phase');
+    transactions.applyHandoffWithWriter(writerHandle, transactionId);
+    fault('after-handoff-event');
+    journal = transactions.advanceWithWriter(writerHandle, transactionId, 'applying', journal.phaseRevision, 'applying', 1);
+    fault('after-handoff-phase');
+    const coreHandle = coreLocks.transferFromWriter(writerHandle, {
+      entityId: task.id,
+      operationId: transactionId,
+      transitionId: TRANSITION,
+    });
+    fault('after-lock-transfer');
+    let released = false;
+    try {
+      journal = transactions.advanceWithCore(coreHandle, transactionId, 'applying', journal.phaseRevision, 'applying', 2);
+      fault('after-lock-phase');
+      const completed = driveCore(transactions, coreHandle, transactionId, fault);
+      coreLocks.release(coreHandle);
+      released = true;
+      fault('after-lock-release');
+      const resultSha256 = transactions.terminalReadback(transactionId);
+      fault('after-terminal-readback');
+      return result(completed, resultSha256, 'yielded');
+    } finally {
+      if (!released) {
+        // Preserve the exact operation owner for explicit stale recovery after a post-intent failure.
+      }
+    }
+  };
+
+  return deepFreeze({ execute, recover });
+}
+
+function driveCore(
+  transactions: CorrectiveYieldTaskTransactionStore,
+  handle: CoreTaskOperationHandle,
+  transactionId: string,
+  fault: (boundary: CorrectiveYieldCrashBoundary) => void,
+): CorrectiveYieldTaskTransactionJournal {
+  let journal = transactions.read(transactionId);
+  if (journal.phase === 'intent') {
+    journal = transactions.advanceWithCore(handle, transactionId, 'intent', journal.phaseRevision, 'applying', 0);
+    fault('after-applying-phase');
+  }
+  if (journal.phase === 'applying' && journal.nextTargetOrdinal === 0) {
+    transactions.applyHandoffWithCore(handle, transactionId);
+    fault('after-handoff-event');
+    journal = transactions.advanceWithCore(handle, transactionId, 'applying', journal.phaseRevision, 'applying', 1);
+    fault('after-handoff-phase');
+  }
+  if (journal.phase === 'applying' && journal.nextTargetOrdinal === 1) {
+    journal = transactions.advanceWithCore(handle, transactionId, 'applying', journal.phaseRevision, 'applying', 2);
+    fault('after-lock-phase');
+  }
+  if (journal.phase === 'applying' && journal.nextTargetOrdinal === 2) {
+    journal = transactions.advanceWithCore(handle, transactionId, 'applying', journal.phaseRevision, 'published-pending-readback', 2);
+    fault('after-published-phase');
+  }
+  if (journal.phase === 'published-pending-readback') {
+    const resultSha256 = transactions.domainReadback(handle, transactionId);
+    fault('after-domain-readback');
+    journal = transactions.advanceWithCore(handle, transactionId, 'published-pending-readback', journal.phaseRevision, 'completed', 2, resultSha256);
+    fault('after-completed-phase');
+  }
+  return journal;
+}
+
+type YieldPosture = CorrectiveReplanPosture & { readonly remediationEventHash?: string };
+
+function requireCorrectiveReplanPosture(store: FileStateStore, task: TaskState): YieldPosture {
+  if (task.steps.some((step) => step.status === 'in_progress')) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective yield requires no running Step.');
+  }
+  const audit = readCorrectivePlanningAudit(store, task);
+  if (!audit) throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective yield requires the current guarded Plan Risk Audit.');
+  const decisions = readCorrectiveDecisionEvents(store, task);
+  const classified = findCurrentGuardedRemediationPosture(store, task, audit);
+  const posture = classified?.posture === 'replan-required'
+    ? classified
+    : identifyCorrectiveReplanPosture(task, audit.reviewRequiredStepIds, decisions, readRemediationEvents(store, task));
+  if (posture?.posture === 'replan-required' && !posture.correctiveDecision
+    && ['ready', 'needs_fix'].includes(task.status)
+    && task.steps.find(step => step.id === posture.stepId)?.status === 'failed') {
+    const history = readRemediationEvents(store, task).filter(event => event.stepId === posture.stepId);
+    if (deriveCurrentCauseDecision(history) === 'root-cause-replan') {
+      return { ...posture, remediationEventHash: history.at(-1)!.eventHash };
+    }
+  }
+  if (!posture || posture.posture !== 'replan-required' || !posture.correctiveDecision) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective yield requires one current replan-required decision.');
+  }
+  return posture;
+}
+
+function yieldExecutionKey(
+  task: TaskState,
+  posture: YieldPosture,
+  claimEventHash: string,
+  actor: string,
+  writerLeaseTokenSha256: string,
+  reason: string,
+): string {
+  return hashCanonical({
+    domain: 'codex-workflow/corrective-yield-execution-key/v1',
+    transitionId: TRANSITION,
+    taskId: task.id,
+    taskRevision: task.revision,
+    planHash: task.planHash,
+    guardedStepId: posture.stepId,
+    correctiveDecisionEventId: posture.correctiveDecision?.eventId,
+    correctiveDecisionHash: posture.correctiveDecision?.eventHash,
+    ...(posture.remediationEventHash ? { remediationEventHash: posture.remediationEventHash } : {}),
+    claimEventHash,
+    actor,
+    writerLeaseTokenSha256,
+    reason,
+  });
+}
+
+function result(
+  journal: CorrectiveYieldTaskTransactionJournal,
+  resultSha256: string,
+  disposition: CorrectiveYieldExecutionResult['disposition'],
+): CorrectiveYieldExecutionResult {
+  return deepFreeze({
+    kind: 'corrective-yield-execution-result',
+    disposition,
+    taskId: journal.taskId,
+    transactionId: journal.transactionId,
+    yieldEventHash: journal.handoffTarget.resultEventHash,
+    resultSha256,
+  });
+}
+
+function assertExact(value: unknown, keys: string[], label: string): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || utilTypes.isProxy(value)
+    || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must be a plain object.`);
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const ownKeys = Reflect.ownKeys(value);
+  if (ownKeys.some((key) => typeof key !== 'string')
+    || Object.values(descriptors).some((descriptor) => !('value' in descriptor) || descriptor.enumerable !== true)) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must contain only enumerable data properties.`);
+  }
+  const actual = Object.keys(descriptors).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} has unknown or missing fields.`);
+  }
+}
+
+function assertHash(value: unknown, label: string): asserts value is string {
+  if (typeof value !== 'string' || !HASH.test(value)) throw new WorkflowError('INVALID_ARGUMENT', `${label} must be lowercase SHA-256.`);
+}
+
+function sha256(value: Buffer | string): string {
+  return createHash('sha256').update(value).digest('hex');
+}