grafeo-ogm 2.1.1 → 2.2.0

package/dist/cjs/policy/resolver.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PolicyResolver = void 0;
+exports.projectResolution = projectResolution;
 exports.hashCtx = hashCtx;
 const crypto_1 = require("crypto");
 /**
@@ -30,68 +31,137 @@ class PolicyResolver {
      * identical Cypher).
      */
     resolve(typeName, op, ctx) {
+        const detailed = this.resolveDetailed(typeName, op, ctx);
+        return detailed ? projectResolution(detailed) : null;
+    }
+    /**
+     * Resolve every operation-matching policy for `(typeName, op, ctx)`
+     * WITHOUT dropping any: `applied` records the `appliesWhen(ctx)` gate
+     * (or, for overrides, `when(ctx)`), and `skipped` marks policies never
+     * evaluated because an earlier override fired. This is the single place
+     * the resolver invokes `appliesWhen`; `resolve()` projects from it.
+     *
+     * Callback invocation order is unchanged from the pre-explain resolver:
+     * override `when` callbacks first (stopping at the first that fires),
+     * then `appliesWhen` in registration order — skipped entirely when an
+     * override fired.
+     *
+     * Returns `null` exactly when `resolve()` does.
+     */
+    resolveDetailed(typeName, op, ctx) {
         const sources = this.gatherSources(typeName);
         if (sources.length === 0)
             return null;
         const matching = [];
-        for (const list of sources)
-            for (const p of list)
-                if (operationMatches(p.operations, op))
-                    matching.push(p);
+        for (const { source, policies } of sources)
+            policies.forEach((policy, index) => {
+                if (operationMatches(policy.operations, op))
+                    matching.push({ policy, source, index });
+            });
         if (matching.length === 0)
             return null;
         // Override short-circuit. First matching override whose `when` returns
-        // true wins — emit nothing.
-        for (const p of matching)
-            if (p.kind === 'override' && p.when(ctx))
-                return {
-                    overridden: true,
-                    permissives: [],
-                    restrictives: [],
-                    evaluated: [p.name ?? 'override'],
-                };
-        const permissives = [];
-        const restrictives = [];
-        const evaluated = [];
-        for (const p of matching)
-            if (p.kind === 'permissive') {
-                // appliesWhen is compile-time. False → drop policy entirely.
-                if (p.appliesWhen && !p.appliesWhen(ctx))
-                    continue;
-                permissives.push(p);
-                evaluated.push(p.name ?? 'permissive');
+        // true wins — nothing after it is evaluated.
+        let firing = -1;
+        for (let i = 0; i < matching.length; i++) {
+            const p = matching[i].policy;
+            if (p.kind === 'override' && p.when(ctx)) {
+                firing = i;
+                break;
             }
-            else if (p.kind === 'restrictive') {
-                restrictives.push(p);
-                evaluated.push(p.name ?? 'restrictive');
+        }
+        const entries = matching.map(({ policy, source, index }, i) => {
+            const named = Boolean(policy.name);
+            const name = named
+                ? policy.name
+                : `${source}.${policy.kind}[${index}]`;
+            const base = { policy, kind: policy.kind, source, index, name, named };
+            if (firing >= 0) {
+                if (i === firing)
+                    return { ...base, applied: true, skipped: false };
+                // Overrides before the firing one WERE evaluated (to false).
+                if (policy.kind === 'override' && i < firing)
+                    return { ...base, applied: false, skipped: false };
+                return { ...base, applied: false, skipped: true };
             }
+            if (policy.kind === 'override')
+                return { ...base, applied: false, skipped: false };
+            const applied = !policy.appliesWhen || policy.appliesWhen(ctx);
+            return { ...base, applied, skipped: false };
+        });
         return {
-            overridden: false,
-            permissives,
-            restrictives,
-            evaluated,
+            overriddenBy: firing >= 0 ? entries[firing].name : null,
+            entries,
         };
     }
     /**
      * Gather all sources of policy that apply to a given concrete type:
-     * the type's own list, plus any interfaces it implements.
+     * the type's own list, plus any interfaces it implements — each tagged
+     * with the registry key that declared it.
      */
     gatherSources(typeName) {
         const out = [];
         const own = this.registry.get(typeName);
         if (own)
-            out.push(own);
+            out.push({ source: typeName, policies: own });
         const nodeDef = this.schema.nodes.get(typeName);
         if (nodeDef)
             for (const ifaceName of nodeDef.implementsInterfaces) {
                 const ifacePolicies = this.registry.get(ifaceName);
                 if (ifacePolicies)
-                    out.push(ifacePolicies);
+                    out.push({ source: ifaceName, policies: ifacePolicies });
             }
         return out;
     }
 }
 exports.PolicyResolver = PolicyResolver;
+/**
+ * Project a detailed resolution onto the `ResolvedPolicies` shape the
+ * compilers consume. `PolicyResolver.resolve()` is exactly
+ * `projectResolution(resolveDetailed(...))`; the explain path calls it on
+ * the SAME detailed object it reports on, so the compiled fragments stay
+ * positionally aligned with the reported entries.
+ */
+function projectResolution(detailed) {
+    if (detailed.overriddenBy !== null) {
+        const firing = detailed.entries.find((e) => e.policy.kind === 'override' && e.applied);
+        return {
+            overridden: true,
+            permissives: [],
+            restrictives: [],
+            evaluated: [firing.policy.name ?? 'override'],
+        };
+    }
+    const permissives = [];
+    const restrictives = [];
+    const evaluated = [];
+    for (const { policy: p, applied } of detailed.entries)
+        if (p.kind === 'permissive') {
+            // appliesWhen is compile-time. False → drop policy entirely.
+            if (!applied)
+                continue;
+            permissives.push(p);
+            evaluated.push(p.name ?? 'permissive');
+        }
+        else if (p.kind === 'restrictive') {
+            // Restrictives are kept even when `appliesWhen(ctx)` is false —
+            // the compiler / `evaluateWriteRestrictives` enforce the gate
+            // downstream. Dropping them here would change what
+            // `InterfaceModel.compileInterfacePolicyClause` sees: an
+            // implementer left with no permissives AND no restrictives is
+            // treated as unconstrained (`THEN true`) instead of default-deny.
+            restrictives.push(p);
+            // Audit metadata lists only policies that actually applied.
+            if (applied)
+                evaluated.push(p.name ?? 'restrictive');
+        }
+    return {
+        overridden: false,
+        permissives,
+        restrictives,
+        evaluated,
+    };
+}
 function operationMatches(operations, op) {
     for (const candidate of operations)
         if (candidate === '*' || candidate === op)

package/dist/cjs/policy/resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/policy/resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/policy/resolver.ts"],"names":[],"mappings":";;;AAgKA,8CA2CC;AAmBD,0BAKC;AAnOD,mCAAoC;AAcpC;;;;;;;GAOG;AACH,MAAa,cAAc;IAIzB,YACE,QAAuD,EACvD,MAAsB;QAEtB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,kFAAkF;IAClF,MAAM;QACJ,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAgB,EAAE,EAAa,EAAE,GAAM;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACzD,OAAO,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,eAAe,CACb,QAAgB,EAChB,EAAa,EACb,GAAM;QAEN,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEtC,MAAM,QAAQ,GAIT,EAAE,CAAC;QACR,KAAK,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,OAAO;YACxC,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;gBACjC,IAAI,gBAAgB,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;oBACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC7C,CAAC,CAAC,CAAC;QAEL,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEvC,uEAAuE;QACvE,6CAA6C;QAC7C,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC;QAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC7B,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,MAAM,GAAG,CAAC,CAAC;gBACX,MAAM;YACR,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAwB,QAAQ,CAAC,GAAG,CAC/C,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE;YAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,KAAK;gBAChB,CAAC,CAAE,MAAM,CAAC,IAAe;gBACzB,CAAC,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,IAAI,IAAI,KAAK,GAAG,CAAC;YACzC,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YAEvE,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC,KAAK,MAAM;oBAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;gBACpE,6DAA6D;gBAC7D,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,GAAG,MAAM;oBAC1C,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;gBACrD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YACpD,CAAC;YAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;gBAC5B,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAErD,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAC/D,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9C,CAAC,CACF,CAAC;QAEF,OAAO;YACL,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YACvD,OAAO;SACR,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,aAAa,CACnB,QAAgB;QAEhB,MAAM,GAAG,GAA6D,EAAE,CAAC;QACzE,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;QAEvD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,OAAO;YACT,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;gBACrD,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACnD,IAAI,aAAa;oBACf,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;YAC7D,CAAC;QAEH,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAjID,wCAiIC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAC/B,QAA+B;IAE/B,IAAI,QAAQ,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,OAAO,CAChD,CAAC;QACH,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,WAAW,EAAE,EAAE;YACf,YAAY,EAAE,EAAE;YAChB,SAAS,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,UAAU,CAAC;SAC9C,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAA0B,EAAE,CAAC;IAC9C,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,QAAQ,CAAC,OAAO;QACnD,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC5B,6DAA6D;YAC7D,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,YAAY,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACpC,gEAAgE;YAChE,8DAA8D;YAC9D,mDAAmD;YACnD,yDAAyD;YACzD,8DAA8D;YAC9D,kEAAkE;YAClE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACrB,4DAA4D;YAC5D,IAAI,OAAO;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,aAAa,CAAC,CAAC;QACvD,CAAC;IAEH,OAAO;QACL,UAAU,EAAE,KAAK;QACjB,WAAW;QACX,YAAY;QACZ,SAAS;KACV,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CACvB,UAA8C,EAC9C,EAAa;IAEb,KAAK,MAAM,SAAS,IAAI,UAAU;QAChC,IAAI,SAAS,KAAK,GAAG,IAAI,SAAS,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;IACzD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,OAAO,CAAC,GAA8B;IACpD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/cjs/policy/types.d.ts

@@ -167,6 +167,93 @@ export interface ResolvedPolicies<C extends PolicyContext = PolicyContext> {
     /** Names of policies that fired (for audit logging). */
     evaluated: ReadonlyArray<string>;
 }
+/**
+ * One operation-matching policy as seen by
+ * `PolicyResolver.resolveDetailed()`. Unlike `ResolvedPolicies`, nothing
+ * is dropped: policies gated off by `appliesWhen` and policies never
+ * evaluated because an override fired are reported too. Consumed by the
+ * explain path (`Model.explainPolicies`).
+ */
+export interface DetailedPolicy<C extends PolicyContext = PolicyContext> {
+    readonly policy: Policy<C>;
+    readonly kind: Policy<C>['kind'];
+    /** Type or interface whose registry entry declared this policy. */
+    readonly source: string;
+    /** Position in `source`'s registration list (all operations counted). */
+    readonly index: number;
+    /** `policy.name`, or `<source>.<kind>[<index>]` when unnamed. */
+    readonly name: string;
+    /** False when `name` is the synthesized fallback identifier. */
+    readonly named: boolean;
+    /**
+     * `appliesWhen(ctx)` held (absent counts as held). For an override:
+     * its `when(ctx)` returned true. Always false when `skipped`.
+     */
+    readonly applied: boolean;
+    /** Not evaluated at all because an earlier override fired. */
+    readonly skipped: boolean;
+}
+/**
+ * Outcome of one policy for one candidate node, as reported by
+ * `Model.explainPolicies()`:
+ *
+ * - `pass` — applied; its predicate evaluated to `true`.
+ * - `fail` — applied; evaluated to `false` (includes a restrictive hard
+ *   deny, `when: () => false`).
+ * - `null` — applied; evaluated to NULL (three-valued logic, e.g. a
+ *   missing property). Enforcement treats it as not-true.
+ * - `abstain` — applied, but emitted no predicate. A permissive abstain
+ *   grants nothing; a restrictive abstain restricts nothing.
+ * - `not-applied` — `appliesWhen(ctx)` was false (override: `when(ctx)`
+ *   was false). Not compiled or evaluated.
+ * - `skipped` — not evaluated because an earlier override fired.
+ */
+export type PolicyClauseOutcome = 'pass' | 'fail' | 'null' | 'abstain' | 'not-applied' | 'skipped';
+/** One policy's report within a `PolicyExplanation`. */
+export interface PolicyClauseExplanation {
+    /** `policy.name`, or `<source>.<kind>[<index>]` when unnamed. */
+    readonly name: string;
+    /** False when `name` is the synthesized fallback identifier. */
+    readonly named: boolean;
+    readonly kind: 'override' | 'permissive' | 'restrictive';
+    /** Type or interface whose registry entry declared the policy. */
+    readonly source: string;
+    /** `appliesWhen(ctx)` held (override: `when(ctx)` was true). */
+    readonly applied: boolean;
+    readonly outcome: PolicyClauseOutcome;
+}
+/**
+ * Per-candidate result of `Model.explainPolicies()`. `visible` is the
+ * exact verdict `find` enforces for the same bound context; the other
+ * fields explain it.
+ */
+export interface PolicyExplanation<T = Record<string, unknown>> {
+    /** The candidate, projected with the requested selection. */
+    readonly node: T;
+    /** Would `find` return this node for the bound context? */
+    readonly visible: boolean;
+    /** Name of the override that fired, else `null`. */
+    readonly overriddenBy: string | null;
+    /**
+     * Some permissive granted access (`true` when an override fired or the
+     * type has no policies). `false` → default deny.
+     */
+    readonly permissiveGranted: boolean;
+    /** Names of applied restrictives whose outcome is `fail` or `null`. */
+    readonly failedRestrictives: ReadonlyArray<string>;
+    /** Every `read` policy for the type, in registration order. */
+    readonly policies: ReadonlyArray<PolicyClauseExplanation>;
+}
+/**
+ * Full resolution for one (typeName, operation, ctx) triple. Entries are
+ * in registration order — the type's own policies first, then each
+ * implemented interface's.
+ */
+export interface DetailedResolution<C extends PolicyContext = PolicyContext> {
+    /** Fallback-aware name of the override that fired, else `null`. */
+    readonly overriddenBy: string | null;
+    readonly entries: ReadonlyArray<DetailedPolicy<C>>;
+}
 /**
  * Carries policy state through one compile pass. Created per query in
  * `Model` / `InterfaceModel` and threaded into `WhereCompiler` /

package/dist/cjs/policy/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/policy/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/policy/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/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/esm/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":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AACzB,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;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACpD,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACtD;AAED,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,MAAM,EAAE;QAAE,SAAS,EAAE,uBAAuB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACvE;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;IAqBd;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EACjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,EAC/B,aAAa,EAAE,mBAAmB,GACjC,kBAAkB;IAgBrB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAqE5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,sBAAsB;IAyH9B;;;;;;;;;;;;;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;AA8ED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,GAAG,aAAa,EAClC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAC3B,MAAM,GAAG,IAAI,CAIf"}