turbine-orm 0.50.0 → 0.51.0

package/dist/nested-write.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Nested write engine
+ * turbine-orm, Nested write engine
  *
  * Tree-walking create/update that resolves relation fields in `data` into
  * batched SQL operations within a transaction. Supports create, connect,
@@ -8,7 +8,7 @@
  *
  * This module is imported by `query/builder.ts` when the `data` argument
  * of `create()` or `update()` contains relation fields. It never imports
- * `client.ts` directly — the transaction handle is passed in via
+ * `client.ts` directly, the transaction handle is passed in via
  * `NestedWriteContext`.
  */
 import { CircularRelationError, describeTargetForMessage, NotFoundError, RelationError, UnsupportedFeatureError, ValidationError, } from './errors.js';
@@ -242,7 +242,7 @@ const M2M_SUPPORTED_OPS = new Set(['connect', 'disconnect', 'set']);
  * On the core client the auto-created property accessors are CAMELCASED
  * (`db.userTags` for `user_tags`, see the `Object.defineProperty` loops in
  * client.ts), so `db["user_tags"]` is `undefined` for every snake_case junction
- * — which is every junction `turbine pull` produces over a hand-written join
+ * - which is every junction `turbine pull` produces over a hand-written join
  * table. `db.table("user_tags")` takes the raw table name and exists on both
  * TurbineClient and the TransactionClient handed to `$transaction`, so that is
  * the form to recommend.
@@ -469,9 +469,9 @@ const SKIP_DUPLICATES_FEATURE = 'createMany({ skipDuplicates: true })';
  * `createMany({ skipDuplicates })`, so the engines that refuse it pay for the
  * refusal once instead of on every connect.
  *
- * The capability is not reachable from here as a flag — the `Dialect` is private
+ * The capability is not reachable from here as a flag, the `Dialect` is private
  * to QueryInterface / TurbineClient and `NestedWriteContext` carries only the
- * schema and the transaction — so it is read from the engine's OWN structured
+ * schema and the transaction, so it is read from the engine's OWN structured
  * refusal (`UnsupportedFeatureError.feature`) rather than from a hardcoded
  * engine list that would drift. Both refusing engines throw while BUILDING the
  * statement, before anything is written, so the attempt is side-effect-free.
@@ -509,11 +509,11 @@ async function insertJunctionRowsSkippingDuplicates(ctx, plan, values) {
  *
  * 1. Junction constrains the pair AND the engine supports `skipDuplicates`
  *    (PostgreSQL, SQLite and MySQL: `ON CONFLICT DO NOTHING` / a no-op
- *    `ON DUPLICATE KEY UPDATE`) — one INSERT, no read. The engine resolves the
+ *    `ON DUPLICATE KEY UPDATE`), one INSERT, no read. The engine resolves the
  *    conflict, so two transactions connecting the same pair at the same time
  *    both succeed and one link row exists. This is the introspected path:
  *    every junction introspection can detect declares the pair unique.
- * 2. Otherwise — read this parent's existing link rows for exactly these targets
+ * 2. Otherwise, read this parent's existing link rows for exactly these targets
  *    and insert only the missing ones. Used when the engine refuses the option
  *    (SQL Server and PowDB have no single-statement skip-duplicates form and
  *    throw E017), and when the junction does NOT constrain the pair, where
@@ -658,7 +658,7 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
         validateOps(relName, ops, false);
     }
     // belongsTo relations put the foreign key on the PARENT row, so they must be
-    // resolved BEFORE the parent is inserted — otherwise a NOT NULL FK column
+    // resolved BEFORE the parent is inserted, otherwise a NOT NULL FK column
     // fails on the initial INSERT. We resolve each belongsTo op (create/connect/
     // connectOrCreate) to its referenced row and fold the FK values into the
     // parent's own INSERT.
@@ -679,7 +679,7 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
     const parentRow = (await ctx.tx.table(tableName).create({
         data: { ...scalars, ...belongsToFks },
     }));
-    // Process hasMany / hasOne relations — their FK lives on the CHILD, so they
+    // Process hasMany / hasOne relations, their FK lives on the CHILD, so they
     // need the parent row to exist first.
     for (const [relName, ops] of Object.entries(relations)) {
         const rel = tableMeta.relations[relName];
@@ -746,7 +746,7 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
     for (const [relName, ops] of Object.entries(relations)) {
         const rel = tableMeta.relations[relName];
         if (rel.type === 'hasMany' || rel.type === 'hasOne') {
-            // create, connect, connectOrCreate — same as nested create
+            // create, connect, connectOrCreate, same as nested create
             await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
             // disconnect
             if (ops.disconnect !== undefined) {
@@ -771,7 +771,7 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
         }
         else if (rel.type === 'belongsTo') {
             await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
-            // update (belongsTo — derive where from parent FK)
+            // update (belongsTo, derive where from parent FK)
             if (ops.update !== undefined) {
                 await processBelongsToUpdate(ctx, rel, ops.update, parentRow, tableName);
             }
@@ -834,7 +834,7 @@ async function processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relNa
                 }
             }
             else {
-                // Batch via createMany (UNNEST) — fast path
+                // Batch via createMany (UNNEST), fast path
                 const injected = items.map((item) => injectForeignKey(item, rel, parentRow, ctx.schema));
                 await ctx.tx.table(rel.to).createMany({ data: injected });
             }
@@ -914,7 +914,7 @@ async function resolveBelongsToForCreate(ctx, rel, ops, parentTable, depth, path
 async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
     const fks = normalizeKeyColumns(rel.foreignKey);
     const refs = normalizeKeyColumns(rel.referenceKey);
-    // create — insert the related row, then update parent's FK
+    // create, insert the related row, then update parent's FK
     if (ops.create !== undefined) {
         const items = toArray(ops.create);
         if (items.length > 0) {
@@ -933,7 +933,7 @@ async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, dep
             });
         }
     }
-    // connect — validate existence, update parent's FK
+    // connect, validate existence, update parent's FK
     if (ops.connect !== undefined) {
         const items = toArray(ops.connect);
         if (items.length > 0) {
@@ -960,6 +960,41 @@ async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, dep
 // ---------------------------------------------------------------------------
 // connect, connectOrCreate, disconnect, set, delete helpers
 // ---------------------------------------------------------------------------
+/**
+ * Refuse a connect that would take a to-many child away from another parent,
+ * when {@link NestedWriteContext.scopedConnect} is on. See that field for why.
+ *
+ * Compares the child's CURRENT foreign key against the parent's reference
+ * value. Null (unowned) passes, an exact match passes (idempotent re-connect),
+ * anything else is refused. Values are compared after normalizing to a
+ * primitive, so a bigint FK read back as a string cannot look like a mismatch
+ * against the number the parent write returned.
+ */
+function assertConnectInScope(ctx, rel, child, parentRow, target) {
+    if (!ctx.scopedConnect)
+        return;
+    if (rel.type !== 'hasMany' && rel.type !== 'hasOne')
+        return;
+    const childTable = ctx.schema.tables[rel.to];
+    const parentTable = ctx.schema.tables[rel.from];
+    if (!childTable)
+        return;
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const key = (v) => (v === null || v === undefined ? null : String(v));
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = parentTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        const current = key(child[fkField]);
+        if (current === null)
+            continue;
+        if (current === key(parentRow[refField]))
+            continue;
+        throw new ValidationError(`[turbine] connect refused: ${rel.to} row ${describeTargetForMessage(target)} is already owned by ` +
+            `another "${rel.from}" (its ${fks[i]} is ${current}). \`scopedConnect\` only allows connecting a row ` +
+            `that is unowned or already owned by this parent; re-parenting must be an explicit update.`);
+    }
+}
 async function batchConnect(ctx, rel, items, parentRow) {
     const fks = normalizeKeyColumns(rel.foreignKey);
     const refs = normalizeKeyColumns(rel.referenceKey);
@@ -972,6 +1007,7 @@ async function batchConnect(ctx, rel, items, parentRow) {
         if (!existing) {
             throw new ValidationError(`[turbine] connect: no ${rel.to} row found matching ${describeTargetForMessage(target)}.`);
         }
+        assertConnectInScope(ctx, rel, existing, parentRow, target);
     }
     // Build FK update data to point children at parent
     const updateData = {};
@@ -999,6 +1035,7 @@ async function connectOrCreate(ctx, rel, op, parentRow) {
         row = (await ctx.tx.table(rel.to).create({ data: injected }));
     }
     else {
+        assertConnectInScope(ctx, rel, row, parentRow, op.where);
         // Update FK to point to parent
         const updateData = {};
         for (let i = 0; i < fks.length; i++) {

package/dist/optional-peer-import.cjs

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * True dynamic `import()` for the optional peer dependencies (`mysql2`,
- * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`) — safe in BOTH
+ * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`), safe in BOTH
  * build outputs, including for peers that are ESM-only.
  *
  * THE PROBLEM THIS FILE SOLVES (the `@zvndev/powdb-client` ≥ 0.9 CJS break):
@@ -9,7 +9,7 @@
  * peers stay out of the static graph. The ESM build (`tsconfig.json`, module
  * NodeNext) emits that `import()` verbatim. The CJS build (`tsconfig.cjs.json`,
  * module CommonJS) however TRANSPILES `import()` into
- * `Promise.resolve().then(() => require(...))` — and `require()` of an
+ * `Promise.resolve().then(() => require(...))`, and `require()` of an
  * ESM-only package (no `require` export condition, e.g. powdb-client ≥ 0.9)
  * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every CJS consumer.
  *
@@ -18,18 +18,18 @@
  * says `"type": "module"`, so NodeNext would classify every `.ts` source as
  * ESM and emit ESM into dist/cjs). A `.cts` file is the escape hatch: it is
  * CommonJS-format by extension regardless of package `type`, so under the ESM
- * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs` — a CommonJS
+ * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs`, a CommonJS
  * file whose `import()` SURVIVES transpilation (NodeNext preserves dynamic
  * import in CJS files precisely because it is the only way CJS can load ESM).
  *
  * That gives the published package two copies of this module:
- *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext)  — real `import()`
- *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS)  — lowered to `require()`
+ *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext) , real `import()`
+ *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS) , lowered to `require()`
  *
  * The lowered copy works fine for CJS-loadable peers (`mysql2`, `mssql`, older
  * powdb peers). When it hits an ESM-only peer, the `require()` fails with a
  * recognizable code and this function falls back to delegating the load to the
- * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) —
+ * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) -
  * which is a plain CommonJS file (loadable by `require()` on every supported
  * Node) whose real `import()` then loads the ESM peer. The ESM-pass copy has
  * no such sibling; its lazy `require` throws and the original error surfaces,
@@ -60,7 +60,7 @@ function isEsmOnlyLoadError(err) {
  * transpilation (see the module doc comment).
  *
  * @param specifier bare package specifier (e.g. `'@zvndev/powdb-client'`).
- * @param allowEsmFallback internal recursion guard — the delegated call passes
+ * @param allowEsmFallback internal recursion guard, the delegated call passes
  *   `false` so a failure in the sibling copy can never bounce back.
  */
 async function importOptionalPeer(specifier, allowEsmFallback = true) {

package/dist/optional-peer-import.d.cts

@@ -1,6 +1,6 @@
 /**
  * True dynamic `import()` for the optional peer dependencies (`mysql2`,
- * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`) — safe in BOTH
+ * `mssql`, `@zvndev/powdb-client`, `@zvndev/powdb-embedded`), safe in BOTH
  * build outputs, including for peers that are ESM-only.
  *
  * THE PROBLEM THIS FILE SOLVES (the `@zvndev/powdb-client` ≥ 0.9 CJS break):
@@ -8,7 +8,7 @@
  * peers stay out of the static graph. The ESM build (`tsconfig.json`, module
  * NodeNext) emits that `import()` verbatim. The CJS build (`tsconfig.cjs.json`,
  * module CommonJS) however TRANSPILES `import()` into
- * `Promise.resolve().then(() => require(...))` — and `require()` of an
+ * `Promise.resolve().then(() => require(...))`, and `require()` of an
  * ESM-only package (no `require` export condition, e.g. powdb-client ≥ 0.9)
  * throws `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every CJS consumer.
  *
@@ -17,18 +17,18 @@
  * says `"type": "module"`, so NodeNext would classify every `.ts` source as
  * ESM and emit ESM into dist/cjs). A `.cts` file is the escape hatch: it is
  * CommonJS-format by extension regardless of package `type`, so under the ESM
- * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs` — a CommonJS
+ * pass (NodeNext) it compiles to `dist/optional-peer-import.cjs`, a CommonJS
  * file whose `import()` SURVIVES transpilation (NodeNext preserves dynamic
  * import in CJS files precisely because it is the only way CJS can load ESM).
  *
  * That gives the published package two copies of this module:
- *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext)  — real `import()`
- *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS)  — lowered to `require()`
+ *   - `dist/optional-peer-import.cjs`      (ESM pass, NodeNext) , real `import()`
+ *   - `dist/cjs/optional-peer-import.cjs`  (CJS pass, CommonJS) , lowered to `require()`
  *
  * The lowered copy works fine for CJS-loadable peers (`mysql2`, `mssql`, older
  * powdb peers). When it hits an ESM-only peer, the `require()` fails with a
  * recognizable code and this function falls back to delegating the load to the
- * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) —
+ * sibling NodeNext copy one directory up (`../optional-peer-import.cjs`) -
  * which is a plain CommonJS file (loadable by `require()` on every supported
  * Node) whose real `import()` then loads the ESM peer. The ESM-pass copy has
  * no such sibling; its lazy `require` throws and the original error surfaces,
@@ -46,7 +46,7 @@
  * transpilation (see the module doc comment).
  *
  * @param specifier bare package specifier (e.g. `'@zvndev/powdb-client'`).
- * @param allowEsmFallback internal recursion guard — the delegated call passes
+ * @param allowEsmFallback internal recursion guard, the delegated call passes
  *   `false` so a failure in the sibling copy can never bounce back.
  */
 declare function importOptionalPeer(specifier: string, allowEsmFallback?: boolean): Promise<unknown>;

package/dist/pipeline-submittable.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Real Postgres pipeline protocol implementation
+ * turbine-orm, Real Postgres pipeline protocol implementation
  *
  * Uses the pg extended-query protocol wire methods (parse/bind/describe/execute/sync)
  * exposed on pg.Client's Connection object to send multiple queries in a single
@@ -18,7 +18,7 @@
  */
 import type { EventEmitter } from 'node:events';
 import type { DeferredQuery } from './query/index.js';
-/** The pg Connection object — an EventEmitter with wire-protocol methods */
+/** The pg Connection object, an EventEmitter with wire-protocol methods */
 export interface PgConnection extends EventEmitter {
     stream: {
         cork?: () => void;

package/dist/pipeline-submittable.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Real Postgres pipeline protocol implementation
+ * turbine-orm, Real Postgres pipeline protocol implementation
  *
  * Uses the pg extended-query protocol wire methods (parse/bind/describe/execute/sync)
  * exposed on pg.Client's Connection object to send multiple queries in a single
@@ -108,7 +108,7 @@ export async function runPipelined(client, queries, options = {}) {
         for (let i = 0; i < queries.length; i++) {
             results.push(new Result(undefined, client._types));
         }
-        // commandComplete counter — tracks position across all commands
+        // commandComplete counter, tracks position across all commands
         let commandIndex = 0;
         // readyForQuery counter
         let rfqCount = 0;
@@ -186,7 +186,7 @@ export async function runPipelined(client, queries, options = {}) {
                 reject(pipelineError);
                 return;
             }
-            // All succeeded — transform results
+            // All succeeded, transform results
             try {
                 const transformed = [];
                 for (let i = 0; i < queries.length; i++) {
@@ -203,13 +203,13 @@ export async function runPipelined(client, queries, options = {}) {
         // Event handlers
         // -----------------------------------------------------------------------
         function onParseComplete() {
-            // No action needed — anonymous prepared statements
+            // No action needed, anonymous prepared statements
         }
         function onBindComplete() {
             // No action needed
         }
         function onNoData() {
-            // DML without RETURNING — no RowDescription follows. Fine.
+            // DML without RETURNING, no RowDescription follows. Fine.
         }
         function onRowDescription(msg) {
             const qIdx = currentQueryIndex();
@@ -306,7 +306,7 @@ export async function runPipelined(client, queries, options = {}) {
             }, timeout);
         }
         // -----------------------------------------------------------------------
-        // Send protocol messages — all in one TCP flush
+        // Send protocol messages, all in one TCP flush
         // -----------------------------------------------------------------------
         try {
             if (connection.stream.cork) {

package/dist/pipeline.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Pipeline execution
+ * turbine-orm, Pipeline execution
  *
  * Pipelines batch multiple independent queries into a single database round-trip.
  * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.

package/dist/pipeline.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Pipeline execution
+ * turbine-orm, Pipeline execution
  *
  * Pipelines batch multiple independent queries into a single database round-trip.
  * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.
@@ -86,11 +86,11 @@ export async function executePipeline(pool, queries, options) {
     if (queries.length === 0) {
         return [];
     }
-    // Acquire a single client — reused for both capability check and execution
+    // Acquire a single client, reused for both capability check and execution
     const client = await pool.connect();
     try {
         if (supportsExtendedPipeline(client)) {
-            // Real pipeline path — uses extended-query protocol wire methods
+            // Real pipeline path, uses extended-query protocol wire methods
             const pipelineOptions = {
                 transactional: options?.transactional ?? true,
                 timeout: options?.timeout,
@@ -98,7 +98,7 @@ export async function executePipeline(pool, queries, options) {
             const results = await runPipelined(client, queries, pipelineOptions);
             return results;
         }
-        // Sequential fallback — reuses the same client
+        // Sequential fallback, reuses the same client
         return await runSequential(client, queries, options);
     }
     finally {

package/dist/powdb-introspect.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm/powdb — `describe`-based introspection.
+ * turbine-orm/powdb, `describe`-based introspection.
  *
  * PowDB exposes its catalog through two ordinary rows-returning statements
  * (keywords since engine 0.10):

package/dist/powdb-introspect.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm/powdb — `describe`-based introspection.
+ * turbine-orm/powdb, `describe`-based introspection.
  *
  * PowDB exposes its catalog through two ordinary rows-returning statements
  * (keywords since engine 0.10):

package/dist/powdb.d.ts

@@ -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
@@ -211,7 +211,7 @@ interface PowdbModule {
         message: string;
     };
 }
-/** Connection options for {@link turbinePowDB} — host/port, not a connection string. */
+/** Connection options for {@link turbinePowDB}, host/port, not a connection string. */
 export interface PowdbConnOptions {
     host: string;
     port: number;
@@ -258,7 +258,7 @@ export interface PowdbCapabilities {
     /** ≥ 0.13: server-side joins, hash-accelerated and bounded. */
     serverJoins: boolean;
     /**
-     * ≥ 0.18: nested projections (shaped results) — a projection field may be a
+     * ≥ 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.
@@ -367,7 +367,7 @@ export declare function powqlColumnType(col: ColumnMetadata): PowqlType;
  * 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.
@@ -376,7 +376,7 @@ 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,
+ * 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
@@ -505,7 +505,7 @@ export declare function rowToEntity(raw: Record<string, unknown>, meta: TableMet
  * 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 declare function wrapPowdbError(err: unknown): Error;
@@ -587,7 +587,7 @@ export declare class PowdbPool implements PgCompatPool {
      * 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}).
      */
     private readonly txGate;
@@ -624,7 +624,7 @@ export declare class PowdbPool implements PgCompatPool {
     /**
      * 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.
      */
     private assertOpen;
     connect(): Promise<PgCompatPoolClient>;
@@ -653,7 +653,7 @@ interface EmbeddedDatabase {
     querySql(sql: string): EmbeddedQueryResult;
     queryReadonly(powql: string): EmbeddedQueryResult;
     isPoisoned(): boolean;
-    /** WAL durability selector — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+    /** WAL durability selector, `@zvndev/powdb-embedded` ≥ 0.7.1. */
     setSyncMode?(mode: string): void;
     /**
      * Lossless typed native wire (`@zvndev/powdb-embedded` ≥ 0.14). All optional
@@ -671,7 +671,7 @@ interface EmbeddedDatabase {
 interface EmbeddedModule {
     Database: {
         open(dir: string): EmbeddedDatabase;
-        /** Open with a per-query memory budget — `@zvndev/powdb-embedded` ≥ 0.7.1. */
+        /** 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` ≥
@@ -684,14 +684,14 @@ interface EmbeddedModule {
 }
 /**
  * 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
@@ -725,13 +725,13 @@ export declare function encodePowqlLiteral(value: unknown, position?: string): s
  * `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 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
+ * {@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).
@@ -754,7 +754,7 @@ export declare class PowdbEmbeddedPool implements PgCompatPool {
     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
+     * 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
@@ -820,7 +820,7 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
      * `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.
+     * 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.
@@ -876,7 +876,7 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
     powdbEmbeddedModule?: EmbeddedModule;
 }
 /**
- * Selects the **embedded** transport — an in-process `@zvndev/powdb-embedded`
+ * 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
@@ -885,7 +885,7 @@ export interface TurbinePowdbOptions extends Pick<TurbineConfig, 'logging' | 'de
  * @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:
+ * // 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);
  * ```
  */
@@ -893,7 +893,7 @@ 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,
+     * `'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';
@@ -919,7 +919,7 @@ export interface TurbinePowdbEmbeddedTarget {
  *   - 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}