@gscdump/engine 1.4.0 → 1.4.2

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

@@ -0,0 +1,172 @@
+import { SearchType as SearchType$1, TableName as TableName$1 } from "../storage.mjs";
+import { ComparisonFilter } from "./types.mjs";
+import { BuilderState } from "gscdump/query";
+import { Grain } from "@gscdump/contracts";
+interface RunQueryCtx {
+  userId: string;
+  siteId: string;
+  table: TableName$1;
+  searchType?: SearchType$1;
+  /**
+   * Temporal granularity. `'day'` (default) drives `enumeratePartitions` to
+   * emit `daily/{date}` only; hourly partitions are skipped by construction.
+   * `'hour'` is reserved for hourly read paths and must use the dedicated
+   * hourly query surface (callers pass `partitions: [hourly/{date}]`
+   * directly through `runSQL`).
+   */
+  grain?: Grain;
+}
+interface RunSQLFn {
+  (opts: {
+    ctx: {
+      userId: string;
+      siteId: string;
+    };
+    table: TableName$1;
+    fileSets: Record<string, {
+      table: TableName$1;
+      partitions?: string[];
+      keys?: string[];
+    }>;
+    sql: string;
+    params: unknown[];
+    searchType?: SearchType$1;
+  }): Promise<{
+    rows: Array<Record<string, unknown>>;
+  }>;
+}
+interface CanonicalQueryDimSource {
+  /** Object keys for the versioned query_dim parquet. */
+  keys: string[];
+  normalizerVersion: number;
+  intentVersion?: number;
+  builtAt?: number;
+}
+interface PrimaryColumnarSource {
+  /** Pre-resolved compacted/Iceberg parquet object keys for the requested fact table. */
+  keys: string[];
+  /** Oldest covered date (`YYYY-MM-DD`). Omit to assert the source covers all older dates. */
+  coversFrom?: string;
+  /** Newest covered date (`YYYY-MM-DD`). Omit to assert the source covers the current tail. */
+  coversThrough?: string;
+}
+/**
+ * Optional overlay that serves a resolver extra (e.g. canonical-variant
+ * grouping, keyed `'canonicalExtras'`) from a precomputed source — typically a
+ * materialised rollup — instead of the live window-function SQL. Return the
+ * rows in the exact shape the live extra produces (`mergeExtras` consumes
+ * either source unchanged), or `null` to decline so the caller falls back to
+ * the live query. Pure seam: storage/tenant routing lives in the host's
+ * implementation, not here. See ADR-0017.
+ */
+interface ResolveExtraFn {
+  (opts: {
+    key: string;
+    state: BuilderState;
+    ctx: RunQueryCtx;
+    dateRange: {
+      startDate: string;
+      endDate: string;
+    };
+  }): Promise<Array<Record<string, unknown>> | null>;
+}
+interface RunOptimizedQueryOptions {
+  /** Overlay tried per extra before the live SQL; absent → today's live path. */
+  resolveExtra?: ResolveExtraFn;
+  /**
+   * Versioned query dimension backing canonical reads over fact rows. Required
+   * whenever a query groups or filters by `queryCanonical`; a canonical rollup
+   * source may carry the same metadata/key set via `canonicalSource.queryDim`.
+   */
+  queryDim?: CanonicalQueryDimSource;
+  /**
+   * Primary fact-file source for consumer reads. Callers pass compacted or
+   * Iceberg data-file keys with explicit coverage metadata; raw daily
+   * partitions are only used when `primarySourceFallback: 'raw'` is set.
+   */
+  primarySource?: PrimaryColumnarSource;
+  /**
+   * Explicit compatibility escape hatch for raw daily shards. Default is
+   * strict: missing/empty/stale primary coverage fails with
+   * `QuerySourceCoverageError`.
+   */
+  primarySourceFallback?: 'raw';
+  /**
+   * Opt-in canonical-primary performance (ADR-0018 Gap 2): object keys of the
+   * `query_canonical_daily` rollup parquet(s). When supplied AND the query is
+   * coverable (`canonicalRollupCovers`) AND the window is within the rollup's
+   * coverage, the MAIN query reads these
+   * pre-summed `(query_canonical × date)` rows instead of re-aggregating raw
+   * partitions. Variant extras still need fact-grain rows, so they read
+   * `primarySource` when present and raw partitions only via
+   * `primarySourceFallback: 'raw'`.
+   *
+   * `coversThrough` (ISO `YYYY-MM-DD`, the rollup's newest covered date) gates
+   * staleness: the source is used only when `dateRange.endDate <= coversThrough`,
+   * else strict mode fails so the recent tail is never silently undercounted.
+   * Omit to assert full coverage (use with care).
+   */
+  canonicalSource?: {
+    keys: string[];
+    coversThrough?: string;
+    queryDim?: CanonicalQueryDimSource;
+  };
+  /** Optional version gates for the query dimension backing `canonicalSource`. */
+  canonicalRequirements?: {
+    normalizerVersion?: number;
+    intentVersion?: number;
+  };
+}
+type QuerySourceKind = 'canonical-rollup' | 'primary-columnar' | 'raw-partitions';
+type QuerySourceFallbackKind = 'primary-source-missing' | 'primary-source-empty' | 'primary-source-missing-coverage' | 'primary-source-stale-coverage' | 'canonical-source-missing' | 'canonical-source-empty' | 'canonical-source-not-coverable' | 'canonical-source-stale-coverage' | 'query-dim-missing' | 'query-dim-empty' | 'query-dim-stale-version';
+interface QuerySourceFallback {
+  kind: QuerySourceFallbackKind;
+  message: string;
+}
+interface QuerySourceDecision {
+  kind: QuerySourceKind;
+  fallback?: QuerySourceFallback;
+  fallbacks?: QuerySourceFallback[];
+}
+declare class QuerySourceCoverageError extends Error {
+  readonly fallback: QuerySourceFallback;
+  name: string;
+  constructor(fallback: QuerySourceFallback);
+}
+interface OptimizedQueryResult {
+  rows: Array<Record<string, unknown>>;
+  totalCount: number;
+  totals: {
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+  };
+  extras: Array<{
+    key: string;
+    rows: Array<Record<string, unknown>>;
+  }>;
+  source: QuerySourceDecision;
+  extraSource?: QuerySourceDecision;
+}
+interface ComparisonQueryResult {
+  rows: Array<Record<string, unknown>>;
+  totalCount: number;
+  totals: Record<string, unknown>;
+  source: QuerySourceDecision;
+}
+declare function runOptimizedQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, state: BuilderState, dateRange: {
+  startDate: string;
+  endDate: string;
+}, options?: RunOptimizedQueryOptions): Promise<OptimizedQueryResult>;
+declare function runComparisonQuery(runSQL: RunSQLFn, ctx: RunQueryCtx, current: BuilderState, previous: BuilderState, windows: {
+  current: {
+    startDate: string;
+    endDate: string;
+  };
+  previous: {
+    startDate: string;
+    endDate: string;
+  };
+}, filter?: ComparisonFilter, options?: RunOptimizedQueryOptions): Promise<ComparisonQueryResult>;
+export { CanonicalQueryDimSource, ComparisonQueryResult, OptimizedQueryResult, PrimaryColumnarSource, QuerySourceCoverageError, QuerySourceDecision, QuerySourceFallback, QuerySourceFallbackKind, QuerySourceKind, ResolveExtraFn, RunOptimizedQueryOptions, RunQueryCtx, RunSQLFn, runComparisonQuery, runOptimizedQuery };

package/dist/resolver/run-query.mjs

@@ -0,0 +1,241 @@
+import { enumeratePartitions } from "../compaction.mjs";
+import "../planner.mjs";
+import { canonicalRollupCovers } from "./canonical-source.mjs";
+import { buildExtrasQueries, buildTotalsSql, resolveComparisonSQL, resolveToSQLOptimized } from "./compile.mjs";
+import { createParquetResolverAdapter } from "./pg-adapter.mjs";
+import { buildLogicalPlan } from "gscdump/query/plan";
+var QuerySourceCoverageError = class extends Error {
+	fallback;
+	name = "QuerySourceCoverageError";
+	constructor(fallback) {
+		super(fallback.message);
+		this.fallback = fallback;
+	}
+};
+function canonicalSourceWithinCoverage(source, windowEnd) {
+	return source.coversThrough === void 0 || windowEnd <= source.coversThrough;
+}
+function querySourceDecision(kind, fallbacks = []) {
+	const first = fallbacks[0];
+	return {
+		kind,
+		...first ? {
+			fallback: first,
+			fallbacks
+		} : {}
+	};
+}
+function canonicalFeatureRequested(state, capabilities) {
+	const plan = buildLogicalPlan(state, capabilities);
+	return plan.groupByDimensions.includes("queryCanonical") || plan.dimensionFilters.some((f) => f.dimension === "queryCanonical");
+}
+function fallback(kind, message) {
+	return {
+		kind,
+		message
+	};
+}
+function staleQueryDim(source, requirements) {
+	if (requirements?.normalizerVersion !== void 0 && source.normalizerVersion !== requirements.normalizerVersion) return fallback("query-dim-stale-version", `canonical query dimension normalizer v${source.normalizerVersion} does not match required v${requirements.normalizerVersion}`);
+	if (requirements?.intentVersion !== void 0 && source.intentVersion !== requirements.intentVersion) return fallback("query-dim-stale-version", `canonical query dimension intent v${source.intentVersion ?? "missing"} does not match required v${requirements.intentVersion}`);
+}
+function canonicalQueryDim(options) {
+	return options.queryDim ?? options.canonicalSource?.queryDim;
+}
+function queryDimMiss(source, requirements) {
+	if (!source) return fallback("query-dim-missing", "canonical query requires queryDim; fact tables do not carry query_canonical");
+	if (source.keys.length === 0) return fallback("query-dim-empty", "queryDim has no parquet keys; refusing to run canonical query from an empty dimension");
+	return staleQueryDim(source, requirements);
+}
+function decideCanonicalSource(state, capabilities, options, windowEnd) {
+	if (!canonicalFeatureRequested(state, capabilities)) return querySourceDecision("raw-partitions");
+	const dimMiss = queryDimMiss(canonicalQueryDim(options), options.canonicalRequirements);
+	if (dimMiss) throw new QuerySourceCoverageError(dimMiss);
+	const source = options.canonicalSource;
+	const miss = (() => {
+		if (!source) return fallback("canonical-source-missing", "canonical rollup source missing; falling back to primary facts joined through query_dim");
+		if (source.keys.length === 0) return fallback("canonical-source-empty", "canonicalSource has no parquet keys; falling back to primary facts joined through query_dim");
+		if (!canonicalSourceWithinCoverage(source, windowEnd)) return fallback("canonical-source-stale-coverage", `canonicalSource covers through ${source.coversThrough}, but query needs ${windowEnd}`);
+		if (!canonicalRollupCovers(state, capabilities)) return fallback("canonical-source-not-coverable", "canonicalSource only covers queryCanonical/date reads without raw-grain filters");
+	})();
+	if (!miss) return querySourceDecision("canonical-rollup");
+	return querySourceDecision("raw-partitions", [miss]);
+}
+function primarySourceMiss(source, dateRange) {
+	if (!source) return fallback("primary-source-missing", "primary columnar source is required; pass primarySourceFallback: \"raw\" to use raw daily partitions explicitly");
+	if (source.keys.length === 0) return fallback("primary-source-empty", "primarySource has no parquet keys; refusing to return partial or empty data implicitly");
+	if (source.coversFrom !== void 0 && dateRange.startDate < source.coversFrom) return fallback("primary-source-missing-coverage", `primarySource covers from ${source.coversFrom}, but query starts ${dateRange.startDate}`);
+	if (source.coversThrough !== void 0 && dateRange.endDate > source.coversThrough) return fallback("primary-source-stale-coverage", `primarySource covers through ${source.coversThrough}, but query needs ${dateRange.endDate}`);
+}
+function decidePrimarySource(options, dateRange, priorFallbacks = []) {
+	const miss = primarySourceMiss(options.primarySource, dateRange);
+	if (!miss) return querySourceDecision("primary-columnar", priorFallbacks);
+	const fallbacks = [...priorFallbacks, miss];
+	if (options.primarySourceFallback === "raw") return querySourceDecision("raw-partitions", fallbacks);
+	throw new QuerySourceCoverageError(miss);
+}
+function sourceFallbacks(source) {
+	if (source.fallbacks) return source.fallbacks;
+	return source.fallback ? [source.fallback] : [];
+}
+function runArgs(ctx, partitions) {
+	return {
+		ctx: {
+			userId: ctx.userId,
+			siteId: ctx.siteId
+		},
+		table: ctx.table,
+		fileSets: { FILES: {
+			table: ctx.table,
+			partitions
+		} },
+		...ctx.searchType !== void 0 ? { searchType: ctx.searchType } : {}
+	};
+}
+function primaryRunArgs(ctx, keys) {
+	return {
+		ctx: {
+			userId: ctx.userId,
+			siteId: ctx.siteId
+		},
+		table: ctx.table,
+		fileSets: { FILES: {
+			table: ctx.table,
+			keys
+		} },
+		...ctx.searchType !== void 0 ? { searchType: ctx.searchType } : {}
+	};
+}
+function withQueryDimFileSet(args, queryDim, enabled) {
+	if (!enabled || !queryDim) return args;
+	return {
+		...args,
+		fileSets: {
+			...args.fileSets,
+			QUERY_DIM: {
+				table: "queries",
+				keys: queryDim.keys
+			}
+		}
+	};
+}
+async function runOptimizedQuery(runSQL, ctx, state, dateRange, options = {}) {
+	const base = runArgs(ctx, enumeratePartitions(dateRange.startDate, dateRange.endDate));
+	const probe = createParquetResolverAdapter();
+	const canonicalRequested = canonicalFeatureRequested(state, probe.capabilities);
+	const canonicalDecision = decideCanonicalSource(state, probe.capabilities, options, dateRange.endDate);
+	const useCanonicalSource = canonicalDecision.kind === "canonical-rollup";
+	const source = useCanonicalSource ? canonicalDecision : decidePrimarySource(options, dateRange, sourceFallbacks(canonicalDecision));
+	const optimized = resolveToSQLOptimized(state, {
+		adapter: useCanonicalSource ? createParquetResolverAdapter({ queryCanonicalSource: "column" }) : probe,
+		siteId: void 0
+	});
+	const extras = buildExtrasQueries(state, {
+		adapter: probe,
+		siteId: void 0
+	});
+	const extraSource = extras.length > 0 ? useCanonicalSource ? decidePrimarySource(options, dateRange) : source : void 0;
+	const queryDim = canonicalQueryDim(options);
+	const mainArgs = withQueryDimFileSet(useCanonicalSource ? {
+		...base,
+		fileSets: { FILES: {
+			table: ctx.table,
+			keys: options.canonicalSource.keys
+		} }
+	} : source.kind === "primary-columnar" ? primaryRunArgs(ctx, options.primarySource.keys) : base, queryDim, canonicalRequested && !useCanonicalSource);
+	const extraArgs = withQueryDimFileSet(extraSource?.kind === "primary-columnar" ? primaryRunArgs(ctx, options.primarySource.keys) : base, queryDim, extras.length > 0);
+	const resolveExtra = options.resolveExtra;
+	const [optRes, ...extrasRows] = await Promise.all([runSQL({
+		...mainArgs,
+		sql: optimized.sql,
+		params: optimized.params
+	}), ...extras.map(async (e) => {
+		const overlaid = resolveExtra ? await resolveExtra({
+			key: e.key,
+			state,
+			ctx,
+			dateRange
+		}) : null;
+		return overlaid !== null ? { rows: overlaid } : runSQL({
+			...extraArgs,
+			sql: e.sql,
+			params: e.params
+		});
+	})]);
+	const firstRow = optRes.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: optRes.rows.map((r) => {
+			const { totalCount: _tc, totalClicks: _tcl, totalImpressions: _ti, totalCtr: _tr, totalPosition: _tp, ...rest } = r;
+			for (const key of Object.keys(rest)) if (key.startsWith("__order_")) delete rest[key];
+			return rest;
+		}),
+		totalCount,
+		totals,
+		extras: extras.map((e, i) => ({
+			key: e.key,
+			rows: extrasRows[i].rows
+		})),
+		source,
+		...extraSource ? { extraSource } : {}
+	};
+}
+async function runComparisonQuery(runSQL, ctx, current, previous, windows, filter, options = {}) {
+	const probe = createParquetResolverAdapter();
+	const maxWindowEnd = windows.current.endDate > windows.previous.endDate ? windows.current.endDate : windows.previous.endDate;
+	const currentSource = decideCanonicalSource(current, probe.capabilities, options, maxWindowEnd);
+	const previousSource = decideCanonicalSource(previous, probe.capabilities, options, maxWindowEnd);
+	const startDate = windows.current.startDate < windows.previous.startDate ? windows.current.startDate : windows.previous.startDate;
+	const endDate = windows.current.endDate > windows.previous.endDate ? windows.current.endDate : windows.previous.endDate;
+	const comparisonRange = {
+		startDate,
+		endDate
+	};
+	const source = currentSource.kind === "canonical-rollup" && previousSource.kind === "canonical-rollup" ? querySourceDecision("canonical-rollup") : decidePrimarySource(options, comparisonRange, [...sourceFallbacks(currentSource), ...sourceFallbacks(previousSource)]);
+	const useCanonicalSource = source.kind === "canonical-rollup";
+	const adapter = useCanonicalSource ? createParquetResolverAdapter({ queryCanonicalSource: "column" }) : probe;
+	const comparison = resolveComparisonSQL(current, previous, {
+		adapter,
+		siteId: void 0
+	}, filter);
+	const totals = buildTotalsSql(current, {
+		adapter,
+		siteId: void 0
+	});
+	const partitions = enumeratePartitions(startDate, endDate);
+	const base = withQueryDimFileSet(useCanonicalSource ? {
+		...runArgs(ctx, partitions),
+		fileSets: { FILES: {
+			table: ctx.table,
+			keys: options.canonicalSource.keys
+		} }
+	} : source.kind === "primary-columnar" ? primaryRunArgs(ctx, options.primarySource.keys) : runArgs(ctx, partitions), canonicalQueryDim(options), !useCanonicalSource && (canonicalFeatureRequested(current, probe.capabilities) || canonicalFeatureRequested(previous, probe.capabilities)));
+	const main = await runSQL({
+		...base,
+		sql: comparison.sql,
+		params: comparison.params
+	});
+	const count = await runSQL({
+		...base,
+		sql: comparison.countSql,
+		params: comparison.countParams
+	});
+	const totalsRow = await runSQL({
+		...base,
+		sql: totals.sql,
+		params: totals.params
+	});
+	return {
+		rows: main.rows,
+		totalCount: Number(count.rows[0]?.total ?? 0),
+		totals: totalsRow.rows[0] ?? {},
+		source
+	};
+}
+export { QuerySourceCoverageError, runComparisonQuery, runOptimizedQuery };

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

@@ -0,0 +1,15 @@
+import { TableName } from "@gscdump/contracts";
+interface AssertSchemaInSyncOptions {
+  /** Label used in the thrown error (e.g. 'browser', 'sqlite'). */
+  label: string;
+  /** Drizzle schema keyed by table name. For sqlite, strip the `gsc_` prefix before passing. */
+  schema: Record<string, unknown>;
+  /**
+   * Map drizzle table key → canonical `TableName`. For browser this is identity;
+   * for sqlite this strips the `gsc_` prefix.
+   */
+  tableKeyToName: (key: string) => TableName;
+  mode: 'exact' | 'superset';
+}
+declare function assertSchemaInSync(options: AssertSchemaInSyncOptions): void;
+export { AssertSchemaInSyncOptions, assertSchemaInSync };

package/dist/resolver/schema-drift.mjs

@@ -0,0 +1,12 @@
+import { SCHEMAS } from "../schema.mjs";
+function assertSchemaInSync(options) {
+	const { label, schema, tableKeyToName, mode } = options;
+	for (const [key, table] of Object.entries(schema)) {
+		const sourceCols = SCHEMAS[tableKeyToName(key)].columns.map((c) => c.name).sort();
+		const drizzleCols = Object.keys(table[Symbol.for("drizzle:Columns")] ?? {}).sort();
+		const missing = sourceCols.filter((c) => !drizzleCols.includes(c));
+		const extra = mode === "exact" ? drizzleCols.filter((c) => !sourceCols.includes(c)) : [];
+		if (missing.length > 0 || extra.length > 0) throw new Error(`${label} drizzle schema for '${key}' drifted from SCHEMAS. Missing: [${missing.join(", ")}]. Extra: [${extra.join(", ")}].`);
+	}
+}
+export { assertSchemaInSync };

package/dist/rollups.d.mts

@@ -1,7 +1,7 @@
-import { DataSource, FileSetRef, Row as Row$1, TableName as TableName$1 } from "./_chunks/storage.mjs";
-import { ColumnDef } from "./_chunks/schema.mjs";
-import { EngineError } from "./_chunks/errors.mjs";
-import "./_chunks/contracts.mjs";
+import { DataSource, FileSetRef, Row as Row$1, TableName as TableName$1 } from "./storage.mjs";
+import { ColumnDef } from "./schema.mjs";
+import { EngineError } from "./errors.mjs";
+import "./contracts.mjs";
 import { SearchType } from "gscdump/query";
 import { TenantCtx } from "@gscdump/contracts";
 interface RollupCtx extends TenantCtx {

package/dist/rollups.mjs

@@ -1,8 +1,9 @@
 import { engineErrors } from "./errors.mjs";
-import "./_chunks/layout.mjs";
+import "./layout.mjs";
 import { inspectionParquetKey, sitemapUrlsIndexPrefix } from "./entity-keys.mjs";
 import { encodeRowsToParquetFlex } from "./adapters/hyparquet.mjs";
-import { createIndexingMetadataStore, createQueryDimStore, createSitemapStore } from "./_chunks/entities.mjs";
+import { createQueryDimStore } from "./query-dim.mjs";
+import { createIndexingMetadataStore, createSitemapStore } from "./entities.mjs";
 import { MS_PER_DAY } from "gscdump/dates";
 import { encodeJsonBigintSafe } from "@gscdump/lakehouse/bigint";
 function rollupPrefix(ctx, searchType) {

package/dist/schedule.mjs

@@ -0,0 +1,100 @@
+const DAY = 24 * (3600 * 1e3);
+function isDue(state, now) {
+	return now >= state.nextAt;
+}
+function sitemapCadenceMs(consecutiveUnchanged) {
+	if (consecutiveUnchanged >= 7) return 30 * DAY;
+	if (consecutiveUnchanged >= 3) return 7 * DAY;
+	return DAY;
+}
+const SITEMAP_VERSION = 1;
+const sitemapPolicy = {
+	version: SITEMAP_VERSION,
+	initial(now) {
+		return {
+			nextAt: now + DAY,
+			consecutiveUnchanged: 0,
+			policyVersion: SITEMAP_VERSION
+		};
+	},
+	observe(prev, evt) {
+		if (prev.policyVersion !== SITEMAP_VERSION) return {
+			nextAt: evt.at + sitemapCadenceMs(0),
+			consecutiveUnchanged: 0,
+			policyVersion: SITEMAP_VERSION
+		};
+		if (evt.changed) return {
+			nextAt: evt.at + DAY,
+			consecutiveUnchanged: 0,
+			policyVersion: SITEMAP_VERSION
+		};
+		const next = prev.consecutiveUnchanged + 1;
+		return {
+			nextAt: evt.at + sitemapCadenceMs(next),
+			consecutiveUnchanged: next,
+			policyVersion: SITEMAP_VERSION
+		};
+	},
+	isDue
+};
+const INSPECTION_VERSION = 1;
+function inspectionCadenceMs(verdict) {
+	if (verdict === "PASS") return 30 * DAY;
+	if (verdict === "FAIL") return 7 * DAY;
+	return 14 * DAY;
+}
+function inspectionPolicy(verdict) {
+	const cadence = inspectionCadenceMs(verdict);
+	return {
+		version: INSPECTION_VERSION,
+		initial(now) {
+			return {
+				nextAt: now + cadence,
+				consecutiveUnchanged: 0,
+				policyVersion: INSPECTION_VERSION
+			};
+		},
+		observe(prev, evt) {
+			if (prev.policyVersion !== INSPECTION_VERSION) return {
+				nextAt: evt.at + cadence,
+				consecutiveUnchanged: 0,
+				policyVersion: INSPECTION_VERSION
+			};
+			const next = evt.changed ? 0 : prev.consecutiveUnchanged + 1;
+			return {
+				nextAt: evt.at + cadence,
+				consecutiveUnchanged: next,
+				policyVersion: INSPECTION_VERSION
+			};
+		},
+		isDue
+	};
+}
+const FIXED_VERSION = 1;
+function fixedPolicy(intervalMs) {
+	return {
+		version: FIXED_VERSION,
+		initial(now) {
+			return {
+				nextAt: now + intervalMs,
+				consecutiveUnchanged: 0,
+				policyVersion: FIXED_VERSION
+			};
+		},
+		observe(prev, evt) {
+			if (prev.policyVersion !== FIXED_VERSION) return {
+				nextAt: evt.at + intervalMs,
+				consecutiveUnchanged: 0,
+				policyVersion: FIXED_VERSION
+			};
+			const next = evt.changed ? 0 : prev.consecutiveUnchanged + 1;
+			return {
+				nextAt: evt.at + intervalMs,
+				consecutiveUnchanged: next,
+				policyVersion: FIXED_VERSION
+			};
+		},
+		isDue
+	};
+}
+export { fixedPolicy, inspectionPolicy, sitemapPolicy };

package/dist/schema.d.mts

@@ -1,2 +1,35 @@
-import { ColumnDef, ColumnType, DrizzleSchema, SCHEMAS, TABLE_METADATA, 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 } from "./_chunks/schema.mjs";
+import { DrizzleSchema, TABLE_METADATA, countries, dates, drizzleSchema, hourly_pages, page_queries, pages, queries, search_appearance, search_appearance_page_queries, search_appearance_pages, search_appearance_queries } from "./drizzle-schema.mjs";
+import { ColumnDef, ColumnType, Row, TableName, TableSchema, TableSchema as TableSchema$1 } from "@gscdump/contracts";
+declare const SCHEMAS: Record<TableName, TableSchema$1>;
+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, type DrizzleSchema, SCHEMAS, TABLE_METADATA, type 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 };