@gscdump/cloudflare 1.3.2 → 1.4.1

package/dist/server-tail/r2-sql-client.d.mts

@@ -0,0 +1,89 @@
+import { ArchetypeSqlPlan, PartitionKeyEncoding } from "./archetype-sql.mjs";
+import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
+import { Result } from "gscdump/result";
+/** Configuration for an R2 SQL client. */
+interface R2SqlClientConfig {
+  /** Cloudflare account id. */
+  accountId: string;
+  /** R2 bucket backing the Iceberg catalog — R2 SQL addresses the catalog by bucket. */
+  bucket: 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;
+  /** Partition-key encoding of the target catalog. Defaults to `'int'`. */
+  partitionKeyEncoding?: PartitionKeyEncoding;
+  /**
+   * Host-owned mapping from public site id to the INT `site_id` partition
+   * value. Required for non-numeric public ids when `partitionKeyEncoding` is
+   * `'int'`.
+   */
+  partitionSiteId?: (siteId: string) => string | 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);
+}
+/**
+ * The modelled, caller-actionable failure channel for an R2 SQL query. Callers
+ * branch on which class came back — a `R2SqlTimeoutError` is a transient retry
+ * candidate (the query outran the per-query deadline), while a `R2SqlError`
+ * (HTTP 4xx/5xx, a rejected envelope, a transport blow-up) is a hard failure.
+ * The error variant IS the existing throwable class, so the throwing wrapper
+ * preserves the exact identity/message tests assert (`rejects.toThrow(/HTTP 403/)`,
+ * `rejects.toBeInstanceOf(R2SqlTimeoutError)`). Defects — a programmer handing
+ * the client malformed params (`escapeSqlValue` / `inlineParams`) — are NOT
+ * modelled here; they keep throwing `R2SqlError` synchronously.
+ */
+type R2SqlQueryError = R2SqlError | R2SqlTimeoutError;
+/** A configured R2 SQL client. */
+interface R2SqlClient {
+  /** Run a raw SQL string (table reference already resolved). */
+  query: (sql: string) => Promise<R2SqlResult>;
+  /**
+   * Errors-as-values core for {@link R2SqlClient.query}: returns the modelled
+   * timeout-vs-hard-fail `R2SqlQueryError` instead of throwing, so callers can
+   * branch on retry-ability without `instanceof` over a `catch`. Optional so a
+   * hand-rolled `R2SqlClient` (e.g. a host app's own endpoint-backed client) can
+   * implement only the throwing surface; {@link createR2SqlClient} always
+   * provides it.
+   */
+  queryResult?: (sql: string) => Promise<Result<R2SqlResult, R2SqlQueryError>>;
+  /** 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;
+export { R2SqlClient, R2SqlClientConfig, R2SqlError, R2SqlQueryError, R2SqlResult, R2SqlRow, R2SqlTimeoutError, createR2SqlClient };

package/dist/server-tail/r2-sql-client.mjs

@@ -0,0 +1,159 @@
+import { TABLE_PLACEHOLDER, buildArchetypeSql } from "./archetype-sql.mjs";
+import { err, ok, unwrapResult } from "gscdump/result";
+import { SEARCH_TYPE_INT } from "@gscdump/engine/iceberg";
+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`);
+	}
+};
+function r2SqlErrorToException(error) {
+	return error;
+}
+const DEFAULT_API_BASE = "https://api.sql.cloudflarestorage.com/api/v1";
+const DEFAULT_TIMEOUT_MS = 25e3;
+const PARTITION_PREDICATE_RE = /\b(site_id|search_type)(\s*=)/g;
+function workaroundPartitionEquality(sql) {
+	return sql.replace(PARTITION_PREDICATE_RE, (_m, col, eq) => `CONCAT(${col}, '')${eq}`);
+}
+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 coerceIntSiteId(siteId, mapper) {
+	const mapped = mapper ? mapper(siteId) : siteId;
+	const n = Number(mapped);
+	if (!Number.isSafeInteger(n)) throw new R2SqlError("int R2 SQL catalog requires a numeric site_id partition value; pass partitionSiteId for public ids");
+	return n;
+}
+function withEncodedPartitions(query, encoding, siteIdMapper) {
+	if (encoding === "string") return query;
+	const scoped = query;
+	const searchType = SEARCH_TYPE_INT[scoped.searchType];
+	if (searchType === void 0) throw new R2SqlError(`unknown search_type for int R2 SQL catalog: ${String(scoped.searchType)}`);
+	return {
+		...query,
+		siteId: coerceIntSiteId(scoped.siteId, siteIdMapper),
+		searchType
+	};
+}
+function createR2SqlClient(config) {
+	const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+	const apiBase = config.apiBase ?? DEFAULT_API_BASE;
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const partitionKeyEncoding = config.partitionKeyEncoding ?? "int";
+	const endpoint = `${apiBase}/accounts/${config.accountId}/r2-sql/query/${config.bucket}`;
+	async function queryResult(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",
+					"user-agent": "gscdump-cloudflare-r2sql/1.0"
+				},
+				body: JSON.stringify({ query: sql }),
+				signal: controller.signal
+			});
+		} catch (error) {
+			if (error instanceof R2SqlTimeoutError || error?.name === "AbortError") return err(new R2SqlTimeoutError(timeoutMs));
+			return err(new R2SqlError(`R2 SQL request failed: ${error.message}`));
+		} finally {
+			clearTimeout(timer);
+		}
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			return err(new R2SqlError(`R2 SQL HTTP ${response.status}: ${text}`, response.status));
+		}
+		const envelope = await response.json();
+		if (!envelope.success) return err(new R2SqlError(`R2 SQL query rejected: ${envelope.errors?.map((e) => e.message).join("; ") ?? "unknown R2 SQL error"}`));
+		return ok({
+			rows: normalizeRows(envelope.result),
+			sql,
+			queryMs: Date.now() - started
+		});
+	}
+	async function query(sql) {
+		return unwrapResult(await queryResult(sql), r2SqlErrorToException);
+	}
+	function materializePlan(plan) {
+		const tableRef = r2TableRef(config.namespace, plan.table);
+		return inlineParams(plan.sql.split(TABLE_PLACEHOLDER).join(tableRef), plan.params);
+	}
+	function runPlan(plan) {
+		const sql = materializePlan(plan);
+		return query(partitionKeyEncoding === "string" ? workaroundPartitionEquality(sql) : sql);
+	}
+	function runArchetype(archetypeQuery) {
+		return query(materializePlan(buildArchetypeSql(withEncodedPartitions(archetypeQuery, partitionKeyEncoding, config.partitionSiteId), { partitionKeyEncoding })));
+	}
+	return {
+		query,
+		queryResult,
+		runPlan,
+		runArchetype
+	};
+}
+export { R2SqlError, R2SqlTimeoutError, createR2SqlClient, escapeSqlValue, inlineParams };

package/dist/workers-duckdb.d.mts

@@ -0,0 +1,19 @@
+import { AnalyticsEnv } from "./env.mjs";
+import { ParquetCodec, QueryExecutor, Row } from "@gscdump/engine";
+declare function createDucklingsCodec(_env: AnalyticsEnv): ParquetCodec;
+interface DucklingsRowCache {
+  clear: () => void;
+  get: (key: string) => Row[] | undefined;
+  put: (key: string, rows: Row[]) => void;
+}
+declare function createDucklingsRowCache(maxBytes?: number): DucklingsRowCache;
+interface DucklingsExecutorOptions {
+  ipcChunkBytes?: number;
+  ipcDirectCallBytes?: number;
+  ipcTotalBytes?: number;
+  /** Per-RPC wall/queue budget. Interactive default is 22 seconds. */
+  rpcTimeoutMs?: number;
+  rowCache?: DucklingsRowCache;
+}
+declare function createDucklingsExecutor(env: AnalyticsEnv, opts?: DucklingsExecutorOptions): QueryExecutor;
+export { DucklingsExecutorOptions, DucklingsRowCache, createDucklingsCodec, createDucklingsExecutor, createDucklingsRowCache };

package/dist/workers-duckdb.mjs

@@ -0,0 +1,360 @@
+import { rowsToArrowIPC } from "./arrow.mjs";
+import { coerceRow } from "@gscdump/engine";
+import { createHyparquetCodec, decodeParquetToRows } from "@gscdump/engine/hyparquet";
+import { SCHEMAS } from "@gscdump/engine/schema";
+import { bindLiterals } from "@gscdump/engine/sql";
+function resolveSvc(env) {
+	const svc = env.DUCKDB_SVC;
+	if (!svc) throw new Error("DUCKDB_SVC service binding is not configured");
+	return svc;
+}
+const DUCKDB_RPC_TIMEOUT_MS = 22e3;
+const WORKER_R2_MAX_FILES = 96;
+const WORKER_R2_MAX_BYTES = 64 * 1024 * 1024;
+const WORKER_R2_DECODE_CONCURRENCY = 2;
+const WORKER_R2_HEAD_CONCURRENCY = 4;
+const IPC_CHUNK_BUDGET = 8 * 1024 * 1024;
+const IPC_DIRECT_CALL_BUDGET = 30 * 1024 * 1024;
+const IPC_STAGED_TOTAL_BUDGET = 64 * 1024 * 1024;
+var DuckDBServiceTimeoutError = class extends Error {
+	name = "DuckDBServiceTimeoutError";
+	constructor(timeoutMs) {
+		super(`DUCKDB_SVC.runSQL exceeded ${timeoutMs}ms deadline`);
+	}
+};
+function withDuckDBDeadline(op, timeoutMs, signal) {
+	if (signal?.aborted) return Promise.reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		let timer;
+		let onAbort;
+		const cleanup = () => {
+			if (timer !== void 0) clearTimeout(timer);
+			if (onAbort) signal?.removeEventListener("abort", onAbort);
+		};
+		const settle = (complete, value) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			complete(value);
+		};
+		onAbort = () => settle(reject, signal.reason ?? new DOMException("Aborted", "AbortError"));
+		timer = setTimeout(() => settle(reject, new DuckDBServiceTimeoutError(timeoutMs)), timeoutMs);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		op.then((value) => settle(resolve, value), (error) => settle(reject, error));
+	});
+}
+function runSQLWithDeadline(svc, args, timeoutMs, signal) {
+	const deadlineAt = Date.now() + timeoutMs;
+	return withDuckDBDeadline(svc.runSQL({
+		...args,
+		deadlineAt
+	}), timeoutMs, signal);
+}
+function createDucklingsCodec(_env) {
+	return createHyparquetCodec();
+}
+const READ_PARQUET_PLACEHOLDER = /read_parquet\(\{\{(\w+)\}\}(?:\s*,[^)]*)?\)/g;
+function tmpTableName(placeholder) {
+	const uuid = crypto.randomUUID().replace(/-/g, "_");
+	return `tmp_${placeholder.toLowerCase()}_${uuid}`;
+}
+async function mapLimit(items, concurrency, fn) {
+	const limit = Math.max(1, Math.floor(concurrency));
+	const out = Array.from({ length: items.length });
+	let next = 0;
+	let failed = false;
+	let failure;
+	async function worker() {
+		while (!failed && next < items.length) {
+			const index = next++;
+			try {
+				out[index] = await fn(items[index], index);
+			} catch (error) {
+				failed = true;
+				failure = error;
+			}
+		}
+	}
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	if (failed) throw failure;
+	return out;
+}
+function assertWorkerReadBudget(opts) {
+	const maxFiles = opts.maxFiles ?? WORKER_R2_MAX_FILES;
+	const maxBytes = opts.maxBytes ?? WORKER_R2_MAX_BYTES;
+	const entries = Object.entries(opts.fileKeys);
+	const totalFiles = entries.reduce((acc, [, keys]) => acc + keys.length, 0);
+	if (totalFiles > maxFiles) throw new Error(`createDucklingsExecutor: planned read spans ${totalFiles} files, exceeding the ${maxFiles} file Worker budget. Narrow the date range or route through a background/windowed query.`);
+	if (!opts.sizes) return;
+	let totalBytes = 0;
+	for (const [, keys] of entries) for (const key of keys) {
+		const bytes = opts.sizes[key];
+		if (bytes !== void 0) totalBytes += Math.max(0, bytes);
+	}
+	if (totalBytes > maxBytes) throw new Error(`createDucklingsExecutor: planned read spans ${totalBytes} bytes, exceeding the ${maxBytes} byte Worker budget. Narrow the date range or route through a background/windowed query.`);
+}
+const ROW_CACHE_MAX_BYTES = 16 * 1024 * 1024;
+function estimateRowsBytes(rows) {
+	if (rows.length === 0) return 0;
+	const cols = Object.keys(rows[0]).length;
+	return rows.length * cols * 64;
+}
+function addInferredValue(inference, value) {
+	if (value === null || value === void 0) return;
+	inference.hasValue = true;
+	if (typeof value === "string") {
+		inference.hasString = true;
+		return;
+	}
+	if (typeof value === "bigint") {
+		inference.hasBigInt = true;
+		return;
+	}
+	if (typeof value === "number") {
+		if (!Number.isInteger(value)) inference.hasFloat = true;
+		if (value > 2147483647 || value < -2147483648) inference.hasBigInt = true;
+	}
+}
+function inferredColumnType(inference) {
+	if (!inference.hasValue || inference.hasString) return "VARCHAR";
+	if (inference.hasFloat) return "DOUBLE";
+	return inference.hasBigInt ? "BIGINT" : "INTEGER";
+}
+function chunkSchemaColumns(rows, schemaColumns) {
+	const columns = schemaColumns ? [...schemaColumns] : [];
+	const seen = new Set(columns.map((c) => c.name));
+	const extraColumns = /* @__PURE__ */ new Map();
+	for (const row of rows) for (const key in row) {
+		if (seen.has(key)) continue;
+		let inference = extraColumns.get(key);
+		if (!inference) {
+			inference = {
+				hasValue: false,
+				hasString: false,
+				hasFloat: false,
+				hasBigInt: false
+			};
+			extraColumns.set(key, inference);
+		}
+		addInferredValue(inference, row[key]);
+	}
+	if (extraColumns.size === 0) return schemaColumns ? columns : void 0;
+	for (const [name, inference] of extraColumns) columns.push({
+		name,
+		type: inferredColumnType(inference),
+		nullable: true
+	});
+	return columns;
+}
+function rowsToArrowIPCChunks(rows, schemaColumns, opts = {}) {
+	const maxChunkBytes = Math.max(1, Math.floor(opts.maxChunkBytes ?? IPC_CHUNK_BUDGET));
+	const placeholder = opts.placeholder ? `{{${opts.placeholder}}}` : "placeholder";
+	const chunkColumns = chunkSchemaColumns(rows, schemaColumns);
+	if (rows.length === 0) {
+		const ipc = rowsToArrowIPC([], chunkColumns);
+		if (ipc.byteLength > maxChunkBytes) throw new Error(`createDucklingsExecutor: empty ${placeholder} Arrow IPC schema encoded to ${ipc.byteLength} bytes, exceeding the ${maxChunkBytes}-byte service-binding chunk budget.`);
+		return [{
+			ipc,
+			rows: 0
+		}];
+	}
+	const estimatedPerRow = Math.max(1, Math.ceil(estimateRowsBytes(rows) / rows.length));
+	let targetRows = Math.max(1, Math.min(rows.length, Math.floor(maxChunkBytes * .75 / estimatedPerRow)));
+	const chunks = [];
+	let index = 0;
+	while (index < rows.length) {
+		let take = Math.min(targetRows, rows.length - index);
+		while (true) {
+			const slice = rows.slice(index, index + take);
+			const ipc = rowsToArrowIPC(slice, chunkColumns);
+			if (ipc.byteLength <= maxChunkBytes) {
+				chunks.push({
+					ipc,
+					rows: slice.length
+				});
+				index += take;
+				if (ipc.byteLength < maxChunkBytes * .4 && take === targetRows) targetRows = Math.min(rows.length - index || targetRows, targetRows * 2);
+				break;
+			}
+			if (take === 1) throw new Error(`createDucklingsExecutor: one ${placeholder} row encoded to ${ipc.byteLength} bytes of Arrow IPC, exceeding the ${maxChunkBytes}-byte service-binding chunk budget. Narrow the query or route through a background/windowed query.`);
+			take = Math.max(1, Math.floor(take / 2));
+		}
+	}
+	return chunks;
+}
+function createDucklingsRowCache(maxBytes = ROW_CACHE_MAX_BYTES) {
+	let totalBytes = 0;
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		clear() {
+			entries.clear();
+			totalBytes = 0;
+		},
+		get(key) {
+			const hit = entries.get(key);
+			if (!hit) return void 0;
+			entries.delete(key);
+			entries.set(key, hit);
+			return hit.rows;
+		},
+		put(key, rows) {
+			const bytes = estimateRowsBytes(rows);
+			if (bytes > maxBytes) return;
+			const existing = entries.get(key);
+			if (existing) {
+				entries.delete(key);
+				totalBytes -= existing.bytes;
+			}
+			while (totalBytes + bytes > maxBytes) {
+				const oldest = entries.keys().next().value;
+				if (oldest === void 0) break;
+				const evicted = entries.get(oldest);
+				entries.delete(oldest);
+				totalBytes -= evicted.bytes;
+			}
+			entries.set(key, {
+				rows,
+				bytes
+			});
+			totalBytes += bytes;
+		}
+	};
+}
+function createDucklingsExecutor(env, opts = {}) {
+	const rowCache = opts.rowCache ?? createDucklingsRowCache();
+	const rpcTimeoutMs = opts.rpcTimeoutMs ?? DUCKDB_RPC_TIMEOUT_MS;
+	if (!Number.isFinite(rpcTimeoutMs) || rpcTimeoutMs <= 0) throw new TypeError("createDucklingsExecutor: rpcTimeoutMs must be a positive finite number");
+	return { async execute({ sql, params, fileKeys, placeholderTables, pushdownFilters, dataSource, signal, table }) {
+		signal?.throwIfAborted();
+		const svc = resolveSvc(env);
+		assertWorkerReadBudget({ fileKeys });
+		const cachedUnfiltered = /* @__PURE__ */ new Map();
+		const scheduledUnfiltered = /* @__PURE__ */ new Set();
+		const plannedReadKeys = [];
+		for (const [placeholder, keys] of Object.entries(fileKeys)) {
+			const filter = pushdownFilters?.[placeholder];
+			for (const key of keys) {
+				if (filter) {
+					plannedReadKeys.push(key);
+					continue;
+				}
+				const cached = cachedUnfiltered.get(key) ?? rowCache.get(key);
+				if (cached !== void 0) {
+					cachedUnfiltered.set(key, cached);
+					continue;
+				}
+				if (!scheduledUnfiltered.has(key)) {
+					scheduledUnfiltered.add(key);
+					plannedReadKeys.push(key);
+				}
+			}
+		}
+		if (dataSource.head && plannedReadKeys.length > 0) {
+			const uniqueKeys = [...new Set(plannedReadKeys)];
+			const sizes = {};
+			await mapLimit(uniqueKeys, WORKER_R2_HEAD_CONCURRENCY, async (key) => {
+				signal?.throwIfAborted();
+				sizes[key] = (await dataSource.head(key))?.bytes;
+			});
+			assertWorkerReadBudget({
+				fileKeys: { READS: plannedReadKeys },
+				sizes
+			});
+		}
+		const tempNames = {};
+		const tableChunks = {};
+		let totalIpcBytes = 0;
+		const maxChunkBytes = opts.ipcChunkBytes ?? IPC_CHUNK_BUDGET;
+		const maxDirectCallBytes = opts.ipcDirectCallBytes ?? IPC_DIRECT_CALL_BUDGET;
+		const maxTotalBytes = opts.ipcTotalBytes ?? IPC_STAGED_TOTAL_BUDGET;
+		const unfilteredLoads = /* @__PURE__ */ new Map();
+		for (const [key, rows] of cachedUnfiltered) unfilteredLoads.set(key, Promise.resolve(rows));
+		const loadUnfiltered = (key) => {
+			let loading = unfilteredLoads.get(key);
+			if (!loading) {
+				loading = (async () => {
+					signal?.throwIfAborted();
+					const bytes = await dataSource.read(key, void 0, signal);
+					signal?.throwIfAborted();
+					const rows = await decodeParquetToRows(bytes);
+					rowCache.put(key, rows);
+					return rows;
+				})();
+				unfilteredLoads.set(key, loading);
+			}
+			return loading;
+		};
+		for (const [placeholder, keys] of Object.entries(fileKeys)) {
+			signal?.throwIfAborted();
+			const filter = pushdownFilters?.[placeholder];
+			const perFile = await mapLimit(keys, WORKER_R2_DECODE_CONCURRENCY, async (key) => {
+				if (!filter) return loadUnfiltered(key);
+				signal?.throwIfAborted();
+				const bytes = await dataSource.read(key, void 0, signal);
+				signal?.throwIfAborted();
+				return await decodeParquetToRows(bytes, filter ? { filter } : {});
+			});
+			const merged = [];
+			for (const rows of perFile) merged.push(...rows);
+			const chunks = rowsToArrowIPCChunks(merged, SCHEMAS[placeholderTables?.[placeholder] ?? table]?.columns, {
+				maxChunkBytes,
+				placeholder
+			});
+			signal?.throwIfAborted();
+			totalIpcBytes += chunks.reduce((acc, chunk) => acc + chunk.ipc.byteLength, 0);
+			if (totalIpcBytes > maxTotalBytes) throw new Error(`createDucklingsExecutor: query encoded to ${totalIpcBytes} bytes of Arrow IPC across ${Object.keys(tableChunks).length + 1} placeholders, exceeding the ${maxTotalBytes}-byte service-binding transport budget. Window the query (chunk partitions / narrow the range).`);
+			const tmp = tmpTableName(placeholder);
+			tempNames[placeholder] = tmp;
+			tableChunks[tmp] = chunks;
+		}
+		signal?.throwIfAborted();
+		const finalSql = bindLiterals(sql.replace(READ_PARQUET_PLACEHOLDER, (_, placeholder) => {
+			const tmp = tempNames[placeholder];
+			if (!tmp) throw new Error(`createDucklingsExecutor: SQL references {{${placeholder}}} but no fileKeys entry provided`);
+			return tmp;
+		}), params);
+		const canInlineTables = totalIpcBytes <= maxDirectCallBytes && Object.values(tableChunks).every((chunks) => chunks.length === 1);
+		let result;
+		if (canInlineTables) {
+			const tables = {};
+			for (const [name, chunks] of Object.entries(tableChunks)) tables[name] = { ipc: chunks[0].ipc };
+			result = await runSQLWithDeadline(svc, {
+				sql: finalSql,
+				tables
+			}, rpcTimeoutMs, signal);
+		} else {
+			if (!svc.stageArrowTable || !svc.dropTables) throw new Error("createDucklingsExecutor: DUCKDB_SVC does not support chunked Arrow IPC staging. Deploy the gscdump-duckdb worker with stageArrowTable/dropTables support.");
+			const staged = /* @__PURE__ */ new Set();
+			let primaryError;
+			let cleanupError;
+			try {
+				for (const [name, chunks] of Object.entries(tableChunks)) for (const chunk of chunks) {
+					signal?.throwIfAborted();
+					staged.add(name);
+					await withDuckDBDeadline(svc.stageArrowTable({
+						table: name,
+						ipc: chunk.ipc
+					}), rpcTimeoutMs, signal);
+				}
+				result = await runSQLWithDeadline(svc, { sql: finalSql }, rpcTimeoutMs, signal);
+			} catch (error) {
+				primaryError = error;
+			} finally {
+				if (staged.size > 0) try {
+					await withDuckDBDeadline(svc.dropTables({ tables: [...staged] }), rpcTimeoutMs);
+				} catch (error) {
+					cleanupError = error;
+				}
+			}
+			if (primaryError) throw primaryError;
+			if (cleanupError) throw cleanupError;
+			result = result;
+		}
+		return {
+			rows: result.rows.map(coerceRow),
+			sql: result.sql
+		};
+	} };
+}
+export { DuckDBServiceTimeoutError, assertWorkerReadBudget, createDucklingsCodec, createDucklingsExecutor, createDucklingsRowCache, mapLimit, rowsToArrowIPCChunks, withDuckDBDeadline };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cloudflare",
   "type": "module",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "description": "Cloudflare-Workers-flavored helpers for the gscdump analytics stack: AnalyticsEnv binding contract, R2 SigV4 presigner, DuckDB Workers shims, engine factory.",
   "author": {
     "name": "Harlan Wilton",
@@ -42,16 +42,16 @@
   },
   "dependencies": {
     "@uwdata/flechette": "^2.5.0",
-    "@gscdump/engine": "^1.3.2",
-    "@gscdump/contracts": "^1.3.2",
-    "@gscdump/engine-sqlite": "^1.3.2",
-    "gscdump": "^1.3.2"
+    "@gscdump/contracts": "^1.4.1",
+    "@gscdump/engine": "^1.4.1",
+    "@gscdump/engine-sqlite": "^1.4.1",
+    "gscdump": "^1.4.1"
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.18.6",
-    "@cloudflare/workers-types": "^5.20260718.1",
-    "typescript": "^6.0.3",
-    "wrangler": "^4.112.0"
+    "@cloudflare/vitest-pool-workers": "^0.18.7",
+    "@cloudflare/workers-types": "^5.20260722.1",
+    "typescript": "^7.0.2",
+    "wrangler": "^4.113.0"
   },
   "scripts": {
     "build": "obuild",