@filen/sync 0.2.1 → 0.3.2

package/tests/e2e/modes.e2e.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { settle, expectConverged } from "./harness/drive"
+import { snapshotLocalReal, snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, modifyLocal, rmLocal, renameLocal, renameRemoteDir, readLocal, existsLocal, uploadRemote, deleteRemote } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — one-way mode semantics against the live backend. localToCloud pushes local changes up
+ * and ignores remote-only changes; cloudToLocal pulls remote changes down and ignores local-only
+ * changes. (The brand-new-file boundary is in sync.e2e.test.ts; here the ignored side acts on
+ * already-synced items.)
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — one-way mode semantics", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	// ---- localToCloud (local is authoritative) ----------------------------------------------------
+
+	it("localToCloud: a local content modification is pushed to the remote", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud" }, async world => {
+			await writeLocal(world, "doc.txt", "v1aa")
+			await settle(world)
+
+			await modifyLocal(world, "doc.txt", "v2bb")
+			await settle(world)
+
+			const local = await snapshotLocalReal(world, { withContent: true })
+			const remote = await snapshotRemoteReal(world, { withContent: true })
+
+			expect(remote["/doc.txt"]!.contentHash).toBe(local["/doc.txt"]!.contentHash)
+		})
+	})
+
+	it("localToCloud: a local deletion is pushed to the remote", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud" }, async world => {
+			await writeLocal(world, "drop.txt", "x")
+			await settle(world)
+
+			await rmLocal(world, "drop.txt")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/drop.txt"]).toBeUndefined()
+		})
+	})
+
+	it("localToCloud: a local rename is pushed to the remote", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud" }, async world => {
+			await writeLocal(world, "before.txt", "data")
+			await settle(world)
+
+			await renameLocal(world, "before.txt", "after.txt")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/before.txt"]).toBeUndefined()
+			expect(remote["/after.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	// ---- cloudToLocal (remote is authoritative) ---------------------------------------------------
+
+	it("cloudToLocal: a remote deletion is pulled down to local", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal" }, async world => {
+			await uploadRemote(world, "remote-drop.txt", "x")
+			await settle(world)
+
+			expect(await existsLocal(world, "remote-drop.txt")).toBe(true)
+
+			await deleteRemote(world, "remote-drop.txt")
+			await settle(world)
+
+			expect(await existsLocal(world, "remote-drop.txt")).toBe(false)
+		})
+	})
+
+	it("cloudToLocal: a remote subtree is pulled down to local", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal" }, async world => {
+			await uploadRemote(world, "tree/a.txt", "a")
+			await uploadRemote(world, "tree/deep/b.txt", "b")
+			await settle(world)
+
+			expect(await existsLocal(world, "tree/a.txt")).toBe(true)
+			expect(await existsLocal(world, "tree/deep/b.txt")).toBe(true)
+			expect(await readLocal(world, "tree/deep/b.txt")).toBe("b")
+
+			await expectConverged(world)
+		})
+	})
+
+	it("cloudToLocal: a local modification to a synced file is NOT pushed up", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal" }, async world => {
+			await uploadRemote(world, "shared.txt", "remote-original")
+			await settle(world)
+
+			// Local edit on the pulled-down copy (clearly-newer mtime) must still NOT propagate upward.
+			await modifyLocal(world, "shared.txt", "locally-edited")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world, { withContent: true })
+
+			// Remote still holds the original content (local edit was ignored upward).
+			expect(Buffer.from("remote-original").length).toBe(remote["/shared.txt"]!.size)
+		})
+	})
+
+	// ---- strict mirror: the foreign side is forced to match the authoritative side ----------------
+
+	it("localToCloud: a remote-only file is mirror-DELETED", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud" }, async world => {
+			await writeLocal(world, "mine.txt", "mine")
+			await settle(world)
+
+			// Another device adds a file the local side never had; the mirror must remove it.
+			await uploadRemote(world, "foreign.txt", "theirs")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/foreign.txt"]).toBeUndefined()
+			expect(remote["/mine.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("cloudToLocal: a local-only file is mirror-DELETED", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal" }, async world => {
+			await uploadRemote(world, "remote.txt", "remote")
+			await settle(world)
+
+			// A local-only file the remote never had; the mirror must remove it.
+			await writeLocal(world, "local-only.txt", "mine")
+			await settle(world)
+
+			expect(await existsLocal(world, "local-only.txt")).toBe(false)
+			expect(await existsLocal(world, "remote.txt")).toBe(true)
+		})
+	})
+
+	it("localToCloud: a foreign remote edit to a synced file is REVERTED (F6)", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud" }, async world => {
+			await writeLocal(world, "a.txt", "local-content")
+			await settle(world)
+
+			await uploadRemote(world, "a.txt", "FOREIGN")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world, { withContent: true }))["/a.txt"]!.size).toBe("local-content".length)
+			expect(await readLocal(world, "a.txt")).toBe("local-content")
+		})
+	})
+
+	it("cloudToLocal: a foreign local edit to a synced file is REVERTED (F6)", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal" }, async world => {
+			await uploadRemote(world, "a.txt", "remote-content")
+			await settle(world)
+
+			await modifyLocal(world, "a.txt", "LOCAL-EDIT")
+			await settle(world)
+
+			expect(await readLocal(world, "a.txt")).toBe("remote-content")
+		})
+	})
+
+	// ---- cross-side directory rename + a concurrent child change in a MIRROR mode (BUG-A parity) ------
+	// In twoWay this was the critical data-loss bug; in a mirror the authoritative side always wins, but
+	// the rename-aware rebase must still keep the dir rename and the child change correctly aligned and
+	// the worlds convergent. (Live counterparts of mocked ZB11/ZB12.)
+
+	it("localToCloud: a local dir rename + a foreign remote child edit → local content wins, converges", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud" }, async world => {
+			await writeLocal(world, "dir/child.txt", "old")
+			await writeLocal(world, "dir/sibling.txt", "sib")
+			await settle(world)
+
+			// Rename the directory locally while another device concurrently edits a child at the old path.
+			await renameLocal(world, "dir", "dir2")
+			await uploadRemote(world, "dir/child.txt", "FOREIGN-REMOTE-EDIT")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world, { withContent: true })
+
+			// Local authoritative: the renamed dir wins and the foreign edit is reverted to local content.
+			expect(remote["/dir2/child.txt"]!.size).toBe("old".length)
+			expect(remote["/dir/child.txt"]).toBeUndefined()
+			await expectConverged(world)
+		})
+	})
+
+	it("cloudToLocal: a remote dir rename + a foreign local child edit → remote content wins, converges", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal" }, async world => {
+			await uploadRemote(world, "dir/child.txt", "old")
+			await uploadRemote(world, "dir/sibling.txt", "sib")
+			await settle(world)
+
+			// Another device renames the directory remotely while we edit a child locally at the old path.
+			await renameRemoteDir(world, "dir", "dir2")
+			await modifyLocal(world, "dir/child.txt", "FOREIGN-LOCAL-EDIT")
+			await settle(world)
+
+			// Remote authoritative: the renamed dir wins and the foreign local edit is reverted.
+			expect(await readLocal(world, "dir2/child.txt")).toBe("old")
+			expect(await existsLocal(world, "dir/child.txt")).toBe(false)
+			await expectConverged(world)
+		})
+	})
+})

package/tests/e2e/platform.e2e.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { cycle, settle, allOps } from "./harness/drive"
+import { snapshotLocalReal, snapshotRemoteReal } from "./harness/assert"
+import { uploadRemote, writeLocal } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — cross-platform path rules against the live backend, validated on the REAL OS of each
+ * matrix runner (ubuntu / macos / windows). A "foreign" client (a direct SDK upload) creates a file
+ * whose name or length is illegal on SOME platforms; syncing it down must behave per-OS:
+ *
+ *   - colon `:`           → illegal on win32 + darwin, legal on linux.
+ *   - reserved `com1.txt` → illegal on win32 only, legal on darwin + linux.
+ *   - very long path      → illegal on win32 (>512), legal on darwin (<1024) + linux (<4096).
+ *
+ * On a platform where the name is illegal the engine SKIPS it (never downloads it, never crashes the
+ * cycle, never deletes it from the remote that legitimately holds it). On a platform where it is legal
+ * the file syncs down normally. This is the live counterpart to the mocked Category AC suite — same
+ * rules, asserted against the real filesystem + backend instead of stubbed `process.platform`.
+ *
+ * Unlike most e2e cases these do NOT call `expectConverged`: when a name is illegal locally the two
+ * sides are SUPPOSED to differ (remote keeps it, local can't hold it), so each side is asserted directly.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — cross-platform path rules", () => {
+	let sdk: FilenSDK
+
+	// A path long enough to exceed win32's 512-char limit on its own (so the tmp-dir prefix is
+	// irrelevant) while staying under darwin's 1024 limit once prefixed; every NAME is ≤ 255 (the
+	// uniform name limit) so only `pathLength`, not `nameLength`, is in play.
+	const longPath = `/${"d".repeat(250)}/${"s".repeat(250)}/${"f".repeat(240)}.txt`
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("a colon name syncs down only on linux; elsewhere it is skipped but kept on the remote", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			// Foreign client (e.g. a linux desktop) created these.
+			await uploadRemote(world, "report:v2.txt", "colon — legal on linux only")
+			await uploadRemote(world, "ok.txt", "legal everywhere")
+			await settle(world)
+
+			const [local, remote] = await Promise.all([snapshotLocalReal(world), snapshotRemoteReal(world)])
+
+			// The remote ALWAYS keeps both files (skipping is never deletion).
+			expect(remote["/report:v2.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/ok.txt"]).toMatchObject({ type: "file" })
+			// The valid sibling always lands locally.
+			expect(local["/ok.txt"]).toMatchObject({ type: "file" })
+
+			// The colon file lands locally ONLY on linux (where a colon is a legal filename).
+			if (process.platform === "linux") {
+				expect(local["/report:v2.txt"]).toMatchObject({ type: "file" })
+			} else {
+				expect(local["/report:v2.txt"]).toBeUndefined()
+			}
+
+			// Long-lived stability: with the world already settled, a fresh confirming cycle does zero work
+			// (no transfer, rename, delete, or mkdir) — the perpetually-skipped file never re-churns.
+			const confirming = await cycle(world)
+
+			expect(allOps(confirming)).toEqual([])
+		})
+	})
+
+	it("a Windows reserved device name (com1.txt) syncs down everywhere except win32", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await uploadRemote(world, "com1.txt", "reserved on windows, ordinary elsewhere")
+			await uploadRemote(world, "normal.txt", "fine everywhere")
+			await settle(world)
+
+			const [local, remote] = await Promise.all([snapshotLocalReal(world), snapshotRemoteReal(world)])
+
+			expect(remote["/com1.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/normal.txt"]).toMatchObject({ type: "file" })
+			expect(local["/normal.txt"]).toMatchObject({ type: "file" })
+
+			if (process.platform === "win32") {
+				expect(local["/com1.txt"]).toBeUndefined()
+			} else {
+				expect(local["/com1.txt"]).toMatchObject({ type: "file" })
+			}
+		})
+	})
+
+	it("a path over the win32 length limit syncs down on darwin/linux but is skipped on win32", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await uploadRemote(world, longPath, "long path — over 512 chars")
+			await uploadRemote(world, "short.txt", "fine everywhere")
+			await settle(world)
+
+			const [local, remote] = await Promise.all([snapshotLocalReal(world), snapshotRemoteReal(world)])
+
+			expect(remote[longPath]).toMatchObject({ type: "file" })
+			expect(local["/short.txt"]).toMatchObject({ type: "file" })
+
+			if (process.platform === "win32") {
+				expect(local[longPath]).toBeUndefined()
+			} else {
+				expect(local[longPath]).toMatchObject({ type: "file" })
+			}
+		})
+	})
+
+	it("a name over 255 BYTES but under 255 UTF-16 units syncs down everywhere except linux (byte NAME_MAX)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			// "あ" is 1 UTF-16 code unit but 3 UTF-8 bytes (and has no NFC/NFD ambiguity). 100 of them is
+			// 100 units — under the 255-unit macOS/NTFS NAME limit — yet 300 bytes, over linux's 255-BYTE
+			// NAME_MAX. A foreign macOS/Windows peer legitimately created it.
+			const multibyteName = `${"あ".repeat(100)}.txt`
+
+			await uploadRemote(world, multibyteName, "three hundred bytes of name")
+			await uploadRemote(world, "plain.txt", "fine everywhere")
+			await settle(world)
+
+			const [local, remote] = await Promise.all([snapshotLocalReal(world), snapshotRemoteReal(world)])
+
+			// The remote always keeps it; the valid sibling always lands locally.
+			expect(remote[`/${multibyteName}`]).toMatchObject({ type: "file" })
+			expect(local["/plain.txt"]).toMatchObject({ type: "file" })
+
+			// Lands locally on darwin + win32 (they count UTF-16 units: 100 < 255). Skipped on linux, whose
+			// NAME_MAX is 255 BYTES (300 > 255) — a graceful skip, NOT a per-cycle ENAMETOOLONG retry loop.
+			if (process.platform === "linux") {
+				expect(local[`/${multibyteName}`]).toBeUndefined()
+			} else {
+				expect(local[`/${multibyteName}`]).toMatchObject({ type: "file" })
+			}
+
+			// With the world settled, a confirming cycle does zero work — on linux the perpetually
+			// byte-over-long name never re-churns.
+			const confirming = await cycle(world)
+
+			expect(allOps(confirming)).toEqual([])
+		})
+	})
+
+	it("a LOCAL file legal here but illegal elsewhere uploads normally (the foreign client will skip it)", async () => {
+		// The mirror direction: whatever this OS lets us create locally, the engine uploads. A peer on a
+		// stricter OS is the one that will skip it on the way down — proven by the inbound cases above.
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			// A name every platform can create locally, to keep this test host-agnostic on the upload side.
+			await writeLocal(world, "everywhere-legal.txt", "content")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/everywhere-legal.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+})

package/tests/e2e/property.e2e.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { cycle, settle, expectConverged, allOps } from "./harness/drive"
+import { writeLocal, rmLocal, uploadRemote, deleteRemote } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — property/fuzz convergence against the live backend, the live counterpart of mocked
+ * Category L (twoWay meta-invariants) AND Category AB (directional mirror invariants). A seeded PRNG
+ * builds a random add/modify/delete history over several rounds (settling between rounds), then asserts
+ * on the REAL backend: convergence (both sides end byte-for-byte identical, content hashes included) and
+ * idempotence (a settled cycle does no transfers). Seeded, so any failure reproduces deterministically.
+ *
+ * For the directional modes the convergence assertion IS the mirror invariant: in localToCloud the remote
+ * must end identical to the (authoritative) local side, in cloudToLocal the local must mirror the remote.
+ * So those runs only mutate the AUTHORITATIVE side — the pure "a random source history is always mirrored"
+ * property (foreign-edit reversion is covered by modes.e2e's fixed scenarios). twoWay mutates both sides.
+ *
+ * "Well-behaved" like the mocked property suites, and ENFORCED (not just asserted): each path is touched
+ * at most once per round (no same-cycle same-path ambiguity), rounds are separated by a real settle, and —
+ * crucially — every write carries a UNIQUE SIZE (a strictly-growing payload, see `nextContent`). The engine
+ * detects changes by (whole-second mtime, size), never by re-hashing content every cycle (that per-cycle
+ * cost is the exact thing the perf/memory budget forbids), so two same-size edits that land in the same
+ * whole second are — by design — indistinguishable to it (the documented §C11 blind spot; an accepted
+ * tradeoff, not a bug, avoided by construction in the mocked suites too). Unique sizes keep the fuzz off
+ * that blind spot: the size delta always reveals the edit, so a divergence here is a REAL convergence bug.
+ * Renames are covered exhaustively by conflict.e2e/edge.e2e, so the fuzz stays on add/modify/delete.
+ */
+function mulberry32(seed: number): () => number {
+	let state = seed >>> 0
+
+	return () => {
+		state = (state + 0x6d2b79f5) >>> 0
+
+		let t = Math.imul(state ^ (state >>> 15), 1 | state)
+
+		t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+const FILE_POOL = ["p0.txt", "p1.txt", "p2.txt", "p3.txt", "p4.txt", "p5.txt"]
+const ROUNDS = 6
+const MAX_PER_ROUND = 3
+
+type FuzzMode = "twoWay" | "localToCloud" | "cloudToLocal"
+
+/**
+ * Drive a seeded random history in `mode`, then assert convergence + idempotence. `mutate` selects which
+ * side a given mutation targets: "both" (random) for twoWay, or the fixed authoritative side for a mirror
+ * mode. The seed file is created on whichever side we mutate, so it is never reverted before the run starts.
+ */
+async function runFuzz(sdk: FilenSDK, mode: FuzzMode, seed: number, mutate: "both" | "local" | "remote"): Promise<void> {
+	await withE2EWorld({ sdk, mode }, async world => {
+		const random = mulberry32(seed)
+		const pick = <T>(items: readonly T[]): T => items[Math.floor(random() * items.length)]!
+		const exists = new Set<string>()
+		let mutationCount = 0
+
+		// Every write gets a strictly-growing payload, so no two writes ever share a size — the engine's
+		// (whole-second mtime, size) detector sees every edit even when a fast settle ties the mtimes,
+		// steering clear of the documented same-size/same-second blind spot (§C11) so divergence means a bug.
+		let writeSeq = 0
+		const nextContent = (): string => `s${seed}-w${writeSeq}-${"x".repeat(writeSeq++)}`
+		const pickSide = (): "local" | "remote" => (mutate === "both" ? (random() < 0.5 ? "local" : "remote") : mutate)
+
+		// Seed a file on the authoritative side so early deletes/modifies have something to act on.
+		if (mutate === "remote") {
+			await uploadRemote(world, "p0.txt", nextContent())
+		} else {
+			await writeLocal(world, "p0.txt", nextContent())
+		}
+
+		exists.add("p0.txt")
+		await settle(world)
+
+		for (let round = 0; round < ROUNDS; round++) {
+			const touched = new Set<string>()
+			const mutations = 1 + Math.floor(random() * MAX_PER_ROUND)
+
+			for (let m = 0; m < mutations; m++) {
+				const path = pick(FILE_POOL)
+
+				if (touched.has(path)) {
+					continue
+				}
+
+				touched.add(path)
+
+				const side = pickSide()
+				const doDelete = exists.has(path) && random() < 0.35
+
+				if (doDelete) {
+					exists.delete(path)
+
+					if (side === "local") {
+						await rmLocal(world, path)
+					} else {
+						await deleteRemote(world, path)
+					}
+				} else {
+					exists.add(path)
+
+					const content = nextContent()
+
+					if (side === "local") {
+						await writeLocal(world, path, content)
+					} else {
+						await uploadRemote(world, path, content)
+					}
+				}
+
+				mutationCount++
+			}
+
+			// Settle between rounds so each round starts converged and the next round's writes carry a
+			// strictly-newer real mtime than anything before them.
+			await settle(world)
+		}
+
+		// Convergence (§2.3) — for a mirror mode this IS the mirror invariant (target == authoritative side).
+		await settle(world)
+		await expectConverged(world)
+
+		// Idempotence (§2.2): a further settled cycle performs no operations at all — not just no transfers,
+		// but no spurious rename/delete/mkdir either (allOps, so an idempotence violation can't hide).
+		const messages = await cycle(world)
+
+		expect(allOps(messages), `seed=${seed} mode=${mode} was not idempotent`).toEqual([])
+		// Sanity: the history actually exercised the engine.
+		expect(mutationCount).toBeGreaterThan(0)
+	})
+}
+
+describe.skipIf(!E2E_ENABLED)("E2E — property/fuzz (live convergence)", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	// Category L — twoWay, both sides mutated.
+	for (const seed of [0xc0ffee, 0x5eed01, 0x1337beef]) {
+		it(`twoWay seed=${seed}: a random two-sided history converges and is idempotent`, async () => {
+			await runFuzz(sdk, "twoWay", seed, "both")
+		})
+	}
+
+	// Category AB — directional mirror: a random authoritative-side history is always mirrored to the target.
+	it("localToCloud: a random local history is always mirrored to the remote (idempotent)", async () => {
+		await runFuzz(sdk, "localToCloud", 0xfeed42, "local")
+	})
+
+	it("cloudToLocal: a random remote history is always mirrored to the local (idempotent)", async () => {
+		await runFuzz(sdk, "cloudToLocal", 0x0b00b1, "remote")
+	})
+})

package/tests/e2e/races.e2e.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import { v4 as uuidv4 } from "uuid"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { settle, expectConverged, messagesOfType } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, deleteRemote } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — concurrency / multi-device races against the live backend, the live counterpart of mocked
+ * Category AA. Unlike the fake cloud (whose contended lock makes the cycle error out), the real engine
+ * acquires the sync resource lock with `maxTries: Infinity`, so a device that already holds the lock makes
+ * the cycle WAIT — the important production property: two devices syncing the same folder never corrupt
+ * each other, the loser simply blocks until the lock frees. We hold the real lock from a second SDK
+ * "device" to prove this, then prove a concurrent delete+recreate still converges with no task errors.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — races & multi-device contention", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("a cycle waits for a contending device's lock, does no work, then converges once released (AA1/AA2)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "data")
+
+			// The exact resource the engine locks (lib/sync.ts) — a second device grabs it first.
+			const resource = `sync-remoteParentUUID-${world.remoteParentUUID}`
+			const otherDevice = uuidv4()
+
+			await sdk.user().acquireResourceLock({ resource, lockUUID: otherDevice, maxTries: 1, tryTimeout: 1000 })
+
+			world.worker.resetCache(world.syncPair.uuid)
+
+			let cycleDone = false
+			const cyclePromise = world.sync.runCycle().finally(() => {
+				cycleDone = true
+			})
+
+			try {
+				// While the other device holds the lock the engine keeps retrying acquisition and does NO sync
+				// work — nothing is uploaded, no state is touched.
+				await new Promise<void>(resolve => setTimeout(resolve, 5000))
+
+				expect(cycleDone, "cycle should still be blocked on the contended lock").toBe(false)
+				expect((await snapshotRemoteReal(world))["/a.txt"], "no work performed while contended").toBeUndefined()
+				// The engine signalled it is waiting for the lock (posted after 3s of waiting).
+				expect(messagesOfType(world.messages, "cycleAcquiringLockStarted").length).toBeGreaterThan(0)
+			} finally {
+				// Release so the engine's pending acquire succeeds on its next try, and drain the now-unblocked
+				// cycle before leaving (no orphaned async work during teardown) regardless of how we exit.
+				await sdk.user().releaseResourceLock({ resource, lockUUID: otherDevice }).catch(() => {})
+				await cyclePromise.catch(() => {})
+			}
+
+			// Once released the cycle proceeds; the world converges with the file uploaded — no corruption.
+			await settle(world)
+			await expectConverged(world)
+
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("a file deleted on one side and re-created on the other converges with no task errors (AA8)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "v1")
+			await settle(world)
+			await expectConverged(world)
+
+			// The remote trashes a.txt while local re-creates it with new content before the next cycle. The
+			// engine resolves the delete-vs-recreate without erroring and settles on the surviving content.
+			await deleteRemote(world, "a.txt")
+			await writeLocal(world, "a.txt", "v2-local-recreated-longer")
+
+			await settle(world)
+			await expectConverged(world)
+
+			const anyTaskErrored = messagesOfType(world.messages, "taskErrors").some(message => message.data.errors.length > 0)
+
+			expect(anyTaskErrored, "no task should surface an error across the reconciliation").toBe(false)
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+})