@aigne/afs-index 1.12.0-beta.5

package/dist/follower-scheduler.mjs

@@ -0,0 +1,92 @@
+//#region src/follower-scheduler.ts
+function clampSpent(value, remaining) {
+	if (!Number.isFinite(value ?? 0) || (value ?? 0) <= 0) return 0;
+	return Math.min(value ?? 0, remaining);
+}
+/**
+* Fairly spend one index-follower tick across a selected scope set.
+*
+* Each scope receives a small bounded slice first; scopes that still report
+* `hasMore` are appended to the tail and can receive another slice only after
+* the other selected scopes had their chance. The helper is intentionally
+* storage/runtime-agnostic so Cloudflare and Node share the same starvation
+* semantics while keeping different budget sizes.
+*/
+async function runIndexFollowerRoundRobin(opts) {
+	let remainingProcessed = Math.max(0, opts.maxProcessed);
+	let remainingNoop = Math.max(0, opts.maxNoop);
+	let remainingScan = Math.max(0, opts.maxScan);
+	const perScopeMaxProcessed = Math.max(0, opts.perScopeMaxProcessed ?? 1);
+	const perScopeMaxNoop = Math.max(0, opts.perScopeMaxNoop ?? 2);
+	const perScopeMaxScan = Math.max(1, opts.perScopeMaxScan ?? 50);
+	const maxRuns = opts.maxRuns ?? opts.scopes.length + Math.ceil((remainingProcessed || 0) / Math.max(1, perScopeMaxProcessed || 1)) + Math.ceil((remainingNoop || 0) / Math.max(1, perScopeMaxNoop || 1)) + Math.ceil((remainingScan || 0) / Math.max(1, perScopeMaxScan));
+	const queue = [...opts.scopes];
+	const runs = [];
+	let indexedThisTick = 0;
+	let deletedThisTick = 0;
+	let noopedThisTick = 0;
+	let ackRaceThisTick = 0;
+	let stoppedBy = "drained";
+	let sawBudgetBlockedScope = false;
+	while (queue.length > 0) {
+		if (opts.shouldStop?.()) {
+			stoppedBy = "time";
+			break;
+		}
+		if (runs.length >= maxRuns) {
+			stoppedBy = "max_runs";
+			break;
+		}
+		if (remainingScan <= 0 || remainingProcessed <= 0 && remainingNoop <= 0) {
+			stoppedBy = "budget";
+			break;
+		}
+		const scope = queue.shift();
+		const limits = {
+			maxProcessed: Math.min(perScopeMaxProcessed, remainingProcessed),
+			maxNoop: Math.min(perScopeMaxNoop, remainingNoop),
+			maxScan: Math.min(perScopeMaxScan, remainingScan)
+		};
+		if (limits.maxScan <= 0 || limits.maxProcessed <= 0 && limits.maxNoop <= 0) {
+			stoppedBy = "budget";
+			break;
+		}
+		const result = await opts.runScope(scope, limits);
+		runs.push({
+			scope,
+			limits,
+			result
+		});
+		remainingProcessed -= clampSpent(result.processed, remainingProcessed);
+		remainingNoop -= clampSpent(result.noopProcessed, remainingNoop);
+		remainingScan -= clampSpent(result.scanned, remainingScan);
+		indexedThisTick += result.indexed;
+		deletedThisTick += result.deleted;
+		noopedThisTick += result.nooped;
+		if (result.ackRace) ackRaceThisTick++;
+		if (!result.advanced && result.hasMore && [
+			"processed_budget",
+			"noop_budget",
+			"scan_budget"
+		].includes(result.stopReason ?? "")) sawBudgetBlockedScope = true;
+		if (result.advanced && result.hasMore && !result.aborted && remainingScan > 0 && (remainingProcessed > 0 || remainingNoop > 0)) queue.push(scope);
+	}
+	return {
+		runs,
+		processedThisTick: opts.maxProcessed - remainingProcessed,
+		noopThisTick: opts.maxNoop - remainingNoop,
+		indexedThisTick,
+		deletedThisTick,
+		noopedThisTick,
+		scannedThisTick: opts.maxScan - remainingScan,
+		ackRaceThisTick,
+		stoppedBy: stoppedBy === "drained" && sawBudgetBlockedScope ? "budget" : stoppedBy,
+		remainingProcessed,
+		remainingNoop,
+		remainingScan
+	};
+}
+
+//#endregion
+export { runIndexFollowerRoundRobin };
+//# sourceMappingURL=follower-scheduler.mjs.map

package/dist/follower-scheduler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"follower-scheduler.mjs","names":[],"sources":["../src/follower-scheduler.ts"],"sourcesContent":["import type { IndexFollowerBatchResult } from \"./follower.js\";\n\n// `maxScan` / `remainingScan` / `scannedThisTick` here count DIRTY ROWS fetched,\n// not changelog rows (the §13 cutover deleted the changelog scan). The `maxScan`\n// field key is kept as a stable public name across the budget chain — see\n// DEFAULT_MAX_SCAN_PER_TICK in follower.ts (§B: doc over public-API rename).\nexport interface IndexFollowerRunLimits {\n  maxProcessed: number;\n  maxNoop: number;\n  maxScan: number;\n}\n\nexport interface IndexFollowerRoundRobinOptions<T> {\n  scopes: T[];\n  maxProcessed: number;\n  maxNoop: number;\n  maxScan: number;\n  perScopeMaxProcessed?: number;\n  perScopeMaxNoop?: number;\n  perScopeMaxScan?: number;\n  maxRuns?: number;\n  shouldStop?: () => boolean;\n  runScope: (scope: T, limits: IndexFollowerRunLimits) => Promise<IndexFollowerBatchResult>;\n}\n\nexport interface IndexFollowerRoundRobinRun<T> {\n  scope: T;\n  limits: IndexFollowerRunLimits;\n  result: IndexFollowerBatchResult;\n}\n\nexport interface IndexFollowerRoundRobinResult<T> {\n  runs: IndexFollowerRoundRobinRun<T>[];\n  processedThisTick: number;\n  noopThisTick: number;\n  indexedThisTick: number;\n  deletedThisTick: number;\n  noopedThisTick: number;\n  scannedThisTick: number;\n  /**\n   * Drain RUNS that lost the ack race-guard this tick (healthy concurrent-write\n   * churn, not failures). Counted per `runScope` call, so a single hot scope\n   * requeued within the tick can contribute more than once — this is a run\n   * occurrence count, not a distinct-scope count.\n   */\n  ackRaceThisTick: number;\n  stoppedBy: \"drained\" | \"budget\" | \"max_runs\" | \"time\";\n  remainingProcessed: number;\n  remainingNoop: number;\n  remainingScan: number;\n}\n\nfunction clampSpent(value: number | undefined, remaining: number): number {\n  if (!Number.isFinite(value ?? 0) || (value ?? 0) <= 0) return 0;\n  return Math.min(value ?? 0, remaining);\n}\n\n/**\n * Fairly spend one index-follower tick across a selected scope set.\n *\n * Each scope receives a small bounded slice first; scopes that still report\n * `hasMore` are appended to the tail and can receive another slice only after\n * the other selected scopes had their chance. The helper is intentionally\n * storage/runtime-agnostic so Cloudflare and Node share the same starvation\n * semantics while keeping different budget sizes.\n */\nexport async function runIndexFollowerRoundRobin<T>(\n  opts: IndexFollowerRoundRobinOptions<T>,\n): Promise<IndexFollowerRoundRobinResult<T>> {\n  let remainingProcessed = Math.max(0, opts.maxProcessed);\n  let remainingNoop = Math.max(0, opts.maxNoop);\n  let remainingScan = Math.max(0, opts.maxScan);\n  const perScopeMaxProcessed = Math.max(0, opts.perScopeMaxProcessed ?? 1);\n  const perScopeMaxNoop = Math.max(0, opts.perScopeMaxNoop ?? 2);\n  const perScopeMaxScan = Math.max(1, opts.perScopeMaxScan ?? 50);\n  const maxRuns =\n    opts.maxRuns ??\n    opts.scopes.length +\n      Math.ceil((remainingProcessed || 0) / Math.max(1, perScopeMaxProcessed || 1)) +\n      Math.ceil((remainingNoop || 0) / Math.max(1, perScopeMaxNoop || 1)) +\n      Math.ceil((remainingScan || 0) / Math.max(1, perScopeMaxScan));\n  const queue = [...opts.scopes];\n  const runs: IndexFollowerRoundRobinRun<T>[] = [];\n  let indexedThisTick = 0;\n  let deletedThisTick = 0;\n  let noopedThisTick = 0;\n  let ackRaceThisTick = 0;\n  let stoppedBy: IndexFollowerRoundRobinResult<T>[\"stoppedBy\"] = \"drained\";\n  let sawBudgetBlockedScope = false;\n\n  while (queue.length > 0) {\n    if (opts.shouldStop?.()) {\n      stoppedBy = \"time\";\n      break;\n    }\n    if (runs.length >= maxRuns) {\n      stoppedBy = \"max_runs\";\n      break;\n    }\n    if (remainingScan <= 0 || (remainingProcessed <= 0 && remainingNoop <= 0)) {\n      stoppedBy = \"budget\";\n      break;\n    }\n\n    const scope = queue.shift()!;\n    const limits: IndexFollowerRunLimits = {\n      maxProcessed: Math.min(perScopeMaxProcessed, remainingProcessed),\n      maxNoop: Math.min(perScopeMaxNoop, remainingNoop),\n      maxScan: Math.min(perScopeMaxScan, remainingScan),\n    };\n    if (limits.maxScan <= 0 || (limits.maxProcessed <= 0 && limits.maxNoop <= 0)) {\n      stoppedBy = \"budget\";\n      break;\n    }\n\n    const result = await opts.runScope(scope, limits);\n    runs.push({ scope, limits, result });\n\n    remainingProcessed -= clampSpent(result.processed, remainingProcessed);\n    remainingNoop -= clampSpent(result.noopProcessed, remainingNoop);\n    remainingScan -= clampSpent(result.scanned, remainingScan);\n    indexedThisTick += result.indexed;\n    deletedThisTick += result.deleted;\n    noopedThisTick += result.nooped;\n    if (result.ackRace) ackRaceThisTick++;\n    if (\n      !result.advanced &&\n      result.hasMore &&\n      [\"processed_budget\", \"noop_budget\", \"scan_budget\"].includes(result.stopReason ?? \"\")\n    ) {\n      sawBudgetBlockedScope = true;\n    }\n\n    if (\n      result.advanced &&\n      result.hasMore &&\n      !result.aborted &&\n      remainingScan > 0 &&\n      (remainingProcessed > 0 || remainingNoop > 0)\n    ) {\n      queue.push(scope);\n    }\n  }\n\n  return {\n    runs,\n    processedThisTick: opts.maxProcessed - remainingProcessed,\n    noopThisTick: opts.maxNoop - remainingNoop,\n    indexedThisTick,\n    deletedThisTick,\n    noopedThisTick,\n    scannedThisTick: opts.maxScan - remainingScan,\n    ackRaceThisTick,\n    stoppedBy: stoppedBy === \"drained\" && sawBudgetBlockedScope ? \"budget\" : stoppedBy,\n    remainingProcessed,\n    remainingNoop,\n    remainingScan,\n  };\n}\n"],"mappings":";AAoDA,SAAS,WAAW,OAA2B,WAA2B;AACxE,KAAI,CAAC,OAAO,SAAS,SAAS,EAAE,KAAK,SAAS,MAAM,EAAG,QAAO;AAC9D,QAAO,KAAK,IAAI,SAAS,GAAG,UAAU;;;;;;;;;;;AAYxC,eAAsB,2BACpB,MAC2C;CAC3C,IAAI,qBAAqB,KAAK,IAAI,GAAG,KAAK,aAAa;CACvD,IAAI,gBAAgB,KAAK,IAAI,GAAG,KAAK,QAAQ;CAC7C,IAAI,gBAAgB,KAAK,IAAI,GAAG,KAAK,QAAQ;CAC7C,MAAM,uBAAuB,KAAK,IAAI,GAAG,KAAK,wBAAwB,EAAE;CACxE,MAAM,kBAAkB,KAAK,IAAI,GAAG,KAAK,mBAAmB,EAAE;CAC9D,MAAM,kBAAkB,KAAK,IAAI,GAAG,KAAK,mBAAmB,GAAG;CAC/D,MAAM,UACJ,KAAK,WACL,KAAK,OAAO,SACV,KAAK,MAAM,sBAAsB,KAAK,KAAK,IAAI,GAAG,wBAAwB,EAAE,CAAC,GAC7E,KAAK,MAAM,iBAAiB,KAAK,KAAK,IAAI,GAAG,mBAAmB,EAAE,CAAC,GACnE,KAAK,MAAM,iBAAiB,KAAK,KAAK,IAAI,GAAG,gBAAgB,CAAC;CAClE,MAAM,QAAQ,CAAC,GAAG,KAAK,OAAO;CAC9B,MAAM,OAAwC,EAAE;CAChD,IAAI,kBAAkB;CACtB,IAAI,kBAAkB;CACtB,IAAI,iBAAiB;CACrB,IAAI,kBAAkB;CACtB,IAAI,YAA2D;CAC/D,IAAI,wBAAwB;AAE5B,QAAO,MAAM,SAAS,GAAG;AACvB,MAAI,KAAK,cAAc,EAAE;AACvB,eAAY;AACZ;;AAEF,MAAI,KAAK,UAAU,SAAS;AAC1B,eAAY;AACZ;;AAEF,MAAI,iBAAiB,KAAM,sBAAsB,KAAK,iBAAiB,GAAI;AACzE,eAAY;AACZ;;EAGF,MAAM,QAAQ,MAAM,OAAO;EAC3B,MAAM,SAAiC;GACrC,cAAc,KAAK,IAAI,sBAAsB,mBAAmB;GAChE,SAAS,KAAK,IAAI,iBAAiB,cAAc;GACjD,SAAS,KAAK,IAAI,iBAAiB,cAAc;GAClD;AACD,MAAI,OAAO,WAAW,KAAM,OAAO,gBAAgB,KAAK,OAAO,WAAW,GAAI;AAC5E,eAAY;AACZ;;EAGF,MAAM,SAAS,MAAM,KAAK,SAAS,OAAO,OAAO;AACjD,OAAK,KAAK;GAAE;GAAO;GAAQ;GAAQ,CAAC;AAEpC,wBAAsB,WAAW,OAAO,WAAW,mBAAmB;AACtE,mBAAiB,WAAW,OAAO,eAAe,cAAc;AAChE,mBAAiB,WAAW,OAAO,SAAS,cAAc;AAC1D,qBAAmB,OAAO;AAC1B,qBAAmB,OAAO;AAC1B,oBAAkB,OAAO;AACzB,MAAI,OAAO,QAAS;AACpB,MACE,CAAC,OAAO,YACR,OAAO,WACP;GAAC;GAAoB;GAAe;GAAc,CAAC,SAAS,OAAO,cAAc,GAAG,CAEpF,yBAAwB;AAG1B,MACE,OAAO,YACP,OAAO,WACP,CAAC,OAAO,WACR,gBAAgB,MACf,qBAAqB,KAAK,gBAAgB,GAE3C,OAAM,KAAK,MAAM;;AAIrB,QAAO;EACL;EACA,mBAAmB,KAAK,eAAe;EACvC,cAAc,KAAK,UAAU;EAC7B;EACA;EACA;EACA,iBAAiB,KAAK,UAAU;EAChC;EACA,WAAW,cAAc,aAAa,wBAAwB,WAAW;EACzE;EACA;EACA;EACD"}

package/dist/follower.cjs

@@ -0,0 +1,577 @@
+const require_field_map = require('./extraction/field-map.cjs');
+let _aigne_afs = require("@aigne/afs");
+let ufo = require("ufo");
+
+//#region src/follower.ts
+/**
+* IndexFollower — DRAINS the source-side dirty queue (`ds_dirty_path`, the merged
+* current-state projection of the changelog) and incrementally indexes file
+* writes/deletes into the index backend. Dirty drain is the SOLE mechanism —
+* the changelog `/.changelog` replay was deleted at the §13 cutover; a follower
+* with no `dirtyQueue` is inert.
+*
+* Two entry points:
+*   runCatchUp()  — inline drain; called from execQuery so a query always sees a
+*                   fresh index (processes whatever dirty rows are pending).
+*   runBatch()    — bounded per-tick drain (maxProcessed/maxNoop/maxScan caps);
+*                   called from the cron task.
+*
+* Cursor: a `consumer_id` row in `idx_index_cursor` registers the follower and
+* carries its instanceDid + domains snapshot for durable cron discovery. Its
+* `last_seq` is a DEAD column post-cutover (nothing advances it during drain —
+* §4.2); scheduling fairness rides `served_at` (markCursorServed). All domains a
+* SINGLE blocklet declares share one cursor; DIFFERENT blocklets under the same
+* caller each get their own (their `/user` data lives in separate instance
+* spaces / dirty-queue prefixes).
+*
+* Consumer-id identity (design.md §4.4 decision-lock addendum, owner
+* 2026-07-05; per-instance fix): a single shared backend hosts MULTIPLE
+* `(scope, instanceDid)` pairs at once — Node's one-shared-SQLite-file rework
+* of #936 P4, and CF's one-shared-D1 model. So the bare `FOLLOWER_CONSUMER_ID`
+* isn't enough to identify ONE follower's cursor row;
+* `deriveFollowerConsumerId(scope, instanceDid)` folds BOTH in
+* (`index:{scope}:{instanceDid}`), the same compositing technique already used
+* for domain-name isolation (`{declared name}:{scope}`). Keying by scope ALONE
+* (the pre-fix behavior) let a caller's SECOND index-blocklet collide on the
+* first's cursor row (`INSERT OR IGNORE` → dropped) so its changelog was never
+* followed. D1 additionally isolates via its own `scope` column (PRIMARY KEY
+* (scope, consumer_id)); both runtimes derive the consumer_id the same way so a
+* persisted row means the same thing everywhere (`IndexBackend.listCursorScopes`
+* matches on the `{FOLLOWER_CONSUMER_ID}:` PREFIX for exactly this reason — see
+* d1-index-backend.ts).
+*/
+const log = (0, _aigne_afs.makeNsLog)("provider:index");
+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).
+*/
+function deriveFollowerConsumerId(scope, instanceDid) {
+	return instanceDid ? `${FOLLOWER_CONSUMER_ID}:${scope}:${instanceDid}` : `${FOLLOWER_CONSUMER_ID}:${scope}`;
+}
+/**
+* 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.
+*/
+function userIndexKey(scope, instanceDid) {
+	return instanceDid ? `${scope}::${instanceDid}` : scope;
+}
+const DEFAULT_MAX_PROCESSED_PER_TICK = 4;
+const DEFAULT_MAX_NOOP_PER_TICK = 12;
+const DEFAULT_MAX_SCAN_PER_TICK = 400;
+/** Preferred alias for {@link DEFAULT_MAX_SCAN_PER_TICK} in dirty-drain call sites. */
+const DEFAULT_MAX_DIRTY_ROWS_PER_TICK = DEFAULT_MAX_SCAN_PER_TICK;
+const DIRTY_RETRY_BACKOFF_MS = 6e4;
+function toAbsolute(path) {
+	return (0, ufo.joinURL)("/", path);
+}
+/**
+* Internal signal thrown by `indexEntry` / the dirty-drain remove path when a
+* read/stat/index failed on content that is STILL current (issue #935 BLOCK
+* fix #3 / sync-engine parity): `processDirty` catches this and BACKS OFF the
+* dirty row (marks it, doesn't ack) so the next tick retries it instead of
+* silently losing the write. (Historically named for the changelog replay that
+* the dirty-path cutover deleted; kept as the dirty-drain retry signal.)
+*/
+var ChangelogAbortError = class extends Error {
+	constructor(originalPath, reason = "transient read failure") {
+		super(`${reason} for "${originalPath}" — retry next run`);
+		this.name = "ChangelogAbortError";
+	}
+};
+var IndexFollower = class {
+	spaceAfs;
+	backend;
+	domains;
+	consumerId;
+	embed;
+	catchUpLimits;
+	dirtyQueue;
+	constructor(opts) {
+		this.spaceAfs = opts.spaceAfs;
+		this.backend = opts.backend;
+		this.domains = opts.domains;
+		this.consumerId = opts.consumerId ?? FOLLOWER_CONSUMER_ID;
+		this.embed = opts.embed;
+		this.dirtyQueue = opts.dirtyQueue;
+	}
+	/**
+	* 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) {
+		this.catchUpLimits = limits;
+	}
+	/**
+	* 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) {
+		this.embed = embed;
+	}
+	/**
+	* 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.
+	*/
+	async runCatchUp() {
+		if (!this.dirtyQueue) return;
+		await this.processDirty({
+			maxProcessed: this.catchUpLimits?.maxProcessed ?? DEFAULT_MAX_PROCESSED_PER_TICK,
+			maxNoop: this.catchUpLimits?.maxNoop ?? DEFAULT_MAX_NOOP_PER_TICK,
+			maxDirtyRows: this.catchUpLimits?.maxScan ?? DEFAULT_MAX_DIRTY_ROWS_PER_TICK
+		});
+	}
+	/**
+	* 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.
+	*/
+	async runBatch(limits) {
+		if (!this.dirtyQueue) return this.idleResult();
+		return this.processDirty({
+			maxProcessed: limits?.maxProcessed ?? DEFAULT_MAX_PROCESSED_PER_TICK,
+			maxNoop: limits?.maxNoop ?? DEFAULT_MAX_NOOP_PER_TICK,
+			maxDirtyRows: limits?.maxDirtyRows ?? limits?.maxScan ?? DEFAULT_MAX_DIRTY_ROWS_PER_TICK
+		});
+	}
+	/** Empty batch result (no dirty queue wired / nothing to drain). */
+	idleResult() {
+		return {
+			scanned: 0,
+			processed: 0,
+			noopProcessed: 0,
+			indexed: 0,
+			deleted: 0,
+			nooped: 0,
+			advanced: false,
+			hasMore: false,
+			ackRace: false,
+			stopReason: "exhausted",
+			fromSeq: 0,
+			toSeq: 0,
+			matched: 0,
+			unmatched: 0,
+			skipped: 0,
+			failed: 0,
+			aborted: false
+		};
+	}
+	/**
+	* 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).
+	*/
+	async reindexPaths(paths, onProgress) {
+		let indexed = 0;
+		let failed = 0;
+		let skipped = 0;
+		let done = 0;
+		for (const raw of paths) {
+			const rel = raw.replace(/^\/+/, "");
+			let matched = false;
+			for (const domain of this.domains) {
+				if (!this.pathMatchesDomain(rel, domain)) continue;
+				matched = true;
+				try {
+					if (await this.indexEntry(domain, rel, this.makeEntryPath(domain, rel)) === "indexed") indexed++;
+				} catch (err) {
+					failed++;
+					log.warn(`reindex failed: ${rel}`, err instanceof Error ? err.message : err);
+				}
+			}
+			if (!matched) skipped++;
+			done++;
+			if (onProgress && (done % 50 === 0 || done === paths.length)) onProgress(done, paths.length);
+		}
+		return {
+			indexed,
+			failed,
+			skipped
+		};
+	}
+	/**
+	* 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.
+	*/
+	async processDirty(limits) {
+		const result0 = () => ({
+			scanned: 0,
+			processed: 0,
+			noopProcessed: 0,
+			indexed: 0,
+			deleted: 0,
+			nooped: 0,
+			advanced: false,
+			hasMore: false,
+			ackRace: false,
+			stopReason: "exhausted",
+			fromSeq: 0,
+			toSeq: 0,
+			matched: 0,
+			unmatched: 0,
+			skipped: 0,
+			failed: 0,
+			aborted: false
+		});
+		const dirtyQueue = this.dirtyQueue;
+		if (!dirtyQueue) return result0();
+		const maxDirtyRows = limits.maxDirtyRows > 0 ? limits.maxDirtyRows : 0;
+		if (maxDirtyRows <= 0 || limits.maxProcessed <= 0 && limits.maxNoop <= 0) return result0();
+		let processedRemaining = limits.maxProcessed;
+		let noopRemaining = limits.maxNoop;
+		let scanned = 0;
+		let processed = 0;
+		let noopProcessed = 0;
+		let indexed = 0;
+		let deleted = 0;
+		let nooped = 0;
+		let matched = 0;
+		let unmatched = 0;
+		let failed = 0;
+		let advanced = false;
+		let hasMore = false;
+		let ackRace = false;
+		let stopReason;
+		const now = Date.now();
+		const rows = await dirtyQueue.listDirtyPaths({
+			prefix: "",
+			limit: maxDirtyRows,
+			now
+		});
+		for (const row of rows) {
+			scanned++;
+			const matchedDomains = this.domains.filter((d) => this.pathMatchesDomain(row.path, d));
+			if (matchedDomains.length === 0) {
+				if (noopRemaining <= 0) {
+					hasMore = true;
+					stopReason = "noop_budget";
+					break;
+				}
+				unmatched++;
+				noopRemaining--;
+				noopProcessed++;
+				if (await dirtyQueue.ackDirtyPath(row.path, row.latestSeq)) advanced = true;
+				else {
+					hasMore = true;
+					ackRace = true;
+				}
+				continue;
+			}
+			const isDelete = row.op === "delete";
+			if (isDelete) {
+				if (noopRemaining <= 0) {
+					hasMore = true;
+					stopReason = "noop_budget";
+					break;
+				}
+			} else if (processedRemaining <= 0) {
+				hasMore = true;
+				stopReason = "processed_budget";
+				break;
+			}
+			try {
+				let didIndex = 0;
+				let didRemove = 0;
+				if (isDelete) {
+					await this.removeDirty(matchedDomains, row.path);
+					didRemove = 1;
+				} else {
+					const r = await this.indexPutDirty(matchedDomains, row.path);
+					didIndex = r.indexed;
+					didRemove = r.removed;
+				}
+				matched++;
+				if (isDelete) {
+					noopRemaining--;
+					noopProcessed++;
+					deleted++;
+				} else if (didIndex > 0) {
+					processedRemaining--;
+					processed++;
+					indexed++;
+				} else if (didRemove > 0) {
+					noopProcessed++;
+					deleted++;
+				} else nooped++;
+				if (await dirtyQueue.ackDirtyPath(row.path, row.latestSeq)) advanced = true;
+				else {
+					advanced = true;
+					hasMore = true;
+					ackRace = true;
+				}
+			} catch (err) {
+				failed++;
+				const msg = err instanceof Error ? err.message : String(err);
+				await dirtyQueue.markDirtyPathError(row.path, row.latestSeq, msg, now + DIRTY_RETRY_BACKOFF_MS);
+				log.warn(`dirty drain failed (backed off): ${row.path}`, msg);
+			}
+			if (processedRemaining <= 0 && noopRemaining <= 0) {
+				hasMore = true;
+				stopReason = "processed_budget";
+				break;
+			}
+		}
+		if (!stopReason) {
+			if (rows.length >= maxDirtyRows && maxDirtyRows > 0) {
+				if ((await dirtyQueue.listDirtyPaths({
+					prefix: "",
+					limit: 1,
+					now
+				})).length > 0) hasMore = true;
+			}
+			stopReason = hasMore ? "scan_budget" : "exhausted";
+		}
+		log.debug("dirty drain processed", {
+			consumerId: this.consumerId,
+			scanned,
+			processed,
+			noopProcessed,
+			indexed,
+			deleted,
+			nooped,
+			matched,
+			unmatched,
+			failed,
+			advanced,
+			hasMore,
+			ackRace,
+			stopReason
+		});
+		return {
+			scanned,
+			processed,
+			noopProcessed,
+			indexed,
+			deleted,
+			nooped,
+			advanced,
+			hasMore,
+			ackRace,
+			stopReason,
+			fromSeq: 0,
+			toSeq: 0,
+			matched,
+			unmatched,
+			skipped: 0,
+			failed,
+			aborted: false
+		};
+	}
+	/** Remove the indexed doc(s) for a delete/removed dirty row across matched domains. */
+	async removeDirty(matchedDomains, originalPath) {
+		for (const domain of matchedDomains) await this.removeIndexed(this.makeEntryPath(domain, originalPath), originalPath);
+	}
+	/** Shared index-removal (delete branch) — throws ChangelogAbortError on failure so the row backs off. */
+	async removeIndexed(entryPath, originalPath) {
+		try {
+			if (this.backend.removeIndexedDocument) await this.backend.removeIndexedDocument(entryPath);
+			else {
+				await this.backend.removeAnchors(entryPath);
+				await this.backend.removeSummary(entryPath);
+				await this.backend.removeEntry(entryPath);
+			}
+		} catch (err) {
+			throw new ChangelogAbortError(originalPath, `index delete failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	/**
+	* 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.
+	*/
+	async indexPutDirty(matchedDomains, originalPath) {
+		let live;
+		try {
+			live = (await this.spaceAfs.stat?.(toAbsolute(originalPath)))?.data;
+		} catch (err) {
+			if (err instanceof _aigne_afs.AFSNotFoundError) live = void 0;
+			else throw new ChangelogAbortError(originalPath, `stat failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (!live) {
+			await this.removeDirty(matchedDomains, originalPath);
+			return {
+				indexed: 0,
+				removed: 1
+			};
+		}
+		let indexed = 0;
+		for (const domain of matchedDomains) if (await this.indexEntry(domain, originalPath, this.makeEntryPath(domain, originalPath)) === "indexed") indexed++;
+		return {
+			indexed,
+			removed: 0
+		};
+	}
+	/**
+	* 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.
+	*/
+	async entryStillCurrent(originalPath) {
+		try {
+			return !!(await this.spaceAfs.stat?.(toAbsolute(originalPath)))?.data;
+		} catch {
+			return false;
+		}
+	}
+	pathMatchesDomain(originalPath, domain) {
+		if (!domain.indexable || domain.indexable.length === 0) return true;
+		return domain.indexable.some((pat) => matchGlob(originalPath, pat));
+	}
+	async indexEntry(domain, originalPath, entryPath) {
+		let content;
+		try {
+			const raw = (await this.spaceAfs.read?.(toAbsolute(originalPath)))?.data?.content;
+			if (typeof raw !== "string" || raw.length === 0) return "noop";
+			try {
+				content = JSON.parse(raw);
+			} catch {
+				content = raw;
+			}
+		} catch {
+			if (await this.entryStillCurrent(originalPath)) throw new ChangelogAbortError(originalPath);
+			return "noop";
+		}
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const anchors = [];
+		if (domain.fields && typeof content === "object" && content !== null) {
+			const fieldValues = require_field_map.applyFieldMap(content, domain.fields);
+			for (const [fieldName, values] of Object.entries(fieldValues)) for (const value of values) if (fieldName === "time") anchors.push({
+				type: "time",
+				confidence: 1,
+				timestamp: value
+			});
+			else anchors.push({
+				type: fieldName,
+				confidence: 1,
+				value
+			});
+		}
+		const entry = {
+			entryPath,
+			sourcePath: originalPath,
+			domain: domain.name,
+			state: "active",
+			indexedAt: now,
+			updatedAt: now,
+			anchorCount: anchors.length
+		};
+		let summary;
+		if (domain.summary) {
+			summary = require_field_map.extractSummaryText(content, domain.summary);
+			if (domain.enrich && typeof content === "object" && content !== null) summary = await require_field_map.applyEnrichContentFile({
+				afs: this.spaceAfs,
+				itemJson: content,
+				baseSummary: summary,
+				enrich: domain.enrich,
+				scope: domain.scope
+			});
+		}
+		try {
+			if (this.backend.writeIndexedDocument) await this.backend.writeIndexedDocument({
+				entry,
+				anchors,
+				summary
+			});
+			else {
+				await this.backend.writeEntry(entry);
+				await this.backend.writeAnchors(entryPath, anchors);
+				if (summary) await this.backend.writeSummary(entryPath, summary);
+			}
+		} catch (err) {
+			throw new ChangelogAbortError(originalPath, `index write failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (summary) {
+			if (this.embed && this.backend.writeEmbedding) try {
+				const vector = await this.embed(summary);
+				if (vector) await this.backend.writeEmbedding(entryPath, vector, domain.name);
+				else log.debug("embed skipped (embedder returned null)", { entryPath });
+			} catch (err) {
+				log.debug("embed failed (entry kept, FTS/anchor only)", {
+					entryPath,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+		}
+		return "indexed";
+	}
+	/**
+	* Build the stable index entry path for a file. Uses the domain scope
+	* (default "/user") as a prefix so query-scope filtering works.
+	*/
+	makeEntryPath(domain, originalPath) {
+		return (0, ufo.joinURL)(domain.scope ?? "/user", originalPath);
+	}
+};
+function matchGlob(path, pattern) {
+	const regexStr = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "⧫").replace(/\*/g, "[^/]*").replace(/⧫/g, ".*").replace(/\?/g, "[^/]");
+	return (/* @__PURE__ */ new RegExp(`(^|/)${regexStr}$`)).test(path);
+}
+
+//#endregion
+exports.DEFAULT_MAX_DIRTY_ROWS_PER_TICK = DEFAULT_MAX_DIRTY_ROWS_PER_TICK;
+exports.DEFAULT_MAX_NOOP_PER_TICK = DEFAULT_MAX_NOOP_PER_TICK;
+exports.DEFAULT_MAX_PROCESSED_PER_TICK = DEFAULT_MAX_PROCESSED_PER_TICK;
+exports.DEFAULT_MAX_SCAN_PER_TICK = DEFAULT_MAX_SCAN_PER_TICK;
+exports.FOLLOWER_CONSUMER_ID = FOLLOWER_CONSUMER_ID;
+exports.IndexFollower = IndexFollower;
+exports.deriveFollowerConsumerId = deriveFollowerConsumerId;
+exports.userIndexKey = userIndexKey;