@filen/sync 0.2.1 → 0.3.2

package/tests/unit/collapse-deltas.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect } from "vitest"
+import { collapseDeltas, directoriesWithSurvivingChildren, type Delta } from "../../src/lib/deltas"
+
+/**
+ * Direct unit coverage for the delta-collapse pass (deltas.ts). The full-cycle scenario net
+ * (tests/scenarios/r-rename-stress.test.ts) can only observe convergence after the engine re-runs and
+ * self-heals, which masks a corrupt FIRST cycle. These tests assert the collapse output directly, so a
+ * dropped or duplicated op is caught even when a later cycle would have papered over it.
+ *
+ * The headline case is BUG-004's deterministic half: a child under TWO overlapping renamed parents, in
+ * the array ordering that made the previous in-place splice clobber an unrelated delta.
+ */
+const empty = {
+	renamedLocalDirectories: [] as Delta[],
+	renamedRemoteDirectories: [] as Delta[],
+	deletedLocalDirectories: [] as Delta[],
+	deletedRemoteDirectories: [] as Delta[]
+}
+
+describe("collapseDeltas", () => {
+	it("drops a child carried by its most-specific parent without clobbering an unrelated delta (specific-first ordering)", () => {
+		// /a -> /x AND /a/b -> /x/y both cover /a/b/c.txt. /unrelated.txt is an independent rename that
+		// must survive untouched. The most-specific parent is listed FIRST — the exact ordering under
+		// which the old splice-in-place loop removed slot i then overwrote the delta that shifted into it,
+		// silently dropping /unrelated.txt and emitting a bogus duplicate rename of the child.
+		const deltas: Delta[] = [
+			{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" },
+			{ type: "renameLocalDirectory", path: "/a/b", from: "/a/b", to: "/x/y" },
+			{ type: "renameLocalFile", path: "/a/b/c.txt", from: "/a/b/c.txt", to: "/x/y/c.txt" },
+			{ type: "renameLocalFile", path: "/unrelated.txt", from: "/unrelated.txt", to: "/renamed.txt" }
+		]
+		const renamedLocalDirectories: Delta[] = [
+			{ type: "renameLocalDirectory", path: "/a/b", from: "/a/b", to: "/x/y" },
+			{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" }
+		]
+
+		const out = collapseDeltas({ ...empty, deltas, renamedLocalDirectories })
+
+		// The unrelated rename survives byte-for-byte.
+		expect(out).toContainEqual({ type: "renameLocalFile", path: "/unrelated.txt", from: "/unrelated.txt", to: "/renamed.txt" })
+		// The child is fully carried by its immediate parent dir rename — dropped, not duplicated.
+		expect(out.find(delta => delta.path === "/a/b/c.txt")).toBeUndefined()
+		expect(out.filter(delta => "to" in delta && delta.to === "/x/y/c.txt")).toEqual([])
+		// The nested dir rename is rewritten to its post-/a-rename source.
+		expect(out).toContainEqual({ type: "renameLocalDirectory", path: "/a/b", from: "/x/b", to: "/x/y" })
+		// Exactly three ops remain: the top rename, the rewritten nested rename, the unrelated rename.
+		expect(out).toHaveLength(3)
+	})
+
+	it("is order-independent: general-first parent ordering yields the identical collapse", () => {
+		const deltas: Delta[] = [
+			{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" },
+			{ type: "renameLocalDirectory", path: "/a/b", from: "/a/b", to: "/x/y" },
+			{ type: "renameLocalFile", path: "/a/b/c.txt", from: "/a/b/c.txt", to: "/x/y/c.txt" },
+			{ type: "renameLocalFile", path: "/unrelated.txt", from: "/unrelated.txt", to: "/renamed.txt" }
+		]
+		const renamedLocalDirectories: Delta[] = [
+			{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" },
+			{ type: "renameLocalDirectory", path: "/a/b", from: "/a/b", to: "/x/y" }
+		]
+
+		const out = collapseDeltas({ ...empty, deltas, renamedLocalDirectories })
+
+		expect(out).toContainEqual({ type: "renameLocalFile", path: "/unrelated.txt", from: "/unrelated.txt", to: "/renamed.txt" })
+		expect(out.find(delta => delta.path === "/a/b/c.txt")).toBeUndefined()
+		expect(out).toContainEqual({ type: "renameLocalDirectory", path: "/a/b", from: "/x/b", to: "/x/y" })
+		expect(out).toHaveLength(3)
+	})
+
+	it("rewrites (does not drop) a child rename whose target differs from the parent-implied location", () => {
+		// The parent dir rename carries the file to /x/c.txt, but the user ALSO renamed the file itself,
+		// so an explicit rename from the post-parent-rename source must remain.
+		const deltas: Delta[] = [
+			{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" },
+			{ type: "renameLocalFile", path: "/a/c.txt", from: "/a/c.txt", to: "/x/renamed.txt" }
+		]
+		const renamedLocalDirectories: Delta[] = [{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" }]
+
+		const out = collapseDeltas({ ...empty, deltas, renamedLocalDirectories })
+
+		expect(out).toContainEqual({ type: "renameLocalFile", path: "/a/c.txt", from: "/x/c.txt", to: "/x/renamed.txt" })
+		expect(out).toHaveLength(2)
+	})
+
+	it("leaves a rename with no covering parent untouched", () => {
+		const deltas: Delta[] = [{ type: "renameLocalFile", path: "/loose.txt", from: "/loose.txt", to: "/moved.txt" }]
+
+		const out = collapseDeltas({ ...empty, deltas })
+
+		expect(out).toEqual(deltas)
+	})
+
+	it("collapses the remote rename side symmetrically", () => {
+		const deltas: Delta[] = [
+			{ type: "renameRemoteDirectory", path: "/a", from: "/a", to: "/x" },
+			{ type: "renameRemoteDirectory", path: "/a/b", from: "/a/b", to: "/x/y" },
+			{ type: "renameRemoteFile", path: "/a/b/c.txt", from: "/a/b/c.txt", to: "/x/y/c.txt" }
+		]
+		const renamedRemoteDirectories: Delta[] = [
+			{ type: "renameRemoteDirectory", path: "/a/b", from: "/a/b", to: "/x/y" },
+			{ type: "renameRemoteDirectory", path: "/a", from: "/a", to: "/x" }
+		]
+
+		const out = collapseDeltas({ ...empty, deltas, renamedRemoteDirectories })
+
+		expect(out.find(delta => delta.path === "/a/b/c.txt")).toBeUndefined()
+		expect(out).toContainEqual({ type: "renameRemoteDirectory", path: "/a/b", from: "/x/b", to: "/x/y" })
+		expect(out).toHaveLength(2)
+	})
+
+	it("drops a child delete covered by an ancestor directory delete, keeping unrelated deletes", () => {
+		const deltas: Delta[] = [
+			{ type: "deleteLocalDirectory", path: "/gone" },
+			{ type: "deleteLocalFile", path: "/gone/inner.txt" },
+			{ type: "deleteLocalDirectory", path: "/gone/sub" },
+			{ type: "deleteLocalFile", path: "/gone/sub/deep.txt" },
+			{ type: "deleteLocalFile", path: "/keep-deleted.txt" }
+		]
+		const deletedLocalDirectories: Delta[] = [
+			{ type: "deleteLocalDirectory", path: "/gone" },
+			{ type: "deleteLocalDirectory", path: "/gone/sub" }
+		]
+
+		const out = collapseDeltas({ ...empty, deltas, deletedLocalDirectories })
+
+		// Only the top-level dir delete and the unrelated file delete survive.
+		expect(out).toEqual([
+			{ type: "deleteLocalDirectory", path: "/gone" },
+			{ type: "deleteLocalFile", path: "/keep-deleted.txt" }
+		])
+	})
+
+	it("drops a child remote delete covered by an ancestor remote directory delete", () => {
+		const deltas: Delta[] = [
+			{ type: "deleteRemoteDirectory", path: "/gone" },
+			{ type: "deleteRemoteFile", path: "/gone/inner.txt" },
+			{ type: "deleteRemoteFile", path: "/keep.txt" }
+		]
+		const deletedRemoteDirectories: Delta[] = [{ type: "deleteRemoteDirectory", path: "/gone" }]
+
+		const out = collapseDeltas({ ...empty, deltas, deletedRemoteDirectories })
+
+		expect(out).toEqual([
+			{ type: "deleteRemoteDirectory", path: "/gone" },
+			{ type: "deleteRemoteFile", path: "/keep.txt" }
+		])
+	})
+
+	it("passes non-rename / non-delete deltas through unchanged", () => {
+		const deltas: Delta[] = [
+			{ type: "uploadFile", path: "/up.txt", size: 12 },
+			{ type: "downloadFile", path: "/down.txt", size: 34 },
+			{ type: "createRemoteDirectory", path: "/newdir" },
+			{ type: "createLocalDirectory", path: "/newlocal" }
+		]
+		const renamedLocalDirectories: Delta[] = [{ type: "renameLocalDirectory", path: "/a", from: "/a", to: "/x" }]
+
+		const out = collapseDeltas({ ...empty, deltas, renamedLocalDirectories })
+
+		expect(out).toEqual(deltas)
+	})
+
+	it("does not treat a sibling-prefix path as a child (no false prefix match)", () => {
+		// "/abc" must NOT be collapsed under a rename of "/ab" — the boundary "/" guards against this.
+		const deltas: Delta[] = [{ type: "renameLocalFile", path: "/abc.txt", from: "/abc.txt", to: "/abc2.txt" }]
+		const renamedLocalDirectories: Delta[] = [{ type: "renameLocalDirectory", path: "/ab", from: "/ab", to: "/zz" }]
+
+		const out = collapseDeltas({ ...empty, deltas, renamedLocalDirectories })
+
+		expect(out).toEqual(deltas)
+	})
+
+	it("collapses a large wide directory move to the single parent rename (ancestor-walk correctness + scale)", () => {
+		// A realistic large move: /src -> /dst with many subdirectories, each holding many files. Every child
+		// must fold into its nearest renamed-directory ancestor, leaving ONLY the top-level rename. This both
+		// checks the indexed ancestor-walk on a large input and acts as a tripwire for a return to the old
+		// O(deltas * directories * pathLength) scan, which on this input ran for MINUTES — far past the test
+		// runner's timeout — where the indexed version finishes in milliseconds. (P1)
+		const deltas: Delta[] = []
+		const renamedLocalDirectories: Delta[] = []
+		const top: Delta = { type: "renameLocalDirectory", path: "/src", from: "/src", to: "/dst" }
+
+		deltas.push(top)
+		renamedLocalDirectories.push(top)
+
+		for (let s = 0; s < 300; s++) {
+			const fromDir = `/src/sub${s}`
+			const toDir = `/dst/sub${s}`
+			const dirRename: Delta = { type: "renameLocalDirectory", path: fromDir, from: fromDir, to: toDir }
+
+			deltas.push(dirRename)
+			renamedLocalDirectories.push(dirRename)
+
+			for (let f = 0; f < 100; f++) {
+				const from = `${fromDir}/f${f}.txt`
+				const to = `${toDir}/f${f}.txt`
+
+				deltas.push({ type: "renameLocalFile", path: from, from, to })
+			}
+		}
+
+		// 1 top rename + 300 subdir renames + 30000 file renames.
+		expect(deltas.length).toBe(30301)
+
+		const out = collapseDeltas({ ...empty, deltas, renamedLocalDirectories })
+
+		// Everything collapses into /src -> /dst: each subdir rename rewrites to /dst/subN (== its target, so
+		// redundant) and each file folds into its subdir which folds into /src.
+		expect(out).toEqual([{ type: "renameLocalDirectory", path: "/src", from: "/src", to: "/dst" }])
+	})
+})
+
+/**
+ * Direct coverage for the dir-delete-vs-live-child guard (H5). A directory slated for deletion must be
+ * KEPT (its delete dropped) when this side still holds a child that is neither deleted nor renamed away.
+ */
+describe("directoriesWithSurvivingChildren", () => {
+	const tree = (paths: string[]): Record<string, unknown> => Object.fromEntries(paths.map(path => [path, {}]))
+
+	const keepFor = (deltas: Delta[], paths: string[]): Set<string> =>
+		directoriesWithSurvivingChildren(deltas, "deleteRemoteDirectory", "deleteRemoteFile", "renameRemoteDirectory", "renameRemoteFile", tree(paths))
+
+	it("keeps a deleted directory that still holds a brand-new (non-deleted) child", () => {
+		const deltas: Delta[] = [{ type: "deleteRemoteDirectory", path: "/dir" }]
+		// /dir/new.txt exists in the tree and is NOT being deleted → it keeps /dir alive.
+		expect([...keepFor(deltas, ["/dir", "/dir/new.txt", "/other.txt"])]).toEqual(["/dir"])
+	})
+
+	it("does NOT keep a directory whose only child is being renamed out", () => {
+		const deltas: Delta[] = [
+			{ type: "deleteRemoteDirectory", path: "/dir" },
+			{ type: "renameRemoteFile", path: "/dir2/c.txt", from: "/dir/c.txt", to: "/dir2/c.txt" }
+		]
+		// /dir/c.txt is leaving via a rename, so /dir has nothing live → it is deleted (empty set).
+		expect([...keepFor(deltas, ["/dir", "/dir/c.txt"])]).toEqual([])
+	})
+
+	it("does NOT keep a directory whose children are all being deleted", () => {
+		const deltas: Delta[] = [
+			{ type: "deleteRemoteDirectory", path: "/dir" },
+			{ type: "deleteRemoteFile", path: "/dir/a.txt" }
+		]
+		expect([...keepFor(deltas, ["/dir", "/dir/a.txt"])]).toEqual([])
+	})
+
+	it("keeps an ancestor when a deep descendant survives, but not when an ancestor is renamed away", () => {
+		const survivingDeep: Delta[] = [{ type: "deleteRemoteDirectory", path: "/dir" }]
+		// A surviving grandchild keeps the top directory.
+		expect([...keepFor(survivingDeep, ["/dir", "/dir/sub/leaf.txt"])]).toEqual(["/dir"])
+
+		// But if the intermediate dir is renamed away, the whole subtree leaves and keeps nothing.
+		const renamedAway: Delta[] = [
+			{ type: "deleteRemoteDirectory", path: "/dir" },
+			{ type: "renameRemoteDirectory", path: "/moved", from: "/dir/sub", to: "/moved" }
+		]
+		expect([...keepFor(renamedAway, ["/dir", "/dir/sub/leaf.txt"])]).toEqual([])
+	})
+
+	it("returns an empty set when nothing is being deleted", () => {
+		expect(keepFor([{ type: "renameRemoteFile", path: "/b", from: "/a", to: "/b" }], ["/a"]).size).toBe(0)
+	})
+
+	it("scopes to the requested direction (a remote delete is invisible to the local-typed query)", () => {
+		const deltas: Delta[] = [{ type: "deleteRemoteDirectory", path: "/dir" }]
+		const localKeep = directoriesWithSurvivingChildren(
+			deltas,
+			"deleteLocalDirectory",
+			"deleteLocalFile",
+			"renameLocalDirectory",
+			"renameLocalFile",
+			tree(["/dir", "/dir/new.txt"])
+		)
+
+		expect(localKeep.size).toBe(0)
+	})
+})

package/tests/unit/dir-tree.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi } from "vitest"
+import { pack } from "msgpackr"
+import { fetchDirTreeMsgpack, DIR_TREE_GATEWAY_URLS, type DirTreeSDK } from "../../src/lib/filesystems/dirTree"
+
+/**
+ * Direct unit coverage for the production msgpack reimplementation of `/v3/dir/tree`. Every sync
+ * scenario routes the fetch through the fake cloud's SDK, so this is the ONLY place the real transport
+ * (JSON body, msgpack response decode, envelope handling, gateway failover, backoff, abort) is
+ * exercised — Phase 3 then validates it end-to-end against the live API.
+ */
+function makeSDK(post: (...args: unknown[]) => unknown, apiKey: string | undefined = "test-key"): DirTreeSDK {
+	return { axiosInstance: { post }, config: { apiKey } } as unknown as DirTreeSDK
+}
+
+// A 200 response carrying the standard { status, data } envelope, msgpack-encoded as the server sends it.
+function ok(data: unknown): { status: number; data: Buffer } {
+	return { status: 200, data: pack({ status: true, data }) }
+}
+
+// Deterministic transport: no real waits, fixed gateway start index (0), no jitter.
+const deterministic = { sleep: async (): Promise<void> => {}, random: (): number => 0, baseRetryDelayMs: 0, maxRetryDelayMs: 0 }
+
+const sampleTree = {
+	files: [["fuuid", "bucket", "region", 1, "puuid", "fmeta", 2, 0]],
+	folders: [["root", "rmeta", "base"]]
+}
+
+describe("fetchDirTreeMsgpack", () => {
+	it("POSTs a JSON body and decodes the msgpack response into the same shape the SDK returns", async () => {
+		const post = vi.fn().mockResolvedValue(ok(sampleTree))
+		const sdk = makeSDK(post)
+
+		const result = await fetchDirTreeMsgpack(sdk, { uuid: "parent-uuid", deviceId: "dev-1", skipCache: false }, deterministic)
+
+		expect(result.files).toEqual(sampleTree.files)
+		expect(result.folders).toEqual(sampleTree.folders)
+
+		const [url, body, config] = post.mock.calls[0]!
+
+		expect(url).toBe(`${DIR_TREE_GATEWAY_URLS[0]}/v3/dir/tree`)
+		// Body stays JSON; skipCache encoded as 0/1 exactly like the SDK.
+		expect(body).toEqual({ uuid: "parent-uuid", deviceId: "dev-1", skipCache: 0 })
+		expect(config.responseType).toBe("arraybuffer")
+		expect(config.headers.Authorization).toBe("Bearer test-key")
+		expect(config.headers.Accept).toBe("application/msgpack")
+		expect(config.headers["Content-Type"]).toBe("application/json")
+		// The response transform must be a pure passthrough so the binary body is never copied/parsed.
+		const raw = Buffer.from([1, 2, 3])
+		expect(config.transformResponse(raw)).toBe(raw)
+	})
+
+	it("encodes skipCache:true as 1", async () => {
+		const post = vi.fn().mockResolvedValue(ok(sampleTree))
+
+		await fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: true }, deterministic)
+
+		expect(post.mock.calls[0]![1]).toEqual({ uuid: "u", deviceId: "d", skipCache: 1 })
+	})
+
+	it("falls back to the anonymous API key when none is configured", async () => {
+		const post = vi.fn().mockResolvedValue(ok(sampleTree))
+		// Build the SDK with no apiKey at all (a default param can't model "explicitly absent").
+		const sdk = { axiosInstance: { post }, config: {} } as unknown as DirTreeSDK
+
+		await fetchDirTreeMsgpack(sdk, { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+
+		expect(post.mock.calls[0]![2].headers.Authorization).toBe("Bearer anonymous")
+	})
+
+	it("preserves the deviceId-cache contract: an unchanged tree (empty arrays) passes straight through", async () => {
+		// The server returns empty files/folders when nothing changed for this deviceId; the fetcher must
+		// surface that verbatim so remote.ts can read it as "reuse my cache".
+		const post = vi.fn().mockResolvedValue(ok({ files: [], folders: [] }))
+
+		const result = await fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+
+		expect(result.files).toEqual([])
+		expect(result.folders).toEqual([])
+	})
+
+	it("accepts a bare (un-enveloped) decoded object", async () => {
+		const post = vi.fn().mockResolvedValue({ status: 200, data: pack(sampleTree) })
+
+		const result = await fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+
+		expect(result.folders).toEqual(sampleTree.folders)
+	})
+
+	it("normalizes ArrayBuffer and Uint8Array response payloads", async () => {
+		const packed = pack({ status: true, data: sampleTree })
+		const asArrayBuffer = packed.buffer.slice(packed.byteOffset, packed.byteOffset + packed.byteLength)
+
+		const postAB = vi.fn().mockResolvedValue({ status: 200, data: asArrayBuffer })
+		const resultAB = await fetchDirTreeMsgpack(makeSDK(postAB), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+		expect(resultAB.folders).toEqual(sampleTree.folders)
+
+		const postU8 = vi.fn().mockResolvedValue({ status: 200, data: new Uint8Array(packed) })
+		const resultU8 = await fetchDirTreeMsgpack(makeSDK(postU8), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+		expect(resultU8.folders).toEqual(sampleTree.folders)
+	})
+
+	it("throws a DirTreeAPIError WITHOUT retrying on a status:false envelope", async () => {
+		const post = vi.fn().mockResolvedValue({ status: 200, data: pack({ status: false, code: "folder_not_found", message: "gone" }) })
+
+		await expect(fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)).rejects.toMatchObject({
+			name: "DirTreeAPIError",
+			code: "folder_not_found"
+		})
+		// Definitive error => exactly one attempt.
+		expect(post).toHaveBeenCalledTimes(1)
+	})
+
+	it("retries a transient failure on the NEXT gateway and succeeds", async () => {
+		const post = vi
+			.fn()
+			.mockRejectedValueOnce(new Error("ECONNRESET"))
+			.mockResolvedValueOnce(ok(sampleTree))
+
+		const result = await fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+
+		expect(result.folders).toEqual(sampleTree.folders)
+		expect(post).toHaveBeenCalledTimes(2)
+		// Gateway rotation: the retry must target a different host than the failed attempt.
+		expect(post.mock.calls[0]![0]).toBe(`${DIR_TREE_GATEWAY_URLS[0]}/v3/dir/tree`)
+		expect(post.mock.calls[1]![0]).toBe(`${DIR_TREE_GATEWAY_URLS[1]}/v3/dir/tree`)
+	})
+
+	it("treats a non-200 status as retryable", async () => {
+		const post = vi
+			.fn()
+			.mockResolvedValueOnce({ status: 503, data: null })
+			.mockResolvedValueOnce(ok(sampleTree))
+
+		const result = await fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, deterministic)
+
+		expect(result.folders).toEqual(sampleTree.folders)
+		expect(post).toHaveBeenCalledTimes(2)
+	})
+
+	it("gives up after maxTries and throws the last error", async () => {
+		const post = vi.fn().mockRejectedValue(new Error("network down"))
+
+		await expect(
+			fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, { ...deterministic, maxTries: 3 })
+		).rejects.toThrow("network down")
+		expect(post).toHaveBeenCalledTimes(3)
+	})
+
+	it("aborts immediately without making a request when the signal is already aborted", async () => {
+		const post = vi.fn().mockResolvedValue(ok(sampleTree))
+		const controller = new AbortController()
+		controller.abort()
+
+		await expect(
+			fetchDirTreeMsgpack(makeSDK(post), { uuid: "u", deviceId: "d", skipCache: false }, { ...deterministic, abortSignal: controller.signal })
+		).rejects.toThrow("Aborted")
+		expect(post).not.toHaveBeenCalled()
+	})
+})

package/tests/unit/icloud.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, afterEach } from "vitest"
+
+/**
+ * Unit coverage for the iCloud-backed-path detection in `src/utils.ts`
+ * (`pathSyncedByICloud` / `isPathSyncedByICloud`). These warn the user when a sync pair points at a
+ * folder iCloud is also managing. The darwin path shells out to `xattr` via execFile; we mock
+ * `child_process.execFile` so the probe is deterministic (no real `xattr`, no real filesystem) and
+ * exercise both the provider-attribute match and the ancestry walk.
+ */
+const { execMock } = vi.hoisted(() => ({ execMock: vi.fn() }))
+
+vi.mock("child_process", async importOriginal => {
+	const actual = await importOriginal<typeof import("child_process")>()
+
+	return { ...actual, execFile: execMock }
+})
+
+import { pathSyncedByICloud, isPathSyncedByICloud } from "../../src/utils"
+
+/** Run `fn` with `process.platform` temporarily forced to `platform`, restoring it afterwards. */
+async function withPlatform(platform: NodeJS.Platform, fn: () => Promise<void>): Promise<void> {
+	const original = Object.getOwnPropertyDescriptor(process, "platform")
+
+	Object.defineProperty(process, "platform", { value: platform, configurable: true })
+
+	try {
+		await fn()
+	} finally {
+		if (original) {
+			Object.defineProperty(process, "platform", original)
+		}
+	}
+}
+
+/** Drive the mocked `execFile` callback with a fixed `(err, stdout, stderr)` result for every invocation. */
+function execYields(err: Error | null, stdout: string, stderr: string): void {
+	execMock.mockImplementation((_file: string, _args: string[], callback: (e: Error | null, o: string, s: string) => void) => {
+		callback(err, stdout, stderr)
+	})
+}
+
+afterEach(() => {
+	execMock.mockReset()
+})
+
+describe("iCloud detection (utils)", () => {
+	it("pathSyncedByICloud short-circuits to false off darwin without probing xattr", async () => {
+		await withPlatform("linux", async () => {
+			expect(await pathSyncedByICloud("/home/user/docs")).toBe(false)
+		})
+
+		expect(execMock).not.toHaveBeenCalled()
+	})
+
+	it("pathSyncedByICloud is true when xattr lists a file-provider / iCloud attribute", async () => {
+		await withPlatform("darwin", async () => {
+			execYields(null, "com.apple.quarantine\ncom.apple.fileprovider.fpfs#P", "")
+
+			expect(await pathSyncedByICloud("/Users/me/Mobile Documents")).toBe(true)
+		})
+	})
+
+	it("pathSyncedByICloud is false when xattr lists only non-cloud attributes", async () => {
+		await withPlatform("darwin", async () => {
+			execYields(null, "com.apple.quarantine\nuser.custom", "")
+
+			expect(await pathSyncedByICloud("/Users/me/local")).toBe(false)
+		})
+	})
+
+	it("pathSyncedByICloud resolves false when xattr errors", async () => {
+		await withPlatform("darwin", async () => {
+			execYields(new Error("xattr: No such file"), "", "")
+
+			expect(await pathSyncedByICloud("/missing")).toBe(false)
+		})
+	})
+
+	it("pathSyncedByICloud resolves false when xattr writes to stderr", async () => {
+		await withPlatform("darwin", async () => {
+			execYields(null, "", "xattr: permission denied")
+
+			expect(await pathSyncedByICloud("/denied")).toBe(false)
+		})
+	})
+
+	it("isPathSyncedByICloud is false off darwin", async () => {
+		await withPlatform("win32", async () => {
+			expect(await isPathSyncedByICloud("/Users/me/x/y")).toBe(false)
+		})
+
+		expect(execMock).not.toHaveBeenCalled()
+	})
+
+	it("isPathSyncedByICloud walks up the ancestry and is true when an ANCESTOR is iCloud-backed", async () => {
+		await withPlatform("darwin", async () => {
+			// Only the grandparent directory carries the marker; the leaf and its parent do not.
+			execMock.mockImplementation((_file: string, args: string[], callback: (e: Error | null, o: string, s: string) => void) => {
+				const target = args[0]
+
+				callback(null, target === "/Users/me/iCloudDrive" ? "com.apple.icloud.marker" : "com.apple.quarantine", "")
+			})
+
+			expect(await isPathSyncedByICloud("/Users/me/iCloudDrive/docs/file.txt")).toBe(true)
+		})
+	})
+
+	it("isPathSyncedByICloud walks to the root and is false when nothing in the ancestry is iCloud-backed", async () => {
+		await withPlatform("darwin", async () => {
+			execYields(null, "com.apple.quarantine", "")
+
+			expect(await isPathSyncedByICloud("/Users/me/local/docs/file.txt")).toBe(false)
+		})
+	})
+})

package/tests/unit/ignorer-cache-regression.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest"
+import { createWorld } from "../harness/world"
+
+/**
+ * Added regression tests pinning the ignorer cache-preservation optimization: a per-cycle re-init
+ * (no passed content) with byte-for-byte unchanged rules must NOT wipe the filesystem ignoredCaches
+ * (that wipe defeated the cache and forced the whole tree's per-file ignore checks to recompute every
+ * cycle), while a real rule change MUST still clear them and update the decisions.
+ *
+ * NEW FILE — does not touch the existing Ignorer tests in tests/unit/ignorer.test.ts.
+ */
+describe("Ignorer — ignoredCache preservation across unchanged re-init (perf guard)", () => {
+	it("keeps the filesystem ignoredCache populated when re-init finds unchanged rules", async () => {
+		const world = await createWorld({ mode: "twoWay", filenIgnore: "*.log" })
+
+		// Populate the local FS ignore cache for a path.
+		world.sync.localFileSystem.isPathIgnored("/keep.txt", "/local/keep.txt", "file")
+
+		expect(world.sync.localFileSystem.ignoredCache.has("/keep.txt")).toBe(true)
+
+		// The per-cycle re-init path (no passed content) with identical rules must leave the cache intact.
+		await world.sync.ignorer.initialize()
+
+		expect(world.sync.localFileSystem.ignoredCache.has("/keep.txt")).toBe(true)
+		expect(world.sync.remoteFileSystem.ignoredCache).toBeDefined()
+	})
+
+	it("clears the cache and updates decisions when the rules change (explicit update)", async () => {
+		const world = await createWorld({ mode: "twoWay", filenIgnore: "*.log" })
+
+		world.sync.localFileSystem.isPathIgnored("/a.txt", "/local/a.txt", "file")
+
+		expect(world.sync.localFileSystem.ignoredCache.has("/a.txt")).toBe(true)
+		expect(world.sync.ignorer.ignores("a.txt")).toBe(false)
+
+		await world.sync.ignorer.update("*.txt")
+
+		// The cache was wiped (re-evaluation forced) and the new rule now applies.
+		expect(world.sync.localFileSystem.ignoredCache.has("/a.txt")).toBe(false)
+		expect(world.sync.ignorer.ignores("a.txt")).toBe(true)
+	})
+
+	it("picks up a physical .filenignore change on the next no-arg initialize", async () => {
+		const world = await createWorld({ mode: "twoWay", filenIgnore: "*.log" })
+
+		expect(world.sync.ignorer.ignores("a.txt")).toBe(false)
+
+		await world.vfs.fs.writeFile("/local/.filenignore", "*.txt", { encoding: "utf-8" })
+
+		// No passed content — exactly the per-cycle path — must still detect the on-disk change.
+		await world.sync.ignorer.initialize()
+
+		expect(world.sync.ignorer.ignores("a.txt")).toBe(true)
+	})
+
+	it("clear() then a same-content initialize() rebuilds the matcher (no stale empty matcher)", async () => {
+		const world = await createWorld({ mode: "twoWay", filenIgnore: "*.log" })
+
+		expect(world.sync.ignorer.ignores("a.log")).toBe(true)
+
+		world.sync.ignorer.clear()
+
+		expect(world.sync.ignorer.ignores("a.log")).toBe(false)
+
+		// Same content as before — the baseline reset in clear() must force a rebuild, not a skip.
+		await world.sync.ignorer.initialize()
+
+		expect(world.sync.ignorer.ignores("a.log")).toBe(true)
+	})
+})