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

package/dist/index.mjs

@@ -0,0 +1,2537 @@
+import { BLOCKLET_PUBLISH_MARKER, applyBlockletDeleteHook, applyBlockletWriteHook } from "./blocklet-hook.mjs";
+import { CHANGELOG_DDL, CHANGELOG_INDEX_SQL, CHANGELOG_ROW_KIND, CHANGELOG_SCOPE_CID_MIGRATION_SQL, CHANGELOG_TABLE_SQL, CHANGELOG_WIRE_EXTRA_FIELDS, DEVICE_SYNC_STATE_INDEX_SQL, DEVICE_SYNC_STATE_TABLE_SQL, MANIFEST_FILE_KIND, MANIFEST_WIRE_EXTRA_FIELDS, PREFIX_WATERMARK_TABLE_SQL, SCOPE_META_FILE_COUNT_BACKFILL_SQL, SCOPE_META_FILE_COUNT_DELETE_ONE_SQL, SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL, SCOPE_META_FILE_COUNT_TRIGGER_SQL, SCOPE_META_INDEX_SQL, SCOPE_META_TABLE_SQL, SCOPE_META_TOTAL_BYTES_BACKFILL_SQL, SCOPE_META_TOTAL_BYTES_COLUMN_SQL, SCOPE_META_TOTAL_BYTES_TRIGGER_SQL, SYNC_STATE_DDL, SYNC_STATE_INDEX_SQL, SYNC_STATE_TABLE_SQL, normalizeDdl, parseChangelogEntry, parseManifestEntry, serializeChangelogEntry, serializeManifestEntry, watermarkWritePrefix } from "./changelog-schema.mjs";
+import { checksumSha256OfContent, cidToChecksumSha256, computeCID } from "./cid.mjs";
+import { normalizeId, validateId } from "./did-utils.mjs";
+import { DOWNLOAD_ACTIONS, DOWNLOAD_GRANT_TTL_SEC, PrepareDownloadArgsSchema } from "./download-actions.mjs";
+import { detectMimeType, isTextMime } from "./mime-utils.mjs";
+import { DEFAULT_INLINE_THRESHOLD, INGEST_DEVICE_ID, INLINE_CONTENT_HARD_CAP, assertInlineThreshold, decodeInlineText } from "./inline-content.mjs";
+import { isShareDeclarationPath, isShareReservedPath } from "./share-declaration.mjs";
+import { applyShareDeleteHook, applyShareWriteHook } from "./share-hook.mjs";
+import { ShareVirtualHandler, matchSharesVirtualPath } from "./share-virtual-path.mjs";
+import { resolveCtime } from "./timestamp.mjs";
+import { buildKeysetCursor, buildOrderedQueryParts, compareTreeSortValues, keysetAfter, loopBatchDeleteEntries, loopBatchPutEntries, parseTreeCursor } from "./tree-index.mjs";
+import { assertTreeQuerySpec, parseRecordText, projectRecordFields } from "./tree-query.mjs";
+import { D1_DID_SPACE_SCHEMA_SQL, ENTRIES_CONTENT_TYPE_COLUMN_SQL, ENTRIES_CONTENT_TYPE_INDEX_DROP_SQL, ENTRIES_CONTENT_TYPE_INDEX_SQL, ENTRIES_DEDUP_INDEX_SQL, ENTRIES_DEDUP_KEY_COLUMN_SQL, ENTRIES_DEDUP_SCOPE_COLUMN_SQL, ENTRIES_INDEX_SQL, ENTRIES_INLINE_CONTENT_COLUMN_SQL, ENTRIES_METADATA_COLUMN_SQL, ENTRIES_TABLE_SQL, GC_QUEUE_INDEX_SQL, GC_QUEUE_TABLE_SQL, RESOLVE_ENTRIES_INDEX_SQL, RESOLVE_ENTRIES_TABLE_SQL, SHARES_INDEX_SQL, SHARES_TABLE_SQL, UPLOAD_SESSIONS_INDEX_SQL, UPLOAD_SESSIONS_TABLE_SQL, UPLOAD_SESSION_ENTRIES_TABLE_SQL, VERSIONED_SCOPES_INDEX_SQL, VERSIONED_SCOPES_TABLE_SQL } from "./d1-schema.mjs";
+import { D1UploadSessionStore, SqliteUploadSessionStore, UPLOAD_SESSION_TTL_MS } from "./upload-session-store.mjs";
+import { AFS_IFMATCH_ABSENT, AbortUploadArgsSchema, CommitUploadArgsSchema, GRANT_EXPIRES_SEC, PrepareUploadArgsSchema, UPLOAD_ACTIONS, ifMatchPreconditionFailed, zodMessage } from "./upload-actions.mjs";
+import { normalizeItemUrl } from "./url-normalize.mjs";
+import { __decorate } from "./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.mjs";
+import { attachMetadataContext, detachMetadataContext, getMetadataContext } from "./afs-metadata-context.mjs";
+import { CHANGELOG_INSERT_SQL, MAX_DEVICE_ID_BYTES, buildChangelogBinds, validateDeviceId } from "./changelog-write.mjs";
+import { CachingObjectStore, CidByteCache } from "./cid-byte-cache.mjs";
+import { BatchOverBudgetError, BatchUnsupportedError, RpcUserSpaceAFS } from "./remote-afs.mjs";
+import { HttpTransport } from "./transports/http.mjs";
+import { StaticReadonlyTransport } from "./transports/static.mjs";
+import { WsTransport, createWsTransport } from "./transports/ws.mjs";
+import { DIDSpaceClient, connectDIDSpace } from "./client.mjs";
+import { D1GCQueue } from "./d1-gc-queue.mjs";
+import { prefixRange } from "./prefix-range.mjs";
+import { D1ResolveStore } from "./d1-resolve-store.mjs";
+import { assertValidCid, objectKeyForCid } from "./object-key.mjs";
+import { ShareResolver } from "./share-resolve.mjs";
+import { rowToEntry } from "./share-store.mjs";
+import { D1ShareReconciler, D1ShareStore } from "./d1-share-store.mjs";
+import { DIRTY_PATH_DDL, DIRTY_PATH_INDEX_SQL, DIRTY_PATH_TABLE_SQL, DIRTY_PATH_TRIGGER_SQL } from "./dirty-path-schema.mjs";
+import { D1TreeIndex, MAX_ENTRIES_PER_SCOPE, ancestorDirs, nameOf, parentOf } from "./d1-tree-index.mjs";
+import { DIDSpaceBlockletDataBackend } from "./data-backend.mjs";
+import { applyDirtyUpsert } from "./dirty-path-queue.mjs";
+import { LOCAL_CHANGELOG_DEFAULT_LIMIT, LOCAL_CHANGELOG_MAX_LIMIT, LocalChangelog } from "./local-changelog.mjs";
+import { MemoryGcQueue } from "./memory-gc-queue.mjs";
+import { MemoryTreeIndex } from "./memory-tree-index.mjs";
+import { PrefixedTreeIndex } from "./prefixed-tree-index.mjs";
+import { PRESIGN_MAX_EXPIRES_SEC } from "./presign-signer.mjs";
+import { referencedAnywhereD1, referencedAnywhereLibsql } from "./reference-check.mjs";
+import { DIDSpaceResolver } from "./resolve.mjs";
+import { buildManifest, computeDiff, fetchRemoteManifest, runWithConcurrency, syncDIDSpace } from "./rsync.mjs";
+import { DEFAULT_GC_GRACE_MS, runGc } from "./run-gc.mjs";
+import { decodeScopeHmacSecret, deriveScope, isPlainDidScope } from "./scope-id.mjs";
+import { buildD1MigrationSql, classifyScopes, migrateD1Scopes } from "./scope-migration.mjs";
+import { serveShare } from "./share-serve.mjs";
+import { SqliteGcQueue } from "./sqlite-gc-queue.mjs";
+import { SqliteResolveStore } from "./sqlite-resolve-store.mjs";
+import { SqliteShareStore, openDaemonShareStore } from "./sqlite-share-store.mjs";
+import { ConflictResolutionError, CurrentObjectMissingError, PULL_BATCH_LIMIT, PULL_FETCH_CONCURRENCY, PUSH_BATCH_LIMIT, PUSH_PROGRESS_FLUSH_INTERVAL, SYNC_WALL_CLOCK_BUDGET_MS, SyncEngine, classifyMissingObject } from "./sync-engine.mjs";
+import { DEVICE_ID_FORMAT_RE, SYNC_STATE_KEYS, SyncStateStore, defaultAppState, generateDesktopDeviceId, isValidDeviceId, parseSyncStatus, serializeSyncStatus } from "./sync-state.mjs";
+import { D1VersionedScopeBackend, LibsqlVersionedScopeBackend, MemoryVersionedScopeBackend } from "./versioned-content-backends.mjs";
+import { VersionedContentIndex } from "./versioned-content-index.mjs";
+import { VersionedContentStore } from "./versioned-content-store.mjs";
+import { resolveVersionToken, versionedScope, versionedScopeGroup } from "./versioned-scope.mjs";
+import { AFSCompactedError, AFSConflictError, AFSForbiddenError, AFSNotFoundError, AFSUnsupportedError, AFSValidationError, SCRIPT_EVENT_TYPES, collectionQueryStandardAction, isValidOrderBy, makeNsLog, orderByRequested, orderEntries, resolveFieldPath } from "@aigne/afs";
+import { AFSBaseProvider, Actions, Delete, Explain, List, Meta, Read, Search, Stat, Write } from "@aigne/afs/provider";
+import { time } from "@aigne/afs-timing";
+import { joinURL } from "ufo";
+import { z } from "zod";
+
+//#region src/index.ts
+const log = makeNsLog("provider:did-space");
+const LIST_MAX_LIMIT = 1e3;
+/**
+* AFS entry `id` is the basename (last path segment), matching AFSFS/AFSJSON —
+* NOT the full path. `AFSBaseProvider.buildEntry` defaults `id` to the full
+* normalized path, so the list handlers below MUST pass an explicit basename id;
+* otherwise consumers that labelize `entry.id` (e.g. the auto-surface settings
+* tabs) render the whole path instead of "Input"/"Sort"/"View". The stat handler
+* already does this (`afsPath.split("/").pop()`); the list handlers were the gap.
+*/
+function basenameId(path) {
+	return path.split("/").filter(Boolean).pop() ?? "/";
+}
+/**
+* Provider-reserved meta keys (planning/agent-hub/metadata-foundation.md §
+* 白名单). These are computed by DID Space at write time and overwrite
+* anything the application tries to put under the same name. The application
+* may write any OTHER key into `payload.meta` and it'll be persisted to the
+* `entries.metadata` column.
+*
+* Note: `ctime / mtime` are NOT in `entry.meta` (they live at AFSEntry top
+* level as `createdAt / updatedAt`), so they're not in the reserved set —
+* the application can write `meta.ctime` and it'll be persisted as just
+* another application field, NOT conflated with the entry's timestamp.
+*/
+const PROVIDER_RESERVED_META_KEYS = new Set([
+	"kind",
+	"size",
+	"cid",
+	"mimeType"
+]);
+/**
+* Strip provider-reserved keys from a write payload's meta, leaving only the
+* application-owned fields that should go to `entries.metadata`.
+* Returns undefined when nothing application-owned remains (avoids storing
+* `{}` blobs).
+*/
+function extractApplicationMeta(meta) {
+	if (!meta) return void 0;
+	const out = {};
+	let any = false;
+	for (const [k, v] of Object.entries(meta)) {
+		if (PROVIDER_RESERVED_META_KEYS.has(k)) continue;
+		out[k] = v;
+		any = true;
+	}
+	return any ? out : void 0;
+}
+/**
+* Loose upper bound on serialized application metadata (did-space-metadata
+* NEEDS DECISION 3). `metadata` rides `z.record(z.unknown())` and is NOT
+* digest-checked (it's application data, not bytes — design §5), so the wire
+* imposes no size limit of its own. Aside's real metadata is tiny (a few ISO
+* timestamps, ~50B), but a malicious / buggy client could otherwise stuff a
+* huge JSON blob straight into the D1 `metadata` column (row-size / write-
+* amplification risk, cf. the D1 burn-through lesson). 64KB is far above any
+* legitimate use yet blocks abuse. Shared by the two new server ingress points
+* (batchWrite + upload-plane commit) so the threshold can't drift.
+*/
+const METADATA_MAX_BYTES = 64 * 1024;
+/**
+* Reject abusively large application metadata gracefully (an `AFSValidationError`,
+* which afs-rpc maps to 400 — never an uncaught 500). Call AFTER
+* `extractApplicationMeta` so the reserved-key strip can't be gamed to dodge
+* the bound. No-op for absent metadata.
+*/
+function assertMetadataSize(meta, path) {
+	if (!meta) return;
+	const bytes = new TextEncoder().encode(JSON.stringify(meta)).length;
+	if (bytes > METADATA_MAX_BYTES) throw new AFSValidationError(`Application metadata for ${path} is ${bytes} bytes, over the ${METADATA_MAX_BYTES}-byte limit`);
+}
+/** Plain JSON object (not array, not null) — the deep-merge branch. */
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** An incoming scalar that carries no information and must never overwrite. */
+function isEmptyScalar(v) {
+	return v === void 0 || v === null || v === "";
+}
+/** Union two arrays, dedup by structural identity, existing entries first. */
+function unionArrays(existing, incoming) {
+	const seen = new Set(existing.map((x) => JSON.stringify(x)));
+	const out = [...existing];
+	for (const item of incoming) {
+		const key = JSON.stringify(item);
+		if (!seen.has(key)) {
+			out.push(item);
+			seen.add(key);
+		}
+	}
+	return out;
+}
+/**
+* Merge incoming item content into the existing item on a duplicate-key write
+* (#492). A re-save is ADDITIVE and must never DEGRADE the stored item:
+*
+* - keys in `immutable` (always `createdAt`, plus caller-supplied lifecycle
+*   fields like `status`) keep the existing value — a re-clip never resets an
+*   archived item or rewrites its creation time;
+* - arrays union-dedup (existing first) so tags / collections accrete;
+* - plain objects deep-merge recursively, so a partial re-clip of `og` /
+*   `content` keeps fields the new capture omitted;
+* - scalars take the incoming value EXCEPT empty ones (`undefined` / `null` /
+*   `""`), which keep the existing value — a bookmarklet that failed to grab a
+*   title must not wipe the good title already saved;
+* - type conflicts (array↔scalar, object↔scalar) take the incoming value.
+*/
+function mergeItemContent(existing, incoming, immutable = new Set(["createdAt"])) {
+	const merged = { ...existing };
+	for (const [k, v] of Object.entries(incoming)) {
+		if (immutable.has(k)) continue;
+		const cur = merged[k];
+		if (Array.isArray(v) && Array.isArray(cur)) merged[k] = unionArrays(cur, v);
+		else if (isPlainObject(v) && isPlainObject(cur)) merged[k] = mergeItemContent(cur, v, immutable);
+		else if (isEmptyScalar(v)) {} else merged[k] = v;
+	}
+	return merged;
+}
+var DIDSpaceProvider = class extends AFSBaseProvider {
+	static manifest() {
+		return {
+			name: "did-space",
+			description: "DID-scoped persistent storage with CID-based content deduplication.\n- Per-user data isolation via DID prefix\n- Content-addressable deduplication (CID v1, raw codec + SHA-256)\n- R2 for objects, D1 for tree index",
+			uriTemplate: "did-space://{did}/{path*}",
+			category: "storage",
+			schema: z.object({
+				did: z.string(),
+				path: z.string().optional()
+			}),
+			tags: [
+				"did",
+				"storage",
+				"cid",
+				"dedup",
+				"cloud"
+			],
+			capabilityTags: [
+				"read-write",
+				"crud",
+				"search",
+				"auth:token"
+			],
+			security: {
+				riskLevel: "sandboxed",
+				resourceAccess: []
+			},
+			capabilities: { filesystem: {
+				read: true,
+				write: true
+			} },
+			noPerEntryActions: true
+		};
+	}
+	static treeSchema() {
+		return {
+			operations: [
+				"list",
+				"read",
+				"write",
+				"delete",
+				"search",
+				"stat",
+				"explain"
+			],
+			tree: {
+				"/": { kind: "did-space:root" },
+				"/{path+}": { kind: "did-space:file" }
+			},
+			auth: { type: "custom" },
+			bestFor: [
+				"user files",
+				"persistent storage",
+				"content-addressed data"
+			],
+			notFor: ["large binary blobs", "real-time streaming"]
+		};
+	}
+	name;
+	description;
+	accessMode;
+	did;
+	objectStore;
+	treeIndex;
+	gcQueue;
+	/** See `DIDSpaceProviderOptions.deviceId`. Read by writeHandler/deleteHandler. */
+	deviceId;
+	/** Optional ShareResolver for .share reconcile hook (Phase 0.4) */
+	shareResolver;
+	/** See `DIDSpaceProviderOptions.shareOwnerDid` / `shareTreePrefix`. */
+	shareOwnerDid;
+	shareTreePrefix;
+	/** See `DIDSpaceProviderOptions.blockletResolver` / `blockletOwnerDid` (#674). */
+	blockletResolver;
+	blockletOwnerDid;
+	/** Upload plane deps (design §7). See `DIDSpaceProviderOptions`. */
+	signer;
+	uploadSessionStore;
+	uploadScope;
+	constructor(options) {
+		super();
+		validateId(options.did);
+		this.name = options.name || "did-space";
+		this.description = options.description;
+		this.accessMode = options.accessMode ?? "readwrite";
+		this.did = normalizeId(options.did);
+		this.objectStore = options.objectStore;
+		this.treeIndex = options.treeIndex;
+		this.gcQueue = options.gcQueue;
+		this.deviceId = options.deviceId ?? "server:default";
+		this.shareResolver = options.shareResolver;
+		this.shareOwnerDid = options.shareOwnerDid;
+		this.shareTreePrefix = options.shareTreePrefix;
+		this.blockletResolver = options.blockletResolver;
+		this.blockletOwnerDid = options.blockletOwnerDid;
+		this.signer = options.signer;
+		this.uploadSessionStore = options.uploadSessionStore;
+		this.uploadScope = options.uploadScope;
+	}
+	/** Convert AFS path to tree-index path (strip leading /) */
+	treePath(afsPath) {
+		if (afsPath.includes("\0")) throw new Error("Null byte in path");
+		if (/(?:^|\/)\.\.(?:\/|$)/.test(afsPath)) throw new Error("Path traversal in path");
+		return afsPath.replace(/^\/+/, "");
+	}
+	/** Convert AFS path to tree-index prefix for directory listing */
+	treeListPrefix(afsPath) {
+		if (afsPath === "/") return "";
+		return `${this.treePath(afsPath)}/`;
+	}
+	/**
+	* Remap a write/delete into the arguments the .share reconcile hook expects.
+	* On a whole-space provider this is identity. On a prefixed instance-fragment
+	* provider (`shareTreePrefix` set) it restores the WHOLE-TREE decl path and
+	* keys the share to the space owner (`shareOwnerDid`), so reconcile stores the
+	* same `owner_did` + full `decl_path` the public serving path resolves by.
+	*/
+	shareHookArgs(afsPath, treePath) {
+		const fullTreePath = this.shareTreePrefix ? joinURL(this.shareTreePrefix, treePath) : treePath;
+		return {
+			afsPath: this.shareTreePrefix ? `/${fullTreePath}` : afsPath,
+			treePath: fullTreePath,
+			ownerDid: this.shareOwnerDid ?? this.did
+		};
+	}
+	/**
+	* Remap a write/delete into the arguments the blocklet hook expects. Same
+	* whole-tree path restoration as {@link shareHookArgs}, but the recorded
+	* `ownerDid` is the PLAINTEXT space owner (`blockletOwnerDid`), not the de-id
+	* scope — the serve path re-derives the storage scope from the plaintext DID.
+	*/
+	blockletHookArgs(afsPath, treePath) {
+		const fullTreePath = this.shareTreePrefix ? joinURL(this.shareTreePrefix, treePath) : treePath;
+		return {
+			afsPath: this.shareTreePrefix ? `/${fullTreePath}` : afsPath,
+			treePath: fullTreePath,
+			ownerDid: this.blockletOwnerDid ?? this.did
+		};
+	}
+	objectKey(cid) {
+		if (!/^[bz][a-zA-Z0-9]{20,100}$/.test(cid)) throw new Error(`Invalid CID format: ${cid.slice(0, 30)}`);
+		return `objects/${cid}`;
+	}
+	async isDirectory(path) {
+		if (path === "/") return true;
+		return this.treeIndex.hasChildren(this.treeListPrefix(path));
+	}
+	/** Collect all CIDs under a prefix for GC queuing before bulk delete. */
+	async collectCIDsByPrefix(prefix) {
+		const cids = [];
+		let cursor;
+		do {
+			const result = await this.treeIndex.listEntries(prefix, {
+				limit: 1e3,
+				cursor
+			});
+			for (const e of result.entries) if (e.cid) cids.push(e.cid);
+			cursor = result.hasMore ? result.cursor : void 0;
+		} while (cursor);
+		return cids;
+	}
+	async readMeta(ctx) {
+		const afsPath = joinURL("/", ctx.params.path ?? "");
+		if (afsPath === "/") {
+			const childrenCount = await this.treeIndex.countChildren(this.treeListPrefix("/"));
+			return this.buildEntry(joinURL(afsPath, ".meta"), {
+				content: {
+					type: "directory",
+					path: "/"
+				},
+				meta: {
+					kind: "did-space:root",
+					childrenCount
+				}
+			});
+		}
+		const entry = await this.treeIndex.get(this.treePath(afsPath), { includeContent: false });
+		if (entry) return this.buildEntry(joinURL(afsPath, ".meta"), {
+			content: {
+				type: "file",
+				path: afsPath,
+				size: entry.size,
+				cid: entry.cid
+			},
+			meta: {
+				kind: "did-space:file",
+				size: entry.size,
+				cid: entry.cid,
+				mimeType: entry.mimeType
+			},
+			createdAt: new Date(entry.ctime),
+			updatedAt: new Date(entry.mtime)
+		});
+		if (await this.isDirectory(afsPath)) {
+			const childrenCount = await this.treeIndex.countChildren(this.treeListPrefix(afsPath));
+			return this.buildEntry(joinURL(afsPath, ".meta"), {
+				content: {
+					type: "directory",
+					path: afsPath
+				},
+				meta: {
+					kind: "did-space:directory",
+					childrenCount
+				}
+			});
+		}
+		throw new AFSNotFoundError(afsPath);
+	}
+	/**
+	* Override to implement the `maxDepth: -1` snapshot contract.
+	*
+	* When called with `maxDepth: -1`, collects ALL file entries under `path`
+	* using cursor-based pagination through the treeIndex and returns them in
+	* a single `AFSListResult` with `meta.cursor = String(manifestSeq)` so
+	* `SyncEngine.fullResync()` can advance `cloudSeq` correctly.
+	*
+	* > 10_000 entries → sets `meta.truncated: true` (HTTP 200, SyncEngine
+	* throws `ManifestTooLargeError`).
+	*
+	* All other options fall through to `super.list()` → `listHandler`.
+	*/
+	async list(path, options) {
+		if (options?.maxDepth !== -1) return super.list(path, options);
+		const normPath = path.startsWith("/") ? path.slice(1) : path;
+		if (normPath === ".changelog" || normPath.startsWith(".changelog/")) throw new AFSValidationError(".changelog path does not support maxDepth=-1 (changelog uses cursor-based incremental access)");
+		if (options.cursor !== void 0 || options.limit !== void 0 && Number.isFinite(options.limit) || options.offset !== void 0 && Number.isFinite(options.offset)) throw new AFSValidationError("list with maxDepth=-1 cannot be combined with cursor, limit, or offset");
+		const SNAPSHOT_MAX_ENTRIES = 1e4;
+		const prefix = this.treeListPrefix(path);
+		const allEntries = [];
+		let cursor;
+		do {
+			const result = await this.treeIndex.listEntries(prefix, {
+				limit: LIST_MAX_LIMIT,
+				cursor
+			});
+			for (const treeEntry of result.entries) {
+				if (allEntries.length >= SNAPSHOT_MAX_ENTRIES) return {
+					data: allEntries,
+					meta: {
+						truncated: true,
+						...orderByRequested(options.orderBy) ? { orderByIgnored: true } : {}
+					}
+				};
+				allEntries.push(this.buildEntry(`/${treeEntry.path}`, {
+					id: basenameId(treeEntry.path),
+					meta: serializeManifestEntry({
+						cid: treeEntry.cid,
+						size: treeEntry.size,
+						mtime: treeEntry.mtime,
+						mimeType: treeEntry.mimeType
+					}),
+					createdAt: new Date(treeEntry.ctime),
+					updatedAt: new Date(treeEntry.mtime)
+				}));
+			}
+			cursor = result.hasMore ? result.cursor : void 0;
+		} while (cursor);
+		const manifestSeq = await this.treeIndex.getMaxSeq();
+		const snapshotMeta = { cursor: String(manifestSeq) };
+		if (orderByRequested(options.orderBy)) snapshotMeta.orderByIgnored = true;
+		return {
+			data: allEntries,
+			meta: snapshotMeta
+		};
+	}
+	async listHandler(ctx) {
+		const afsPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const options = ctx.options;
+		const includeContent = options?.includeContent === true;
+		const includeChildrenCounts = options?.includeChildrenCounts === true;
+		const orderRequested = orderByRequested(options?.orderBy);
+		const orderBy = orderRequested && isValidOrderBy(options?.orderBy) ? options.orderBy : void 0;
+		/** Merge the no-silent-drop flag into a result when ordering was requested but not applied. */
+		const flagIgnored = (result) => orderRequested ? {
+			...result,
+			meta: {
+				...result.meta,
+				orderByIgnored: true
+			}
+		} : result;
+		const sharesMatch = matchSharesVirtualPath(afsPath);
+		if (sharesMatch && this.shareResolver && !this.shareTreePrefix) {
+			const { list } = await new ShareVirtualHandler(this.shareResolver, this.did).list(sharesMatch);
+			return flagIgnored({ data: list });
+		}
+		const normPath = afsPath.startsWith("/") ? afsPath.slice(1) : afsPath;
+		const isChangelog = normPath === ".changelog" || normPath.startsWith(".changelog/");
+		if (isChangelog && options?.cursor !== void 0) return flagIgnored(await this.listChangelog(options.cursor, options.limit));
+		const limit = Math.min(options?.limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		const offset = Math.max(0, Number(options?.offset) || 0);
+		const maxDepth = options?.maxDepth ?? 1;
+		const collectLimit = offset + limit;
+		if (maxDepth === 0) return { data: [] };
+		const prefix = this.treeListPrefix(afsPath);
+		if (afsPath !== "/") {
+			if (!await this.treeIndex.get(this.treePath(afsPath), { includeContent: false })) {
+				if (!await this.treeIndex.hasChildren(prefix)) throw new AFSNotFoundError(afsPath);
+			}
+		}
+		const entries = [];
+		if (maxDepth === 1) {
+			if (orderBy) {
+				const scan$1 = await this.listShallowOrdered(prefix, collectLimit, entries, orderBy, includeContent);
+				if (includeChildrenCounts) await this.fillChildrenCounts(entries);
+				return this.withLiveSeq({
+					data: entries,
+					total: await this.shallowTotal(prefix, scan$1)
+				}, prefix, isChangelog);
+			}
+			const scan = await this.listShallow(prefix, collectLimit, entries, void 0, includeContent);
+			if (includeChildrenCounts) await this.fillChildrenCounts(entries);
+			return this.withLiveSeq(flagIgnored({
+				data: entries,
+				total: await this.shallowTotal(prefix, scan)
+			}), prefix, isChangelog);
+		}
+		await this.listDeep(afsPath, prefix, collectLimit, maxDepth, entries, includeContent);
+		return flagIgnored({ data: entries });
+	}
+	/**
+	* True direct-children total for a shallow listing.
+	*
+	* AFSListResult contract (`packages/core/src/type.ts`): absent `total`
+	* means "data IS the complete result" — so a handler that truncates its
+	* collection MUST report `total`, or every consumer downstream (base.ts
+	* pagination, afs-list pager) mistakes the page for the whole set.
+	*
+	* Cost model (D1: per-query round-trips dominate): `listShallow` scans
+	* the index in LIST_MAX_LIMIT batches and keeps counting rows past the
+	* build cap, so when the cursor drained (directories ≤ LIST_MAX_LIMIT
+	* children — the common case) the scan itself yields the exact total:
+	* ZERO extra queries. Only a directory truncated mid-cursor (> 1000
+	* children) pays ONE COUNT round-trip (same `countChildren(prefix)`
+	* call and parent-key format `readMeta` already relies on).
+	*/
+	async shallowTotal(prefix, scan) {
+		if (scan.exhausted) return scan.seen;
+		return this.treeIndex.countChildren(prefix);
+	}
+	/**
+	* Attach the per-prefix watermark `version` as the result's top-level
+	* `liveSeq` (Live Update Resilience §4 / 0a'). Read ONE row via the
+	* TreeIndex — O(1), independent of changelog history/global write volume.
+	*
+	* - Skipped for `.changelog` listings (sync-internal, no live-update scope).
+	* - Skipped when the index has no `getPrefixWatermark` (rollout) or reports
+	*   no watermark key for the path (`null` — no collection root): the
+	*   consumer then falls back to full re-list on the next edge/poll, still
+	*   correct.
+	* - A valid-but-never-written collection root reports `"0"` so consumers
+	*   baseline at 0 instead of conservatively refetching every poll tick on a
+	*   read-only collection (the first write bumps to 1 > 0 and is detected).
+	* - The value is prefix-LOCAL (only this collection root's write count), so
+	*   it never leaks another blocklet's timing (invariant I3).
+	*/
+	async withLiveSeq(result, prefix, isChangelog) {
+		if (isChangelog || !this.treeIndex.getPrefixWatermark) return result;
+		const version = await this.treeIndex.getPrefixWatermark(prefix);
+		if (version != null) result.liveSeq = String(version);
+		return result;
+	}
+	/**
+	* Shallow listing with a VALID orderBy (did-space-sorting Phase 3).
+	*
+	* - Single tuple → forwarded to the TreeIndex (`listChildren` orders
+	*   natively over the (scope,parent,col,name) indexes; keyset cursor
+	*   pages stay globally ordered, so collecting offset+limit entries is
+	*   the correct order-before-pagination slice).
+	* - 2-3 tuples → the index can order by one column only, so collect the
+	*   FULL child set and apply the canonical core sort before truncation
+	*   (order → offset → limit still holds).
+	*/
+	async listShallowOrdered(prefix, collectLimit, entries, orderBy, includeContent = false) {
+		if (orderBy.length === 1) {
+			const [field, order] = orderBy[0];
+			return this.listShallow(prefix, collectLimit, entries, {
+				orderBy: field,
+				order
+			}, includeContent);
+		}
+		const all = [];
+		await this.listShallow(prefix, Number.MAX_SAFE_INTEGER, all, void 0, includeContent);
+		const { entries: sorted } = orderEntries(all, orderBy);
+		entries.push(...sorted.slice(0, collectLimit));
+		return {
+			exhausted: true,
+			seen: all.length
+		};
+	}
+	async listShallow(prefix, limit, entries, order, includeContent = false) {
+		let cursor;
+		let seen = 0;
+		do {
+			const result = await this.treeIndex.listChildren(prefix, {
+				limit: LIST_MAX_LIMIT,
+				cursor,
+				includeContent,
+				...order ?? {}
+			});
+			seen += result.entries.length;
+			for (const child of result.entries) {
+				if (entries.length >= limit) continue;
+				if (child.path.endsWith("/")) {
+					const displayPath = `/${child.path.slice(0, -1)}`;
+					entries.push(this.buildEntry(displayPath, {
+						id: basenameId(displayPath),
+						meta: {
+							kind: "did-space:directory",
+							childrenCount: -1,
+							size: child.size
+						},
+						createdAt: new Date(child.ctime),
+						updatedAt: new Date(child.mtime)
+					}));
+				} else entries.push(this.buildEntry(`/${child.path}`, {
+					id: basenameId(child.path),
+					...includeContent && await this.verifiedInline(child) !== null ? { content: child.content } : {},
+					meta: {
+						kind: "did-space:file",
+						cid: child.cid,
+						size: child.size,
+						mimeType: child.mimeType
+					},
+					createdAt: new Date(child.ctime),
+					updatedAt: new Date(child.mtime)
+				}));
+			}
+			cursor = result.hasMore ? result.cursor : void 0;
+		} while (cursor && entries.length < limit);
+		return {
+			exhausted: cursor === void 0,
+			seen
+		};
+	}
+	/**
+	* Patch EXACT `meta.childrenCount` onto the directory entries of a
+	* collected shallow page — the opt-in half of the two-tier childrenCount
+	* contract (`AFSListOptions.includeChildrenCounts`; default tier is the
+	* `-1` sentinel stamped by listShallow). Page-bounded by construction:
+	* only the dirs actually collected are counted, ONE `countChildrenMany`
+	* round-trip (per-dir `countChildren` fallback for indexes without it),
+	* so the cost is Σ direct children of the page's dirs — never the
+	* whole-subtree scan the retired `countChildrenGrouped` performed.
+	*/
+	async fillChildrenCounts(entries) {
+		const dirs = entries.filter((e) => e.meta?.kind === "did-space:directory");
+		if (dirs.length === 0) return;
+		const keyOf = (e) => `${this.treePath(e.path)}/`;
+		if (this.treeIndex.countChildrenMany) {
+			const counts = await this.treeIndex.countChildrenMany(dirs.map(keyOf));
+			for (const e of dirs) e.meta.childrenCount = counts.get(keyOf(e)) ?? 0;
+			return;
+		}
+		for (const e of dirs) e.meta.childrenCount = await this.treeIndex.countChildren(keyOf(e));
+	}
+	async listDeep(afsBasePath, prefix, limit, maxDepth, entries, includeContent = false) {
+		const prefixDepth = afsBasePath === "/" ? 0 : afsBasePath.split("/").filter(Boolean).length;
+		const seenDirs = /* @__PURE__ */ new Set();
+		let cursor;
+		do {
+			const result = await this.treeIndex.listEntries(prefix, {
+				limit: LIST_MAX_LIMIT,
+				cursor,
+				includeContent
+			});
+			for (const treeEntry of result.entries) {
+				if (entries.length >= limit) return;
+				const parts = treeEntry.path.slice(prefix.length).split("/").filter(Boolean);
+				for (let i = 0; i < parts.length - 1; i++) {
+					if (i + 1 > maxDepth) break;
+					const dirKey = prefix + parts.slice(0, i + 1).join("/");
+					if (!seenDirs.has(dirKey)) {
+						seenDirs.add(dirKey);
+						entries.push(this.buildEntry(`/${dirKey}`, {
+							id: basenameId(dirKey),
+							meta: {
+								kind: "did-space:directory",
+								childrenCount: -1
+							}
+						}));
+					}
+				}
+				const path = `/${treeEntry.path}`;
+				if (path.split("/").filter(Boolean).length - prefixDepth <= maxDepth) entries.push(this.buildEntry(path, {
+					id: basenameId(path),
+					...includeContent && await this.verifiedInline(treeEntry) !== null ? { content: treeEntry.content } : {},
+					meta: {
+						kind: "did-space:file",
+						cid: treeEntry.cid,
+						size: treeEntry.size,
+						mimeType: treeEntry.mimeType
+					},
+					createdAt: new Date(treeEntry.ctime),
+					updatedAt: new Date(treeEntry.mtime)
+				}));
+			}
+			cursor = result.hasMore ? result.cursor : void 0;
+		} while (cursor && entries.length < limit);
+	}
+	/**
+	* Task 1.9: list changelog rows starting after `cursor` (seq number).
+	* Returns rows as AFSEntry objects + meta.cursor pointing to the last row's seq.
+	*/
+	async listChangelog(cursor, limit) {
+		const sinceSeq = Number(cursor) || 0;
+		const effectiveLimit = Math.min(limit || LIST_MAX_LIMIT, LIST_MAX_LIMIT);
+		const watermark = await this.treeIndex.getCompactedBelowSeq?.() ?? 0;
+		if (watermark > 0 && sinceSeq < watermark) throw new AFSCompactedError("/.changelog", String(watermark));
+		const changelog = await this.treeIndex.getChangelogSince(sinceSeq, effectiveLimit);
+		return {
+			data: changelog.entries.map((row) => this.buildEntry(`/.changelog/${row.seq}`, {
+				content: null,
+				meta: {
+					kind: CHANGELOG_ROW_KIND,
+					extra: serializeChangelogEntry(row)
+				}
+			})),
+			meta: {
+				cursor: String(changelog.cursor),
+				hasMore: changelog.hasMore
+			}
+		};
+	}
+	/**
+	* Promote write + delete to the object form so callers can discover the
+	* `ifMatch` sub-capability (CLAUDE.md "Sub-capability schema"). The base impl
+	* (base.ts) returns plain booleans; without this override the if-match
+	* conformance suite's `getCapabilityFeature("write","ifMatch")` reads nothing
+	* and the suite skips. Mirrors AFSFS's override (fs/src/index.ts).
+	*/
+	getOperationsDeclaration() {
+		const ops = super.getOperationsDeclaration();
+		if (typeof ops.write === "boolean" ? ops.write : ops.write?.supported === true) ops.write = {
+			supported: true,
+			features: {
+				ifMatch: true,
+				treeMerge: true,
+				treeToggle: true,
+				treeIncrement: true,
+				treeListAdd: true,
+				treeListRemove: true,
+				batchPushdown: true
+			}
+		};
+		if (typeof ops.delete === "boolean" ? ops.delete : ops.delete?.supported === true) ops.delete = {
+			supported: true,
+			features: { ifMatch: true }
+		};
+		if (typeof ops.list === "boolean" ? ops.list : ops.list?.supported === true) ops.list = {
+			supported: true,
+			features: {
+				orderBy: true,
+				includeContent: true
+			}
+		};
+		return ops;
+	}
+	async readCapabilities(_ctx) {
+		const operations = this.getOperationsDeclaration();
+		const queryable = typeof this.treeIndex.query === "function";
+		if (queryable) operations.query = true;
+		return {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				description: this.description || "DID-scoped persistent storage with CID-based deduplication",
+				tools: [],
+				actions: [],
+				operations,
+				...queryable ? { standardActions: [collectionQueryStandardAction({
+					doc: true,
+					groupBy: true,
+					annotate: true,
+					aggregate: true
+				})] } : {}
+			},
+			meta: {
+				kind: "afs:capabilities",
+				operations
+			}
+		};
+	}
+	/**
+	* Typed collection query over a directory of records (design §3.5).
+	*
+	* - dir-per-record (`spec.doc`): direct child dirs joined with their
+	*   `<dir>/<doc>` document; file-per-record (no doc): direct child files'
+	*   inline content is the record.
+	* - where/orderBy/pagination/total/groupBy execute inside the TreeIndex
+	*   engine (SQL or in-memory — lockstep-tested). select + annotate.memberOf
+	*   are page-level post-processing here, identical across backends.
+	* - Strict contract: spec arrives core-validated; provider constraints
+	*   (single orderBy key, no text) throw AFSValidationError. An index
+	*   without the engine (e.g. not-yet-migrated backends) throws
+	*   AFSUnsupportedError — and is never declared in capabilities.
+	*/
+	async query(path, spec, _options) {
+		if (!this.treeIndex.query) throw new AFSUnsupportedError("query", "Collection query is not supported by this index backend");
+		const afsPath = joinURL("/", path);
+		if (this.isVirtualPath(afsPath) || matchSharesVirtualPath(afsPath)) throw new AFSValidationError(`Invalid query spec: path: not a queryable collection: ${afsPath}`);
+		assertTreeQuerySpec(spec);
+		const prefix = this.treeListPrefix(afsPath);
+		if (afsPath !== "/") {
+			if (!await this.treeIndex.get(this.treePath(afsPath), { includeContent: false }) && !await this.treeIndex.hasChildren(prefix)) throw new AFSNotFoundError(afsPath);
+		}
+		const result = await this.treeIndex.query(prefix, spec);
+		let memberValues;
+		if (spec.annotate) {
+			memberValues = /* @__PURE__ */ new Set();
+			try {
+				const ref = await this.read(joinURL("/", spec.annotate.memberOf.doc));
+				const raw = resolveFieldPath(parseRecordText(typeof ref.data?.content === "string" ? ref.data.content : void 0), spec.annotate.memberOf.field);
+				if (Array.isArray(raw)) for (const v of raw) memberValues.add(typeof v === "string" ? v.toLowerCase() : String(v));
+			} catch {}
+		}
+		const entries = [];
+		for (const row of result.rows) entries.push(await this.queryRowToEntry(row, spec, memberValues));
+		const out = {
+			entries,
+			total: result.total
+		};
+		if (result.cursor) out.cursor = result.cursor;
+		if (result.groups) out.groups = result.groups;
+		if (result.aggregateGroups) out.aggregateGroups = result.aggregateGroups;
+		if (result.seekOffset !== void 0) out.seekOffset = result.seekOffset;
+		if (this.treeIndex.getPrefixWatermark) {
+			const version = await this.treeIndex.getPrefixWatermark(prefix);
+			if (version != null) out.liveSeq = String(version);
+		}
+		return out;
+	}
+	/** Map an engine row to an AFSEntry (mirrors the list handlers' shapes). */
+	async queryRowToEntry(row, spec, memberValues) {
+		const isDir = row.kind === "dir";
+		const displayPath = isDir ? `/${row.path.slice(0, -1)}` : `/${row.path}`;
+		const verifyCid = isDir ? row.contentCid : row.cid;
+		const verified = row.content !== void 0 && verifyCid ? await this.verifiedInline({
+			cid: verifyCid,
+			content: row.content
+		}) : null;
+		let content;
+		if (spec.select) content = projectRecordFields(parseRecordText(verified ?? void 0), spec.select);
+		else if (verified !== null) content = verified;
+		const entry = this.buildEntry(displayPath, {
+			id: basenameId(displayPath),
+			...content !== void 0 ? { content } : {},
+			meta: isDir ? {
+				...row.metadata ?? {},
+				kind: "did-space:directory",
+				childrenCount: -1,
+				size: row.size
+			} : {
+				...row.metadata ?? {},
+				kind: "did-space:file",
+				cid: row.cid,
+				size: row.size,
+				mimeType: row.mimeType
+			},
+			createdAt: new Date(row.ctime),
+			updatedAt: new Date(row.mtime)
+		});
+		if (spec.annotate && memberValues) {
+			const { by, as } = spec.annotate.memberOf;
+			const byValue = by === "$id" ? row.name : resolveFieldPath(parseRecordText(verified ?? row.content), by);
+			const member = byValue != null && memberValues.has(typeof byValue === "string" ? byValue.toLowerCase() : String(byValue));
+			entry._derived = { [as]: member ? "1" : "" };
+		}
+		return entry;
+	}
+	async readHandler(ctx) {
+		const afsPath = joinURL("/", ctx.params.path ?? "");
+		const sharesMatch = matchSharesVirtualPath(afsPath);
+		if (sharesMatch && this.shareResolver && !this.shareTreePrefix) {
+			const result = await new ShareVirtualHandler(this.shareResolver, this.did).read(sharesMatch);
+			if (!result) throw new AFSNotFoundError(afsPath);
+			return result.data;
+		}
+		const normPath = afsPath.startsWith("/") ? afsPath.slice(1) : afsPath;
+		if (normPath.startsWith(".objects/")) {
+			const cid = normPath.slice(9);
+			if (!await time("ds.ref", () => this.treeIndex.isReferenced(cid))) throw new AFSNotFoundError(afsPath);
+			const obj = await time("ds.obj", () => this.objectStore.get(this.objectKey(cid)));
+			if (!obj) throw new AFSNotFoundError(afsPath);
+			const bytes = new Uint8Array(await time("ds.body", () => obj.arrayBuffer()));
+			return this.buildEntry(afsPath, {
+				content: bytes,
+				meta: {
+					kind: "did-space:object",
+					cid,
+					size: bytes.length
+				}
+			});
+		}
+		if (afsPath === "/") {
+			const childrenCount = await this.treeIndex.countChildren(this.treeListPrefix("/"));
+			return this.buildEntry(afsPath, {
+				content: `DID Space root for ${this.did} (${childrenCount} entries)`,
+				meta: {
+					kind: "did-space:root",
+					childrenCount
+				}
+			});
+		}
+		const entry = await time("ds.idx", () => this.treeIndex.get(this.treePath(afsPath)));
+		if (entry) {
+			if (entry.content !== void 0 && isTextMime(entry.mimeType)) {
+				if (await time("ds.inl", async () => {
+					return await computeCID(entry.content) === entry.cid;
+				})) return this.buildEntry(afsPath, {
+					content: entry.content,
+					meta: {
+						...entry.metadata ?? {},
+						kind: "did-space:file",
+						size: entry.size,
+						cid: entry.cid,
+						mimeType: entry.mimeType,
+						version: entry.cid
+					},
+					createdAt: new Date(entry.ctime),
+					updatedAt: new Date(entry.mtime)
+				});
+				log.warn(`[did-space] inline content failed cid verification at ${afsPath} (cid=${entry.cid}) — serving from objects; row will self-repair on next write`);
+			}
+			const obj = await time("ds.obj", () => this.objectStore.get(this.objectKey(entry.cid)));
+			const content = await time("ds.body", async () => obj ? isTextMime(entry.mimeType) ? await obj.text() : await obj.arrayBuffer() : isTextMime(entry.mimeType) ? "" : /* @__PURE__ */ new ArrayBuffer(0));
+			return this.buildEntry(afsPath, {
+				content,
+				meta: {
+					...entry.metadata ?? {},
+					kind: "did-space:file",
+					size: entry.size,
+					cid: entry.cid,
+					mimeType: entry.mimeType,
+					version: entry.cid
+				},
+				createdAt: new Date(entry.ctime),
+				updatedAt: new Date(entry.mtime)
+			});
+		}
+		if (await this.isDirectory(afsPath)) {
+			const childrenCount = await this.treeIndex.countChildren(this.treeListPrefix(afsPath));
+			return this.buildEntry(afsPath, {
+				content: `Directory: ${afsPath} (${childrenCount} entries)`,
+				meta: {
+					kind: "did-space:directory",
+					childrenCount
+				}
+			});
+		}
+		throw new AFSNotFoundError(afsPath);
+	}
+	/**
+	* presignRead — path-keyed read-grant capability (preview-r2-direct §3).
+	*
+	* Resolves `path` in THIS provider's (prefix-isolated) view exactly like
+	* `read`/`stat` (`treeIndex.get(treePath(path))`, incl. the same null-byte /
+	* `..`-segment guards). iff the resolved entry has a cid AND a signer with
+	* `presignGet` is present → mint a short-TTL presigned GET with the
+	* Content-Type baked in, and return `{ url, expiresAt }`.
+	*
+	* The path resolution IS the authorization: a caller can only presign what
+	* `read` would already return. Prefix isolation is inherited from the view's
+	* `PrefixedTreeIndex` — no separate object-level `isReferenced(cid)` is needed
+	* (that primitive is for the cid-keyed `.objects/{cid}` path, which has no
+	* tree path). NEVER throws to the caller: no signer (Node) / non-CAS / no cid /
+	* unresolved / any internal error → `null`, and the raw handler then falls back
+	* to the worker serve path. TTL = `DOWNLOAD_GRANT_TTL_SEC` (2h) — never the 7d
+	* signer cap (§8.3).
+	*/
+	async presignRead(path, opts) {
+		try {
+			const entry = await this.treeIndex.get(this.treePath(path), { includeContent: false });
+			if (!entry?.cid) return null;
+			if (this.signer == null || typeof this.signer.presignGet !== "function") return null;
+			const g = await this.signer.presignGet({
+				objectKey: this.objectKey(entry.cid),
+				expiresInSec: DOWNLOAD_GRANT_TTL_SEC,
+				responseContentType: opts?.responseContentType
+			});
+			return {
+				url: g.url,
+				expiresAt: g.expiresAt
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Re-verify an entry's inline copy against its cid (§2.I list contract).
+	* Returns the content when verified, null otherwise (best-effort miss).
+	*/
+	async verifiedInline(entry) {
+		if (entry.content === void 0) return null;
+		return await computeCID(entry.content) === entry.cid ? entry.content : null;
+	}
+	/**
+	* Returns true if the given AFS path is a virtual D4-protected path
+	* (.objects/* or .changelog/*).
+	*/
+	isVirtualPath(afsPath) {
+		const norm = afsPath.startsWith("/") ? afsPath.slice(1) : afsPath;
+		return norm === ".objects" || norm.startsWith(".objects/") || norm === ".changelog" || norm.startsWith(".changelog/");
+	}
+	async writeHandler(ctx, payload) {
+		const afsPath = joinURL("/", ctx.params.path ?? "");
+		if (this.isVirtualPath(afsPath)) throw new AFSForbiddenError(afsPath, "virtual_path");
+		if (isShareReservedPath(afsPath)) throw new AFSForbiddenError(afsPath, "share-path-reserved");
+		const writeIfMatch = ctx.options?.ifMatch;
+		if (writeIfMatch !== void 0) {
+			const current = await this.treeIndex.get(this.treePath(afsPath), { includeContent: false });
+			if (ifMatchPreconditionFailed(writeIfMatch, current)) throw new AFSConflictError(afsPath, {
+				cid: current?.cid ?? null,
+				mtime: current?.mtime ?? null
+			});
+		}
+		if (payload.content === void 0 && payload.meta !== void 0) return { data: this.buildEntry(afsPath, { meta: {
+			kind: "did-space:file",
+			...payload.meta
+		} }) };
+		let bytes;
+		let storeValue;
+		if (payload.content instanceof Uint8Array) {
+			bytes = payload.content;
+			storeValue = bytes.buffer;
+		} else if (payload.content instanceof ArrayBuffer) {
+			bytes = new Uint8Array(payload.content);
+			storeValue = payload.content;
+		} else {
+			const text = typeof payload.content === "string" ? payload.content : JSON.stringify(payload.content);
+			bytes = new TextEncoder().encode(text);
+			storeValue = text;
+		}
+		const cid = await computeCID(bytes);
+		const treePath = this.treePath(afsPath);
+		await applyShareWriteHook({
+			...this.shareHookArgs(afsPath, treePath),
+			bytes,
+			cid,
+			resolver: this.shareResolver,
+			phase: "pre-io"
+		});
+		if (!await this.objectStore.head(this.objectKey(cid))) await this.objectStore.put(this.objectKey(cid), storeValue);
+		const writeMeta = ctx.options?.meta;
+		const writeDeviceId = typeof writeMeta?.deviceId === "string" && writeMeta.deviceId ? writeMeta.deviceId : this.deviceId;
+		const now = typeof writeMeta?.mtime === "number" ? writeMeta.mtime : Date.now();
+		let mimeType = payload.meta?.mimeType ?? detectMimeType(afsPath) ?? void 0;
+		if (!mimeType && (payload.content instanceof Uint8Array || payload.content instanceof ArrayBuffer)) mimeType = "application/octet-stream";
+		const ctime = resolveCtime(payload.meta, now);
+		const treeEntry = {
+			cid,
+			size: bytes.length,
+			mtime: now,
+			ctime,
+			mimeType
+		};
+		const appMeta = extractApplicationMeta(payload.meta);
+		if (appMeta) {
+			if (typeof appMeta.dedupScope === "string") {
+				treeEntry.dedupScope = appMeta.dedupScope;
+				delete appMeta.dedupScope;
+			}
+			if (typeof appMeta.dedupKey === "string") treeEntry.dedupKey = appMeta.dedupKey;
+			if (Object.keys(appMeta).length > 0) treeEntry.metadata = appMeta;
+		}
+		if (typeof storeValue === "string") treeEntry.content = storeValue;
+		else {
+			const inlineText = decodeInlineText(bytes, mimeType);
+			if (inlineText !== null) treeEntry.content = inlineText;
+		}
+		const { oldCid } = await this.treeIndex.put(treePath, treeEntry, { deviceId: writeDeviceId });
+		if (this.gcQueue) {
+			await this.gcQueue.remove(cid);
+			if (oldCid && oldCid !== cid) await this.gcQueue.enqueue([oldCid]);
+		}
+		await applyShareWriteHook({
+			...this.shareHookArgs(afsPath, treePath),
+			bytes,
+			cid,
+			resolver: this.shareResolver,
+			phase: "post-io"
+		});
+		await applyBlockletWriteHook({
+			...this.blockletHookArgs(afsPath, treePath),
+			bytes,
+			resolver: this.blockletResolver
+		});
+		if (afsPath.endsWith(".ash")) this.emit({
+			type: SCRIPT_EVENT_TYPES.REGISTERED,
+			path: afsPath,
+			data: { runtime: "ash" }
+		});
+		const meta = {
+			...appMeta ?? {},
+			kind: "did-space:file",
+			size: treeEntry.size,
+			cid,
+			mimeType: treeEntry.mimeType
+		};
+		if (this.treeIndex.getPrefixWatermark) {
+			const version = await this.treeIndex.getPrefixWatermark(this.treePath(afsPath));
+			if (version != null) meta.liveSeq = String(version);
+		}
+		return { data: this.buildEntry(afsPath, {
+			content: storeValue,
+			meta,
+			createdAt: new Date(treeEntry.ctime),
+			updatedAt: new Date(treeEntry.mtime)
+		}) };
+	}
+	async deleteHandler(ctx) {
+		const afsPath = joinURL("/", ctx.params.path ?? "");
+		if (this.isVirtualPath(afsPath)) throw new AFSForbiddenError(afsPath, "virtual_path");
+		if (isShareReservedPath(afsPath)) throw new AFSForbiddenError(afsPath, "share-path-reserved");
+		const treePath = this.treePath(afsPath);
+		const deleteMeta = ctx.options?.meta;
+		const deleteIfMatch = deleteMeta?.ifMatch;
+		if (deleteIfMatch !== void 0) {
+			const current = await this.treeIndex.get(treePath, { includeContent: false });
+			if (!current || current.cid !== deleteIfMatch) throw new AFSConflictError(afsPath, {
+				cid: current?.cid ?? null,
+				mtime: current?.mtime ?? null
+			});
+		}
+		const deleteOpts = {
+			deviceId: typeof deleteMeta?.deviceId === "string" && deleteMeta.deviceId ? deleteMeta.deviceId : this.deviceId,
+			...typeof deleteMeta?.mtime === "number" ? { mtime: deleteMeta.mtime } : {}
+		};
+		const entry = await this.treeIndex.get(treePath, { includeContent: false });
+		if (entry) {
+			await this.gcQueue?.enqueue([entry.cid]);
+			await this.treeIndex.delete(treePath, deleteOpts);
+			await applyShareDeleteHook({
+				...this.shareHookArgs(afsPath, treePath),
+				resolver: this.shareResolver
+			});
+			await applyBlockletDeleteHook({
+				...this.blockletHookArgs(afsPath, treePath),
+				resolver: this.blockletResolver
+			});
+			if (afsPath.endsWith(".ash")) this.emit({
+				type: SCRIPT_EVENT_TYPES.UNREGISTERED,
+				path: afsPath,
+				data: { runtime: "ash" }
+			});
+			return {
+				path: afsPath,
+				deleted: true
+			};
+		}
+		const prefix = this.treeListPrefix(afsPath);
+		if (this.gcQueue) {
+			const cids = await this.collectCIDsByPrefix(prefix);
+			if (cids.length > 0) await this.gcQueue.enqueue(cids);
+		}
+		if (await this.treeIndex.deleteByPrefix(prefix, deleteOpts) === 0) throw new AFSNotFoundError(afsPath);
+		return {
+			path: afsPath,
+			deleted: true
+		};
+	}
+	/** Conflict failure shaped exactly like the single-op AFSConflictError surface. */
+	batchConflictFailure(afsPath, conflict) {
+		return {
+			path: afsPath,
+			success: false,
+			error: `Write conflict at ${afsPath}`,
+			code: "AFS_CONFLICT",
+			conflict
+		};
+	}
+	/** ONE preflight read for a batch — getMany when the index has it, per-path get otherwise. */
+	async batchPreread(treePaths) {
+		if (this.treeIndex.getMany) return this.treeIndex.getMany(treePaths);
+		return new Map(await Promise.all(treePaths.map(async (tp) => [tp, await this.treeIndex.get(tp)])));
+	}
+	/** Run `fn` over `items` with bounded concurrency (Workers cap: 6 sockets). */
+	async boundedAll(items, limit, fn) {
+		let next = 0;
+		const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+			while (next < items.length) {
+				const item = items[next++];
+				await fn(item);
+			}
+		});
+		await Promise.all(workers);
+	}
+	/**
+	* Native batch read (issue #808 follow-up) — the render fast path. Resolves the
+	* whole path set with ONE `treeIndex.getMany` (chunked `IN(…)`, which carries
+	* inline content when the index has it), so small cid-verified inline files are
+	* served with ZERO R2 gets; only the (few, large) non-inline entries fall back
+	* to bounded-concurrent `objectStore.get`. Mirrors the single-read handler's
+	* inline-verify → objects cascade per entry. File-oriented: getMany matches
+	* `kind='file'`, so directory / absent paths come back AFS_NOT_FOUND (callers
+	* reading directories use `list`/`read`).
+	*/
+	async batchRead(entries, _options) {
+		const afsPaths = entries.map((e) => joinURL("/", e.path));
+		const treePaths = afsPaths.map((p) => this.treePath(p));
+		const preread = await this.batchPreread(treePaths);
+		const results = new Array(entries.length);
+		const fileEntry = (afsPath, entry, content) => this.buildEntry(afsPath, {
+			content,
+			meta: {
+				...entry.metadata ?? {},
+				kind: "did-space:file",
+				size: entry.size,
+				cid: entry.cid,
+				mimeType: entry.mimeType,
+				version: entry.cid
+			},
+			createdAt: new Date(entry.ctime),
+			updatedAt: new Date(entry.mtime)
+		});
+		const needObject = [];
+		for (let i = 0; i < entries.length; i++) {
+			const entry = preread.get(treePaths[i]);
+			if (!entry) {
+				results[i] = {
+					path: afsPaths[i],
+					success: false,
+					error: `Path not found: ${afsPaths[i]}`,
+					code: "AFS_NOT_FOUND"
+				};
+				continue;
+			}
+			if (entry.content !== void 0 && isTextMime(entry.mimeType)) {
+				if (await computeCID(entry.content) === entry.cid) {
+					results[i] = {
+						path: afsPaths[i],
+						success: true,
+						data: fileEntry(afsPaths[i], entry, entry.content)
+					};
+					continue;
+				}
+				log.warn(`[did-space] inline content failed cid verification at ${afsPaths[i]} (cid=${entry.cid}) — serving from objects; row will self-repair on next write`);
+			}
+			needObject.push(i);
+		}
+		await this.boundedAll(needObject, 6, async (i) => {
+			const entry = preread.get(treePaths[i]);
+			const obj = await this.objectStore.get(this.objectKey(entry.cid));
+			const isText = isTextMime(entry.mimeType);
+			const content = obj ? isText ? await obj.text() : await obj.arrayBuffer() : isText ? "" : /* @__PURE__ */ new ArrayBuffer(0);
+			results[i] = {
+				path: afsPaths[i],
+				success: true,
+				data: fileEntry(afsPaths[i], entry, content)
+			};
+		});
+		const succeeded = results.filter((r) => r.success).length;
+		return {
+			results,
+			succeeded,
+			failed: entries.length - succeeded
+		};
+	}
+	/**
+	* Native batch write — the CF-subrequest-budget merge (§4.3): eight-step
+	* order aligned point-for-point with the single write path (preread BEFORE
+	* share pre-io, so a stale ifMatch on a `.share` declaration yields 409,
+	* never a share error):
+	*   1 shape/decode/computeCID → 2 ONE preread (conflict/skip exit here —
+	*   no share hook, no R2 upload) → 3 share pre-io (survivors) → 4 in-batch
+	*   CID dedup → 5 unconditional R2 put (unique cids, bounded ≤6 —
+	*   P0-measured wall-time) → 6 treeIndex.batchPutEntries (single db.batch)
+	*   → 7 gcQueue removeMany/enqueue → 8 share post-io + per-entry results.
+	*/
+	async batchWrite(entries, _options) {
+		if (entries.some((e) => e.options?.dedupBy || e.options?.dedupKey)) {
+			const seq = [];
+			let succeeded$1 = 0;
+			for (const entry of entries) {
+				const afsPath = joinURL("/", entry.path);
+				try {
+					const payload = entry.content;
+					if (!payload || payload.content === void 0) throw new AFSValidationError("Batch write requires entry content");
+					const opts = {
+						...entry.options ?? {},
+						...entry.mode ? { mode: entry.mode } : {}
+					};
+					const res = await this.write(entry.path, payload, opts);
+					seq.push({
+						path: res.data.path,
+						success: true,
+						data: res.data
+					});
+					succeeded$1++;
+				} catch (err) {
+					seq.push({
+						path: afsPath,
+						success: false,
+						error: err instanceof Error ? err.message : String(err),
+						code: err instanceof AFSConflictError ? "AFS_CONFLICT" : err?.code ?? "AFS_WRITE_ERROR"
+					});
+				}
+			}
+			return {
+				results: seq,
+				succeeded: succeeded$1,
+				failed: entries.length - succeeded$1
+			};
+		}
+		const results = new Array(entries.length);
+		const prepared = [];
+		for (let i = 0; i < entries.length; i++) {
+			const entry = entries[i];
+			const afsPath = joinURL("/", entry.path);
+			if (entry.patches || entry.mode && entry.mode !== "replace") {
+				results[i] = {
+					path: afsPath,
+					success: false,
+					error: `Batch write supports replace-mode content writes only (got mode '${entry.mode ?? "patches"}')`,
+					code: "AFS_UNSUPPORTED"
+				};
+				continue;
+			}
+			if (this.isVirtualPath(afsPath) || isShareReservedPath(afsPath)) {
+				results[i] = {
+					path: afsPath,
+					success: false,
+					error: `Forbidden at ${afsPath}: virtual_path`,
+					code: "AFS_FORBIDDEN"
+				};
+				continue;
+			}
+			const payload = entry.content ?? {};
+			if (payload.content === void 0) {
+				results[i] = {
+					path: afsPath,
+					success: false,
+					error: "Batch write requires entry content (meta-only writes are single-op)",
+					code: "AFS_VALIDATION_ERROR"
+				};
+				continue;
+			}
+			let bytes;
+			let storeValue;
+			if (payload.content instanceof Uint8Array) {
+				bytes = payload.content;
+				storeValue = bytes.buffer;
+			} else if (payload.content instanceof ArrayBuffer) {
+				bytes = new Uint8Array(payload.content);
+				storeValue = payload.content;
+			} else {
+				const text = typeof payload.content === "string" ? payload.content : JSON.stringify(payload.content);
+				bytes = new TextEncoder().encode(text);
+				storeValue = text;
+			}
+			const cid = await computeCID(bytes);
+			const writeOptions = entry.options;
+			const writeMeta = writeOptions?.meta;
+			const deviceId = typeof writeMeta?.deviceId === "string" && writeMeta.deviceId ? writeMeta.deviceId : this.deviceId;
+			const now = typeof writeMeta?.mtime === "number" ? writeMeta.mtime : Date.now();
+			let mimeType = payload.meta?.mimeType ?? detectMimeType(afsPath) ?? void 0;
+			if (!mimeType && (payload.content instanceof Uint8Array || payload.content instanceof ArrayBuffer)) mimeType = "application/octet-stream";
+			const ctime = resolveCtime(payload.meta, now);
+			const treeEntry = {
+				cid,
+				size: bytes.length,
+				mtime: now,
+				ctime,
+				mimeType
+			};
+			const appMeta = extractApplicationMeta(payload.meta);
+			if (appMeta) {
+				try {
+					assertMetadataSize(appMeta, afsPath);
+				} catch (err) {
+					results[i] = {
+						path: afsPath,
+						success: false,
+						error: err instanceof Error ? err.message : String(err),
+						code: err.code ?? "AFS_VALIDATION_ERROR"
+					};
+					continue;
+				}
+				treeEntry.metadata = appMeta;
+			}
+			if (typeof storeValue === "string") treeEntry.content = storeValue;
+			else {
+				const inlineText = decodeInlineText(bytes, mimeType);
+				if (inlineText !== null) treeEntry.content = inlineText;
+			}
+			prepared.push({
+				i,
+				afsPath,
+				treePath: this.treePath(afsPath),
+				bytes,
+				storeValue,
+				cid,
+				treeEntry,
+				deviceId,
+				ifMatch: writeOptions?.ifMatch
+			});
+		}
+		const preread = await this.batchPreread(prepared.map((p) => p.treePath));
+		const skipped = [];
+		let live = [];
+		for (const p of prepared) {
+			const existing = preread.get(p.treePath) ?? null;
+			if (ifMatchPreconditionFailed(p.ifMatch, existing)) {
+				results[p.i] = this.batchConflictFailure(p.afsPath, {
+					currentCid: existing?.cid ?? null,
+					currentMtime: existing?.mtime ?? null,
+					currentDeviceId: null
+				});
+				continue;
+			}
+			live.push(p);
+		}
+		const preIoOk = [];
+		for (const p of live) try {
+			await applyShareWriteHook({
+				...this.shareHookArgs(p.afsPath, p.treePath),
+				bytes: p.bytes,
+				cid: p.cid,
+				resolver: this.shareResolver,
+				phase: "pre-io"
+			});
+			preIoOk.push(p);
+		} catch (err) {
+			results[p.i] = {
+				path: p.afsPath,
+				success: false,
+				error: err instanceof Error ? err.message : String(err),
+				code: err.code
+			};
+		}
+		live = preIoOk;
+		const uniqueCids = /* @__PURE__ */ new Map();
+		for (const p of live) if (!uniqueCids.has(p.cid)) uniqueCids.set(p.cid, p);
+		const uploadFailed = /* @__PURE__ */ new Map();
+		const uploaded = [];
+		await this.boundedAll([...uniqueCids.values()], 6, async (p) => {
+			try {
+				await this.objectStore.put(this.objectKey(p.cid), p.storeValue);
+				uploaded.push(p.cid);
+			} catch (err) {
+				uploadFailed.set(p.cid, err instanceof Error ? err.message : String(err));
+			}
+		});
+		if (uploadFailed.size > 0) {
+			const stillLive = [];
+			for (const p of live) {
+				const failure = uploadFailed.get(p.cid);
+				if (failure !== void 0) results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: `R2 put failed: ${failure}`
+				};
+				else stillLive.push(p);
+			}
+			live = stillLive;
+		}
+		let indexResults = [];
+		if (live.length > 0) {
+			const batchEntries = live.map((p) => ({
+				path: p.treePath,
+				entry: p.treeEntry,
+				opts: { deviceId: p.deviceId }
+			}));
+			try {
+				indexResults = this.treeIndex.batchPutEntries ? await this.treeIndex.batchPutEntries(batchEntries, { preread }) : await loopBatchPutEntries(this.treeIndex, batchEntries, { preread });
+			} catch (err) {
+				await this.gcQueue?.enqueue(uploaded);
+				const message = err instanceof Error ? err.message : String(err);
+				for (const p of live) results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: message
+				};
+				live = [];
+			}
+		}
+		const written = [];
+		live.forEach((p, j) => {
+			const r = indexResults[j];
+			if (!r) {
+				results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: "index batch returned no result"
+				};
+				return;
+			}
+			if (r.conflict) {
+				results[p.i] = this.batchConflictFailure(p.afsPath, r.conflict);
+				return;
+			}
+			if (r.error) {
+				results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: r.error
+				};
+				return;
+			}
+			if (r.skipped) {
+				skipped.push(p);
+				return;
+			}
+			written.push({
+				p,
+				oldCid: r.oldCid,
+				liveSeq: r.liveSeq
+			});
+		});
+		if (this.gcQueue) {
+			const reReferenced = [...new Set([...written.map((w) => w.p.cid), ...skipped.map((s) => s.cid)])];
+			if (reReferenced.length > 0) if (this.gcQueue.removeMany) await this.gcQueue.removeMany(reReferenced);
+			else for (const cid of reReferenced) await this.gcQueue.remove(cid);
+			const replaced = [...new Set(written.filter((w) => w.oldCid && w.oldCid !== w.p.cid).map((w) => w.oldCid))];
+			if (replaced.length > 0) await this.gcQueue.enqueue(replaced);
+		}
+		for (const w of written) {
+			try {
+				await applyShareWriteHook({
+					...this.shareHookArgs(w.p.afsPath, w.p.treePath),
+					bytes: w.p.bytes,
+					cid: w.p.cid,
+					resolver: this.shareResolver,
+					phase: "post-io"
+				});
+			} catch (err) {
+				w.error = err instanceof Error ? err.message : String(err);
+			}
+			if (w.p.afsPath.endsWith(".ash")) this.emit({
+				type: SCRIPT_EVENT_TYPES.REGISTERED,
+				path: w.p.afsPath,
+				data: { runtime: "ash" }
+			});
+		}
+		const maxSeqByPrefix = /* @__PURE__ */ new Map();
+		for (const w of written) {
+			if (typeof w.liveSeq !== "number") continue;
+			const wm = watermarkWritePrefix(w.p.treePath);
+			if (wm === null) continue;
+			maxSeqByPrefix.set(wm, Math.max(maxSeqByPrefix.get(wm) ?? 0, w.liveSeq));
+		}
+		for (const s of skipped) {
+			const wm = watermarkWritePrefix(s.treePath);
+			let liveSeq = wm !== null ? maxSeqByPrefix.get(wm) : void 0;
+			if (liveSeq === void 0 && this.treeIndex.getPrefixWatermark) liveSeq = await this.treeIndex.getPrefixWatermark(s.treePath) ?? void 0;
+			results[s.i] = {
+				path: s.afsPath,
+				success: true,
+				data: this.buildBatchWriteData(s, liveSeq)
+			};
+		}
+		for (const w of written) {
+			if (w.error) {
+				results[w.p.i] = {
+					path: w.p.afsPath,
+					success: false,
+					error: w.error
+				};
+				continue;
+			}
+			results[w.p.i] = {
+				path: w.p.afsPath,
+				success: true,
+				data: this.buildBatchWriteData(w.p, w.liveSeq)
+			};
+		}
+		const succeeded = results.filter((r) => r?.success).length;
+		return {
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	/** Write-echo entry — field-for-field the single-op writeHandler result. */
+	buildBatchWriteData(p, liveSeq) {
+		const meta = {
+			kind: "did-space:file",
+			size: p.treeEntry.size,
+			cid: p.cid,
+			mimeType: p.treeEntry.mimeType
+		};
+		if (liveSeq != null) meta.liveSeq = String(liveSeq);
+		return this.buildEntry(p.afsPath, {
+			content: p.storeValue,
+			meta,
+			createdAt: new Date(p.treeEntry.ctime),
+			updatedAt: new Date(p.treeEntry.mtime)
+		});
+	}
+	/** Build a failed AFSExecResult (shared across the three action handlers). */
+	uploadErr(code, message) {
+		return {
+			success: false,
+			error: {
+				code,
+				message
+			}
+		};
+	}
+	/**
+	* Session ownership isolation (§9 / §10): a session belongs to THIS view only
+	* when its scope equals this provider's storage scope. A different-scope (or
+	* unknown) session is treated as not-found — never confirm another user's
+	* session exists, and never let one view commit into another.
+	*/
+	ownsSession(session) {
+		return !!session && session.scope === (this.uploadScope ?? this.did);
+	}
+	/**
+	* Validate an action-supplied `path`. Unlike `@Write` handlers, action args
+	* carry NO router-layer traversal protection — `args.entries[].path` is raw
+	* client input, so we MUST normalize + reject traversal / reserved virtual
+	* prefixes explicitly (design §10). Returns the tree path on success.
+	*/
+	validateActionPath(afsPath) {
+		const norm = afsPath.startsWith("/") ? afsPath.slice(1) : afsPath;
+		if (this.isVirtualPath(afsPath) || isShareReservedPath(afsPath) || norm === ".actions" || norm.startsWith(".actions/")) return {
+			ok: false,
+			reason: `reserved path: ${afsPath}`
+		};
+		let treePath;
+		try {
+			treePath = this.treePath(afsPath);
+		} catch (err) {
+			return {
+				ok: false,
+				reason: err instanceof Error ? err.message : String(err)
+			};
+		}
+		return {
+			ok: true,
+			treePath
+		};
+	}
+	/**
+	* Action catalogue — the upload-plane + download-plane actions, always listed
+	* (protocol parity, T2.5). Each plane advertises its OWN capability flag:
+	* `grantCapability` for prepare-upload, the INDEPENDENT `downloadGrantCapability`
+	* for prepare-download (design §7.3 / Finding 4 — never reuse the upload flag,
+	* so the two planes can be advertised separately).
+	*/
+	listObjectPlaneActions(ctx) {
+		const grantCapable = this.signer != null;
+		const downloadGrantCapable = this.signer != null && typeof this.signer.presignGet === "function";
+		return { data: [...UPLOAD_ACTIONS, ...DOWNLOAD_ACTIONS].map((name) => this.buildEntry(joinURL(ctx.path, name), {
+			id: name,
+			meta: {
+				kind: "afs:executable",
+				...name === "prepare-upload" ? { grantCapability: grantCapable } : {},
+				...name === "prepare-download" ? { downloadGrantCapability: downloadGrantCapable } : {}
+			}
+		})) };
+	}
+	async execPrepareUpload(_ctx, args) {
+		if (!this.uploadSessionStore) return this.uploadErr("AFS_UNSUPPORTED", "upload plane not available");
+		const parsed = PrepareUploadArgsSchema.safeParse(args);
+		if (!parsed.success) return this.uploadErr("AFS_VALIDATION_ERROR", zodMessage(parsed.error));
+		const outEntries = [];
+		const storeEntries = [];
+		const seenPaths = /* @__PURE__ */ new Set();
+		for (const e of parsed.data.entries) {
+			const afsPath = joinURL("/", e.path);
+			const pv = this.validateActionPath(afsPath);
+			if (!pv.ok) return this.uploadErr("AFS_VALIDATION_ERROR", pv.reason);
+			if (seenPaths.has(afsPath)) return this.uploadErr("AFS_VALIDATION_ERROR", `duplicate path: ${afsPath}`);
+			seenPaths.add(afsPath);
+			let checksum;
+			try {
+				checksum = cidToChecksumSha256(e.cid);
+			} catch (err) {
+				return this.uploadErr("AFS_VALIDATION_ERROR", `bad cid for ${afsPath}: ${err instanceof Error ? err.message : err}`);
+			}
+			const objectKey = this.objectKey(e.cid);
+			let grant = null;
+			if (this.signer) {
+				const g = await this.signer.presignPut({
+					objectKey,
+					checksumSha256: checksum,
+					expiresInSec: GRANT_EXPIRES_SEC,
+					contentLength: e.size
+				});
+				grant = {
+					kind: "presigned-put",
+					url: g.url,
+					method: g.method,
+					signedHeaders: g.signedHeaders,
+					expiresAt: g.expiresAt
+				};
+			}
+			outEntries.push({
+				path: afsPath,
+				cid: e.cid,
+				status: "needs-upload",
+				objectKey,
+				checksumSha256: checksum,
+				grant
+			});
+			storeEntries.push({
+				path: afsPath,
+				cid: e.cid,
+				objectKey,
+				checksumSha256: checksum,
+				size: e.size,
+				mimeType: e.mimeType ?? null,
+				ifMatch: e.ifMatch ?? null,
+				deviceId: e.deviceId ?? null,
+				mtime: e.mtime ?? null,
+				status: "needs_upload"
+			});
+		}
+		const sessionId = crypto.randomUUID();
+		const expiresAt = Date.now() + UPLOAD_SESSION_TTL_MS;
+		await this.uploadSessionStore.createSession({
+			id: sessionId,
+			scope: this.uploadScope ?? this.did,
+			caller: null,
+			expiresAt,
+			entries: storeEntries
+		});
+		return {
+			success: true,
+			data: {
+				sessionId,
+				expiresAt: new Date(expiresAt).toISOString(),
+				entries: outEntries
+			}
+		};
+	}
+	async execPrepareDownload(_ctx, args) {
+		const parsed = PrepareDownloadArgsSchema.safeParse(args);
+		if (!parsed.success) return this.uploadErr("AFS_VALIDATION_ERROR", zodMessage(parsed.error));
+		const inputEntries = parsed.data.entries;
+		const cidValid = /* @__PURE__ */ new Map();
+		const validCids = [];
+		for (const e of inputEntries) {
+			if (cidValid.has(e.cid)) continue;
+			let ok = true;
+			try {
+				cidToChecksumSha256(e.cid);
+			} catch {
+				ok = false;
+			}
+			cidValid.set(e.cid, ok);
+			if (ok) validCids.push(e.cid);
+		}
+		let referenced = /* @__PURE__ */ new Set();
+		if (validCids.length > 0) try {
+			referenced = await this.treeIndex.isReferencedMany(validCids);
+		} catch {
+			return this.uploadErr("AFS_INTERNAL_ERROR", "prepare-download authorization unavailable");
+		}
+		const canSign = this.signer != null && typeof this.signer.presignGet === "function";
+		const grantByCid = /* @__PURE__ */ new Map();
+		for (const cid of referenced) if (canSign) {
+			const g = await this.signer.presignGet({
+				objectKey: this.objectKey(cid),
+				expiresInSec: DOWNLOAD_GRANT_TTL_SEC
+			});
+			grantByCid.set(cid, {
+				kind: "presigned-get",
+				url: g.url,
+				method: g.method,
+				signedHeaders: g.signedHeaders,
+				expiresAt: g.expiresAt
+			});
+		} else grantByCid.set(cid, null);
+		return {
+			success: true,
+			data: { entries: inputEntries.map((e) => {
+				if (!cidValid.get(e.cid)) return {
+					cid: e.cid,
+					status: "invalid"
+				};
+				if (!referenced.has(e.cid)) return {
+					cid: e.cid,
+					status: "forbidden"
+				};
+				return {
+					cid: e.cid,
+					status: "ok",
+					objectKey: this.objectKey(e.cid),
+					grant: grantByCid.get(e.cid) ?? null
+				};
+			}) }
+		};
+	}
+	async execCommitUpload(_ctx, args) {
+		if (!this.uploadSessionStore) return this.uploadErr("AFS_UNSUPPORTED", "upload plane not available");
+		const parsed = CommitUploadArgsSchema.safeParse(args);
+		if (!parsed.success) return this.uploadErr("AFS_VALIDATION_ERROR", zodMessage(parsed.error));
+		const { sessionId, entries } = parsed.data;
+		const session = await this.uploadSessionStore.getSession(sessionId);
+		if (!this.ownsSession(session)) return this.uploadErr("AFS_NOT_FOUND", "unknown upload session");
+		if (session.status === "aborted") return this.uploadErr("AFS_UNSUPPORTED", "session aborted");
+		if (session.status === "prepared" && session.expiresAt <= Date.now()) return this.uploadErr("AFS_UNSUPPORTED", "session expired");
+		const result = await this.commitSessionEntries(session.id, session.entries, entries);
+		await this.uploadSessionStore.markCommitted(session.id);
+		return {
+			success: true,
+			data: result
+		};
+	}
+	async execAbortUpload(_ctx, args) {
+		if (!this.uploadSessionStore) return this.uploadErr("AFS_UNSUPPORTED", "upload plane not available");
+		const parsed = AbortUploadArgsSchema.safeParse(args);
+		if (!parsed.success) return this.uploadErr("AFS_VALIDATION_ERROR", zodMessage(parsed.error));
+		const session = await this.uploadSessionStore.getSession(parsed.data.sessionId);
+		if (!this.ownsSession(session)) return this.uploadErr("AFS_NOT_FOUND", "unknown upload session");
+		await this.uploadSessionStore.markAborted(session.id);
+		if (this.gcQueue) {
+			const orphanCids = [...new Set(session.entries.filter((e) => e.status !== "committed").map((e) => e.cid))];
+			if (orphanCids.length > 0) await this.gcQueue.enqueue(orphanCids);
+		}
+		return {
+			success: true,
+			data: {
+				sessionId: session.id,
+				status: "aborted"
+			}
+		};
+	}
+	/**
+	* Resolve the immutable-merge-key set: `createdAt` is always preserved, plus
+	* any caller-supplied lifecycle fields (e.g. `status`).
+	*/
+	resolveImmutableMergeKeys(extra) {
+		const keys = new Set(["createdAt"]);
+		for (const k of extra ?? []) keys.add(k);
+		return keys;
+	}
+	/** Extract the JSON record object from a write payload's `content`. */
+	parseRecordBody(content) {
+		if (content !== null && typeof content === "object" && !Array.isArray(content) && !(content instanceof Uint8Array) && !(content instanceof ArrayBuffer)) return content;
+		if (typeof content === "string") try {
+			const v = JSON.parse(content);
+			return v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+		} catch {
+			return null;
+		}
+		return null;
+	}
+	/**
+	* Stamp the dedup identity into a write's meta so the writeHandler can project
+	* it onto the entry's `dedup_scope` / `dedup_key` columns (#1159). `dedupKey`
+	* stays in the metadata blob (observability / collection-query); on a merge
+	* we drop `createdAt` so the index keeps the original file ctime (R1,
+	* feed-sort §5.1).
+	*/
+	stampDedupMeta(base, dedupScope, dedupKey, isDuplicate) {
+		const meta = { ...base ?? {} };
+		meta.dedupKey = dedupKey;
+		meta.dedupScope = dedupScope;
+		if (isDuplicate) delete meta.createdAt;
+		return meta;
+	}
+	/**
+	* Dedup-on-write core (#492 / #1159) — the `options.dedupBy` upsert behind the
+	* standard `write` / `batchWrite`. The record's `dedupBy` field (URL-valued)
+	* is normalized into a `dedupKey`; the record lands at a STABLE readable path
+	* (`{collection}/{uuid}.json`) and dedup resolves through the tree-index's
+	* `(scope, dedup_scope, dedup_key)` secondary UNIQUE index — NOT a
+	* cid-in-path filename (which silently orphaned records written under any
+	* other layout, #1159). On a hit the incoming record is MERGED
+	* (non-degrading) into the existing entry AT ITS REAL PATH. Concurrency-safe:
+	* a racing create collides on the UNIQUE index, and the loser re-queries the
+	* index and merges (bounded retry). Records missing the field are written
+	* normally under the collection (no dedup).
+	*/
+	async upsertByDedupKey(path, content, options, dedupBy) {
+		if (!this.treeIndex.findByDedupKey) throw new AFSValidationError("dedup-on-write (dedupBy) is not supported by this DID Space index");
+		const { dedupBy: _by, dedupKey: _dk, mergeImmutableFields, ...baseOpts } = options;
+		const body = this.parseRecordBody(content.content);
+		const rawVal = body && typeof body[dedupBy] === "string" ? body[dedupBy] : null;
+		if (!body || !rawVal) {
+			const fresh = joinURL("/", path, `${crypto.randomUUID()}.json`);
+			return {
+				...await super.write(fresh, content, baseOpts),
+				deduped: false
+			};
+		}
+		const dedupKey = normalizeItemUrl(rawVal);
+		const dedupScope = this.treePath(joinURL("/", path));
+		const immutable = this.resolveImmutableMergeKeys(mergeImmutableFields);
+		const MAX_ATTEMPTS = 4;
+		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+			const existing = await this.treeIndex.findByDedupKey(dedupScope, dedupKey);
+			if (existing) {
+				const target = `/${existing.path}`;
+				let existingBody = null;
+				let version;
+				try {
+					const readResult = await this.read(target);
+					existingBody = this.parseRecordBody(readResult.data?.content);
+					version = (readResult.data?.meta)?.version;
+				} catch (err) {
+					if (err instanceof AFSNotFoundError) continue;
+					throw err;
+				}
+				const mergedBody = existingBody !== null ? mergeItemContent(existingBody, body, immutable) : { ...body };
+				const meta$1 = this.stampDedupMeta(content.meta, dedupScope, dedupKey, true);
+				const callerIfMatch = baseOpts.ifMatch;
+				const ifMatch = callerIfMatch ?? version;
+				try {
+					return {
+						...await super.write(target, {
+							...content,
+							content: mergedBody,
+							meta: meta$1
+						}, ifMatch ? {
+							...baseOpts,
+							ifMatch
+						} : baseOpts),
+						deduped: true
+					};
+				} catch (err) {
+					if (err instanceof AFSConflictError && callerIfMatch === void 0) continue;
+					throw err;
+				}
+			}
+			const fresh = joinURL("/", path, `${crypto.randomUUID()}.json`);
+			const meta = this.stampDedupMeta(content.meta, dedupScope, dedupKey, false);
+			try {
+				return {
+					...await super.write(fresh, {
+						...content,
+						content: body,
+						meta
+					}, baseOpts),
+					deduped: false
+				};
+			} catch (err) {
+				if (await this.treeIndex.findByDedupKey(dedupScope, dedupKey)) continue;
+				throw err;
+			}
+		}
+		throw new AFSConflictError(joinURL("/", path), {});
+	}
+	/**
+	* One-time reindex/backfill seam (#1159 — run from a deferred one-shot
+	* script, NOT on the write hot path). Populates the dedup columns for
+	* EXISTING records under `collection` so pre-feature entries (old
+	* `{slug}.json` / `{uuid}/item.json` / `{cid}.json` layouts) become
+	* dedup-able — fixing the "an already-saved URL's first re-save duplicates"
+	* bug. Reads each record, extracts + normalizes `record[dedupBy]`, and writes
+	* the dedup columns INDEX-ONLY (no changelog / no cid change) via
+	* `TreeIndex.setDedupKey`. Records missing the field, and genuine
+	* pre-existing duplicates (which would violate the UNIQUE index), are
+	* skipped. Idempotent.
+	*/
+	async reindexDedupKeys(collection, dedupBy) {
+		if (!this.treeIndex.setDedupKey) throw new AFSValidationError("reindexDedupKeys is not supported by this DID Space index");
+		const dedupScope = this.treePath(joinURL("/", collection));
+		const listPrefix = dedupScope.endsWith("/") ? dedupScope : `${dedupScope}/`;
+		let scanned = 0;
+		let indexed = 0;
+		let skipped = 0;
+		let cursor;
+		do {
+			const page = await this.treeIndex.listEntries(listPrefix, {
+				limit: 500,
+				cursor
+			});
+			for (const e of page.entries) {
+				scanned++;
+				let body = null;
+				try {
+					const r = await this.read(`/${e.path}`);
+					body = this.parseRecordBody(r.data?.content);
+				} catch {
+					skipped++;
+					continue;
+				}
+				const raw = body && typeof body[dedupBy] === "string" ? body[dedupBy] : null;
+				if (!raw) {
+					skipped++;
+					continue;
+				}
+				try {
+					await this.treeIndex.setDedupKey(e.path, dedupScope, normalizeItemUrl(raw), { deviceId: this.deviceId });
+					indexed++;
+				} catch {
+					skipped++;
+				}
+			}
+			cursor = page.hasMore ? page.cursor : void 0;
+		} while (cursor);
+		return {
+			scanned,
+			indexed,
+			skipped
+		};
+	}
+	/**
+	* Standard write, extended with the dedup-on-write upsert policy (#492 /
+	* #1159). When `options.dedupBy` (canonical) or the deprecated `dedupKey`
+	* alias is set the write becomes a secondary-index upsert (see
+	* {@link upsertByDedupKey}); otherwise it is the base provider's write.
+	*/
+	async write(path, content, options) {
+		const dedupBy = options?.dedupBy ?? options?.dedupKey;
+		if (dedupBy) return this.upsertByDedupKey(path, content, options, dedupBy);
+		return super.write(path, content, options);
+	}
+	/**
+	* The commit write — mirrors `batchWrite` steps 2/6/7/8 WITHOUT the R2 byte
+	* leg (existence is trusted, §8): preread → ifMatch/skip → batchPutEntries →
+	* GC bookkeeping → share hooks → per-entry results. `cid`/`size`/`mimeType`
+	* come from the SESSION record (the prepared contract, re-validated against
+	* the client's entries); `deviceId`/`mtime` are client provenance threaded to
+	* the changelog (echo防回环, §6.1).
+	*/
+	async commitSessionEntries(sessionId, sessionEntries, clientEntries) {
+		const byPath = new Map(sessionEntries.map((e) => [joinURL("/", e.path), e]));
+		const results = new Array(clientEntries.length);
+		const prepared = [];
+		for (let i = 0; i < clientEntries.length; i++) {
+			const c = clientEntries[i];
+			const afsPath = joinURL("/", c.path);
+			const pv = this.validateActionPath(afsPath);
+			if (!pv.ok) {
+				results[i] = {
+					path: afsPath,
+					success: false,
+					error: pv.reason,
+					code: "AFS_VALIDATION_ERROR"
+				};
+				continue;
+			}
+			const se = byPath.get(afsPath);
+			if (!se || se.cid !== c.cid) {
+				results[i] = {
+					path: afsPath,
+					success: false,
+					error: "entry not in session, or cid mismatch with prepared contract",
+					code: "AFS_VALIDATION_ERROR"
+				};
+				continue;
+			}
+			const deviceId = typeof c.deviceId === "string" && c.deviceId ? c.deviceId : se.deviceId ?? this.deviceId;
+			const mtime = typeof c.mtime === "number" ? c.mtime : se.mtime ?? Date.now();
+			const ctime = resolveCtime(c.metadata, mtime);
+			const treeEntry = {
+				cid: se.cid,
+				size: se.size,
+				mtime,
+				ctime,
+				mimeType: se.mimeType ?? void 0
+			};
+			if (c.content !== void 0 && isTextMime(se.mimeType ?? void 0)) {
+				if (await checksumSha256OfContent(c.content) === se.checksumSha256) treeEntry.content = c.content;
+			}
+			if (c.metadata) {
+				const appMeta = extractApplicationMeta(c.metadata);
+				if (appMeta) {
+					try {
+						assertMetadataSize(appMeta, afsPath);
+					} catch (err) {
+						results[i] = {
+							path: afsPath,
+							success: false,
+							error: err instanceof Error ? err.message : String(err),
+							code: err.code ?? "AFS_VALIDATION_ERROR"
+						};
+						continue;
+					}
+					treeEntry.metadata = appMeta;
+				}
+			}
+			prepared.push({
+				i,
+				afsPath,
+				treePath: pv.treePath,
+				cid: se.cid,
+				treeEntry,
+				deviceId,
+				...se.ifMatch ? { ifMatch: se.ifMatch } : {}
+			});
+		}
+		const preread = await this.batchPreread(prepared.map((p) => p.treePath));
+		const skipped = [];
+		let live = [];
+		for (const p of prepared) {
+			const existing = preread.get(p.treePath) ?? null;
+			if (ifMatchPreconditionFailed(p.ifMatch, existing)) {
+				results[p.i] = this.batchConflictFailure(p.afsPath, {
+					currentCid: existing?.cid ?? null,
+					currentMtime: existing?.mtime ?? null,
+					currentDeviceId: null
+				});
+				continue;
+			}
+			live.push(p);
+		}
+		const preIoOk = [];
+		for (const p of live) try {
+			await applyShareWriteHook({
+				...this.shareHookArgs(p.afsPath, p.treePath),
+				bytes: new Uint8Array(0),
+				cid: p.cid,
+				resolver: this.shareResolver,
+				phase: "pre-io"
+			});
+			preIoOk.push(p);
+		} catch (err) {
+			results[p.i] = {
+				path: p.afsPath,
+				success: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+		live = preIoOk;
+		let indexResults = [];
+		if (live.length > 0) {
+			const batchEntries = live.map((p) => ({
+				path: p.treePath,
+				entry: p.treeEntry,
+				opts: { deviceId: p.deviceId }
+			}));
+			indexResults = this.treeIndex.batchPutEntries ? await this.treeIndex.batchPutEntries(batchEntries, { preread }) : await loopBatchPutEntries(this.treeIndex, batchEntries, { preread });
+		}
+		const written = [];
+		live.forEach((p, j) => {
+			const r = indexResults[j];
+			if (!r) {
+				results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: "index batch returned no result"
+				};
+				return;
+			}
+			if (r.conflict) {
+				results[p.i] = this.batchConflictFailure(p.afsPath, r.conflict);
+				return;
+			}
+			if (r.error) {
+				results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: r.error
+				};
+				return;
+			}
+			if (r.skipped) {
+				skipped.push(p);
+				return;
+			}
+			written.push({
+				p,
+				oldCid: r.oldCid,
+				liveSeq: r.liveSeq
+			});
+		});
+		if (this.gcQueue) {
+			const reReferenced = [...new Set([...written.map((w) => w.p.cid), ...skipped.map((s) => s.cid)])];
+			if (reReferenced.length > 0) if (this.gcQueue.removeMany) await this.gcQueue.removeMany(reReferenced);
+			else for (const cid of reReferenced) await this.gcQueue.remove(cid);
+			const replaced = [...new Set(written.filter((w) => w.oldCid && w.oldCid !== w.p.cid).map((w) => w.oldCid))];
+			if (replaced.length > 0) await this.gcQueue.enqueue(replaced);
+		}
+		for (const w of written) try {
+			await applyShareWriteHook({
+				...this.shareHookArgs(w.p.afsPath, w.p.treePath),
+				bytes: new Uint8Array(0),
+				cid: w.p.cid,
+				resolver: this.shareResolver,
+				phase: "post-io"
+			});
+		} catch {}
+		const commitOk = (p, liveSeq) => ({
+			status: 200,
+			ok: true,
+			data: {
+				path: p.afsPath,
+				meta: {
+					cid: p.cid,
+					liveSeq: liveSeq != null ? String(liveSeq) : void 0
+				}
+			}
+		});
+		for (const w of written) results[w.p.i] = commitOk(w.p, w.liveSeq);
+		for (const s of skipped) {
+			let liveSeq;
+			if (this.treeIndex.getPrefixWatermark) liveSeq = await this.treeIndex.getPrefixWatermark(s.treePath) ?? void 0;
+			results[s.i] = commitOk(s, liveSeq);
+		}
+		const committedPaths = [...written, ...skipped.map((s) => ({ p: s }))].map((w) => ({
+			path: w.p.afsPath,
+			status: "committed"
+		}));
+		if (committedPaths.length > 0) await this.uploadSessionStore?.markEntries(sessionId, committedPaths);
+		const succeeded = results.filter((r) => r?.ok === true).length;
+		return {
+			ok: true,
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	/**
+	* Native batch delete — same merge without the R2 leg: ONE preread → GC
+	* enqueue (before delete, single-op ordering) → ONE atomic index batch →
+	* share delete hooks. FILE entries only (no directory fallback — sync
+	* never dir-deletes; a dir path fails per entry with 404).
+	*/
+	async batchDelete(entries, _options) {
+		const results = new Array(entries.length);
+		const prepared = [];
+		for (let i = 0; i < entries.length; i++) {
+			const entry = entries[i];
+			const afsPath = joinURL("/", entry.path);
+			if (this.isVirtualPath(afsPath) || isShareReservedPath(afsPath)) {
+				results[i] = {
+					path: afsPath,
+					success: false,
+					error: `Forbidden at ${afsPath}: virtual_path`,
+					code: "AFS_FORBIDDEN"
+				};
+				continue;
+			}
+			const deleteMeta = entry.options?.meta;
+			prepared.push({
+				i,
+				afsPath,
+				treePath: this.treePath(afsPath),
+				deviceId: typeof deleteMeta?.deviceId === "string" && deleteMeta.deviceId ? deleteMeta.deviceId : this.deviceId,
+				...typeof deleteMeta?.mtime === "number" ? { mtime: deleteMeta.mtime } : {},
+				...typeof deleteMeta?.ifMatch === "string" ? { ifMatch: deleteMeta.ifMatch } : {}
+			});
+		}
+		const preread = await this.batchPreread(prepared.map((p) => p.treePath));
+		const live = [];
+		for (const p of prepared) {
+			const existing = preread.get(p.treePath) ?? null;
+			if (p.ifMatch !== void 0 && (!existing || existing.cid !== p.ifMatch)) {
+				results[p.i] = this.batchConflictFailure(p.afsPath, {
+					currentCid: existing?.cid ?? null,
+					currentMtime: existing?.mtime ?? null,
+					currentDeviceId: null
+				});
+				continue;
+			}
+			if (!existing) {
+				results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: `Path not found: ${p.afsPath}`,
+					code: "AFS_NOT_FOUND"
+				};
+				continue;
+			}
+			live.push(p);
+		}
+		if (this.gcQueue && live.length > 0) {
+			const cids = [...new Set(live.map((p) => (preread.get(p.treePath) ?? null)?.cid).filter(Boolean))];
+			if (cids.length > 0) await this.gcQueue.enqueue(cids);
+		}
+		if (live.length > 0) {
+			const batchEntries = live.map((p) => ({
+				path: p.treePath,
+				opts: {
+					deviceId: p.deviceId,
+					...p.mtime !== void 0 ? { mtime: p.mtime } : {}
+				}
+			}));
+			let indexResults;
+			try {
+				indexResults = this.treeIndex.batchDeleteEntries ? await this.treeIndex.batchDeleteEntries(batchEntries, { preread }) : await loopBatchDeleteEntries(this.treeIndex, batchEntries, { preread });
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				for (const p of live) results[p.i] = {
+					path: p.afsPath,
+					success: false,
+					error: message
+				};
+				const succeededEarly = results.filter((r) => r?.success).length;
+				return {
+					results,
+					succeeded: succeededEarly,
+					failed: results.length - succeededEarly
+				};
+			}
+			for (let j = 0; j < live.length; j++) {
+				const p = live[j];
+				const r = indexResults[j];
+				if (!r || r.error || r.conflict || r.notFound) {
+					results[p.i] = r?.conflict ? this.batchConflictFailure(p.afsPath, r.conflict) : {
+						path: p.afsPath,
+						success: false,
+						error: r?.error ?? `Path not found: ${p.afsPath}`,
+						...r?.notFound ? { code: "AFS_NOT_FOUND" } : {}
+					};
+					continue;
+				}
+				await applyShareDeleteHook({
+					...this.shareHookArgs(p.afsPath, p.treePath),
+					resolver: this.shareResolver
+				});
+				if (p.afsPath.endsWith(".ash")) this.emit({
+					type: SCRIPT_EVENT_TYPES.UNREGISTERED,
+					path: p.afsPath,
+					data: { runtime: "ash" }
+				});
+				results[p.i] = {
+					path: p.afsPath,
+					success: true
+				};
+			}
+		}
+		const succeeded = results.filter((r) => r?.success).length;
+		return {
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	async statHandler(ctx) {
+		const afsPath = joinURL("/", ctx.params.path ?? "");
+		if (afsPath === "/") return { data: {
+			id: "/",
+			path: "/",
+			meta: {
+				kind: "did-space:root",
+				childrenCount: await this.treeIndex.countChildren(this.treeListPrefix("/"))
+			}
+		} };
+		const entry = await this.treeIndex.get(this.treePath(afsPath), { includeContent: false });
+		if (entry) return { data: {
+			id: afsPath.split("/").pop() || afsPath,
+			path: afsPath,
+			meta: {
+				kind: "did-space:file",
+				size: entry.size,
+				cid: entry.cid,
+				mimeType: entry.mimeType,
+				version: entry.cid
+			},
+			createdAt: new Date(entry.ctime),
+			updatedAt: new Date(entry.mtime)
+		} };
+		if (await this.isDirectory(afsPath)) {
+			const prefix = this.treeListPrefix(afsPath);
+			const meta = {
+				kind: "did-space:directory",
+				childrenCount: await this.treeIndex.countChildren(prefix)
+			};
+			if (this.treeIndex.getPrefixWatermark) {
+				const version = await this.treeIndex.getPrefixWatermark(prefix);
+				if (version != null) meta.liveSeq = String(version);
+			}
+			const stat = {
+				id: afsPath.split("/").pop() || afsPath,
+				path: afsPath,
+				meta
+			};
+			const dirTimes = await this.treeIndex.getDirTimes?.(prefix);
+			if (dirTimes) {
+				stat.createdAt = new Date(dirTimes.ctime);
+				stat.updatedAt = new Date(dirTimes.mtime);
+			}
+			return { data: stat };
+		}
+		throw new AFSNotFoundError(afsPath);
+	}
+	async searchHandler(ctx, query, options) {
+		const afsPath = ctx.params.path ? `/${ctx.params.path}` : "/";
+		const pattern = query || "";
+		const limit = options?.limit || 50;
+		if (!pattern) return {
+			data: [],
+			total: 0
+		};
+		const prefix = this.treeListPrefix(afsPath);
+		const results = [];
+		let cursor;
+		const searchQuery = pattern.toLowerCase();
+		do {
+			const listResult = await this.treeIndex.list(prefix, {
+				limit: LIST_MAX_LIMIT,
+				cursor
+			});
+			for (const treeListEntry of listResult.entries) {
+				if (results.length >= limit) break;
+				const path = `/${treeListEntry.path}`;
+				if ((path.split("/").pop() || "").toLowerCase().includes(searchQuery)) {
+					results.push(this.buildEntry(path, {}));
+					continue;
+				}
+				const treeEntry = await this.treeIndex.get(treeListEntry.path, { includeContent: false });
+				if (treeEntry) {
+					if (!isTextMime(treeEntry.mimeType)) continue;
+					const obj = await this.objectStore.get(this.objectKey(treeEntry.cid));
+					if (obj) {
+						const content = await obj.text();
+						if (content.toLowerCase().includes(searchQuery)) results.push(this.buildEntry(path, { content }));
+					}
+				}
+			}
+			cursor = listResult.hasMore ? listResult.cursor : void 0;
+		} while (cursor && results.length < limit);
+		return {
+			data: results,
+			total: results.length
+		};
+	}
+	async explainHandler(ctx) {
+		const afsPath = joinURL("/", ctx.params.path ?? "");
+		const lines = [];
+		lines.push(`# DID Space: ${afsPath}`);
+		lines.push("");
+		if (afsPath === "/") {
+			lines.push(`DID: ${this.did}`);
+			lines.push("");
+			lines.push(this.description || "DID-scoped persistent storage with CID-based deduplication");
+			lines.push("");
+			lines.push("## Operations");
+			lines.push("- `list /` — List root files and directories");
+			lines.push("- `read /{path}` — Read file content");
+			lines.push("- `write /{path}` — Write file (content-addressed dedup)");
+			lines.push("- `delete /{path}` — Delete file entry (lazy GC)");
+		} else {
+			const entry = await this.treeIndex.get(this.treePath(afsPath), { includeContent: false });
+			if (entry) {
+				lines.push(`DID: ${this.did}`);
+				lines.push(`Path: ${afsPath}`);
+				lines.push(`Size: ${entry.size} bytes`);
+				lines.push(`CID: ${entry.cid}`);
+				lines.push(`MIME: ${entry.mimeType ?? "unknown"}`);
+				lines.push(`Created: ${new Date(entry.ctime).toISOString()}`);
+				lines.push(`Modified: ${new Date(entry.mtime).toISOString()}`);
+			} else if (await this.isDirectory(afsPath)) {
+				lines.push(`DID: ${this.did}`);
+				lines.push(`Virtual directory: ${afsPath}`);
+				lines.push("Use `list` to see contents.");
+			} else lines.push("Path not found.");
+		}
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	/**
+	* Write content to the provider, bypassing D4 virtual path protection.
+	* Stores content to objectStore and treeIndex with the given deviceId.
+	*/
+	async internalWrite(afsPath, opts) {
+		if (isShareReservedPath(afsPath)) throw new AFSForbiddenError(afsPath, "share-path-reserved");
+		const { content, deviceId, mtime, mimeType: explicitMimeType, metadata } = opts;
+		let bytes;
+		let storeValue;
+		if (content instanceof Uint8Array) {
+			bytes = content;
+			storeValue = bytes.buffer;
+		} else {
+			bytes = new Uint8Array(content);
+			storeValue = bytes.buffer;
+		}
+		const cid = await computeCID(bytes);
+		const objKey = this.objectKey(cid);
+		const treePath = this.treePath(afsPath);
+		await applyShareWriteHook({
+			...this.shareHookArgs(afsPath, treePath),
+			bytes,
+			cid,
+			resolver: this.shareResolver,
+			phase: "pre-io"
+		});
+		if (!await this.objectStore.head(objKey)) await this.objectStore.put(objKey, storeValue);
+		const now = mtime ?? Date.now();
+		const detectedMime = explicitMimeType ?? detectMimeType(afsPath) ?? void 0;
+		const ctime = resolveCtime(metadata, now);
+		const treeEntry = {
+			cid,
+			size: bytes.length,
+			mtime: now,
+			ctime,
+			mimeType: detectedMime
+		};
+		const appMeta = extractApplicationMeta(metadata);
+		if (appMeta) treeEntry.metadata = appMeta;
+		const inlineText = decodeInlineText(bytes, detectedMime);
+		if (inlineText !== null) treeEntry.content = inlineText;
+		const { oldCid } = await this.treeIndex.put(treePath, treeEntry, { deviceId });
+		if (this.gcQueue) {
+			await this.gcQueue.remove(cid);
+			if (oldCid && oldCid !== cid) await this.gcQueue.enqueue([oldCid]);
+		}
+		await applyShareWriteHook({
+			...this.shareHookArgs(afsPath, treePath),
+			bytes,
+			cid,
+			resolver: this.shareResolver,
+			phase: "post-io"
+		});
+		await applyBlockletWriteHook({
+			...this.blockletHookArgs(afsPath, treePath),
+			bytes,
+			resolver: this.blockletResolver
+		});
+		return oldCid === void 0 ? { cid } : {
+			cid,
+			oldCid
+		};
+	}
+	/**
+	* Delete a file from the provider, bypassing D4 virtual path protection.
+	*/
+	async internalDelete(afsPath, opts) {
+		if (isShareReservedPath(afsPath)) throw new AFSForbiddenError(afsPath, "share-path-reserved");
+		const treePath = this.treePath(afsPath);
+		const entry = await this.treeIndex.get(treePath, { includeContent: false });
+		if (!entry) return { deleted: false };
+		await this.gcQueue?.enqueue([entry.cid]);
+		await this.treeIndex.delete(treePath, { deviceId: opts.deviceId });
+		await applyShareDeleteHook({
+			...this.shareHookArgs(afsPath, treePath),
+			resolver: this.shareResolver
+		});
+		await applyBlockletDeleteHook({
+			...this.blockletHookArgs(afsPath, treePath),
+			resolver: this.blockletResolver
+		});
+		return { deleted: true };
+	}
+	capabilities() {
+		return {
+			schemaVersion: 1,
+			provider: this.name,
+			tools: [],
+			actions: [],
+			operations: this.getOperationsDeclaration()
+		};
+	}
+};
+__decorate([Meta("/:path*")], DIDSpaceProvider.prototype, "readMeta", null);
+__decorate([List("/:path*", { handleDepth: true })], DIDSpaceProvider.prototype, "listHandler", null);
+__decorate([Read("/.meta/.capabilities")], DIDSpaceProvider.prototype, "readCapabilities", null);
+__decorate([Read("/:path*")], DIDSpaceProvider.prototype, "readHandler", null);
+__decorate([Write("/:path*")], DIDSpaceProvider.prototype, "writeHandler", null);
+__decorate([Delete("/:path*")], DIDSpaceProvider.prototype, "deleteHandler", null);
+__decorate([Actions("/")], DIDSpaceProvider.prototype, "listObjectPlaneActions", null);
+__decorate([Actions.Exec("/", "prepare-upload", "Reserve an upload session + (CF) mint exact-key checksum-pinned PUT grants", { effect: "write" })], DIDSpaceProvider.prototype, "execPrepareUpload", null);
+__decorate([Actions.Exec("/", "prepare-download", "Mint exact-key short-TTL presigned GET grants for view-referenced objects", { effect: "write" })], DIDSpaceProvider.prototype, "execPrepareDownload", null);
+__decorate([Actions.Exec("/", "commit-upload", "Commit uploaded objects' metadata (trust existence, 0 R2 subrequests)", { effect: "write" })], DIDSpaceProvider.prototype, "execCommitUpload", null);
+__decorate([Actions.Exec("/", "abort-upload", "Abort an upload session; staged objects become GC candidates", { effect: "write" })], DIDSpaceProvider.prototype, "execAbortUpload", null);
+__decorate([Stat("/:path*")], DIDSpaceProvider.prototype, "statHandler", null);
+__decorate([Search("/:path*")], DIDSpaceProvider.prototype, "searchHandler", null);
+__decorate([Explain("/:path*")], DIDSpaceProvider.prototype, "explainHandler", null);
+
+//#endregion
+export { AFS_IFMATCH_ABSENT, BLOCKLET_PUBLISH_MARKER, BatchOverBudgetError, BatchUnsupportedError, CHANGELOG_DDL, CHANGELOG_INDEX_SQL, CHANGELOG_INSERT_SQL, CHANGELOG_ROW_KIND, CHANGELOG_SCOPE_CID_MIGRATION_SQL, CHANGELOG_TABLE_SQL, CHANGELOG_WIRE_EXTRA_FIELDS, CachingObjectStore, CidByteCache, ConflictResolutionError, CurrentObjectMissingError, D1GCQueue, D1ResolveStore, D1ShareReconciler, D1ShareStore, D1TreeIndex, D1UploadSessionStore, D1VersionedScopeBackend, D1_DID_SPACE_SCHEMA_SQL, DEFAULT_GC_GRACE_MS, DEFAULT_INLINE_THRESHOLD, DEVICE_ID_FORMAT_RE, DEVICE_SYNC_STATE_INDEX_SQL, DEVICE_SYNC_STATE_TABLE_SQL, DIDSpaceBlockletDataBackend, DIDSpaceClient, DIDSpaceProvider, DIDSpaceResolver, DIRTY_PATH_DDL, DIRTY_PATH_INDEX_SQL, DIRTY_PATH_TABLE_SQL, DIRTY_PATH_TRIGGER_SQL, ENTRIES_CONTENT_TYPE_COLUMN_SQL, ENTRIES_CONTENT_TYPE_INDEX_DROP_SQL, ENTRIES_CONTENT_TYPE_INDEX_SQL, ENTRIES_DEDUP_INDEX_SQL, ENTRIES_DEDUP_KEY_COLUMN_SQL, ENTRIES_DEDUP_SCOPE_COLUMN_SQL, ENTRIES_INDEX_SQL, ENTRIES_INLINE_CONTENT_COLUMN_SQL, ENTRIES_METADATA_COLUMN_SQL, ENTRIES_TABLE_SQL, GC_QUEUE_INDEX_SQL, GC_QUEUE_TABLE_SQL, HttpTransport, INGEST_DEVICE_ID, INLINE_CONTENT_HARD_CAP, LOCAL_CHANGELOG_DEFAULT_LIMIT, LOCAL_CHANGELOG_MAX_LIMIT, LibsqlVersionedScopeBackend, LocalChangelog, MANIFEST_FILE_KIND, MANIFEST_WIRE_EXTRA_FIELDS, MAX_DEVICE_ID_BYTES, MAX_ENTRIES_PER_SCOPE, MemoryGcQueue, MemoryTreeIndex, MemoryVersionedScopeBackend, PREFIX_WATERMARK_TABLE_SQL, PRESIGN_MAX_EXPIRES_SEC, PULL_BATCH_LIMIT, PULL_FETCH_CONCURRENCY, PUSH_BATCH_LIMIT, PUSH_PROGRESS_FLUSH_INTERVAL, PrefixedTreeIndex, RESOLVE_ENTRIES_INDEX_SQL, RESOLVE_ENTRIES_TABLE_SQL, RpcUserSpaceAFS, SCOPE_META_FILE_COUNT_BACKFILL_SQL, SCOPE_META_FILE_COUNT_DELETE_ONE_SQL, SCOPE_META_FILE_COUNT_DELETE_RANGE_SQL, SCOPE_META_FILE_COUNT_TRIGGER_SQL, SCOPE_META_INDEX_SQL, SCOPE_META_TABLE_SQL, SCOPE_META_TOTAL_BYTES_BACKFILL_SQL, SCOPE_META_TOTAL_BYTES_COLUMN_SQL, SCOPE_META_TOTAL_BYTES_TRIGGER_SQL, SHARES_INDEX_SQL, SHARES_TABLE_SQL, SYNC_STATE_DDL, SYNC_STATE_INDEX_SQL, SYNC_STATE_KEYS, SYNC_STATE_TABLE_SQL, SYNC_WALL_CLOCK_BUDGET_MS, ShareResolver, SqliteGcQueue, SqliteResolveStore, SqliteShareStore, SqliteUploadSessionStore, StaticReadonlyTransport, SyncEngine, SyncStateStore, UPLOAD_SESSIONS_INDEX_SQL, UPLOAD_SESSIONS_TABLE_SQL, UPLOAD_SESSION_ENTRIES_TABLE_SQL, UPLOAD_SESSION_TTL_MS, VERSIONED_SCOPES_INDEX_SQL, VERSIONED_SCOPES_TABLE_SQL, VersionedContentIndex, VersionedContentStore, WsTransport, ancestorDirs, applyDirtyUpsert, assertInlineThreshold, assertValidCid, attachMetadataContext, buildChangelogBinds, buildD1MigrationSql, buildKeysetCursor, buildManifest, buildOrderedQueryParts, cidToChecksumSha256, classifyMissingObject, classifyScopes, compareTreeSortValues, computeCID, computeDiff, connectDIDSpace, createWsTransport, decodeInlineText, decodeScopeHmacSecret, defaultAppState, deriveScope, detachMetadataContext, detectMimeType, fetchRemoteManifest, generateDesktopDeviceId, getMetadataContext, isPlainDidScope, isShareDeclarationPath, isTextMime, isValidDeviceId, keysetAfter, migrateD1Scopes, nameOf, normalizeDdl, normalizeId, normalizeItemUrl, objectKeyForCid, openDaemonShareStore, parentOf, parseChangelogEntry, parseManifestEntry, parseSyncStatus, parseTreeCursor, prefixRange, referencedAnywhereD1, referencedAnywhereLibsql, resolveVersionToken, rowToEntry, runGc, runWithConcurrency, serializeChangelogEntry, serializeManifestEntry, serializeSyncStatus, serveShare, syncDIDSpace, validateDeviceId, validateId, versionedScope, versionedScopeGroup };
+//# sourceMappingURL=index.mjs.map