@inixiative/json-rules 3.1.0 → 3.2.0

package/dist/index.d.cts

@@ -140,6 +140,107 @@ type FuzzyConfig = {
     maxRatio?: number;
 };
 
+type Lens = FieldMapSet & {
+    mapName: string;
+    model: string;
+};
+/**
+ * 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.
+ * - 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.
+ */
+type ModelDefaultNarrowing = {
+    picks?: string[];
+    omits?: string[];
+    enumPicks?: Record<string, readonly string[]>;
+    enumOmits?: Record<string, readonly string[]>;
+    /**
+     * Row-level filter anchored to this model — "from what you can see, this is true."
+     * Composes via filter-first semantic at every visit of this model.
+     */
+    where?: Condition;
+    /**
+     * Per-field eligibility over THIS model — decorates a field's option picker.
+     * A bare `Condition` is the eligibility `where`: the field's selectable values =
+     * DISTINCT(field) over this model filtered by `where` (plus the model's own
+     * narrowing). A `SourceSpec` adds an optional `label` — a sibling column, or a
+     * dotted to-one path ending on a scalar (like `groupBy`), co-selected as each
+     * value's display label. Referenced-model option sets need no special form: declare
+     * the source at a relation-traversed narrowing node and it compiles over whatever
+     * model that path resolves to. The `where` composes AND-only across layers (general
+     * via `mapDefaults`, path-specific via `root`/`relations`); a later layer's `label` wins.
+     */
+    sources?: Record<string, SourceEntry>;
+};
+/**
+ * A sourced field's eligibility `where` plus an optional display-label column — a
+ * sibling, or a dotted to-one path ending on a scalar, resolved exactly like a
+ * `groupBy` axis — and an optional `groupBy`: a dotted path (to-one hops only, ending
+ * on a scalar) whose value partitions the option set. Grouped options carry `group`;
+ * the classic flat set is the ungrouped case. At least one key is required — `{}` is not a
+ * Condition; the unconstrained spelling is `true`.
+ */
+type SourceSpec = {
+    where: Condition;
+    label?: string;
+    groupBy?: string | string[];
+    from?: never;
+} | {
+    where?: Condition;
+    label: string;
+    groupBy?: string | string[];
+    from?: never;
+} | {
+    where?: Condition;
+    label?: string;
+    groupBy: string | string[];
+    from?: never;
+}
+/** A path source that offers its model's own source — `mapDefaults[map].models[model]
+ *  .sources[field]` for the map and model this path reaches — instead of the rows reachable
+ *  down the path. Its label and axes are the model source's; its `where` can only narrow. */
+ | {
+    from: 'mapDefaults';
+    where?: Condition;
+    label?: never;
+    groupBy?: never;
+};
+/** 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 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. */
+type NarrowingDefaults = {
+    models?: Record<string, ModelDefaultNarrowing>;
+    enums?: Record<string, EnumNarrowing>;
+};
+type LensNarrowing = {
+    parent: Lens | LensNarrowing;
+    /**
+     * Path-specific narrowing anchored at (lens.mapName, lens.model). Descends via
+     * `.relations` and may cross maps through bridge relations.
+     */
+    root?: ModelNarrowing;
+    /**
+     * Per-map applies-everywhere narrowings, keyed by map name. Apply wherever the
+     * named model/enum appears in the visit being resolved.
+     */
+    mapDefaults?: Record<string, NarrowingDefaults>;
+};
+
 declare const FieldKind: {
     readonly String: "String";
     readonly Boolean: "Boolean";
@@ -179,12 +280,17 @@ declare const ValueShape: {
 type ValueShape = (typeof ValueShape)[keyof typeof ValueShape];
 /** Which catalog an operator belongs to — `between` is both a field and a date operator. */
 type OperatorFamily = 'field' | 'date' | 'array';
+/** The operand an operator takes in its family (`between` is a field and a date operator).
+ *  Throws on an operator the family doesn't have. */
 declare const getValueShape: (operator: string, family: OperatorFamily) => ValueShape;
+/** The field and date operators a field kind takes, narrowed to one target when given. */
 declare const getOperatorsForKind: (kind: FieldKind, target?: RuleTarget) => {
     field: Operator[];
     date: DateOperator[];
 };
+/** The array operators, narrowed to one target when given. */
 declare const getArrayOperators: (target?: RuleTarget) => ArrayOperator[];
+/** The comparisons an aggregate rule takes; every target compiles all of them. */
 declare const getAggregateOperators: () => readonly Operator[];
 
 type OperatorValues = typeof Operator;
@@ -403,11 +509,14 @@ 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 `$` refs read, and the clock. */
+ *  model the rule reads, the context bare `path` refs read, 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 = {
     map?: FieldMap | FieldMapSet;
     mapName?: string;
     model?: string;
+    lens?: Lens | LensNarrowing;
     context?: Row;
 } & DateConfig;
 /** What check() evaluates: one row, or a root array of them. */
@@ -434,6 +543,9 @@ 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
+ *  `all` / `any` only): `true` when it holds, else the failing rule's error text. Throws on a
+ *  structurally invalid rule or malformed data. */
 declare const check: <TData extends CheckData>(conditions: Condition, data: TData, options?: CheckOptions) => boolean | string;
 
 type PrismaProvider = 'postgresql' | 'mysql' | 'sqlite' | 'sqlserver' | 'cockroachdb' | 'mongodb';
@@ -454,6 +566,8 @@ type EngineGlobalsState = {
 type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
+/** Process-wide defaults, read and written by dotted path (`string.caseInsensitive`,
+ *  `string.fuzzy`, `prismaOptions.datasource.provider`, `prismaOptions.anyNull`). */
 declare const engineGlobals: {
     set: (path: string, value: unknown) => void;
     get: (path: string) => unknown;
@@ -464,8 +578,14 @@ declare const engineGlobals: {
 type BridgeDictionary = Record<string, // map name
 Record<string, // model name
 Record<string, Record<string, Row | Row[]>>>>;
+/** Raw rows (keyed by endpoint, `<fieldMap>:<Model>`) indexed for embedding under bridge keys:
+ *  map → model → `on` field → its value → the row, or the rows on a oneToMany's "many" side.
+ *  Throws on a duplicate value where a side must be unique. */
 declare const indexBridges: (set: FieldMapSet, rawData: Record<string, Row[]>) => BridgeDictionary;
 
+/** A copy of the set where each bridge's endpoint models gain a `kind: 'bridge'` field named
+ *  after the other endpoint (`<fieldMap>:<Model>`). Throws on a missing endpoint or `on` field, a
+ *  self-bridge, or a bridge stitched twice. */
 declare const stitchFieldMaps: (set: FieldMapSet) => FieldMapSet;
 
 type ValidationIssue = {
@@ -481,114 +601,17 @@ type ValidationResult = {
 type ValidateRuleOptions = {
     target?: RuleTarget;
 };
+/** A rule's shape checked without data: every node well formed, and runnable on `target`
+ *  (operators, windows, scope refs, patterns). */
 declare const validateRule: (condition: unknown, options?: ValidateRuleOptions) => ValidationResult;
+/** `validateRule`, throwing its issues; narrows the input to a `Condition`. */
 declare const assertValidRule: (condition: unknown, options?: ValidateRuleOptions) => asserts condition is Condition;
 
 /** Field names are plain identifiers: `.` walks a path and `:` names a bridge target. */
 declare const validateFieldMaps: (set: FieldMapSet) => ValidationResult;
+/** `validateFieldMaps`, throwing its issues. */
 declare const assertValidFieldMaps: (set: FieldMapSet) => void;
 
-type Lens = FieldMapSet & {
-    mapName: string;
-    model: string;
-};
-/**
- * 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.
- * - 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.
- */
-type ModelDefaultNarrowing = {
-    picks?: string[];
-    omits?: string[];
-    enumPicks?: Record<string, readonly string[]>;
-    enumOmits?: Record<string, readonly string[]>;
-    /**
-     * Row-level filter anchored to this model — "from what you can see, this is true."
-     * Composes via filter-first semantic at every visit of this model.
-     */
-    where?: Condition;
-    /**
-     * Per-field eligibility over THIS model — decorates a field's option picker.
-     * A bare `Condition` is the eligibility `where`: the field's selectable values =
-     * DISTINCT(field) over this model filtered by `where` (plus the model's own
-     * narrowing). A `SourceSpec` adds an optional `label` — a sibling column, or a
-     * dotted to-one path ending on a scalar (like `groupBy`), co-selected as each
-     * value's display label. Referenced-model option sets need no special form: declare
-     * the source at a relation-traversed narrowing node and it compiles over whatever
-     * model that path resolves to. The `where` composes AND-only across layers (general
-     * via `mapDefaults`, path-specific via `root`/`relations`); a later layer's `label` wins.
-     */
-    sources?: Record<string, SourceEntry>;
-};
-/**
- * A sourced field's eligibility `where` plus an optional display-label column — a
- * sibling, or a dotted to-one path ending on a scalar, resolved exactly like a
- * `groupBy` axis — and an optional `groupBy`: a dotted path (to-one hops only, ending
- * on a scalar) whose value partitions the option set. Grouped options carry `group`;
- * the classic flat set is the ungrouped case. At least one key is required — `{}` is not a
- * Condition; the unconstrained spelling is `true`.
- */
-type SourceSpec = {
-    where: Condition;
-    label?: string;
-    groupBy?: string | string[];
-    from?: never;
-} | {
-    where?: Condition;
-    label: string;
-    groupBy?: string | string[];
-    from?: never;
-} | {
-    where?: Condition;
-    label?: string;
-    groupBy: string | string[];
-    from?: never;
-}
-/** A path source that offers its model's own source — `mapDefaults[map].models[model]
- *  .sources[field]` for the map and model this path reaches — instead of the rows reachable
- *  down the path. Its label and axes are the model source's; its `where` can only narrow. */
- | {
-    from: 'mapDefaults';
-    where?: Condition;
-    label?: never;
-    groupBy?: never;
-};
-/** 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 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. */
-type NarrowingDefaults = {
-    models?: Record<string, ModelDefaultNarrowing>;
-    enums?: Record<string, EnumNarrowing>;
-};
-type LensNarrowing = {
-    parent: Lens | LensNarrowing;
-    /**
-     * Path-specific narrowing anchored at (lens.mapName, lens.model). Descends via
-     * `.relations` and may cross maps through bridge relations.
-     */
-    root?: ModelNarrowing;
-    /**
-     * Per-map applies-everywhere narrowings, keyed by map name. Apply wherever the
-     * named model/enum appears in the visit being resolved.
-     */
-    mapDefaults?: Record<string, NarrowingDefaults>;
-};
-
 /**
  * Every bind name a lens (its whole narrowing chain) needs supplied to execute —
  * `bindOptional` tokens are not required (unsupplied, they resolve to null).
@@ -600,14 +623,21 @@ type LensNarrowing = {
 declare const listLensBindings: (lensOrNarrowing: Lens | LensNarrowing) => string[];
 /**
  * Preprocess a lens: resolve every `{ bind }` token the map covers in the chain's
- * `where`/`sources`, returning a structurally-new lens with concrete conditions.
- * Partial — uncovered tokens stay, so stages bind progressively. Once resolved,
- * `narrowRule` / `toPrisma` / `toSql` / `toSourceQueries` / `projectPaths` consume the
- * lens unchanged: a bind needs nothing new downstream. `parent:name` draws the same
- * value as the ancestor's `name`. Does not mutate the input.
+ * `where`/`sources`, returning a structurally-new lens of the same form with concrete
+ * conditions. Partial — uncovered tokens stay, so stages bind progressively. Once resolved, `narrowRule` / `toPrisma` / `toSql` / `toSourceQueries` / `projectLens` consume the
+ * lens unchanged. `parent:name` draws the same value as the ancestor's `name`. Does not mutate
+ * the input.
  */
-declare const bindLens: (lensOrNarrowing: Lens | LensNarrowing, bindings: Record<string, RuleValue>) => Lens | LensNarrowing;
+declare const bindLens: <T extends Lens | LensNarrowing>(lensOrNarrowing: T, bindings: Record<string, RuleValue>) => T;
+
+/** The base lens a narrowing chain is rooted at; a lens is its own. Throws on a cyclic chain. */
+declare const getLensRoot: (x: Lens | LensNarrowing) => Lens;
 
+/** Stamp `coerceType` onto every field rule from the lens's field map: the rule carries its
+ *  coercion; `check()` never infers types from values. A relation node's condition / filter stamp
+ *  against the relation's model; below a Json boundary the kind is undeclared, so nothing is
+ *  stamped. A date rule, an aggregate comparison (numeric by contract) and a rule that already
+ *  names its coercion are left as they are. */
 declare const coerceRule: (condition: Condition, lensOrNarrowing: Lens | LensNarrowing) => Condition;
 
 /** A lens over field maps, its bridges stitched into the maps as fields. */
@@ -620,6 +650,9 @@ type RuleDescription = {
     /** What the lens refuses in the rule — validateRuleInLens's issues. */
     errors: ValidationIssue[];
 };
+/** A rule under a lens, for routing and UX: the maps it reads, whether it crosses a bridge, the
+ *  targets `validateRule` passes it for (a bridge leaves `check` alone), and the lens gate's
+ *  issues. `validateRuleInLens` stays the gate. */
 declare const describeRule: (rule: Condition, lensOrNarrowing: Lens | LensNarrowing) => RuleDescription;
 
 /**
@@ -660,6 +693,79 @@ type RuleSourceDescription = {
  */
 declare const describeRuleSources: (rule: Condition, lensOrNarrowing: Lens | LensNarrowing) => RuleSourceDescription[];
 
+type PrismaWhere = Record<string, unknown>;
+type StepRef = {
+    __step: number;
+};
+type GroupByStep = {
+    operation: 'groupBy';
+    model: string;
+    args: {
+        by: string[];
+        where: Record<string, unknown>;
+        having: Record<string, unknown>;
+    };
+    extract: string;
+};
+type WhereStep = {
+    operation: 'where';
+    where: Record<string, unknown>;
+};
+type PrismaStep = GroupByStep | WhereStep;
+type ToPrismaResult = {
+    steps: PrismaStep[];
+};
+type ToPrismaOptions = CompileOptions & {
+    datasource?: {
+        provider?: PrismaProvider;
+    };
+};
+
+/** 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[];
+
 type LensPathHop = {
     field: string;
     entry: FieldMapEntry;
@@ -720,34 +826,6 @@ type ProjectLensOptions = {
     sourceValues?: readonly SourceValues[];
 };
 
-type PrismaWhere = Record<string, unknown>;
-type StepRef = {
-    __step: number;
-};
-type GroupByStep = {
-    operation: 'groupBy';
-    model: string;
-    args: {
-        by: string[];
-        where: Record<string, unknown>;
-        having: Record<string, unknown>;
-    };
-    extract: string;
-};
-type WhereStep = {
-    operation: 'where';
-    where: Record<string, unknown>;
-};
-type PrismaStep = GroupByStep | WhereStep;
-type ToPrismaResult = {
-    steps: PrismaStep[];
-};
-type ToPrismaOptions = CompileOptions & {
-    datasource?: {
-        provider?: PrismaProvider;
-    };
-};
-
 /** Prisma `select` shape — nested for a grouped source's relation path. */
 type SourceSelect = {
     [field: string]: true | {
@@ -791,14 +869,20 @@ type SourceQuery = {
 /**
  * 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
- * own narrowing at that path AND its source where(s). The app runs these (with
- * its own client) to materialize each field's option set — feed the fetched rows
- * to `materializeSourceQuery`.
+ * own narrowing at that path, the grants above it carried down the path, its source
+ * 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`.
  */
 declare const toSourceQueries: (lensOrNarrowing: Lens | LensNarrowing) => 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?: SourceRowShape;
+};
 /**
  * Materialize one compiled `SourceQuery`'s fetched rows into its `SourceValues` —
  * the executor-side counterpart of `toSourceQueries`, so apps never hand-map rows.
@@ -807,10 +891,6 @@ type SourceRowShape = 'prisma' | 'sql';
  * statement's `__group_i` / `__label` aliases. Grouped queries fetch without
  * DISTINCT, so dedup per (groups, value) happens here.
  */
-/** `rowShape`: how the rows came back — nested Prisma rows (the default) or flat SQL rows. */
-type MaterializeSourceQueryOptions = {
-    rowShape?: SourceRowShape;
-};
 declare const materializeSourceQuery: (query: SourceQuery, rows: readonly Row[], opts?: MaterializeSourceQueryOptions) => SourceValues;
 
 /**
@@ -818,18 +898,26 @@ declare const materializeSourceQuery: (query: SourceQuery, rows: readonly Row[],
  * 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 as `toSourceQueries` composes it — 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). Scalar-list fields contribute one
- * option per element, labels take the first non-null value of the label column
+ * 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 }`.
+ * 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.
  */
 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`). */
 declare const validateNarrowing: (narrowing: LensNarrowing) => ValidationResult;
+/** `validateNarrowing`, throwing its issues. */
 declare const assertValidNarrowing: (narrowing: LensNarrowing) => void;
 
+/** A rule with the lens's grants (`where`s) injected at their anchors: the root's around it, each
+ *  relation's where the rule descends into it — under an `all`, into its window `filter`. */
 declare const narrowRule: (rule: Condition, lensOrNarrowing: Lens | LensNarrowing) => Condition;
 
 /**
@@ -870,7 +958,7 @@ declare const validateRuleInLens: (rule: Condition, lensOrNarrowing: Lens | Lens
 
 /**
  * Resolve one dotted path through a lens, hop by hop, verifying as it walks: every hop is checked
- * against the narrowing at that visit, so a relation the narrowing dropped is `hidden`, a column the
+ * against the narrowing at that visit, so a field the narrowing hides is `hidden`, a field the
  * model lacks is `missing`, and a segment past a scalar is `pastScalar`. This is the walk
  * `validateRuleInLens` gates a rule's field with, exposed for consumers that resolve paths of their
  * own (template tokens, loop bindings, presence guards).
@@ -881,6 +969,7 @@ type ScopeRef = {
     depth: number;
     path: string;
 };
+/** A `$`-prefixed ref's depth (one per `$`) and the path after it; `null` for a bare ref. */
 declare const parseScopeRef: (ref: string) => ScopeRef | null;
 type ScopedRef<S> = {
     scope: S;
@@ -889,6 +978,9 @@ type ScopedRef<S> = {
 type ScopeOutOfBounds = {
     outOfBounds: string;
 };
+/** The scope a ref names in a stack (innermost last) and the path left to read in it: a bare
+ *  ref and `$.` read the innermost, `$$.` the one above it, … A ref deeper than the stack comes
+ *  back as `{ outOfBounds }` with its message; it never throws. */
 declare const readScopeRef: <S>(ref: string, scopes: readonly S[]) => ScopedRef<S> | ScopeOutOfBounds;
 
 /**
@@ -912,7 +1004,8 @@ declare const executePrismaPlan: (plan: ToPrismaResult, prismaDelegate: Record<s
 
 /**
  * Compile a condition to a Prisma query plan: `steps`, any groupBy steps (counts and relation
- * aggregates, which need `{ map, model }`) and then the final `where`. Run a plan with
+ * aggregates, which need `{ map, model }` or `{ lens }`) and then the final `where`. With `lens`,
+ * the rule compiles narrowed by it, against its base lens. Run a plan with
  * `executePrismaPlan(plan, client)` to resolve step refs; a single-step plan's `where` is its
  * last step's.
  *
@@ -924,9 +1017,11 @@ declare const executePrismaPlan: (plan: ToPrismaResult, prismaDelegate: Record<s
  * const plan = toPrisma({ field: 'posts', arrayOperator: 'atLeast', count: 3, condition }, { map, model: 'User' });
  * const where = await executePrismaPlan(plan, prisma);
  * await prisma.user.findMany({ where });
+ *
+ * toPrisma(rule, { lens: narrowing, now }); // toPrisma(narrowRule(rule, narrowing), { map: base, mapName, model, now })
  * ```
  */
-declare const toPrisma: (condition: Condition, options?: ToPrismaOptions) => ToPrismaResult;
+declare const toPrisma: (rule: Condition, compileOptions?: ToPrismaOptions) => ToPrismaResult;
 
 type ToSqlResult = {
     sql: string;
@@ -938,6 +1033,8 @@ type ToSqlOptions = CompileOptions & {
     alias?: string;
 };
 
-declare const toSql: (condition: Condition, options?: ToSqlOptions) => ToSqlResult;
+/** Compile a condition to a SQL WHERE. With `lens`, the rule compiles narrowed by it, against its
+ *  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 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 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, getOperatorsForKind, getValueShape, indexBridges, listBindings, listLensBindings, materializeSourceQuery, materializeSources, narrowRule, parseScopeRef, projectLens, readScopeRef, stitchFieldMaps, storeLens, 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, type LensRelationSelect, type LensSelect, type LensSelectOptions, 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, readScopeRef, stitchFieldMaps, storeLens, toLensSelect, toPrisma, toSourceQueries, toSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };