@rewind-ai/cli 0.6.2

package/dist/src/session/watcher.js

@@ -0,0 +1,186 @@
+import { assertApprovedSandbox, assertSafeRelativePath, getProjectRoot, isPathInside, } from "../paths.js";
+import { matchAmbientPath } from "./ambient.js";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { lstat } from "node:fs/promises";
+import chokidar from "chokidar";
+function toRel(root, abs) {
+    const rel = path.relative(root, abs).split(path.sep).join("/");
+    if (rel === "" || rel === ".") {
+        throw new Error("root event");
+    }
+    return assertSafeRelativePath(rel);
+}
+/**
+ * Live sandbox watcher.
+ * Uses chokidar (FSEvents on macOS) with debounce/coalesce.
+ * Events are signals — final manifest diff remains authoritative.
+ */
+export class SandboxWatcher {
+    sandboxRoot;
+    onEvent;
+    watcher = null;
+    pending = new Map();
+    closed = false;
+    debounceMs;
+    stats = {
+        rawSignals: 0,
+        emittedEvents: 0,
+        peakEventsPerSec: 0,
+    };
+    windowCount = 0;
+    windowTimer = null;
+    constructor(sandboxRoot, onEvent, options = {}) {
+        this.sandboxRoot = sandboxRoot;
+        this.onEvent = onEvent;
+        this.debounceMs = options.debounceMs ?? 75;
+    }
+    async start(projectRoot = getProjectRoot()) {
+        await assertApprovedSandbox(this.sandboxRoot, projectRoot);
+        this.windowTimer = setInterval(() => {
+            if (this.windowCount > this.stats.peakEventsPerSec) {
+                this.stats.peakEventsPerSec = this.windowCount;
+            }
+            this.windowCount = 0;
+        }, 1000);
+        this.windowTimer.unref?.();
+        this.watcher = chokidar.watch(this.sandboxRoot, {
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 50,
+                pollInterval: 25,
+            },
+            followSymlinks: false,
+            depth: 99,
+        });
+        this.watcher.on("all", (eventName, absPath) => {
+            void this.handleRaw(eventName, absPath);
+        });
+        this.watcher.on("error", (err) => {
+            // Surface as UNKNOWN modify on root marker — keep watching
+            console.error(`[watcher error] ${err instanceof Error ? err.message : String(err)}`);
+        });
+        // Ready wait
+        await new Promise((resolve) => {
+            this.watcher?.on("ready", () => resolve());
+        });
+    }
+    async handleRaw(eventName, absPath) {
+        if (this.closed)
+            return;
+        if (!isPathInside(this.sandboxRoot, absPath))
+            return;
+        this.stats.rawSignals++;
+        this.windowCount++;
+        const key = absPath;
+        const existing = this.pending.get(key);
+        if (existing) {
+            existing.types.add(eventName);
+            existing.rawCount++;
+            clearTimeout(existing.timer);
+            existing.timer = setTimeout(() => {
+                void this.flush(key);
+            }, this.debounceMs);
+            return;
+        }
+        const timer = setTimeout(() => {
+            void this.flush(key);
+        }, this.debounceMs);
+        this.pending.set(key, {
+            abs: absPath,
+            types: new Set([eventName]),
+            timer,
+            rawCount: 1,
+        });
+    }
+    async flush(key) {
+        const pending = this.pending.get(key);
+        if (!pending)
+            return;
+        this.pending.delete(key);
+        let rel;
+        try {
+            rel = toRel(this.sandboxRoot, pending.abs);
+            if (rel === ".")
+                return;
+        }
+        catch {
+            return;
+        }
+        const type = await this.classify(pending.types, pending.abs);
+        const ambient = matchAmbientPath(rel);
+        const evidence = [
+            {
+                kind: "watcher_signal",
+                detail: `chokidar/FSEvents signals: ${[...pending.types].join(",")}`,
+                observedAt: new Date().toISOString(),
+            },
+        ];
+        if (ambient.ambient) {
+            evidence.push({
+                kind: "ambient_filename_pattern",
+                detail: ambient.evidence,
+                observedAt: new Date().toISOString(),
+            });
+        }
+        const event = {
+            id: `ev-${Date.now().toString(36)}-${randomBytes(2).toString("hex")}`,
+            at: new Date().toISOString(),
+            type,
+            path: rel,
+            rawCount: pending.rawCount,
+            // Honest default: watcher does not know the actor
+            actor: ambient.ambient ? "SYSTEM" : "UNKNOWN",
+            confidence: ambient.ambient ? "MEDIUM" : "NONE",
+            evidence,
+            ambientSuspect: ambient.ambient,
+        };
+        this.stats.emittedEvents++;
+        this.onEvent(event);
+    }
+    async classify(types, abs) {
+        const has = (t) => types.has(t);
+        let isDir = false;
+        try {
+            const st = await lstat(abs);
+            isDir = st.isDirectory();
+        }
+        catch {
+            // deleted
+            if (has("unlinkDir") || has("rmdir"))
+                return "DIRECTORY_DELETE";
+            if (has("unlink") || has("delete"))
+                return "DELETE";
+            return "DELETE";
+        }
+        if (has("addDir") || (has("add") && isDir))
+            return "DIRECTORY_CREATE";
+        if (has("unlinkDir"))
+            return "DIRECTORY_DELETE";
+        if (has("add") && !isDir)
+            return "CREATE";
+        if (has("change") || has("modify"))
+            return "MODIFY";
+        if (has("unlink"))
+            return "DELETE";
+        return "UNKNOWN";
+    }
+    async stop() {
+        this.closed = true;
+        for (const p of this.pending.values())
+            clearTimeout(p.timer);
+        // Flush remaining
+        const keys = [...this.pending.keys()];
+        for (const k of keys)
+            await this.flush(k);
+        if (this.windowTimer)
+            clearInterval(this.windowTimer);
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        return { ...this.stats };
+    }
+}
+//# sourceMappingURL=watcher.js.map

package/dist/src/session/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../../src/session/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMhD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,QAA+C,MAAM,UAAU,CAAC;AAEvE,SAAS,KAAK,CAAC,IAAY,EAAE,GAAW;IACtC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/D,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,sBAAsB,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC;AAiBD;;;;GAIG;AACH,MAAM,OAAO,cAAc;IAcN;IACA;IAdX,OAAO,GAA2B,IAAI,CAAC;IACvC,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IACrC,MAAM,GAAG,KAAK,CAAC;IACN,UAAU,CAAS;IAC3B,KAAK,GAAiB;QAC7B,UAAU,EAAE,CAAC;QACb,aAAa,EAAE,CAAC;QAChB,gBAAgB,EAAE,CAAC;KACpB,CAAC;IACM,WAAW,GAAG,CAAC,CAAC;IAChB,WAAW,GAA0B,IAAI,CAAC;IAElD,YACmB,WAAmB,EACnB,OAA0B,EAC3C,UAAyD,EAAE;QAF1C,gBAAW,GAAX,WAAW,CAAQ;QACnB,YAAO,GAAP,OAAO,CAAmB;QAG3C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,WAAW,GAAG,cAAc,EAAE;QACxC,MAAM,qBAAqB,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QAE3D,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;YAClC,IAAI,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;gBACnD,IAAI,CAAC,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,WAAW,CAAC;YACjD,CAAC;YACD,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACvB,CAAC,EAAE,IAAI,CAAC,CAAC;QACT,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;QAE3B,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE;YAC9C,aAAa,EAAE,IAAI;YACnB,UAAU,EAAE,IAAI;YAChB,gBAAgB,EAAE;gBAChB,kBAAkB,EAAE,EAAE;gBACtB,YAAY,EAAE,EAAE;aACjB;YACD,cAAc,EAAE,KAAK;YACrB,KAAK,EAAE,EAAE;SACV,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE;YAC5C,KAAK,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YAC/B,2DAA2D;YAC3D,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC,CAAC,CAAC;QAEH,aAAa;QACb,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,SAAiB,EAAE,OAAe;QACxD,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC;YAAE,OAAO;QAErD,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QACxB,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB,MAAM,GAAG,GAAG,OAAO,CAAC;QACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9B,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACpB,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC7B,QAAQ,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC/B,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,GAAG,EAAE,OAAO;YACZ,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;YAC3B,KAAK;YACL,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,GAAW;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAEzB,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,GAAG,KAAK,GAAG;gBAAE,OAAO;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,QAAQ,GAA0B;YACtC;gBACE,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,8BAA8B,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;gBACpE,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACrC;SACF,CAAC;QACF,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,0BAA0B;gBAChC,MAAM,EAAE,OAAO,CAAC,QAAQ;gBACxB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACrC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,KAAK,GAAkB;YAC3B,EAAE,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;YACrE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,IAAI;YACJ,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,kDAAkD;YAClD,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YAC7C,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;YAC/C,QAAQ;YACR,cAAc,EAAE,OAAO,CAAC,OAAO;SAChC,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAEO,KAAK,CAAC,QAAQ,CACpB,KAAkB,EAClB,GAAW;QAEX,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YAC5B,KAAK,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,UAAU;YACV,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC;gBAAE,OAAO,kBAAkB,CAAC;YAChE,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC;gBAAE,OAAO,QAAQ,CAAC;YACpD,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,kBAAkB,CAAC;QACtE,IAAI,GAAG,CAAC,WAAW,CAAC;YAAE,OAAO,kBAAkB,CAAC;QAChD,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,QAAQ,CAAC;QAC1C,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;QACpD,IAAI,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAC;QACnC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC7D,kBAAkB;QAClB,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,IAAI,CAAC,WAAW;YAAE,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/src/timing.d.ts

@@ -0,0 +1,7 @@
+/** Simple timing helpers. */
+export declare class Timer {
+    private readonly start;
+    constructor();
+    elapsedMs(): number;
+}
+export declare function formatMs(ms: number): string;

package/dist/src/timing.js

@@ -0,0 +1,19 @@
+/** Simple timing helpers. */
+export class Timer {
+    start;
+    constructor() {
+        this.start = process.hrtime.bigint();
+    }
+    elapsedMs() {
+        const ns = process.hrtime.bigint() - this.start;
+        return Number(ns) / 1e6;
+    }
+}
+export function formatMs(ms) {
+    if (ms < 1)
+        return `${ms.toFixed(2)}ms`;
+    if (ms < 1000)
+        return `${ms.toFixed(1)}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+//# sourceMappingURL=timing.js.map

package/dist/src/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/timing.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAE7B,MAAM,OAAO,KAAK;IACC,KAAK,CAAS;IAE/B;QACE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IACvC,CAAC;IAED,SAAS;QACP,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAChD,OAAO,MAAM,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,IAAI,EAAE,GAAG,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3C,OAAO,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACtC,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,101 @@
+/** Core domain types for REWIND V0. */
+export type ChangeType = "CREATED" | "MODIFIED" | "DELETED" | "RENAMED" | "MOVED";
+export type Reversibility = "REVERSIBLE" | "COMPENSABLE" | "IRREVERSIBLE";
+export type EntryKind = "file" | "directory" | "symlink";
+export interface ManifestEntry {
+    /** Relative path from sandbox root, POSIX-style, no leading slash. */
+    path: string;
+    kind: EntryKind;
+    /** SHA-256 of file contents; null for directories; symlink target hashed for symlinks. */
+    hash: string | null;
+    size: number;
+    /** Octal permission bits as number (e.g. 0o644). */
+    mode: number;
+    /** Symlink target if kind === "symlink". */
+    linkTarget: string | null;
+}
+export interface Manifest {
+    version: 1;
+    createdAt: string;
+    rootLabel: string;
+    entries: ManifestEntry[];
+    /** SHA-256 of canonical serialized entries. */
+    fingerprint: string;
+}
+export interface CheckpointMeta {
+    id: string;
+    createdAt: string;
+    targetPath: string;
+    fingerprint: string;
+    fileCount: number;
+    directoryCount: number;
+    symlinkCount: number;
+    timingsMs: {
+        manifest: number;
+        contentStore: number;
+        total: number;
+    };
+}
+export interface Checkpoint {
+    meta: CheckpointMeta;
+    manifest: Manifest;
+    /** Absolute path to checkpoint directory under .rewind/checkpoints/<id> */
+    directory: string;
+}
+export interface Change {
+    type: ChangeType;
+    pathBefore: string | null;
+    pathAfter: string | null;
+    hashBefore: string | null;
+    hashAfter: string | null;
+    sizeBefore: number | null;
+    sizeAfter: number | null;
+    reversibility: Reversibility;
+}
+export type TransactionStatus = "open" | "recorded" | "rewound" | "verified" | "failed";
+export interface Transaction {
+    id: string;
+    startedAt: string;
+    completedAt: string | null;
+    checkpointId: string;
+    targetPath: string;
+    changes: Change[];
+    status: TransactionStatus;
+    summary: TransactionSummary;
+    timingsMs: {
+        diff: number;
+    };
+}
+export interface TransactionSummary {
+    total: number;
+    modified: number;
+    created: number;
+    deleted: number;
+    renamed: number;
+    moved: number;
+    reversible: number;
+    compensable: number;
+    irreversible: number;
+}
+export interface VerificationResult {
+    ok: boolean;
+    filesChecked: number;
+    expectedFingerprint: string;
+    actualFingerprint: string;
+    mismatches: VerificationMismatch[];
+    timingsMs: {
+        manifest: number;
+        compare: number;
+        total: number;
+    };
+}
+export interface VerificationMismatch {
+    path: string;
+    reason: string;
+    expected?: string;
+    actual?: string;
+}
+export interface TimingRecord {
+    label: string;
+    ms: number;
+}

package/dist/src/types.js

@@ -0,0 +1,3 @@
+/** Core domain types for REWIND V0. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,uCAAuC"}

package/dist/src/verify.d.ts

@@ -0,0 +1,8 @@
+import type { Checkpoint, VerificationResult } from "./types.js";
+/**
+ * Compare restored sandbox against a checkpoint manifest.
+ * Fail closed: any mismatch → ok: false.
+ */
+export declare function verifyAgainstCheckpoint(checkpoint: Checkpoint, projectRoot?: string): Promise<VerificationResult>;
+export declare function verifyLatest(projectRoot?: string): Promise<VerificationResult>;
+export declare function printVerification(result: VerificationResult): void;

package/dist/src/verify.js

@@ -0,0 +1,126 @@
+import { getProjectRoot, getSandboxPath, assertApprovedSandbox, } from "./paths.js";
+import { loadCheckpoint } from "./checkpoint.js";
+import { buildManifest, fingerprintManifestEntries, } from "./manifest.js";
+import { Timer } from "./timing.js";
+function entryKey(e) {
+    return [
+        e.path,
+        e.kind,
+        e.hash ?? "",
+        String(e.size),
+        String(e.mode),
+        e.linkTarget ?? "",
+    ].join("|");
+}
+/**
+ * Compare restored sandbox against a checkpoint manifest.
+ * Fail closed: any mismatch → ok: false.
+ */
+export async function verifyAgainstCheckpoint(checkpoint, projectRoot = getProjectRoot()) {
+    const totalTimer = new Timer();
+    const sandbox = getSandboxPath(projectRoot);
+    await assertApprovedSandbox(sandbox, projectRoot);
+    const manifestTimer = new Timer();
+    const actual = await buildManifest(sandbox, "sandbox-test-project");
+    const manifestMs = manifestTimer.elapsedMs();
+    const compareTimer = new Timer();
+    const mismatches = [];
+    const expectedMap = new Map(checkpoint.manifest.entries.map((e) => [e.path, e]));
+    const actualMap = new Map(actual.entries.map((e) => [e.path, e]));
+    for (const [p, exp] of expectedMap) {
+        const act = actualMap.get(p);
+        if (!act) {
+            mismatches.push({
+                path: p,
+                reason: "missing in restored tree",
+                expected: entryKey(exp),
+            });
+            continue;
+        }
+        if (entryKey(exp) !== entryKey(act)) {
+            const reasons = [];
+            if (exp.kind !== act.kind)
+                reasons.push(`kind ${exp.kind}→${act.kind}`);
+            if (exp.hash !== act.hash)
+                reasons.push("hash mismatch");
+            if (exp.size !== act.size)
+                reasons.push(`size ${exp.size}→${act.size}`);
+            if (exp.mode !== act.mode)
+                reasons.push(`mode ${exp.mode}→${act.mode}`);
+            if (exp.linkTarget !== act.linkTarget)
+                reasons.push("linkTarget mismatch");
+            mismatches.push({
+                path: p,
+                reason: reasons.join(", ") || "entry mismatch",
+                expected: entryKey(exp),
+                actual: entryKey(act),
+            });
+        }
+    }
+    for (const [p, act] of actualMap) {
+        if (!expectedMap.has(p)) {
+            mismatches.push({
+                path: p,
+                reason: "unexpected path after restore",
+                actual: entryKey(act),
+            });
+        }
+    }
+    // Fingerprint compare (authoritative whole-tree check)
+    const expectedFingerprint = checkpoint.manifest.fingerprint;
+    const actualFingerprint = fingerprintManifestEntries(actual.entries);
+    if (expectedFingerprint !== actualFingerprint && mismatches.length === 0) {
+        mismatches.push({
+            path: "(fingerprint)",
+            reason: "fingerprint mismatch without per-entry diffs (canonicalization bug?)",
+            expected: expectedFingerprint,
+            actual: actualFingerprint,
+        });
+    }
+    const compareMs = compareTimer.elapsedMs();
+    const filesChecked = checkpoint.manifest.entries.length;
+    return {
+        ok: mismatches.length === 0 && expectedFingerprint === actualFingerprint,
+        filesChecked,
+        expectedFingerprint,
+        actualFingerprint,
+        mismatches,
+        timingsMs: {
+            manifest: manifestMs,
+            compare: compareMs,
+            total: totalTimer.elapsedMs(),
+        },
+    };
+}
+export async function verifyLatest(projectRoot = getProjectRoot()) {
+    const checkpoint = await loadCheckpoint("latest", projectRoot);
+    return verifyAgainstCheckpoint(checkpoint, projectRoot);
+}
+export function printVerification(result) {
+    console.log("REWIND VERIFICATION");
+    console.log("");
+    console.log(`Files checked: ${result.filesChecked}`);
+    console.log("");
+    console.log("Expected manifest hash:");
+    console.log(result.expectedFingerprint);
+    console.log("");
+    console.log("Actual manifest hash:");
+    console.log(result.actualFingerprint);
+    console.log("");
+    console.log("RESULT:");
+    console.log("");
+    if (result.ok) {
+        console.log("EXACT MATCH");
+    }
+    else {
+        console.log("RESTORE FAILED");
+        console.log("");
+        for (const m of result.mismatches.slice(0, 50)) {
+            console.log(`- ${m.path}: ${m.reason}`);
+        }
+        if (result.mismatches.length > 50) {
+            console.log(`… and ${result.mismatches.length - 50} more`);
+        }
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/src/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/verify.ts"],"names":[],"mappings":"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"}

package/docs/ADAPTERS.md

@@ -0,0 +1,37 @@
+# Adapters (V5)
+
+## EXISTS
+
+### Interface (`RewindAdapter`)
+
+- `identifyTarget` / `validateOperation`
+- `inspectCurrent` / `captureBefore`
+- `execute` / `captureAfter`
+- `compareExpectedCurrent` / `reverse`
+- `describe`
+
+### FilesystemAdapter
+
+**Shipped.** Wraps proven V2 primitives:
+
+- create / write / delete / move
+- create_directory / delete_directory (subtree capture)
+- CAS objects under `.rewind/objects`
+- conflict-aware reverse via snapshot restore
+
+MCP tools and `mediate*` functions call the transaction engine, which calls this adapter. There is one authoritative mediated FS path.
+
+### Registry
+
+`getAdapter("filesystem")` — only registered adapter in V5.
+
+## PLANNED (not implemented)
+
+| Adapter | Notes |
+|---------|--------|
+| shell | Command capture + cwd/env; often COMPENSATABLE/IRREVERSIBLE |
+| database | Txn-aware reverse or compensating SQL |
+| http/api | Idempotency keys + compensation |
+| browser | DOM/navigation actions |
+
+Do not treat these as available APIs.

package/docs/APPROVALS.md

@@ -0,0 +1,32 @@
+# Approvals (V5)
+
+## EXISTS
+
+When permission returns **ASK**:
+
+1. Capture validated intent + before state  
+2. Fingerprint current target state  
+3. Persist `.rewind/approvals/appr_….json`  
+4. Transaction status = `AWAITING_APPROVAL`  
+5. **No mutation yet**
+
+Human may:
+
+- `rewind approvals`
+- `rewind approve <appr_…>` — revalidate fingerprint + operation, then execute
+- `rewind deny <appr_…>` — mark DENIED, never execute
+
+### TOCTOU
+
+If target state changes while waiting, approve **refuses** and does not apply the stale intent.
+
+### UI / API
+
+Local API: `GET /v1/approvals`, `POST /v1/approvals/:id/approve|deny`  
+Minimal control app shows Approve/Deny on real pending rows.
+
+## PLANNED
+
+- Rich desktop approval UX
+- Push notifications
+- Multi-approver / quorum (not designed yet)

package/docs/ARCHITECTURE.md

@@ -0,0 +1,57 @@
+# Architecture (V5)
+
+## EXISTS
+
+```
+MCP / CLI / Local API
+        │
+        ▼
+┌───────────────────┐
+│ Transaction Engine │  prepare → permission → adapter → mutate
+└─────────┬─────────┘
+          │
+   ┌──────┴──────┐
+   ▼             ▼
+Permission    Adapter Registry
+Engine           │
+                 ▼
+          FilesystemAdapter  ← wraps action/capture|mutate|objects
+                 │
+                 ▼
+         .rewind/actions (v2 JSON, append index)
+         .rewind/transactions (v5 overlays)
+         .rewind/objects (CAS)
+         .rewind/approvals
+         .rewind/policy/permissions.json
+```
+
+### Layers
+
+| Layer | Path | Role |
+|-------|------|------|
+| Core types | `src/core/types.ts` | Transaction, Actor, Authority, reversibility |
+| Lifecycle | `src/core/lifecycle.ts` | Validated status transitions |
+| Engine | `src/core/engine.ts` | Single mediated execution + undo + approval |
+| Compatibility | `src/core/compatibility.ts` | ActionRecord v2 ↔ Transaction v5 |
+| Adapters | `src/adapters/*` | RewindAdapter + FilesystemAdapter |
+| Permission | `src/permission/*` | ALLOW / ASK / DENY policies |
+| Approval | `src/approval/*` | Pending intents + TOCTOU fingerprint |
+| Ledger query | `src/ledger/query.ts` | History / formatting |
+| Entitlement | `src/entitlement/provider.ts` | Pluggable license boundary |
+| Local API | `src/api/server.ts` | Loopback control API + minimal UI |
+| MCP | `src/mcp/server.ts` | Tools → mediate* → engine |
+| V0–V4 | `src/sandbox`, `session`, `enforcement`, `protect` | Unchanged proofs |
+
+## PLANNED
+
+- Additional adapters (shell, database, HTTP, browser)
+- Stronger OS-level enforcement so bypass is hard
+- Delegated authority with real principals
+- Paid `EntitlementProvider` implementation (not in core)
+
+## Design rules
+
+- Do not duplicate FS mutation paths — adapter calls existing `action/mutate`.
+- Do not claim COMPENSATABLE unless an adapter implements compensation.
+- Do not fabricate human principals; authority may be UNKNOWN.
+- Crash recovery marks PREPARED/EXECUTING/UNDOING as FAILED; never wipes AWAITING_APPROVAL.