@filen/sync 0.2.1 → 0.3.2

package/tests/scenarios/ab-mode-property.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, localMutate, remoteMutate, type Step } from "../harness/runner"
+import { BASE_TIME } from "../harness/world"
+import { allOps } from "../harness/snapshot"
+import { writeLocalAt, rmLocal } from "../harness/mutations"
+
+/**
+ * Category AB — randomized property tests for the directional MIRROR modes (localToCloud / cloudToLocal),
+ * the directional analogue of Category L (twoWay). The defining invariant of a mirror is stronger than
+ * twoWay convergence: the AUTHORITATIVE side dictates the whole tree, so no matter what foreign NOISE the
+ * other side injects (adds, edits, deletes), the engine must drive the two worlds back to the
+ * authoritative side's exact state and stay there (idempotence). This exercises mirror-delete + F5
+ * (authoritative wins) + F6 (foreign-edit revert) together under thousands of random operations.
+ *
+ * Histories are well-behaved on the authoritative side (strictly-increasing whole-second mtimes, one op
+ * per path per round, non-empty content, case-distinct names) so a failure is a real bug. The foreign
+ * noise is deliberately adversarial.
+ */
+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 = ["f0.txt", "f1.txt", "f2.txt", "f3.txt", "f4.txt"]
+const ROUNDS = 8
+const MAX_OPS_PER_ROUND = 3
+const SETTLE_CYCLES = 4
+
+/**
+ * Build a directional-mirror history. `side` is the authoritative side: its mutations are the source of
+ * truth, and we additionally inject foreign noise on the OTHER side that the mirror must undo. Returns
+ * the step list. After settling, the two worlds must be identical.
+ */
+function buildMirrorHistory(seed: number, authoritative: "local" | "remote"): Step[] {
+	const random = mulberry32(seed)
+	const pick = <T>(items: readonly T[]): T => items[Math.floor(random() * items.length)]!
+	const steps: Step[] = []
+	const exists = new Set<string>()
+	let clock = BASE_TIME + 1000
+
+	const authWrite = (path: string, content: string, mtime: number): void => {
+		if (authoritative === "local") {
+			steps.push(localMutate(world => writeLocalAt(world, path, content, mtime)))
+		} else {
+			steps.push(remoteMutate(world => world.cloud.controls.addFile(`/${path}`, content, { mtimeMs: mtime })))
+		}
+	}
+	const authUpdate = (path: string, content: string, mtime: number): void => {
+		if (authoritative === "local") {
+			steps.push(localMutate(world => writeLocalAt(world, path, content, mtime)))
+		} else {
+			steps.push(remoteMutate(world => world.cloud.controls.updateFile(`/${path}`, content, { mtimeMs: mtime })))
+		}
+	}
+	const authDelete = (path: string): void => {
+		if (authoritative === "local") {
+			steps.push(localMutate(world => rmLocal(world, path)))
+		} else {
+			steps.push(remoteMutate(world => world.cloud.controls.trashPath(`/${path}`)))
+		}
+	}
+	// Foreign noise lands on the NON-authoritative side; the mirror must erase its effect. `noiseClock` is
+	// captured by VALUE per call — the closures must NOT close over the mutable `clock` (it advances during
+	// generation, so a by-reference capture would stamp every foreign edit with the final, largest mtime and
+	// collapse them all into one whole-second, the §C11 ambiguity this suite deliberately avoids).
+	const foreignNoise = (round: number, noiseClock: number): void => {
+		const r = random()
+
+		if (authoritative === "local") {
+			if (r < 0.4) {
+				steps.push(remoteMutate(world => world.cloud.controls.addFile(`/foreign-${round}.txt`, `foreign${round}`, { mtimeMs: noiseClock })))
+			} else if (r < 0.7 && exists.size > 0) {
+				const target = pick([...exists])
+
+				steps.push(remoteMutate(world => world.cloud.controls.updateFile(`/${target}`, `tampered${round}`, { mtimeMs: noiseClock })))
+			} else if (exists.size > 0) {
+				const target = pick([...exists])
+
+				steps.push(remoteMutate(world => world.cloud.controls.trashPath(`/${target}`)))
+			}
+		} else {
+			if (r < 0.4) {
+				steps.push(localMutate(world => writeLocalAt(world, `foreign-${round}.txt`, `foreign${round}`, noiseClock)))
+			} else if (r < 0.7 && exists.size > 0) {
+				const target = pick([...exists])
+
+				steps.push(localMutate(world => writeLocalAt(world, target, `tampered${round}`, noiseClock)))
+			} else if (exists.size > 0) {
+				const target = pick([...exists])
+
+				steps.push(localMutate(world => rmLocal(world, target)))
+			}
+		}
+	}
+
+	// Seed one authoritative file.
+	clock += 1000
+	authWrite("f0.txt", "seed-0", clock)
+	exists.add("f0.txt")
+	steps.push(runCycle())
+
+	for (let round = 0; round < ROUNDS; round++) {
+		const touched = new Set<string>()
+		const ops = 1 + Math.floor(random() * MAX_OPS_PER_ROUND)
+
+		for (let op = 0; op < ops; op++) {
+			const path = pick(FILE_POOL)
+
+			if (touched.has(path)) {
+				continue
+			}
+
+			touched.add(path)
+			clock += 1000
+
+			const content = `s${seed}-r${round}-o${op}-${Math.floor(random() * 1_000_000)}`
+			const doDelete = exists.has(path) && random() < 0.3
+
+			if (doDelete) {
+				exists.delete(path)
+				authDelete(path)
+			} else if (exists.has(path)) {
+				authUpdate(path, content, clock)
+			} else {
+				exists.add(path)
+				authWrite(path, content, clock)
+			}
+		}
+
+		// Inject adversarial foreign noise most rounds.
+		if (random() < 0.7) {
+			clock += 1000
+			foreignNoise(round, clock)
+		}
+
+		steps.push(runCycle())
+	}
+
+	for (let cycle = 0; cycle < SETTLE_CYCLES; cycle++) {
+		steps.push(runCycle())
+	}
+
+	return steps
+}
+
+describe("Category AB — directional mirror property tests", () => {
+	const ITERATIONS = 16
+
+	for (let iteration = 0; iteration < ITERATIONS; iteration++) {
+		const seed = 0x5151 + iteration * 0x9e37
+
+		it(`AB-localToCloud seed=${seed}: the remote is driven to exactly mirror the authoritative local tree`, async () => {
+			const steps = buildMirrorHistory(seed, "local")
+			const result = await runScenario({ name: `AB-ltc-${seed}`, mode: "localToCloud", steps })
+
+			// Mirror: the remote equals the authoritative local tree, every foreign edit undone.
+			expect(result.finalRemote, `seed=${seed} remote did not mirror local`).toEqual(result.finalLocal)
+
+			// Idempotence: the final settled cycle did no transfers.
+			const lastCycle = result.cycles[result.cycles.length - 1]!
+
+			expect(allOps(lastCycle.messages), `seed=${seed} not idempotent`).toEqual([])
+		})
+	}
+
+	for (let iteration = 0; iteration < ITERATIONS; iteration++) {
+		const seed = 0x7333 + iteration * 0x9e37
+
+		it(`AB-cloudToLocal seed=${seed}: local is driven to exactly mirror the authoritative remote tree`, async () => {
+			const steps = buildMirrorHistory(seed, "remote")
+			const result = await runScenario({ name: `AB-ctl-${seed}`, mode: "cloudToLocal", steps })
+
+			expect(result.finalLocal, `seed=${seed} local did not mirror remote`).toEqual(result.finalRemote)
+
+			const lastCycle = result.cycles[result.cycles.length - 1]!
+
+			expect(allOps(lastCycle.messages), `seed=${seed} not idempotent`).toEqual([])
+		})
+	}
+})

package/tests/scenarios/ac-platform.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, restart } from "../harness/runner"
+import { messagesOfType, hadTransfers } from "../harness/snapshot"
+import { type SyncMessage } from "../../src/types"
+
+/**
+ * Category AC — cross-platform / per-OS path rules (behavioral spec §platform). A production sync
+ * engine runs on Windows, macOS and Linux against ONE shared backend, so a name that is perfectly
+ * legal where it was created can be illegal on the machine syncing it down. The engine guards this in
+ * BOTH filesystem walks via `isValidPath` / `isPathOverMaxLength` / `isNameOverMaxLength` (utils.ts),
+ * each of which reads `process.platform` at call time. The rule:
+ *
+ *   - win32  → forbids `< > : " | ? *`, control chars, the reserved device names (CON/PRN/AUX/NUL/
+ *              COM1-9/LPT1-9, with or without an extension), and paths over 512 chars.
+ *   - darwin → forbids `:` and NUL; paths over 1024 chars.
+ *   - linux  → forbids only NUL; paths over 4096 chars.
+ *
+ * A path the local platform can't represent must be SKIPPED (reason `invalidPath` / `pathLength` /
+ * `nameLength`) — never downloaded, never crashing the cycle, and (crucially) never deleted from the
+ * side that legitimately holds it. The opposite OS, where the name is legal, must sync it normally.
+ *
+ * These tests force `process.platform` so every branch runs deterministically on ANY host — darwin
+ * locally, and all three runners in CI. The host's real platform is irrelevant to the assertions.
+ */
+
+/** Run an entire scenario with `process.platform` forced to `platform`, restoring it afterwards. */
+async function withPlatform<T>(platform: NodeJS.Platform, fn: () => Promise<T>): Promise<T> {
+	const original = Object.getOwnPropertyDescriptor(process, "platform")!
+
+	Object.defineProperty(process, "platform", { value: platform, configurable: true })
+
+	try {
+		return await fn()
+	} finally {
+		Object.defineProperty(process, "platform", original)
+	}
+}
+
+/** Every structural-ignore reason reported across the whole message stream (local + remote walks). */
+function ignoredReasons(messages: SyncMessage[]): string[] {
+	const local = messagesOfType(messages, "localTreeIgnored").flatMap(message => message.data.ignored.map(entry => entry.reason))
+	const remote = messagesOfType(messages, "remoteTreeIgnored").flatMap(message => message.data.ignored.map(entry => entry.reason))
+
+	return [...local, ...remote]
+}
+
+// A path long enough that its absolute local form (prefixed with "/local") exceeds Windows' 512-char
+// limit, but every individual NAME stays under the uniform 255-char name limit (so only `pathLength`,
+// not `nameLength`, is exercised). 6 + 1 + 200 + 1 + 200 + 1 + 154 = 563 chars absolute.
+const LONG_DIR = "d".repeat(200)
+const LONG_SUB = "s".repeat(200)
+const LONG_LEAF = `${"f".repeat(150)}.txt`
+const LONG_PATH = `/${LONG_DIR}/${LONG_SUB}/${LONG_LEAF}`
+
+describe("Category AC — cross-platform path rules", () => {
+	it("AC1: win32 skips a remote file with a colon (invalidPath), syncs valid siblings, never deletes it", async () => {
+		const result = await withPlatform("win32", () =>
+			runScenario({
+				name: "AC1",
+				mode: "twoWay",
+				initialRemote: {
+					"/report:v2.txt": "colon is illegal on windows",
+					"/ok.txt": "fine everywhere"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		// The colon file is skipped on the way down…
+		expect(result.finalLocal["/report:v2.txt"]).toBeUndefined()
+		expect(ignoredReasons(result.messages)).toContain("invalidPath")
+		// …the valid sibling converges on both sides…
+		expect(result.finalLocal["/ok.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/ok.txt"]).toMatchObject({ type: "file" })
+		// …and the skipped remote file is NOT deleted (ignore ≠ delete; it just can't land on win32).
+		expect(result.finalRemote["/report:v2.txt"]).toMatchObject({ type: "file" })
+	})
+
+	it("AC2: linux DOES sync the colon file down — a colon is a legal filename on linux", async () => {
+		const result = await withPlatform("linux", () =>
+			runScenario({
+				name: "AC2",
+				mode: "twoWay",
+				initialRemote: {
+					"/report:v2.txt": "legal on linux",
+					"/ok.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal["/report:v2.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/ok.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).not.toContain("invalidPath")
+	})
+
+	it("AC3: darwin also skips the colon file — `:` is illegal on macOS too (unlike linux)", async () => {
+		const result = await withPlatform("darwin", () =>
+			runScenario({
+				name: "AC3",
+				mode: "twoWay",
+				initialRemote: {
+					"/a:b.txt": "illegal on macOS",
+					"/ok.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal["/a:b.txt"]).toBeUndefined()
+		expect(result.finalLocal["/ok.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/a:b.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).toContain("invalidPath")
+	})
+
+	it("AC4: win32 skips remote files using reserved device names (CON, com1.txt, nul); a normal file syncs", async () => {
+		const result = await withPlatform("win32", () =>
+			runScenario({
+				name: "AC4",
+				mode: "cloudToLocal",
+				initialRemote: {
+					"/CON": "reserved",
+					"/com1.txt": "reserved even with an extension",
+					"/nul": "reserved",
+					"/normal.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal["/CON"]).toBeUndefined()
+		expect(result.finalLocal["/com1.txt"]).toBeUndefined()
+		expect(result.finalLocal["/nul"]).toBeUndefined()
+		expect(result.finalLocal["/normal.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).toContain("invalidPath")
+	})
+
+	it("AC5: linux treats reserved device names as ordinary filenames and syncs them", async () => {
+		const result = await withPlatform("linux", () =>
+			runScenario({
+				name: "AC5",
+				mode: "cloudToLocal",
+				initialRemote: {
+					"/CON": "just a name on linux",
+					"/com1.txt": "fine",
+					"/nul": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal["/CON"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/com1.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/nul"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).not.toContain("invalidPath")
+	})
+
+	it("AC6: win32 skips each illegal metacharacter (< > | ? * \") while a clean file syncs", async () => {
+		const illegal: Record<string, string> = {
+			"/lt<name.txt": "x",
+			"/gt>name.txt": "x",
+			"/pipe|name.txt": "x",
+			"/q?name.txt": "x",
+			"/star*name.txt": "x",
+			"/quote\"name.txt": "x"
+		}
+
+		const result = await withPlatform("win32", () =>
+			runScenario({
+				name: "AC6",
+				mode: "twoWay",
+				initialRemote: { ...illegal, "/clean.txt": "ok" },
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		for (const path of Object.keys(illegal)) {
+			// Skipped locally (can't be represented on win32)…
+			expect(result.finalLocal[path]).toBeUndefined()
+			// …but never deleted from the remote.
+			expect(result.finalRemote[path]).toMatchObject({ type: "file" })
+		}
+
+		expect(result.finalLocal["/clean.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).toContain("invalidPath")
+	})
+
+	it("AC7: win32 skips uploading a LOCAL file whose name is illegal on the platform (outbound guard)", async () => {
+		const result = await withPlatform("win32", () =>
+			runScenario({
+				name: "AC7",
+				mode: "twoWay",
+				initialLocal: {
+					"/local/bad:name.txt": "colon illegal on win32",
+					"/local/good.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		// The illegal-named local file is never uploaded…
+		expect(result.finalRemote["/bad:name.txt"]).toBeUndefined()
+		// …but it stays on local disk (ignore ≠ delete) and the valid file uploads.
+		expect(result.finalLocal["/bad:name.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/good.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).toContain("invalidPath")
+	})
+
+	it("AC8: win32 skips a remote path over its 512-char limit (pathLength); a short sibling syncs", async () => {
+		const result = await withPlatform("win32", () =>
+			runScenario({
+				name: "AC8",
+				mode: "cloudToLocal",
+				initialRemote: {
+					[LONG_PATH]: "too long for windows",
+					"/short.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal[LONG_PATH]).toBeUndefined()
+		expect(result.finalLocal["/short.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).toContain("pathLength")
+	})
+
+	it("AC9: linux syncs the same long path — its 4096-char limit permits it", async () => {
+		const result = await withPlatform("linux", () =>
+			runScenario({
+				name: "AC9",
+				mode: "cloudToLocal",
+				initialRemote: {
+					[LONG_PATH]: "fine on linux",
+					"/short.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal[LONG_PATH]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/short.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).not.toContain("pathLength")
+	})
+
+	it("AC10: win32 converges a mixed tree (valid synced, illegal skipped) and stays stable across a restart", async () => {
+		const result = await withPlatform("win32", () =>
+			runScenario({
+				name: "AC10",
+				mode: "twoWay",
+				initialRemote: {
+					"/docs/readme.txt": "valid",
+					"/docs/a:b.txt": "illegal colon",
+					"/CON": "reserved",
+					"/photos/pic.txt": "valid"
+				},
+				steps: [runCycle(), runCycle(), restart(), runCycle()]
+			})
+		)
+
+		// Valid files synced down…
+		expect(result.finalLocal["/docs/readme.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/photos/pic.txt"]).toMatchObject({ type: "file" })
+		// …illegal ones skipped locally but intact on the remote.
+		expect(result.finalLocal["/docs/a:b.txt"]).toBeUndefined()
+		expect(result.finalLocal["/CON"]).toBeUndefined()
+		expect(result.finalRemote["/docs/a:b.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/CON"]).toMatchObject({ type: "file" })
+
+		// The post-restart cycle does NO transfers — the skipped files never cause repeated churn, and
+		// the valid files are already reconciled, so a long-lived win32 sync stays quiet.
+		const lastCycle = result.cycles[result.cycles.length - 1]!
+
+		expect(hadTransfers(lastCycle.messages)).toBe(false)
+	})
+
+	// A name that fits in 255 UTF-16 code units but exceeds 255 UTF-8 BYTES — legal on macOS/Windows
+	// (which count code units) but over Linux's byte-based NAME_MAX. "あ" is 1 code unit / 3 bytes, so
+	// 100 of them is 100 units (under 255) yet 300 bytes (over 255).
+	const MULTIBYTE_NAME = "あ".repeat(100)
+	const MULTIBYTE_PATH = `/${MULTIBYTE_NAME}.txt`
+
+	it("AC11: linux skips a remote name that exceeds 255 BYTES (nameLength) instead of failing forever", async () => {
+		const result = await withPlatform("linux", () =>
+			runScenario({
+				name: "AC11",
+				mode: "cloudToLocal",
+				initialRemote: {
+					[MULTIBYTE_PATH]: "too many bytes for linux",
+					"/short.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		// The over-long name is skipped (not materialized locally), the valid sibling syncs, and the remote
+		// copy is untouched — a graceful skip, not a per-cycle ENAMETOOLONG retry loop.
+		expect(result.finalLocal[MULTIBYTE_PATH]).toBeUndefined()
+		expect(result.finalLocal["/short.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote[MULTIBYTE_PATH]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).toContain("nameLength")
+	})
+
+	it("AC12: darwin SYNCS the same name down — it is 100 UTF-16 units, under the 255-unit macOS limit", async () => {
+		const result = await withPlatform("darwin", () =>
+			runScenario({
+				name: "AC12",
+				mode: "cloudToLocal",
+				initialRemote: {
+					[MULTIBYTE_PATH]: "fine on macOS",
+					"/short.txt": "fine"
+				},
+				steps: [runCycle(), runCycle()]
+			})
+		)
+
+		expect(result.finalLocal[MULTIBYTE_PATH]).toMatchObject({ type: "file" })
+		expect(result.finalLocal["/short.txt"]).toMatchObject({ type: "file" })
+		expect(ignoredReasons(result.messages)).not.toContain("nameLength")
+	})
+})

package/tests/scenarios/ad-unicode-normalization.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle } from "../harness/runner"
+
+/**
+ * Category AD — Unicode normalization (KNOWN, DEFERRED LIMITATION).
+ *
+ * A filename like "cafe<accent>.txt" can be encoded two ways that look identical but are different bytes:
+ *   - NFC (precomposed):  the accented letter is one code point  (U+00E9)
+ *   - NFD (decomposed):   base letter + combining accent          (U+0065 U+0301)
+ *
+ * The engine compares names BYTEWISE and does NOT Unicode-normalize — and neither does @filen/sdk
+ * (verified: the SDK only uses path.normalize for `..`/separators, never String.normalize("NFC")). So
+ * the SAME visual filename in two normalization forms is treated as two distinct files, which on a
+ * mixed-normalization cross-sync ends as a permanent DUPLICATE on both sides.
+ *
+ * In practice NFD names come almost exclusively from old macOS HFS+ (which forced NFD on write); modern
+ * Windows/Linux/APFS-macOS produce NFC. For a modern user base this is rare, so the fix (NFC-normalize
+ * keys for comparison + migrate the persisted base trees so the first post-upgrade cycle stays a no-op)
+ * is DEFERRED by maintainer decision (2026-06-27). See docs/hardening-findings.md and the
+ * filen-sync-caveats memory.
+ *
+ * These tests PIN the current behavior (golden master): if normalization is ever added, AD1 flips and
+ * forces this note + the fix to be reconciled, rather than the change sliding in silently.
+ *
+ * NFC below is the precomposed byte sequence and NFD the decomposed one of the same visual name;
+ * verified distinct-but-NFC-equal in the first two assertions of AD1.
+ */
+const NFC: string = "café.txt" // precomposed: U+00E9
+const NFD: string = "café.txt" // decomposed: U+0065 U+0301
+
+describe("Category AD — Unicode normalization (known, deferred limitation)", () => {
+	it("AD1: KNOWN LIMITATION — NFC-remote vs NFD-local of the same visual name DUPLICATE (no normalization yet)", async () => {
+		// Sanity: different bytes, yet the SAME name once normalized — exactly the trap the engine misses.
+		expect(NFC).not.toBe(NFD)
+		expect(NFC.normalize("NFC")).toBe(NFD.normalize("NFC"))
+
+		const result = await runScenario({
+			name: "AD1",
+			mode: "twoWay",
+			initialLocal: { [`/local/${NFD}`]: "from-an-nfd-client" },
+			initialRemote: { [`/${NFC}`]: "from-an-nfc-client" },
+			steps: [runCycle(), runCycle(), runCycle()]
+		})
+
+		const localForms = [NFC, NFD].filter(name => result.finalLocal[`/${name}`] !== undefined)
+		const remoteForms = [NFC, NFD].filter(name => result.finalRemote[`/${name}`] !== undefined)
+
+		// DOCUMENTED current behavior: BOTH forms end up on BOTH sides — the duplication bug. When
+		// NFC-normalized comparison lands, each side collapses to a single form and these flip to 1.
+		expect(localForms.length).toBe(2)
+		expect(remoteForms.length).toBe(2)
+	})
+
+	it("AD2: a pure-ASCII name is unaffected (normalization would be a no-op here) — sanity", async () => {
+		const result = await runScenario({
+			name: "AD2",
+			mode: "twoWay",
+			initialLocal: { "/local/plain.txt": "ascii" },
+			initialRemote: { "/plain.txt": "ascii" },
+			steps: [runCycle(), runCycle()]
+		})
+
+		// No duplication for ASCII: exactly one converged copy on each side.
+		expect(Object.keys(result.finalLocal).filter(key => key.includes("plain")).length).toBe(1)
+		expect(Object.keys(result.finalRemote).filter(key => key.includes("plain")).length).toBe(1)
+	})
+})