@gscdump/engine 0.8.2 → 0.9.1

package/dist/_chunks/duckdb.d.mts

@@ -1,4 +1,4 @@
-import { N as TableName, S as QueryExecutor, h as ParquetCodec, w as Row } from "./storage.mjs";
+import { C as QueryExecutor, P as TableName, T as Row, g as ParquetCodec } from "./storage.mjs";
 interface DuckDBHandle {
   query: (sql: string, params?: unknown[]) => Promise<Row[]>;
   registerFileBuffer: (name: string, bytes: Uint8Array) => Promise<void>;

package/dist/_chunks/index.d.mts

@@ -0,0 +1,57 @@
+import { t as AnalysisParams } from "./analysis-types.mjs";
+type WindowPreset = 'last-7d' | 'last-28d' | 'last-30d' | 'last-90d' | 'last-180d' | 'last-365d' | 'mtd' | 'ytd' | 'custom';
+type ComparisonMode = 'none' | 'prev-period' | 'yoy';
+interface ResolveWindowOptions {
+  preset: WindowPreset;
+  comparison?: ComparisonMode;
+  anchor?: string;
+  start?: string;
+  end?: string;
+}
+interface ResolvedWindow {
+  start: string;
+  end: string;
+  days: number;
+  comparison?: {
+    start: string;
+    end: string;
+  };
+}
+interface AnalysisPeriod {
+  startDate: string;
+  endDate: string;
+}
+interface ComparisonPeriod {
+  current: AnalysisPeriod;
+  previous: AnalysisPeriod;
+}
+declare function defaultEndDate(): string;
+declare function defaultStartDate(): string;
+declare function periodOf(params: AnalysisParams): AnalysisPeriod;
+declare function comparisonOf(params: AnalysisParams): ComparisonPeriod;
+declare function resolveWindow(opts: ResolveWindowOptions): ResolvedWindow;
+/** Convert a ResolvedWindow into the AnalysisPeriod / ComparisonPeriod shape. */
+declare function windowToPeriod(w: ResolvedWindow): AnalysisPeriod;
+declare function windowToComparisonPeriod(w: ResolvedWindow): ComparisonPeriod | undefined;
+interface PadTimeseriesOptions<T> {
+  /** ISO date (YYYY-MM-DD), inclusive lower bound. */
+  startDate: string;
+  /** ISO date (YYYY-MM-DD), inclusive upper bound. */
+  endDate: string;
+  /**
+   * Row to insert for missing dates. Defaults to `{ clicks: 0, impressions: 0, ctr: 0, position: 0 }`.
+   * The `date` field is set automatically.
+   */
+  fill?: Omit<T, 'date'>;
+  /** Row-field that carries the ISO date. Defaults to `date`. */
+  dateKey?: string;
+}
+type DateRowShape = Record<string, unknown> & {
+  date?: unknown;
+};
+/**
+ * Pad rows so every calendar day in `[startDate, endDate]` appears at least
+ * once. Existing dates keep all their rows (grouped timeseries safe).
+ */
+declare function padTimeseries<T extends DateRowShape = DateRowShape>(rows: readonly T[], options: PadTimeseriesOptions<T>): T[];
+export { ResolveWindowOptions as a, comparisonOf as c, padTimeseries as d, periodOf as f, windowToPeriod as h, PadTimeseriesOptions as i, defaultEndDate as l, windowToComparisonPeriod as m, ComparisonMode as n, ResolvedWindow as o, resolveWindow as p, ComparisonPeriod as r, WindowPreset as s, AnalysisPeriod as t, defaultStartDate as u };

package/dist/_chunks/planner.d.mts

@@ -1,4 +1,4 @@
-import { N as TableName } from "./storage.mjs";
+import { P as TableName } from "./storage.mjs";
 import { LogicalQueryPlan } from "gscdump/query/plan";
 import { BuilderState } from "gscdump/query";
 interface ResolvedQuery {

package/dist/_chunks/registry.d.mts

@@ -1,4 +1,4 @@
-import { w as Row } from "./storage.mjs";
+import { T as Row } from "./storage.mjs";
 import { t as AnalysisParams } from "./analysis-types.mjs";
 import { r as FileSet } from "./source-types.mjs";
 import { BuilderState } from "gscdump/query";

package/dist/_chunks/storage.d.mts

@@ -307,6 +307,16 @@ interface ExtraResult {
   key: string;
   rows: Row[];
 }
+interface OptimizedQueryResult {
+  rows: Row[];
+  totalCount: number;
+  totals: {
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+  };
+}
 interface QueryExecuteOptions {
   sql: string;
   params: unknown[];
@@ -317,6 +327,13 @@ interface QueryExecuteOptions {
    * `dataSource.uri` is available.
    */
   fileKeys: Record<string, string[]>;
+  /**
+   * Per-placeholder table identity. Used by the executor to emit a
+   * schema-correct empty fallback when a named file set is empty: an
+   * `extraFiles` placeholder against `page_keywords` should fall back to
+   * the page_keywords schema, not the analyzer's primary `table`.
+   */
+  placeholderTables?: Record<string, TableName>;
   dataSource: DataSource;
   table: TableName;
   signal?: AbortSignal;
@@ -396,6 +413,16 @@ interface StorageEngine {
    * when the state has no extras-eligible dimensions.
    */
   queryExtras: (ctx: QueryCtx, state: BuilderState) => Promise<ExtraResult[]>;
+  /**
+   * Single-scan variant of {@link query} that piggy-backs `totalCount` and
+   * unfiltered metric totals onto the dimensioned result via window functions.
+   * Replaces the host-side rows + totals + count fan-out with one DuckDB
+   * execution. Window-function output columns (`totalCount`, `totalClicks`,
+   * `totalImpressions`, `totalCtr`, `totalPosition`) are stripped from `rows`
+   * before return; missing per-metric totals (when the metric was not
+   * requested in `state.metrics`) default to 0.
+   */
+  queryOptimized: (ctx: QueryCtx, state: BuilderState) => Promise<OptimizedQueryResult>;
   /**
    * Run arbitrary SQL resolved against named partition sets. Composes
    * manifest lookup + object reads + placeholder substitution + execution
@@ -473,4 +500,4 @@ declare function mondayOfWeek(isoDate: string): string;
 /** YYYY-Qq for the quarter containing the given YYYY-MM month string. */
 declare function quarterOfMonth(month: string): string;
 declare function objectKey(ctx: TenantCtx, table: TableName, partition: string, version: number, searchType?: SearchType): string;
-export { SyncStateFilter as A, dayPartition as B, QueryResult as C, StorageEngine as D, SearchType$1 as E, Watermark as F, objectKey as G, inferSearchType as H, WatermarkFilter as I, weekPartition as J, quarterOfMonth as K, WatermarkScope as L, SyncStateScope as M, TableName$1 as N, SyncState as O, TenantCtx$1 as P, WriteCtx as R, QueryExecutor as S, RunSQLOptions as T, mondayOfWeek as U, inferLegacyTier as V, monthPartition as W, enumeratePartitions as X, CompactionThresholds as Y, PurgeResult as _, DataSource as a, QueryExecuteOptions as b, FileSetRef as c, LockScope as d, ManifestEntry as f, PurgeFilter as g, ParquetCodec as h, DEFAULT_SEARCH_TYPE as i, SyncStateKind as j, SyncStateDetail as k, GcCtx as l, ManifestStore as m, CompactionTier as n, EngineOptions as o, ManifestPurgeResult as p, quarterPartition as q, ComparisonResult as r, ExtraResult as s, CodecCtx as t, ListLiveFilter as u, PurgeUrlsResult as v, Row$1 as w, QueryExecuteResult as x, QueryCtx as y, WriteResult as z };
+export { SyncStateDetail as A, WriteResult as B, QueryExecutor as C, SearchType$1 as D, RunSQLOptions as E, TenantCtx$1 as F, monthPartition as G, inferLegacyTier as H, Watermark as I, quarterPartition as J, objectKey as K, WatermarkFilter as L, SyncStateKind as M, SyncStateScope as N, StorageEngine as O, TableName$1 as P, WatermarkScope as R, QueryExecuteResult as S, Row$1 as T, inferSearchType as U, dayPartition as V, mondayOfWeek as W, CompactionThresholds as X, weekPartition as Y, enumeratePartitions as Z, PurgeFilter as _, DataSource as a, QueryCtx as b, FileSetRef as c, LockScope as d, ManifestEntry as f, ParquetCodec as g, OptimizedQueryResult as h, DEFAULT_SEARCH_TYPE as i, SyncStateFilter as j, SyncState as k, GcCtx as l, ManifestStore as m, CompactionTier as n, EngineOptions as o, ManifestPurgeResult as p, quarterOfMonth as q, ComparisonResult as r, ExtraResult as s, CodecCtx as t, ListLiveFilter as u, PurgeResult as v, QueryResult as w, QueryExecuteOptions as x, PurgeUrlsResult as y, WriteCtx as z };

package/dist/adapters/hyparquet.d.mts

@@ -1,4 +1,4 @@
-import { N as TableName, a as DataSource, h as ParquetCodec, t as CodecCtx, w as Row } from "../_chunks/storage.mjs";
+import { P as TableName, T as Row, a as DataSource, g as ParquetCodec, t as CodecCtx } from "../_chunks/storage.mjs";
 import { t as ColumnDef } from "../_chunks/schema.mjs";
 declare function encodeRowsToParquet(table: TableName, rows: readonly Row[]): Uint8Array;
 interface EncodeFlexOptions {

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

@@ -1,4 +1,4 @@
-import { N as TableName, m as ManifestStore } from "../_chunks/storage.mjs";
+import { P as TableName, m as ManifestStore } from "../_chunks/storage.mjs";
 interface R2ObjectMetadata {
   etag: string;
 }

package/dist/contracts.d.mts

@@ -1,2 +1,2 @@
-import { A as SyncStateFilter, C as QueryResult, D as StorageEngine, E as SearchType, F as Watermark, I as WatermarkFilter, L as WatermarkScope, M as SyncStateScope, N as TableName, O as SyncState, P as TenantCtx, R as WriteCtx, S as QueryExecutor, T as RunSQLOptions, a as DataSource, b as QueryExecuteOptions, c as FileSetRef, d as LockScope, f as ManifestEntry, h as ParquetCodec, j as SyncStateKind, k as SyncStateDetail, l as GcCtx, m as ManifestStore, n as CompactionTier, o as EngineOptions, t as CodecCtx, u as ListLiveFilter, w as Row, x as QueryExecuteResult, y as QueryCtx, z as WriteResult } from "./_chunks/storage.mjs";
+import { A as SyncStateDetail, B as WriteResult, C as QueryExecutor, D as SearchType, E as RunSQLOptions, F as TenantCtx, I as Watermark, L as WatermarkFilter, M as SyncStateKind, N as SyncStateScope, O as StorageEngine, P as TableName, R as WatermarkScope, S as QueryExecuteResult, T as Row, a as DataSource, b as QueryCtx, c as FileSetRef, d as LockScope, f as ManifestEntry, g as ParquetCodec, j as SyncStateFilter, k as SyncState, l as GcCtx, m as ManifestStore, n as CompactionTier, o as EngineOptions, t as CodecCtx, u as ListLiveFilter, w as QueryResult, x as QueryExecuteOptions, z as WriteCtx } from "./_chunks/storage.mjs";
 export { 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/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SyncStateFilter, B as dayPartition, C as QueryResult, D as StorageEngine, E as SearchType, F as Watermark, G as objectKey, H as inferSearchType, I as WatermarkFilter, J as weekPartition, K as quarterOfMonth, L as WatermarkScope, M as SyncStateScope, N as TableName, O as SyncState, P as TenantCtx, R as WriteCtx, S as QueryExecutor, T as RunSQLOptions, U as mondayOfWeek, V as inferLegacyTier, W as monthPartition, X as enumeratePartitions, Y as CompactionThresholds, _ as PurgeResult, a as DataSource, b as QueryExecuteOptions, c as FileSetRef, d as LockScope, f as ManifestEntry, g as PurgeFilter, h as ParquetCodec, i as DEFAULT_SEARCH_TYPE, j as SyncStateKind, k as SyncStateDetail, l as GcCtx, m as ManifestStore, n as CompactionTier, o as EngineOptions, p as ManifestPurgeResult, q as quarterPartition, r as ComparisonResult, s as ExtraResult, t as CodecCtx, u as ListLiveFilter, v as PurgeUrlsResult, w as Row, x as QueryExecuteResult, y as QueryCtx, z as WriteResult } from "./_chunks/storage.mjs";
+import { A as SyncStateDetail, B as WriteResult, C as QueryExecutor, D as SearchType, E as RunSQLOptions, F as TenantCtx, G as monthPartition, H as inferLegacyTier, I as Watermark, J as quarterPartition, K as objectKey, L as WatermarkFilter, M as SyncStateKind, N as SyncStateScope, O as StorageEngine, P as TableName, R as WatermarkScope, S as QueryExecuteResult, T as Row, U as inferSearchType, V as dayPartition, W as mondayOfWeek, X as CompactionThresholds, Y as weekPartition, Z as enumeratePartitions, _ as PurgeFilter, a as DataSource, b as QueryCtx, c as FileSetRef, d as LockScope, f as ManifestEntry, g as ParquetCodec, h as OptimizedQueryResult, i as DEFAULT_SEARCH_TYPE, j as SyncStateFilter, k as SyncState, l as GcCtx, m as ManifestStore, n as CompactionTier, o as EngineOptions, p as ManifestPurgeResult, q as quarterOfMonth, r as ComparisonResult, s as ExtraResult, t as CodecCtx, u as ListLiveFilter, v as PurgeResult, w as QueryResult, x as QueryExecuteOptions, y as PurgeUrlsResult, z as WriteCtx } from "./_chunks/storage.mjs";
 import { a as createDuckDBExecutor, i as createDuckDBCodec, n as DuckDBHandle, r as canonicalEmptyParquetSchema, t as DuckDBFactory } from "./_chunks/duckdb.mjs";
 import { _ as pages, a as allTables, c as inferTable, d as TABLE_METADATA, f as countries, g as page_keywords, h as keywords, i as TableSchema, m as drizzleSchema, n as ColumnType, o as currentSchemaVersion, p as devices, r as SCHEMAS, s as dimensionToColumn, t as ColumnDef, u as DrizzleSchema } from "./_chunks/schema.mjs";
 import { GscApiRow, IngestOptions, RowAccumulator, RowAccumulatorOptions, createRowAccumulator, toPath, toSumPosition, transformGscRow } from "./ingest.mjs";
@@ -9,4 +9,4 @@ declare function coerceRow(row: Row$1): Row$1;
 declare function coerceRows(rows: readonly Row$1[]): Row$1[];
 declare const MAX_DAY_BYTES: number;
 declare function createStorageEngine(opts: EngineOptions): StorageEngine;
-export { type CodecCtx, type ColumnDef, type ColumnType, type CompactionThresholds, type CompactionTier, type ComparisonResult, DEFAULT_SEARCH_TYPE, type DataSource, type DrizzleSchema, type DuckDBFactory, type DuckDBHandle, type EngineOptions, type ExtraResult, FILES_PLACEHOLDER, type FileSetRef, type GcCtx, type GscApiRow, type IngestOptions, type ListLiveFilter, type LockScope, MAX_DAY_BYTES, type ManifestEntry, type ManifestPurgeResult, type ManifestStore, type ParquetCodec, type PurgeFilter, type PurgeResult, type PurgeUrlsResult, type QueryCtx, type QueryExecuteOptions, type QueryExecuteResult, type QueryExecutor, type QueryResult, type ResolvedQuery, type Row, type RowAccumulator, type RowAccumulatorOptions, type RunSQLOptions, SCHEMAS, type SearchType, type StorageEngine, type SyncState, type SyncStateDetail, type SyncStateFilter, type SyncStateKind, type SyncStateScope, TABLE_METADATA, type TableName, type TableSchema, type TenantCtx, type Watermark, type WatermarkFilter, type WatermarkScope, type WriteCtx, type WriteResult, allTables, bindLiterals, canonicalEmptyParquetSchema, coerceRow, coerceRows, countries, createDuckDBCodec, createDuckDBExecutor, createRowAccumulator, createStorageEngine, currentSchemaVersion, dayPartition, devices, dimensionToColumn, drizzleSchema, enumeratePartitions, formatLiteral, inferLegacyTier, inferSearchType, inferTable, keywords, mondayOfWeek, monthPartition, objectKey, page_keywords, pages, quarterOfMonth, quarterPartition, resolveToSQL, substituteNamedFiles, toPath, toSumPosition, transformGscRow, weekPartition };
+export { type CodecCtx, type ColumnDef, type ColumnType, type CompactionThresholds, type CompactionTier, type ComparisonResult, DEFAULT_SEARCH_TYPE, type DataSource, type DrizzleSchema, type DuckDBFactory, type DuckDBHandle, type EngineOptions, type ExtraResult, FILES_PLACEHOLDER, type FileSetRef, type GcCtx, type GscApiRow, type IngestOptions, type ListLiveFilter, type LockScope, MAX_DAY_BYTES, type ManifestEntry, type ManifestPurgeResult, type ManifestStore, type OptimizedQueryResult, type ParquetCodec, type PurgeFilter, type PurgeResult, type PurgeUrlsResult, type QueryCtx, type QueryExecuteOptions, type QueryExecuteResult, type QueryExecutor, type QueryResult, type ResolvedQuery, type Row, type RowAccumulator, type RowAccumulatorOptions, type RunSQLOptions, SCHEMAS, type SearchType, type StorageEngine, type SyncState, type SyncStateDetail, type SyncStateFilter, type SyncStateKind, type SyncStateScope, TABLE_METADATA, type TableName, type TableSchema, type TenantCtx, type Watermark, type WatermarkFilter, type WatermarkScope, type WriteCtx, type WriteResult, allTables, bindLiterals, canonicalEmptyParquetSchema, coerceRow, coerceRows, countries, createDuckDBCodec, createDuckDBExecutor, createRowAccumulator, createStorageEngine, currentSchemaVersion, dayPartition, devices, dimensionToColumn, drizzleSchema, enumeratePartitions, formatLiteral, inferLegacyTier, inferSearchType, inferTable, keywords, mondayOfWeek, monthPartition, objectKey, page_keywords, pages, quarterOfMonth, quarterPartition, resolveToSQL, substituteNamedFiles, toPath, toSumPosition, transformGscRow, weekPartition };

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { a as inferTable, c as countries, d as keywords, f as page_keywords, i a
 import { a as mondayOfWeek, c as quarterOfMonth, d as weekPartition, i as inferSearchType, l as quarterPartition, n as dayPartition, o as monthPartition, r as inferLegacyTier, s as objectKey, t as DEFAULT_SEARCH_TYPE, u as tenantPrefix } from "./_chunks/storage.mjs";
 import { a as compactTieredImpl, i as substituteNamedFiles, n as compileLogicalQueryPlan, o as enumeratePartitions, r as resolveToSQL, t as FILES_PLACEHOLDER } from "./_chunks/planner.mjs";
 import { bindLiterals, formatLiteral, sqlEscape } from "./sql-bind.mjs";
-import { g as resolveComparisonSQL, m as buildTotalsSql, p as buildExtrasQueries, t as createParquetResolverAdapter } from "./_chunks/pg-adapter.mjs";
+import { g as resolveComparisonSQL, m as buildTotalsSql, p as buildExtrasQueries, t as createParquetResolverAdapter, v as resolveToSQLOptimized } from "./_chunks/pg-adapter.mjs";
 import { createRowAccumulator, toPath, toSumPosition, transformGscRow } from "./ingest.mjs";
 import { buildLogicalPlan } from "gscdump/query/plan";
 import { normalizeUrl } from "gscdump/normalize";
@@ -113,18 +113,18 @@ function createDuckDBCodec(factory) {
 		}
 	};
 }
-function rewriteEmptyFileSets(sql, placeholders, table) {
-	const emptyFallback = `(SELECT * FROM ${emptyTableSchema(table)} WHERE FALSE)`;
+function rewriteEmptyFileSets(sql, placeholders, defaultTable, placeholderTables) {
 	let out = sql;
 	for (const [name, keys] of Object.entries(placeholders)) {
 		if (keys.length > 0) continue;
+		const emptyFallback = `(SELECT * FROM ${emptyTableSchema(placeholderTables?.[name] ?? defaultTable)} WHERE FALSE)`;
 		const pattern = new RegExp(`read_parquet\\(\\s*\\{\\{${name}\\}\\}\\s*(?:,\\s*union_by_name\\s*=\\s*true\\s*)?\\)`, "g");
 		out = out.replace(pattern, emptyFallback);
 	}
 	return out;
 }
 function createDuckDBExecutor(factory) {
-	return { async execute({ sql, params, fileKeys, dataSource, table, signal }) {
+	return { async execute({ sql, params, fileKeys, placeholderTables, dataSource, table, signal }) {
 		signal?.throwIfAborted();
 		const db = await factory.getDuckDB();
 		const placeholders = {};
@@ -145,7 +145,7 @@ function createDuckDBExecutor(factory) {
 		}
 		try {
 			signal?.throwIfAborted();
-			const finalSql = substituteNamedFiles(rewriteEmptyFileSets(sql, placeholders, table), placeholders);
+			const finalSql = substituteNamedFiles(rewriteEmptyFileSets(sql, placeholders, table, placeholderTables), placeholders);
 			return {
 				rows: await db.query(finalSql, params),
 				sql: finalSql
@@ -349,10 +349,13 @@ function createStorageEngine(opts) {
 			table = entries[0]?.[1].table;
 		}
 		if (!table) throw new Error("runSQL requires at least one fileSet or an explicit table");
+		const placeholderTables = {};
+		for (const [name, ref] of entries) placeholderTables[name] = ref.table;
 		const result = await executor.execute({
 			sql: opts.sql,
 			params: opts.params ?? [],
 			fileKeys,
+			placeholderTables,
 			dataSource,
 			table,
 			signal: opts.signal
@@ -436,6 +439,46 @@ function createStorageEngine(opts) {
 			totals: totalsRow.rows[0] ?? {}
 		};
 	}
+	async function queryOptimized(ctx, state) {
+		const adapter = createParquetResolverAdapter();
+		const plan = buildLogicalPlan(state, adapter.capabilities);
+		const table = ctx.table ?? plan.dataset;
+		const partitions = enumeratePartitions(plan.dateRange.startDate, plan.dateRange.endDate);
+		const { sql, params } = resolveToSQLOptimized(state, {
+			adapter,
+			siteId: void 0
+		});
+		const result = await runSQL({
+			ctx: {
+				userId: ctx.userId,
+				siteId: ctx.siteId
+			},
+			table,
+			fileSets: { FILES: {
+				table,
+				partitions
+			} },
+			sql,
+			params,
+			signal: ctx.signal
+		});
+		const firstRow = result.rows[0];
+		const totalCount = Number(firstRow?.totalCount ?? 0);
+		const totals = {
+			clicks: Number(firstRow?.totalClicks ?? 0),
+			impressions: Number(firstRow?.totalImpressions ?? 0),
+			ctr: Number(firstRow?.totalCtr ?? 0),
+			position: Number(firstRow?.totalPosition ?? 0)
+		};
+		return {
+			rows: result.rows.map((r) => {
+				const { totalCount: _tc, totalClicks: _tcl, totalImpressions: _ti, totalCtr: _tr, totalPosition: _tp, ...rest } = r;
+				return rest;
+			}),
+			totalCount,
+			totals
+		};
+	}
 	async function queryExtras(ctx, state) {
 		const adapter = createParquetResolverAdapter();
 		const extras = buildExtrasQueries(state, {
@@ -576,6 +619,7 @@ function createStorageEngine(opts) {
 		query,
 		queryComparison,
 		queryExtras,
+		queryOptimized,
 		runSQL,
 		compactTiered,
 		gcOrphans,

package/dist/ingest.d.mts

@@ -1,4 +1,4 @@
-import { N as TableName, w as Row } from "./_chunks/storage.mjs";
+import { P as TableName, T as Row } from "./_chunks/storage.mjs";
 /**
  * Canonical GSC API dimension order per table. Consumers hitting the raw
  * `searchanalytics.query` endpoint must request dimensions in this order so

package/dist/period/index.d.mts

@@ -1,57 +1,2 @@
-import { t as AnalysisParams } from "../_chunks/analysis-types.mjs";
-type WindowPreset = 'last-7d' | 'last-28d' | 'last-30d' | 'last-90d' | 'last-180d' | 'last-365d' | 'mtd' | 'ytd' | 'custom';
-type ComparisonMode = 'none' | 'prev-period' | 'yoy';
-interface ResolveWindowOptions {
-  preset: WindowPreset;
-  comparison?: ComparisonMode;
-  anchor?: string;
-  start?: string;
-  end?: string;
-}
-interface ResolvedWindow {
-  start: string;
-  end: string;
-  days: number;
-  comparison?: {
-    start: string;
-    end: string;
-  };
-}
-interface AnalysisPeriod {
-  startDate: string;
-  endDate: string;
-}
-interface ComparisonPeriod {
-  current: AnalysisPeriod;
-  previous: AnalysisPeriod;
-}
-declare function defaultEndDate(): string;
-declare function defaultStartDate(): string;
-declare function periodOf(params: AnalysisParams): AnalysisPeriod;
-declare function comparisonOf(params: AnalysisParams): ComparisonPeriod;
-declare function resolveWindow(opts: ResolveWindowOptions): ResolvedWindow;
-/** Convert a ResolvedWindow into the AnalysisPeriod / ComparisonPeriod shape. */
-declare function windowToPeriod(w: ResolvedWindow): AnalysisPeriod;
-declare function windowToComparisonPeriod(w: ResolvedWindow): ComparisonPeriod | undefined;
-interface PadTimeseriesOptions<T> {
-  /** ISO date (YYYY-MM-DD), inclusive lower bound. */
-  startDate: string;
-  /** ISO date (YYYY-MM-DD), inclusive upper bound. */
-  endDate: string;
-  /**
-   * Row to insert for missing dates. Defaults to `{ clicks: 0, impressions: 0, ctr: 0, position: 0 }`.
-   * The `date` field is set automatically.
-   */
-  fill?: Omit<T, 'date'>;
-  /** Row-field that carries the ISO date. Defaults to `date`. */
-  dateKey?: string;
-}
-type DateRowShape = Record<string, unknown> & {
-  date?: unknown;
-};
-/**
- * Pad rows so every calendar day in `[startDate, endDate]` appears at least
- * once. Existing dates keep all their rows (grouped timeseries safe).
- */
-declare function padTimeseries<T extends DateRowShape = DateRowShape>(rows: readonly T[], options: PadTimeseriesOptions<T>): T[];
+import { a as ResolveWindowOptions, c as comparisonOf, d as padTimeseries, f as periodOf, h as windowToPeriod, i as PadTimeseriesOptions, l as defaultEndDate, m as windowToComparisonPeriod, n as ComparisonMode, o as ResolvedWindow, p as resolveWindow, r as ComparisonPeriod, s as WindowPreset, t as AnalysisPeriod, u as defaultStartDate } from "../_chunks/index.mjs";
 export { AnalysisPeriod, ComparisonMode, ComparisonPeriod, PadTimeseriesOptions, ResolveWindowOptions, ResolvedWindow, WindowPreset, comparisonOf, defaultEndDate, defaultStartDate, padTimeseries, periodOf, resolveWindow, windowToComparisonPeriod, windowToPeriod };

package/dist/planner.d.mts

@@ -1,3 +1,3 @@
-import { X as enumeratePartitions } from "./_chunks/storage.mjs";
+import { Z as enumeratePartitions } from "./_chunks/storage.mjs";
 import { a as substituteNamedFiles, i as resolveToSQL, n as ResolvedQuery, r as compileLogicalQueryPlan, t as FILES_PLACEHOLDER } from "./_chunks/planner.mjs";
 export { FILES_PLACEHOLDER, ResolvedQuery, compileLogicalQueryPlan, enumeratePartitions, resolveToSQL, substituteNamedFiles };

package/dist/report/index.d.mts

@@ -0,0 +1,171 @@
+import { n as AnalysisResult, t as AnalysisParams } from "../_chunks/analysis-types.mjs";
+import { n as ComparisonMode, o as ResolvedWindow, s as WindowPreset } from "../_chunks/index.mjs";
+/** Status vocabulary mirrors `ActionPrioritySourceStatus`. */
+type ReportStepStatus = 'pending' | 'running' | 'done' | 'skipped' | 'error';
+type ReportSeverity = 'info' | 'low' | 'medium' | 'high';
+type ReportEntityKind = 'page' | 'query';
+type ReportActionKind = 'analyzer' | 'cli' | 'indexing' | 'fix';
+type ReportCoverage = 'full' | 'partial';
+/** Citty-shaped arg spec, kept structural so engine doesn't pull citty in. */
+interface ReportArgDef {
+  type: 'string' | 'boolean' | 'number';
+  description?: string;
+  default?: string | boolean | number;
+  required?: boolean;
+  alias?: string;
+}
+type ReportArgsSpec = Record<string, ReportArgDef>;
+interface ReportEntity {
+  kind: ReportEntityKind;
+  value: string;
+}
+interface ReportFindingDelta {
+  metric: string;
+  prior: number;
+  current: number;
+  pct: number;
+}
+interface ReportFinding {
+  entity: ReportEntity;
+  metrics: Record<string, number>;
+  delta?: ReportFindingDelta;
+  why?: string;
+}
+interface ReportSectionSummary {
+  delta?: number;
+  direction?: 'up' | 'down' | 'flat';
+  magnitudeLabel?: string;
+}
+interface ReportAction {
+  kind: ReportActionKind;
+  target?: ReportEntity;
+  params?: Record<string, unknown>;
+  rationale: string;
+  /** Human hint, generated; never authoritative. */
+  cliHint?: string;
+}
+interface ReportSectionArtifact {
+  analyzer: string;
+  params: AnalysisParams;
+}
+interface ReportSection {
+  id: string;
+  title: string;
+  severity: ReportSeverity;
+  summary: ReportSectionSummary;
+  /** Bounded; sorted by stable composite key. */
+  findings: ReportFinding[];
+  truncated?: {
+    kept: number;
+    total: number;
+  };
+  coverage: ReportCoverage;
+  actions: ReportAction[];
+  artifact?: ReportSectionArtifact;
+}
+interface ReportPlanStep {
+  /** Stable identifier within the report (e.g. `movers`, `decay-current`). */
+  key: string;
+  /** Analyzer id (or future: nested report id). Open string by design. */
+  type: string;
+  /** Analyzer params; report-runtime applies `type` from the step. */
+  params: Omit<AnalysisParams, 'type'>;
+  /** Required steps fail the report; optional steps degrade `coverage`. */
+  required?: boolean;
+}
+interface ReportStepStateMeta {
+  key: string;
+  type: string;
+  status: ReportStepStatus;
+  error?: string;
+}
+interface ReportResultMeta {
+  durationMs: number;
+  rowsScanned: number;
+  degraded: boolean;
+  steps: ReportStepStateMeta[];
+}
+interface ReportResult {
+  id: string;
+  site: string;
+  /** sha256(id|site|window|paramsCanonical|registryVersion). Stable. */
+  inputHash: string;
+  /** ISO 8601. NOT included in inputHash. */
+  generatedAt: string;
+  window: ResolvedWindow;
+  sections: ReportSection[];
+  meta: ReportResultMeta;
+}
+/**
+ * Loose params bag. Concrete reports refine this with their own interface.
+ * Constraint is `object` so report authors can use plain interfaces without
+ * needing an index signature.
+ */
+type ReportParams = object;
+interface ReportContext<P extends ReportParams = ReportParams> {
+  /** Resolved site URL (e.g. `https://example.com/`). */
+  site: string;
+  /** Already-resolved window — runtime calls `resolveWindow` once before plan(). */
+  window: ResolvedWindow;
+  params: P;
+  /** Hash of registry/code version. Bumped via package version. */
+  registryVersion: string;
+}
+/**
+ * Reduce step results → sections. Runtime injects `meta` post-reduce.
+ */
+type ReportReducer<P extends ReportParams = ReportParams> = (results: Record<string, AnalysisResult>, ctx: ReportContext<P>) => Omit<ReportResult, 'meta' | 'inputHash' | 'generatedAt' | 'site' | 'window' | 'id'> & {
+  sections: ReportSection[];
+};
+interface DefinedReport<P extends ReportParams = ReportParams> {
+  id: string;
+  description: string;
+  defaultPeriod: WindowPreset;
+  defaultComparison: ComparisonMode;
+  /** Single source of truth for CLI flags + MCP input schema. */
+  argsSpec: ReportArgsSpec;
+  plan: (params: P, window: ResolvedWindow) => readonly ReportPlanStep[];
+  reduce: ReportReducer<P>;
+}
+interface DefineReportOptions<P extends ReportParams = ReportParams> {
+  id: string;
+  description: string;
+  defaultPeriod: WindowPreset;
+  defaultComparison: ComparisonMode;
+  argsSpec?: ReportArgsSpec;
+  plan: (params: P, window: ResolvedWindow) => readonly ReportPlanStep[];
+  reduce: ReportReducer<P>;
+}
+/**
+ * Mirror of `defineAnalyzer`. Pure factory: validates required fields,
+ * fills default `argsSpec`. No runtime behaviour — `runReport` consumes
+ * the returned object.
+ */
+declare function defineReport<P extends ReportParams = ReportParams>(opts: DefineReportOptions<P>): DefinedReport<P>;
+interface InputHashSeeds {
+  id: string;
+  site: string;
+  window: ResolvedWindow;
+  params: ReportParams;
+  registryVersion: string;
+}
+/** Stable JSON: sorts object keys at every level. Arrays preserve order. */
+declare function canonicalize(value: unknown): unknown;
+declare function computeInputHash(seeds: InputHashSeeds): Promise<string>;
+interface ReportRegistryInit {
+  reports?: readonly DefinedReport<ReportParams>[];
+  /**
+   * Opaque version string. Used as the `registryVersion` input to
+   * `inputHash` so cached results invalidate when report code ships.
+   * Caller is expected to feed in their package version.
+   */
+  version?: string;
+}
+interface ReportRegistry {
+  version: string;
+  listReportIds: () => readonly string[];
+  getReport: (id: string) => DefinedReport<ReportParams> | undefined;
+  listReports: () => readonly DefinedReport<ReportParams>[];
+}
+declare function createReportRegistry(init?: ReportRegistryInit): ReportRegistry;
+export { type DefineReportOptions, type DefinedReport, type InputHashSeeds, type ReportAction, type ReportActionKind, type ReportArgDef, type ReportArgsSpec, type ReportContext, type ReportCoverage, type ReportEntity, type ReportEntityKind, type ReportFinding, type ReportFindingDelta, type ReportParams, type ReportPlanStep, type ReportReducer, type ReportRegistry, type ReportRegistryInit, type ReportResult, type ReportResultMeta, type ReportSection, type ReportSectionArtifact, type ReportSectionSummary, type ReportSeverity, type ReportStepStateMeta, type ReportStepStatus, canonicalize, computeInputHash, createReportRegistry, defineReport };

package/dist/report/index.mjs

@@ -0,0 +1,56 @@
+function defineReport(opts) {
+	if (!opts.id) throw new Error("defineReport: id is required");
+	if (!opts.plan) throw new Error(`defineReport(${opts.id}): plan is required`);
+	if (!opts.reduce) throw new Error(`defineReport(${opts.id}): reduce is required`);
+	return {
+		id: opts.id,
+		description: opts.description,
+		defaultPeriod: opts.defaultPeriod,
+		defaultComparison: opts.defaultComparison,
+		argsSpec: opts.argsSpec ?? {},
+		plan: opts.plan,
+		reduce: opts.reduce
+	};
+}
+function canonicalize(value) {
+	if (value == null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const out = {};
+	for (const k of Object.keys(value).sort()) out[k] = canonicalize(value[k]);
+	return out;
+}
+async function computeInputHash(seeds) {
+	const payload = JSON.stringify(canonicalize({
+		id: seeds.id,
+		site: seeds.site,
+		window: {
+			start: seeds.window.start,
+			end: seeds.window.end,
+			comparison: seeds.window.comparison ?? null
+		},
+		params: seeds.params,
+		registryVersion: seeds.registryVersion
+	}));
+	const bytes = new TextEncoder().encode(payload);
+	return bufferToHex(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+}
+function bufferToHex(buffer) {
+	const bytes = new Uint8Array(buffer);
+	let out = "";
+	for (let i = 0; i < bytes.length; i++) out += bytes[i].toString(16).padStart(2, "0");
+	return out;
+}
+function createReportRegistry(init = {}) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const r of init.reports ?? []) {
+		if (byId.has(r.id)) throw new Error(`createReportRegistry: duplicate report id ${r.id}`);
+		byId.set(r.id, r);
+	}
+	return {
+		version: init.version ?? "0",
+		listReportIds: () => [...byId.keys()].sort(),
+		getReport: (id) => byId.get(id),
+		listReports: () => [...byId.values()]
+	};
+}
+export { canonicalize, computeInputHash, createReportRegistry, defineReport };

package/dist/source/index.d.mts

@@ -1,4 +1,4 @@
-import { D as StorageEngine, P as TenantCtx, w as Row } from "../_chunks/storage.mjs";
+import { F as TenantCtx, O as StorageEngine, T as Row } from "../_chunks/storage.mjs";
 import { n as AnalysisResult, t as AnalysisParams } from "../_chunks/analysis-types.mjs";
 import { i as QueryRow, r as FileSet, s as SqlQuerySource, t as AnalysisQuerySource } from "../_chunks/source-types.mjs";
 import { t as AnalyzerRegistry } from "../_chunks/registry.mjs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine",
   "type": "module",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Append-only Parquet/DuckDB storage engine + planner + adapters for the gscdump pipeline. Node + edge runtimes; opt-in heavy peers.",
   "author": {
     "name": "Harlan Wilton",
@@ -101,6 +101,11 @@
       "import": "./dist/analyzer/index.mjs",
       "default": "./dist/analyzer/index.mjs"
     },
+    "./report": {
+      "types": "./dist/report/index.d.mts",
+      "import": "./dist/report/index.mjs",
+      "default": "./dist/report/index.mjs"
+    },
     "./analysis-types": {
       "types": "./dist/analysis-types.d.mts",
       "import": "./dist/analysis-types.mjs",
@@ -154,7 +159,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "proper-lockfile": "^4.1.2",
-    "gscdump": "0.8.2"
+    "gscdump": "0.9.1"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",