@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/local-artifact-finalization.ts

@@ -1,16 +1,36 @@
 import fs from 'node:fs';
 
-import { inspectDecisionDetailDuplicates, scanVisibleMarkdown } from './decision-details.ts';
+import { inspectDecisionDetailDuplicates } from './decision-details.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
+import { parseArtifactName } from './artifact-name.ts';
 import {
-  parseArtifactName,
+  hasOpenArtifactRound,
+  parseCodePlanInputReference,
+  validateArtifactPublication,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.ts';
 import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
-import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.ts';
-import type { ArtifactRepairIntent } from './artifact-repair-intent.ts';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
+import type { ArtifactRecoveryIntent } from './artifact-repair-intent.ts';
+import {
+  beginArtifactRecovery,
+  commitArtifactRecovery,
+  consumeArtifactRecovery,
+  prepareArtifactRecoveryCommit,
+  recordArtifactRecoveryPassed,
+  recoveryContextFromIntent,
+  stageArtifactCandidate
+} from './artifact-recovery.ts';
+import type { ArtifactRecoveryContext } from './artifact-recovery.ts';
+import {
+  consumeLifecycleRecoveryAttestation,
+  lifecycleRecoveryAttestationDigest,
+  validateLifecycleRecoveryAttestation
+} from './control-authority.ts';
+import type { LifecycleRecoveryAttestationV1 } from './control-authority.ts';
 
 type LocalArtifactFamily = 'analysis' | 'plan' | 'code';
 
@@ -29,18 +49,14 @@ type LocalArtifactDiagnosticCode =
   | 'LOCAL_REQUIRED_PATTERN_MISSING'
   | 'LOCAL_STRUCTURAL_INVALID'
   | 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION'
-  | 'LOCAL_REPAIR_PROVENANCE_CONFLICT'
-  | 'LOCAL_REPAIR_BASELINE_MISMATCH'
+  | 'LOCAL_RECOVERY_PROVENANCE_CONFLICT'
+  | 'LOCAL_RECOVERY_BASELINE_MISMATCH'
   | 'LOCAL_QUALIFICATION_AUDIT_INVALID';
 
 type LocalArtifactDiagnostic = {
   code: LocalArtifactDiagnosticCode;
   message: string;
-  repairable: boolean;
   line: number | null;
-  from?: string;
-  to?: string;
-  operation?: 'replace-line';
 };
 
 type LocalArtifactValidationOptions = {
@@ -54,7 +70,6 @@ type LocalArtifactValidationResult = {
   ok: boolean;
   family: LocalArtifactFamily;
   semanticDigest: string;
-  repairable: boolean;
   diagnostics: readonly LocalArtifactDiagnostic[];
 };
 
@@ -64,49 +79,76 @@ type LocalArtifactFinalizationRequest = {
   artifact: string;
   repoRoot?: string;
   requiredSections?: readonly string[];
+  recoveryId?: string;
+  lockAlreadyHeld?: boolean;
 };
 
+type LocalArtifactRecoveryInfo = Readonly<{
+  recoveryId: string;
+  candidatePath: string;
+  baselineSha256: string;
+  baselineSemanticDigest: string;
+}>;
+
 type LocalArtifactFinalizationResult = {
   status: 'passed' | 'failed';
-  changed: false;
+  changed: boolean;
   taskId: string | null;
   taskDir: string | null;
   family: LocalArtifactFamily;
   artifact: string;
   artifactSha256: string | null;
   semanticDigest: string | null;
-  repairable: boolean;
   diagnostics: readonly LocalArtifactDiagnostic[];
+  recovery?: LocalArtifactRecoveryInfo;
   error: { code: string; message: string } | null;
 };
 
-type LocalArtifactFinalizationIntent = ArtifactRepairIntent;
+type LocalArtifactFinalizationIntent = ArtifactRecoveryIntent;
 
-function readLocalArtifactFinalizationIntent(
-  repoRoot: string,
-  taskId: string,
-  family: LocalArtifactFamily,
-  artifact: string
-): LocalArtifactFinalizationIntent | null {
-  return readArtifactRepairIntent(repoRoot, taskId, family, artifact);
+function authorityDigest(authority: LifecycleRecoveryAttestationV1): string {
+  return lifecycleRecoveryAttestationDigest(authority);
 }
 
-function writeLocalArtifactFinalizationIntent(repoRoot: string, value: LocalArtifactFinalizationIntent): void {
-  writeArtifactRepairIntent(repoRoot, value);
+function validFinalizerAuthority(
+  authority: LifecycleRecoveryAttestationV1 | undefined,
+  request: LocalArtifactFinalizationRequest,
+  taskId: string
+): boolean {
+  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 recoveryInfo(context: ArtifactRecoveryContext): LocalArtifactRecoveryInfo {
+  return {
+    recoveryId: context.recoveryId,
+    candidatePath: context.stagingPath,
+    baselineSha256: context.baselineSha256,
+    baselineSemanticDigest: context.baselineSemanticDigest
+  };
 }
 
 function consumeLocalArtifactFinalizationIntent(
   repoRoot: string,
-  intent: LocalArtifactFinalizationIntent
+  intent: LocalArtifactFinalizationIntent,
+  options: Readonly<{ lockAlreadyHeld?: boolean }> = {}
 ): LocalArtifactFinalizationIntent {
   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' as const };
-  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: string): LocalArtifactDiagnosticCode | null {
+function localDiagnosticCode(code: string): LocalArtifactDiagnosticCode {
   const map: Record<string, LocalArtifactDiagnosticCode> = {
     ARTIFACT_EMPTY: 'LOCAL_ARTIFACT_EMPTY',
     ARTIFACT_MISSING_SECTION: 'LOCAL_ARTIFACT_MISSING_SECTION',
@@ -116,20 +158,8 @@ function localDiagnosticCode(code: string): LocalArtifactDiagnosticCode | null {
   return map[code] ?? 'LOCAL_STRUCTURAL_INVALID';
 }
 
-function localDiagnostic(
-  item: { code: string; message: string; line: number | null; repairable: boolean; operation?: { kind: string; from: string; to: string } }
-): LocalArtifactDiagnostic | null {
-  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' as const }
-      : {})
-  };
+function localDiagnostic(item: { code: string; message: string; line: number | null }): LocalArtifactDiagnostic {
+  return { code: localDiagnosticCode(item.code), message: item.message, line: item.line };
 }
 
 function isStatusPattern(pattern: string): boolean {
@@ -141,14 +171,10 @@ function validateLocalArtifact(
   options: LocalArtifactValidationOptions
 ): LocalArtifactValidationResult {
   const schema = getArtifactSchema(options.family)!;
-  const patterns = schema.requiredPatterns;
   const diagnostics: LocalArtifactDiagnostic[] = [];
   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) {
@@ -160,9 +186,9 @@ function validateLocalArtifact(
     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 });
         }
       }
     }
@@ -170,40 +196,28 @@ function validateLocalArtifact(
 
   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
   };
 }
@@ -218,204 +232,198 @@ function failedFinalization(
     taskId: null, taskDir: null,
     family: request.family, artifact: request.artifact,
     artifactSha256: null, semanticDigest: null,
-    repairable: false, diagnostics: [], error, ...extra
+    diagnostics: [], error, ...extra
   };
 }
 
-function provenanceFailure(
+type LocalArtifactPreparation = Readonly<{
+  result: LocalArtifactFinalizationResult;
+  content: string;
+  repoRoot?: string;
+  lockAlreadyHeld?: boolean;
+  recovery?: ArtifactRecoveryContext;
+  authority?: LifecycleRecoveryAttestationV1;
+}>;
+
+function tupleFor(
   request: LocalArtifactFinalizationRequest,
-  resolved: { taskId: string; taskDir: string },
-  content: string,
-  artifactSha256: string,
-  semanticDigestValue: string,
-  code: LocalArtifactDiagnosticCode,
-  message: string
-): LocalArtifactFinalizationResult {
-  return failedFinalization(request, { code, message }, {
-    taskId: resolved.taskId,
-    taskDir: resolved.taskDir,
-    artifactSha256,
-    semanticDigest: semanticDigestValue,
-    diagnostics: [{ code, message, repairable: false, line: null }]
-  });
+  taskId: string,
+  authority?: LifecycleRecoveryAttestationV1
+) {
+  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' as const,
+    authorityDigest: authority ? authorityDigest(authority) : null
+  };
 }
 
-function finalizeLocalArtifact(request: LocalArtifactFinalizationRequest): LocalArtifactFinalizationResult {
+function prepareLocalArtifact(
+  request: LocalArtifactFinalizationRequest,
+  candidate?: string,
+  authority?: LifecycleRecoveryAttestationV1
+): LocalArtifactPreparation {
+  const failed = (code: string, message: string, extra: Partial<LocalArtifactFinalizationResult> = {}): LocalArtifactPreparation => ({
+    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 });
+  if (!resolved.ok) 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: string;
-  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: string;
-  try { taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
-  catch (error) {
-    return failedFinalization(request, { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) }, {
-      taskId: resolved.taskId, taskDir: resolved.taskDir
-    });
+  let content: string;
+  let recovery: ArtifactRecoveryContext | undefined;
+  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 failed('ARTIFACT_NOT_READABLE', String(error)); }
+
+  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 result = validateLocalArtifact(content, {
-    family: request.family,
-    requiredSections: request.requiredSections,
-    taskContent,
-    artifact: request.artifact
+  const validation = validateLocalArtifact(content, {
+    family: request.family, requiredSections: request.requiredSections, taskContent, artifact: request.artifact
   });
   const artifactSha256 = sha256Content(content);
-  let intent: LocalArtifactFinalizationIntent | null;
-  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
     };
+  } catch (error) {
+    return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', String(error)), content, repoRoot: resolved.repoRoot, 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'
-    );
-  }
-  if (intent?.state === 'consumed') {
+}
+
+function commitLocalArtifactProvenance(prepared: LocalArtifactPreparation): LocalArtifactFinalizationResult {
+  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: LocalArtifactFinalizationRequest,
+  authority?: LifecycleRecoveryAttestationV1,
+  options: Readonly<{ deferLifecycleRecoveryConsumption?: boolean }> = {}
+): LocalArtifactFinalizationResult {
+  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,
+  prepareLocalArtifact,
+  commitLocalArtifactProvenance,
+  readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent,
   canonicalSemanticDigest as semanticDigest,
   sha256Content,
   validateLocalArtifact
@@ -427,6 +435,8 @@ export type {
   LocalArtifactFinalizationRequest,
   LocalArtifactFinalizationResult,
   LocalArtifactFinalizationIntent,
+  LocalArtifactPreparation,
   LocalArtifactValidationOptions,
-  LocalArtifactValidationResult
+  LocalArtifactValidationResult,
+  LocalArtifactRecoveryInfo
 };