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

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

@@ -0,0 +1,730 @@
+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, computeSidecarEventHash } from '../alpha6/store-sidecars.js';
+import { hashCanonical } from '../lifecycle/fingerprint.js';
+import { deepFreeze } from '../lifecycle/immutable.js';
+import {
+  WriterLockManager,
+  assertCoreTaskOperationHandle,
+  type CoreTaskOperationHandle,
+  type WriterLeaseHandle,
+} from './lock.js';
+
+const HASH = /^[a-f0-9]{64}$/;
+const TASK = /^TASK-[0-9A-HJKMNP-TV-Z]{26}$/;
+const PROJECT = /^[a-f0-9]{24}$/;
+const TRANSITION = 'task.coordination.corrective-yield' as const;
+const schema = JSON.parse(readFileSync(
+  new URL('../../../schemas/corrective-yield-task-transaction.private.schema.json', import.meta.url),
+  'utf8',
+)) as object;
+const ajv = new Ajv2020({
+  allErrors: true,
+  strict: true,
+  formats: {
+    'date-time': {
+      type: 'string',
+      validate(value: string) {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+      },
+    },
+  },
+});
+if (!ajv.validateSchema(schema)) throw new TypeError(`Invalid corrective-yield transaction schema: ${ajv.errorsText(ajv.errors)}`);
+const validateSchema = ajv.compile(schema);
+
+export type CorrectiveYieldTransactionPhase = 'intent' | 'applying' | 'published-pending-readback' | 'completed';
+
+interface SnapshotRecord {
+  exists: boolean;
+  contentSha256: string | null;
+  byteLength: number;
+  contentPath: 'preimages/0.bin' | null;
+}
+
+export interface CorrectiveYieldTaskTransactionJournal {
+  schemaVersion: 1;
+  kind: 'corrective-yield-task-transaction';
+  transactionId: string;
+  projectId: string;
+  taskId: string;
+  transitionId: typeof TRANSITION;
+  taskStateSha256: string;
+  actor: string;
+  writerLeaseTokenSha256: string;
+  writerLeaseContentSha256: string;
+  writerLeaseExpiresAt: string;
+  admittedAt: string;
+  intentSha256: string;
+  phase: CorrectiveYieldTransactionPhase;
+  phaseRevision: number;
+  nextTargetOrdinal: number;
+  handoffTarget: {
+    targetId: 'handoff-event';
+    ordinal: 0;
+    relativePath: 'handoffs.jsonl';
+    preimage: SnapshotRecord;
+    postimage: { contentSha256: string; byteLength: number; contentPath: 'targets/0.bin' };
+    previousEventHash: string | null;
+    resultEventHash: string;
+  };
+  phaseHistory: Array<{
+    sequence: number;
+    phase: CorrectiveYieldTransactionPhase;
+    nextTargetOrdinal: number;
+    recordedAt: string;
+    previousEntryHash: string | null;
+    entryHash: string;
+  }>;
+  completedResult: { resultSha256: string } | null;
+  updatedAt: string;
+}
+
+export interface CreateCorrectiveYieldIntentInput {
+  projectId: string;
+  taskId: string;
+  transactionId: string;
+  taskStateSha256: string;
+  actor: string;
+  writerLeaseTokenSha256: string;
+  writerLeaseContentSha256: string;
+  writerLeaseExpiresAt: string;
+  handoffPostimage: Uint8Array;
+}
+
+export class CorrectiveYieldTaskTransactionStore {
+  private readonly taskRoot: string;
+  private readonly locksRoot: string;
+  private readonly trustedRoot: string;
+  private readonly now: () => Date;
+  private readonly writerLocks: WriterLockManager;
+
+  constructor(options: { taskRoot: string; locksRoot: string; trustedRoot: string; now?: () => Date }) {
+    this.taskRoot = path.resolve(options.taskRoot);
+    this.locksRoot = path.resolve(options.locksRoot);
+    this.trustedRoot = path.resolve(options.trustedRoot);
+    this.now = options.now ?? (() => new Date());
+    this.writerLocks = new WriterLockManager(this.locksRoot, this.now, this.trustedRoot);
+    assertTaskRoot(this.taskRoot, this.trustedRoot);
+  }
+
+  createIntent(writerHandle: WriterLeaseHandle, input: CreateCorrectiveYieldIntentInput): CorrectiveYieldTaskTransactionJournal {
+    assertExactRecord(input, [
+      'actor', 'handoffPostimage', 'projectId', 'taskId', 'taskStateSha256', 'transactionId',
+      'writerLeaseContentSha256', 'writerLeaseExpiresAt', 'writerLeaseTokenSha256',
+    ], 'Corrective-yield intent');
+    assertIntent(input);
+    const proof = this.writerLocks.proofBinding(writerHandle);
+    if (proof.entityId !== input.taskId || proof.owner !== input.actor
+      || proof.tokenSha256 !== input.writerLeaseTokenSha256
+      || proof.contentSha256 !== input.writerLeaseContentSha256
+      || proof.expiresAt !== input.writerLeaseExpiresAt) {
+      throw new WorkflowError('LOCK_TOKEN_INVALID', 'Writer lease proof does not match the corrective-yield intent.');
+    }
+    const stateBytes = readRequired(this.targetPath('state.json'), this.taskRoot);
+    if (sha256(stateBytes) !== input.taskStateSha256) {
+      throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield Task snapshot changed before intent.');
+    }
+    const preimage = readOptional(this.targetPath('handoffs.jsonl'), this.taskRoot);
+    const postimage = Buffer.from(input.handoffPostimage);
+    const anchors = validateAppend(preimage, postimage, input.transactionId, input.actor, input.writerLeaseTokenSha256);
+    const root = this.transactionRoot(input.transactionId);
+    if (existsSync(root)) throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield transaction already exists.');
+    const admittedAt = this.now().toISOString();
+    const journal: CorrectiveYieldTaskTransactionJournal = {
+      schemaVersion: 1,
+      kind: 'corrective-yield-task-transaction',
+      transactionId: input.transactionId,
+      projectId: input.projectId,
+      taskId: input.taskId,
+      transitionId: TRANSITION,
+      taskStateSha256: input.taskStateSha256,
+      actor: input.actor,
+      writerLeaseTokenSha256: input.writerLeaseTokenSha256,
+      writerLeaseContentSha256: input.writerLeaseContentSha256,
+      writerLeaseExpiresAt: input.writerLeaseExpiresAt,
+      admittedAt,
+      intentSha256: '0'.repeat(64),
+      phase: 'intent',
+      phaseRevision: 1,
+      nextTargetOrdinal: 0,
+      handoffTarget: {
+        targetId: 'handoff-event',
+        ordinal: 0,
+        relativePath: 'handoffs.jsonl',
+        preimage: snapshot(preimage),
+        postimage: { contentSha256: sha256(postimage), byteLength: postimage.byteLength, contentPath: 'targets/0.bin' },
+        ...anchors,
+      },
+      phaseHistory: [],
+      completedResult: null,
+      updatedAt: admittedAt,
+    };
+    journal.intentSha256 = intentHash(journal);
+    journal.phaseHistory = [phaseEntry(0, 'intent', 0, admittedAt, null, journal.intentSha256)];
+    validateJournal(journal, this.taskRoot, false);
+    ensureDirectorySafe(path.dirname(root), this.trustedRoot);
+    let created = false;
+    try {
+      mkdirSync(root, { mode: 0o700 });
+      created = true;
+      mkdirSync(path.join(root, 'preimages'), { mode: 0o700 });
+      mkdirSync(path.join(root, 'targets'), { mode: 0o700 });
+      if (preimage) writeNewDurable(path.join(root, 'preimages', '0.bin'), preimage);
+      writeNewDurable(path.join(root, 'targets', '0.bin'), postimage);
+      this.writerLocks.proofBinding(writerHandle);
+      writeNewDurable(this.journalPath(input.transactionId), jsonBytes(journal));
+      fsyncDirectory(root);
+      return this.read(input.transactionId);
+    } catch (error) {
+      if (created && !existsSync(this.journalPath(input.transactionId))) rmSync(root, { recursive: true, force: true });
+      throw error;
+    }
+  }
+
+  read(transactionId: string): CorrectiveYieldTaskTransactionJournal {
+    assertHash(transactionId, 'Corrective-yield transaction id');
+    const file = this.journalPath(transactionId);
+    assertNoSymlinkPathComponents(file, { label: 'Corrective-yield journal', trustedRoot: this.trustedRoot, requireLeaf: true });
+    if (!existsSync(file)) throw new WorkflowError('NOT_FOUND', `Corrective-yield journal not found: ${transactionId}`);
+    let value: unknown;
+    try { value = JSON.parse(readFileSync(file, 'utf8')); } catch { throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield journal is not valid JSON.'); }
+    validateJournal(value, this.taskRoot, true);
+    const journal = value as CorrectiveYieldTaskTransactionJournal;
+    if (journal.transactionId !== transactionId || journal.taskId !== path.basename(this.taskRoot)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield journal path identity mismatch.');
+    }
+    return deepFreeze(structuredClone(journal));
+  }
+
+  journalPath(transactionId: string): string {
+    assertHash(transactionId, 'Corrective-yield transaction id');
+    return path.join(this.transactionRoot(transactionId), 'journal.json');
+  }
+
+  advanceWithWriter(
+    writerHandle: WriterLeaseHandle,
+    transactionId: string,
+    expectedPhase: CorrectiveYieldTransactionPhase,
+    expectedRevision: number,
+    nextPhase: CorrectiveYieldTransactionPhase,
+    nextTargetOrdinal: number,
+  ): CorrectiveYieldTaskTransactionJournal {
+    const journal = this.read(transactionId);
+    const proof = this.writerLocks.proofBinding(writerHandle);
+    if (proof.entityId !== journal.taskId || proof.tokenSha256 !== journal.writerLeaseTokenSha256) {
+      throw new WorkflowError('LOCK_TOKEN_INVALID', 'Writer proof does not own the corrective-yield transaction.');
+    }
+    return this.advance(journal, expectedPhase, expectedRevision, nextPhase, nextTargetOrdinal);
+  }
+
+  advanceWithCore(
+    handle: CoreTaskOperationHandle,
+    transactionId: string,
+    expectedPhase: CorrectiveYieldTransactionPhase,
+    expectedRevision: number,
+    nextPhase: CorrectiveYieldTransactionPhase,
+    nextTargetOrdinal: number,
+    completedResultSha256?: string,
+  ): CorrectiveYieldTaskTransactionJournal {
+    const journal = this.read(transactionId);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: journal.taskId,
+      operationId: journal.transactionId,
+      transitionId: journal.transitionId,
+    });
+    return this.advance(journal, expectedPhase, expectedRevision, nextPhase, nextTargetOrdinal, completedResultSha256);
+  }
+
+  applyHandoffWithWriter(writerHandle: WriterLeaseHandle, transactionId: string): 'applied' | 'confirmed' {
+    const journal = this.read(transactionId);
+    const proof = this.writerLocks.proofBinding(writerHandle);
+    if (proof.entityId !== journal.taskId || proof.tokenSha256 !== journal.writerLeaseTokenSha256) {
+      throw new WorkflowError('LOCK_TOKEN_INVALID', 'Writer proof does not own the corrective-yield transaction.');
+    }
+    return this.applyHandoff(journal);
+  }
+
+  applyHandoffWithCore(handle: CoreTaskOperationHandle, transactionId: string): 'applied' | 'confirmed' {
+    const journal = this.read(transactionId);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: journal.taskId,
+      operationId: journal.transactionId,
+      transitionId: journal.transitionId,
+    });
+    return this.applyHandoff(journal);
+  }
+
+  domainReadback(handle: CoreTaskOperationHandle, transactionId: string): string {
+    const journal = this.read(transactionId);
+    assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now(), {
+      entityId: journal.taskId,
+      operationId: journal.transactionId,
+      transitionId: journal.transitionId,
+    });
+    if (journal.phase !== 'published-pending-readback') {
+      throw new WorkflowError('TASK_RECOVERY_REQUIRED', 'Corrective-yield domain readback requires its published phase.');
+    }
+    assertCanonicalHandoff(this.taskRoot, journal);
+    assertTaskState(this.taskRoot, journal.taskStateSha256);
+    return resultHash(journal);
+  }
+
+  terminalReadback(transactionId: string): string {
+    const journal = this.read(transactionId);
+    if (journal.phase !== 'completed' || !journal.completedResult) {
+      throw new WorkflowError('TASK_RECOVERY_REQUIRED', 'Corrective-yield transaction is not terminal.');
+    }
+    assertCanonicalHandoffRetained(this.taskRoot, journal);
+    if (existsSync(path.join(this.locksRoot, `${journal.taskId}.json`))) {
+      throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield terminal readback requires the writer/Core lock slot to be empty.');
+    }
+    const result = resultHash(journal);
+    if (result !== journal.completedResult.resultSha256) {
+      throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield completed result digest mismatch.');
+    }
+    return result;
+  }
+
+  handoffIsPostimage(journal: CorrectiveYieldTaskTransactionJournal): boolean {
+    const current = readOptional(this.targetPath('handoffs.jsonl'), this.taskRoot);
+    return current !== null && sha256(current) === journal.handoffTarget.postimage.contentSha256;
+  }
+
+  private applyHandoff(journal: CorrectiveYieldTaskTransactionJournal): 'applied' | 'confirmed' {
+    if (journal.phase !== 'applying' || journal.nextTargetOrdinal !== 0) {
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Corrective-yield handoff event is not the exact next target.');
+    }
+    assertTaskState(this.taskRoot, journal.taskStateSha256);
+    const file = this.targetPath('handoffs.jsonl');
+    const current = readOptional(file, this.taskRoot);
+    const currentHash = current ? sha256(current) : null;
+    if (currentHash === journal.handoffTarget.postimage.contentSha256) return 'confirmed';
+    if (currentHash !== journal.handoffTarget.preimage.contentSha256) {
+      throw new WorkflowError('STATE_CONFLICT', 'Task handoff target found neither exact preimage nor exact yield result.');
+    }
+    const owned = readOwned(this.taskRoot, journal);
+    writeAtomicDurable(file, owned);
+    assertCanonicalHandoff(this.taskRoot, journal);
+    return 'applied';
+  }
+
+  private advance(
+    current: CorrectiveYieldTaskTransactionJournal,
+    expectedPhase: CorrectiveYieldTransactionPhase,
+    expectedRevision: number,
+    nextPhase: CorrectiveYieldTransactionPhase,
+    nextTargetOrdinal: number,
+    completedResultSha256?: string,
+  ): CorrectiveYieldTaskTransactionJournal {
+    if (current.phase !== expectedPhase || current.phaseRevision !== expectedRevision) {
+      throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield phase compare-and-set conflict.');
+    }
+    assertPhaseTransition(current, nextPhase, nextTargetOrdinal);
+    if (nextTargetOrdinal >= 1) assertCanonicalHandoff(this.taskRoot, current);
+    if (nextPhase === 'completed') assertHash(completedResultSha256, 'Corrective-yield completed result hash');
+    else if (completedResultSha256 !== undefined) throw new WorkflowError('INVALID_ARGUMENT', 'Only completed yield may bind a result.');
+    const recordedAt = this.now().toISOString();
+    const previous = current.phaseHistory.at(-1)!;
+    const entry = phaseEntry(current.phaseRevision, nextPhase, nextTargetOrdinal, recordedAt, previous.entryHash, current.intentSha256);
+    const next: CorrectiveYieldTaskTransactionJournal = {
+      ...structuredClone(current),
+      phase: nextPhase,
+      phaseRevision: current.phaseRevision + 1,
+      nextTargetOrdinal,
+      phaseHistory: [...current.phaseHistory, entry],
+      completedResult: nextPhase === 'completed' ? { resultSha256: completedResultSha256! } : current.completedResult,
+      updatedAt: recordedAt,
+    };
+    validateJournal(next, this.taskRoot, true);
+    writeAtomicDurable(this.journalPath(current.transactionId), jsonBytes(next));
+    return this.read(current.transactionId);
+  }
+
+  private transactionRoot(transactionId: string): string {
+    assertHash(transactionId, 'Corrective-yield transaction id');
+    return path.join(this.taskRoot, '.yield-transactions', transactionId);
+  }
+
+  private targetPath(relative: string): string {
+    return path.join(this.taskRoot, relative);
+  }
+}
+
+export function inspectCorrectiveYieldTaskTransactions(
+  projectRoot: string,
+  trustedRoot: string,
+): { pending: ObservedTaskTransaction[]; completed: ObservedTaskTransaction[]; corrupt: CorruptObservedTaskTransaction[] } {
+  const pending: ObservedTaskTransaction[] = [];
+  const completed: ObservedTaskTransaction[] = [];
+  const corrupt: CorruptObservedTaskTransaction[] = [];
+  const tasksRoot = path.join(path.resolve(projectRoot), 'tasks');
+  if (!existsSync(tasksRoot)) return deepFreeze({ pending, completed, corrupt });
+  assertNoSymlinkPathComponents(tasksRoot, { label: 'Corrective-yield observation root', trustedRoot, requireLeaf: true });
+  for (const task of readdirSync(tasksRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (task.isSymbolicLink()) throw new WorkflowError('STATE_CORRUPT', 'Task observation root must not be a symlink.');
+    if (!task.isDirectory() || !TASK.test(task.name)) continue;
+    const taskRoot = path.join(tasksRoot, task.name);
+    const root = path.join(taskRoot, '.yield-transactions');
+    if (!existsSync(root)) continue;
+    assertNoSymlinkPathComponents(root, { label: 'Corrective-yield transaction root', trustedRoot, requireLeaf: true });
+    for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const transactionId = HASH.test(entry.name) ? entry.name : 'invalid-transaction-id';
+      if (entry.isSymbolicLink() || !entry.isDirectory() || !HASH.test(entry.name)) {
+        corrupt.push({ taskId: task.name, transactionId, reason: 'journal-invalid' });
+        continue;
+      }
+      try {
+        const journal = new CorrectiveYieldTaskTransactionStore({
+          taskRoot,
+          locksRoot: path.join(projectRoot, 'locks'),
+          trustedRoot,
+        }).read(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: task.name, transactionId, reason: 'journal-invalid' });
+      }
+    }
+  }
+  return deepFreeze({
+    completed: completed.sort(orderObserved),
+    pending: pending.sort(orderObserved),
+    corrupt: corrupt.sort(orderObserved),
+  });
+}
+
+export function assertCorrectiveYieldTaskTransactionBoundary(
+  projectRoot: string,
+  trustedRoot: string,
+  taskId?: string,
+): void {
+  const observed = inspectCorrectiveYieldTaskTransactions(projectRoot, trustedRoot);
+  const corrupt = taskId ? observed.corrupt.filter((row) => row.taskId === taskId) : observed.corrupt;
+  if (corrupt.length > 0) throw new WorkflowError('STATE_CORRUPT', 'A corrective-yield journal failed integrity validation.', { transactions: corrupt });
+  const pending = taskId ? observed.pending.filter((row) => row.taskId === taskId) : observed.pending;
+  if (pending.length > 0) throw new WorkflowError('TASK_RECOVERY_REQUIRED', 'A corrective-yield transaction requires explicit recovery.', {
+    taskIds: [...new Set(pending.map((row) => row.taskId))].sort(),
+    transactionIds: pending.map((row) => row.transactionId).sort(),
+  });
+}
+
+function validateJournal(value: unknown, taskRoot: string, verifyOwned: boolean): asserts value is CorrectiveYieldTaskTransactionJournal {
+  if (validateSchema(value) !== true) throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield transaction schema is invalid.');
+  const journal = value as CorrectiveYieldTaskTransactionJournal;
+  if (journal.intentSha256 !== intentHash(journal)) throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield intent hash mismatch.');
+  if (journal.phaseHistory.length !== journal.phaseRevision) throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield phase revision mismatch.');
+  journal.phaseHistory.forEach((entry, index) => {
+    const previous = index === 0 ? null : journal.phaseHistory[index - 1]!.entryHash;
+    if (entry.sequence !== index || entry.previousEntryHash !== previous
+      || entry.entryHash !== phaseEntryHash(index, entry.phase, entry.nextTargetOrdinal, entry.recordedAt, previous, journal.intentSha256)
+      || (index > 0 && entry.recordedAt < journal.phaseHistory[index - 1]!.recordedAt)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield phase history is invalid.');
+    }
+    if (index === 0 && (entry.phase !== 'intent' || entry.nextTargetOrdinal !== 0)) {
+      throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield phase history must start at intent.');
+    }
+    if (index > 0) {
+      const prior = journal.phaseHistory[index - 1]!;
+      const legal = (prior.phase === 'intent' && entry.phase === 'applying' && prior.nextTargetOrdinal === 0 && entry.nextTargetOrdinal === 0)
+        || (prior.phase === 'applying' && entry.phase === 'applying' && entry.nextTargetOrdinal === prior.nextTargetOrdinal + 1 && entry.nextTargetOrdinal <= 2)
+        || (prior.phase === 'applying' && prior.nextTargetOrdinal === 2 && entry.phase === 'published-pending-readback' && entry.nextTargetOrdinal === 2)
+        || (prior.phase === 'published-pending-readback' && entry.phase === 'completed' && entry.nextTargetOrdinal === 2);
+      if (!legal) throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield phase topology is invalid.');
+    }
+  });
+  const last = journal.phaseHistory.at(-1)!;
+  if (last.phase !== journal.phase || last.nextTargetOrdinal !== journal.nextTargetOrdinal || last.recordedAt !== journal.updatedAt
+    || (journal.phase === 'completed') !== (journal.completedResult !== null)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield current phase projection is invalid.');
+  }
+  if (journal.phaseRevision > 6 || Date.parse(journal.admittedAt) >= Date.parse(journal.writerLeaseExpiresAt)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield timing or phase cardinality is invalid.');
+  }
+  const before = journal.handoffTarget.preimage;
+  if (before.exists !== (before.contentSha256 !== null) || before.exists !== (before.contentPath !== null)
+    || (before.exists ? before.byteLength < 1 : before.byteLength !== 0)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield preimage ownership is invalid.');
+  }
+  if (journal.completedResult && journal.completedResult.resultSha256 !== resultHash(journal)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield completed result formula mismatch.');
+  }
+  if (verifyOwned) {
+    const owned = readOwned(taskRoot, journal);
+    const preimage = readOwnedPreimage(taskRoot, journal);
+    const anchors = validateAppend(preimage, owned, journal.transactionId, journal.actor, journal.writerLeaseTokenSha256);
+    if (anchors.previousEventHash !== journal.handoffTarget.previousEventHash
+      || anchors.resultEventHash !== journal.handoffTarget.resultEventHash) {
+      throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield handoff anchors mismatch.');
+    }
+    if (journal.phase === 'completed') {
+      assertCanonicalHandoffRetained(taskRoot, journal);
+    }
+  }
+}
+
+function assertPhaseTransition(current: CorrectiveYieldTaskTransactionJournal, phase: CorrectiveYieldTransactionPhase, ordinal: number): void {
+  const allowed = (current.phase === 'intent' && phase === 'applying' && ordinal === 0)
+    || (current.phase === 'applying' && phase === 'applying' && ordinal === current.nextTargetOrdinal + 1 && ordinal <= 2)
+    || (current.phase === 'applying' && current.nextTargetOrdinal === 2 && phase === 'published-pending-readback' && ordinal === 2)
+    || (current.phase === 'published-pending-readback' && phase === 'completed' && ordinal === 2);
+  if (!allowed) throw new WorkflowError('INVALID_ARGUMENT', 'Invalid corrective-yield phase transition.');
+}
+
+function validateAppend(
+  before: Buffer | null,
+  after: Buffer,
+  transactionId: string,
+  actor: string,
+  tokenSha256: string,
+): { previousEventHash: string | null; resultEventHash: string } {
+  if ((before && !after.subarray(0, before.byteLength).equals(before)) || after.byteLength <= (before?.byteLength ?? 0)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield handoff postimage must append exact bytes.');
+  }
+  const beforeLines = jsonLines(before);
+  const afterLines = jsonLines(after);
+  if (afterLines.length !== beforeLines.length + 1) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield must append exactly one handoff event.');
+  const event = afterLines.at(-1)!;
+  const previousEventHash = beforeLines.length === 0 ? null : eventHash(beforeLines.at(-1)!);
+  if (event.eventId !== `HOF-${transactionId}` || event.eventType !== 'yield' || event.actor !== actor
+    || event.writerLeaseTokenHash !== tokenSha256 || event.targetActor !== null || event.handback !== null
+    || event.previousEventHash !== previousEventHash) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield event does not bind the exact claimant transaction.');
+  }
+  return { previousEventHash, resultEventHash: eventHash(event) };
+}
+
+function intentHash(journal: CorrectiveYieldTaskTransactionJournal): string {
+  const { intentSha256: _intent, phase: _phase, phaseRevision: _revision, nextTargetOrdinal: _ordinal,
+    phaseHistory: _history, completedResult: _completed, updatedAt: _updated, ...intent } = journal;
+  return hashCanonical({ domain: 'codex-workflow/corrective-yield-intent/v1', intent });
+}
+
+function resultHash(journal: CorrectiveYieldTaskTransactionJournal): string {
+  return hashCanonical({
+    domain: 'codex-workflow/corrective-yield-result/v1',
+    transactionId: journal.transactionId,
+    intentSha256: journal.intentSha256,
+    taskStateSha256: journal.taskStateSha256,
+    handoffSha256: journal.handoffTarget.postimage.contentSha256,
+    yieldEventHash: journal.handoffTarget.resultEventHash,
+    writerLeaseReleased: true,
+  });
+}
+
+function phaseEntry(
+  sequence: number,
+  phase: CorrectiveYieldTransactionPhase,
+  nextTargetOrdinal: number,
+  recordedAt: string,
+  previousEntryHash: string | null,
+  intentSha256: string,
+) {
+  return { sequence, phase, nextTargetOrdinal, recordedAt, previousEntryHash,
+    entryHash: phaseEntryHash(sequence, phase, nextTargetOrdinal, recordedAt, previousEntryHash, intentSha256) };
+}
+
+function phaseEntryHash(
+  sequence: number,
+  phase: CorrectiveYieldTransactionPhase,
+  nextTargetOrdinal: number,
+  recordedAt: string,
+  previousEntryHash: string | null,
+  intentSha256: string,
+): string {
+  return hashCanonical({ domain: 'codex-workflow/corrective-yield-phase/v1', sequence, phase, nextTargetOrdinal, recordedAt, previousEntryHash, intentSha256 });
+}
+
+function snapshot(content: Buffer | null): SnapshotRecord {
+  return content === null
+    ? { exists: false, contentSha256: null, byteLength: 0, contentPath: null }
+    : { exists: true, contentSha256: sha256(content), byteLength: content.byteLength, contentPath: 'preimages/0.bin' };
+}
+
+function assertIntent(input: CreateCorrectiveYieldIntentInput): void {
+  if (!PROJECT.test(input.projectId) || !TASK.test(input.taskId) || !HASH.test(input.transactionId)
+    || !HASH.test(input.taskStateSha256) || !HASH.test(input.writerLeaseTokenSha256)
+    || !HASH.test(input.writerLeaseContentSha256) || !input.actor.trim() || input.actor.length > 256
+    || !(input.handoffPostimage instanceof Uint8Array) || input.handoffPostimage.byteLength === 0
+    || input.handoffPostimage.byteLength > 1_048_576) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield intent is invalid.');
+  }
+  assertIso(input.writerLeaseExpiresAt, 'Corrective-yield writer lease expiry');
+}
+
+function assertExactRecord(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 assertCanonicalHandoff(taskRoot: string, journal: CorrectiveYieldTaskTransactionJournal): void {
+  const current = readOptional(path.join(taskRoot, journal.handoffTarget.relativePath), taskRoot);
+  if (!current || sha256(current) !== journal.handoffTarget.postimage.contentSha256) {
+    throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield handoff target does not match its exact result.');
+  }
+}
+
+function assertCanonicalHandoffRetained(taskRoot: string, journal: CorrectiveYieldTaskTransactionJournal): void {
+  const current = readOptional(path.join(taskRoot, journal.handoffTarget.relativePath), taskRoot);
+  const owned = readOwned(taskRoot, journal);
+  if (!current || current.byteLength < owned.byteLength
+    || !current.subarray(0, owned.byteLength).equals(owned)) {
+    throw new WorkflowError('STATE_CONFLICT', 'Corrective-yield handoff result is not retained in canonical history.');
+  }
+  jsonLines(current);
+}
+
+function assertTaskState(taskRoot: string, expectedHash: string): void {
+  if (sha256(readRequired(path.join(taskRoot, 'state.json'), taskRoot)) !== expectedHash) {
+    throw new WorkflowError('STATE_CONFLICT', 'Task state changed across corrective-yield.');
+  }
+}
+
+function readOwned(taskRoot: string, journal: CorrectiveYieldTaskTransactionJournal): Buffer {
+  const file = path.join(taskRoot, '.yield-transactions', journal.transactionId, journal.handoffTarget.postimage.contentPath);
+  const content = readRequired(file, taskRoot);
+  if (content.byteLength !== journal.handoffTarget.postimage.byteLength || sha256(content) !== journal.handoffTarget.postimage.contentSha256) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield owned postimage is corrupt.');
+  }
+  return content;
+}
+
+function readOwnedPreimage(taskRoot: string, journal: CorrectiveYieldTaskTransactionJournal): Buffer | null {
+  if (!journal.handoffTarget.preimage.exists) return null;
+  const file = path.join(taskRoot, '.yield-transactions', journal.transactionId, journal.handoffTarget.preimage.contentPath!);
+  const content = readRequired(file, taskRoot);
+  if (content.byteLength !== journal.handoffTarget.preimage.byteLength || sha256(content) !== journal.handoffTarget.preimage.contentSha256) {
+    throw new WorkflowError('STATE_CORRUPT', 'Corrective-yield owned preimage is corrupt.');
+  }
+  return content;
+}
+
+function jsonLines(content: Buffer | null): Array<Record<string, unknown>> {
+  if (!content) return [];
+  const text = content.toString('utf8');
+  if (!text.endsWith('\n')) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield handoff bytes must end with newline.');
+  const events = text.slice(0, -1).split('\n').map((line) => {
+    const value = JSON.parse(line) as unknown;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield handoff line is invalid.');
+    return value as Record<string, unknown>;
+  });
+  let previousEventHash: string | null = null;
+  for (const event of events) {
+    if (event.previousEventHash !== previousEventHash
+      || event.eventHash !== computeSidecarEventHash(event as never)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield handoff event chain is invalid.');
+    }
+    previousEventHash = eventHash(event);
+  }
+  return events;
+}
+
+function eventHash(event: Record<string, unknown>): string {
+  if (typeof event.eventHash !== 'string' || !HASH.test(event.eventHash)) throw new WorkflowError('INVALID_ARGUMENT', 'Handoff event hash is invalid.');
+  return event.eventHash;
+}
+
+function readOptional(file: string, trustedRoot: string): Buffer | null {
+  assertNoSymlinkPathComponents(file, { label: 'Corrective-yield target', trustedRoot, requireLeaf: true });
+  return existsSync(file) ? readFileSync(file) : null;
+}
+
+function readRequired(file: string, trustedRoot: string): Buffer {
+  const value = readOptional(file, trustedRoot);
+  if (!value) throw new WorkflowError('STATE_CORRUPT', `Corrective-yield required file is missing: ${file}`);
+  return value;
+}
+
+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 ensureDirectorySafe(directory: string, trustedRoot: string): void {
+  if (!existsSync(directory)) mkdirSync(directory, { recursive: true, mode: 0o700 });
+  assertNoSymlinkPathComponents(directory, { label: 'Corrective-yield transaction directory', trustedRoot, requireLeaf: true });
+}
+
+function fsyncDirectory(directory: string): void {
+  const descriptor = openSync(directory, 'r');
+  try { fsyncSync(descriptor); } finally { closeSync(descriptor); }
+}
+
+function assertTaskRoot(taskRoot: string, trustedRoot: string): void {
+  const resolvedTask = path.resolve(taskRoot);
+  const resolvedTrusted = path.resolve(trustedRoot);
+  if (!resolvedTask.startsWith(`${resolvedTrusted}${path.sep}`)) throw new WorkflowError('INVALID_ARGUMENT', 'Corrective-yield Task root is outside trusted state.');
+  assertNoSymlinkPathComponents(resolvedTask, { label: 'Corrective-yield Task root', trustedRoot: resolvedTrusted, requireLeaf: true });
+}
+
+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 canonical UTC.`);
+}
+
+function jsonBytes(value: unknown): Buffer {
+  return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function sha256(value: Buffer | string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function orderObserved(left: { taskId: string; transactionId: string }, right: { taskId: string; transactionId: string }): number {
+  return left.taskId.localeCompare(right.taskId) || left.transactionId.localeCompare(right.transactionId);
+}