@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/review-finalization.ts

@@ -1,9 +1,7 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
 
-import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
-import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
+import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.ts';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { LedgerStageStatus, ReviewStage } from './ledger.ts';
 import { finalizeReviewSummaryContent } from './review-artifacts.ts';
@@ -16,8 +14,15 @@ import { allowsManualOverride } from './guard-override.ts';
 import type { ManualOverrideCapability } from './guard-override.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
-import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.ts';
-import type { ArtifactRepairOperation } from './artifact-operations.ts';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
+import {
+  beginArtifactRecovery,
+  commitArtifactRecovery,
+  prepareArtifactRecoveryCommit,
+  recoveryContextFromIntent,
+  stageArtifactCandidate
+} from './artifact-recovery.ts';
+import type { ArtifactRecoveryContext } from './artifact-recovery.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -34,8 +39,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
-  | 'REVIEW_TEMP_WRITE_FAILED'
-  | 'REVIEW_RENAME_FAILED';
+  | 'REVIEW_RECOVERY_COMMIT_FAILED';
 type ReviewFinalizationError = { code: ReviewFinalizationErrorCode; message: string };
 type ReviewFinalizationRequest = {
   taskRef: string;
@@ -43,6 +47,7 @@ type ReviewFinalizationRequest = {
   artifact: string;
   orchestrated?: boolean;
   dryRun?: boolean;
+  recoveryId?: string;
 };
 type ReviewFinalizationResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed';
@@ -55,8 +60,12 @@ type ReviewFinalizationResult = {
   stageStatus: LedgerStageStatus | null;
   artifactSha256: string | null;
   semanticDigest: string | null;
-  repairable: boolean;
-  operation: ArtifactRepairOperation | null;
+  recovery?: Readonly<{
+    recoveryId: string;
+    candidatePath: string;
+    baselineSha256: string;
+    baselineSemanticDigest: string;
+  }>;
   operations: readonly {
     kind: 'artifact';
     artifact: string;
@@ -66,30 +75,22 @@ type ReviewFinalizationResult = {
 };
 type ReviewFileSystem = {
   readFileSync: (file: string) => string;
-  statModeSync: (file: string) => number;
-  writeFileSync: (file: string, content: string, mode: number) => void;
-  renameSync: (from: string, to: string) => void;
-  unlinkSync: (file: string) => void;
 };
 type ReviewFinalizationOptions = {
   repoRoot?: string;
-  randomSuffix?: () => string;
   fileSystem?: Partial<ReviewFileSystem>;
   manualOverride?: ManualOverrideCapability;
   lockAlreadyHeld?: boolean;
+  startRecovery?: boolean;
 };
 
-const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code'; action: string }> = {
-  analysis: { family: 'review-analysis', action: 'Review Analysis' },
-  plan: { family: 'review-plan', action: 'Review Plan' },
-  code: { family: 'review-code', action: 'Review Code' }
+const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code' }> = {
+  analysis: { family: 'review-analysis' },
+  plan: { family: 'review-plan' },
+  code: { family: 'review-code' }
 };
 const DEFAULT_FILE_SYSTEM: ReviewFileSystem = {
-  readFileSync: (file) => fs.readFileSync(file, 'utf8'),
-  statModeSync: (file) => fs.statSync(file).mode,
-  writeFileSync: (file, content, mode) => fs.writeFileSync(file, content, { encoding: 'utf8', flag: 'wx', mode }),
-  renameSync: (from, to) => fs.renameSync(from, to),
-  unlinkSync: (file) => fs.unlinkSync(file)
+  readFileSync: (file) => fs.readFileSync(file, 'utf8')
 };
 
 function failed(
@@ -111,328 +112,217 @@ function failed(
     stageStatus,
     artifactSha256: null,
     semanticDigest: null,
-    repairable: false,
-    operation: null,
     operations: [],
     error: { code, message },
     ...extra
   };
 }
 
-function openReviewRound(content: string, action: string, round: number): boolean {
-  const section = locateActivityLog(content);
-  if (!section) return false;
-  const expected = `${action} (Round ${round})`;
-  return startedBackedRows(pairEntries(section.entries)).filter((row) => (
-    row.step === expected && !row.done
-  )).length === 1;
-}
-
-function cleanupTemp(fileSystem: ReviewFileSystem, tempPath: string): void {
-  try {
-    fileSystem.unlinkSync(tempPath);
-  } catch {
-    // Best-effort cleanup preserves the primary failure.
-  }
-}
+type ReviewSummaryCandidatePreparation = Readonly<{
+  result: ReviewFinalizationResult;
+  content: string;
+  recovery?: ArtifactRecoveryContext;
+  lockAlreadyHeld?: boolean;
+}>;
 
-function finalizeReviewSummaryUnlocked(
+/** Prepare domain validation, summary bytes and provenance before any publication. */
+function prepareReviewSummaryCandidate(
   request: ReviewFinalizationRequest,
+  artifactContent: string,
   options: ReviewFinalizationOptions = {}
-): ReviewFinalizationResult {
+): ReviewSummaryCandidatePreparation {
+  let taskId: string | null = null;
+  let stageStatus: LedgerStageStatus | null = null;
+  const reject = (code: ReviewFinalizationErrorCode, message: string, extra: Partial<ReviewFinalizationResult> = {}): ReviewSummaryCandidatePreparation => ({
+    result: failed(request, code, message, taskId, stageStatus, extra), content: artifactContent
+  });
   const stage = request.stage as ReviewStage;
   const spec = STAGES[stage];
-  if (!spec) return failed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
-  if (!request.taskRef || !request.artifact) {
-    return failed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
-  }
+  if (!spec) return reject('REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+  if (!request.taskRef || !request.artifact) return reject('REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
+  taskId = resolved.taskId ?? null;
+  if (!resolved.ok) return reject(resolved.code, resolved.message);
   if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
-    return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    return reject('TASK_STATE_MISMATCH', `task ${taskId} is ${resolved.state}, expected active`);
   }
-  const parsedArtifact = parseArtifactName(request.artifact);
-  if (!parsedArtifact || parsedArtifact.family !== spec.family) {
-    return failed(
-      request,
-      'REVIEW_ARTIFACT_IDENTITY_INVALID',
-      `artifact '${request.artifact}' does not match ${spec.family}`,
-      resolved.taskId
-    );
-  }
-  const validated = validateCompletedArtifact(
-    resolved.taskDir,
-    spec.family,
-    request.artifact,
-    parsedArtifact.round
-  );
-  if (!validated.ok) {
-    const code = validated.error.code === 'ARTIFACT_NOT_REGULAR'
-      ? 'REVIEW_ARTIFACT_NOT_REGULAR'
-      : 'REVIEW_ARTIFACT_IDENTITY_INVALID';
-    return failed(request, code, validated.error.message, resolved.taskId);
-  }
-
-  const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+  const parsed = parseArtifactName(request.artifact);
+  if (!parsed || parsed.family !== spec.family) return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`);
+  const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
+  if (publicationError) return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message);
   let taskContent: string;
-  let artifactContent: string;
-  try {
-    taskContent = fileSystem.readFileSync(resolved.taskMdPath);
-    artifactContent = fileSystem.readFileSync(validated.artifact.path);
-  } catch (error) {
-    return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+  try { taskContent = (options.fileSystem?.readFileSync ?? DEFAULT_FILE_SYSTEM.readFileSync)(resolved.taskMdPath); }
+  catch (error) { return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error)); }
+  let recovery: ArtifactRecoveryContext | undefined;
+  if (request.recoveryId) {
+    try {
+      const intent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact);
+      if (!intent || intent.recoveryOperationId !== request.recoveryId) return reject('REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal');
+      if (!['awaiting-recovery', 'finalize-ready', 'commit-started'].includes(intent.state)) return reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`);
+      recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+      artifactContent = fs.existsSync(recovery.stagingPath)
+        ? fs.readFileSync(recovery.stagingPath, 'utf8')
+        : fs.readFileSync(recovery.formalPath, 'utf8');
+    } catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error)); }
   }
-  const schema = getArtifactSchema(spec.family);
-  const structure = schema ? inspectArtifactContract(artifactContent, schema) : null;
   const artifactSha256 = sha256Content(artifactContent);
-  const artifactSemanticDigest = canonicalSemanticDigest(artifactContent);
+  const semanticDigest = canonicalSemanticDigest(artifactContent);
+  const digests = { artifactSha256, semanticDigest };
   let repairIntent;
-  try {
-    repairIntent = readArtifactRepairIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
-  } catch (error) {
-    return failed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, null, {
-      artifactSha256,
-      semanticDigest: artifactSemanticDigest
-    });
-  }
-  if (structure && !structure.ok) {
-    const repairable = structure.repair !== null && structure.diagnostics.length === 1 && structure.diagnostics[0]?.repairable === true;
-    if (repairable) {
-      if (repairIntent && (
-        repairIntent.state !== 'awaiting-repair' ||
-        repairIntent.artifactSha256 !== artifactSha256 ||
-        repairIntent.semanticDigest !== structure.semanticDigest
-      )) {
-        return failed(request, 'REVIEW_PROVENANCE_INVALID', 'a different review repair baseline is already recorded for this artifact', resolved.taskId, null, {
-          artifactSha256,
-          semanticDigest: structure.semanticDigest
-        });
-      }
-      try {
-        if (!repairIntent) {
-          writeArtifactRepairIntent(resolved.repoRoot, {
-            version: 1,
-            taskId: resolved.taskId,
-            family: spec.family,
-            artifact: request.artifact,
-            state: 'awaiting-repair',
-            baselineSemanticDigest: structure.semanticDigest,
-            artifactSha256,
-            semanticDigest: structure.semanticDigest
-          });
-        }
-      } catch (error) {
-        return failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repair provenance: ${String(error)}`, resolved.taskId, null, {
-          artifactSha256,
-          semanticDigest: structure.semanticDigest,
-          operation: structure.repair
-        });
-      }
+  try { repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact); }
+  catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), digests); }
+  if (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed') {
+    if (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest) {
+      return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
     }
-    return failed(
-      request,
-      'REVIEW_ARTIFACT_STRUCTURE_INVALID',
-      structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '),
-      resolved.taskId,
-      null,
-      {
-        artifactSha256,
-        semanticDigest: structure.semanticDigest,
-        repairable,
-        operation: structure.repair
-      }
-    );
-  }
-  if (repairIntent?.state === 'awaiting-repair' && repairIntent.baselineSemanticDigest !== artifactSemanticDigest) {
-    return failed(request, 'REVIEW_PROVENANCE_INVALID', 'the repaired review artifact semantic digest does not match the recorded repair baseline', resolved.taskId, null, {
-      artifactSha256,
-      semanticDigest: artifactSemanticDigest
-    });
   }
-  if ((repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')
-    && (repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== artifactSemanticDigest)) {
-    return failed(request, 'REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', resolved.taskId, null, {
-      artifactSha256,
-      semanticDigest: artifactSemanticDigest
-    });
-  }
-  if (!openReviewRound(taskContent, spec.action, parsedArtifact.round)) {
-    return failed(
-      request,
-      'REVIEW_ARTIFACT_IDENTITY_INVALID',
-      `${request.artifact} does not have one matching open started review event`,
-      resolved.taskId
-    );
+  if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
+    return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
   }
   const execution = validateLifecycleExecution(request.taskRef, {
     mode: request.orchestrated ? 'orchestrated' : 'standalone',
-    identity: {
-      stage: spec.family,
-      round: parsedArtifact.round,
-      artifact: request.artifact,
-      role: 'reviewer'
-    },
+    identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
     dryRun: request.dryRun
   }, { repoRoot: options.repoRoot });
   if (!execution.ok) {
-    return failed(
-      request,
-      'REVIEW_PROVENANCE_INVALID',
-      `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`,
-      resolved.taskId
-    );
+    return reject('REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`);
   }
-
-  let rows;
   try {
     const ledger = parseLedgerDocument(taskContent);
-    if (!ledger.present) {
-      return failed(request, 'REVIEW_LEDGER_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`, resolved.taskId);
-    }
-    rows = ledger.rows;
-  } catch (error) {
-    return failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
-  }
-  const ledgerError = validateLedgerRows(rows);
-  if (ledgerError) {
-    return failed(
-      request,
-      'REVIEW_LEDGER_INVALID',
-      `${ledgerError.code}: ${ledgerError.message}`,
-      resolved.taskId
-    );
-  }
-  const stageStatus = summarizeLedgerStage(rows, stage);
-  const detailInspection = inspectDecisionDetailDuplicates(artifactContent);
-  if (!detailInspection.ok) {
-    return failed(
-      request,
-      'REVIEW_DECISION_DETAIL_INVALID',
-      `${detailInspection.code}: ${detailInspection.message}`,
-      resolved.taskId,
-      stageStatus
-    );
-  }
-  const transformed = finalizeReviewSummaryContent(
-    artifactContent,
-    stageStatus.unresolvedFindingCounts
-  );
-  if (!transformed.ok) {
-    return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
-  }
-  if (!transformed.changed) {
-    if (repairIntent?.state === 'awaiting-repair') {
+    if (!ledger.present) return reject('REVIEW_LEDGER_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`);
+    const error = validateLedgerRows(ledger.rows);
+    if (error) return reject('REVIEW_LEDGER_INVALID', `${error.code}: ${error.message}`);
+    stageStatus = summarizeLedgerStage(ledger.rows, stage);
+  } catch (error) { return reject('REVIEW_LEDGER_INVALID', String(error)); }
+  const detail = inspectDecisionDetailDuplicates(artifactContent);
+  if (!detail.ok) return reject('REVIEW_DECISION_DETAIL_INVALID', `${detail.code}: ${detail.message}`);
+  const schema = getArtifactSchema(spec.family)!;
+  const structure = inspectArtifactContract(artifactContent, schema);
+  if (!structure.ok) {
+    if (!recovery && !request.dryRun && options.startRecovery) {
       try {
-        writeArtifactRepairIntent(resolved.repoRoot, {
-          ...repairIntent,
-          state: 'passed',
-          artifactSha256,
-          semanticDigest: artifactSemanticDigest
-        });
-      } catch (error) {
-        return failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repaired review provenance: ${String(error)}`, resolved.taskId, stageStatus, {
-          artifactSha256,
-          semanticDigest: artifactSemanticDigest
-        });
-      }
+        recovery = beginArtifactRecovery({
+          taskId: taskId!, family: spec.family, artifact: request.artifact, round: parsed.round,
+          requestId: `review-finalize:${taskId!}:${stage}:${parsed.round}`
+        }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+      } catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), digests); }
     }
     return {
-      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus, {
-        artifactSha256,
-        semanticDigest: artifactSemanticDigest
+      ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
+        artifactSha256, semanticDigest: structure.semanticDigest,
+        ...(recovery ? { recovery: {
+          recoveryId: recovery.recoveryId,
+          candidatePath: recovery.stagingPath,
+          baselineSha256: recovery.baselineSha256,
+          baselineSemanticDigest: recovery.baselineSemanticDigest
+        } } : {})
       }),
-      status: 'no-op',
-      error: null
+      ...(recovery ? { recovery } : {})
     };
   }
-  const operations = [{ kind: 'artifact' as const, artifact: request.artifact, operation: 'update' as const }];
-  if (request.dryRun) {
+  const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
+  if (!transformed.ok) return reject(transformed.code, transformed.message);
+  const finalDigests = { artifactSha256: sha256Content(transformed.content), semanticDigest: canonicalSemanticDigest(transformed.content) };
+  if (!recovery && (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')) {
+    if (transformed.changed) return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact requires changes after its completed recovery was consumed', finalDigests);
     return {
-      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus, {
-        artifactSha256: sha256Content(transformed.content),
-        semanticDigest: canonicalSemanticDigest(transformed.content)
-      }),
-      status: 'planned',
-      changed: true,
-      operations,
-      error: null
+      content: transformed.content,
+      result: {
+        ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
+        status: 'no-op',
+        changed: false,
+        error: null
+      },
+      lockAlreadyHeld: options.lockAlreadyHeld
     };
   }
-
-  const tempPath = path.join(
-    resolved.taskDir,
-    `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`
-  );
-  let mode: number;
-  try {
-    mode = fileSystem.statModeSync(validated.artifact.path);
-    fileSystem.writeFileSync(tempPath, transformed.content, mode);
-  } catch (error) {
-    cleanupTemp(fileSystem, tempPath);
-    return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, stageStatus);
+  if (!recovery && !request.dryRun && options.startRecovery) {
+    try {
+      recovery = beginArtifactRecovery({
+        taskId: taskId!, family: spec.family, artifact: request.artifact, round: parsed.round,
+        requestId: `review-finalize:${taskId!}:${stage}:${parsed.round}`
+      }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+    } catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), finalDigests); }
   }
+  return {
+    content: transformed.content,
+    result: {
+      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
+      status: transformed.changed ? request.dryRun ? 'planned' : 'applied' : 'no-op',
+      changed: transformed.changed,
+      operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
+      error: null
+    },
+    ...(recovery ? { recovery } : {}),
+    lockAlreadyHeld: options.lockAlreadyHeld
+  };
+}
+
+function commitReviewSummaryProvenance(
+  prepared: ReviewSummaryCandidatePreparation,
+  repoRoot: string
+): ReviewFinalizationResult {
+  if (prepared.result.status === 'failed' || !prepared.recovery) return prepared.result;
   try {
-    if (fileSystem.readFileSync(validated.artifact.path) !== artifactContent) {
-      cleanupTemp(fileSystem, tempPath);
-      return failed(
-        request,
-        'REVIEW_ARTIFACT_CONFLICT',
-        `${request.artifact} changed during finalization`,
-        resolved.taskId,
-        stageStatus
-      );
+    const intent = readArtifactRecoveryIntent(prepared.recovery.repoRoot, prepared.recovery.taskId, prepared.recovery.family, prepared.recovery.artifact);
+    if (!intent) throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
+    let committed;
+    if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+    } else {
+      const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+      prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
     }
-    fileSystem.renameSync(tempPath, validated.artifact.path);
+    if (committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+    return {
+      ...prepared.result,
+      artifactSha256: committed.finalArtifactSha256,
+      semanticDigest: committed.finalSemanticDigest,
+      error: null
+    };
   } catch (error) {
-    cleanupTemp(fileSystem, tempPath);
-    return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, stageStatus);
+    return { ...prepared.result, status: 'failed', error: {
+      code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
+    } };
   }
-  if (repairIntent?.state === 'awaiting-repair') {
-    try {
-      writeArtifactRepairIntent(resolved.repoRoot, {
-        ...repairIntent,
-        state: 'passed',
-        artifactSha256: sha256Content(transformed.content),
-        semanticDigest: canonicalSemanticDigest(transformed.content)
-      });
-    } catch (error) {
-      return failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repaired review provenance: ${String(error)}`, resolved.taskId, stageStatus, {
-        artifactSha256: sha256Content(transformed.content),
-        semanticDigest: canonicalSemanticDigest(transformed.content)
-      });
-    }
+}
+
+function finalizeReviewSummaryUnlocked(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewFinalizationResult {
+  const spec = STAGES[request.stage as ReviewStage];
+  if (!spec || !request.taskRef || !request.artifact) return prepareReviewSummaryCandidate(request, '', options).result;
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
+  const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+  if (!validated.ok) {
+    return failed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
   }
-  return {
-    status: 'applied',
-    changed: true,
-    intent: 'finalize-summary',
-    requestRef: request.taskRef,
-    taskId: resolved.taskId,
-    stage,
-    artifact: request.artifact,
-    stageStatus,
-    artifactSha256: sha256Content(transformed.content),
-    semanticDigest: canonicalSemanticDigest(transformed.content),
-    repairable: false,
-    operation: null,
-    operations,
-    error: null
-  };
+  const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+  let content: string;
+  try { content = fileSystem.readFileSync(validated.artifact.path); }
+  catch (error) { return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId); }
+  const prepared = prepareReviewSummaryCandidate(request, content, options);
+  if (request.dryRun) return prepared.result;
+  return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
 }
 
 function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
-  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, options);
+  const effectiveOptions = { ...options, startRecovery: !request.dryRun };
+  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
+  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
   try {
     return withTaskExecutionLock(
       resolved.repoRoot,
       resolved.taskId,
       'task-review.finalize-summary',
-      () => finalizeReviewSummaryUnlocked(request, options)
+      () => finalizeReviewSummaryUnlocked(request, { ...effectiveOptions, lockAlreadyHeld: true })
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;
@@ -445,11 +335,12 @@ function finalizeReviewSummary(
   }
 }
 
-export { finalizeReviewSummary };
+export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 export type {
   ReviewFinalizationError,
   ReviewFinalizationErrorCode,
   ReviewFinalizationOptions,
   ReviewFinalizationRequest,
-  ReviewFinalizationResult
+  ReviewFinalizationResult,
+  ReviewSummaryCandidatePreparation
 };

package/lib/task/review-fingerprint.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { artifactName, maxRound } from "./review-artifacts.ts";
+import { artifactName, maxArtifactRound } from "./artifact-name.ts";
 import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.ts";
 
 type ReviewedGitTree = string & { readonly __reviewedGitTree: unique symbol };
@@ -45,7 +45,7 @@ export function resolvePostReviewGlobs(
 
 export function findAuthoritativeReviewCodeArtifact(taskDir: string) {
   const entries = fs.existsSync(taskDir) ? fs.readdirSync(taskDir) : [];
-  const round = maxRound(entries, "review-code");
+  const round = maxArtifactRound(entries, "review-code");
   if (round === 0) {
     return { ok: false, round: 0, fileName: null, path: null, error: null };
   }