turbine-orm 0.34.0 → 0.36.0

package/dist/cjs/generate.js

@@ -168,8 +168,13 @@ function generateTypes(schema, options) {
         for (const col of table.columns) {
             const pkNote = table.primaryKey.includes(col.name) ? ' (primary key)' : '';
             const nullNote = col.nullable ? ' (nullable)' : '';
-            lines.push(`  /** Column: ${col.name} — ${col.pgType}${pkNote}${nullNote} */`);
-            lines.push(`  ${col.field}: ${columnTsType(col, schema.enums)};`);
+            // PII columns are excluded from default projections, so the field is
+            // absent unless the query names it in `select` or passes `includePii`.
+            // The emitted type marks it optional so it tells the truth about absence.
+            const piiNote = col.pii ? ' (PII: absent unless selected or includePii)' : '';
+            const optional = col.pii ? '?' : '';
+            lines.push(`  /** Column: ${col.name}, ${col.pgType}${pkNote}${nullNote}${piiNote} */`);
+            lines.push(`  ${col.field}${optional}: ${columnTsType(col, schema.enums)};`);
         }
         lines.push('}');
         lines.push('');
@@ -531,6 +536,17 @@ function generateMetadata(schema, options) {
             lines.push(`        { name: '${escSQ(idx.name)}', columns: [${idx.columns.map((c) => `'${escSQ(c)}'`).join(', ')}], unique: ${idx.unique}, definition: ${JSON.stringify(idx.definition)} },`);
         }
         lines.push('      ],');
+        // checks: introspected named CHECK constraints. Emitted only when present
+        // (byte-stable for check-less tables) and sorted by name so `--no-timestamp`
+        // output is deterministic regardless of catalog row order.
+        if (table.checks && table.checks.length > 0) {
+            const sortedChecks = [...table.checks].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            lines.push('      checks: [');
+            for (const chk of sortedChecks) {
+                lines.push(`        { name: '${escSQ(chk.name)}', expression: ${JSON.stringify(chk.expression)} },`);
+            }
+            lines.push('      ],');
+        }
         // isView — read-only marker; the runtime write guard reads it.
         if (table.isView)
             lines.push('      isView: true,');
@@ -734,6 +750,11 @@ function serializeColumn(col) {
     if (col.generationExpression !== undefined) {
         parts.push(`generationExpression: '${escSQ(col.generationExpression)}'`);
     }
+    // PII marker: emitted only when set, so untagged schemas stay byte-identical.
+    // Introspection never sets this (code-first declaration), but a metadata
+    // object built from `defineSchema` (pii: true) carries it through codegen.
+    if (col.pii)
+        parts.push(`pii: true`);
     if (col.maxLength !== undefined)
         parts.push(`maxLength: ${col.maxLength}`);
     return `{ ${parts.join(', ')} }`;

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.DestructivePushRefusal = 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; } });
@@ -118,6 +119,7 @@ var schema_metadata_js_1 = require("./schema-metadata.js");
 Object.defineProperty(exports, "schemaDefToMetadata", { enumerable: true, get: function () { return schema_metadata_js_1.schemaDefToMetadata; } });
 // Schema SQL — generate DDL, diff, and push
 var schema_sql_js_1 = require("./schema-sql.js");
+Object.defineProperty(exports, "DestructivePushRefusal", { enumerable: true, get: function () { return schema_sql_js_1.DestructivePushRefusal; } });
 Object.defineProperty(exports, "schemaDiff", { enumerable: true, get: function () { return schema_sql_js_1.schemaDiff; } });
 Object.defineProperty(exports, "schemaPush", { enumerable: true, get: function () { return schema_sql_js_1.schemaPush; } });
 Object.defineProperty(exports, "schemaToSQL", { enumerable: true, get: function () { return schema_sql_js_1.schemaToSQL; } });

package/dist/cjs/mssql.js

@@ -459,6 +459,23 @@ function mssqlColumnType(type, maxLength) {
 // ---------------------------------------------------------------------------
 // mssqlDialect — the full Dialect contract for SQL Server 2016+
 // ---------------------------------------------------------------------------
+/**
+ * Render the SQL Server `OUTPUT` clause for a write's returning selection.
+ * `'*'` → ` OUTPUT INSERTED.*` (byte-identical to the historical default); a
+ * quoted column list → ` OUTPUT INSERTED.[c1], INSERTED.[c2]`; each column
+ * carries its own `INSERTED.`/`DELETED.` prefix (a bare comma list is invalid
+ * T-SQL). Used to exclude PII columns from a write's returned row. Empty
+ * selection → no clause.
+ */
+function mssqlOutput(returning, alias) {
+    if (!returning)
+        return '';
+    if (returning === '*')
+        return ` OUTPUT ${alias}.*`;
+    if (returning.length === 0)
+        return '';
+    return ` OUTPUT ${returning.map((col) => `${alias}.${col}`).join(', ')}`;
+}
 /**
  * SQL Server 2016+ implementation of the {@link Dialect} contract. Bracket
  * identifier quoting (`[…]`), named `@pN` placeholders, the `FOR JSON PATH`
@@ -483,6 +500,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',
@@ -517,7 +539,7 @@ exports.mssqlDialect = {
         return '';
     },
     buildInsertStatement(input) {
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES (${input.valuePlaceholders.join(', ')})`;
     },
     buildBulkInsertStatement(input) {
@@ -537,7 +559,7 @@ exports.mssqlDialect = {
         const placeholders = input.rowValues
             .map((row) => `(${row.map(() => this.paramPlaceholder(++n)).join(', ')})`)
             .join(', ');
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         // skipDuplicates has no single-statement equivalent here; ignored (documented).
         return {
             sql: `INSERT INTO ${input.table} (${input.columns.join(', ')})${out} VALUES ${placeholders}`,
@@ -552,7 +574,7 @@ exports.mssqlDialect = {
         const on = input.conflictColumns.map((c) => `T.${c} = S.${c}`).join(' AND ');
         const insertCols = input.insertColumns.join(', ');
         const sourceVals = input.insertColumns.map((c) => `S.${c}`).join(', ');
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return (`MERGE INTO ${input.table} AS T ` +
             `USING (VALUES (${input.valuePlaceholders.join(', ')})) AS S (${insertCols}) ` +
             `ON (${on}) ` +
@@ -563,11 +585,11 @@ exports.mssqlDialect = {
     // UPDATE/DELETE inject OUTPUT mid-statement (between SET and WHERE / FROM and
     // WHERE) — a trailing clause would be invalid T-SQL.
     buildUpdateStatement(input) {
-        const out = input.returning ? ` OUTPUT INSERTED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'INSERTED');
         return `UPDATE ${input.table} SET ${input.setClauses.join(', ')}${out}${input.whereSql}`;
     },
     buildDeleteStatement(input) {
-        const out = input.returning ? ` OUTPUT DELETED.${input.returning}` : '';
+        const out = mssqlOutput(input.returning, 'DELETED');
         return `DELETE FROM ${input.table}${out}${input.whereSql}`;
     },
     // SQL Server has no LIMIT — emit OFFSET/FETCH, injecting a stable ORDER BY when

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

@@ -90,7 +90,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PowqlInterface = exports.introspectPowdbDatabase = exports.PowdbEmbeddedPool = exports.PowdbPool = exports.DEFAULT_TX_QUEUE_TIMEOUT_MS = exports.POWQL_KEYWORDS = exports.ALL_POWDB_CAPABILITIES = exports.MIN_POWDB_VERSION = exports.PowdbJsonParam = exports.PowdbFloatParam = exports.powdbDialect = void 0;
+exports.PowqlInterface = exports.introspectPowdbDatabase = exports.PowdbEmbeddedPool = exports.POWQL_LEXER_TESTED_CEILING = exports.PowdbPool = exports.DEFAULT_TX_QUEUE_TIMEOUT_MS = exports.POWQL_KEYWORDS = exports.ALL_POWDB_CAPABILITIES = exports.MIN_POWDB_VERSION = exports.PowdbJsonParam = exports.PowdbFloatParam = exports.powdbDialect = void 0;
 exports.parsePowdbUrl = parsePowdbUrl;
 exports.assertSupportedPowdbVersion = assertSupportedPowdbVersion;
 exports.capabilitiesFromVersion = capabilitiesFromVersion;
@@ -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
@@ -1369,6 +1430,26 @@ function encodePowqlLiteral(value) {
         return encodePowqlString(value);
     throw new errors_js_1.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.
+ */
+exports.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 = '"';
@@ -1405,10 +1486,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 +1514,64 @@ 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.
+        //
+        // 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(exports.POWQL_LEXER_TESTED_CEILING);
+        if (engineSem &&
+            ceiling &&
+            (engineSem.major > ceiling.major || (engineSem.major === ceiling.major && engineSem.minor > ceiling.minor))) {
+            throw new errors_js_1.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 ` +
+                `(<= ${exports.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)));
     }
@@ -1462,6 +1591,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 +1675,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 +1753,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 +1801,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 +1839,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 +1854,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 +1881,7 @@ async function turbinePowDB(target, schema, options = {}) {
         logging: options.logging,
         defaultLimit: options.defaultLimit,
         warnOnUnlimited: options.warnOnUnlimited,
+        relationLoadStrategy: options.relationLoadStrategy,
         queryInterfaceFactory,
     }, schema);
     if (owns) {