@romedb/node 0.2.12 → 0.2.14

package/README.md

@@ -1,170 +1,547 @@
-# RomeDB Node.js / TypeScript client
+# RomeDB for Node.js
 
-This package provides a native N-API addon backed by the RomeDB Rust frontend. It does not expose the raw Turso connection. Linux x64 prebuilds are distributed in the GitHub release bundle. Node 22 and 24 are the tested runtime majors; other operating systems and architectures are outside this release. See [deployment](../../docs/deployment.md) for the single-owner process contract.
+RomeDB is an embedded database. You query it with RomeQL, a document query
+language that also accepts SQL. This package has two parts:
 
-Install it from npm:
+- A native addon that runs RomeDB inside your Node.js process. It is built for
+  Linux x64 and needs Node.js 22 or later. Node 22 and 24 are the tested versions.
+- A client that connects to `romedb serve` or RomeDB Cloud by URL. It uses only Web
+  APIs, so it also runs in Cloudflare Workers and in browsers.
+
+Other operating systems and architectures are outside this release. The addon does
+not expose the raw Turso connection. One process owns a database file at a time.
+The [deployment contract](https://github.com/romedb/romedb/blob/main/romedb/docs/deployment.md) describes this rule.
+
+## Install
 
 ```sh
 npm install @romedb/node
 ```
 
-From 0.2.12 each GitHub release also has the package as its own asset, so a
-project can depend on it by URL:
+Each release publishes its Node package asset to npm unchanged. The first npm
+version, 0.2.12, differs from its asset only in `package.json` and this README. A
+project can also depend on the asset of a GitHub release by URL:
 
 ```sh
-pnpm add https://github.com/romedb/romedb/releases/download/romedb-v0.2.12/romedb-node-0.2.12.tgz
+pnpm add https://github.com/romedb/romedb/releases/download/romedb-v0.2.14/romedb-node-0.2.14.tgz
 ```
 
-Use this package in your Node.js backend. A browser UI calls your backend API;
-RomeDB runs inside the server process and stores the database there. For request
-handlers, prefer [AsyncDatabase](#asynchronous-database) to keep database work off
-the main JavaScript thread. The synchronous Database API remains useful for
-scripts and other blocking workflows. Browser/WASM support is not part of V2.
-
-From the repository root, install the declaration checker and run the scoped checks:
+## A first database
 
-```sh
-pnpm --dir romedb/bindings/node install --ignore-scripts
-romedb/scripts/check.sh
+```js
+const { Database, Record } = require('@romedb/node');
+const rql = new Database('app.romedb');
+try {
+  // The first document write creates the posts collection.
+  rql.execute('INSERT INTO posts DOCUMENT $doc', {
+    $doc: { id: new Record('posts', 'p1'), title: 'Hello', visits: 1n },
+  });
+  rql.execute('UPDATE posts:p1 MERGE {visits: 2}');
+  const [post] = rql.exactlyOne('SELECT * FROM posts:p1');
+  console.log(post.title, post.visits); // Hello 2n
+} finally {
+  rql.close();
+}
 ```
 
-Use the repository's documented Rust environment when its temporary toolchain is needed. `check-node.sh` builds the addon, copies it to the ignored `romedb.node` path, runs Node tests, and type-checks declarations. There are no npm runtime dependencies. TypeScript 5.8.3 is pinned only for declaration checks.
+`posts:p1` is a record ID: the collection `posts` and the key `p1`. In
+JavaScript, `new Record('posts', 'p1')` is the same ID. `$doc` is a parameter, so
+the values never become part of the statement text. Integer results are always
+`bigint`.
+
+Use this package in your Node.js backend. A browser calls your backend API, and
+RomeDB runs and stores the database inside the server process. For request
+handlers, use [AsyncDatabase](#asynchronous-database) or
+[openEmbedded](#embedded-client), which keep database work off the main JavaScript
+thread. The synchronous `Database` suits scripts and other blocking work.
+
+`Database` and `AsyncDatabase` open MVCC files and WAL files, and they create new
+files in WAL mode. `openEmbedded`, `romedb serve` and RomeDB Cloud use only MVCC
+files. To use a WAL file with them, convert it with `romedb migrate-to-mvcc`, or
+create the file with `openEmbedded` from the start.
+
+## RomeQL at a glance
+
+| Statement | What it does |
+| --- | --- |
+| `INSERT INTO posts {id: posts:hello, title: 'Hello', tags: ['news']}` | Adds a document. If the collection does not exist, the write creates it. |
+| `UPSERT people:alice {name: 'Alice', role: 'editor'}` | Creates the record, or merges these fields into it. |
+| `SELECT * FROM posts:hello` | Reads one record by its ID. |
+| `UPDATE posts:hello MERGE {visits: 2}` | Changes the given fields and keeps the others. |
+| `SELECT id, title FROM posts WHERE array::contains(tags, 'news')` | Finds documents by a value in an array. |
+| `INSERT INTO posts {id: posts:second, title: 'Second', author: people:alice}` | Stores a link to another record. |
+| `SELECT * FROM posts WHERE id = posts:second FETCH author` | Returns the post with the linked `people:alice` document in place of the link. |
+| `DELETE posts:hello` | Deletes one record. `DELETE FROM posts:hello` is the same statement. |
+| `DEFINE FIELD title ON posts TYPE string` | Adds validation. After it, a write with a number in `title` fails with `RDB_VALIDATION`. |
+| `CREATE UNIQUE INDEX posts_title ON posts(title)` | Adds a unique index on a field. |
+| `CREATE TABLE visits(at INTEGER, path TEXT)` | Makes an ordinary SQL table. SQL statements work on it, and collections can join it. |
+
+The [language guide](https://github.com/romedb/romedb/blob/main/romedb/docs/v2.2-language.md) describes the full language. The
+[document SDK guide](https://github.com/romedb/romedb/blob/main/romedb/docs/node-sdk.md) describes the typed `collection(name)`
+helpers.
+
+## Choose an API
+
+| API | Entry | Use it for |
+| --- | --- | --- |
+| `Database` | `@romedb/node` | Scripts and tools. Each call blocks the JavaScript thread. |
+| `AsyncDatabase` | `@romedb/node` | Servers. Queries run on a worker thread, in the order you send them. |
+| `openEmbedded` | `@romedb/node/embedded-client` | A local MVCC file with the same request interface as the URL client: atomic batches, sequences and write recovery. |
+| `connect` | `@romedb/node/client` | A database behind `romedb serve` or RomeDB Cloud. Runs in Node.js, Workers and browsers. |
+
+## Database
+
+### Results
+
+`execute(sql, parameters)` returns an object with these fields:
+
+- `columns`: the column names.
+- `rows`: positional rows of typed values.
+- `affected`: the count of changed rows, as a `bigint`.
+- `transaction`: the transaction state before and after the statement.
+
+`all`, `first` and `exactlyOne` return only rows. `first` returns `undefined` when
+there is no row. `exactlyOne` throws a `RangeError` with the code `RDB_CARDINALITY`
+unless the result has exactly one row. That error has the `transaction` field of
+the statement. The statement already ran, so the helper does not undo writes or
+roll back an outer transaction.
+
+### The connection
+
+`Database` methods are synchronous and block the calling JavaScript thread. Each
+instance owns one frontend connection and the lifetime of its database. You can
+call `close()` more than once. Calls after `close()` fail. Closing during an active
+transaction uses the normal connection-drop behavior of the engine. Do not share
+native handles across workers. Use `AsyncDatabase` to give a dedicated worker its
+own connection.
+
+### Values
+
+| JavaScript | RomeDB |
+| --- | --- |
+| `bigint`, or a `Number` that is a safe integer | int64. Integer results are always `bigint`. |
+| A `Number` with a fraction, and `-0` | binary64, with the exact bits kept |
+| A `Number` that is an unsafe integer | Refused. Use a `bigint`. |
+| `boolean`, `null`, `string` | The same type |
+| Array, plain object | Array, object |
+| `Buffer`, `Uint8Array` | Binary |
+| `Record(table, key)` | A record ID. The key is a string or a `bigint`. `String(record)` gives `table:key`, and `record.equals(other)` compares the table and the key. |
+| `Vector` | A vector of validated native-format bytes. See [typed vectors](#typed-vectors). |
+
+RomeDB never makes a reference from a string. Unsupported JavaScript types,
+non-finite numbers, int64 values out of range and too much nesting fail. The bridge
+reads only the own entries of an object, so a field named like a prototype property
+stays data. Values travel in the transfer-v1 tagged encoding.
+
+Standalone projections such as `SELECT $object AS value` keep the types of
+composite, record, vector and boolean parameters. Typed helper expressions and
+DOCUMENT writes keep them too. Type propagation through other source queries is
+not finished. Prepared statements and streamed results are not available.
+
+### Errors
+
+Engine and frontend failures throw an `Error` with a `code` and a `transaction`
+field. A call on a closed `Database` or `AsyncDatabase`, or on a worker that is
+closing, fails with `RDB_CLOSED`. That error has no `transaction` field, because no
+statement ran. Constructor errors and JavaScript argument errors are ordinary
+errors without these fields. The error contract across clients is not final.
+
+| Code | Meaning |
+| --- | --- |
+| `RDB_BUSY` | Native lock contention. |
+| `RDB_BUSY_SNAPSHOT` | A stale read transaction cannot become a writer. The work needs a fresh transaction. |
+| `RDB_CONSTRAINT` | A native constraint, foreign-key or trigger-raise error, with the engine message. |
+| `RDB_VALIDATION` | Frontend validation of a document failed. |
+| `RDB_CLOSED` | The database or its worker is closed. |
+
+Before you recover from an error, read its `transaction` field. The client does not
+retry by itself. `RDB_CONSTRAINT` also covers some runtime validation failures, and
+it does not tell the rollback scope: ordinary SQL `OR FAIL` can keep earlier rows.
+Apply the conflict policy of the statement when you recover. A test with two
+`Database` instances on one file covers both busy codes. Contention and recovery
+across processes need more qualification.
+
+`isRomeDBError(error)` narrows a caught `unknown` value to the exported
+`RomeDBError` interface. It accepts an `Error` with an `RDB_*` code. It also
+validates the transaction and migration details when they are present. The
+`transaction` field is optional, because closed-handle, worker and queue errors can
+happen before execution. Constructor and argument errors can fail this test.
+
+### Migrations
+
+`migrate(migrations)` takes the complete ordered history as
+`{ version: bigint, name: string, sql: string }` entries. It returns
+`{ alreadyApplied: number, applied: bigint[], transaction }`. The rules of the Rust
+runner apply unchanged. It needs autocommit and compares applied scripts with their
+exact source. It has limits, and it runs all pending scripts atomically. The Node
+client does not read migration folders, so your code supplies the scripts.
+
+| Migration failure | Error and meaning |
+| --- | --- |
+| Script splitting or tokenization | `RDB_SYNTAX`, with the migration version and the byte offset in that script. The plan did not start. |
+| Edited or incomplete applied history | `RDB_VALIDATION`. The message tells whether the version sequence, the name or the exact SQL differs. Restore the original applied scripts before you retry. |
+| Size limit of the input or the stored history | `RDB_LIMIT`. The message names the limit. |
+| Incompatible history schema or invalid stored types | `RDB_STORAGE`. The runner does not repair the history. |
+| A pending statement fails | Usually `RDB_MIGRATION`. `error.migration.version` and `.offset` are `bigint` values, and `.cause.code` and `.cause.message` give the underlying failure. The offset counts UTF-8 bytes in that script. The runner rolls back all pending scripts and their history together. |
+| Cooperative cancellation | `RDB_CANCELLED`. The message of a pending statement keeps its version and offset. Completion can win the race with the abort. |
+| Rollback failure | `RDB_ROLLBACK`. Cleanup did not reach the normal rollback outcome. |
+
+Migration errors keep `code`, `message` and the transaction observations of the
+runner in both clients. The version and the UTF-8 byte offset are in the message.
+There are no separate JavaScript `version` or `offset` properties on the error.
+
+The optional `migration` property has the exported `MigrationFailure` shape. Wrapped
+statement failures have it, interrupted statements included. Plan parsing, history
+comparison and cancellation before execution do not always provide it.
+
+Before you retry, read `error.transaction` and the actual result. A worker
+transport failure (`RDB_WORKER`) has no transaction observation, so it does not tell
+whether accepted migration work committed. JavaScript argument validation can fail
+before the runner starts. Keep applied scripts unchanged, comments and whitespace
+included. After a confirmed failed run, you can correct a pending script that is not
+recorded yet.
+
+### Document import and export
+
+`exportDocuments(table, format = 'json')` returns the versioned typed transfer
+string. `importDocuments(table, input, format = 'json')` returns
+`{ imported: number, transaction }`. The format is `json` or `ndjson`. Imports go
+into an existing collection and keep its validation, indexes and rollback behavior.
+
+These methods hold the whole string in memory and use the transfer limits of the
+frontend. They do not back up the schema, stream data or read or write files. To
+copy a whole database into a file, use [`exportFile`](#copying-a-database-into-a-file).
+Failures use the same code and transaction fields as `execute`. Closed-handle calls
+fail with `RDB_CLOSED` and no transaction field.
+
+## Asynchronous database
 
 ```js
-const { Database, Record } = require('./romedb/bindings/node/index.cjs');
-const db = new Database('application.db');
+const { AsyncDatabase } = require('@romedb/node');
+const rql = await AsyncDatabase.open('app.romedb');
 try {
-  db.execute('CREATE TABLE IF NOT EXISTS posts');
-  db.execute('INSERT INTO posts DOCUMENT $doc', {
-    $doc: { id: new Record('posts', 'p1'), title: 'Hello', visits: 1n }
-  });
-  const row = db.exactlyOne('SELECT * FROM posts WHERE id = $id', {
-    $id: new Record('posts', 'p1')
-  });
-  console.log(row[0]);
+  await rql.execute("UPSERT people:alice {name: 'Alice', active: true}");
+  console.log(await rql.all('SELECT name FROM people WHERE active = true')); // [ [ 'Alice' ] ]
 } finally {
-  db.close();
+  await rql.close();
 }
 ```
 
-`execute` returns columns, positional rows, bigint affected count, and transaction before/after observations. `all`, `first` and `exactlyOne` provide row-cardinality helpers; first returns undefined for no rows and exactlyOne throws unless there is one row. A cardinality mismatch is a `RangeError` with code `FDB_CARDINALITY` and the completed statement's `transaction` observations. The statement has already executed: the helper does not undo writes or roll back an outer transaction. Engine/frontend execution failures throw Error with `code` and `transaction` fields. Public Database/AsyncDatabase operations rejected after close (or while the worker is closing) use `FDB_CLOSED` without a transaction field because no statement was submitted. Constructor and JavaScript argument errors currently use ordinary errors without that envelope; the final cross-client error contract is unfinished.
+`AsyncDatabase` has the methods of `Database` and returns Promises with the same
+values and results. It also has `exportFile(destination, options)`, which copies an
+MVCC database into a new file while queries continue and resolves to `{ bytes }`.
 
-`isRomeDBError(error)` narrows a caught `unknown` value to the exported `RomeDBError` interface. It recognizes Error instances with an `FDB_*` code and validates transaction observations and migration details when present. `transaction` is optional: closed-handle, worker and queue errors can occur before execution. Constructor and argument errors can fail this guard.
+### How it runs
 
+`AsyncDatabase.open()` waits for the native database to open and rejects if it
+fails. One dedicated [Node worker](https://nodejs.org/api/worker_threads.html) owns
+the native connection. Requests run one at a time, in the order you send them.
+Each `AsyncDatabase` instance has its own worker and connection. The database work
+runs off the event loop of the caller. Argument encoding, message copies and result
+decoding still use time and memory in the caller.
 
-`Database` methods are synchronous and block the calling JavaScript thread. Each instance owns one frontend connection and its database lifetime. Close is idempotent; calls after close fail. Closing an active transaction uses the engine's normal connection-drop behavior. Do not share native handles across workers; use AsyncDatabase to own a separate native connection on a dedicated worker. AsyncDatabase exposes cooperative connection interruption and AbortSignal cancellation for queries, profiling, integrity audits, batches, document transfers and migrations. See [operation cancellation](#operation-abortsignal-cancellation) for signatures and outcome handling.
+### Queue and closing
 
-Values use the transfer-v1 tagged encoding internally. Integer results are always bigint. Safe integer Number inputs become int64; unsafe integer Numbers are rejected, requiring bigint. Fractional Numbers and negative zero retain their binary64 bits. Booleans/nulls/strings, arrays and plain objects map explicitly. Buffer/Uint8Array map to binary; Record takes a table plus string/bigint key, and Vector takes validated native-format bytes. References are never inferred from strings. Unsupported JavaScript types, non-finite numbers, out-of-range int64 values and excessive nesting fail. The bridge uses own object entries and safe object construction, preserving prototype-looking string fields as data.
+The queue accepts 256 outstanding operations and 128 MiB of encoded argument
+strings, the active operation included. A request over these limits rejects with
+`RDB_LIMIT` before it is sent. These limits do not bound total memory or query time.
 
-The current frontend query subset remains in force. Standalone SELECT projections such as `SELECT $object AS value` now preserve composite/record/vector/boolean parameters, as do typed helper expressions and DOCUMENT writes. Broader source-query type propagation remains unfinished. Full alias/type propagation, prepared statements, streaming, async cancellation/lifecycle qualification, packaging and release qualification remain work for V1. This package is private and has not been published.
+`close()` stops new requests, runs the requests already accepted, closes the native
+connection and waits for the worker to exit. Repeated `close()` calls share the same
+Promise. Closing during an active transaction rolls it back, through the native
+drop behavior that the reopen tests cover. You must await `close()` to release the
+worker. There is no automatic idle shutdown and no force-termination API.
 
+### Transactions and errors
 
-`migrate(migrations)` accepts the complete ordered history with `{ version: bigint, name: string, sql: string }` entries. It returns `{ alreadyApplied: number, applied: bigint[], transaction }`. The Rust runner's autocommit requirement, exact-source checks, limits and atomic pending-run behavior apply unchanged. The Node client does not read migration directories; application code supplies the scripts.
+A query error rejects only its own Promise. Later queued requests still run. An
+explicit transaction belongs to the whole connection, not to one caller or one
+Promise chain. Your application must decide who owns a transaction, and it must
+await each step before it sends dependent work. The API has no transaction callback
+that isolates callers.
 
-Migration errors retain `code`, `message` and the runner's transaction observations in both clients. Version and UTF-8 byte-offset context appears in the message; there are currently no separate JavaScript `version` or `offset` error properties.
+An unexpected worker error or exit rejects every outstanding request. Recovery
+after a worker crash, accounting of native memory, more cancellation tests and
+long-running lifecycle stress are still release gates.
 
-| Migration failure | Error and interpretation |
-|---|---|
-| Script splitting/tokenization | `FDB_SYNTAX`, with migration version and byte offset within that script; the plan has not begun executing. |
-| Edited or incomplete applied history | `FDB_VALIDATION`; a mismatch message distinguishes the version sequence, name or exact SQL source. Restore the original applied prefix before retrying. |
-| Input or stored-history size limit | `FDB_LIMIT`; inspect the message to identify the rejected limit. |
-| Incompatible ledger schema or invalid stored types | `FDB_STORAGE`; the runner does not repair the ledger. |
-| Pending statement failure | Usually `FDB_MIGRATION`, with `error.migration.version` and `.offset` as bigint values and `.cause.code`/`.message` identifying the underlying failure. The offset counts UTF-8 bytes within that script. The runner attempts to roll back all pending scripts and history together. |
-| Cooperative cancellation | `FDB_CANCELLED`; a pending statement's version and offset remain in its message. Completion can win the abort race. |
-| Rollback failure | `FDB_ROLLBACK`; cleanup did not establish the normal rollback outcome. |
+### Interrupting a statement
 
-The optional `migration` property has the exported `MigrationFailure` shape. It is present for wrapped statement failures, including interrupted statements; plan parsing, history checks and pre-execution cancellation need not provide it.
+`interrupt()` asks the engine to stop the active statement. It runs at once and does
+not wait in the worker queue. It returns `false` after native close, and `true` while
+the connection is live. `true` does not confirm that the statement stopped.
 
-Inspect `error.transaction` and the actual result before retrying. A worker transport failure (`FDB_WORKER`) has no transaction observation and does not establish whether accepted migration work committed. JavaScript argument validation may fail before reaching the runner. Keep applied scripts unchanged, including comments and whitespace; correcting an unrecorded pending script is supported after a confirmed failed run.
+A cancelled `execute` rejects with `RDB_CANCELLED` and the observed transaction
+state, and the worker can run later operations. The interruption applies to the
+whole connection: it does not target one Promise and does not remove queued
+requests. Stop repeated interrupt requests before you use the connection again.
+Parsing, work outside the engine and a running bundled function do not stop by
+interruption, and there is no hard deadline.
 
-`exportDocuments(table, format = 'json')` returns the versioned typed transfer string. `importDocuments(table, input, format = 'json')` returns `{ imported: number, transaction }`. Format is explicitly `json` or `ndjson`; imports target an existing collection and preserve validation, indexes and rollback behavior. These methods materialize strings and use the frontend transfer limits. They do not provide schema backups, streaming or implicit file I/O. Migration/import/export failures use the same code and transaction envelope as execute; parameter validation retains the limitations above; closed-handle operations use `FDB_CLOSED` without transaction observations.
+The addon keeps a process-local registry of weak interrupt handles and removes an
+entry on native close or drop. No raw engine pointer crosses into JavaScript.
 
+### Worker failures
 
-## Asynchronous database
+A fatal worker transport error uses `RDB_WORKER`, keeps the first cause and rejects
+every outstanding request. It has no transaction observation: a missing response
+does not tell whether an accepted write committed. Later requests reject with the
+same failure. Do not retry a write with an unknown outcome automatically.
 
-```js
-const { AsyncDatabase } = require('./romedb/bindings/node/index.cjs');
-const db = await AsyncDatabase.open('application.db');
-try {
-  const rows = await db.all('SELECT name FROM accounts');
-  console.log(rows);
-} finally {
-  await db.close();
-}
-```
+After such a failure, `close()` waits for the worker to exit. If the failure happens
+during a `close()` that is already running, that `close()` rejects after cleanup
+ends. When a message cannot be deserialized, the client asks for a graceful native
+close through the remaining channel. If that send fails too, cleanup terminates the
+worker. This fallback is separate from query interruption, and it does not prove
+database recovery or the outcome of a write.
 
-AsyncDatabase provides Promise-returning execute/all/first/exactlyOne, migrate, importDocuments and exportDocuments methods with the same value and result shapes. Opening waits for native initialization and rejects on failure. One dedicated [Node worker](https://nodejs.org/api/worker_threads.html) owns the native connection; submissions execute sequentially in send order. Separate AsyncDatabase instances have separate workers and connections. Native database execution occurs off the calling event loop; argument encoding, message copying and result decoding still consume time and memory on the caller.
+Isolated fault-injection tests cover the state changes of the worker transport.
+Native crashes, interrupted commit or recovery and the resources of a forced
+termination need separate release qualification.
 
-The initial queue permits 256 outstanding operations and 128 MiB of encoded argument strings, including the active operation. Excess requests reject with FDB_LIMIT before submission. These are queue limits, not total-memory or query-time guarantees. Close stops new submissions, drains previously accepted operations, closes the native connection and waits for worker exit. Repeated close calls share the same Promise. Closing an active transaction uses native rollback-on-drop behavior, covered by reopen tests. Applications must await close to release the worker; no automatic idle shutdown or force-termination API is provided.
+### Script batches
 
-Query errors reject their own promises without stopping later queued requests. An explicit transaction belongs to the whole connection, not to an individual caller or Promise chain. Applications must coordinate transaction ownership and await/check steps before submitting dependent work. The current API does not provide transaction callback isolation. Unexpected worker errors/exits reject outstanding requests; deterministic worker-crash recovery, native-memory accounting, broader cancellation qualification and long-running lifecycle stress remain release gates.
+`executeBatch(script)` runs a semicolon-separated script and returns one entry per
+statement. `AsyncDatabase` sends the whole batch as one worker operation. Each entry
+is one of these:
 
+- `{ offset, transaction, result }`, where `result` has columns, typed positional
+  rows and a `bigint` affected count.
+- `{ offset, transaction, error: { code, message } }`.
 
-`asyncDb.interrupt()` synchronously requests interruption of the active engine statement without entering the blocked worker queue. It returns false after native close, and otherwise true to indicate a live connection; true does not confirm interruption. The addon uses a process-local registry of weak interrupt handles and removes entries on native close/drop. No raw engine pointer crosses the JavaScript boundary. A cancelled execute rejects with FDB_CANCELLED and observed transaction state, and the worker can run subsequent operations. This is connection-wide, best-effort interruption: it neither targets a particular Promise nor removes queued requests. Coordinate submissions and stop repeated interrupt requests before reusing the connection. Parsing, frontend-only work and a running bundled function are outside direct engine interruption; no hard deadline is promised.
+Offsets are UTF-8 byte positions. A statement error is returned as an entry and
+stops the batch, so you must read every entry. Lexical errors and other errors
+before execution throw or reject in the normal error format, and no statement runs.
 
+Batches use the same semicolon-aware parser as Rust and the CLI, trigger bodies and
+multiline documents included. A batch has no implicit transaction and takes no
+parameters. Put explicit transaction statements in the script, and read the
+transaction state of the last entry after a failure. Each result is encoded before
+the next statement runs, so a result that cannot be encoded also stops the batch.
+Neither a stop nor an encoding error undoes earlier work. Results stay in memory,
+and limits for scripts and result memory need more qualification.
 
-Fatal worker transport errors use FDB_WORKER, retain the first cause, and reject every outstanding request. They do not carry a transaction observation: a missing response does not establish whether an accepted write committed. Later requests reject with the same failure. After such a failure, close waits for worker exit; if a failure occurs during an already-running close, that close rejects only after cleanup finishes. A message-deserialization failure requests graceful native close through the remaining send channel. If that send itself fails, cleanup falls back to worker termination. This fatal-channel fallback is separate from cooperative query interruption and does not prove database recovery or write disposition. Do not automatically retry unknown-outcome writes.
+### Cancellation with AbortSignal
 
-Worker-transport state transitions have deterministic fault-injection coverage in an isolated test process. Native crashes, interrupted commit/recovery and forced-termination resource behavior still require separate release qualification.
+Pass `{ signal: controller.signal }` in the options position. If you skip an earlier
+optional argument, pass `undefined` in its place.
 
+| Async method | Call with options |
+| --- | --- |
+| Queries and row helpers | `execute(sql, parameters, options)`, `all(sql, parameters, options)`, `first(sql, parameters, options)`, `exactlyOne(sql, parameters, options)` |
+| Query profiling | `profileSelect(sql, parameters, options)` |
+| Collection integrity | `checkCollectionIntegrity(table, limits, options)` |
+| Script batch | `executeBatch(script, options)` |
+| Document export | `exportDocuments(table, format, options)` |
+| Document import | `importDocuments(table, input, format, options)` |
+| Database file copy | `exportFile(destination, options)` |
+| Migrations | `migrate(plan, options)` |
 
-`executeBatch(script)` returns an array of `{ offset, transaction, result }` or `{ offset, transaction, error: { code, message } }` entries. AsyncDatabase returns a Promise for that array and submits the entire batch as one worker operation. Offsets are UTF-8 byte positions. Successful result objects contain columns, typed positional rows and a bigint affected count. Statement errors are returned as entries and stop the batch; callers must inspect them. Lexical/pre-execution errors throw or reject through the normal error envelope and execute no statements.
+For example, `await rql.exportDocuments('posts', undefined, { signal })` uses the
+default JSON format. `open()` and `close()` do not take a signal.
+
+Each signalled request gets its own native cancellation token. A queued request that
+is aborted runs no SQL when its turn comes. Accepted requests keep their queue order
+and their queue slot until the worker responds. Cancellation does not close the
+database or cancel other requests.
+
+Active cancellation is cooperative: the engine reacts at its progress points.
+Completion can win the race with the abort, so use the returned result or error. An
+abort alone does not prove a rollback. A cancelled query rejects with
+`RDB_CANCELLED` and the usual transaction fields, not with `signal.reason`. There is
+no fixed cancellation delay for compilation or work outside the engine. The pinned
+defect in trigger interruption is still a release gate.
+
+Listeners and token entries are released on a response, a send failure or a worker
+failure. Tokens do not keep connections, so a late abort cannot reach another
+request. The process-local registry allows 16,384 outstanding signalled operations
+across all clients, in addition to the queue limits of each client. Requests without
+a signal use the normal path. Synchronous `Database` methods do not take signals.
+
+How each operation ends after cancellation:
+
+- `executeBatch`: a request aborted before it starts rejects before the script is
+  split. Cancellation during the batch appears as a final `RDB_CANCELLED` entry with
+  the byte offset and transaction state of that statement. Earlier entries stay,
+  and later statements do not run. Earlier writes keep their effects, and an explicit
+  transaction can stay active. Coordinate any rollback yourself, and use a fresh
+  signal for a retry.
+- `importDocuments` and `exportDocuments`: rejects with `RDB_CANCELLED` and
+  transaction fields. An import rolls back its own work and keeps earlier outer work.
+  An export returns a complete string or an error.
+- `migrate`: interrupted statements report `RDB_CANCELLED`, and the message keeps the
+  migration version and byte offset. All pending scripts and history rows roll back
+  together, and applied migrations stay. A request aborted before it starts does no
+  database work, but JavaScript argument validation still runs.
+- `close()`: runs the accepted requests and does not abort them. Signals can still
+  cancel accepted operations while `close()` waits. Later requests reject with
+  `RDB_CLOSED`.
+
+Parsing, conversion and serialization have no fixed cancellation delay. In every
+case, a successful completion can win the race, so read the outcome before a retry.
+
+### Timeouts
+
+Async operations that take options also take `timeoutMs`, an integer from 0 to
+4,294,967,295:
 
-Batches use the same semicolon-aware parser as Rust and the CLI, including trigger bodies and multiline documents. They have no implicit transaction and accept no parameter map. Explicit transaction statements belong in the script; inspect the last entry's transaction state on failure. Result encoding is performed before the next statement, so an unrepresentable result also stops the batch. Neither stopping nor an encoding error undoes previously executed work. Results remain materialized, and scripts/result-memory limits still need broader qualification.
+```js
+await rql.execute('SELECT * FROM posts', {}, { timeoutMs: 500 });
+```
 
+The deadline starts when the request token is made: after the parameters are
+encoded and before the request enters the worker queue. Time in the queue counts,
+and 0 has already expired. An expired request returns `RDB_CANCELLED` through the
+cancellation path, with the normal rollback and transaction fields. You can pass
+`signal` with it. An expired request does not cancel later requests. `close()` has no
+timeout.
 
-Native lock contention uses FDB_BUSY; a stale read transaction that cannot become a writer uses FDB_BUSY_SNAPSHOT. These replace the former FDB_ENGINE classification for those native variants. Inspect the error's transaction observation before recovery; stale-snapshot work needs a fresh transaction. The client performs no automatic retries. A real shared-file test covers both codes and committed-value preservation through two Database instances. Broader cross-process contention/recovery qualification remains pending.
+This is not a hard deadline for the Promise. The engine notices the deadline at its
+progress points. Parsing, work outside the engine, cleanup and the response can take
+longer, and completion can win the race. Synchronous clients do not have this
+option.
 
+## Result and memory limits
 
-Native constraint, foreign-key and trigger-raise errors use FDB_CONSTRAINT and retain their engine message. Frontend candidate validation remains FDB_VALIDATION. The native category includes some runtime validation failures and does not specify a constraint subtype or rollback scope: ordinary SQL OR FAIL can retain earlier rows. Inspect transaction observations and apply the statement's conflict policy when recovering.
+### Bounded SELECT results
 
+Both clients have `selectWithLimits(sql, limits, parameters?)` and
+`profileSelectWithLimits(sql, limits, parameters?)`. The `AsyncDatabase` versions
+take `{ signal }` as a fourth argument. Both limits are required, nonnegative
+`bigint` values:
 
-## Local package smoke
+```js
+const result = await rql.selectWithLimits(
+  'SELECT title FROM posts LIMIT 100',
+  { maxRows: 100n, maxPayloadBytes: 65536n },
+);
+```
 
-Normal npm packing first checks that the native addon loads; a missing or incompatible build fails before creating the archive. The npm file allowlist includes the native addon, synchronous/worker JavaScript entry points, declarations, README, MIT license and third-party notices. Build the current platform's addon, then verify the actual tarball from the repository root:
+If the result passes a limit, the call fails with `RDB_LIMIT` and the transaction
+fields, and it returns no partial rows or metrics. An empty result still counts its
+column names. These calls accept one SQL SELECT, one-hop FETCH included. Fetched
+documents and their duplicates count toward the payload limit, and missing targets
+count as nulls. A found target is counted with its output multiplicity before the
+cache keeps it, so the call can fail early. Reference placeholders do not count.
+`execute` and `profileSelect` keep their own result policy.
+
+Payload bytes count UTF-8 column names, strings, object keys, record table names and
+string keys. Integer keys and numbers count eight bytes, `null` and booleans one byte,
+and binary values and encoded vectors their byte length. Objects and arrays count
+the sum of their contents. These are budgets for the logical result. They do not
+count containers, allocator overhead, temporary decoding, copies in Node transport
+or engine working memory. FETCH keeps its own reference and tagged-JSON limits, and
+the final payload limit does not cover temporary references or the target cache.
+These limits are not process memory limits or deadlines.
 
-```sh
-romedb/scripts/check-node.sh
-node romedb/scripts/check-node-package.cjs
+### Limits on write results
+
+Both clients have `writeWithResultLimits(sql, limits, parameters?)`. The
+`AsyncDatabase` version takes `{ signal }` as a fourth argument. It uses the same
+required `bigint` fields `maxRows` and `maxPayloadBytes`:
+
+```js
+const result = await rql.writeWithResultLimits(
+  'UPDATE posts SET published = true RETURNING id',
+  { maxRows: 100n, maxPayloadBytes: 65536n },
+);
+```
+
+Supported SQL writes and document writes run in an operation savepoint. Native SQL
+counts each result row before the frontend keeps it. Collection SQL and document
+RETURNING count each projected row before they keep it. Native destinations with
+logical sources also count rows during the final collection. In all cases, a write
+over a limit returns `RDB_LIMIT` and rolls back, index and trigger effects included.
+
+This policy accepts or refuses a result. It does not bound engine RETURNING buffers,
+write candidates, document snapshots or the working memory of one projection.
+Transaction control, DDL, reads and multiple statements are refused. A write without
+RETURNING can succeed with limits of zero, because affected rows are not returned
+rows. An empty RETURNING still counts its column names. Cooperative cancellation
+uses the usual error fields and the savepoint recovery, and the count of completed
+results has no fixed cancellation delay.
+
+### Collection write buffers
+
+Both clients take an optional second argument when they open:
+
+```js
+const options = { writeBufferLimits: { maxRows: 10_000n, maxPayloadBytes: 64n * 1024n * 1024n } };
+const rql = new Database(':memory:', options);
+const worker = await AsyncDatabase.open(':memory:', options);
 ```
 
-The smoke packs into a temporary directory, verifies the exact file inventory, installs the tarball into a separate consumer with npm offline and lifecycle scripts disabled, and tests public synchronous/worker queries, typed int64/record values, rollback and reopen. Profiling and audit calls cover both clients, lossless bigint counters, exact audit limits, retained active work on limit failure, repeat-call profiling counters and reopened index counts. It also compiles a consumer TypeScript import against the installed declarations, including public profiling/audit types, async results and rejection of numeric audit limits. Temporary artifacts are removed afterward. The TypeScript compiler is a checkout development tool; the installed package has no runtime registry dependencies.
+The limits apply to each write-candidate buffer and each document-snapshot buffer of
+the frontend. If a buffer passes a limit, the operation fails with `RDB_LIMIT` and
+rolls back, and earlier work in the transaction stays. Ordinary reads and the result
+limits above have their own policies. The limits are off by default and cannot
+change while the connection is open. Both fields are required, nonnegative uint64
+`bigint` values. Unknown options and invalid values fail before the database opens.
 
-For an optimized local addon, run `romedb/scripts/check-node.sh --release` before the package smoke. The script uses the pinned workspace release profile and runs the same client/application tests and TypeScript check as the default debug build. It copies the selected artifact into the private package; the subsequent package smoke validates that actual artifact. This option does not build universal prebuilds or publish a package. On Linux, `--release-stripped` additionally runs `strip --strip-debug` on the package copy before the same checks, retaining the full release artifact under Cargo’s target directory for diagnostics. It requires `strip`; other platforms reject this option.
+These are not total memory limits. Native engine buffers, parsing, temporary values
+and overlapping buffers are outside them, and transfer APIs keep their own limits.
+See [result budgets](https://github.com/romedb/romedb/blob/main/romedb/docs/result-budgets.md) for the accounting and the open
+resource gates.
 
-This is a maintainer packaging check, separate from routine CI because the current debug addon is large. The verified local artifact is Linux x64 with Node 24.19.0, not a universal binary. Keep private=true: platform-specific prebuild selection, Node-version/platform coverage, optimized artifact sizing and complete distribution notices remain release work. No package has been published.
+## Profiling and audits
 
-## SELECT profiling
+### SELECT profiling
 
-Both clients provide `profileSelect(sql, parameters?)`; the async version returns a Promise and uses the existing worker queue. It returns `{ result, metrics }`, where `result` has the same typed rows, bigint affected count and transaction observations as `execute`. Every metric is a bigint: `rowsRead`, `rowsWritten`, `fullscanSteps`, `indexSteps`, `vmSteps`, `sortOperations`, `btreeSeeks`, `fetchBatches`, `fetchRowsRead` and `fetchVmSteps`. Native transport encodes counters as decimal strings before converting them to bigint, without a JavaScript Number conversion.
+Both clients have `profileSelect(sql, parameters?)`. It returns `{ result, metrics }`.
+`result` has the same typed rows, `bigint` affected count and transaction fields as
+`execute`.
 
 ```js
-const profile = await asyncDb.profileSelect(
-  'SELECT id FROM posts WHERE author=$author',
-  { $author: new Record('users', 'alice') },
+const profile = await rql.profileSelect(
+  'SELECT id FROM posts WHERE author = $author',
+  { $author: new Record('people', 'alice') },
 );
 console.log(profile.result.rows, profile.metrics.rowsRead);
 ```
 
-The fetch-prefixed counters separately report target SELECT batches, physical row reads and VM instructions (zero without target reads); the other counters cover the primary statement. Deduplicated references share target reads. Fetch profiling uses the ordinary fetch budgets and one atomic snapshot scope; metadata/lowering queries, Rust/JavaScript decoding and transport are excluded. Physical row reads are not logical document counts. Only one SQL SELECT is accepted; writes, multiple statements, EXPLAIN and direct-record shorthand are rejected. Failures throw/reject through the usual error/transaction envelope without partial counters. Connection-wide async interruption and close behavior follow `execute`. Async profiling also accepts an optional third argument `{ signal }` for cooperative request-scoped cancellation; this is not a deadline guarantee.
+Every metric is a `bigint`: `rowsRead`, `rowsWritten`, `fullscanSteps`,
+`indexSteps`, `vmSteps`, `sortOperations`, `btreeSeeks`, `fetchBatches`,
+`fetchRowsRead` and `fetchVmSteps`, and the graph and spatial counters of
+`QueryMetrics`. The addon sends counters as decimal strings, so no JavaScript
+`Number` conversion loses digits.
+
+The `fetch` counters report the target SELECT batches, physical row reads and VM
+instructions of FETCH, and they are zero without target reads. The other counters
+cover the main statement. References that point to the same target share its reads.
+Physical row reads are not logical document counts. Metadata and lowering queries,
+decoding and transport are not counted.
 
-## Collection integrity audit
+`profileSelect` accepts one SQL SELECT. Writes, multiple statements, EXPLAIN and
+direct-record shorthand are refused. A failure throws or rejects with the usual
+error fields and no partial counters. The `AsyncDatabase` version takes
+`{ signal }` as a third argument, which cancels cooperatively and is not a deadline.
 
-`checkCollectionIntegrity(table, limits?)` is available on both clients; AsyncDatabase returns a Promise and runs the audit on its worker. Its optional third argument `{ signal }` requests operation-scoped cancellation using the same token and cleanup contract as query execution. It returns bigint `documents`, `indexes`, `indexEntries`, `encodedBytes`, plus transaction observations. Optional `maxDocuments` and `maxEncodedBytes` limits require nonnegative bigint values fitting uint64. Omitted limits use Rust defaults: 100,000 documents and 64 MiB of encoded ID/document bytes. Zero is valid for checking an empty collection.
+### Collection integrity audit
+
+Both clients have `checkCollectionIntegrity(table, limits?)`. It returns the
+`bigint` counts `documents`, `indexes`, `indexEntries` and `encodedBytes`, and the
+transaction fields:
 
 ```js
-const audit = await asyncDb.checkCollectionIntegrity('posts', {
+const audit = await rql.checkCollectionIntegrity('posts', {
   maxDocuments: 100_000n,
   maxEncodedBytes: 64n * 1024n * 1024n,
 });
 console.log(audit.documents, audit.indexEntries);
 ```
 
-The audit checks typed IDs, validation and index entry consistency in one snapshot, without repairing data. FDB_LIMIT returns no partial report; native errors include transaction observations. Limits do not bound engine allocations or time. It is not physical page/B-tree verification or a complete corruption-recovery tool. Async queue, close and connection-wide interruption behavior are unchanged.
+The optional limits are nonnegative `bigint` values that fit in uint64. Without them,
+the defaults are 100,000 documents and 64 MiB of encoded IDs and documents. Zero is
+valid for an empty collection. The `AsyncDatabase` version takes `{ signal }` as a
+third argument.
+
+The audit tests typed IDs, validation and the consistency of index entries in one
+snapshot, and it repairs nothing. `RDB_LIMIT` returns no partial report. The limits
+do not bound engine memory or time. This is not a test of physical pages or B-trees,
+and it is not a tool to recover from corruption.
 
-## Constructing typed vectors
+## Typed vectors
 
-Vector factories work without opening a database and produce values accepted by either client:
+The vector factories work without a database, and both clients accept their values:
 
 ```js
 const { Vector } = require('@romedb/node');
@@ -176,431 +553,492 @@ const bits = Vector.bit1([1, 0, -1]);
 const sparseEntries = Vector.sparse32Entries(65536, [[0, 1], [65535, -1]]);
 ```
 
-The five dense-input factories accept number arrays (including readonly arrays in TypeScript), Float32Array or Float64Array. Sparse, quantized and bit factories also take dense components. Inputs must contain 1–65,536 finite numbers. float64 retains binary64 inputs; the other factories first convert to float32 and reject overflow to infinity. Quantized and bit conversion are lossy. Inputs are copied, and factories run synchronously even when their results will be used with AsyncDatabase.
-
-`Vector.sparse32Entries(dimensions, entries)` accepts an array of `[index, value]` pairs (readonly tuples are supported by the exported TypeScript `SparseVectorEntry` type). Dimensions must be 1–65,536. Indices must be unique, strictly increasing and in range, including zero-valued entries. Values must be finite and fit float32. Zero entries are omitted after float32 conversion; empty entries create an all-zero vector with the declared dimensions. Input and output storage scale with entry count, with no dense intermediate. Invalid indices throw RangeError; malformed pairs throw TypeError.
+The five dense factories take a number array (a readonly array in TypeScript), a
+`Float32Array` or a `Float64Array` of 1 to 65,536 finite numbers. `float64` keeps
+binary64 values. The other factories first convert to float32 and refuse an overflow
+to infinity. Quantized and bit conversion lose precision. Inputs are copied, and the
+factories run synchronously. The installed-package smoke uses the five dense
+factories and the sparse-entry factory through both clients.
+
+`Vector.sparse32Entries(dimensions, entries)` takes `[index, value]` pairs. The
+exported `SparseVectorEntry` type supports readonly tuples. Dimensions are 1 to
+65,536. Indices must be unique, strictly increasing and in range, zero-valued entries
+included. Values must be finite and fit in float32. Zero entries are left out after
+the float32 conversion, and no entries make an all-zero vector of the given
+dimensions. Memory grows with the count of entries, with no dense copy.
+
+Invalid indices throw a `RangeError`, and malformed pairs throw a `TypeError`. Invalid
+container or component types throw a `TypeError`, and invalid dimensions or a float32
+overflow throw a `RangeError`. Native conversion errors are ordinary errors with no
+transaction fields, because no connection is open. `new Vector(encodedBytes)` keeps
+the encoded-byte path, and binding that value still validates its encoding.
+
+The native adapter uses the Rust value constructors and validates their output.
+JavaScript passes a bounded binary64 buffer, so no JSON number conversion changes a
+value. Tests cover float32 halfway rounding, subnormal underflow and signed zero with
+known IEEE-754 bits. `float64` keeps the smallest positive and negative subnormals, a
+value next to one and the largest finite binary64 value. Quantized conversion can fail
+for finite inputs: the pinned scale calculation overflows for a range from the
+negative to the positive float32 maximum. These errors happen locally and do not
+change an open transaction.
+
+## Embedded client
+
+`@romedb/node/embedded-client` opens a local MVCC file. It has the same request
+methods as the URL client (`info`, `read`, `prepareWrite`, `submit`, `recover` and
+`writeAtomic`) and the same value types. It needs the native addon. CommonJS
+and ESM imports both work.
 
-The native adapter uses the Rust Value constructors and validates conversion output. JavaScript passes a bounded binary64 buffer, preserving floating-point inputs without JSON number conversion. Invalid container/component types throw TypeError; invalid dimensions and float32 overflow throw RangeError. Native conversion/validation failures throw ordinary native errors without transaction observations because construction opens no connection. `new Vector(encodedBytes)` retains its existing encoded-byte path; binding that value still validates the encoding.
+```js
+const { openEmbedded, Record } = require('@romedb/node/embedded-client');
+const rql = await openEmbedded({ path: 'app.romedb', create: true });
+try {
+  await rql.writeAtomic([
+    { sql: "INSERT INTO posts {id: posts:hello, title: 'Hello', visits: 1}" },
+    { sql: 'UPDATE posts:hello MERGE {visits: $visits}', params: { $visits: 2n } },
+  ]);
+  const { results } = await rql.read([
+    { sql: 'SELECT title, visits FROM posts WHERE id = $id', params: { $id: new Record('posts', 'hello') } },
+  ]);
+  console.log(results[0].rows); // [ [ 'Hello', 2n ] ]
+} finally {
+  await rql.close();
+}
+```
 
-The installed-package smoke exercises all five dense-input factories and the sparse-entry factory through both clients and type-checks VectorComponents, readonly numeric arrays and rejection of bigint components.
+### Opening and creating files
 
-Factory precision tests cover float32 halfway rounding, subnormal underflow and signed zero with known IEEE-754 bits. float64 preserves the smallest positive/negative subnormal, an adjacent-to-one value and the largest finite binary64 value. Sparse/quantized/bit factories operate on the narrowed float32 values. Quantized conversion can fail even for finite inputs: the pinned scale calculation overflows for a range spanning negative to positive float32 maximum. Such constructor errors occur locally and do not change an existing database transaction.
+`openEmbedded({ path })` opens an existing regular file with one link. To create a
+new file, pass `create: true`. Creation refuses an existing file and leftover
+journal files. Files use MVCC, the journal mode of `romedb serve` and RomeDB Cloud.
+A file moves between these without conversion and gets the same write conflicts.
 
-## Operation AbortSignal cancellation
+Opening a WAL file fails with `RDB_UNSUPPORTED` and leaves the file unchanged. Stop
+its owner and convert it with `romedb migrate-to-mvcc`. The managed connection turns
+on SQL foreign keys. The legacy APIs keep their own setting.
 
-Pass `{ signal: controller.signal }` in the options position below. Supply `undefined` for an earlier optional argument when using its default.
+### Private files
 
-| Async method | Call with cancellation options |
-|---|---|
-| Query and row helpers | `execute(sql, parameters, options)`, `all(sql, parameters, options)`, `first(sql, parameters, options)`, `exactlyOne(sql, parameters, options)` |
-| Query profiling | `profileSelect(sql, parameters, options)` |
-| Collection integrity | `checkCollectionIntegrity(table, limits, options)` |
-| Script batch | `executeBatch(script, options)` |
-| Document export | `exportDocuments(table, format, options)` |
-| Document import | `importDocuments(table, input, format, options)` |
-| Migrations | `migrate(plan, options)` |
+`create: true` makes the database file with mode 0600. The WAL file (`NAME-wal`) and
+the MVCC log (`STEM.db-log`, which holds row data until a checkpoint) get the
+permissions of the database file, as in SQLite. RomeDB creates them before the
+engine does. On each open, it removes permission bits that the database file does
+not have from existing ones. So every file of a new database is 0600, and a database
+made by 0.2.11 or earlier gets private journal files at its next open.
 
-For example, `await db.exportDocuments('posts', undefined, { signal: controller.signal })` uses the default JSON format. Opening and closing do not accept a signal; close drains accepted work. Batch cancellation can be returned as an error entry in a resolved array, as described below.
+### Open files
 
-`execute(sql, parameters?, { signal }?)`, `all`, `first`, `exactlyOne` and `profileSelect` on AsyncDatabase accept an AbortSignal. Each signalled query receives a separate native cancellation token. An aborted queued request executes no SQL when its turn arrives; accepted requests keep their original queue order and their queue slot until the worker responds. Cancellation does not close the database or cancel neighboring requests.
+One process keeps at most `maxOpen` different files open: 1 to 1024, 16 by default.
+An open over this number fails with `RDB_LIMIT`. Clients of a file that is already
+open do not count again. To keep many databases, such as one per site, open them
+with the same `maxOpen` and close the least recently used one yourself.
 
-Active cancellation is cooperative at engine progress boundaries. Completion can win a race with abort, so use the returned result/error; abort alone does not prove rollback. A cancelled query rejects with `code: 'FDB_CANCELLED'` and the usual transaction observations. `signal.reason` is not substituted for the database report. No fixed cancellation latency is promised for compilation or non-engine work. The pinned trigger-interruption defect remains a release gate.
+`close()` of the last client checkpoints the MVCC log into the database file, so the
+next open has no log to replay. Then it releases the OS lock of the file. Reopening a
+closed file takes about 75 to 90 ms on Linux x64 (release build, 2026-11-02), nearly
+independent of its size. Each open file has its own worker thread, and starting it
+and loading the addon in it takes about 60 ms of that. The engine opens in about
+9 ms, and closing with the checkpoint takes about 10 ms.
 
-Listeners and token registry entries are released on response, send failure or worker failure. Tokens do not retain connections; a late abort cannot target another request. The process-local registry permits up to 16,384 outstanding signalled operations across clients, in addition to each client's existing queue bounds. Unsignalled queries use their existing path. Queries, batches, profiles, audits, transfers and migrations now accept signals; broader cancellation qualification remains open. Sync Database methods are unchanged.
+### Batches and sequences
 
+Clients of the same canonical file in one Node module share one native worker. Each
+batch runs as one worker operation inside a managed transaction. All statements are
+validated before any runs, and user transaction control is refused. A failure or an
+exceeded result or work limit rolls back the whole batch. The `executeBatch`
+behavior of the legacy API does not change.
 
-Async `executeBatch(script, { signal }?)` supports operation-scoped cancellation. A pre-aborted request rejects before script splitting. Once execution starts, cancellation during or between statements appears as the final `FDB_CANCELLED` batch entry with that statement's byte offset and transaction observations; earlier entries are retained and later statements are skipped. Inspect every entry: a resolved batch promise does not imply that every statement succeeded. Earlier successful writes keep their effects, and an explicit transaction may remain active. No implicit rollback or commit is added. Rust visitor work and other non-engine work have no cancellation latency bound. Use a fresh signal for a retry and coordinate any rollback explicitly.
+Sequence conditions cover writes through this shared adapter. Its capabilities
+report `sequenceScope: 'adapter'` and `replayDurability: 'adapter-lifetime'`. Other
+native or legacy handles do not advance its sequence. An application must use one
+managed adapter for each canonical file. To share a file between processes, use the
+service URL.
 
+`info()` also returns `engineVersion`, the RomeDB release of the native engine.
+Database URLs report it from local services 2.7.0 and later and from Cloud. Older
+services do not report it.
 
-Async `importDocuments(table, input, format?, {signal}?)` and `exportDocuments(table, format?, {signal}?)` support operation-scoped cancellation. Aborted requests reject with FDB_CANCELLED and transaction observations. Import uses its existing atomic rollback scope, preserving prior outer work; export returns a complete string or an error. Accepted queued requests retain their place until the worker responds. Parsing, conversion and serialization have no fixed cancellation latency, and completion can win the race. Sync signatures and transfer encodings are unchanged.
+### Write recovery
 
+The adapter keeps 64 exact write receipts in memory. A saved journal can recover a
+write while that adapter stays open. After its last client closes, reopening makes a
+new identity and refuses old requests. After a reopen, reconcile uncertain writes
+from the stored data. Service and Cloud connections recover writes across process
+restarts.
 
-Async `migrate(plan, {signal}?)` supports cooperative cancellation. Interrupted migration statements report FDB_CANCELLED while retaining migration version/byte-offset context in the message and optional migration metadata; its underlying cause code is also FDB_CANCELLED. A request cancelled before execution has no statement metadata. All pending scripts and history rows share one atomic scope and roll back together on failure; previously applied migrations remain intact. A pre-aborted request does no database work, though JavaScript argument validation still runs. Compilation and plan parsing have no fixed cancellation latency, and a successful commit can win the race. Inspect the outcome before retrying.
+### Limits and closing
 
+Each adapter accepts 32 outstanding requests and 2 MiB of queued request bodies, and
+a process has 16 open file adapters by default. The request, result and work limits
+match the common contract. Calls time out after 20 seconds by default and accept a
+`timeoutMs` of 1 to 120,000. Opening also has a deadline. If opening expires, cleanup
+continues until the native startup returns. Filesystem work and native cleanup do
+not stop early.
 
-`close()` drains accepted requests before dropping the worker connection; it does not implicitly abort them. Signals can still cancel accepted operations while close is pending. Later submissions reject with `FDB_CLOSED` and no transaction observations. An existing worker failure retains `FDB_WORKER` precedence. Aborted queued requests retain their queue slots until a response or worker failure. The real-worker close regression verifies that dropping an active outer transaction leaves only committed data after reopening; callers should still explicitly commit or roll back during normal operation.
+`close()` stops requests from that client and cancels its outstanding work. The last
+client runs the remaining worker queue, closes the native handle and waits for the
+worker to exit. Await `close()` of every client to release the file.
 
+### Copying a database into a file
 
-Importing on Node versions below the declared minimum of 22 throws `FDB_RUNTIME_VERSION` before loading native code.
+`exportFile` copies the open database into a new `.romedb` file while reads and
+writes continue. The file is one snapshot, and it opens by itself in `openEmbedded`
+and `romedb serve FILE`.
 
-If the native addon is absent or cannot be loaded, importing the package throws `FDB_NATIVE_LOAD`. The message identifies the current platform, architecture and Node version and points to the source build instructions. The original loader error remains in `error.cause` for diagnosing missing libraries, invalid binaries or other loader failures. This diagnostic does not select, download or rebuild an addon automatically.
+```js
+const { sequence, bytes } = await rql.exportFile('backups/site-2026-11-03.romedb');
+// Or stream the copy, for example as a download. Nothing stays on disk afterwards.
+const { size, body } = await rql.exportFile({ signal });
+```
 
+The file holds every write up to and including `sequence`, and none after it. The
+destination and its `-wal`, `-shm`, `-log`, `-journal` and `.db-log` files must not
+exist, or the call fails with `RDB_ALREADY_EXISTS`. The new file has mode 0600 and
+appears only when it is complete.
 
-The local package smoke also verifies pre-aborted calls for every signalled API, preserved transaction observations, listener disposal and fresh/late-token behavior using the installed package. Its consumer TypeScript check covers all cancellation options. These supplement the real-worker active-cancellation tests in the checkout.
+The streaming form builds its copy in a private folder beside the database file. It
+removes the name of the copy before it returns, so read `body` to the end or cancel
+it. Exports have no deadline unless you pass `timeoutMs`. `signal`, `timeoutMs` and
+`close()` cancel a running export. It then rejects with `RDB_CANCELLED`, unless it
+finished first.
 
-## Dependency declaration inventory
+#### Leaving data out of a copy
 
-From the checkout root, with the pinned Rust toolchain available:
+A whole copy holds everything, including sessions and tokens. Use `emptyTables` when
+someone else gets the file:
 
-```sh
-node romedb/scripts/inventory-node-dependencies.cjs x86_64-unknown-linux-gnu romedb/docs/node-dependencies-linux-x64.json
-node romedb/scripts/inventory-node-dependencies.cjs x86_64-unknown-linux-gnu romedb/docs/node-dependencies-linux-x64.json --check
+```js
+await rql.exportFile('site.romedb', { emptyTables: ['cms_auth_sessions', 'cms_cache'] });
 ```
 
-This offline, locked, package-scoped Cargo query records normal and build dependencies, declared license expressions, the target and the lockfile hash. The checked-in Linux inventory contains 192 package/version entries. `cfg_block` 0.1.1 has no license expression in the query output: its pinned manifest instead declares `license-file = "LICENSE"`. That source file contains an Apache 2.0 notice; the package notice file includes it and the Apache 2.0 text. The inventory retains the absent expression rather than replacing Cargo metadata with an inferred value. Build tools are included; development dependencies are excluded. The inventory is an audit input, not evidence that every listed crate is linked into the addon, a complete component inventory, or a replacement for license texts. Bundled C/C++ sources and other vendored components require separate inspection. Regenerate for dependency changes and qualify other advertised targets separately.
+- The named tables keep their schema and indexes, but no rows.
+- Their rows are never read, so they cannot reach the file. They are not in freed
+  pages, a log or a receipt.
+- A name that is not a table fails with `RDB_VALIDATION`.
+- An edge table must be emptied together with the tables it connects.
+- Rows in other tables keep their references to the emptied rows.
+- The copy also gets a new identity, because a receipt can hold row data.
 
-With Python 3.11+ and the same Cargo cache, inspect cached source archives:
+Use `newIdentity: true` to copy every row into a new database, for example to
+duplicate a site. The copy leaves out the database ID, the sequence and the receipts.
+Its sequence starts at 0, and it gets a new ID the first time it opens.
 
-```sh
-python3 romedb/scripts/audit-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json
-python3 romedb/scripts/audit-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json --check
+The URL client has the streaming form, `rql.exportFile({ signal, timeoutMs, emptyTables,
+newIdentity })`, for `romedb serve`, `serve --directory` and Cloud. On Cloud, set
+`timeoutMs` high enough for the size of the database: a job builds the file first. See
+[database files](https://github.com/romedb/romedb/blob/main/romedb/docs/service-protocol.md#database-files) for how the copy is
+made.
+
+## URL client
+
+`@romedb/node/client` connects to a database behind `romedb serve`, `romedb serve
+--directory` or RomeDB Cloud. Importing it never loads the native addon.
+
+```js
+const { connect, Float64, saveRequest, loadRequest } = require('@romedb/node/client');
+const rql = await connect({ url: process.env.ROMEDB_URL, token: process.env.ROMEDB_TOKEN });
+const snapshot = await rql.read([{ sql: 'SELECT * FROM posts LIMIT 20' }]);
+const request = rql.prepareWrite([
+  { sql: 'UPDATE posts:p1 MERGE {score: $score}', params: { $score: new Float64(1) } },
+], { ifSequence: snapshot.sequence });
+await saveRequest('/private/new-request.json', request);
+try {
+  await rql.submit(request);
+} catch (error) {
+  if (error.outcome === 'unknown') {
+    // Keep this journal. Recovery sends its original identity and exact body.
+    await rql.recover(await loadRequest('/private/new-request.json'));
+  } else throw error;
+}
+await rql.close();
 ```
 
-The audit checks archive checksums against Cargo.lock and records declared license-file paths plus hashes of license/notice filename candidates, including nested bundled sources. It reads archives without extracting them. Missing/ambiguous archives, checksum mismatches and stale reports fail explicitly. The current report verifies 185 archives with 316 candidate files; 13 archives have no matching candidates and seven workspace packages require separate inspection. Filename discovery can miss inline notices or unconventional names, and identifying a file does not establish that all required notices are included in the package. The report is kept outside the npm runtime package.
+### Saved requests
 
-For archives with no notice filename candidates, the report also searches selected code/text files up to 200,000 bytes for copyright, SPDX and licensing phrases. It records source hashes, line numbers and bounded excerpts. The current report finds four files across crc32c, rapidhash and rquickjs-core, including crc32c's reference to zlib and a futures-author attribution in rquickjs-core. These references need review; ten of the thirteen archives have no hits within this bounded search. Absence of a match is not proof that attribution is absent or unnecessary.
+Use a new journal file name for each prepared write. `saveRequest` refuses to
+overwrite an existing file, and it flushes a mode-0600 file and its folder. A journal
+holds SQL and parameter values, so keep it private, although it holds no token. A
+refused recovery does not tell the outcome of the earlier write. Do not replace an
+expired or uncertain request with a new write automatically.
 
-Generate and verify the collected crate notice texts with:
+### URLs and tokens
 
-```sh
-python3 romedb/scripts/bundle-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json romedb/bindings/node/THIRD_PARTY_CRATE_NOTICES.md
-python3 romedb/scripts/bundle-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json romedb/bindings/node/THIRD_PARTY_CRATE_NOTICES.md --check
-```
+A local service URL is `http://127.0.0.1:4321`. A Cloud URL names the organization
+and database by stable UUIDs, and a dashboard URL that ends in `/query` also works.
+Use HTTPS for every host that is not local.
 
-The generator rechecks lockfile, inventory, archive and notice-file hashes before writing. Identical texts are deduplicated with per-package source links. The private npm package includes this partial collection (125 distinct texts for 316 candidate files), and the offline package smoke verifies both installed notice files exactly. The twenty packages without collected filename candidates and any other inline/bundled attribution remain review items; this is not a complete distribution-notice claim.
+`romedb://` is another name for `https://`. The client replaces the scheme and applies
+the same rules, so `romedb://cloud.romedb.com/v1/organizations/{org}/databases/{db}`
+and the `https://` form are the same database. Requests use `redirect: 'manual'`, and
+any redirect fails with `RDB_PROTOCOL`, so the token never goes to another URL. Pass
+the bearer token separately. The client refuses a token in the URL.
 
-Run the synthetic notice-generator integrity checks without Cargo or registry access:
+### Cloud URLs
 
-```sh
-python3 romedb/scripts/test-notice-bundle.py
-```
+For a Cloud URL, `connect()` returns without a network round trip. The database ID
+comes from the URL, and the Cloud capabilities are documented. Reads start from
+sequence 0 as their lower bound and update the sequence from each reply.
 
-These verify reproducible output, identical-text deduplication with retained source references, stale inventory and output detection, package identity mismatch, archive corruption and altered notice hashes. Failure cases must leave an existing output file intact.
+A write needs a current sequence. If none is known yet, `writeAtomic` first fetches
+the database details, and `prepareWrite` throws `RDB_SEQUENCE_UNKNOWN` (outcome
+`not-sent`) until a read, `info()` or an explicit `afterSequence` supplies one. To
+fetch the details at connect, pass `deferInfo: false`. Other URLs always fetch the
+details at connect and refuse `deferInfo: true`.
 
-## Linux artifact requirements
+`connect()` on a Cloud URL also sends a warm request in the background and does not
+wait for it. Cloud then starts the container of the database and opens it, so a query
+a second or more later does not wait for that start. Errors of the background request
+are ignored. To skip it, pass `warm: false`.
 
-Inspect the actual package addon without loading it (Python 3.11+ and `readelf`):
+`await rql.warm()` sends the same request and returns `{ state }`. The state is
+`ready` when the database is already open, `starting` when Cloud began to open it, or
+`skipped` when Cloud declined because another database is busy. Call it when your
+application knows that a query is coming, for example when a page or a function
+starts. Local URLs refuse `warm()`.
 
-```sh
-python3 romedb/scripts/inspect-node-elf.py romedb/bindings/node/romedb.node romedb/docs/node-elf-linux-x64.json
-python3 romedb/scripts/inspect-node-elf.py romedb/bindings/node/romedb.node romedb/docs/node-elf-linux-x64.json --check
-```
+### Local directories
 
-The checked-in report identifies the tested stripped artifact by size and SHA-256, records ELF class/machine, linked libraries, search paths and required symbol versions. This local artifact references GLIBC symbols through 2.35 and has no RPATH/RUNPATH. A successful local Linux test does not establish compatibility with older glibc systems, musl distributions, another architecture or another Node version. A release baseline still needs an explicit build environment and tests on the advertised targets. Regenerate the report whenever the addon changes.
+An organization URL on a loopback host, such as a database of `romedb serve
+--directory` (`http://127.0.0.1:4321/v1/organizations/{org}/databases/{db}`), always
+fetches the details at connect. A reply with `serviceVersion: 1` is a local service.
+The client then negotiates its capabilities and uses the 64 KiB service request
+format, with no warm request. Any other reply is Cloud running locally, which keeps
+the Cloud request format. So an application can use the same organization URLs for a
+local directory and for Cloud.
 
+### Values and results
 
-### Bounded SELECT results
+Results use positional rows and keep duplicate columns. Integer results are `bigint`.
+Number results are `Float64` instances with a `.value` number. They keep their exact
+float type when you bind them again, integral floats and negative zero included.
 
-Both clients expose `selectWithLimits(sql, limits, parameters?)` and
-`profileSelectWithLimits(sql, limits, parameters?)`. The worker variants accept
-an additional fourth `{ signal }` argument using the existing cooperative
-cancellation contract. Both budgets are required nonnegative bigint values:
+This entry exports its own `Record`, `Vector` and value codec. Use those types for its
+parameters. Encoded vectors and the dense float32, float64 and sparse-entry factories
+work without native code. `null` is a present field. `undefined` and array holes are
+refused, so no data disappears without an error.
+
+### Errors and timeouts
+
+Requests and responses have finite byte and row limits. Each call times out after 20
+seconds by default and accepts `signal` and `timeoutMs`. An HTTP error reply with a
+`Retry-After` header sets `ClientError.retryAfterMs`. A transport or response failure
+without a database reply keeps the underlying error as `ClientError.cause`, for
+example a `fetch failed` TypeError with `ECONNREFUSED`.
+
+`rql.sequenceKnown` is `true` once a reply has given the current sequence. `rql.cloud`
+tells a Cloud database from a local service. A write cancelled after it was sent stays
+unknown until a receipt confirms it. Cloud capabilities are marked as documented,
+because its API does not negotiate the local capability object. See the
+[service contract](https://github.com/romedb/romedb/blob/main/romedb/docs/service-protocol.md) for limits, receipt rules and
+compatibility gaps.
+
+### Query versions
+
+From RomeDB 2.9.0 the client asks Cloud for query version 3
+(`x-romedb-query-version: 3` on `/query` and `/read`). In version 3, Binary and
+Vector values travel as canonical base64, and request bodies can be up to 1 MiB.
+Local services and embedded databases keep version 2, with byte arrays and 64 KiB
+bodies.
+
+Version 2 covers tagged Record keys and typed query errors. Resource URLs stay `/v1`,
+and `readVersion: 2` separately defines fresh-read execution. The client accepts the
+version it asked for, version 2, and older responses without the header, and it
+decodes both byte forms. An unknown version fails with `RDB_PROTOCOL`. A write that
+was sent then stays `unknown` and keeps its exact saved request for recovery.
+
+Saved writes are version 2 and record their query version. Version 1 saved writes
+from 2.8.0 replay at version 2. Older receipts with enum keys still decode.
+
+### Workers, browsers and other runtimes
+
+From 0.2.12, `@romedb/node/client` and `@romedb/node/values` use only Web APIs:
+`fetch`, `crypto.randomUUID`, `TextEncoder`, `AbortSignal`, `atob` and `btoa`. Node.js
+loads the CommonJS files through the `node` export condition. Every other runtime and
+bundler gets the ES modules `client.mjs` and `values.mjs`, for example Cloudflare
+Workers, browsers and Deno with a bundler. They run the same code: `build-esm.cjs`
+writes them from `client.cjs` and `values.cjs`, and the package tests fail when they
+are out of date.
+
+Workers need no `nodejs_compat`. The client calls `fetch` without a `this` value, so
+`globalThis.fetch` and your own `fetch` both work in Workers.
 
 ```js
-const result = await asyncDb.selectWithLimits(
-  'SELECT title FROM posts LIMIT 100',
-  { maxRows: 100n, maxPayloadBytes: 65536n },
-);
+import { connect } from '@romedb/node/client';
+
+export default {
+  async fetch(request, env) {
+    const rql = await connect({ url: env.ROMEDB_URL, token: env.ROMEDB_TOKEN });
+    const { results } = await rql.read([{ sql: "SELECT title FROM posts WHERE array::contains(tags, 'news')" }]);
+    return Response.json({ posts: results[0].rows.length });
+  },
+};
 ```
 
-Overflow throws/rejects with `FDB_LIMIT` and transaction observations, without
-partial rows or metrics. Empty results still charge column names. These APIs
-accept one SQL SELECT, including supported one-hop FETCH. Resolved documents
-and duplicate occurrences count toward the final payload budget; missing targets
-count as nulls. Found targets are charged with their output multiplicity before
-cache retention, allowing early rejection during target reads. Reference
-placeholders are excluded. Existing execute/profile
-methods keep their current result policy.
-
-Payload bytes count UTF-8 column names, strings, object keys, record table names
-and string keys; integer keys and numbers cost eight bytes, null and booleans one
-byte, and binary/encoded vectors their byte length. Objects and arrays sum their
-contents. These are logical result budgets, excluding container/allocator
-costs, temporary decoding, Node transport copies and engine working memory.
-FETCH retains its independent reference and tagged-JSON limits; temporary
-references and the target cache are not covered by the final payload budget.
-These limits are not process memory limits or deadlines.
+`@romedb/node/values` exports only the value types and the codec (`Float64`, `Record`,
+`Vector`, `encodeValue`, `decodeValue`). Use it for code that never connects, such as
+a browser bundle. Both entries share one set of value classes.
 
+Binary values and `Vector.bytes` are plain `Uint8Array` objects in every runtime.
+Before 0.2.12, Node returned `Buffer`. Use `Buffer.from(bytes)` where you need Buffer
+methods. `saveRequest` and `loadRequest` need Node.js file access and reject in other
+runtimes. There, store the `PreparedWrite` object yourself, for example in a Durable
+Object.
 
-### Atomic write-result acceptance
+The package also contains the native addon. So installing it for a Workers app also
+downloads the addon, but the Workers bundle never includes it.
 
-Both clients expose `writeWithResultLimits(sql, limits, parameters?)`; the worker
-version accepts a fourth `{ signal }` argument. Use the same required bigint
-`maxRows` and `maxPayloadBytes` fields as bounded SELECT. Supported SQL data
-writes and object writes run in an operation savepoint. Native SQL checks each
-result row before frontend retention; collection SQL and object RETURNING check
-each projected row before retention. Native destinations with logical sources
-also check rows during final statement collection. In all cases, overflow returns `FDB_LIMIT` and rolls back that write,
-including index and trigger effects, using the existing recovery path.
+## Load errors
 
-```js
-const result = await asyncDb.writeWithResultLimits(
-  'UPDATE posts SET published=true RETURNING id',
-  { maxRows: 100n, maxPayloadBytes: 65536n },
-);
+On Node.js versions before 22, importing the native entries throws
+`RDB_RUNTIME_VERSION` before native code loads.
+
+If the native addon is missing or cannot load, importing the package throws
+`RDB_NATIVE_LOAD`. The message names the platform, the architecture and the Node
+version, and it points to the source build instructions. `error.cause` keeps the
+original loader error, for example a missing library or an invalid binary. The package
+does not select, download or rebuild an addon automatically.
+
+## For maintainers
+
+### Build and test from the checkout
+
+From the repository root, install the declaration checker and run the checks:
+
+```sh
+pnpm --dir romedb/bindings/node install --ignore-scripts
+romedb/scripts/check.sh
 ```
 
-This is a result acceptance policy with progressive native frontend collection.
-**It does not bound engine RETURNING buffers, write candidates, document
-snapshots or individual projection working memory.** Transaction control, DDL, reads and multiple
-statements are rejected. A write without RETURNING can succeed with zero budgets;
-affected rows do not count as returned rows. Empty RETURNING still charges column
-names. Cooperative cancellation uses the usual error/transaction envelope and
-savepoint recovery; completed-result accounting has no fixed cancellation latency.
+`check-node.sh` builds the addon and copies it to the ignored `romedb.node` path. Then
+it runs the Node tests and type-checks the declarations. If you need the temporary
+toolchain, use the documented Rust environment of the repository. The package has no
+npm runtime dependencies. TypeScript 5.8.3 is pinned only for the declaration checks.
 
-### Collection write buffer limits
+### Local package smoke
 
-Both clients accept an optional second argument at open time:
+Normal npm packing first makes sure that the native addon loads. A missing or
+incompatible build fails before the archive exists. The npm file list holds the native
+addon, the synchronous and worker JavaScript entries, the declarations, the README,
+the MIT license and the third-party notices. Build the addon for the current
+platform, then test the actual tarball from the repository root:
 
-```js
-const options = { writeBufferLimits: { maxRows: 10_000n, maxPayloadBytes: 64n * 1024n * 1024n } };
-const db = new Database(':memory:', options);
-const workerDb = await AsyncDatabase.open(':memory:', options);
+```sh
+romedb/scripts/check-node.sh
+node romedb/scripts/check-node-package.cjs
 ```
 
-The policy limits each frontend collection-write candidate or document snapshot
-buffer separately. Exceeding a limit returns `FDB_LIMIT` and rolls back the
-operation while preserving prior transaction work. Ordinary reads and explicit
-returned-result limits retain their separate policies. Limits are fixed for the
-lifetime of a Node connection and disabled by default. Both fields are required
-nonnegative uint64 bigint values; unknown options and invalid values are rejected
-before opening the database or starting its worker.
+The smoke packs into a temporary folder and compares the exact file list. It installs
+the tarball into a separate consumer with npm offline and lifecycle scripts off. Then
+it tests public synchronous and worker queries, typed int64 and record values,
+rollback and reopen. It also covers profiling and audits in both clients, cancellation
+before dispatch for every signalled API, and listener and token cleanup. It compiles a
+consumer TypeScript import against the installed declarations. It removes its
+temporary files afterwards.
 
-These are not total memory limits: native engine buffers, parsing, temporary
-values and overlapping buffers remain outside the policy. Transfer APIs also
-retain their existing separate limits. See the repository's
-`romedb/docs/result-budgets.md` for accounting and remaining resource gates.
+For an optimized local addon, run `romedb/scripts/check-node.sh --release` before the
+smoke. That build uses the pinned release profile of the workspace and runs the same
+tests and TypeScript type check. It does not build universal prebuilds or publish a package.
+On Linux, `--release-stripped` also runs `strip --strip-debug` on the package copy. It
+keeps the full release artifact in the Cargo target folder for diagnostics, and it
+needs `strip`.
 
-### Worker operation timeouts
+The smoke is a maintainer test, separate from routine CI, because the debug addon is
+large. The tested local artifact is Linux x64 with Node 24.19.0, not a universal
+binary. Prebuilds for other platforms, more Node versions and platforms, and complete
+distribution notices are release work. Releases reach npm through the publishing
+workflow, which [publishing to npm](https://github.com/romedb/romedb/blob/main/romedb/docs/npm-publishing.md) describes.
 
-Async operations accepting `ExecuteOptions` also accept `timeoutMs`, an integer
-number from 0 through 4,294,967,295. For example:
+### Dependency declaration inventory
 
-```js
-await workerDb.execute('SELECT * FROM docs', {}, { timeoutMs: 500 });
+From the checkout root, with the pinned Rust toolchain:
+
+```sh
+node romedb/scripts/inventory-node-dependencies.cjs x86_64-unknown-linux-gnu romedb/docs/node-dependencies-linux-x64.json
+node romedb/scripts/inventory-node-dependencies.cjs x86_64-unknown-linux-gnu romedb/docs/node-dependencies-linux-x64.json --check
 ```
 
-The native monotonic deadline starts when the request token is created, after
-local parameter encoding and before worker queue submission. Queue time counts;
-zero is immediately expired. It shares the existing cooperative cancellation
-path and returns `FDB_CANCELLED`, with normal operation rollback and transaction
-observations. `signal` can be supplied alongside it. No JavaScript timeout timer
-is needed; token cleanup follows request completion/failure. Timeout expiry does
-not cancel later requests. `close()` has no timeout option.
-
-This is not a hard promise-return deadline. Native progress checks observe expiry;
-parsing, non-engine work, cleanup and response transport can exceed the requested
-time, and completion can win a race. Synchronous clients do not expose this option.
-
-### URL client for the Studio service work
-
-The new `@romedb/node/client` entry supports the current Cloud read-v2/write
-envelopes and the version-1 local service contract. The URL client, native service,
-and embedded adapter are implemented in development source. They are not released.
-The hosted common fixture and production Studio browser workflow pass. Existing
-native imports are unchanged. Final release-candidate packaging remains pending.
-
-Since 2.9.0 the SDK asks Cloud for query version 3 (`x-romedb-query-version: 3`
-on `/query` and `/read`): Binary and Vector values travel as canonical base64 and
-request bodies may be up to 1 MiB. Local services and embedded databases keep
-version 2 (byte arrays, 64 KiB). Version 2 covers tagged Record keys and typed
-query errors; resource URLs remain `/v1`, and `readVersion: 2` separately defines
-fresh-read execution. The SDK accepts the version it asked for, version 2, and
-historical responses without the header, and decodes both byte forms. An unknown
-advertised version fails with `FDB_PROTOCOL`; a dispatched write remains `unknown`
-and retains its exact saved request for recovery. Saved writes are version 2 and
-record their query version; version 1 saved writes from 2.8.0 replay at version 2.
-Historical enum-key receipts still decode.
+This offline, locked Cargo query records normal and build dependencies, their declared
+license expressions, the target and the lockfile hash. The Linux inventory has 192
+package versions. Build tools are included, and development dependencies are not.
 
-```js
-const { connect, Float64, Record, saveRequest, loadRequest } = require('@romedb/node/client');
-const db = await connect({ url: process.env.ROMEDB_URL, token: process.env.ROMEDB_TOKEN });
-const snapshot = await db.read([{ sql: 'SELECT * FROM posts LIMIT 20' }]);
-const request = db.prepareWrite([
-  { sql: 'UPDATE posts:p1 SET score=$score', params: { $score: new Float64(1) } },
-], { ifSequence: snapshot.sequence });
-await saveRequest('/private/new-request.json', request);
-try {
-  await db.submit(request);
-} catch (error) {
-  if (error.outcome === 'unknown') {
-    // Keep this journal. Recovery sends its original identity and exact body.
-    await db.recover(await loadRequest('/private/new-request.json'));
-  } else throw error;
-}
-await db.close();
+`cfg_block` 0.1.1 has no license expression in the query output. Its pinned manifest
+declares `license-file = "LICENSE"` instead, and that file contains an Apache 2.0
+notice. The package notice file includes it and the Apache 2.0 text. The inventory
+keeps the missing expression rather than an inferred value.
+
+The inventory is an input for an audit. It does not prove that every listed crate is
+linked into the addon, and it is not a complete component inventory or a replacement
+for license texts. Bundled C and C++ sources and other vendored components need their
+own inspection. Regenerate the inventory when dependencies change, and qualify other
+targets separately.
+
+With Python 3.11 or later and the same Cargo cache, inspect the cached source archives:
+
+```sh
+python3 romedb/scripts/audit-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json
+python3 romedb/scripts/audit-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json --check
 ```
 
-Use a new journal filename for each prepared write. `saveRequest` refuses to
-overwrite an existing file and flushes a mode-0600 file and its directory. Journals
-contain SQL and parameter values; they are private even though they contain no
-token. A rejected recovery attempt does not establish an earlier write's outcome.
-Do not automatically replace an expired or uncertain request with a new write.
-
-URL imports never load the native addon. Cloud URLs use stable organization and
-database UUIDs; dashboard URLs ending in `/query` are accepted too. The proposed
-local URL is `http://127.0.0.1:4321`. Use HTTPS for other hosts. `romedb://` is an
-alias for `https://`: the client replaces the scheme and applies the same checks,
-so `romedb://cloud.romedb.com/v1/organizations/{org}/databases/{db}` and the
-`https://` form are the same database. It changes no transport or protocol.
-Requests use `redirect: 'manual'`, and any redirect reply fails with
-`FDB_PROTOCOL`, so the token is never sent on to another URL. The bearer token
-must be passed separately from the URL; a token in the URL is refused.
-
-For Cloud database URLs, `connect()` returns without a network round trip: the
-database id comes from the URL and Cloud capabilities are documented. Reads start
-from sequence 0 as their lower bound and update the sequence from each reply. A
-write needs a current sequence: `writeAtomic` fetches the database details first
-when none is known yet, and `prepareWrite` throws `FDB_SEQUENCE_UNKNOWN` (outcome
-`not-sent`) until a read, `info()` or an explicit `afterSequence` supplies one.
-Pass `deferInfo: false` to request the details at connect, as 2.5 did by default.
-Other URLs always request the details at connect, and `deferInfo: true` is
-rejected for them.
-
-An organization URL on a loopback host, such as a database of
-`romedb serve --directory` (`http://127.0.0.1:4321/v1/organizations/{org}/databases/{db}`),
-always requests the details at connect. A reply with `serviceVersion: 1` is a local
-service: the client negotiates its capabilities and uses the 64 KiB service request
-format, with no warm request. Any other reply is Cloud running locally, which keeps
-the Cloud request format. Application code can therefore use the same organization
-URLs for a local directory and for Cloud.
-
-`connect()` on a Cloud URL also sends a warm request in the background and does
-not wait for it. Cloud then starts the database's container and opens the
-database, so a query sent a second or more later skips that start-up time. Errors
-from the background request are ignored; pass `warm: false` to skip it.
-`await db.warm()` sends the same request and returns `{ state }`: `ready` when the
-database is already open, `starting` when Cloud began opening it, or `skipped`
-when Cloud declined because another database is busy. Call it when your
-application knows a query is coming, for example when a page or a function
-starts. `warm()` is rejected for local URLs.
-
-Results use positional rows, preserving duplicate columns. Integer results are
-bigint. Number results are explicit `Float64` instances with a `.value` number;
-they retain their exact float type when rebound, including integral floats and
-negative zero. This new entry exports its own `Record`, `Vector` and value codec.
-Use those types for its parameters. Encoded vectors and dense float32/float64 or
-sparse-entry factories work without native code. Null is a present field;
-undefined and array holes are rejected instead of silently removing data.
-
-Requests and responses have finite byte/row limits. Each call defaults to a
-20-second timeout and accepts `signal`/`timeoutMs`. An HTTP error reply with a
-`Retry-After` header sets `ClientError.retryAfterMs`. A transport or response
-failure without a database reply keeps the underlying error as `ClientError.cause`
-(for example a `fetch failed` TypeError with `ECONNREFUSED`). `db.sequenceKnown`
-is true once a reply has given the current sequence, and `db.cloud` tells a Cloud
-database from a local service. Cancellation after dispatch
-leaves a write unknown until a receipt confirms it. Cloud capabilities are marked
-as documented, because its API currently does not negotiate the local capability
-object. See the [service contract](../../docs/service-protocol.md) for limits,
-receipt rules and compatibility gaps.
+The audit compares archive checksums with `Cargo.lock`. It records declared license-file
+paths and hashes of files whose names look like licenses or notices, nested bundled
+sources included. It reads the archives without extracting them. Missing or ambiguous
+archives, checksum mismatches and stale reports fail. The current report has 185
+archives with 316 candidate files. 13 archives have no candidates, and seven workspace
+packages need separate inspection. A name search can miss inline notices and unusual
+names, and a found file does not prove that the package has every required notice.
+The report stays outside the npm package.
+
+For archives without candidates, the report also searches selected code and text files
+of up to 200,000 bytes for copyright, SPDX and license phrases. It records source
+hashes, line numbers and short excerpts. The current report finds four files in
+crc32c, rapidhash and rquickjs-core: crc32c refers to zlib, and rquickjs-core has an
+attribution to the futures authors. These references need review. Ten of the thirteen
+archives have no hits in this bounded search, and no hit is not proof that no
+attribution is needed.
+
+Generate and test the collected crate notice texts:
 
-### Workers, browsers and other runtimes
+```sh
+python3 romedb/scripts/bundle-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json romedb/bindings/node/THIRD_PARTY_CRATE_NOTICES.md
+python3 romedb/scripts/bundle-crate-notices.py romedb/docs/node-dependencies-linux-x64.json romedb/docs/node-crate-notices-linux-x64.json romedb/bindings/node/THIRD_PARTY_CRATE_NOTICES.md --check
+```
 
-From 0.2.12, `@romedb/node/client` and `@romedb/node/values` use only Web APIs
-(`fetch`, `crypto.randomUUID`, `TextEncoder`, `AbortSignal`, `atob` and `btoa`).
-Node.js resolves them to the CommonJS files through the `node` export condition.
-Every other runtime and bundler (Cloudflare Workers, browsers, Deno with a
-bundler) gets the ES modules `client.mjs` and `values.mjs`, which run the same
-code: `build-esm.cjs` writes them from `client.cjs` and `values.cjs`, and the
-package tests fail when they are out of date. Workers need no `nodejs_compat`.
-The client calls `fetch` without a `this` value, so `globalThis.fetch` and your
-own `fetch` both work in Workers.
+The generator compares the lockfile, inventory, archive and notice-file hashes again
+before it writes. It writes identical texts once, with source links for each package.
+The npm package includes this partial collection: 125 distinct texts for 316 candidate
+files. The offline package smoke compares both installed notice files exactly. The
+twenty packages without collected candidates and any other inline or bundled
+attribution are still review items, so this is not a complete set of distribution
+notices.
 
-```js
-import { connect, Float64 } from '@romedb/node/client';
+Run the synthetic tests of the notice generator without Cargo or registry access:
 
-export default {
-  async fetch(request, env) {
-    const db = await connect({ url: env.ROMEDB_URL, token: env.ROMEDB_TOKEN });
-    const { results } = await db.read([{ sql: 'SELECT $x AS x', params: { $x: new Float64(1) } }]);
-    return Response.json({ rows: results[0].rows.length });
-  },
-};
+```sh
+python3 romedb/scripts/test-notice-bundle.py
 ```
 
-`@romedb/node/values` exports only the value types and codec (`Float64`, `Record`,
-`Vector`, `encodeValue`, `decodeValue`) for code that never connects, such as a
-browser bundle. Both entries share one set of value classes.
+They test these cases:
 
-Binary values and `Vector.bytes` are plain `Uint8Array` objects in every runtime;
-before 0.2.12 Node returned `Buffer`. Use `Buffer.from(bytes)` where Buffer
-methods are needed. `saveRequest` and `loadRequest` need Node.js file access and
-reject elsewhere; store the `PreparedWrite` object yourself there, for example in
-a Durable Object.
+- Reproducible output.
+- Identical texts written once, with their source references.
+- Detection of a stale inventory or a stale output.
+- A package identity mismatch, a corrupt archive and changed notice hashes.
 
-The package still contains the native addon, so installing it for a Workers app
-also downloads the addon, which the Workers bundle never includes.
+A failure case must leave an existing output file unchanged.
 
-### Embedded client for the same asynchronous interface
+### Linux artifact requirements
 
-Use `@romedb/node/embedded-client` for native file access through the new managed
-interface. This entry requires the native addon. It exports the same value types
-and `info`, `read`, `prepareWrite`, `submit`, `recover`, and `writeAtomic` methods.
-CommonJS and ESM imports are supported.
+Inspect the package addon without loading it (Python 3.11 or later and `readelf`):
 
-```js
-const { openEmbedded, Record } = require('@romedb/node/embedded-client');
-const db = await openEmbedded({ path: 'app.romedb' });
-try {
-  await db.writeAtomic([
-    { sql: 'UPSERT posts:p1 { count: $count }', params: { $count: 9223372036854775807n } },
-  ]);
-  const result = await db.read([
-    { sql: 'SELECT * FROM posts WHERE id=$id', params: { $id: new Record('posts', 'p1') } },
-  ]);
-  console.log(result.results[0].rows);
-} finally {
-  await db.close();
-}
+```sh
+python3 romedb/scripts/inspect-node-elf.py romedb/bindings/node/romedb.node romedb/docs/node-elf-linux-x64.json
+python3 romedb/scripts/inspect-node-elf.py romedb/bindings/node/romedb.node romedb/docs/node-elf-linux-x64.json --check
 ```
 
-Opening requires an existing regular file with one link. To create a new file,
-use `openEmbedded({ path: 'new.romedb', create: true })`. Creation refuses existing
-files and journal sidecars. Files use MVCC, the journal mode of `romedb serve` and
-Cloud, so a file moves between these modes without conversion and sees the same
-write conflicts. Opening a WAL file fails with `FDB_UNSUPPORTED` and leaves the file
-unchanged; stop its owner and convert it with `romedb migrate-to-mvcc`. The managed
-connection enables SQL foreign keys without changing the legacy APIs.
-
-`create: true` makes the database file with mode 0600. The WAL file
-(`NAME-wal`) and the MVCC log (`STEM.db-log`, which holds row data until a
-checkpoint) get the database file's permissions, as in SQLite: RomeDB creates
-them before the engine does, and on each open it removes permission bits that the
-database file does not have from existing ones. So every file of a new database is
-0600, and a database made by 0.2.11 or earlier gets private journal files at its
-next open.
-
-One process keeps at most `maxOpen` different files open (1 to 1024, default 16).
-An open that would pass this number fails with `FDB_LIMIT`; clients of a file that
-is already open do not count again. `close()` of the last client checkpoints the
-MVCC log into the database file, so the next open has no log to replay, and then
-releases the file's OS lock. To keep many databases, such as one per site, open
-them with the same `maxOpen` and close the least recently used one yourself.
-Reopening a closed file takes about 75 to 90 ms on Linux x64 (release build,
-2026-11-02), nearly independent of its size: each open file has its own worker
-thread, and starting it and loading the addon in it is about 60 ms of that; the
-engine open is about 9 ms and closing with the checkpoint about 10 ms.
-
-Clients for the same canonical file in one Node module share one native worker.
-Each batch runs as one worker operation inside a managed transaction. All
-statements are validated before execution. User transaction control is rejected.
-Failures and exceeded result/work limits restore the batch. Existing
-`executeBatch` behavior remains unchanged.
-
-Sequence conditions cover writes through this shared adapter. Its capabilities
-report `sequenceScope: 'adapter'` and `replayDurability: 'adapter-lifetime'`.
-`info()` also returns `engineVersion`, the RomeDB release of the native engine.
-Database URLs report it from local services 2.7.0 and later and from Cloud; it is
-absent for older services.
-Other native or legacy handles do not advance this revision. Studio must reuse
-the managed adapter for each canonical file. Use the service URL for sharing
-between application processes.
-
-The adapter retains 64 exact write receipts in memory. Saved journals can recover
-a write while that adapter remains open. After its last client closes, reopening
-creates a new identity and refuses old requests. Reconcile uncertain writes from
-the stored data after a reopen. Service and Cloud connections provide recovery
-across process restarts.
-
-The initial limits are 16 open file adapters, 32 outstanding requests per adapter,
-and 2 MiB of queued request bodies. The request, result, and work limits match the
-common contract. Calls default to 20 seconds and accept a 1–120,000 ms timeout.
-Opening also has a deadline. If opening expires, cleanup continues until native
-startup returns. Filesystem work and native cleanup are not hard preempted.
-
-Close stops requests from that client and cancels its outstanding work. The last
-client drains the worker queue, closes the native handle, and waits for worker
-exit. Await every client's `close()` to release ownership.
-
-For typed collection CRUD helpers, see the [document SDK guide](https://github.com/romedb/romedb/blob/main/romedb/docs/node-sdk.md).
+The report names the tested stripped artifact by size and SHA-256. It records the ELF
+class and machine, linked libraries, search paths and required symbol versions. This
+artifact uses GLIBC symbols up to 2.35 and has no RPATH or RUNPATH. A passing local
+Linux test does not prove compatibility with older glibc systems, musl distributions,
+another architecture or another Node version. A release baseline needs an explicit
+build environment and tests on the advertised targets. Regenerate the report whenever
+the addon changes.