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

package/dist/cloudflare.d.cts

@@ -0,0 +1,307 @@
+import { ObjectStore } from "./platform/r2/dist/types.cjs";
+import { D1GCQueue } from "./d1-gc-queue.cjs";
+import { DIDSpaceLike as DIDSpaceLike$1, InstanceSpaceOptions } from "./did-space-like.cjs";
+import { PresignSigner } from "./presign-signer.cjs";
+import { DIDSpaceResolver } from "./resolve.cjs";
+import { PutOpts } from "./tree-index.cjs";
+import { ShareResolver } from "./share-resolve.cjs";
+import { normalizeId, validateId } from "./did-utils.cjs";
+import { AFS, AFSAccessMode } from "@aigne/afs";
+
+//#region src/cloudflare.d.ts
+interface CloudflareDIDSpaceOptions {
+  /** Owner DID of this space */
+  userDid: string;
+  /** Shared R2 object store (content-addressed, shared across all apps) */
+  objectStore: ObjectStore;
+  /** D1 database for tree index + resolve entries */
+  indexDb: D1Database;
+  /**
+   * Optional per-deployment HMAC secret for scope de-identification (README §4.4).
+   * When set, all D1 storage keys (`entries.scope` / `changelog.scope` /
+   * `shares.owner_did`) become `deriveScope(userDid, secret)` — an opaque HMAC —
+   * instead of the plaintext DID. When absent, scope stays plaintext (de-id off,
+   * back-compat). Injected along `objectStore` / `indexDb` by the resolver.
+   */
+  scopeHmacSecret?: Uint8Array;
+  /** Optional: ShareResolver for .share reconcile hook (Phase 0.4) */
+  shareResolver?: ShareResolver;
+  /**
+   * Route READ-serving D1 queries through a D1 Session
+   * (`withSession("first-unconstrained")`) so they can be served by the
+   * nearest read replica. Requires `read_replication: { mode: "auto" }` on the
+   * D1 database (a DB-level setting, NOT wrangler.toml) — otherwise every query
+   * stays on primary regardless of this flag.
+   *
+   * Only the read paths honor this (getInstanceSpace / getConfigSpace /
+   * getUserSpace / listApps / resolver). The write + GC paths (internalWrite /
+   * internalDelete / gcQueue) ALWAYS use the primary: they read the old entry to
+   * drive GC, and a stale replica read there would compute the wrong `oldCid`.
+   *
+   * Consistency note: each tree-index opens its own session with no bookmark
+   * threading, so this is "first-unconstrained" (potentially-stale) reads.
+   * Read-your-write holds WITHIN a single mounted AFS (same session) but NOT
+   * across requests. Default false (last-write-wins on primary, back-compat).
+   */
+  useReplica?: boolean;
+  /**
+   * Object-store presigned-PUT signer (DID Space upload plane, §15 decision 7).
+   * Injected by the CF runtime when R2 signer credentials are configured;
+   * `prepare-upload` (P2) mints exact-key checksum-pinned grants through it.
+   * Absent → no grant capability (clients fall back to batchWrite). Node never
+   * injects one (decision 8, fallback-only).
+   */
+  signer?: PresignSigner;
+  /**
+   * upload-limits Phase 5 per-scope byte quota (bytes). 0 / unset = OFF (the
+   * opt-in default). Injected by the CF runtime from `resolveUploadLimits`'s
+   * `maxBytesPerScope`; enforced on every write through this space's tree index.
+   */
+  maxBytesPerScope?: number;
+}
+declare class CloudflareDIDSpace implements DIDSpaceLike$1 {
+  /** Real normalizeId(DID) — identity, returned to callers (NOT a storage key). */
+  private readonly 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).
+   */
+  private readonly _scope;
+  private readonly objectStore;
+  private readonly indexDb;
+  private _resolver?;
+  /** Optional ShareResolver for .share reconcile hook (Phase 0.4) */
+  private readonly shareResolver?;
+  /** Read replica opt-in for read-serving paths only — see options doc. */
+  private readonly useReplica;
+  /** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */
+  private readonly 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`.
+   */
+  private readonly instanceSpaces;
+  /**
+   * 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.
+   */
+  private readonly userSpaces;
+  /** Shared GC queue instance — created once per CloudflareDIDSpace instance */
+  readonly gcQueue: D1GCQueue;
+  /** Injected presigned-PUT signer (upload plane). Undefined → no grant capability. */
+  private readonly signer?;
+  constructor(options: CloudflareDIDSpaceOptions);
+  /**
+   * 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.
+   */
+  private makeTreeIndex;
+  /**
+   * 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(): PresignSigner | undefined;
+  /**
+   * 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.
+   */
+  private uploadDeps;
+  /**
+   * 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.
+   */
+  getInstanceSpace(opts: InstanceSpaceOptions): Promise<AFS>;
+  /**
+   * Runtime-internal config fragment (`blocklets/<i>/config/`, mounted at
+   * `/`). Mirrors local `getConfigSpace`. Invisible to `/instance`; holds
+   * per-instance machine state like `mounts.toml`.
+   */
+  getConfigSpace(instanceDid: string): Promise<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.
+   */
+  listApps(): Promise<string[]>;
+  /**
+   * 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.
+   */
+  getSpaceRoot(options?: {
+    accessMode?: AFSAccessMode;
+  }): Promise<AFS>;
+  /**
+   * Get an AFS instance scoped to the user's entire DID Space.
+   * No appDid sub-partitioning.
+   */
+  getUserSpace(options?: {
+    accessMode?: AFSAccessMode;
+  }): Promise<AFS>;
+  get resolver(): DIDSpaceResolver;
+  /**
+   * 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(): string;
+  /**
+   * 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.
+   */
+  internalWrite(afsPath: string, content: string | Uint8Array | ArrayBuffer, opts: PutOpts): Promise<{
+    cid: string;
+    oldCid?: string;
+  }>;
+  /**
+   * 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.
+   */
+  getCurrentEntry(afsPath: string): Promise<{
+    cid: string;
+    mtime: number;
+    deviceId: string | null;
+  } | null>;
+  /**
+   * 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).
+   */
+  getLastSeq(afsPath: string, deviceId: string): Promise<number>;
+  /**
+   * 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.
+   */
+  internalDelete(afsPath: string, opts: PutOpts): Promise<{
+    deleted: boolean;
+  }>;
+  /**
+   * Clean up resources. Drops the cached instance-space map so retained AFS
+   * instances are GC-eligible alongside this DID-Space.
+   */
+  close(): void;
+}
+//#endregion
+export { CloudflareDIDSpace, CloudflareDIDSpaceOptions, type InstanceSpaceOptions, normalizeId, validateId };
+//# sourceMappingURL=cloudflare.d.cts.map

package/dist/cloudflare.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.cts","names":[],"sources":["../src/cloudflare.ts"],"mappings":";;;;;;;;;;;UA2CiB,yBAAA;EAIF;EAFb,OAAA;EAIS;EAFT,WAAA,EAAa,WAAA;EAUK;EARlB,OAAA,EAAS,UAAA;EAUO;;;;;;;EAFhB,eAAA,GAAkB,UAAA;EAuCY;EArC9B,aAAA,GAAgB,aAAA;EA+EE;;;;;;;;;;;;;;;;;EA7DlB,UAAA;EA0ZQ;;;;;;;EAlZR,MAAA,GAAS,aAAA;EAW4C;;;;;EALrD,gBAAA;AAAA;AAAA,cAKW,kBAAA,YAA8B,cAAA;EAiBxB;EAAA,iBAfA,OAAA;EAsCA;;;;;EAAA,iBAhCA,MAAA;EAAA,iBACA,WAAA;EAAA,iBACA,OAAA;EAAA,QACT,SAAA;EAqFa;EAAA,iBAnFJ,aAAA;EA2HX;EAAA,iBAzHW,UAAA;EAyHM;EAAA,iBAvHN,gBAAA;EAuH2C;;;;;;;;;;;;EAAA,iBA1G3C,cAAA;EAiRX;;;;;;;;;EAAA,iBAvQW,UAAA;EA6Vf;EAAA,SA3VO,OAAA,EAAS,SAAA;EA4Ve;EAAA,iBA1VhB,MAAA;cAEL,OAAA,EAAS,yBAAA;EAyVnB;;;;;EAAA,QApTM,aAAA;EA4bgC;;;;;;EAAA,IA/apC,aAAA,CAAA,GAAiB,aAAA;EA0dgC;;;;;;EAAA,QAhd7C,UAAA;EA6hBR;;;;;;;;;;;;;;;;;;;;;;EA/fM,gBAAA,CAAiB,IAAA,EAAM,oBAAA,GAAuB,OAAA,CAAQ,GAAA;;;;;;EAiHtD,cAAA,CAAe,WAAA,WAAsB,OAAA,CAAQ,GAAA;;;;;;;;;;EA0B7C,QAAA,CAAA,GAAY,OAAA;;;;;;EAoBZ,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;;;;;EAQhE,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;EAAA,IA6BlE,QAAA,CAAA,GAAY,gBAAA;;;;;;MAcZ,KAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0CE,aAAA,CACJ,OAAA,UACA,OAAA,WAAkB,UAAA,GAAa,WAAA,EAC/B,IAAA,EAAM,OAAA,GACL,OAAA;IAAU,GAAA;IAAa,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;EAuIpB,eAAA,CAAgB,OAAA,WAAkB,OAAA;IACtC,GAAA;IACA,KAAA;IACA,QAAA;EAAA;;;;;;;;;;;;;;;;;;;;;EAwCI,UAAA,CAAW,OAAA,UAAiB,QAAA,WAAmB,OAAA;;;;;;;;;;;;;;;;;;EA6B/C,cAAA,CAAe,OAAA,UAAiB,IAAA,EAAM,OAAA,GAAU,OAAA;IAAU,OAAA;EAAA;;;;;EAgDhE,KAAA,CAAA;AAAA"}

package/dist/cloudflare.d.mts

@@ -0,0 +1,308 @@
+import { ObjectStore } from "./providers/platform/r2/dist/types.mjs";
+import "./providers/platform/r2/dist/index.mjs";
+import { D1GCQueue } from "./d1-gc-queue.mjs";
+import { DIDSpaceLike as DIDSpaceLike$1, InstanceSpaceOptions } from "./did-space-like.mjs";
+import { PresignSigner } from "./presign-signer.mjs";
+import { DIDSpaceResolver } from "./resolve.mjs";
+import { PutOpts } from "./tree-index.mjs";
+import { ShareResolver } from "./share-resolve.mjs";
+import { normalizeId, validateId } from "./did-utils.mjs";
+import { AFS, AFSAccessMode } from "@aigne/afs";
+
+//#region src/cloudflare.d.ts
+interface CloudflareDIDSpaceOptions {
+  /** Owner DID of this space */
+  userDid: string;
+  /** Shared R2 object store (content-addressed, shared across all apps) */
+  objectStore: ObjectStore;
+  /** D1 database for tree index + resolve entries */
+  indexDb: D1Database;
+  /**
+   * Optional per-deployment HMAC secret for scope de-identification (README §4.4).
+   * When set, all D1 storage keys (`entries.scope` / `changelog.scope` /
+   * `shares.owner_did`) become `deriveScope(userDid, secret)` — an opaque HMAC —
+   * instead of the plaintext DID. When absent, scope stays plaintext (de-id off,
+   * back-compat). Injected along `objectStore` / `indexDb` by the resolver.
+   */
+  scopeHmacSecret?: Uint8Array;
+  /** Optional: ShareResolver for .share reconcile hook (Phase 0.4) */
+  shareResolver?: ShareResolver;
+  /**
+   * Route READ-serving D1 queries through a D1 Session
+   * (`withSession("first-unconstrained")`) so they can be served by the
+   * nearest read replica. Requires `read_replication: { mode: "auto" }` on the
+   * D1 database (a DB-level setting, NOT wrangler.toml) — otherwise every query
+   * stays on primary regardless of this flag.
+   *
+   * Only the read paths honor this (getInstanceSpace / getConfigSpace /
+   * getUserSpace / listApps / resolver). The write + GC paths (internalWrite /
+   * internalDelete / gcQueue) ALWAYS use the primary: they read the old entry to
+   * drive GC, and a stale replica read there would compute the wrong `oldCid`.
+   *
+   * Consistency note: each tree-index opens its own session with no bookmark
+   * threading, so this is "first-unconstrained" (potentially-stale) reads.
+   * Read-your-write holds WITHIN a single mounted AFS (same session) but NOT
+   * across requests. Default false (last-write-wins on primary, back-compat).
+   */
+  useReplica?: boolean;
+  /**
+   * Object-store presigned-PUT signer (DID Space upload plane, §15 decision 7).
+   * Injected by the CF runtime when R2 signer credentials are configured;
+   * `prepare-upload` (P2) mints exact-key checksum-pinned grants through it.
+   * Absent → no grant capability (clients fall back to batchWrite). Node never
+   * injects one (decision 8, fallback-only).
+   */
+  signer?: PresignSigner;
+  /**
+   * upload-limits Phase 5 per-scope byte quota (bytes). 0 / unset = OFF (the
+   * opt-in default). Injected by the CF runtime from `resolveUploadLimits`'s
+   * `maxBytesPerScope`; enforced on every write through this space's tree index.
+   */
+  maxBytesPerScope?: number;
+}
+declare class CloudflareDIDSpace implements DIDSpaceLike$1 {
+  /** Real normalizeId(DID) — identity, returned to callers (NOT a storage key). */
+  private readonly 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).
+   */
+  private readonly _scope;
+  private readonly objectStore;
+  private readonly indexDb;
+  private _resolver?;
+  /** Optional ShareResolver for .share reconcile hook (Phase 0.4) */
+  private readonly shareResolver?;
+  /** Read replica opt-in for read-serving paths only — see options doc. */
+  private readonly useReplica;
+  /** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */
+  private readonly 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`.
+   */
+  private readonly instanceSpaces;
+  /**
+   * 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.
+   */
+  private readonly userSpaces;
+  /** Shared GC queue instance — created once per CloudflareDIDSpace instance */
+  readonly gcQueue: D1GCQueue;
+  /** Injected presigned-PUT signer (upload plane). Undefined → no grant capability. */
+  private readonly signer?;
+  constructor(options: CloudflareDIDSpaceOptions);
+  /**
+   * 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.
+   */
+  private makeTreeIndex;
+  /**
+   * 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(): PresignSigner | undefined;
+  /**
+   * 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.
+   */
+  private uploadDeps;
+  /**
+   * 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.
+   */
+  getInstanceSpace(opts: InstanceSpaceOptions): Promise<AFS>;
+  /**
+   * Runtime-internal config fragment (`blocklets/<i>/config/`, mounted at
+   * `/`). Mirrors local `getConfigSpace`. Invisible to `/instance`; holds
+   * per-instance machine state like `mounts.toml`.
+   */
+  getConfigSpace(instanceDid: string): Promise<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.
+   */
+  listApps(): Promise<string[]>;
+  /**
+   * 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.
+   */
+  getSpaceRoot(options?: {
+    accessMode?: AFSAccessMode;
+  }): Promise<AFS>;
+  /**
+   * Get an AFS instance scoped to the user's entire DID Space.
+   * No appDid sub-partitioning.
+   */
+  getUserSpace(options?: {
+    accessMode?: AFSAccessMode;
+  }): Promise<AFS>;
+  get resolver(): DIDSpaceResolver;
+  /**
+   * 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(): string;
+  /**
+   * 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.
+   */
+  internalWrite(afsPath: string, content: string | Uint8Array | ArrayBuffer, opts: PutOpts): Promise<{
+    cid: string;
+    oldCid?: string;
+  }>;
+  /**
+   * 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.
+   */
+  getCurrentEntry(afsPath: string): Promise<{
+    cid: string;
+    mtime: number;
+    deviceId: string | null;
+  } | null>;
+  /**
+   * 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).
+   */
+  getLastSeq(afsPath: string, deviceId: string): Promise<number>;
+  /**
+   * 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.
+   */
+  internalDelete(afsPath: string, opts: PutOpts): Promise<{
+    deleted: boolean;
+  }>;
+  /**
+   * Clean up resources. Drops the cached instance-space map so retained AFS
+   * instances are GC-eligible alongside this DID-Space.
+   */
+  close(): void;
+}
+//#endregion
+export { CloudflareDIDSpace, CloudflareDIDSpaceOptions, type InstanceSpaceOptions, normalizeId, validateId };
+//# sourceMappingURL=cloudflare.d.mts.map

package/dist/cloudflare.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.d.mts","names":[],"sources":["../src/cloudflare.ts"],"mappings":";;;;;;;;;;;;UA2CiB,yBAAA;EAIf;EAFA,OAAA;EAIA;EAFA,WAAA,EAAa,WAAA;EAUb;EARA,OAAA,EAAS,UAAA;EAUT;;;;;;;EAFA,eAAA,GAAkB,UAAA;EAuCP;EArCX,aAAA,GAAgB,aAAA;;;;;;;;;;;;;;;;;;EAkBhB,UAAA;EAyZiC;;;;;;;EAjZjC,MAAA,GAAS,aAAA;EAW4C;;;;;EALrD,gBAAA;AAAA;AAAA,cAKW,kBAAA,YAA8B,cAAA;EAexB;EAAA,iBAbA,OAAA;EA4BA;;;;;EAAA,iBAtBA,MAAA;EAAA,iBACA,WAAA;EAAA,iBACA,OAAA;EAAA,QACT,SAAA;EAqFJ;EAAA,iBAnFa,aAAA;EA6FT;EAAA,iBA3FS,UAAA;EAyHY;EAAA,iBAvHZ,gBAAA;EAuHmC;;;;;;;;;;;;EAAA,iBA1GnC,cAAA;EAyQqD;;;;;;;;;EAAA,iBA/PrD,UAAA;EA4VX;EAAA,SA1VG,OAAA,EAAS,SAAA;EA4VE;EAAA,iBA1VH,MAAA;cAEL,OAAA,EAAS,yBAAA;EAyVb;;;;;EAAA,QApTA,aAAA;EA4bc;;;;;;EAAA,IA/alB,aAAA,CAAA,GAAiB,aAAA;EA0da;;;;;;EAAA,QAhd1B,UAAA;EA6ewD;;;;;;;;;;;;;;;;;;;;;;EA/c1D,gBAAA,CAAiB,IAAA,EAAM,oBAAA,GAAuB,OAAA,CAAQ,GAAA;;;;;;EAiHtD,cAAA,CAAe,WAAA,WAAsB,OAAA,CAAQ,GAAA;;;;;;;;;;EA0B7C,QAAA,CAAA,GAAY,OAAA;;;;;;EAoBZ,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;;;;;EAQhE,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;EAAA,IA6BlE,QAAA,CAAA,GAAY,gBAAA;;;;;;MAcZ,KAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0CE,aAAA,CACJ,OAAA,UACA,OAAA,WAAkB,UAAA,GAAa,WAAA,EAC/B,IAAA,EAAM,OAAA,GACL,OAAA;IAAU,GAAA;IAAa,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;EAuIpB,eAAA,CAAgB,OAAA,WAAkB,OAAA;IACtC,GAAA;IACA,KAAA;IACA,QAAA;EAAA;;;;;;;;;;;;;;;;;;;;;EAwCI,UAAA,CAAW,OAAA,UAAiB,QAAA,WAAmB,OAAA;;;;;;;;;;;;;;;;;;EA6B/C,cAAA,CAAe,OAAA,UAAiB,IAAA,EAAM,OAAA,GAAU,OAAA;IAAU,OAAA;EAAA;;;;;EAgDhE,KAAA,CAAA;AAAA"}