@romedb/node 0.2.13 → 0.2.15

package/README.md

@@ -23,9 +23,12 @@ version, 0.2.12, differs from its asset only in `package.json` and this README.
 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.13/romedb-node-0.2.13.tgz
+pnpm add https://github.com/romedb/romedb/releases/download/romedb-v0.2.15/romedb-node-0.2.15.tgz
 ```
 
+From 0.2.15, `@romedb/node` depends on `@romedb/client` at the same version, so that
+asset also needs npm or the `romedb-client` asset of the same release.
+
 ## A first database
 
 ```js
@@ -125,7 +128,7 @@ own connection.
 | `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`. |
+| `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,
@@ -702,8 +705,30 @@ it. Exports have no deadline unless you pass `timeoutMs`. `signal`, `timeoutMs`
 `close()` cancel a running export. It then rejects with `RDB_CANCELLED`, unless it
 finished first.
 
-The URL client has the streaming form, `rql.exportFile({ signal, timeoutMs })`, for
-`romedb serve` and `serve --directory`. Cloud URLs do not support it yet. See
+#### Leaving data out of a copy
+
+A whole copy holds everything, including sessions and tokens. Use `emptyTables` when
+someone else gets the file:
+
+```js
+await rql.exportFile('site.romedb', { emptyTables: ['cms_auth_sessions', 'cms_cache'] });
+```
+
+- 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.
+
+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.
+
+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.
 
@@ -790,8 +815,9 @@ Results use positional rows and keep duplicate columns. Integer results are `big
 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.
 
-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
+This entry exports `Record`, `Vector` and the value codec of `@romedb/client`, which
+`@romedb/node/embedded-client` also uses. The main `@romedb/node` entry has its own
+`Record` and `Vector`, so do not pass those to this client. 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.
 
@@ -833,9 +859,9 @@ 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, browsers and Deno with a bundler. They run the same code: `build-esm.cjs` in
+`@romedb/client` 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.
@@ -863,7 +889,11 @@ runtimes. There, store the `PreparedWrite` object yourself, for example in a Dur
 Object.
 
 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.
+downloads the addon, but the Workers bundle never includes it. To skip that download,
+install [`@romedb/client`](https://www.npmjs.com/package/@romedb/client). It holds this
+code: `@romedb/node` depends on it, and `@romedb/node/client` and `@romedb/node/values`
+pass it through. A project that uses both packages gets one set of value classes when
+both are at the same version.
 
 ## Load errors
 

package/THIRD_PARTY_CRATE_NOTICES.md

@@ -4,7 +4,7 @@ Generated from the pinned Cargo dependency inventory and checksummed source arch
 
 This is a partial notice collection. It supplements LICENSE.md and THIRD_PARTY_NOTICES.md. Inline attributions, unconventional filenames and other bundled components require further review before a complete distribution-notice claim.
 
-Target: `x86_64-unknown-linux-gnu`. Cargo.lock SHA-256: `092e973bbc52cf5defe48c0c1c1cf5bc8755b603f5a6ef47927c31bfa5276aa3`.
+Target: `x86_64-unknown-linux-gnu`. Cargo.lock SHA-256: `600d6e7ecfe4d96e7ad02ea62ba679b7ae7e3c858b650adeb16693643bae6570`.
 
 ## Packages without collected archive or supplemental texts
 
@@ -703,13 +703,13 @@ Target: `x86_64-unknown-linux-gnu`. Cargo.lock SHA-256: `092e973bbc52cf5defe48c0
 - `LICENSE-APACHE`: [source text a60eea817514531668d7e00765731449fe14d059d3249e0bc93b36de45f759f2](#text-a60eea817514531668d7e00765731449fe14d059d3249e0bc93b36de45f759f2)
 - `LICENSE-MIT`: [source text 42d3bf7e7d4d49d72c0555d14ed99c3ee7ce9ce3cbffbc38bbafe8c103f50969](#text-42d3bf7e7d4d49d72c0555d14ed99c3ee7ce9ce3cbffbc38bbafe8c103f50969)
 
-### romedb-node 0.2.13
+### romedb-node 0.2.15
 - Workspace `LICENSE.md`: [source text b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5](#text-b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5)
 
-### romedb 0.2.13
+### romedb 0.2.15
 - Workspace `LICENSE.md`: [source text b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5](#text-b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5)
 
-### romeql-parser 0.2.13
+### romeql-parser 0.2.15
 - Workspace `LICENSE.md`: [source text b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5](#text-b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5)
 
 ### rquickjs-core 0.13.0

package/client.cjs

@@ -1,483 +1,2 @@
 'use strict';
-// Web APIs only: this file also runs in Workers and browsers through client.mjs.
-const { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text } = require('./values.cjs');
-
-const MAX_REQUEST = 65_536;
-const MAX_CLOUD_REQUEST = 1_048_576;
-const CLOUD_QUERY_VERSION = 3;
-const MAX_RESPONSE = 524_288;
-const MAX_SEQUENCE = Number.MAX_SAFE_INTEGER - 1;
-const DATABASE_FILE_TYPE = 'application/vnd.romedb.database';
-const construction = Symbol('RemoteDatabase');
-const warmAtConnect = Symbol('warmAtConnect');
-const WARM_STATES = new Set(['ready', 'starting', 'skipped']);
-const encoder = new TextEncoder();
-
-class ClientError extends Error {
-  constructor(code, message, outcome, details = {}) {
-    const { cause, ...fields } = details;
-    super(message, cause === undefined ? undefined : { cause });
-    this.name = 'ClientError';
-    this.code = code;
-    this.outcome = outcome;
-    Object.assign(this, fields);
-  }
-}
-
-async function connect(options) {
-  const db = new RemoteDatabase(options, construction);
-  db[warmAtConnect]();
-  if (db.deferred) return db;
-  try { await db.info(); return db; }
-  catch (error) { await db.close(); throw error; }
-}
-
-class RemoteDatabase {
-  #url; #token; #fetch; #timeout; #sequence = 0; #id; #capabilities; #transport;
-  #closed = false; #active = new Set(); #inflightBytes = 0; #sequenceKnown = false; #deferred = false; #cloud = false; #warm = false; #loopbackOrganization = false;
-  constructor(options, key, transport) {
-    if (key !== construction) throw new TypeError('use connect()');
-    if (!plainObject(options)) throw new TypeError('connection options require an object');
-    this.#url = transport ? normalizeFileUrl(options.url) : normalizeUrl(options.url);
-    this.#transport = transport;
-    if (typeof options.token !== 'string' || !/^[\x21-\x7e]{1,4096}$/.test(options.token)) throw new TypeError('token requires a bounded bearer credential');
-    this.#token = options.token;
-    const fetch = options.fetch ?? globalThis.fetch;
-    if (typeof fetch !== 'function') throw new TypeError('fetch must be a function');
-    // Workers refuse fetch called on another object, so the default keeps globalThis.
-    this.#fetch = options.fetch ?? fetch.bind(globalThis);
-    this.#timeout = timeout(options.timeoutMs ?? 20_000);
-    if (options.deferInfo !== undefined && typeof options.deferInfo !== 'boolean') throw new TypeError('deferInfo requires a boolean');
-    if (options.warm !== undefined && typeof options.warm !== 'boolean') throw new TypeError('warm requires a boolean');
-    const cloudId = transport ? undefined : /\/databases\/([0-9a-f-]{36})$/.exec(this.#url)?.[1];
-    // A loopback organization URL is a local service directory or Cloud in development;
-    // the details reply tells which, so these connections always read details first.
-    this.#loopbackOrganization = cloudId !== undefined && loopbackHost(new URL(this.#url).hostname);
-    this.#cloud = cloudId !== undefined && !this.#loopbackOrganization;
-    if (cloudId === undefined && options.deferInfo === true) throw new TypeError('deferInfo applies only to Cloud database URLs');
-    if (cloudId === undefined && options.warm === true) throw new TypeError('warm applies only to Cloud database URLs');
-    // Cloud database URLs carry the database id and have documented capabilities,
-    // so the details request waits until a write needs a current sequence.
-    if (this.#cloud && options.deferInfo !== false) {
-      this.#id = cloudId; this.#capabilities = capabilities(this.#url, {}, false); this.#deferred = true;
-    }
-    this.#warm = this.#cloud && options.warm !== false;
-  }
-  [warmAtConnect]() {
-    if (this.#warm) this.warm().catch(() => {});
-  }
-  get deferred() { return this.#deferred; }
-  get url() { return this.#url; }
-  get cloud() { return this.#cloud; }
-  get sequence() { return this.#sequence; }
-  get sequenceKnown() { return this.#sequenceKnown; }
-  get databaseId() { return this.#id; }
-  async info(options = {}) {
-    const info = await this.#request('', undefined, options, false);
-    if (!plainObject(info) || typeof info.id !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(info.id) || !sequence(info.sequence, true) || (this.#id !== undefined && this.#id !== info.id)) {
-      throw new ClientError('RDB_PROTOCOL', 'Invalid database details or changed database identity', 'read-failed');
-    }
-    if (this.#loopbackOrganization) this.#cloud = info.serviceVersion === undefined;
-    const supported = capabilities(this.#url, info, !this.#cloud);
-    this.#id = info.id;
-    this.#sequence = Math.max(this.#sequence, info.sequence);
-    this.#sequenceKnown = true;
-    this.#capabilities = supported;
-    return { ...info, capabilities: supported };
-  }
-  async warm(options = {}) {
-    this.#assertOpen();
-    if (!this.#cloud) throw new ClientError('RDB_UNSUPPORTED', 'warm applies only to Cloud database URLs', 'not-sent');
-    const reply = await this.#request('/warm', '{}', options, false);
-    if (!plainObject(reply) || !WARM_STATES.has(reply.state)) throw new ClientError('RDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
-    return { state: reply.state };
-  }
-  async read(statements, options = {}) {
-    this.#assertOpen();
-    if (this.#capabilities.readVersion !== 2) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support fresh reads', 'not-sent');
-    if (options.ifSequence !== undefined) throw new TypeError('fresh reads do not accept ifSequence');
-    const afterSequence = options.afterSequence ?? this.#sequence;
-    checkSequence(afterSequence);
-    const workLimits = encodeWorkLimits(options.workLimits);
-    const queryVersion = this.#queryVersion();
-    const body = JSON.stringify({ readVersion: 2, requestId: crypto.randomUUID(), afterSequence, statements: encodeStatements(statements, queryVersion), ...(workLimits === undefined ? {} : { workLimits }) });
-    checkBodySize(body, queryVersion);
-    const request = JSON.parse(body);
-    const reply = await this.#request('/read', body, options, false, undefined, queryVersion);
-    const result = confirmReply(reply, request, true);
-    this.#sequence = Math.max(this.#sequence, result.sequence);
-    this.#sequenceKnown = true;
-    return result;
-  }
-  prepareWrite(statements, options = {}) {
-    this.#assertOpen();
-    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) throw new ClientError('RDB_SEQUENCE_UNKNOWN', 'Read, call info() or pass afterSequence before preparing a write on a deferred connection', 'not-sent');
-    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support atomic writes with recovery', 'not-sent');
-    const afterSequence = options.afterSequence ?? this.#sequence;
-    checkSequence(afterSequence);
-    if (options.ifSequence !== undefined) {
-      if (this.#capabilities.exactSequenceCondition !== true) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support exact sequence conditions', 'not-sent');
-      checkSequence(options.ifSequence);
-      if (options.ifSequence < afterSequence) throw new RangeError('ifSequence must be at least afterSequence');
-    }
-    const requestId = options.requestId ?? crypto.randomUUID();
-    if (typeof requestId !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(requestId)) throw new TypeError('requestId requires 1..80 letters, digits, underscores or hyphens');
-    const workLimits = encodeWorkLimits(options.workLimits);
-    const queryVersion = this.#queryVersion();
-    const body = JSON.stringify({ requestId, afterSequence, ...(options.ifSequence === undefined ? {} : { ifSequence: options.ifSequence }), statements: encodeStatements(statements, queryVersion), ...(workLimits === undefined ? {} : { workLimits }) });
-    checkBodySize(body, queryVersion);
-    return Object.freeze({ version: 2, url: this.#url, databaseId: this.#id, queryVersion, body });
-  }
-  async submit(prepared, options = {}) {
-    this.#assertOpen();
-    const request = validatePrepared(prepared);
-    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64 || (request.ifSequence !== undefined && this.#capabilities.exactSequenceCondition !== true)) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
-    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('RDB_REQUEST_IDENTITY', 'Saved request belongs to another database', 'not-sent');
-    try {
-      const reply = await this.#request('/query', prepared.body, options, true, prepared, preparedQueryVersion(prepared));
-      const result = confirmReply(reply, request, false, prepared);
-      this.#sequence = Math.max(this.#sequence, result.sequence);
-      this.#sequenceKnown = true;
-      return result;
-    } catch (error) {
-      if (error instanceof ClientError) {
-        if (error.outcome === 'rolled-back') this.#sequence = Math.max(this.#sequence, error.sequence);
-        throw error;
-      }
-      throw new ClientError('RDB_PROTOCOL', 'Write response could not be confirmed; recover the saved request', 'unknown', { request: prepared });
-    }
-  }
-  async recover(prepared, options = {}) {
-    try { return await this.submit(prepared, options); }
-    catch (error) {
-      if (error instanceof ClientError && error.outcome === 'not-sent') throw new ClientError(error.code, 'Recovery did not confirm the earlier write; keep the saved request', 'unknown', { request: prepared });
-      throw error;
-    }
-  }
-  async writeAtomic(statements, options = {}) {
-    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) await this.info(options);
-    return this.submit(this.prepareWrite(statements, options), options);
-  }
-  async exportFile(options = {}) {
-    this.#assertOpen();
-    if (this.#transport) throw new ClientError('RDB_UNSUPPORTED', 'Export embedded databases through EmbeddedDatabase.exportFile', 'not-sent');
-    if (this.#cloud) throw new ClientError('RDB_UNSUPPORTED', 'Cloud databases do not export database files yet', 'not-sent');
-    if (!plainObject(options) || Object.keys(options).some(key => !['signal', 'timeoutMs'].includes(key))) throw new TypeError('export options take signal and timeoutMs');
-    const duration = timeout(options.timeoutMs ?? this.#timeout);
-    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
-    if (options.signal?.aborted) throw new ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent');
-    if (this.#active.size >= 32) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent');
-    const controller = new AbortController();
-    const abort = () => controller.abort();
-    options.signal?.addEventListener('abort', abort, { once: true });
-    const timer = setTimeout(abort, duration);
-    this.#active.add(controller);
-    let open = true;
-    const finish = () => {
-      if (!open) return;
-      open = false;
-      clearTimeout(timer);
-      options.signal?.removeEventListener('abort', abort);
-      this.#active.delete(controller);
-    };
-    const credential = this.#token;
-    let status;
-    try {
-      const response = await this.#fetch(this.#url + '/file', {
-        method: 'GET',
-        headers: { authorization: `Bearer ${credential}`, accept: `${DATABASE_FILE_TYPE}, application/json`, ...(this.#id === undefined ? {} : { 'x-romedb-database-id': this.#id }) },
-        redirect: 'manual', signal: controller.signal,
-      });
-      // The deadline covers building the copy; the caller's signal still stops the download.
-      clearTimeout(timer);
-      status = response.status;
-      if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', 'read-failed', { status });
-      if (!response.ok) {
-        const retryAfterMs = retryAfter(response.headers.get('retry-after'));
-        const reply = await boundedJson(response, MAX_RESPONSE).catch(() => undefined);
-        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
-        throw new ClientError(code, safeMessage(reply, credential), 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) });
-      }
-      const size = Number(/^\d{1,16}$/.exec(response.headers.get('content-length') ?? '')?.[0] ?? NaN);
-      const exported = Number(/^\d{1,16}$/.exec(response.headers.get('x-romedb-sequence') ?? '')?.[0] ?? NaN);
-      const identity = response.headers.get('x-romedb-database-id');
-      if ((response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase() !== DATABASE_FILE_TYPE || !Number.isSafeInteger(size) || !sequence(exported, true) || !response.body) {
-        throw new ClientError('RDB_PROTOCOL', 'Invalid database file response', 'read-failed', { status });
-      }
-      if (identity === null || (this.#id !== undefined && identity !== this.#id)) throw new ClientError('RDB_REQUEST_IDENTITY', 'Database file belongs to another database', 'read-failed', { status });
-      this.#id ??= identity;
-      this.#sequence = Math.max(this.#sequence, exported);
-      this.#sequenceKnown = true;
-      return { sequence: exported, size, body: countedBody(response.body, size, controller, finish) };
-    } catch (error) {
-      finish();
-      if (error instanceof ClientError) throw new ClientError(error.code, redactMessage(error.message, credential), error.outcome, { ...(error.status === undefined ? {} : { status: error.status }), ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }) });
-      throw new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL', 'Database file request failed', 'read-failed', { ...(status === undefined ? {} : { status }), cause: error });
-    }
-  }
-  async close() {
-    this.#closed = true;
-    for (const controller of this.#active) controller.abort();
-    this.#token = '';
-  }
-  #assertOpen() {
-    if (this.#closed) throw new ClientError('RDB_CLOSED', 'Database client is closed', 'not-sent');
-  }
-  #queryVersion() { return this.#cloud ? CLOUD_QUERY_VERSION : 2; }
-  async #request(path, body, options, writing, prepared, queryVersion = 2) {
-    this.#assertOpen();
-    const duration = timeout(options.timeoutMs ?? this.#timeout);
-    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
-    if (options.signal?.aborted) throw new ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent', prepared ? { request: prepared } : {});
-    const bodyBytes = body === undefined ? 0 : byteLength(body);
-    if (this.#active.size >= 32 || this.#inflightBytes + bodyBytes > 2_097_152) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent', prepared ? { request: prepared } : {});
-    const controller = new AbortController();
-    const abort = () => controller.abort();
-    options.signal?.addEventListener('abort', abort, { once: true });
-    const timer = setTimeout(abort, duration);
-    this.#active.add(controller);
-    this.#inflightBytes += bodyBytes;
-    const credential = this.#token;
-    const fetch = this.#fetch;
-    let status;
-    try {
-      if (this.#transport) return await this.#transport(path, body, controller.signal, duration);
-      const send = () => fetch(this.#url + path, {
-        method: body === undefined ? 'GET' : 'POST',
-        headers: { authorization: `Bearer ${credential}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...(this.#id === undefined ? {} : { 'x-romedb-database-id': prepared?.databaseId ?? this.#id }),
-          ...(queryVersion === CLOUD_QUERY_VERSION && (path === '/query' || path === '/read') ? { 'x-romedb-query-version': String(queryVersion) } : {}) },
-        ...(body === undefined ? {} : { body }),
-        // Workers have no redirect: 'error'; a redirect is refused below, never followed with the credential.
-        redirect: 'manual', signal: controller.signal,
-      });
-      let response = await send();
-      if (await queueRefused(response)) {
-        await pause(queueRetryDelay(response), controller.signal);
-        response = await send();
-      }
-      status = response.status;
-      if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) {
-        await response.body?.cancel().catch(() => {});
-        throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
-      }
-      const retryAfterMs = retryAfter(response.headers.get('retry-after'));
-      const replyVersion = response.headers.get('x-romedb-query-version');
-      if ((path === '/query' || path === '/read') && replyVersion !== null && replyVersion !== '2' && replyVersion !== String(queryVersion)) {
-        await response.body?.cancel();
-        throw new ClientError('RDB_PROTOCOL', 'Unsupported database query response version', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
-      }
-      const reply = await boundedJson(response, MAX_RESPONSE);
-      if (plainObject(reply?.error) && typeof reply.error.message === 'string') reply.error.message = redactMessage(reply.error.message, credential);
-      if (!response.ok && !(writing && reply?.requestId && reply?.sequence !== undefined)) {
-        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
-        throw new ClientError(code, safeMessage(reply, credential), writing ? 'unknown' : 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }), ...(prepared ? { request: prepared } : {}) });
-      }
-      return reply;
-    } catch (error) {
-      if (error instanceof ClientError) {
-        const outcome = writing
-          ? this.#transport && error.outcome === 'not-sent' ? 'not-sent' : 'unknown'
-          : error.outcome === 'not-sent' ? 'not-sent' : 'read-failed';
-        const message = this.#transport ? error.message.slice(0, 2048) : redactMessage(error.message, credential);
-        throw new ClientError(error.code, message, outcome, {
-          ...(error.status === undefined ? {} : { status: error.status }),
-          ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }),
-          ...(prepared ? { request: prepared } : {}),
-        });
-      }
-      const code = controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL';
-      throw new ClientError(code, writing ? 'Write was not confirmed; recover the saved request' : 'Database request failed', writing ? 'unknown' : 'read-failed', { ...(status === undefined ? {} : { status }), ...(prepared ? { request: prepared } : {}), cause: error });
-    } finally {
-      clearTimeout(timer);
-      options.signal?.removeEventListener('abort', abort);
-      this.#active.delete(controller);
-      this.#inflightBytes -= bodyBytes;
-    }
-  }
-}
-
-require('./client-internal.cjs').createEmbeddedClient = async (options, transport) => {
-  const database = new RemoteDatabase({ ...options, token: 'embedded' }, construction, transport);
-  try { await database.info(); return database; }
-  catch (error) { await database.close(); throw error; }
-};
-
-function normalizeFileUrl(input) {
-  if (typeof input !== 'string' || input.length > 4096) throw new TypeError('file URL requires a bounded local path');
-  const url = new URL(input);
-  if (url.protocol !== 'file:' || url.hostname || url.search || url.hash || url.pathname === '/' || /%2f|%5c|%00/i.test(url.pathname)) throw new TypeError('use a local file URL without a query or fragment');
-  return url.href;
-}
-
-function normalizeUrl(input) {
-  if (typeof input !== 'string' || input.length > 4096) throw new TypeError('url requires a bounded database URL');
-  // romedb:// is an alias for https://; the same checks apply after the rewrite.
-  const url = new URL(input.startsWith('romedb://') ? 'https://' + input.slice('romedb://'.length) : input);
-  const loopback = loopbackHost(url.hostname);
-  if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) throw new TypeError('use HTTPS or loopback HTTP without URL credentials, query or fragment');
-  let path = url.pathname.replace(/\/$/, '').replace(/\/(?:query|read)$/, '');
-  if (loopback && !path) path = '/v1/database';
-  const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}';
-  if (!(loopback && path === '/v1/database') && !new RegExp(`^/v1/organizations/${uuid}/databases/${uuid}$`).test(path)) throw new TypeError('use a local service URL or stable organization-scoped Cloud database URL');
-  return url.origin + path;
-}
-
-function encodeStatements(statements, queryVersion = 2) {
-  if (!Array.isArray(statements) || statements.length < 1 || statements.length > 32) throw new RangeError('request requires 1..32 statements');
-  return statements.map(statement => {
-    if (!plainObject(statement) || Object.keys(statement).some(key => !['sql', 'params'].includes(key)) || typeof statement.sql !== 'string' || !statement.sql.trim()) throw new TypeError('statement requires SQL and optional params');
-    if (statement.params === undefined) return { sql: text(statement.sql) };
-    if (!plainObject(statement.params)) throw new TypeError('params require an object');
-    return { sql: text(statement.sql), params: Object.fromEntries(Object.entries(statement.params).map(([key, value]) => [text(key), encodeValue(value, 0, queryVersion === CLOUD_QUERY_VERSION)])) };
-  });
-}
-
-function validatePrepared(prepared) {
-  const fields = prepared?.version === 1 ? 'body,databaseId,url,version' : 'body,databaseId,queryVersion,url,version';
-  if (!plainObject(prepared) || Object.keys(prepared).sort().join(',') !== fields || ![1, 2].includes(prepared.version) ||
-      (prepared.version === 2 && ![2, CLOUD_QUERY_VERSION].includes(prepared.queryVersion)) || typeof prepared.databaseId !== 'string' || !prepared.databaseId ||
-      (prepared.url?.startsWith('file:') ? normalizeFileUrl(prepared.url) : normalizeUrl(prepared.url)) !== prepared.url || typeof prepared.body !== 'string') throw new TypeError('invalid saved request');
-  checkBodySize(prepared.body, preparedQueryVersion(prepared));
-  const body = JSON.parse(prepared.body);
-  if (!plainObject(body) || Object.keys(body).some(key => !['requestId', 'afterSequence', 'ifSequence', 'statements', 'workLimits'].includes(key)) || typeof body.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(body.requestId)) throw new TypeError('invalid saved request identity');
-  encodeWorkLimits(body.workLimits);
-  checkSequence(body.afterSequence);
-  if (body.ifSequence !== undefined) {
-    checkSequence(body.ifSequence);
-    if (body.ifSequence < body.afterSequence) throw new RangeError('invalid saved sequence condition');
-  }
-  if (!Array.isArray(body.statements) || body.statements.length < 1 || body.statements.length > 32) throw new TypeError('invalid saved statements');
-  for (const statement of body.statements) {
-    if (!plainObject(statement) || Object.keys(statement).some(key => !['sql', 'params'].includes(key)) || typeof statement.sql !== 'string' || !statement.sql.trim() || (statement.params !== undefined && !plainObject(statement.params))) throw new TypeError('invalid saved statement');
-    for (const value of Object.values(statement.params ?? {})) decodeValue(value);
-  }
-  return body;
-}
-
-function confirmReply(reply, request, reading, prepared) {
-  const invalid = () => new ClientError('RDB_PROTOCOL', reading ? 'Read response identity or results differ' : 'Write response could not be confirmed; recover the saved request', reading ? 'read-failed' : 'unknown', prepared ? { request: prepared } : {});
-  if (!plainObject(reply) || reply.requestId !== request.requestId || !sequence(reply.sequence, true) || (reading ? reply.readVersion !== 2 || reply.sequence < request.afterSequence : reply.readVersion !== undefined || reply.sequence <= request.afterSequence || reply.sequence - request.afterSequence > 64)) throw invalid();
-  if (plainObject(reply.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]+$/.test(reply.error.code) && typeof reply.error.message === 'string' && reply.results === undefined) throw new ClientError(reply.error.code, reply.error.message.slice(0, 2048), reading ? 'read-failed' : 'rolled-back', { sequence: reply.sequence, request: prepared });
-  if (!Array.isArray(reply.results) || reply.results.length !== request.statements.length || reply.error !== undefined || byteLength(JSON.stringify(reply.results)) > 262_144) throw invalid();
-  try {
-    const results = reply.results.map(result => {
-      if (!plainObject(result) || !Array.isArray(result.columns) || result.columns.some(name => typeof name !== 'string') || !Array.isArray(result.rows) || result.rows.length > 1000 || typeof result.affected !== 'string' || !/^(?:0|[1-9][0-9]{0,19})$/.test(result.affected) || BigInt(result.affected) > (1n << 64n) - 1n) throw invalid();
-      return { columns: result.columns, rows: result.rows.map(row => {
-        if (!Array.isArray(row) || row.length !== result.columns.length) throw invalid();
-        return row.map(value => decodeValue(value));
-      }), affected: BigInt(result.affected) };
-    });
-    return { requestId: reply.requestId, sequence: reply.sequence, results, ...(reading ? { readVersion: 2 } : {}), ...(reply.executionWork === undefined ? {} : { executionWork: reply.executionWork }) };
-  } catch { throw invalid(); }
-}
-
-async function boundedJson(response, limit) {
-  if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type') ?? '')) throw new TypeError('response requires JSON');
-  if (!response.body) throw new TypeError('response body is missing');
-  const reader = response.body.getReader();
-  const chunks = [];
-  let length = 0;
-  try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      length += value.byteLength;
-      if (length > limit) throw new RangeError('response exceeds client byte limit');
-      chunks.push(value);
-    }
-    const bytes = new Uint8Array(length);
-    let offset = 0;
-    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
-    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
-  } finally { await reader.cancel().catch(() => {}); }
-}
-
-// Passes the download through and fails it unless exactly `size` bytes arrive.
-function countedBody(body, size, controller, finish) {
-  const reader = body.getReader();
-  let received = 0;
-  const failure = (message, cause) => new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : 'RDB_TRANSPORT', message, 'read-failed', cause === undefined ? {} : { cause });
-  return new ReadableStream({
-    async pull(stream) {
-      let chunk;
-      try { chunk = await reader.read(); }
-      catch (error) { finish(); stream.error(failure('Database file download failed', error)); return; }
-      if (chunk.done) {
-        finish();
-        if (received === size) stream.close();
-        else stream.error(failure('Database file ended before its declared size'));
-        return;
-      }
-      received += chunk.value.byteLength;
-      if (received > size) {
-        finish(); controller.abort();
-        stream.error(new ClientError('RDB_PROTOCOL', 'Database file is larger than its declared size', 'read-failed'));
-        return;
-      }
-      stream.enqueue(chunk.value);
-    },
-    cancel(reason) { finish(); controller.abort(); return reader.cancel(reason).catch(() => {}); },
-  }, { highWaterMark: 0 });
-}
-
-function loopbackHost(hostname) { return ['127.0.0.1', 'localhost', '[::1]'].includes(hostname); }
-
-function capabilities(url, info, local) {
-  if (local) {
-    if ((url.startsWith('file:') ? info.adapterVersion : info.serviceVersion) !== 1 || !plainObject(info.capabilities) || !plainObject(info.limits) || info.capabilities.readVersion !== 2 || typeof info.capabilities.atomicWrites !== 'boolean' || typeof info.capabilities.exactSequenceCondition !== 'boolean' || (info.capabilities.atomicWrites && info.capabilities.replayWindow !== 64)) throw new ClientError('RDB_PROTOCOL', 'Unsupported database client contract', 'read-failed');
-    return { ...info.capabilities, provenance: 'negotiated' };
-  }
-  return { provenance: 'documented', readVersion: 2, atomicWrites: true, replayWindow: 64, exactSequenceCondition: true, negotiatedLimits: false };
-}
-
-function sequence(value, reply = false) { return Number.isSafeInteger(value) && value >= 0 && value <= (reply ? MAX_SEQUENCE + 1 : MAX_SEQUENCE); }
-function encodeWorkLimits(value) {
-  if (value === undefined) return undefined;
-  const ceilings = { rowsRead: 1_000_000, rowMutations: 100_000, vmSteps: 10_000_000 };
-  if (!plainObject(value)) throw new TypeError('workLimits require an object');
-  for (const [name, limit] of Object.entries(value)) {
-    if (!Object.hasOwn(ceilings, name) || !Number.isSafeInteger(limit) || limit < 0 || limit > ceilings[name]) throw new RangeError('workLimits require nonnegative integers within the service ceilings');
-  }
-  return Object.fromEntries(Object.keys(ceilings).filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
-}
-function checkSequence(value) { if (!sequence(value)) throw new RangeError('sequence requires a nonnegative safe integer below Number.MAX_SAFE_INTEGER'); }
-function timeout(value) { if (!Number.isInteger(value) || value < 1 || value > 120_000) throw new RangeError('timeoutMs must be 1..120000'); return value; }
-function byteLength(text) { return encoder.encode(text).byteLength; }
-function checkBodySize(body, queryVersion = 2) {
-  if (byteLength(body) > (queryVersion === CLOUD_QUERY_VERSION ? MAX_CLOUD_REQUEST : MAX_REQUEST))
-    throw new RangeError(queryVersion === CLOUD_QUERY_VERSION ? 'request exceeds 1 MiB' : 'request exceeds 64 KiB');
-}
-function preparedQueryVersion(prepared) { return prepared.version === 1 ? 2 : prepared.queryVersion; }
-// Cloud refuses a queued request with 503 query_queue_* before dispatching it,
-// so nothing ran and one retry is safe for reads and writes alike.
-async function queueRefused(response) {
-  if (response.status !== 503) return false;
-  try { return /^query_queue_[a-z_]{1,40}$/.test((await response.clone().json())?.code ?? ''); } catch { return false; }
-}
-function queueRetryDelay(response) {
-  const header = response.headers.get('retry-after');
-  return header === null ? 0 : Math.min(retryAfter(header) ?? 1000, 2000);
-}
-// Retry-After holds delay seconds or an HTTP date.
-function retryAfter(value) {
-  if (value === null) return undefined;
-  if (/^\s*\d{1,9}(?:\.\d+)?\s*$/.test(value)) return Math.round(Number(value) * 1000);
-  const date = /GMT\s*$/.test(value) ? Date.parse(value) : NaN;
-  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
-}
-function pause(ms, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal.aborted) { reject(signal.reason); return; }
-    const timer = setTimeout(() => { signal.removeEventListener('abort', stop); resolve(); }, ms);
-    const stop = () => { clearTimeout(timer); reject(signal.reason); };
-    signal.addEventListener('abort', stop, { once: true });
-  });
-}
-function httpCode(status) { return status === 401 ? 'RDB_AUTH' : status === 403 ? 'RDB_FORBIDDEN' : status === 409 ? 'RDB_CONFLICT' : status === 429 || status === 413 ? 'RDB_LIMIT' : 'RDB_REMOTE'; }
-function redactMessage(message, token) { return (token ? message.replaceAll(token, '[redacted]') : message).slice(0, 2048); }
-function safeMessage(reply, token) { return redactMessage(typeof reply?.error === 'string' ? reply.error : typeof reply?.error?.message === 'string' ? reply.error.message : 'Database request was rejected', token); }
-
-async function saveRequest(path, request) { return require('./request-journal.cjs').saveRequest(path, request, validatePrepared); }
-async function loadRequest(path) { return require('./request-journal.cjs').loadRequest(path, validatePrepared); }
-
-module.exports = { connect, RemoteDatabase, ClientError, Float64, Record, Vector, encodeValue, decodeValue, normalizeUrl, validatePrepared, saveRequest, loadRequest };
+module.exports = require('@romedb/client');