@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/core/recovery/checkpoint.js

@@ -0,0 +1,260 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { canonicalPath } from '../path-utils.js';
+import { artifactRepoRoot, atomicWriteJson, checkpointDir, checkpointIds, checkpointIdsForRepo, checkpointsRoot, cleanupOrphanedStaging, directorySize, fsyncPath, markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, RECOVERY_CHECKPOINT_CORRUPT, readRecoveryArtifact, writeRecoveryState, } from './artifact-store.js';
+import { matchRecoverySide, reconcileRecoveryCheckpoint } from './reconcile.js';
+import { currentRecoveryResourceIdentity } from './resource-identity.js';
+import { RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, recoveryRestoreBinding, restoreRecoveryCheckpoint, } from './restore.js';
+import { assertRecoverySafeTarget, captureRecoverySnapshot, withoutRecoveryBlob, } from './snapshot-node.js';
+function recoveryProofProbeSignals(backend) {
+    if (backend === 'file_checkpoint') {
+        return ['dirty_git_worktree', 'file_checkpoint', 'observed_repo_local_diff'];
+    }
+    return ['clean_git_worktree', 'observed_repo_local_diff'];
+}
+export const RECOVERY_CHECKPOINT_QUOTA = 'recovery_checkpoint_quota_exceeded';
+async function garbageCollect(stateDir, config, repoRoot) {
+    const artifacts = [];
+    for (const id of await checkpointIdsForRepo(stateDir, repoRoot)) {
+        try {
+            const loaded = await readRecoveryArtifact(stateDir, id);
+            artifacts.push({
+                id,
+                state: loaded.state.state,
+                updatedAt: Date.parse(loaded.state.updatedAt),
+            });
+        }
+        catch {
+            // Corrupt checkpoints are retained for inspection.
+        }
+    }
+    const now = Date.now();
+    const removable = artifacts
+        .filter((entry) => entry.state === 'applied' || entry.state === 'restored')
+        .sort((left, right) => left.updatedAt - right.updatedAt);
+    for (const entry of removable) {
+        const retentionHours = entry.state === 'restored' ? config.restoredRetentionHours : config.appliedRetentionHours;
+        const expired = now - entry.updatedAt >= retentionHours * 60 * 60 * 1000;
+        if (!expired)
+            continue;
+        await rm(checkpointDir(stateDir, entry.id), { recursive: true, force: true });
+    }
+}
+export async function prepareRecoveryCheckpoint(params) {
+    const backend = params.backend ?? 'git_worktree';
+    await mkdir(checkpointsRoot(params.stateDir), { recursive: true, mode: 0o700 });
+    await cleanupOrphanedStaging(params.stateDir);
+    await garbageCollect(params.stateDir, params.config, params.repoRoot);
+    const existing = await checkpointIdsForRepo(params.stateDir, params.repoRoot);
+    if (existing.length >= params.config.maxCheckpoints) {
+        throw new Error(RECOVERY_CHECKPOINT_QUOTA);
+    }
+    const checkpointId = `cp_${randomUUID().replaceAll('-', '').slice(0, 24)}`;
+    const temporary = path.join(checkpointsRoot(params.stateDir), `.tmp-${checkpointId}`);
+    const finalDir = checkpointDir(params.stateDir, checkpointId);
+    await mkdir(temporary, { recursive: true, mode: 0o700 });
+    await atomicWriteJson(path.join(temporary, 'owner.json'), {
+        version: 1,
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        repoRoot: canonicalPath(params.repoRoot),
+    });
+    await mkdir(path.join(temporary, 'blobs'), { recursive: true, mode: 0o700 });
+    try {
+        const entries = [];
+        const protectedRoots = (params.protectedRoots ?? []).map(canonicalPath);
+        for (const change of [...params.changes].sort((left, right) => left.relativePath.localeCompare(right.relativePath))) {
+            const target = await assertRecoverySafeTarget(params.repoRoot, change.relativePath);
+            if (protectedRoots.some((root) => {
+                const relative = path.relative(root, target);
+                return (relative === '' ||
+                    (relative !== '..' &&
+                        !relative.startsWith(`..${path.sep}`) &&
+                        !path.isAbsolute(relative)));
+            })) {
+                throw new Error('recovery_protected_path');
+            }
+            const baseline = await assertRecoverySafeTarget(params.baselinePath ?? params.repoRoot, change.relativePath);
+            const source = await assertRecoverySafeTarget(params.worktreePath, change.relativePath);
+            entries.push({
+                path: change.relativePath,
+                before: await captureRecoverySnapshot(baseline, {
+                    blobDir: path.join(temporary, 'blobs'),
+                }),
+                after: withoutRecoveryBlob(await captureRecoverySnapshot(source)),
+            });
+        }
+        const createdAt = new Date().toISOString();
+        const proof = {
+            version: 1,
+            backend,
+            inputFingerprint: params.commandFingerprint,
+            resourceScope: canonicalPath(params.repoRoot),
+            baseStateHash: hashValue(canonicalStringify(entries.map((entry) => entry.before))),
+            effectClosure: 'repo_local_fs_observed',
+            issuedAt: createdAt,
+            expiresAt: new Date(Date.now() + params.config.appliedRetentionHours * 60 * 60 * 1000).toISOString(),
+            probeSignals: recoveryProofProbeSignals(backend),
+        };
+        const manifest = {
+            version: 2,
+            checkpointId,
+            backend,
+            repoRoot: canonicalPath(params.repoRoot),
+            resourceKind: 'git_repository',
+            repoIdentity: await currentRecoveryResourceIdentity(params.repoRoot, 'git_repository'),
+            commandFingerprint: params.commandFingerprint,
+            createdAt,
+            expiresAt: proof.expiresAt,
+            proof,
+            entries,
+        };
+        const manifestHash = hashValue(canonicalStringify(manifest));
+        await atomicWriteJson(path.join(temporary, 'manifest.json'), manifest);
+        await writeRecoveryState(temporary, 'prepared', manifestHash);
+        await fsyncPath(temporary);
+        const projectedBytes = await recoveryCheckpointStorageBytes(params.stateDir, params.repoRoot);
+        if (projectedBytes > params.config.maxBytes)
+            throw new Error(RECOVERY_CHECKPOINT_QUOTA);
+        await rename(temporary, finalDir);
+        await fsyncPath(checkpointsRoot(params.stateDir));
+        return {
+            checkpointId,
+            manifest,
+            manifestHash,
+            proofHash: hashValue(canonicalStringify(proof)),
+        };
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function discardPreparedRecoveryCheckpoint(stateDir, checkpointId) {
+    const state = await reconcileRecoveryCheckpoint(stateDir, checkpointId);
+    if (state !== 'prepared')
+        return false;
+    const loaded = await readRecoveryArtifact(stateDir, checkpointId);
+    if (!(await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'before'))) {
+        return false;
+    }
+    await rm(loaded.artifactDir, { recursive: true, force: true });
+    return true;
+}
+export async function listRecoveryCheckpoints(stateDir, repoRoot) {
+    await cleanupOrphanedStaging(stateDir);
+    const summaries = [];
+    for (const id of await checkpointIds(stateDir)) {
+        if (repoRoot) {
+            let rootFromArtifact;
+            try {
+                rootFromArtifact = (await readRecoveryArtifact(stateDir, id)).manifest.repoRoot;
+            }
+            catch {
+                try {
+                    const raw = JSON.parse(await readFile(path.join(checkpointDir(stateDir, id), 'manifest.json'), 'utf8'));
+                    rootFromArtifact =
+                        typeof raw.repoRoot === 'string' && raw.repoRoot ? raw.repoRoot : undefined;
+                }
+                catch {
+                    rootFromArtifact = undefined;
+                }
+            }
+            if (!rootFromArtifact || canonicalPath(rootFromArtifact) !== canonicalPath(repoRoot))
+                continue;
+        }
+        const state = await reconcileRecoveryCheckpoint(stateDir, id);
+        try {
+            const loaded = await readRecoveryArtifact(stateDir, id);
+            if (repoRoot && canonicalPath(loaded.manifest.repoRoot) !== canonicalPath(repoRoot))
+                continue;
+            summaries.push({
+                checkpointId: id,
+                state,
+                ...(loaded.state.detail ? { stateDetail: loaded.state.detail } : {}),
+                backend: loaded.manifest.backend,
+                repoRoot: loaded.manifest.repoRoot,
+                commandFingerprint: loaded.manifest.commandFingerprint,
+                createdAt: loaded.manifest.createdAt,
+                expiresAt: loaded.manifest.expiresAt,
+                changeCount: loaded.manifest.entries.length,
+                manifestHash: loaded.manifestHash,
+                ...(loaded.receipt
+                    ? {
+                        receiptHash: hashValue(canonicalStringify(loaded.receipt)),
+                        proofHash: loaded.receipt.proofHash,
+                        postStateHash: loaded.receipt.postStateHash,
+                    }
+                    : {}),
+            });
+        }
+        catch {
+            try {
+                const manifest = JSON.parse(await readFile(path.join(checkpointDir(stateDir, id), 'manifest.json'), 'utf8'));
+                if (manifest.checkpointId !== id || ![1, 2].includes(manifest.version))
+                    continue;
+                if (repoRoot && canonicalPath(manifest.repoRoot) !== canonicalPath(repoRoot))
+                    continue;
+                summaries.push({
+                    checkpointId: id,
+                    state: 'corrupt',
+                    backend: manifest.backend,
+                    repoRoot: manifest.repoRoot,
+                    commandFingerprint: manifest.commandFingerprint,
+                    createdAt: manifest.createdAt,
+                    expiresAt: manifest.expiresAt,
+                    changeCount: Array.isArray(manifest.entries) ? manifest.entries.length : 0,
+                    manifestHash: hashValue(canonicalStringify(manifest)),
+                });
+            }
+            catch {
+                // No trustworthy repository identity is available for this artifact.
+            }
+        }
+    }
+    return summaries.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+export async function recoveryCheckpointStorageBytes(stateDir, repoRoot) {
+    const root = checkpointsRoot(stateDir);
+    if (!repoRoot)
+        return directorySize(root);
+    if (!existsSync(root))
+        return 0;
+    const expected = canonicalPath(repoRoot);
+    let total = 0;
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const entryPath = path.join(root, entry.name);
+        if (/^cp_[a-f0-9]{24}$/.test(entry.name)) {
+            if ((await artifactRepoRoot(stateDir, entry.name)) === expected) {
+                total += await directorySize(entryPath);
+            }
+            continue;
+        }
+        if (/^\.tmp-cp_[a-f0-9]{24}$/.test(entry.name)) {
+            try {
+                const owner = JSON.parse(await readFile(path.join(entryPath, 'owner.json'), 'utf8'));
+                if (typeof owner.repoRoot === 'string' && canonicalPath(owner.repoRoot) === expected) {
+                    total += await directorySize(entryPath);
+                }
+            }
+            catch {
+                // Unattributable staging data is reconciled once it is stale.
+            }
+        }
+    }
+    return total;
+}
+export async function showRecoveryCheckpoint(stateDir, checkpointId, expectedRepoRoot) {
+    if (expectedRepoRoot &&
+        (await artifactRepoRoot(stateDir, checkpointId)) !== canonicalPath(expectedRepoRoot)) {
+        throw new Error('recovery_checkpoint_repo_mismatch');
+    }
+    await reconcileRecoveryCheckpoint(stateDir, checkpointId);
+    return readRecoveryArtifact(stateDir, checkpointId);
+}
+export { markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, reconcileRecoveryCheckpoint, recoveryRestoreBinding, restoreRecoveryCheckpoint, };

package/dist/core/recovery/index.d.ts

@@ -1,3 +1,5 @@
 export { capabilityRequestsBlockRecovery } from './capability.js';
+export { discardPreparedRecoveryCheckpoint, listRecoveryCheckpoints, markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, prepareRecoveryCheckpoint, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_CHECKPOINT_QUOTA, RECOVERY_RESTORE_CONFLICT, reconcileRecoveryCheckpoint, recoveryCheckpointStorageBytes, recoveryRestoreBinding, restoreRecoveryCheckpoint, showRecoveryCheckpoint, } from './checkpoint.js';
 export { RECOVERY_DIRTY_WORKTREE, RECOVERY_EXECUTION_FAILED, RECOVERY_SUBSTRATE_UNAVAILABLE, recoveryFailClosedResult, recoveryFailReasonFromSkip, } from './fail-closed.js';
-export type { RecoveryBackend, RecoveryProofContext, RecoveryProofV1 } from './types.js';
+export { formatRecoveryStateDiagnostic, recoveryApprovalSetupNotes, recoveryNotificationConfigured, recoveryNotificationSetupWarning, summarizeRecoveryCheckpointDiagnostics, } from './operator-guidance.js';
+export type { RecoveryBackend, RecoveryCheckpointEntry, RecoveryCheckpointEntryV1, RecoveryCheckpointEntryV2, RecoveryCheckpointManifest, RecoveryCheckpointManifestV1, RecoveryCheckpointManifestV2, RecoveryCheckpointState, RecoveryCheckpointSummary, RecoveryFileSnapshotV1, RecoveryFileSnapshotV2, RecoveryProofContext, RecoveryProofV1, RecoveryReceiptV1, } from './types.js';

package/dist/core/recovery/index.js

@@ -1,2 +1,4 @@
 export { capabilityRequestsBlockRecovery } from './capability.js';
+export { discardPreparedRecoveryCheckpoint, listRecoveryCheckpoints, markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, prepareRecoveryCheckpoint, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_CHECKPOINT_QUOTA, RECOVERY_RESTORE_CONFLICT, reconcileRecoveryCheckpoint, recoveryCheckpointStorageBytes, recoveryRestoreBinding, restoreRecoveryCheckpoint, showRecoveryCheckpoint, } from './checkpoint.js';
 export { RECOVERY_DIRTY_WORKTREE, RECOVERY_EXECUTION_FAILED, RECOVERY_SUBSTRATE_UNAVAILABLE, recoveryFailClosedResult, recoveryFailReasonFromSkip, } from './fail-closed.js';
+export { formatRecoveryStateDiagnostic, recoveryApprovalSetupNotes, recoveryNotificationConfigured, recoveryNotificationSetupWarning, summarizeRecoveryCheckpointDiagnostics, } from './operator-guidance.js';

package/dist/core/recovery/operator-guidance.d.ts

@@ -0,0 +1,7 @@
+import type { BelayConfigV4 } from '../config.js';
+import type { RecoveryCheckpointState, RecoveryCheckpointSummary } from './types.js';
+export declare function recoveryNotificationConfigured(config: BelayConfigV4): boolean;
+export declare function recoveryApprovalSetupNotes(): string[];
+export declare function recoveryNotificationSetupWarning(): string;
+export declare function formatRecoveryStateDiagnostic(state: RecoveryCheckpointState, detail?: string): string | null;
+export declare function summarizeRecoveryCheckpointDiagnostics(checkpoints: RecoveryCheckpointSummary[]): string[];

package/dist/core/recovery/operator-guidance.js

@@ -0,0 +1,39 @@
+export function recoveryNotificationConfigured(config) {
+    return Boolean(config.notifications.webhookUrl || config.notifications.commandHook);
+}
+export function recoveryApprovalSetupNotes() {
+    return [
+        'Recovery restore flow: run `belay recover apply <checkpoint-id>`, approve with `belay approve <approval-id> --token <signed-token>`, then run the same apply command again.',
+        'Recovery restore always requires a signed out-of-band token, even when approvalSigning.required is false for general approvals.',
+    ];
+}
+export function recoveryNotificationSetupWarning() {
+    return ('Recovery checkpoint restore requires a signed out-of-band approval token, but no notification channel is configured. ' +
+        'Set notifications.webhookUrl or notifications.commandHook (e.g. via `belay config`) so `belay recover apply` can deliver the token.');
+}
+export function formatRecoveryStateDiagnostic(state, detail) {
+    switch (state) {
+        case 'needs_manual_repair':
+            return (detail ??
+                'Repository files no longer match the recorded before/after snapshots after an interrupted apply or restore. ' +
+                    'Inspect the working tree manually; automatic restore is blocked until the mismatch is resolved or the checkpoint is removed.');
+        case 'conflict':
+            return (detail ??
+                'Current repository files do not match the recorded post-state for this checkpoint. Restore was refused to avoid overwriting newer changes.');
+        case 'corrupt':
+            return (detail ??
+                'Checkpoint artifacts failed integrity checks. Do not restore from this checkpoint; inspect or remove the artifact directory manually.');
+        default:
+            return detail ?? null;
+    }
+}
+export function summarizeRecoveryCheckpointDiagnostics(checkpoints) {
+    const advisories = [];
+    for (const checkpoint of checkpoints) {
+        const diagnostic = formatRecoveryStateDiagnostic(checkpoint.state, checkpoint.stateDetail);
+        if (!diagnostic)
+            continue;
+        advisories.push(`${checkpoint.checkpointId} (${checkpoint.state}): ${diagnostic}`);
+    }
+    return advisories;
+}

package/dist/core/recovery/reconcile.d.ts

@@ -0,0 +1,3 @@
+import type { RecoveryCheckpointEntry, RecoveryCheckpointState } from './types.js';
+export declare function matchRecoverySide(resourceRoot: string, entries: RecoveryCheckpointEntry[], side: 'before' | 'after'): Promise<boolean>;
+export declare function reconcileRecoveryCheckpoint(stateDir: string, checkpointId: string): Promise<RecoveryCheckpointState>;

package/dist/core/recovery/reconcile.js

@@ -0,0 +1,48 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { hashValue } from '../fingerprint.js';
+import { checkpointDir, ensureRecoveryReceipt, RECOVERY_CHECKPOINT_CORRUPT, readRecoveryArtifact, writeRecoveryState, } from './artifact-store.js';
+import { assertRecoverySafeTarget, recoverySnapshotMatches, withoutRecoveryBlob, } from './snapshot-node.js';
+export async function matchRecoverySide(resourceRoot, entries, side) {
+    for (const entry of entries) {
+        const target = await assertRecoverySafeTarget(resourceRoot, entry.path);
+        if (!(await recoverySnapshotMatches(target, withoutRecoveryBlob(entry[side]))))
+            return false;
+    }
+    return true;
+}
+export async function reconcileRecoveryCheckpoint(stateDir, checkpointId) {
+    let loaded;
+    try {
+        loaded = await readRecoveryArtifact(stateDir, checkpointId);
+    }
+    catch {
+        const artifactDir = checkpointDir(stateDir, checkpointId);
+        if (existsSync(artifactDir)) {
+            const manifestPath = path.join(artifactDir, 'manifest.json');
+            const hash = existsSync(manifestPath)
+                ? hashValue(await readFile(manifestPath, 'utf8'))
+                : 'unavailable';
+            await writeRecoveryState(artifactDir, 'corrupt', hash, RECOVERY_CHECKPOINT_CORRUPT);
+        }
+        return 'corrupt';
+    }
+    if (!['prepared', 'applying', 'restoring'].includes(loaded.state.state)) {
+        return loaded.state.state;
+    }
+    const before = await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'before');
+    const after = await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'after');
+    if (before) {
+        const state = loaded.state.state === 'restoring' ? 'restored' : 'prepared';
+        await writeRecoveryState(loaded.artifactDir, state, loaded.manifestHash);
+        return state;
+    }
+    if (after) {
+        await ensureRecoveryReceipt(loaded.artifactDir, loaded.manifest, loaded.manifestHash);
+        await writeRecoveryState(loaded.artifactDir, 'applied', loaded.manifestHash);
+        return 'applied';
+    }
+    await writeRecoveryState(loaded.artifactDir, 'needs_manual_repair', loaded.manifestHash, 'mixed checkpoint state after interrupted operation');
+    return 'needs_manual_repair';
+}

package/dist/core/recovery/resource-identity.d.ts

@@ -0,0 +1,4 @@
+import type { RecoveryCheckpointManifest } from './types.js';
+export type RecoveryResourceKind = 'git_repository' | 'directory';
+export declare function currentRecoveryResourceIdentity(resourceRoot: string, resourceKind: RecoveryResourceKind): Promise<string>;
+export declare function assertRecoveryResourceIdentity(manifest: RecoveryCheckpointManifest): Promise<void>;

package/dist/core/recovery/resource-identity.js

@@ -0,0 +1,34 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { hashValue } from '../fingerprint.js';
+export async function currentRecoveryResourceIdentity(resourceRoot, resourceKind) {
+    const resolvedRoot = await realpath(resourceRoot);
+    if (resourceKind === 'directory') {
+        const rootInfo = await lstat(resolvedRoot);
+        if (!rootInfo.isDirectory())
+            throw new Error('recovery_repo_identity_unavailable');
+        return hashValue(`${resolvedRoot}\0${rootInfo.dev}:${rootInfo.ino}:${rootInfo.birthtimeMs}`);
+    }
+    const dotGit = path.join(resolvedRoot, '.git');
+    const gitInfo = await lstat(dotGit);
+    let gitMetadataPath = dotGit;
+    if (gitInfo.isFile()) {
+        const marker = (await readFile(dotGit, 'utf8')).trim();
+        if (!marker.startsWith('gitdir:'))
+            throw new Error('recovery_repo_identity_unavailable');
+        gitMetadataPath = path.resolve(resolvedRoot, marker.slice('gitdir:'.length).trim());
+    }
+    else if (!gitInfo.isDirectory()) {
+        throw new Error('recovery_repo_identity_unavailable');
+    }
+    const resolvedGitMetadataPath = await realpath(gitMetadataPath);
+    const metadata = await lstat(resolvedGitMetadataPath);
+    return hashValue(`${resolvedRoot}\0${resolvedGitMetadataPath}\0${metadata.dev}:${metadata.ino}:${metadata.birthtimeMs}`);
+}
+export async function assertRecoveryResourceIdentity(manifest) {
+    const resourceKind = manifest.version === 1 ? 'git_repository' : manifest.resourceKind;
+    if ((await currentRecoveryResourceIdentity(manifest.repoRoot, resourceKind)) !==
+        manifest.repoIdentity) {
+        throw new Error('recovery_checkpoint_repo_mismatch');
+    }
+}

package/dist/core/recovery/restore.d.ts

@@ -0,0 +1,13 @@
+export declare const RECOVERY_RESTORE_CONFLICT = "recovery_restore_conflict";
+export declare const RECOVERY_RESTORE_REASON = "recovery_restore";
+export declare function recoveryRestoreBinding(stateDir: string, checkpointId: string, expectedRepoRoot?: string): Promise<{
+    fingerprint: string;
+    manifestHash: string;
+    postStateHash: string;
+    paths: string[];
+    repoRoot: string;
+}>;
+export declare function restoreRecoveryCheckpoint(stateDir: string, checkpointId: string, expectedRepoRoot?: string): Promise<{
+    manifestHash: string;
+    changeCount: number;
+}>;

package/dist/core/recovery/restore.js

@@ -0,0 +1,114 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { canonicalPath } from '../path-utils.js';
+import { artifactRepoRoot, RECOVERY_CHECKPOINT_CORRUPT, readRecoveryArtifact, writeRecoveryState, } from './artifact-store.js';
+import { matchRecoverySide } from './reconcile.js';
+import { assertRecoveryResourceIdentity } from './resource-identity.js';
+import { applyRecoverySnapshot, assertRecoverySafeTarget, captureRecoverySnapshot, recoverySnapshotHash, recoveryStateHash, sortRecoveryEntriesForSide, withoutRecoveryBlob, } from './snapshot-node.js';
+export const RECOVERY_RESTORE_CONFLICT = 'recovery_restore_conflict';
+export const RECOVERY_RESTORE_REASON = 'recovery_restore';
+async function assertExpectedRepoRoot(stateDir, checkpointId, expectedRepoRoot) {
+    if (expectedRepoRoot &&
+        (await artifactRepoRoot(stateDir, checkpointId)) !== canonicalPath(expectedRepoRoot)) {
+        throw new Error('recovery_checkpoint_repo_mismatch');
+    }
+}
+export async function recoveryRestoreBinding(stateDir, checkpointId, expectedRepoRoot) {
+    await assertExpectedRepoRoot(stateDir, checkpointId, expectedRepoRoot);
+    const loaded = await readRecoveryArtifact(stateDir, checkpointId);
+    await assertRecoveryResourceIdentity(loaded.manifest);
+    if (Date.parse(loaded.manifest.expiresAt) <= Date.now()) {
+        throw new Error('recovery_checkpoint_expired');
+    }
+    if (!['applied', 'conflict'].includes(loaded.state.state)) {
+        throw new Error(`recovery_checkpoint_not_applied:${loaded.state.state}`);
+    }
+    if (!(await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'after'))) {
+        await writeRecoveryState(loaded.artifactDir, 'conflict', loaded.manifestHash, RECOVERY_RESTORE_CONFLICT);
+        throw new Error(RECOVERY_RESTORE_CONFLICT);
+    }
+    const paths = loaded.manifest.entries.map((entry) => entry.path).sort();
+    const postStateHash = recoveryStateHash(loaded.manifest.entries, 'after');
+    return {
+        fingerprint: hashValue(canonicalStringify({
+            action: 'recovery.restore',
+            repoRoot: loaded.manifest.repoRoot,
+            checkpointId,
+            manifestHash: loaded.manifestHash,
+            postStateHash,
+            paths,
+        })),
+        manifestHash: loaded.manifestHash,
+        postStateHash,
+        paths,
+        repoRoot: loaded.manifest.repoRoot,
+    };
+}
+export async function restoreRecoveryCheckpoint(stateDir, checkpointId, expectedRepoRoot) {
+    await assertExpectedRepoRoot(stateDir, checkpointId, expectedRepoRoot);
+    const loaded = await readRecoveryArtifact(stateDir, checkpointId);
+    await assertRecoveryResourceIdentity(loaded.manifest);
+    if (Date.parse(loaded.manifest.expiresAt) <= Date.now()) {
+        throw new Error('recovery_checkpoint_expired');
+    }
+    if (!['applied', 'conflict'].includes(loaded.state.state)) {
+        throw new Error(`recovery_checkpoint_not_applied:${loaded.state.state}`);
+    }
+    if (!(await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'after'))) {
+        await writeRecoveryState(loaded.artifactDir, 'conflict', loaded.manifestHash, RECOVERY_RESTORE_CONFLICT);
+        throw new Error(RECOVERY_RESTORE_CONFLICT);
+    }
+    const rollbackDir = await mkdtemp(path.join(os.tmpdir(), 'belay-recovery-rollback-'));
+    const rollback = [];
+    try {
+        for (const entry of loaded.manifest.entries) {
+            const target = await assertRecoverySafeTarget(loaded.manifest.repoRoot, entry.path);
+            const snapshot = await captureRecoverySnapshot(target, {
+                blobDir: path.join(rollbackDir, 'blobs'),
+            });
+            rollback.push({ path: entry.path, target, before: snapshot, after: snapshot });
+        }
+        const capturedPostStateMatches = rollback.every((item, index) => {
+            const expected = loaded.manifest.entries[index]?.after;
+            return (expected !== undefined &&
+                recoverySnapshotHash(withoutRecoveryBlob(item.before)) ===
+                    recoverySnapshotHash(withoutRecoveryBlob(expected)));
+        });
+        if (!capturedPostStateMatches) {
+            await writeRecoveryState(loaded.artifactDir, 'conflict', loaded.manifestHash, RECOVERY_RESTORE_CONFLICT);
+            throw new Error(RECOVERY_RESTORE_CONFLICT);
+        }
+        await writeRecoveryState(loaded.artifactDir, 'restoring', loaded.manifestHash);
+        try {
+            for (const entry of sortRecoveryEntriesForSide(loaded.manifest.entries, 'before')) {
+                const target = await assertRecoverySafeTarget(loaded.manifest.repoRoot, entry.path);
+                await applyRecoverySnapshot(target, entry.before, loaded.artifactDir, RECOVERY_CHECKPOINT_CORRUPT);
+            }
+            if (!(await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'before'))) {
+                throw new Error('recovery_restore_verification_failed');
+            }
+            await writeRecoveryState(loaded.artifactDir, 'restored', loaded.manifestHash);
+            return { manifestHash: loaded.manifestHash, changeCount: loaded.manifest.entries.length };
+        }
+        catch (error) {
+            let rollbackFailed = false;
+            for (const item of sortRecoveryEntriesForSide(rollback, 'before')) {
+                try {
+                    await applyRecoverySnapshot(item.target, item.before, rollbackDir, RECOVERY_CHECKPOINT_CORRUPT);
+                }
+                catch {
+                    rollbackFailed = true;
+                }
+            }
+            const rollbackVerified = !rollbackFailed &&
+                (await matchRecoverySide(loaded.manifest.repoRoot, loaded.manifest.entries, 'after'));
+            await writeRecoveryState(loaded.artifactDir, rollbackVerified ? 'applied' : 'needs_manual_repair', loaded.manifestHash, error instanceof Error ? error.message : 'recovery_restore_failed');
+            throw error;
+        }
+    }
+    finally {
+        await rm(rollbackDir, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/dist/core/recovery/snapshot-node.d.ts

@@ -0,0 +1,27 @@
+import type { RecoveryCheckpointEntry, RecoveryFileSnapshotV2 } from './types.js';
+export declare const RECOVERY_UNSUPPORTED_FILE_KIND = "recovery_unsupported_file_kind";
+export declare function validRecoveryRelativePath(relativePath: string): boolean;
+export declare function assertRecoverySafeTarget(resourceRoot: string, relativePath: string): Promise<string>;
+export declare function recoveryDirectoryHash(mode: number): string;
+export declare function recoverySnapshotHash(snapshot: RecoveryFileSnapshotV2): string;
+export declare function withoutRecoveryBlob(snapshot: RecoveryFileSnapshotV2): RecoveryFileSnapshotV2;
+export declare function captureRecoverySnapshot(filePath: string, options?: {
+    blobDir?: string;
+}): Promise<RecoveryFileSnapshotV2>;
+export declare function recoverySnapshotMatches(filePath: string, expected: RecoveryFileSnapshotV2): Promise<boolean>;
+export declare function validateRecoverySnapshot(params: {
+    snapshot: unknown;
+    side: 'before' | 'after';
+    manifestVersion: 1 | 2;
+    artifactDir: string;
+    corruptReason: string;
+}): Promise<void>;
+export declare function applyRecoverySnapshot(target: string, snapshot: RecoveryFileSnapshotV2, artifactDir: string, corruptReason: string): Promise<void>;
+interface RecoveryEntryLike {
+    path: string;
+    before: RecoveryFileSnapshotV2;
+    after: RecoveryFileSnapshotV2;
+}
+export declare function sortRecoveryEntriesForSide<T extends RecoveryEntryLike>(entries: T[], side: 'before' | 'after'): T[];
+export declare function recoveryStateHash(entries: RecoveryCheckpointEntry[], side: 'before' | 'after'): string;
+export {};