@anionex/dsh-turn-rewind 0.3.4 → 0.3.5

package/lib/engine.js

@@ -7,6 +7,7 @@ import { ChangeLedgerError, errorMessage } from './errors.js';
 import { ensureGitWorktreeIdentity, resolveGitWorktreeRoot } from './git.js';
 import { captureGitTurnCheckpoint, deleteGitCheckpoint, deleteGitCheckpointRef, publishGitCheckpoint, readGitBlob, verifyGitCheckpoint, } from './git-checkpoint.js';
 import { assertSafeParents, ensureSafeParents, expandHome, isNodeError, isWithin, pruneEmptyParents, removeRestoreTarget, replaceRegularFile, replaceSymbolicLink, resolveWorkspacePath, validateRelativePath, } from './path-utils.js';
+import { readPathCache, writePathCache } from './path-cache.js';
 import { captureSnapshotEntry, captureStableTree, diffTrees, entriesEqual } from './snapshot.js';
 import { LedgerStore } from './store.js';
 import { discoverWorkspace, discoverWorkspaceIdentity, sameWorkspaceFence } from './workspace.js';
@@ -15,7 +16,7 @@ const DEFAULTS = {
     maxRestorePoints: 50,
     maxTurnCheckpointsPerSession: 30,
     maxFiles: 20_000,
-    maxFileBytes: 16 * 1024 * 1024,
+    maxFileBytes: 64 * 1024 * 1024,
     maxSnapshotBytes: 512 * 1024 * 1024,
     planTtlMs: 15 * 60 * 1_000,
     staleLockMs: 30_000,
@@ -66,6 +67,21 @@ export class ChangeLedgerEngine {
      * A Git worktree also binds the shared per-worktree lock derived from its Git
      * identity; an ordinary directory owns only the durable directory lock.
      */
+    /** Per-workspace path identity caches, loaded once per process generation. */
+    pathCaches = new Map();
+    /**
+     * Load (once) the identity cache that lets a capture reuse unchanged files.
+     * @param workspaceDir - durable directory of one workspace.
+     * @returns the mutable cache shared by every capture of this workspace.
+     */
+    async pathCacheFor(workspaceDir) {
+        const loaded = this.pathCaches.get(workspaceDir);
+        if (loaded !== undefined)
+            return loaded;
+        const cache = await readPathCache(workspaceDir);
+        this.pathCaches.set(workspaceDir, cache);
+        return cache;
+    }
     async acquireWorkspace(workspace, signal) {
         if (workspace.type === 'directory') {
             return this.store.acquire(workspace.root, undefined, undefined, signal);
@@ -401,6 +417,8 @@ export class ChangeLedgerEngine {
             const current = await captureStableTree({
                 cwd: source.state.root,
                 config: this.config,
+                store: this.store,
+                pathCache: await this.pathCacheFor(this.store.workspaceDirectory(source.state.root)),
                 ...(manifest.version === 2 ? { gitObjectFormat: manifest.git.objectFormat } : {}),
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
@@ -439,6 +457,8 @@ export class ChangeLedgerEngine {
             const current = await captureStableTree({
                 cwd: source.state.root,
                 config: this.config,
+                store: this.store,
+                pathCache: await this.pathCacheFor(this.store.workspaceDirectory(source.state.root)),
                 ...(manifest.version === 2 ? { gitObjectFormat: manifest.git.objectFormat } : {}),
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
@@ -799,12 +819,16 @@ export class ChangeLedgerEngine {
             await this.store.writeSnapshotCleanup(options.cwd);
         }
         try {
+            const workspaceDir = this.store.workspaceDirectory(options.cwd);
+            const pathCache = await this.pathCacheFor(workspaceDir);
             const tree = await captureStableTree({
                 cwd: options.cwd,
                 config: this.config,
                 store: this.store,
+                pathCache,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
+            await writePathCache(workspaceDir, pathCache).catch(() => undefined);
             const manifest = {
                 version: LEDGER_FORMAT_VERSION,
                 id: makeId('rp'),

package/lib/path-cache.js

@@ -0,0 +1,137 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isNodeError, pathExists, writeJsonAtomic } from './path-utils.js';
+const CACHE_FILE = 'path-cache.json';
+const CACHE_VERSION = 1;
+const MAX_ENTRIES = 200_000;
+const MAX_FILE_BYTES = 64 * 1024 * 1024;
+/** Stable identity string for one observed filesystem object. */
+export function pathCacheKey(info) {
+    return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}:${info.mode.toString()}`;
+}
+/** Remember what one unknown does not already describe. */
+export function toPathCacheEntry(info, entry) {
+    return {
+        dev: info.dev.toString(),
+        ino: info.ino.toString(),
+        size: info.size.toString(),
+        mtimeNs: info.mtimeNs.toString(),
+        ctimeNs: info.ctimeNs.toString(),
+        mode: Number(info.mode & 511n),
+        entry,
+    };
+}
+/** Whether a cached record still describes the object the filesystem reports now. */
+export function matchesPathCache(record, info) {
+    return record.dev === info.dev.toString()
+        && record.ino === info.ino.toString()
+        && record.size === info.size.toString()
+        && record.mtimeNs === info.mtimeNs.toString()
+        && record.ctimeNs === info.ctimeNs.toString()
+        && record.mode === Number(info.mode & 511n);
+}
+/**
+ * Read the per-workspace path cache.
+ *
+ * The cache is a pure optimization: any malformed or unreadable record is
+ * discarded instead of trusted, and a discarded cache only costs a cold capture.
+ * @param workspaceDir - durable directory of one workspace.
+ * @returns the cached records, newest read wins.
+ */
+export async function readPathCache(workspaceDir) {
+    const cache = new Map();
+    let raw;
+    try {
+        raw = await readFile(join(workspaceDir, CACHE_FILE), 'utf8');
+    }
+    catch (error) {
+        if (isNodeError(error, 'ENOENT'))
+            return cache;
+        return cache;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return cache;
+        const record = parsed;
+        if (record.version !== CACHE_VERSION || record.paths === null || typeof record.paths !== 'object')
+            return cache;
+        for (const [path, value] of Object.entries(record.paths)) {
+            const entry = parseCacheEntry(value);
+            if (entry === undefined)
+                continue;
+            cache.set(path, entry);
+            if (cache.size >= MAX_ENTRIES)
+                break;
+        }
+    }
+    catch {
+        return new Map();
+    }
+    return cache;
+}
+/** Persist the path cache atomically, replacing any previous generation. */
+export async function writePathCache(workspaceDir, cache) {
+    const paths = Object.create(null);
+    let count = 0;
+    for (const [path, entry] of cache) {
+        if (count >= MAX_ENTRIES)
+            break;
+        paths[path] = serializeCacheEntry(entry);
+        count += 1;
+    }
+    await writeJsonAtomic(join(workspaceDir, CACHE_FILE), { version: CACHE_VERSION, paths });
+}
+/** Drop the cache when its file is unreadable or was never written. */
+export async function pathCacheExists(workspaceDir) {
+    return pathExists(join(workspaceDir, CACHE_FILE));
+}
+function serializeCacheEntry(record) {
+    const entry = record.entry;
+    return {
+        dev: record.dev, ino: record.ino, size: record.size,
+        mtimeNs: record.mtimeNs, ctimeNs: record.ctimeNs, mode: record.mode,
+        kind: entry.kind,
+        ...(entry.kind === 'file' ? { blob: entry.blob, provider: entry.provider } : { target: entry.target }),
+    };
+}
+function parseCacheEntry(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const text = (key) => (typeof record[key] === 'string' ? record[key] : undefined);
+    const dev = text('dev');
+    const ino = text('ino');
+    const size = text('size');
+    const mtimeNs = text('mtimeNs');
+    const ctimeNs = text('ctimeNs');
+    if (dev === undefined || ino === undefined || size === undefined || mtimeNs === undefined || ctimeNs === undefined)
+        return undefined;
+    if (typeof record.mode !== 'number' || !Number.isInteger(record.mode))
+        return undefined;
+    let entry;
+    if (record.kind === 'file') {
+        const blob = text('blob');
+        if (blob === undefined || !/^[0-9a-f]{64}$/.test(blob))
+            return undefined;
+        const provider = record.provider;
+        if (provider !== undefined && provider !== 'git')
+            return undefined;
+        entry = {
+            kind: 'file', blob, size: Number(size), mode: record.mode,
+            ...(provider === undefined ? {} : { provider }),
+        };
+    }
+    else if (record.kind === 'symlink') {
+        const target = text('target');
+        if (target === undefined || target.includes('\0'))
+            return undefined;
+        entry = { kind: 'symlink', target, mode: record.mode };
+    }
+    else {
+        return undefined;
+    }
+    if (BigInt(size) > BigInt(MAX_FILE_BYTES))
+        return undefined;
+    return { dev, ino, size, mtimeNs, ctimeNs, mode: record.mode, entry };
+}

package/lib/snapshot.js

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import { lstat, open, readlink } from 'node:fs/promises';
 import { ChangeLedgerError } from './errors.js';
 import { isNodeError, resolveWorkspacePath } from './path-utils.js';
+import { matchesPathCache, toPathCacheEntry } from './path-cache.js';
 import { discoverWorkspace, sameWorkspaceFence } from './workspace.js';
 const COMPARISON_READ_BUDGET_BYTES = 128 * 1024 * 1024;
 const MAX_RECORDED_SKIPS = 50;
@@ -42,6 +43,31 @@ export async function captureTree(options) {
     let budgetSpent = false;
     const capturePath = async (path) => {
         throwIfAborted(options.signal);
+        // Reuse is only sound when the identity is unchanged and the stored blob is
+        // still present; a garbage-collected blob falls back to a fresh read.
+        if (options.pathCache !== undefined && options.store !== undefined && gitCapture === undefined) {
+            const cached = options.pathCache.get(path);
+            if (cached !== undefined) {
+                let info;
+                try {
+                    info = await lstat(resolveWorkspacePath(source.state.root, path), { bigint: true });
+                }
+                catch (error) {
+                    if (!isNodeError(error, 'ENOENT'))
+                        throw error;
+                }
+                if (info !== undefined && matchesPathCache(cached, info)) {
+                    const reusable = cached.entry.kind === 'symlink'
+                        || await options.store.hasBlob(source.state.root, cached.entry.blob);
+                    if (reusable) {
+                        entries[path] = cached.entry;
+                        if (cached.entry.kind === 'file')
+                            totalBytes += cached.entry.size;
+                        return;
+                    }
+                }
+            }
+        }
         if (budgetSpent) {
             // The aggregate budget is gone, but the path is still recorded so a
             // restore can prove this point never observed it.
@@ -85,6 +111,9 @@ export async function captureTree(options) {
         entries[path] = entry.snapshot;
         if (gitCapture !== undefined)
             gitCapture.entries[path] = entry.snapshot;
+        if (options.pathCache !== undefined && gitCapture === undefined) {
+            options.pathCache.set(path, toPathCacheEntry(entry.info, entry.snapshot));
+        }
     };
     {
         // Reading one file at a time makes a real project directory take minutes, so
@@ -139,6 +168,8 @@ export async function captureStableTree(options) {
         const first = await captureTree({
             cwd: options.cwd,
             config: options.config,
+            ...(options.store === undefined ? {} : { store: options.store }),
+            ...(options.pathCache === undefined ? {} : { pathCache: options.pathCache }),
             ...(options.gitObjectFormat === undefined ? {} : { gitObjectFormat: options.gitObjectFormat }),
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
@@ -263,7 +294,7 @@ async function captureEntry(root, path, maxFileBytes, signal) {
             const after = await lstat(target, { bigint: true });
             if (!sameStat(before, after))
                 continue;
-            return { kind: 'symlink', snapshot: { kind: 'symlink', target: linkTarget, mode } };
+            return { kind: 'symlink', snapshot: { kind: 'symlink', target: linkTarget, mode }, info: after };
         }
         if (!before.isFile()) {
             throw new ChangeLedgerError('UNSUPPORTED_FILE_TYPE', `eligible path is not a regular file or symlink: ${JSON.stringify(path)}`);
@@ -299,6 +330,7 @@ async function captureEntry(root, path, maxFileBytes, signal) {
             kind: 'file',
             snapshot: { kind: 'file', blob, size: content.length, mode },
             content,
+            info: { ...before, size: BigInt(content.length) },
         };
     }
     throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `path changed repeatedly while being captured: ${JSON.stringify(path)}`);

package/lib/store.js

@@ -173,6 +173,15 @@ export class LedgerStore {
         throw new ChangeLedgerError('WORKSPACE_LOCKED', `could not acquire change-ledger lock for ${JSON.stringify(workspace)}`);
     }
     /** Persist a blob if it is not already present, and verify existing content. */
+    /** Whether one content-addressed blob is already stored for a workspace. */
+    async hasBlob(workspace, hash) {
+        validateBlobHash(hash);
+        return pathExists(this.blobPath(workspace, hash));
+    }
+    /** Durable directory holding one workspace's manifests, blobs, and caches. */
+    workspaceDirectory(workspace) {
+        return this.workspaceDir(workspace);
+    }
     async putBlob(workspace, hash, content) {
         validateBlobHash(hash);
         const contentHash = createHash('sha256').update(content).digest('hex');

package/lib/types/engine.d.ts

@@ -25,6 +25,14 @@ export declare class ChangeLedgerEngine {
      * A Git worktree also binds the shared per-worktree lock derived from its Git
      * identity; an ordinary directory owns only the durable directory lock.
      */
+    /** Per-workspace path identity caches, loaded once per process generation. */
+    private readonly pathCaches;
+    /**
+     * Load (once) the identity cache that lets a capture reuse unchanged files.
+     * @param workspaceDir - durable directory of one workspace.
+     * @returns the mutable cache shared by every capture of this workspace.
+     */
+    private pathCacheFor;
     private acquireWorkspace;
     private reconcileGitCheckpointJournals;
     private publishGitManifest;

package/lib/types/path-cache.d.ts

@@ -0,0 +1,36 @@
+import type { BigIntStats } from 'node:fs';
+import type { SnapshotEntry } from './types.js';
+/**
+ * One observed path, keyed by the filesystem identity that proves it is unchanged.
+ *
+ * `ctimeNs` changes on every write even when size and mtime are restored, so a
+ * matching key means the stored content is still exactly what the path holds.
+ */
+export interface PathCacheEntry {
+    readonly dev: string;
+    readonly ino: string;
+    readonly size: string;
+    readonly mtimeNs: string;
+    readonly ctimeNs: string;
+    readonly mode: number;
+    readonly entry: SnapshotEntry;
+}
+/** Stable identity string for one observed filesystem object. */
+export declare function pathCacheKey(info: BigIntStats): string;
+/** Remember what one unknown does not already describe. */
+export declare function toPathCacheEntry(info: BigIntStats, entry: SnapshotEntry): PathCacheEntry;
+/** Whether a cached record still describes the object the filesystem reports now. */
+export declare function matchesPathCache(record: PathCacheEntry, info: BigIntStats): boolean;
+/**
+ * Read the per-workspace path cache.
+ *
+ * The cache is a pure optimization: any malformed or unreadable record is
+ * discarded instead of trusted, and a discarded cache only costs a cold capture.
+ * @param workspaceDir - durable directory of one workspace.
+ * @returns the cached records, newest read wins.
+ */
+export declare function readPathCache(workspaceDir: string): Promise<Map<string, PathCacheEntry>>;
+/** Persist the path cache atomically, replacing any previous generation. */
+export declare function writePathCache(workspaceDir: string, cache: ReadonlyMap<string, PathCacheEntry>): Promise<void>;
+/** Drop the cache when its file is unreadable or was never written. */
+export declare function pathCacheExists(workspaceDir: string): Promise<boolean>;

package/lib/types/snapshot.d.ts

@@ -1,3 +1,4 @@
+import { type PathCacheEntry } from './path-cache.js';
 import type { LedgerStore } from './store.js';
 import { type WorkspaceSnapshotSource } from './workspace.js';
 import type { CaptureSkip, CaptureTruncation, ResolvedChangeLedgerConfig, SnapshotEntry, WorkspaceChange } from './types.js';
@@ -23,6 +24,8 @@ export declare function captureTree(options: {
     readonly config: ResolvedChangeLedgerConfig;
     readonly store?: LedgerStore;
     readonly gitObjectFormat?: 'sha1' | 'sha256';
+    /** Per-path identity cache: an unchanged path is reused instead of re-read. */
+    readonly pathCache?: Map<string, PathCacheEntry>;
     readonly signal?: AbortSignal;
 }): Promise<CapturedTree>;
 /**
@@ -35,6 +38,8 @@ export declare function captureStableTree(options: {
     readonly config: ResolvedChangeLedgerConfig;
     readonly store?: LedgerStore;
     readonly gitObjectFormat?: 'sha1' | 'sha256';
+    /** Per-path identity cache: an unchanged path is reused instead of re-read. */
+    readonly pathCache?: Map<string, PathCacheEntry>;
     readonly signal?: AbortSignal;
 }): Promise<CapturedTree>;
 /** Compute stable path-level differences between two captured trees. */

package/lib/types/store.d.ts

@@ -39,6 +39,10 @@ export declare class LedgerStore {
     acquireWorkspaceDir(workspaceDir: string, workspace: string, signal?: AbortSignal): Promise<() => Promise<void>>;
     private acquireOne;
     /** Persist a blob if it is not already present, and verify existing content. */
+    /** Whether one content-addressed blob is already stored for a workspace. */
+    hasBlob(workspace: string, hash: string): Promise<boolean>;
+    /** Durable directory holding one workspace's manifests, blobs, and caches. */
+    workspaceDirectory(workspace: string): string;
     putBlob(workspace: string, hash: string, content: Buffer): Promise<void>;
     /** Read and verify one content-addressed blob. */
     readBlob(workspace: string, hash: string): Promise<Buffer>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-turn-rewind",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Turn-level conversation and workspace rewind for DeepSeek Harness, powered by a persistent Change Ledger",
   "repository": {
     "type": "git",

package/src/engine.ts

@@ -26,6 +26,7 @@ import {
   resolveWorkspacePath,
   validateRelativePath,
 } from './path-utils.js'
+import { readPathCache, writePathCache, type PathCacheEntry } from './path-cache.js'
 import { captureSnapshotEntry, captureStableTree, diffTrees, entriesEqual } from './snapshot.js'
 import { LedgerStore, type GitCheckpointJournal } from './store.js'
 import { discoverWorkspace, discoverWorkspaceIdentity, sameWorkspaceFence } from './workspace.js'
@@ -53,7 +54,7 @@ const DEFAULTS = {
   maxRestorePoints: 50,
   maxTurnCheckpointsPerSession: 30,
   maxFiles: 20_000,
-  maxFileBytes: 16 * 1024 * 1024,
+  maxFileBytes: 64 * 1024 * 1024,
   maxSnapshotBytes: 512 * 1024 * 1024,
   planTtlMs: 15 * 60 * 1_000,
   staleLockMs: 30_000,
@@ -111,6 +112,22 @@ export class ChangeLedgerEngine {
    * A Git worktree also binds the shared per-worktree lock derived from its Git
    * identity; an ordinary directory owns only the durable directory lock.
    */
+  /** Per-workspace path identity caches, loaded once per process generation. */
+  private readonly pathCaches = new Map<string, Map<string, PathCacheEntry>>()
+
+  /**
+   * Load (once) the identity cache that lets a capture reuse unchanged files.
+   * @param workspaceDir - durable directory of one workspace.
+   * @returns the mutable cache shared by every capture of this workspace.
+   */
+  private async pathCacheFor(workspaceDir: string): Promise<Map<string, PathCacheEntry>> {
+    const loaded = this.pathCaches.get(workspaceDir)
+    if (loaded !== undefined) return loaded
+    const cache = await readPathCache(workspaceDir)
+    this.pathCaches.set(workspaceDir, cache)
+    return cache
+  }
+
   private async acquireWorkspace(
     workspace: Pick<WorkspaceState, 'type' | 'root'>,
     signal?: AbortSignal,
@@ -496,6 +513,8 @@ export class ChangeLedgerEngine {
       const current = await captureStableTree({
         cwd: source.state.root,
         config: this.config,
+        store: this.store,
+        pathCache: await this.pathCacheFor(this.store.workspaceDirectory(source.state.root)),
         ...(manifest.version === 2 ? { gitObjectFormat: manifest.git.objectFormat } : {}),
         ...(options.signal === undefined ? {} : { signal: options.signal }),
       })
@@ -541,6 +560,8 @@ export class ChangeLedgerEngine {
       const current = await captureStableTree({
         cwd: source.state.root,
         config: this.config,
+        store: this.store,
+        pathCache: await this.pathCacheFor(this.store.workspaceDirectory(source.state.root)),
         ...(manifest.version === 2 ? { gitObjectFormat: manifest.git.objectFormat } : {}),
         ...(options.signal === undefined ? {} : { signal: options.signal }),
       })
@@ -948,12 +969,16 @@ export class ChangeLedgerEngine {
       await this.store.writeSnapshotCleanup(options.cwd)
     }
     try {
+      const workspaceDir = this.store.workspaceDirectory(options.cwd)
+      const pathCache = await this.pathCacheFor(workspaceDir)
       const tree = await captureStableTree({
         cwd: options.cwd,
         config: this.config,
         store: this.store,
+        pathCache,
         ...(options.signal === undefined ? {} : { signal: options.signal }),
       })
+      await writePathCache(workspaceDir, pathCache).catch(() => undefined)
       const manifest: RestorePointManifest = {
         version: LEDGER_FORMAT_VERSION,
         id: makeId('rp'),

package/src/path-cache.ts

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { BigIntStats } from 'node:fs'
+import { isNodeError, pathExists, writeJsonAtomic } from './path-utils.js'
+import type { SnapshotEntry } from './types.js'
+
+const CACHE_FILE = 'path-cache.json'
+const CACHE_VERSION = 1
+const MAX_ENTRIES = 200_000
+const MAX_FILE_BYTES = 64 * 1024 * 1024
+
+/**
+ * One observed path, keyed by the filesystem identity that proves it is unchanged.
+ *
+ * `ctimeNs` changes on every write even when size and mtime are restored, so a
+ * matching key means the stored content is still exactly what the path holds.
+ */
+export interface PathCacheEntry {
+  readonly dev: string
+  readonly ino: string
+  readonly size: string
+  readonly mtimeNs: string
+  readonly ctimeNs: string
+  readonly mode: number
+  readonly entry: SnapshotEntry
+}
+
+/** Stable identity string for one observed filesystem object. */
+export function pathCacheKey(info: BigIntStats): string {
+  return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}:${info.mode.toString()}`
+}
+
+/** Remember what one unknown does not already describe. */
+export function toPathCacheEntry(info: BigIntStats, entry: SnapshotEntry): PathCacheEntry {
+  return {
+    dev: info.dev.toString(),
+    ino: info.ino.toString(),
+    size: info.size.toString(),
+    mtimeNs: info.mtimeNs.toString(),
+    ctimeNs: info.ctimeNs.toString(),
+    mode: Number(info.mode & 0o777n),
+    entry,
+  }
+}
+
+/** Whether a cached record still describes the object the filesystem reports now. */
+export function matchesPathCache(record: PathCacheEntry, info: BigIntStats): boolean {
+  return record.dev === info.dev.toString()
+    && record.ino === info.ino.toString()
+    && record.size === info.size.toString()
+    && record.mtimeNs === info.mtimeNs.toString()
+    && record.ctimeNs === info.ctimeNs.toString()
+    && record.mode === Number(info.mode & 0o777n)
+}
+
+/**
+ * Read the per-workspace path cache.
+ *
+ * The cache is a pure optimization: any malformed or unreadable record is
+ * discarded instead of trusted, and a discarded cache only costs a cold capture.
+ * @param workspaceDir - durable directory of one workspace.
+ * @returns the cached records, newest read wins.
+ */
+export async function readPathCache(workspaceDir: string): Promise<Map<string, PathCacheEntry>> {
+  const cache = new Map<string, PathCacheEntry>()
+  let raw: string
+  try {
+    raw = await readFile(join(workspaceDir, CACHE_FILE), 'utf8')
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) return cache
+    return cache
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return cache
+    const record = parsed as { version?: unknown; paths?: unknown }
+    if (record.version !== CACHE_VERSION || record.paths === null || typeof record.paths !== 'object') return cache
+    for (const [path, value] of Object.entries(record.paths as Record<string, unknown>)) {
+      const entry = parseCacheEntry(value)
+      if (entry === undefined) continue
+      cache.set(path, entry)
+      if (cache.size >= MAX_ENTRIES) break
+    }
+  } catch {
+    return new Map()
+  }
+  return cache
+}
+
+/** Persist the path cache atomically, replacing any previous generation. */
+export async function writePathCache(workspaceDir: string, cache: ReadonlyMap<string, PathCacheEntry>): Promise<void> {
+  const paths: Record<string, unknown> = Object.create(null) as Record<string, unknown>
+  let count = 0
+  for (const [path, entry] of cache) {
+    if (count >= MAX_ENTRIES) break
+    paths[path] = serializeCacheEntry(entry)
+    count += 1
+  }
+  await writeJsonAtomic(join(workspaceDir, CACHE_FILE), { version: CACHE_VERSION, paths })
+}
+
+/** Drop the cache when its file is unreadable or was never written. */
+export async function pathCacheExists(workspaceDir: string): Promise<boolean> {
+  return pathExists(join(workspaceDir, CACHE_FILE))
+}
+
+function serializeCacheEntry(record: PathCacheEntry): Record<string, unknown> {
+  const entry = record.entry
+  return {
+    dev: record.dev, ino: record.ino, size: record.size,
+    mtimeNs: record.mtimeNs, ctimeNs: record.ctimeNs, mode: record.mode,
+    kind: entry.kind,
+    ...(entry.kind === 'file' ? { blob: entry.blob, provider: entry.provider } : { target: entry.target }),
+  }
+}
+
+function parseCacheEntry(value: unknown): PathCacheEntry | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const record = value as Record<string, unknown>
+  const text = (key: string): string | undefined => (typeof record[key] === 'string' ? record[key] as string : undefined)
+  const dev = text('dev'); const ino = text('ino'); const size = text('size')
+  const mtimeNs = text('mtimeNs'); const ctimeNs = text('ctimeNs')
+  if (dev === undefined || ino === undefined || size === undefined || mtimeNs === undefined || ctimeNs === undefined) return undefined
+  if (typeof record.mode !== 'number' || !Number.isInteger(record.mode)) return undefined
+  let entry: SnapshotEntry
+  if (record.kind === 'file') {
+    const blob = text('blob')
+    if (blob === undefined || !/^[0-9a-f]{64}$/.test(blob)) return undefined
+    const provider = record.provider
+    if (provider !== undefined && provider !== 'git') return undefined
+    entry = {
+      kind: 'file', blob, size: Number(size), mode: record.mode,
+      ...(provider === undefined ? {} : { provider }),
+    }
+  } else if (record.kind === 'symlink') {
+    const target = text('target')
+    if (target === undefined || target.includes('\0')) return undefined
+    entry = { kind: 'symlink', target, mode: record.mode }
+  } else {
+    return undefined
+  }
+  if (BigInt(size) > BigInt(MAX_FILE_BYTES)) return undefined
+  return { dev, ino, size, mtimeNs, ctimeNs, mode: record.mode, entry }
+}

package/src/snapshot.ts

@@ -3,6 +3,7 @@ import { constants, type BigIntStats } from 'node:fs'
 import { lstat, open, readlink } from 'node:fs/promises'
 import { ChangeLedgerError } from './errors.js'
 import { isNodeError, resolveWorkspacePath } from './path-utils.js'
+import { matchesPathCache, toPathCacheEntry, type PathCacheEntry } from './path-cache.js'
 import type { LedgerStore } from './store.js'
 import { discoverWorkspace, sameWorkspaceFence, type WorkspaceSnapshotSource } from './workspace.js'
 import type {
@@ -41,6 +42,8 @@ export async function captureTree(options: {
   readonly config: ResolvedChangeLedgerConfig
   readonly store?: LedgerStore
   readonly gitObjectFormat?: 'sha1' | 'sha256'
+  /** Per-path identity cache: an unchanged path is reused instead of re-read. */
+  readonly pathCache?: Map<string, PathCacheEntry>
   readonly signal?: AbortSignal
 }): Promise<CapturedTree> {
   throwIfAborted(options.signal)
@@ -75,6 +78,28 @@ export async function captureTree(options: {
   let budgetSpent = false
   const capturePath = async (path: string): Promise<void> => {
     throwIfAborted(options.signal)
+    // Reuse is only sound when the identity is unchanged and the stored blob is
+    // still present; a garbage-collected blob falls back to a fresh read.
+    if (options.pathCache !== undefined && options.store !== undefined && gitCapture === undefined) {
+      const cached = options.pathCache.get(path)
+      if (cached !== undefined) {
+        let info: BigIntStats | undefined
+        try {
+          info = await lstat(resolveWorkspacePath(source.state.root, path), { bigint: true })
+        } catch (error) {
+          if (!isNodeError(error, 'ENOENT')) throw error
+        }
+        if (info !== undefined && matchesPathCache(cached, info)) {
+          const reusable = cached.entry.kind === 'symlink'
+            || await options.store.hasBlob(source.state.root, cached.entry.blob)
+          if (reusable) {
+            entries[path] = cached.entry
+            if (cached.entry.kind === 'file') totalBytes += cached.entry.size
+            return
+          }
+        }
+      }
+    }
     if (budgetSpent) {
       // The aggregate budget is gone, but the path is still recorded so a
       // restore can prove this point never observed it.
@@ -115,6 +140,9 @@ export async function captureTree(options: {
     }
     entries[path] = entry.snapshot
     if (gitCapture !== undefined) gitCapture.entries[path] = entry.snapshot
+    if (options.pathCache !== undefined && gitCapture === undefined) {
+      options.pathCache.set(path, toPathCacheEntry(entry.info, entry.snapshot))
+    }
   }
   {
     // Reading one file at a time makes a real project directory take minutes, so
@@ -172,12 +200,16 @@ export async function captureStableTree(options: {
   readonly config: ResolvedChangeLedgerConfig
   readonly store?: LedgerStore
   readonly gitObjectFormat?: 'sha1' | 'sha256'
+  /** Per-path identity cache: an unchanged path is reused instead of re-read. */
+  readonly pathCache?: Map<string, PathCacheEntry>
   readonly signal?: AbortSignal
 }): Promise<CapturedTree> {
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const first = await captureTree({
       cwd: options.cwd,
       config: options.config,
+      ...(options.store === undefined ? {} : { store: options.store }),
+      ...(options.pathCache === undefined ? {} : { pathCache: options.pathCache }),
       ...(options.gitObjectFormat === undefined ? {} : { gitObjectFormat: options.gitObjectFormat }),
       ...(options.signal === undefined ? {} : { signal: options.signal }),
     })
@@ -303,8 +335,8 @@ async function captureEntry(
   path: string,
   maxFileBytes: number,
   signal?: AbortSignal,
-): Promise<{ readonly kind: 'file'; readonly snapshot: SnapshotEntry & { readonly kind: 'file' }; readonly content: Buffer }
-  | { readonly kind: 'symlink'; readonly snapshot: SnapshotEntry & { readonly kind: 'symlink' } }
+): Promise<{ readonly kind: 'file'; readonly snapshot: SnapshotEntry & { readonly kind: 'file' }; readonly content: Buffer; readonly info: BigIntStats }
+  | { readonly kind: 'symlink'; readonly snapshot: SnapshotEntry & { readonly kind: 'symlink' }; readonly info: BigIntStats }
   | undefined> {
   const target = resolveWorkspacePath(root, path)
   for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -321,7 +353,7 @@ async function captureEntry(
       const linkTarget = await readlink(target)
       const after = await lstat(target, { bigint: true })
       if (!sameStat(before, after)) continue
-      return { kind: 'symlink', snapshot: { kind: 'symlink', target: linkTarget, mode } }
+      return { kind: 'symlink', snapshot: { kind: 'symlink', target: linkTarget, mode }, info: after }
     }
     if (!before.isFile()) {
       throw new ChangeLedgerError('UNSUPPORTED_FILE_TYPE', `eligible path is not a regular file or symlink: ${JSON.stringify(path)}`)
@@ -355,6 +387,7 @@ async function captureEntry(
       kind: 'file',
       snapshot: { kind: 'file', blob, size: content.length, mode },
       content,
+      info: { ...before, size: BigInt(content.length) } as BigIntStats,
     }
   }
   throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `path changed repeatedly while being captured: ${JSON.stringify(path)}`)

package/src/store.ts

@@ -263,6 +263,17 @@ export class LedgerStore {
   }
 
   /** Persist a blob if it is not already present, and verify existing content. */
+  /** Whether one content-addressed blob is already stored for a workspace. */
+  async hasBlob(workspace: string, hash: string): Promise<boolean> {
+    validateBlobHash(hash)
+    return pathExists(this.blobPath(workspace, hash))
+  }
+
+  /** Durable directory holding one workspace's manifests, blobs, and caches. */
+  workspaceDirectory(workspace: string): string {
+    return this.workspaceDir(workspace)
+  }
+
   async putBlob(workspace: string, hash: string, content: Buffer): Promise<void> {
     validateBlobHash(hash)
     const contentHash = createHash('sha256').update(content).digest('hex')