@gscdump/engine 1.4.0 → 1.4.2

package/dist/adapters/r2-manifest.d.mts

@@ -0,0 +1,82 @@
+import { ManifestStore, TableName } from "../storage.mjs";
+interface R2ObjectMetadata {
+  etag: string;
+}
+interface R2ObjectBody extends R2ObjectMetadata {
+  text: () => Promise<string>;
+}
+interface R2ListResult {
+  objects: Array<{
+    key: string;
+  }>;
+  truncated: boolean;
+  cursor?: string;
+}
+interface R2ConditionalPutOptions {
+  /**
+   * Workers-binding-style precondition. `etagMatches` rejects with `null`
+   *  return on mismatch; `etagDoesNotMatch: '*'` rejects if the key exists.
+   */
+  onlyIf?: {
+    etagMatches?: string;
+    etagDoesNotMatch?: string;
+  };
+}
+/**
+ * Minimal Cloudflare R2 binding shape needed for the manifest CAS loop.
+ * Structurally compatible with Cloudflare's `R2Bucket` Workers API.
+ */
+interface R2ManifestBucketLike {
+  get: (key: string) => Promise<R2ObjectBody | null>;
+  put: (key: string, bytes: string | Uint8Array, options?: R2ConditionalPutOptions) => Promise<R2ObjectMetadata | null>;
+  list: (options?: {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+  }) => Promise<R2ListResult>;
+  /**
+   * Bulk delete. Required by {@link ManifestStore.purgeTenant}. Cloudflare's
+   * `R2Bucket.delete` accepts a single key or a string[] batch; both shapes
+   * work here.
+   */
+  delete: (keys: string | string[]) => Promise<void>;
+}
+/**
+ * CAS lifecycle events emitted by the manifest store. Consumers wire these
+ * into metrics (prom-client, console.table, the contention harness) to
+ * measure rejection rate and latency under real R2 load.
+ */
+type R2ManifestEvent = {
+  kind: 'cas-attempt';
+  siteId: string;
+  table: TableName;
+  attempt: number;
+} | {
+  kind: 'cas-rejected';
+  siteId: string;
+  table: TableName;
+  attempt: number;
+} | {
+  kind: 'cas-committed';
+  siteId: string;
+  table: TableName;
+  attempts: number;
+};
+interface CreateR2ManifestStoreOptions {
+  bucket: R2ManifestBucketLike;
+  /** Tenant scope. All shard keys are prefixed `u_<userId>/manifest/...`. */
+  userId: string;
+  /** Override the snapshot version-id generator. Defaults to `${ts}-${random}`. */
+  newSnapshotId?: () => string;
+  now?: () => number;
+  /** Maximum CAS retries before giving up. Defaults to 8. */
+  maxRetries?: number;
+  /**
+   * Optional telemetry hook. Fired synchronously from the CAS loop on each
+   * attempt, rejection, and successful commit. Must not throw; exceptions
+   * propagate and will fail the mutation.
+   */
+  onEvent?: (event: R2ManifestEvent) => void;
+}
+declare function createR2ManifestStore(opts: CreateR2ManifestStoreOptions): ManifestStore;
+export { CreateR2ManifestStoreOptions, R2ManifestBucketLike, R2ManifestEvent, createR2ManifestStore };

package/dist/adapters/r2-manifest.mjs

@@ -0,0 +1,364 @@
+import { engineErrorToException, engineErrors } from "../errors.mjs";
+import { inferSearchType } from "../layout.mjs";
+import { matchesManifestEntryFilter, matchesSyncStateFilter, matchesWatermarkFilter } from "../manifest-store-utils.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
+const SHARD_RE = /^u_[^/]+\/manifest\/(?<siteId>[^/]+)\/(?<table>[^/]+)\/HEAD$/;
+const CAS_BACKOFF_BASE_MS = 5;
+const CAS_BACKOFF_CAP_MS = 250;
+const SHARD_IO_CONCURRENCY = 8;
+const R2_DELETE_BATCH_SIZE = 1e3;
+async function casBackoff(attempt) {
+	const ceil = Math.min(CAS_BACKOFF_CAP_MS, CAS_BACKOFF_BASE_MS * 2 ** attempt);
+	await new Promise((resolve) => setTimeout(resolve, Math.random() * ceil));
+}
+async function mapWithConcurrency(items, concurrency, fn) {
+	if (items.length === 0) return [];
+	const workerCount = Math.max(1, Math.min(items.length, Math.floor(concurrency)));
+	const results = Array.from({ length: items.length }, () => void 0);
+	let nextIndex = 0;
+	async function worker() {
+		while (true) {
+			const index = nextIndex++;
+			if (index >= items.length) return;
+			results[index] = await fn(items[index], index);
+		}
+	}
+	await Promise.all(Array.from({ length: workerCount }, worker));
+	return results;
+}
+function defaultSnapshotId() {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function shardPrefix(userId, siteId, table) {
+	return `u_${userId}/manifest/${siteId}/${table}/`;
+}
+function headKey(userId, siteId, table) {
+	return `${shardPrefix(userId, siteId, table)}HEAD`;
+}
+function snapshotKey(userId, siteId, table, snapshotId) {
+	return `${shardPrefix(userId, siteId, table)}v${snapshotId}.json`;
+}
+function emptySnapshot() {
+	return {
+		version: 1,
+		entries: [],
+		watermarks: [],
+		syncStates: []
+	};
+}
+function shardScopesFromEntries(entries) {
+	const out = /* @__PURE__ */ new Set();
+	for (const e of entries) {
+		if (e.siteId === void 0) throw new Error("R2 manifest store requires entries to carry siteId; cross-site entries are unshardable");
+		out.add(`${e.siteId}\0${e.table}`);
+	}
+	return out;
+}
+function createR2ManifestStore(opts) {
+	const { bucket, userId } = opts;
+	const newSnapshotId = opts.newSnapshotId ?? defaultSnapshotId;
+	const now = opts.now ?? (() => Date.now());
+	const maxRetries = opts.maxRetries ?? 16;
+	const onEvent = opts.onEvent;
+	async function readShard(siteId, table) {
+		const head = await bucket.get(headKey(userId, siteId, table));
+		if (!head) return {
+			snapshot: emptySnapshot(),
+			headEtag: void 0
+		};
+		const snapshotId = (await head.text()).trim();
+		if (!snapshotId) return {
+			snapshot: emptySnapshot(),
+			headEtag: head.etag
+		};
+		const snap = await bucket.get(snapshotKey(userId, siteId, table, snapshotId));
+		if (!snap) return {
+			snapshot: emptySnapshot(),
+			headEtag: head.etag
+		};
+		const parsed = JSON.parse(await snap.text());
+		if (parsed.version !== 1) throw new Error(`unsupported manifest snapshot version: ${parsed.version}`);
+		return {
+			snapshot: parsed,
+			headEtag: head.etag
+		};
+	}
+	async function writeShardResult(siteId, table, snapshot, headEtag, attempt) {
+		const id = newSnapshotId();
+		const snapKey = snapshotKey(userId, siteId, table, id);
+		await bucket.put(snapKey, JSON.stringify(snapshot));
+		const conditional = headEtag ? { onlyIf: { etagMatches: headEtag } } : { onlyIf: { etagDoesNotMatch: "*" } };
+		return await bucket.put(headKey(userId, siteId, table), id, conditional) !== null ? ok(void 0) : err(engineErrors.manifestCasRoundLost(siteId, table, attempt));
+	}
+	async function mutateShardResult(siteId, table, mutate) {
+		let attempt = 0;
+		while (attempt < maxRetries) {
+			onEvent?.({
+				kind: "cas-attempt",
+				siteId,
+				table,
+				attempt
+			});
+			const { snapshot, headEtag } = await readShard(siteId, table);
+			await mutate(snapshot);
+			const round = await writeShardResult(siteId, table, snapshot, headEtag, attempt);
+			if (round.ok) {
+				onEvent?.({
+					kind: "cas-committed",
+					siteId,
+					table,
+					attempts: attempt + 1
+				});
+				return round;
+			}
+			onEvent?.({
+				kind: "cas-rejected",
+				siteId,
+				table,
+				attempt
+			});
+			attempt++;
+			if (attempt < maxRetries) await casBackoff(attempt);
+		}
+		return err(engineErrors.manifestCasExhausted(siteId, table, maxRetries));
+	}
+	async function mutateShard(siteId, table, mutate) {
+		return unwrapResult(await mutateShardResult(siteId, table, mutate), engineErrorToException);
+	}
+	async function listShards(siteId) {
+		const shards = [];
+		let cursor;
+		const prefix = siteId === void 0 ? `u_${userId}/manifest/` : `u_${userId}/manifest/${siteId}/`;
+		do {
+			const res = await bucket.list({
+				prefix,
+				cursor,
+				limit: 1e3
+			});
+			for (const obj of res.objects) {
+				const m = SHARD_RE.exec(obj.key);
+				if (m?.groups) shards.push({
+					siteId: m.groups.siteId,
+					table: m.groups.table
+				});
+			}
+			cursor = res.truncated ? res.cursor : void 0;
+		} while (cursor);
+		return shards;
+	}
+	async function shardsForFilter(filter) {
+		if (filter.siteId !== void 0 && filter.table !== void 0) return [{
+			siteId: filter.siteId,
+			table: filter.table
+		}];
+		return (await listShards(filter.siteId)).filter((s) => (filter.siteId === void 0 || s.siteId === filter.siteId) && (filter.table === void 0 || s.table === filter.table));
+	}
+	function assertScopedUser(got, op) {
+		if (got !== userId) throw new Error(`${op}: R2 manifest store is scoped to userId=${userId}, got ${got}`);
+	}
+	async function readEntriesAcrossShards(filter, includeRetired) {
+		assertScopedUser(filter.userId, includeRetired ? "listAll" : "listLive");
+		return (await mapWithConcurrency(await shardsForFilter(filter), SHARD_IO_CONCURRENCY, async ({ siteId, table }) => {
+			const { snapshot } = await readShard(siteId, table);
+			const entries = [];
+			for (const entry of snapshot.entries) {
+				if (!includeRetired && entry.retiredAt !== void 0) continue;
+				if (matchesManifestEntryFilter(entry, filter, { ignoreUserId: true })) entries.push(entry);
+			}
+			return entries;
+		})).flat();
+	}
+	function groupBySiteTable(entries) {
+		const out = /* @__PURE__ */ new Map();
+		for (const e of entries) {
+			const key = `${e.siteId}\0${e.table}`;
+			if (!out.has(key)) out.set(key, []);
+			out.get(key).push(e);
+		}
+		return out;
+	}
+	async function registerVersionsImpl(newEntries, superseding) {
+		if (newEntries.length === 0 && (!superseding || superseding.length === 0)) return;
+		const supersededAt = newEntries[0]?.createdAt ?? now();
+		const byShard = /* @__PURE__ */ new Map();
+		function bucket(entry, kind) {
+			assertScopedUser(entry.userId, "registerVersions");
+			if (entry.siteId === void 0) throw new Error("R2 manifest store requires entries to carry siteId");
+			const key = `${entry.siteId}\0${entry.table}`;
+			let bag = byShard.get(key);
+			if (!bag) {
+				bag = {
+					newEntries: [],
+					superseding: []
+				};
+				byShard.set(key, bag);
+			}
+			if (kind === "new") bag.newEntries.push(entry);
+			else bag.superseding.push(entry);
+		}
+		for (const e of newEntries) bucket(e, "new");
+		if (superseding) for (const e of superseding) bucket(e, "super");
+		await mapWithConcurrency([...byShard], SHARD_IO_CONCURRENCY, async ([shardKey, { newEntries: news, superseding: supers }]) => {
+			const [siteId, table] = shardKey.split("\0");
+			await mutateShard(siteId, table, (snap) => {
+				const byObjectKey = new Map(snap.entries.map((e) => [e.objectKey, e]));
+				for (const s of supers) {
+					const existing = byObjectKey.get(s.objectKey);
+					if (existing && existing.retiredAt === void 0) byObjectKey.set(s.objectKey, {
+						...existing,
+						retiredAt: supersededAt
+					});
+				}
+				for (const n of news) byObjectKey.set(n.objectKey, n);
+				snap.entries = Array.from(byObjectKey.values());
+			});
+		});
+	}
+	return {
+		async listLive(filter) {
+			return readEntriesAcrossShards(filter, false);
+		},
+		async listAll(filter) {
+			return readEntriesAcrossShards(filter, true);
+		},
+		async registerVersion(entry, superseding) {
+			return registerVersionsImpl([entry], superseding);
+		},
+		async registerVersions(entries, superseding) {
+			shardScopesFromEntries(entries);
+			return registerVersionsImpl(entries, superseding);
+		},
+		async listRetired(olderThan) {
+			return (await mapWithConcurrency(await listShards(), SHARD_IO_CONCURRENCY, async ({ siteId, table }) => {
+				const { snapshot } = await readShard(siteId, table);
+				const retired = [];
+				for (const e of snapshot.entries) if (e.retiredAt !== void 0 && e.retiredAt <= olderThan) retired.push(e);
+				return retired;
+			})).flat();
+		},
+		async delete(toDelete) {
+			await mapWithConcurrency([...groupBySiteTable(toDelete)], SHARD_IO_CONCURRENCY, async ([shardKey, entries]) => {
+				const [siteId, table] = shardKey.split("\0");
+				await mutateShard(siteId, table, (snap) => {
+					const drop = new Set(entries.map((e) => e.objectKey));
+					snap.entries = snap.entries.filter((e) => !drop.has(e.objectKey));
+				});
+			});
+		},
+		async getWatermarks(filter) {
+			assertScopedUser(filter.userId, "getWatermarks");
+			return (await mapWithConcurrency(await shardsForFilter(filter), SHARD_IO_CONCURRENCY, async ({ siteId, table }) => {
+				const { snapshot } = await readShard(siteId, table);
+				const watermarks = [];
+				for (const w of snapshot.watermarks) if (matchesWatermarkFilter(w, filter, { ignoreUserId: true })) watermarks.push(w);
+				return watermarks;
+			})).flat();
+		},
+		async bumpWatermark(scope, date, at) {
+			assertScopedUser(scope.userId, "bumpWatermark");
+			if (scope.siteId === void 0) throw new Error("R2 manifest store requires watermarks to carry siteId");
+			const ts = at ?? now();
+			const scopeSearchType = inferSearchType(scope);
+			await mutateShard(scope.siteId, scope.table, (snap) => {
+				const idx = snap.watermarks.findIndex((w) => w.userId === userId && w.siteId === scope.siteId && w.table === scope.table && inferSearchType(w) === scopeSearchType);
+				if (idx === -1) {
+					snap.watermarks.push({
+						userId,
+						siteId: scope.siteId,
+						table: scope.table,
+						...scope.searchType !== void 0 ? { searchType: scope.searchType } : {},
+						newestDateSynced: date,
+						oldestDateSynced: date,
+						lastSyncAt: ts
+					});
+					return;
+				}
+				const w = snap.watermarks[idx];
+				const newest = date > w.newestDateSynced ? date : w.newestDateSynced;
+				const oldest = date < w.oldestDateSynced ? date : w.oldestDateSynced;
+				const lastSyncAt = ts > w.lastSyncAt ? ts : w.lastSyncAt;
+				snap.watermarks[idx] = {
+					...w,
+					newestDateSynced: newest,
+					oldestDateSynced: oldest,
+					lastSyncAt
+				};
+			});
+		},
+		async getSyncStates(filter) {
+			assertScopedUser(filter.userId, "getSyncStates");
+			return (await mapWithConcurrency(await shardsForFilter(filter), SHARD_IO_CONCURRENCY, async ({ siteId, table }) => {
+				const { snapshot } = await readShard(siteId, table);
+				const states = [];
+				for (const s of snapshot.syncStates) if (matchesSyncStateFilter(s, filter, { ignoreUserId: true })) states.push(s);
+				return states;
+			})).flat();
+		},
+		async setSyncState(scope, state, detail) {
+			assertScopedUser(scope.userId, "setSyncState");
+			if (scope.siteId === void 0) throw new Error("R2 manifest store requires sync states to carry siteId");
+			const at = detail?.at ?? now();
+			const scopeSearchType = inferSearchType(scope);
+			await mutateShard(scope.siteId, scope.table, (snap) => {
+				const idx = snap.syncStates.findIndex((s) => s.userId === userId && s.siteId === scope.siteId && s.table === scope.table && s.date === scope.date && inferSearchType(s) === scopeSearchType);
+				if (idx === -1) {
+					snap.syncStates.push({
+						userId,
+						siteId: scope.siteId,
+						table: scope.table,
+						date: scope.date,
+						state,
+						updatedAt: at,
+						attempts: 1,
+						error: detail?.error,
+						...scope.searchType !== void 0 ? { searchType: scope.searchType } : {}
+					});
+					return;
+				}
+				const prev = snap.syncStates[idx];
+				const attempts = state === "inflight" && prev.state !== "inflight" ? prev.attempts + 1 : prev.attempts;
+				const error = state === "done" ? void 0 : detail?.error ?? prev.error;
+				snap.syncStates[idx] = {
+					...prev,
+					state,
+					updatedAt: at,
+					attempts,
+					error
+				};
+			});
+		},
+		async withLock(_scope, fn) {
+			return fn();
+		},
+		async purgeTenant(filter) {
+			if (filter.userId !== userId) throw new Error(`purgeTenant: store is scoped to userId=${userId}, got ${filter.userId}`);
+			const purged = await mapWithConcurrency(await shardsForFilter({ siteId: filter.siteId }), SHARD_IO_CONCURRENCY, async ({ siteId, table }) => {
+				const { snapshot } = await readShard(siteId, table);
+				const prefix = shardPrefix(userId, siteId, table);
+				const keys = [];
+				let cursor;
+				do {
+					const res = await bucket.list({
+						prefix,
+						cursor,
+						limit: 1e3
+					});
+					for (const obj of res.objects) keys.push(obj.key);
+					cursor = res.truncated ? res.cursor : void 0;
+				} while (cursor);
+				for (let offset = 0; offset < keys.length; offset += R2_DELETE_BATCH_SIZE) await bucket.delete(keys.slice(offset, offset + R2_DELETE_BATCH_SIZE));
+				return {
+					entriesRemoved: snapshot.entries.length,
+					watermarksRemoved: snapshot.watermarks.length,
+					syncStatesRemoved: snapshot.syncStates.length
+				};
+			});
+			return {
+				entriesRemoved: purged.reduce((sum, result) => sum + result.entriesRemoved, 0),
+				watermarksRemoved: purged.reduce((sum, result) => sum + result.watermarksRemoved, 0),
+				syncStatesRemoved: purged.reduce((sum, result) => sum + result.syncStatesRemoved, 0)
+			};
+		}
+	};
+}
+export { createR2ManifestStore };

package/dist/adapters/r2.d.mts

@@ -1,4 +1,4 @@
-import { DataSource } from "../_chunks/storage.mjs";
+import { DataSource } from "../storage.mjs";
 interface R2GetOptions {
   range?: {
     offset: number;

package/dist/adapters/read-optional.mjs

@@ -0,0 +1,15 @@
+function isMissingKeyError(e) {
+	if (typeof e !== "object" || e === null) return false;
+	if (e.code === "ENOENT") return true;
+	if (e.name === "NotFoundError") return true;
+	const message = e.message;
+	if (typeof message !== "string") return false;
+	return /\bnot found\b|\bENOENT\b|\bmissing key\b/i.test(message);
+}
+async function readOptional(ds, key, signal) {
+	return await ds.read(key, void 0, signal).catch((e) => {
+		if (isMissingKeyError(e)) return void 0;
+		throw e;
+	});
+}
+export { isMissingKeyError, readOptional };

package/dist/adapters/snapshot-attach.d.mts

@@ -0,0 +1,38 @@
+import { SnapshotIndex } from "../snapshot.mjs";
+/**
+ * Runs arbitrary SQL and returns rows as plain objects. Caller supplies
+ * this so the function works with AsyncDuckDB (browser DuckDB-WASM) or
+ * @duckdb/node-api (Node) without coupling to either.
+ */
+type SnapshotQueryRunner = (sql: string) => Promise<Array<Record<string, unknown>>>;
+interface AttachSnapshotOptions {
+  /** Index produced by the builder. */
+  index: SnapshotIndex;
+  /**
+   * Map from filename (`cold-YYYY-MM.duckdb`, `hot.duckdb`) to an HTTPS
+   * URL (typically a pre-signed R2 URL). Must contain an entry for every
+   * cold month in `index.cold` and — if `index.hot` — for `hot.duckdb`.
+   */
+  attachUrls: Record<string, string>;
+  /** Schema the unified views land under. Default `main`. */
+  schema?: string;
+  /**
+   * DuckDB httpfs can error with "Server sent back more data than expected"
+   * against some proxies; `force_download=true` sidesteps it. Default true.
+   */
+  forceDownload?: boolean;
+}
+interface AttachSnapshotResult {
+  schema: string;
+  /** Aliases we ATTACH'd — e.g. ['cold_2024_09', 'cold_2024_10', 'hot']. */
+  aliases: string[];
+  /** Table names with a UNION view created under `schema`. */
+  tables: string[];
+}
+/**
+ * Turns a filename like `cold-2024-09.duckdb` into a valid SQL identifier
+ * `cold_2024_09`. `hot.duckdb` → `hot`.
+ */
+declare function snapshotAlias(fileName: string): string;
+declare function attachSnapshotIndex(runner: SnapshotQueryRunner, opts: AttachSnapshotOptions): Promise<AttachSnapshotResult>;
+export { AttachSnapshotOptions, AttachSnapshotResult, SnapshotQueryRunner, attachSnapshotIndex, snapshotAlias };

package/dist/adapters/snapshot-attach.mjs

@@ -0,0 +1,85 @@
+import { engineErrors } from "../errors.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
+const YEAR_MONTH_RE = /^\d{4}-\d{2}$/;
+const SCHEMA_IDENT_RE = /^[A-Z_][\w$]*$/i;
+const COLD_FILENAME_RE = /^cold-(\d{4}-\d{2})\.duckdb$/;
+function snapshotAlias(fileName) {
+	if (fileName === "hot.duckdb") return "hot";
+	const m = fileName.match(COLD_FILENAME_RE);
+	if (!m?.[1]) throw new TypeError(`snapshotAlias: unrecognised filename ${JSON.stringify(fileName)}`);
+	return `cold_${m[1].replace("-", "_")}`;
+}
+const SNAPSHOT_TYPE_ERROR_KINDS = /* @__PURE__ */ new Set([
+	"invalid-snapshot-filename",
+	"unsupported-snapshot-index-version",
+	"invalid-schema-identifier",
+	"invalid-year-month"
+]);
+function snapshotAttachErrorToException(error) {
+	const exception = SNAPSHOT_TYPE_ERROR_KINDS.has(error.kind) ? new TypeError(error.message) : new Error(error.message);
+	exception.engineError = error;
+	return exception;
+}
+async function attachSnapshotIndexResult(runner, opts) {
+	const { index, attachUrls } = opts;
+	const schema = opts.schema ?? "main";
+	const forceDownload = opts.forceDownload !== false;
+	if (index?.version !== 1) return err(engineErrors.unsupportedSnapshotIndexVersion(index?.version));
+	if (!SCHEMA_IDENT_RE.test(schema)) return err(engineErrors.invalidSchemaIdentifier(schema));
+	for (const ym of index.cold) if (!YEAR_MONTH_RE.test(ym)) return err(engineErrors.invalidYearMonth(ym));
+	await runner("LOAD httpfs").catch(() => void 0);
+	if (forceDownload) await runner("SET force_download=true");
+	const plan = [];
+	for (const ym of index.cold) {
+		const fileName = `cold-${ym}.duckdb`;
+		const url = attachUrls[fileName];
+		if (!url) return err(engineErrors.missingAttachUrl(fileName));
+		plan.push({
+			fileName,
+			alias: snapshotAlias(fileName),
+			url
+		});
+	}
+	if (index.hot) {
+		const fileName = "hot.duckdb";
+		const url = attachUrls[fileName];
+		if (!url) return err(engineErrors.missingAttachUrl(fileName));
+		plan.push({
+			fileName,
+			alias: snapshotAlias(fileName),
+			url
+		});
+	}
+	const aliases = [];
+	for (const { alias, url } of plan) {
+		await runner(`ATTACH '${url.replace(/'/g, "''")}' AS ${alias} (READ_ONLY)`);
+		aliases.push(alias);
+	}
+	const aliasSet = new Set(aliases);
+	const tableRows = await runner("SELECT database_name, table_name FROM duckdb_tables()");
+	const present = /* @__PURE__ */ new Map();
+	for (const row of tableRows) {
+		const db = String(row.database_name ?? "");
+		const table = String(row.table_name ?? "");
+		if (!aliasSet.has(db) || !table) continue;
+		const list = present.get(table);
+		if (list) list.push(db);
+		else present.set(table, [db]);
+	}
+	const tables = [];
+	for (const [table, dbs] of present) {
+		if (!SCHEMA_IDENT_RE.test(table)) continue;
+		const dbsSet = new Set(dbs);
+		await runner(`CREATE OR REPLACE VIEW ${schema}.${table} AS ${aliases.filter((a) => dbsSet.has(a)).map((db) => `SELECT * FROM ${db}.${table}`).join(" UNION ALL BY NAME ")}`);
+		tables.push(table);
+	}
+	return ok({
+		schema,
+		aliases,
+		tables
+	});
+}
+async function attachSnapshotIndex(runner, opts) {
+	return unwrapResult(await attachSnapshotIndexResult(runner, opts), snapshotAttachErrorToException);
+}
+export { attachSnapshotIndex, snapshotAlias };

package/dist/analysis-types.d.mts

@@ -1,2 +1,57 @@
-import { AnalysisParams, AnalysisResult, AnalysisTool, num } from "./_chunks/analysis-types.mjs";
+import { BuilderState, SearchType } from "gscdump/query";
+type AnalysisTool = 'striking-distance' | 'opportunity' | 'movers' | 'decay' | 'zero-click' | 'brand' | 'cannibalization' | 'clustering' | 'concentration' | 'seasonality' | 'trends' | 'ctr-anomaly' | 'position-volatility' | 'long-tail' | 'intent-atlas' | 'query-migration' | 'bayesian-ctr' | 'stl-decompose' | 'change-point' | 'bipartite-pagerank' | 'survival' | 'position-distribution' | 'ctr-curve' | 'dark-traffic' | 'content-velocity' | 'keyword-breadth' | 'device-gap' | 'data-query' | 'data-detail';
+interface AnalysisParams {
+  type: AnalysisTool;
+  startDate?: string;
+  endDate?: string;
+  prevStartDate?: string;
+  prevEndDate?: string;
+  brandTerms?: string[];
+  limit?: number;
+  offset?: number;
+  /**
+   * movers: select a single direction and paginate within it. When set, the
+   * analyzer filters to that direction, reports `meta.total` as the full
+   * pre-pagination count for the direction, and applies `limit`/`offset`. When
+   * unset, both directions are returned uncapped (the top-N callers slice
+   * themselves).
+   */
+  direction?: 'rising' | 'declining';
+  /** Sort column. Each analyzer enforces its own whitelist. */
+  sortBy?: string;
+  /** Sort direction. Default per-analyzer. */
+  sortDir?: 'asc' | 'desc';
+  minPosition?: number;
+  maxPosition?: number;
+  minImpressions?: number;
+  maxCtr?: number;
+  minPages?: number;
+  maxPositionSpread?: number;
+  minClusterSize?: number;
+  clusterBy?: 'prefix' | 'intent' | 'both';
+  dimension?: 'pages' | 'keywords';
+  topN?: number;
+  metric?: 'clicks' | 'impressions';
+  changeThreshold?: number;
+  minPreviousClicks?: number;
+  threshold?: number;
+  weeks?: number;
+  minWeeksWithData?: number;
+  /** content-velocity lookback window in days (max 365, default 90). */
+  days?: number;
+  /** data-query / data-detail primary BuilderState. */
+  q?: BuilderState;
+  /** data-query / data-detail optional comparison-period BuilderState. */
+  qc?: BuilderState;
+  /** data-query comparison filter applied to joined current/previous rows. */
+  comparisonFilter?: 'new' | 'lost' | 'improving' | 'declining';
+  /** GSC slice the analysis is scoped to. Undefined = analyzer runs cross-type (today's behaviour for web-only sites). */
+  searchType?: SearchType;
+}
+interface AnalysisResult {
+  results: Record<string, unknown>[];
+  meta: Record<string, unknown>;
+}
+/** Coerce arbitrary value (number, bigint, string, null) to number, defaulting to 0. */
+declare function num(v: unknown): number;
 export { AnalysisParams, AnalysisResult, AnalysisTool, num };