turbine-orm 0.50.0 → 0.51.0

package/dist/powdb.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm/powdb — Turbine's PowDB / PowQL backend.
+ * 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
@@ -10,26 +10,26 @@
  *
  * 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
+ *   - **`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
+ *   - **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
+ *   - **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
+ *   - **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
+ *     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
+ *     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
@@ -84,9 +84,9 @@ import { normalizeKeyColumns } from './schema.js';
 export const powdbDialect = {
     ...postgresDialect,
     name: 'powdb',
-    // `resultStrategy` is decorative for PowDB — PowqlInterface owns its own write
+    // `resultStrategy` is decorative for PowDB, PowqlInterface owns its own write
     // path and never reads it. Set to 'returning' for honesty: writes use PowDB
-    // 0.7.0's trailing `returning` keyword (upsert excepted — see PowqlInterface).
+    // 0.7.0's trailing `returning` keyword (upsert excepted, see PowqlInterface).
     resultStrategy: 'returning',
     supportsReturning: true,
     supportsVector: false,
@@ -103,7 +103,7 @@ export const powdbDialect = {
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',
-    // PowDB has no savepoints — a nested `tx.$transaction` would emit one and PowDB
+    // PowDB has no savepoints, a nested `tx.$transaction` would emit one and PowDB
     // rejects it with a cryptic parse error. Throw a clear typed error instead.
     // These run synchronously in TransactionClient.$transaction before any query,
     // so the nested call fails fast with no partial DB state.
@@ -111,9 +111,9 @@ export const powdbDialect = {
     releaseSavepointStatement: throwNoNestedTransaction,
     rollbackToSavepointStatement: throwNoNestedTransaction,
 };
-/** Reject any savepoint (nested-transaction) operation — PowDB is single-writer. */
+/** Reject any savepoint (nested-transaction) operation, PowDB is single-writer. */
 function throwNoNestedTransaction() {
-    throw new UnsupportedFeatureError('nested transactions', 'powdb', 'PowDB is single-writer — it has one global write lock and no savepoints. ' +
+    throw new UnsupportedFeatureError('nested transactions', 'powdb', 'PowDB is single-writer, it has one global write lock and no savepoints. ' +
         'Complete the open transaction before starting another; do not nest `$transaction` calls.');
 }
 /**
@@ -190,7 +190,7 @@ export function parsePowdbUrl(connectionString) {
 export function assertSupportedPowdbVersion(version) {
     const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version ?? '').trim());
     if (!m)
-        return; // unknown / non-semver — don't block
+        return; // unknown / non-semver, don't block
     const [major, minor] = [Number(m[1]), Number(m[2])];
     // 0.7.0 is the floor; >= 0.7 (or any 1.x+) passes.
     if (major > 0 || (major === 0 && minor >= 7))
@@ -354,7 +354,7 @@ export function isJsonColumn(col) {
  */
 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.`);
+        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';
@@ -370,7 +370,7 @@ export function powqlColumnType(col) {
     if (ts === 'string')
         return 'str';
     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.`);
+        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.`);
     }
     return 'str';
 }
@@ -393,7 +393,7 @@ function isDateColumn(col) {
  * synthesizing a client-side value for it.
  */
 /**
- * PowQL reserved words — the v0.10 lexer keyword table from POWQL.md's
+ * 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.
@@ -497,7 +497,7 @@ const POWQL_BARE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
  * 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,
+ * 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
@@ -558,7 +558,7 @@ export function powqlSchemaDDL(schema, opts = {}) {
     const stmts = [];
     for (const meta of Object.values(schema.tables)) {
         const pkSet = new Set(meta.primaryKey);
-        // PowDB's `unique` is single-column only — there is no composite-unique
+        // PowDB's `unique` is single-column only, there is no composite-unique
         // constraint (`add unique` takes one `.column`). So the per-field `unique`
         // modifier is emitted only for a single-column PK; a composite PK (e.g. a
         // m2m junction's `(source_id, target_id)`) marks its columns `required` but
@@ -703,7 +703,7 @@ export async function applyPowdbLinks(exec, schema, options = {}) {
 }
 /**
  * Read the live `schema links` listing into {@link PowdbDesiredLink} rows (owner,
- * name, target, localKey, targetKey; cardinality is dropped — it is derived, not
+ * name, target, localKey, targetKey; cardinality is dropped, it is derived, not
  * a DDL input). An empty catalog returns `[]`, never an error. Naming edge: a
  * table literally named `links` is described with `describe links`, but the
  * link LISTING is the contextual keyword form `schema links`.
@@ -890,7 +890,7 @@ export function rowToEntity(raw, meta, native = false) {
  * 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),
+ * server >= 0.17, accurate even when the server sanitized the message text),
  * then fall through to the networked `.code` switch.
  */
 export function wrapPowdbError(err) {
@@ -898,12 +898,12 @@ export function wrapPowdbError(err) {
         return new ConnectionError(`[turbine] PowDB error: ${String(err)}`);
     const e = err;
     const msg = e.message ?? 'unknown PowDB error';
-    // Unique-constraint — message-based on both transports.
+    // Unique-constraint, message-based on both transports.
     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 });
     }
-    // NOT NULL — "column 'x' is required but no value was provided". Map on BOTH
+    // NOT NULL, "column 'x' is required but no value was provided". Map on BOTH
     // transports (the networked path used to collapse this into E003).
     if (/required|not[- ]?null|no value/i.test(msg)) {
         const m = /column ['"]?(\w+)['"]?/i.exec(msg);
@@ -1016,25 +1016,25 @@ export function wrapPowdbError(err) {
     const wireClass = err.wireErrorClass;
     if (typeof wireClass === 'number') {
         switch (wireClass) {
-            case 3: // timeout (per-query budget, gate wait, idle timeout) — retryable
+            case 3: // timeout (per-query budget, gate wait, idle timeout), retryable
                 return new TimeoutError(0, 'PowDB query', { message: `[turbine] PowDB ${msg}`, cause: err });
-            case 4: // limit_exceeded (memory / size budget) — a query-shape defect
+            case 4: // limit_exceeded (memory / size budget), a query-shape defect
                 return new ValidationError(`[turbine] PowDB resource limit exceeded: ${msg}`);
-            case 5: // readonly_refused — the snapshot-serving routing signal
+            case 5: // readonly_refused, the snapshot-serving routing signal
                 return new ReadOnlyError(`PowDB refused a write on a read-only database: ${msg}.`, {
                     cause: err,
                     reason: 'snapshot',
                 });
             case 6: // auth_failed at CONNECT
                 return new ConnectionError(`[turbine] PowDB authentication failed: ${msg} (check the user / password / dbName for this connection).`, { cause: err });
-            case 7: // rate_limited (repeated bad auth) — connection-establishment class
+            case 7: // rate_limited (repeated bad auth), connection-establishment class
                 return new ConnectionError(`[turbine] PowDB rate-limited this address after repeated failed authentication: ${msg}. Wait before retrying.`, { cause: err });
             case 8: {
-                // constraint_violation — today that is always a unique index
+                // constraint_violation, today that is always a unique index
                 const m = /on\s+\S+\.(\w+)/i.exec(msg);
                 return new UniqueConstraintError({ constraint: m?.[1], cause: err });
             }
-            case 9: // cancelled (issuing client disconnected) — final, never retry
+            case 9: // cancelled (issuing client disconnected), final, never retry
                 return new ConnectionError(`[turbine] PowDB query cancelled by client disconnect: ${msg}`, { cause: err });
             case 1: // parse
             case 2: // execution
@@ -1116,15 +1116,15 @@ function txControl(powql) {
  * the write lock the outer transaction holds), and on the networked transport
  * it would block a fresh pooled connection on the lock forever. This guard
  * converts that hang into a fast, typed error. Independent concurrent
- * transactions do NOT hit this — they queue FIFO on {@link PowdbTxGate}.
+ * transactions do NOT hit this, they queue FIFO on {@link PowdbTxGate}.
  */
 function reentrantTransactionError() {
-    return new UnsupportedFeatureError('re-entrant transactions', 'powdb', 'PowDB is single-writer — a transaction opened from inside an active transaction callback would deadlock ' +
+    return new UnsupportedFeatureError('re-entrant transactions', 'powdb', 'PowDB is single-writer, a transaction opened from inside an active transaction callback would deadlock ' +
         'on the write lock the open transaction holds. Use the `tx` client the callback receives, or start the ' +
         'second transaction after the first completes. (Independent concurrent transactions queue automatically.)');
 }
 // ---------------------------------------------------------------------------
-// Single-writer transaction gate — FIFO queueing + re-entrancy detection
+// Single-writer transaction gate, FIFO queueing + re-entrancy detection
 // ---------------------------------------------------------------------------
 /**
  * Default cap (ms) on how long a `begin` may wait in the FIFO queue for
@@ -1151,8 +1151,8 @@ const powdbTxStorage = new AsyncLocalStorage();
  * (and the embedded engine rejects it with a raw parse error).
  *
  * `acquire()` is called (synchronously, see below) for every `begin`:
- *   - a **re-entrant** `begin` — issued from inside an active transaction's
- *     async context, detected via {@link powdbTxStorage} — throws E017
+ *   - a **re-entrant** `begin`, issued from inside an active transaction's
+ *     async context, detected via {@link powdbTxStorage}, throws E017
  *     immediately. Queueing it can never succeed: the open transaction cannot
  *     commit while its callback awaits the queued one.
  *   - an **independent** `begin` waits its FIFO turn, bounded by the queue
@@ -1191,7 +1191,7 @@ const powdbTxStorage = new AsyncLocalStorage();
  */
 class PowdbTxGate {
     queueTimeoutMs;
-    /** Tail of the FIFO queue — resolves once every earlier transaction has finished. */
+    /** Tail of the FIFO queue, resolves once every earlier transaction has finished. */
     tail = Promise.resolve();
     constructor(queueTimeoutMs) {
         this.queueTimeoutMs = queueTimeoutMs;
@@ -1207,11 +1207,11 @@ class PowdbTxGate {
     async acquire() {
         // Walk the WHOLE marker chain, not just the innermost marker: with two
         // pools, dbA-tx → dbB-tx → dbA-begin leaves dbB's marker innermost, but
-        // the dbA ancestor is still open — queueing the inner dbA begin behind it
+        // the dbA ancestor is still open, queueing the inner dbA begin behind it
         // would deadlock. Any live ancestor on this gate ⇒ re-entrant E017.
         // Prune completed heads first (`done` never flips back) so sequential
-        // transactions issued from one long-lived context do not chain — and leak
-        // — unboundedly; what remains is bounded by real nesting depth.
+        // transactions issued from one long-lived context do not chain, and leak
+        // - unboundedly; what remains is bounded by real nesting depth.
         let parent = powdbTxStorage.getStore();
         while (parent?.done)
             parent = parent.parent;
@@ -1365,7 +1365,7 @@ export class PowdbPool {
      * 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);
+     * connection and blocking on the lock forever, the networked hang);
      * re-entrant `begin`s throw E017 (see {@link PowdbTxGate}).
      */
     txGate;
@@ -1425,7 +1425,7 @@ export class PowdbPool {
         if ((ctl === 'commit' || ctl === 'rollback') && this.poolHold === null) {
             // No gate hold → our `begin` never ran (gate timeout / re-entrant
             // E017 / no begin at all). Never forward a stray commit/rollback to
-            // the engine — PowDB is single-writer, so it could only ever end a
+            // the engine, PowDB is single-writer, so it could only ever end a
             // DIFFERENT caller's open transaction. Empty success instead.
             return { rows: [], rowCount: 0, fields: [] };
         }
@@ -1449,11 +1449,11 @@ export class PowdbPool {
     /**
      * 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.
+     * cannot classify, surface the same ConnectionError on both transports.
      */
     assertOpen() {
         if (this.closed) {
-            throw new ConnectionError('[turbine] The PowDB pool is closed — disconnect() was already called on this client.');
+            throw new ConnectionError('[turbine] The PowDB pool is closed, disconnect() was already called on this client.');
         }
     }
     async connect() {
@@ -1476,7 +1476,7 @@ export class PowdbPool {
             // lets the batch `$transaction([...])` path dispatch all statements in
             // one write burst instead of paying a round trip per statement. Safe
             // for the batch's rollback contract because a failed statement leaves
-            // the engine's transaction open (no aborted state, no auto-rollback) —
+            // the engine's transaction open (no aborted state, no auto-rollback) -
             // later pipelined statements execute inside the same still-open
             // transaction and the final `rollback` discards every effect. (The
             // batch path awaits `begin` before dispatching the burst, so the gate
@@ -1494,7 +1494,7 @@ export class PowdbPool {
                     hold = await this.txGate.acquire();
                 }
                 if ((ctl === 'commit' || ctl === 'rollback') && hold === null) {
-                    // This connection never acquired the gate — its `begin` never ran
+                    // This connection never acquired the gate, its `begin` never ran
                     // (gate timeout / re-entrant E017). A stray commit/rollback must
                     // never reach the single-writer engine, where it could only end a
                     // DIFFERENT caller's open transaction. Empty success instead.
@@ -1530,7 +1530,7 @@ export class PowdbPool {
             },
             release: (err) => {
                 // Releasing this connection ends its transaction scope. pg semantics:
-                // a truthy `err` means "destroy, don't re-idle" — client.ts's
+                // a truthy `err` means "destroy, don't re-idle", client.ts's
                 // $transaction timeout path relies on that to keep an abandoned
                 // callback's connection out of the pool. Additionally, an OPEN hold
                 // here means the tx begun on this connection never saw commit/rollback
@@ -1539,7 +1539,7 @@ export class PowdbPool {
                 // server-side transaction ends (destroying the socket alone leaves it
                 // open until the server's idle timeout), THEN hand the gate to the
                 // next queued transaction. If the rollback fails or times out the
-                // connection is treated as broken and destroyed. Never throws — a
+                // connection is treated as broken and destroyed. Never throws, a
                 // teardown error must not mask the transaction's real outcome.
                 const openHold = hold;
                 hold = null;
@@ -1606,14 +1606,14 @@ function normalizeEmbeddedResult(r) {
 }
 /**
  * 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.
+ * 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
+ * `\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
@@ -1715,7 +1715,7 @@ function powqlNumberText(n) {
  * `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.
+ * already covers every 0.19.x patch, no bump is needed for 0.19.1.
  */
 export const POWQL_LEXER_TESTED_CEILING = '0.19';
 /**
@@ -1744,14 +1744,14 @@ function encodePowqlString(s, position) {
         else if (ch === '\t')
             out += '\\t';
         else
-            out += ch; // raw — the lexer takes any other char literally (incl. CR, unicode)
+            out += ch; // raw, the lexer takes any other char literally (incl. CR, unicode)
     }
     return `${out}"`;
 }
 /**
  * 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
+ * {@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).
@@ -1782,7 +1782,7 @@ export class PowdbEmbeddedPool {
     closed = false;
     /**
      * 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
+     * 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
@@ -1883,13 +1883,13 @@ export class PowdbEmbeddedPool {
             }
         }
         if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
-            // This context never acquired the gate — its `begin` never ran (the
+            // This context never acquired the gate, its `begin` never ran (the
             // gate timed out / threw re-entrant E017, or no begin was issued at
             // all). The engine is ONE shared handle: forwarding this stray
             // commit/rollback would hit whatever transaction ANOTHER caller has
             // open on it (live-reproduced: a best-effort ROLLBACK after a failed
             // begin silently discarded a concurrent transaction's writes). Swallow
-            // it as an empty success instead — there is nothing of ours to end.
+            // it as an empty success instead, there is nothing of ours to end.
             return { rows: [], rowCount: 0, fields: [] };
         }
         try {
@@ -1915,7 +1915,7 @@ export class PowdbEmbeddedPool {
         return this.run(powql, params, this.poolHoldRef);
     }
     async connect() {
-        // Single in-process handle — the "client" shares the one Database; tx
+        // Single in-process handle, the "client" shares the one Database; tx
         // keywords run serially on it. Each checked-out client scopes its own
         // gate hold so release() only ever finishes ITS transaction.
         const holdRef = { hold: null };
@@ -1933,7 +1933,7 @@ export class PowdbEmbeddedPool {
             },
             release: () => {
                 // End-of-scope safety net (see PowdbPool.connect()): a tx torn down
-                // without an explicit commit/rollback must not wedge the queue — and
+                // without an explicit commit/rollback must not wedge the queue, and
                 // on the ONE shared embedded handle its open engine transaction must
                 // actually be rolled back before the gate moves on, or the next
                 // transaction's work interleaves into it. run() owns the
@@ -1968,7 +1968,7 @@ export class PowdbEmbeddedPool {
     }
 }
 // ---------------------------------------------------------------------------
-// PowqlInterface — the PowQL query generator (Phase A: flat CRUD via returning)
+// 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';
@@ -1980,19 +1980,19 @@ export { PowqlInterface } from './powql.js';
 async function loadPowdb() {
     try {
         // Via the .cts helper so the CJS build keeps a path to a REAL dynamic
-        // import() — @zvndev/powdb-client ≥ 0.9 is ESM-only, and the CommonJS
+        // import(), @zvndev/powdb-client ≥ 0.9 is ESM-only, and the CommonJS
         // pass transpiles a plain `import()` here into an unusable `require()`.
         return (await importOptionalPeer('@zvndev/powdb-client'));
     }
     catch (err) {
-        throw new ConnectionError("[turbine] turbine-orm/powdb requires the optional peer dependency '@zvndev/powdb-client'. Install it: npm i @zvndev/powdb-client — " +
+        throw new ConnectionError("[turbine] turbine-orm/powdb requires the optional peer dependency '@zvndev/powdb-client'. Install it: npm i @zvndev/powdb-client, " +
             'or construct the PowDB pool yourself and inject it: turbinePowDB(pool, schema). ' +
             `(${err.message})`);
     }
 }
 /**
  * Dynamically load `@zvndev/powdb-embedded` (the in-process napi addon). Kept out
- * of the static import graph — `import 'turbine-orm/powdb'` never pulls it. A
+ * of the static import graph, `import 'turbine-orm/powdb'` never pulls it. A
  * missing package or an unsupported platform (Intel-mac/musl/Windows ship no
  * prebuilt binary) throws a clear {@link ConnectionError} pointing at the
  * from-source `npm run build` fallback.
@@ -2000,7 +2000,7 @@ async function loadPowdb() {
 async function loadPowdbEmbedded() {
     let mod;
     try {
-        // Via the .cts helper — keeps a real dynamic import() available to the
+        // Via the .cts helper, keeps a real dynamic import() available to the
         // CJS build in case a future addon version ships ESM-only (see loadPowdb).
         mod = (await importOptionalPeer('@zvndev/powdb-embedded'));
     }
@@ -2008,12 +2008,12 @@ async function loadPowdbEmbedded() {
         throw new ConnectionError("[turbine] turbine-orm/powdb embedded mode requires the optional peer '@zvndev/powdb-embedded'. " +
             'Install it: npm i @zvndev/powdb-embedded. If install succeeded but loading failed, your platform has no ' +
             'prebuilt binary (prebuilts ship for macOS arm64/x64 and Linux glibc x64/arm64; Intel-mac/musl/Windows ' +
-            'build from source) — build it with `npm run build` in the addon, then retry. You can also construct the ' +
+            'build from source), build it with `npm run build` in the addon, then retry. You can also construct the ' +
             'pool yourself and inject it: turbinePowDB(pool, schema). ' +
             `(${err.message})`);
     }
     if (!mod || typeof mod.Database?.open !== 'function') {
-        throw new ConnectionError("[turbine] '@zvndev/powdb-embedded' loaded but did not export Database.open — the installed version is " +
+        throw new ConnectionError("[turbine] '@zvndev/powdb-embedded' loaded but did not export Database.open, the installed version is " +
             'likely incompatible (turbine-orm/powdb embedded requires @zvndev/powdb-embedded ^0.7.0).');
     }
     return mod;
@@ -2102,7 +2102,7 @@ async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion, i
  *   - 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).
+ *     (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}
@@ -2179,7 +2179,7 @@ export async function turbinePowDB(target, schema, options = {}) {
         patch.end = close;
     }
     else {
-        // Injected pool — the caller owns its lifecycle.
+        // Injected pool, the caller owns its lifecycle.
         client.disconnect = async () => { };
     }
     return client;

package/dist/powql.d.ts

@@ -1,8 +1,8 @@
 /**
- * PowqlInterface — Turbine's PowQL query generator (the PowDB analogue of
+ * PowqlInterface, Turbine's PowQL query generator (the PowDB analogue of
  * {@link QueryInterface}). It exposes the same public method surface as the SQL
- * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL** — a
- * pipeline language, not SQL — executed through {@link PowdbPool}.
+ * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL**, a
+ * pipeline language, not SQL, executed through {@link PowdbPool}.
  *
  * It is a *parallel* implementation rather than a `Dialect` of the SQL builder:
  * PowQL's grammar (`T filter <e> order <k> { .col }`) shares no surface with
@@ -14,14 +14,14 @@
  * server):
  *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
  *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
- *     in one round-trip. `upsert` is the lone exception — its statement does not
+ *     in one round-trip. `upsert` is the lone exception, its statement does not
  *     accept `returning`, so it reselects the row by PK (a composite-PK upsert
  *     reselects-or-writes inside one flat transaction).
  *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
- *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     int, read back via `returning`); otherwise a defaulted **string** PK is
  *     generated client-side (UUID).
- *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
- *     depth D, not one query — including manyToMany (junction → targets).
+ *   - `with` (nested relations) uses **batched N+1 loaders**, D round-trips for
+ *     depth D, not one query, including manyToMany (junction → targets).
  *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
  *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
  *     PowDB's executor caches a subquery's result by plan shape and would return
@@ -30,7 +30,7 @@
  *     shared nested-write engine as one flat top-level transaction (PowDB is
  *     single-writer, no savepoints).
  *   - pgvector / JSON / array filters and cursor streaming throw
- *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
+ *     {@link UnsupportedFeatureError} (E017), they have no PowDB equivalent.
  *
  * @module
  */
@@ -77,8 +77,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private param;
     /**
-     * Render a value for a write *assignment* (`col := …`). Every value — float
-     * columns included — is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
+     * Render a value for a write *assignment* (`col := …`). Every value, float
+     * columns included, is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
      * the int→float UPDATE coercion bug (`score := $n` with an integer param now
      * reads back the integer value, not the raw i64 bits), so the float-literal
      * inlining workaround Turbine carried for ≤ 0.6.2 is gone. Marks the column as
@@ -95,7 +95,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * default so a hand-built test pool never crashes the version gates.
      */
     private get capabilities();
-    /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
+    /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     private alwaysFalse;
     /**
      * Compile a {@link WhereClause} into a PowQL filter expression, pushing every
@@ -153,7 +153,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private bind;
     /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
     private bindLike;
-    /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
+    /** `lhs [not] in ($1, $2, …)`, empty list collapses to a constant. */
     private buildInList;
     /**
      * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
@@ -167,7 +167,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * so a second subquery of the same shape with a different value returns the
      * first one's stale rows (reproduced live on the embedded engine; the
      * single-statement literal `in (list)` form is always correct). Resolving
-     * client-side trades extra round-trips for correctness, and recurses — nested
+     * client-side trades extra round-trips for correctness, and recurses, nested
      * relation filters in the inner predicate resolve when the target query runs.
      */
     private resolveRelationFilters;
@@ -274,8 +274,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      *
      * When the engine supports nested projections (>= 0.18) and the strategy
      * does not opt out, eligible `with` relations compile INTO this statement as
-     * nested-projection blocks (`nestedPlans`) — one round-trip for the whole
-     * shape — and only the ineligible remainder (`residualWith`) goes to the
+     * nested-projection blocks (`nestedPlans`), one round-trip for the whole
+     * shape, and only the ineligible remainder (`residualWith`) goes to the
      * post-execution loaders. Without nesting the emitted PowQL is byte-identical
      * to the pre-0.18 output (no alias, `.col` refs).
      */
@@ -313,7 +313,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private loadRelations;
     /**
-     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * manyToMany nested read, a three-hop batched loader (no `json_agg`/join
      * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
      * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
      * each parent → its junction rows → its targets in memory. Mirrors the
@@ -445,7 +445,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /**
      * Shape the nested JSON children back into typed entities on every parent
      * row. The nested field arrives as a decoded JSON array on the native wire
-     * (or JSON text on the legacy wire — parsed here); its values are real JSON
+     * (or JSON text on the legacy wire, parsed here); its values are real JSON
      * types, so each child object goes through the NATIVE coercion policy
      * (`rowToEntity(…, true)`: a date column's micros number becomes a `Date`, a
      * json column's document passes through, a str `"null"` stays a string).
@@ -477,7 +477,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * must stay on the loaders (ALWAYS a silent fallback with identical output).
      *
      * SCOPED TIGHT: this fires ONLY for a to-one relation whose child projection
-     * includes a bigint/bytes column — exactly the case a JSON nested block cannot
+     * includes a bigint/bytes column, exactly the case a JSON nested block cannot
      * carry, so nested projections have already fallen back to a per-relation loader
      * (`planNestedRelation` returned `null` for the same shape). Cases nested
      * projections DO serve keep nested projections: link-bearing statements are
@@ -485,9 +485,9 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * link path would regress a hot path for no gain. Requires: single-column
      * belongsTo; no relation `with` / `where` / `distinct` / `orderBy` /
      * `limit` / `offset` (a scalar path has no per-hop filter/order and cannot
-     * reproduce those — such inputs stay on the loader for exact parity); a link
+     * reproduce those, such inputs stay on the loader for exact parity); a link
      * name and all projected columns that are bare identifiers (a quoted segment in
-     * a dotted link path is outside the verified spelling — fall back); and a
+     * a dotted link path is outside the verified spelling, fall back); and a
      * DECLARED link that verifiably matches (`findMatchingLink`).
      */
     private planLinkPathRelation;
@@ -495,7 +495,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private linkPathFields;
     /**
      * Reconstruct each link-path relation's child entity from its flat hop fields
-     * and attach it under the relation name — output indistinguishable from the
+     * and attach it under the relation name, output indistinguishable from the
      * loader (same keys, same coercions). Presence: the target PK cell arriving
      * Empty (a null/dangling FK at the hop) means no linked row → `null`, matching
      * the loader's `matches[0] ?? null`. Otherwise the gathered snake cells go
@@ -509,12 +509,12 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /**
      * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
      * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
-     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
-     * it and the trailing `returning` reads it back — as is any non-string PK.
+     * `int` column with PowDB's `auto` modifier) is left untouched, PowDB assigns
+     * it and the trailing `returning` reads it back, as is any non-string PK.
      */
     private applyPkDefault;
     /**
-     * The table name as a PowQL type reference — backtick-quoted when it is a
+     * The table name as a PowQL type reference, backtick-quoted when it is a
      * reserved word (e.g. a table named `order`). Used in every emitted
      * statement; plain `this.table` stays in error messages.
      */
@@ -580,12 +580,12 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /** Reselect a single row by its single-column primary key value. */
     private reselectByPk;
     /**
-     * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
+     * Empty-where guard, blocks accidental whole-table writes. Mirrors the SQL
      * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
      * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
-     * `where` whose conditions all evaporate during compilation — `{}`,
+     * `where` whose conditions all evaporate during compilation, `{}`,
      * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
-     * `{ OR: [{ f: undefined }] }` — compiles to the empty string and is refused,
+     * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
      * because emitting a filter-less write would hit every row.
      */
     private assertCompiledWhere;