@gscdump/engine-duckdb-wasm 0.20.3 → 0.21.0

package/dist/index.d.mts

@@ -1,11 +1,25 @@
 import { Assume, DrizzleConfig, entityKind } from "drizzle-orm";
 import { PgDatabase, PgDialect, PgPreparedQuery, PgQueryResultHKT, PgSession } from "drizzle-orm/pg-core";
-import { DrizzleSchema as Schema, countries, devices, drizzleSchema as schema, hourly_pages, keywords, page_keywords, pages } from "@gscdump/engine/schema";
+import { DrizzleSchema as Schema, countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
 import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
 import { ComparisonMode, ResolveWindowOptions, ResolvedWindow, WindowPreset, resolveWindow } from "@gscdump/engine/period";
+import { ArchetypeQuery } from "@gscdump/sdk";
 import { AsyncDuckDB, AsyncDuckDBConnection, DuckDBBundles, DuckDBConfig } from "@duckdb/duckdb-wasm";
 import { AnalysisParams } from "@gscdump/engine/analysis-types";
+/** A compiled, parameterised statement. */
+interface CompiledArchetypeSql {
+  sql: string;
+  params: unknown[];
+  /** The fact-table view the query reads. */
+  table: string;
+}
+/**
+ * Compile one archetype query to DuckDB SQL. Throws for `aux-cloud-only`.
+ */
+declare function compileArchetypeSql(query: ArchetypeQuery): CompiledArchetypeSql;
+/** The fact-table view an archetype reads — drives per-table browser routing. */
+declare function tableForArchetype(query: ArchetypeQuery): string | null;
 interface DuckDBWasmClient {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
@@ -44,7 +58,7 @@ declare function createInsightRunner(opts: InsightRunnerOptions): Promise<Insigh
  * so consumers can add the predicate without an interface change when
  * multi-site snapshots land.
  */
-declare const scopeFor: (table: "pages" | "keywords" | "countries" | "devices" | "page_keywords" | "search_appearance" | "hourly_pages", opts: ScopedRunnerOptions) => TableScope, mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
+declare const scopeFor: (table: "pages" | "queries" | "countries" | "page_queries" | "dates" | "search_appearance" | "hourly_pages", opts: ScopedRunnerOptions) => TableScope, mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
 interface StrikingMomentumOptions {
   /** Anchor date (YYYY-MM-DD). Defaults to today. */
   anchor?: string;
@@ -67,6 +81,113 @@ interface StrikingMomentumRow {
   momentum_score: number;
 }
 declare function strikingMomentum(runner: InsightRunner, opts?: StrikingMomentumOptions): Promise<StrikingMomentumRow[]>;
+/** A parquet data file to materialise into OPFS. */
+interface OpfsParquetFile {
+  /** Same-origin URL carrying a signed size hint + short-lived access token. */
+  url: string;
+  /** Expected byte size — drives progress + a cheap pre-verify shortcut. */
+  bytes: number;
+  /**
+   * Lowercase hex SHA-256 of the file's bytes (the Iceberg data-file digest).
+   * The OPFS-cached copy is verified against this before it is trusted.
+   * When omitted, only the byte size is checked (degraded trust).
+   */
+  contentHash?: string;
+  /** Row count — diagnostics only. */
+  rowCount?: number;
+}
+/** One logical table and the parquet files that compose it. */
+interface OpfsParquetTable {
+  /** Iceberg table name — becomes the DuckDB view name. */
+  table: string;
+  files: OpfsParquetFile[];
+}
+interface AttachOpfsTablesOptions {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  tables: OpfsParquetTable[];
+  /** DuckDB schema the views are created in. Default `main`. */
+  schema?: string;
+  /** `fetch` override (tests). Default `globalThis.fetch`. */
+  fetch?: typeof fetch;
+  /** Request init for the parquet downloads (auth headers, credentials mode). */
+  fetchInit?: RequestInit;
+  /** Caps simultaneous downloads. Default 2. */
+  fetchConcurrency?: number;
+  /** Abort signal threaded through downloads + registration. */
+  signal?: AbortSignal;
+  /** Snapshot version associated with this file set — echoed on the handle. */
+  version?: string;
+  /** Ticks once per file as it lands in OPFS + registers. UI progress. */
+  onFileProgress?: (info: OpfsFileProgress) => void;
+}
+interface OpfsFileProgress {
+  table: string;
+  /** OPFS file name. */
+  file: string;
+  /** Index within the flat file list. */
+  index: number;
+  /** Total files across all tables. */
+  total: number;
+  /** Bytes of this file (cumulative caller-side). */
+  bytes: number;
+  /** `'cache-hit'` — already in OPFS, verified; `'downloaded'` — fetched. */
+  outcome: 'cache-hit' | 'downloaded';
+}
+/** Handle returned from {@link attachOpfsParquetTables}. */
+interface OpfsAttachedHandle {
+  version: string | undefined;
+  /** Tables that successfully attached (a per-table failure drops only that table). */
+  tables: string[];
+  schema: string;
+  /** Total bytes materialised into OPFS for this attach. */
+  bytesAttached: number;
+  /**
+   * Tables that could NOT be attached because OPFS ran out of quota. The
+   * caller routes these to the server tail. Empty on a clean attach.
+   */
+  degradedTables: string[];
+  /** Detach the created views + release the registered OPFS file handles. */
+  detach: () => Promise<void>;
+}
+/**
+ * Raised when OPFS cannot hold the file set. Carries the partial state so the
+ * caller can degrade — attach what fit, route the rest server-side.
+ */
+declare class OpfsQuotaExceededError extends Error {
+  name: string;
+  /** Tables that did not fit. */
+  readonly degradedTables: string[];
+  constructor(message: string, degradedTables: string[]);
+}
+/**
+ * Request persistent storage so the browser is less likely to evict the OPFS
+ * cache under pressure. Returns the granted state — `false` is normal for an
+ * un-engaged origin and is NOT an error; it just means eviction is possible.
+ */
+declare function requestPersistentStorage(): Promise<boolean>;
+/** Best-effort `{ usageBytes, quotaBytes }` from the Storage API. */
+declare function estimateOpfsStorage(): Promise<{
+  usageBytes?: number;
+  quotaBytes?: number;
+}>;
+/**
+ * Download every parquet file in `tables` into OPFS, content-hash verify, and
+ * attach them as DuckDB-WASM views. Attach-once: call this once per
+ * `(site, table)` span; re-query without re-attaching for filter / range
+ * changes inside the span.
+ *
+ * Quota handling: a `QuotaExceededError` while writing a table's files does
+ * NOT throw — that table is recorded in `degradedTables` and skipped; the
+ * caller routes it to the server tail. The remaining tables still attach.
+ */
+declare function attachOpfsParquetTables(options: AttachOpfsTablesOptions): Promise<OpfsAttachedHandle>;
+/**
+ * Delete every OPFS entry this module created. Used to reclaim space after a
+ * quota error, or to force a clean re-download. Best-effort — missing entries
+ * are ignored.
+ */
+declare function clearOpfsSnapshotCache(): Promise<void>;
 interface QueryResult {
   rows: Record<string, unknown>[];
   queryMs: number;
@@ -188,8 +309,8 @@ interface BrowserAnalysisRuntime {
   /**
    * Update the list of attached table names. Lets callers fast-fail in
    * `analyze()` when a SQL plan references a table that wasn't in the manifest
-   * for this site (e.g. site has only `keywords` parquet, analyzer wants
-   * `page_keywords`) — surface a clean `AttachedTableMissingError` so the
+   * for this site (e.g. site has only `queries` parquet, analyzer wants
+   * `page_queries`) — surface a clean `AttachedTableMissingError` so the
    * caller can route to cloud fallback without paying the SQL execution cost.
    */
   setAttachedTables: (tables: readonly string[]) => void;
@@ -206,4 +327,4 @@ declare function createBrowserAnalysisRuntime(boot: DuckDBWasmBootResult, option
   version?: number | string;
   attachedTables?: readonly string[];
 }): BrowserAnalysisRuntime;
-export { type AnalyzeResult, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type StrikingMomentumOptions, type StrikingMomentumRow, type TableScope, type WindowPreset, attachParquetTables, attachParquetUrlTables, bootDuckDBWasm, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, devices, drizzle, hourly_pages, keywords, mergeScope, page_keywords, pages, resolveWindow, schema, scopeFor, strikingMomentum };
+export { type AnalyzeResult, type AttachOpfsTablesOptions, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type CompiledArchetypeSql, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type OpfsAttachedHandle, type OpfsFileProgress, type OpfsParquetFile, type OpfsParquetTable, OpfsQuotaExceededError, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type StrikingMomentumOptions, type StrikingMomentumRow, type TableScope, type WindowPreset, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, bootDuckDBWasm, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, mergeScope, page_queries, pages, queries, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };

package/dist/index.mjs

@@ -2,13 +2,247 @@ import { arrowToRows } from "@gscdump/engine/arrow";
 import { DefaultLogger, NoopLogger, createTableRelationsHelpers, entityKind, extractTablesRelationalConfig, fillPlaceholders, sql } from "drizzle-orm";
 import { PgDatabase, PgDialect, PgPreparedQuery, PgSession } from "drizzle-orm/pg-core";
 import { toIsoDate } from "gscdump";
-import { countries, devices, drizzleSchema as schema, hourly_pages, keywords, page_keywords, pages } from "@gscdump/engine/schema";
+import { countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { createScopedHelpers } from "@gscdump/engine/scope";
 import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 import { pgResolverAdapter } from "@gscdump/engine/resolver";
 import { createAttachedTableSource } from "@gscdump/engine/source";
 import { sqlEscape } from "@gscdump/engine/sql";
 import { resolveWindow } from "@gscdump/engine/period";
+const METRIC_SQL = {
+	clicks: "SUM(clicks)",
+	impressions: "SUM(impressions)",
+	ctr: "CASE WHEN SUM(impressions) = 0 THEN 0 ELSE SUM(clicks) * 1.0 / SUM(impressions) END",
+	position: "CASE WHEN SUM(impressions) = 0 THEN NULL ELSE SUM(sum_position) * 1.0 / SUM(impressions) END"
+};
+const DIM_COLUMN = {
+	page: "url",
+	query: "query",
+	country: "country",
+	date: "date",
+	searchAppearance: "search_appearance"
+};
+function tableForDimensions(dims) {
+	const set = new Set(dims.filter((d) => d !== "date"));
+	if (set.has("page") && set.has("query")) return "page_queries";
+	if (set.has("query")) return "queries";
+	if (set.has("country")) return "countries";
+	if (set.has("device")) return "dates";
+	return "pages";
+}
+function metricExpr(metric) {
+	const expr = METRIC_SQL[metric];
+	if (!expr) throw new Error(`[archetype-sql] unknown metric: ${metric}`);
+	return expr;
+}
+function metricSelectList(metrics) {
+	return metrics.map((m) => `${metricExpr(m)} AS ${m}`).join(", ");
+}
+const DEVICE_VALUES = [
+	"DESKTOP",
+	"MOBILE",
+	"TABLET"
+];
+const DEVICE_SUFFIX = {
+	DESKTOP: "desktop",
+	MOBILE: "mobile",
+	TABLET: "tablet"
+};
+function deviceMetricExpr(metric, suffix) {
+	switch (metric) {
+		case "clicks": return `SUM(clicks_${suffix})`;
+		case "impressions": return `SUM(impressions_${suffix})`;
+		case "ctr": return `CASE WHEN SUM(impressions_${suffix}) = 0 THEN 0 ELSE SUM(clicks_${suffix}) * 1.0 / SUM(impressions_${suffix}) END`;
+		case "position": return `CASE WHEN SUM(impressions_${suffix}) = 0 THEN NULL ELSE SUM(sum_position_${suffix}) * 1.0 / SUM(impressions_${suffix}) END`;
+		default: throw new Error(`[archetype-sql] unknown metric: ${metric}`);
+	}
+}
+function deviceUnpivotSql(metrics, whereSql, byDate) {
+	const dateCol = byDate ? "date, " : "";
+	const dateGroup = byDate ? " GROUP BY date" : "";
+	return DEVICE_VALUES.map((dv) => {
+		const suffix = DEVICE_SUFFIX[dv];
+		return `SELECT ${dateCol}'${dv}' AS device, ${metrics.map((m) => `${deviceMetricExpr(m, suffix)} AS ${m}`).join(", ")} FROM dates WHERE ${whereSql}${dateGroup}`;
+	}).join(" UNION ALL ");
+}
+function rangePredicate(q) {
+	return {
+		sql: "date BETWEEN ? AND ? AND search_type = ?",
+		params: [
+			q.range.start,
+			q.range.end,
+			q.searchType
+		]
+	};
+}
+function compileArchetypeSql(query) {
+	switch (query.archetype) {
+		case "site-daily-timeseries": {
+			const table = "dates";
+			const where = rangePredicate(query);
+			return {
+				table,
+				sql: `SELECT date, ${query.metrics.map((m) => `${metricExpr(m)} AS ${m}`).join(", ")} FROM ${table} WHERE ${where.sql} GROUP BY date ORDER BY date`,
+				params: where.params
+			};
+		}
+		case "entity-daily-timeseries": {
+			const table = tableForDimensions([query.entity.dimension]);
+			const col = DIM_COLUMN[query.entity.dimension];
+			const where = rangePredicate(query);
+			return {
+				table,
+				sql: `SELECT date, ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql} AND ${col} = ? GROUP BY date ORDER BY date`,
+				params: [...where.params, query.entity.value]
+			};
+		}
+		case "entity-daily-sparkline": {
+			const table = tableForDimensions([query.dimension]);
+			const col = DIM_COLUMN[query.dimension];
+			const where = rangePredicate(query);
+			if (query.entities.length === 0) throw new Error("[archetype-sql] entity-daily-sparkline requires resolved entities");
+			const placeholders = query.entities.map(() => "?").join(", ");
+			return {
+				table,
+				sql: `SELECT ${col} AS entity, date, ${metricExpr(query.metric)} AS ${query.metric} FROM ${table} WHERE ${where.sql} AND ${col} IN (${placeholders}) GROUP BY ${col}, date ORDER BY ${col}, date`,
+				params: [...where.params, ...query.entities]
+			};
+		}
+		case "top-n-breakdown": {
+			const table = tableForDimensions([query.dimension]);
+			const where = rangePredicate(query);
+			const dir = query.orderBy.dir === "asc" ? "ASC" : "DESC";
+			if (query.dimension === "device") {
+				let sql = `SELECT device, ${query.metrics.join(", ")} FROM (${deviceUnpivotSql(query.metrics, where.sql, false)}) ORDER BY ${query.orderBy.metric} ${dir} LIMIT ?`;
+				const params = [
+					...where.params,
+					...where.params,
+					...where.params,
+					query.limit
+				];
+				if (query.offset && query.offset > 0) {
+					sql += " OFFSET ?";
+					params.push(query.offset);
+				}
+				return {
+					table,
+					sql,
+					params
+				};
+			}
+			const col = DIM_COLUMN[query.dimension];
+			let sql = `SELECT ${col} AS ${query.dimension}, ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql} GROUP BY ${col} ORDER BY ${query.orderBy.metric} ${dir} LIMIT ?`;
+			const params = [...where.params, query.limit];
+			if (query.offset && query.offset > 0) {
+				sql += " OFFSET ?";
+				params.push(query.offset);
+			}
+			return {
+				table,
+				sql,
+				params
+			};
+		}
+		case "single-row-lookup": {
+			const table = tableForDimensions(Object.keys(query.match));
+			const where = rangePredicate(query);
+			const matchParts = [];
+			const matchParams = [];
+			for (const [dim, value] of Object.entries(query.match)) {
+				const col = DIM_COLUMN[dim];
+				if (!col) throw new Error(`[archetype-sql] single-row-lookup: unknown dimension ${dim}`);
+				matchParts.push(`${col} = ?`);
+				matchParams.push(value);
+			}
+			const matchSql = matchParts.length ? ` AND ${matchParts.join(" AND ")}` : "";
+			return {
+				table,
+				sql: `SELECT ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql}${matchSql}`,
+				params: [...where.params, ...matchParams]
+			};
+		}
+		case "multi-series-stacked-daily": {
+			const table = tableForDimensions([query.seriesDimension]);
+			const where = rangePredicate(query);
+			if (query.seriesDimension === "device") return {
+				table,
+				sql: `SELECT date, device, ${query.metric} FROM (${deviceUnpivotSql([query.metric], where.sql, true)}) ORDER BY date, device`,
+				params: [
+					...where.params,
+					...where.params,
+					...where.params
+				]
+			};
+			const col = DIM_COLUMN[query.seriesDimension];
+			return {
+				table,
+				sql: `SELECT date, ${col} AS ${query.seriesDimension}, ${metricExpr(query.metric)} AS ${query.metric} FROM ${table} WHERE ${where.sql} GROUP BY date, ${col} ORDER BY date, ${col}`,
+				params: where.params
+			};
+		}
+		case "preset-analyzer": {
+			const table = "queries";
+			const where = rangePredicate(query);
+			const params = query.params ?? {};
+			const minPos = Number(params.minPosition ?? 4);
+			const maxPos = Number(params.maxPosition ?? 20);
+			const minImpr = Number(params.minImpressions ?? 10);
+			const limit = Number(params.limit ?? 1e3);
+			return {
+				table,
+				sql: `SELECT query, ${metricExpr("clicks")} AS clicks, ${metricExpr("impressions")} AS impressions, ${metricExpr("position")} AS position FROM ${table} WHERE ${where.sql} GROUP BY query HAVING position BETWEEN ? AND ? AND impressions > ? ORDER BY impressions DESC LIMIT ?`,
+				params: [
+					...where.params,
+					minPos,
+					maxPos,
+					minImpr,
+					limit
+				]
+			};
+		}
+		case "two-dimension-detail": {
+			const table = "page_queries";
+			const where = rangePredicate(query);
+			const filterParts = [];
+			const filterParams = [];
+			if (query.filter?.page) {
+				filterParts.push("url = ?");
+				filterParams.push(query.filter.page);
+			}
+			if (query.filter?.query) {
+				filterParts.push("query = ?");
+				filterParams.push(query.filter.query);
+			}
+			const filterSql = filterParts.length ? ` AND ${filterParts.join(" AND ")}` : "";
+			let sql = `SELECT url AS page, query, ${metricSelectList(query.metrics)} FROM ${table} WHERE ${where.sql}${filterSql} GROUP BY url, query`;
+			const params = [...where.params, ...filterParams];
+			if (query.orderBy) {
+				const dir = query.orderBy.dir === "asc" ? "ASC" : "DESC";
+				sql += ` ORDER BY ${query.orderBy.metric} ${dir}`;
+			}
+			if (typeof query.limit === "number") {
+				sql += " LIMIT ?";
+				params.push(query.limit);
+			}
+			return {
+				table,
+				sql,
+				params
+			};
+		}
+		case "arbitrary-sql": return {
+			table: "page_queries",
+			sql: query.sql,
+			params: [...query.params ?? []]
+		};
+		case "aux-cloud-only": throw new Error("[archetype-sql] aux-cloud-only is not an Iceberg query — route to the cloud endpoint");
+		default: throw new Error(`[archetype-sql] unhandled archetype: ${query.archetype}`);
+	}
+}
+function tableForArchetype(query) {
+	if (query.archetype === "aux-cloud-only") return null;
+	return compileArchetypeSql(query).table;
+}
 async function createClient(db, conn) {
 	return {
 		db,
@@ -104,16 +338,16 @@ async function strikingMomentum(runner, opts = {}) {
       SELECT
         query,
         url,
-        ${page_keywords.date} AS date,
-        ${page_keywords.impressions} AS impressions,
-        ${page_keywords.sum_position} AS sum_position,
+        ${page_queries.date} AS date,
+        ${page_queries.impressions} AS impressions,
+        ${page_queries.sum_position} AS sum_position,
         CASE
-          WHEN ${page_keywords.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays}`)} DAY)
+          WHEN ${page_queries.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays}`)} DAY)
           THEN 'recent' ELSE 'prior'
         END AS period
-      FROM ${page_keywords}
-      WHERE ${page_keywords.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays * 2}`)} DAY)
-        AND ${page_keywords.date} <  (DATE ${sql.raw(`'${anchor}'`)} + INTERVAL 1 DAY)
+      FROM ${page_queries}
+      WHERE ${page_queries.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays * 2}`)} DAY)
+        AND ${page_queries.date} <  (DATE ${sql.raw(`'${anchor}'`)} + INTERVAL 1 DAY)
     ),
     agg AS (
       SELECT
@@ -154,6 +388,206 @@ async function strikingMomentum(runner, opts = {}) {
   `;
 	return await runner.db.execute(windowExpr);
 }
+var OpfsQuotaExceededError = class extends Error {
+	name = "OpfsQuotaExceededError";
+	degradedTables;
+	constructor(message, degradedTables) {
+		super(message);
+		this.degradedTables = degradedTables;
+	}
+};
+const DEFAULT_CONCURRENCY = 2;
+const OPFS_PREFIX = "gscdump-snapshot__";
+function isQuotaError(err) {
+	if (typeof err !== "object" || err === null) return false;
+	return err.name === "QuotaExceededError" || err.code === 22;
+}
+function isAbortError$1(err) {
+	return typeof err === "object" && err !== null && err.name === "AbortError";
+}
+function opfsFileName(table, index) {
+	return `${OPFS_PREFIX}${table}_${index}.parquet`;
+}
+async function requestPersistentStorage() {
+	const storage = globalThis.navigator?.storage;
+	if (!storage?.persist) return false;
+	if (await storage.persisted?.().catch(() => false)) return true;
+	return storage.persist().catch(() => false);
+}
+async function estimateOpfsStorage() {
+	const estimate = globalThis.navigator?.storage?.estimate;
+	if (!estimate) return {};
+	const est = await estimate.call(globalThis.navigator.storage).catch(() => null);
+	return est ? {
+		usageBytes: est.usage,
+		quotaBytes: est.quota
+	} : {};
+}
+async function sha256Hex(bytes) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function getOpfsRoot() {
+	const dir = globalThis.navigator?.storage?.getDirectory;
+	if (!dir) throw new Error("[engine-duckdb-wasm/opfs] OPFS unavailable: navigator.storage.getDirectory missing");
+	return dir.call(globalThis.navigator.storage);
+}
+async function materialiseFile(root, name, file, fetchImpl, fetchInit, signal) {
+	signal?.throwIfAborted();
+	let handle;
+	try {
+		handle = await root.getFileHandle(name);
+		const cached = await handle.getFile();
+		if (cached.size === file.bytes) {
+			if (!file.contentHash) return {
+				handle,
+				outcome: "cache-hit"
+			};
+			if (await sha256Hex(await cached.arrayBuffer()) === file.contentHash.toLowerCase()) return {
+				handle,
+				outcome: "cache-hit"
+			};
+		}
+	} catch {}
+	signal?.throwIfAborted();
+	const resp = await fetchImpl(file.url, {
+		...fetchInit,
+		signal
+	});
+	if (!resp.ok) throw new Error(`[engine-duckdb-wasm/opfs] download ${file.url} failed: ${resp.status}`);
+	const buf = await resp.arrayBuffer();
+	if (file.contentHash) {
+		const hash = await sha256Hex(buf);
+		if (hash !== file.contentHash.toLowerCase()) throw new Error(`[engine-duckdb-wasm/opfs] content-hash mismatch for ${file.url}: expected ${file.contentHash}, got ${hash}`);
+	}
+	handle = await root.getFileHandle(name, { create: true });
+	const writable = await handle.createWritable();
+	try {
+		await writable.write(buf);
+		await writable.close();
+	} catch (err) {
+		await writable.abort?.().catch(() => {});
+		await root.removeEntry(name).catch(() => {});
+		throw err;
+	}
+	return {
+		handle,
+		outcome: "downloaded"
+	};
+}
+function readParquetViewSql$1(schema, table, files) {
+	return `CREATE OR REPLACE VIEW ${schema}.${table} AS SELECT * REPLACE (CAST(date AS DATE) AS date) FROM read_parquet([${files.map((f) => `'${f.replace(/'/g, "''")}'`).join(", ")}], union_by_name = true)`;
+}
+async function runWithConcurrency$1(items, concurrency, fn) {
+	let next = 0;
+	let failed;
+	async function worker() {
+		while (failed === void 0 && next < items.length) {
+			const index = next++;
+			try {
+				await fn(items[index], index);
+			} catch (err) {
+				failed = err;
+				throw err;
+			}
+		}
+	}
+	await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+}
+async function attachOpfsParquetTables(options) {
+	const { db, conn, tables, schema = "main", fetch: fetchImpl = globalThis.fetch.bind(globalThis), fetchInit, fetchConcurrency = DEFAULT_CONCURRENCY, signal, version, onFileProgress } = options;
+	await requestPersistentStorage();
+	const root = await getOpfsRoot();
+	const flat = [];
+	for (const t of tables) for (let i = 0; i < t.files.length; i++) flat.push({
+		table: t.table,
+		file: t.files[i],
+		fileIndex: i
+	});
+	const total = flat.length;
+	const { DuckDBDataProtocol } = await import("@duckdb/duckdb-wasm");
+	const tableFiles = /* @__PURE__ */ new Map();
+	const degraded = /* @__PURE__ */ new Set();
+	let bytesAttached = 0;
+	await runWithConcurrency$1(flat, Math.max(1, fetchConcurrency), async (item, index) => {
+		if (degraded.has(item.table)) return;
+		signal?.throwIfAborted();
+		const name = opfsFileName(item.table, item.fileIndex);
+		let result;
+		try {
+			result = await materialiseFile(root, name, item.file, fetchImpl, fetchInit, signal);
+		} catch (err) {
+			if (isAbortError$1(err)) throw err;
+			if (isQuotaError(err)) {
+				degraded.add(item.table);
+				return;
+			}
+			throw err;
+		}
+		await db.registerFileHandle(name, result.handle, DuckDBDataProtocol.BROWSER_FSACCESS, true);
+		const list = tableFiles.get(item.table) ?? [];
+		list.push({
+			name,
+			handle: result.handle
+		});
+		tableFiles.set(item.table, list);
+		bytesAttached += item.file.bytes;
+		onFileProgress?.({
+			table: item.table,
+			file: name,
+			index,
+			total,
+			bytes: item.file.bytes,
+			outcome: result.outcome
+		});
+	});
+	const attached = [];
+	const registeredNames = [];
+	try {
+		for (const t of tables) {
+			if (degraded.has(t.table)) continue;
+			const files = tableFiles.get(t.table) ?? [];
+			if (files.length !== t.files.length) {
+				degraded.add(t.table);
+				continue;
+			}
+			signal?.throwIfAborted();
+			await conn.query(readParquetViewSql$1(schema, t.table, files.map((f) => f.name)));
+			attached.push(t.table);
+			for (const f of files) registeredNames.push(f.name);
+		}
+	} catch (err) {
+		await detachOpfs(db, conn, schema, attached, registeredNames).catch(() => {});
+		throw err;
+	}
+	let detached = false;
+	return {
+		version,
+		tables: attached,
+		schema,
+		bytesAttached,
+		degradedTables: [...degraded],
+		async detach() {
+			if (detached) return;
+			detached = true;
+			await detachOpfs(db, conn, schema, attached, registeredNames);
+		}
+	};
+}
+async function detachOpfs(db, conn, schema, tables, files) {
+	for (const table of tables) await conn.query(`DROP VIEW IF EXISTS ${schema}.${table}`).catch(() => {});
+	if (files.length > 0) await db.dropFiles([...files]).catch(() => {});
+}
+async function clearOpfsSnapshotCache() {
+	const root = await getOpfsRoot().catch(() => null);
+	if (!root) return;
+	const removable = [];
+	const dir = root;
+	if (dir.keys) {
+		for await (const name of dir.keys()) if (name.startsWith(OPFS_PREFIX)) removable.push(name);
+	}
+	for (const name of removable) await root.removeEntry(name).catch(() => {});
+}
 async function createInsightRunner(opts) {
 	const client = await createClient(opts.db, opts.conn);
 	const clientPromise = Promise.resolve(client);
@@ -521,4 +955,4 @@ function createBrowserAnalysisRuntime(boot, options = {}) {
 		}
 	};
 }
-export { BrowserAttachBudgetExceededError, DuckDBWasmDatabase, attachParquetTables, attachParquetUrlTables, bootDuckDBWasm, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, devices, drizzle, hourly_pages, keywords, mergeScope, page_keywords, pages, resolveWindow, schema, scopeFor, strikingMomentum };
+export { BrowserAttachBudgetExceededError, DuckDBWasmDatabase, OpfsQuotaExceededError, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, bootDuckDBWasm, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, mergeScope, page_queries, pages, queries, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-duckdb-wasm",
   "type": "module",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "DuckDB-WASM engine adapter for @gscdump/analysis — typed browser analytics against parquet via R2.",
   "author": {
     "name": "Harlan Wilton",
@@ -45,8 +45,9 @@
   },
   "dependencies": {
     "drizzle-orm": "^0.45.2",
-    "@gscdump/engine": "0.20.3",
-    "gscdump": "0.20.3"
+    "@gscdump/sdk": "0.21.0",
+    "@gscdump/engine": "0.21.0",
+    "gscdump": "0.21.0"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",