@guilz-dev/belay 0.4.0 → 0.7.0

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

@@ -0,0 +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 { 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

@@ -0,0 +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 {};

package/dist/core/recovery/snapshot-node.js

@@ -0,0 +1,261 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { chmod, copyFile, lstat, mkdir, open, readFile, readlink, rm, rmdir, symlink, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { canonicalPath } from '../path-utils.js';
+export const RECOVERY_UNSUPPORTED_FILE_KIND = 'recovery_unsupported_file_kind';
+export function validRecoveryRelativePath(relativePath) {
+    if (!relativePath || relativePath.includes('\0') || path.isAbsolute(relativePath))
+        return false;
+    const normalized = path.normalize(relativePath);
+    return normalized !== '.' && normalized !== '..' && !normalized.startsWith(`..${path.sep}`);
+}
+export async function assertRecoverySafeTarget(resourceRoot, relativePath) {
+    if (!validRecoveryRelativePath(relativePath))
+        throw new Error('recovery_path_escape');
+    const root = canonicalPath(resourceRoot);
+    const target = path.resolve(root, relativePath);
+    const relative = path.relative(root, target);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('recovery_path_escape');
+    }
+    let current = root;
+    const parentParts = path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean);
+    for (const part of parentParts) {
+        current = path.join(current, part);
+        if (!existsSync(current))
+            break;
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            throw new Error('recovery_symlink_escape');
+        if (!info.isDirectory())
+            break;
+    }
+    return target;
+}
+async function fsyncPath(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function normalizedMode(mode) {
+    return mode & 0o777;
+}
+export function recoveryDirectoryHash(mode) {
+    return hashValue(`directory:${normalizedMode(mode)}`);
+}
+export function recoverySnapshotHash(snapshot) {
+    return hashValue(canonicalStringify(snapshot));
+}
+export function withoutRecoveryBlob(snapshot) {
+    if (snapshot.kind !== 'file')
+        return { ...snapshot };
+    const { blob: _blob, ...rest } = snapshot;
+    return rest;
+}
+export async function captureRecoverySnapshot(filePath, options) {
+    let info;
+    try {
+        info = await lstat(filePath);
+    }
+    catch (error) {
+        if (!['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            throw error;
+        return { kind: 'absent' };
+    }
+    if (info.isSymbolicLink()) {
+        const symlinkTarget = await readlink(filePath);
+        return {
+            kind: 'symlink',
+            symlinkTarget,
+            hash: hashValue(`symlink:${symlinkTarget}`),
+        };
+    }
+    if (info.isDirectory()) {
+        const mode = normalizedMode(info.mode);
+        return { kind: 'directory', mode, hash: recoveryDirectoryHash(mode) };
+    }
+    if (!info.isFile())
+        throw new Error(RECOVERY_UNSUPPORTED_FILE_KIND);
+    const content = await readFile(filePath);
+    const hash = createHash('sha256').update(content).digest('hex');
+    let blob;
+    if (options?.blobDir) {
+        await mkdir(options.blobDir, { recursive: true, mode: 0o700 });
+        const blobPath = path.join(options.blobDir, hash);
+        if (!existsSync(blobPath)) {
+            await writeFile(blobPath, content, { mode: 0o600 });
+            await fsyncPath(blobPath);
+        }
+        blob = `blobs/${hash}`;
+    }
+    return { kind: 'file', mode: normalizedMode(info.mode), hash, ...(blob ? { blob } : {}) };
+}
+export async function recoverySnapshotMatches(filePath, expected) {
+    try {
+        const current = await captureRecoverySnapshot(filePath);
+        return (recoverySnapshotHash(withoutRecoveryBlob(current)) ===
+            recoverySnapshotHash(withoutRecoveryBlob(expected)));
+    }
+    catch {
+        return false;
+    }
+}
+export async function validateRecoverySnapshot(params) {
+    const { snapshot } = params;
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        throw new Error(params.corruptReason);
+    }
+    const record = snapshot;
+    const hasExactKeys = (allowed) => {
+        const keys = Object.keys(record);
+        return keys.length === allowed.length && keys.every((key) => allowed.includes(key));
+    };
+    const validHash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+    const validMode = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0o777;
+    if (record.kind === 'absent') {
+        if (!hasExactKeys(['kind']))
+            throw new Error(params.corruptReason);
+        return;
+    }
+    if (record.kind === 'directory') {
+        if (params.manifestVersion !== 2 ||
+            !hasExactKeys(['kind', 'mode', 'hash']) ||
+            !validMode(record.mode) ||
+            !validHash(record.hash) ||
+            record.hash !== recoveryDirectoryHash(record.mode)) {
+            throw new Error(params.corruptReason);
+        }
+        return;
+    }
+    if (record.kind === 'symlink') {
+        if (!hasExactKeys(['kind', 'symlinkTarget', 'hash']) ||
+            typeof record.symlinkTarget !== 'string' ||
+            !validHash(record.hash) ||
+            record.hash !== hashValue(`symlink:${record.symlinkTarget}`)) {
+            throw new Error(params.corruptReason);
+        }
+        return;
+    }
+    if (record.kind !== 'file')
+        throw new Error(params.corruptReason);
+    const allowedKeys = record.blob === undefined ? ['kind', 'mode', 'hash'] : ['kind', 'mode', 'hash', 'blob'];
+    if (!hasExactKeys(allowedKeys) ||
+        !validMode(record.mode) ||
+        !validHash(record.hash) ||
+        (record.blob !== undefined && typeof record.blob !== 'string')) {
+        throw new Error(params.corruptReason);
+    }
+    if (params.side === 'before' && !record.blob)
+        throw new Error(params.corruptReason);
+    if (!record.blob)
+        return;
+    if (record.blob !== `blobs/${record.hash}`)
+        throw new Error(params.corruptReason);
+    let content;
+    try {
+        content = await readFile(path.join(params.artifactDir, record.blob));
+    }
+    catch {
+        throw new Error(params.corruptReason);
+    }
+    if (createHash('sha256').update(content).digest('hex') !== record.hash) {
+        throw new Error(params.corruptReason);
+    }
+}
+async function removeTargetWithoutRecursion(target) {
+    let info;
+    try {
+        info = await lstat(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (info.isDirectory() && !info.isSymbolicLink()) {
+        await rmdir(target);
+        return;
+    }
+    await rm(target, { force: true, recursive: false });
+}
+export async function applyRecoverySnapshot(target, snapshot, artifactDir, corruptReason) {
+    if (snapshot.kind === 'absent') {
+        await removeTargetWithoutRecursion(target);
+        return;
+    }
+    let current;
+    try {
+        current = await lstat(target);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (snapshot.kind === 'directory') {
+        if (current && (!current.isDirectory() || current.isSymbolicLink())) {
+            await removeTargetWithoutRecursion(target);
+            current = undefined;
+        }
+        if (!current)
+            await mkdir(target, { recursive: false, mode: snapshot.mode });
+        await chmod(target, snapshot.mode);
+        return;
+    }
+    if (current)
+        await removeTargetWithoutRecursion(target);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (snapshot.kind === 'symlink') {
+        if (snapshot.symlinkTarget === undefined)
+            throw new Error(corruptReason);
+        await symlink(snapshot.symlinkTarget, target);
+        return;
+    }
+    if (!snapshot.blob || !snapshot.hash)
+        throw new Error(corruptReason);
+    const blobPath = path.join(artifactDir, snapshot.blob);
+    let content;
+    try {
+        content = await readFile(blobPath);
+    }
+    catch {
+        throw new Error(corruptReason);
+    }
+    if (createHash('sha256').update(content).digest('hex') !== snapshot.hash) {
+        throw new Error(corruptReason);
+    }
+    await copyFile(blobPath, target);
+    if (snapshot.mode !== undefined)
+        await chmod(target, snapshot.mode);
+}
+function pathDepth(relativePath) {
+    return relativePath.split(path.sep).length;
+}
+export function sortRecoveryEntriesForSide(entries, side) {
+    const rank = (entry) => {
+        if (entry[side].kind === 'absent')
+            return 0;
+        if (entry[side].kind === 'directory')
+            return 1;
+        return 2;
+    };
+    return [...entries].sort((left, right) => {
+        const rankDifference = rank(left) - rank(right);
+        if (rankDifference !== 0)
+            return rankDifference;
+        const depthDifference = pathDepth(left.path) - pathDepth(right.path);
+        if (left[side].kind === 'absent' && depthDifference !== 0)
+            return -depthDifference;
+        if (depthDifference !== 0)
+            return depthDifference;
+        return left.path.localeCompare(right.path);
+    });
+}
+export function recoveryStateHash(entries, side) {
+    return hashValue(canonicalStringify(entries.map((entry) => ({ path: entry.path, state: entry[side] }))));
+}