@aigne/afs-index 1.12.0-beta.5

package/dist/follower.d.cts

@@ -0,0 +1,241 @@
+import { IndexBackend } from "./backend/types.cjs";
+import { DirtyPathQueue } from "./dirty-queue.cjs";
+import { AFSRoot, BlockletIndexDomain } from "@aigne/afs";
+
+//#region src/follower.d.ts
+declare const FOLLOWER_CONSUMER_ID = "index";
+/**
+ * Derive a follower consumer_id that isolates per `(scope, instanceDid)` —
+ * `"index:{scope}:{instanceDid}"`. A single shared backend (Node's `/user/index`
+ * file, CF's D1) hosts many callers AND many blocklets per caller; the cursor
+ * row must be unique per (caller scope × blocklet instance) because each
+ * blocklet follows its OWN instance-space changelog. `instanceDid` is optional
+ * for backward compatibility (bare `index:{scope}` for pre-fix rows / callers
+ * that don't supply it); passing the bare `FOLLOWER_CONSUMER_ID` is only safe
+ * for single-scope callers (tests, standalone use).
+ */
+declare function deriveFollowerConsumerId(scope: string, instanceDid?: string | null): string;
+/**
+ * Memory-map key for a caller's per-blocklet index resources (the AFSIndex
+ * handle, its in-flight build promise, its IndexFollower). Isolation is
+ * per-`(scope, instanceDid)`: the SAME caller (scope) gets a SEPARATE index per
+ * blocklet (instanceDid). Keying these isolate-lived maps by scope ALONE let a
+ * caller's second index-blocklet reuse the FIRST's handle/follower (wrong bound
+ * domains + wrong instance-space changelog) — the in-memory twin of the cursor
+ * collision `deriveFollowerConsumerId` guards against.
+ */
+declare function userIndexKey(scope: string, instanceDid?: string | null): string;
+declare const DEFAULT_MAX_PROCESSED_PER_TICK = 4;
+declare const DEFAULT_MAX_NOOP_PER_TICK = 12;
+declare const DEFAULT_MAX_SCAN_PER_TICK = 400;
+/** Preferred alias for {@link DEFAULT_MAX_SCAN_PER_TICK} in dirty-drain call sites. */
+declare const DEFAULT_MAX_DIRTY_ROWS_PER_TICK = 400;
+interface IndexFollowerBatchResult {
+  scanned: number;
+  /** Matched PUT rows that consumed the expensive maxProcessed budget. */
+  processed: number;
+  /**
+   * Rows that consumed the maxNoop budget (design §8): delete rows, put-rows
+   * whose live state was missing (removed as cleanup), AND non-indexable
+   * (unmatched-domain) rows.
+   */
+  noopProcessed: number;
+  /** PUT rows that actually wrote entry/anchor/summary index data. */
+  indexed: number;
+  /** Delete/remove rows whose index cleanup was attempted. */
+  deleted: number;
+  /** Matched rows that intentionally wrote no index data (empty or stale content). */
+  nooped: number;
+  advanced: boolean;
+  hasMore: boolean;
+  /**
+   * At least one dirty row lost the ack race-guard this tick — a newer write
+   * bumped `latest_seq` while we processed, so the guarded ack no-oped and the
+   * newer dirty row waits for the next tick. NOT an error (real progress was
+   * made on the superseded state); surfaced so the CF/Node drain logs can
+   * distinguish healthy churn (`ackRace`) from failures (`failed`).
+   */
+  ackRace: boolean;
+  /**
+   * Why the tick stopped. `scan_budget` = the dirty-row FETCH budget (maxScan /
+   * maxDirtyRows) was exhausted — the name predates the §13 cutover (it used to
+   * mean "changelog scan budget"); kept as a stable value across the exported
+   * scheduler/daemon types.
+   */
+  stopReason?: "processed_budget" | "noop_budget" | "scan_budget" | "exhausted" | "aborted";
+  /** Log-compat only; dirty mode never advances a seq cursor (both 0). */
+  fromSeq: number;
+  toSeq: number;
+  matched: number;
+  unmatched: number;
+  skipped: number;
+  failed: number;
+  aborted: boolean;
+  abortReason?: string;
+}
+interface IndexFollowerOptions {
+  /** AFS backed by DIDSpaceProvider+PrefixedTreeIndex — CURRENT-state file read/stat
+   *  for the dirty drain (the `.changelog` consumption line was deleted at §13 cutover). */
+  spaceAfs: AFSRoot;
+  /** Index backend for writing indexed data. Must implement cursor methods. */
+  backend: IndexBackend;
+  /** Domain declarations from blocklet.yaml `index:` section. */
+  domains: BlockletIndexDomain[];
+  /**
+   * Cursor row identity for THIS follower. Defaults to the bare
+   * `FOLLOWER_CONSUMER_ID` ("index") for single-scope callers (tests,
+   * standalone use). Any caller whose backend hosts MULTIPLE scopes MUST pass
+   * `deriveFollowerConsumerId(scope)` — otherwise every scope sharing that
+   * backend would read/write the SAME `idx_index_cursor` row, each run
+   * clobbering the others' progress.
+   */
+  consumerId?: string;
+  /**
+   * Optional passage embedder — generates the vector stored alongside each
+   * indexed summary for semantic recall (Epic #932). Usually left unset here and
+   * wired later via `setEmbedder` (see its doc). Returns null to skip embedding.
+   */
+  embed?: (text: string) => Promise<number[] | null>;
+  /**
+   * Source-side dirty queue (index-follower-dirty-path). The follower DRAINS the
+   * merged `ds_dirty_path` projection — catch-up is O(unique dirty paths), not
+   * O(changelog rows). This is the SOLE catch-up mechanism (§13 cutover — the
+   * changelog `/.changelog` replay was deleted); a follower with no dirty queue
+   * has no source to drain and `runCatchUp`/`runBatch` are no-ops for it.
+   * Normally a fragment-scoped `PrefixedTreeIndex` so `listDirtyPaths` returns
+   * stripped `originalPath`s. ack/fail must be a runtime-internal capability,
+   * never a public `/user` action.
+   */
+  dirtyQueue?: DirtyPathQueue;
+}
+declare class IndexFollower {
+  private readonly spaceAfs;
+  private readonly backend;
+  private readonly domains;
+  private readonly consumerId;
+  private embed?;
+  private catchUpLimits?;
+  private readonly dirtyQueue?;
+  constructor(opts: IndexFollowerOptions);
+  /**
+   * Override the inline `runCatchUp()` budget — the per-invocation caps on
+   * matched PUT attempts, matched delete/remove rows, and dirty rows FETCHED
+   * (`maxScan`). Injected by the runtime from the SAME env group the cron uses
+   * (`AFS_INDEX_MAX_*_PER_TICK`) so both indexing paths share one budget group.
+   * Unset → provider defaults (standalone/tests).
+   */
+  setCatchUpLimits(limits: {
+    maxProcessed: number;
+    maxNoop?: number;
+    maxScan: number;
+  }): void;
+  /**
+   * Wire (or replace) the passage embedder used at index time — semantic recall
+   * (Epic #932). Called by `AFSIndex.setFollower` (query-path follower) and by
+   * `rebuildFollowerFromCursor` (CF cron-path follower) so BOTH indexing paths
+   * write embeddings; without this a changelog-indexed entry has only FTS +
+   * anchors and cross-lingual / semantic queries can't match it. A no-op
+   * embedder (or a backend without `writeEmbedding`) degrades cleanly to
+   * FTS+anchor.
+   */
+  setEmbedder(embed: (text: string) => Promise<number[] | null>): void;
+  /**
+   * Lightweight catch-up: drain any ready dirty rows so a query sees a fresh
+   * index without waiting for the next cron tick. Called from execQuery.
+   *
+   * Dirty drain is the SOLE catch-up mechanism (index-follower-dirty-path §13
+   * cutover — the changelog `/.changelog` replay was deleted). Freshness = "are
+   * there ready dirty rows under my prefix", so there is no `last_seq` probe: a
+   * query sees a fresh index by processing whatever dirty paths are pending
+   * (design §4.2, §8). A follower with no dirty queue (standalone/legacy) is a
+   * no-op here — it has no source to drain.
+   */
+  runCatchUp(): Promise<void>;
+  /**
+   * Bounded per-tick drain of the dirty queue — attempt up to `maxProcessed`
+   * matched PUT rows, up to `maxNoop` matched delete/remove/noop rows, fetching
+   * at most `maxScan` (a.k.a. `maxDirtyRows`) dirty rows. Called from the cron.
+   *
+   * Dirty drain is the SOLE mechanism (index-follower-dirty-path §13 cutover —
+   * changelog replay was deleted). A follower with no dirty queue has no source
+   * to drain, so it is idle. Separate budgets are intentional: matched PUT rows
+   * are the expensive read+embed+write axis, delete/noop rows are cheaper.
+   */
+  runBatch(limits?: {
+    maxProcessed?: number;
+    maxNoop?: number; /** Max dirty rows fetched this tick. `maxDirtyRows` is the preferred name. */
+    maxScan?: number;
+    maxDirtyRows?: number;
+  }): Promise<IndexFollowerBatchResult>;
+  /** Empty batch result (no dirty queue wired / nothing to drain). */
+  private idleResult;
+  /**
+   * Cold rebuild of an EXPLICIT list of space-relative paths — the enumeration
+   * is done by the caller (an external driver listing the live tree via D1),
+   * NOT in this process. Reads CURRENT live state per path and writes the
+   * derived index layers, independent of any queue — so it is the seam the
+   * offline reset-and-rebuild (`offlineRebuildScope`) uses to rebuild from live
+   * `ds_entries`. Keeping the per-call cost to just `paths.length`
+   * read+embed+writes with ZERO in-Worker tree enumeration is what keeps a small
+   * batch inside the CF free-tier per-request CPU/subrequest budget (an in-Worker
+   * `maxDepth:-1` enumeration pushed cold isolates over that budget into 503s).
+   * Each path is matched against the declared domains and indexed through the
+   * same `indexEntry` as the drain path (byte-identical output). `paths` are
+   * space-relative, e.g. `"items/foo.json"` (leading slash tolerated).
+   */
+  reindexPaths(paths: string[], onProgress?: (done: number, total: number) => void): Promise<{
+    indexed: number;
+    failed: number;
+    skipped: number;
+  }>;
+  /**
+   * Dirty drain (index-follower-dirty-path §8) — the O(unique dirty paths)
+   * replacement for changelog replay. Fetches ready dirty rows under this
+   * follower's prefix, and for each: domain-matches the stripped `originalPath`,
+   * reads CURRENT live state, and indexes / removes accordingly, then acks with
+   * the `latestSeq` race guard. A transient failure marks the row with a backoff
+   * (so a poison row can't refill the tick) instead of acking.
+   *
+   * Dirty mode NEVER writes `idx_index_cursor.last_seq` (design §4.2 — it is a
+   * dead column post-cutover); scheduling reads `advanced/hasMore/scanned` +
+   * the dirty count. The `dirtyQueue.listDirtyPaths({ prefix: "" })` call assumes
+   * a fragment-scoped queue (PrefixedTreeIndex), so `row.path` is already the
+   * stripped `originalPath` the domain globs + `spaceAfs.read` expect.
+   */
+  private processDirty;
+  /** Remove the indexed doc(s) for a delete/removed dirty row across matched domains. */
+  private removeDirty;
+  /** Shared index-removal (delete branch) — throws ChangelogAbortError on failure so the row backs off. */
+  private removeIndexed;
+  /**
+   * Handle a `put` dirty row against CURRENT live state (design §4.3 / §8 step 6):
+   *   - live exists  → indexEntry (writes FTS/anchor/summary/embedding).
+   *   - live missing (authoritative 404) → remove the indexed doc.
+   *   - stat throws a NON-404 error → transient → ChangelogAbortError (retry).
+   * This is what makes a stale put whose file was deleted converge to "removed",
+   * while a replica-lag / D1 blip is NEVER mistaken for a deletion.
+   */
+  private indexPutDirty;
+  /**
+   * Does `originalPath` STILL EXIST (via `stat`)? Used to classify a `read()`
+   * failure (issue #935 BLOCK fix #3 / sync-engine parity):
+   *   - stat 404 (or throws) → the file is gone (later delete, or never existed
+   *     at this position) → the row is stale, safe to skip.
+   *   - stat succeeds → the file is live; the read failure was transient (R2/D1
+   *     blip) and must be retried, not lost.
+   * Post-cutover the drain only ever indexes live state (cid is never compared —
+   * supersession is caught by the ack race-guard), so existence is the only
+   * question left here.
+   */
+  private entryStillCurrent;
+  private pathMatchesDomain;
+  private indexEntry;
+  /**
+   * Build the stable index entry path for a file. Uses the domain scope
+   * (default "/user") as a prefix so query-scope filtering works.
+   */
+  private makeEntryPath;
+}
+//#endregion
+export { DEFAULT_MAX_DIRTY_ROWS_PER_TICK, DEFAULT_MAX_NOOP_PER_TICK, DEFAULT_MAX_PROCESSED_PER_TICK, DEFAULT_MAX_SCAN_PER_TICK, FOLLOWER_CONSUMER_ID, IndexFollower, IndexFollowerBatchResult, IndexFollowerOptions, deriveFollowerConsumerId, userIndexKey };
+//# sourceMappingURL=follower.d.cts.map

package/dist/follower.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follower.d.cts","names":[],"sources":["../src/follower.ts"],"mappings":";;;;;cAqDa,oBAAA;;;;;;;;;;;iBAYG,wBAAA,CAAyB,KAAA,UAAe,WAAA;;;;;;;;;;iBAexC,YAAA,CAAa,KAAA,UAAe,WAAA;AAAA,cAe/B,8BAAA;AAAA,cACA,yBAAA;AAAA,cAQA,yBAAA;;cAEA,+BAAA;AAAA,UA+BI,wBAAA;EACf,OAAA;EAkDS;EAhDT,SAAA;EA0Ea;;;;;EApEb,aAAA;EAwCS;EAtCT,OAAA;EAwCS;EAtCT,OAAA;EAqDA;EAnDA,MAAA;EACA,QAAA;EACA,OAAA;EA4Da;;;AAGf;;;;EAvDE,OAAA;EA8GoB;;;;;;EAvGpB,UAAA;EAkDiB;EAhDjB,OAAA;EACA,KAAA;EACA,OAAA;EACA,SAAA;EACA,OAAA;EACA,MAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,oBAAA;EA+DkC;;EA5DjD,QAAA,EAAU,OAAA;EAyEV;EAvEA,OAAA,EAAS,YAAA;EAuE4B;EArErC,OAAA,EAAS,mBAAA;EAoFH;;;;;;;;EA3EN,UAAA;EAoGY;;;;;EA9FZ,KAAA,IAAS,IAAA,aAAiB,OAAA;EA8IxB;;;;;;;;;;EAnIF,UAAA,GAAa,cAAA;AAAA;AAAA,cAGF,aAAA;EAAA,iBACM,QAAA;EAAA,iBACA,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,UAAA;EAAA,QACT,KAAA;EAAA,QAGA,aAAA;EAAA,iBACS,UAAA;cAEL,IAAA,EAAM,oBAAA;;;;;;;;EAgBlB,gBAAA,CAAiB,MAAA;IAAU,YAAA;IAAsB,OAAA;IAAkB,OAAA;EAAA;;;;;;;;;;EAanE,WAAA,CAAY,KAAA,GAAQ,IAAA,aAAiB,OAAA;;;;;;;;;;;;EAe/B,UAAA,CAAA,GAAc,OAAA;;;;;;;;;;;EAmBd,QAAA,CAAS,MAAA;IACb,YAAA;IACA,OAAA;IAEA,OAAA;IACA,YAAA;EAAA,IACE,OAAA,CAAQ,wBAAA;;UAUJ,UAAA;;;;;;;;;;;;;;;EAoCF,YAAA,CACJ,KAAA,YACA,UAAA,IAAc,IAAA,UAAc,KAAA,oBAC3B,OAAA;IAAU,OAAA;IAAiB,MAAA;IAAgB,OAAA;EAAA;;;;;;;;;;;;;;;UAwChC,YAAA;;UAwMA,WAAA;;UAUA,aAAA;;;;;;;;;UAyBA,aAAA;;;;;;;;;;;;UAkDA,iBAAA;EAAA,QASN,iBAAA;EAAA,QAKM,UAAA;;;;;UAwHN,aAAA;AAAA"}

package/dist/follower.d.mts

@@ -0,0 +1,241 @@
+import { IndexBackend } from "./backend/types.mjs";
+import { DirtyPathQueue } from "./dirty-queue.mjs";
+import { AFSRoot, BlockletIndexDomain } from "@aigne/afs";
+
+//#region src/follower.d.ts
+declare const FOLLOWER_CONSUMER_ID = "index";
+/**
+ * Derive a follower consumer_id that isolates per `(scope, instanceDid)` —
+ * `"index:{scope}:{instanceDid}"`. A single shared backend (Node's `/user/index`
+ * file, CF's D1) hosts many callers AND many blocklets per caller; the cursor
+ * row must be unique per (caller scope × blocklet instance) because each
+ * blocklet follows its OWN instance-space changelog. `instanceDid` is optional
+ * for backward compatibility (bare `index:{scope}` for pre-fix rows / callers
+ * that don't supply it); passing the bare `FOLLOWER_CONSUMER_ID` is only safe
+ * for single-scope callers (tests, standalone use).
+ */
+declare function deriveFollowerConsumerId(scope: string, instanceDid?: string | null): string;
+/**
+ * Memory-map key for a caller's per-blocklet index resources (the AFSIndex
+ * handle, its in-flight build promise, its IndexFollower). Isolation is
+ * per-`(scope, instanceDid)`: the SAME caller (scope) gets a SEPARATE index per
+ * blocklet (instanceDid). Keying these isolate-lived maps by scope ALONE let a
+ * caller's second index-blocklet reuse the FIRST's handle/follower (wrong bound
+ * domains + wrong instance-space changelog) — the in-memory twin of the cursor
+ * collision `deriveFollowerConsumerId` guards against.
+ */
+declare function userIndexKey(scope: string, instanceDid?: string | null): string;
+declare const DEFAULT_MAX_PROCESSED_PER_TICK = 4;
+declare const DEFAULT_MAX_NOOP_PER_TICK = 12;
+declare const DEFAULT_MAX_SCAN_PER_TICK = 400;
+/** Preferred alias for {@link DEFAULT_MAX_SCAN_PER_TICK} in dirty-drain call sites. */
+declare const DEFAULT_MAX_DIRTY_ROWS_PER_TICK = 400;
+interface IndexFollowerBatchResult {
+  scanned: number;
+  /** Matched PUT rows that consumed the expensive maxProcessed budget. */
+  processed: number;
+  /**
+   * Rows that consumed the maxNoop budget (design §8): delete rows, put-rows
+   * whose live state was missing (removed as cleanup), AND non-indexable
+   * (unmatched-domain) rows.
+   */
+  noopProcessed: number;
+  /** PUT rows that actually wrote entry/anchor/summary index data. */
+  indexed: number;
+  /** Delete/remove rows whose index cleanup was attempted. */
+  deleted: number;
+  /** Matched rows that intentionally wrote no index data (empty or stale content). */
+  nooped: number;
+  advanced: boolean;
+  hasMore: boolean;
+  /**
+   * At least one dirty row lost the ack race-guard this tick — a newer write
+   * bumped `latest_seq` while we processed, so the guarded ack no-oped and the
+   * newer dirty row waits for the next tick. NOT an error (real progress was
+   * made on the superseded state); surfaced so the CF/Node drain logs can
+   * distinguish healthy churn (`ackRace`) from failures (`failed`).
+   */
+  ackRace: boolean;
+  /**
+   * Why the tick stopped. `scan_budget` = the dirty-row FETCH budget (maxScan /
+   * maxDirtyRows) was exhausted — the name predates the §13 cutover (it used to
+   * mean "changelog scan budget"); kept as a stable value across the exported
+   * scheduler/daemon types.
+   */
+  stopReason?: "processed_budget" | "noop_budget" | "scan_budget" | "exhausted" | "aborted";
+  /** Log-compat only; dirty mode never advances a seq cursor (both 0). */
+  fromSeq: number;
+  toSeq: number;
+  matched: number;
+  unmatched: number;
+  skipped: number;
+  failed: number;
+  aborted: boolean;
+  abortReason?: string;
+}
+interface IndexFollowerOptions {
+  /** AFS backed by DIDSpaceProvider+PrefixedTreeIndex — CURRENT-state file read/stat
+   *  for the dirty drain (the `.changelog` consumption line was deleted at §13 cutover). */
+  spaceAfs: AFSRoot;
+  /** Index backend for writing indexed data. Must implement cursor methods. */
+  backend: IndexBackend;
+  /** Domain declarations from blocklet.yaml `index:` section. */
+  domains: BlockletIndexDomain[];
+  /**
+   * Cursor row identity for THIS follower. Defaults to the bare
+   * `FOLLOWER_CONSUMER_ID` ("index") for single-scope callers (tests,
+   * standalone use). Any caller whose backend hosts MULTIPLE scopes MUST pass
+   * `deriveFollowerConsumerId(scope)` — otherwise every scope sharing that
+   * backend would read/write the SAME `idx_index_cursor` row, each run
+   * clobbering the others' progress.
+   */
+  consumerId?: string;
+  /**
+   * Optional passage embedder — generates the vector stored alongside each
+   * indexed summary for semantic recall (Epic #932). Usually left unset here and
+   * wired later via `setEmbedder` (see its doc). Returns null to skip embedding.
+   */
+  embed?: (text: string) => Promise<number[] | null>;
+  /**
+   * Source-side dirty queue (index-follower-dirty-path). The follower DRAINS the
+   * merged `ds_dirty_path` projection — catch-up is O(unique dirty paths), not
+   * O(changelog rows). This is the SOLE catch-up mechanism (§13 cutover — the
+   * changelog `/.changelog` replay was deleted); a follower with no dirty queue
+   * has no source to drain and `runCatchUp`/`runBatch` are no-ops for it.
+   * Normally a fragment-scoped `PrefixedTreeIndex` so `listDirtyPaths` returns
+   * stripped `originalPath`s. ack/fail must be a runtime-internal capability,
+   * never a public `/user` action.
+   */
+  dirtyQueue?: DirtyPathQueue;
+}
+declare class IndexFollower {
+  private readonly spaceAfs;
+  private readonly backend;
+  private readonly domains;
+  private readonly consumerId;
+  private embed?;
+  private catchUpLimits?;
+  private readonly dirtyQueue?;
+  constructor(opts: IndexFollowerOptions);
+  /**
+   * Override the inline `runCatchUp()` budget — the per-invocation caps on
+   * matched PUT attempts, matched delete/remove rows, and dirty rows FETCHED
+   * (`maxScan`). Injected by the runtime from the SAME env group the cron uses
+   * (`AFS_INDEX_MAX_*_PER_TICK`) so both indexing paths share one budget group.
+   * Unset → provider defaults (standalone/tests).
+   */
+  setCatchUpLimits(limits: {
+    maxProcessed: number;
+    maxNoop?: number;
+    maxScan: number;
+  }): void;
+  /**
+   * Wire (or replace) the passage embedder used at index time — semantic recall
+   * (Epic #932). Called by `AFSIndex.setFollower` (query-path follower) and by
+   * `rebuildFollowerFromCursor` (CF cron-path follower) so BOTH indexing paths
+   * write embeddings; without this a changelog-indexed entry has only FTS +
+   * anchors and cross-lingual / semantic queries can't match it. A no-op
+   * embedder (or a backend without `writeEmbedding`) degrades cleanly to
+   * FTS+anchor.
+   */
+  setEmbedder(embed: (text: string) => Promise<number[] | null>): void;
+  /**
+   * Lightweight catch-up: drain any ready dirty rows so a query sees a fresh
+   * index without waiting for the next cron tick. Called from execQuery.
+   *
+   * Dirty drain is the SOLE catch-up mechanism (index-follower-dirty-path §13
+   * cutover — the changelog `/.changelog` replay was deleted). Freshness = "are
+   * there ready dirty rows under my prefix", so there is no `last_seq` probe: a
+   * query sees a fresh index by processing whatever dirty paths are pending
+   * (design §4.2, §8). A follower with no dirty queue (standalone/legacy) is a
+   * no-op here — it has no source to drain.
+   */
+  runCatchUp(): Promise<void>;
+  /**
+   * Bounded per-tick drain of the dirty queue — attempt up to `maxProcessed`
+   * matched PUT rows, up to `maxNoop` matched delete/remove/noop rows, fetching
+   * at most `maxScan` (a.k.a. `maxDirtyRows`) dirty rows. Called from the cron.
+   *
+   * Dirty drain is the SOLE mechanism (index-follower-dirty-path §13 cutover —
+   * changelog replay was deleted). A follower with no dirty queue has no source
+   * to drain, so it is idle. Separate budgets are intentional: matched PUT rows
+   * are the expensive read+embed+write axis, delete/noop rows are cheaper.
+   */
+  runBatch(limits?: {
+    maxProcessed?: number;
+    maxNoop?: number; /** Max dirty rows fetched this tick. `maxDirtyRows` is the preferred name. */
+    maxScan?: number;
+    maxDirtyRows?: number;
+  }): Promise<IndexFollowerBatchResult>;
+  /** Empty batch result (no dirty queue wired / nothing to drain). */
+  private idleResult;
+  /**
+   * Cold rebuild of an EXPLICIT list of space-relative paths — the enumeration
+   * is done by the caller (an external driver listing the live tree via D1),
+   * NOT in this process. Reads CURRENT live state per path and writes the
+   * derived index layers, independent of any queue — so it is the seam the
+   * offline reset-and-rebuild (`offlineRebuildScope`) uses to rebuild from live
+   * `ds_entries`. Keeping the per-call cost to just `paths.length`
+   * read+embed+writes with ZERO in-Worker tree enumeration is what keeps a small
+   * batch inside the CF free-tier per-request CPU/subrequest budget (an in-Worker
+   * `maxDepth:-1` enumeration pushed cold isolates over that budget into 503s).
+   * Each path is matched against the declared domains and indexed through the
+   * same `indexEntry` as the drain path (byte-identical output). `paths` are
+   * space-relative, e.g. `"items/foo.json"` (leading slash tolerated).
+   */
+  reindexPaths(paths: string[], onProgress?: (done: number, total: number) => void): Promise<{
+    indexed: number;
+    failed: number;
+    skipped: number;
+  }>;
+  /**
+   * Dirty drain (index-follower-dirty-path §8) — the O(unique dirty paths)
+   * replacement for changelog replay. Fetches ready dirty rows under this
+   * follower's prefix, and for each: domain-matches the stripped `originalPath`,
+   * reads CURRENT live state, and indexes / removes accordingly, then acks with
+   * the `latestSeq` race guard. A transient failure marks the row with a backoff
+   * (so a poison row can't refill the tick) instead of acking.
+   *
+   * Dirty mode NEVER writes `idx_index_cursor.last_seq` (design §4.2 — it is a
+   * dead column post-cutover); scheduling reads `advanced/hasMore/scanned` +
+   * the dirty count. The `dirtyQueue.listDirtyPaths({ prefix: "" })` call assumes
+   * a fragment-scoped queue (PrefixedTreeIndex), so `row.path` is already the
+   * stripped `originalPath` the domain globs + `spaceAfs.read` expect.
+   */
+  private processDirty;
+  /** Remove the indexed doc(s) for a delete/removed dirty row across matched domains. */
+  private removeDirty;
+  /** Shared index-removal (delete branch) — throws ChangelogAbortError on failure so the row backs off. */
+  private removeIndexed;
+  /**
+   * Handle a `put` dirty row against CURRENT live state (design §4.3 / §8 step 6):
+   *   - live exists  → indexEntry (writes FTS/anchor/summary/embedding).
+   *   - live missing (authoritative 404) → remove the indexed doc.
+   *   - stat throws a NON-404 error → transient → ChangelogAbortError (retry).
+   * This is what makes a stale put whose file was deleted converge to "removed",
+   * while a replica-lag / D1 blip is NEVER mistaken for a deletion.
+   */
+  private indexPutDirty;
+  /**
+   * Does `originalPath` STILL EXIST (via `stat`)? Used to classify a `read()`
+   * failure (issue #935 BLOCK fix #3 / sync-engine parity):
+   *   - stat 404 (or throws) → the file is gone (later delete, or never existed
+   *     at this position) → the row is stale, safe to skip.
+   *   - stat succeeds → the file is live; the read failure was transient (R2/D1
+   *     blip) and must be retried, not lost.
+   * Post-cutover the drain only ever indexes live state (cid is never compared —
+   * supersession is caught by the ack race-guard), so existence is the only
+   * question left here.
+   */
+  private entryStillCurrent;
+  private pathMatchesDomain;
+  private indexEntry;
+  /**
+   * Build the stable index entry path for a file. Uses the domain scope
+   * (default "/user") as a prefix so query-scope filtering works.
+   */
+  private makeEntryPath;
+}
+//#endregion
+export { DEFAULT_MAX_DIRTY_ROWS_PER_TICK, DEFAULT_MAX_NOOP_PER_TICK, DEFAULT_MAX_PROCESSED_PER_TICK, DEFAULT_MAX_SCAN_PER_TICK, FOLLOWER_CONSUMER_ID, IndexFollower, IndexFollowerBatchResult, IndexFollowerOptions, deriveFollowerConsumerId, userIndexKey };
+//# sourceMappingURL=follower.d.mts.map

package/dist/follower.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follower.d.mts","names":[],"sources":["../src/follower.ts"],"mappings":";;;;;cAqDa,oBAAA;;;;;;;;;;;iBAYG,wBAAA,CAAyB,KAAA,UAAe,WAAA;;;;;;;;;;iBAexC,YAAA,CAAa,KAAA,UAAe,WAAA;AAAA,cAe/B,8BAAA;AAAA,cACA,yBAAA;AAAA,cAQA,yBAAA;;cAEA,+BAAA;AAAA,UA+BI,wBAAA;EACf,OAAA;EAkDS;EAhDT,SAAA;EA0Ea;;;;;EApEb,aAAA;EAwCS;EAtCT,OAAA;EAwCS;EAtCT,OAAA;EAqDA;EAnDA,MAAA;EACA,QAAA;EACA,OAAA;EA4Da;;;AAGf;;;;EAvDE,OAAA;EA8GoB;;;;;;EAvGpB,UAAA;EAkDiB;EAhDjB,OAAA;EACA,KAAA;EACA,OAAA;EACA,SAAA;EACA,OAAA;EACA,MAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,oBAAA;EA+DkC;;EA5DjD,QAAA,EAAU,OAAA;EAyEV;EAvEA,OAAA,EAAS,YAAA;EAuE4B;EArErC,OAAA,EAAS,mBAAA;EAoFH;;;;;;;;EA3EN,UAAA;EAoGY;;;;;EA9FZ,KAAA,IAAS,IAAA,aAAiB,OAAA;EA8IxB;;;;;;;;;;EAnIF,UAAA,GAAa,cAAA;AAAA;AAAA,cAGF,aAAA;EAAA,iBACM,QAAA;EAAA,iBACA,OAAA;EAAA,iBACA,OAAA;EAAA,iBACA,UAAA;EAAA,QACT,KAAA;EAAA,QAGA,aAAA;EAAA,iBACS,UAAA;cAEL,IAAA,EAAM,oBAAA;;;;;;;;EAgBlB,gBAAA,CAAiB,MAAA;IAAU,YAAA;IAAsB,OAAA;IAAkB,OAAA;EAAA;;;;;;;;;;EAanE,WAAA,CAAY,KAAA,GAAQ,IAAA,aAAiB,OAAA;;;;;;;;;;;;EAe/B,UAAA,CAAA,GAAc,OAAA;;;;;;;;;;;EAmBd,QAAA,CAAS,MAAA;IACb,YAAA;IACA,OAAA;IAEA,OAAA;IACA,YAAA;EAAA,IACE,OAAA,CAAQ,wBAAA;;UAUJ,UAAA;;;;;;;;;;;;;;;EAoCF,YAAA,CACJ,KAAA,YACA,UAAA,IAAc,IAAA,UAAc,KAAA,oBAC3B,OAAA;IAAU,OAAA;IAAiB,MAAA;IAAgB,OAAA;EAAA;;;;;;;;;;;;;;;UAwChC,YAAA;;UAwMA,WAAA;;UAUA,aAAA;;;;;;;;;UAyBA,aAAA;;;;;;;;;;;;UAkDA,iBAAA;EAAA,QASN,iBAAA;EAAA,QAKM,UAAA;;;;;UAwHN,aAAA;AAAA"}