@reddb-io/browser 0.1.0-alpha.0 → 0.1.0

package/README.md

@@ -1,10 +1,10 @@
-# RedDB Browser — experimental persistence and query engine
+# RedDB Browser — persistence and query engine
 
-This experimental package is the first distribution of RedDB Browser. It runs the
-canonical Rust `.rdb` artifact publication/recovery code, RQL parser and shared
+The `@reddb-io/browser` package runs the canonical Rust `.rdb` artifact publication/recovery code, RQL parser and shared
 scalar evaluator in a dedicated WebAssembly worker, persisting through a real
 OPFS sync access handle.
-It requires a secure context, module workers, OPFS and Web Locks.
+Artifact storage requires a secure context, module workers, OPFS and Web Locks.
+The storage-independent runtime only needs module workers and WebAssembly.
 
 The target is a fully offline local database with a JavaScript/TypeScript API.
 The Rust/WASM engine ships with the package; local operation must not require a
@@ -14,7 +14,7 @@ application cache. Sync is optional and must never gate local reads or writes.
 
 **It is not a database SDK yet.** It executes storage-free scalar SELECTs;
 queries over stored data, five-model local transactions, synchronization,
-conflict resolution and forwarding between tabs remain pending. It is published on the `experimental` npm channel and does not replace the remote `@reddb-io/client`.
+conflict resolution and forwarding between tabs remain pending. It is published on the `latest` npm channel and does not replace the remote `@reddb-io/client`.
 
 ## Use from JS/TS
 
@@ -22,7 +22,7 @@ See the [application guide](https://github.com/reddb-io/reddb/blob/main/docs/cli
 Vite/React/Vue/Svelte, plain JavaScript, Worker ownership and offline assets.
 
 ```sh
-npm add @reddb-io/browser@experimental
+npm add @reddb-io/browser
 ```
 
 ```ts
@@ -40,6 +40,45 @@ try {
 Consumers receive built JS/Worker/WASM assets and TypeScript declarations; they
 need no Rust toolchain. The commands below are for engine/package contributors.
 
+## Shared runtime and language interop
+
+`createRuntime({ worker? })` opens no file and requires neither OPFS nor Web
+Locks. It exposes `info`, `validateQuery`, `executeScalar` and `close`:
+
+```ts
+import { createRuntime } from '@reddb-io/browser'
+import RedDBWorker from '@reddb-io/browser/worker?worker'
+const runtime = await createRuntime({ worker: new RedDBWorker() })
+try {
+  console.log(await runtime.info())
+  console.log(await runtime.executeScalar('SELECT 6 * 7 AS answer'))
+} finally { await runtime.close() }
+```
+
+The versioned Worker/WASM contract reports `abiVersion: 1`,
+`valueEncoding: 'reddb-json-v1'` and capabilities. Currently `queryValidation`
+and `scalarQueries` are true; `storedQueries`, `transactions` and `sync` are
+false. Mismatched SDK/Worker/WASM versions fail with `VERSION_MISMATCH` before
+opening storage. Cache the JS, Worker and WASM as one versioned unit.
+
+`createInteropRuntime({ worker? })` returns a synchronous bridge object with
+`invoke(method, params?)` and `close()`. `invoke` accepts `info`, `validateQuery`
+and `executeScalar` (queries take `{ sql }`) and resolves JSON-safe envelopes:
+`{ ok: true, result }` or `{ ok: false, error: { code, message } }`.
+A void result is `null`; exact integer/decimal tags are unchanged. `close()` is
+idempotent and cancels pending initialization/operations. Calls after close
+return `CLOSED`. Each bridge owns a dedicated Worker.
+
+Source adapters use this same bridge for
+[Dart/Flutter Web](https://github.com/reddb-io/reddb/blob/main/drivers/dart/BROWSER.md) and
+[C#/Blazor](https://github.com/reddb-io/reddb/blob/main/drivers/dotnet/src/Reddb.Browser/README.md). They are not yet
+published on pub.dev/NuGet. Their real compiled browser probes exercise scalar
+execution, exact values, errors and disposal online and offline. Full offline
+browser restarts are verified on Chromium/Firefox; Playwright WPE persistent
+profiles lack working CacheStorage, so Safari/iOS qualification remains pending. Run `pnpm --filter @reddb-io/browser build:interop` followed by
+`pnpm --filter @reddb-io/browser test:interop` with Dart 3.13.7 and .NET 8.0.426.
+These adapters do not expose artifact storage or qualify complete offline apps.
+
 ## Build and verify
 
 Install the repository-pinned Rust toolchain, its `wasm32-unknown-unknown` target,
@@ -145,7 +184,7 @@ these primitives do not promise that a browser will grant it or sync after closi
 ## Offline asset loading
 
 The SDK does not register a service worker or control application updates. A
-PWA should include `index.js`, `worker.js`, `wasm/reddb_wasm.js` and
+PWA should include `index.js`, `protocol.js`, `worker.js`, `wasm/reddb_wasm.js` and
 `wasm/reddb_wasm_bg.wasm` from `src/` in its own versioned application cache,
 along with its application shell. Those assets must remain available together
 after installation. A locally packaged host can serve the same assets locally.
@@ -245,6 +284,40 @@ artifact operations and storage-free scalar SELECTs; stored-data dispatch,
 durable runtime transactions/WAL and application collection catalogs remain
 unfinished. No file format, wire envelope or public browser API changes here.
 
+## Shared resident collection storage
+
+The growing/sealed segment, typed metadata, key/unique-key and physical graph
+candidate indexes, and resident payload accounting now live in
+`reddb-engine::storage`. Native paths re-export the same implementations. The
+native segment manager retains lifecycle, consolidation, explicit snapshot and
+moderation gates. Storage clocks use Unix seconds on both native and WASM hosts.
+Four shared conformance cases exercise all original record-oracle entity shapes,
+key-version lookup and raw mutation, bounded/cancelled scans, metadata and sealing;
+the browser worker repeats them after the existing offline restart.
+
+These are canonical resident storage operations, not durable application
+transactions. WAL publication, catalog dispatch and the application SDK still
+need integration before JS/TS can query and mutate persisted collections. The
+production artifact/scalar API and all file formats remain unchanged.
+
+## Shared snapshot recovery
+
+Native and WASM now use the same typed metadata/entity-record codecs and streaming
+V1–V12 dump reader. Recovery preserves empty collection registration, record
+metadata, cross-references and the optional V10+ catalog blob. The shared file
+layer verifies the checksum before any restore callback and lends the payload
+without copying the entire snapshot. Hosts must restore into private state and
+publish it only after successful recovery.
+
+Frozen pre-extraction native metadata bytes and entity fixtures check compatible
+encoding and decoding. Shared native/WASM cases also cover truncated metadata,
+invalid counts/tags/UTF-8, nesting at the RQL depth limit, checksum failures,
+legacy optional tails and host callback errors. Metadata nesting above the existing
+RQL JSON limit is now rejected; previously the native metadata reader was unbounded.
+The native host retains collection/index restoration, ID allocation and WAL policy.
+These internal recovery primitives do not yet expose stored-data queries or
+application transactions through the browser SDK.
+
 ## Remaining work toward the approved Browser design
 
 1. Extract the remaining storage-coupled executor/runtime into the shared portable engine and

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@reddb-io/browser",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
-  "description": "Experimental RedDB browser persistence and shared scalar execution; stored-data queries and sync remain pending.",
+  "description": "RedDB browser persistence and shared scalar execution; stored-data queries and sync remain pending.",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -14,9 +14,11 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "test": "node scripts/build-test.mjs && node --test test/browser.test.mjs",
+    "test": "node scripts/build-test.mjs && node --test test/runtime.test.mjs test/browser.test.mjs",
     "prepack": "node scripts/verify-dist.mjs",
-    "test:distribution": "node --test test/distribution.test.mjs"
+    "test:distribution": "node --test test/distribution.test.mjs",
+    "build:interop": "node scripts/build-interop.mjs",
+    "test:interop": "node --test test/interop.test.mjs"
   },
   "devDependencies": {
     "playwright": "1.61.1",
@@ -39,6 +41,6 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "experimental"
+    "tag": "latest"
   }
 }

package/scripts/verify-dist.mjs

@@ -3,7 +3,7 @@ import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const directory = resolve(dirname(fileURLToPath(import.meta.url)), '..')
-for (const path of ['src/index.js', 'src/index.d.ts', 'src/worker.js', 'src/wasm/reddb_wasm.js', 'LICENSE']) {
+for (const path of ['src/index.js', 'src/index.d.ts', 'src/protocol.js', 'src/worker.js', 'src/wasm/reddb_wasm.js', 'LICENSE']) {
   if (!readFileSync(resolve(directory, path)).length) throw new Error(`Missing browser distribution file: ${path}`)
 }
 const wasm = readFileSync(resolve(directory, 'src/wasm/reddb_wasm_bg.wasm'))

package/src/index.d.ts

@@ -1,14 +1,49 @@
-/** Experimental persistence and scalar execution; stored-data queries and sync remain pending. */
+/** Persistence and scalar execution; stored-data queries and sync remain pending. */
 export class BrowserError extends Error {
   readonly code: string
   constructor(code: string, message: string)
 }
 
-export interface Artifact {
+export interface RuntimeInfo {
+  readonly abiVersion: 1
+  readonly valueEncoding: 'reddb-json-v1'
+  readonly capabilities: {
+    readonly queryValidation: boolean
+    readonly scalarQueries: boolean
+    readonly storedQueries: boolean
+    readonly transactions: boolean
+    readonly sync: boolean
+  }
+}
+
+export interface Runtime {
+  /** Compiled engine capabilities; does not imply OPFS availability on this host. */
+  info(): Promise<RuntimeInfo>
   /** Parse with the canonical RQL front-end; does not execute the statement. */
   validateQuery(sql: string): Promise<void>
   /** Storage-free scalar SELECT only; does not read or mutate the artifact. */
   executeScalar(sql: string): Promise<{ columns: string[]; rows: unknown[][] }>
+  /** Terminate the storage-independent worker, rejecting pending operations. */
+  close(): Promise<void>
+}
+
+export type InteropResult =
+  | { ok: true; result: unknown }
+  | { ok: false; error: { code: string; message: string } }
+
+export interface RuntimeBridge {
+  /** info, validateQuery or executeScalar. Failures resolve as structured envelopes. */
+  invoke(method: string, params?: Record<string, unknown>): Promise<InteropResult>
+  /** Synchronous, idempotent cancellation, including during initialization. */
+  close(): void
+}
+
+/** No OPFS or Web Locks required; scalar execution only. */
+export function createRuntime(options?: { worker?: Worker }): Promise<Runtime>
+/** JSON-safe adapter boundary; does not expose artifact mutation or stored-data queries. */
+export function createInteropRuntime(options?: { worker?: Worker }): RuntimeBridge
+
+export interface Artifact extends Runtime {
   generation(): Promise<string>
   readWal(): Promise<Uint8Array[]>
   readSnapshot(): Promise<Uint8Array | undefined>
@@ -16,6 +51,7 @@ export interface Artifact {
   append(payloads: Uint8Array[]): Promise<void>
   /** Complete native store snapshot; the caller must fold in the committed WAL. */
   checkpoint(snapshot: Uint8Array, minWalBytes?: number): Promise<void>
+  /** Flush/close through the owner before terminating the worker. */
   close(): Promise<void>
 }
 

package/src/index.js

@@ -1,22 +1,9 @@
-/** Experimental artifact storage and storage-free scalar execution. */
-
-export class BrowserError extends Error {
-  constructor(code, message) {
-    super(message)
-    this.name = 'BrowserError'
-    this.code = code
-  }
-}
-
-/** Open an exclusively owned, canonical .rdb artifact in an OPFS worker. */
-export async function openArtifact({ name, worker: suppliedWorker } = {}) {
-  if (typeof name !== 'string' || !/^[a-zA-Z0-9_-][a-zA-Z0-9_.-]{0,79}$/.test(name)) {
-    throw new BrowserError('INVALID_NAME', 'Artifact names must contain 1–80 letters, digits, dots, underscores or hyphens')
-  }
-  if (!globalThis.isSecureContext || !globalThis.Worker || !globalThis.navigator?.storage?.getDirectory || !globalThis.navigator?.locks) {
-    throw new BrowserError('STORAGE_UNSUPPORTED', 'RedDB Browser requires HTTPS, module Workers, OPFS and Web Locks')
-  }
+/** Shared Rust/WASM runtime and artifact storage. */
+import { BrowserError, RUNTIME_ABI_VERSION, VALUE_ENCODING } from './protocol.js'
+export { BrowserError } from './protocol.js'
 
+function createClient(suppliedWorker) {
+  if (!globalThis.Worker) throw new BrowserError('RUNTIME_UNSUPPORTED', 'RedDB requires module Workers and WebAssembly')
   if (suppliedWorker !== undefined && !(suppliedWorker instanceof Worker)) {
     throw new BrowserError('INVALID_ARGUMENT', 'worker must be a dedicated Worker instance')
   }
@@ -24,56 +11,140 @@ export async function openArtifact({ name, worker: suppliedWorker } = {}) {
   const pending = new Map()
   let sequence = 0
   let closed = false
+  let terminated = false
 
-  function fail(error) {
+  function shutdown(error = new BrowserError('CLOSED', 'This runtime handle is closed')) {
     closed = true
     for (const request of pending.values()) request.reject(error)
     pending.clear()
-    worker.terminate()
+    if (!terminated) worker.terminate()
+    terminated = true
   }
 
   worker.onmessage = ({ data }) => {
+    if (terminated) return
+    if (data?.abiVersion !== RUNTIME_ABI_VERSION) {
+      shutdown(new BrowserError('VERSION_MISMATCH', 'Worker runtime ABI does not match this SDK'))
+      return
+    }
+    if (!Number.isSafeInteger(data.id) || data.id < 1) {
+      shutdown(new BrowserError('WORKER_FAILED', 'Invalid runtime response identifier'))
+      return
+    }
     const request = pending.get(data.id)
     if (!request) return
     pending.delete(data.id)
     if (data.error) request.reject(new BrowserError(data.error.code, data.error.message))
     else request.resolve(data.result)
   }
-  worker.onerror = (event) => fail(new BrowserError('WORKER_FAILED', event.message || 'RedDB storage worker failed'))
-  worker.onmessageerror = () => fail(new BrowserError('WORKER_FAILED', 'Unable to decode a storage worker response'))
+  worker.onerror = (event) => shutdown(new BrowserError('WORKER_FAILED', event.message || 'RedDB worker failed'))
+  worker.onmessageerror = () => shutdown(new BrowserError('WORKER_FAILED', 'Unable to decode a worker response'))
 
   function call(method, params = {}) {
-    if (closed) return Promise.reject(new BrowserError('CLOSED', 'This artifact handle is closed'))
+    if (closed) return Promise.reject(new BrowserError('CLOSED', 'This runtime handle is closed'))
     const id = ++sequence
     return new Promise((resolve, reject) => {
       pending.set(id, { resolve, reject })
-      try { worker.postMessage({ id, method, params }) }
+      try { worker.postMessage({ abiVersion: RUNTIME_ABI_VERSION, id, method, params }) }
       catch (error) { pending.delete(id); reject(error) }
     })
   }
 
-  try { await call('open', { name }) }
-  catch (error) { fail(error); throw error }
-
+  const ready = call('initialize').then(info => {
+    if (info?.abiVersion !== RUNTIME_ABI_VERSION || info.valueEncoding !== VALUE_ENCODING
+      || info.capabilities?.queryValidation !== true || info.capabilities?.scalarQueries !== true) {
+      throw new BrowserError('VERSION_MISMATCH', 'WASM runtime capabilities do not match this SDK')
+    }
+    return info
+  }).catch(error => { shutdown(error); throw error })
+  ready.catch(() => {}) // A bridge can be closed before its first invocation.
   let closing
   return {
-    validateQuery: (sql) => call('validateQuery', { sql }),
-    executeScalar: (sql) => call('executeScalar', { sql }),
-    generation: () => call('generation'),
-    readWal: () => call('readWal'),
-    readSnapshot: () => call('readSnapshot'),
-    append: (payloads) => call('append', { payloads }),
-    checkpoint: (snapshot, minWalBytes = 0) => call('checkpoint', { snapshot, minWalBytes }),
-    close() {
+    ready, call, shutdown,
+    closeFile() {
       if (!closing) {
-        closing = closed ? Promise.resolve() : call('close').finally(() => {
-          closed = true
-          worker.terminate()
-        })
-        // Reject calls issued after close(), including calls in the same turn.
+        closing = closed ? Promise.resolve() : call('close').finally(() => shutdown())
         closed = true
       }
       return closing
     },
   }
 }
+
+function runtimeMethods(client) {
+  const query = (method, sql) => typeof sql === 'string'
+    ? client.call(method, { sql })
+    : Promise.reject(new BrowserError('INVALID_ARGUMENT', 'Expected an RQL string'))
+  return {
+    info: () => client.call('info'),
+    validateQuery: sql => query('validateQuery', sql),
+    executeScalar: sql => query('executeScalar', sql),
+  }
+}
+
+/** Storage-independent Rust/WASM operations; does not open an OPFS file. */
+export async function createRuntime({ worker } = {}) {
+  const client = createClient(worker)
+  await client.ready
+  return { ...runtimeMethods(client), close() { client.shutdown(); return Promise.resolve() } }
+}
+
+/** JSON-safe boundary for Dart, .NET and other JS-interop hosts. */
+export function createInteropRuntime({ worker } = {}) {
+  let client
+  let ready
+  let closed = false
+  try {
+    client = createClient(worker)
+    ready = client.ready.then(() => runtimeMethods(client))
+  } catch (error) { ready = Promise.reject(error) }
+  ready.catch(() => {})
+  return {
+    async invoke(method, params = {}) {
+      try {
+        if (closed) throw new BrowserError('CLOSED', 'This runtime handle is closed')
+        const runtime = await ready
+        if (!params || typeof params !== 'object' || Array.isArray(params)) {
+          throw new BrowserError('INVALID_ARGUMENT', 'Expected an argument object')
+        }
+        let result
+        switch (method) {
+          case 'info': result = await runtime.info(); break
+          case 'validateQuery': result = await runtime.validateQuery(params.sql); break
+          case 'executeScalar': result = await runtime.executeScalar(params.sql); break
+          default: throw new BrowserError('INVALID_ARGUMENT', 'Unknown runtime operation')
+        }
+        return { ok: true, result: result ?? null }
+      } catch (error) {
+        return { ok: false, error: {
+          code: typeof error.code === 'string' ? error.code : 'RUNTIME_ERROR',
+          message: error.message || String(error),
+        } }
+      }
+    },
+    close() { closed = true; client?.shutdown() },
+  }
+}
+
+/** Open an exclusively owned, canonical .rdb artifact in an OPFS worker. */
+export async function openArtifact({ name, worker } = {}) {
+  if (typeof name !== 'string' || !/^[a-zA-Z0-9_-][a-zA-Z0-9_.-]{0,79}$/.test(name)) {
+    throw new BrowserError('INVALID_NAME', 'Artifact names must contain 1–80 letters, digits, dots, underscores or hyphens')
+  }
+  if (!globalThis.isSecureContext || !globalThis.Worker || !globalThis.navigator?.storage?.getDirectory || !globalThis.navigator?.locks) {
+    throw new BrowserError('STORAGE_UNSUPPORTED', 'RedDB Browser requires HTTPS, module Workers, OPFS and Web Locks')
+  }
+  const client = createClient(worker)
+  try { await client.ready; await client.call('open', { name }) }
+  catch (error) { client.shutdown(error); throw error }
+  const { call } = client
+  return {
+    ...runtimeMethods(client),
+    generation: () => call('generation'),
+    readWal: () => call('readWal'),
+    readSnapshot: () => call('readSnapshot'),
+    append: (payloads) => call('append', { payloads }),
+    checkpoint: (snapshot, minWalBytes = 0) => call('checkpoint', { snapshot, minWalBytes }),
+    close: client.closeFile,
+  }
+}

package/src/protocol.js

@@ -0,0 +1,10 @@
+export const RUNTIME_ABI_VERSION = 1
+export const VALUE_ENCODING = 'reddb-json-v1'
+
+export class BrowserError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'BrowserError'
+    this.code = code
+  }
+}

package/src/wasm/reddb_wasm.d.ts

@@ -26,6 +26,11 @@ export class BrowserArtifact {
  */
 export function executeScalar(sql: string): any;
 
+/**
+ * Contract shared by the JS worker and foreign-language browser adapters.
+ */
+export function runtimeInfo(): any;
+
 export function validateQuery(sql: string): void;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
@@ -41,6 +46,7 @@ export interface InitOutput {
     readonly browserartifact_readSnapshot: (a: number) => [number, number, number, number];
     readonly browserartifact_readWal: (a: number) => [number, number, number];
     readonly executeScalar: (a: number, b: number) => [number, number, number];
+    readonly runtimeInfo: () => [number, number, number];
     readonly validateQuery: (a: number, b: number) => [number, number];
     readonly rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
     readonly rust_zstd_wasm_shim_free: (a: number) => void;

package/src/wasm/reddb_wasm.js

@@ -136,6 +136,18 @@ export function executeScalar(sql) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Contract shared by the JS worker and foreign-language browser adapters.
+ * @returns {any}
+ */
+export function runtimeInfo() {
+    const ret = wasm.runtimeInfo();
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {string} sql
  */

package/src/wasm/reddb_wasm_bg.wasm.d.ts

@@ -10,6 +10,7 @@ export const browserartifact_open: (a: any, b: number, c: number) => [number, nu
 export const browserartifact_readSnapshot: (a: number) => [number, number, number, number];
 export const browserartifact_readWal: (a: number) => [number, number, number];
 export const executeScalar: (a: number, b: number) => [number, number, number];
+export const runtimeInfo: () => [number, number, number];
 export const validateQuery: (a: number, b: number) => [number, number];
 export const rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
 export const rust_zstd_wasm_shim_free: (a: number) => void;

package/src/worker.js

@@ -1,10 +1,26 @@
-import init, { BrowserArtifact, validateQuery, executeScalar } from './wasm/reddb_wasm.js'
+import init, * as wasm from './wasm/reddb_wasm.js'
+import { RUNTIME_ABI_VERSION, VALUE_ENCODING } from './protocol.js'
 
 let artifact
 let access
 let release
 let ownership
 let queue = Promise.resolve()
+let initialized
+
+function initialize() {
+  return initialized ??= (async () => {
+    await init()
+    if (typeof wasm.runtimeInfo !== 'function') throw error('VERSION_MISMATCH', 'WASM runtime metadata is missing')
+    let info
+    try { info = wasm.runtimeInfo() }
+    catch { throw error('VERSION_MISMATCH', 'WASM binary does not expose the expected runtime ABI') }
+    if (info.abiVersion !== RUNTIME_ABI_VERSION || info.valueEncoding !== VALUE_ENCODING) {
+      throw error('VERSION_MISMATCH', 'WASM runtime ABI does not match this worker')
+    }
+    return info
+  })()
+}
 
 function error(code, message) {
   return Object.assign(new Error(message), { code })
@@ -19,7 +35,7 @@ function synchronous(value) {
 }
 
 async function open(name) {
-  await init()
+  await initialize()
   await new Promise((resolve, reject) => {
     ownership = navigator.locks.request(`reddb-browser:${name}`, { ifAvailable: true }, async (lock) => {
       if (!lock) throw error('FILE_BUSY', 'This artifact is already open in another worker or tab')
@@ -39,8 +55,8 @@ async function open(name) {
           flush: () => synchronous(access.flush()),
         }
         artifact = fileIo.getSize() === 0
-          ? BrowserArtifact.create(fileIo, name, Date.now())
-          : BrowserArtifact.open(fileIo, name)
+          ? wasm.BrowserArtifact.create(fileIo, name, Date.now())
+          : wasm.BrowserArtifact.open(fileIo, name)
         const lifetime = new Promise((resolveRelease) => { release = resolveRelease })
         resolve()
         await lifetime
@@ -65,15 +81,15 @@ function bytes(value) {
 }
 
 async function execute(method, params) {
+  if (method === 'initialize' || method === 'info') return initialize()
   if (method === 'open') return open(params.name)
+  if (method === 'validateQuery' || method === 'executeScalar') {
+    await initialize()
+    if (typeof params.sql !== 'string') throw error('INVALID_ARGUMENT', 'Expected an RQL string')
+    return method === 'validateQuery' ? wasm.validateQuery(params.sql) : wasm.executeScalar(params.sql)
+  }
   if (!artifact) throw error('CLOSED', 'The artifact is not open')
   switch (method) {
-    case 'validateQuery':
-      if (typeof params.sql !== 'string') throw error('INVALID_ARGUMENT', 'Expected an RQL string')
-      return validateQuery(params.sql)
-    case 'executeScalar':
-      if (typeof params.sql !== 'string') throw error('INVALID_ARGUMENT', 'Expected an RQL string')
-      return executeScalar(params.sql)
     case 'generation': return artifact.generation()
     case 'readWal': return artifact.readWal()
     case 'readSnapshot': return artifact.readSnapshot()
@@ -93,14 +109,19 @@ async function execute(method, params) {
   }
 }
 
-self.onmessage = ({ data: { id, method, params } }) => {
+self.onmessage = ({ data }) => {
+  const { id, method, params = {} } = data ?? {}
+  if (data?.abiVersion !== RUNTIME_ABI_VERSION) {
+    self.postMessage({ abiVersion: RUNTIME_ABI_VERSION, id, error: { code: 'VERSION_MISMATCH', message: 'SDK runtime ABI does not match this worker' } })
+    return
+  }
   // Opening is asynchronous; all following operations wait for ownership.
   queue = queue.then(async () => {
     try {
       const result = await execute(method, params)
-      self.postMessage({ id, result })
+      self.postMessage({ abiVersion: RUNTIME_ABI_VERSION, id, result })
     } catch (failure) {
-      self.postMessage({ id, error: { code: failure.code || 'ARTIFACT_ERROR', message: failure.message || String(failure) } })
+      self.postMessage({ abiVersion: RUNTIME_ABI_VERSION, id, error: { code: failure.code || 'ARTIFACT_ERROR', message: failure.message || String(failure) } })
     }
   })
 }