grafeo-ogm 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 2.2.0 (2026-09-23) — 🔎 Explain policy decisions
+
+> **Policy-bound reads can now explain themselves.** When a policy hides a node, `find` could only show *that* it disappeared, never *which* named clause removed it, because every clause is compiled into a single `WHERE` predicate. The new `Model.explainPolicies()` evaluates each `read` policy separately for every candidate node, covering both the declarative `when:` form and the raw `cypher:` form, and returns the hidden nodes too ([#6](https://github.com/neomodular/grafeo-ogm/issues/6)).
+>
+> **Additive minor release.** No existing signature changes, and every existing query emits byte-identical Cypher (pinned by a new 17-case golden suite). The one observable change is a correction to `policiesEvaluated` in the audit metadata (see below).
+
+### ✨ `Model.explainPolicies()`
+
+```typescript
+const report = await ogm
+  .withContext(ctx)
+  .model('Chart')
+  .explainPolicies({ where: { id_IN: candidateIds }, select: { id: true } });
+// → [{ node, visible, overriddenBy, permissiveGranted, failedRestrictives,
+//      policies: [{ name, named, kind, source, applied, outcome }] }]
+```
+
+- **Matches enforcement exactly.** Explain reuses the fragments `find` compiles, and `visible` is computed from the same composed predicate `find` puts in its `WHERE`. The verdict recomputed from the per-policy outcomes is checked against it, and a mismatch throws rather than returning a wrong explanation.
+- **Outcomes:** `pass`, `fail`, `null` (NULL is reported separately from `false`), `abstain` (the policy emitted no predicate), `not-applied` (`appliesWhen` returned false), `skipped` (an override fired).
+- **Candidates** are selected by `where` / `labels` exactly as in `find`. Full `select` / `selectionSet` is supported, and nested relationships are still filtered by their own policies.
+- **Read-only:** when grafeo opens the session itself, it uses `READ` access mode. Candidates default to 100 per call; more than 1,000 is rejected.
+- **An explicit bypass:** every call logs a `warn`, is tagged `explain: true` in the transaction metadata (even with `auditMetadata: false`), and throws on models without a policy binding and on policy-bypassed OGMs. `onDeny: 'throw'` is reported as `visible: false` instead of being thrown.
+- Scope: `Model` and the `read` operation only. `InterfaceModel`, `count`, `aggregate`, and `delete` are not supported yet.
+- New exported types: `PolicyExplanation`, `PolicyClauseExplanation`, `PolicyClauseOutcome`, and `ExecuteOptions`.
+
+### 🐛 `policiesEvaluated` lists only policies that applied
+
+The audit metadata field is documented as "names of policies that fired", but it also listed restrictives whose `appliesWhen(ctx)` returned `false`, even though those contributed nothing to the query. They are no longer listed. Emitted Cypher is unchanged.
+
+To produce this list, the resolver now evaluates restrictive `appliesWhen` itself, and the compiler (or `evaluateWriteRestrictives`) still evaluates it too. As a result, **restrictive `appliesWhen` callbacks run twice per query**. They are documented as pure compile-time gates, so this only matters if yours have side effects (counters, logging).
+
+### 🔧 Internal
+
+- `WhereCompiler`'s policy clause is now built in two steps: `compilePolicyFragments()` (the per-policy parts) and `composePolicyClause()` (the combination). Output is byte-identical to 2.1.1. The new `compileForExplain()` returns the fragments without folding them into the `WHERE`.
+- `PolicyResolver.resolveDetailed()` returns every operation-matching policy with its `applied` / `skipped` state, source, and registration index. `resolve()` is now a projection of it via `projectResolution()`.
+- `Executor.execute()` accepts an optional 4th argument, `{ accessMode }`. It only affects sessions the executor opens itself; calls without it behave as before.
+
+### Tests
+
+- `tests/policy/explain-refactor-golden.spec.ts`: 17 goldens captured from the 2.1.1 compiler, covering every fragment shape, interface inheritance, `@cypher` preludes, traversal, nested selection, count, aggregate, delete, override, and `InterfaceModel`.
+- `tests/policy/explain.spec.ts`: 27 tests covering guards, clause forms, no short-circuiting, applicability, the outcome vocabulary, fidelity with `find` (including a forced mismatch), identity, selection and prelude scoping, and security signalling.
+- 10 new resolver tests, 2 new audit-metadata tests, and `tests/executor-access-mode.spec.ts` (5 tests).
+
 ## 2.1.1 (2026-08-13) — 📍 Point fields round-trip
 
 > **The last member of the 2.1.0 type-faithfulness family.** Reads flatten a native Point into a plain `{ x, y[, z], srid }` object — but writing that object back bound it as a map property value, which Neo4j rejects at runtime ("Property values can only be of primitive types or arrays thereof"). A `Point` read through the OGM could not be written back through the OGM.

package/README.md

@@ -1302,6 +1302,54 @@ When `policies` is configured, every OGM-emitted query attaches transaction meta
 
 Disable via `policyDefaults: { auditMetadata: false }`. The fingerprint is intentionally key-only — no ctx values are leaked.
 
+`policiesEvaluated` lists only the policies that **applied** to the query. A restrictive whose `appliesWhen(ctx)` returned `false` is omitted (before v2.2.0 it was listed even though it contributed nothing). `explainPolicies` calls add `explain: true` and are always recorded, even with `auditMetadata: false`.
+
+#### Explaining policy decisions
+
+When a policy-bound read hides a node, `find` can only show *that* the node disappeared. `explainPolicies` shows *which* named clause decided it. It evaluates every `read` policy for the type separately, for each candidate node, without short-circuiting. Both `when:` and `cypher:` clauses are covered, and nodes the policies reject are returned too.
+
+```typescript
+const report = await ogm
+  .withContext(ctx)
+  .model('Chart')
+  .explainPolicies({ where: { id_IN: candidateIds }, select: { id: true } });
+
+// [{
+//   node: { id: 'chart-8617' },
+//   visible: false,                        // exactly what `find` would enforce
+//   overriddenBy: null,
+//   permissiveGranted: true,
+//   failedRestrictives: ['chart.dose-translation-coverage'],
+//   policies: [
+//     { name: 'chart.read-grant', kind: 'permissive', source: 'Chart', applied: true, outcome: 'pass' },
+//     { name: 'chart.weight-zone', kind: 'restrictive', source: 'Chart', applied: true, outcome: 'pass' },
+//     { name: 'chart.text-field-scope', kind: 'restrictive', source: 'Chart', applied: false, outcome: 'not-applied' },
+//     { name: 'chart.dose-translation-coverage', kind: 'restrictive', source: 'Chart', applied: true, outcome: 'fail' },
+//   ],
+// }]
+```
+
+| `outcome` | Meaning |
+|---|---|
+| `pass` | Applied, and its predicate evaluated to `true`. |
+| `fail` | Applied, and it evaluated to `false`. This includes a restrictive hard deny (`when: () => false`). |
+| `null` | Applied, and it evaluated to NULL (for example, a missing property). Enforcement treats NULL as not-true. It is reported separately from `fail` because the fix is different. |
+| `abstain` | Applied, but it emitted no predicate. A permissive abstain grants nothing; a restrictive abstain restricts nothing. |
+| `not-applied` | `appliesWhen(ctx)` returned `false` (for an override: `when(ctx)` returned `false`). The policy was not evaluated. |
+| `skipped` | Not evaluated, because an earlier override fired. |
+
+How it works:
+
+- **Same predicates as `find`.** The explain query projects the exact compiled fragments `find` would enforce. `visible` is computed from the same composed predicate `find` puts in its `WHERE`. The verdict recomputed from the per-policy outcomes must agree with it; if it ever doesn't, the call throws instead of returning a wrong explanation.
+- **Candidate selection.** `where` and `labels` select candidates exactly as in `find`, including target-type policies on relationship filters. The root type's policy clause is reported, not used as a filter. Candidates that don't match `where` are simply absent from the result.
+- **Selection.** `select` / `selectionSet` accept everything `find` accepts. Relationships in the selection are still filtered by their own target-type policies. Only the root type's policies are explained.
+- **Read-only.** When grafeo opens the session itself, it opens it in `READ` access mode, so the server rejects any write. If you pass your own `transaction` or `session`, it is used as-is, and you control its access mode.
+- **Bounded.** `options.limit` defaults to 100, and values above 1,000 are rejected. Each candidate evaluates every policy, and the enforcement predicate is evaluated a second time for the cross-check, so explain costs more than a normal read. `sort` and `offset` are supported.
+- **Unnamed policies** are reported as `<source>.<kind>[<index>]` with `named: false`. Give every policy a `name` if you want stable, readable output.
+- **Default deny is reported, not thrown.** With `onDeny: 'throw'`, `explainPolicies` still returns rows with `visible: false` and `permissiveGranted: false`.
+
+> **Security: `explainPolicies` bypasses policy filtering by design.** It returns nodes the bound context cannot see, together with their selected fields. Expose it only on admin-only diagnostic paths, and never let request input decide whether it runs. Every call logs a `warn` and is tagged `explain: true` in the transaction metadata. It is only available on policy-bound models (`ogm.withContext(ctx).model(...)`) and throws on a model with no policy binding or on a policy-bypassed OGM. In this release it covers `Model` and the `read` operation only: `InterfaceModel`, `count`, `aggregate`, and `delete` are not supported yet.
+
 #### Limitations
 
 - **`@cypher` scalar fields inside a policy `where`-partial throw when the policy is injected into nested-selection enforcement.** Refactor the policy to use stored properties or a relationship traversal.
@@ -1879,6 +1927,7 @@ Open an issue on [GitHub](https://github.com/neomodular/grafeo-ogm/issues). For
 | `count(options?)` | `number` | Count matching nodes |
 | `aggregate(options)` | `AggregateResult` | Aggregate values (min, max, avg, count) |
 | `setLabels(options)` | `void` | Add or remove labels on matching nodes |
+| `explainPolicies(options?)` | `PolicyExplanation<T>[]` | Per-clause `read` policy outcomes per candidate, including hidden nodes (policy-bound models only; see [Explaining policy decisions](#explaining-policy-decisions)) |
 
 ### InterfaceModel
 

package/dist/cjs/compilers/where.compiler.d.ts

@@ -1,5 +1,5 @@
 import type { OGMLogger } from '../execution/executor';
-import type { PolicyContextBundle } from '../policy/types';
+import type { PermissivePolicy, PolicyContextBundle, RestrictivePolicy } from '../policy/types';
 import { NodeDefinition, SchemaMetadata } from '../schema/types';
 export interface WhereResult {
     cypher: string;
@@ -17,6 +17,43 @@ export interface WhereResult {
      */
     preludes?: string[];
 }
+/**
+ * One resolved policy's compiled contribution to the policy clause.
+ * `parts` are its boolean fragments in emission order (the `when` part,
+ * then the `cypher` part) — exactly what `composePolicyClause` joins.
+ * Empty `parts` → the policy emitted no predicate: it abstained, or (for
+ * restrictives) it is write-side or gated off by `appliesWhen`.
+ */
+export interface CompiledPolicy {
+    readonly policy: PermissivePolicy | RestrictivePolicy;
+    readonly parts: ReadonlyArray<string>;
+}
+/**
+ * Per-policy compilation of one (typeName, op) frame. Positionally
+ * aligned with the bundle's `resolved.permissives` /
+ * `resolved.restrictives` — one entry per policy, in order.
+ */
+export interface CompiledPolicyFragments {
+    readonly permissives: ReadonlyArray<CompiledPolicy>;
+    readonly restrictives: ReadonlyArray<CompiledPolicy>;
+}
+/** Result of `WhereCompiler.compileForExplain` (explain path). */
+export interface ExplainWhereResult {
+    /** User where body only — the candidate filter. `''` when absent. */
+    userCypher: string;
+    /** User-where params followed by policy params (same as `compile()`). */
+    params: Record<string, unknown>;
+    /** Top-level `@cypher` preludes for BOTH the user where and policies. */
+    preludes: string[];
+    /**
+     * Root policy clause, or `null` when none applies (override fired).
+     * `clause` is byte-identical to what `compile()` AND-stitches.
+     */
+    policy: {
+        fragments: CompiledPolicyFragments;
+        clause: string;
+    } | null;
+}
 type OperatorSuffix = string;
 export interface WhereCompilerOptions {
     /** Set of operator suffixes to reject at runtime (e.g. `new Set(['_MATCHES'])`) */
@@ -75,15 +112,44 @@ export declare class WhereCompiler {
         policyContext?: PolicyContextBundle;
     }): WhereResult;
     /**
-     * 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.
+     * 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: Record<string, unknown> | undefined | null, nodeVar: string, nodeDef: NodeDefinition, paramCounter: {
+        count: number;
+    }, policyContext: PolicyContextBundle): ExplainWhereResult;
+    /**
+     * 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).
+     */
+    private compileUserAndPolicy;
+    /**
+     * 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`.
      */
-    private compilePolicyClause;
+    private compilePolicyFragments;
     /**
      * Build a `PolicyContextBundle` for a target type when crossing a
      * node-type boundary inside a relationship traversal (`_SOME` /
@@ -139,5 +205,16 @@ export declare class WhereCompiler {
      */
     private compileScalarCondition;
 }
+/**
+ * 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 declare function policyValueExpression(kind: 'permissive' | 'restrictive', parts: ReadonlyArray<string>): string | null;
 export {};
 //# sourceMappingURL=where.compiler.d.ts.map

package/dist/cjs/compilers/where.compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"where.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/where.compiler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EACL,cAAc,EAGd,cAAc,EACf,MAAM,iBAAiB,CAAC;AAiBzB,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAqDD,KAAK,cAAc,GAAG,MAAM,CAAC;AA4B7B,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IACxC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,MAAM,CAAC,CAAY;gBAGjB,MAAM,EAAE,cAAc,EAC9B,OAAO,CAAC,EAAE,oBAAoB;IAOhC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CACL,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EACjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,YAAY,GAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAiB,EAC9C,OAAO,CAAC,EAAE;QACR;;;;;WAKG;QACH,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QACrC;;;;;;;;;;WAUG;QACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;KACrC,GACA,WAAW;IAoDd;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IA6K3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,iBAAiB;IAsNzB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,oBAAoB;IA0I5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,2BAA2B;IAsKnC,OAAO,CAAC,sBAAsB;IAsK9B;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAyKhC,OAAO,CAAC,qBAAqB;IA8B7B;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;CA0G/B"}
+{"version":3,"file":"where.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/where.compiler.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WhereCompiler = void 0;
+exports.policyValueExpression = policyValueExpression;
 const errors_1 = require("../errors");
 const types_1 = require("../policy/types");
 const utils_1 = require("../schema/utils");
@@ -83,11 +84,56 @@ 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,
+        };
+    }
+    /**
+     * 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.
@@ -95,34 +141,39 @@ class WhereCompiler {
         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: 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) {
@@ -130,13 +181,13 @@ 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})`);
                         (0, validation_1.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>_`.
@@ -148,12 +199,14 @@ class WhereCompiler {
                     const rawParams = p.cypher.params(ctx) ?? {};
                     const namespaced = namespacePolicyParams(rawParams, `policy_p${policyParamIdx++}_`);
                     (0, validation_1.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)`
@@ -162,7 +215,8 @@ 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) {
@@ -171,13 +225,13 @@ 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})`);
                             (0, validation_1.mergeParams)(paramsTarget, compiled.params);
                         }
                     }
@@ -191,61 +245,11 @@ class WhereCompiler {
                     const rawParams = p.cypher.params(ctx) ?? {};
                     const namespaced = namespacePolicyParams(rawParams, `policy_p${policyParamIdx++}_`);
                     (0, validation_1.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
@@ -1005,6 +1009,82 @@ function stitchUserAndPolicy(userBody, policyClause) {
         return userBody;
     return `(${userBody}) AND ${policyClause}`;
 }
+/**
+ * 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).
+ */
+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