@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/dist/lib/task/pr-delivery-fact.js

@@ -1,4 +1,3 @@
-import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.js';
 import { isResourceIdentity, parseResourceIdentity, resourceIdentityNumber, serializeResourceIdentity } from '../platform/resource-identity.js';
 const PR_DELIVERY_FACT_KEY = 'pr_delivery_fact';
 function factError(message) {
@@ -28,11 +27,6 @@ function timestamp(value, label) {
         throw factError(`${label} must be a valid timestamp`);
     return new Date(result).toISOString();
 }
-function positiveNumber(value, label) {
-    if (!Number.isSafeInteger(value) || value <= 0)
-        throw factError(`${label} must be a positive integer`);
-    return value;
-}
 function parseRef(value, label) {
     if (!isRecord(value))
         throw factError(`${label} must be an object`);
@@ -51,36 +45,17 @@ function canonicalIdentity(value) {
         base: parseRef(value.base, 'identity.base')
     };
 }
-function decodeLegacyIdentity(value) {
-    if (!isRecord(value))
-        throw factError('legacy identity must be an object');
-    // TODO(compat): Remove the v1 identity decoder before the first stable v1.0.0 release.
-    exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'legacy identity');
-    const legacy = {
-        number: positiveNumber(value.number, 'legacy identity.number'),
-        repository: text(value.repository, 'identity.repository'),
-        nodeId: text(value.nodeId, 'legacy identity.nodeId'),
-        url: text(value.url, 'identity.url'),
-        head: parseRef(value.head, 'identity.head'),
-        base: parseRef(value.base, 'identity.base')
-    };
-    return {
-        resource: { kind: 'number', value: legacy.number },
-        repository: legacy.repository,
-        url: legacy.url,
-        head: legacy.head,
-        base: legacy.base
-    };
-}
 function provenanceForSource(source) { return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source; }
-function parseFact(value, runtimeVersion = VERSION) {
+function legacyFactError() {
+    return Object.assign(new Error('PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: v1 PR delivery fact is unsupported; use the previous tool version to view this task or migrate its fact to version 2 before using this version'), { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' });
+}
+function parseFact(value) {
     if (!isRecord(value))
         throw factError('fact must be an object');
-    if ((value.version !== 1 && value.version !== 2) || typeof value.state !== 'string')
+    if (value.version === 1)
+        throw legacyFactError();
+    if (value.version !== 2 || typeof value.state !== 'string')
         throw factError('version or state is invalid');
-    if (value.version === 1 && !isLegacyCompatibilityEnabled(runtimeVersion)) {
-        throw legacyCompatibilityError('v1 PR delivery fact', runtimeVersion);
-    }
     if (value.state === 'unbound') {
         exactKeys(value, ['version', 'state', 'reason'], 'unbound fact');
         if (value.reason !== 'initial')
@@ -95,25 +70,6 @@ function parseFact(value, runtimeVersion = VERSION) {
     }
     if (value.state !== 'bound')
         throw factError('state is invalid');
-    if (value.version === 1) {
-        // TODO(compat): Remove this v1-to-v2 shape conversion before the first stable v1.0.0 release.
-        exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'legacy bound fact');
-        if (!isRecord(value.binding) || !isRecord(value.provenance))
-            throw factError('legacy binding or provenance is invalid');
-        exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'legacy binding');
-        const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'legacy binding.issueNumber');
-        return parseFact({
-            version: 2,
-            state: 'bound',
-            identity: decodeLegacyIdentity(value.identity),
-            binding: {
-                status: 'verified', source: value.binding.source, verifiedAt: timestamp(value.binding.verifiedAt, 'binding.verifiedAt'),
-                issueIdentity: issueNumber === null ? null : { kind: 'number', value: issueNumber }, remoteState: value.binding.remoteState,
-                mergedAt: value.binding.mergedAt === null ? null : timestamp(value.binding.mergedAt, 'binding.mergedAt'), mergeCommitSha: nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha')
-            },
-            provenance: value.provenance
-        }, runtimeVersion);
-    }
     exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'bound fact');
     if (!isRecord(value.binding) || !isRecord(value.provenance))
         throw factError('binding or provenance is invalid');
@@ -142,7 +98,7 @@ function parseFact(value, runtimeVersion = VERSION) {
         provenance: { establishedBy: value.provenance.establishedBy }
     };
 }
-function decodePrDeliveryFact(value, runtimeVersion = VERSION) {
+function decodePrDeliveryFact(value, _runtimeVersion) {
     if (typeof value === 'string') {
         let decoded;
         try {
@@ -151,16 +107,16 @@ function decodePrDeliveryFact(value, runtimeVersion = VERSION) {
         catch {
             throw factError('value is not valid JSON');
         }
-        return parseFact(decoded, runtimeVersion);
+        return parseFact(decoded);
     }
-    return parseFact(value, runtimeVersion);
+    return parseFact(value);
 }
 function encodePrDeliveryFact(fact) { return JSON.stringify(parseFact(fact)); }
-function readPrDeliveryFact(metadata, runtimeVersion = VERSION) {
+function readPrDeliveryFact(metadata, _runtimeVersion) {
     if (!Object.hasOwn(metadata, PR_DELIVERY_FACT_KEY) || metadata[PR_DELIVERY_FACT_KEY] === '')
         return { status: 'missing', fact: null };
     try {
-        return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY], runtimeVersion) };
+        return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY]) };
     }
     catch (error) {
         return { status: 'invalid', fact: null, error: asFactError(error) };

package/dist/lib/task/recovery-warning.js

@@ -0,0 +1,19 @@
+function warningText(value) {
+    return typeof value === 'string' && value.length > 0 && value.trim() === value && !/[\r\n]/u.test(value);
+}
+export function isRecoveryWarning(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const warning = value;
+    return Object.keys(warning).sort().join(',') === 'action,code,message'
+        && warningText(warning.code)
+        && warningText(warning.message)
+        && warningText(warning.action);
+}
+export function sameRecoveryWarning(left, right) {
+    return isRecoveryWarning(left) && isRecoveryWarning(right)
+        && left.code === right.code
+        && left.message === right.message
+        && left.action === right.action;
+}
+//# sourceMappingURL=recovery-warning.js.map

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

@@ -1,9 +1,10 @@
 export function parseReviewCommand(args) {
-    if (!args[0] || args[1] !== 'finalize-summary')
-        throw new Error('task ref and finalize-summary are required');
+    if (!args[0] || !['preflight', 'finalize-summary'].includes(args[1] ?? ''))
+        throw new Error('task ref and a supported review operation are required');
     const values = {};
     const flags = {
         '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',
+        '--recovery-id': 'recoveryId',
         '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
     };
     for (let index = 2; index < args.length; index += 1) {

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

@@ -1,6 +1,4 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
 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';
@@ -12,18 +10,16 @@ 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 { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
     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,21 +33,167 @@ 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 cleanupTemp(fileSystem, tempPath) {
+function preflightFailed(request, code, message, taskId = null, extra = {}) {
+    const { status: _status, intent: _intent, stageStatus: _stageStatus, ...finalizationExtra } = extra;
+    return {
+        ...failed(request, code, message, taskId, null, finalizationExtra),
+        status: 'failed',
+        intent: 'preflight',
+        stageStatus: null
+    };
+}
+/** Validate and seal a review draft before any finding-ledger write. */
+function preflightReviewSummaryUnlocked(request, options = {}) {
+    const stage = request.stage;
+    const spec = STAGES[stage];
+    if (!spec)
+        return preflightFailed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+    if (!request.taskRef || !request.artifact)
+        return preflightFailed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return preflightFailed(request, resolved.code, resolved.message, resolved.taskId ?? null);
+    if (resolved.state !== 'active')
+        return preflightFailed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    const parsed = parseArtifactName(request.artifact);
+    if (!parsed || parsed.family !== spec.family)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`, resolved.taskId);
+    const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
+    if (publicationError)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
+    let taskContent;
+    let content;
+    let recovery;
+    let existingIntent;
     try {
-        fileSystem.unlinkSync(tempPath);
+        taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        if (request.recoveryId) {
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+            if (!intent || intent.recoveryOperationId !== request.recoveryId)
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal', resolved.taskId);
+            if (!['awaiting-preflight-recovery', 'preflight-ready'].includes(intent.state))
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`, resolved.taskId);
+            recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+            content = fs.existsSync(recovery.stagingPath)
+                ? fs.readFileSync(recovery.stagingPath, 'utf8')
+                : fs.readFileSync(recovery.formalPath, 'utf8');
+        }
+        else {
+            const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+            if (!validated.ok)
+                return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
+            content = fs.readFileSync(validated.artifact.path, 'utf8');
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+            existingIntent = intent;
+            if (intent?.state === 'preflight-ready')
+                recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+            if (intent?.state === 'consumed')
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'review artifact was already finalized', resolved.taskId);
+        }
     }
-    catch {
-        // Best-effort cleanup preserves the primary failure.
+    catch (error) {
+        return preflightFailed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+    }
+    if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round))
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
+    const execution = validateLifecycleExecution(request.taskRef, {
+        mode: request.orchestrated ? 'orchestrated' : 'standalone',
+        identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
+        dryRun: request.dryRun
+    }, { repoRoot: options.repoRoot });
+    if (!execution.ok)
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
+    const artifactSha256 = sha256Content(content);
+    const semanticDigest = canonicalSemanticDigest(content);
+    const detail = inspectDecisionDetailDuplicates(content);
+    const structure = inspectArtifactContract(content, getArtifactSchema(spec.family));
+    const expected = expectedQualificationRelations(taskContent, spec.family);
+    if (!expected.ok)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', `${expected.code}: ${expected.message}`, resolved.taskId, { artifactSha256, semanticDigest });
+    const qualification = validateQualificationAudit(taskContent, content, {
+        family: spec.family,
+        artifact: request.artifact,
+        expectedUpstreamRelations: expected.relations
+    });
+    const qualificationError = qualification.ok ? null : qualification;
+    if (!detail.ok || !structure.ok || qualificationError) {
+        if (!recovery && !request.dryRun) {
+            try {
+                recovery = beginArtifactRecovery({
+                    taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
+                    requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
+                }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+            }
+            catch (error) {
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId);
+            }
+        }
+        const diagnostics = [
+            ...(!detail.ok ? [`${detail.code}: ${detail.message}`] : []),
+            ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`),
+            ...(qualificationError ? [`${qualificationError.code}: ${qualificationError.message}`] : [])
+        ].join('; ');
+        return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : !structure.ok ? 'REVIEW_ARTIFACT_STRUCTURE_INVALID' : 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', diagnostics, resolved.taskId, {
+            artifactSha256, semanticDigest,
+            ...(recovery ? { recovery: recoveryInfo(recovery) } : {})
+        });
+    }
+    if (!recovery && existingIntent?.state === 'passed') {
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
+            status: 'passed', changed: false, error: null
+        };
+    }
+    if (request.dryRun || recovery && readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact)?.state === 'preflight-ready') {
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, ...(recovery ? { recovery: recoveryInfo(recovery) } : {}) }),
+            status: 'passed', changed: false, error: null
+        };
+    }
+    try {
+        recovery ??= beginArtifactRecovery({
+            taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
+            requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
+        }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+        const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: options.lockAlreadyHeld });
+        prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: options.lockAlreadyHeld });
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, recovery: recoveryInfo(recovery) }),
+            status: 'passed', changed: false, error: null
+        };
+    }
+    catch (error) {
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, { artifactSha256, semanticDigest });
+    }
+}
+function preflightReviewSummary(request, options = {}) {
+    if (request.dryRun || options.lockAlreadyHeld)
+        return preflightReviewSummaryUnlocked(request, options);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return preflightReviewSummaryUnlocked(request, options);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.preflight', () => preflightReviewSummaryUnlocked(request, { ...options, lockAlreadyHeld: true }));
+    }
+    catch (error) {
+        if (!(error instanceof TaskExecutionLockError))
+            throw error;
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
+function recoveryInfo(recovery) {
+    return {
+        recoveryId: recovery.recoveryId,
+        candidatePath: recovery.stagingPath,
+        baselineSha256: recovery.baselineSha256,
+        baselineSemanticDigest: recovery.baselineSemanticDigest
+    };
+}
 /** Prepare domain validation, summary bytes and provenance before any publication. */
 function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     let taskId = null;
@@ -85,43 +227,41 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     catch (error) {
         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-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-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 artifactSha256 = sha256Content(artifactContent);
     const semanticDigest = canonicalSemanticDigest(artifactContent);
     const digests = { artifactSha256, semanticDigest };
     let repairIntent;
     try {
-        repairIntent = readArtifactRepairIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
+        repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
     }
     catch (error) {
         return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
     }
-    const schema = getArtifactSchema(spec.family);
-    const structure = inspectArtifactContract(artifactContent, schema);
-    if (!structure.ok) {
-        const repairable = structure.repair !== null && structure.diagnostics.length === 1 && structure.diagnostics[0]?.repairable === true;
-        if (repairable && repairIntent && (repairIntent.state !== 'awaiting-repair'
-            || repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== structure.semanticDigest)) {
-            return reject('REVIEW_PROVENANCE_INVALID', 'a different review repair baseline is already recorded for this artifact', digests);
+    if (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 {
-            ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
-                artifactSha256, semanticDigest: structure.semanticDigest, repairable, operation: structure.repair
-            }),
-            ...(repairable && !repairIntent ? { provenance: {
-                    version: 2, taskId: taskId, family: spec.family, artifact: request.artifact,
-                    state: 'awaiting-repair', baselineSemanticDigest: structure.semanticDigest,
-                    artifactSha256, semanticDigest: structure.semanticDigest,
-                    recoveryOperationId: null, phase: null, authorityDigest: null,
-                    requestId: `review-finalize:${taskId}`, createdAt: Date.now(), updatedAt: Date.now()
-                }, expectedIntent: null } : {})
-        };
-    }
-    if (repairIntent?.state === 'awaiting-repair' && repairIntent.baselineSemanticDigest !== semanticDigest) {
-        return reject('REVIEW_PROVENANCE_INVALID', 'the repaired review artifact semantic digest does not match the recorded repair baseline', digests);
     }
-    if ((repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')
-        && (repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== semanticDigest)) {
-        return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
+    if (repairIntent?.state === 'passed'
+        && (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest)) {
+        repairIntent = undefined;
     }
     if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
         return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
@@ -149,10 +289,68 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     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 {
+                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 {
+            ...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
+                    } } : {})
+            }),
+            ...(recovery ? { recovery } : {})
+        };
+    }
     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 === 'commit-started') {
+        if (repairIntent.finalArtifactSha256 !== finalDigests.artifactSha256 || repairIntent.finalSemanticDigest !== finalDigests.semanticDigest) {
+            return reject('REVIEW_PROVENANCE_INVALID', 'formal review artifact does not match the interrupted recovery journal', finalDigests);
+        }
+        recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, repairIntent);
+    }
+    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 {
+            content: transformed.content,
+            result: {
+                ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
+                status: 'no-op',
+                changed: false,
+                error: null
+            },
+            lockAlreadyHeld: options.lockAlreadyHeld
+        };
+    }
+    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: {
@@ -162,22 +360,64 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
             error: null
         },
-        ...(repairIntent?.state === 'awaiting-repair' ? {
-            provenance: { ...repairIntent, state: 'passed', ...finalDigests },
-            expectedIntent: repairIntent
-        } : {})
+        ...(recovery ? { recovery } : {}),
+        lockAlreadyHeld: options.lockAlreadyHeld
     };
 }
-function commitReviewSummaryProvenance(prepared, repoRoot) {
+function commitReviewSummaryProvenance(prepared, repoRoot, options = {}) {
+    if (prepared.result.status === 'failed' || !prepared.recovery)
+        return prepared.result;
     try {
-        if (prepared.provenance) {
-            writeArtifactRepairIntent(repoRoot, prepared.provenance, { expected: prepared.expectedIntent ?? null });
+        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 === 'passed' || intent.state === 'consumed') {
+            return {
+                ...prepared.result,
+                status: 'no-op',
+                changed: false,
+                artifactSha256: intent.finalArtifactSha256,
+                semanticDigest: intent.finalSemanticDigest,
+                error: null
+            };
         }
-        return prepared.result;
+        else if (intent.state === 'commit-started') {
+            const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+                lockAlreadyHeld: prepared.lockAlreadyHeld,
+                afterPublish: options.afterPublish
+            });
+            committed = reconciled.intent;
+        }
+        else if (intent.state === 'awaiting-preflight-recovery') {
+            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 });
+        }
+        else if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        }
+        if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
+            prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        else if (intent.state === 'full-finalizer-ready') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        if (!committed || committed.state !== 'passed')
+            throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
+        return {
+            ...prepared.result,
+            artifactSha256: committed.finalArtifactSha256,
+            semanticDigest: committed.finalSemanticDigest,
+            error: null
+        };
     }
     catch (error) {
+        if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:'))
+            throw error;
         return { ...prepared.result, status: 'failed', error: {
-                code: 'REVIEW_PROVENANCE_INVALID', message: `cannot record review provenance: ${String(error)}`
+                code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
             } };
     }
 }
@@ -203,37 +443,17 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     const prepared = prepareReviewSummaryCandidate(request, content, options);
     if (request.dryRun)
         return prepared.result;
-    if (prepared.result.status !== 'applied')
-        return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
-    const tempPath = path.join(resolved.taskDir, `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`);
-    try {
-        fileSystem.writeFileSync(tempPath, prepared.content, fileSystem.statModeSync(validated.artifact.path));
-    }
-    catch (error) {
-        cleanupTemp(fileSystem, tempPath);
-        return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, prepared.result.stageStatus);
-    }
-    try {
-        if (fileSystem.readFileSync(validated.artifact.path) !== content) {
-            cleanupTemp(fileSystem, tempPath);
-            return failed(request, 'REVIEW_ARTIFACT_CONFLICT', `${request.artifact} changed during finalization`, resolved.taskId, prepared.result.stageStatus);
-        }
-        fileSystem.renameSync(tempPath, validated.artifact.path);
-    }
-    catch (error) {
-        cleanupTemp(fileSystem, tempPath);
-        return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, prepared.result.stageStatus);
-    }
     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))
@@ -241,5 +461,5 @@ function finalizeReviewSummary(request, options = {}) {
         return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
-export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
+export { finalizeReviewSummary, preflightReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 //# sourceMappingURL=review-finalization.js.map