@gscdump/engine 3.5.0 → 3.6.1

package/dist/resolver/compile.d.mts

@@ -1,15 +1,19 @@
 import { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverOptions } from "./types.mjs";
 import { BuilderState } from "gscdump/query";
-declare function resolveToSQLOptimized<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQLOptimized;
-declare function resolveToSQL<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQL;
-declare function buildTotalsSql<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): {
+export declare function resolveToSQLOptimized<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQLOptimized;
+export declare function resolveToSQL<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ResolvedSQL;
+export declare function buildTotalsSql<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): {
   sql: string;
   params: unknown[];
 };
-declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter): ResolvedComparisonSQL;
-declare function buildExtrasQueries<TK extends string>(state: BuilderState, options: ResolverOptions<TK>): ExtraQuery[];
-declare function mergeExtras(rows: Record<string, unknown>[], extrasResults: {
+export declare function resolveComparisonSQL<TK extends string>(current: BuilderState, previous: BuilderState, options: ResolverOptions<TK>, comparisonFilter?: ComparisonFilter): ResolvedComparisonSQL;
+/**
+ * Enrich Canonical Query groups with their raw variants.
+ * Supply selected keys to limit aggregation to the current page.
+ * An empty key list skips enrichment. Omit keys to enrich the full window.
+ */
+export declare function buildExtrasQueries<TK extends string>(state: BuilderState, options: ResolverOptions<TK>, queryCanonicalKeys?: readonly string[]): ExtraQuery[];
+export declare function mergeExtras(rows: Record<string, unknown>[], extrasResults: {
   key: string;
   results: Record<string, unknown>[];
-}[]): Record<string, unknown>[];
-export { buildExtrasQueries, buildTotalsSql, mergeExtras, resolveComparisonSQL, resolveToSQL, resolveToSQLOptimized };
+}[]): Record<string, unknown>[];

package/dist/resolver/compile.mjs

@@ -295,12 +295,12 @@ function resolveComparisonSQL(current, previous, options, comparisonFilter) {
 		countParams: count.params
 	};
 }
-function buildExtrasQueries(state, options) {
+function buildExtrasQueries(state, options, queryCanonicalKeys) {
 	const { adapter, siteId, searchType } = options;
 	const plan = buildLogicalPlan(state, adapter.capabilities);
 	const dims = plan.groupByDimensions;
 	const extras = [];
-	if (!dims.includes("queryCanonical")) return extras;
+	if (!dims.includes("queryCanonical") || queryCanonicalKeys?.length === 0) return extras;
 	const queriesKey = adapter.tableKeyForDataset("queries");
 	const t = adapter.schema[queriesKey];
 	const table = adapter.fromSql(queriesKey, { queryCanonical: true });
@@ -309,9 +309,13 @@ function buildExtrasQueries(state, options) {
 	if (adapter.searchTypeColRef && searchType != null) whereParts.push(sql`${adapter.searchTypeColRef(queriesKey)} = ${searchType}`);
 	whereParts.push(sql`${adapter.dateColRef(queriesKey)} >= ${plan.dateRange.startDate}`);
 	whereParts.push(sql`${adapter.dateColRef(queriesKey)} <= ${plan.dateRange.endDate}`);
-	const whereExpr = whereParts.length > 0 ? sql`WHERE ${joinAnd(whereParts)}` : sql``;
 	const outerQueryCol = sql.raw("query");
 	const canonKey = adapter.dimExprSql("queryCanonical", queriesKey);
+	if (queryCanonicalKeys) {
+		const keys = [...new Set(queryCanonicalKeys)].map((key) => sql`${key}`);
+		whereParts.push(sql`${canonKey} IN (${joinComma(keys)})`);
+	}
+	const whereExpr = whereParts.length > 0 ? sql`WHERE ${joinAnd(whereParts)}` : sql``;
 	const compiled = compileCollapsed(adapter, sql`WITH per_variant AS (SELECT ${canonKey} as joinKey, ${t.query} as query, SUM(${t.clicks}) as clicks, SUM(${t.impressions}) as impressions, SUM(${t.sum_position}) as sum_pos, ROW_NUMBER() OVER (PARTITION BY ${canonKey} ORDER BY SUM(${t.clicks}) DESC) as rn, COUNT(*) OVER (PARTITION BY ${canonKey}) as variantCount FROM ${table} ${whereExpr} GROUP BY ${canonKey}, ${t.query}) SELECT joinKey, MAX(variantCount) as variantCount, MAX(CASE WHEN rn = 1 THEN ${outerQueryCol} END) as canonicalName, STRING_AGG(CASE WHEN rn <= 10 THEN ${outerQueryCol} || ':::' || clicks || ':::' || impressions || ':::' || CAST(ROUND(CAST(sum_pos AS REAL) / NULLIF(impressions, 0) + 1, 1) AS TEXT) END, '||') as variants FROM per_variant GROUP BY joinKey`);
 	extras.push({
 		key: "canonicalExtras",

package/dist/resolver/datasets.d.mts

@@ -1,16 +1,16 @@
 import { LogicalDataset as LogicalDataset$1, UnresolvableDatasetError, inferDataset as inferLogicalDataset, isDatasetResolvable } from "gscdump/query/plan";
 import { Dimension } from "gscdump/query";
-type DimensionSurface = 'api' | 'stored' | 'derived';
-interface DimensionBinding {
+export type DimensionSurface = 'api' | 'stored' | 'derived';
+export interface DimensionBinding {
   column: string;
   surfaces: readonly DimensionSurface[];
 }
-interface LogicalDatasetDefinition {
+export interface LogicalDatasetDefinition {
   dimensions: Partial<Record<Dimension, DimensionBinding>>;
 }
-declare const DIMENSION_SURFACES: Record<Dimension, readonly DimensionSurface[]>;
-declare const LOGICAL_DATASETS: Record<LogicalDataset$1, LogicalDatasetDefinition>;
-declare function dimensionColumn(dim: Dimension, dataset: LogicalDataset$1): string;
-declare function supportsDimensionOnSurface(dim: Dimension, surface: DimensionSurface): boolean;
-declare function assertDimensionsSupported(dimensions: readonly Dimension[], surface: DimensionSurface, context: string): void;
-export { DIMENSION_SURFACES, DimensionBinding, DimensionSurface, LOGICAL_DATASETS, type LogicalDataset$1 as LogicalDataset, LogicalDatasetDefinition, UnresolvableDatasetError, assertDimensionsSupported, dimensionColumn, inferLogicalDataset, isDatasetResolvable, supportsDimensionOnSurface };
+export declare const DIMENSION_SURFACES: Record<Dimension, readonly DimensionSurface[]>;
+export declare const LOGICAL_DATASETS: Record<LogicalDataset$1, LogicalDatasetDefinition>;
+export declare function dimensionColumn(dim: Dimension, dataset: LogicalDataset$1): string;
+export declare function supportsDimensionOnSurface(dim: Dimension, surface: DimensionSurface): boolean;
+export declare function assertDimensionsSupported(dimensions: readonly Dimension[], surface: DimensionSurface, context: string): void;
+export { type LogicalDataset$1 as LogicalDataset, UnresolvableDatasetError, inferLogicalDataset, isDatasetResolvable };

package/dist/resolver/extras-overlay.d.mts

@@ -14,7 +14,7 @@ import { ResolveExtraFn } from "./run-query.mjs";
  * out-of-window variantCount/canonicalName/variants. A common rule: serve only
  * when the request window covers full history.
  */
-interface RollupRowsReader {
+export interface RollupRowsReader {
   (opts: {
     id: string;
     ctx: {
@@ -33,5 +33,4 @@ interface RollupRowsReader {
  * rollups when one is mapped for the extra's key, else returns `null` to fall
  * back to the live SQL. Pure wiring around the host's `readRollupRows`.
  */
-declare function createRollupExtrasOverlay(readRollupRows: RollupRowsReader): ResolveExtraFn;
-export { RollupRowsReader, createRollupExtrasOverlay };
+export declare function createRollupExtrasOverlay(readRollupRows: RollupRowsReader): ResolveExtraFn;

package/dist/resolver/filter-utils.d.mts

@@ -1,10 +1,10 @@
 import { Dimension, FilterInput, InternalFilter, Metric } from "gscdump/query";
-declare function getInternalFilters(filter: FilterInput | undefined): InternalFilter[];
-declare function getDimensionFilters(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): InternalFilter[];
-declare function getFilterDimensions(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): Dimension[];
+export declare function getInternalFilters(filter: FilterInput | undefined): InternalFilter[];
+export declare function getDimensionFilters(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): InternalFilter[];
+export declare function getFilterDimensions(filter: FilterInput | undefined, isMetricDimension: (dim: string) => dim is Metric): Dimension[];
 declare function metricValue(row: Record<string, unknown>, metric: string): number;
 declare function dimensionValue(row: Record<string, unknown>, dimension: string): 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;
-export { dimensionValue, getDimensionFilters, getFilterDimensions, getInternalFilters, matchesDimensionFilter, matchesMetricFilter, matchesTopLevelPage, metricValue };
+export declare function matchesDimensionFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
+export declare function matchesMetricFilter(row: Record<string, unknown>, filter: InternalFilter): boolean;
+export declare function matchesTopLevelPage(row: Record<string, unknown>): boolean;
+export { dimensionValue, metricValue };

package/dist/resolver/fragments.d.mts

@@ -2,7 +2,7 @@ import { LOGICAL_DATASETS } from "./datasets.mjs";
 import { LogicalDataset } from "gscdump/query/plan";
 import { SQL } from "drizzle-orm";
 import { Dimension, InternalFilter, Metric } from "gscdump/query";
-interface SqlFragmentsConfig<TableKey extends string> {
+export interface SqlFragmentsConfig<TableKey extends string> {
   schema: Record<TableKey, unknown>;
   datasetToTableKey: Record<keyof typeof LOGICAL_DATASETS, TableKey>;
   metricCast: 'REAL' | 'DOUBLE';
@@ -33,7 +33,7 @@ interface SqlFragmentsConfig<TableKey extends string> {
   /** When true, also joins query_dim on site_id (SQLite/D1 dimension table). */
   queryDimSiteScoped?: boolean;
 }
-interface SqlFragments<TableKey extends string> {
+export interface SqlFragments<TableKey extends string> {
   METRIC_NAMES: Metric[];
   DIM_COLUMN_MAP: Record<TableKey, Record<string, string>>;
   isMetricDimension: (dim: string) => dim is Metric;
@@ -56,5 +56,4 @@ interface SqlFragments<TableKey extends string> {
   dimensionPredicates: (filters: InternalFilter[], tableKey: TableKey) => SQL[];
   topLevelPredicate: (filters: InternalFilter[], tableKey: TableKey) => SQL | undefined;
 }
-declare function createSqlFragments<TableKey extends string>(config: SqlFragmentsConfig<TableKey>): SqlFragments<TableKey>;
-export { SqlFragments, SqlFragmentsConfig, createSqlFragments };
+export declare function createSqlFragments<TableKey extends string>(config: SqlFragmentsConfig<TableKey>): SqlFragments<TableKey>;

package/dist/resolver/pg-adapter.d.mts

@@ -1,7 +1,7 @@
 import { ResolverAdapter } from "./types.mjs";
 import { TableName } from "@gscdump/contracts";
-type PgTableKey = TableName;
-declare const pgResolverAdapter: ResolverAdapter<PgTableKey>;
+export type PgTableKey = TableName;
+export 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
@@ -13,7 +13,7 @@ declare const pgResolverAdapter: ResolverAdapter<PgTableKey>;
  * 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 {
+export interface ResolverAdapterOptions {
   /**
    * `queryDim` reads canonical from a joined query dimension. `column` is only
    * for derived canonical rollup relations whose primary relation already
@@ -21,7 +21,7 @@ interface ResolverAdapterOptions {
    */
   queryCanonicalSource?: 'queryDim' | 'column';
 }
-interface R2SqlResolverAdapterOptions extends ResolverAdapterOptions {
+export interface R2SqlResolverAdapterOptions extends ResolverAdapterOptions {
   /**
    * R2 SQL string partition equality can undercount on identity partitions;
    * string-encoded catalogs use CONCAT(col, '') in partition predicates. Int
@@ -29,7 +29,7 @@ interface R2SqlResolverAdapterOptions extends ResolverAdapterOptions {
    */
   partitionKeyEncoding?: 'string' | 'int';
 }
-declare function createParquetResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
+export declare function createParquetResolverAdapter(options?: ResolverAdapterOptions): ResolverAdapter<PgTableKey>;
 /**
  * Multi-tenant pg-flavored adapter for the Iceberg / R2 SQL read path.
  * Set `dialect: 'r2sql'` to emit R2 SQL regex predicates. The default targets DuckDB.
@@ -46,7 +46,7 @@ declare function createParquetResolverAdapter(options?: ResolverAdapterOptions):
  * `partitionKeyEncoding: 'string'` to emit `CONCAT(col, '') = ?` instead —
  * bare equality undercounts (silently returns fewer rows) on those catalogs.
  */
-declare function createIcebergResolverAdapter(options?: R2SqlResolverAdapterOptions & {
+export declare function createIcebergResolverAdapter(options?: R2SqlResolverAdapterOptions & {
   dialect?: 'duckdb' | 'r2sql';
 }): ResolverAdapter<PgTableKey>;
 /**
@@ -60,5 +60,4 @@ declare function createIcebergResolverAdapter(options?: R2SqlResolverAdapterOpti
  * working around R2 SQL's partition-string equality undercount while preserving
  * bound params.
  */
-declare function createR2SqlResolverAdapter(options?: R2SqlResolverAdapterOptions): ResolverAdapter<PgTableKey>;
-export { PgTableKey, R2SqlResolverAdapterOptions, ResolverAdapterOptions, createIcebergResolverAdapter, createParquetResolverAdapter, createR2SqlResolverAdapter, pgResolverAdapter };
+export declare function createR2SqlResolverAdapter(options?: R2SqlResolverAdapterOptions): ResolverAdapter<PgTableKey>;

package/dist/resolver/run-query.d.mts

@@ -2,7 +2,7 @@ import { SearchType as SearchType$1, TableName as TableName$1 } from "../storage
 import { ComparisonFilter } from "./types.mjs";
 import { Grain } from "@gscdump/contracts";
 import { BuilderState } from "gscdump/query";
-interface RunQueryCtx {
+export interface RunQueryCtx {
   userId: string;
   siteId: string;
   table: TableName$1;
@@ -16,7 +16,7 @@ interface RunQueryCtx {
    */
   grain?: Grain;
 }
-interface RunSQLFn {
+export interface RunSQLFn {
   (opts: {
     ctx: {
       userId: string;
@@ -35,14 +35,14 @@ interface RunSQLFn {
     rows: Array<Record<string, unknown>>;
   }>;
 }
-interface CanonicalQueryDimSource {
+export interface CanonicalQueryDimSource {
   /** Object keys for the versioned query_dim parquet. */
   keys: string[];
   normalizerVersion: number;
   intentVersion?: number;
   builtAt?: number;
 }
-interface PrimaryColumnarSource {
+export interface PrimaryColumnarSource {
   /** Pre-resolved compacted/Iceberg parquet object keys for the requested fact table. */
   keys: string[];
   /** Oldest covered date (`YYYY-MM-DD`). Omit to assert the source covers all older dates. */
@@ -59,7 +59,7 @@ interface PrimaryColumnarSource {
  * the live query. Pure seam: storage/tenant routing lives in the host's
  * implementation, not here. See ADR-0017.
  */
-interface ResolveExtraFn {
+export interface ResolveExtraFn {
   (opts: {
     key: string;
     state: BuilderState;
@@ -70,7 +70,7 @@ interface ResolveExtraFn {
     };
   }): Promise<Array<Record<string, unknown>> | null>;
 }
-interface RunOptimizedQueryOptions {
+export interface RunOptimizedQueryOptions {
   /** Overlay tried per extra before the live SQL; absent → today's live path. */
   resolveExtra?: ResolveExtraFn;
   /**
@@ -117,23 +117,23 @@ interface RunOptimizedQueryOptions {
     intentVersion?: number;
   };
 }
-type QuerySourceKind = 'canonical-rollup' | 'primary-columnar' | 'raw-partitions';
-type QuerySourceFallbackKind = 'primary-source-missing' | 'primary-source-empty' | 'primary-source-missing-coverage' | 'primary-source-stale-coverage' | 'canonical-source-missing' | 'canonical-source-empty' | 'canonical-source-not-coverable' | 'canonical-source-stale-coverage' | 'query-dim-missing' | 'query-dim-empty' | 'query-dim-stale-version';
-interface QuerySourceFallback {
+export type QuerySourceKind = 'canonical-rollup' | 'primary-columnar' | 'raw-partitions';
+export type QuerySourceFallbackKind = 'primary-source-missing' | 'primary-source-empty' | 'primary-source-missing-coverage' | 'primary-source-stale-coverage' | 'canonical-source-missing' | 'canonical-source-empty' | 'canonical-source-not-coverable' | 'canonical-source-stale-coverage' | 'query-dim-missing' | 'query-dim-empty' | 'query-dim-stale-version';
+export interface QuerySourceFallback {
   kind: QuerySourceFallbackKind;
   message: string;
 }
-interface QuerySourceDecision {
+export interface QuerySourceDecision {
   kind: QuerySourceKind;
   fallback?: QuerySourceFallback;
   fallbacks?: QuerySourceFallback[];
 }
-declare class QuerySourceCoverageError extends Error {
+export declare class QuerySourceCoverageError extends Error {
   readonly fallback: QuerySourceFallback;
   name: string;
   constructor(fallback: QuerySourceFallback);
 }
-interface OptimizedQueryResult {
+export interface OptimizedQueryResult {
   rows: Array<Record<string, unknown>>;
   totalCount: number;
   totals: {
@@ -149,17 +149,17 @@ interface OptimizedQueryResult {
   source: QuerySourceDecision;
   extraSource?: QuerySourceDecision;
 }
-interface ComparisonQueryResult {
+export interface ComparisonQueryResult {
   rows: Array<Record<string, unknown>>;
   totalCount: number;
   totals: Record<string, unknown>;
   source: QuerySourceDecision;
 }
-declare function runOptimizedQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, state: BuilderState, dateRange: {
+export declare function runOptimizedQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, state: BuilderState, dateRange: {
   startDate: string;
   endDate: string;
 }, options?: RunOptimizedQueryOptions): Promise<OptimizedQueryResult>;
-declare function runComparisonQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, current: BuilderState, previous: BuilderState, windows: {
+export declare function runComparisonQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, current: BuilderState, previous: BuilderState, windows: {
   current: {
     startDate: string;
     endDate: string;
@@ -168,5 +168,4 @@ declare function runComparisonQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, current:
     startDate: string;
     endDate: string;
   };
-}, filter?: ComparisonFilter, options?: RunOptimizedQueryOptions): Promise<ComparisonQueryResult>;
-export { CanonicalQueryDimSource, ComparisonQueryResult, OptimizedQueryResult, PrimaryColumnarSource, QuerySourceCoverageError, QuerySourceDecision, QuerySourceFallback, QuerySourceFallbackKind, QuerySourceKind, ResolveExtraFn, RunOptimizedQueryOptions, RunQueryCtx, RunSQLFn, runComparisonQuery, runOptimizedQuery };
+}, filter?: ComparisonFilter, options?: RunOptimizedQueryOptions): Promise<ComparisonQueryResult>;

package/dist/resolver/run-query.mjs

@@ -131,26 +131,27 @@ async function runOptimizedQuery(runSQL, ctx, state, dateRange, options = {}) {
 		adapter,
 		siteId: void 0
 	});
+	const queryDim = canonicalQueryDim(options);
+	const optRes = await runSQL({
+		...withQueryDimFileSet(useCanonicalSource ? {
+			...base,
+			fileSets: { FILES: {
+				table: ctx.table,
+				keys: options.canonicalSource.keys
+			} }
+		} : source.kind === "primary-columnar" ? primaryRunArgs(ctx, options.primarySource.keys) : base, queryDim, canonicalRequested && !useCanonicalSource),
+		sql: optimized.sql,
+		params: optimized.params
+	});
+	const queryCanonicalKeys = optRes.rows.flatMap((row) => typeof row.queryCanonical === "string" ? [row.queryCanonical] : []);
 	const extras = buildExtrasQueries(state, {
 		adapter: probe,
 		siteId: void 0
-	});
+	}, queryCanonicalKeys);
 	const extraSource = extras.length > 0 ? useCanonicalSource ? decidePrimarySource(options, dateRange) : source : void 0;
-	const queryDim = canonicalQueryDim(options);
-	const mainArgs = withQueryDimFileSet(useCanonicalSource ? {
-		...base,
-		fileSets: { FILES: {
-			table: ctx.table,
-			keys: options.canonicalSource.keys
-		} }
-	} : source.kind === "primary-columnar" ? primaryRunArgs(ctx, options.primarySource.keys) : base, queryDim, canonicalRequested && !useCanonicalSource);
 	const extraArgs = withQueryDimFileSet(extraSource?.kind === "primary-columnar" ? primaryRunArgs(ctx, options.primarySource.keys) : base, queryDim, extras.length > 0);
 	const resolveExtra = options.resolveExtra;
-	const [optRes, ...extrasRows] = await Promise.all([runSQL({
-		...mainArgs,
-		sql: optimized.sql,
-		params: optimized.params
-	}), ...extras.map(async (e) => {
+	const extrasRows = await Promise.all(extras.map(async (e) => {
 		const overlaid = resolveExtra ? await resolveExtra({
 			key: e.key,
 			state,
@@ -162,7 +163,7 @@ async function runOptimizedQuery(runSQL, ctx, state, dateRange, options = {}) {
 			sql: e.sql,
 			params: e.params
 		});
-	})]);
+	}));
 	const firstRow = optRes.rows[0];
 	const totalCount = Number(firstRow?.totalCount ?? 0);
 	const totals = {

package/dist/resolver/schema-drift.d.mts

@@ -1,5 +1,5 @@
 import { TableName } from "@gscdump/contracts";
-interface AssertSchemaInSyncOptions {
+export interface AssertSchemaInSyncOptions {
   /** Label used in the thrown error (e.g. 'browser', 'sqlite'). */
   label: string;
   /** Drizzle schema keyed by table name. For sqlite, strip the `gsc_` prefix before passing. */
@@ -11,5 +11,4 @@ interface AssertSchemaInSyncOptions {
   tableKeyToName: (key: string) => TableName;
   mode: 'exact' | 'superset';
 }
-declare function assertSchemaInSync(options: AssertSchemaInSyncOptions): void;
-export { AssertSchemaInSyncOptions, assertSchemaInSync };
+export declare function assertSchemaInSync(options: AssertSchemaInSyncOptions): void;

package/dist/resolver/types.d.mts

@@ -1,7 +1,7 @@
 import { LogicalDataset, PlannerCapabilities } from "gscdump/query/plan";
 import { SQL } from "drizzle-orm";
 import { Dimension, InternalFilter, Metric } from "gscdump/query";
-interface ResolverAdapter<TableKey extends string = string> {
+export interface ResolverAdapter<TableKey extends string = string> {
   readonly METRIC_NAMES: readonly Metric[];
   readonly capabilities: PlannerCapabilities;
   readonly schema: Record<TableKey, unknown>;
@@ -28,8 +28,8 @@ interface ResolverAdapter<TableKey extends string = string> {
     params: unknown[];
   };
 }
-type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
-interface ResolverOptions<TableKey extends string = string> {
+export type ComparisonFilter = 'new' | 'lost' | 'improving' | 'declining';
+export interface ResolverOptions<TableKey extends string = string> {
   adapter: ResolverAdapter<TableKey>;
   /** Optional site scope. Required for multi-tenant D1; omitted for parquet. */
   siteId?: string | number;
@@ -49,25 +49,24 @@ interface ResolverOptions<TableKey extends string = string> {
    */
   minimumImpressions?: number;
 }
-interface ResolvedSQL {
+export interface ResolvedSQL {
   sql: string;
   params: unknown[];
   countSql: string;
   countParams: unknown[];
 }
-interface ResolvedSQLOptimized {
+export interface ResolvedSQLOptimized {
   sql: string;
   params: unknown[];
 }
-interface ResolvedComparisonSQL {
+export interface ResolvedComparisonSQL {
   sql: string;
   params: unknown[];
   countSql: string;
   countParams: unknown[];
 }
-interface ExtraQuery {
+export interface ExtraQuery {
   key: string;
   sql: string;
   params: unknown[];
-}
-export { ComparisonFilter, ExtraQuery, ResolvedComparisonSQL, ResolvedSQL, ResolvedSQLOptimized, ResolverAdapter, ResolverOptions };
+}

package/dist/rollups/canonical.d.mts

@@ -3,7 +3,7 @@ import "../contracts.mjs";
 import { RollupDef, RollupEngine } from "./core.mjs";
 import { TenantCtx } from "@gscdump/contracts";
 import { SearchType } from "gscdump/query";
-declare const queryCanonicalVariantsRollup: RollupDef;
+export declare const queryCanonicalVariantsRollup: RollupDef;
 /**
  * Canonical-grained fact aggregate (ADR-0018 Gap 2): pre-sums the raw
  * `(query × date)` query rows to `(query_canonical × date)`, so canonical-
@@ -23,7 +23,7 @@ declare const queryCanonicalVariantsRollup: RollupDef;
  * queries the rollup covers (see `canonicalRollupCovers` /
  * `RunOptimizedQueryOptions.canonicalSource`).
  */
-declare const queryCanonicalDailyRollup: RollupDef;
+export declare const queryCanonicalDailyRollup: RollupDef;
 /**
  * Resumable, cross-invocation build of `query_canonical_daily` for a high-
  * cardinality site whose full windowed build exceeds one job reservation (300s).
@@ -44,7 +44,7 @@ declare const queryCanonicalDailyRollup: RollupDef;
  * `(windowOffset, pageOffset)`; multiple parts may contain the same canonical/date
  * from different raw-query shards, and rollup reads sum over the union.
  */
-declare function rebuildCanonicalDailyResumable(opts: {
+export declare function rebuildCanonicalDailyResumable(opts: {
   engine: RollupEngine;
   ctx: TenantCtx;
   dataSource: DataSource;
@@ -67,5 +67,4 @@ declare function rebuildCanonicalDailyResumable(opts: {
   windowsTotal: number;
   windowsBuilt: number;
   rowsWritten: number;
-}>;
-export { queryCanonicalDailyRollup, queryCanonicalVariantsRollup, rebuildCanonicalDailyResumable };
+}>;

package/dist/rollups/core.d.mts

@@ -4,7 +4,7 @@ import { EngineError } from "../errors.mjs";
 import "../contracts.mjs";
 import { TenantCtx } from "@gscdump/contracts";
 import { SearchType } from "gscdump/query";
-interface RollupCtx extends TenantCtx {
+export interface RollupCtx extends TenantCtx {
   /** When the rollup was built. Stamped into payload + filename. */
   builtAt: number;
 }
@@ -12,7 +12,7 @@ interface RollupCtx extends TenantCtx {
  * Tenant-scoped engine surface a rollup builder needs. Subset of
  * `StorageEngine.runSQL` so rollups stay testable without a full engine.
  */
-interface RollupEngine {
+export interface RollupEngine {
   runSQL: (opts: {
     ctx: TenantCtx;
     fileSets: Record<string, FileSetRef>;
@@ -50,7 +50,7 @@ interface RollupEngine {
  * from entity stores via `dataSource`, returning a JSON-serializable payload
  * that the runner timestamps + writes.
  */
-interface RollupDef {
+export interface RollupDef {
   id: string;
   /**
    * Window in days the rollup covers. `null` means full history. Used by
@@ -114,14 +114,14 @@ interface RollupDef {
  * Parquet rollups write this envelope as a sidecar whose `payload` points at
  * the co-located `.parquet` object via `{ parquetKey, rowCount }`.
  */
-interface RollupEnvelope<T = unknown> {
+export interface RollupEnvelope<T = unknown> {
   version: 1;
   id: string;
   builtAt: number;
   windowDays: number | null;
   payload: T;
 }
-interface ParquetRollupPointer {
+export interface ParquetRollupPointer {
   parquetKey: string;
   rowCount: number;
   /**
@@ -134,9 +134,9 @@ interface ParquetRollupPointer {
    */
   parquetKeys?: string[];
 }
-declare function rollupKey(ctx: TenantCtx, id: string, builtAt: number, searchType?: SearchType): string;
-declare function rollupParquetKey(ctx: TenantCtx, id: string, builtAt: number, searchType?: SearchType): string;
-interface RollupBucket {
+export declare function rollupKey(ctx: TenantCtx, id: string, builtAt: number, searchType?: SearchType): string;
+export declare function rollupParquetKey(ctx: TenantCtx, id: string, builtAt: number, searchType?: SearchType): string;
+export interface RollupBucket {
   list: (opts: {
     prefix: string;
     cursor?: string;
@@ -151,8 +151,8 @@ interface RollupBucket {
     text: () => Promise<string>;
   } | null>;
 }
-declare function readLatestRollup<T = unknown>(bucket: RollupBucket, ctx: TenantCtx, id: string, searchType?: SearchType): Promise<RollupEnvelope<T> | null>;
-interface RebuildRollupsOptions {
+export declare function readLatestRollup<T = unknown>(bucket: RollupBucket, ctx: TenantCtx, id: string, searchType?: SearchType): Promise<RollupEnvelope<T> | null>;
+export interface RebuildRollupsOptions {
   engine: RollupEngine;
   dataSource: DataSource;
   ctx: TenantCtx;
@@ -178,7 +178,7 @@ interface RebuildRollupsOptions {
    */
   dataEndDate?: string;
 }
-interface RebuildRollupResult {
+export interface RebuildRollupResult {
   id: string;
   /** JSON envelope key. For parquet rollups this is the sidecar pointer. */
   objectKey: string;
@@ -197,5 +197,4 @@ interface RebuildRollupResult {
    */
   error?: EngineError;
 }
-declare function rebuildRollups(opts: RebuildRollupsOptions): Promise<RebuildRollupResult[]>;
-export { ParquetRollupPointer, RebuildRollupResult, RebuildRollupsOptions, RollupBucket, RollupCtx, RollupDef, RollupEngine, RollupEnvelope, readLatestRollup, rebuildRollups, rollupKey, rollupParquetKey };
+export declare function rebuildRollups(opts: RebuildRollupsOptions): Promise<RebuildRollupResult[]>;

package/dist/rollups/defaults.d.mts

@@ -1,5 +1,5 @@
 import { RollupDef } from "./core.mjs";
-declare const DEFAULT_ROLLUPS: readonly RollupDef[];
+export declare const DEFAULT_ROLLUPS: readonly RollupDef[];
 /**
  * Canonical-primary rollups (ADR-0017 / ADR-0018). Opt-in — kept out of
  * `DEFAULT_ROLLUPS` because they only pay off once the consumer queries by
@@ -7,5 +7,4 @@ declare const DEFAULT_ROLLUPS: readonly RollupDef[];
  * `canonicalSource`). Hosts opt in by concatenating these onto their def list
  * (CLI: `gscdump rollups --with-canonical`).
  */
-declare const CANONICAL_ROLLUPS: readonly RollupDef[];
-export { CANONICAL_ROLLUPS, DEFAULT_ROLLUPS };
+export declare const CANONICAL_ROLLUPS: readonly RollupDef[];

package/dist/rollups/hourly.d.mts

@@ -18,7 +18,7 @@ import { SearchType } from "gscdump/query";
  * existing dashboard queries (which read `pages`) see the rolled-up day
  * transparently.
  */
-interface RebuildDailyFromHourlyOptions {
+export interface RebuildDailyFromHourlyOptions {
   engine: RollupEngine & {
     writeDay: (scope: TenantCtx & {
       table: TableTypeName;
@@ -32,7 +32,6 @@ interface RebuildDailyFromHourlyOptions {
   searchType: 'discover';
 }
 type TableTypeName = import('@gscdump/contracts').TableName;
-declare function rebuildDailyFromHourly(opts: RebuildDailyFromHourlyOptions): Promise<{
+export declare function rebuildDailyFromHourly(opts: RebuildDailyFromHourlyOptions): Promise<{
   rowsWritten: number;
-}>;
-export { RebuildDailyFromHourlyOptions, rebuildDailyFromHourly };
+}>;

package/dist/rollups/indexing.d.mts

@@ -9,7 +9,7 @@ import { RollupDef } from "./core.mjs";
  * Safe no-op when the entity store is empty: returns `{ totals: {...}, days: [] }`
  * so downstream readers don't have to special-case first-run sites.
  */
-declare const indexingMetadataRollup: RollupDef;
+export declare const indexingMetadataRollup: RollupDef;
 /**
  * Indexing-API health by day: per `inspectedAt` date, counts of indexed,
  * soft-404, redirect, not-found, mobile passes, rich-results passes, and
@@ -19,24 +19,23 @@ declare const indexingMetadataRollup: RollupDef;
  * Empty-payload no-op when the sidecar URI is unavailable (in-memory
  * `DataSource`, or before `materialize` has run).
  */
-declare const indexingHealthRollup: RollupDef;
+export declare const indexingHealthRollup: RollupDef;
 /**
  * Per-day index-percent: ratio of (sitemap URLs that received GSC clicks on
  * that date) / (total published sitemap URLs). The published generation
  * manifest supplies the exact immutable feed bases. No storage listing or
  * derived projection participates in authority.
  */
-declare const indexPercentRollup: RollupDef;
+export declare const indexPercentRollup: RollupDef;
 /**
  * Sitemap-health history derives exclusively from published complete
  * generations. The newest generation observed on each day is retained.
  */
-declare const sitemapHealthRollup: RollupDef;
+export declare const sitemapHealthRollup: RollupDef;
 /**
  * Trailing-28-day sitemap URL changes: per-day per-feedpath {added, removed}
  * counts plus rolling top-200 added and removed URLs. Streams from
  * retained `SitemapReadStore.loadEvents()` history. State compaction cannot
  * erase analytics input; memory scales independently of total site state.
  */
-declare const sitemapChanges28dRollup: RollupDef;
-export { indexPercentRollup, indexingHealthRollup, indexingMetadataRollup, sitemapChanges28dRollup, sitemapHealthRollup };
+export declare const sitemapChanges28dRollup: RollupDef;