@gscdump/cloudflare 1.3.2 → 1.4.1

package/dist/server-tail/archetype-sql.mjs

@@ -0,0 +1,345 @@
+const TABLE_PLACEHOLDER = "{{TABLE}}";
+const FACT_ALIAS = "fact";
+function factTableRef() {
+	return `${TABLE_PLACEHOLDER} AS ${FACT_ALIAS}`;
+}
+function dimColumn(dim) {
+	if (dim === "page") return "url";
+	if (dim === "queryCanonical") return `COALESCE((SELECT qd.query_canonical FROM query_dim qd WHERE qd.query = ${FACT_ALIAS}.query LIMIT 1), ${FACT_ALIAS}.query)`;
+	return dim;
+}
+function dimSelect(dim) {
+	const col = dimColumn(dim);
+	return dim === "queryCanonical" ? `${col} AS queryCanonical` : col;
+}
+function tableForDimensions(dims) {
+	const set = new Set(dims.filter((d) => d !== "date"));
+	if (set.has("page") && (set.has("query") || set.has("queryCanonical"))) return "page_queries";
+	if (set.has("query") || set.has("queryCanonical")) return "queries";
+	if (set.has("country")) return "countries";
+	if (set.has("device")) return "dates";
+	return "pages";
+}
+function tableForTopNBreakdown(q) {
+	const dims = [q.dimension];
+	for (const facet of q.facets ?? []) {
+		const hasPage = q.dimension === "page" || facet.column === "page";
+		const hasQuery = q.dimension === "query" || q.dimension === "queryCanonical" || facet.column === "query" || facet.column === "queryCanonical";
+		if (hasPage && hasQuery) dims.push(facet.column);
+	}
+	return tableForDimensions(dims);
+}
+function metricExpr(metric) {
+	switch (metric) {
+		case "clicks": return "SUM(clicks) AS clicks";
+		case "impressions": return "SUM(impressions) AS impressions";
+		case "ctr": return "SUM(clicks) / NULLIF(SUM(impressions), 0) AS ctr";
+		case "position": return "SUM(sum_position) / NULLIF(SUM(impressions), 0) + 1 AS position";
+		default: throw new Error(`[archetype-sql] unknown metric: ${JSON.stringify(metric)}`);
+	}
+}
+function metricAlias(metric) {
+	switch (metric) {
+		case "clicks":
+		case "impressions":
+		case "ctr":
+		case "position": return metric;
+		default: throw new Error(`[archetype-sql] unknown order metric: ${JSON.stringify(metric)}`);
+	}
+}
+const DEVICE_SUFFIXES = [
+	"desktop",
+	"mobile",
+	"tablet"
+];
+function metricExprForSource(metric, source) {
+	switch (metric) {
+		case "clicks": return `SUM(${source.clicks}) AS clicks`;
+		case "impressions": return `SUM(${source.impressions}) AS impressions`;
+		case "ctr": return `SUM(${source.clicks}) / NULLIF(SUM(${source.impressions}), 0) AS ctr`;
+		case "position": return `SUM(${source.sumPosition}) / NULLIF(SUM(${source.impressions}), 0) + 1 AS position`;
+		default: throw new Error(`[archetype-sql] unknown metric: ${JSON.stringify(metric)}`);
+	}
+}
+function deviceSource(suffix) {
+	return {
+		clicks: `clicks_${suffix}`,
+		impressions: `impressions_${suffix}`,
+		sumPosition: `sum_position_${suffix}`
+	};
+}
+const STD_METRICS = [
+	"clicks",
+	"impressions",
+	"ctr",
+	"position"
+];
+function coalesceMetric(metric, src, alias) {
+	const ref = `${src}.${metric}`;
+	return metric === "clicks" || metric === "impressions" ? `CAST(COALESCE(${ref}, 0) AS DOUBLE) AS ${alias}` : `COALESCE(${ref}, 0) AS ${alias}`;
+}
+function prevAlias(metric) {
+	return `prev${metric.charAt(0).toUpperCase()}${metric.slice(1)}`;
+}
+function moverClause(movers) {
+	const curClicks = "COALESCE(c.clicks, 0)";
+	const prevClicks = "COALESCE(p.clicks, 0)";
+	const curImpr = "COALESCE(c.impressions, 0)";
+	const prevImpr = "COALESCE(p.impressions, 0)";
+	switch (movers) {
+		case "improving": return { where: `${curClicks} > ${prevClicks}` };
+		case "declining": return { where: `${curClicks} < ${prevClicks}` };
+		case "new": return { where: `${prevImpr} = 0 AND ${curImpr} > 0` };
+		case "lost": return { where: `${curImpr} = 0 AND ${prevImpr} > 0` };
+		default: throw new Error(`[archetype-sql] unknown movers mode: ${movers}`);
+	}
+}
+function moverOrderByAlias(movers) {
+	switch (movers) {
+		case "improving": return "(clicks - prevClicks) DESC";
+		case "declining": return "(clicks - prevClicks) ASC";
+		case "new": return "clicks DESC, impressions DESC";
+		case "lost": return "prevImpressions DESC";
+		default: throw new Error(`[archetype-sql] unknown movers mode: ${movers}`);
+	}
+}
+function sqlStringLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function partitionWhere(q, partitionPruned = false, mode = "bare") {
+	if (partitionPruned) return {
+		clause: "date BETWEEN ? AND ?",
+		params: [q.range.start, q.range.end]
+	};
+	return {
+		clause: `${mode === "r2-sql-concat" ? "CONCAT(site_id, '')" : "site_id"} = ? AND ${mode === "r2-sql-concat" ? "CONCAT(search_type, '')" : "search_type"} = ? AND date BETWEEN ? AND ?`,
+		params: [
+			q.siteId,
+			q.searchType,
+			q.range.start,
+			q.range.end
+		]
+	};
+}
+function facetPredicate(query) {
+	const facets = query.facets;
+	if (!facets?.length) return {
+		sql: "",
+		params: []
+	};
+	const parts = [];
+	const params = [];
+	for (const f of facets) {
+		const col = dimColumn(f.column);
+		switch (f.op) {
+			case "eq":
+				parts.push(`${col} = ?`);
+				params.push(f.value);
+				break;
+			case "regex":
+				parts.push(`regexp_matches(LOWER(${col}), ?)`);
+				params.push(f.value);
+				break;
+			case "notRegex":
+				parts.push(`NOT regexp_matches(LOWER(${col}), ?)`);
+				params.push(f.value);
+				break;
+			default: throw new Error(`[archetype-sql] unknown facet op: ${f.op}`);
+		}
+	}
+	return {
+		sql: parts.length ? ` AND ${parts.join(" AND ")}` : "",
+		params
+	};
+}
+function buildSiteDailyTimeseries(q, pruned, mode) {
+	const w = partitionWhere(q, pruned, mode);
+	const metrics = q.metrics.map(metricExpr).join(", ");
+	return {
+		table: "dates",
+		params: w.params,
+		sql: `SELECT date, ${metrics} FROM ${factTableRef()} WHERE ${w.clause} GROUP BY date ORDER BY date ASC`
+	};
+}
+function buildEntityDailyTimeseries(q, pruned, mode) {
+	const table = tableForDimensions([q.entity.dimension]);
+	const w = partitionWhere(q, pruned, mode);
+	const col = dimColumn(q.entity.dimension);
+	const metrics = q.metrics.map(metricExpr).join(", ");
+	return {
+		table,
+		params: [...w.params, q.entity.value],
+		sql: `SELECT date, ${metrics} FROM ${factTableRef()} WHERE ${w.clause} AND ${col} = ? GROUP BY date ORDER BY date ASC`
+	};
+}
+function buildEntityDailySparkline(q, pruned, mode) {
+	const table = tableForDimensions([q.dimension]);
+	const w = partitionWhere(q, pruned, mode);
+	const col = dimColumn(q.dimension);
+	if (q.entities.length === 0) throw new Error("entity-daily-sparkline: empty entities - resolver must pre-resolve the top-N list");
+	const inList = q.entities.map(sqlStringLiteral).join(", ");
+	return {
+		table,
+		params: w.params,
+		sql: `SELECT date, ${col} AS entity, ${metricExpr(q.metric)} FROM ${factTableRef()} WHERE ${w.clause} AND ${col} IN (${inList}) GROUP BY date, ${col} ORDER BY date ASC`
+	};
+}
+function buildTopNBreakdown(q, pruned, mode) {
+	const table = tableForTopNBreakdown(q);
+	const w = partitionWhere(q, pruned, mode);
+	if (!q.orderBy || !q.orderBy.metric || !q.orderBy.dir) throw new Error(`[archetype-sql] top-n-breakdown requires orderBy.{metric,dir}, got: ${JSON.stringify(q.orderBy)}`);
+	const order = `${metricAlias(q.orderBy.metric)} ${q.orderBy.dir.toUpperCase()}`;
+	const limit = `LIMIT ${Math.max(0, Math.floor(q.limit))}`;
+	const offset = q.offset && q.offset > 0 ? ` OFFSET ${Math.floor(q.offset)}` : "";
+	const metricList0 = q.metrics.includes(q.orderBy.metric) ? q.metrics : [...q.metrics, q.orderBy.metric];
+	const metricList = q.compareRange && q.movers ? [.../* @__PURE__ */ new Set([
+		...metricList0,
+		"clicks",
+		"impressions"
+	])] : metricList0;
+	const variantSel = q.dimension === "queryCanonical" ? ", COUNT(DISTINCT query) AS variantCount" : "";
+	if (q.dimension === "device") {
+		if (q.compareRange) {
+			const wPrev = partitionWhere({
+				...q,
+				range: q.compareRange
+			}, pruned, mode);
+			const deviceSelects = (clause, ml) => DEVICE_SUFFIXES.map((suffix) => {
+				const source = deviceSource(suffix);
+				const metrics = ml.map((m) => metricExprForSource(m, source)).join(", ");
+				return `SELECT '${suffix.toUpperCase()}' AS device, ${metrics} FROM ${factTableRef()} WHERE ${clause}`;
+			}).join(" UNION ALL ");
+			const inner = `SELECT COALESCE(c.device, p.device) AS device, ${metricList.map((m) => coalesceMetric(m, "c", m)).join(", ")}, ${STD_METRICS.map((m) => coalesceMetric(m, "p", prevAlias(m))).join(", ")} FROM cur c FULL OUTER JOIN prev p ON c.device = p.device`;
+			const sql = `WITH cur AS (${deviceSelects(w.clause, metricList)}), prev AS (${deviceSelects(wPrev.clause, STD_METRICS)}) SELECT * FROM (${inner}) t ORDER BY ${order} ${limit}${offset}`;
+			return {
+				table,
+				params: [...DEVICE_SUFFIXES.flatMap(() => w.params), ...DEVICE_SUFFIXES.flatMap(() => wPrev.params)],
+				sql
+			};
+		}
+		const sql = `${DEVICE_SUFFIXES.map((suffix) => {
+			const source = deviceSource(suffix);
+			const metrics = metricList.map((m) => metricExprForSource(m, source)).join(", ");
+			return `SELECT '${suffix.toUpperCase()}' AS device, ${metrics} FROM ${factTableRef()} WHERE ${w.clause}`;
+		}).join(" UNION ALL ")} ORDER BY ${order} ${limit}${offset}`;
+		return {
+			table,
+			params: DEVICE_SUFFIXES.flatMap(() => w.params),
+			sql
+		};
+	}
+	const col = dimColumn(q.dimension);
+	const facet = facetPredicate(q);
+	const totalCol = q.includeTotal ? ", COUNT(*) OVER() AS __total" : "";
+	if (q.compareRange) {
+		const wPrev = partitionWhere({
+			...q,
+			range: q.compareRange
+		}, pruned, mode);
+		const curMetrics = metricList.map(metricExpr).join(", ");
+		const prevMetrics = STD_METRICS.map((m) => metricExpr(m)).join(", ");
+		const curCols = metricList.map((m) => coalesceMetric(m, "c", m)).join(", ");
+		const prevCols = STD_METRICS.map((m) => coalesceMetric(m, "p", prevAlias(m))).join(", ");
+		const variantOut = q.dimension === "queryCanonical" ? ", c.variantCount AS variantCount" : "";
+		const moverWhere = q.movers ? `WHERE ${moverClause(q.movers).where} ` : "";
+		const outerOrder = q.movers ? moverOrderByAlias(q.movers) : order;
+		const inner = `SELECT COALESCE(c.k, p.k) AS ${q.dimension}, ${curCols}, ${prevCols}${variantOut}${totalCol} FROM cur c FULL OUTER JOIN prev p ON c.k = p.k ${moverWhere}`;
+		const sql = `WITH cur AS (SELECT ${col} AS k, ${curMetrics}${variantSel} FROM ${factTableRef()} WHERE ${w.clause}${facet.sql} GROUP BY ${col}), prev AS (SELECT ${col} AS k, ${prevMetrics} FROM ${factTableRef()} WHERE ${wPrev.clause}${facet.sql} GROUP BY ${col}) SELECT * FROM (${inner}) t ORDER BY ${outerOrder} ${limit}${offset}`;
+		return {
+			table,
+			params: [
+				...w.params,
+				...facet.params,
+				...wPrev.params,
+				...facet.params
+			],
+			sql
+		};
+	}
+	const metrics = metricList.map(metricExpr).join(", ");
+	const sql = `SELECT ${dimSelect(q.dimension)}, ${metrics}${variantSel}${totalCol} FROM ${factTableRef()} WHERE ${w.clause}${facet.sql} GROUP BY ${col} ORDER BY ${order} ${limit}${offset}`;
+	return {
+		table,
+		params: [...w.params, ...facet.params],
+		sql
+	};
+}
+function buildSingleRowLookup(q, pruned, mode) {
+	const dims = Object.keys(q.match);
+	const table = tableForDimensions(dims);
+	const w = partitionWhere(q, pruned, mode);
+	const params = [...w.params];
+	let clause = w.clause;
+	for (const dim of dims) {
+		clause += ` AND ${dimColumn(dim)} = ?`;
+		params.push(q.match[dim]);
+	}
+	const metrics = q.metrics.map(metricExpr).join(", ");
+	const groupBy = dims.length > 0 ? ` GROUP BY ${dims.map(dimColumn).join(", ")}` : "";
+	return {
+		table,
+		params,
+		sql: `SELECT ${dims.length > 0 ? `${dims.map(dimSelect).join(", ")}, ${metrics}` : metrics} FROM ${factTableRef()} WHERE ${clause}${groupBy}`
+	};
+}
+function buildMultiSeriesStackedDaily(q, pruned, mode) {
+	const table = tableForDimensions([q.seriesDimension]);
+	const w = partitionWhere(q, pruned, mode);
+	if (q.seriesDimension === "device") {
+		const selects = DEVICE_SUFFIXES.map((suffix) => {
+			const source = deviceSource(suffix);
+			return `SELECT date, '${suffix.toUpperCase()}' AS device, ${metricExprForSource(q.metric, source)} FROM ${factTableRef()} WHERE ${w.clause} GROUP BY date`;
+		});
+		return {
+			table,
+			params: DEVICE_SUFFIXES.flatMap(() => w.params),
+			sql: `${selects.join(" UNION ALL ")} ORDER BY date ASC, device ASC`
+		};
+	}
+	const col = dimColumn(q.seriesDimension);
+	return {
+		table,
+		params: w.params,
+		sql: `SELECT date, ${dimSelect(q.seriesDimension)}, ${metricExpr(q.metric)} FROM ${factTableRef()} WHERE ${w.clause} GROUP BY date, ${col} ORDER BY date ASC`
+	};
+}
+function buildTwoDimensionDetail(q, pruned, mode) {
+	const w = partitionWhere(q, pruned, mode);
+	const params = [...w.params];
+	let clause = w.clause;
+	if (q.filter?.page) {
+		clause += ` AND url = ?`;
+		params.push(q.filter.page);
+	}
+	if (q.filter?.query) {
+		clause += ` AND query = ?`;
+		params.push(q.filter.query);
+	}
+	const facet = facetPredicate(q);
+	clause += facet.sql;
+	params.push(...facet.params);
+	let sql = `SELECT url, query, ${(q.orderBy && !q.metrics.includes(q.orderBy.metric) ? [...q.metrics, q.orderBy.metric] : q.metrics).map(metricExpr).join(", ")} FROM ${factTableRef()} WHERE ${clause} GROUP BY url, query`;
+	if (q.orderBy) sql += ` ORDER BY ${metricAlias(q.orderBy.metric)} ${q.orderBy.dir.toUpperCase()}`;
+	if (q.limit && q.limit > 0) sql += ` LIMIT ${Math.floor(q.limit)}`;
+	return {
+		table: "page_queries",
+		params,
+		sql
+	};
+}
+function buildArchetypeSql(query, opts = {}) {
+	const pruned = opts.partitionPruned ?? false;
+	const mode = opts.partitionPredicateMode ?? (opts.partitionKeyEncoding === "string" ? "r2-sql-concat" : "bare");
+	switch (query.archetype) {
+		case "site-daily-timeseries": return buildSiteDailyTimeseries(query, pruned, mode);
+		case "entity-daily-timeseries": return buildEntityDailyTimeseries(query, pruned, mode);
+		case "entity-daily-sparkline": return buildEntityDailySparkline(query, pruned, mode);
+		case "top-n-breakdown": return buildTopNBreakdown(query, pruned, mode);
+		case "single-row-lookup": return buildSingleRowLookup(query, pruned, mode);
+		case "multi-series-stacked-daily": return buildMultiSeriesStackedDaily(query, pruned, mode);
+		case "two-dimension-detail": return buildTwoDimensionDetail(query, pruned, mode);
+		case "arbitrary-sql": throw new Error("buildArchetypeSql: arbitrary-sql carries caller SQL - the DuckDB executor runs it verbatim");
+		case "aux-cloud-only": throw new Error("buildArchetypeSql: aux-cloud-only is not an Iceberg query");
+	}
+}
+export { TABLE_PLACEHOLDER, buildArchetypeSql };

package/dist/server-tail/dispatcher.d.mts

@@ -0,0 +1,47 @@
+import { DuckDbIcebergExecutor } from "./duckdb-iceberg-executor.mjs";
+import { R2SqlClient } from "./r2-sql-client.mjs";
+import { ArchetypeQuery, ArchetypeResult, ArchetypeResultRow } from "@gscdump/contracts/archetypes";
+import { Result } from "gscdump/result";
+import { ServerTailDirective } from "@gscdump/contracts";
+/** The two engines the server tail can route to. */
+type ServerTailEngine = 'r2-sql' | 'duckdb';
+/** Executors the dispatcher routes between. */
+interface ServerTailDispatcherConfig {
+  r2Sql: R2SqlClient;
+  duckdb: DuckDbIcebergExecutor;
+}
+declare class ServerTailRoutingError extends Error {
+  name: string;
+}
+/**
+ * Errors-as-values core for {@link resolveServerTailEngine}: returns a
+ * `ServerTailRoutingError` instead of throwing when an archetype is `cloud-only`
+ * (the one caller-actionable routing failure — the consumer must route that
+ * query through the cloud endpoints, not the server tail). Pure — no I/O.
+ */
+declare function resolveServerTailEngineResult(query: ArchetypeQuery): Result<ServerTailEngine, ServerTailRoutingError>;
+/**
+ * Decide which engine answers an archetype query. Pure — no I/O. Exposed so
+ * the file-resolution endpoint can compute the `ServerTailDirective.engine`
+ * with the SAME logic the dispatcher uses at execution time. Throws
+ * `ServerTailRoutingError` for a `cloud-only` archetype; see
+ * {@link resolveServerTailEngineResult} for the errors-as-values core.
+ */
+declare function resolveServerTailEngine(query: ArchetypeQuery): ServerTailEngine;
+/** A configured server-tail dispatcher. */
+interface ServerTailDispatcher {
+  /** Decide the engine for a query without running it. */
+  route: (query: ArchetypeQuery) => ServerTailEngine;
+  /**
+   * Execute a query, routing by execution class. If `directive` is supplied
+   * its `engine` is honoured only when consistent with the archetype's class
+   * (a `duckdb`-class archetype always runs on DuckDB regardless).
+   */
+  execute: <R extends ArchetypeResultRow = ArchetypeResultRow>(query: ArchetypeQuery, directive?: ServerTailDirective) => Promise<ArchetypeResult<R>>;
+}
+/**
+ * Create the server-tail dispatcher. Holds an R2 SQL client and a DuckDB
+ * executor and routes every `ArchetypeQuery` to one of them.
+ */
+declare function createServerTailDispatcher(config: ServerTailDispatcherConfig): ServerTailDispatcher;
+export { ServerTailDispatcher, ServerTailDispatcherConfig, ServerTailEngine, ServerTailRoutingError, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };

package/dist/server-tail/dispatcher.mjs

@@ -0,0 +1,87 @@
+import { ARCHETYPE_EXECUTION_CLASS } from "@gscdump/contracts/archetypes";
+import { err, ok, unwrapResult } from "gscdump/result";
+var ServerTailRoutingError = class extends Error {
+	name = "ServerTailRoutingError";
+};
+function routingErrorToException(error) {
+	return error;
+}
+function hasRegexFacet(query) {
+	return query.facets?.some((f) => f.op === "regex" || f.op === "notRegex") ?? false;
+}
+function referencesQueryDim(query) {
+	const q = query;
+	if (q.dimension === "queryCanonical" || q.seriesDimension === "queryCanonical") return true;
+	if (q.entity?.dimension === "queryCanonical") return true;
+	if (q.match && "queryCanonical" in q.match) return true;
+	return q.facets?.some((f) => f.column === "queryCanonical") ?? false;
+}
+function resolveServerTailEngineResult(query) {
+	const cls = ARCHETYPE_EXECUTION_CLASS[query.archetype];
+	if (cls === "cloud-only") return err(new ServerTailRoutingError(`archetype '${query.archetype}' is cloud-only — not a server-tail query`));
+	if (cls === "duckdb") return ok("duckdb");
+	if (query.archetype === "top-n-breakdown" && query.offset && query.offset > 0) return ok("duckdb");
+	if (referencesQueryDim(query)) return ok("duckdb");
+	if (hasRegexFacet(query)) return ok("duckdb");
+	return ok("r2-sql");
+}
+function resolveServerTailEngine(query) {
+	return unwrapResult(resolveServerTailEngineResult(query), routingErrorToException);
+}
+function sourceFor(engine) {
+	return engine === "r2-sql" ? "server-r2-sql" : "server-duckdb";
+}
+function extractTotal(rows) {
+	if (!rows.length || !("__total" in rows[0])) return { rows };
+	const totalRows = Number(rows[0].__total) || 0;
+	return {
+		rows: rows.map((r) => {
+			const { __total, ...rest } = r;
+			return rest;
+		}),
+		totalRows
+	};
+}
+function createServerTailDispatcher(config) {
+	function route(query) {
+		return resolveServerTailEngine(query);
+	}
+	async function execute(query, directive) {
+		const engine = route(query);
+		if (directive && directive.engine !== engine && engine === "r2-sql") return runOn("duckdb", query);
+		return runOn(engine, query);
+	}
+	async function runOn(engine, query) {
+		if (engine === "r2-sql") {
+			const res = await config.r2Sql.runArchetype(query);
+			const { rows, totalRows } = extractTotal(res.rows);
+			return {
+				archetype: query.archetype,
+				rows,
+				source: sourceFor("r2-sql"),
+				meta: {
+					rowCount: rows.length,
+					queryMs: res.queryMs,
+					...totalRows !== void 0 ? { totalRows } : {}
+				}
+			};
+		}
+		const res = await config.duckdb.runArchetype(query);
+		const { rows, totalRows } = extractTotal(res.rows);
+		return {
+			archetype: query.archetype,
+			rows,
+			source: sourceFor("duckdb"),
+			meta: {
+				rowCount: rows.length,
+				queryMs: res.queryMs,
+				...totalRows !== void 0 ? { totalRows } : {}
+			}
+		};
+	}
+	return {
+		route,
+		execute
+	};
+}
+export { ServerTailRoutingError, createServerTailDispatcher, resolveServerTailEngine, resolveServerTailEngineResult };

package/dist/server-tail/duckdb-iceberg-executor.d.mts

@@ -0,0 +1,88 @@
+import { ArchetypeSqlPlan } from "./archetype-sql.mjs";
+import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
+import { Result } from "gscdump/result";
+/** Row returned by the DuckDB sibling. */
+type DuckDbIcebergRow = Record<string, string | number | null>;
+/**
+ * The minimal `DUCKDB_SVC` shape this executor needs — a structural subset of
+ * the binding in `workers-duckdb.ts` / `env.ts`. Any binding with `runSQL`
+ * satisfies it.
+ */
+interface DuckDbSvc {
+  runSQL: (args: {
+    sql: string;
+    deadlineAt?: number;
+  }) => Promise<{
+    rows: unknown[];
+    sql: string;
+  }>;
+}
+/** Configuration for the DuckDB-over-Iceberg executor. */
+interface DuckDbIcebergExecutorConfig {
+  /** The DuckDB service binding (the sibling Worker RPC). */
+  svc: DuckDbSvc;
+  /**
+   * R2 Data Catalog warehouse identifier. The sibling resolves Iceberg table
+   * locations from `<warehouse>` + `<namespace>` + table name.
+   */
+  warehouse: string;
+  /** Iceberg namespace the 5 fact tables live in. */
+  namespace: string;
+  /**
+   * How the sibling addresses an Iceberg table in a `FROM` clause. Defaults to
+   * DuckDB's `iceberg_scan('<warehouse>/<namespace>/<table>')`. Overridable so
+   * a sibling configured with the Iceberg REST catalog can use
+   * `iceberg_scan('<namespace>.<table>')` or an attached-catalog reference.
+   */
+  tableRefStyle?: 'path' | 'catalog';
+  /** Per-query wall-clock deadline (ms). Default 25s. */
+  timeoutMs?: number;
+}
+/** Result of a DuckDB-over-Iceberg query. */
+interface DuckDbIcebergResult {
+  rows: DuckDbIcebergRow[];
+  /** The exact SQL sent to the sibling. */
+  sql: string;
+  queryMs: number;
+}
+declare class DuckDbIcebergError extends Error {
+  name: string;
+}
+declare class DuckDbIcebergTimeoutError extends Error {
+  name: string;
+  constructor(timeoutMs: number);
+}
+/**
+ * The modelled, caller-actionable failure channel for a DuckDB-over-Iceberg
+ * query. As with the R2 SQL client, callers branch on which class came back: a
+ * `DuckDbIcebergTimeoutError` is the retry-able deadline overrun, a
+ * `DuckDbIcebergError` is a hard sibling-RPC failure (or the `aux-cloud-only`
+ * routing reject). The error variant IS the existing throwable class, so the
+ * throwing wrappers preserve the identity/message tests assert
+ * (`rejects.toThrow(/OOM in sibling/)`, `rejects.toThrow(DuckDbIcebergError)`).
+ */
+type DuckDbIcebergQueryError = DuckDbIcebergError | DuckDbIcebergTimeoutError;
+/** A configured DuckDB-over-Iceberg executor. */
+interface DuckDbIcebergExecutor {
+  /** Run a raw SQL string with `{{TABLE_<name>}}` placeholders resolved. */
+  runSql: (sql: string, params?: readonly unknown[]) => Promise<DuckDbIcebergResult>;
+  /** Run a dialect-neutral plan: resolve `{{TABLE}}`, bind params, send. */
+  runPlan: (plan: ArchetypeSqlPlan) => Promise<DuckDbIcebergResult>;
+  /** Translate + run an archetype query. Handles `arbitrary-sql` verbatim. */
+  runArchetype: (query: ArchetypeQuery) => Promise<DuckDbIcebergResult>;
+  /**
+   * Errors-as-values core for {@link DuckDbIcebergExecutor.runArchetype}:
+   * returns the modelled timeout-vs-hard-fail `DuckDbIcebergQueryError` instead
+   * of throwing, so the dispatcher can branch on retry-ability (a timeout may be
+   * worth a fallback) without `instanceof` over a `catch`. Optional so a
+   * hand-rolled executor (e.g. a host app's own service-binding executor) can
+   * implement only the throwing surface; {@link createDuckDbIcebergExecutor}
+   * always provides it.
+   */
+  runArchetypeResult?: (query: ArchetypeQuery) => Promise<Result<DuckDbIcebergResult, DuckDbIcebergQueryError>>;
+}
+/**
+ * Create a DuckDB-over-Iceberg-files executor.
+ */
+declare function createDuckDbIcebergExecutor(config: DuckDbIcebergExecutorConfig): DuckDbIcebergExecutor;
+export { DuckDbIcebergError, DuckDbIcebergExecutor, DuckDbIcebergExecutorConfig, DuckDbIcebergQueryError, DuckDbIcebergResult, DuckDbIcebergRow, DuckDbIcebergTimeoutError, DuckDbSvc, createDuckDbIcebergExecutor };

package/dist/server-tail/duckdb-iceberg-executor.mjs

@@ -0,0 +1,77 @@
+import { TABLE_PLACEHOLDER, buildArchetypeSql } from "./archetype-sql.mjs";
+import { bindLiterals } from "@gscdump/engine/sql";
+import { err, ok, unwrapResult } from "gscdump/result";
+var DuckDbIcebergError = class extends Error {
+	name = "DuckDbIcebergError";
+};
+var DuckDbIcebergTimeoutError = class extends Error {
+	name = "DuckDbIcebergTimeoutError";
+	constructor(timeoutMs) {
+		super(`DuckDB-over-Iceberg query exceeded ${timeoutMs}ms deadline`);
+	}
+};
+function duckDbIcebergErrorToException(error) {
+	return error;
+}
+const DEFAULT_TIMEOUT_MS = 25e3;
+function icebergTableRef(config, table) {
+	if (config.tableRefStyle === "catalog") return `${config.namespace}.${table}`;
+	return `iceberg_scan('${config.warehouse}/${config.namespace}/${table}')`;
+}
+function withDeadline(op, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new DuckDbIcebergTimeoutError(timeoutMs)), timeoutMs);
+		op.then(resolve, reject).finally(() => clearTimeout(timer));
+	});
+}
+function resolveTablePlaceholders(sql, config) {
+	return sql.replace(/\{\{(\w+)\}\}/g, (_, table) => icebergTableRef(config, table));
+}
+function createDuckDbIcebergExecutor(config) {
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	async function sendResult(sql) {
+		const started = Date.now();
+		const deadlineAt = Date.now() + timeoutMs;
+		const raced = await withDeadline(config.svc.runSQL({
+			sql,
+			deadlineAt
+		}), timeoutMs).then((value) => ok(value)).catch((error) => error instanceof DuckDbIcebergTimeoutError ? err(error) : err(new DuckDbIcebergError(`DUCKDB_SVC.runSQL failed: ${error.message}`)));
+		if (!raced.ok) return raced;
+		const result = raced.value;
+		return ok({
+			rows: result.rows ?? [],
+			sql: result.sql ?? sql,
+			queryMs: Date.now() - started
+		});
+	}
+	async function send(sql) {
+		return unwrapResult(await sendResult(sql), duckDbIcebergErrorToException);
+	}
+	function runSqlResult(sql, params = []) {
+		return sendResult(bindLiterals(resolveTablePlaceholders(sql, config), params));
+	}
+	function runSql(sql, params = []) {
+		return send(bindLiterals(resolveTablePlaceholders(sql, config), params));
+	}
+	function runPlan(plan) {
+		return send(bindLiterals(plan.sql.split(TABLE_PLACEHOLDER).join(icebergTableRef(config, plan.table)), plan.params));
+	}
+	function runPlanResult(plan) {
+		return sendResult(bindLiterals(plan.sql.split(TABLE_PLACEHOLDER).join(icebergTableRef(config, plan.table)), plan.params));
+	}
+	function runArchetypeResult(query) {
+		if (query.archetype === "arbitrary-sql") return runSqlResult(query.sql, query.params ?? []);
+		if (query.archetype === "aux-cloud-only") return Promise.resolve(err(new DuckDbIcebergError("aux-cloud-only is not an Iceberg query")));
+		return runPlanResult(buildArchetypeSql(query));
+	}
+	async function runArchetype(query) {
+		return unwrapResult(await runArchetypeResult(query), duckDbIcebergErrorToException);
+	}
+	return {
+		runSql,
+		runPlan,
+		runArchetype,
+		runArchetypeResult
+	};
+}
+export { DuckDbIcebergError, DuckDbIcebergTimeoutError, createDuckDbIcebergExecutor };