grafeo-ogm 1.6.0 → 1.7.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [1.7.0-beta.2] (2026-05-02)
+
+> **BETA — type-safety hardening.** Install with `npm install grafeo-ogm@beta`. No runtime behavior changes.
+
+### Changed
+
+- **`ModelInterface` and `Model` gain a 12th generic `TFulltext`**, defaulting to the loose `FulltextInput`. The generated type file now passes `<Node>FulltextInput` as that generic for every node with a fulltext index (direct or via a relationship-properties type). The previous `Omit<..., 'find' | ...> & { find(...) }` override pattern is gone — typed fulltext flows through `find`, `findFirst`, `findFirstOrThrow`, `count`, and `aggregate` purely via generic substitution. Same mechanism `<Node>Sort` already used.
+- **Result: typos in fulltext index names are now compile errors at every nesting level**, including inside `OR` / `AND` / `NOT` logical compositions. The recursive `<Node>FulltextInput` shape closes over the per-node leaf, so `{ OR: [{ TpoIndex: { phrase: '...' } }] }` fails type-checking against `<Node>FulltextInput[]`.
+- Public API surface: no breaking changes. The new `TFulltext` parameter has a default, so existing `Model<...>` consumers without the generated `<ModelMap>` see the same loose `FulltextInput` they always did. Generated types narrow it automatically.
+
+## [1.7.0-beta.1] (2026-05-02)
+
+> **BETA — republish of beta.0 with no code changes.** Install with `npm install grafeo-ogm@beta`.
+
+### Fixed
+
+- **CI publish workflow** now passes `--tag` to `npm publish`, derived from the version's pre-release suffix (`beta`, `alpha`, `rc`, etc.), defaulting to `latest` for stable releases. Required because npm refuses to publish prerelease versions without an explicit dist-tag. v1.7.0-beta.0 was tagged on GitHub but never reached npm because of this; v1.7.0-beta.1 is the first beta artifact actually available on the registry.
+
+## [1.7.0-beta.0] (2026-05-02)
+
+> **BETA — API may change before 1.7.0 final.** Install with `npm install grafeo-ogm@beta` (after the package is published to the `beta` dist-tag). The shape of the public API is settled, but feedback during the beta window may cause minor adjustments.
+
+### Features
+
+- **Node-Level Security (NLS).** New optional `policies` config on `OGMConfig` plus `OGM.withContext(ctx)` give you a Postgres-RLS-style filter layer that compiles into the existing WHERE pipeline. Policies return `<Node>Where` partials — every operator, quantifier, connection filter, and nested traversal already supported by `WhereCompiler` is automatically available. Three policy kinds: `override` (compile-time short-circuit; admin path is byte-identical to no-policy), `permissive` (OR'd grants with optional `appliesWhen` compile-time gate), `restrictive` (split into read-side and write-side flavors — see "Contract change" below). Vocabulary-neutral — no hardcoded role strings, you compose your own.
+- **Nested-selection enforcement.** `SelectionCompiler` injects every target type's `'read'` policy into pattern comprehensions, connection edges, and union branches. Policies cannot be bypassed by traversal.
+- **Default-deny baseline.** `policyDefaults.onDeny: 'empty'` (default) emits `WHERE false` when no permissive matches; `'throw'` raises `PolicyDeniedError` before the query runs.
+- **Audit metadata.** Every OGM-emitted query when policies are configured attaches `tx.setMetaData({ ogmPolicySetVersion, ctxFingerprint, modelType, operation, policiesEvaluated, bypassed })`. `ctxFingerprint` is a SHA-256 of the SORTED ctx KEYS only — never values, never anything sensitive.
+- **Escape hatches.** `ogm.unsafe.bypassPolicies()` returns a non-policy-aware OGM (logged via `logger.warn`); per-method `unsafe: { bypassPolicies: true }` skips policies for a single call (also logged).
+- **Interface-aware enforcement.** `InterfaceModel.find()` / `aggregate()` emit a CASE-per-label WHERE that AND-combines each implementer's `'read'` policy with the interface-level policy. Concrete-type policies are NOT bypassed when querying through the interface.
+- **`PolicyDeniedError`** — new public error class extending `OGMError`. Carries `typeName`, `operation`, `reason` (`'no-permissive-matched' | 'restrictive-rejected-input' | 'override-failed-validation'`), and optional `policyName`.
+
+### Contract change during beta — read/write restrictive split
+
+The pre-fix beta invoked `RestrictivePolicy.when` twice on every write path: once at the application layer with `(ctx, input)` (WITH CHECK semantics) and once at WHERE-compile with `(ctx)` only (row predicate). Side-effecting callbacks fired inconsistently and any predicate that legitimately depended on `input` returned `false` at compile time → `WHERE false` → reads silently blocked.
+
+**Fix:** `RestrictivePolicy` is now a discriminated union over `operations`.
+
+- **`ReadRestrictivePolicy`** — `operations` includes only `read|delete|aggregate|count`. `when(ctx)` returns a `<Node>Where` partial OR `false`. Compiles into the WHERE clause via `WhereCompiler`. Invoked exactly once per read-side query.
+- **`WriteRestrictivePolicy`** — `operations` includes only `create|update`. `when(ctx, input)` returns a boolean (where-partial returns are no longer accepted; if you need a row filter on `update`, register a `ReadRestrictive` on `read`/`delete`). Runs at the application layer ("WITH CHECK"). Invoked exactly once per write op. The `cypher` escape hatch is not supported on write restrictives.
+- **Mixed-operation arrays are rejected** at construction time with `OGMError`. Split a single `restrictive({ operations: ['read', 'create'], … })` into two restrictives — one per kind.
+
+The `restrictive()` constructor uses TypeScript overloads so authoring code gets the correct `when` signature inferred from the literal `operations` tuple. New runtime helpers `isReadRestrictive` / `isWriteRestrictive` are exported for users who need to inspect a policy at runtime.
+
+This is a contract change inside the beta window — the API has shifted before `1.7.0` final, which is exactly what the beta dist-tag exists for. No public types were removed; `RestrictivePolicy` remains a public type and resolves to the union of the two new flavors.
+
+### Public API additions (additive only)
+
+- New exports: `override`, `permissive`, `restrictive`, `isReadRestrictive`, `isWriteRestrictive`, `OGMWithContext`, `PolicyDeniedError`.
+- New types: `Policy`, `OverridePolicy`, `PermissivePolicy`, `RestrictivePolicy`, `ReadRestrictivePolicy`, `WriteRestrictivePolicy`, `PolicyContext`, `PolicyContextBundle`, `Operation`, `OperationOrWildcard`, `ReadOperation`, `WriteOperation`, `PoliciesByModel`, `PolicyDefaults`, `ResolvedPolicies`, `UnsafeOptions`.
+- `OGMConfig` gains optional `policies?` and `policyDefaults?`.
+- `OGM` gains `withContext<C>(ctx: C)` and `unsafe.bypassPolicies()`.
+- Every Model / InterfaceModel method's params bag gains optional `unsafe?: { bypassPolicies?: boolean }`.
+- All existing call signatures remain valid. Calling code that doesn't pass policies must compile and run identically — byte-identical Cypher for non-policy calls.
+
+### Install command (beta)
+
+```bash
+npm install grafeo-ogm@beta
+# or
+pnpm add grafeo-ogm@beta
+```
+
+### Known limits in this beta
+
+- **`@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. (Top-level WHERE on the root model still supports `@cypher` filters.)
+- **`upsert` evaluates create- and update-side policies at the application layer.** MERGE has no WHERE we can stitch into; the WHERE-side enforcement only covers the matching path. Documented limit; full MERGE-aware enforcement is deferred to v1.7.1.
+- **Restrictive read/write split — fixed in this iteration.** The dual-invocation contract bug present in earlier beta builds is resolved. `ReadRestrictivePolicy` (`when(ctx)`) is invoked exactly once at WHERE-compile; `WriteRestrictivePolicy` (`when(ctx, input)`) is invoked exactly once at the application layer. See the "Contract change during beta" section above for the new shape and migration notes.
+- **InterfaceModel CASE-per-label fallback.** When an interface has policies registered but a concrete implementer does not, the implementer's branch falls back to interface-level enforcement only (rather than default-denying the unlisted implementer). The OGM emits a `logger.warn` at construction time when this configuration is detected so it never passes silently. Strict per-implementer default-deny is being evaluated for `1.7.0` final.
+- **AsyncLocalStorage opt-in is deferred to v1.7.1.** Beta is explicit `withContext()` only — create one wrapper per request and discard it.
+- **Index requirement declaration deferred to v1.8.0.** No `requires.indexes` config in this beta.
+- **EXPLAIN-in-test mode deferred to v1.8.0.** No dev hook in beta.
+- **No live Neo4j integration test in this beta.** Mock-driver coverage is extensive (1317 specs incl. byte-identical regression of every v1.6.0 emission and the C1 read/write contract proofs), but a live `pnpm run test:integration` against a real Neo4j is a `1.7.0` final blocker.
+
+### Unaffected paths (byte-identical to v1.6.0)
+
+- An OGM constructed without `policies` emits identical Cypher to v1.6.0 for every covered operation. Verified in `tests/policy/byte-identical.spec.ts`.
+- An OGM with `policies` but invoked via the bare `OGM.model()` path (no `withContext`) emits identical Cypher to v1.6.0.
+- An override match emits identical Cypher to a no-policy query.
+- `ogm.unsafe.bypassPolicies()` and per-call `unsafe: { bypassPolicies: true }` both emit identical Cypher to v1.6.0.
+
+### Generated types
+
+- Existing `<Node>Where`, `<Node>CreateInput`, `<Node>UpdateInput` are sufficient for typing policy callbacks. The generator's `ModelMap` already exposed `Where`, `CreateInput`, and `UpdateInput` keys per model so `PoliciesByModel<M, C>` can index into them. **No regeneration required when upgrading from v1.6.0 → v1.7.0-beta.0.**
+
+### Migration
+
+- v1.6.0 → v1.7.0-beta.0 is purely additive — no changes required unless you opt into NLS.
+
 ## 1.6.0 (2026-05-01)
 
 ### Features

package/README.md

@@ -213,6 +213,24 @@ await ogm.$transaction(async (ctx) => {
 
 ---
 
+## Beta features
+
+The current beta release exposes one new feature behind opt-in config:
+
+- **Node-Level Security (NLS)** — a Postgres-RLS-style filter layer that compiles into the existing WHERE pipeline. See **[Advanced Features → Node-Level Security (Beta)](#node-level-security-beta)**.
+
+The beta is purely additive: an OGM constructed without the new `policies` option emits **byte-identical Cypher** to v1.6.0. Install with:
+
+```bash
+npm install grafeo-ogm@beta
+# or
+pnpm add grafeo-ogm@beta
+```
+
+The shape of the public API is settled, but the beta window is for collecting integration feedback. Minor adjustments may land before `1.7.0` final.
+
+---
+
 ## Features Overview
 
 | Feature | Description |
@@ -918,6 +936,171 @@ These are not OGM bugs — they are Cypher-language constraints. Pattern compreh
 
 Each scope (`where`, `select`, sort) emits its own `CALL { WITH n; WITH n AS this; <statement> }` block per `@cypher` field reference. A query that references the same `@cypher` field in all three scopes emits three `CALL` blocks. This is functionally correct and parameter-isolated, but worth knowing if your statement is expensive (multi-hop traversals, aggregations over large fan-outs). For frequently-accessed computed values, consider materializing as a stored property updated on write instead.
 
+### Node-Level Security (Beta)
+
+> **Beta — install with `npm install grafeo-ogm@beta`.**
+
+Node-Level Security (NLS) is a per-request filter layer that compiles into the existing WHERE pipeline. Policies return `<Node>Where` partials, so every operator, quantifier, connection filter, and nested traversal already supported by `WhereCompiler` is automatically available inside policies — no new DSL.
+
+#### Declaration
+
+```typescript
+import { OGM, override, permissive, restrictive } from 'grafeo-ogm';
+
+interface RequestCtx {
+  userId: string;
+  capabilities: string[];
+  tierIds: string[];
+}
+
+const ogm = new OGM<ModelMap>({
+  typeDefs,
+  driver,
+  policies: {
+    Book: [
+      // Compile-time short-circuit. When `when(ctx)` returns true, ALL
+      // other policies for `Book.read` are dropped — query is byte-
+      // identical to a no-policy query. Zero runtime cost for admins.
+      override({
+        operations: ['*'],
+        when: (c: RequestCtx) => c.capabilities.includes('admin'),
+        name: 'admin-bypass',
+      }),
+
+      // OR-grant. Multiple permissives compose with OR — any match grants.
+      permissive({
+        operations: ['read'],
+        when: (c: RequestCtx) => ({ ownerId: c.userId }),
+        name: 'owner-can-read',
+      }),
+
+      // Read-side restrictive — AND-row predicate. Compiles into the
+      // WHERE clause and applies to read|delete|aggregate|count.
+      // `when` receives only `ctx` and returns a where-partial (or
+      // `false` for a hard deny).
+      restrictive({
+        operations: ['read'],
+        when: (c: RequestCtx) => ({ tierIds_IN: c.tierIds }),
+        name: 'tier-isolation',
+      }),
+
+      // Write-side restrictive — Postgres `WITH CHECK` semantics. Runs
+      // at the application layer for create|update only; receives both
+      // `ctx` and the user-submitted `input`. MUST return a boolean.
+      // The OGM rejects mixed read+write `operations` arrays — split a
+      // single restrictive into two if you need both read- and write-
+      // side coverage.
+      restrictive({
+        operations: ['create', 'update'],
+        when: (c, input) =>
+          (input as { ownerId?: string }).ownerId === c.userId,
+        name: 'cannot-set-other-owner',
+      }),
+    ],
+  },
+  policyDefaults: {
+    onDeny: 'empty', // Or 'throw' — raises PolicyDeniedError pre-compile.
+    auditMetadata: true,
+  },
+});
+
+// Per request:
+const Books = ogm.withContext({ userId, capabilities, tierIds }).model('Book');
+const visible = await Books.find({ where: { published_GT: '2024-01-01' } });
+```
+
+The Cypher emitted for the call above is roughly:
+
+```cypher
+MATCH (n:`Book`)
+WHERE (n.`published` > $param0) AND ((n.`ownerId` = $param1) AND n.`tierIds` IN $param2)
+RETURN n { .id, .title, .ownerId, .tierIds, ... }
+```
+
+#### Hierarchical ACL example
+
+Combine permissives to express "owner OR member of an allowed tier":
+
+```typescript
+policies: {
+  Book: [
+    permissive({
+      operations: ['read'],
+      when: (c) => ({ ownerId: c.userId }),
+      name: 'owner-can-read',
+    }),
+    permissive({
+      operations: ['read'],
+      // Returns a where-partial that uses the existing _SOME quantifier.
+      when: (c) => ({ tiers_SOME: { id_IN: c.tierIds } }),
+      name: 'tier-can-read',
+    }),
+  ],
+}
+```
+
+Both permissives OR together — a row passes if either branch matches.
+
+#### Interface inheritance
+
+Policies on an interface AND with policies on every implementing concrete type. Concrete types can only narrow restrictives, never broaden — predictable. `OR` composition for permissives lets concrete types add allow paths their interface didn't anticipate.
+
+```typescript
+policies: {
+  Resource: [
+    // Tenant isolation applies to every type that implements Resource.
+    restrictive({ operations: ['read'], when: (c) => ({ tenantId: c.tenantId }) }),
+  ],
+  Book: [
+    // Additional grant only for Book — composed via OR with any
+    // Resource-level permissives.
+    permissive({ operations: ['read'], when: (c) => ({ authorId: c.userId }) }),
+  ],
+}
+```
+
+#### 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.
+
+#### Escape hatches
+
+```typescript
+// Disable policies for a single call. Logged via logger.warn.
+await Books.find({ where: { id: 'b1' }, unsafe: { bypassPolicies: true } });
+
+// Disable policies for a derived OGM (data migrations, admin scripts).
+const adminOgm = ogm.unsafe.bypassPolicies();
+```
+
+Both paths emit byte-identical Cypher to a no-policy OGM.
+
+#### Audit metadata
+
+When `policies` is configured, every OGM-emitted query attaches transaction metadata:
+
+```typescript
+{
+  ogmPolicySetVersion: '1.7.0-beta.0',
+  ctxFingerprint: '<sha256 of sorted ctx KEYS — never values>',
+  modelType: 'Book',
+  operation: 'read',
+  policiesEvaluated: ['owner-can-read', 'tier-isolation'],
+  bypassed: false,
+}
+```
+
+Disable via `policyDefaults: { auditMetadata: false }`. The fingerprint is intentionally key-only — no ctx values are leaked.
+
+#### Beta limits
+
+- **`@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 deferred to v1.7.1.
+- **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); the dual-invocation contract bug from earlier beta iterations is fixed. 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.
+- **AsyncLocalStorage** opt-in is deferred to v1.7.1. Beta is explicit `withContext()` only — create one wrapper per request, discard after.
+- **Live Neo4j integration tests are not part of the beta.** Mock-driver coverage is extensive but a real-DB suite is a `1.7.0` final blocker.
+
 ### Raw Cypher
 
 ```typescript

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

@@ -1,3 +1,4 @@
+import type { PolicyContextBundle } from '../policy/types';
 import type { NodeDefinition, SchemaMetadata } from '../schema/types';
 import { CypherFieldScope } from '../utils/cypher-field-projection';
 import type { WhereCompiler } from './where.compiler';
@@ -70,7 +71,15 @@ export declare class SelectionCompiler {
      * throw — this is the case inside nested relationship pattern
      * comprehensions where CALL { ... } subqueries are not allowed.
      */
-    cypherScope?: CypherFieldScope | null): string;
+    cypherScope?: CypherFieldScope | null, 
+    /**
+     * Policy context for nested-selection enforcement. When set, every
+     * relationship pattern comprehension, connection edge, and union
+     * branch resolves the target type's `'read'` policy via
+     * `policyContext.resolveForType` and AND-stitches it into the inner
+     * WHERE clause. Without this, traversals would bypass policies.
+     */
+    policyContext?: PolicyContextBundle | null): string;
     /**
      * Parse a GraphQL selection set string into SelectionNode[].
      *
@@ -110,6 +119,17 @@ export declare class SelectionCompiler {
      * Compile a connection field into a Cypher pattern comprehension with edge properties.
      */
     private compileConnection;
+    /**
+     * AND-combine an optional user where (`select.where` / `connectionWhere`)
+     * with the target type's `'read'` policy and emit a `WHERE …` fragment
+     * (with leading space). Returns `''` when nothing applies.
+     *
+     * The returned where lives inside a pattern comprehension so any
+     * `@cypher` field used by the policy MUST throw — the comprehension
+     * cannot host CALL { ... } subqueries. The error message points to the
+     * documented limitation.
+     */
+    private compileNestedWhere;
     /**
      * Compile a __typename expression for a node.
      * For union targets: picks the label matching a union member name.

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

@@ -1 +1 @@
-{"version":3,"file":"selection.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/selection.compiler.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAOpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,YAAY,CAAC,EAAE,aAAa,EAAE,CAAC;IAC/B,mFAAmF;IACnF,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D;;;OAGG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;KACxB,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAW1B,OAAO,CAAC,MAAM;IAVhB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAK;IAC9C;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,aAAa,CAAC,CAAgB;gBAG5B,MAAM,EAAE,cAAc,EAC9B,aAAa,CAAC,EAAE,aAAa;IAK/B,8EAA8E;IAC9E,UAAU,IAAI,IAAI;IAIlB;;;;;;;;;OASG;IACH,OAAO,CACL,SAAS,EAAE,aAAa,EAAE,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4C,EACtD,YAAY,GAAE,MAAU,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAChC;;;;;;;OAOG;IACH,WAAW,GAAE,gBAAgB,GAAG,IAAW,GAC1C,MAAM;IAmHT;;;;;OAKG;IACH,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,EAAE;IA8BxD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgD3B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuF3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,6BAA6B;IA6DrC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuIzB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAoBvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAsC3B"}
+{"version":3,"file":"selection.compiler.d.ts","sourceRoot":"","sources":["../../../src/compilers/selection.compiler.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAOpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,YAAY,CAAC,EAAE,aAAa,EAAE,CAAC;IAC/B,mFAAmF;IACnF,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D;;;OAGG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;QAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;KACxB,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAW1B,OAAO,CAAC,MAAM;IAVhB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAK;IAC9C;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,aAAa,CAAC,CAAgB;gBAG5B,MAAM,EAAE,cAAc,EAC9B,aAAa,CAAC,EAAE,aAAa;IAK/B,8EAA8E;IAC9E,UAAU,IAAI,IAAI;IAIlB;;;;;;;;;OASG;IACH,OAAO,CACL,SAAS,EAAE,aAAa,EAAE,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,MAA4C,EACtD,YAAY,GAAE,MAAU,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAChC;;;;;;;OAOG;IACH,WAAW,GAAE,gBAAgB,GAAG,IAAW;IAC3C;;;;;;OAMG;IACH,aAAa,GAAE,mBAAmB,GAAG,IAAW,GAC/C,MAAM;IAsHT;;;;;OAKG;IACH,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,EAAE;IA8BxD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgD3B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA0B/B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0E3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,6BAA6B;IA8ErC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiJzB;;;;;;;;;OASG;IACH,OAAO,CAAC,kBAAkB;IA2F1B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAoBvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAsC3B"}

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

@@ -45,7 +45,15 @@ class SelectionCompiler {
      * throw — this is the case inside nested relationship pattern
      * comprehensions where CALL { ... } subqueries are not allowed.
      */
-    cypherScope = null) {
+    cypherScope = null, 
+    /**
+     * Policy context for nested-selection enforcement. When set, every
+     * relationship pattern comprehension, connection edge, and union
+     * branch resolves the target type's `'read'` policy via
+     * `policyContext.resolveForType` and AND-stitches it into the inner
+     * WHERE clause. Without this, traversals would bypass policies.
+     */
+    policyContext = null) {
         if (selection.length === 0)
             return `${nodeVar} { .id }`;
         // Check if this nodeDef is a resolved union type — if so, relationship
@@ -100,7 +108,7 @@ class SelectionCompiler {
                 continue;
             }
             if (node.isConnection) {
-                const connectionCypher = this.compileConnection(node, nodeVar, nodeDef, maxDepth, currentDepth, params, paramCounter);
+                const connectionCypher = this.compileConnection(node, nodeVar, nodeDef, maxDepth, currentDepth, params, paramCounter, policyContext);
                 if (connectionCypher)
                     parts.push(`${node.fieldName}: ${connectionCypher}`);
                 continue;
@@ -109,12 +117,12 @@ class SelectionCompiler {
                 // For union targets, relationship fields may have different relationship
                 // types across members. Generate CASE WHEN branches per member.
                 if (unionMembers && unionMembers.length > 0) {
-                    const caseCypher = this.compileUnionRelationshipField(node, nodeVar, unionMembers, maxDepth, currentDepth, params, paramCounter);
+                    const caseCypher = this.compileUnionRelationshipField(node, nodeVar, unionMembers, maxDepth, currentDepth, params, paramCounter, policyContext);
                     if (caseCypher)
                         parts.push(`${node.fieldName}: ${caseCypher}`);
                     continue;
                 }
-                const relCypher = this.compileRelationship(node, nodeVar, nodeDef, maxDepth, currentDepth, params, paramCounter);
+                const relCypher = this.compileRelationship(node, nodeVar, nodeDef, maxDepth, currentDepth, params, paramCounter, policyContext);
                 if (relCypher)
                     parts.push(`${node.fieldName}: ${relCypher}`);
                 continue;
@@ -220,7 +228,7 @@ class SelectionCompiler {
     /**
      * Compile a relationship field into a Cypher pattern comprehension.
      */
-    compileRelationship(node, parentVar, parentDef, maxDepth, currentDepth, params, paramCounter) {
+    compileRelationship(node, parentVar, parentDef, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
         if (currentDepth >= maxDepth)
             return null;
         const relDef = parentDef.relationships.get(node.fieldName);
@@ -238,26 +246,19 @@ class SelectionCompiler {
             schema: this.schema,
         });
         const children = node.children ?? [];
-        const innerProjection = this.compile(children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter);
-        // Compile WHERE clause for relationship filtering (Prisma-like select)
-        let whereClause = '';
-        if (node.relationshipWhere &&
-            Object.keys(node.relationshipWhere).length > 0 &&
-            this.whereCompiler &&
-            params &&
-            paramCounter) {
-            const whereResult = this.whereCompiler.compile(node.relationshipWhere, childVar, targetDef, paramCounter);
-            // Pattern comprehensions cannot host CALL { ... } subqueries, so we
-            // cannot stitch `@cypher` field preludes here. Reject with a clear
-            // error rather than silently dropping them.
-            if (whereResult.preludes && whereResult.preludes.length > 0)
-                throw new errors_1.OGMError(`Filtering nested-select relationship "${node.fieldName}" by an @cypher field is not supported. ` +
-                    `@cypher fields can only appear in top-level WHERE filters, not inside select.where on relationships.`);
-            if (whereResult.cypher) {
-                (0, validation_1.mergeParams)(params, whereResult.params);
-                whereClause = ` WHERE ${whereResult.cypher}`;
-            }
-        }
+        const innerProjection = this.compile(children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter, null, policyContext);
+        // Compile WHERE clause for relationship filtering (Prisma-like select).
+        // Combines user `select.where` with the target type's `'read'` policy.
+        const whereClause = this.compileNestedWhere({
+            node,
+            childVar,
+            targetDef,
+            params,
+            paramCounter,
+            policyContext,
+            contextLabel: `relationship "${node.fieldName}"`,
+            userWhere: node.relationshipWhere,
+        });
         const comprehension = `[${pattern}${whereClause} | ${innerProjection}]`;
         // Wrap singular relationships with head()
         if (!relDef.isArray)
@@ -291,7 +292,7 @@ class SelectionCompiler {
      *     ELSE []
      *   END
      */
-    compileUnionRelationshipField(node, nodeVar, unionMembers, maxDepth, currentDepth, params, paramCounter) {
+    compileUnionRelationshipField(node, nodeVar, unionMembers, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
         if (currentDepth >= maxDepth)
             return null;
         const branches = [];
@@ -311,7 +312,7 @@ class SelectionCompiler {
                 isSingular = true;
             const childVar = `n${currentDepth}`;
             const children = node.children ?? [];
-            const innerProjection = this.compile(children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter);
+            const innerProjection = this.compile(children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter, null, policyContext);
             const pattern = (0, utils_1.buildRelPattern)({
                 sourceVar: nodeVar,
                 relDef,
@@ -319,10 +320,23 @@ class SelectionCompiler {
                 targetLabel: 'auto',
                 schema: this.schema,
             });
+            // Inject the union member's `'read'` policy into the comprehension WHERE.
+            const memberPolicyWhere = this.compileNestedWhere({
+                node,
+                childVar,
+                targetDef,
+                params,
+                paramCounter,
+                policyContext,
+                contextLabel: `union member "${memberName}" of "${node.fieldName}"`,
+                // Union branches don't have a user select.where in the
+                // SelectionNode model — only policies contribute here.
+                userWhere: undefined,
+            });
             // Wrap singular relationships with head() to return object instead of array
             const comprehension = isSingular
-                ? `head([${pattern} | ${innerProjection}])`
-                : `[${pattern} | ${innerProjection}]`;
+                ? `head([${pattern}${memberPolicyWhere} | ${innerProjection}])`
+                : `[${pattern}${memberPolicyWhere} | ${innerProjection}]`;
             const memberLabel = (0, validation_1.escapeIdentifier)(memberName);
             branches.push(`WHEN ${nodeVar}:${memberLabel} THEN ${comprehension}`);
         }
@@ -334,7 +348,7 @@ class SelectionCompiler {
     /**
      * Compile a connection field into a Cypher pattern comprehension with edge properties.
      */
-    compileConnection(node, parentVar, parentDef, maxDepth, currentDepth, params, paramCounter) {
+    compileConnection(node, parentVar, parentDef, maxDepth, currentDepth, params, paramCounter, policyContext = null) {
         if (currentDepth >= maxDepth)
             return null;
         // Strip 'Connection' suffix to find the relationship field
@@ -359,7 +373,7 @@ class SelectionCompiler {
         const projectionKeys = [];
         // Compile node projection
         if (node.children && node.children.length > 0) {
-            const nodeProjection = this.compile(node.children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter);
+            const nodeProjection = this.compile(node.children, childVar, targetDef, maxDepth, currentDepth + 1, params, paramCounter, null, policyContext);
             mapParts.push(`node: ${nodeProjection}`);
             projectionKeys.push('node');
         }
@@ -386,7 +400,8 @@ class SelectionCompiler {
                 sortKeyTokens.push(direction === 'ASC' ? `'^${syntheticKey}'` : `'${syntheticKey}'`);
             });
         const innerMap = `{ ${mapParts.join(', ')} }`;
-        // Add WHERE clause if connectionWhere is present
+        // Add WHERE clause if connectionWhere is present, AND-combined with the
+        // target type's `'read'` policy.
         let whereClause = '';
         if (node.connectionWhere && Object.keys(node.connectionWhere).length > 0) {
             // Reject unsupported edge WHERE filters with a descriptive error
@@ -398,23 +413,35 @@ class SelectionCompiler {
                 ? node.connectionWhere.node
                 : node.connectionWhere;
             // If we have a full WhereCompiler, delegate to it for complete operator support
-            if (this.whereCompiler && targetDef) {
-                const whereResult = this.whereCompiler.compile(nodeWhere, childVar, targetDef, paramCounter);
-                if (whereResult.preludes && whereResult.preludes.length > 0)
-                    throw new errors_1.OGMError(`Filtering connection "${node.fieldName}" by an @cypher field is not supported. ` +
-                        `@cypher fields can only appear in top-level WHERE filters, not inside connection where.`);
-                if (whereResult.cypher) {
-                    if (params)
-                        (0, validation_1.mergeParams)(params, whereResult.params);
-                    whereClause = ` WHERE ${whereResult.cypher}`;
-                }
-            }
+            if (this.whereCompiler && targetDef)
+                whereClause = this.compileNestedWhere({
+                    node,
+                    childVar,
+                    targetDef,
+                    params,
+                    paramCounter,
+                    policyContext,
+                    contextLabel: `connection "${node.fieldName}"`,
+                    userWhere: nodeWhere,
+                });
             else {
                 const simpleWhere = this.compileSimpleWhere(node.connectionWhere, childVar, params, paramCounter);
                 if (simpleWhere)
                     whereClause = ` WHERE ${simpleWhere}`;
             }
         }
+        else if (this.whereCompiler && targetDef)
+            // No user where but we still need the policy injected if active.
+            whereClause = this.compileNestedWhere({
+                node,
+                childVar,
+                targetDef,
+                params,
+                paramCounter,
+                policyContext,
+                contextLabel: `connection "${node.fieldName}"`,
+                userWhere: undefined,
+            });
         if (sortKeyTokens.length === 0)
             return `{ edges: [${pattern}${whereClause} | ${innerMap}] }`;
         // Re-project only the user-facing keys so synthetic __skN scalars don't
@@ -424,6 +451,71 @@ class SelectionCompiler {
             : `{}`;
         return `{ edges: [x IN apoc.coll.sortMulti([${pattern}${whereClause} | ${innerMap}], [${sortKeyTokens.join(', ')}]) | ${outerProjection}] }`;
     }
+    /**
+     * AND-combine an optional user where (`select.where` / `connectionWhere`)
+     * with the target type's `'read'` policy and emit a `WHERE …` fragment
+     * (with leading space). Returns `''` when nothing applies.
+     *
+     * The returned where lives inside a pattern comprehension so any
+     * `@cypher` field used by the policy MUST throw — the comprehension
+     * cannot host CALL { ... } subqueries. The error message points to the
+     * documented limitation.
+     */
+    compileNestedWhere(args) {
+        const { node, childVar, targetDef, params, paramCounter, policyContext, contextLabel, userWhere, } = args;
+        if (!this.whereCompiler || !params || !paramCounter) {
+            // Without these, the policy can't be compiled — fall back to user-only
+            // (matches v1.6.0 behavior when WhereCompiler isn't wired).
+            if (userWhere && Object.keys(userWhere).length > 0)
+                // We can't compile via whereCompiler without paramCounter; let
+                // the fallback simple where path handle it.
+                return '';
+            return '';
+        }
+        // Resolve the target type's read policy (if any).
+        const targetPolicy = policyContext
+            ? policyContext.resolveForType(targetDef.typeName, 'read')
+            : null;
+        const targetBundle = targetPolicy
+            ? {
+                ctx: policyContext.ctx,
+                operation: 'read',
+                resolved: targetPolicy,
+                resolveForType: policyContext.resolveForType,
+                defaults: policyContext.defaults,
+            }
+            : undefined;
+        // Compile combined user where + policy in one pass.
+        const compiled = this.whereCompiler.compile(userWhere, childVar, targetDef, paramCounter, targetBundle ? { policyContext: targetBundle } : undefined);
+        // Pattern comprehensions cannot host CALL { ... } subqueries.
+        if (compiled.preludes && compiled.preludes.length > 0) {
+            // Two distinct cases:
+            //  - user where references @cypher → original v1.6.0 error path
+            //  - policy references @cypher inside nested selection → new path
+            const policyHasCypher = targetBundle &&
+                compiled.cypher.length > 0 &&
+                // Heuristic: if the user where alone produces no cypher refs but
+                // adding policy did, then policy is the source. We use a clearer
+                // policy-targeted error since both paths are equivalent for the
+                // user.
+                true;
+            if (policyHasCypher && targetBundle)
+                throw new errors_1.OGMError(`Policy on "${targetDef.typeName}" requires @cypher field projection, ` +
+                    `which is not supported inside nested-selection enforcement (${contextLabel}). ` +
+                    `Refactor the policy to use stored properties or a relationship traversal.`);
+            throw new errors_1.OGMError(`Filtering ${contextLabel} by an @cypher field is not supported. ` +
+                `@cypher fields can only appear in top-level WHERE filters, not inside select.where on relationships.`);
+        }
+        if (compiled.cypher) {
+            (0, validation_1.mergeParams)(params, compiled.params);
+            return ` WHERE ${compiled.cypher}`;
+        }
+        // Compile produced no clause but may still have merged params.
+        if (compiled.params && Object.keys(compiled.params).length > 0)
+            (0, validation_1.mergeParams)(params, compiled.params);
+        void node;
+        return '';
+    }
     /**
      * Compile a __typename expression for a node.
      * For union targets: picks the label matching a union member name.