grafeo-ogm 2.1.1 → 2.3.0

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

@@ -1,13 +1,10 @@
 import { OGMError } from '../errors';
+import { PolicyDeniedError } from '../policy/errors';
+import { NO_ROOT_POLICY } from '../policy/types';
 import { buildRelPattern, getTargetLabelString, resolveTargetDef, } from '../schema/utils';
-import { assertSafeIdentifier, assertSafeLabel, assertSafePropertyName, escapeIdentifier, mergeParams, } from '../utils/validation';
+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';
-/**
- * Relationship filter suffixes that require EXISTS subquery patterns.
- * These match related nodes via relationship traversal rather than scalar property comparison.
- */
-const RELATIONSHIP_SUFFIXES = ['_SOME', '_NONE', '_ALL', '_SINGLE'];
 /**
  * Compiles create, update, delete, and label mutations into Cypher + params.
  */
@@ -19,8 +16,6 @@ export class MutationCompiler {
          * Bounded by the number of node types in the schema (~50-100 entries).
          */
         this.labelCache = new Map();
-        /** Counter for unique relationship filter variables within a single WHERE clause. */
-        this.relFilterCounter = 0;
         this.logger = options?.logger;
         this.policyWhereCompiler = options?.whereCompiler;
     }
@@ -48,34 +43,126 @@ export class MutationCompiler {
      * `connect_<field>_<prop>`) or the selection's params (allocated later
      * from the same counter).
      */
-    buildTargetPolicyPredicate(targetNodeDef, targetVar, params, policyContext, paramCounter) {
-        if (!policyContext || !paramCounter)
-            return null;
-        const targetPolicy = policyContext.resolveForType(targetNodeDef.typeName, 'read');
-        if (!targetPolicy)
+    buildTargetPolicyPredicate(targetNodeDef, targetVar, params, policyContext, paramCounter, 
+    /**
+     * Operation whose policy gates the target (v2.3.0): `read` for
+     * connect/disconnect (you must see a node to link it), `update` for a
+     * nested update, `delete` for nested/cascade deletes — exactly what the
+     * equivalent DIRECT write on the target type enforces.
+     */
+    op = 'read') {
+        if (!policyContext)
             return null;
-        const targetBundle = {
-            ctx: policyContext.ctx,
-            operation: 'read',
-            resolved: targetPolicy,
-            resolveForType: policyContext.resolveForType,
-            defaults: policyContext.defaults,
-        };
-        const compiled = this.getPolicyWhereCompiler().compile(undefined, targetVar, targetNodeDef, paramCounter, { policyContext: targetBundle });
-        if (compiled.preludes && compiled.preludes.length > 0)
+        // v2.3.0 — a missing counter must never mean a missing policy.
+        const counter = paramCounter ?? counterAfter(params);
+        // Mirror the direct write's compile-time default-deny: a direct
+        // update/delete with `onDeny: 'throw'` and no applicable permissive
+        // throws before running, so the nested equivalent must too. (Connect/
+        // disconnect keep their pre-2.3.0 `read` semantics: compile to false.)
+        if (op !== 'read' && policyContext.defaults.onDeny === 'throw') {
+            const resolved = policyContext.resolveForType(targetNodeDef.typeName, op);
+            if (resolved && !resolved.overridden && resolved.permissives.length === 0)
+                throw new PolicyDeniedError({
+                    typeName: targetNodeDef.typeName,
+                    operation: op,
+                    reason: 'no-permissive-matched',
+                });
+        }
+        // Abstract (interface / union) targets get a CASE over their concrete
+        // members' own clauses — pre-2.3.0 only the abstract type's own
+        // policies (usually none) were applied.
+        const clause = this.getPolicyWhereCompiler().compileTargetPolicyClause(targetNodeDef.typeName, targetVar, op, policyContext, counter);
+        if (clause.preludes.length > 0)
             throw new OGMError(`Policy on "${targetNodeDef.typeName}" requires @cypher field ` +
-                `projection, which is not supported inside connect/disconnect ` +
+                `projection, which is not supported inside nested mutation ` +
                 `target filters. Refactor the policy to use stored properties.`);
-        if (!compiled.cypher)
+        if (!clause.cypher)
             return null;
-        mergeParams(params, compiled.params);
-        return compiled.cypher;
+        mergeParams(params, clause.params);
+        return clause.cypher;
     }
     getPolicyWhereCompiler() {
+        // Inherit the logger: since v2.3.0 this compiler also compiles every
+        // nested-write `where`, and its empty-AND/OR warnings must surface.
         if (!this.policyWhereCompiler)
-            this.policyWhereCompiler = new WhereCompiler(this.schema);
+            this.policyWhereCompiler = new WhereCompiler(this.schema, {
+                logger: this.logger,
+            });
         return this.policyWhereCompiler;
     }
+    /**
+     * Compile a nested-write `where` (connect, disconnect, nested update,
+     * nested/cascade delete) against `targetVar` through `WhereCompiler` —
+     * the single where implementation (v2.3.0: the mutation compiler's
+     * parallel builder was removed after repeatedly drifting from it).
+     * Operators, null semantics, abstract relationship targets and —
+     * crucially — traversal-policy enforcement are identical to a direct
+     * `where`: a relationship filter inside it AND-stitches the traversed
+     * type's `read` policy. The target's OWN operation policy is added
+     * separately by `buildTargetPolicyPredicate`, so the root here is bound
+     * as `NO_ROOT_POLICY`.
+     *
+     * Returns `''` for an absent or empty where.
+     */
+    compileTargetWhere(whereSpec, targetVar, targetNodeDef, params, policyContext, paramCounter) {
+        if (!whereSpec || Object.keys(whereSpec).length === 0)
+            return '';
+        const counter = paramCounter ?? counterAfter(params);
+        const nodeWhere = connectionWhereToNodeWhere(whereSpec);
+        const traversalBundle = policyContext
+            ? { ...policyContext, operation: 'read', resolved: NO_ROOT_POLICY }
+            : undefined;
+        const compiled = this.getPolicyWhereCompiler().compile(nodeWhere, targetVar, targetNodeDef, counter, traversalBundle ? { policyContext: traversalBundle } : undefined);
+        if (compiled.preludes && compiled.preludes.length > 0)
+            throw new OGMError(`Filtering a nested mutation target of type "${targetNodeDef.typeName}" ` +
+                `by an @cypher field is not supported. Use stored properties in ` +
+                `nested connect/disconnect/update/delete filters.`);
+        mergeParams(params, compiled.params);
+        return compiled.cypher;
+    }
+    /**
+     * The bulk-connect UNWIND fast path compiles each where key against the
+     * ROW's own value (`connItem.where.node.<key>`), which `WhereCompiler`
+     * cannot express. It is therefore restricted to the one shape where
+     * that is exact: every item's where is `{ node: { … } }` or bare
+     * properties, holding only declared, stored scalar properties of the
+     * target (registered operators allowed) with NON-NULL values — no
+     * `AND`/`OR`/`NOT`/`node_NOT`, no relationship traversal, no `@cypher`
+     * field. Every predicate it emits is then a scalar comparison against a
+     * concrete row value, so it can only narrow matches, never fail open.
+     * Anything else takes the per-item path through `WhereCompiler`.
+     */
+    isConnectFastPathEligible(items, targetNodeDef) {
+        for (const item of items) {
+            const where = item.where;
+            if (where === undefined)
+                continue;
+            if (!isPlainObject(where))
+                return false;
+            const keys = Object.keys(where).filter((k) => where[k] !== undefined);
+            let nodeWhere;
+            if (keys.some((k) => CONNECTION_WHERE_KEYS.has(k))) {
+                if (keys.length !== 1 || keys[0] !== 'node')
+                    return false;
+                if (!isPlainObject(where.node))
+                    return false;
+                nodeWhere = where.node;
+            }
+            else
+                nodeWhere = where;
+            for (const [key, val] of Object.entries(nodeWhere)) {
+                if (val === undefined || val === null)
+                    return false;
+                if (isPlainObject(val))
+                    return false;
+                const { baseProp } = this.parseOperatorSuffix(key);
+                const propDef = targetNodeDef.properties.get(baseProp);
+                if (!propDef || propDef.isCypher)
+                    return false;
+            }
+        }
+        return true;
+    }
     /**
      * Surface a logical operator that contributed zero effective conditions.
      * Mirrors WhereCompiler.warnEmptyLogical — fires only on the anomalous
@@ -102,8 +189,19 @@ export class MutationCompiler {
      * Generate CREATE Cypher for one or more nodes.
      * Handles scalar properties, nested relationship creates, and connects.
      */
-    compileCreate(inputs, nodeDef, labels) {
-        this.relFilterCounter = 0;
+    compileCreate(inputs, nodeDef, labels, 
+    /**
+     * The caller's `create` bundle (v2.3.0). Its `resolveForType` gates
+     * every connect target in the nested input by the TARGET type's `read`
+     * policy — pre-2.3.0 the create path threaded no policy at all.
+     */
+    policyContext, 
+    /**
+     * Shared `param<N>` counter; continue it into the RETURN selection so
+     * nested-filter params never collide with the selection's.
+     */
+    paramCounter) {
+        const counter = paramCounter ?? { count: 0 };
         const lines = [];
         const params = {};
         const createdVars = [];
@@ -120,10 +218,7 @@ export class MutationCompiler {
             // Pass all previously created node vars as ancestors so WITH clauses
             // don't drop them from scope (needed for RETURN n at the end)
             const relLines = this.buildCreateRelationships(input, nodeDef, nodeVar, prefix, params, createdVars.slice(0, -1), // ancestors = all vars before current
-            // No policy context is threaded on the create path: `create`'s
-            // nested connect enforcement is out of scope for this fix, so
-            // the emitted create Cypher stays byte-identical.
-            undefined, undefined);
+            policyContext, counter);
             lines.push(...relLines);
         }
         // Add extra labels to all created nodes
@@ -153,10 +248,12 @@ export class MutationCompiler {
      * disconnect `where` params or the selection's params.
      */
     paramCounter) {
-        this.relFilterCounter = 0;
         const labelStr = this.getCachedLabelString(nodeDef);
         const lines = [];
         const params = { ...whereResult.params };
+        // Continue after the root WHERE's params when the caller threads no
+        // counter, so nested filters can never collide with them.
+        const counter = paramCounter ?? counterAfter(whereResult.params);
         // Apply runtime labels to MATCH pattern (same as find())
         if (labels && labels.length > 0) {
             const extraLabels = labels.map((l) => assertSafeLabel(l)).join(':');
@@ -189,18 +286,18 @@ export class MutationCompiler {
             if (setClauses.length > 0)
                 lines.push(`SET ${setClauses.join(', ')}`);
             // Process nested relationship operations within update body
-            const relLines = this.buildUpdateRelationships(update, nodeDef, 'n', 'update', params, 0, [], policyContext, paramCounter);
+            const relLines = this.buildUpdateRelationships(update, nodeDef, 'n', 'update', params, 0, [], policyContext, counter);
             lines.push(...relLines);
         }
         // Disconnect relationships (top-level) — must run before connects
         // so that blanket disconnects don't remove newly-connected relationships.
         if (disconnect) {
-            const disconnectLines = this.buildDisconnects(disconnect, nodeDef, params, policyContext, paramCounter);
+            const disconnectLines = this.buildDisconnects(disconnect, nodeDef, params, policyContext, counter);
             lines.push(...disconnectLines);
         }
         // Connect relationships (top-level)
         if (connect) {
-            const connectLines = this.buildConnects(connect, nodeDef, params, policyContext, paramCounter);
+            const connectLines = this.buildConnects(connect, nodeDef, params, policyContext, counter);
             lines.push(...connectLines);
         }
         lines.push(returnMode === 'count' ? 'RETURN count(n) AS count' : 'RETURN n');
@@ -208,40 +305,121 @@ export class MutationCompiler {
     }
     /**
      * Generate DELETE Cypher with optional cascade.
+     *
+     * v2.3.0 — each cascaded relationship honours its per-item `where` and
+     * is gated by the TARGET type's `delete` policy (`buildNestedDelete`).
+     * Pre-2.3.0 the cascade iterated only the relationship KEYS: the
+     * documented `{ where }` was ignored, so every related node — shared
+     * ones included — was deleted, with no policy check.
      */
-    compileDelete(nodeDef, whereResult, deleteInput) {
+    compileDelete(nodeDef, whereResult, deleteInput, 
+    /** The caller's `delete` bundle; gates each cascade target. */
+    policyContext, 
+    /** Shared `param<N>` counter, continued from the root WHERE. */
+    paramCounter) {
         const labelStr = this.getCachedLabelString(nodeDef);
         const lines = [];
         const params = { ...whereResult.params };
+        const counter = paramCounter ?? counterAfter(whereResult.params);
         lines.push(`MATCH (n:${labelStr})`);
         if (whereResult.preludes && whereResult.preludes.length > 0)
             lines.push(...whereResult.preludes);
         if (whereResult.cypher)
             lines.push(`WHERE ${whereResult.cypher}`);
         if (deleteInput && Object.keys(deleteInput).length > 0) {
-            const deleteVars = [];
             let varCounter = 0;
-            for (const [fieldName] of Object.entries(deleteInput)) {
+            for (const [fieldName, spec] of Object.entries(deleteInput)) {
+                if (spec === undefined)
+                    continue;
                 const relDef = nodeDef.relationships.get(fieldName);
                 if (!relDef)
-                    continue;
-                const cascadeVar = `cascade_${varCounter}`;
-                varCounter++;
-                const pattern = buildRelPattern({
-                    sourceVar: 'n',
+                    throw new OGMError(`Unknown relationship "${fieldName}" in the delete input of ${nodeDef.typeName}.`);
+                const targetNodeDef = resolveTargetDef(relDef.target, this.schema);
+                if (!targetNodeDef)
+                    throw new OGMError(`Cannot resolve the target type "${relDef.target}" of relationship "${fieldName}".`);
+                lines.push(...this.buildNestedDelete({
+                    spec,
                     relDef,
-                    targetVar: cascadeVar,
-                    targetLabel: relDef.target,
-                });
-                lines.push(`OPTIONAL MATCH ${pattern}`);
-                deleteVars.push(cascadeVar);
+                    sourceVar: 'n',
+                    withClause: 'WITH n',
+                    targetNodeDef,
+                    nextVar: () => `cascade_${varCounter++}`,
+                    tag: fieldName,
+                    params,
+                    policyContext,
+                    paramCounter: counter,
+                }));
             }
-            lines.push(`DETACH DELETE ${[...deleteVars, 'n'].join(', ')}`);
         }
-        else
-            lines.push('DETACH DELETE n');
+        lines.push('DETACH DELETE n');
         return { cypher: lines.join('\n'), params };
     }
+    /**
+     * Nested / cascade delete of ONE relationship's targets (v2.3.0), shared
+     * by `compileDelete` (`Model.delete`'s `delete` input) and delete-inside-
+     * `update`. One subquery per spec item:
+     *
+     *   <withClause>
+     *   CALL {
+     *     <withClause>
+     *     MATCH (src)-[:REL]->(t)
+     *     WHERE <item.where via WhereCompiler> AND <target `delete` policy>
+     *     DETACH DELETE t
+     *     RETURN count(*) AS _del_<tag>_<i>
+     *   }
+     *
+     * `spec` is one item or an array (singular vs list relationships);
+     * `null` means "no cascade" (GraphQL InputMaybe). `{}` / no `where`
+     * deletes every related node the target's `delete` policy permits.
+     * A multi-level cascade (`delete` inside an item) and unknown item keys
+     * are rejected instead of silently ignored.
+     */
+    buildNestedDelete(args) {
+        const { spec, relDef, sourceVar, withClause, targetNodeDef } = args;
+        if (spec === null || spec === undefined)
+            return [];
+        // Legacy shorthand: `{ rel: true }` = delete every related node (the
+        // pre-2.3.0 cascade ignored values, so callers relied on it). Any other
+        // non-object value — `false` included, which used to delete everything
+        // too — is rejected below rather than silently reinterpreted.
+        const items = spec === true ? [{}] : Array.isArray(spec) ? spec : [spec];
+        const lines = [];
+        items.forEach((item, idx) => {
+            if (!isPlainObject(item))
+                throw new OGMError(`Each nested delete of "${relDef.fieldName}" must be an object ({ where?, delete? }).`);
+            for (const key of Object.keys(item)) {
+                if (item[key] === undefined)
+                    continue;
+                if (key !== 'where' && key !== 'delete')
+                    throw new OGMError(`Unknown key "${key}" in a nested delete of "${relDef.fieldName}". Allowed: "where", "delete".`);
+            }
+            if (hasNestedCascade(item.delete))
+                throw new OGMError(`Multi-level cascade delete is not supported (a "delete" inside the nested delete of "${relDef.fieldName}"). ` +
+                    `Delete the deeper nodes in a separate call.`);
+            const targetVar = args.nextVar();
+            const pattern = buildRelPattern({
+                sourceVar,
+                relDef,
+                targetVar,
+                targetLabel: 'auto',
+                schema: this.schema,
+            });
+            const conditions = [
+                this.compileTargetWhere(item.where, targetVar, targetNodeDef, args.params, args.policyContext, args.paramCounter),
+                this.buildTargetPolicyPredicate(targetNodeDef, targetVar, args.params, args.policyContext, args.paramCounter, 'delete'),
+            ].filter((c) => Boolean(c));
+            lines.push(withClause);
+            lines.push('CALL {');
+            lines.push(withClause);
+            lines.push(`MATCH ${pattern}`);
+            if (conditions.length > 0)
+                lines.push(`WHERE ${conditions.join(' AND ')}`);
+            lines.push(`DETACH DELETE ${targetVar}`);
+            lines.push(`RETURN count(*) AS _del_${args.tag}_${idx}`);
+            lines.push('}');
+        });
+        return lines;
+    }
     /**
      * Generate MERGE (upsert) Cypher with ON CREATE SET / ON MATCH SET.
      * Scalar properties only — nested relationship ops are not supported.
@@ -674,11 +852,10 @@ export class MutationCompiler {
                 const connectVar = `${nodeVar}_cn${startCounter + counter}`;
                 counter++;
                 lines.push(`MATCH (${connectVar}:${targetLabelStr})`);
-                const conditions = this.buildConnectionWhereConditions(whereSpec, connectVar, `${prefix}_conn${ci}`, params, targetNodeDef);
-                const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, connectVar, params, policyContext, paramCounter);
-                const connectConditions = policyPredicate
-                    ? [...conditions, policyPredicate]
-                    : conditions;
+                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) {
@@ -732,13 +909,13 @@ export class MutationCompiler {
             if (Array.isArray(spec)) {
                 if (spec.length === 0)
                     continue; // Empty array — nothing to connect
-                // Check if WHERE contains relationship filters (nested objects referencing
-                // relationships on the target node). UNWIND can't handle EXISTS subqueries
-                // with dynamic params, so we fall back to individual CALL subqueries.
-                const hasRelFilters = this.arrayConnectHasRelationshipFilters(spec, targetNodeDef);
-                if (hasRelFilters)
-                    // Fall back to individual CALL subqueries per item — these use
-                    // buildConnectionWhereConditions which handles relationship filters.
+                // 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;
@@ -748,11 +925,10 @@ export class MutationCompiler {
                         lines.push('WITH n');
                         const connectVar = `target_${fieldName}_${ci}`;
                         lines.push(`MATCH (${connectVar}:${targetLabelStr})`);
-                        const conditions = this.buildConnectionWhereConditions(whereSpec, connectVar, `connect_${fieldName}_${ci}`, params, targetNodeDef);
-                        const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, connectVar, params, policyContext, paramCounter);
-                        const connectConditions = policyPredicate
-                            ? [...conditions, policyPredicate]
-                            : conditions;
+                        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) {
@@ -860,11 +1036,10 @@ export class MutationCompiler {
                 const edgeInput = connectSpec.edge;
                 lines.push('WITH n');
                 lines.push(`MATCH (target:${targetLabelStr})`);
-                const matchConditions = this.buildConnectionWhereConditions(whereSpec, 'target', `connect_${fieldName}`, params, targetNodeDef);
-                const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, 'target', params, policyContext, paramCounter);
-                const singleConnectConditions = policyPredicate
-                    ? [...matchConditions, policyPredicate]
-                    : matchConditions;
+                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) {
@@ -937,13 +1112,12 @@ export class MutationCompiler {
                         targetLabel: 'auto',
                     });
                     lines.push(`OPTIONAL MATCH ${pattern}`);
-                    const conditions = this.buildConnectionWhereConditions(whereSpec, targetVar, `disconnect_${fieldName}_${si}`, params, targetNodeDef);
-                    const policyPredicate = targetNodeDef
-                        ? this.buildTargetPolicyPredicate(targetNodeDef, targetVar, params, policyContext, paramCounter)
-                        : null;
-                    const disconnectConditions = policyPredicate
-                        ? [...conditions, policyPredicate]
-                        : conditions;
+                    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}`);
@@ -1019,47 +1193,21 @@ export class MutationCompiler {
                 const item = items[i];
                 const itemPrefix = `${relPrefix}_${i}`;
                 // --- delete (detach delete target nodes) ---
-                // Wrapped in CALL subquery to prevent OPTIONAL MATCH from multiplying
-                // pipeline rows (N existing nodes → N rows → N subsequent CREATEs).
-                if (item.delete) {
-                    const deleteItems = Array.isArray(item.delete)
-                        ? item.delete
-                        : [item.delete];
-                    for (let di = 0; di < deleteItems.length; di++) {
-                        const deleteSpec = deleteItems[di];
-                        const whereSpec = deleteSpec.where;
-                        const delTarget = `${sourceVar}_del${varCounter}`;
-                        const delRel = `r_del_${key}_${i}_${di}`;
-                        varCounter++;
-                        lines.push(withClause);
-                        lines.push(`CALL {`);
-                        lines.push(withClause);
-                        const pattern = buildRelPattern({
-                            sourceVar,
-                            relDef,
-                            targetVar: delTarget,
-                            edgeVar: delRel,
-                            targetLabel: 'auto',
-                        });
-                        lines.push(`OPTIONAL MATCH ${pattern}`);
-                        if (whereSpec && Object.keys(whereSpec).length > 0) {
-                            const nodeWhere = (whereSpec.node ?? whereSpec);
-                            // Use the same WHERE-condition builder as the disconnect /
-                            // connect paths so operator suffixes (_GT/_CONTAINS/_IN/etc.),
-                            // `NOT`, and relationship sub-filters work consistently. The
-                            // pre-1.7.2 inline implementation only emitted `prop = $param`
-                            // for every key, silently turning operator-suffixed keys
-                            // (`name_CONTAINS`) into property lookups against
-                            // non-existent fields → zero rows deleted.
-                            const conditions = this.buildNodeWhereConditions(nodeWhere, delTarget, `${itemPrefix}_del${di}`, params, targetNodeDef);
-                            if (conditions.length > 0)
-                                lines.push(`WHERE ${conditions.join(' AND ')}`);
-                        }
-                        lines.push(`DETACH DELETE ${delTarget}`);
-                        lines.push(`RETURN count(*) AS _del_${key}_${i}_${di}`);
-                        lines.push(`}`);
-                    }
-                }
+                // Shared with `compileDelete`'s cascade: where + target `delete`
+                // policy, one CALL subquery per spec item (v2.3.0).
+                if (item.delete)
+                    lines.push(...this.buildNestedDelete({
+                        spec: item.delete,
+                        relDef,
+                        sourceVar,
+                        withClause,
+                        targetNodeDef,
+                        nextVar: () => `${sourceVar}_del${varCounter++}`,
+                        tag: `${key}_${i}`,
+                        params,
+                        policyContext,
+                        paramCounter,
+                    }));
                 // --- create ---
                 if (item.create) {
                     const createItems = Array.isArray(item.create)
@@ -1140,11 +1288,10 @@ export class MutationCompiler {
                             // keys are handled identically to the top-level disconnect
                             // path (`buildDisconnects`). Restores backwards-compat with
                             // @neo4j/graphql-ogm's nested update.disconnect[].where shape.
-                            const conditions = this.buildConnectionWhereConditions(whereSpec, discTarget, `${itemPrefix}_disc_${di}`, params, targetNodeDef);
-                            const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, discTarget, params, policyContext, paramCounter);
-                            const nestedDiscConditions = policyPredicate
-                                ? [...conditions, policyPredicate]
-                                : conditions;
+                            const nestedDiscConditions = [
+                                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}`);
@@ -1174,11 +1321,10 @@ export class MutationCompiler {
                         // 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 conditions = this.buildConnectionWhereConditions(whereSpec, connectVar, `${itemPrefix}_conn${ci}`, params, targetNodeDef);
-                        const policyPredicate = this.buildTargetPolicyPredicate(targetNodeDef, connectVar, params, policyContext, paramCounter);
-                        const nestedConnConditions = policyPredicate
-                            ? [...conditions, policyPredicate]
-                            : conditions;
+                        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) {
@@ -1285,11 +1431,15 @@ export class MutationCompiler {
                         // compiler; this was the missed third sibling. The param
                         // prefix is chosen so the legacy plain-equality case keeps
                         // byte-identical param names (`${itemPrefix}_where_${prop}`).
-                        if (updateWhere) {
-                            const conditions = this.buildConnectionWhereConditions(updateWhere, updateVar, `${itemPrefix}_where`, params, targetNodeDef);
-                            if (conditions.length > 0)
-                                lines.push(`WHERE ${conditions.join(' AND ')}`);
-                        }
+                        // v2.3.0 — the nested update is row-filtered by the TARGET's
+                        // `update` policy, exactly like a direct update on that type
+                        // (pre-2.3.0 it enforced no target policy at all).
+                        const updateConditions = [
+                            this.compileTargetWhere(updateWhere, updateVar, targetNodeDef, params, policyContext, paramCounter),
+                            this.buildTargetPolicyPredicate(targetNodeDef, updateVar, params, policyContext, paramCounter, 'update'),
+                        ].filter((c) => Boolean(c));
+                        if (updateConditions.length > 0)
+                            lines.push(`WHERE ${updateConditions.join(' AND ')}`);
                         if (setClauses.length > 0)
                             lines.push(`SET ${setClauses.join(', ')}`);
                         mergeParams(params, setParams);
@@ -1317,180 +1467,6 @@ export class MutationCompiler {
         // No suffix — simple equality
         return { baseProp: key, template: '%v = $%p' };
     }
-    /**
-     * Build WHERE conditions for connect/disconnect operations.
-     * Handles operator suffixes (_IN, _NOT, _NOT_IN, _CONTAINS, etc.),
-     * NOT blocks, and relationship filters (_SOME, _NONE, _ALL, _SINGLE).
-     *
-     * @param targetNodeDef - Optional node definition for the target node.
-     *   Required to resolve relationship filters like `configurations_SOME`.
-     *   When omitted, relationship filters are silently skipped.
-     */
-    buildNodeWhereConditions(nodeWhere, targetVar, prefix, params, targetNodeDef) {
-        const conditions = [];
-        for (const [prop, val] of Object.entries(nodeWhere))
-            if (prop === 'NOT') {
-                const notSpec = val;
-                for (const [notProp, notVal] of Object.entries(notSpec)) {
-                    const { baseProp, template } = this.parseOperatorSuffix(notProp);
-                    assertSafePropertyName(baseProp, 'where property');
-                    const paramName = `${prefix}_NOT_${notProp}`;
-                    const escapedProp = escapeIdentifier(baseProp);
-                    const paramRef = wrapWhereParam(`$${paramName}`, notVal, targetNodeDef?.properties.get(baseProp), notProp.slice(baseProp.length));
-                    let expr;
-                    if (template === '%v = $%p')
-                        // Simple equality → negate to <>
-                        expr = `${targetVar}.${escapedProp} <> ${paramRef}`;
-                    else {
-                        // Operator suffix — wrap with NOT if not already negated
-                        const resolved = template
-                            .replace('%v', `${targetVar}.${escapedProp}`)
-                            .replace('$%p', paramRef);
-                        expr = resolved.startsWith('NOT ') ? resolved : `NOT ${resolved}`;
-                    }
-                    conditions.push(expr);
-                    params[paramName] = notVal;
-                }
-            }
-            else {
-                // Check for relationship filter suffixes (_SOME, _NONE, _ALL, _SINGLE)
-                const relFilter = this.tryBuildRelationshipFilter(prop, val, targetVar, prefix, params, targetNodeDef);
-                if (relFilter) {
-                    conditions.push(relFilter);
-                    continue;
-                }
-                const { baseProp, template } = this.parseOperatorSuffix(prop);
-                assertSafePropertyName(baseProp, 'where property');
-                const paramName = `${prefix}_${prop}`;
-                const paramRef = wrapWhereParam(`$${paramName}`, val, targetNodeDef?.properties.get(baseProp), prop.slice(baseProp.length));
-                conditions.push(template
-                    .replace('%v', `${targetVar}.${escapeIdentifier(baseProp)}`)
-                    .replace('$%p', paramRef));
-                params[paramName] = val;
-            }
-        return conditions;
-    }
-    /**
-     * Build WHERE conditions from a connection-level WHERE spec.
-     * Handles `node`, `NOT`, `AND`, `OR` at the connection level.
-     *
-     * Connection WHERE format: `{ node: {...}, NOT: { node: {...} }, AND: [...], OR: [...] }`
-     */
-    buildConnectionWhereConditions(whereSpec, targetVar, prefix, params, targetNodeDef) {
-        if (!whereSpec || Object.keys(whereSpec).length === 0)
-            return [];
-        const conditions = [];
-        // Direct node conditions
-        if (whereSpec.node) {
-            const nodeConditions = this.buildNodeWhereConditions(whereSpec.node, targetVar, prefix, params, targetNodeDef);
-            conditions.push(...nodeConditions);
-        }
-        // NOT wrapper — negate the inner connection conditions
-        if (whereSpec.NOT) {
-            const notSpec = whereSpec.NOT;
-            const innerConditions = this.buildConnectionWhereConditions(notSpec, targetVar, `${prefix}_NOT`, params, targetNodeDef);
-            if (innerConditions.length > 0)
-                conditions.push(`NOT (${innerConditions.join(' AND ')})`);
-        }
-        // AND — all sub-conditions must hold
-        if (Array.isArray(whereSpec.AND)) {
-            const before = conditions.length;
-            for (let i = 0; i < whereSpec.AND.length; i++) {
-                const sub = this.buildConnectionWhereConditions(whereSpec.AND[i], targetVar, `${prefix}_AND${i}`, params, targetNodeDef);
-                conditions.push(...sub);
-            }
-            if (conditions.length === before)
-                this.warnEmptyLogical('AND', 'mutation connection where');
-        }
-        // OR — any sub-condition must hold
-        if (Array.isArray(whereSpec.OR)) {
-            const orClauses = [];
-            for (let i = 0; i < whereSpec.OR.length; i++) {
-                const sub = this.buildConnectionWhereConditions(whereSpec.OR[i], targetVar, `${prefix}_OR${i}`, params, targetNodeDef);
-                if (sub.length > 0)
-                    orClauses.push(`(${sub.join(' AND ')})`);
-            }
-            if (orClauses.length > 0)
-                conditions.push(`(${orClauses.join(' OR ')})`);
-            // Prisma semantics: OR with zero effective disjuncts matches NOTHING.
-            // Previously the operator vanished, so `disconnect: [{ where:
-            // { OR: [] } }]` detached EVERY related node instead of none.
-            else {
-                this.warnEmptyLogical('OR', 'mutation connection where');
-                conditions.push('false');
-            }
-        }
-        // Fallback: if no recognized keys, treat the whole spec as node conditions
-        // (backward compatibility for simple `{ id: '...' }` style)
-        if (!whereSpec.node && !whereSpec.NOT && !whereSpec.AND && !whereSpec.OR) {
-            // Reject unsupported connection WHERE keys (e.g., "edge")
-            if (whereSpec.edge !== undefined)
-                throw new OGMError(`Connection WHERE with "edge" filters is not supported in mutations. ` +
-                    `Only "node", "NOT", "AND", "OR" keys or direct property conditions are allowed.`);
-            const fallbackConditions = this.buildNodeWhereConditions(whereSpec, targetVar, prefix, params, targetNodeDef);
-            conditions.push(...fallbackConditions);
-        }
-        return conditions;
-    }
-    /**
-     * Try to compile a relationship filter condition (_SOME, _NONE, _ALL, _SINGLE).
-     * Returns the Cypher expression string or null if the key is not a relationship filter.
-     */
-    tryBuildRelationshipFilter(key, value, nodeVar, prefix, params, targetNodeDef) {
-        if (!targetNodeDef || typeof value !== 'object' || value === null)
-            return null;
-        // Detect suffix and extract field name
-        let suffix = null;
-        let fieldName = '';
-        for (const s of RELATIONSHIP_SUFFIXES)
-            if (key.endsWith(s)) {
-                suffix = s;
-                fieldName = key.slice(0, -s.length);
-                break;
-            }
-        // If no suffix, check if bare key is a relationship (defaults to _SOME)
-        if (!suffix) {
-            const relDef = targetNodeDef.relationships.get(key);
-            if (!relDef)
-                return null;
-            suffix = '_SOME';
-            fieldName = key;
-        }
-        const relDef = targetNodeDef.relationships.get(fieldName);
-        if (!relDef)
-            return null;
-        const relTargetDef = resolveTargetDef(relDef.target, this.schema);
-        if (!relTargetDef)
-            return null;
-        const relVar = `rf${this.relFilterCounter++}`;
-        const innerWhere = value;
-        // Build the MATCH pattern
-        const edgePart = `[:${escapeIdentifier(relDef.type)}]`;
-        const escapedTarget = escapeIdentifier(relDef.target);
-        const pattern = relDef.direction === 'IN'
-            ? `(${nodeVar})<-${edgePart}-(${relVar}:${escapedTarget})`
-            : `(${nodeVar})-${edgePart}->(${relVar}:${escapedTarget})`;
-        // Recursively compile inner conditions
-        const innerConditions = this.buildNodeWhereConditions(innerWhere, relVar, `${prefix}_${fieldName}`, params, relTargetDef);
-        const innerClause = innerConditions.length > 0
-            ? ` WHERE ${innerConditions.join(' AND ')}`
-            : '';
-        switch (suffix) {
-            case '_SOME':
-                return `EXISTS { MATCH ${pattern}${innerClause} }`;
-            case '_NONE':
-                return `NOT EXISTS { MATCH ${pattern}${innerClause} }`;
-            case '_ALL':
-                // Double negation: all match ≡ none fail to match
-                if (!innerClause)
-                    return '';
-                return `NOT EXISTS { MATCH ${pattern} WHERE NOT (${innerConditions.join(' AND ')}) }`;
-            case '_SINGLE':
-                return `size([${relVar} IN [(${pattern}${innerClause} | ${relVar})] | ${relVar}]) = 1`;
-            default:
-                return null;
-        }
-    }
     buildGeneratedIdClause(nodeDef) {
         const parts = [];
         for (const [, propDef] of nodeDef.properties)
@@ -1498,38 +1474,6 @@ export class MutationCompiler {
                 parts.push(`${escapeIdentifier(propDef.name)}: randomUUID()`);
         return parts.join(', ');
     }
-    /**
-     * Check if any item in an array connect spec has relationship filters in its WHERE clause.
-     * Relationship filters require EXISTS subqueries which can't use UNWIND param references.
-     */
-    arrayConnectHasRelationshipFilters(items, targetNodeDef) {
-        for (const item of items) {
-            const whereSpec = item.where;
-            if (!whereSpec)
-                continue;
-            const nodeWhere = (whereSpec.node ?? whereSpec);
-            for (const key of Object.keys(nodeWhere)) {
-                // Strip operator suffixes to get the base field name
-                let fieldName = key;
-                for (const s of RELATIONSHIP_SUFFIXES)
-                    if (key.endsWith(s)) {
-                        fieldName = key.slice(0, -s.length);
-                        break;
-                    }
-                // If the base field name is a relationship on the target, it's a rel filter
-                if (targetNodeDef.relationships.has(fieldName))
-                    return true;
-                // Also check if the value is an object (nested filter on a relationship)
-                const val = nodeWhere[key];
-                if (typeof val === 'object' &&
-                    val !== null &&
-                    !Array.isArray(val) &&
-                    targetNodeDef.relationships.has(key))
-                    return true;
-            }
-        }
-        return false;
-    }
     extractConnectWhereConditions(item, targetVar, itemVar, targetNodeDef) {
         const conditions = [];
         const whereSpec = item.where;
@@ -1586,6 +1530,99 @@ MutationCompiler.OPERATOR_SUFFIXES = [
  * path to validate that every item shares the same shape; mismatched
  * shapes silently drop keys from the compiled WHERE / SET.
  */
+/** Keys that make a nested-mutation `where` connection-shaped. */
+const CONNECTION_WHERE_KEYS = new Set([
+    'node',
+    'node_NOT',
+    'NOT',
+    'AND',
+    'OR',
+    'edge',
+    'edge_NOT',
+]);
+/**
+ * Map a nested-mutation connection where onto an equivalent NODE where on
+ * the target, for `WhereCompiler` (v2.3.0). Mutation `where` never supports
+ * edge filters, so the two shapes are interchangeable:
+ *
+ *   { node: A }          → A
+ *   { node_NOT: A }      → { NOT: A }
+ *   { NOT: C }           → { NOT: map(C) }
+ *   { AND: [C…] }        → { AND: [map(C)…] }   (likewise OR; `OR: []`
+ *                                                 still matches nothing)
+ *   bare properties      → themselves (legacy `{ id: 'x' }` shape)
+ *
+ * `edge`/`edge_NOT` throw (unsupported in mutations). In a connection-
+ * shaped where, any other key throws too — the removed parallel builder
+ * silently IGNORED such keys (`{ id: 'x', NOT: {…} }` dropped `id`),
+ * widening the match.
+ */
+export function connectionWhereToNodeWhere(spec) {
+    if (!isPlainObject(spec))
+        throw new OGMError('A nested mutation where must be an object.');
+    const keys = Object.keys(spec).filter((k) => spec[k] !== undefined);
+    const edgeKey = keys.find((k) => k === 'edge' || k === 'edge_NOT');
+    if (edgeKey)
+        throw new OGMError(`Connection WHERE with "${edgeKey}" filters is not supported in mutations. ` +
+            `Only "node", "node_NOT", "NOT", "AND", "OR" keys or direct property conditions are allowed.`);
+    if (!keys.some((k) => CONNECTION_WHERE_KEYS.has(k)))
+        return spec;
+    const parts = [];
+    for (const key of keys) {
+        const value = spec[key];
+        if (value === null)
+            continue;
+        switch (key) {
+            case 'node':
+                parts.push(value);
+                break;
+            case 'node_NOT':
+                parts.push({ NOT: value });
+                break;
+            case 'NOT':
+                parts.push({
+                    NOT: connectionWhereToNodeWhere(value),
+                });
+                break;
+            case 'AND':
+            case 'OR':
+                if (!Array.isArray(value))
+                    throw new OGMError(`"${key}" in a nested mutation where must be an array.`);
+                parts.push({
+                    [key]: value.map((item) => connectionWhereToNodeWhere(item)),
+                });
+                break;
+            default:
+                throw new OGMError(`Unknown key "${key}" in a connection-shaped nested mutation where. ` +
+                    `Allowed: "node", "node_NOT", "NOT", "AND", "OR" — put property ` +
+                    `conditions inside "node".`);
+        }
+    }
+    return parts.length === 1 ? parts[0] : { AND: parts };
+}
+/** A nested delete item's own `delete` asks for a deeper cascade. */
+function hasNestedCascade(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return isPlainObject(value) ? Object.keys(value).length > 0 : true;
+}
+/**
+ * A `param<N>` counter that continues after every `param<N>` already in
+ * `params`, for callers that did not thread their own counter (direct
+ * `MutationCompiler` use): nested-write filters compiled with it can never
+ * collide with the root WHERE's params.
+ */
+function counterAfter(params) {
+    let max = -1;
+    for (const key of Object.keys(params)) {
+        const match = /^param(\d+)$/.exec(key);
+        if (match)
+            max = Math.max(max, Number(match[1]));
+    }
+    return { count: max + 1 };
+}
 function computeConnectItemSignature(item) {
     const where = item.where;
     const nodeWhere = (where?.node ?? where ?? {});