@gscdump/engine 1.4.0 → 1.4.1

package/dist/analyzer/define.d.mts

@@ -0,0 +1,48 @@
+import { AnalysisParams } from "../analysis-types.mjs";
+import { FileSet } from "../source/source-types.mjs";
+import { Analyzer, BuildContext, RequiredCapability, SqlExtraQuery } from "./types.mjs";
+import { BuilderState } from "gscdump/query";
+interface SqlPlanSpec {
+  sql: string;
+  params: unknown[];
+  current: FileSet;
+  previous?: FileSet;
+  extraFiles?: Record<string, FileSet>;
+  extraQueries?: SqlExtraQuery[];
+}
+interface ReduceCtx<InputRow> {
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name` (SQL path only). */
+  extras?: Record<string, InputRow[]>;
+}
+type Reducer<Params, InputRow, Result> = (rows: InputRow[] | Record<string, InputRow[]>, params: Params, ctx: ReduceCtx<InputRow>) => {
+  results: Result;
+  meta?: Record<string, unknown>;
+};
+interface DefineAnalyzerOptions<Params extends AnalysisParams, InputRow, Result> {
+  id: string;
+  /**
+   * Shared reducer used by both SQL and row paths. Use this when the
+   * post-aggregation row count is small and filter/sort/derive can live in
+   * one place. Mutually exclusive with `reduceSql` / `reduceRows`.
+   */
+  reduce?: Reducer<Params, InputRow, Result>;
+  /** SQL-only reducer. Required when `buildSql` is set without `reduce`. */
+  reduceSql?: Reducer<Params, InputRow, Result>;
+  /** Row-only reducer. Required when `buildRows` is set without `reduce`. */
+  reduceRows?: Reducer<Params, InputRow, Result>;
+  /** SQL plan builder. Omit if the analyzer has no SQL path. */
+  buildSql?: (params: Params, ctx: BuildContext) => SqlPlanSpec;
+  /** Row plan builder. Omit if the analyzer has no row path. */
+  buildRows?: (params: Params, ctx: BuildContext) => Record<string, BuilderState>;
+  /** Capabilities required by the SQL plan. Defaults to `['executeSql', 'fileSets']`. */
+  sqlRequires?: readonly RequiredCapability[];
+  /** Capabilities required by the row plan. Defaults to `[]`. */
+  rowsRequires?: readonly RequiredCapability[];
+}
+interface DefinedAnalyzer {
+  id: string;
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+declare function defineAnalyzer<Params extends AnalysisParams, InputRow, Result>(opts: DefineAnalyzerOptions<Params, InputRow, Result>): DefinedAnalyzer;
+export { DefineAnalyzerOptions, DefinedAnalyzer, ReduceCtx, Reducer, SqlPlanSpec, defineAnalyzer };

package/dist/analyzer/define.mjs

@@ -0,0 +1,60 @@
+const DEFAULT_SQL_REQUIRES = ["executeSql", "fileSets"];
+function defineAnalyzer(opts) {
+	const { id, reduce, reduceSql, reduceRows, buildSql, buildRows, sqlRequires = DEFAULT_SQL_REQUIRES, rowsRequires = [] } = opts;
+	const sqlReducer = reduceSql ?? reduce;
+	const rowsReducer = reduceRows ?? reduce;
+	if (buildSql && !sqlReducer) throw new Error(`defineAnalyzer(${id}): buildSql requires reduce or reduceSql`);
+	if (buildRows && !rowsReducer) throw new Error(`defineAnalyzer(${id}): buildRows requires reduce or reduceRows`);
+	const wrap = (fn) => (rows, params, ctx) => {
+		return fn(Array.isArray(rows) ? rows : pickSingle(rows) ?? rows, params, ctx);
+	};
+	return {
+		id,
+		sql: buildSql && sqlReducer ? {
+			id,
+			requires: sqlRequires,
+			build(params, ctx = {}) {
+				const spec = buildSql(params, ctx);
+				return {
+					kind: "sql",
+					sql: spec.sql,
+					params: spec.params,
+					current: spec.current,
+					previous: spec.previous,
+					extraFiles: spec.extraFiles,
+					extraQueries: spec.extraQueries
+				};
+			},
+			reduce(rows, ctx) {
+				const { results, meta } = wrap(sqlReducer)(rows, ctx.params, { extras: ctx.extras });
+				return {
+					results,
+					meta
+				};
+			}
+		} : void 0,
+		rows: buildRows && rowsReducer ? {
+			id,
+			requires: rowsRequires,
+			build(params, ctx = {}) {
+				const queries = buildRows(params, ctx);
+				return {
+					kind: "rows",
+					queries: Object.fromEntries(Object.entries(queries).map(([k, state]) => [k, { state }]))
+				};
+			},
+			reduce(rows, ctx) {
+				const { results, meta } = wrap(rowsReducer)(rows, ctx.params, {});
+				return {
+					results,
+					meta
+				};
+			}
+		} : void 0
+	};
+}
+function pickSingle(rows) {
+	const keys = Object.keys(rows);
+	return keys.length === 1 ? rows[keys[0]] : void 0;
+}
+export { defineAnalyzer };

package/dist/analyzer/dispatch.d.mts

@@ -0,0 +1,17 @@
+import { AnalysisParams, AnalysisResult } from "../analysis-types.mjs";
+import { AnalysisQuerySource } from "../source/source-types.mjs";
+import { RequiredCapability } from "./types.mjs";
+import { EngineError } from "../errors.mjs";
+import { AnalyzerRegistry } from "./registry.mjs";
+declare class AnalyzerCapabilityError extends Error {
+  readonly tool: string;
+  readonly missing: readonly RequiredCapability[];
+  readonly engineError: EngineError;
+  constructor(tool: string, missing: readonly RequiredCapability[]);
+}
+/**
+ * Run an analyzer against a generic `AnalysisQuerySource`. The registry is
+ * an explicit parameter — callers build one via `createAnalyzerRegistry`.
+ */
+declare function runAnalyzerFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
+export { AnalyzerCapabilityError, runAnalyzerFromSource };

package/dist/analyzer/index.d.mts

@@ -1,15 +1,5 @@
-import { AnalysisParams, AnalysisResult } from "../_chunks/analysis-types.mjs";
-import { AnalysisQuerySource, Analyzer, AnalyzerRegistry, AnalyzerRegistryInit, AnalyzerVariants, BuildContext, DefineAnalyzerOptions, DefinedAnalyzer, Plan, ReduceContext, ReduceCtx, Reducer, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, SqlPlanSpec, TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, requireAdapter } from "../_chunks/registry.mjs";
-import { EngineError } from "../_chunks/errors.mjs";
-declare class AnalyzerCapabilityError extends Error {
-  readonly tool: string;
-  readonly missing: readonly RequiredCapability[];
-  readonly engineError: EngineError;
-  constructor(tool: string, missing: readonly RequiredCapability[]);
-}
-/**
- * Run an analyzer against a generic `AnalysisQuerySource`. The registry is
- * an explicit parameter — callers build one via `createAnalyzerRegistry`.
- */
-declare function runAnalyzerFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
+import { Analyzer, BuildContext, Plan, ReduceContext, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, TypedRowQuery, requireAdapter } from "./types.mjs";
+import { DefineAnalyzerOptions, DefinedAnalyzer, ReduceCtx, Reducer, SqlPlanSpec, defineAnalyzer } from "./define.mjs";
+import { AnalyzerRegistry, AnalyzerRegistryInit, AnalyzerVariants, createAnalyzerRegistry } from "./registry.mjs";
+import { AnalyzerCapabilityError, runAnalyzerFromSource } from "./dispatch.mjs";
 export { type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerVariants, type BuildContext, type DefineAnalyzerOptions, type DefinedAnalyzer, type Plan, type ReduceContext, type ReduceCtx, type Reducer, type RequiredCapability, type RowQueriesPlan, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type TypedRowQuery, createAnalyzerRegistry, defineAnalyzer, requireAdapter, runAnalyzerFromSource };

package/dist/analyzer/index.mjs

@@ -1,113 +1,5 @@
-import { AnalyzerCapabilityError, runAnalyzerFromSource } from "../_chunks/dispatch.mjs";
-const DEFAULT_SQL_REQUIRES = ["executeSql", "fileSets"];
-function defineAnalyzer(opts) {
-	const { id, reduce, reduceSql, reduceRows, buildSql, buildRows, sqlRequires = DEFAULT_SQL_REQUIRES, rowsRequires = [] } = opts;
-	const sqlReducer = reduceSql ?? reduce;
-	const rowsReducer = reduceRows ?? reduce;
-	if (buildSql && !sqlReducer) throw new Error(`defineAnalyzer(${id}): buildSql requires reduce or reduceSql`);
-	if (buildRows && !rowsReducer) throw new Error(`defineAnalyzer(${id}): buildRows requires reduce or reduceRows`);
-	const wrap = (fn) => (rows, params, ctx) => {
-		return fn(Array.isArray(rows) ? rows : pickSingle(rows) ?? rows, params, ctx);
-	};
-	return {
-		id,
-		sql: buildSql && sqlReducer ? {
-			id,
-			requires: sqlRequires,
-			build(params, ctx = {}) {
-				const spec = buildSql(params, ctx);
-				return {
-					kind: "sql",
-					sql: spec.sql,
-					params: spec.params,
-					current: spec.current,
-					previous: spec.previous,
-					extraFiles: spec.extraFiles,
-					extraQueries: spec.extraQueries
-				};
-			},
-			reduce(rows, ctx) {
-				const { results, meta } = wrap(sqlReducer)(rows, ctx.params, { extras: ctx.extras });
-				return {
-					results,
-					meta
-				};
-			}
-		} : void 0,
-		rows: buildRows && rowsReducer ? {
-			id,
-			requires: rowsRequires,
-			build(params, ctx = {}) {
-				const queries = buildRows(params, ctx);
-				return {
-					kind: "rows",
-					queries: Object.fromEntries(Object.entries(queries).map(([k, state]) => [k, { state }]))
-				};
-			},
-			reduce(rows, ctx) {
-				const { results, meta } = wrap(rowsReducer)(rows, ctx.params, {});
-				return {
-					results,
-					meta
-				};
-			}
-		} : void 0
-	};
-}
-function pickSingle(rows) {
-	const keys = Object.keys(rows);
-	return keys.length === 1 ? rows[keys[0]] : void 0;
-}
-function createAnalyzerRegistry(init = {}) {
-	const byId = /* @__PURE__ */ new Map();
-	for (const d of init.defined ?? []) {
-		const entry = byId.get(d.id) ?? {};
-		if (d.sql) entry.sql = d.sql;
-		if (d.rows) entry.rows = d.rows;
-		byId.set(d.id, entry);
-	}
-	for (const a of init.rows ?? []) {
-		const entry = byId.get(a.id) ?? {};
-		entry.rows = a;
-		byId.set(a.id, entry);
-	}
-	for (const a of init.sql ?? []) {
-		const entry = byId.get(a.id) ?? {};
-		entry.sql = a;
-		byId.set(a.id, entry);
-	}
-	const listAnalyzerIds = () => [...byId.keys()].sort();
-	const getAnalyzerVariants = (id) => byId.get(id);
-	const resolveAnalyzer = (id, sourceSupportsSql) => {
-		const variants = byId.get(id);
-		if (!variants) return void 0;
-		if (sourceSupportsSql) return variants.sql ?? variants.rows;
-		return variants.rows;
-	};
-	const listAnalyzersFor = (sourceSupportsSql) => {
-		const out = [];
-		for (const id of listAnalyzerIds()) {
-			const a = resolveAnalyzer(id, sourceSupportsSql);
-			if (a) out.push(a);
-		}
-		return out;
-	};
-	const listAnalyzerIdsFor = (source) => {
-		const sourceSupportsSql = typeof source.executeSql === "function";
-		const out = [];
-		for (const id of listAnalyzerIds()) if (resolveAnalyzer(id, sourceSupportsSql)) out.push(id);
-		return out;
-	};
-	return {
-		listAnalyzerIds,
-		getAnalyzerVariants,
-		resolveAnalyzer,
-		listAnalyzersFor,
-		listAnalyzerIdsFor
-	};
-}
-function requireAdapter(ctx, analyzerId) {
-	if (!ctx.adapter) throw new Error(`analyzer "${analyzerId}": BuildContext.adapter missing — declare 'adapter' in sqlRequires/rowsRequires`);
-	return ctx.adapter;
-}
+import { defineAnalyzer } from "./define.mjs";
+import { AnalyzerCapabilityError, runAnalyzerFromSource } from "./dispatch.mjs";
+import { createAnalyzerRegistry } from "./registry.mjs";
+import { requireAdapter } from "./types.mjs";
 export { AnalyzerCapabilityError, createAnalyzerRegistry, defineAnalyzer, requireAdapter, runAnalyzerFromSource };

package/dist/analyzer/registry.d.mts

@@ -0,0 +1,33 @@
+import { Analyzer } from "./types.mjs";
+import { DefinedAnalyzer } from "./define.mjs";
+interface AnalyzerVariants {
+  sql?: Analyzer;
+  rows?: Analyzer;
+}
+interface AnalyzerRegistryInit {
+  /**
+   * Preferred for in-tree composition: pass `DefinedAnalyzer[]` directly so
+   * SQL/row variants can never drift apart from their `defineAnalyzer` site.
+   */
+  defined?: readonly DefinedAnalyzer[];
+  /** Flat-array path retained for narrow tree-shaken registry composition. */
+  rows?: readonly Analyzer[];
+  /** Flat-array path retained for narrow tree-shaken registry composition. */
+  sql?: readonly Analyzer[];
+}
+interface AnalyzerRegistry {
+  listAnalyzerIds: () => readonly string[];
+  getAnalyzerVariants: (id: string) => AnalyzerVariants | undefined;
+  resolveAnalyzer: (id: string, sourceSupportsSql: boolean) => Analyzer | undefined;
+  listAnalyzersFor: (sourceSupportsSql: boolean) => readonly Analyzer[];
+  listAnalyzerIdsFor: (source: {
+    executeSql?: unknown;
+  }) => readonly string[];
+}
+/**
+ * Build an immutable registry from collections of row / SQL analyzers.
+ * No global state; call this once per logical use (typically at startup
+ * or per-request in a worker).
+ */
+declare function createAnalyzerRegistry(init?: AnalyzerRegistryInit): AnalyzerRegistry;
+export { AnalyzerRegistry, AnalyzerRegistryInit, AnalyzerVariants, createAnalyzerRegistry };

package/dist/analyzer/registry.mjs

@@ -0,0 +1,49 @@
+function createAnalyzerRegistry(init = {}) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const d of init.defined ?? []) {
+		const entry = byId.get(d.id) ?? {};
+		if (d.sql) entry.sql = d.sql;
+		if (d.rows) entry.rows = d.rows;
+		byId.set(d.id, entry);
+	}
+	for (const a of init.rows ?? []) {
+		const entry = byId.get(a.id) ?? {};
+		entry.rows = a;
+		byId.set(a.id, entry);
+	}
+	for (const a of init.sql ?? []) {
+		const entry = byId.get(a.id) ?? {};
+		entry.sql = a;
+		byId.set(a.id, entry);
+	}
+	const listAnalyzerIds = () => [...byId.keys()].sort();
+	const getAnalyzerVariants = (id) => byId.get(id);
+	const resolveAnalyzer = (id, sourceSupportsSql) => {
+		const variants = byId.get(id);
+		if (!variants) return void 0;
+		if (sourceSupportsSql) return variants.sql ?? variants.rows;
+		return variants.rows;
+	};
+	const listAnalyzersFor = (sourceSupportsSql) => {
+		const out = [];
+		for (const id of listAnalyzerIds()) {
+			const a = resolveAnalyzer(id, sourceSupportsSql);
+			if (a) out.push(a);
+		}
+		return out;
+	};
+	const listAnalyzerIdsFor = (source) => {
+		const sourceSupportsSql = typeof source.executeSql === "function";
+		const out = [];
+		for (const id of listAnalyzerIds()) if (resolveAnalyzer(id, sourceSupportsSql)) out.push(id);
+		return out;
+	};
+	return {
+		listAnalyzerIds,
+		getAnalyzerVariants,
+		resolveAnalyzer,
+		listAnalyzersFor,
+		listAnalyzerIdsFor
+	};
+}
+export { createAnalyzerRegistry };

package/dist/analyzer/types.d.mts

@@ -0,0 +1,95 @@
+import { Row } from "../storage.mjs";
+import { AnalysisParams } from "../analysis-types.mjs";
+import { ResolverAdapter } from "../resolver/types.mjs";
+import { FileSet, SourceCapabilities } from "../source/source-types.mjs";
+import { BuilderState } from "gscdump/query";
+/**
+ * Capabilities a Plan may require of its host. Dispatch matches `requires`
+ * against the source's declared `capabilities` (and the presence of
+ * `executeSql`) and rejects mismatches.
+ *
+ * `'executeSql'` checks for the method on the source; the rest are flag keys
+ * on `SourceCapabilities`. Single source of truth — adding a new capability
+ * is one line in `SourceCapabilities`.
+ */
+type RequiredCapability = 'executeSql' | keyof SourceCapabilities;
+interface SqlExtraQuery {
+  name: string;
+  sql: string;
+  params: unknown[];
+}
+/**
+ * SQL-native plan: SQL string + placeholders, with optional extra file sets
+ * and follow-up queries.
+ */
+interface SqlPlan {
+  kind: 'sql';
+  sql: string;
+  params: unknown[];
+  current: FileSet;
+  previous?: FileSet;
+  extraFiles?: Record<string, FileSet>;
+  extraQueries?: SqlExtraQuery[];
+}
+interface TypedRowQuery<T extends Row = Row> {
+  state: BuilderState;
+  /** Optional type tag for downstream narrowing. */
+  rowType?: (row: Row) => T;
+}
+/**
+ * Row-queries plan: a named set of typed `BuilderState` queries. A portable
+ * dispatcher runs each against a source's `queryRows` and hands the row
+ * collection to `reduce`.
+ */
+interface RowQueriesPlan {
+  kind: 'rows';
+  queries: Record<string, TypedRowQuery>;
+}
+type Plan = SqlPlan | RowQueriesPlan;
+/**
+ * Plan-build context. Surfaced from the source at dispatch time so analyzers
+ * that compose SQL from a typed `BuilderState` can pick up the right dialect
+ * adapter without importing one directly. Most SQL analyzers emit static SQL
+ * and ignore this; only the BuilderState-driven `data-query` / `data-detail`
+ * analyzers consume it today.
+ *
+ * `adapter` is optional on the type; analyzers that need it should call
+ * `requireAdapter(ctx, id)` rather than non-null-asserting. Capability
+ * declaration (`'adapter'` in `requires`) is the runtime guarantee; the
+ * helper makes the failure mode loud if the contract is broken.
+ */
+interface BuildContext {
+  adapter?: ResolverAdapter<any>;
+  siteId?: string | number;
+}
+/**
+ * Throw a uniform error if a SQL analyzer declared the `'adapter'` capability
+ * but the dispatcher handed it a context without one. Centralizes the assert
+ * so analyzers don't repeat `ctx.adapter!` with explanatory comments.
+ */
+declare function requireAdapter(ctx: BuildContext, analyzerId: string): ResolverAdapter<any>;
+interface ReduceContext<TRow extends Row = Row> {
+  params: AnalysisParams;
+  /** Extra SQL-query results keyed by `SqlExtraQuery.name`. */
+  extras?: Record<string, TRow[]>;
+}
+/**
+ * Unified analyzer contract. `TRow` lets authors narrow from the default
+ * `Row = Record<string, unknown>` to a typed row shape (e.g. `QueriesRow`)
+ * when their reducer assumes specific columns exist — catches drift between
+ * `build` (SELECT list) and `reduce` (column access) at compile time.
+ */
+interface Analyzer<P extends AnalysisParams = AnalysisParams, R = unknown, TRow extends Row = Row> {
+  /** Stable tool id (e.g. `striking-distance`, `opportunity`). */
+  id: string;
+  /** Capabilities a host source must provide. */
+  requires: readonly RequiredCapability[];
+  /** Pure: params → plan. Snapshot-testable. `ctx` carries the source's dialect adapter when one is available. */
+  build: (params: P, ctx?: BuildContext) => Plan;
+  /** Pure: rows + context → typed result + meta. */
+  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
+    results: R;
+    meta?: Record<string, unknown>;
+  };
+}
+export { Analyzer, BuildContext, Plan, ReduceContext, RequiredCapability, RowQueriesPlan, SqlExtraQuery, SqlPlan, TypedRowQuery, requireAdapter };

package/dist/analyzer/types.mjs

@@ -0,0 +1,5 @@
+function requireAdapter(ctx, analyzerId) {
+	if (!ctx.adapter) throw new Error(`analyzer "${analyzerId}": BuildContext.adapter missing — declare 'adapter' in sqlRequires/rowsRequires`);
+	return ctx.adapter;
+}
+export { requireAdapter };

package/dist/coerce.d.mts

@@ -0,0 +1,4 @@
+import { Row } from "@gscdump/contracts";
+declare function coerceRow(row: Row): Row;
+declare function coerceRows(rows: readonly Row[]): Row[];
+export { coerceRow, coerceRows };

package/dist/compaction.d.mts

@@ -0,0 +1,14 @@
+import "./storage.mjs";
+/**
+ * Per-tier age threshold in days. Default ladder collapses on these gates:
+ * - raw → d7 once a daily file is older than `raw` days (default 7).
+ * - d7 → d30 once the entire weekly bucket sits behind `d7` days (default 30).
+ * - d30 → d90 once the entire monthly bucket sits behind `d30` days (default 90).
+ */
+interface CompactionThresholds {
+  raw?: number;
+  d7?: number;
+  d30?: number;
+}
+declare function enumeratePartitions(startDate: string, endDate: string): string[];
+export { CompactionThresholds, enumeratePartitions };

package/dist/{_chunks/parquet-plan.mjs → compaction.mjs}

@@ -1,8 +1,6 @@
 import { dayPartition, inferSearchType, mondayOfWeek, monthPartition, objectKey, quarterOfMonth, quarterPartition, weekPartition } from "./layout.mjs";
-import { currentSchemaVersion, dimensionToColumn } from "./schema.mjs";
-import { METRIC_EXPR, escapeLike, topLevelPagePredicateSql } from "../sql-fragments.mjs";
+import { currentSchemaVersion } from "./schema.mjs";
 import { MS_PER_DAY } from "gscdump/dates";
-import { buildLogicalPlan } from "gscdump/query/plan";
 const DAILY_PARTITION_RE = /^daily\/(\d{4}-\d{2}-\d{2})$/;
 const WEEKLY_PARTITION_RE = /^weekly\/(\d{4}-\d{2}-\d{2})$/;
 const MONTHLY_PARTITION_RE = /^monthly\/(\d{4}-\d{2})$/;
@@ -247,138 +245,4 @@ function quarterEndMs(quarter) {
 	const q = Number(qStr);
 	return Date.UTC(y, q * 3, 0, 23, 59, 59, 999);
 }
-const FILES_PLACEHOLDER = "{{FILES}}";
-function buildDimensionWhere(filters, table) {
-	const clauses = [];
-	const params = [];
-	for (const filter of filters) {
-		const column = dimensionToColumn(filter.dimension, table);
-		switch (filter.operator) {
-			case "equals":
-				clauses.push(`${column} = ?`);
-				params.push(filter.expression);
-				break;
-			case "notEquals":
-				clauses.push(`${column} != ?`);
-				params.push(filter.expression);
-				break;
-			case "contains":
-				clauses.push(`${column} LIKE ? ESCAPE '\\'`);
-				params.push(`%${escapeLike(filter.expression)}%`);
-				break;
-			case "notContains":
-				clauses.push(`${column} NOT LIKE ? ESCAPE '\\'`);
-				params.push(`%${escapeLike(filter.expression)}%`);
-				break;
-			case "includingRegex":
-				clauses.push(`regexp_matches(${column}, ?)`);
-				params.push(filter.expression);
-				break;
-			case "excludingRegex":
-				clauses.push(`NOT regexp_matches(${column}, ?)`);
-				params.push(filter.expression);
-				break;
-		}
-	}
-	return {
-		clause: clauses.join(" AND "),
-		params
-	};
-}
-function buildTopLevelWhere(plan, table) {
-	if (!plan.specialFilters.topLevel) return "";
-	return topLevelPagePredicateSql(dimensionToColumn("page", table));
-}
-function buildHaving(filters) {
-	if (filters.length === 0) return {
-		clause: "",
-		params: []
-	};
-	const clauses = [];
-	const params = [];
-	for (const filter of filters) {
-		const expr = METRIC_EXPR[filter.metric];
-		switch (filter.operator) {
-			case "metricGte":
-				clauses.push(`${expr} >= ?`);
-				params.push(filter.expression);
-				break;
-			case "metricGt":
-				clauses.push(`${expr} > ?`);
-				params.push(filter.expression);
-				break;
-			case "metricLte":
-				clauses.push(`${expr} <= ?`);
-				params.push(filter.expression);
-				break;
-			case "metricLt":
-				clauses.push(`${expr} < ?`);
-				params.push(filter.expression);
-				break;
-			case "metricBetween":
-				clauses.push(`${expr} >= ? AND ${expr} <= ?`);
-				params.push(filter.expression, filter.expression2 ?? filter.expression);
-				break;
-		}
-	}
-	return {
-		clause: clauses.length > 0 ? `HAVING ${clauses.join(" AND ")}` : "",
-		params
-	};
-}
-function compileLogicalQueryPlan(plan, table = plan.dataset) {
-	const partitions = enumeratePartitions(plan.dateRange.startDate, plan.dateRange.endDate);
-	const metricSelects = plan.metrics.map((metric) => `${METRIC_EXPR[metric]} AS ${metric}`);
-	const dimSelects = plan.groupByDimensions.map((dimension) => {
-		const column = dimensionToColumn(dimension, table);
-		return column !== dimension ? `${column} AS ${dimension}` : dimension;
-	});
-	const whereClauses = ["date >= ?", "date <= ?"];
-	const whereParams = [plan.dateRange.startDate, plan.dateRange.endDate];
-	const dimWhere = buildDimensionWhere(plan.dimensionFilters, table);
-	if (dimWhere.clause) {
-		whereClauses.push(dimWhere.clause);
-		whereParams.push(...dimWhere.params);
-	}
-	const topLevelClause = buildTopLevelWhere(plan, table);
-	if (topLevelClause) whereClauses.push(topLevelClause);
-	const having = buildHaving(plan.metricFilters);
-	const groupByCols = [...plan.groupByDimensions.map((dimension) => dimensionToColumn(dimension, table)), ...plan.hasDate ? ["date"] : []];
-	const groupBy = groupByCols.length > 0 ? `GROUP BY ${groupByCols.join(", ")}` : "";
-	const orderBy = plan.orderBy ? `ORDER BY ${plan.orderBy.column} ${plan.orderBy.dir.toUpperCase()}` : "ORDER BY clicks DESC";
-	const limit = `LIMIT ${plan.rowLimit ?? 1e3}`;
-	const offset = plan.startRow ? `OFFSET ${plan.startRow}` : "";
-	return {
-		sql: [
-			`SELECT ${[
-				...dimSelects,
-				...plan.hasDate ? ["date"] : [],
-				...metricSelects
-			].join(", ")}`,
-			`FROM read_parquet(${FILES_PLACEHOLDER}, union_by_name = true)`,
-			`WHERE ${whereClauses.join(" AND ")}`,
-			groupBy,
-			having.clause,
-			orderBy,
-			limit,
-			offset
-		].filter(Boolean).join(" ").replace(/\s+/g, " ").trim(),
-		params: [...whereParams, ...having.params],
-		partitions,
-		table,
-		filesPlaceholder: FILES_PLACEHOLDER
-	};
-}
-function resolveParquetSQL(state, table) {
-	const plan = buildLogicalPlan(state, { regex: true });
-	return compileLogicalQueryPlan(plan, table ?? plan.dataset);
-}
-function fileList(keys) {
-	return keys.length === 0 ? "[]" : `[${keys.map((key) => `'${key.replace(/'/g, "''")}'`).join(", ")}]`;
-}
-function substituteNamedFiles(sql, sets) {
-	let out = sql;
-	for (const [name, keys] of Object.entries(sets)) out = out.replace(new RegExp(`\\{\\{${name}\\}\\}`, "g"), fileList(keys));
-	return out;
-}
-export { FILES_PLACEHOLDER, compactTieredImpl, compileLogicalQueryPlan, dedupeOverlappingTiers, enumeratePartitions, resolveParquetSQL, splitOverlappingTiers, substituteNamedFiles };
+export { compactTieredImpl, dedupeOverlappingTiers, enumeratePartitions, splitOverlappingTiers };

package/dist/contracts.d.mts

@@ -1,3 +1,2 @@
-import { CodecCtx, CompactionTier, DataSource, EngineOptions, FileSetRef, GcCtx, ListLiveFilter, LockScope, ManifestEntry, ManifestStore, ParquetCodec, QueryCtx, QueryExecuteOptions, QueryExecuteResult, QueryExecutor, QueryResult, Row, RunSQLOptions, SearchType, StorageEngine, SyncState, SyncStateDetail, SyncStateFilter, SyncStateKind, SyncStateScope, TableName, TenantCtx, Watermark, WatermarkFilter, WatermarkScope, WriteCtx, WriteResult } from "./_chunks/storage.mjs";
-import "./_chunks/contracts.mjs";
+import { CodecCtx, CompactionTier, DataSource, EngineOptions, FileSetRef, GcCtx, ListLiveFilter, LockScope, ManifestEntry, ManifestStore, ParquetCodec, QueryCtx, QueryExecuteOptions, QueryExecuteResult, QueryExecutor, QueryResult, Row, RunSQLOptions, SearchType, StorageEngine, SyncState, SyncStateDetail, SyncStateFilter, SyncStateKind, SyncStateScope, TableName, TenantCtx, Watermark, WatermarkFilter, WatermarkScope, WriteCtx, WriteResult } from "./storage.mjs";
 export type { CodecCtx, CompactionTier, DataSource, EngineOptions, FileSetRef, GcCtx, ListLiveFilter, LockScope, ManifestEntry, ManifestStore, ParquetCodec, QueryCtx, QueryExecuteOptions, QueryExecuteResult, QueryExecutor, QueryResult, Row, RunSQLOptions, SearchType, StorageEngine, SyncState, SyncStateDetail, SyncStateFilter, SyncStateKind, SyncStateScope, TableName, TenantCtx, Watermark, WatermarkFilter, WatermarkScope, WriteCtx, WriteResult };

package/dist/{_chunks/schema.d.mts → drizzle-schema.d.mts}

@@ -1,4 +1,4 @@
-import { ColumnDef, ColumnType, Row, TableName, TableSchema, TableSchema as TableSchema$1 } from "@gscdump/contracts";
+import { TableName } from "@gscdump/contracts";
 declare const pages: import("drizzle-orm/pg-core").PgTableWithColumns<{
   name: "pages";
   schema: undefined;
@@ -2113,36 +2113,4 @@ declare const TABLE_METADATA: Record<TableName, {
   clusterKey: string[];
   version: number;
 }>;
-declare const SCHEMAS: Record<TableName, TableSchema>;
-declare function currentSchemaVersion(table: TableName): number;
-/**
- * DATE column names for a table. The single schema-derived source every read
- * path uses to build the legacy-VARCHAR date canonicalization (see
- * `dateReplaceClause` in `./sql-fragments`), so the engine codec and the CLI
- * `dump`/`export` commands agree on which columns to cast.
- */
-declare function dateColumnsFor(table: TableName): string[];
-declare function allTables(): readonly TableName[];
-declare function inferTable(dimensions: readonly string[]): TableName;
-/**
- * Natural-key columns for a table: the `sortKey` dimensions that uniquely
- * identify a metric row (e.g. `['date', 'url']` for `pages`).
- */
-declare function naturalKeyColumns(table: TableName): readonly string[];
-/**
- * Collapse rows that share a natural key (see {@link naturalKeyColumns}) to a
- * single survivor.
- *
- * Correct write and compaction inputs never collide on the natural key — each
- * (date, dimension) tuple is produced exactly once per slice — so on healthy
- * data this is a no-op. It exists as a recurrence guard: the 2026-04 monthly
- * compaction corruption folded a complete month back on top of its own daily
- * inputs, doubling every row. Absorbing duplicates at every write/compaction
- * boundary keeps that class of bug from inflating impressions downstream.
- *
- * Last occurrence wins. Observed duplicates are byte-identical, so the choice
- * of survivor is immaterial.
- */
-declare function dedupeByNaturalKey(table: TableName, rows: readonly Row[]): Row[];
-declare function dimensionToColumn(dim: string, _table: TableName): string;
-export { type ColumnDef, type ColumnType, DrizzleSchema, SCHEMAS, TABLE_METADATA, type TableSchema$1 as TableSchema, allTables, countries, currentSchemaVersion, dateColumnsFor, dates, dedupeByNaturalKey, dimensionToColumn, drizzleSchema, hourly_pages, inferTable, naturalKeyColumns, page_queries, pages, queries, search_appearance, search_appearance_page_queries, search_appearance_pages, search_appearance_queries };
+export { DrizzleSchema, TABLE_METADATA, countries, dates, drizzleSchema, hourly_pages, page_queries, pages, queries, search_appearance, search_appearance_page_queries, search_appearance_pages, search_appearance_queries };