@filen/sync 0.2.1 → 0.3.2

package/tests/scenarios/zk-ignore-asymmetry.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi } from "vitest"
+import { createWorld, BASE_TIME, type CreateWorldOptions, type World } from "../harness/world"
+import { type LocalItem, type LocalTree, type LocalTreeIgnored } from "../../src/lib/filesystems/local"
+import { type RemoteItem, type RemoteTree } from "../../src/lib/filesystems/remote"
+
+/**
+ * Category ZK — a remote deletion must not delete the LOCAL copy of a path that is IGNORED locally (M4).
+ *
+ * The local-deletions pass skips ignored paths (BUG-006): a path that is physically present locally but
+ * excluded from the scanned tree — over-long name, invalid path, a default-ignore that grew across an
+ * upgrade, a case-duplicate — must keep its cloud copy, never be reported as a deletion. The symmetric
+ * remote-deletions pass had no such guard: when that same ignored path's REMOTE copy was deleted, it
+ * emitted deleteLocal* and wiped the on-disk file the user never asked to sync.
+ *
+ * The end-of-process ignore filter does NOT cover this: it only consults the .filenignore matcher (and the
+ * dot-file flag), never the nameLength / pathLength / invalidPath / defaultIgnore / duplicate reasons that
+ * `currentLocalTreeIgnored` carries — so a .filenignore-based test would be masked and falsely pass. These
+ * tests therefore drive deltas.process() directly with an injected `currentLocalTreeIgnored` entry whose
+ * path the (empty) ignorer does NOT match, modelling exactly those non-.filenignore reasons.
+ *
+ * This is client-side delta-attribution logic; the backend's only role (a path deleted remotely) is already
+ * covered by the live deletion e2e tests, and the trigger — a base path that became ignored for a
+ * non-.filenignore reason — cannot be forced deterministically against the real backend, so there is no
+ * e2e counterpart (boundary noted in tests/e2e/regressions.e2e.test.ts).
+ */
+const FAKE_TIMERS = ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] as const
+
+async function withWorld(options: CreateWorldOptions, body: (world: World) => Promise<void>): Promise<void> {
+	vi.useFakeTimers({ toFake: [...FAKE_TIMERS] })
+	vi.setSystemTime(BASE_TIME)
+
+	try {
+		const world = await createWorld(options)
+
+		await body(world)
+	} finally {
+		vi.useRealTimers()
+	}
+}
+
+function localFile(path: string, inode: number): LocalItem {
+	return { type: "file", path, inode, size: 100, lastModified: 1_700_000_000_000, creation: 1_690_000_000_000 }
+}
+
+function localDir(path: string, inode: number): LocalItem {
+	return { type: "directory", path, inode, size: 0, lastModified: 1_700_000_000_000, creation: 1_690_000_000_000 }
+}
+
+function remoteFile(path: string, uuid: string, name: string): RemoteItem {
+	return {
+		type: "file",
+		uuid,
+		name,
+		size: 100,
+		mime: "text/plain",
+		lastModified: 1_700_000_000_000,
+		version: 2,
+		chunks: 1,
+		key: `key-${uuid}`,
+		bucket: "bucket",
+		region: "region",
+		path
+	}
+}
+
+function remoteDir(path: string, uuid: string, name: string): RemoteItem {
+	return { type: "directory", uuid, name, size: 0, path }
+}
+
+const ignoredEntry = (path: string): LocalTreeIgnored => ({ localPath: `/local${path}`, relativePath: path, reason: "nameLength" })
+
+// A base where `path` was synced on both sides; the remote copy is now gone. The local copy is present on
+// disk but the caller decides (via currentLocalTree / currentLocalTreeIgnored) whether the scan ignored it.
+function baseWith(path: string, kind: "file" | "dir"): { previousLocalTree: LocalTree; previousRemoteTree: RemoteTree } {
+	const li = kind === "dir" ? localDir(path, 101) : localFile(path, 101)
+	const ri = kind === "dir" ? remoteDir(path, "u-1", path.slice(1)) : remoteFile(path, "u-1", path.slice(1))
+
+	return {
+		previousLocalTree: { tree: { [path]: li }, inodes: { 101: li }, size: 1 },
+		previousRemoteTree: { tree: { [path]: ri }, uuids: { "u-1": ri }, size: 1 }
+	}
+}
+
+const EMPTY_LOCAL: LocalTree = { tree: {}, inodes: {}, size: 0 }
+const EMPTY_REMOTE: RemoteTree = { tree: {}, uuids: {}, size: 0 }
+
+describe("Category ZK — a remote deletion must not wipe a locally-ignored file", () => {
+	it("ZK1: an IGNORED local file whose remote copy was deleted is NOT deleted locally", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const { previousLocalTree, previousRemoteTree } = baseWith("/over-long.txt", "file")
+
+			// Current state: remote deleted it (absent remotely), and the local scan IGNORED it (absent from the
+			// scanned tree, recorded in currentLocalTreeIgnored). The file is still on disk.
+			const { deltas } = await world.sync.deltas.process({
+				currentLocalTree: EMPTY_LOCAL,
+				currentRemoteTree: EMPTY_REMOTE,
+				previousLocalTree,
+				previousRemoteTree,
+				currentLocalTreeErrors: [],
+				currentLocalTreeIgnored: [ignoredEntry("/over-long.txt")]
+			})
+
+			const wipes = deltas.filter(d => d.type === "deleteLocalFile" && d.path === "/over-long.txt")
+
+			expect(wipes, "a remote delete must not propagate onto an ignored local file").toHaveLength(0)
+			// And it must not have been mistaken for a local deletion to push to the cloud either (BUG-006).
+			expect(deltas.filter(d => d.type === "deleteRemoteFile" && d.path === "/over-long.txt")).toHaveLength(0)
+		})
+	})
+
+	it("ZK2: an IGNORED local directory whose remote copy was deleted is NOT deleted locally", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const { previousLocalTree, previousRemoteTree } = baseWith("/over-long-dir", "dir")
+
+			const { deltas } = await world.sync.deltas.process({
+				currentLocalTree: EMPTY_LOCAL,
+				currentRemoteTree: EMPTY_REMOTE,
+				previousLocalTree,
+				previousRemoteTree,
+				currentLocalTreeErrors: [],
+				currentLocalTreeIgnored: [ignoredEntry("/over-long-dir")]
+			})
+
+			expect(deltas.filter(d => d.type === "deleteLocalDirectory" && d.path === "/over-long-dir")).toHaveLength(0)
+		})
+	})
+
+	it("ZK3 (no over-suppression): a NON-ignored local file whose remote copy was deleted IS still deleted locally", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const { previousLocalTree, previousRemoteTree } = baseWith("/normal.txt", "file")
+			const li = localFile("/normal.txt", 101)
+
+			// Same remote deletion, but the local file is present in the scanned tree (not ignored). The normal
+			// remote->local deletion propagation must still happen — the guard must not over-suppress.
+			const { deltas } = await world.sync.deltas.process({
+				currentLocalTree: { tree: { "/normal.txt": li }, inodes: { 101: li }, size: 1 },
+				currentRemoteTree: EMPTY_REMOTE,
+				previousLocalTree,
+				previousRemoteTree,
+				currentLocalTreeErrors: [],
+				currentLocalTreeIgnored: []
+			})
+
+			expect(
+				deltas.filter(d => d.type === "deleteLocalFile" && d.path === "/normal.txt"),
+				"a normal remote deletion must still propagate to the local copy"
+			).toHaveLength(1)
+		})
+	})
+})

package/tests/scenarios/zl-mode-atomicity.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi } from "vitest"
+import { createWorld, BASE_TIME, type CreateWorldOptions, type World } from "../harness/world"
+import { type LocalItem, type LocalTree } from "../../src/lib/filesystems/local"
+import { type RemoteItem, type RemoteTree } from "../../src/lib/filesystems/remote"
+
+/**
+ * Category ZL — one cycle must compute its whole delta set under a SINGLE mode (M6).
+ *
+ * process() is async (it awaits a content hash on the same-size/newer-mtime path) and reads the pair's
+ * mode in ~20 places across its passes. updateMode() mutates sync.mode synchronously from the main thread
+ * at any moment, so a mode switch landing during one of those awaits used to split a single cycle across
+ * two modes — e.g. the local-deletions pass running as twoWay while a later pass runs as cloudToLocal —
+ * producing a self-contradictory delta set (here: a brand-new local file silently dropped instead of
+ * uploaded). The fix snapshots the mode once at entry and reports it back.
+ *
+ * The mode flip is injected through the one awaited dependency inside the passes (createFileHash), which is
+ * exactly the real race window. This is client-side delta logic with no backend role, so there is no e2e
+ * counterpart (boundary noted in tests/e2e/regressions.e2e.test.ts).
+ */
+const FAKE_TIMERS = ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] as const
+
+async function withWorld(options: CreateWorldOptions, body: (world: World) => Promise<void>): Promise<void> {
+	vi.useFakeTimers({ toFake: [...FAKE_TIMERS] })
+	vi.setSystemTime(BASE_TIME)
+
+	try {
+		const world = await createWorld(options)
+
+		await body(world)
+	} finally {
+		vi.useRealTimers()
+	}
+}
+
+function localFile(path: string, inode: number, lastModified = 1_700_000_000_000): LocalItem {
+	return { type: "file", path, inode, size: 100, lastModified, creation: 1_690_000_000_000 }
+}
+
+function remoteFile(path: string, uuid: string, name: string): RemoteItem {
+	return {
+		type: "file",
+		uuid,
+		name,
+		size: 100,
+		mime: "text/plain",
+		lastModified: 1_700_000_000_000,
+		version: 2,
+		chunks: 1,
+		key: `key-${uuid}`,
+		bucket: "bucket",
+		region: "region",
+		path
+	}
+}
+
+const EMPTY_REMOTE: RemoteTree = { tree: {}, uuids: {}, size: 0 }
+
+describe("Category ZL — a mid-cycle mode switch must not split one delta computation", () => {
+	it("ZL1: a mode switch DURING process() does not split the cycle across two modes", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			// "hashme.txt" forces the single awaited content hash inside the delta passes; the stub flips the
+			// pair's mode mid-flight, exactly as a racing updateMode() would. (Its own delta is irrelevant.)
+			const hashSpy = vi.spyOn(world.sync.localFileSystem, "createFileHash").mockImplementation(async () => {
+				world.sync.mode = "cloudToLocal"
+
+				return "cached-hash"
+			})
+
+			world.sync.localFileHashes["/hashme.txt"] = "cached-hash"
+
+			const baseHash = localFile("/hashme.txt", 201, 1_700_000_000_000)
+			const currentHash = localFile("/hashme.txt", 201, 1_700_000_010_000) // same size, newer mtime -> needs the hash
+			const remoteHash = remoteFile("/hashme.txt", "u-h", "hashme.txt")
+			const newLocal = localFile("/localnew.txt", 202)
+
+			const currentLocalTree: LocalTree = {
+				tree: { "/hashme.txt": currentHash, "/localnew.txt": newLocal },
+				inodes: { 201: currentHash, 202: newLocal },
+				size: 2
+			}
+
+			const { deltas, mode } = await world.sync.deltas.process({
+				currentLocalTree,
+				currentRemoteTree: EMPTY_REMOTE, // both remote copies are gone
+				previousLocalTree: { tree: { "/hashme.txt": baseHash }, inodes: { 201: baseHash }, size: 1 },
+				previousRemoteTree: { tree: { "/hashme.txt": remoteHash }, uuids: { "u-h": remoteHash }, size: 1 },
+				currentLocalTreeErrors: [],
+				currentLocalTreeIgnored: []
+			})
+
+			expect(hashSpy, "the scenario must actually reach the awaited hash (the race window)").toHaveBeenCalled()
+
+			// The new local file is attributed by the local-additions pass, which runs AFTER that await. Under the
+			// entry mode (twoWay) it must upload; a live read of the flipped mode (cloudToLocal) would skip the
+			// whole pass and silently drop the file. The single-mode snapshot keeps the cycle on twoWay.
+			expect(
+				deltas.filter(d => d.type === "uploadFile" && d.path === "/localnew.txt"),
+				"a pass after the mid-cycle flip must still use the entry mode"
+			).toHaveLength(1)
+			expect(deltas.filter(d => d.type === "deleteLocalFile" && d.path === "/localnew.txt")).toHaveLength(0)
+			expect(mode, "process() reports the one mode the whole cycle ran under").toBe("twoWay")
+		})
+	})
+})

package/tests/scenarios/zm-scan-concurrency.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
+import { createWorld, BASE_TIME, LOCAL_ROOT } from "../harness/world"
+import { LOCAL_SCAN_CONCURRENCY } from "../../src/lib/filesystems/local"
+
+/**
+ * Category ZM — the local tree scan must bound how many filesystem stat operations it launches at once.
+ *
+ * getDirectoryTree() fans an `lstat` (+ `access`) out over every glob entry. The walk used to map ALL
+ * entries to promises in one go — `entries.map(async …)` eagerly invokes every async body, so a tree
+ * with N entries allocated N pending promises and N in-flight stat results simultaneously. The chunk
+ * size handed to the awaiting helper only batched the AWAIT, never the launch, so peak concurrency (and
+ * peak memory) was unbounded — O(N) on top of the unavoidable result tree, with matching pressure on the
+ * libuv thread pool and open file descriptors. Walking the entries in fixed-size batches caps the
+ * in-flight fan-out at LOCAL_SCAN_CONCURRENCY.
+ *
+ * The peak is measured by wrapping the per-entry `lstat`: the scan routes those through environment.fs,
+ * whereas FastGlob's own traversal uses the separate globFs adapter — so the wrapper observes ONLY the
+ * fan-out. Because each async body runs synchronously up to its first `await`, every body in a batch
+ * increments the in-flight counter before any stat resolves, so the observed peak equals the batch size
+ * deterministically, with no reliance on timing.
+ */
+describe("Category ZM — the local scan bounds concurrent stat operations", () => {
+	beforeEach(() => {
+		// Match the scenario harness: fake only the engine's timers + clock, leaving microtasks/setImmediate
+		// real so FastGlob's async traversal drains while the clock is frozen.
+		vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] })
+		vi.setSystemTime(BASE_TIME)
+	})
+
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	it("ZM1: getDirectoryTree never launches more than LOCAL_SCAN_CONCURRENCY lstat operations at once", async () => {
+		// Comfortably more entries than the bound, and not a round multiple of it, so the buggy unbounded
+		// fan-out (peak = fileCount) is clearly distinguishable from the bounded one (peak = the bound).
+		const fileCount = LOCAL_SCAN_CONCURRENCY * 2 + 137
+		const initialLocal: Record<string, string> = {}
+
+		for (let i = 0; i < fileCount; i++) {
+			initialLocal[`${LOCAL_ROOT}/f${i}.txt`] = "x"
+		}
+
+		const world = await createWorld({ mode: "twoWay", initialLocal })
+
+		// Wrap the per-entry lstat to record peak concurrent in-flight calls. environment.fs IS world.vfs.fs,
+		// and the scan calls it once per entry; FastGlob's walk uses globFs, so this counts only the fan-out.
+		const realLstat = world.vfs.fs.lstat.bind(world.vfs.fs)
+		let inFlight = 0
+		let maxInFlight = 0
+
+		const countingLstat = (async (path: string) => {
+			inFlight++
+			maxInFlight = Math.max(maxInFlight, inFlight)
+
+			try {
+				return await realLstat(path)
+			} finally {
+				inFlight--
+			}
+		}) as typeof world.vfs.fs.lstat
+
+		// SyncFS declares lstat readonly; swap in the counting wrapper through a mutable view (the underlying
+		// memfs object is a plain mutable JS object — the readonly is only a compile-time annotation).
+		;(world.vfs.fs as { lstat: typeof world.vfs.fs.lstat }).lstat = countingLstat
+
+		const tree = await world.sync.localFileSystem.getDirectoryTree()
+
+		// Sanity: the scan visited every file (otherwise a no-op scan would trivially satisfy the bound).
+		expect(tree.result.size).toBe(fileCount)
+		// The fix: peak in-flight stat operations are capped at the bound. The buggy fan-out peaked at
+		// fileCount (every entry launched at once), so it fails this both as "> bound" and "≠ bound".
+		expect(
+			maxInFlight,
+			`scan should cap concurrent lstat fan-out at ${LOCAL_SCAN_CONCURRENCY}, but ${maxInFlight} of ${fileCount} entries were in flight at once`
+		).toBe(LOCAL_SCAN_CONCURRENCY)
+	})
+})

package/tests/scenarios/zn-delta-ordering.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi } from "vitest"
+import { createWorld, BASE_TIME, type CreateWorldOptions, type World } from "../harness/world"
+import { type LocalItem, type LocalTree } from "../../src/lib/filesystems/local"
+import { type RemoteItem, type RemoteTree } from "../../src/lib/filesystems/remote"
+
+/**
+ * Category ZN — deltas.process() must return its deltas ordered shallow-to-deep (ascending path depth) so
+ * the executor always creates/renames/deletes a parent directory before touching its children.
+ *
+ * process() used to sort by depth TWICE: once over the full PRE-collapse set and again over the collapsed
+ * result. collapseDeltas only ever filters (drops subsumed descendants) or rewrites a rename's `from` — it
+ * never reorders and never changes a delta's `path` — and it indexes the renamed/deleted directories up
+ * front, so it is independent of input order. The pre-collapse sort was therefore redundant: a single sort
+ * on the (smaller) collapsed set yields the identical order, with each delta's depth computed once instead
+ * of re-splitting the path on every comparison. This locks the observable contract — the returned deltas
+ * are depth-ascending and child deletes still fold into their ancestor — so the dropped sort cannot
+ * silently regress ordering.
+ *
+ * Behavior-preserving performance change with no backend-observable effect (the executor consumes the same
+ * ordered set); correctness against the live backend is covered by every convergence e2e scenario.
+ */
+const FAKE_TIMERS = ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] as const
+
+async function withWorld(options: CreateWorldOptions, body: (world: World) => Promise<void>): Promise<void> {
+	vi.useFakeTimers({ toFake: [...FAKE_TIMERS] })
+	vi.setSystemTime(BASE_TIME)
+
+	try {
+		const world = await createWorld(options)
+
+		await body(world)
+	} finally {
+		vi.useRealTimers()
+	}
+}
+
+function localFile(path: string, inode: number): LocalItem {
+	return { type: "file", path, inode, size: 100, lastModified: 1_700_000_000_000, creation: 1_690_000_000_000 }
+}
+
+function localDir(path: string, inode: number): LocalItem {
+	return { type: "directory", path, inode, size: 0, lastModified: 1_700_000_000_000, creation: 1_690_000_000_000 }
+}
+
+function remoteFile(path: string, uuid: string): RemoteItem {
+	return {
+		type: "file",
+		uuid,
+		name: path.slice(path.lastIndexOf("/") + 1),
+		size: 100,
+		mime: "text/plain",
+		lastModified: 1_700_000_000_000,
+		version: 2,
+		chunks: 1,
+		key: `key-${uuid}`,
+		bucket: "bucket",
+		region: "region",
+		path
+	}
+}
+
+function remoteDir(path: string, uuid: string): RemoteItem {
+	return { type: "directory", uuid, name: path.slice(path.lastIndexOf("/") + 1), size: 0, path }
+}
+
+describe("Category ZN — process() returns depth-ordered deltas after a single post-collapse sort", () => {
+	it("ZN1: a directory delete that subsumes its child, alongside nested adds, yields depth-ascending output", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			// Base: /gone and /gone/inner.txt were synced on both sides.
+			const goneDir = localDir("/gone", 1)
+			const goneInner = localFile("/gone/inner.txt", 2)
+			const goneDirR = remoteDir("/gone", "u-gone")
+			const goneInnerR = remoteFile("/gone/inner.txt", "u-gone-inner")
+
+			const previousLocalTree: LocalTree = {
+				tree: { "/gone": goneDir, "/gone/inner.txt": goneInner },
+				inodes: { 1: goneDir, 2: goneInner },
+				size: 2
+			}
+			const previousRemoteTree: RemoteTree = {
+				tree: { "/gone": goneDirR, "/gone/inner.txt": goneInnerR },
+				uuids: { "u-gone": goneDirR, "u-gone-inner": goneInnerR },
+				size: 2
+			}
+
+			// Current local: /gone was deleted, and a fresh nested subtree /new/sub/deep.txt was added — so the
+			// raw deltas span depths 2..4 and include a child delete that must fold into its ancestor dir delete.
+			// The subtree is inserted DEEP-FIRST: the add pass emits in tree-iteration order, so the raw (pre-sort)
+			// deltas come out deepest-first — only the final depth sort restores parents-before-children, which is
+			// exactly what this test must catch if it ever regresses.
+			const newDeep = localFile("/new/sub/deep.txt", 12)
+			const newSub = localDir("/new/sub", 11)
+			const newDir = localDir("/new", 10)
+			const currentLocalTree: LocalTree = {
+				tree: { "/new/sub/deep.txt": newDeep, "/new/sub": newSub, "/new": newDir },
+				inodes: { 12: newDeep, 11: newSub, 10: newDir },
+				size: 3
+			}
+
+			// Current remote: unchanged (still holds /gone + child), so the local delete propagates to the remote.
+			const currentRemoteTree: RemoteTree = {
+				tree: { "/gone": goneDirR, "/gone/inner.txt": goneInnerR },
+				uuids: { "u-gone": goneDirR, "u-gone-inner": goneInnerR },
+				size: 2
+			}
+
+			const { deltas } = await world.sync.deltas.process({
+				currentLocalTree,
+				currentRemoteTree,
+				previousLocalTree,
+				previousRemoteTree,
+				currentLocalTreeErrors: [],
+				currentLocalTreeIgnored: []
+			})
+
+			// The child delete folded into the ancestor directory delete (collapse ran).
+			expect(deltas.find(delta => delta.path === "/gone/inner.txt"), "child delete must be subsumed by /gone").toBeUndefined()
+			// The collapsed parent delete and the deepest add are both present, so the set spans depths 2..4.
+			expect(deltas.some(delta => delta.type === "deleteRemoteDirectory" && delta.path === "/gone")).toBe(true)
+			expect(deltas.some(delta => delta.type === "uploadFile" && delta.path === "/new/sub/deep.txt")).toBe(true)
+
+			// The contract P5 must preserve: the returned deltas are ordered ascending by path depth (parents
+			// before children), produced by the single post-collapse sort.
+			const depths = deltas.map(delta => delta.path.split("/").length)
+			expect(depths, `deltas must be depth-ascending, got: ${deltas.map(delta => delta.path).join(", ")}`).toEqual(
+				[...depths].sort((a, b) => a - b)
+			)
+		})
+	})
+})

package/tests/scenarios/zo-download-temp-cleanup.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, control } from "../harness/runner"
+import { LOCAL_ROOT } from "../harness/world"
+import { LOCAL_TRASH_NAME } from "../../src/constants"
+
+/**
+ * Category ZO — a download that fails AFTER staging its file must not orphan the staged temp (L1).
+ *
+ * download() streams the remote file into a uuid-named temp under the local trash dir, then commits it
+ * with a single move into place. The size-mismatch guard already discards the temp before throwing, but
+ * the general catch (a rejected/partial transfer, or a failure during the commit move) re-threw without
+ * removing it — so every failed download leaked a temp file into .filen.trash.local. The periodic trash
+ * sweep only ages them out later, so under a flaky connection these accumulate and waste disk in the
+ * meantime. The fix discards the temp in the catch path too.
+ *
+ * Reproduced deterministically by letting the staging succeed and then failing the commit move (the only
+ * move whose SOURCE is in the trash dir), which lands execution in the catch with a fully-staged temp.
+ *
+ * No e2e counterpart: the leak is a LOCAL artifact and the trigger is a failure of the local commit move,
+ * which the real backend cannot be made to produce on demand (a backend-side download abort takes the
+ * size-mismatch path, which already cleaned up). Boundary noted in tests/e2e/regressions.e2e.test.ts.
+ */
+describe("Category ZO — a failed download does not orphan its staged temp file", () => {
+	it("ZO1: a download that fails while committing its staged file leaves no temp behind", async () => {
+		let moveAttempted = false
+
+		const result = await runScenario({
+			name: "ZO1",
+			mode: "cloudToLocal",
+			initialRemote: { "/file.txt": "hello world contents" },
+			steps: [
+				// Fail the commit move (staging dir -> final path) so the download lands in its catch with a
+				// fully-staged temp. Only the download's commit move has a trash-dir source, so nothing else is hit.
+				control(world => {
+					const realMove = world.vfs.fs.move.bind(world.vfs.fs)
+
+					;(world.vfs.fs as { move: typeof world.vfs.fs.move }).move = (async (
+						src: string,
+						dest: string,
+						opts?: { overwrite?: boolean }
+					) => {
+						if (src.includes(LOCAL_TRASH_NAME)) {
+							moveAttempted = true
+
+							throw new Error("simulated disk error committing the download")
+						}
+
+						return realMove(src, dest, opts)
+					}) as typeof world.vfs.fs.move
+				}),
+				runCycle()
+			]
+		})
+
+		// The failure path was actually exercised: the staged temp's commit move was attempted (a temp existed).
+		expect(moveAttempted, "the download must have staged a temp and attempted to commit it").toBe(true)
+		// The download did not land (its commit failed), so the local file is absent...
+		expect(result.world.vfs.ifs.existsSync(`${LOCAL_ROOT}/file.txt`)).toBe(false)
+		// ...and crucially the staged temp file is NOT orphaned in the local trash directory.
+		const trashDir = `${LOCAL_ROOT}/${LOCAL_TRASH_NAME}`
+		const orphaned = result.world.vfs.ifs.existsSync(trashDir) ? result.world.vfs.ifs.readdirSync(trashDir) : []
+
+		expect(orphaned, "a failed download must not leak its staged temp file").toEqual([])
+	})
+})