@gscdump/analysis 0.6.3 → 0.7.5

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@gscdump/analysis?color=yellow)](https://npm.chart.dev/@gscdump/analysis)
 [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
 
-> SEO analyzers + typed query primitives for Google Search Console data. Row-based, DuckDB-native, D1-ready.
+> SEO analyzers for Google Search Console data. Row-based, DuckDB-native, D1-ready.
 
 ## Install
 
@@ -16,15 +16,16 @@ npm install @gscdump/analysis
 
 | Subpath | Use when |
 |---|---|
-| `@gscdump/analysis` | You have arrays of rows (GSC API responses, D1 query results). Pure functions, no DB. |
-| `@gscdump/analysis/analyzer` | Analyzer contracts (`Analyzer`, `Plan`, `FileSet`), `ROW_ANALYZERS`, registry, dispatcher. |
-| `@gscdump/engine-duckdb-node` | You have a Node DuckDB handle over parquet. Ships `SQL_ANALYZERS` + `analyzeInBrowser` for attached-table parquet. |
-| `@gscdump/engine-wasm` | Nuxt / React / vanilla app running DuckDB-WASM client-side against R2 parquets. |
-| `@gscdump/engine-sqlite` | Cloudflare Workers / anywhere routing through sqlite-proxy (D1). |
-| `@gscdump/engine/resolver` | Dialect-neutral SQL composition kit: `ResolverAdapter`, `pgResolverAdapter`, `compilePg`/`compileSqlite`, `resolveToSQL`, source contracts. |
-| `@gscdump/analysis/source` | Portable query sources + source-backed analyzers shared across GSC API, sqlite, DuckDB, and tests. |
+| `@gscdump/analysis` | Top-level barrel: row analyzers, source-backed analyzers, `SQL_ANALYZERS`, `analyzeInBrowser`, `defaultAnalyzerRegistry`, contract types re-exported from engine. |
+| `@gscdump/analysis/analyzer` | `ROW_ANALYZERS` array + `paginate*` / `adapt-rows` helpers used by analyzer authors. |
+| `@gscdump/analysis/registry` | Pre-built `defaultAnalyzerRegistry` (rows + sql). Convenience for callers who don't care about bundle size. |
+| `@gscdump/analysis/source` | Portable query sources (`createInMemoryQuerySource`, `createCompositeSource`) + source-backed analyzers. |
 | `@gscdump/analysis/semantic` | Browser-only semantic analyzers such as content-gap; optional `@huggingface/transformers` peer. |
 | `@gscdump/analysis/query` | `buildDataQueryPlan` / `buildDataDetailPlan` for the generic query analyzers. |
+| `@gscdump/analysis/routing` | Phase-aware D1 ↔ R2 routing helpers. |
+| `@gscdump/analysis/rollups` | Pre-baked rollup definitions + rebuild orchestration. |
+
+The contract layer (`Analyzer`, `Plan`, `Capability`, `AnalysisParams`, `AnalysisResult`, `AnalysisQuerySource`, `runAnalyzerFromSource`, `createAnalyzerRegistry`, `defineAnalyzer`, period helpers, `createEngineQuerySource`) lives in `@gscdump/engine` under the `/analyzer`, `/analysis-types`, `/period`, `/source`, and `/resolver` subpaths. Most are re-exported from `@gscdump/analysis` for convenience.
 
 ## Row-based analyzers
 
@@ -61,11 +62,8 @@ const prioritized = await analyzeActionPriority({
 Source adapters compose a GSC client + analyzer in one call:
 
 ```ts
-import {
-  analyzeMoversFromSource,
-  analyzeStrikingDistanceFromSource,
-  createGscApiQuerySource,
-} from '@gscdump/analysis'
+import { analyzeMoversFromSource, analyzeStrikingDistanceFromSource } from '@gscdump/analysis'
+import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
 
 const source = createGscApiQuerySource({ client, siteUrl })
 const movers = await analyzeMoversFromSource(source, { current, previous })
@@ -76,92 +74,39 @@ const movers = await analyzeMoversFromSource(source, { current, previous })
 SQL-native path. `SQL_ANALYZERS` dispatch through `runAnalyzerFromSource` against an engine-backed source.
 
 ```ts
-import { createAnalyzerRegistry, ROW_ANALYZERS, runAnalyzerFromSource } from '@gscdump/analysis/analyzer'
-import { createEngine, SQL_ANALYZERS } from '@gscdump/engine-duckdb-node'
+import { ROW_ANALYZERS, SQL_ANALYZERS } from '@gscdump/analysis'
+import { createAnalyzerRegistry, runAnalyzerFromSource } from '@gscdump/engine/analyzer'
+import { createEngineQuerySource } from '@gscdump/engine/source'
 
-const source = createEngine({ engine, ctx })
+const source = createEngineQuerySource({ engine, ctx })
 const registry = createAnalyzerRegistry({ rows: ROW_ANALYZERS, sql: SQL_ANALYZERS })
 const result = await runAnalyzerFromSource(source, { type: 'striking-distance', minImpressions: 100 }, registry)
 ```
 
-`attachParquetIndex` and `attachSnapshotIndex` wire parquet files (per-day, per-month, or pre-baked `.duckdb` snapshots) into a DuckDB session for `analyzeInBrowser` (attached-table path).
+`attachParquetIndex` and `attachSnapshotIndex` from `@gscdump/engine-duckdb-node` wire parquet files (per-day, per-month, or pre-baked `.duckdb` snapshots) into a DuckDB session. Pair with `analyzeInBrowser` from `@gscdump/analysis` for the attached-table dispatch path.
 
 ## Browser (DuckDB-WASM)
 
-Three primitives for client-side analytics:
-
 ```ts
-import {
-  createInsightRunner,
-  resolveWindow,
-  scopeFor,
-  strikingMomentum,
-} from '@gscdump/engine-wasm'
+import { analyzeInBrowser } from '@gscdump/analysis'
+import { createEngine } from '@gscdump/engine-duckdb-wasm'
 
-const runner = createInsightRunner({ db, conn }) // AsyncDuckDB + connection
-const window = resolveWindow({ preset: 'last-30d', comparison: 'prev-period' })
-const scope = scopeFor('pages', { siteId, window })
-
-const rows = await strikingMomentum(runner, { ...scope, limit: 50 })
+const result = await analyzeInBrowser(runner, { schema: 'gsc' }, { type: 'striking-distance' })
 ```
 
-- `createInsightRunner({ db, conn })` — drizzle-orm handle over DuckDB-WASM. Typed `.select()` / window functions, or drop to `sql\`...\`` raw.
-- `bootDuckDBWasm()` / `attachParquetUrlTables()` / `attachParquetTables()` / `createBrowserAnalysisRuntime()` — reusable browser runtime primitives for booting DuckDB-WASM, attaching parquet-backed views, and exposing `query()` / `analyze()` helpers without rewriting the same glue in every app.
-- `resolveWindow({ preset, comparison, anchor })` — canonical date windows, no DB.
-- `scopeFor(table, { siteId, window })` + `mergeScope()` — boundary predicates for multi-tenant queries.
-- `schema`, `pages`, `keywords`, `page_keywords`, `countries`, `devices` — drizzle schema mirroring `gscdump/analytics` `SCHEMAS`. Drift fails loudly at load.
-
-Vendors a stripped-down drizzle-orm DuckDB-WASM adapter (~240 LoC, adapted from `@proj-airi/drizzle-duckdb-wasm`, MIT). Transactions throw — analytics workload is read-only.
+`analyzeInBrowser` wraps any runner with `query(sql, params, signal?)` in an `AnalysisQuerySource` with the `attachedTables` capability and dispatches via `runAnalyzerFromSource`.
 
-`@duckdb/duckdb-wasm` is an optional peer dep. Bundle: **10.3 kB / 2.72 kB gzipped**.
+For typed drizzle-style access, `@gscdump/engine-duckdb-wasm` exports `createEngine` (a `SqlQuerySource`) plus `bootDuckDBWasm`, `attachParquetUrlTables`, `createBrowserAnalysisRuntime`, and `resolveWindow` (re-export from `@gscdump/engine/period`).
 
 ## SQLite (D1 / Cloudflare Workers)
 
-Mirror of `/browser`, dialect-targeted at sqlite-core.
-
-```ts
-import {
-  aggClicks,
-  aggCtr,
-  aggImpressions,
-  aggPosition,
-  compileSqlite,
-  createSqliteInsightRunner,
-  gsc_keywords,
-  sql,
-} from '@gscdump/engine-sqlite'
-
-const queryExpr = sql`
-  SELECT ${gsc_keywords.query} as keyword,
-         SUM(${gsc_keywords.clicks}) as clicks,
-         ${aggCtr(gsc_keywords)} as ctr
-  FROM ${gsc_keywords}
-  WHERE ${gsc_keywords.site_id} = ${siteId}
-  GROUP BY ${gsc_keywords.query}
-`
-const { sql: compiledSql, params } = compileSqlite(queryExpr)
-const rows = await executor(compiledSql, params) // queryUserD1, etc.
-```
-
-- `createSqliteInsightRunner({ executor })` — sqlite-proxy drizzle adapter.
-- `compileSqlite(sql)` — compile to `{ sql, params }` for any HTTP executor.
-- `aggClicks` / `aggImpressions` / `aggCtr` / `aggPosition` — aggregate helpers replacing hand-rolled `METRICS_SQL`.
-- Runtime builder exports (`colRef`, `dimColumn`, `metricSql`, `havingPredicates`, …) for dimension/metric driven query builders.
-
-Always import `sql` from `@gscdump/engine-sqlite` — not `drizzle-orm` directly — so consumers bind to the package's drizzle-orm instance and avoid cross-install `SQL<unknown>` mismatches.
-
-Bundle: **5.3 kB / 1.4 kB gzipped**.
+Mirror of the DuckDB path, dialect-targeted at sqlite-core. `@gscdump/engine-sqlite` exports `createEngine` (a `SqlQuerySource` over `executor + siteId`), `compileSqlite`, drizzle helpers (`gsc_keywords`, etc.), and `resolveWindow` (re-export from `@gscdump/engine/period`).
 
 ## Query composers (dialect-neutral)
 
 ```ts
 import { sqliteResolverAdapter } from '@gscdump/engine-sqlite'
-import {
-  buildTotalsSql,
-  pgResolverAdapter,
-  resolveToSQL,
-  resolveToSQLOptimized,
-} from '@gscdump/engine/resolver'
+import { pgResolverAdapter, resolveToSQL } from '@gscdump/engine/resolver'
 
 const resolved = resolveToSQL(builderState, { adapter: sqliteResolverAdapter, siteId })
 ```
@@ -173,16 +118,10 @@ Pass `sqliteResolverAdapter` from `@gscdump/engine-sqlite` (D1, `site_id`-scoped
 `/source` is the cross-implementation seam:
 
 ```ts
-import {
-  analyzeMoversFromSource,
-  createEngineQuerySource,
-  queryRows,
-} from '@gscdump/analysis/source'
-
-const source = createEngineQuerySource({
-  engine,
-  ctx: { userId, siteId },
-})
+import { analyzeMoversFromSource } from '@gscdump/analysis'
+import { createEngineQuerySource, queryRows } from '@gscdump/engine/source'
+
+const source = createEngineQuerySource({ engine, ctx: { userId, siteId } })
 
 const rows = await queryRows(source, builderState)
 const movers = await analyzeMoversFromSource(source, periods)
@@ -190,11 +129,12 @@ const movers = await analyzeMoversFromSource(source, periods)
 
 Available source factories:
 
-- `createGscApiQuerySource({ client, siteUrl })`
-- `createBrowserQuerySource({ query(sql, params) })`
-- `createSqliteQuerySource({ executor, siteId })`
-- `createEngineQuerySource({ engine, ctx })`
-- `createInMemoryQuerySource({ queryRows })`
+- `createGscApiQuerySource({ client, siteUrl })` — `@gscdump/engine-gsc-api`
+- `createLiveGscSource({ accessToken, siteUrl })` — `@gscdump/engine-gsc-api`
+- `createCompositeSource({ engine, gsc })` — `@gscdump/analysis/source`; engine first, GSC fallback
+- `createInMemoryQuerySource({ queryRows })` — `@gscdump/analysis/source`
+- `createEngineQuerySource({ engine, ctx })` — `@gscdump/engine/source`
+- `createEngine({ ... })` — `@gscdump/engine-duckdb-wasm`, `@gscdump/engine-sqlite`, `@gscdump/engine-duckdb-node`
 
 Portable analyzers currently cover the row-based tools:
 `striking-distance`, `opportunity`, `brand`, `clustering`, `concentration`,
@@ -202,9 +142,6 @@ Portable analyzers currently cover the row-based tools:
 
 ## Semantic (browser-only)
 
-`/semantic` holds browser-only analysis that depends on client runtime
-capabilities rather than SQL backends alone.
-
 ```ts
 import { analyzeContentGap } from '@gscdump/analysis/semantic'
 
@@ -214,14 +151,12 @@ const result = await analyzeContentGap(runner, {
 })
 ```
 
-`analyzeContentGap()` loads a MiniLM/BGE embedding model via
-`@huggingface/transformers`, caches vectors in IndexedDB, and compares top
-queries to candidate URLs derived from `page_keywords`.
+Loads a MiniLM/BGE embedding model via `@huggingface/transformers`, caches vectors in IndexedDB, and compares top queries to candidate URLs derived from `page_keywords`.
 
 ## Window resolution
 
 ```ts
-import { resolveWindow } from '@gscdump/engine-wasm'
+import { resolveWindow } from '@gscdump/analysis'
 
 const w = resolveWindow({ preset: 'last-30d', comparison: 'yoy' })
 // { start: '...', end: '...', days: 30, comparison: { start, end } }
@@ -234,19 +169,19 @@ Presets: `last-7d`, `last-28d`, `last-30d`, `last-90d`, `last-180d`, `last-365d`
 | Surface | Stability |
 |---|---|
 | Row analyzers (`analyzeStrikingDistance`, `analyzeMovers`, ...) | Public |
-| Source factories (`create*QuerySource`) + `analyzeFromSource` | Public |
-| Engine factories (`@gscdump/analysis/engine/<name>`'s `createEngine`) | Public |
-| `Analyzer<P, R>` contract + `analyzerRegistry` | Public |
-| `/period`, `/query`, `/source`, `/semantic` subpaths | Public |
-| Internals reached through `@gscdump/analysis/engine/<name>/<file>` not listed above | Private |
+| Source factories + `analyzeFromSource` | Public |
+| `Analyzer<P, R>` contract + `createAnalyzerRegistry` (re-exported from `@gscdump/engine/analyzer`) | Public |
+| `/source`, `/semantic`, `/query`, `/routing`, `/rollups` subpaths | Public |
+| Per-analyzer modules under `analysis/src/analyzers/<name>` | Private |
 
 ## Related
 
 - [`gscdump`](../gscdump) — REST client + query builder (edge-safe).
-- [`@gscdump/engine`](../engine) — Parquet/DuckDB storage engine.
-- [`@gscdump/engine-duckdb-node`](../engine-duckdb-node) — Node DuckDB analyzer dispatch.
-- [`@gscdump/engine-wasm`](../engine-wasm) — DuckDB-WASM browser runtime.
+- [`@gscdump/engine`](../engine) — Parquet/DuckDB storage engine + analyzer/source/period contracts.
+- [`@gscdump/engine-duckdb-node`](../engine-duckdb-node) — Node DuckDB engine factory + parquet/snapshot attach helpers.
+- [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) — DuckDB-WASM browser runtime + drizzle adapter.
 - [`@gscdump/engine-sqlite`](../engine-sqlite) — SQLite / D1 dialect adapter.
+- [`@gscdump/engine-gsc-api`](../engine-gsc-api) — GSC live-API engine adapter.
 - [`@gscdump/cli`](../cli) — CLI wrapping `gscdump` + `@gscdump/engine` + `@gscdump/analysis`.
 
 ## License

package/dist/analyzer/index.d.mts

@@ -1,6 +1,7 @@
+import * as _$_gscdump_engine_analyzer0 from "@gscdump/engine/analyzer";
+import { Analyzer } from "@gscdump/engine/analyzer";
+import { AnalysisPeriod } from "@gscdump/engine/period";
 import { BuilderState } from "gscdump/query";
-import { AnalysisQuerySource, FileSet, FileSet as FileSet$1 } from "@gscdump/engine/resolver";
-import { AnalysisParams, AnalysisResult } from "gscdump/contracts";
 import { Row } from "@gscdump/engine/contracts";
 /**
  * `bayesian-ctr` — Empirical-Bayes CTR shrinkage. SQL-only colocation.
@@ -27,7 +28,7 @@ interface BayesianCtrResult {
   significance: number;
   classification: 'overperforming' | 'underperforming' | 'expected';
 }
-declare const bayesianCtrAnalyzer: DefinedAnalyzer;
+declare const bayesianCtrAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * bipartite-pagerank
  *
@@ -53,7 +54,12 @@ interface BipartitePagerankNode {
   impressions: number;
 }
 type BipartitePagerankResult = BipartitePagerankNode;
-declare const bipartitePagerankAnalyzer: DefinedAnalyzer;
+declare const bipartitePagerankAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
+/**
+ * Domain row shapes + analysis utilities. Analyzer-call contracts
+ * (`AnalysisParams`, `AnalysisResult`, `AnalysisTool`, `num`) live in
+ * `@gscdump/engine/analysis-types`.
+ */
 type SortOrder = 'asc' | 'desc';
 /** Base search metrics */
 interface BaseMetrics {
@@ -98,7 +104,7 @@ interface BrandResultRow {
   position: number;
   segment: 'brand' | 'non-brand';
 }
-declare const brandAnalyzer: DefinedAnalyzer;
+declare const brandAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type CannibalizationSortMetric = 'clicks' | 'impressions' | 'positionSpread' | 'pageCount';
 interface CannibalizationOptions {
   /** Minimum impressions for a query to be considered. Default: 10 */
@@ -149,7 +155,7 @@ interface CannibalizationEvent {
   severity: number;
   competitors: CannibalizationCompetitor[];
 }
-declare const cannibalizationAnalyzer: DefinedAnalyzer;
+declare const cannibalizationAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * `change-point` — per-(query, url) timeseries change-point detection. SQL-only.
  *
@@ -174,7 +180,7 @@ interface ChangePointResult {
   direction: 'improved' | 'worsened';
   series: ChangePointSeriesPoint[];
 }
-declare const changePointAnalyzer: DefinedAnalyzer;
+declare const changePointAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type ClusterType = 'prefix' | 'intent' | 'both';
 interface ClusteringOptions {
   /** Minimum keywords for a cluster to be reported. Default: 2 */
@@ -197,7 +203,7 @@ interface ClusteringResult {
   clusters: KeywordCluster[];
   unclustered: KeywordRow[];
 }
-declare const clusteringAnalyzer: DefinedAnalyzer;
+declare const clusteringAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type ConcentrationRiskLevel = 'low' | 'medium' | 'high';
 interface ConcentrationOptions {
   /** Number of top items to report. Default: 10 */
@@ -225,7 +231,7 @@ interface ConcentrationResult {
   /** Risk level derived from HHI: <1500 low, 1500-2500 medium, >2500 high */
   riskLevel: ConcentrationRiskLevel;
 }
-declare const concentrationAnalyzer: DefinedAnalyzer;
+declare const concentrationAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * `content-velocity` — weekly new-keyword cadence. SQL-only colocation.
  *
@@ -236,7 +242,7 @@ interface ContentVelocityWeek {
   newKeywords: number;
   totalKeywords: number;
 }
-declare const contentVelocityAnalyzer: DefinedAnalyzer;
+declare const contentVelocityAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * `ctr-anomaly` — rolling CTR envelope per (query, page). SQL-only colocation.
  *
@@ -266,7 +272,7 @@ interface CtrAnomalyResult {
   totalClicks: number;
   series: CtrAnomalySeriesPoint[];
 }
-declare const ctrAnomalyAnalyzer: DefinedAnalyzer;
+declare const ctrAnomalyAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * `ctr-curve` — CTR by position bucket plus over/under-performing outliers.
  * SQL-only colocation.
@@ -290,7 +296,7 @@ interface CtrCurveOutlier {
   expectedCtr: number;
   ctrDiff: number;
 }
-declare const ctrCurveAnalyzer: DefinedAnalyzer;
+declare const ctrCurveAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * dark-traffic — gap between page-level clicks and sum-of-keyword clicks.
  *
@@ -305,11 +311,11 @@ interface DarkTrafficResult {
   darkPercent: number;
   keywordCount: number;
 }
-declare const darkTrafficAnalyzer: DefinedAnalyzer;
+declare const darkTrafficAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type DataDetailResult = Row;
-declare const dataDetailAnalyzer: DefinedAnalyzer;
+declare const dataDetailAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type DataQueryResult = Row;
-declare const dataQueryAnalyzer: DefinedAnalyzer;
+declare const dataQueryAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type DecaySortMetric = 'lostClicks' | 'declinePercent' | 'currentClicks';
 interface DecayOptions {
   /** Minimum clicks in previous period to consider. Default: 50 */
@@ -339,7 +345,7 @@ interface DecayResult {
   positionDrop: number;
   series?: DecaySeriesPoint[];
 }
-declare const decayAnalyzer: DefinedAnalyzer;
+declare const decayAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * device-gap — desktop vs mobile CTR/position delta over time.
  */
@@ -358,7 +364,7 @@ interface DeviceGapResult {
     positionGap: number;
   };
 }
-declare const deviceGapAnalyzer: DefinedAnalyzer;
+declare const deviceGapAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * intent-atlas
  *
@@ -381,7 +387,7 @@ interface IntentAtlasResult {
     position: number;
   }>;
 }
-declare const intentAtlasAnalyzer: DefinedAnalyzer;
+declare const intentAtlasAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * keyword-breadth — keyword-count histogram across pages + fragile/authority
  * classification.
@@ -390,7 +396,7 @@ interface KeywordBreadthResult {
   bucket: string;
   pageCount: number;
 }
-declare const keywordBreadthAnalyzer: DefinedAnalyzer;
+declare const keywordBreadthAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * long-tail
  *
@@ -415,7 +421,7 @@ interface LongTailResult {
     query: string;
   }>;
 }
-declare const longTailAnalyzer: DefinedAnalyzer;
+declare const longTailAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type MoversSortMetric = 'clicks' | 'impressions' | 'clicksChange' | 'impressionsChange' | 'positionChange';
 interface MoversOptions {
   /** Minimum change threshold to flag. Default: 0.2 (20%) */
@@ -459,7 +465,7 @@ interface MoversResultRow extends MoverData {
   direction: 'rising' | 'declining' | 'stable';
   series?: MoversSeriesPoint[];
 }
-declare const moversAnalyzer: DefinedAnalyzer;
+declare const moversAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 interface OpportunityFactors {
   positionScore: number;
   impressionScore: number;
@@ -476,7 +482,7 @@ interface OpportunityResult {
   potentialClicks: number;
   factors: OpportunityFactors;
 }
-declare const opportunityAnalyzer: DefinedAnalyzer;
+declare const opportunityAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * position-distribution — daily count of keywords per position bucket.
  * Matches `/api/sites/[siteId]/position-distribution.get.ts`.
@@ -489,7 +495,7 @@ interface PositionDistributionResult {
   pos_20_plus: number;
   total: number;
 }
-declare const positionDistributionAnalyzer: DefinedAnalyzer;
+declare const positionDistributionAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * position-volatility
  *
@@ -517,7 +523,7 @@ interface PositionVolatilityResult {
   totalImpressions: number;
   days: PositionVolatilityDay[];
 }
-declare const positionVolatilityAnalyzer: DefinedAnalyzer;
+declare const positionVolatilityAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * query-migration
  *
@@ -545,7 +551,7 @@ interface QueryMigrationResult {
   fuzzyCount: number;
   examples: QueryMigrationExample[];
 }
-declare const queryMigrationAnalyzer: DefinedAnalyzer;
+declare const queryMigrationAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 type SeasonalityMetric = 'clicks' | 'impressions';
 interface SeasonalityOptions {
   /** Metric to analyze for seasonality. Default: clicks */
@@ -567,7 +573,7 @@ interface SeasonalityResult {
   monthlyBreakdown: MonthlyData[];
   insufficientData: boolean;
 }
-declare const seasonalityAnalyzer: DefinedAnalyzer;
+declare const seasonalityAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * stl-decompose
  *
@@ -597,7 +603,7 @@ interface StlDecomposeResult {
   trendSlope: number;
   series: StlDecomposeSeriesPoint[];
 }
-declare const stlDecomposeAnalyzer: DefinedAnalyzer;
+declare const stlDecomposeAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * Unified `striking-distance` analyzer. Spike for the `defineAnalyzer`
  * pattern: one file owns the SQL plan, the row plan, the typed `InputRow`
@@ -632,7 +638,7 @@ interface StrikingDistanceResult {
   /** Estimated clicks at ~15% CTR (the average for positions 1–3). */
   potentialClicks: number;
 }
-declare const strikingDistanceAnalyzer: DefinedAnalyzer;
+declare const strikingDistanceAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * survival (Kaplan-Meier)
  *
@@ -660,7 +666,7 @@ interface SurvivalResult {
   medianTenure: number;
   curve: SurvivalCurvePoint[];
 }
-declare const survivalAnalyzer: DefinedAnalyzer;
+declare const survivalAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * trends — weekly trajectory over a rolling window (default 28 weeks)
  */
@@ -682,7 +688,7 @@ interface TrendsResult {
   trend: TrendCategory;
   series: TrendSeriesPoint[];
 }
-declare const trendsAnalyzer: DefinedAnalyzer;
+declare const trendsAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 /**
  * `zero-click` — high impressions, low CTR, good ranking. SQL groups by
  * (query, url) and applies HAVING/WHERE pushdown; row reducer dedupes to the
@@ -697,157 +703,10 @@ interface ZeroClickResult {
   ctr: number;
   position: number;
 }
-declare const zeroClickAnalyzer: DefinedAnalyzer;
-interface AnalysisPeriod {
-  startDate: string;
-  endDate: string;
-}
+declare const zeroClickAnalyzer: _$_gscdump_engine_analyzer0.DefinedAnalyzer;
 declare function keywordsQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
 declare function pagesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
 declare function datesQueryState(period: AnalysisPeriod, limit?: number): BuilderState;
-/**
- * Capabilities a Plan may require of its host. A dispatcher matches these
- * against a source's declared capabilities and rejects mismatches.
- */
-type Capability = 'executeSql' | 'partitionedParquet' | 'attachedTables' | 'regex' | 'windowTotals' | 'comparisonJoin';
-interface SqlExtraQuery {
-  name: string;
-  sql: string;
-  params: unknown[];
-}
-/**
- * SQL-native plan: SQL string + placeholders, with optional extra file sets
- * and follow-up queries. Mirrors the existing `AnalyzerSpec` shape but
- * renamed for clarity under the unified contract.
- */
-interface SqlPlan {
-  kind: 'sql';
-  sql: string;
-  params: unknown[];
-  current: FileSet$1;
-  previous?: FileSet$1;
-  extraFiles?: Record<string, FileSet$1>;
-  extraQueries?: SqlExtraQuery[];
-  /** Emits direct table refs (browser-only). Dispatcher rejects for manifest path. */
-  requiresAttachedTables?: boolean;
-}
-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;
-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. `KeywordRow`)
- * 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 Capability[];
-  /** Pure: params → plan. Snapshot-testable. */
-  build: (params: P) => Plan;
-  /** Pure: rows + context → typed result + meta. */
-  reduce: (rows: TRow[] | Record<string, TRow[]>, ctx: ReduceContext<TRow>) => {
-    results: R;
-    meta?: Record<string, unknown>;
-  };
-}
-interface SqlPlanSpec {
-  sql: string;
-  params: unknown[];
-  current: FileSet$1;
-  previous?: FileSet$1;
-  extraFiles?: Record<string, FileSet$1>;
-  extraQueries?: SqlExtraQuery[];
-  requiresAttachedTables?: boolean;
-}
-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) => SqlPlanSpec;
-  /** Row plan builder. Omit if the analyzer has no row path. */
-  buildRows?: (params: Params) => Record<string, BuilderState>;
-  /** Capabilities required by the SQL plan. Defaults to `['executeSql', 'partitionedParquet']`. */
-  sqlRequires?: readonly Capability[];
-  /** Capabilities required by the row plan. Defaults to `[]`. */
-  rowsRequires?: readonly Capability[];
-}
-interface DefinedAnalyzer {
-  id: string;
-  sql?: Analyzer;
-  rows?: Analyzer;
-}
-declare function defineAnalyzer<Params extends AnalysisParams, InputRow, Result>(opts: DefineAnalyzerOptions<Params, InputRow, Result>): DefinedAnalyzer;
-interface AnalyzerVariants {
-  sql?: Analyzer;
-  rows?: Analyzer;
-}
-interface AnalyzerRegistryInit {
-  rows?: readonly Analyzer[];
-  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;
-declare class AnalyzerCapabilityError extends Error {
-  readonly tool: string;
-  readonly missing: readonly Capability[];
-  constructor(tool: string, missing: readonly Capability[]);
-}
-/**
- * Run an analyzer against a generic `AnalysisQuerySource`. The registry is
- * an explicit parameter — callers build one via `createAnalyzerRegistry` (or
- * reuse `defaultAnalyzerRegistry` from the main barrel).
- */
-declare function runAnalyzerFromSource(source: AnalysisQuerySource, params: AnalysisParams, registry: AnalyzerRegistry): Promise<AnalysisResult>;
 /**
  * Pagination helpers shared across analyzers. SQL builders compose
  * `paginateClause` into their tail; row reducers use `paginateInMemory`
@@ -890,4 +749,4 @@ declare function resolveSort<K extends string>(input: {
   sortDir: 'asc' | 'desc';
 };
 declare const ROW_ANALYZERS: readonly Analyzer[];
-export { type Analyzer, AnalyzerCapabilityError, type AnalyzerRegistry, type AnalyzerRegistryInit, type AnalyzerVariants, type BayesianCtrResult, type BipartitePagerankNode, type BipartitePagerankResult, type BrandResultRow, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type Capability, type ChangePointResult, type ChangePointSeriesPoint, type ClusterType, type ClusteringOptions, type ClusteringResult, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type ContentVelocityWeek, type CtrAnomalyResult, type CtrAnomalySeriesPoint, type CtrCurveBucket, type CtrCurveOutlier, type DarkTrafficResult, type DataDetailResult, type DataQueryResult, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DefineAnalyzerOptions, type DefinedAnalyzer, type DeviceGapResult, type FileSet, type IntentAtlasResult, type KeywordBreadthResult, type KeywordCluster, type LongTailResult, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversResultRow, type MoversSeriesPoint, type MoversSortMetric, type OpportunityResult, type PaginateInput, type Plan, type PositionDistributionResult, type PositionVolatilityDay, type PositionVolatilityResult, type QueryMigrationExample, type QueryMigrationResult, ROW_ANALYZERS, type ReduceContext, type RowQueriesPlan, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type SqlExtraQuery, type SqlPlan, type SqlPlanSpec, type StlDecomposeResult, type StlDecomposeSeriesPoint, type StrikingDistanceInputRow, type StrikingDistanceResult, type SurvivalCurvePoint, type SurvivalResult, type TrendCategory, type TrendSeriesPoint, type TrendsResult, type TypedRowQuery, type ZeroClickResult, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, createAnalyzerRegistry, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, defineAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, runAnalyzerFromSource, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };
+export { type BayesianCtrResult, type BipartitePagerankNode, type BipartitePagerankResult, type BrandResultRow, type BrandSegmentationOptions, type BrandSegmentationResult, type BrandSummary, type CannibalizationCompetitor, type CannibalizationEvent, type CannibalizationOptions, type CannibalizationPage, type CannibalizationResult, type CannibalizationSortMetric, type ChangePointResult, type ChangePointSeriesPoint, type ClusterType, type ClusteringOptions, type ClusteringResult, type ConcentrationInput, type ConcentrationItem, type ConcentrationOptions, type ConcentrationResult, type ConcentrationRiskLevel, type ContentVelocityWeek, type CtrAnomalyResult, type CtrAnomalySeriesPoint, type CtrCurveBucket, type CtrCurveOutlier, type DarkTrafficResult, type DataDetailResult, type DataQueryResult, type DecayInput, type DecayOptions, type DecayResult, type DecaySeriesPoint, type DecaySortMetric, type DeviceGapResult, type IntentAtlasResult, type KeywordBreadthResult, type KeywordCluster, type LongTailResult, type MonthlyData, type MoverData, type MoversInput, type MoversOptions, type MoversResult, type MoversResultRow, type MoversSeriesPoint, type MoversSortMetric, type OpportunityResult, type PaginateInput, type PositionDistributionResult, type PositionVolatilityDay, type PositionVolatilityResult, type QueryMigrationExample, type QueryMigrationResult, ROW_ANALYZERS, type SeasonalityMetric, type SeasonalityOptions, type SeasonalityResult, type StlDecomposeResult, type StlDecomposeSeriesPoint, type StrikingDistanceInputRow, type StrikingDistanceResult, type SurvivalCurvePoint, type SurvivalResult, type TrendCategory, type TrendSeriesPoint, type TrendsResult, type ZeroClickResult, bayesianCtrAnalyzer, bipartitePagerankAnalyzer, brandAnalyzer, cannibalizationAnalyzer, changePointAnalyzer, clampLimit, clampOffset, clusteringAnalyzer, concentrationAnalyzer, contentVelocityAnalyzer, ctrAnomalyAnalyzer, ctrCurveAnalyzer, darkTrafficAnalyzer, dataDetailAnalyzer, dataQueryAnalyzer, datesQueryState, decayAnalyzer, deviceGapAnalyzer, intentAtlasAnalyzer, keywordBreadthAnalyzer, keywordsQueryState, longTailAnalyzer, moversAnalyzer, opportunityAnalyzer, pagesQueryState, paginateClause, paginateInMemory, positionDistributionAnalyzer, positionVolatilityAnalyzer, queryMigrationAnalyzer, resolveSort, seasonalityAnalyzer, stlDecomposeAnalyzer, strikingDistanceAnalyzer, survivalAnalyzer, trendsAnalyzer, zeroClickAnalyzer };