turbine-orm 0.34.0 → 0.35.0

package/dist/cjs/client.js

@@ -111,15 +111,27 @@ class TransactionClient {
     schema;
     middlewares;
     queryOptions;
+    sourcePool;
     tableCache = new Map();
     savepointCounter = 0;
     /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
     dialect;
-    constructor(client, schema, middlewares, queryOptions) {
+    constructor(client, schema, middlewares, queryOptions, 
+    /**
+     * The parent pool this transaction runs on. Only its `readonly` and
+     * `capabilities` are read (both PowDB-only flags), so the transaction-scoped
+     * proxy pool built by {@link createTxPool} carries them through: without this
+     * a read-only client's `$transaction` writes bypass the E018 guard, and an
+     * older-engine client falls back to ALL_POWDB_CAPABILITIES inside the tx
+     * (emitting join PowQL a pre-0.13 engine rejects). Undefined / absent flags
+     * for a plain pg pool leave the proxy unchanged.
+     */
+    sourcePool) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
         this.queryOptions = queryOptions;
+        this.sourcePool = sourcePool;
         this.dialect = queryOptions?.dialect ?? dialect_js_1.postgresDialect;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
@@ -199,7 +211,7 @@ class TransactionClient {
         const client = this.client;
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
-        return {
+        const txPool = {
             query: async (textOrConfig, values) => {
                 try {
                     if (typeof textOrConfig === 'string') {
@@ -216,6 +228,14 @@ class TransactionClient {
             },
             connect: () => Promise.resolve(client),
         };
+        // Carry the parent pool's PowDB-only flags through so a transaction-scoped
+        // PowqlInterface reads the same read-only guard and capabilities it would
+        // outside the transaction (a plain pg pool has neither, so nothing changes).
+        if (this.sourcePool?.readonly !== undefined)
+            txPool.readonly = this.sourcePool.readonly;
+        if (this.sourcePool?.capabilities !== undefined)
+            txPool.capabilities = this.sourcePool.capabilities;
+        return txPool;
     }
 }
 exports.TransactionClient = TransactionClient;
@@ -884,8 +904,10 @@ class TurbineClient {
                     await client.query(cfg.sql, cfg.params);
                 }
             }
-            // Create the transaction client with typed table accessors
-            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
+            // Create the transaction client with typed table accessors. Pass the
+            // parent pool so its read-only guard + PowDB capabilities flow into the
+            // transaction-scoped proxy pool (see TransactionClient.createTxPool).
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions, this.pool);
             // Dynamically attach table accessors to tx
             for (const tableName of Object.keys(this.schema.tables)) {
                 const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());

package/dist/cjs/dialect.js

@@ -59,6 +59,7 @@ exports.postgresDialect = {
     supportsRLS: true,
     supportsAdvisoryLock: true,
     supportsLateralJoin: true,
+    explainQuery: { prefix: 'EXPLAIN' },
     paramPlaceholder(index) {
         return `$${index}`;
     },

package/dist/cjs/errors.js

@@ -6,7 +6,7 @@
  * All Turbine errors extend TurbineError which includes a `code` property.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
+exports.ReadOnlyError = exports.UnsupportedFeatureError = exports.OptimisticLockError = exports.PipelineError = exports.ExclusionConstraintError = exports.CheckConstraintError = exports.SerializationFailureError = exports.DeadlockError = exports.NotNullViolationError = exports.ForeignKeyError = exports.UniqueConstraintError = exports.CircularRelationError = exports.MigrationError = exports.RelationError = exports.ConnectionError = exports.ValidationError = exports.TimeoutError = exports.NotFoundError = exports.TurbineError = exports.TurbineErrorCode = void 0;
 exports.setErrorMessageMode = setErrorMessageMode;
 exports.getErrorMessageMode = getErrorMessageMode;
 exports.wrapPgError = wrapPgError;
@@ -29,6 +29,7 @@ exports.TurbineErrorCode = {
     OPTIMISTIC_LOCK: 'TURBINE_E015',
     EXCLUSION_VIOLATION: 'TURBINE_E016',
     UNSUPPORTED_FEATURE: 'TURBINE_E017',
+    READ_ONLY: 'TURBINE_E018',
 };
 /**
  * Prefix a human message with its stable error code so logs are greppable
@@ -503,6 +504,45 @@ class UnsupportedFeatureError extends TurbineError {
     }
 }
 exports.UnsupportedFeatureError = UnsupportedFeatureError;
+/**
+ * Thrown when a write or DDL statement is refused because the target is
+ * read-only. Two shapes reach here, both on PowDB:
+ *   - an embedded database opened read-only for snapshot serving refuses a write
+ *     with `readonly mode: statement requires a writer …`;
+ *   - a networked read-only role refuses a write with `permission denied: role
+ *     '<role>' cannot execute write statements` (translated by `wrapPowdbError`).
+ * It is also raised locally, before the wire, when a write is issued on a pool
+ * the caller marked read-only (fail-fast). The message carries the engine text
+ * plus a hint to route writes to a writable primary.
+ *
+ * NOT retryable: the same write against the same read-only target fails
+ * identically; route it to a writable primary instead.
+ */
+class ReadOnlyError extends TurbineError {
+    /**
+     * Why the write was refused. `'snapshot'`: the database itself is read-only
+     * (snapshot serving, an embedded `readonly: true` open, or the client-level
+     * fail-fast flag), so NOTHING can write here and writes must route to the
+     * primary. `'rbac'`: the database is writable but THIS connection's role may
+     * not write (per-connection permission), so re-authenticating may suffice.
+     */
+    reason;
+    /**
+     * @param detail human-readable description of the refused write (the engine
+     *   message, or a local fail-fast description). A "route writes to a writable
+     *   primary" hint is always appended.
+     * @param options optional driver `cause` to preserve when wrapping a refusal,
+     *   and the refusal `reason` (default `'snapshot'`).
+     */
+    constructor(detail, options) {
+        super(exports.TurbineErrorCode.READ_ONLY, `[turbine] ${detail} Route writes to a writable primary.`, {
+            cause: options?.cause,
+        });
+        this.name = 'ReadOnlyError';
+        this.reason = options?.reason ?? 'snapshot';
+    }
+}
+exports.ReadOnlyError = ReadOnlyError;
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ColumnBuilder = exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = void 0;
+exports.applyManyToManyRelations = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -63,6 +63,7 @@ Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: functio
 Object.defineProperty(exports, "NotNullViolationError", { enumerable: true, get: function () { return errors_js_1.NotNullViolationError; } });
 Object.defineProperty(exports, "OptimisticLockError", { enumerable: true, get: function () { return errors_js_1.OptimisticLockError; } });
 Object.defineProperty(exports, "PipelineError", { enumerable: true, get: function () { return errors_js_1.PipelineError; } });
+Object.defineProperty(exports, "ReadOnlyError", { enumerable: true, get: function () { return errors_js_1.ReadOnlyError; } });
 Object.defineProperty(exports, "RelationError", { enumerable: true, get: function () { return errors_js_1.RelationError; } });
 Object.defineProperty(exports, "SerializationFailureError", { enumerable: true, get: function () { return errors_js_1.SerializationFailureError; } });
 Object.defineProperty(exports, "setErrorMessageMode", { enumerable: true, get: function () { return errors_js_1.setErrorMessageMode; } });

package/dist/cjs/mssql.js

@@ -483,6 +483,11 @@ exports.mssqlDialect = {
     supportsLateralJoin: false,
     // sp_getapplock / sp_releaseapplock exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
+    // No in-band EXPLAIN: SQL Server's SHOWPLAN is a session toggle
+    // (SET SHOWPLAN_ALL ON), not a statement prefix, so a compiled query cannot
+    // be explained in one round-trip. Override the inherited Postgres `EXPLAIN`
+    // to absent → QueryInterface.explain() throws E017.
+    explainQuery: undefined,
     // FOR JSON over zero rows is NULL → coalesced in the relation override.
     aggSupportsInlineOrderBy: false,
     jsonPathSupport: 'limited',

package/dist/cjs/mysql.js

@@ -384,6 +384,10 @@ exports.mysqlDialect = {
     supportsLateralJoin: false,
     // GET_LOCK / RELEASE_LOCK exist (used by a future migrate adapter).
     supportsAdvisoryLock: true,
+    // Plain `EXPLAIN` (one row of tabular plan columns) works on every supported
+    // MySQL 8.0.x; the readable `FORMAT=TREE` variant only exists from 8.0.16 and
+    // the engine floor here is 8.0.0. Plan text is a diagnostic, not a contract.
+    explainQuery: { prefix: 'EXPLAIN' },
     // JSON_ARRAYAGG has no inline ORDER BY argument → force the inner-subquery
     // rewrite for every ordered to-many relation.
     aggSupportsInlineOrderBy: false,

package/dist/cjs/powdb.js

@@ -252,6 +252,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
@@ -266,6 +267,7 @@ exports.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`. */
@@ -293,6 +295,7 @@ function capabilitiesFromVersion(version, opts = {}) {
             jsonDocs: false,
             docFieldIndexes: false,
             introspection: false,
+            serverJoins: false,
             nativeRaw: false,
         };
     }
@@ -301,6 +304,7 @@ 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),
     };
 }
@@ -745,9 +749,10 @@ function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new errors_js_1.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 errors_js_1.ConnectionError(`[turbine] PowDB connection unavailable: ${msg}`, { cause: err });
     }
     // Server-side transaction-gate wait bound (PowDB ≥ 0.10, default 5s): another
@@ -769,6 +774,54 @@ function wrapPowdbError(err) {
         /received unexpected frame|unknown message type|truncated payload|bad framing/i.test(msg)) {
         return new errors_js_1.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 errors_js_1.ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
+            cause: err,
+            reason: 'snapshot',
+        });
+    }
+    if (/permission denied: role/i.test(msg)) {
+        return new errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.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
@@ -1109,12 +1162,20 @@ 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 ?? exports.DEFAULT_TX_QUEUE_TIMEOUT_MS);
         this.capabilities = options.capabilities ?? exports.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
@@ -1405,10 +1466,14 @@ 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.
  */
 class PowdbEmbeddedPool {
@@ -1429,20 +1494,44 @@ 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 ?? exports.DEFAULT_TX_QUEUE_TIMEOUT_MS);
         this.capabilities = options.capabilities ?? exports.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.
         const materialized = materializePowql(powql, params);
         return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }
@@ -1462,6 +1551,15 @@ 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 errors_js_1.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
@@ -1537,13 +1635,15 @@ 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?.();
     }
 }
 exports.PowdbEmbeddedPool = PowdbEmbeddedPool;
@@ -1613,12 +1713,34 @@ function resolveEmbeddedVersion() {
     return optional_peer_import_cjs_1.default.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 errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.ConnectionError('[turbine] embedded `memoryLimit` requires @zvndev/powdb-embedded ≥ 0.7.1.');
             }
@@ -1639,11 +1761,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:
@@ -1669,6 +1799,7 @@ 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') {
@@ -1683,7 +1814,7 @@ 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)) {
@@ -1710,6 +1841,7 @@ async function turbinePowDB(target, schema, options = {}) {
         logging: options.logging,
         defaultLimit: options.defaultLimit,
         warnOnUnlimited: options.warnOnUnlimited,
+        relationLoadStrategy: options.relationLoadStrategy,
         queryInterfaceFactory,
     }, schema);
     if (owns) {