@filen/sync 0.2.1 → 0.3.2

package/tests/fakes/virtual-fs.ts

@@ -0,0 +1,354 @@
+import { Volume, createFsFromVolume, type IFs } from "memfs"
+import pathModule from "path"
+import { type SyncFS, type SyncGlobFS } from "../../src/lib/environment"
+
+/**
+ * Declarative description of an initial in-memory tree.
+ *
+ * Key   = absolute path (e.g. "/local/a.txt").
+ * Value = `string`        → a file with that UTF-8 content,
+ *         `VfsFileSpec`   → a file with content and/or an explicit mtime,
+ *         `null`          → an (empty) directory.
+ *
+ * Intermediate directories are created automatically.
+ */
+export type VfsFileSpec = { content?: string; mtimeMs?: number }
+export type VfsSpec = Record<string, string | VfsFileSpec | null>
+
+export type VirtualFS = {
+	/** The {@link SyncFS} surface to inject into the engine's environment. */
+	fs: SyncFS
+	/** The fast-glob filesystem adapter to inject as `globFs`. */
+	globFs: SyncGlobFS
+	/** The underlying memfs volume (for advanced manipulation in tests). */
+	vol: InstanceType<typeof Volume>
+	/** The memfs fs implementation backing both {@link fs} and {@link globFs}. */
+	ifs: IFs
+	controls: {
+		/** Current inode of a path, or null if it does not exist. */
+		getInode(path: string): number | null
+		/**
+		 * Force `stat`/`lstat` of `path` to report inode `ino`, simulating an OS (ext4) that recycles a
+		 * freed inode number for the next-created file. memfs has no native reuse, so this is the only way
+		 * to reproduce the inode-reuse rename misdetection deterministically. Use the real posix path the
+		 * engine will stat (e.g. "/local/c.txt").
+		 */
+		setInode(path: string, ino: number): void
+		/** Remove a previously forced inode for `path`. */
+		clearInode(path: string): void
+		/** Whether a path currently exists (no symlink following beyond stat). */
+		exists(path: string): boolean
+		/** Force the next fs operation that touches `path` to throw `error`. */
+		setError(path: string, error: NodeJS.ErrnoException): void
+		/** Remove a previously injected error for `path`. */
+		clearError(path: string): void
+		/** Remove all injected errors. */
+		clearAllErrors(): void
+		/**
+		 * Register a callback invoked synchronously AFTER every `lstat`/`stat` returns, with the posix path
+		 * just stat'd. Lets a test edit a file mid-scan (after the engine has already read it) to reproduce a
+		 * read-during-scan race deterministically. The callback should gate itself (path match + a one-shot
+		 * flag) and is cleared with {@link clearStatHook}. Only one hook is active at a time.
+		 */
+		onStat(hook: (posixPath: string) => void): void
+		/** Remove the {@link onStat} hook. */
+		clearStatHook(): void
+		/** Flat JSON view of the volume (file path → content, dir → null). */
+		toJSON(): Record<string, string | null>
+	}
+}
+
+/**
+ * Build a Node `ErrnoException` with a `code` (e.g. "ENOENT", "EACCES").
+ */
+export function makeErrnoError(code: string, message?: string): NodeJS.ErrnoException {
+	const error = new Error(message ?? code) as NodeJS.ErrnoException
+
+	error.code = code
+
+	return error
+}
+
+/**
+ * Normalize a path the ENGINE produced into the posix form memfs understands.
+ *
+ * memfs is strictly posix (it rejects backslashes), and the virtual tree is seeded with `/`-paths. But
+ * the engine joins local paths with the host's real `path` module, so on a Windows runner it emits
+ * backslash separators — and FastGlob/@nodelib may resolve the posix `cwd` to a drive-rooted absolute
+ * like `C:\local\...`. Stripping a leading drive letter and converting `\`→`/` lets the in-memory fs
+ * accept whatever the host's path module emits, so the identical suite runs on win32/darwin/linux.
+ *
+ * On posix hosts this is a no-op (no drive letter, no backslashes). Only paths the engine passes in are
+ * normalized here; test-side `ifs`/`vol` access stays posix (tests always use `/`).
+ */
+export function toPosixPath<T>(path: T): T {
+	return (typeof path === "string" ? path.replace(/^[a-zA-Z]:(?=[\\/])/, "").replace(/\\/g, "/") : path) as T
+}
+
+/**
+ * Materialize a {@link VfsSpec} into a memfs filesystem.
+ */
+export function applyVfsSpec(ifs: IFs, spec: VfsSpec): void {
+	for (const [path, value] of Object.entries(spec)) {
+		if (value === null) {
+			ifs.mkdirSync(path, { recursive: true })
+
+			continue
+		}
+
+		const content = typeof value === "string" ? value : value.content ?? ""
+
+		ifs.mkdirSync(pathModule.posix.dirname(path), { recursive: true })
+		ifs.writeFileSync(path, content)
+
+		const mtimeMs = typeof value === "string" ? undefined : value.mtimeMs
+
+		if (typeof mtimeMs === "number") {
+			const seconds = mtimeMs / 1000
+
+			ifs.utimesSync(path, seconds, seconds)
+		}
+	}
+}
+
+/**
+ * Create an in-memory filesystem that satisfies the engine's {@link SyncFS} and
+ * {@link SyncGlobFS} contracts. Backed by memfs (battle-tested), with the
+ * fs-extra conveniences the engine relies on (`ensureDir`, `exists`,
+ * `pathExists`, `move`) layered on top, plus a per-path error-injection map for
+ * resilience tests.
+ */
+export function createVirtualFS(initial: VfsSpec = {}): VirtualFS {
+	const vol = new Volume()
+	const ifs = createFsFromVolume(vol)
+
+	applyVfsSpec(ifs, initial)
+
+	const errors = new Map<string, NodeJS.ErrnoException>()
+	// Forced inode numbers (posix path -> ino) so a test can reproduce ext4-style inode reuse, which
+	// memfs's allocator does not surface naturally.
+	const inodeOverrides = new Map<string, number>()
+	// Optional one-shot-friendly hook fired after each lstat/stat returns, so a test can mutate a file
+	// mid-scan (after the engine read it) to reproduce a read-during-scan race deterministically.
+	let statHook: ((posixPath: string) => void) | null = null
+	// `guard` is always called with an already-posix-normalized path (each method normalizes its inputs
+	// at entry), so the error map — keyed by the posix paths tests inject — matches on every host.
+	const guard = (path: string): void => {
+		const error = errors.get(path)
+
+		if (error) {
+			throw error
+		}
+	}
+
+	const promises = ifs.promises
+
+	const fs = {
+		constants: ifs.constants,
+		stat: async (path: string) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			const stats = await promises.stat(path)
+			const overriddenInode = inodeOverrides.get(path)
+
+			if (overriddenInode !== undefined) {
+				stats.ino = overriddenInode
+			}
+
+			if (statHook) {
+				statHook(path)
+			}
+
+			return stats
+		},
+		lstat: async (path: string) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			const stats = await promises.lstat(path)
+			const overriddenInode = inodeOverrides.get(path)
+
+			if (overriddenInode !== undefined) {
+				stats.ino = overriddenInode
+			}
+
+			if (statHook) {
+				statHook(path)
+			}
+
+			return stats
+		},
+		access: async (path: string, mode?: number) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			return await promises.access(path, mode)
+		},
+		exists: async (path: string): Promise<boolean> => {
+			try {
+				path = toPosixPath(path)
+				guard(path)
+
+				await promises.access(path)
+
+				return true
+			} catch {
+				return false
+			}
+		},
+		pathExists: async (path: string): Promise<boolean> => {
+			try {
+				path = toPosixPath(path)
+				guard(path)
+
+				await promises.access(path)
+
+				return true
+			} catch {
+				return false
+			}
+		},
+		ensureDir: async (path: string): Promise<void> => {
+			path = toPosixPath(path)
+			guard(path)
+
+			await promises.mkdir(path, { recursive: true })
+		},
+		mkdir: async (path: string, options?: { recursive?: boolean }) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			return await promises.mkdir(path, options)
+		},
+		rm: async (
+			path: string,
+			options?: { force?: boolean; maxRetries?: number; recursive?: boolean; retryDelay?: number }
+		): Promise<void> => {
+			path = toPosixPath(path)
+			guard(path)
+
+			await promises.rm(path, options)
+		},
+		rename: async (src: string, dest: string): Promise<void> => {
+			src = toPosixPath(src)
+			dest = toPosixPath(dest)
+			guard(src)
+
+			await promises.rename(src, dest)
+		},
+		move: async (src: string, dest: string, options?: { overwrite?: boolean }): Promise<void> => {
+			src = toPosixPath(src)
+			dest = toPosixPath(dest)
+			guard(src)
+
+			await promises.mkdir(pathModule.posix.dirname(dest), { recursive: true })
+
+			if (options?.overwrite) {
+				try {
+					await promises.rm(dest, { recursive: true, force: true })
+				} catch {
+					// destination did not exist — nothing to overwrite
+				}
+			}
+
+			await promises.rename(src, dest)
+		},
+		utimes: async (path: string, atime: number | Date, mtime: number | Date): Promise<void> => {
+			path = toPosixPath(path)
+			guard(path)
+
+			await promises.utimes(path, atime, mtime)
+		},
+		readFile: async (path: string, options?: { encoding?: BufferEncoding }) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			return await promises.readFile(path, options)
+		},
+		writeFile: async (path: string, data: string | Uint8Array, options?: { encoding?: BufferEncoding }): Promise<void> => {
+			path = toPosixPath(path)
+			guard(path)
+
+			await promises.writeFile(path, data, options)
+		},
+		createReadStream: (path: string, options?: Parameters<IFs["createReadStream"]>[1]) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			return ifs.createReadStream(path, options)
+		},
+		createWriteStream: (path: string, options?: Parameters<IFs["createWriteStream"]>[1]) => {
+			path = toPosixPath(path)
+			guard(path)
+
+			return ifs.createWriteStream(path, options)
+		}
+	}
+
+	// FastGlob walks the tree through this adapter (lstat/stat/readdir + sync variants). On a Windows
+	// runner @nodelib builds child paths with the host separator and may resolve the posix `cwd` to a
+	// drive-rooted absolute, so every path it hands us is posix-normalized before reaching memfs. The
+	// returned glob entries are already forward-slash (fast-glob normalizes its output on all platforms).
+	const globFs = {
+		lstat: (path: string, ...rest: unknown[]) => (ifs.lstat as (...args: unknown[]) => unknown)(toPosixPath(path), ...rest),
+		lstatSync: (path: string, ...rest: unknown[]) => (ifs.lstatSync as (...args: unknown[]) => unknown)(toPosixPath(path), ...rest),
+		stat: (path: string, ...rest: unknown[]) => (ifs.stat as (...args: unknown[]) => unknown)(toPosixPath(path), ...rest),
+		statSync: (path: string, ...rest: unknown[]) => (ifs.statSync as (...args: unknown[]) => unknown)(toPosixPath(path), ...rest),
+		readdir: (path: string, ...rest: unknown[]) => (ifs.readdir as (...args: unknown[]) => unknown)(toPosixPath(path), ...rest),
+		readdirSync: (path: string, ...rest: unknown[]) => (ifs.readdirSync as (...args: unknown[]) => unknown)(toPosixPath(path), ...rest)
+	}
+
+	const controls: VirtualFS["controls"] = {
+		// Every path-keyed control normalizes with toPosixPath, exactly as the fs methods do before they
+		// consult these maps. Tests pass either posix literals (a no-op here) or engine-computed paths,
+		// which on Windows carry host backslash separators — without this an injected key would never
+		// match the posix path the engine actually stats/opens.
+		getInode: (path: string): number | null => {
+			try {
+				return Number(vol.statSync(toPosixPath(path)).ino)
+			} catch {
+				return null
+			}
+		},
+		exists: (path: string): boolean => {
+			try {
+				vol.statSync(toPosixPath(path))
+
+				return true
+			} catch {
+				return false
+			}
+		},
+		setInode: (path: string, ino: number): void => {
+			inodeOverrides.set(toPosixPath(path), ino)
+		},
+		clearInode: (path: string): void => {
+			inodeOverrides.delete(toPosixPath(path))
+		},
+		setError: (path: string, error: NodeJS.ErrnoException): void => {
+			errors.set(toPosixPath(path), error)
+		},
+		clearError: (path: string): void => {
+			errors.delete(toPosixPath(path))
+		},
+		clearAllErrors: (): void => {
+			errors.clear()
+		},
+		onStat: (hook: (posixPath: string) => void): void => {
+			statHook = hook
+		},
+		clearStatHook: (): void => {
+			statHook = null
+		},
+		toJSON: (): Record<string, string | null> => vol.toJSON()
+	}
+
+	return {
+		fs: fs as unknown as SyncFS,
+		globFs: globFs as unknown as SyncGlobFS,
+		vol,
+		ifs,
+		controls
+	}
+}

package/tests/harness/known-bug.ts

@@ -0,0 +1,17 @@
+import { it } from "vitest"
+
+/**
+ * A scenario that encodes the CORRECT behavior the engine currently violates (catalogued in
+ * docs/sync-bug-catalog.md). Implemented with `it.fails` so the suite stays green while the bug
+ * exists: the body asserts correct behavior, the engine produces wrong behavior, the assertion
+ * throws, and `it.fails` treats that throw as a pass.
+ *
+ * When the corresponding Phase 2 fix lands, the assertion starts passing, `it.fails` then FAILS
+ * (the body no longer throws) — that is the signal to convert `knownBug(...)` to a plain `it(...)`.
+ *
+ * Keep the body focused so it fails for the RIGHT reason (the catalogued defect), not an unrelated
+ * harness error.
+ */
+export function knownBug(bugId: string, name: string, fn: () => Promise<void>): void {
+	it.fails(`[KB ${bugId}] ${name}`, fn)
+}

package/tests/harness/mutations.ts

@@ -0,0 +1,65 @@
+import pathModule from "path"
+import { type World } from "./world"
+
+/**
+ * Local filesystem mutations applied to a {@link World} between cycles. All paths are relative to the
+ * local sync root (e.g. "a.txt", "dir/b.txt"). Parent directories are created as needed. After a
+ * local mutation the runner fires the watcher so the next cycle rescans.
+ */
+
+function localFull(world: World, relativePath: string): string {
+	return pathModule.posix.join(world.localPath, relativePath.replace(/^\/+/, ""))
+}
+
+export function writeLocal(world: World, relativePath: string, content: string): void {
+	const full = localFull(world, relativePath)
+
+	world.vfs.ifs.mkdirSync(pathModule.posix.dirname(full), { recursive: true })
+	world.vfs.ifs.writeFileSync(full, content)
+}
+
+/** Write a local file and force a specific mtime (whole-second precision drives conflict resolution). */
+export function writeLocalAt(world: World, relativePath: string, content: string, mtimeMs: number): void {
+	writeLocal(world, relativePath, content)
+
+	const seconds = mtimeMs / 1000
+
+	world.vfs.ifs.utimesSync(localFull(world, relativePath), seconds, seconds)
+}
+
+/** Update a local file's mtime WITHOUT changing its content or inode (a pure touch). */
+export function touchLocal(world: World, relativePath: string, mtimeMs: number): void {
+	const seconds = mtimeMs / 1000
+
+	world.vfs.ifs.utimesSync(localFull(world, relativePath), seconds, seconds)
+}
+
+export function mkdirLocal(world: World, relativePath: string): void {
+	world.vfs.ifs.mkdirSync(localFull(world, relativePath), { recursive: true })
+}
+
+export function rmLocal(world: World, relativePath: string): void {
+	world.vfs.ifs.rmSync(localFull(world, relativePath), { recursive: true, force: true })
+}
+
+export function renameLocal(world: World, fromRelativePath: string, toRelativePath: string): void {
+	const from = localFull(world, fromRelativePath)
+	const to = localFull(world, toRelativePath)
+
+	world.vfs.ifs.mkdirSync(pathModule.posix.dirname(to), { recursive: true })
+	world.vfs.ifs.renameSync(from, to)
+}
+
+export function readLocal(world: World, relativePath: string): string {
+	return world.vfs.ifs.readFileSync(localFull(world, relativePath), "utf-8") as string
+}
+
+export function existsLocal(world: World, relativePath: string): boolean {
+	try {
+		world.vfs.ifs.statSync(localFull(world, relativePath))
+
+		return true
+	} catch {
+		return false
+	}
+}

package/tests/harness/runner.ts

@@ -0,0 +1,141 @@
+import { vi, expect } from "vitest"
+import { SYNC_INTERVAL } from "../../src/constants"
+import { createWorld, restartSync, BASE_TIME, type CreateWorldOptions, type World } from "./world"
+import { snapshotLocal, snapshotRemote, type WorldSnapshot } from "./snapshot"
+import { type SyncMessage } from "../../src/types"
+
+/**
+ * One step in a scenario. `runCycle` drives exactly one synchronization cycle; the mutate/control
+ * steps apply changes between cycles. `localMutate` automatically fires the watcher afterwards so the
+ * next cycle rescans the local tree.
+ */
+export type Step =
+	| { type: "runCycle" }
+	| { type: "restart" }
+	| { type: "localMutate"; mutate: (world: World) => unknown }
+	| { type: "remoteMutate"; mutate: (world: World) => unknown }
+	| { type: "control"; control: (world: World) => unknown }
+
+export function runCycle(): Step {
+	return { type: "runCycle" }
+}
+
+/** Simulate a process restart: reload persisted state and rebuild the engine over the same world. */
+export function restart(): Step {
+	return { type: "restart" }
+}
+
+export function localMutate(mutate: (world: World) => unknown): Step {
+	return { type: "localMutate", mutate }
+}
+
+export function remoteMutate(mutate: (world: World) => unknown): Step {
+	return { type: "remoteMutate", mutate }
+}
+
+export function control(controlFn: (world: World) => unknown): Step {
+	return { type: "control", control: controlFn }
+}
+
+export type Scenario = CreateWorldOptions & {
+	name: string
+	steps: Step[]
+}
+
+export type RunResult = {
+	world: World
+	finalLocal: WorldSnapshot
+	finalRemote: WorldSnapshot
+	messages: SyncMessage[]
+	/** Per-`runCycle` snapshots and the messages emitted during that cycle. */
+	cycles: { local: WorldSnapshot; remote: WorldSnapshot; messages: SyncMessage[] }[]
+}
+
+async function applyStep(world: World, step: Step): Promise<void> {
+	switch (step.type) {
+		case "runCycle": {
+			// Advance past the local-change debounce window so waitForLocalDirectoryChanges returns
+			// immediately (its first synchronous check passes); during the cycle the clock is frozen,
+			// so the engine's internal progress timeouts and the lock-refresh interval never fire.
+			await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+			await world.sync.runCycle()
+
+			break
+		}
+
+		case "restart": {
+			await restartSync(world)
+
+			break
+		}
+
+		case "localMutate": {
+			await step.mutate(world)
+
+			world.triggerWatcher()
+
+			break
+		}
+
+		case "remoteMutate": {
+			await step.mutate(world)
+
+			break
+		}
+
+		case "control": {
+			await step.control(world)
+
+			break
+		}
+	}
+}
+
+/**
+ * Build an in-memory world from the scenario spec, run its steps under fake timers, and return the
+ * final local/remote snapshots, the full message stream, and per-cycle snapshots.
+ */
+export async function runScenario(scenario: Scenario): Promise<RunResult> {
+	// Fake only the timers the engine schedules on (debounce, lock refresh, cleanup, retries) and the
+	// clock. Leave setImmediate/microtasks real so async I/O (fast-glob traversal, streams) resolves
+	// while the fake clock is frozen mid-cycle.
+	vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] })
+	vi.setSystemTime(BASE_TIME)
+
+	try {
+		const world = await createWorld(scenario)
+		const cycles: { local: WorldSnapshot; remote: WorldSnapshot; messages: SyncMessage[] }[] = []
+
+		for (const step of scenario.steps) {
+			const messagesBefore = world.messages.length
+
+			await applyStep(world, step)
+
+			if (step.type === "runCycle") {
+				cycles.push({
+					local: snapshotLocal(world),
+					remote: snapshotRemote(world),
+					messages: world.messages.slice(messagesBefore)
+				})
+			}
+		}
+
+		return {
+			world,
+			finalLocal: snapshotLocal(world),
+			finalRemote: snapshotRemote(world),
+			messages: world.messages,
+			cycles
+		}
+	} finally {
+		vi.useRealTimers()
+	}
+}
+
+/**
+ * Assert the two normalized worlds are identical (used for twoWay equivalence: §2.3).
+ */
+export function expectWorldsEqual(a: WorldSnapshot, b: WorldSnapshot): void {
+	expect(a).toEqual(b)
+}

package/tests/harness/snapshot.ts

@@ -0,0 +1,113 @@
+import pathModule from "path"
+import crypto from "crypto"
+import { LOCAL_TRASH_NAME } from "../../src/constants"
+import { type SyncMessage } from "../../src/types"
+import { type World } from "./world"
+
+export type SnapshotEntry = { type: "file" | "directory"; size: number; mtimeSec: number; contentHash: string }
+
+/**
+ * The normalized assertion unit: `path → { type, size, mtime(sec), contentHash }`, excluding the
+ * local trash directory. Local and remote snapshots are directly comparable — same content yields
+ * the same sha512 hash and the same whole-second mtime on both sides.
+ */
+export type WorldSnapshot = Record<string, SnapshotEntry>
+
+function sha512Hex(data: Buffer): string {
+	return crypto.createHash("sha512").update(Uint8Array.from(data)).digest("hex")
+}
+
+/**
+ * Normalized snapshot of the local sync directory (relative POSIX paths), excluding the local trash.
+ */
+export function snapshotLocal(world: World): WorldSnapshot {
+	const result: WorldSnapshot = {}
+	const ifs = world.vfs.ifs
+	const root = world.localPath
+
+	const walk = (directory: string): void => {
+		let entries: string[]
+
+		try {
+			entries = ifs.readdirSync(directory) as string[]
+		} catch {
+			return
+		}
+
+		for (const entry of entries) {
+			if (entry === LOCAL_TRASH_NAME) {
+				continue
+			}
+
+			const full = pathModule.posix.join(directory, entry)
+			const relativePath = full.slice(root.length)
+			const stats = ifs.statSync(full)
+
+			if (stats.isDirectory()) {
+				result[relativePath] = { type: "directory", size: 0, mtimeSec: 0, contentHash: "" }
+
+				walk(full)
+			} else if (stats.isFile()) {
+				const content = ifs.readFileSync(full) as Buffer
+
+				result[relativePath] = {
+					type: "file",
+					size: stats.size,
+					mtimeSec: Math.floor(stats.mtimeMs / 1000),
+					contentHash: sha512Hex(content)
+				}
+			}
+		}
+	}
+
+	walk(root)
+
+	return result
+}
+
+/**
+ * Normalized snapshot of the live remote tree (relative POSIX paths).
+ */
+export function snapshotRemote(world: World): WorldSnapshot {
+	return world.cloud.controls.snapshot()
+}
+
+/** All messages of a given `type`. */
+export function messagesOfType<T extends SyncMessage["type"]>(messages: SyncMessage[], type: T): Extract<SyncMessage, { type: T }>[] {
+	return messages.filter((message): message is Extract<SyncMessage, { type: T }> => message.type === type)
+}
+
+/** Count messages of a given `type`. */
+export function countMessages(messages: SyncMessage[], type: SyncMessage["type"]): number {
+	return messages.filter(message => message.type === type).length
+}
+
+/** The `of` discriminators of every "transfer" message (e.g. "upload", "downloadFile", ...). */
+export function transferKinds(messages: SyncMessage[]): string[] {
+	return messagesOfType(messages, "transfer").map(message => message.data.of)
+}
+
+/** The transfer `of` discriminators that represent an actual file transfer (not a dir/rename op). */
+export const FILE_TRANSFER_OPS = ["upload", "uploadFile", "download", "downloadFile"] as const
+
+/** The actual file-transfer operations seen in a message stream (upload/download, queued..finished). */
+export function transferOps(messages: SyncMessage[]): string[] {
+	return transferKinds(messages).filter(kind => (FILE_TRANSFER_OPS as readonly string[]).includes(kind))
+}
+
+/**
+ * Every operation kind in the stream — file transfers AND directory creates, deletes, and renames (the
+ * full set of `transfer.of` discriminators), deduplicated and sorted for readable failure output.
+ *
+ * `expect(allOps(messages)).toEqual([])` is the assertion for a COMPLETE no-op. transferOps() sees only
+ * file up/downloads, so a cycle that spuriously renamed, deleted, or mkdir'd a path slips past it; allOps
+ * catches it. Mirror of the e2e harness helper of the same name.
+ */
+export function allOps(messages: SyncMessage[]): string[] {
+	return [...new Set(transferKinds(messages))].sort()
+}
+
+/** Whether any actual file transfer (upload/download) occurred in the message stream. */
+export function hadTransfers(messages: SyncMessage[]): boolean {
+	return transferOps(messages).length > 0
+}