@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/core/transactional/git-worktree.js

@@ -1,11 +1,10 @@
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { copyFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { canonicalPath, isPathOutsideRoot, pathWithinRoot } from '../path-utils.js';
-export const TRANSACTIONAL_APPLY_TOCTOU = 'transactional_apply_toctou';
+import { runProcessWithBoundedOutput } from '../process-runner.js';
+import { applyObservedChanges, buildObservedChangesFromTransactional, TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU, } from './apply-observed-changes.js';
+export { TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU };
 function execGit(repoRoot, args) {
     return new Promise((resolve, reject) => {
         const child = spawn('git', ['-C', repoRoot, ...args], {
@@ -29,7 +28,7 @@ function porcelainRelativePath(line) {
     if (line.length < 4) {
         return null;
     }
-    const relativePath = line.slice(3).trim();
+    const relativePath = line.slice(3);
     return relativePath || null;
 }
 function isIgnoredDirtyPath(repoRoot, relativePath, ignoreRoots) {
@@ -41,22 +40,6 @@ function isIgnoredDirtyPath(repoRoot, relativePath, ignoreRoots) {
         root === absolutePath ||
         pathWithinRoot(absolutePath, root));
 }
-export async function hashRepoFile(filePath) {
-    const content = await readFile(filePath);
-    return createHash('sha256').update(content).digest('hex');
-}
-export async function captureRepoFileHashes(repoRoot, changes) {
-    const hashes = new Map();
-    for (const change of changes) {
-        const target = path.join(repoRoot, change.relativePath);
-        if (!existsSync(target)) {
-            hashes.set(change.relativePath, null);
-            continue;
-        }
-        hashes.set(change.relativePath, await hashRepoFile(target));
-    }
-    return hashes;
-}
 export async function isGitWorktreeAvailable(repoRoot) {
     try {
         await execGit(repoRoot, ['rev-parse', '--git-dir']);
@@ -91,6 +74,7 @@ export async function isDirtyWorktree(repoRoot, options) {
     }
 }
 export async function createGitWorktreeSnapshot(repoRoot, _stateDir) {
+    const { mkdtemp, rm } = await import('node:fs/promises');
     const worktreePath = await mkdtemp(path.join(os.tmpdir(), 'belay-tx-'));
     await execGit(repoRoot, ['worktree', 'add', '--detach', worktreePath, 'HEAD']);
     return {
@@ -123,38 +107,14 @@ export function resolveWorktreeCwd(repoRoot, worktreePath, cwd) {
     return path.join(worktreePath, relative);
 }
 export function runShellCommand(command, cwd, timeoutMs) {
-    return new Promise((resolve) => {
-        const child = spawn(command, {
-            cwd,
-            shell: true,
-            stdio: 'ignore',
-            env: process.env,
-        });
-        let timedOut = false;
-        const timer = setTimeout(() => {
-            timedOut = true;
-            child.kill('SIGTERM');
-        }, timeoutMs);
-        child.on('error', () => {
-            clearTimeout(timer);
-            resolve({ exitCode: 1, signal: null, timedOut });
-        });
-        child.on('close', (exitCode, signal) => {
-            clearTimeout(timer);
-            resolve({
-                exitCode,
-                signal: signal ? String(signal) : null,
-                timedOut,
-            });
-        });
-    });
+    return runProcessWithBoundedOutput(command, [], { cwd, shell: true, env: process.env }, timeoutMs);
 }
 function parseStatusLine(line) {
     if (line.length < 4) {
         return null;
     }
     const status = line.slice(0, 2);
-    const relativePath = line.slice(3).trim();
+    const relativePath = line.slice(3);
     if (!relativePath) {
         return null;
     }
@@ -170,11 +130,17 @@ function parseStatusLine(line) {
     return { relativePath, kind: 'modified' };
 }
 export async function collectWorktreeChanges(worktreePath) {
-    const status = await execGit(worktreePath, ['status', '--porcelain']);
+    const status = await execGit(worktreePath, [
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '-uall',
+        '--no-renames',
+    ]);
     const changes = [];
     const seen = new Set();
-    for (const line of status.split('\n')) {
-        if (!line.trim()) {
+    for (const line of status.split('\0')) {
+        if (!line) {
             continue;
         }
         const change = parseStatusLine(line);
@@ -186,74 +152,13 @@ export async function collectWorktreeChanges(worktreePath) {
     }
     return changes;
 }
-async function rollbackAppliedChanges(actions) {
-    for (const action of [...actions].reverse()) {
-        try {
-            if (action.type === 'restore') {
-                await mkdir(path.dirname(action.target), { recursive: true });
-                await copyFile(action.backupPath, action.target);
-            }
-            else {
-                await rm(action.target, { force: true });
-            }
-        }
-        catch {
-            // best effort
-        }
-    }
-}
-async function assertRepoFilesUnchanged(repoRoot, changes, baseHashes) {
-    for (const change of changes) {
-        const target = path.join(repoRoot, change.relativePath);
-        const expected = baseHashes.get(change.relativePath);
-        const exists = existsSync(target);
-        if (expected === null) {
-            if (exists) {
-                throw new Error(TRANSACTIONAL_APPLY_TOCTOU);
-            }
-            continue;
-        }
-        if (!exists) {
-            throw new Error(TRANSACTIONAL_APPLY_TOCTOU);
-        }
-        const current = await hashRepoFile(target);
-        if (current !== expected) {
-            throw new Error(TRANSACTIONAL_APPLY_TOCTOU);
-        }
-    }
-}
 export async function applyWorktreeChanges(worktreePath, repoRoot, changes, options) {
-    if (options?.baseHashes) {
-        await assertRepoFilesUnchanged(repoRoot, changes, options.baseHashes);
-    }
-    const backupRoot = await mkdtemp(path.join(os.tmpdir(), 'belay-tx-rollback-'));
-    const rollbackActions = [];
-    try {
-        for (const change of changes) {
-            const target = path.join(repoRoot, change.relativePath);
-            if (existsSync(target)) {
-                const backupPath = path.join(backupRoot, change.relativePath);
-                await mkdir(path.dirname(backupPath), { recursive: true });
-                await copyFile(target, backupPath);
-                rollbackActions.push({ type: 'restore', target, backupPath });
-            }
-            else if (change.kind !== 'deleted') {
-                rollbackActions.push({ type: 'remove', target });
-            }
-            if (change.kind === 'deleted') {
-                await rm(target, { force: true });
-                continue;
-            }
-            const source = path.join(worktreePath, change.relativePath);
-            await mkdir(path.dirname(target), { recursive: true });
-            await copyFile(source, target);
-        }
-    }
-    catch (error) {
-        await rollbackAppliedChanges(rollbackActions);
-        throw error;
-    }
-    finally {
-        await rm(backupRoot, { recursive: true, force: true });
-    }
+    const observed = options?.observedChanges ??
+        (await buildObservedChangesFromTransactional(repoRoot, worktreePath, changes));
+    await applyObservedChanges({
+        sourceRoot: worktreePath,
+        targetRoot: repoRoot,
+        changes: observed,
+        afterApply: options?.afterApply,
+    });
 }

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

@@ -1,5 +1,16 @@
+export { applyObservedChanges, buildObservedChangesFromTransactional, TRANSACTIONAL_APPLY_CONFLICT, TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU, } from './apply-observed-changes.js';
+export type { TransactionalBackend, TransactionalBackendContext, TransactionalBackendId, TransactionalBackendProbe, TransactionalBackendSelection, TransactionalSnapshot, } from './backend.js';
+export { FILE_CHECKPOINT_DISABLED, FILE_CHECKPOINT_DURABLE_REQUIRED, FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, FILE_CHECKPOINT_NON_GIT_DISABLED, FILE_CHECKPOINT_NOT_IMPLEMENTED, probeTransactionalBackends, selectTransactionalBackend, } from './backend-selector.js';
 export { evaluateTransactionalDiff } from './diff-evaluator.js';
 export { isTransactionalEligible } from './eligibility.js';
+export { FILE_CHECKPOINT_PROTECTED_PATH_CHANGED, fileCheckpointBackend, } from './file-checkpoint-backend.js';
+export { FILE_CHECKPOINT_CWD_OUTSIDE_ROOT, FILE_CHECKPOINT_GIT_METADATA_CHANGED, FILE_CHECKPOINT_SOURCE_CHANGED, FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED, resolveExecutionCwdRelative, } from './file-checkpoint-git.js';
+export { collectDeadOwnerStaging, type FileCheckpointOwnerMarker, isOwnerProcessAlive, removeDeadOwnerStaging, writeOwnerMarker, } from './file-checkpoint-staging.js';
+export { cloneDirectoryTree, type FileCloneResult, type FileCloneStrategy, probeFileCloneStrategy, } from './file-clone.js';
+export { buildFileTreeIndex, diffFileTreeIndices, FileCheckpointDiagnosticError, type FileTreeEntry, type FileTreeIndex, type ObservedFileChange, readObservedChanges, } from './file-tree.js';
+export { compareRelativePathsBytewise, joinRelativePath, validateRelativePath, } from './file-tree-path.js';
+export { gitWorktreeBackend } from './git-worktree-backend.js';
 export { TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, TRANSACTIONAL_OBSERVED_RISK, } from './reasons.js';
 export { runTransactionalExecution } from './runner.js';
+export { hashDirectoryNode, hashFileContent, type PresentSnapshotNode, readSnapshotNode, type SnapshotNode, snapshotNodesEqual, } from './snapshot-node.js';
 export type { TransactionalDiffEvaluation, TransactionalExecutionResult, TransactionalFileChange, TransactionalRunnerParams, } from './types.js';

package/dist/core/transactional/index.js

@@ -1,4 +1,14 @@
+export { applyObservedChanges, buildObservedChangesFromTransactional, TRANSACTIONAL_APPLY_CONFLICT, TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU, } from './apply-observed-changes.js';
+export { FILE_CHECKPOINT_DISABLED, FILE_CHECKPOINT_DURABLE_REQUIRED, FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, FILE_CHECKPOINT_NON_GIT_DISABLED, FILE_CHECKPOINT_NOT_IMPLEMENTED, probeTransactionalBackends, selectTransactionalBackend, } from './backend-selector.js';
 export { evaluateTransactionalDiff } from './diff-evaluator.js';
 export { isTransactionalEligible } from './eligibility.js';
+export { FILE_CHECKPOINT_PROTECTED_PATH_CHANGED, fileCheckpointBackend, } from './file-checkpoint-backend.js';
+export { FILE_CHECKPOINT_CWD_OUTSIDE_ROOT, FILE_CHECKPOINT_GIT_METADATA_CHANGED, FILE_CHECKPOINT_SOURCE_CHANGED, FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED, resolveExecutionCwdRelative, } from './file-checkpoint-git.js';
+export { collectDeadOwnerStaging, isOwnerProcessAlive, removeDeadOwnerStaging, writeOwnerMarker, } from './file-checkpoint-staging.js';
+export { cloneDirectoryTree, probeFileCloneStrategy, } from './file-clone.js';
+export { buildFileTreeIndex, diffFileTreeIndices, FileCheckpointDiagnosticError, readObservedChanges, } from './file-tree.js';
+export { compareRelativePathsBytewise, joinRelativePath, validateRelativePath, } from './file-tree-path.js';
+export { gitWorktreeBackend } from './git-worktree-backend.js';
 export { TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, TRANSACTIONAL_OBSERVED_RISK, } from './reasons.js';
 export { runTransactionalExecution } from './runner.js';
+export { hashDirectoryNode, hashFileContent, readSnapshotNode, snapshotNodesEqual, } from './snapshot-node.js';

package/dist/core/transactional/reasons.js

@@ -9,4 +9,5 @@ export const TRANSACTIONAL_APPROVAL_BYPASS_REASONS = new Set([
     'recovery_substrate_unavailable',
     'recovery_execution_failed',
     'recovery_dirty_worktree',
+    'file_checkpoint_isolation_unavailable',
 ]);

package/dist/core/transactional/runner.js

@@ -1,41 +1,90 @@
 import { boundaryMountReadOnlyFromPrediction, runWithBoundaryRunnable, } from '../capability/boundary-run.js';
 import { hostIntegrationBoundaryContext } from '../capability/boundary-session.js';
+import { resolveGuestWorkdir } from '../capability/boundary-workspace-mount.js';
+import { discardPreparedRecoveryCheckpoint, listRecoveryCheckpoints, markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, prepareRecoveryCheckpoint, reconcileRecoveryCheckpoint, } from '../recovery/checkpoint.js';
+import { buildObservedChangesFromTransactional } from './apply-observed-changes.js';
+import { selectTransactionalBackend } from './backend-selector.js';
 import { evaluateTransactionalDiff } from './diff-evaluator.js';
-import { applyWorktreeChanges, captureRepoFileHashes, collectWorktreeChanges, createGitWorktreeSnapshot, isDirtyWorktree, isGitWorktreeAvailable, resolveWorktreeCwd, TRANSACTIONAL_APPLY_TOCTOU, } from './git-worktree.js';
+import { FileCheckpointDiagnosticError } from './file-tree.js';
+import { applyWorktreeChanges, resolveWorktreeCwd, TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU, } from './git-worktree.js';
 import { TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPLY_FAILED, TRANSACTIONAL_OBSERVED_RISK, } from './reasons.js';
 export async function runTransactionalExecution(params) {
     const { predicted, repoRoot, stateDir, command, cwd, timeoutMs, diffContext } = params;
-    if (!(await isGitWorktreeAvailable(repoRoot))) {
+    const backendContext = {
+        repoRoot,
+        stateDir,
+        cwd,
+        dirtyIgnoreRoots: params.dirtyIgnoreRoots,
+        fileCheckpoint: params.fileCheckpoint,
+        durableCheckpointEnabled: params.checkpoint?.enabled === true,
+        boundaryAttestation: params.boundaryContext?.attestation ?? null,
+        boundaryAttestationFresh: params.boundaryContext?.attestationFresh ?? false,
+        boundaryDriverId: params.boundaryContext?.driverId,
+    };
+    const selection = await selectTransactionalBackend(backendContext);
+    if (!selection.backend) {
+        const skipReason = params.fileCheckpoint.enabled
+            ? (selection.probe.reason ?? selection.skipReason)
+            : (selection.skipReason ?? selection.probe.reason);
         return {
             ok: false,
             skipped: true,
-            skipReason: 'git_worktree_unavailable',
+            skipReason: skipReason ?? 'transactional_execution_failed',
             predicted,
             result: predicted,
         };
     }
-    if (await isDirtyWorktree(repoRoot, { ignoreRoots: params.dirtyIgnoreRoots })) {
-        return {
-            ok: false,
-            skipped: true,
-            skipReason: 'dirty_worktree',
-            predicted,
-            result: predicted,
-        };
+    if (params.checkpoint?.enabled) {
+        try {
+            await listRecoveryCheckpoints(stateDir, repoRoot);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                skipped: true,
+                skipReason: error instanceof Error ? error.message : 'recovery_checkpoint_reconcile_failed',
+                predicted,
+                result: predicted,
+            };
+        }
     }
     let snapshot = null;
     try {
-        snapshot = await createGitWorktreeSnapshot(repoRoot, stateDir);
-        const execCwd = resolveWorktreeCwd(repoRoot, snapshot.worktreePath, cwd);
+        snapshot = await selection.backend.prepare(backendContext);
+        const snapshotAudit = {
+            transactionalBackend: snapshot.backend,
+            resourceKind: snapshot.resourceKind,
+            baselineTreeHash: snapshot.baselineTreeHash,
+            snapshotFileCount: snapshot.snapshotFileCount,
+            snapshotSourceBytes: snapshot.snapshotSourceBytes,
+            snapshotWorkspaceBytes: snapshot.snapshotWorkspaceBytes,
+            snapshotCopyStrategy: snapshot.copyStrategy,
+            snapshotPrepareMs: snapshot.snapshotPrepareMs,
+        };
+        const runOptions = snapshot.backend === 'file_checkpoint' && snapshot.executionCwdRelative !== undefined
+            ? {
+                mountReadOnly: boundaryMountReadOnlyFromPrediction(predicted),
+                workspaceMount: {
+                    hostSourceRoot: snapshot.executionRoot,
+                    guestTargetRoot: snapshot.resourceRoot,
+                    cwdRelative: snapshot.executionCwdRelative,
+                    writable: true,
+                    hideHostSourcePath: true,
+                },
+            }
+            : {
+                mountReadOnly: boundaryMountReadOnlyFromPrediction(predicted),
+            };
+        const execCwd = snapshot.backend === 'file_checkpoint' && runOptions.workspaceMount
+            ? resolveGuestWorkdir(runOptions.workspaceMount)
+            : resolveWorktreeCwd(repoRoot, snapshot.executionRoot, cwd);
         const boundaryContext = params.boundaryContext ?? hostIntegrationBoundaryContext(params.repoRoot);
         const shellResult = await runWithBoundaryRunnable(boundaryContext.driver, {
             prepareContext: boundaryContext.prepareContext,
             command,
             cwd: execCwd,
             timeoutMs,
-            runOptions: {
-                mountReadOnly: boundaryMountReadOnlyFromPrediction(predicted),
-            },
+            runOptions,
         });
         if (shellResult.timedOut) {
             return {
@@ -44,6 +93,7 @@ export async function runTransactionalExecution(params) {
                 skipReason: 'transactional_timed_out',
                 predicted,
                 result: predicted,
+                ...snapshotAudit,
                 commandExitCode: shellResult.exitCode,
                 commandSignal: shellResult.signal,
                 timedOut: true,
@@ -56,19 +106,77 @@ export async function runTransactionalExecution(params) {
                 skipReason: 'transactional_command_failed',
                 predicted,
                 result: predicted,
+                ...snapshotAudit,
                 commandExitCode: shellResult.exitCode,
                 commandSignal: shellResult.signal,
             };
         }
-        const changes = await collectWorktreeChanges(snapshot.worktreePath);
+        const changes = await snapshot.collectChanges();
         const observed = evaluateTransactionalDiff(changes, diffContext);
         if (observed.verdict === 'allow') {
-            const baseHashes = await captureRepoFileHashes(repoRoot, changes);
+            await snapshot.validateSourceState?.();
+            const observedChanges = await buildObservedChangesFromTransactional(snapshot.baselineRoot ?? repoRoot, snapshot.executionRoot, changes);
+            const checkpoint = params.checkpoint?.enabled && changes.length > 0
+                ? await prepareRecoveryCheckpoint({
+                    stateDir,
+                    repoRoot,
+                    baselinePath: snapshot.baselineRoot ?? repoRoot,
+                    worktreePath: snapshot.executionRoot,
+                    commandFingerprint: predicted.fingerprint,
+                    changes,
+                    protectedRoots: diffContext.protectedRoots,
+                    config: params.checkpoint,
+                    backend: snapshot.backend,
+                })
+                : null;
             try {
-                await applyWorktreeChanges(snapshot.worktreePath, repoRoot, changes, { baseHashes });
+                if (checkpoint) {
+                    await markRecoveryCheckpointApplying(stateDir, checkpoint);
+                }
+                let receipt;
+                await applyWorktreeChanges(snapshot.executionRoot, repoRoot, changes, {
+                    observedChanges,
+                    afterApply: checkpoint
+                        ? async () => {
+                            receipt = await markRecoveryCheckpointApplied(stateDir, checkpoint);
+                        }
+                        : undefined,
+                });
+                const result = {
+                    ...predicted,
+                    verdict: 'allow',
+                    reason: TRANSACTIONAL_ALREADY_APPLIED,
+                    assessment: observed.assessment,
+                };
+                return {
+                    ok: true,
+                    predicted,
+                    observed,
+                    result,
+                    worktreePath: snapshot.executionRoot,
+                    ...snapshotAudit,
+                    commandExitCode: shellResult.exitCode,
+                    commandSignal: shellResult.signal,
+                    timedOut: shellResult.timedOut,
+                    ...(checkpoint && receipt
+                        ? {
+                            recoveryCheckpointId: checkpoint.checkpointId,
+                            recoveryBackend: snapshot.backend,
+                            recoveryProofHash: receipt.proofHash,
+                            recoveryState: 'applied',
+                        }
+                        : {}),
+                };
             }
             catch (error) {
+                if (checkpoint) {
+                    const recoveryState = await reconcileRecoveryCheckpoint(stateDir, checkpoint.checkpointId);
+                    if (recoveryState === 'prepared') {
+                        await discardPreparedRecoveryCheckpoint(stateDir, checkpoint.checkpointId);
+                    }
+                }
                 const toctou = error instanceof Error && error.message === TRANSACTIONAL_APPLY_TOCTOU;
+                const rollbackFailed = error instanceof Error && error.message === TRANSACTIONAL_APPLY_ROLLBACK_FAILED;
                 const result = {
                     ...predicted,
                     verdict: 'deny_pending_approval',
@@ -79,7 +187,11 @@ export async function runTransactionalExecution(params) {
                         confidence: 1,
                         signals: [
                             ...observed.assessment.signals,
-                            toctou ? 'transactional_apply_toctou' : 'transactional_apply_failed',
+                            rollbackFailed
+                                ? 'transactional_apply_rollback_failed'
+                                : toctou
+                                    ? 'transactional_apply_toctou'
+                                    : 'transactional_apply_failed',
                         ],
                     },
                 };
@@ -88,7 +200,8 @@ export async function runTransactionalExecution(params) {
                     predicted,
                     observed,
                     result,
-                    worktreePath: snapshot.worktreePath,
+                    worktreePath: snapshot.executionRoot,
+                    ...snapshotAudit,
                     commandExitCode: shellResult.exitCode,
                     commandSignal: shellResult.signal,
                     timedOut: shellResult.timedOut,
@@ -97,8 +210,8 @@ export async function runTransactionalExecution(params) {
         }
         const result = {
             ...predicted,
-            verdict: observed.verdict === 'allow' ? 'allow' : 'deny_pending_approval',
-            reason: observed.verdict === 'allow' ? TRANSACTIONAL_ALREADY_APPLIED : TRANSACTIONAL_OBSERVED_RISK,
+            verdict: 'deny_pending_approval',
+            reason: TRANSACTIONAL_OBSERVED_RISK,
             assessment: observed.assessment,
         };
         return {
@@ -106,7 +219,8 @@ export async function runTransactionalExecution(params) {
             predicted,
             observed,
             result,
-            worktreePath: snapshot.worktreePath,
+            worktreePath: snapshot.executionRoot,
+            ...snapshotAudit,
             commandExitCode: shellResult.exitCode,
             commandSignal: shellResult.signal,
             timedOut: shellResult.timedOut,
@@ -117,13 +231,31 @@ export async function runTransactionalExecution(params) {
             ok: false,
             skipped: true,
             skipReason: error instanceof Error ? error.message : 'transactional_execution_failed',
+            ...(error instanceof FileCheckpointDiagnosticError ? { skipDetail: error.diagnostic } : {}),
             predicted,
             result: predicted,
+            ...(snapshot
+                ? {
+                    transactionalBackend: snapshot.backend,
+                    resourceKind: snapshot.resourceKind,
+                    baselineTreeHash: snapshot.baselineTreeHash,
+                    snapshotFileCount: snapshot.snapshotFileCount,
+                    snapshotSourceBytes: snapshot.snapshotSourceBytes,
+                    snapshotWorkspaceBytes: snapshot.snapshotWorkspaceBytes,
+                    snapshotCopyStrategy: snapshot.copyStrategy,
+                    snapshotPrepareMs: snapshot.snapshotPrepareMs,
+                }
+                : {}),
         };
     }
     finally {
         if (snapshot) {
-            await snapshot.cleanup();
+            try {
+                await snapshot.cleanup();
+            }
+            catch {
+                // Cleanup is best effort and must not overturn a verified apply or observed-risk result.
+            }
         }
     }
 }

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

@@ -0,0 +1,26 @@
+export type SnapshotNode = {
+    kind: 'absent';
+} | {
+    kind: 'file';
+    mode: number;
+    size: number;
+    hash: string;
+} | {
+    kind: 'symlink';
+    target: string;
+    hash: string;
+} | {
+    kind: 'directory';
+    mode: number;
+    hash: string;
+};
+export type PresentSnapshotNode = Exclude<SnapshotNode, {
+    kind: 'absent';
+}>;
+export declare function hashFileContent(filePath: string): Promise<string>;
+export declare function hashSymlinkTarget(target: string): string;
+export declare function hashDirectoryNode(mode: number): string;
+export declare function hashFileNode(mode: number, contentHash: string): string;
+export declare function snapshotNodesEqual(left: SnapshotNode, right: SnapshotNode): boolean;
+export declare function readSnapshotNode(absolutePath: string): Promise<SnapshotNode>;
+export declare function presentNodeKind(node: PresentSnapshotNode): 'file' | 'symlink' | 'directory';

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

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, readlink } from 'node:fs/promises';
+export async function hashFileContent(filePath) {
+    const hash = createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', () => resolve());
+    });
+    return hash.digest('hex');
+}
+export function hashSymlinkTarget(target) {
+    return createHash('sha256').update(`symlink:${target}`).digest('hex');
+}
+export function hashDirectoryNode(mode) {
+    return createHash('sha256')
+        .update(`directory:${mode & 0o777}`)
+        .digest('hex');
+}
+export function hashFileNode(mode, contentHash) {
+    return createHash('sha256')
+        .update(`file:${mode & 0o777}:${contentHash}`)
+        .digest('hex');
+}
+export function snapshotNodesEqual(left, right) {
+    if (left.kind === 'absent' || right.kind === 'absent') {
+        return left.kind === right.kind;
+    }
+    if (left.kind !== right.kind) {
+        return false;
+    }
+    switch (left.kind) {
+        case 'file':
+            return (right.kind === 'file' &&
+                left.mode === right.mode &&
+                left.size === right.size &&
+                left.hash === right.hash);
+        case 'symlink':
+            return right.kind === 'symlink' && left.target === right.target && left.hash === right.hash;
+        case 'directory':
+            return right.kind === 'directory' && left.mode === right.mode && left.hash === right.hash;
+        default:
+            return false;
+    }
+}
+export async function readSnapshotNode(absolutePath) {
+    let info;
+    try {
+        info = await lstat(absolutePath);
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR'].includes(error.code ?? '')) {
+            return { kind: 'absent' };
+        }
+        throw error;
+    }
+    if (info.isSymbolicLink()) {
+        const target = await readlink(absolutePath);
+        return {
+            kind: 'symlink',
+            target,
+            hash: hashSymlinkTarget(target),
+        };
+    }
+    if (info.isFile()) {
+        const contentHash = await hashFileContent(absolutePath);
+        return {
+            kind: 'file',
+            mode: info.mode,
+            size: info.size,
+            hash: hashFileNode(info.mode, contentHash),
+        };
+    }
+    if (info.isDirectory()) {
+        return {
+            kind: 'directory',
+            mode: info.mode,
+            hash: hashDirectoryNode(info.mode),
+        };
+    }
+    throw new Error('file_checkpoint_unsupported_node');
+}
+export function presentNodeKind(node) {
+    return node.kind;
+}

package/dist/core/transactional/types.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedBoundaryDriverContext } from '../capability/boundary-session.js';
+import type { BelayFileCheckpointConfig, BelayTransactionalConfig } from '../config.js';
 import type { Assessment, ClassifyResult, HookVerdict } from '../types.js';
 export type TransactionalFileChangeKind = 'added' | 'modified' | 'deleted';
 export interface TransactionalFileChange {
@@ -18,15 +19,28 @@ export interface TransactionalExecutionResult {
     ok: boolean;
     skipped?: boolean;
     skipReason?: string;
+    skipDetail?: string;
     predicted: ClassifyResult;
     observed?: TransactionalDiffEvaluation;
     result: ClassifyResult;
     worktreePath?: string;
+    transactionalBackend?: 'git_worktree' | 'file_checkpoint';
+    resourceKind?: 'git_repository' | 'directory';
+    baselineTreeHash?: string;
+    snapshotFileCount?: number;
+    snapshotSourceBytes?: number;
+    snapshotWorkspaceBytes?: number;
+    snapshotCopyStrategy?: 'clonefile' | 'reflink' | 'copy';
+    snapshotPrepareMs?: number;
     commandExitCode?: number | null;
     commandSignal?: string | null;
     timedOut?: boolean;
+    recoveryCheckpointId?: string;
+    recoveryBackend?: 'git_worktree' | 'file_checkpoint';
+    recoveryProofHash?: string;
+    recoveryState?: 'applied';
 }
-export interface TransactionalSnapshot {
+export interface GitWorktreeSnapshot {
     worktreePath: string;
     cleanup: () => Promise<void>;
 }
@@ -47,4 +61,6 @@ export interface TransactionalRunnerParams {
     boundaryContext?: ResolvedBoundaryDriverContext;
     /** Repo-local Belay paths excluded from dirty-worktree gating (init artifacts). */
     dirtyIgnoreRoots?: string[];
+    fileCheckpoint: BelayFileCheckpointConfig;
+    checkpoint?: NonNullable<BelayTransactionalConfig['checkpoint']>;
 }