grafeo-ogm 2.4.7 → 2.5.0

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

@@ -5,6 +5,33 @@ import { buildRelPattern, getTargetLabelString, resolveTargetDef, } from '../sch
 import { assertSafeIdentifier, assertSafeLabel, assertSafePropertyName, escapeIdentifier, isPlainObject, mergeParams, } from '../utils/validation';
 import { coerceWriteValue, resolveDefaultWriteValue, wrapListItemExpr, wrapWhereParam, wrapWriteExpr, } from '../utils/write-coercion';
 import { WhereCompiler } from './where.compiler';
+/** The root node `n` of an update — the pre-2.4.8 names, unprefixed. */
+const TOP_SCOPE = {
+    sourceVar: 'n',
+    carryVars: ['n'],
+    withClause: 'WITH n',
+    varPrefix: '',
+    depth: 0,
+};
+/** Max depth of connects nested in connects (disconnects likewise). */
+const MAX_NESTED_LINK_DEPTH = 5;
+/**
+ * The scope of a connect / disconnect nested in an item whose target is
+ * bound as `targetVar`: that node becomes the source, everything in scope
+ * stays carried, and its own names are prefixed by it.
+ */
+function nestedScope(carryVars, targetVar, depth) {
+    if (depth >= MAX_NESTED_LINK_DEPTH)
+        throw new OGMError(`Nested connect / disconnect deeper than ${MAX_NESTED_LINK_DEPTH} levels is not supported.`);
+    const vars = [...new Set([...carryVars, targetVar])];
+    return {
+        sourceVar: targetVar,
+        carryVars: vars,
+        withClause: `WITH ${vars.join(', ')}`,
+        varPrefix: `${targetVar}_`,
+        depth: depth + 1,
+    };
+}
 /**
  * Compiles create, update, delete, and label mutations into Cypher + params.
  */
@@ -16,6 +43,13 @@ export class MutationCompiler {
          * Bounded by the number of node types in the schema (~50-100 entries).
          */
         this.labelCache = new Map();
+        /**
+         * Relationships narrowed from an abstract target to one member by the
+         * per-member dispatch. A BLANKET disconnect on one adds the member's
+         * label: the relationship type alone also reaches the other members, so
+         * pre-2.4.8 `{ Ebook: [{ disconnect: [{}] }] }` unlinked every member.
+         */
+        this.narrowedRelDefs = new WeakSet();
         this.logger = options?.logger;
         this.policyWhereCompiler = options?.whereCompiler;
     }
@@ -134,6 +168,9 @@ export class MutationCompiler {
      */
     isConnectFastPathEligible(items, targetNodeDef) {
         for (const item of items) {
+            // A nested `connect` is per item (v2.4.8): the UNWIND cannot run it.
+            if (item.connect != null)
+                return false;
             const where = item.where;
             if (where === undefined)
                 continue;
@@ -185,6 +222,36 @@ export class MutationCompiler {
         this.labelCache.set(nodeDef.typeName, labelStr);
         return labelStr;
     }
+    /**
+     * The MATCH that binds a connect TARGET by type. A node type keeps its
+     * label pattern; an interface / union target matches its MEMBERS' labels
+     * through a WHERE predicate (v2.4.8). Pre-2.4.8 it matched the abstract
+     * type's own label, which implementer and member nodes do not carry, so
+     * the connect linked nothing.
+     */
+    targetMatch(targetNodeDef, targetVar) {
+        const abstract = abstractTarget(targetNodeDef.typeName, this.schema);
+        if (!abstract)
+            return {
+                match: `MATCH (${targetVar}:${this.getCachedLabelString(targetNodeDef)})`,
+                labelPredicate: null,
+            };
+        const alternatives = abstract.members.map((m) => `${targetVar}:${this.getCachedLabelString(this.schema.nodes.get(m))}`);
+        return {
+            match: `MATCH (${targetVar})`,
+            labelPredicate: alternatives.length > 0 ? `(${alternatives.join(' OR ')})` : 'false',
+        };
+    }
+    /**
+     * Resolve a relationship's target for a nested write. Throws when the
+     * target is unknown — pre-2.4.8 the nested op was silently skipped.
+     */
+    requireTargetDef(relDef) {
+        const targetNodeDef = resolveTargetDef(relDef.target, this.schema);
+        if (!targetNodeDef)
+            throw new OGMError(`Cannot resolve the target type "${relDef.target}" of relationship "${relDef.fieldName}".`);
+        return targetNodeDef;
+    }
     /**
      * Generate CREATE Cypher for one or more nodes.
      * Handles scalar properties, nested relationship creates, and connects.
@@ -209,8 +276,10 @@ export class MutationCompiler {
             const input = inputs[i];
             const prefix = `create${i}`;
             const nodeVar = i === 0 ? 'n' : `n_${i}`;
-            const { propString, propParams } = this.buildCreateProperties(input, nodeDef, prefix);
+            // Labels first: an unsafe label must fail as such, before any
+            // input-key check (v2.5.0 rejects unknown keys).
             const labelStr = this.getCachedLabelString(nodeDef);
+            const { propString, propParams } = this.buildCreateProperties(input, nodeDef, prefix);
             lines.push(`CREATE (${nodeVar}:${labelStr} { ${propString} })`);
             mergeParams(params, propParams);
             createdVars.push(nodeVar);
@@ -285,6 +354,7 @@ export class MutationCompiler {
                 if (value === undefined)
                     continue;
                 assertSafePropertyName(key, 'update property');
+                assertKnownField(nodeDef, key, 'update');
                 const propDef = nodeDef.properties.get(key);
                 const paramName = `update_${key}`;
                 const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
@@ -436,19 +506,31 @@ export class MutationCompiler {
         const labelStr = this.getCachedLabelString(nodeDef);
         const lines = [];
         const params = {};
-        // Build MERGE key properties from where clause (scalar only)
+        // MERGE key: the `@id` / `@unique` fields of `where`, and nothing else
+        // (v2.5.0). Any other key throws:
+        //   - a plain field (`{ email, name }`) became part of the MERGE
+        //     pattern, so an existing node with that email but another name did
+        //     not match — MERGE created a DUPLICATE beside it;
+        //   - an operator key (`name_CONTAINS`) was dropped, silently widening
+        //     the match to the remaining keys;
+        //   - a typo (`usernme`) became a phantom property on the new node.
+        // Pre-1.7.4 any key set was accepted; 1.7.4 required at least one
+        // unique key but still let the others through.
         const mergeProps = [];
         const mergeKeyNames = [];
         for (const [key, value] of Object.entries(where)) {
-            if (value === undefined || value === null)
-                continue;
-            // Skip relationship suffixes and operators
-            if (key === 'AND' || key === 'OR' || key === 'NOT')
-                continue;
-            if (key.includes('_') && !nodeDef.properties.has(key))
+            if (value === undefined)
                 continue;
-            assertSafePropertyName(key, 'merge key');
             const propDef = nodeDef.properties.get(key);
+            if (!propDef ||
+                propDef.isCypher ||
+                !(propDef.isUnique || propDef.isGenerated))
+                throw new OGMError(`upsert "where" accepts only @id / @unique fields of ${nodeDef.typeName}; "${key}" is not one. ` +
+                    `MERGE matches on exactly these keys — put other fields in "create" / "update", ` +
+                    `or use findFirst() + create() / update() for a non-unique match.`);
+            if (value === null)
+                throw new OGMError(`upsert "where.${key}" is null; a MERGE key must have a value.`);
+            assertSafePropertyName(key, 'merge key');
             const paramName = `merge_${key}`;
             const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
             mergeProps.push(`${escapeIdentifier(key)}: ${valueExpr}`);
@@ -456,39 +538,21 @@ export class MutationCompiler {
             params[paramName] = coerceWriteValue(value, propDef);
         }
         if (mergeProps.length === 0)
-            throw new OGMError('upsert requires at least one scalar property in "where" for MERGE key');
-        // Validate that the MERGE key set contains at least one `@unique` or
-        // `@id` property. Pre-1.7.4 we accepted any key set, so:
-        //   - A typo in `where` (e.g. `usernme`) became a phantom MERGE
-        //     property — Neo4j happily created a node with that mis-named
-        //     attribute on first use.
-        //   - A non-unique `where` (e.g. `where: { country: 'AR' }`) matched
-        //     multiple existing nodes; MERGE then fans out across all of
-        //     them, applying ON MATCH SET to every match. Almost always a
-        //     bug, never the developer's intent.
-        // Requiring at least one unique/id key forces MERGE to target at
-        // most one row.
-        const hasUniqueOrId = mergeKeyNames.some((name) => {
-            const prop = nodeDef.properties.get(name);
-            // `isGenerated` is the parser's flag for the `@id` directive;
-            // `isUnique` is the flag for `@unique`. Either is sufficient
-            // to guarantee the MERGE pattern targets at most one row.
-            return prop !== undefined && (prop.isUnique || prop.isGenerated);
-        });
-        if (!hasUniqueOrId)
-            throw new OGMError(`upsert "where" must contain at least one property marked with @id or @unique. ` +
-                `Got [${mergeKeyNames.map((n) => `"${n}"`).join(', ')}] — none of these are unique on ${nodeDef.typeName}. ` +
-                `Without a unique key, MERGE can fan out across multiple existing nodes (applying ON MATCH SET to each) ` +
-                `or create phantom properties on typo. If you really want a non-unique merge, use create() + update().`);
+            throw new OGMError(`upsert requires at least one scalar property in "where" for MERGE key: ` +
+                `an @id or @unique field of ${nodeDef.typeName}.`);
         lines.push(`MERGE (n:${labelStr} { ${mergeProps.join(', ')} })`);
         // ON CREATE SET — all properties from create input (scalar only)
         const createSets = [];
         for (const [key, value] of Object.entries(create)) {
             if (value === undefined)
                 continue;
-            if (nodeDef.relationships.has(key))
-                continue;
+            if (nodeDef.relationships.has(key)) {
+                if (value === null)
+                    continue;
+                throw upsertRelationshipError(nodeDef, key, 'create');
+            }
             assertSafePropertyName(key, 'create property');
+            assertKnownField(nodeDef, key, 'create');
             const propDef = nodeDef.properties.get(key);
             const paramName = `onCreate_${key}`;
             const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
@@ -533,9 +597,13 @@ export class MutationCompiler {
         for (const [key, value] of Object.entries(update)) {
             if (value === undefined)
                 continue;
-            if (nodeDef.relationships.has(key))
-                continue;
+            if (nodeDef.relationships.has(key)) {
+                if (value === null)
+                    continue;
+                throw upsertRelationshipError(nodeDef, key, 'update');
+            }
             assertSafePropertyName(key, 'update property');
+            assertKnownField(nodeDef, key, 'update');
             const propDef = nodeDef.properties.get(key);
             const paramName = `onMatch_${key}`;
             const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
@@ -609,16 +677,13 @@ export class MutationCompiler {
             for (const key of Object.keys(item)) {
                 if (item[key] === undefined || scalarKeys.includes(key))
                     continue;
-                if (nodeDef.relationships.has(key)) {
-                    // Only the first item's relationship fields have ever been
-                    // rejected; in later items they were (and still are) skipped
-                    // unwritten. Rejecting them everywhere would make calls that
-                    // succeed today throw — tracked as a separate, breaking change.
-                    if (index > 0)
-                        continue;
-                    throw new OGMError(`createMany does not support relationship fields. Found: "${key}". Use create() for nested operations.`);
-                }
+                // v2.5.0 — rejected in EVERY item. Pre-2.5.0 only the first item's
+                // relationship fields were; in later items the nested input was
+                // skipped unwritten.
+                if (nodeDef.relationships.has(key))
+                    throw new OGMError(`createMany does not support relationship fields. Found: "${key}" in data[${index}]. Use create() for nested operations.`);
                 assertSafePropertyName(key, 'createMany property');
+                assertKnownField(nodeDef, key, 'createMany');
                 scalarKeys.push(key);
             }
         // Identify @id (generated) fields that are NOT provided in data
@@ -750,6 +815,7 @@ export class MutationCompiler {
             if (value === undefined)
                 continue;
             assertSafePropertyName(key, 'create property');
+            assertKnownField(nodeDef, key, 'create');
             const propDef = nodeDef.properties.get(key);
             const paramName = `${prefix}_${key}`;
             const valueExpr = wrapWriteExpr(`$${paramName}`, value, propDef);
@@ -785,19 +851,20 @@ export class MutationCompiler {
             const relDef = nodeDef.relationships.get(key);
             if (!relDef)
                 continue;
+            if (value == null)
+                continue;
             const relInput = value;
-            // Check if target is a union type — if so, relInput uses per-member keys
-            // e.g., items: { Ebook: { create: [...] } }
-            const isUnionTarget = !this.schema.nodes.has(relDef.target) &&
-                this.schema.unions?.has(relDef.target);
-            if (isUnionTarget) {
-                const unionMembers = this.schema.unions.get(relDef.target);
-                for (const [memberKey, memberValue] of Object.entries(relInput)) {
-                    if (!unionMembers.includes(memberKey))
-                        continue;
+            // Union / interface targets: per-member keys (e.g. items: { Ebook:
+            // { create: [...] } }) dispatch to the concrete member; an interface
+            // also takes the flat `{ connect, create }` shape (v2.4.8 — pre-2.4.8
+            // interface targets were skipped entirely, so nothing was written).
+            const abstract = abstractTarget(relDef.target, this.schema);
+            const memberEntries = abstract
+                ? perMemberEntries(relInput, abstract, key)
+                : null;
+            if (memberEntries) {
+                for (const [memberKey, memberValue] of memberEntries) {
                     const memberNodeDef = this.schema.nodes.get(memberKey);
-                    if (!memberNodeDef)
-                        continue;
                     const memberInput = memberValue;
                     // Process creates/connects for this union member
                     const memberLines = this.buildCreateRelationshipsForTarget(memberInput, memberNodeDef, relDef, nodeVar, `${prefix}_${key}_${memberKey}`, params, allVars, withClause, nestedCounter, policyContext, paramCounter);
@@ -806,9 +873,7 @@ export class MutationCompiler {
                 }
                 continue;
             }
-            const targetNodeDef = this.schema.nodes.get(relDef.target);
-            if (!targetNodeDef)
-                continue;
+            const targetNodeDef = this.requireTargetDef(relDef);
             const resultLines = this.buildCreateRelationshipsForTarget(relInput, targetNodeDef, relDef, nodeVar, `${prefix}_${key}`, params, allVars, withClause, nestedCounter, policyContext, paramCounter);
             nestedCounter += resultLines.counterUsed;
             lines.push(...resultLines.lines);
@@ -822,7 +887,8 @@ export class MutationCompiler {
     buildCreateRelationshipsForTarget(relInput, targetNodeDef, relDef, nodeVar, prefix, params, allVars, withClause, startCounter, policyContext, paramCounter) {
         const lines = [];
         let counter = 0;
-        const targetLabelStr = this.getCachedLabelString(targetNodeDef);
+        // A flat interface input (v2.4.8): each create names its implementer.
+        const abstract = abstractTarget(targetNodeDef.typeName, this.schema);
         // --- create ---
         if (relInput.create) {
             const createItems = Array.isArray(relInput.create)
@@ -830,15 +896,22 @@ export class MutationCompiler {
                 : [relInput.create];
             for (let ci = 0; ci < createItems.length; ci++) {
                 const createSpec = createItems[ci];
-                const nodeSpec = (createSpec.node ?? createSpec);
+                let nodeSpec = (createSpec.node ?? createSpec);
+                let createDef = targetNodeDef;
+                if (abstract) {
+                    const [member, memberSpec] = unwrapAbstractCreateNode(nodeSpec, abstract, relDef.fieldName);
+                    createDef = this.schema.nodes.get(member);
+                    nodeSpec = memberSpec;
+                }
+                const targetLabelStr = this.getCachedLabelString(createDef);
                 const createVar = `${nodeVar}_c${startCounter + counter}`;
                 counter++;
-                const { propString, propParams } = this.buildCreateProperties(nodeSpec, targetNodeDef, `${prefix}_create${ci}`);
+                const { propString, propParams } = this.buildCreateProperties(nodeSpec, createDef, `${prefix}_create${ci}`);
                 // Handle nested relationship creates within the created node
-                const nestedRelLines = this.buildCreateRelationships(nodeSpec, targetNodeDef, createVar, `${prefix}_create${ci}`, params, allVars, policyContext, paramCounter);
+                const nestedRelLines = this.buildCreateRelationships(nodeSpec, createDef, createVar, `${prefix}_create${ci}`, params, allVars, policyContext, paramCounter);
                 const propsClause = propString.length > 0
                     ? ` { ${propString} }`
-                    : ` { ${this.buildGeneratedIdClause(targetNodeDef)} }`;
+                    : ` { ${this.buildGeneratedIdClause(createDef)} }`;
                 const relPattern = buildRelPattern({
                     sourceVar: nodeVar,
                     relDef,
@@ -868,6 +941,9 @@ export class MutationCompiler {
                         targetVar: createVar,
                         edgeVar: relVar,
                         targetLabel: 'auto',
+                        // Abstract targets: no label — the created node never carries
+                        // the union / interface label (v2.4.8).
+                        schema: this.schema,
                     });
                     lines.push(`WITH ${[...allVars, createVar].join(', ')}`);
                     lines.push(`MATCH ${relArrow}`);
@@ -897,339 +973,426 @@ export class MutationCompiler {
                 ? relInput.connect
                 : [relInput.connect];
             for (let ci = 0; ci < connectItems.length; ci++) {
-                const connectSpec = connectItems[ci];
-                const whereSpec = connectSpec.where;
-                const edgeInput = connectSpec.edge;
                 // Wrap in CALL subquery so a failed MATCH doesn't kill the outer pipeline
-                lines.push(withClause);
-                lines.push(`CALL {`);
-                lines.push(withClause);
-                const connectVar = `${nodeVar}_cn${startCounter + counter}`;
+                const index = startCounter + counter;
                 counter++;
-                lines.push(`MATCH (${connectVar}:${targetLabelStr})`);
-                const connectConditions = [
-                    this.compileTargetWhere(whereSpec, connectVar, targetNodeDef, params, policyContext, paramCounter),
-                    this.buildTargetPolicyPredicate(targetNodeDef, connectVar, params, policyContext, paramCounter),
-                ].filter((c) => Boolean(c));
-                if (connectConditions.length > 0)
-                    lines.push(`WHERE ${connectConditions.join(' AND ')}`);
-                if (edgeInput && Object.keys(edgeInput).length > 0) {
-                    // Use bare target var (no label) since connectVar is already bound by MATCH.
-                    // Including labels on a bound variable in MERGE causes Neo4j to reject it.
-                    const relVar = `r_conn_${startCounter + counter - 1}`;
-                    assertSafeIdentifier(relDef.type, 'relationship type');
-                    const escapedRelType = escapeIdentifier(relDef.type);
-                    const mergePattern = relDef.direction === 'OUT'
-                        ? `(${nodeVar})-[${relVar}:${escapedRelType}]->(${connectVar})`
-                        : `(${nodeVar})<-[${relVar}:${escapedRelType}]-(${connectVar})`;
-                    lines.push(`MERGE ${mergePattern}`);
-                    const setItems = [];
-                    for (const [prop, val] of Object.entries(edgeInput)) {
-                        if (val === undefined)
-                            continue;
-                        assertSafePropertyName(prop, 'edge property');
-                        const edgePropDef = this.getEdgePropDef(relDef, prop);
-                        const paramName = `${prefix}_conn${ci}_edge_${prop}`;
-                        setItems.push(`r_conn_${startCounter + counter - 1}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
-                        params[paramName] = coerceWriteValue(val, edgePropDef);
-                    }
-                    if (setItems.length > 0)
-                        lines.push(`SET ${setItems.join(', ')}`);
-                }
-                else {
-                    const relPattern = buildRelPattern({
+                lines.push(...this.buildConnectItem({
+                    connectSpec: connectItems[ci],
+                    relDef,
+                    targetNodeDef,
+                    sourceVar: nodeVar,
+                    withClause,
+                    connectVar: `${nodeVar}_cn${index}`,
+                    relVar: `r_conn_${index}`,
+                    edgeParamPrefix: `${prefix}_conn${ci}`,
+                    returnAlias: `_ccn_${prefix}_${ci}`,
+                    params,
+                    policyContext,
+                    paramCounter,
+                    scope: {
                         sourceVar: nodeVar,
-                        relDef,
-                        targetVar: connectVar,
-                    });
-                    lines.push(`MERGE ${relPattern}`);
-                }
-                lines.push(`RETURN count(*) AS _ccn_${prefix}_${ci}`);
-                lines.push(`}`);
+                        carryVars: allVars,
+                        withClause,
+                        varPrefix: '',
+                        depth: 0,
+                    },
+                }));
             }
         }
         return { lines, counterUsed: counter };
     }
-    buildConnects(connect, nodeDef, params, policyContext, paramCounter) {
+    /**
+     * Top-level `connect`. A union / interface relationship keyed by member
+     * (`{ media: { Book: [...] } }`, the shape codegen emits) connects each
+     * member separately; a flat interface input matches the implementers by
+     * their own labels (v2.4.8 — pre-2.4.8 both matched the abstract type's
+     * label, which no node carries, and the per-member shape was never
+     * unwrapped, so the MATCH carried NO filter at all).
+     */
+    buildConnects(connect, nodeDef, params, policyContext, paramCounter, scope = TOP_SCOPE) {
         const lines = [];
         for (const [fieldName, spec] of Object.entries(connect)) {
             const relDef = nodeDef.relationships.get(fieldName);
             if (!relDef)
                 continue;
-            const targetNodeDef = resolveTargetDef(relDef.target, this.schema);
-            if (!targetNodeDef)
+            const abstract = abstractTarget(relDef.target, this.schema);
+            const memberEntries = abstract && !isBlanketSpec(spec)
+                ? perMemberEntries(spec, abstract, fieldName)
+                : null;
+            if (memberEntries) {
+                for (const [member, memberSpec] of memberEntries)
+                    lines.push(...this.buildRelConnects(memberSpec, this.narrowToMember(relDef, member), this.schema.nodes.get(member), `${fieldName}_${member}`, params, policyContext, paramCounter, scope));
                 continue;
-            const targetLabelStr = this.getCachedLabelString(targetNodeDef);
-            // Array connect
-            if (Array.isArray(spec)) {
-                if (spec.length === 0)
-                    continue; // Empty array — nothing to connect
-                // The UNWIND fast path compiles filters against per-row values and
-                // is only exact for plain scalar, non-null filters (see
-                // isConnectFastPathEligible). Everything else — null values,
-                // logical keys, traversals — takes one CALL subquery per item,
-                // compiled through WhereCompiler.
-                const useFastPath = this.isConnectFastPathEligible(spec, targetNodeDef);
-                if (!useFastPath)
-                    for (let ci = 0; ci < spec.length; ci++) {
-                        const connectSpec = spec[ci];
-                        const whereSpec = connectSpec.where;
-                        const edgeInput = connectSpec.edge;
-                        lines.push('WITH n');
-                        lines.push(`CALL {`);
-                        lines.push('WITH n');
-                        const connectVar = `target_${fieldName}_${ci}`;
-                        lines.push(`MATCH (${connectVar}:${targetLabelStr})`);
-                        const connectConditions = [
-                            this.compileTargetWhere(whereSpec, connectVar, targetNodeDef, params, policyContext, paramCounter),
-                            this.buildTargetPolicyPredicate(targetNodeDef, connectVar, params, policyContext, paramCounter),
-                        ].filter((c) => Boolean(c));
-                        if (connectConditions.length > 0)
-                            lines.push(`WHERE ${connectConditions.join(' AND ')}`);
-                        if (edgeInput && Object.keys(edgeInput).length > 0) {
-                            assertSafeIdentifier(relDef.type, 'relationship type');
-                            const escapedRelType = escapeIdentifier(relDef.type);
-                            const relVar = `r_conn_${fieldName}_${ci}`;
-                            const mergePattern = relDef.direction === 'OUT'
-                                ? `(n)-[${relVar}:${escapedRelType}]->(${connectVar})`
-                                : `(n)<-[${relVar}:${escapedRelType}]-(${connectVar})`;
-                            lines.push(`MERGE ${mergePattern}`);
-                            const setItems = [];
-                            for (const [prop, val] of Object.entries(edgeInput)) {
-                                if (val === undefined)
-                                    continue;
-                                assertSafePropertyName(prop, 'edge property');
-                                const edgePropDef = this.getEdgePropDef(relDef, prop);
-                                const paramName = `connect_${fieldName}_${ci}_edge_${prop}`;
-                                setItems.push(`${relVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
-                                params[paramName] = coerceWriteValue(val, edgePropDef);
-                            }
-                            if (setItems.length > 0)
-                                lines.push(`SET ${setItems.join(', ')}`);
-                        }
-                        else {
-                            const mergePattern = buildRelPattern({
-                                sourceVar: 'n',
-                                relDef,
-                                targetVar: connectVar,
-                            });
-                            lines.push(`MERGE ${mergePattern}`);
-                        }
-                        lines.push(`RETURN count(*) AS _ccn_${fieldName}_${ci}`);
-                        lines.push(`}`);
-                    }
-                else {
-                    // Scalar-only WHERE — use efficient UNWIND approach
-                    const paramName = `connect_${fieldName}`;
-                    // Strip undefined values from edge objects — Neo4j driver drops undefined,
-                    // causing param mismatches when the Cypher references nested edge properties.
-                    params[paramName] = spec.map((item) => {
-                        const edge = item.edge;
-                        if (!edge)
-                            return item;
-                        const cleaned = {};
-                        for (const [k, v] of Object.entries(edge))
-                            if (v !== undefined)
-                                cleaned[k] = coerceWriteValue(v, this.getEdgePropDef(relDef, k));
-                        return { ...item, edge: cleaned };
-                    });
-                    // Wrap in a CALL subquery: UNWIND + MATCH yields one row per
-                    // matched target (zero when nothing matches), which would
-                    // multiply — or drop — the updated node for every later clause.
-                    // Connecting to no target is a no-op, as in @neo4j/graphql.
-                    lines.push('WITH n');
-                    lines.push('CALL {');
-                    lines.push('WITH n');
-                    lines.push(`UNWIND $${paramName} AS connItem`);
-                    lines.push(`MATCH (target:${targetLabelStr})`);
-                    // Build WHERE from the first item's structure to determine the path.
-                    // Pre-1.7.4 we silently used `firstItem`'s keys for ALL items —
-                    // if `spec[1]` had different filter keys (e.g. an extra
-                    // `tenantId`), those keys were silently dropped from the WHERE.
-                    // Validate homogeneity now and throw if items diverge so the
-                    // caller knows to split into separate calls or use the per-item
-                    // CALL fallback.
-                    const firstItem = spec[0];
-                    const firstItemSig = computeConnectItemSignature(firstItem);
-                    for (let idx = 1; idx < spec.length; idx++) {
-                        const sig = computeConnectItemSignature(spec[idx]);
-                        if (sig !== firstItemSig)
-                            throw new OGMError(`connect array items have divergent shapes — item[0] has keys "${firstItemSig}" ` +
-                                `but item[${idx}] has keys "${sig}". The UNWIND fast path requires every item ` +
-                                `to share the same WHERE / edge key set; otherwise the additional keys are ` +
-                                `silently dropped. Split into separate connect calls, or normalise the items ` +
-                                `to share the same shape.`);
-                    }
-                    const whereConditions = this.extractConnectWhereConditions(firstItem, 'target', 'connItem', targetNodeDef);
-                    const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, 'target', params, policyContext, paramCounter);
-                    const unwindConditions = policyPredicate
-                        ? [...whereConditions, policyPredicate]
-                        : whereConditions;
-                    if (unwindConditions.length > 0)
-                        lines.push(`WHERE ${unwindConditions.join(' AND ')}`);
-                    const mergePattern = buildRelPattern({
-                        sourceVar: 'n',
-                        relDef,
-                        targetVar: 'target',
-                    });
-                    lines.push(`MERGE ${mergePattern}`);
-                    // Handle edge properties from first item structure
-                    const edgeProps = this.extractEdgeProperties(firstItem);
-                    if (edgeProps.length > 0) {
-                        // Use bare target var (no label) since target is already bound by MATCH
-                        assertSafeIdentifier(relDef.type, 'relationship type');
-                        const escapedRelType = escapeIdentifier(relDef.type);
-                        const mergeWithVar = relDef.direction === 'OUT'
-                            ? `(n)-[r:${escapedRelType}]->(target)`
-                            : `(n)<-[r:${escapedRelType}]-(target)`;
-                        // Replace MERGE line with one that has a variable
-                        lines[lines.length - 1] = `MERGE ${mergeWithVar}`;
-                        // r.prop is relationship property (escape), connItem.edge.prop is parameter map (no escape)
-                        const setItems = edgeProps.map((p) => `r.${escapeIdentifier(p)} = ${wrapListItemExpr(`connItem.edge.${p}`, spec.map((it) => it.edge?.[p]), this.getEdgePropDef(relDef, p))}`);
-                        lines.push(`SET ${setItems.join(', ')}`);
-                    }
-                    lines.push(`RETURN count(*) AS _conn_${fieldName}`);
-                    lines.push('}');
-                }
             }
+            lines.push(...this.buildRelConnects(spec, relDef, this.requireTargetDef(relDef), fieldName, params, policyContext, paramCounter, scope));
+        }
+        return lines;
+    }
+    /**
+     * One relationship's top-level connect. `tag` names its variables,
+     * params and aliases: the field name, or `<field>_<Member>` for an
+     * abstract relationship given per member, so two members never collide.
+     */
+    buildRelConnects(spec, relDef, targetNodeDef, tag, params, policyContext, paramCounter, scope) {
+        const lines = [];
+        const { sourceVar, withClause, varPrefix } = scope;
+        // Array connect
+        if (Array.isArray(spec)) {
+            if (spec.length === 0)
+                return lines; // Empty array — nothing to connect
+            // The UNWIND fast path compiles filters against per-row values and
+            // is only exact for plain scalar, non-null filters (see
+            // isConnectFastPathEligible). Everything else — null values,
+            // logical keys, traversals, abstract targets — takes one CALL
+            // subquery per item, compiled through WhereCompiler.
+            const useFastPath = !abstractTarget(targetNodeDef.typeName, this.schema) &&
+                this.isConnectFastPathEligible(spec, targetNodeDef);
+            if (!useFastPath)
+                for (let ci = 0; ci < spec.length; ci++)
+                    lines.push(...this.buildConnectItem({
+                        connectSpec: spec[ci],
+                        relDef,
+                        targetNodeDef,
+                        sourceVar,
+                        withClause,
+                        connectVar: `${varPrefix}target_${tag}_${ci}`,
+                        relVar: `${varPrefix}r_conn_${tag}_${ci}`,
+                        edgeParamPrefix: `${varPrefix}connect_${tag}_${ci}`,
+                        returnAlias: `_ccn_${varPrefix}${tag}_${ci}`,
+                        params,
+                        policyContext,
+                        paramCounter,
+                        scope,
+                    }));
             else {
-                // Single connect
-                const connectSpec = spec;
-                const whereSpec = connectSpec.where;
-                const edgeInput = connectSpec.edge;
-                // Same row-preserving isolation as the UNWIND path above.
-                lines.push('WITH n');
+                const targetVar = `${varPrefix}target`;
+                const relVar = `${varPrefix}r`;
+                const targetLabelStr = this.getCachedLabelString(targetNodeDef);
+                // Scalar-only WHERE — use efficient UNWIND approach
+                const paramName = `${varPrefix}connect_${tag}`;
+                // Strip undefined values from edge objects — Neo4j driver drops undefined,
+                // causing param mismatches when the Cypher references nested edge properties.
+                params[paramName] = spec.map((raw) => {
+                    // The WHERE reads `connItem.where.node.<key>`, so a bare-property
+                    // where (`{ where: { title } }`, which the fast path accepts) is
+                    // rebound under `node`. Pre-2.4.8 it was sent as-is: every lookup
+                    // was null, so the array connect silently linked nothing.
+                    const where = raw.where;
+                    const item = isPlainObject(where) &&
+                        !Object.keys(where).some((k) => CONNECTION_WHERE_KEYS.has(k))
+                        ? { ...raw, where: { node: where } }
+                        : raw;
+                    const edge = item.edge;
+                    if (!edge)
+                        return item;
+                    const cleaned = {};
+                    for (const [k, v] of Object.entries(edge))
+                        if (v !== undefined)
+                            cleaned[k] = coerceWriteValue(v, this.getEdgePropDef(relDef, k));
+                    return { ...item, edge: cleaned };
+                });
+                // Wrap in a CALL subquery: UNWIND + MATCH yields one row per
+                // matched target (zero when nothing matches), which would
+                // multiply — or drop — the updated node for every later clause.
+                // Connecting to no target is a no-op, as in @neo4j/graphql.
+                lines.push(withClause);
                 lines.push('CALL {');
-                lines.push('WITH n');
-                lines.push(`MATCH (target:${targetLabelStr})`);
-                const singleConnectConditions = [
-                    this.compileTargetWhere(whereSpec, 'target', targetNodeDef, params, policyContext, paramCounter),
-                    this.buildTargetPolicyPredicate(targetNodeDef, 'target', params, policyContext, paramCounter),
-                ].filter((c) => Boolean(c));
-                if (singleConnectConditions.length > 0)
-                    lines.push(`WHERE ${singleConnectConditions.join(' AND ')}`);
-                if (edgeInput && Object.keys(edgeInput).length > 0) {
+                lines.push(withClause);
+                lines.push(`UNWIND $${paramName} AS connItem`);
+                lines.push(`MATCH (${targetVar}:${targetLabelStr})`);
+                // Build WHERE from the first item's structure to determine the path.
+                // Pre-1.7.4 we silently used `firstItem`'s keys for ALL items —
+                // if `spec[1]` had different filter keys (e.g. an extra
+                // `tenantId`), those keys were silently dropped from the WHERE.
+                // Validate homogeneity now and throw if items diverge so the
+                // caller knows to split into separate calls or use the per-item
+                // CALL fallback.
+                const firstItem = spec[0];
+                const firstItemSig = computeConnectItemSignature(firstItem);
+                for (let idx = 1; idx < spec.length; idx++) {
+                    const sig = computeConnectItemSignature(spec[idx]);
+                    if (sig !== firstItemSig)
+                        throw new OGMError(`connect array items have divergent shapes — item[0] has keys "${firstItemSig}" ` +
+                            `but item[${idx}] has keys "${sig}". The UNWIND fast path requires every item ` +
+                            `to share the same WHERE / edge key set; otherwise the additional keys are ` +
+                            `silently dropped. Split into separate connect calls, or normalise the items ` +
+                            `to share the same shape.`);
+                }
+                const whereConditions = this.extractConnectWhereConditions(firstItem, targetVar, 'connItem', targetNodeDef);
+                const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, targetVar, params, policyContext, paramCounter);
+                const unwindConditions = policyPredicate
+                    ? [...whereConditions, policyPredicate]
+                    : whereConditions;
+                if (unwindConditions.length > 0)
+                    lines.push(`WHERE ${unwindConditions.join(' AND ')}`);
+                const mergePattern = buildRelPattern({
+                    sourceVar,
+                    relDef,
+                    targetVar,
+                });
+                lines.push(`MERGE ${mergePattern}`);
+                // Handle edge properties from first item structure
+                const edgeProps = this.extractEdgeProperties(firstItem);
+                if (edgeProps.length > 0) {
                     // Use bare target var (no label) since target is already bound by MATCH
                     assertSafeIdentifier(relDef.type, 'relationship type');
                     const escapedRelType = escapeIdentifier(relDef.type);
                     const mergeWithVar = relDef.direction === 'OUT'
-                        ? `(n)-[r:${escapedRelType}]->(target)`
-                        : `(n)<-[r:${escapedRelType}]-(target)`;
-                    lines.push(`MERGE ${mergeWithVar}`);
-                    const setItems = [];
-                    for (const [prop, val] of Object.entries(edgeInput)) {
-                        if (val === undefined)
-                            continue;
-                        const edgePropDef = this.getEdgePropDef(relDef, prop);
-                        const paramName = `connect_${fieldName}_edge_${prop}`;
-                        setItems.push(`r.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
-                        params[paramName] = coerceWriteValue(val, edgePropDef);
-                    }
-                    if (setItems.length > 0)
-                        lines.push(`SET ${setItems.join(', ')}`);
+                        ? `(${sourceVar})-[${relVar}:${escapedRelType}]->(${targetVar})`
+                        : `(${sourceVar})<-[${relVar}:${escapedRelType}]-(${targetVar})`;
+                    // Replace MERGE line with one that has a variable
+                    lines[lines.length - 1] = `MERGE ${mergeWithVar}`;
+                    // r.prop is relationship property (escape), connItem.edge.prop is parameter map (no escape)
+                    const setItems = edgeProps.map((p) => `${relVar}.${escapeIdentifier(p)} = ${wrapListItemExpr(`connItem.edge.${p}`, spec.map((it) => it.edge?.[p]), this.getEdgePropDef(relDef, p))}`);
+                    lines.push(`SET ${setItems.join(', ')}`);
                 }
-                else {
-                    const mergePattern = buildRelPattern({
-                        sourceVar: 'n',
-                        relDef,
-                        targetVar: 'target',
-                    });
-                    lines.push(`MERGE ${mergePattern}`);
-                }
-                lines.push(`RETURN count(*) AS _conn_${fieldName}`);
+                lines.push(`RETURN count(*) AS _conn_${varPrefix}${tag}`);
                 lines.push('}');
             }
+            return lines;
+        }
+        // Single connect — same row-preserving isolation as the UNWIND path.
+        return this.buildConnectItem({
+            connectSpec: spec,
+            relDef,
+            targetNodeDef,
+            sourceVar,
+            withClause,
+            connectVar: `${varPrefix}target`,
+            relVar: `${varPrefix}r`,
+            edgeParamPrefix: `${varPrefix}connect_${tag}`,
+            returnAlias: `_conn_${varPrefix}${tag}`,
+            params,
+            policyContext,
+            paramCounter,
+            scope,
+        });
+    }
+    /**
+     * One connect item, isolated in a CALL subquery so a MATCH that finds
+     * nothing (or many) never changes the outer row count:
+     *
+     *   <withClause>
+     *   CALL {
+     *     <withClause>
+     *     MATCH (cv[:Label])
+     *     WHERE <member labels> AND <where> AND <target `read` policy>
+     *     MERGE (src)-[rv:REL]->(cv) [SET rv.<edge> = …]
+     *     RETURN count(*) AS <alias>
+     *   }
+     *
+     * Shared by every connect site (top-level, nested in create, nested in
+     * update), which differ only in the names they pass.
+     */
+    buildConnectItem(a) {
+        const { connectSpec, relDef, targetNodeDef, sourceVar, connectVar } = a;
+        const lines = [];
+        const whereSpec = connectSpec?.where;
+        const edgeInput = connectSpec?.edge;
+        lines.push(a.withClause);
+        lines.push('CALL {');
+        lines.push(a.withClause);
+        const { match, labelPredicate } = this.targetMatch(targetNodeDef, connectVar);
+        lines.push(match);
+        const conditions = [
+            labelPredicate,
+            this.compileTargetWhere(whereSpec, connectVar, targetNodeDef, a.params, a.policyContext, a.paramCounter),
+            this.buildTargetPolicyPredicate(targetNodeDef, connectVar, a.params, a.policyContext, a.paramCounter),
+        ].filter((c) => Boolean(c));
+        if (conditions.length > 0)
+            lines.push(`WHERE ${conditions.join(' AND ')}`);
+        if (edgeInput && Object.keys(edgeInput).length > 0) {
+            // Use bare target var (no label) since connectVar is already bound by MATCH.
+            // Including labels on a bound variable in MERGE causes Neo4j to reject it.
+            assertSafeIdentifier(relDef.type, 'relationship type');
+            const escapedRelType = escapeIdentifier(relDef.type);
+            const mergePattern = relDef.direction === 'OUT'
+                ? `(${sourceVar})-[${a.relVar}:${escapedRelType}]->(${connectVar})`
+                : `(${sourceVar})<-[${a.relVar}:${escapedRelType}]-(${connectVar})`;
+            lines.push(`MERGE ${mergePattern}`);
+            const setItems = [];
+            for (const [prop, val] of Object.entries(edgeInput)) {
+                if (val === undefined)
+                    continue;
+                assertSafePropertyName(prop, 'edge property');
+                const edgePropDef = this.getEdgePropDef(relDef, prop);
+                const paramName = `${a.edgeParamPrefix}_edge_${prop}`;
+                setItems.push(`${a.relVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
+                a.params[paramName] = coerceWriteValue(val, edgePropDef);
+            }
+            if (setItems.length > 0)
+                lines.push(`SET ${setItems.join(', ')}`);
+        }
+        else {
+            const relPattern = buildRelPattern({
+                sourceVar,
+                relDef,
+                targetVar: connectVar,
+            });
+            lines.push(`MERGE ${relPattern}`);
+        }
+        // A `connect` nested in the item links the CONNECTED node onward
+        // (`connect: { posts: [{ where, connect: { tags: [...] } }] }`), with
+        // the same policy predicates at its level. Pre-2.4.8 it was ignored.
+        const nested = connectSpec?.connect;
+        if (nested != null) {
+            if (abstractTarget(targetNodeDef.typeName, this.schema))
+                throw new OGMError(`A nested "connect" inside a connect on "${relDef.fieldName}" (abstract type "${targetNodeDef.typeName}") ` +
+                    `must be keyed by the implementing type, e.g. { ${relDef.fieldName}: { Member: [{ where, connect }] } }.`);
+            const inner = nestedScope(a.scope.carryVars, connectVar, a.scope.depth);
+            for (const nestedConnect of Array.isArray(nested) ? nested : [nested]) {
+                if (!isPlainObject(nestedConnect))
+                    throw new OGMError(`A nested "connect" inside a connect on "${relDef.fieldName}" must be an object keyed by relationship.`);
+                lines.push(...this.buildConnects(nestedConnect, targetNodeDef, a.params, a.policyContext, a.paramCounter, inner));
+            }
         }
+        lines.push(`RETURN count(*) AS ${a.returnAlias}`);
+        lines.push('}');
         return lines;
     }
-    buildDisconnects(disconnect, nodeDef, params, policyContext, paramCounter) {
+    /**
+     * Top-level `disconnect`. Abstract relationships follow the connect
+     * rules (see buildConnects): per member, or flat on an interface,
+     * matching implementers by their own labels (v2.4.8 — pre-2.4.8 the
+     * target pattern used the interface / union label, so nothing matched).
+     */
+    buildDisconnects(disconnect, nodeDef, params, policyContext, paramCounter, scope = TOP_SCOPE) {
         const lines = [];
         for (const [fieldName, spec] of Object.entries(disconnect)) {
             const relDef = nodeDef.relationships.get(fieldName);
             if (!relDef)
                 continue;
-            const targetNodeDef = resolveTargetDef(relDef.target, this.schema) ?? undefined;
-            // Normalize spec to an array of disconnect items
-            const specItems = Array.isArray(spec) ? spec : [spec];
-            for (let si = 0; si < specItems.length; si++) {
-                const item = specItems[si];
-                const relVar = `r_${fieldName}_${si}`;
-                // Wrap in a CALL subquery: the OPTIONAL MATCH yields one row per
-                // matched relationship, which would multiply every later clause.
-                // `count(*)` collapses it back to exactly one row per `n`.
-                lines.push('WITH n');
-                lines.push('CALL {');
-                lines.push('WITH n');
-                if (item == null ||
-                    (typeof item === 'object' && Object.keys(item).length === 0)) {
-                    // Blanket disconnect — remove every relationship of this type to
-                    // a target the caller can READ. Like the `where` branch below, a
-                    // policy-bound context only unlinks nodes it can see; pre-2.5.0
-                    // the blanket form bound an anonymous `()` and also severed links
-                    // to policy-hidden nodes. Without policies there is no predicate
-                    // and the Cypher is unchanged.
-                    const blanketTarget = `target_${fieldName}_${si}`;
-                    const predicate = targetNodeDef
-                        ? this.buildTargetPolicyPredicate(targetNodeDef, blanketTarget, params, policyContext, paramCounter)
-                        : undefined;
-                    const pattern = buildRelPattern({
-                        sourceVar: 'n',
-                        relDef,
-                        targetVar: predicate ? blanketTarget : '',
-                        edgeVar: relVar,
-                    });
-                    lines.push(`OPTIONAL MATCH ${pattern}`);
-                    if (predicate)
-                        lines.push(`WHERE ${predicate}`);
-                    lines.push(`DELETE ${relVar}`);
-                }
-                else {
-                    // Specific disconnect with conditions
-                    const disconnectSpec = item;
-                    const whereSpec = disconnectSpec.where;
-                    const targetVar = `target_${fieldName}_${si}`;
-                    const pattern = buildRelPattern({
-                        sourceVar: 'n',
-                        relDef,
-                        targetVar,
-                        edgeVar: relVar,
-                        targetLabel: 'auto',
-                    });
-                    lines.push(`OPTIONAL MATCH ${pattern}`);
-                    if (!targetNodeDef)
-                        throw new OGMError(`Cannot resolve the target type "${relDef.target}" of relationship "${fieldName}".`);
-                    const disconnectConditions = [
-                        this.compileTargetWhere(whereSpec, targetVar, targetNodeDef, params, policyContext, paramCounter),
-                        this.buildTargetPolicyPredicate(targetNodeDef, targetVar, params, policyContext, paramCounter),
-                    ].filter((c) => Boolean(c));
-                    if (disconnectConditions.length > 0)
-                        lines.push(`WHERE ${disconnectConditions.join(' AND ')}`);
-                    lines.push(`DELETE ${relVar}`);
-                }
-                lines.push(`RETURN count(*) AS _${relVar}`);
-                lines.push('}');
+            const abstract = abstractTarget(relDef.target, this.schema);
+            // `null` / `{}` stays a blanket disconnect of the whole relationship.
+            const memberEntries = abstract && !isBlanketSpec(spec)
+                ? perMemberEntries(spec, abstract, fieldName)
+                : null;
+            if (memberEntries) {
+                for (const [member, memberSpec] of memberEntries)
+                    lines.push(...this.buildRelDisconnects(memberSpec, this.narrowToMember(relDef, member), this.schema.nodes.get(member), `${fieldName}_${member}`, params, policyContext, paramCounter, scope));
+                continue;
             }
+            lines.push(...this.buildRelDisconnects(spec, relDef, resolveTargetDef(relDef.target, this.schema) ?? undefined, fieldName, params, policyContext, paramCounter, scope));
         }
         return lines;
     }
     /**
-     * Dispatch update operations for a union-typed relationship.
+     * A `disconnect` nested in a disconnect item unlinks the disconnected
+     * node's OWN relationships (`disconnect: { posts: [{ where, disconnect:
+     * { tags: [...] } }] }`), with the same policy predicates at its level.
+     * Pre-2.4.8 it was ignored. `''`-free: no input, no lines.
+     */
+    buildNestedDisconnect(nested, relDef, targetNodeDef, targetVar, carryVars, params, policyContext, paramCounter, depth = 0) {
+        if (nested == null)
+            return [];
+        if (abstractTarget(targetNodeDef.typeName, this.schema))
+            throw new OGMError(`A nested "disconnect" inside a disconnect on "${relDef.fieldName}" (abstract type "${targetNodeDef.typeName}") ` +
+                `must be keyed by the implementing type, e.g. { ${relDef.fieldName}: { Member: [{ where, disconnect }] } }.`);
+        const inner = nestedScope(carryVars, targetVar, depth);
+        const lines = [];
+        for (const nestedDisconnect of Array.isArray(nested) ? nested : [nested]) {
+            if (!isPlainObject(nestedDisconnect))
+                throw new OGMError(`A nested "disconnect" inside a disconnect on "${relDef.fieldName}" must be an object keyed by relationship.`);
+            lines.push(...this.buildDisconnects(nestedDisconnect, targetNodeDef, params, policyContext, paramCounter, inner));
+        }
+        return lines;
+    }
+    /** One relationship's disconnect items; `tag` as in buildRelConnects. */
+    buildRelDisconnects(spec, relDef, targetNodeDef, tag, params, policyContext, paramCounter, scope) {
+        const lines = [];
+        const { sourceVar, withClause, varPrefix } = scope;
+        // Normalize spec to an array of disconnect items
+        const specItems = Array.isArray(spec) ? spec : [spec];
+        for (let si = 0; si < specItems.length; si++) {
+            const item = specItems[si];
+            const relVar = `${varPrefix}r_${tag}_${si}`;
+            // Wrap in a CALL subquery: the OPTIONAL MATCH yields one row per
+            // matched relationship, which would multiply every later clause.
+            // `count(*)` collapses it back to exactly one row per `n`.
+            lines.push(withClause);
+            lines.push('CALL {');
+            lines.push(withClause);
+            if (item == null ||
+                (typeof item === 'object' && Object.keys(item).length === 0)) {
+                // Blanket disconnect — remove every relationship of this type to
+                // a target the caller can READ. Like the `where` branch below, a
+                // policy-bound context only unlinks nodes it can see; pre-2.4.4
+                // the blanket form bound an anonymous `()` and also severed links
+                // to policy-hidden nodes. Without policies there is no predicate
+                // and the Cypher is unchanged.
+                const blanketTarget = `${varPrefix}target_${tag}_${si}`;
+                const predicate = targetNodeDef
+                    ? this.buildTargetPolicyPredicate(targetNodeDef, blanketTarget, params, policyContext, paramCounter)
+                    : undefined;
+                const pattern = buildRelPattern({
+                    sourceVar,
+                    relDef,
+                    targetVar: predicate ? blanketTarget : '',
+                    edgeVar: relVar,
+                    targetLabelRaw: this.blanketTargetLabel(relDef),
+                });
+                lines.push(`OPTIONAL MATCH ${pattern}`);
+                if (predicate)
+                    lines.push(`WHERE ${predicate}`);
+                lines.push(`DELETE ${relVar}`);
+            }
+            else {
+                // Specific disconnect with conditions
+                const disconnectSpec = item;
+                const whereSpec = disconnectSpec.where;
+                const targetVar = `${varPrefix}target_${tag}_${si}`;
+                const pattern = buildRelPattern({
+                    sourceVar,
+                    relDef,
+                    targetVar,
+                    edgeVar: relVar,
+                    targetLabel: 'auto',
+                    // An abstract target binds no label (its nodes carry their
+                    // members' labels); the member predicate below narrows it.
+                    schema: this.schema,
+                });
+                lines.push(`OPTIONAL MATCH ${pattern}`);
+                if (!targetNodeDef)
+                    throw new OGMError(`Cannot resolve the target type "${relDef.target}" of relationship "${relDef.fieldName}".`);
+                const labelPredicate = abstractTarget(targetNodeDef.typeName, this.schema)
+                    ? this.targetMatch(targetNodeDef, targetVar).labelPredicate
+                    : null;
+                const disconnectConditions = [
+                    labelPredicate,
+                    this.compileTargetWhere(whereSpec, targetVar, targetNodeDef, params, policyContext, paramCounter),
+                    this.buildTargetPolicyPredicate(targetNodeDef, targetVar, params, policyContext, paramCounter),
+                ].filter((c) => Boolean(c));
+                if (disconnectConditions.length > 0)
+                    lines.push(`WHERE ${disconnectConditions.join(' AND ')}`);
+                lines.push(`DELETE ${relVar}`);
+                lines.push(...this.buildNestedDisconnect(disconnectSpec.disconnect, relDef, targetNodeDef, targetVar, scope.carryVars, params, policyContext, paramCounter, scope.depth));
+            }
+            lines.push(`RETURN count(*) AS _${relVar}`);
+            lines.push('}');
+        }
+        return lines;
+    }
+    narrowToMember(relDef, member) {
+        const narrowed = { ...relDef, target: member };
+        this.narrowedRelDefs.add(narrowed);
+        return narrowed;
+    }
+    /** The label a blanket disconnect over `relDef` must keep (see above). */
+    blanketTargetLabel(relDef) {
+        if (!this.narrowedRelDefs.has(relDef))
+            return undefined;
+        return this.getCachedLabelString(this.schema.nodes.get(relDef.target));
+    }
+    /**
+     * Dispatch update operations for a union- or interface-typed
+     * relationship given per member (interfaces since v2.4.8).
      * Each member key in the input is recursed into buildUpdateRelationships
      * with a narrowed relDef pointing at the concrete member type.
      */
     dispatchUnionUpdateOps(key, memberEntries, relDef, nodeDef, sourceVar, prefix, params, depth, ancestorVars, policyContext, paramCounter) {
-        const unionMembers = this.schema.unions.get(relDef.target);
         const lines = [];
-        for (const [memberKey, memberValue] of Object.entries(memberEntries)) {
-            if (!unionMembers.includes(memberKey))
-                continue;
-            const memberNodeDef = this.schema.nodes.get(memberKey);
-            if (!memberNodeDef || memberValue == null)
-                continue;
-            const memberRelDef = {
-                ...relDef,
-                target: memberKey,
-            };
+        for (const [memberKey, memberValue] of memberEntries) {
+            const memberRelDef = this.narrowToMember(relDef, memberKey);
             const memberItems = Array.isArray(memberValue)
                 ? memberValue
                 : [memberValue];
@@ -1258,18 +1421,21 @@ export class MutationCompiler {
             const relDef = nodeDef.relationships.get(key);
             if (!relDef || value == null)
                 continue;
-            // Union targets use per-member keys — dispatch each member recursively
-            const isUnionTarget = !this.schema.nodes.has(relDef.target) &&
-                this.schema.unions?.has(relDef.target);
-            if (isUnionTarget) {
-                lines.push(...this.dispatchUnionUpdateOps(key, value, relDef, nodeDef, sourceVar, prefix, params, depth, ancestorVars, policyContext, paramCounter));
+            // Union / interface targets given per member — dispatch each member
+            // recursively. A flat interface input is handled below against the
+            // interface (v2.4.8 — pre-2.4.8 it was skipped, writing nothing).
+            const abstract = abstractTarget(relDef.target, this.schema);
+            const memberEntries = abstract
+                ? perMemberEntries(value, abstract, key)
+                : null;
+            if (memberEntries) {
+                lines.push(...this.dispatchUnionUpdateOps(key, memberEntries, relDef, nodeDef, sourceVar, prefix, params, depth, ancestorVars, policyContext, paramCounter));
                 continue;
             }
-            const targetNodeDef = this.schema.nodes.get(relDef.target);
-            if (!targetNodeDef)
-                continue;
-            const targetLabelStr = this.getCachedLabelString(targetNodeDef);
+            const targetNodeDef = this.requireTargetDef(relDef);
             const relPrefix = `${prefix}_${key}`;
+            // Past the dispatch, `abstract` is set only for a flat INTERFACE
+            // input (a flat union input threw in perMemberEntries).
             // Value can be an array (e.g., chapters: [{ create: ... }, { update: ... }])
             // or an object (e.g., author: { connect: ... })
             const items = Array.isArray(value)
@@ -1302,13 +1468,17 @@ export class MutationCompiler {
                     for (let di = 0; di < disconnectItems.length; di++) {
                         const disconnectSpec = disconnectItems[di];
                         const whereSpec = disconnectSpec.where;
+                        // A nested `disconnect` needs the target bound, so an item that
+                        // carries one is never the anonymous blanket form.
+                        const nestedDisconnect = disconnectSpec.disconnect;
                         const relVar = `r_disc_${key}_${i}_${di}`;
                         // Same isolation as the top-level disconnect: keep the
                         // OPTIONAL MATCH fan-out from multiplying later nested ops.
                         lines.push(withClause);
                         lines.push('CALL {');
                         lines.push(withClause);
-                        if (!whereSpec || Object.keys(whereSpec).length === 0) {
+                        if ((!whereSpec || Object.keys(whereSpec).length === 0) &&
+                            nestedDisconnect == null) {
                             // Blanket — same read-policy gate as the top-level blanket
                             // disconnect: only unlink targets the caller can read.
                             const blanketTarget = `${sourceVar}_disc${varCounter}`;
@@ -1320,6 +1490,7 @@ export class MutationCompiler {
                                 relDef,
                                 targetVar: predicate ? blanketTarget : '',
                                 edgeVar: relVar,
+                                targetLabelRaw: this.blanketTargetLabel(relDef),
                             });
                             lines.push(`OPTIONAL MATCH ${pattern}`);
                             if (predicate)
@@ -1335,6 +1506,9 @@ export class MutationCompiler {
                                 targetVar: discTarget,
                                 edgeVar: relVar,
                                 targetLabel: 'auto',
+                                // An interface target matches its implementers, which do
+                                // not carry the interface label (v2.4.8).
+                                schema: this.schema,
                             });
                             lines.push(`OPTIONAL MATCH ${pattern}`);
                             // Pre-1.8.1 this called `buildNodeWhereConditions` with
@@ -1347,12 +1521,16 @@ export class MutationCompiler {
                             // path (`buildDisconnects`). Restores backwards-compat with
                             // @neo4j/graphql-ogm's nested update.disconnect[].where shape.
                             const nestedDiscConditions = [
+                                abstract
+                                    ? this.targetMatch(targetNodeDef, discTarget).labelPredicate
+                                    : null,
                                 this.compileTargetWhere(whereSpec, discTarget, targetNodeDef, params, policyContext, paramCounter),
                                 this.buildTargetPolicyPredicate(targetNodeDef, discTarget, params, policyContext, paramCounter),
                             ].filter((c) => Boolean(c));
                             if (nestedDiscConditions.length > 0)
                                 lines.push(`WHERE ${nestedDiscConditions.join(' AND ')}`);
                             lines.push(`DELETE ${relVar}`);
+                            lines.push(...this.buildNestedDisconnect(nestedDisconnect, relDef, targetNodeDef, discTarget, allVars, params, policyContext, paramCounter));
                         }
                         lines.push(`RETURN count(*) AS _${relVar}`);
                         lines.push('}');
@@ -1364,61 +1542,30 @@ export class MutationCompiler {
                         ? item.connect
                         : [item.connect];
                     for (let ci = 0; ci < connectItems.length; ci++) {
-                        const connectSpec = connectItems[ci];
-                        const whereSpec = connectSpec.where;
-                        const edgeInput = connectSpec.edge;
                         // Wrap in CALL subquery so a failed MATCH doesn't kill the outer pipeline
-                        lines.push(withClause);
-                        lines.push(`CALL {`);
-                        lines.push(withClause);
                         const connectVar = `${sourceVar}_conn${varCounter}`;
                         varCounter++;
-                        lines.push(`MATCH (${connectVar}:${targetLabelStr})`);
-                        // Pre-1.8.1 this used `buildNodeWhereConditions` with
-                        // `(whereSpec?.node ?? whereSpec ?? {})`, which broke on
-                        // connection-shape inputs (NOT/AND/OR wrappers). Routing
-                        // through `buildConnectionWhereConditions` makes nested
-                        // connect handle the same shapes as nested disconnect and
-                        // top-level paths. Empty/undefined `whereSpec` short-circuits
-                        // to `[]` inside the helper, so the no-where case still works.
-                        const nestedConnConditions = [
-                            this.compileTargetWhere(whereSpec, connectVar, targetNodeDef, params, policyContext, paramCounter),
-                            this.buildTargetPolicyPredicate(targetNodeDef, connectVar, params, policyContext, paramCounter),
-                        ].filter((c) => Boolean(c));
-                        if (nestedConnConditions.length > 0)
-                            lines.push(`WHERE ${nestedConnConditions.join(' AND ')}`);
-                        if (edgeInput && Object.keys(edgeInput).length > 0) {
-                            // Use bare target var (no label) since connectVar is already bound by MATCH
-                            const relVar = `r_conn_${key}_${ci}`;
-                            assertSafeIdentifier(relDef.type, 'relationship type');
-                            const escapedRelType = escapeIdentifier(relDef.type);
-                            const mergePattern = relDef.direction === 'OUT'
-                                ? `(${sourceVar})-[${relVar}:${escapedRelType}]->(${connectVar})`
-                                : `(${sourceVar})<-[${relVar}:${escapedRelType}]-(${connectVar})`;
-                            lines.push(`MERGE ${mergePattern}`);
-                            const setItems = [];
-                            for (const [prop, val] of Object.entries(edgeInput)) {
-                                if (val === undefined)
-                                    continue;
-                                assertSafePropertyName(prop, 'edge property');
-                                const edgePropDef = this.getEdgePropDef(relDef, prop);
-                                const paramName = `${itemPrefix}_conn${ci}_edge_${prop}`;
-                                setItems.push(`r_conn_${key}_${ci}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, edgePropDef)}`);
-                                params[paramName] = coerceWriteValue(val, edgePropDef);
-                            }
-                            if (setItems.length > 0)
-                                lines.push(`SET ${setItems.join(', ')}`);
-                        }
-                        else {
-                            const relPattern = buildRelPattern({
+                        lines.push(...this.buildConnectItem({
+                            connectSpec: connectItems[ci],
+                            relDef,
+                            targetNodeDef,
+                            sourceVar,
+                            withClause,
+                            connectVar,
+                            relVar: `r_conn_${key}_${ci}`,
+                            edgeParamPrefix: `${itemPrefix}_conn${ci}`,
+                            returnAlias: `_cn_${key}_${ci}`,
+                            params,
+                            policyContext,
+                            paramCounter,
+                            scope: {
                                 sourceVar,
-                                relDef,
-                                targetVar: connectVar,
-                            });
-                            lines.push(`MERGE ${relPattern}`);
-                        }
-                        lines.push(`RETURN count(*) AS _cn_${key}_${ci}`);
-                        lines.push(`}`);
+                                carryVars: allVars,
+                                withClause,
+                                varPrefix: '',
+                                depth: 0,
+                            },
+                        }));
                     }
                 }
                 // --- create ---
@@ -1431,15 +1578,23 @@ export class MutationCompiler {
                         : [item.create];
                     for (let ci = 0; ci < createItems.length; ci++) {
                         const createSpec = createItems[ci];
-                        const nodeSpec = (createSpec.node ?? createSpec);
+                        let nodeSpec = (createSpec.node ?? createSpec);
+                        // Flat interface input: the create names its implementer.
+                        let createDef = targetNodeDef;
+                        if (abstract) {
+                            const [member, memberSpec] = unwrapAbstractCreateNode(nodeSpec, abstract, key);
+                            createDef = this.schema.nodes.get(member);
+                            nodeSpec = memberSpec;
+                        }
+                        const targetLabelStr = this.getCachedLabelString(createDef);
                         const createVar = `${sourceVar}_cr${varCounter}`;
                         varCounter++;
-                        const { propString, propParams } = this.buildCreateProperties(nodeSpec, targetNodeDef, `${itemPrefix}_create${ci}`);
+                        const { propString, propParams } = this.buildCreateProperties(nodeSpec, createDef, `${itemPrefix}_create${ci}`);
                         // Handle nested relationship creates within the created node
-                        const nestedRelLines = this.buildCreateRelationships(nodeSpec, targetNodeDef, createVar, `${itemPrefix}_create${ci}`, params, allVars, policyContext, paramCounter);
+                        const nestedRelLines = this.buildCreateRelationships(nodeSpec, createDef, createVar, `${itemPrefix}_create${ci}`, params, allVars, policyContext, paramCounter);
                         const propsClause = propString.length > 0
                             ? ` { ${propString} }`
-                            : ` { ${this.buildGeneratedIdClause(targetNodeDef)} }`;
+                            : ` { ${this.buildGeneratedIdClause(createDef)} }`;
                         // `edge` properties on the new relationship — the same input
                         // create() accepts. Pre-2.4.5 this path never read
                         // `createSpec.edge`, so they were silently dropped.
@@ -1488,6 +1643,11 @@ export class MutationCompiler {
                     const nodeUpdate = (updateSpec.node ??
                         (edgeUpdate ? {} : updateSpec));
                     const updateWhere = item.where;
+                    // A flat interface update writes the interface's own fields; the
+                    // per-implementer `_on` form is not supported (v2.4.8).
+                    if (abstract && isPlainObject(nodeUpdate) && '_on' in nodeUpdate)
+                        throw new OGMError(`"_on" in a nested update of "${key}" is not supported. Key the update by implementing type instead ` +
+                            `(e.g. { ${key}: { ${abstract.members[0] ?? 'Member'}: [{ where, update }] } }).`);
                     const updateVar = `${sourceVar}_u${varCounter}`;
                     const relVar = `r_${key}_${i}`;
                     varCounter++;
@@ -1500,6 +1660,7 @@ export class MutationCompiler {
                         if (val === undefined)
                             continue;
                         assertSafePropertyName(prop, 'nested update property');
+                        assertKnownField(targetNodeDef, prop, 'nested update');
                         const nodePropDef = targetNodeDef.properties.get(prop);
                         const paramName = `${itemPrefix}_set_${prop}`;
                         setClauses.push(`${updateVar}.${escapeIdentifier(prop)} = ${wrapWriteExpr(`$${paramName}`, val, nodePropDef)}`);
@@ -1538,6 +1699,7 @@ export class MutationCompiler {
                             targetVar: updateVar,
                             edgeVar: relVar,
                             targetLabel: 'auto',
+                            schema: this.schema,
                         });
                         lines.push(`MATCH ${relArrow}`);
                         // WHERE on the target.
@@ -1720,6 +1882,114 @@ export function connectionWhereToNodeWhere(spec) {
     }
     return parts.length === 1 ? parts[0] : { AND: parts };
 }
+/**
+ * The concrete members of an interface / union relationship target, or
+ * `null` for a node type. Implementer nodes carry their OWN labels, not
+ * the interface's, so every write that has to find one matches by these
+ * members' labels (v2.4.8).
+ */
+export function abstractTarget(target, schema) {
+    if (schema.nodes.has(target))
+        return null;
+    const iface = schema.interfaces?.get(target);
+    if (iface)
+        return {
+            kind: 'interface',
+            name: target,
+            members: iface.implementedBy.filter((m) => schema.nodes.has(m)),
+        };
+    const union = schema.unions?.get(target);
+    if (union)
+        return {
+            kind: 'union',
+            name: target,
+            members: union.filter((m) => schema.nodes.has(m)),
+        };
+    return null;
+}
+/**
+ * Classify the nested-write value of an abstract relationship (v2.4.8):
+ *
+ *   - PER-MEMBER — keyed by member type (`{ Dog: { … } }`), the shape
+ *     codegen emits for union AND interface targets. Returns the defined
+ *     `[member, value]` entries.
+ *   - FLAT — the operation keys themselves (`{ connect, create, … }`, or an
+ *     array of them), the @neo4j/graphql interface shape. Returns `null`.
+ *     Only interfaces accept it: a union has no common fields to filter or
+ *     write, so a flat union input throws.
+ *
+ * Pre-2.4.8 a key that was not a member was skipped, so a flat or typo'd
+ * input on an abstract relationship compiled to no write at all. Mixing
+ * member keys with other keys now throws instead.
+ */
+export function perMemberEntries(value, target, fieldName) {
+    if (Array.isArray(value) || !isPlainObject(value)) {
+        if (target.kind === 'union')
+            throw new OGMError(`Relationship "${fieldName}" targets the union "${target.name}": key its nested input by member type ` +
+                `(${target.members.map((m) => `"${m}"`).join(', ')}).`);
+        return null;
+    }
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+    const memberKeys = keys.filter((k) => target.members.includes(k));
+    if (memberKeys.length === 0 && target.kind === 'interface')
+        return null;
+    if (memberKeys.length !== keys.length) {
+        const other = keys.filter((k) => !target.members.includes(k));
+        throw new OGMError(`Unknown key(s) ${other.map((k) => `"${k}"`).join(', ')} in the nested input of "${fieldName}" ` +
+            `(${target.kind} "${target.name}"). ` +
+            (target.kind === 'union'
+                ? `Key it by member type: ${target.members.map((m) => `"${m}"`).join(', ')}.`
+                : `Use either member keys (${target.members.map((m) => `"${m}"`).join(', ')}) or the operation keys, not both.`));
+    }
+    return memberKeys
+        .filter((k) => value[k] !== null)
+        .map((k) => [k, value[k]]);
+}
+/**
+ * Unwrap a FLAT interface nested-create node spec — `{ Dog: { … } }`,
+ * exactly one implementer key — into the implementer and its own input
+ * (v2.4.8). Anything else throws: without a member key the compiler cannot
+ * know which labels and properties the new node gets.
+ */
+export function unwrapAbstractCreateNode(nodeSpec, target, fieldName) {
+    const keys = isPlainObject(nodeSpec)
+        ? Object.keys(nodeSpec).filter((k) => nodeSpec[k] !== undefined)
+        : [];
+    if (!isPlainObject(nodeSpec) ||
+        keys.length !== 1 ||
+        !target.members.includes(keys[0]) ||
+        !isPlainObject(nodeSpec[keys[0]]))
+        throw new OGMError(`A nested create on "${fieldName}" (${target.kind} "${target.name}") must name exactly one implementing type, ` +
+            `e.g. { node: { ${target.members[0] ?? 'Member'}: { … } } }. Allowed: ${target.members.map((m) => `"${m}"`).join(', ')}.`);
+    return [keys[0], nodeSpec[keys[0]]];
+}
+/**
+ * Reject a write key that is neither a property nor a relationship of the
+ * type (v2.5.0). Pre-2.5.0 only its spelling was checked, so a typo
+ * (`nmae`) was stored as a stray property and the intended field was left
+ * untouched — at every depth (nested creates and updates included).
+ */
+function assertKnownField(nodeDef, key, input) {
+    if (nodeDef.properties.has(key) || nodeDef.relationships.has(key))
+        return;
+    throw new OGMError(`Unknown field "${key}" in the ${input} input of ${nodeDef.typeName}: it is neither a property nor a ` +
+        `relationship of the type. Declare it in the schema, or fix the key.`);
+}
+/**
+ * MERGE writes scalars only. Pre-2.4.8 a relationship field in an upsert's
+ * `create` / `update` was skipped, so its nested connect / create never
+ * ran and nothing said so.
+ */
+function upsertRelationshipError(nodeDef, key, branch) {
+    return new OGMError(`upsert does not support relationship fields: "${key}" in "${branch}" (${nodeDef.typeName}). ` +
+        `Use create() / update() for nested relationship operations.`);
+}
+/** `null` / `{}`: the whole-relationship (blanket) form, never per member. */
+function isBlanketSpec(spec) {
+    if (spec == null)
+        return true;
+    return (isPlainObject(spec) && Object.keys(spec).every((k) => spec[k] === undefined));
+}
 /** A nested delete item's own `delete` asks for a deeper cascade. */
 function hasNestedCascade(value) {
     if (value === undefined || value === null)