@gscdump/engine-duckdb-wasm 1.4.0 → 1.4.2

package/dist/index.d.mts

@@ -1,495 +1,11 @@
-import { Assume, DrizzleConfig, entityKind } from "drizzle-orm";
-import { PgAsyncDatabase, PgAsyncPreparedQuery, PgAsyncSession, PgDialect, PgQueryResultHKT } from "drizzle-orm/pg-core";
-import { AnyRelations, EmptyRelations, ExtractTablesWithRelations, Schema as Schema$1 } from "drizzle-orm/relations";
-import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
-import { DrizzleSchema as Schema, countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
-import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
-import { Result } from "gscdump/result";
+import { CompiledArchetypeSql, compileArchetypeSql, tableForArchetype } from "./archetype-sql.mjs";
+import { DuckDBWasmClient, createClient } from "./drizzle-adapter/client.mjs";
+import { DuckDBWasmDatabase, DuckDBWasmDrizzleDatabase, drizzle } from "./drizzle-adapter/driver.mjs";
+import "./drizzle-adapter/index.mjs";
+import { AttachOpfsTablesOptions, OpfsAttachTiming, OpfsAttachTimingStage, OpfsAttachedHandle, OpfsFileProgress, OpfsParquetFile, OpfsParquetTable, OpfsQuotaExceededError, attachOpfsParquetTables, clearOpfsSnapshotCache, estimateOpfsStorage, readOpfsSnapshotFile, requestPersistentStorage } from "./opfs.mjs";
+import { overlayViewBody } from "./overlay-view.mjs";
+import { Schema, countries, dates, hourly_pages, page_queries, pages, queries, schema } from "./schema.mjs";
+import { InsightRunner, InsightRunnerOptions, ScopedRunnerOptions, TableScope, createInsightRunner, mergeScope, scopeFor } from "./runner.mjs";
+import { AnalyzeResult, AttachParquetTablesOptions, AttachParquetUrlTablesOptions, AttachedTablesHandle, BootDuckDBWasmOptions, BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, BrowserAttachError, BrowserParquetFile, BrowserParquetTable, BrowserParquetUrlTable, DuckDBWasmBootResult, QueryResult, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, createBrowserAnalysisRuntime, isBrowserAttachError } from "./runtime.mjs";
 import { ComparisonMode, ResolveWindowOptions, ResolvedWindow, WindowPreset, resolveWindow } from "@gscdump/engine/period";
-import { ArchetypeQuery } from "@gscdump/contracts/archetypes";
-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;
-  query: (sql: string, params?: unknown[]) => Promise<Record<string, unknown>[]>;
-  close: () => Promise<void>;
-}
-declare function createClient(db: AsyncDuckDB, conn: AsyncDuckDBConnection): Promise<DuckDBWasmClient>;
-type Row = Record<string, unknown>;
-interface DuckDBWasmQueryResultHKT extends PgQueryResultHKT {
-  type: Assume<this['row'], Row>[];
-}
-type SchemaRelations<TSchema extends Schema$1> = ExtractTablesWithRelations<Record<string, never>, TSchema>;
-declare class DuckDBWasmDatabase<TRelations extends AnyRelations = EmptyRelations> extends PgAsyncDatabase<DuckDBWasmQueryResultHKT, TRelations> {
-  static readonly [entityKind]: string;
-}
-interface DuckDBWasmDrizzleDatabase<TSchema extends Schema$1 = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>> extends DuckDBWasmDatabase<TRelations> {
-  $client: Promise<DuckDBWasmClient>;
-}
-declare function drizzle<TSchema extends Schema$1 = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>>(client: Promise<DuckDBWasmClient> | DuckDBWasmClient, config?: DrizzleConfig<TSchema, TRelations>): DuckDBWasmDrizzleDatabase<TSchema, TRelations>;
-/** 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;
-  /**
-   * Opaque content-stable identifier for this file (e.g. the Iceberg data-
-   * file object key). Encoded into the OPFS filename so the same hash is the
-   * same cache entry. NOT required to be a SHA-256. When omitted, the cache
-   * key falls back to `(table, index)` and only the byte size is verified
-   * (degraded — stale entries can survive a content change).
-   */
-  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[];
-  /**
-   * Recent-window overlay parquet (the non-stable tail the lake excludes). When
-   * present it is materialised into OPFS alongside `files` and the view unions
-   * it with an anti-join dedup: the lake (`files`) serves every day it has, the
-   * overlay serves ONLY days the lake lacks. So a stale overlay whose days have
-   * since landed in the lake can't double-count, and a day that stabilised but
-   * isn't yet in the lake still serves from the overlay. Its `contentHash` must
-   * change when the overlay bytes change (it is overwritten in place) so the
-   * cache re-downloads.
-   */
-  overlay?: 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;
-  /**
-   * Low-volume diagnostics for the OPFS attach waterfall. This is intentionally
-   * phase-level rather than a logger so hosts can join it with their own route
-   * timings without parsing console text.
-   */
-  onTiming?: (info: OpfsAttachTiming) => void;
-  /**
-   * Serializer for the operations that mutate the DuckDB-WASM virtual
-   * filesystem / catalog (`registerFileHandle`, `dropFile`, `CREATE`/`DROP
-   * VIEW`) — those are not concurrency-safe across consumers sharing one
-   * `AsyncDuckDB`. Callers with a shared DB pass their global attach mutex
-   * here so ONLY these mutations serialize; the parquet downloads (network +
-   * OPFS writes, no DB interaction) run outside the lock and overlap across
-   * concurrent attaches. Wrapping the whole `attachOpfsParquetTables` call in
-   * the mutex instead serializes every table's downloads end-to-end — the
-   * dominant cold-load cost.
-   *
-   * The returned handle's `detach()` is NOT routed through this — callers
-   * that pass a lock typically already hold it around teardown, and the lock
-   * is not reentrant.
-   *
-   * Default: run inline (caller owns the DB exclusively).
-   */
-  withDb?: <T>(fn: () => Promise<T>) => Promise<T>;
-  /**
-   * Recover a table degraded by an OPFS sync-access-handle / write conflict
-   * (the multi-tab case — another tab holds the file's exclusive handle) by
-   * reading the already-cached bytes via the lock-free File API (or HTTP on a
-   * genuine cache miss) and registering them as in-memory buffers, so the table
-   * attaches from the shared cache instead of being pushed back to the caller.
-   * Quota / incomplete degradations are NEVER recovered this way — buffering a
-   * quota-exceeding set risks OOM, and the caller routes those to its tail.
-   * Default true.
-   */
-  recoverContention?: boolean;
-}
-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';
-  /** Time spent probing/downloading/writing this file before DuckDB registration. */
-  materialiseMs?: number;
-  /** Time spent inside DuckDB's file-registration mutation lock for this file. */
-  registerMs?: number;
-  /** 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 {
-  stage: OpfsAttachTimingStage;
-  durationMs: number;
-  table?: string;
-  file?: string;
-  files?: number;
-  tables?: number;
-  bytes?: number;
-  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[];
-  /**
-   * Why each degraded table degraded. 'quota' is actionable (the caller can
-   * reclaim space via `clearOpfsSnapshotCache` and retry once); 'contention'
-   * and 'incomplete' are transient multi-tab races the buffer fallback
-   * already absorbs.
-   */
-  degradeReasons: Partial<Record<string, 'quota' | 'contention' | 'incomplete'>>;
-  /** 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;
-}>;
-/**
- * Read a content-addressed OPFS snapshot file via the async File API and return
- * its bytes, or null when absent / size-mismatched (partial / stale write).
- *
- * `getFile()` takes NO lock — unlike DuckDB's `BROWSER_FSACCESS` sync access
- * handle — so it reads cleanly while ANOTHER tab holds the same file open. That
- * is the basis for cross-tab cache sharing: a tab that loses the exclusive-handle
- * race reads the shared cached bytes here instead of re-downloading. The
- * filename derivation is the SAME `opfsFileName` + `contentHashSlug` the attach
- * path writes, so consumers reuse the engine's naming with no replicated slug
- * 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>;
-/**
- * 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>;
-/**
- * Browser-side recent-overlay merge-on-read SQL — shared by the OPFS attach path
- * (`opfs.ts`) and the in-memory buffer attach path (consumers'
- * `registerParquetView`).
- *
- * The lake serves every day it has; the overlay serves ONLY days the lake lacks
- * (`date NOT IN (SELECT DISTINCT date FROM lake)`), unioned with
- * `UNION ALL BY NAME`. This is the browser sibling of the server's
- * `overlayMergeEnvelope` (in gscdump.com); kept SEPARATE because the browser path
- * can read the lake once via a `MATERIALIZED` CTE (CPU-bound DuckDB-WASM, bounded
- * per-site buffers) where the server's many-s3-file reads prefer projection
- * pushdown over a re-scan.
- *
- * Both `lakeSelect` / `overlaySelect` must already expose a `date` column cast to
- * DATE (the overlay stores ISO strings; `SELECT * REPLACE (CAST(date AS DATE) AS
- * date)`), so `UNION ALL BY NAME` merges them type-uniformly.
- */
-/**
- * The view BODY (no `CREATE VIEW` wrapper) merging a base lake relation and a
- * recent overlay. Returns null when neither side exists; the lake verbatim with
- * no overlay; the overlay verbatim with no lake (every recent row is wanted).
- *
- * `materializeLake` (default true): wrap the lake in a `MATERIALIZED` CTE so it is
- * scanned ONCE and reused for both the served rows and the anti-join date set — a
- * 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: {
-  lakeSelect: string | null;
-  overlaySelect: string | null;
-  materializeLake?: boolean;
-}): string | null;
-interface InsightRunnerOptions {
-  db: AsyncDuckDB;
-  conn: AsyncDuckDBConnection;
-  logger?: boolean;
-}
-interface InsightRunner {
-  db: DuckDBWasmDrizzleDatabase<Schema>;
-  client: Promise<DuckDBWasmClient>;
-  close: () => Promise<void>;
-}
-declare function createInsightRunner(opts: InsightRunnerOptions): Promise<InsightRunner>;
-/**
- * Build a per-table predicate set from {siteId, window}. The returned
- * `wherePredicates` composes with user-level filters via `mergeScope`.
- *
- * Note: the current SCHEMAS don't include `site_id` on any table (snapshots
- * are already per-site), so `siteId` is a no-op for now — kept in the API
- * so consumers can add the predicate without an interface change when
- * multi-site snapshots land.
- */
-declare const scopeFor: (table: "countries" | "dates" | "hourly_pages" | "page_queries" | "pages" | "queries" | "search_appearance" | "search_appearance_page_queries" | "search_appearance_pages" | "search_appearance_queries", opts: ScopedRunnerOptions) => TableScope, mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
-interface QueryResult {
-  rows: Record<string, unknown>[];
-  queryMs: number;
-}
-interface AnalyzeResult {
-  results: Record<string, unknown>[];
-  meta: Record<string, unknown>;
-  queryMs: number;
-}
-interface DuckDBWasmBootResult {
-  db: AsyncDuckDB;
-  conn: AsyncDuckDBConnection;
-}
-interface BootDuckDBWasmOptions {
-  /**
-   * DuckDB-WASM logger. Defaults to a `ConsoleLogger` thresholded at
-   * `LogLevel.WARNING`, so real warnings/errors still surface but the per-query
-   * INFO events (START/OK/RUN) — which DuckDB's default `ConsoleLogger()` emits
-   * as raw objects, flooding the host console with dozens of lines per render —
-   * are dropped. Pass `new ConsoleLogger(LogLevel.DEBUG)` to see everything, or
-   * `new VoidLogger()` to silence it entirely.
-   */
-  logger?: unknown;
-  /**
-   * Override the jsDelivr-hosted bundle map. Required in environments where
-   * the default CDN is unreachable or where hosts must serve the WASM +
-   * worker assets themselves (e.g. Cloudflare Workers' 25 MB per-asset cap).
-   */
-  bundles?: DuckDBBundles;
-  /**
-   * Extra DuckDB open config. The browser runtime always forces HTTP files
-   * into range-only mode (reliable HEAD probes, no full HTTP fallback) so a
-   * server that cannot answer bounded reads fails closed.
-   */
-  config?: DuckDBConfig;
-  /**
-   * Cap DuckDB's memory with `SET memory_limit=<value>` right after open (e.g.
-   * `'2GB'`, `'512MB'`). A runaway query then errors with a clean
-   * out-of-memory rather than growing the WASM heap until the tab crashes —
-   * DuckDB has no statement-level timeout, so abandoned queries are otherwise
-   * only stopped by the caller's `AbortSignal` (which the runtime forwards to
-   * `conn.cancelSent()`). Opt-in: omit to keep DuckDB-WASM's default sizing.
-   * Accepts `<number>` with an optional `B`/`KB`/`MB`/`GB`/`TB` suffix.
-   */
-  memoryLimit?: string;
-}
-interface BrowserParquetFile {
-  bytes: Uint8Array;
-  name?: string;
-}
-interface BrowserParquetTable {
-  table: string;
-  files: BrowserParquetFile[];
-}
-interface BrowserParquetUrlTable {
-  table: string;
-  urls: string[];
-}
-interface AttachParquetTablesOptions {
-  db: AsyncDuckDB;
-  conn: AsyncDuckDBConnection;
-  tables: BrowserParquetTable[];
-  schema?: string;
-}
-interface AttachParquetUrlTablesOptions {
-  db: AsyncDuckDB;
-  conn: AsyncDuckDBConnection;
-  tables: BrowserParquetUrlTable[];
-  fetch?: typeof fetch;
-  schema?: string;
-  /**
-   * Request init used only for runtime-owned HEAD / one-byte Range preflights.
-   * DuckDB-WASM's internal HTTP reader cannot receive custom fetch headers;
-   * URL reads must therefore be authorized by the URL itself.
-   */
-  fetchInit?: RequestInit;
-  /**
-   * Caps simultaneous URL preflights. Browser source endpoints should already
-   * return small, coverage-planned URL sets; this is the runtime's local
-   * guard against accidental unbounded attachment.
-   */
-  fetchConcurrency?: number;
-  /** Reject before preflight when the URL set exceeds this many parquet files. */
-  maxFiles?: number;
-  /** Reject before registration when hinted or authoritative bytes exceed budget. */
-  maxBytes?: number;
-  /** Abort signal passed through to URL preflights and registration. */
-  signal?: AbortSignal;
-  /**
-   * How DuckDB reads the parquet bytes:
-   *  - `'http'` (default): register the URL as an HTTP file; DuckDB issues
-   *    its own range reads during query execution. Right for large parquet
-   *    where only some column chunks are touched per query.
-   *  - `'buffer'`: fetch the full file once into an `ArrayBuffer` and register
-   *    it via `registerFileBuffer`. DuckDB makes zero HTTP calls after
-   *    registration — every query reads from the in-memory copy. Right for
-   *    tiny files (e.g. `dates` daily-totals parquet, <50 KB per file) where
-   *    the per-file round-trip overhead dominates the actual bytes moved.
-   */
-  attachMode?: 'http' | 'buffer';
-  /**
-   * When `true` (default), skip per-file HEAD/Range preflight if the URL
-   * carries a signed `?s=<bytes>.<sig>` size hint — the size is already
-   * known and DuckDB will learn `Accept-Ranges` from its first read.
-   * Eliminates one round-trip per file on hosts that mint size hints. Set
-   * `false` to force preflight against URLs whose size you don't trust.
-   */
-  trustSizeHint?: boolean;
-  /**
-   * Manifest version the caller associates with this set of URLs. Returned
-   * on the resulting handle so callers can compare against a fresh manifest
-   * probe without re-attaching. Purely advisory — the runtime never derives
-   * behavior from the value itself.
-   */
-  version?: number | string;
-  /**
-   * Called once per parquet file after it's been fetched and registered with
-   * DuckDB. For URL-backed HTTP files this means "preflighted and registered"
-   * rather than fully downloaded; DuckDB then performs range reads during the
-   * query. Fires in bounded-concurrency completion order, which is still not
-   * guaranteed to match manifest URL order. Used by UI progress indicators to
-   * tick a per-site counter; a no-op default keeps the hot path free.
-   */
-  onFileAttached?: (info: {
-    table: string;
-    index: number;
-    total: number;
-  }) => void;
-}
-/**
- * Handle returned from {@link attachParquetUrlTables}. Lets callers detach
- * the created views (for lazy re-attach on a new manifest version) or cheap-
- * check the embedded version against a fresh probe.
- */
-interface AttachedTablesHandle {
-  version: number | string | undefined;
-  tables: string[];
-  schema: string;
-  detach: () => Promise<void>;
-}
-interface BrowserAnalysisRuntime {
-  db: AsyncDuckDB;
-  conn: AsyncDuckDBConnection;
-  query: (sql: string, params?: unknown[], signal?: AbortSignal) => Promise<QueryResult>;
-  analyze: (params: AnalysisParams, registry: AnalyzerRegistry, options?: {
-    signal?: AbortSignal;
-  }) => Promise<AnalyzeResult>;
-  /**
-   * Returns true when `expected` doesn't match the version the runtime was
-   * attached with — cheap check callers can run before each query to decide
-   * whether to detach + re-attach against a fresher manifest. Undefined
-   * values on either side compare equal so the no-version path is a no-op.
-   */
-  isStale: (expected: number | string | undefined) => boolean;
-  /** Update the runtime's cached manifest version in-place (e.g. after a re-attach). */
-  setVersion: (version: number | string | undefined) => void;
-  /**
-   * 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 `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;
-  close: () => Promise<void>;
-}
-declare class BrowserAttachBudgetExceededError extends Error {
-  name: string;
-}
-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: {
-  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>;
-/**
- * Errors-as-values core for {@link attachParquetUrlTables}: returns a typed
- * {@link BrowserAttachError} when the requested file set blows the local file-
- * count / byte budget, so callers can branch (route the affected tables
- * server-side) instead of catching an untyped throw. WASM/DuckDB/HTTP IO
- * failures stay defects and propagate. `attachParquetUrlTables` is the thin
- * throwing wrapper preserving the historical `BrowserAttachBudgetExceededError`.
- */
-declare function attachParquetUrlTablesResult(options: AttachParquetUrlTablesOptions): Promise<Result<AttachedTablesHandle, BrowserAttachError>>;
-/**
- * Attach browser parquet URL tables, throwing
- * {@link BrowserAttachBudgetExceededError} when the requested set blows the
- * file-count / byte budget. Thin throwing wrapper over
- * {@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?: {
-  schema?: string;
-  version?: number | string;
-  attachedTables?: readonly string[];
-}): BrowserAnalysisRuntime;
 export { type AnalyzeResult, type AttachOpfsTablesOptions, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserAttachError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type CompiledArchetypeSql, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type OpfsAttachTiming, type OpfsAttachTimingStage, type OpfsAttachedHandle, type OpfsFileProgress, type OpfsParquetFile, type OpfsParquetTable, OpfsQuotaExceededError, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type TableScope, type WindowPreset, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, overlayViewBody, page_queries, pages, queries, readOpfsSnapshotFile, requestPersistentStorage, resolveWindow, schema, scopeFor, tableForArchetype };