@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/task/review-finalization.js

@@ -1,8 +1,6 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.js';
-import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { parseArtifactName } from './artifact-name.js';
+import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { inspectDecisionDetailDuplicates } from './decision-details.js';
@@ -12,18 +10,15 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import { allowsManualOverride } from './guard-override.js';
 import { getArtifactSchema } from './artifact-schema.js';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.js';
-import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.js';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryCommit, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
-    analysis: { family: 'review-analysis', action: 'Review Analysis' },
-    plan: { family: 'review-plan', action: 'Review Plan' },
-    code: { family: 'review-code', action: 'Review Code' }
+    analysis: { family: 'review-analysis' },
+    plan: { family: 'review-plan' },
+    code: { family: 'review-code' }
 };
 const DEFAULT_FILE_SYSTEM = {
-    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(request, code, message, taskId = null, stageStatus = null, extra = {}) {
     return {
@@ -37,271 +32,235 @@ function failed(request, code, message, taskId = null, stageStatus = null, extra
         stageStatus,
         artifactSha256: null,
         semanticDigest: null,
-        repairable: false,
-        operation: null,
         operations: [],
         error: { code, message },
         ...extra
     };
 }
-function openReviewRound(content, action, round) {
-    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, tempPath) {
-    try {
-        fileSystem.unlinkSync(tempPath);
-    }
-    catch {
-        // Best-effort cleanup preserves the primary failure.
-    }
-}
-function finalizeReviewSummaryUnlocked(request, options = {}) {
+/** Prepare domain validation, summary bytes and provenance before any publication. */
+function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
+    let taskId = null;
+    let stageStatus = null;
+    const reject = (code, message, extra = {}) => ({
+        result: failed(request, code, message, taskId, stageStatus, extra), content: artifactContent
+    });
     const stage = request.stage;
     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');
-    }
+        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 });
+    taskId = resolved.taskId ?? null;
     if (!resolved.ok)
-        return failed(request, resolved.code, resolved.message, resolved.taskId);
+        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;
-    let artifactContent;
     try {
-        taskContent = fileSystem.readFileSync(resolved.taskMdPath);
-        artifactContent = fileSystem.readFileSync(validated.artifact.path);
+        taskContent = (options.fileSystem?.readFileSync ?? DEFAULT_FILE_SYSTEM.readFileSync)(resolved.taskMdPath);
     }
     catch (error) {
-        return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+        return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error));
+    }
+    let recovery;
+    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);
+        repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
     }
     catch (error) {
-        return failed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, null, {
-            artifactSha256,
-            semanticDigest: artifactSemanticDigest
-        });
+        return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
     }
-    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
-                });
-            }
+    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;
+        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 failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
+        return reject('REVIEW_LEDGER_INVALID', String(error));
     }
-    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') {
+    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
-                });
+                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 failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repaired review provenance: ${String(error)}`, resolved.taskId, stageStatus, {
-                    artifactSha256,
-                    semanticDigest: artifactSemanticDigest
-                });
+                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', artifact: request.artifact, operation: 'update' }];
-    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;
+    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, repoRoot) {
+    if (prepared.result.status === 'failed' || !prepared.recovery)
+        return prepared.result;
     try {
-        mode = fileSystem.statModeSync(validated.artifact.path);
-        fileSystem.writeFileSync(tempPath, transformed.content, mode);
+        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 });
+        }
+        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_TEMP_WRITE_FAILED', String(error), resolved.taskId, stageStatus);
+        return { ...prepared.result, status: 'failed', error: {
+                code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
+            } };
+    }
+}
+function finalizeReviewSummaryUnlocked(request, options = {}) {
+    const spec = STAGES[request.stage];
+    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);
     }
+    const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+    let content;
     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);
-        }
-        fileSystem.renameSync(tempPath, validated.artifact.path);
+        content = fileSystem.readFileSync(validated.artifact.path);
     }
     catch (error) {
-        cleanupTemp(fileSystem, tempPath);
-        return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, stageStatus);
-    }
-    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)
-            });
-        }
+        return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), 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 prepared = prepareReviewSummaryCandidate(request, content, options);
+    if (request.dryRun)
+        return prepared.result;
+    return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
 }
 function finalizeReviewSummary(request, options = {}) {
+    const effectiveOptions = { ...options, startRecovery: !request.dryRun };
     if (request.dryRun || options.lockAlreadyHeld)
-        return finalizeReviewSummaryUnlocked(request, options);
+        return finalizeReviewSummaryUnlocked(request, effectiveOptions);
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
-        return finalizeReviewSummaryUnlocked(request, options);
+        return finalizeReviewSummaryUnlocked(request, effectiveOptions);
     try {
-        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => finalizeReviewSummaryUnlocked(request, options));
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => finalizeReviewSummaryUnlocked(request, { ...effectiveOptions, lockAlreadyHeld: true }));
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))
@@ -309,5 +268,5 @@ function finalizeReviewSummary(request, options = {}) {
         return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
-export { finalizeReviewSummary };
+export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 //# sourceMappingURL=review-finalization.js.map

package/dist/lib/task/review-fingerprint.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { artifactName, maxRound } from "./review-artifacts.js";
+import { artifactName, maxArtifactRound } from "./artifact-name.js";
 import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.js";
 const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
 export function parseReviewedGitTree(value) {
@@ -29,7 +29,7 @@ export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
 }
 export function findAuthoritativeReviewCodeArtifact(taskDir) {
     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 };
     }

package/dist/lib/task/sections.js

@@ -1,3 +1,4 @@
+import { scanVisibleMarkdown } from './markdown.js';
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -27,10 +28,13 @@ function parseTable(content, input) {
         throw new DocumentMutationError('TASK_DOCUMENT_INVALID', 'table section is ambiguous');
     }
     const section = sections[0];
+    const visibleStarts = new Set(scanVisibleMarkdown(content).lines.map((line) => line.start));
     const sectionLines = linesOf(content).filter((line) => line.start >= section.bodyStart && line.start < section.end);
     const firstContent = sectionLines.findIndex((line) => line.text.trim() !== '');
     const tables = [];
     for (let index = 0; index + 1 < sectionLines.length; index += 1) {
+        if (!visibleStarts.has(sectionLines[index].start) || !visibleStarts.has(sectionLines[index + 1].start))
+            continue;
         const header = splitTableCells(sectionLines[index].text);
         const separator = splitTableCells(sectionLines[index + 1].text);
         if (!header || !separator || header.cells.length !== input.columns.length)
@@ -97,24 +101,23 @@ function documentEol(content) {
 }
 function matchingSections(content, aliases) {
     const allowed = new Set(aliases);
-    return linesOf(content)
-        .map((line, index, lines) => {
-        const match = /^(#{2,3})\s+(.+?)\s*$/.exec(line.text);
-        if (!match?.[2] || !allowed.has(match[2]))
+    const lines = new Map(linesOf(content).map((line) => [line.start, line]));
+    const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2 || heading.level === 3);
+    return headings
+        .map((heading, index) => {
+        if (!allowed.has(heading.text))
             return null;
-        const level = match[1].length;
-        let end = content.length;
-        for (let i = index + 1; i < lines.length; i += 1) {
-            const nextHeading = /^(#{2,3})\s+/.exec(lines[i].text);
-            if (nextHeading && nextHeading[1].length <= level) {
-                end = lines[i].start;
-                break;
-            }
-        }
-        return { heading: match[2], line, bodyStart: line.end, end };
+        const next = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+        const line = lines.get(heading.start);
+        return { heading: heading.text, level: heading.level, line, bodyStart: line.end, end: next?.start ?? content.length };
     })
         .filter((match) => match !== null);
 }
+// Select the first visible section at the requested level, in document order.
+function findSectionRange(content, aliases, level = 2) {
+    const section = matchingSections(content, aliases).find((candidate) => candidate.level === level);
+    return section ? { start: section.line.start, bodyStart: section.bodyStart, end: section.end, heading: section.heading } : null;
+}
 function validateAliases(aliases, name) {
     if (!Array.isArray(aliases) || aliases.length === 0 || aliases.some((alias) => !alias || /[\r\n]/.test(alias))) {
         throw new DocumentMutationError('MUTATION_INVALID', `${name} must contain headings`);
@@ -261,9 +264,12 @@ function mutateTableRow(content, mutation) {
         throw new DocumentMutationError(sections.length === 0 ? 'TABLE_NOT_FOUND' : 'TASK_DOCUMENT_INVALID', sections.length === 0 ? 'table section not found' : 'table section is ambiguous');
     }
     const section = sections[0];
+    const visibleStarts = new Set(scanVisibleMarkdown(content).lines.map((line) => line.start));
     const sectionLines = linesOf(content).filter((line) => line.start >= section.bodyStart && line.start < section.end);
     const tables = [];
     for (let i = 0; i + 1 < sectionLines.length; i += 1) {
+        if (!visibleStarts.has(sectionLines[i].start) || !visibleStarts.has(sectionLines[i + 1].start))
+            continue;
         const header = splitTableCells(sectionLines[i].text);
         const separator = splitTableCells(sectionLines[i + 1].text);
         if (!header || !separator || header.cells.length !== mutation.columns.length)
@@ -368,25 +374,12 @@ function mutateTableRow(content, mutation) {
  * lines are trimmed. Returns '' when no alias heading is present.
  */
 function extractSection(content, aliases) {
-    const lines = content.split('\n');
-    let start = -1;
-    for (let i = 0; i < lines.length; i += 1) {
-        const line = lines[i].trim();
-        if (aliases.some((alias) => new RegExp(`^##\\s+${escapeRegExp(alias)}\\s*$`).test(line))) {
-            start = i + 1;
-            break;
-        }
-    }
-    if (start === -1)
+    const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2);
+    const index = headings.findIndex((heading) => aliases.includes(heading.text));
+    if (index === -1)
         return '';
-    let end = lines.length;
-    for (let i = start; i < lines.length; i += 1) {
-        if (/^##\s+/.test(lines[i])) {
-            end = i;
-            break;
-        }
-    }
-    return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+    return content.slice(headings[index].end + 1, headings[index + 1]?.start ?? content.length)
+        .replace(/^(?:\r?\n)+|(?:\r?\n)+$/g, '');
 }
 /**
  * Return the heading alias that actually appears as a `## {alias}` line, so a
@@ -394,11 +387,8 @@ function extractSection(content, aliases) {
  * alias when none is present.
  */
 function findSectionHeading(content, aliases) {
-    for (const alias of aliases) {
-        if (new RegExp(`^##\\s+${escapeRegExp(alias)}\\s*$`, 'm').test(content))
-            return alias;
-    }
-    return aliases[0];
+    const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2);
+    return aliases.find((alias) => headings.some((heading) => heading.text === alias)) ?? aliases[0];
 }
 /**
  * Return the body of the first `### {headingPrefix}` sub-section, from the
@@ -409,25 +399,13 @@ function findSectionHeading(content, aliases) {
  * and trailing blank lines are trimmed. Returns '' when no match is present.
  */
 function extractSubSection(content, headingPrefix) {
-    const lines = content.split('\n');
-    const headRe = new RegExp(`^###\\s+${escapeRegExp(headingPrefix)}(?![\\w-])`);
-    let start = -1;
-    for (let i = 0; i < lines.length; i += 1) {
-        if (headRe.test(lines[i].trim())) {
-            start = i;
-            break;
-        }
-    }
-    if (start === -1)
+    const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2 || heading.level === 3);
+    const headRe = new RegExp(`^${escapeRegExp(headingPrefix)}(?![\\w-])`);
+    const index = headings.findIndex((heading) => heading.level === 3 && headRe.test(heading.text));
+    if (index === -1)
         return '';
-    let end = lines.length;
-    for (let i = start + 1; i < lines.length; i += 1) {
-        if (/^###?\s+/.test(lines[i])) {
-            end = i;
-            break;
-        }
-    }
-    return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+    return content.slice(headings[index].start, headings[index + 1]?.start ?? content.length)
+        .replace(/^(?:\r?\n)+|(?:\r?\n)+$/g, '');
 }
-export { extractSection, findSectionHeading, extractSubSection, parseTable, upsertSection, mutateTableRow, DocumentMutationError };
+export { findSectionRange, extractSection, findSectionHeading, extractSubSection, parseTable, upsertSection, mutateTableRow, DocumentMutationError };
 //# sourceMappingURL=sections.js.map