@filen/sync 0.2.1 → 0.3.1

package/tests/e2e/harness/world.ts

@@ -0,0 +1,222 @@
+import type FilenSDK from "@filen/sdk"
+import Sync from "../../../src/lib/sync"
+import SyncWorker from "../../../src/index"
+import { type SyncPair, type SyncMessage, type SyncMode } from "../../../src/types"
+import { type SyncEnvironment, defaultEnvironment } from "../../../src/lib/environment"
+import os from "os"
+import pathModule from "path"
+import fs from "fs-extra"
+import { v4 as uuidv4 } from "uuid"
+
+export type E2EWorldOptions = {
+	sdk: FilenSDK
+	mode: SyncMode
+	/** Default true: local deletions are permanent (no `.filen.trash` subdir to reason about). */
+	localTrashDisabled?: boolean
+	excludeDotFiles?: boolean
+	requireConfirmationOnLargeDeletion?: boolean
+	/** `.filenignore` contents to seed at the local root before the first cycle. */
+	filenIgnore?: string
+	/**
+	 * Default false: use a no-op watcher and drive cycles manually (deterministic). Set true only for a
+	 * test that specifically exercises the production fs.watch watcher.
+	 */
+	useRealWatcher?: boolean
+}
+
+export type E2EWorld = {
+	sdk: FilenSDK
+	worker: SyncWorker
+	sync: Sync
+	syncPair: SyncPair
+	messages: SyncMessage[]
+	/** The unique id for this world; used for both the local tmp dir name and the remote dir name. */
+	runId: string
+	/** UUID of the remote `/<runId>` directory that is this sync's remote root. */
+	remoteParentUUID: string
+	/** Absolute path of the local sync root (a fresh tmp dir). */
+	localRoot: string
+	/** Absolute path of the per-world state/db dir (a fresh tmp dir). */
+	dbPath: string
+	/** Absolute path of the tmp dir tree that holds localRoot + dbPath (removed on teardown). */
+	workRoot: string
+}
+
+const noopWatcher: SyncEnvironment["createWatcher"] = async () => ({
+	close: async (): Promise<void> => {}
+})
+
+/**
+ * Build a real, isolated sync world against the live account:
+ *   - a remote directory `/<runId>` under the account's base folder is the sync's remote root,
+ *   - a fresh local tmp dir is the sync's local root, with its state/db in a sibling tmp dir,
+ *   - a real {@link SyncWorker}/{@link Sync} wired with the PRODUCTION environment (real fs, real
+ *     write-file-atomic, the msgpack `fetchDirTree`) so the engine talks to the real backend exactly as
+ *     it does in the desktop client. Only the directory watcher is a no-op by default — cycles are
+ *     driven explicitly for determinism.
+ *
+ * Always pair with {@link destroyE2EWorld} (permanent remote delete + trash empty + local tmp removal).
+ */
+export async function createE2EWorld(options: E2EWorldOptions): Promise<E2EWorld> {
+	const { sdk } = options
+	const runId = uuidv4()
+	const baseFolderUUID = sdk.config.baseFolderUUID
+
+	if (!baseFolderUUID || baseFolderUUID.length === 0) {
+		throw new Error("SDK has no baseFolderUUID — login likely failed.")
+	}
+
+	// Remote root: a fresh /<runId> directory under the account base folder.
+	const remoteParentUUID = await sdk.cloud().createDirectory({
+		name: runId,
+		parent: baseFolderUUID
+	})
+
+	// Local roots: a fresh tmp tree, sync dir + db dir as siblings.
+	const workRoot = pathModule.join(os.tmpdir(), `filen-sync-e2e-${runId}`)
+	const localRoot = pathModule.join(workRoot, "local")
+	const dbPath = pathModule.join(workRoot, "db")
+
+	await fs.ensureDir(localRoot)
+	await fs.ensureDir(dbPath)
+
+	if (typeof options.filenIgnore === "string") {
+		await fs.writeFile(pathModule.join(localRoot, ".filenignore"), options.filenIgnore)
+	}
+
+	const messages: SyncMessage[] = []
+	const syncPair: SyncPair = {
+		name: `e2e-${runId}`,
+		uuid: runId,
+		localPath: localRoot,
+		remotePath: `/${runId}`,
+		remoteParentUUID,
+		mode: options.mode,
+		excludeDotFiles: options.excludeDotFiles ?? false,
+		paused: false,
+		localTrashDisabled: options.localTrashDisabled ?? true,
+		requireConfirmationOnLargeDeletion: options.requireConfirmationOnLargeDeletion ?? false
+	}
+
+	const environment: SyncEnvironment = options.useRealWatcher
+		? defaultEnvironment()
+		: { ...defaultEnvironment(), createWatcher: noopWatcher }
+
+	const worker = new SyncWorker({
+		syncPairs: [syncPair],
+		dbPath,
+		sdk,
+		onMessage: message => {
+			messages.push(message)
+		},
+		disableLogging: true,
+		environment
+	})
+
+	const sync = new Sync({ syncPair, worker })
+
+	worker.syncs[syncPair.uuid] = sync
+
+	// Mirror the harness pattern: load persisted state directly and drive discrete cycles ourselves
+	// instead of letting initialize() start the self-scheduling loop.
+	await sync.state.initialize()
+	await sync.ignorer.initialize()
+
+	return {
+		sdk,
+		worker,
+		sync,
+		syncPair,
+		messages,
+		runId,
+		remoteParentUUID,
+		localRoot,
+		dbPath,
+		workRoot
+	}
+}
+
+/**
+ * Tear a world down completely and leave the account clean:
+ *   1. permanently delete the remote `/<runId>` directory (real delete, NOT trash),
+ *   2. empty the account trash (the engine trashes its own deletions during a test; a dedicated test
+ *      account means this is safe and is what "no trash left behind" requires),
+ *   3. remove the local tmp tree.
+ * Every step is best-effort so one failure cannot strand the others.
+ */
+export async function destroyE2EWorld(world: E2EWorld): Promise<void> {
+	try {
+		await world.sync.cleanup({ deleteLocalDbFiles: false })
+	} catch {
+		// best effort
+	}
+
+	try {
+		await world.sdk.cloud().deleteDirectory({ uuid: world.remoteParentUUID })
+	} catch {
+		// already gone
+	}
+
+	try {
+		await world.sdk.cloud().emptyTrash()
+	} catch {
+		// best effort
+	}
+
+	try {
+		await fs.rm(world.workRoot, { force: true, recursive: true, maxRetries: 10, retryDelay: 100 })
+	} catch {
+		// best effort
+	}
+}
+
+/**
+ * Simulate a process restart / client upgrade: rebuild the worker + sync over the SAME local dir, db
+ * dir, and remote root, so persisted state (previous trees, deviceId, hashes) is reloaded from disk.
+ * Mutates `world` in place and keeps appending to the same message stream.
+ */
+export async function restartE2EWorld(world: E2EWorld, options: { useRealWatcher?: boolean } = {}): Promise<void> {
+	try {
+		await world.sync.cleanup({ deleteLocalDbFiles: false })
+	} catch {
+		// best effort
+	}
+
+	const environment: SyncEnvironment = options.useRealWatcher ? defaultEnvironment() : { ...defaultEnvironment(), createWatcher: noopWatcher }
+
+	const worker = new SyncWorker({
+		syncPairs: [world.syncPair],
+		dbPath: world.dbPath,
+		sdk: world.sdk,
+		onMessage: message => {
+			world.messages.push(message)
+		},
+		disableLogging: true,
+		environment
+	})
+
+	const sync = new Sync({ syncPair: world.syncPair, worker })
+
+	worker.syncs[world.syncPair.uuid] = sync
+
+	await sync.state.initialize()
+	await sync.ignorer.initialize()
+
+	world.worker = worker
+	world.sync = sync
+}
+
+/**
+ * Create a world, run `body`, and ALWAYS tear it down (permanent remote delete + trash empty + local
+ * tmp removal) — even when the body throws. The standard way to write an e2e case so no account state
+ * leaks between tests or on failure.
+ */
+export async function withE2EWorld(options: E2EWorldOptions, body: (world: E2EWorld) => Promise<void>): Promise<void> {
+	const world = await createE2EWorld(options)
+
+	try {
+		await body(world)
+	} finally {
+		await destroyE2EWorld(world)
+	}
+}

package/tests/e2e/ignore.e2e.test.ts

@@ -0,0 +1,123 @@
+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 } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, modifyLocal, existsLocal } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — .filenignore + dotfile filtering against the live backend. Ignored paths must never
+ * reach the remote; everything else must.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — ignore filtering", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("ignores a directory pattern", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", filenIgnore: "ignored/\n" }, async world => {
+			await writeLocal(world, "ignored/secret.txt", "nope")
+			await writeLocal(world, "visible.txt", "yes")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/visible.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/ignored"]).toBeUndefined()
+			expect(remote["/ignored/secret.txt"]).toBeUndefined()
+		})
+	})
+
+	it("ignores a glob pattern", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", filenIgnore: "*.log\n" }, async world => {
+			await writeLocal(world, "app.log", "log")
+			await writeLocal(world, "app.txt", "txt")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/app.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/app.log"]).toBeUndefined()
+		})
+	})
+
+	it("honors a negation pattern", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", filenIgnore: "*.log\n!keep.log\n" }, async world => {
+			await writeLocal(world, "drop.log", "drop")
+			await writeLocal(world, "keep.log", "keep")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/keep.log"]).toMatchObject({ type: "file" })
+			expect(remote["/drop.log"]).toBeUndefined()
+		})
+	})
+
+	it("ignores a nested glob pattern", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", filenIgnore: "**/*.tmp\n" }, async world => {
+			await writeLocal(world, "a/b/scratch.tmp", "tmp")
+			await writeLocal(world, "a/b/real.txt", "real")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/a/b/real.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/a/b/scratch.tmp"]).toBeUndefined()
+		})
+	})
+
+	it("excludes dotfiles when excludeDotFiles is set", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", excludeDotFiles: true }, async world => {
+			await writeLocal(world, ".hidden", "secret")
+			await writeLocal(world, "shown.txt", "public")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/shown.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/.hidden"]).toBeUndefined()
+		})
+	})
+
+	it("default OS-junk names (.DS_Store, Thumbs.db) are never uploaded; real files sync", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, ".DS_Store", "junk")
+			await writeLocal(world, "Thumbs.db", "junk")
+			await writeLocal(world, "real.txt", "real")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/.DS_Store"]).toBeUndefined()
+			expect(remote["/Thumbs.db"]).toBeUndefined()
+			expect(remote["/real.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("a file synced and THEN newly ignored is not deleted from the remote (ignore ≠ delete)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "keep-me.txt", "content")
+			await settle(world)
+
+			// It synced up.
+			expect((await snapshotRemoteReal(world))["/keep-me.txt"]).toMatchObject({ type: "file" })
+
+			// Now ignore the already-synced file and edit it; ignoring must not imply a remote deletion.
+			await world.worker.updateIgnorerContent(world.syncPair.uuid, "keep-me.txt")
+			await modifyLocal(world, "keep-me.txt", "content-edited-after-ignore")
+			await settle(world)
+
+			// The remote copy survives and the local file is untouched — ignore is not deletion.
+			expect((await snapshotRemoteReal(world))["/keep-me.txt"]).toMatchObject({ type: "file" })
+			expect(await existsLocal(world, "keep-me.txt")).toBe(true)
+		})
+	})
+})

package/tests/e2e/lifecycle.e2e.test.ts

@@ -0,0 +1,290 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import FilenSDK, { PauseSignal } from "@filen/sdk"
+import fs from "fs-extra"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { cycle, settle, expectConverged, messagesOfType, allOps } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, rmLocal, uploadRemote, readLocal, existsLocal } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — the SyncWorker control surface against the live backend, the live counterpart of mocked
+ * Category I (+ the abort-driven error path of Q5). These exercise the REAL worker methods a host app
+ * drives at runtime — pause/resume (I2), runtime mode change (I6), pair removal + db cleanup (I3),
+ * idempotent registration (I7), per-transfer pause/stop routing (I4), and stop-then-retry for an upload
+ * (I5) — plus the task-error gate (Q5). A pre-registered abort controller is the deterministic stand-in
+ * for an in-flight transfer: the SDK honors the abort at the chunk-loop entry, so a pre-aborted upload
+ * fails reliably (verified by hammering). Stopping a DOWNLOAD is covered too — and surfaced a real bug now
+ * fixed in remote.ts: an aborted download RESOLVES with a 0-byte staged file, which the engine used to
+ * commit as synced (permanent divergence); the integrity guard now discards an incomplete download so the
+ * next cycle re-fetches it in full. Only runOnce (I1) stays mocked-only — a self-scheduling one-shot loop
+ * whose distinctive effect, cleanup-without-reschedule, is already exercised live by I3.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — lifecycle & control surface", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("a paused pair short-circuits its cycle; resuming syncs the pending change (I2)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			world.worker.updatePaused(world.syncPair.uuid, true)
+
+			// A change is pending while paused.
+			await writeLocal(world, "a.txt", "v1")
+
+			const pausedMessages = await cycle(world)
+
+			// The cycle short-circuits before doing any work: cyclePaused is emitted, nothing starts/transfers.
+			expect(messagesOfType(pausedMessages, "cyclePaused").length).toBeGreaterThan(0)
+			expect(messagesOfType(pausedMessages, "cycleStarted").length).toBe(0)
+			expect(allOps(pausedMessages)).toEqual([])
+			expect((await snapshotRemoteReal(world))["/a.txt"], "nothing uploaded while paused").toBeUndefined()
+
+			// Resume → the pending change now syncs to the real backend and the worlds converge.
+			world.worker.updatePaused(world.syncPair.uuid, false)
+			await settle(world)
+			await expectConverged(world)
+
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("updateMode mid-run switches behavior on the next cycle: twoWay -> localBackup stops deletions (I6)", 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)
+
+			// Switch to a backup mode; it must take effect on the NEXT cycle.
+			world.worker.updateMode(world.syncPair.uuid, "localBackup")
+
+			// A deletion twoWay WOULD propagate, plus an addition.
+			await rmLocal(world, "a.txt")
+			await writeLocal(world, "c.txt", "c")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			// localBackup propagates additions but NOT deletions, proving the new mode is active.
+			expect(remote["/c.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/a.txt"], "the local deletion was NOT mirrored (backup keeps the remote copy)").toMatchObject({
+				type: "file"
+			})
+		})
+	})
+
+	it("removing a pair aborts its in-flight transfers, deletes its db files, and exits (I3)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			// First settle persists state + a deviceId, so there are real db files to delete.
+			await settle(world)
+
+			const stateFiles = [
+				world.sync.state.previousLocalTreePath,
+				world.sync.state.previousRemoteTreePath,
+				world.sync.state.localFileHashesPath
+			]
+
+			for (const file of stateFiles) {
+				expect(await fs.pathExists(file)).toBe(true)
+			}
+
+			// Stand in for an in-flight transfer: a registered, not-yet-aborted controller at the real key.
+			world.sync.abortControllers["upload:/a.txt"] = new AbortController()
+
+			const mark = world.messages.length
+
+			await world.worker.updateRemoved(world.syncPair.uuid, true)
+
+			const removalMessages = world.messages.slice(mark)
+
+			// The transfer was aborted, the pair is marked removed, and it exited (cleanup -> cycleExited).
+			expect(world.sync.abortControllers["upload:/a.txt"]!.signal.aborted).toBe(true)
+			expect(world.sync.removed).toBe(true)
+			expect(messagesOfType(removalMessages, "cycleExited").length).toBeGreaterThan(0)
+
+			// The persisted state files for this pair are gone from the real filesystem.
+			for (const file of stateFiles) {
+				expect(await fs.pathExists(file)).toBe(false)
+			}
+		})
+	})
+
+	it("updateSyncPairs is an idempotent no-op for empty input and an already-registered pair (I7)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			await settle(world)
+			await expectConverged(world)
+
+			const existingSync = world.worker.syncs[world.syncPair.uuid]
+
+			// Empty input returns early; re-registering the existing pair must not recreate its Sync.
+			await world.worker.updateSyncPairs([])
+			await world.worker.updateSyncPairs([world.syncPair])
+
+			expect(world.worker.syncs[world.syncPair.uuid]).toBe(existingSync)
+
+			// The worker stays healthy after the no-op registrations: a new change still converges live.
+			await writeLocal(world, "b.txt", "b")
+			await settle(world)
+			await expectConverged(world)
+
+			expect((await snapshotRemoteReal(world))["/b.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("pauseTransfer / resumeTransfer route to the per-transfer signal; unknown keys are safe no-ops (I4)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			// Stand in for an in-flight upload: a registered pause signal keyed `${type}:${path}`.
+			const signalKey = "upload:/a.txt"
+			world.sync.pauseSignals[signalKey] = new PauseSignal()
+
+			// pauseTransfer / resumeTransfer route by the same key and flip the real signal's state.
+			world.worker.pauseTransfer(uuid, "upload", "/a.txt")
+			expect(world.sync.pauseSignals[signalKey]!.isPaused()).toBe(true)
+
+			world.worker.resumeTransfer(uuid, "upload", "/a.txt")
+			expect(world.sync.pauseSignals[signalKey]!.isPaused()).toBe(false)
+
+			// An unknown key is a safe no-op: no throw and no signal conjured.
+			world.worker.pauseTransfer(uuid, "download", "/does-not-exist.txt")
+			expect(world.sync.pauseSignals["download:/does-not-exist.txt"]).toBeUndefined()
+		})
+	})
+
+	it("stopping a transfer surfaces an error, and a retry converges (I5)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			await writeLocal(world, "a.txt", "v1")
+
+			// Pre-register the transfer's abort controller (as if in flight) and stop it via the worker; the
+			// upload then runs against an already-aborted signal — the engine reuses the registered controller.
+			const signalKey = "upload:/a.txt"
+			world.sync.abortControllers[signalKey] = new AbortController()
+			world.worker.stopTransfer(uuid, "upload", "/a.txt")
+
+			expect(world.sync.abortControllers[signalKey]!.signal.aborted).toBe(true)
+
+			const abortedMessages = await cycle(world)
+			const uploadErrors = messagesOfType(abortedMessages, "transfer").filter(
+				message => message.data.of === "upload" && message.data.type === "error"
+			)
+
+			// The abort is surfaced as an upload transfer error and nothing was uploaded.
+			expect(uploadErrors.length).toBeGreaterThan(0)
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toBeUndefined()
+
+			// Retry on a later cycle: clear the recorded task error (it gates the next cycle); a fresh
+			// controller is created and the upload succeeds against the real backend.
+			world.worker.resetTaskErrors(uuid)
+			await settle(world)
+			await expectConverged(world)
+
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("a cycle starting with an unresolved task error re-reports it and gates without doing work (Q5)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			await writeLocal(world, "a.txt", "v1")
+
+			// Induce a REAL task error (no synthetic injection): stop the upload so the transfer fails and the
+			// engine records a task error for the pair.
+			world.sync.abortControllers["upload:/a.txt"] = new AbortController()
+			world.worker.stopTransfer(uuid, "upload", "/a.txt")
+
+			await cycle(world)
+
+			// The NEXT cycle is NOT error-reset, so it observes the pending task error at the very top and
+			// gates: it re-emits taskErrors + cycleRestarting and returns BEFORE cycleStarted (no work done).
+			const gated = await cycle(world)
+
+			expect(messagesOfType(gated, "taskErrors").length).toBeGreaterThan(0)
+			expect(messagesOfType(gated, "cycleRestarting").length).toBeGreaterThan(0)
+			expect(messagesOfType(gated, "cycleStarted").length).toBe(0)
+			expect((await snapshotRemoteReal(world))["/a.txt"], "still nothing uploaded while the error gates").toBeUndefined()
+		})
+	})
+
+	it("an incomplete (stopped) download is discarded, not committed as 0 bytes, and a retry converges", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			// A remote-origin file the engine will pull down.
+			await uploadRemote(world, "r.txt", "remote-content")
+
+			// Pre-abort the download. The SDK resolves with a 0-byte staged file (the aborted stream ends
+			// cleanly), but the engine's integrity guard must DISCARD it on the size mismatch instead of
+			// moving a 0-byte file into place and caching it as synced — which would diverge permanently.
+			const signalKey = "download:/r.txt"
+			world.sync.abortControllers[signalKey] = new AbortController()
+			world.worker.stopTransfer(uuid, "download", "/r.txt")
+
+			const abortedMessages = await cycle(world)
+
+			expect(
+				messagesOfType(abortedMessages, "transfer").filter(message => message.data.of === "download" && message.data.type === "error")
+					.length
+			).toBeGreaterThan(0)
+			// The guard prevented a corrupt 0-byte file from being committed locally.
+			expect(await existsLocal(world, "r.txt"), "the incomplete download must not be committed").toBe(false)
+
+			// Retry: the FULL file downloads and the worlds converge (no lingering 0-byte divergence).
+			world.worker.resetTaskErrors(uuid)
+			await settle(world)
+			await expectConverged(world)
+
+			expect(await readLocal(world, "r.txt")).toBe("remote-content")
+		})
+	})
+
+	it("an upload failure on an already-synced, then EDITED file does not suppress the retry (F1)", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			// First sync the file so it exists on BOTH sides and its md5 is recorded in localFileHashes.
+			await writeLocal(world, "a.txt", "v1-original")
+			await settle(world)
+			await expectConverged(world)
+
+			// Edit it (distinct size) → the modify branch, which consults the md5 dedup cache.
+			await writeLocal(world, "a.txt", "v2-edited-longer-content")
+
+			// Fail the upload of the edit by pre-aborting its transfer (no synthetic injection).
+			const signalKey = "upload:/a.txt"
+			world.sync.abortControllers[signalKey] = new AbortController()
+			world.worker.stopTransfer(uuid, "upload", "/a.txt")
+
+			const abortedMessages = await cycle(world)
+
+			expect(
+				messagesOfType(abortedMessages, "transfer").filter(message => message.data.of === "upload" && message.data.type === "error")
+					.length
+			).toBeGreaterThan(0)
+			// The edit has not landed remotely yet (still the original).
+			expect((await snapshotRemoteReal(world, { withContent: true }))["/a.txt"]).toMatchObject({ size: "v1-original".length })
+
+			// Recover. resetTaskErrors does NOT clear localFileHashes — if the failed upload had poisoned it with
+			// the edit's hash, the modify branch would now find the hash already cached and SUPPRESS the
+			// re-upload, stranding the edit locally forever. With the fix the hash is only written on success.
+			world.worker.resetTaskErrors(uuid)
+			await settle(world)
+			await expectConverged(world)
+
+			expect(await readLocal(world, "a.txt")).toBe("v2-edited-longer-content")
+			expect((await snapshotRemoteReal(world, { withContent: true }))["/a.txt"]).toMatchObject({ size: "v2-edited-longer-content".length })
+		})
+	})
+})