@inixiative/json-rules 3.4.0 → 3.4.1

package/dist/index.d.cts

@@ -899,17 +899,27 @@ 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 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;
@@ -922,15 +932,19 @@ type SourceQueryOptions = DateConfig;
  * 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;
 
@@ -955,10 +975,9 @@ declare const materializeSourceQuery: (query: SourceQuery, rows: readonly Row[],
  * `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[];
 

package/dist/index.d.ts

@@ -899,17 +899,27 @@ 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 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;
@@ -922,15 +932,19 @@ type SourceQueryOptions = DateConfig;
  * 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;
 
@@ -955,10 +975,9 @@ declare const materializeSourceQuery: (query: SourceQuery, rows: readonly Row[],
  * `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[];