@gscdump/cloudflare 0.20.3 → 0.21.0

package/dist/index.d.mts

@@ -1,5 +1,7 @@
-import { DuckDBFactory, ParquetCodec, QueryExecutor, Row, createStorageEngine } from "@gscdump/engine";
+import { DuckDBFactory, IcebergTableName, ParquetCodec, QueryExecutor, Row, createStorageEngine } from "@gscdump/engine";
 import { H3Event } from "h3";
+import { ArchetypeQuery, ArchetypeResult, ArchetypeResultRow } from "@gscdump/sdk";
+import { ServerTailDirective } from "@gscdump/contracts";
 declare function getWasmDuckDBFactory(): DuckDBFactory;
 declare function resetWasmDuckDB(): void;
 interface AnalyticsEnv {
@@ -89,6 +91,187 @@ declare function createR2Presigner(env: AnalyticsEnv): ({
   bucket,
   expiresIn
 }: PresignOptions) => Promise<string>;
+/** Placeholder substituted for the engine-specific table reference. */
+declare const TABLE_PLACEHOLDER = "{{TABLE}}";
+/** A dialect-neutral SQL plan. */
+interface ArchetypeSqlPlan {
+  /** SQL with `{{TABLE}}` standing in for the table reference. */
+  sql: string;
+  /** Bound parameters, in `?`-order. */
+  params: unknown[];
+  /** The Iceberg fact table this query reads. */
+  table: IcebergTableName;
+}
+/**
+ * Translate an archetype query to a dialect-neutral SQL plan.
+ *
+ * Throws for `arbitrary-sql` (caller-supplied SQL, handled by the DuckDB
+ * executor directly) and `aux-cloud-only` (not an Iceberg query).
+ */
+declare function buildArchetypeSql(query: ArchetypeQuery): ArchetypeSqlPlan;
+/** 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;
+  }) => 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);
+}
+/** 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>;
+}
+/**
+ * Create a DuckDB-over-Iceberg-files executor.
+ */
+declare function createDuckDbIcebergExecutor(config: DuckDbIcebergExecutorConfig): DuckDbIcebergExecutor;
+/** Configuration for an R2 SQL client. */
+interface R2SqlClientConfig {
+  /** Cloudflare account id. */
+  accountId: string;
+  /** R2 Data Catalog warehouse name (`<bucket>` or `<account>_<bucket>`). */
+  warehouse: string;
+  /** Iceberg namespace the 5 fact tables live in. */
+  namespace: string;
+  /** Cloudflare API token with R2 Data Catalog read scope. */
+  token: string;
+  /**
+   * Override the HTTP endpoint base. Defaults to the public CF API. Tests
+   * point this at a local recorder.
+   */
+  apiBase?: string;
+  /**
+   * Injectable fetch. Defaults to global `fetch`. Tests pass a fake that
+   * returns a recorded CF envelope without a network round-trip.
+   */
+  fetchImpl?: typeof fetch;
+  /** Per-query wall-clock deadline (ms). Default 25s — under the Worker CPU budget. */
+  timeoutMs?: number;
+}
+/** A row as returned by R2 SQL — flat dimension + metric values. */
+type R2SqlRow = Record<string, string | number | null>;
+/** Result of an R2 SQL query. */
+interface R2SqlResult {
+  rows: R2SqlRow[];
+  /** The exact SQL sent (params already inlined). For diagnostics. */
+  sql: string;
+  /** Wall-clock duration of the HTTP round-trip. */
+  queryMs: number;
+}
+declare class R2SqlError extends Error {
+  readonly status?: number | undefined;
+  name: string;
+  constructor(message: string, status?: number | undefined);
+}
+declare class R2SqlTimeoutError extends Error {
+  name: string;
+  constructor(timeoutMs: number);
+}
+/**
+ * Escape a JS value for inline embedding in R2 SQL. R2 SQL has no bound-param
+ * channel, so `buildArchetypeSql`'s `?` placeholders are substituted here.
+ * Numbers go in bare; strings are single-quote-escaped; null → `NULL`.
+ */
+declare function escapeSqlValue(value: unknown): string;
+/**
+ * Inline a plan's `?`-bound params into its SQL, in order. R2 SQL accepts only
+ * a literal query string. Quote-aware so a `?` inside a string literal is not
+ * mistaken for a placeholder.
+ */
+declare function inlineParams(sql: string, params: readonly unknown[]): string;
+/** A configured R2 SQL client. */
+interface R2SqlClient {
+  /** Run a raw SQL string (table reference already resolved). */
+  query: (sql: string) => Promise<R2SqlResult>;
+  /** Run a dialect-neutral plan: resolve `{{TABLE}}`, inline params, send. */
+  runPlan: (plan: ArchetypeSqlPlan) => Promise<R2SqlResult>;
+  /** Translate + run an archetype query end to end. */
+  runArchetype: (query: ArchetypeQuery) => Promise<R2SqlResult>;
+}
+/**
+ * Create an R2 SQL client. The endpoint requires a real CF token in
+ * production; tests inject `fetchImpl` returning a recorded envelope.
+ */
+declare function createR2SqlClient(config: R2SqlClientConfig): R2SqlClient;
+/** 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;
+}
+/**
+ * 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.
+ */
+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;
 declare function signSizeHint(env: AnalyticsEnv, key: string, bytes: number): Promise<string>;
 declare function verifySizeHint(env: AnalyticsEnv, key: string, bytes: number, providedHex: string): Promise<boolean>;
 declare function createDucklingsCodec(_env: AnalyticsEnv): ParquetCodec;
@@ -98,4 +281,4 @@ interface DucklingsExecutorOptions {
   ipcTotalBytes?: number;
 }
 declare function createDucklingsExecutor(env: AnalyticsEnv, opts?: DucklingsExecutorOptions): QueryExecutor;
-export { type AnalyticsEngineHooks, type AnalyticsEnv, type HostedR2QueryKeyInput, type InflightDedupe, type PresignOptions, type Row, createDucklingsCodec, createDucklingsExecutor, createInflightDedupe, createR2Presigner, getAnalyticsEngine, getHostedR2QueryKey, getWasmDuckDBFactory, resetWasmDuckDB, signSizeHint, useAnalyticsEnv, verifySizeHint };
+export { type AnalyticsEngineHooks, type AnalyticsEnv, type ArchetypeSqlPlan, DuckDbIcebergError, type DuckDbIcebergExecutor, type DuckDbIcebergExecutorConfig, type DuckDbIcebergResult, type DuckDbIcebergRow, DuckDbIcebergTimeoutError, type DuckDbSvc, type HostedR2QueryKeyInput, type InflightDedupe, type PresignOptions, type R2SqlClient, type R2SqlClientConfig, R2SqlError, type R2SqlResult, type R2SqlRow, R2SqlTimeoutError, type Row, type ServerTailDispatcher, type ServerTailDispatcherConfig, type ServerTailEngine, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createDucklingsCodec, createDucklingsExecutor, createInflightDedupe, createR2Presigner, createR2SqlClient, createServerTailDispatcher, escapeSqlValue, getAnalyticsEngine, getHostedR2QueryKey, getWasmDuckDBFactory, inlineParams, resetWasmDuckDB, resolveServerTailEngine, signSizeHint, useAnalyticsEnv, verifySizeHint };

package/dist/index.mjs

@@ -1,10 +1,11 @@
-import { SCHEMAS, bindLiterals, coerceRow, createStorageEngine } from "@gscdump/engine";
+import { SCHEMAS, bindLiterals, coerceRow, createStorageEngine, inferTable } from "@gscdump/engine";
 import { createD1ManifestStore } from "@gscdump/engine-sqlite";
 import { createR2DataSource } from "@gscdump/engine/r2";
 import { createHyparquetCodec, decodeParquetToRows } from "@gscdump/engine/hyparquet";
 import { float64, int32, int64, tableFromArrays, tableToIPC, utf8 } from "@uwdata/flechette";
 import { createError } from "h3";
 import { AwsClient } from "aws4fetch";
+import { ARCHETYPE_EXECUTION_CLASS } from "@gscdump/sdk";
 let handle = null;
 async function initHandle() {
 	throw new Error("DuckDB-WASM handle not wired for Cloudflare Workers yet. Complete duckdb-wasm-handle.ts before enabling dual-write (user.migration_phase != 'd1').");
@@ -443,6 +444,405 @@ function createR2Presigner(env) {
 function encodeKey(key) {
 	return key.split("/").map(encodeURIComponent).join("/");
 }
+const TABLE_PLACEHOLDER = "{{TABLE}}";
+function dimColumn(dim) {
+	if (dim === "page") return "url";
+	if (dim === "queryCanonical") return "query_canonical";
+	return dim;
+}
+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) AS position";
+	}
+}
+function orderMetricExpr(metric) {
+	switch (metric) {
+		case "clicks": return "SUM(clicks)";
+		case "impressions": return "SUM(impressions)";
+		case "ctr": return "SUM(clicks) / NULLIF(SUM(impressions), 0)";
+		case "position": return "SUM(sum_position) / NULLIF(SUM(impressions), 0)";
+	}
+}
+function sqlStringLiteral(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function partitionWhere(q) {
+	return {
+		clause: "site_id = ? AND search_type = ? AND date BETWEEN ? AND ?",
+		params: [
+			q.siteId,
+			q.searchType,
+			q.range.start,
+			q.range.end
+		]
+	};
+}
+function buildSiteDailyTimeseries(q) {
+	const w = partitionWhere(q);
+	const metrics = q.metrics.map(metricExpr).join(", ");
+	return {
+		table: "dates",
+		params: w.params,
+		sql: `SELECT date, ${metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY date ORDER BY date ASC`
+	};
+}
+function buildEntityDailyTimeseries(q) {
+	const table = inferTable([q.entity.dimension]);
+	const w = partitionWhere(q);
+	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 ${TABLE_PLACEHOLDER} WHERE ${w.clause} AND ${col} = ? GROUP BY date ORDER BY date ASC`
+	};
+}
+function buildEntityDailySparkline(q) {
+	const table = inferTable([q.dimension]);
+	const w = partitionWhere(q);
+	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}, ${metricExpr(q.metric)} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} AND ${col} IN (${inList}) GROUP BY date, ${col} ORDER BY date ASC`
+	};
+}
+function buildTopNBreakdown(q) {
+	const table = inferTable([q.dimension]);
+	const w = partitionWhere(q);
+	const col = dimColumn(q.dimension);
+	const metrics = q.metrics.map(metricExpr).join(", ");
+	const order = `${orderMetricExpr(q.orderBy.metric)} ${q.orderBy.dir.toUpperCase()}`;
+	let sql = `SELECT ${col}, ${metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY ${col} ORDER BY ${order} LIMIT ${Math.max(0, Math.floor(q.limit))}`;
+	if (q.offset && q.offset > 0) sql += ` OFFSET ${Math.floor(q.offset)}`;
+	return {
+		table,
+		params: w.params,
+		sql
+	};
+}
+function buildSingleRowLookup(q) {
+	const dims = Object.keys(q.match);
+	const table = inferTable(dims);
+	const w = partitionWhere(q);
+	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(dimColumn).join(", ")}, ${metrics}` : metrics} FROM ${TABLE_PLACEHOLDER} WHERE ${clause}${groupBy}`
+	};
+}
+function buildMultiSeriesStackedDaily(q) {
+	const table = inferTable([q.seriesDimension]);
+	const w = partitionWhere(q);
+	const col = dimColumn(q.seriesDimension);
+	return {
+		table,
+		params: w.params,
+		sql: `SELECT date, ${col}, ${metricExpr(q.metric)} FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY date, ${col} ORDER BY date ASC`
+	};
+}
+function buildPresetAnalyzer(q) {
+	const params = q.params ?? {};
+	const minImpressions = Number(params.minImpressions ?? 100);
+	const limit = Math.max(1, Math.floor(Number(params.limit ?? 1e3)));
+	const w = partitionWhere(q);
+	const wp = [...w.params];
+	let having;
+	switch (q.presetId) {
+		case "striking-distance":
+			having = `HAVING SUM(impressions) >= ? AND (SUM(sum_position) / NULLIF(SUM(impressions), 0)) BETWEEN ? AND ?`;
+			wp.push(minImpressions, Number(params.minPosition ?? 11), Number(params.maxPosition ?? 20));
+			break;
+		case "opportunity":
+			having = `HAVING SUM(impressions) >= ? AND SUM(clicks) = 0`;
+			wp.push(minImpressions);
+			break;
+		case "zero-click":
+			having = `HAVING SUM(impressions) >= ? AND SUM(clicks) = 0`;
+			wp.push(minImpressions);
+			break;
+		default: throw new Error(`preset-analyzer: preset '${q.presetId}' is not R2-SQL-safe — window-function presets must be sent as archetype 'arbitrary-sql'`);
+	}
+	return {
+		table: "page_queries",
+		params: wp,
+		sql: `SELECT url, query, SUM(clicks) AS clicks, SUM(impressions) AS impressions, SUM(clicks) / NULLIF(SUM(impressions), 0) AS ctr, SUM(sum_position) / NULLIF(SUM(impressions), 0) AS position FROM ${TABLE_PLACEHOLDER} WHERE ${w.clause} GROUP BY url, query ${having} ORDER BY SUM(impressions) DESC LIMIT ${limit}`
+	};
+}
+function buildTwoDimensionDetail(q) {
+	const w = partitionWhere(q);
+	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);
+	}
+	let sql = `SELECT url, query, ${q.metrics.map(metricExpr).join(", ")} FROM ${TABLE_PLACEHOLDER} WHERE ${clause} GROUP BY url, query`;
+	if (q.orderBy) sql += ` ORDER BY ${orderMetricExpr(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) {
+	switch (query.archetype) {
+		case "site-daily-timeseries": return buildSiteDailyTimeseries(query);
+		case "entity-daily-timeseries": return buildEntityDailyTimeseries(query);
+		case "entity-daily-sparkline": return buildEntityDailySparkline(query);
+		case "top-n-breakdown": return buildTopNBreakdown(query);
+		case "single-row-lookup": return buildSingleRowLookup(query);
+		case "multi-series-stacked-daily": return buildMultiSeriesStackedDaily(query);
+		case "preset-analyzer": return buildPresetAnalyzer(query);
+		case "two-dimension-detail": return buildTwoDimensionDetail(query);
+		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");
+	}
+}
+var ServerTailRoutingError = class extends Error {
+	name = "ServerTailRoutingError";
+};
+function resolveServerTailEngine(query) {
+	const cls = ARCHETYPE_EXECUTION_CLASS[query.archetype];
+	if (cls === "cloud-only") throw new ServerTailRoutingError(`archetype '${query.archetype}' is cloud-only — not a server-tail query`);
+	if (cls === "duckdb") return "duckdb";
+	if (query.archetype === "top-n-breakdown" && query.offset && query.offset > 0) return "duckdb";
+	return "r2-sql";
+}
+function sourceFor(engine) {
+	return engine === "r2-sql" ? "server-r2-sql" : "server-duckdb";
+}
+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);
+			return {
+				archetype: query.archetype,
+				rows: res.rows,
+				source: sourceFor("r2-sql"),
+				meta: {
+					rowCount: res.rows.length,
+					queryMs: res.queryMs
+				}
+			};
+		}
+		const res = await config.duckdb.runArchetype(query);
+		return {
+			archetype: query.archetype,
+			rows: res.rows,
+			source: sourceFor("duckdb"),
+			meta: {
+				rowCount: res.rows.length,
+				queryMs: res.queryMs
+			}
+		};
+	}
+	return {
+		route,
+		execute
+	};
+}
+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`);
+	}
+};
+const DEFAULT_TIMEOUT_MS$1 = 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$1;
+	async function send(sql) {
+		const started = Date.now();
+		const result = await withDeadline(config.svc.runSQL({ sql }), timeoutMs).catch((err) => {
+			if (err instanceof DuckDbIcebergTimeoutError) throw err;
+			throw new DuckDbIcebergError(`DUCKDB_SVC.runSQL failed: ${err.message}`);
+		});
+		return {
+			rows: result.rows ?? [],
+			sql: result.sql ?? sql,
+			queryMs: Date.now() - started
+		};
+	}
+	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));
+	}
+	async function runArchetype(query) {
+		if (query.archetype === "arbitrary-sql") return runSql(query.sql, query.params ?? []);
+		if (query.archetype === "aux-cloud-only") throw new DuckDbIcebergError("aux-cloud-only is not an Iceberg query");
+		return runPlan(buildArchetypeSql(query));
+	}
+	return {
+		runSql,
+		runPlan,
+		runArchetype
+	};
+}
+function r2TableRef(namespace, table) {
+	return `${namespace}.${table}`;
+}
+var R2SqlError = class extends Error {
+	status;
+	name = "R2SqlError";
+	constructor(message, status) {
+		super(message);
+		this.status = status;
+	}
+};
+var R2SqlTimeoutError = class extends Error {
+	name = "R2SqlTimeoutError";
+	constructor(timeoutMs) {
+		super(`R2 SQL query exceeded ${timeoutMs}ms deadline`);
+	}
+};
+const DEFAULT_API_BASE = "https://api.cloudflare.com/client/v4";
+const DEFAULT_TIMEOUT_MS = 25e3;
+function escapeSqlValue(value) {
+	if (value === null || value === void 0) return "NULL";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new R2SqlError(`cannot embed non-finite number in SQL: ${value}`);
+		return String(value);
+	}
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+	return `'${String(value).replace(/'/g, "''")}'`;
+}
+function inlineParams(sql, params) {
+	let out = "";
+	let paramIndex = 0;
+	let inString = false;
+	for (let i = 0; i < sql.length; i++) {
+		const ch = sql[i];
+		if (ch === "'") {
+			if (inString && sql[i + 1] === "'") {
+				out += "''";
+				i++;
+				continue;
+			}
+			inString = !inString;
+			out += ch;
+			continue;
+		}
+		if (ch === "?" && !inString) {
+			if (paramIndex >= params.length) throw new R2SqlError(`SQL has more ? placeholders than params (${params.length})`);
+			out += escapeSqlValue(params[paramIndex++]);
+			continue;
+		}
+		out += ch;
+	}
+	if (paramIndex !== params.length) throw new R2SqlError(`SQL has ${paramIndex} ? placeholders but ${params.length} params supplied`);
+	return out;
+}
+function normalizeRows(result) {
+	if (!result) return [];
+	if (Array.isArray(result.rows)) return result.rows;
+	if (Array.isArray(result.columns) && Array.isArray(result.data)) {
+		const cols = result.columns;
+		return result.data.map((tuple) => {
+			const row = {};
+			cols.forEach((col, idx) => {
+				row[col] = tuple[idx] ?? null;
+			});
+			return row;
+		});
+	}
+	return [];
+}
+function createR2SqlClient(config) {
+	const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+	const apiBase = config.apiBase ?? DEFAULT_API_BASE;
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const endpoint = `${apiBase}/accounts/${config.accountId}/r2-catalog/${config.warehouse}/sql`;
+	async function query(sql) {
+		const started = Date.now();
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new R2SqlTimeoutError(timeoutMs)), timeoutMs);
+		let response;
+		try {
+			response = await fetchImpl(endpoint, {
+				method: "POST",
+				headers: {
+					"authorization": `Bearer ${config.token}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({ query: sql }),
+				signal: controller.signal
+			});
+		} catch (err) {
+			if (err instanceof R2SqlTimeoutError || err?.name === "AbortError") throw new R2SqlTimeoutError(timeoutMs);
+			throw new R2SqlError(`R2 SQL request failed: ${err.message}`);
+		} finally {
+			clearTimeout(timer);
+		}
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			throw new R2SqlError(`R2 SQL HTTP ${response.status}: ${text}`, response.status);
+		}
+		const envelope = await response.json();
+		if (!envelope.success) throw new R2SqlError(`R2 SQL query rejected: ${envelope.errors?.map((e) => e.message).join("; ") ?? "unknown R2 SQL error"}`);
+		return {
+			rows: normalizeRows(envelope.result),
+			sql,
+			queryMs: Date.now() - started
+		};
+	}
+	function runPlan(plan) {
+		const tableRef = r2TableRef(config.namespace, plan.table);
+		return query(inlineParams(plan.sql.split(TABLE_PLACEHOLDER).join(tableRef), plan.params));
+	}
+	function runArchetype(archetypeQuery) {
+		return runPlan(buildArchetypeSql(archetypeQuery));
+	}
+	return {
+		query,
+		runPlan,
+		runArchetype
+	};
+}
 const SIG_HEX_LEN = 16;
 const keyCache = /* @__PURE__ */ new WeakMap();
 const stringKeyCache = /* @__PURE__ */ new Map();
@@ -483,4 +883,4 @@ async function verifySizeHint(env, key, bytes, providedHex) {
 	for (let i = 0; i < SIG_HEX_LEN; i++) diff |= expected.charCodeAt(i) ^ providedHex.charCodeAt(i);
 	return diff === 0;
 }
-export { createDucklingsCodec, createDucklingsExecutor, createInflightDedupe, createR2Presigner, getAnalyticsEngine, getHostedR2QueryKey, getWasmDuckDBFactory, resetWasmDuckDB, signSizeHint, useAnalyticsEnv, verifySizeHint };
+export { DuckDbIcebergError, DuckDbIcebergTimeoutError, R2SqlError, R2SqlTimeoutError, ServerTailRoutingError, TABLE_PLACEHOLDER, buildArchetypeSql, createDuckDbIcebergExecutor, createDucklingsCodec, createDucklingsExecutor, createInflightDedupe, createR2Presigner, createR2SqlClient, createServerTailDispatcher, escapeSqlValue, getAnalyticsEngine, getHostedR2QueryKey, getWasmDuckDBFactory, inlineParams, resetWasmDuckDB, resolveServerTailEngine, signSizeHint, useAnalyticsEnv, verifySizeHint };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cloudflare",
   "type": "module",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Cloudflare-Workers-flavored helpers for the gscdump analytics stack: AnalyticsEnv binding contract, R2 SigV4 presigner, size-hint HMAC, DuckDB Workers shims, engine factory.",
   "author": {
     "name": "Harlan Wilton",
@@ -41,8 +41,11 @@
   "dependencies": {
     "@uwdata/flechette": "^2.5.0",
     "aws4fetch": "^1.0.20",
-    "@gscdump/engine-sqlite": "0.20.3",
-    "@gscdump/engine": "0.20.3"
+    "@gscdump/contracts": "0.21.0",
+    "@gscdump/engine-sqlite": "0.21.0",
+    "gscdump": "0.21.0",
+    "@gscdump/sdk": "0.21.0",
+    "@gscdump/engine": "0.21.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260520.1",