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

package/src/alpha6/review.ts

@@ -0,0 +1,1198 @@
+import type {
+  ReviewInput,
+  ReviewStatus,
+  ReviewerAttestationEvent,
+  StepEvidence,
+  StepReviewEvent,
+  StepReviewEventType,
+  TaskState,
+  TaskStep,
+} from '../contracts.js';
+import { WorkflowError } from '../errors.js';
+import type { FileStateStore } from '../state/store.js';
+import { canonicalJsonStringify, assertHash64, sha256Hex } from './store-sidecars.js';
+import { createUlid } from '../ulid.js';
+import { reviewerCauseFingerprint } from './remediation-cause.js';
+
+const STEP_REVIEW_EVENTS_SIDECAR = 'step-review-events.jsonl';
+const REVIEWER_ATTESTATIONS_SIDECAR = 'reviewer-attestations.jsonl';
+const GIT_SHA_PATTERN = /^[a-f0-9]{40}$/;
+const STEP_REVIEW_EVENT_TYPES = new Set<StepReviewEventType>([
+  'pending',
+  'review-recorded',
+  'attestation-verified',
+]);
+const REVIEW_DECISIONS = new Set<ReviewStatus>(['pending', 'passed', 'failed', 'unverified']);
+const REVIEW_FINDING_SEVERITIES = new Set(['critical', 'major', 'minor']);
+
+export interface StrictStepBinding {
+  stepId: string;
+  taskRevision: number;
+  stepDefinitionHash: string;
+  completionCommit: string;
+  checksHash: string;
+  planHash: string;
+  evidenceHash: string;
+}
+
+export interface CurrentStrictStepReviewBinding {
+  step: TaskStep;
+  evidence: StepEvidence;
+  binding: StrictStepBinding;
+}
+
+export type StrictStepReviewResolution = 'pending' | 'passed_verified' | 'failed' | 'unverified';
+
+export interface CurrentStrictStepReviewCycle extends CurrentStrictStepReviewBinding {
+  latestMatchingEvent: StepReviewEvent | null;
+  pendingEvent: StepReviewEvent | null;
+  reviewRecordedEvent: StepReviewEvent | null;
+  reviewerAttestationEvent: ReviewerAttestationEvent | null;
+  attestationVerifiedEvent: StepReviewEvent | null;
+  resolution: StrictStepReviewResolution;
+}
+
+export interface StepReviewRecordInput {
+  review: ReviewInput;
+  reviewerOutputHash: string;
+  reviewedCommit: string;
+  isolationResult: 'verified' | 'unverified';
+}
+
+export interface StrictStepReviewRecordResult {
+  reviewRecordedEvent: StepReviewEvent;
+  reviewerAttestationEvent: ReviewerAttestationEvent;
+  attestationVerifiedEvent: StepReviewEvent | null;
+  resolution: StrictStepReviewResolution;
+  canFinalizeStep: boolean;
+}
+
+export interface ReviewRemediationRouting {
+  route: 'fix' | 'replan';
+  planConflicts: NonNullable<StepReviewEvent['planConflicts']>;
+}
+
+export function isStepReviewRequired(task: TaskState, stepId: string, reviewRequiredStepIds: readonly string[]): boolean {
+  return reviewRequiredStepIds.includes(stepId);
+}
+
+export function ensurePendingStrictStepReview(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+  now: Date,
+): StepReviewEvent {
+  const current = buildCurrentStrictStepReviewCycle(store, task, stepId);
+  if (current.pendingEvent && current.latestMatchingEvent?.eventType === 'pending') return current.pendingEvent;
+  return appendStepReviewEvent(store, task, {
+    eventId: `SRE-${createUlid(now.getTime())}`,
+    recordedAt: now.toISOString(),
+    taskId: task.id,
+    taskRevision: task.revision,
+    stepId: current.binding.stepId,
+    stepDefinitionHash: current.binding.stepDefinitionHash,
+    completionCommit: current.binding.completionCommit,
+    checksHash: current.binding.checksHash,
+    planHash: current.binding.planHash,
+    evidenceHash: current.binding.evidenceHash,
+    eventType: 'pending',
+    decision: 'pending',
+    reviewerAttestationHash: null,
+  });
+}
+
+export function requireCurrentStrictStepReview(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+): CurrentStrictStepReviewCycle {
+  const current = buildCurrentStrictStepReviewCycle(store, task, stepId);
+  if (!current.pendingEvent) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Strict Step Review pending event is missing for ${stepId}.`, {
+      taskId: task.id,
+      stepId,
+      completionCommit: current.binding.completionCommit,
+    });
+  }
+  if (current.latestMatchingEvent?.eventType !== 'pending') {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Strict Step Review for ${stepId} is no longer pending.`, {
+      taskId: task.id,
+      stepId,
+      eventType: current.latestMatchingEvent?.eventType ?? null,
+      completionCommit: current.binding.completionCommit,
+    });
+  }
+  return current;
+}
+
+export function buildCurrentStrictStepReviewCycle(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+): CurrentStrictStepReviewCycle {
+  const current = buildCurrentStrictStepBinding(task, stepId);
+  const stepReviewEvents = readStepReviewEvents(store, task);
+  const reviewerAttestations = readReviewerAttestations(store, task);
+  validateGlobalStrictStepReviewHistory(stepReviewEvents, reviewerAttestations);
+  return resolveCurrentStrictStepReviewCycle(current, stepReviewEvents, reviewerAttestations);
+}
+
+export function recordStrictStepReview(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+  input: StepReviewRecordInput,
+  now: Date,
+): StrictStepReviewRecordResult {
+  let current = buildCurrentStrictStepReviewCycle(store, task, stepId);
+  if (!current.pendingEvent) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Strict Step Review pending event is missing for ${stepId}.`, {
+      taskId: task.id,
+      stepId,
+      completionCommit: current.binding.completionCommit,
+    });
+  }
+  validateStepReviewRecordInput(current, input);
+
+  const reviewRecordedEvent = current.reviewRecordedEvent
+    ? reuseReviewRecordedEvent(current, input)
+    : appendStepReviewEvent(store, task, {
+        eventId: `SRE-${createUlid(now.getTime())}`,
+        recordedAt: now.toISOString(),
+        taskId: task.id,
+        taskRevision: task.revision,
+        stepId: current.binding.stepId,
+        stepDefinitionHash: current.binding.stepDefinitionHash,
+        completionCommit: current.binding.completionCommit,
+        checksHash: current.binding.checksHash,
+        planHash: current.binding.planHash,
+        evidenceHash: current.binding.evidenceHash,
+        eventType: 'review-recorded',
+        decision: input.review.status,
+        reviewerAttestationHash: null,
+        ...reviewRemediationEventFields(input.review),
+      });
+
+  current = buildCurrentStrictStepReviewCycle(store, task, stepId);
+
+  const reviewerAttestationEvent = current.reviewerAttestationEvent
+    ? reuseReviewerAttestationEvent(current, reviewRecordedEvent, input)
+    : appendReviewerAttestationEvent(store, task, {
+        eventId: `RAT-${createUlid(now.getTime())}`,
+        recordedAt: now.toISOString(),
+        taskId: task.id,
+        stepId: current.binding.stepId,
+        reviewer: input.review.reviewer.trim(),
+        isolationResult: input.isolationResult,
+        outputHash: input.reviewerOutputHash,
+        reviewedCommit: input.reviewedCommit,
+        reviewEventHash: reviewRecordedEvent.eventHash,
+        planHash: current.binding.planHash,
+        evidenceHash: current.binding.evidenceHash,
+      });
+
+  current = buildCurrentStrictStepReviewCycle(store, task, stepId);
+
+  const attestationVerifiedEvent = input.isolationResult === 'verified'
+    ? current.attestationVerifiedEvent
+      ? reuseAttestationVerifiedEvent(current, reviewRecordedEvent, reviewerAttestationEvent)
+      : appendStepReviewEvent(store, task, {
+          eventId: `SRE-${createUlid(now.getTime())}`,
+          recordedAt: now.toISOString(),
+          taskId: task.id,
+          taskRevision: task.revision,
+          stepId: current.binding.stepId,
+          stepDefinitionHash: current.binding.stepDefinitionHash,
+          completionCommit: current.binding.completionCommit,
+          checksHash: current.binding.checksHash,
+          planHash: current.binding.planHash,
+          evidenceHash: current.binding.evidenceHash,
+          eventType: 'attestation-verified',
+          decision: reviewRecordedEvent.decision,
+          reviewerAttestationHash: reviewerAttestationEvent.eventHash,
+        })
+    : null;
+
+  const resolution = deriveStrictStepReviewResolution(reviewRecordedEvent, reviewerAttestationEvent, attestationVerifiedEvent);
+  return {
+    reviewRecordedEvent,
+    reviewerAttestationEvent,
+    attestationVerifiedEvent,
+    resolution,
+    canFinalizeStep: resolution === 'passed_verified',
+  };
+}
+
+export function readStepReviewEvents(store: FileStateStore, task: TaskState): StepReviewEvent[] {
+  return store.readSidecarEvents<StepReviewEvent>(
+    store.taskRoot(task.projectId, task.id),
+    STEP_REVIEW_EVENTS_SIDECAR,
+    {
+      validateEvent: (event, context) => validateStoredStepReviewEvent(event, task.id, context.file, context.line),
+    },
+  );
+}
+
+export function readReviewerAttestations(store: FileStateStore, task: TaskState): ReviewerAttestationEvent[] {
+  return store.readSidecarEvents<ReviewerAttestationEvent>(
+    store.taskRoot(task.projectId, task.id),
+    REVIEWER_ATTESTATIONS_SIDECAR,
+    {
+      validateEvent: (event, context) => validateStoredReviewerAttestationEvent(event, task.id, context.file, context.line),
+    },
+  );
+}
+
+export function latestFailedStepReviewRouting(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+): ReviewRemediationRouting | null {
+  const event = readStepReviewEvents(store, task)
+    .filter((candidate) => candidate.stepId === stepId
+      && candidate.eventType === 'review-recorded'
+      && candidate.decision === 'failed')
+    .at(-1);
+  if (!event) return null;
+  return {
+    route: event.remediationRoute ?? 'fix',
+    planConflicts: event.planConflicts ?? [],
+  };
+}
+
+export function latestPassedVerifiedStepReviewEvent(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+): StepReviewEvent | null {
+  const stepReviewEvents = readStepReviewEvents(store, task);
+  const reviewerAttestations = readReviewerAttestations(store, task);
+  validateGlobalStrictStepReviewHistory(stepReviewEvents, reviewerAttestations);
+  return stepReviewEvents.filter((event) =>
+    event.stepId === stepId
+    && event.eventType === 'attestation-verified'
+    && event.decision === 'passed'
+  ).at(-1) ?? null;
+}
+
+export function verifiedHistoricalStepReviewCommits(
+  store: FileStateStore,
+  task: TaskState,
+): string[] {
+  const stepReviewEvents = readStepReviewEvents(store, task);
+  const reviewerAttestations = readReviewerAttestations(store, task);
+  validateGlobalStrictStepReviewHistory(stepReviewEvents, reviewerAttestations);
+  return [...new Set(stepReviewEvents.filter((event) =>
+    event.eventType === 'attestation-verified'
+    && event.decision === 'passed'
+  ).map((event) => event.completionCommit))];
+}
+
+export function verifiedHistoricalStepReviewBindings(
+  store: FileStateStore,
+  task: TaskState,
+): Array<{ stepId: string; commitSha: string; planHash: string; recordedAt: string }> {
+  const stepReviewEvents = readStepReviewEvents(store, task);
+  const reviewerAttestations = readReviewerAttestations(store, task);
+  validateGlobalStrictStepReviewHistory(stepReviewEvents, reviewerAttestations);
+  return stepReviewEvents.filter((event) =>
+    event.eventType === 'attestation-verified'
+    && event.decision === 'passed'
+  ).map((event) => ({
+    stepId: event.stepId,
+    commitSha: event.completionCommit,
+    planHash: event.planHash,
+    recordedAt: event.recordedAt,
+  }));
+}
+
+export function countUnverifiedStrictStepReviews(
+  store: FileStateStore,
+  task: TaskState,
+  stepId: string,
+): number {
+  const current = buildCurrentStrictStepBinding(task, stepId);
+  return readStepReviewEvents(store, task).filter((event) =>
+    event.eventType === 'review-recorded'
+    && event.decision === 'unverified'
+    && event.stepId === current.binding.stepId
+    && event.completionCommit === current.binding.completionCommit
+    && event.planHash === current.binding.planHash
+    && event.evidenceHash === current.binding.evidenceHash
+  ).length;
+}
+
+export function deriveStrictStepReviewResolution(
+  reviewRecordedEvent: StepReviewEvent | null,
+  reviewerAttestationEvent: ReviewerAttestationEvent | null,
+  attestationVerifiedEvent: StepReviewEvent | null,
+): StrictStepReviewResolution {
+  if (!reviewRecordedEvent || !reviewerAttestationEvent) return 'pending';
+  if (reviewRecordedEvent.decision === 'failed') return 'failed';
+  if (reviewRecordedEvent.decision === 'unverified') return 'unverified';
+  if (reviewRecordedEvent.decision !== 'passed') return 'pending';
+  if (reviewerAttestationEvent.isolationResult !== 'verified') return 'unverified';
+  return attestationVerifiedEvent ? 'passed_verified' : 'pending';
+}
+
+function buildCurrentStrictStepBinding(task: TaskState, stepId: string): CurrentStrictStepReviewBinding {
+  const step = requireTaskStep(task, stepId);
+  if (!step.evidence) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Strict Step Review requires canonical evidence for ${stepId}.`, {
+      taskId: task.id,
+      stepId,
+    });
+  }
+  if (!task.planHash) {
+    throw new WorkflowError('STATE_CORRUPT', `Task ${task.id} has no current plan hash for strict Step Review.`, {
+      taskId: task.id,
+      stepId,
+    });
+  }
+  return {
+    step,
+    evidence: step.evidence,
+    binding: {
+      stepId: step.id,
+      taskRevision: task.revision,
+      stepDefinitionHash: sha256Hex(canonicalJsonStringify(stripStepRuntime(step))),
+      completionCommit: step.evidence.commitSha,
+      checksHash: sha256Hex(canonicalJsonStringify(step.evidence.checks)),
+      planHash: task.planHash,
+      evidenceHash: sha256Hex(canonicalJsonStringify(step.evidence)),
+    },
+  };
+}
+
+function resolveCurrentStrictStepReviewCycle(
+  current: CurrentStrictStepReviewBinding,
+  stepReviewEvents: readonly StepReviewEvent[],
+  reviewerAttestations: readonly ReviewerAttestationEvent[],
+): CurrentStrictStepReviewCycle {
+  const matchingEvents = stepReviewEvents.filter((event) => eventMatchesBinding(event, current.binding));
+  const latestMatchingEvent = matchingEvents.at(-1) ?? null;
+  const latestPendingIndex = findLastIndex(matchingEvents, (event) => event.eventType === 'pending');
+  if (latestPendingIndex < 0) {
+    if (matchingEvents.length > 0) {
+      throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review history is missing the pending event that should anchor the current cycle.', {
+        stepId: current.binding.stepId,
+        completionCommit: current.binding.completionCommit,
+        latestEventType: latestMatchingEvent?.eventType ?? null,
+      });
+    }
+    return {
+      ...current,
+      latestMatchingEvent: null,
+      pendingEvent: null,
+      reviewRecordedEvent: null,
+      reviewerAttestationEvent: null,
+      attestationVerifiedEvent: null,
+      resolution: 'pending',
+    };
+  }
+
+  const pendingEvent = matchingEvents[latestPendingIndex]!;
+  const cycleEvents = matchingEvents.slice(latestPendingIndex + 1);
+  const reviewRecordedEvents = cycleEvents.filter((event) => event.eventType === 'review-recorded');
+  const attestationVerifiedEvents = cycleEvents.filter((event) => event.eventType === 'attestation-verified');
+
+  if (reviewRecordedEvents.length > 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review cycle has multiple review-recorded events for one pending event.', {
+      stepId: current.binding.stepId,
+      completionCommit: current.binding.completionCommit,
+      eventIds: reviewRecordedEvents.map((event) => event.eventId),
+    });
+  }
+  if (attestationVerifiedEvents.length > 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review cycle has multiple attestation-verified events for one pending event.', {
+      stepId: current.binding.stepId,
+      completionCommit: current.binding.completionCommit,
+      eventIds: attestationVerifiedEvents.map((event) => event.eventId),
+    });
+  }
+
+  const reviewRecordedEvent = reviewRecordedEvents[0] ?? null;
+  const attestationVerifiedEvent = attestationVerifiedEvents[0] ?? null;
+  let reviewerAttestationEvent: ReviewerAttestationEvent | null = null;
+
+  if (reviewRecordedEvent) {
+    const linkedAttestations = reviewerAttestations.filter((event) => event.reviewEventHash === reviewRecordedEvent.eventHash);
+    if (linkedAttestations.length > 1) {
+      throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review cycle has multiple reviewer attestations for one review event.', {
+        stepId: current.binding.stepId,
+        reviewEventId: reviewRecordedEvent.eventId,
+        eventIds: linkedAttestations.map((event) => event.eventId),
+      });
+    }
+    reviewerAttestationEvent = linkedAttestations[0] ?? null;
+    if (reviewerAttestationEvent) validateAttestationBinding(current.binding, reviewRecordedEvent, reviewerAttestationEvent);
+  } else if (attestationVerifiedEvent) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification cannot exist without a review-recorded event.', {
+      stepId: current.binding.stepId,
+      eventId: attestationVerifiedEvent.eventId,
+    });
+  }
+
+  if (attestationVerifiedEvent) {
+    if (!reviewerAttestationEvent || !reviewRecordedEvent) {
+      throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification is missing its prerequisite chain.', {
+        stepId: current.binding.stepId,
+        eventId: attestationVerifiedEvent.eventId,
+      });
+    }
+    validateAttestationVerifiedChain(current.binding, reviewRecordedEvent, reviewerAttestationEvent, attestationVerifiedEvent);
+  }
+
+  return {
+    ...current,
+    latestMatchingEvent,
+    pendingEvent,
+    reviewRecordedEvent,
+    reviewerAttestationEvent,
+    attestationVerifiedEvent,
+    resolution: deriveStrictStepReviewResolution(reviewRecordedEvent, reviewerAttestationEvent, attestationVerifiedEvent),
+  };
+}
+
+function validateGlobalStrictStepReviewHistory(
+  stepReviewEvents: readonly StepReviewEvent[],
+  reviewerAttestations: readonly ReviewerAttestationEvent[],
+): void {
+  const reviewRecordedEventsByHash = indexStepReviewEventsByHash(stepReviewEvents, 'review-recorded');
+  const reviewerAttestationsByReviewHash = new Map<string, ReviewerAttestationEvent[]>();
+  for (const attestation of reviewerAttestations) {
+    const linkedReviewEvents = reviewRecordedEventsByHash.get(attestation.reviewEventHash) ?? [];
+    if (linkedReviewEvents.length !== 1) {
+      throw new WorkflowError(
+        'STATE_CORRUPT',
+        linkedReviewEvents.length === 0
+          ? 'Reviewer attestation references a missing review-recorded Step Review event.'
+          : 'Reviewer attestation references multiple review-recorded Step Review events.',
+        {
+          eventId: attestation.eventId,
+          reviewEventHash: attestation.reviewEventHash,
+          matchCount: linkedReviewEvents.length,
+        },
+      );
+    }
+    const linkedReviewEvent = linkedReviewEvents[0]!;
+    validateHistoricalAttestationBinding(linkedReviewEvent, attestation);
+    const linkedAttestations = reviewerAttestationsByReviewHash.get(attestation.reviewEventHash) ?? [];
+    linkedAttestations.push(attestation);
+    reviewerAttestationsByReviewHash.set(attestation.reviewEventHash, linkedAttestations);
+  }
+  for (const [reviewEventHash, linkedAttestations] of reviewerAttestationsByReviewHash) {
+    if (linkedAttestations.length > 1) {
+      throw new WorkflowError('STATE_CORRUPT', 'Multiple reviewer attestations target the same review-recorded Step Review event.', {
+        reviewEventHash,
+        eventIds: linkedAttestations.map((event) => event.eventId),
+      });
+    }
+  }
+
+  const reviewerAttestationsByHash = indexReviewerAttestationsByHash(reviewerAttestations);
+  const attestationVerifiedEventsByAttestationHash = new Map<string, StepReviewEvent[]>();
+  for (const verifiedEvent of stepReviewEvents) {
+    if (verifiedEvent.eventType !== 'attestation-verified') continue;
+    const attestationHash = verifiedEvent.reviewerAttestationHash;
+    if (typeof attestationHash !== 'string') {
+      throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review event is missing its attestation hash.', {
+        eventId: verifiedEvent.eventId,
+      });
+    }
+    const linkedAttestations = reviewerAttestationsByHash.get(attestationHash) ?? [];
+    if (linkedAttestations.length !== 1) {
+      throw new WorkflowError(
+        'STATE_CORRUPT',
+        linkedAttestations.length === 0
+          ? 'Attestation-verified Step Review event references a missing reviewer attestation.'
+          : 'Attestation-verified Step Review event references multiple reviewer attestations.',
+        {
+          eventId: verifiedEvent.eventId,
+          reviewerAttestationHash: attestationHash,
+          matchCount: linkedAttestations.length,
+        },
+      );
+    }
+    const reviewerAttestationEvent = linkedAttestations[0]!;
+    const linkedReviewEvents = reviewRecordedEventsByHash.get(reviewerAttestationEvent.reviewEventHash) ?? [];
+    if (linkedReviewEvents.length !== 1) {
+      throw new WorkflowError(
+        'STATE_CORRUPT',
+        linkedReviewEvents.length === 0
+          ? 'Attestation-verified Step Review event references an attestation whose review-recorded event is missing.'
+          : 'Attestation-verified Step Review event references an attestation with multiple review-recorded targets.',
+        {
+          eventId: verifiedEvent.eventId,
+          reviewerAttestationEventId: reviewerAttestationEvent.eventId,
+          reviewEventHash: reviewerAttestationEvent.reviewEventHash,
+          matchCount: linkedReviewEvents.length,
+        },
+      );
+    }
+    const linkedReviewEvent = linkedReviewEvents[0]!;
+    validateHistoricalAttestationBinding(linkedReviewEvent, reviewerAttestationEvent);
+    validateHistoricalAttestationVerifiedChain(linkedReviewEvent, reviewerAttestationEvent, verifiedEvent);
+    const linkedVerifiedEvents = attestationVerifiedEventsByAttestationHash.get(attestationHash) ?? [];
+    linkedVerifiedEvents.push(verifiedEvent);
+    attestationVerifiedEventsByAttestationHash.set(attestationHash, linkedVerifiedEvents);
+  }
+  for (const [reviewerAttestationHash, linkedVerifiedEvents] of attestationVerifiedEventsByAttestationHash) {
+    if (linkedVerifiedEvents.length > 1) {
+      throw new WorkflowError('STATE_CORRUPT', 'Multiple attestation-verified Step Review events target the same reviewer attestation.', {
+        reviewerAttestationHash,
+        eventIds: linkedVerifiedEvents.map((event) => event.eventId),
+      });
+    }
+  }
+}
+
+function stripStepRuntime(step: TaskStep) {
+  const { status: _status, evidence: _evidence, failurePause: _failurePause, ...definition } = step;
+  return definition;
+}
+
+function requireTaskStep(task: TaskState, stepId: string): TaskStep {
+  const step = task.steps.find((candidate) => candidate.id === stepId);
+  if (!step) throw new WorkflowError('NOT_FOUND', `Step not found: ${stepId}`);
+  return step;
+}
+
+function eventMatchesBinding(event: StepReviewEvent, binding: StrictStepBinding): boolean {
+  return event.stepId === binding.stepId
+    && event.stepDefinitionHash === binding.stepDefinitionHash
+    && event.completionCommit === binding.completionCommit
+    && event.checksHash === binding.checksHash
+    && event.planHash === binding.planHash
+    && event.evidenceHash === binding.evidenceHash;
+}
+
+function stepReviewEventsMatchStructuralBinding(left: StepReviewEvent, right: StepReviewEvent): boolean {
+  return left.taskId === right.taskId
+    && left.stepId === right.stepId
+    && left.stepDefinitionHash === right.stepDefinitionHash
+    && left.completionCommit === right.completionCommit
+    && left.checksHash === right.checksHash
+    && left.planHash === right.planHash
+    && left.evidenceHash === right.evidenceHash;
+}
+
+function validateStepReviewRecordInput(current: CurrentStrictStepReviewCycle, input: StepReviewRecordInput): void {
+  const reviewer = typeof input.review.reviewer === 'string' ? input.review.reviewer.trim() : '';
+  const summary = typeof input.review.summary === 'string' ? input.review.summary.trim() : '';
+  if (!reviewer || !summary) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review requires reviewer identity and summary.', {
+      stepId: current.binding.stepId,
+    });
+  }
+  if (!Array.isArray(input.review.findings)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review findings must be an array.', {
+      stepId: current.binding.stepId,
+    });
+  }
+  if (input.review.status === 'pending' || !REVIEW_DECISIONS.has(input.review.status)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review status is invalid.', {
+      stepId: current.binding.stepId,
+      status: input.review.status,
+    });
+  }
+  for (const finding of input.review.findings) {
+    if (!finding || typeof finding !== 'object') {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review findings must be objects.', {
+        stepId: current.binding.stepId,
+      });
+    }
+    if (typeof finding.id !== 'string' || !finding.id.trim()) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review findings require an id.', {
+        stepId: current.binding.stepId,
+      });
+    }
+    if (!REVIEW_FINDING_SEVERITIES.has(finding.severity)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review findings severity is invalid.', {
+        stepId: current.binding.stepId,
+        findingId: finding.id,
+        severity: finding.severity,
+      });
+    }
+    if (finding.requirement !== null && (typeof finding.requirement !== 'string' || !finding.requirement.trim())) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review finding requirement must be null or a non-empty string.', {
+        stepId: current.binding.stepId,
+        findingId: finding.id,
+      });
+    }
+    for (const [label, value] of [
+      ['summary', finding.summary],
+      ['evidence', finding.evidence],
+      ['requiredAction', finding.requiredAction],
+    ] as const) {
+      if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowError('INVALID_ARGUMENT', `Strict Step Review finding ${label} is required.`, {
+          stepId: current.binding.stepId,
+          findingId: finding.id,
+        });
+      }
+    }
+    validateFindingRemediationRoute(finding, current.binding.stepId);
+  }
+  if (input.review.status === 'passed' && input.review.findings.length > 0) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review cannot mark passed while findings remain.', {
+      stepId: current.binding.stepId,
+    });
+  }
+  if (input.review.status === 'failed' && input.review.findings.length === 0) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review failure must include at least one finding.', {
+      stepId: current.binding.stepId,
+    });
+  }
+  assertHash64(input.reviewerOutputHash, 'Strict Step Review reviewer output hash');
+  if (!GIT_SHA_PATTERN.test(input.reviewedCommit)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Strict Step Review reviewed commit is not a full Git SHA.', {
+      stepId: current.binding.stepId,
+      reviewedCommit: input.reviewedCommit,
+    });
+  }
+  if (input.reviewedCommit !== current.binding.completionCommit) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Strict Step Review must bind the exact completion commit.', {
+      stepId: current.binding.stepId,
+      reviewedCommit: input.reviewedCommit,
+      completionCommit: current.binding.completionCommit,
+    });
+  }
+  if (input.isolationResult !== 'verified' && input.isolationResult !== 'unverified') {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review isolation result is invalid.', {
+      stepId: current.binding.stepId,
+      isolationResult: input.isolationResult,
+    });
+  }
+}
+
+function reuseReviewRecordedEvent(
+  current: CurrentStrictStepReviewCycle,
+  input: StepReviewRecordInput,
+): StepReviewEvent {
+  const existing = current.reviewRecordedEvent;
+  if (!existing) throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review review-recorded event is unexpectedly missing.', {
+    stepId: current.binding.stepId,
+  });
+  if (existing.decision !== input.review.status) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Strict Step Review already recorded a conflicting decision for this completion commit.', {
+      stepId: current.binding.stepId,
+      existingDecision: existing.decision,
+      requestedDecision: input.review.status,
+      completionCommit: current.binding.completionCommit,
+    });
+  }
+  const requestedRouting = reviewRemediationEventFields(input.review);
+  if (
+    (existing.remediationRoute ?? null) !== (requestedRouting.remediationRoute ?? null)
+    || canonicalJsonStringify(existing.planConflicts ?? []) !== canonicalJsonStringify(requestedRouting.planConflicts ?? [])
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Strict Step Review already recorded a conflicting remediation route for this completion commit.', {
+      stepId: current.binding.stepId,
+      completionCommit: current.binding.completionCommit,
+      existingRoute: existing.remediationRoute ?? null,
+      requestedRoute: requestedRouting.remediationRoute ?? null,
+    });
+  }
+  return existing;
+}
+
+function reuseReviewerAttestationEvent(
+  current: CurrentStrictStepReviewCycle,
+  reviewRecordedEvent: StepReviewEvent,
+  input: StepReviewRecordInput,
+): ReviewerAttestationEvent {
+  const existing = current.reviewerAttestationEvent;
+  if (!existing) throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation is unexpectedly missing.', {
+    stepId: current.binding.stepId,
+  });
+  validateAttestationBinding(current.binding, reviewRecordedEvent, existing);
+  const reviewer = input.review.reviewer.trim();
+  if (existing.reviewer !== reviewer
+    || existing.isolationResult !== input.isolationResult
+    || existing.outputHash !== input.reviewerOutputHash
+    || existing.reviewedCommit !== input.reviewedCommit) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Strict Step Review already recorded a conflicting reviewer attestation for this completion commit.', {
+      stepId: current.binding.stepId,
+      completionCommit: current.binding.completionCommit,
+      existingReviewer: existing.reviewer,
+      requestedReviewer: reviewer,
+      existingIsolationResult: existing.isolationResult,
+      requestedIsolationResult: input.isolationResult,
+      existingOutputHash: existing.outputHash,
+      requestedOutputHash: input.reviewerOutputHash,
+      existingReviewedCommit: existing.reviewedCommit,
+      requestedReviewedCommit: input.reviewedCommit,
+    });
+  }
+  return existing;
+}
+
+function reuseAttestationVerifiedEvent(
+  current: CurrentStrictStepReviewCycle,
+  reviewRecordedEvent: StepReviewEvent,
+  reviewerAttestationEvent: ReviewerAttestationEvent,
+): StepReviewEvent {
+  const existing = current.attestationVerifiedEvent;
+  if (!existing) throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification is unexpectedly missing.', {
+    stepId: current.binding.stepId,
+  });
+  validateAttestationVerifiedChain(current.binding, reviewRecordedEvent, reviewerAttestationEvent, existing);
+  return existing;
+}
+
+function validateAttestationBinding(
+  binding: StrictStepBinding,
+  reviewRecordedEvent: StepReviewEvent,
+  attestation: ReviewerAttestationEvent,
+): void {
+  if (attestation.stepId !== binding.stepId
+    || attestation.taskId !== reviewRecordedEvent.taskId
+    || attestation.reviewedCommit !== binding.completionCommit
+    || attestation.reviewEventHash !== reviewRecordedEvent.eventHash
+    || attestation.planHash !== binding.planHash
+    || attestation.evidenceHash !== binding.evidenceHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review reviewer attestation does not match the current completion binding.', {
+      stepId: binding.stepId,
+      completionCommit: binding.completionCommit,
+      reviewEventId: reviewRecordedEvent.eventId,
+      attestationEventId: attestation.eventId,
+    });
+  }
+}
+
+function validateHistoricalAttestationBinding(
+  reviewRecordedEvent: StepReviewEvent,
+  attestation: ReviewerAttestationEvent,
+): void {
+  if (reviewRecordedEvent.eventType !== 'review-recorded') {
+    throw new WorkflowError('STATE_CORRUPT', 'Reviewer attestation must target a review-recorded Step Review event.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      reviewEventType: reviewRecordedEvent.eventType,
+      attestationEventId: attestation.eventId,
+    });
+  }
+  if (attestation.taskId !== reviewRecordedEvent.taskId
+    || attestation.stepId !== reviewRecordedEvent.stepId
+    || attestation.reviewedCommit !== reviewRecordedEvent.completionCommit
+    || attestation.reviewEventHash !== reviewRecordedEvent.eventHash
+    || attestation.planHash !== reviewRecordedEvent.planHash
+    || attestation.evidenceHash !== reviewRecordedEvent.evidenceHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Reviewer attestation does not match the referenced review-recorded Step Review event binding.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      attestationEventId: attestation.eventId,
+      reviewEventHash: reviewRecordedEvent.eventHash,
+    });
+  }
+}
+
+function validateAttestationVerifiedChain(
+  binding: StrictStepBinding,
+  reviewRecordedEvent: StepReviewEvent,
+  reviewerAttestationEvent: ReviewerAttestationEvent,
+  verifiedEvent: StepReviewEvent,
+): void {
+  if (!eventMatchesBinding(verifiedEvent, binding)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification does not match the current completion binding.', {
+      stepId: binding.stepId,
+      eventId: verifiedEvent.eventId,
+    });
+  }
+  if (reviewerAttestationEvent.isolationResult !== 'verified') {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification cannot exist for an unverified isolation result.', {
+      stepId: binding.stepId,
+      attestationEventId: reviewerAttestationEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+    });
+  }
+  if (verifiedEvent.reviewerAttestationHash !== reviewerAttestationEvent.eventHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification does not reference the expected attestation event.', {
+      stepId: binding.stepId,
+      attestationEventId: reviewerAttestationEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+    });
+  }
+  if (verifiedEvent.decision !== reviewRecordedEvent.decision) {
+    throw new WorkflowError('STATE_CORRUPT', 'Strict Step Review attestation verification decision does not match the review event.', {
+      stepId: binding.stepId,
+      reviewEventId: reviewRecordedEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+      reviewDecision: reviewRecordedEvent.decision,
+      verifiedDecision: verifiedEvent.decision,
+    });
+  }
+  validateAttestationBinding(binding, reviewRecordedEvent, reviewerAttestationEvent);
+}
+
+function validateHistoricalAttestationVerifiedChain(
+  reviewRecordedEvent: StepReviewEvent,
+  reviewerAttestationEvent: ReviewerAttestationEvent,
+  verifiedEvent: StepReviewEvent,
+): void {
+  if (reviewRecordedEvent.eventType !== 'review-recorded') {
+    throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review event must link to a review-recorded Step Review event.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      reviewEventType: reviewRecordedEvent.eventType,
+      verifiedEventId: verifiedEvent.eventId,
+    });
+  }
+  if (!stepReviewEventsMatchStructuralBinding(verifiedEvent, reviewRecordedEvent)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review event does not match the referenced review-recorded binding.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+    });
+  }
+  if (reviewerAttestationEvent.isolationResult !== 'verified') {
+    throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review event cannot link to an unverified reviewer attestation.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      reviewerAttestationEventId: reviewerAttestationEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+    });
+  }
+  if (verifiedEvent.reviewerAttestationHash !== reviewerAttestationEvent.eventHash) {
+    throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review event does not reference the expected reviewer attestation.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      reviewerAttestationEventId: reviewerAttestationEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+    });
+  }
+  if (verifiedEvent.decision !== reviewRecordedEvent.decision) {
+    throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review decision does not match the referenced review-recorded event.', {
+      reviewEventId: reviewRecordedEvent.eventId,
+      reviewerAttestationEventId: reviewerAttestationEvent.eventId,
+      verifiedEventId: verifiedEvent.eventId,
+      reviewDecision: reviewRecordedEvent.decision,
+      verifiedDecision: verifiedEvent.decision,
+    });
+  }
+  validateHistoricalAttestationBinding(reviewRecordedEvent, reviewerAttestationEvent);
+}
+
+function appendStepReviewEvent(
+  store: FileStateStore,
+  task: TaskState,
+  event: Omit<StepReviewEvent, 'previousEventHash' | 'eventHash'>,
+): StepReviewEvent {
+  return store.appendSidecarEvent<StepReviewEvent>(
+    store.taskRoot(task.projectId, task.id),
+    STEP_REVIEW_EVENTS_SIDECAR,
+    event,
+    {
+      validateEvent: (candidate, context) => validateStoredStepReviewEvent(candidate, task.id, context.file, context.line),
+    },
+  );
+}
+
+function appendReviewerAttestationEvent(
+  store: FileStateStore,
+  task: TaskState,
+  event: Omit<ReviewerAttestationEvent, 'previousEventHash' | 'eventHash'>,
+): ReviewerAttestationEvent {
+  return store.appendSidecarEvent<ReviewerAttestationEvent>(
+    store.taskRoot(task.projectId, task.id),
+    REVIEWER_ATTESTATIONS_SIDECAR,
+    event,
+    {
+      validateEvent: (candidate, context) =>
+        validateStoredReviewerAttestationEvent(candidate, task.id, context.file, context.line),
+    },
+  );
+}
+
+function validateStoredStepReviewEvent(
+  event: StepReviewEvent,
+  expectedTaskId: string,
+  file: string,
+  line: number,
+): void {
+  if (event.taskId !== expectedTaskId) {
+    throw new WorkflowError('STATE_CORRUPT', 'Step Review event task binding does not match its task root.', {
+      file,
+      line,
+      eventId: event.eventId,
+      expectedTaskId,
+      actualTaskId: event.taskId,
+    });
+  }
+  assertPositiveInteger(event.taskRevision, 'Step Review taskRevision', file, line, event.eventId);
+  assertNonEmptyString(event.stepId, 'Step Review stepId', file, line, event.eventId);
+  assertHash64(event.stepDefinitionHash, 'Step Review stepDefinitionHash');
+  assertGitSha(event.completionCommit, 'Step Review completionCommit', file, line, event.eventId);
+  assertHash64(event.checksHash, 'Step Review checksHash');
+  assertHash64(event.planHash, 'Step Review planHash');
+  assertOptionalHash64(event.evidenceHash, 'Step Review evidenceHash', file, line, event.eventId);
+  if (!STEP_REVIEW_EVENT_TYPES.has(event.eventType)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Step Review eventType is invalid.', {
+      file,
+      line,
+      eventId: event.eventId,
+      eventType: event.eventType,
+    });
+  }
+  if (!REVIEW_DECISIONS.has(event.decision)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Step Review decision is invalid.', {
+      file,
+      line,
+      eventId: event.eventId,
+      decision: event.decision,
+    });
+  }
+  if (event.eventType === 'pending') {
+    if (event.decision !== 'pending' || event.reviewerAttestationHash !== null
+      || event.remediationRoute !== undefined || event.planConflicts !== undefined
+      || event.remediationCauses !== undefined) {
+      throw new WorkflowError('STATE_CORRUPT', 'Pending Step Review event must remain unattested with decision pending.', {
+        file,
+        line,
+        eventId: event.eventId,
+      });
+    }
+  }
+  if (event.eventType === 'review-recorded') {
+    if (event.decision === 'pending' || event.reviewerAttestationHash !== null) {
+      throw new WorkflowError('STATE_CORRUPT', 'Review-recorded Step Review event must carry a terminal review decision and no attestation hash.', {
+        file,
+        line,
+        eventId: event.eventId,
+      });
+    }
+    validateStoredReviewRemediation(event, file, line);
+  }
+  if (event.eventType === 'attestation-verified') {
+    if (event.decision === 'pending' || typeof event.reviewerAttestationHash !== 'string'
+      || event.remediationRoute !== undefined || event.planConflicts !== undefined
+      || event.remediationCauses !== undefined) {
+      throw new WorkflowError('STATE_CORRUPT', 'Attestation-verified Step Review event must carry a terminal decision and attestation hash.', {
+        file,
+        line,
+        eventId: event.eventId,
+      });
+    }
+    assertHash64(event.reviewerAttestationHash, 'Step Review reviewerAttestationHash');
+  }
+}
+
+function reviewRemediationEventFields(
+  review: ReviewInput,
+): Pick<StepReviewEvent, 'remediationRoute' | 'planConflicts' | 'remediationCauses'> | Record<string, never> {
+  if (review.status !== 'failed') return {};
+  const replanFindings = review.findings.filter((finding) => (finding.route ?? 'fix') === 'replan');
+  const remediationCauses = review.findings.flatMap((finding) => finding.causeId ? [{
+    findingId: finding.id,
+    causeId: finding.causeId,
+    causeFingerprint: reviewerCauseFingerprint(finding.causeId),
+    route: finding.route ?? 'fix',
+    planConflict: (finding.route ?? 'fix') === 'replan' && finding.planConflict !== null,
+  }] : []);
+  return {
+    remediationRoute: replanFindings.length > 0 ? 'replan' : 'fix',
+    planConflicts: replanFindings.map((finding) => ({
+      findingId: finding.id,
+      planClause: finding.planConflict!.planClause,
+      whyFixCannotFit: finding.planConflict!.whyFixCannotFit,
+      minimalPlanChange: finding.planConflict!.minimalPlanChange,
+    })),
+    ...(remediationCauses.length > 0 ? { remediationCauses } : {}),
+  };
+}
+
+function validateFindingRemediationRoute(
+  finding: ReviewInput['findings'][number],
+  stepId: string,
+): void {
+  if (finding.causeId !== undefined
+    && !/^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$/.test(finding.causeId)) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review finding causeId is invalid.', {
+      stepId,
+      findingId: finding.id,
+    });
+  }
+  const route = finding.route ?? 'fix';
+  if (route !== 'fix' && route !== 'replan') {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Strict Step Review finding remediation route is invalid.', {
+      stepId,
+      findingId: finding.id,
+      route,
+    });
+  }
+  if (route === 'fix') {
+    if (finding.planConflict !== undefined && finding.planConflict !== null) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'A fix finding cannot carry a Plan conflict.', {
+        stepId,
+        findingId: finding.id,
+      });
+    }
+    return;
+  }
+  const conflict = finding.planConflict;
+  if (!conflict
+    || !conflict.planClause?.trim()
+    || !conflict.whyFixCannotFit?.trim()
+    || !conflict.minimalPlanChange?.trim()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'A replan finding requires an exact Plan clause, obstruction, and minimal Plan change.', {
+      stepId,
+      findingId: finding.id,
+    });
+  }
+}
+
+function validateStoredReviewRemediation(event: StepReviewEvent, file: string, line: number): void {
+  if (event.decision !== 'failed') {
+    if (event.remediationRoute !== undefined || event.planConflicts !== undefined
+      || event.remediationCauses !== undefined) {
+      throw new WorkflowError('STATE_CORRUPT', 'Only a failed review-recorded event may carry remediation routing.', {
+        file,
+        line,
+        eventId: event.eventId,
+      });
+    }
+    return;
+  }
+  const route = event.remediationRoute ?? 'fix';
+  const conflicts = event.planConflicts ?? [];
+  const causes = event.remediationCauses ?? [];
+  if (route !== 'fix' && route !== 'replan') {
+    throw new WorkflowError('STATE_CORRUPT', 'Review-recorded remediation route is invalid.', { file, line, eventId: event.eventId });
+  }
+  if ((route === 'fix' && conflicts.length > 0) || (route === 'replan' && conflicts.length === 0)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Review-recorded remediation route conflicts with its Plan evidence.', {
+      file,
+      line,
+      eventId: event.eventId,
+      route,
+    });
+  }
+  for (const conflict of conflicts) {
+    if (!conflict.findingId?.trim()
+      || !conflict.planClause?.trim()
+      || !conflict.whyFixCannotFit?.trim()
+      || !conflict.minimalPlanChange?.trim()) {
+      throw new WorkflowError('STATE_CORRUPT', 'Review-recorded Plan conflict evidence is incomplete.', {
+        file,
+        line,
+        eventId: event.eventId,
+      });
+    }
+  }
+  for (const cause of causes) {
+    if (!cause.findingId?.trim()
+      || !/^[A-Za-z0-9][A-Za-z0-9._:-]{2,127}$/.test(cause.causeId)
+      || cause.causeFingerprint !== reviewerCauseFingerprint(cause.causeId)
+      || cause.planConflict !== (cause.route === 'replan')) {
+      throw new WorkflowError('STATE_CORRUPT', 'Review-recorded cause evidence is invalid.', {
+        file, line, eventId: event.eventId,
+      });
+    }
+  }
+}
+
+function validateStoredReviewerAttestationEvent(
+  event: ReviewerAttestationEvent,
+  expectedTaskId: string,
+  file: string,
+  line: number,
+): void {
+  if (event.taskId !== expectedTaskId) {
+    throw new WorkflowError('STATE_CORRUPT', 'Reviewer attestation task binding does not match its task root.', {
+      file,
+      line,
+      eventId: event.eventId,
+      expectedTaskId,
+      actualTaskId: event.taskId,
+    });
+  }
+  assertNonEmptyString(event.stepId, 'Reviewer attestation stepId', file, line, event.eventId);
+  assertNonEmptyString(event.reviewer, 'Reviewer attestation reviewer', file, line, event.eventId);
+  if (event.isolationResult !== 'verified' && event.isolationResult !== 'unverified') {
+    throw new WorkflowError('STATE_CORRUPT', 'Reviewer attestation isolation result is invalid.', {
+      file,
+      line,
+      eventId: event.eventId,
+      isolationResult: event.isolationResult,
+    });
+  }
+  assertHash64(event.outputHash, 'Reviewer attestation outputHash');
+  assertGitSha(event.reviewedCommit, 'Reviewer attestation reviewedCommit', file, line, event.eventId);
+  assertHash64(event.reviewEventHash, 'Reviewer attestation reviewEventHash');
+  assertHash64(event.planHash, 'Reviewer attestation planHash');
+  assertOptionalHash64(event.evidenceHash, 'Reviewer attestation evidenceHash', file, line, event.eventId);
+}
+
+function findLastIndex<T>(items: readonly T[], predicate: (value: T) => boolean): number {
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    if (predicate(items[index]!)) return index;
+  }
+  return -1;
+}
+
+function indexStepReviewEventsByHash(
+  stepReviewEvents: readonly StepReviewEvent[],
+  eventType: StepReviewEventType,
+): Map<string, StepReviewEvent[]> {
+  const indexed = new Map<string, StepReviewEvent[]>();
+  for (const event of stepReviewEvents) {
+    if (event.eventType !== eventType) continue;
+    const matches = indexed.get(event.eventHash) ?? [];
+    matches.push(event);
+    indexed.set(event.eventHash, matches);
+  }
+  return indexed;
+}
+
+function indexReviewerAttestationsByHash(
+  reviewerAttestations: readonly ReviewerAttestationEvent[],
+): Map<string, ReviewerAttestationEvent[]> {
+  const indexed = new Map<string, ReviewerAttestationEvent[]>();
+  for (const event of reviewerAttestations) {
+    const matches = indexed.get(event.eventHash) ?? [];
+    matches.push(event);
+    indexed.set(event.eventHash, matches);
+  }
+  return indexed;
+}
+
+function assertPositiveInteger(value: unknown, label: string, file: string, line: number, eventId: string): void {
+  if (!Number.isInteger(value) || Number(value) < 1) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a positive integer.`, {
+      file,
+      line,
+      eventId,
+      value,
+    });
+  }
+}
+
+function assertNonEmptyString(value: unknown, label: string, file: string, line: number, eventId: string): void {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a non-empty string.`, {
+      file,
+      line,
+      eventId,
+      value,
+    });
+  }
+}
+
+function assertGitSha(value: unknown, label: string, file: string, line: number, eventId: string): void {
+  if (typeof value !== 'string' || !GIT_SHA_PATTERN.test(value)) {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be a full Git SHA.`, {
+      file,
+      line,
+      eventId,
+      value,
+    });
+  }
+}
+
+function assertOptionalHash64(value: unknown, label: string, file: string, line: number, eventId: string): void {
+  if (value === null) return;
+  if (typeof value !== 'string') {
+    throw new WorkflowError('STATE_CORRUPT', `${label} must be null or a sha256 hex digest.`, {
+      file,
+      line,
+      eventId,
+      value,
+    });
+  }
+  assertHash64(value, label);
+}