grafeo-ogm 1.5.0 → 1.7.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## [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
+
+- **`@cypher` scalar fields are now resolved at runtime in `WHERE`** — `find()`, `findFirst()`, `findUnique()`, `count()`, `aggregate()`, `update()`, `updateMany()`, `delete()`, `deleteMany()`, `upsert()`, `setLabels()`, `searchByVector()`, `searchByPhrase()`, and `InterfaceModel.find()` / `aggregate()` now resolve `@cypher` scalar fields when they appear as filter keys (with or without operator suffix — `_EQ`, `_CONTAINS`, `_GT`, `_LT`, `_GTE`, `_LTE`, `_IN`, `_NOT`, `_NOT_IN`, `_STARTS_WITH`, `_ENDS_WITH`, `_MATCHES`, `_NOT_CONTAINS`, etc.). Pre-1.6.0, the typed `<Node>Where` surface emitted these fields and the WHERE compiler would compile `n.<cypherField>` against a property that doesn't exist on the node — predicate always false → silent data omission. Each `@cypher` filter is now compiled into a `CALL { WITH n; WITH n AS this; <user statement> }` prelude before the `WHERE`, with the projected column renamed to a unique `__where_n_<fieldName>` alias the predicate references.
+- **`@cypher` scalar fields are now resolved at runtime in `SELECT`** — both `selectionSet: '...'` (string SDL) and `select: { field: true }` (typed) paths now project `@cypher` scalar fields. Compiled into a `CALL { ... } WITH n, <col> AS __sel_n_<fieldName>` prelude before the `RETURN`, then projected into the map as `<fieldName>: __sel_n_<fieldName>`. Pre-1.6.0 these fields were silently emitted as `.\`<fieldName>\`` and returned NULL.
+- **AND/OR/NOT composition de-dupes references** — a `@cypher` field referenced multiple times at the same scope (e.g. `OR: [{ field_GT: 1 }, { field_LT: 10 }]`) emits a single `CALL` prelude shared by all references.
+- **Relationship-quantifier inner WHERE** — `@cypher` scalar fields on related nodes now work inside `_SOME` / `_NONE` / `_ALL` filters (e.g. `hasStatus_SOME: { statusLowerName_CONTAINS: 'act' }`). The inner `CALL` prelude is stitched directly inside the `EXISTS { MATCH pattern <prelude> WHERE <inner> }` body so each iteration projects the field for its own bound relationship variable.
+- **Combined WHERE + SELECT + sort** — all three preludes can co-exist in the same query. Each uses a disjoint alias namespace (`__where_*`, `__sel_*`, `__sort_*`) and the carry chain is threaded so later `WITH` clauses preserve aliases from earlier preludes.
+- **Mutation projections now project `@cypher` fields** — `update()`, `upsert()`, and `create()` honour `@cypher` fields in their `select` / `selectionSet` projections via the same SELECT prelude pipeline.
+
+### Internal
+
+- New helper `src/utils/cypher-field-projection.ts` exporting `buildCypherFieldCall()` and `CypherFieldScope`. `CypherFieldScope` is the central state holder used by both `WhereCompiler` and `SelectionCompiler`: it dedupes per-`(nodeVar, fieldName)` registrations, threads carried aliases through every emitted `WITH`, and accepts a `preserveVars` array so callers can keep surrounding pipeline vars (`__typename`, `score`) in scope.
+- `WhereCompiler.compile()` now returns `WhereResult { cypher, params, preludes? }`. Top-level preludes are returned for the caller to stitch between MATCH and WHERE; inner-scope preludes (relationship quantifiers, union members) are stitched directly into the `EXISTS` body. A new `compile(...)` option `preserveVars` lets callers keep `score` (vector / fulltext) or `__typename` (interface) in scope across the prelude `WITH` chain.
+- `MutationCompiler.compileUpdate()`, `compileDelete()`, and `compileSetLabels()` accept `whereResult.preludes` and emit them between MATCH and WHERE.
+- `SelectionCompiler.compile()` accepts an optional `cypherScope` argument. When supplied, top-level `@cypher` scalar fields register there and the caller stitches the scope's emitted lines before the RETURN. When omitted (the default for nested recursive calls), `@cypher` scalar fields throw — pattern comprehensions cannot host CALL subqueries.
+- `Model.compileOptions()` now accepts `preserveVars` so the sort prelude carries forward any aliases already projected by an earlier SELECT prelude.
+
+### Notes & Limits
+
+- **Scalar return types only.** Mirrors the v1.5.0 sort scope. `@cypher` fields whose declared return type is a node / interface / union are still projection-only (the `where-emitter` already excludes them, and the SELECT pipeline does not synthesize a sub-projection from a `@cypher` statement).
+- **Aggregations are out of scope.** `aggregate()` continues to skip `@cypher` fields when emitting `min(n.<f>) / max / avg`. The aggregation emitters (`<Type>AggregationSelection`, `<Type>EdgeAggregateSelection`, etc.) already exclude `@cypher` from the typed surface.
+- **`_SINGLE` quantifiers reject `@cypher` filters.** Both relationship `_SINGLE` and `Connection_SINGLE` use list comprehensions (`size([(pattern WHERE inner) | 1]) = 1`) which cannot host `CALL { ... }` subqueries. Using a `@cypher` field inside `_SINGLE` throws `OGMError` with a clear message — refactor to `_SOME` + `_NONE`.
+- **Nested-relationship SELECT projection of `@cypher` fields is rejected.** `select: { hasStatus: { select: { statusLowerName: true } } }` (selecting a `@cypher` field on a related node inside a nested selection) throws `OGMError`. Nested relationships use list comprehensions for their pattern, and CALL subqueries cannot be embedded there. Top-level `@cypher` fields on the root model are fully supported. Workaround: query the related node directly via its own model.
+- **Connection `where` does not accept `@cypher` filters.** `select: { hasStatusConnection: { where: { node: { statusLowerName_CONTAINS: 'x' } } } }` throws — same constraint as above.
+- **`select.where` (Prisma-style relationship filtering) does not accept `@cypher` filters.** Same root cause; same error.
+- **Stored-only queries are byte-identical to 1.5.0.** Only queries that reference at least one `@cypher` field gain the new prelude machinery. Every previous test passes without modification (1031 → 1092 tests after this release).
+- **No new generic parameters or breaking type changes.** The `<Node>Where` and `<Node>Select` types are unchanged; if you regenerated against 1.4.x or 1.5.x, those types already exposed scalar `@cypher` fields and now they are correctly resolved at runtime.
+
 ## 1.5.0 (2026-04-30)
 
 ### Features
@@ -23,7 +132,7 @@
 
 - **Sort-only.** This release implements `@cypher` resolution exclusively for `ORDER BY`. `select`, `selectionSet`, `where`, and `aggregate` continue to skip `@cypher` fields at runtime as in 1.4.0 — those use cases will be addressed in a separate release.
 - **Pre-existing `where-emitter` footgun unchanged**: scalar `@cypher` fields are still emitted in `<Node>Where`, and the WHERE compiler still produces `n.<cypherField>` (which fails at Neo4j). This was already broken in 1.4.x and is out of scope for 1.5.0; track in a separate issue.
-- **Statement convention.** `@cypher` statements must reference the bound node as `this` and end with `RETURN <expr> AS <columnName>` (or `RETURN <expr>` alone — the column name then defaults to the GraphQL field name). Example: `@cypher(statement: "RETURN toLower(this.drugName) AS insensitiveDrugName")`. The OGM never modifies the user's statement — `this` is rebound by the wrapping `CALL` subquery.
+- **Statement convention.** `@cypher` statements must reference the bound node as `this` and end with `RETURN <expr> AS <columnName>` (or `RETURN <expr>` alone — the column name then defaults to the GraphQL field name). Example: `@cypher(statement: "RETURN toLower(this.title) AS insensitiveTitle")`. The OGM never modifies the user's statement — `this` is rebound by the wrapping `CALL` subquery.
 - **Stored-field sorts produce byte-identical Cypher to 1.4.0.** Only sorts that resolve to a `@cypher` field gain the new CALL/WITH machinery; everything else is unchanged.
 - **No new generic parameters or breaking type changes.** `TSort` keeps its 1.4.0 default (`Record<string, 'ASC' | 'DESC'>`) — un-regenerated consumers continue to compile against the older `<Node>Sort` shape.
 

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 |
@@ -250,7 +268,7 @@ grafeo-ogm uses standard GraphQL SDL with Neo4j directives to define your graph
 | `@relationshipProperties` | Type | Marks a type as relationship properties (edge data) |
 | `@id` | Field | Auto-generates a UUID on create |
 | `@unique` | Field | Creates a uniqueness constraint in Neo4j |
-| `@cypher` | Field | Computed field resolved via a custom Cypher statement |
+| `@cypher` | Field | Computed field resolved via a custom Cypher statement. Scalar return types are resolved at runtime in `select` / `selectionSet`, `where`, and `options.sort` (see [Computed Fields with @cypher](#computed-fields-with-cypher)); node/interface return types remain projection-only |
 | `@default` | Field | Sets a default value on create |
 | `@fulltext` | Type | Defines fulltext search indexes with `name` and `fields` |
 | `@vector` | Type | Registers one or more Neo4j vector indexes on a node (see [Vector Search](#vector-search)) |
@@ -814,6 +832,275 @@ const deleteResult = await deleteSubgraph(
 );
 ```
 
+### Computed Fields with @cypher
+
+The `@cypher` directive declares a field whose value is produced by a custom Cypher statement at query time. As of v1.6.0, scalar `@cypher` fields are resolved in three scopes — `select` / `selectionSet`, `where`, and `options.sort` — so you can project, filter, and order by them just like stored properties. Pre-1.6.0, references in `select` and `where` silently returned `NULL`.
+
+#### Declaration
+
+```graphql
+type Book @node {
+  id: ID! @id
+  title: String!
+  published: DateTime
+
+  # Computed: lowercased title for case-insensitive sort/filter
+  insensitiveTitle: String @cypher(
+    statement: "RETURN toLower(this.title) AS result"
+    columnName: "result"
+  )
+
+  # Computed: count of related reviews
+  reviewCount: Int @cypher(
+    statement: "MATCH (this)-[:HAS_REVIEW]->(r) RETURN count(r) AS count"
+    columnName: "count"
+  )
+
+  # Computed: average review rating (aggregating relationship-property data)
+  averageRating: Float @cypher(
+    statement: "MATCH (this)-[:HAS_REVIEW]->(r) RETURN avg(r.rating) AS avg"
+    columnName: "avg"
+  )
+}
+```
+
+`statement` is the Cypher body — `this` is bound to the matched node. `columnName` is the alias the OGM reads from the `RETURN` clause; if omitted it defaults to the field name.
+
+#### Using @cypher in SELECT
+
+```typescript
+const books = await Book.find({
+  select: {
+    id: true,
+    title: true,
+    insensitiveTitle: true,
+    reviewCount: true,
+    averageRating: true,
+  },
+});
+
+// Or via the legacy selectionSet API:
+const books = await Book.find({
+  selectionSet: '{ id title insensitiveTitle reviewCount averageRating }',
+});
+```
+
+#### Using @cypher in WHERE
+
+```typescript
+// Case-insensitive prefix match
+await Book.find({
+  where: { insensitiveTitle_STARTS_WITH: 'the' },
+});
+
+// Combined with stored fields under AND/OR
+await Book.find({
+  where: {
+    AND: [
+      { insensitiveTitle_CONTAINS: 'graph' },
+      { reviewCount_GT: 5 },
+    ],
+  },
+});
+
+// Nested inside a relationship quantifier
+// Find authors who have at least one book with more than 5 reviews
+await Author.find({
+  where: { books_SOME: { reviewCount_GT: 5 } },
+});
+```
+
+All standard operator suffixes are supported (`_EQ`, `_NOT`, `_IN`, `_NOT_IN`, `_LT`, `_LTE`, `_GT`, `_GTE`, `_CONTAINS`, `_NOT_CONTAINS`, `_STARTS_WITH`, `_ENDS_WITH`, `_MATCHES`).
+
+#### Using @cypher in ORDER BY
+
+```typescript
+await Book.find({
+  where: { insensitiveTitle_STARTS_WITH: 'g' },
+  options: { sort: [{ insensitiveTitle: 'ASC' }] },
+  select: { id: true, title: true, reviewCount: true },
+});
+```
+
+#### Limitations
+
+The following positions throw `OGMError` at compile time with a clear hint, rather than silently misbehaving:
+
+- **Connection `where` and `select.where`**: Prisma-style relationship filtering with `@cypher` is unsupported. Workaround: filter on the parent type, or query the related node directly via its own model.
+- **`_SINGLE` / `Connection_SINGLE` quantifiers**: unsupported. Workaround: combine `_SOME` and `_NONE` to express "exactly one match."
+- **Nested-relationship SELECT projection**: `select: { rel: { select: { cypherField: true } } }` is unsupported. Workaround: query the related node directly via its own model and join in application code.
+
+These are not OGM bugs — they are Cypher-language constraints. Pattern comprehensions (`[(n)-[:R]->(m) | m { ... }]`) cannot host `CALL` subqueries, so resolving an `@cypher` field inside a projection or relationship-scoped predicate is impossible at the language level.
+
+#### Performance
+
+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
@@ -1299,7 +1586,7 @@ Pure query builders (e.g. `cypher-query-builder`) help you compose Cypher fragme
 
 ### Is grafeo-ogm production-ready?
 
-Yes. The library has 892 unit tests covering compilers, mutations, fulltext, transactions, security, scalar type mapping, and edge cases. It targets Neo4j 5.x and follows semver — see [CHANGELOG.md](CHANGELOG.md).
+Yes. The library has 1,093 unit tests covering compilers, mutations, fulltext, transactions, security, scalar type mapping, and edge cases. It targets Neo4j 5.x and follows semver — see [CHANGELOG.md](CHANGELOG.md).
 
 ### Does grafeo-ogm work with Neo4j Aura?
 

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

@@ -28,6 +28,7 @@ export declare class MutationCompiler {
     compileUpdate(_where: Record<string, unknown>, update: Record<string, unknown> | undefined, connect: Record<string, unknown> | undefined, disconnect: Record<string, unknown> | undefined, nodeDef: NodeDefinition, whereResult: {
         cypher: string;
         params: Record<string, unknown>;
+        preludes?: string[];
     }, labels?: string[], returnMode?: 'node' | 'count'): MutationResult;
     /**
      * Generate DELETE Cypher with optional cascade.
@@ -35,6 +36,7 @@ export declare class MutationCompiler {
     compileDelete(nodeDef: NodeDefinition, whereResult: {
         cypher: string;
         params: Record<string, unknown>;
+        preludes?: string[];
     }, deleteInput?: Record<string, unknown>): MutationResult;
     /**
      * Generate MERGE (upsert) Cypher with ON CREATE SET / ON MATCH SET.
@@ -47,6 +49,7 @@ export declare class MutationCompiler {
     compileSetLabels(nodeDef: NodeDefinition, whereResult: {
         cypher: string;
         params: Record<string, unknown>;
+        preludes?: string[];
     }, addLabels?: string[], removeLabels?: string[]): MutationResult;
     /**
      * Generate batch CREATE (or MERGE for skipDuplicates) Cypher via UNWIND.

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":"AACA,OAAO,EACL,cAAc,EAEd,cAAc,EACf,MAAM,iBAAiB,CAAC;AAoBzB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAOf,OAAO,CAAC,MAAM;IAN1B;;;OAGG;IACH,OAAO,CAAC,UAAU,CAA6B;gBAE3B,MAAM,EAAE,cAAc;IAE1C,8EAA8E;IAC9E,WAAW,IAAI,IAAI;IAInB,OAAO,CAAC,oBAAoB;IAQ5B;;;OAGG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACjC,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,cAAc;IAkDjB;;OAEG;IACH,aAAa,CACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC/C,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,EACD,MAAM,CAAC,EAAE,MAAM,EAAE,EACjB,UAAU,GAAE,MAAM,GAAG,OAAgB,GACpC,cAAc;IAqEjB;;OAEG;IACH,aAAa,CACX,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,EACD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,cAAc;IAsCjB;;;OAGG;IACH,YAAY,CACV,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,cAAc;IA8DjB;;OAEG;IACH,gBAAgB,CACd,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,EACD,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,cAAc;IAqBjB;;;;OAIG;IACH,iBAAiB,CACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,EAAE,cAAc,EACvB,cAAc,CAAC,EAAE,OAAO,EACxB,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,cAAc;IA8FjB,OAAO,CAAC,qBAAqB;IA0B7B,OAAO,CAAC,wBAAwB;IA0EhC;;;OAGG;IACH,OAAO,CAAC,iCAAiC;IAwLzC,OAAO,CAAC,aAAa;IAuMrB,OAAO,CAAC,gBAAgB;IAyExB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAgD9B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA6ahC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAcvC;IAEF;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IA4DhC;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAyFtC,qFAAqF;IACrF,OAAO,CAAC,gBAAgB,CAAK;IAE7B;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IA+ElC,OAAO,CAAC,sBAAsB;IAS9B;;;OAGG;IACH,OAAO,CAAC,kCAAkC;IAoC1C,OAAO,CAAC,6BAA6B;IA0BrC,OAAO,CAAC,qBAAqB;CAQ9B"}

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

@@ -83,6 +83,10 @@ class MutationCompiler {
         }
         else
             lines.push(`MATCH (n:${labelStr})`);
+        // CALL preludes for `@cypher` fields referenced in the WHERE — must be
+        // emitted between MATCH and WHERE so the projected aliases are in scope.
+        if (whereResult.preludes && whereResult.preludes.length > 0)
+            lines.push(...whereResult.preludes);
         if (whereResult.cypher)
             lines.push(`WHERE ${whereResult.cypher}`);
         // SET properties
@@ -127,6 +131,8 @@ class MutationCompiler {
         const lines = [];
         const params = { ...whereResult.params };
         lines.push(`MATCH (n:${labelStr})`);
+        if (whereResult.preludes && whereResult.preludes.length > 0)
+            lines.push(...whereResult.preludes);
         if (whereResult.cypher)
             lines.push(`WHERE ${whereResult.cypher}`);
         if (deleteInput && Object.keys(deleteInput).length > 0) {
@@ -223,6 +229,8 @@ class MutationCompiler {
         const lines = [];
         const params = { ...whereResult.params };
         lines.push(`MATCH (n:${labelStr})`);
+        if (whereResult.preludes && whereResult.preludes.length > 0)
+            lines.push(...whereResult.preludes);
         if (whereResult.cypher)
             lines.push(`WHERE ${whereResult.cypher}`);
         if (addLabels && addLabels.length > 0)