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

package/dist/dirty-path-queue.d.mts

@@ -0,0 +1,104 @@
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/dirty-path-queue.d.ts
+/** Latest op merged for a dirty path. Mirrors `ds_changelog.op` / the CHECK. */
+type DirtyPathOp = "put" | "delete";
+/**
+ * A dirty row as handed to the follower. The follower uses `op/cid/latestSeq`
+ * for scheduling + the ack race-guard ONLY — it re-reads current live state
+ * before writing the index (design §4.3), so `cid` here is never trusted as the
+ * final content. `path` is the form the queue returns: full DID-space path from
+ * a raw backend, or the prefix-STRIPPED `originalPath` from
+ * {@link PrefixedTreeIndex} (e.g. `items/x.json`).
+ */
+interface DirtyPathRow {
+  path: string;
+  latestSeq: number;
+  op: DirtyPathOp;
+  cid?: string | null;
+  mtime: number;
+  attempts: number;
+}
+/**
+ * Full stored shape of a `ds_dirty_path` row (all columns). SQL backends store
+ * it as a table row; the Memory backend keeps a `Map<\`${scope}\0${path}\`,
+ * DirtyPathStoredRow>` and mutates it through {@link applyDirtyUpsert} so its
+ * merge/guard semantics match the D1/SQLite trigger byte-for-byte.
+ */
+interface DirtyPathStoredRow {
+  scope: string;
+  path: string;
+  latestSeq: number;
+  op: DirtyPathOp;
+  cid: string | null;
+  mtime: number;
+  updatedAt: number;
+  attempts: number;
+  nextAttemptAt: number;
+  lastError: string | null;
+}
+interface ListDirtyPathOptions {
+  /** Full DID-space path prefix to scan (e.g. `blocklets/{instanceDid}/user/`). */
+  prefix: string;
+  /** Max dirty rows to return this tick. */
+  limit: number;
+  /** Clock override (ms) for the `next_attempt_at <= now` ready filter; defaults to the wall clock. */
+  now?: number;
+}
+/**
+ * Source-side dirty queue — list ready rows, ack a processed row, or record a
+ * failed attempt. All three carry the `latestSeq` race guard (design §8): an
+ * ack/mark that targets a `latest_seq` a concurrent write has already superseded
+ * affects 0 rows and returns `false`, leaving the newer dirty row for the next
+ * tick.
+ */
+interface DirtyPathQueue {
+  /** Ready dirty rows under `prefix` with `next_attempt_at <= now`, capped at `limit`. */
+  listDirtyPaths(options: ListDirtyPathOptions): Promise<DirtyPathRow[]>;
+  /**
+   * Delete the dirty row for `path` iff its `latest_seq` still equals
+   * `latestSeq` (nothing newer arrived). Returns `true` when a row was removed,
+   * `false` when the guard lost (a newer write bumped latest_seq — leave it).
+   */
+  ackDirtyPath(path: string, latestSeq: number): Promise<boolean>;
+  /**
+   * Record a failed attempt: `attempts+1`, set `last_error`/`next_attempt_at`,
+   * guarded by the SAME `latest_seq` equality so a fresh write's reset is never
+   * clobbered. Returns `true` when the guarded row was updated.
+   */
+  markDirtyPathError(path: string, latestSeq: number, error: string, nextAttemptAt: number): Promise<boolean>;
+}
+/**
+ * The follower's two source planes, wired explicitly so the AFS read plane and
+ * the dirty ack plane never get conflated (design §7):
+ *   - `contentAfs`: read/stat CURRENT live content only.
+ *   - `dirtyQueue`: list/ack/fail dirty rows only.
+ * They may share one underlying source-side TreeIndex, but ack/fail is a
+ * runtime-internal capability — it is never exposed as a `/user` AFS action.
+ */
+interface DirtyPathFollowerSource {
+  contentAfs: AFSRoot;
+  dirtyQueue: DirtyPathQueue;
+}
+/**
+ * Apply one changelog-derived write to a Memory dirty map entry, reproducing the
+ * `ds_changelog_to_ds_dirty_path` trigger's merge/guard EXACTLY:
+ *   - no existing row → the incoming row (attempts/backoff/error zeroed).
+ *   - incoming.latestSeq > existing.latestSeq → overwrite + reset attempts/
+ *     next_attempt_at/last_error.
+ *   - stale incoming (seq <= existing) → keep existing unchanged (no rollback).
+ *
+ * Returned value is what the map should store for `(scope, path)`.
+ */
+declare function applyDirtyUpsert(existing: DirtyPathStoredRow | undefined, incoming: {
+  scope: string;
+  path: string;
+  latestSeq: number;
+  op: DirtyPathOp;
+  cid: string | null;
+  mtime: number;
+  updatedAt: number;
+}): DirtyPathStoredRow;
+//#endregion
+export { DirtyPathFollowerSource, DirtyPathOp, DirtyPathQueue, DirtyPathRow, DirtyPathStoredRow, ListDirtyPathOptions, applyDirtyUpsert };
+//# sourceMappingURL=dirty-path-queue.d.mts.map

package/dist/dirty-path-queue.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-path-queue.d.mts","names":[],"sources":["../src/dirty-path-queue.ts"],"mappings":";;;;KAwCY,WAAA;;;;;;;;;UAUK,YAAA;EACf,IAAA;EACA,SAAA;EACA,EAAA,EAAI,WAAA;EACJ,GAAA;EACA,KAAA;EACA,QAAA;AAAA;;;;;;;UASe,kBAAA;EACf,KAAA;EACA,IAAA;EACA,SAAA;EACA,EAAA,EAAI,WAAA;EACJ,GAAA;EACA,KAAA;EACA,SAAA;EACA,QAAA;EACA,aAAA;EACA,SAAA;AAAA;AAAA,UAGe,oBAAA;EA8CA;EA5Cf,MAAA;;EAEA,KAAA;EA2CA;EAzCA,GAAA;AAAA;;;;AAuDF;;;;UA7CiB,cAAA;EAwDd;EAtDD,cAAA,CAAe,OAAA,EAAS,oBAAA,GAAuB,OAAA,CAAQ,YAAA;EAsDpC;;;;;EAhDnB,YAAA,CAAa,IAAA,UAAc,SAAA,WAAoB,OAAA;EA2C7C;;;;;EArCF,kBAAA,CACE,IAAA,UACA,SAAA,UACA,KAAA,UACA,aAAA,WACC,OAAA;AAAA;;;;;;;;;UAWY,uBAAA;EACf,UAAA,EAAY,OAAA;EACZ,UAAA,EAAY,cAAA;AAAA;;;;;;;;;;;iBAaE,gBAAA,CACd,QAAA,EAAU,kBAAA,cACV,QAAA;EACE,KAAA;EACA,IAAA;EACA,SAAA;EACA,EAAA,EAAI,WAAA;EACJ,GAAA;EACA,KAAA;EACA,SAAA;AAAA,IAED,kBAAA"}

package/dist/dirty-path-queue.mjs

@@ -0,0 +1,31 @@
+//#region src/dirty-path-queue.ts
+/**
+* Apply one changelog-derived write to a Memory dirty map entry, reproducing the
+* `ds_changelog_to_ds_dirty_path` trigger's merge/guard EXACTLY:
+*   - no existing row → the incoming row (attempts/backoff/error zeroed).
+*   - incoming.latestSeq > existing.latestSeq → overwrite + reset attempts/
+*     next_attempt_at/last_error.
+*   - stale incoming (seq <= existing) → keep existing unchanged (no rollback).
+*
+* Returned value is what the map should store for `(scope, path)`.
+*/
+function applyDirtyUpsert(existing, incoming) {
+	const next = {
+		scope: incoming.scope,
+		path: incoming.path,
+		latestSeq: incoming.latestSeq,
+		op: incoming.op,
+		cid: incoming.cid,
+		mtime: incoming.mtime,
+		updatedAt: incoming.updatedAt,
+		attempts: 0,
+		nextAttemptAt: 0,
+		lastError: null
+	};
+	if (!existing) return next;
+	return incoming.latestSeq > existing.latestSeq ? next : existing;
+}
+
+//#endregion
+export { applyDirtyUpsert };
+//# sourceMappingURL=dirty-path-queue.mjs.map

package/dist/dirty-path-queue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-path-queue.mjs","names":[],"sources":["../src/dirty-path-queue.ts"],"sourcesContent":["/**\n * Dirty-path queue contract — the internal source-side interface the index\n * follower drains instead of replaying `/.changelog`\n * (planning/index-provider/dirty-path-follower, design §7).\n *\n * This is deliberately NOT a public AFS action. `ackDirtyPath` /\n * `markDirtyPathError` MUTATE source-side scheduling state and must never be\n * reachable by an ordinary `/user` client (design §7 security boundary). The\n * runtime wires it inside the worker/daemon (Phase 3); the follower holds a\n * {@link DirtyPathQueue} handle, the same source-side TreeIndex that owns the\n * `ds_dirty_path` rows.\n *\n * ── Cursor semantics after cutover (design §4.2, defined here, enforced in\n *    Phase 2/3) ──\n * `idx_index_cursor` still registers/schedules followers, but once the changelog\n * replay drain is deleted (Phase 4) NOTHING advances `idx_index_cursor.last_seq`\n * — it becomes a DEAD COLUMN kept only for schema/log compatibility. Freshness\n * is \"are there ready dirty rows under my prefix?\", NOT a `last_seq` probe.\n * Fairness rides `served_at`, which dirty mode updates via `markCursorServed`\n * UNCONDITIONALLY every drain (not the changelog era's `!advanced` gate — an\n * always-active scope would otherwise freeze at the front of the queue).\n *\n * ── `IndexFollowerBatchResult` in dirty mode (design §8, defined here,\n *    consumed by Phase 2) ──\n *   - `scanned`     : dirty rows inspected this tick (NOT changelog rows).\n *   - `processed`   : put dirty rows that indexed current live content.\n *   - `noopProcessed`: delete / live-missing / non-indexable rows acked as noop.\n *   - `advanced`    : ≥1 dirty row acked (or an ack guard-lost to a confirmed\n *                     newer latest_seq); mark-error does NOT count as advanced.\n *   - `hasMore`     : ready dirty rows remain under the prefix, or the tick\n *                     stopped on budget.\n *   - `fromSeq/toSeq`: log-compat only; dirty mode never writes `last_seq`.\n * Round-robin scheduling keys off `advanced/hasMore/scanned` + dirty count, so a\n * poison row (mark-error, `advanced=false`, `hasMore=true`) does not busy-loop a\n * single tick, and a scope with ready rows still gets requeued.\n */\n\nimport type { AFSRoot } from \"@aigne/afs\";\n\n/** Latest op merged for a dirty path. Mirrors `ds_changelog.op` / the CHECK. */\nexport type DirtyPathOp = \"put\" | \"delete\";\n\n/**\n * A dirty row as handed to the follower. The follower uses `op/cid/latestSeq`\n * for scheduling + the ack race-guard ONLY — it re-reads current live state\n * before writing the index (design §4.3), so `cid` here is never trusted as the\n * final content. `path` is the form the queue returns: full DID-space path from\n * a raw backend, or the prefix-STRIPPED `originalPath` from\n * {@link PrefixedTreeIndex} (e.g. `items/x.json`).\n */\nexport interface DirtyPathRow {\n  path: string;\n  latestSeq: number;\n  op: DirtyPathOp;\n  cid?: string | null;\n  mtime: number;\n  attempts: number;\n}\n\n/**\n * Full stored shape of a `ds_dirty_path` row (all columns). SQL backends store\n * it as a table row; the Memory backend keeps a `Map<\\`${scope}\\0${path}\\`,\n * DirtyPathStoredRow>` and mutates it through {@link applyDirtyUpsert} so its\n * merge/guard semantics match the D1/SQLite trigger byte-for-byte.\n */\nexport interface DirtyPathStoredRow {\n  scope: string;\n  path: string;\n  latestSeq: number;\n  op: DirtyPathOp;\n  cid: string | null;\n  mtime: number;\n  updatedAt: number;\n  attempts: number;\n  nextAttemptAt: number;\n  lastError: string | null;\n}\n\nexport interface ListDirtyPathOptions {\n  /** Full DID-space path prefix to scan (e.g. `blocklets/{instanceDid}/user/`). */\n  prefix: string;\n  /** Max dirty rows to return this tick. */\n  limit: number;\n  /** Clock override (ms) for the `next_attempt_at <= now` ready filter; defaults to the wall clock. */\n  now?: number;\n}\n\n/**\n * Source-side dirty queue — list ready rows, ack a processed row, or record a\n * failed attempt. All three carry the `latestSeq` race guard (design §8): an\n * ack/mark that targets a `latest_seq` a concurrent write has already superseded\n * affects 0 rows and returns `false`, leaving the newer dirty row for the next\n * tick.\n */\nexport interface DirtyPathQueue {\n  /** Ready dirty rows under `prefix` with `next_attempt_at <= now`, capped at `limit`. */\n  listDirtyPaths(options: ListDirtyPathOptions): Promise<DirtyPathRow[]>;\n  /**\n   * Delete the dirty row for `path` iff its `latest_seq` still equals\n   * `latestSeq` (nothing newer arrived). Returns `true` when a row was removed,\n   * `false` when the guard lost (a newer write bumped latest_seq — leave it).\n   */\n  ackDirtyPath(path: string, latestSeq: number): Promise<boolean>;\n  /**\n   * Record a failed attempt: `attempts+1`, set `last_error`/`next_attempt_at`,\n   * guarded by the SAME `latest_seq` equality so a fresh write's reset is never\n   * clobbered. Returns `true` when the guarded row was updated.\n   */\n  markDirtyPathError(\n    path: string,\n    latestSeq: number,\n    error: string,\n    nextAttemptAt: number,\n  ): Promise<boolean>;\n}\n\n/**\n * The follower's two source planes, wired explicitly so the AFS read plane and\n * the dirty ack plane never get conflated (design §7):\n *   - `contentAfs`: read/stat CURRENT live content only.\n *   - `dirtyQueue`: list/ack/fail dirty rows only.\n * They may share one underlying source-side TreeIndex, but ack/fail is a\n * runtime-internal capability — it is never exposed as a `/user` AFS action.\n */\nexport interface DirtyPathFollowerSource {\n  contentAfs: AFSRoot;\n  dirtyQueue: DirtyPathQueue;\n}\n\n/**\n * Apply one changelog-derived write to a Memory dirty map entry, reproducing the\n * `ds_changelog_to_ds_dirty_path` trigger's merge/guard EXACTLY:\n *   - no existing row → the incoming row (attempts/backoff/error zeroed).\n *   - incoming.latestSeq > existing.latestSeq → overwrite + reset attempts/\n *     next_attempt_at/last_error.\n *   - stale incoming (seq <= existing) → keep existing unchanged (no rollback).\n *\n * Returned value is what the map should store for `(scope, path)`.\n */\nexport function applyDirtyUpsert(\n  existing: DirtyPathStoredRow | undefined,\n  incoming: {\n    scope: string;\n    path: string;\n    latestSeq: number;\n    op: DirtyPathOp;\n    cid: string | null;\n    mtime: number;\n    updatedAt: number;\n  },\n): DirtyPathStoredRow {\n  const next: DirtyPathStoredRow = {\n    scope: incoming.scope,\n    path: incoming.path,\n    latestSeq: incoming.latestSeq,\n    op: incoming.op,\n    cid: incoming.cid,\n    mtime: incoming.mtime,\n    updatedAt: incoming.updatedAt,\n    attempts: 0,\n    nextAttemptAt: 0,\n    lastError: null,\n  };\n  if (!existing) return next;\n  // Trigger guard: WHERE excluded.latest_seq > ds_dirty_path.latest_seq.\n  return incoming.latestSeq > existing.latestSeq ? next : existing;\n}\n"],"mappings":";;;;;;;;;;;AA2IA,SAAgB,iBACd,UACA,UASoB;CACpB,MAAM,OAA2B;EAC/B,OAAO,SAAS;EAChB,MAAM,SAAS;EACf,WAAW,SAAS;EACpB,IAAI,SAAS;EACb,KAAK,SAAS;EACd,OAAO,SAAS;EAChB,WAAW,SAAS;EACpB,UAAU;EACV,eAAe;EACf,WAAW;EACZ;AACD,KAAI,CAAC,SAAU,QAAO;AAEtB,QAAO,SAAS,YAAY,SAAS,YAAY,OAAO"}

package/dist/dirty-path-schema.cjs

@@ -0,0 +1,142 @@
+
+//#region src/dirty-path-schema.ts
+/**
+* ds_dirty_path schema — single source of truth for the index-follower dirty
+* queue (planning/index-provider/dirty-path-follower).
+*
+* `ds_dirty_path` is a SOURCE-SIDE derived projection of `ds_changelog`: one row
+* per `(scope, path)` recording the CURRENT op/latest_seq that still needs
+* materialising into the index. It replaces the follower's `O(changelog rows)`
+* replay with an `O(unique dirty paths)` drain (design §1-§4).
+*
+* Physical placement follows the CLAUDE.md D1-table-naming rule: it lives beside
+* `ds_changelog` in the DID Space metadata DB (CF: D1; Node: each user's
+* `_metadata.db`) — the ONLY place it can stay atomically consistent with the
+* changelog via an `AFTER INSERT` trigger — so it carries the `ds_` (DID Space)
+* prefix even though it logically serves the index provider.
+*
+* This module is the ONE definition of the DDL. It is materialised by:
+*   - CF     : a numbered D1 migration (Phase 4) that runs these statements.
+*   - Node   : `metadata-db.ts` ensureSchema (Phase 1), which has no migration
+*              runner and CREATEs tables on DB open.
+*   - tests  : every phase's D1 (miniflare / mock-d1) + libsql setup runs these
+*              statements directly (raw DDL, NOT via a numbered migration) so
+*              Phase 0-3 can exercise the trigger before Phase 4 exists.
+* All four import THESE constants — never re-spell the SQL — so the trigger
+* guard, CHECK, and column list can never drift across runtimes.
+*/
+/**
+* CREATE TABLE statement. Idempotent (`IF NOT EXISTS`).
+*
+* Columns (design §5):
+*   - scope           : DID Space scope, mirrors `ds_changelog.scope`.
+*   - path            : full DID-space path, e.g. `blocklets/{did}/user/items/x.json`.
+*   - latest_seq      : max `ds_changelog.seq` this path has merged to (race guard).
+*   - op              : latest op, `put` | `delete` (CHECK-constrained).
+*   - cid             : latest cid; NULL on delete.
+*   - mtime           : latest changelog mtime.
+*   - updated_at      : last upsert/reset time (ms) — scheduling + observability.
+*   - attempts        : consecutive failures (poison-row backoff).
+*   - next_attempt_at : retry-backoff watermark; a row with next_attempt_at > now
+*                       is skipped so a poison row never fills a tick's budget.
+*   - last_error      : most recent failure summary.
+*
+* PRIMARY KEY(scope, path) is what makes the trigger's `ON CONFLICT(scope, path)`
+* merge N changelog rows for one path into a single dirty row.
+*/
+const DIRTY_PATH_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_dirty_path (
+  scope TEXT NOT NULL,
+  path TEXT NOT NULL,
+  latest_seq INTEGER NOT NULL,
+  op TEXT NOT NULL CHECK (op IN ('put', 'delete')),
+  cid TEXT,
+  mtime INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  PRIMARY KEY(scope, path)
+)`;
+/**
+* CREATE INDEX statements. The `(scope, next_attempt_at, updated_at)` index
+* serves the follower's ready-row scan: scope equality, `next_attempt_at <= now`
+* range, `updated_at` tiebreak — an index-only ordered seek instead of a scope
+* full-scan on every tick.
+*/
+const DIRTY_PATH_INDEX_SQL = ["CREATE INDEX IF NOT EXISTS ds_dirty_path_scope_retry ON ds_dirty_path(scope, next_attempt_at, updated_at)"];
+/**
+* The `AFTER INSERT ON ds_changelog` trigger that derives dirty rows.
+*
+* Because it hangs off the changelog INSERT, it covers EVERY changelog write
+* face by construction (design §6) — the 6 TreeIndex methods AND the metadata-db
+* direct writes — with no need to enumerate write sites (that enumeration is the
+* §6 fallback, only for a runtime whose trigger support is inadequate).
+*
+* Merge/guard semantics (mirrored in-process by {@link applyDirtyUpsert} for the
+* Memory backend, so all three backends stay in lockstep):
+*   - first write for a path → INSERT the dirty row.
+*   - later write with a GREATER seq → overwrite op/cid/mtime/latest_seq and
+*     RESET attempts/next_attempt_at/last_error (a fresh write clears prior
+*     failure/backoff state).
+*   - a stale write (seq <= current latest_seq) → the
+*     `WHERE excluded.latest_seq > ds_dirty_path.latest_seq` guard makes it a
+*     no-op; latest_seq NEVER rolls backwards.
+*
+* NOTE: the body contains inner `;` (required by the trigger grammar). Any SQL
+* splitter feeding this to D1 one statement at a time MUST keep the whole
+* `CREATE TRIGGER … BEGIN … END` block intact — same rule as the existing
+* `SCOPE_META_FILE_COUNT_TRIGGER_SQL` (see apply-d1-migrations.mjs
+* splitSqlStatements).
+*
+* `strftime('%s','now')` is second-granularity → *1000 for a millis `updated_at`
+* that reads uniformly with the app-clock millis the SQL/Memory backends write.
+*/
+const DIRTY_PATH_TRIGGER_SQL = [`CREATE TRIGGER IF NOT EXISTS ds_changelog_to_ds_dirty_path
+   AFTER INSERT ON ds_changelog
+   BEGIN
+     INSERT INTO ds_dirty_path (
+       scope, path, latest_seq, op, cid, mtime, updated_at, attempts, next_attempt_at, last_error
+     )
+     VALUES (
+       NEW.scope, NEW.path, NEW.seq, NEW.op, NEW.cid, NEW.mtime,
+       CAST(strftime('%s', 'now') AS INTEGER) * 1000, 0, 0, NULL
+     )
+     ON CONFLICT(scope, path) DO UPDATE SET
+       latest_seq = excluded.latest_seq,
+       op = excluded.op,
+       cid = excluded.cid,
+       mtime = excluded.mtime,
+       updated_at = excluded.updated_at,
+       attempts = 0,
+       next_attempt_at = 0,
+       last_error = NULL
+     WHERE excluded.latest_seq > ds_dirty_path.latest_seq;
+   END`];
+/**
+* Full DDL sequence (table → index → trigger) in dependency order. Test setups
+* and the Node ensureSchema loop run this after the `ds_changelog` DDL (the
+* trigger references `ds_changelog`, so the changelog table must exist first).
+*/
+const DIRTY_PATH_DDL = [
+	DIRTY_PATH_TABLE_SQL,
+	...DIRTY_PATH_INDEX_SQL,
+	...DIRTY_PATH_TRIGGER_SQL
+];
+/** Ready dirty rows under a prefix. Binds: `(scope, lo, hi, now, limit)`. */
+const DIRTY_PATH_LIST_SQL = `SELECT path, latest_seq, op, cid, mtime, attempts FROM ds_dirty_path INDEXED BY ds_dirty_path_scope_retry
+  WHERE scope = ? AND path >= ? AND path < ? AND next_attempt_at <= ?
+  ORDER BY next_attempt_at ASC, updated_at ASC LIMIT ?`;
+/** Guarded ack (delete iff latest_seq unchanged). Binds: `(scope, path, latestSeq)`. */
+const DIRTY_PATH_ACK_SQL = "DELETE FROM ds_dirty_path WHERE scope = ? AND path = ? AND latest_seq = ?";
+/** Guarded failure record. Binds: `(error, nextAttemptAt, scope, path, latestSeq)`. */
+const DIRTY_PATH_MARK_ERROR_SQL = `UPDATE ds_dirty_path SET attempts = attempts + 1, last_error = ?, next_attempt_at = ?
+  WHERE scope = ? AND path = ? AND latest_seq = ?`;
+
+//#endregion
+exports.DIRTY_PATH_ACK_SQL = DIRTY_PATH_ACK_SQL;
+exports.DIRTY_PATH_DDL = DIRTY_PATH_DDL;
+exports.DIRTY_PATH_INDEX_SQL = DIRTY_PATH_INDEX_SQL;
+exports.DIRTY_PATH_LIST_SQL = DIRTY_PATH_LIST_SQL;
+exports.DIRTY_PATH_MARK_ERROR_SQL = DIRTY_PATH_MARK_ERROR_SQL;
+exports.DIRTY_PATH_TABLE_SQL = DIRTY_PATH_TABLE_SQL;
+exports.DIRTY_PATH_TRIGGER_SQL = DIRTY_PATH_TRIGGER_SQL;

package/dist/dirty-path-schema.d.cts

@@ -0,0 +1,90 @@
+//#region src/dirty-path-schema.d.ts
+/**
+ * ds_dirty_path schema — single source of truth for the index-follower dirty
+ * queue (planning/index-provider/dirty-path-follower).
+ *
+ * `ds_dirty_path` is a SOURCE-SIDE derived projection of `ds_changelog`: one row
+ * per `(scope, path)` recording the CURRENT op/latest_seq that still needs
+ * materialising into the index. It replaces the follower's `O(changelog rows)`
+ * replay with an `O(unique dirty paths)` drain (design §1-§4).
+ *
+ * Physical placement follows the CLAUDE.md D1-table-naming rule: it lives beside
+ * `ds_changelog` in the DID Space metadata DB (CF: D1; Node: each user's
+ * `_metadata.db`) — the ONLY place it can stay atomically consistent with the
+ * changelog via an `AFTER INSERT` trigger — so it carries the `ds_` (DID Space)
+ * prefix even though it logically serves the index provider.
+ *
+ * This module is the ONE definition of the DDL. It is materialised by:
+ *   - CF     : a numbered D1 migration (Phase 4) that runs these statements.
+ *   - Node   : `metadata-db.ts` ensureSchema (Phase 1), which has no migration
+ *              runner and CREATEs tables on DB open.
+ *   - tests  : every phase's D1 (miniflare / mock-d1) + libsql setup runs these
+ *              statements directly (raw DDL, NOT via a numbered migration) so
+ *              Phase 0-3 can exercise the trigger before Phase 4 exists.
+ * All four import THESE constants — never re-spell the SQL — so the trigger
+ * guard, CHECK, and column list can never drift across runtimes.
+ */
+/**
+ * CREATE TABLE statement. Idempotent (`IF NOT EXISTS`).
+ *
+ * Columns (design §5):
+ *   - scope           : DID Space scope, mirrors `ds_changelog.scope`.
+ *   - path            : full DID-space path, e.g. `blocklets/{did}/user/items/x.json`.
+ *   - latest_seq      : max `ds_changelog.seq` this path has merged to (race guard).
+ *   - op              : latest op, `put` | `delete` (CHECK-constrained).
+ *   - cid             : latest cid; NULL on delete.
+ *   - mtime           : latest changelog mtime.
+ *   - updated_at      : last upsert/reset time (ms) — scheduling + observability.
+ *   - attempts        : consecutive failures (poison-row backoff).
+ *   - next_attempt_at : retry-backoff watermark; a row with next_attempt_at > now
+ *                       is skipped so a poison row never fills a tick's budget.
+ *   - last_error      : most recent failure summary.
+ *
+ * PRIMARY KEY(scope, path) is what makes the trigger's `ON CONFLICT(scope, path)`
+ * merge N changelog rows for one path into a single dirty row.
+ */
+declare const DIRTY_PATH_TABLE_SQL = "CREATE TABLE IF NOT EXISTS ds_dirty_path (\n  scope TEXT NOT NULL,\n  path TEXT NOT NULL,\n  latest_seq INTEGER NOT NULL,\n  op TEXT NOT NULL CHECK (op IN ('put', 'delete')),\n  cid TEXT,\n  mtime INTEGER NOT NULL,\n  updated_at INTEGER NOT NULL,\n  attempts INTEGER NOT NULL DEFAULT 0,\n  next_attempt_at INTEGER NOT NULL DEFAULT 0,\n  last_error TEXT,\n  PRIMARY KEY(scope, path)\n)";
+/**
+ * CREATE INDEX statements. The `(scope, next_attempt_at, updated_at)` index
+ * serves the follower's ready-row scan: scope equality, `next_attempt_at <= now`
+ * range, `updated_at` tiebreak — an index-only ordered seek instead of a scope
+ * full-scan on every tick.
+ */
+declare const DIRTY_PATH_INDEX_SQL: readonly string[];
+/**
+ * The `AFTER INSERT ON ds_changelog` trigger that derives dirty rows.
+ *
+ * Because it hangs off the changelog INSERT, it covers EVERY changelog write
+ * face by construction (design §6) — the 6 TreeIndex methods AND the metadata-db
+ * direct writes — with no need to enumerate write sites (that enumeration is the
+ * §6 fallback, only for a runtime whose trigger support is inadequate).
+ *
+ * Merge/guard semantics (mirrored in-process by {@link applyDirtyUpsert} for the
+ * Memory backend, so all three backends stay in lockstep):
+ *   - first write for a path → INSERT the dirty row.
+ *   - later write with a GREATER seq → overwrite op/cid/mtime/latest_seq and
+ *     RESET attempts/next_attempt_at/last_error (a fresh write clears prior
+ *     failure/backoff state).
+ *   - a stale write (seq <= current latest_seq) → the
+ *     `WHERE excluded.latest_seq > ds_dirty_path.latest_seq` guard makes it a
+ *     no-op; latest_seq NEVER rolls backwards.
+ *
+ * NOTE: the body contains inner `;` (required by the trigger grammar). Any SQL
+ * splitter feeding this to D1 one statement at a time MUST keep the whole
+ * `CREATE TRIGGER … BEGIN … END` block intact — same rule as the existing
+ * `SCOPE_META_FILE_COUNT_TRIGGER_SQL` (see apply-d1-migrations.mjs
+ * splitSqlStatements).
+ *
+ * `strftime('%s','now')` is second-granularity → *1000 for a millis `updated_at`
+ * that reads uniformly with the app-clock millis the SQL/Memory backends write.
+ */
+declare const DIRTY_PATH_TRIGGER_SQL: readonly string[];
+/**
+ * Full DDL sequence (table → index → trigger) in dependency order. Test setups
+ * and the Node ensureSchema loop run this after the `ds_changelog` DDL (the
+ * trigger references `ds_changelog`, so the changelog table must exist first).
+ */
+declare const DIRTY_PATH_DDL: readonly string[];
+//#endregion
+export { DIRTY_PATH_DDL, DIRTY_PATH_INDEX_SQL, DIRTY_PATH_TABLE_SQL, DIRTY_PATH_TRIGGER_SQL };
+//# sourceMappingURL=dirty-path-schema.d.cts.map

package/dist/dirty-path-schema.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-path-schema.d.cts","names":[],"sources":["../src/dirty-path-schema.ts"],"mappings":";;AA6CA;;;;;AAoBA;;;;;AA+BA;;;;;AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAhFa,oBAAA;;;;;;;cAoBA,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BA,sBAAA;;;;;;cA6BA,cAAA"}

package/dist/dirty-path-schema.d.mts

@@ -0,0 +1,90 @@
+//#region src/dirty-path-schema.d.ts
+/**
+ * ds_dirty_path schema — single source of truth for the index-follower dirty
+ * queue (planning/index-provider/dirty-path-follower).
+ *
+ * `ds_dirty_path` is a SOURCE-SIDE derived projection of `ds_changelog`: one row
+ * per `(scope, path)` recording the CURRENT op/latest_seq that still needs
+ * materialising into the index. It replaces the follower's `O(changelog rows)`
+ * replay with an `O(unique dirty paths)` drain (design §1-§4).
+ *
+ * Physical placement follows the CLAUDE.md D1-table-naming rule: it lives beside
+ * `ds_changelog` in the DID Space metadata DB (CF: D1; Node: each user's
+ * `_metadata.db`) — the ONLY place it can stay atomically consistent with the
+ * changelog via an `AFTER INSERT` trigger — so it carries the `ds_` (DID Space)
+ * prefix even though it logically serves the index provider.
+ *
+ * This module is the ONE definition of the DDL. It is materialised by:
+ *   - CF     : a numbered D1 migration (Phase 4) that runs these statements.
+ *   - Node   : `metadata-db.ts` ensureSchema (Phase 1), which has no migration
+ *              runner and CREATEs tables on DB open.
+ *   - tests  : every phase's D1 (miniflare / mock-d1) + libsql setup runs these
+ *              statements directly (raw DDL, NOT via a numbered migration) so
+ *              Phase 0-3 can exercise the trigger before Phase 4 exists.
+ * All four import THESE constants — never re-spell the SQL — so the trigger
+ * guard, CHECK, and column list can never drift across runtimes.
+ */
+/**
+ * CREATE TABLE statement. Idempotent (`IF NOT EXISTS`).
+ *
+ * Columns (design §5):
+ *   - scope           : DID Space scope, mirrors `ds_changelog.scope`.
+ *   - path            : full DID-space path, e.g. `blocklets/{did}/user/items/x.json`.
+ *   - latest_seq      : max `ds_changelog.seq` this path has merged to (race guard).
+ *   - op              : latest op, `put` | `delete` (CHECK-constrained).
+ *   - cid             : latest cid; NULL on delete.
+ *   - mtime           : latest changelog mtime.
+ *   - updated_at      : last upsert/reset time (ms) — scheduling + observability.
+ *   - attempts        : consecutive failures (poison-row backoff).
+ *   - next_attempt_at : retry-backoff watermark; a row with next_attempt_at > now
+ *                       is skipped so a poison row never fills a tick's budget.
+ *   - last_error      : most recent failure summary.
+ *
+ * PRIMARY KEY(scope, path) is what makes the trigger's `ON CONFLICT(scope, path)`
+ * merge N changelog rows for one path into a single dirty row.
+ */
+declare const DIRTY_PATH_TABLE_SQL = "CREATE TABLE IF NOT EXISTS ds_dirty_path (\n  scope TEXT NOT NULL,\n  path TEXT NOT NULL,\n  latest_seq INTEGER NOT NULL,\n  op TEXT NOT NULL CHECK (op IN ('put', 'delete')),\n  cid TEXT,\n  mtime INTEGER NOT NULL,\n  updated_at INTEGER NOT NULL,\n  attempts INTEGER NOT NULL DEFAULT 0,\n  next_attempt_at INTEGER NOT NULL DEFAULT 0,\n  last_error TEXT,\n  PRIMARY KEY(scope, path)\n)";
+/**
+ * CREATE INDEX statements. The `(scope, next_attempt_at, updated_at)` index
+ * serves the follower's ready-row scan: scope equality, `next_attempt_at <= now`
+ * range, `updated_at` tiebreak — an index-only ordered seek instead of a scope
+ * full-scan on every tick.
+ */
+declare const DIRTY_PATH_INDEX_SQL: readonly string[];
+/**
+ * The `AFTER INSERT ON ds_changelog` trigger that derives dirty rows.
+ *
+ * Because it hangs off the changelog INSERT, it covers EVERY changelog write
+ * face by construction (design §6) — the 6 TreeIndex methods AND the metadata-db
+ * direct writes — with no need to enumerate write sites (that enumeration is the
+ * §6 fallback, only for a runtime whose trigger support is inadequate).
+ *
+ * Merge/guard semantics (mirrored in-process by {@link applyDirtyUpsert} for the
+ * Memory backend, so all three backends stay in lockstep):
+ *   - first write for a path → INSERT the dirty row.
+ *   - later write with a GREATER seq → overwrite op/cid/mtime/latest_seq and
+ *     RESET attempts/next_attempt_at/last_error (a fresh write clears prior
+ *     failure/backoff state).
+ *   - a stale write (seq <= current latest_seq) → the
+ *     `WHERE excluded.latest_seq > ds_dirty_path.latest_seq` guard makes it a
+ *     no-op; latest_seq NEVER rolls backwards.
+ *
+ * NOTE: the body contains inner `;` (required by the trigger grammar). Any SQL
+ * splitter feeding this to D1 one statement at a time MUST keep the whole
+ * `CREATE TRIGGER … BEGIN … END` block intact — same rule as the existing
+ * `SCOPE_META_FILE_COUNT_TRIGGER_SQL` (see apply-d1-migrations.mjs
+ * splitSqlStatements).
+ *
+ * `strftime('%s','now')` is second-granularity → *1000 for a millis `updated_at`
+ * that reads uniformly with the app-clock millis the SQL/Memory backends write.
+ */
+declare const DIRTY_PATH_TRIGGER_SQL: readonly string[];
+/**
+ * Full DDL sequence (table → index → trigger) in dependency order. Test setups
+ * and the Node ensureSchema loop run this after the `ds_changelog` DDL (the
+ * trigger references `ds_changelog`, so the changelog table must exist first).
+ */
+declare const DIRTY_PATH_DDL: readonly string[];
+//#endregion
+export { DIRTY_PATH_DDL, DIRTY_PATH_INDEX_SQL, DIRTY_PATH_TABLE_SQL, DIRTY_PATH_TRIGGER_SQL };
+//# sourceMappingURL=dirty-path-schema.d.mts.map

package/dist/dirty-path-schema.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-path-schema.d.mts","names":[],"sources":["../src/dirty-path-schema.ts"],"mappings":";;AA6CA;;;;;AAoBA;;;;;AA+BA;;;;;AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAhFa,oBAAA;;;;;;;cAoBA,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BA,sBAAA;;;;;;cA6BA,cAAA"}

package/dist/dirty-path-schema.mjs

@@ -0,0 +1,136 @@
+//#region src/dirty-path-schema.ts
+/**
+* ds_dirty_path schema — single source of truth for the index-follower dirty
+* queue (planning/index-provider/dirty-path-follower).
+*
+* `ds_dirty_path` is a SOURCE-SIDE derived projection of `ds_changelog`: one row
+* per `(scope, path)` recording the CURRENT op/latest_seq that still needs
+* materialising into the index. It replaces the follower's `O(changelog rows)`
+* replay with an `O(unique dirty paths)` drain (design §1-§4).
+*
+* Physical placement follows the CLAUDE.md D1-table-naming rule: it lives beside
+* `ds_changelog` in the DID Space metadata DB (CF: D1; Node: each user's
+* `_metadata.db`) — the ONLY place it can stay atomically consistent with the
+* changelog via an `AFTER INSERT` trigger — so it carries the `ds_` (DID Space)
+* prefix even though it logically serves the index provider.
+*
+* This module is the ONE definition of the DDL. It is materialised by:
+*   - CF     : a numbered D1 migration (Phase 4) that runs these statements.
+*   - Node   : `metadata-db.ts` ensureSchema (Phase 1), which has no migration
+*              runner and CREATEs tables on DB open.
+*   - tests  : every phase's D1 (miniflare / mock-d1) + libsql setup runs these
+*              statements directly (raw DDL, NOT via a numbered migration) so
+*              Phase 0-3 can exercise the trigger before Phase 4 exists.
+* All four import THESE constants — never re-spell the SQL — so the trigger
+* guard, CHECK, and column list can never drift across runtimes.
+*/
+/**
+* CREATE TABLE statement. Idempotent (`IF NOT EXISTS`).
+*
+* Columns (design §5):
+*   - scope           : DID Space scope, mirrors `ds_changelog.scope`.
+*   - path            : full DID-space path, e.g. `blocklets/{did}/user/items/x.json`.
+*   - latest_seq      : max `ds_changelog.seq` this path has merged to (race guard).
+*   - op              : latest op, `put` | `delete` (CHECK-constrained).
+*   - cid             : latest cid; NULL on delete.
+*   - mtime           : latest changelog mtime.
+*   - updated_at      : last upsert/reset time (ms) — scheduling + observability.
+*   - attempts        : consecutive failures (poison-row backoff).
+*   - next_attempt_at : retry-backoff watermark; a row with next_attempt_at > now
+*                       is skipped so a poison row never fills a tick's budget.
+*   - last_error      : most recent failure summary.
+*
+* PRIMARY KEY(scope, path) is what makes the trigger's `ON CONFLICT(scope, path)`
+* merge N changelog rows for one path into a single dirty row.
+*/
+const DIRTY_PATH_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_dirty_path (
+  scope TEXT NOT NULL,
+  path TEXT NOT NULL,
+  latest_seq INTEGER NOT NULL,
+  op TEXT NOT NULL CHECK (op IN ('put', 'delete')),
+  cid TEXT,
+  mtime INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  PRIMARY KEY(scope, path)
+)`;
+/**
+* CREATE INDEX statements. The `(scope, next_attempt_at, updated_at)` index
+* serves the follower's ready-row scan: scope equality, `next_attempt_at <= now`
+* range, `updated_at` tiebreak — an index-only ordered seek instead of a scope
+* full-scan on every tick.
+*/
+const DIRTY_PATH_INDEX_SQL = ["CREATE INDEX IF NOT EXISTS ds_dirty_path_scope_retry ON ds_dirty_path(scope, next_attempt_at, updated_at)"];
+/**
+* The `AFTER INSERT ON ds_changelog` trigger that derives dirty rows.
+*
+* Because it hangs off the changelog INSERT, it covers EVERY changelog write
+* face by construction (design §6) — the 6 TreeIndex methods AND the metadata-db
+* direct writes — with no need to enumerate write sites (that enumeration is the
+* §6 fallback, only for a runtime whose trigger support is inadequate).
+*
+* Merge/guard semantics (mirrored in-process by {@link applyDirtyUpsert} for the
+* Memory backend, so all three backends stay in lockstep):
+*   - first write for a path → INSERT the dirty row.
+*   - later write with a GREATER seq → overwrite op/cid/mtime/latest_seq and
+*     RESET attempts/next_attempt_at/last_error (a fresh write clears prior
+*     failure/backoff state).
+*   - a stale write (seq <= current latest_seq) → the
+*     `WHERE excluded.latest_seq > ds_dirty_path.latest_seq` guard makes it a
+*     no-op; latest_seq NEVER rolls backwards.
+*
+* NOTE: the body contains inner `;` (required by the trigger grammar). Any SQL
+* splitter feeding this to D1 one statement at a time MUST keep the whole
+* `CREATE TRIGGER … BEGIN … END` block intact — same rule as the existing
+* `SCOPE_META_FILE_COUNT_TRIGGER_SQL` (see apply-d1-migrations.mjs
+* splitSqlStatements).
+*
+* `strftime('%s','now')` is second-granularity → *1000 for a millis `updated_at`
+* that reads uniformly with the app-clock millis the SQL/Memory backends write.
+*/
+const DIRTY_PATH_TRIGGER_SQL = [`CREATE TRIGGER IF NOT EXISTS ds_changelog_to_ds_dirty_path
+   AFTER INSERT ON ds_changelog
+   BEGIN
+     INSERT INTO ds_dirty_path (
+       scope, path, latest_seq, op, cid, mtime, updated_at, attempts, next_attempt_at, last_error
+     )
+     VALUES (
+       NEW.scope, NEW.path, NEW.seq, NEW.op, NEW.cid, NEW.mtime,
+       CAST(strftime('%s', 'now') AS INTEGER) * 1000, 0, 0, NULL
+     )
+     ON CONFLICT(scope, path) DO UPDATE SET
+       latest_seq = excluded.latest_seq,
+       op = excluded.op,
+       cid = excluded.cid,
+       mtime = excluded.mtime,
+       updated_at = excluded.updated_at,
+       attempts = 0,
+       next_attempt_at = 0,
+       last_error = NULL
+     WHERE excluded.latest_seq > ds_dirty_path.latest_seq;
+   END`];
+/**
+* Full DDL sequence (table → index → trigger) in dependency order. Test setups
+* and the Node ensureSchema loop run this after the `ds_changelog` DDL (the
+* trigger references `ds_changelog`, so the changelog table must exist first).
+*/
+const DIRTY_PATH_DDL = [
+	DIRTY_PATH_TABLE_SQL,
+	...DIRTY_PATH_INDEX_SQL,
+	...DIRTY_PATH_TRIGGER_SQL
+];
+/** Ready dirty rows under a prefix. Binds: `(scope, lo, hi, now, limit)`. */
+const DIRTY_PATH_LIST_SQL = `SELECT path, latest_seq, op, cid, mtime, attempts FROM ds_dirty_path INDEXED BY ds_dirty_path_scope_retry
+  WHERE scope = ? AND path >= ? AND path < ? AND next_attempt_at <= ?
+  ORDER BY next_attempt_at ASC, updated_at ASC LIMIT ?`;
+/** Guarded ack (delete iff latest_seq unchanged). Binds: `(scope, path, latestSeq)`. */
+const DIRTY_PATH_ACK_SQL = "DELETE FROM ds_dirty_path WHERE scope = ? AND path = ? AND latest_seq = ?";
+/** Guarded failure record. Binds: `(error, nextAttemptAt, scope, path, latestSeq)`. */
+const DIRTY_PATH_MARK_ERROR_SQL = `UPDATE ds_dirty_path SET attempts = attempts + 1, last_error = ?, next_attempt_at = ?
+  WHERE scope = ? AND path = ? AND latest_seq = ?`;
+
+//#endregion
+export { DIRTY_PATH_ACK_SQL, DIRTY_PATH_DDL, DIRTY_PATH_INDEX_SQL, DIRTY_PATH_LIST_SQL, DIRTY_PATH_MARK_ERROR_SQL, DIRTY_PATH_TABLE_SQL, DIRTY_PATH_TRIGGER_SQL };
+//# sourceMappingURL=dirty-path-schema.mjs.map

package/dist/dirty-path-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-path-schema.mjs","names":[],"sources":["../src/dirty-path-schema.ts"],"sourcesContent":["/**\n * ds_dirty_path schema — single source of truth for the index-follower dirty\n * queue (planning/index-provider/dirty-path-follower).\n *\n * `ds_dirty_path` is a SOURCE-SIDE derived projection of `ds_changelog`: one row\n * per `(scope, path)` recording the CURRENT op/latest_seq that still needs\n * materialising into the index. It replaces the follower's `O(changelog rows)`\n * replay with an `O(unique dirty paths)` drain (design §1-§4).\n *\n * Physical placement follows the CLAUDE.md D1-table-naming rule: it lives beside\n * `ds_changelog` in the DID Space metadata DB (CF: D1; Node: each user's\n * `_metadata.db`) — the ONLY place it can stay atomically consistent with the\n * changelog via an `AFTER INSERT` trigger — so it carries the `ds_` (DID Space)\n * prefix even though it logically serves the index provider.\n *\n * This module is the ONE definition of the DDL. It is materialised by:\n *   - CF     : a numbered D1 migration (Phase 4) that runs these statements.\n *   - Node   : `metadata-db.ts` ensureSchema (Phase 1), which has no migration\n *              runner and CREATEs tables on DB open.\n *   - tests  : every phase's D1 (miniflare / mock-d1) + libsql setup runs these\n *              statements directly (raw DDL, NOT via a numbered migration) so\n *              Phase 0-3 can exercise the trigger before Phase 4 exists.\n * All four import THESE constants — never re-spell the SQL — so the trigger\n * guard, CHECK, and column list can never drift across runtimes.\n */\n\n/**\n * CREATE TABLE statement. Idempotent (`IF NOT EXISTS`).\n *\n * Columns (design §5):\n *   - scope           : DID Space scope, mirrors `ds_changelog.scope`.\n *   - path            : full DID-space path, e.g. `blocklets/{did}/user/items/x.json`.\n *   - latest_seq      : max `ds_changelog.seq` this path has merged to (race guard).\n *   - op              : latest op, `put` | `delete` (CHECK-constrained).\n *   - cid             : latest cid; NULL on delete.\n *   - mtime           : latest changelog mtime.\n *   - updated_at      : last upsert/reset time (ms) — scheduling + observability.\n *   - attempts        : consecutive failures (poison-row backoff).\n *   - next_attempt_at : retry-backoff watermark; a row with next_attempt_at > now\n *                       is skipped so a poison row never fills a tick's budget.\n *   - last_error      : most recent failure summary.\n *\n * PRIMARY KEY(scope, path) is what makes the trigger's `ON CONFLICT(scope, path)`\n * merge N changelog rows for one path into a single dirty row.\n */\nexport const DIRTY_PATH_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ds_dirty_path (\n  scope TEXT NOT NULL,\n  path TEXT NOT NULL,\n  latest_seq INTEGER NOT NULL,\n  op TEXT NOT NULL CHECK (op IN ('put', 'delete')),\n  cid TEXT,\n  mtime INTEGER NOT NULL,\n  updated_at INTEGER NOT NULL,\n  attempts INTEGER NOT NULL DEFAULT 0,\n  next_attempt_at INTEGER NOT NULL DEFAULT 0,\n  last_error TEXT,\n  PRIMARY KEY(scope, path)\n)`;\n\n/**\n * CREATE INDEX statements. The `(scope, next_attempt_at, updated_at)` index\n * serves the follower's ready-row scan: scope equality, `next_attempt_at <= now`\n * range, `updated_at` tiebreak — an index-only ordered seek instead of a scope\n * full-scan on every tick.\n */\nexport const DIRTY_PATH_INDEX_SQL: readonly string[] = [\n  \"CREATE INDEX IF NOT EXISTS ds_dirty_path_scope_retry ON ds_dirty_path(scope, next_attempt_at, updated_at)\",\n];\n\n/**\n * The `AFTER INSERT ON ds_changelog` trigger that derives dirty rows.\n *\n * Because it hangs off the changelog INSERT, it covers EVERY changelog write\n * face by construction (design §6) — the 6 TreeIndex methods AND the metadata-db\n * direct writes — with no need to enumerate write sites (that enumeration is the\n * §6 fallback, only for a runtime whose trigger support is inadequate).\n *\n * Merge/guard semantics (mirrored in-process by {@link applyDirtyUpsert} for the\n * Memory backend, so all three backends stay in lockstep):\n *   - first write for a path → INSERT the dirty row.\n *   - later write with a GREATER seq → overwrite op/cid/mtime/latest_seq and\n *     RESET attempts/next_attempt_at/last_error (a fresh write clears prior\n *     failure/backoff state).\n *   - a stale write (seq <= current latest_seq) → the\n *     `WHERE excluded.latest_seq > ds_dirty_path.latest_seq` guard makes it a\n *     no-op; latest_seq NEVER rolls backwards.\n *\n * NOTE: the body contains inner `;` (required by the trigger grammar). Any SQL\n * splitter feeding this to D1 one statement at a time MUST keep the whole\n * `CREATE TRIGGER … BEGIN … END` block intact — same rule as the existing\n * `SCOPE_META_FILE_COUNT_TRIGGER_SQL` (see apply-d1-migrations.mjs\n * splitSqlStatements).\n *\n * `strftime('%s','now')` is second-granularity → *1000 for a millis `updated_at`\n * that reads uniformly with the app-clock millis the SQL/Memory backends write.\n */\nexport const DIRTY_PATH_TRIGGER_SQL: readonly string[] = [\n  `CREATE TRIGGER IF NOT EXISTS ds_changelog_to_ds_dirty_path\n   AFTER INSERT ON ds_changelog\n   BEGIN\n     INSERT INTO ds_dirty_path (\n       scope, path, latest_seq, op, cid, mtime, updated_at, attempts, next_attempt_at, last_error\n     )\n     VALUES (\n       NEW.scope, NEW.path, NEW.seq, NEW.op, NEW.cid, NEW.mtime,\n       CAST(strftime('%s', 'now') AS INTEGER) * 1000, 0, 0, NULL\n     )\n     ON CONFLICT(scope, path) DO UPDATE SET\n       latest_seq = excluded.latest_seq,\n       op = excluded.op,\n       cid = excluded.cid,\n       mtime = excluded.mtime,\n       updated_at = excluded.updated_at,\n       attempts = 0,\n       next_attempt_at = 0,\n       last_error = NULL\n     WHERE excluded.latest_seq > ds_dirty_path.latest_seq;\n   END`,\n];\n\n/**\n * Full DDL sequence (table → index → trigger) in dependency order. Test setups\n * and the Node ensureSchema loop run this after the `ds_changelog` DDL (the\n * trigger references `ds_changelog`, so the changelog table must exist first).\n */\nexport const DIRTY_PATH_DDL: readonly string[] = [\n  DIRTY_PATH_TABLE_SQL,\n  ...DIRTY_PATH_INDEX_SQL,\n  ...DIRTY_PATH_TRIGGER_SQL,\n];\n\n// ── DirtyPathQueue query SQL (single source, D1 + SQLite) ──\n//\n// D1TreeIndex and SQLiteTreeIndex run the SAME SQLite dialect, so — like\n// `CHANGELOG_INSERT_SQL` — the statements live here once and both backends bind\n// against them (only the client API differs). Keeping the bind ORDER documented\n// beside each string is what stops the two runtimes drifting.\n\n// `INDEXED BY ds_dirty_path_scope_retry` is NOT cosmetic — it PINS the plan.\n// This query has two viable indexes: the PK auto-index `(scope, path)` serves\n// the `path` prefix range, while `ds_dirty_path_scope_retry (scope,\n// next_attempt_at, updated_at)` serves the `next_attempt_at<=now` filter AND the\n// ORDER BY for free. WITHOUT stats the planner picks the retry index (an ordered\n// index-only seek, no sort). But once D1 gains ANALYZE cardinality stats it FLIPS\n// to the PK index + `USE TEMP B-TREE FOR ORDER BY`, which scans this instance's\n// WHOLE path range and sorts it every tick — the exact rows_read cliff that bit\n// staging in issue #1120 (measured here: ~3.3× slower on an 8k-row table). The\n// hint forces the ordered-seek plan unconditionally, mirroring markStale's\n// `INDEXED BY idx_ad_scope_anchor_type` fix in d1-index-backend.ts.\n//\n// Tradeoff (accepted): the retry index orders by time, not path, so in a scope\n// SHARED by several instances a quiet instance walks past siblings' ready rows\n// (residual-filtered by `path`) before filling its LIMIT. That is bounded by the\n// scope's ready set and never worse than the ANALYZE'd temp-b-tree it replaces.\n// If multi-blocklet-per-space with concurrent backlogs ever becomes hot, switch\n// to `ORDER BY path` on the PK index (a true per-instance bounded seek) — see the\n// dirty-path-follower design review (finding #4).\n/** Ready dirty rows under a prefix. Binds: `(scope, lo, hi, now, limit)`. */\nexport const DIRTY_PATH_LIST_SQL = `SELECT path, latest_seq, op, cid, mtime, attempts FROM ds_dirty_path INDEXED BY ds_dirty_path_scope_retry\n  WHERE scope = ? AND path >= ? AND path < ? AND next_attempt_at <= ?\n  ORDER BY next_attempt_at ASC, updated_at ASC LIMIT ?`;\n\n/** Guarded ack (delete iff latest_seq unchanged). Binds: `(scope, path, latestSeq)`. */\nexport const DIRTY_PATH_ACK_SQL =\n  \"DELETE FROM ds_dirty_path WHERE scope = ? AND path = ? AND latest_seq = ?\";\n\n/** Guarded failure record. Binds: `(error, nextAttemptAt, scope, path, latestSeq)`. */\nexport const DIRTY_PATH_MARK_ERROR_SQL = `UPDATE ds_dirty_path SET attempts = attempts + 1, last_error = ?, next_attempt_at = ?\n  WHERE scope = ? AND path = ? AND latest_seq = ?`;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,MAAa,uBAAuB;;;;;;;;;;;;;;;;;;;AAoBpC,MAAa,uBAA0C,CACrD,4GACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BD,MAAa,yBAA4C,CACvD;;;;;;;;;;;;;;;;;;;;QAqBD;;;;;;AAOD,MAAa,iBAAoC;CAC/C;CACA,GAAG;CACH,GAAG;CACJ;;AA6BD,MAAa,sBAAsB;;;;AAKnC,MAAa,qBACX;;AAGF,MAAa,4BAA4B"}