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

package/dist/tree-index.d.mts

@@ -0,0 +1,524 @@
+import { TreeQueryResult, TreeQuerySpec } from "./tree-query.mjs";
+import { DirtyPathRow, ListDirtyPathOptions } from "./dirty-path-queue.mjs";
+
+//#region src/tree-index.d.ts
+interface TreeEntry {
+  cid: string;
+  size: number;
+  mtime: number;
+  ctime: number;
+  mimeType?: string;
+  /**
+   * Inline copy of the entry's bytes (Layer 0 inline-content capability, see
+   * `inline-content.ts`). cid-verified: when present, `hash(content) === cid`
+   * holds — the cid stays the identity; content is a co-located copy.
+   *
+   * On `put`: an index constructed with `inlineCache: "on"` stores text
+   * content ≤ its threshold (verified against cid, mismatch rejected);
+   * default-off indexes ignore the field (byte-identical legacy behavior).
+   * Passing NO content on overwrite clears any prior inline copy — the
+   * column can never go stale relative to the cid.
+   *
+   * On reads: `get` returns it when stored; `listEntries`/`listChildren`
+   * include it ONLY under `{ includeContent: true }` (default projection
+   * stays content-free).
+   */
+  content?: string;
+  /**
+   * Application metadata (planning/agent-hub/metadata-foundation.md).
+   * Stores `AFSWriteEntryPayload.meta` — application-level dimension
+   * fields the application uses for collection-query `meta.*` paths.
+   *
+   * Provider-computed fields (`kind / size / cid / mimeType`) are NOT in
+   * here — they live in their own TreeEntry properties / columns and the
+   * provider merges them on top at read time.
+   *
+   * On `put`: persisted as a JSON blob to the `entries.metadata` column.
+   * Undefined / empty object → stored as NULL.
+   *
+   * On reads: returned exactly as written (after provider-reserved fields
+   * are stripped by the application-layer write path).
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Dedup-on-write secondary-index columns (#1159). Together they back the
+   * `(scope, dedup_scope, dedup_key)` partial UNIQUE index that resolves a
+   * dedup write to at-most-one entry — replacing the old cid-in-path scheme.
+   *
+   * - `dedupScope`: the COLLECTION the record dedups within (the write `path`
+   *   argument, e.g. `user/items`). Decoupled from the row's physical `parent`
+   *   so a flat `{coll}/{uuid}.json` and a legacy dir-per-record
+   *   `{coll}/{uuid}/item.json` dedup against the SAME scope.
+   * - `dedupKey`: the normalized identity value (e.g. `normalizeItemUrl(url)`).
+   *
+   * Set ONLY by the provider's dedup write path (and the reindex seam); a plain
+   * write leaves them undefined. On overwrite the SQL upserts COALESCE the
+   * existing value when the incoming entry omits them, so a non-dedup edit of a
+   * dedup row never drops it out of the index.
+   */
+  dedupScope?: string;
+  dedupKey?: string;
+}
+interface TreeIndexListOptions {
+  limit?: number;
+  cursor?: string;
+  /**
+   * Include each entry's inline `content` (when stored) in the result.
+   * Default OFF — the default SELECT never touches the content column, so
+   * every existing list path is zero-regression, zero extra bytes. Entries
+   * without an inline copy come back without `content` (best-effort).
+   */
+  includeContent?: boolean;
+  /**
+   * Sort column. `name` is `listChildren`'s historical hardcoded default,
+   * now explicit (the `entries` table has a `name` column, so `list` /
+   * `listEntries` map it naturally too).
+   *
+   * Semantics when set (all three impls, enforced by
+   * `test/tree-index-order.test.ts`):
+   * - tiebreak on the listing's unique key (`name` for `listChildren`,
+   *   `path` for `list`/`listEntries`), same direction;
+   * - missing values (NULL `mime_type`) sort LAST regardless of direction;
+   * - the resume cursor is the keyset v2 format (`v2:<b64>:<b64>`, see
+   *   {@link buildKeysetCursor}) so duplicate sort values never skip rows
+   *   across a page boundary;
+   * - a legacy (non-v2) cursor combined with `orderBy` is rejected.
+   *
+   * When UNSET the listing keeps its historical byte-identical behavior:
+   * `listChildren` orders by `name` with a plain name-string cursor;
+   * `list`/`listEntries` order by `path` with a plain sort-value cursor.
+   */
+  orderBy?: "path" | "mtime" | "size" | "ctime" | "mimeType" | "name";
+  order?: "asc" | "desc";
+}
+/** Decoded keyset cursor: the last row's sort value + unique tiebreak value. */
+interface TreeKeysetCursor {
+  /** Raw sort-column value of the last row; `null` for NULL (missing) values. */
+  sortValue: string | number | null;
+  /** Unique tiebreak value of the last row (`name` or `path`). */
+  tie: string;
+}
+/** Build a v2 keyset cursor: `v2:<b64(json(sortValue))>:<b64(tie)>`. */
+declare function buildKeysetCursor(sortValue: string | number | null, tie: string): string;
+type ParsedTreeCursor = {
+  kind: "none";
+} | {
+  kind: "legacy";
+  value: string;
+} | {
+  kind: "v2";
+  cursor: TreeKeysetCursor;
+};
+/**
+ * Parse a list cursor. Shared by all three TreeIndex impls so the
+ * legacy-vs-v2 dance can never drift between them.
+ *
+ * - undefined → none
+ * - `v2:`-prefixed → keyset cursor; REQUIRES `hasOrderBy` (a keyset cursor
+ *   replayed onto a default-order listing would be a wrong page); malformed
+ *   payloads throw a clean error instead of producing a wrong page.
+ * - anything else → legacy plain cursor, accepted ONLY for default
+ *   (no-orderBy) order.
+ */
+declare function parseTreeCursor(cursor: string | undefined, hasOrderBy: boolean): ParsedTreeCursor;
+/** SQL fragments for an ordered, keyset-resumable listing. */
+interface OrderedQueryParts {
+  /** Extra WHERE condition (empty string when no cursor). */
+  cursorWhereSql: string;
+  cursorArgs: Array<string | number>;
+  /** ORDER BY clause body (without the `ORDER BY` keyword). */
+  orderSql: string;
+}
+/**
+ * Build the ORDER BY + keyset-resume WHERE for an ordered listing. Shared
+ * by SQLiteTreeIndex and D1TreeIndex (identical SQL dialect).
+ *
+ * - Missing values sort LAST regardless of direction: nullable columns get
+ *   a leading `(col IS NULL) ASC` term. Non-nullable columns skip it so the
+ *   `(scope, parent, col, name)` indexes stay usable.
+ * - Resume uses the expansion `col > ? OR (col = ? AND tie > ?)` (row-value
+ *   free — works on every SQLite the runtimes target) plus NULL-run
+ *   handling for nullable columns.
+ */
+declare function buildOrderedQueryParts(opts: {
+  col: string;
+  nullable: boolean;
+  order: "asc" | "desc";
+  tieCol: string;
+  cursor?: TreeKeysetCursor;
+}): OrderedQueryParts;
+/**
+ * In-memory equivalents of the SQL ordering semantics, used by
+ * MemoryTreeIndex so all three impls stay in lockstep.
+ */
+declare function compareTreeSortValues(a: string | number | null, b: string | number | null, order: "asc" | "desc"): number;
+/** Keyset predicate mirroring {@link buildOrderedQueryParts}'s WHERE. */
+declare function keysetAfter(rowSort: string | number | null, rowTie: string, cursor: TreeKeysetCursor, order: "asc" | "desc"): boolean;
+interface TreeIndexListResult {
+  entries: Array<{
+    path: string;
+  }>;
+  hasMore: boolean;
+  cursor?: string;
+}
+interface TreeIndexListEntriesResult {
+  entries: Array<{
+    path: string;
+  } & TreeEntry>;
+  hasMore: boolean;
+  cursor?: string;
+}
+/**
+ * Options for mutation methods (Task 2.4a — atomic changelog write).
+ *
+ * Every put/delete/putBatch/deleteByPrefix call carries:
+ *   - `deviceId`: opaque per-device identifier persisted into the changelog row.
+ *                 Required, non-empty, ≤ 128 bytes. Validated at runtime by
+ *                 `validateDeviceId()` in `changelog-write.ts`.
+ *   - `skipChangelog`: when `true`, the underlying TreeIndex writes the `entries`
+ *                 row but skips the corresponding `changelog` INSERT. Used by
+ *                 Task 2.4b to exempt blocklet-publish CLI uploads (the publish
+ *                 flow is already batched and does not need per-file sync fan-out).
+ *
+ * Strict-TypeScript design: `opts` is a REQUIRED trailing parameter on every
+ * mutation method (see `tree-index.ts`). Callers that go through the `TreeIndex`
+ * interface (e.g. `CloudflareDIDSpace`, `DIDSpaceProvider`) get a compile-time
+ * error if they omit `opts` — that is the enforcement point for Phase 2 sync.
+ */
+interface PutOpts {
+  /** Required. Non-empty string ≤ 128 bytes. Written into `changelog.device_id`. */
+  deviceId: string;
+  /**
+   * Optional client mtime (unix millis) written into `changelog.mtime` for
+   * delete/deleteByPrefix rows (T1.5). When absent, implementations fall back to
+   * the server clock (`Date.now()`). `put` carries its mtime via the `TreeEntry`,
+   * so this only affects the delete paths where there is no entry to read it from.
+   */
+  mtime?: number;
+  /** When `true`, skip the `changelog` INSERT. Default `false`. */
+  skipChangelog?: boolean;
+}
+/**
+ * In-memory shape of a `changelog` row.
+ *
+ * Matches the D1/libsql row shape 1:1 so MemoryTreeIndex tests can assert
+ * against the same fields that production code will see on the wire. Exposed
+ * via `MemoryTreeIndex.getChangelogSnapshot()` for unit tests.
+ */
+interface ChangelogEntry {
+  /** Monotonically increasing row ID (1-based in MemoryTreeIndex; AUTOINCREMENT in D1). */
+  seq: number;
+  scope: string;
+  path: string;
+  op: "put" | "delete";
+  /** `null` on delete rows; non-null on put rows. */
+  cid: string | null;
+  /** `null` on first write; prior cid on overwrite/delete. */
+  old_cid: string | null;
+  /** `null` on delete rows; file size on put rows. */
+  size: number | null;
+  mtime: number;
+  device_id: string;
+}
+/** Per-entry options for the batch sync fast path. */
+interface BatchEntryOpts {
+  /** Required. Written into `changelog.device_id` (echo prevention / LWW). */
+  deviceId: string;
+  /** Client mtime for DELETE changelog rows (put rows take mtime from the entry). */
+  mtime?: number;
+  /** Optimistic-concurrency precondition against the current entry cid. */
+  ifMatch?: string;
+}
+interface BatchPutEntry {
+  path: string;
+  entry: TreeEntry;
+  opts: BatchEntryOpts;
+}
+interface BatchDeleteEntry {
+  path: string;
+  opts: BatchEntryOpts;
+}
+/** Conflict triple — mirrors the single-op AFSConflictError fields
+ *  (deviceId is null, exactly like the single write path which never reads it). */
+interface BatchEntryConflict {
+  currentCid: string | null;
+  currentMtime: number | null;
+  currentDeviceId: string | null;
+}
+interface BatchPutEntryResult {
+  path: string;
+  /** Prior cid when the path existed (drives the caller's GC enqueue). */
+  oldCid?: string;
+  /** Skip-if-unchanged hit: same cid+mimeType — no changelog row, no watermark bump. */
+  skipped?: boolean;
+  /** Present iff the entry failed its ifMatch precondition (nothing written). */
+  conflict?: BatchEntryConflict;
+  /** Non-conflict per-entry failure (e.g. quota) — message parity with single put. */
+  error?: string;
+  /**
+   * Stable code for a non-conflict failure (upload-limits Phase 5):
+   * `STORAGE_QUOTA_EXCEEDED` on a file-count OR byte-quota rejection. Lets a
+   * consumer distinguish quota from other per-entry errors (the single-put path
+   * carries it on the thrown Error's `.code`).
+   */
+  code?: string;
+  /** This entry's own watermark seq (+1 per write, batch-order ascending).
+   *  Absent for skip/conflict/error entries and root-level paths (no collection root). */
+  liveSeq?: number;
+}
+interface BatchDeleteEntryResult {
+  path: string;
+  /** The deleted entry's cid (drives the caller's GC enqueue). */
+  deletedCid?: string;
+  /** Path had no file entry — per-entry not-found, never aborts neighbors. */
+  notFound?: boolean;
+  conflict?: BatchEntryConflict;
+  error?: string;
+  liveSeq?: number;
+}
+/** Shared context: a caller-supplied preread snapshot (one IN query reused
+ *  across the provider's preflight AND the index batch — design §4.3). */
+interface BatchIndexContext {
+  preread?: Map<string, TreeEntry | null>;
+}
+interface TreeIndex {
+  /**
+   * Read a single file's metadata. `includeContent` (default true) projects the
+   * inline `content` copy; metadata-only callers (stat / list / readMeta) pass
+   * `false` to skip marshalling the inline bytes. A projection hint — an
+   * in-memory backend may still return content (zero marshalling cost there).
+   */
+  get(path: string, opts?: {
+    includeContent?: boolean;
+  }): Promise<TreeEntry | null>;
+  /**
+   * Read a directory row's own `ctime`/`mtime`. Directory rows are scaffolded
+   * by the put path (`ancestorDirs` + `buildDirChainStmt`) with no `cid`, so
+   * {@link get} — which returns null for cid-less rows — never surfaces them.
+   * This is the read used to expose a directory's created/modified time on
+   * `stat` (the file path already returns them via {@link get}).
+   *
+   * `dirPath` is the trailing-slash index key (e.g. `user/photos/`), i.e. the
+   * value {@link treeListPrefix} produces. Returns null for a directory with
+   * no scaffolded row (the absolute scope root, or an as-yet-unwritten dir).
+   *
+   * Optional: callers MUST guard and simply omit the timestamps when an
+   * implementation does not provide it.
+   */
+  getDirTimes?(dirPath: string): Promise<{
+    ctime: number;
+    mtime: number;
+  } | null>;
+  /**
+   * Batch metadata read for the sync fast path's ONE-query preflight
+   * (afs-rpc-batch §4.3). Returns a map with an entry for EVERY requested
+   * path (`null` when absent). Optional: callers fall back to per-path `get`.
+   */
+  getMany?(paths: string[]): Promise<Map<string, TreeEntry | null>>;
+  /**
+   * Batch `get(filePath)` + `hasChildren(dirPrefix)` in a single storage
+   * round-trip. Used by `readHandler` to cut miss-path D1 calls in half:
+   * a non-existent file previously paid `get` + `hasChildren` sequentially
+   * (2 HTTP round-trips); this collapses both into one batch call.
+   * Optional — callers fall back to sequential `get` + `hasChildren` when absent.
+   */
+  getAndHasChildren?(filePath: string, dirPrefix: string): Promise<[TreeEntry | null, boolean]>;
+  /**
+   * Batch sync fast path (afs-rpc-batch P3) — per-entry opts
+   * (deviceId/mtime/ifMatch) and per-entry results (oldCid / skipped /
+   * conflict / liveSeq). Entries arrive with UNIQUE paths (the core splits
+   * duplicate-path batches) so a one-shot preread is serial-equivalent.
+   * Watermark semantics match single `put`: +1 per written entry, each
+   * result carrying its own seq. See the section comment above for why this
+   * is NOT the legacy `putBatch`.
+   */
+  batchPutEntries?(entries: BatchPutEntry[], ctx?: BatchIndexContext): Promise<BatchPutEntryResult[]>;
+  /** Delete twin of {@link batchPutEntries}. FILE entries only (no dir fallback). */
+  batchDeleteEntries?(entries: BatchDeleteEntry[], ctx?: BatchIndexContext): Promise<BatchDeleteEntryResult[]>;
+  /** Write/update file metadata (ctime preserved by implementation). Returns previous CID if entry existed. */
+  put(path: string, entry: TreeEntry, opts: PutOpts): Promise<{
+    oldCid?: string;
+  }>;
+  /**
+   * Dedup-on-write lookup (#1159): resolve the single entry whose
+   * `(dedup_scope, dedup_key)` matches within this scope, or `null`. Backed by
+   * the `(scope, dedup_scope, dedup_key)` partial UNIQUE index → O(log n) point
+   * seek, never a `json_extract` full scan. Returns the entry's REAL path so the
+   * provider can merge into it in place.
+   *
+   * Optional during rollout: a TreeIndex without it makes the owning provider
+   * treat `dedupBy` writes as unsupported (explicit error, never silent).
+   */
+  findByDedupKey?(dedupScope: string, dedupKey: string): Promise<({
+    path: string;
+  } & TreeEntry) | null>;
+  /**
+   * Populate the dedup columns of an EXISTING row WITHOUT rewriting its
+   * content/cid or emitting a changelog row — the one-time reindex/backfill seam
+   * (#1159, deferred script). Index-only UPDATE keyed on `(scope, path)`. No-op
+   * if the path has no row. Optional: reindex callers guard on its presence.
+   */
+  setDedupKey?(path: string, dedupScope: string, dedupKey: string, opts: PutOpts): Promise<void>;
+  /**
+   * Resolve the inline `content` this entry WOULD store under the index's
+   * configured inline policy (or `null` for "store NULL"). Exposed so
+   * {@link loopBatchPutEntries} can mirror D1's content-aware skip — a cid+mime
+   * match whose inline column is out of sync must fall through to `put()` to
+   * self-repair, instead of being early-skipped. Optional: indexes without
+   * inline support omit it and the loop keeps the legacy cid+mime skip.
+   */
+  inlineForEntry?(entry: TreeEntry): Promise<string | null>;
+  /** Delete a single file */
+  delete(path: string, opts: PutOpts): Promise<void>;
+  /** List entries under a prefix (for directory browsing) */
+  list(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListResult>;
+  /** List entries with full metadata under a prefix */
+  listEntries(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  /** Check if prefix has any child entries (directory existence) */
+  hasChildren(prefix: string): Promise<boolean>;
+  /** Count entries under a prefix (exact value) */
+  count(prefix: string): Promise<number>;
+  /** Bulk-delete all entries under a prefix, return count deleted */
+  deleteByPrefix(prefix: string, opts: PutOpts): Promise<number>;
+  /** List direct children of a parent directory (uses parent index) */
+  listChildren(parent: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  /** Count direct children of a parent directory (exact, O(log n)) */
+  countChildren(parent: string): Promise<number>;
+  /**
+   * Count direct children for EACH of the given parent directories in one
+   * round-trip, returned as `Map<parentPath, count>` keyed by the same path
+   * form `listChildren` yields for a directory child (trailing-slash, and —
+   * for {@link PrefixedTreeIndex} — prefix-stripped).
+   *
+   * PAGE-BOUNDED by contract: callers pass only the directories on the page
+   * being listed, so the cost is Σ direct children of those dirs. This
+   * replaces the retired subtree-wide `countChildrenGrouped(prefix)`, whose
+   * `parent >= lo AND parent < hi` range scanned EVERY descendant (all
+   * depths) under the listed prefix on every list — ~100M+ D1 rows_read/day
+   * once a hot collection grew to ~1k dirs (2026-06 free-tier exhaustion).
+   *
+   * Optional: callers MUST fall back to per-path {@link countChildren} when
+   * an implementation does not provide it. The returned map omits empty
+   * directories (count 0) — look up with `map.get(path) ?? 0`.
+   */
+  countChildrenMany?(parents: string[]): Promise<Map<string, number>>;
+  /** Get aggregate stats (file count + total size) for a prefix */
+  aggregate(prefix: string): Promise<{
+    fileCount: number;
+    totalSize: number;
+  }>;
+  /** Batch write entries in a transaction */
+  putBatch(entries: Array<{
+    path: string;
+    entry: TreeEntry;
+  }>, opts: PutOpts): Promise<void>;
+  /** List entries modified since a timestamp */
+  listModifiedSince(prefix: string, since: number, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  /**
+   * Return the maximum changelog seq for this scope.
+   * Used by `DIDSpaceProvider.list(path, { maxDepth: -1 })` to include
+   * the snapshot waterline in `meta.cursor`. Returns 0 when the changelog
+   * is empty (no writes have been recorded yet).
+   */
+  getMaxSeq(): Promise<number>;
+  /**
+   * Read the per-prefix watermark `version` for a collection root (Live Update
+   * Resilience §11.4). `prefix` is a scope-relative path; the implementation
+   * reduces it to its first path segment (the `/user` first-level collection
+   * root) and returns that row's `version`, or `0` when no row exists yet
+   * ("nothing written under this collection root").
+   *
+   * This is the O(1) change-detector that web reconcile reads on every
+   * connection edge: it never scans the changelog and never grows with history
+   * or global write volume. Optional during rollout — a TreeIndex without it
+   * leaves the owning provider unable to emit `liveSeq` (consumer falls back to
+   * full re-list on every edge/poll, still correct).
+   *
+   * Tri-state return:
+   * - `null`  — the path has no collection root (no watermark key): the owner
+   *   emits NO `liveSeq`, consumers stay on the conservative full-refetch path.
+   * - `0`     — valid collection root with no writes yet: the owner emits
+   *   `liveSeq: "0"` so consumers baseline at 0 and DON'T refetch every poll
+   *   tick on a read-only collection (the first write bumps to 1 > 0).
+   * - `>0`    — the row's version.
+   */
+  getPrefixWatermark?(prefix: string): Promise<number | null>;
+  /**
+   * Return changelog rows with `seq > sinceSeq` (ascending), capped at `limit`.
+   *
+   * `cursor` is the highest **inner** seq this scan observed — NOT the seq of
+   * the last returned entry. This distinction matters for {@link
+   * PrefixedTreeIndex}: when a prefix filter drops every row on a page, the page
+   * returns `entries: []` but `cursor` still advances to the max inner seq so
+   * the caller never re-requests the same window (no infinite loop on empty
+   * pages). `hasMore` follows the inner pagination ("are there more inner rows
+   * with seq > cursor"), not "are there more rows under this prefix".
+   *
+   * On an empty changelog (or no rows past `sinceSeq`) returns
+   * `{ entries: [], hasMore: false, cursor: sinceSeq }` — cursor never goes
+   * backwards.
+   */
+  getChangelogSince(sinceSeq: number, limit: number): Promise<{
+    entries: ChangelogEntry[];
+    hasMore: boolean;
+    cursor: number;
+  }>;
+  /**
+   * Compaction watermark for this scope (Phase 1 of changelog compaction).
+   * Returns 0 when no compaction has ever run (safe permissive default).
+   */
+  getCompactedBelowSeq?(): Promise<number>;
+  /**
+   * Collection query over DIRECT children of `parent` (afs-collection-query
+   * Phase 1, design §3.5): typed where σ on the record document (doc-joined
+   * for dir-per-record, inline content for file-per-record), entry-column
+   * orderBy, exact post-WHERE total, keyset/offset pagination, groupBy
+   * counting. Spec semantics are locked to the core reference evaluator by
+   * conformance + the cross-backend lockstep test (`tree-query.ts`).
+   *
+   * Optional during rollout: implementations without it leave the owning
+   * provider undeclared (the root action then fails AFS_UNSUPPORTED).
+   */
+  query?(parent: string, spec: TreeQuerySpec): Promise<TreeQueryResult>;
+  /**
+   * True if `cid` is referenced within THIS index's VIEW (read-**auth**,
+   * design §4.1) — three-way `entries.cid ∪ changelog.cid ∪ changelog.old_cid`,
+   * always `WHERE scope = ?`.
+   *
+   * `pathPrefix` (default `""`) restricts the check to a sub-tree
+   * (`path >= lo AND path < hi`). {@link PrefixedTreeIndex} passes its own
+   * prefix so a blocklet/role provider authorizes ONLY cids its own fragment
+   * references (P0#2 blocklet isolation); the unprefixed space-root provider
+   * leaves it `""` and stays whole-scope.
+   *
+   * This is the authorization check, distinct from the scope-blind,
+   * entries-only GC-liveness check `referencedAnywhere` (design §3, §4.4b).
+   * Returns false for empty `cid`.
+   */
+  isReferenced(cid: string, pathPrefix?: string): Promise<boolean>;
+  /**
+   * Batch read-auth (download plane, design §7.2): given a set of cids, return
+   * the SUBSET that is referenced within THIS index's VIEW — exactly the cids
+   * for which {@link isReferenced} would return `true`. A cid NOT in the result
+   * is `forbidden` (covers both unreferenced AND not-found — never distinguish).
+   *
+   * MUST be three-way-equivalent to per-cid `isReferenced`
+   * (`entries.cid ∪ changelog.cid ∪ changelog.old_cid`, scope-aware, optionally
+   * prefix-local) — a superseded cid that left `entries` but lives in
+   * `changelog.old_cid` MUST still be returned, or the read-auth invariant
+   * breaks (design Finding 2). The SQL backends shard the `IN (?,…)` list to
+   * stay under the bound-parameter cap (D1 = 100; the three-way UNION binds each
+   * cid 3×, so the per-query cid budget is small). Empty input → empty set, no
+   * query (avoid `IN ()`).
+   */
+  isReferencedMany(cids: string[], pathPrefix?: string): Promise<Set<string>>;
+  /** Ready dirty rows under `prefix` with `next_attempt_at <= now`, capped at `limit`. */
+  listDirtyPaths?(options: ListDirtyPathOptions): Promise<DirtyPathRow[]>;
+  /** Guarded ack: delete the dirty row iff its `latest_seq` still equals `latestSeq`. */
+  ackDirtyPath?(path: string, latestSeq: number): Promise<boolean>;
+  /** Guarded failure record: bump attempts + set last_error/next_attempt_at on the matching row. */
+  markDirtyPathError?(path: string, latestSeq: number, error: string, nextAttemptAt: number): Promise<boolean>;
+}
+//#endregion
+export { BatchDeleteEntry, BatchDeleteEntryResult, BatchIndexContext, BatchPutEntry, BatchPutEntryResult, ChangelogEntry, OrderedQueryParts, ParsedTreeCursor, PutOpts, TreeEntry, TreeIndex, TreeIndexListEntriesResult, TreeIndexListOptions, TreeIndexListResult, TreeKeysetCursor, buildKeysetCursor, buildOrderedQueryParts, compareTreeSortValues, keysetAfter, parseTreeCursor };
+//# sourceMappingURL=tree-index.d.mts.map

package/dist/tree-index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-index.d.mts","names":[],"sources":["../src/tree-index.ts"],"mappings":"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"}