sekejap 0.16.5 → 0.18.0

package/README.md

@@ -1,14 +1,37 @@
-# sekejap
-
-Embedded **graph-first, multi-model database** for Node.js — SQL + graph + vector +
-spatial in one native library. No server, no external process; the whole engine runs
-in-process on a Rust core.
-
-- **PostgreSQL-like SQL** — `CREATE TABLE`, `INSERT`, `SELECT … WHERE`, parameters (`$1`).
-- **Graph** — link records and traverse relationships.
-- **Prepared statements** — compile once, run many with varying parameters.
-- **No native build** — the prebuilt binaries for every platform ship inside the
-  package. No Rust toolchain, no `node-gyp`, no compile step.
+# sekejap (Node.js)
+
+Embedded **graph-first, multi-model database** for Node.js: SQL + graph + vector
++ spatial in one native library. No server, no external process — the whole
+engine runs in-process, in Rust, and this package talks to it over the C ABI
+(`docs/dist/C_ABI.md`), not napi-rs.
+
+- **PostgreSQL-like SQL** — `CREATE TABLE`, `INSERT`, `SELECT … WHERE`, `$n` parameters.
+- **Graph** — `link`/`unlink`/`neighbours`, and `GRAPH_TABLE` in SQL for deeper walks.
+- **Prepared statements and paged scans** — compile once, run many; walk a
+  collection or a SELECT's answer a page at a time.
+- **Transactions** — many writes under one commit barrier.
+- **Documents already parsed** — every call returns a JS value, not a JSON
+  string to `JSON.parse` yourself.
+
+## Choosing the FFI route
+
+This wrapper binds `libsekejap` through [koffi](https://koffi.dev), not
+through a compiled napi-rs addon (e1's approach, and what this package used
+before). Two reasons:
+
+1. **No native build for this package.** koffi ships its own prebuilt N-API
+   glue for the platforms it supports; this file does one `koffi.load()` of
+   the sekejap shared library at `require()` time. There is no `cargo build`,
+   no `node-gyp`, and no per-Node-ABI addon to rebuild — the wrapper itself
+   is pure JS, and only `libsekejap.{dylib,so,dll}` is platform-specific.
+2. **`node-ffi-napi`/`ref-napi` are gone.** They were the other candidate
+   considered, but `node-ffi-napi` is unpublished from the npm registry
+   (`npm view node-ffi-napi` → 404) and its `ref-napi` dependency compiles a
+   native addon of its own — the opposite of what "no native build" needs.
+   koffi is the smaller, actively maintained port: one dependency, prebuilt,
+   with disposable types (`koffi.disposable`) that map directly onto this
+   ABI's "every returned `char*` is freed once with `sekejap_string_free`"
+   rule (see `index.js` §2-3).
 
 ## Install
 
@@ -16,71 +39,159 @@ in-process on a Rust core.
 npm install sekejap
 ```
 
-Works on macOS (arm64/x64), Linux (x64/arm64), and Windows (x64), Node ≥ 16.
+The published package bundles a `native/<platform>-<arch>/lib/libsekejap.*`
+per supported platform (assembled by the `publish-node` CI job from the same
+`build-native-libs` artifacts every other wrapper links). Locally, or against
+a library you built yourself, point at it explicitly:
+
+```sh
+export SEKEJAP_LIB_PATH=/path/to/libsekejap.dylib   # exact file, or:
+export SEKEJAP_LIB_DIR=/path/to/dir/holding/it       # a directory, or:
+export DYLD_LIBRARY_PATH=/path/to/dir                # (Linux: LD_LIBRARY_PATH)
+```
+
+Resolution order: `SEKEJAP_LIB_PATH` → `SEKEJAP_LIB_DIR` →
+`native/<platform>-<arch>/` inside the package → the bare library name,
+which the OS loader then searches its own path for.
 
 ## Quick start
 
 ```js
-const { Db, version } = require('sekejap');
+const { Db } = require('sekejap');
 
-const db = Db.open('/tmp/notes');           // open (or create) a database directory
+const db = Db.open('/tmp/notes'); // open (or create) a database directory
 
-// Define a table and insert rows with SQL.
-db.execute('CREATE TABLE note (_key TEXT PRIMARY KEY, title TEXT, pinned INTEGER)');
-db.execute("INSERT INTO note (_key, title, pinned) VALUES ('n1', 'Buy milk', 1)");
+db.execute('CREATE TABLE note (title TEXT, pinned BOOL)');
+db.execute("INSERT INTO note (_key, title, pinned) VALUES ('n1', 'Buy milk', true)");
 
-// Insert a record directly (no SQL) as a JSON payload.
-db.put('note/n2', JSON.stringify({ _collection: 'note', _key: 'n2', title: 'Call Sam', pinned: 0 }));
+// The document API — no SQL. `_key` in the value is optional; it is set
+// from the `key` argument when absent.
+db.put('note', 'n2', { title: 'Call Sam', pinned: false });
 
-// Query. Results come back as a JSON string — JSON.parse it.
-const notes = JSON.parse(db.query('SELECT * FROM note'));
-console.log(notes);
-// [ { _key: 'n1', title: 'Buy milk', pinned: 1, ... }, { _key: 'n2', ... } ]
+console.log(db.get('note', 'n1')); // { _key: 'n1', title: 'Buy milk', pinned: true }
 
-// Parameterized query ($1, $2, …) — injection-safe. Params are a JSON array string.
-const pinned = JSON.parse(db.queryParams('SELECT title FROM note WHERE pinned = $1', JSON.stringify([1])));
+db.execute('CREATE INDEX note_pinned ON note USING btree (pinned)');
+const pinned = db.query('SELECT title FROM note WHERE pinned = $1', [true]);
 
-// Prepared statement — compile once, run many.
-const byPin = db.prepare('SELECT _key FROM note WHERE pinned = $1');
-for (const p of [0, 1]) {
-  console.log(JSON.parse(db.queryPrepared(byPin, JSON.stringify([p]))));
-}
+const stmt = db.prepare('SELECT title FROM note WHERE pinned = $1');
+for (const want of [true, false]) console.log(stmt.query([want]));
+stmt.close();
 
-// Graph: link two records.
-db.link('note/n1', 'note/n2', 'related');
-console.log('nodes:', db.nodeCount(), 'edges:', db.edgeCount());
+db.link('note', 'n1', 'related', 'note', 'n2');
+console.log(db.neighbours('note', 'n1', 'related', 'outgoing', 10));
 
-// Flush + compact to disk after heavy writes.
-db.compact();
+const tx = db.transaction();
+tx.put('note', 'n3', { title: 'Committed together', pinned: false });
+tx.commit(); // or tx.rollback()
+
+console.log('rows:', db.countRows('note'));
+db.close();
 ```
 
-## API
+More: `examples/tour.js`.
+
+## API mapping (C function → wrapper call)
 
-| Method | Purpose |
+| C function | wrapper call |
 |---|---|
-| `Db.open(path)` | Open (or create) a database at a directory path |
-| `db.execute(sql)` | Run DDL/DML (`CREATE`/`INSERT`/`UPDATE`/`DELETE`) → rows affected |
-| `db.query(sql)` | Run a `SELECT`/graph query → **JSON string** |
-| `db.queryParams(sql, paramsJson)` | Parameterized query; `paramsJson` is a JSON array string |
-| `db.prepare(sql)` / `db.queryPrepared(stmt, paramsJson)` | Prepared statements |
-| `db.put(slug, payloadJson)` | Insert/replace one record by slug with a JSON payload |
-| `db.link(from, to, edgeType)` | Create a graph edge |
-| `db.nodeCount()` / `db.edgeCount()` | Counts |
-| `db.compact()` | Flush WAL, rewrite payloads, reclaim RAM |
-| `version()` | Library version |
-
-`query` / `queryParams` / `queryPrepared` return a **JSON string** — decode with
-`JSON.parse(...)`. It's an array of row objects.
-
-### TypeScript
-
-Types ship with the package (`index.d.ts`) — no `@types` needed.
-
-```ts
-import { Db } from 'sekejap';
-const db = Db.open('/tmp/notes');
-```
+| `sekejap_open` | `Db.open(path)` |
+| `sekejap_open_with_config` | `Db.openWithConfig(path, config)` |
+| `sekejap_open_service` | `Db.openService(path)` |
+| `sekejap_close` | `db.close()` |
+| `sekejap_version` | `version()` (module function) |
+| `sekejap_format_version` | `formatVersion()` (module function) |
+| `sekejap_last_error` / `sekejap_last_error_code` | folded into every thrown `SekejapError` (`.message`, `.code`, `.status`) |
+| `sekejap_string_free` | never called by user code — wired as a `koffi.disposable` type, freed automatically after every C→JS string conversion |
+| `sekejap_put` | `db.put(collection, key, doc)` |
+| `sekejap_put_many` | `db.putMany(collection, rows)` |
+| `sekejap_get` | `db.get(collection, key)` → object or `null` |
+| `sekejap_exists` | `db.exists(collection, key)` → boolean |
+| `sekejap_delete` | `db.delete(collection, key)` → boolean |
+| `sekejap_scan_open` / `_next` / `_close` | `db.scan(collection, pageRows)` → `Scan` (`for...of`, `.rows()`, `.next()`, `.close()`) |
+| `sekejap_execute` | `db.execute(sql, params)` |
+| `sekejap_query` | `db.query(sql, params)` |
+| `sekejap_explain` | `db.explain(sql, params)` |
+| `sekejap_prepare` | `db.prepare(sql)` → `Statement` |
+| `sekejap_stmt_query` | `stmt.query(params)` |
+| `sekejap_stmt_execute` | `stmt.execute(params)` |
+| `sekejap_stmt_rebindable` | `stmt.rebindable()` → boolean or `null` (unbound) |
+| `sekejap_stmt_free` | `stmt.close()` |
+| `sekejap_query_open` / `_next` / `_close` | `db.stream(sql, params, pageRows)` → `Scan` |
+| `sekejap_link` | `db.link(fromCollection, fromKey, edgeType, toCollection, toKey)` |
+| `sekejap_link_with` | `db.linkWith(..., properties)` |
+| `sekejap_unlink` | `db.unlink(...)` → boolean |
+| `sekejap_neighbours` | `db.neighbours(collection, key, edgeType, direction, limit)` |
+| `sekejap_create_collection` | `db.createCollection(name, fields)` → boolean |
+| `sekejap_drop_collection` | `db.dropCollection(name)` → boolean |
+| `sekejap_collections` | `db.collections()` |
+| `sekejap_describe` | `db.describe(collection)` → object or `null` |
+| `sekejap_count_rows` | `db.countRows(collection)` |
+| `sekejap_scan_count_rows` | `db.scanCountRows(collection)` |
+| `sekejap_scan_count_edges` | `db.scanCountEdges()` |
+| `sekejap_tx_begin` | `db.transaction()` → `Tx` |
+| `sekejap_tx_put` / `_delete` / `_link` / `_execute` | `tx.put` / `tx.delete` / `tx.link` / `tx.execute` |
+| `sekejap_tx_commit` / `_rollback` | `tx.commit()` / `tx.rollback()` |
+| `sekejap_checkpoint` | `db.checkpoint()` → boolean (folded/deferred) |
+| `sekejap_publish` | `db.publish()` |
+| `sekejap_storage` | `db.storage()` |
+| `sekejap_statement_timeout_ms` | `db.statementTimeoutMs(ms)` |
+| `sekejap_cancel` / `_clear_interrupt` | `db.cancel()` / `db.clearInterrupt()` |
+| `sekejap_subscribe` / `_next_change` / `_unsubscribe` | `db.subscribe()` / `db.nextChange(id, timeoutMs)` / `db.unsubscribe(id)` |
+| `sekejap_open_memory`, `_trim_memory`, `_compact`, `_show` | `Db.openMemory()`, `db.trimMemory()`, `db.compact()`, `db.show()` — all always throw `SekejapError` with `.code === 'Refused'`, by name |
+
+## What was removed from e1's wrapper
+
+e1's `dist/bindings/wrappers/node/` was a napi-rs addon (`src/lib.rs`,
+`Cargo.toml`/`Cargo.lock`, `build.rs`) compiled against the OLD `CoreDB`
+(slug-addressed rows, `nodeCount`/`edgeCount`, a single-string `Db.open`) and
+a prebuilt `sekejap.darwin-arm64.node` binary, plus a TypeScript ORM layer
+(`orm/`, and its build output `dist/`) and Next.js/Express example apps built
+on that ORM. All of it is gone:
+
+- **The napi-rs Rust glue crate** (`src/`, `Cargo.toml`, `Cargo.lock`,
+  `build.rs`) — this wrapper is pure JS over koffi now; there is nothing to
+  compile, so no Rust crate belongs here at all. This is also why `build-node`
+  no longer runs `cargo`/`napi build`.
+- **The committed `.node` binary and `node_modules/`** — a native binary and
+  ~2,000 files of transitively-vendored TypeScript/React tooling had no
+  business in version control; `npm install` fetches the one runtime
+  dependency (`koffi`) and `.gitignore` keeps `node_modules/` out from here on.
+- **`orm/` and its `dist/` build output** — a hand-rolled query builder /
+  React-hooks layer over the old slug API. It does not carry over: this
+  wrapper's job is the one-to-one C ABI mirror above, and a higher-level ORM
+  over the 0.17 shape is a separate, later decision, not part of re-opening
+  the publish channel.
+- **`examples/nextjs/`, `examples/express-server.js`** — both were demos of
+  the ORM layer, not of the C ABI surface. `examples/tour.js` stays,
+  rewritten against the 0.17 API (`db.query()`/`db.get()` already return
+  parsed values, not JSON strings; `_key` is implicit rather than a declared
+  `TEXT PRIMARY KEY` column — see `lang/src/compile/ddl.rs`: names starting
+  with `_` are reserved in `CREATE TABLE`).
+- **`test.cjs`, `test_prepared.cjs`, `bench.cjs`** — kept as a single
+  `test.cjs` (every leg of the common wrapper checklist: open, create,
+  put/get, a parameterized query, scan, prepare+rebind, link+neighbours,
+  tx commit/rollback, count_rows, an error path, close) and a rewritten
+  `bench.cjs` (same shape, `Db.get` instead of a SQL SELECT by `_key`,
+  because `_key` equality now needs a named index like every other Tier-1
+  predicate — QL_CONTRACT §6 — and the point of this bench is the FFI/JSON
+  round trip, not the planner).
+
+## Gaps in the C ABI found
+
+None. Every one of the 59 functions in `dist/ffi/include/sekejap.h` is bound
+and reachable from JS (the four "refused by name" calls are bound too, so
+the refusal surfaces as a named `SekejapError`, never `TypeError: ... is not
+a function`).
+
+## Tests
 
-## License
+```sh
+export SEKEJAP_LIB_DIR=/path/to/libsekejap   # or SEKEJAP_LIB_PATH
+npm install
+npm test
+npm run bench     # optional
+node examples/tour.js
+```
 
-Dual-licensed under **MIT OR Apache-2.0**.
+`test.cjs` runs against the real library — no mocks — and prints one `ok -`
+line per leg.

package/index.d.ts

@@ -1,138 +1,196 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/* auto-generated by NAPI-RS */
-
-/** The library version. */
-export declare function version(): string
-/**
- * An open sekejap database. JS is single-threaded, but we guard with a Mutex so
- * the handle is sound even if shared via worker threads.
- */
-export declare class Db {
-  /** Open (or create) a database at `path`. */
-  static open(path: string): Db
-  /** Run a mutating statement; returns affected rows. */
-  execute(sql: string): number
-  /** Run a SELECT; returns a JSON-array string (caller `JSON.parse`s it). */
-  query(sql: string): string
-  /** Parameterized SELECT ($1, $2, …); `paramsJson` is a JSON array string. */
-  queryParams(sql: string, paramsJson: string): string
-  /**
-   * Parameterized mutating statement ($1, $2, …); `paramsJson` is a JSON array
-   * string. Returns affected rows. The typed layer's update/delete lower here.
-   */
-  executeParams(sql: string, paramsJson: string): number
-  /**
-   * Subscribe to the change feed. `callback` is invoked once per committed
-   * mutation (a transaction fires once, at COMMIT) with a JSON string
-   * `{"collections":[…],"keys":[…],"edge_types":[…]}`. Returns a subscription
-   * id; pass it to [`unwatch`] to stop. The napi ThreadsafeFunction marshals
-   * the call onto the JS event loop, so no manual threading is needed.
-   */
-  watch(callback: (arg: string) => any): number
-  /** Stop a change-feed subscription created by [`watch`]. */
-  unwatch(id: number): void
-  /** Compile a query once for repeated execution — a prepared statement. */
-  prepare(sql: string): PreparedStatement
-  /**
-   * Run a prepared statement, binding `$1`, `$2`, … from a JSON-array string.
-   * Returns a JSON-array string (caller `JSON.parse`s it).
-   */
-  queryPrepared(stmt: PreparedStatement, paramsJson: string): string
-  /** Insert/replace one node by slug with a JSON payload. */
-  put(slug: string, payloadJson: string): void
-  /** Create a plain edge from -> to of the given type. */
-  link(from: string, to: string, edgeType: string): void
-  /** Number of nodes. */
-  nodeCount(): number
-  /** Number of edges. */
-  edgeCount(): number
-  /** Compact: truncate WAL, rewrite payloads/topology, reclaim RAM. */
-  compact(): void
-  /**
-   * Open an existing database in paged mode: identity/topology served from
-   * memory-mapped files — small open time and resident memory at any size.
-   */
-  static openPaged(path: string): Db
-  /** Open an existing database read-only. */
-  static openReadOnly(path: string): Db
-  /** A node's raw JSON payload, or null. */
-  get(slug: string): string | null
-  /** True if the node exists. */
-  contains(slug: string): boolean
-  /** Delete a node (and its edges). */
-  remove(slug: string): void
-  /**
-   * Store many nodes in one batch (single disk sync).
-   * `pairsJson` is a JSON array of `[slug, payloadJson]` pairs.
-   */
-  putMany(pairsJson: string): number
-  /** Begin a bulk-load scope (defer the per-write disk sync). Pair with `endBulk`. */
-  beginBulk(): void
-  /** End a bulk-load scope: one disk sync for the whole batch. */
-  endBulk(): void
-  /** Store an embedding under a named field of a node. */
-  putVector(slug: string, field: string, data: Array<number>): void
-  /** The stored embedding for a node's field, or null. */
-  getVector(slug: string, field: string): Array<number> | null
-  /** Create an edge with JSON attributes (primitives ride fast columns). */
-  linkMeta(from: string, to: string, edgeType: string, metaJson: string): void
-  /**
-   * Create many edges in one batch (single disk sync).
-   * `edgesJson` is a JSON array of `[from, to, edgeType]` triples.
-   */
-  linkMany(edgesJson: string): void
-  /** Remove a directed edge. */
-  unlink(from: string, to: string, edgeType: string): void
-  /**
-   * Remove edges matching attribute equality conditions (`propsJson` is a
-   * JSON object). Returns how many were removed.
-   */
-  unlinkWhere(from: string, to: string, edgeType: string, propsJson: string): number
-  /**
-   * Update attributes on matching edges: `propsJson` selects, `setsJson`
-   * assigns. Returns how many were updated.
-   */
-  updateEdge(from: string, to: string, edgeType: string, propsJson: string, setsJson: string): number
-  /**
-   * Edges leaving a node, as a JSON-array string of
-   * `{from, to, type, meta}` objects.
-   */
-  edgesFrom(slug: string): string
-  /** Edges arriving at a node, same shape as `edgesFrom`. */
-  edgesTo(slug: string): string
-  /** Edges from one collection to another, same shape as `edgesFrom`. */
-  edgesBetween(fromCollection: string, toCollection: string): string
-  /** All collection names. */
-  collectionNames(): Array<string>
-  /** Every node slug. */
-  allSlugs(): Array<string>
-  /** DDL string for a collection schema, or null. */
-  schemaDdl(collection: string): string | null
-  /**
-   * Ranked text search over a BM25-indexed field: JSON-array string of
-   * `[slug, score]` pairs, best first.
-   */
-  bm25Search(field: string, query: string, topK: number): string
-  /**
-   * The query plan for a statement, as a JSON-array string (one step per
-   * element). `analyze = true` also executes it and adds per-step timings.
-   */
-  explain(sql: string, analyze?: boolean | undefined | null): string
-  /** Run a SHOW statement (`SHOW TABLES`, `SHOW EDGES`, …); JSON-array string. */
-  show(sql: string): string
-  /** Shrink resident memory to the live working set (never drops indexes). */
-  trimMemory(): void
-  /** Per-structure resident-memory estimate, as a JSON object string. */
-  memoryReport(): string
-  /** Override HNSW search breadth (`efSearch`); null restores the default. */
-  setHnswEfSearch(ef?: number | undefined | null): void
-  /**
-   * Close the database and release its lock. Further calls error (or no-op
-   * for count/list getters). Safe to call twice.
-   */
-  close(): void
+// TypeScript definitions for the sekejap Node.js wrapper (over libsekejap's C ABI).
+// See docs/dist/C_ABI.md for the contract this file mirrors.
+
+export type SekejapStatusName =
+  | 'Ok'
+  | 'Refused'
+  | 'Corrupt'
+  | 'Unsupported'
+  | 'Io'
+  | 'Invalid'
+  | 'Busy'
+  | 'UnknownRow'
+  | 'Unknown';
+
+export const SekejapStatus: {
+  readonly Ok: 0;
+  readonly Refused: 1;
+  readonly Corrupt: 2;
+  readonly Unsupported: 3;
+  readonly Io: 4;
+  readonly Invalid: 5;
+  readonly Busy: 6;
+  readonly UnknownRow: 7;
+  readonly Unknown: 8;
+};
+
+export const SekejapDirection: {
+  readonly Outgoing: 0;
+  readonly Incoming: 1;
+  readonly Both: 2;
+};
+
+export type Direction = 'outgoing' | 'incoming' | 'both' | 0 | 1 | 2;
+
+export class SekejapError extends Error {
+  code: SekejapStatusName;
+  status: number;
+}
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type Document = { _key?: string; [field: string]: JsonValue | undefined };
+
+export type FieldKind = 'text' | 'int' | 'real' | 'bool' | 'json' | 'geo' | 'point' | 'vector';
+
+export interface FieldDecl {
+  name: string;
+  kind: FieldKind;
+  dimension?: number;
+}
+
+export interface IndexDecl {
+  name: string;
+  field: string;
+  family: 'scalar' | 'text' | 'exact_vector' | 'quantized_vector' | 'spatial_point' | 'spatial_geometry';
+  unique: boolean;
+  ready: boolean;
+}
+
+export interface CollectionDescriptor {
+  name: string;
+  timestamps: boolean;
+  rows: number | null;
+  fields: Array<FieldDecl & { declared: string | null; primary_key: boolean }>;
+  indexes: IndexDecl[];
+}
+
+export interface Neighbour {
+  collection: string;
+  key: string;
+  document: Document;
+}
+
+export interface StoreConfig {
+  budgetBytes?: number;
+  io?: 'buffered' | 'direct';
+  sync?: 'full' | 'normal' | 'off';
+}
+
+export interface Storage {
+  dataBytes: number;
+  walBytes: number;
+  totalBytes: number;
 }
-/** A prepared (compiled) query — from `Db.prepare`, run with `Db.queryPrepared`. */
-export declare class PreparedStatement { }
+
+export interface ChangeEvent {
+  sequence: number;
+  collections: string[];
+  edge_types: string[];
+  keys: Array<{ collection: string; key: string; kind: 'put' | 'delete' }>;
+  keys_total: number;
+  keys_truncated: boolean;
+  unnamed_writes: number;
+  rows_affected: number;
+}
+
+export class Scan {
+  next(): JsonValue[] | null;
+  close(): void;
+  rows(): Generator<JsonValue, void, void>;
+  [Symbol.iterator](): Generator<JsonValue[], void, void>;
+}
+
+export class Statement {
+  query(params?: JsonValue): Document[];
+  execute(params?: JsonValue): number;
+  rebindable(): boolean | null;
+  close(): void;
+}
+
+export class Tx {
+  put(collection: string, key: string, doc: Document): void;
+  delete(collection: string, key: string): boolean;
+  link(fromCollection: string, fromKey: string, edgeType: string, toCollection: string, toKey: string): void;
+  execute(sql: string, params?: JsonValue): number;
+  commit(): void;
+  rollback(): void;
+}
+
+export class Db {
+  static open(path: string): Db;
+  static openWithConfig(path: string, config?: StoreConfig): Db;
+  static openService(path: string): Db;
+  /** REFUSED by name: sekejap has no in-memory store. Always throws. */
+  static openMemory(): never;
+
+  close(): void;
+
+  put(collection: string, key: string, doc: Document): void;
+  putMany(collection: string, rows: Array<{ key: string; doc: Document }>): number;
+  get(collection: string, key: string): Document | null;
+  exists(collection: string, key: string): boolean;
+  delete(collection: string, key: string): boolean;
+  scan(collection: string, pageRows?: number): Scan;
+
+  execute(sql: string, params?: JsonValue): number;
+  query(sql: string, params?: JsonValue): Document[];
+  explain(sql: string, params?: JsonValue): string;
+  prepare(sql: string): Statement;
+  stream(sql: string, params?: JsonValue, pageRows?: number): Scan;
+
+  link(fromCollection: string, fromKey: string, edgeType: string, toCollection: string, toKey: string): void;
+  linkWith(
+    fromCollection: string,
+    fromKey: string,
+    edgeType: string,
+    toCollection: string,
+    toKey: string,
+    properties: JsonValue
+  ): void;
+  unlink(fromCollection: string, fromKey: string, edgeType: string, toCollection: string, toKey: string): boolean;
+  neighbours(
+    collection: string,
+    key: string,
+    edgeType?: string | null,
+    direction?: Direction,
+    limit?: number
+  ): Neighbour[];
+
+  createCollection(name: string, fields: FieldDecl[]): boolean;
+  dropCollection(name: string): boolean;
+  collections(): string[];
+  describe(collection: string): CollectionDescriptor | null;
+  countRows(collection: string): number;
+  scanCountRows(collection: string): number;
+  scanCountEdges(): number;
+
+  transaction(): Tx;
+
+  checkpoint(): boolean;
+  publish(): void;
+  storage(): Storage;
+
+  statementTimeoutMs(milliseconds: number): void;
+  cancel(): void;
+  clearInterrupt(): boolean;
+  subscribe(): number;
+  nextChange(subscriptionId: number, timeoutMs?: number): ChangeEvent | null;
+  unsubscribe(subscriptionId: number): boolean;
+
+  /** REFUSED: no proportional-to-rows memory to trim. Always throws. */
+  trimMemory(): never;
+  /** REFUSED: no payload-rewriting compaction. Always throws; use checkpoint(). */
+  compact(): never;
+  /** REFUSED: SHOW has no Tier-1 spelling. Always throws; use collections()/describe(). */
+  show(statement?: string | null): never;
+}
+
+export function version(): string;
+export function formatVersion(): number;