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

package/dist/dedup-backfill.mjs

@@ -0,0 +1,273 @@
+import { normalizeItemUrl } from "./url-normalize.mjs";
+
+//#region src/dedup-backfill.ts
+/**
+* dedup-backfill — one-time backfill of the dedup-on-write secondary index
+* (`ds_entries.dedup_scope` / `dedup_key`) for records written BEFORE #1159
+* landed (planning: dedup-on-write, issue #1159).
+*
+* Pre-#1159 the dedup entry lived at `{collection}/{cid(url)}.json` and had no
+* `dedup_key` column; older layouts (`{slug}.json`, `{uuid}/item.json`) never
+* had one either. After #1159 dedup resolves through the
+* `(scope, dedup_scope, dedup_key)` UNIQUE index, so those historical rows are
+* INVISIBLE to `findByDedupKey` — an already-saved URL's first re-save creates
+* a duplicate. This sweep populates their columns so a re-save merges in place.
+*
+* Design (mirrors ctime-backfill / inline-content-migration):
+*  - OFFLINE, code-driven. The core loop {@link backfillDedup} is backend-
+*    agnostic; the SQL lives in {@link DedupBackfillBackend} adapters (D1 binding
+*    vs Node SQLite vs the CF D1 HTTP API) so it is unit-testable against a mock.
+*  - **Host-language normalization** — the `dedup_key` is
+*    `normalizeItemUrl(record[dedupBy])`, computed in JS with the SAME function
+*    the write path uses. It CANNOT be done in SQL (`json_extract` would store
+*    the RAW url, which would never match the Worker's normalized lookups), so
+*    the sweep MUST read the record body (`content` column) and normalize here.
+*  - **JS uniqueness pre-filter, never DB rejection.** The `(scope, dedup_scope,
+*    dedup_key)` UNIQUE index means two rows can't share a key. A `seen` set —
+*    seeded from the keys ALREADY indexed (e.g. entries a post-#1159 client
+*    already wrote) and grown as the sweep assigns — decides the winner in JS so
+*    NO `UPDATE` ever violates the constraint. This matters over the D1 HTTP
+*    channel where a constraint error is a 4xx that would abort the whole run.
+*    A genuine pre-existing duplicate is left un-indexed (reported), NEVER merged
+*    (the tool does not touch content).
+*  - **WHERE pins `scope` + the collection prefix**, binds everything as
+*    parameters — never a cross-scope / cross-collection UPDATE.
+*  - **Deterministic `ORDER BY path ASC` keyset cursor** — resumable across
+*    invocations; among genuine duplicates the FIRST in path order wins the key.
+*  - **Idempotent**: `UPDATE … WHERE dedup_key IS NULL` — a re-run never
+*    re-touches an already-populated row (0 write). The cursor advances past
+*    EVERY scanned row so one invocation can't loop.
+*  - **Only dedup_scope/dedup_key change** — never cid/size/content/mtime/ctime
+*    (index-only; no changelog / no sync fan-out).
+*/
+/** Extract the record body's `dedupBy` field as a non-empty string, or null. */
+function extractKeyField(content, dedupBy) {
+	if (content == null) return null;
+	let body;
+	try {
+		body = JSON.parse(content);
+	} catch {
+		return null;
+	}
+	if (body === null || typeof body !== "object" || Array.isArray(body)) return null;
+	const v = body[dedupBy];
+	return typeof v === "string" && v.length > 0 ? v : null;
+}
+/**
+* Page over NULL-`dedup_key` FILE rows in one `(scope, collection)` and populate
+* their dedup columns. Returns stats; resumable across calls (a fresh call
+* re-seeds `seen` from the DB, so previously-indexed keys stay winners).
+*/
+async function backfillDedup(backend, opts) {
+	const pageSize = opts.pageSize ?? 100;
+	const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
+	const dryRun = opts.dryRun ?? false;
+	const log = opts.log ?? (() => {});
+	const stats = {
+		scanned: 0,
+		indexed: 0,
+		skippedNoContent: 0,
+		skippedNoField: 0,
+		skippedDuplicate: 0,
+		pages: 0,
+		lastCursor: "",
+		done: false
+	};
+	const seen = new Set(await backend.existingKeys());
+	let cursor = "";
+	while (stats.pages < maxPages) {
+		const rows = await backend.selectCandidates(cursor, pageSize);
+		if (rows.length === 0) {
+			stats.done = true;
+			break;
+		}
+		stats.pages++;
+		for (const row of rows) {
+			stats.scanned++;
+			cursor = row.path;
+			const raw = extractKeyField(row.content, opts.dedupBy);
+			if (raw === null) {
+				if (row.content == null) stats.skippedNoContent++;
+				else stats.skippedNoField++;
+				continue;
+			}
+			const key = normalizeItemUrl(raw);
+			if (seen.has(key)) {
+				stats.skippedDuplicate++;
+				continue;
+			}
+			seen.add(key);
+			if (dryRun) {
+				stats.indexed++;
+				continue;
+			}
+			if (await backend.setDedupKey(row.path, key) > 0) stats.indexed++;
+		}
+		stats.lastCursor = cursor;
+		log(`[dedup-backfill] page ${stats.pages}: scanned=${stats.scanned} indexed=${stats.indexed} dup=${stats.skippedDuplicate} cursor=${cursor}`);
+	}
+	return stats;
+}
+const SELECT_SQL = "SELECT path, content FROM ds_entries WHERE scope = ? AND kind = 'file' AND dedup_key IS NULL AND path > ? AND substr(path, 1, ?) = ? ORDER BY path ASC LIMIT ?";
+const EXISTING_KEYS_SQL = "SELECT dedup_key FROM ds_entries WHERE scope = ? AND dedup_scope = ? AND dedup_key IS NOT NULL";
+const UPDATE_SQL = "UPDATE ds_entries SET dedup_scope = ?, dedup_key = ? WHERE scope = ? AND path = ? AND kind = 'file' AND dedup_key IS NULL";
+const DISTINCT_SCOPES_SQL = "SELECT DISTINCT scope FROM ds_entries WHERE kind = 'file' AND dedup_key IS NULL AND substr(path, 1, ?) = ?";
+/** The `path` prefix (`{collection}/`) + its length, for the substr filter. */
+function collectionPrefix(collection) {
+	const prefix = collection.endsWith("/") ? collection : `${collection}/`;
+	return {
+		prefix,
+		len: prefix.length
+	};
+}
+/** D1 (Cloudflare binding) backend adapter for one (scope, collection). */
+function makeD1DedupBackfillBackend(db, scope, collection) {
+	const { prefix, len } = collectionPrefix(collection);
+	return {
+		async existingKeys() {
+			return ((await db.prepare(EXISTING_KEYS_SQL).bind(scope, collection).all()).results ?? []).map((r) => String(r.dedup_key));
+		},
+		async selectCandidates(cursor, limit) {
+			return ((await db.prepare(SELECT_SQL).bind(scope, cursor, len, prefix, limit).all()).results ?? []).map((r) => ({
+				path: String(r.path),
+				content: r.content === null || r.content === void 0 ? null : String(r.content)
+			}));
+		},
+		async setDedupKey(path, dedupKey) {
+			return (await db.prepare(UPDATE_SQL).bind(collection, dedupKey, scope, path).run()).meta?.changes ?? 0;
+		}
+	};
+}
+/** Node SQLite (libsql) backend adapter for one (scope, collection). */
+function makeSqliteDedupBackfillBackend(db, scope, collection) {
+	const { prefix, len } = collectionPrefix(collection);
+	return {
+		async existingKeys() {
+			return (await db.execute({
+				sql: EXISTING_KEYS_SQL,
+				args: [scope, collection]
+			})).rows.map((r) => String(r.dedup_key));
+		},
+		async selectCandidates(cursor, limit) {
+			return (await db.execute({
+				sql: SELECT_SQL,
+				args: [
+					scope,
+					cursor,
+					len,
+					prefix,
+					limit
+				]
+			})).rows.map((r) => ({
+				path: String(r.path),
+				content: r.content === null || r.content === void 0 ? null : String(r.content)
+			}));
+		},
+		async setDedupKey(path, dedupKey) {
+			return (await db.execute({
+				sql: UPDATE_SQL,
+				args: [
+					collection,
+					dedupKey,
+					scope,
+					path
+				]
+			})).rowsAffected ?? 0;
+		}
+	};
+}
+/** Enumerate scopes with any NULL-dedup_key file row under the collection (D1). */
+async function distinctScopesWithDedupCandidatesD1(db, collection) {
+	const { prefix, len } = collectionPrefix(collection);
+	return ((await db.prepare(DISTINCT_SCOPES_SQL).bind(len, prefix).all()).results ?? []).map((r) => String(r.scope));
+}
+/** Enumerate candidate scopes under the collection (Node SQLite). */
+async function distinctScopesWithDedupCandidatesSqlite(db, collection) {
+	const { prefix, len } = collectionPrefix(collection);
+	return (await db.execute({
+		sql: DISTINCT_SCOPES_SQL,
+		args: [len, prefix]
+	})).rows.map((r) => String(r.scope));
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function d1HttpQuery(cfg, sql, params) {
+	const f = cfg.fetchImpl ?? fetch;
+	const sleep = cfg.sleep ?? defaultSleep;
+	const maxRetries = cfg.maxRetries ?? 4;
+	const url = `https://api.cloudflare.com/client/v4/accounts/${cfg.accountId}/d1/database/${cfg.databaseId}/query`;
+	for (let attempt = 0;; attempt++) {
+		let status = 0;
+		let json;
+		let networkErr;
+		try {
+			const res = await f(url, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${cfg.apiToken}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({
+					sql,
+					params
+				})
+			});
+			status = res.status;
+			json = await res.json();
+		} catch (e) {
+			networkErr = e;
+		}
+		if (!networkErr && status >= 200 && status < 300 && json?.success !== false) {
+			const r = json?.result?.[0];
+			return {
+				results: r?.results ?? [],
+				changes: r?.meta?.changes ?? 0
+			};
+		}
+		const transient = networkErr != null || status >= 500 || status === 429;
+		const msg = networkErr ? `D1 HTTP network error: ${String(networkErr).slice(0, 160)}` : `D1 HTTP ${status}: ${JSON.stringify(json?.errors ?? json).slice(0, 200)}`;
+		if (!transient || attempt >= maxRetries) throw new Error(msg);
+		await sleep(Math.min(2e3, 200 * 2 ** attempt));
+	}
+}
+/** CF D1 HTTP-API backend adapter for one (scope, collection) — offline channel. */
+function makeD1HttpDedupBackfillBackend(cfg, scope, collection) {
+	const { prefix, len } = collectionPrefix(collection);
+	return {
+		async existingKeys() {
+			const { results } = await d1HttpQuery(cfg, EXISTING_KEYS_SQL, [scope, collection]);
+			return results.map((r) => String(r.dedup_key));
+		},
+		async selectCandidates(cursor, limit) {
+			const { results } = await d1HttpQuery(cfg, SELECT_SQL, [
+				scope,
+				cursor,
+				len,
+				prefix,
+				limit
+			]);
+			return results.map((r) => ({
+				path: String(r.path),
+				content: r.content === null || r.content === void 0 ? null : String(r.content)
+			}));
+		},
+		async setDedupKey(path, dedupKey) {
+			const { changes } = await d1HttpQuery(cfg, UPDATE_SQL, [
+				collection,
+				dedupKey,
+				scope,
+				path
+			]);
+			return changes;
+		}
+	};
+}
+/** List distinct candidate scopes under the collection on a CF D1 over HTTP. */
+async function distinctScopesWithDedupCandidatesD1Http(cfg, collection) {
+	const { prefix, len } = collectionPrefix(collection);
+	const { results } = await d1HttpQuery(cfg, DISTINCT_SCOPES_SQL, [len, prefix]);
+	return results.map((r) => String(r.scope));
+}
+
+//#endregion
+export { backfillDedup, distinctScopesWithDedupCandidatesD1, distinctScopesWithDedupCandidatesD1Http, distinctScopesWithDedupCandidatesSqlite, makeD1DedupBackfillBackend, makeD1HttpDedupBackfillBackend, makeSqliteDedupBackfillBackend };
+//# sourceMappingURL=dedup-backfill.mjs.map

package/dist/dedup-backfill.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-backfill.mjs","names":[],"sources":["../src/dedup-backfill.ts"],"sourcesContent":["/**\n * dedup-backfill — one-time backfill of the dedup-on-write secondary index\n * (`ds_entries.dedup_scope` / `dedup_key`) for records written BEFORE #1159\n * landed (planning: dedup-on-write, issue #1159).\n *\n * Pre-#1159 the dedup entry lived at `{collection}/{cid(url)}.json` and had no\n * `dedup_key` column; older layouts (`{slug}.json`, `{uuid}/item.json`) never\n * had one either. After #1159 dedup resolves through the\n * `(scope, dedup_scope, dedup_key)` UNIQUE index, so those historical rows are\n * INVISIBLE to `findByDedupKey` — an already-saved URL's first re-save creates\n * a duplicate. This sweep populates their columns so a re-save merges in place.\n *\n * Design (mirrors ctime-backfill / inline-content-migration):\n *  - OFFLINE, code-driven. The core loop {@link backfillDedup} is backend-\n *    agnostic; the SQL lives in {@link DedupBackfillBackend} adapters (D1 binding\n *    vs Node SQLite vs the CF D1 HTTP API) so it is unit-testable against a mock.\n *  - **Host-language normalization** — the `dedup_key` is\n *    `normalizeItemUrl(record[dedupBy])`, computed in JS with the SAME function\n *    the write path uses. It CANNOT be done in SQL (`json_extract` would store\n *    the RAW url, which would never match the Worker's normalized lookups), so\n *    the sweep MUST read the record body (`content` column) and normalize here.\n *  - **JS uniqueness pre-filter, never DB rejection.** The `(scope, dedup_scope,\n *    dedup_key)` UNIQUE index means two rows can't share a key. A `seen` set —\n *    seeded from the keys ALREADY indexed (e.g. entries a post-#1159 client\n *    already wrote) and grown as the sweep assigns — decides the winner in JS so\n *    NO `UPDATE` ever violates the constraint. This matters over the D1 HTTP\n *    channel where a constraint error is a 4xx that would abort the whole run.\n *    A genuine pre-existing duplicate is left un-indexed (reported), NEVER merged\n *    (the tool does not touch content).\n *  - **WHERE pins `scope` + the collection prefix**, binds everything as\n *    parameters — never a cross-scope / cross-collection UPDATE.\n *  - **Deterministic `ORDER BY path ASC` keyset cursor** — resumable across\n *    invocations; among genuine duplicates the FIRST in path order wins the key.\n *  - **Idempotent**: `UPDATE … WHERE dedup_key IS NULL` — a re-run never\n *    re-touches an already-populated row (0 write). The cursor advances past\n *    EVERY scanned row so one invocation can't loop.\n *  - **Only dedup_scope/dedup_key change** — never cid/size/content/mtime/ctime\n *    (index-only; no changelog / no sync fan-out).\n */\n\nimport { normalizeItemUrl } from \"./url-normalize.js\";\n\n/** A dedup-index candidate: a FILE row with a NULL `dedup_key`. */\nexport interface DedupBackfillCandidate {\n  path: string;\n  /** Raw `entries.content` inline record body (host-parsed here, never in SQL). */\n  content: string | null;\n}\n\n/**\n * Backend-specific SQL for the sweep (D1 binding vs Node SQLite vs D1 HTTP).\n * One `(scope, collection)` per adapter — `collection` is the full stored\n * collection path (e.g. `blocklets/aside/user/items`), which is BOTH the value\n * written to `dedup_scope` and the `path` prefix that scopes the sweep.\n */\nexport interface DedupBackfillBackend {\n  /**\n   * `dedup_key`s already claimed within this `(scope, collection)` — seeds the\n   * uniqueness `seen` set so the sweep never collides with a row a post-#1159\n   * client already indexed.\n   */\n  existingKeys(): Promise<string[]>;\n  /**\n   * Select up to `limit` FILE rows with `dedup_key IS NULL` under the collection\n   * and `path > cursor`, ordered `path ASC` (the keyset cursor). Empty ⇒ done.\n   */\n  selectCandidates(cursor: string, limit: number): Promise<DedupBackfillCandidate[]>;\n  /**\n   * Set `dedup_scope` (= the collection) + `dedup_key` on the row, guarded\n   * `AND dedup_key IS NULL` so an already-populated row is a 0-row no-op.\n   * Returns the number of rows actually changed (0 or 1).\n   */\n  setDedupKey(path: string, dedupKey: string): Promise<number>;\n}\n\nexport interface DedupBackfillOptions {\n  /** Record field to dedup by (e.g. `\"url\"`). Required. */\n  dedupBy: string;\n  /** Rows per page. Default 100 (content is heavier than a metadata blob). */\n  pageSize?: number;\n  /** Cap pages this invocation (cross-invocation paging). Default unbounded. */\n  maxPages?: number;\n  /**\n   * Preview only — scan + count, run NO UPDATE. `indexed` then reports rows that\n   * WOULD be indexed; all skip counts are exact in both modes.\n   */\n  dryRun?: boolean;\n  log?: (msg: string) => void;\n}\n\nexport interface DedupBackfillStats {\n  /** FILE rows examined (dedup_key IS NULL under the collection). */\n  scanned: number;\n  /** Rows whose dedup columns were populated (or WOULD be, in dryRun). */\n  indexed: number;\n  /** Rows with no inline `content` — cannot extract the field, left as-is. */\n  skippedNoContent: number;\n  /** Rows whose body lacked a usable `dedupBy` field — not dedup-able. */\n  skippedNoField: number;\n  /** Rows whose key was already claimed — a genuine duplicate, left un-indexed. */\n  skippedDuplicate: number;\n  pages: number;\n  lastCursor: string;\n  /** True when a page came back empty (the sweep reached the end). */\n  done: boolean;\n}\n\n/** Extract the record body's `dedupBy` field as a non-empty string, or null. */\nfunction extractKeyField(content: string | null, dedupBy: string): string | null {\n  if (content == null) return null;\n  let body: unknown;\n  try {\n    body = JSON.parse(content);\n  } catch {\n    return null;\n  }\n  if (body === null || typeof body !== \"object\" || Array.isArray(body)) return null;\n  const v = (body as Record<string, unknown>)[dedupBy];\n  return typeof v === \"string\" && v.length > 0 ? v : null;\n}\n\n/**\n * Page over NULL-`dedup_key` FILE rows in one `(scope, collection)` and populate\n * their dedup columns. Returns stats; resumable across calls (a fresh call\n * re-seeds `seen` from the DB, so previously-indexed keys stay winners).\n */\nexport async function backfillDedup(\n  backend: DedupBackfillBackend,\n  opts: DedupBackfillOptions,\n): Promise<DedupBackfillStats> {\n  const pageSize = opts.pageSize ?? 100;\n  const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;\n  const dryRun = opts.dryRun ?? false;\n  const log = opts.log ?? (() => {});\n\n  const stats: DedupBackfillStats = {\n    scanned: 0,\n    indexed: 0,\n    skippedNoContent: 0,\n    skippedNoField: 0,\n    skippedDuplicate: 0,\n    pages: 0,\n    lastCursor: \"\",\n    done: false,\n  };\n\n  // Seed the uniqueness set from keys already claimed under this collection\n  // (e.g. entries a post-#1159 client already wrote) so the sweep defers to them.\n  const seen = new Set<string>(await backend.existingKeys());\n\n  let cursor = \"\";\n  while (stats.pages < maxPages) {\n    const rows = await backend.selectCandidates(cursor, pageSize);\n    if (rows.length === 0) {\n      stats.done = true;\n      break;\n    }\n    stats.pages++;\n    // SERIAL — the `seen` check+add must be atomic per key (a concurrent pool\n    // could let two rows both claim one key and collide at the DB).\n    for (const row of rows) {\n      stats.scanned++;\n      cursor = row.path; // advance past EVERY scanned row so one pass can't loop\n      const raw = extractKeyField(row.content, opts.dedupBy);\n      if (raw === null) {\n        if (row.content == null) stats.skippedNoContent++;\n        else stats.skippedNoField++;\n        continue;\n      }\n      const key = normalizeItemUrl(raw);\n      if (seen.has(key)) {\n        stats.skippedDuplicate++; // pre-existing duplicate — leave un-indexed\n        continue;\n      }\n      seen.add(key);\n      if (dryRun) {\n        stats.indexed++; // would-index (no UPDATE issued)\n        continue;\n      }\n      const changed = await backend.setDedupKey(row.path, key);\n      if (changed > 0) stats.indexed++;\n    }\n    stats.lastCursor = cursor;\n    log(\n      `[dedup-backfill] page ${stats.pages}: scanned=${stats.scanned} indexed=${stats.indexed} dup=${stats.skippedDuplicate} cursor=${cursor}`,\n    );\n  }\n  return stats;\n}\n\n// ── SQL (shared by all adapters; entries PK is (scope, path)) ────────────────\n//\n// `substr(path,1,?)=?` scopes the sweep to ONE collection prefix (the sweep is\n// per-app, e.g. `blocklets/aside/user/items/`). Not index-optimized, but this is\n// a bounded one-time offline sweep, never a hot path.\nconst SELECT_SQL =\n  \"SELECT path, content FROM ds_entries WHERE scope = ? AND kind = 'file' \" +\n  \"AND dedup_key IS NULL AND path > ? AND substr(path, 1, ?) = ? ORDER BY path ASC LIMIT ?\";\nconst EXISTING_KEYS_SQL =\n  \"SELECT dedup_key FROM ds_entries WHERE scope = ? AND dedup_scope = ? AND dedup_key IS NOT NULL\";\n// Guarded `AND dedup_key IS NULL` → an already-populated row is a 0-row no-op\n// (idempotent re-runs). Bind order: (dedup_scope, dedup_key, scope, path).\nconst UPDATE_SQL =\n  \"UPDATE ds_entries SET dedup_scope = ?, dedup_key = ? WHERE scope = ? AND path = ? AND kind = 'file' AND dedup_key IS NULL\";\nconst DISTINCT_SCOPES_SQL =\n  \"SELECT DISTINCT scope FROM ds_entries WHERE kind = 'file' AND dedup_key IS NULL AND substr(path, 1, ?) = ?\";\n\n/** The `path` prefix (`{collection}/`) + its length, for the substr filter. */\nfunction collectionPrefix(collection: string): { prefix: string; len: number } {\n  const prefix = collection.endsWith(\"/\") ? collection : `${collection}/`;\n  return { prefix, len: prefix.length };\n}\n\n/** Minimal D1 shape used by the sweep (subset of `D1Database`). */\nexport interface D1Like {\n  prepare(sql: string): {\n    bind(...args: (string | number)[]): {\n      all(): Promise<{ results?: unknown[] }>;\n      run(): Promise<{ meta?: { changes?: number } }>;\n    };\n  };\n}\n\n/** D1 (Cloudflare binding) backend adapter for one (scope, collection). */\nexport function makeD1DedupBackfillBackend(\n  db: D1Like,\n  scope: string,\n  collection: string,\n): DedupBackfillBackend {\n  const { prefix, len } = collectionPrefix(collection);\n  return {\n    async existingKeys() {\n      const res = await db.prepare(EXISTING_KEYS_SQL).bind(scope, collection).all();\n      return ((res.results ?? []) as Array<Record<string, unknown>>).map((r) =>\n        String(r.dedup_key),\n      );\n    },\n    async selectCandidates(cursor, limit) {\n      const res = await db.prepare(SELECT_SQL).bind(scope, cursor, len, prefix, limit).all();\n      return ((res.results ?? []) as Array<Record<string, unknown>>).map((r) => ({\n        path: String(r.path),\n        content: r.content === null || r.content === undefined ? null : String(r.content),\n      }));\n    },\n    async setDedupKey(path, dedupKey) {\n      const r = await db.prepare(UPDATE_SQL).bind(collection, dedupKey, scope, path).run();\n      return r.meta?.changes ?? 0;\n    },\n  };\n}\n\n/**\n * Minimal libsql client shape (Node `_metadata.db`). `args` narrowed to the\n * exact bound types so a real `@libsql/client` `Client` is assignable.\n */\nexport interface LibsqlLike {\n  execute(stmt: { sql: string; args: (string | number)[] }): Promise<{\n    rows: Array<Record<string, unknown>>;\n    rowsAffected?: number;\n  }>;\n}\n\n/** Node SQLite (libsql) backend adapter for one (scope, collection). */\nexport function makeSqliteDedupBackfillBackend(\n  db: LibsqlLike,\n  scope: string,\n  collection: string,\n): DedupBackfillBackend {\n  const { prefix, len } = collectionPrefix(collection);\n  return {\n    async existingKeys() {\n      const res = await db.execute({ sql: EXISTING_KEYS_SQL, args: [scope, collection] });\n      return res.rows.map((r) => String(r.dedup_key));\n    },\n    async selectCandidates(cursor, limit) {\n      const res = await db.execute({ sql: SELECT_SQL, args: [scope, cursor, len, prefix, limit] });\n      return res.rows.map((r) => ({\n        path: String(r.path),\n        content: r.content === null || r.content === undefined ? null : String(r.content),\n      }));\n    },\n    async setDedupKey(path, dedupKey) {\n      const r = await db.execute({ sql: UPDATE_SQL, args: [collection, dedupKey, scope, path] });\n      return r.rowsAffected ?? 0;\n    },\n  };\n}\n\n/** Enumerate scopes with any NULL-dedup_key file row under the collection (D1). */\nexport async function distinctScopesWithDedupCandidatesD1(\n  db: D1Like,\n  collection: string,\n): Promise<string[]> {\n  const { prefix, len } = collectionPrefix(collection);\n  const res = await db.prepare(DISTINCT_SCOPES_SQL).bind(len, prefix).all();\n  return ((res.results ?? []) as Array<Record<string, unknown>>).map((r) => String(r.scope));\n}\n\n/** Enumerate candidate scopes under the collection (Node SQLite). */\nexport async function distinctScopesWithDedupCandidatesSqlite(\n  db: LibsqlLike,\n  collection: string,\n): Promise<string[]> {\n  const { prefix, len } = collectionPrefix(collection);\n  const res = await db.execute({ sql: DISTINCT_SCOPES_SQL, args: [len, prefix] });\n  return res.rows.map((r) => String(r.scope));\n}\n\n// ── CF D1 over the HTTP API (offline admin channel for staging/prod) ─────────\n/**\n * Config for the offline CF D1 HTTP backend: a local Node process holding a\n * Cloudflare API token with D1-edit runs the SAME paged sweep SQL the Worker\n * would. No R2 — dedup backfill is pure index UPDATEs (record bodies come from\n * the inline `content` column). `fetchImpl` / `sleep` are injectable for tests.\n */\nexport interface DedupBackfillD1HttpConfig {\n  accountId: string;\n  databaseId: string;\n  apiToken: string;\n  fetchImpl?: typeof fetch;\n  /** Bounded retries for TRANSIENT failures (5xx / 429 / network). Default 4. */\n  maxRetries?: number;\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));\n\nasync function d1HttpQuery(\n  cfg: DedupBackfillD1HttpConfig,\n  sql: string,\n  params: (string | number)[],\n): Promise<{ results: Array<Record<string, unknown>>; changes: number }> {\n  const f = cfg.fetchImpl ?? fetch;\n  const sleep = cfg.sleep ?? defaultSleep;\n  const maxRetries = cfg.maxRetries ?? 4;\n  const url = `https://api.cloudflare.com/client/v4/accounts/${cfg.accountId}/d1/database/${cfg.databaseId}/query`;\n  for (let attempt = 0; ; attempt++) {\n    let status = 0;\n    let json:\n      | {\n          success?: boolean;\n          errors?: unknown;\n          result?: Array<{ results?: Array<Record<string, unknown>>; meta?: { changes?: number } }>;\n        }\n      | undefined;\n    let networkErr: unknown;\n    try {\n      const res = await f(url, {\n        method: \"POST\",\n        headers: { authorization: `Bearer ${cfg.apiToken}`, \"content-type\": \"application/json\" },\n        body: JSON.stringify({ sql, params }),\n      });\n      status = res.status;\n      json = await res.json();\n    } catch (e) {\n      networkErr = e; // network/parse failure → transient\n    }\n    if (!networkErr && status >= 200 && status < 300 && json?.success !== false) {\n      const r = json?.result?.[0];\n      return { results: r?.results ?? [], changes: r?.meta?.changes ?? 0 };\n    }\n    // 5xx / 429 / network → transient (retry); 4xx (auth/SQL) → permanent.\n    const transient = networkErr != null || status >= 500 || status === 429;\n    const msg = networkErr\n      ? `D1 HTTP network error: ${String(networkErr).slice(0, 160)}`\n      : `D1 HTTP ${status}: ${JSON.stringify(json?.errors ?? json).slice(0, 200)}`;\n    if (!transient || attempt >= maxRetries) throw new Error(msg);\n    await sleep(Math.min(2000, 200 * 2 ** attempt));\n  }\n}\n\n/** CF D1 HTTP-API backend adapter for one (scope, collection) — offline channel. */\nexport function makeD1HttpDedupBackfillBackend(\n  cfg: DedupBackfillD1HttpConfig,\n  scope: string,\n  collection: string,\n): DedupBackfillBackend {\n  const { prefix, len } = collectionPrefix(collection);\n  return {\n    async existingKeys() {\n      const { results } = await d1HttpQuery(cfg, EXISTING_KEYS_SQL, [scope, collection]);\n      return results.map((r) => String(r.dedup_key));\n    },\n    async selectCandidates(cursor, limit) {\n      const { results } = await d1HttpQuery(cfg, SELECT_SQL, [scope, cursor, len, prefix, limit]);\n      return results.map((r) => ({\n        path: String(r.path),\n        content: r.content === null || r.content === undefined ? null : String(r.content),\n      }));\n    },\n    async setDedupKey(path, dedupKey) {\n      const { changes } = await d1HttpQuery(cfg, UPDATE_SQL, [collection, dedupKey, scope, path]);\n      return changes;\n    },\n  };\n}\n\n/** List distinct candidate scopes under the collection on a CF D1 over HTTP. */\nexport async function distinctScopesWithDedupCandidatesD1Http(\n  cfg: DedupBackfillD1HttpConfig,\n  collection: string,\n): Promise<string[]> {\n  const { prefix, len } = collectionPrefix(collection);\n  const { results } = await d1HttpQuery(cfg, DISTINCT_SCOPES_SQL, [len, prefix]);\n  return results.map((r) => String(r.scope));\n}\n"],"mappings":"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"}

package/dist/did-space-like.d.cts

@@ -0,0 +1,2 @@
+import { DIDSpaceLike as DIDSpaceLike$1, InstanceSpaceOptions } from "@aigne/afs";
+export { type DIDSpaceLike$1 as DIDSpaceLike, type InstanceSpaceOptions };

package/dist/did-space-like.d.mts

@@ -0,0 +1,2 @@
+import { DIDSpaceLike as DIDSpaceLike$1, InstanceSpaceOptions } from "@aigne/afs";
+export { type DIDSpaceLike$1 as DIDSpaceLike, type InstanceSpaceOptions };

package/dist/did-utils.cjs

@@ -0,0 +1,44 @@
+
+//#region src/did-utils.ts
+/**
+* ID validation and normalization utilities.
+*
+* All storage paths use bare identifiers (e.g., "z3hxxx", "persona"),
+* never full DID format (e.g., "did:abt:z3hxxx"). The normalizeId()
+* function strips any "did:method:" prefix at API boundaries.
+*/
+/**
+* Validate an identifier string for safety.
+* Accepts both bare IDs ("persona") and full DIDs ("did:abt:persona").
+* Rejects path separators, traversal patterns, and null bytes.
+*/
+function validateId(id) {
+	if (!id || typeof id !== "string") throw new Error("ID must be a non-empty string");
+	if (id.length > 128) throw new Error(`ID exceeds max length: ${id.length}`);
+	if (/[/\\]/.test(id)) throw new Error(`ID contains path separator: ${id}`);
+	if (id.includes("..")) throw new Error(`ID contains path traversal: ${id}`);
+	if (id.includes("\0")) throw new Error(`ID contains null byte: ${id}`);
+	let decoded = id;
+	try {
+		decoded = decodeURIComponent(id);
+	} catch {}
+	if (decoded !== id) {
+		if (/[/\\]/.test(decoded)) throw new Error(`ID contains encoded path separator: ${id}`);
+		if (decoded.includes("..")) throw new Error(`ID contains encoded traversal: ${id}`);
+		if (decoded.includes("\0")) throw new Error(`ID contains encoded null byte: ${id}`);
+	}
+}
+/**
+* Normalize an identifier by stripping any "did:method:" prefix.
+*
+* "did:abt:persona" → "persona"
+* "did:web:example.com" → "example.com"
+* "persona" → "persona" (unchanged)
+*/
+function normalizeId(input) {
+	return input.match(/^did:[a-z0-9]+:(.+)$/i)?.[1] ?? input;
+}
+
+//#endregion
+exports.normalizeId = normalizeId;
+exports.validateId = validateId;

package/dist/did-utils.d.cts

@@ -0,0 +1,25 @@
+//#region src/did-utils.d.ts
+/**
+ * ID validation and normalization utilities.
+ *
+ * All storage paths use bare identifiers (e.g., "z3hxxx", "persona"),
+ * never full DID format (e.g., "did:abt:z3hxxx"). The normalizeId()
+ * function strips any "did:method:" prefix at API boundaries.
+ */
+/**
+ * Validate an identifier string for safety.
+ * Accepts both bare IDs ("persona") and full DIDs ("did:abt:persona").
+ * Rejects path separators, traversal patterns, and null bytes.
+ */
+declare function validateId(id: string): void;
+/**
+ * Normalize an identifier by stripping any "did:method:" prefix.
+ *
+ * "did:abt:persona" → "persona"
+ * "did:web:example.com" → "example.com"
+ * "persona" → "persona" (unchanged)
+ */
+declare function normalizeId(input: string): string;
+//#endregion
+export { normalizeId, validateId };
+//# sourceMappingURL=did-utils.d.cts.map

package/dist/did-utils.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-utils.d.cts","names":[],"sources":["../src/did-utils.ts"],"mappings":";;AAaA;;;;;AAsCA;;;;;;iBAtCgB,UAAA,CAAW,EAAA;;;;;;;;iBAsCX,WAAA,CAAY,KAAA"}

package/dist/did-utils.d.mts

@@ -0,0 +1,25 @@
+//#region src/did-utils.d.ts
+/**
+ * ID validation and normalization utilities.
+ *
+ * All storage paths use bare identifiers (e.g., "z3hxxx", "persona"),
+ * never full DID format (e.g., "did:abt:z3hxxx"). The normalizeId()
+ * function strips any "did:method:" prefix at API boundaries.
+ */
+/**
+ * Validate an identifier string for safety.
+ * Accepts both bare IDs ("persona") and full DIDs ("did:abt:persona").
+ * Rejects path separators, traversal patterns, and null bytes.
+ */
+declare function validateId(id: string): void;
+/**
+ * Normalize an identifier by stripping any "did:method:" prefix.
+ *
+ * "did:abt:persona" → "persona"
+ * "did:web:example.com" → "example.com"
+ * "persona" → "persona" (unchanged)
+ */
+declare function normalizeId(input: string): string;
+//#endregion
+export { normalizeId, validateId };
+//# sourceMappingURL=did-utils.d.mts.map

package/dist/did-utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-utils.d.mts","names":[],"sources":["../src/did-utils.ts"],"mappings":";;AAaA;;;;;AAsCA;;;;;;iBAtCgB,UAAA,CAAW,EAAA;;;;;;;;iBAsCX,WAAA,CAAY,KAAA"}

package/dist/did-utils.mjs

@@ -0,0 +1,43 @@
+//#region src/did-utils.ts
+/**
+* ID validation and normalization utilities.
+*
+* All storage paths use bare identifiers (e.g., "z3hxxx", "persona"),
+* never full DID format (e.g., "did:abt:z3hxxx"). The normalizeId()
+* function strips any "did:method:" prefix at API boundaries.
+*/
+/**
+* Validate an identifier string for safety.
+* Accepts both bare IDs ("persona") and full DIDs ("did:abt:persona").
+* Rejects path separators, traversal patterns, and null bytes.
+*/
+function validateId(id) {
+	if (!id || typeof id !== "string") throw new Error("ID must be a non-empty string");
+	if (id.length > 128) throw new Error(`ID exceeds max length: ${id.length}`);
+	if (/[/\\]/.test(id)) throw new Error(`ID contains path separator: ${id}`);
+	if (id.includes("..")) throw new Error(`ID contains path traversal: ${id}`);
+	if (id.includes("\0")) throw new Error(`ID contains null byte: ${id}`);
+	let decoded = id;
+	try {
+		decoded = decodeURIComponent(id);
+	} catch {}
+	if (decoded !== id) {
+		if (/[/\\]/.test(decoded)) throw new Error(`ID contains encoded path separator: ${id}`);
+		if (decoded.includes("..")) throw new Error(`ID contains encoded traversal: ${id}`);
+		if (decoded.includes("\0")) throw new Error(`ID contains encoded null byte: ${id}`);
+	}
+}
+/**
+* Normalize an identifier by stripping any "did:method:" prefix.
+*
+* "did:abt:persona" → "persona"
+* "did:web:example.com" → "example.com"
+* "persona" → "persona" (unchanged)
+*/
+function normalizeId(input) {
+	return input.match(/^did:[a-z0-9]+:(.+)$/i)?.[1] ?? input;
+}
+
+//#endregion
+export { normalizeId, validateId };
+//# sourceMappingURL=did-utils.mjs.map

package/dist/did-utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-utils.mjs","names":[],"sources":["../src/did-utils.ts"],"sourcesContent":["/**\n * ID validation and normalization utilities.\n *\n * All storage paths use bare identifiers (e.g., \"z3hxxx\", \"persona\"),\n * never full DID format (e.g., \"did:abt:z3hxxx\"). The normalizeId()\n * function strips any \"did:method:\" prefix at API boundaries.\n */\n\n/**\n * Validate an identifier string for safety.\n * Accepts both bare IDs (\"persona\") and full DIDs (\"did:abt:persona\").\n * Rejects path separators, traversal patterns, and null bytes.\n */\nexport function validateId(id: string): void {\n  if (!id || typeof id !== \"string\") {\n    throw new Error(\"ID must be a non-empty string\");\n  }\n  // Length limit: DID bare identifiers are 36-60 bytes; 128 gives 2x headroom\n  if (id.length > 128) {\n    throw new Error(`ID exceeds max length: ${id.length}`);\n  }\n  if (/[/\\\\]/.test(id)) {\n    throw new Error(`ID contains path separator: ${id}`);\n  }\n  if (id.includes(\"..\")) {\n    throw new Error(`ID contains path traversal: ${id}`);\n  }\n  if (id.includes(\"\\0\")) {\n    throw new Error(`ID contains null byte: ${id}`);\n  }\n  // Decode-and-recheck: catch %2e%2e and similar percent-encoded bypasses\n  let decoded = id;\n  try {\n    decoded = decodeURIComponent(id);\n  } catch {\n    /* treat as literal if malformed */\n  }\n  if (decoded !== id) {\n    if (/[/\\\\]/.test(decoded)) throw new Error(`ID contains encoded path separator: ${id}`);\n    if (decoded.includes(\"..\")) throw new Error(`ID contains encoded traversal: ${id}`);\n    if (decoded.includes(\"\\0\")) throw new Error(`ID contains encoded null byte: ${id}`);\n  }\n}\n\n/**\n * Normalize an identifier by stripping any \"did:method:\" prefix.\n *\n * \"did:abt:persona\" → \"persona\"\n * \"did:web:example.com\" → \"example.com\"\n * \"persona\" → \"persona\" (unchanged)\n */\nexport function normalizeId(input: string): string {\n  const match = input.match(/^did:[a-z0-9]+:(.+)$/i);\n  return match?.[1] ?? input;\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,WAAW,IAAkB;AAC3C,KAAI,CAAC,MAAM,OAAO,OAAO,SACvB,OAAM,IAAI,MAAM,gCAAgC;AAGlD,KAAI,GAAG,SAAS,IACd,OAAM,IAAI,MAAM,0BAA0B,GAAG,SAAS;AAExD,KAAI,QAAQ,KAAK,GAAG,CAClB,OAAM,IAAI,MAAM,+BAA+B,KAAK;AAEtD,KAAI,GAAG,SAAS,KAAK,CACnB,OAAM,IAAI,MAAM,+BAA+B,KAAK;AAEtD,KAAI,GAAG,SAAS,KAAK,CACnB,OAAM,IAAI,MAAM,0BAA0B,KAAK;CAGjD,IAAI,UAAU;AACd,KAAI;AACF,YAAU,mBAAmB,GAAG;SAC1B;AAGR,KAAI,YAAY,IAAI;AAClB,MAAI,QAAQ,KAAK,QAAQ,CAAE,OAAM,IAAI,MAAM,uCAAuC,KAAK;AACvF,MAAI,QAAQ,SAAS,KAAK,CAAE,OAAM,IAAI,MAAM,kCAAkC,KAAK;AACnF,MAAI,QAAQ,SAAS,KAAK,CAAE,OAAM,IAAI,MAAM,kCAAkC,KAAK;;;;;;;;;;AAWvF,SAAgB,YAAY,OAAuB;AAEjD,QADc,MAAM,MAAM,wBAAwB,GACnC,MAAM"}

package/dist/dirty-path-queue.cjs

@@ -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
+exports.applyDirtyUpsert = applyDirtyUpsert;

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

@@ -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.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dirty-path-queue.d.cts","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"}