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

package/dist/ctime-backfill.mjs

@@ -0,0 +1,267 @@
+import { resolveParentDirStamp } from "./timestamp.mjs";
+import { parseTreeEntryMetadata } from "./tree-index.mjs";
+import { parentOf } from "./d1-tree-index.mjs";
+
+//#region src/ctime-backfill.ts
+/**
+* ctime-backfill — one-time backfill of `entries.ctime` from the application
+* `createdAt` for data written BEFORE the feed-sort Rule R landed
+* (planning/did-integration/feed-sort-createdat §7).
+*
+* Pre-fix, a FILE row's ctime was its insert time and its DIRECT-parent DIR row
+* was created `INSERT OR IGNORE` with `ctime = Date.now()` and never updated.
+* After Phase 3 switches the feed to `orderBy ctime`, those historical rows
+* would sort by insert time. This sweep rewrites them to match what a fresh
+* write would now stamp (R1 = file ctime, R2 = direct-parent DIR ctime/mtime).
+*
+* Design (mirrors inline-content-migration / scope-migration):
+*  - OFFLINE, code-driven. The core loop {@link backfillCtime} is backend-
+*    agnostic; the SQL lives in {@link CtimeBackfillBackend} adapters (D1 vs
+*    Node SQLite) so it is unit-testable against a mock D1.
+*  - **Host-language ISO parse** (`normalizeTs`) — NEVER SQLite `strftime`,
+*    which is unreliable for `Z`/offset/ms ISO-8601 (§7).
+*  - **WHERE pins `scope`** and binds scope/path as parameters — never a string
+*    interpolation; one scope is migrated at a time, never a cross-scope UPDATE.
+*  - **Deterministic `ORDER BY path ASC` keyset cursor** ⇒ for a degenerate
+*    DIR with several createdAt-bearing children, the LAST in path order wins
+*    (same LWW as the write path's R2 — NEVER MIN/MAX). Aside has exactly one
+*    createdAt child (`item.json`) per `{uuid}/`, so the result is deterministic.
+*  - **Idempotent**: each row is rewritten to `normalizeTs(createdAt)`, a fixed
+*    value, so a second pass writes the same value (0 effective change). The
+*    cursor advances past EVERY scanned row (including skips) so one invocation
+*    can't loop; a fresh invocation re-scans from the start.
+*  - **Only ctime/mtime change** — never cid/size/content/metadata. The FILE
+*    row's `mtime` (LWW arbiter) is NEVER touched; only its `ctime`. The DIR
+*    row gets both ctime+mtime (dir rows carry no LWW meaning, §1 fact 3).
+*  - **Batched / bounded** (`pageSize`, `maxPages`) to respect D1 write quota /
+*    avoid the O(N²) trap (cf. the D1 file_count burn-through lesson).
+*/
+/** Run `fn` over `items` with at most `limit` in flight (single-threaded pool). */
+async function mapPool(items, limit, fn) {
+	if (limit <= 1) {
+		for (const item of items) await fn(item);
+		return;
+	}
+	let i = 0;
+	const worker = async () => {
+		while (i < items.length) {
+			const item = items[i++];
+			if (item !== void 0) await fn(item);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+/**
+* Page over createdAt-bearing FILE rows in one scope and rewrite ctime (R1) +
+* the direct-parent DIR stamp (R2). Returns stats; resumable across calls.
+*/
+async function backfillCtime(backend, opts = {}) {
+	const pageSize = opts.pageSize ?? 200;
+	const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
+	const concurrency = Math.max(1, opts.concurrency ?? 1);
+	const dryRun = opts.dryRun ?? false;
+	const log = opts.log ?? (() => {});
+	const stats = {
+		scanned: 0,
+		stamped: 0,
+		alreadyCurrent: 0,
+		skippedNoCreatedAt: 0,
+		pages: 0,
+		lastCursor: "",
+		done: false
+	};
+	let cursor = "";
+	while (stats.pages < maxPages) {
+		const rows = await backend.selectCandidates(cursor, pageSize);
+		if (rows.length === 0) {
+			stats.done = true;
+			break;
+		}
+		stats.pages++;
+		const tasks = [];
+		for (const row of rows) {
+			stats.scanned++;
+			cursor = row.path;
+			const stamp = resolveParentDirStamp(parseTreeEntryMetadata(row.metadata));
+			if (!stamp) {
+				stats.skippedNoCreatedAt++;
+				continue;
+			}
+			tasks.push({
+				path: row.path,
+				ctime: stamp.ctime,
+				mtime: stamp.mtime
+			});
+		}
+		if (dryRun) stats.stamped += tasks.length;
+		else await mapPool(tasks, concurrency, async (t) => {
+			let changed = await backend.updateFileCtime(t.path, t.ctime);
+			const dir = parentOf(t.path);
+			if (dir) changed += await backend.updateDirStamp(dir, t.ctime, t.mtime);
+			if (changed > 0) stats.stamped++;
+			else stats.alreadyCurrent++;
+		});
+		stats.lastCursor = cursor;
+		log(`[ctime-backfill] page ${stats.pages}: scanned=${stats.scanned} stamped=${stats.stamped} cursor=${cursor}`);
+	}
+	return stats;
+}
+const SELECT_SQL = "SELECT path, metadata FROM ds_entries WHERE scope = ? AND kind = 'file' AND metadata IS NOT NULL AND path > ? ORDER BY path ASC LIMIT ?";
+const UPDATE_FILE_SQL = "UPDATE ds_entries SET ctime = ? WHERE scope = ? AND path = ? AND kind = 'file' AND ctime != ?";
+const UPDATE_DIR_SQL = "UPDATE ds_entries SET ctime = ?, mtime = ? WHERE scope = ? AND path = ? AND kind = 'dir' AND (ctime != ? OR mtime != ?)";
+/** D1 (Cloudflare) backend adapter for one scope. */
+function makeD1CtimeBackfillBackend(db, scope) {
+	return {
+		async selectCandidates(cursor, limit) {
+			return ((await db.prepare(SELECT_SQL).bind(scope, cursor, limit).all()).results ?? []).map((r) => ({
+				path: String(r.path),
+				metadata: r.metadata === null ? null : String(r.metadata)
+			}));
+		},
+		async updateFileCtime(path, ctime) {
+			return (await db.prepare(UPDATE_FILE_SQL).bind(ctime, scope, path, ctime).run()).meta?.changes ?? 0;
+		},
+		async updateDirStamp(dirPath, ctime, mtime) {
+			return (await db.prepare(UPDATE_DIR_SQL).bind(ctime, mtime, scope, dirPath, ctime, mtime).run()).meta?.changes ?? 0;
+		}
+	};
+}
+/** Node SQLite (libsql) backend adapter for one scope. */
+function makeSqliteCtimeBackfillBackend(db, scope) {
+	return {
+		async selectCandidates(cursor, limit) {
+			return (await db.execute({
+				sql: SELECT_SQL,
+				args: [
+					scope,
+					cursor,
+					limit
+				]
+			})).rows.map((r) => ({
+				path: String(r.path),
+				metadata: r.metadata === null ? null : String(r.metadata)
+			}));
+		},
+		async updateFileCtime(path, ctime) {
+			return (await db.execute({
+				sql: UPDATE_FILE_SQL,
+				args: [
+					ctime,
+					scope,
+					path,
+					ctime
+				]
+			})).rowsAffected ?? 0;
+		},
+		async updateDirStamp(dirPath, ctime, mtime) {
+			return (await db.execute({
+				sql: UPDATE_DIR_SQL,
+				args: [
+					ctime,
+					mtime,
+					scope,
+					dirPath,
+					ctime,
+					mtime
+				]
+			})).rowsAffected ?? 0;
+		}
+	};
+}
+const DISTINCT_SCOPES_SQL = "SELECT DISTINCT scope FROM ds_entries WHERE kind = 'file' AND metadata IS NOT NULL";
+/** Enumerate scopes that have any createdAt-bearing file row (D1). */
+async function distinctScopesWithMetadataD1(db) {
+	return ((await db.prepare(DISTINCT_SCOPES_SQL).bind().all()).results ?? []).map((r) => String(r.scope));
+}
+/** Enumerate scopes that have any createdAt-bearing file row (Node SQLite). */
+async function distinctScopesWithMetadataSqlite(db) {
+	return (await db.execute({
+		sql: DISTINCT_SCOPES_SQL,
+		args: []
+	})).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 (offline admin channel). */
+function makeD1HttpCtimeBackfillBackend(cfg) {
+	return {
+		async selectCandidates(cursor, limit) {
+			const { results } = await d1HttpQuery(cfg, SELECT_SQL, [
+				cfg.scope,
+				cursor,
+				limit
+			]);
+			return results.map((r) => ({
+				path: String(r.path),
+				metadata: r.metadata === null ? null : String(r.metadata)
+			}));
+		},
+		async updateFileCtime(path, ctime) {
+			const { changes } = await d1HttpQuery(cfg, UPDATE_FILE_SQL, [
+				ctime,
+				cfg.scope,
+				path,
+				ctime
+			]);
+			return changes;
+		},
+		async updateDirStamp(dirPath, ctime, mtime) {
+			const { changes } = await d1HttpQuery(cfg, UPDATE_DIR_SQL, [
+				ctime,
+				mtime,
+				cfg.scope,
+				dirPath,
+				ctime,
+				mtime
+			]);
+			return changes;
+		}
+	};
+}
+/** List distinct createdAt-bearing scopes on a CF D1 over HTTP (bulk sweep). */
+async function distinctScopesWithMetadataD1Http(cfg) {
+	const { results } = await d1HttpQuery(cfg, DISTINCT_SCOPES_SQL, []);
+	return results.map((r) => String(r.scope));
+}
+
+//#endregion
+export { backfillCtime, distinctScopesWithMetadataD1, distinctScopesWithMetadataD1Http, distinctScopesWithMetadataSqlite, makeD1CtimeBackfillBackend, makeD1HttpCtimeBackfillBackend, makeSqliteCtimeBackfillBackend };
+//# sourceMappingURL=ctime-backfill.mjs.map

package/dist/ctime-backfill.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctime-backfill.mjs","names":[],"sources":["../src/ctime-backfill.ts"],"sourcesContent":["/**\n * ctime-backfill — one-time backfill of `entries.ctime` from the application\n * `createdAt` for data written BEFORE the feed-sort Rule R landed\n * (planning/did-integration/feed-sort-createdat §7).\n *\n * Pre-fix, a FILE row's ctime was its insert time and its DIRECT-parent DIR row\n * was created `INSERT OR IGNORE` with `ctime = Date.now()` and never updated.\n * After Phase 3 switches the feed to `orderBy ctime`, those historical rows\n * would sort by insert time. This sweep rewrites them to match what a fresh\n * write would now stamp (R1 = file ctime, R2 = direct-parent DIR ctime/mtime).\n *\n * Design (mirrors inline-content-migration / scope-migration):\n *  - OFFLINE, code-driven. The core loop {@link backfillCtime} is backend-\n *    agnostic; the SQL lives in {@link CtimeBackfillBackend} adapters (D1 vs\n *    Node SQLite) so it is unit-testable against a mock D1.\n *  - **Host-language ISO parse** (`normalizeTs`) — NEVER SQLite `strftime`,\n *    which is unreliable for `Z`/offset/ms ISO-8601 (§7).\n *  - **WHERE pins `scope`** and binds scope/path as parameters — never a string\n *    interpolation; one scope is migrated at a time, never a cross-scope UPDATE.\n *  - **Deterministic `ORDER BY path ASC` keyset cursor** ⇒ for a degenerate\n *    DIR with several createdAt-bearing children, the LAST in path order wins\n *    (same LWW as the write path's R2 — NEVER MIN/MAX). Aside has exactly one\n *    createdAt child (`item.json`) per `{uuid}/`, so the result is deterministic.\n *  - **Idempotent**: each row is rewritten to `normalizeTs(createdAt)`, a fixed\n *    value, so a second pass writes the same value (0 effective change). The\n *    cursor advances past EVERY scanned row (including skips) so one invocation\n *    can't loop; a fresh invocation re-scans from the start.\n *  - **Only ctime/mtime change** — never cid/size/content/metadata. The FILE\n *    row's `mtime` (LWW arbiter) is NEVER touched; only its `ctime`. The DIR\n *    row gets both ctime+mtime (dir rows carry no LWW meaning, §1 fact 3).\n *  - **Batched / bounded** (`pageSize`, `maxPages`) to respect D1 write quota /\n *    avoid the O(N²) trap (cf. the D1 file_count burn-through lesson).\n */\n\nimport { parentOf } from \"./d1-tree-index.js\";\nimport { resolveParentDirStamp } from \"./timestamp.js\";\nimport { parseTreeEntryMetadata } from \"./tree-index.js\";\n\n/** A FILE row with non-null metadata — a backfill candidate. */\nexport interface CtimeBackfillCandidate {\n  path: string;\n  /** Raw `entries.metadata` JSON blob (host-parsed here, never in SQL). */\n  metadata: string | null;\n}\n\n/** Backend-specific SQL for the sweep (D1 vs Node SQLite). One scope each. */\nexport interface CtimeBackfillBackend {\n  /**\n   * Select up to `limit` FILE rows with `metadata IS NOT NULL` and\n   * `path > cursor`, ordered `path ASC` (the keyset cursor). Empty ⇒ done.\n   */\n  selectCandidates(cursor: string, limit: number): Promise<CtimeBackfillCandidate[]>;\n  /**\n   * R1: set the FILE row's `ctime` (NEVER its mtime). The UPDATE is guarded\n   * `AND ctime != ?` so an already-migrated row is a 0-row no-op (re-runs burn\n   * no D1 write quota). Returns the number of rows actually changed (0 or 1).\n   */\n  updateFileCtime(path: string, ctime: number): Promise<number>;\n  /**\n   * R2: set the DIRECT-parent DIR row's `ctime` + `mtime`, guarded so an\n   * already-current dir is a no-op. Returns rows actually changed (0 or 1).\n   */\n  updateDirStamp(dirPath: string, ctime: number, mtime: number): Promise<number>;\n}\n\nexport interface CtimeBackfillOptions {\n  /** Rows per page (bounds the D1 write budget per invocation). Default 200. */\n  pageSize?: number;\n  /** Cap pages this invocation (cross-invocation paging). Default unbounded. */\n  maxPages?: number;\n  /**\n   * Max concurrent UPDATE round-trips WITHIN a page. Default 1 (serial — the\n   * deterministic reference behavior). >1 is a throughput win for the high-\n   * latency D1-HTTP channel (each row = 2 sequential UPDATEs otherwise).\n   *\n   * ⚠️ Concurrency > 1 makes the direct-parent DIR stamp NON-deterministic for\n   * a degenerate collection where MULTIPLE createdAt-bearing rows share one\n   * direct parent (the `ORDER BY path` last-writer-wins guarantee only holds\n   * serially). SAFE for dir-per-record collections (Aside: exactly one\n   * createdAt child — `item.json` — per `{uuid}/`, no shared parent). Use 1\n   * for strict determinism on degenerate shapes. Node SQLite (single\n   * connection) gains nothing — keep it 1 there.\n   */\n  concurrency?: number;\n  /**\n   * Preview only — scan + count candidates, run NO UPDATE. `stats.stamped`\n   * then reports rows that WOULD be stamped (an upper bound; the real run's\n   * `AND ctime != ?` guard skips already-current rows as 0-write). `scanned`\n   * and `skippedNoCreatedAt` are exact in both modes.\n   */\n  dryRun?: boolean;\n  log?: (msg: string) => void;\n}\n\nexport interface CtimeBackfillStats {\n  /** FILE rows examined (metadata IS NOT NULL). */\n  scanned: number;\n  /** Rows where a ctime/mtime value ACTUALLY changed (file and/or dir). */\n  stamped: number;\n  /**\n   * Rows that had a valid createdAt but were already at the target value — a\n   * 0-write no-op. On a clean second run this equals `scanned` and `stamped`\n   * is 0 (the spec's \"第二趟 0 改动\" idempotency contract).\n   */\n  alreadyCurrent: number;\n  /** Rows with metadata but no usable createdAt — left at insert time. */\n  skippedNoCreatedAt: 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/** Run `fn` over `items` with at most `limit` in flight (single-threaded pool). */\nasync function mapPool<T>(\n  items: T[],\n  limit: number,\n  fn: (item: T) => Promise<void>,\n): Promise<void> {\n  if (limit <= 1) {\n    for (const item of items) await fn(item);\n    return;\n  }\n  let i = 0;\n  const worker = async () => {\n    while (i < items.length) {\n      const item = items[i++];\n      if (item !== undefined) await fn(item);\n    }\n  };\n  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));\n}\n\n/**\n * Page over createdAt-bearing FILE rows in one scope and rewrite ctime (R1) +\n * the direct-parent DIR stamp (R2). Returns stats; resumable across calls.\n */\nexport async function backfillCtime(\n  backend: CtimeBackfillBackend,\n  opts: CtimeBackfillOptions = {},\n): Promise<CtimeBackfillStats> {\n  const pageSize = opts.pageSize ?? 200;\n  const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;\n  const concurrency = Math.max(1, opts.concurrency ?? 1);\n  const dryRun = opts.dryRun ?? false;\n  const log = opts.log ?? (() => {});\n\n  const stats: CtimeBackfillStats = {\n    scanned: 0,\n    stamped: 0,\n    alreadyCurrent: 0,\n    skippedNoCreatedAt: 0,\n    pages: 0,\n    lastCursor: \"\",\n    done: false,\n  };\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    // Build the page's task list SERIALLY (preserves `ORDER BY path` for the\n    // cursor + the degenerate-parent last-writer determinism at concurrency 1).\n    const tasks: Array<{ path: string; ctime: number; mtime: number }> = [];\n    for (const row of rows) {\n      stats.scanned++;\n      cursor = row.path; // advance past EVERY scanned row so a single pass can't loop\n      // resolveParentDirStamp = the SAME R2 helper the write path uses:\n      // { ctime: normalizeTs(createdAt), mtime: normalizeTs(updatedAt) ?? ctime }\n      // or null when createdAt is missing/malformed (→ leave insert time).\n      const stamp = resolveParentDirStamp(parseTreeEntryMetadata(row.metadata));\n      if (!stamp) {\n        stats.skippedNoCreatedAt++;\n        continue;\n      }\n      tasks.push({ path: row.path, ctime: stamp.ctime, mtime: stamp.mtime });\n    }\n\n    if (dryRun) {\n      stats.stamped += tasks.length; // would-stamp (no UPDATE issued)\n    } else {\n      await mapPool(tasks, concurrency, async (t) => {\n        // R1: file ctime = normalizeTs(createdAt) (mtime untouched).\n        let changed = await backend.updateFileCtime(t.path, t.ctime);\n        // R2: direct parent only — never propagate to ancestors.\n        const dir = parentOf(t.path);\n        if (dir) changed += await backend.updateDirStamp(dir, t.ctime, t.mtime);\n        // Guarded UPDATEs are 0-row no-ops when already at target → a clean\n        // re-run changes nothing (spec §7: \"第二趟 0 改动\").\n        if (changed > 0) stats.stamped++;\n        else stats.alreadyCurrent++;\n      });\n    }\n    // The cursor always ends at this page's last row — resumption is per-page.\n    stats.lastCursor = cursor;\n    log(\n      `[ctime-backfill] page ${stats.pages}: scanned=${stats.scanned} stamped=${stats.stamped} cursor=${cursor}`,\n    );\n  }\n  return stats;\n}\n\n// ── SQL (shared by both adapters; entries PK is (scope, path)) ──────────────\nconst SELECT_SQL =\n  \"SELECT path, metadata FROM ds_entries WHERE scope = ? AND kind = 'file' \" +\n  \"AND metadata IS NOT NULL AND path > ? ORDER BY path ASC LIMIT ?\";\n// File: ONLY ctime — mtime is the LWW arbiter and stays put. Guarded\n// `AND ctime != ?` so an already-migrated row is a 0-row no-op (idempotent\n// re-runs burn no write quota). Bind order: (ctime, scope, path, ctime).\nconst UPDATE_FILE_SQL =\n  \"UPDATE ds_entries SET ctime = ? WHERE scope = ? AND path = ? AND kind = 'file' AND ctime != ?\";\n// Dir: ctime + mtime (dir rows carry no LWW meaning). Guarded so an already-\n// current dir is a no-op. Bind order: (ctime, mtime, scope, path, ctime, mtime).\nconst UPDATE_DIR_SQL =\n  \"UPDATE ds_entries SET ctime = ?, mtime = ? WHERE scope = ? AND path = ? AND kind = 'dir' AND (ctime != ? OR mtime != ?)\";\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) backend adapter for one scope. */\nexport function makeD1CtimeBackfillBackend(db: D1Like, scope: string): CtimeBackfillBackend {\n  return {\n    async selectCandidates(cursor, limit) {\n      const res = await db.prepare(SELECT_SQL).bind(scope, cursor, limit).all();\n      return ((res.results ?? []) as Array<Record<string, unknown>>).map((r) => ({\n        path: String(r.path),\n        metadata: r.metadata === null ? null : String(r.metadata),\n      }));\n    },\n    async updateFileCtime(path, ctime) {\n      const r = await db.prepare(UPDATE_FILE_SQL).bind(ctime, scope, path, ctime).run();\n      return r.meta?.changes ?? 0;\n    },\n    async updateDirStamp(dirPath, ctime, mtime) {\n      const r = await db\n        .prepare(UPDATE_DIR_SQL)\n        .bind(ctime, mtime, scope, dirPath, ctime, mtime)\n        .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. */\nexport function makeSqliteCtimeBackfillBackend(\n  db: LibsqlLike,\n  scope: string,\n): CtimeBackfillBackend {\n  return {\n    async selectCandidates(cursor, limit) {\n      const res = await db.execute({ sql: SELECT_SQL, args: [scope, cursor, limit] });\n      return res.rows.map((r) => ({\n        path: String(r.path),\n        metadata: r.metadata === null ? null : String(r.metadata),\n      }));\n    },\n    async updateFileCtime(path, ctime) {\n      const r = await db.execute({ sql: UPDATE_FILE_SQL, args: [ctime, scope, path, ctime] });\n      return r.rowsAffected ?? 0;\n    },\n    async updateDirStamp(dirPath, ctime, mtime) {\n      const r = await db.execute({\n        sql: UPDATE_DIR_SQL,\n        args: [ctime, mtime, scope, dirPath, ctime, mtime],\n      });\n      return r.rowsAffected ?? 0;\n    },\n  };\n}\n\nconst DISTINCT_SCOPES_SQL =\n  \"SELECT DISTINCT scope FROM ds_entries WHERE kind = 'file' AND metadata IS NOT NULL\";\n\n/** Enumerate scopes that have any createdAt-bearing file row (D1). */\nexport async function distinctScopesWithMetadataD1(db: D1Like): Promise<string[]> {\n  const res = await db.prepare(DISTINCT_SCOPES_SQL).bind().all();\n  return ((res.results ?? []) as Array<Record<string, unknown>>).map((r) => String(r.scope));\n}\n\n/** Enumerate scopes that have any createdAt-bearing file row (Node SQLite). */\nexport async function distinctScopesWithMetadataSqlite(db: LibsqlLike): Promise<string[]> {\n  const res = await db.execute({ sql: DISTINCT_SCOPES_SQL, args: [] });\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 involved — ctime backfill is pure index UPDATEs. `fetchImpl` /\n * `sleep` are injectable for tests.\n */\nexport interface CtimeBackfillD1HttpConfig {\n  accountId: string;\n  databaseId: string;\n  apiToken: string;\n  scope: 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: Omit<CtimeBackfillD1HttpConfig, \"scope\">,\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 (offline admin channel). */\nexport function makeD1HttpCtimeBackfillBackend(\n  cfg: CtimeBackfillD1HttpConfig,\n): CtimeBackfillBackend {\n  return {\n    async selectCandidates(cursor, limit) {\n      const { results } = await d1HttpQuery(cfg, SELECT_SQL, [cfg.scope, cursor, limit]);\n      return results.map((r) => ({\n        path: String(r.path),\n        metadata: r.metadata === null ? null : String(r.metadata),\n      }));\n    },\n    async updateFileCtime(path, ctime) {\n      const { changes } = await d1HttpQuery(cfg, UPDATE_FILE_SQL, [ctime, cfg.scope, path, ctime]);\n      return changes;\n    },\n    async updateDirStamp(dirPath, ctime, mtime) {\n      const { changes } = await d1HttpQuery(cfg, UPDATE_DIR_SQL, [\n        ctime,\n        mtime,\n        cfg.scope,\n        dirPath,\n        ctime,\n        mtime,\n      ]);\n      return changes;\n    },\n  };\n}\n\n/** List distinct createdAt-bearing scopes on a CF D1 over HTTP (bulk sweep). */\nexport async function distinctScopesWithMetadataD1Http(\n  cfg: Omit<CtimeBackfillD1HttpConfig, \"scope\">,\n): Promise<string[]> {\n  const { results } = await d1HttpQuery(cfg, DISTINCT_SCOPES_SQL, []);\n  return results.map((r) => String(r.scope));\n}\n"],"mappings":"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"}

package/dist/d1-gc-queue.cjs

@@ -0,0 +1,80 @@
+const require_d1_schema = require('./d1-schema.cjs');
+
+//#region src/d1-gc-queue.ts
+/**
+* D1GCQueue — deferred garbage-collection queue backed by D1 (SQLite).
+*
+* When a file is overwritten or deleted, the old CID is enqueued here.
+* A scheduled GC job later checks `entries` for live references before
+* deleting the corresponding R2 object.
+*
+* Implements the pure-storage {@link GcQueue} interface (`ensureTable`,
+* `enqueue`, `fetchCandidates`, `remove`). Liveness is decided separately:
+* `runGc` uses the entries-only `referencedAnywhere` (design §3, §4.4b) and
+* read-auth uses the scope-aware three-way `TreeIndex.isReferenced(Many)`.
+* (The old scope-blind three-way `isReferenced` method that lived here — the
+* only reader of the now-removed global `idx_changelog_cid`/`_old_cid` indexes
+* — was retired with migration 0110; the `GcQueue` interface deliberately has
+* no liveness method, §0.2.)
+*
+* Schema (migration 0004_gc_queue.sql):
+*   CREATE TABLE gc_queue (
+*     cid       TEXT    NOT NULL PRIMARY KEY,
+*     queued_at INTEGER NOT NULL
+*   )
+*/
+var D1GCQueue = class {
+	constructor(db) {
+		this.db = db;
+	}
+	/**
+	* Create the gc_queue table. Used in tests with in-memory DB.
+	* Production: schema created by `wrangler d1 migrations apply`.
+	*/
+	async ensureTable() {
+		await this.db.prepare(require_d1_schema.GC_QUEUE_TABLE_SQL).run();
+		for (const sql of require_d1_schema.GC_QUEUE_INDEX_SQL) await this.db.prepare(sql).run();
+	}
+	/**
+	* Enqueue CIDs for deferred GC. Idempotent — duplicate CIDs are silently ignored.
+	* Empty array is a no-op (no D1 calls made).
+	*/
+	async enqueue(cids) {
+		if (cids.length === 0) return;
+		const now = Date.now();
+		const stmts = cids.map((cid) => this.db.prepare("INSERT INTO ds_gc_queue (cid, queued_at) VALUES (?, ?) ON CONFLICT DO NOTHING").bind(cid, now));
+		await this.db.batch(stmts);
+	}
+	/**
+	* Fetch GC candidates whose grace period has expired.
+	* @param limit  Maximum number of candidates to return (default 500).
+	* @param graceMs  Grace period in milliseconds (default 2 hours). Only CIDs
+	*                 enqueued more than graceMs ago are returned.
+	*/
+	async fetchCandidates(limit = 500, graceMs = 7200 * 1e3) {
+		if (limit === 0) return [];
+		const { results } = await this.db.prepare("SELECT cid FROM ds_gc_queue WHERE queued_at <= ? LIMIT ?").bind(Date.now() - graceMs, limit).all();
+		return results;
+	}
+	/**
+	* Remove a CID from the queue after its R2 object has been deleted
+	* or after confirming it still has live references.
+	*/
+	async remove(cid) {
+		await this.db.prepare("DELETE FROM ds_gc_queue WHERE cid = ?").bind(cid).run();
+	}
+	/** DELETE … IN, chunked at ≤90 binds (D1 limit) but issued as ONE
+	*  db.batch round trip — afs-rpc-batch P3. */
+	async removeMany(cids) {
+		if (cids.length === 0) return;
+		const stmts = [];
+		for (let offset = 0; offset < cids.length; offset += 90) {
+			const chunk = cids.slice(offset, offset + 90);
+			stmts.push(this.db.prepare(`DELETE FROM ds_gc_queue WHERE cid IN (${chunk.map(() => "?").join(",")})`).bind(...chunk));
+		}
+		await this.db.batch(stmts);
+	}
+};
+
+//#endregion
+exports.D1GCQueue = D1GCQueue;

package/dist/d1-gc-queue.d.cts

@@ -0,0 +1,59 @@
+import { GcQueue } from "./gc-queue.cjs";
+
+//#region src/d1-gc-queue.d.ts
+/**
+ * D1GCQueue — deferred garbage-collection queue backed by D1 (SQLite).
+ *
+ * When a file is overwritten or deleted, the old CID is enqueued here.
+ * A scheduled GC job later checks `entries` for live references before
+ * deleting the corresponding R2 object.
+ *
+ * Implements the pure-storage {@link GcQueue} interface (`ensureTable`,
+ * `enqueue`, `fetchCandidates`, `remove`). Liveness is decided separately:
+ * `runGc` uses the entries-only `referencedAnywhere` (design §3, §4.4b) and
+ * read-auth uses the scope-aware three-way `TreeIndex.isReferenced(Many)`.
+ * (The old scope-blind three-way `isReferenced` method that lived here — the
+ * only reader of the now-removed global `idx_changelog_cid`/`_old_cid` indexes
+ * — was retired with migration 0110; the `GcQueue` interface deliberately has
+ * no liveness method, §0.2.)
+ *
+ * Schema (migration 0004_gc_queue.sql):
+ *   CREATE TABLE gc_queue (
+ *     cid       TEXT    NOT NULL PRIMARY KEY,
+ *     queued_at INTEGER NOT NULL
+ *   )
+ */
+declare class D1GCQueue implements GcQueue {
+  private readonly db;
+  constructor(db: D1Database);
+  /**
+   * Create the gc_queue table. Used in tests with in-memory DB.
+   * Production: schema created by `wrangler d1 migrations apply`.
+   */
+  ensureTable(): Promise<void>;
+  /**
+   * Enqueue CIDs for deferred GC. Idempotent — duplicate CIDs are silently ignored.
+   * Empty array is a no-op (no D1 calls made).
+   */
+  enqueue(cids: string[]): Promise<void>;
+  /**
+   * Fetch GC candidates whose grace period has expired.
+   * @param limit  Maximum number of candidates to return (default 500).
+   * @param graceMs  Grace period in milliseconds (default 2 hours). Only CIDs
+   *                 enqueued more than graceMs ago are returned.
+   */
+  fetchCandidates(limit?: number, graceMs?: number): Promise<Array<{
+    cid: string;
+  }>>;
+  /**
+   * Remove a CID from the queue after its R2 object has been deleted
+   * or after confirming it still has live references.
+   */
+  remove(cid: string): Promise<void>;
+  /** DELETE … IN, chunked at ≤90 binds (D1 limit) but issued as ONE
+   *  db.batch round trip — afs-rpc-batch P3. */
+  removeMany(cids: string[]): Promise<void>;
+}
+//#endregion
+export { D1GCQueue };
+//# sourceMappingURL=d1-gc-queue.d.cts.map

package/dist/d1-gc-queue.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1-gc-queue.d.cts","names":[],"sources":["../src/d1-gc-queue.ts"],"mappings":";;;;;AAyBA;;;;;;;;;;;;;;;;;;;;cAAa,SAAA,YAAqB,OAAA;EAAA,iBACH,EAAA;cAAA,EAAA,EAAI,UAAA;EAgC3B;;;;EA1BA,WAAA,CAAA,GAAe,OAAA;EA6BF;;;;EApBb,OAAA,CAAQ,IAAA,aAAiB,OAAA;EAuCd;;;;;;EAtBX,eAAA,CACJ,KAAA,WACA,OAAA,YACC,OAAA,CAAQ,KAAA;IAAQ,GAAA;EAAA;;;;;EAab,MAAA,CAAO,GAAA,WAAc,OAAA;;;EAMrB,UAAA,CAAW,IAAA,aAAiB,OAAA;AAAA"}

package/dist/d1-gc-queue.d.mts

@@ -0,0 +1,59 @@
+import { GcQueue } from "./gc-queue.mjs";
+
+//#region src/d1-gc-queue.d.ts
+/**
+ * D1GCQueue — deferred garbage-collection queue backed by D1 (SQLite).
+ *
+ * When a file is overwritten or deleted, the old CID is enqueued here.
+ * A scheduled GC job later checks `entries` for live references before
+ * deleting the corresponding R2 object.
+ *
+ * Implements the pure-storage {@link GcQueue} interface (`ensureTable`,
+ * `enqueue`, `fetchCandidates`, `remove`). Liveness is decided separately:
+ * `runGc` uses the entries-only `referencedAnywhere` (design §3, §4.4b) and
+ * read-auth uses the scope-aware three-way `TreeIndex.isReferenced(Many)`.
+ * (The old scope-blind three-way `isReferenced` method that lived here — the
+ * only reader of the now-removed global `idx_changelog_cid`/`_old_cid` indexes
+ * — was retired with migration 0110; the `GcQueue` interface deliberately has
+ * no liveness method, §0.2.)
+ *
+ * Schema (migration 0004_gc_queue.sql):
+ *   CREATE TABLE gc_queue (
+ *     cid       TEXT    NOT NULL PRIMARY KEY,
+ *     queued_at INTEGER NOT NULL
+ *   )
+ */
+declare class D1GCQueue implements GcQueue {
+  private readonly db;
+  constructor(db: D1Database);
+  /**
+   * Create the gc_queue table. Used in tests with in-memory DB.
+   * Production: schema created by `wrangler d1 migrations apply`.
+   */
+  ensureTable(): Promise<void>;
+  /**
+   * Enqueue CIDs for deferred GC. Idempotent — duplicate CIDs are silently ignored.
+   * Empty array is a no-op (no D1 calls made).
+   */
+  enqueue(cids: string[]): Promise<void>;
+  /**
+   * Fetch GC candidates whose grace period has expired.
+   * @param limit  Maximum number of candidates to return (default 500).
+   * @param graceMs  Grace period in milliseconds (default 2 hours). Only CIDs
+   *                 enqueued more than graceMs ago are returned.
+   */
+  fetchCandidates(limit?: number, graceMs?: number): Promise<Array<{
+    cid: string;
+  }>>;
+  /**
+   * Remove a CID from the queue after its R2 object has been deleted
+   * or after confirming it still has live references.
+   */
+  remove(cid: string): Promise<void>;
+  /** DELETE … IN, chunked at ≤90 binds (D1 limit) but issued as ONE
+   *  db.batch round trip — afs-rpc-batch P3. */
+  removeMany(cids: string[]): Promise<void>;
+}
+//#endregion
+export { D1GCQueue };
+//# sourceMappingURL=d1-gc-queue.d.mts.map

package/dist/d1-gc-queue.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1-gc-queue.d.mts","names":[],"sources":["../src/d1-gc-queue.ts"],"mappings":";;;;;AAyBA;;;;;;;;;;;;;;;;;;;;cAAa,SAAA,YAAqB,OAAA;EAAA,iBACH,EAAA;cAAA,EAAA,EAAI,UAAA;EAgC3B;;;;EA1BA,WAAA,CAAA,GAAe,OAAA;EA6BF;;;;EApBb,OAAA,CAAQ,IAAA,aAAiB,OAAA;EAuCd;;;;;;EAtBX,eAAA,CACJ,KAAA,WACA,OAAA,YACC,OAAA,CAAQ,KAAA;IAAQ,GAAA;EAAA;;;;;EAab,MAAA,CAAO,GAAA,WAAc,OAAA;;;EAMrB,UAAA,CAAW,IAAA,aAAiB,OAAA;AAAA"}

package/dist/d1-gc-queue.mjs

@@ -0,0 +1,81 @@
+import { GC_QUEUE_INDEX_SQL, GC_QUEUE_TABLE_SQL } from "./d1-schema.mjs";
+
+//#region src/d1-gc-queue.ts
+/**
+* D1GCQueue — deferred garbage-collection queue backed by D1 (SQLite).
+*
+* When a file is overwritten or deleted, the old CID is enqueued here.
+* A scheduled GC job later checks `entries` for live references before
+* deleting the corresponding R2 object.
+*
+* Implements the pure-storage {@link GcQueue} interface (`ensureTable`,
+* `enqueue`, `fetchCandidates`, `remove`). Liveness is decided separately:
+* `runGc` uses the entries-only `referencedAnywhere` (design §3, §4.4b) and
+* read-auth uses the scope-aware three-way `TreeIndex.isReferenced(Many)`.
+* (The old scope-blind three-way `isReferenced` method that lived here — the
+* only reader of the now-removed global `idx_changelog_cid`/`_old_cid` indexes
+* — was retired with migration 0110; the `GcQueue` interface deliberately has
+* no liveness method, §0.2.)
+*
+* Schema (migration 0004_gc_queue.sql):
+*   CREATE TABLE gc_queue (
+*     cid       TEXT    NOT NULL PRIMARY KEY,
+*     queued_at INTEGER NOT NULL
+*   )
+*/
+var D1GCQueue = class {
+	constructor(db) {
+		this.db = db;
+	}
+	/**
+	* Create the gc_queue table. Used in tests with in-memory DB.
+	* Production: schema created by `wrangler d1 migrations apply`.
+	*/
+	async ensureTable() {
+		await this.db.prepare(GC_QUEUE_TABLE_SQL).run();
+		for (const sql of GC_QUEUE_INDEX_SQL) await this.db.prepare(sql).run();
+	}
+	/**
+	* Enqueue CIDs for deferred GC. Idempotent — duplicate CIDs are silently ignored.
+	* Empty array is a no-op (no D1 calls made).
+	*/
+	async enqueue(cids) {
+		if (cids.length === 0) return;
+		const now = Date.now();
+		const stmts = cids.map((cid) => this.db.prepare("INSERT INTO ds_gc_queue (cid, queued_at) VALUES (?, ?) ON CONFLICT DO NOTHING").bind(cid, now));
+		await this.db.batch(stmts);
+	}
+	/**
+	* Fetch GC candidates whose grace period has expired.
+	* @param limit  Maximum number of candidates to return (default 500).
+	* @param graceMs  Grace period in milliseconds (default 2 hours). Only CIDs
+	*                 enqueued more than graceMs ago are returned.
+	*/
+	async fetchCandidates(limit = 500, graceMs = 7200 * 1e3) {
+		if (limit === 0) return [];
+		const { results } = await this.db.prepare("SELECT cid FROM ds_gc_queue WHERE queued_at <= ? LIMIT ?").bind(Date.now() - graceMs, limit).all();
+		return results;
+	}
+	/**
+	* Remove a CID from the queue after its R2 object has been deleted
+	* or after confirming it still has live references.
+	*/
+	async remove(cid) {
+		await this.db.prepare("DELETE FROM ds_gc_queue WHERE cid = ?").bind(cid).run();
+	}
+	/** DELETE … IN, chunked at ≤90 binds (D1 limit) but issued as ONE
+	*  db.batch round trip — afs-rpc-batch P3. */
+	async removeMany(cids) {
+		if (cids.length === 0) return;
+		const stmts = [];
+		for (let offset = 0; offset < cids.length; offset += 90) {
+			const chunk = cids.slice(offset, offset + 90);
+			stmts.push(this.db.prepare(`DELETE FROM ds_gc_queue WHERE cid IN (${chunk.map(() => "?").join(",")})`).bind(...chunk));
+		}
+		await this.db.batch(stmts);
+	}
+};
+
+//#endregion
+export { D1GCQueue };
+//# sourceMappingURL=d1-gc-queue.mjs.map

package/dist/d1-gc-queue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1-gc-queue.mjs","names":[],"sources":["../src/d1-gc-queue.ts"],"sourcesContent":["import { GC_QUEUE_INDEX_SQL, GC_QUEUE_TABLE_SQL } from \"./d1-schema.js\";\nimport type { GcQueue } from \"./gc-queue.js\";\n\n/**\n * D1GCQueue — deferred garbage-collection queue backed by D1 (SQLite).\n *\n * When a file is overwritten or deleted, the old CID is enqueued here.\n * A scheduled GC job later checks `entries` for live references before\n * deleting the corresponding R2 object.\n *\n * Implements the pure-storage {@link GcQueue} interface (`ensureTable`,\n * `enqueue`, `fetchCandidates`, `remove`). Liveness is decided separately:\n * `runGc` uses the entries-only `referencedAnywhere` (design §3, §4.4b) and\n * read-auth uses the scope-aware three-way `TreeIndex.isReferenced(Many)`.\n * (The old scope-blind three-way `isReferenced` method that lived here — the\n * only reader of the now-removed global `idx_changelog_cid`/`_old_cid` indexes\n * — was retired with migration 0110; the `GcQueue` interface deliberately has\n * no liveness method, §0.2.)\n *\n * Schema (migration 0004_gc_queue.sql):\n *   CREATE TABLE gc_queue (\n *     cid       TEXT    NOT NULL PRIMARY KEY,\n *     queued_at INTEGER NOT NULL\n *   )\n */\nexport class D1GCQueue implements GcQueue {\n  constructor(private readonly db: D1Database) {}\n\n  /**\n   * Create the gc_queue table. Used in tests with in-memory DB.\n   * Production: schema created by `wrangler d1 migrations apply`.\n   */\n  async ensureTable(): Promise<void> {\n    await this.db.prepare(GC_QUEUE_TABLE_SQL).run();\n    for (const sql of GC_QUEUE_INDEX_SQL) await this.db.prepare(sql).run();\n  }\n\n  /**\n   * Enqueue CIDs for deferred GC. Idempotent — duplicate CIDs are silently ignored.\n   * Empty array is a no-op (no D1 calls made).\n   */\n  async enqueue(cids: string[]): Promise<void> {\n    if (cids.length === 0) return;\n    const now = Date.now();\n    const stmts = cids.map((cid) =>\n      this.db\n        .prepare(\"INSERT INTO ds_gc_queue (cid, queued_at) VALUES (?, ?) ON CONFLICT DO NOTHING\")\n        .bind(cid, now),\n    );\n    await this.db.batch(stmts);\n  }\n\n  /**\n   * Fetch GC candidates whose grace period has expired.\n   * @param limit  Maximum number of candidates to return (default 500).\n   * @param graceMs  Grace period in milliseconds (default 2 hours). Only CIDs\n   *                 enqueued more than graceMs ago are returned.\n   */\n  async fetchCandidates(\n    limit = 500,\n    graceMs = 2 * 60 * 60 * 1000,\n  ): Promise<Array<{ cid: string }>> {\n    if (limit === 0) return [];\n    const { results } = await this.db\n      .prepare(\"SELECT cid FROM ds_gc_queue WHERE queued_at <= ? LIMIT ?\")\n      .bind(Date.now() - graceMs, limit)\n      .all<{ cid: string }>();\n    return results;\n  }\n\n  /**\n   * Remove a CID from the queue after its R2 object has been deleted\n   * or after confirming it still has live references.\n   */\n  async remove(cid: string): Promise<void> {\n    await this.db.prepare(\"DELETE FROM ds_gc_queue WHERE cid = ?\").bind(cid).run();\n  }\n\n  /** DELETE … IN, chunked at ≤90 binds (D1 limit) but issued as ONE\n   *  db.batch round trip — afs-rpc-batch P3. */\n  async removeMany(cids: string[]): Promise<void> {\n    if (cids.length === 0) return;\n    const stmts: D1PreparedStatement[] = [];\n    for (let offset = 0; offset < cids.length; offset += 90) {\n      const chunk = cids.slice(offset, offset + 90);\n      stmts.push(\n        this.db\n          .prepare(`DELETE FROM ds_gc_queue WHERE cid IN (${chunk.map(() => \"?\").join(\",\")})`)\n          .bind(...chunk),\n      );\n    }\n    await this.db.batch(stmts);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,IAAa,YAAb,MAA0C;CACxC,YAAY,AAAiB,IAAgB;EAAhB;;;;;;CAM7B,MAAM,cAA6B;AACjC,QAAM,KAAK,GAAG,QAAQ,mBAAmB,CAAC,KAAK;AAC/C,OAAK,MAAM,OAAO,mBAAoB,OAAM,KAAK,GAAG,QAAQ,IAAI,CAAC,KAAK;;;;;;CAOxE,MAAM,QAAQ,MAA+B;AAC3C,MAAI,KAAK,WAAW,EAAG;EACvB,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,QAAQ,KAAK,KAAK,QACtB,KAAK,GACF,QAAQ,gFAAgF,CACxF,KAAK,KAAK,IAAI,CAClB;AACD,QAAM,KAAK,GAAG,MAAM,MAAM;;;;;;;;CAS5B,MAAM,gBACJ,QAAQ,KACR,UAAU,OAAc,KACS;AACjC,MAAI,UAAU,EAAG,QAAO,EAAE;EAC1B,MAAM,EAAE,YAAY,MAAM,KAAK,GAC5B,QAAQ,2DAA2D,CACnE,KAAK,KAAK,KAAK,GAAG,SAAS,MAAM,CACjC,KAAsB;AACzB,SAAO;;;;;;CAOT,MAAM,OAAO,KAA4B;AACvC,QAAM,KAAK,GAAG,QAAQ,wCAAwC,CAAC,KAAK,IAAI,CAAC,KAAK;;;;CAKhF,MAAM,WAAW,MAA+B;AAC9C,MAAI,KAAK,WAAW,EAAG;EACvB,MAAM,QAA+B,EAAE;AACvC,OAAK,IAAI,SAAS,GAAG,SAAS,KAAK,QAAQ,UAAU,IAAI;GACvD,MAAM,QAAQ,KAAK,MAAM,QAAQ,SAAS,GAAG;AAC7C,SAAM,KACJ,KAAK,GACF,QAAQ,yCAAyC,MAAM,UAAU,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,CACnF,KAAK,GAAG,MAAM,CAClB;;AAEH,QAAM,KAAK,GAAG,MAAM,MAAM"}