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

package/dist/cloudflare.mjs

@@ -0,0 +1,507 @@
+import { applyBlockletDeleteHook, applyBlockletWriteHook } from "./blocklet-hook.mjs";
+import { computeCID } from "./cid.mjs";
+import { normalizeId, validateId } from "./did-utils.mjs";
+import { detectMimeType } from "./mime-utils.mjs";
+import { decodeInlineText } from "./inline-content.mjs";
+import { isShareReservedPath } from "./share-declaration.mjs";
+import { applyShareDeleteHook, applyShareWriteHook } from "./share-hook.mjs";
+import { D1UploadSessionStore } from "./upload-session-store.mjs";
+import { CachingObjectStore, CidByteCache } from "./cid-byte-cache.mjs";
+import { D1GCQueue } from "./d1-gc-queue.mjs";
+import { D1ResolveStore } from "./d1-resolve-store.mjs";
+import { objectKeyForCid } from "./object-key.mjs";
+import { D1TreeIndex } from "./d1-tree-index.mjs";
+import { PrefixedTreeIndex } from "./prefixed-tree-index.mjs";
+import { DIDSpaceResolver } from "./resolve.mjs";
+import { deriveScope } from "./scope-id.mjs";
+import { DIDSpaceProvider } from "./index.mjs";
+import { AFS, AFSForbiddenError, nsLog } from "@aigne/afs";
+
+//#region src/cloudflare.ts
+/**
+* CloudflareDIDSpace — Cloudflare backend for DID-scoped storage.
+*
+* Composes DIDSpaceProvider (files via R2 + D1 TreeIndex) per app,
+* with logical isolation (separate D1 scope per user+app DID).
+*
+* Same interface as local DIDSpace for 100% compatibility.
+*
+* Usage:
+*   const space = new CloudflareDIDSpace({ userDid: "did:abt:z1...", objectStore, indexDb });
+*   const afs = await space.getInstanceSpace({ instanceDid: "z1app", role: "system" });
+*   await afs.write("/hello.txt", { content: "hello" });
+*/
+/** provider:did-space structured logger (debug self-guards; off by default). */
+const log = nsLog("provider:did-space");
+var CloudflareDIDSpace = class {
+	/** Real normalizeId(DID) — identity, returned to callers (NOT a storage key). */
+	userDid;
+	/**
+	* Storage scope — `deriveScope(userDid, secret)` when de-id is on, else the
+	* plaintext `userDid`. Every D1 storage/query key uses this, never `userDid`.
+	* Named `_scope` to avoid colliding with the `get scope()` accessor (README §4.1).
+	*/
+	_scope;
+	objectStore;
+	indexDb;
+	_resolver;
+	/** Optional ShareResolver for .share reconcile hook (Phase 0.4) */
+	shareResolver;
+	/** Read replica opt-in for read-serving paths only — see options doc. */
+	useReplica;
+	/** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */
+	maxBytesPerScope;
+	/**
+	* Instance space cache keyed by (role, useReplica) — same shape as `local.ts`
+	* `instanceSpaces`. Without it, `getInstanceSpace` returns a fresh `AFS`
+	* (and fresh `EventBus`) every call, so propBind subscribe (registered on
+	* AFS_A at session start) and the agent's subsequent write (executing on
+	* AFS_B for that exec) cross different buses — the write's `afs:write`
+	* event never reaches the subscriber, so the live patch silently drops and
+	* the user only sees the new value after a manual page reload (Layer 2
+	* staleness on staging). Bounded by the lifetime of this DID-Space (per
+	* caller in the resolver), the same memory budget the resolver already
+	* spends on `spaces`.
+	*/
+	instanceSpaces = /* @__PURE__ */ new Map();
+	/**
+	* User-space cache keyed by (accessMode, useReplica) — the getUserSpace
+	* counterpart of {@link instanceSpaces}. Without it, every `getUserSpace()`
+	* builds a fresh `AFS` and re-runs `AFS.mount()`'s async provider health check
+	* (a root `stat` → `countChildren` + list). Blocklet serve calls getUserSpace
+	* once PER stage (reader / afsRoot), so a cold page paid that root enumeration
+	* 3× (issue #808 #4). Caching the handle reuses the mounted provider; data
+	* reads stay fresh (path→cid D1 lookups are never cached), so zero staleness.
+	*/
+	userSpaces = /* @__PURE__ */ new Map();
+	/** Shared GC queue instance — created once per CloudflareDIDSpace instance */
+	gcQueue;
+	/** Injected presigned-PUT signer (upload plane). Undefined → no grant capability. */
+	signer;
+	constructor(options) {
+		validateId(options.userDid);
+		this.userDid = normalizeId(options.userDid);
+		this._scope = options.scopeHmacSecret ? deriveScope(this.userDid, options.scopeHmacSecret) : this.userDid;
+		this.objectStore = new CachingObjectStore(options.objectStore, new CidByteCache());
+		this.indexDb = options.indexDb;
+		this.gcQueue = new D1GCQueue(options.indexDb);
+		this.shareResolver = options.shareResolver;
+		this.useReplica = options.useReplica ?? false;
+		this.maxBytesPerScope = options.maxBytesPerScope ?? 0;
+		this.signer = options.signer;
+	}
+	/**
+	* Construct a D1TreeIndex for this scope with the per-scope byte quota
+	* (upload-limits Phase 5) always injected — so every write path enforces it
+	* uniformly without each call site remembering to thread it. 0 = quota off.
+	*/
+	makeTreeIndex(opts) {
+		return new D1TreeIndex(this.indexDb, this._scope, {
+			...opts,
+			maxBytesPerScope: this.maxBytesPerScope
+		});
+	}
+	/**
+	* The injected presigned-PUT signer, or undefined when no R2 signer
+	* credentials are configured. The seam through which `prepare-upload` (P2)
+	* mints upload grants; also the capability signal clients use to decide
+	* grant-path vs batchWrite fallback (§15 decision 7/8).
+	*/
+	get presignSigner() {
+		return this.signer;
+	}
+	/**
+	* Upload-plane deps for the user-facing `DIDSpaceProvider` (design §7): the
+	* injected signer (CF mints grants; absent → fallback), a D1-backed session
+	* store, and the de-identified storage scope written into `upload_sessions`.
+	* Only the user space gets these — `/instance` (installer) + config don't.
+	*/
+	uploadDeps() {
+		return {
+			signer: this.signer,
+			uploadSessionStore: new D1UploadSessionStore(this.indexDb),
+			uploadScope: this._scope
+		};
+	}
+	/**
+	* Get an isolated AFS instance for a blocklet instance under this DID Space,
+	* scoped by role (system = installer-side data, user = caller-side data).
+	*
+	* Layout (PrefixedTreeIndex prefix relative to `entries.scope = userDid`):
+	*   role:"system" → blocklets/{instanceDid}/system/   (content tree, mounted at `/`)
+	*   role:"user"   → blocklets/{instanceDid}/user/      (content tree, mounted at `/`)
+	*   config        → blocklets/{instanceDid}/config/    (sibling fragment, getConfigSpace)
+	*
+	* /files-prefix-removal: content tree is the role root (no `files/` wrapper);
+	* config is a sibling fragment (invisible to `/instance`); vault removed.
+	*
+	* did-space-composition Phase 2 (symmetric with the local backend): the user
+	* fragment is a SINGLE `user` subtree. Per-user isolation comes from scope =
+	* caller's userDid (the resolver hands back a CloudflareDIDSpace scoped to the
+	* caller), so a `users/{userDid}` path segment would be redundant. `userDid`
+	* is @deprecated for this call and ignored for the path.
+	*
+	* Cached per (instanceDid, role, useReplica) — first caller's accessMode
+	* wins for that triple (mirrors local.ts). See `instanceSpaces` for the
+	* live-update rationale.
+	*/
+	async getInstanceSpace(opts) {
+		log.debug({
+			message: "getInstanceSpace",
+			instanceDid: opts.instanceDid,
+			role: opts.role
+		});
+		validateId(opts.instanceDid);
+		if (opts.role !== "system" && opts.role !== "user") throw new Error(`getInstanceSpace: invalid role "${opts.role}"`);
+		if (opts.role === "user" && opts.userDid != null) validateId(opts.userDid);
+		const bareInstanceId = normalizeId(opts.instanceDid);
+		const useReplica = opts.consistency === "primary" ? false : this.useReplica;
+		const cacheKey = `${bareInstanceId}::${opts.role}::${useReplica ? "r" : "p"}`;
+		const cached = this.instanceSpaces.get(cacheKey);
+		if (cached) return cached;
+		const subtree = opts.role === "system" ? `blocklets/${bareInstanceId}/system` : `blocklets/${bareInstanceId}/user`;
+		const accessMode = opts.accessMode ?? "readwrite";
+		const afs = new AFS();
+		const baseTreeIndex = this.makeTreeIndex({
+			useReplica,
+			inlineCache: "on"
+		});
+		const fileProvider = new DIDSpaceProvider({
+			did: bareInstanceId,
+			objectStore: this.objectStore,
+			treeIndex: new PrefixedTreeIndex(baseTreeIndex, `${subtree}/`),
+			name: "content",
+			accessMode,
+			gcQueue: this.gcQueue,
+			...opts.role === "user" ? {
+				shareTreePrefix: `${subtree}/`,
+				...this.shareResolver ? {
+					shareResolver: this.shareResolver,
+					shareOwnerDid: this._scope
+				} : {},
+				blockletResolver: this.resolver,
+				blockletOwnerDid: this.userDid
+			} : {},
+			...opts.role === "user" ? this.uploadDeps() : {}
+		});
+		await afs.mount(fileProvider, "/", { skipHealthCheck: true });
+		this.instanceSpaces.set(cacheKey, afs);
+		return afs;
+	}
+	/**
+	* Runtime-internal config fragment (`blocklets/<i>/config/`, mounted at
+	* `/`). Mirrors local `getConfigSpace`. Invisible to `/instance`; holds
+	* per-instance machine state like `mounts.toml`.
+	*/
+	async getConfigSpace(instanceDid) {
+		validateId(instanceDid);
+		const bareInstanceId = normalizeId(instanceDid);
+		const afs = new AFS();
+		const baseTreeIndex = this.makeTreeIndex({
+			useReplica: this.useReplica,
+			inlineCache: "on"
+		});
+		const configProvider = new DIDSpaceProvider({
+			did: bareInstanceId,
+			objectStore: this.objectStore,
+			treeIndex: new PrefixedTreeIndex(baseTreeIndex, `blocklets/${bareInstanceId}/config/`),
+			name: "config",
+			accessMode: "readwrite",
+			gcQueue: this.gcQueue
+		});
+		await afs.mount(configProvider, "/", { skipHealthCheck: true });
+		return afs;
+	}
+	/**
+	* List all instance DIDs that have storage in this user's space.
+	*
+	* Enumerates entries under the `blocklets/<instanceDid>/...` prefix and
+	* returns the distinct instance-DID segment. This mirrors the local
+	* backend's `listApps`, which enumerates `{userDir}/blocklets/*`. Legacy
+	* top-level `getAppSpace` segments are NOT enumerated — that layout is
+	* deprecated and removed in P4.
+	*/
+	async listApps() {
+		const result = await this.makeTreeIndex({ useReplica: this.useReplica }).list("", { limit: 1e3 });
+		const apps = /* @__PURE__ */ new Set();
+		for (const entry of result.entries) {
+			const parts = entry.path.split("/");
+			if (parts[0] === "blocklets" && parts[1]) apps.add(parts[1]);
+		}
+		return [...apps];
+	}
+	/**
+	* Contract alias (分叉 A, observability Phase 2) for the whole-space root.
+	* Delegates to {@link getUserSpace}; satisfies `DIDSpaceLike.getSpaceRoot`
+	* without renaming the existing CF method. Defaults readonly via getUserSpace.
+	*/
+	async getSpaceRoot(options) {
+		return this.getUserSpace(options);
+	}
+	/**
+	* Get an AFS instance scoped to the user's entire DID Space.
+	* No appDid sub-partitioning.
+	*/
+	async getUserSpace(options) {
+		log.debug({
+			message: "getUserSpace",
+			userDid: this.userDid
+		});
+		const accessMode = options?.accessMode ?? "readonly";
+		const cacheKey = `${accessMode}::${this.useReplica ? "r" : "p"}`;
+		const cached = this.userSpaces.get(cacheKey);
+		if (cached) return cached;
+		const afs = new AFS();
+		const provider = new DIDSpaceProvider({
+			did: this.userDid,
+			objectStore: this.objectStore,
+			treeIndex: this.makeTreeIndex({
+				useReplica: this.useReplica,
+				inlineCache: "on"
+			}),
+			name: "did-space-user",
+			accessMode,
+			shareResolver: this.shareResolver,
+			blockletResolver: this.resolver,
+			blockletOwnerDid: this.userDid,
+			...this.uploadDeps()
+		});
+		await afs.mount(provider, "/", { skipHealthCheck: true });
+		this.userSpaces.set(cacheKey, afs);
+		return afs;
+	}
+	get resolver() {
+		if (!this._resolver) this._resolver = new DIDSpaceResolver(new D1ResolveStore(this.indexDb, { useReplica: this.useReplica }));
+		return this._resolver;
+	}
+	/**
+	* Expose the underlying storage scope — used by worker handlers for
+	* cid-permission queries. MUST return the derived scope (not the plaintext
+	* DID) so the worker's `entries.scope` lookups match what was written.
+	*/
+	get scope() {
+		return this._scope;
+	}
+	/**
+	* Direct write path for the Worker HTTP handler (Task 2.4b).
+	*
+	* Bypasses the generic `afs.write()` path because `AFSWriteEntryPayload` has
+	* no `deviceId`/`skipChangelog` field — the `PutOpts` cannot be smuggled
+	* through the public AFS API. The Worker handler therefore constructs a
+	* `CloudflareDIDSpace` and calls this method directly, passing the per-
+	* request `deviceId` read from the `X-Device-Id` header.
+	*
+	* Semantics mirror `DIDSpaceProvider.writeHandler`:
+	*   1. Compute the content-addressed CID from the payload bytes.
+	*   2. R2 put `objects/{cid}` if not already stored (head-check for dedup).
+	*   3. `treeIndex.put` — atomic `entries` + `changelog` write (Task 2.4a).
+	*   4. Enqueue the previous CID (if any) onto the GC queue for deferred
+	*      cleanup. Enqueuing an overwritten CID is a no-op if the CID is still
+	*      referenced by another row (the GC job's reference check handles it).
+	*
+	* Path conventions:
+	*   - `afsPath` is an AFS-style path WITH leading slash (e.g. `/foo.json`
+	*     or `/blocklets/z1abc/index.html`).
+	*   - The leading slash is stripped before `treeIndex.put`; the remainder is
+	*     stored verbatim under `entries.scope = this._scope` (the derived storage
+	*     scope when de-id is on, else the plaintext DID). This matches the
+	*     `getUserSpace()` layout (no appDid sub-partition) that blocklet publish
+	*     and general user-space CRUD share.
+	*
+	* Returns `{ cid, oldCid }`. `oldCid` is present only when an existing row
+	* was overwritten; the caller can treat its presence as "something was
+	* replaced" for change-tracking. `seq` is not returned — Task 2.4a's
+	* `treeIndex.put` does not expose the changelog's AUTOINCREMENT `seq`, and
+	* adding a separate SELECT round trip here is wasted work for the current
+	* sync path (which only cares about cid + oldCid).
+	*
+	* No event dispatch is performed (Decision 3A round 5): CloudflareDIDSpace
+	* has no event bus reference, the Worker runtime is request/response with
+	* no long-lived subscriber, and the sync protocol polls `changelog` rows
+	* by `seq` rather than reacting to transient event fan-out.
+	*/
+	async internalWrite(afsPath, content, opts) {
+		let bytes;
+		let storeValue;
+		if (content instanceof Uint8Array) {
+			bytes = content;
+			storeValue = bytes.buffer;
+		} else if (content instanceof ArrayBuffer) {
+			bytes = new Uint8Array(content);
+			storeValue = content;
+		} else {
+			bytes = new TextEncoder().encode(content);
+			storeValue = content;
+		}
+		const cid = await computeCID(bytes);
+		const objectKey = objectKeyForCid(cid);
+		const treePath = afsPath.replace(/^\/+/, "");
+		if (isShareReservedPath(afsPath)) throw new AFSForbiddenError(afsPath, "share-path-reserved");
+		await applyShareWriteHook({
+			afsPath,
+			treePath,
+			bytes,
+			cid,
+			ownerDid: this._scope,
+			resolver: this.shareResolver,
+			phase: "pre-io"
+		});
+		if (!await this.objectStore.head(objectKey)) await this.objectStore.put(objectKey, storeValue);
+		const now = Date.now();
+		const mimeType = detectMimeType(afsPath) ?? void 0;
+		const treeIndex = this.makeTreeIndex({ inlineCache: "on" });
+		const entry = {
+			cid,
+			size: bytes.length,
+			mtime: now,
+			ctime: now,
+			mimeType
+		};
+		const inlineText = decodeInlineText(bytes, mimeType);
+		if (inlineText !== null) entry.content = inlineText;
+		const { oldCid } = await treeIndex.put(treePath, entry, opts);
+		await this.gcQueue.remove(cid);
+		if (oldCid && oldCid !== cid) await this.gcQueue.enqueue([oldCid]);
+		await applyShareWriteHook({
+			afsPath,
+			treePath,
+			bytes,
+			cid,
+			ownerDid: this._scope,
+			resolver: this.shareResolver,
+			phase: "post-io"
+		});
+		await applyBlockletWriteHook({
+			afsPath,
+			treePath,
+			bytes,
+			ownerDid: this.userDid,
+			resolver: this.resolver,
+			purgeCachesForDomains: typeof caches !== "undefined" ? async (domains) => {
+				const cfCaches = caches;
+				for (const domain of domains) {
+					const rootKey = new Request(`https://${domain}/`, { method: "GET" });
+					await cfCaches.default.delete(rootKey);
+				}
+			} : void 0
+		});
+		return oldCid === void 0 ? { cid } : {
+			cid,
+			oldCid
+		};
+	}
+	/**
+	* Read the current entry's cid + mtime + last-write deviceId for an
+	* If-Match precondition check (Task 3.3).
+	*
+	* Used by `_createSpaceHandler` BEFORE issuing a write when the client
+	* sends `If-Match: <cid>` for optimistic concurrency control. The
+	* handler compares the returned `cid` to the header value and returns
+	* 409 (with the full snapshot below) on mismatch, or 412 if the row
+	* doesn't exist (first-create with If-Match).
+	*
+	* The query joins `entries` (cid + mtime authoritative) with the most
+	* recent put row in `changelog` (device_id of last writer). Both
+	* indices used (`PRIMARY KEY (scope, path)` on entries +
+	* `idx_changelog_scope_seq` on changelog) keep this O(log n).
+	*
+	* `deviceId` is `null` when the entry was written via the blocklet
+	* exemption path (skipChangelog = true) — there's no changelog row to
+	* read the device id from. The handler exposes `null` to clients in
+	* the 409 body.
+	*
+	* Returns `null` when no entry exists at this path.
+	*/
+	async getCurrentEntry(afsPath) {
+		const treePath = afsPath.replace(/^\/+/, "");
+		const row = await this.indexDb.prepare(`SELECT
+           e.cid AS cid,
+           e.mtime AS mtime,
+           (SELECT device_id FROM ds_changelog
+              WHERE scope = ? AND path = ? AND op = 'put'
+              ORDER BY seq DESC LIMIT 1) AS device_id
+         FROM ds_entries e
+         WHERE e.scope = ? AND e.path = ? AND e.kind = 'file'`).bind(this._scope, treePath, this._scope, treePath).first();
+		if (!row || row.cid === null) return null;
+		return {
+			cid: row.cid,
+			mtime: row.mtime,
+			deviceId: row.device_id
+		};
+	}
+	/**
+	* Read the changelog `seq` of the most recent write by `(scope, path,
+	* deviceId)` (Task 3.3).
+	*
+	* The Worker handler calls this AFTER `internalWrite/internalDelete`
+	* to recover the seq of the row just inserted, so the PUT/DELETE
+	* response can echo `{cid, seq}` for the client.
+	*
+	* The triple WHERE clause (scope + path + device_id) is the safety
+	* mechanism for concurrent writers: each writer is guaranteed to have
+	* a unique `device_id` (validated by the Worker handler's strict
+	* format regex BEFORE we get here), so even if two PUTs on the same
+	* path race, each call's getLastSeq sees ONLY its own write — never
+	* the other writer's.
+	*
+	* Returns `0` when no row matches (impossible if called immediately
+	* after a successful internalWrite, but defensive against
+	* skipChangelog = true callers — blocklet exempt PUTs have no
+	* changelog row at all and the handler should NOT call this for them).
+	*/
+	async getLastSeq(afsPath, deviceId) {
+		const treePath = afsPath.replace(/^\/+/, "");
+		return (await this.indexDb.prepare(`SELECT MAX(seq) AS seq FROM ds_changelog
+         WHERE scope = ? AND path = ? AND device_id = ?`).bind(this._scope, treePath, deviceId).first())?.seq ?? 0;
+	}
+	/**
+	* Direct delete path for the Worker HTTP handler (Task 2.4b).
+	*
+	* Semantics mirror `DIDSpaceProvider.deleteHandler`:
+	*   1. Read the current entry (for GC enqueue of the soon-to-be-orphaned CID).
+	*   2. `treeIndex.delete` — atomic `entries` delete + `changelog` delete row
+	*      (Task 2.4a's `INSERT INTO ds_changelog SELECT ... FROM ds_entries` pattern
+	*      captures the old CID in-batch).
+	*   3. Enqueue the old CID for GC. Enqueueing is safe even under races —
+	*      the GC job's `isReferenced` check skips CIDs still referenced by
+	*      other rows.
+	*
+	* Returns an empty object (no `seq` for the same reason as `internalWrite`).
+	* Callers that need to know whether anything was actually deleted can rely
+	* on the absence of an `AFSNotFoundError` — Task 2.4b's handler converts
+	* that to a 404 response.
+	*/
+	async internalDelete(afsPath, opts) {
+		const treePath = afsPath.replace(/^\/+/, "");
+		const treeIndex = this.makeTreeIndex();
+		if (isShareReservedPath(afsPath)) throw new AFSForbiddenError(afsPath, "share-path-reserved");
+		const entry = await treeIndex.get(treePath, { includeContent: false });
+		if (!entry) return { deleted: false };
+		await this.gcQueue.enqueue([entry.cid]);
+		await treeIndex.delete(treePath, opts);
+		await applyShareDeleteHook({
+			afsPath,
+			treePath,
+			ownerDid: this._scope,
+			resolver: this.shareResolver
+		});
+		await applyBlockletDeleteHook({
+			afsPath,
+			treePath,
+			ownerDid: this.userDid,
+			resolver: this.resolver
+		});
+		return { deleted: true };
+	}
+	/**
+	* Clean up resources. Drops the cached instance-space map so retained AFS
+	* instances are GC-eligible alongside this DID-Space.
+	*/
+	close() {
+		this.instanceSpaces.clear();
+	}
+};
+
+//#endregion
+export { CloudflareDIDSpace, normalizeId, validateId };
+//# sourceMappingURL=cloudflare.mjs.map

package/dist/cloudflare.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.mjs","names":[],"sources":["../src/cloudflare.ts"],"sourcesContent":["/**\n * CloudflareDIDSpace — Cloudflare backend for DID-scoped storage.\n *\n * Composes DIDSpaceProvider (files via R2 + D1 TreeIndex) per app,\n * with logical isolation (separate D1 scope per user+app DID).\n *\n * Same interface as local DIDSpace for 100% compatibility.\n *\n * Usage:\n *   const space = new CloudflareDIDSpace({ userDid: \"did:abt:z1...\", objectStore, indexDb });\n *   const afs = await space.getInstanceSpace({ instanceDid: \"z1app\", role: \"system\" });\n *   await afs.write(\"/hello.txt\", { content: \"hello\" });\n */\n\nimport { AFS, type AFSAccessMode, AFSForbiddenError, nsLog } from \"@aigne/afs\";\nimport type { ObjectStore } from \"@aigne/afs-r2\";\nimport { applyBlockletDeleteHook, applyBlockletWriteHook } from \"./blocklet-hook.js\";\nimport { computeCID } from \"./cid.js\";\nimport { CachingObjectStore, CidByteCache } from \"./cid-byte-cache.js\";\nimport { D1GCQueue } from \"./d1-gc-queue.js\";\nimport { D1ResolveStore } from \"./d1-resolve-store.js\";\nimport { D1TreeIndex } from \"./d1-tree-index.js\";\nimport type { DIDSpaceLike, InstanceSpaceOptions } from \"./did-space-like.js\";\nimport { normalizeId, validateId } from \"./did-utils.js\";\nimport { DIDSpaceProvider } from \"./index.js\";\nimport { decodeInlineText } from \"./inline-content.js\";\nimport { detectMimeType } from \"./mime-utils.js\";\nimport { objectKeyForCid } from \"./object-key.js\";\nimport { PrefixedTreeIndex } from \"./prefixed-tree-index.js\";\nimport type { PresignSigner } from \"./presign-signer.js\";\nimport { DIDSpaceResolver } from \"./resolve.js\";\nimport { deriveScope } from \"./scope-id.js\";\nimport { isShareReservedPath } from \"./share-declaration.js\";\nimport { applyShareDeleteHook, applyShareWriteHook } from \"./share-hook.js\";\nimport type { ShareResolver } from \"./share-resolve.js\";\nimport type { PutOpts, TreeEntry } from \"./tree-index.js\";\nimport { D1UploadSessionStore } from \"./upload-session-store.js\";\n\nexport { normalizeId, validateId } from \"./did-utils.js\";\n\n/** provider:did-space structured logger (debug self-guards; off by default). */\nconst log = nsLog(\"provider:did-space\");\n\nexport interface CloudflareDIDSpaceOptions {\n  /** Owner DID of this space */\n  userDid: string;\n  /** Shared R2 object store (content-addressed, shared across all apps) */\n  objectStore: ObjectStore;\n  /** D1 database for tree index + resolve entries */\n  indexDb: D1Database;\n  /**\n   * Optional per-deployment HMAC secret for scope de-identification (README §4.4).\n   * When set, all D1 storage keys (`entries.scope` / `changelog.scope` /\n   * `shares.owner_did`) become `deriveScope(userDid, secret)` — an opaque HMAC —\n   * instead of the plaintext DID. When absent, scope stays plaintext (de-id off,\n   * back-compat). Injected along `objectStore` / `indexDb` by the resolver.\n   */\n  scopeHmacSecret?: Uint8Array;\n  /** Optional: ShareResolver for .share reconcile hook (Phase 0.4) */\n  shareResolver?: ShareResolver;\n  /**\n   * Route READ-serving D1 queries through a D1 Session\n   * (`withSession(\"first-unconstrained\")`) so they can be served by the\n   * nearest read replica. Requires `read_replication: { mode: \"auto\" }` on the\n   * D1 database (a DB-level setting, NOT wrangler.toml) — otherwise every query\n   * stays on primary regardless of this flag.\n   *\n   * Only the read paths honor this (getInstanceSpace / getConfigSpace /\n   * getUserSpace / listApps / resolver). The write + GC paths (internalWrite /\n   * internalDelete / gcQueue) ALWAYS use the primary: they read the old entry to\n   * drive GC, and a stale replica read there would compute the wrong `oldCid`.\n   *\n   * Consistency note: each tree-index opens its own session with no bookmark\n   * threading, so this is \"first-unconstrained\" (potentially-stale) reads.\n   * Read-your-write holds WITHIN a single mounted AFS (same session) but NOT\n   * across requests. Default false (last-write-wins on primary, back-compat).\n   */\n  useReplica?: boolean;\n  /**\n   * Object-store presigned-PUT signer (DID Space upload plane, §15 decision 7).\n   * Injected by the CF runtime when R2 signer credentials are configured;\n   * `prepare-upload` (P2) mints exact-key checksum-pinned grants through it.\n   * Absent → no grant capability (clients fall back to batchWrite). Node never\n   * injects one (decision 8, fallback-only).\n   */\n  signer?: PresignSigner;\n  /**\n   * upload-limits Phase 5 per-scope byte quota (bytes). 0 / unset = OFF (the\n   * opt-in default). Injected by the CF runtime from `resolveUploadLimits`'s\n   * `maxBytesPerScope`; enforced on every write through this space's tree index.\n   */\n  maxBytesPerScope?: number;\n}\n\nexport type { InstanceSpaceOptions } from \"./did-space-like.js\";\n\nexport class CloudflareDIDSpace implements DIDSpaceLike {\n  /** Real normalizeId(DID) — identity, returned to callers (NOT a storage key). */\n  private readonly userDid: string;\n  /**\n   * Storage scope — `deriveScope(userDid, secret)` when de-id is on, else the\n   * plaintext `userDid`. Every D1 storage/query key uses this, never `userDid`.\n   * Named `_scope` to avoid colliding with the `get scope()` accessor (README §4.1).\n   */\n  private readonly _scope: string;\n  private readonly objectStore: ObjectStore;\n  private readonly indexDb: D1Database;\n  private _resolver?: DIDSpaceResolver;\n  /** Optional ShareResolver for .share reconcile hook (Phase 0.4) */\n  private readonly shareResolver?: ShareResolver;\n  /** Read replica opt-in for read-serving paths only — see options doc. */\n  private readonly useReplica: boolean;\n  /** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */\n  private readonly maxBytesPerScope: number;\n  /**\n   * Instance space cache keyed by (role, useReplica) — same shape as `local.ts`\n   * `instanceSpaces`. Without it, `getInstanceSpace` returns a fresh `AFS`\n   * (and fresh `EventBus`) every call, so propBind subscribe (registered on\n   * AFS_A at session start) and the agent's subsequent write (executing on\n   * AFS_B for that exec) cross different buses — the write's `afs:write`\n   * event never reaches the subscriber, so the live patch silently drops and\n   * the user only sees the new value after a manual page reload (Layer 2\n   * staleness on staging). Bounded by the lifetime of this DID-Space (per\n   * caller in the resolver), the same memory budget the resolver already\n   * spends on `spaces`.\n   */\n  private readonly instanceSpaces = new Map<string, AFS>();\n  /**\n   * User-space cache keyed by (accessMode, useReplica) — the getUserSpace\n   * counterpart of {@link instanceSpaces}. Without it, every `getUserSpace()`\n   * builds a fresh `AFS` and re-runs `AFS.mount()`'s async provider health check\n   * (a root `stat` → `countChildren` + list). Blocklet serve calls getUserSpace\n   * once PER stage (reader / afsRoot), so a cold page paid that root enumeration\n   * 3× (issue #808 #4). Caching the handle reuses the mounted provider; data\n   * reads stay fresh (path→cid D1 lookups are never cached), so zero staleness.\n   */\n  private readonly userSpaces = new Map<string, AFS>();\n  /** Shared GC queue instance — created once per CloudflareDIDSpace instance */\n  readonly gcQueue: D1GCQueue;\n  /** Injected presigned-PUT signer (upload plane). Undefined → no grant capability. */\n  private readonly signer?: PresignSigner;\n\n  constructor(options: CloudflareDIDSpaceOptions) {\n    validateId(options.userDid);\n    this.userDid = normalizeId(options.userDid);\n    // de-id opt-in (README §4.4): derive an opaque storage scope only when a\n    // secret is provided; otherwise keep the plaintext DID (back-compat). The\n    // identity (`userDid`) is always the real DID.\n    this._scope = options.scopeHmacSecret\n      ? deriveScope(this.userDid, options.scopeHmacSecret)\n      : this.userDid;\n    // GC plan §4.3 — Model B global object pool: inject the raw R2 store\n    // directly (no per-user key prefix), so identical bytes dedup across users\n    // at the canonical key `objects/{cid}`. Cross-user read isolation is now\n    // enforced at the index layer (`DIDSpaceProvider.readHandler` gates\n    // `.objects/{cid}` on a view-local `treeIndex.isReferenced`), NOT by the\n    // store key shape. (Was `ScopedObjectStore`, removed in the GC plan.)\n    //\n    // #674 perf: wrap the store with a content-addressed byte cache so repeat\n    // reads of the same blob (e.g. a published blocklet's files across requests)\n    // skip the R2 GET. Keyed by cid (immutable) → no staleness, no TTL. This\n    // instance is cached per-user by the space resolver, so the cache persists\n    // for the isolate lifetime — but bounded (LRU) so memory stays flat.\n    this.objectStore = new CachingObjectStore(options.objectStore, new CidByteCache());\n    this.indexDb = options.indexDb;\n    // GC queue always on primary: dequeue + isReferenced reference-counting must\n    // see the latest writes, never a replica.\n    this.gcQueue = new D1GCQueue(options.indexDb);\n    this.shareResolver = options.shareResolver;\n    this.useReplica = options.useReplica ?? false;\n    this.maxBytesPerScope = options.maxBytesPerScope ?? 0;\n    this.signer = options.signer;\n  }\n\n  /**\n   * Construct a D1TreeIndex for this scope with the per-scope byte quota\n   * (upload-limits Phase 5) always injected — so every write path enforces it\n   * uniformly without each call site remembering to thread it. 0 = quota off.\n   */\n  private makeTreeIndex(opts?: { useReplica?: boolean; inlineCache?: \"on\" }): D1TreeIndex {\n    return new D1TreeIndex(this.indexDb, this._scope, {\n      ...opts,\n      maxBytesPerScope: this.maxBytesPerScope,\n    });\n  }\n\n  /**\n   * The injected presigned-PUT signer, or undefined when no R2 signer\n   * credentials are configured. The seam through which `prepare-upload` (P2)\n   * mints upload grants; also the capability signal clients use to decide\n   * grant-path vs batchWrite fallback (§15 decision 7/8).\n   */\n  get presignSigner(): PresignSigner | undefined {\n    return this.signer;\n  }\n\n  /**\n   * Upload-plane deps for the user-facing `DIDSpaceProvider` (design §7): the\n   * injected signer (CF mints grants; absent → fallback), a D1-backed session\n   * store, and the de-identified storage scope written into `upload_sessions`.\n   * Only the user space gets these — `/instance` (installer) + config don't.\n   */\n  private uploadDeps() {\n    return {\n      signer: this.signer,\n      uploadSessionStore: new D1UploadSessionStore(this.indexDb),\n      uploadScope: this._scope,\n    };\n  }\n\n  /**\n   * Get an isolated AFS instance for a blocklet instance under this DID Space,\n   * scoped by role (system = installer-side data, user = caller-side data).\n   *\n   * Layout (PrefixedTreeIndex prefix relative to `entries.scope = userDid`):\n   *   role:\"system\" → blocklets/{instanceDid}/system/   (content tree, mounted at `/`)\n   *   role:\"user\"   → blocklets/{instanceDid}/user/      (content tree, mounted at `/`)\n   *   config        → blocklets/{instanceDid}/config/    (sibling fragment, getConfigSpace)\n   *\n   * /files-prefix-removal: content tree is the role root (no `files/` wrapper);\n   * config is a sibling fragment (invisible to `/instance`); vault removed.\n   *\n   * did-space-composition Phase 2 (symmetric with the local backend): the user\n   * fragment is a SINGLE `user` subtree. Per-user isolation comes from scope =\n   * caller's userDid (the resolver hands back a CloudflareDIDSpace scoped to the\n   * caller), so a `users/{userDid}` path segment would be redundant. `userDid`\n   * is @deprecated for this call and ignored for the path.\n   *\n   * Cached per (instanceDid, role, useReplica) — first caller's accessMode\n   * wins for that triple (mirrors local.ts). See `instanceSpaces` for the\n   * live-update rationale.\n   */\n  async getInstanceSpace(opts: InstanceSpaceOptions): Promise<AFS> {\n    log.debug({ message: \"getInstanceSpace\", instanceDid: opts.instanceDid, role: opts.role });\n    validateId(opts.instanceDid);\n    if (opts.role !== \"system\" && opts.role !== \"user\") {\n      throw new Error(`getInstanceSpace: invalid role \"${opts.role}\"`);\n    }\n    // userDid is @deprecated for role:\"user\" — validated as defense if present,\n    // but never enters the path (the space's scope IS the user). See local.ts.\n    if (opts.role === \"user\" && opts.userDid != null) {\n      validateId(opts.userDid);\n    }\n\n    const bareInstanceId = normalizeId(opts.instanceDid);\n    // Cache key splits on useReplica because the D1TreeIndex's session is\n    // fixed at construction — a replica-vs-primary mismatch can't be served\n    // by sharing one AFS instance (a reconcile pass asking for \"primary\" must\n    // get a primary-bound space). Within a single (role, useReplica) bucket,\n    // every caller shares the same eventBus → propBind sees its sibling\n    // writes.\n    const useReplica = opts.consistency === \"primary\" ? false : this.useReplica;\n    const cacheKey = `${bareInstanceId}::${opts.role}::${useReplica ? \"r\" : \"p\"}`;\n    const cached = this.instanceSpaces.get(cacheKey);\n    if (cached) return cached;\n\n    const subtree =\n      opts.role === \"system\"\n        ? `blocklets/${bareInstanceId}/system`\n        : `blocklets/${bareInstanceId}/user`;\n    const accessMode: AFSAccessMode = opts.accessMode ?? \"readwrite\";\n\n    const afs = new AFS();\n    // Read replica opt-in: the mounted AFS reuses this single session, so\n    // write→read within it stays sequentially consistent even on a replica.\n    // inlineCache \"on\" = write-through (settings-layering 1d): text content\n    // ≤ threshold rides the index row as a cid-verified read-acceleration\n    // copy (saves an R2 GET per hit). `objects/{cid}` is ALWAYS written\n    // regardless (cas-blob-always-written) — sync/GC semantics untouched.\n    //\n    // Live Update Resilience 1d / DEC-5 (read-your-watermark) — RESERVED HOOK,\n    // currently UNWIRED. Passing `consistency: \"primary\"` pins this space to the\n    // primary DB (useReplica:false) so a reconcile observes its own watermark\n    // rather than a replica snapshot (replica lag ~30-75ms, no SLA). The choice\n    // must be made HERE (the layer that holds indexDb) because the D1TreeIndex\n    // conn is fixed at construction — a per-op flag would not retarget an\n    // already-built session.\n    //\n    // No caller passes `consistency` today (cf-session-view's getInstanceSpace\n    // omits it), and reading the watermark from the replica is SAFE without this\n    // pin: the client (web-page/live-update.ts) makes a stale read cost at most\n    // one redundant refetch / one poll cycle, NEVER a missed update —\n    //   1. self-write refetches UNCONDITIONALLY (never gates on the watermark);\n    //   2. foreign-write detection rides the ~45s visible-only poll, so the\n    //      ~75ms replica lag is in the noise and the next poll reads the caught-\n    //      up value;\n    //   3. the refetch predicate is monotonic (`raw > lastVersion`) — a stale\n    //      read skips one cycle, never lowers the baseline;\n    //   4. pushes carry their own prefix-local liveSeq and reconcile on any\n    //      gap/forged/bulk value, never adopting a replica read.\n    // The \"(with no further edge) permanently stale\" failure this would guard\n    // against needs NO poll backstop, which does not hold — so the pin is\n    // redundant defense-in-depth, kept only as an opt-in for a caller that ever\n    // needs strict read-your-watermark. Default (omitted/\"replica\") keeps the\n    // backend's standing useReplica. (useReplica is computed above as part of\n    // the cache key so subscribe + write share an AFS — see ~line 150.)\n    const baseTreeIndex = this.makeTreeIndex({ useReplica, inlineCache: \"on\" });\n\n    // /files-prefix-removal: content tree IS the role root (prefix `${subtree}/`,\n    // mounted at `/`). config moved to a sibling fragment (getConfigSpace);\n    // vault removed (real vault = @aigne/afs-vault provider).\n    const fileProvider = new DIDSpaceProvider({\n      did: bareInstanceId,\n      objectStore: this.objectStore,\n      treeIndex: new PrefixedTreeIndex(baseTreeIndex, `${subtree}/`),\n      name: \"content\",\n      accessMode,\n      gcQueue: this.gcQueue,\n      // Share-out + blocklet publish on the caller's OWN per-user fragment\n      // (role:\"user\" — the `/user` session mount, mobile-sync + remote-publish\n      // target). The provider's treeIndex is prefixed to `blocklets/<i>/user/`\n      // and its `did` is the instance, so both hooks need the whole-tree path\n      // restored: `shareTreePrefix` does that (read by share+blocklet hookArgs).\n      // It is set for ALL role:\"user\" fragments (independent of shareResolver),\n      // so the blocklet hook captures the full physical path even when shares\n      // are off. role:\"system\" stays excluded (installer data is never public).\n      //   - share: `shareOwnerDid` keys the share to the whole-space user scope.\n      //   - blocklet: `blockletOwnerDid` records the PLAINTEXT userDid (the serve\n      //     path re-derives the storage scope from it); the instance `did` would\n      //     be wrong here.\n      ...(opts.role === \"user\"\n        ? {\n            shareTreePrefix: `${subtree}/`,\n            ...(this.shareResolver\n              ? { shareResolver: this.shareResolver, shareOwnerDid: this._scope }\n              : {}),\n            blockletResolver: this.resolver,\n            blockletOwnerDid: this.userDid,\n          }\n        : {}),\n      // Upload plane only on the caller's own `/user` fragment (the native-sync\n      // target); `/instance` (role:system, installer data) never gets grants.\n      ...(opts.role === \"user\" ? this.uploadDeps() : {}),\n    });\n    await afs.mount(fileProvider, \"/\", { skipHealthCheck: true });\n\n    this.instanceSpaces.set(cacheKey, afs);\n    return afs;\n  }\n\n  /**\n   * Runtime-internal config fragment (`blocklets/<i>/config/`, mounted at\n   * `/`). Mirrors local `getConfigSpace`. Invisible to `/instance`; holds\n   * per-instance machine state like `mounts.toml`.\n   */\n  async getConfigSpace(instanceDid: string): Promise<AFS> {\n    validateId(instanceDid);\n    const bareInstanceId = normalizeId(instanceDid);\n    const afs = new AFS();\n    const baseTreeIndex = this.makeTreeIndex({ useReplica: this.useReplica, inlineCache: \"on\" });\n    const configProvider = new DIDSpaceProvider({\n      did: bareInstanceId,\n      objectStore: this.objectStore,\n      treeIndex: new PrefixedTreeIndex(baseTreeIndex, `blocklets/${bareInstanceId}/config/`),\n      name: \"config\",\n      accessMode: \"readwrite\",\n      gcQueue: this.gcQueue,\n    });\n    await afs.mount(configProvider, \"/\", { skipHealthCheck: true });\n    return afs;\n  }\n\n  /**\n   * List all instance DIDs that have storage in this user's space.\n   *\n   * Enumerates entries under the `blocklets/<instanceDid>/...` prefix and\n   * returns the distinct instance-DID segment. This mirrors the local\n   * backend's `listApps`, which enumerates `{userDir}/blocklets/*`. Legacy\n   * top-level `getAppSpace` segments are NOT enumerated — that layout is\n   * deprecated and removed in P4.\n   */\n  async listApps(): Promise<string[]> {\n    const idx = this.makeTreeIndex({ useReplica: this.useReplica });\n    const result = await idx.list(\"\", { limit: 1000 });\n\n    const apps = new Set<string>();\n    for (const entry of result.entries) {\n      const parts = entry.path.split(\"/\");\n      // blocklets/<instanceDid>/{system|user}/...\n      if (parts[0] === \"blocklets\" && parts[1]) {\n        apps.add(parts[1]);\n      }\n    }\n    return [...apps];\n  }\n\n  /**\n   * Contract alias (分叉 A, observability Phase 2) for the whole-space root.\n   * Delegates to {@link getUserSpace}; satisfies `DIDSpaceLike.getSpaceRoot`\n   * without renaming the existing CF method. Defaults readonly via getUserSpace.\n   */\n  async getSpaceRoot(options?: { accessMode?: AFSAccessMode }): Promise<AFS> {\n    return this.getUserSpace(options);\n  }\n\n  /**\n   * Get an AFS instance scoped to the user's entire DID Space.\n   * No appDid sub-partitioning.\n   */\n  async getUserSpace(options?: { accessMode?: AFSAccessMode }): Promise<AFS> {\n    log.debug({ message: \"getUserSpace\", userDid: this.userDid });\n    const accessMode: AFSAccessMode = options?.accessMode ?? \"readonly\";\n    // Cache key splits on useReplica for the same reason as instanceSpaces (the\n    // D1TreeIndex session is fixed at construction) and on accessMode (readonly\n    // vs readwrite build different providers). See userSpaces doc.\n    const cacheKey = `${accessMode}::${this.useReplica ? \"r\" : \"p\"}`;\n    const cached = this.userSpaces.get(cacheKey);\n    if (cached) return cached;\n    const afs = new AFS();\n    const provider = new DIDSpaceProvider({\n      did: this.userDid,\n      objectStore: this.objectStore,\n      treeIndex: this.makeTreeIndex({ useReplica: this.useReplica, inlineCache: \"on\" }),\n      name: \"did-space-user\",\n      accessMode,\n      shareResolver: this.shareResolver,\n      // #674: blocklet publish/resolve — whole-space writes (e.g. local-style\n      // `getUserSpace().write(\"/blocklets/<id>/blocklet.yaml\")`) register into\n      // the global resolve table. owner = plaintext userDid (NOT the de-id scope).\n      blockletResolver: this.resolver,\n      blockletOwnerDid: this.userDid,\n      ...this.uploadDeps(),\n    });\n    await afs.mount(provider, \"/\", { skipHealthCheck: true });\n    this.userSpaces.set(cacheKey, afs);\n    return afs;\n  }\n\n  get resolver(): DIDSpaceResolver {\n    if (!this._resolver) {\n      this._resolver = new DIDSpaceResolver(\n        new D1ResolveStore(this.indexDb, { useReplica: this.useReplica }),\n      );\n    }\n    return this._resolver;\n  }\n\n  /**\n   * Expose the underlying storage scope — used by worker handlers for\n   * cid-permission queries. MUST return the derived scope (not the plaintext\n   * DID) so the worker's `entries.scope` lookups match what was written.\n   */\n  get scope(): string {\n    return this._scope;\n  }\n\n  /**\n   * Direct write path for the Worker HTTP handler (Task 2.4b).\n   *\n   * Bypasses the generic `afs.write()` path because `AFSWriteEntryPayload` has\n   * no `deviceId`/`skipChangelog` field — the `PutOpts` cannot be smuggled\n   * through the public AFS API. The Worker handler therefore constructs a\n   * `CloudflareDIDSpace` and calls this method directly, passing the per-\n   * request `deviceId` read from the `X-Device-Id` header.\n   *\n   * Semantics mirror `DIDSpaceProvider.writeHandler`:\n   *   1. Compute the content-addressed CID from the payload bytes.\n   *   2. R2 put `objects/{cid}` if not already stored (head-check for dedup).\n   *   3. `treeIndex.put` — atomic `entries` + `changelog` write (Task 2.4a).\n   *   4. Enqueue the previous CID (if any) onto the GC queue for deferred\n   *      cleanup. Enqueuing an overwritten CID is a no-op if the CID is still\n   *      referenced by another row (the GC job's reference check handles it).\n   *\n   * Path conventions:\n   *   - `afsPath` is an AFS-style path WITH leading slash (e.g. `/foo.json`\n   *     or `/blocklets/z1abc/index.html`).\n   *   - The leading slash is stripped before `treeIndex.put`; the remainder is\n   *     stored verbatim under `entries.scope = this._scope` (the derived storage\n   *     scope when de-id is on, else the plaintext DID). This matches the\n   *     `getUserSpace()` layout (no appDid sub-partition) that blocklet publish\n   *     and general user-space CRUD share.\n   *\n   * Returns `{ cid, oldCid }`. `oldCid` is present only when an existing row\n   * was overwritten; the caller can treat its presence as \"something was\n   * replaced\" for change-tracking. `seq` is not returned — Task 2.4a's\n   * `treeIndex.put` does not expose the changelog's AUTOINCREMENT `seq`, and\n   * adding a separate SELECT round trip here is wasted work for the current\n   * sync path (which only cares about cid + oldCid).\n   *\n   * No event dispatch is performed (Decision 3A round 5): CloudflareDIDSpace\n   * has no event bus reference, the Worker runtime is request/response with\n   * no long-lived subscriber, and the sync protocol polls `changelog` rows\n   * by `seq` rather than reacting to transient event fan-out.\n   */\n  async internalWrite(\n    afsPath: string,\n    content: string | Uint8Array | ArrayBuffer,\n    opts: PutOpts,\n  ): Promise<{ cid: string; oldCid?: string }> {\n    // Normalise content to bytes + storage value (same branches as\n    // DIDSpaceProvider.writeHandler). Text stored as text; binary stored as\n    // ArrayBuffer — both are acceptable inputs to the R2 put API.\n    let bytes: Uint8Array;\n    let storeValue: string | ArrayBuffer;\n    if (content instanceof Uint8Array) {\n      bytes = content;\n      storeValue = bytes.buffer as ArrayBuffer;\n    } else if (content instanceof ArrayBuffer) {\n      bytes = new Uint8Array(content);\n      storeValue = content;\n    } else {\n      bytes = new TextEncoder().encode(content);\n      storeValue = content;\n    }\n\n    const cid = await computeCID(bytes);\n    // Single hardened key builder (validates the cid) — never raw `'objects/'+cid`.\n    const objectKey = objectKeyForCid(cid);\n\n    // Strip leading slash to match the tree-index path convention used by\n    // DIDSpaceProvider (see `treePath()` in index.ts:182).\n    const treePath = afsPath.replace(/^\\/+/, \"\");\n\n    // Phase 0.4: reserved path check + pre-io share hook (before R2 PUT)\n    if (isShareReservedPath(afsPath)) {\n      throw new AFSForbiddenError(afsPath, \"share-path-reserved\");\n    }\n    await applyShareWriteHook({\n      afsPath,\n      treePath,\n      bytes,\n      cid,\n      ownerDid: this._scope,\n      resolver: this.shareResolver,\n      phase: \"pre-io\",\n    });\n\n    // Content-addressed dedup — skip R2 put when the object already exists.\n    const existingObj = await this.objectStore.head(objectKey);\n    if (!existingObj) {\n      await this.objectStore.put(objectKey, storeValue);\n    }\n\n    const now = Date.now();\n    const mimeType = detectMimeType(afsPath) ?? undefined;\n\n    // Primary only (no useReplica): `put` reads the prior row to return oldCid\n    // for GC enqueue; a stale replica read here would leak/misroute GC.\n    const treeIndex = this.makeTreeIndex({ inlineCache: \"on\" });\n    // Write-through (1d): offer the payload as inline text when it decodes as\n    // strict UTF-8 (text mime, within cap). Best-effort — undecodable payloads\n    // simply aren't inlined; the blob above is ALWAYS written either way.\n    const entry: TreeEntry = { cid, size: bytes.length, mtime: now, ctime: now, mimeType };\n    const inlineText = decodeInlineText(bytes, mimeType);\n    if (inlineText !== null) entry.content = inlineText;\n    const { oldCid } = await treeIndex.put(treePath, entry, opts);\n\n    // §4.7.1 write-dequeue: a write re-references `cid` — remove it from the GC\n    // queue (if a prior delete/overwrite queued it) so a concurrent sweep can't\n    // delete a now-live object.\n    await this.gcQueue.remove(cid);\n    if (oldCid && oldCid !== cid) {\n      await this.gcQueue.enqueue([oldCid]);\n    }\n\n    // Phase 0.4: post-io share hook (after tree_entries written)\n    await applyShareWriteHook({\n      afsPath,\n      treePath,\n      bytes,\n      cid,\n      ownerDid: this._scope,\n      resolver: this.shareResolver,\n      phase: \"post-io\",\n    });\n\n    // #674: blocklet publish/resolve hook (CF direct write path). `treePath` is\n    // already whole-space scope-absolute here; owner = plaintext userDid.\n    // #1110: inject a CF-specific purge callback so a re-publish immediately\n    // invalidates the pre-rendered pages in the CF edge cache (`caches.default`).\n    await applyBlockletWriteHook({\n      afsPath,\n      treePath,\n      bytes,\n      ownerDid: this.userDid,\n      resolver: this.resolver,\n      // Guard: `caches` is CF-Worker-only global; undefined in Node/Bun context\n      // (e.g. Miniflare tests that instantiate CloudflareDIDSpace directly from\n      // Node rather than going through the Worker fetch handler).\n      purgeCachesForDomains:\n        typeof caches !== \"undefined\"\n          ? async (domains) => {\n              // Purge the root entry for each domain from the CF Cache API so\n              // the next request fetches the freshly published content (#1110).\n              // The CF Cache API has no wildcard/prefix delete — only exact URLs.\n              // We purge the root (most important) path; deeper paths expire at TTL.\n              // Cast: bun's CacheStorage lacks `.default`; CF workers-types has it.\n              const cfCaches = caches as unknown as {\n                default: { delete(r: Request): Promise<boolean> };\n              };\n              for (const domain of domains) {\n                const rootKey = new Request(`https://${domain}/`, { method: \"GET\" });\n                await cfCaches.default.delete(rootKey);\n              }\n            }\n          : undefined,\n    });\n\n    return oldCid === undefined ? { cid } : { cid, oldCid };\n  }\n\n  /**\n   * Read the current entry's cid + mtime + last-write deviceId for an\n   * If-Match precondition check (Task 3.3).\n   *\n   * Used by `_createSpaceHandler` BEFORE issuing a write when the client\n   * sends `If-Match: <cid>` for optimistic concurrency control. The\n   * handler compares the returned `cid` to the header value and returns\n   * 409 (with the full snapshot below) on mismatch, or 412 if the row\n   * doesn't exist (first-create with If-Match).\n   *\n   * The query joins `entries` (cid + mtime authoritative) with the most\n   * recent put row in `changelog` (device_id of last writer). Both\n   * indices used (`PRIMARY KEY (scope, path)` on entries +\n   * `idx_changelog_scope_seq` on changelog) keep this O(log n).\n   *\n   * `deviceId` is `null` when the entry was written via the blocklet\n   * exemption path (skipChangelog = true) — there's no changelog row to\n   * read the device id from. The handler exposes `null` to clients in\n   * the 409 body.\n   *\n   * Returns `null` when no entry exists at this path.\n   */\n  async getCurrentEntry(afsPath: string): Promise<{\n    cid: string;\n    mtime: number;\n    deviceId: string | null;\n  } | null> {\n    const treePath = afsPath.replace(/^\\/+/, \"\");\n    const row = await this.indexDb\n      .prepare(\n        `SELECT\n           e.cid AS cid,\n           e.mtime AS mtime,\n           (SELECT device_id FROM ds_changelog\n              WHERE scope = ? AND path = ? AND op = 'put'\n              ORDER BY seq DESC LIMIT 1) AS device_id\n         FROM ds_entries e\n         WHERE e.scope = ? AND e.path = ? AND e.kind = 'file'`,\n      )\n      .bind(this._scope, treePath, this._scope, treePath)\n      .first<{ cid: string | null; mtime: number; device_id: string | null }>();\n    if (!row || row.cid === null) return null;\n    return { cid: row.cid, mtime: row.mtime, deviceId: row.device_id };\n  }\n\n  /**\n   * Read the changelog `seq` of the most recent write by `(scope, path,\n   * deviceId)` (Task 3.3).\n   *\n   * The Worker handler calls this AFTER `internalWrite/internalDelete`\n   * to recover the seq of the row just inserted, so the PUT/DELETE\n   * response can echo `{cid, seq}` for the client.\n   *\n   * The triple WHERE clause (scope + path + device_id) is the safety\n   * mechanism for concurrent writers: each writer is guaranteed to have\n   * a unique `device_id` (validated by the Worker handler's strict\n   * format regex BEFORE we get here), so even if two PUTs on the same\n   * path race, each call's getLastSeq sees ONLY its own write — never\n   * the other writer's.\n   *\n   * Returns `0` when no row matches (impossible if called immediately\n   * after a successful internalWrite, but defensive against\n   * skipChangelog = true callers — blocklet exempt PUTs have no\n   * changelog row at all and the handler should NOT call this for them).\n   */\n  async getLastSeq(afsPath: string, deviceId: string): Promise<number> {\n    const treePath = afsPath.replace(/^\\/+/, \"\");\n    const row = await this.indexDb\n      .prepare(\n        `SELECT MAX(seq) AS seq FROM ds_changelog\n         WHERE scope = ? AND path = ? AND device_id = ?`,\n      )\n      .bind(this._scope, treePath, deviceId)\n      .first<{ seq: number | null }>();\n    return row?.seq ?? 0;\n  }\n\n  /**\n   * Direct delete path for the Worker HTTP handler (Task 2.4b).\n   *\n   * Semantics mirror `DIDSpaceProvider.deleteHandler`:\n   *   1. Read the current entry (for GC enqueue of the soon-to-be-orphaned CID).\n   *   2. `treeIndex.delete` — atomic `entries` delete + `changelog` delete row\n   *      (Task 2.4a's `INSERT INTO ds_changelog SELECT ... FROM ds_entries` pattern\n   *      captures the old CID in-batch).\n   *   3. Enqueue the old CID for GC. Enqueueing is safe even under races —\n   *      the GC job's `isReferenced` check skips CIDs still referenced by\n   *      other rows.\n   *\n   * Returns an empty object (no `seq` for the same reason as `internalWrite`).\n   * Callers that need to know whether anything was actually deleted can rely\n   * on the absence of an `AFSNotFoundError` — Task 2.4b's handler converts\n   * that to a 404 response.\n   */\n  async internalDelete(afsPath: string, opts: PutOpts): Promise<{ deleted: boolean }> {\n    const treePath = afsPath.replace(/^\\/+/, \"\");\n    // Primary only (no useReplica): reads the entry to GC its CID after delete;\n    // a stale replica read here would leak/misroute GC.\n    const treeIndex = this.makeTreeIndex();\n\n    // Phase 0.4: reserved path check\n    if (isShareReservedPath(afsPath)) {\n      throw new AFSForbiddenError(afsPath, \"share-path-reserved\");\n    }\n\n    // Read first so we can GC the CID AFTER the delete succeeds. Matches the\n    // enqueue-before-delete ordering in DIDSpaceProvider.deleteHandler — the\n    // rationale there is that a failing enqueue leaves entries untouched, and\n    // a failing delete after a successful enqueue is safe because the CID is\n    // still referenced. We preserve the same ordering here.\n    // GC enqueue path — needs only entry.cid, never the inline bytes.\n    const entry = await treeIndex.get(treePath, { includeContent: false });\n    if (!entry) {\n      return { deleted: false };\n    }\n\n    await this.gcQueue.enqueue([entry.cid]);\n    await treeIndex.delete(treePath, opts);\n\n    // Phase 0.4: delete hook (after tree_entries removed)\n    await applyShareDeleteHook({\n      afsPath,\n      treePath,\n      ownerDid: this._scope,\n      resolver: this.shareResolver,\n    });\n\n    // #674: blocklet unregister (CF direct delete path).\n    await applyBlockletDeleteHook({\n      afsPath,\n      treePath,\n      ownerDid: this.userDid,\n      resolver: this.resolver,\n    });\n\n    return { deleted: true };\n  }\n\n  /**\n   * Clean up resources. Drops the cached instance-space map so retained AFS\n   * instances are GC-eligible alongside this DID-Space.\n   */\n  close(): void {\n    this.instanceSpaces.clear();\n  }\n}\n"],"mappings":"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"}