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

package/dist/local.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.cts","names":[],"sources":["../src/local.ts"],"mappings":";;;;;;;;;;;;;;;;;AAmHA;;;;;;;;KAnDY,oBAAA,IAAwB,cAAA,EAAgB,SAAA,KAAc,aAAA;AAAA,UAqBjD,eAAA;EAyVoC;EAvVnD,QAAA;EA4WkB;EA1WlB,OAAA;EA8Y4C;;;;;;;EAtY5C,eAAA,GAAkB,UAAA;EAkBa;;;;;;EAX/B,oBAAA,GAAuB,oBAAA;EAsBd;;;;;EAhBT,gBAAA;AAAA;AAAA,cAKW,QAAA,YAAoB,cAAA;EAAA,iBACd,QAAA;EAqCA;EAAA,iBAnCA,OAAA;EAqCI;;;;;;EAAA,iBA9BJ,MAAA;EAAA,SACR,OAAA;EAAA,iBACQ,cAAA;EAAA,QACT,SAAA;EAmFyB;EAAA,QAjFzB,aAAA;EAsFJ;EAAA,QAnFI,UAAA;EAmFe;EAAA,QAjFf,WAAA;EAyFe;;;;;EAAA,QAnFf,YAAA;EAAA,iBACS,eAAA;EA6If;EAAA,QA3IM,OAAA;EA4IC;;;;;;EAAA,QArID,qBAAA;EAgLqB;EAAA,iBA9KZ,gBAAA;cAEL,OAAA,EAAS,eAAA;EA4KuC;;;;;;EAAA,IAvJxD,KAAA,CAAA;EA8PE;;;;;EAAA,QArPE,eAAA;EA+RJ;;;;;;;;;EAAA,OA/QG,gBAAA,CAAiB,IAAA;IAAQ,QAAA;IAAkB,YAAA;EAAA,IAAyB,QAAA;EAkSL;;;;;;EAxRtE,uBAAA,CAAwB,OAAA,EAAS,oBAAA;EA+V5B;EAAA,IA1VD,MAAA,CAAA,GAAU,QAAA,CAAS,eAAA;;;;;EAQjB,aAAA,CAAA,GAAiB,OAAA,CAAQ,UAAA;;;;;;;UAavB,UAAA;;;;;;;UAaA,cAAA;;;;;;;UAeM,UAAA;;;;;;;EAgBR,KAAA,CAAM,IAAA;IACV,OAAA;IACA,KAAA;IACA,GAAA,IAAO,IAAA;EAAA,IACL,OAAA,CAAQ,OAAA;;;;;;EAyBN,gBAAA,CAAA,GAAoB,OAAA;;;;;;;;;;;;;;EAiBpB,gBAAA,CAAiB,IAAA,EAAM,oBAAA,GAAuB,OAAA,CAAQ,GAAA;;;;;;;;;;;;EAsFtD,qBAAA,CAAsB,IAAA;IAC1B,WAAA;IACA,IAAA;EAAA,IACE,OAAA,CAAQ,iBAAA;;;;;;;EAcN,cAAA,CAAe,WAAA,WAAsB,OAAA,CAAQ,GAAA;;;;;;;;;EAqB7C,QAAA,CAAA,GAAY,OAAA;;;;;;;;;MAqBd,QAAA,CAAA,GAAY,gBAAA;;;;;;;;EAeV,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;EAIhE,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;;;;;;;;EAgDhE,gBAAA,CAAiB,MAAA,YAAkB,OAAA,CAAQ,GAAA;;;;;EAuBjD,KAAA,CAAA;AAAA"}

package/dist/local.d.mts

@@ -0,0 +1,254 @@
+import { DIDSpaceLike as DIDSpaceLike$1, InstanceSpaceOptions } from "./did-space-like.mjs";
+import { DIDSpaceResolver } from "./resolve.mjs";
+import { TreeIndex } from "./tree-index.mjs";
+import { ShareResolver } from "./share-resolve.mjs";
+import { normalizeId, validateId } from "./did-utils.mjs";
+import { CidCacheRow, EntryRow, MetadataDB } from "./metadata-db.mjs";
+import { PrefixedTreeIndex } from "./prefixed-tree-index.mjs";
+import { GcStats } from "./run-gc.mjs";
+import { FsObjectStore } from "./fs-object-store.mjs";
+import { ReconcileOptions, ReconcileStats, reconcile } from "./reconcile.mjs";
+import { NodeScopeMigrationOptions, NodeScopeMigrationReport, migrateNodeMetadataDb, migrateNodeSpaces } from "./scope-migration-node.mjs";
+import { SQLiteTreeIndex } from "./sqlite-tree-index.mjs";
+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.mts.map

package/dist/local.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.mts","names":[],"sources":["../src/local.ts"],"mappings":";;;;;;;;;;;;;;;;;AAmHA;;;;;;;;KAnDY,oBAAA,IAAwB,cAAA,EAAgB,SAAA,KAAc,aAAA;AAAA,UAqBjD,eAAA;EAyVoC;EAvVnD,QAAA;EA4WkB;EA1WlB,OAAA;EA8Y4C;;;;;;;EAtY5C,eAAA,GAAkB,UAAA;EAkBa;;;;;;EAX/B,oBAAA,GAAuB,oBAAA;EAsBd;;;;;EAhBT,gBAAA;AAAA;AAAA,cAKW,QAAA,YAAoB,cAAA;EAAA,iBACd,QAAA;EAqCA;EAAA,iBAnCA,OAAA;EAqCI;;;;;;EAAA,iBA9BJ,MAAA;EAAA,SACR,OAAA;EAAA,iBACQ,cAAA;EAAA,QACT,SAAA;EAmFyB;EAAA,QAjFzB,aAAA;EAsFJ;EAAA,QAnFI,UAAA;EAmFe;EAAA,QAjFf,WAAA;EAyFe;;;;;EAAA,QAnFf,YAAA;EAAA,iBACS,eAAA;EA6If;EAAA,QA3IM,OAAA;EA4IC;;;;;;EAAA,QArID,qBAAA;EAgLqB;EAAA,iBA9KZ,gBAAA;cAEL,OAAA,EAAS,eAAA;EA4KuC;;;;;;EAAA,IAvJxD,KAAA,CAAA;EA8PE;;;;;EAAA,QArPE,eAAA;EA+RJ;;;;;;;;;EAAA,OA/QG,gBAAA,CAAiB,IAAA;IAAQ,QAAA;IAAkB,YAAA;EAAA,IAAyB,QAAA;EAkSL;;;;;;EAxRtE,uBAAA,CAAwB,OAAA,EAAS,oBAAA;EA+V5B;EAAA,IA1VD,MAAA,CAAA,GAAU,QAAA,CAAS,eAAA;;;;;EAQjB,aAAA,CAAA,GAAiB,OAAA,CAAQ,UAAA;;;;;;;UAavB,UAAA;;;;;;;UAaA,cAAA;;;;;;;UAeM,UAAA;;;;;;;EAgBR,KAAA,CAAM,IAAA;IACV,OAAA;IACA,KAAA;IACA,GAAA,IAAO,IAAA;EAAA,IACL,OAAA,CAAQ,OAAA;;;;;;EAyBN,gBAAA,CAAA,GAAoB,OAAA;;;;;;;;;;;;;;EAiBpB,gBAAA,CAAiB,IAAA,EAAM,oBAAA,GAAuB,OAAA,CAAQ,GAAA;;;;;;;;;;;;EAsFtD,qBAAA,CAAsB,IAAA;IAC1B,WAAA;IACA,IAAA;EAAA,IACE,OAAA,CAAQ,iBAAA;;;;;;;EAcN,cAAA,CAAe,WAAA,WAAsB,OAAA,CAAQ,GAAA;;;;;;;;;EAqB7C,QAAA,CAAA,GAAY,OAAA;;;;;;;;;MAqBd,QAAA,CAAA,GAAY,gBAAA;;;;;;;;EAeV,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;EAIhE,YAAA,CAAa,OAAA;IAAY,UAAA,GAAa,aAAA;EAAA,IAAkB,OAAA,CAAQ,GAAA;;;;;;;;EAgDhE,gBAAA,CAAiB,MAAA,YAAkB,OAAA,CAAQ,GAAA;;;;;EAuBjD,KAAA,CAAA;AAAA"}