turbine-orm 0.33.0 → 0.35.0

package/dist/powdb.js

@@ -55,7 +55,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
-import { ConnectionError, NotNullViolationError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import { ConnectionError, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 /**
  * Capability descriptor for PowDB. PowQL generation is owned by
@@ -124,6 +124,22 @@ export class PowdbFloatParam {
         this.value = value;
     }
 }
+/**
+ * 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 class PowdbJsonParam {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
 /** Minimum PowDB server version the networked transport requires. */
 export const MIN_POWDB_VERSION = '0.7.0';
 /**
@@ -174,19 +190,119 @@ export function assertSupportedPowdbVersion(version) {
     throw new ConnectionError(`[turbine] turbine-orm/powdb requires PowDB >= ${MIN_POWDB_VERSION}; the server reports "${version}". ` +
         'Upgrade the PowDB server (0.7.0 added the `returning` keyword and the int->float coercion fix Turbine relies on).');
 }
+/** Minimum engine version each gated feature needs, for the E017 hint text. */
+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
+ * 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 const ALL_POWDB_CAPABILITIES = {
+    engineVersion: null,
+    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`. */
+function parsePowdbSemver(version) {
+    const m = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(version ?? '').trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3] ?? 0) };
+}
+/** Is `sem` at least `major.minor`? */
+function atLeastVersion(sem, major, minor) {
+    return sem.major > major || (sem.major === major && sem.minor >= minor);
+}
+/**
+ * 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 function capabilitiesFromVersion(version, opts = {}) {
+    const sem = parsePowdbSemver(version);
+    if (!sem) {
+        return {
+            engineVersion: version ?? null,
+            jsonDocs: false,
+            docFieldIndexes: false,
+            introspection: false,
+            serverJoins: false,
+            nativeRaw: false,
+        };
+    }
+    return {
+        engineVersion: `${sem.major}.${sem.minor}.${sem.patch}`,
+        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),
+    };
+}
+/**
+ * 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 function requireCapability(caps, key, feature) {
+    if (caps[key])
+        return;
+    const min = POWDB_FEATURE_MIN_VERSION[key];
+    const reported = caps.engineVersion
+        ? `this connection reports ${caps.engineVersion}`
+        : 'this connection could not report a version';
+    throw new UnsupportedFeatureError(feature, 'PowDB', `${feature} requires PowDB >= ${min}; ${reported}. Upgrade powdb-server / @zvndev/powdb-embedded ` +
+        '(or pass `assumeEngineVersion` if the version cannot be detected).');
+}
+/**
+ * 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 function isJsonColumn(col) {
+    if (col.isArray)
+        return false;
+    const dbType = (col.dialectType ?? col.pgType ?? '').toLowerCase();
+    if (dbType === 'json' || dbType === 'jsonb')
+        return true;
+    const ts = col.tsType.replace(/\s*\|\s*null$/i, '').trim();
+    if (ts === 'Date' || ts === 'boolean' || ts === 'number' || ts === 'bigint' || ts === 'string')
+        return false;
+    if (ts === 'Buffer' || ts === 'Uint8Array')
+        return false;
+    return /Record<|object|unknown|\[\]|\{/.test(ts);
+}
 /**
  * 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 function powqlColumnType(col) {
     if (col.isArray) {
         throw new ValidationError(`[turbine] Column "${col.name}" is an array — PowDB has no array type. Arrays are unsupported on the PowDB backend.`);
     }
+    if (isJsonColumn(col))
+        return 'json';
     const ts = col.tsType.replace(/\s*\|\s*null$/i, '').trim();
     if (ts === 'Date')
         return 'int'; // epoch micros
@@ -201,9 +317,6 @@ export function powqlColumnType(col) {
     if (ts === 'Buffer' || ts === 'Uint8Array') {
         throw new ValidationError(`[turbine] Column "${col.name}" is binary — PowDB cannot store client-supplied bytes on the wire. Use a string (e.g. base64) instead.`);
     }
-    if (/Record<|object|unknown|\[\]|\{/.test(ts)) {
-        throw new ValidationError(`[turbine] Column "${col.name}" (${col.tsType}) maps to JSON/object, which PowDB has no type for. Flatten it or store a JSON string.`);
-    }
     return 'str';
 }
 /** Heuristic: does this numeric column hold fractional values (→ PowQL `float`)? */
@@ -343,7 +456,8 @@ export function quotePowqlIdent(name) {
     }
     return POWQL_KEYWORDS.has(name) || !POWQL_BARE_IDENT.test(name) ? `\`${name}\`` : name;
 }
-export function powqlSchemaDDL(schema) {
+export function powqlSchemaDDL(schema, opts = {}) {
+    const caps = opts.capabilities;
     const stmts = [];
     for (const meta of Object.values(schema.tables)) {
         const pkSet = new Set(meta.primaryKey);
@@ -354,6 +468,12 @@ export function powqlSchemaDDL(schema) {
         // cannot enforce the tuple's uniqueness at the engine level.
         const pkIsSingle = meta.primaryKey.length === 1;
         const fields = meta.columns.map((col) => {
+            const powqlType = powqlColumnType(col);
+            // Gate `json` columns behind the engine's jsonDocs capability when a
+            // caller supplied one, an old engine has no `json` type and would reject
+            // the DDL. Pure-function callers (no opts) emit unconditionally.
+            if (powqlType === 'json' && caps)
+                requireCapability(caps, 'jsonDocs', 'JSON document columns');
             const mods = [];
             if (!col.nullable || pkSet.has(col.name))
                 mods.push('required');
@@ -362,15 +482,57 @@ export function powqlSchemaDDL(schema) {
             // `auto` = server-generated monotonic int. PowDB requires it be `int` and
             // rejects it alongside a `default`; non-int generated columns fall back to
             // a plain typed column (Turbine assigns the value client-side instead).
-            if (col.isGenerated && powqlColumnType(col) === 'int')
+            if (col.isGenerated && powqlType === 'int')
                 mods.push('auto');
-            return `  ${mods.join(' ')}${mods.length ? ' ' : ''}${quotePowqlIdent(col.name)}: ${powqlColumnType(col)}`;
+            return `  ${mods.join(' ')}${mods.length ? ' ' : ''}${quotePowqlIdent(col.name)}: ${powqlType}`;
         });
         stmts.push(`type ${quotePowqlIdent(meta.name)} {\n${fields.join(',\n')}\n}`);
+        // Track which single columns already carry a unique constraint (the
+        // single-column PK is inlined `required unique` in the type body above) so
+        // a redundant `add unique .col` is never emitted twice.
+        const emittedUnique = new Set();
+        if (pkIsSingle && meta.primaryKey[0] !== undefined)
+            emittedUnique.add(meta.primaryKey[0]);
         // Secondary unique constraints (beyond the PK) become unique indexes.
         for (const uniq of meta.uniqueColumns) {
             if (uniq.length === 1 && !pkSet.has(uniq[0])) {
                 stmts.push(`alter ${quotePowqlIdent(meta.name)} add unique .${quotePowqlIdent(uniq[0])}`);
+                emittedUnique.add(uniq[0]);
+            }
+        }
+        // Declared indexes: PowDB doc-field expression indexes (docPath) and plain
+        // single-column indexes. A doc-field index MUST be parenthesized (the engine
+        // rejects a bare JSON path); string path segments emit lexer-exact via the
+        // shared `encodePowqlString`, integer array indexes emit bare. A json
+        // document column reference stays dotted-bare (`.col`), which bypasses
+        // keyword lookup on every engine version exactly like a filter path.
+        for (const idx of meta.indexes) {
+            const kind = idx.unique ? 'unique' : 'index';
+            if (idx.docPath) {
+                if (caps)
+                    requireCapability(caps, 'docFieldIndexes', 'JSON doc-field expression indexes');
+                const column = idx.columns[0];
+                if (column === undefined) {
+                    throw new ValidationError(`[turbine] Doc-field index "${idx.name}" on ${meta.name} has no target json column.`);
+                }
+                const segs = idx.docPath.map((s) => (typeof s === 'number' ? `->${s}` : `->${encodePowqlString(s)}`)).join('');
+                stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} (.${column}${segs})`);
+            }
+            else {
+                // Plain column index. PowDB has no composite index (`add index` takes a
+                // single `.column`), so a multi-column entry is a typed E017.
+                if (idx.columns.length !== 1) {
+                    throw new UnsupportedFeatureError('composite indexes', 'PowDB', `PowDB has no composite index. Index "${idx.name}" on ${meta.name} lists ` +
+                        `${idx.columns.length} columns; declare a single-column index (or a doc-field index) instead.`);
+                }
+                const column = idx.columns[0];
+                // A unique index whose column already carries a unique constraint (the
+                // PK, or a column-level unique) would be a redundant duplicate, so skip it.
+                if (idx.unique && emittedUnique.has(column))
+                    continue;
+                stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} .${quotePowqlIdent(column)}`);
+                if (idx.unique)
+                    emittedUnique.add(column);
             }
         }
     }
@@ -380,6 +542,10 @@ export function powqlSchemaDDL(schema) {
 function toPowdbParam(value, col) {
     if (value instanceof PowdbFloatParam)
         return value.value; // wire-side: a float column takes the plain number
+    // json document: serialize to canonical JSON text and bind as a str param,
+    // the engine validates it as JSON and stores the canonical binary form.
+    if (value instanceof PowdbJsonParam)
+        return JSON.stringify(value.value);
     if (value === undefined || value === null)
         return null;
     if (value instanceof Date)
@@ -402,10 +568,23 @@ function toPowdbParam(value, col) {
  */
 export function coerceValue(raw, col) {
     const ts = col.tsType.replace(/\s*\|\s*null$/i, '').trim();
+    const json = isJsonColumn(col);
     // NULL bareword: unambiguous for non-string columns; for `str` we cannot tell a
     // literal "null" from SQL NULL, so a nullable str of value "null" reads as null.
-    if (raw === 'null' && (ts !== 'string' || col.nullable))
+    // For a `json` column the bareword `null` (a legacy-wire rendering shared by an
+    // absent value AND a top-level JSON-null document, documented residual,
+    // resolved on the native transport by the WireValue path) maps to null; a JSON
+    // string document "null" renders WITH quotes (`"null"`) and parses distinctly.
+    if (raw === 'null' && (json || ts !== 'string' || col.nullable))
         return null;
+    if (json) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw; // defensive: canonical JSON text always parses
+        }
+    }
     if (ts === 'Date') {
         const micros = Number(raw);
         return Number.isFinite(micros) ? new Date(micros / 1000) : null;
@@ -422,19 +601,62 @@ export function coerceValue(raw, col) {
     return raw; // string / uuid-as-string
 }
 /**
- * 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 function coerceNativeValue(value, col) {
+    if (value === undefined || value === null)
+        return null;
+    if (isDateColumn(col)) {
+        if (typeof value === 'bigint')
+            return new Date(Number(value) / 1000);
+        if (typeof value === 'number')
+            return new Date(value / 1000);
+        return value;
+    }
+    const ts = col.tsType.replace(/\s*\|\s*null$/i, '').trim();
+    if (typeof value === 'bigint') {
+        if (ts === 'bigint')
+            return value;
+        if (ts === 'number') {
+            const n = Number(value);
+            return Number.isSafeInteger(n) ? n : value.toString(); // int8 policy: keep big ints as strings
+        }
+        return value;
+    }
+    return value; // number / boolean / string / NativeJson document / Uint8Array
+}
+/**
+ * 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 function rowToEntity(raw, meta) {
+export function rowToEntity(raw, meta, native = false) {
     const byName = new Map(meta.columns.map((c) => [c.name, c]));
     const out = {};
     for (const snake of Object.keys(raw)) {
         const col = byName.get(snake);
         const field = meta.reverseColumnMap[snake] ?? snake;
         const value = raw[snake];
-        out[field] = col && typeof value === 'string' ? coerceValue(value, col) : value;
+        if (!col) {
+            out[field] = value;
+        }
+        else if (native) {
+            out[field] = coerceNativeValue(value, col);
+        }
+        else {
+            out[field] = typeof value === 'string' ? coerceValue(value, col) : value;
+        }
     }
     return out;
 }
@@ -460,7 +682,7 @@ export function wrapPowdbError(err) {
     const e = err;
     const msg = e.message ?? 'unknown PowDB error';
     // Unique-constraint — message-based on both transports.
-    if (/unique constraint violation/i.test(msg)) {
+    if (/unique (constraint|expression index) violation/i.test(msg)) {
         const m = /on\s+\S+\.(\w+)/i.exec(msg);
         return new UniqueConstraintError({ constraint: m?.[1], cause: err });
     }
@@ -470,40 +692,123 @@ export function wrapPowdbError(err) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
         return new NotNullViolationError({ column: m?.[1], cause: err });
     }
-    // Driver pool lifecycle errors (acquire after close, acquire timeout) carry
-    // no .code — classify by message so both transports surface E004.
-    if (/pool closed|pool acquire timeout/i.test(msg)) {
-        return new ConnectionError(`[turbine] PowDB connection unavailable: ${msg}`);
+    // Driver pool lifecycle errors (acquire after close, acquire timeout, or a
+    // statement reaching an already-closed embedded handle) carry no .code:
+    // classify by message so both transports surface E004.
+    if (/pool closed|pool acquire timeout|database is closed/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB connection unavailable: ${msg}`, { cause: err });
     }
     // Server-side transaction-gate wait bound (PowDB ≥ 0.10, default 5s): another
     // connection held the single global write lock past the server's
     // --tx-wait-timeout-ms. Retryable timeout, not a query defect.
     if (/transaction gate timeout/i.test(msg)) {
-        return new TimeoutError(0, 'PowDB transaction gate');
+        return new TimeoutError(0, 'PowDB transaction gate', { cause: err });
+    }
+    // Stale / violated WIRE state → ConnectionError (E004), NOT a query defect.
+    // A `protocol_error`-class failure means the socket's framing state is gone
+    // (the client cannot safely reuse it and the pool must destroy it). The
+    // canonical trigger is the "received unexpected frame from server" that a
+    // fresh request hits after a multi-minute idle gap; sibling shapes are an
+    // unknown message type, a truncated payload, or bad framing. Runs BEFORE the
+    // validation regex below, whose `unexpected` token would otherwise misclass
+    // "received unexpected frame" as an E003 query defect. `.cause` preserved so
+    // callers (and the opt-in stale-read retry) can inspect the driver code.
+    if (e.code === 'protocol_error' ||
+        /received unexpected frame|unknown message type|truncated payload|bad framing/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB connection is in an invalid state: ${msg}`, { cause: err });
     }
-    // Type mismatch / parse / execution / storage / unexpected → validation
-    // (E003). On the embedded transport these are the only signal we get
-    // (code is always 'GenericFailure'); on the networked path they are a
-    // safety net before the .code switch.
+    // Read-only refusal → ReadOnlyError (E018). Two engine shapes, both mapped by
+    // substring (the networked transport prefixes the message with `query failed:
+    // `, so never anchor on the start): an embedded database opened read-only for
+    // snapshot serving (`readonly mode: statement requires a writer …`), and a
+    // networked read-only role (`permission denied: role '<role>' cannot execute
+    // write statements`). These run BEFORE the generic validation regex below so a
+    // read-only write is surfaced as the routing signal E018, not a query defect.
+    // The driver spec (0.15) distinguishes them via `reason`: snapshot mode
+    // means "nothing can write here; route writes to the primary", RBAC means
+    // "this connection's role may not write here".
+    if (/readonly mode: statement requires a writer/i.test(msg)) {
+        return new ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
+            cause: err,
+            reason: 'snapshot',
+        });
+    }
+    if (/permission denied: role/i.test(msg)) {
+        return new ReadOnlyError(`PowDB refused a write for a read-only role: ${msg}.`, { cause: err, reason: 'rbac' });
+    }
+    // Open-time read-only failure: a read-only handle over a directory whose WAL
+    // still has uncommitted frames is refused (`cannot open read-only: the WAL is
+    // not empty …`). It is a connection failure (E004), not a query defect, the
+    // fix is to recover the directory with a writable open first.
+    if (/cannot open read-only: the WAL is not empty/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB could not open the directory read-only: ${msg}. Open it once with a writable handle to ` +
+            'flush the WAL (recover the directory), then reopen it read-only for snapshot serving.', { cause: err });
+    }
+    // Per-query deadline → TimeoutError (E002). Message-path so it fires on the
+    // embedded transport too (code is always 'GenericFailure' there); retryable.
+    // Pass the engine prose through the message override (same pattern as the
+    // transaction-gate timeout below) so the real "query timeout after <n>ms"
+    // survives instead of rendering the placeholder "timed out after 0ms".
+    if (/query timeout after/i.test(msg)) {
+        return new TimeoutError(0, 'PowDB query', { message: `[turbine] PowDB ${msg}`, cause: err });
+    }
+    // Client-initiated cancellation → ConnectionError (E004). This is FINAL: the
+    // issuing client disconnected, so the query was a clean early return, never
+    // auto-retry it (the opt-in stale-read retry only replays stale-FRAME reads).
+    if (/query cancelled by client disconnect/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB query cancelled by client disconnect: ${msg}`, { cause: err });
+    }
+    // Bounded join rejection → ValidationError (E003). The engine rejects a pure
+    // nested-loop join whose candidate-pair count (or result row count) exceeds
+    // the safety bound BEFORE executing, and names the fix in the message, keep
+    // that fix-hint intact so the caller knows how to make the join eligible.
+    if (/nested-loop join would evaluate|join result exceeds row limit/i.test(msg)) {
+        return new ValidationError(`[turbine] PowDB join rejected: ${msg}`);
+    }
+    // Type mismatch / parse / execution / storage / unexpected(token) / row too
+    // large → validation (E003). On the embedded transport these are the only
+    // signal we get (code is always 'GenericFailure'); on the networked path they
+    // are a safety net before the .code switch.
     if (/type mismatch|\bParse\b|\bExecution\b|StorageError|unexpected|row too large/i.test(msg)) {
         return new ValidationError(`[turbine] PowDB query rejected: ${msg}`);
     }
     switch (e.code) {
         case 'connect_failed':
         case 'closed':
-            return new ConnectionError(`[turbine] PowDB connection failed: ${msg}`);
+            return new ConnectionError(`[turbine] PowDB connection failed: ${msg}`, { cause: err });
+        case 'auth_failed':
+            // Connection-establishment class, non-retryable: the handshake was
+            // rejected. Surface E004 with a concrete remediation hint instead of
+            // letting it fall through to the raw error.
+            return new ConnectionError(`[turbine] PowDB authentication failed: ${msg} (check the user / password / dbName for this connection).`, { cause: err });
         case 'timeout':
         case 'aborted':
-            return new TimeoutError(0, 'PowDB query');
+            return new TimeoutError(0, 'PowDB query', { cause: err });
         case 'query_failed':
         case 'type_coercion_failed':
-        case 'protocol_error':
         case 'size_exceeded':
             return new ValidationError(`[turbine] PowDB query rejected: ${msg}`);
         default:
-            return err instanceof Error ? err : new ConnectionError(`[turbine] PowDB error: ${msg}`);
+            return err instanceof Error ? err : new ConnectionError(`[turbine] PowDB error: ${msg}`, { cause: err });
     }
 }
+/**
+ * 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 function isStaleFramePowdbError(err) {
+    if (!(err instanceof ConnectionError))
+        return false;
+    const cause = err.cause;
+    if (cause && typeof cause === 'object' && cause.code === 'protocol_error')
+        return true;
+    return /PowDB connection is in an invalid state/.test(err.message);
+}
 function normalizeQueryArgs(arg, values) {
     if (typeof arg === 'string')
         return { text: arg, params: values ?? [] };
@@ -682,7 +987,7 @@ class PowdbTxGate {
         return hold;
     }
 }
-/** Adapt a PowDB result into the pg-compat `{ rows, rowCount, fields }` shape. */
+/** Adapt a PowDB (legacy string wire) result into the pg-compat `{ rows, rowCount, fields }` shape. */
 function adaptResult(r) {
     switch (r.kind) {
         case 'rows': {
@@ -693,21 +998,86 @@ function adaptResult(r) {
                 });
                 return o;
             });
-            return { rows, rowCount: rows.length, fields: r.columns.map((name) => ({ name, dataTypeID: 0 })) };
+            return { rows, rowCount: rows.length, fields: r.columns.map((name) => ({ name, dataTypeID: 0 })), native: false };
         }
         case 'ok':
-            return { rows: [], rowCount: Number(r.affected), fields: [] };
+            return { rows: [], rowCount: Number(r.affected), fields: [], native: false };
         case 'scalar':
-            return { rows: [{ value: r.value }], rowCount: 1, fields: [{ name: 'value', dataTypeID: 0 }] };
+            return { rows: [{ value: r.value }], rowCount: 1, fields: [{ name: 'value', dataTypeID: 0 }], native: false };
         default:
-            return { rows: [], rowCount: 0, fields: [] };
+            return { rows: [], rowCount: 0, fields: [], native: false };
+    }
+}
+/** Format 16 raw UUID bytes as a canonical `8-4-4-4-12` hex string. */
+function uuidBytesToHex(bytes) {
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    if (hex.length !== 32)
+        return hex; // defensive: non-16B payloads pass through as raw hex
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * Decode one native {@link PowdbWireValue} cell into a JS value. `empty` →
+ * `null` (an unset value; for a json column this cleanly distinguishes absent
+ * from a JSON-null document, which arrives as `{ type: 'json', value: null }`).
+ * `int`/`datetime` stay `bigint` so the row layer ({@link coerceNativeValue})
+ * applies the int8 policy / Date conversion by column; `uuid` becomes canonical
+ * hex; `bytes` stay `Uint8Array`; `json` passes the decoded document through
+ * with no re-parse (its `pj1` raw bytes are dropped).
+ */
+function decodeWireValue(cell) {
+    switch (cell.type) {
+        case 'empty':
+            return null;
+        case 'int':
+        case 'datetime':
+            return cell.value; // bigint; row layer decides Date vs number vs bigint per column
+        case 'float':
+        case 'bool':
+        case 'str':
+            return cell.value;
+        case 'uuid':
+            return uuidBytesToHex(cell.value);
+        case 'bytes':
+            return cell.value; // Uint8Array
+        case 'json':
+            return cell.value; // NativeJson document, already recursive data
+    }
+}
+/** Adapt a native (typed-wire) PowDB result into the pg-compat shape, decoding every {@link PowdbWireValue} cell. */
+function adaptNativeResult(r) {
+    switch (r.kind) {
+        case 'rows': {
+            const rows = r.rows.map((row) => {
+                const o = {};
+                r.columns.forEach((c, i) => {
+                    o[c] = decodeWireValue(row[i] ?? { type: 'empty' });
+                });
+                return o;
+            });
+            return { rows, rowCount: rows.length, fields: r.columns.map((name) => ({ name, dataTypeID: 0 })), native: true };
+        }
+        case 'ok':
+            return { rows: [], rowCount: Number(r.affected), fields: [], native: true };
+        case 'scalar':
+            return {
+                rows: [{ value: decodeWireValue(r.value) }],
+                rowCount: 1,
+                fields: [{ name: 'value', dataTypeID: 0 }],
+                native: true,
+            };
+        default:
+            return { rows: [], rowCount: 0, fields: [], native: true };
     }
 }
 /**
  * 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 class PowdbPool {
     pool;
@@ -731,10 +1101,37 @@ export class PowdbPool {
      * live socket holding the process open until the server's idle timeout.
      */
     checkedOut = new Set();
+    /** Feature capabilities of the bound server (probed version + native-wire feature-detect). */
+    capabilities;
+    /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
+    retryStaleReads;
+    /**
+     * True when the caller marked this pool read-only (`readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own read-only-role refusal (mapped by
+     * {@link wrapPowdbError}) is the backstop for raw / injected paths.
+     */
+    readonly;
     constructor(pool, toParam = (v) => toPowdbParam(v), options = {}) {
         this.pool = pool;
         this.toParam = toParam;
         this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
+        this.capabilities = options.capabilities ?? ALL_POWDB_CAPABILITIES;
+        this.retryStaleReads = options.retryStaleReads ?? false;
+        this.readonly = options.readonly ?? false;
+    }
+    /**
+     * Run one statement on `c`, choosing the lossless native typed wire when the
+     * 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.
+     */
+    async runOnClient(c, powql, params) {
+        const bound = params.map(this.toParam);
+        if (this.capabilities.nativeRaw && typeof c.queryNativeRaw === 'function') {
+            return adaptNativeResult(await c.queryNativeRaw(powql, bound));
+        }
+        return adaptResult(await c.query(powql, bound));
     }
     // biome-ignore lint/suspicious/noExplicitAny: pg-compat query is generic over the row shape.
     async query(text, values) {
@@ -755,8 +1152,7 @@ export class PowdbPool {
             return { rows: [], rowCount: 0, fields: [] };
         }
         try {
-            const result = await this.pool.withClient((c) => c.query(powql, params.map(this.toParam)));
-            return adaptResult(result);
+            return await this.pool.withClient((c) => this.runOnClient(c, powql, params));
         }
         catch (err) {
             if (ctl === 'begin') {
@@ -827,7 +1223,7 @@ export class PowdbPool {
                     return { rows: [], rowCount: 0, fields: [] };
                 }
                 try {
-                    return adaptResult(await client.query(powql, params.map(this.toParam)));
+                    return await this.runOnClient(client, powql, params);
                 }
                 catch (err) {
                     broken = true;
@@ -953,6 +1349,10 @@ export function encodePowqlLiteral(value) {
         // Force a float-form literal so an integer-valued float column stays a float.
         return Number.isInteger(n) ? `${n}.0` : String(n);
     }
+    // json document: emit the canonical JSON text as a PowQL string literal (the
+    // embedded engine validates and stores it as a json document).
+    if (value instanceof PowdbJsonParam)
+        return encodePowqlString(JSON.stringify(value.value));
     if (value === undefined || value === null)
         return 'null';
     if (value instanceof Date)
@@ -1008,10 +1408,14 @@ export function materializePowql(powql, params) {
 }
 /**
  * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
- * `Database`. The embedded addon takes **no params array** — its `query(powql)`
- * accepts only a string — so this pool materializes each positional `$N` into a
- * PowQL literal via {@link materializePowql} before handing the text to the
- * engine. One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `Database`. On the addon's typed native wire (≥ 0.14, when
+ * `capabilities.nativeRaw` is set) this pool binds positional `$N` params via
+ * `queryWithParams` and decodes the typed cells, exactly like the networked
+ * transport. On an older addon (no `queryWithParams`) it falls back to the
+ * legacy string wire, which takes **no params array** (its `query(powql)`
+ * accepts only a string), so each positional `$N` is materialized into a PowQL
+ * literal via {@link materializePowql} before the text is handed to the engine.
+ * One handle, single connection: transaction keywords (`begin`/`commit`/
  * `rollback`) are issued serially as ordinary queries.
  */
 export class PowdbEmbeddedPool {
@@ -1030,12 +1434,46 @@ export class PowdbEmbeddedPool {
     txGate;
     /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
     poolHoldRef = { hold: null };
+    /**
+     * 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.
+     */
+    capabilities;
+    /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
+    retryStaleReads;
+    /**
+     * True when this pool was opened read-only (an `{ embedded, readonly: true }`
+     * target, or a directly-constructed pool passed `readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own refusal (mapped by {@link wrapPowdbError}) is the
+     * backstop for raw / injected paths.
+     */
+    readonly;
     constructor(db, options = {}) {
         this.db = db;
         this.txGate = new PowdbTxGate(options.transactionQueueTimeoutMs ?? DEFAULT_TX_QUEUE_TIMEOUT_MS);
+        this.capabilities = options.capabilities ?? ALL_POWDB_CAPABILITIES;
+        this.retryStaleReads = options.retryStaleReads ?? false;
+        this.readonly = options.readonly ?? false;
     }
-    /** Materialize `$N` params and hand the PowQL to the in-process engine. */
+    /** Run the PowQL on the in-process engine, choosing the native or legacy wire. */
     exec(powql, params) {
+        // Native typed wire (addon ≥ 0.14): bind positional params with the SAME
+        // binder the networked transport uses ({@link toPowdbParam} yields exactly
+        // the NativeParam union null|bigint|number|boolean|string) and decode the
+        // typed cells: a genuine str "null" survives, a json-null document stays
+        // distinct from an absent value. Gated on the resolved capability AND a
+        // per-call feature-detect so a heterogeneous injected handle cannot crash.
+        if (this.capabilities.nativeRaw && typeof this.db.queryWithParams === 'function') {
+            const bound = params.map((v) => toPowdbParam(v));
+            return adaptNativeResult(this.db.queryWithParams(powql, bound));
+        }
+        // Legacy string wire (addon < 0.14): the engine takes no params array, so
+        // materialize each `$N` into a PowQL literal. Byte-for-byte unchanged, kept
+        // live and tested as the pre-0.14 fallback.
         const materialized = materializePowql(powql, params);
         return adaptResult(normalizeEmbeddedResult(this.db.query(materialized)));
     }
@@ -1055,6 +1493,15 @@ export class PowdbEmbeddedPool {
             // transaction callback throws re-entrant E017 fast; independent
             // concurrent ones wait their FIFO turn.
             holdRef.hold = await this.txGate.acquire();
+            // The gate may have handed us the slot AFTER disconnect() closed the
+            // handle (a transaction queued behind an in-flight one, released as the
+            // pool shut down). Re-check before touching the now-closed engine, and
+            // release the slot we just took so the queue keeps draining.
+            if (this.closed) {
+                holdRef.hold.finish();
+                holdRef.hold = null;
+                throw new ConnectionError('[turbine] The PowDB embedded pool is closed: disconnect() was already called on this client.');
+            }
         }
         if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
             // This context never acquired the gate — its `begin` never ran (the
@@ -1130,18 +1577,22 @@ export class PowdbEmbeddedPool {
     async end() {
         if (this.closed)
             return;
-        // The addon exposes no explicit close — drop the reference and let GC /
-        // the engine's checkpoint flush. Marking the pool closed makes later
-        // queries fail with a typed ConnectionError instead of silently running
-        // against a handle the caller believes is gone. Caveat: durability is
-        // checkpoint-bound, so hold the process open long enough for the final
-        // WAL flush in short scripts.
         this.closed = true;
+        // Addon ≥ 0.14 exposes an explicit checkpoint-flushing close(): call it so
+        // the final WAL flush completes deterministically before the handle is
+        // dropped. An older addon has no close, dropping the reference and letting
+        // GC / the engine's checkpoint flush is the fallback (durability is then
+        // checkpoint-bound, so a short script must hold the process open long enough
+        // for the final flush). Marking the pool closed makes later queries fail
+        // with a typed ConnectionError instead of running against a gone handle.
+        this.db.close?.();
     }
 }
 // ---------------------------------------------------------------------------
 // PowqlInterface — the PowQL query generator (Phase A: flat CRUD via returning)
 // ---------------------------------------------------------------------------
+// `describe`-based introspection (programmatic API; see powdb-introspect.ts).
+export { introspectPowdbDatabase, } from './powdb-introspect.js';
 export { PowqlInterface } from './powql.js';
 /**
  * Dynamically load `@zvndev/powdb-client`. Kept out of the static import graph so
@@ -1188,13 +1639,47 @@ async function loadPowdbEmbedded() {
     }
     return mod;
 }
+/**
+ * Resolve the embedded addon's engine version. The addon vendors the engine and
+ * exports no version, but `@zvndev/powdb-embedded/package.json` has no `exports`
+ * map, so a bare `require` of it resolves: the package version IS the engine
+ * version. Delegated to the `.cts` optional-peer helper so the resolution uses a
+ * real CommonJS `require` in BOTH build outputs; `import.meta.url` here would
+ * fail `tsc` under `tsconfig.cjs.json` (module: CommonJS) and crash any CJS
+ * consumer of `turbine-orm/powdb`. Returns `null` when it cannot be resolved.
+ */
+function resolveEmbeddedVersion() {
+    return importOptionalPeer.peerPackageVersion('@zvndev/powdb-embedded');
+}
 /** Open an embedded database handle, wrapping engine open failures (corrupt dir, etc.). */
-async function openEmbeddedPool(target, poolOptions = {}) {
-    const mod = await loadPowdbEmbedded();
-    const { embedded: dir, syncMode, memoryLimit } = target;
+async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion, injectedModule) {
+    const mod = injectedModule ?? (await loadPowdbEmbedded());
+    const { embedded: dir, syncMode, memoryLimit, readonly } = target;
+    // A read-only engine never writes, so a durability selector is meaningless
+    // there, reject the combination loudly rather than silently ignoring one.
+    if (readonly && syncMode !== undefined) {
+        throw new ValidationError('[turbine] embedded `syncMode` is meaningless with `readonly: true` (a read-only database never writes). Remove one.');
+    }
     let db;
     try {
-        if (memoryLimit !== undefined) {
+        if (readonly) {
+            // Read-only snapshot serving (addon ≥ 0.14): route to the openReadOnly*
+            // constructors; feature-detect and fail with a clear version hint if the
+            // installed addon predates them.
+            if (memoryLimit !== undefined) {
+                if (typeof mod.Database.openReadOnlyWithMemoryLimit !== 'function') {
+                    throw new ConnectionError('[turbine] embedded `readonly` + `memoryLimit` requires @zvndev/powdb-embedded >= 0.14 (openReadOnlyWithMemoryLimit).');
+                }
+                db = mod.Database.openReadOnlyWithMemoryLimit(dir, memoryLimit);
+            }
+            else {
+                if (typeof mod.Database.openReadOnly !== 'function') {
+                    throw new ConnectionError('[turbine] embedded `readonly: true` requires @zvndev/powdb-embedded >= 0.14 (the installed addon has no openReadOnly).');
+                }
+                db = mod.Database.openReadOnly(dir);
+            }
+        }
+        else if (memoryLimit !== undefined) {
             if (typeof mod.Database.openWithMemoryLimit !== 'function') {
                 throw new ConnectionError('[turbine] embedded `memoryLimit` requires @zvndev/powdb-embedded ≥ 0.7.1.');
             }
@@ -1215,7 +1700,19 @@ async function openEmbeddedPool(target, poolOptions = {}) {
         }
         db.setSyncMode(syncMode);
     }
-    return new PowdbEmbeddedPool(db, poolOptions);
+    // 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: 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),
+    });
 }
 /**
  * Bind Turbine to PowDB. `target` is one of:
@@ -1238,30 +1735,39 @@ async function openEmbeddedPool(target, poolOptions = {}) {
 export async function turbinePowDB(target, schema, options = {}) {
     let pool;
     let owns = false;
-    const poolOptions = { transactionQueueTimeoutMs: options.transactionQueueTimeoutMs };
+    const poolOptions = {
+        transactionQueueTimeoutMs: options.transactionQueueTimeoutMs,
+        retryStaleReads: options.retryStaleReads,
+        readonly: options.readonly,
+    };
+    const max = options.connectionLimit ?? 10;
     if (typeof target === 'string') {
         const mod = options.powdbClientModule ?? (await loadPowdb());
-        const clientPool = new mod.Pool({ ...parsePowdbUrl(target), max: options.connectionLimit ?? 10 });
-        await assertNetworkedVersion(clientPool);
-        pool = new PowdbPool(clientPool, undefined, poolOptions);
+        const clientPool = new mod.Pool({ ...parsePowdbUrl(target), max });
+        const capabilities = await assertNetworkedVersion(clientPool, options.assumeEngineVersion);
+        pool = new PowdbPool(clientPool, undefined, { ...poolOptions, capabilities });
         owns = true;
     }
     else if (target instanceof PowdbPool) {
-        // An injected PowdbPool carries its own PowdbPoolOptions.
+        // An injected PowdbPool carries its own PowdbPoolOptions (incl. capabilities).
         pool = target;
     }
     else if (isEmbeddedTarget(target)) {
-        pool = await openEmbeddedPool(target, poolOptions);
+        pool = await openEmbeddedPool(target, poolOptions, options.assumeEngineVersion, options.powdbEmbeddedModule);
         owns = true;
     }
     else if (isPowdbClientPool(target)) {
-        pool = new PowdbPool(target, undefined, poolOptions);
+        // Injected client pool: run the SAME probe as the URL / host+port paths so
+        // it gets real capabilities AND the version-floor check (this branch used
+        // to skip the probe entirely (an injected pool silently bypassed both).
+        const capabilities = await assertNetworkedVersion(target, options.assumeEngineVersion);
+        pool = new PowdbPool(target, undefined, { ...poolOptions, capabilities });
     }
     else {
         const mod = options.powdbClientModule ?? (await loadPowdb());
-        const clientPool = new mod.Pool({ ...target, max: options.connectionLimit ?? 10 });
-        await assertNetworkedVersion(clientPool);
-        pool = new PowdbPool(clientPool, undefined, poolOptions);
+        const clientPool = new mod.Pool({ ...target, max });
+        const capabilities = await assertNetworkedVersion(clientPool, options.assumeEngineVersion);
+        pool = new PowdbPool(clientPool, undefined, { ...poolOptions, capabilities });
         owns = true;
     }
     // The PowQL generator is loaded here to keep client.ts free of any PowDB import.
@@ -1274,6 +1780,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         logging: options.logging,
         defaultLimit: options.defaultLimit,
         warnOnUnlimited: options.warnOnUnlimited,
+        relationLoadStrategy: options.relationLoadStrategy,
         queryInterfaceFactory,
     }, schema);
     if (owns) {
@@ -1299,14 +1806,20 @@ export async function turbinePowDB(target, schema, options = {}) {
     return client;
 }
 /**
- * Probe a networked pool's `serverVersion` (declared on {@link PowdbClient}) and
- * fail fast if the server is older than {@link MIN_POWDB_VERSION}. Best-effort:
- * a driver that does not surface a version is left untouched (we cannot prove it
- * too old). Errors from the probe itself surface as the normal connect failure.
+ * Probe a networked pool's `serverVersion` (declared on {@link PowdbClient}),
+ * fail fast if the server is older than {@link MIN_POWDB_VERSION}, and derive
+ * the {@link PowdbCapabilities} for it: the version gates PLUS `nativeRaw`
+ * (server ≥ 0.13 AND the client exposes `queryNativeRaw`, feature-detected
+ * here). `assumeEngineVersion` overrides the version used for capability
+ * derivation (the floor check still runs against the real reported version).
+ * Errors from the probe itself surface as the normal connect failure.
  */
-async function assertNetworkedVersion(clientPool) {
-    await clientPool.withClient(async (c) => {
+async function assertNetworkedVersion(clientPool, assumeEngineVersion) {
+    return clientPool.withClient(async (c) => {
         assertSupportedPowdbVersion(c.serverVersion);
+        const version = assumeEngineVersion ?? c.serverVersion;
+        const hasNativeRaw = typeof c.queryNativeRaw === 'function';
+        return capabilitiesFromVersion(version, { hasNativeRaw });
     });
 }
 function isPowdbClientPool(x) {