@aztec/kv-store 0.0.1-commit.9ef841308 → 0.0.1-commit.a5db02d

package/src/sqlite-opfs/internal/ordered-binary-browser.js

@@ -0,0 +1,465 @@
+/* eslint-disable */
+/**
+ * Vendored from `ordered-binary@1.5.3/index.js` with one targeted edit:
+ * the `readString` definition (originally a dynamically-generated
+ * unrolled-loop function) is replaced with a hand-written interpreted
+ * equivalent that does the same work without code-generation-from-strings.
+ *
+ * Why vendor: upstream has no CSP-safe build, and the codegen is a
+ * module-init-time string-passed-to-evaluator that trips MV3 CSP
+ * (`script-src 'self' 'wasm-unsafe-eval'`). The codegen is a perf
+ * optimization on the string-decoding path only — the interpreted
+ * version is functionally identical, just slower per call.
+ *
+ * Parity with upstream is enforced by `ordered-binary-browser.test.ts`,
+ * which compares byte-exact output for a representative key set on every
+ * Node-mode test run. If `ordered-binary` is bumped, re-vendor by
+ * recopying upstream and reapplying the patch in the section marked
+ * `// CSP PATCH BEGIN` ... `// CSP PATCH END`.
+ */
+/*
+control character types:
+1 - metadata
+2 - symbols
+6 - false
+7 - true
+8- 16 - negative doubles
+16-24 positive doubles
+27 - String starts with a character 27 or less or is an empty string
+0 - multipart separator
+> 27 normal string characters
+*/
+/*
+ * Convert arbitrary scalar values to buffer bytes with type preservation and type-appropriate ordering
+ */
+
+const float64Array = new Float64Array(2);
+const int32Array = new Int32Array(float64Array.buffer, 0, 4);
+let nullTerminate = false;
+let textEncoder;
+try {
+  textEncoder = new TextEncoder();
+} catch (error) {}
+
+/*
+ * Convert arbitrary scalar values to buffer bytes with type preservation and type-appropriate ordering
+ */
+export function writeKey(key, target, position, inSequence) {
+  let targetView = target.dataView;
+  if (!targetView) {
+    targetView = target.dataView = new DataView(target.buffer, target.byteOffset, ((target.byteLength + 3) >> 2) << 2);
+  }
+  switch (typeof key) {
+    case 'string':
+      let strLength = key.length;
+      let c1 = key.charCodeAt(0);
+      if (!(c1 >= 28)) {
+        // escape character
+        target[position++] = 27;
+      }
+      if (strLength < 0x40) {
+        let i, c2;
+        for (i = 0; i < strLength; i++) {
+          c1 = key.charCodeAt(i);
+          if (c1 <= 4) {
+            target[position++] = 4;
+            target[position++] = c1;
+          } else if (c1 < 0x80) {
+            target[position++] = c1;
+          } else if (c1 < 0x800) {
+            target[position++] = (c1 >> 6) | 0xc0;
+            target[position++] = (c1 & 0x3f) | 0x80;
+          } else if ((c1 & 0xfc00) === 0xd800 && ((c2 = key.charCodeAt(i + 1)) & 0xfc00) === 0xdc00) {
+            c1 = 0x10000 + ((c1 & 0x03ff) << 10) + (c2 & 0x03ff);
+            i++;
+            target[position++] = (c1 >> 18) | 0xf0;
+            target[position++] = ((c1 >> 12) & 0x3f) | 0x80;
+            target[position++] = ((c1 >> 6) & 0x3f) | 0x80;
+            target[position++] = (c1 & 0x3f) | 0x80;
+          } else {
+            target[position++] = (c1 >> 12) | 0xe0;
+            target[position++] = ((c1 >> 6) & 0x3f) | 0x80;
+            target[position++] = (c1 & 0x3f) | 0x80;
+          }
+        }
+      } else {
+        if (target.utf8Write) {
+          position += target.utf8Write(key, position, target.byteLength - position);
+        } else {
+          position += textEncoder.encodeInto(key, target.subarray(position)).written;
+        }
+        if (position > target.length - 4) {
+          throw new RangeError('String does not fit in target buffer');
+        }
+      }
+      break;
+    case 'number':
+      float64Array[0] = key;
+      let lowInt = int32Array[0];
+      let highInt = int32Array[1];
+      let length;
+      if (key < 0) {
+        targetView.setInt32(position + 4, ~((lowInt >>> 4) | (highInt << 28)));
+        targetView.setInt32(position + 0, (highInt ^ 0x7fffffff) >>> 4);
+        targetView.setInt32(position + 8, ((lowInt & 0xf) ^ 0xf) << 4, true); // just always do the null termination here
+        return position + 9;
+      } else if (lowInt & 0xf || inSequence) {
+        length = 9;
+      } else if (lowInt & 0xfffff) {
+        length = 8;
+      } else if (lowInt || highInt & 0xf) {
+        length = 6;
+      } else {
+        length = 4;
+      }
+      // switching order to go to little endian
+      targetView.setInt32(position + 0, (highInt >>> 4) | 0x10000000);
+      targetView.setInt32(position + 4, (lowInt >>> 4) | (highInt << 28));
+      // if (length == 9 || nullTerminate)
+      targetView.setInt32(position + 8, (lowInt & 0xf) << 4, true);
+      return position + length;
+    case 'object':
+      if (key) {
+        if (Array.isArray(key)) {
+          for (let i = 0, l = key.length; i < l; i++) {
+            if (i > 0) {
+              target[position++] = 0;
+            }
+            position = writeKey(key[i], target, position, true);
+          }
+          break;
+        } else if (key instanceof Uint8Array) {
+          target.set(key, position);
+          position += key.length;
+          break;
+        } else {
+          throw new Error('Unable to serialize object as a key: ' + JSON.stringify(key));
+        }
+      } // null
+      else {
+        target[position++] = 0;
+      }
+      break;
+    case 'boolean':
+      targetView.setUint32(position++, key ? 7 : 6, true);
+      return position;
+    case 'bigint':
+      let asFloat = Number(key);
+      if (BigInt(asFloat) > key) {
+        float64Array[0] = asFloat;
+        if (asFloat > 0) {
+          if (int32Array[0]) {
+            int32Array[0]--;
+          } else {
+            int32Array[1]--;
+            int32Array[0] = 0xffffffff;
+          }
+        } else {
+          if (int32Array[0] < 0xffffffff) {
+            int32Array[0]++;
+          } else {
+            int32Array[1]++;
+            int32Array[0] = 0;
+          }
+        }
+        asFloat = float64Array[0];
+      }
+      let difference = key - BigInt(asFloat);
+      if (difference === 0n) {
+        return writeKey(asFloat, target, position, inSequence);
+      }
+      writeKey(asFloat, target, position, inSequence);
+      position += 9; // always increment by 9 if we are adding fractional bits
+      let exponent = BigInt(((int32Array[1] >> 20) & 0x7ff) - 1079);
+      let nextByte = difference >> exponent;
+      target[position - 1] |= Number(nextByte);
+      difference -= nextByte << exponent;
+      let first = true;
+      while (difference || first) {
+        first = false;
+        exponent -= 7n;
+        let nextByte = difference >> exponent;
+        target[position++] = Number(nextByte) | 0x80;
+        difference -= nextByte << exponent;
+      }
+      return position;
+    case 'undefined':
+      return position;
+    // undefined is interpreted as the absence of a key, signified by zero length
+    case 'symbol':
+      target[position++] = 2;
+      return writeKey(key.description, target, position, inSequence);
+    default:
+      throw new Error('Can not serialize key of type ' + typeof key);
+  }
+  if (nullTerminate && !inSequence) {
+    targetView.setUint32(position, 0);
+  }
+  return position;
+}
+
+let position;
+export function readKey(buffer, start, end, inSequence) {
+  position = start;
+  let controlByte = buffer[position];
+  let value;
+  if (controlByte < 24) {
+    if (controlByte < 8) {
+      position++;
+      if (controlByte == 6) {
+        value = false;
+      } else if (controlByte == 7) {
+        value = true;
+      } else if (controlByte == 0) {
+        value = null;
+      } else if (controlByte == 2) {
+        value = Symbol.for(readStringSafely(buffer, end));
+      } else {
+        return Uint8Array.prototype.slice.call(buffer, start, end);
+      }
+    } else {
+      let dataView;
+      try {
+        dataView =
+          buffer.dataView ||
+          (buffer.dataView = new DataView(buffer.buffer, buffer.byteOffset, ((buffer.byteLength + 3) >> 2) << 2));
+      } catch (error) {
+        // if it is write at the end of the ArrayBuffer, we may need to retry with the exact remaining bytes
+        dataView =
+          buffer.dataView ||
+          (buffer.dataView = new DataView(
+            buffer.buffer,
+            buffer.byteOffset,
+            buffer.buffer.byteLength - buffer.byteOffset,
+          ));
+      }
+
+      let highInt = dataView.getInt32(position) << 4;
+      let size = end - position;
+      let lowInt;
+      if (size > 4) {
+        lowInt = dataView.getInt32(position + 4);
+        highInt |= lowInt >>> 28;
+        if (size <= 6) {
+          // clear the last bits
+          lowInt &= -0x10000;
+        }
+        lowInt = lowInt << 4;
+        if (size > 8) {
+          lowInt = lowInt | (buffer[position + 8] >> 4);
+        }
+      } else {
+        lowInt = 0;
+      }
+      if (controlByte < 16) {
+        // negative gets negated
+        highInt = highInt ^ 0x7fffffff;
+        lowInt = ~lowInt;
+      }
+      int32Array[1] = highInt;
+      int32Array[0] = lowInt;
+      value = float64Array[0];
+      position += 9;
+      if (size > 9 && buffer[position] > 0) {
+        // convert the float to bigint, and then we will add precision as we enumerate through the
+        // extra bytes
+        value = BigInt(value);
+        let exponent = (highInt >> 20) & 0x7ff;
+        let next_byte = buffer[position - 1] & 0xf;
+        value += BigInt(next_byte) << BigInt(exponent - 1079);
+        while ((next_byte = buffer[position]) > 0 && position++ < end) {
+          value += BigInt(next_byte & 0x7f) << BigInt((start - position) * 7 + exponent - 1016);
+        }
+      }
+    }
+  } else {
+    if (controlByte == 27) {
+      position++;
+    }
+    value = readStringSafely(buffer, end);
+  }
+  while (position < end) {
+    if (buffer[position] === 0) {
+      position++;
+    }
+    if (inSequence) {
+      encoder.position = position;
+      return value;
+    }
+    let nextValue = readKey(buffer, position, end, true);
+    if (value instanceof Array) {
+      value.push(nextValue);
+    } else {
+      value = [value, nextValue];
+    }
+  }
+  return value;
+}
+export const enableNullTermination = () => (nullTerminate = true);
+
+export const encoder = {
+  writeKey,
+  readKey,
+  enableNullTermination,
+};
+let targetBuffer = [];
+let targetPosition = 0;
+const hasNodeBuffer = typeof Buffer !== 'undefined';
+const ByteArrayAllocate = hasNodeBuffer ? Buffer.allocUnsafeSlow : Uint8Array;
+export const toBufferKey = key => {
+  let newBuffer;
+  if (targetPosition + 100 > targetBuffer.length) {
+    targetBuffer = new ByteArrayAllocate(8192);
+    targetPosition = 0;
+    newBuffer = true;
+  }
+  try {
+    let result = targetBuffer.slice(targetPosition, (targetPosition = writeKey(key, targetBuffer, targetPosition)));
+    if (targetPosition > targetBuffer.length) {
+      if (newBuffer) {
+        throw new Error('Key is too large');
+      }
+      return toBufferKey(key);
+    }
+    return result;
+  } catch (error) {
+    if (newBuffer) {
+      throw error;
+    }
+    targetPosition = targetBuffer.length;
+    return toBufferKey(key);
+  }
+};
+export const fromBufferKey = sourceBuffer => {
+  return readKey(sourceBuffer, 0, sourceBuffer.length);
+};
+const fromCharCode = String.fromCharCode;
+
+let pendingSurrogate;
+function finishUtf8(byte1, src) {
+  if ((byte1 & 0xe0) === 0xc0) {
+    // 2 bytes
+    const byte2 = src[position++] & 0x3f;
+    return ((byte1 & 0x1f) << 6) | byte2;
+  } else if ((byte1 & 0xf0) === 0xe0) {
+    // 3 bytes
+    const byte2 = src[position++] & 0x3f;
+    const byte3 = src[position++] & 0x3f;
+    return ((byte1 & 0x1f) << 12) | (byte2 << 6) | byte3;
+  } else if ((byte1 & 0xf8) === 0xf0) {
+    // 4 bytes
+    if (pendingSurrogate) {
+      byte1 = pendingSurrogate;
+      pendingSurrogate = null;
+      position += 3;
+      return byte1;
+    }
+    const byte2 = src[position++] & 0x3f;
+    const byte3 = src[position++] & 0x3f;
+    const byte4 = src[position++] & 0x3f;
+    let unit = ((byte1 & 0x07) << 0x12) | (byte2 << 0x0c) | (byte3 << 0x06) | byte4;
+    if (unit > 0xffff) {
+      pendingSurrogate = 0xdc00 | (unit & 0x3ff);
+      unit = (((unit - 0x10000) >>> 10) & 0x3ff) | 0xd800;
+      position -= 4; // reset so we can return the next part of the surrogate pair
+    }
+    return unit;
+  } else {
+    return byte1;
+  }
+}
+
+// CSP PATCH BEGIN — replaces upstream's module-init dynamic-codegen with
+// an interpreted equivalent. The original `makeStringBuilder()` produces
+// a function string that unrolls 0x30 iterations of the loop below for
+// perf; this version does the same work as a real loop, slower per call
+// but CSP-safe (no module-init code generation from strings).
+const readString = (function makeReadString() {
+  function readStr(source) {
+    const codes = [];
+    while (codes.length < 0x30) {
+      let v = source[position++];
+      if (v > 4) {
+        if (v >= 0x80) {
+          v = finishUtf8(v, source);
+        }
+      } else if (v === 4) {
+        v = source[position++];
+      } else {
+        return fromCharCode.apply(null, codes);
+      }
+      codes.push(v);
+    }
+    return fromCharCode.apply(null, codes) + readStr(source);
+  }
+  return readStr;
+})();
+// CSP PATCH END
+
+function readStringSafely(source, end) {
+  if (source[end] > 0) {
+    let previous = source[end];
+    try {
+      // read string expects a null terminator, that is a 0 or undefined from reading past the end of the buffer, so we
+      // have to ensure that, but do so safely, restoring the buffer to its original state
+      source[end] = 0;
+      return readString(source);
+    } finally {
+      source[end] = previous;
+    }
+  } else {
+    return readString(source);
+  }
+}
+export function compareKeys(a, b) {
+  // compare with type consistency that matches binary comparison
+  if (typeof a == 'object') {
+    if (!a) {
+      return b == null ? 0 : -1;
+    }
+    if (a.compare) {
+      if (b == null) {
+        return 1;
+      } else if (b.compare) {
+        return a.compare(b);
+      } else {
+        return -1;
+      }
+    }
+    let arrayComparison;
+    if (b instanceof Array) {
+      let i = 0;
+      while ((arrayComparison = compareKeys(a[i], b[i])) == 0 && i <= a.length) {
+        i++;
+      }
+      return arrayComparison;
+    }
+    arrayComparison = compareKeys(a[0], b);
+    if (arrayComparison == 0 && a.length > 1) {
+      return 1;
+    }
+    return arrayComparison;
+  } else if (typeof a == typeof b) {
+    if (typeof a === 'symbol') {
+      a = Symbol.keyFor(a);
+      b = Symbol.keyFor(b);
+    }
+    return a < b ? -1 : a === b ? 0 : 1;
+  } else if (typeof b == 'object') {
+    if (b instanceof Array) {
+      return -compareKeys(b, a);
+    }
+    return 1;
+  } else {
+    return typeOrder[typeof a] < typeOrder[typeof b] ? -1 : 1;
+  }
+}
+const typeOrder = {
+  symbol: 0,
+  undefined: 1,
+  boolean: 2,
+  number: 3,
+  string: 4,
+};
+export const MINIMUM_KEY = null;
+export const MAXIMUM_KEY = new Uint8Array([0xff]);

package/src/sqlite-opfs/manage.ts

@@ -0,0 +1,36 @@
+/** Prefix for the per-store OPFS SAH pool directories owned by this package. */
+export const OPFS_POOL_DIR_PREFIX = '.aztec-kv-';
+
+/**
+ * OPFS directory holding a store's SAH pool. One directory per store: the SAH-pool VFS allows only one
+ * concurrent instance per directory and its capacity does not grow automatically, so sharing a pool across
+ * stores would make concurrently opened stores contend for locks and orphaned stores exhaust pool slots.
+ */
+export function storePoolDirectory(effectiveName: string): string {
+  return `${OPFS_POOL_DIR_PREFIX}${effectiveName}`;
+}
+
+/**
+ * Lists the names of every persistent sqlite-opfs store in this origin, by enumerating the per-store pool
+ * directories. Includes stores other than the current one, so wallets can surface and clean up data for
+ * networks/versions no longer in use.
+ */
+export async function listStores(): Promise<string[]> {
+  const root = await navigator.storage.getDirectory();
+  const names: string[] = [];
+  for await (const [entryName, handle] of root.entries()) {
+    if (handle.kind === 'directory' && entryName.startsWith(OPFS_POOL_DIR_PREFIX)) {
+      names.push(entryName.slice(OPFS_POOL_DIR_PREFIX.length));
+    }
+  }
+  return names;
+}
+
+/**
+ * Permanently deletes a store by effective name (as returned by {@link listStores}). The store must be closed:
+ * an open store's SAH pool holds locks on the directory and the removal will reject.
+ */
+export async function deleteStore(effectiveName: string): Promise<void> {
+  const root = await navigator.storage.getDirectory();
+  await root.removeEntry(storePoolDirectory(effectiveName), { recursive: true });
+}

package/src/sqlite-opfs/map.ts

@@ -0,0 +1,163 @@
+import { Encoder } from '#msgpackr';
+import { fromBufferKey, toBufferKey } from '#ordered-binary';
+import { Buffer } from 'buffer';
+import { hash } from 'ohash';
+
+import type { Key, Range, Value } from '../interfaces/common.js';
+import type { AztecAsyncMap } from '../interfaces/map.js';
+import type { SqlValue } from './messages.js';
+import type { AztecSQLiteOPFSStore } from './store.js';
+
+/** A map backed by SQLite in OPFS. Mirrors `IndexedDBAztecMap`. */
+export class SQLiteOPFSAztecMap<K extends Key, V extends Value> implements AztecAsyncMap<K, V> {
+  protected readonly name: string;
+  protected readonly container: string;
+  protected readonly encoder = new Encoder();
+
+  constructor(
+    protected readonly store: AztecSQLiteOPFSStore,
+    mapName: string,
+  ) {
+    this.name = mapName;
+    this.container = `map:${mapName}`;
+  }
+
+  async getAsync(key: K): Promise<V | undefined> {
+    const rows = await this.store.allAsync('SELECT value FROM data WHERE slot = ? LIMIT 1', [this.slot(key)]);
+    if (rows.length === 0) {
+      return undefined;
+    }
+    const raw = rows[0][0];
+    return raw == null ? undefined : this.decodeValue(raw);
+  }
+
+  async hasAsync(key: K): Promise<boolean> {
+    const rows = await this.store.allAsync('SELECT 1 FROM data WHERE slot = ? LIMIT 1', [this.slot(key)]);
+    return rows.length > 0;
+  }
+
+  async sizeAsync(): Promise<number> {
+    const rows = await this.store.allAsync('SELECT COUNT(*) FROM data WHERE container = ?', [this.container]);
+    return Number(rows[0]?.[0] ?? 0);
+  }
+
+  async set(key: K, val: V): Promise<void> {
+    await this.store.runAsync(
+      `INSERT OR REPLACE INTO data (slot, container, key, key_count, hash, value)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [this.slot(key), this.container, this.encodedKey(key), 1, hash(val), this.encoder.pack(val)],
+    );
+  }
+
+  async setMany(entries: { key: K; value: V }[]): Promise<void> {
+    if (entries.length === 0) {
+      return;
+    }
+    await this.store.transactionAsync(async () => {
+      for (const { key, value } of entries) {
+        await this.set(key, value);
+      }
+    });
+  }
+
+  swap(_key: K, _fn: (val: V | undefined) => V): Promise<void> {
+    throw new Error('Not implemented');
+  }
+
+  async setIfNotExists(key: K, val: V): Promise<boolean> {
+    return await this.store.transactionAsync(async () => {
+      if (await this.hasAsync(key)) {
+        return false;
+      }
+      await this.set(key, val);
+      return true;
+    });
+  }
+
+  async delete(key: K): Promise<void> {
+    await this.store.runAsync('DELETE FROM data WHERE slot = ?', [this.slot(key)]);
+  }
+
+  async *entriesAsync(range: Range<K> = {}): AsyncIterableIterator<[K, V]> {
+    const rows = await this.rangeQuery(range);
+    for (const row of rows) {
+      const [_slot, keyBlob, value] = row;
+      if (keyBlob == null || value == null) {
+        continue;
+      }
+      yield [this.decodeKey(keyBlob), this.decodeValue(value)];
+    }
+  }
+
+  async *valuesAsync(range: Range<K> = {}): AsyncIterableIterator<V> {
+    for await (const [, value] of this.entriesAsync(range)) {
+      yield value;
+    }
+  }
+
+  async *keysAsync(range: Range<K> = {}): AsyncIterableIterator<K> {
+    for await (const [key] of this.entriesAsync(range)) {
+      yield key;
+    }
+  }
+
+  protected async rangeQuery(range: Range<K>): Promise<Array<[string, Uint8Array, Uint8Array | null]>> {
+    // Inclusivity flips with direction to match the IndexedDB backend:
+    //   forward: [start, end)     reverse: (start, end]
+    // That asymmetry is load-bearing — tests pin the exact inclusivity at boundaries.
+    const reverse = !!range.reverse;
+    const parts: string[] = ['container = ?'];
+    const bind: SqlValue[] = [this.container];
+    if (range.start !== undefined) {
+      parts.push(reverse ? 'key > ?' : 'key >= ?');
+      bind.push(this.encodedKey(range.start));
+    }
+    if (range.end !== undefined) {
+      parts.push(reverse ? 'key <= ?' : 'key < ?');
+      bind.push(this.encodedKey(range.end));
+    }
+    const order = reverse ? 'DESC' : 'ASC';
+    let sql = `SELECT slot, key, value FROM data WHERE ${parts.join(' AND ')} ORDER BY key ${order}, key_count ${order}`;
+    if (range.limit !== undefined) {
+      sql += ' LIMIT ?';
+      bind.push(range.limit);
+    }
+    const rows = await this.store.allAsync(sql, bind);
+    return rows.map(r => [String(r[0]), r[1] as Uint8Array, r[2] as Uint8Array | null]);
+  }
+
+  protected decodeValue(val: SqlValue): V {
+    if (!(val instanceof Uint8Array)) {
+      return val as V;
+    }
+    const unpacked = this.encoder.unpack(val);
+    // msgpackr returns plain Uint8Array in browsers for packed Buffers. Callers that
+    // stored Buffers (walletDB uses Buffer.from(...).toString('utf8') round-trips)
+    // rely on Buffer-flavored behavior — re-wrap at the storage boundary, mirroring
+    // IndexedDBAztecMap.restoreBuffers.
+    if (unpacked instanceof Uint8Array && !Buffer.isBuffer(unpacked)) {
+      return Buffer.from(unpacked) as V;
+    }
+    return unpacked as V;
+  }
+
+  protected decodeKey(raw: Uint8Array): K {
+    const parsed = fromBufferKey(Buffer.from(raw));
+    if (Array.isArray(parsed)) {
+      return (parsed.length > 1 ? parsed : parsed[0]) as K;
+    }
+    return parsed as K;
+  }
+
+  protected encodedKey(key: K): Buffer {
+    return toBufferKey(this.normalizeKey(key));
+  }
+
+  protected normalizeKey(key: K): (string | number | Uint8Array)[] {
+    return Array.isArray(key) ? key : [key];
+  }
+
+  protected slot(key: K, index: number = 0): string {
+    return `map:${this.name}:slot:${this.normalizeKey(key)}:${index}`;
+  }
+}

package/src/sqlite-opfs/messages.ts

@@ -0,0 +1,39 @@
+/**
+ * RPC protocol between the main thread and the SQLite worker.
+ * All requests carry a unique `id`; responses echo the same id so the main thread
+ * can resolve the right pending promise.
+ */
+import type { SqliteEncryptionErrorCode } from './errors.js';
+
+/** Matches `@sqlite.org/sqlite-wasm`'s internal SqlValue type. Boolean is not a native SQLite type. */
+export type SqlValue = string | number | bigint | null | Uint8Array;
+
+/** A row returned in 'array' rowMode — one value per column, in select order. */
+export type ResultRow = SqlValue[];
+
+export type WorkerRequest =
+  | { type: 'init'; id: number; dbName: string; ephemeral: boolean; poolDirectory?: string; encryptionKey?: Uint8Array }
+  | { type: 'close'; id: number }
+  | { type: 'deleteDb'; id: number; dbName: string }
+  | { type: 'run'; id: number; sql: string; bind?: SqlValue[] }
+  | { type: 'all'; id: number; sql: string; bind?: SqlValue[] }
+  | { type: 'export'; id: number }
+  | { type: 'begin'; id: number }
+  | { type: 'commit'; id: number }
+  | { type: 'rollback'; id: number };
+
+export type WorkerResponse =
+  | { type: 'ok'; id: number; rows?: ResultRow[]; changes?: number; bytes?: Uint8Array }
+  | {
+      type: 'err';
+      id: number;
+      message: string;
+      /**
+       * Set when the worker detected an encryption-shaped failure. The main thread
+       * uses this to re-throw the error as a {@link SqliteEncryptionError} with the
+       * matching code. Absent on non-encryption failures (untyped paths preserved).
+       */
+      encryptionCode?: SqliteEncryptionErrorCode;
+    };
+
+export type WorkerRequestType = WorkerRequest['type'];