turbine-orm 0.33.0 → 0.35.0

package/dist/powdb.d.ts

@@ -91,7 +91,21 @@ export declare class PowdbFloatParam {
     readonly value: number;
     constructor(value: number);
 }
-/** The four shapes a PowQL result takes over the wire. */
+/**
+ * Marker wrapper for a JS object/array bound to a `json` document column. Both
+ * transports serialize `value` with `JSON.stringify` and send the text as a
+ * `str` param / string literal, exactly how the PowDB docs insert a json
+ * document (the engine validates it as JSON text and stores the canonical
+ * binary form). Constructed in {@link PowqlInterface.param} when the target
+ * column is `json` and the value is a non-null object/array; a JS string
+ * written to a json column passes through RAW (same contract as pg jsonb,
+ * pass `'"x"'` to store the JSON string `"x"`), and `null` stays `null`.
+ */
+export declare class PowdbJsonParam {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+/** The four shapes a PowQL result takes over the legacy string wire. */
 type PowdbResult = {
     kind: 'rows';
     columns: string[];
@@ -106,11 +120,73 @@ type PowdbResult = {
     kind: 'message';
     message: string;
 };
+/**
+ * Local structural mirror of `@zvndev/powdb-client`'s `WireValue` (the lossless
+ * typed cell of the native wire surface). Defined here rather than imported so
+ * the optional peer's types never leak into Turbine's published `.d.ts` (a
+ * consumer without the peer installed must still `tsc` cleanly, same rule as
+ * every other optional-peer type in this module). `empty` = an unset value
+ * (distinct, for a json column, from a JSON-null document, which is
+ * `{ type: 'json', value: null }`).
+ */
+type PowdbWireValue = {
+    type: 'empty';
+} | {
+    type: 'int';
+    value: bigint;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'bool';
+    value: boolean;
+} | {
+    type: 'str';
+    value: string;
+} | {
+    type: 'datetime';
+    value: bigint;
+} | {
+    type: 'uuid';
+    value: Uint8Array;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+} | {
+    type: 'json';
+    value: unknown;
+    pj1?: Uint8Array;
+};
+/** The native (lossless typed) result shape, mirroring `RawNativeQueryResult`. */
+type PowdbRawNativeResult = {
+    kind: 'rows';
+    columns: string[];
+    rows: PowdbWireValue[][];
+} | {
+    kind: 'scalar';
+    value: PowdbWireValue;
+} | {
+    kind: 'ok';
+    affected: bigint;
+} | {
+    kind: 'message';
+    message: string;
+};
 interface PowdbClient {
     readonly serverVersion: string;
     query(query: string, params?: PowdbParam[], opts?: {
         signal?: AbortSignal;
     }): Promise<PowdbResult>;
+    /**
+     * Lossless typed wire surface (client ≥ 0.13, server ≥ 0.13). Optional: an
+     * older client omits it, so every call site feature-detects
+     * `typeof c.queryNativeRaw === 'function'` before using it and falls back to
+     * {@link query}. It NEVER retries as a legacy query, replaying an ambiguous
+     * mutation is unsafe, so its use is additionally version-gated server-side.
+     */
+    queryNativeRaw?(query: string, params?: PowdbParam[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<PowdbRawNativeResult>;
     close(): Promise<void>;
 }
 interface PowdbClientPool {
@@ -159,16 +235,80 @@ export declare function parsePowdbUrl(connectionString: string): PowdbConnOption
  * prove it is too old).
  */
 export declare function assertSupportedPowdbVersion(version: string | undefined): void;
-/** PowQL column types Turbine is willing to emit (the four writable scalars). */
-export type PowqlType = 'str' | 'int' | 'float' | 'bool';
+/**
+ * Feature capabilities of a bound PowDB connection. Resolved once (from the
+ * probed server version on the networked transport, or the addon package
+ * version on embedded) and carried on the pool so {@link PowqlInterface} can
+ * gate PowQL features that only exist on newer engines, an old engine gets a
+ * typed {@link UnsupportedFeatureError} (E017) with a version hint instead of a
+ * raw PowQL parse error.
+ */
+export interface PowdbCapabilities {
+    /** Best-known engine version (e.g. `'0.13.0'`), or `null` when unknowable. */
+    engineVersion: string | null;
+    /** ≥ 0.12: `json` column type, `->` path filters / ordering / grouping. */
+    jsonDocs: boolean;
+    /** ≥ 0.13: `alter T add index (.col->seg)` expression indexes. */
+    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' | 'serverJoins';
+/**
+ * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
+ * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
+ * did not go through {@link turbinePowDB}'s version probe (e.g. an injected
+ * pool, or a unit-test pool). `nativeRaw` stays OFF here because it flips the
+ * actual wire path and must only be enabled after a real server-version probe,
+ * never inferred from a bare construction.
+ */
+export declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
+/**
+ * Derive {@link PowdbCapabilities} from an engine version string. A non-semver /
+ * unknown version turns every gate OFF (the E017 hint then tells the caller to
+ * upgrade or pass `assumeEngineVersion`). `nativeRaw` requires BOTH the client
+ * to expose `queryNativeRaw` (passed in) AND server ≥ 0.13.
+ */
+export declare function capabilitiesFromVersion(version: string | undefined | null, opts?: {
+    hasNativeRaw?: boolean;
+}): PowdbCapabilities;
+/**
+ * Throw a version-hinting {@link UnsupportedFeatureError} (E017) when a gated
+ * PowQL feature is used on an engine that does not support it. Keeps old engines
+ * getting clean typed errors instead of raw PowQL parse failures.
+ */
+export declare function requireCapability(caps: PowdbCapabilities, key: PowdbFeatureKey, feature: string): void;
+/**
+ * PowQL column types Turbine emits: the four writable scalars plus PowDB's
+ * native `json` document type (added to the map in the 0.12/0.13 parity round,
+ * see {@link isJsonColumn}). A `json` column stores a canonical binary document
+ * (sorted keys, int/float distinction preserved) that Turbine writes as a JSON
+ * string literal and reads back by parsing the canonical JSON text.
+ */
+export type PowqlType = 'str' | 'int' | 'float' | 'bool' | 'json';
+/**
+ * Does this column map to PowDB's native `json` document type? A Postgres
+ * `json`/`jsonb` type (via `dialectType`/`pgType`) is authoritative; otherwise
+ * the tsType heuristic (`Record<…>`, `object`, `unknown`, an object/array
+ * literal) that the four scalar branches do not claim. Array columns never map
+ * to json, a PowDB array only exists INSIDE a json document, so a Postgres
+ * array column has no PowDB shape and still throws in {@link powqlColumnType}.
+ */
+export declare function isJsonColumn(col: ColumnMetadata): boolean;
 /**
  * Map a Turbine column to the PowQL DDL type used in `defineSchema` →
  * `type T { … }`. Turbine never emits PowDB's `uuid`/`datetime`/`bytes` types,
  * which cannot hold client-supplied values on the wire (no literal, no cast):
  *   - `Date` → `int` (epoch micros)   - `boolean` → `bool`
  *   - integral `number`/`bigint` → `int`   - fractional `number` → `float`
+ *   - JSON / object columns → `json` (native PowDB document type, ≥ 0.12)
  *   - everything else (incl. UUID/PK strings) → `str`
- * Array / JSON / bytes columns throw — they have no PowDB equivalent.
+ * Array (non-json) and bytes columns throw, they have no PowDB equivalent.
  */
 export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
 /**
@@ -198,7 +338,18 @@ export declare const POWQL_KEYWORDS: ReadonlySet<string>;
  * errors when emitted bare, so quoting is strictly an improvement.
  */
 export declare function quotePowqlIdent(name: string): string;
-export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
+/**
+ * Options for {@link powqlSchemaDDL}. Additive: with no options the DDL is
+ * emitted unconditionally (pure-function callers / tests); pass `capabilities`
+ * to gate engine-version-specific features (json columns, and, since the
+ * 0.13 parity round, doc-field expression indexes) behind the connection's
+ * real capabilities. Doc-field expression index declarations plug into the
+ * per-table `indexes` surface consumed here without further signature churn.
+ */
+export interface PowqlSchemaDDLOptions {
+    capabilities?: PowdbCapabilities;
+}
+export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchemaDDLOptions): string[];
 /**
  * Coerce a single PowDB wire string into the JS value its column type implies.
  * Every PowDB value arrives as a string; NULL arrives as the bareword `"null"`.
@@ -206,12 +357,26 @@ export declare function powqlSchemaDDL(schema: SchemaMetadata): string[];
  */
 export declare function coerceValue(raw: string, col: ColumnMetadata): unknown;
 /**
- * Map one raw PowDB row (snake-cased columns → raw wire strings, as produced by
- * {@link PowdbPool}) into a typed entity (camelCase fields, coerced values).
- * Only the columns present in `raw` are emitted, so partial `select` projections
- * round-trip unchanged.
+ * Coerce a single cell that arrived over the NATIVE typed wire (decoded from a
+ * {@link PowdbWireValue}, so already a JS `bigint`/`number`/`boolean`/`string`/
+ * `NativeJson`/`Uint8Array`/`null`, never a bare `"null"` string). Unlike
+ * {@link coerceValue} this NEVER collapses the string `"null"` to `null`: an
+ * absent value already decoded to `null` (from the `empty` cell), so a genuine
+ * str `"null"` stays the string `"null"` (fixes the legacy-wire wart on the
+ * native transport). `datetime`-shaped cells (int micros) become `Date`; a
+ * bigint on a `number` column follows the int8 safe-integer policy.
+ */
+export declare function coerceNativeValue(value: unknown, col: ColumnMetadata): unknown;
+/**
+ * Map one raw PowDB row into a typed entity (camelCase fields, coerced values).
+ * Only the columns present in `raw` are emitted, so partial `select`
+ * projections round-trip unchanged. `native` selects the coercion policy: the
+ * default `false` handles the legacy string wire (every cell is a string, via
+ * {@link coerceValue}); `true` handles the native typed wire, where non-string
+ * cells arrive pre-typed and go through {@link coerceNativeValue} (see F3).
+ * Callers on the native transport pass `this.pool.capabilities.nativeRaw`.
  */
-export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata, native?: boolean): Record<string, unknown>;
 /**
  * Translate a PowDB error into a typed Turbine error. Handles BOTH transports,
  * whose error shapes differ:
@@ -226,6 +391,16 @@ export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMet
  * fire for both transports), then fall through to the networked `.code` switch.
  */
 export declare function wrapPowdbError(err: unknown): Error;
+/**
+ * True when `err` is the stale-wire-frame {@link ConnectionError} produced by
+ * {@link wrapPowdbError} (its `.cause` is a `protocol_error` PowDBError, or the
+ * message carries the invalid-state signature). The opt-in read retry
+ * (`retryStaleReads`, evaluated in {@link PowqlInterface}'s exec seam) uses this
+ * to decide whether a first-statement READ may be replayed once on a fresh
+ * connection; writes are NEVER retried (an ambiguous mutation reply is unsafe
+ * to replay, matching the client's own native-path policy).
+ */
+export declare function isStaleFramePowdbError(err: unknown): boolean;
 type QueryArg = string | {
     name?: string;
     text: string;
@@ -251,12 +426,40 @@ export interface PowdbPoolOptions {
      * *after* the transaction has begun.
      */
     transactionQueueTimeoutMs?: number;
+    /**
+     * Feature capabilities of the bound connection. Set by {@link turbinePowDB}
+     * from the probed engine version; defaults to {@link ALL_POWDB_CAPABILITIES}
+     * (feature gates on, `nativeRaw` off, engine version unknown) for a
+     * directly-constructed pool: a "trusted caller".
+     */
+    capabilities?: PowdbCapabilities;
+    /**
+     * Opt in to replaying a first-statement READ once, on a fresh connection,
+     * when it fails with the stale-wire-frame {@link ConnectionError} (see
+     * {@link isStaleFramePowdbError}). Networked only; writes and mid-transaction
+     * statements are NEVER retried. Read by {@link PowqlInterface}'s exec seam.
+     * 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
- * `text` is **PowQL**, not SQL — {@link PowqlInterface} generates it. Rows come
- * back as raw strings here; per-column JS coercion happens in `PowqlInterface`
- * (it owns the schema metadata).
+ * `text` is **PowQL**, not SQL ({@link PowqlInterface} generates it). On the
+ * legacy string wire cells come back as strings; when `capabilities.nativeRaw`
+ * is set (server ≥ 0.13 + a client exposing `queryNativeRaw`) this pool routes
+ * through the typed native wire instead, so cells arrive pre-typed (a json int
+ * as `bigint`, etc.) and each result is tagged with the wire that served it
+ * ({@link PowdbTaggedResult}). Per-column JS coercion still happens in
+ * `PowqlInterface` (it owns the schema metadata), keyed on that per-result tag.
  */
 export declare class PowdbPool implements PgCompatPool {
     readonly pool: PowdbClientPool;
@@ -280,7 +483,25 @@ export declare class PowdbPool implements PgCompatPool {
      * live socket holding the process open until the server's idle timeout.
      */
     private readonly checkedOut;
+    /** Feature capabilities of the bound server (probed version + native-wire feature-detect). */
+    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
+     * server supports it (`capabilities.nativeRaw`) AND this client exposes
+     * `queryNativeRaw` (a defensive per-call feature-detect, so a heterogeneous
+     * injected pool cannot crash). Otherwise the legacy string wire, unchanged.
+     */
+    private runOnClient;
     query(text: QueryArg, values?: unknown[]): Promise<any>;
     /**
      * Typed guard mirroring {@link PowdbEmbeddedPool}: after `end()` the driver
@@ -300,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;
@@ -308,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
@@ -336,10 +591,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 {
@@ -358,8 +617,26 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     private readonly txGate;
     /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
     private readonly poolHoldRef;
+    /**
+     * Feature capabilities of the embedded engine (resolved from the addon
+     * 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
@@ -372,9 +649,20 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     connect(): Promise<PgCompatPoolClient>;
     end(): Promise<void>;
 }
+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;
     /**
@@ -385,8 +673,44 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * transactions queue and run one at a time; only a re-entrant
      * `db.$transaction` (opened inside an active transaction callback) throws
      * E017 — queueing that shape would deadlock.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
      */
     transactionQueueTimeoutMs?: number;
+    /**
+     * Opt in to replaying a first-statement READ once (on a fresh connection)
+     * when it fails with the stale-wire-frame {@link ConnectionError} that a
+     * request can hit after a long idle gap. Networked only; WRITES and any
+     * statement inside a transaction are NEVER retried (an ambiguous mutation
+     * reply is unsafe to replay). Default `false`: the error is surfaced typed
+     * so the caller can decide. See the retry recipe in the docs.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    retryStaleReads?: boolean;
+    /**
+     * Override the detected engine version used for capability gating. For exotic
+     * deployments and injected pools whose version cannot be probed (a non-semver
+     * server string, or an addon whose package.json cannot be resolved): pass
+     * e.g. `'0.13.0'` to unlock the features that version supports. Without it, an
+     * undetectable version turns every version-gated feature OFF (with a hinting
+     * 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
@@ -394,6 +718,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`
@@ -419,6 +751,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: