@gscdump/engine 1.4.11 → 1.5.0

package/dist/rollups/canonical.d.mts

@@ -0,0 +1,71 @@
+import { DataSource } from "../storage.mjs";
+import "../contracts.mjs";
+import { RollupDef, RollupEngine } from "./core.mjs";
+import { TenantCtx } from "@gscdump/contracts";
+import { SearchType } from "gscdump/query";
+declare const queryCanonicalVariantsRollup: RollupDef;
+/**
+ * Canonical-grained fact aggregate (ADR-0018 Gap 2): pre-sums the raw
+ * `(query × date)` query rows to `(query_canonical × date)`, so canonical-
+ * primary top/gaining/losing reads a small pre-aggregated table instead of
+ * re-collapsing variants on every request. Metrics are additive, so summing
+ * these per-date sums over a window is exact — identical to aggregating the raw
+ * rows.
+ *
+ * Null-free by construction: groups by the versioned query dimension when it
+ * exists, with raw query as the fallback, so the rollup never carries a NULL/''
+ * canonical bucket and the read path can treat the rollup's `query_canonical`
+ * column as already-derived.
+ *
+ * Date-grained full history (`windowDays: null`): one rollup serves every date
+ * range (reads filter by `date`) and both windows of a comparison. Opt-in (not
+ * in `DEFAULT_ROLLUPS`); the host points the main query's file set at it for
+ * queries the rollup covers (see `canonicalRollupCovers` /
+ * `RunOptimizedQueryOptions.canonicalSource`).
+ */
+declare const queryCanonicalDailyRollup: RollupDef;
+/**
+ * Resumable, cross-invocation build of `query_canonical_daily` for a high-
+ * cardinality site whose full windowed build exceeds one job reservation (300s).
+ *
+ * Each call builds from `(windowOffset, pageOffset)` until `deadlineMs`, writes
+ * that batch's rows to a PART parquet, and returns `{ done:false, nextWindowOffset,
+ * nextPageOffset }` for the caller to re-enqueue. When the last window is fully
+ * paged it publishes a multi-file envelope listing every part (parts are disjoint
+ * by `(query_canonical, date)`, so the read path just unions them — no merge),
+ * returning `{ done:true }`. `builtAt` MUST be stable across the continuation chain
+ * (it versions both the part keys and the final rollup key).
+ *
+ * INTRA-WINDOW resumability: the deadline is checked between raw-query hash shards,
+ * not just between date windows. A single high-cardinality day can spend a full
+ * reservation inside one grouped/sorted aggregate before the deadline check gets
+ * control back. `pageOffset` is the next shard index for the current window, so a
+ * continuation resumes the SAME day at the next shard. Parts are keyed by
+ * `(windowOffset, pageOffset)`; multiple parts may contain the same canonical/date
+ * from different raw-query shards, and rollup reads sum over the union.
+ */
+declare function rebuildCanonicalDailyResumable(opts: {
+  engine: RollupEngine;
+  ctx: TenantCtx;
+  dataSource: DataSource;
+  searchType?: SearchType;
+  builtAt: number;
+  windowOffset: number;
+  /** Resume the `windowOffset` window at this shard offset (0 = window start). */
+  pageOffset?: number;
+  /** Output rows per page (default `ROLLUP_PAGE_ROWS_DAILY`). Injectable for tests. */
+  pageRows?: number;
+  /** Cap each input window's day span (default `DAILY_MAX_WINDOW_DAYS`). */
+  maxWindowDays?: number;
+  /** Split each date window by raw-query hash before grouping (1 = no sharding). */
+  shardCount?: number;
+  deadlineMs: number;
+}): Promise<{
+  done: boolean;
+  nextWindowOffset: number;
+  nextPageOffset: number;
+  windowsTotal: number;
+  windowsBuilt: number;
+  rowsWritten: number;
+}>;
+export { queryCanonicalDailyRollup, queryCanonicalVariantsRollup, rebuildCanonicalDailyResumable };

package/dist/rollups/canonical.mjs

@@ -0,0 +1,335 @@
+import { encodeRowsToParquetFlex } from "../adapters/hyparquet.mjs";
+import { createQueryDimStore } from "../entities/query-dim.mjs";
+import "../entities.mjs";
+import { rollupKey, rollupParquetKey } from "./core.mjs";
+import { ROLLUP_PAGE_ROWS_DAILY, ROLLUP_PAGE_ROWS_WIDE, planRollupWindows, runWindowed } from "./windows.mjs";
+import { encodeJsonBigintSafe } from "@gscdump/lakehouse/bigint";
+const CANONICAL_VARIANT_LIMIT = 10;
+function retainCanonicalVariant(bucket, query, clicks, impressions, sumPos) {
+	bucket.count++;
+	let insertAt = 0;
+	while (insertAt < bucket.top.length) {
+		const existing = bucket.top[insertAt];
+		if (clicks > existing.clicks || clicks === existing.clicks && query.localeCompare(existing.query) < 0) break;
+		insertAt++;
+	}
+	if (insertAt >= CANONICAL_VARIANT_LIMIT) return;
+	bucket.top.splice(insertAt, 0, {
+		query,
+		clicks,
+		impressions,
+		sumPos
+	});
+	if (bucket.top.length > CANONICAL_VARIANT_LIMIT) bucket.top.pop();
+}
+const queryCanonicalVariantsRollup = {
+	id: "query_canonical_variants",
+	windowDays: null,
+	format: "parquet",
+	parquetColumns: [
+		{
+			name: "joinKey",
+			type: "VARCHAR",
+			nullable: false
+		},
+		{
+			name: "variantCount",
+			type: "BIGINT",
+			nullable: false
+		},
+		{
+			name: "canonicalName",
+			type: "VARCHAR",
+			nullable: true
+		},
+		{
+			name: "variants",
+			type: "VARCHAR",
+			nullable: true
+		}
+	],
+	parquetSortKey: ["joinKey"],
+	async build({ engine, ctx, dataSource, searchType }) {
+		const parts = await engine.listPartitions({
+			ctx,
+			table: "queries",
+			...searchType !== void 0 ? { searchType } : {}
+		});
+		if (parts.length === 0) return [];
+		const partitions = parts.map((p) => p.partition);
+		const byCanonical = /* @__PURE__ */ new Map();
+		const dimStore = createQueryDimStore({ dataSource });
+		const useDim = await dimStore.loadMeta(ctx) !== null;
+		const canonExpr = useDim ? "COALESCE(qd.query_canonical, q.query)" : "q.query";
+		let cursor = null;
+		for (;;) {
+			const after = cursor === null ? "" : `AND q.query > '${cursor.replace(/'/g, "''")}'`;
+			const fileSets = { FILES: {
+				table: "queries",
+				partitions
+			} };
+			if (useDim) fileSets.QUERY_DIM = {
+				table: "queries",
+				keys: [dimStore.parquetKey(ctx)]
+			};
+			const { rows } = await engine.runSQL({
+				ctx,
+				table: "queries",
+				...searchType !== void 0 ? { searchType } : {},
+				fileSets,
+				sql: `
+          SELECT
+            ${canonExpr} AS joinKey,
+            q.query AS query,
+            SUM(q.clicks) AS clicks,
+            SUM(q.impressions) AS impressions,
+            SUM(q.sum_position) AS sum_pos
+          FROM read_parquet({{FILES}}, union_by_name = true) q
+          ${useDim ? "LEFT JOIN read_parquet({{QUERY_DIM}}, union_by_name = true) qd ON q.query = qd.query" : ""}
+          WHERE q.query IS NOT NULL ${after}
+          GROUP BY ${canonExpr}, q.query
+          ORDER BY q.query
+          LIMIT ${ROLLUP_PAGE_ROWS_WIDE}
+        `
+			});
+			for (const r of rows) {
+				const joinKey = String(r.joinKey);
+				let bucket = byCanonical.get(joinKey);
+				if (!bucket) {
+					bucket = {
+						count: 0,
+						top: []
+					};
+					byCanonical.set(joinKey, bucket);
+				}
+				retainCanonicalVariant(bucket, String(r.query), Number(r.clicks), Number(r.impressions), Number(r.sum_pos));
+			}
+			if (rows.length < 2e4) break;
+			cursor = String(rows[rows.length - 1].query);
+		}
+		const out = [];
+		for (const [joinKey, bucket] of byCanonical) {
+			const canonicalName = bucket.top[0]?.query ?? null;
+			const top = bucket.top.filter((v) => v.impressions > 0);
+			const variantsStr = top.length === 0 ? null : top.map((v) => `${v.query}:::${v.clicks}:::${v.impressions}:::${(v.sumPos / v.impressions + 1).toFixed(1)}`).join("||");
+			out.push({
+				joinKey,
+				variantCount: BigInt(bucket.count),
+				canonicalName,
+				variants: variantsStr
+			});
+		}
+		return out;
+	}
+};
+const CANONICAL_DAILY_ROLLUP_FINAL_ID = "query_canonical_daily";
+const CANONICAL_DAILY_PART_STEM = "query_canonical_daily__part";
+const queryCanonicalDailyRollup = {
+	id: "query_canonical_daily",
+	windowDays: null,
+	format: "parquet",
+	parquetColumns: [
+		{
+			name: "query_canonical",
+			type: "VARCHAR",
+			nullable: false
+		},
+		{
+			name: "date",
+			type: "DATE",
+			nullable: false
+		},
+		{
+			name: "clicks",
+			type: "BIGINT",
+			nullable: false
+		},
+		{
+			name: "impressions",
+			type: "BIGINT",
+			nullable: false
+		},
+		{
+			name: "sum_position",
+			type: "DOUBLE",
+			nullable: false
+		}
+	],
+	parquetSortKey: ["date", "query_canonical"],
+	async build({ engine, ctx, dataSource, searchType }) {
+		const dimStore = createQueryDimStore({ dataSource });
+		const useDim = await dimStore.loadMeta(ctx) !== null;
+		const canonExpr = useDim ? `COALESCE(qd.query_canonical, q.query)` : `query`;
+		return (await runWindowed({
+			engine,
+			ctx,
+			table: "queries",
+			...searchType !== void 0 ? { searchType } : {},
+			...useDim ? { extraFileSets: { QUERY_DIM: {
+				table: "queries",
+				keys: [dimStore.parquetKey(ctx)]
+			} } } : {},
+			paginate: {
+				orderBy: "date, query_canonical",
+				pageRows: ROLLUP_PAGE_ROWS_DAILY
+			},
+			maxWindowDays: 7,
+			sqlFor: dailyWindowSqlFor(useDim, canonExpr)
+		})).map(mapDailyRow);
+	}
+};
+function canonicalDailyShardPredicate(queryExpr, shardIndex, shardCount) {
+	return shardCount <= 1 ? "" : ` AND (hash(${queryExpr}) % ${shardCount}) = ${shardIndex}`;
+}
+function dailyWindowSqlFor(useDim, canonExpr) {
+	return useDim ? (w, shard) => `
+        SELECT
+          ${canonExpr} AS query_canonical,
+          CAST(q.date AS VARCHAR) AS date,
+          SUM(q.clicks)::BIGINT AS clicks,
+          SUM(q.impressions)::BIGINT AS impressions,
+          SUM(q.sum_position)::DOUBLE AS sum_position
+        FROM read_parquet({{FILES}}, union_by_name = true) q
+        LEFT JOIN read_parquet({{QUERY_DIM}}, union_by_name = true) qd ON q.query = qd.query
+        WHERE q.date >= '${w.start}' AND q.date <= '${w.end}'${canonicalDailyShardPredicate("q.query", shard?.index ?? 0, shard?.count ?? 1)}
+        GROUP BY ${canonExpr}, q.date
+      ` : (w, shard) => `
+        SELECT
+          ${canonExpr} AS query_canonical,
+          CAST(q.date AS VARCHAR) AS date,
+          SUM(q.clicks)::BIGINT AS clicks,
+          SUM(q.impressions)::BIGINT AS impressions,
+          SUM(q.sum_position)::DOUBLE AS sum_position
+        FROM read_parquet({{FILES}}, union_by_name = true) q
+        WHERE q.date >= '${w.start}' AND q.date <= '${w.end}'${canonicalDailyShardPredicate("q.query", shard?.index ?? 0, shard?.count ?? 1)}
+        GROUP BY ${canonExpr}, q.date
+      `;
+}
+function mapDailyRow(r) {
+	return {
+		query_canonical: String(r.query_canonical),
+		date: String(r.date),
+		clicks: BigInt(r.clicks),
+		impressions: BigInt(r.impressions),
+		sum_position: Number(r.sum_position)
+	};
+}
+async function rebuildCanonicalDailyResumable(opts) {
+	const { engine, ctx, dataSource, searchType, builtAt, windowOffset, deadlineMs } = opts;
+	const sType = searchType !== void 0 ? { searchType } : {};
+	const startPageOffset = opts.pageOffset ?? 0;
+	const pageRows = opts.pageRows ?? 7e4;
+	const maxWindowDays = opts.maxWindowDays ?? 7;
+	const shardCount = Math.max(1, Math.floor(opts.shardCount ?? 1));
+	const windows = planRollupWindows((await engine.listPartitions({
+		ctx,
+		table: "queries",
+		...sType
+	})).map((p) => ({
+		partition: p.partition,
+		bytes: p.bytes
+	})), void 0, maxWindowDays);
+	const windowsTotal = windows.length;
+	const dimStore = createQueryDimStore({ dataSource });
+	const useDim = await dimStore.loadMeta(ctx) !== null;
+	const canonExpr = useDim ? `COALESCE(qd.query_canonical, q.query)` : `query`;
+	const extraFileSets = useDim ? { QUERY_DIM: {
+		table: "queries",
+		keys: [dimStore.parquetKey(ctx)]
+	} } : void 0;
+	const sqlFor = dailyWindowSqlFor(useDim, canonExpr);
+	const cols = queryCanonicalDailyRollup.parquetColumns;
+	const sortKey = queryCanonicalDailyRollup.parquetSortKey;
+	let i = windowOffset;
+	let page = startPageOffset;
+	let nextWindowOffset = windowsTotal;
+	let nextPageOffset = 0;
+	let rowsWritten = 0;
+	let pausedMidWindow = false;
+	const flushPage = async (windowIdx, pageOffset, rows) => {
+		if (rows.length === 0) return;
+		const key = rollupParquetKey(ctx, `${CANONICAL_DAILY_PART_STEM}__w${windowIdx}_p${pageOffset}`, builtAt, searchType);
+		await dataSource.write(key, encodeRowsToParquetFlex(rows, {
+			columns: cols,
+			sortKey
+		}));
+		rowsWritten += rows.length;
+	};
+	for (; i < windowsTotal; i++) {
+		const w = windows[i];
+		for (; page < shardCount;) {
+			const coreSql = sqlFor(w, {
+				index: page,
+				count: shardCount
+			});
+			const result = await engine.runSQL({
+				ctx,
+				table: "queries",
+				...sType,
+				fileSets: {
+					FILES: {
+						table: "queries",
+						partitions: w.partitions
+					},
+					...extraFileSets
+				},
+				sql: `${coreSql}\nORDER BY date, query_canonical\nLIMIT ${pageRows}`
+			});
+			if (result.rows.length >= pageRows) throw new Error(`query_canonical_daily shard overflow: window=${i} shard=${page}/${shardCount} returned >= ${pageRows} rows; increase shardCount or pageRows`);
+			await flushPage(i, page, result.rows.map(mapDailyRow));
+			page += 1;
+			if (Date.now() > deadlineMs) {
+				nextWindowOffset = i;
+				nextPageOffset = page;
+				pausedMidWindow = true;
+				break;
+			}
+		}
+		if (pausedMidWindow) break;
+		page = 0;
+		if (Date.now() > deadlineMs) {
+			nextWindowOffset = i + 1;
+			nextPageOffset = 0;
+			break;
+		}
+	}
+	if (nextWindowOffset < windowsTotal || nextPageOffset > 0) return {
+		done: false,
+		nextWindowOffset,
+		nextPageOffset,
+		windowsTotal,
+		windowsBuilt: nextWindowOffset - windowOffset,
+		rowsWritten
+	};
+	const partPrefixDir = rollupParquetKey(ctx, CANONICAL_DAILY_PART_STEM, builtAt, searchType).replace(/[^/]*$/, "");
+	const partKeys = (await dataSource.list(partPrefixDir)).filter((k) => k.includes(`${CANONICAL_DAILY_PART_STEM}__w`) && k.endsWith(`__v${builtAt}.parquet`)).sort();
+	if (partKeys.length === 0) {
+		const emptyKey = rollupParquetKey(ctx, `${CANONICAL_DAILY_PART_STEM}__w0_p0`, builtAt, searchType);
+		await dataSource.write(emptyKey, encodeRowsToParquetFlex([], {
+			columns: cols,
+			sortKey
+		}));
+		partKeys.push(emptyKey);
+	}
+	const envelope = {
+		version: 1,
+		id: CANONICAL_DAILY_ROLLUP_FINAL_ID,
+		builtAt,
+		windowDays: queryCanonicalDailyRollup.windowDays,
+		payload: {
+			parquetKey: partKeys[0],
+			parquetKeys: partKeys,
+			rowCount: 0
+		}
+	};
+	await dataSource.write(rollupKey(ctx, CANONICAL_DAILY_ROLLUP_FINAL_ID, builtAt, searchType), encodeJsonBigintSafe(envelope));
+	return {
+		done: true,
+		nextWindowOffset,
+		nextPageOffset,
+		windowsTotal,
+		windowsBuilt: nextWindowOffset - windowOffset,
+		rowsWritten
+	};
+}
+export { queryCanonicalDailyRollup, queryCanonicalVariantsRollup, rebuildCanonicalDailyResumable };

package/dist/rollups/core.d.mts

@@ -0,0 +1,201 @@
+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 { TenantCtx } from "@gscdump/contracts";
+import { SearchType } from "gscdump/query";
+interface RollupCtx extends TenantCtx {
+  /** When the rollup was built. Stamped into payload + filename. */
+  builtAt: number;
+}
+/**
+ * Tenant-scoped engine surface a rollup builder needs. Subset of
+ * `StorageEngine.runSQL` so rollups stay testable without a full engine.
+ */
+interface RollupEngine {
+  runSQL: (opts: {
+    ctx: TenantCtx;
+    fileSets: Record<string, FileSetRef>;
+    table?: TableName$1;
+    sql: string;
+    params?: unknown[];
+    /**
+     * Restrict every manifest lookup to a single GSC search-type slice. The
+     * rollup runner forwards `RebuildRollupsOptions.searchType` so the
+     * aggregated facts never mix web + non-web rows. Undefined preserves
+     * the legacy cross-type union (web-only tenants).
+     */
+    searchType?: SearchType;
+  }) => Promise<{
+    rows: Row$1[];
+  }>;
+  /**
+   * Read the live manifest for a (tenant, table[, searchType]) cohort —
+   * cheap, no parquet decode. Builders use this to chunk a full-history scan
+   * into byte-bounded windows (see `WINDOW_BYTE_BUDGET`) so a single `runSQL`
+   * call never ships an oversized Arrow IPC payload across the Workers
+   * service-binding RPC (32MiB hard cap).
+   */
+  listPartitions: (opts: {
+    ctx: TenantCtx;
+    table: TableName$1;
+    searchType?: SearchType;
+  }) => Promise<Array<{
+    partition: string;
+    bytes: number;
+  }>>;
+}
+/**
+ * One rollup definition. Build runs SQL over the tenant's facts and/or reads
+ * from entity stores via `dataSource`, returning a JSON-serializable payload
+ * that the runner timestamps + writes.
+ */
+interface RollupDef {
+  id: string;
+  /**
+   * Window in days the rollup covers. `null` means full history. Used by
+   * the runner to populate `windowDays` in the payload metadata so readers
+   * can validate freshness.
+   */
+  windowDays: number | null;
+  /**
+   * Storage format. `'json'` (default) wraps the build payload in a
+   * `RollupEnvelope` and writes as a JSON blob. `'parquet'` expects `build`
+   * to return rows matching `parquetColumns` and writes a parquet file plus
+   * a tiny JSON sidecar envelope that points at it, so metadata
+   * (`builtAt` / `windowDays`) stays readable without decoding parquet.
+   */
+  format?: 'json' | 'parquet';
+  /**
+   * Column schema for parquet output. Required when `format === 'parquet'`.
+   * Types map the same way as the fact-table encoder: VARCHAR / DATE go
+   * through BYTE_ARRAY/UTF8; BIGINT → INT64; INTEGER → INT32; DOUBLE → DOUBLE.
+   */
+  parquetColumns?: readonly ColumnDef[];
+  /** Sort-key column names for parquet row-group stats. Optional. */
+  parquetSortKey?: readonly string[];
+  /**
+   * When true, this rollup's payload is independent of GSC slice (e.g. entity
+   * rollups sourced from sitemap / indexing snapshots, not slice-partitioned
+   * fact tables). The runner rejects calls that pass `searchType` alongside
+   * a slice-orthogonal def so the output never lands under a per-slice prefix
+   * that the read path won't look at.
+   */
+  sliceOrthogonal?: boolean;
+  build: (deps: {
+    engine: RollupEngine;
+    ctx: TenantCtx;
+    /**
+     * Tenant-scoped object store. Rollups that aggregate over entity
+     * snapshots (e.g. indexing metadata) read JSON docs through this.
+     * Pure-SQL rollups can ignore it.
+     */
+    dataSource: DataSource;
+    /**
+     * UTC millis the trailing window anchors to — its inclusive END. Equals
+     * the newest synced/finalized data date when the runner is given
+     * `dataEndDate`, otherwise wall-clock build time. Builders derive window
+     * cutoffs from this (e.g. the trailing-28d boundary) and inline a date
+     * literal so the SQL stays portable across DuckDB builds without the ICU
+     * extension (Workers DuckDB — `CURRENT_DATE` lives in ICU).
+     */
+    windowAnchorMs: number;
+    /**
+     * GSC search-type slice the runner was invoked for. Builders forward
+     * this to every `engine.runSQL` call so the aggregated facts come
+     * from one cohort. Undefined preserves the legacy cross-type union
+     * (used by web-only tenants and admin paths).
+     */
+    searchType?: SearchType;
+  }) => Promise<unknown>;
+}
+/**
+ * Wire shape persisted to R2/disk. Readers can rely on the `version` + `builtAt`.
+ * Parquet rollups write this envelope as a sidecar whose `payload` points at
+ * the co-located `.parquet` object via `{ parquetKey, rowCount }`.
+ */
+interface RollupEnvelope<T = unknown> {
+  version: 1;
+  id: string;
+  builtAt: number;
+  windowDays: number | null;
+  payload: T;
+}
+interface ParquetRollupPointer {
+  parquetKey: string;
+  rowCount: number;
+  /**
+   * MULTI-FILE rollup: when set, the rollup is the UNION of these parquet keys
+   * (disjoint by the grain's partition column, e.g. `date` for the resumable
+   * `query_canonical_daily` build). Readers MUST union all keys; `parquetKey`
+   * stays populated (the first part) for single-file readers. Avoids a JS
+   * merge/re-encode of the whole rollup — the scaling bottleneck for a
+   * cross-invocation resumable build.
+   */
+  parquetKeys?: string[];
+}
+declare function rollupKey(ctx: TenantCtx, id: string, builtAt: number, searchType?: SearchType): string;
+declare function rollupParquetKey(ctx: TenantCtx, id: string, builtAt: number, searchType?: SearchType): string;
+interface RollupBucket {
+  list: (opts: {
+    prefix: string;
+    cursor?: string;
+  }) => Promise<{
+    objects: Array<{
+      key: string;
+    }>;
+    truncated?: boolean;
+    cursor?: string;
+  }>;
+  get: (key: string) => Promise<{
+    text: () => Promise<string>;
+  } | null>;
+}
+declare function readLatestRollup<T = unknown>(bucket: RollupBucket, ctx: TenantCtx, id: string, searchType?: SearchType): Promise<RollupEnvelope<T> | null>;
+interface RebuildRollupsOptions {
+  engine: RollupEngine;
+  dataSource: DataSource;
+  ctx: TenantCtx;
+  defs: readonly RollupDef[];
+  now?: () => number;
+  /**
+   * Build rollups for a single GSC search-type slice. Threads into every
+   * builder's `engine.runSQL` call so the aggregated facts come from one
+   * cohort, and namespaces the output object keys under a `<searchType>/`
+   * segment so per-slice rollups coexist without overwriting each other.
+   * Undefined preserves the legacy cross-type behaviour (one rollup over
+   * the union of all slices, written to the legacy path) — fine for web-
+   * only tenants and explicit cross-type admin views.
+   */
+  searchType?: SearchType;
+  /**
+   * ISO date (`YYYY-MM-DD`) of the newest synced/finalized day. Trailing-
+   * window rollups (28d/90d) anchor their window END here instead of
+   * wall-clock build time, so a "last 28 days" rollup covers the 28 days of
+   * data that actually exist — not 28 days back from whenever the job ran,
+   * which would include GSC's 2-3 day empty tail. Omit for the legacy
+   * wall-clock behaviour.
+   */
+  dataEndDate?: string;
+}
+interface RebuildRollupResult {
+  id: string;
+  /** JSON envelope key. For parquet rollups this is the sidecar pointer. */
+  objectKey: string;
+  /** Parquet payload key. Present only when `format === 'parquet'`. */
+  parquetKey?: string;
+  /** Envelope byte size; for parquet rollups does NOT include parquet bytes. */
+  bytes: number;
+  /** Parquet payload byte size when `format === 'parquet'`. */
+  parquetBytes?: number;
+  builtAt: number;
+  /**
+   * Set when this def's build/encode/write failed. The runner records the
+   * failure and continues with the remaining defs so one bad rollup never
+   * aborts the rest. Successful defs have no `error`. The human-readable
+   * message (including the stack when available) lives on `error.message`.
+   */
+  error?: EngineError;
+}
+declare function rebuildRollups(opts: RebuildRollupsOptions): Promise<RebuildRollupResult[]>;
+export { ParquetRollupPointer, RebuildRollupResult, RebuildRollupsOptions, RollupBucket, RollupCtx, RollupDef, RollupEngine, RollupEnvelope, readLatestRollup, rebuildRollups, rollupKey, rollupParquetKey };