@filen/sync 0.2.1 → 0.3.2

package/tests/scenarios/i-lifecycle.test.ts

@@ -0,0 +1,353 @@
+import { describe, it, expect, vi } from "vitest"
+import pathModule from "path"
+import { PauseSignal } from "@filen/sdk"
+import { SYNC_INTERVAL } from "../../src/constants"
+import SyncWorker from "../../src/index"
+import { type SyncMessage } from "../../src/types"
+import { type SyncEnvironment } from "../../src/lib/environment"
+import { DEVICE_ID_VERSION } from "../../src/lib/filesystems/remote"
+import { createWorld, BASE_TIME, DB_ROOT, type CreateWorldOptions, type World } from "../harness/world"
+import { snapshotLocal, snapshotRemote, messagesOfType, countMessages, transferKinds, allOps } from "../harness/snapshot"
+import { writeLocal, rmLocal } from "../harness/mutations"
+
+/**
+ * Category I — lifecycle / control / transfers (behavioral spec §I, §8). These exercise the
+ * SyncWorker control surface that drives a pair's lifecycle: `runOnce` (one cycle then cleanup),
+ * `updatePaused` (short-circuit / resume), `updateRemoved` (abort transfers + delete db files),
+ * the per-transfer `pauseTransfer`/`resumeTransfer`/`stopTransfer` signals keyed `${type}:${path}`,
+ * `updateMode` (mode change takes effect next cycle), and `updateSyncPairs` (runtime registration).
+ *
+ * Like Category G these cycles are driven MANUALLY (not via runScenario): fake timers are installed,
+ * the clock is pinned to BASE_TIME, and {@link plainCycle} pumps the sync interval before each
+ * {@link Sync.runCycle}. This gives the deterministic control the lifecycle assertions need.
+ */
+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()
+	}
+}
+
+/** Drive exactly one cycle (advance the interval so the local-change wait passes, then run). */
+async function plainCycle(world: World): Promise<void> {
+	await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+	await world.sync.runCycle()
+}
+
+/** The messages appended to the world's stream while `body` runs (a per-cycle slice). */
+async function capture(world: World, body: () => Promise<void>): Promise<SyncMessage[]> {
+	const mark = world.messages.length
+
+	await body()
+
+	return world.messages.slice(mark)
+}
+
+describe("Category I — lifecycle / control / transfers", () => {
+	it("I1: a runOnce worker performs a single cycle, syncs, then cleans up and exits without rescheduling", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				initialLocal: { "/local/a.txt": "hello" }
+			},
+			async world => {
+				// A runOnce pair is a WORKER-level constructor option, so build a second worker over the
+				// same virtual fs + cloud + pair. Its messages land on a private stream (process.onMessage
+				// is replaced when the worker is constructed), so assert against that stream directly.
+				const messages: SyncMessage[] = []
+				const environment: SyncEnvironment = {
+					fs: world.vfs.fs,
+					globFs: world.vfs.globFs,
+					writeFileAtomic: async (filename, data, writeOptions): Promise<void> => {
+						await world.vfs.fs.writeFile(filename, data, writeOptions)
+					},
+					createWatcher: async (_path, _onChange) => ({
+						close: async (): Promise<void> => {}
+					}),
+					fetchDirTree: (_sdk, request) => world.cloud.sdk.api(3).dir().tree(request)
+				}
+
+				const worker = new SyncWorker({
+					syncPairs: [world.syncPair],
+					dbPath: DB_ROOT,
+					sdk: world.cloud.sdk,
+					onMessage: message => {
+						messages.push(message)
+					},
+					disableLogging: true,
+					environment,
+					runOnce: true
+				})
+
+				// initialize() floats the self-driving run() loop; for runOnce that loop runs one cycle
+				// then calls cleanup() (which emits cycleExited) instead of rescheduling. Pump until the
+				// terminal message arrives — the cycle never blocks, so this settles in a few iterations.
+				await worker.initialize()
+
+				for (let tick = 0; tick < 200 && !messages.some(message => message.type === "cycleExited"); tick++) {
+					await vi.advanceTimersByTimeAsync(100)
+				}
+
+				// The one cycle ran: the pending local file was uploaded and the worlds converged.
+				expect(transferKinds(messages)).toContain("upload")
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+
+				// Terminal state: it cleaned up (cycleExited) and did NOT schedule another cycle.
+				expect(messages.some(message => message.type === "cycleExited")).toBe(true)
+				expect(countMessages(messages, "cycleRestarting")).toBe(0)
+				expect(worker.syncs[world.syncPair.uuid]!.removed).toBe(true)
+			}
+		)
+	})
+
+	it("I2: a paused pair short-circuits its cycle and resuming lets the pending change sync", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				paused: true
+			},
+			async world => {
+				const uuid = world.syncPair.uuid
+
+				// A change is pending while the pair is paused.
+				writeLocal(world, "a.txt", "v1")
+				world.triggerWatcher()
+
+				const pausedCycle = await capture(world, () => plainCycle(world))
+
+				// The cycle short-circuits before doing any work: cyclePaused is emitted, nothing starts.
+				expect(messagesOfType(pausedCycle, "cyclePaused").length).toBeGreaterThan(0)
+				expect(countMessages(pausedCycle, "cycleStarted")).toBe(0)
+				expect(allOps(pausedCycle)).toEqual([])
+				// No op happened: the pending addition was NOT uploaded.
+				expect(snapshotRemote(world)).toEqual({})
+
+				// Resume via the worker control method, then run a cycle.
+				world.worker.updatePaused(uuid, false)
+				world.triggerWatcher()
+
+				const resumedCycle = await capture(world, () => plainCycle(world))
+
+				// Now the pending change syncs and the worlds converge.
+				expect(messagesOfType(resumedCycle, "cyclePaused").length).toBe(0)
+				expect(transferKinds(resumedCycle)).toContain("upload")
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+			}
+		)
+	})
+
+	it("I3: removing a pair aborts its in-flight transfers, deletes its db files, and exits", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				initialLocal: { "/local/a.txt": "a" }
+			},
+			async world => {
+				const uuid = world.syncPair.uuid
+
+				// First cycle uploads and persists state + a deviceId, so there are db files to delete.
+				await plainCycle(world)
+
+				const stateFiles = [
+					world.sync.state.previousLocalTreePath,
+					world.sync.state.previousRemoteTreePath,
+					world.sync.state.localFileHashesPath
+				]
+				const deviceIdFile = pathModule.posix.join(DB_ROOT, "deviceId", `v${DEVICE_ID_VERSION}`, uuid)
+
+				for (const file of stateFiles) {
+					expect(world.vfs.controls.exists(file)).toBe(true)
+				}
+				expect(world.vfs.controls.exists(deviceIdFile)).toBe(true)
+
+				// Stand in for an in-flight transfer: a registered, not-yet-aborted controller.
+				world.sync.abortControllers["upload:/a.txt"] = new AbortController()
+
+				const removalMessages = await capture(world, () => world.worker.updateRemoved(uuid, true))
+
+				// The transfer was aborted, the pair is marked removed, and it exited (cleanup -> cycleExited).
+				expect(world.sync.abortControllers["upload:/a.txt"]!.signal.aborted).toBe(true)
+				expect(world.sync.removed).toBe(true)
+				expect(messagesOfType(removalMessages, "cycleExited").length).toBeGreaterThan(0)
+
+				// The persisted state + deviceId files for this pair are gone.
+				for (const file of stateFiles) {
+					expect(world.vfs.controls.exists(file)).toBe(false)
+				}
+				expect(world.vfs.controls.exists(deviceIdFile)).toBe(false)
+			}
+		)
+	})
+
+	it("I4: pauseTransfer and resumeTransfer toggle a specific transfer signal and the pair still syncs", async () => {
+		await withWorld(
+			{
+				mode: "twoWay"
+			},
+			async world => {
+				const uuid = world.syncPair.uuid
+
+				writeLocal(world, "a.txt", "v1")
+				world.triggerWatcher()
+
+				// Stand in for an in-flight upload: a registered pause signal keyed `${type}:${path}`.
+				const signalKey = "upload:/a.txt"
+				world.sync.pauseSignals[signalKey] = new PauseSignal()
+
+				// pauseTransfer / resumeTransfer route by the same key and flip the signal state.
+				world.worker.pauseTransfer(uuid, "upload", "/a.txt")
+				expect(world.sync.pauseSignals[signalKey]!.isPaused()).toBe(true)
+
+				world.worker.resumeTransfer(uuid, "upload", "/a.txt")
+				expect(world.sync.pauseSignals[signalKey]!.isPaused()).toBe(false)
+
+				// An unknown key is a safe no-op: no throw and no signal conjured.
+				world.worker.pauseTransfer(uuid, "download", "/does-not-exist.txt")
+				expect(world.sync.pauseSignals["download:/does-not-exist.txt"]).toBeUndefined()
+
+				// With the signal resumed, the cycle still converges. (NOTE: the fake cloud does not honor
+				// pauseSignal mid-transfer, so end-to-end blocking is not observable here — only the
+				// worker's signal routing is. The transfer consumes/clears the signal when it completes.)
+				await plainCycle(world)
+
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+			}
+		)
+	})
+
+	it("I5: stopping a specific transfer surfaces an error, and the transfer is retried until it converges", async () => {
+		await withWorld(
+			{
+				mode: "twoWay"
+			},
+			async world => {
+				const uuid = world.syncPair.uuid
+
+				writeLocal(world, "a.txt", "v1")
+				world.triggerWatcher()
+
+				// Pre-register the transfer's abort controller (as if it were in flight) and stop it via the
+				// worker. The upload then runs against an already-aborted signal — the closest deterministic
+				// stand-in for a mid-transfer abort, since the harness completes transfers synchronously.
+				const signalKey = "upload:/a.txt"
+				world.sync.abortControllers[signalKey] = new AbortController()
+				world.worker.stopTransfer(uuid, "upload", "/a.txt")
+				expect(world.sync.abortControllers[signalKey]!.signal.aborted).toBe(true)
+
+				const abortedCycle = await capture(world, () => plainCycle(world))
+
+				// The abort is surfaced as an upload transfer error, and nothing was uploaded.
+				const uploadErrors = messagesOfType(abortedCycle, "transfer").filter(
+					message => message.data.of === "upload" && message.data.type === "error"
+				)
+
+				expect(uploadErrors.length).toBeGreaterThan(0)
+				expect(snapshotRemote(world)).toEqual({})
+
+				// Retry on a later cycle: clear the recorded task error (it gates the next cycle) and rerun.
+				// The controller was disposed by the failed transfer, so a fresh one is created and succeeds.
+				world.worker.resetTaskErrors(uuid)
+				world.triggerWatcher()
+
+				const retryCycle = await capture(world, () => plainCycle(world))
+
+				expect(transferKinds(retryCycle)).toContain("upload")
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+
+				// Idempotence: a further cycle with no external change performs no transfer.
+				world.triggerWatcher()
+
+				const settledCycle = await capture(world, () => plainCycle(world))
+
+				expect(allOps(settledCycle)).toEqual([])
+			}
+		)
+	})
+
+	it("I6: updateMode mid-run switches behavior on the next cycle (twoWay -> localBackup stops deletions)", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b" }
+			},
+			async world => {
+				const uuid = world.syncPair.uuid
+
+				// First cycle (twoWay): both files upload and the worlds converge.
+				const firstCycle = await capture(world, () => plainCycle(world))
+
+				expect(transferKinds(firstCycle)).toContain("upload")
+				expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+
+				// Switch to a backup mode; it must take effect on the NEXT cycle.
+				world.worker.updateMode(uuid, "localBackup")
+
+				// Delete one file (a deletion that twoWay WOULD propagate) and add another.
+				rmLocal(world, "a.txt")
+				writeLocal(world, "c.txt", "c")
+				world.triggerWatcher()
+
+				const backupCycle = await capture(world, () => plainCycle(world))
+
+				// localBackup propagates additions but NOT deletions, proving the new mode is active:
+				// the add reached the cloud, the deletion did not.
+				expect(transferKinds(backupCycle)).toContain("upload")
+				expect(transferKinds(backupCycle)).not.toContain("deleteRemoteFile")
+				expect(snapshotRemote(world)["/c.txt"]).toMatchObject({ type: "file" })
+				// The local deletion was NOT mirrored to the cloud (backup keeps the remote copy)…
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				// …and it was not pulled back down either (backup is one-way local -> cloud).
+				expect(snapshotLocal(world)["/a.txt"]).toBeUndefined()
+			}
+		)
+	})
+
+	it("I7: updateSyncPairs is a safe idempotent no-op for empty input and an already-registered pair", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				initialLocal: { "/local/a.txt": "a" }
+			},
+			async world => {
+				const uuid = world.syncPair.uuid
+
+				await plainCycle(world)
+
+				const existingSync = world.worker.syncs[uuid]
+
+				// Empty input returns early; re-registering the existing pair must not recreate its Sync
+				// (the worker guards on syncs[uuid]). Neither call throws or disturbs internal state.
+				await world.worker.updateSyncPairs([])
+				await world.worker.updateSyncPairs([world.syncPair])
+
+				expect(world.worker.syncs[uuid]).toBe(existingSync)
+				expect(Object.keys(world.worker.syncs)).toEqual([uuid])
+
+				// The worker remains healthy after the no-op registrations: a new change still converges.
+				// (NOTE: registering a brand-new pair triggers Sync.initialize() -> the self-scheduling
+				// run() loop, which this direct-runCycle harness does not host; runtime-add of a NEW pair
+				// is therefore covered structurally — method present + idempotent — not end-to-end.)
+				writeLocal(world, "b.txt", "b")
+				world.triggerWatcher()
+
+				await plainCycle(world)
+
+				expect(snapshotRemote(world)["/b.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+			}
+		)
+	})
+})

package/tests/scenarios/j-state-cache.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, restart, control, localMutate } from "../harness/runner"
+import { transferOps, countMessages, snapshotLocal, snapshotRemote } from "../harness/snapshot"
+import { rmLocal } from "../harness/mutations"
+
+/**
+ * Category J — state persistence / cache (behavioral spec §J, §9).
+ *
+ * These pin the durability layer that lets the engine stay quiet across restarts and remote-tree
+ * cache hits:
+ *
+ * - The persisted state lives under `state/v2/<uuid>/` as five line-delimited-JSON files
+ *   (`previousLocalTree`, `previousLocalINodes`, `previousRemoteTree`, `previousRemoteUUIDs`,
+ *   `localFileHashes`); `restart()` rebuilds the engine over the same vfs+cloud so that state is
+ *   reloaded from disk (see {@link restartSync}).
+ * - The `deviceId/v1/<uuid>` file drives the SDK `dir().tree()` cache: once a deviceId has fetched at
+ *   a given revision, the next fetch returns an EMPTY `{files:[],folders:[]}` "unchanged" response,
+ *   which {@link RemoteFileSystem.getDirectoryTree} treats as "data did not change, use cache" — NOT
+ *   as "the remote was emptied".
+ * - `worker.resetCache(uuid)` drops both in-memory tree caches (and the deviceId-cache timestamp) so
+ *   the next cycle performs a fresh full re-scan.
+ * - `localFileHashes` is pruned during the local tree scan: any stored path absent from the freshly
+ *   scanned tree is dropped.
+ * - Corrupt/partial state files degrade to an empty previous state (the line reader swallows
+ *   unparseable lines) rather than throwing, so the engine re-converges instead of crashing.
+ */
+describe("Category J — state persistence / cache", () => {
+	it("J1: persisted previous-trees + hashes round-trip through a restart → next cycle is a no-op", async () => {
+		let preLocalTree: Record<string, unknown> = {}
+		let preRemoteTree: Record<string, unknown> = {}
+		let preHashes: Record<string, string> = {}
+		let postLocalTree: Record<string, unknown> = {}
+		let postRemoteTree: Record<string, unknown> = {}
+		let postHashes: Record<string, string> = {}
+
+		const result = await runScenario({
+			name: "J1",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "alpha", "/local/dir/b.txt": "beta" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				runCycle(),
+				// Capture the in-memory persisted state of the converged engine just before the restart.
+				control(world => {
+					preLocalTree = structuredClone(world.sync.previousLocalTree.tree)
+					preRemoteTree = structuredClone(world.sync.previousRemoteTree.tree)
+					preHashes = structuredClone(world.sync.localFileHashes)
+				}),
+				restart(),
+				// After the restart the NEW engine has loaded its previous state straight from disk.
+				control(world => {
+					postLocalTree = structuredClone(world.sync.previousLocalTree.tree)
+					postRemoteTree = structuredClone(world.sync.previousRemoteTree.tree)
+					postHashes = structuredClone(world.sync.localFileHashes)
+				}),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The reloaded state is non-empty and exactly equals what was persisted (a faithful round-trip).
+		expect(Object.keys(postLocalTree).length).toBeGreaterThan(0)
+		expect(postLocalTree).toEqual(preLocalTree)
+		expect(postRemoteTree).toEqual(preRemoteTree)
+		expect(postHashes).toEqual(preHashes)
+		expect(postLocalTree).toHaveProperty("/a.txt")
+		expect(postRemoteTree).toHaveProperty("/dir/b.txt")
+		expect(postHashes).toHaveProperty("/a.txt")
+
+		// The two cycles after the restart (indices 3 and 4) transfer nothing: state proves convergence.
+		expect(transferOps(result.cycles[3]!.messages)).toEqual([])
+		expect(transferOps(result.cycles[4]!.messages)).toEqual([])
+		expect(countMessages(result.messages, "cycleError")).toBe(0)
+		expect(countMessages(result.messages, "cycleNoChanges")).toBeGreaterThanOrEqual(1)
+
+		// The worlds remain converged and intact across the restart (no data loss).
+		expect(result.finalLocal["/a.txt"]).toMatchObject({ type: "file", size: 5 })
+		expect(result.finalLocal["/dir/b.txt"]).toMatchObject({ type: "file", size: 4 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("J2: an empty deviceId cache-hit tree is read as 'unchanged', not 'remote emptied'", async () => {
+		let revisionBefore = -1
+		let revisionAfter = -1
+
+		const result = await runScenario({
+			name: "J2",
+			mode: "twoWay",
+			initialLocal: { "/local/one.txt": "one", "/local/sub/two.txt": "two" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				runCycle(),
+				// Record the cloud's mutation counter just before a steady-state cycle...
+				control(world => {
+					revisionBefore = world.cloud.controls.revision()
+				}),
+				runCycle(),
+				// ...and again right after it.
+				control(world => {
+					revisionAfter = world.cloud.controls.revision()
+				})
+			]
+		})
+
+		// The steady-state cycle drove the remote tree fetch into its cache-hit (empty-tree) path. The
+		// engine used its cache: no cloud mutation happened (the revision counter is stable) and the
+		// cycle performed no file transfers.
+		expect(revisionBefore).toBeGreaterThanOrEqual(0)
+		expect(revisionAfter).toBe(revisionBefore)
+		expect(transferOps(result.cycles[3]!.messages)).toEqual([])
+		expect(countMessages(result.messages, "cycleNoChanges")).toBeGreaterThanOrEqual(1)
+
+		// Crucially: the empty cache-hit response did NOT delete everything locally — all files survive
+		// on both sides and the worlds stay converged.
+		expect(result.finalLocal["/one.txt"]).toMatchObject({ type: "file", size: 3 })
+		expect(result.finalLocal["/sub/two.txt"]).toMatchObject({ type: "file", size: 3 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("J3: resetCache drops the tree caches and forces a fresh full re-scan that still converges", async () => {
+		let timestampAfterReset = -1
+		let treeKeysAfterReset: string[] = []
+		let timestampAfterRescan = -1
+		let treeKeysAfterRescan: string[] = []
+		let convergedRemote: Record<string, unknown> = {}
+
+		const result = await runScenario({
+			name: "J3",
+			mode: "twoWay",
+			initialLocal: { "/local/keep.txt": "keep-me", "/local/nested/deep.txt": "deep-content" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				runCycle(),
+				// Force a full cache reset on the converged engine, then observe the now-empty remote cache.
+				control(world => {
+					convergedRemote = snapshotRemote(world)
+
+					world.worker.resetCache(world.syncPair.uuid)
+
+					timestampAfterReset = world.sync.remoteFileSystem.getDirectoryTreeCache.timestamp
+					treeKeysAfterReset = Object.keys(world.sync.remoteFileSystem.getDirectoryTreeCache.tree)
+				}),
+				runCycle(),
+				// The cycle had to re-fetch the full remote tree (cache timestamp was 0, forcing a
+				// skipCache fetch) — the cache is repopulated with every node.
+				control(world => {
+					timestampAfterRescan = world.sync.remoteFileSystem.getDirectoryTreeCache.timestamp
+					treeKeysAfterRescan = Object.keys(world.sync.remoteFileSystem.getDirectoryTreeCache.tree)
+				})
+			]
+		})
+
+		// resetCache cleared the remote tree cache outright.
+		expect(timestampAfterReset).toBe(0)
+		expect(treeKeysAfterReset).toEqual([])
+
+		// The next cycle did a fresh full re-scan: a new timestamp and the full tree are back.
+		expect(timestampAfterRescan).toBeGreaterThan(0)
+		expect(treeKeysAfterRescan).toContain("/keep.txt")
+		expect(treeKeysAfterRescan).toContain("/nested/deep.txt")
+
+		// A forced re-scan must not corrupt or lose data: no transfers, no deletions, same converged state.
+		expect(transferOps(result.cycles[3]!.messages)).toEqual([])
+		expect(countMessages(result.messages, "cycleError")).toBe(0)
+		expect(snapshotRemote(result.world)).toEqual(convergedRemote)
+		expect(result.finalLocal["/keep.txt"]).toMatchObject({ type: "file", size: 7 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("J4: a deleted local path's stored hash is pruned while a surviving path's hash is kept", async () => {
+		let hashesBeforeDelete: Record<string, string> = {}
+
+		const result = await runScenario({
+			name: "J4",
+			mode: "twoWay",
+			initialLocal: { "/local/gone.txt": "to-be-deleted", "/local/stays.txt": "survivor" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				// Both uploaded files have a stored md5 hash at this point.
+				control(world => {
+					hashesBeforeDelete = structuredClone(world.sync.localFileHashes)
+				}),
+				localMutate(world => rmLocal(world, "gone.txt")),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// Pre-delete: both paths had a stored hash.
+		expect(hashesBeforeDelete["/gone.txt"]).toEqual(expect.any(String))
+		expect(hashesBeforeDelete["/stays.txt"]).toEqual(expect.any(String))
+
+		// Post-delete cycle: the local scan pruned the now-missing path's hash and kept the survivor's
+		// (still equal to the value it held before the deletion).
+		expect(result.world.sync.localFileHashes["/gone.txt"]).toBeUndefined()
+		expect(result.world.sync.localFileHashes["/stays.txt"]).toBe(hashesBeforeDelete["/stays.txt"])
+
+		// The deletion itself propagated correctly and the surviving file is intact.
+		expect(result.finalLocal["/gone.txt"]).toBeUndefined()
+		expect(result.finalRemote["/gone.txt"]).toBeUndefined()
+		expect(result.finalLocal["/stays.txt"]).toMatchObject({ type: "file", size: "survivor".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("J5: corrupt/partial state files degrade to an empty previous state and the engine re-converges", async () => {
+		let postRestartLocalKeys = -1
+		let postRestartRemoteKeys = -1
+
+		const result = await runScenario({
+			name: "J5",
+			mode: "twoWay",
+			initialLocal: { "/local/safe.txt": "safe-content", "/local/dir/child.txt": "child-content" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				runCycle(),
+				// Overwrite the persisted tree records with unparseable garbage (the dir/files still exist,
+				// so the loader proceeds to read them rather than short-circuiting to "no saved state").
+				control(world => {
+					const state = world.sync.state
+					const garbage = "not-json\n}{ broken line\n<<< corrupt >>>\n"
+
+					for (const filePath of [
+						state.previousLocalTreePath,
+						state.previousLocalINodesPath,
+						state.previousRemoteTreePath,
+						state.previousRemoteUUIDsPath,
+						state.localFileHashesPath
+					]) {
+						world.vfs.ifs.writeFileSync(filePath, garbage)
+					}
+				}),
+				restart(),
+				// The corrupt lines were swallowed: the reloaded previous trees are empty (treated as a
+				// fresh, blank previous state) and the restart did not throw.
+				control(world => {
+					postRestartLocalKeys = Object.keys(world.sync.previousLocalTree.tree).length
+					postRestartRemoteKeys = Object.keys(world.sync.previousRemoteTree.tree).length
+				}),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The corruption was recovered as "empty previous state", not loaded as real data.
+		expect(postRestartLocalKeys).toBe(0)
+		expect(postRestartRemoteKeys).toBe(0)
+
+		// No crash, and because both sides already hold identical content the re-diff needs no transfers.
+		expect(countMessages(result.messages, "cycleError")).toBe(0)
+		expect(transferOps(result.cycles[3]!.messages)).toEqual([])
+		expect(transferOps(result.cycles[4]!.messages)).toEqual([])
+
+		// All originally-synced data survives intact on both sides and the worlds stay converged.
+		expect(snapshotLocal(result.world)["/safe.txt"]).toMatchObject({ type: "file", size: "safe-content".length })
+		expect(result.finalLocal["/safe.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/dir/child.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})