@filen/sync 0.2.1 → 0.3.2

package/tests/scenarios/zb-dir-rename-cross.test.ts

@@ -0,0 +1,296 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, localMutate, remoteMutate } from "../harness/runner"
+import { BASE_TIME } from "../harness/world"
+import { transferKinds } from "../harness/snapshot"
+import { renameLocal, writeLocalAt, rmLocal } from "../harness/mutations"
+
+/**
+ * Cross-side directory rename + concurrent child change (BUG-A / BUG-B). A directory renamed on ONE side
+ * while a descendant is changed on the OTHER side is the hardest reconciliation case: the rename relocates
+ * the whole subtree, but the per-descendant passes compare current-vs-base by PATH, so a child still sitting
+ * at the pre-rename path on the other side is mis-attributed. Before the rename-aware rebase, this silently
+ * destroyed the other-side modification (BUG-A) or resurrected an other-side deletion (BUG-B). Every case
+ * must converge (finalLocal === finalRemote) with the NEWER change winning and no data loss.
+ *
+ * Category E covers same-side rename mechanics; Z covers same-side multi-op; Y covers same-path conflicts.
+ * This file is specifically the cross-side directory-subtree race.
+ */
+const SECOND = 1000
+
+describe("Cross-side directory rename + concurrent child change (BUG-A / BUG-B)", () => {
+	it("ZB1: local dir rename + remote child MODIFY → the remote edit survives (BUG-A)", async () => {
+		const result = await runScenario({
+			name: "ZB1",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old", "/local/dir/sibling.txt": "sib" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				remoteMutate(world =>
+					world.cloud.controls.updateFile("/dir/child.txt", "REMOTE-EDITED-NEW-CONTENT", { mtimeMs: BASE_TIME + 10 * SECOND })
+				),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir2/child.txt"]).toMatchObject({ size: "REMOTE-EDITED-NEW-CONTENT".length })
+		expect(result.finalRemote["/dir2/sibling.txt"]).toMatchObject({ size: "sib".length })
+		expect(result.finalRemote["/dir/child.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB2: remote dir rename + local child MODIFY → the local edit survives (BUG-A symmetric)", async () => {
+		const result = await runScenario({
+			name: "ZB2",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old", "/local/dir/sibling.txt": "sib" },
+			steps: [
+				runCycle(),
+				remoteMutate(world => world.cloud.controls.movePath("/dir", "/dir2")),
+				localMutate(world => writeLocalAt(world, "dir/child.txt", "LOCAL-EDITED-NEW-CONTENT", BASE_TIME + 10 * SECOND)),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir2/child.txt"]).toMatchObject({ size: "LOCAL-EDITED-NEW-CONTENT".length })
+		expect(result.finalRemote["/dir2/sibling.txt"]).toMatchObject({ size: "sib".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB3: local dir rename + remote child DELETE → the child is deleted, not resurrected (BUG-B)", async () => {
+		const result = await runScenario({
+			name: "ZB3",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old", "/local/dir/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				remoteMutate(world => world.cloud.controls.trashPath("/dir/child.txt")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The renamed directory survives with its un-touched child; the remotely-deleted child stays deleted.
+		expect(result.finalRemote["/dir2/keep.txt"]).toMatchObject({ size: "k".length })
+		expect(result.finalRemote["/dir2/child.txt"]).toBeUndefined()
+		expect(result.finalLocal["/dir2/child.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB4: remote dir rename + local child DELETE → the child is deleted, not resurrected (BUG-B symmetric)", async () => {
+		const result = await runScenario({
+			name: "ZB4",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old", "/local/dir/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				remoteMutate(world => world.cloud.controls.movePath("/dir", "/dir2")),
+				// The user deletes a file inside a folder another device just renamed. Without the rebase the
+				// remote copy (now at /dir2/child.txt) would be resurrected back down instead of deleted.
+				localMutate(world => rmLocal(world, "dir/child.txt")),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir2/keep.txt"]).toMatchObject({ size: "k".length })
+		expect(result.finalRemote["/dir2/child.txt"]).toBeUndefined()
+		expect(result.finalLocal["/dir2/child.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB5: NESTED — rename a top dir + remote modify of a DEEPLY nested child → edit survives at the new path", async () => {
+		const result = await runScenario({
+			name: "ZB5",
+			mode: "twoWay",
+			initialLocal: { "/local/top/mid/deep/child.txt": "old", "/local/top/other.txt": "o" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "top", "top2")),
+				remoteMutate(world =>
+					world.cloud.controls.updateFile("/top/mid/deep/child.txt", "DEEPLY-NESTED-NEW-CONTENT", {
+						mtimeMs: BASE_TIME + 10 * SECOND
+					})
+				),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/top2/mid/deep/child.txt"]).toMatchObject({ size: "DEEPLY-NESTED-NEW-CONTENT".length })
+		expect(result.finalRemote["/top2/other.txt"]).toMatchObject({ size: "o".length })
+		expect(result.finalRemote["/top/mid/deep/child.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB6: MULTIPLE children — rename dir; remote modifies one, deletes one, leaves one", async () => {
+		const result = await runScenario({
+			name: "ZB6",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/a.txt": "a-old", "/local/dir/b.txt": "b-old", "/local/dir/c.txt": "c-old" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				remoteMutate(world => {
+					world.cloud.controls.updateFile("/dir/a.txt", "A-REMOTE-EDITED-NEW", { mtimeMs: BASE_TIME + 10 * SECOND })
+					world.cloud.controls.trashPath("/dir/b.txt")
+				}),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir2/a.txt"]).toMatchObject({ size: "A-REMOTE-EDITED-NEW".length })
+		expect(result.finalRemote["/dir2/b.txt"]).toBeUndefined()
+		expect(result.finalRemote["/dir2/c.txt"]).toMatchObject({ size: "c-old".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB7: MOVE a dir into another dir + remote child modify → edit survives at the moved-into path", async () => {
+		const result = await runScenario({
+			name: "ZB7",
+			mode: "twoWay",
+			initialLocal: { "/local/src/data.txt": "old", "/local/dest/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "src", "dest/src")),
+				remoteMutate(world =>
+					world.cloud.controls.updateFile("/src/data.txt", "MOVED-DIR-CHILD-NEW-CONTENT", { mtimeMs: BASE_TIME + 10 * SECOND })
+				),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dest/src/data.txt"]).toMatchObject({ size: "MOVED-DIR-CHILD-NEW-CONTENT".length })
+		expect(result.finalRemote["/dest/keep.txt"]).toMatchObject({ size: "k".length })
+		expect(result.finalRemote["/src/data.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB8: local dir rename + remote ADDS a new child under the old path → the new child lands in the renamed dir", async () => {
+		const result = await runScenario({
+			name: "ZB8",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				remoteMutate(world => world.cloud.controls.addFile("/dir/new.txt", "REMOTE-ADDED-CHILD", { mtimeMs: BASE_TIME + 10 * SECOND })),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(result.finalRemote["/dir2/child.txt"]).toMatchObject({ size: "old".length })
+		expect(result.finalRemote["/dir2/new.txt"]).toMatchObject({ size: "REMOTE-ADDED-CHILD".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB9: a SIMPLE dir rename (no child change) converges with NO file transfer (regression guard)", async () => {
+		const result = await runScenario({
+			name: "ZB9",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old", "/local/dir/sibling.txt": "sib" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The rename must NOT degrade into a re-upload/re-download of the unchanged children.
+		const renameCycleKinds = transferKinds(result.cycles[1]!.messages)
+		expect(renameCycleKinds).not.toContain("upload")
+		expect(renameCycleKinds).not.toContain("download")
+		expect(result.finalRemote["/dir2/child.txt"]).toMatchObject({ size: "old".length })
+		expect(result.finalRemote["/dir2/sibling.txt"]).toMatchObject({ size: "sib".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB10: after a cross-side rename+modify converges, an extra cycle is a no-op (multi-cycle stability)", async () => {
+		const result = await runScenario({
+			name: "ZB10",
+			mode: "twoWay",
+			initialLocal: { "/local/dir/child.txt": "old" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				remoteMutate(world =>
+					world.cloud.controls.updateFile("/dir/child.txt", "REMOTE-EDITED-NEW-CONTENT", { mtimeMs: BASE_TIME + 10 * SECOND })
+				),
+				runCycle(),
+				runCycle(),
+				runCycle(),
+				// A final settled cycle must produce no transfers.
+				runCycle()
+			]
+		})
+
+		const lastCycleKinds = transferKinds(result.cycles[result.cycles.length - 1]!.messages)
+		expect(lastCycleKinds).not.toContain("upload")
+		expect(lastCycleKinds).not.toContain("download")
+		expect(result.finalRemote["/dir2/child.txt"]).toMatchObject({ size: "REMOTE-EDITED-NEW-CONTENT".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	// Mirror-mode coverage: BUG-A's DATA LOSS is twoWay-specific (a mirror's authoritative side always wins
+	// correctly), but the rename-aware rebase must still keep mirror modes CONVERGENT and the authoritative
+	// side's content winning at the renamed path.
+
+	it("ZB11: localToCloud — local dir rename + a foreign remote child edit → local content wins, converges", async () => {
+		const result = await runScenario({
+			name: "ZB11",
+			mode: "localToCloud",
+			initialLocal: { "/local/dir/child.txt": "old", "/local/dir/sibling.txt": "sib" },
+			steps: [
+				runCycle(),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				remoteMutate(world =>
+					world.cloud.controls.updateFile("/dir/child.txt", "FOREIGN-REMOTE-EDIT", { mtimeMs: BASE_TIME + 10 * SECOND })
+				),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Local authoritative: the foreign remote edit is reverted to the local content at the renamed path.
+		expect(result.finalRemote["/dir2/child.txt"]).toMatchObject({ size: "old".length })
+		expect(result.finalRemote["/dir/child.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZB12: cloudToLocal — remote dir rename + a foreign local child edit → remote content wins, converges", async () => {
+		const result = await runScenario({
+			name: "ZB12",
+			mode: "cloudToLocal",
+			initialRemote: { "/dir/child.txt": "old", "/dir/sibling.txt": "sib" },
+			steps: [
+				runCycle(),
+				remoteMutate(world => world.cloud.controls.movePath("/dir", "/dir2")),
+				localMutate(world => writeLocalAt(world, "dir/child.txt", "FOREIGN-LOCAL-EDIT", BASE_TIME + 10 * SECOND)),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Remote authoritative: the foreign local edit is reverted to the remote content at the renamed path.
+		expect(result.finalLocal["/dir2/child.txt"]).toMatchObject({ size: "old".length })
+		expect(result.finalLocal["/dir/child.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/zc-crash-recovery.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, restart, localMutate, remoteMutate, control, type Step } from "../harness/runner"
+import { writeLocalAt, renameLocal, rmLocal } from "../harness/mutations"
+import { BASE_TIME } from "../harness/world"
+
+const SECOND = 1000
+
+/**
+ * Category ZC — crash / stop mid-run recovery.
+ *
+ * The engine has no write-ahead log; instead it relies on a single invariant: the persisted base
+ * (`previousLocalTree`/`previousRemoteTree`) is advanced ONLY at the end of a cycle that had ZERO task
+ * errors (`sync.ts` — `if (this.taskErrors.length === 0) { ... state.save() }`). So if the process is
+ * killed — or the user stops the sync — mid-cycle, the on-disk base stays at the LAST CLEAN cycle while
+ * the real filesystem / remote may already be partially advanced. On the next boot a fresh engine loads
+ * that stale base, re-scans both sides, and re-derives whatever work is still outstanding. The recovery
+ * is "at-least-once": an already-applied transfer may be re-derived, but it converges with no data loss
+ * and no duplication.
+ *
+ * A crash is modelled faithfully by (1) running a cycle in which one task fails — which gates the cycle
+ * and SKIPS the state save while OTHER tasks in the same cycle have already hit the fake cloud — then
+ * (2) `restart()`, which rebuilds the engine over the SAME virtual fs + cloud and reloads the (stale)
+ * persisted base, discarding all in-memory cycle progress. That on-disk outcome (base behind reality,
+ * in-memory state gone) is identical to a hard `kill -9` between task application and the state save.
+ *
+ * Distinct from Category S (restart between SETTLED cycles, where base == reality and the first cycle is
+ * a trivial no-op): here the base is deliberately BEHIND reality, exercising the self-heal path.
+ */
+
+function settle(): Step[] {
+	return [runCycle(), runCycle()]
+}
+
+describe("Category ZC — crash / stop mid-run recovery", () => {
+	it("ZC1: a crash after a partially-applied cycle (upload landed, rename did not, state NOT saved) heals on restart", async () => {
+		const result = await runScenario({
+			name: "ZC1",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "a", "/local/dir/c.txt": "c" },
+			steps: [
+				...settle(),
+				// Two INDEPENDENT local changes in one cycle: add new.txt (its upload lands on the fake
+				// remote) and rename dir -> dir2 (the remote rename is forced to fail = the "crash" point).
+				localMutate(world => writeLocalAt(world, "new.txt", "fresh", BASE_TIME + 10 * SECOND)),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				control(world => world.cloud.controls.setError("renameDirectory", new Error("crash: rename never reached the server"))),
+				// new.txt uploads; the dir rename throws -> taskErrors > 0 -> state.save() is SKIPPED.
+				runCycle(),
+				// Process dies here: in-memory progress is discarded and the on-disk base is still PRE-cycle.
+				restart(),
+				control(world => {
+					world.cloud.controls.clearError("renameDirectory")
+					world.triggerWatcher()
+				}),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Guard the premise: the crash cycle (index 2, after the two settle cycles) genuinely left PARTIAL
+		// state — new.txt's upload reached the remote, but the rename did not. Without this the test could
+		// silently degrade into "everything just syncs after a restart".
+		const crashCycle = result.cycles[2]!
+
+		expect(crashCycle.remote["/new.txt"]).toMatchObject({ type: "file" })
+		expect(crashCycle.remote["/dir/c.txt"]).toMatchObject({ type: "file" })
+		expect(crashCycle.remote["/dir2"]).toBeUndefined()
+
+		// No loss, no duplication: the already-uploaded file survives exactly once, the lost rename
+		// completes, and the stale base is fully reconciled.
+		expect(result.finalRemote["/new.txt"]).toMatchObject({ type: "file", size: "fresh".length })
+		expect(result.finalRemote["/dir2/c.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/dir/c.txt"]).toBeUndefined()
+		expect(result.finalRemote["/dir"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZC2: a crash with un-synced changes on BOTH sides (base behind reality both ways) converges on restart", async () => {
+		const result = await runScenario({
+			name: "ZC2",
+			mode: "twoWay",
+			initialLocal: { "/local/base.txt": "base" },
+			steps: [
+				...settle(),
+				// Both sides change, but the engine dies before ANY cycle syncs them: the on-disk base only
+				// knows base.txt, yet local has local-only.txt and the remote has remote-only.txt.
+				localMutate(world => writeLocalAt(world, "local-only.txt", "L", BASE_TIME + 10 * SECOND)),
+				remoteMutate(world => world.cloud.controls.addFile("/remote-only.txt", "R", { mtimeMs: BASE_TIME + 10 * SECOND })),
+				restart(),
+				control(world => world.triggerWatcher()),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Both un-synced additions are picked up from the real fs/remote despite the stale base — neither
+		// is lost, and the deleted-detection gate does NOT mistake "present but not in base" for a deletion.
+		expect(result.finalLocal["/local-only.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/remote-only.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/base.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/local-only.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/remote-only.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZC3: a crash mid-deletion (one delete applied, one failed, state NOT saved) does NOT resurrect on restart", async () => {
+		const result = await runScenario({
+			name: "ZC3",
+			mode: "twoWay",
+			initialLocal: {
+				"/local/gone.txt": "g",
+				"/local/keepdir/k.txt": "k",
+				"/local/deldir/d.txt": "d"
+			},
+			steps: [
+				...settle(),
+				// Delete a file AND a directory locally in one cycle; the remote DIR-trash fails (crash),
+				// but the remote FILE-trash lands — so gone.txt is already removed remotely when we die.
+				localMutate(world => rmLocal(world, "gone.txt")),
+				localMutate(world => rmLocal(world, "deldir")),
+				control(world => world.cloud.controls.setError("trashDirectory", new Error("crash: dir delete never reached the server"))),
+				runCycle(),
+				// Reload the stale base: it still lists gone.txt AND deldir as present on BOTH sides.
+				restart(),
+				control(world => {
+					world.cloud.controls.clearError("trashDirectory")
+					world.triggerWatcher()
+				}),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Guard the premise: the crash cycle genuinely left a HALF-APPLIED deletion — gone.txt was already
+		// trashed remotely, but deldir was not.
+		const crashCycle = result.cycles[2]!
+
+		expect(crashCycle.remote["/gone.txt"]).toBeUndefined()
+		expect(crashCycle.remote["/deldir/d.txt"]).toMatchObject({ type: "file" })
+
+		// The already-applied file deletion must NOT be resurrected from the stale base (both sides
+		// genuinely removed it); the pending dir deletion completes; untouched data is preserved.
+		expect(result.finalRemote["/gone.txt"]).toBeUndefined()
+		expect(result.finalLocal["/gone.txt"]).toBeUndefined()
+		expect(result.finalRemote["/deldir"]).toBeUndefined()
+		expect(result.finalRemote["/deldir/d.txt"]).toBeUndefined()
+		expect(result.finalRemote["/keepdir/k.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZC4: localToCloud — a crash after a partially-applied cycle heals on restart (mirror still converges)", async () => {
+		const result = await runScenario({
+			name: "ZC4",
+			mode: "localToCloud",
+			initialLocal: { "/local/a.txt": "a", "/local/dir/c.txt": "c" },
+			steps: [
+				...settle(),
+				localMutate(world => writeLocalAt(world, "new.txt", "fresh", BASE_TIME + 10 * SECOND)),
+				localMutate(world => renameLocal(world, "dir", "dir2")),
+				control(world => world.cloud.controls.setError("renameDirectory", new Error("crash"))),
+				runCycle(),
+				restart(),
+				control(world => {
+					world.cloud.controls.clearError("renameDirectory")
+					world.triggerWatcher()
+				}),
+				runCycle(),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Guard the premise: the crash cycle left partial state (upload landed, rename did not).
+		const crashCycle = result.cycles[2]!
+
+		expect(crashCycle.remote["/new.txt"]).toMatchObject({ type: "file" })
+		expect(crashCycle.remote["/dir2"]).toBeUndefined()
+
+		// The local mirror is authoritative: after the crash the remote is brought back into line with it,
+		// the dropped rename completes, and the partially-uploaded file is present exactly once.
+		expect(result.finalRemote["/new.txt"]).toMatchObject({ type: "file", size: "fresh".length })
+		expect(result.finalRemote["/dir2/c.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/dir"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/zd-inode-reuse.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, localMutate, control, type Step } from "../harness/runner"
+import { writeLocalAt, rmLocal, renameLocal } from "../harness/mutations"
+import { transferKinds } from "../harness/snapshot"
+import { BASE_TIME } from "../harness/world"
+
+const SECOND = 1000
+
+/**
+ * Category ZD — inode reuse must not be misread as a rename.
+ *
+ * The local rename pass keys on inode: an inode that sat at path P in the base but now sits at path Q is
+ * treated as "P renamed to Q". But the OS RECYCLES inode numbers — ext4 hands a just-freed inode to the
+ * very next created file — so "delete a.txt + create c.txt" can put c.txt on a.txt's old inode and be
+ * misread as "rename a.txt -> c.txt". That phantom rename propagates as a REMOTE rename and deletes the
+ * original: silent data loss in modes that keep deletions (localBackup), and invisible in twoWay only
+ * because the stale path was going to be deleted anyway. This is exactly why the live `lifecycle.e2e` I6
+ * test flaked on Linux (ext4) while passing on macOS/Windows and in this fake-fs suite — memfs does not
+ * surface the reuse on its own, so these tests force it with the `setInode` control.
+ *
+ * The fix additionally requires the creation/birthtime to match: a genuine rename (even a rename+modify)
+ * preserves birthtime, whereas a reused inode belongs to a freshly-created file with a newer one.
+ */
+
+function settle(): Step[] {
+	return [runCycle(), runCycle()]
+}
+
+describe("Category ZD — inode reuse is not a rename", () => {
+	it("ZD1: localBackup — a NEW file on a deleted file's recycled inode does NOT delete the original (no phantom rename)", async () => {
+		let reusedInode = 0
+
+		const result = await runScenario({
+			name: "ZD1",
+			mode: "localBackup",
+			initialLocal: { "/local/a.txt": "a", "/local/keep.txt": "k" },
+			steps: [
+				...settle(),
+				// Capture a.txt's inode, delete it (freeing the inode), create a brand-new c.txt, then force
+				// c.txt onto a.txt's freed inode — exactly what ext4 does and memfs will not do on its own.
+				control(world => {
+					reusedInode = world.vfs.controls.getInode("/local/a.txt")!
+				}),
+				localMutate(world => rmLocal(world, "a.txt")),
+				localMutate(world => writeLocalAt(world, "c.txt", "c", BASE_TIME + 30 * SECOND)),
+				control(world => world.vfs.controls.setInode("/local/c.txt", reusedInode)),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		const reuseCycle = result.cycles[2]!
+
+		// The reuse must NOT be propagated as a rename of the remote original.
+		expect(transferKinds(reuseCycle.messages)).not.toContain("renameRemoteFile")
+		// localBackup keeps remote-only files: the original survives, and the genuinely new file is uploaded.
+		expect(result.finalRemote["/a.txt"]).toMatchObject({ type: "file", size: 1 })
+		expect(result.finalRemote["/c.txt"]).toMatchObject({ type: "file", size: 1 })
+		expect(result.finalRemote["/keep.txt"]).toMatchObject({ type: "file" })
+	})
+
+	it("ZD2: twoWay — inode reuse is a delete+add, never a phantom rename", async () => {
+		let reusedInode = 0
+
+		const result = await runScenario({
+			name: "ZD2",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "aaaa", "/local/keep.txt": "k" },
+			steps: [
+				...settle(),
+				control(world => {
+					reusedInode = world.vfs.controls.getInode("/local/a.txt")!
+				}),
+				localMutate(world => rmLocal(world, "a.txt")),
+				localMutate(world => writeLocalAt(world, "c.txt", "cc", BASE_TIME + 30 * SECOND)),
+				control(world => world.vfs.controls.setInode("/local/c.txt", reusedInode)),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		const reuseCycle = result.cycles[2]!
+
+		// twoWay would also end up with a.txt gone and c.txt present even WITH the phantom rename (the rename
+		// + a follow-up content upload coincidentally lands the same end state), so the meaningful guarantee
+		// is the EMITTED intent: a delete + an add, never a rename of the unrelated original.
+		expect(transferKinds(reuseCycle.messages)).not.toContain("renameRemoteFile")
+		// The deletion genuinely propagated and the new file carries ITS OWN content ("cc" = 2 bytes), not
+		// the original's ("aaaa" = 4 bytes).
+		expect(result.finalRemote["/a.txt"]).toBeUndefined()
+		expect(result.finalRemote["/c.txt"]).toMatchObject({ type: "file", size: 2 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("ZD3: a genuine rename (inode AND birthtime preserved) is still detected as a rename, not a re-upload", async () => {
+		const result = await runScenario({
+			name: "ZD3",
+			mode: "twoWay",
+			initialLocal: { "/local/old.txt": "data", "/local/keep.txt": "k" },
+			steps: [
+				...settle(),
+				localMutate(world => renameLocal(world, "old.txt", "new.txt")),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		const renameCycle = result.cycles[2]!
+
+		// The creation-match guard must NOT over-correct: a real move (memfs rename preserves inode AND
+		// birthtime, like a real fs) still propagates as a rename — no content re-upload.
+		expect(transferKinds(renameCycle.messages)).toContain("renameRemoteFile")
+		expect(transferKinds(renameCycle.messages)).not.toContain("upload")
+		expect(result.finalRemote["/new.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/old.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})