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

package/dist/ctime-backfill.cjs

@@ -0,0 +1,272 @@
+const require_timestamp = require('./timestamp.cjs');
+const require_tree_index = require('./tree-index.cjs');
+const require_d1_tree_index = require('./d1-tree-index.cjs');
+
+//#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 = require_timestamp.resolveParentDirStamp(require_tree_index.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 = require_d1_tree_index.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
+exports.backfillCtime = backfillCtime;
+exports.distinctScopesWithMetadataD1 = distinctScopesWithMetadataD1;
+exports.distinctScopesWithMetadataD1Http = distinctScopesWithMetadataD1Http;
+exports.distinctScopesWithMetadataSqlite = distinctScopesWithMetadataSqlite;
+exports.makeD1CtimeBackfillBackend = makeD1CtimeBackfillBackend;
+exports.makeD1HttpCtimeBackfillBackend = makeD1HttpCtimeBackfillBackend;
+exports.makeSqliteCtimeBackfillBackend = makeSqliteCtimeBackfillBackend;

package/dist/ctime-backfill.d.cts

@@ -0,0 +1,169 @@
+//#region src/ctime-backfill.d.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).
+ */
+/** A FILE row with non-null metadata — a backfill candidate. */
+interface CtimeBackfillCandidate {
+  path: string;
+  /** Raw `entries.metadata` JSON blob (host-parsed here, never in SQL). */
+  metadata: string | null;
+}
+/** Backend-specific SQL for the sweep (D1 vs Node SQLite). One scope each. */
+interface CtimeBackfillBackend {
+  /**
+   * Select up to `limit` FILE rows with `metadata IS NOT NULL` and
+   * `path > cursor`, ordered `path ASC` (the keyset cursor). Empty ⇒ done.
+   */
+  selectCandidates(cursor: string, limit: number): Promise<CtimeBackfillCandidate[]>;
+  /**
+   * R1: set the FILE row's `ctime` (NEVER its mtime). The UPDATE is guarded
+   * `AND ctime != ?` so an already-migrated row is a 0-row no-op (re-runs burn
+   * no D1 write quota). Returns the number of rows actually changed (0 or 1).
+   */
+  updateFileCtime(path: string, ctime: number): Promise<number>;
+  /**
+   * R2: set the DIRECT-parent DIR row's `ctime` + `mtime`, guarded so an
+   * already-current dir is a no-op. Returns rows actually changed (0 or 1).
+   */
+  updateDirStamp(dirPath: string, ctime: number, mtime: number): Promise<number>;
+}
+interface CtimeBackfillOptions {
+  /** Rows per page (bounds the D1 write budget per invocation). Default 200. */
+  pageSize?: number;
+  /** Cap pages this invocation (cross-invocation paging). Default unbounded. */
+  maxPages?: number;
+  /**
+   * Max concurrent UPDATE round-trips WITHIN a page. Default 1 (serial — the
+   * deterministic reference behavior). >1 is a throughput win for the high-
+   * latency D1-HTTP channel (each row = 2 sequential UPDATEs otherwise).
+   *
+   * ⚠️ Concurrency > 1 makes the direct-parent DIR stamp NON-deterministic for
+   * a degenerate collection where MULTIPLE createdAt-bearing rows share one
+   * direct parent (the `ORDER BY path` last-writer-wins guarantee only holds
+   * serially). SAFE for dir-per-record collections (Aside: exactly one
+   * createdAt child — `item.json` — per `{uuid}/`, no shared parent). Use 1
+   * for strict determinism on degenerate shapes. Node SQLite (single
+   * connection) gains nothing — keep it 1 there.
+   */
+  concurrency?: number;
+  /**
+   * Preview only — scan + count candidates, run NO UPDATE. `stats.stamped`
+   * then reports rows that WOULD be stamped (an upper bound; the real run's
+   * `AND ctime != ?` guard skips already-current rows as 0-write). `scanned`
+   * and `skippedNoCreatedAt` are exact in both modes.
+   */
+  dryRun?: boolean;
+  log?: (msg: string) => void;
+}
+interface CtimeBackfillStats {
+  /** FILE rows examined (metadata IS NOT NULL). */
+  scanned: number;
+  /** Rows where a ctime/mtime value ACTUALLY changed (file and/or dir). */
+  stamped: number;
+  /**
+   * Rows that had a valid createdAt but were already at the target value — a
+   * 0-write no-op. On a clean second run this equals `scanned` and `stamped`
+   * is 0 (the spec's "第二趟 0 改动" idempotency contract).
+   */
+  alreadyCurrent: number;
+  /** Rows with metadata but no usable createdAt — left at insert time. */
+  skippedNoCreatedAt: number;
+  pages: number;
+  lastCursor: string;
+  /** True when a page came back empty (the sweep reached the end). */
+  done: boolean;
+}
+/**
+ * Page over createdAt-bearing FILE rows in one scope and rewrite ctime (R1) +
+ * the direct-parent DIR stamp (R2). Returns stats; resumable across calls.
+ */
+declare function backfillCtime(backend: CtimeBackfillBackend, opts?: CtimeBackfillOptions): Promise<CtimeBackfillStats>;
+/** Minimal D1 shape used by the sweep (subset of `D1Database`). */
+interface D1Like {
+  prepare(sql: string): {
+    bind(...args: (string | number)[]): {
+      all(): Promise<{
+        results?: unknown[];
+      }>;
+      run(): Promise<{
+        meta?: {
+          changes?: number;
+        };
+      }>;
+    };
+  };
+}
+/** D1 (Cloudflare) backend adapter for one scope. */
+declare function makeD1CtimeBackfillBackend(db: D1Like, scope: string): CtimeBackfillBackend;
+/**
+ * Minimal libsql client shape (Node `_metadata.db`). `args` narrowed to the
+ * exact bound types so a real `@libsql/client` `Client` is assignable.
+ */
+interface LibsqlLike {
+  execute(stmt: {
+    sql: string;
+    args: (string | number)[];
+  }): Promise<{
+    rows: Array<Record<string, unknown>>;
+    rowsAffected?: number;
+  }>;
+}
+/** Node SQLite (libsql) backend adapter for one scope. */
+declare function makeSqliteCtimeBackfillBackend(db: LibsqlLike, scope: string): CtimeBackfillBackend;
+/** Enumerate scopes that have any createdAt-bearing file row (D1). */
+declare function distinctScopesWithMetadataD1(db: D1Like): Promise<string[]>;
+/** Enumerate scopes that have any createdAt-bearing file row (Node SQLite). */
+declare function distinctScopesWithMetadataSqlite(db: LibsqlLike): Promise<string[]>;
+/**
+ * Config for the offline CF D1 HTTP backend: a local Node process holding a
+ * Cloudflare API token with D1-edit runs the SAME paged sweep SQL the worker
+ * would. No R2 involved — ctime backfill is pure index UPDATEs. `fetchImpl` /
+ * `sleep` are injectable for tests.
+ */
+interface CtimeBackfillD1HttpConfig {
+  accountId: string;
+  databaseId: string;
+  apiToken: string;
+  scope: string;
+  fetchImpl?: typeof fetch;
+  /** Bounded retries for TRANSIENT failures (5xx / 429 / network). Default 4. */
+  maxRetries?: number;
+  sleep?: (ms: number) => Promise<void>;
+}
+/** CF D1 HTTP-API backend adapter for one scope (offline admin channel). */
+declare function makeD1HttpCtimeBackfillBackend(cfg: CtimeBackfillD1HttpConfig): CtimeBackfillBackend;
+/** List distinct createdAt-bearing scopes on a CF D1 over HTTP (bulk sweep). */
+declare function distinctScopesWithMetadataD1Http(cfg: Omit<CtimeBackfillD1HttpConfig, "scope">): Promise<string[]>;
+//#endregion
+export { CtimeBackfillBackend, CtimeBackfillCandidate, CtimeBackfillD1HttpConfig, CtimeBackfillOptions, CtimeBackfillStats, D1Like, LibsqlLike, backfillCtime, distinctScopesWithMetadataD1, distinctScopesWithMetadataD1Http, distinctScopesWithMetadataSqlite, makeD1CtimeBackfillBackend, makeD1HttpCtimeBackfillBackend, makeSqliteCtimeBackfillBackend };
+//# sourceMappingURL=ctime-backfill.d.cts.map

package/dist/ctime-backfill.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctime-backfill.d.cts","names":[],"sources":["../src/ctime-backfill.ts"],"mappings":";;AAuCA;;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;AAmBA;;;UA1BiB,sBAAA;EACf,IAAA;EA6BA;EA3BA,QAAA;AAAA;;UAIe,oBAAA;EA6CG;;AAGpB;;EA3CE,gBAAA,CAAiB,MAAA,UAAgB,KAAA,WAAgB,OAAA,CAAQ,sBAAA;EA2CxB;;;;;EArCjC,eAAA,CAAgB,IAAA,UAAc,KAAA,WAAgB,OAAA;EAmD9C;;;;EA9CA,cAAA,CAAe,OAAA,UAAiB,KAAA,UAAe,KAAA,WAAgB,OAAA;AAAA;AAAA,UAGhD,oBAAA;EAyEN;EAvET,QAAA;EAyES;EAvET,QAAA;EAuEQ;;;;;;;;;;AAiFV;;;EA1IE,WAAA;EA2IA;;;;;;EApIA,MAAA;EACA,GAAA,IAAO,GAAA;AAAA;AAAA,UAGQ,kBAAA;EAmIe;EAjI9B,OAAA;EAiIqC;EA/HrC,OAAA;EAqIwC;;;;;EA/HxC,cAAA;EA+HqE;EA7HrE,kBAAA;EACA,KAAA;EACA,UAAA;EAsJyB;EApJzB,IAAA;AAAA;;;;;iBA2BoB,aAAA,CACpB,OAAA,EAAS,oBAAA,EACT,IAAA,GAAM,oBAAA,GACL,OAAA,CAAQ,kBAAA;;UAiFM,MAAA;EACf,OAAA,CAAQ,GAAA;IACN,IAAA,IAAQ,IAAA;MACN,GAAA,IAAO,OAAA;QAAU,OAAA;MAAA;MACjB,GAAA,IAAO,OAAA;QAAU,IAAA;UAAS,OAAA;QAAA;MAAA;IAAA;EAAA;AAAA;;iBAMhB,0BAAA,CAA2B,EAAA,EAAI,MAAA,EAAQ,KAAA,WAAgB,oBAAA;;;;AAiEvE;UAtCiB,UAAA;EACf,OAAA,CAAQ,IAAA;IAAQ,GAAA;IAAa,IAAA;EAAA,IAA8B,OAAA;IACzD,IAAA,EAAM,KAAA,CAAM,MAAA;IACZ,YAAA;EAAA;AAAA;;iBAKY,8BAAA,CACd,EAAA,EAAI,UAAA,EACJ,KAAA,WACC,oBAAA;;iBA2BmB,4BAAA,CAA6B,EAAA,EAAI,MAAA,GAAS,OAAA;;iBAM1C,gCAAA,CAAiC,EAAA,EAAI,UAAA,GAAa,OAAA;;;AAYxE;;;;UAAiB,yBAAA;EACf,SAAA;EACA,UAAA;EACA,QAAA;EACA,KAAA;EACA,SAAA,UAAmB,KAAA;EAEnB;EAAA,UAAA;EACA,KAAA,IAAS,EAAA,aAAe,OAAA;AAAA;;iBAkDV,8BAAA,CACd,GAAA,EAAK,yBAAA,GACJ,oBAAA;AAFH;AAAA,iBA8BsB,gCAAA,CACpB,GAAA,EAAK,IAAA,CAAK,yBAAA,aACT,OAAA"}

package/dist/ctime-backfill.d.mts

@@ -0,0 +1,169 @@
+//#region src/ctime-backfill.d.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).
+ */
+/** A FILE row with non-null metadata — a backfill candidate. */
+interface CtimeBackfillCandidate {
+  path: string;
+  /** Raw `entries.metadata` JSON blob (host-parsed here, never in SQL). */
+  metadata: string | null;
+}
+/** Backend-specific SQL for the sweep (D1 vs Node SQLite). One scope each. */
+interface CtimeBackfillBackend {
+  /**
+   * Select up to `limit` FILE rows with `metadata IS NOT NULL` and
+   * `path > cursor`, ordered `path ASC` (the keyset cursor). Empty ⇒ done.
+   */
+  selectCandidates(cursor: string, limit: number): Promise<CtimeBackfillCandidate[]>;
+  /**
+   * R1: set the FILE row's `ctime` (NEVER its mtime). The UPDATE is guarded
+   * `AND ctime != ?` so an already-migrated row is a 0-row no-op (re-runs burn
+   * no D1 write quota). Returns the number of rows actually changed (0 or 1).
+   */
+  updateFileCtime(path: string, ctime: number): Promise<number>;
+  /**
+   * R2: set the DIRECT-parent DIR row's `ctime` + `mtime`, guarded so an
+   * already-current dir is a no-op. Returns rows actually changed (0 or 1).
+   */
+  updateDirStamp(dirPath: string, ctime: number, mtime: number): Promise<number>;
+}
+interface CtimeBackfillOptions {
+  /** Rows per page (bounds the D1 write budget per invocation). Default 200. */
+  pageSize?: number;
+  /** Cap pages this invocation (cross-invocation paging). Default unbounded. */
+  maxPages?: number;
+  /**
+   * Max concurrent UPDATE round-trips WITHIN a page. Default 1 (serial — the
+   * deterministic reference behavior). >1 is a throughput win for the high-
+   * latency D1-HTTP channel (each row = 2 sequential UPDATEs otherwise).
+   *
+   * ⚠️ Concurrency > 1 makes the direct-parent DIR stamp NON-deterministic for
+   * a degenerate collection where MULTIPLE createdAt-bearing rows share one
+   * direct parent (the `ORDER BY path` last-writer-wins guarantee only holds
+   * serially). SAFE for dir-per-record collections (Aside: exactly one
+   * createdAt child — `item.json` — per `{uuid}/`, no shared parent). Use 1
+   * for strict determinism on degenerate shapes. Node SQLite (single
+   * connection) gains nothing — keep it 1 there.
+   */
+  concurrency?: number;
+  /**
+   * Preview only — scan + count candidates, run NO UPDATE. `stats.stamped`
+   * then reports rows that WOULD be stamped (an upper bound; the real run's
+   * `AND ctime != ?` guard skips already-current rows as 0-write). `scanned`
+   * and `skippedNoCreatedAt` are exact in both modes.
+   */
+  dryRun?: boolean;
+  log?: (msg: string) => void;
+}
+interface CtimeBackfillStats {
+  /** FILE rows examined (metadata IS NOT NULL). */
+  scanned: number;
+  /** Rows where a ctime/mtime value ACTUALLY changed (file and/or dir). */
+  stamped: number;
+  /**
+   * Rows that had a valid createdAt but were already at the target value — a
+   * 0-write no-op. On a clean second run this equals `scanned` and `stamped`
+   * is 0 (the spec's "第二趟 0 改动" idempotency contract).
+   */
+  alreadyCurrent: number;
+  /** Rows with metadata but no usable createdAt — left at insert time. */
+  skippedNoCreatedAt: number;
+  pages: number;
+  lastCursor: string;
+  /** True when a page came back empty (the sweep reached the end). */
+  done: boolean;
+}
+/**
+ * Page over createdAt-bearing FILE rows in one scope and rewrite ctime (R1) +
+ * the direct-parent DIR stamp (R2). Returns stats; resumable across calls.
+ */
+declare function backfillCtime(backend: CtimeBackfillBackend, opts?: CtimeBackfillOptions): Promise<CtimeBackfillStats>;
+/** Minimal D1 shape used by the sweep (subset of `D1Database`). */
+interface D1Like {
+  prepare(sql: string): {
+    bind(...args: (string | number)[]): {
+      all(): Promise<{
+        results?: unknown[];
+      }>;
+      run(): Promise<{
+        meta?: {
+          changes?: number;
+        };
+      }>;
+    };
+  };
+}
+/** D1 (Cloudflare) backend adapter for one scope. */
+declare function makeD1CtimeBackfillBackend(db: D1Like, scope: string): CtimeBackfillBackend;
+/**
+ * Minimal libsql client shape (Node `_metadata.db`). `args` narrowed to the
+ * exact bound types so a real `@libsql/client` `Client` is assignable.
+ */
+interface LibsqlLike {
+  execute(stmt: {
+    sql: string;
+    args: (string | number)[];
+  }): Promise<{
+    rows: Array<Record<string, unknown>>;
+    rowsAffected?: number;
+  }>;
+}
+/** Node SQLite (libsql) backend adapter for one scope. */
+declare function makeSqliteCtimeBackfillBackend(db: LibsqlLike, scope: string): CtimeBackfillBackend;
+/** Enumerate scopes that have any createdAt-bearing file row (D1). */
+declare function distinctScopesWithMetadataD1(db: D1Like): Promise<string[]>;
+/** Enumerate scopes that have any createdAt-bearing file row (Node SQLite). */
+declare function distinctScopesWithMetadataSqlite(db: LibsqlLike): Promise<string[]>;
+/**
+ * Config for the offline CF D1 HTTP backend: a local Node process holding a
+ * Cloudflare API token with D1-edit runs the SAME paged sweep SQL the worker
+ * would. No R2 involved — ctime backfill is pure index UPDATEs. `fetchImpl` /
+ * `sleep` are injectable for tests.
+ */
+interface CtimeBackfillD1HttpConfig {
+  accountId: string;
+  databaseId: string;
+  apiToken: string;
+  scope: string;
+  fetchImpl?: typeof fetch;
+  /** Bounded retries for TRANSIENT failures (5xx / 429 / network). Default 4. */
+  maxRetries?: number;
+  sleep?: (ms: number) => Promise<void>;
+}
+/** CF D1 HTTP-API backend adapter for one scope (offline admin channel). */
+declare function makeD1HttpCtimeBackfillBackend(cfg: CtimeBackfillD1HttpConfig): CtimeBackfillBackend;
+/** List distinct createdAt-bearing scopes on a CF D1 over HTTP (bulk sweep). */
+declare function distinctScopesWithMetadataD1Http(cfg: Omit<CtimeBackfillD1HttpConfig, "scope">): Promise<string[]>;
+//#endregion
+export { CtimeBackfillBackend, CtimeBackfillCandidate, CtimeBackfillD1HttpConfig, CtimeBackfillOptions, CtimeBackfillStats, D1Like, LibsqlLike, backfillCtime, distinctScopesWithMetadataD1, distinctScopesWithMetadataD1Http, distinctScopesWithMetadataSqlite, makeD1CtimeBackfillBackend, makeD1HttpCtimeBackfillBackend, makeSqliteCtimeBackfillBackend };
+//# sourceMappingURL=ctime-backfill.d.mts.map

package/dist/ctime-backfill.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctime-backfill.d.mts","names":[],"sources":["../src/ctime-backfill.ts"],"mappings":";;AAuCA;;;;;AAOA;;;;;;;;;;;;;;;;;;;;;;;;;AAmBA;;;UA1BiB,sBAAA;EACf,IAAA;EA6BA;EA3BA,QAAA;AAAA;;UAIe,oBAAA;EA6CG;;AAGpB;;EA3CE,gBAAA,CAAiB,MAAA,UAAgB,KAAA,WAAgB,OAAA,CAAQ,sBAAA;EA2CxB;;;;;EArCjC,eAAA,CAAgB,IAAA,UAAc,KAAA,WAAgB,OAAA;EAmD9C;;;;EA9CA,cAAA,CAAe,OAAA,UAAiB,KAAA,UAAe,KAAA,WAAgB,OAAA;AAAA;AAAA,UAGhD,oBAAA;EAyEN;EAvET,QAAA;EAyES;EAvET,QAAA;EAuEQ;;;;;;;;;;AAiFV;;;EA1IE,WAAA;EA2IA;;;;;;EApIA,MAAA;EACA,GAAA,IAAO,GAAA;AAAA;AAAA,UAGQ,kBAAA;EAmIe;EAjI9B,OAAA;EAiIqC;EA/HrC,OAAA;EAqIwC;;;;;EA/HxC,cAAA;EA+HqE;EA7HrE,kBAAA;EACA,KAAA;EACA,UAAA;EAsJyB;EApJzB,IAAA;AAAA;;;;;iBA2BoB,aAAA,CACpB,OAAA,EAAS,oBAAA,EACT,IAAA,GAAM,oBAAA,GACL,OAAA,CAAQ,kBAAA;;UAiFM,MAAA;EACf,OAAA,CAAQ,GAAA;IACN,IAAA,IAAQ,IAAA;MACN,GAAA,IAAO,OAAA;QAAU,OAAA;MAAA;MACjB,GAAA,IAAO,OAAA;QAAU,IAAA;UAAS,OAAA;QAAA;MAAA;IAAA;EAAA;AAAA;;iBAMhB,0BAAA,CAA2B,EAAA,EAAI,MAAA,EAAQ,KAAA,WAAgB,oBAAA;;;;AAiEvE;UAtCiB,UAAA;EACf,OAAA,CAAQ,IAAA;IAAQ,GAAA;IAAa,IAAA;EAAA,IAA8B,OAAA;IACzD,IAAA,EAAM,KAAA,CAAM,MAAA;IACZ,YAAA;EAAA;AAAA;;iBAKY,8BAAA,CACd,EAAA,EAAI,UAAA,EACJ,KAAA,WACC,oBAAA;;iBA2BmB,4BAAA,CAA6B,EAAA,EAAI,MAAA,GAAS,OAAA;;iBAM1C,gCAAA,CAAiC,EAAA,EAAI,UAAA,GAAa,OAAA;;;AAYxE;;;;UAAiB,yBAAA;EACf,SAAA;EACA,UAAA;EACA,QAAA;EACA,KAAA;EACA,SAAA,UAAmB,KAAA;EAEnB;EAAA,UAAA;EACA,KAAA,IAAS,EAAA,aAAe,OAAA;AAAA;;iBAkDV,8BAAA,CACd,GAAA,EAAK,yBAAA,GACJ,oBAAA;AAFH;AAAA,iBA8BsB,gCAAA,CACpB,GAAA,EAAK,IAAA,CAAK,yBAAA,aACT,OAAA"}