@loradb/lora-wasm 0.5.6 → 0.8.0

package/pkg-bundler/lora_wasm.d.ts

@@ -21,23 +21,35 @@ export class WasmDatabase {
    * transaction. Returns an array of query results in statement order.
    */
   transaction(statements: any, mode?: string | null): any;
-  relationshipCount(): number;
   /**
-   * Serialize the graph into a byte buffer. The caller is responsible for
-   * writing it to disk, IndexedDB, localStorage, or wherever — WASM does
-   * not have direct filesystem access. The returned bytes can later be
-   * passed to `loadSnapshotFromBytes` on any `WasmDatabase` instance.
+   * Replace the graph state with a database snapshot decoded from `bytes`.
+   * Legacy store snapshot bytes are accepted for compatibility.
+   *
+   * Returns a plain object matching the shape of `SnapshotMeta`:
+   * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
+   */
+  loadSnapshot(bytes: Uint8Array, options: any): any;
+  /**
+   * Serialize the graph into database snapshot bytes. The caller is
+   * responsible for writing them to IndexedDB, localStorage, a server, or
+   * another host-provided store — WASM has no direct filesystem access.
+   * The returned bytes can later be passed to `loadSnapshot` on any
+   * `WasmDatabase` instance.
    *
    * Returns the serialized bytes as a `Uint8Array`.
    */
-  saveSnapshotToBytes(): Uint8Array;
+  saveSnapshot(options: any): Uint8Array;
   /**
-   * Replace the graph state with a snapshot decoded from `bytes`.
+   * Execute a Lora query and return the result as a binary buffer.
    *
-   * Returns a plain object matching the shape of `SnapshotMeta`:
-   * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
+   * Wire format is the shared `lora_binding_buffer` layout. The TS
+   * wrapper decodes it once into the same `{ columns, rows }` shape
+   * `execute()` returns, but in a tight V8 loop instead of going
+   * through `serde_wasm_bindgen` value-by-value. Materially faster
+   * on bulk reads.
    */
-  loadSnapshotFromBytes(bytes: Uint8Array): any;
+  executeBuffer(query: string, params: any): Uint8Array;
+  relationshipCount(): number;
   constructor();
   clear(): void;
   /**
@@ -48,6 +60,21 @@ export class WasmDatabase {
    * as a plain JS object (structured-clonable).
    */
   execute(query: string, params: any): any;
+  /**
+   * Compile a query and return its plan without executing it.
+   *
+   * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+   * the graph untouched — this method never runs the executor.
+   */
+  explain(query: string, params: any): any;
+  /**
+   * Execute a query and return the plan plus runtime metrics.
+   *
+   * **PROFILE executes the query for real.** Mutating queries are
+   * persisted exactly as in `execute()`. Use `explain()` to inspect
+   * a mutating plan without running it.
+   */
+  profile(query: string, params: any): any;
 }
 export class WasmQueryStream {
   private constructor();

package/pkg-bundler/lora_wasm_bg.js

@@ -181,17 +181,17 @@ function takeFromExternrefTable0(idx) {
     return value;
 }
 
-function getArrayU8FromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
-}
-
 function passArray8ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 1, 1) >>> 0;
     getUint8ArrayMemory0().set(arg, ptr / 1);
     WASM_VECTOR_LEN = arg.length;
     return ptr;
 }
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
 /**
  * Call once at module start to install a panic hook that routes Rust
  * panics to `console.error`. No-op if compiled without the default feature.
@@ -259,23 +259,37 @@ export class WasmDatabase {
         return takeFromExternrefTable0(ret[0]);
     }
     /**
-     * @returns {number}
+     * Replace the graph state with a database snapshot decoded from `bytes`.
+     * Legacy store snapshot bytes are accepted for compatibility.
+     *
+     * Returns a plain object matching the shape of `SnapshotMeta`:
+     * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
+     * @param {Uint8Array} bytes
+     * @param {any} options
+     * @returns {any}
      */
-    relationshipCount() {
-        const ret = wasm.wasmdatabase_relationshipCount(this.__wbg_ptr);
-        return ret >>> 0;
+    loadSnapshot(bytes, options) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_loadSnapshot(this.__wbg_ptr, ptr0, len0, options);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
     }
     /**
-     * Serialize the graph into a byte buffer. The caller is responsible for
-     * writing it to disk, IndexedDB, localStorage, or wherever — WASM does
-     * not have direct filesystem access. The returned bytes can later be
-     * passed to `loadSnapshotFromBytes` on any `WasmDatabase` instance.
+     * Serialize the graph into database snapshot bytes. The caller is
+     * responsible for writing them to IndexedDB, localStorage, a server, or
+     * another host-provided store — WASM has no direct filesystem access.
+     * The returned bytes can later be passed to `loadSnapshot` on any
+     * `WasmDatabase` instance.
      *
      * Returns the serialized bytes as a `Uint8Array`.
+     * @param {any} options
      * @returns {Uint8Array}
      */
-    saveSnapshotToBytes() {
-        const ret = wasm.wasmdatabase_saveSnapshotToBytes(this.__wbg_ptr);
+    saveSnapshot(options) {
+        const ret = wasm.wasmdatabase_saveSnapshot(this.__wbg_ptr, options);
         if (ret[3]) {
             throw takeFromExternrefTable0(ret[2]);
         }
@@ -284,21 +298,34 @@ export class WasmDatabase {
         return v1;
     }
     /**
-     * Replace the graph state with a snapshot decoded from `bytes`.
+     * Execute a Lora query and return the result as a binary buffer.
      *
-     * Returns a plain object matching the shape of `SnapshotMeta`:
-     * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
-     * @param {Uint8Array} bytes
-     * @returns {any}
+     * Wire format is the shared `lora_binding_buffer` layout. The TS
+     * wrapper decodes it once into the same `{ columns, rows }` shape
+     * `execute()` returns, but in a tight V8 loop instead of going
+     * through `serde_wasm_bindgen` value-by-value. Materially faster
+     * on bulk reads.
+     * @param {string} query
+     * @param {any} params
+     * @returns {Uint8Array}
      */
-    loadSnapshotFromBytes(bytes) {
-        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+    executeBuffer(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.wasmdatabase_loadSnapshotFromBytes(this.__wbg_ptr, ptr0, len0);
-        if (ret[2]) {
-            throw takeFromExternrefTable0(ret[1]);
+        const ret = wasm.wasmdatabase_executeBuffer(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
         }
-        return takeFromExternrefTable0(ret[0]);
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
+    /**
+     * @returns {number}
+     */
+    relationshipCount() {
+        const ret = wasm.wasmdatabase_relationshipCount(this.__wbg_ptr);
+        return ret >>> 0;
     }
     constructor() {
         const ret = wasm.wasmdatabase_new();
@@ -328,6 +355,43 @@ export class WasmDatabase {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * Compile a query and return its plan without executing it.
+     *
+     * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+     * the graph untouched — this method never runs the executor.
+     * @param {string} query
+     * @param {any} params
+     * @returns {any}
+     */
+    explain(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_explain(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * Execute a query and return the plan plus runtime metrics.
+     *
+     * **PROFILE executes the query for real.** Mutating queries are
+     * persisted exactly as in `execute()`. Use `explain()` to inspect
+     * a mutating plan without running it.
+     * @param {string} query
+     * @param {any} params
+     * @returns {any}
+     */
+    profile(query, params) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmdatabase_profile(this.__wbg_ptr, ptr0, len0, params);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
 }
 
 const WasmQueryStreamFinalization = (typeof FinalizationRegistry === 'undefined')
@@ -398,6 +462,16 @@ export function __wbg_call_672a4d21634d4a24() { return handleError(function (arg
     return ret;
 }, arguments) };
 
+export function __wbg_call_7cccdd69e0791ae2() { return handleError(function (arg0, arg1, arg2) {
+    const ret = arg0.call(arg1, arg2);
+    return ret;
+}, arguments) };
+
+export function __wbg_crypto_86f2631e91b51511(arg0) {
+    const ret = arg0.crypto;
+    return ret;
+};
+
 export function __wbg_done_769e5ede4b31c67b(arg0) {
     const ret = arg0.done;
     return ret;
@@ -420,6 +494,10 @@ export function __wbg_error_7534b8e9a36f1ab4(arg0, arg1) {
     }
 };
 
+export function __wbg_getRandomValues_b3f15fcbfabb0f8b() { return handleError(function (arg0, arg1) {
+    arg0.getRandomValues(arg1);
+}, arguments) };
+
 export function __wbg_get_67b2ba62fc30de12() { return handleError(function (arg0, arg1) {
     const ret = Reflect.get(arg0, arg1);
     return ret;
@@ -488,6 +566,11 @@ export function __wbg_length_e2d2a49132c1b256(arg0) {
     return ret;
 };
 
+export function __wbg_msCrypto_d562bbe83e0d4b91(arg0) {
+    const ret = arg0.msCrypto;
+    return ret;
+};
+
 export function __wbg_new_405e22f390576ce2() {
     const ret = new Object();
     return ret;
@@ -513,6 +596,21 @@ export function __wbg_new_a12002a7f91c75be(arg0) {
     return ret;
 };
 
+export function __wbg_newnoargs_105ed471475aaf50(arg0, arg1) {
+    const ret = new Function(getStringFromWasm0(arg0, arg1));
+    return ret;
+};
+
+export function __wbg_newwithbyteoffsetandlength_d97e637ebe145a9a(arg0, arg1, arg2) {
+    const ret = new Uint8Array(arg0, arg1 >>> 0, arg2 >>> 0);
+    return ret;
+};
+
+export function __wbg_newwithlength_a381634e90c276d4(arg0) {
+    const ret = new Uint8Array(arg0 >>> 0);
+    return ret;
+};
+
 export function __wbg_next_25feadfc0913fea9(arg0) {
     const ret = arg0.next;
     return ret;
@@ -523,11 +621,30 @@ export function __wbg_next_6574e1a8a62d1055() { return handleError(function (arg
     return ret;
 }, arguments) };
 
+export function __wbg_node_e1f24f89a7336c2e(arg0) {
+    const ret = arg0.node;
+    return ret;
+};
+
 export function __wbg_now_807e54c39636c349() {
     const ret = Date.now();
     return ret;
 };
 
+export function __wbg_process_3975fd6c72f520aa(arg0) {
+    const ret = arg0.process;
+    return ret;
+};
+
+export function __wbg_randomFillSync_f8c153b79f285817() { return handleError(function (arg0, arg1) {
+    arg0.randomFillSync(arg1);
+}, arguments) };
+
+export function __wbg_require_b74f47fc2d022fd6() { return handleError(function () {
+    const ret = module.require;
+    return ret;
+}, arguments) };
+
 export function __wbg_set_37837023f3d740e8(arg0, arg1, arg2) {
     arg0[arg1 >>> 0] = arg2;
 };
@@ -553,11 +670,41 @@ export function __wbg_stack_0ed75d68575b0f3c(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 };
 
+export function __wbg_static_accessor_GLOBAL_88a902d13a557d07() {
+    const ret = typeof global === 'undefined' ? null : global;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+};
+
+export function __wbg_static_accessor_GLOBAL_THIS_56578be7e9f832b0() {
+    const ret = typeof globalThis === 'undefined' ? null : globalThis;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+};
+
+export function __wbg_static_accessor_SELF_37c5d418e4bf5819() {
+    const ret = typeof self === 'undefined' ? null : self;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+};
+
+export function __wbg_static_accessor_WINDOW_5de37043a91a9c40() {
+    const ret = typeof window === 'undefined' ? null : window;
+    return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+};
+
+export function __wbg_subarray_aa9065fa9dc5df96(arg0, arg1, arg2) {
+    const ret = arg0.subarray(arg1 >>> 0, arg2 >>> 0);
+    return ret;
+};
+
 export function __wbg_value_cd1ffa7b1ab794f1(arg0) {
     const ret = arg0.value;
     return ret;
 };
 
+export function __wbg_versions_4e31226f5e8dc909(arg0) {
+    const ret = arg0.versions;
+    return ret;
+};
+
 export function __wbindgen_bigint_from_i64(arg0) {
     const ret = arg0;
     return ret;

package/pkg-bundler/lora_wasm_bg.wasm.d.ts

@@ -5,12 +5,15 @@ export const __wbg_wasmdatabase_free: (a: number, b: number) => void;
 export const __wbg_wasmquerystream_free: (a: number, b: number) => void;
 export const wasmdatabase_clear: (a: number) => void;
 export const wasmdatabase_execute: (a: number, b: number, c: number, d: any) => [number, number, number];
-export const wasmdatabase_loadSnapshotFromBytes: (a: number, b: number, c: number) => [number, number, number];
+export const wasmdatabase_executeBuffer: (a: number, b: number, c: number, d: any) => [number, number, number, number];
+export const wasmdatabase_explain: (a: number, b: number, c: number, d: any) => [number, number, number];
+export const wasmdatabase_loadSnapshot: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_new: () => number;
 export const wasmdatabase_nodeCount: (a: number) => number;
 export const wasmdatabase_openStream: (a: number, b: number, c: number, d: any) => [number, number, number];
+export const wasmdatabase_profile: (a: number, b: number, c: number, d: any) => [number, number, number];
 export const wasmdatabase_relationshipCount: (a: number) => number;
-export const wasmdatabase_saveSnapshotToBytes: (a: number) => [number, number, number, number];
+export const wasmdatabase_saveSnapshot: (a: number, b: any) => [number, number, number, number];
 export const wasmdatabase_transaction: (a: number, b: any, c: number, d: number) => [number, number, number];
 export const wasmquerystream_close: (a: number) => void;
 export const wasmquerystream_columns: (a: number) => [number, number, number];

package/pkg-bundler/package.json

@@ -5,7 +5,7 @@
     "LoraDB, Inc."
   ],
   "description": "WebAssembly bindings for the Lora in-memory graph database",
-  "version": "0.5.6",
+  "version": "0.8.0",
   "license": "BUSL-1.1",
   "files": [
     "lora_wasm_bg.wasm",

package/pkg-node/README.md

@@ -1,17 +1,17 @@
 # lora-wasm
 
-WebAssembly bindings for the [Lora](../../README.md) in-memory graph
+WebAssembly bindings for the [Lora](../../../README.md) in-memory graph
 database. The package is designed for browsers and Node.js and exposes a
 **strongly typed, async-facing API** that keeps the main thread responsive:
 heavy query work can run inside a Web Worker while your UI code simply awaits
 the result.
 
-> **Status:** prototype / feasibility check. Not published to npm.
+> **Package:** `@loradb/lora-wasm`.
 
 ## Build
 
 ```bash
-cd crates/lora-wasm
+cd crates/bindings/lora-wasm
 npm install
 npm run build              # wasm-pack (node + bundler) + tsc
 npm test                   # vitest
@@ -52,7 +52,7 @@ fails during startup, the package emits one `console.warn` and falls back to
 the in-process WASM engine so the app can still run.
 
 ```ts
-import { createDatabase, isNode } from "lora-wasm";
+import { createDatabase, isNode } from "@loradb/lora-wasm";
 
 const db = await createDatabase(); // Worker-backed in browsers when possible
 await db.execute("CREATE (:Person {name: $n})", { n: "Alice" });
@@ -63,6 +63,37 @@ for (const row of r.rows) {
 }
 ```
 
+### Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally *separate calls*, not a flag
+on `execute()`, so plan inspection and runtime metrics must be
+requested explicitly.
+
+```ts
+const plan = await db.explain(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { name: "Alice" },
+);
+console.log(plan.shape);          // "readOnly"
+console.log(plan.tree.operator);
+
+const profile = await db.profile(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { name: "Alice" },
+);
+console.log(profile.metrics.totalElapsedNs);
+console.log(profile.metrics.perOperator); // per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 To force the in-process engine:
 
 ```ts
@@ -84,7 +115,7 @@ const db = await createDatabase({ warnOnFallback: false });
 ### 2. Explicit main-thread WASM
 
 ```ts
-import { createMainThreadDatabase } from "lora-wasm";
+import { createMainThreadDatabase } from "@loradb/lora-wasm";
 
 const db = await createMainThreadDatabase();
 ```
@@ -116,35 +147,36 @@ useful for tests and for swapping execution backends behind the same API.
 
 ## Snapshots
 
-WASM has no filesystem access, so `saveSnapshot()` defaults to a `Uint8Array`.
-It also accepts typed formats: `"base64"` returns base64 text, `"blob"` returns
-a `Blob`, and `"download"` triggers a browser download from the main thread.
-
-`loadSnapshot` accepts a `WasmSnapshotSource`: `Uint8Array`, `ArrayBuffer`,
-`Blob`/`File`, `Response`, web `ReadableStream`, string URL, or `URL`. It does
-not include Node `Buffer`; use `Uint8Array` bytes when running the WASM package
-from Node.
+WASM has no filesystem access, so snapshots never accept string paths.
+`saveSnapshot()` defaults to `Uint8Array`, and can also return `ArrayBuffer`,
+`Blob`, `Response`, `ReadableStream`, or an object `URL`. `loadSnapshot`
+accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, and web
+`ReadableStream<Uint8Array | ArrayBuffer>`. The bytes use the database
+snapshot codec (`LORACOL1`) and can be loaded by native LoraDB. Older store
+snapshots use the current `LORACOL1` columnar format.
+Snapshot bytes are uncompressed by default; pass `{ compression: "gzip" }` or
+`{ compression: { format: "gzip", level: 1 } }` to save smaller
+WASM-portable snapshots. Gzip levels `0..9` are supported; level `1` is the
+fast default.
 
 ```ts
-import { createDatabase } from "lora-wasm";
+import { createDatabase } from "@loradb/lora-wasm";
 
 const db = await createDatabase();
 await db.execute("CREATE (:Person {name: 'Alice'})");
 
-const bytes = await db.saveSnapshotToBytes();
-const sameBytes = await db.saveSnapshot("binary");
-const blob = await db.saveSnapshot({ format: "blob" });
-await db.saveSnapshot({ format: "download", filename: "graph.lorasnap" });
+const bytes = await db.saveSnapshot();
+const compressed = await db.saveSnapshot({ compression: "gzip" });
+const blob = await db.saveSnapshot({ format: "blob", compression: "gzip" });
+const response = await db.saveSnapshot({ format: "response" });
 
 await db.loadSnapshot(bytes);
+await db.loadSnapshot(compressed);
 await db.loadSnapshot(blob);
-await db.loadSnapshot(new Response(bytes).body!);
+await db.loadSnapshot(response);
 await db.loadSnapshot(new URL("/graph.lorasnap", location.href));
 ```
 
-`loadSnapshotFromBytes(bytes)` remains available for the narrow
-`Uint8Array`-only path.
-
 ## Typed value model
 
 | TS type                              | Runtime shape                                                               |
@@ -171,31 +203,42 @@ Helper constructors: `date`, `time`, `datetime`, `localtime`, `localdatetime`,
 `isNode`, `isRelationship`, `isPath`, `isPoint`, `isTemporal`.
 
 > `distance()` on WGS-84-3D points ignores `height`. See
-> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the spatial
+> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the spatial
 > reference and out-of-scope operations.
 
 ## Errors
 
-`db.execute(...)` and the worker client throw `LoraError` with a narrowed
-`code`:
+`db.execute(...)` and the worker client throw `LoraError` with a
+narrowed `code` from the `LoraErrorCode` union — these mirror
+`lora_database::LoraErrorCode` 1:1, plus `WORKER_ERROR` and `UNKNOWN`.
 
-- `LORA_ERROR` — parse / analyze / execute failure
-- `INVALID_PARAMS` — a param value could not be mapped to a Lora value
+Common ones:
+
+- `LORA_PARSE` — Cypher syntax could not be parsed
+- `LORA_SEMANTIC` — analysis failure (unknown variable, label, type mismatch, …)
+- `LORA_INVALID_PARAMS` — a parameter value could not be coerced to a `LoraValue`
+- `LORA_INVALID_VECTOR` — vector value failed dimension / coordinate-type validation
+- `LORA_TIMEOUT` — query exceeded its cooperative deadline
+- `LORA_IO`, `LORA_SNAPSHOT_CODEC`, `LORA_SNAPSHOT_CRYPTO` — storage / snapshot failures
+- `LORA_INTERNAL` — last-resort fallback when the engine cannot classify the failure
 - `WORKER_ERROR` — worker transport / lifecycle failure (worker client only)
 
+See `ts/types.ts` (`LoraErrorCode`) for the full list.
+
 ## Shared type contract
 
 The public TypeScript value model (`LoraValue`, `LoraNode`, …,
 `QueryResult`, `LoraError`) lives in a single canonical file at
-`crates/shared-ts/types.ts` and is copied into each consumer package by
+`crates/bindings/shared-ts/types.ts` and is copied into each consumer package by
 its `sync:types` npm script. CI runs `verify:types` to fail on drift.
 That keeps `lora-node` and `lora-wasm` locked to one identical
 public surface — consumers can swap backends without rewriting types.
 
 ## Known limitations
 
-- The wasm module is single-threaded. Parallel queries inside one worker
-  serialise; spawn more workers for true parallelism.
+- The wasm module runs inside one JavaScript runtime. Auto-commit reads can
+  overlap on engine snapshots; write commits serialize. Use more Workers for
+  separate graphs or stronger UI isolation.
 - I64 values are delivered as JS `number` and lose precision above 2^53.
   Applications that need bigint precision should use the native
   `lora-node` binding instead.
@@ -227,7 +270,7 @@ public surface — consumers can swap backends without rewriting types.
   forms, parameter validation errors, and concurrent queries across the
   worker message protocol.
 - The TypeScript public contract is shared verbatim with `lora-node`
-  via `crates/shared-ts/types.ts`, enforced by `verify:types` in CI.
+  via `crates/bindings/shared-ts/types.ts`, enforced by `verify:types` in CI.
 - `npm pack --dry-run` produces a 45-file, 6.6 MB tarball containing
   all three wasm bundles plus the compiled TS wrapper. No `file:` deps,
   no postinstall scripts.
@@ -244,9 +287,8 @@ public surface — consumers can swap backends without rewriting types.
 - I64 precision is capped at `Number.MAX_SAFE_INTEGER`. For larger
   integer properties we need a `bigint`-aware serializer on the wasm
   boundary.
-- The engine is synchronous inside wasm — a single Worker serialises
-  queries. Multi-tenant workloads need either multiple Workers (already
-  possible), or an engine-level cooperative scheduler.
+- The engine is synchronous inside wasm once a call enters the module. A slow
+  query blocks that Worker until completion.
 - No query cancellation or progress streaming crosses the Worker
   boundary; a slow query blocks that Worker until completion.
 

package/pkg-node/lora_wasm.d.ts

@@ -21,23 +21,35 @@ export class WasmDatabase {
    * transaction. Returns an array of query results in statement order.
    */
   transaction(statements: any, mode?: string | null): any;
-  relationshipCount(): number;
   /**
-   * Serialize the graph into a byte buffer. The caller is responsible for
-   * writing it to disk, IndexedDB, localStorage, or wherever — WASM does
-   * not have direct filesystem access. The returned bytes can later be
-   * passed to `loadSnapshotFromBytes` on any `WasmDatabase` instance.
+   * Replace the graph state with a database snapshot decoded from `bytes`.
+   * Legacy store snapshot bytes are accepted for compatibility.
+   *
+   * Returns a plain object matching the shape of `SnapshotMeta`:
+   * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
+   */
+  loadSnapshot(bytes: Uint8Array, options: any): any;
+  /**
+   * Serialize the graph into database snapshot bytes. The caller is
+   * responsible for writing them to IndexedDB, localStorage, a server, or
+   * another host-provided store — WASM has no direct filesystem access.
+   * The returned bytes can later be passed to `loadSnapshot` on any
+   * `WasmDatabase` instance.
    *
    * Returns the serialized bytes as a `Uint8Array`.
    */
-  saveSnapshotToBytes(): Uint8Array;
+  saveSnapshot(options: any): Uint8Array;
   /**
-   * Replace the graph state with a snapshot decoded from `bytes`.
+   * Execute a Lora query and return the result as a binary buffer.
    *
-   * Returns a plain object matching the shape of `SnapshotMeta`:
-   * `{ formatVersion, nodeCount, relationshipCount, walLsn }`.
+   * Wire format is the shared `lora_binding_buffer` layout. The TS
+   * wrapper decodes it once into the same `{ columns, rows }` shape
+   * `execute()` returns, but in a tight V8 loop instead of going
+   * through `serde_wasm_bindgen` value-by-value. Materially faster
+   * on bulk reads.
    */
-  loadSnapshotFromBytes(bytes: Uint8Array): any;
+  executeBuffer(query: string, params: any): Uint8Array;
+  relationshipCount(): number;
   constructor();
   clear(): void;
   /**
@@ -48,6 +60,21 @@ export class WasmDatabase {
    * as a plain JS object (structured-clonable).
    */
   execute(query: string, params: any): any;
+  /**
+   * Compile a query and return its plan without executing it.
+   *
+   * Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) leave
+   * the graph untouched — this method never runs the executor.
+   */
+  explain(query: string, params: any): any;
+  /**
+   * Execute a query and return the plan plus runtime metrics.
+   *
+   * **PROFILE executes the query for real.** Mutating queries are
+   * persisted exactly as in `execute()`. Use `explain()` to inspect
+   * a mutating plan without running it.
+   */
+  profile(query: string, params: any): any;
 }
 export class WasmQueryStream {
   private constructor();