@guilz-dev/belay 0.6.0 → 0.7.0

package/dist/core/recovery/artifact-store.js

@@ -0,0 +1,336 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { lstat, mkdir, open, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { canonicalPath } from '../path-utils.js';
+import { recoveryStateHash, validateRecoverySnapshot, validRecoveryRelativePath, } from './snapshot-node.js';
+export const RECOVERY_CHECKPOINT_CORRUPT = 'recovery_checkpoint_corrupt';
+const RECOVERY_STATES = new Set([
+    'prepared',
+    'applying',
+    'applied',
+    'restoring',
+    'restored',
+    'conflict',
+    'corrupt',
+    'needs_manual_repair',
+]);
+const STAGING_STALE_MS = 5 * 60_000;
+export function checkpointsRoot(stateDir) {
+    return path.join(stateDir, 'recovery', 'checkpoints');
+}
+export function checkpointDir(stateDir, checkpointId) {
+    if (!/^cp_[a-f0-9]{24}$/.test(checkpointId)) {
+        throw new Error('invalid_recovery_checkpoint_id');
+    }
+    return path.join(checkpointsRoot(stateDir), checkpointId);
+}
+export async function fsyncPath(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function atomicWriteJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.tmp-${randomUUID()}`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    await fsyncPath(temporary);
+    await rename(temporary, filePath);
+    await fsyncPath(path.dirname(filePath));
+}
+export async function writeRecoveryState(artifactDir, state, manifestHash, detail) {
+    const value = {
+        version: 1,
+        state,
+        updatedAt: new Date().toISOString(),
+        manifestHash,
+        ...(detail ? { detail } : {}),
+    };
+    await atomicWriteJson(path.join(artifactDir, 'state.json'), value);
+}
+export async function directorySize(root) {
+    if (!existsSync(root))
+        return 0;
+    let total = 0;
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory())
+            total += await directorySize(entryPath);
+        else
+            total += (await lstat(entryPath)).size;
+    }
+    return total;
+}
+function isManifestShape(value, checkpointId) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const manifest = value;
+    const proof = manifest.proof;
+    const manifestKeys = [
+        'version',
+        'checkpointId',
+        'backend',
+        'repoRoot',
+        'repoIdentity',
+        'commandFingerprint',
+        'createdAt',
+        'expiresAt',
+        'proof',
+        'entries',
+        ...(manifest.version === 2 ? ['resourceKind'] : []),
+    ];
+    const proofKeys = [
+        'version',
+        'backend',
+        'inputFingerprint',
+        'resourceScope',
+        'baseStateHash',
+        'effectClosure',
+        'issuedAt',
+        'expiresAt',
+        'probeSignals',
+    ];
+    if (![1, 2].includes(manifest.version) ||
+        Object.keys(manifest).length !== manifestKeys.length ||
+        !Object.keys(manifest).every((key) => manifestKeys.includes(key)) ||
+        manifest.checkpointId !== checkpointId ||
+        !['git_worktree', 'file_checkpoint'].includes(String(manifest.backend)) ||
+        typeof manifest.repoRoot !== 'string' ||
+        typeof manifest.repoIdentity !== 'string' ||
+        typeof manifest.commandFingerprint !== 'string' ||
+        typeof manifest.createdAt !== 'string' ||
+        !Number.isFinite(Date.parse(manifest.createdAt)) ||
+        typeof manifest.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(manifest.expiresAt)) ||
+        !Array.isArray(manifest.entries) ||
+        !proof ||
+        Object.keys(proof).length !== proofKeys.length ||
+        !Object.keys(proof).every((key) => proofKeys.includes(key)) ||
+        proof.version !== 1 ||
+        proof.backend !== manifest.backend ||
+        typeof proof.inputFingerprint !== 'string' ||
+        proof.inputFingerprint !== manifest.commandFingerprint ||
+        typeof proof.resourceScope !== 'string' ||
+        proof.resourceScope !== manifest.repoRoot ||
+        typeof proof.baseStateHash !== 'string' ||
+        proof.effectClosure !== 'repo_local_fs_observed' ||
+        typeof proof.issuedAt !== 'string' ||
+        !Number.isFinite(Date.parse(proof.issuedAt)) ||
+        proof.issuedAt !== manifest.createdAt ||
+        typeof proof.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(proof.expiresAt)) ||
+        proof.expiresAt !== manifest.expiresAt ||
+        !Array.isArray(proof.probeSignals) ||
+        !proof.probeSignals.every((signal) => typeof signal === 'string')) {
+        return false;
+    }
+    if (manifest.version === 1)
+        return !('resourceKind' in manifest);
+    return ['git_repository', 'directory'].includes(String(manifest.resourceKind));
+}
+export async function readRecoveryArtifact(stateDir, checkpointId) {
+    const artifactDir = checkpointDir(stateDir, checkpointId);
+    let rawManifest;
+    let state;
+    try {
+        rawManifest = JSON.parse(await readFile(path.join(artifactDir, 'manifest.json'), 'utf8'));
+        state = JSON.parse(await readFile(path.join(artifactDir, 'state.json'), 'utf8'));
+    }
+    catch {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    if (!isManifestShape(rawManifest, checkpointId))
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    const manifest = rawManifest;
+    const manifestHash = hashValue(canonicalStringify(manifest));
+    const stateKeys = state && typeof state === 'object' ? Object.keys(state) : [];
+    const expectedStateKeys = ['version', 'state', 'updatedAt', 'manifestHash'];
+    if (state && typeof state === 'object' && 'detail' in state)
+        expectedStateKeys.push('detail');
+    if (!state ||
+        typeof state !== 'object' ||
+        Array.isArray(state) ||
+        stateKeys.length !== expectedStateKeys.length ||
+        !stateKeys.every((key) => expectedStateKeys.includes(key)) ||
+        state.version !== 1 ||
+        !RECOVERY_STATES.has(state.state) ||
+        typeof state.updatedAt !== 'string' ||
+        !Number.isFinite(Date.parse(state.updatedAt)) ||
+        (state.detail !== undefined && typeof state.detail !== 'string') ||
+        state.manifestHash !== manifestHash) {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    const entryPaths = new Set();
+    for (const entry of manifest.entries) {
+        if (!entry ||
+            typeof entry !== 'object' ||
+            Array.isArray(entry) ||
+            Object.keys(entry).length !== 3 ||
+            !Object.keys(entry).every((key) => ['path', 'before', 'after'].includes(key)) ||
+            typeof entry.path !== 'string' ||
+            !('before' in entry) ||
+            !('after' in entry) ||
+            !validRecoveryRelativePath(entry.path) ||
+            entryPaths.has(path.normalize(entry.path))) {
+            throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+        }
+        entryPaths.add(path.normalize(entry.path));
+        for (const [side, snapshot] of [
+            ['before', entry.before],
+            ['after', entry.after],
+        ]) {
+            await validateRecoverySnapshot({
+                snapshot,
+                side,
+                manifestVersion: manifest.version,
+                artifactDir,
+                corruptReason: RECOVERY_CHECKPOINT_CORRUPT,
+            });
+        }
+    }
+    const receiptPath = path.join(artifactDir, 'receipt.json');
+    let receipt;
+    if (['applied', 'restoring', 'restored', 'conflict'].includes(state.state) ||
+        existsSync(receiptPath)) {
+        receipt = await readAndValidateRecoveryReceipt(artifactDir, manifest, manifestHash);
+    }
+    return { artifactDir, manifest, state, manifestHash, ...(receipt ? { receipt } : {}) };
+}
+async function readAndValidateRecoveryReceipt(artifactDir, manifest, manifestHash) {
+    let rawReceipt;
+    try {
+        rawReceipt = JSON.parse(await readFile(path.join(artifactDir, 'receipt.json'), 'utf8'));
+    }
+    catch {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    if (!rawReceipt || typeof rawReceipt !== 'object' || Array.isArray(rawReceipt)) {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    const receipt = rawReceipt;
+    const receiptKeys = [
+        'version',
+        'checkpointId',
+        'manifestHash',
+        'proofHash',
+        'postStateHash',
+        'appliedAt',
+        'changeCount',
+    ];
+    if (Object.keys(receipt).length !== receiptKeys.length ||
+        !Object.keys(receipt).every((key) => receiptKeys.includes(key)) ||
+        receipt.version !== 1 ||
+        receipt.checkpointId !== manifest.checkpointId ||
+        receipt.manifestHash !== manifestHash ||
+        receipt.proofHash !== hashValue(canonicalStringify(manifest.proof)) ||
+        receipt.postStateHash !== recoveryStateHash(manifest.entries, 'after') ||
+        receipt.changeCount !== manifest.entries.length ||
+        typeof receipt.appliedAt !== 'string' ||
+        !Number.isFinite(Date.parse(receipt.appliedAt))) {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    return receipt;
+}
+export async function ensureRecoveryReceipt(artifactDir, manifest, manifestHash) {
+    const receiptPath = path.join(artifactDir, 'receipt.json');
+    if (existsSync(receiptPath)) {
+        return readAndValidateRecoveryReceipt(artifactDir, manifest, manifestHash);
+    }
+    const receipt = {
+        version: 1,
+        checkpointId: manifest.checkpointId,
+        manifestHash,
+        proofHash: hashValue(canonicalStringify(manifest.proof)),
+        postStateHash: recoveryStateHash(manifest.entries, 'after'),
+        appliedAt: new Date().toISOString(),
+        changeCount: manifest.entries.length,
+    };
+    await atomicWriteJson(receiptPath, receipt);
+    return receipt;
+}
+export async function checkpointIds(stateDir) {
+    const root = checkpointsRoot(stateDir);
+    if (!existsSync(root))
+        return [];
+    return (await readdir(root, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory() && /^cp_[a-f0-9]{24}$/.test(entry.name))
+        .map((entry) => entry.name);
+}
+export async function artifactRepoRoot(stateDir, checkpointId) {
+    const artifactDir = checkpointDir(stateDir, checkpointId);
+    try {
+        const manifest = JSON.parse(await readFile(path.join(artifactDir, 'manifest.json'), 'utf8'));
+        if (typeof manifest.repoRoot === 'string' && manifest.repoRoot) {
+            return canonicalPath(manifest.repoRoot);
+        }
+    }
+    catch {
+        // Fall through to the immutable staging owner used for quota attribution.
+    }
+    try {
+        const owner = JSON.parse(await readFile(path.join(artifactDir, 'owner.json'), 'utf8'));
+        return typeof owner.repoRoot === 'string' && owner.repoRoot
+            ? canonicalPath(owner.repoRoot)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function checkpointIdsForRepo(stateDir, repoRoot) {
+    const expected = canonicalPath(repoRoot);
+    const matching = [];
+    for (const id of await checkpointIds(stateDir)) {
+        if ((await artifactRepoRoot(stateDir, id)) === expected)
+            matching.push(id);
+    }
+    return matching;
+}
+export async function cleanupOrphanedStaging(stateDir) {
+    const root = checkpointsRoot(stateDir);
+    if (!existsSync(root))
+        return;
+    const now = Date.now();
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^\.tmp-cp_[a-f0-9]{24}$/.test(entry.name))
+            continue;
+        const stagingPath = path.join(root, entry.name);
+        let stale = false;
+        try {
+            const owner = JSON.parse(await readFile(path.join(stagingPath, 'owner.json'), 'utf8'));
+            const pid = typeof owner.pid === 'number' ? owner.pid : Number.NaN;
+            const createdAt = typeof owner.createdAt === 'string' ? Date.parse(owner.createdAt) : NaN;
+            let alive = false;
+            if (Number.isInteger(pid) && pid > 0) {
+                try {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+                catch {
+                    alive = false;
+                }
+            }
+            stale = !alive || !Number.isFinite(createdAt);
+        }
+        catch {
+            const info = await lstat(stagingPath);
+            stale = now - info.mtimeMs >= STAGING_STALE_MS;
+        }
+        if (stale)
+            await rm(stagingPath, { recursive: true, force: true });
+    }
+}
+export async function markRecoveryCheckpointApplying(stateDir, checkpoint) {
+    await writeRecoveryState(checkpointDir(stateDir, checkpoint.checkpointId), 'applying', checkpoint.manifestHash);
+}
+export async function markRecoveryCheckpointApplied(stateDir, checkpoint) {
+    const artifactDir = checkpointDir(stateDir, checkpoint.checkpointId);
+    const receipt = await ensureRecoveryReceipt(artifactDir, checkpoint.manifest, checkpoint.manifestHash);
+    await writeRecoveryState(artifactDir, 'applied', checkpoint.manifestHash);
+    return receipt;
+}

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

@@ -0,0 +1,25 @@
+import type { BelayTransactionalConfig } from '../config.js';
+import type { TransactionalFileChange } from '../transactional/types.js';
+import { markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, type PreparedRecoveryCheckpoint, RECOVERY_CHECKPOINT_CORRUPT } from './artifact-store.js';
+import { reconcileRecoveryCheckpoint } from './reconcile.js';
+import { RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, recoveryRestoreBinding, restoreRecoveryCheckpoint } from './restore.js';
+import type { RecoveryBackend, RecoveryCheckpointSummary } from './types.js';
+export declare const RECOVERY_CHECKPOINT_QUOTA = "recovery_checkpoint_quota_exceeded";
+type CheckpointConfig = NonNullable<BelayTransactionalConfig['checkpoint']>;
+export declare function prepareRecoveryCheckpoint(params: {
+    stateDir: string;
+    repoRoot: string;
+    /** Immutable pre-command source for recovery blobs, when available. */
+    baselinePath?: string;
+    worktreePath: string;
+    commandFingerprint: string;
+    changes: TransactionalFileChange[];
+    protectedRoots?: string[];
+    config: CheckpointConfig;
+    backend?: RecoveryBackend;
+}): Promise<PreparedRecoveryCheckpoint>;
+export declare function discardPreparedRecoveryCheckpoint(stateDir: string, checkpointId: string): Promise<boolean>;
+export declare function listRecoveryCheckpoints(stateDir: string, repoRoot?: string): Promise<RecoveryCheckpointSummary[]>;
+export declare function recoveryCheckpointStorageBytes(stateDir: string, repoRoot?: string): Promise<number>;
+export declare function showRecoveryCheckpoint(stateDir: string, checkpointId: string, expectedRepoRoot?: string): Promise<import("./artifact-store.js").RecoveryArtifact>;
+export { markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, reconcileRecoveryCheckpoint, recoveryRestoreBinding, restoreRecoveryCheckpoint, };

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[];