turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/powdb.d.ts

@@ -0,0 +1,931 @@
+/**
+ * turbine-orm/powdb — Turbine's PowDB / PowQL backend.
+ *
+ * PowDB is a single-node embedded database with its own query language, **PowQL**
+ * (not SQL), reached over `@zvndev/powdb-client`'s binary TCP protocol. PowDB is a
+ * different shape than the SQL engines, so this module does NOT route through the
+ * SQL `Dialect` / `QueryInterface`: it ships a parallel {@link PowqlInterface} that
+ * generates PowQL, plugged into `TurbineClient` via the `queryInterfaceFactory`
+ * seam. The four SQL engines are untouched.
+ *
+ * PowDB realities shape the design (all verified firsthand against a live
+ * `powdb-server` / the embedded addon, see `docs/internal/strategy/powdb-parity-matrix.md`):
+ *   - **`RETURNING` (since 0.7.0)** — `create/createMany/update/delete` append the
+ *     trailing `returning` keyword (`RETURNING *`, all columns) and read the
+ *     affected rows back in one round-trip. `upsert` is the lone exception (its
+ *     statement rejects `returning`) and reselects by primary key.
+ *   - **No generated IDs** — the app must supply every value → Turbine generates a
+ *     client-side UUID for the primary key when it has a default.
+ *   - **`uuid`/`datetime`/`bytes` columns can't hold client-supplied values** (no
+ *     literal, no working cast on the wire) → Turbine maps everything onto the four
+ *     writable types (`str`/`int`/`float`/`bool`); `Date` → `int` epoch micros;
+ *     `string` PKs hold UUID strings.
+ *   - **No JSON aggregation / link navigation** — single-query nested `with` is
+ *     impossible → it degrades to batched N+1 loaders (Phase B).
+ *   - **Single global write lock; no savepoints/isolation** — nested
+ *     transactions / isolation / vector / LISTEN-NOTIFY / RLS throw.
+ *     Independent concurrent `db.$transaction` calls do NOT throw: they queue
+ *     FIFO on a pool-level gate and run one at a time (see {@link PowdbTxGate}).
+ *     Only a *re-entrant* transaction — a `db.$transaction` opened from inside
+ *     an active transaction callback's async context, which queueing would
+ *     deadlock — fails fast with E017.
+ *   - **The wire protocol pipelines** — `@zvndev/powdb-client` writes each
+ *     request frame immediately and matches replies FIFO, so multiple queries
+ *     may be in flight on one connection. {@link PowdbPool}'s checked-out
+ *     clients advertise `supportsPipelining`, which lets the batch
+ *     `$transaction([...])` overload dispatch all statements in one write
+ *     burst (~1 round trip) instead of one round trip per statement.
+ *
+ * `@zvndev/powdb-client` is an **optional peer dependency** loaded by dynamic
+ * import; `npm i turbine-orm` still pulls only `pg`.
+ *
+ * @example
+ * ```ts
+ * import { turbinePowDB } from 'turbine-orm/powdb';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = await turbinePowDB({ host: '127.0.0.1', port: 5433 }, SCHEMA);
+ * const user = await db.table('users').create({ data: { name: 'Ada' } }); // UUID id auto-generated
+ * const found = await db.table('users').findMany({ where: { name: 'Ada' }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ *
+ * @module
+ */
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect } from './dialect.js';
+import type { PowdbExec } from './powdb-introspect.js';
+import { type ColumnMetadata, type SchemaMetadata, type TableMetadata } from './schema.js';
+/**
+ * Capability descriptor for PowDB. PowQL generation is owned by
+ * {@link PowqlInterface} (not the SQL `Dialect`), so this dialect exists only to
+ * drive `TurbineClient`'s capability gating and transaction keywords:
+ *   - `supports*` flags are all `false` for the Postgres-only features, so
+ *     `$listen`/`$notify`, RLS `sessionContext`/`$withSession`, and pgvector
+ *     throw a clear {@link UnsupportedFeatureError} (E017) at the client surface
+ *     instead of emitting SQL that PowDB cannot parse.
+ *   - `begin`/`commit`/`rollback` are lowercase PowQL keywords (verified on the
+ *     wire) so a single-level `$transaction` works.
+ *   - PowDB has a single global write lock and supports neither savepoints nor
+ *     nested/concurrent transactions. The `savepoint*` keywords therefore throw
+ *     {@link UnsupportedFeatureError} (E017): a nested `tx.$transaction` emits a
+ *     savepoint synchronously (before any DB call) and so fails fast with a
+ *     clear typed error instead of leaking PowDB's cryptic `Parse(... 'sp_1')`.
+ *     The pool-level transaction gate (see {@link PowdbTxGate}) handles the
+ *     other shapes: a fresh top-level `db.$transaction` opened inside an
+ *     already-open one throws E017 before it can deadlock on the write lock,
+ *     while INDEPENDENT concurrent `db.$transaction` calls queue FIFO and run
+ *     one at a time instead of failing.
+ * Isolation levels remain Phase B.
+ */
+export declare const powdbDialect: Dialect;
+/** A single value PowDB accepts as a positional `$N` parameter. */
+type PowdbParam = string | number | bigint | boolean | null;
+/**
+ * Marker wrapper for a value bound to a `float` column. The networked driver
+ * unwraps it to the plain number (the wire param is unchanged), but the
+ * *embedded* literal encoder reads it to emit a float-form PowQL literal (`42`
+ * → `42.0`) so an integer-valued float column stays unambiguously a float.
+ * Constructed in {@link PowqlInterface.param}.
+ */
+export declare class PowdbFloatParam {
+    readonly value: number;
+    constructor(value: number);
+}
+/**
+ * Marker wrapper for a JS object/array bound to a `json` document column. Both
+ * transports serialize `value` with `JSON.stringify` and send the text as a
+ * `str` param / string literal, exactly how the PowDB docs insert a json
+ * document (the engine validates it as JSON text and stores the canonical
+ * binary form). Constructed in {@link PowqlInterface.param} when the target
+ * column is `json` and the value is a non-null object/array; a JS string
+ * written to a json column passes through RAW (same contract as pg jsonb,
+ * pass `'"x"'` to store the JSON string `"x"`), and `null` stays `null`.
+ */
+export declare class PowdbJsonParam {
+    readonly value: unknown;
+    readonly column?: string | undefined;
+    /** `column` is diagnostic only: it names the target column when serialization fails. */
+    constructor(value: unknown, column?: string | undefined);
+}
+/** The four shapes a PowQL result takes over the legacy string wire. */
+type PowdbResult = {
+    kind: 'rows';
+    columns: string[];
+    rows: string[][];
+} | {
+    kind: 'scalar';
+    value: string;
+} | {
+    kind: 'ok';
+    affected: bigint;
+} | {
+    kind: 'message';
+    message: string;
+};
+/**
+ * Local structural mirror of `@zvndev/powdb-client`'s `WireValue` (the lossless
+ * typed cell of the native wire surface). Defined here rather than imported so
+ * the optional peer's types never leak into Turbine's published `.d.ts` (a
+ * consumer without the peer installed must still `tsc` cleanly, same rule as
+ * every other optional-peer type in this module). `empty` = an unset value
+ * (distinct, for a json column, from a JSON-null document, which is
+ * `{ type: 'json', value: null }`).
+ */
+type PowdbWireValue = {
+    type: 'empty';
+} | {
+    type: 'int';
+    value: bigint;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'bool';
+    value: boolean;
+} | {
+    type: 'str';
+    value: string;
+} | {
+    type: 'datetime';
+    value: bigint;
+} | {
+    type: 'uuid';
+    value: Uint8Array;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+} | {
+    type: 'json';
+    value: unknown;
+    pj1?: Uint8Array;
+};
+/** The native (lossless typed) result shape, mirroring `RawNativeQueryResult`. */
+type PowdbRawNativeResult = {
+    kind: 'rows';
+    columns: string[];
+    rows: PowdbWireValue[][];
+} | {
+    kind: 'scalar';
+    value: PowdbWireValue;
+} | {
+    kind: 'ok';
+    affected: bigint;
+} | {
+    kind: 'message';
+    message: string;
+};
+interface PowdbClient {
+    readonly serverVersion: string;
+    query(query: string, params?: PowdbParam[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<PowdbResult>;
+    /**
+     * Lossless typed wire surface (client ≥ 0.13, server ≥ 0.13). Optional: an
+     * older client omits it, so every call site feature-detects
+     * `typeof c.queryNativeRaw === 'function'` before using it and falls back to
+     * {@link query}. It NEVER retries as a legacy query, replaying an ambiguous
+     * mutation is unsafe, so its use is additionally version-gated server-side.
+     */
+    queryNativeRaw?(query: string, params?: PowdbParam[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<PowdbRawNativeResult>;
+    close(): Promise<void>;
+}
+interface PowdbClientPool {
+    acquire(): Promise<PowdbClient>;
+    release(c: PowdbClient): void;
+    destroy(c: PowdbClient): void;
+    withClient<T>(fn: (c: PowdbClient) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+interface PowdbModule {
+    Client: {
+        connect(opts: PowdbConnOptions): Promise<PowdbClient>;
+    };
+    Pool: new (opts: PowdbConnOptions & {
+        max?: number;
+    }) => PowdbClientPool;
+    isPowDBError?(err: unknown): err is {
+        code: string;
+        message: string;
+    };
+}
+/** Connection options for {@link turbinePowDB} — host/port, not a connection string. */
+export interface PowdbConnOptions {
+    host: string;
+    port: number;
+    dbName?: string;
+    user?: string;
+    password?: string | null;
+    connectTimeoutMs?: number;
+    tls?: boolean;
+}
+/** Minimum PowDB server version the networked transport requires. */
+export declare const MIN_POWDB_VERSION = "0.7.0";
+/**
+ * Parse a `powdb://[user[:pass]@]host[:port][/db]` connection string into
+ * {@link PowdbConnOptions} (consistency with `turbineMysql`/`turbineMssql`,
+ * which accept a URL). Defaults: host `127.0.0.1`, port `5433`.
+ */
+export declare function parsePowdbUrl(connectionString: string): PowdbConnOptions;
+/**
+ * Fail fast if a networked PowDB server is older than {@link MIN_POWDB_VERSION}.
+ * Turbine's write path relies on the trailing `returning` keyword and the
+ * int→float coercion fix, both of which landed in 0.7.0. Embedded exposes no
+ * version method, so this is networked-only (the embedded peer is pinned ^0.7.0
+ * at install time). A non-semver / empty version string is tolerated (we cannot
+ * prove it is too old).
+ */
+export declare function assertSupportedPowdbVersion(version: string | undefined): void;
+/**
+ * Feature capabilities of a bound PowDB connection. Resolved once (from the
+ * probed server version on the networked transport, or the addon package
+ * version on embedded) and carried on the pool so {@link PowqlInterface} can
+ * gate PowQL features that only exist on newer engines, an old engine gets a
+ * typed {@link UnsupportedFeatureError} (E017) with a version hint instead of a
+ * raw PowQL parse error.
+ */
+export interface PowdbCapabilities {
+    /** Best-known engine version (e.g. `'0.13.0'`), or `null` when unknowable. */
+    engineVersion: string | null;
+    /** ≥ 0.12: `json` column type, `->` path filters / ordering / grouping. */
+    jsonDocs: boolean;
+    /** ≥ 0.13: `alter T add index (.col->seg)` expression indexes. */
+    docFieldIndexes: boolean;
+    /** ≥ 0.10: `schema` / `describe` introspection statements. */
+    introspection: boolean;
+    /** ≥ 0.13: server-side joins, hash-accelerated and bounded. */
+    serverJoins: boolean;
+    /**
+     * ≥ 0.18: nested projections (shaped results) — a projection field may be a
+     * whole correlated child query returning a per-parent JSON array. When set,
+     * eligible `with` clauses compile into the parent statement instead of the
+     * batched loaders.
+     */
+    nestedProjections: boolean;
+    /**
+     * ≥ 0.19: entity links (`link` DDL, scalar/block traversal). Capability is
+     * recognized (probe-only), but query generation deliberately does NOT consume
+     * links yet: turbine keeps composing its own nested projections (see the
+     * PowDB engine page for the rationale). Declaring a link permanently upgrades
+     * the on-disk catalog to v7, so this stays FALSE in ALL_POWDB_CAPABILITIES.
+     */
+    entityLinks: boolean;
+    /**
+     * ≥ 0.19.1: link INTROSPECTION, the `schema links` listing statement and the
+     * appended link rows in `describe <T>`. Only meaningful when probed (there is
+     * no query-generation flip behind it), so it stays FALSE in
+     * ALL_POWDB_CAPABILITIES like the other probe-only gates. Floored at the PATCH
+     * 0.19.1: the listing statement shipped there, not in 0.19.0.
+     */
+    linkIntrospection: boolean;
+    /**
+     * ≥ 0.19.1: scalar to-one link PATHS in query generation. Floored at the PATCH
+     * 0.19.1 (never 0.19.0) because 0.19.0 had silent-wrong-results link bugs
+     * (bare-dotted-path split, wrong aggregates over links) that make traversal
+     * unsafe; 0.19.1 turned those into hard errors. This flag flips real query
+     * generation (a to-one `with` whose child carries bigint/bytes compiles to
+     * link-path projections instead of a loader), so it stays FALSE in
+     * ALL_POWDB_CAPABILITIES: it must only light up behind a real version probe.
+     */
+    linkPaths: boolean;
+    /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
+    nativeRaw: boolean;
+}
+/** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections' | 'entityLinks' | 'linkIntrospection' | 'linkPaths';
+/**
+ * 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. `nestedProjections` stays OFF for
+ * the same reason: it changes the generated PowQL for every `with` query, and
+ * an unprobed engine below 0.18 would reject the syntax outright.
+ * `entityLinks` stays OFF for a stronger reason still: declaring a link
+ * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
+ * so it must only ever light up behind a real version probe.
+ * `linkIntrospection` / `linkPaths` stay OFF for the same probe-only discipline:
+ * `linkPaths` flips real query generation (a to-one `with` compiling to link
+ * projections), and `linkIntrospection` is only meaningful once genuinely
+ * probed, so both must come from a real version resolution, never a bare
+ * construction.
+ */
+export declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
+/**
+ * Derive {@link PowdbCapabilities} from an engine version string. A non-semver /
+ * unknown version turns every gate OFF (the E017 hint then tells the caller to
+ * upgrade or pass `assumeEngineVersion`). `nativeRaw` requires BOTH the client
+ * to expose `queryNativeRaw` (passed in) AND server ≥ 0.13.
+ */
+export declare function capabilitiesFromVersion(version: string | undefined | null, opts?: {
+    hasNativeRaw?: boolean;
+}): PowdbCapabilities;
+/**
+ * Throw a version-hinting {@link UnsupportedFeatureError} (E017) when a gated
+ * PowQL feature is used on an engine that does not support it. Keeps old engines
+ * getting clean typed errors instead of raw PowQL parse failures.
+ */
+export declare function requireCapability(caps: PowdbCapabilities, key: PowdbFeatureKey, feature: string): void;
+/**
+ * PowQL column types Turbine emits: the four writable scalars plus PowDB's
+ * native `json` document type (added to the map in the 0.12/0.13 parity round,
+ * see {@link isJsonColumn}). A `json` column stores a canonical binary document
+ * (sorted keys, int/float distinction preserved) that Turbine writes as a JSON
+ * string literal and reads back by parsing the canonical JSON text.
+ */
+export type PowqlType = 'str' | 'int' | 'float' | 'bool' | 'json';
+/**
+ * Does this column map to PowDB's native `json` document type? A Postgres
+ * `json`/`jsonb` type (via `dialectType`/`pgType`) is authoritative; otherwise
+ * the tsType heuristic (`Record<…>`, `object`, `unknown`, an object/array
+ * literal) that the four scalar branches do not claim. Array columns never map
+ * to json, a PowDB array only exists INSIDE a json document, so a Postgres
+ * array column has no PowDB shape and still throws in {@link powqlColumnType}.
+ */
+export declare function isJsonColumn(col: ColumnMetadata): boolean;
+/**
+ * Map a Turbine column to the PowQL DDL type used in `defineSchema` →
+ * `type T { … }`. Turbine never emits PowDB's `uuid`/`datetime`/`bytes` types,
+ * which cannot hold client-supplied values on the wire (no literal, no cast):
+ *   - `Date` → `int` (epoch micros)   - `boolean` → `bool`
+ *   - integral `number`/`bigint` → `int`   - fractional `number` → `float`
+ *   - JSON / object columns → `json` (native PowDB document type, ≥ 0.12)
+ *   - everything else (incl. UUID/PK strings) → `str`
+ * Array (non-json) and bytes columns throw, they have no PowDB equivalent.
+ */
+export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
+/**
+ * Generate PowQL DDL (`type T { … }`) for every table in a schema. Used to
+ * provision a PowDB database from a code-first `defineSchema`/`SchemaMetadata`
+ * (PowDB has no migration runner yet). The primary key column is declared
+ * `required unique`; non-nullable columns are `required`. A server-generated
+ * column ({@link ColumnMetadata.isGenerated}) that maps to PowQL `int` gets the
+ * `auto` modifier, so PowDB assigns a monotonic id on insert and Turbine stops
+ * synthesizing a client-side value for it.
+ */
+/**
+ * PowQL reserved words — the v0.10 lexer keyword table from POWQL.md's
+ * "Reserved Words and Quoting" section, including the v0.10 additions
+ * `schema` and `describe`. Keyword matching is case-sensitive in the lexer,
+ * so only the exact lowercase form collides.
+ */
+export declare const POWQL_KEYWORDS: ReadonlySet<string>;
+/**
+ * Backtick-quote an identifier when PowQL would otherwise lex it as a keyword
+ * (or when it contains characters outside the bare-identifier grammar).
+ * Applied only in bare-identifier positions — DDL type/field names, index DDL,
+ * and `insert`/`update`/`upsert` assignment targets. Dotted references
+ * (`.col` in filters/projections/ordering) bypass keyword lookup on every
+ * engine version and deliberately stay bare for ≤0.9 compatibility. Backticks
+ * parse on PowDB ≥ 0.10; on older engines these names were already parse
+ * errors when emitted bare, so quoting is strictly an improvement.
+ */
+export declare function quotePowqlIdent(name: string): string;
+/**
+ * Options for {@link powqlSchemaDDL}. Additive: with no options the DDL is
+ * emitted unconditionally (pure-function callers / tests); pass `capabilities`
+ * to gate engine-version-specific features (json columns, and, since the
+ * 0.13 parity round, doc-field expression indexes) behind the connection's
+ * real capabilities. Doc-field expression index declarations plug into the
+ * per-table `indexes` surface consumed here without further signature churn.
+ */
+export interface PowqlSchemaDDLOptions {
+    capabilities?: PowdbCapabilities;
+    /**
+     * Emit `link Owner.name -> Target on local = target` declarations (PowDB entity
+     * links, >= 0.19) for every single-column hasMany / hasOne / belongsTo relation
+     * in the metadata, appended after the `type` / index statements. Default
+     * `false`: links are opt-in. Composite-key relations and m2m junctions are
+     * skipped (a link is single-column only); a relation whose name collides with a
+     * column on the owner is skipped with a one-time warning (the engine hard-errors
+     * on such a collision). When `capabilities` is also supplied it must pass the
+     * `entityLinks` gate, else this throws a typed E017.
+     *
+     * ONE-WAY DOOR: the FIRST `link` a database ever executes permanently upgrades
+     * its on-disk catalog to format v7; pre-0.19 PowDB binaries / addons can then no
+     * longer open that data directory. A database that never declares a link stays
+     * on its current catalog format. The DDL is create-only (no `if not exists`, no
+     * drop spelling), so an apply layer must existence-check first (see
+     * {@link applyPowdbLinks}).
+     */
+    emitLinks?: boolean;
+}
+/**
+ * One entity link Turbine wants declared for a relation: `link owner.name ->
+ * target on localKey = targetKey`. Cardinality is NOT part of the DDL (PowDB
+ * derives to-one vs to-many from whether `targetKey` is unique on `target` at
+ * declare time), so a belongsTo and its reverse hasMany both round-trip to the
+ * same shape from opposite owners.
+ */
+export interface PowdbDesiredLink {
+    owner: string;
+    name: string;
+    target: string;
+    localKey: string;
+    targetKey: string;
+}
+/**
+ * Derive the entity links Turbine would declare from a schema's relations. One
+ * link per single-column hasMany / hasOne / belongsTo relation, owned by the
+ * relation's `from` table:
+ *   - belongsTo Order->User: `Order.user -> User on user_id = id`
+ *     (localKey = the FK on the owner, targetKey = the referenced key on target).
+ *   - hasMany  User->Order: `User.orders -> Order on id = user_id`
+ *     (localKey = the referenced key on the owner, targetKey = the FK on the child).
+ * Composite-key relations and m2m junctions are skipped (links are single-column;
+ * a junction cannot be inferred from links). A relation whose name collides with
+ * a column on the owner is skipped and reported through `onCollision` (the caller
+ * decides whether to warn). Pure: no capability gate, no side effects.
+ */
+export declare function deriveDesiredLinks(schema: SchemaMetadata, onCollision?: (owner: string, name: string) => void): PowdbDesiredLink[];
+/** Render one {@link PowdbDesiredLink} as its create-only `link ...` DDL statement. */
+export declare function powdbLinkStatement(link: PowdbDesiredLink): string;
+export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchemaDDLOptions): string[];
+/**
+ * Existence-checked apply of entity-link DDL against a LIVE PowDB database.
+ * Because link DDL is create-only (no `if not exists`, redeclaring is an error,
+ * and there is no drop spelling), an apply layer must diff against the live
+ * catalog first: this reads the `schema links` listing, then executes only the
+ * links that are genuinely missing.
+ *
+ *   - a desired link already declared with the SAME endpoints  → skipped (idempotent);
+ *   - a link declared with the same owner + name but DIFFERENT endpoints → skipped
+ *     with a one-time warning (never dropped/replaced: there is no drop DDL, and a
+ *     silent replace would be a destructive schema change);
+ *   - a name/column collision on the owner → skipped (deriveDesiredLinks warns).
+ *
+ * Requires the `entityLinks` + `linkIntrospection` capabilities when `capabilities`
+ * is supplied (the listing statement is 0.19.1+). Returns the statements executed.
+ * `exec` runs one PowQL statement (embedded `db.raw` / a networked query shim); it
+ * must return rows keyed by column name for the `schema links` read.
+ */
+export declare function applyPowdbLinks(exec: PowdbExec, schema: SchemaMetadata, options?: {
+    capabilities?: PowdbCapabilities;
+}): Promise<string[]>;
+/**
+ * Coerce a single PowDB wire string into the JS value its column type implies.
+ * Every PowDB value arrives as a string; NULL arrives as the bareword `"null"`.
+ * Metadata resolves the `"null"` ambiguity for nullable non-string columns.
+ */
+export declare function coerceValue(raw: string, col: ColumnMetadata): unknown;
+/**
+ * Coerce a single cell that arrived over the NATIVE typed wire (decoded from a
+ * {@link PowdbWireValue}, so already a JS `bigint`/`number`/`boolean`/`string`/
+ * `NativeJson`/`Uint8Array`/`null`, never a bare `"null"` string). Unlike
+ * {@link coerceValue} this NEVER collapses the string `"null"` to `null`: an
+ * absent value already decoded to `null` (from the `empty` cell), so a genuine
+ * str `"null"` stays the string `"null"` (fixes the legacy-wire wart on the
+ * native transport). `datetime`-shaped cells (int micros) become `Date`; a
+ * bigint on a `number` column follows the int8 safe-integer policy.
+ */
+export declare function coerceNativeValue(value: unknown, col: ColumnMetadata): unknown;
+/**
+ * Map one raw PowDB row into a typed entity (camelCase fields, coerced values).
+ * Only the columns present in `raw` are emitted, so partial `select`
+ * projections round-trip unchanged. `native` selects the coercion policy: the
+ * default `false` handles the legacy string wire (every cell is a string, via
+ * {@link coerceValue}); `true` handles the native typed wire, where non-string
+ * cells arrive pre-typed and go through {@link coerceNativeValue} (see F3).
+ * Callers on the native transport pass `this.pool.capabilities.nativeRaw`.
+ */
+export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMetadata, native?: boolean): Record<string, unknown>;
+/**
+ * Translate a PowDB error into a typed Turbine error. Handles BOTH transports,
+ * whose error shapes differ:
+ *   - **networked** (`@zvndev/powdb-client`) tags errors with a *semantic*
+ *     `.code` (`connect_failed`, `timeout`, `query_failed`, …);
+ *   - **embedded** (`@zvndev/powdb-embedded` napi addon) tags EVERY error
+ *     `code:'GenericFailure'`, so the class can only be recovered from the
+ *     message text (`Execution("column 'email' is required …")`,
+ *     `Execution("type mismatch …")`, `Parse(…)`, `StorageError(…)`).
+ *
+ * So we always run the unique-constraint and message-shape checks first (they
+ * fire for both transports and extract detail like constraint / column names),
+ * then classify by the typed wire error class (`.wireErrorClass`, networked
+ * server >= 0.17 — accurate even when the server sanitized the message text),
+ * then fall through to the networked `.code` switch.
+ */
+export declare function wrapPowdbError(err: unknown): Error;
+/**
+ * True when `err` is the stale-wire-frame {@link ConnectionError} produced by
+ * {@link wrapPowdbError} (its `.cause` is a `protocol_error` PowDBError, or the
+ * message carries the invalid-state signature). The opt-in read retry
+ * (`retryStaleReads`, evaluated in {@link PowqlInterface}'s exec seam) uses this
+ * to decide whether a first-statement READ may be replayed once on a fresh
+ * connection; writes are NEVER retried (an ambiguous mutation reply is unsafe
+ * to replay, matching the client's own native-path policy).
+ */
+export declare function isStaleFramePowdbError(err: unknown): boolean;
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * Default cap (ms) on how long a `begin` may wait in the FIFO queue for
+ * PowDB's single global write lock before failing with a typed
+ * {@link TimeoutError} (E002). Prevents silent starvation behind a wedged
+ * transaction. Override via `transactionQueueTimeoutMs`
+ * ({@link TurbinePowdbOptions} / {@link PowdbPoolOptions}); `0` or `Infinity`
+ * waits without limit.
+ */
+export declare const DEFAULT_TX_QUEUE_TIMEOUT_MS = 30000;
+/** Tuning options shared by {@link PowdbPool} and {@link PowdbEmbeddedPool}. */
+export interface PowdbPoolOptions {
+    /**
+     * Max time (ms) a concurrent transaction's `begin` may wait in the FIFO
+     * queue for the single-writer lock before failing with a
+     * {@link TimeoutError}. Default {@link DEFAULT_TX_QUEUE_TIMEOUT_MS};
+     * `0` / `Infinity` = wait without limit. Note this is a separate surface
+     * from `$transaction`'s `timeout` option, which only covers the callback
+     * *after* the transaction has begun.
+     */
+    transactionQueueTimeoutMs?: number;
+    /**
+     * Feature capabilities of the bound connection. Set by {@link turbinePowDB}
+     * from the probed engine version; defaults to {@link ALL_POWDB_CAPABILITIES}
+     * (feature gates on, `nativeRaw` off, engine version unknown) for a
+     * directly-constructed pool: a "trusted caller".
+     */
+    capabilities?: PowdbCapabilities;
+    /**
+     * Opt in to replaying a first-statement READ once, on a fresh connection,
+     * when it fails with the stale-wire-frame {@link ConnectionError} (see
+     * {@link isStaleFramePowdbError}). Networked only; writes and mid-transaction
+     * statements are NEVER retried. Read by {@link PowqlInterface}'s exec seam.
+     * Default `false` (typed-error-only).
+     */
+    retryStaleReads?: boolean;
+    /**
+     * Mark this pool read-only: {@link PowqlInterface}'s exec seam then fails a
+     * write (or a tx-control `begin`) fast with a {@link ReadOnlyError} (E018)
+     * before it reaches the wire. An `{ embedded, readonly: true }` target forces
+     * this true; a networked pool bound to a read-only role can also set it so
+     * writes are rejected locally instead of round-tripping to the engine's
+     * refusal. Default `false`.
+     */
+    readonly?: boolean;
+}
+/**
+ * A {@link PgCompatPool} backed by a `@zvndev/powdb-client` `Pool`. The query
+ * `text` is **PowQL**, not SQL ({@link PowqlInterface} generates it). On the
+ * legacy string wire cells come back as strings; when `capabilities.nativeRaw`
+ * is set (server ≥ 0.13 + a client exposing `queryNativeRaw`) this pool routes
+ * through the typed native wire instead, so cells arrive pre-typed (a json int
+ * as `bigint`, etc.) and each result is tagged with the wire that served it
+ * ({@link PowdbTaggedResult}). Per-column JS coercion still happens in
+ * `PowqlInterface` (it owns the schema metadata), keyed on that per-result tag.
+ */
+export declare class PowdbPool implements PgCompatPool {
+    readonly pool: PowdbClientPool;
+    private readonly toParam;
+    private closed;
+    /**
+     * Pool-level single-writer gate. PowDB holds one global write lock, so at
+     * most one transaction may be open across the whole pool. Concurrent
+     * `begin`s queue FIFO on the gate (instead of checking out a second
+     * connection and blocking on the lock forever — the networked hang);
+     * re-entrant `begin`s throw E017 (see {@link PowdbTxGate}).
+     */
+    private readonly txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    private poolHold;
+    /**
+     * Clients currently checked out via {@link connect}. The driver pool's
+     * `close()` only closes IDLE clients (checked-out ones are documented as the
+     * caller's responsibility), so {@link end} destroys these explicitly;
+     * otherwise a `disconnect()` racing an unreleased connection would leave a
+     * live socket holding the process open until the server's idle timeout.
+     */
+    private readonly checkedOut;
+    /** Feature capabilities of the bound server (probed version + native-wire feature-detect). */
+    readonly capabilities: PowdbCapabilities;
+    /** Opt-in first-statement-read replay on a stale wire frame (read by {@link PowqlInterface}). */
+    readonly retryStaleReads: boolean;
+    /**
+     * True when the caller marked this pool read-only (`readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own read-only-role refusal (mapped by
+     * {@link wrapPowdbError}) is the backstop for raw / injected paths.
+     */
+    readonly readonly: boolean;
+    constructor(pool: PowdbClientPool, toParam?: (v: unknown, i: number) => PowdbParam, options?: PowdbPoolOptions);
+    /**
+     * Run one statement on `c`, choosing the lossless native typed wire when the
+     * server supports it (`capabilities.nativeRaw`) AND this client exposes
+     * `queryNativeRaw` (a defensive per-call feature-detect, so a heterogeneous
+     * injected pool cannot crash). Otherwise the legacy string wire, unchanged.
+     */
+    private runOnClient;
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    /**
+     * Typed guard mirroring {@link PowdbEmbeddedPool}: after `end()` the driver
+     * pool throws a raw `Error('pool closed')` that {@link wrapPowdbError}
+     * cannot classify — surface the same ConnectionError on both transports.
+     */
+    private assertOpen;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/** The embedded addon's result shape (matches {@link PowdbResult} but with optional fields). */
+interface EmbeddedQueryResult {
+    kind: string;
+    columns?: string[];
+    rows?: string[][];
+    value?: string;
+    affected?: bigint;
+    message?: string;
+}
+/**
+ * The embedded addon's native typed result (`@zvndev/powdb-embedded` ≥ 0.14).
+ * Mirrors {@link PowdbRawNativeResult}, the same tagged {@link PowdbWireValue}
+ * cells (embedded `bytes` arrive as a `Buffer`, which IS a `Uint8Array`, so the
+ * decode path is unchanged), including the `message` kind for DDL / status
+ * replies, which {@link adaptNativeResult}'s default branch handles at runtime.
+ */
+type EmbeddedNativeResult = PowdbRawNativeResult;
+/** A single in-process embedded database handle (`@zvndev/powdb-embedded`). */
+interface EmbeddedDatabase {
+    query(powql: string): EmbeddedQueryResult;
+    querySql(sql: string): EmbeddedQueryResult;
+    queryReadonly(powql: string): EmbeddedQueryResult;
+    isPoisoned(): boolean;
+    /** WAL durability selector — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+    setSyncMode?(mode: string): void;
+    /**
+     * Lossless typed native wire (`@zvndev/powdb-embedded` ≥ 0.14). All optional
+     * and feature-detected: an older addon omits them, so {@link PowdbEmbeddedPool}
+     * falls back to {@link materializePowql} + {@link query}. `queryWithParams`
+     * binds positional `$N` params as {@link PowdbParam} values (the NativeParam
+     * union) instead of materializing literals.
+     */
+    queryNative?(powql: string): EmbeddedNativeResult;
+    queryReadonlyNative?(powql: string): EmbeddedNativeResult;
+    queryWithParams?(powql: string, params: PowdbParam[]): EmbeddedNativeResult;
+    /** Checkpoint-flushing close (`@zvndev/powdb-embedded` ≥ 0.14). Optional (feature-detected). */
+    close?(): void;
+}
+interface EmbeddedModule {
+    Database: {
+        open(dir: string): EmbeddedDatabase;
+        /** Open with a per-query memory budget — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+        openWithMemoryLimit?(dir: string, limitBytes: number): EmbeddedDatabase;
+        /**
+         * Open a read-only handle for snapshot serving (`@zvndev/powdb-embedded` ≥
+         * 0.14). Optional (feature-detected); a write through such a handle is
+         * refused with `readonly mode: statement requires a writer …` (→ E018).
+         */
+        openReadOnly?(dir: string): EmbeddedDatabase;
+        openReadOnlyWithMemoryLimit?(dir: string, limitBytes: number): EmbeddedDatabase;
+    };
+}
+/**
+ * Encode a JS value as a **PowQL literal** for the embedded driver, which takes
+ * no params array — `$N` placeholders must be materialized into the query text.
+ *
+ * This is the single place Turbine builds PowQL text from a value, so it is the
+ * security-critical surface. String encoding matches PowDB's lexer
+ * (`crates/query/src/lexer.rs`) exactly: a string literal is `"…"`, and inside
+ * it the lexer recognizes only the escapes `\"`, `\\`, `\n`, `\t` (any other
+ * `\x` drops the backslash and keeps `x`; every non-`\`/non-`"` char — raw
+ * newlines, CR, unicode — is taken literally). So we escape `\` → `\\` and
+ * `"` → `\"` (the only breakout vectors), render `\n`/`\t` as their recognized
+ * escapes, and leave everything else raw. Verified against the real engine:
+ * quotes, backslashes, `$N`, `"); drop … --`, raw CR, and emoji all round-trip
+ * as data and cannot break out of the literal or inject a second statement.
+ */
+export declare function encodePowqlLiteral(value: unknown, position?: string): string;
+/**
+ * The newest PowDB engine LINE (major.minor) whose lexer escape handling
+ * {@link encodePowqlString} is VERIFIED against by reading
+ * `crates/query/src/lexer.rs`. The legacy materialize path
+ * ({@link materializePowql}) inlines encoded string literals directly into query
+ * text, so it is only injection-safe while the lexer recognizes exactly the
+ * escape set the escaper emits (`\"`, `\\`, `\n`, `\t`, everything else raw). If
+ * a future engine line teaches the lexer new escapes (e.g. `\u`, `\x`), a string
+ * that the escaper leaves raw could be re-interpreted by the lexer and break out
+ * of the literal, turning the fallback into an injection primitive.
+ *
+ * CONTRACT: bump this ceiling ONLY after re-verifying the escape handling in
+ * `crates/query/src/lexer.rs` for the newer line AND confirming
+ * {@link encodePowqlString} still escapes every breakout vector the lexer
+ * recognizes. The legacy path guards on this value (see
+ * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
+ * the ceiling yet still routes through the string wire is refused rather than
+ * materialized.
+ *
+ * Verification for the 0.19 line: `crates/query/src/lexer.rs` is byte-identical
+ * between v0.18.0 and v0.19.0 (empty git diff), and `link` was already a lexer
+ * keyword at 0.18.0. The 0.19 entity-links surface adds new STATEMENTS built from
+ * pre-existing tokens, so the tokenization / escape surface this ceiling guards is
+ * unmoved. The 0.19.1 link-introspection / link-path round is likewise lexer-neutral:
+ * `git diff v0.19.0 v0.19.1 -- crates/query/src/lexer.rs` is empty (the bare-dotted-path
+ * hard error is parser-level, not tokenization), so this ceiling stays `'0.19'`. The
+ * guard in {@link PowdbEmbeddedPool.exec} compares major.minor only, so `'0.19'`
+ * already covers every 0.19.x patch — no bump is needed for 0.19.1.
+ */
+export declare const POWQL_LEXER_TESTED_CEILING = "0.19";
+/**
+ * Substitute every `$N` placeholder in a generator-produced PowQL template with
+ * the encoded literal of `params[N-1]`. Safe because the template is produced by
+ * {@link PowqlInterface} and contains **no** user string literals — the only
+ * `$<digits>` tokens are genuine positional placeholders, so a single scan
+ * cannot accidentally rewrite a `$N` that is itself part of a value (values are
+ * params, never inlined into the template by the generator).
+ */
+export declare function materializePowql(powql: string, params: unknown[]): string;
+/**
+ * A {@link PgCompatPool} backed by an in-process `@zvndev/powdb-embedded`
+ * `Database`. On the addon's typed native wire (≥ 0.14, when
+ * `capabilities.nativeRaw` is set) this pool binds positional `$N` params via
+ * `queryWithParams` and decodes the typed cells, exactly like the networked
+ * transport. On an older addon (no `queryWithParams`) it falls back to the
+ * legacy string wire, which takes **no params array** (its `query(powql)`
+ * accepts only a string), so each positional `$N` is materialized into a PowQL
+ * literal via {@link materializePowql} before the text is handed to the engine.
+ * One handle, single connection: transaction keywords (`begin`/`commit`/
+ * `rollback`) are issued serially as ordinary queries.
+ */
+export declare class PowdbEmbeddedPool implements PgCompatPool {
+    private readonly db;
+    private closed;
+    /**
+     * Single-writer gate. The embedded engine is one handle with one global
+     * write lock — only one transaction may be open at a time. A re-entrant
+     * `begin` (a fresh top-level `db.$transaction` opened inside an open one's
+     * callback) would otherwise hit PowDB's raw "already in a transaction"
+     * parse error; the gate surfaces a typed E017 instead, while INDEPENDENT
+     * concurrent transactions queue FIFO and run one at a time. (Nested
+     * `tx.$transaction` is caught earlier still, by the savepoint override in
+     * {@link powdbDialect}.)
+     */
+    private readonly txGate;
+    /** Hold taken by a `begin` issued via `query()` directly (no checked-out client). */
+    private readonly poolHoldRef;
+    /**
+     * Feature capabilities of the embedded engine (resolved from the addon
+     * package version). `nativeRaw` is true when the addon is ≥ 0.14 and the
+     * opened handle exposes `queryWithParams` (the typed native wire); an older
+     * addon has no such method, so it stays false and the legacy string wire is
+     * used.
+     */
+    readonly capabilities: PowdbCapabilities;
+    /** Carried for surface uniformity with {@link PowdbPool}; inert on embedded (no protocol_error frames). */
+    readonly retryStaleReads: boolean;
+    /**
+     * True when this pool was opened read-only (an `{ embedded, readonly: true }`
+     * target, or a directly-constructed pool passed `readonly: true`). Read by
+     * {@link PowqlInterface}'s exec seam to fail writes fast with E018 before the
+     * wire; the engine's own refusal (mapped by {@link wrapPowdbError}) is the
+     * backstop for raw / injected paths.
+     */
+    readonly readonly: boolean;
+    constructor(db: EmbeddedDatabase, options?: PowdbPoolOptions);
+    /** Run the PowQL on the in-process engine, choosing the native or legacy wire. */
+    private exec;
+    /**
+     * Run one statement, gating transaction control. `holdRef` scopes the gate
+     * hold to whoever issued the `begin` (the pool itself or one checked-out
+     * client), so finishing a transaction can never release a slot a different
+     * transaction is holding.
+     */
+    private run;
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+export { introspectPowdbDatabase, type PowdbExec, type PowdbIntrospectOptions, } from './powdb-introspect.js';
+export { PowqlInterface } from './powql.js';
+/** Options for {@link turbinePowDB}. */
+export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited' | 'relationLoadStrategy'> {
+    /**
+     * Client-level default `with`-relation load strategy. On PowDB the default is
+     * the batched N+1 loaders; setting `'join'` opts INTO native PowQL server-side
+     * joins for eligible top-level relations (ineligible ones, e.g. a paged parent
+     * or a nested `with`, fall back to the loaders per-relation and silently). A
+     * per-query `relationLoadStrategy` arg still overrides this. Requires an engine
+     * that advertises `serverJoins` (PowDB ≥ 0.13); a per-query `'join'` on an
+     * older engine throws E017, a client-level default silently falls back.
+     */
+    relationLoadStrategy?: TurbineConfig['relationLoadStrategy'];
+    /** Max pooled connections (default 10). Networked transport only. */
+    connectionLimit?: number;
+    /**
+     * Max time (ms) a concurrent `$transaction` waits in the FIFO queue for
+     * PowDB's single global write lock before failing with a typed
+     * `TimeoutError` (default {@link DEFAULT_TX_QUEUE_TIMEOUT_MS} = 30 000;
+     * `0` / `Infinity` = wait without limit). Independent concurrent
+     * transactions queue and run one at a time; only a re-entrant
+     * `db.$transaction` (opened inside an active transaction callback) throws
+     * E017 — queueing that shape would deadlock.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    transactionQueueTimeoutMs?: number;
+    /**
+     * Opt in to replaying a first-statement READ once (on a fresh connection)
+     * when it fails with the stale-wire-frame {@link ConnectionError} that a
+     * request can hit after a long idle gap. Networked only; WRITES and any
+     * statement inside a transaction are NEVER retried (an ambiguous mutation
+     * reply is unsafe to replay). Default `false`: the error is surfaced typed
+     * so the caller can decide. See the retry recipe in the docs.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    retryStaleReads?: boolean;
+    /**
+     * Override the detected engine version used for capability gating. For exotic
+     * deployments and injected pools whose version cannot be probed (a non-semver
+     * server string, or an addon whose package.json cannot be resolved): pass
+     * e.g. `'0.13.0'` to unlock the features that version supports. Without it, an
+     * undetectable version turns every version-gated feature OFF (with a hinting
+     * E017).
+     */
+    assumeEngineVersion?: string;
+    /**
+     * Mark the client read-only: a write (or a transaction `begin`) fails fast
+     * locally with a {@link ReadOnlyError} (E018) before it reaches the wire,
+     * rather than round-tripping to the engine's refusal. Works on both
+     * transports (a networked pool bound to a read-only role, or an embedded
+     * handle). An `{ embedded, readonly: true }` target implies this. Default
+     * `false`.
+     *
+     * Ignored when you inject an already-constructed {@link PowdbPool} (it carries
+     * its own {@link PowdbPoolOptions}); set it on that pool's constructor instead.
+     */
+    readonly?: boolean;
+    /**
+     * Driver-module injection for the networked target forms (URL / host+port):
+     * bypasses the dynamic `import('@zvndev/powdb-client')` and uses this object
+     * as the driver module instead. Intended for tests (a fake pool that counts
+     * connections) and advanced embedding; everyday callers never set it.
+     */
+    powdbClientModule?: PowdbModule;
+    /**
+     * Driver-module injection for the **embedded** target form (`{ embedded }`):
+     * bypasses the dynamic `import('@zvndev/powdb-embedded')` and uses this object
+     * as the addon module instead. Intended for tests (a fake `Database` factory
+     * that records how the handle was opened) and advanced embedding; everyday
+     * callers never set it. The symmetric counterpart to {@link powdbClientModule}.
+     */
+    powdbEmbeddedModule?: EmbeddedModule;
+}
+/**
+ * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`
+ * database at the given data directory (no server, no socket). The value is the
+ * data dir path. Preview: Full-durability checkpoint-bound; built binaries ship
+ * for macOS (arm64/x64) and Unix-glibc only (Intel-mac/musl/Windows fall back to
+ * a from-source `npm run build`).
+ *
+ * @example
+ * ```ts
+ * const db = await turbinePowDB({ embedded: '/var/data/app.powdb' }, SCHEMA);
+ * // Faster writes (fsync off the commit path, bounded-loss) — requires addon >= 0.7.1:
+ * const fast = await turbinePowDB({ embedded: '/var/data/app.powdb', syncMode: 'normal' }, SCHEMA);
+ * ```
+ */
+export interface TurbinePowdbEmbeddedTarget {
+    embedded: string;
+    /**
+     * WAL durability for the embedded engine (requires `@zvndev/powdb-embedded` ≥ 0.7.1):
+     * `'full'` (default — fsync per commit), `'normal'` (fsync off the commit path,
+     * ~15–40× faster writes, bounded loss on OS crash/power loss), `'off'` (bench-only).
+     */
+    syncMode?: 'full' | 'normal' | 'off';
+    /** Per-query memory budget in bytes (requires `@zvndev/powdb-embedded` ≥ 0.7.1). */
+    memoryLimit?: number;
+    /**
+     * Open the data directory read-only for snapshot serving (requires
+     * `@zvndev/powdb-embedded` ≥ 0.14: `openReadOnly` / `openReadOnlyWithMemoryLimit`).
+     * A write through a read-only handle is refused by the engine with
+     * `readonly mode: statement requires a writer …` (→ {@link ReadOnlyError}, E018),
+     * and Turbine additionally fails writes fast locally (this implies the pool's
+     * `readonly` flag). Meaningless together with `syncMode` (a read-only engine
+     * never writes), setting both throws a {@link ValidationError}.
+     */
+    readonly?: boolean;
+}
+/**
+ * Bind Turbine to PowDB. `target` is one of:
+ *   - a `powdb://[user[:pass]@]host[:port][/db]` connection string → a
+ *     **networked** `@zvndev/powdb-client` pool (consistency with
+ *     `turbineMysql`/`turbineMssql`);
+ *   - a host/port options object → a **networked** `@zvndev/powdb-client` pool;
+ *   - an `{ embedded: <data-dir> }` object → an in-process
+ *     `@zvndev/powdb-embedded` database (no server);
+ *   - an already-constructed `@zvndev/powdb-client` `Pool` or {@link PowdbPool}
+ *     (injection — you own its lifecycle and `disconnect()` is a no-op).
+ *
+ * On the networked transport the server version is probed and a clear
+ * {@link ConnectionError} is thrown if it is older than {@link MIN_POWDB_VERSION}
+ * (the `returning` keyword / int->float coercion fix Turbine relies on).
+ *
+ * Resolves to a `TurbineClient` whose `table()` accessors generate **PowQL** via
+ * {@link PowqlInterface}. The SQL `Dialect` is not involved.
+ */
+export declare function turbinePowDB(target: string | PowdbConnOptions | PowdbClientPool | PowdbPool | TurbinePowdbEmbeddedTarget, schema: SchemaMetadata, options?: TurbinePowdbOptions): Promise<TurbineClient>;