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

package/dist/remote-afs.cjs

@@ -0,0 +1,681 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_cid = require('./cid.cjs');
+require('./mime-utils.cjs');
+let _aigne_afs = require("@aigne/afs");
+let ufo = require("ufo");
+let _aigne_afs_provider_utils = require("@aigne/afs-provider-utils");
+
+//#region src/remote-afs.ts
+/**
+* Loopback hosts that may be served over plain http (no HTTPS requirement).
+* Covers `localhost`, the reserved `*.localhost` subdomains (RFC 6761 — always
+* loopback, e.g. `aside.localhost:8787` for local multi-app dev where the
+* subdomain selects the blocklet), and the IPv4/IPv6 loopback literals.
+*/
+function isLoopbackHost(hostname) {
+	const h = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	return h === "localhost" || h.endsWith(".localhost") || h === "127.0.0.1" || h === "::1";
+}
+var RemoteUserSpaceAFS = class {
+	name = "remote-user-space";
+	baseUrl;
+	token;
+	constructor(options) {
+		const url = new URL(options.baseUrl);
+		if (url.protocol !== "https:" && !isLoopbackHost(url.hostname)) throw new Error(`HTTPS required for remote connections (got ${url.protocol}//${url.hostname})`);
+		this.baseUrl = options.baseUrl;
+		this.token = options.token;
+	}
+	apiUrl(path, params) {
+		const url = (0, ufo.joinURL)(this.baseUrl, "/api/space/", (0, ufo.encodePath)(path));
+		if (!params) return url;
+		return `${url}?${new URLSearchParams(params).toString()}`;
+	}
+	headers() {
+		return { Authorization: `Bearer ${this.token}` };
+	}
+	async handleResponse(res, path) {
+		if (res.ok) return res.json();
+		if (res.status === 404) throw new _aigne_afs.AFSNotFoundError(path);
+		if (res.status === 401) throw new Error("Authentication failed: check your access token");
+		if (res.status === 409) await this.handle409(res, path);
+		const errorMsg = await this.parseErrorBody(res);
+		throw new Error(`Remote AFS error at ${path}: ${errorMsg}`);
+	}
+	/**
+	* Parse a 409 response body and throw the appropriate AFS error:
+	*   - `{ error: "if_match_failed", currentCid, currentMtime, currentDeviceId }` → AFSConflictError
+	*   - `{ requireFullResync: true, compactedBelowSeq }` → AFSCompactedError
+	*   - Otherwise → generic error
+	*/
+	async handle409(res, path) {
+		let body;
+		try {
+			body = await res.json();
+		} catch {
+			throw new Error(`Remote AFS 409 at ${path}`);
+		}
+		if (body.requireFullResync === true) {
+			const seq = typeof body.compactedBelowSeq === "number" ? body.compactedBelowSeq : 0;
+			throw new _aigne_afs.AFSCompactedError(path, String(seq));
+		}
+		if (body.code === "AFS_CONFLICT" || body.error === "if_match_failed" || "currentCid" in body) throw new _aigne_afs.AFSConflictError(path, {
+			cid: typeof body.currentCid === "string" ? body.currentCid : null,
+			mtime: typeof body.currentMtime === "number" ? body.currentMtime : null,
+			deviceId: typeof body.currentDeviceId === "string" ? body.currentDeviceId : null
+		});
+		throw new Error(`Remote AFS 409 at ${path}: ${JSON.stringify(body)}`);
+	}
+	async parseErrorBody(res) {
+		try {
+			return (await res.json()).error || `HTTP ${res.status}`;
+		} catch {
+			return `HTTP ${res.status}`;
+		}
+	}
+	async list(path, options) {
+		const params = { op: "list" };
+		const normPath = path.startsWith("/") ? path.slice(1) : path;
+		const isChangelog = normPath === ".changelog" || normPath.startsWith(".changelog/");
+		if (options?.maxDepth === -1) {
+			if (isChangelog) throw new _aigne_afs.AFSValidationError(".changelog path does not support maxDepth=-1 (changelog uses cursor-based incremental access)");
+			if (options.limit !== void 0 && Number.isFinite(options.limit) || options.offset !== void 0 && Number.isFinite(options.offset) || options.cursor !== void 0) throw new _aigne_afs.AFSValidationError("list with maxDepth=-1 cannot be combined with cursor, limit, or offset");
+		}
+		if (options?.maxDepth !== void 0) params.maxDepth = String(options.maxDepth);
+		if (isChangelog && options?.cursor !== void 0) params.cursor = String(options.cursor);
+		if (!isChangelog) {
+			if (options?.limit !== void 0 && Number.isFinite(options.limit)) params.limit = String(options.limit);
+			if (options?.offset !== void 0 && Number.isFinite(options.offset)) params.offset = String(options.offset);
+		}
+		const res = await fetch(this.apiUrl(path, params), { headers: this.headers() });
+		return this.handleResponse(res, path);
+	}
+	async read(path) {
+		const normPath = path.startsWith("/") ? path.slice(1) : path;
+		if (normPath.startsWith(".objects/")) return this.readObject(path, normPath);
+		const res = await fetch(this.apiUrl(path), { headers: this.headers() });
+		if (!res.ok) return this.handleResponse(res, path);
+		const contentType = res.headers.get("Content-Type") || "";
+		if (!res.headers.has("X-AFS-Kind") && contentType.includes("application/json")) return res.json();
+		const meta = {};
+		const kind = res.headers.get("X-AFS-Kind");
+		const cid = res.headers.get("X-AFS-CID");
+		const size = res.headers.get("X-AFS-Size");
+		const mimeType = res.headers.get("X-AFS-MimeType");
+		const childrenCount = res.headers.get("X-AFS-ChildrenCount");
+		meta.kind = kind || "did-space:file";
+		if (cid) meta.cid = cid;
+		if (size) meta.size = Number(size);
+		if (mimeType) meta.mimeType = mimeType;
+		if (childrenCount != null) meta.childrenCount = Number(childrenCount);
+		const content = (0, _aigne_afs_provider_utils.isTextMime)(mimeType || (contentType.split(";")[0] ?? "").trim() || void 0) ? await res.text() : await res.arrayBuffer();
+		const createdAt = res.headers.get("X-AFS-CreatedAt");
+		const updatedAt = res.headers.get("X-AFS-UpdatedAt");
+		return { data: {
+			id: path,
+			path,
+			content,
+			meta,
+			createdAt: createdAt ? new Date(createdAt) : void 0,
+			updatedAt: updatedAt ? new Date(updatedAt) : void 0
+		} };
+	}
+	/**
+	* Task 1.3: read a content-addressed object by path `.objects/{cid}`.
+	* Calls `GET /api/space/.objects/{cid}`, reads raw bytes, then recomputes
+	* the CID to verify integrity before returning.
+	*/
+	async readObject(path, normPath) {
+		const requestedCid = normPath.slice(9);
+		const res = await fetch(this.apiUrl(path), { headers: this.headers() });
+		if (!res.ok) return this.handleResponse(res, path);
+		const ab = await res.arrayBuffer();
+		const bytes = new Uint8Array(ab);
+		const actualCid = await require_cid.computeCID(bytes);
+		if (actualCid !== requestedCid) throw new Error(`read .objects: CID mismatch (requested ${requestedCid}, got ${actualCid})`);
+		return { data: {
+			id: path,
+			path,
+			content: bytes,
+			meta: {
+				kind: "did-space:object",
+				cid: requestedCid,
+				size: bytes.length
+			}
+		} };
+	}
+	async write(path, payload) {
+		const content = payload.content;
+		const extra = payload.meta?.extra;
+		const extraHeaders = {};
+		if (extra) {
+			if (typeof extra.contentCid === "string") extraHeaders["X-Content-CID"] = extra.contentCid;
+			if (typeof extra.deviceId === "string") extraHeaders["X-Device-Id"] = extra.deviceId;
+			if (typeof extra.mtime === "number") extraHeaders["X-Mtime"] = String(extra.mtime);
+			if (typeof extra.ifMatch === "string") extraHeaders["If-Match"] = extra.ifMatch;
+		}
+		if (content instanceof ArrayBuffer || content instanceof Uint8Array) {
+			const body$1 = content instanceof Uint8Array ? content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength) : content;
+			const res$1 = await fetch(this.apiUrl(path), {
+				method: "PUT",
+				headers: {
+					...this.headers(),
+					"Content-Type": "application/octet-stream",
+					...extraHeaders
+				},
+				body: body$1
+			});
+			return this.handleResponse(res$1, path);
+		}
+		const isString = typeof content === "string";
+		const body = isString ? content : JSON.stringify(content);
+		const mimeType = isString ? "text/plain" : "application/json";
+		const res = await fetch(this.apiUrl(path), {
+			method: "PUT",
+			headers: {
+				...this.headers(),
+				"Content-Type": mimeType,
+				...extraHeaders
+			},
+			body
+		});
+		return this.handleResponse(res, path);
+	}
+	async delete(path, opts) {
+		const meta = opts?.meta;
+		const extraHeaders = {};
+		if (meta) {
+			if (typeof meta.deviceId === "string") extraHeaders["X-Device-Id"] = meta.deviceId;
+			if (typeof meta.mtime === "number") extraHeaders["X-Mtime"] = String(meta.mtime);
+			if (typeof meta.ifMatch === "string") extraHeaders["If-Match"] = meta.ifMatch;
+		}
+		const res = await fetch(this.apiUrl(path), {
+			method: "DELETE",
+			headers: {
+				...this.headers(),
+				...extraHeaders
+			}
+		});
+		return this.handleResponse(res, path);
+	}
+};
+/** Thrown when the server does not support the batch wire ops (old daemon). */
+var BatchUnsupportedError = class extends Error {
+	constructor() {
+		super("server does not support batch wire ops");
+		this.name = "BatchUnsupportedError";
+	}
+};
+/**
+* Envelope-level BATCH_OVER_BUDGET / PAYLOAD_TOO_LARGE — zero entries
+* executed; the engine halves the chunk and retries (design §7.3). MUST NOT
+* trip the capability-fallback memory.
+*/
+var BatchOverBudgetError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BatchOverBudgetError";
+	}
+};
+/**
+* SyncCloudAFS over the afs-rpc wire (`POST /api/afs/rpc`) — the transport
+* the production daemon/worker actually serve (the legacy `/api/space` REST
+* server is gone; `RemoteUserSpaceAFS` above survives only for the
+* export/import CLI against legacy hosts).
+*
+* Sync paths are fragment-root-relative; the wire allowlist admits only
+* `/user/**` mutations, so every path is mapped through `/user` on the way
+* out and stripped on the way back.
+*
+* Batch (P4): `batchWrite`/`batchDelete`/`batchRead` send one wire envelope
+* each (wire-contract §9) and restore per-entry results to the single-op
+* error types (`AFSConflictError` with the triple, `BATCH_TAIL_SKIPPED`
+* passthrough). Capability fallback: the FIRST envelope answered with the
+* old server's exact `Unsupported op 'batch…'` 400 marks this INSTANCE as
+* batch-unsupported (`supportsBatch === false`) and throws
+* {@link BatchUnsupportedError}; the engine then stays on the single-op
+* path for the rest of the instance's life. Any other 400 (e.g.
+* BATCH_OVER_BUDGET) does NOT trip the memory.
+*/
+var RpcUserSpaceAFS = class {
+	name = "rpc-user-space";
+	baseUrl;
+	token;
+	blocklet;
+	sessionId;
+	extraHeaders;
+	/** null = unknown (no batch envelope sent yet); set on first evidence. */
+	batchSupported = null;
+	constructor(options) {
+		const url = new URL(options.baseUrl);
+		if (url.protocol !== "https:" && !isLoopbackHost(url.hostname)) throw new Error(`HTTPS required for remote connections (got ${url.protocol}//${url.hostname})`);
+		this.baseUrl = options.baseUrl;
+		this.token = options.token;
+		this.blocklet = options.blocklet;
+		this.sessionId = options.sessionId;
+		this.extraHeaders = options.extraHeaders ?? {};
+	}
+	/** Instance-scoped capability memory (per-server, design §7.1). */
+	get supportsBatch() {
+		return this.batchSupported;
+	}
+	wirePath(path) {
+		const p = path.startsWith("/") ? path : `/${path}`;
+		return `/user${p === "/" ? "" : p}`;
+	}
+	stripUser(path) {
+		return path.startsWith("/user/") ? path.slice(5) : path;
+	}
+	async rpc(body) {
+		const res = await fetch((0, ufo.joinURL)(this.baseUrl, "/api/afs/rpc"), {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				Authorization: `Bearer ${this.token}`,
+				...this.extraHeaders
+			},
+			body: JSON.stringify({
+				blocklet: this.blocklet,
+				...this.sessionId ? { sessionId: this.sessionId } : {},
+				...body
+			})
+		});
+		let json;
+		try {
+			json = await res.json();
+		} catch {
+			json = {
+				ok: false,
+				error: `non-JSON response (HTTP ${res.status})`
+			};
+		}
+		return {
+			status: res.status,
+			json
+		};
+	}
+	/** Map a non-OK single-op wire response onto the AFS error types. */
+	throwWireError(status, json, path) {
+		if (status === 404) throw new _aigne_afs.AFSNotFoundError(path);
+		if (status === 401) throw new Error("Authentication failed: check your access token");
+		if (status === 409) this.throwConflict(json, path);
+		if (json.requireFullResync === true) throw new _aigne_afs.AFSCompactedError(path, String(json.compactedBelowSeq ?? 0));
+		throw new Error(`afs-rpc error at ${path}: ${String(json.error ?? `HTTP ${status}`)}`);
+	}
+	/**
+	* 409 → AFSConflictError with the triple. Keyed on `code: "AFS_CONFLICT"`
+	* OR triple-field presence — NEVER the legacy `error === "if_match_failed"`
+	* string (the T4.1 存量 bug: the wire sends the stable code, see
+	* afs-rpc-wire.ts WIRE_ERROR_CODES.conflict; Swift's throwConflict already
+	* keys on the code).
+	*/
+	throwConflict(json, path) {
+		if (json.code === "AFS_CONFLICT" || "currentCid" in json) throw new _aigne_afs.AFSConflictError(path, {
+			cid: typeof json.currentCid === "string" ? json.currentCid : null,
+			mtime: typeof json.currentMtime === "number" ? json.currentMtime : null,
+			deviceId: typeof json.currentDeviceId === "string" ? json.currentDeviceId : null
+		});
+		if (json.requireFullResync === true) throw new _aigne_afs.AFSCompactedError(path, String(json.compactedBelowSeq ?? 0));
+		throw new Error(`afs-rpc 409 at ${path}: ${JSON.stringify(json)}`);
+	}
+	async list(path, options) {
+		const opts = {};
+		if (options?.cursor !== void 0) opts.cursor = options.cursor;
+		if (options?.limit !== void 0 && Number.isFinite(options.limit)) opts.limit = options.limit;
+		if (options?.maxDepth !== void 0) opts.maxDepth = options.maxDepth;
+		const { status, json } = await this.rpc({
+			type: "list",
+			path: this.wirePath(path),
+			...Object.keys(opts).length ? { options: opts } : {}
+		});
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, path);
+		const data = json.data ?? [];
+		return {
+			data: data.map((e) => ({
+				...e,
+				path: this.stripUser(String(e.path ?? ""))
+			})),
+			total: typeof json.total === "number" ? json.total : data.length,
+			meta: json.meta,
+			liveSeq: json.liveSeq
+		};
+	}
+	async read(path) {
+		const normPath = path.startsWith("/") ? path.slice(1) : path;
+		const isObject = normPath.startsWith(".objects/");
+		const { status, json } = await this.rpc({
+			type: "read",
+			path: this.wirePath(path)
+		});
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, path);
+		const data = json.data ?? {};
+		let content = data.content;
+		if (data.encoding === "base64" && typeof content === "string") content = decodeBase64ToBytes(content);
+		if (isObject) {
+			const requestedCid = normPath.slice(9);
+			const bytes = content instanceof Uint8Array ? content : new TextEncoder().encode(String(content ?? ""));
+			const actualCid = await require_cid.computeCID(bytes);
+			if (actualCid !== requestedCid) throw new Error(`read .objects: CID mismatch (requested ${requestedCid}, got ${actualCid})`);
+			content = bytes;
+		}
+		return { data: {
+			...data,
+			path: this.stripUser(String(data.path ?? path)),
+			content
+		} };
+	}
+	async write(path, payload) {
+		const extra = payload.meta?.extra;
+		const content = payload.content;
+		const bytes = content instanceof Uint8Array ? content : content instanceof ArrayBuffer ? new Uint8Array(content) : new TextEncoder().encode(typeof content === "string" ? content : JSON.stringify(content));
+		const options = {};
+		const meta = {};
+		if (typeof extra?.deviceId === "string") meta.deviceId = extra.deviceId;
+		if (typeof extra?.mtime === "number") meta.mtime = extra.mtime;
+		if (Object.keys(meta).length) options.meta = meta;
+		if (typeof extra?.ifMatch === "string") options.ifMatch = extra.ifMatch;
+		const { extra: _extra, ...appMeta } = payload.meta ?? {};
+		const { status, json } = await this.rpc({
+			type: "write",
+			path: this.wirePath(path),
+			content: encodeBytesToBase64(bytes),
+			encoding: "base64",
+			...appMeta && Object.keys(appMeta).length ? { meta: appMeta } : {},
+			...Object.keys(options).length ? { options } : {}
+		});
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, path);
+		return { data: json.data };
+	}
+	async delete(path, opts) {
+		const meta = opts?.meta;
+		const wireMeta = {};
+		if (typeof meta?.deviceId === "string") wireMeta.deviceId = meta.deviceId;
+		if (typeof meta?.mtime === "number") wireMeta.mtime = meta.mtime;
+		if (typeof meta?.ifMatch === "string") wireMeta.ifMatch = meta.ifMatch;
+		const { status, json } = await this.rpc({
+			type: "delete",
+			path: this.wirePath(path),
+			...Object.keys(wireMeta).length ? { options: { meta: wireMeta } } : {}
+		});
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, path);
+		return json.data;
+	}
+	/** Detect the old server's exact "unsupported batch op" 400 (design T4.2):
+	*  ONLY this text trips the per-instance fallback memory. */
+	checkBatchUnsupported(status, json) {
+		if (status === 400 && typeof json.error === "string" && /Unsupported op 'batch/.test(json.error)) {
+			this.batchSupported = false;
+			throw new BatchUnsupportedError();
+		}
+		if (json.code === "BATCH_OVER_BUDGET" || json.code === "PAYLOAD_TOO_LARGE") throw new BatchOverBudgetError(String(json.error ?? json.code));
+	}
+	restoreBatchResults(rawResults, entryPaths) {
+		if (!Array.isArray(rawResults) || rawResults.length !== entryPaths.length) throw new Error(`afs-rpc batch: results length ${Array.isArray(rawResults) ? rawResults.length : "?"} != entries length ${entryPaths.length}`);
+		return rawResults.map((raw, i) => {
+			const r = raw ?? {};
+			const status = typeof r.status === "number" ? r.status : 500;
+			const ok = r.ok === true;
+			const out = {
+				path: entryPaths[i],
+				success: ok,
+				status
+			};
+			if (ok) {
+				out.data = r.data;
+				return out;
+			}
+			out.error = typeof r.error === "string" ? r.error : void 0;
+			out.code = typeof r.code === "string" ? r.code : void 0;
+			if (r.missing === true) out.missing = true;
+			if (status === 409 || out.code === "AFS_CONFLICT") out.conflict = {
+				currentCid: typeof r.currentCid === "string" ? r.currentCid : null,
+				currentMtime: typeof r.currentMtime === "number" ? r.currentMtime : null,
+				currentDeviceId: typeof r.currentDeviceId === "string" ? r.currentDeviceId : null
+			};
+			return out;
+		});
+	}
+	/**
+	* One wire envelope per call — entries in the CORE batch shape
+	* (`AFSBatchWriteEntry`: `content.content` bytes + `options.ifMatch` /
+	* `options.meta` provenance), paths fragment-relative.
+	*/
+	async batchWrite(entries) {
+		const wireEntries = entries.map((e) => {
+			const payload = e.content?.content;
+			const bytes = payload instanceof Uint8Array ? payload : payload instanceof ArrayBuffer ? new Uint8Array(payload) : new TextEncoder().encode(typeof payload === "string" ? payload : JSON.stringify(payload ?? ""));
+			const options = e.options;
+			const meta = {};
+			if (typeof options?.meta?.deviceId === "string") meta.deviceId = options.meta.deviceId;
+			if (typeof options?.meta?.mtime === "number") meta.mtime = options.meta.mtime;
+			const wireOptions = {};
+			if (Object.keys(meta).length) wireOptions.meta = meta;
+			if (typeof options?.ifMatch === "string") wireOptions.ifMatch = options.ifMatch;
+			const appMeta = e.content?.meta;
+			return {
+				path: this.wirePath(e.path),
+				content: encodeBytesToBase64(bytes),
+				encoding: "base64",
+				...appMeta && Object.keys(appMeta).length ? { meta: appMeta } : {},
+				...Object.keys(wireOptions).length ? { options: wireOptions } : {}
+			};
+		});
+		const { status, json } = await this.rpc({
+			type: "batchWrite",
+			entries: wireEntries
+		});
+		this.checkBatchUnsupported(status, json);
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, "batchWrite");
+		this.batchSupported = true;
+		return {
+			results: this.restoreBatchResults(json.results, entries.map((e) => e.path)),
+			succeeded: Number(json.succeeded ?? 0),
+			failed: Number(json.failed ?? 0)
+		};
+	}
+	/** Core-shaped delete entries (`options.meta.{ifMatch,deviceId,mtime}`). */
+	async batchDelete(entries) {
+		const wireEntries = entries.map((e) => {
+			const m = e.options?.meta;
+			const meta = {};
+			if (typeof m?.deviceId === "string") meta.deviceId = m.deviceId;
+			if (typeof m?.mtime === "number") meta.mtime = m.mtime;
+			if (typeof m?.ifMatch === "string") meta.ifMatch = m.ifMatch;
+			return {
+				path: this.wirePath(e.path),
+				...Object.keys(meta).length ? { options: { meta } } : {}
+			};
+		});
+		const { status, json } = await this.rpc({
+			type: "batchDelete",
+			entries: wireEntries
+		});
+		this.checkBatchUnsupported(status, json);
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, "batchDelete");
+		this.batchSupported = true;
+		return {
+			results: this.restoreBatchResults(json.results, entries.map((e) => e.path)),
+			succeeded: Number(json.succeeded ?? 0),
+			failed: Number(json.failed ?? 0)
+		};
+	}
+	/** Entries are absolute wire paths already (e.g. "/.objects/{cid}" reads). */
+	async batchRead(entries) {
+		const wireEntries = entries.map((e) => ({
+			path: this.wirePath(e.path),
+			...e.optional ? { optional: true } : {}
+		}));
+		const { status, json } = await this.rpc({
+			type: "batchRead",
+			entries: wireEntries
+		});
+		this.checkBatchUnsupported(status, json);
+		if (status !== 200 || json.ok !== true) this.throwWireError(status, json, "batchRead");
+		this.batchSupported = true;
+		const results = this.restoreBatchResults(json.results, entries.map((e) => e.path));
+		for (const r of results) {
+			const content = r.data?.content;
+			if (r.data?.encoding === "base64" && typeof content === "string") r.data.content = decodeBase64ToBytes(content);
+		}
+		return {
+			results,
+			succeeded: Number(json.succeeded ?? 0),
+			failed: Number(json.failed ?? 0)
+		};
+	}
+	/**
+	* Probe whether the server's `/user` space advertises grant capability
+	* (P2 T2.5). Reads the `.actions` catalogue and checks the prepare-upload
+	* entry's `meta.grantCapability`. `false` on Node (fallback-only) or an old
+	* server with no upload actions → the engine stays on batchWrite.
+	*/
+	async uploadGrantCapability() {
+		const { status, json } = await this.rpc({
+			type: "list",
+			path: this.wirePath("/.actions")
+		});
+		if (status !== 200 || json.ok !== true) return false;
+		return (json.data ?? []).find((e) => e.id === "prepare-upload")?.meta?.grantCapability === true;
+	}
+	/** Run a `/user/.actions/<name>` exec. Throws `BatchUnsupportedError` when the
+	*  server lacks the action (old server) so the engine falls back. */
+	async execAction(name, args) {
+		const { status, json } = await this.rpc({
+			type: "exec",
+			path: this.wirePath(`/.actions/${name}`),
+			args
+		});
+		if (status === 404 || status === 501) throw new BatchUnsupportedError();
+		if (status !== 200 || json.ok !== true) throw new Error(`afs-rpc exec ${name} failed: ${String(json.error ?? json.message ?? status)}`);
+		return json.data ?? {};
+	}
+	async prepareUpload(entries) {
+		return await this.execAction("prepare-upload", {
+			entries,
+			strategy: "auto"
+		});
+	}
+	async commitUpload(sessionId, entries) {
+		const data = await this.execAction("commit-upload", {
+			sessionId,
+			entries
+		});
+		const results = (data.results ?? []).map((r) => commitResultToBatchEntry(r));
+		let okCount = 0;
+		for (const r of results) if (r.success) okCount++;
+		return {
+			results,
+			succeeded: Number(data.succeeded ?? okCount),
+			failed: Number(data.failed ?? results.length - okCount)
+		};
+	}
+	/** Abort a prepared session (staged objects → GC). No TS engine call site yet
+	*  — the engine bails via BatchUnsupportedError on grant loss; exposed for
+	*  protocol parity (Swift mirror) + a future P4 abort-on-timeout path. */
+	async abortUpload(sessionId) {
+		await this.execAction("abort-upload", { sessionId });
+	}
+	/** Out-of-band PUT of object bytes via a presigned grant. Returns the HTTP
+	*  status (commit-after-200: the engine only commits entries that got 200). */
+	async uploadObject(grant, bytes) {
+		const res = await fetch(grant.url, {
+			method: grant.method,
+			headers: grant.signedHeaders,
+			body: bytes
+		});
+		if (!res.ok) await res.text().catch(() => void 0);
+		return res.status;
+	}
+	/**
+	* Probe whether the server's `/user` space advertises GET-grant capability
+	* (P2 T2.4). Reads the `.actions` catalogue and checks the prepare-download
+	* entry's INDEPENDENT `meta.downloadGrantCapability` (NOT the upload
+	* `grantCapability`). `false` on Node (fallback-only) or an old server → the
+	* engine stays on batchRead.
+	*/
+	async downloadGrantCapability() {
+		const { status, json } = await this.rpc({
+			type: "list",
+			path: this.wirePath("/.actions")
+		});
+		if (status !== 200 || json.ok !== true) return false;
+		return (json.data ?? []).find((e) => e.id === "prepare-download")?.meta?.downloadGrantCapability === true;
+	}
+	/** Run `prepare-download` — mints GET grants for the referenced cids. Throws
+	*  `BatchUnsupportedError` when the server lacks the action (old server). */
+	async prepareDownload(entries) {
+		return await this.execAction("prepare-download", { entries });
+	}
+	/**
+	* Out-of-band GET of object bytes via a presigned grant (content leaves R2
+	* directly — never through the Worker / base64). Returns the raw bytes on
+	* 200. A 401/403 means the grant was rejected (token lacks GetObject / bad
+	* signature) → throws {@link DownloadForbiddenError} so the engine flips the
+	* whole session to batchRead (runtime fallback-on-403, §7.3). Any other
+	* non-2xx (404 dangling / 5xx) throws a generic Error — the engine leaves the
+	* cid unfilled so the existing missing-object path handles it.
+	*/
+	async downloadObject(grant) {
+		const res = await fetch(grant.url, { method: grant.method });
+		if (res.status === 401 || res.status === 403) {
+			await res.body?.cancel().catch(() => void 0);
+			throw new DownloadForbiddenError(res.status);
+		}
+		if (!res.ok) {
+			await res.body?.cancel().catch(() => void 0);
+			throw new Error(`downloadObject ${grant.method} failed: ${res.status}`);
+		}
+		return new Uint8Array(await res.arrayBuffer());
+	}
+};
+/**
+* A presigned GET directly rejected the bearer (401/403) — the R2 token likely
+* lacks GetObject or the signature is bad. Signals the engine to flip the whole
+* sync session to batchRead and not keep hitting the same wall (§7.3).
+*/
+var DownloadForbiddenError = class extends Error {
+	constructor(status) {
+		super(`download grant rejected by object store: ${status}`);
+		this.status = status;
+		this.name = "DownloadForbiddenError";
+	}
+};
+/** Map a commit-upload per-entry result (P2 shape) → the engine's RpcBatchEntryResult. */
+function commitResultToBatchEntry(r) {
+	if (r.ok === true || typeof r.status === "number" && r.status === 200 && !r.code) {
+		const data = r.data;
+		return {
+			path: String(data?.path ?? ""),
+			success: true,
+			status: 200,
+			data: r.data
+		};
+	}
+	return {
+		path: String(r.path ?? ""),
+		success: false,
+		status: typeof r.status === "number" ? r.status : r.code === "AFS_CONFLICT" ? 409 : 500,
+		code: typeof r.code === "string" ? r.code : void 0,
+		error: typeof r.error === "string" ? r.error : void 0,
+		conflict: r.conflict
+	};
+}
+function encodeBytesToBase64(bytes) {
+	let binary = "";
+	const CHUNK = 32768;
+	for (let i = 0; i < bytes.length; i += CHUNK) binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+	return btoa(binary);
+}
+function decodeBase64ToBytes(b64) {
+	const binary = atob(b64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+
+//#endregion
+exports.BatchOverBudgetError = BatchOverBudgetError;
+exports.BatchUnsupportedError = BatchUnsupportedError;
+exports.DownloadForbiddenError = DownloadForbiddenError;
+exports.RemoteUserSpaceAFS = RemoteUserSpaceAFS;
+exports.RpcUserSpaceAFS = RpcUserSpaceAFS;