grafeo-ogm 2.5.3 → 2.6.0

package/dist/esm/compilers/selection.compiler.js

@@ -4,6 +4,7 @@ import { OGMError } from '../errors';
 import { buildRelPattern, resolveTargetDef } from '../schema/utils';
 import { buildInlineCypherFieldExpr, } from '../utils/cypher-field-projection';
 import { assertSafeIdentifier, assertSortDirection, escapeIdentifier, isPlainObject, mergeParams, } from '../utils/validation';
+import { lenientStrictMode } from '../utils/strict-mode';
 import { stitchUserAndPolicy, traversalBundle, } from './where.compiler';
 /**
  * v2.5.3 — the printed arguments of a parsed selectionSet field, so a
@@ -11,6 +12,52 @@ import { stitchUserAndPolicy, traversalBundle, } from './where.compiler';
  * selections carry the same arguments.
  */
 const argumentKeys = new WeakMap();
+/**
+ * v2.6.0 — the strict-mode warnings of each parsed selectionSet, replayed
+ * on cache hits (see `SelectionCompiler.replayParseWarnings`).
+ */
+const parseWarnings = new WeakMap();
+/**
+ * v2.6.0 — whether two selections of one response key can apply to the
+ * same object. A selection outside any fragment applies to every object;
+ * fragment-only selections overlap when their type conditions share a
+ * possible concrete type. Only overlapping selections with different
+ * arguments conflict (GraphQL's "fields in set can merge" rule).
+ */
+function canApplyToSameObject(a, b, ctx) {
+    if (!a || !b)
+        return true;
+    const types = new Set(a.flatMap((t) => ctx.possibleTypes(t)));
+    return b.some((t) => ctx.possibleTypes(t).some((p) => types.has(p)));
+}
+/**
+ * v2.6.0 — strict merge of a response key selected with different
+ * arguments: a conflict throws (as GraphQL validation does) when the two
+ * selections can apply to the same object; otherwise the incoming
+ * selection becomes (or joins) a per-type variant.
+ */
+function mergeTypeVariant(existing, incoming, key, ctx) {
+    const groups = [existing, ...(existing.typeVariants ?? [])];
+    for (const group of groups)
+        if (!sameArguments(group, incoming) &&
+            canApplyToSameObject(group.typeConditions, incoming.typeConditions, ctx))
+            throw new OGMError(`Fields "${key}" conflict because they have differing arguments. ` +
+                `Use different aliases on the fields to fetch both.`);
+    const same = groups.find((g) => sameArguments(g, incoming));
+    if (!same) {
+        existing.typeVariants = [...(existing.typeVariants ?? []), incoming];
+        return;
+    }
+    if (same.typeConditions && incoming.typeConditions)
+        same.typeConditions = [
+            ...new Set([...same.typeConditions, ...incoming.typeConditions]),
+        ];
+    mergeSameArguments(same, incoming, ctx);
+}
+function parseWarn(ctx, warning) {
+    if (!ctx.warnings.some((w) => w.code === warning.code && w.detail === warning.detail))
+        ctx.warnings.push(warning);
+}
 function sameArguments(a, b) {
     return (argumentKeys.get(a) ?? '') === (argumentKeys.get(b) ?? '');
 }
@@ -26,7 +73,7 @@ function sameArguments(a, b) {
  *   different types: recorded in `fieldByType` for a per-type projection.
  * - A selection outside any fragment makes the field unconditional.
  */
-function mergeSelection(list, seen, incoming) {
+function mergeSelection(list, seen, incoming, ctx) {
     const key = incoming.alias ?? incoming.fieldName;
     const existing = seen.get(key);
     if (!existing) {
@@ -38,6 +85,12 @@ function mergeSelection(list, seen, incoming) {
         mergeFragmentField(existing, incoming);
         return;
     }
+    if (ctx.strict &&
+        (!sameArguments(existing, incoming) || existing.typeVariants)) {
+        mergeTypeVariant(existing, incoming, key, ctx);
+        return;
+    }
+    const priorTypes = existing.typeConditions;
     if (existing.typeConditions && incoming.typeConditions)
         existing.typeConditions = [
             ...new Set([...existing.typeConditions, ...incoming.typeConditions]),
@@ -45,12 +98,51 @@ function mergeSelection(list, seen, incoming) {
     // Also selected outside any fragment → unconditional.
     else
         delete existing.typeConditions;
-    if (!sameArguments(existing, incoming))
+    if (!sameArguments(existing, incoming)) {
+        // v2.6.0 — GraphQL rejects one response key selected with different
+        // arguments when both selections can apply to the same object; 2.x
+        // keeps the first selection and drops the second. Fragments on types
+        // that can never be the same object are valid GraphQL: no warning
+        // (strict projects each per type, see `mergeTypeVariant`).
+        if (!canApplyToSameObject(priorTypes, incoming.typeConditions, ctx))
+            return;
+        parseWarn(ctx, {
+            code: 'selection-key-arguments',
+            detail: key,
+            problem: `The selectionSet selects "${key}" twice with different arguments; ` +
+                `2.x keeps the first selection and drops the second.`,
+            fix: 'reject the conflict, as GraphQL validation does',
+        });
         return;
+    }
+    mergeSameArguments(existing, incoming, ctx);
+}
+/** Merge a repeat of a response key with the same arguments (v2.5.3). */
+function mergeSameArguments(existing, incoming, ctx) {
+    const key = incoming.alias ?? incoming.fieldName;
+    if (existing.isConnection) {
+        if (ctx.strict) {
+            mergeConnectionEdgeSets(existing, incoming, ctx);
+            return;
+        }
+        if (!existing.totalCountOnly &&
+            !incoming.totalCountOnly &&
+            edgesKeyOf(existing) !== edgesKeyOf(incoming))
+            warnAliasedEdges(ctx, key, edgesKeyOf(existing), edgesKeyOf(incoming));
+        else
+            for (const which of ['node', 'properties']) {
+                const a = which === 'node' ? existing.children : existing.edgeChildren;
+                const b = which === 'node' ? incoming.children : incoming.edgeChildren;
+                const ka = existing.connectionAliases?.[which] ?? which;
+                const kb = incoming.connectionAliases?.[which] ?? which;
+                if (a && b && ka !== kb)
+                    warnAliasedEdgeKey(ctx, key, which, ka, kb);
+            }
+    }
     if (incoming.children)
-        existing.children = mergeSelectionLists(existing.children, incoming.children);
+        existing.children = mergeSelectionLists(existing.children, incoming.children, ctx);
     if (incoming.edgeChildren)
-        existing.edgeChildren = mergeSelectionLists(existing.edgeChildren, incoming.edgeChildren);
+        existing.edgeChildren = mergeSelectionLists(existing.edgeChildren, incoming.edgeChildren, ctx);
     if (existing.isConnection) {
         if (incoming.totalCount)
             existing.totalCount = true;
@@ -63,6 +155,168 @@ function mergeSelection(list, seen, incoming) {
             };
     }
 }
+/** The response key of a connection's (first) `edges` selection. */
+function edgesKeyOf(node) {
+    return node.connectionAliases?.edges ?? 'edges';
+}
+/** v2.6.0 — 2.x merges differently aliased `edges` under the first alias. */
+function warnAliasedEdges(ctx, connection, first, second) {
+    parseWarn(ctx, {
+        code: 'selection-aliased-edges',
+        detail: `${connection}:${first}:${second}`,
+        problem: `"${connection}" selects \`edges\` under two response keys ("${first}", "${second}"); ` +
+            `2.x returns only "${first}", with both selections merged into it.`,
+        fix: 'return each `edges` alias with its own selection',
+    });
+}
+/** v2.6.0 — 2.x merges differently aliased `node` / `properties` keys. */
+function warnAliasedEdgeKey(ctx, connection, which, first, second) {
+    parseWarn(ctx, {
+        code: 'selection-aliased-edge-key',
+        detail: `${connection}:${which}:${first}:${second}`,
+        problem: `"${connection}" selects \`${which}\` under two response keys ("${first}", "${second}") in its edges; ` +
+            `2.x returns only "${first}", with both selections merged into it.`,
+        fix: `return each \`${which}\` alias with its own selection`,
+    });
+}
+/** The `node` (or `properties`) keys of an edge set, main key first. */
+function edgeKeyEntries(set, which) {
+    const main = which === 'node' ? set.children : set.edgeChildren;
+    const extras = (which === 'node' ? set.extraNodes : set.extraProperties) ?? [];
+    return [
+        ...(main
+            ? [{ key: set.connectionAliases?.[which] ?? which, children: main }]
+            : []),
+        ...extras,
+    ];
+}
+/** Store `entries` (main key first) back on an edge set (strict). */
+function setEdgeKeyEntries(set, which, entries) {
+    const [main, ...rest] = entries;
+    const extrasProp = which === 'node' ? 'extraNodes' : 'extraProperties';
+    if (which === 'node')
+        set.children = main?.children;
+    else
+        set.edgeChildren = main?.children;
+    if (!main)
+        if (which === 'node')
+            delete set.children;
+        else
+            delete set.edgeChildren;
+    if (main && main.key !== which)
+        set.connectionAliases = { ...set.connectionAliases, [which]: main.key };
+    else if (set.connectionAliases) {
+        delete set.connectionAliases[which];
+        if (Object.keys(set.connectionAliases).length === 0)
+            delete set.connectionAliases;
+    }
+    if (rest.length > 0)
+        set[extrasProp] = rest;
+    else
+        delete set[extrasProp];
+}
+/** Merge two edge sets' `node` / `properties` keys by response key (strict). */
+function mergeEdgeKeys(into, from, ctx) {
+    for (const which of ['node', 'properties']) {
+        const merged = edgeKeyEntries(into, which).map((e) => ({ ...e }));
+        for (const entry of edgeKeyEntries(from, which)) {
+            const same = merged.find((m) => m.key === entry.key);
+            if (same)
+                same.children = mergeSelectionLists(same.children, entry.children, ctx);
+            else
+                merged.push({ ...entry });
+        }
+        setEdgeKeyEntries(into, which, merged);
+    }
+}
+/** A connection's edges selection as a standalone edge set (strict). */
+function asEdgeSet(node) {
+    if (node.totalCountOnly)
+        return null;
+    const set = {
+        fieldName: node.fieldName,
+        isScalar: false,
+        isRelationship: false,
+        isConnection: true,
+    };
+    if (node.children)
+        set.children = node.children;
+    if (node.edgeChildren)
+        set.edgeChildren = node.edgeChildren;
+    if (node.extraNodes)
+        set.extraNodes = node.extraNodes;
+    if (node.extraProperties)
+        set.extraProperties = node.extraProperties;
+    const { totalCount: _total, ...aliases } = node.connectionAliases ?? {};
+    if (Object.keys(aliases).length > 0)
+        set.connectionAliases = aliases;
+    return set;
+}
+/**
+ * v2.6.0 — strict merge of a connection selected twice (same arguments):
+ * edge sets merge by response key, so `a: edges` and `b: edges` stay apart.
+ */
+function mergeConnectionEdgeSets(existing, incoming, ctx) {
+    const sets = new Map();
+    const add = (set) => {
+        const k = edgesKeyOf(set);
+        const prev = sets.get(k);
+        if (!prev) {
+            sets.set(k, {
+                ...set,
+                ...(set.connectionAliases
+                    ? { connectionAliases: { ...set.connectionAliases } }
+                    : {}),
+            });
+            return;
+        }
+        // v2.6.0 — `node` / `properties` keys merge by response key too.
+        mergeEdgeKeys(prev, set, ctx);
+    };
+    for (const node of [existing, incoming]) {
+        const main = asEdgeSet(node);
+        if (main)
+            add(main);
+        for (const extra of node.extraEdges ?? [])
+            add(extra);
+    }
+    const totalAlias = existing.connectionAliases?.totalCount ??
+        incoming.connectionAliases?.totalCount;
+    if (incoming.totalCount)
+        existing.totalCount = true;
+    const [main, ...rest] = [...sets.values()];
+    if (main) {
+        delete existing.totalCountOnly;
+        if (main.children)
+            existing.children = main.children;
+        else
+            delete existing.children;
+        if (main.edgeChildren)
+            existing.edgeChildren = main.edgeChildren;
+        else
+            delete existing.edgeChildren;
+        if (main.extraNodes)
+            existing.extraNodes = main.extraNodes;
+        else
+            delete existing.extraNodes;
+        if (main.extraProperties)
+            existing.extraProperties = main.extraProperties;
+        else
+            delete existing.extraProperties;
+    }
+    const aliases = {
+        ...(main?.connectionAliases ?? {}),
+        ...(totalAlias !== undefined ? { totalCount: totalAlias } : {}),
+    };
+    if (Object.keys(aliases).length > 0)
+        existing.connectionAliases = aliases;
+    else
+        delete existing.connectionAliases;
+    if (rest.length > 0)
+        existing.extraEdges = rest;
+    else
+        delete existing.extraEdges;
+}
 /** Two scalars under one key, from fragments on different types (v2.5.3). */
 function mergeFragmentField(existing, incoming) {
     // Only scalars selected by inline fragments can differ per type; any
@@ -84,11 +338,11 @@ function mergeFragmentField(existing, incoming) {
         ...new Set([...existing.typeConditions, ...incoming.typeConditions]),
     ];
 }
-function mergeSelectionLists(base, extra) {
+function mergeSelectionLists(base, extra, ctx) {
     const list = [];
     const seen = new Map();
     for (const node of [...(base ?? []), ...extra])
-        mergeSelection(list, seen, node);
+        mergeSelection(list, seen, node, ctx);
     return list;
 }
 /** selectionSet field arguments the OGM honours, by field kind (v2.5.0). */
@@ -107,6 +361,43 @@ function assertNoVariables(value, where) {
         for (const f of value.fields)
             assertNoVariables(f.value, where);
 }
+/**
+ * v2.6.0 — whether `@include` / `@skip` keep a selectionSet field or inline
+ * fragment. 2.x ignores both directives (the selection is always kept) and
+ * warns; strict honours a literal `if: true | false` and rejects anything
+ * else, `$variables` included (selectionSet strings have no variables).
+ */
+function keptByDirectives(directives, where, ctx) {
+    const relevant = (directives ?? []).filter((d) => d.name.value === 'include' || d.name.value === 'skip');
+    if (relevant.length === 0)
+        return true;
+    if (!ctx.strict) {
+        parseWarn(ctx, {
+            code: 'selection-include-skip',
+            detail: where,
+            problem: `@include / @skip on "${where}" in a selectionSet is ignored in 2.x: ` +
+                `the selection is always kept.`,
+            fix: 'honour @include / @skip with a literal `if: true | false`',
+        });
+        return true;
+    }
+    let kept = true;
+    for (const directive of relevant) {
+        const name = directive.name.value;
+        const args = directive.arguments ?? [];
+        const arg = args.length === 1 ? args[0] : undefined;
+        if (!arg || arg.name.value !== 'if')
+            throw new OGMError(`@${name} on "${where}" takes exactly one argument: if: true | false.`);
+        if (arg.value.kind === Kind.VARIABLE)
+            throw new OGMError(`GraphQL variables are not supported in selectionSet directives (@${name} on "${where}": ` +
+                `$${arg.value.name.value}). Use a literal true or false.`);
+        if (arg.value.kind !== Kind.BOOLEAN)
+            throw new OGMError(`@${name}(if:) on "${where}" must be a literal true or false.`);
+        if (name === 'include' ? !arg.value.value : arg.value.value)
+            kept = false;
+    }
+    return kept;
+}
 function assertNoArguments(field, where) {
     if (field.arguments && field.arguments.length > 0)
         throw new OGMError(`Unsupported argument "${field.arguments[0].name.value}" on "${where}". ` +
@@ -188,7 +479,7 @@ function applyFieldArguments(field, node) {
  * connection fields with edge properties, and nested traversals with depth limiting.
  */
 export class SelectionCompiler {
-    constructor(schema, whereCompiler) {
+    constructor(schema, whereCompiler, strictMode) {
         this.schema = schema;
         /**
          * Real LRU cache of parsed selection sets, capped at
@@ -205,6 +496,17 @@ export class SelectionCompiler {
          */
         this.parseCache = new Map();
         this.whereCompiler = whereCompiler;
+        this.strictMode = strictMode ?? lenientStrictMode();
+    }
+    /**
+     * v2.6.0 — re-log (through the warn-once log) the strict-mode warnings
+     * found when `parsed` was first parsed. Parsed selections are cached —
+     * here and in `Model`'s cross-OGM cache — so a cache hit must still warn
+     * on an OGM instance that has not seen the shape yet.
+     */
+    replayParseWarnings(parsed) {
+        for (const w of parseWarnings.get(parsed) ?? [])
+            this.strictMode.warn(w.code, w.detail, w.problem, w.fix);
     }
     /** Clear the parse cache. Useful in tests to prevent cross-test pollution. */
     clearCache() {
@@ -285,7 +587,7 @@ export class SelectionCompiler {
                 }
                 assertSafeIdentifier(node.fieldName, 'selection field');
                 if (isAbstract && node.typeConditions) {
-                    const conditional = this.compileFragmentScalar(node, key, nodeVar, nodeDef, cypherScope);
+                    const conditional = this.compileFragmentScalar(node, key, nodeVar, nodeDef, cypherScope, params, paramCounter, policyContext);
                     if (conditional) {
                         parts.push(conditional);
                         continue;
@@ -312,6 +614,15 @@ export class SelectionCompiler {
                     : `.${escapeIdentifier(node.fieldName)}`);
                 continue;
             }
+            // v2.6.0 — strict: one key selected with different arguments by
+            // fragments on disjoint types, projected per concrete type.
+            if (node.typeVariants && node.typeVariants.length > 0) {
+                const variantCypher = this.compileTypeVariants(node, nodeVar, maxDepth, currentDepth, params, paramCounter, policyContext);
+                if (variantCypher) {
+                    parts.push(`${key}: ${variantCypher}`);
+                    continue;
+                }
+            }
             // v2.5.3 — a relationship / connection field selected through an
             // inline fragment on an abstract type that doesn't declare it.
             // (Union relationship fields keep their per-member CASE below.)
@@ -361,8 +672,15 @@ export class SelectionCompiler {
      * when the abstract type declares the field as `@cypher` itself, when a
      * condition isn't a concrete type, or when no fragment type declares it
      * as `@cypher`.
+     *
+     * v2.5.4 — under a policy context, each `@cypher` branch is also guarded
+     * by that member's own `read` clause (`WHEN n:B AND <B read> THEN …`),
+     * so a member's statement only projects for a node that passes the
+     * member's policy. The node filter (`compileTargetPolicyClause`) already
+     * requires every carried member's clause; this is defense in depth.
+     * Without a policy context the branches are unchanged.
      */
-    compileFragmentScalar(node, key, nodeVar, nodeDef, cypherScope) {
+    compileFragmentScalar(node, key, nodeVar, nodeDef, cypherScope, params, paramCounter, policyContext = null) {
         // v2.5.3 — `fieldByType`: sibling fragments selected different fields
         // under this key, so each type projects its own field.
         const perType = node.fieldByType;
@@ -390,10 +708,28 @@ export class SelectionCompiler {
                     : buildInlineCypherFieldExpr(prop.cypherStatement, nodeVar, `${def.typeName}.${field}`);
             else
                 expr = `${nodeVar}.${escapeIdentifier(field)}`;
-            return `WHEN ${nodeVar}:${escapeIdentifier(def.label)} THEN ${expr}`;
+            const guard = prop.isCypher && prop.cypherStatement
+                ? this.memberReadGuard(def, nodeVar, params, paramCounter, policyContext)
+                : '';
+            return `WHEN ${nodeVar}:${escapeIdentifier(def.label)}${guard} THEN ${expr}`;
         });
         return `${escapeIdentifier(key)}: CASE ${branches.join(' ')} END`;
     }
+    /**
+     * ` AND <member read clause>` guarding a fragment `@cypher` branch
+     * (v2.5.4); `''` without a policy context, when the member has no read
+     * clause, or when that clause needs `@cypher` preludes a projection
+     * cannot host (the node filter still enforces it).
+     */
+    memberReadGuard(def, nodeVar, params, paramCounter, policyContext) {
+        if (!policyContext || !this.whereCompiler || !params || !paramCounter)
+            return '';
+        const clause = this.whereCompiler.compileTargetPolicyClause(def.typeName, nodeVar, 'read', policyContext, paramCounter);
+        if (clause.cypher === null || clause.preludes.length > 0)
+            return '';
+        mergeParams(params, clause.params);
+        return ` AND ${clause.cypher}`;
+    }
     /**
      * Parse a GraphQL selection set string into SelectionNode[].
      *
@@ -407,6 +743,7 @@ export class SelectionCompiler {
             // order is the LRU iteration order we rely on for eviction.
             this.parseCache.delete(selectionSet);
             this.parseCache.set(selectionSet, cached);
+            this.replayParseWarnings(cached);
             return cached;
         }
         const trimmed = selectionSet.trim();
@@ -425,7 +762,16 @@ export class SelectionCompiler {
         const dummyField = opDef.selectionSet.selections[0];
         if (dummyField.kind !== Kind.FIELD || !dummyField.selectionSet)
             return [];
-        const result = this.convertSelectionSet(dummyField.selectionSet);
+        const ctx = {
+            strict: this.strictMode.strict,
+            warnings: [],
+            possibleTypes: (typeName) => this.possibleTypes(typeName),
+        };
+        const result = this.convertSelectionSet(dummyField.selectionSet, undefined, ctx);
+        if (ctx.warnings.length > 0) {
+            parseWarnings.set(result, ctx.warnings);
+            this.replayParseWarnings(result);
+        }
         // Real-LRU eviction: drop the oldest entry when the cache is full,
         // then insert. Pre-1.7.5 we just stopped caching at saturation,
         // forcing every subsequent miss to re-parse — a silent perf cliff
@@ -438,12 +784,24 @@ export class SelectionCompiler {
         this.parseCache.set(selectionSet, result);
         return result;
     }
+    /**
+     * v2.6.0 — the concrete types a fragment on `typeName` can apply to (see
+     * `ParseContext.possibleTypes`). Unknown names stand for themselves.
+     */
+    possibleTypes(typeName) {
+        if (this.schema.nodes.has(typeName))
+            return [typeName];
+        const iface = this.schema.interfaces?.get(typeName);
+        if (iface)
+            return iface.implementedBy;
+        return this.schema.unions?.get(typeName) ?? [typeName];
+    }
     /**
      * Convert a GraphQL SelectionSetNode into SelectionNode[].
      */
     convertSelectionSet(selectionSet, 
     /** Type condition of the enclosing inline fragment, if any (v2.4.8). */
-    typeCondition) {
+    typeCondition, ctx) {
         const nodes = [];
         const seen = new Map();
         for (const sel of selectionSet.selections) {
@@ -454,15 +812,19 @@ export class SelectionCompiler {
             if (sel.kind === Kind.INLINE_FRAGMENT) {
                 const fragment = sel;
                 const condition = fragment.typeCondition?.name.value ?? typeCondition;
+                if (!keptByDirectives(fragment.directives, `... on ${condition ?? '(inline fragment)'}`, ctx))
+                    continue;
                 if (fragment.selectionSet)
-                    for (const merged of this.convertSelectionSet(fragment.selectionSet, condition))
-                        mergeSelection(nodes, seen, merged);
+                    for (const merged of this.convertSelectionSet(fragment.selectionSet, condition, ctx))
+                        mergeSelection(nodes, seen, merged, ctx);
                 continue;
             }
             if (sel.kind !== Kind.FIELD)
                 continue;
             const field = sel;
             const fieldName = field.name.value;
+            if (!keptByDirectives(field.directives, field.alias?.value ?? fieldName, ctx))
+                continue;
             // v2.5.0 — fields are keyed by their OUTPUT name, so the same field
             // under two aliases (`a: kids { .. } b: kids { .. }`) stays two
             // selections. Pre-2.5.0 they collapsed into one.
@@ -488,30 +850,82 @@ export class SelectionCompiler {
             if (hasChildren && field.selectionSet)
                 if (isConnection)
                     // For connections, parse edges -> node and edges -> properties
-                    this.parseConnectionChildren(field.selectionSet, node);
+                    this.parseConnectionChildren(field.selectionSet, node, ctx);
                 else
-                    node.children = this.convertSelectionSet(field.selectionSet);
-            mergeSelection(nodes, seen, node);
+                    node.children = this.convertSelectionSet(field.selectionSet, undefined, ctx);
+            mergeSelection(nodes, seen, node, ctx);
         }
         return nodes;
     }
     /**
      * Parse the children of a connection field, extracting node and edge children.
      */
-    parseConnectionChildren(selectionSet, parentNode) {
+    parseConnectionChildren(selectionSet, parentNode, ctx) {
         let selectsEdges = false;
+        // v2.6.0 — the response key of the first `edges`, and (strict) the edge
+        // sets of `edges` selected under other keys.
+        let firstEdgesKey;
+        const extras = new Map();
+        // v2.6.0 — the first `node` / `properties` key of each edge set.
+        const firstKeys = new Map();
+        const connectionName = parentNode.alias ?? parentNode.fieldName;
+        /**
+         * Where a `node` / `properties` selection under `key` goes: the edge
+         * set's own (first) key, or — strict, another key — its own entry.
+         */
+        const edgeKeyTarget = (set, which, key) => {
+            const firsts = firstKeys.get(set) ?? {};
+            firstKeys.set(set, firsts);
+            firsts[which] ?? (firsts[which] = key);
+            if (firsts[which] === key)
+                return null;
+            if (!ctx.strict) {
+                warnAliasedEdgeKey(ctx, connectionName, which, firsts[which], key);
+                return null;
+            }
+            const prop = which === 'node' ? 'extraNodes' : 'extraProperties';
+            const list = (set[prop] ?? (set[prop] = []));
+            let entry = list.find((e) => e.key === key);
+            if (!entry) {
+                assertSafeIdentifier(key, 'selection alias');
+                entry = { key, children: [] };
+                list.push(entry);
+            }
+            return entry;
+        };
         for (const sel of selectionSet.selections) {
             if (sel.kind !== Kind.FIELD)
                 continue;
             const field = sel;
             assertNoArguments(field, `${parentNode.fieldName}.${field.name.value}`);
+            if (!keptByDirectives(field.directives, `${parentNode.fieldName}.${field.name.value}`, ctx))
+                continue;
             if (field.name.value === 'totalCount') {
                 parentNode.totalCount = true;
                 this.recordConnectionAlias(parentNode, 'totalCount', field);
             }
+            let target = parentNode;
             if (field.name.value === 'edges') {
                 selectsEdges = true;
-                this.recordConnectionAlias(parentNode, 'edges', field);
+                const edgesKey = field.alias?.value ?? 'edges';
+                firstEdgesKey ?? (firstEdgesKey = edgesKey);
+                if (edgesKey !== firstEdgesKey)
+                    if (ctx.strict) {
+                        let extra = extras.get(edgesKey);
+                        if (!extra) {
+                            extra = {
+                                fieldName: parentNode.fieldName,
+                                isScalar: false,
+                                isRelationship: false,
+                                isConnection: true,
+                            };
+                            extras.set(edgesKey, extra);
+                        }
+                        target = extra;
+                    }
+                    else
+                        warnAliasedEdges(ctx, parentNode.alias ?? parentNode.fieldName, firstEdgesKey, edgesKey);
+                this.recordConnectionAlias(target, 'edges', field);
             }
             if (field.name.value === 'edges' && field.selectionSet)
                 for (const edgeSel of field.selectionSet.selections) {
@@ -519,20 +933,36 @@ export class SelectionCompiler {
                         continue;
                     const edgeField = edgeSel;
                     assertNoArguments(edgeField, `${parentNode.fieldName}.edges.${edgeField.name.value}`);
+                    if (!keptByDirectives(edgeField.directives, `${parentNode.fieldName}.edges.${edgeField.name.value}`, ctx))
+                        continue;
                     // v2.5.3 — a repeated `edges { node { … } }` merges its
                     // sub-selections; pre-2.5.3 the last one replaced the others.
                     if (edgeField.name.value === 'node' && edgeField.selectionSet) {
-                        this.recordConnectionAlias(parentNode, 'node', edgeField);
-                        parentNode.children = mergeSelectionLists(parentNode.children, this.convertSelectionSet(edgeField.selectionSet));
+                        const extra = edgeKeyTarget(target, 'node', edgeField.alias?.value ?? 'node');
+                        const parsed = this.convertSelectionSet(edgeField.selectionSet, undefined, ctx);
+                        if (extra)
+                            extra.children = mergeSelectionLists(extra.children, parsed, ctx);
+                        else {
+                            this.recordConnectionAlias(target, 'node', edgeField);
+                            target.children = mergeSelectionLists(target.children, parsed, ctx);
+                        }
                     }
                     if (edgeField.name.value === 'properties' && edgeField.selectionSet) {
-                        this.recordConnectionAlias(parentNode, 'properties', edgeField);
-                        parentNode.edgeChildren = mergeSelectionLists(parentNode.edgeChildren, this.convertSelectionSet(edgeField.selectionSet));
+                        const extra = edgeKeyTarget(target, 'properties', edgeField.alias?.value ?? 'properties');
+                        const parsed = this.convertSelectionSet(edgeField.selectionSet, undefined, ctx);
+                        if (extra)
+                            extra.children = mergeSelectionLists(extra.children, parsed, ctx);
+                        else {
+                            this.recordConnectionAlias(target, 'properties', edgeField);
+                            target.edgeChildren = mergeSelectionLists(target.edgeChildren, parsed, ctx);
+                        }
                     }
                 }
         }
         if (parentNode.totalCount && !selectsEdges)
             parentNode.totalCountOnly = true;
+        if (extras.size > 0)
+            parentNode.extraEdges = [...extras.values()];
     }
     /**
      * Keep the selectionSet alias of a connection key (v2.5.3). The first
@@ -558,12 +988,40 @@ export class SelectionCompiler {
      * Returns `null` (unchanged behaviour) when no fragment type declares it.
      */
     compileFragmentRelationship(node, nodeVar, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
+        const { branches, singular } = this.fragmentRelationshipBranches(node, node.typeConditions ?? [], nodeVar, maxDepth, currentDepth, params, paramCounter, policyContext);
+        if (branches.length === 0)
+            return null;
+        return `CASE ${branches.join(' ')} ELSE ${singular ? 'null' : '[]'} END`;
+    }
+    /**
+     * v2.6.0 — strict: a relationship / connection key with per-type
+     * variants (`SelectionNode.typeVariants`): one `CASE` whose branches
+     * compile each variant, with its own arguments and the target's read
+     * policy, against the concrete types its fragments apply to.
+     */
+    compileTypeVariants(node, nodeVar, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
+        const branches = [];
+        let singular = false;
+        for (const variant of [node, ...(node.typeVariants ?? [])]) {
+            const types = [
+                ...new Set((variant.typeConditions ?? []).flatMap((t) => this.possibleTypes(t))),
+            ];
+            const part = this.fragmentRelationshipBranches(variant, types, nodeVar, maxDepth, currentDepth, params, paramCounter, policyContext);
+            branches.push(...part.branches);
+            singular || (singular = part.singular);
+        }
+        if (branches.length === 0)
+            return null;
+        return `CASE ${branches.join(' ')} ELSE ${singular ? 'null' : '[]'} END`;
+    }
+    /** `WHEN n:T THEN <projection>` per type of `typeNames` declaring the field. */
+    fragmentRelationshipBranches(node, typeNames, nodeVar, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
         const relField = node.isConnection
             ? node.fieldName.replace(/Connection$/, '')
             : node.fieldName;
         const branches = [];
         let singular = node.isConnection;
-        for (const typeName of node.typeConditions ?? []) {
+        for (const typeName of typeNames) {
             const def = this.schema.nodes.get(typeName);
             const relDef = def?.relationships.get(relField);
             if (!def || !relDef)
@@ -576,9 +1034,7 @@ export class SelectionCompiler {
             if (expr)
                 branches.push(`WHEN ${nodeVar}:${escapeIdentifier(def.label)} THEN ${expr}`);
         }
-        if (branches.length === 0)
-            return null;
-        return `CASE ${branches.join(' ')} ELSE ${singular ? 'null' : '[]'} END`;
+        return { branches, singular };
     }
     /**
      * Compile a relationship field into a Cypher pattern comprehension.
@@ -811,6 +1267,11 @@ export class SelectionCompiler {
             mapParts.push(`${propertiesKey}: ${edgeVar} { ${edgeFields} }`);
             projectionKeys.push(propertiesKey);
         }
+        // v2.6.0 — strict: further `node` / `properties` keys of these edges.
+        for (const [k, expr] of this.extraEdgeKeyParts(node, childVar, edgeVar, targetDef, maxDepth, currentDepth, params, paramCounter, policyContext)) {
+            mapParts.push(`${k}: ${expr}`);
+            projectionKeys.push(k);
+        }
         // Inject synthetic sort scalars at the top level of the edge map so
         // apoc.coll.sortMulti (which only accepts top-level keys) can order the
         // collection. The outer list comprehension strips them on the way out.
@@ -957,7 +1418,12 @@ export class SelectionCompiler {
             : '';
         if (node.totalCountOnly)
             return `{ ${totalCount} }`;
-        const withTotal = totalCount ? `, ${totalCount}` : '';
+        // v2.6.0 — strict: `edges` selected under further response keys, each
+        // its own list over the same pattern and filter. Empty otherwise.
+        const extraEdges = (node.extraEdges ?? [])
+            .map((extra) => `, ${escapeIdentifier(edgesKeyOf(extra))}: [${pattern}${whereClause} | ${this.compileEdgeSetMap(extra, childVar, edgeVar, targetDef, maxDepth, currentDepth, params, paramCounter, policyContext)}]`)
+            .join('');
+        const withTotal = `${extraEdges}${totalCount ? `, ${totalCount}` : ''}`;
         if (sortKeyTokens.length === 0)
             return `{ ${edgesKey}: [${pattern}${whereClause} | ${innerMap}]${withTotal} }`;
         // Re-project only the user-facing keys so synthetic __skN scalars don't
@@ -967,6 +1433,61 @@ export class SelectionCompiler {
             : `{}`;
         return `{ ${edgesKey}: [x IN apoc.coll.sortMulti([${pattern}${whereClause} | ${innerMap}], [${sortKeyTokens.join(', ')}]) | ${outerProjection}]${withTotal} }`;
     }
+    /**
+     * v2.6.0 — the `{ node: …, properties: … }` map of one strict-mode extra
+     * edge set (see `SelectionNode.extraEdges`), mirroring `compileConnection`.
+     */
+    compileEdgeSetMap(set, childVar, edgeVar, targetDef, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
+        const parts = [];
+        const aliases = set.connectionAliases ?? {};
+        if (set.children && set.children.length > 0)
+            parts.push(`${aliases.node ? escapeIdentifier(aliases.node) : 'node'}: ${this.compile(set.children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter, null, policyContext)}`);
+        if (set.edgeChildren && set.edgeChildren.length > 0) {
+            const edgeFields = set.edgeChildren
+                .filter((c) => c.isScalar)
+                .map((c) => {
+                if (c.alias === undefined || c.alias === c.fieldName)
+                    return `.${escapeIdentifier(c.fieldName)}`;
+                assertSafeIdentifier(c.alias, 'selection alias');
+                return `${escapeIdentifier(c.alias)}: ${edgeVar}.${escapeIdentifier(c.fieldName)}`;
+            })
+                .join(', ');
+            parts.push(`${aliases.properties ? escapeIdentifier(aliases.properties) : 'properties'}: ${edgeVar} { ${edgeFields} }`);
+        }
+        for (const [k, expr] of this.extraEdgeKeyParts(set, childVar, edgeVar, targetDef, maxDepth, currentDepth, params, paramCounter, policyContext))
+            parts.push(`${k}: ${expr}`);
+        return `{ ${parts.join(', ')} }`;
+    }
+    /**
+     * v2.6.0 — strict: the projections of an edge set's further `node` /
+     * `properties` keys (`SelectionNode.extraNodes` / `extraProperties`),
+     * as `[escapedKey, expression]` pairs. Empty in 2.x default mode.
+     */
+    extraEdgeKeyParts(set, childVar, edgeVar, targetDef, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
+        const out = [];
+        for (const extra of set.extraNodes ?? [])
+            if (extra.children.length > 0)
+                out.push([
+                    escapeIdentifier(extra.key),
+                    this.compile(extra.children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter, null, policyContext),
+                ]);
+        for (const extra of set.extraProperties ?? []) {
+            const fields = extra.children
+                .filter((c) => c.isScalar)
+                .map((c) => {
+                if (c.alias === undefined || c.alias === c.fieldName)
+                    return `.${escapeIdentifier(c.fieldName)}`;
+                assertSafeIdentifier(c.alias, 'selection alias');
+                return `${escapeIdentifier(c.alias)}: ${edgeVar}.${escapeIdentifier(c.fieldName)}`;
+            });
+            if (fields.length > 0)
+                out.push([
+                    escapeIdentifier(extra.key),
+                    `${edgeVar} { ${fields.join(', ')} }`,
+                ]);
+        }
+        return out;
+    }
     /**
      * AND-combine an optional user where (`select.where` / `connectionWhere`)
      * with the target type's `'read'` policy and emit a `WHERE …` fragment