turbine-orm 0.65.0 → 0.66.0

package/dist/cjs/powql.js

@@ -243,18 +243,32 @@ class PowqlInterface {
         return col;
     }
     /**
-     * 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).
      */
     ref(field, alias) {
         return this.colRefName(this.column(field).name, alias);
     }
-    /** 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.
+     */
     colRefName(name, alias) {
-        return alias ? `${alias}.${(0, powdb_js_1.quotePowqlIdent)(name)}` : `.${name}`;
+        return alias ? `${alias}.${(0, powdb_js_1.quotePowqlIdent)(name)}` : `.${(0, powdb_js_1.quotePowqlDotted)(name)}`;
     }
     /**
      * Push a value into the param array and return its `$N` placeholder. When the
@@ -361,7 +375,8 @@ class PowqlInterface {
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     alwaysFalse() {
         const pk = this.meta.primaryKey[0] ?? this.meta.columns[0]?.name;
-        return `(.${pk} is null and .${pk} is not null)`;
+        const ref = pk === undefined ? '.__turbine_missing_pk' : this.colRefName(pk);
+        return `(${ref} is null and ${ref} is not null)`;
     }
     // -------------------------------------------------------------------------
     // WHERE builder
@@ -876,8 +891,8 @@ class PowqlInterface {
             for (let i = 0; i < targetPks.length; i += junctionChunk) {
                 const chunk = targetPks.slice(i, i + junctionChunk);
                 const params = [];
-                const keyClause = this.inClause(`.${targetJCol}`, chunk, params, targetJColMeta);
-                const { rows } = await this.exec(`${(0, powdb_js_1.quotePowqlIdent)(through.table)} filter ${keyClause} { .${sourceJCol} }`, params, timeout, 'findMany');
+                const keyClause = this.inClause(this.colRefName(targetJCol), chunk, params, targetJColMeta);
+                const { rows } = await this.exec(`${(0, powdb_js_1.quotePowqlIdent)(through.table)} filter ${keyClause} { ${this.colRefName(sourceJCol)} }`, params, timeout, 'findMany');
                 for (const r of rows) {
                     const v = r[sourceJCol];
                     if (v != null)
@@ -922,7 +937,32 @@ class PowqlInterface {
         }
         return this.column(field).name;
     }
-    projectedColumns(select, omit, includePii) {
+    /**
+     * 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).
+     */
+    projectionPlan(select, omit, includePii) {
         // Same two shape refusals as `resolveProjection` on the SQL engines, with
         // the shared messages, and for a live reason here: this path used to
         // APPLY select-minus-omit while the SQL engines ignored the `omit` half,
@@ -942,14 +982,20 @@ class PowqlInterface {
         }
         const pk = new Set(this.meta.primaryKey);
         let cols = this.meta.columns.map((c) => c.name);
+        const forcedPk = [];
         const hasSelect = select && Object.keys(select).length;
         if (hasSelect) {
             const picked = new Set(Object.entries(select)
                 .filter(([, v]) => v)
                 .map(([k]) => this.projectionColumn(k, 'select')));
-            // Always keep the PK so reselect / relation stitching has a key to work with.
-            for (const key of pk)
+            // Always keep the PK so reselect / relation stitching has a key to work
+            // with; record the ones the caller did NOT name so they can be taken back
+            // off the entity once the stitching is done.
+            for (const key of pk) {
+                if (!picked.has(key))
+                    forcedPk.push(key);
                 picked.add(key);
+            }
             cols = cols.filter((c) => picked.has(c));
         }
         else if (!includePii) {
@@ -974,9 +1020,28 @@ class PowqlInterface {
             // target map on the PK (`targetByPk`), so every target collapsed onto the
             // single bucket "undefined", no parent matched, and the relation came
             // back `[]` for every row with no error.
+            for (const key of dropped) {
+                if (pk.has(key) && !forcedPk.includes(key))
+                    forcedPk.push(key);
+            }
             cols = cols.filter((c) => !dropped.has(c) || pk.has(c));
         }
-        return cols;
+        return { cols, forcedPk };
+    }
+    /**
+     * 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.
+     */
+    stripForcedPk(entities, forcedPk) {
+        if (forcedPk.length === 0 || entities.length === 0)
+            return;
+        const fields = forcedPk.map((c) => this.meta.reverseColumnMap[c] ?? c);
+        for (const entity of entities) {
+            for (const field of fields)
+                delete entity[field];
+        }
     }
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table
@@ -1005,7 +1070,7 @@ class PowqlInterface {
      * 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.
@@ -1021,7 +1086,7 @@ class PowqlInterface {
     }
     /** `{ .c1, .c2, … }` projection clause. */
     projection(cols) {
-        return `{ ${cols.map((c) => `.${c}`).join(', ')} }`;
+        return `{ ${cols.map((c) => this.colRefName(c)).join(', ')} }`;
     }
     /**
      * `order .c1 asc, .c2 desc` clause (empty string when no orderBy). Supports,
@@ -1243,7 +1308,7 @@ class PowqlInterface {
             this.assertPagination(this.effectiveLimit(args), args.offset, 'findMany');
             if (this.effectiveLimit(args) === 0)
                 return [];
-            const { rows, native, resolvedWhere, nestedPlans, linkPlans, residualWith } = await this.runFind(args, 'findMany');
+            const { rows, native, resolvedWhere, nestedPlans, linkPlans, residualWith, forcedPk } = await this.runFind(args, 'findMany');
             const entities = this.shape(rows, native);
             if (nestedPlans.length)
                 this.attachNestedRows(entities, nestedPlans);
@@ -1252,6 +1317,9 @@ class PowqlInterface {
             if (residualWith) {
                 await this.loadRelations(entities, residualWith, args.timeout, 0, { args, resolvedWhere }, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii'));
             }
+            // LAST: every consumer of the internally-forced PK (relation stitching,
+            // the loaders' correlation) has finished with it by here.
+            this.stripForcedPk(entities, forcedPk);
             return entities;
         });
     }
@@ -1273,7 +1341,7 @@ class PowqlInterface {
             throw new errors_js_1.UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-        const cols = this.projectedColumns(args.select, args.omit, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii'));
+        const { cols, forcedPk } = this.projectionPlan(args.select, args.omit, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii'));
         // Partition the `with` clause: nested-projection blocks vs loader residue.
         // A parent `distinct` never nests (distinct over a row containing a JSON
         // array is not a defined comparison), and a relation whose field name
@@ -1342,14 +1410,14 @@ class PowqlInterface {
             projection = this.projection(cols);
         }
         const powql = `${this.qt}${nest ? ' as t0' : ''}${distinct}${filter}${order}${limitClause}${offsetClause} ${projection}`;
-        return { powql, resolvedWhere, nestedPlans, linkPlans, residualWith };
+        return { powql, resolvedWhere, nestedPlans, linkPlans, residualWith, forcedPk };
     }
     /** Build + run the findMany select; returns raw rows, the serving wire, the resolved where, and the `with` partition. */
     async runFind(args, action = 'findMany') {
         const params = [];
-        const { powql, resolvedWhere, nestedPlans, linkPlans, residualWith } = await this.buildFind(args, params);
+        const { powql, resolvedWhere, nestedPlans, linkPlans, residualWith, forcedPk } = await this.buildFind(args, params);
         const { rows, native } = await this.exec(powql, params, args.timeout, action);
-        return { rows, native, resolvedWhere, nestedPlans, linkPlans, residualWith };
+        return { rows, native, resolvedWhere, nestedPlans, linkPlans, residualWith, forcedPk };
     }
     /**
      * Diagnostic surface: compile the same PowQL {@link findMany} would run for
@@ -1385,7 +1453,7 @@ class PowqlInterface {
                 args = { ...args, where: expanded };
         }
         return this.withMiddleware('findUnique', args, async () => {
-            const { rows, native, nestedPlans, linkPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
+            const { rows, native, nestedPlans, linkPlans, residualWith, forcedPk } = await this.runFind({ ...args, limit: 1 }, 'findUnique');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
@@ -1395,13 +1463,15 @@ class PowqlInterface {
                 this.attachLinkRows(entities, linkPlans, native);
             if (residualWith)
                 await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii'));
+            // See findMany: the strip is last, after every consumer of the key.
+            this.stripForcedPk(entities, forcedPk);
             return entities[0];
         });
     }
     async findFirst(args = {}) {
         this.assertNoForceCustomPlan(args);
         return this.withMiddleware('findFirst', args, async () => {
-            const { rows, native, nestedPlans, linkPlans, residualWith } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
+            const { rows, native, nestedPlans, linkPlans, residualWith, forcedPk } = await this.runFind({ ...args, limit: 1 }, 'findFirst');
             if (!rows.length)
                 return null;
             const entities = this.shape(rows, native);
@@ -1411,6 +1481,8 @@ class PowqlInterface {
                 this.attachLinkRows(entities, linkPlans, native);
             if (residualWith)
                 await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii'));
+            // See findMany: the strip is last, after every consumer of the key.
+            this.stripForcedPk(entities, forcedPk);
             return entities[0];
         });
     }
@@ -1498,7 +1570,7 @@ class PowqlInterface {
             const userSelect = options.select;
             const userOmit = options.omit;
             // The RAW shape rules, before the force-add below: the forced key makes
-            // an all-falsy select look populated to the child's projectedColumns,
+            // an all-falsy select look populated to the child's projectionPlan,
             // which would accept here what the nested-projection path refuses. Same
             // messages as the SQL engines' assertProjectionShape, same reason.
             if (userSelect) {
@@ -1618,8 +1690,9 @@ class PowqlInterface {
         for (let i = 0; i < parentKeys.length; i += junctionChunk) {
             const chunk = parentKeys.slice(i, i + junctionChunk);
             const params = [];
-            const keyClause = this.inClause(`.${sourceJCol}`, chunk, params, sourceJColMeta);
-            const powql = `${(0, powdb_js_1.quotePowqlIdent)(through.table)} filter ${keyClause} { .${sourceJCol}, .${targetJCol} }`;
+            const keyClause = this.inClause(this.colRefName(sourceJCol), chunk, params, sourceJColMeta);
+            const powql = `${(0, powdb_js_1.quotePowqlIdent)(through.table)} filter ${keyClause} ` +
+                `{ ${this.colRefName(sourceJCol)}, ${this.colRefName(targetJCol)} }`;
             const { rows } = await this.exec(powql, params, timeout, 'findMany');
             for (const row of rows) {
                 const sv = String(row[sourceJCol]);
@@ -1635,6 +1708,41 @@ class PowqlInterface {
         // (2) Target rows by PK, honouring the relation's own where/with/select/…
         const options = (opt === true ? {} : opt);
         const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        // This loader stitches on the TARGET's own primary key, so the PK has to be
+        // in the fetch even when the caller's select/omit excludes it, and has to
+        // come back off afterwards. Exactly the shape `loadRelation` uses for its
+        // correlation column: force it in here, strip it after stitching. It cannot
+        // be left to the projection's internal force-add, because that one is
+        // stripped before findMany returns (see projectionPlan) and the map would
+        // key every target on "undefined".
+        const userSelect = options.select;
+        const userOmit = options.omit;
+        // The RAW shape rules, before the force-add: same reason and same messages
+        // as `loadRelation`, since a forced key makes an all-falsy select look
+        // populated to the child's own projection check.
+        if (userSelect) {
+            if (!Object.values(userSelect).some(Boolean)) {
+                throw new errors_js_1.ValidationError((0, utils_js_1.selectNamesNothingMessage)(targetMeta.name));
+            }
+            if (userOmit && Object.values(userOmit).some(Boolean)) {
+                throw new errors_js_1.ValidationError((0, utils_js_1.selectOmitExclusiveMessage)(targetMeta.name));
+            }
+        }
+        const pkProjected = userSelect ? Boolean(userSelect[targetPkField]) : userOmit ? !userOmit[targetPkField] : true;
+        let fetchOptions = options;
+        if (!pkProjected) {
+            if (userSelect) {
+                fetchOptions = {
+                    ...options,
+                    select: { ...userSelect, [targetPkField]: true },
+                };
+            }
+            else if (userOmit) {
+                const omitWithoutPk = { ...userOmit };
+                delete omitWithoutPk[targetPkField];
+                fetchOptions = { ...options, omit: omitWithoutPk };
+            }
+        }
         const targetByPk = new Map();
         const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
         const targetChunk = this.keyChunkSize(targetMeta, targetPkCol);
@@ -1645,7 +1753,7 @@ class PowqlInterface {
                 [targetPkField]: { in: chunk },
             };
             const targets = (await targetQi.findMany({
-                ...options,
+                ...fetchOptions,
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
@@ -1667,6 +1775,13 @@ class PowqlInterface {
             }
             parent[relName] = children;
         }
+        // Stitching is done: take the forced PK back off. Iterating the map rather
+        // than the stitched lists is deliberate, one target can be linked from many
+        // parents and is the SAME object in each, so this touches each entity once.
+        if (!pkProjected) {
+            for (const target of targetByPk.values())
+                delete target[targetPkField];
+        }
     }
     // -------------------------------------------------------------------------
     // Nested relations: native PowQL joins (F2, opt-in via relationLoadStrategy)
@@ -1793,7 +1908,7 @@ class PowqlInterface {
         const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const parentKeyField = this.meta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
         const params = [];
-        const childCols = this.joinChildCols(targetQi, options, includePii);
+        const { cols: childCols, forcedPk: childForcedPk } = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
         this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
@@ -1806,7 +1921,7 @@ class PowqlInterface {
         // A READ: thread a read-shaped action through the exec seam.
         const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
-        const byKey = this.bucketByTpk(targetQi, rows, native);
+        const byKey = this.bucketByTpk(targetQi, rows, native, childForcedPk);
         for (const p of parents) {
             const key = this.joinKey(p[parentKeyField]);
             const matches = (key == null ? undefined : byKey.get(key)) ?? [];
@@ -1833,7 +1948,7 @@ class PowqlInterface {
         const targetPkCol = targetMeta.primaryKey[0];
         const parentRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const params = [];
-        const childCols = this.joinChildCols(targetQi, options, includePii);
+        const { cols: childCols, forcedPk: childForcedPk } = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 't', params, options.timeout ?? timeout);
         const proj = this.joinProjection(childCols, `j.${(0, powdb_js_1.quotePowqlIdent)(sourceJCol)}`, 't');
         const powql = `${targetQi.qt} as t ` +
@@ -1841,7 +1956,7 @@ class PowqlInterface {
             `join ${this.qt} as p on j.${(0, powdb_js_1.quotePowqlIdent)(sourceJCol)} = p.${(0, powdb_js_1.quotePowqlIdent)(sourceRefCol)}` +
             `${filter} ${proj}`;
         const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
-        const byKey = this.bucketByTpk(targetQi, rows, native);
+        const byKey = this.bucketByTpk(targetQi, rows, native, childForcedPk);
         for (const p of parents) {
             const key = this.joinKey(p[parentRefField]);
             p[relName] = (key == null ? undefined : byKey.get(key)) ?? [];
@@ -1853,12 +1968,12 @@ class PowqlInterface {
      * reserved correlation alias, so refuse rather than silently mis-stitch.
      */
     joinChildCols(targetQi, options, includePii = false) {
-        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
-        if (cols.includes('__tpk')) {
+        const plan = targetQi.projectionPlan(options.select, options.omit, includePii);
+        if (plan.cols.includes('__tpk')) {
             throw new errors_js_1.ValidationError(`[turbine] relation target "${targetQi.table}" has a column named "__tpk", which collides with the reserved ` +
                 `join correlation alias. Rename the column or load this relation with relationLoadStrategy: 'batched'.`);
         }
-        return cols;
+        return plan;
     }
     /**
      * `{ __tpk: <tpkExpr>, <col>: <childAlias>.<col>, … }`. Each child column is
@@ -1891,12 +2006,15 @@ class PowqlInterface {
         return parts.length ? ` filter ${parts.join(' and ')}` : '';
     }
     /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
-    bucketByTpk(targetQi, rows, native) {
+    bucketByTpk(targetQi, rows, native, forcedPk = []) {
         const byKey = new Map();
         for (const raw of rows) {
             const tpk = this.joinKey(raw.__tpk);
             delete raw.__tpk;
             const child = targetQi.shape([raw], native)[0];
+            // The correlation runs on `__tpk` (the PARENT's key), so an internally
+            // forced child PK has no consumer past this point and comes straight off.
+            targetQi.stripForcedPk([child], forcedPk);
             if (tpk == null)
                 continue;
             const bucket = byKey.get(tpk);
@@ -1984,7 +2102,7 @@ class PowqlInterface {
         if (options.limit === 0)
             return null;
         const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
-        const cols = targetQi.projectedColumns(options.select, options.omit, includePii);
+        const { cols, forcedPk } = targetQi.projectionPlan(options.select, options.omit, includePii);
         const byName = new Map(targetQi.meta.columns.map((c) => [c.name, c]));
         for (const c of cols) {
             const ts = (byName.get(c)?.tsType ?? '').replace(/\s*\|\s*null$/i, '').trim();
@@ -2013,7 +2131,7 @@ class PowqlInterface {
                 return null;
             keys.add(child.relName);
         }
-        return { relName, rel, options, targetQi, single, cols, children };
+        return { relName, rel, options, targetQi, single, cols, forcedPk, children };
     }
     /**
      * Compile one {@link NestedRelationPlan} into its projection-field block:
@@ -2084,6 +2202,8 @@ class PowqlInterface {
             for (const sub of plan.children)
                 plan.targetQi.attachOneNested(child, sub);
         }
+        // After the sub-blocks, for the same reason the top-level strip runs last.
+        plan.targetQi.stripForcedPk(shaped, plan.forcedPk);
         row[plan.relName] = plan.single ? (shaped[0] ?? null) : shaped;
     }
     // -------------------------------------------------------------------------
@@ -2183,7 +2303,10 @@ class PowqlInterface {
         if (options.orderBy || options.limit !== undefined || options.offset)
             return null;
         const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
-        const userCols = targetQi.projectedColumns(options.select, options.omit, includePii);
+        // `projectionPlan`, not `projectedColumns`: the plan is what carries
+        // `forcedPk`, and reading the column LIST alone is what made this path's
+        // strip dead. See the pkProjected line below.
+        const { cols: userCols, forcedPk } = targetQi.projectionPlan(options.select, options.omit, includePii);
         const byName = new Map(targetMeta.columns.map((c) => [c.name, c]));
         // Only adopt link paths where a JSON block genuinely cannot serve the case:
         // at least one projected child column is bigint/bytes. Otherwise nested
@@ -2204,13 +2327,20 @@ class PowqlInterface {
         if (!userCols.every((c) => this.isBareIdent(c)))
             return null;
         // Always project the target PK for presence detection (an absent to-one yields
-        // Empty at every hop; PK-Empty is the unambiguous "no linked row" signal). Add
-        // it if the user's projection dropped it, and remember to strip it back off.
+        // Empty at every hop; PK-Empty is the unambiguous "no linked row" signal).
+        // `projectionPlan` has already put it in `userCols`, so there is nothing to
+        // add; what is needed is knowing whether the CALLER asked for it.
+        //
+        // This is the line that was wrong. It read `userCols.includes(pkCol)`, and
+        // the projection force-adds the PK, so the answer was ALWAYS true and the
+        // strip in `attachLinkRows` never ran once. `forcedPk` is the caller's
+        // intent rather than the fetched list: it names the PK columns that are in
+        // `userCols` only because the projection put them there.
         const pkCol = targetMeta.primaryKey[0];
         if (!this.isBareIdent(pkCol))
             return null;
-        const pkProjected = userCols.includes(pkCol);
-        const cols = pkProjected ? userCols : [...userCols, pkCol];
+        const pkProjected = !forcedPk.includes(pkCol);
+        const cols = userCols;
         // Synthetic flat result keys (`l<index>_<col>`) keep the hop fields from
         // colliding with real parent columns or each other. Refuse the (astronomically
         // unlikely) case where a real parent/child column already uses the prefix.
@@ -2219,9 +2349,16 @@ class PowqlInterface {
             return null;
         return { relName, linkName: link.name, targetQi, cols, pkCol, pkProjected, keyPrefix };
     }
-    /** 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.
+     */
     linkPathFields(plan, parentAlias) {
-        return plan.cols.map((c) => `${plan.keyPrefix}${c}: ${parentAlias}.${plan.linkName}.${c}`);
+        const link = (0, powdb_js_1.quotePowqlDotted)(plan.linkName);
+        return plan.cols.map((c) => `${(0, powdb_js_1.quotePowqlIdent)(`${plan.keyPrefix}${c}`)}: ${parentAlias}.${link}.${(0, powdb_js_1.quotePowqlDotted)(c)}`);
     }
     /**
      * Reconstruct each link-path relation's child entity from its flat hop fields
@@ -2581,7 +2718,7 @@ class PowqlInterface {
             // (verified: "unexpected trailing token … 'returning'"), because it is one
             // atomic insert-or-update, not two branches. So upsert alone keeps the
             // reselect-by-PK fetch; create/update/delete all use `returning`.
-            await this.exec(`upsert ${this.qt} on .${pkCol} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout, 'upsert');
+            await this.exec(`upsert ${this.qt} on ${this.colRefName(pkCol)} { ${createBody} } on conflict { ${updateBody} }`, params, args.timeout, 'upsert');
             const pkField = this.meta.reverseColumnMap[pkCol] ?? pkCol;
             const row = await this.reselectByPk(createData[pkField], args.timeout);
             if (!row)
@@ -2754,9 +2891,9 @@ class PowqlInterface {
                     claim(entry, `column "${col.name}"`);
                     if (col.name !== entry)
                         claim(col.name, `column "${col.name}"`);
-                    groupExprs.push(`.${col.name}`);
-                    proj.push(`.${col.name}`);
-                    byOrderExprs.set(entry, `.${col.name}`);
+                    groupExprs.push(this.colRefName(col.name));
+                    proj.push(this.colRefName(col.name));
+                    byOrderExprs.set(entry, this.colRefName(col.name));
                     byReaders.push({ kind: 'plain', resultKey: entry, rowKey: col.name, col });
                 }
                 else {
@@ -2818,7 +2955,7 @@ class PowqlInterface {
                             (0, aggregates_js_1.assertAggregatePiiOptIn)(this.table, this.meta, key, col.name, `groupBy ${fn}`, (0, types_js_1.resolveUnsafeFlag)(args.includePii, 'includePii'));
                         }
                         claim(`${fn}_${col.name}`, `${fn} of column "${col.name}"`);
-                        const inner = `.${col.name}`;
+                        const inner = this.colRefName(col.name);
                         proj.push(`${alias}: ${powfn}(${inner})`);
                         aggReaders.push({ alias, outKey: `${fn}:${key}`, numeric: true });
                         aggOrderExprs.set(`${fn}:${key}`, `.${alias}`);