@gscdump/engine 1.0.2 → 1.0.3

package/dist/index.mjs

@@ -1,17 +1,8 @@
-import { engineErrorToException, engineErrors, isEngineError } from "./errors.mjs";
+import { engineErrorToException, engineErrors } from "./errors.mjs";
 import { DEFAULT_SEARCH_TYPE, dayPartition, hourPartition, inferLegacyTier, inferSearchType, objectKey } from "./_chunks/layout.mjs";
 import { matchesManifestEntryFilter, matchesSyncStateFilter, matchesWatermarkFilter } from "./_chunks/manifest-store-utils.mjs";
 import { coerceRow, coerceRows } from "./_chunks/coerce.mjs";
-import { SCHEMAS, TABLE_METADATA, allTables, countries, currentSchemaVersion, dates, dimensionToColumn, drizzleSchema, hourly_pages, inferTable, page_queries, pages, queries } from "./_chunks/schema.mjs";
-import { FILES_PLACEHOLDER, enumeratePartitions, resolveParquetSQL, substituteNamedFiles } from "./_chunks/parquet-plan.mjs";
-import { bindLiterals, formatLiteral } from "./sql-bind.mjs";
 import { MAX_DAY_BYTES, createDuckDBCodec, createDuckDBExecutor, createStorageEngine } from "./_chunks/engine.mjs";
-import { assembleDatesRow, createRowAccumulator, toPath, toSumPosition, transformGscRow } from "./ingest.mjs";
-import "./planner.mjs";
-import { createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter } from "./_chunks/resolver.mjs";
-import { rebuildDailyFromHourly } from "./rollups.mjs";
-import { fixedPolicy, inspectionPolicy, sitemapPolicy } from "./schedule.mjs";
-import { ENGINE_QUERY_CAPABILITIES, createSqlQuerySource } from "./_chunks/source.mjs";
 import { err, ok, unwrapResult } from "gscdump/result";
 const SHARD_RE = /^u_[^/]+\/manifest\/(?<siteId>[^/]+)\/(?<table>[^/]+)\/HEAD$/;
 const CAS_BACKOFF_BASE_MS = 5;
@@ -372,127 +363,6 @@ function createR2ManifestStore(opts) {
 		}
 	};
 }
-function scopeOf(ctx, table, date) {
-	return {
-		userId: String(ctx.userId),
-		siteId: ctx.siteId,
-		table,
-		date,
-		...ctx.searchType !== void 0 ? { searchType: ctx.searchType } : {}
-	};
-}
-function createIngestAccumulator(opts) {
-	const { engine, ctx, hooks, ...accOpts } = opts;
-	const acc = createRowAccumulator(accOpts);
-	function reportHookFailure(hook, error) {
-		console.warn(`[gscdump/engine] ${hook} hook failed`, error);
-	}
-	async function notifyWriteError(info) {
-		try {
-			await hooks.onWriteError(info);
-		} catch (hookError) {
-			reportHookFailure("onWriteError", hookError);
-		}
-	}
-	async function writeOne(table, date, rows) {
-		const scope = scopeOf(ctx, table, date);
-		return (ctx.grain === "hour" ? engine.writeHour ?? (() => Promise.reject(/* @__PURE__ */ new Error("ingest accumulator: grain=hour requires engine.writeHour"))) : engine.writeDay)(scope, rows).then(() => engine.setSyncState(scope, "done")).then(async () => {
-			await hooks.onWritten?.({
-				table,
-				date,
-				rowCount: rows.length
-			});
-			return {
-				ok: true,
-				rows: rows.length
-			};
-		}).catch(async (err) => {
-			await notifyWriteError({
-				table,
-				date,
-				error: err
-			});
-			return { ok: false };
-		});
-	}
-	async function recover(table, date) {
-		const scope = scopeOf(ctx, table, date);
-		try {
-			await engine.setSyncState(scope, "failed", { error: "mid-continuation-skip" });
-		} catch (stateError) {
-			await notifyWriteError({
-				table,
-				date,
-				error: stateError
-			});
-		}
-		return hooks.onRecover(table, date).catch(async (err) => {
-			await notifyWriteError({
-				table,
-				date,
-				error: err
-			});
-			return false;
-		});
-	}
-	return {
-		push(table, rows) {
-			return acc.push(table, rows);
-		},
-		async finalize({ hasMore }) {
-			const overflowed = acc.overflowed;
-			const totalRows = acc.totalRows;
-			const buckets = acc.drain();
-			if (overflowed || hasMore) {
-				const tasks = [];
-				for (const [table, byDate] of buckets) for (const date of byDate.keys()) tasks.push(recover(table, date));
-				const results = await Promise.all(tasks).catch(async (err) => {
-					await notifyWriteError({
-						table: null,
-						date: null,
-						error: err
-					});
-					return [];
-				});
-				if (overflowed) await notifyWriteError({
-					table: null,
-					date: null,
-					error: /* @__PURE__ */ new Error(`ingest accumulator overflow at ${totalRows} rows; recovering via forced re-sync`)
-				});
-				return {
-					flushed: 0,
-					recovered: results.filter(Boolean).length,
-					failed: 0,
-					rowsWritten: 0
-				};
-			}
-			const writes = [];
-			for (const [table, byDate] of buckets) for (const [date, rows] of byDate) writes.push(writeOne(table, date, rows));
-			const outcomes = await Promise.all(writes);
-			let flushed = 0;
-			let failed = 0;
-			let rowsWritten = 0;
-			for (const o of outcomes) if (o.ok) {
-				flushed++;
-				rowsWritten += o.rows;
-			} else failed++;
-			if (flushed > 0 && hooks.onJobComplete) try {
-				await hooks.onJobComplete({
-					flushed,
-					rowsWritten
-				});
-			} catch (hookError) {
-				reportHookFailure("onJobComplete", hookError);
-			}
-			return {
-				flushed,
-				recovered: 0,
-				failed,
-				rowsWritten
-			};
-		}
-	};
-}
 function createQueryProfiler(sink, now = () => Date.now()) {
 	return { start(name, meta) {
 		const t0 = now();
@@ -519,6 +389,105 @@ function collectSpans(now) {
 		spans
 	};
 }
+const DAY = 24 * (3600 * 1e3);
+function isDue(state, now) {
+	return now >= state.nextAt;
+}
+function sitemapCadenceMs(consecutiveUnchanged) {
+	if (consecutiveUnchanged >= 7) return 30 * DAY;
+	if (consecutiveUnchanged >= 3) return 7 * DAY;
+	return DAY;
+}
+const SITEMAP_VERSION = 1;
+const sitemapPolicy = {
+	version: SITEMAP_VERSION,
+	initial(now) {
+		return {
+			nextAt: now + DAY,
+			consecutiveUnchanged: 0,
+			policyVersion: SITEMAP_VERSION
+		};
+	},
+	observe(prev, evt) {
+		if (prev.policyVersion !== SITEMAP_VERSION) return {
+			nextAt: evt.at + sitemapCadenceMs(0),
+			consecutiveUnchanged: 0,
+			policyVersion: SITEMAP_VERSION
+		};
+		if (evt.changed) return {
+			nextAt: evt.at + DAY,
+			consecutiveUnchanged: 0,
+			policyVersion: SITEMAP_VERSION
+		};
+		const next = prev.consecutiveUnchanged + 1;
+		return {
+			nextAt: evt.at + sitemapCadenceMs(next),
+			consecutiveUnchanged: next,
+			policyVersion: SITEMAP_VERSION
+		};
+	},
+	isDue
+};
+const INSPECTION_VERSION = 1;
+function inspectionCadenceMs(verdict) {
+	if (verdict === "PASS") return 30 * DAY;
+	if (verdict === "FAIL") return 7 * DAY;
+	return 14 * DAY;
+}
+function inspectionPolicy(verdict) {
+	const cadence = inspectionCadenceMs(verdict);
+	return {
+		version: INSPECTION_VERSION,
+		initial(now) {
+			return {
+				nextAt: now + cadence,
+				consecutiveUnchanged: 0,
+				policyVersion: INSPECTION_VERSION
+			};
+		},
+		observe(prev, evt) {
+			if (prev.policyVersion !== INSPECTION_VERSION) return {
+				nextAt: evt.at + cadence,
+				consecutiveUnchanged: 0,
+				policyVersion: INSPECTION_VERSION
+			};
+			const next = evt.changed ? 0 : prev.consecutiveUnchanged + 1;
+			return {
+				nextAt: evt.at + cadence,
+				consecutiveUnchanged: next,
+				policyVersion: INSPECTION_VERSION
+			};
+		},
+		isDue
+	};
+}
+const FIXED_VERSION = 1;
+function fixedPolicy(intervalMs) {
+	return {
+		version: FIXED_VERSION,
+		initial(now) {
+			return {
+				nextAt: now + intervalMs,
+				consecutiveUnchanged: 0,
+				policyVersion: FIXED_VERSION
+			};
+		},
+		observe(prev, evt) {
+			if (prev.policyVersion !== FIXED_VERSION) return {
+				nextAt: evt.at + intervalMs,
+				consecutiveUnchanged: 0,
+				policyVersion: FIXED_VERSION
+			};
+			const next = evt.changed ? 0 : prev.consecutiveUnchanged + 1;
+			return {
+				nextAt: evt.at + intervalMs,
+				consecutiveUnchanged: next,
+				policyVersion: FIXED_VERSION
+			};
+		},
+		isDue
+	};
+}
 const KEY_SEP = "\0";
 function partitionKey(slice) {
 	return [
@@ -674,4 +643,4 @@ const MIN_SYNC_IMPRESSIONS = 1;
 const MIN_COUNTRY_IMPRESSIONS = 10;
 const MAX_SITEMAP_URLS_PER_SITE = 5e4;
 const MAX_TRACKED_URLS_PER_SITE = 2e5;
-export { DEFAULT_SEARCH_TYPE, ENGINE_QUERY_CAPABILITIES, FILES_PLACEHOLDER, MAX_DAY_BYTES, MAX_GSC_PAGES_R2, MAX_SITEMAP_URLS_PER_SITE, MAX_TRACKED_URLS_PER_SITE, MIN_COUNTRY_IMPRESSIONS, MIN_SYNC_IMPRESSIONS, ROW_LIMIT_R2, SCHEMAS, TABLES_BY_SEARCH_TYPE, TABLE_METADATA, TABLE_TIERS, TIER_PRIORITY, WEIGHT_PRIORITY, allTables, assembleDatesRow, bindLiterals, coerceRow, coerceRows, collectSpans, countries, createDuckDBCodec, createDuckDBExecutor, createIcebergResolverAdapter, createInMemorySink, createIngestAccumulator, createParquetResolverAdapter, createQueryProfiler, createR2ManifestStore, createR2SqlResolverAdapter, createRowAccumulator, createSqlQuerySource, createStorageEngine, currentSchemaVersion, dates, dayPartition, dimensionToColumn, drizzleSchema, engineErrorToException, engineErrors, enumeratePartitions, fixedPolicy, formatLiteral, getDateWeight, getTableTier, getTablesForTier, hourPartition, hourly_pages, inferLegacyTier, inferSearchType, inferTable, inspectionPolicy, isEngineError, objectKey, page_queries, pages, parseEnabledSearchTypes, pgResolverAdapter, queries, rebuildDailyFromHourly, resolveParquetSQL, sitemapPolicy, substituteNamedFiles, toPath, toSumPosition, transformGscRow, validateEnabledSearchTypes, validateEnabledSearchTypesResult };
+export { DEFAULT_SEARCH_TYPE, MAX_DAY_BYTES, MAX_GSC_PAGES_R2, MAX_SITEMAP_URLS_PER_SITE, MAX_TRACKED_URLS_PER_SITE, MIN_COUNTRY_IMPRESSIONS, MIN_SYNC_IMPRESSIONS, ROW_LIMIT_R2, TABLES_BY_SEARCH_TYPE, TABLE_TIERS, TIER_PRIORITY, WEIGHT_PRIORITY, coerceRow, coerceRows, collectSpans, createDuckDBCodec, createDuckDBExecutor, createInMemorySink, createQueryProfiler, createR2ManifestStore, createStorageEngine, dayPartition, fixedPolicy, getDateWeight, getTableTier, getTablesForTier, hourPartition, inferLegacyTier, inferSearchType, inspectionPolicy, objectKey, parseEnabledSearchTypes, sitemapPolicy, validateEnabledSearchTypes, validateEnabledSearchTypesResult };

package/dist/ingest-accumulator.d.mts

@@ -0,0 +1,97 @@
+import { SearchType, TenantCtx as TenantCtx$1 } from "./_chunks/storage.mjs";
+import { GscApiRow, RowAccumulatorOptions } from "./ingest.mjs";
+import { Grain, Row, TableName } from "@gscdump/contracts";
+interface IngestAccumulatorEngine {
+  writeDay: (scope: TenantCtx$1 & {
+    table: TableName;
+    date: string;
+    searchType?: SearchType;
+  }, rows: Row[]) => Promise<void>;
+  /**
+   * Routed when the accumulator's `ctx.grain === 'hour'`. Same scope shape as
+   * `writeDay`; `date` is the PT calendar day, rows carry `hour` + `date`.
+   * Optional so hosts that never opt into hourly need not implement it.
+   */
+  writeHour?: (scope: TenantCtx$1 & {
+    table: TableName;
+    date: string;
+    searchType?: SearchType;
+  }, rows: Row[]) => Promise<void>;
+  setSyncState: (scope: TenantCtx$1 & {
+    table: TableName;
+    date: string;
+    searchType?: SearchType;
+  }, state: 'done' | 'failed', info?: {
+    error?: string;
+  }) => Promise<void>;
+}
+interface IngestAccumulatorCtx {
+  userId: string | number;
+  siteId: string;
+  searchType?: SearchType;
+  /**
+   * Temporal granularity for this accumulator. `'day'` (default) routes
+   * flushed buckets to `engine.writeDay`. `'hour'` routes to
+   * `engine.writeHour` and requires the engine implementation to be set.
+   */
+  grain?: Grain;
+}
+interface IngestAccumulatorHooks {
+  /**
+   * Called once per (table, date) when the job must abandon in-memory rows
+   *  (overflow or `hasMore` continuation). Host queues a forced re-sync from
+   *  the source. Return true iff a recovery job was actually queued.
+   */
+  onRecover: (table: TableName, date: string) => Promise<boolean>;
+  /**
+   * Called when an engine.writeDay fails or recovery itself errors. Host
+   *  logs to its error sink (e.g. `r2_write_errors` D1 table).
+   */
+  onWriteError: (info: {
+    table: TableName | null;
+    date: string | null;
+    error: unknown;
+  }) => Promise<void>;
+  /**
+   * Called after a successful writeDay for a (table, date). Host typically
+   *  busts the manifest cache here so the next read sees the new parquet.
+   */
+  onWritten?: (info: {
+    table: TableName;
+    date: string;
+    rowCount: number;
+  }) => void | Promise<void>;
+  /**
+   * Called once at end of `finalize`, only when at least one (table, date)
+   *  actually landed. Host queues rollup rebuild + compaction.
+   */
+  onJobComplete?: (info: {
+    flushed: number;
+    rowsWritten: number;
+  }) => Promise<void>;
+}
+interface FinalizeOptions {
+  /**
+   * The GSC `hasMore` flag for the whole job. When true, in-memory buckets
+   *  only reflect this job's slice; we re-queue forced single-day re-syncs
+   *  via `onRecover` so R2 stays authoritative.
+   */
+  hasMore: boolean;
+}
+interface FinalizeResult {
+  flushed: number;
+  recovered: number;
+  failed: number;
+  rowsWritten: number;
+}
+interface IngestAccumulator {
+  push: (table: TableName, rows: readonly GscApiRow[]) => boolean;
+  finalize: (opts: FinalizeOptions) => Promise<FinalizeResult>;
+}
+interface CreateIngestAccumulatorOptions extends RowAccumulatorOptions {
+  engine: IngestAccumulatorEngine;
+  ctx: IngestAccumulatorCtx;
+  hooks: IngestAccumulatorHooks;
+}
+declare function createIngestAccumulator(opts: CreateIngestAccumulatorOptions): IngestAccumulator;
+export { CreateIngestAccumulatorOptions, FinalizeOptions, FinalizeResult, IngestAccumulator, IngestAccumulatorCtx, IngestAccumulatorEngine, IngestAccumulatorHooks, createIngestAccumulator };

package/dist/ingest-accumulator.mjs

@@ -0,0 +1,123 @@
+import { createRowAccumulator } from "./ingest.mjs";
+function scopeOf(ctx, table, date) {
+	return {
+		userId: String(ctx.userId),
+		siteId: ctx.siteId,
+		table,
+		date,
+		...ctx.searchType !== void 0 ? { searchType: ctx.searchType } : {}
+	};
+}
+function createIngestAccumulator(opts) {
+	const { engine, ctx, hooks, ...accOpts } = opts;
+	const acc = createRowAccumulator(accOpts);
+	function reportHookFailure(hook, error) {
+		console.warn(`[gscdump/engine] ${hook} hook failed`, error);
+	}
+	async function notifyWriteError(info) {
+		try {
+			await hooks.onWriteError(info);
+		} catch (hookError) {
+			reportHookFailure("onWriteError", hookError);
+		}
+	}
+	async function writeOne(table, date, rows) {
+		const scope = scopeOf(ctx, table, date);
+		return (ctx.grain === "hour" ? engine.writeHour ?? (() => Promise.reject(/* @__PURE__ */ new Error("ingest accumulator: grain=hour requires engine.writeHour"))) : engine.writeDay)(scope, rows).then(() => engine.setSyncState(scope, "done")).then(async () => {
+			await hooks.onWritten?.({
+				table,
+				date,
+				rowCount: rows.length
+			});
+			return {
+				ok: true,
+				rows: rows.length
+			};
+		}).catch(async (err) => {
+			await notifyWriteError({
+				table,
+				date,
+				error: err
+			});
+			return { ok: false };
+		});
+	}
+	async function recover(table, date) {
+		const scope = scopeOf(ctx, table, date);
+		try {
+			await engine.setSyncState(scope, "failed", { error: "mid-continuation-skip" });
+		} catch (stateError) {
+			await notifyWriteError({
+				table,
+				date,
+				error: stateError
+			});
+		}
+		return hooks.onRecover(table, date).catch(async (err) => {
+			await notifyWriteError({
+				table,
+				date,
+				error: err
+			});
+			return false;
+		});
+	}
+	return {
+		push(table, rows) {
+			return acc.push(table, rows);
+		},
+		async finalize({ hasMore }) {
+			const overflowed = acc.overflowed;
+			const totalRows = acc.totalRows;
+			const buckets = acc.drain();
+			if (overflowed || hasMore) {
+				const tasks = [];
+				for (const [table, byDate] of buckets) for (const date of byDate.keys()) tasks.push(recover(table, date));
+				const results = await Promise.all(tasks).catch(async (err) => {
+					await notifyWriteError({
+						table: null,
+						date: null,
+						error: err
+					});
+					return [];
+				});
+				if (overflowed) await notifyWriteError({
+					table: null,
+					date: null,
+					error: /* @__PURE__ */ new Error(`ingest accumulator overflow at ${totalRows} rows; recovering via forced re-sync`)
+				});
+				return {
+					flushed: 0,
+					recovered: results.filter(Boolean).length,
+					failed: 0,
+					rowsWritten: 0
+				};
+			}
+			const writes = [];
+			for (const [table, byDate] of buckets) for (const [date, rows] of byDate) writes.push(writeOne(table, date, rows));
+			const outcomes = await Promise.all(writes);
+			let flushed = 0;
+			let failed = 0;
+			let rowsWritten = 0;
+			for (const o of outcomes) if (o.ok) {
+				flushed++;
+				rowsWritten += o.rows;
+			} else failed++;
+			if (flushed > 0 && hooks.onJobComplete) try {
+				await hooks.onJobComplete({
+					flushed,
+					rowsWritten
+				});
+			} catch (hookError) {
+				reportHookFailure("onJobComplete", hookError);
+			}
+			return {
+				flushed,
+				recovered: 0,
+				failed,
+				rowsWritten
+			};
+		}
+	};
+}
+export { createIngestAccumulator };

package/dist/period/index.d.mts

@@ -1,2 +1,2 @@
-import { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, padTimeseries, periodOf, resolveWindow } from "../_chunks/index2.mjs";
+import { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, padTimeseries, periodOf, resolveWindow } from "../_chunks/index.mjs";
 export { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, padTimeseries, periodOf, resolveWindow };

package/dist/planner.d.mts

@@ -1,3 +1,15 @@
-import { enumeratePartitions } from "./_chunks/storage.mjs";
-import { FILES_PLACEHOLDER, ResolvedQuery, compileLogicalQueryPlan, resolveParquetSQL, substituteNamedFiles } from "./_chunks/planner.mjs";
+import { TableName, enumeratePartitions } from "./_chunks/storage.mjs";
+import { LogicalQueryPlan } from "gscdump/query/plan";
+import { BuilderState } from "gscdump/query";
+interface ResolvedQuery {
+  sql: string;
+  params: unknown[];
+  partitions: string[];
+  table: TableName;
+  filesPlaceholder: string;
+}
+declare const FILES_PLACEHOLDER = "{{FILES}}";
+declare function compileLogicalQueryPlan(plan: LogicalQueryPlan, table?: TableName): ResolvedQuery;
+declare function resolveParquetSQL(state: BuilderState, table?: TableName): ResolvedQuery;
+declare function substituteNamedFiles(sql: string, sets: Record<string, string[]>): string;
 export { FILES_PLACEHOLDER, type ResolvedQuery, compileLogicalQueryPlan, enumeratePartitions, resolveParquetSQL, substituteNamedFiles };

package/dist/report/index.d.mts

@@ -1,5 +1,5 @@
 import { AnalysisParams, AnalysisResult } from "../_chunks/analysis-types.mjs";
-import { ComparisonMode, ResolvedWindow, WindowPreset } from "../_chunks/index2.mjs";
+import { ComparisonMode, ResolvedWindow, WindowPreset } from "../_chunks/index.mjs";
 /** Status vocabulary mirrors `ActionPrioritySourceStatus`. */
 type ReportStepStatus = 'pending' | 'running' | 'done' | 'skipped' | 'error';
 type ReportSeverity = 'info' | 'low' | 'medium' | 'high';

package/dist/resolver/index.d.mts

@@ -1,6 +1,5 @@
 import { SearchType as SearchType$1, TableName as TableName$1 } from "../_chunks/storage.mjs";
 import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverAdapter, ResolverOptions } from "../_chunks/types.mjs";
-import { PgTableKey, R2SqlResolverAdapterOptions, ResolverAdapterOptions, createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter } from "../_chunks/pg-adapter.mjs";
 import { LogicalDataset, LogicalDataset as LogicalDataset$1, PlannerCapabilities, UnresolvableDatasetError, inferDataset as inferLogicalDataset, isDatasetResolvable } from "gscdump/query/plan";
 import { SQL } from "drizzle-orm";
 import { BuilderState, Dimension, FilterInput, InternalFilter, Metric } from "gscdump/query";
@@ -304,6 +303,59 @@ declare function dimensionValue(row: Record<string, unknown>, dimension: string)
 declare function matchesDimensionFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
 declare function matchesMetricFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
 declare function matchesTopLevelPage(row: Record<string, unknown>): boolean;
+type PgTableKey = TableName;
+declare const pgResolverAdapter: ResolverAdapter<PgTableKey>;
+/**
+ * Parquet-aware variant of {@link pgResolverAdapter}. Identical SQL output
+ * except FROM clauses emit `read_parquet({{FILES}}, union_by_name = true) AS
+ * "${tk}"`. The runSQL pipeline substitutes `{{FILES}}` with R2 object keys
+ * resolved from the manifest. The `AS "${tk}"` alias is mandatory — drizzle
+ * compiles `colRef` to table-qualified `"pages"."url"`, which would not
+ * resolve against an unaliased FROM.
+ *
+ * Single-use: build a fresh adapter per query. Cheap (no I/O) and avoids
+ * accidental adapter caching that would lock in a stale `{{FILES}}` set.
+ */
+interface ResolverAdapterOptions {
+  /**
+   * `queryDim` reads canonical from a joined query dimension. `column` is only
+   * for derived canonical rollup relations whose primary relation already
+   * carries a null-free `query_canonical` output column.
+   */
+  queryCanonicalSource?: 'queryDim' | 'column';
+}
+interface R2SqlResolverAdapterOptions extends ResolverAdapterOptions {
+  /**
+   * R2 SQL string partition equality can undercount on identity partitions;
+   * string-encoded catalogs use CONCAT(col, '') in partition predicates. Int
+   * catalogs do not need the workaround and keep bare equality for pruning.
+   */
+  partitionKeyEncoding?: 'string' | 'int';
+}
+declare function createParquetResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
+/**
+ * Multi-tenant pg-flavored adapter for the Iceberg / R2 SQL read path.
+ * Identical SQL output to `pgResolverAdapter` except WHERE clauses inject
+ * `site_id = ?` AND `search_type = ?` automatically when those scopes are
+ * passed to `resolveToSQL`. Required for the Iceberg fact tables which are
+ * shared across tenants — querying without these predicates would leak
+ * cross-tenant data. Single-use: the adapter has no `tableRef` override,
+ * so callers must rewrite bare table names to their qualified form (e.g.
+ * `${namespace}.pages`) before sending to R2 SQL.
+ */
+declare function createIcebergResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
+/**
+ * R2 SQL adapter for the Iceberg fact tables.
+ *
+ * It shares the multi-tenant Iceberg schema with `createIcebergResolverAdapter`
+ * but models R2 SQL's narrower execution surface: no window-total plans and no
+ * comparison joins. Int-partition catalogs are the default and emit bare
+ * equality predicates for pruning. Legacy string-partition catalogs must pass
+ * `partitionKeyEncoding: 'string'` to emit `CONCAT(partition_col, '') = ?`,
+ * working around R2 SQL's partition-string equality undercount while preserving
+ * bound params.
+ */
+declare function createR2SqlResolverAdapter(options?: R2SqlResolverAdapterOptions): ResolverAdapter<PgTableKey>;
 interface AssertSchemaInSyncOptions {
   /** Label used in the thrown error (e.g. 'browser', 'sqlite'). */
   label: string;

package/dist/rollups.mjs

@@ -1,9 +1,10 @@
 import { engineErrors } from "./errors.mjs";
 import "./_chunks/layout.mjs";
+import { inspectionParquetKey, sitemapUrlsIndexPrefix } from "./entity-keys.mjs";
 import { encodeRowsToParquetFlex } from "./adapters/hyparquet.mjs";
-import { createIndexingMetadataStore, createQueryDimStore, createSitemapStore, inspectionParquetKey, sitemapUrlsIndexPrefix } from "./_chunks/entities.mjs";
+import { createIndexingMetadataStore, createQueryDimStore, createSitemapStore } from "./_chunks/entities.mjs";
 import { MS_PER_DAY } from "gscdump/dates";
-import { encodeJsonBigintSafe } from "@gscdump/lakehouse";
+import { encodeJsonBigintSafe } from "@gscdump/lakehouse/bigint";
 function rollupPrefix(ctx, searchType) {
 	const base = ctx.siteId ? `u_${ctx.userId}/${ctx.siteId}/rollups` : `u_${ctx.userId}/rollups`;
 	return searchType !== void 0 && searchType !== "web" ? `${base}/${searchType}` : base;