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

package/dist/prefixed-tree-index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefixed-tree-index.mjs","names":["map"],"sources":["../src/prefixed-tree-index.ts"],"sourcesContent":["/**\n * PrefixedTreeIndex — wraps a TreeIndex, prepending a prefix to all paths.\n *\n * Used by CloudflareDIDSpace to store per-app data under a shared user scope:\n *   scope = \"z1user\", prefix = \"z1appA/\" → path \"file.txt\" stored as \"z1appA/file.txt\"\n */\n\nimport type { DirtyPathRow, ListDirtyPathOptions } from \"./dirty-path-queue.js\";\nimport {\n  type BatchDeleteEntry,\n  type BatchDeleteEntryResult,\n  type BatchIndexContext,\n  type BatchPutEntry,\n  type BatchPutEntryResult,\n  type ChangelogEntry,\n  loopBatchDeleteEntries,\n  loopBatchPutEntries,\n  type PutOpts,\n  type TreeEntry,\n  type TreeIndex,\n  type TreeIndexListEntriesResult,\n  type TreeIndexListOptions,\n  type TreeIndexListResult,\n} from \"./tree-index.js\";\n\nexport class PrefixedTreeIndex implements TreeIndex {\n  constructor(\n    private inner: TreeIndex,\n    private prefix: string,\n  ) {}\n\n  async get(path: string, opts?: { includeContent?: boolean }): Promise<TreeEntry | null> {\n    return this.inner.get(this.prefix + path, opts);\n  }\n\n  async getDirTimes(dirPath: string): Promise<{ ctime: number; mtime: number } | null> {\n    return (await this.inner.getDirTimes?.(this.prefix + dirPath)) ?? null;\n  }\n\n  async put(path: string, entry: TreeEntry, opts: PutOpts): Promise<{ oldCid?: string }> {\n    // Dedup scope is a collection path in the SAME namespace as `path`, so it\n    // must carry the fragment prefix too — otherwise app A and app B under one\n    // user scope would share a dedup identity (#1159 app-isolation, mirrors the\n    // prefix-local read-auth in isReferenced).\n    const prefixed =\n      entry.dedupScope != null ? { ...entry, dedupScope: this.prefix + entry.dedupScope } : entry;\n    return this.inner.put(this.prefix + path, prefixed, opts);\n  }\n\n  async delete(path: string, opts: PutOpts): Promise<void> {\n    return this.inner.delete(this.prefix + path, opts);\n  }\n\n  /** Dedup lookup (#1159) — prefix the scope in, strip the prefix off the result path. */\n  async findByDedupKey(\n    dedupScope: string,\n    dedupKey: string,\n  ): Promise<({ path: string } & TreeEntry) | null> {\n    const r = await this.inner.findByDedupKey?.(this.prefix + dedupScope, dedupKey);\n    if (!r) return null;\n    return { ...r, path: r.path.slice(this.prefix.length) };\n  }\n\n  /** Dedup reindex seam (#1159) — prefix both the path and the dedup scope. */\n  async setDedupKey(\n    path: string,\n    dedupScope: string,\n    dedupKey: string,\n    opts: PutOpts,\n  ): Promise<void> {\n    await this.inner.setDedupKey?.(this.prefix + path, this.prefix + dedupScope, dedupKey, opts);\n  }\n\n  async list(listPrefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListResult> {\n    const result = await this.inner.list(this.prefix + listPrefix, options);\n    // Strip prefix from returned paths\n    return {\n      entries: result.entries.map((e) => ({\n        path: e.path.slice(this.prefix.length),\n      })),\n      hasMore: result.hasMore,\n      cursor: result.cursor,\n    };\n  }\n\n  async listEntries(\n    listPrefix: string,\n    options?: TreeIndexListOptions,\n  ): Promise<TreeIndexListEntriesResult> {\n    const result = await this.inner.listEntries(this.prefix + listPrefix, options);\n    return {\n      entries: result.entries.map((e) => ({\n        ...e,\n        path: e.path.slice(this.prefix.length),\n      })),\n      hasMore: result.hasMore,\n      cursor: result.cursor,\n    };\n  }\n\n  async hasChildren(listPrefix: string): Promise<boolean> {\n    return this.inner.hasChildren(this.prefix + listPrefix);\n  }\n\n  async getAndHasChildren(\n    filePath: string,\n    dirPrefix: string,\n  ): Promise<[TreeEntry | null, boolean]> {\n    if (this.inner.getAndHasChildren) {\n      return this.inner.getAndHasChildren(this.prefix + filePath, this.prefix + dirPrefix);\n    }\n    const [entry, hasChildren] = await Promise.all([\n      this.inner.get(this.prefix + filePath),\n      this.inner.hasChildren(this.prefix + dirPrefix),\n    ]);\n    return [entry, hasChildren];\n  }\n\n  async count(listPrefix: string): Promise<number> {\n    return this.inner.count(this.prefix + listPrefix);\n  }\n\n  async deleteByPrefix(listPrefix: string, opts: PutOpts): Promise<number> {\n    return this.inner.deleteByPrefix(this.prefix + listPrefix, opts);\n  }\n\n  // ========== v2 methods ==========\n\n  async listChildren(\n    parent: string,\n    options?: TreeIndexListOptions,\n  ): Promise<TreeIndexListEntriesResult> {\n    const result = await this.inner.listChildren(this.prefix + parent, options);\n    return {\n      entries: result.entries.map((e) => ({\n        ...e,\n        path: e.path.slice(this.prefix.length),\n      })),\n      hasMore: result.hasMore,\n      cursor: result.cursor,\n    };\n  }\n\n  async countChildren(parent: string): Promise<number> {\n    return this.inner.countChildren(this.prefix + parent);\n  }\n\n  /**\n   * Collection query — delegate with the fragment prefix prepended, strip it\n   * off result row paths. The prefix is the blocklet-isolation boundary: a\n   * fragment can only ever query its own sub-tree.\n   */\n  async query(\n    parent: string,\n    spec: import(\"./tree-query.js\").TreeQuerySpec,\n  ): Promise<import(\"./tree-query.js\").TreeQueryResult> {\n    if (!this.inner.query) {\n      throw new Error(\"Collection query is not supported by the underlying index\");\n    }\n    const result = await this.inner.query(this.prefix + parent, spec);\n    return {\n      ...result,\n      rows: result.rows.map((r) => ({ ...r, path: r.path.slice(this.prefix.length) })),\n    };\n  }\n\n  async countChildrenMany(parents: string[]): Promise<Map<string, number>> {\n    // Delegate with the prefix prepended, then strip it back off the parent\n    // keys so the returned paths match what `listChildren` yields here. An\n    // inner index without the method falls back to per-path countChildren —\n    // page-bounded by contract, so the loop is ≤ one page of parents. Zero\n    // counts stay omitted in both branches (contract: `map.get(p) ?? 0`).\n    const out = new Map<string, number>();\n    if (!this.inner.countChildrenMany) {\n      for (const p of parents) {\n        const cnt = await this.inner.countChildren(this.prefix + p);\n        if (cnt > 0) out.set(p, cnt);\n      }\n      return out;\n    }\n    const inner = await this.inner.countChildrenMany(parents.map((p) => this.prefix + p));\n    for (const [parent, cnt] of inner) out.set(parent.slice(this.prefix.length), cnt);\n    return out;\n  }\n\n  async aggregate(prefix: string): Promise<{ fileCount: number; totalSize: number }> {\n    return this.inner.aggregate(this.prefix + prefix);\n  }\n\n  async putBatch(entries: Array<{ path: string; entry: TreeEntry }>, opts: PutOpts): Promise<void> {\n    return this.inner.putBatch(\n      entries.map((e) => ({ path: this.prefix + e.path, entry: e.entry })),\n      opts,\n    );\n  }\n\n  // ── batch sync fast path (afs-rpc-batch P3) — prefix in, strip out ──\n  // Forwards to the inner index's merged implementation when present; falls\n  // back to the loop reference semantics over THIS wrapper otherwise.\n\n  private mapPrereadIn(ctx: BatchIndexContext | undefined): BatchIndexContext | undefined {\n    if (!ctx?.preread) return ctx;\n    const inner = new Map<string, TreeEntry | null>();\n    for (const [k, v] of ctx.preread) inner.set(this.prefix + k, v);\n    return { ...ctx, preread: inner };\n  }\n\n  async getMany(paths: string[]): Promise<Map<string, TreeEntry | null>> {\n    if (!this.inner.getMany) {\n      const map = new Map<string, TreeEntry | null>();\n      for (const p of paths) map.set(p, await this.get(p));\n      return map;\n    }\n    const innerMap = await this.inner.getMany(paths.map((p) => this.prefix + p));\n    const map = new Map<string, TreeEntry | null>();\n    for (const p of paths) map.set(p, innerMap.get(this.prefix + p) ?? null);\n    return map;\n  }\n\n  /** Inline policy is path-independent — delegate straight to the inner index.\n   *  An inner without inline support resolves to NULL (loop keeps the legacy skip). */\n  inlineForEntry(entry: TreeEntry): Promise<string | null> {\n    return this.inner.inlineForEntry?.(entry) ?? Promise.resolve(null);\n  }\n\n  async batchPutEntries(\n    entries: BatchPutEntry[],\n    ctx?: BatchIndexContext,\n  ): Promise<BatchPutEntryResult[]> {\n    if (!this.inner.batchPutEntries) return loopBatchPutEntries(this, entries, ctx);\n    const results = await this.inner.batchPutEntries(\n      entries.map((e) => ({ ...e, path: this.prefix + e.path })),\n      this.mapPrereadIn(ctx),\n    );\n    return results.map((r) => ({ ...r, path: r.path.slice(this.prefix.length) }));\n  }\n\n  async batchDeleteEntries(\n    entries: BatchDeleteEntry[],\n    ctx?: BatchIndexContext,\n  ): Promise<BatchDeleteEntryResult[]> {\n    if (!this.inner.batchDeleteEntries) return loopBatchDeleteEntries(this, entries, ctx);\n    const results = await this.inner.batchDeleteEntries(\n      entries.map((e) => ({ ...e, path: this.prefix + e.path })),\n      this.mapPrereadIn(ctx),\n    );\n    return results.map((r) => ({ ...r, path: r.path.slice(this.prefix.length) }));\n  }\n\n  async listModifiedSince(\n    prefix: string,\n    since: number,\n    options?: TreeIndexListOptions,\n  ): Promise<TreeIndexListEntriesResult> {\n    const result = await this.inner.listModifiedSince(this.prefix + prefix, since, options);\n    return {\n      entries: result.entries.map((e) => ({\n        ...e,\n        path: e.path.slice(this.prefix.length),\n      })),\n      hasMore: result.hasMore,\n      cursor: result.cursor,\n    };\n  }\n\n  async getMaxSeq(): Promise<number> {\n    // The changelog is shared across the entire scope; delegate to the\n    // underlying index so the waterline reflects the scope's latest write.\n    return this.inner.getMaxSeq();\n  }\n\n  async getPrefixWatermark(prefix: string): Promise<number | null> {\n    // Prepend the fragment prefix so the inner index reduces `prefix + path`\n    // to the same watermark key on read as it did on write. For the\n    // instance-space layout (`blocklets/{i}/{role}/`) `watermarkPrefix`\n    // resolves the key at the per-fragment collection root\n    // (`blocklets/{i}/{role}/items`), keeping rows prefix-local (I3) instead\n    // of collapsing the whole scope onto one first-segment row. If the inner\n    // index lacks the method (rollout), there is no watermark → null.\n    if (!this.inner.getPrefixWatermark) return null;\n    return this.inner.getPrefixWatermark(this.prefix + prefix);\n  }\n\n  async getChangelogSince(\n    sinceSeq: number,\n    limit: number,\n  ): Promise<{ entries: ChangelogEntry[]; hasMore: boolean; cursor: number }> {\n    // The inner changelog is space-wide (scope = userDid). Filter to rows whose\n    // path falls under this fragment's prefix and strip it, so callers only see\n    // their own app's changes — never another app's rows under the same scope.\n    //\n    // `cursor` and `hasMore` come STRAIGHT from inner: cursor = max inner seq on\n    // this page (NOT the last surviving entry's seq), hasMore = inner pagination.\n    // This guarantees the cursor advances even when the prefix filter empties a\n    // page — the caller keeps pulling by cursor until the inner scan is drained,\n    // with no infinite loop and no skipped rows.\n    const inner = await this.inner.getChangelogSince(sinceSeq, limit);\n    const entries = inner.entries\n      .filter((r) => r.path.startsWith(this.prefix))\n      .map((r) => ({ ...r, path: r.path.slice(this.prefix.length) }));\n    return { entries, hasMore: inner.hasMore, cursor: inner.cursor };\n  }\n\n  async getCompactedBelowSeq(): Promise<number> {\n    return (await this.inner.getCompactedBelowSeq?.()) ?? 0;\n  }\n\n  /**\n   * PREFIX-LOCAL read-auth (design §4.1, P0#2): authorize a cid ONLY when this\n   * fragment's own sub-tree references it. Delegates with the fragment prefix\n   * prepended, so app A can never read app B's object under the same user by\n   * knowing the cid. The unprefixed space-root provider stays whole-scope.\n   */\n  async isReferenced(cid: string, pathPrefix = \"\"): Promise<boolean> {\n    return this.inner.isReferenced(cid, this.prefix + pathPrefix);\n  }\n\n  /**\n   * PREFIX-LOCAL batch read-auth (design §7.2): authorize ONLY cids this\n   * fragment's own sub-tree references. Same prefix-prepend delegation as the\n   * single-cid {@link isReferenced}.\n   */\n  async isReferencedMany(cids: string[], pathPrefix = \"\"): Promise<Set<string>> {\n    return this.inner.isReferencedMany(cids, this.prefix + pathPrefix);\n  }\n\n  // ── Source-side dirty queue (index-follower-dirty-path §7) ──\n  //\n  // The blocklet-isolation boundary for dirty rows: prepend this fragment's\n  // prefix on the way IN (so the inner range scan is confined to\n  // `blocklets/{instanceDid}/{role}/…`, never another blocklet's rows) and\n  // strip it OFF the returned `path` so the follower sees the stripped\n  // `originalPath` (e.g. `items/x.json`). ack/fail re-add the full path. A\n  // caller can only ever list/ack/fail dirty rows inside its own sub-tree — a\n  // manual `../` or foreign full path lands OUTSIDE `[prefix, prefix+succ)` and\n  // matches nothing.\n\n  async listDirtyPaths(options: ListDirtyPathOptions): Promise<DirtyPathRow[]> {\n    if (!this.inner.listDirtyPaths) return [];\n    const rows = await this.inner.listDirtyPaths({\n      ...options,\n      prefix: this.prefix + options.prefix,\n    });\n    return rows.map((r) => ({ ...r, path: r.path.slice(this.prefix.length) }));\n  }\n\n  async ackDirtyPath(path: string, latestSeq: number): Promise<boolean> {\n    if (!this.inner.ackDirtyPath) return false;\n    return this.inner.ackDirtyPath(this.prefix + path, latestSeq);\n  }\n\n  async markDirtyPathError(\n    path: string,\n    latestSeq: number,\n    error: string,\n    nextAttemptAt: number,\n  ): Promise<boolean> {\n    if (!this.inner.markDirtyPathError) return false;\n    return this.inner.markDirtyPathError(this.prefix + path, latestSeq, error, nextAttemptAt);\n  }\n}\n"],"mappings":"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"}

package/dist/presign-signer.cjs

@@ -0,0 +1,7 @@
+
+//#region src/presign-signer.ts
+/** S3/R2 presigned-URL max validity (7 days, in seconds). */
+const PRESIGN_MAX_EXPIRES_SEC = 10080 * 60;
+
+//#endregion
+exports.PRESIGN_MAX_EXPIRES_SEC = PRESIGN_MAX_EXPIRES_SEC;

package/dist/presign-signer.d.cts

@@ -0,0 +1,99 @@
+//#region src/presign-signer.d.ts
+/**
+ * presign-signer.ts — the object-store signing capability contract (design §7.1).
+ *
+ * A `PresignSigner` mints a single, exact-key, checksum-pinned upload grant for
+ * the object-store layer. It is an **injected dependency** (like `ObjectStore`):
+ * the provider itself never holds R2 credentials — the runtime constructs a
+ * concrete signer (CF: `R2PresignSigner` over `aws4fetch`, §15 decision 7) and
+ * injects it, or injects nothing (Node `DIDSpace` = fallback-only, §15 decision 8,
+ * so `signer === null` is a legitimate, stable state).
+ *
+ * The grant authorizes EXACTLY one object key + one `PutObject`, and pins the
+ * full-object SHA-256 checksum into the signature so a malicious client can
+ * neither change the key nor the bytes (the global CAS pool's only cross-user
+ * integrity defense — design §7.1 / §10, P0-verified in p0-measurements.md).
+ */
+/**
+ * A minted presigned PUT grant. The client uploads bytes out-of-band:
+ * `fetch(url, { method, headers: signedHeaders, body })`.
+ *
+ * `signedHeaders` are the headers the client MUST resend verbatim for the
+ * signature to validate (with aws4fetch's `signQuery`, the checksum header's
+ * NAME is in `X-Amz-SignedHeaders` but its VALUE is not in the query — so the
+ * client has to send the header itself; tampering → `403`, see §8).
+ */
+interface PresignedPut {
+  url: string;
+  method: "PUT";
+  signedHeaders: Record<string, string>;
+  /** ISO-8601 expiry — when the presigned URL stops being accepted by R2. */
+  expiresAt: string;
+}
+interface PresignPutInput {
+  /** Exact object-store key, e.g. `objects/bafk...`. Pinned into the signature. */
+  objectKey: string;
+  /** base64 of the 32-byte SHA-256 digest (= the CID's multihash digest). */
+  checksumSha256: string;
+  /** URL validity in seconds (0 < n ≤ 604800; S3/R2 hard cap is 7 days). */
+  expiresInSec: number;
+  /** Optional content type to pin (currently advisory; not signed in v1). */
+  contentType?: string;
+  /**
+   * Declared byte length (upload-limits Phase 4, anti-lie D2 = §9.2(ii)). When
+   * set, the signer pins `Content-Length` INTO the signature so R2 rejects a PUT
+   * whose body size differs (`403 SignatureDoesNotMatch`) — a client cannot
+   * declare a small size to pass the ingest-prepare cap then PUT a larger object
+   * (PRE-2 spike PASS, real R2). Omitted → no size pin (back-compat; Node has no
+   * signer so this is moot there). aws4fetch lists `content-length` as
+   * UNSIGNABLE, so the signer must opt into `allHeaders` to sign it.
+   */
+  contentLength?: number;
+}
+/**
+ * A minted presigned GET grant (download plane, design §7.1). The client reads
+ * bytes out-of-band: `fetch(url, { method, headers: signedHeaders })`.
+ *
+ * Symmetric to {@link PresignedPut} but READ-ONLY: GET-only, exact-key, short
+ * TTL, and — unlike PUT — NO checksum is pinned. Integrity is the client's
+ * `computeCID(bytes)` self-check (design §8.1), not an R2-enforced precondition,
+ * so `signedHeaders` is normally `{}` (the host header is injected by `fetch`).
+ */
+interface PresignedGet {
+  url: string;
+  method: "GET";
+  signedHeaders: Record<string, string>;
+  /** ISO-8601 expiry — when the presigned URL stops being accepted by R2. */
+  expiresAt: string;
+}
+interface PresignGetInput {
+  /** Exact object-store key, e.g. `objects/bafk...`. Pinned into the signature. */
+  objectKey: string;
+  /** URL validity in seconds (0 < n ≤ 604800; S3/R2 hard cap is 7 days). */
+  expiresInSec: number;
+  /**
+   * Optional Content-Type to bake into the signed URL via the S3
+   * `response-content-type` query override (preview-r2-direct §3 / Review-1).
+   * Objects are stored content-addressed with NO httpMetadata, so R2 would
+   * otherwise serve them as `application/octet-stream` (a `<video>`/`<audio>`
+   * element then won't play). Set, the signer adds `response-content-type=<mime>`
+   * (+ defensive `response-content-disposition=inline`) BEFORE signing so R2
+   * honors it. OMITTED → the URL is byte-identical to the no-override form
+   * (native-sync `prepare-download` omits it → back-compatible).
+   */
+  responseContentType?: string;
+}
+interface PresignSigner {
+  presignPut(input: PresignPutInput): Promise<PresignedPut>;
+  /**
+   * Mint an exact-key, short-TTL presigned GET (download plane, design §7.1).
+   * Required on every signer — its presence IS the `downloadGrantCapability`
+   * flag's `typeof signer.presignGet === "function"` basis (design §7.3).
+   */
+  presignGet(input: PresignGetInput): Promise<PresignedGet>;
+}
+/** S3/R2 presigned-URL max validity (7 days, in seconds). */
+declare const PRESIGN_MAX_EXPIRES_SEC: number;
+//#endregion
+export { PRESIGN_MAX_EXPIRES_SEC, PresignGetInput, PresignPutInput, PresignSigner, PresignedGet, PresignedPut };
+//# sourceMappingURL=presign-signer.d.cts.map

package/dist/presign-signer.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presign-signer.d.cts","names":[],"sources":["../src/presign-signer.ts"],"mappings":";;AAyBA;;;;;;;;;;;AAQA;;;;;;;;;;;AA8BA;UAtCiB,YAAA;EACf,GAAA;EACA,MAAA;EACA,aAAA,EAAe,MAAA;EAqCf;EAnCA,SAAA;AAAA;AAAA,UAGe,eAAA;EAmCN;EAjCT,SAAA;EAoCe;EAlCf,cAAA;;EAEA,YAAA;EAkCA;EAhCA,WAAA;EA+CA;;;AAGF;;;;;;EAxCE,aAAA;AAAA;;;;;;;;;;UAYe,YAAA;EACf,GAAA;EACA,MAAA;EACA,aAAA,EAAe,MAAA;EAgCyC;EA9BxD,SAAA;AAAA;AAAA,UAGe,eAAA;;EAEf,SAAA;EA6BqD;EA3BrD,YAAA;;;;;;;;;;;EAaA,mBAAA;AAAA;AAAA,UAGe,aAAA;EACf,UAAA,CAAW,KAAA,EAAO,eAAA,GAAkB,OAAA,CAAQ,YAAA;;;;;;EAM5C,UAAA,CAAW,KAAA,EAAO,eAAA,GAAkB,OAAA,CAAQ,YAAA;AAAA;;cAIjC,uBAAA"}

package/dist/presign-signer.d.mts

@@ -0,0 +1,99 @@
+//#region src/presign-signer.d.ts
+/**
+ * presign-signer.ts — the object-store signing capability contract (design §7.1).
+ *
+ * A `PresignSigner` mints a single, exact-key, checksum-pinned upload grant for
+ * the object-store layer. It is an **injected dependency** (like `ObjectStore`):
+ * the provider itself never holds R2 credentials — the runtime constructs a
+ * concrete signer (CF: `R2PresignSigner` over `aws4fetch`, §15 decision 7) and
+ * injects it, or injects nothing (Node `DIDSpace` = fallback-only, §15 decision 8,
+ * so `signer === null` is a legitimate, stable state).
+ *
+ * The grant authorizes EXACTLY one object key + one `PutObject`, and pins the
+ * full-object SHA-256 checksum into the signature so a malicious client can
+ * neither change the key nor the bytes (the global CAS pool's only cross-user
+ * integrity defense — design §7.1 / §10, P0-verified in p0-measurements.md).
+ */
+/**
+ * A minted presigned PUT grant. The client uploads bytes out-of-band:
+ * `fetch(url, { method, headers: signedHeaders, body })`.
+ *
+ * `signedHeaders` are the headers the client MUST resend verbatim for the
+ * signature to validate (with aws4fetch's `signQuery`, the checksum header's
+ * NAME is in `X-Amz-SignedHeaders` but its VALUE is not in the query — so the
+ * client has to send the header itself; tampering → `403`, see §8).
+ */
+interface PresignedPut {
+  url: string;
+  method: "PUT";
+  signedHeaders: Record<string, string>;
+  /** ISO-8601 expiry — when the presigned URL stops being accepted by R2. */
+  expiresAt: string;
+}
+interface PresignPutInput {
+  /** Exact object-store key, e.g. `objects/bafk...`. Pinned into the signature. */
+  objectKey: string;
+  /** base64 of the 32-byte SHA-256 digest (= the CID's multihash digest). */
+  checksumSha256: string;
+  /** URL validity in seconds (0 < n ≤ 604800; S3/R2 hard cap is 7 days). */
+  expiresInSec: number;
+  /** Optional content type to pin (currently advisory; not signed in v1). */
+  contentType?: string;
+  /**
+   * Declared byte length (upload-limits Phase 4, anti-lie D2 = §9.2(ii)). When
+   * set, the signer pins `Content-Length` INTO the signature so R2 rejects a PUT
+   * whose body size differs (`403 SignatureDoesNotMatch`) — a client cannot
+   * declare a small size to pass the ingest-prepare cap then PUT a larger object
+   * (PRE-2 spike PASS, real R2). Omitted → no size pin (back-compat; Node has no
+   * signer so this is moot there). aws4fetch lists `content-length` as
+   * UNSIGNABLE, so the signer must opt into `allHeaders` to sign it.
+   */
+  contentLength?: number;
+}
+/**
+ * A minted presigned GET grant (download plane, design §7.1). The client reads
+ * bytes out-of-band: `fetch(url, { method, headers: signedHeaders })`.
+ *
+ * Symmetric to {@link PresignedPut} but READ-ONLY: GET-only, exact-key, short
+ * TTL, and — unlike PUT — NO checksum is pinned. Integrity is the client's
+ * `computeCID(bytes)` self-check (design §8.1), not an R2-enforced precondition,
+ * so `signedHeaders` is normally `{}` (the host header is injected by `fetch`).
+ */
+interface PresignedGet {
+  url: string;
+  method: "GET";
+  signedHeaders: Record<string, string>;
+  /** ISO-8601 expiry — when the presigned URL stops being accepted by R2. */
+  expiresAt: string;
+}
+interface PresignGetInput {
+  /** Exact object-store key, e.g. `objects/bafk...`. Pinned into the signature. */
+  objectKey: string;
+  /** URL validity in seconds (0 < n ≤ 604800; S3/R2 hard cap is 7 days). */
+  expiresInSec: number;
+  /**
+   * Optional Content-Type to bake into the signed URL via the S3
+   * `response-content-type` query override (preview-r2-direct §3 / Review-1).
+   * Objects are stored content-addressed with NO httpMetadata, so R2 would
+   * otherwise serve them as `application/octet-stream` (a `<video>`/`<audio>`
+   * element then won't play). Set, the signer adds `response-content-type=<mime>`
+   * (+ defensive `response-content-disposition=inline`) BEFORE signing so R2
+   * honors it. OMITTED → the URL is byte-identical to the no-override form
+   * (native-sync `prepare-download` omits it → back-compatible).
+   */
+  responseContentType?: string;
+}
+interface PresignSigner {
+  presignPut(input: PresignPutInput): Promise<PresignedPut>;
+  /**
+   * Mint an exact-key, short-TTL presigned GET (download plane, design §7.1).
+   * Required on every signer — its presence IS the `downloadGrantCapability`
+   * flag's `typeof signer.presignGet === "function"` basis (design §7.3).
+   */
+  presignGet(input: PresignGetInput): Promise<PresignedGet>;
+}
+/** S3/R2 presigned-URL max validity (7 days, in seconds). */
+declare const PRESIGN_MAX_EXPIRES_SEC: number;
+//#endregion
+export { PRESIGN_MAX_EXPIRES_SEC, PresignGetInput, PresignPutInput, PresignSigner, PresignedGet, PresignedPut };
+//# sourceMappingURL=presign-signer.d.mts.map

package/dist/presign-signer.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presign-signer.d.mts","names":[],"sources":["../src/presign-signer.ts"],"mappings":";;AAyBA;;;;;;;;;;;AAQA;;;;;;;;;;;AA8BA;UAtCiB,YAAA;EACf,GAAA;EACA,MAAA;EACA,aAAA,EAAe,MAAA;EAqCf;EAnCA,SAAA;AAAA;AAAA,UAGe,eAAA;EAmCN;EAjCT,SAAA;EAoCe;EAlCf,cAAA;;EAEA,YAAA;EAkCA;EAhCA,WAAA;EA+CA;;;AAGF;;;;;;EAxCE,aAAA;AAAA;;;;;;;;;;UAYe,YAAA;EACf,GAAA;EACA,MAAA;EACA,aAAA,EAAe,MAAA;EAgCyC;EA9BxD,SAAA;AAAA;AAAA,UAGe,eAAA;;EAEf,SAAA;EA6BqD;EA3BrD,YAAA;;;;;;;;;;;EAaA,mBAAA;AAAA;AAAA,UAGe,aAAA;EACf,UAAA,CAAW,KAAA,EAAO,eAAA,GAAkB,OAAA,CAAQ,YAAA;;;;;;EAM5C,UAAA,CAAW,KAAA,EAAO,eAAA,GAAkB,OAAA,CAAQ,YAAA;AAAA;;cAIjC,uBAAA"}

package/dist/presign-signer.mjs

@@ -0,0 +1,7 @@
+//#region src/presign-signer.ts
+/** S3/R2 presigned-URL max validity (7 days, in seconds). */
+const PRESIGN_MAX_EXPIRES_SEC = 10080 * 60;
+
+//#endregion
+export { PRESIGN_MAX_EXPIRES_SEC };
+//# sourceMappingURL=presign-signer.mjs.map

package/dist/presign-signer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"presign-signer.mjs","names":[],"sources":["../src/presign-signer.ts"],"sourcesContent":["/**\n * presign-signer.ts — the object-store signing capability contract (design §7.1).\n *\n * A `PresignSigner` mints a single, exact-key, checksum-pinned upload grant for\n * the object-store layer. It is an **injected dependency** (like `ObjectStore`):\n * the provider itself never holds R2 credentials — the runtime constructs a\n * concrete signer (CF: `R2PresignSigner` over `aws4fetch`, §15 decision 7) and\n * injects it, or injects nothing (Node `DIDSpace` = fallback-only, §15 decision 8,\n * so `signer === null` is a legitimate, stable state).\n *\n * The grant authorizes EXACTLY one object key + one `PutObject`, and pins the\n * full-object SHA-256 checksum into the signature so a malicious client can\n * neither change the key nor the bytes (the global CAS pool's only cross-user\n * integrity defense — design §7.1 / §10, P0-verified in p0-measurements.md).\n */\n\n/**\n * A minted presigned PUT grant. The client uploads bytes out-of-band:\n * `fetch(url, { method, headers: signedHeaders, body })`.\n *\n * `signedHeaders` are the headers the client MUST resend verbatim for the\n * signature to validate (with aws4fetch's `signQuery`, the checksum header's\n * NAME is in `X-Amz-SignedHeaders` but its VALUE is not in the query — so the\n * client has to send the header itself; tampering → `403`, see §8).\n */\nexport interface PresignedPut {\n  url: string;\n  method: \"PUT\";\n  signedHeaders: Record<string, string>;\n  /** ISO-8601 expiry — when the presigned URL stops being accepted by R2. */\n  expiresAt: string;\n}\n\nexport interface PresignPutInput {\n  /** Exact object-store key, e.g. `objects/bafk...`. Pinned into the signature. */\n  objectKey: string;\n  /** base64 of the 32-byte SHA-256 digest (= the CID's multihash digest). */\n  checksumSha256: string;\n  /** URL validity in seconds (0 < n ≤ 604800; S3/R2 hard cap is 7 days). */\n  expiresInSec: number;\n  /** Optional content type to pin (currently advisory; not signed in v1). */\n  contentType?: string;\n  /**\n   * Declared byte length (upload-limits Phase 4, anti-lie D2 = §9.2(ii)). When\n   * set, the signer pins `Content-Length` INTO the signature so R2 rejects a PUT\n   * whose body size differs (`403 SignatureDoesNotMatch`) — a client cannot\n   * declare a small size to pass the ingest-prepare cap then PUT a larger object\n   * (PRE-2 spike PASS, real R2). Omitted → no size pin (back-compat; Node has no\n   * signer so this is moot there). aws4fetch lists `content-length` as\n   * UNSIGNABLE, so the signer must opt into `allHeaders` to sign it.\n   */\n  contentLength?: number;\n}\n\n/**\n * A minted presigned GET grant (download plane, design §7.1). The client reads\n * bytes out-of-band: `fetch(url, { method, headers: signedHeaders })`.\n *\n * Symmetric to {@link PresignedPut} but READ-ONLY: GET-only, exact-key, short\n * TTL, and — unlike PUT — NO checksum is pinned. Integrity is the client's\n * `computeCID(bytes)` self-check (design §8.1), not an R2-enforced precondition,\n * so `signedHeaders` is normally `{}` (the host header is injected by `fetch`).\n */\nexport interface PresignedGet {\n  url: string;\n  method: \"GET\";\n  signedHeaders: Record<string, string>;\n  /** ISO-8601 expiry — when the presigned URL stops being accepted by R2. */\n  expiresAt: string;\n}\n\nexport interface PresignGetInput {\n  /** Exact object-store key, e.g. `objects/bafk...`. Pinned into the signature. */\n  objectKey: string;\n  /** URL validity in seconds (0 < n ≤ 604800; S3/R2 hard cap is 7 days). */\n  expiresInSec: number;\n  // GET pins no checksum: integrity is verified by the client's computeCID\n  // (design §8.1), not enforced by R2 — the dual of presignPut's checksum pin.\n  /**\n   * Optional Content-Type to bake into the signed URL via the S3\n   * `response-content-type` query override (preview-r2-direct §3 / Review-1).\n   * Objects are stored content-addressed with NO httpMetadata, so R2 would\n   * otherwise serve them as `application/octet-stream` (a `<video>`/`<audio>`\n   * element then won't play). Set, the signer adds `response-content-type=<mime>`\n   * (+ defensive `response-content-disposition=inline`) BEFORE signing so R2\n   * honors it. OMITTED → the URL is byte-identical to the no-override form\n   * (native-sync `prepare-download` omits it → back-compatible).\n   */\n  responseContentType?: string;\n}\n\nexport interface PresignSigner {\n  presignPut(input: PresignPutInput): Promise<PresignedPut>;\n  /**\n   * Mint an exact-key, short-TTL presigned GET (download plane, design §7.1).\n   * Required on every signer — its presence IS the `downloadGrantCapability`\n   * flag's `typeof signer.presignGet === \"function\"` basis (design §7.3).\n   */\n  presignGet(input: PresignGetInput): Promise<PresignedGet>;\n}\n\n/** S3/R2 presigned-URL max validity (7 days, in seconds). */\nexport const PRESIGN_MAX_EXPIRES_SEC = 7 * 24 * 60 * 60;\n"],"mappings":";;AAsGA,MAAa,0BAA0B,QAAc"}

package/dist/providers/platform/r2/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { ObjectStore, ObjectStoreHeadResult, ObjectStoreListOptions, ObjectStoreListResult, ObjectStoreObject } from "./types.mjs";
+import { AFSAccessMode, AFSEntry, AFSExplainResult, AFSListResult, AFSSearchOptions, AFSStatResult, AFSWriteEntryPayload, CapabilitiesManifest, ProviderManifest, ProviderTreeSchema } from "@aigne/afs";
+import { AFSBaseProvider, RouteContext } from "@aigne/afs/provider";

package/dist/providers/platform/r2/dist/types.d.mts

@@ -0,0 +1,49 @@
+//#region ../../platform/r2/dist/types.d.cts
+//#region src/types.d.ts
+/**
+ * ObjectStore — platform-agnostic interface for R2-compatible object storage.
+ *
+ * R2Bucket satisfies this interface natively.
+ * For Node.js testing, use MemoryObjectStore or miniflare.
+ */
+interface ObjectStoreObject {
+  readonly key: string;
+  readonly size: number;
+  readonly uploaded: Date;
+  /** Custom metadata (R2 httpMetadata or custom) */
+  readonly customMetadata?: Record<string, string>;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+interface ObjectStoreHeadResult {
+  readonly key: string;
+  readonly size: number;
+  readonly uploaded: Date;
+  readonly customMetadata?: Record<string, string>;
+}
+interface ObjectStoreListResult {
+  readonly objects: ReadonlyArray<{
+    readonly key: string;
+    readonly size: number;
+    readonly uploaded: Date;
+    readonly customMetadata?: Record<string, string>;
+  }>;
+  readonly truncated: boolean;
+  readonly cursor?: string;
+}
+interface ObjectStoreListOptions {
+  prefix?: string;
+  cursor?: string;
+  limit?: number;
+  delimiter?: string;
+}
+interface ObjectStore {
+  get(key: string): Promise<ObjectStoreObject | null>;
+  put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+  list(options?: ObjectStoreListOptions): Promise<ObjectStoreListResult>;
+  head(key: string): Promise<ObjectStoreHeadResult | null>;
+  delete(key: string): Promise<void>;
+} //#endregion
+//#endregion
+export { ObjectStore, ObjectStoreHeadResult, ObjectStoreListOptions, ObjectStoreListResult, ObjectStoreObject };
+//# sourceMappingURL=types.d.mts.map

package/dist/providers/platform/r2/dist/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":["ObjectStoreObject","Date","Record","Promise","ArrayBuffer","key","size","uploaded","customMetadata","text","arrayBuffer","ObjectStoreHeadResult","ObjectStoreListResult","ReadonlyArray","objects","truncated","cursor","ObjectStoreListOptions","prefix","limit","delimiter","ObjectStore","ReadableStream","get","put","value","list","options","head","delete"],"sources":["../../../../../../../platform/r2/dist/types.d.cts"],"mappings":";;;;;;;;UAOUA,iBAAAA;EAAAA,SACCK,GAAAA;EAAAA,SACAC,IAAAA;EAAAA,SACAC,QAAAA,EAAUN,IAAAA;EAFVI;EAAAA,SAIAG,cAAAA,GAAiBN,MAAAA;EAC1BO,IAAAA,IAAQN,OAAAA;EACRO,WAAAA,IAAeP,OAAAA,CAAQC,WAAAA;AAAAA;AAAAA,UAEfO,qBAAAA;EAAAA,SACCN,GAAAA;EAAAA,SACAC,IAAAA;EAAAA,SACAC,QAAAA,EAAUN,IAAAA;EAAAA,SACVO,cAAAA,GAAiBN,MAAAA;AAAAA;AAAAA,UAElBU,qBAAAA;EAAAA,SACCE,OAAAA,EAASD,aAAAA;IAAAA,SACPR,GAAAA;IAAAA,SACAC,IAAAA;IAAAA,SACAC,QAAAA,EAAUN,IAAAA;IAAAA,SACVO,cAAAA,GAAiBN,MAAAA;EAAAA;EAAAA,SAEnBa,SAAAA;EAAAA,SACAC,MAAAA;AAAAA;AAAAA,UAEDC,sBAAAA;EACRC,MAAAA;EACAF,MAAAA;EACAG,KAAAA;EACAC,SAAAA;AAAAA;AAAAA,UAEQC,WAAAA;EACRE,GAAAA,CAAIlB,GAAAA,WAAcF,OAAAA,CAAQH,iBAAAA;EAC1BwB,GAAAA,CAAInB,GAAAA,UAAaoB,KAAAA,WAAgBrB,WAAAA,GAAckB,cAAAA,GAAiBnB,OAAAA;EAChEuB,IAAAA,CAAKC,OAAAA,GAAUV,sBAAAA,GAAyBd,OAAAA,CAAQS,qBAAAA;EAChDgB,IAAAA,CAAKvB,GAAAA,WAAcF,OAAAA,CAAQQ,qBAAAA;EAC3BkB,MAAAA,CAAOxB,GAAAA,WAAcF,OAAAA;AAAAA"}

package/dist/reconcile.cjs

@@ -0,0 +1,184 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_cid = require('./cid.cjs');
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+
+//#region src/reconcile.ts
+/**
+* DIDSpace reconcile engine — Phase 2 (Task 2.2)
+*
+* Compares the local filesystem against _metadata.db and brings the index
+* up to date without reading file content unless necessary.
+*
+* Algorithm (scalability-design §七):
+*   1. Walk filesystem (stat only) — O(n) syscalls, no file reads
+*   2. Read index from _metadata.db — single SQL query
+*   3. Three-way compare per file:
+*      - NEW:       in FS, not in DB  → read file, computeCID, INSERT
+*      - MODIFIED:  in both, mtime or size differ → re-read, computeCID, UPDATE
+*      - UNCHANGED: in both, mtime+size same       → skip (CID cache hit)
+*      - DELETED:   in DB, not in FS  → DELETE from entries
+*   4. Batch-update entries + cid_cache
+*/
+/** File names/patterns to exclude from reconcile */
+const EXCLUDED_NAMES = new Set([
+	"_metadata.db",
+	"_metadata.db-wal",
+	"_metadata.db-shm"
+]);
+/** Directory names to skip entirely (they contain sensitive/internal data) */
+const EXCLUDED_DIRS = new Set(["vault", "config"]);
+function isExcluded(name) {
+	if (EXCLUDED_NAMES.has(name)) return true;
+	if (name.startsWith("data.db")) return true;
+	if (name.endsWith("-wal") || name.endsWith("-shm") || name.endsWith("-journal")) return true;
+	return false;
+}
+/** Convert an absolute filesystem path to a relative AFS-style path (no leading slash). */
+function fsPathToRelative(rootPath, absPath) {
+	const rel = (0, node_path.relative)(rootPath, absPath);
+	return node_path.sep === "\\" ? rel.replace(/\\/g, "/") : rel;
+}
+function walkFs(rootPath, dir, depth) {
+	const results = [];
+	let entries;
+	try {
+		entries = (0, node_fs.readdirSync)(dir, { withFileTypes: true });
+	} catch {
+		return results;
+	}
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		if (isExcluded(entry.name)) continue;
+		const absPath = (0, node_path.join)(dir, entry.name);
+		if (entry.isSymbolicLink()) continue;
+		if (entry.isDirectory()) {
+			if (EXCLUDED_DIRS.has(entry.name)) continue;
+			results.push(...walkFs(rootPath, absPath, depth + 1));
+		} else if (entry.isFile()) {
+			if (depth === 0) continue;
+			let st;
+			try {
+				st = (0, node_fs.statSync)(absPath);
+			} catch {
+				continue;
+			}
+			results.push({
+				absPath,
+				relPath: fsPathToRelative(rootPath, absPath),
+				size: st.size,
+				mtimeMs: Math.floor(st.mtimeMs)
+			});
+		}
+	}
+	return results;
+}
+/**
+* Derive the `parent` path for a given file/dir path (no leading slash convention).
+*
+* Examples:
+*   "appA/files/hello.txt" → "appA/files/"
+*   "appA/files/"          → "appA/"
+*   "appA/"                → ""
+*/
+function parentOf(path) {
+	const p = path.endsWith("/") ? path.slice(0, -1) : path;
+	const idx = p.lastIndexOf("/");
+	if (idx < 0) return "";
+	return p.slice(0, idx + 1);
+}
+/** Derive the basename (name) from a path (no leading slash convention). */
+function nameOf(path) {
+	const p = path.endsWith("/") ? path.slice(0, -1) : path;
+	const idx = p.lastIndexOf("/");
+	return idx < 0 ? p : p.slice(idx + 1);
+}
+/**
+* Reconcile the local filesystem against _metadata.db.
+* Returns stats about the reconcile operation.
+*/
+async function reconcile(options) {
+	const { rootPath, scope, metadataDb } = options;
+	const start = Date.now();
+	const fsFiles = walkFs(rootPath, rootPath, 0);
+	const fsMap = /* @__PURE__ */ new Map();
+	for (const f of fsFiles) fsMap.set(f.relPath, {
+		size: f.size,
+		mtimeMs: f.mtimeMs,
+		absPath: f.absPath
+	});
+	const dbFiles = await metadataDb.getFiles(scope);
+	const dbMap = /* @__PURE__ */ new Map();
+	for (const row of dbFiles) dbMap.set(row.path, row);
+	const toUpsert = [];
+	const toDelete = [];
+	const now = Date.now();
+	let added = 0;
+	let modified = 0;
+	let unchanged = 0;
+	for (const [relPath, fsInfo] of fsMap) {
+		const dbEntry = dbMap.get(relPath);
+		if (!dbEntry) {
+			const cid = await computeCidWithCache(metadataDb, fsInfo.absPath, fsInfo.size, fsInfo.mtimeMs);
+			toUpsert.push({
+				scope,
+				path: relPath,
+				parent: parentOf(relPath),
+				name: nameOf(relPath),
+				kind: "file",
+				cid,
+				size: fsInfo.size,
+				mime_type: null,
+				ctime: now,
+				mtime: fsInfo.mtimeMs
+			});
+			added++;
+		} else if (fsInfo.size !== dbEntry.size || fsInfo.mtimeMs !== dbEntry.mtime) {
+			const cid = await computeCidWithCache(metadataDb, fsInfo.absPath, fsInfo.size, fsInfo.mtimeMs);
+			toUpsert.push({
+				...dbEntry,
+				cid,
+				size: fsInfo.size,
+				mtime: fsInfo.mtimeMs
+			});
+			modified++;
+		} else unchanged++;
+	}
+	for (const [dbPath] of dbMap) if (!fsMap.has(dbPath)) toDelete.push(dbPath);
+	const reconcileOpts = { deviceId: "desktop:default" };
+	if (toUpsert.length > 0) for (let i = 0; i < toUpsert.length; i += 500) await metadataDb.upsertEntries(toUpsert.slice(i, i + 500), reconcileOpts);
+	for (const path of toDelete) await metadataDb.deleteEntry(scope, path, reconcileOpts);
+	return {
+		added,
+		modified,
+		unchanged,
+		deleted: toDelete.length,
+		elapsed: Date.now() - start
+	};
+}
+/**
+* Get CID for a file — use cid_cache if mtime+size match, else compute and cache.
+*/
+async function computeCidWithCache(metadataDb, absPath, size, mtimeMs) {
+	const cached = await metadataDb.getCidCache(absPath);
+	if (cached && cached.mtime_ms === mtimeMs && cached.size === size) return cached.cid;
+	let content;
+	try {
+		const buf = (0, node_fs.readFileSync)(absPath);
+		content = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+	} catch {
+		content = new Uint8Array(0);
+	}
+	const cid = await require_cid.computeCID(content);
+	await metadataDb.setCidCache({
+		path: absPath,
+		cid,
+		size,
+		mtime_ms: mtimeMs,
+		computed_at: Date.now()
+	});
+	return cid;
+}
+
+//#endregion
+exports.reconcile = reconcile;

package/dist/reconcile.d.cts

@@ -0,0 +1,26 @@
+import { MetadataDB } from "./metadata-db.cjs";
+
+//#region src/reconcile.d.ts
+interface ReconcileOptions {
+  /** Root directory of the user's DID space (e.g. ~/.afs/spaces/{userDid}/) */
+  rootPath: string;
+  /** userDid used as scope in the entries table */
+  scope: string;
+  /** MetadataDB instance (already opened) */
+  metadataDb: MetadataDB;
+}
+interface ReconcileStats {
+  added: number;
+  modified: number;
+  unchanged: number;
+  deleted: number;
+  elapsed: number;
+}
+/**
+ * Reconcile the local filesystem against _metadata.db.
+ * Returns stats about the reconcile operation.
+ */
+declare function reconcile(options: ReconcileOptions): Promise<ReconcileStats>;
+//#endregion
+export { ReconcileOptions, ReconcileStats, reconcile };
+//# sourceMappingURL=reconcile.d.cts.map

package/dist/reconcile.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.cts","names":[],"sources":["../src/reconcile.ts"],"mappings":";;;UAwBiB,gBAAA;EAWf;EATA,QAAA;EAWA;EATA,KAAA;EAUO;EARP,UAAA,EAAY,UAAA;AAAA;AAAA,UAGG,cAAA;EACf,KAAA;EACA,QAAA;EACA,SAAA;EACA,OAAA;EACA,OAAA;AAAA;;;;;iBAiHoB,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,cAAA"}

package/dist/reconcile.d.mts

@@ -0,0 +1,26 @@
+import { MetadataDB } from "./metadata-db.mjs";
+
+//#region src/reconcile.d.ts
+interface ReconcileOptions {
+  /** Root directory of the user's DID space (e.g. ~/.afs/spaces/{userDid}/) */
+  rootPath: string;
+  /** userDid used as scope in the entries table */
+  scope: string;
+  /** MetadataDB instance (already opened) */
+  metadataDb: MetadataDB;
+}
+interface ReconcileStats {
+  added: number;
+  modified: number;
+  unchanged: number;
+  deleted: number;
+  elapsed: number;
+}
+/**
+ * Reconcile the local filesystem against _metadata.db.
+ * Returns stats about the reconcile operation.
+ */
+declare function reconcile(options: ReconcileOptions): Promise<ReconcileStats>;
+//#endregion
+export { ReconcileOptions, ReconcileStats, reconcile };
+//# sourceMappingURL=reconcile.d.mts.map

package/dist/reconcile.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.mts","names":[],"sources":["../src/reconcile.ts"],"mappings":";;;UAwBiB,gBAAA;EAWf;EATA,QAAA;EAWA;EATA,KAAA;EAUO;EARP,UAAA,EAAY,UAAA;AAAA;AAAA,UAGG,cAAA;EACf,KAAA;EACA,QAAA;EACA,SAAA;EACA,OAAA;EACA,OAAA;AAAA;;;;;iBAiHoB,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,cAAA"}