turbine-orm 0.65.0 → 0.66.0

package/dist/cjs/mysql.js

@@ -124,10 +124,58 @@ function toNamedBinding(values) {
 // ---------------------------------------------------------------------------
 // Result shaping + error translation
 // ---------------------------------------------------------------------------
+/**
+ * mysql2's `MYSQL_TYPE_TINY`. A result field with this type and a display width
+ * of 1 IS the `BOOLEAN` / `TINYINT(1)` column; see {@link MYSQL_BOOLEAN_TYPE}.
+ */
+const MYSQL_FIELD_TYPE_TINY = 1;
+/**
+ * Turn `TINYINT(1)` cells back into real booleans, in place.
+ *
+ * MySQL stores a boolean as 1/0 and mysql2 returns the integer. Turbine still
+ * generates `ok: boolean` for the column ({@link mysqlTypeToTs}), so
+ * `row.ok === true` was false, `JSON.stringify(row)` emitted `1`, and a value
+ * the ORM itself wrote as `true` came back as a number.
+ *
+ * Done from the RESULT FIELDS rather than from mysql2's `typeCast` option on
+ * purpose. `typeCast` lives in {@link MYSQL_DRIVER_FLAGS}, which only applies
+ * to pools TURBINE builds; an injected mysql2 pool (a supported, documented
+ * entry point) would keep returning numbers at the top level while the join
+ * strategy's `jsonWireRule` returned booleans, i.e. fixing it there would have
+ * created exactly the strategy-dependent split this is meant to close. The
+ * field metadata is on every result from every pool.
+ *
+ * An expression column is never touched: `ok + 0` comes back as
+ * MYSQL_TYPE_LONGLONG with a different width, and only an exact
+ * (TINY, width 1) field is coerced.
+ */
+function coerceBooleanColumns(rows, fields) {
+    if (!Array.isArray(fields) || rows.length === 0)
+        return;
+    const names = [];
+    for (const f of fields) {
+        if (!f || f.columnType !== MYSQL_FIELD_TYPE_TINY || f.columnLength !== 1)
+            continue;
+        if (typeof f.name !== 'string')
+            continue;
+        names.push(f.name);
+    }
+    if (names.length === 0)
+        return;
+    for (const row of rows) {
+        for (const name of names) {
+            const v = row[name];
+            if (v === 1 || v === 0)
+                row[name] = v === 1;
+        }
+    }
+}
 /** Shape a mysql2 `[result]` into a `pg.QueryResult`-like object. */
-function shapeResult(result) {
+function shapeResult(result, fields) {
     if (Array.isArray(result)) {
-        return { rows: result, rowCount: result.length };
+        const rows = result;
+        coerceBooleanColumns(rows, fields);
+        return { rows, rowCount: rows.length };
     }
     // Write statement → ResultSetHeader (no rows). Expose insertId/lastID for the
     // `reselect` strategy to re-fetch the auto-increment row.
@@ -164,6 +212,19 @@ function augmentMysqlError(err) {
                 const parts = key.split('.');
                 target.constraint = parts.length > 1 ? parts[parts.length - 1] : key;
             }
+            // THE conflicting row value is in that message, between the quotes after
+            // "Duplicate entry". MySQL has no `detail` field, so 'safe' mode had
+            // nothing to redact and returned this error verbatim as `.cause`, putting
+            // the value into every log line that renders the cause chain. Flag it so
+            // the message is withheld in 'safe' mode (see markValueBearingMessage);
+            // the constraint NAME survives on `target.constraint` and in the typed
+            // UniqueConstraintError's own message, so nothing diagnostic is lost.
+            //
+            // Deliberately only 1062: the other MySQL codes handled here report
+            // column/constraint NAMES only ("Column 'x' cannot be null", "Check
+            // constraint 'c' is violated", the FK constraint definition), so flagging
+            // them would withhold a message that never carried a value.
+            (0, errors_js_1.markValueBearingMessage)(err);
             return err;
         }
         // ER_ROW_IS_REFERENCED_2 / ER_NO_REFERENCED_ROW_2 → foreign key violation
@@ -212,8 +273,8 @@ function normalizeQueryArgs(arg, values) {
 async function execOne(runner, sql, params) {
     const binding = toNamedBinding(params);
     try {
-        const [result] = binding ? await runner.execute(sql, binding) : await runner.query(sql);
-        return shapeResult(result);
+        const [result, fields] = binding ? await runner.execute(sql, binding) : await runner.query(sql);
+        return shapeResult(result, fields);
     }
     catch (err) {
         throw augmentMysqlError(err);
@@ -290,7 +351,11 @@ function mysqlTypeToTs(dialectType, nullable, columnType) {
     const t = dialectType.toLowerCase();
     const full = (columnType ?? '').toLowerCase();
     let base;
-    if (t === 'tinyint' && full === 'tinyint(1)')
+    // `tinyint(1)` can arrive either way: as (DATA_TYPE, COLUMN_TYPE) from the
+    // introspector's first pass, or as a single dialect type, because that is the
+    // spelling the introspector RECORDS for a boolean column (see the note there)
+    // and the `typeToTypeScript` dialect hook passes only the one string.
+    if (t === MYSQL_BOOLEAN_TYPE || (t === 'tinyint' && full === MYSQL_BOOLEAN_TYPE))
         base = 'boolean';
     else if (/^(tinyint|smallint|mediumint|int|integer|bigint)$/.test(t))
         base = 'number';
@@ -310,6 +375,63 @@ function mysqlTypeToTs(dialectType, nullable, columnType) {
         base = 'unknown';
     return nullable ? `${base} | null` : base;
 }
+/**
+ * The dialect-type spelling Turbine records for a MySQL boolean column.
+ *
+ * MySQL has no boolean type: `BOOLEAN` is an alias for `TINYINT(1)`, and
+ * `information_schema` reports DATA_TYPE `tinyint` for it, which is the same
+ * DATA_TYPE a genuine one-byte integer column has. The display width in
+ * COLUMN_TYPE is the ONLY thing that separates them, so the introspector keeps
+ * the full spelling for this one type rather than the bare DATA_TYPE. Anything
+ * reading a dialect type has to accept both spellings; the two places that
+ * matter are {@link mysqlTypeToTs} and {@link mysqlDialect.jsonWireRule}.
+ */
+const MYSQL_BOOLEAN_TYPE = 'tinyint(1)';
+/**
+ * Rewrite every boolean column's recorded dialect type to
+ * {@link MYSQL_BOOLEAN_TYPE}, returning a schema that is safe to key
+ * {@link mysqlDialect.jsonWireRule} on.
+ *
+ * WHY. Only the join strategy consults the recorded type, so a column whose
+ * type is spelled some other way reads as a boolean at the top level (the shim
+ * decides that from the RESULT FIELDS, which every pool has) and as 1/0 through
+ * a `with` join, which is the strategy-dependent split the boolean rule exists
+ * to close. Two schemas spell it differently and neither is wrong:
+ *
+ *  - a metadata file generated before Turbine started keeping the display width
+ *    records the bare DATA_TYPE `tinyint` (with `tsType: 'boolean'`, which is
+ *    what identifies it), so `turbine generate` is NOT required to get the fix;
+ *  - a code-first `defineSchema` column records the Postgres spelling
+ *    `boolean` / `bool`, which the DDL generator already emits as `TINYINT(1)`.
+ *
+ * A genuine one-byte integer column is never touched: it carries
+ * `tsType: 'number'`, and the `tsType` is the gate. Copy-on-write, because the
+ * argument is usually a shared exported constant and may also be handed to
+ * another engine's factory; an already-correct schema is returned unchanged and
+ * pays nothing.
+ */
+function normalizeBooleanDialectTypes(schema) {
+    const needsFix = (col) => {
+        if (!/^boolean\b/.test(col.tsType))
+            return false;
+        const recorded = (col.dialectType ?? col.pgType ?? '').toLowerCase();
+        return recorded === 'tinyint' || recorded === 'bool' || recorded === 'boolean';
+    };
+    let tables;
+    for (const [name, table] of Object.entries(schema.tables)) {
+        if (!table.columns.some(needsFix))
+            continue;
+        const columns = table.columns.map((col) => needsFix(col) ? { ...col, dialectType: MYSQL_BOOLEAN_TYPE, pgType: MYSQL_BOOLEAN_TYPE } : col);
+        if (!tables)
+            tables = { ...schema.tables };
+        tables[name] = {
+            ...table,
+            columns,
+            pgTypes: Object.fromEntries(columns.map((c) => [c.name, c.pgType])),
+        };
+    }
+    return tables ? { ...schema, tables } : schema;
+}
 /** Is a MySQL declared type a date/time type (so values coerce back to `Date`)? */
 function isMysqlDateType(dialectType) {
     const t = dialectType.toLowerCase();
@@ -477,6 +599,52 @@ exports.mysqlDialect = {
         if (t === 'decimal' || t === 'numeric') {
             return { sql: (ref) => `CAST(${ref} AS CHAR)`, decode: (value) => value };
         }
+        // A boolean is 1/0 on the wire, and the driver shim turns that back into
+        // true/false on every direct read (see coerceBooleanColumns). JSON_OBJECT
+        // renders the same column as a JSON number and has no column metadata to
+        // consult, so without this the join strategy alone would keep returning
+        // 1/0: the same strategy-dependent type flip the json rule below exists to
+        // prevent. Carried as text because the decode half only runs on a string
+        // cell, and a plain CAST is enough here (unlike SQLite, MySQL enforces the
+        // column type, so the value is always an integer and `Number` reproduces
+        // the driver's own reading of anything that is not 0 or 1).
+        if (t === MYSQL_BOOLEAN_TYPE) {
+            return {
+                sql: (ref) => `CAST(${ref} AS CHAR)`,
+                decode: (value) => {
+                    if (value === '1')
+                        return true;
+                    if (value === '0')
+                        return false;
+                    if (typeof value !== 'string' || !/^-?\d+$/.test(value))
+                        return value;
+                    return Number(value);
+                },
+            };
+        }
+        // A `json` column gets NO rule, and that is the fix rather than the absence
+        // of one. It used to read differently depending on the relation strategy:
+        // the driver handed back text while JSON_OBJECT, which knows the column is
+        // JSON, embedded it as a real nested value, so parsing the row yielded an
+        // object. Under the default `'auto'` the strategy is decided per query by
+        // row counts and index coverage, so adding a `limit` to
+        // `findMany({ with: { org: true } })` flipped `org.meta` from a string to
+        // an object with no other change.
+        //
+        // A `CAST(… AS CHAR)` carrier closes that, but only for a pool Turbine
+        // built: the text half of it came from a `typeCast` override in
+        // MYSQL_DRIVER_FLAGS, and an injected mysql2 pool (a documented entry
+        // point) never sees those flags, so it read the column as an object at the
+        // top level and as a string through the join. That trades one split for
+        // another. So the agreement is built on what BOTH pool shapes already do:
+        // mysql2 parses a `json` column by default, JSON_OBJECT embeds it parsed,
+        // and with the `typeCast` override gone every read path lands on the same
+        // parsed value. It is also what `pg` returns for json/jsonb, so this is
+        // Postgres parity rather than a MySQL convention.
+        //
+        // Contrast SQLite and SQL Server, which return TEXT for the same schema:
+        // neither has a JSON column type, so the value there really is a string in
+        // a text column and there is nothing to parse it back from.
         // Binary columns are worse than lossy: JSON_OBJECT emits MySQL's internal
         // `base64:type15:…` marker string, so the caller got that text instead of
         // bytes. Carry hex and rebuild the buffer.
@@ -711,11 +879,14 @@ async function introspectMysqlWith(exec, schema, options = {}) {
             }
         }
         const maxLen = c.CHARACTER_MAXIMUM_LENGTH != null ? num(c.CHARACTER_MAXIMUM_LENGTH) : undefined;
+        // `tinyint(1)` is the one type whose DATA_TYPE is not enough to identify it
+        // (see MYSQL_BOOLEAN_TYPE); everything else keeps the bare DATA_TYPE.
+        const recordedType = c.COLUMN_TYPE.toLowerCase() === MYSQL_BOOLEAN_TYPE ? MYSQL_BOOLEAN_TYPE : dataType;
         const col = {
             name: c.COLUMN_NAME,
             field: (0, schema_js_1.snakeToCamel)(c.COLUMN_NAME),
-            dialectType: dataType,
-            pgType: dataType,
+            dialectType: recordedType,
+            pgType: recordedType,
             tsType: mysqlTypeToTs(dataType, nullable, c.COLUMN_TYPE),
             nullable,
             hasDefault: c.COLUMN_DEFAULT !== null || /auto_increment/i.test(c.EXTRA),
@@ -881,12 +1052,18 @@ const MYSQL_DRIVER_FLAGS = {
     // DATETIME/TIMESTAMP → JS Date interpreted as UTC (matches Postgres).
     dateStrings: false,
     timezone: 'Z',
-    // Force JSON columns to raw strings so the nested-relation parser
-    // (parseNestedRow) always takes its well-tested JSON.parse path, instead of
-    // mysql2's auto-parsed objects or a Buffer. Top-level JSON columns therefore
-    // come back as strings (consistent with the SQLite engine; parse them yourself).
-    // biome-ignore lint/suspicious/noExplicitAny: mysql2 typeCast field shape (has .type and .string()).
-    typeCast: (field, next) => (field.type === 'JSON' ? field.string() : next()),
+    //
+    // NOTE: deliberately NO `typeCast` JSON override here. There used to be one,
+    // pinning a `json` column to raw text so the nested-relation parser always
+    // took its JSON.parse path. It could only ever apply to pools TURBINE builds,
+    // and pool injection is a documented entry point, so it did not decide how a
+    // `json` column reads; it decided that the two pool shapes read it
+    // DIFFERENTLY (owned: string, injected: object). Every flag above is
+    // idempotent in that sense (a placeholder style, an integer policy, a time
+    // zone) and none of them changes a value's TYPE. Letting mysql2 parse a
+    // `json` column is what both pool shapes do by default, and it is also what
+    // `pg` does with json/jsonb, so the parsed value is the one answer that is
+    // reachable from every entry point. See `jsonWireRule` for the other half.
 };
 /** Parse a `mysql://user:pass@host:port/db` connection string into mysql2 config. */
 function parseMysqlConfig(connectionString) {
@@ -906,7 +1083,8 @@ function parseMysqlConfig(connectionString) {
         return config;
     }
     catch {
-        throw new errors_js_1.ConnectionError(`[turbine] Invalid MySQL connection string: "${connectionString}"`);
+        // Never echo the value, see malformedConnectionStringMessage.
+        throw new errors_js_1.ConnectionError((0, errors_js_1.malformedConnectionStringMessage)('MySQL', 'mysql://user:password@localhost:3306/app'));
     }
 }
 /**
@@ -962,8 +1140,11 @@ function isMysql2Pool(x) {
  *    `disconnect()` is a no-op, advanced config like SSL lives here).
  *
  * When Turbine builds the pool (string/config), it pins the correct mysql2 flags
- * (named placeholders, bignum, UTC dates, JSON-as-string), probes `SELECT VERSION()`
- * to reject MySQL < 8.0 / MariaDB, and `disconnect()` closes the pool it created.
+ * (named placeholders, bignum, UTC dates), probes `SELECT VERSION()` to reject
+ * MySQL < 8.0 / MariaDB, and `disconnect()` closes the pool it created. None of
+ * those flags changes a column's TYPE, so an injected pool reads every value
+ * the same way (see {@link MYSQL_DRIVER_FLAGS}); `namedPlaceholders: true` is
+ * the one an injected pool must set for itself.
  *
  * @example
  * ```ts
@@ -1018,7 +1199,11 @@ async function turbineMysql(target, schema, options = {}) {
         pool,
         dialect: exports.mysqlDialect,
         preparedStatements: false,
-    }, schema);
+    }, 
+    // The join strategy is the only read path that consults a recorded dialect
+    // type, so a schema that spells a boolean any other way would read 1/0
+    // there and `true`/`false` everywhere else.
+    normalizeBooleanDialectTypes(schema));
     if (owns) {
         // Turbine built this pool, so disconnect()/end() must close it. External
         // pools (injection) stay the caller's responsibility (disconnect() no-op),

package/dist/cjs/nested-write.js

@@ -318,8 +318,13 @@ function belongsToCorrelationWhere(ctx, rel, parentRow, parentTable) {
  */
 function scopeWhereToParent(target, correlation) {
     for (const key of Object.keys(correlation)) {
+        // Branded as Turbine's own: this `AND` has a FIXED arity of two, chosen
+        // here rather than reachable from a request body, so it must not cost the
+        // statement its server-side prepared name the way a caller-written
+        // combinator array does. Same reason the global-filter merge and the
+        // batched loader's correlation merge are branded.
         if (Object.hasOwn(target, key))
-            return { AND: [target, correlation] };
+            return (0, utils_js_1.markInternalCombinator)({ AND: [target, correlation] });
     }
     return { ...target, ...correlation };
 }

package/dist/cjs/pipeline-submittable.js

@@ -172,7 +172,8 @@ async function runPipelined(client, queries, options = {}) {
                 return;
             }
             if (!transactional && pipelineError) {
-                // In non-transactional mode, attach partial results to the error
+                // In non-transactional mode, report every slot: what each query returned
+                // or the error it failed with.
                 const partialResults = [];
                 for (let i = 0; i < queries.length; i++) {
                     const qErr = queryErrors[i];
@@ -189,8 +190,21 @@ async function runPipelined(client, queries, options = {}) {
                         }
                     }
                 }
-                pipelineError.results = partialResults;
-                reject(pipelineError);
+                // A REAL PipelineError, not the first driver error with a `results`
+                // property bolted onto it. The old shape happened to satisfy
+                // `err.results`, which is what the docs show callers reading, while
+                // leaving `err instanceof PipelineError` and `err.code ===
+                // 'TURBINE_E014'` permanently false: E014 was defined, documented, and
+                // never constructed. The driver error survives as `.cause` and as the
+                // first `error` slot, and `failedIndex` / `failedTag` (recorded on it by
+                // `onErrorMessage`) move onto the typed error's own fields.
+                const first = pipelineError;
+                reject(new errors_js_1.PipelineError({
+                    results: partialResults,
+                    failedIndex: first.failedIndex,
+                    failedTag: first.failedTag,
+                    cause: pipelineError,
+                }));
                 return;
             }
             // All succeeded, transform results

package/dist/cjs/pipeline.js

@@ -34,10 +34,21 @@ const pipeline_submittable_js_1 = require("./pipeline-submittable.js");
  */
 async function runSequential(client, queries, options = {}) {
     const { transactional = true } = options;
+    if (!transactional)
+        return runIndependent(client, queries);
     try {
-        if (transactional) {
+        // Transaction control is wrapped too. It used to be bare, so a connection
+        // that died between checkout and BEGIN (or at COMMIT) surfaced the raw
+        // driver error while every statement between them surfaced a typed
+        // TurbineError, and a caller branching on `err.code` saw neither
+        // `TURBINE_E004` nor a retryable flag for the one failure that is most
+        // worth retrying.
+        try {
             await client.query('BEGIN');
         }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
         const results = [];
         for (const q of queries) {
             let raw;
@@ -49,23 +60,78 @@ async function runSequential(client, queries, options = {}) {
             }
             results.push(q.transform(raw));
         }
-        if (transactional) {
+        try {
             await client.query('COMMIT');
         }
+        catch (err) {
+            throw (0, errors_js_1.wrapPgError)(err);
+        }
         return results;
     }
     catch (err) {
-        if (transactional) {
-            try {
-                await client.query('ROLLBACK');
-            }
-            catch {
-                // Best-effort rollback
-            }
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Best-effort rollback
         }
         throw err;
     }
 }
+/**
+ * Sequential fallback for `{ transactional: false }`: each query is
+ * INDEPENDENT, which is what that option promises and what the real pipeline
+ * path already did. A failing query records its slot and the batch keeps going
+ * (there is no transaction to poison), and if anything failed the whole batch
+ * rejects with a `PipelineError` carrying every slot.
+ *
+ * It used to `throw wrapPgError(err)` on the first failure instead. That both
+ * abandoned the remaining queries, contradicting the option's own docstring,
+ * and rejected with the raw driver error, so `err instanceof PipelineError` and
+ * `err.code === 'TURBINE_E014'` were permanently false on the one path that
+ * documents them, and `err.results` did not exist at all. The first failure is
+ * still reachable, as `.cause` and as the first `error` slot.
+ */
+async function runIndependent(client, queries) {
+    const slots = [];
+    let firstError;
+    let failedIndex;
+    let failedTag;
+    const fail = (index, error) => {
+        slots.push({ status: 'error', error });
+        if (firstError !== undefined)
+            return;
+        firstError = error;
+        failedIndex = index;
+        failedTag = queries[index]?.tag;
+    };
+    for (let i = 0; i < queries.length; i++) {
+        const q = queries[i];
+        let raw;
+        try {
+            raw = await client.query(q.sql, q.params);
+        }
+        catch (err) {
+            const wrapped = (0, errors_js_1.wrapPgError)(err);
+            fail(i, wrapped instanceof Error ? wrapped : new Error(String(wrapped)));
+            continue;
+        }
+        // A transform throw is a slot failure too, not a batch abort: that is what
+        // the real pipeline path's `finalize` does with the same situation. It is
+        // deliberately NOT run through wrapPgError, since it never came from the
+        // driver.
+        try {
+            slots.push({ status: 'ok', value: q.transform(raw) });
+        }
+        catch (err) {
+            fail(i, err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    if (firstError === undefined) {
+        return slots.map((slot) => slot.value);
+    }
+    throw new errors_js_1.PipelineError({ results: slots, failedIndex, failedTag, cause: firstError });
+}
 // ---------------------------------------------------------------------------
 // Pipeline executor (public)
 // ---------------------------------------------------------------------------

package/dist/cjs/powdb.d.ts

@@ -478,6 +478,29 @@ export declare const POWQL_KEYWORDS: ReadonlySet<string>;
  * errors when emitted bare, so quoting is strictly an improvement.
  */
 export declare function quotePowqlIdent(name: string): string;
+/**
+ * The DOTTED-position spelling of {@link quotePowqlIdent}: quote a name that
+ * falls outside the bare-identifier grammar, and only that.
+ *
+ * A dotted reference (`.col` in a filter, projection, `order`, `group`, or an
+ * `upsert on`) bypasses keyword lookup, so `.order` parses on every engine
+ * version and stays bare here, which is the ≤0.9 compatibility decision
+ * {@link quotePowqlIdent} documents and which this must not undo.
+ *
+ * What it does NOT excuse is interpolating the name RAW, which is what these
+ * sites used to do. Keyword-ness is a parsing question; a name outside
+ * `POWQL_BARE_IDENT` is a statement-integrity one, and that name is the only
+ * thing that can carry PowQL syntax into a statement whose values are all bound
+ * as `$N` params. Reaching it needs a hostile column name (an introspected
+ * database, a generator, a migration authored elsewhere) since names come from
+ * schema metadata, but "the names are trusted" is not the invariant the rest of
+ * this engine is written to. So: bare when the grammar allows it (byte-identical
+ * output for every ordinary and every keyword name), quoted when it does not,
+ * where the bare form was a parse error anyway. Verified against the engine that
+ * a quoted dotted reference parses everywhere the bare one does and yields the
+ * same result-column name.
+ */
+export declare function quotePowqlDotted(name: string): string;
 /**
  * Options for {@link powqlSchemaDDL}. Additive: with no options the DDL is
  * emitted unconditionally (pure-function callers / tests); pass `capabilities`

package/dist/cjs/powdb.js

@@ -99,6 +99,7 @@ exports.isJsonColumn = isJsonColumn;
 exports.powqlColumnType = powqlColumnType;
 exports.isPowdbDatetimeColumn = isPowdbDatetimeColumn;
 exports.quotePowqlIdent = quotePowqlIdent;
+exports.quotePowqlDotted = quotePowqlDotted;
 exports.deriveDesiredLinks = deriveDesiredLinks;
 exports.powdbLinkStatement = powdbLinkStatement;
 exports.powqlSchemaDDL = powqlSchemaDDL;
@@ -223,7 +224,8 @@ function parsePowdbUrl(connectionString) {
         u = new URL(connectionString);
     }
     catch {
-        throw new errors_js_1.ConnectionError(`[turbine] Invalid PowDB connection string: "${connectionString}"`);
+        // Never echo the value, see malformedConnectionStringMessage.
+        throw new errors_js_1.ConnectionError((0, errors_js_1.malformedConnectionStringMessage)('PowDB', 'powdb://user:password@127.0.0.1:5433/app'));
     }
     if (u.protocol !== 'powdb:') {
         throw new errors_js_1.ConnectionError(`[turbine] PowDB connection string must use the powdb:// scheme (got "${u.protocol}//…").`);
@@ -646,6 +648,36 @@ function quotePowqlIdent(name) {
     }
     return exports.POWQL_KEYWORDS.has(name) || !POWQL_BARE_IDENT.test(name) ? `\`${name}\`` : name;
 }
+/**
+ * The DOTTED-position spelling of {@link quotePowqlIdent}: quote a name that
+ * falls outside the bare-identifier grammar, and only that.
+ *
+ * A dotted reference (`.col` in a filter, projection, `order`, `group`, or an
+ * `upsert on`) bypasses keyword lookup, so `.order` parses on every engine
+ * version and stays bare here, which is the ≤0.9 compatibility decision
+ * {@link quotePowqlIdent} documents and which this must not undo.
+ *
+ * What it does NOT excuse is interpolating the name RAW, which is what these
+ * sites used to do. Keyword-ness is a parsing question; a name outside
+ * `POWQL_BARE_IDENT` is a statement-integrity one, and that name is the only
+ * thing that can carry PowQL syntax into a statement whose values are all bound
+ * as `$N` params. Reaching it needs a hostile column name (an introspected
+ * database, a generator, a migration authored elsewhere) since names come from
+ * schema metadata, but "the names are trusted" is not the invariant the rest of
+ * this engine is written to. So: bare when the grammar allows it (byte-identical
+ * output for every ordinary and every keyword name), quoted when it does not,
+ * where the bare form was a parse error anyway. Verified against the engine that
+ * a quoted dotted reference parses everywhere the bare one does and yields the
+ * same result-column name.
+ */
+function quotePowqlDotted(name) {
+    if (POWQL_BARE_IDENT.test(name))
+        return name;
+    if (name.includes('`')) {
+        throw new errors_js_1.ValidationError(`[turbine] Identifier "${name}" contains a backtick, which PowQL cannot represent.`);
+    }
+    return `\`${name}\``;
+}
 /**
  * Derive the entity links Turbine would declare from a schema's relations. One
  * link per single-column hasMany / hasOne / belongsTo relation, owned by the

package/dist/cjs/powql.d.ts

@@ -70,14 +70,28 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /** Resolve a camelCase field name (or raw snake) to its column metadata. */
     private column;
     /**
-     * PowQL column reference for a field. Unqualified it is a dotted field
-     * reference (`.snake_name`), which bypasses keyword lookup. When an `alias`
-     * is supplied (the F2 join path) it is qualified (`alias.snake_name`) and the
-     * column name is backtick-quoted if it is a reserved word (a qualified
-     * `p.order` does NOT bypass keyword lookup, unlike the dotted `.order`).
+     * PowQL column reference for a field: a dotted field reference
+     * (`.snake_name`), or `alias.snake_name` when an `alias` is supplied (the F2
+     * join path).
      */
     private ref;
-    /** Render a raw column name as a PowQL reference, qualified with `alias` when given. */
+    /**
+     * Render a raw column name as a PowQL reference, qualified with `alias` when
+     * given.
+     *
+     * BOTH branches quote now; they just use different rules, because the two
+     * positions have different grammars. A QUALIFIED `p.col` does not bypass
+     * keyword lookup, so it needs the full {@link quotePowqlIdent}. An
+     * UNQUALIFIED `.col` does bypass it, so it uses {@link quotePowqlDotted},
+     * which quotes only a name outside the bare-identifier grammar and leaves
+     * keywords bare, preserving the ≤0.9 compatibility decision documented on
+     * `quotePowqlIdent` while still keeping a column NAME from carrying syntax
+     * into the statement. This branch used to interpolate the name RAW, the one
+     * identifier site in the engine with no boundary at all.
+     *
+     * Output is byte-identical for every name the grammar accepts bare, keywords
+     * included, so no existing schema sees a different statement.
+     */
     private colRefName;
     /**
      * Push a value into the param array and return its `$N` placeholder. When the
@@ -316,7 +330,39 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * for a misspelling that is not there. Same message as the SQL engines.
      */
     private projectionColumn;
-    private projectedColumns;
+    /**
+     * The projected column list, plus the PK columns that are in it ONLY because
+     * this method put them there.
+     *
+     * PowDB needs the PK in the FETCH even when the caller excluded it: `upsert`
+     * reselects by PK, the m2m loader keys its target map on it (`targetByPk`),
+     * and the join path correlates through it. That force-add is right and stays.
+     * What was missing is the other half, taking it back off the ENTITY, so
+     * `select: { name: true }` returned `{ id, name }` and `omit: { id: true }`
+     * returned the column the caller asked to hide. The SQL engines return
+     * neither, so this was a cross-engine divergence on a documented-as-shared
+     * surface, and it was UNIFORM within PowDB: all five paths leaked (top-level
+     * find, batched loader, native join, nested projection, link path). The link
+     * path was the only one that even tried, and its strip could never fire: it
+     * decided "did the caller ask for the PK" by testing the column list AFTER
+     * the force-add, which by construction always contains it. So there was one
+     * strip in the code, dead since it shipped, and no query anywhere got the
+     * projection it asked for.
+     *
+     * `forcedPk` is what the strip needs, and it is deliberately NARROW: only the
+     * `select` / `omit` force-adds are listed. A PII-tagged PK kept through the
+     * DEFAULT projection is NOT, because that one is a deliberate, documented
+     * decision the SQL engines make identically (a row that cannot address itself
+     * is worse than a key that leaks its own value).
+     */
+    private projectionPlan;
+    /**
+     * Take the internally-forced PK columns back off the entities, so what the
+     * caller receives matches the `select` / `omit` they wrote. Called only after
+     * every consumer of the key (relation stitching, reselect) has finished with
+     * it. A no-op, and free, when nothing was forced.
+     */
+    private stripForcedPk;
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table
      * with no `pii: true` column, so untagged tables keep their prior projection.
@@ -337,7 +383,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * client-side strip of last resort, not defense-in-depth, for those paths; we
      * do NOT reverse-engineer an undocumented projection form. The upsert path is
      * different: it has no `returning` and reselects by PK through the read
-     * projection ({@link projectedColumns}), which already omits PII, so PII never
+     * projection ({@link projectionPlan}), which already omits PII, so PII never
      * crosses the wire there. If a future spec revision lets `returning` take a
      * projection, switch the write paths to emit the non-PII list and this strip
      * becomes a no-op like {@link parseWriteRow} on the SQL engines.
@@ -641,7 +687,13 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * DECLARED link that verifiably matches (`findMatchingLink`).
      */
     private planLinkPathRelation;
-    /** The flat `l<i>_<col>: t0.<linkName>.<col>` projection fields for one link plan. */
+    /**
+     * The flat `l<i>_<col>: t0.<linkName>.<col>` projection fields for one link
+     * plan. Both path segments and the synthetic result key go through
+     * `quotePowqlIdent`, the same identifier boundary every other emission site
+     * uses; verified against the engine that a quoted link hop and a quoted alias
+     * parse exactly like their bare forms and yield the same result-column names.
+     */
     private linkPathFields;
     /**
      * Reconstruct each link-path relation's child entity from its flat hop fields