grafeo-ogm 2.1.1 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## 2.3.0 (2026-09-23) — 🛡️ Security release: NLS enforcement through relationships, nested writes and cascade delete
+
+> **Security release. Upgrade if you use `policies`.** Node-level-security (NLS) enforcement of the **root** type was sound, but enforcement of **other types reached through relationships** had several gaps. Together they let a bound `withContext(ctx)` read, link, update, create and delete nodes that the target type's policies forbid. One of them (cascade delete) deleted unrelated data with no policy involved at all. Every gap was reproduced before the fix and is pinned by a red-first regression test, both in the mock suite and in a new opt-in live-Neo4j suite.
+>
+> **Reads on OGMs without `policies` emit byte-identical Cypher.** Three changes apply to everyone: the cascade-delete fix, strict `null` filters, and nested-write `where` now being compiled by `WhereCompiler` (see *Behavior changes*).
+
+### 🛡️ Types without policies no longer bypass their neighbours' policies (critical)
+
+When the root type of a query had no policies of its own, the policy context was dropped entirely. Every related type's policies were then skipped in nested selection, in relationship filters (`_SOME`/`_NONE`/`_ALL`/`_SINGLE`/`…Connection`), on `connect`/`disconnect`, and in `explainPolicies`. A policy-free type (a tag, a join node) was a gateway around its neighbours. The same happened one level down: a policy-free type in the **middle** of a traversal (`a_SOME: { b_SOME: { c_SOME } }`) switched enforcement off for everything beyond it.
+
+A policy-bound model now always carries its policy context. A type without policies contributes no clause of its own, and every type it reaches still enforces its own. `count`/`aggregate` keep their fallback from `aggregate` to `read` policies.
+
+### 🛡️ Cascade delete honours its `where` and the target's `delete` policy (critical)
+
+`Model.delete({ delete: { rel: [{ where }] } })` ignored the per-relationship `where`: the documented README example deleted **every** related node, including nodes shared with other records, and never checked the target type's policies. Each cascade item now deletes only the related nodes matching its `where` (`{}` still means all), and each cascaded node must pass its own type's `delete` policy. A `delete` nested inside a cascade item (multi-level cascade, previously ignored) and unknown item keys now throw `OGMError` before anything runs.
+
+### 🛡️ Nested writes enforce the target type's policies
+
+A nested write now enforces exactly what the equivalent direct write on the target type would. Before, most nested writes enforced no target-type policy at all:
+
+| Nested operation | Now enforces on the target type |
+|---|---|
+| `connect` / `disconnect`, including `connect` inside `create` (previously unchecked) | `read` |
+| nested `update` | `update` row filter, plus its write restrictives (`WITH CHECK`) on the nested input |
+| nested `create`, in `create` or `update` | `create`: default deny, plus its write restrictives on the nested input |
+| `delete` inside `update` | `delete` row filter |
+
+Write restrictives and create default-deny are checked, at any depth, before the query runs. A rejected nested write throws `PolicyDeniedError` and nothing is written. The mutation compiler's separate `where` builder, which had drifted from `WhereCompiler` (it threaded no policy context into traversals and misparsed `null`), is removed. Nested-write `where` is now compiled by `WhereCompiler`, so traversals inside it enforce the traversed types' `read` policies too.
+
+### 🛡️ Interface and union relationship targets apply each member's policy (critical)
+
+When a relationship pointed at an **interface** or **union**, enforcement looked up the abstract type's name. That name carries only interface-level policies (none for a union), so the concrete members' own policies were never applied through the relationship: not in nested selection, not in relationship filters, not in nested writes. Each related node is now checked against its concrete type's policy: `CASE WHEN n:Chart THEN <Chart policy> WHEN n:Drug THEN <Drug policy> … ELSE false END`. One shared helper builds this clause for every consumer, including `InterfaceModel` (below).
+
+### 🛡️ Relationship filters no longer leak hidden nodes
+
+The target type's policy was compiled **inside** the caller's filter, which is only correct for `_SOME`. Wherever the quantifier negates the filter, hidden nodes leaked into the result:
+
+- `rel_ALL: { … }` was falsified by hidden related nodes.
+- `rel_ALL: {}` held only when no related node existed at all, which revealed whether hidden nodes exist.
+- A connection `node_NOT` filter was satisfied by hidden nodes.
+- An edge-only connection filter (`relConnection: { edge: { … } }`) applied no target policy at all.
+
+The filter and the policy are now composed separately, with the policy outside every negation. Quantifiers range over the related nodes the caller may see: a hidden node neither satisfies nor falsifies them. `_SOME` emits the same Cypher as before.
+
+### 🛡️ `null` filters no longer fail open (high)
+
+`{ field_NOT: null }` compiled to `` n.`field_NOT` IS NULL ``, which is always true, so a restrictive policy such as `{ approvedAt_NOT: null }` matched every row. `null` is now interpreted after the operator suffix is split off:
+
+- `field_NOT: null` → `IS NOT NULL`
+- `rel_NOT: null` → `EXISTS`
+- any other operator with `null`, or an unknown field with `null` (even without `strictWhere`), throws `OGMError`
+
+This applies to every `where`, including policy partials and nested-write `where`.
+
+### 🛡️ `InterfaceModel` branches match each implementer's own model (medium)
+
+An implementer whose `read` permissives were all gated off by `appliesWhen` got `THEN true` in `InterfaceModel`'s per-label `CASE`, while `Model(<Impl>).find` denies it. Each branch is now exactly the clause that the implementer's own model enforces, which also removes the interface predicates that previously appeared twice per branch. `aggregate`/`count` branches now use each implementer's own `aggregate` policies (falling back to `read`), as `Model.aggregate` does. The `onDeny: 'throw'` pre-check no longer throws when an implementer has no policies (it is visible under its own model).
+
+### ⚠️ Behavior changes
+
+- **Cascade delete honours `where`.** If you relied on the old delete-everything behavior while passing a `where`, pass `{}` instead. Multi-level cascade and unknown cascade keys throw.
+- **Nested writes into protected types can now be filtered or denied.** Add the matching policy for that operation on the target type, or perform the write directly on its model.
+- **Relationship filters over protected types** now range over visible related nodes only (`_ALL` in particular).
+- **Strict `null`:** `field_NOT: null` flips from always-true to `IS NOT NULL`; unsupported or unknown `null` filters throw.
+- **Emitted Cypher changes** for: reads that reach protected types through policy-free types; every nested write with a `where` or a protected target (parameters now come from the shared `paramN` counter); `InterfaceModel` reads with policies; and cascade deletes (one `CALL { … }` per item).
+- Two edge cases now throw `OGMError` instead of emitting Cypher that fails at runtime: `@cypher`-projecting policies on more than one member of an interface/union target, and `@cypher` fields in both an abstract target's filter and a member policy.
+
+### 🔧 Internal
+
+- New `NO_ROOT_POLICY` resolution ("bound, but no root clause"). New `src/policy/nested-writes.ts`, where the root and nested create/update checks share one implementation.
+- `WhereCompiler.compileTargetPolicyClause()` (concrete or abstract, optional operation fallback) and `compileTargetBody()` are the single construction behind every target-policy consumer. `compile()` accepts a caller-owned `@cypher` scope.
+- `MutationCompiler.compileCreate` / `compileDelete` gain optional trailing `policyContext` / `paramCounter` parameters. The bulk-connect `UNWIND` fast path is kept for scalar, non-null, non-logical items; everything else compiles through `WhereCompiler`.
+
+### Tests
+
+- Mock red/green tests for every gap (`tests/policy/enforcement-gaps.spec.ts`).
+- A 25-case invariant suite: each `InterfaceModel` branch equals its implementer's own `find`/`aggregate`/`count` clause, in text and parameter values.
+- Against v2.2.0, 56 of these 75 new tests fail. The other 19 are byte-identity guards, positive controls, and invariant cases where the old construction already agreed.
+- An opt-in live-Neo4j suite (`tests/integration/`, skipped unless `NEO4J_URI` is set) asserting database outcomes per gap.
+- The 17-case policy golden suite is unchanged except for the deliberately re-pinned `InterfaceModel` case (deduplicated predicates).
+
+---
+
+## 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

@@ -580,6 +580,8 @@ const book = await Book.findUniqueOrThrow({
 | `_ALL` | Every related node matches | `{ categories_ALL: { name: 'Tech' } }` |
 | `_SINGLE` | Exactly one related node matches | `{ categories_SINGLE: { name: 'Tech' } }` |
 
+With [Node-Level Security](#node-level-security), quantifiers range over the related nodes the caller may **see**: a related node hidden by its type's `read` policy neither satisfies nor falsifies `_SOME`, `_NONE`, `_ALL` or `_SINGLE`.
+
 **Logical operators:**
 
 ```typescript
@@ -599,11 +601,24 @@ await Book.find({
 ```typescript
 // Scalar null check
 await Book.find({ where: { isbn: null } });        // WHERE n.isbn IS NULL
+await Book.find({ where: { isbn_NOT: null } });    // WHERE n.isbn IS NOT NULL
 
 // Relationship existence
 await Book.find({ where: { author: null } });       // NOT EXISTS pattern
+await Book.find({ where: { author_NOT: null } });   // EXISTS pattern
 ```
 
+| Input | Compiles to |
+|---|---|
+| `field: null` | `field IS NULL` |
+| `field_NOT: null` | `field IS NOT NULL` |
+| `relationship: null` | `NOT EXISTS { MATCH … }` |
+| `relationship_NOT: null` | `EXISTS { MATCH … }` |
+| any other operator with `null` (`_IN`, `_GT`, `_CONTAINS`, `_SOME`, …) | throws `OGMError` |
+| an unknown field with `null` | throws `OGMError`, even without `strictWhere` |
+
+The same rules apply everywhere a `where` is accepted: policy `when` partials, nested `select` filters, and nested-write `where`. Before v2.3.0, `{ field_NOT: null }` compiled to the always-true `` n.`field_NOT` IS NULL ``, so a filter such as a policy restrictive `{ approvedAt_NOT: null }` silently matched every row.
+
 **Connection filters (with edge properties):**
 
 ```typescript
@@ -840,6 +855,15 @@ await Book.delete({
 });
 ```
 
+Cascade semantics:
+
+- Each item deletes only the related nodes matching its `where`. An empty item (`{}`) deletes every related node of that relationship.
+- An item may be a single object or an array of items.
+- With [Node-Level Security](#node-level-security), each cascaded node must also pass its own type's `delete` policy. Nodes the policy rejects are kept.
+- A `delete` nested inside a cascade item (multi-level cascade) throws `OGMError`, as do unknown keys in a cascade item.
+
+> **Behavior change in v2.3.0:** before v2.3.0 the per-item `where` was ignored and the cascade deleted **every** related node, including nodes shared with other records. If you relied on that, pass `{}` explicitly.
+
 ### Delete Many
 
 ```typescript
@@ -1269,6 +1293,28 @@ policies: {
 }
 ```
 
+#### Relationships and nested writes
+
+Policies protect a **type**, wherever it is reached from. When a bound model reaches another type through a relationship, that type's own policies apply, whether or not the root type has any.
+
+Reads:
+- **Nested selection**: related nodes are filtered by their type's `read` policy.
+- **Relationship filters** (`_SOME`, `_NONE`, `_ALL`, `_SINGLE`, `…Connection`): these range over the related nodes the caller may see. At any depth, a hidden node neither satisfies nor falsifies the quantifier.
+- **Interface and union targets**: each related node is checked against the policy of its concrete type (`CASE WHEN n:Chart THEN <Chart policy> WHEN n:Drug THEN <Drug policy> … ELSE false END`).
+
+Writes follow one principle: **a nested write enforces exactly what the equivalent direct write on the target type would.**
+
+| Nested operation | Target-type policy applied |
+|---|---|
+| `connect` / `disconnect` (in `create` or `update`) | `read`: only visible nodes can be linked or unlinked |
+| nested `update` | `update` row filter, plus its write restrictives (`WITH CHECK`) on the nested input |
+| nested `create` (in `create` or `update`) | `create`: at least one permissive must apply, plus its write restrictives on the nested input |
+| `delete` inside `update`, cascade `delete` | `delete` row filter |
+
+Write restrictives and create default-deny are checked before the query runs, so a rejected nested write throws `PolicyDeniedError` and nothing is written.
+
+> **A type without policies is open, but not a gateway.** Before v2.3.0, reading or writing through a type with no policies of its own skipped the policies of the types beyond it, and nested writes enforced no target-type policy at all. If a nested write into a protected type now gets filtered or denied, add the matching policy for that operation on the target type, or perform the write directly on its model.
+
 #### Enforcement boundary
 
 > **The OGM enforces policies at the compiler.** Policies do NOT apply to `ogm.$queryRaw`, `ogm.$executeRaw`, or to `@cypher` directive bodies that traverse from a stored field. If you need raw-Cypher enforcement, write the predicate into your raw Cypher manually or layer a Neo4j role/RBAC at the database.
@@ -1302,12 +1348,62 @@ 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.
 - **`upsert`** evaluates create- and update-side policies at the application layer (MERGE has no WHERE). Documented limit; full MERGE-aware enforcement is not yet implemented.
 - **Restrictives are split into read-side and write-side flavors.** A restrictive's `operations` array determines which `when` signature applies. Read-side ops (`read|delete|aggregate|count`) → `when(ctx)` returns a where-partial or boolean. Write-side ops (`create|update`) → `when(ctx, input)` returns a boolean only. Mixed arrays (e.g. `['read', 'create']`) are rejected at construction time — split into two restrictives. Each flavor is invoked exactly once per query (read-side at compile, write-side at the application layer). Use `isReadRestrictive` / `isWriteRestrictive` if you need to inspect a policy at runtime.
-- **InterfaceModel CASE-per-label fallback.** Implementers without a registered policy fall back to interface-level enforcement on their branch. The OGM emits a `logger.warn` at construction time when an interface has policies and one of its implementers does not — silence the warning by registering an explicit policy on each implementer.
+- **InterfaceModel branches.** Each implementer's `CASE` branch is exactly the policy clause that implementer's own model enforces, including the interface-level policies it inherits. An implementer with no policies of its own therefore gets only the interface-level ones. The OGM emits a `logger.warn` at construction time when an interface has policies and one of its implementers does not. Silence it by registering an explicit policy on each implementer.
+- **`edge` filters in nested-write `where`** (connect, disconnect, nested update and delete) are not supported and throw.
+- **`@cypher` fields in the policies of more than one member of an interface or union** cannot be combined in one query and throw. Refactor all but one to stored properties.
 - **No AsyncLocalStorage integration.** Context is supplied via explicit `withContext()` only — create one wrapper per request, discard after.
 
 ### Raw Cypher
@@ -1879,6 +1975,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/mutation.compiler.d.ts

@@ -55,6 +55,34 @@ export declare class MutationCompiler {
      */
     private buildTargetPolicyPredicate;
     private getPolicyWhereCompiler;
+    /**
+     * Compile a nested-write `where` (connect, disconnect, nested update,
+     * nested/cascade delete) against `targetVar` through `WhereCompiler` —
+     * the single where implementation (v2.3.0: the mutation compiler's
+     * parallel builder was removed after repeatedly drifting from it).
+     * Operators, null semantics, abstract relationship targets and —
+     * crucially — traversal-policy enforcement are identical to a direct
+     * `where`: a relationship filter inside it AND-stitches the traversed
+     * type's `read` policy. The target's OWN operation policy is added
+     * separately by `buildTargetPolicyPredicate`, so the root here is bound
+     * as `NO_ROOT_POLICY`.
+     *
+     * Returns `''` for an absent or empty where.
+     */
+    private compileTargetWhere;
+    /**
+     * The bulk-connect UNWIND fast path compiles each where key against the
+     * ROW's own value (`connItem.where.node.<key>`), which `WhereCompiler`
+     * cannot express. It is therefore restricted to the one shape where
+     * that is exact: every item's where is `{ node: { … } }` or bare
+     * properties, holding only declared, stored scalar properties of the
+     * target (registered operators allowed) with NON-NULL values — no
+     * `AND`/`OR`/`NOT`/`node_NOT`, no relationship traversal, no `@cypher`
+     * field. Every predicate it emits is then a scalar comparison against a
+     * concrete row value, so it can only narrow matches, never fail open.
+     * Anything else takes the per-item path through `WhereCompiler`.
+     */
+    private isConnectFastPathEligible;
     /**
      * Surface a logical operator that contributed zero effective conditions.
      * Mirrors WhereCompiler.warnEmptyLogical — fires only on the anomalous
@@ -68,7 +96,20 @@ export declare class MutationCompiler {
      * Generate CREATE Cypher for one or more nodes.
      * Handles scalar properties, nested relationship creates, and connects.
      */
-    compileCreate(inputs: Record<string, unknown>[], nodeDef: NodeDefinition, labels?: string[]): MutationResult;
+    compileCreate(inputs: Record<string, unknown>[], nodeDef: NodeDefinition, labels?: string[], 
+    /**
+     * The caller's `create` bundle (v2.3.0). Its `resolveForType` gates
+     * every connect target in the nested input by the TARGET type's `read`
+     * policy — pre-2.3.0 the create path threaded no policy at all.
+     */
+    policyContext?: PolicyContextBundle, 
+    /**
+     * Shared `param<N>` counter; continue it into the RETURN selection so
+     * nested-filter params never collide with the selection's.
+     */
+    paramCounter?: {
+        count: number;
+    }): MutationResult;
     /**
      * Generate UPDATE Cypher (SET properties + connect/disconnect).
      */
@@ -95,12 +136,45 @@ export declare class MutationCompiler {
     }): MutationResult;
     /**
      * Generate DELETE Cypher with optional cascade.
+     *
+     * v2.3.0 — each cascaded relationship honours its per-item `where` and
+     * is gated by the TARGET type's `delete` policy (`buildNestedDelete`).
+     * Pre-2.3.0 the cascade iterated only the relationship KEYS: the
+     * documented `{ where }` was ignored, so every related node — shared
+     * ones included — was deleted, with no policy check.
      */
     compileDelete(nodeDef: NodeDefinition, whereResult: {
         cypher: string;
         params: Record<string, unknown>;
         preludes?: string[];
-    }, deleteInput?: Record<string, unknown>): MutationResult;
+    }, deleteInput?: Record<string, unknown>, 
+    /** The caller's `delete` bundle; gates each cascade target. */
+    policyContext?: PolicyContextBundle, 
+    /** Shared `param<N>` counter, continued from the root WHERE. */
+    paramCounter?: {
+        count: number;
+    }): MutationResult;
+    /**
+     * Nested / cascade delete of ONE relationship's targets (v2.3.0), shared
+     * by `compileDelete` (`Model.delete`'s `delete` input) and delete-inside-
+     * `update`. One subquery per spec item:
+     *
+     *   <withClause>
+     *   CALL {
+     *     <withClause>
+     *     MATCH (src)-[:REL]->(t)
+     *     WHERE <item.where via WhereCompiler> AND <target `delete` policy>
+     *     DETACH DELETE t
+     *     RETURN count(*) AS _del_<tag>_<i>
+     *   }
+     *
+     * `spec` is one item or an array (singular vs list relationships);
+     * `null` means "no cascade" (GraphQL InputMaybe). `{}` / no `where`
+     * deletes every related node the target's `delete` policy permits.
+     * A multi-level cascade (`delete` inside an item) and unknown item keys
+     * are rejected instead of silently ignored.
+     */
+    private buildNestedDelete;
     /**
      * Generate MERGE (upsert) Cypher with ON CREATE SET / ON MATCH SET.
      * Scalar properties only — nested relationship ops are not supported.
@@ -157,37 +231,26 @@ export declare class MutationCompiler {
      * Returns the base property name and the Cypher expression template.
      */
     private parseOperatorSuffix;
-    /**
-     * Build WHERE conditions for connect/disconnect operations.
-     * Handles operator suffixes (_IN, _NOT, _NOT_IN, _CONTAINS, etc.),
-     * NOT blocks, and relationship filters (_SOME, _NONE, _ALL, _SINGLE).
-     *
-     * @param targetNodeDef - Optional node definition for the target node.
-     *   Required to resolve relationship filters like `configurations_SOME`.
-     *   When omitted, relationship filters are silently skipped.
-     */
-    private buildNodeWhereConditions;
-    /**
-     * Build WHERE conditions from a connection-level WHERE spec.
-     * Handles `node`, `NOT`, `AND`, `OR` at the connection level.
-     *
-     * Connection WHERE format: `{ node: {...}, NOT: { node: {...} }, AND: [...], OR: [...] }`
-     */
-    private buildConnectionWhereConditions;
-    /** Counter for unique relationship filter variables within a single WHERE clause. */
-    private relFilterCounter;
-    /**
-     * Try to compile a relationship filter condition (_SOME, _NONE, _ALL, _SINGLE).
-     * Returns the Cypher expression string or null if the key is not a relationship filter.
-     */
-    private tryBuildRelationshipFilter;
     private buildGeneratedIdClause;
-    /**
-     * Check if any item in an array connect spec has relationship filters in its WHERE clause.
-     * Relationship filters require EXISTS subqueries which can't use UNWIND param references.
-     */
-    private arrayConnectHasRelationshipFilters;
     private extractConnectWhereConditions;
     private extractEdgeProperties;
 }
+/**
+ * Map a nested-mutation connection where onto an equivalent NODE where on
+ * the target, for `WhereCompiler` (v2.3.0). Mutation `where` never supports
+ * edge filters, so the two shapes are interchangeable:
+ *
+ *   { node: A }          → A
+ *   { node_NOT: A }      → { NOT: A }
+ *   { NOT: C }           → { NOT: map(C) }
+ *   { AND: [C…] }        → { AND: [map(C)…] }   (likewise OR; `OR: []`
+ *                                                 still matches nothing)
+ *   bare properties      → themselves (legacy `{ id: 'x' }` shape)
+ *
+ * `edge`/`edge_NOT` throw (unsupported in mutations). In a connection-
+ * shaped where, any other key throws too — the removed parallel builder
+ * silently IGNORED such keys (`{ id: 'x', NOT: {…} }` dropped `id`),
+ * widening the match.
+ */
+export declare function connectionWhereToNodeWhere(spec: Record<string, unknown>): Record<string, unknown>;
 //# sourceMappingURL=mutation.compiler.d.ts.map

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

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