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

package/dist/local.cjs

@@ -0,0 +1,435 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_did_utils = require('./did-utils.cjs');
+const require_upload_session_store = require('./upload-session-store.cjs');
+const require_afs_metadata_context = require('./afs-metadata-context.cjs');
+const require_cid_byte_cache = require('./cid-byte-cache.cjs');
+const require_prefixed_tree_index = require('./prefixed-tree-index.cjs');
+const require_reference_check = require('./reference-check.cjs');
+const require_resolve = require('./resolve.cjs');
+const require_run_gc = require('./run-gc.cjs');
+const require_scope_id = require('./scope-id.cjs');
+const require_sqlite_gc_queue = require('./sqlite-gc-queue.cjs');
+const require_sqlite_resolve_store = require('./sqlite-resolve-store.cjs');
+const require_sqlite_tree_index = require('./sqlite-tree-index.cjs');
+const require_index = require('./index.cjs');
+const require_fs_object_store = require('./fs-object-store.cjs');
+const require_metadata_db = require('./metadata-db.cjs');
+const require_reconcile = require('./reconcile.cjs');
+const require_scope_migration_node = require('./scope-migration-node.cjs');
+let _aigne_afs = require("@aigne/afs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let _aigne_afs_fs = require("@aigne/afs-fs");
+
+//#region src/local.ts
+/**
+* DIDSpace — local (Node) backend for DID-scoped storage.
+*
+* Phase 3 (mobile-didspace-transport): unified onto the single
+* `DIDSpaceProvider`, exactly like the Cloudflare backend — only the injected
+* storage primitives differ (Node: `FsObjectStore` + `SQLiteTreeIndex`; CF: R2
+* + `D1TreeIndex`). This makes the backend runtime-agnostic per CLAUDE.md and
+* gives Node the content-addressed `.objects/{cid}`, `.changelog`, `maxDepth:-1`
+* manifest, device-aware writes, and ifMatch that the bare `AFSFS` mount lacked.
+*
+* Layout (relative to `userDir`, all under `entries.scope = <storage scope>` —
+* the derived scope when de-id is on, else the plaintext DID; `userDir` itself
+* is `{rootPath}/{storage scope}`):
+*   role:"system" → PrefixedTreeIndex `blocklets/{i}/system/`   (mounted at `/`)
+*   role:"user"   → PrefixedTreeIndex `blocklets/{i}/user/`     (mounted at `/`)
+*   space root    → no-prefix SQLiteTreeIndex (whole space; CLI manifest)
+*   config        → AFSFS `blocklets/{i}/config/`               (blob fragment)
+* Content blobs live once at `{userDir}/objects/{cid}` (FsObjectStore); the
+* index (`_metadata.db`) is the source of truth. The old eventual-mirror
+* subscriber + `desktop:default` deviceId hardcode are gone — the provider's
+* `put` writes entries + changelog atomically.
+*
+* Usage:
+*   const space = new DIDSpace({ rootPath: "~/.afs/spaces", userDid: "did:abt:z1..." });
+*   const afs = await space.getInstanceSpace({ instanceDid: "z1app", role: "system" });
+*   await afs.write("/hello.txt", { content: "hello" });
+*/
+/** Local desktop device label written into changelog rows for local writes. */
+const LOCAL_DEVICE_ID = "desktop:default";
+var DIDSpace = class DIDSpace {
+	rootPath;
+	/** 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`. Drives the directory name (`userDir`), every
+	* SQLiteTreeIndex scope, and `_shares.db` owner_did. Named `_scope` to mirror
+	* the CF backend (cloudflare.ts).
+	*/
+	_scope;
+	userDir;
+	instanceSpaces = /* @__PURE__ */ new Map();
+	_resolver;
+	/** Backing store for {@link resolver}; closed in {@link close}. */
+	_resolveStore;
+	/** User-level MetadataDB; lazy-opened on first getInstanceSpace/getUserSpace */
+	metadataDb = null;
+	/** Shared content-addressed object store (one objects/ dir per user space). */
+	objectStore = null;
+	/**
+	* `objectStore` wrapped with a content-addressed byte cache (#674 perf). Keyed
+	* by cid (immutable) → no staleness, no TTL; bounded LRU keeps memory flat.
+	* Persists for this DID-Space's lifetime (the Node daemon reuses it per user).
+	*/
+	cachingStore = null;
+	objectByteCache = new require_cid_byte_cache.CidByteCache();
+	/** GC queue over `_metadata.db` (deferred object cleanup); lazy, ensureTable once. */
+	gcQueue = null;
+	/**
+	* Share-out Phase 3: builds the ShareResolver for getUserSpace providers.
+	* Read lazily at provider-construction time, so a late {@link
+	* setShareResolverFactory} (installer space) still covers providers built
+	* after the call. Undefined → no share-out (back-compat: dark-wired off).
+	*/
+	_shareResolverFactory;
+	/** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */
+	maxBytesPerScope;
+	constructor(options) {
+		require_did_utils.validateId(options.userDid);
+		this.rootPath = options.rootPath;
+		this.maxBytesPerScope = options.maxBytesPerScope ?? 0;
+		this.userDid = require_did_utils.normalizeId(options.userDid);
+		this._scope = options.scopeHmacSecret ? require_scope_id.deriveScope(this.userDid, options.scopeHmacSecret) : this.userDid;
+		this.userDir = (0, node_path.join)(this.rootPath, this._scope);
+		this._shareResolverFactory = options.shareResolverFactory;
+	}
+	/**
+	* Storage scope — mirrors `CloudflareDIDSpace.scope` (cloudflare.ts:443).
+	* De-id on → derived HMAC hash; de-id off → plaintext `userDid`.
+	* Used by consumers (e.g. the Node daemon `/user/index` mount) that need
+	* the same de-identified partition key used for physical storage.
+	*/
+	get scope() {
+		return this._scope;
+	}
+	/**
+	* Construct a SQLiteTreeIndex for this scope with the per-scope byte quota
+	* (upload-limits Phase 5) always injected — so every write path enforces it
+	* without each call site threading it. 0 = quota off (the opt-in default).
+	*/
+	sqliteTreeIndex(metadataDb, opts) {
+		return new require_sqlite_tree_index.SQLiteTreeIndex(metadataDb, this._scope, {
+			...opts,
+			maxBytesPerScope: this.maxBytesPerScope
+		});
+	}
+	/**
+	* Open a space DIRECTLY by its storage scope, WITHOUT deriving (README §5.6
+	* `/spaces` naming contract). For `/spaces/{X}` inspection where `X` is already
+	* the storage scope (a base32 hash under de-id, or a plaintext DID otherwise):
+	* the directory `{rootPath}/{storageScope}` is opened verbatim, `did` returns
+	* the opaque `storageScope`, and NO `deriveScope` runs (re-deriving would point
+	* at a non-existent `{rootPath}/{derive(storageScope)}`). Constructing with no
+	* secret guarantees `_scope === storageScope`. Callers mount it readonly.
+	*/
+	static openStorageScope(opts) {
+		return new DIDSpace({
+			rootPath: opts.rootPath,
+			userDid: opts.storageScope
+		});
+	}
+	/**
+	* Late-inject the share-resolver factory (share-out Phase 3). Used for the
+	* installer space, which `resolveLocalDIDSpace()` builds BEFORE the
+	* daemon-global share store exists. Lazy provider construction means this
+	* covers every getUserSpace provider built after the call.
+	*/
+	setShareResolverFactory(factory) {
+		this._shareResolverFactory = factory;
+	}
+	/** Expose constructor options for daemon integration (rootPath, userDid). */
+	get config() {
+		return {
+			rootPath: this.rootPath,
+			userDid: this.userDid
+		};
+	}
+	/**
+	* Lazily open (or reuse) the user-level `_metadata.db`.
+	* Creates `userDir` if missing. Only one instance per DIDSpace.
+	*/
+	async getMetadataDb() {
+		if (this.metadataDb) return this.metadataDb;
+		(0, node_fs.mkdirSync)(this.userDir, { recursive: true });
+		this.metadataDb = await require_metadata_db.MetadataDB.open(this.userDir);
+		return this.metadataDb;
+	}
+	/**
+	* Upload-plane deps for the user-facing provider (design §7 / §15 decision 8).
+	* Node is FALLBACK-ONLY: it implements the actions + SQLite session table
+	* (protocol parity) but injects NO signer, so `prepare-upload` returns
+	* `grant: null` and the native client falls back to batchWrite.
+	*/
+	uploadDeps(metadataDb) {
+		return {
+			uploadSessionStore: new require_upload_session_store.SqliteUploadSessionStore(metadataDb.rawClient),
+			uploadScope: this._scope
+		};
+	}
+	/**
+	* Lazily create the shared FsObjectStore rooted at `{userDir}/objects`, wrapped
+	* with the content-addressed byte cache. Returns the caching wrapper so every
+	* provider read benefits; the raw {@link objectStore} field is kept only so
+	* {@link close} can drop it.
+	*/
+	getObjectStore() {
+		if (!this.cachingStore) {
+			(0, node_fs.mkdirSync)(this.userDir, { recursive: true });
+			this.objectStore = new require_fs_object_store.FsObjectStore(this.userDir);
+			this.cachingStore = new require_cid_byte_cache.CachingObjectStore(this.objectStore, this.objectByteCache);
+		}
+		return this.cachingStore;
+	}
+	/**
+	* Lazily create the `SqliteGcQueue` over the user-level `_metadata.db`
+	* (via the `MetadataDB.rawClient` getter — never reaches into private fields).
+	* One queue per DIDSpace; injected into every DIDSpaceProvider so overwrites/
+	* deletes enqueue the orphaned oldCid for the deferred sweep.
+	*/
+	async getGcQueue() {
+		if (!this.gcQueue) {
+			const queue = new require_sqlite_gc_queue.SqliteGcQueue((await this.getMetadataDb()).rawClient);
+			await queue.ensureTable();
+			this.gcQueue = queue;
+		}
+		return this.gcQueue;
+	}
+	/**
+	* Run one object-GC sweep over this space's single owner scope (design §4.6).
+	* Scope-agnostic: `referencedAnywhere` is scope-blind over the one
+	* `_metadata.db`, so one sweep covers the whole daemon. Used by both the
+	* `arc space gc` CLI and the daemon's scheduled GC task (AFSScheduler, #742 S3).
+	*/
+	async runGc(opts) {
+		const metadataDb = await this.getMetadataDb();
+		const stats = await require_run_gc.runGc({
+			queue: await this.getGcQueue(),
+			referencedAnywhere: (cid, nowMs) => require_reference_check.referencedAnywhereLibsql(metadataDb.rawClient, cid, nowMs),
+			objectStore: this.getObjectStore(),
+			graceMs: opts?.graceMs,
+			limit: opts?.limit,
+			log: opts?.log
+		});
+		await new require_upload_session_store.SqliteUploadSessionStore(metadataDb.rawClient).sweepExpired(Date.now());
+		return stats;
+	}
+	/**
+	* Back-compat no-op: the eventual-mirror subscriber is gone (the provider now
+	* writes entries + changelog atomically), so there is no in-flight work to
+	* drain. Kept so existing test/daemon call sites don't break.
+	*/
+	async drainSubscribers() {}
+	/**
+	* Get an isolated AFS instance for a blocklet instance under this DID Space,
+	* scoped by role (system = installer-side data, user = caller-side data).
+	*
+	* Mounts a single `DIDSpaceProvider` whose treeIndex is a `PrefixedTreeIndex`
+	* over the user-scoped `SQLiteTreeIndex` at `blocklets/{i}/{role}/`. The
+	* prefix is MANDATORY — without it the role root would degrade to the whole
+	* space root (data越界). Blobs share the user-level `FsObjectStore`.
+	*
+	* `userDid` is @deprecated for role:"user" — per-user isolation comes from
+	* WHICH space backs the call (the space is already the caller's), so it never
+	* enters the path; validated only as defense if supplied.
+	*/
+	async getInstanceSpace(opts) {
+		require_did_utils.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) require_did_utils.validateId(opts.userDid);
+		const bareInstanceId = require_did_utils.normalizeId(opts.instanceDid);
+		const cacheKey = opts.role === "system" ? `system:${bareInstanceId}` : `user:${bareInstanceId}`;
+		const existing = this.instanceSpaces.get(cacheKey);
+		if (existing) return existing;
+		const prefix = `blocklets/${bareInstanceId}/${opts.role}/`;
+		const accessMode = opts.accessMode ?? "readwrite";
+		const metadataDb = await this.getMetadataDb();
+		const treeIndex = new require_prefixed_tree_index.PrefixedTreeIndex(this.sqliteTreeIndex(metadataDb, { inlineCache: "on" }), prefix);
+		const gcQueue = await this.getGcQueue();
+		const shareResolver = opts.role === "user" ? this._shareResolverFactory?.(this.sqliteTreeIndex(metadataDb, { inlineCache: "on" })) : void 0;
+		const afs = new _aigne_afs.AFS();
+		await afs.mount(new require_index.DIDSpaceProvider({
+			did: bareInstanceId,
+			objectStore: this.getObjectStore(),
+			treeIndex,
+			name: "content",
+			accessMode,
+			deviceId: LOCAL_DEVICE_ID,
+			gcQueue,
+			...opts.role === "user" ? {
+				shareTreePrefix: prefix,
+				...shareResolver ? {
+					shareResolver,
+					shareOwnerDid: this._scope
+				} : {},
+				blockletResolver: this.resolver,
+				blockletOwnerDid: this.userDid
+			} : {},
+			...opts.role === "user" ? this.uploadDeps(metadataDb) : {}
+		}), "/");
+		this.instanceSpaces.set(cacheKey, afs);
+		return afs;
+	}
+	/**
+	* Source-side dirty queue for an instance's `/user` fragment
+	* (index-follower-dirty-path §7, §9.2). Returns a `PrefixedTreeIndex` over the
+	* user-level `_metadata.db` (where `ds_changelog` + `ds_dirty_path` live), so
+	* the daemon can drain the merged dirty projection instead of replaying
+	* `/.changelog`. This is a RUNTIME-INTERNAL capability held directly by the
+	* daemon's follower — it is NEVER exposed as a public `/user` AFS action
+	* (ack/fail mutate scheduling state). Node has no D1 replica, so a single
+	* primary `_metadata.db` read is already read-your-write. The index writes stay
+	* in the separate `user-index.db`; only source/dirty rows are read here.
+	*/
+	async getInstanceDirtyQueue(opts) {
+		require_did_utils.validateId(opts.instanceDid);
+		const prefix = `blocklets/${require_did_utils.normalizeId(opts.instanceDid)}/${opts.role}/`;
+		const metadataDb = await this.getMetadataDb();
+		return new require_prefixed_tree_index.PrefixedTreeIndex(this.sqliteTreeIndex(metadataDb), prefix);
+	}
+	/**
+	* Config fragment for an instance — a sibling of the role content tree at
+	* `blocklets/<i>/config/`, mounted at `/`. Runtime-internal (mount overrides
+	* etc.); NOT part of `/instance`. Stays a plain `AFSFS` blob fragment: config
+	* is opaque machine state, not content-addressed sync data (design §2.F/T3.9).
+	*/
+	async getConfigSpace(instanceDid) {
+		require_did_utils.validateId(instanceDid);
+		const bareInstanceId = require_did_utils.normalizeId(instanceDid);
+		const configDir = (0, node_path.join)(this.userDir, "blocklets", bareInstanceId, "config");
+		(0, node_fs.mkdirSync)(configDir, { recursive: true });
+		const afs = new _aigne_afs.AFS();
+		await afs.mount(new _aigne_afs_fs.AFSFS({
+			localPath: configDir,
+			name: "config",
+			accessMode: "readwrite"
+		}), "/");
+		return afs;
+	}
+	/**
+	* List all instance DIDs that have storage in this user's DID space.
+	*
+	* Enumerated from the index (the source of truth) rather than `readdir` of
+	* the physical tree — the physical layout is now `objects/{cid}` + index, so
+	* there is no per-instance directory to walk. Direct children of the
+	* `blocklets/` prefix are the instance ids (trailing-slash dir rows).
+	*/
+	async listApps() {
+		const metadataDb = await this.getMetadataDb();
+		const result = await this.sqliteTreeIndex(metadataDb).listChildren("blocklets/");
+		const ids = /* @__PURE__ */ new Set();
+		for (const entry of result.entries) {
+			const rel = entry.path.slice(10).replace(/\/$/, "");
+			if (rel) ids.add(rel);
+		}
+		return [...ids];
+	}
+	/**
+	* Resolve table — persistent + DAEMON-GLOBAL (`{rootPath}/_resolve.db`, NOT
+	* the per-space `_metadata.db`): `blocklet/<id> → owner` / `domain/<host> → …`
+	* are caller-less reverse lookups that need ONE shared registry, exactly like
+	* `_shares.db` and CF's single shared D1. Backed by `SqliteResolveStore` so
+	* entries survive across DID-Space instances and daemon restarts — symmetric
+	* with `CloudflareDIDSpace.resolver` (D1ResolveStore). Closed in {@link close}.
+	*/
+	get resolver() {
+		if (!this._resolver) {
+			this._resolveStore = new require_sqlite_resolve_store.SqliteResolveStore((0, node_path.join)(this.rootPath, "_resolve.db"));
+			this._resolver = new require_resolve.DIDSpaceResolver(this._resolveStore);
+		}
+		return this._resolver;
+	}
+	/**
+	* Whole-space root (contract alias `getSpaceRoot`; legacy name `getUserSpace`)
+	* — a `DIDSpaceProvider` over the NO-PREFIX user-scoped `SQLiteTreeIndex`, so
+	* it sees every instance fragment in the space. Used by `arc space`
+	* export/import/diff (CLI manifest source) and observability. Mobile sync does
+	* NOT use it (mobile goes through the aside `/user` fragment).
+	*/
+	async getSpaceRoot(options) {
+		return this.getUserSpace(options);
+	}
+	async getUserSpace(options) {
+		const metadataDb = await this.getMetadataDb();
+		const gcQueue = await this.getGcQueue();
+		const afs = new _aigne_afs.AFS();
+		const scopeTreeIndex = this.sqliteTreeIndex(metadataDb, { inlineCache: "on" });
+		await afs.mount(new require_index.DIDSpaceProvider({
+			did: this.userDid,
+			objectStore: this.getObjectStore(),
+			treeIndex: scopeTreeIndex,
+			name: "did-space-user",
+			accessMode: options?.accessMode ?? "readonly",
+			deviceId: LOCAL_DEVICE_ID,
+			gcQueue,
+			shareResolver: this._shareResolverFactory?.(scopeTreeIndex),
+			blockletResolver: this.resolver,
+			blockletOwnerDid: this.userDid,
+			...this.uploadDeps(metadataDb)
+		}), "/");
+		require_afs_metadata_context.attachMetadataContext(afs, {
+			metadataDb,
+			userDir: this.userDir,
+			scope: this._scope
+		});
+		return afs;
+	}
+	/**
+	* Share-out Phase 4: a READONLY AFS for public `/s/{slug}` serving, scoped by
+	* `prefix` (with trailing slash, e.g. `docs/`) or — when undefined — the whole
+	* owner tree (root share + sidecar). Reuses THIS space's metadataDb +
+	* objectStore (no second libsql client on `_metadata.db`, which would race).
+	* No shareResolver injected: serving is read-only, never reconciles.
+	*/
+	async getShareServeAFS(prefix) {
+		const metadataDb = await this.getMetadataDb();
+		const base = this.sqliteTreeIndex(metadataDb, { inlineCache: "on" });
+		const treeIndex = prefix ? new require_prefixed_tree_index.PrefixedTreeIndex(base, prefix) : base;
+		const afs = new _aigne_afs.AFS();
+		await afs.mount(new require_index.DIDSpaceProvider({
+			did: this.userDid,
+			objectStore: this.getObjectStore(),
+			treeIndex,
+			name: "did-space-share-serve",
+			accessMode: "readonly",
+			deviceId: LOCAL_DEVICE_ID
+		}), "/");
+		return afs;
+	}
+	/**
+	* Clean up resources. Closes the user-level MetadataDB and clears the
+	* instance-space cache. No event subscriptions to tear down anymore.
+	*/
+	close() {
+		if (this.metadataDb) {
+			try {
+				this.metadataDb.close();
+			} catch {}
+			this.metadataDb = null;
+		}
+		if (this._resolveStore) {
+			this._resolveStore.close();
+			this._resolveStore = void 0;
+			this._resolver = void 0;
+		}
+		this.gcQueue = null;
+		this.objectStore = null;
+		this.cachingStore = null;
+		this.instanceSpaces.clear();
+	}
+};
+
+//#endregion
+exports.DIDSpace = DIDSpace;
+exports.FsObjectStore = require_fs_object_store.FsObjectStore;
+exports.MetadataDB = require_metadata_db.MetadataDB;
+exports.SQLiteTreeIndex = require_sqlite_tree_index.SQLiteTreeIndex;
+exports.migrateNodeMetadataDb = require_scope_migration_node.migrateNodeMetadataDb;
+exports.migrateNodeSpaces = require_scope_migration_node.migrateNodeSpaces;
+exports.normalizeId = require_did_utils.normalizeId;
+exports.reconcile = require_reconcile.reconcile;
+exports.validateId = require_did_utils.validateId;

package/dist/local.d.cts

@@ -0,0 +1,254 @@
+import { DIDSpaceLike as DIDSpaceLike$1, InstanceSpaceOptions } from "./did-space-like.cjs";
+import { DIDSpaceResolver } from "./resolve.cjs";
+import { TreeIndex } from "./tree-index.cjs";
+import { ShareResolver } from "./share-resolve.cjs";
+import { normalizeId, validateId } from "./did-utils.cjs";
+import { CidCacheRow, EntryRow, MetadataDB } from "./metadata-db.cjs";
+import { PrefixedTreeIndex } from "./prefixed-tree-index.cjs";
+import { GcStats } from "./run-gc.cjs";
+import { FsObjectStore } from "./fs-object-store.cjs";
+import { ReconcileOptions, ReconcileStats, reconcile } from "./reconcile.cjs";
+import { NodeScopeMigrationOptions, NodeScopeMigrationReport, migrateNodeMetadataDb, migrateNodeSpaces } from "./scope-migration-node.cjs";
+import { SQLiteTreeIndex } from "./sqlite-tree-index.cjs";
+import { AFS, AFSAccessMode } from "@aigne/afs";
+
+//#region src/local.d.ts
+/**
+ * Builds a {@link ShareResolver} for a user/owner space (share-out Phase 3).
+ * The daemon-global share store is captured in the factory's closure (one
+ * `_shares.db` across all owners); `scopeTreeIndex` is the per-space tree index
+ * (WHOLE user tree, no prefix) the resolver uses for sidecar/.web pre-io checks.
+ * Injected into `getUserSpace` (whole-space) AND `getInstanceSpace(role:"user")`
+ * (the caller's own per-user blocklet fragment — `/user` mount + mobile-sync
+ * target); the fragment provider remaps owner→userDid + restores the full decl
+ * path. role:"system" instance spaces are NEVER shared (installer data).
+ */
+type ShareResolverFactory = (scopeTreeIndex: TreeIndex) => ShareResolver;
+interface DIDSpaceOptions {
+  /** Root directory for all DID spaces (e.g., ~/.afs/spaces) */
+  rootPath: string;
+  /** Owner DID of this space */
+  userDid: string;
+  /**
+   * Per-deployment HMAC secret for scope de-identification (README §5.3). When
+   * set, the storage scope — the directory name `{rootPath}/{scope}`, the
+   * `_metadata.db` scope columns, and the `_shares.db` owner_did — becomes
+   * `deriveScope(userDid, secret)`. When absent, scope stays the plaintext DID
+   * (de-id off, back-compat). Each deployment has its own secret (§5.5).
+   */
+  scopeHmacSecret?: Uint8Array;
+  /**
+   * Share-out Phase 3: optional factory that builds a ShareResolver for this
+   * space's `getUserSpace` provider (closure over the daemon-global share
+   * store). Can also be late-injected via {@link DIDSpace.setShareResolverFactory}
+   * for spaces constructed before the store exists (installer space).
+   */
+  shareResolverFactory?: ShareResolverFactory;
+  /**
+   * upload-limits Phase 5 per-scope byte quota (bytes). 0 / unset = OFF (the
+   * opt-in default). Threaded into every SQLiteTreeIndex this space builds.
+   * The Node daemon resolves it from `resolveUploadLimits(process.env)`.
+   */
+  maxBytesPerScope?: number;
+}
+declare class DIDSpace implements DIDSpaceLike$1 {
+  private readonly rootPath;
+  /** 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`. Drives the directory name (`userDir`), every
+   * SQLiteTreeIndex scope, and `_shares.db` owner_did. Named `_scope` to mirror
+   * the CF backend (cloudflare.ts).
+   */
+  private readonly _scope;
+  readonly userDir: string;
+  private readonly instanceSpaces;
+  private _resolver?;
+  /** Backing store for {@link resolver}; closed in {@link close}. */
+  private _resolveStore?;
+  /** User-level MetadataDB; lazy-opened on first getInstanceSpace/getUserSpace */
+  private metadataDb;
+  /** Shared content-addressed object store (one objects/ dir per user space). */
+  private objectStore;
+  /**
+   * `objectStore` wrapped with a content-addressed byte cache (#674 perf). Keyed
+   * by cid (immutable) → no staleness, no TTL; bounded LRU keeps memory flat.
+   * Persists for this DID-Space's lifetime (the Node daemon reuses it per user).
+   */
+  private cachingStore;
+  private readonly objectByteCache;
+  /** GC queue over `_metadata.db` (deferred object cleanup); lazy, ensureTable once. */
+  private gcQueue;
+  /**
+   * Share-out Phase 3: builds the ShareResolver for getUserSpace providers.
+   * Read lazily at provider-construction time, so a late {@link
+   * setShareResolverFactory} (installer space) still covers providers built
+   * after the call. Undefined → no share-out (back-compat: dark-wired off).
+   */
+  private _shareResolverFactory?;
+  /** upload-limits Phase 5 per-scope byte quota (0 = off, the opt-in default). */
+  private readonly maxBytesPerScope;
+  constructor(options: DIDSpaceOptions);
+  /**
+   * Storage scope — mirrors `CloudflareDIDSpace.scope` (cloudflare.ts:443).
+   * De-id on → derived HMAC hash; de-id off → plaintext `userDid`.
+   * Used by consumers (e.g. the Node daemon `/user/index` mount) that need
+   * the same de-identified partition key used for physical storage.
+   */
+  get scope(): string;
+  /**
+   * Construct a SQLiteTreeIndex for this scope with the per-scope byte quota
+   * (upload-limits Phase 5) always injected — so every write path enforces it
+   * without each call site threading it. 0 = quota off (the opt-in default).
+   */
+  private sqliteTreeIndex;
+  /**
+   * Open a space DIRECTLY by its storage scope, WITHOUT deriving (README §5.6
+   * `/spaces` naming contract). For `/spaces/{X}` inspection where `X` is already
+   * the storage scope (a base32 hash under de-id, or a plaintext DID otherwise):
+   * the directory `{rootPath}/{storageScope}` is opened verbatim, `did` returns
+   * the opaque `storageScope`, and NO `deriveScope` runs (re-deriving would point
+   * at a non-existent `{rootPath}/{derive(storageScope)}`). Constructing with no
+   * secret guarantees `_scope === storageScope`. Callers mount it readonly.
+   */
+  static openStorageScope(opts: {
+    rootPath: string;
+    storageScope: string;
+  }): DIDSpace;
+  /**
+   * Late-inject the share-resolver factory (share-out Phase 3). Used for the
+   * installer space, which `resolveLocalDIDSpace()` builds BEFORE the
+   * daemon-global share store exists. Lazy provider construction means this
+   * covers every getUserSpace provider built after the call.
+   */
+  setShareResolverFactory(factory: ShareResolverFactory): void;
+  /** Expose constructor options for daemon integration (rootPath, userDid). */
+  get config(): Readonly<DIDSpaceOptions>;
+  /**
+   * Lazily open (or reuse) the user-level `_metadata.db`.
+   * Creates `userDir` if missing. Only one instance per DIDSpace.
+   */
+  getMetadataDb(): Promise<MetadataDB>;
+  /**
+   * Upload-plane deps for the user-facing provider (design §7 / §15 decision 8).
+   * Node is FALLBACK-ONLY: it implements the actions + SQLite session table
+   * (protocol parity) but injects NO signer, so `prepare-upload` returns
+   * `grant: null` and the native client falls back to batchWrite.
+   */
+  private uploadDeps;
+  /**
+   * Lazily create the shared FsObjectStore rooted at `{userDir}/objects`, wrapped
+   * with the content-addressed byte cache. Returns the caching wrapper so every
+   * provider read benefits; the raw {@link objectStore} field is kept only so
+   * {@link close} can drop it.
+   */
+  private getObjectStore;
+  /**
+   * Lazily create the `SqliteGcQueue` over the user-level `_metadata.db`
+   * (via the `MetadataDB.rawClient` getter — never reaches into private fields).
+   * One queue per DIDSpace; injected into every DIDSpaceProvider so overwrites/
+   * deletes enqueue the orphaned oldCid for the deferred sweep.
+   */
+  private getGcQueue;
+  /**
+   * Run one object-GC sweep over this space's single owner scope (design §4.6).
+   * Scope-agnostic: `referencedAnywhere` is scope-blind over the one
+   * `_metadata.db`, so one sweep covers the whole daemon. Used by both the
+   * `arc space gc` CLI and the daemon's scheduled GC task (AFSScheduler, #742 S3).
+   */
+  runGc(opts?: {
+    graceMs?: number;
+    limit?: number;
+    log?: (line: string) => void;
+  }): Promise<GcStats>;
+  /**
+   * Back-compat no-op: the eventual-mirror subscriber is gone (the provider now
+   * writes entries + changelog atomically), so there is no in-flight work to
+   * drain. Kept so existing test/daemon call sites don't break.
+   */
+  drainSubscribers(): Promise<void>;
+  /**
+   * Get an isolated AFS instance for a blocklet instance under this DID Space,
+   * scoped by role (system = installer-side data, user = caller-side data).
+   *
+   * Mounts a single `DIDSpaceProvider` whose treeIndex is a `PrefixedTreeIndex`
+   * over the user-scoped `SQLiteTreeIndex` at `blocklets/{i}/{role}/`. The
+   * prefix is MANDATORY — without it the role root would degrade to the whole
+   * space root (data越界). Blobs share the user-level `FsObjectStore`.
+   *
+   * `userDid` is @deprecated for role:"user" — per-user isolation comes from
+   * WHICH space backs the call (the space is already the caller's), so it never
+   * enters the path; validated only as defense if supplied.
+   */
+  getInstanceSpace(opts: InstanceSpaceOptions): Promise<AFS>;
+  /**
+   * Source-side dirty queue for an instance's `/user` fragment
+   * (index-follower-dirty-path §7, §9.2). Returns a `PrefixedTreeIndex` over the
+   * user-level `_metadata.db` (where `ds_changelog` + `ds_dirty_path` live), so
+   * the daemon can drain the merged dirty projection instead of replaying
+   * `/.changelog`. This is a RUNTIME-INTERNAL capability held directly by the
+   * daemon's follower — it is NEVER exposed as a public `/user` AFS action
+   * (ack/fail mutate scheduling state). Node has no D1 replica, so a single
+   * primary `_metadata.db` read is already read-your-write. The index writes stay
+   * in the separate `user-index.db`; only source/dirty rows are read here.
+   */
+  getInstanceDirtyQueue(opts: {
+    instanceDid: string;
+    role: "user";
+  }): Promise<PrefixedTreeIndex>;
+  /**
+   * Config fragment for an instance — a sibling of the role content tree at
+   * `blocklets/<i>/config/`, mounted at `/`. Runtime-internal (mount overrides
+   * etc.); NOT part of `/instance`. Stays a plain `AFSFS` blob fragment: config
+   * is opaque machine state, not content-addressed sync data (design §2.F/T3.9).
+   */
+  getConfigSpace(instanceDid: string): Promise<AFS>;
+  /**
+   * List all instance DIDs that have storage in this user's DID space.
+   *
+   * Enumerated from the index (the source of truth) rather than `readdir` of
+   * the physical tree — the physical layout is now `objects/{cid}` + index, so
+   * there is no per-instance directory to walk. Direct children of the
+   * `blocklets/` prefix are the instance ids (trailing-slash dir rows).
+   */
+  listApps(): Promise<string[]>;
+  /**
+   * Resolve table — persistent + DAEMON-GLOBAL (`{rootPath}/_resolve.db`, NOT
+   * the per-space `_metadata.db`): `blocklet/<id> → owner` / `domain/<host> → …`
+   * are caller-less reverse lookups that need ONE shared registry, exactly like
+   * `_shares.db` and CF's single shared D1. Backed by `SqliteResolveStore` so
+   * entries survive across DID-Space instances and daemon restarts — symmetric
+   * with `CloudflareDIDSpace.resolver` (D1ResolveStore). Closed in {@link close}.
+   */
+  get resolver(): DIDSpaceResolver;
+  /**
+   * Whole-space root (contract alias `getSpaceRoot`; legacy name `getUserSpace`)
+   * — a `DIDSpaceProvider` over the NO-PREFIX user-scoped `SQLiteTreeIndex`, so
+   * it sees every instance fragment in the space. Used by `arc space`
+   * export/import/diff (CLI manifest source) and observability. Mobile sync does
+   * NOT use it (mobile goes through the aside `/user` fragment).
+   */
+  getSpaceRoot(options?: {
+    accessMode?: AFSAccessMode;
+  }): Promise<AFS>;
+  getUserSpace(options?: {
+    accessMode?: AFSAccessMode;
+  }): Promise<AFS>;
+  /**
+   * Share-out Phase 4: a READONLY AFS for public `/s/{slug}` serving, scoped by
+   * `prefix` (with trailing slash, e.g. `docs/`) or — when undefined — the whole
+   * owner tree (root share + sidecar). Reuses THIS space's metadataDb +
+   * objectStore (no second libsql client on `_metadata.db`, which would race).
+   * No shareResolver injected: serving is read-only, never reconciles.
+   */
+  getShareServeAFS(prefix?: string): Promise<AFS>;
+  /**
+   * Clean up resources. Closes the user-level MetadataDB and clears the
+   * instance-space cache. No event subscriptions to tear down anymore.
+   */
+  close(): void;
+}
+//#endregion
+export { type CidCacheRow, DIDSpace, DIDSpaceOptions, type EntryRow, FsObjectStore, type InstanceSpaceOptions, MetadataDB, type NodeScopeMigrationOptions, type NodeScopeMigrationReport, type ReconcileOptions, type ReconcileStats, SQLiteTreeIndex, ShareResolverFactory, migrateNodeMetadataDb, migrateNodeSpaces, normalizeId, reconcile, validateId };
+//# sourceMappingURL=local.d.cts.map