@filen/sync 0.2.1 → 0.3.1

package/tests/scenarios/ze-move-into-new-dir.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, localMutate, control } from "../harness/runner"
+import { renameLocal } from "../harness/mutations"
+import { messagesOfType } from "../harness/snapshot"
+import { type SyncMessage } from "../../src/types"
+
+/**
+ * Category ZE — moving an item INTO a newly-created nested directory.
+ *
+ * remote.mkdir() must be able to create a directory whose missing parent is the sync ROOT. The
+ * intermediate-directory loop used to skip any level whose parent was the root (the `if (!parentItem)
+ * continue` fired before the `parentIsBase` branch that supplies remoteParentUUID), so mkdir('/x/y')
+ * threw whenever '/x' did not already exist. A cross-parent rename builds its destination parent inline
+ * (BEFORE the createRemoteDirectory tasks run), so moving a file into a NEW >=2-level folder made the
+ * rename throw; for a TOP-LEVEL source that throw was then swallowed by fileExists() (which returned
+ * false for every top-level file because tree['/'] is never a cache key) -> zero task errors -> a skewed
+ * base was persisted -> the file was silently DUPLICATED (original resurrected + a copy at the new path).
+ */
+
+function taskErrorCount(messages: SyncMessage[]): number {
+	return messagesOfType(messages, "taskErrors").reduce((sum, m) => sum + m.data.errors.length, 0)
+}
+
+describe("Category ZE — move into a newly-created nested directory", () => {
+	it("ZE1: twoWay — move a top-level file into a NEW 2-level dir converges (no duplication)", async () => {
+		const result = await runScenario({
+			name: "ZE1",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "hello", "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "a.txt", "x/y/a.txt")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/a.txt"], "the moved-away original must NOT survive").toBeUndefined()
+		expect(result.finalLocal["/a.txt"]).toBeUndefined()
+		expect(result.finalRemote["/x/y/a.txt"]).toMatchObject({ type: "file", size: "hello".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZE2: twoWay — move a top-level file into a NEW 3-level dir converges", async () => {
+		const result = await runScenario({
+			name: "ZE2",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "deep", "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "a.txt", "p/q/r/a.txt")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/a.txt"]).toBeUndefined()
+		expect(result.finalRemote["/p/q/r/a.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZE3: twoWay — move a top-level DIRECTORY into a NEW 2-level dir converges", async () => {
+		const result = await runScenario({
+			name: "ZE3",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "c", "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "x/y/dir")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir"]).toBeUndefined()
+		expect(result.finalRemote["/x/y/dir/child.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZE4: localToCloud — move a top-level file into a NEW 2-level dir converges", async () => {
+		const result = await runScenario({
+			name: "ZE4",
+			mode: "localToCloud",
+			initialLocal: { "/local/a.txt": "mirror", "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "a.txt", "x/y/a.txt")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/a.txt"]).toBeUndefined()
+		expect(result.finalRemote["/x/y/a.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZE5: a TRANSIENT error on a top-level remote file op SURFACES (not swallowed) and retries to convergence", async () => {
+		const result = await runScenario({
+			name: "ZE5",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "x", "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "a.txt", "b.txt")),
+				control(world => world.cloud.controls.setError("renameFile", new Error("transient rename failure"))),
+				runCycle(),
+				control(world => {
+					world.cloud.controls.clearError("renameFile")
+					world.worker.resetTaskErrors(world.syncPair.uuid)
+					world.triggerWatcher()
+				}),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The failing cycle must REPORT a task error (the top-level rename failure must not be swallowed as
+		// "target vanished" — fileExists has to see the still-present top-level file).
+		expect(taskErrorCount(result.cycles[1]!.messages)).toBeGreaterThan(0)
+		// After recovery: the rename completed, no resurrection of the old name, both sides converge.
+		expect(result.finalRemote["/b.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/a.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/zf-remote-change-unchanged-local.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, remoteMutate, localMutate } from "../harness/runner"
+import { BASE_TIME } from "../harness/world"
+import { transferKinds } from "../harness/snapshot"
+import { readLocal, writeLocalAt } from "../harness/mutations"
+
+/**
+ * Category ZF — a genuine REMOTE content change must be pulled in twoWay even when the remote's mtime is
+ * not strictly newer than the local copy, AS LONG AS the local copy is itself unchanged since the base.
+ *
+ * The download gate's `remoteWins` term only resolved a CONFLICT (newer mtime wins), but it applied the
+ * newer-mtime tiebreak unconditionally — so when only the remote changed (no conflict, local untouched) a
+ * remote edit whose mtime equalled or trailed the local mtime was silently dropped and never re-pulled. The
+ * remote re-upload mints a new uuid, so the change is unambiguously detectable; the tiebreak belongs to the
+ * both-changed case only. The fix makes `remoteWins` also true when the local copy is unchanged vs the base.
+ */
+const SECOND = 1000
+
+describe("Category ZF — remote change vs unchanged local (twoWay, mtime tiebreak)", () => {
+	it("ZF1: a remote edit with an EQUAL mtime is pulled when local is unchanged", async () => {
+		const result = await runScenario({
+			name: "ZF1",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": { content: "v1", mtimeMs: BASE_TIME }, "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				// Remote re-uploads new content (new uuid) but stamps the SAME whole-second mtime as local.
+				remoteMutate(world => world.cloud.controls.updateFile("/a.txt", "v2-remote-edit", { mtimeMs: BASE_TIME })),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The change must actually be downloaded (not just "eventually equal" by some other path).
+		expect(transferKinds(result.cycles[1]!.messages)).toContain("download")
+		expect(readLocal(result.world, "a.txt")).toBe("v2-remote-edit")
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZF2: a remote edit with an OLDER mtime is pulled when local is unchanged", async () => {
+		const result = await runScenario({
+			name: "ZF2",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": { content: "v1", mtimeMs: BASE_TIME + 10 * SECOND }, "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				// Remote edit lands with an mtime BEHIND the local copy (e.g. an out-of-sync clock on the
+				// editing device). It still changed (new uuid) and local is untouched, so it must win.
+				remoteMutate(world => world.cloud.controls.updateFile("/a.txt", "older-but-real", { mtimeMs: BASE_TIME })),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(readLocal(result.world, "a.txt")).toBe("older-but-real")
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZF3: a real CONFLICT (both edited) still resolves by newer mtime — local newer wins, not the older remote", async () => {
+		const result = await runScenario({
+			name: "ZF3",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": { content: "v1", mtimeMs: BASE_TIME }, "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				// BOTH sides edit: local becomes strictly newer than the remote edit → local must win the
+				// conflict (the fix must NOT turn every remote change into an unconditional pull).
+				remoteMutate(world => world.cloud.controls.updateFile("/a.txt", "remote-older", { mtimeMs: BASE_TIME + 1 * SECOND })),
+				localMutate(world => writeLocalAt(world, "a.txt", "local-newer", BASE_TIME + 5 * SECOND)),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(readLocal(result.world, "a.txt")).toBe("local-newer")
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/zg-edit-during-scan.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi } from "vitest"
+import { runScenario, runCycle, control } from "../harness/runner"
+import { BASE_TIME } from "../harness/world"
+import { writeLocalAt, readLocal } from "../harness/mutations"
+
+/**
+ * Category ZG — a file edited WHILE the local scan is running must not be lost.
+ *
+ * getDirectoryTree() skips a rescan while `lastDirectoryChangeTimestamp < cache.timestamp`. The cache used
+ * to be stamped when the walk ENDED, so a file changed after the engine lstat'd it (but before the walk
+ * returned) recorded a change time EARLIER than the stamp — the next cycle then judged the cache fresh and
+ * never re-read the edit. Stamping at the walk's START closes that window: the change time is >= the stamp,
+ * the strict `<` fails, and the next cycle rescans. This reproduces the race deterministically by editing
+ * the file from inside the lstat hook (after the engine read it) and advancing the fake clock so that an
+ * end-of-walk stamp WOULD have beaten the edit.
+ */
+const SECOND = 1000
+
+describe("Category ZG — an edit during the local scan is not lost", () => {
+	it("ZG1: a file edited mid-scan is re-detected and uploaded on the next cycle (twoWay)", async () => {
+		let fired = false
+
+		const result = await runScenario({
+			name: "ZG1",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": { content: "v1", mtimeMs: BASE_TIME }, "/local/keep.txt": "k" },
+			steps: [
+				// Cycle 0: settle the initial state — a.txt="v1" is uploaded and becomes the base.
+				runCycle(),
+				// Force the next cycle to actually scan (bump the change clock) and arm a one-shot hook that,
+				// the moment the engine lstats a.txt, simulates the user overwriting it AFTER it was read, then
+				// advances the clock so an end-of-walk stamp would land after the edit's change time.
+				control(world => {
+					world.triggerWatcher()
+
+					world.vfs.controls.onStat(posixPath => {
+						if (fired || !posixPath.endsWith("/a.txt")) {
+							return
+						}
+
+						fired = true
+
+						const editAt = Date.now()
+
+						writeLocalAt(world, "a.txt", "v2-edited-mid-scan", editAt)
+						world.triggerWatcher()
+						vi.setSystemTime(editAt + 30 * SECOND)
+						world.vfs.controls.clearStatHook()
+					})
+				}),
+				// Cycle 1: the racy scan reads "v1"; the hook overwrites to v2, bumps the change clock, and
+				// jumps the clock forward. With the bug the cache is stamped AFTER the edit's change time.
+				runCycle(),
+				// Cycle 2: must rescan (change time >= scan-start stamp) and upload v2. The bug skips it as a
+				// "fresh" cache, so the edit never reaches the remote.
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The hook edited the local file in BOTH the fixed and buggy worlds, so the discriminating signal is
+		// whether the edit reached the REMOTE: convergence holds only if the mid-scan edit was re-detected.
+		expect(fired, "the mid-scan lstat hook must have fired").toBe(true)
+		expect(readLocal(result.world, "a.txt")).toBe("v2-edited-mid-scan")
+		expect(result.finalRemote["/a.txt"]).toMatchObject({ type: "file", size: "v2-edited-mid-scan".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/zh-dir-delete-vs-child.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, localMutate, remoteMutate } from "../harness/runner"
+import { writeLocal, rmLocal } from "../harness/mutations"
+
+/**
+ * Category ZH — a directory deletion must not cascade over live content the OTHER side did not delete.
+ *
+ * When one side removes a directory while the other adds (or keeps a modified) child inside it in the same
+ * cycle, the raw delta set holds both `deleteXDirectory <dir>` and the child's own add. The dir-delete used
+ * to win — collapse subsumed the child's sibling deletes under it and the dir-delete then wiped the
+ * brand-new file at execution time, before it was ever propagated (silent data loss). Newer content beats a
+ * delete (the same rule the per-file passes apply), so the directory survives: its delete is dropped and
+ * the surviving child's own add re-creates it. A child that is merely RENAMED out of the directory does NOT
+ * keep it alive (that is a normal dir rename, which deletes the now-empty old directory).
+ */
+describe("Category ZH — directory delete vs a live child", () => {
+	it("ZH1: remote deletes a dir while local adds a new child — the child survives, the dir is kept (twoWay)", async () => {
+		const result = await runScenario({
+			name: "ZH1",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/keep.txt": "keep", "/local/other.txt": "o" },
+			steps: [
+				runCycle(),
+				remoteMutate(world => world.cloud.controls.trashPath("/dir")),
+				localMutate(world => writeLocal(world, "dir/new.txt", "new-child")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The new child survives and is uploaded; the dir is re-asserted; the unmodified base child the
+		// remote deleted is gone; both sides converge.
+		expect(result.finalLocal["/dir/new.txt"]).toMatchObject({ type: "file", size: "new-child".length })
+		expect(result.finalRemote["/dir/new.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/dir/keep.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZH2: local deletes a dir while remote adds a new child — the child survives (symmetric)", async () => {
+		const result = await runScenario({
+			name: "ZH2",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/keep.txt": "keep", "/local/other.txt": "o" },
+			steps: [
+				runCycle(),
+				localMutate(world => rmLocal(world, "dir")),
+				remoteMutate(world => world.cloud.controls.addFile("/dir/new.txt", "remote-new")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir/new.txt"]).toMatchObject({ type: "file", size: "remote-new".length })
+		expect(result.finalLocal["/dir/new.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/dir/keep.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZH3: remote deletes a dir while local MODIFIES a base child — the modified child wins, dir kept", async () => {
+		const result = await runScenario({
+			name: "ZH3",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/keep.txt": "v1", "/local/other.txt": "o" },
+			steps: [
+				runCycle(),
+				remoteMutate(world => world.cloud.controls.trashPath("/dir")),
+				localMutate(world => writeLocal(world, "dir/keep.txt", "v2-modified-bigger")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Newer-modify-wins: the locally-modified child is resurrected (re-uploaded), keeping its directory.
+		expect(result.finalRemote["/dir/keep.txt"]).toMatchObject({ type: "file", size: "v2-modified-bigger".length })
+		expect(result.finalLocal["/dir/keep.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZH4: deleting a dir whose ONLY child is moved out still deletes the dir (no false-keep on rename)", async () => {
+		const result = await runScenario({
+			name: "ZH4",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/only.txt": "x", "/local/other.txt": "o" },
+			steps: [
+				runCycle(),
+				localMutate(world => {
+					// Move the only child OUT to the root, then remove the now-empty directory.
+					writeLocal(world, "moved.txt", "x")
+					rmLocal(world, "dir")
+				}),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir"]).toBeUndefined()
+		expect(result.finalRemote["/moved.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/zi-smoke-test-outage.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi } from "vitest"
+import { SYNC_INTERVAL } from "../../src/constants"
+import { createWorld, BASE_TIME, type CreateWorldOptions, type World } from "../harness/world"
+import { messagesOfType } from "../harness/snapshot"
+import { makeErrnoError } from "../fakes/virtual-fs"
+
+/**
+ * Category ZI — the local smoke test must not hold the account lock during a local outage (H7).
+ *
+ * The smoke test retries every SYNC_INTERVAL for as long as the local sync root is unavailable (an
+ * unmounted drive, a disconnected network filesystem). It used to run AFTER the lock was acquired, so the
+ * whole outage held the account lock and starved every other device. Running it BEFORE the lock means an
+ * outage stalls only this pair's cycle. (The retry loop was also de-recursed so a long outage no longer
+ * grows the stack by one suspended frame per retry.)
+ */
+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()
+	}
+}
+
+const countOf = (world: World, type: Parameters<typeof messagesOfType>[1]): number => messagesOfType(world.messages, type).length
+
+describe("Category ZI — smoke test does not hold the lock during a local outage", () => {
+	it("ZI1: a local outage retries the smoke test WITHOUT acquiring the lock, then proceeds on recovery", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "a" } }, async world => {
+			// Settle once for a clean base.
+			await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+			await world.sync.runCycle()
+
+			const lockDoneBaseline = countOf(world, "cycleAcquiringLockDone")
+
+			// Simulate a local outage: the sync root is no longer accessible.
+			world.vfs.controls.setError("/local", makeErrnoError("EACCES", "local sync root unavailable"))
+
+			await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+			let settled = false
+			const cyclePromise = world.sync.runCycle().finally(() => {
+				settled = true
+			})
+
+			// Pump several retry intervals while the outage persists.
+			for (let i = 0; i < 3 && !settled; i++) {
+				await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+			}
+
+			// The smoke test failed and kept failing — but the lock was NEVER acquired (before the fix it
+			// would have been, because the smoke test ran under the lock), and the cycle has not settled.
+			expect(countOf(world, "cycleLocalSmokeTestFailed")).toBeGreaterThan(0)
+			expect(countOf(world, "cycleAcquiringLockDone"), "the lock must not be acquired during the outage").toBe(lockDoneBaseline)
+			expect(settled).toBe(false)
+
+			// Recover: the path is accessible again. The next retry succeeds and the cycle runs to completion.
+			world.vfs.controls.clearError("/local")
+
+			for (let i = 0; i < 10 && !settled; i++) {
+				await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+			}
+
+			await cyclePromise
+
+			expect(settled).toBe(true)
+			expect(countOf(world, "cycleAcquiringLockDone"), "after recovery the lock is acquired and the cycle proceeds").toBeGreaterThan(
+				lockDoneBaseline
+			)
+		})
+	})
+})

package/tests/scenarios/zj-trash-cleanup.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi } from "vitest"
+import pathModule from "path"
+import { createWorld, BASE_TIME, LOCAL_ROOT, type CreateWorldOptions, type World } from "../harness/world"
+import { toPosixPath } from "../fakes/virtual-fs"
+import { LOCAL_TRASH_NAME } from "../../src/constants"
+
+/**
+ * Category ZJ — the local-trash eviction sweep must age out trashed DIRECTORIES, and the sweep's timer
+ * must be torn down with the pair (M2 + M3).
+ *
+ * The local trash holds whatever a delete moved aside — and a deleted directory is moved in wholesale by
+ * its basename, so it lands as a top-level DIRECTORY inside the trash. The 30-day eviction sweep globbed
+ * with `onlyFiles:true`, which skipped every trashed directory (and, with `deep:0`, their contents too),
+ * so trashed directories accumulated on disk forever (M2). Separately, the sweep's `setInterval` handle
+ * was discarded, so a removed pair's timer kept firing every 5 minutes forever, pinning the whole Sync
+ * (and its in-memory trees) and burning a periodic glob on a dead pair (M3).
+ *
+ * These are LOCAL-only concerns (a folder on the local disk + a client-side timer); the backend plays no
+ * part, so there is no e2e counterpart — see the boundary note in tests/e2e/regressions.e2e.test.ts.
+ */
+const FAKE_TIMERS = ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] as const
+const CLEANUP_INTERVAL_MS = 300000
+const DAY_MS = 86400000
+const TRASH_ROOT = pathModule.posix.join(LOCAL_ROOT, LOCAL_TRASH_NAME)
+
+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()
+	}
+}
+
+// Drop a file or a directory (with one child) straight into the on-disk trash via memfs, then backdate its
+// access time so the eviction gate (`atime + 30d < now`) decides it on the next sweep.
+function seedTrashEntry(world: World, name: string, kind: "file" | "dir", ageDays: number): string {
+	const ifs = world.vfs.ifs
+	const entryPath = pathModule.posix.join(TRASH_ROOT, name)
+
+	if (kind === "dir") {
+		ifs.mkdirSync(toPosixPath(entryPath), { recursive: true })
+		ifs.writeFileSync(toPosixPath(pathModule.posix.join(entryPath, "inner.txt")), "inner")
+	} else {
+		ifs.mkdirSync(toPosixPath(TRASH_ROOT), { recursive: true })
+		ifs.writeFileSync(toPosixPath(entryPath), "leaf")
+	}
+
+	// utimesSync takes seconds; set atime to `ageDays` before the (fake) current time.
+	const atimeSeconds = (Date.now() - ageDays * DAY_MS) / 1000
+
+	ifs.utimesSync(toPosixPath(entryPath), atimeSeconds, atimeSeconds)
+
+	return entryPath
+}
+
+const existsInTrash = (world: World, name: string): boolean => world.vfs.ifs.existsSync(toPosixPath(pathModule.posix.join(TRASH_ROOT, name)))
+
+describe("Category ZJ — local trash cleanup evicts directories and tears down its timer", () => {
+	it("ZJ1: an old trashed DIRECTORY is evicted by the sweep (not just old files)", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "a" } }, async world => {
+			const oldDir = seedTrashEntry(world, "old-dir", "dir", 40)
+			const oldFile = seedTrashEntry(world, "old-file.txt", "file", 40)
+
+			expect(existsInTrash(world, "old-dir")).toBe(true)
+			expect(existsInTrash(world, "old-file.txt")).toBe(true)
+
+			await world.sync.cleanupLocalTrashOnce()
+
+			// Both the aged directory (with onlyFiles:true it was skipped and leaked forever) and the aged file
+			// are gone.
+			expect(world.vfs.ifs.existsSync(toPosixPath(oldDir)), "an aged trashed directory must be removed").toBe(false)
+			expect(world.vfs.ifs.existsSync(toPosixPath(oldFile))).toBe(false)
+		})
+	})
+
+	it("ZJ2: a RECENT trashed directory is kept — the 30-day gate still applies to directories", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "a" } }, async world => {
+			seedTrashEntry(world, "recent-dir", "dir", 5)
+			seedTrashEntry(world, "old-dir", "dir", 40)
+
+			await world.sync.cleanupLocalTrashOnce()
+
+			expect(existsInTrash(world, "recent-dir"), "a directory trashed 5 days ago is still within the retention window").toBe(true)
+			expect(existsInTrash(world, "old-dir")).toBe(false)
+		})
+	})
+
+	it("ZJ3: cleanup() tears down the sweep timer so a removed pair stops sweeping", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "a" } }, async world => {
+			// The constructor armed the periodic sweep and kept its handle.
+			expect(world.sync.cleanupLocalTrashInterval, "the sweep timer must be retained so it can be cleared").toBeDefined()
+
+			await world.sync.cleanup({})
+
+			expect(world.sync.cleanupLocalTrashInterval, "cleanup() must clear the sweep timer handle").toBeUndefined()
+
+			// An aged directory appears in the trash AFTER the pair was removed. If the timer were still alive
+			// it would fire within one interval and delete it; because it was cleared, the entry survives.
+			seedTrashEntry(world, "post-removal-old-dir", "dir", 40)
+
+			await vi.advanceTimersByTimeAsync(CLEANUP_INTERVAL_MS * 3 + 1)
+
+			expect(existsInTrash(world, "post-removal-old-dir"), "a removed pair must not keep sweeping the trash").toBe(true)
+		})
+	})
+
+	it("ZJ4: while the pair is live the timer invokes the sweep once per period", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "a" } }, async world => {
+			// Assert the timer WIRING (it calls the sweep on schedule) rather than the sweep's async filesystem
+			// effect — FastGlob's stream completion leans on the real event loop, which a floating timer
+			// callback can't deterministically drain under fake timers (ZJ1/ZJ2 cover the eviction effect when
+			// the sweep is awaited directly).
+			const sweep = vi.spyOn(world.sync, "cleanupLocalTrashOnce").mockResolvedValue()
+
+			expect(sweep).not.toHaveBeenCalled()
+
+			await vi.advanceTimersByTimeAsync(CLEANUP_INTERVAL_MS + 1)
+
+			expect(sweep, "the armed interval must invoke the sweep once per period").toHaveBeenCalledTimes(1)
+
+			await vi.advanceTimersByTimeAsync(CLEANUP_INTERVAL_MS)
+
+			expect(sweep, "and again on the next period").toHaveBeenCalledTimes(2)
+
+			sweep.mockRestore()
+		})
+	})
+})