@aigne/afs-did-space 1.12.0-beta.5

package/dist/sync-engine.mjs

@@ -0,0 +1,1315 @@
+import { computeCID } from "./cid.mjs";
+import { DOWNLOAD_MAX_ENTRIES } from "./download-actions.mjs";
+import { detectMimeType } from "./mime-utils.mjs";
+import { DEFAULT_INLINE_THRESHOLD, decodeInlineText } from "./inline-content.mjs";
+import { BatchOverBudgetError, BatchUnsupportedError, DownloadForbiddenError } from "./remote-afs.mjs";
+import { AFSCompactedError, AFSConflictError, makeNsLog } from "@aigne/afs";
+import { firstNonEmpty } from "@aigne/afs/utils/env";
+
+//#region src/sync-engine.ts
+const log = makeNsLog("provider:did-space");
+/** Client-side batch packing constants (wire-contract §9 CF tier — packing
+*  to the CF table is slightly conservative against Node but always valid;
+*  the client never needs to know the server runtime, design §7.3). */
+const BATCH_PUT_MAX_ENTRIES = 20;
+const BATCH_DELETE_MAX_ENTRIES = 40;
+const BATCH_PUT_MAX_BYTES = 1024 * 1024;
+const BATCH_READ_MAX_ENTRIES = 20;
+const BATCH_READ_MAX_BYTES = 2 * 1024 * 1024;
+/**
+* Push batch size. Each round, push() fetches up to this many unpushed
+* changelog rows in a single SQLite query and uploads them one by one.
+* Lower than PULL_BATCH_LIMIT because each row is a separate PUT/DELETE
+* round-trip (vs. PULL which fetches many change rows in a single call).
+*/
+const PUSH_BATCH_LIMIT = 100;
+/**
+* Client-side upload-plane ACTIVATION threshold (design §6.1 / §15 decision 4).
+* The upload plane (prepare → out-of-band PUT → commit) is taken ONLY for large
+* backlogs — the Aside pain point of a ~2000-row small-record first full sync.
+* Small/common writes stay on the proven `batchWrite` path. A push uses the
+* upload plane only when its put backlog is ≥ MIN_ENTRIES (peeked) AND the
+* server advertises grant capability.
+*
+* Value 200 is deliberate, not a placeholder: lowering it does nothing for the
+* 2000 case (2000 ≥ 200 already activates) and would only pull the 100–200 band
+* onto the upload plane — MORE round-trips than batchWrite's ceil(N/20) POSTs.
+* Only lower with a measured 100–200 wall-clock crossover.
+*/
+const AFS_DID_SPACE_UPLOAD_MIN_ENTRIES = 200;
+const AFS_DID_SPACE_UPLOAD_MIN_BYTES = 8 * 1024 * 1024;
+/**
+* Browser upload-plane SINGLE-FILE size threshold (upload-browser §4.5 / T4.2).
+* Distinct from the native-sync count/bytes batch gates above: the browser
+* orchestrator triages by individual file size — a file LARGER than this goes
+* the grant plane (bytes direct to R2, out of the worker); smaller files fall to
+* the legacy WS batchWrite. The browser orchestrator mirrors this value in its
+* inlined page JS (it cannot import this const). Conservative default — only
+* clearly-large files grant; measurement-gated, calibrated in P6.
+*/
+const AFS_DID_SPACE_UPLOAD_MIN_SIZE = 4 * 1024 * 1024;
+/**
+* Upload-plane put-CHUNK caps (the load-bearing fix for Aside 2000 small writes).
+* Once the upload plane is active, each prepare/commit round packs up to this
+* many entries — DECOUPLED from `BATCH_PUT_MAX_ENTRIES` (20). Reusing the batch
+* cap would turn a 2000-entry backlog into ~100 prepare/commit rounds; at 100 it
+* is ~20. The effective chunk is `min(CHUNK_MAX_ENTRIES, PUSH_BATCH_LIMIT)`, and
+* `PUSH_BATCH_LIMIT` is also 100, so a full window is one chunk → 20 rounds for
+* 2000. The Cloudflare commit-sim probe (100 entries ≈ 425ms wall) justifies 100
+* as a safe client default; raising it past PUSH_BATCH_LIMIT is inert.
+*/
+const AFS_DID_SPACE_UPLOAD_CHUNK_MAX_ENTRIES = 100;
+const AFS_DID_SPACE_UPLOAD_CHUNK_MAX_BYTES = 8 * 1024 * 1024;
+/**
+* Out-of-band PUT fan-out for the upload plane (independent tuning, design §3).
+* Each presigned PUT leaves the worker, so the client can run several in flight;
+* 8 is the deterministic default. Adaptive 8→4 backoff under R2 5xx/429 is a
+* follow-up, intentionally NOT in the first patch.
+*/
+const AFS_DID_SPACE_UPLOAD_PUT_CONCURRENCY = 8;
+/**
+* Flush local_seq to SQLite every N successful pushes. Trade-off: lower
+* = less progress lost on crash, higher = fewer DB writes. 10 is the
+* round-trip frequency Task 3.6 spec mandates.
+*/
+const PUSH_PROGRESS_FLUSH_INTERVAL = 10;
+/**
+* Pull batch size. Each `.changelog` cursor list call fetches up to this
+* many rows. Matches the server's MAX_LIMIT hard cap
+* (`services/arc-computer/src/handlers/space-api.ts` — .changelog list
+* branch inside `_createSpaceHandler`).
+*/
+const PULL_BATCH_LIMIT = 1e3;
+/**
+* Concurrency cap for `.objects/{cid}` reads inside pull(). Higher = faster
+* under large pulls, but risks server-side rate limits and memory
+* pressure on the client. 4 is the spec default.
+*/
+const PULL_FETCH_CONCURRENCY = 4;
+/**
+* Download-plane size gate (design §6.3 / T3.5) — CALIBRATED by P4/T4.4 staging
+* measurement (2026-06-21, aside.afsd.io, logs/staging-download-plane-*.log).
+* An object whose size is ≥ this routes to the download plane (prepare-download
+* → direct R2 GET → computeCID → internalWrite), keeping its bytes out of the
+* worker; smaller objects / text / inline-cache hits stay on `batchRead` (D1
+* inline serves small text with ZERO R2 GETs — faster there). A null/missing
+* size is treated as small (never route into the plane on missing size).
+*
+* MEASURED breaking point: a single in-worker `.objects/{cid}` read (arrayBuffer
+* + base64-over-JSON) is fine at 5 MiB (~930ms) but HARD-FAILS with HTTP 503
+* (Worker exceeded resource limits) at 8 / 12 / 18 MiB — the download plane
+* served all of those correctly (8 MiB ~0.8s warm). So the worker simply CANNOT
+* read a single object ≳8 MiB; 4 MiB sits safely below that failure zone (and
+* covers the reported 5.26 MiB pain case) while keeping the common small/medium
+* objects on the locally-fast worker path.
+*/
+const DOWNLOAD_PLANE_MIN_BYTES = 4 * 1024 * 1024;
+/**
+* Out-of-band GET fan-out for the download plane (design §6.3). The client reads
+* directly from R2 and is NOT bound by the Workers 6-simultaneous-connection cap,
+* so the default is higher than the in-worker batchRead. Default 8; TS/Node may
+* override via `AFS_DID_SPACE_DOWNLOAD_GET_CONCURRENCY` (a single-point int parse
+* — NOT parseBool; the `AFS_DID_SPACE_DOWNLOAD_*` family, mirror of the shipped
+* `AFS_DID_SPACE_UPLOAD_*`). Swift/Kotlin clients use their own platform constant.
+*/
+const DOWNLOAD_GET_CONCURRENCY_DEFAULT = 8;
+function resolveDownloadGetConcurrency() {
+	const raw = typeof process !== "undefined" && process.env ? firstNonEmpty(process.env.AFS_DID_SPACE_DOWNLOAD_GET_CONCURRENCY) : void 0;
+	const n = raw !== void 0 ? Number.parseInt(raw, 10) : NaN;
+	return Number.isInteger(n) && n > 0 ? n : DOWNLOAD_GET_CONCURRENCY_DEFAULT;
+}
+/**
+* Wall-clock budget for a single sync() call. Protects against runaway
+* pulls on wildly out-of-date clients. pull() checks Date.now() against
+* the deadline at the top of every batch loop iteration.
+*/
+const SYNC_WALL_CLOCK_BUDGET_MS = 25e3;
+/**
+* Thrown by {@link SyncEngine.resolveConflict} when the server's 409
+* conflict response is missing required fields (notably `currentMtime`).
+* The LWW decision needs both timestamps, so a malformed response is
+* treated as fatal to the in-flight push leg.
+*
+* Phase 5 Task 5.1 (G11): replaced the Task 3.6 `ConflictTODOError`
+* stub with the real LWW resolver. The resolver handles every well-formed
+* conflict shape inline; this error class only fires on protocol breakage.
+*/
+var ConflictResolutionError = class extends Error {
+	change;
+	reason;
+	constructor(change, reason) {
+		super(`resolveConflict on ${change.path}: ${reason}`);
+		this.name = "ConflictResolutionError";
+		this.change = change;
+		this.reason = reason;
+	}
+};
+/**
+* Thrown by {@link SyncEngine.fullResync} when the cloud-side manifest
+* snapshot exceeds the size budget the server is willing to materialise
+* in one shot. The server signals this via `result.meta.truncated === true`
+* on the `cloudAfs.list("", { maxDepth: -1 })` response.
+*
+* Recovery: the caller (typically a higher-level scheduler) is expected
+* to either narrow the scope (sub-tree manifest, future feature) or
+* back off and retry once the cloud has compacted the manifest. There
+* is no automatic recovery inside SyncEngine — applying a partial
+* manifest would silently lose data.
+*/
+var ManifestTooLargeError = class extends Error {
+	constructor(message = "fullResync: cloud manifest is too large to materialise in one shot") {
+		super(message);
+		this.name = "ManifestTooLargeError";
+	}
+};
+/**
+* Thrown when an object read returns 404 for a cid that is the **current**
+* state of a path — design §4.7.2, the GC-go-live safety contract. Enabling
+* object GC makes a current-cid 404 possible (a GC bug or the residual
+* re-reference race); it MUST be a loud, hard error — NEVER silently treated as
+* convergence. The cursor must stay pinned (do not advance past the failing
+* change) so the next sync revisits it once the object is restored/re-pushed.
+*
+* Distinct from a **superseded**-cid 404 (an old changelog row a later same-path
+* row supersedes), which is benign — skip + advance (the Path-Y offline
+* tradeoff, §0.2). Classification: see {@link classifyMissingObject}.
+*/
+var CurrentObjectMissingError = class extends Error {
+	path;
+	cid;
+	source;
+	constructor(path, cid, source) {
+		super(`SyncEngine: current object missing (${source}) for path ${path} cid ${cid} — object GC may have reclaimed a live cid; cursor left pinned for retry`);
+		this.name = "CurrentObjectMissingError";
+		this.path = path;
+		this.cid = cid;
+		this.source = source;
+	}
+};
+/**
+* Classify an object-read 404 during incremental apply (design §4.7.2).
+*
+* `lastCidForPath` maps each path in the batch to the cid of its LAST row
+* (max seq) — `null` if that last row is a delete. Fail-closed:
+*   - cid === the path's last-row cid  ⇒ "current" (this cid is the path's
+*     final state in the batch) ⇒ hard error.
+*   - path absent from the map (unknown cid, not in this batch) ⇒ "current"
+*     (fail closed — never benign-skip something we can't prove superseded).
+*   - otherwise a later same-path row supersedes this cid ⇒ "superseded" ⇒ skip.
+*/
+function classifyMissingObject(path, cid, lastCidForPath) {
+	if (!lastCidForPath.has(path)) return "current";
+	return lastCidForPath.get(path) === cid ? "current" : "superseded";
+}
+/**
+* Simple promise-based mutex used to serialise concurrent sync() calls.
+* Callers `await acquire()` to claim the lock and MUST `release()` in a
+* finally block. FIFO ordering is not guaranteed — the spec only
+* requires mutual exclusion.
+*/
+var AsyncMutex = class {
+	chain = Promise.resolve();
+	async acquire() {
+		let release;
+		const next = new Promise((resolve) => {
+			release = resolve;
+		});
+		const prev = this.chain;
+		this.chain = this.chain.then(() => next);
+		await prev;
+		return release;
+	}
+};
+/**
+* Local push + pull + GC orchestrator. One instance per DIDSpaceProvider /
+* per userDid. Instances are NOT thread-safe at the data level — the
+* internal mutex only serialises `sync()` calls; callers that mutate
+* local state while a sync is in flight are expected to do so via
+* `provider.internalWrite/Delete` so the changelog row is visible to the
+* next push batch.
+*/
+var SyncEngine = class {
+	localChangelog;
+	syncStateStore;
+	cloudAfs;
+	provider;
+	selfDeviceId;
+	wallClockBudgetMs;
+	mutex = new AsyncMutex();
+	/**
+	* Per-INSTANCE capability-fallback memory (design §7.1): set the first
+	* time the server answers a batch envelope with the exact
+	* "Unsupported op 'batch…'" 400. Never set by any other 400 (e.g.
+	* BATCH_OVER_BUDGET halves and retries instead).
+	*/
+	batchFallback = false;
+	/**
+	* Per-INSTANCE upload-plane capability memory (design §7.1, mirrors
+	* batchFallback). null = not yet probed; set on the first `push()` that
+	* reaches the threshold. `false` (Node / old server / signer-less) keeps the
+	* engine on batchWrite forever for this instance.
+	*/
+	uploadPlaneCapable = null;
+	/** Set per-push() when this push routes large put-chunks through the upload plane. */
+	uploadPlaneActive = false;
+	/**
+	* Per-INSTANCE download-plane capability memory (design §7.3, mirrors
+	* uploadPlaneCapable). null = not yet probed. `false` (Node / old server /
+	* signer-less) keeps the engine on batchRead forever for this instance — it is
+	* NOT reset per session (unlike {@link downloadFallback}): a server that never
+	* advertised the capability won't start mid-process, so re-probing every sync
+	* would just waste a `/.actions` list. A server UPGRADE needs a client restart.
+	*/
+	downloadPlaneCapable = null;
+	/**
+	* Runtime fallback-on-403 latch (design §7.3): set when a presigned GET is
+	* rejected 401/403 (token lacks GetObject / bad signature). Once set, the whole
+	* sync SESSION reverts to batchRead and never re-tries the plane — so a misconfig
+	* costs at most ONE 403 per object before the first hit flips it, then nothing.
+	* Reset at the start of each sync() so a fixed token recovers without restart.
+	*/
+	downloadFallback = false;
+	/** Resolved once per instance — the out-of-band GET fan-out (env-overridable). */
+	downloadGetConcurrency = resolveDownloadGetConcurrency();
+	constructor(opts) {
+		if (!opts.deviceId) throw new Error("SyncEngine: deviceId is required");
+		this.localChangelog = opts.localChangelog;
+		this.syncStateStore = opts.syncStateStore;
+		this.cloudAfs = opts.cloudAfs;
+		this.provider = opts.provider;
+		this.selfDeviceId = opts.deviceId;
+		this.wallClockBudgetMs = opts.wallClockBudgetMs ?? SYNC_WALL_CLOCK_BUDGET_MS;
+	}
+	/**
+	* Run a single sync round — push → pull → gc. Concurrent sync() calls
+	* on the same instance are serialised by the internal mutex. Always
+	* returns a {@link SyncResult}; throws only on unhandled errors from
+	* the underlying store/network layers.
+	*/
+	async sync(opts = {}) {
+		const release = await this.mutex.acquire();
+		const deadline = Date.now() + this.wallClockBudgetMs;
+		this.downloadFallback = false;
+		const result = {
+			ok: false,
+			aborted: false,
+			pushed: 0,
+			pulled: 0,
+			gcDeleted: 0,
+			fullResynced: false,
+			endedAt: 0
+		};
+		try {
+			if (opts.signal?.aborted) {
+				result.aborted = true;
+				result.endedAt = Date.now();
+				await this.syncStateStore.save({ syncStatus: { kind: "idle" } });
+				return result;
+			}
+			await this.syncStateStore.save({ syncStatus: { kind: "syncing" } });
+			try {
+				if ((await this.syncStateStore.load()).lastSyncAt === 0) {
+					result.pulled = (await this.fullResync({
+						signal: opts.signal,
+						deadline
+					})).pulled;
+					result.fullResynced = true;
+				} else {
+					result.pushed = (await this.push({
+						signal: opts.signal,
+						deadline
+					})).pushed;
+					const pullResult = await this.pull({
+						signal: opts.signal,
+						deadline
+					});
+					result.pulled = pullResult.pulled;
+					if (pullResult.fullResynced) result.fullResynced = true;
+				}
+				result.gcDeleted = (await this.localChangelog.gc()).deleted;
+				await this.syncStateStore.save({
+					syncStatus: { kind: "active" },
+					lastSyncAt: Date.now()
+				});
+				result.ok = true;
+			} catch (e) {
+				if (opts.signal?.aborted) {
+					result.aborted = true;
+					await this.syncStateStore.save({ syncStatus: { kind: "idle" } });
+					return result;
+				}
+				const message = e instanceof Error ? e.message : String(e);
+				await this.syncStateStore.save({ syncStatus: {
+					kind: "error",
+					message
+				} });
+				throw e;
+			}
+		} finally {
+			result.endedAt = Date.now();
+			release();
+		}
+		return result;
+	}
+	/**
+	* Upload unpushed local changes to the cloud, advancing local_seq in
+	* SQLite every `PUSH_PROGRESS_FLUSH_INTERVAL` rows. On any error
+	* mid-batch, flush the already-advanced cursor before re-throwing so
+	* the next sync() resumes where this one left off.
+	*
+	* Per-row semantics:
+	*   - `put` row → `cloudAfs.write(path, content, {...})`
+	*   - `delete` row → `cloudAfs.delete(path, {...})`
+	*   - `put` row whose file has been deleted locally since the row was
+	*     written → skip (cursor advances; the following delete row will
+	*     tell the cloud what happened).
+	*   - 409 conflict → delegate to {@link SyncEngine.resolveConflict}
+	*     (LWW + tiebreak — see G11 in native-sync-design.md).
+	*/
+	async push(opts) {
+		let cursor = (await this.syncStateStore.load()).localSeq;
+		let pushed = 0;
+		let processedSinceFlush = 0;
+		this.uploadPlaneActive = await this.shouldUseUploadPlane(cursor);
+		const batchCapable = () => !this.batchFallback && typeof this.cloudAfs.batchWrite === "function" && typeof this.cloudAfs.batchDelete === "function";
+		try {
+			while (true) {
+				if (opts.signal?.aborted) return { pushed };
+				if (Date.now() >= opts.deadline) return { pushed };
+				const batch = await this.localChangelog.getUnpushed(cursor, PUSH_BATCH_LIMIT);
+				if (batch.length === 0) break;
+				if (batchCapable()) {
+					const r = await this.pushBatchLeg(batch, cursor, opts);
+					cursor = r.cursor;
+					pushed += r.pushed;
+					await this.syncStateStore.save({ localSeq: cursor });
+					if (r.stop) return { pushed };
+					continue;
+				}
+				for (const change of batch) {
+					if (opts.signal?.aborted) return { pushed };
+					if (Date.now() >= opts.deadline) return { pushed };
+					await this.pushOne(change);
+					cursor = change.seq;
+					pushed += 1;
+					processedSinceFlush += 1;
+					if (processedSinceFlush >= PUSH_PROGRESS_FLUSH_INTERVAL) {
+						await this.syncStateStore.save({ localSeq: cursor });
+						processedSinceFlush = 0;
+					}
+				}
+			}
+		} finally {
+			if (cursor > 0) await this.syncStateStore.save({ localSeq: cursor });
+		}
+		return { pushed };
+	}
+	/**
+	* Batch push leg (P4, design §7.2): split the changelog window into
+	* MAXIMAL same-op runs in seq order (op type never mixes inside a run —
+	* put(a)→delete(a) is two runs, so same-path cross-op order rides the
+	* sequential awaits); pack each run by maxEntries + Σ-decoded-bytes +
+	* UNIQUE-path-per-chunk (a duplicate path cuts the chunk so the server's
+	* one-shot preread stays serial-equivalent — and the SECOND chunk's
+	* ifMatch sees the first chunk's result); consume results strictly in
+	* order. Returns the advanced cursor; `stop` = abort/deadline/tail-skip.
+	*/
+	async pushBatchLeg(batch, cursor, opts) {
+		let pushed = 0;
+		const runs = [];
+		for (const change of batch) {
+			const last = runs[runs.length - 1];
+			if (last && last[0].op === change.op) last.push(change);
+			else runs.push([change]);
+		}
+		for (const run of runs) {
+			let index = 0;
+			while (index < run.length) {
+				if (opts.signal?.aborted || Date.now() >= opts.deadline) return {
+					cursor,
+					pushed,
+					stop: true
+				};
+				const putUploadPlane = run[0].op === "put" && this.uploadPlaneActive;
+				const maxEntries = run[0].op !== "put" ? BATCH_DELETE_MAX_ENTRIES : putUploadPlane ? AFS_DID_SPACE_UPLOAD_CHUNK_MAX_ENTRIES : BATCH_PUT_MAX_ENTRIES;
+				const maxBytes = putUploadPlane ? AFS_DID_SPACE_UPLOAD_CHUNK_MAX_BYTES : BATCH_PUT_MAX_BYTES;
+				const chunk = [];
+				const seen = /* @__PURE__ */ new Set();
+				let chunkBytes = 0;
+				while (index < run.length && chunk.length < maxEntries) {
+					const change = run[index];
+					if (seen.has(change.path)) break;
+					if (change.op === "put") {
+						const bytes = await this.provider.readBytes(change.path);
+						if (bytes === null) {
+							cursor = change.seq;
+							index++;
+							continue;
+						}
+						if (chunk.length > 0 && chunkBytes + bytes.length > maxBytes) break;
+						chunkBytes += bytes.length;
+						chunk.push({
+							change,
+							bytes
+						});
+					} else chunk.push({
+						change,
+						bytes: null
+					});
+					seen.add(change.path);
+					index++;
+				}
+				if (chunk.length === 0) continue;
+				const outcome = await this.sendPushChunk(chunk);
+				if (outcome.fallback) {
+					this.batchFallback = true;
+					return {
+						cursor,
+						pushed,
+						stop: false
+					};
+				}
+				for (const consumed of outcome.consumed) {
+					cursor = consumed.seq;
+					if (consumed.counted) pushed += 1;
+				}
+				if (outcome.consumed.length > 0 || outcome.error) await this.syncStateStore.save({ localSeq: cursor });
+				if (outcome.error) throw outcome.error;
+				if (outcome.tailSkipped) return {
+					cursor,
+					pushed,
+					stop: false
+				};
+			}
+		}
+		return {
+			cursor,
+			pushed,
+			stop: false
+		};
+	}
+	/**
+	* Send one packed chunk, halving on envelope over-budget (down to 1 entry
+	* = pushOne, the literal old behavior — bounded recursion by construction:
+	* each level halves a strictly smaller chunk).
+	*/
+	async sendPushChunk(chunk) {
+		const op = chunk[0].change.op;
+		let result;
+		try {
+			if (op === "put") result = this.uploadPlaneActive ? await this.uploadPlaneWriteChunk(chunk) : await this.cloudAfs.batchWrite(await Promise.all(chunk.map(async ({ change, bytes }) => {
+				const appMeta = await this.readAppMeta(change.path, bytes);
+				return {
+					path: normaliseWirePath(change.path),
+					content: appMeta ? {
+						content: bytes,
+						meta: appMeta
+					} : { content: bytes },
+					options: {
+						...change.old_cid ? { ifMatch: change.old_cid } : {},
+						meta: {
+							deviceId: change.device_id,
+							mtime: change.mtime
+						}
+					}
+				};
+			})));
+			else result = await this.cloudAfs.batchDelete(chunk.map(({ change }) => ({
+				path: normaliseWirePath(change.path),
+				options: { meta: {
+					deviceId: change.device_id,
+					mtime: change.mtime,
+					...change.old_cid ? { ifMatch: change.old_cid } : {}
+				} }
+			})));
+		} catch (e) {
+			if (e instanceof BatchUnsupportedError) return {
+				consumed: [],
+				tailSkipped: false,
+				fallback: true
+			};
+			if (e instanceof BatchOverBudgetError) {
+				if (chunk.length === 1) {
+					await this.pushOne(chunk[0].change);
+					return {
+						consumed: [{
+							seq: chunk[0].change.seq,
+							counted: true
+						}],
+						tailSkipped: false,
+						fallback: false
+					};
+				}
+				const mid = Math.ceil(chunk.length / 2);
+				const left = await this.sendPushChunk(chunk.slice(0, mid));
+				if (left.fallback || left.tailSkipped || left.error) return left;
+				const right = await this.sendPushChunk(chunk.slice(mid));
+				return {
+					consumed: [...left.consumed, ...right.consumed],
+					tailSkipped: right.tailSkipped,
+					fallback: right.fallback,
+					error: right.error
+				};
+			}
+			throw e;
+		}
+		if (!Array.isArray(result.results) || result.results.length !== chunk.length) throw new Error(`SyncEngine.push: batch results length ${result.results?.length ?? "?"} != chunk length ${chunk.length} (protocol violation)`);
+		const consumed = [];
+		for (let i = 0; i < result.results.length; i++) {
+			const r = result.results[i];
+			const change = chunk[i].change;
+			if (r.success) {
+				consumed.push({
+					seq: change.seq,
+					counted: true
+				});
+				continue;
+			}
+			if (r.code === "BATCH_TAIL_SKIPPED") return {
+				consumed,
+				tailSkipped: true,
+				fallback: false
+			};
+			if (r.conflict) {
+				await this.resolveConflict(change, r.conflict);
+				consumed.push({
+					seq: change.seq,
+					counted: true
+				});
+				continue;
+			}
+			return {
+				consumed,
+				tailSkipped: false,
+				fallback: false,
+				error: /* @__PURE__ */ new Error(`SyncEngine.push: batch entry failed at seq=${change.seq} path=${change.path}: ${r.error ?? r.code ?? r.status}`)
+			};
+		}
+		return {
+			consumed,
+			tailSkipped: false,
+			fallback: false
+		};
+	}
+	/**
+	* Decide whether THIS push routes large put-chunks through the upload plane
+	* (design §6.1 / decision 4). True only when (a) the adapter has the
+	* prepare/commit/uploadObject surface, (b) the server advertises grant
+	* capability (memoized per instance — Node/old-server/signer-less → false →
+	* never), and (c) the put backlog meets the conservative threshold
+	* (≥ MIN_ENTRIES puts, or ≥ MIN_BYTES) via a cheap bounded peek.
+	*/
+	async shouldUseUploadPlane(cursor) {
+		if (typeof this.cloudAfs.prepareUpload !== "function" || typeof this.cloudAfs.commitUpload !== "function" || typeof this.cloudAfs.uploadObject !== "function") return false;
+		if (this.uploadPlaneCapable === null) try {
+			this.uploadPlaneCapable = typeof this.cloudAfs.uploadGrantCapability === "function" ? await this.cloudAfs.uploadGrantCapability() : false;
+		} catch {
+			this.uploadPlaneCapable = false;
+		}
+		if (!this.uploadPlaneCapable) return false;
+		const puts = (await this.localChangelog.getUnpushed(cursor, AFS_DID_SPACE_UPLOAD_MIN_ENTRIES + 1)).filter((c) => c.op === "put");
+		if (puts.length >= AFS_DID_SPACE_UPLOAD_MIN_ENTRIES) return true;
+		return puts.reduce((sum, c) => sum + (c.size ?? 0), 0) >= AFS_DID_SPACE_UPLOAD_MIN_BYTES;
+	}
+	/**
+	* Upload-plane transport for one put chunk (design §6.1 / §8). Mirrors a
+	* `batchWrite` call but moves content OUT of the worker:
+	*   1. prepare-upload (reuses each row's local `cid` — never re-hashed);
+	*   2. out-of-band PUT each grant (bounded concurrency);
+	*   3. commit-upload ONLY the entries whose PUT returned 200 (commit-after-
+	*      200, decision 2 — the sole dangling defense). PUT-failed entries get a
+	*      per-entry failure so the cursor pins there for retry next round.
+	* Returns the SAME `RpcBatchResult` shape `sendPushChunk` consumes. If a grant
+	* is unexpectedly absent (capability was advertised but a row got none), bail
+	* via `BatchUnsupportedError` → the engine reverts to the legacy path.
+	*/
+	/**
+	* Application metadata for a push entry, derived from its own bytes via the
+	* optional provider hook (did-space-metadata G3). Returns undefined when the
+	* provider exposes none — so the engine emits no metadata and the wire stays
+	* pre-G3 byte-identical.
+	*/
+	async readAppMeta(path, bytes) {
+		const read = this.provider.readApplicationMetadata;
+		if (!read) return void 0;
+		try {
+			const meta = await read.call(this.provider, path, bytes);
+			return meta && Object.keys(meta).length > 0 ? meta : void 0;
+		} catch {
+			return;
+		}
+	}
+	async uploadPlaneWriteChunk(chunk) {
+		const cids = await Promise.all(chunk.map(({ bytes }) => computeCID(bytes)));
+		const toEntry = (change, size, cid) => {
+			const wirePath = normaliseWirePath(change.path);
+			const mimeType = detectMimeType(wirePath);
+			return {
+				path: wirePath,
+				cid,
+				size,
+				...mimeType ? { mimeType } : {},
+				...change.old_cid ? { ifMatch: change.old_cid } : {},
+				deviceId: change.device_id,
+				mtime: change.mtime
+			};
+		};
+		const inlineCandidate = (bytes, mimeType) => {
+			if (bytes.length > DEFAULT_INLINE_THRESHOLD) return void 0;
+			return decodeInlineText(bytes, mimeType) ?? void 0;
+		};
+		const prep = await this.cloudAfs.prepareUpload(chunk.map(({ change, bytes }, i) => toEntry(change, bytes.length, cids[i])));
+		if (prep.entries.length !== chunk.length || prep.entries.some((e) => !e.grant)) throw new BatchUnsupportedError();
+		const putOk = new Array(chunk.length).fill(false);
+		await this.boundedAll(chunk.length, AFS_DID_SPACE_UPLOAD_PUT_CONCURRENCY, async (i) => {
+			putOk[i] = await this.cloudAfs.uploadObject(prep.entries[i].grant, chunk[i].bytes) === 200;
+		});
+		const commitEntries = [];
+		const commitIndex = /* @__PURE__ */ new Map();
+		for (const [i, { change, bytes }] of chunk.entries()) {
+			if (!putOk[i]) continue;
+			commitIndex.set(i, commitEntries.length);
+			const base = toEntry(change, bytes.length, cids[i]);
+			const content = inlineCandidate(bytes, base.mimeType);
+			const metadata = await this.readAppMeta(change.path, bytes);
+			commitEntries.push({
+				...base,
+				...content !== void 0 ? { content } : {},
+				...metadata ? { metadata } : {}
+			});
+		}
+		const commit = commitEntries.length > 0 ? await this.cloudAfs.commitUpload(prep.sessionId, commitEntries) : {
+			results: [],
+			succeeded: 0,
+			failed: 0
+		};
+		const results = chunk.map(({ change }, i) => {
+			const ci = commitIndex.get(i);
+			if (ci !== void 0) return commit.results[ci] ?? {
+				path: normaliseWirePath(change.path),
+				success: false,
+				status: 500,
+				error: "missing commit result"
+			};
+			return {
+				path: normaliseWirePath(change.path),
+				success: false,
+				status: 503,
+				code: "UPLOAD_PUT_FAILED",
+				error: "presigned PUT did not return 200"
+			};
+		});
+		let succeeded = 0;
+		for (const r of results) if (r.success) succeeded++;
+		return {
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	/** Run `fn(0..n-1)` with at most `limit` in flight (push-side PUT fan-out). */
+	async boundedAll(n, limit, fn) {
+		let next = 0;
+		const workers = Array.from({ length: Math.min(limit, n) }, async () => {
+			while (next < n) await fn(next++);
+		});
+		await Promise.all(workers);
+	}
+	/**
+	* Upload a single change row. Split from push() so both the normal
+	* loop and future retry paths can call it.
+	*
+	* On 409 conflict, delegates to {@link resolveConflict}, which decides
+	* by LWW + tiebreak whether to force-overwrite the cloud or adopt the
+	* cloud's version locally. Either way, after resolveConflict returns,
+	* the row is considered "handled" and the push cursor advances past it.
+	*/
+	async pushOne(change) {
+		const wirePath = normaliseWirePath(change.path);
+		if (change.op === "put") {
+			if (change.cid === null) throw new Error(`SyncEngine.push: put row with null cid at seq=${change.seq} path=${change.path}`);
+			const bytes = await this.provider.readBytes(change.path);
+			if (bytes === null) return;
+			const appMeta = await this.readAppMeta(change.path, bytes);
+			try {
+				await this.cloudAfs.write(wirePath, {
+					content: bytes,
+					meta: {
+						...appMeta,
+						extra: {
+							contentCid: change.cid,
+							deviceId: change.device_id,
+							mtime: change.mtime,
+							ifMatch: change.old_cid ?? void 0
+						}
+					}
+				});
+			} catch (e) {
+				if (e instanceof AFSConflictError) {
+					await this.resolveConflict(change, {
+						currentCid: e.currentCid,
+						currentMtime: e.currentMtime,
+						currentDeviceId: e.currentDeviceId
+					});
+					return;
+				}
+				throw e;
+			}
+		} else if (change.op === "delete") try {
+			await this.cloudAfs.delete(wirePath, { meta: {
+				deviceId: change.device_id,
+				mtime: change.mtime,
+				ifMatch: change.old_cid ?? void 0
+			} });
+		} catch (e) {
+			if (e instanceof AFSConflictError) {
+				await this.resolveConflict(change, {
+					currentCid: e.currentCid,
+					currentMtime: e.currentMtime,
+					currentDeviceId: e.currentDeviceId
+				});
+				return;
+			}
+			throw e;
+		}
+		else throw new Error(`SyncEngine.push: unexpected op=${change.op} at seq=${change.seq}`);
+	}
+	/**
+	* Resolve a push-side 409 conflict via Last-Write-Wins (LWW).
+	*
+	* Decision matrix (see `native-sync-design.md` G11 for the full 7-row
+	* matrix and rationale):
+	*
+	*   1. `localMtime > cloudMtime` → **local wins**: force-overwrite the
+	*      cloud (resend without `If-Match`). The server still validates
+	*      `X-Content-CID`, so a corrupted upload still fails.
+	*
+	*   2. `localMtime < cloudMtime` → **cloud wins**: adopt the cloud's
+	*      version locally via `provider.internalWrite/Delete` with the
+	*      ORIGIN deviceId from the conflict response. Echo-loop Layer II.
+	*
+	*   3. `localMtime === cloudMtime` → **tiebreak by CID lexicographic
+	*      order** (round 7 decision). The larger cid wins. delete ops
+	*      treat their cid as the empty string, so a `put` with non-empty
+	*      cid always beats a `delete` at the same mtime.
+	*
+	* Special cases handled here:
+	*   - delete vs delete (both null cid) → idempotent no-op (defensive;
+	*     in practice the server's delete handler turns DELETE 404 into
+	*     success and the conflict never reaches here).
+	*   - same mtime + same cid → idempotent natural convergence (the
+	*     local-wins path is taken but the resend produces the same cid
+	*     the cloud already has).
+	*
+	* mtime skew defense: G5.c (Task 3.3) rejects writes with
+	* `mtime > serverNow + 5min` at the header layer, so a single device
+	* with a wildly bad clock cannot poison the LWW decision globally.
+	*/
+	async resolveConflict(change, resp) {
+		if (resp.currentMtime === null) throw new ConflictResolutionError(change, "missing currentMtime in conflict response");
+		const localMtime = change.mtime;
+		const cloudMtime = resp.currentMtime;
+		if (change.op === "delete" && resp.currentCid === null) return;
+		const localCid = change.cid ?? "";
+		const cloudCid = resp.currentCid ?? "";
+		if (localMtime > cloudMtime || localMtime === cloudMtime && localCid > cloudCid) {
+			const wirePath = normaliseWirePath(change.path);
+			if (change.op === "put") {
+				const bytes = await this.provider.readBytes(change.path);
+				if (bytes === null) return;
+				const appMeta = await this.readAppMeta(change.path, bytes);
+				await this.cloudAfs.write(wirePath, {
+					content: bytes,
+					meta: {
+						...appMeta,
+						extra: {
+							contentCid: change.cid,
+							deviceId: change.device_id,
+							mtime: change.mtime
+						}
+					}
+				});
+			} else await this.cloudAfs.delete(wirePath, { meta: {
+				deviceId: change.device_id,
+				mtime: change.mtime
+			} });
+		} else {
+			const wirePath = normaliseWirePath(change.path);
+			const originDeviceId = resp.currentDeviceId ?? "unknown";
+			if (resp.currentCid !== null) {
+				let bytes;
+				try {
+					bytes = (await this.cloudAfs.read(`/.objects/${resp.currentCid}`)).data?.content;
+				} catch (e) {
+					if (e instanceof Error && e.name === "AbortError") throw e;
+					throw new CurrentObjectMissingError(wirePath, resp.currentCid, "conflict");
+				}
+				if (bytes === void 0) throw new CurrentObjectMissingError(wirePath, resp.currentCid, "conflict");
+				await this.provider.internalWrite(wirePath, {
+					content: bytes,
+					deviceId: originDeviceId,
+					mtime: cloudMtime,
+					metadata: await this.readAppMeta(wirePath, bytes)
+				});
+			} else await this.provider.internalDelete(wirePath, {
+				deviceId: originDeviceId,
+				mtime: cloudMtime
+			});
+		}
+	}
+	/**
+	* Fetch and apply incoming changes from the cloud. Loops until either
+	* the server reports `hasMore === false`, the deadline passes, or the
+	* abort signal fires. On 409 Compacted, delegates to fullResync().
+	*
+	* Apply order: sequential in seq order within a batch (SQLite
+	* integrity + single origin-deviceId per row). Content fetching is
+	* parallel up to `PULL_FETCH_CONCURRENCY`.
+	*/
+	async pull(opts) {
+		const initialCloudSeq = (await this.syncStateStore.load()).cloudSeq;
+		let cloudCursor = initialCloudSeq > 0 ? String(initialCloudSeq) : void 0;
+		let pulled = 0;
+		try {
+			while (true) {
+				if (opts.signal?.aborted) return {
+					pulled,
+					fullResynced: false
+				};
+				if (Date.now() >= opts.deadline) return {
+					pulled,
+					fullResynced: false
+				};
+				let listResult;
+				try {
+					listResult = await this.cloudAfs.list(".changelog", {
+						cursor: cloudCursor ?? "0",
+						limit: PULL_BATCH_LIMIT
+					});
+				} catch (e) {
+					if (e instanceof AFSCompactedError) {
+						const r = await this.fullResync({
+							signal: opts.signal,
+							deadline: opts.deadline
+						});
+						return {
+							pulled: pulled + r.pulled,
+							fullResynced: true
+						};
+					}
+					throw e;
+				}
+				const allChanges = listResult.data.map((entry) => {
+					const extra = entry.meta?.extra ?? {};
+					return {
+						seq: Number(extra.seq ?? 0),
+						originalPath: String(extra.originalPath ?? ""),
+						op: String(extra.op ?? ""),
+						cid: typeof extra.cid === "string" ? extra.cid : null,
+						oldCid: typeof extra.oldCid === "string" ? extra.oldCid : null,
+						size: typeof extra.size === "number" ? extra.size : null,
+						mtime: Number(extra.mtime ?? 0),
+						deviceId: String(extra.deviceId ?? "")
+					};
+				});
+				const hasMore = listResult.meta?.hasMore ?? false;
+				for (let i = 1; i < allChanges.length; i++) if (allChanges[i].seq <= allChanges[i - 1].seq) throw new Error("SyncEngine.pull: cloud returned out-of-order changes");
+				const foreignChanges = allChanges.filter((c) => c.deviceId !== this.selfDeviceId);
+				const putRows = foreignChanges.filter((c) => c.op === "put" && c.cid !== null);
+				const cidMap = /* @__PURE__ */ new Map();
+				await this.fetchContent(putRows, cidMap, opts);
+				const lastCidForPath = /* @__PURE__ */ new Map();
+				for (const c of foreignChanges) lastCidForPath.set(normaliseAfsPath(c.originalPath), c.op === "put" ? c.cid : null);
+				for (const change of foreignChanges) {
+					if (opts.signal?.aborted) return {
+						pulled,
+						fullResynced: false
+					};
+					const wirePath = normaliseAfsPath(change.originalPath);
+					if (change.op === "put") {
+						if (change.cid === null) continue;
+						const bytes = cidMap.get(change.cid);
+						if (bytes === void 0) {
+							if (classifyMissingObject(wirePath, change.cid, lastCidForPath) === "current") throw new CurrentObjectMissingError(wirePath, change.cid, "latest-put");
+							log.warn(`SyncEngine.pull: skipping superseded seq=${change.seq} path=${wirePath} (cid ${change.cid} reclaimed)`);
+							cloudCursor = String(change.seq);
+							continue;
+						}
+						await this.provider.internalWrite(wirePath, {
+							content: bytes,
+							deviceId: change.deviceId,
+							mtime: change.mtime,
+							metadata: await this.readAppMeta(wirePath, bytes)
+						});
+					} else if (change.op === "delete") await this.provider.internalDelete(wirePath, {
+						deviceId: change.deviceId,
+						mtime: change.mtime
+					});
+					cloudCursor = String(change.seq);
+					pulled += 1;
+				}
+				if (foreignChanges.length === 0 && allChanges.length > 0) cloudCursor = listResult.meta?.cursor ?? cloudCursor;
+				if (!hasMore) break;
+			}
+		} finally {
+			if (cloudCursor !== void 0) {
+				const numericCursor = Number(cloudCursor);
+				if (Number.isFinite(numericCursor) && numericCursor > 0) await this.syncStateStore.save({ cloudSeq: numericCursor });
+			}
+		}
+		return {
+			pulled,
+			fullResynced: false
+		};
+	}
+	/**
+	* Fetch content bytes for a batch of `put` rows in parallel, bounded
+	* by {@link PULL_FETCH_CONCURRENCY}. Results land in `cidMap`;
+	* individual fetch failures (404, cid mismatch) are logged and the
+	* offending cid is omitted so the caller's serial apply pass can
+	* detect the gap and skip.
+	*/
+	/**
+	* Content fetch dispatcher (P4): chunked `batchRead(optional:true)` when
+	* the adapter has it (≤20 cids and ≤2MB ESTIMATED bytes per chunk — size
+	* from the changelog rows), single concurrent reads otherwise. Tail-
+	* skipped cids are simply re-queued for the next chunk (they were never
+	* read); `missing:true` cids stay out of the map so the apply loop's
+	* §4.7.2 current/superseded classification is untouched.
+	*/
+	async fetchContent(rows, cidMap, opts) {
+		const planeSatisfied = await this.fillBytesViaDownloadPlane(rows.filter((r) => r.cid !== null), cidMap, opts);
+		const remaining = planeSatisfied.size === 0 ? rows : rows.filter((r) => r.cid === null || !planeSatisfied.has(r.cid));
+		if (this.batchFallback || typeof this.cloudAfs.batchRead !== "function") return this.fetchContentConcurrent(remaining, cidMap, opts);
+		const sizeByCid = /* @__PURE__ */ new Map();
+		for (const r of remaining) if (r.cid !== null && !sizeByCid.has(r.cid)) sizeByCid.set(r.cid, r.size ?? 0);
+		const queue = Array.from(sizeByCid.keys());
+		while (queue.length > 0) {
+			if (opts.signal?.aborted) return;
+			const chunk = [];
+			let estBytes = 0;
+			while (queue.length > 0 && chunk.length < BATCH_READ_MAX_ENTRIES) {
+				const cid = queue[0];
+				const est = sizeByCid.get(cid) ?? 0;
+				if (chunk.length > 0 && estBytes + est > BATCH_READ_MAX_BYTES) break;
+				chunk.push(cid);
+				estBytes += est;
+				queue.shift();
+			}
+			let result;
+			try {
+				result = await this.cloudAfs.batchRead(chunk.map((cid) => ({
+					path: `/.objects/${cid}`,
+					optional: true
+				})));
+			} catch (e) {
+				if (e instanceof BatchUnsupportedError) {
+					this.batchFallback = true;
+					const remaining$1 = [...chunk, ...queue].map((cid) => ({
+						cid,
+						size: sizeByCid.get(cid) ?? null
+					}));
+					return this.fetchContentConcurrent(remaining$1, cidMap, opts);
+				}
+				if (e instanceof BatchOverBudgetError && chunk.length > 1) {
+					const half = Math.ceil(chunk.length / 2);
+					for (const cid of chunk.slice(0, half)) await this.fetchOneObject(cid, cidMap, opts);
+					queue.unshift(...chunk.slice(half));
+					continue;
+				}
+				throw e;
+			}
+			let skippedTail = false;
+			for (let i = 0; i < result.results.length; i++) {
+				const r = result.results[i];
+				const cid = chunk[i];
+				if (r.success) {
+					const content = r.data?.content;
+					const bytes = content instanceof Uint8Array ? content : typeof content === "string" ? new TextEncoder().encode(content) : void 0;
+					if (bytes) {
+						const actualCid = await computeCID(bytes);
+						if (actualCid !== cid) log.warn(`SyncEngine.pull: cid mismatch for ${cid}: got ${actualCid}`);
+						else cidMap.set(cid, bytes);
+					}
+					continue;
+				}
+				if (r.code === "BATCH_TAIL_SKIPPED") {
+					if (i === 0) for (const c of chunk.slice(i)) await this.fetchOneObject(c, cidMap, opts);
+					else queue.unshift(...chunk.slice(i));
+					skippedTail = true;
+					break;
+				}
+			}
+			if (skippedTail) continue;
+		}
+	}
+	/** Single `.objects/{cid}` read with the same soft-failure semantics. */
+	async fetchOneObject(cid, cidMap, opts) {
+		if (opts.signal?.aborted) return;
+		try {
+			const bytes = (await this.cloudAfs.read(`/.objects/${cid}`)).data?.content;
+			if (bytes) {
+				const actualCid = await computeCID(bytes);
+				if (actualCid === cid) cidMap.set(cid, bytes);
+				else log.warn(`SyncEngine.pull: cid mismatch for ${cid}: got ${actualCid}`);
+			}
+		} catch (e) {
+			if (e instanceof Error && e.name === "AbortError") throw e;
+			log.warn(`SyncEngine.pull: read .objects/${cid} failed: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	async fetchContentConcurrent(rows, cidMap, opts) {
+		const uniqueCids = /* @__PURE__ */ new Set();
+		for (const r of rows) if (r.cid !== null) uniqueCids.add(r.cid);
+		const cids = Array.from(uniqueCids);
+		let index = 0;
+		const worker = async () => {
+			while (index < cids.length) {
+				if (opts.signal?.aborted) return;
+				const cid = cids[index++];
+				try {
+					const bytes = (await this.cloudAfs.read(`/.objects/${cid}`)).data?.content;
+					if (bytes) {
+						const actualCid = await computeCID(bytes);
+						if (actualCid !== cid) log.warn(`SyncEngine.pull: cid mismatch for ${cid}: got ${actualCid}`);
+						else cidMap.set(cid, bytes);
+					}
+				} catch (e) {
+					if (e instanceof Error && e.name === "AbortError") throw e;
+					log.warn(`SyncEngine.pull: read .objects/${cid} failed: ${e instanceof Error ? e.message : String(e)}`);
+				}
+			}
+		};
+		const concurrency = Math.max(1, Math.min(PULL_FETCH_CONCURRENCY, cids.length));
+		const workers = [];
+		for (let i = 0; i < concurrency; i++) workers.push(worker());
+		await Promise.all(workers);
+	}
+	/**
+	* Whether the download plane can be used RIGHT NOW: the adapter speaks the
+	* methods, the server advertised the INDEPENDENT capability (memoized per
+	* instance, §7.3), and this session hasn't latched a 401/403 fallback.
+	*/
+	async downloadPlaneAvailable() {
+		if (this.downloadFallback) return false;
+		if (typeof this.cloudAfs.prepareDownload !== "function" || typeof this.cloudAfs.downloadObject !== "function") return false;
+		if (this.downloadPlaneCapable === null) try {
+			this.downloadPlaneCapable = typeof this.cloudAfs.downloadGrantCapability === "function" ? await this.cloudAfs.downloadGrantCapability() : false;
+		} catch {
+			this.downloadPlaneCapable = false;
+		}
+		return this.downloadPlaneCapable === true;
+	}
+	/**
+	* Fetch LARGE objects (size ≥ {@link DOWNLOAD_PLANE_MIN_BYTES}) via the
+	* download plane — prepare-download → bounded-concurrency direct R2 GET →
+	* computeCID → `bytesMap`. Bytes leave R2 directly (never through the worker /
+	* base64). Returns the SET of cids it satisfied; the caller routes the rest
+	* (small objects, Node `grant:null`, forbidden, 404, post-fallback) through
+	* batchRead — so a true miss still raises the existing fail-closed path.
+	*
+	* fail-closed: a byte string whose `computeCID` ≠ the requested cid (R2 served
+	* tampered/other bytes) is DROPPED, never written (§8.1). A 401/403 latches
+	* `downloadFallback` for the whole session — at most one wall-bang (§7.3).
+	*/
+	async fillBytesViaDownloadPlane(entries, bytesMap, opts) {
+		const satisfied = /* @__PURE__ */ new Set();
+		if (!await this.downloadPlaneAvailable()) return satisfied;
+		const bigCids = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const e of entries) {
+			if ((e.size ?? 0) < DOWNLOAD_PLANE_MIN_BYTES) continue;
+			if (seen.has(e.cid)) continue;
+			seen.add(e.cid);
+			bigCids.push(e.cid);
+		}
+		if (bigCids.length === 0) return satisfied;
+		for (let i = 0; i < bigCids.length; i += DOWNLOAD_MAX_ENTRIES) {
+			if (opts.signal?.aborted || this.downloadFallback) break;
+			const batch = bigCids.slice(i, i + DOWNLOAD_MAX_ENTRIES);
+			let prep;
+			try {
+				prep = await this.cloudAfs.prepareDownload(batch.map((cid) => ({ cid })));
+			} catch (e) {
+				if (e instanceof BatchUnsupportedError) {
+					this.downloadPlaneCapable = false;
+					return satisfied;
+				}
+				throw e;
+			}
+			const grantByCid = /* @__PURE__ */ new Map();
+			for (const pe of prep.entries) if (pe.status === "ok" && pe.grant) grantByCid.set(pe.cid, pe.grant);
+			const grantedCids = batch.filter((c) => grantByCid.has(c));
+			await this.boundedAll(grantedCids.length, this.downloadGetConcurrency, async (j) => {
+				if (opts.signal?.aborted || this.downloadFallback) return;
+				const cid = grantedCids[j];
+				try {
+					const bytes = await this.cloudAfs.downloadObject(grantByCid.get(cid));
+					const actualCid = await computeCID(bytes);
+					if (actualCid === cid) {
+						bytesMap.set(cid, bytes);
+						satisfied.add(cid);
+					} else log.warn(`SyncEngine.pull: download-plane cid mismatch for ${cid}: got ${actualCid}`);
+				} catch (e) {
+					if (e instanceof DownloadForbiddenError) {
+						this.downloadFallback = true;
+						return;
+					}
+					if (e instanceof Error && e.name === "AbortError") throw e;
+				}
+			});
+		}
+		return satisfied;
+	}
+	/**
+	* First-sync / post-compaction recovery path. Fetches the full manifest
+	* and reconciles the local store against it, skipping paths the local
+	* changelog still has unpushed changes for (invariant I1).
+	*
+	* ORDERING IS CRITICAL — `pendingPaths` MUST be collected BEFORE the
+	* manifest fetch so a delete written between pendingPaths collection
+	* and apply does not get reverted by the manifest restoration.
+	*/
+	async fullResync(opts) {
+		const unpushed = await this.localChangelog.getUnpushed(0, Number.MAX_SAFE_INTEGER);
+		const pendingPaths = new Set(unpushed.map((c) => c.path));
+		if (opts.signal?.aborted) return { pulled: 0 };
+		const manifestResult = await this.cloudAfs.list("", { maxDepth: -1 });
+		if (manifestResult.meta?.truncated === true) throw new ManifestTooLargeError();
+		const manifestEntries = manifestResult.data.map((entry) => {
+			const extra = entry.meta?.extra ?? {};
+			const cid = typeof extra.cid === "string" ? extra.cid : typeof entry.meta?.cid === "string" ? entry.meta.cid : "";
+			return {
+				path: entry.path,
+				cid,
+				mtime: typeof extra.mtime === "number" ? extra.mtime : 0,
+				size: typeof entry.meta?.size === "number" ? entry.meta.size : 0
+			};
+		});
+		const manifestSeq = Number(manifestResult.meta?.cursor ?? 0);
+		const manifestPathSet = /* @__PURE__ */ new Set();
+		for (const e of manifestEntries) manifestPathSet.add(normaliseToLocalPath(e.path));
+		let pulled = 0;
+		const applicable = manifestEntries.filter((entry) => !pendingPaths.has(normaliseToLocalPath(entry.path)));
+		const planeBytes = /* @__PURE__ */ new Map();
+		const planeSatisfied = await this.fillBytesViaDownloadPlane(applicable.map((e) => ({
+			cid: e.cid,
+			size: e.size
+		})), planeBytes, opts);
+		for (const entry of applicable) {
+			if (opts.signal?.aborted) return { pulled };
+			if (Date.now() >= opts.deadline) return { pulled };
+			const bytes = planeBytes.get(entry.cid);
+			if (!bytes) continue;
+			await this.provider.internalWrite(normaliseAfsPath(entry.path), {
+				content: bytes,
+				deviceId: this.selfDeviceId,
+				mtime: entry.mtime,
+				metadata: await this.readAppMeta(normaliseAfsPath(entry.path), bytes)
+			});
+			pulled += 1;
+		}
+		const viaBatch = planeSatisfied.size === 0 ? applicable : applicable.filter((e) => !planeSatisfied.has(e.cid));
+		const useBatchRead = () => !this.batchFallback && typeof this.cloudAfs.batchRead === "function";
+		for (let offset = 0; offset < viaBatch.length;) {
+			if (opts.signal?.aborted) return { pulled };
+			if (Date.now() >= opts.deadline) return { pulled };
+			const chunk = [];
+			while (offset < viaBatch.length && chunk.length < (useBatchRead() ? BATCH_READ_MAX_ENTRIES : 1)) {
+				chunk.push(viaBatch[offset]);
+				offset++;
+			}
+			const bytesByCid = /* @__PURE__ */ new Map();
+			if (useBatchRead() && chunk.length > 0) {
+				let result;
+				try {
+					result = await this.cloudAfs.batchRead(chunk.map((entry) => ({
+						path: `/.objects/${entry.cid}`,
+						optional: true
+					})));
+				} catch (e) {
+					if (e instanceof BatchUnsupportedError) {
+						this.batchFallback = true;
+						offset -= chunk.length;
+						continue;
+					}
+					throw e;
+				}
+				for (let i = 0; i < result.results.length; i++) {
+					const r = result.results[i];
+					const entry = chunk[i];
+					if (r.code === "BATCH_TAIL_SKIPPED") {
+						offset -= chunk.length - i;
+						break;
+					}
+					if (!r.success) throw new CurrentObjectMissingError(entry.path, entry.cid, "manifest");
+					const content = r.data?.content;
+					const bytes = content instanceof Uint8Array ? content : typeof content === "string" ? new TextEncoder().encode(content) : void 0;
+					if (!bytes) throw new CurrentObjectMissingError(entry.path, entry.cid, "manifest");
+					bytesByCid.set(entry.cid, bytes);
+				}
+			} else for (const entry of chunk) try {
+				const content = (await this.cloudAfs.read(`/.objects/${entry.cid}`)).data?.content;
+				if (!content) throw new CurrentObjectMissingError(entry.path, entry.cid, "manifest");
+				bytesByCid.set(entry.cid, content);
+			} catch (e) {
+				if (e instanceof CurrentObjectMissingError) throw e;
+				if (e instanceof Error && e.name === "AbortError") throw e;
+				throw new CurrentObjectMissingError(entry.path, entry.cid, "manifest");
+			}
+			for (const entry of chunk) {
+				if (opts.signal?.aborted) return { pulled };
+				const bytes = bytesByCid.get(entry.cid);
+				if (!bytes) continue;
+				const wirePath = normaliseAfsPath(entry.path);
+				await this.provider.internalWrite(wirePath, {
+					content: bytes,
+					deviceId: this.selfDeviceId,
+					mtime: entry.mtime,
+					metadata: await this.readAppMeta(wirePath, bytes)
+				});
+				pulled += 1;
+			}
+		}
+		if (!opts.signal?.aborted) {
+			const localPaths = await this.provider.listAllPaths();
+			for (const p of localPaths) {
+				if (opts.signal?.aborted) break;
+				if (manifestPathSet.has(p)) continue;
+				if (pendingPaths.has(p)) continue;
+				await this.provider.internalDelete(normaliseAfsPath(p), { deviceId: this.selfDeviceId });
+			}
+		}
+		if (manifestSeq > 0) await this.syncStateStore.save({ cloudSeq: manifestSeq });
+		return { pulled };
+	}
+};
+/**
+* Normalise an internal changelog path (no leading slash) to the AFS
+* wire path used by PUT/DELETE endpoints (always starts with `/`).
+*/
+function normaliseWirePath(path) {
+	return path.startsWith("/") ? path : `/${path}`;
+}
+/**
+* Same as {@link normaliseWirePath} but applied to paths that may come
+* from either the manifest (no leading slash) or a `.changelog` row's
+* `meta.extra.originalPath` (no leading slash either — the server stores
+* without leading slash). Always returns a `/`-prefixed path suitable
+* for `provider.internalWrite/Delete`.
+*/
+function normaliseAfsPath(path) {
+	return path.startsWith("/") ? path : `/${path}`;
+}
+/**
+* Inverse of {@link normaliseAfsPath}: strip the leading slash so the
+* path matches the `entries.path` / `changelog.path` column shape
+* (used by pendingPaths lookups).
+*/
+function normaliseToLocalPath(path) {
+	return path.startsWith("/") ? path.slice(1) : path;
+}
+
+//#endregion
+export { ConflictResolutionError, CurrentObjectMissingError, PULL_BATCH_LIMIT, PULL_FETCH_CONCURRENCY, PUSH_BATCH_LIMIT, PUSH_PROGRESS_FLUSH_INTERVAL, SYNC_WALL_CLOCK_BUDGET_MS, SyncEngine, classifyMissingObject };
+//# sourceMappingURL=sync-engine.mjs.map