@statewalker/webrun-files-sync 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present StateWalker Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @statewalker/webrun-files-sync
+
+rclone-like file-synchronisation engine (copy / sync / bisync / move / check) over two `FilesApi` endpoints.
+
+## Overview
+
+`files-sync` is Axis A of the two-axis VCS architecture — the git-independent "sync" engine. It **plans, then executes**: `plan(a, b, op, opts)` is pure (mutates neither endpoint) and returns a serializable `SyncPlan`; `execute(plan, a, b, opts)` applies it, emitting events and resuming from an optional checkpoint after interruption. Bidirectional `bisync` is a genuine **three-way merge over a sync-owned `SyncAnchor`** (delegated to `@statewalker/webrun-merge`), never two chained one-way syncs.
+
+It imports **only** `@statewalker/webrun-files` and `@statewalker/webrun-merge` and knows nothing of git or versioning — that is the hard Axis A ✗↔ Axis B ban. Content identity (`hashContent`), the per-copy `Transfer` strategy, and conflict resolution are all injected.
+
+## Installation
+
+```bash
+pnpm add @statewalker/webrun-files-sync
+```
+
+## Quick Start
+
+```typescript
+import { createHash } from "node:crypto";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+import { execute, plan } from "@statewalker/webrun-files-sync";
+
+async function sha256(input: AsyncIterable<Uint8Array>): Promise<string> {
+  const h = createHash("sha256");
+  for await (const chunk of input) h.update(chunk);
+  return `sha256:${h.digest("hex")}`;
+}
+
+const a = new MemFilesApi({ initialFiles: { "/new.txt": "new", "/changed.txt": "v2" } });
+const b = new MemFilesApi({ initialFiles: { "/changed.txt": "v1", "/extra.txt": "keep" } });
+
+// Pure plan — dry-runnable, serializable, mutates nothing.
+const p = await plan(a, b, "copy", { hashContent: sha256 });
+
+// Execute, streaming per-action events.
+for await (const event of execute(p, a, b, { hashContent: sha256 })) {
+  if (event.type === "done") console.log("synced", event.action);
+}
+// b now has new.txt + updated changed.txt; extra.txt is kept (copy never deletes).
+```
+
+## API
+
+- **`plan(a, b, op, opts): Promise<SyncPlan>`** — pure planner. `op` is `"copy" | "sync" | "bisync" | "move" | "check"`. `copy` never deletes destination files; `sync` deletes extraneous ones; `move` is copy+verify+delete; `check` compares only; `bisync` runs the 3-way merge.
+- **`execute(plan, a, b, opts): AsyncIterable<SyncEvent>`** — applies a plan, verifying each action and skipping already-completed indices from `opts.checkpoint`.
+- **`buildAnchor(...)`** — build a `SyncAnchor` (bisync base) from an endpoint.
+- **`snapshot(files, filter?)` / `isChanged(...)`** — the change-detection ladder primitives.
+- **`createStreamingTransfer(): Transfer`** — the default whole-file streaming copy executor.
+
+`SyncOptions` carries the required `hashContent`, plus optional `filter`, `transfer`, `verify` (`VerificationMode`), `anchorStore` / `pairKey` (bisync), `resolve`, `quickFingerprint`, and `checkpoint`. Types: `SyncPlan`, `SyncAction`, `SyncConflict`, `SyncEvent`, `SyncAnchor`, `AnchorStore`, `CheckpointStore`, `Transfer`.
+
+## Notes
+
+- **Plan-then-execute + resumable.** Plans are serializable and auditable; `execute` records each completed action index, so an interrupted run resumes with no duplicate work.
+- **Cheap-first change detection.** A short-circuiting ladder (path/type → size → stable mtime → optional quick fingerprint → full `hashContent`) avoids hashing byte-identical files.
+- **Injected `Transfer` seam.** The default streams whole files; a chunk-dedup transfer (from `@statewalker/webrun-content-transfer`) plugs into the *same* seam with no rewrite.
+- **bisync = 3-way over an anchor** via `@statewalker/webrun-merge`, using the same injected content id — not two one-way syncs.
+- Built red/green TDD.

package/dist/anchor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * {@link SyncAnchor} helpers — building a manifest from an endpoint and
+ * reconstructing a read-only "base" {@link FilesApi} view from a manifest.
+ */
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { ByteStream, SyncAnchor } from "./types.js";
+/** Build a fresh anchor manifest by hashing every file in an endpoint. */
+export declare function buildAnchor(files: FilesApi, hashContent: (b: ByteStream) => Promise<string>): Promise<SyncAnchor>;
+/**
+ * A read-only base tree reconstructed from a {@link SyncAnchor}.
+ *
+ * Contract decision 1: the anchor stores NO base bytes. Base content is resolved
+ * ON DEMAND by content-id from whichever live endpoint still holds it (both `a`
+ * and `b` are searched, hashing lazily). When no endpoint holds the id — i.e.
+ * both sides changed the file — `read` yields nothing, and the both-modified
+ * path resolves to a conflict in webrun-merge rather than a bogus merge.
+ */
+export declare function anchorBaseView(anchor: SyncAnchor, a: FilesApi, b: FilesApi, hashContent: (input: ByteStream) => Promise<string>): FilesApi;
+//# sourceMappingURL=anchor.d.ts.map

package/dist/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,0EAA0E;AAC1E,wBAAsB,WAAW,CAC/B,KAAK,EAAE,QAAQ,EACf,WAAW,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,GAC9C,OAAO,CAAC,UAAU,CAAC,CAWrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,CAAC,EAAE,QAAQ,EACX,CAAC,EAAE,QAAQ,EACX,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,GAClD,QAAQ,CA6DV"}

package/dist/bisync.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bidirectional sync — a THREE-WAY merge over a sync-owned {@link SyncAnchor},
+ * delegated to `@statewalker/webrun-merge`. This is NEVER two chained one-way syncs.
+ *
+ * base  = the anchor manifest (with base bytes resolved on demand, see anchor.ts)
+ * left  = endpoint `a`   right = endpoint `b`
+ *
+ * webrun-merge returns operations relative to the merged tree; each is translated
+ * into {@link SyncAction}s applied to BOTH endpoints, and its conflicts are
+ * surfaced (or folded away by an injected `resolve`, inside webrun-merge).
+ *
+ * both-modified policy: files-sync installs a content merger that ALWAYS
+ * conflicts, so a file changed on both sides is a conflict (optionally resolved
+ * by the injected policy) — it is never silently line-merged.
+ *
+ * No-anchor first bisync: with no anchor there is no base, so a true 3-way merge
+ * is impossible. We fall back to a CONSERVATIVE UNION — propagate additions both
+ * ways, delete nothing — and emit a warning. Files present on both sides with
+ * differing content are surfaced as conflicts, never overwritten.
+ */
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { SyncOptions, SyncPlan } from "./types.js";
+export declare function planBisync(a: FilesApi, b: FilesApi, opts: SyncOptions): Promise<SyncPlan>;
+//# sourceMappingURL=bisync.d.ts.map

package/dist/bisync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bisync.d.ts","sourceRoot":"","sources":["../src/bisync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAI1D,OAAO,KAAK,EAA4B,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIlF,wBAAsB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2C/F"}

package/dist/change-detection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The cheap-first change-detection ladder.
+ *
+ * Short-circuits from the cheapest signal to the most expensive:
+ *   path/type  →  size  →  stable mtime  →  optional quick fingerprint  →
+ *   full content hash (injected `hashContent`).
+ *
+ * Each rung that can decide "same" or "changed" returns without paying for the
+ * next one — in particular a size difference marks a file changed WITHOUT ever
+ * hashing, and an equal size+mtime pair is treated as unchanged (rclone's
+ * default heuristic) without hashing either.
+ */
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { ByteStream, PathFilter } from "./types.js";
+export interface Entry {
+    path: string;
+    kind: "file" | "directory";
+    size?: number;
+    mtime?: number;
+}
+export type Snapshot = Map<string, Entry>;
+/** List a whole tree into a path-keyed snapshot, applying an optional filter. */
+export declare function snapshot(files: FilesApi, filter?: PathFilter): Promise<Snapshot>;
+export interface LadderOptions {
+    hashContent: (input: ByteStream) => Promise<string>;
+    quickFingerprint?: boolean;
+}
+/**
+ * Decide whether `from`'s file at `path` differs from `to`'s file, climbing the
+ * ladder only as far as needed. `fromEntry` must exist; `toEntry` may be absent.
+ */
+export declare function isChanged(from: FilesApi, to: FilesApi, path: string, fromEntry: Entry, toEntry: Entry | undefined, opts: LadderOptions): Promise<boolean>;
+//# sourceMappingURL=change-detection.d.ts.map

package/dist/change-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-detection.d.ts","sourceRoot":"","sources":["../src/change-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,iFAAiF;AACjF,wBAAsB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAYtF;AAwCD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,QAAQ,EACd,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,KAAK,EAChB,OAAO,EAAE,KAAK,GAAG,SAAS,EAC1B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,OAAO,CAAC,CAoClB"}

package/dist/execute.d.ts

@@ -0,0 +1,16 @@
+/**
+ * {@link execute} — applies a {@link SyncPlan}, emitting {@link SyncEvent}s.
+ *
+ * - Every copy/update is verified at the destination per {@link VerificationMode}.
+ * - `move` never deletes a source until its destination is verified (the delete
+ *   action re-verifies before removing).
+ * - Interruptible + resumable: completed action indices are recorded in the
+ *   injected {@link CheckpointStore} before each `done` event, so a second call
+ *   with the same store completes the remainder with no duplicate work.
+ * - `check` mutates nothing.
+ * - After a fully-clean `bisync`, a fresh anchor is written from the merged state.
+ */
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { SyncEvent, SyncOptions, SyncPlan } from "./types.js";
+export declare function execute(plan: SyncPlan, a: FilesApi, b: FilesApi, opts: SyncOptions): AsyncIterable<SyncEvent>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,KAAK,EAGV,SAAS,EAET,WAAW,EACX,QAAQ,EAGT,MAAM,YAAY,CAAC;AA+EpB,wBAAuB,OAAO,CAC5B,IAAI,EAAE,QAAQ,EACd,CAAC,EAAE,QAAQ,EACX,CAAC,EAAE,QAAQ,EACX,IAAI,EAAE,WAAW,GAChB,aAAa,CAAC,SAAS,CAAC,CA4C1B"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @statewalker/webrun-files-sync
+ *
+ * rclone-like file-synchronisation engine (copy / sync / bisync / move / check)
+ * over two `@statewalker/webrun-files` endpoints. Plan-then-execute: {@link plan}
+ * is pure and produces a serializable {@link SyncPlan}; {@link execute} applies
+ * it, verifying and resuming. Bidirectional sync is a three-way merge over a
+ * sync-owned anchor, delegated to `@statewalker/webrun-merge`.
+ *
+ * Domain-neutral: this package imports ONLY webrun-files + webrun-merge and knows
+ * nothing about git or versioning (Axis A / Axis B ban).
+ */
+export { buildAnchor } from "./anchor.js";
+export { isChanged, snapshot } from "./change-detection.js";
+export { execute } from "./execute.js";
+export { plan } from "./plan.js";
+export { createStreamingTransfer } from "./transfer.js";
+export type { AnchorStore, ByteStream, CheckpointStore, FilesApi, PathFilter, Resolution, SyncAction, SyncAnchor, SyncConflict, SyncEvent, SyncOp, SyncOptions, SyncPlan, Transfer, VerificationMode, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,SAAS,EACT,MAAM,EACN,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,422 @@
+import { merge } from "@statewalker/webrun-merge";
+//#region src/anchor.ts
+/** Build a fresh anchor manifest by hashing every file in an endpoint. */
+async function buildAnchor(files, hashContent) {
+	const entries = {};
+	for await (const info of files.list("/", { recursive: true })) {
+		if (info.kind !== "file") continue;
+		entries[info.path] = {
+			contentId: await hashContent(files.read(info.path)),
+			size: info.size ?? 0,
+			mtime: info.lastModified ?? 0
+		};
+	}
+	return { entries };
+}
+/**
+* A read-only base tree reconstructed from a {@link SyncAnchor}.
+*
+* Contract decision 1: the anchor stores NO base bytes. Base content is resolved
+* ON DEMAND by content-id from whichever live endpoint still holds it (both `a`
+* and `b` are searched, hashing lazily). When no endpoint holds the id — i.e.
+* both sides changed the file — `read` yields nothing, and the both-modified
+* path resolves to a conflict in webrun-merge rather than a bogus merge.
+*/
+function anchorBaseView(anchor, a, b, hashContent) {
+	let index;
+	const wanted = new Set(Object.values(anchor.entries).map((e) => e.contentId));
+	async function buildIndex() {
+		const map = /* @__PURE__ */ new Map();
+		for (const api of [a, b]) for await (const info of api.list("/", { recursive: true })) {
+			if (info.kind !== "file") continue;
+			const id = await hashContent(api.read(info.path));
+			if (wanted.has(id) && !map.has(id)) map.set(id, {
+				api,
+				path: info.path
+			});
+		}
+		return map;
+	}
+	async function locate(path) {
+		const entry = anchor.entries[path];
+		if (!entry) return void 0;
+		if (!index) index = await buildIndex();
+		return index.get(entry.contentId);
+	}
+	const readOnly = (op) => async () => {
+		throw new Error(`anchor base view is read-only (${op})`);
+	};
+	return {
+		async *read(path, _options) {
+			const loc = await locate(path);
+			if (!loc) return;
+			yield* loc.api.read(loc.path);
+		},
+		async *list(path, options) {
+			const prefix = path === "/" ? "/" : `${path}/`;
+			for (const [p, e] of Object.entries(anchor.entries)) {
+				if (p !== path && !p.startsWith(prefix)) continue;
+				if (!options?.recursive && p.slice(prefix.length).includes("/")) continue;
+				yield {
+					name: p.slice(p.lastIndexOf("/") + 1),
+					path: p,
+					kind: "file",
+					size: e.size,
+					lastModified: e.mtime
+				};
+			}
+		},
+		async stats(path) {
+			const e = anchor.entries[path];
+			return e ? {
+				kind: "file",
+				size: e.size,
+				lastModified: e.mtime
+			} : void 0;
+		},
+		async exists(path) {
+			return path in anchor.entries;
+		},
+		write: readOnly("write"),
+		mkdir: readOnly("mkdir"),
+		remove: readOnly("remove"),
+		move: readOnly("move"),
+		copy: readOnly("copy")
+	};
+}
+//#endregion
+//#region src/change-detection.ts
+/** List a whole tree into a path-keyed snapshot, applying an optional filter. */
+async function snapshot(files, filter) {
+	const map = /* @__PURE__ */ new Map();
+	for await (const info of files.list("/", { recursive: true })) {
+		if (filter && info.kind === "file" && !filter(info.path)) continue;
+		map.set(info.path, {
+			path: info.path,
+			kind: info.kind,
+			size: info.kind === "file" ? info.size : void 0,
+			mtime: info.kind === "file" ? info.lastModified : void 0
+		});
+	}
+	return map;
+}
+const HEAD_TAIL = 64;
+/** Read a bounded byte range as a single buffer (for fingerprint sampling). */
+async function readRange(files, path, start, length) {
+	const parts = [];
+	for await (const chunk of files.read(path, {
+		start,
+		length
+	})) parts.push(chunk);
+	const total = parts.reduce((n, p) => n + p.length, 0);
+	const out = new Uint8Array(total);
+	let off = 0;
+	for (const p of parts) {
+		out.set(p, off);
+		off += p.length;
+	}
+	return out;
+}
+function bytesEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+/** head+tail sample of a file, used by the optional quick-fingerprint rung. */
+async function fingerprint(files, path, size) {
+	if (size <= 128) return readRange(files, path, 0, size);
+	const head = await readRange(files, path, 0, HEAD_TAIL);
+	const tail = await readRange(files, path, size - HEAD_TAIL, HEAD_TAIL);
+	const out = new Uint8Array(head.length + tail.length);
+	out.set(head, 0);
+	out.set(tail, head.length);
+	return out;
+}
+/**
+* Decide whether `from`'s file at `path` differs from `to`'s file, climbing the
+* ladder only as far as needed. `fromEntry` must exist; `toEntry` may be absent.
+*/
+async function isChanged(from, to, path, fromEntry, toEntry, opts) {
+	if (!toEntry) return true;
+	if (fromEntry.kind !== toEntry.kind) return true;
+	if (fromEntry.kind === "directory") return false;
+	if (fromEntry.size !== toEntry.size) return true;
+	if (fromEntry.mtime !== void 0 && toEntry.mtime !== void 0 && fromEntry.mtime === toEntry.mtime) return false;
+	const size = fromEntry.size ?? 0;
+	if (opts.quickFingerprint) {
+		const [fa, fb] = await Promise.all([fingerprint(from, path, size), fingerprint(to, path, size)]);
+		if (!bytesEqual(fa, fb)) return true;
+	}
+	const [ha, hb] = await Promise.all([opts.hashContent(from.read(path)), opts.hashContent(to.read(path))]);
+	return ha !== hb;
+}
+//#endregion
+//#region src/transfer.ts
+function createStreamingTransfer() {
+	return { async run(action, from, to) {
+		if (action.kind !== "copy" && action.kind !== "update") throw new Error(`streaming transfer only handles copy/update, got ${action.kind}`);
+		const path = action.path;
+		if (from === to) {
+			await from.copy(path, path);
+			return;
+		}
+		await to.write(path, from.read(path));
+	} };
+}
+//#endregion
+//#region src/execute.ts
+async function verifyCopy(mode, source, dest, path, hashContent) {
+	if (mode === "content-hash" || mode === "backend-hash" || mode === "read-after-write") {
+		if (!await dest.stats(path)) return false;
+		const [hs, hd] = await Promise.all([hashContent(source.read(path)), hashContent(dest.read(path))]);
+		return hs === hd;
+	}
+	const [s, d] = await Promise.all([source.stats(path), dest.stats(path)]);
+	return !!s && !!d && sizeOf(s) === sizeOf(d);
+}
+/** Byte length of a file; `undefined` for a directory (two directories compare equal). */
+function sizeOf(stats) {
+	return stats.kind === "file" ? stats.size : void 0;
+}
+async function applyAction(action, a, b, op, transfer, verify, opts) {
+	const pick = (s) => s === "a" ? a : b;
+	switch (action.kind) {
+		case "mkdir":
+			await b.mkdir(action.path);
+			return { ok: true };
+		case "copy":
+		case "update": {
+			const from = pick(action.from);
+			const to = action.from === "a" ? b : a;
+			await transfer.run(action, from, to);
+			return await verifyCopy(verify, from, to, action.path, opts.hashContent) ? { ok: true } : {
+				ok: false,
+				reason: "destination verification failed"
+			};
+		}
+		case "move":
+			await pick(action.side).move(action.from, action.to);
+			return { ok: true };
+		case "delete":
+			if (op === "move" && action.side === "a") {
+				if (!await verifyCopy(verify, a, b, action.path, opts.hashContent)) return {
+					ok: false,
+					skipped: true,
+					reason: "destination not verified; source retained"
+				};
+				await a.remove(action.path);
+				return { ok: true };
+			}
+			await pick(action.side).remove(action.path);
+			return { ok: true };
+	}
+}
+async function* execute(plan, a, b, opts) {
+	const transfer = opts.transfer ?? createStreamingTransfer();
+	const verify = opts.verify ?? "size";
+	for (const message of plan.warnings ?? []) yield {
+		type: "warning",
+		message
+	};
+	for (const conflict of plan.conflicts) yield {
+		type: "conflict",
+		conflict
+	};
+	if (plan.op === "check") return;
+	const done = await opts.checkpoint?.read() ?? /* @__PURE__ */ new Set();
+	let anyFailure = false;
+	for (let i = 0; i < plan.actions.length; i++) {
+		if (done.has(i)) continue;
+		const action = plan.actions[i];
+		yield {
+			type: "start",
+			index: i,
+			action
+		};
+		try {
+			const outcome = await applyAction(action, a, b, plan.op, transfer, verify, opts);
+			if (!outcome.ok) {
+				anyFailure = true;
+				const reason = outcome.reason ?? "failed";
+				yield outcome.skipped ? {
+					type: "skipped",
+					index: i,
+					action,
+					reason
+				} : {
+					type: "failed",
+					index: i,
+					action,
+					reason
+				};
+				continue;
+			}
+			await opts.checkpoint?.add(i);
+			yield {
+				type: "done",
+				index: i,
+				action
+			};
+		} catch (error) {
+			anyFailure = true;
+			yield {
+				type: "failed",
+				index: i,
+				action,
+				reason: String(error?.message ?? error)
+			};
+		}
+	}
+	if (plan.op === "bisync" && !anyFailure && plan.conflicts.length === 0 && opts.anchorStore) await opts.anchorStore.write(opts.pairKey ?? "default", await buildAnchor(a, opts.hashContent));
+}
+//#endregion
+//#region src/bisync.ts
+const alwaysConflictMerger = { merge: () => ({ conflict: true }) };
+async function planBisync(a, b, opts) {
+	const pairKey = opts.pairKey ?? "default";
+	const anchor = await opts.anchorStore?.read(pairKey);
+	if (!anchor) return planUnion(a, b, opts);
+	const base = anchorBaseView(anchor, a, b, opts.hashContent);
+	const result = await merge(base, a, b, {
+		hashContent: opts.hashContent,
+		contentMerger: alwaysConflictMerger,
+		resolve: opts.resolve
+	});
+	const [snapA, snapB] = await Promise.all([snapshot(a, opts.filter), snapshot(b, opts.filter)]);
+	const actions = [];
+	for (const op of result.operations) switch (op.op) {
+		case "add":
+		case "modify": {
+			if (!op.source) throw new Error(`bisync cannot apply an inline-content ${op.op} for ${op.path}`);
+			const from = op.source.side === "left" ? "a" : "b";
+			actions.push({
+				kind: op.op === "add" ? "copy" : "update",
+				path: op.path,
+				from
+			});
+			break;
+		}
+		case "delete":
+			if (snapA.has(op.path)) actions.push({
+				kind: "delete",
+				path: op.path,
+				side: "a"
+			});
+			if (snapB.has(op.path)) actions.push({
+				kind: "delete",
+				path: op.path,
+				side: "b"
+			});
+			break;
+		case "rename": {
+			const from = op.from;
+			if (snapA.has(from)) actions.push({
+				kind: "move",
+				from,
+				to: op.path,
+				side: "a"
+			});
+			if (snapB.has(from)) actions.push({
+				kind: "move",
+				from,
+				to: op.path,
+				side: "b"
+			});
+			break;
+		}
+	}
+	return {
+		op: "bisync",
+		actions,
+		conflicts: result.conflicts
+	};
+}
+/** Conservative union used for the first bisync (no anchor yet). */
+async function planUnion(a, b, opts) {
+	const [snapA, snapB] = await Promise.all([snapshot(a, opts.filter), snapshot(b, opts.filter)]);
+	const actions = [];
+	const conflicts = [];
+	for (const [path, entry] of snapA) {
+		if (entry.kind !== "file") continue;
+		const other = snapB.get(path);
+		if (!other) actions.push({
+			kind: "copy",
+			path,
+			from: "a"
+		});
+		else if (await isChanged(a, b, path, entry, other, opts)) conflicts.push({
+			kind: "content",
+			path,
+			left: {
+				path,
+				kind: "file"
+			},
+			right: {
+				path,
+				kind: "file"
+			}
+		});
+	}
+	for (const [path, entry] of snapB) {
+		if (entry.kind !== "file") continue;
+		if (!snapA.has(path)) actions.push({
+			kind: "copy",
+			path,
+			from: "b"
+		});
+	}
+	return {
+		op: "bisync",
+		actions,
+		conflicts,
+		warnings: ["no sync anchor; performing conservative union (additions only, no deletions)"]
+	};
+}
+//#endregion
+//#region src/plan.ts
+async function plan(a, b, op, opts) {
+	if (op === "bisync") return planBisync(a, b, opts);
+	const [snapA, snapB] = await Promise.all([snapshot(a, opts.filter), snapshot(b, opts.filter)]);
+	const actions = [];
+	for (const [path, entry] of snapA) {
+		const other = snapB.get(path);
+		if (entry.kind === "directory") {
+			if (!other) actions.push({
+				kind: "mkdir",
+				path
+			});
+			continue;
+		}
+		if (!other) actions.push({
+			kind: "copy",
+			path,
+			from: "a"
+		});
+		else if (await isChanged(a, b, path, entry, other, opts)) actions.push({
+			kind: "update",
+			path,
+			from: "a"
+		});
+	}
+	if (op === "move") {
+		for (const [path, entry] of snapA) if (entry.kind === "file") actions.push({
+			kind: "delete",
+			path,
+			side: "a"
+		});
+	}
+	if (op === "sync") {
+		for (const [path, entry] of snapB) if (entry.kind === "file" && !snapA.has(path)) actions.push({
+			kind: "delete",
+			path,
+			side: "b"
+		});
+	}
+	return {
+		op,
+		actions,
+		conflicts: []
+	};
+}
+//#endregion
+export { buildAnchor, createStreamingTransfer, execute, isChanged, plan, snapshot };

package/dist/plan.d.ts

@@ -0,0 +1,15 @@
+/**
+ * {@link plan} — pure planning for all sync operations. It reads both endpoints
+ * (listing, and hashing only when the ladder demands it) but MUTATES NEITHER.
+ *
+ *   copy   — new/changed A files → B; extraneous B files KEPT.
+ *   sync   — copy, plus extraneous B files DELETED.
+ *   move   — copy each A file, then (at execute, after the destination is
+ *            verified) delete the source; source is never lost.
+ *   check  — the copy diff, transferring nothing (execute is a no-op).
+ *   bisync — three-way merge over the anchor (see bisync.ts).
+ */
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { SyncOp, SyncOptions, SyncPlan } from "./types.js";
+export declare function plan(a: FilesApi, b: FilesApi, op: SyncOp, opts: SyncOptions): Promise<SyncPlan>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,KAAK,EAAc,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5E,wBAAsB,IAAI,CACxB,CAAC,EAAE,QAAQ,EACX,CAAC,EAAE,QAAQ,EACX,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,QAAQ,CAAC,CAqCnB"}

package/dist/transfer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The default {@link Transfer}: a whole-file copy.
+ *
+ * When source and destination are the SAME backend instance, it uses the
+ * backend's native server-side `copy` ("capabilities allow"). Across two
+ * distinct backends — the normal sync case, and all MemFilesApi pairs — it falls
+ * back to streaming the bytes through `to.write(from.read(...))`.
+ *
+ * A later phase can plug a chunk-dedup Transfer into this same seam.
+ */
+import type { Transfer } from "./types.js";
+export declare function createStreamingTransfer(): Transfer;
+//# sourceMappingURL=transfer.d.ts.map

package/dist/transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../src/transfer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAgB,uBAAuB,IAAI,QAAQ,CAelD"}