@inixiative/json-rules 3.4.0 → 3.5.0

package/dist/index.d.cts

@@ -183,7 +183,7 @@ type ModelDefaultNarrowing = {
      * 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
+     * once, at its nearest reach; reach it another way by spelling the path under `root`. The first narrowing's clamps (`where`) may read any
      * relation; a later layer's only what its parent shows.
      */
     relations?: Record<string, ModelNarrowing>;
@@ -753,7 +753,7 @@ type ToPrismaOptions = CompileOptions & {
     };
 };
 
-/** A narrowing the lens refuses to apply: a grant validateNarrowing reports, met at runtime. */
+/** A narrowing the lens refuses to apply: a clamp validateNarrowing reports, met at runtime. */
 declare class LensRefusal extends Error {
     readonly code: string;
     name: string;
@@ -835,20 +835,20 @@ type LensRelationSelect = {
     select?: LensSelect;
     where?: PrismaWhere;
 };
-/** What a grant's compile reads: the clock, never a schema (the lens is it). */
+/** What a clamp'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
+/** `keepClampColumns`: 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;
+    keepClampColumns?: 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
+ * columns every `where` on the way reads, through any relation. A to-many relation carries its visit's clamps compiled as its `where`, so
+ * related rows come pre-narrowed, unless a clamp reads that list (it reads it whole); a to-one relation can't (Prisma
+ * takes no `where` there), so `projectRows` drops one its clamp hides. The root's own clamps are the
+ * query's `where`: `toPrisma(rule, { lens })`. Bridges are not selected. A to-many relation's clamp
  * that needs a counting step, or has a window toPrisma can't compile, is refused before anything
  * compiles.
  */
@@ -858,13 +858,13 @@ declare const toLensSelect: (lensOrNarrowing: Lens | LensNarrowing, options?: Le
 /**
  * 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
+ * null. `keepClampColumns` 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 clamp
  * 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
+ * clamps 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[];
+declare const projectRows: (lensOrNarrowing: Lens | LensNarrowing, rows: readonly Row[], { keepClampColumns, ...options }?: ProjectRowsOptions) => Row[];
 
 /** Prisma `select` shape — nested for a grouped source's relation path. */
 type SourceSelect = {
@@ -899,38 +899,52 @@ 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;
-    /** Null, with `sql.sql` null and `sql.error` saying why, when the composed where crosses a
-     * bridge: a database holds one side of it only, so no query offers the right set — materialize
-     * it with `materializeSources` over rows that hold both sides. */
-    prisma: SourcePrismaQuery | null;
+    prisma: SourcePrismaQuery;
     sql: SourceSqlQuery;
+    /** Present when the source reads across a bridge (its where, a clamp 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
- * own narrowing at that path, the grants above it carried down the path, its source
+ * own narrowing at that path, the clamps 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
+ * `from: 'mapDefaults'` source reads the model's own source and carries no clamp 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`. `options` is the clock a
  * relative date in the where compiles with (`now` required for one, as for any compile). A
- * where across a bridge has no query (`prisma` null; see `SourceQuery`).
+ * 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, 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` —
@@ -939,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;
 
@@ -947,18 +967,17 @@ 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 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
+ * `projectRows(…, { keepClampColumns: true })` keeps them; a viewer's projection drops what
+ * the sources read, and a row lacking a key a source or a clamp on its path reads throws. The
+ * path is walked down the rows, each level's clamps met, and each row it reaches must meet its
+ * visit's clamps, 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 here alone, from
- * rows that hold the far side inline under its bridge field (the fetch selects no bridge); a
- * `from: 'mapDefaults'` source throws unless it crosses one: a fetched collection can't hold
- * unlinked rows.
+ * `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[];
 
@@ -971,7 +990,7 @@ 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
+/** A rule with the lens's clamps (`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;
 
@@ -999,9 +1018,9 @@ type LensValue = {
 /**
  * One value off a row, as the lens shows it: the path walked as `validateRuleInLens` walks a
  * 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
+ * its visit's clamps, the row itself included (a row a clamp 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.
+ * rows rather than a value and is refused. `options` is what each clamp is checked with.
  */
 declare const readLensValue: (lensOrNarrowing: Lens | LensNarrowing, row: Row, path: string, options?: CheckOptions) => LensValue;
 
@@ -1113,4 +1132,11 @@ 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, 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 };
+/**
+ * Records sorted by an `OrderBy`, the way every rail orders a window: each key in turn, read as an
+ * own-property path, `dir` order, a NULL (or absent) value last in either direction; ties keep their
+ * input order. A new array; the input is not mutated.
+ */
+declare const orderRecords: <T>(items: readonly T[], orderBy: OrderBy) => T[];
+
+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, orderRecords, parseScopeRef, projectLens, projectRows, readLensValue, readScopeRef, stitchFieldMaps, storeLens, toLensSelect, toPrisma, toSourceQueries, toSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };

package/dist/index.d.ts

@@ -183,7 +183,7 @@ type ModelDefaultNarrowing = {
      * 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
+     * once, at its nearest reach; reach it another way by spelling the path under `root`. The first narrowing's clamps (`where`) may read any
      * relation; a later layer's only what its parent shows.
      */
     relations?: Record<string, ModelNarrowing>;
@@ -753,7 +753,7 @@ type ToPrismaOptions = CompileOptions & {
     };
 };
 
-/** A narrowing the lens refuses to apply: a grant validateNarrowing reports, met at runtime. */
+/** A narrowing the lens refuses to apply: a clamp validateNarrowing reports, met at runtime. */
 declare class LensRefusal extends Error {
     readonly code: string;
     name: string;
@@ -835,20 +835,20 @@ type LensRelationSelect = {
     select?: LensSelect;
     where?: PrismaWhere;
 };
-/** What a grant's compile reads: the clock, never a schema (the lens is it). */
+/** What a clamp'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
+/** `keepClampColumns`: 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;
+    keepClampColumns?: 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
+ * columns every `where` on the way reads, through any relation. A to-many relation carries its visit's clamps compiled as its `where`, so
+ * related rows come pre-narrowed, unless a clamp reads that list (it reads it whole); a to-one relation can't (Prisma
+ * takes no `where` there), so `projectRows` drops one its clamp hides. The root's own clamps are the
+ * query's `where`: `toPrisma(rule, { lens })`. Bridges are not selected. A to-many relation's clamp
  * that needs a counting step, or has a window toPrisma can't compile, is refused before anything
  * compiles.
  */
@@ -858,13 +858,13 @@ declare const toLensSelect: (lensOrNarrowing: Lens | LensNarrowing, options?: Le
 /**
  * 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
+ * null. `keepClampColumns` 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 clamp
  * 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
+ * clamps 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[];
+declare const projectRows: (lensOrNarrowing: Lens | LensNarrowing, rows: readonly Row[], { keepClampColumns, ...options }?: ProjectRowsOptions) => Row[];
 
 /** Prisma `select` shape — nested for a grouped source's relation path. */
 type SourceSelect = {
@@ -899,38 +899,52 @@ 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;
-    /** Null, with `sql.sql` null and `sql.error` saying why, when the composed where crosses a
-     * bridge: a database holds one side of it only, so no query offers the right set — materialize
-     * it with `materializeSources` over rows that hold both sides. */
-    prisma: SourcePrismaQuery | null;
+    prisma: SourcePrismaQuery;
     sql: SourceSqlQuery;
+    /** Present when the source reads across a bridge (its where, a clamp 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
- * own narrowing at that path, the grants above it carried down the path, its source
+ * own narrowing at that path, the clamps 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
+ * `from: 'mapDefaults'` source reads the model's own source and carries no clamp 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`. `options` is the clock a
  * relative date in the where compiles with (`now` required for one, as for any compile). A
- * where across a bridge has no query (`prisma` null; see `SourceQuery`).
+ * 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, 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` —
@@ -939,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;
 
@@ -947,18 +967,17 @@ 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 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
+ * `projectRows(…, { keepClampColumns: true })` keeps them; a viewer's projection drops what
+ * the sources read, and a row lacking a key a source or a clamp on its path reads throws. The
+ * path is walked down the rows, each level's clamps met, and each row it reaches must meet its
+ * visit's clamps, 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 here alone, from
- * rows that hold the far side inline under its bridge field (the fetch selects no bridge); a
- * `from: 'mapDefaults'` source throws unless it crosses one: a fetched collection can't hold
- * unlinked rows.
+ * `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[];
 
@@ -971,7 +990,7 @@ 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
+/** A rule with the lens's clamps (`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;
 
@@ -999,9 +1018,9 @@ type LensValue = {
 /**
  * One value off a row, as the lens shows it: the path walked as `validateRuleInLens` walks a
  * 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
+ * its visit's clamps, the row itself included (a row a clamp 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.
+ * rows rather than a value and is refused. `options` is what each clamp is checked with.
  */
 declare const readLensValue: (lensOrNarrowing: Lens | LensNarrowing, row: Row, path: string, options?: CheckOptions) => LensValue;
 
@@ -1113,4 +1132,11 @@ 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, 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 };
+/**
+ * Records sorted by an `OrderBy`, the way every rail orders a window: each key in turn, read as an
+ * own-property path, `dir` order, a NULL (or absent) value last in either direction; ties keep their
+ * input order. A new array; the input is not mutated.
+ */
+declare const orderRecords: <T>(items: readonly T[], orderBy: OrderBy) => T[];
+
+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, orderRecords, parseScopeRef, projectLens, projectRows, readLensValue, readScopeRef, stitchFieldMaps, storeLens, toLensSelect, toPrisma, toSourceQueries, toSql, validateFieldMaps, validateNarrowing, validateRule, validateRuleInLens, walkLensPath };