@wiscale/velesdb-wasm 1.12.0 → 1.13.0

package/README.md

@@ -8,7 +8,6 @@ WebAssembly build of [VelesDB](https://github.com/cyberlife-coder/VelesDB) - vec
 ## Features
 
 - **In-browser vector search** - No server required
-- **SIMD optimized** - Uses WASM SIMD128 for fast distance calculations
 - **Multiple metrics** - Cosine, Euclidean, Dot Product, Hamming, Jaccard
 - **Memory optimization** - SQ8 (4x) and Binary (32x) quantization
 - **Knowledge Graph** - In-memory graph store with BFS/DFS traversal

package/package.json

@@ -5,7 +5,7 @@
     "Julien Lange <contact@wiscale.fr>"
   ],
   "description": "VelesDB for WebAssembly - Vector search in the browser",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/velesdb_wasm.d.ts

@@ -282,17 +282,20 @@ export class GraphStore {
 }
 
 /**
- * Configuration for Web Worker traversal decisions.
+ * Thresholds used by [`should_use_worker`] to recommend Web Worker offload.
+ *
+ * This is a data-only configuration object. It does not allocate or start
+ * a Worker — the caller remains responsible for Worker lifecycle.
  */
 export class GraphWorkerConfig {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Creates a configuration optimized for large graphs.
+     * Returns thresholds tuned for large graphs.
      */
     static for_large_graphs(): GraphWorkerConfig;
     /**
-     * Creates a configuration optimized for responsive UI.
+     * Returns thresholds tuned for UI responsiveness on smaller graphs.
      */
     static for_responsive_ui(): GraphWorkerConfig;
     /**
@@ -300,21 +303,19 @@ export class GraphWorkerConfig {
      */
     constructor();
     /**
-     * Minimum depth to trigger worker offload.
+     * Minimum traversal depth at which offload is recommended.
      */
     depth_threshold: number;
     /**
-     * Minimum node count to trigger worker offload.
+     * Minimum node count at which offload is recommended.
      */
     node_threshold: number;
     /**
-     * Progress callback interval in milliseconds.
+     * Suggested progress callback interval in milliseconds for the
+     * caller's own worker implementation. This crate does not emit
+     * progress events on its own.
      */
     progress_interval_ms: number;
-    /**
-     * Whether to use `SharedArrayBuffer` for result transfer (if available).
-     */
-    use_shared_buffer: boolean;
 }
 
 /**
@@ -333,7 +334,17 @@ export class ParsedQuery {
      */
     readonly collectionName: string | undefined;
     /**
-     * Get the list of selected columns as JSON array.
+     * Get the list of selected columns — one entry per SELECT-list item.
+     *
+     * Returns a JSON array with every item in the SELECT list, in grammar
+     * order: regular columns, aggregate calls, `similarity()` expressions,
+     * qualified wildcards (`alias.*`), and window functions. `SELECT *`
+     * returns `["*"]`.
+     *
+     * Note (v1.13.0 contract completion): versions prior to v1.13.0
+     * silently omitted `similarity()` expressions and qualified wildcards
+     * from this list for mixed SELECT statements. The full list is now
+     * returned. Callers that hard-coded the shorter length must update.
      */
     readonly columns: any;
     /**
@@ -448,6 +459,99 @@ export class ParsedQuery {
     readonly tableName: string | undefined;
 }
 
+/**
+ * Result of executing a VelesQL query via
+ * [`WasmDatabase::execute_query`](crate::WasmDatabase).
+ *
+ * Getters expose the payload to JavaScript:
+ * - [`kind`](Self::kind) — statement class (`"rows"`, `"mutation"`, ...)
+ * - [`row_count`](Self::row_count) — number of rows in the result
+ * - [`message`](Self::message) — human-readable status message
+ * - [`row`](Self::row) / [`rows_json`](Self::rows_json) — row accessors
+ *
+ * # Row count semantics (Devin Review Finding F13)
+ *
+ * For row-returning statements (`SELECT`, `SHOW`, `DESCRIBE`, `SELECT
+ * EDGES`, `MATCH`) `row_count()` is `rows.len()` and `rows_json()`
+ * materialises every row.
+ *
+ * For row-affecting statements (`INSERT`, `UPSERT`, `UPDATE`, `DELETE`,
+ * graph mutations) `row_count()` returns an explicit `mutation_count`
+ * field and `rows_json()` is the empty array. Previously the executor
+ * allocated N placeholder rows (`{"id":0,"score":0.0}`) so that
+ * `rows.len()` matched the affected-row count — O(n) allocation for
+ * zero information content, plus a misleading JSON payload.
+ */
+export class QueryResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Row at the given index, or `undefined` when out of range.
+     *
+     * Transfers ownership to JavaScript — do not reuse the same index.
+     */
+    row(index: number): QueryResultRow | undefined;
+    /**
+     * Statement class, as a stable string.
+     *
+     * One of: `"rows"`, `"mutation"`, `"deletion"`, `"ddl"`, `"train"`,
+     * `"admin"`. Callers can branch on this to decide how to interpret
+     * [`rows_json`](Self::rows_json).
+     */
+    readonly kind: string;
+    /**
+     * Human-readable status message (for display / logging).
+     */
+    readonly message: string;
+    /**
+     * Number of rows affected or returned (`0` for DDL / admin / empty).
+     *
+     * For mutation statements the value comes from the explicit
+     * `mutation_count` field (set by `from_mutation`). For everything
+     * else it equals `rows.len()`. See the struct-level docs for the
+     * rationale behind the dual accounting (Finding F13).
+     */
+    readonly rowCount: number;
+    /**
+     * All rows as a single JSON array string.
+     *
+     * Each element is the row's `dataJson` object. Prefer this over
+     * iterating with [`row`](Self::row) when the caller wants a single
+     * `JSON.parse` call per query.
+     */
+    readonly rowsJson: string;
+}
+
+/**
+ * A single row returned by [`WasmDatabase::execute_query`](crate::WasmDatabase).
+ *
+ * The full row (id, score, and all payload fields merged at top level) is
+ * serialized as a JSON object string in [`QueryResultRow::data_json`]. This
+ * matches the Mobile bindings contract and lets the JavaScript caller do a
+ * single `JSON.parse()` per row.
+ */
+export class QueryResultRow {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Full row content as a JSON object string.
+     *
+     * Always contains at least `id` and `score`; all payload fields are
+     * merged at the top level (excluding shadowing of `id`/`score`).
+     */
+    readonly dataJson: string;
+    /**
+     * Point ID (0 for non-point results such as `SHOW COLLECTIONS`).
+     */
+    readonly id: bigint;
+    /**
+     * Similarity / relevance score (0.0 when no vector search ran).
+     */
+    readonly score: number;
+}
+
 /**
  * Semantic Memory for AI agents in WASM.
  *
@@ -631,7 +735,16 @@ export class VectorStore {
      */
     batch_search(vectors: Float32Array, num_vectors: number, k: number): any;
     /**
-     * Clears all vectors from the store.
+     * Clears all vectors, payloads, and auxiliary indexes from the
+     * store in place.
+     *
+     * Preserves `dimension`, `metric`, and `storage_mode` so the store
+     * can be re-populated without reallocation. Any sparse index is
+     * dropped: it would otherwise reference rows that no longer exist.
+     *
+     * Used by `TRUNCATE` (Devin Review Finding F12) so that outstanding
+     * `WasmCollectionHandle`s holding an `Rc` to this store observe the
+     * wipe atomically instead of pointing to a stale clone.
      */
     clear(): void;
     /**
@@ -735,6 +848,21 @@ export class VectorStore {
      * Searches with metadata filtering. Returns [{id, score, payload}].
      */
     search_with_filter(query: Float32Array, k: number, filter: any): any;
+    /**
+     * k-NN search with a named quality mode (API parity with Server/Python/Mobile).
+     *
+     * Accepts the same quality strings as the Python and Server SDKs:
+     * `"fast"`, `"balanced"`, `"accurate"`, `"perfect"`, `"autotune"`,
+     * `"custom:<ef>"`, `"adaptive:<min_ef>:<max_ef>"`.
+     *
+     * **WASM note**: The current WASM VectorStore uses brute-force O(n)
+     * search (no HNSW graph), so all quality modes produce identical results.
+     * The quality parameter is parsed and validated for API parity and
+     * forward-compatibility with future HNSW-backed WASM stores.
+     *
+     * Returns `[[id, score], ...]` sorted by relevance.
+     */
+    search_with_quality(query: Float32Array, k: number, quality: string): any;
     /**
      * Similarity search with threshold. Operators: >, >=, <, <=, =, !=.
      */
@@ -817,6 +945,179 @@ export class VelesQL {
     static parse(query: string): ParsedQuery;
 }
 
+/**
+ * A handle to a [`VectorStore`] managed by a [`WasmDatabase`].
+ *
+ * Operations on this handle mutate the shared collection. Multiple handles
+ * to the same collection are valid (single-threaded WASM — no data races).
+ *
+ * # Lifetime across DDL (Devin Review Finding F12)
+ *
+ * | Operation  | Effect on outstanding handles                              |
+ * |------------|-----------------------------------------------------------|
+ * | `TRUNCATE` | Handle keeps pointing to the same (now-emptied) store.    |
+ * | `DROP`     | Handle retains its `Rc` to the OLD store, detached from    |
+ * |            | the database. A later `CREATE` with the same name creates |
+ * |            | a NEW store that the old handle does not see.             |
+ * | `CREATE`   | Fresh handles obtained via `get_collection` are required  |
+ * |            | to observe the new store when reusing a dropped name.     |
+ */
+export class WasmCollectionHandle {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Inserts a vector with the given ID.
+     *
+     * # Errors
+     * Returns an error if the vector dimension does not match the collection.
+     */
+    insert(id: bigint, vector: Float32Array): void;
+    /**
+     * Removes a vector by ID. Returns `true` if found.
+     */
+    remove(id: bigint): boolean;
+    /**
+     * k-NN search. Returns `[[id, score], ...]`.
+     *
+     * # Errors
+     * Returns an error if the query dimension does not match the collection.
+     */
+    search(query: Float32Array, k: number): any;
+    /**
+     * Returns the vector dimensionality.
+     */
+    readonly dimension: number;
+    /**
+     * Returns `true` if the collection has no vectors.
+     */
+    readonly is_empty: boolean;
+    /**
+     * Returns the number of vectors in the collection.
+     */
+    readonly len: number;
+}
+
+/**
+ * An in-memory database that manages named [`VectorStore`] collections.
+ *
+ * # JavaScript usage
+ *
+ * ```javascript
+ * const db = new WasmDatabase();
+ * db.create_collection("docs", 768, "cosine");
+ * const coll = db.get_collection("docs");
+ * coll.insert(1n, new Float32Array([...]));
+ * const results = coll.search(new Float32Array([...]), 10);
+ * db.delete_collection("docs");
+ * ```
+ */
+export class WasmDatabase {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Creates a metadata-only collection (no vectors, only payloads).
+     *
+     * A metadata-only collection accepts `INSERT`/`UPDATE`/`DELETE` via
+     * `execute_query()` without requiring a `vector` column, making it the
+     * ideal target for reference data, lookup tables, or auxiliary metadata.
+     *
+     * # Errors
+     * Returns an error if the collection already exists.
+     */
+    createMetadataCollection(name: string): void;
+    /**
+     * Creates a named collection.
+     *
+     * # Arguments
+     * * `name` — unique collection name
+     * * `dimension` — vector dimensionality (e.g. 768)
+     * * `metric` — distance metric: `"cosine"`, `"euclidean"`, `"dot"`, etc.
+     *
+     * # Errors
+     * Returns an error if the collection already exists or the metric is
+     * invalid.
+     */
+    create_collection(name: string, dimension: number, metric: string): void;
+    /**
+     * Deletes a named collection and frees its memory.
+     *
+     * # Handle semantics
+     *
+     * Any [`WasmCollectionHandle`] previously obtained via
+     * [`get_collection`](Self::get_collection) keeps its own `Rc` to the
+     * backing store — mechanically the data is NOT freed on the spot.
+     * The handle continues to reference the *old* store, detached from
+     * the database. A subsequent `CREATE COLLECTION` with the same name
+     * allocates a **new** store, distinct from the old handle's data.
+     *
+     * Callers that want handles to observe later mutations should re-
+     * obtain a fresh handle after any CREATE. Note that `TRUNCATE`
+     * clears in place (see Devin Review Finding F12), so outstanding
+     * handles DO see the wipe — only DROP detaches.
+     *
+     * # Errors
+     * Returns an error if the collection does not exist.
+     */
+    delete_collection(name: string): void;
+    /**
+     * Executes a VelesQL statement against this database.
+     *
+     * Supports SELECT, INSERT / UPSERT, UPDATE, DELETE, DDL (CREATE / DROP /
+     * TRUNCATE COLLECTION), introspection (SHOW COLLECTIONS, DESCRIBE
+     * COLLECTION), and admin (FLUSH as no-op). Unsupported surfaces such as
+     * MATCH, TRAIN QUANTIZER, FUSION clauses, compound queries and graph
+     * DML return a descriptive error instead of crashing. See the
+     * [`velesql_exec`](crate::velesql_exec) module rustdoc for the full
+     * statement matrix.
+     *
+     * # Parameters
+     * * `sql` — VelesQL query string.
+     * * `params_json` — Optional JSON object with query parameters (keys
+     *   are bare names; use `$name` syntax in SQL). Pass `null` or `"{}"`
+     *   when no parameters are needed.
+     *
+     * # Example (JavaScript)
+     * ```javascript
+     * const db = new WasmDatabase();
+     * db.createMetadataCollection("docs");
+     * const r = db.executeQuery(
+     *     "INSERT INTO docs (id, title) VALUES (1, 'hello')",
+     *     null
+     * );
+     * console.log(r.kind, r.rowCount, r.rowsJson);
+     * ```
+     *
+     * # Errors
+     * Returns a `JsValue` error string when parsing fails, parameters are
+     * invalid, the target collection does not exist, or the statement uses
+     * a feature that WASM does not support.
+     */
+    executeQuery(sql: string, params_json?: string | null): QueryResult;
+    /**
+     * Returns a mutable handle to an existing collection.
+     *
+     * The returned [`WasmCollectionHandle`] shares state with the database —
+     * inserts and deletions through the handle are visible in the database.
+     *
+     * # Errors
+     * Returns an error if the collection does not exist.
+     */
+    get_collection(name: string): WasmCollectionHandle;
+    /**
+     * Lists all collection names as a JavaScript `Array<string>`.
+     */
+    list_collections(): any;
+    /**
+     * Creates an empty database with no collections.
+     */
+    constructor();
+    /**
+     * Returns the number of managed collections.
+     */
+    readonly collection_count: number;
+}
+
 /**
  * Estimates the number of nodes that will be visited during traversal.
  *
@@ -853,23 +1154,28 @@ export interface InitOutput {
     readonly __wbg_get_graphworkerconfig_depth_threshold: (a: number) => number;
     readonly __wbg_get_graphworkerconfig_node_threshold: (a: number) => number;
     readonly __wbg_get_graphworkerconfig_progress_interval_ms: (a: number) => number;
-    readonly __wbg_get_graphworkerconfig_use_shared_buffer: (a: number) => number;
     readonly __wbg_get_traversalprogress_is_cancelled: (a: number) => number;
+    readonly __wbg_get_traversalprogress_is_complete: (a: number) => number;
     readonly __wbg_graphedge_free: (a: number, b: number) => void;
     readonly __wbg_graphnode_free: (a: number, b: number) => void;
     readonly __wbg_graphpersistence_free: (a: number, b: number) => void;
     readonly __wbg_graphstore_free: (a: number, b: number) => void;
     readonly __wbg_graphworkerconfig_free: (a: number, b: number) => void;
     readonly __wbg_parsedquery_free: (a: number, b: number) => void;
+    readonly __wbg_queryresult_free: (a: number, b: number) => void;
+    readonly __wbg_queryresultrow_free: (a: number, b: number) => void;
     readonly __wbg_semanticmemory_free: (a: number, b: number) => void;
     readonly __wbg_set_graphworkerconfig_depth_threshold: (a: number, b: number) => void;
     readonly __wbg_set_graphworkerconfig_node_threshold: (a: number, b: number) => void;
     readonly __wbg_set_graphworkerconfig_progress_interval_ms: (a: number, b: number) => void;
-    readonly __wbg_set_graphworkerconfig_use_shared_buffer: (a: number, b: number) => void;
     readonly __wbg_set_traversalprogress_is_cancelled: (a: number, b: number) => void;
+    readonly __wbg_set_traversalprogress_is_complete: (a: number, b: number) => void;
     readonly __wbg_sparseindex_free: (a: number, b: number) => void;
+    readonly __wbg_traversalprogress_free: (a: number, b: number) => void;
     readonly __wbg_vectorstore_free: (a: number, b: number) => void;
     readonly __wbg_velesql_free: (a: number, b: number) => void;
+    readonly __wbg_wasmcollectionhandle_free: (a: number, b: number) => void;
+    readonly __wbg_wasmdatabase_free: (a: number, b: number) => void;
     readonly estimate_traversal_size: (a: number, b: number, c: number) => number;
     readonly graphedge_id: (a: number) => bigint;
     readonly graphedge_label: (a: number, b: number) => void;
@@ -950,6 +1256,14 @@ export interface InitOutput {
     readonly parsedquery_matchReturnItems: (a: number) => number;
     readonly parsedquery_offset: (a: number, b: number) => void;
     readonly parsedquery_orderBy: (a: number) => number;
+    readonly queryresult_kind: (a: number, b: number) => void;
+    readonly queryresult_message: (a: number, b: number) => void;
+    readonly queryresult_row: (a: number, b: number) => number;
+    readonly queryresult_rowCount: (a: number) => number;
+    readonly queryresult_rowsJson: (a: number, b: number) => void;
+    readonly queryresultrow_dataJson: (a: number, b: number) => void;
+    readonly queryresultrow_id: (a: number) => bigint;
+    readonly queryresultrow_score: (a: number) => number;
     readonly semanticmemory_clear: (a: number) => void;
     readonly semanticmemory_dimension: (a: number) => number;
     readonly semanticmemory_is_empty: (a: number) => number;
@@ -992,6 +1306,7 @@ export interface InitOutput {
     readonly vectorstore_save: (a: number, b: number, c: number) => number;
     readonly vectorstore_search: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly vectorstore_search_with_filter: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly vectorstore_search_with_quality: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
     readonly vectorstore_similarity_search: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
     readonly vectorstore_sparse_insert: (a: number, b: number, c: bigint, d: number, e: number, f: number, g: number) => void;
     readonly vectorstore_sparse_search: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
@@ -1000,7 +1315,19 @@ export interface InitOutput {
     readonly vectorstore_with_capacity: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly velesql_isValid: (a: number, b: number) => number;
     readonly velesql_parse: (a: number, b: number, c: number) => void;
-    readonly __wbg_set_traversalprogress_is_complete: (a: number, b: number) => void;
+    readonly wasmcollectionhandle_dimension: (a: number) => number;
+    readonly wasmcollectionhandle_insert: (a: number, b: number, c: bigint, d: number, e: number) => void;
+    readonly wasmcollectionhandle_is_empty: (a: number) => number;
+    readonly wasmcollectionhandle_len: (a: number) => number;
+    readonly wasmcollectionhandle_remove: (a: number, b: bigint) => number;
+    readonly wasmcollectionhandle_search: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly wasmdatabase_createMetadataCollection: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmdatabase_create_collection: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly wasmdatabase_delete_collection: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmdatabase_executeQuery: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasmdatabase_get_collection: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmdatabase_list_collections: (a: number) => number;
+    readonly wasmdatabase_new: () => number;
     readonly __wbg_set_traversalprogress_current_depth: (a: number, b: number) => void;
     readonly __wbg_set_traversalprogress_estimated_total: (a: number, b: number) => void;
     readonly __wbg_set_traversalprogress_visited_count: (a: number, b: number) => void;
@@ -1008,14 +1335,13 @@ export interface InitOutput {
     readonly __wbg_get_traversalprogress_estimated_total: (a: number) => number;
     readonly __wbg_get_traversalprogress_visited_count: (a: number) => number;
     readonly graphnode_id: (a: number) => bigint;
+    readonly wasmdatabase_collection_count: (a: number) => number;
     readonly parsedquery_tableName: (a: number, b: number) => void;
-    readonly __wbg_get_traversalprogress_is_complete: (a: number) => number;
-    readonly __wbg_traversalprogress_free: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1234: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_287: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1235: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_1477: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_288: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_1653: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_396: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_1654: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1896: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_397: (a: number, b: number, c: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/velesdb_wasm.js

@@ -757,7 +757,10 @@ export class GraphStore {
 if (Symbol.dispose) GraphStore.prototype[Symbol.dispose] = GraphStore.prototype.free;
 
 /**
- * Configuration for Web Worker traversal decisions.
+ * Thresholds used by [`should_use_worker`] to recommend Web Worker offload.
+ *
+ * This is a data-only configuration object. It does not allocate or start
+ * a Worker — the caller remains responsible for Worker lifecycle.
  */
 export class GraphWorkerConfig {
     static __wrap(ptr) {
@@ -778,7 +781,7 @@ export class GraphWorkerConfig {
         wasm.__wbg_graphworkerconfig_free(ptr, 0);
     }
     /**
-     * Minimum depth to trigger worker offload.
+     * Minimum traversal depth at which offload is recommended.
      * @returns {number}
      */
     get depth_threshold() {
@@ -786,7 +789,7 @@ export class GraphWorkerConfig {
         return ret >>> 0;
     }
     /**
-     * Minimum node count to trigger worker offload.
+     * Minimum node count at which offload is recommended.
      * @returns {number}
      */
     get node_threshold() {
@@ -794,7 +797,9 @@ export class GraphWorkerConfig {
         return ret >>> 0;
     }
     /**
-     * Progress callback interval in milliseconds.
+     * Suggested progress callback interval in milliseconds for the
+     * caller's own worker implementation. This crate does not emit
+     * progress events on its own.
      * @returns {number}
      */
     get progress_interval_ms() {
@@ -802,15 +807,7 @@ export class GraphWorkerConfig {
         return ret >>> 0;
     }
     /**
-     * Whether to use `SharedArrayBuffer` for result transfer (if available).
-     * @returns {boolean}
-     */
-    get use_shared_buffer() {
-        const ret = wasm.__wbg_get_graphworkerconfig_use_shared_buffer(this.__wbg_ptr);
-        return ret !== 0;
-    }
-    /**
-     * Creates a configuration optimized for large graphs.
+     * Returns thresholds tuned for large graphs.
      * @returns {GraphWorkerConfig}
      */
     static for_large_graphs() {
@@ -818,7 +815,7 @@ export class GraphWorkerConfig {
         return GraphWorkerConfig.__wrap(ret);
     }
     /**
-     * Creates a configuration optimized for responsive UI.
+     * Returns thresholds tuned for UI responsiveness on smaller graphs.
      * @returns {GraphWorkerConfig}
      */
     static for_responsive_ui() {
@@ -835,33 +832,28 @@ export class GraphWorkerConfig {
         return this;
     }
     /**
-     * Minimum depth to trigger worker offload.
+     * Minimum traversal depth at which offload is recommended.
      * @param {number} arg0
      */
     set depth_threshold(arg0) {
         wasm.__wbg_set_graphworkerconfig_depth_threshold(this.__wbg_ptr, arg0);
     }
     /**
-     * Minimum node count to trigger worker offload.
+     * Minimum node count at which offload is recommended.
      * @param {number} arg0
      */
     set node_threshold(arg0) {
         wasm.__wbg_set_graphworkerconfig_node_threshold(this.__wbg_ptr, arg0);
     }
     /**
-     * Progress callback interval in milliseconds.
+     * Suggested progress callback interval in milliseconds for the
+     * caller's own worker implementation. This crate does not emit
+     * progress events on its own.
      * @param {number} arg0
      */
     set progress_interval_ms(arg0) {
         wasm.__wbg_set_graphworkerconfig_progress_interval_ms(this.__wbg_ptr, arg0);
     }
-    /**
-     * Whether to use `SharedArrayBuffer` for result transfer (if available).
-     * @param {boolean} arg0
-     */
-    set use_shared_buffer(arg0) {
-        wasm.__wbg_set_graphworkerconfig_use_shared_buffer(this.__wbg_ptr, arg0);
-    }
 }
 if (Symbol.dispose) GraphWorkerConfig.prototype[Symbol.dispose] = GraphWorkerConfig.prototype.free;
 
@@ -911,7 +903,17 @@ export class ParsedQuery {
         }
     }
     /**
-     * Get the list of selected columns as JSON array.
+     * Get the list of selected columns — one entry per SELECT-list item.
+     *
+     * Returns a JSON array with every item in the SELECT list, in grammar
+     * order: regular columns, aggregate calls, `similarity()` expressions,
+     * qualified wildcards (`alias.*`), and window functions. `SELECT *`
+     * returns `["*"]`.
+     *
+     * Note (v1.13.0 contract completion): versions prior to v1.13.0
+     * silently omitted `similarity()` expressions and qualified wildcards
+     * from this list for mixed SELECT statements. The full list is now
+     * returned. Callers that hard-coded the shorter length must update.
      * @returns {any}
      */
     get columns() {
@@ -1172,6 +1174,210 @@ export class ParsedQuery {
 }
 if (Symbol.dispose) ParsedQuery.prototype[Symbol.dispose] = ParsedQuery.prototype.free;
 
+/**
+ * Result of executing a VelesQL query via
+ * [`WasmDatabase::execute_query`](crate::WasmDatabase).
+ *
+ * Getters expose the payload to JavaScript:
+ * - [`kind`](Self::kind) — statement class (`"rows"`, `"mutation"`, ...)
+ * - [`row_count`](Self::row_count) — number of rows in the result
+ * - [`message`](Self::message) — human-readable status message
+ * - [`row`](Self::row) / [`rows_json`](Self::rows_json) — row accessors
+ *
+ * # Row count semantics (Devin Review Finding F13)
+ *
+ * For row-returning statements (`SELECT`, `SHOW`, `DESCRIBE`, `SELECT
+ * EDGES`, `MATCH`) `row_count()` is `rows.len()` and `rows_json()`
+ * materialises every row.
+ *
+ * For row-affecting statements (`INSERT`, `UPSERT`, `UPDATE`, `DELETE`,
+ * graph mutations) `row_count()` returns an explicit `mutation_count`
+ * field and `rows_json()` is the empty array. Previously the executor
+ * allocated N placeholder rows (`{"id":0,"score":0.0}`) so that
+ * `rows.len()` matched the affected-row count — O(n) allocation for
+ * zero information content, plus a misleading JSON payload.
+ */
+export class QueryResult {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(QueryResult.prototype);
+        obj.__wbg_ptr = ptr;
+        QueryResultFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        QueryResultFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_queryresult_free(ptr, 0);
+    }
+    /**
+     * Statement class, as a stable string.
+     *
+     * One of: `"rows"`, `"mutation"`, `"deletion"`, `"ddl"`, `"train"`,
+     * `"admin"`. Callers can branch on this to decide how to interpret
+     * [`rows_json`](Self::rows_json).
+     * @returns {string}
+     */
+    get kind() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.queryresult_kind(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Human-readable status message (for display / logging).
+     * @returns {string}
+     */
+    get message() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.queryresult_message(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Row at the given index, or `undefined` when out of range.
+     *
+     * Transfers ownership to JavaScript — do not reuse the same index.
+     * @param {number} index
+     * @returns {QueryResultRow | undefined}
+     */
+    row(index) {
+        const ret = wasm.queryresult_row(this.__wbg_ptr, index);
+        return ret === 0 ? undefined : QueryResultRow.__wrap(ret);
+    }
+    /**
+     * Number of rows affected or returned (`0` for DDL / admin / empty).
+     *
+     * For mutation statements the value comes from the explicit
+     * `mutation_count` field (set by `from_mutation`). For everything
+     * else it equals `rows.len()`. See the struct-level docs for the
+     * rationale behind the dual accounting (Finding F13).
+     * @returns {number}
+     */
+    get rowCount() {
+        const ret = wasm.queryresult_rowCount(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * All rows as a single JSON array string.
+     *
+     * Each element is the row's `dataJson` object. Prefer this over
+     * iterating with [`row`](Self::row) when the caller wants a single
+     * `JSON.parse` call per query.
+     * @returns {string}
+     */
+    get rowsJson() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.queryresult_rowsJson(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) QueryResult.prototype[Symbol.dispose] = QueryResult.prototype.free;
+
+/**
+ * A single row returned by [`WasmDatabase::execute_query`](crate::WasmDatabase).
+ *
+ * The full row (id, score, and all payload fields merged at top level) is
+ * serialized as a JSON object string in [`QueryResultRow::data_json`]. This
+ * matches the Mobile bindings contract and lets the JavaScript caller do a
+ * single `JSON.parse()` per row.
+ */
+export class QueryResultRow {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(QueryResultRow.prototype);
+        obj.__wbg_ptr = ptr;
+        QueryResultRowFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        QueryResultRowFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_queryresultrow_free(ptr, 0);
+    }
+    /**
+     * Full row content as a JSON object string.
+     *
+     * Always contains at least `id` and `score`; all payload fields are
+     * merged at the top level (excluding shadowing of `id`/`score`).
+     * @returns {string}
+     */
+    get dataJson() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.queryresultrow_dataJson(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Point ID (0 for non-point results such as `SHOW COLLECTIONS`).
+     * @returns {bigint}
+     */
+    get id() {
+        const ret = wasm.queryresultrow_id(this.__wbg_ptr);
+        return BigInt.asUintN(64, ret);
+    }
+    /**
+     * Similarity / relevance score (0.0 when no vector search ran).
+     * @returns {number}
+     */
+    get score() {
+        const ret = wasm.queryresultrow_score(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose) QueryResultRow.prototype[Symbol.dispose] = QueryResultRow.prototype.free;
+
 /**
  * Semantic Memory for AI agents in WASM.
  *
@@ -1624,7 +1830,16 @@ export class VectorStore {
         }
     }
     /**
-     * Clears all vectors from the store.
+     * Clears all vectors, payloads, and auxiliary indexes from the
+     * store in place.
+     *
+     * Preserves `dimension`, `metric`, and `storage_mode` so the store
+     * can be re-populated without reallocation. Any sparse index is
+     * dropped: it would otherwise reference rows that no longer exist.
+     *
+     * Used by `TRUNCATE` (Devin Review Finding F12) so that outstanding
+     * `WasmCollectionHandle`s holding an `Rc` to this store observe the
+     * wipe atomically instead of pointing to a stale clone.
      */
     clear() {
         wasm.vectorstore_clear(this.__wbg_ptr);
@@ -2044,6 +2259,43 @@ export class VectorStore {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * k-NN search with a named quality mode (API parity with Server/Python/Mobile).
+     *
+     * Accepts the same quality strings as the Python and Server SDKs:
+     * `"fast"`, `"balanced"`, `"accurate"`, `"perfect"`, `"autotune"`,
+     * `"custom:<ef>"`, `"adaptive:<min_ef>:<max_ef>"`.
+     *
+     * **WASM note**: The current WASM VectorStore uses brute-force O(n)
+     * search (no HNSW graph), so all quality modes produce identical results.
+     * The quality parameter is parsed and validated for API parity and
+     * forward-compatibility with future HNSW-backed WASM stores.
+     *
+     * Returns `[[id, score], ...]` sorted by relevance.
+     * @param {Float32Array} query
+     * @param {number} k
+     * @param {string} quality
+     * @returns {any}
+     */
+    search_with_quality(query, k, quality) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArrayF32ToWasm0(query, wasm.__wbindgen_export);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(quality, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.vectorstore_search_with_quality(retptr, this.__wbg_ptr, ptr0, len0, k, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Similarity search with threshold. Operators: >, >=, <, <=, =, !=.
      * @param {Float32Array} query
@@ -2266,6 +2518,356 @@ export class VelesQL {
 }
 if (Symbol.dispose) VelesQL.prototype[Symbol.dispose] = VelesQL.prototype.free;
 
+/**
+ * A handle to a [`VectorStore`] managed by a [`WasmDatabase`].
+ *
+ * Operations on this handle mutate the shared collection. Multiple handles
+ * to the same collection are valid (single-threaded WASM — no data races).
+ *
+ * # Lifetime across DDL (Devin Review Finding F12)
+ *
+ * | Operation  | Effect on outstanding handles                              |
+ * |------------|-----------------------------------------------------------|
+ * | `TRUNCATE` | Handle keeps pointing to the same (now-emptied) store.    |
+ * | `DROP`     | Handle retains its `Rc` to the OLD store, detached from    |
+ * |            | the database. A later `CREATE` with the same name creates |
+ * |            | a NEW store that the old handle does not see.             |
+ * | `CREATE`   | Fresh handles obtained via `get_collection` are required  |
+ * |            | to observe the new store when reusing a dropped name.     |
+ */
+export class WasmCollectionHandle {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmCollectionHandle.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmCollectionHandleFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmCollectionHandleFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmcollectionhandle_free(ptr, 0);
+    }
+    /**
+     * Returns the vector dimensionality.
+     * @returns {number}
+     */
+    get dimension() {
+        const ret = wasm.wasmcollectionhandle_dimension(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Inserts a vector with the given ID.
+     *
+     * # Errors
+     * Returns an error if the vector dimension does not match the collection.
+     * @param {bigint} id
+     * @param {Float32Array} vector
+     */
+    insert(id, vector) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArrayF32ToWasm0(vector, wasm.__wbindgen_export);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.wasmcollectionhandle_insert(retptr, this.__wbg_ptr, id, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Returns `true` if the collection has no vectors.
+     * @returns {boolean}
+     */
+    get is_empty() {
+        const ret = wasm.wasmcollectionhandle_is_empty(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Returns the number of vectors in the collection.
+     * @returns {number}
+     */
+    get len() {
+        const ret = wasm.wasmcollectionhandle_len(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Removes a vector by ID. Returns `true` if found.
+     * @param {bigint} id
+     * @returns {boolean}
+     */
+    remove(id) {
+        const ret = wasm.wasmcollectionhandle_remove(this.__wbg_ptr, id);
+        return ret !== 0;
+    }
+    /**
+     * k-NN search. Returns `[[id, score], ...]`.
+     *
+     * # Errors
+     * Returns an error if the query dimension does not match the collection.
+     * @param {Float32Array} query
+     * @param {number} k
+     * @returns {any}
+     */
+    search(query, k) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passArrayF32ToWasm0(query, wasm.__wbindgen_export);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.wasmcollectionhandle_search(retptr, this.__wbg_ptr, ptr0, len0, k);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+}
+if (Symbol.dispose) WasmCollectionHandle.prototype[Symbol.dispose] = WasmCollectionHandle.prototype.free;
+
+/**
+ * An in-memory database that manages named [`VectorStore`] collections.
+ *
+ * # JavaScript usage
+ *
+ * ```javascript
+ * const db = new WasmDatabase();
+ * db.create_collection("docs", 768, "cosine");
+ * const coll = db.get_collection("docs");
+ * coll.insert(1n, new Float32Array([...]));
+ * const results = coll.search(new Float32Array([...]), 10);
+ * db.delete_collection("docs");
+ * ```
+ */
+export class WasmDatabase {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmDatabaseFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmdatabase_free(ptr, 0);
+    }
+    /**
+     * Returns the number of managed collections.
+     * @returns {number}
+     */
+    get collection_count() {
+        const ret = wasm.wasmdatabase_collection_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Creates a metadata-only collection (no vectors, only payloads).
+     *
+     * A metadata-only collection accepts `INSERT`/`UPDATE`/`DELETE` via
+     * `execute_query()` without requiring a `vector` column, making it the
+     * ideal target for reference data, lookup tables, or auxiliary metadata.
+     *
+     * # Errors
+     * Returns an error if the collection already exists.
+     * @param {string} name
+     */
+    createMetadataCollection(name) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.wasmdatabase_createMetadataCollection(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Creates a named collection.
+     *
+     * # Arguments
+     * * `name` — unique collection name
+     * * `dimension` — vector dimensionality (e.g. 768)
+     * * `metric` — distance metric: `"cosine"`, `"euclidean"`, `"dot"`, etc.
+     *
+     * # Errors
+     * Returns an error if the collection already exists or the metric is
+     * invalid.
+     * @param {string} name
+     * @param {number} dimension
+     * @param {string} metric
+     */
+    create_collection(name, dimension, metric) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            const ptr1 = passStringToWasm0(metric, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            wasm.wasmdatabase_create_collection(retptr, this.__wbg_ptr, ptr0, len0, dimension, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Deletes a named collection and frees its memory.
+     *
+     * # Handle semantics
+     *
+     * Any [`WasmCollectionHandle`] previously obtained via
+     * [`get_collection`](Self::get_collection) keeps its own `Rc` to the
+     * backing store — mechanically the data is NOT freed on the spot.
+     * The handle continues to reference the *old* store, detached from
+     * the database. A subsequent `CREATE COLLECTION` with the same name
+     * allocates a **new** store, distinct from the old handle's data.
+     *
+     * Callers that want handles to observe later mutations should re-
+     * obtain a fresh handle after any CREATE. Note that `TRUNCATE`
+     * clears in place (see Devin Review Finding F12), so outstanding
+     * handles DO see the wipe — only DROP detaches.
+     *
+     * # Errors
+     * Returns an error if the collection does not exist.
+     * @param {string} name
+     */
+    delete_collection(name) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.wasmdatabase_delete_collection(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Executes a VelesQL statement against this database.
+     *
+     * Supports SELECT, INSERT / UPSERT, UPDATE, DELETE, DDL (CREATE / DROP /
+     * TRUNCATE COLLECTION), introspection (SHOW COLLECTIONS, DESCRIBE
+     * COLLECTION), and admin (FLUSH as no-op). Unsupported surfaces such as
+     * MATCH, TRAIN QUANTIZER, FUSION clauses, compound queries and graph
+     * DML return a descriptive error instead of crashing. See the
+     * [`velesql_exec`](crate::velesql_exec) module rustdoc for the full
+     * statement matrix.
+     *
+     * # Parameters
+     * * `sql` — VelesQL query string.
+     * * `params_json` — Optional JSON object with query parameters (keys
+     *   are bare names; use `$name` syntax in SQL). Pass `null` or `"{}"`
+     *   when no parameters are needed.
+     *
+     * # Example (JavaScript)
+     * ```javascript
+     * const db = new WasmDatabase();
+     * db.createMetadataCollection("docs");
+     * const r = db.executeQuery(
+     *     "INSERT INTO docs (id, title) VALUES (1, 'hello')",
+     *     null
+     * );
+     * console.log(r.kind, r.rowCount, r.rowsJson);
+     * ```
+     *
+     * # Errors
+     * Returns a `JsValue` error string when parsing fails, parameters are
+     * invalid, the target collection does not exist, or the statement uses
+     * a feature that WASM does not support.
+     * @param {string} sql
+     * @param {string | null} [params_json]
+     * @returns {QueryResult}
+     */
+    executeQuery(sql, params_json) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(sql, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            var ptr1 = isLikeNone(params_json) ? 0 : passStringToWasm0(params_json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len1 = WASM_VECTOR_LEN;
+            wasm.wasmdatabase_executeQuery(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return QueryResult.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Returns a mutable handle to an existing collection.
+     *
+     * The returned [`WasmCollectionHandle`] shares state with the database —
+     * inserts and deletions through the handle are visible in the database.
+     *
+     * # Errors
+     * Returns an error if the collection does not exist.
+     * @param {string} name
+     * @returns {WasmCollectionHandle}
+     */
+    get_collection(name) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.wasmdatabase_get_collection(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return WasmCollectionHandle.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Lists all collection names as a JavaScript `Array<string>`.
+     * @returns {any}
+     */
+    list_collections() {
+        const ret = wasm.wasmdatabase_list_collections(this.__wbg_ptr);
+        return takeObject(ret);
+    }
+    /**
+     * Creates an empty database with no collections.
+     */
+    constructor() {
+        const ret = wasm.wasmdatabase_new();
+        this.__wbg_ptr = ret >>> 0;
+        WasmDatabaseFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+}
+if (Symbol.dispose) WasmDatabase.prototype[Symbol.dispose] = WasmDatabase.prototype.free;
+
 /**
  * Estimates the number of nodes that will be visited during traversal.
  *
@@ -2599,7 +3201,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1477(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1896(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -2621,7 +3223,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1477(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1896(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -2754,13 +3356,13 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 144, function: Function { arguments: [Externref], shim_idx: 145, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_1234, __wasm_bindgen_func_elem_1235);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 332, function: Function { arguments: [Externref], shim_idx: 333, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_1653, __wasm_bindgen_func_elem_1654);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 5, function: Function { arguments: [NamedExternref("Event")], shim_idx: 6, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_287, __wasm_bindgen_func_elem_288);
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 7, function: Function { arguments: [NamedExternref("Event")], shim_idx: 8, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, wasm.__wasm_bindgen_func_elem_396, __wasm_bindgen_func_elem_397);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0) {
@@ -2797,14 +3399,14 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_288(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_288(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_397(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_397(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_1235(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_1654(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_1235(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_1654(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -2815,8 +3417,8 @@ function __wasm_bindgen_func_elem_1235(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_1477(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_1477(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_1896(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_1896(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 
@@ -2839,6 +3441,12 @@ const GraphWorkerConfigFinalization = (typeof FinalizationRegistry === 'undefine
 const ParsedQueryFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_parsedquery_free(ptr >>> 0, 1));
+const QueryResultFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_queryresult_free(ptr >>> 0, 1));
+const QueryResultRowFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_queryresultrow_free(ptr >>> 0, 1));
 const SemanticMemoryFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_semanticmemory_free(ptr >>> 0, 1));
@@ -2854,6 +3462,12 @@ const VectorStoreFinalization = (typeof FinalizationRegistry === 'undefined')
 const VelesQLFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_velesql_free(ptr >>> 0, 1));
+const WasmCollectionHandleFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmcollectionhandle_free(ptr >>> 0, 1));
+const WasmDatabaseFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmdatabase_free(ptr >>> 0, 1));
 
 function addHeapObject(obj) {
     if (heap_next === heap.length) heap.push(heap.length + 1);