@gscdump/engine-duckdb-wasm 3.5.0 → 3.6.0

package/README.md

@@ -4,11 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@gscdump/engine-duckdb-wasm?color=yellow)](https://npm.chart.dev/@gscdump/engine-duckdb-wasm)
 [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
 
-> DuckDB-WASM engine adapter for `@gscdump/analysis` — typed browser analytics against parquet via R2.
-
-In-browser DuckDB-WASM connection wrapped as a `SqlQuerySource`. Ships a vendored, stripped-down drizzle-orm DuckDB-WASM adapter (~240 LoC, adapted from `@proj-airi/drizzle-duckdb-wasm`, MIT). Transactions throw — analytics workload is read-only.
-
-Bundle: **10.3 kB / 2.72 kB gzipped**. `@duckdb/duckdb-wasm` is an optional peer dep.
+Run DuckDB queries and Analyzers over Parquet files in the browser.
 
 ## Install
 
@@ -16,7 +12,7 @@ Bundle: **10.3 kB / 2.72 kB gzipped**. `@duckdb/duckdb-wasm` is an optional peer
 npm install @gscdump/engine-duckdb-wasm @duckdb/duckdb-wasm
 ```
 
-## Usage
+## Query Parquet URLs
 
 ```ts
 import {
@@ -26,59 +22,66 @@ import {
 } from '@gscdump/engine-duckdb-wasm'
 
 const { db, conn } = await bootDuckDBWasm()
-await attachParquetUrlTables(conn, { tables: [{ name: 'queries', url: '/r2/queries.parquet' }] })
+await attachParquetUrlTables({
+  db,
+  conn,
+  tables: [{ table: 'queries', urls: ['https://example.com/data/queries.parquet'] }],
+  maxFiles: 10,
+  maxBytes: 50_000_000,
+})
 
 const runner = await createInsightRunner({ db, conn })
 const client = await runner.client
 const rows = await client.query('SELECT query, clicks, impressions FROM queries LIMIT 50')
+console.log(rows)
+await runner.close()
+await db.terminate()
 ```
 
-## Browser Parquet Attachment Strategy
+Replace the URL with a Parquet file containing the expected table columns, including `date`.
+The endpoint must support browser access and byte-range reads.
 
-`attachParquetUrlTables()` uses URL registration with DuckDB-WASM's HTTP file
-reader rather than downloading parquet objects into JS memory. Each exact-object
-URL is preflighted with `HEAD`; if the endpoint does not support `HEAD`, the
-runtime performs a one-byte `Range: bytes=0-0` probe. Attachment fails closed
-unless the response proves `Content-Length` / `Content-Range` and byte-range
-support.
+## Attachment and caching
 
-The runtime keeps local guards independent of the server response:
-`maxFiles`, `maxBytes`, `fetchConcurrency`, and `AbortSignal` are enforced
-before registering files. `bootDuckDBWasm()` opens DuckDB with full HTTP reads
-disabled, so a server that cannot satisfy range reads routes to server-side
-fallback instead of causing broad browser object downloads.
+`attachParquetUrlTables` registers URLs with DuckDB's HTTP reader.
+It supports `maxFiles`, `maxBytes`, `fetchConcurrency`, and `signal` limits.
 
-OPFS (`attachOpfsParquetTables` et al., in `src/opfs.ts`) is the primary
-write-through parquet cache: attached snapshot files persist keyed by
-manifest `contentHash`/object key, gated by the same file/byte budgets before
-anything is materialized locally.
+Preflight uses `HEAD`, with a one-byte range probe when needed.
+Trusted URL size hints can skip preflight by default; set `trustSizeHint: false` to require endpoint checks.
+The default HTTP mode disables full-file fallback reads.
+Handle attachment failures in your application if you want to offer server queries instead.
 
-### Attaching parquet as analyzer sources
+`fetchInit` applies to preflight requests only.
+DuckDB's own range reads need URLs that work without custom request headers.
 
-Per [ADR-0001](../../docs/adr/0001-browser-engine-uses-attached-tables.md), the
-browser engine dispatches over attached parquet tables (`createAttachedTableSource`
-from `@gscdump/engine/source`, wired up inside `createBrowserAnalysisRuntime`),
-not a canonical-schema `SqlQuerySource`. An earlier `createEngine()` wrapping the
-canonical-schema path had zero callers and was deleted in 2026-05 — don't
-reintroduce it; extend `createAttachedTableSource` or the attach helpers below
-instead.
+Use `attachOpfsParquetTables` to cache snapshot files in the browser's Origin Private File System.
+Its file and byte limits apply before download.
+Use `estimateOpfsStorage`, `requestPersistentStorage`, and `clearOpfsSnapshotCache` to manage that cache.
 
-## Exports
+## Analyzers
 
-- `createInsightRunner({ db, conn })` — drizzle-orm handle for typed `.select()` / window functions, with `sql\`...\`` raw escape hatch.
-- `bootDuckDBWasm()` / `attachParquetTables()` / `attachParquetUrlTables()` / `attachSingleTable()` / `createBrowserAnalysisRuntime()` / `createDuckDBBundlesFromBase()` / `listAttachedTables()` — browser runtime primitives.
-- `attachOpfsParquetTables()` / `readOpfsSnapshotFile()` / `estimateOpfsStorage()` / `requestPersistentStorage()` / `clearOpfsSnapshotCache()` — OPFS-backed parquet cache.
-- `scopeFor(table, { siteId, window })` / `mergeScope()` — tenant scope predicates.
-- `pages` / `queries` / `page_queries` / `countries` / `dates` / `hourly_pages` / `schema` — drizzle schema mirroring `gscdump/analytics` `SCHEMAS`. Drift fails loudly at module load.
-- `compileArchetypeSql()` / `tableForArchetype()` — archetype query compilation.
-- `createClient` / `drizzle` / `DuckDBWasmDatabase` — vendored drizzle-orm DuckDB-WASM adapter.
-- `resolveWindow` (re-exported from `@gscdump/engine/period`).
+`createBrowserAnalysisRuntime` runs Analyzers against attached tables.
+See [`@gscdump/analysis`](../analysis/README.md#duckdb-and-browser-use) and
+[ADR-0001](../../docs/adr/0001-browser-engine-uses-attached-tables.md) for the Source contract.
 
-## Related
+The package includes a vendored Drizzle adapter for typed queries.
+Transactions are unsupported.
+
+## Exports
 
-- [`@gscdump/engine`](../engine) — Storage contracts + dialect-neutral resolver.
-- [`@gscdump/analysis`](../analysis) — Portable analyzer registry and browser dispatch.
-- [`@gscdump/engine-sqlite`](../engine-sqlite) — SQLite / D1 counterpart.
+| Group | Exports |
+| --- | --- |
+| Runtime | `bootDuckDBWasm`, `createInsightRunner`, `createBrowserAnalysisRuntime` |
+| Attachment | `attachParquetTables`, `attachParquetUrlTables`, `attachParquetUrlTablesResult` |
+| OPFS | `attachOpfsParquetTables`, `readOpfsSnapshotFile`, storage and cache helpers |
+| Schema | `pages`, `queries`, `page_queries`, `countries`, `dates`, `hourly_pages`, `schema` |
+| Queries | `compileArchetypeSql`, `tableForArchetype`, `scopeFor`, `mergeScope` |
+| Drizzle | `createClient`, `drizzle`, `DuckDBWasmDatabase` |
+| Dates | `resolveWindow`, re-exported from `@gscdump/engine/period` |
+
+Schema exports follow `@gscdump/engine/schema`.
+Parquet snapshots are Site-specific; browser `scopeFor` currently adds no `siteId` predicate.
+Keep authorization and file selection in your application.
 
 ## License
 

package/dist/archetype-sql.d.mts

@@ -1,6 +1,6 @@
 import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
 /** A compiled, parameterised statement. */
-interface CompiledArchetypeSql {
+export interface CompiledArchetypeSql {
   sql: string;
   params: unknown[];
   /** The fact-table view the query reads. */
@@ -9,7 +9,6 @@ interface CompiledArchetypeSql {
 /**
  * Compile one archetype query to DuckDB SQL. Throws for `aux-cloud-only`.
  */
-declare function compileArchetypeSql(query: ArchetypeQuery): CompiledArchetypeSql;
+export 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;
-export { CompiledArchetypeSql, compileArchetypeSql, tableForArchetype };
+export declare function tableForArchetype(query: ArchetypeQuery): string | null;

package/dist/drizzle-adapter/client.d.mts

@@ -1,9 +1,8 @@
 import { AsyncDuckDB, AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
-interface DuckDBWasmClient {
+export interface DuckDBWasmClient {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
   query: (sql: string, params?: unknown[]) => Promise<Record<string, unknown>[]>;
   close: () => Promise<void>;
 }
-declare function createClient(db: AsyncDuckDB, conn: AsyncDuckDBConnection): Promise<DuckDBWasmClient>;
-export { DuckDBWasmClient, createClient };
+export declare function createClient(db: AsyncDuckDB, conn: AsyncDuckDBConnection): Promise<DuckDBWasmClient>;

package/dist/drizzle-adapter/driver.d.mts

@@ -4,11 +4,10 @@ import { DrizzleConfig, entityKind } from "drizzle-orm";
 import { PgAsyncDatabase } from "drizzle-orm/pg-core";
 import { AnyRelations, EmptyRelations, ExtractTablesWithRelations, Schema } from "drizzle-orm/relations";
 type SchemaRelations<TSchema extends Schema> = ExtractTablesWithRelations<Record<string, never>, TSchema>;
-declare class DuckDBWasmDatabase<TRelations extends AnyRelations = EmptyRelations> extends PgAsyncDatabase<DuckDBWasmQueryResultHKT, TRelations> {
+export declare class DuckDBWasmDatabase<TRelations extends AnyRelations = EmptyRelations> extends PgAsyncDatabase<DuckDBWasmQueryResultHKT, TRelations> {
   static readonly [entityKind]: string;
 }
-interface DuckDBWasmDrizzleDatabase<TSchema extends Schema = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>> extends DuckDBWasmDatabase<TRelations> {
+export interface DuckDBWasmDrizzleDatabase<TSchema extends Schema = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>> extends DuckDBWasmDatabase<TRelations> {
   $client: Promise<DuckDBWasmClient>;
 }
-declare function drizzle<TSchema extends Schema = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>>(client: Promise<DuckDBWasmClient> | DuckDBWasmClient, config?: DrizzleConfig<TSchema, TRelations>): DuckDBWasmDrizzleDatabase<TSchema, TRelations>;
-export { DuckDBWasmDatabase, DuckDBWasmDrizzleDatabase, drizzle };
+export declare function drizzle<TSchema extends Schema = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>>(client: Promise<DuckDBWasmClient> | DuckDBWasmClient, config?: DrizzleConfig<TSchema, TRelations>): DuckDBWasmDrizzleDatabase<TSchema, TRelations>;

package/dist/drizzle-adapter/session.d.mts

@@ -1,8 +1,7 @@
 import "./client.mjs";
 import { Assume, entityKind } from "drizzle-orm";
 import { PgAsyncPreparedQuery, PgAsyncSession, PgDialect, PgQueryResultHKT } from "drizzle-orm/pg-core";
-type Row = Record<string, unknown>;
-interface DuckDBWasmQueryResultHKT extends PgQueryResultHKT {
+export type Row = Record<string, unknown>;
+export interface DuckDBWasmQueryResultHKT extends PgQueryResultHKT {
   type: Assume<this['row'], Row>[];
-}
-export { DuckDBWasmQueryResultHKT, Row };
+}

package/dist/opfs.d.mts

@@ -1,6 +1,6 @@
 import { AsyncDuckDB, AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
 /** A parquet data file to materialise into OPFS. */
-interface OpfsParquetFile {
+export 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. */
@@ -17,7 +17,7 @@ interface OpfsParquetFile {
   rowCount?: number;
 }
 /** One logical table and the parquet files that compose it. */
-interface OpfsParquetTable {
+export interface OpfsParquetTable {
   /** Iceberg table name — becomes the DuckDB view name. */
   table: string;
   files: OpfsParquetFile[];
@@ -33,7 +33,7 @@ interface OpfsParquetTable {
    */
   overlay?: OpfsParquetFile;
 }
-interface AttachOpfsTablesOptions {
+export interface AttachOpfsTablesOptions {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
   tables: OpfsParquetTable[];
@@ -87,7 +87,7 @@ interface AttachOpfsTablesOptions {
    */
   recoverContention?: boolean;
 }
-interface OpfsFileProgress {
+export interface OpfsFileProgress {
   table: string;
   /** OPFS file name. */
   file: string;
@@ -106,8 +106,8 @@ interface OpfsFileProgress {
   /** End-to-end file phase time, materialise + register + callback overhead. */
   totalMs?: number;
 }
-type OpfsAttachTimingStage = 'persist' | 'root' | 'plan' | 'duckdb-import' | 'sweep' | 'materialise' | 'register' | 'downloads' | 'view' | 'recovery' | 'total';
-interface OpfsAttachTiming {
+export type OpfsAttachTimingStage = 'persist' | 'root' | 'plan' | 'duckdb-import' | 'sweep' | 'materialise' | 'register' | 'downloads' | 'view' | 'recovery' | 'total';
+export interface OpfsAttachTiming {
   stage: OpfsAttachTimingStage;
   durationMs: number;
   table?: string;
@@ -118,7 +118,7 @@ interface OpfsAttachTiming {
   outcome?: 'cache-hit' | 'downloaded';
 }
 /** Handle returned from {@link attachOpfsParquetTables}. */
-interface OpfsAttachedHandle {
+export interface OpfsAttachedHandle {
   version: string | undefined;
   /** Tables that successfully attached (a per-table failure drops only that table). */
   tables: string[];
@@ -144,7 +144,7 @@ interface OpfsAttachedHandle {
  * 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 {
+export declare class OpfsQuotaExceededError extends Error {
   name: string;
   /** Tables that did not fit. */
   readonly degradedTables: string[];
@@ -155,9 +155,9 @@ declare class OpfsQuotaExceededError extends Error {
  * 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>;
+export declare function requestPersistentStorage(): Promise<boolean>;
 /** Best-effort `{ usageBytes, quotaBytes }` from the Storage API. */
-declare function estimateOpfsStorage(): Promise<{
+export declare function estimateOpfsStorage(): Promise<{
   usageBytes?: number;
   quotaBytes?: number;
 }>;
@@ -174,7 +174,7 @@ declare function estimateOpfsStorage(): Promise<{
  * logic to drift out of lock-step. `index` is only the disambiguator for the
  * degraded no-`contentHash` fallback (mirrors `attachOpfsParquetTables`).
  */
-declare function readOpfsSnapshotFile(table: string, contentHash: string | undefined, index: number, expectedBytes: number): Promise<Uint8Array | null>;
+export declare function readOpfsSnapshotFile(table: string, contentHash: string | undefined, index: number, expectedBytes: number): Promise<Uint8Array | null>;
 /**
  * Download every parquet file in `tables` into OPFS, content-hash verify, and
  * attach them as DuckDB-WASM views. Attach-once: call this once per
@@ -185,11 +185,10 @@ declare function readOpfsSnapshotFile(table: string, contentHash: string | undef
  * 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>;
+export 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>;
-export { AttachOpfsTablesOptions, OpfsAttachTiming, OpfsAttachTimingStage, OpfsAttachedHandle, OpfsFileProgress, OpfsParquetFile, OpfsParquetTable, OpfsQuotaExceededError, attachOpfsParquetTables, clearOpfsSnapshotCache, estimateOpfsStorage, readOpfsSnapshotFile, requestPersistentStorage };
+export declare function clearOpfsSnapshotCache(): Promise<void>;

package/dist/opfs.mjs

@@ -104,15 +104,15 @@ function opfsFileName(table, hashSlug, index) {
 function escapeRegExp(s) {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function tableEntryMatcher(table) {
-	return new RegExp(`^${escapeRegExp(`${OPFS_PREFIX}${table}_`)}(?:[0-9a-f]{16}|\\d+(?:_[0-9a-f]{16})?)\\.parquet$`);
+function legacyEntryMatcher(table) {
+	return new RegExp(`^${escapeRegExp(`${OPFS_PREFIX}${table}_`)}(?![0-9a-f]{16}\\.parquet$)\\d+(?:_[0-9a-f]{16})?\\.parquet$`);
 }
-async function sweepStaleEntries(root, registry, expectedByTable) {
+async function sweepLegacyEntries(root, registry, expectedByTable) {
 	const dir = root;
 	if (!dir.keys) return;
 	const matchers = [...expectedByTable].map(([table, expected]) => ({
 		expected,
-		re: tableEntryMatcher(table)
+		re: legacyEntryMatcher(table)
 	}));
 	for await (const name of dir.keys()) {
 		const m = matchers.find((m) => m.re.test(name));
@@ -120,7 +120,7 @@ async function sweepStaleEntries(root, registry, expectedByTable) {
 		try {
 			await root.removeEntry(name);
 		} catch (error) {
-			if (!isNotFoundError(error)) reportBestEffortFailure(`removing stale OPFS entry ${name}`, error);
+			if (!isNotFoundError(error)) reportBestEffortFailure(`removing legacy OPFS entry ${name}`, error);
 		}
 	}
 }
@@ -177,18 +177,47 @@ async function readOpfsSnapshotFile(table, contentHash, index, expectedBytes) {
 		return null;
 	}
 }
-async function materialiseFile(root, name, file, fetchImpl, fetchInit, signal) {
+const fileWriteTails = /* @__PURE__ */ new Map();
+async function withFileWrite(name, signal, write) {
 	signal?.throwIfAborted();
-	let handle;
+	const previous = fileWriteTails.get(name) ?? Promise.resolve();
+	const released = Promise.withResolvers();
+	const tail = previous.then(() => released.promise);
+	fileWriteTails.set(name, tail);
+	tail.then(() => {
+		if (fileWriteTails.get(name) === tail) fileWriteTails.delete(name);
+	});
+	let onAbort;
+	try {
+		if (signal) await new Promise((resolve, reject) => {
+			onAbort = () => reject(signal.reason);
+			signal.addEventListener("abort", onAbort, { once: true });
+			previous.then(resolve);
+		});
+		else await previous;
+		signal?.throwIfAborted();
+		return await write();
+	} finally {
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		released.resolve();
+	}
+}
+async function cachedFile(root, name, expectedBytes) {
 	try {
-		handle = await root.getFileHandle(name);
-		if ((await handle.getFile()).size === file.bytes) return {
-			handle,
-			outcome: "cache-hit"
-		};
+		const handle = await root.getFileHandle(name);
+		return (await handle.getFile()).size === expectedBytes ? handle : void 0;
 	} catch (error) {
 		if (!isNotFoundError(error)) throw error;
+		return;
 	}
+}
+async function materialiseFile(root, name, file, fetchImpl, fetchInit, signal) {
+	signal?.throwIfAborted();
+	const cached = await cachedFile(root, name, file.bytes);
+	if (cached) return {
+		handle: cached,
+		outcome: "cache-hit"
+	};
 	signal?.throwIfAborted();
 	const deadline = AbortSignal.timeout(DOWNLOAD_DEADLINE_MS);
 	const fetchSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
@@ -197,45 +226,56 @@ async function materialiseFile(root, name, file, fetchImpl, fetchInit, signal) {
 		signal: fetchSignal
 	});
 	if (!resp.ok) throw new Error(`[engine-duckdb-wasm/opfs] download ${file.url} failed: ${resp.status}`);
-	handle = await root.getFileHandle(name, { create: true });
-	let writable;
-	try {
-		writable = await handle.createWritable();
-	} catch (err) {
-		await resp.body?.cancel().catch(() => void 0);
-		throw err;
-	}
-	let reader;
-	let bytesWritten = 0;
 	try {
-		if (resp.body) {
-			reader = resp.body.getReader();
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				bytesWritten += value.byteLength;
-				if (bytesWritten > file.bytes) throw new Error(`[engine-duckdb-wasm/opfs] download ${file.url} byte length mismatch: expected ${file.bytes}, got more than ${file.bytes}`);
-				await writable.write(value);
+		return await withFileWrite(name, signal, async () => {
+			const cached = await cachedFile(root, name, file.bytes);
+			if (cached) return {
+				handle: cached,
+				outcome: "cache-hit"
+			};
+			const handle = await root.getFileHandle(name, { create: true });
+			let writable;
+			try {
+				writable = await handle.createWritable();
+			} catch (err) {
+				await resp.body?.cancel().catch(() => void 0);
+				throw err;
 			}
-		} else {
-			const buf = await resp.arrayBuffer();
-			bytesWritten = buf.byteLength;
-			await writable.write(buf);
-		}
-		if (bytesWritten !== file.bytes) throw new Error(`[engine-duckdb-wasm/opfs] download ${file.url} byte length mismatch: expected ${file.bytes}, got ${bytesWritten}`);
-		await writable.close();
-	} catch (err) {
-		await reader?.cancel().catch(() => void 0);
-		if (writable.abort) await attemptCleanup(`aborting partial OPFS write ${name}`, () => writable.abort());
-		await attemptCleanup(`removing partial OPFS file ${name}`, () => root.removeEntry(name));
-		throw err;
+			let reader;
+			let bytesWritten = 0;
+			try {
+				if (resp.body) {
+					reader = resp.body.getReader();
+					while (true) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						bytesWritten += value.byteLength;
+						if (bytesWritten > file.bytes) throw new Error(`[engine-duckdb-wasm/opfs] download ${file.url} byte length mismatch: expected ${file.bytes}, got more than ${file.bytes}`);
+						await writable.write(value);
+					}
+				} else {
+					const buf = await resp.arrayBuffer();
+					bytesWritten = buf.byteLength;
+					await writable.write(buf);
+				}
+				if (bytesWritten !== file.bytes) throw new Error(`[engine-duckdb-wasm/opfs] download ${file.url} byte length mismatch: expected ${file.bytes}, got ${bytesWritten}`);
+				await writable.close();
+			} catch (err) {
+				await reader?.cancel().catch(() => void 0);
+				if (writable.abort) await attemptCleanup(`aborting partial OPFS write ${name}`, () => writable.abort());
+				await attemptCleanup(`removing partial OPFS file ${name}`, () => root.removeEntry(name));
+				throw err;
+			} finally {
+				reader?.releaseLock();
+			}
+			return {
+				handle,
+				outcome: "downloaded"
+			};
+		});
 	} finally {
-		reader?.releaseLock();
+		if (resp.body && !resp.bodyUsed) await attemptCleanup(`cancelling unused OPFS download ${name}`, () => resp.body.cancel());
 	}
-	return {
-		handle,
-		outcome: "downloaded"
-	};
 }
 function quoteList(files) {
 	return files.map((f) => `'${f.replace(/'/g, "''")}'`).join(", ");
@@ -340,8 +380,8 @@ async function attachOpfsParquetTables(options) {
 	await timed(onTiming, "sweep", {
 		files: total,
 		tables: tables.length
-	}, () => sweepStaleEntries(root, registry, expectedByTable)).catch((error) => {
-		reportBestEffortFailure("stale OPFS cache sweep", error);
+	}, () => sweepLegacyEntries(root, registry, expectedByTable)).catch((error) => {
+		reportBestEffortFailure("legacy OPFS cache sweep", error);
 	});
 	const tableFiles = /* @__PURE__ */ new Map();
 	const degraded = /* @__PURE__ */ new Set();

package/dist/overlay-view.d.mts

@@ -25,9 +25,8 @@
  * plain CTE inlines and re-scans the parquet, the dominant cost in DuckDB-WASM.
  * Set false to keep the streaming re-scan shape (lower peak memory, two scans).
  */
-declare function overlayViewBody(args: {
+export declare function overlayViewBody(args: {
   lakeSelect: string | null;
   overlaySelect: string | null;
   materializeLake?: boolean;
-}): string | null;
-export { overlayViewBody };
+}): string | null;

package/dist/runner.d.mts

@@ -4,17 +4,17 @@ import "./drizzle-adapter/index.mjs";
 import { Schema } from "./schema.mjs";
 import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
 import { AsyncDuckDB, AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
-interface InsightRunnerOptions {
+export interface InsightRunnerOptions {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
   logger?: boolean;
 }
-interface InsightRunner {
+export interface InsightRunner {
   db: DuckDBWasmDrizzleDatabase<Schema>;
   client: Promise<DuckDBWasmClient>;
   close: () => Promise<void>;
 }
-declare function createInsightRunner(opts: InsightRunnerOptions): Promise<InsightRunner>;
-declare const scopeFor: (table: "pages" | "queries" | "countries" | "page_queries" | "dates" | "search_appearance" | "search_appearance_pages" | "search_appearance_queries" | "search_appearance_page_queries" | "hourly_pages", opts: ScopedRunnerOptions) => TableScope;
-declare const mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
-export { InsightRunner, InsightRunnerOptions, type ScopedRunnerOptions, type TableScope, createInsightRunner, mergeScope, scopeFor };
+export declare function createInsightRunner(opts: InsightRunnerOptions): Promise<InsightRunner>;
+export declare const scopeFor: (table: "pages" | "queries" | "countries" | "page_queries" | "dates" | "search_appearance" | "search_appearance_pages" | "search_appearance_queries" | "search_appearance_page_queries" | "hourly_pages", opts: ScopedRunnerOptions) => TableScope;
+export declare const mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
+export type { ScopedRunnerOptions, TableScope };

package/dist/runtime.d.mts

@@ -2,20 +2,20 @@ import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
 import { Result } from "gscdump/result";
 import { AsyncDuckDB, AsyncDuckDBConnection, DuckDBBundles, DuckDBConfig } from "@duckdb/duckdb-wasm";
 import { AnalysisParams } from "@gscdump/engine/analysis-types";
-interface QueryResult {
+export interface QueryResult {
   rows: Record<string, unknown>[];
   queryMs: number;
 }
-interface AnalyzeResult {
+export interface AnalyzeResult {
   results: Record<string, unknown>[];
   meta: Record<string, unknown>;
   queryMs: number;
 }
-interface DuckDBWasmBootResult {
+export interface DuckDBWasmBootResult {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
 }
-interface BootDuckDBWasmOptions {
+export interface BootDuckDBWasmOptions {
   /**
    * DuckDB-WASM logger. Defaults to a `ConsoleLogger` thresholded at
    * `LogLevel.WARNING`, so real warnings/errors still surface but the per-query
@@ -48,25 +48,25 @@ interface BootDuckDBWasmOptions {
    */
   memoryLimit?: string;
 }
-interface BrowserParquetFile {
+export interface BrowserParquetFile {
   bytes: Uint8Array;
   name?: string;
 }
-interface BrowserParquetTable {
+export interface BrowserParquetTable {
   table: string;
   files: BrowserParquetFile[];
 }
-interface BrowserParquetUrlTable {
+export interface BrowserParquetUrlTable {
   table: string;
   urls: string[];
 }
-interface AttachParquetTablesOptions {
+export interface AttachParquetTablesOptions {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
   tables: BrowserParquetTable[];
   schema?: string;
 }
-interface AttachParquetUrlTablesOptions {
+export interface AttachParquetUrlTablesOptions {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
   tables: BrowserParquetUrlTable[];
@@ -136,13 +136,13 @@ interface AttachParquetUrlTablesOptions {
  * the created views (for lazy re-attach on a new manifest version) or cheap-
  * check the embedded version against a fresh probe.
  */
-interface AttachedTablesHandle {
+export interface AttachedTablesHandle {
   version: number | string | undefined;
   tables: string[];
   schema: string;
   detach: () => Promise<void>;
 }
-interface BrowserAnalysisRuntime {
+export interface BrowserAnalysisRuntime {
   db: AsyncDuckDB;
   conn: AsyncDuckDBConnection;
   query: (sql: string, params?: unknown[], signal?: AbortSignal) => Promise<QueryResult>;
@@ -168,23 +168,23 @@ interface BrowserAnalysisRuntime {
   setAttachedTables: (tables: readonly string[]) => void;
   close: () => Promise<void>;
 }
-declare class BrowserAttachBudgetExceededError extends Error {
+export declare class BrowserAttachBudgetExceededError extends Error {
   name: string;
 }
-interface BrowserAttachError {
+export interface BrowserAttachError {
   kind: 'browser-attach-budget-exceeded';
   message: string;
   /** Which budget tripped: the file count, the hinted byte plan, or the running byte plan. */
   budget: 'maxFiles' | 'maxBytes';
 }
-declare const browserAttachErrors: {
+export declare const browserAttachErrors: {
   readonly maxFilesExceeded: (files: number, maxFiles: number) => BrowserAttachError;
   readonly hintedBytesExceeded: (hintedBytes: number, maxBytes: number) => BrowserAttachError;
   readonly plannedBytesExceeded: (plannedBytes: number, maxBytes: number) => BrowserAttachError;
 };
-declare function isBrowserAttachError(value: unknown): value is BrowserAttachError;
-declare function bootDuckDBWasm(options?: BootDuckDBWasmOptions): Promise<DuckDBWasmBootResult>;
-declare function attachParquetTables(options: AttachParquetTablesOptions): Promise<void>;
+export declare function isBrowserAttachError(value: unknown): value is BrowserAttachError;
+export declare function bootDuckDBWasm(options?: BootDuckDBWasmOptions): Promise<DuckDBWasmBootResult>;
+export declare function attachParquetTables(options: AttachParquetTablesOptions): Promise<void>;
 /**
  * Errors-as-values core for {@link attachParquetUrlTables}: returns a typed
  * {@link BrowserAttachError} when the requested file set blows the local file-
@@ -193,7 +193,7 @@ declare function attachParquetTables(options: AttachParquetTablesOptions): Promi
  * failures stay defects and propagate. `attachParquetUrlTables` is the thin
  * throwing wrapper preserving the historical `BrowserAttachBudgetExceededError`.
  */
-declare function attachParquetUrlTablesResult(options: AttachParquetUrlTablesOptions): Promise<Result<AttachedTablesHandle, BrowserAttachError>>;
+export declare function attachParquetUrlTablesResult(options: AttachParquetUrlTablesOptions): Promise<Result<AttachedTablesHandle, BrowserAttachError>>;
 /**
  * Attach browser parquet URL tables, throwing
  * {@link BrowserAttachBudgetExceededError} when the requested set blows the
@@ -201,10 +201,9 @@ declare function attachParquetUrlTablesResult(options: AttachParquetUrlTablesOpt
  * {@link attachParquetUrlTablesResult}; existing call sites and their
  * `instanceof BrowserAttachBudgetExceededError` checks keep holding.
  */
-declare function attachParquetUrlTables(options: AttachParquetUrlTablesOptions): Promise<AttachedTablesHandle>;
-declare function createBrowserAnalysisRuntime(boot: DuckDBWasmBootResult, options?: {
+export declare function attachParquetUrlTables(options: AttachParquetUrlTablesOptions): Promise<AttachedTablesHandle>;
+export declare function createBrowserAnalysisRuntime(boot: DuckDBWasmBootResult, options?: {
   schema?: string;
   version?: number | string;
   attachedTables?: readonly string[];
-}): BrowserAnalysisRuntime;
-export { AnalyzeResult, AttachParquetTablesOptions, AttachParquetUrlTablesOptions, AttachedTablesHandle, BootDuckDBWasmOptions, BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, BrowserAttachError, BrowserParquetFile, BrowserParquetTable, BrowserParquetUrlTable, DuckDBWasmBootResult, QueryResult, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, createBrowserAnalysisRuntime, isBrowserAttachError };
+}): BrowserAnalysisRuntime;

package/dist/runtime.mjs

@@ -423,8 +423,11 @@ function createBrowserAnalysisRuntime(boot, options = {}) {
 			attachedTables = next;
 		},
 		async close() {
-			await conn.close();
-			await db.terminate();
+			try {
+				await conn.close();
+			} finally {
+				await db.terminate();
+			}
 		}
 	};
 }

package/dist/shared-runtime.d.mts

@@ -1,4 +1,4 @@
-type SharedAsyncResourceState = {
+export type SharedAsyncResourceState = {
   _tag: 'idle' | 'loading' | 'ready';
   consecutiveFailures: number;
   lastFailureAt: null;
@@ -8,21 +8,20 @@ type SharedAsyncResourceState = {
   lastFailureAt: number;
   error: unknown;
 };
-interface SharedAsyncResourceOptions<T> {
+export interface SharedAsyncResourceOptions<T> {
   load: () => Promise<T>;
   retryCooldownMs?: number;
   maxConsecutiveFailures?: number;
   now?: () => number;
   onStateChange?: (state: SharedAsyncResourceState) => void;
 }
-interface SharedAsyncResource<T> {
+export interface SharedAsyncResource<T> {
   get: () => Promise<T>;
   state: () => SharedAsyncResourceState;
   reset: () => void;
 }
-declare function createSharedAsyncResource<T>(options: SharedAsyncResourceOptions<T>): SharedAsyncResource<T>;
-interface ObjectAsyncLock<T extends object> {
+export declare function createSharedAsyncResource<T>(options: SharedAsyncResourceOptions<T>): SharedAsyncResource<T>;
+export interface ObjectAsyncLock<T extends object> {
   run: <R>(key: T, task: () => Promise<R>) => Promise<R>;
 }
-declare function createObjectAsyncLock<T extends object>(onRejected?: (error: unknown) => void): ObjectAsyncLock<T>;
-export { ObjectAsyncLock, SharedAsyncResource, SharedAsyncResourceOptions, SharedAsyncResourceState, createObjectAsyncLock, createSharedAsyncResource };
+export declare function createObjectAsyncLock<T extends object>(onRejected?: (error: unknown) => void): ObjectAsyncLock<T>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-duckdb-wasm",
   "type": "module",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "DuckDB-WASM engine adapter for @gscdump/analysis — typed browser analytics against parquet via R2.",
   "author": {
     "name": "Harlan Wilton",
@@ -44,17 +44,17 @@
     }
   },
   "dependencies": {
-    "@gscdump/contracts": "^3.5.0",
-    "@gscdump/engine": "^3.5.0",
+    "@gscdump/contracts": "^3.6.0",
+    "@gscdump/engine": "^3.6.0",
     "drizzle-orm": "1.0.0-rc.4",
-    "gscdump": "^3.5.0"
+    "gscdump": "^3.6.0"
   },
   "devDependencies": {
     "@duckdb/duckdb-wasm": "1.33.1-dev57.0",
-    "@vitest/browser": "^4.1.11",
-    "@vitest/browser-playwright": "^4.1.11",
-    "playwright": "^1.62.1",
-    "vitest": "^4.1.11"
+    "@vitest/browser": "^5.0.0",
+    "@vitest/browser-playwright": "^5.0.0",
+    "playwright": "^1.63.0",
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "obuild",