@inixiative/json-rules 3.3.1 → 3.4.1

package/dist/index.d.ts

@@ -146,11 +146,11 @@ type Lens = FieldMapSet & {
 };
 /**
  * Narrowing applied wherever a model appears (intrinsic to the model).
- * Has no `relations` because relations are path-specific by definition.
  *
  * Two kinds of narrowing live here:
- * - SCHEMA narrowing (picks/omits/enumPicks/enumOmits): controls what's visible
- *   in the type surface. AI/SDK consumers can't see narrowed-away fields.
+ * - SCHEMA narrowing (picks/omits/enumPicks/enumOmits, relations): controls what's visible in the
+ *   type surface. AI/SDK consumers can't see narrowed-away fields. `picks` names columns only;
+ *   a relation is a field turned on through `relations`.
  * - DATA narrowing (where): controls which ROWS are in scope. Filter-first
  *   semantic, anchored to the model. Under arrayOperator: 'all', it becomes the window filter
  *   (filter-first) — see narrowRule.
@@ -177,6 +177,16 @@ type ModelDefaultNarrowing = {
      * via `mapDefaults`, path-specific via `root`/`relations`); a later layer's `label` wins.
      */
     sources?: Record<string, SourceEntry>;
+    /**
+     * Relations are fields, off by default. A key here turns that relation on at this node — on a
+     * path node, at that visit; on a model default, wherever the model is visited — and its value is
+     * that hop's narrowing (`where`, `picks`/`omits` of the target's columns, further `relations`).
+     * Only the first narrowing over the base lens turns a relation on; a later layer may only narrow
+     * one its parent shows. Model-default turn-ons grow a tree under each spelled node: each model
+     * once, at its nearest reach; reach it another way by spelling the path under `root`. The first narrowing's grants (`where`) may read any
+     * relation; a later layer's only what its parent shows.
+     */
+    relations?: Record<string, ModelNarrowing>;
 };
 /**
  * A sourced field's eligibility `where` plus an optional display-label column — a
@@ -213,16 +223,14 @@ type SourceSpec = {
 };
 /** A `sources` entry: a bare eligibility `Condition`, or a richer `SourceSpec`. */
 type SourceEntry = Condition | SourceSpec;
-/** Narrowing for a model at a specific traversal path. Adds relations to the default shape. */
-type ModelNarrowing = ModelDefaultNarrowing & {
-    relations?: Record<string, ModelNarrowing>;
-};
+/** Narrowing for a model at a specific traversal path: the same shape as a model default. */
+type ModelNarrowing = ModelDefaultNarrowing;
 /** Narrowing for an enum type (applies anywhere the enum is referenced). */
 type EnumNarrowing = {
     picks?: readonly string[];
     omits?: readonly string[];
 };
-/** Applies-everywhere narrowings for one map — per-model (no relations) + per-enum-type. */
+/** Applies-everywhere narrowings for one map — per-model + per-enum-type. */
 type NarrowingDefaults = {
     models?: Record<string, ModelDefaultNarrowing>;
     enums?: Record<string, EnumNarrowing>;
@@ -230,8 +238,8 @@ type NarrowingDefaults = {
 type LensNarrowing = {
     parent: Lens | LensNarrowing;
     /**
-     * Path-specific narrowing anchored at (lens.mapName, lens.model). Descends via
-     * `.relations` and may cross maps through bridge relations.
+     * Path-specific narrowing anchored at (lens.mapName, lens.model). Descends via `.relations` —
+     * which turns those relations on — and may cross maps through bridge relations.
      */
     root?: ModelNarrowing;
     /**
@@ -509,7 +517,7 @@ type StrictCondition<TRuleValue = RuleValue, TDateValue = DateRuleValue> = Stric
 /** A row as a rule reads it: a record of fields. */
 type Row = Record<string, unknown>;
 /** What both compilers take: the schema (a FieldMap, or a FieldMapSet with `mapName`), the
- *  model the rule reads, the context bare `path` refs read, and the clock. `lens` compiles the
+ *  model the rule reads, and the clock. `lens` compiles the
  *  rule under a lens instead — narrowed (`narrowRule`), against the base lens's maps, map and
  *  model — and can't be passed with `map` / `mapName` / `model`. */
 type CompileOptions = {
@@ -517,7 +525,6 @@ type CompileOptions = {
     mapName?: string;
     model?: string;
     lens?: Lens | LensNarrowing;
-    context?: Row;
 } & DateConfig;
 /** What check() evaluates: one row, or a root array of them. */
 type CheckData = Row | unknown[];
@@ -539,8 +546,8 @@ declare const listBindings: (condition: Condition, { required }?: ListBindingsOp
  */
 declare const bindRule: (condition: Condition, bindings: Record<string, RuleValue>) => Condition;
 
+/** `bindings`: the caller's values, read by `{ bind }`. The rest is the clock and zone. */
 type CheckOptions = {
-    context?: CheckData;
     bindings?: Record<string, RuleValue>;
 } & DateConfig;
 /** Evaluate a rule against one row, or a root array of rows (fieldless array rules under
@@ -575,6 +582,12 @@ declare const engineGlobals: {
     with: <T>(partial: DeepPartial<EngineGlobalsState>, fn: () => T) => T;
 };
 
+/** A caller's input missing or malformed — the clock, the time zone, a bind's value — not the
+ *  rule's or the lens's shape. */
+declare class UsageError extends Error {
+    name: string;
+}
+
 type BridgeDictionary = Record<string, // map name
 Record<string, // model name
 Record<string, Record<string, Row | Row[]>>>>;
@@ -597,9 +610,14 @@ type ValidationResult = {
     ok: boolean;
     errors: ValidationIssue[];
 };
-/** Which engine a rule must compile for; `check` (the default) accepts every rule. */
+/** Which engine a rule must compile for; `check` (the default) accepts every rule. The schema
+ *  (`map` — a FieldMap, or a FieldMapSet with `mapName` — and `model`) lets the Prisma target
+ *  accept a column compared with a column it can compile. */
 type ValidateRuleOptions = {
     target?: RuleTarget;
+    map?: FieldMap | FieldMapSet;
+    mapName?: string;
+    model?: string;
 };
 /** A rule's shape checked without data: every node well formed, and runnable on `target`
  *  (operators, windows, scope refs, patterns). */
@@ -659,8 +677,7 @@ declare const describeRule: (rule: Condition, lensOrNarrowing: Lens | LensNarrow
  * The values one rule compares at one declared source — keyed the way `projectPaths`
  * keys a source (`path` + `field`), so the caller can join it back to the source's
  * model without spelling a path of its own. A `mapDefaults`-declared source resolves
- * wherever its model appears, so `path` may name a relation chain the narrowing never
- * spelled under `root.relations`; the dotted format is the same.
+ * wherever its model appears on the declared relations; the dotted format is the same.
  */
 type RuleSourceDescription = {
     path: string;
@@ -682,23 +699,36 @@ type RuleSourceDescription = {
  * vocabulary, so it answers questions about it; callers never spell a path. A leaf reaches a
  * source by its absolute path through the lens: nested (`{ field: 'orders', arrayOperator,
  * condition: { field: 'sku' } }`) and dotted (`{ field: 'orders.sku' }`) spellings are one path,
- * resolved by `lensPathEnd` — visibility, `mapDefaults`, and the Json boundary all apply, so a
- * source declared in `mapDefaults` answers wherever its model appears. Quantifier-blind on
+ * resolved by `lensPathEnd` — declared relations, visibility, `mapDefaults`, and the Json boundary
+ * all apply, so a source declared in `mapDefaults` answers wherever a declared path reaches its model. Quantifier-blind on
  * purpose — a `none` relation names its value as much as an `any` one, `notIn` as much as `in` —
  * but shape-aware via the operator catalog: only literal-naming shapes contribute `values`;
  * substring / pattern / range / window operators, and operators the catalog does not know, mark
  * the source `dynamic` instead of inventing values. A relation node's own comparison (an
  * aggregate's threshold, an array `count`) belongs to the node, not to a source. Paths invisible
- * under the lens, unmapped segments, and sub-paths beneath a Json column are silent.
+ * or undeclared under the lens, unmapped segments, and sub-paths beneath a Json column are silent.
  */
 declare const describeRuleSources: (rule: Condition, lensOrNarrowing: Lens | LensNarrowing) => RuleSourceDescription[];
 
+/**
+ * The plan's own references — a `{ __step }` (a groupBy step's result) or a `{ __field }` (a
+ * column reference) — are objects this compile emitted, and the plan records where each sits.
+ * `executePrismaPlan` resolves those locations only: a rule value shaped like one is data, never a
+ * reference, and the compile refuses it outright.
+ */
+/** Where a step's where (or groupBy args) holds a reference: the keys down to it. */
+type SentinelRef = {
+    path: (string | number)[];
+};
+
 type PrismaWhere = Record<string, unknown>;
 type StepRef = {
     __step: number;
 };
 type GroupByStep = {
     operation: 'groupBy';
+    /** Where `args` holds this plan's own references; only those are resolved. */
+    refs?: SentinelRef[];
     model: string;
     args: {
         by: string[];
@@ -710,6 +740,8 @@ type GroupByStep = {
 type WhereStep = {
     operation: 'where';
     where: Record<string, unknown>;
+    /** Where `where` holds this plan's own references; only those are resolved. */
+    refs?: SentinelRef[];
 };
 type PrismaStep = GroupByStep | WhereStep;
 type ToPrismaResult = {
@@ -721,51 +753,12 @@ type ToPrismaOptions = CompileOptions & {
     };
 };
 
-/** A Prisma `select` tree: a column, or a relation with its own `select` and, to-many, `where`. */
-type LensSelect = {
-    [field: string]: true | LensRelationSelect;
-};
-type LensRelationSelect = {
-    select?: LensSelect;
-    where?: PrismaWhere;
-};
-/** `rules`: the rules the rows will be re-checked with — each relation they read past the declared
- *  paths opens as a declared one. The rest is what a grant's compile reads: the clock and context,
- *  never a schema (the lens is it). */
-type LensSelectOptions = Omit<ToPrismaOptions, 'map' | 'mapName' | 'model' | 'lens'> & {
-    rules?: readonly Condition[];
-};
-/** `keepGrantColumns`: keep the columns the lens's `where`s read, though it hides them. `rules`: as
- *  `toLensSelect`'s. The rest is what each `where` is checked with. */
-type ProjectRowsOptions = CheckOptions & {
-    keepGrantColumns?: boolean;
-    rules?: readonly Condition[];
-};
-/**
- * Prisma `findMany` args for the rows a lens shows, at its base model: each projected path's
- * visible columns, the relations its declared paths open (a visible relation off them, its columns
- * only), the relations `rules` read past them (opened as declared), and the columns every `where`
- * on the way reads. A to-many relation carries its visit's grants compiled as its `where`, so
- * related rows come pre-narrowed, unless a grant reads that list (it reads it whole); a to-one relation can't (Prisma
- * takes no `where` there), so `projectRows` drops one its grant hides. The root's own grants are the
- * query's `where`: `toPrisma(rule, { lens })`. Bridges are not selected. A relation grant that needs
- * a counting step throws.
- */
-declare const toLensSelect: (lensOrNarrowing: Lens | LensNarrowing, { rules, ...options }?: LensSelectOptions) => {
-    select: LensSelect;
-};
-/**
- * Rows cut to what a lens shows, recursively from its base model: hidden columns and relations
- * removed, and every row a visit's `where` hides gone — a root or list row dropped, a to-one row
- * null. `keepGrantColumns` also keeps the columns those `where`s read (hidden or not), and a hidden to-one row, or a hidden row of a list a grant
- * reads, as those columns alone, so a later `check(narrowRule(rule, lens), row)` re-tests the
- * grants as the database does — for the rules passed in `rules`, or ones reading only the declared
- * paths. Its output carries hidden values: it's for that re-check, never for
- * a viewer. The rest of `options` is what each
- * `where` is checked with (`now`, `bindings`). Plain JSON in and out; the input is not mutated.
- */
-declare const projectRows: (lensOrNarrowing: Lens | LensNarrowing, rows: readonly Row[], { keepGrantColumns, rules, ...options }?: ProjectRowsOptions) => Row[];
-
+/** A narrowing the lens refuses to apply: a grant validateNarrowing reports, met at runtime. */
+declare class LensRefusal extends Error {
+    readonly code: string;
+    name: string;
+    constructor(message: string, code: string);
+}
 type LensPathHop = {
     field: string;
     entry: FieldMapEntry;
@@ -776,9 +769,10 @@ type LensPathHop = {
 };
 /**
  * Where a dotted path lands through the lens, hop by hop. `hidden` is a field the model has but
- * the narrowing does not expose at this visit; `missing` is a field the model does not have (or a
- * model the map does not have); `pastScalar` is a segment after a scalar. A path that continues
- * below a Json column resolves at the column with the remainder in `jsonSubPath`.
+ * the narrowing does not expose at this visit — a column it doesn't keep, or a relation it doesn't
+ * turn on (or omits); `missing` is a field the model does not have (or a model the map does not
+ * have); `pastScalar` is a segment after a scalar. A path that continues below a Json column
+ * resolves at the column with the remainder in `jsonSubPath`.
  */
 type LensPathResolution = {
     outcome: 'resolved';
@@ -825,6 +819,52 @@ type SourceValues = {
 type ProjectLensOptions = {
     sourceValues?: readonly SourceValues[];
 };
+/**
+ * One visit as `projectLens` (by path) gives it, resolved on demand: `relationPath` is the dotted
+ * relation path from the lens anchor (`''` for the anchor). Null when a relation on it isn't shown
+ * there — off, omitted, or outside the model-default tree. Nothing is
+ * enumerated, so it is cheap on any schema.
+ */
+declare const lensVisit: (lensOrNarrowing: Lens | LensNarrowing, relationPath: string, opts?: ProjectLensOptions) => ProjectedVisit | null;
+
+/** A Prisma `select` tree: a column, or a relation with its own `select` and, to-many, `where`. */
+type LensSelect = {
+    [field: string]: true | LensRelationSelect;
+};
+type LensRelationSelect = {
+    select?: LensSelect;
+    where?: PrismaWhere;
+};
+/** What a grant's compile reads: the clock, never a schema (the lens is it). */
+type LensSelectOptions = Omit<ToPrismaOptions, 'map' | 'mapName' | 'model' | 'lens'>;
+/** `keepGrantColumns`: keep the columns the lens's `where`s read, though it hides them. The rest is
+ *  what each `where` is checked with. */
+type ProjectRowsOptions = CheckOptions & {
+    keepGrantColumns?: boolean;
+};
+/**
+ * Prisma `findMany` args for the rows a lens shows, at its base model: each shown visit's visible
+ * columns and the relations turned on there (one that is off is not fetched), and the
+ * columns every `where` on the way reads, through any relation. A to-many relation carries its visit's grants compiled as its `where`, so
+ * related rows come pre-narrowed, unless a grant reads that list (it reads it whole); a to-one relation can't (Prisma
+ * takes no `where` there), so `projectRows` drops one its grant hides. The root's own grants are the
+ * query's `where`: `toPrisma(rule, { lens })`. Bridges are not selected. A to-many relation's grant
+ * that needs a counting step, or has a window toPrisma can't compile, is refused before anything
+ * compiles.
+ */
+declare const toLensSelect: (lensOrNarrowing: Lens | LensNarrowing, options?: LensSelectOptions) => {
+    select: LensSelect;
+};
+/**
+ * Rows cut to what a lens shows, recursively from its base model: hidden columns, and relations
+ * hidden or off, removed, and every row a visit's `where` hides gone — a root or list row dropped, a to-one row
+ * null. `keepGrantColumns` also keeps the columns those `where`s read (hidden or not), and a hidden to-one row, or a hidden row of a list a grant
+ * reads, as those columns alone, so a later `check(narrowRule(rule, lens), row)` re-tests the
+ * grants as the database does for any rule the lens admits. Its output carries hidden values: it's for that re-check, never for
+ * a viewer. The rest of `options` is what each
+ * `where` is checked with (`now`, `bindings`). Plain JSON in and out; the input is not mutated.
+ */
+declare const projectRows: (lensOrNarrowing: Lens | LensNarrowing, rows: readonly Row[], { keepGrantColumns, ...options }?: ProjectRowsOptions) => Row[];
 
 /** Prisma `select` shape — nested for a grouped source's relation path. */
 type SourceSelect = {
@@ -834,8 +874,10 @@ type SourceSelect = {
 };
 type SourcePrismaQuery = {
     model: string;
-    /** Absent for grouped sources — DISTINCT on the value column alone would collapse
-     * same-value rows across groups; dedup happens in `materializeSourceQuery`. */
+    /** The value column, and a sibling label column: one row per value and label, so the least
+     * label is there for `materializeSourceQuery` to pick. Absent for grouped sources and a dotted
+     * label — DISTINCT on columns alone would collapse rows across groups or labels; dedup happens
+     * in `materializeSourceQuery`. */
     distinct?: string[];
     select: SourceSelect;
     where: PrismaWhere;
@@ -857,15 +899,30 @@ type SourceQuery = {
     field: string;
     /** Co-selected as each value's display label (from a SourceSpec's `label`): a sibling
      * column, or a dotted to-one path like a groupBy axis — then selected nested in prisma
-     * and aliased `__label` in sql. */
+     * and aliased `__label` in sql. Across a bridge it is not selected: it is read from the far side
+     * the caller loads onto each candidate row. */
     label?: string;
     /** Option-partition axes (from a SourceSpec's `groupBy`, normalized); each axis
-     * column is selected nested in prisma and aliased `__group_i` in sql. */
+     * column is selected nested in prisma and aliased `__group_i` in sql — save one across a
+     * bridge, read from the far side as a label across one is. */
     groupBy?: string[];
     composedWhere: Condition;
     prisma: SourcePrismaQuery;
     sql: SourceSqlQuery;
-};
+    /** Present when the source reads across a bridge (its where, a grant carried across one, its
+     * label or an axis); absent otherwise. **If `recheck` is present, the query's rows are
+     * candidates, not options:** a database holds one side of a bridge, so the query folds what
+     * reads across it to TRUE and over-fetches — it never misses an option, but may return more.
+     * `recheck` is the condition the database couldn't decide (the conjuncts of `composedWhere` that
+     * read across a bridge; `true` when only the label or an axis does). The query selects the local
+     * columns `recheck` reads and each bridge's local `on` key; load the far side onto each candidate
+     * row under its bridge field (the `indexBridges` shape) and pass the rows to
+     * `materializeSourceQuery(query, rows, { lens })`, which re-checks them and reads the label and
+     * axes across the bridge from the far side. */
+    recheck?: Condition;
+};
+/** What a source query's compile reads besides the lens: the clock, as the compilers take it. */
+type SourceQueryOptions = DateConfig;
 /**
  * Compile a DISTINCT(value) query — Prisma and SQL — per sourced field across
  * the projected lens. The WHERE is the field's composed eligibility: the model's
@@ -873,15 +930,21 @@ type SourceQuery = {
  * where(s), the guards of the relations they cross and any allowed values. A
  * `from: 'mapDefaults'` source reads the model's own source and carries no grant from
  * its layer on. The app runs these (with its own client) to materialize each field's
- * option set — feed the fetched rows to `materializeSourceQuery`.
+ * option set — feed the fetched rows to `materializeSourceQuery`. `options` is the clock a
+ * relative date in the where compiles with (`now` required for one, as for any compile). A
+ * source that reads across a bridge gets an over-fetching query and a `recheck` (see
+ * `SourceQuery`): its rows are candidates, not options.
  */
-declare const toSourceQueries: (lensOrNarrowing: Lens | LensNarrowing) => SourceQuery[];
+declare const toSourceQueries: (lensOrNarrowing: Lens | LensNarrowing, options?: SourceQueryOptions) => SourceQuery[];
 
 /** Which executor produced the rows — the caller always knows; never guessed. */
 type SourceRowShape = 'prisma' | 'sql';
-/** `rowShape`: how the rows came back — nested Prisma rows (the default) or flat SQL rows. */
-type MaterializeSourceQueryOptions = {
+/** `rowShape`: how the rows came back — nested Prisma rows (the default) or flat SQL rows.
+ *  `lens`: the lens the query was compiled from, required for a query with a `recheck` — it says
+ *  what each far side must hold. The rest is the clock and bindings the re-check runs with. */
+type MaterializeSourceQueryOptions = CheckOptions & {
     rowShape?: SourceRowShape;
+    lens?: Lens | LensNarrowing;
 };
 /**
  * Materialize one compiled `SourceQuery`'s fetched rows into its `SourceValues` —
@@ -890,6 +953,12 @@ type MaterializeSourceQueryOptions = {
  * (and a dotted `label`) as related objects; sql rows carry them flat under the
  * statement's `__group_i` / `__label` aliases. Grouped queries fetch without
  * DISTINCT, so dedup per (groups, value) happens here.
+ *
+ * A query with a `recheck` (a source across a bridge) returned candidates: each row must hold the
+ * far side inline under its bridge field — one row or a list as the bridge names it, with every
+ * key the re-check, the label and the axes read across it — or this throws a `UsageError` rather
+ * than offer a wrong set. A candidate offers its value only if `check(recheck, row, options)`
+ * holds; a label or axis across the bridge is read from the far side, in either row shape.
  */
 declare const materializeSourceQuery: (query: SourceQuery, rows: readonly Row[], opts?: MaterializeSourceQueryOptions) => SourceValues;
 
@@ -897,21 +966,26 @@ declare const materializeSourceQuery: (query: SourceQuery, rows: readonly Row[],
  * Materialize each sourced field's option set from an already-fetched collection —
  * the in-memory executor of `sources` declarations, alongside `toSourceQueries`
  * (which compiles the same declarations to DISTINCT queries for a DB). Rows are
- * the collection fetched under the lens (relations inline). Each row must meet the field's
- * eligibility — its source `where`, the grants above it, the guards of the relations it crosses
- * and any allowed values — evaluated with `check()` (`options` feeds `{bind}` clauses); its own
- * visit's `where` is not re-applied, since the rows were fetched under it. Scalar-list fields
- * contribute one option per element, labels take the first non-null value of the label column
- * (a sibling, or a dotted to-one path read through the nested rows), and sorting is
- * numeric-aware in a fixed locale. Feed the result to `projectLens` as `{ sourceValues }`. A
- * `from: 'mapDefaults'` source throws: a fetched collection can't hold unlinked rows.
+ * the collection the lens fetches — `toLensSelect`'s rows as fetched, or as
+ * `projectRows(…, { keepGrantColumns: true })` keeps them; a viewer's projection drops what
+ * the sources read, and a row lacking a key a source or a grant on its path reads throws. The
+ * path is walked down the rows, each level's grants met, and each row it reaches must meet its
+ * visit's grants, its source `where` narrowed as a rule, the guards of the relations its label
+ * and axes cross and any allowed values — evaluated with `check()` (`options`: `now`,
+ * `bindings`), so it offers what the database does. Scalar-list fields contribute one option per
+ * element, a value takes its least label (a sibling column, or a dotted to-one path read through
+ * the nested rows), and sorting is numeric-aware in a fixed locale. Feed the result to
+ * `projectLens` as `{ sourceValues }`. A source across a bridge is materialized from rows that
+ * hold the far side inline under its bridge field (the fetch selects no bridge); a
+ * `from: 'mapDefaults'` source throws: a fetched collection can't hold unlinked rows — query it.
  */
 declare const materializeSources: (lensOrNarrowing: Lens | LensNarrowing, rows: readonly Row[], options?: CheckOptions) => SourceValues[];
 
-/** A narrowing layer checked against the layers above it: it names only what they still show and
- *  only narrows. Each problem is an issue with a code (`not_in_lens`, `not_visible`,
- *  `conflicting_selection`, `wrong_kind`, `value_not_allowed`, `invalid_source`,
- *  `invalid_binding`, or the lens gate's for a `where`). */
+/** A narrowing layer checked against the layers above it: it names only what they still show —
+ *  a relation it turns on or narrows included, unless it is the first narrowing over the base
+ *  lens — and only narrows. `picks` names columns only. Each problem is an issue with a code
+ *  (`not_in_lens`, `not_visible`, `conflicting_selection`, `wrong_kind`, `value_not_allowed`,
+ *  `invalid_source`, `invalid_binding`, or the lens gate's for a `where`). */
 declare const validateNarrowing: (narrowing: LensNarrowing) => ValidationResult;
 /** `validateNarrowing`, throwing its issues. */
 declare const assertValidNarrowing: (narrowing: LensNarrowing) => void;
@@ -943,7 +1017,7 @@ type LensValue = {
 };
 /**
  * One value off a row, as the lens shows it: the path walked as `validateRuleInLens` walks a
- * field (a hidden, missing or past-scalar segment is refused), each related row checked against
+ * field (a hidden segment — a column it doesn't keep, a relation it doesn't turn on — or a missing or past-scalar one is refused), each related row checked against
  * its visit's grants, the row itself included (a row a grant hides, or a missing one, reads `null`), and only the row's own
  * properties read, into a Json column too. A path ending on a relation, or crossing a list, names
  * rows rather than a value and is refused. `options` is what each grant is checked with.
@@ -1004,11 +1078,15 @@ declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<
  * Execute a Prisma query plan produced by toPrisma().
  *
  * The plan is a flat list of steps where all but the last are `groupBy` steps
- * that feed results (via { __step: N } sentinels) into subsequent steps.
- * The final step is always a `where` step whose resolved WHERE clause is returned.
+ * that feed results (via { __step: N } references) into subsequent steps.
+ * The final step is always a `where` step whose resolved WHERE clause is returned. A column
+ * compared with a column is a `{ __field }` reference resolved to the delegate's field reference
+ * (`prisma.user.fields.age`). Each step's `refs` record where its references sit, and only those
+ * locations are resolved: a value shaped like a reference anywhere else stays data. Read a plan's
+ * where only through here — Prisma rejects an unresolved reference.
  *
  * @param result         - Result from toPrisma()
- * @param prismaDelegate - Map of camelCase model name → Prisma delegate
+ * @param prismaDelegate - Map of camelCase model name → Prisma delegate (or the client)
  *                         e.g. { post: prisma.post, user: prisma.user }
  * @returns The resolved WHERE clause (ready for findMany/count/etc.)
  *
@@ -1017,7 +1095,7 @@ declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<
  * const where = await executePrismaPlan(plan, { post: prisma.post });
  * await prisma.user.findMany({ where });
  */
-declare const executePrismaPlan: (plan: ToPrismaResult, prismaDelegate: Record<string, Record<string, (...args: unknown[]) => unknown>>) => Promise<Record<string, unknown>>;
+declare const executePrismaPlan: (plan: ToPrismaResult, prismaDelegate: Record<string, object>) => Promise<Record<string, unknown>>;
 
 /**
  * Compile a condition to a Prisma query plan: `steps`, any groupBy steps (counts and relation
@@ -1035,7 +1113,7 @@ declare const executePrismaPlan: (plan: ToPrismaResult, prismaDelegate: Record<s
  * const where = await executePrismaPlan(plan, prisma);
  * await prisma.user.findMany({ where });
  *
- * toPrisma(rule, { lens: narrowing, now }); // gated, narrowed (a bare value path read as context), compiled against the base lens
+ * toPrisma(rule, { lens: narrowing, now }); // gated, narrowed, compiled against the base lens
  * ```
  */
 declare const toPrisma: (rule: Condition, compileOptions?: ToPrismaOptions) => ToPrismaResult;
@@ -1054,4 +1132,4 @@ type ToSqlOptions = CompileOptions & {
  *  base lens. */
 declare const toSql: (rule: Condition, compileOptions?: ToSqlOptions) => ToSqlResult;
 
-export { ALL_KINDS, type AggregateMode, type AggregateRule, type All, type Any, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, type CheckData, type CheckOptions, type CompileOptions, type Condition, type DateConfig, type DateExpr, type DateInputOrExpr, type DateInputValue, type DateOffset, DateOperator, type DateRule, type DateRuleValue, type EdgeExpr, type EngineGlobalsState, type EnumNarrowing, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type FuzzyConfig, type GroupByStep, type IfThenElse, type Lens, type LensNarrowing, type LensPathHop, type LensPathResolution, type LensRelationSelect, type LensSelect, type LensSelectOptions, type LensValue, type ListBindingsOptions, type Magnitude, type MaterializeSourceQueryOptions, type ModelDefaultNarrowing, type ModelEntry, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, type NumberOffset, Operator, type OperatorFamily, type OrderBy, type OrderedRuleValue, type PathProjection, type PeriodExpr, type PeriodUnit, type PrismaProvider, type PrismaStep, type PrismaWhere, type ProjectLensOptions, type ProjectRowsOptions, type ProjectedVisit, type RelativeUnits, type RollingExpr, type Row, type Rule, type RuleDescription, type RuleScalar, type RuleSourceDescription, RuleTarget, type RuleValue, type ScopeOutOfBounds, type ScopeRef, type ScopedRef, type SortDir, type SourceEntry, type SourceOption, type SourcePrismaQuery, type SourceQuery, type SourceRowShape, type SourceSelect, type SourceSpec, type SourceSqlQuery, type SourceValues, type StepRef, type StoredLens, type StrictAggregateRule, type StrictAll, type StrictAny, type StrictArrayCountRule, type StrictArrayPredicateRule, type StrictArrayPresenceRule, type StrictArrayRule, type StrictCondition, type StrictContainsRule, type StrictDateComparisonRule, type StrictDateDayRule, type StrictDateRangeRule, type StrictDateRule, type StrictEqualityRule, type StrictIfThenElse, type StrictMembershipRule, type StrictOrderedComparisonRule, type StrictPatternRule, type StrictPresenceRule, type StrictRangeRule, type StrictRule, type StrictStringBoundaryRule, type TimeZoneConfig, type ToPrismaOptions, type ToPrismaResult, type ToSqlOptions, type ToSqlResult, type ValidateRuleOptions, type ValidationIssue, type ValidationResult, ValueShape, type ValueSourceFields, type ValueSourceOf, type WeekStart, type WhereStep, type WindowFields, assertValidFieldMaps, assertValidNarrowing, assertValidRule, bindLens, bindRule, check, coerceRule, composeLens, createLens, describeRule, describeRuleSources, engineGlobals, executePrismaPlan, getAggregateOperators, getArrayOperators, getLensRoot, getOperatorsForKind, getValueShape, indexBridges, listBindings, listLensBindings, materializeSourceQuery, materializeSources, narrowRule, parseScopeRef, projectLens, projectRows, readLensValue, readScopeRef, stitchFieldMaps, storeLens, toLensSelect, toPrisma, toSourceQueries, toSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };
+export { ALL_KINDS, type AggregateMode, type AggregateRule, type All, type Any, ArrayOperator, type ArrayRule, type Bridge, type BridgeCardinality, type BridgeDictionary, type BridgeEndpoint, type CheckData, type CheckOptions, type CompileOptions, type Condition, type DateConfig, type DateExpr, type DateInputOrExpr, type DateInputValue, type DateOffset, DateOperator, type DateRule, type DateRuleValue, type EdgeExpr, type EngineGlobalsState, type EnumNarrowing, FieldKind, type FieldMap, type FieldMapEntry, type FieldMapSet, type FuzzyConfig, type GroupByStep, type IfThenElse, type Lens, type LensNarrowing, type LensPathHop, type LensPathResolution, LensRefusal, type LensRelationSelect, type LensSelect, type LensSelectOptions, type LensValue, type ListBindingsOptions, type Magnitude, type MaterializeSourceQueryOptions, type ModelDefaultNarrowing, type ModelEntry, type ModelNarrowing, NUMERIC_KINDS, type NarrowingDefaults, type NumberOffset, Operator, type OperatorFamily, type OrderBy, type OrderedRuleValue, type PathProjection, type PeriodExpr, type PeriodUnit, type PrismaProvider, type PrismaStep, type PrismaWhere, type ProjectLensOptions, type ProjectRowsOptions, type ProjectedVisit, type RelativeUnits, type RollingExpr, type Row, type Rule, type RuleDescription, type RuleScalar, type RuleSourceDescription, RuleTarget, type RuleValue, type ScopeOutOfBounds, type ScopeRef, type ScopedRef, type SortDir, type SourceEntry, type SourceOption, type SourcePrismaQuery, type SourceQuery, type SourceRowShape, type SourceSelect, type SourceSpec, type SourceSqlQuery, type SourceValues, type StepRef, type StoredLens, type StrictAggregateRule, type StrictAll, type StrictAny, type StrictArrayCountRule, type StrictArrayPredicateRule, type StrictArrayPresenceRule, type StrictArrayRule, type StrictCondition, type StrictContainsRule, type StrictDateComparisonRule, type StrictDateDayRule, type StrictDateRangeRule, type StrictDateRule, type StrictEqualityRule, type StrictIfThenElse, type StrictMembershipRule, type StrictOrderedComparisonRule, type StrictPatternRule, type StrictPresenceRule, type StrictRangeRule, type StrictRule, type StrictStringBoundaryRule, type TimeZoneConfig, type ToPrismaOptions, type ToPrismaResult, type ToSqlOptions, type ToSqlResult, UsageError, type ValidateRuleOptions, type ValidationIssue, type ValidationResult, ValueShape, type ValueSourceFields, type ValueSourceOf, type WeekStart, type WhereStep, type WindowFields, assertValidFieldMaps, assertValidNarrowing, assertValidRule, bindLens, bindRule, check, coerceRule, composeLens, createLens, describeRule, describeRuleSources, engineGlobals, executePrismaPlan, getAggregateOperators, getArrayOperators, getLensRoot, getOperatorsForKind, getValueShape, indexBridges, lensVisit, listBindings, listLensBindings, materializeSourceQuery, materializeSources, narrowRule, parseScopeRef, projectLens, projectRows, readLensValue, readScopeRef, stitchFieldMaps, storeLens, toLensSelect, toPrisma, toSourceQueries, toSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };