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

package/dist/d1-tree-index.d.cts

@@ -0,0 +1,203 @@
+import { TreeQueryResult, TreeQuerySpec } from "./tree-query.cjs";
+import { DirtyPathRow, ListDirtyPathOptions } from "./dirty-path-queue.cjs";
+import { BatchDeleteEntry, BatchDeleteEntryResult, BatchIndexContext, BatchPutEntry, BatchPutEntryResult, ChangelogEntry, PutOpts, TreeEntry, TreeIndex, TreeIndexListEntriesResult, TreeIndexListOptions, TreeIndexListResult } from "./tree-index.cjs";
+import { InlineContentOptions } from "./inline-content.cjs";
+import { prefixRange } from "./prefix-range.cjs";
+
+//#region src/d1-tree-index.d.ts
+/** Extract parent directory path from a file/dir path */
+declare function parentOf(path: string): string;
+/** Extract basename from a file/dir path */
+declare function nameOf(path: string): string;
+/** Collect all ancestor directory paths from a file path (deepest first) */
+declare function ancestorDirs(path: string): string[];
+/** Maximum file entries per scope (files only, excludes dirs) */
+declare const MAX_ENTRIES_PER_SCOPE = 1000000;
+declare class D1TreeIndex implements TreeIndex {
+  private db;
+  private scope;
+  private readonly conn;
+  private readonly maxEntriesPerScope;
+  /** upload-limits Phase 5 byte quota (0 = disabled, the opt-in default). */
+  private readonly maxBytesPerScope;
+  private readonly inline;
+  constructor(db: D1Database, scope: string, opts?: {
+    useReplica?: boolean;
+    maxEntriesPerScope?: number;
+    maxBytesPerScope?: number;
+  } & InlineContentOptions);
+  /**
+   * Create entries table + indexes (v2 schema) AND the Phase 2 changelog table.
+   * Production: schema created by `wrangler d1 migrations apply`.
+   * Tests: call this in beforeEach with in-memory DB.
+   *
+   * Changelog DDL is sourced from `changelog-schema.ts` to keep the four
+   * runtimes (D1, desktop, Swift, Kotlin) byte-equivalent — see
+   * `scripts/check-changelog-ddl-parity.ts`. Schema-only here; producers come
+   * online in Task 2.4.
+   */
+  ensureTable(): Promise<void>;
+  get(path: string, opts?: {
+    includeContent?: boolean;
+  }): Promise<TreeEntry | null>;
+  getDirTimes(dirPath: string): Promise<{
+    ctime: number;
+    mtime: number;
+  } | null>;
+  /** Inline content this entry would store — parity with the loop reference impl. */
+  inlineForEntry(entry: TreeEntry): Promise<string | null>;
+  /** Point seek on the `(scope, dedup_scope, dedup_key)` partial UNIQUE index. */
+  findByDedupKey(dedupScope: string, dedupKey: string): Promise<({
+    path: string;
+  } & TreeEntry) | null>;
+  /** Index-only backfill: set the dedup columns without touching content/changelog. */
+  setDedupKey(path: string, dedupScope: string, dedupKey: string, opts: PutOpts): Promise<void>;
+  /**
+   * Batch metadata read — one chunked `IN (…)` query per ≤90 paths (D1's
+   * 100-bind limit minus the scope bind, design §4.3). Result map carries an
+   * entry for EVERY requested path (`null` when absent), keyed verbatim.
+   */
+  getMany(paths: string[]): Promise<Map<string, TreeEntry | null>>;
+  /**
+   * Merged batch put (afs-rpc-batch §4.3 / §6.3) — the CF subrequest-budget
+   * fast path: ONE preread (caller-supplied or chunked IN), ONE capacity
+   * read, ONE atomic `db.batch` carrying every surviving entry's
+   * changelog+upsert (+1 watermark bump per write), then ONE watermark
+   * readback per distinct collection root to attribute per-entry seqs
+   * (`liveSeq[i] = final − N + 1 + i`, skip/conflict entries take no seq).
+   *
+   * Statement order inside the batch mirrors single `put`: dirs first, then
+   * per entry changelog INSERT (correlated old_cid subquery reads the
+   * pre-upsert cid) BEFORE its upsert — D1 preserves batch statement order.
+   */
+  batchPutEntries(entries: BatchPutEntry[], ctx?: BatchIndexContext): Promise<BatchPutEntryResult[]>;
+  /**
+   * Merged batch delete — same shape as {@link batchPutEntries} without the
+   * R2 leg: ONE preread, ONE atomic `db.batch` (per entry: changelog INSERT
+   * SELECT + file_count decrement + DELETE, +1 watermark bump), then empty-
+   * parent cleanup over the DISTINCT ancestor chain. FILE entries only.
+   */
+  batchDeleteEntries(entries: BatchDeleteEntry[], ctx?: BatchIndexContext): Promise<BatchDeleteEntryResult[]>;
+  put(path: string, entry: TreeEntry, opts: PutOpts): Promise<{
+    oldCid?: string;
+  }>;
+  /**
+   * Build the file-row UPSERT. Inline-enabled indexes always write the
+   * content column (inline copy or NULL — an overwrite without inline content
+   * MUST clear any prior copy so the column never goes stale relative to the
+   * new cid); default-off indexes keep the byte-identical legacy statement
+   * (and never touch a not-yet-migrated database's missing column).
+   */
+  private buildFileUpsert;
+  delete(path: string, opts: PutOpts): Promise<void>;
+  /** Walk up parent chain, removing directory entries that have no remaining children */
+  private cleanEmptyParents;
+  private static readonly VALID_ORDER_BY;
+  /** The only nullable sortable column — NULLs sort last (see tree-index.ts). */
+  private static readonly NULLABLE_ORDER_COLUMNS;
+  list(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListResult>;
+  listEntries(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  hasChildren(prefix: string): Promise<boolean>;
+  getAndHasChildren(filePath: string, dirPrefix: string): Promise<[TreeEntry | null, boolean]>;
+  count(prefix: string): Promise<number>;
+  /**
+   * O(1) read of the trigger-maintained file count for this scope, used by the
+   * `put()` capacity guard. A missing `scope_meta` row means "no files counted
+   * yet" → 0, which is also the correct answer for a brand-new scope and the
+   * safe (permissive) fallback for a scope not yet backfilled. This replaces
+   * the per-write full-scope `count("")` scan — the source of the O(N²)
+   * `rows_read` blow-up that exhausted the D1 free tier during bulk sync.
+   */
+  private getScopeFileCount;
+  /**
+   * O(1) read of the trigger-maintained byte total for this scope, used by the
+   * Phase 5 byte-quota guard (only when `maxBytesPerScope > 0`). Same O(1)
+   * contract as {@link getScopeFileCount} — never a `SELECT SUM(size)` scan.
+   * Missing row → 0 (new/un-backfilled scope; permissive).
+   */
+  private getScopeTotalBytes;
+  getCompactedBelowSeq(): Promise<number>;
+  deleteByPrefix(prefix: string, opts: PutOpts): Promise<number>;
+  listChildren(parent: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  countChildren(parent: string): Promise<number>;
+  /**
+   * Collection query (afs-collection-query Phase 2) — same shared compiler +
+   * result builder as SQLiteTreeIndex (tree-query.ts), executed over the
+   * replica-aware `this.conn`: query is read-class and follows the SAME
+   * replica routing policy as list (AFS_D1_READ_REPLICA gate upstream picks
+   * the session; no separate consistency standard — design T2.1).
+   */
+  query(parent: string, spec: TreeQuerySpec): Promise<TreeQueryResult>;
+  /**
+   * Page-bounded grouped child counts: ONE chunked `parent IN (…)` aggregate
+   * per ≤90 parents (D1's 100-bind limit minus the scope bind — same chunking
+   * as `getMany`), index-only seeks on `idx_entries_children(scope, parent,
+   * name)`. rows_read is bounded by the listed page's direct grandchildren.
+   *
+   * Predecessor (`countChildrenGrouped(prefix)`) used a `parent >= lo AND
+   * parent < hi` range — a scan/group over EVERY descendant under the listed
+   * prefix on EVERY list. Once the aside user space grew to ~1.8k dirs, each
+   * list of any ancestor dir read ~3.8k rows; at list frequency that burned
+   * ~100M D1 rows_read/day (42× the free tier).
+   */
+  countChildrenMany(parents: string[]): Promise<Map<string, number>>;
+  aggregate(prefix: string): Promise<{
+    fileCount: number;
+    totalSize: number;
+  }>;
+  putBatch(entries: Array<{
+    path: string;
+    entry: TreeEntry;
+  }>, opts: PutOpts): Promise<void>;
+  /**
+   * Read the per-prefix watermark version (Live Update Resilience §11.4).
+   * Reduces `prefix` to its first path segment (collection root) and returns
+   * that row's `version`, or 0 when no row exists. Replica-aware via `this.conn`
+   * — but reconcile passes a primary-pinned index for read-your-watermark
+   * (DEC-5; see CloudflareDIDSpace.getInstanceSpace consistency option).
+   */
+  getPrefixWatermark(prefix: string): Promise<number | null>;
+  listModifiedSince(prefix: string, since: number, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  getMaxSeq(): Promise<number>;
+  /**
+   * Read-auth reference check (design §4.1) — three-way, scoped, optionally
+   * prefix-local. See {@link TreeIndex.isReferenced}.
+   */
+  isReferenced(cid: string, pathPrefix?: string): Promise<boolean>;
+  /**
+   * Batch read-auth (design §7.2 / §14) — three-way-equivalent to per-cid
+   * {@link isReferenced}, sharded under D1's 100-param cap (see
+   * {@link D1_MANY_SHARD_SIZE}). Returns the referenced subset of `cids`.
+   */
+  isReferencedMany(cids: string[], pathPrefix?: string): Promise<Set<string>>;
+  getChangelogSince(sinceSeq: number, limit: number): Promise<{
+    entries: ChangelogEntry[];
+    hasMore: boolean;
+    cursor: number;
+  }>;
+  /**
+   * Ready dirty rows under `prefix` for this scope. `next_attempt_at <= now`
+   * skips poison rows still in backoff; the `(scope, next_attempt_at,
+   * updated_at)` index serves the ordered seek. Reads go through `this.conn`, so
+   * a follower constructed primary-bound (`useReplica:false`, Phase 3) gets
+   * read-your-write; a replica-routed instance would return replica state — the
+   * runtime is responsible for pinning primary for the dirty follower.
+   */
+  listDirtyPaths(options: ListDirtyPathOptions): Promise<DirtyPathRow[]>;
+  /**
+   * Guarded ack (design §8): delete the dirty row ONLY if its `latest_seq` is
+   * still the one we processed. A concurrent write bumps latest_seq (trigger),
+   * so a stale worker's DELETE affects 0 rows → returns false, and the newer
+   * dirty row survives for the next tick. Writes go to primary (`this.db`).
+   */
+  ackDirtyPath(path: string, latestSeq: number): Promise<boolean>;
+  /**
+   * Guarded failure record (design §8): bump attempts, stamp last_error +
+   * next_attempt_at, SAME `latest_seq` guard so a fresh write's reset (trigger
+   * sets attempts=0) is never clobbered by a late error from the prior attempt.
+   */
+  markDirtyPathError(path: string, latestSeq: number, error: string, nextAttemptAt: number): Promise<boolean>;
+}
+//#endregion
+export { D1TreeIndex, MAX_ENTRIES_PER_SCOPE, ancestorDirs, nameOf, parentOf };
+//# sourceMappingURL=d1-tree-index.d.cts.map

package/dist/d1-tree-index.d.cts.map

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

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

@@ -0,0 +1,203 @@
+import { TreeQueryResult, TreeQuerySpec } from "./tree-query.mjs";
+import { DirtyPathRow, ListDirtyPathOptions } from "./dirty-path-queue.mjs";
+import { BatchDeleteEntry, BatchDeleteEntryResult, BatchIndexContext, BatchPutEntry, BatchPutEntryResult, ChangelogEntry, PutOpts, TreeEntry, TreeIndex, TreeIndexListEntriesResult, TreeIndexListOptions, TreeIndexListResult } from "./tree-index.mjs";
+import { InlineContentOptions } from "./inline-content.mjs";
+import { prefixRange } from "./prefix-range.mjs";
+
+//#region src/d1-tree-index.d.ts
+/** Extract parent directory path from a file/dir path */
+declare function parentOf(path: string): string;
+/** Extract basename from a file/dir path */
+declare function nameOf(path: string): string;
+/** Collect all ancestor directory paths from a file path (deepest first) */
+declare function ancestorDirs(path: string): string[];
+/** Maximum file entries per scope (files only, excludes dirs) */
+declare const MAX_ENTRIES_PER_SCOPE = 1000000;
+declare class D1TreeIndex implements TreeIndex {
+  private db;
+  private scope;
+  private readonly conn;
+  private readonly maxEntriesPerScope;
+  /** upload-limits Phase 5 byte quota (0 = disabled, the opt-in default). */
+  private readonly maxBytesPerScope;
+  private readonly inline;
+  constructor(db: D1Database, scope: string, opts?: {
+    useReplica?: boolean;
+    maxEntriesPerScope?: number;
+    maxBytesPerScope?: number;
+  } & InlineContentOptions);
+  /**
+   * Create entries table + indexes (v2 schema) AND the Phase 2 changelog table.
+   * Production: schema created by `wrangler d1 migrations apply`.
+   * Tests: call this in beforeEach with in-memory DB.
+   *
+   * Changelog DDL is sourced from `changelog-schema.ts` to keep the four
+   * runtimes (D1, desktop, Swift, Kotlin) byte-equivalent — see
+   * `scripts/check-changelog-ddl-parity.ts`. Schema-only here; producers come
+   * online in Task 2.4.
+   */
+  ensureTable(): Promise<void>;
+  get(path: string, opts?: {
+    includeContent?: boolean;
+  }): Promise<TreeEntry | null>;
+  getDirTimes(dirPath: string): Promise<{
+    ctime: number;
+    mtime: number;
+  } | null>;
+  /** Inline content this entry would store — parity with the loop reference impl. */
+  inlineForEntry(entry: TreeEntry): Promise<string | null>;
+  /** Point seek on the `(scope, dedup_scope, dedup_key)` partial UNIQUE index. */
+  findByDedupKey(dedupScope: string, dedupKey: string): Promise<({
+    path: string;
+  } & TreeEntry) | null>;
+  /** Index-only backfill: set the dedup columns without touching content/changelog. */
+  setDedupKey(path: string, dedupScope: string, dedupKey: string, opts: PutOpts): Promise<void>;
+  /**
+   * Batch metadata read — one chunked `IN (…)` query per ≤90 paths (D1's
+   * 100-bind limit minus the scope bind, design §4.3). Result map carries an
+   * entry for EVERY requested path (`null` when absent), keyed verbatim.
+   */
+  getMany(paths: string[]): Promise<Map<string, TreeEntry | null>>;
+  /**
+   * Merged batch put (afs-rpc-batch §4.3 / §6.3) — the CF subrequest-budget
+   * fast path: ONE preread (caller-supplied or chunked IN), ONE capacity
+   * read, ONE atomic `db.batch` carrying every surviving entry's
+   * changelog+upsert (+1 watermark bump per write), then ONE watermark
+   * readback per distinct collection root to attribute per-entry seqs
+   * (`liveSeq[i] = final − N + 1 + i`, skip/conflict entries take no seq).
+   *
+   * Statement order inside the batch mirrors single `put`: dirs first, then
+   * per entry changelog INSERT (correlated old_cid subquery reads the
+   * pre-upsert cid) BEFORE its upsert — D1 preserves batch statement order.
+   */
+  batchPutEntries(entries: BatchPutEntry[], ctx?: BatchIndexContext): Promise<BatchPutEntryResult[]>;
+  /**
+   * Merged batch delete — same shape as {@link batchPutEntries} without the
+   * R2 leg: ONE preread, ONE atomic `db.batch` (per entry: changelog INSERT
+   * SELECT + file_count decrement + DELETE, +1 watermark bump), then empty-
+   * parent cleanup over the DISTINCT ancestor chain. FILE entries only.
+   */
+  batchDeleteEntries(entries: BatchDeleteEntry[], ctx?: BatchIndexContext): Promise<BatchDeleteEntryResult[]>;
+  put(path: string, entry: TreeEntry, opts: PutOpts): Promise<{
+    oldCid?: string;
+  }>;
+  /**
+   * Build the file-row UPSERT. Inline-enabled indexes always write the
+   * content column (inline copy or NULL — an overwrite without inline content
+   * MUST clear any prior copy so the column never goes stale relative to the
+   * new cid); default-off indexes keep the byte-identical legacy statement
+   * (and never touch a not-yet-migrated database's missing column).
+   */
+  private buildFileUpsert;
+  delete(path: string, opts: PutOpts): Promise<void>;
+  /** Walk up parent chain, removing directory entries that have no remaining children */
+  private cleanEmptyParents;
+  private static readonly VALID_ORDER_BY;
+  /** The only nullable sortable column — NULLs sort last (see tree-index.ts). */
+  private static readonly NULLABLE_ORDER_COLUMNS;
+  list(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListResult>;
+  listEntries(prefix: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  hasChildren(prefix: string): Promise<boolean>;
+  getAndHasChildren(filePath: string, dirPrefix: string): Promise<[TreeEntry | null, boolean]>;
+  count(prefix: string): Promise<number>;
+  /**
+   * O(1) read of the trigger-maintained file count for this scope, used by the
+   * `put()` capacity guard. A missing `scope_meta` row means "no files counted
+   * yet" → 0, which is also the correct answer for a brand-new scope and the
+   * safe (permissive) fallback for a scope not yet backfilled. This replaces
+   * the per-write full-scope `count("")` scan — the source of the O(N²)
+   * `rows_read` blow-up that exhausted the D1 free tier during bulk sync.
+   */
+  private getScopeFileCount;
+  /**
+   * O(1) read of the trigger-maintained byte total for this scope, used by the
+   * Phase 5 byte-quota guard (only when `maxBytesPerScope > 0`). Same O(1)
+   * contract as {@link getScopeFileCount} — never a `SELECT SUM(size)` scan.
+   * Missing row → 0 (new/un-backfilled scope; permissive).
+   */
+  private getScopeTotalBytes;
+  getCompactedBelowSeq(): Promise<number>;
+  deleteByPrefix(prefix: string, opts: PutOpts): Promise<number>;
+  listChildren(parent: string, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  countChildren(parent: string): Promise<number>;
+  /**
+   * Collection query (afs-collection-query Phase 2) — same shared compiler +
+   * result builder as SQLiteTreeIndex (tree-query.ts), executed over the
+   * replica-aware `this.conn`: query is read-class and follows the SAME
+   * replica routing policy as list (AFS_D1_READ_REPLICA gate upstream picks
+   * the session; no separate consistency standard — design T2.1).
+   */
+  query(parent: string, spec: TreeQuerySpec): Promise<TreeQueryResult>;
+  /**
+   * Page-bounded grouped child counts: ONE chunked `parent IN (…)` aggregate
+   * per ≤90 parents (D1's 100-bind limit minus the scope bind — same chunking
+   * as `getMany`), index-only seeks on `idx_entries_children(scope, parent,
+   * name)`. rows_read is bounded by the listed page's direct grandchildren.
+   *
+   * Predecessor (`countChildrenGrouped(prefix)`) used a `parent >= lo AND
+   * parent < hi` range — a scan/group over EVERY descendant under the listed
+   * prefix on EVERY list. Once the aside user space grew to ~1.8k dirs, each
+   * list of any ancestor dir read ~3.8k rows; at list frequency that burned
+   * ~100M D1 rows_read/day (42× the free tier).
+   */
+  countChildrenMany(parents: string[]): Promise<Map<string, number>>;
+  aggregate(prefix: string): Promise<{
+    fileCount: number;
+    totalSize: number;
+  }>;
+  putBatch(entries: Array<{
+    path: string;
+    entry: TreeEntry;
+  }>, opts: PutOpts): Promise<void>;
+  /**
+   * Read the per-prefix watermark version (Live Update Resilience §11.4).
+   * Reduces `prefix` to its first path segment (collection root) and returns
+   * that row's `version`, or 0 when no row exists. Replica-aware via `this.conn`
+   * — but reconcile passes a primary-pinned index for read-your-watermark
+   * (DEC-5; see CloudflareDIDSpace.getInstanceSpace consistency option).
+   */
+  getPrefixWatermark(prefix: string): Promise<number | null>;
+  listModifiedSince(prefix: string, since: number, options?: TreeIndexListOptions): Promise<TreeIndexListEntriesResult>;
+  getMaxSeq(): Promise<number>;
+  /**
+   * Read-auth reference check (design §4.1) — three-way, scoped, optionally
+   * prefix-local. See {@link TreeIndex.isReferenced}.
+   */
+  isReferenced(cid: string, pathPrefix?: string): Promise<boolean>;
+  /**
+   * Batch read-auth (design §7.2 / §14) — three-way-equivalent to per-cid
+   * {@link isReferenced}, sharded under D1's 100-param cap (see
+   * {@link D1_MANY_SHARD_SIZE}). Returns the referenced subset of `cids`.
+   */
+  isReferencedMany(cids: string[], pathPrefix?: string): Promise<Set<string>>;
+  getChangelogSince(sinceSeq: number, limit: number): Promise<{
+    entries: ChangelogEntry[];
+    hasMore: boolean;
+    cursor: number;
+  }>;
+  /**
+   * Ready dirty rows under `prefix` for this scope. `next_attempt_at <= now`
+   * skips poison rows still in backoff; the `(scope, next_attempt_at,
+   * updated_at)` index serves the ordered seek. Reads go through `this.conn`, so
+   * a follower constructed primary-bound (`useReplica:false`, Phase 3) gets
+   * read-your-write; a replica-routed instance would return replica state — the
+   * runtime is responsible for pinning primary for the dirty follower.
+   */
+  listDirtyPaths(options: ListDirtyPathOptions): Promise<DirtyPathRow[]>;
+  /**
+   * Guarded ack (design §8): delete the dirty row ONLY if its `latest_seq` is
+   * still the one we processed. A concurrent write bumps latest_seq (trigger),
+   * so a stale worker's DELETE affects 0 rows → returns false, and the newer
+   * dirty row survives for the next tick. Writes go to primary (`this.db`).
+   */
+  ackDirtyPath(path: string, latestSeq: number): Promise<boolean>;
+  /**
+   * Guarded failure record (design §8): bump attempts, stamp last_error +
+   * next_attempt_at, SAME `latest_seq` guard so a fresh write's reset (trigger
+   * sets attempts=0) is never clobbered by a late error from the prior attempt.
+   */
+  markDirtyPathError(path: string, latestSeq: number, error: string, nextAttemptAt: number): Promise<boolean>;
+}
+//#endregion
+export { D1TreeIndex, MAX_ENTRIES_PER_SCOPE, ancestorDirs, nameOf, parentOf };
+//# sourceMappingURL=d1-tree-index.d.mts.map

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

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