@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/task/local-artifact-finalization.js

@@ -1,30 +1,56 @@
 import fs from 'node:fs';
-import { inspectDecisionDetailDuplicates, scanVisibleMarkdown } from './decision-details.js';
-import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { inspectDecisionDetailDuplicates } from './decision-details.js';
+import { scanVisibleMarkdown } from './markdown.js';
+import { parseArtifactName } from './artifact-name.js';
+import { hasOpenArtifactRound, parseCodePlanInputReference, validateArtifactPublication, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
 import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.js';
 import { getArtifactSchema } from './artifact-schema.js';
-import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.js';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { beginArtifactRecovery, commitArtifactRecovery, consumeArtifactRecovery, prepareArtifactRecoveryCommit, recordArtifactRecoveryPassed, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
+import { consumeLifecycleRecoveryAttestation, lifecycleRecoveryAttestationDigest, validateLifecycleRecoveryAttestation } from './control-authority.js';
 const LOCAL_ARTIFACT_REQUIRED_SECTIONS = {
     analysis: getArtifactSchema('analysis').sections.map((section) => section.headings.zh),
     plan: getArtifactSchema('plan').sections.map((section) => section.headings.zh),
     code: getArtifactSchema('code').sections.map((section) => section.headings.zh)
 };
-function readLocalArtifactFinalizationIntent(repoRoot, taskId, family, artifact) {
-    return readArtifactRepairIntent(repoRoot, taskId, family, artifact);
+function authorityDigest(authority) {
+    return lifecycleRecoveryAttestationDigest(authority);
 }
-function writeLocalArtifactFinalizationIntent(repoRoot, value) {
-    writeArtifactRepairIntent(repoRoot, value);
+function validFinalizerAuthority(authority, request, taskId) {
+    if (!authority)
+        return false;
+    try {
+        validateLifecycleRecoveryAttestation(authority);
+    }
+    catch {
+        return false;
+    }
+    return authority.version === 1
+        && authority.phase === 'artifact.finalize-local'
+        && authority.taskId === taskId
+        && authority.family === request.family
+        && authority.artifact === request.artifact
+        && authority.round === (parseArtifactName(request.artifact)?.round ?? 0)
+        && authority.requestId.length > 0
+        && authority.operationId.length > 0;
 }
-function consumeLocalArtifactFinalizationIntent(repoRoot, intent) {
+function recoveryInfo(context) {
+    return {
+        recoveryId: context.recoveryId,
+        candidatePath: context.stagingPath,
+        baselineSha256: context.baselineSha256,
+        baselineSemanticDigest: context.baselineSemanticDigest
+    };
+}
+function consumeLocalArtifactFinalizationIntent(repoRoot, intent, options = {}) {
     if (intent.state === 'consumed')
         return intent;
-    if (intent.state !== 'passed')
-        throw new Error('LOCAL_FINALIZATION_INTENT_INVALID: only passed provenance can be consumed');
-    const consumed = { ...intent, state: 'consumed' };
-    writeLocalArtifactFinalizationIntent(repoRoot, consumed);
-    return consumed;
+    const resolved = resolveTaskRef(intent.taskId, { repoRoot });
+    if (!resolved.ok)
+        throw new Error(resolved.message);
+    return consumeArtifactRecovery(recoveryContextFromIntent(repoRoot, resolved.taskDir, intent), options);
 }
 function localDiagnosticCode(code) {
     const map = {
@@ -36,78 +62,56 @@ function localDiagnosticCode(code) {
     return map[code] ?? 'LOCAL_STRUCTURAL_INVALID';
 }
 function localDiagnostic(item) {
-    const code = localDiagnosticCode(item.code);
-    if (!code)
-        return null;
-    return {
-        code,
-        message: item.message,
-        repairable: item.repairable,
-        line: item.line,
-        ...(item.operation?.kind === 'replace-line'
-            ? { from: item.operation.from, to: item.operation.to, operation: 'replace-line' }
-            : {})
-    };
+    return { code: localDiagnosticCode(item.code), message: item.message, line: item.line };
 }
 function isStatusPattern(pattern) {
     return pattern === '^\\$ ';
 }
 function validateLocalArtifact(content, options) {
     const schema = getArtifactSchema(options.family);
-    const patterns = schema.requiredPatterns;
     const diagnostics = [];
     const scanned = scanVisibleMarkdown(content);
     const structure = inspectArtifactStructure(content, schema);
-    for (const item of structure.diagnostics) {
-        const mapped = localDiagnostic(item);
-        if (mapped)
-            diagnostics.push(mapped);
-    }
+    for (const item of structure.diagnostics)
+        diagnostics.push(localDiagnostic(item));
     const statusSection = schema.sections.find((section) => section.id === 'state-check');
     if (statusSection) {
         const statusHeading = scanned.headings.find((heading) => (heading.level === 2 && [statusSection.headings.zh, statusSection.headings.en].some((name) => (heading.text === name || heading.text === `${name}:` || heading.text === `${name}：`))));
         if (statusHeading) {
             const next = scanned.headings.find((candidate) => candidate.start > statusHeading.start && candidate.level <= 2);
             const body = content.slice(statusHeading.end, next?.start ?? content.length);
-            for (const pattern of patterns.filter(isStatusPattern)) {
+            for (const pattern of schema.requiredPatterns.filter(isStatusPattern)) {
                 if (!new RegExp(pattern, 'm').test(body)) {
-                    diagnostics.push({ code: 'LOCAL_STATUS_COMMAND_MISSING', message: `status section '${statusHeading.text}' is missing required command output`, repairable: false, line: content.slice(0, statusHeading.start).split('\n').length });
+                    diagnostics.push({ code: 'LOCAL_STATUS_COMMAND_MISSING', message: `status section '${statusHeading.text}' is missing required command output`, line: content.slice(0, statusHeading.start).split('\n').length });
                 }
             }
         }
     }
     const patternInspection = inspectArtifactPatterns(content, {
         ...schema,
-        requiredPatterns: patterns.filter((item) => !isStatusPattern(item))
+        requiredPatterns: schema.requiredPatterns.filter((item) => !isStatusPattern(item))
     });
-    for (const item of patternInspection.diagnostics) {
-        diagnostics.push({ code: 'LOCAL_REQUIRED_PATTERN_MISSING', message: item.message, repairable: false, line: null });
-    }
+    for (const item of patternInspection.diagnostics)
+        diagnostics.push({ code: 'LOCAL_REQUIRED_PATTERN_MISSING', message: item.message, line: null });
     const decisionDetails = inspectDecisionDetailDuplicates(content);
-    if (!decisionDetails.ok) {
-        diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, repairable: false, line: null });
-    }
+    if (!decisionDetails.ok)
+        diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, line: null });
     if (options.taskContent !== undefined) {
         const expected = expectedQualificationRelations(options.taskContent, options.family);
-        if (!expected.ok) {
-            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, repairable: false, line: null });
-        }
+        if (!expected.ok)
+            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, line: null });
         const qualification = validateQualificationAudit(options.taskContent, content, {
-            family: options.family === 'analysis' ? 'analysis' : options.family === 'plan' ? 'plan' : 'code',
+            family: options.family,
             artifact: options.artifact,
             expectedUpstreamRelations: expected.ok ? expected.relations : undefined
         });
-        if (!qualification.ok) {
-            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, repairable: false, line: null });
-        }
+        if (!qualification.ok)
+            diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, line: null });
     }
-    const repairable = structure.repair !== null && diagnostics.length === 1 && diagnostics[0]?.repairable === true;
-    const semanticDigestValue = canonicalSemanticDigest(content, structure.repair);
     return {
         ok: diagnostics.length === 0,
         family: options.family,
-        semanticDigest: semanticDigestValue,
-        repairable,
+        semanticDigest: canonicalSemanticDigest(content),
         diagnostics
     };
 }
@@ -117,183 +121,179 @@ function failedFinalization(request, error, extra = {}) {
         taskId: null, taskDir: null,
         family: request.family, artifact: request.artifact,
         artifactSha256: null, semanticDigest: null,
-        repairable: false, diagnostics: [], error, ...extra
+        diagnostics: [], error, ...extra
     };
 }
-function provenanceFailure(request, resolved, content, artifactSha256, semanticDigestValue, code, message) {
-    return failedFinalization(request, { code, message }, {
-        taskId: resolved.taskId,
-        taskDir: resolved.taskDir,
-        artifactSha256,
-        semanticDigest: semanticDigestValue,
-        diagnostics: [{ code, message, repairable: false, line: null }]
-    });
+function tupleFor(request, taskId, authority) {
+    const round = parseArtifactName(request.artifact)?.round ?? 0;
+    return {
+        taskId,
+        family: request.family,
+        artifact: request.artifact,
+        round,
+        requestId: authority?.lifecycleRequestId ?? `local-finalize:${taskId}:${request.family}:${round}`,
+        phase: authority?.phase ?? 'artifact.finalize-local',
+        authorityDigest: authority ? authorityDigest(authority) : null
+    };
 }
-function finalizeLocalArtifact(request) {
+function prepareLocalArtifact(request, candidate, authority) {
+    const failed = (code, message, extra = {}) => ({
+        result: failedFinalization(request, { code, message }, extra), content: candidate ?? ''
+    });
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: request.repoRoot });
     if (!resolved.ok)
-        return failedFinalization(request, { code: resolved.code, message: resolved.message });
+        return failed(resolved.code, resolved.message);
     const parsed = parseArtifactName(request.artifact);
-    if (!parsed || parsed.family !== request.family) {
-        return failedFinalization(request, {
-            code: 'ARTIFACT_IDENTITY_INVALID',
-            message: `artifact '${request.artifact}' does not match ${request.family}`
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir });
-    }
-    const validated = validateCompletedArtifact(resolved.taskDir, request.family, request.artifact, parsed.round);
-    if (!validated.ok) {
-        return failedFinalization(request, validated.error, { taskId: resolved.taskId, taskDir: resolved.taskDir });
-    }
-    let content;
-    try {
-        content = fs.readFileSync(validated.artifact.path, 'utf8');
-    }
-    catch (error) {
-        return failedFinalization(request, { code: 'ARTIFACT_NOT_READABLE', message: String(error) }, {
-            taskId: resolved.taskId, taskDir: resolved.taskDir
-        });
+    if (!parsed || parsed.family !== request.family)
+        return failed('ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${request.family}`);
+    if (authority && !validFinalizerAuthority(authority, request, resolved.taskId)) {
+        return failed('LOCAL_EXECUTION_AUTHORITY_INVALID', 'finalizer authority does not match the artifact tuple');
     }
     let taskContent;
+    let content;
+    let recovery;
     try {
         taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        if (request.recoveryId) {
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
+            if (!intent || intent.recoveryOperationId !== request.recoveryId)
+                return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'recovery id does not match the artifact journal');
+            if (!['awaiting-recovery', 'finalize-ready', 'commit-started'].includes(intent.state))
+                return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+            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, request.family, request.artifact, parsed.round);
+            if (!validated.ok)
+                return failed(validated.error.code, validated.error.message);
+            content = candidate ?? fs.readFileSync(validated.artifact.path, 'utf8');
+        }
     }
     catch (error) {
-        return failedFinalization(request, { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) }, {
-            taskId: resolved.taskId, taskDir: resolved.taskDir
-        });
+        return failed('ARTIFACT_NOT_READABLE', String(error));
     }
-    const result = validateLocalArtifact(content, {
-        family: request.family,
-        requiredSections: request.requiredSections,
-        taskContent,
-        artifact: request.artifact
+    if (resolved.state !== 'active' || !hasOpenArtifactRound(taskContent, request.family, parsed.round)) {
+        return failed('ARTIFACT_IDENTITY_INVALID', 'candidate must match one open started round in an active task');
+    }
+    const validation = validateLocalArtifact(content, {
+        family: request.family, requiredSections: request.requiredSections, taskContent, artifact: request.artifact
     });
     const artifactSha256 = sha256Content(content);
-    let intent;
-    try {
-        intent = readLocalArtifactFinalizationIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
-    }
-    catch (error) {
-        return failedFinalization(request, {
-            code: 'LOCAL_FINALIZATION_INTENT_INVALID',
-            message: error instanceof Error ? error.message : String(error)
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
+    const result = failedFinalization(request, {
+        code: 'LOCAL_ARTIFACT_INVALID',
+        message: validation.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+    }, {
+        taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256,
+        semanticDigest: validation.semanticDigest, diagnostics: validation.diagnostics
+    });
+    if (request.recoveryId) {
+        if (!validation.ok)
+            return { result, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        return {
+            result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(recovery) },
+            content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
+        };
     }
-    if (result.repairable) {
-        if (intent && (intent.state !== 'awaiting-repair' || intent.baselineSemanticDigest !== result.semanticDigest)) {
-            return provenanceFailure(request, resolved, content, artifactSha256, result.semanticDigest, 'LOCAL_REPAIR_PROVENANCE_CONFLICT', 'a different local repair baseline is already recorded for this artifact');
-        }
-        if (!intent) {
-            try {
-                writeLocalArtifactFinalizationIntent(resolved.repoRoot, {
-                    version: 1,
-                    taskId: resolved.taskId,
-                    family: request.family,
-                    artifact: request.artifact,
-                    state: 'awaiting-repair',
-                    baselineSemanticDigest: result.semanticDigest,
-                    artifactSha256,
-                    semanticDigest: result.semanticDigest
-                });
-            }
-            catch (error) {
-                return failedFinalization(request, {
-                    code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED',
-                    message: error instanceof Error ? error.message : String(error)
-                }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
-            }
+    const existing = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
+    if (existing?.state === 'passed' || existing?.state === 'consumed') {
+        if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+            return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match its completed recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
         }
+        const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
         return {
-            status: 'failed',
-            changed: false,
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            family: request.family,
-            artifact: request.artifact,
-            artifactSha256,
-            semanticDigest: result.semanticDigest,
-            repairable: true,
-            diagnostics: result.diagnostics,
-            error: {
-                code: 'LOCAL_ARTIFACT_INVALID',
-                message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-            }
+            result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+            content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
         };
     }
-    if (!result.ok) {
-        return {
-            status: 'failed',
-            changed: false,
-            taskId: resolved.taskId,
+    try {
+        if (validation.ok) {
+            const context = recordArtifactRecoveryPassed(tupleFor(request, resolved.taskId, authority), {
+                repoRoot: resolved.repoRoot,
+                taskDir: resolved.taskDir,
+                expectedFinalSha256: artifactSha256,
+                expectedFinalSemanticDigest: validation.semanticDigest,
+                ...(authority ? { recoveryId: authority.operationId } : {}),
+                lockAlreadyHeld: request.lockAlreadyHeld
+            });
+            recovery = context;
+            return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        }
+        const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
+            repoRoot: resolved.repoRoot,
             taskDir: resolved.taskDir,
-            family: request.family,
-            artifact: request.artifact,
-            artifactSha256,
-            semanticDigest: result.semanticDigest,
-            repairable: false,
-            diagnostics: result.diagnostics,
-            error: {
-                code: 'LOCAL_ARTIFACT_INVALID',
-                message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
-            }
+            ...(authority ? { recoveryId: authority.operationId } : {}),
+            lockAlreadyHeld: request.lockAlreadyHeld
+        });
+        recovery = context;
+        return {
+            result: { ...result, recovery: recoveryInfo(context) },
+            content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
         };
     }
-    if (intent?.state === 'awaiting-repair' && intent.baselineSemanticDigest !== result.semanticDigest) {
-        return provenanceFailure(request, resolved, content, artifactSha256, result.semanticDigest, 'LOCAL_REPAIR_BASELINE_MISMATCH', 'the repaired artifact semantic digest does not match the recorded repair baseline');
-    }
-    if ((intent?.state === 'passed' || intent?.state === 'consumed')
-        && (intent.artifactSha256 !== artifactSha256 || intent.semanticDigest !== result.semanticDigest)) {
-        return provenanceFailure(request, resolved, content, artifactSha256, result.semanticDigest, 'LOCAL_REPAIR_PROVENANCE_CONFLICT', 'the artifact changed after its finalization provenance was recorded');
+    catch (error) {
+        return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', String(error)), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
-    if (intent?.state === 'consumed') {
+}
+function commitLocalArtifactProvenance(prepared) {
+    if (!prepared.recovery || !prepared.repoRoot || prepared.result.status === 'failed' && !prepared.result.recovery)
+        return prepared.result;
+    if (prepared.result.status === 'failed')
+        return prepared.result;
+    try {
+        const intent = readArtifactRecoveryIntent(prepared.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,
+                artifactSha256: intent.finalArtifactSha256,
+                semanticDigest: intent.finalSemanticDigest,
+                error: null
+            };
+        }
+        else 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,
             status: 'passed',
-            changed: false,
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            family: request.family,
-            artifact: request.artifact,
-            artifactSha256,
-            semanticDigest: result.semanticDigest,
-            repairable: false,
-            diagnostics: result.diagnostics,
+            artifactSha256: committed.finalArtifactSha256,
+            semanticDigest: committed.finalSemanticDigest,
             error: null
         };
     }
-    try {
-        writeLocalArtifactFinalizationIntent(resolved.repoRoot, {
-            version: 1,
-            taskId: resolved.taskId,
-            family: request.family,
-            artifact: request.artifact,
-            state: 'passed',
-            baselineSemanticDigest: intent?.baselineSemanticDigest ?? null,
-            artifactSha256,
-            semanticDigest: result.semanticDigest
-        });
-    }
     catch (error) {
-        return failedFinalization(request, {
-            code: 'LOCAL_FINALIZATION_INTENT_WRITE_FAILED',
-            message: error instanceof Error ? error.message : String(error)
-        }, { taskId: resolved.taskId, taskDir: resolved.taskDir, artifactSha256, semanticDigest: result.semanticDigest });
+        return { ...prepared.result, status: 'failed', error: {
+                code: 'LOCAL_RECOVERY_COMMIT_FAILED', message: String(error)
+            } };
     }
-    return {
-        status: result.ok ? 'passed' : 'failed',
-        changed: false,
-        taskId: resolved.taskId,
-        taskDir: resolved.taskDir,
-        family: request.family,
-        artifact: request.artifact,
-        artifactSha256,
-        semanticDigest: result.semanticDigest,
-        repairable: result.repairable,
-        diagnostics: result.diagnostics,
-        error: result.ok ? null : {
-            code: 'LOCAL_ARTIFACT_INVALID',
-            message: result.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')
+}
+function finalizeLocalArtifact(request, authority, options = {}) {
+    const prepared = prepareLocalArtifact(request, undefined, authority);
+    const result = commitLocalArtifactProvenance(prepared);
+    if (authority && !options.deferLifecycleRecoveryConsumption && result.status === 'passed') {
+        try {
+            consumeLifecycleRecoveryAttestation(authority);
         }
-    };
+        catch (error) {
+            return { ...result, status: 'failed', error: {
+                    code: 'LOCAL_EXECUTION_AUTHORITY_CONSUME_FAILED',
+                    message: error instanceof Error ? error.message : String(error)
+                } };
+        }
+    }
+    return result;
 }
-export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
+export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, prepareLocalArtifact, commitLocalArtifactProvenance, readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
 //# sourceMappingURL=local-artifact-finalization.js.map

package/dist/lib/task/manual-validation-completion.js

@@ -0,0 +1,26 @@
+import { readManualValidationReceipt } from './manual-validation-receipt.js';
+import { readManualValidationTransaction } from './manual-validation-transaction.js';
+function readManualValidationCompletion(taskDir, expected = {}) {
+    const { receiptDigest: expectedReceiptDigest, ...receiptIdentity } = expected;
+    const receipt = readManualValidationReceipt(taskDir, receiptIdentity);
+    if (!receipt.ok)
+        return receipt;
+    if (expectedReceiptDigest !== undefined && receipt.value.receiptDigest !== expectedReceiptDigest) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_RECEIPT_IDENTITY_MISMATCH', message: 'receipt digest does not match the expected completion' } };
+    }
+    const transaction = readManualValidationTransaction(taskDir, {
+        transactionId: receipt.value.transactionId,
+        taskId: receipt.value.taskId,
+        prNumber: receipt.value.prNumber,
+        prHeadSha: receipt.value.prHeadSha,
+        artifact: receipt.value.artifact
+    });
+    if (!transaction.ok)
+        return transaction;
+    if (transaction.value.committedReceipt !== receipt.value.receiptDigest) {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_TRANSACTION_PHASE_INVALID', message: 'completion transaction is not bound to the canonical receipt' } };
+    }
+    return { ok: true, value: { receipt: receipt.value, transaction: transaction.value } };
+}
+export { readManualValidationCompletion };
+//# sourceMappingURL=manual-validation-completion.js.map

package/dist/lib/task/manual-validation-evidence.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { MANUAL_VALIDATION_SHA40 as SHA40, MANUAL_VALIDATION_TASK_ID as TASK_ID, exactKeys, isRecord, validTimestamp } from './manual-validation-shared.js';
+const MANUAL_VALIDATION_EVIDENCE_SCHEMA = 'agent-infra/branch-only-validation-evidence';
+const MANUAL_VALIDATION_EVIDENCE_VERSION = 1;
+function invalid(message) {
+    return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_INVALID', message } };
+}
+function validateShape(value) {
+    if (!isRecord(value))
+        return invalid('evidence must be a JSON object');
+    const topError = exactKeys(value, ['schema', 'version', 'mode', 'taskId', 'branch', 'commit', 'recoverable', 'source', 'result'], 'evidence');
+    if (topError)
+        return invalid(topError);
+    if (value.schema !== MANUAL_VALIDATION_EVIDENCE_SCHEMA || value.version !== MANUAL_VALIDATION_EVIDENCE_VERSION) {
+        return invalid('evidence schema or version is unsupported');
+    }
+    if (value.mode !== 'task-bound' && value.mode !== 'branch-only')
+        return invalid('mode must be task-bound or branch-only');
+    if (value.taskId !== null && (typeof value.taskId !== 'string' || !TASK_ID.test(value.taskId)))
+        return invalid('taskId must be a TASK identifier or null');
+    if (typeof value.branch !== 'string' || !value.branch.trim() || /[\r\n]/u.test(value.branch))
+        return invalid('branch must be a non-empty single line');
+    if (typeof value.commit !== 'string' || !SHA40.test(value.commit))
+        return invalid('commit must be a 40-character lowercase hexadecimal SHA');
+    if (typeof value.recoverable !== 'boolean')
+        return invalid('recoverable must be boolean');
+    if (value.source !== 'run-manual-validation')
+        return invalid('source is unsupported');
+    if (value.mode === 'branch-only' && (value.taskId !== null || value.recoverable !== false))
+        return invalid('branch-only evidence must be non-recoverable and task-free');
+    if (value.mode === 'task-bound' && (value.taskId === null || value.recoverable !== true))
+        return invalid('task-bound evidence must identify a recoverable task');
+    if (!isRecord(value.result))
+        return invalid('result must be a JSON object');
+    const result = value.result;
+    const resultError = exactKeys(result, ['scope', 'command', 'startedAt', 'completedAt', 'exitCode', 'signal', 'cleanup'], 'result');
+    if (resultError)
+        return invalid(resultError);
+    if (result.scope !== 'snapshot' && result.scope !== 'inplace')
+        return invalid('result.scope is invalid');
+    if (typeof result.command !== 'string' || !result.command || /[\\/\r\n]/u.test(result.command))
+        return invalid('result.command must be a basename');
+    if (!validTimestamp(result.startedAt) || !validTimestamp(result.completedAt) || Date.parse(result.completedAt) < Date.parse(result.startedAt))
+        return invalid('result timestamps are invalid');
+    const exitCode = result.exitCode;
+    if (!Number.isSafeInteger(exitCode) || exitCode < 0)
+        return invalid('result.exitCode must be a non-negative integer');
+    if (result.signal !== null && (typeof result.signal !== 'string' || !result.signal || /[\r\n]/u.test(result.signal)))
+        return invalid('result.signal must be a string or null');
+    if (!['completed', 'pending', 'failed', 'not-created'].includes(result.cleanup))
+        return invalid('result.cleanup is invalid');
+    return { ok: true, value: value };
+}
+function createManualValidationEvidence(input) {
+    const value = {
+        schema: MANUAL_VALIDATION_EVIDENCE_SCHEMA,
+        version: MANUAL_VALIDATION_EVIDENCE_VERSION,
+        mode: input.mode,
+        taskId: input.taskId,
+        branch: input.branch,
+        commit: input.commit,
+        recoverable: input.recoverable,
+        source: 'run-manual-validation',
+        result: {
+            scope: input.scope,
+            command: input.command,
+            startedAt: input.startedAt,
+            completedAt: input.completedAt,
+            exitCode: input.exitCode,
+            signal: input.signal,
+            cleanup: input.cleanup
+        }
+    };
+    const checked = validateShape(value);
+    if (!checked.ok)
+        throw new Error(`${checked.error.code}: ${checked.error.message}`);
+    return checked.value;
+}
+function manualValidationEvidenceSummary(evidence) {
+    return {
+        version: 1,
+        taskId: evidence.taskId,
+        branch: evidence.branch,
+        scope: evidence.result.scope,
+        commit: evidence.commit,
+        command: evidence.result.command,
+        startedAt: evidence.result.startedAt,
+        completedAt: evidence.result.completedAt,
+        exitCode: evidence.result.exitCode,
+        signal: evidence.result.signal,
+        cleanup: evidence.result.cleanup
+    };
+}
+function validateManualValidationEvidence(value, expected) {
+    const shape = validateShape(value);
+    if (!shape.ok)
+        return shape;
+    const evidence = shape.value;
+    if (evidence.result.exitCode !== 0 || evidence.result.signal !== null || evidence.result.cleanup !== 'completed') {
+        return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_UNSUCCESSFUL', message: 'validation must exit 0 without a signal and complete cleanup' } };
+    }
+    if (expected) {
+        if (evidence.taskId !== expected.taskId || evidence.branch !== expected.branch) {
+            return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_IDENTITY_MISMATCH', message: 'evidence task or branch does not match the expected identity' } };
+        }
+        if (expected.commit !== undefined && evidence.commit !== expected.commit) {
+            return { ok: false, error: { code: 'MANUAL_VALIDATION_EVIDENCE_STALE', message: 'evidence commit does not match the current head' } };
+        }
+    }
+    return shape;
+}
+function readManualValidationEvidence(file, expected) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const code = error.code === 'ENOENT'
+            ? 'MANUAL_VALIDATION_EVIDENCE_MISSING'
+            : 'MANUAL_VALIDATION_EVIDENCE_INVALID';
+        return { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } };
+    }
+    return validateManualValidationEvidence(parsed, expected);
+}
+function manualValidationEvidenceDigest(evidence) {
+    return createHash('sha256').update(JSON.stringify(evidence), 'utf8').digest('hex');
+}
+export { MANUAL_VALIDATION_EVIDENCE_SCHEMA, MANUAL_VALIDATION_EVIDENCE_VERSION, createManualValidationEvidence, manualValidationEvidenceSummary, manualValidationEvidenceDigest, readManualValidationEvidence, validateManualValidationEvidence };
+//# sourceMappingURL=manual-validation-evidence.js.map