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

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

@@ -0,0 +1,949 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from 'node:fs';
+import path from 'node:path';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import type {
+  CorruptObservedTaskTransaction,
+  ObservedTaskTransaction,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import { assertNoSymlinkPathComponents } from '../alpha6/store-sidecars.js';
+import { deepFreeze } from '../lifecycle/immutable.js';
+import {
+  correctiveReplanBindingManifest,
+  historicalCompletedCorrectiveReplanBindingIdentities,
+} from '../lifecycle/corrective-replan-binding-manifest.js';
+import {
+  assertCoreTaskOperationHandle,
+  type CoreTaskOperationHandle,
+} from './lock.js';
+
+const HASH = /^[a-f0-9]{64}$/;
+const PROJECT = /^[a-f0-9]{24}$/;
+const TASK = /^TASK-[0-9A-HJKMNP-TV-Z]{26}$/;
+const MAX_TARGET_BYTES = 256 * 1024 * 1024;
+const schema = JSON.parse(readFileSync(
+  new URL('../../../schemas/corrective-replan-task-transaction.private.schema.json', import.meta.url),
+  'utf8',
+)) as object;
+const ajv = new Ajv2020({ allErrors: true, strict: true, formats: { 'date-time': true } });
+if (!ajv.validateSchema(schema)) throw new TypeError(`Invalid private Task transaction schema: ${ajv.errorsText(ajv.errors)}`);
+const validateSchema = ajv.compile(schema);
+
+export const CORRECTIVE_REPLAN_TARGETS = deepFreeze([
+  { targetId: 'task-state', relativePath: 'state.json', writeMode: 'replace-exact' },
+  { targetId: 'plan', relativePath: 'plan.md', writeMode: 'replace-exact' },
+  { targetId: 'plan-validation', relativePath: 'plan-validations.jsonl', writeMode: 'append-exact' },
+  { targetId: 'plan-risk-audit', relativePath: 'plan-risk-audits.jsonl', writeMode: 'append-exact' },
+  { targetId: 'execution-evidence', relativePath: 'corrective-replan-executions.jsonl', writeMode: 'append-exact' },
+] as const);
+
+export type CorrectiveReplanTransactionPhase = 'intent' | 'applying' | 'published-pending-readback' | 'completed';
+type TargetId = typeof CORRECTIVE_REPLAN_TARGETS[number]['targetId'];
+
+export interface CorrectiveReplanTargetRecord {
+  targetId: TargetId;
+  ordinal: number;
+  relativePath: string;
+  writeMode: 'replace-exact' | 'append-exact';
+  preimage: { exists: boolean; contentSha256: string | null; byteLength: number; contentPath: string | null };
+  postimage: { contentSha256: string; byteLength: number; contentPath: string };
+  sidecarAnchors: null | {
+    previousEventHash: string | null;
+    resultEventHash: string;
+    previousLineCount: number;
+    resultLineCount: number;
+  };
+  taskCas: null | { expectedRevision: number; resultRevision: number };
+}
+
+export interface CorrectiveReplanTaskTransactionJournal {
+  schemaVersion: 1;
+  kind: 'corrective-replan-task-transaction';
+  transactionId: string;
+  projectId: string;
+  taskId: string;
+  transitionId: 'task.plan.corrective-replan';
+  executionKeyHash: string;
+  runtimeFingerprint: string;
+  catalogHash: string;
+  lifecycleEpoch: number;
+  bindingManifest: { id: 'binding-manifest.corrective-replan.exact-v1'; version: 1; manifestSha256: string };
+  bindingSha256: string;
+  receiptHash: string;
+  actorIdentityHash: string;
+  humanPrincipalIdentityHash: string;
+  admittedAt: string;
+  intentSha256: string;
+  phase: CorrectiveReplanTransactionPhase;
+  phaseRevision: number;
+  nextTargetOrdinal: number;
+  targets: CorrectiveReplanTargetRecord[];
+  phaseHistory: Array<{
+    sequence: number;
+    phase: CorrectiveReplanTransactionPhase;
+    nextTargetOrdinal: number;
+    recordedAt: string;
+    previousEntryHash: string | null;
+    entryHash: string;
+  }>;
+  completedResult: null | { resultSha256: string };
+  updatedAt: string;
+}
+
+export interface CreateCorrectiveReplanIntentInput {
+  projectId: string;
+  taskId: string;
+  transitionId: 'task.plan.corrective-replan';
+  executionKeyHash: string;
+  runtimeFingerprint: string;
+  catalogHash: string;
+  lifecycleEpoch: number;
+  bindingManifest: { id: 'binding-manifest.corrective-replan.exact-v1'; version: 1; manifestSha256: string };
+  bindingSha256: string;
+  receiptHash: string;
+  actorIdentityHash: string;
+  humanPrincipalIdentityHash: string;
+  expectedTaskRevision: number;
+  resultTaskRevision: number;
+  postimages: {
+    taskState: Uint8Array;
+    plan: Uint8Array;
+    planValidation: Uint8Array;
+    planRiskAudit: Uint8Array;
+    executionEvidence: Uint8Array;
+  };
+}
+
+interface StoreOptions {
+  taskRoot: string;
+  locksRoot: string;
+  trustedRoot: string;
+  now?: () => Date;
+}
+
+export class CorrectiveReplanTaskTransactionStore {
+  private readonly taskRoot: string;
+  private readonly locksRoot: string;
+  private readonly trustedRoot: string;
+  private readonly now: () => Date;
+
+  constructor(options: StoreOptions) {
+    this.taskRoot = path.resolve(options.taskRoot);
+    this.locksRoot = path.resolve(options.locksRoot);
+    this.trustedRoot = path.resolve(options.trustedRoot);
+    this.now = options.now ?? (() => new Date());
+    assertTaskRoot(this.taskRoot, this.trustedRoot);
+  }
+
+  createIntent(handle: unknown, input: CreateCorrectiveReplanIntentInput): CorrectiveReplanTaskTransactionJournal {
+    assertPlainExact(input, [
+      'actorIdentityHash', 'bindingManifest', 'bindingSha256', 'catalogHash', 'executionKeyHash',
+      'expectedTaskRevision', 'humanPrincipalIdentityHash', 'lifecycleEpoch', 'postimages', 'projectId', 'receiptHash',
+      'resultTaskRevision', 'runtimeFingerprint', 'taskId', 'transitionId',
+    ], 'Corrective-replan intent');
+    assertHeader(input);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: input.taskId,
+      operationId: input.executionKeyHash,
+      transitionId: input.transitionId,
+    });
+    const postimages = normalizePostimages(input.postimages);
+    const preimages = CORRECTIVE_REPLAN_TARGETS.map((target) => readTarget(this.taskRoot, target.relativePath));
+    validateTaskStatePair(
+      preimages[0]!.content,
+      postimages[0]!,
+      input.projectId,
+      input.taskId,
+      input.expectedTaskRevision,
+      input.resultTaskRevision,
+    );
+    if (postimages[1]!.byteLength === 0) throw new WorkflowError('INVALID_ARGUMENT', 'Replacement Plan bytes must not be empty.');
+    const sidecars = [2, 3, 4].map((ordinal) => sidecarAnchors(preimages[ordinal]!.content, postimages[ordinal]!));
+    const transactionRoot = this.transactionRoot(input.executionKeyHash);
+    if (existsSync(transactionRoot)) {
+      throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan transaction already exists.', {
+        transactionId: input.executionKeyHash,
+      });
+    }
+    const targets: CorrectiveReplanTargetRecord[] = CORRECTIVE_REPLAN_TARGETS.map((target, ordinal) => ({
+      ...target,
+      ordinal,
+      preimage: snapshot(preimages[ordinal]!.content, ordinal),
+      postimage: {
+        contentSha256: sha256(postimages[ordinal]!),
+        byteLength: postimages[ordinal]!.byteLength,
+        contentPath: `targets/${ordinal}.bin`,
+      },
+      sidecarAnchors: ordinal < 2 ? null : sidecars[ordinal - 2]!,
+      taskCas: ordinal === 0
+        ? { expectedRevision: input.expectedTaskRevision, resultRevision: input.resultTaskRevision }
+        : null,
+    }));
+    const admittedAt = this.now().toISOString();
+    const journal: CorrectiveReplanTaskTransactionJournal = {
+      schemaVersion: 1,
+      kind: 'corrective-replan-task-transaction',
+      transactionId: input.executionKeyHash,
+      projectId: input.projectId,
+      taskId: input.taskId,
+      transitionId: input.transitionId,
+      executionKeyHash: input.executionKeyHash,
+      runtimeFingerprint: input.runtimeFingerprint,
+      catalogHash: input.catalogHash,
+      lifecycleEpoch: input.lifecycleEpoch,
+      bindingManifest: {
+        id: correctiveReplanBindingManifest.id,
+        version: correctiveReplanBindingManifest.version,
+        manifestSha256: correctiveReplanBindingManifest.manifestSha256,
+      },
+      bindingSha256: input.bindingSha256,
+      receiptHash: input.receiptHash,
+      actorIdentityHash: input.actorIdentityHash,
+      humanPrincipalIdentityHash: input.humanPrincipalIdentityHash,
+      admittedAt,
+      intentSha256: '0'.repeat(64),
+      phase: 'intent',
+      phaseRevision: 1,
+      nextTargetOrdinal: 0,
+      targets,
+      phaseHistory: [],
+      completedResult: null,
+      updatedAt: admittedAt,
+    };
+    journal.intentSha256 = intentHash(journal);
+    journal.phaseHistory = [phaseEntry(0, 'intent', 0, admittedAt, null, journal.intentSha256)];
+    validateJournal(journal, this.taskRoot, false, input.executionKeyHash);
+    ensureDirectorySafe(path.dirname(transactionRoot), this.trustedRoot);
+    let createdTransactionRoot = false;
+    try {
+      mkdirSync(transactionRoot, { mode: 0o700 });
+      createdTransactionRoot = true;
+      mkdirSync(path.join(transactionRoot, 'preimages'), { mode: 0o700 });
+      mkdirSync(path.join(transactionRoot, 'targets'), { mode: 0o700 });
+      preimages.forEach(({ content }, ordinal) => {
+        if (content !== null) writeNewDurable(path.join(transactionRoot, 'preimages', `${ordinal}.bin`), content);
+      });
+      postimages.forEach((content, ordinal) => writeNewDurable(path.join(transactionRoot, 'targets', `${ordinal}.bin`), content));
+      assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+        entityId: input.taskId, operationId: input.executionKeyHash, transitionId: input.transitionId,
+      });
+      writeNewDurable(this.journalPath(input.executionKeyHash), jsonBuffer(journal));
+      fsyncDirectory(transactionRoot);
+      return this.read(input.executionKeyHash);
+    } catch (error) {
+      if (createdTransactionRoot && !existsSync(this.journalPath(input.executionKeyHash))) {
+        rmSync(transactionRoot, { recursive: true, force: true });
+      }
+      if (isNodeError(error) && error.code === 'EEXIST') {
+        throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan transaction already exists.', {
+          transactionId: input.executionKeyHash,
+        });
+      }
+      throw error;
+    }
+  }
+
+  read(transactionId: string): CorrectiveReplanTaskTransactionJournal {
+    return this.readValidated(transactionId, true);
+  }
+
+  readForObservation(transactionId: string): CorrectiveReplanTaskTransactionJournal {
+    return this.readValidated(transactionId, false);
+  }
+
+  private readValidated(
+    transactionId: string,
+    requireCanonicalTargets: boolean,
+  ): CorrectiveReplanTaskTransactionJournal {
+    assertHash(transactionId, 'Transaction id');
+    const file = this.journalPath(transactionId);
+    assertNoSymlinkPathComponents(file, { label: 'Task transaction journal', trustedRoot: this.trustedRoot, requireLeaf: true });
+    if (!existsSync(file)) throw new WorkflowError('NOT_FOUND', `Task transaction journal not found: ${transactionId}`);
+    let journal: unknown;
+    try {
+      journal = JSON.parse(readFileSync(file, 'utf8'));
+    } catch {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction journal is not valid JSON.');
+    }
+    validateJournal(journal, this.taskRoot, true, transactionId, requireCanonicalTargets);
+    return deepFreeze(structuredClone(journal as CorrectiveReplanTaskTransactionJournal));
+  }
+
+  journalPath(transactionId: string): string {
+    assertHash(transactionId, 'Transaction id');
+    return path.join(this.transactionRoot(transactionId), 'journal.json');
+  }
+
+  readOwnedPostimage(transactionId: string, requested: Pick<CorrectiveReplanTargetRecord, 'targetId'>): Buffer {
+    const journal = this.read(transactionId);
+    const target = journal.targets.find((row) => row.targetId === requested.targetId);
+    if (!target) throw new WorkflowError('INVALID_ARGUMENT', 'Unknown corrective-replan target.');
+    return readOwnedContent(this.taskRoot, transactionId, target);
+  }
+
+  readOwnedPreimage(
+    transactionId: string,
+    requested: Pick<CorrectiveReplanTargetRecord, 'targetId'>,
+  ): Buffer | null {
+    const journal = this.read(transactionId);
+    const target = journal.targets.find((row) => row.targetId === requested.targetId);
+    if (!target) throw new WorkflowError('INVALID_ARGUMENT', 'Unknown corrective-replan target.');
+    return readOwnedPreimage(this.taskRoot, transactionId, target);
+  }
+
+  captureCurrentTarget(
+    handle: unknown,
+    input: { taskId: string; operationId: string; targetId: TargetId },
+  ): Buffer | null {
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: input.taskId,
+      operationId: input.operationId,
+      transitionId: 'task.plan.corrective-replan',
+    });
+    const target = CORRECTIVE_REPLAN_TARGETS.find((candidate) => candidate.targetId === input.targetId);
+    if (!target) throw new WorkflowError('INVALID_ARGUMENT', 'Unknown corrective-replan target.');
+    const content = readTarget(this.taskRoot, target.relativePath).content;
+    return content === null ? null : Buffer.from(content);
+  }
+
+  compareAndSetPhase(
+    handle: unknown,
+    transactionId: string,
+    input: {
+      expectedPhase: CorrectiveReplanTransactionPhase;
+      expectedRevision: number;
+      nextPhase: CorrectiveReplanTransactionPhase;
+      nextTargetOrdinal: number;
+      completedResultSha256?: string;
+    },
+  ): CorrectiveReplanTaskTransactionJournal {
+    const current = this.read(transactionId);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: current.taskId, operationId: current.executionKeyHash, transitionId: current.transitionId,
+    });
+    if (current.phase !== input.expectedPhase || current.phaseRevision !== input.expectedRevision) {
+      throw new WorkflowError('STATE_CONFLICT', 'Task transaction phase compare-and-set conflict.');
+    }
+    assertPhaseTransition(current, input.nextPhase, input.nextTargetOrdinal);
+    if (current.phase === 'applying' && input.nextPhase === 'applying' && input.nextTargetOrdinal > 0) {
+      assertCanonicalTargetMatches(this.taskRoot, current.targets[input.nextTargetOrdinal - 1]!);
+    }
+    if (input.nextPhase === 'completed') {
+      assertHash(input.completedResultSha256, 'Completed Task transaction result hash');
+      assertCanonicalTargetsMatch(this.taskRoot, current);
+    } else if (input.completedResultSha256 !== undefined) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Only a completed Task transaction may bind a result hash.');
+    }
+    const previous = current.phaseHistory.at(-1)!;
+    const recordedAt = this.now().toISOString();
+    const nextEntry = phaseEntry(
+      current.phaseRevision,
+      input.nextPhase,
+      input.nextTargetOrdinal,
+      recordedAt,
+      previous.entryHash,
+      current.intentSha256,
+    );
+    const next: CorrectiveReplanTaskTransactionJournal = {
+      ...structuredClone(current),
+      phase: input.nextPhase,
+      phaseRevision: current.phaseRevision + 1,
+      nextTargetOrdinal: input.nextTargetOrdinal,
+      phaseHistory: [...current.phaseHistory, nextEntry],
+      completedResult: input.nextPhase === 'completed'
+        ? { resultSha256: input.completedResultSha256! }
+        : current.completedResult,
+      updatedAt: recordedAt,
+    };
+    validateJournal(next, this.taskRoot, true, transactionId);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: current.taskId, operationId: current.executionKeyHash, transitionId: current.transitionId,
+    });
+    writeAtomicDurable(this.journalPath(transactionId), jsonBuffer(next));
+    return this.read(transactionId);
+  }
+
+  applyTarget(
+    handle: unknown,
+    transactionId: string,
+    targetId: TargetId,
+  ): 'applied' | 'confirmed' {
+    const journal = this.read(transactionId);
+    if (journal.phase !== 'applying') {
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Target application requires an applying transaction.');
+    }
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: journal.taskId, operationId: journal.executionKeyHash, transitionId: journal.transitionId,
+    });
+    const target = journal.targets.find((candidate) => candidate.targetId === targetId);
+    if (!target || target.ordinal !== journal.nextTargetOrdinal) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Task transaction target is not the exact next target.');
+    }
+    const file = path.join(this.taskRoot, target.relativePath);
+    const current = readTarget(this.taskRoot, target.relativePath).content;
+    const currentHash = current === null ? null : sha256(current);
+    if (currentHash === target.postimage.contentSha256) return 'confirmed';
+    if (currentHash !== target.preimage.contentSha256) {
+      throw new WorkflowError('STATE_CONFLICT', 'Task target found neither the exact preimage nor exact result.', {
+        targetId,
+      });
+    }
+    const result = readOwnedContent(this.taskRoot, transactionId, target);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: journal.taskId, operationId: journal.executionKeyHash, transitionId: journal.transitionId,
+    });
+    writeAtomicDurable(file, result);
+    if (sha256(readFileSync(file)) !== target.postimage.contentSha256) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task target readback mismatch.', { targetId });
+    }
+    return 'applied';
+  }
+
+  applyTaskStateCas(handle: unknown, transactionId: string): 'applied' | 'confirmed' {
+    return this.applyTarget(handle, transactionId, 'task-state');
+  }
+
+  readCanonicalTarget(handle: unknown, transactionId: string, targetId: TargetId): Buffer {
+    const journal = this.read(transactionId);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: journal.taskId,
+      operationId: journal.executionKeyHash,
+      transitionId: journal.transitionId,
+    });
+    const target = journal.targets.find((candidate) => candidate.targetId === targetId);
+    if (!target) throw new WorkflowError('INVALID_ARGUMENT', 'Unknown corrective-replan target.');
+    assertCanonicalTargetMatches(this.taskRoot, target);
+    return Buffer.from(readTarget(this.taskRoot, target.relativePath).content!);
+  }
+
+  readCompletedTarget(transactionId: string, targetId: TargetId): Buffer {
+    const journal = this.read(transactionId);
+    if (journal.phase !== 'completed') {
+      throw new WorkflowError('TASK_RECOVERY_REQUIRED', 'Task transaction is not completed.');
+    }
+    const target = journal.targets.find((candidate) => candidate.targetId === targetId);
+    if (!target) throw new WorkflowError('INVALID_ARGUMENT', 'Unknown corrective-replan target.');
+    return Buffer.from(readTarget(this.taskRoot, target.relativePath).content!);
+  }
+
+  private transactionRoot(transactionId: string): string {
+    assertHash(transactionId, 'Transaction id');
+    return path.join(this.taskRoot, '.transactions', transactionId);
+  }
+}
+
+export function inspectCorrectiveReplanTaskTransactions(
+  projectRoot: string,
+  trustedRoot: string,
+): { pending: ObservedTaskTransaction[]; completed: ObservedTaskTransaction[]; corrupt: CorruptObservedTaskTransaction[] } {
+  const resolvedProject = path.resolve(projectRoot);
+  const resolvedTrusted = path.resolve(trustedRoot);
+  if (!existsSync(resolvedTrusted) || !existsSync(resolvedProject)) {
+    return deepFreeze({ pending: [], completed: [], corrupt: [] });
+  }
+  assertNoSymlinkPathComponents(resolvedProject, { label: 'Project transaction observation root', trustedRoot: resolvedTrusted });
+  const tasksRoot = path.join(resolvedProject, 'tasks');
+  if (!existsSync(tasksRoot)) return deepFreeze({ pending: [], completed: [], corrupt: [] });
+  assertNoSymlinkPathComponents(tasksRoot, { label: 'Task transaction observation root', trustedRoot: resolvedTrusted, requireLeaf: true });
+  const pending: ObservedTaskTransaction[] = [];
+  const completed: ObservedTaskTransaction[] = [];
+  const corrupt: CorruptObservedTaskTransaction[] = [];
+  for (const taskEntry of readdirSync(tasksRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const taskPath = path.join(tasksRoot, taskEntry.name);
+    if (taskEntry.isSymbolicLink()) throw new WorkflowError('STATE_CORRUPT', 'Task observation root must not be a symlink.');
+    if (!taskEntry.isDirectory() || !TASK.test(taskEntry.name)) continue;
+    const transactionRoot = path.join(taskPath, '.transactions');
+    if (!existsSync(transactionRoot)) continue;
+    assertNoSymlinkPathComponents(transactionRoot, { label: 'Task transaction directory', trustedRoot: resolvedTrusted, requireLeaf: true });
+    for (const entry of readdirSync(transactionRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.isSymbolicLink()) throw new WorkflowError('STATE_CORRUPT', 'Task transaction entry must not be a symlink.');
+      if (!entry.isDirectory()) continue;
+      const transactionId = HASH.test(entry.name) ? entry.name : 'invalid-transaction-id';
+      if (!HASH.test(entry.name)) {
+        corrupt.push({ taskId: taskEntry.name, transactionId, reason: 'journal-invalid' });
+        continue;
+      }
+      try {
+        const store = new CorrectiveReplanTaskTransactionStore({
+          taskRoot: taskPath,
+          locksRoot: path.join(resolvedProject, 'locks'),
+          trustedRoot: resolvedTrusted,
+        });
+        const journal = store.readForObservation(entry.name);
+        (journal.phase === 'completed' ? completed : pending).push({
+          transitionId: journal.transitionId,
+          taskId: journal.taskId,
+          transactionId: journal.transactionId,
+          phase: journal.phase,
+          phaseRevision: journal.phaseRevision,
+          updatedAt: journal.updatedAt,
+        });
+      } catch {
+        corrupt.push({ taskId: taskEntry.name, transactionId, reason: 'journal-invalid' });
+      }
+    }
+  }
+  return deepFreeze({
+    completed: completed.sort((a, b) => a.taskId.localeCompare(b.taskId) || a.transactionId.localeCompare(b.transactionId)),
+    pending: pending.sort((a, b) => a.taskId.localeCompare(b.taskId) || a.transactionId.localeCompare(b.transactionId)),
+    corrupt: corrupt.sort((a, b) => a.taskId.localeCompare(b.taskId) || a.transactionId.localeCompare(b.transactionId)),
+  });
+}
+
+export function assertTaskTransactionBoundary(
+  projectRoot: string,
+  trustedRoot: string,
+  taskId?: string,
+): void {
+  const observed = inspectCorrectiveReplanTaskTransactions(projectRoot, trustedRoot);
+  const corrupt = taskId === undefined
+    ? observed.corrupt
+    : observed.corrupt.filter((transaction) => transaction.taskId === taskId);
+  if (corrupt.length > 0) {
+    throw new WorkflowError('STATE_CORRUPT', 'A Task transaction journal failed integrity validation.', {
+      transactions: corrupt,
+    });
+  }
+  const pending = taskId === undefined
+    ? observed.pending
+    : observed.pending.filter((transaction) => transaction.taskId === taskId);
+  if (pending.length > 0) {
+    throw new WorkflowError('TASK_RECOVERY_REQUIRED', 'A Task transaction requires explicit recovery.', {
+      taskIds: [...new Set(pending.map((transaction) => transaction.taskId))].sort(),
+      transactionIds: pending.map((transaction) => transaction.transactionId).sort(),
+    });
+  }
+}
+
+function assertHeader(input: CreateCorrectiveReplanIntentInput): void {
+  if (!PROJECT.test(input.projectId) || !TASK.test(input.taskId) || input.transitionId !== 'task.plan.corrective-replan') {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan intent identity is invalid.');
+  }
+  [input.executionKeyHash, input.runtimeFingerprint, input.catalogHash, input.bindingManifest?.manifestSha256,
+    input.bindingSha256, input.receiptHash, input.actorIdentityHash, input.humanPrincipalIdentityHash]
+    .forEach((value) => assertHash(value, 'Corrective-replan binding hash'));
+  if (input.bindingManifest?.id !== correctiveReplanBindingManifest.id
+    || input.bindingManifest.version !== correctiveReplanBindingManifest.version
+    || input.bindingManifest.manifestSha256 !== correctiveReplanBindingManifest.manifestSha256) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan binding manifest identity is invalid.');
+  }
+  if (!Number.isSafeInteger(input.lifecycleEpoch) || input.lifecycleEpoch < 1
+    || !Number.isSafeInteger(input.expectedTaskRevision) || input.expectedTaskRevision < 1
+    || input.resultTaskRevision !== input.expectedTaskRevision + 1) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan revision or epoch is invalid.');
+  }
+}
+
+function normalizePostimages(value: CreateCorrectiveReplanIntentInput['postimages']): Buffer[] {
+  assertPlainExact(value, ['executionEvidence', 'plan', 'planRiskAudit', 'planValidation', 'taskState'], 'Postimages');
+  return [value.taskState, value.plan, value.planValidation, value.planRiskAudit, value.executionEvidence].map((item) => {
+    if (!(item instanceof Uint8Array) || item.byteLength === 0 || item.byteLength > MAX_TARGET_BYTES) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Each corrective-replan postimage must contain bounded owned bytes.');
+    }
+    return Buffer.from(item);
+  });
+}
+
+function validateTaskStatePair(
+  preimage: Buffer | null,
+  postimage: Buffer,
+  projectId: string,
+  taskId: string,
+  expectedTaskRevision: number,
+  resultTaskRevision: number,
+): void {
+  if (!preimage) throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan Task preimage is missing.');
+  const before = parseJsonRecord(preimage, 'Task preimage');
+  const after = parseJsonRecord(postimage, 'Task postimage');
+  for (const value of [before, after]) {
+    if (value.kind !== 'task' || value.projectId !== projectId || value.id !== taskId) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan Task bytes have the wrong identity.');
+    }
+  }
+  if (before.revision !== expectedTaskRevision || after.revision !== resultTaskRevision) {
+    throw new WorkflowError('STATE_CONFLICT', 'Corrective-replan Task bytes have the wrong revision CAS.');
+  }
+}
+
+function sidecarAnchors(preimage: Buffer | null, result: Buffer): NonNullable<CorrectiveReplanTargetRecord['sidecarAnchors']> {
+  const before = jsonLines(preimage);
+  const after = jsonLines(result);
+  if (after.length !== before.length + 1 || (preimage && !result.subarray(0, preimage.byteLength).equals(preimage))) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan sidecar postimage must append exactly one event.');
+  }
+  const previousEventHash = before.length === 0 ? null : eventHash(before.at(-1)!);
+  const appended = after.at(-1)!;
+  const resultEventHash = eventHash(appended);
+  if (appended.previousEventHash !== previousEventHash) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-replan sidecar event does not bind the current tail.');
+  }
+  return { previousEventHash, resultEventHash, previousLineCount: before.length, resultLineCount: after.length };
+}
+
+function jsonLines(content: Buffer | null): Array<Record<string, unknown>> {
+  if (!content || content.byteLength === 0) return [];
+  const text = content.toString('utf8');
+  if (!text.endsWith('\n')) throw new WorkflowError('INVALID_ARGUMENT', 'Sidecar bytes must end with a newline.');
+  return text.slice(0, -1).split('\n').map((line) => parseJsonRecord(Buffer.from(line), 'Sidecar event'));
+}
+
+function eventHash(event: Record<string, unknown>): string {
+  assertHash(event.eventHash, 'Sidecar eventHash');
+  return event.eventHash;
+}
+
+function validateJournal(
+  value: unknown,
+  taskRoot: string,
+  verifyOwnedContent: boolean,
+  expectedTransactionId: string,
+  requireCanonicalTargets = true,
+): asserts value is CorrectiveReplanTaskTransactionJournal {
+  if (validateSchema(value) !== true) throw new WorkflowError('STATE_CORRUPT', 'Task transaction journal schema is invalid.');
+  const journal = value as CorrectiveReplanTaskTransactionJournal;
+  assertStoredIso(journal.admittedAt);
+  assertStoredIso(journal.updatedAt);
+  if (journal.transactionId !== journal.executionKeyHash || journal.transactionId !== expectedTransactionId
+    || journal.taskId !== path.basename(taskRoot)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction path identity mismatch.');
+  }
+  if (!hasSupportedBindingIdentity(journal)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction binding manifest mismatch.');
+  }
+  if (journal.intentSha256 !== intentHash(journal)) throw new WorkflowError('STATE_CORRUPT', 'Task transaction intent hash mismatch.');
+  CORRECTIVE_REPLAN_TARGETS.forEach((expected, ordinal) => {
+    const actual = journal.targets[ordinal];
+    if (!actual || actual.targetId !== expected.targetId || actual.ordinal !== ordinal
+      || actual.relativePath !== expected.relativePath || actual.writeMode !== expected.writeMode
+      || (ordinal === 0) !== (actual.taskCas !== null) || (ordinal >= 2) !== (actual.sidecarAnchors !== null)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction target inventory mismatch.');
+    }
+    if (actual.preimage.exists !== (actual.preimage.contentPath !== null)
+      || actual.preimage.exists !== (actual.preimage.contentSha256 !== null)
+      || actual.preimage.contentPath !== (actual.preimage.exists ? `preimages/${ordinal}.bin` : null)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction preimage ownership mismatch.');
+    }
+    if (verifyOwnedContent) {
+      const preimage = readOwnedPreimage(taskRoot, journal.transactionId, actual);
+      const postimage = readOwnedContent(taskRoot, journal.transactionId, actual);
+      if (ordinal === 0) {
+        validateTaskStatePair(
+          preimage,
+          postimage,
+          journal.projectId,
+          journal.taskId,
+          actual.taskCas!.expectedRevision,
+          actual.taskCas!.resultRevision,
+        );
+      }
+      if (ordinal >= 2) {
+        const anchors = sidecarAnchors(preimage, postimage);
+        if (JSON.stringify(anchors) !== JSON.stringify(actual.sidecarAnchors)) {
+          throw new WorkflowError('STATE_CORRUPT', 'Task transaction sidecar anchors mismatch.');
+        }
+      }
+    }
+  });
+  if (journal.phaseHistory.length !== journal.phaseRevision) throw new WorkflowError('STATE_CORRUPT', 'Task transaction phase revision mismatch.');
+  journal.phaseHistory.forEach((entry, index) => {
+    assertStoredIso(entry.recordedAt);
+    const previous = index === 0 ? null : journal.phaseHistory[index - 1]!.entryHash;
+    if (index > 0 && entry.recordedAt < journal.phaseHistory[index - 1]!.recordedAt) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction phase time moved backwards.');
+    }
+    if (entry.sequence !== index || entry.previousEntryHash !== previous
+      || entry.entryHash !== phaseEntryHash(
+        entry.sequence,
+        entry.phase,
+        entry.nextTargetOrdinal,
+        entry.recordedAt,
+        previous,
+        journal.intentSha256,
+      )) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction phase hash chain mismatch.');
+    }
+    if (index === 0 && (entry.phase !== 'intent' || entry.nextTargetOrdinal !== 0 || entry.recordedAt !== journal.admittedAt)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction phase history must start at intent.');
+    }
+    if (index > 0 && !isStoredPhaseTransition(journal.phaseHistory[index - 1]!, entry)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Task transaction phase topology mismatch.');
+    }
+  });
+  const last = journal.phaseHistory.at(-1)!;
+  if (last.phase !== journal.phase || last.nextTargetOrdinal !== journal.nextTargetOrdinal || last.recordedAt !== journal.updatedAt) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction current phase projection mismatch.');
+  }
+  if ((journal.phase === 'completed') !== (journal.completedResult !== null)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction completion result mismatch.');
+  }
+  if (journal.phaseRevision > 9) throw new WorkflowError('STATE_CORRUPT', 'Task transaction phase cardinality mismatch.');
+  if (verifyOwnedContent && requireCanonicalTargets && journal.phase === 'completed') {
+    assertCanonicalTargetsMatch(taskRoot, journal);
+  }
+}
+
+function hasSupportedBindingIdentity(journal: CorrectiveReplanTaskTransactionJournal): boolean {
+  if (journal.bindingManifest.id !== correctiveReplanBindingManifest.id
+    || journal.bindingManifest.version !== correctiveReplanBindingManifest.version) return false;
+  if (journal.bindingManifest.manifestSha256 === correctiveReplanBindingManifest.manifestSha256) return true;
+  return journal.phase === 'completed' && historicalCompletedCorrectiveReplanBindingIdentities.some((identity) =>
+    identity.manifestSha256 === journal.bindingManifest.manifestSha256
+    && identity.runtimeFingerprint === journal.runtimeFingerprint
+    && identity.catalogHash === journal.catalogHash);
+}
+
+function isStoredPhaseTransition(
+  previous: CorrectiveReplanTaskTransactionJournal['phaseHistory'][number],
+  next: CorrectiveReplanTaskTransactionJournal['phaseHistory'][number],
+): boolean {
+  return previous.phase === 'intent' && previous.nextTargetOrdinal === 0
+      && next.phase === 'applying' && next.nextTargetOrdinal === 0
+    || previous.phase === 'applying' && next.phase === 'applying'
+      && next.nextTargetOrdinal === previous.nextTargetOrdinal + 1
+      && next.nextTargetOrdinal <= CORRECTIVE_REPLAN_TARGETS.length
+    || previous.phase === 'applying' && previous.nextTargetOrdinal === CORRECTIVE_REPLAN_TARGETS.length
+      && next.phase === 'published-pending-readback' && next.nextTargetOrdinal === CORRECTIVE_REPLAN_TARGETS.length
+    || previous.phase === 'published-pending-readback' && next.phase === 'completed'
+      && next.nextTargetOrdinal === CORRECTIVE_REPLAN_TARGETS.length;
+}
+
+function assertPhaseTransition(
+  current: CorrectiveReplanTaskTransactionJournal,
+  next: CorrectiveReplanTransactionPhase,
+  ordinal: number,
+): void {
+  const allowed = current.phase === 'intent' && next === 'applying' && ordinal === 0
+    || current.phase === 'applying' && next === 'applying'
+      && ordinal === current.nextTargetOrdinal + 1 && ordinal <= CORRECTIVE_REPLAN_TARGETS.length
+    || current.phase === 'applying' && next === 'published-pending-readback'
+      && current.nextTargetOrdinal === CORRECTIVE_REPLAN_TARGETS.length
+      && ordinal === CORRECTIVE_REPLAN_TARGETS.length
+    || current.phase === 'published-pending-readback' && next === 'completed'
+      && ordinal === CORRECTIVE_REPLAN_TARGETS.length;
+  if (!allowed) throw new WorkflowError('INVALID_ARGUMENT', 'Invalid Task transaction phase transition.');
+}
+
+function phaseEntry(
+  sequence: number,
+  phase: CorrectiveReplanTransactionPhase,
+  nextTargetOrdinal: number,
+  recordedAt: string,
+  previousEntryHash: string | null,
+  intentSha256: string,
+) {
+  assertIso(recordedAt, 'phase recordedAt');
+  return {
+    sequence, phase, nextTargetOrdinal, recordedAt, previousEntryHash,
+    entryHash: phaseEntryHash(sequence, phase, nextTargetOrdinal, recordedAt, previousEntryHash, intentSha256),
+  };
+}
+
+function phaseEntryHash(
+  sequence: number,
+  phase: CorrectiveReplanTransactionPhase,
+  nextTargetOrdinal: number,
+  recordedAt: string,
+  previousEntryHash: string | null,
+  intentSha256: string,
+): string {
+  return sha256(Buffer.from(JSON.stringify({
+    domain: 'codex-workflow/corrective-replan-task-transaction-phase/v1',
+    intentSha256, sequence, phase, nextTargetOrdinal, recordedAt, previousEntryHash,
+  })));
+}
+
+function intentHash(journal: CorrectiveReplanTaskTransactionJournal): string {
+  return sha256(Buffer.from(JSON.stringify({
+    domain: 'codex-workflow/corrective-replan-task-transaction-intent/v1',
+    schemaVersion: journal.schemaVersion,
+    kind: journal.kind,
+    transactionId: journal.transactionId,
+    projectId: journal.projectId,
+    taskId: journal.taskId,
+    transitionId: journal.transitionId,
+    executionKeyHash: journal.executionKeyHash,
+    runtimeFingerprint: journal.runtimeFingerprint,
+    catalogHash: journal.catalogHash,
+    lifecycleEpoch: journal.lifecycleEpoch,
+    bindingManifest: journal.bindingManifest,
+    bindingSha256: journal.bindingSha256,
+    receiptHash: journal.receiptHash,
+    actorIdentityHash: journal.actorIdentityHash,
+    humanPrincipalIdentityHash: journal.humanPrincipalIdentityHash,
+    admittedAt: journal.admittedAt,
+    targets: journal.targets,
+  })));
+}
+
+function readTarget(taskRoot: string, relativePath: string): { content: Buffer | null } {
+  const file = path.join(taskRoot, relativePath);
+  assertNoSymlinkPathComponents(file, { label: 'Corrective-replan target', trustedRoot: taskRoot });
+  if (!existsSync(file)) return { content: null };
+  const stat = lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new WorkflowError('STATE_CORRUPT', 'Corrective-replan target must be a regular file.');
+  return { content: readFileSync(file) };
+}
+
+function snapshot(content: Buffer | null, ordinal: number): CorrectiveReplanTargetRecord['preimage'] {
+  return content === null
+    ? { exists: false, contentSha256: null, byteLength: 0, contentPath: null }
+    : { exists: true, contentSha256: sha256(content), byteLength: content.byteLength, contentPath: `preimages/${ordinal}.bin` };
+}
+
+function readOwnedPreimage(
+  taskRoot: string,
+  transactionId: string,
+  target: CorrectiveReplanTargetRecord,
+): Buffer | null {
+  if (!target.preimage.exists) return null;
+  if (target.preimage.contentPath !== `preimages/${target.ordinal}.bin`) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction preimage path mismatch.');
+  }
+  const file = path.join(taskRoot, '.transactions', transactionId, target.preimage.contentPath);
+  assertNoSymlinkPathComponents(file, { label: 'Task transaction owned preimage', trustedRoot: taskRoot, requireLeaf: true });
+  if (!existsSync(file)) throw new WorkflowError('STATE_CORRUPT', 'Task transaction owned preimage is missing.');
+  const content = readFileSync(file);
+  if (content.byteLength !== target.preimage.byteLength || sha256(content) !== target.preimage.contentSha256) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction owned preimage digest mismatch.');
+  }
+  return content;
+}
+
+function assertCanonicalTargetsMatch(taskRoot: string, journal: CorrectiveReplanTaskTransactionJournal): void {
+  for (const target of journal.targets) {
+    assertCanonicalTargetMatches(taskRoot, target);
+  }
+}
+
+function assertCanonicalTargetMatches(taskRoot: string, target: CorrectiveReplanTargetRecord): void {
+  const current = readTarget(taskRoot, target.relativePath).content;
+  if (current === null || sha256(current) !== target.postimage.contentSha256) {
+    throw new WorkflowError('STATE_CONFLICT', 'Task transaction target readback mismatch.', {
+      targetId: target.targetId,
+    });
+  }
+}
+
+function readOwnedContent(taskRoot: string, transactionId: string, target: CorrectiveReplanTargetRecord): Buffer {
+  if (target.postimage.contentPath !== `targets/${target.ordinal}.bin`) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction owned-content path mismatch.');
+  }
+  const file = path.join(taskRoot, '.transactions', transactionId, target.postimage.contentPath);
+  assertNoSymlinkPathComponents(file, { label: 'Task transaction owned content', trustedRoot: taskRoot, requireLeaf: true });
+  if (!existsSync(file)) throw new WorkflowError('STATE_CORRUPT', 'Task transaction owned content is missing.');
+  const content = readFileSync(file);
+  if (content.byteLength !== target.postimage.byteLength || sha256(content) !== target.postimage.contentSha256) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction owned content digest mismatch.');
+  }
+  return content;
+}
+
+function parseJsonRecord(content: Buffer, label: string): Record<string, unknown> {
+  try {
+    const value = JSON.parse(content.toString('utf8')) as unknown;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('not an object');
+    return value as Record<string, unknown>;
+  } catch {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must contain one JSON object.`);
+  }
+}
+
+function assertPlainExact(value: unknown, keys: string[], label: string): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must be a plain object.`);
+  }
+  const actual = Object.keys(value).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 assertTaskRoot(taskRoot: string, trustedRoot: string): void {
+  if (!path.resolve(taskRoot).startsWith(`${path.resolve(trustedRoot)}${path.sep}`)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Task transaction root is outside the trusted state root.');
+  }
+  assertNoSymlinkPathComponents(taskRoot, { label: 'Task transaction root', trustedRoot, requireLeaf: true });
+}
+
+function ensureDirectorySafe(directory: string, trustedRoot: string): void {
+  if (!existsSync(directory)) mkdirSync(directory, { recursive: true, mode: 0o700 });
+  assertNoSymlinkPathComponents(directory, { label: 'Task transaction directory', trustedRoot, requireLeaf: true });
+}
+
+function writeNewDurable(file: string, content: Buffer): void {
+  let descriptor: number | null = null;
+  try {
+    descriptor = openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    writeSync(descriptor, content);
+    fsyncSync(descriptor);
+  } finally {
+    if (descriptor !== null) closeSync(descriptor);
+  }
+}
+
+function writeAtomicDurable(file: string, content: Buffer): void {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`);
+  let descriptor: number | null = null;
+  try {
+    descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    writeSync(descriptor, content);
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = null;
+    renameSync(temporary, file);
+    fsyncDirectory(path.dirname(file));
+  } finally {
+    if (descriptor !== null) closeSync(descriptor);
+    rmSync(temporary, { force: true });
+  }
+}
+
+function fsyncDirectory(directory: string): void {
+  const descriptor = openSync(directory, 'r');
+  try { fsyncSync(descriptor); } finally { closeSync(descriptor); }
+}
+
+function jsonBuffer(value: unknown): Buffer {
+  return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function sha256(value: Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+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 assertIso(value: string, label: string): void {
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value) {
+    throw new WorkflowError('INVALID_ARGUMENT', `${label} must be a canonical UTC timestamp.`);
+  }
+}
+
+function assertStoredIso(value: string): void {
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value) {
+    throw new WorkflowError('STATE_CORRUPT', 'Task transaction contains a noncanonical timestamp.');
+  }
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error;
+}