turbine-orm 0.34.0 → 0.36.0

package/dist/powdb.d.ts

@@ -252,11 +252,13 @@ export interface PowdbCapabilities {
     docFieldIndexes: boolean;
     /** ≥ 0.10: `schema` / `describe` introspection statements. */
     introspection: boolean;
+    /** ≥ 0.13: server-side joins, hash-accelerated and bounded. */
+    serverJoins: boolean;
     /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
     nativeRaw: boolean;
 }
 /** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
-type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection';
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins';
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
  * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
@@ -439,6 +441,15 @@ export interface PowdbPoolOptions {
      * Default `false` (typed-error-only).
      */
     retryStaleReads?: boolean;
+    /**
+     * Mark this pool read-only: {@link PowqlInterface}'s exec seam then fails a
+     * write (or a tx-control `begin`) fast with a {@link ReadOnlyError} (E018)
+     * before it reaches the wire. An `{ embedded, readonly: true }` target forces
+     * this true; a networked pool bound to a read-only role can also set it so
+     * writes are rejected locally instead of round-tripping to the engine's
+     * refusal. Default `false`.
+     */
+    readonly?: boolean;
 }
 /**
  * A {@link PgCompatPool} backed by a `@zvndev/powdb-client` `Pool`. The query
@@ -476,6 +487,13 @@ export declare class PowdbPool implements PgCompatPool {
     readonly capabilities: PowdbCapabilities;
     /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
     readonly retryStaleReads: boolean;
+    /**
+     * True when the caller marked this pool read-only (`readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own read-only-role refusal (mapped by
+     * {@link wrapPowdbError}) is the backstop for raw / injected paths.
+     */
+    readonly readonly: boolean;
     constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam, options?: PowdbPoolOptions);
     /**
      * Run one statement on `c`, choosing the lossless native typed wire when the
@@ -503,6 +521,14 @@ interface EmbeddedQueryResult {
     affected?: bigint;
     message?: string;
 }
+/**
+ * The embedded addon's native typed result (`@zvndev/powdb-embedded` ≥ 0.14).
+ * Mirrors {@link PowdbRawNativeResult}, the same tagged {@link PowdbWireValue}
+ * cells (embedded `bytes` arrive as a `Buffer`, which IS a `Uint8Array`, so the
+ * decode path is unchanged), including the `message` kind for DDL / status
+ * replies, which {@link adaptNativeResult}'s default branch handles at runtime.
+ */
+type EmbeddedNativeResult = PowdbRawNativeResult;
 /** A single in-process embedded database handle (`@zvndev/powdb-embedded`). */
 interface EmbeddedDatabase {
     query(powql: string): EmbeddedQueryResult;
@@ -511,6 +537,32 @@ interface EmbeddedDatabase {
     isPoisoned(): boolean;
     /** WAL durability selector — `@zvndev/powdb-embedded` ≥ 0.7.1. */
     setSyncMode?(mode: string): void;
+    /**
+     * Lossless typed native wire (`@zvndev/powdb-embedded` ≥ 0.14). All optional
+     * and feature-detected: an older addon omits them, so {@link PowdbEmbeddedPool}
+     * falls back to {@link materializePowql} + {@link query}. `queryWithParams`
+     * binds positional `$N` params as {@link PowdbParam} values (the NativeParam
+     * union) instead of materializing literals.
+     */
+    queryNative?(powql: string): EmbeddedNativeResult;
+    queryReadonlyNative?(powql: string): EmbeddedNativeResult;
+    queryWithParams?(powql: string, params: PowdbParam[]): EmbeddedNativeResult;
+    /** Checkpoint-flushing close (`@zvndev/powdb-embedded` ≥ 0.14). Optional (feature-detected). */
+    close?(): void;
+}
+interface EmbeddedModule {
+    Database: {
+        open(dir: string): EmbeddedDatabase;
+        /** Open with a per-query memory budget — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+        openWithMemoryLimit?(dir: string, limitBytes: number): EmbeddedDatabase;
+        /**
+         * Open a read-only handle for snapshot serving (`@zvndev/powdb-embedded` ≥
+         * 0.14). Optional (feature-detected); a write through such a handle is
+         * refused with `readonly mode: statement requires a writer …` (→ E018).
+         */
+        openReadOnly?(dir: string): EmbeddedDatabase;
+        openReadOnlyWithMemoryLimit?(dir: string, limitBytes: number): EmbeddedDatabase;
+    };
 }
 /**
  * Encode a JS value as a **PowQL literal** for the embedded driver, which takes
@@ -528,6 +580,26 @@ interface EmbeddedDatabase {
  * as data and cannot break out of the literal or inject a second statement.
  */
 export declare function encodePowqlLiteral(value: unknown): string;
+/**
+ * The newest PowDB engine LINE (major.minor) whose lexer escape handling
+ * {@link encodePowqlString} is VERIFIED against by reading
+ * `crates/query/src/lexer.rs`. The legacy materialize path
+ * ({@link materializePowql}) inlines encoded string literals directly into query
+ * text, so it is only injection-safe while the lexer recognizes exactly the
+ * escape set the escaper emits (`\"`, `\\`, `\n`, `\t`, everything else raw). If
+ * a future engine line teaches the lexer new escapes (e.g. `\u`, `\x`), a string
+ * that the escaper leaves raw could be re-interpreted by the lexer and break out
+ * of the literal, turning the fallback into an injection primitive.
+ *
+ * CONTRACT: bump this ceiling ONLY after re-verifying the escape handling in
+ * `crates/query/src/lexer.rs` for the newer line AND confirming
+ * {@link encodePowqlString} still escapes every breakout vector the lexer
+ * recognizes. The legacy path guards on this value (see
+ * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
+ * the ceiling yet still routes through the string wire is refused rather than
+ * materialized.
+ */
+export declare const POWQL_LEXER_TESTED_CEILING = "0.15";
 /**
  * Substitute every `$N` placeholder in a generator-produced PowQL template with
  * the encoded literal of `params[N-1]`. Safe because the template is produced by
@@ -539,10 +611,14 @@ export declare function encodePowqlLiteral(value: unknown): string;
 export declare function materializePowql(powql: string, params: unknown[]): string;
 /**
  * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
- * `Database`. The embedded addon takes **no params array** — its `query(powql)`
- * accepts only a string — so this pool materializes each positional `$N` into a
- * PowQL literal via {@link materializePowql} before handing the text to the
- * engine. One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `Database`. On the addon's typed native wire (≥ 0.14, when
+ * `capabilities.nativeRaw` is set) this pool binds positional `$N` params via
+ * `queryWithParams` and decodes the typed cells, exactly like the networked
+ * transport. On an older addon (no `queryWithParams`) it falls back to the
+ * legacy string wire, which takes **no params array** (its `query(powql)`
+ * accepts only a string), so each positional `$N` is materialized into a PowQL
+ * literal via {@link materializePowql} before the text is handed to the engine.
+ * One handle, single connection: transaction keywords (`begin`/`commit`/
  * `rollback`) are issued serially as ordinary queries.
  */
 export declare class PowdbEmbeddedPool implements PgCompatPool {
@@ -563,14 +639,24 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     private readonly poolHoldRef;
     /**
      * Feature capabilities of the embedded engine (resolved from the addon
-     * package version). `nativeRaw` is always false: the embedded addon exposes
-     * no native typed-wire surface (its rows are `string[][]`, the legacy wire).
+     * package version). `nativeRaw` is true when the addon is ≥ 0.14 and the
+     * opened handle exposes `queryWithParams` (the typed native wire); an older
+     * addon has no such method, so it stays false and the legacy string wire is
+     * used.
      */
     readonly capabilities: PowdbCapabilities;
     /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
     readonly retryStaleReads: boolean;
+    /**
+     * True when this pool was opened read-only (an `{ embedded, readonly: true }`
+     * target, or a directly-constructed pool passed `readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own refusal (mapped by {@link wrapPowdbError}) is the
+     * backstop for raw / injected paths.
+     */
+    readonly readonly: boolean;
     constructor(db: EmbeddedDatabase, options?: PowdbPoolOptions);
-    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    /** Run the PowQL on the in-process engine, choosing the native or legacy wire. */
     private exec;
     /**
      * Run one statement, gating transaction control. `holdRef` scopes the gate
@@ -586,7 +672,17 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
 export { introspectPowdbDatabase, type PowdbExec, type PowdbIntrospectOptions, } from './powdb-introspect.js';
 export { PowqlInterface } from './powql.js';
 /** Options for {@link turbinePowDB}. */
-export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited' | 'relationLoadStrategy'> {
+    /**
+     * Client-level default `with`-relation load strategy. On PowDB the default is
+     * the batched N+1 loaders; setting `'join'` opts INTO native PowQL server-side
+     * joins for eligible top-level relations (ineligible ones, e.g. a paged parent
+     * or a nested `with`, fall back to the loaders per-relation and silently). A
+     * per-query `relationLoadStrategy` arg still overrides this. Requires an engine
+     * that advertises `serverJoins` (PowDB ≥ 0.13); a per-query `'join'` on an
+     * older engine throws E017, a client-level default silently falls back.
+     */
+    relationLoadStrategy?: TurbineConfig['relationLoadStrategy'];
     /** Max pooled connections (default 10). Networked transport only. */
     connectionLimit?: number;
     /**
@@ -623,6 +719,18 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * E017).
      */
     assumeEngineVersion?: string;
+    /**
+     * Mark the client read-only: a write (or a transaction `begin`) fails fast
+     * locally with a {@link ReadOnlyError} (E018) before it reaches the wire,
+     * rather than round-tripping to the engine's refusal. Works on both
+     * transports (a networked pool bound to a read-only role, or an embedded
+     * handle). An `{ embedded, readonly: true }` target implies this. Default
+     * `false`.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    readonly?: boolean;
     /**
      * Driver-module injection for the networked target forms (URL / host+port):
      * bypasses the dynamic `import('@zvndev/powdb-client')` and uses this object
@@ -630,6 +738,14 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * connections) and advanced embedding; everyday callers never set it.
      */
     powdbClientModule?: PowdbModule;
+    /**
+     * Driver-module injection for the **embedded** target form (`{ embedded }`):
+     * bypasses the dynamic `import('@zvndev/powdb-embedded')` and uses this object
+     * as the addon module instead. Intended for tests (a fake `Database` factory
+     * that records how the handle was opened) and advanced embedding; everyday
+     * callers never set it. The symmetric counterpart to {@link powdbClientModule}.
+     */
+    powdbEmbeddedModule?: EmbeddedModule;
 }
 /**
  * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`
@@ -655,6 +771,16 @@ export interface TurbinePowdbEmbeddedTarget {
     syncMode?: 'full' | 'normal' | 'off';
     /** Per-query memory budget in bytes (requires `@zvndev/powdb-embedded` ≥ 0.7.1). */
     memoryLimit?: number;
+    /**
+     * Open the data directory read-only for snapshot serving (requires
+     * `@zvndev/powdb-embedded` ≥ 0.14: `openReadOnly` / `openReadOnlyWithMemoryLimit`).
+     * A write through a read-only handle is refused by the engine with
+     * `readonly mode: statement requires a writer …` (→ {@link ReadOnlyError}, E018),
+     * and Turbine additionally fails writes fast locally (this implies the pool's
+     * `readonly` flag). Meaningless together with `syncMode` (a read-only engine
+     * never writes), setting both throws a {@link ValidationError}.
+     */
+    readonly?: boolean;
 }
 /**
  * Bind Turbine to PowDB. `target` is one of:

package/dist/powdb.js

@@ -55,7 +55,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
-import { ConnectionError, NotNullViolationError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import { ConnectionError, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
@@ -195,6 +195,7 @@ const POWDB_FEATURE_MIN_VERSION = {
     introspection: '0.10',
     jsonDocs: '0.12',
     docFieldIndexes: '0.13',
+    serverJoins: '0.13',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -209,6 +210,7 @@ export const ALL_POWDB_CAPABILITIES = {
     jsonDocs: true,
     docFieldIndexes: true,
     introspection: true,
+    serverJoins: true,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -236,6 +238,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
             jsonDocs: false,
             docFieldIndexes: false,
             introspection: false,
+            serverJoins: false,
             nativeRaw: false,
         };
     }
@@ -244,6 +247,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
         introspection: atLeastVersion(sem, 0, 10),
         jsonDocs: atLeastVersion(sem, 0, 12),
         docFieldIndexes: atLeastVersion(sem, 0, 13),
+        serverJoins: atLeastVersion(sem, 0, 13),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -688,9 +692,10 @@ export function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new NotNullViolationError({ column: m?.[1], cause: err });
     }
-    // Driver pool lifecycle errors (acquire after close, acquire timeout) carry
-    // no .code — classify by message so both transports surface E004.
-    if (/pool closed|pool acquire timeout/i.test(msg)) {
+    // Driver pool lifecycle errors (acquire after close, acquire timeout, or a
+    // statement reaching an already-closed embedded handle) carry no .code:
+    // classify by message so both transports surface E004.
+    if (/pool closed|pool acquire timeout|database is closed/i.test(msg)) {
         return new ConnectionError(`[turbine] PowDB connection unavailable: ${msg}`, { cause: err });
     }
     // Server-side transaction-gate wait bound (PowDB ≥ 0.10, default 5s): another
@@ -712,6 +717,54 @@ export function wrapPowdbError(err) {
         /received unexpected frame|unknown message type|truncated payload|bad framing/i.test(msg)) {
         return new ConnectionError(`[turbine] PowDB connection is in an invalid state: ${msg}`, { cause: err });
     }
+    // Read-only refusal → ReadOnlyError (E018). Two engine shapes, both mapped by
+    // substring (the networked transport prefixes the message with `query failed:
+    // `, so never anchor on the start): an embedded database opened read-only for
+    // snapshot serving (`readonly mode: statement requires a writer …`), and a
+    // networked read-only role (`permission denied: role '<role>' cannot execute
+    // write statements`). These run BEFORE the generic validation regex below so a
+    // read-only write is surfaced as the routing signal E018, not a query defect.
+    // The driver spec (0.15) distinguishes them via `reason`: snapshot mode
+    // means "nothing can write here; route writes to the primary", RBAC means
+    // "this connection's role may not write here".
+    if (/readonly mode: statement requires a writer/i.test(msg)) {
+        return new ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
+            cause: err,
+            reason: 'snapshot',
+        });
+    }
+    if (/permission denied: role/i.test(msg)) {
+        return new ReadOnlyError(`PowDB refused a write for a read-only role: ${msg}.`, { cause: err, reason: 'rbac' });
+    }
+    // Open-time read-only failure: a read-only handle over a directory whose WAL
+    // still has uncommitted frames is refused (`cannot open read-only: the WAL is
+    // not empty …`). It is a connection failure (E004), not a query defect, the
+    // fix is to recover the directory with a writable open first.
+    if (/cannot open read-only: the WAL is not empty/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB could not open the directory read-only: ${msg}. Open it once with a writable handle to ` +
+            'flush the WAL (recover the directory), then reopen it read-only for snapshot serving.', { cause: err });
+    }
+    // Per-query deadline → TimeoutError (E002). Message-path so it fires on the
+    // embedded transport too (code is always 'GenericFailure' there); retryable.
+    // Pass the engine prose through the message override (same pattern as the
+    // transaction-gate timeout below) so the real "query timeout after <n>ms"
+    // survives instead of rendering the placeholder "timed out after 0ms".
+    if (/query timeout after/i.test(msg)) {
+        return new TimeoutError(0, 'PowDB query', { message: `[turbine] PowDB ${msg}`, cause: err });
+    }
+    // Client-initiated cancellation → ConnectionError (E004). This is FINAL: the
+    // issuing client disconnected, so the query was a clean early return, never
+    // auto-retry it (the opt-in stale-read retry only replays stale-FRAME reads).
+    if (/query cancelled by client disconnect/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB query cancelled by client disconnect: ${msg}`, { cause: err });
+    }
+    // Bounded join rejection → ValidationError (E003). The engine rejects a pure
+    // nested-loop join whose candidate-pair count (or result row count) exceeds
+    // the safety bound BEFORE executing, and names the fix in the message, keep
+    // that fix-hint intact so the caller knows how to make the join eligible.
+    if (/nested-loop join would evaluate|join result exceeds row limit/i.test(msg)) {
+        return new ValidationError(`[turbine] PowDB join rejected: ${msg}`);
+    }
     // Type mismatch / parse / execution / storage / unexpected(token) / row too
     // large → validation (E003). On the embedded transport these are the only
     // signal we get (code is always 'GenericFailure'); on the networked path they
@@ -1052,12 +1105,20 @@ export class PowdbPool {
     capabilities;
     /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
     retryStaleReads;
+    /**
+     * True when the caller marked this pool read-only (`readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own read-only-role refusal (mapped by
+     * {@link wrapPowdbError}) is the backstop for raw / injected paths.
+     */
+    readonly;
     constructor(pool, toParam = (v) => toPowdbParam(v), options = {}) {
         this.pool = pool;
         this.toParam = toParam;
         this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
         this.capabilities = options.capabilities ?? ALL_POWDB_CAPABILITIES;
         this.retryStaleReads = options.retryStaleReads ?? false;
+        this.readonly = options.readonly ?? false;
     }
     /**
      * Run one statement on `c`, choosing the lossless native typed wire when the
@@ -1311,6 +1372,26 @@ export function encodePowqlLiteral(value) {
         return encodePowqlString(value);
     throw new ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal.`);
 }
+/**
+ * The newest PowDB engine LINE (major.minor) whose lexer escape handling
+ * {@link encodePowqlString} is VERIFIED against by reading
+ * `crates/query/src/lexer.rs`. The legacy materialize path
+ * ({@link materializePowql}) inlines encoded string literals directly into query
+ * text, so it is only injection-safe while the lexer recognizes exactly the
+ * escape set the escaper emits (`\"`, `\\`, `\n`, `\t`, everything else raw). If
+ * a future engine line teaches the lexer new escapes (e.g. `\u`, `\x`), a string
+ * that the escaper leaves raw could be re-interpreted by the lexer and break out
+ * of the literal, turning the fallback into an injection primitive.
+ *
+ * CONTRACT: bump this ceiling ONLY after re-verifying the escape handling in
+ * `crates/query/src/lexer.rs` for the newer line AND confirming
+ * {@link encodePowqlString} still escapes every breakout vector the lexer
+ * recognizes. The legacy path guards on this value (see
+ * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
+ * the ceiling yet still routes through the string wire is refused rather than
+ * materialized.
+ */
+export const POWQL_LEXER_TESTED_CEILING = '0.15';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';
@@ -1347,10 +1428,14 @@ export function materializePowql(powql, params) {
 }
 /**
  * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
- * `Database`. The embedded addon takes **no params array** — its `query(powql)`
- * accepts only a string — so this pool materializes each positional `$N` into a
- * PowQL literal via {@link materializePowql} before handing the text to the
- * engine. One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `Database`. On the addon's typed native wire (≥ 0.14, when
+ * `capabilities.nativeRaw` is set) this pool binds positional `$N` params via
+ * `queryWithParams` and decodes the typed cells, exactly like the networked
+ * transport. On an older addon (no `queryWithParams`) it falls back to the
+ * legacy string wire, which takes **no params array** (its `query(powql)`
+ * accepts only a string), so each positional `$N` is materialized into a PowQL
+ * literal via {@link materializePowql} before the text is handed to the engine.
+ * One handle, single connection: transaction keywords (`begin`/`commit`/
  * `rollback`) are issued serially as ordinary queries.
  */
 export class PowdbEmbeddedPool {
@@ -1371,20 +1456,64 @@ export class PowdbEmbeddedPool {
     poolHoldRef = { hold: null };
     /**
      * Feature capabilities of the embedded engine (resolved from the addon
-     * package version). `nativeRaw` is always false: the embedded addon exposes
-     * no native typed-wire surface (its rows are `string[][]`, the legacy wire).
+     * package version). `nativeRaw` is true when the addon is ≥ 0.14 and the
+     * opened handle exposes `queryWithParams` (the typed native wire); an older
+     * addon has no such method, so it stays false and the legacy string wire is
+     * used.
      */
     capabilities;
     /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
     retryStaleReads;
+    /**
+     * True when this pool was opened read-only (an `{ embedded, readonly: true }`
+     * target, or a directly-constructed pool passed `readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own refusal (mapped by {@link wrapPowdbError}) is the
+     * backstop for raw / injected paths.
+     */
+    readonly;
     constructor(db, options = {}) {
         this.db = db;
         this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
         this.capabilities = options.capabilities ?? ALL_POWDB_CAPABILITIES;
         this.retryStaleReads = options.retryStaleReads ?? false;
+        this.readonly = options.readonly ?? false;
     }
-    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    /** Run the PowQL on the in-process engine, choosing the native or legacy wire. */
     exec(powql, params) {
+        // Native typed wire (addon ≥ 0.14): bind positional params with the SAME
+        // binder the networked transport uses ({@link toPowdbParam} yields exactly
+        // the NativeParam union null|bigint|number|boolean|string) and decode the
+        // typed cells: a genuine str "null" survives, a json-null document stays
+        // distinct from an absent value. Gated on the resolved capability AND a
+        // per-call feature-detect so a heterogeneous injected handle cannot crash.
+        if (this.capabilities.nativeRaw && typeof this.db.queryWithParams === 'function') {
+            const bound = params.map((v) => toPowdbParam(v));
+            return adaptNativeResult(this.db.queryWithParams(powql, bound));
+        }
+        // Legacy string wire (addon < 0.14): the engine takes no params array, so
+        // materialize each `$N` into a PowQL literal. Byte-for-byte unchanged, kept
+        // live and tested as the pre-0.14 fallback.
+        //
+        // Safety assertion (see {@link POWQL_LEXER_TESTED_CEILING}): an addon whose
+        // engine line EXCEEDS the escaper's verified lexer ceiling must never be
+        // materialized: a newer lexer may recognize escapes the escaper leaves raw,
+        // making the inline path an injection primitive. Reachability: addons >= 0.14
+        // expose `queryWithParams` and take the native path above, so the ONLY way to
+        // reach this branch with a newer-than-ceiling engine is the anomalous
+        // newer-addon-without-native case (feature-detect failed). Refuse it rather
+        // than inline-encode against an unverified lexer.
+        const engineSem = parsePowdbSemver(this.capabilities.engineVersion);
+        const ceiling = parsePowdbSemver(POWQL_LEXER_TESTED_CEILING);
+        if (engineSem &&
+            ceiling &&
+            (engineSem.major > ceiling.major || (engineSem.major === ceiling.major && engineSem.minor > ceiling.minor))) {
+            throw new ValidationError(`[turbine] Refusing the PowDB legacy string wire: this embedded addon reports engine ` +
+                `${this.capabilities.engineVersion}, which is newer than the escaper's verified lexer range ` +
+                `(<= ${POWQL_LEXER_TESTED_CEILING}) AND such an addon exposes the parameterized native API, so ` +
+                `reaching the legacy materialize path means the queryWithParams feature-detect failed. Upgrade ` +
+                `turbine-orm so its PowQL escaper is verified against this engine line before running on it.`);
+        }
         const materialized = materializePowql(powql, params);
         return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }
@@ -1404,6 +1533,15 @@ export class PowdbEmbeddedPool {
             // transaction callback throws re-entrant E017 fast; independent
             // concurrent ones wait their FIFO turn.
             holdRef.hold = await this.txGate.acquire();
+            // The gate may have handed us the slot AFTER disconnect() closed the
+            // handle (a transaction queued behind an in-flight one, released as the
+            // pool shut down). Re-check before touching the now-closed engine, and
+            // release the slot we just took so the queue keeps draining.
+            if (this.closed) {
+                holdRef.hold.finish();
+                holdRef.hold = null;
+                throw new ConnectionError('[turbine] The PowDB embedded pool is closed: disconnect() was already called on this client.');
+            }
         }
         if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
             // This context never acquired the gate — its `begin` never ran (the
@@ -1479,13 +1617,15 @@ export class PowdbEmbeddedPool {
     async end() {
         if (this.closed)
             return;
-        // The addon exposes no explicit close — drop the reference and let GC /
-        // the engine's checkpoint flush. Marking the pool closed makes later
-        // queries fail with a typed ConnectionError instead of silently running
-        // against a handle the caller believes is gone. Caveat: durability is
-        // checkpoint-bound, so hold the process open long enough for the final
-        // WAL flush in short scripts.
         this.closed = true;
+        // Addon ≥ 0.14 exposes an explicit checkpoint-flushing close(): call it so
+        // the final WAL flush completes deterministically before the handle is
+        // dropped. An older addon has no close, dropping the reference and letting
+        // GC / the engine's checkpoint flush is the fallback (durability is then
+        // checkpoint-bound, so a short script must hold the process open long enough
+        // for the final flush). Marking the pool closed makes later queries fail
+        // with a typed ConnectionError instead of running against a gone handle.
+        this.db.close?.();
     }
 }
 // ---------------------------------------------------------------------------
@@ -1552,12 +1692,34 @@ function resolveEmbeddedVersion() {
     return importOptionalPeer.peerPackageVersion('@zvndev/powdb-embedded');
 }
 /** Open an embedded database handle, wrapping engine open failures (corrupt dir, etc.). */
-async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion) {
-    const mod = await loadPowdbEmbedded();
-    const { embedded: dir, syncMode, memoryLimit } = target;
+async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion, injectedModule) {
+    const mod = injectedModule ?? (await loadPowdbEmbedded());
+    const { embedded: dir, syncMode, memoryLimit, readonly } = target;
+    // A read-only engine never writes, so a durability selector is meaningless
+    // there, reject the combination loudly rather than silently ignoring one.
+    if (readonly && syncMode !== undefined) {
+        throw new ValidationError('[turbine] embedded `syncMode` is meaningless with `readonly: true` (a read-only database never writes). Remove one.');
+    }
     let db;
     try {
-        if (memoryLimit !== undefined) {
+        if (readonly) {
+            // Read-only snapshot serving (addon ≥ 0.14): route to the openReadOnly*
+            // constructors; feature-detect and fail with a clear version hint if the
+            // installed addon predates them.
+            if (memoryLimit !== undefined) {
+                if (typeof mod.Database.openReadOnlyWithMemoryLimit !== 'function') {
+                    throw new ConnectionError('[turbine] embedded `readonly` + `memoryLimit` requires @zvndev/powdb-embedded >= 0.14 (openReadOnlyWithMemoryLimit).');
+                }
+                db = mod.Database.openReadOnlyWithMemoryLimit(dir, memoryLimit);
+            }
+            else {
+                if (typeof mod.Database.openReadOnly !== 'function') {
+                    throw new ConnectionError('[turbine] embedded `readonly: true` requires @zvndev/powdb-embedded >= 0.14 (the installed addon has no openReadOnly).');
+                }
+                db = mod.Database.openReadOnly(dir);
+            }
+        }
+        else if (memoryLimit !== undefined) {
             if (typeof mod.Database.openWithMemoryLimit !== 'function') {
                 throw new ConnectionError('[turbine] embedded `memoryLimit` requires @zvndev/powdb-embedded ≥ 0.7.1.');
             }
@@ -1578,11 +1740,19 @@ async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion) {
         }
         db.setSyncMode(syncMode);
     }
-    // Embedded exposes no native typed-wire surface, so nativeRaw is always false.
+    // Native typed wire is feature-detected on the OPENED handle: an addon ≥ 0.14
+    // exposes `queryWithParams`, so nativeRaw turns on (server-gate ≥ 0.13 still
+    // applies via the version); an older addon has no such method → false.
     const capabilities = capabilitiesFromVersion(assumeEngineVersion ?? resolveEmbeddedVersion(), {
-        hasNativeRaw: false,
+        hasNativeRaw: typeof db.queryWithParams === 'function',
+    });
+    // A read-only target forces the pool's readonly flag; otherwise honor whatever
+    // `poolOptions` (threaded from `options.readonly`) carried.
+    return new PowdbEmbeddedPool(db, {
+        ...poolOptions,
+        capabilities,
+        readonly: Boolean(readonly) || Boolean(poolOptions.readonly),
     });
-    return new PowdbEmbeddedPool(db, { ...poolOptions, capabilities });
 }
 /**
  * Bind Turbine to PowDB. `target` is one of:
@@ -1608,6 +1778,7 @@ export async function turbinePowDB(target, schema, options = {}) {
     const poolOptions = {
         transactionQueueTimeoutMs: options.transactionQueueTimeoutMs,
         retryStaleReads: options.retryStaleReads,
+        readonly: options.readonly,
     };
     const max = options.connectionLimit ?? 10;
     if (typeof target === 'string') {
@@ -1622,7 +1793,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         pool = target;
     }
     else if (isEmbeddedTarget(target)) {
-        pool = await openEmbeddedPool(target, poolOptions, options.assumeEngineVersion);
+        pool = await openEmbeddedPool(target, poolOptions, options.assumeEngineVersion, options.powdbEmbeddedModule);
         owns = true;
     }
     else if (isPowdbClientPool(target)) {
@@ -1649,6 +1820,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         logging: options.logging,
         defaultLimit: options.defaultLimit,
         warnOnUnlimited: options.warnOnUnlimited,
+        relationLoadStrategy: options.relationLoadStrategy,
         queryInterfaceFactory,
     }, schema);
     if (owns) {