@filen/sync 0.2.1 → 0.3.1

package/tests/e2e/regressions.e2e.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import fs from "fs-extra"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld, restartE2EWorld } from "./harness/world"
+import { settle, expectConverged } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, renameLocal, readLocal, existsLocal, uploadRemote, setLocalMtime, rmLocal, deleteRemote } from "./harness/mutations"
+
+/**
+ * Live-backend counterparts for the audit-round bug fixes, so each fix is proven against the real Filen
+ * backend and not just the fake cloud (the mocked regressions live in tests/scenarios/z*.test.ts and
+ * tests/unit/*lock.test.ts). One login is shared across the whole serial e2e suite.
+ *
+ * Mocked-only by necessity (no e2e counterpart):
+ *   - H1: lock teardown after a FORCED releaseResourceLock failure — the real backend can't be made to
+ *     fail a release on demand. Unit test with injected faults: tests/unit/lock.test.ts + ipc-lock.test.ts.
+ *   - H3: a file edited DURING the local scan (a read-during-scan race) — reproducing it needs deterministic
+ *     control of the scan window, which a real filesystem can't provide without flakiness. Deterministic
+ *     mocked regression with a mid-scan lstat hook: tests/scenarios/zg-edit-during-scan.test.ts.
+ *   - H6: the deletion-confirmation wait must bail (releasing the lock) when the pair is paused/removed.
+ *     This is client-side control flow — the backend plays no part — driven deterministically with fake
+ *     timers in tests/scenarios/g-large-deletion.test.ts (G6/G7); the gate itself is covered live in
+ *     tests/e2e/confirm.e2e.test.ts.
+ *   - H7: the local smoke test must run BEFORE the lock so a local outage never holds the account lock.
+ *     Lock ORDERING during a LOCAL filesystem outage — no backend semantics — driven deterministically
+ *     with an injected fs error + fake timers in tests/scenarios/zi-smoke-test-outage.test.ts.
+ *   - M2/M3: the local-trash eviction sweep must age out trashed DIRECTORIES (not just files), and its
+ *     setInterval must be torn down with the pair. Both are purely LOCAL — a folder on the local disk and
+ *     a client-side timer — with no backend involvement. Deterministic mocked regressions (memfs trash +
+ *     atime backdating + fake timers): tests/scenarios/zj-trash-cleanup.test.ts.
+ *   - M4: a remote deletion must not wipe a LOCALLY-IGNORED file (one present on disk but excluded from the
+ *     scanned tree for a non-.filenignore reason). This is client-side delta-attribution logic; the
+ *     backend's only role (a path deleted remotely) is already exercised by the live deletion tests, and
+ *     the trigger — a base path that became ignored for a nameLength/invalidPath/defaultIgnore/duplicate
+ *     reason — cannot be forced deterministically on the real backend. Driven directly through
+ *     deltas.process() with an injected ignored entry in tests/scenarios/zk-ignore-asymmetry.test.ts.
+ *   - M5: isValidPath must reject Windows names that end in a dot/space (Windows strips them, causing a
+ *     re-sync loop). This is a per-OS path rule that only runs on the win32 branch; the e2e backend host
+ *     here is darwin, whose filesystem does NOT strip trailing dots, so the bug cannot manifest in an e2e
+ *     round-trip. It is covered instead by the cross-platform unit suite (stubbed process.platform) run on
+ *     a real Windows host by the matrixed CI: tests/unit/n-unit.test.ts (isValidPath win32).
+ *   - M6: one cycle must compute its whole delta set under a single mode snapshot, even if updateMode()
+ *     races the cycle. The race window is an await INSIDE deltas.process(); reproducing it needs to flip
+ *     the mode at that exact await, which is only controllable by stubbing the awaited hash — not via the
+ *     backend. Driven deterministically in tests/scenarios/zl-mode-atomicity.test.ts.
+ *   - P4: the local scan must bound how many filesystem stat operations it launches concurrently (the old
+ *     walk mapped every entry to a promise up front — an O(n) pending-promise/memory spike on a huge tree).
+ *     This is a client-side memory/concurrency property: bounded vs unbounded fan-out produces the identical
+ *     tree, so it has no backend-observable effect, and the bound is only measurable by instrumenting
+ *     fs.lstat. The batched scan's CORRECTNESS is exercised by every live scenario here (it sits in the sync
+ *     hot path); the bound itself is asserted with an lstat-counting wrapper in
+ *     tests/scenarios/zm-scan-concurrency.test.ts.
+ *   - L1: a download that fails AFTER staging its temp file must discard the temp instead of orphaning it in
+ *     the local trash dir. The leak is a LOCAL artifact, and the trigger is a failure of the local commit
+ *     move (or a partial transfer) — neither of which the real backend can be made to produce on demand (a
+ *     backend-side abort takes the size-mismatch path, which already cleaned up). Driven deterministically by
+ *     failing the commit move in tests/scenarios/zo-download-temp-cleanup.test.ts.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — audit regression fixes against live backend", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	// ---- C1: create nested dirs from the sync root; don't swallow failed top-level remote ops ----------
+
+	it("C1: moving a top-level file into a NEW 2-level directory converges with no resurrection", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "hello")
+			await writeLocal(world, "keep.txt", "k")
+			await settle(world)
+
+			// Move a TOP-LEVEL file into a directory chain that does NOT exist yet (x/y). The cross-parent
+			// rename must build x then y from the sync root inline. The old broken mkdir threw here; the throw
+			// was swallowed for the top-level source (fileExists returned false for every top-level file), so
+			// the task was dropped, a skewed base was persisted, and the file was resurrected + duplicated.
+			await renameLocal(world, "a.txt", "x/y/a.txt")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/a.txt"], "the moved-away original must not survive on the remote").toBeUndefined()
+			expect(remote["/x/y/a.txt"]).toMatchObject({ type: "file", size: 5 })
+			expect(await existsLocal(world, "a.txt")).toBe(false)
+			expect(await readLocal(world, "x/y/a.txt")).toBe("hello")
+			await expectConverged(world)
+		})
+	})
+
+	it("C1: moving a directory into a NEW 2-level directory converges", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "dir/child.txt", "c")
+			await writeLocal(world, "keep.txt", "k")
+			await settle(world)
+
+			await renameLocal(world, "dir", "x/y/dir")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/dir"]).toBeUndefined()
+			expect(remote["/x/y/dir/child.txt"]).toMatchObject({ type: "file" })
+			await expectConverged(world)
+		})
+	})
+
+	// ---- H2: a remote change wins over an UNCHANGED local copy regardless of the mtime tiebreak --------
+
+	it("H2: a remote edit with a non-newer mtime is pulled when the local copy is unchanged", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "v1")
+			// Age the local copy into the FUTURE so the remote edit that follows lands with an OLDER mtime,
+			// while the local copy itself stays byte-for-byte unchanged vs the base. Only the remote moved,
+			// so it is not a conflict — the newer-mtime tiebreak must not gate the pull.
+			await setLocalMtime(world, "a.txt", Date.now() + 600_000)
+			await settle(world)
+
+			// A peer re-uploads new content (a new version → new uuid); its lastModified is ~now, i.e. BEHIND
+			// the local copy's future mtime. The change must still be pulled down.
+			await uploadRemote(world, "a.txt", "v2-remote-edit")
+			await settle(world)
+
+			expect(await readLocal(world, "a.txt")).toBe("v2-remote-edit")
+			await expectConverged(world)
+		})
+	})
+
+	// ---- H5: a directory deletion must not cascade over a live child the other side did not delete -----
+
+	it("H5: a remote directory delete does not wipe a child added locally in the same window", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "dir/keep.txt", "keep")
+			await writeLocal(world, "other.txt", "o")
+			await settle(world)
+
+			// A peer deletes the whole directory while we add a brand-new file into it.
+			await deleteRemote(world, "dir")
+			await writeLocal(world, "dir/new.txt", "new-child")
+			await settle(world)
+
+			// The new child survives (uploaded), the directory is re-asserted, the unmodified base child the
+			// peer deleted is gone, and both sides converge — the delete did not cascade over the new file.
+			expect(await existsLocal(world, "dir/new.txt")).toBe(true)
+			expect(await readLocal(world, "dir/new.txt")).toBe("new-child")
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/dir/new.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/dir/keep.txt"]).toBeUndefined()
+			await expectConverged(world)
+		})
+	})
+
+	it("H5 (symmetric): a local directory delete does not wipe a child the remote added in the same window", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "dir/keep.txt", "keep")
+			await writeLocal(world, "other.txt", "o")
+			await settle(world)
+
+			// We delete the directory locally while a peer adds a new file into it remotely.
+			await rmLocal(world, "dir")
+			await uploadRemote(world, "dir/new.txt", "remote-new")
+			await settle(world)
+
+			expect(await existsLocal(world, "dir/new.txt")).toBe(true)
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/dir/new.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/dir/keep.txt"]).toBeUndefined()
+			await expectConverged(world)
+		})
+	})
+
+	// ---- M1: a saved state with a MISSING local-inodes file must reload as "no saved state", not crash --
+
+	it("M1: a missing local-inodes state file recovers (re-derives) on restart instead of crashing", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "alpha")
+			await writeLocal(world, "dir/b.txt", "bravo")
+			await settle(world)
+			await expectConverged(world)
+
+			// The loader reads the local-INODES file unconditionally, but its existence guard checked the
+			// remote-tree file twice and never this one. Drop it to mimic a partial / interrupted state write
+			// (a present tree file with a missing inodes sibling).
+			const inodesPath = world.sync.state.previousLocalINodesPath
+
+			await fs.rm(inodesPath, { force: true })
+
+			expect(await fs.pathExists(inodesPath)).toBe(false)
+
+			// A restart reloads persisted state from disk. With the bug this throws ENOENT and bricks startup;
+			// with the fix it degrades to "no saved state", re-derives the base from disk, and stays converged.
+			await restartE2EWorld(world)
+			await settle(world)
+
+			expect(await readLocal(world, "a.txt")).toBe("alpha")
+			expect(await readLocal(world, "dir/b.txt")).toBe("bravo")
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/a.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/dir/b.txt"]).toMatchObject({ type: "file" })
+			await expectConverged(world)
+		})
+	})
+})

package/tests/e2e/resilience.e2e.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import os from "os"
+import pathModule from "path"
+import fs from "fs-extra"
+import { v4 as uuidv4 } from "uuid"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld, restartE2EWorld } from "./harness/world"
+import { cycle, settle, expectConverged, allOps, messagesOfType } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, modifyLocal, rmLocal, renameLocal, uploadRemote, chmodLocal, existsLocal } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — resilience + long-lived stability against the live backend. The mocked suite injects
+ * faults and drives many cycles with fake timers; here the equivalents run against the real filesystem
+ * and real backend, so we know the engine survives a genuinely unreadable file and that a long-lived
+ * sync stays correct (and quiet) across many real mutation rounds and a restart.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — resilience & long-lived stability", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("a permission-denied local file is skipped and the cycle continues (posix, non-root)", async ctx => {
+		// Windows' permission model doesn't deny reads via chmod, and root bypasses 0o000 entirely — in
+		// either case the permission guard can't trigger, so probe first and skip rather than mis-assert.
+		if (process.platform === "win32") {
+			ctx.skip()
+
+			return
+		}
+
+		const probeDir = await fs.mkdtemp(pathModule.join(os.tmpdir(), `e2e-perm-probe-${uuidv4()}-`))
+		const probeFile = pathModule.join(probeDir, "p")
+
+		await fs.writeFile(probeFile, "x")
+		await fs.chmod(probeFile, 0o000)
+
+		let denies = false
+
+		try {
+			await fs.readFile(probeFile)
+		} catch {
+			denies = true
+		}
+
+		await fs.chmod(probeFile, 0o644).catch(() => {})
+		await fs.rm(probeDir, { recursive: true, force: true }).catch(() => {})
+
+		if (!denies) {
+			ctx.skip()
+
+			return
+		}
+
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "ok.txt", "fine")
+			await writeLocal(world, "denied.txt", "secret")
+			await chmodLocal(world, "denied.txt", 0o000)
+
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			// The readable file syncs; the unreadable one is skipped (never uploaded), and the cycle did
+			// not crash on it.
+			expect(remote["/ok.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/denied.txt"]).toBeUndefined()
+
+			// Restore permissions so teardown can clean up without relying on directory-level removal.
+			await chmodLocal(world, "denied.txt", 0o644)
+		})
+	})
+
+	it("a failed local writable smoke test retries until the path heals, then syncs (Q1, posix, non-root)", async ctx => {
+		// The smoke test gates each cycle on the sync root being writable; a read-only root must not crash
+		// the cycle — it emits cycleLocalSmokeTestFailed and retries every SYNC_INTERVAL until it heals.
+		// Windows chmod doesn't deny dir writes and root bypasses the W_OK bit, so probe-then-skip.
+		if (process.platform === "win32") {
+			ctx.skip()
+
+			return
+		}
+
+		const probeDir = await fs.mkdtemp(pathModule.join(os.tmpdir(), `e2e-rodir-probe-${uuidv4()}-`))
+
+		await fs.chmod(probeDir, 0o555)
+
+		let denies = false
+
+		try {
+			await fs.access(probeDir, fs.constants.W_OK)
+		} catch {
+			denies = true
+		}
+
+		await fs.chmod(probeDir, 0o755).catch(() => {})
+		await fs.rm(probeDir, { recursive: true, force: true }).catch(() => {})
+
+		if (!denies) {
+			ctx.skip()
+
+			return
+		}
+
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "data")
+
+			// Make the sync root unwritable, then drive a cycle WITHOUT awaiting — its smoke test fails and
+			// the cycle parks on a retry loop instead of erroring.
+			await fs.chmod(world.localRoot, 0o555)
+
+			try {
+				world.worker.resetCache(world.syncPair.uuid)
+
+				const cyclePromise = world.sync.runCycle()
+
+				// Wait for the smoke test to report the failure (it then sleeps SYNC_INTERVAL before retrying).
+				for (let tick = 0; tick < 40 && messagesOfType(world.messages, "cycleLocalSmokeTestFailed").length === 0; tick++) {
+					await new Promise<void>(resolve => setTimeout(resolve, 100))
+				}
+
+				expect(messagesOfType(world.messages, "cycleLocalSmokeTestFailed").length).toBeGreaterThan(0)
+				// Nothing synced while the smoke test was failing.
+				expect((await snapshotRemoteReal(world))["/a.txt"]).toBeUndefined()
+
+				// Heal the path; the next retry passes and the cycle completes its work.
+				await fs.chmod(world.localRoot, 0o755)
+
+				await cyclePromise
+			} finally {
+				// Always restore writability so teardown can remove the tree.
+				await fs.chmod(world.localRoot, 0o755).catch(() => {})
+			}
+
+			await settle(world)
+			await expectConverged(world)
+
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("a deleted remote root parks on the remote smoke test and does NOT delete local files (Q3, data-loss guard)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			await writeLocal(world, "b.txt", "b")
+			await settle(world)
+			await expectConverged(world)
+
+			// Another client deletes the ENTIRE synced remote folder. The engine must NOT read this as
+			// "remote emptied" and mirror-delete the local files — the remote smoke test catches the missing
+			// root first and parks the cycle (retrying) instead.
+			await sdk.cloud().deleteDirectory({ uuid: world.remoteParentUUID })
+
+			world.worker.resetCache(world.syncPair.uuid)
+
+			const cyclePromise = world.sync.runCycle()
+
+			try {
+				for (let tick = 0; tick < 60 && messagesOfType(world.messages, "cycleRemoteSmokeTestFailed").length === 0; tick++) {
+					await new Promise<void>(resolve => setTimeout(resolve, 100))
+				}
+
+				expect(messagesOfType(world.messages, "cycleRemoteSmokeTestFailed").length).toBeGreaterThan(0)
+				// The critical guarantee: the vanished remote did NOT cause the local files to be deleted.
+				expect(await existsLocal(world, "a.txt")).toBe(true)
+				expect(await existsLocal(world, "b.txt")).toBe(true)
+			} finally {
+				// The remote root uuid is gone for good, so the parked cycle can never heal — remove the pair
+				// to abort its retry loop (smokeTest throws "Aborted" once removed), then drain it.
+				await world.worker.updateRemoved(world.syncPair.uuid, true).catch(() => {})
+				await cyclePromise.catch(() => {})
+			}
+		})
+	})
+
+	it("a long-lived sync stays correct across many real mutation rounds and a restart, then no-ops", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			// Round 1 — create a small tree.
+			await writeLocal(world, "doc.txt", "v1")
+			await writeLocal(world, "dir/nested.txt", "n1")
+			await settle(world)
+			await expectConverged(world)
+
+			// Round 2 — modify.
+			await modifyLocal(world, "doc.txt", "v2-longer-content")
+			await settle(world)
+			await expectConverged(world)
+
+			// Round 3 — rename.
+			await renameLocal(world, "doc.txt", "renamed.txt")
+			await settle(world)
+			await expectConverged(world)
+
+			// Round 4 — a remote-originated addition (a peer client).
+			await uploadRemote(world, "from-remote.txt", "r1")
+			await settle(world)
+			await expectConverged(world)
+
+			// Round 5 — survive a process restart with no work, then keep going.
+			await restartE2EWorld(world)
+			await settle(world)
+			await expectConverged(world)
+
+			// Round 6 — delete.
+			await rmLocal(world, "dir/nested.txt")
+			await settle(world)
+			await expectConverged(world)
+
+			// After all that churn, a settled cycle must be a COMPLETE no-op — the long-lived sync is quiet.
+			const messages = await cycle(world)
+
+			expect(allOps(messages)).toEqual([])
+
+			// Final-state sanity across the whole history.
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/renamed.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/from-remote.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/dir/nested.txt"]).toBeUndefined()
+			expect(await existsLocal(world, "renamed.txt")).toBe(true)
+			expect(await existsLocal(world, "from-remote.txt")).toBe(true)
+		})
+	})
+})

package/tests/e2e/special.e2e.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import os from "os"
+import pathModule from "path"
+import fs from "fs-extra"
+import { v4 as uuidv4 } from "uuid"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { settle, expectConverged } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, modifyLocal, writeLocalPreservingMtime, symlinkLocal, rmLocal, existsLocal } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — special files against the live backend: symlinks (skipped, BUG-006) and size-edge
+ * transitions (truncate-to-0, grow-from-0).
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — special files", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("skips symlinks: they never sync and don't break the cycle (BUG-006)", async ctx => {
+		// Probe symlink support first (Windows without Developer Mode can't create them).
+		const probeDir = pathModule.join(os.tmpdir(), `e2e-symlink-probe-${uuidv4()}`)
+
+		await fs.ensureDir(probeDir)
+
+		let symlinksSupported = true
+
+		try {
+			await fs.symlink(pathModule.join(probeDir, "target"), pathModule.join(probeDir, "link"))
+		} catch {
+			symlinksSupported = false
+		}
+
+		await fs.rm(probeDir, { recursive: true, force: true }).catch(() => {})
+
+		if (!symlinksSupported) {
+			ctx.skip()
+
+			return
+		}
+
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "real.txt", "real")
+
+			// A symlink pointing outside the sync root — must be skipped, never followed/uploaded.
+			const externalTarget = pathModule.join(os.tmpdir(), `e2e-symlink-target-${uuidv4()}.txt`)
+
+			await fs.writeFile(externalTarget, "external content")
+
+			try {
+				await symlinkLocal(world, "link.txt", externalTarget)
+
+				await settle(world)
+
+				const remote = await snapshotRemoteReal(world)
+
+				expect(remote["/real.txt"]).toMatchObject({ type: "file" })
+				expect(remote["/link.txt"]).toBeUndefined()
+				// The real file converges; the symlink is simply absent on both sides of the comparison.
+				await expectConverged(world)
+			} finally {
+				await fs.rm(externalTarget, { force: true }).catch(() => {})
+			}
+		})
+	})
+
+	it("a synced file replaced by a symlink is skipped, and the cloud copy survives (F15/BUG-006)", async ctx => {
+		// Probe symlink support first (Windows without Developer Mode can't create them).
+		const probeDir = pathModule.join(os.tmpdir(), `e2e-symlink-probe-${uuidv4()}`)
+
+		await fs.ensureDir(probeDir)
+
+		let symlinksSupported = true
+
+		try {
+			await fs.symlink(pathModule.join(probeDir, "target"), pathModule.join(probeDir, "link"))
+		} catch {
+			symlinksSupported = false
+		}
+
+		await fs.rm(probeDir, { recursive: true, force: true }).catch(() => {})
+
+		if (!symlinksSupported) {
+			ctx.skip()
+
+			return
+		}
+
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			// A file synced normally to the cloud…
+			await writeLocal(world, "data.txt", "real content")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/data.txt"]).toMatchObject({ type: "file" })
+
+			// …is then replaced in place by a (dangling) symlink. The walk lstats it, sees a link, and skips
+			// it structurally; a structurally-skipped path is treated like ignore-after-sync, so the cloud
+			// copy is NOT deleted (mirrors mocked F15 — prevents data loss after the lstat upgrade). The two
+			// sides are intentionally divergent here (local no longer syncs the path), so we assert the cloud
+			// survivor directly rather than convergence.
+			await rmLocal(world, "data.txt")
+			await symlinkLocal(world, "data.txt", pathModule.join(os.tmpdir(), `e2e-dangling-${uuidv4()}.txt`))
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/data.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("round-trips a multi-chunk (>1 MiB) file with byte integrity across chunk boundaries", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			// The SDK uploads in 1 MiB chunks, so 2.5 MiB spans three chunks. The bytes are position-dependent
+			// (not a constant fill), so a dropped, duplicated, or reordered chunk changes the content hash —
+			// not just the size — and the withContent convergence check below would catch it.
+			const size = 2.5 * 1024 * 1024
+			const bytes = new Uint8Array(size)
+
+			for (let i = 0; i < size; i++) {
+				bytes[i] = (i * 31 + 7) % 251
+			}
+
+			await writeLocal(world, "big.bin", bytes)
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/big.bin"]).toMatchObject({ type: "file", size })
+
+			// withContent downloads the remote copy and sha512s both sides → proves byte-for-byte integrity
+			// of the large file after a full upload-then-download round trip through the real backend.
+			await expectConverged(world)
+		})
+	})
+
+	it("truncating a file to 0 bytes propagates", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "shrink.txt", "hello world")
+			await settle(world)
+
+			// modifyLocal stamps a clearly-newer mtime so the change is detected regardless of how fast the
+			// prior settle ran (change detection is mtime-gated at whole-second precision; size is not compared).
+			await modifyLocal(world, "shrink.txt", "")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/shrink.txt"]).toMatchObject({ type: "file", size: 0 })
+			await expectConverged(world)
+		})
+	})
+
+	it("growing a file from 0 bytes propagates", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "grow.txt", "")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/grow.txt"]).toMatchObject({ type: "file", size: 0 })
+
+			await modifyLocal(world, "grow.txt", "now it has content")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/grow.txt"]).toMatchObject({ type: "file", size: 18 })
+			expect(await existsLocal(world, "grow.txt")).toBe(true)
+			await expectConverged(world)
+		})
+	})
+
+	it("propagates a same-mtime size change (base-relative detection, E2E-OBS-002)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "sized.txt", "12345678")
+			await settle(world)
+
+			// Change the size but restore the original mtime: the whole-second mtime is unchanged, so only
+			// the base-relative size comparison can detect this edit (the old side-vs-side gate missed it).
+			await writeLocalPreservingMtime(world, "sized.txt", "123")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/sized.txt"]).toMatchObject({ type: "file", size: 3 })
+			await expectConverged(world)
+		})
+	})
+})