@fitlab-ai/agent-infra 0.9.15 → 0.10.0

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

@@ -0,0 +1,430 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { writeDurableFile } from '../fs/durable-write.js';
+import { readStableFileSync } from '../host-control/secure-fs.js';
+import { parseArtifactName } from './artifact-name.js';
+import { canonicalSemanticDigest, sha256Content } from './artifact-operations.js';
+import { artifactRecoveryRoot, readArtifactRecoveryIntent, writeArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { withTaskExecutionLock } from './task-execution-lock.js';
+const MAX_ARTIFACT_BYTES = 1024 * 1024;
+export class ArtifactRecoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = 'ArtifactRecoveryError';
+        this.code = code;
+    }
+}
+function fail(code, message) {
+    throw new ArtifactRecoveryError(code, message);
+}
+function runLocked(context, owner, callback, lockAlreadyHeld = false) {
+    return lockAlreadyHeld ? callback() : withTaskExecutionLock(context.repoRoot, context.taskId, owner, callback);
+}
+function assertTaskId(taskId) {
+    if (!/^TASK-\d{8}-\d{6}$/u.test(taskId))
+        fail('ARTIFACT_RECOVERY_IDENTITY_INVALID', 'task id is invalid');
+}
+function assertDigest(value, name) {
+    if (!/^[a-f0-9]{64}$/u.test(value))
+        fail('ARTIFACT_RECOVERY_DIGEST_INVALID', `${name} must be a lowercase SHA-256 digest`);
+}
+function assertRecoveryId(value) {
+    if (!/^[a-f0-9-]{16,64}$/u.test(value))
+        fail('ARTIFACT_RECOVERY_IDENTITY_INVALID', 'recovery id is invalid');
+}
+function assertTuple(tuple) {
+    assertTaskId(tuple.taskId);
+    if (path.basename(tuple.artifact) !== tuple.artifact || !tuple.artifact.endsWith('.md')) {
+        fail('ARTIFACT_RECOVERY_TARGET_INVALID', 'artifact must be a canonical top-level Markdown file');
+    }
+    const parsed = parseArtifactName(tuple.artifact);
+    if (!parsed || parsed.family !== tuple.family || parsed.round !== tuple.round) {
+        fail('ARTIFACT_RECOVERY_IDENTITY_INVALID', 'artifact tuple does not match its canonical family and round');
+    }
+    if (!tuple.requestId || /[\r\n]/u.test(tuple.requestId))
+        fail('ARTIFACT_RECOVERY_IDENTITY_INVALID', 'request id is invalid');
+    if (!Number.isSafeInteger(tuple.round) || tuple.round < 1)
+        fail('ARTIFACT_RECOVERY_IDENTITY_INVALID', 'round is invalid');
+}
+function assertDirectory(directory, label) {
+    let stat;
+    try {
+        stat = fs.lstatSync(directory);
+    }
+    catch (error) {
+        fail('ARTIFACT_RECOVERY_PATH_INVALID', `${label} is unavailable: ${String(error)}`);
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        fail('ARTIFACT_RECOVERY_PATH_INVALID', `${label} must be a real directory`);
+}
+function assertRegular(file, label) {
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (error) {
+        fail('ARTIFACT_RECOVERY_PATH_INVALID', `${label} is unavailable: ${String(error)}`);
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        fail('ARTIFACT_RECOVERY_PATH_INVALID', `${label} must be a regular file`);
+    return stat;
+}
+function ensureOwnedDirectoryTree(rootInput, targetInput) {
+    const root = path.resolve(rootInput);
+    const target = path.resolve(targetInput);
+    const relative = path.relative(root, target);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+        fail('ARTIFACT_RECOVERY_PATH_INVALID', 'recovery staging must remain inside the repository');
+    }
+    assertDirectory(root, 'repository root');
+    let current = root;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                fail('ARTIFACT_RECOVERY_PATH_INVALID', `recovery directory is unavailable: ${String(error)}`);
+            }
+            try {
+                fs.mkdirSync(current, { mode: 0o700 });
+            }
+            catch (mkdirError) {
+                fail('ARTIFACT_RECOVERY_PATH_INVALID', `recovery directory could not be created: ${String(mkdirError)}`);
+            }
+            try {
+                stat = fs.lstatSync(current);
+            }
+            catch (lstatError) {
+                fail('ARTIFACT_RECOVERY_PATH_INVALID', `recovery directory could not be verified: ${String(lstatError)}`);
+            }
+        }
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            fail('ARTIFACT_RECOVERY_PATH_INVALID', 'recovery directory must be a real directory');
+        if (process.platform !== 'win32' && typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+            fail('ARTIFACT_RECOVERY_PATH_INVALID', 'recovery directory is not owned by the current user');
+        }
+    }
+}
+function assertRecoveryRoot(context) {
+    ensureOwnedDirectoryTree(context.repoRoot, path.dirname(context.stagingPath));
+}
+function unlinkIfPresent(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+function writeBytes(target, bytes) {
+    if (bytes.length > MAX_ARTIFACT_BYTES)
+        fail('ARTIFACT_RECOVERY_SIZE_LIMIT', 'candidate exceeds the bounded artifact size limit');
+    writeDurableFile(target, bytes.toString('utf8'), { mode: 0o600, replace: true });
+}
+function contextPaths(tuple, options, recoveryId) {
+    const taskDir = path.resolve(options.taskDir);
+    const root = artifactRecoveryRoot(taskDir, recoveryId);
+    return {
+        ...tuple,
+        repoRoot: options.repoRoot,
+        taskDir,
+        recoveryId,
+        stagingId: recoveryId,
+        formalPath: path.join(taskDir, tuple.artifact),
+        stagingPath: path.join(root, 'candidate.md'),
+        baselinePath: path.join(root, 'baseline.md'),
+        finalPath: path.join(root, 'final.md'),
+        baselineSha256: '',
+        baselineSemanticDigest: ''
+    };
+}
+function readIntentForContext(context) {
+    const intent = readArtifactRecoveryIntent(context.repoRoot, context.taskId, context.family, context.artifact);
+    if (!intent)
+        fail('ARTIFACT_RECOVERY_INTENT_MISSING', 'recovery journal is missing');
+    if (intent.recoveryOperationId !== context.recoveryId
+        || intent.stagingId !== context.stagingId
+        || intent.round !== context.round
+        || intent.requestId !== context.requestId) {
+        fail('ARTIFACT_RECOVERY_IDENTITY_INVALID', 'recovery context does not match the journal');
+    }
+    return intent;
+}
+function contextWithIntent(context, intent) {
+    return {
+        ...context,
+        phase: intent.phase,
+        authorityDigest: intent.authorityDigest,
+        baselineSha256: intent.baselineSha256,
+        baselineSemanticDigest: intent.baselineSemanticDigest
+    };
+}
+function createIntent(context, now) {
+    return {
+        version: 3,
+        taskId: context.taskId,
+        family: context.family,
+        artifact: context.artifact,
+        round: context.round,
+        state: 'awaiting-recovery',
+        baselineSha256: context.baselineSha256,
+        baselineSemanticDigest: context.baselineSemanticDigest,
+        stagingId: context.stagingId,
+        candidateSha256: context.baselineSha256,
+        finalArtifactSha256: null,
+        finalSemanticDigest: null,
+        recoveryOperationId: context.recoveryId,
+        phase: context.phase ?? null,
+        authorityDigest: context.authorityDigest ?? null,
+        requestId: context.requestId,
+        errorCode: null,
+        errorMessage: null,
+        createdAt: now,
+        updatedAt: now
+    };
+}
+export function beginArtifactRecovery(tuple, baselineBytes, options) {
+    assertTuple(tuple);
+    assertDirectory(options.taskDir, 'task directory');
+    const context = contextPaths(tuple, options, options.recoveryId ?? randomUUID());
+    assertRecoveryId(context.recoveryId);
+    const targetStat = assertRegular(context.formalPath, 'formal artifact');
+    const rootParent = path.dirname(context.stagingPath);
+    ensureOwnedDirectoryTree(options.repoRoot, rootParent);
+    const stagingStat = fs.lstatSync(rootParent);
+    if (stagingStat.dev !== targetStat.dev)
+        fail('ARTIFACT_RECOVERY_PATH_INVALID', 'recovery staging must share the formal artifact file system');
+    const baselineSha256 = sha256Content(baselineBytes.toString('utf8'));
+    const prepared = { ...context, baselineSha256, baselineSemanticDigest: canonicalSemanticDigest(baselineBytes.toString('utf8')) };
+    return runLocked(prepared, 'task-artifact.recovery.begin', () => {
+        assertRecoveryRoot(prepared);
+        const current = readStableFileSync(prepared.formalPath, { maxBytes: MAX_ARTIFACT_BYTES }).bytes;
+        if (sha256Content(current.toString('utf8')) !== baselineSha256 || !current.equals(baselineBytes)) {
+            fail('ARTIFACT_RECOVERY_BASELINE_MISMATCH', 'formal artifact does not match the recovery baseline');
+        }
+        const existing = readArtifactRecoveryIntent(prepared.repoRoot, prepared.taskId, prepared.family, prepared.artifact);
+        if (existing && existing.state !== 'aborted' && existing.state !== 'consumed') {
+            fail('ARTIFACT_RECOVERY_CONFLICT', 'an active recovery journal already exists for this artifact');
+        }
+        writeBytes(prepared.baselinePath, baselineBytes);
+        writeBytes(prepared.stagingPath, baselineBytes);
+        writeArtifactRecoveryIntent(prepared.repoRoot, createIntent(prepared, Date.now()), { expected: existing });
+        return prepared;
+    }, options.lockAlreadyHeld);
+}
+export function recordArtifactRecoveryPassed(tuple, options) {
+    assertTuple(tuple);
+    assertDirectory(options.taskDir, 'task directory');
+    const context = contextPaths(tuple, options, options.recoveryId ?? randomUUID());
+    assertRecoveryId(context.recoveryId);
+    assertRegular(context.formalPath, 'formal artifact');
+    return runLocked(context, 'task-artifact.recovery.record-passed', () => {
+        const current = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        const prepared = {
+            ...context,
+            baselineSha256: current.sha256,
+            baselineSemanticDigest: canonicalSemanticDigest(current.bytes.toString('utf8'))
+        };
+        if ((options.expectedFinalSha256 !== undefined) !== (options.expectedFinalSemanticDigest !== undefined)) {
+            fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'fast-path provenance requires both finalizer digests');
+        }
+        if (options.expectedFinalSha256 !== undefined && options.expectedFinalSemanticDigest !== undefined
+            && (current.sha256 !== options.expectedFinalSha256 || prepared.baselineSemanticDigest !== options.expectedFinalSemanticDigest)) {
+            fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'formal artifact does not match the finalizer digests');
+        }
+        const existing = readArtifactRecoveryIntent(prepared.repoRoot, prepared.taskId, prepared.family, prepared.artifact);
+        if (existing && (existing.state === 'passed' || existing.state === 'consumed')
+            && existing.finalArtifactSha256 === prepared.baselineSha256
+            && existing.finalSemanticDigest === prepared.baselineSemanticDigest) {
+            return recoveryContextFromIntent(prepared.repoRoot, prepared.taskDir, existing);
+        }
+        if (existing && existing.state !== 'aborted') {
+            fail('ARTIFACT_RECOVERY_CONFLICT', 'an active recovery journal already exists for this artifact');
+        }
+        const now = Date.now();
+        const next = {
+            ...createIntent(prepared, now),
+            state: 'passed',
+            candidateSha256: prepared.baselineSha256,
+            finalArtifactSha256: prepared.baselineSha256,
+            finalSemanticDigest: prepared.baselineSemanticDigest
+        };
+        writeArtifactRecoveryIntent(prepared.repoRoot, next, { expected: existing });
+        return prepared;
+    }, options.lockAlreadyHeld);
+}
+export function stageArtifactCandidate(context, candidateBytes, options = {}) {
+    return runLocked(context, 'task-artifact.recovery.stage', () => {
+        assertRecoveryRoot(context);
+        const intent = readIntentForContext(context);
+        if (intent.state !== 'awaiting-recovery')
+            fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot stage a candidate from '${intent.state}'`);
+        const candidateSha256 = sha256Content(candidateBytes.toString('utf8'));
+        const semanticDigest = canonicalSemanticDigest(candidateBytes.toString('utf8'));
+        writeBytes(context.stagingPath, candidateBytes);
+        const next = { ...intent, candidateSha256, updatedAt: Date.now() };
+        writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
+        return { recoveryId: context.recoveryId, candidateSha256, semanticDigest, path: context.stagingPath };
+    }, options.lockAlreadyHeld);
+}
+export function prepareArtifactRecoveryCommit(context, finalSha256, finalSemanticDigest, options = {}) {
+    assertDigest(finalSha256, 'final artifact digest');
+    assertDigest(finalSemanticDigest, 'final semantic digest');
+    return runLocked(context, 'task-artifact.recovery.prepare', () => {
+        const intent = readIntentForContext(context);
+        if (intent.state !== 'awaiting-recovery')
+            fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot prepare a commit from '${intent.state}'`);
+        assertRecoveryRoot(context);
+        const staged = readStableFileSync(context.stagingPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (staged.sha256 !== finalSha256 || canonicalSemanticDigest(staged.bytes.toString('utf8')) !== finalSemanticDigest) {
+            fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'staged candidate does not match the finalizer digest');
+        }
+        writeBytes(context.finalPath, staged.bytes);
+        fs.chmodSync(context.finalPath, 0o400);
+        const sealed = readStableFileSync(context.finalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (sealed.sha256 !== finalSha256 || canonicalSemanticDigest(sealed.bytes.toString('utf8')) !== finalSemanticDigest) {
+            fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'sealed candidate does not match the finalizer digest');
+        }
+        const next = {
+            ...intent,
+            state: 'finalize-ready',
+            candidateSha256: staged.sha256,
+            finalArtifactSha256: finalSha256,
+            finalSemanticDigest,
+            errorCode: null,
+            errorMessage: null,
+            updatedAt: Date.now()
+        };
+        writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
+        return next;
+    }, options.lockAlreadyHeld);
+}
+function markCommitStarted(context, intent) {
+    if (intent.state === 'commit-started')
+        return intent;
+    if (intent.state !== 'finalize-ready')
+        fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot commit from '${intent.state}'`);
+    const next = { ...intent, state: 'commit-started', updatedAt: Date.now() };
+    writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
+    return next;
+}
+export function commitArtifactRecovery(context, options = {}) {
+    return runLocked(context, 'task-artifact.recovery.commit', () => {
+        let intent = readIntentForContext(context);
+        if (intent.state === 'passed' || intent.state === 'consumed')
+            return intent;
+        assertRecoveryRoot(context);
+        intent = markCommitStarted(context, intent);
+        const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (target.sha256 === intent.finalArtifactSha256) {
+            const passed = { ...intent, state: 'passed', updatedAt: Date.now() };
+            writeArtifactRecoveryIntent(context.repoRoot, passed, { expected: intent });
+            return passed;
+        }
+        if (target.sha256 !== intent.baselineSha256)
+            fail('ARTIFACT_RECOVERY_CONFLICT', 'formal artifact changed outside the recovery baseline');
+        const sealed = readStableFileSync(context.finalPath, {
+            maxBytes: MAX_ARTIFACT_BYTES,
+            expectedSha256: intent.finalArtifactSha256
+        });
+        if (canonicalSemanticDigest(sealed.bytes.toString('utf8')) !== intent.finalSemanticDigest) {
+            fail('ARTIFACT_RECOVERY_CONFLICT', 'sealed artifact does not match the staged final semantic digest');
+        }
+        // Publish the bytes that were validated above. The sealed path is only a
+        // recovery input; renaming it directly would reopen a same-uid path swap
+        // between validation and publication.
+        const publishPath = path.join(path.dirname(context.finalPath), 'publish.md');
+        unlinkIfPresent(publishPath);
+        writeBytes(publishPath, sealed.bytes);
+        fs.chmodSync(publishPath, 0o400);
+        const publish = readStableFileSync(publishPath, {
+            maxBytes: MAX_ARTIFACT_BYTES,
+            expectedSha256: intent.finalArtifactSha256
+        });
+        if (canonicalSemanticDigest(publish.bytes.toString('utf8')) !== intent.finalSemanticDigest) {
+            fail('ARTIFACT_RECOVERY_CONFLICT', 'publish artifact does not match the staged final semantic digest');
+        }
+        fs.renameSync(publishPath, context.formalPath);
+        const published = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (published.sha256 !== intent.finalArtifactSha256)
+            fail('ARTIFACT_RECOVERY_CONFLICT', 'formal artifact does not match the staged final digest');
+        const passed = { ...intent, state: 'passed', updatedAt: Date.now() };
+        writeArtifactRecoveryIntent(context.repoRoot, passed, { expected: intent });
+        return passed;
+    }, options.lockAlreadyHeld);
+}
+export function abortArtifactRecovery(context, code, message, options = {}) {
+    return runLocked(context, 'task-artifact.recovery.abort', () => {
+        const intent = readIntentForContext(context);
+        assertRegular(context.baselinePath, 'baseline backup');
+        const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (target.sha256 !== intent.baselineSha256)
+            fs.renameSync(context.baselinePath, context.formalPath);
+        const restored = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (restored.sha256 !== intent.baselineSha256)
+            fail('ARTIFACT_RECOVERY_INDETERMINATE', 'baseline restore could not be verified');
+        const aborted = {
+            ...intent,
+            state: 'aborted',
+            errorCode: code,
+            errorMessage: message,
+            updatedAt: Date.now()
+        };
+        writeArtifactRecoveryIntent(context.repoRoot, aborted, { expected: intent });
+        return aborted;
+    }, options.lockAlreadyHeld);
+}
+export function reconcileArtifactRecovery(context, options = {}) {
+    return runLocked(context, 'task-artifact.recovery.reconcile', () => {
+        const intent = readIntentForContext(context);
+        if (intent.state !== 'commit-started')
+            return { status: intent.state, intent };
+        const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+        if (target.sha256 === intent.finalArtifactSha256 && (options.validateFinal?.() ?? true)) {
+            const passed = { ...intent, state: 'passed', updatedAt: Date.now() };
+            writeArtifactRecoveryIntent(context.repoRoot, passed, { expected: intent });
+            return { status: 'passed', intent: passed };
+        }
+        if (target.sha256 === intent.baselineSha256) {
+            const retried = commitArtifactRecovery(context, { lockAlreadyHeld: true });
+            return { status: retried.state, intent: retried };
+        }
+        if (options.restoreBaseline) {
+            const aborted = abortArtifactRecovery(context, 'ARTIFACT_RECOVERY_CONTEXT_INVALID', 'formal target is not a verifiable baseline or final candidate', { lockAlreadyHeld: true });
+            return { status: 'aborted', intent: aborted };
+        }
+        return { status: 'indeterminate', intent };
+    }, options.lockAlreadyHeld);
+}
+export function consumeArtifactRecovery(context, options = {}) {
+    return runLocked(context, 'task-artifact.recovery.consume', () => {
+        const intent = readIntentForContext(context);
+        if (intent.state === 'consumed')
+            return intent;
+        if (intent.state !== 'passed')
+            fail('ARTIFACT_RECOVERY_STATE_INVALID', `only passed recovery can be consumed, got '${intent.state}'`);
+        const consumed = { ...intent, state: 'consumed', updatedAt: Date.now() };
+        writeArtifactRecoveryIntent(context.repoRoot, consumed, { expected: intent });
+        return consumed;
+    }, options.lockAlreadyHeld);
+}
+export function recoveryContextFromIntent(repoRoot, taskDir, intent) {
+    const context = contextPaths({
+        taskId: intent.taskId,
+        family: intent.family,
+        artifact: intent.artifact,
+        round: intent.round,
+        requestId: intent.requestId,
+        phase: intent.phase,
+        authorityDigest: intent.authorityDigest
+    }, { repoRoot, taskDir, recoveryId: intent.recoveryOperationId }, intent.recoveryOperationId);
+    return contextWithIntent(context, intent);
+}
+export { canonicalSemanticDigest, readArtifactRecoveryIntent, sha256Content };
+//# sourceMappingURL=artifact-recovery.js.map

package/dist/lib/task/artifact-repair-intent.js

@@ -1,11 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-function intentRoot(repoRoot) {
+import { parseArtifactName } from './artifact-name.js';
+export function artifactRecoveryIntentRoot(repoRoot) {
     return path.join(repoRoot, '.agents', 'workspace', '.local-artifact-finalization-intents');
 }
+export function artifactRecoveryRoot(taskDir, stagingId) {
+    return path.join(taskDir, '.local-artifact-recovery', stagingId);
+}
 function intentPath(repoRoot, taskId, family, artifact) {
-    return path.join(intentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
+    return path.join(artifactRecoveryIntentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
 }
 function validDigest(value) {
     return typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
@@ -13,35 +17,65 @@ function validDigest(value) {
 function validTaskId(value) {
     return typeof value === 'string' && /^TASK-\d{8}-\d{6}$/u.test(value);
 }
+function validToken(value) {
+    return typeof value === 'string' && value.length > 0 && !/[\r\n]/u.test(value);
+}
+function validRecoveryId(value) {
+    return typeof value === 'string' && /^[a-f0-9-]{16,64}$/u.test(value);
+}
+function validArtifact(value, family, round) {
+    if (typeof value !== 'string' || path.basename(value) !== value || !value.endsWith('.md'))
+        return false;
+    const parsed = parseArtifactName(value);
+    return Boolean(parsed && parsed.family === family && parsed.round === round);
+}
 function exactKeys(value, keys) {
     return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
 }
-export function isArtifactRepairIntent(value) {
+export function isArtifactRecoveryIntent(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
     const intent = value;
     return exactKeys(intent, [
-        'artifact', 'artifactSha256', 'authorityDigest', 'baselineSemanticDigest', 'createdAt',
-        'family', 'phase', 'recoveryOperationId', 'requestId', 'semanticDigest', 'state',
-        'taskId', 'updatedAt', 'version'
+        'artifact', 'authorityDigest', 'baselineSemanticDigest', 'baselineSha256', 'candidateSha256',
+        'createdAt', 'errorCode', 'errorMessage', 'family', 'finalArtifactSha256', 'finalSemanticDigest',
+        'phase', 'recoveryOperationId', 'requestId', 'round', 'stagingId', 'state', 'taskId', 'updatedAt',
+        'version'
     ])
-        && intent.version === 2
+        && intent.version === 3
         && validTaskId(intent.taskId)
         && typeof intent.family === 'string'
         && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
-        && typeof intent.artifact === 'string' && intent.artifact.length > 0
-        && ['awaiting-repair', 'finalize-ready', 'commit-started', 'passed', 'consumed'].includes(String(intent.state))
-        && (intent.baselineSemanticDigest === null || validDigest(intent.baselineSemanticDigest))
-        && validDigest(intent.artifactSha256)
-        && validDigest(intent.semanticDigest)
-        && (intent.recoveryOperationId === null || (typeof intent.recoveryOperationId === 'string' && /^[a-f0-9-]{16,64}$/u.test(intent.recoveryOperationId)))
+        && Number.isSafeInteger(intent.round) && intent.round > 0
+        && validArtifact(intent.artifact, intent.family, intent.round)
+        && ['awaiting-recovery', 'finalize-ready', 'commit-started', 'passed', 'consumed', 'aborted'].includes(String(intent.state))
+        && validDigest(intent.baselineSha256)
+        && validDigest(intent.baselineSemanticDigest)
+        && validRecoveryId(intent.stagingId)
+        && (intent.candidateSha256 === null || validDigest(intent.candidateSha256))
+        && (intent.finalArtifactSha256 === null || validDigest(intent.finalArtifactSha256))
+        && (intent.finalSemanticDigest === null || validDigest(intent.finalSemanticDigest))
+        && validRecoveryId(intent.recoveryOperationId)
+        && intent.stagingId === intent.recoveryOperationId
         && (intent.phase === null || ['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(String(intent.phase)))
         && (intent.authorityDigest === null || validDigest(intent.authorityDigest))
-        && typeof intent.requestId === 'string' && intent.requestId.length > 0 && !/[\r\n]/u.test(intent.requestId)
-        && Number.isSafeInteger(intent.createdAt) && Number.isSafeInteger(intent.updatedAt)
-        && (intent.state === 'awaiting-repair' ? intent.baselineSemanticDigest === intent.semanticDigest : true);
+        && validToken(intent.requestId)
+        && (intent.errorCode === null || validToken(intent.errorCode))
+        && (intent.errorMessage === null || validToken(intent.errorMessage))
+        && Number.isSafeInteger(intent.createdAt)
+        && Number.isSafeInteger(intent.updatedAt)
+        && (intent.state === 'awaiting-recovery'
+            ? intent.finalArtifactSha256 === null && intent.finalSemanticDigest === null
+            : true)
+        && (intent.state === 'finalize-ready' || intent.state === 'commit-started' || intent.state === 'passed' || intent.state === 'consumed'
+            ? validDigest(intent.candidateSha256) && validDigest(intent.finalArtifactSha256) && validDigest(intent.finalSemanticDigest)
+            : true)
+        && (intent.state === 'aborted' ? intent.errorCode !== null && intent.errorMessage !== null : true);
 }
-function readArtifactRepairIntent(repoRoot, taskId, family, artifact) {
+export function readArtifactRecoveryIntent(repoRoot, taskId, family, artifact) {
+    if (!validTaskId(taskId) || !validArtifact(artifact, family, parseArtifactName(artifact)?.round)) {
+        throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal identity is invalid');
+    }
     const target = intentPath(repoRoot, taskId, family, artifact);
     if (!fs.existsSync(target))
         return null;
@@ -50,19 +84,20 @@ function readArtifactRepairIntent(repoRoot, taskId, family, artifact) {
         value = JSON.parse(fs.readFileSync(target, 'utf8'));
     }
     catch (error) {
-        throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`);
+        throw new Error(`ARTIFACT_RECOVERY_INTENT_INVALID: ${String(error)}`);
     }
-    if (!isArtifactRepairIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
-        throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+    if (!isArtifactRecoveryIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
+        throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
     }
     return value;
 }
-export function writeArtifactRepairIntent(repoRoot, value, options = {}) {
-    if (!isArtifactRepairIntent(value))
-        throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
-    const directory = intentRoot(repoRoot);
+export function writeArtifactRecoveryIntent(repoRoot, value, options = {}) {
+    if (!isArtifactRecoveryIntent(value))
+        throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
+    const intent = value;
+    const directory = artifactRecoveryIntentRoot(repoRoot);
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-    const target = intentPath(repoRoot, value.taskId, value.family, value.artifact);
+    const target = intentPath(repoRoot, intent.taskId, intent.family, intent.artifact);
     const lock = `${target}.lock`;
     let descriptor;
     try {
@@ -70,19 +105,19 @@ export function writeArtifactRepairIntent(repoRoot, value, options = {}) {
     }
     catch (error) {
         if (error.code === 'EEXIST') {
-            throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: another provenance writer owns the intent');
+            throw new Error('ARTIFACT_RECOVERY_INTENT_CONFLICT: another journal writer owns the intent');
         }
         throw error;
     }
     try {
         const current = fs.existsSync(target)
-            ? readArtifactRepairIntent(repoRoot, value.taskId, value.family, value.artifact)
+            ? readArtifactRecoveryIntent(repoRoot, intent.taskId, intent.family, intent.artifact)
             : null;
         if (!isDeepStrictEqual(current, options.expected ?? null)) {
-            throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: repair provenance changed during finalization');
+            throw new Error('ARTIFACT_RECOVERY_INTENT_CONFLICT: recovery journal changed during finalization');
         }
         const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-        fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        fs.writeFileSync(temporary, `${JSON.stringify(intent)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
         try {
             fs.renameSync(temporary, target);
         }
@@ -90,7 +125,7 @@ export function writeArtifactRepairIntent(repoRoot, value, options = {}) {
             try {
                 fs.unlinkSync(temporary);
             }
-            catch { /* preserve primary error */ }
+            catch { /* preserve the primary error */ }
             throw error;
         }
     }
@@ -102,11 +137,10 @@ export function writeArtifactRepairIntent(repoRoot, value, options = {}) {
         catch { /* preserve the primary result */ }
     }
 }
-export function findArtifactRepairIntentsByOperation(repoRoot, operationId) {
-    if (!operationId || /[\r\n]/u.test(operationId)) {
-        throw new Error('ARTIFACT_REPAIR_OPERATION_INVALID: recovery operation id is invalid');
-    }
-    const directory = intentRoot(repoRoot);
+export function findArtifactRecoveryIntentsByOperation(repoRoot, operationId) {
+    if (!validToken(operationId))
+        throw new Error('ARTIFACT_RECOVERY_OPERATION_INVALID: recovery operation id is invalid');
+    const directory = artifactRecoveryIntentRoot(repoRoot);
     if (!fs.existsSync(directory))
         return Object.freeze([]);
     return Object.freeze(fs.readdirSync(directory)
@@ -118,13 +152,13 @@ export function findArtifactRepairIntentsByOperation(repoRoot, operationId) {
             value = JSON.parse(fs.readFileSync(target, 'utf8'));
         }
         catch (error) {
-            throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`);
+            throw new Error(`ARTIFACT_RECOVERY_INTENT_INVALID: ${String(error)}`);
         }
-        if (!isArtifactRepairIntent(value))
-            throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+        if (!isArtifactRecoveryIntent(value))
+            throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
         return value;
     })
         .filter((value) => value.recoveryOperationId === operationId));
 }
-export { readArtifactRepairIntent };
+export { intentPath as artifactRecoveryIntentPath };
 //# sourceMappingURL=artifact-repair-intent.js.map