grafeo-ogm 2.1.1 → 2.3.0

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

@@ -1,5 +1,5 @@
 import { OGMError } from '../errors';
-import { isReadRestrictive } from '../policy/types';
+import { isReadRestrictive, NO_ROOT_POLICY } from '../policy/types';
 import { buildRelPattern, getTargetLabelString, resolveTargetDef, } from '../schema/utils';
 import { CypherFieldScope } from '../utils/cypher-field-projection';
 import { assertSafeIdentifier, assertSafeKey, assertSafeRegexPattern, escapeIdentifier, isPlainObject, mergeParams, } from '../utils/validation';
@@ -80,46 +80,196 @@ export class WhereCompiler {
             : `[OGM] ${context}.AND has zero effective conditions — no filter emitted (matches everything).`);
     }
     compile(where, nodeVar, nodeDef, paramCounter = { count: 0 }, options) {
+        const split = this.compileUserAndPolicy(where, nodeVar, nodeDef, paramCounter, options);
+        if (!split)
+            return { cypher: '', params: {} };
+        const cypher = split.policy
+            ? stitchUserAndPolicy(split.userCypher, split.policy.clause)
+            : split.userCypher;
+        const result = {
+            cypher,
+            params: split.params,
+        };
+        if (split.preludes)
+            result.preludes = split.preludes;
+        return result;
+    }
+    /**
+     * Explain-path twin of `compile()`, used by `Model.explainPolicies`.
+     * Compiles the user `where` EXACTLY as `compile()` does — same order,
+     * same `paramCounter`, same `@cypher` prelude scope, same policy-aware
+     * relationship traversal — but returns the root policy clause
+     * separately instead of AND-stitching it: as per-policy fragments AND
+     * as the composed string `compile()` would have stitched. Both come
+     * from one compilation, so an explanation cannot drift from
+     * enforcement.
+     *
+     * `policy` is `null` when no root policy clause applies (an override
+     * fired).
+     *
+     * @internal
+     */
+    compileForExplain(where, nodeVar, nodeDef, paramCounter, policyContext) {
+        const split = this.compileUserAndPolicy(where, nodeVar, nodeDef, paramCounter, { policyContext });
+        return {
+            userCypher: split?.userCypher ?? '',
+            params: split?.params ?? {},
+            preludes: split?.preludes ?? [],
+            policy: split?.policy ?? null,
+        };
+    }
+    /**
+     * The policy clause guarding a node of a possibly ABSTRACT type for one
+     * operation (v2.3.0) — the single construction behind every target-
+     * policy consumer (nested selection, traversal filters, nested writes)
+     * and `InterfaceModel`'s root clause:
+     *
+     *   - concrete type → its own composed clause for `op` (byte-identical
+     *     to compiling it directly); `null` when it has no policy for `op`
+     *     or an override fires.
+     *   - interface / union →
+     *       `(CASE WHEN v:M1 THEN <M1 clause> WHEN v:M2 THEN … ELSE false END)`
+     *     over the concrete members, each branch being exactly that member's
+     *     own clause (`resolveForType(M, op)` already folds in M's interface
+     *     policies). A member without a policy for `op`, or whose override
+     *     fires, is `true`; when EVERY member is `true` the result is `null`
+     *     (unconstrained, like a concrete type without policies). `ELSE false`
+     *     excludes a node carrying no known member label (defense in depth).
+     *
+     * Pre-2.3.0 abstract targets resolved the ABSTRACT type's name, so the
+     * implementers' own policies were never applied through relationships.
+     *
+     * `fallbackOp`: resolve it for a type with NO policy for `op` — the
+     * `aggregate` → `read` fallback `Model.aggregate` applies at the root.
+     *
+     * `preludes` (for `@cypher` fields referenced by a policy) are returned
+     * to the caller; nested contexts reject them.
+     *
+     * @internal
+     */
+    compileTargetPolicyClause(typeName, varName, op, policyContext, paramCounter, fallbackOp) {
+        const members = this.abstractMembers(typeName);
+        if (members === null)
+            return this.compileConcreteTargetClause(typeName, varName, op, policyContext, paramCounter, fallbackOp);
+        const params = {};
+        const preludes = [];
+        const branches = [];
+        let constrained = false;
+        for (const member of members) {
+            if (!this.schema.nodes.has(member))
+                continue;
+            const clause = this.compileConcreteTargetClause(member, varName, op, policyContext, paramCounter, fallbackOp);
+            mergeParams(params, clause.params);
+            // Each member compiles in its own `@cypher` scope; chaining two
+            // scopes would drop the first one's aliases at the second's `WITH`.
+            if (preludes.length > 0 && clause.preludes.length > 0)
+                throw new OGMError(`Policies on more than one member of "${typeName}" project @cypher ` +
+                    `fields, which cannot be combined in one query. Refactor all but ` +
+                    `one to stored properties.`);
+            preludes.push(...clause.preludes);
+            if (clause.cypher !== null)
+                constrained = true;
+            branches.push(`WHEN ${varName}:${escapeIdentifier(member)} THEN ${clause.cypher ?? 'true'}`);
+        }
+        if (!constrained)
+            return { cypher: null, params: {}, preludes: [] };
+        return {
+            cypher: `(CASE ${branches.join(' ')} ELSE false END)`,
+            params,
+            preludes,
+        };
+    }
+    compileConcreteTargetClause(typeName, varName, op, policyContext, paramCounter, fallbackOp) {
+        const nodeDef = this.schema.nodes.get(typeName);
+        let resolvedOp = op;
+        let resolved = policyContext.resolveForType(typeName, op);
+        if (!resolved && fallbackOp) {
+            resolvedOp = fallbackOp;
+            resolved = policyContext.resolveForType(typeName, fallbackOp);
+        }
+        if (!nodeDef || !resolved || resolved.overridden)
+            return { cypher: null, params: {}, preludes: [] };
+        const compiled = this.compile(undefined, varName, nodeDef, paramCounter, {
+            policyContext: {
+                ctx: policyContext.ctx,
+                operation: resolvedOp,
+                resolved,
+                resolveForType: policyContext.resolveForType,
+                defaults: policyContext.defaults,
+            },
+        });
+        return {
+            cypher: compiled.cypher || null,
+            params: compiled.params,
+            preludes: compiled.preludes ?? [],
+        };
+    }
+    /** Concrete members of an interface / union; `null` for any other type. */
+    abstractMembers(typeName) {
+        if (this.schema.nodes.has(typeName))
+            return null;
+        const iface = this.schema.interfaces?.get(typeName);
+        if (iface)
+            return [...iface.implementedBy];
+        const union = this.schema.unions?.get(typeName);
+        if (union)
+            return [...union];
+        return null;
+    }
+    /**
+     * Shared body of `compile()` / `compileForExplain()`: compiles the user
+     * where, then the policy fragments, sharing one `paramCounter` and one
+     * top-level `@cypher` scope. Returns `null` when there is nothing to
+     * compile (no user where and no active policy).
+     */
+    compileUserAndPolicy(where, nodeVar, nodeDef, paramCounter, options) {
         const hasUserWhere = where != null && Object.keys(where).length > 0;
         const policyContext = options?.policyContext;
         const policyActive = policyContext !== undefined && !policyContext.resolved.overridden;
         if (!hasUserWhere && !policyActive)
-            return { cypher: '', params: {} };
+            return null;
         // Top-level scope — preludes here are returned to the caller for stitching
         // BEFORE the WHERE clause. Nested scopes (relationship quantifiers) build
         // their own scopes and stitch their preludes into the EXISTS body inline.
-        const scope = new CypherFieldScope(nodeVar, options?.preserveVars ?? [], '__where');
+        const ownsScope = options?.scope === undefined;
+        const scope = options?.scope ??
+            new CypherFieldScope(nodeVar, options?.preserveVars ?? [], '__where');
         const userBody = hasUserWhere
             ? this.compileConditions(where, nodeVar, nodeDef, paramCounter, 0, scope, undefined, policyContext)
             : { cypher: '', params: {} };
-        let cypher = userBody.cypher;
         const params = { ...userBody.params };
+        let policy = null;
         if (policyActive) {
-            const policyClause = this.compilePolicyClause(policyContext, nodeVar, nodeDef, paramCounter, scope, params);
-            cypher = stitchUserAndPolicy(cypher, policyClause);
+            const fragments = this.compilePolicyFragments(policyContext, nodeVar, nodeDef, paramCounter, scope, params);
+            policy = { fragments, clause: composePolicyClause(fragments) };
         }
-        const result = {
-            cypher,
+        return {
+            userCypher: userBody.cypher,
             params,
+            preludes: ownsScope && scope.hasAny() ? scope.emit() : undefined,
+            policy,
         };
-        if (scope.hasAny())
-            result.preludes = scope.emit();
-        return result;
     }
     /**
-     * Compile the policy clause for a single (typeName, op) frame. AND-
-     * stitches into the user's body via `stitchUserAndPolicy`. Shares the
-     * same `paramCounter` and `scope` as the user where so that nothing
-     * collides downstream.
+     * Compile each resolved policy of a single (typeName, op) frame into
+     * its boolean fragments ("parts"), WITHOUT combining them —
+     * `composePolicyClause` does that. Shares the same `paramCounter` and
+     * `scope` as the user where so that nothing collides downstream.
+     *
+     * The result is positionally aligned with `resolved.permissives` /
+     * `resolved.restrictives`: one entry per policy, in order, even when a
+     * policy contributes no part.
      *
      * Permissive `cypher.params` keys are namespaced with `policy_p<n>_`
      * to guarantee no collision with `param0..N`.
      */
-    compilePolicyClause(bundle, nodeVar, nodeDef, paramCounter, scope, paramsTarget) {
-        const { ctx, resolved, defaults, operation } = bundle;
-        const permFrags = [];
+    compilePolicyFragments(bundle, nodeVar, nodeDef, paramCounter, scope, paramsTarget) {
+        const { ctx, resolved } = bundle;
+        const permissives = [];
         let policyParamIdx = 0;
         for (const p of resolved.permissives) {
+            const parts = [];
+            permissives.push({ policy: p, parts });
             // `when` returns a where-partial — compile it through the same
             // pipeline so every existing operator/quantifier just works.
             if (p.when) {
@@ -127,13 +277,13 @@ export class WhereCompiler {
                 if (partial && Object.keys(partial).length > 0) {
                     const compiled = this.compileConditions(partial, nodeVar, nodeDef, paramCounter, 0, scope);
                     if (compiled.cypher) {
-                        permFrags.push(`(${compiled.cypher})`);
+                        parts.push(`(${compiled.cypher})`);
                         mergeParams(paramsTarget, compiled.params);
                     }
                 }
                 else if (partial && Object.keys(partial).length === 0)
                     // Empty partial means "match everything" — equivalent to true.
-                    permFrags.push('true');
+                    parts.push('true');
             }
             // `cypher` escape hatch — raw fragment + parameterized params
             // namespaced with `policy_p<idx>_`.
@@ -145,12 +295,14 @@ export class WhereCompiler {
                     const rawParams = p.cypher.params(ctx) ?? {};
                     const namespaced = namespacePolicyParams(rawParams, `policy_p${policyParamIdx++}_`);
                     mergeParams(paramsTarget, namespaced.values);
-                    permFrags.push(`(${rewritePolicyFragment(fragment, namespaced.map)})`);
+                    parts.push(`(${rewritePolicyFragment(fragment, namespaced.map)})`);
                 }
             }
         }
-        const restFrags = [];
+        const restrictives = [];
         for (const p of resolved.restrictives) {
+            const parts = [];
+            restrictives.push({ policy: p, parts });
             // Only ReadRestrictive policies participate in the WHERE clause.
             // WriteRestrictive policies (create/update) are evaluated at the
             // application layer in Model.* — calling their `(ctx, input)`
@@ -159,7 +311,8 @@ export class WhereCompiler {
                 continue;
             // Compile-time gate. If `appliesWhen(ctx)` is false, the policy
             // contributes nothing to this query — same semantics as a
-            // dropped permissive.
+            // dropped permissive. (The resolver evaluates this gate too; this
+            // check stays as defense in depth for hand-built bundles.)
             if (p.appliesWhen && !p.appliesWhen(ctx))
                 continue;
             if (p.when) {
@@ -168,13 +321,13 @@ export class WhereCompiler {
                 if (partial === false)
                     // Hard deny — compiles to `false` and short-circuits the
                     // restrictive AND chain.
-                    restFrags.push('false');
+                    parts.push('false');
                 else if (partial && typeof partial === 'object') {
                     const obj = partial;
                     if (Object.keys(obj).length > 0) {
                         const compiled = this.compileConditions(obj, nodeVar, nodeDef, paramCounter, 0, scope);
                         if (compiled.cypher) {
-                            restFrags.push(`(${compiled.cypher})`);
+                            parts.push(`(${compiled.cypher})`);
                             mergeParams(paramsTarget, compiled.params);
                         }
                     }
@@ -188,61 +341,11 @@ export class WhereCompiler {
                     const rawParams = p.cypher.params(ctx) ?? {};
                     const namespaced = namespacePolicyParams(rawParams, `policy_p${policyParamIdx++}_`);
                     mergeParams(paramsTarget, namespaced.values);
-                    restFrags.push(`(${rewritePolicyFragment(fragment, namespaced.map)})`);
+                    parts.push(`(${rewritePolicyFragment(fragment, namespaced.map)})`);
                 }
             }
         }
-        // Default-deny: no permissives matched. The Model call site is
-        // responsible for raising `PolicyDeniedError` BEFORE compile when
-        // `defaults.onDeny === 'throw'`. At compile time we always fall
-        // back to `false` so the query is safe even if the call-site
-        // throw is bypassed (defense in depth, not the primary path).
-        if (resolved.permissives.length === 0) {
-            void defaults;
-            void operation;
-            return 'false';
-        }
-        // At least one permissive matched. Compose `(perm) AND (rest)`.
-        //
-        // SECURITY FIX (v1.8.2 — CRITICAL): Pre-1.8.2 emitted `'true'` here
-        // when `permFrags.length === 0`, on the assumption that an empty
-        // permFrags meant "every permissive returned an empty partial,
-        // which is match-anything". That assumption was WRONG and silently
-        // inverted the deny default in three documented patterns:
-        //
-        //   permissive: [{ when: (ctx) => ctx.userId ? {...} : null }]
-        //                                              ^^^ abstain
-        //   permissive: [{ when: (ctx) => undefined }]
-        //   permissive: [{ cypher: { fragment: () => '', params: ... } }]
-        //
-        // In every case, `permFrags` ended up empty and the compiler emitted
-        // `WHERE true`, dumping unrestricted data. The bug survived TS
-        // checks, code review, and the v1.7.0 NLS audit because "abstain"
-        // and "match-anything" looked indistinguishable at this layer.
-        //
-        // Permissives are an ALLOW-LIST. If no rule fires, access is DENIED.
-        // The explicit "match-anything" path is preserved: when a developer
-        // writes `when: () => ({})`, line 257-259 still pushes `'true'` into
-        // permFrags before this check, so permFrags.length > 0 and we take
-        // the else branch. The migration path for users relying on the old
-        // abstain-as-allow behaviour is to write `when: () => ({})` instead
-        // of `when: () => null`.
-        const permClause = permFrags.length === 0
-            ? 'false'
-            : permFrags.length === 1
-                ? permFrags[0]
-                : `(${permFrags.join(' OR ')})`;
-        const restClause = restFrags.length === 0
-            ? 'true'
-            : restFrags.length === 1
-                ? restFrags[0]
-                : restFrags.join(' AND ');
-        // Avoid the trivial `(... AND true)` formulation when there are no
-        // restrictives — keeps emitted Cypher tighter and the byte-
-        // identical regression cleaner.
-        return restClause === 'true'
-            ? permClause
-            : `(${permClause} AND ${restClause})`;
+        return { permissives, restrictives };
     }
     /**
      * Build a `PolicyContextBundle` for a target type when crossing a
@@ -261,9 +364,12 @@ export class WhereCompiler {
     buildTargetBundle(typeName, policyContext) {
         if (!policyContext)
             return undefined;
-        const targetPolicy = policyContext.resolveForType(typeName, 'read');
-        if (!targetPolicy)
-            return undefined;
+        // v2.3.0 — a target WITHOUT a read policy still gets a bundle
+        // (`NO_ROOT_POLICY`: no clause of its own) so enforcement keeps
+        // cascading into deeper traversals. Pre-2.3.0 this returned
+        // `undefined`, making every policy-free type on a traversal path a
+        // gateway around the types beyond it (A → B(no policy) → C skipped C).
+        const targetPolicy = policyContext.resolveForType(typeName, 'read') ?? NO_ROOT_POLICY;
         return {
             ctx: policyContext.ctx,
             operation: 'read',
@@ -272,6 +378,73 @@ export class WhereCompiler {
             defaults: policyContext.defaults,
         };
     }
+    /**
+     * Compile a traversal's filter against its target node with the
+     * caller's filter (`user`) and the target's `read` policy (`policy`)
+     * kept SEPARATE, so each quantifier composes them correctly — the
+     * policy must never sit inside a negation (v2.3.0). Pre-2.3.0 the policy
+     * was compiled INTO the filter, so `_ALL` (`NOT (user AND policy)`) was
+     * falsified by hidden related nodes (an existence oracle), and a
+     * connection `node_NOT` was SATISFIED by them.
+     *
+     *   - no policy context → plain compile.
+     *   - concrete target → one `compileUserAndPolicy` pass (shared `@cypher`
+     *     prelude scope); the bundle cascades as `NO_ROOT_POLICY` at any depth.
+     *   - interface target → filter via a `NO_ROOT_POLICY` traversal bundle,
+     *     policy via `compileTargetPolicyClause` (CASE over the members'
+     *     own clauses — pre-2.3.0 only the interface's own policies ran).
+     *
+     * `''` for an absent part. With `scope`, concrete-target preludes
+     * register into it (caller emits); otherwise they are returned.
+     * Shared with `SelectionCompiler`'s nested-projection filters.
+     *
+     * @internal
+     */
+    compileTargetBody(where, targetVar, targetDef, counter, policyContext, scope) {
+        if (!policyContext) {
+            const plain = this.compile(where, targetVar, targetDef, counter, {
+                scope,
+            });
+            return {
+                user: plain.cypher,
+                policy: '',
+                params: plain.params,
+                preludes: plain.preludes ?? [],
+            };
+        }
+        if (this.abstractMembers(targetDef.typeName) === null) {
+            const split = this.compileUserAndPolicy(where, targetVar, targetDef, counter, {
+                policyContext: this.buildTargetBundle(targetDef.typeName, policyContext),
+                scope,
+            });
+            if (!split)
+                return { user: '', policy: '', params: {}, preludes: [] };
+            return {
+                user: split.userCypher,
+                policy: split.policy?.clause ?? '',
+                params: split.params,
+                preludes: split.preludes ?? [],
+            };
+        }
+        const userPart = this.compile(where, targetVar, targetDef, counter, {
+            policyContext: traversalBundle(policyContext),
+            scope,
+        });
+        const policyPart = this.compileTargetPolicyClause(targetDef.typeName, targetVar, 'read', policyContext, counter);
+        const userHasPreludes = (userPart.preludes?.length ?? 0) > 0 || (scope?.hasAny() ?? false);
+        if (userHasPreludes && policyPart.preludes.length > 0)
+            throw new OGMError(`Filtering "${targetDef.typeName}" by @cypher fields is not supported ` +
+                `when a member type's policy also projects @cypher fields. Filter on ` +
+                `stored properties, or refactor the member policy.`);
+        const params = { ...userPart.params };
+        mergeParams(params, policyPart.params);
+        return {
+            user: userPart.cypher,
+            policy: policyPart.cypher ?? '',
+            params,
+            preludes: [...(userPart.preludes ?? []), ...policyPart.preludes],
+        };
+    }
     compileConditions(where, nodeVar, nodeDef, counter, depth, scope, 
     /**
      * Optional shared params accumulator. When provided, every leaf
@@ -355,37 +528,10 @@ export class WhereCompiler {
                     clauses.push(`NOT (${sub.cypher})`);
                 continue;
             }
-            // Handle null values: relationship null → NOT EXISTS, scalar null → IS NULL
+            // Null values — the operator suffix is split off FIRST (v2.3.0); see
+            // `compileNullCondition`.
             if (value === null) {
-                const relDef = nodeDef.relationships.get(key);
-                if (relDef) {
-                    // Relationship null means "no such relationship exists"
-                    const targetNodeDef = resolveTargetDef(relDef.target, this.schema);
-                    if (targetNodeDef) {
-                        const relVar = `r${counter.count}`;
-                        counter.count++;
-                        const pattern = buildRelPattern({
-                            sourceVar: nodeVar,
-                            relDef,
-                            targetVar: relVar,
-                            targetLabel: 'auto',
-                            // Pass schema so that union/interface targets resolve to a
-                            // labelless target (relationship-type-only filter). Without
-                            // this, the literal abstract type name is escaped as a label
-                            // that no concrete node carries → NOT EXISTS is true for
-                            // every row → ALL rows match.
-                            schema: this.schema,
-                        });
-                        clauses.push(`NOT EXISTS { MATCH ${pattern} }`);
-                    }
-                }
-                else {
-                    // Scalar null means "property IS NULL". `@cypher` scalars need
-                    // to project through the scope first (NULL check on the alias).
-                    assertSafeIdentifier(key, 'where clause');
-                    const fieldRef = this.resolveFieldRef(key, nodeVar, nodeDef, scope);
-                    clauses.push(`${fieldRef} IS NULL`);
-                }
+                clauses.push(this.compileNullCondition(key, nodeVar, nodeDef, counter, scope));
                 continue;
             }
             // Connection operators (e.g. hasStatusConnection_SOME)
@@ -487,16 +633,24 @@ export class WhereCompiler {
             ? (this.schema.relationshipProperties.get(relDef.properties) ?? null)
             : null;
         const inner = this.compileConnectionWhereInput(value, relVar, edgeVar, targetNodeDef, propsDef, nodeScope, edgeScope, counter, depth, policyContext);
-        const innerClauses = inner.cypher ? [inner.cypher] : [];
-        const innerParams = inner.params;
+        const innerParams = { ...inner.params };
+        // v2.3.0 — the target's `'read'` policy, composed ONCE over the whole
+        // connection body (node, node_NOT, edge and logical groups alike) and
+        // kept outside every negation. Compiled after the caller's filter so
+        // parameter numbering matches the pre-2.3.0 single-`node` shape.
+        const target = policyContext
+            ? this.compileTargetBody(undefined, relVar, targetNodeDef, counter, policyContext, nodeScope)
+            : null;
+        const policy = target?.policy ?? '';
+        if (target)
+            mergeParams(innerParams, target.params);
         // Stitch the inner preludes (CALL { ... } + WITH ...) INSIDE the
         // EXISTS body, between the MATCH pattern and the inner WHERE.
-        //   - `nodeScope.emit()` — preludes from `@cypher` fields registered
-        //     directly on the connection-where input's edge-side scope.
+        //   - `nodeScope.emit()` — node-side `@cypher` projections: the
+        //     caller's `node` filters and (concrete target) the target policy.
         //   - `edgeScope.emit()` — same, but edge-side.
-        //   - `inner.preludes` (v1.8.5) — preludes returned by the recursive
-        //     `compile()` calls on the node side, which now own their own
-        //     scopes.
+        //   - `inner.preludes` / `target.preludes` — scopes owned elsewhere
+        //     (an abstract target's member policies).
         const innerPreludes = [];
         if (nodeScope.hasAny())
             innerPreludes.push(...nodeScope.emit());
@@ -504,10 +658,13 @@ export class WhereCompiler {
             innerPreludes.push(...edgeScope.emit());
         if (inner.preludes && inner.preludes.length > 0)
             innerPreludes.push(...inner.preludes);
+        if (target && target.preludes.length > 0)
+            innerPreludes.push(...target.preludes);
         const preludeFragment = innerPreludes.length
             ? ` ${innerPreludes.join(' ')}`
             : '';
-        const whereClause = innerClauses.length > 0 ? ` WHERE ${innerClauses.join(' AND ')}` : '';
+        const matched = stitchUserAndPolicy(inner.cypher, policy);
+        const whereClause = matched ? ` WHERE ${matched}` : '';
         switch (connSuffix) {
             case 'Connection':
             case 'Connection_SOME':
@@ -522,9 +679,9 @@ export class WhereCompiler {
                     params: innerParams,
                 };
             case 'Connection_ALL':
-                if (innerClauses.length > 0)
+                if (inner.cypher)
                     return {
-                        cypher: `NOT EXISTS { MATCH ${pattern}${preludeFragment} WHERE NOT (${innerClauses.join(' AND ')}) }`,
+                        cypher: `NOT EXISTS { MATCH ${pattern}${preludeFragment} WHERE ${stitchAllCounterexample(inner.cypher, policy)} }`,
                         params: innerParams,
                     };
                 return { cypher: '', params: {} };
@@ -570,23 +727,23 @@ export class WhereCompiler {
          * `MATCH ${pattern}` and `WHERE ...` inside the EXISTS body.
          */
         const extraPreludes = [];
-        // Resolve the target type's `'read'` policy ONCE per connection-where
-        // input. The same bundle is reused across every `node` / `node_NOT`
-        // key we encounter at this level (and across nested AND/OR/NOT
-        // groups via direct policyContext threading).
-        const targetBundle = this.buildTargetBundle(targetNodeDef.typeName, policyContext);
         for (const [key, val] of Object.entries(value)) {
             if (val === undefined)
                 continue;
             if (key === 'node' || key === 'node_NOT') {
-                // Re-enter the top-level `compile()` so that the target type's
-                // `'read'` policy AND-stitches into the same body that the user
-                // filter produces. `compile()` manages its own inner scope and
-                // returns any preludes via `WhereResult.preludes`; we hoist
-                // those into `extraPreludes` so the surrounding `tryCompileConnection`
-                // can stitch them inside the EXISTS body alongside the existing
-                // `nodeScope.emit()` content.
-                const nodeResult = this.compile(val, relVar, targetNodeDef, counter, targetBundle ? { policyContext: targetBundle } : undefined);
+                // v2.3.0 — the caller's node filter only. The target's `'read'`
+                // policy is composed ONCE by `tryCompileConnection` over the whole
+                // connection body, never here: stitched in here it sat inside the
+                // `node_NOT` negation (satisfied by hidden nodes) and was absent
+                // from edge-only filters. The traversal bundle keeps deeper
+                // traversals enforcing; `nodeScope` shares the `@cypher` chain
+                // with that policy.
+                const nodeResult = this.compile(val, relVar, targetNodeDef, counter, {
+                    policyContext: policyContext
+                        ? traversalBundle(policyContext)
+                        : undefined,
+                    scope: nodeScope,
+                });
                 if (nodeResult.preludes && nodeResult.preludes.length > 0)
                     extraPreludes.push(...nodeResult.preludes);
                 if (nodeResult.cypher) {
@@ -706,28 +863,22 @@ export class WhereCompiler {
             // EXISTS never matches concrete-typed nodes.
             schema: this.schema,
         });
-        // v1.8.5 — re-resolve the TARGET type's `'read'` policy when crossing
-        // the relationship boundary, mirroring `selection.compiler.ts:826-847`.
-        // Pre-1.8.5 this call site invoked `compileConditions` directly,
-        // skipping policy AND-stitching for the target — CRIT-3.
-        const targetBundle = this.buildTargetBundle(targetNodeDef.typeName, policyContext);
-        // Re-enter the top-level `compile()` so the target's policy clause
-        // (when present) AND-stitches into the same body that the user filter
-        // produces. `compile()` manages its own inner scope and returns any
-        // preludes via `WhereResult.preludes` for stitching inside EXISTS.
-        const innerResult = this.compile(value, relVar, targetNodeDef, counter, targetBundle ? { policyContext: targetBundle } : undefined);
-        const innerPreludes = innerResult.preludes ?? [];
+        // v1.8.5 — the TARGET type's `'read'` policy applies when crossing the
+        // relationship boundary (CRIT-3). v2.3.0 — the caller's filter and the
+        // target's policy compile SEPARATELY and compose per quantifier with
+        // the policy OUTSIDE every negation (see `compileTargetBody`).
+        const body = this.compileTargetBody(value, relVar, targetNodeDef, counter, policyContext);
+        const matched = stitchUserAndPolicy(body.user, body.policy);
+        const innerPreludes = body.preludes;
         const innerPreludeFragment = innerPreludes.length
             ? ` ${innerPreludes.join(' ')}`
             : '';
-        const whereClause = innerResult.cypher
-            ? ` WHERE ${innerResult.cypher}`
-            : '';
+        const whereClause = matched ? ` WHERE ${matched}` : '';
         switch (suffix) {
             case '_SOME':
                 return {
                     cypher: `EXISTS { MATCH ${pattern}${innerPreludeFragment}${whereClause} }`,
-                    params: innerResult.params,
+                    params: body.params,
                 };
             case '_NONE':
             case '_NOT':
@@ -738,14 +889,16 @@ export class WhereCompiler {
                 // Map → NULL → silent wrong rows.
                 return {
                     cypher: `NOT EXISTS { MATCH ${pattern}${innerPreludeFragment}${whereClause} }`,
-                    params: innerResult.params,
+                    params: body.params,
                 };
             case '_ALL':
-                // All matching rels must satisfy: NOT EXISTS { MATCH pattern WHERE NOT (inner) }
-                if (innerResult.cypher)
+                // No VISIBLE related node fails the filter. Without a caller filter
+                // the quantifier is vacuous — hidden nodes must not falsify it
+                // (pre-2.3.0 `_ALL: {}` leaked their existence).
+                if (body.user)
                     return {
-                        cypher: `NOT EXISTS { MATCH ${pattern}${innerPreludeFragment} WHERE NOT (${innerResult.cypher}) }`,
-                        params: innerResult.params,
+                        cypher: `NOT EXISTS { MATCH ${pattern}${innerPreludeFragment} WHERE ${stitchAllCounterexample(body.user, body.policy)} }`,
+                        params: body.params,
                     };
                 return { cypher: '', params: {} };
             case '_SINGLE': {
@@ -755,7 +908,7 @@ export class WhereCompiler {
                 // produces preludes — distinguish that case so the error message
                 // points at the right cause.
                 if (innerPreludes.length > 0) {
-                    if (targetBundle)
+                    if (body.policy)
                         throw new OGMError(`Policy on "${targetNodeDef.typeName}" requires @cypher field projection, ` +
                             `which is not supported inside _SINGLE quantifiers. Refactor the policy ` +
                             `to use stored properties, or refactor the predicate to _SOME + _NONE.`);
@@ -770,7 +923,7 @@ export class WhereCompiler {
                 // collisions if/when a future compiler shared this counter.
                 return {
                     cypher: `size([${relVar} IN [(${pattern}${whereClause} | ${relVar})] | ${relVar}]) = 1`,
-                    params: innerResult.params,
+                    params: body.params,
                 };
             }
             default:
@@ -816,27 +969,27 @@ export class WhereCompiler {
                 targetVar: relVar,
                 targetLabelRaw: labelStr,
             });
-            // Per-member target bundle. `null` member-policy → undefined bundle
-            // → no policy stitching for this branch (original behavior).
-            const targetBundle = this.buildTargetBundle(memberDef.typeName, policyContext);
-            // Compile inner WHERE conditions for this member (if any properties
-            // specified). When the member has its own `'read'` policy, we still
-            // re-enter `compile()` so the policy AND-stitches into the EXISTS
-            // body even when `memberValue` is empty/null.
+            // Caller filter and the member's own `'read'` policy, compiled
+            // separately (v2.3.0) so `_ALL` can keep the policy outside its
+            // negation. `_SOME`/`_NONE`/`_SINGLE` use the stitched form, which
+            // is byte-identical to the pre-2.3.0 single compile.
             const memberWhere = memberValue;
-            const hasUserMemberWhere = memberWhere && Object.keys(memberWhere).length > 0;
-            let inner = '';
-            let preludeFragment = '';
-            if (hasUserMemberWhere || targetBundle) {
-                const memberCompile = this.compile(hasUserMemberWhere ? memberWhere : undefined, relVar, memberDef, counter, targetBundle ? { policyContext: targetBundle } : undefined);
-                if (memberCompile.cypher) {
-                    inner = memberCompile.cypher;
-                    mergeParams(allParams, memberCompile.params);
-                }
-                if (memberCompile.preludes && memberCompile.preludes.length > 0)
-                    preludeFragment = ` ${memberCompile.preludes.join(' ')}`;
-            }
-            members.push({ memberKey, pattern, relVar, inner, preludeFragment });
+            const body = this.compileTargetBody(memberWhere, relVar, memberDef, counter, policyContext);
+            const inner = stitchUserAndPolicy(body.user, body.policy);
+            if (inner)
+                mergeParams(allParams, body.params);
+            const preludeFragment = body.preludes.length
+                ? ` ${body.preludes.join(' ')}`
+                : '';
+            members.push({
+                memberKey,
+                pattern,
+                relVar,
+                inner,
+                user: body.user,
+                policy: body.policy,
+                preludeFragment,
+            });
         }
         if (members.length === 0)
             return { cypher: '', params: {} };
@@ -863,9 +1016,12 @@ export class WhereCompiler {
                 // satisfied (same as the non-union empty-inner short-circuit),
                 // and union members absent from the input are unconstrained —
                 // consistent with `_SOME`, where only mentioned members count.
+                // v2.3.0 — only a VISIBLE member node (its policy holds) can fail
+                // the predicate; a member with no caller filter is vacuous even
+                // when it has a policy (pre-2.3.0 its hidden nodes falsified it).
                 const failClauses = members
-                    .filter((m) => m.inner)
-                    .map((m) => `NOT EXISTS { MATCH ${m.pattern}${m.preludeFragment} WHERE NOT (${m.inner}) }`);
+                    .filter((m) => m.user)
+                    .map((m) => `NOT EXISTS { MATCH ${m.pattern}${m.preludeFragment} WHERE ${stitchAllCounterexample(m.user, m.policy)} }`);
                 if (failClauses.length === 0)
                     return { cypher: '', params: {} };
                 return {
@@ -898,11 +1054,105 @@ export class WhereCompiler {
                 return null;
         }
     }
+    /**
+     * Compile `<key>: null` on a node (v2.3.0). The operator suffix is split
+     * off FIRST: pre-2.3.0 the whole key was treated as a property name, so
+     * the common "is not null" idiom `{ deletedAt_NOT: null }` compiled to
+     * `n.deletedAt_NOT IS NULL` — always true, silently matching every row
+     * (and silently restricting nothing when used in a restrictive policy).
+     *
+     *   field: null          → field IS NULL
+     *   field_NOT: null      → field IS NOT NULL
+     *   rel: null            → NOT EXISTS { MATCH (n)-[:REL]->(…) }
+     *   rel_NOT: null        → EXISTS { MATCH (n)-[:REL]->(…) }
+     *   any other operator   → OGMError (null has no meaning there)
+     *   undeclared field     → OGMError regardless of `strictWhere` — a null
+     *                          filter on an undeclared field matches every
+     *                          row (fail OPEN), unlike a non-null one
+     *
+     * A field literally named `key` always wins over suffix parsing.
+     */
+    compileNullCondition(key, nodeVar, nodeDef, counter, scope) {
+        if (nodeDef.relationships.has(key))
+            return this.compileRelationshipExistence(key, nodeVar, nodeDef, counter, false);
+        if (!nodeDef.properties.has(key))
+            for (const suffix of RELATIONSHIP_SUFFIXES) {
+                if (!key.endsWith(suffix))
+                    continue;
+                const field = key.slice(0, -suffix.length);
+                if (!nodeDef.relationships.has(field))
+                    continue;
+                if (suffix === '_NOT')
+                    return this.compileRelationshipExistence(field, nodeVar, nodeDef, counter, true);
+                throw new OGMError(`Relationship filter "${key}" cannot be null. Use "${field}: null" ` +
+                    `(no related node) or "${field}_NOT: null" (at least one related node).`);
+            }
+        return this.compileNullScalar(key, nodeVar, nodeDef, scope);
+    }
+    /**
+     * Scalar half of the null semantics above, shared by node properties and
+     * relationship-edge properties: `IS NULL` / `IS NOT NULL`, or an
+     * `OGMError` for any other operator and for undeclared fields.
+     */
+    compileNullScalar(key, varName, propsHolder, scope) {
+        if (propsHolder?.properties.has(key)) {
+            assertSafeIdentifier(key, 'where clause');
+            // `@cypher` scalars project through the scope (NULL check on the alias).
+            return `${this.resolveFieldRef(key, varName, propsHolder, scope)} IS NULL`;
+        }
+        for (const suffix of OPERATOR_SUFFIXES) {
+            if (!key.endsWith(suffix))
+                continue;
+            const field = key.slice(0, -suffix.length);
+            if (!propsHolder?.properties.has(field))
+                continue;
+            if (suffix !== '_NOT')
+                throw new OGMError(`Operator "${suffix}" cannot be used with null ("${key}"). Use ` +
+                    `"${field}: null" (IS NULL) or "${field}_NOT: null" (IS NOT NULL) to test for null.`);
+            assertSafeIdentifier(field, 'where clause');
+            return `${this.resolveFieldRef(field, varName, propsHolder, scope)} IS NOT NULL`;
+        }
+        throw new OGMError(`Unknown field "${key}" in where clause with a null value. A null ` +
+            `filter on a field the type does not declare would match every row, ` +
+            `so it is rejected (regardless of strictWhere). Check for typos.`);
+    }
+    /**
+     * `NOT EXISTS` (no related node) / `EXISTS` (at least one) for a
+     * relationship null filter. Byte-identical to the pre-2.3.0 `rel: null`
+     * emission for the `NOT EXISTS` case.
+     */
+    compileRelationshipExistence(field, nodeVar, nodeDef, counter, exists) {
+        const relDef = nodeDef.relationships.get(field);
+        if (!resolveTargetDef(relDef.target, this.schema))
+            throw new OGMError(`Cannot resolve the target type "${relDef.target}" of relationship "${field}".`);
+        const relVar = `r${counter.count}`;
+        counter.count++;
+        const pattern = buildRelPattern({
+            sourceVar: nodeVar,
+            relDef,
+            targetVar: relVar,
+            targetLabel: 'auto',
+            // Pass schema so that union/interface targets resolve to a
+            // labelless target (relationship-type-only filter). Without this,
+            // the literal abstract type name is escaped as a label that no
+            // concrete node carries → NOT EXISTS is true for every row → ALL
+            // rows match.
+            schema: this.schema,
+        });
+        return exists
+            ? `EXISTS { MATCH ${pattern} }`
+            : `NOT EXISTS { MATCH ${pattern} }`;
+    }
     compileEdgeConditions(edgeWhere, edgeVar, propsDef, edgeScope, counter) {
         const clauses = [];
         const params = {};
         for (const [key, value] of Object.entries(edgeWhere)) {
             assertSafeKey(key, 'edge where input');
+            // Same null semantics as node properties (v2.3.0).
+            if (value === null) {
+                clauses.push(this.compileNullScalar(key, edgeVar, propsDef, edgeScope));
+                continue;
+            }
             const result = this.compileScalarCondition(key, value, edgeVar, propsDef, edgeScope, counter);
             clauses.push(result.cypher);
             mergeParams(params, result.params);
@@ -994,13 +1244,109 @@ export class WhereCompiler {
  * fragment. Both come from `compileConditions` so each is already a
  * valid boolean expression. Empty user bodies skip the AND wrap.
  */
-function stitchUserAndPolicy(userBody, policyClause) {
+export function stitchUserAndPolicy(userBody, policyClause) {
     if (!userBody)
         return policyClause;
     if (!policyClause)
         return userBody;
     return `(${userBody}) AND ${policyClause}`;
 }
+/**
+ * `_ALL` body (v2.3.0): a related node the caller may SEE (`policy`) that
+ * fails the caller's filter. The policy sits OUTSIDE the negation, so
+ * hidden related nodes neither satisfy nor falsify the quantifier.
+ */
+function stitchAllCounterexample(userBody, policyClause) {
+    return policyClause
+        ? `${policyClause} AND NOT (${userBody})`
+        : `NOT (${userBody})`;
+}
+/**
+ * The bundle a traversal's USER filter compiles under (v2.3.0): no clause
+ * for the target itself (its policy is composed separately by the caller),
+ * but `resolveForType` stays live so deeper traversals keep enforcing.
+ *
+ * @internal
+ */
+export function traversalBundle(policyContext) {
+    return { ...policyContext, operation: 'read', resolved: NO_ROOT_POLICY };
+}
+/**
+ * Compose compiled policy fragments into the single boolean clause
+ * `(P1 OR P2 …) AND R1 AND R2 …` that `compile()` AND-stitches into the
+ * WHERE. This is the ONLY place that composition happens: `compile()`
+ * stitches its output, and `Model.explainPolicies` projects the very
+ * same string as its enforcement verdict — so the two cannot disagree.
+ */
+function composePolicyClause(fragments) {
+    // Default-deny: no permissives matched. The Model call site is
+    // responsible for raising `PolicyDeniedError` BEFORE compile when
+    // `defaults.onDeny === 'throw'`. At compile time we always fall
+    // back to `false` so the query is safe even if the call-site
+    // throw is bypassed (defense in depth, not the primary path).
+    if (fragments.permissives.length === 0)
+        return 'false';
+    const permFrags = fragments.permissives.flatMap((c) => c.parts);
+    const restFrags = fragments.restrictives.flatMap((c) => c.parts);
+    // At least one permissive matched. Compose `(perm) AND (rest)`.
+    //
+    // SECURITY FIX (v1.8.2 — CRITICAL): Pre-1.8.2 emitted `'true'` here
+    // when `permFrags.length === 0`, on the assumption that an empty
+    // permFrags meant "every permissive returned an empty partial,
+    // which is match-anything". That assumption was WRONG and silently
+    // inverted the deny default in three documented patterns:
+    //
+    //   permissive: [{ when: (ctx) => ctx.userId ? {...} : null }]
+    //                                              ^^^ abstain
+    //   permissive: [{ when: (ctx) => undefined }]
+    //   permissive: [{ cypher: { fragment: () => '', params: ... } }]
+    //
+    // In every case, `permFrags` ended up empty and the compiler emitted
+    // `WHERE true`, dumping unrestricted data. The bug survived TS
+    // checks, code review, and the v1.7.0 NLS audit because "abstain"
+    // and "match-anything" looked indistinguishable at this layer.
+    //
+    // Permissives are an ALLOW-LIST. If no rule fires, access is DENIED.
+    // The explicit "match-anything" path is preserved: when a developer
+    // writes `when: () => ({})`, `compilePolicyFragments` still pushes
+    // `'true'` as that permissive's part, so permFrags.length > 0 and we
+    // take the else branch. The migration path for users relying on the
+    // old abstain-as-allow behaviour is to write `when: () => ({})`
+    // instead of `when: () => null`.
+    const permClause = permFrags.length === 0
+        ? 'false'
+        : permFrags.length === 1
+            ? permFrags[0]
+            : `(${permFrags.join(' OR ')})`;
+    const restClause = restFrags.length === 0
+        ? 'true'
+        : restFrags.length === 1
+            ? restFrags[0]
+            : restFrags.join(' AND ');
+    // Avoid the trivial `(... AND true)` formulation when there are no
+    // restrictives — keeps emitted Cypher tighter and the byte-
+    // identical regression cleaner.
+    return restClause === 'true'
+        ? permClause
+        : `(${permClause} AND ${restClause})`;
+}
+/**
+ * The boolean value ONE compiled policy contributes to
+ * `composePolicyClause`, as a standalone expression (explain path): a
+ * permissive's parts are OR-ed — they join the permissive disjunction —
+ * and a restrictive's parts are AND-ed — they join the restrictive
+ * conjunction. OR/AND are associative in Cypher's three-valued logic,
+ * so grouping per policy preserves the composed clause's truth value.
+ *
+ * Returns `null` when the policy has no parts (it abstained).
+ */
+export function policyValueExpression(kind, parts) {
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return parts[0];
+    return `(${parts.join(kind === 'permissive' ? ' OR ' : ' AND ')})`;
+}
 /**
  * Namespace raw `cypher.params` keys with the given prefix and produce a
  * lookup map old-name → new-name. The fragment text is rewritten with