@guilz-dev/belay 0.8.0 → 0.9.0

package/dist/core/transactional/backend-selector.d.ts

@@ -2,7 +2,8 @@ import type { TransactionalBackendContext, TransactionalBackendProbe, Transactio
 export declare const FILE_CHECKPOINT_DISABLED = "file_checkpoint_disabled";
 export declare const FILE_CHECKPOINT_NON_GIT_DISABLED = "file_checkpoint_non_git_disabled";
 export declare const FILE_CHECKPOINT_DURABLE_REQUIRED = "file_checkpoint_durable_checkpoint_required";
-export declare const FILE_CHECKPOINT_ISOLATION_UNAVAILABLE = "file_checkpoint_isolation_unavailable";
+export { FILE_CHECKPOINT_ISOLATION_UNAVAILABLE } from './file-checkpoint-isolation.js';
 export declare const FILE_CHECKPOINT_NOT_IMPLEMENTED = "file_checkpoint_not_implemented";
 export declare function probeTransactionalBackends(context: TransactionalBackendContext): Promise<TransactionalBackendProbe[]>;
+export declare function probeFileCheckpointBackend(context: TransactionalBackendContext): Promise<TransactionalBackendProbe>;
 export declare function selectTransactionalBackend(context: TransactionalBackendContext): Promise<TransactionalBackendSelection>;

package/dist/core/transactional/backend-selector.js

@@ -1,35 +1,21 @@
-import { attestsWorkspaceMountIsolation } from '../capability/attestation.js';
 import { fileCheckpointBackend } from './file-checkpoint-backend.js';
+import { fileCheckpointIsolationReason } from './file-checkpoint-isolation.js';
 import { isDirtyWorktree, isGitWorktreeAvailable } from './git-worktree.js';
 import { gitWorktreeBackend } from './git-worktree-backend.js';
 export const FILE_CHECKPOINT_DISABLED = 'file_checkpoint_disabled';
 export const FILE_CHECKPOINT_NON_GIT_DISABLED = 'file_checkpoint_non_git_disabled';
 export const FILE_CHECKPOINT_DURABLE_REQUIRED = 'file_checkpoint_durable_checkpoint_required';
-export const FILE_CHECKPOINT_ISOLATION_UNAVAILABLE = 'file_checkpoint_isolation_unavailable';
+export { FILE_CHECKPOINT_ISOLATION_UNAVAILABLE } from './file-checkpoint-isolation.js';
 export const FILE_CHECKPOINT_NOT_IMPLEMENTED = 'file_checkpoint_not_implemented';
-function fileCheckpointProbe(reason, signals) {
+function fileCheckpointProbe(reason, signals, resourceKind) {
     return {
         eligible: false,
         backend: 'file_checkpoint',
+        resourceKind,
         reason,
         signals,
     };
 }
-function fileCheckpointIsolationReason(context) {
-    const attestation = context.boundaryAttestation;
-    const fresh = context.boundaryAttestationFresh === true;
-    const driverId = context.boundaryDriverId;
-    if (!attestation || !fresh || !driverId) {
-        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
-    }
-    if (attestation.driver !== driverId) {
-        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
-    }
-    if (!attestsWorkspaceMountIsolation(attestation)) {
-        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
-    }
-    return null;
-}
 export async function probeTransactionalBackends(context) {
     const probes = [await gitWorktreeBackend.probe(context)];
     if (await isGitWorktreeAvailable(context.repoRoot)) {
@@ -40,6 +26,13 @@ export async function probeTransactionalBackends(context) {
     }
     return probes;
 }
+export async function probeFileCheckpointBackend(context) {
+    const probes = await probeTransactionalBackends(context);
+    const probe = probes.find((candidate) => candidate.backend === 'file_checkpoint');
+    if (!probe)
+        throw new Error(FILE_CHECKPOINT_NOT_IMPLEMENTED);
+    return probe;
+}
 async function gitWorkspaceSignals(context) {
     const signals = ['git_repository'];
     if (await isDirtyWorktree(context.repoRoot, { ignoreRoots: context.dirtyIgnoreRoots })) {
@@ -50,14 +43,14 @@ async function gitWorkspaceSignals(context) {
 async function probeFileCheckpointForGit(context) {
     const signals = await gitWorkspaceSignals(context);
     if (!context.fileCheckpoint.enabled) {
-        return fileCheckpointProbe(FILE_CHECKPOINT_DISABLED, signals);
+        return fileCheckpointProbe(FILE_CHECKPOINT_DISABLED, signals, 'git_repository');
     }
     if (!context.durableCheckpointEnabled) {
-        return fileCheckpointProbe(FILE_CHECKPOINT_DURABLE_REQUIRED, signals);
+        return fileCheckpointProbe(FILE_CHECKPOINT_DURABLE_REQUIRED, signals, 'git_repository');
     }
     const isolationReason = fileCheckpointIsolationReason(context);
     if (isolationReason) {
-        return fileCheckpointProbe(isolationReason, [...signals, 'isolation_unavailable']);
+        return fileCheckpointProbe(isolationReason, [...signals, 'isolation_unavailable'], 'git_repository');
     }
     const backendProbe = await fileCheckpointBackend.probe(context);
     if (backendProbe.eligible) {
@@ -66,26 +59,30 @@ async function probeFileCheckpointForGit(context) {
     return fileCheckpointProbe(backendProbe.reason ?? FILE_CHECKPOINT_NOT_IMPLEMENTED, [
         ...signals,
         ...(backendProbe.reason === FILE_CHECKPOINT_NOT_IMPLEMENTED ? ['not_implemented'] : []),
-    ]);
+    ], 'git_repository');
 }
 async function probeFileCheckpointForNonGit(context) {
     if (!context.fileCheckpoint.enabled) {
-        return fileCheckpointProbe(FILE_CHECKPOINT_DISABLED, ['non_git_workspace']);
+        return fileCheckpointProbe(FILE_CHECKPOINT_DISABLED, ['non_git_workspace'], 'directory');
     }
     if (!context.fileCheckpoint.allowNonGit) {
-        return fileCheckpointProbe(FILE_CHECKPOINT_NON_GIT_DISABLED, ['non_git_workspace']);
+        return fileCheckpointProbe(FILE_CHECKPOINT_NON_GIT_DISABLED, ['non_git_workspace'], 'directory');
     }
     if (!context.durableCheckpointEnabled) {
-        return fileCheckpointProbe(FILE_CHECKPOINT_DURABLE_REQUIRED, ['non_git_workspace']);
+        return fileCheckpointProbe(FILE_CHECKPOINT_DURABLE_REQUIRED, ['non_git_workspace'], 'directory');
     }
     const isolationReason = fileCheckpointIsolationReason(context);
     if (isolationReason) {
-        return fileCheckpointProbe(isolationReason, ['non_git_workspace', 'isolation_unavailable']);
+        return fileCheckpointProbe(isolationReason, ['non_git_workspace', 'isolation_unavailable'], 'directory');
     }
-    return fileCheckpointProbe(FILE_CHECKPOINT_NOT_IMPLEMENTED, [
+    const backendProbe = await fileCheckpointBackend.probe(context);
+    if (backendProbe.eligible) {
+        return backendProbe;
+    }
+    return fileCheckpointProbe(backendProbe.reason ?? FILE_CHECKPOINT_NOT_IMPLEMENTED, [
         'non_git_workspace',
-        'not_implemented',
-    ]);
+        ...(backendProbe.reason === FILE_CHECKPOINT_NOT_IMPLEMENTED ? ['not_implemented'] : []),
+    ], 'directory');
 }
 export async function selectTransactionalBackend(context) {
     const gitProbe = await gitWorktreeBackend.probe(context);
@@ -110,6 +107,12 @@ export async function selectTransactionalBackend(context) {
         };
     }
     const fileProbe = await probeFileCheckpointForNonGit(context);
+    if (fileProbe.eligible) {
+        return {
+            backend: fileCheckpointBackend,
+            probe: fileProbe,
+        };
+    }
     return {
         backend: null,
         probe: fileProbe,

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

@@ -5,6 +5,7 @@ export type TransactionalBackendId = 'git_worktree' | 'file_checkpoint';
 export interface TransactionalBackendProbe {
     eligible: boolean;
     backend: TransactionalBackendId;
+    resourceKind: 'git_repository' | 'directory';
     reason?: string;
     signals: string[];
 }
@@ -26,6 +27,8 @@ export interface TransactionalSnapshot {
     executionCwdRelative?: string;
     /** Revalidates the source tree and metadata immediately before apply. */
     validateSourceState?(): Promise<void>;
+    /** Revalidates resource identity immediately before each real mutation. */
+    validateResourceIdentity?(): Promise<void>;
     collectChanges(): Promise<TransactionalFileChange[]>;
     cleanup(): Promise<void>;
 }

package/dist/core/transactional/file-checkpoint-backend.js

@@ -1,37 +1,23 @@
-import { cp, lstat, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { cp, lstat, mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { attestsWorkspaceMountIsolation } from '../capability/attestation.js';
 import { currentRecoveryResourceIdentity } from '../recovery/resource-identity.js';
-import { FILE_CHECKPOINT_DISABLED, FILE_CHECKPOINT_DURABLE_REQUIRED, FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, } from './backend-selector.js';
-import { cloneBareWorktreeCopy, computeGitMetadataFingerprint, copyGitIndexState, execGit, FILE_CHECKPOINT_CWD_OUTSIDE_ROOT, FILE_CHECKPOINT_GIT_METADATA_CHANGED, FILE_CHECKPOINT_PREPARE_FAILED, FILE_CHECKPOINT_SOURCE_CHANGED, removeAllGitRemotes, resolveExecutionCwdRelative, } from './file-checkpoint-git.js';
+import { FILE_CHECKPOINT_DISABLED, FILE_CHECKPOINT_DURABLE_REQUIRED, FILE_CHECKPOINT_NON_GIT_DISABLED, } from './backend-selector.js';
+import { assertRootGitMetadataUnchanged, cloneBareWorktreeCopy, computeGitMetadataFingerprint, copyGitIndexState, execGit, FILE_CHECKPOINT_GIT_METADATA_CHANGED, FILE_CHECKPOINT_PREPARE_FAILED, FILE_CHECKPOINT_SOURCE_CHANGED, removeAllGitRemotes, resolveExecutionCwdRelative, rethrowStableFileCheckpointError, } from './file-checkpoint-git.js';
+import { fileCheckpointIsolationReason } from './file-checkpoint-isolation.js';
 import { removeDeadOwnerStaging, writeOwnerMarker } from './file-checkpoint-staging.js';
 import { cloneDirectoryTree, probeFileCloneStrategy } from './file-clone.js';
 import { buildFileTreeIndex, diffFileTreeIndices, FILE_CHECKPOINT_PREPARE_TIMEOUT, FILE_CHECKPOINT_QUOTA_EXCEEDED, FileCheckpointDiagnosticError, } from './file-tree.js';
 import { isDirtyWorktree, isGitWorktreeAvailable } from './git-worktree.js';
 import { readSnapshotNode } from './snapshot-node.js';
 export const FILE_CHECKPOINT_PROTECTED_PATH_CHANGED = 'file_checkpoint_protected_path_changed';
-function fileCheckpointIsolationReason(context) {
-    const attestation = context.boundaryAttestation;
-    const fresh = context.boundaryAttestationFresh === true;
-    const driverId = context.boundaryDriverId;
-    if (!attestation || !fresh || !driverId) {
-        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
-    }
-    if (attestation.driver !== driverId) {
-        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
-    }
-    if (!attestsWorkspaceMountIsolation(attestation)) {
-        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
-    }
-    return null;
-}
 async function probeDirtyGitFileCheckpoint(context) {
     const signals = ['git_repository', 'dirty_git_worktree'];
     if (!(await isGitWorktreeAvailable(context.repoRoot))) {
         return {
             eligible: false,
             backend: 'file_checkpoint',
+            resourceKind: 'git_repository',
             reason: 'git_worktree_unavailable',
             signals: ['git_repository'],
         };
@@ -40,6 +26,7 @@ async function probeDirtyGitFileCheckpoint(context) {
         return {
             eligible: false,
             backend: 'file_checkpoint',
+            resourceKind: 'git_repository',
             reason: 'clean_git_worktree',
             signals: ['git_repository', 'clean_git_worktree'],
         };
@@ -48,6 +35,7 @@ async function probeDirtyGitFileCheckpoint(context) {
         return {
             eligible: false,
             backend: 'file_checkpoint',
+            resourceKind: 'git_repository',
             reason: FILE_CHECKPOINT_DISABLED,
             signals,
         };
@@ -56,6 +44,7 @@ async function probeDirtyGitFileCheckpoint(context) {
         return {
             eligible: false,
             backend: 'file_checkpoint',
+            resourceKind: 'git_repository',
             reason: FILE_CHECKPOINT_DURABLE_REQUIRED,
             signals,
         };
@@ -65,6 +54,7 @@ async function probeDirtyGitFileCheckpoint(context) {
         return {
             eligible: false,
             backend: 'file_checkpoint',
+            resourceKind: 'git_repository',
             reason: isolationReason,
             signals: [...signals, 'isolation_unavailable'],
         };
@@ -73,9 +63,66 @@ async function probeDirtyGitFileCheckpoint(context) {
     return {
         eligible: true,
         backend: 'file_checkpoint',
+        resourceKind: 'git_repository',
         signals: [...signals, 'dirty_git_file_checkpoint', copyStrategy],
     };
 }
+async function probeNonGitFileCheckpoint(context) {
+    const signals = ['non_git_workspace'];
+    if (await isGitWorktreeAvailable(context.repoRoot)) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            resourceKind: 'directory',
+            reason: 'git_worktree_available',
+            signals: ['git_repository'],
+        };
+    }
+    if (!context.fileCheckpoint.enabled) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            resourceKind: 'directory',
+            reason: FILE_CHECKPOINT_DISABLED,
+            signals,
+        };
+    }
+    if (!context.fileCheckpoint.allowNonGit) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            resourceKind: 'directory',
+            reason: FILE_CHECKPOINT_NON_GIT_DISABLED,
+            signals,
+        };
+    }
+    if (!context.durableCheckpointEnabled) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            resourceKind: 'directory',
+            reason: FILE_CHECKPOINT_DURABLE_REQUIRED,
+            signals,
+        };
+    }
+    const isolationReason = fileCheckpointIsolationReason(context);
+    if (isolationReason) {
+        return {
+            eligible: false,
+            backend: 'file_checkpoint',
+            resourceKind: 'directory',
+            reason: isolationReason,
+            signals: [...signals, 'isolation_unavailable'],
+        };
+    }
+    const copyStrategy = await probeFileCloneStrategy();
+    return {
+        eligible: true,
+        backend: 'file_checkpoint',
+        resourceKind: 'directory',
+        signals: [...signals, 'non_git_file_checkpoint', copyStrategy],
+    };
+}
 async function protectedRootState(root) {
     const node = await readSnapshotNode(root);
     if (node.kind !== 'directory') {
@@ -163,6 +210,9 @@ async function prepareDirtyGitSnapshot(context) {
             quotas,
             deadlineMs,
         });
+        if (sourceIndex.treeHash !== baselineCopy.sourceIndex.treeHash) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+        }
         if (sourceIndex.treeHash !== baselineIndex.treeHash) {
             throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
         }
@@ -200,35 +250,190 @@ async function prepareDirtyGitSnapshot(context) {
         if (error instanceof FileCheckpointDiagnosticError) {
             throw error;
         }
-        if (error instanceof Error && error.message === FILE_CHECKPOINT_CWD_OUTSIDE_ROOT) {
-            throw error;
+        rethrowStableFileCheckpointError(error);
+    }
+}
+async function prepareNonGitSnapshot(context) {
+    const prepareStartedAt = Date.now();
+    const excludedRoots = context.dirtyIgnoreRoots ?? [];
+    const quotas = context.fileCheckpoint;
+    const deadlineMs = Date.now() + quotas.prepareTimeoutMs;
+    await removeDeadOwnerStaging(os.tmpdir());
+    const stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'belay-file-checkpoint-'));
+    await writeOwnerMarker(stagingRoot, {
+        version: 1,
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        resourceRoot: context.repoRoot,
+        backend: 'file_checkpoint',
+    });
+    const baselineRoot = path.join(stagingRoot, 'baseline');
+    const executionRoot = path.join(stagingRoot, 'execution');
+    try {
+        resolveExecutionCwdRelative(context.repoRoot, context.cwd);
+        const resourceIdentity = await currentRecoveryResourceIdentity(context.repoRoot, 'directory');
+        const baselineCopy = await cloneDirectoryTree(context.repoRoot, baselineRoot, {
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        await mkdir(baselineRoot, { recursive: true });
+        const baselineIndex = await buildFileTreeIndex({
+            resourceRoot: baselineRoot,
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        const sourceIndex = await buildFileTreeIndex({
+            resourceRoot: context.repoRoot,
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        if (sourceIndex.treeHash !== baselineCopy.sourceIndex.treeHash) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
         }
-        if (error instanceof Error && error.message === FILE_CHECKPOINT_SOURCE_CHANGED) {
-            throw error;
+        if (sourceIndex.treeHash !== baselineIndex.treeHash) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
         }
-        throw new Error(error instanceof Error ? error.message : FILE_CHECKPOINT_PREPARE_FAILED, {
-            cause: error,
+        await writeFile(path.join(stagingRoot, 'baseline-index.json'), `${JSON.stringify(baselineIndex)}\n`, 'utf8');
+        const executionCopy = await cloneDirectoryTree(baselineRoot, executionRoot, {
+            excludedRoots,
+            quotas,
+            deadlineMs,
         });
+        await mkdir(executionRoot, { recursive: true });
+        const finalSourceIndex = await buildFileTreeIndex({
+            resourceRoot: context.repoRoot,
+            excludedRoots,
+            quotas,
+            deadlineMs,
+        });
+        if (finalSourceIndex.treeHash !== baselineIndex.treeHash) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+        }
+        if ((await currentRecoveryResourceIdentity(context.repoRoot, 'directory')) !== resourceIdentity) {
+            throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+        }
+        const protectedRootStates = await captureProtectedRootStates(context.repoRoot, executionRoot, excludedRoots);
+        const workspaceBytes = await directoryByteSize(stagingRoot, deadlineMs);
+        if (workspaceBytes > quotas.maxWorkspaceBytes) {
+            throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_QUOTA_EXCEEDED, `snapshot workspaceBytes=${workspaceBytes} exceeds maxWorkspaceBytes=${quotas.maxWorkspaceBytes}`);
+        }
+        return {
+            stagingRoot,
+            baselineRoot,
+            executionRoot,
+            baselineIndex,
+            resourceIdentity,
+            copyStrategy: executionCopy.strategy === baselineCopy.strategy ? executionCopy.strategy : 'copy',
+            workspaceBytes,
+            prepareMs: Date.now() - prepareStartedAt,
+            protectedRootStates,
+        };
+    }
+    catch (error) {
+        await rm(stagingRoot, { recursive: true, force: true });
+        if (error instanceof FileCheckpointDiagnosticError) {
+            throw error;
+        }
+        rethrowStableFileCheckpointError(error);
     }
 }
+function collectObservedChanges(prepared, context) {
+    return async () => {
+        for (const [protectedRoot, before] of prepared.protectedRootStates) {
+            if ((await protectedRootState(protectedRoot)) !== before) {
+                throw new Error(FILE_CHECKPOINT_PROTECTED_PATH_CHANGED);
+            }
+        }
+        const executionIndex = await buildFileTreeIndex({
+            resourceRoot: prepared.executionRoot,
+            excludedRoots: context.dirtyIgnoreRoots ?? [],
+            quotas: context.fileCheckpoint,
+        });
+        const observed = diffFileTreeIndices(prepared.baselineIndex, executionIndex);
+        return observed.map((change) => ({
+            relativePath: change.relativePath,
+            kind: change.kind,
+        }));
+    };
+}
 export const fileCheckpointBackend = {
     id: 'file_checkpoint',
-    probe: probeDirtyGitFileCheckpoint,
+    async probe(context) {
+        if (await isGitWorktreeAvailable(context.repoRoot)) {
+            return probeDirtyGitFileCheckpoint(context);
+        }
+        return probeNonGitFileCheckpoint(context);
+    },
     async prepare(context) {
-        const probe = await probeDirtyGitFileCheckpoint(context);
+        if (await isGitWorktreeAvailable(context.repoRoot)) {
+            const probe = await probeDirtyGitFileCheckpoint(context);
+            if (!probe.eligible) {
+                throw new Error(probe.reason ?? FILE_CHECKPOINT_PREPARE_FAILED);
+            }
+            const prepared = await prepareDirtyGitSnapshot(context);
+            const executionCwdRelative = resolveExecutionCwdRelative(context.repoRoot, context.cwd);
+            const resourceIdentity = await currentRecoveryResourceIdentity(context.repoRoot, 'git_repository');
+            return {
+                backend: 'file_checkpoint',
+                resourceRoot: context.repoRoot,
+                executionRoot: prepared.executionRoot,
+                baselineRoot: prepared.baselineRoot,
+                resourceKind: 'git_repository',
+                resourceIdentity,
+                baselineTreeHash: prepared.baselineIndex.treeHash,
+                excludedRoots: context.dirtyIgnoreRoots ?? [],
+                copyStrategy: prepared.copyStrategy,
+                snapshotFileCount: prepared.baselineIndex.fileCount,
+                snapshotSourceBytes: prepared.baselineIndex.totalFileBytes,
+                snapshotWorkspaceBytes: prepared.workspaceBytes,
+                snapshotPrepareMs: prepared.prepareMs,
+                executionCwdRelative,
+                async validateSourceState() {
+                    const sourceIndex = await buildFileTreeIndex({
+                        resourceRoot: context.repoRoot,
+                        excludedRoots: context.dirtyIgnoreRoots ?? [],
+                        quotas: context.fileCheckpoint,
+                    });
+                    if (sourceIndex.treeHash !== prepared.baselineIndex.treeHash ||
+                        (await computeGitMetadataFingerprint(context.repoRoot)) !==
+                            prepared.sourceGitMetadataFingerprint) {
+                        throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+                    }
+                },
+                async collectChanges() {
+                    const afterFingerprint = await computeGitMetadataFingerprint(prepared.executionRoot);
+                    if (afterFingerprint !== prepared.gitMetadataFingerprint) {
+                        throw new Error(FILE_CHECKPOINT_GIT_METADATA_CHANGED);
+                    }
+                    return collectObservedChanges(prepared, context)();
+                },
+                async cleanup() {
+                    await rm(prepared.stagingRoot, { recursive: true, force: true });
+                },
+            };
+        }
+        const probe = await probeNonGitFileCheckpoint(context);
         if (!probe.eligible) {
             throw new Error(probe.reason ?? FILE_CHECKPOINT_PREPARE_FAILED);
         }
-        const prepared = await prepareDirtyGitSnapshot(context);
+        const prepared = await prepareNonGitSnapshot(context);
         const executionCwdRelative = resolveExecutionCwdRelative(context.repoRoot, context.cwd);
-        const resourceIdentity = await currentRecoveryResourceIdentity(context.repoRoot, 'git_repository');
+        const validateResourceIdentity = async () => {
+            if ((await currentRecoveryResourceIdentity(context.repoRoot, 'directory')) !==
+                prepared.resourceIdentity) {
+                throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
+            }
+        };
         return {
             backend: 'file_checkpoint',
             resourceRoot: context.repoRoot,
             executionRoot: prepared.executionRoot,
             baselineRoot: prepared.baselineRoot,
-            resourceKind: 'git_repository',
-            resourceIdentity,
+            resourceKind: 'directory',
+            resourceIdentity: prepared.resourceIdentity,
             baselineTreeHash: prepared.baselineIndex.treeHash,
             excludedRoots: context.dirtyIgnoreRoots ?? [],
             copyStrategy: prepared.copyStrategy,
@@ -243,32 +448,15 @@ export const fileCheckpointBackend = {
                     excludedRoots: context.dirtyIgnoreRoots ?? [],
                     quotas: context.fileCheckpoint,
                 });
-                if (sourceIndex.treeHash !== prepared.baselineIndex.treeHash ||
-                    (await computeGitMetadataFingerprint(context.repoRoot)) !==
-                        prepared.sourceGitMetadataFingerprint) {
+                if (sourceIndex.treeHash !== prepared.baselineIndex.treeHash) {
                     throw new Error(FILE_CHECKPOINT_SOURCE_CHANGED);
                 }
+                await validateResourceIdentity();
             },
-            async collectChanges() {
-                const afterFingerprint = await computeGitMetadataFingerprint(prepared.executionRoot);
-                if (afterFingerprint !== prepared.gitMetadataFingerprint) {
-                    throw new Error(FILE_CHECKPOINT_GIT_METADATA_CHANGED);
-                }
-                for (const [protectedRoot, before] of prepared.protectedRootStates) {
-                    if ((await protectedRootState(protectedRoot)) !== before) {
-                        throw new Error(FILE_CHECKPOINT_PROTECTED_PATH_CHANGED);
-                    }
-                }
-                const executionIndex = await buildFileTreeIndex({
-                    resourceRoot: prepared.executionRoot,
-                    excludedRoots: context.dirtyIgnoreRoots ?? [],
-                    quotas: context.fileCheckpoint,
-                });
-                const observed = diffFileTreeIndices(prepared.baselineIndex, executionIndex);
-                return observed.map((change) => ({
-                    relativePath: change.relativePath,
-                    kind: change.kind,
-                }));
+            validateResourceIdentity,
+            collectChanges: async () => {
+                await assertRootGitMetadataUnchanged(prepared.baselineRoot, prepared.executionRoot);
+                return collectObservedChanges(prepared, context)();
             },
             async cleanup() {
                 await rm(prepared.stagingRoot, { recursive: true, force: true });

package/dist/core/transactional/file-checkpoint-git.d.ts

@@ -3,6 +3,9 @@ export declare const FILE_CHECKPOINT_SOURCE_CHANGED = "file_checkpoint_source_ch
 export declare const FILE_CHECKPOINT_CWD_OUTSIDE_ROOT = "file_checkpoint_cwd_outside_root";
 export declare const FILE_CHECKPOINT_PREPARE_FAILED = "file_checkpoint_prepare_failed";
 export declare const FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED = "file_checkpoint_split_index_unsupported";
+export declare function rethrowStableFileCheckpointError(error: unknown): never;
+export declare function rootGitMetadataPresent(repoRoot: string): Promise<boolean>;
+export declare function assertRootGitMetadataUnchanged(baselineRoot: string, executionRoot: string): Promise<void>;
 export declare function execGit(repoRoot: string, args: string[]): Promise<string>;
 export declare function cloneBareWorktreeCopy(sourceRoot: string, destinationRoot: string): Promise<void>;
 export declare function removeAllGitRemotes(repoRoot: string): Promise<void>;

package/dist/core/transactional/file-checkpoint-git.js

@@ -8,6 +8,59 @@ export const FILE_CHECKPOINT_SOURCE_CHANGED = 'file_checkpoint_source_changed';
 export const FILE_CHECKPOINT_CWD_OUTSIDE_ROOT = 'file_checkpoint_cwd_outside_root';
 export const FILE_CHECKPOINT_PREPARE_FAILED = 'file_checkpoint_prepare_failed';
 export const FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED = 'file_checkpoint_split_index_unsupported';
+const STABLE_FILE_CHECKPOINT_ERRORS = new Set([
+    FILE_CHECKPOINT_GIT_METADATA_CHANGED,
+    FILE_CHECKPOINT_SOURCE_CHANGED,
+    FILE_CHECKPOINT_CWD_OUTSIDE_ROOT,
+    FILE_CHECKPOINT_PREPARE_FAILED,
+    FILE_CHECKPOINT_SPLIT_INDEX_UNSUPPORTED,
+    'file_checkpoint_disabled',
+    'file_checkpoint_non_git_disabled',
+    'file_checkpoint_durable_checkpoint_required',
+    'file_checkpoint_isolation_unavailable',
+    'file_checkpoint_not_implemented',
+    'file_checkpoint_nested_repository',
+    'file_checkpoint_unsupported_node',
+    'file_checkpoint_hardlink_unsupported',
+    'file_checkpoint_quota_exceeded',
+    'file_checkpoint_prepare_timeout',
+    'file_checkpoint_copy_failed',
+    'file_checkpoint_protected_path_changed',
+    'file_checkpoint_path_escape',
+]);
+export function rethrowStableFileCheckpointError(error) {
+    if (error instanceof Error && STABLE_FILE_CHECKPOINT_ERRORS.has(error.message)) {
+        throw error;
+    }
+    throw new Error(FILE_CHECKPOINT_PREPARE_FAILED, { cause: error });
+}
+export async function rootGitMetadataPresent(repoRoot) {
+    try {
+        await lstat(path.join(repoRoot, '.git'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function assertRootGitMetadataUnchanged(baselineRoot, executionRoot) {
+    const [baselinePresent, executionPresent] = await Promise.all([
+        rootGitMetadataPresent(baselineRoot),
+        rootGitMetadataPresent(executionRoot),
+    ]);
+    if (baselinePresent !== executionPresent) {
+        throw new Error(FILE_CHECKPOINT_GIT_METADATA_CHANGED);
+    }
+    if (executionPresent) {
+        const [baselineFingerprint, executionFingerprint] = await Promise.all([
+            computeGitMetadataFingerprint(baselineRoot),
+            computeGitMetadataFingerprint(executionRoot),
+        ]);
+        if (baselineFingerprint !== executionFingerprint) {
+            throw new Error(FILE_CHECKPOINT_GIT_METADATA_CHANGED);
+        }
+    }
+}
 export function execGit(repoRoot, args) {
     return new Promise((resolve, reject) => {
         const child = spawn('git', ['-C', repoRoot, ...args], {

package/dist/core/transactional/file-checkpoint-isolation.d.ts

@@ -0,0 +1,3 @@
+import type { TransactionalBackendContext } from './backend.js';
+export declare const FILE_CHECKPOINT_ISOLATION_UNAVAILABLE = "file_checkpoint_isolation_unavailable";
+export declare function fileCheckpointIsolationReason(context: TransactionalBackendContext): string | null;

package/dist/core/transactional/file-checkpoint-isolation.js

@@ -0,0 +1,16 @@
+import { attestsWorkspaceMountIsolation, isAttestationCurrent } from '../capability/attestation.js';
+export const FILE_CHECKPOINT_ISOLATION_UNAVAILABLE = 'file_checkpoint_isolation_unavailable';
+export function fileCheckpointIsolationReason(context) {
+    const attestation = context.boundaryAttestation;
+    const driverId = context.boundaryDriverId;
+    if (!attestation || !isAttestationCurrent(attestation) || !driverId) {
+        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
+    }
+    if (attestation.driver !== driverId) {
+        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
+    }
+    if (!attestsWorkspaceMountIsolation(attestation)) {
+        return FILE_CHECKPOINT_ISOLATION_UNAVAILABLE;
+    }
+    return null;
+}

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

@@ -4,6 +4,7 @@ async function probeGitWorktreeBackend(context) {
         return {
             eligible: false,
             backend: 'git_worktree',
+            resourceKind: 'git_repository',
             reason: 'git_worktree_unavailable',
             signals: [],
         };
@@ -12,6 +13,7 @@ async function probeGitWorktreeBackend(context) {
         return {
             eligible: false,
             backend: 'git_worktree',
+            resourceKind: 'git_repository',
             reason: 'dirty_worktree',
             signals: ['dirty_git_worktree'],
         };
@@ -19,6 +21,7 @@ async function probeGitWorktreeBackend(context) {
     return {
         eligible: true,
         backend: 'git_worktree',
+        resourceKind: 'git_repository',
         signals: ['clean_git_worktree'],
     };
 }

package/dist/core/transactional/git-worktree.d.ts

@@ -15,4 +15,5 @@ export declare function applyWorktreeChanges(worktreePath: string, repoRoot: str
     /** Runs while rollback backups are still available. */
     afterApply?: () => Promise<void>;
     observedChanges?: Awaited<ReturnType<typeof buildObservedChangesFromTransactional>>;
+    beforeMutation?: () => Promise<void>;
 }): Promise<void>;