@jarenjs/db 0.73.0 → 0.75.0

package/ARCHITECTURE.md

@@ -177,9 +177,19 @@ stable code, an object and a detail, sorted, once:
 | `unmapped-table` | a table with neither a document column nor a key |
 | `unmapped-column` | a generated column whose expression is not a member path this dialect wrote |
 | `unmapped-index` | an index over an expression, a predicate, or a column no member path explains |
+| `unmapped-constraint` | a CHECK that is not a complete scalar enum of a mapped entity column |
 | `unmapped-type` | a column type no schema type maps back from — the member is derived untyped |
 | `ambiguous-relation` | a foreign key says which entity it points at; which side declared the edge, and whether the other holds many, is not in the shape |
 
+Scalar entity enum CHECKs are recovered on both dialects. SQLite reads its
+stored CREATE text; PostgreSQL reads `pg_constraint` expressions, including
+its `ANY (ARRAY[...])` rendering and numeric literal casts. The parser accepts
+only the entire enum expression. Unknown predicates, NULL lists, non-binary SQLite collations, nondeterministic
+PostgreSQL collations and casts whose meaning is not proven remain `unmapped-constraint`. Partial indexes and
+expression terms retain their catalog flags; they are never converted into
+unconditional uniqueness. Optional `introspect.checks`/`readChecks` hooks leave
+injected dialects compatible with the earlier catalog surface.
+
 `strict: true` refuses instead of returning a partial model, because a
 caller about to diff the result against a declared model needs to know
 the difference is real.
@@ -351,7 +361,8 @@ A single-binding FLWOR over the collection (`$for: { <name>: '$[*]' }`
 — the examples here write `it`, but the binding is the **document's** to
 name and nothing translates differently under another one)
 with: comparison predicates (`$eq $ne $lt $le $gt $ge`) between a
-singular member path and a literal or external; `$and`/`$or`/`$not`
+singular member path and a literal or external, or two paths in the same
+non-null number/string family; `$and`/`$or`/`$not`
 composition; `$exists`/`$empty`; `$starts-with`/`$ends-with`/
 `$contains` on schema-typed string paths with literal patterns;
 `$orderby` over singular schema-typed paths (`$dir`, `$empty`, no
@@ -359,11 +370,33 @@ collation); a top-level `$subsequence` window with literal bounds; the
 top-level aggregates `$count` and `$sum`/`$avg`/`$min`/`$max` over a
 singular schema-typed path; the whole-document projection that returns
 the bare binding; ONE member path, projected as its value beside its
-JSON type; and a nested SHAPE of objects, arrays, literals and member
+JSON type; and a nested SHAPE of objects, arrays, literals, whole collection bindings and member
 paths, projected as one value/type pair per distinct leaf and rebuilt
 by the decoder — never by parsing a JSON text the database assembled,
 which could not tell an absent member from a present `null`.
 
+Constant projection trees fetch a row marker instead of a document. A
+window over a single path removes absent members before its SQL limit;
+a window over an opaque projection stays set-residual because that projection
+may emit zero or several items per source row.
+
+General scalar grouping preserves absent and null keys separately through
+value/type pairs. Null and boolean keys may group, but ordering them stays
+residual to preserve `JQ2005`. Explicit group ordering accepts orderable keys and proven count/min/max
+expressions, including aggregates absent from the return; first appearance
+breaks ties. SUM/AVG ordering remains residual: compensated or differently
+ordered SQL accumulation can change which group sorts first. Literal windows lower over singleton group constructors;
+`$count` over such constructors with only row-count aggregates counts a grouped
+subquery. `$distinct` over a typed scalar projection uses the same key relation, with
+absent members removed first. Unordered inputs retain first appearance; an
+ordering composed solely of the projected path lowers to group-key order.
+
+Entity projection trees, constants, counts and single-path windows follow the
+same cardinality rules. An equijoin graph can additionally filter through
+boolean trees whose leaves belong to individual bindings. The entity emitter
+resolves each leaf's binding alias before composing the total predicates;
+a disjunction never supplies a mandatory join edge.
+
 Plus the spatial predicates a **derived** index makes decidable:
 `$bbox-intersects` against a literal or external region, a geohash
 prefix no longer than a `derive: 'geohash'` column's precision, and the
@@ -396,15 +429,16 @@ mode, `knn`, beside native, row and set.
 | construct | reason |
 |---|---|
 | `$let` bindings, `$fold`, positional/window bindings | no equivalence proof exists yet; residual by default |
-| a `$groupby` whose key is untyped or nullable, whose `$return` reads the binding, or whose `$orderby` names anything but a key | SQL's grouping and the engine's need not agree on an untyped key; after a grouping the binding holds the group's ROWS, which an object member cannot take |
-| a window over the GROUPS, or an aggregate of them | the plan groups whole; a `LIMIT` over the groups would cut a different set |
+| a `$groupby` whose key is untyped, whose `$return` reads the binding, or whose `$orderby` names anything but an orderable key or count/min/max | SQL's grouping and the engine's need not agree on an untyped key; after a grouping the binding holds the group's ROWS, which an object member cannot take |
+| a window over a group return that may omit an item, or a group aggregate beyond the proven constructor count | SQL group cardinality must equal the projected item cardinality; numeric and error semantics need their own proof |
 | a `$for` binding nothing joins to — a cartesian product | the engine builds the product; a plan that emitted one by accident is the thing an equi-join graph exists to prevent |
 | non-singular path expansion | one relation per binding in this version |
 | `$match` and other unlisted operators, `$call` | no native spelling proven equivalent |
 | `$orderby` with a `$collation` | a collation the dialect cannot reproduce is refused, not approximated |
-| a projection the tree cannot rebuild: an operator over a member, a reference to the binding itself, a non-singular path, a projection with no member path at all | the WHOLE projection runs per row (the row residual) — pushed, ordered and windowed rows, projected by the engine; promoting the part that composes would answer a shape nobody asked for |
+| a projection the tree cannot rebuild: an operator over a member, a reference to the binding itself, a non-singular path | the WHOLE projection runs per row (the row residual) — pushed and ordered rows, projected by the engine; a window over these items runs in the set residual; promoting the part that composes would answer a shape nobody asked for |
 | string operators with an external pattern | the pattern's type is unknowable at plan time and the engine ERRORS on non-string patterns |
-| comparisons where both sides are paths | join territory |
+| path comparisons with untyped, nullable, boolean or differing comparison families | the total typed comparison proof does not cover these shapes |
+| `$distinct` over untyped/compound projections or ordering by other paths | first-occurrence order and structural equality need additional lowering |
 | array/object literals in comparisons | deep-equality has no guarded native form |
 | `$within` over a `derive: 'bbox'` column | a bounding-box pre-filter is pushed; exact containment refines in the engine |
 | a bounded `$distance` over a `derive: 'bbox'` column | a geodesic-circle box pre-filter is pushed; the exact distance refines in the engine |
@@ -788,7 +822,7 @@ exactly what an honest explain may not print.
 ### The two residual modes
 
 - **Row residual** — only the projection is untranslated: predicates,
-  ordering and the window are fully pushed; each fetched row runs
+  and ordering are fully pushed, with no output window; each fetched row runs
   `{ $for: { <the document's own binding>: '$[*]' },
   $return: [ <the document's $return> ] }` (the array wrapper keeps
   array-valued items unambiguous) and the items concatenate in row
@@ -1116,3 +1150,12 @@ by refreshing affected parents from bounded leaves. Source and result payloads
 consume row and byte credits; unsupported shapes keep named reruns. See
 [the replication contract](docs/REPLICATION-FORMAT.md) and
 [the strategy matrix](docs/LIVE-FORMAT.md).
+
+Parameterized distance bounds use the closed `circleAxis` derived parameter:
+`{ kind: 'circleAxis', centre: { external } | { literal }, radius: { external }
+| { literal }, axis: 'w' | 's' | 'e' | 'n' }`. Both inputs are named in every
+edge slot. The binder uses the shared geographic kernel and diverts the whole
+query for missing/invalid values, negative radii, polar or antimeridian boxes.
+The exact distance predicate still refines the candidates. The shared oracle
+covers SQLite column/R*Tree indexes and PostgreSQL, including repeated cached
+calls with different bound values.

package/README.md

@@ -214,7 +214,7 @@ no continuation to emit.
   `explain().projection` names the path or the leaf `paths`, and
   reading a shape no longer reads every document. A shape the tree
   cannot rebuild — an operator over a member, a reference to the
-  binding itself, a projection with no path at all — refuses WHOLE and
+  whole entity binding, a non-singular path — refuses WHOLE and
   runs per row, with `explain().residualProjection` naming what stayed
   behind: promoting the half that composes would answer a shape nobody
   asked for. Every `explain()` also carries `budget`: the profile
@@ -227,6 +227,10 @@ no continuation to emit.
   arithmetic deviation declared rather than hidden (MODEL-FORMAT §10.6: SQLite's
   compensated `SUM` and the engine's naive one differ in the last
   bit). `strict: true` turns any residual into a compile error.
+  Constant trees fetch only a row marker. Counts over entity projection trees
+  lower too; a single-path count or window excludes absent members before
+  counting items. A window over a projection that can emit several items runs
+  in the engine.
 - **Registered operators, correct in the residual, pushed where it
   pays.** Open with a registry (`operators:
   createJsltRegistry().use(mathPack).use(financePack)`) and a query may
@@ -254,6 +258,12 @@ no continuation to emit.
   `openStore` by name — and the promotion still needs a numeric member
   the schema forbids `null` on, because SQL cannot tell a stored `null`
   from an absent one and the engine can.
+- **Typed path comparisons and distinct scalar projections.** Comparisons
+  between two paths in the same non-null number/string family lower without
+  a UDF. `$distinct` over a typed scalar projection groups by its value and JSON
+  type, excluding missing members. Unordered inputs retain first occurrence;
+  ordering solely by the projected path also lowers. Literal windows apply
+  to the distinct items.
 - **Grouping and joins lower whole, or not at all.** A `$groupby` over
   schema-typed member keys becomes a real `GROUP BY`: the keys come back
   with their JSON types beside them, so a group whose key is ABSENT
@@ -262,13 +272,20 @@ no continuation to emit.
   in SQL under the ENGINE's empty rules (`0` for a count or a sum, no
   member at all for the other three), and the groups come out in the
   engine's own order of first appearance unless an `$orderby` over the
-  keys says otherwise. Entity queries join any number of bindings: every
+  keys or count/min/max says otherwise. Entity queries join any number of bindings: every
   binding past the first must be attached by a column equality to one
   already joined, which is what makes the plan a nested loop the engine
   can be compared against — a binding nothing attaches would be a
   cartesian product, so it is the residual, named, and `strict: true`
   refuses it. `explain()` lists the join order with the equalities that
   attached each binding, and the group's keys, aggregates and order.
+  Nullable scalar keys also group; ordering null or boolean keys remains
+  residual to preserve the engine's error. Windows over singleton group
+  constructors lower, and counts over constructors containing only keys,
+  literals and row counts count the grouped subquery. Ties under a partial
+  group ordering retain first appearance.
+  Boolean predicates may span joined bindings when each leaf belongs to one
+  binding; the equality graph still establishes every join.
   A join predicate that is not an equality — a range between two mapped
   columns of one family — refines a match it never makes: the anchor is
   still an equality, so a range alone stays the residual. A projected
@@ -1177,6 +1194,13 @@ be declared (`unmapped-view`), a foreign key cannot say which side
 declared the edge (`ambiguous-relation`). `strict: true` refuses rather
 than answering a partial model.
 
+Scalar enum CHECKs on mapped entity columns are recovered from both
+catalogs. A partial index or an expression term is reported as `unmapped-index`
+without inventing unconditional uniqueness. CHECKs outside the complete scalar
+enum grammar, including NULL lists, collation-dependent equality and unproven
+type conversions, remain
+`unmapped-constraint`.
+
 The derived model is usable as a migration's `from`: read a database,
 plan against your declared model, and an unchanged shape plans nothing.
 SQLite and PostgreSQL derive the same logical model from equivalent
@@ -1309,10 +1333,10 @@ its side-effect-free status read are in
   capture after a disposable live probe. Failed session probes select journal
   capture. OPFS, IndexedDB snapshots and memory have explicit capability and
   durability differences; see [execution hosts](docs/HOSTS.md).
-- **Named future work, not silent gaps**: `$groupby` pushdown beyond
-  the `$time-bucket` ladder, a many-to-many hop on the chain, membership
-  on an auto-keyed pending insert, additional join/group shapes, other SQL dialects,
-  transport policy, database introspection (MODEL-FORMAT §10.6, the roadmap).
+- **Remaining boundaries**: untyped and opaque grouped/projection shapes,
+  federation beyond two sources, richer incremental live queries, portable
+  capture and introspection outside the model vocabulary (MODEL-FORMAT §10.6
+  and the roadmap).
 
 The normative formats are
 [docs/MODEL-FORMAT.md](docs/MODEL-FORMAT.md) (storage §§1–7, safe
@@ -1368,3 +1392,17 @@ The output is one atomically published collection bundle; read it with
 `--format collections`. Assertion plans expose provider, ordered-fold and
 bounded materialization strategies through `onAssertionPlan`.
 See [MIGRATION-FORMAT §6 and §11](docs/MIGRATION-FORMAT.md).
+
+Collection constructor projections can include a whole row beside member
+paths. Group ordering lowers count/min/max expressions, including aggregates
+used only for sorting; SUM/AVG ordering remains in the engine to preserve
+floating-point accumulation order. Parameterized distance bounds bind both
+centre and radius through the spatial index, with full-query fallback for
+invalid, polar and antimeridian probes.
+
+Live collection groups now maintain multiple keys, unordered typed scalar
+distinct projections, and count/sum/avg/min/max over canonical group results.
+Only affected groups are reevaluated in source order; a final aggregate folds
+the retained group outputs in first-appearance order. Input documents and
+group outputs consume both state-entry and byte credits. See
+[LIVE-FORMAT](docs/LIVE-FORMAT.md) for the supported shapes and measured costs.

package/docs/LIVE-FORMAT.md

@@ -192,11 +192,11 @@ Choosing how much history to keep is the host's decision
 (`retention`); what the reader owes is that when rows go, it reports
 the gap instead of hiding it.
 
-**Replication is not built here**, and this log alone does not make
-it safe: there is no conflict resolution, no site identity, no causal
-ordering across writers. The bounded reader with its watermarks and
-its explicit gap is the precondition a replication protocol would be
-built on — not the protocol. That sentence is the whole claim.
+**The log alone is not replication.** Replica identity, causal frontiers,
+durable receipts, conflicts and bounded reset snapshots belong to the opt-in
+[replication subsystem](REPLICATION-FORMAT.md). Its protocol builds on these
+watermarks; a change-log cursor by itself supplies no conflict policy or causal
+ordering across writers.
 
 ## 6. Cross-connection behaviour and non-claims
 
@@ -208,8 +208,8 @@ which changes when ANOTHER connection commits; poll it and treat a
 change as "re-read what you care about". Cross-tab delivery is §7's
 story (the live-query layer).
 
-Non-claims, in one place: no replication, no conflict resolution, no
-capture of writes made by other connections, no capture on stores
+Capture-layer non-claims: no conflict resolution or capture of writes made
+by other connections, no capture on stores
 opened without `capture`, and no statement-level ordering within a
 commit (§2).
 
@@ -255,9 +255,8 @@ the maintenance are this table's — an entity chain re-runs, declared —
 and this document stays the only place they are decided.
 
 **This table is normative.** Every row is implemented and tested;
-nothing outside it is attempted. Classification reads the compiled
-PLAN (never the raw document), so "extractable" below means exactly
-what the pushdown planner already means by it.
+nothing outside it is attempted. Classification combines canonical document shapes with the compiled selection
+plan; "extractable" below means what the pushdown planner already proves.
 
 | Construct (as planned) | Strategy | Maintained state |
 |---|---|---|
@@ -265,7 +264,10 @@ what the pushdown planner already means by it.
 | the same with a per-row `select` projection (row-mode plan) | **incremental rows**: the affected row alone is recomputed; a source row may project to several items | result rows, grouped by source key |
 | `orderBy` over extractable paths, optional `limit`, offset 0 | **maintained window**: a sorted structure; ties broken by the collection key, appended as the final sort term; an insert sorting beyond a full window is a no-op | the window rows and their sort keys |
 | whole-query `count` / `sum` / `avg` / `min` / `max` (the plan's aggregate), optional `where` | **running accumulator** plus a per-row contribution map — a delete can only be answered from retained contributions (§3: a `remove` carries no old value). `min`/`max` removal of the last extremum holder FALLS BACK to a recompute over the retained contributions; the accumulator alone cannot answer, and this fallback is the documented cost | one contribution per matching row |
-| single-level `groupBy` with aggregate returns, in the canonical form below | **per-group deltas**: the accumulator machinery, one instance per group; groups appear in first-appearance order, exactly the engine's order | per-group, per-row contributions |
+| single-level `groupBy` with one or more keys and canonical returns below | **group maintenance**: reevaluate affected groups through the engine in source-row order; first surviving source occurrence determines group order | source documents and group outputs, with entry and byte credits |
+| unordered SQL-native typed scalar distinct projections | **distinct maintenance**: keep the source holders of each value; deleting its earliest holder may move the value in first-occurrence order | source documents and unique outputs, with entry and byte credits |
+| count/sum/avg/min/max over canonical unwindowed groups | **group maintenance** followed by an engine fold over the retained group outputs in first-occurrence order | source documents and group outputs, with entry and byte credits |
+| ordered/windowed distinct or other aggregates over groups | **re-run on invalidation** | the previous result, for diffing |
 | `where` whose spatial predicate is **refined** (the plan pushed a bounding-box or cell-range pre-filter and left the exact `$within`, bounded `$distance` or over-long cell prefix to the residual — `explain().prefilters` with `exact: false`), no order, no aggregate; optional per-row `select` | **incremental rows** — the geofence: the initial fetch narrows through the derived index, and every touched row is re-evaluated by the engine's EXACT predicate, so a point emits `add` when it enters the region, `remove` when it leaves, and nothing while it moves within (a whole-document return sees a `replace` carrying the new position) | the result rows |
 | a refined spatial predicate over a collection with **no document key** (`key: null`, rowid identity) | **re-run on invalidation** — the per-row strategy tracks a row by its declared key, and a rowid is not one; the reason says `rows without a document key cannot be tracked` | the previous result, for diffing |
 | `orderBy` beside a refined spatial predicate — over `$distance` (not a path) or over a member (the set residual drops the planner's order terms) | **re-run on invalidation**, the ordering named as the reason | the previous result, for diffing |
@@ -326,8 +328,8 @@ nested groups have a separate bounded strategy below):
 
 After `$groupby`, `$it` is the group's item sequence and `$g` its key;
 return members are the group key or an aggregate over `$it` (a path
-below it selects the aggregated member). Anything else in the return
-is not canonical and re-runs.
+below it selects the aggregated member). A bare key or a single aggregate is also canonical; other return shapes
+re-run. Multiple declared keys follow the same rule.
 
 ## 8. Invalidation
 
@@ -657,3 +659,36 @@ Count, sum, average, minimum and maximum recompute from only the affected
 parent's bounded leaves. An offset, an unsupported operator, a global input to
 the nested group, or a group-of-groups LINQ emission remains a named rerun.
 Replicated writes enter the same committed capture stream as local writes.
+
+### Group maintenance details
+
+Canonical single-level groups accept one or more key expressions over one
+collection binding, an optional fully translated filter, and either a bare
+key, one count/sum/avg/min/max expression, or an object containing key,
+`$default: [key, null]`, and aggregate members. Global-root reads, ordering,
+and windows remain rerun shapes. Aggregate expressions are evaluated by the
+query engine, including empty results and errors; maintenance does not
+substitute JavaScript arithmetic for query operators.
+
+Keys preserve structural equality and distinguish missing from null. Source
+holders retain physical row positions: changing a holder preserves its
+position, and deleting a group's earliest holder may move that group's
+output. Unaffected group outputs retain reference identity. Only affected
+groups are reevaluated, followed by an optional final aggregate over all group
+outputs. This costs work proportional to the affected groups plus group-output
+ordering/folding, rather than constant-time arithmetic deltas.
+
+`live.maxMaintained` counts source holders and group output items;
+`live.maxBytes` counts their serialized documents. This includes document
+members omitted from a small aggregate result. Exceeding a bound refuses
+registration or closes an active query with `JD2060`; the last delivered
+result remains unchanged. Engine failures follow the same invalidation path.
+
+`node --expose-gc benchmark/changeflow.js` compares every mutation against a
+fresh query and a patch-only consumer. The
+[generated comparison table](REPLICATION-FORMAT.md#measurements) includes
+multiple-key groups, an aggregate of groups and distinct beside forced reruns.
+It reports initialization allocations and both median and tail mutation time;
+heap deltas before collection are not precise retained-state sizes. The fixture
+has 200 initial rows and 15 mutations per case, so these measurements establish
+correctness and costs for that fixture rather than a universal crossover.

package/docs/MODEL-FORMAT.md

@@ -1503,10 +1503,10 @@ The token is a promise about the FOLD, and three rules enforce it:
   the promotion needs the same schema-typed path the core `$sum` and
   `$avg` need. An absent member contributes nothing on either side.
 
-A grouped fold is not promoted — a `$groupby` outside the fixed
-temporal bucket is engine work (§6) — and neither is an aggregate under
-a window. Both answer what the engine answers, and `explain()` names
-the reason. As with the scalar hatch, a profiled document triggers no
+A registered fold inside a `$groupby` return is not promoted — the
+grouped SQL fold currently handles the built-in aggregate set only — and
+neither is an aggregate under a window. Both answer what the engine answers,
+and `explain()` names the reason. As with the scalar hatch, a profiled document triggers no
 registration: the same `$mean` under a profile folds in the residual,
 and `strict: true` refuses it by name (`JD0010`).
 
@@ -1826,16 +1826,24 @@ paths stay residual.
 
 ### 10.2 Joins
 
-Two bindings joined by one equality between their column references
-become an INNER equijoin — exactly the engine's
+Bindings connected by equalities between their column references
+become an INNER equijoin graph — exactly the engine's
 cross-product-plus-filter semantics. Result order is deterministic:
-any `$orderby` keys first, then BOTH bindings' row identities in
+any `$orderby` keys first, then all bindings' row identities in
 binding order, which is the engine's nested-loop order. `explain()`
 reports the join (`{ left, right }`) and the `EXPLAIN QUERY PLAN`
 narrative; the paired foreign key carries an index (every foreign key
 does — unique for a strict one-to-one, plain otherwise), so the probe
 side of the join is a `SEARCH`, never a second scan.
 
+Projection trees of singular member paths and constants lower over one or
+several bindings. Counts over those trees count their items; a single-path
+count or window first excludes rows where that path is absent. Boolean
+predicates may span bindings when each leaf uses one binding's proven total
+forms. The mandatory column equalities still establish the join graph;
+a disjunction is never treated as a mandatory join edge. Compatible path
+comparisons within one binding also lower for non-null numbers and strings.
+
 On the `load` surface the join KIND is derived from the schema
 (§10.4): a `oneToOne` include reports `inner (fk required)` when the
 `via` property is in `required`, `left (fk optional)` otherwise —
@@ -2034,17 +2042,26 @@ a number appears only where `capabilities.rowEstimates` is filled):
   must never emit by accident; every binding past the first attaches by
   a column equality to one already joined, and a graph that does not
   close is the engine's;
-- non-equality join predicates, and disjunctions spanning bindings;
-- a `$groupby` whose key is untyped or admits `null`, whose `$return`
-  reads the binding (after a grouping it holds the group's ROWS), or
-  whose `$orderby` names anything but a group key; a window over the
-  groups, or an aggregate of them;
-- projections (`$return` objects) ACROSS a join — over one binding a
-  nested shape of member paths lowers (§ the projection tree);
+- a non-equality predicate used as the only join anchor, or a boolean
+  predicate whose individual leaf cannot be assigned to one binding;
+- collection grouping with untyped keys, row-binding returns, or ordering by
+  anything except an orderable key or count/min/max expression; entity grouping; aggregates over groups
+  beyond a count of singleton constructors containing keys, literals and row
+  counts; windows over group returns that may omit an item;
+- projection trees containing operators, whole entity binding references or
+  non-singular paths; windows over those opaque projections;
+- `$distinct` over untyped/compound projections or ordering by other paths;
+  typed scalar projections lower when unordered or ordered solely by the
+  projected path, preserving first occurrence or that declared order;
 - externals against document paths; booleans and `null` at bind time;
 - everything phase A already listed (§8 of `QUERY-FORMAT.md`
   notwithstanding, the truth table is the contract).
 
+Collection group keys may include null or boolean values, but ordering those
+keys stays residual to preserve `JQ2005`. Group ordering is stable under ties.
+Literal windows over singleton group constructors lower directly, and the
+proven constructor count wraps the grouped statement in `COUNT(*)`.
+
 Two deviations between a pushed answer and the engine's are DECLARED
 rather than refused, because in both the database is right by its own
 arithmetic:

package/docs/REPLICATION-FORMAT.md

@@ -184,25 +184,31 @@ allocations observed after initialization, not precise retained-heap sizes.
 
 <!--fact:db.changeflow-->
 
-Measured 2026-09-08, v24.19.0, AMD Ryzen 9 5900HX with Radeon Graphics; 15 mutations per case.
+Measured 2026-09-09, v24.20.0, AMD Ryzen 9 5900HX with Radeon Graphics; 15 mutations per case.
 
 | Shape | Strategy | Initialize ms | Mutation p50 ms | Mutation p95 ms | Initialization heap bytes |
 |---|---|---:|---:|---:|---:|
-| selective join | join | 16.663 | 0.323 | 2.119 | 4878848 |
-| selective join | rerun | 0.899 | 0.746 | 1.622 | 347160 |
-| high fan-out join | join | 7.314 | 1.901 | 3.179 | 4851232 |
-| high fan-out join | rerun | 0.860 | 0.850 | 1.188 | 340328 |
-| graph | graph | 7.462 | 0.459 | 0.750 | 4811712 |
-| graph | rerun | 4.539 | 4.042 | 4.979 | 1417928 |
-| nested groups | nested-group | 6.775 | 0.252 | 0.795 | 2057832 |
-| nested groups | rerun | 0.897 | 0.472 | 0.685 | 295808 |
-| offset groups | rerun | 1.519 | 0.459 | 0.547 | 383648 |
-| offset groups | rerun | 0.884 | 0.426 | 0.585 | 282280 |
+| selective join | join | 15.740 | 0.349 | 2.173 | 4854712 |
+| selective join | rerun | 1.040 | 0.850 | 1.321 | 347640 |
+| high fan-out join | join | 8.115 | 1.984 | 3.040 | 4769632 |
+| high fan-out join | rerun | 0.744 | 0.973 | 1.303 | 353768 |
+| graph | graph | 7.742 | 0.429 | 0.728 | 4811904 |
+| graph | rerun | 4.606 | 4.170 | 7.953 | 1418576 |
+| multiple-key groups | group | 8.417 | 0.285 | 0.882 | 2107240 |
+| multiple-key groups | rerun | 0.663 | 0.405 | 0.464 | 116960 |
+| group aggregate | group | 3.839 | 0.236 | 0.398 | 1932544 |
+| group aggregate | rerun | 0.846 | 0.449 | 0.670 | 275560 |
+| distinct | distinct | 3.731 | 0.179 | 0.317 | 1616800 |
+| distinct | rerun | 0.480 | 0.238 | 0.333 | 86128 |
+| nested groups | nested-group | 4.565 | 0.206 | 0.377 | 1757528 |
+| nested groups | rerun | 0.779 | 0.551 | 0.675 | 293560 |
+| offset groups | rerun | 1.274 | 0.474 | 0.623 | 383792 |
+| offset groups | rerun | 0.773 | 0.527 | 1.158 | 299416 |
 
 | Capture | Envelopes | Operations | Bytes | Apply p50 ms | Replay p50 ms | Conflict p50 ms |
 |---|---:|---:|---:|---:|---:|---:|---:|
-| session | 15 | 15 | 3169 | 0.458 | 0.118 | 0.204 |
-| journal | 15 | 15 | 3169 | 0.294 | 0.092 | 0.161 |
+| session | 15 | 15 | 3169 | 0.463 | 0.119 | 0.213 |
+| journal | 15 | 15 | 3169 | 0.333 | 0.097 | 0.160 |
 
 Selective maintenance avoids repeated full SQL evaluation. Initialization and high-fan-out maintenance can cost more than rerunning; the table includes both. Offset groups remain rerun in both requested modes.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.75.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -84,9 +84,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.73.0",
-    "@jarenjs/json": "^0.73.0",
-    "@jarenjs/validate": "^0.73.0"
+    "@jarenjs/core": "^0.75.0",
+    "@jarenjs/json": "^0.75.0",
+    "@jarenjs/validate": "^0.75.0"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/src/algebra.js

@@ -50,13 +50,17 @@ export const PLAN_VERSION = 2;
  *   { p: 'not', item: PlanPredicate } |
  *   { p: 'cmp', op: 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge',
  *     ref: PlanRef, operand: PlanOperand } |
+ *   { p: 'refCmp', op: 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge',
+ *     left: PlanRef, right: PlanRef } |
  *   { p: 'typeIs', ref: PlanRef, types: string[], positive: boolean } |
  *   { p: 'strop', kind: 'starts' | 'ends' | 'contains',
  *     ref: PlanRef, operand: PlanOperand } |
  *   { p: 'const', value: boolean } |
  *   { p: 'udf', name: string, key: string } |
  *   { p: 'bboxOverlap', columns: { w: string, s: string, e: string,
- *     n: string }, probe: { box: number[] } | { ext: string } } |
+ *     n: string }, probe: { box: number[] } | { ext: string } |
+ *     { circle: { centre: { external: string } | { literal: unknown },
+ *       radius: { external: string } | { literal: unknown } } } } |
  *   { p: 'cellIn', column: string, cells: string[], keepEmpty?: boolean } |
  *   { p: 'cellPrefix', column: string, prefix: string } |
  *   { p: 'interval', columns: { start: string, end: string },
@@ -123,7 +127,8 @@ export const PLAN_VERSION = 2;
  *   aggregates: { as: string, fn: 'rows' | 'sum' | 'avg' | 'min' | 'max',
  *     ref: PlanRef | null, empty: 'zero' | 'omit' | 'null' }[],
  *   tree: PlanProjectionNode,
- *   order: 'first-seen' | { index: number, desc: boolean, nullsFirst: boolean }[]
+ *   order: 'first-seen' | { index?: number, aggregate?: number,
+ *     desc: boolean, nullsFirst: boolean }[]
  * }} PlanGroup
  *   The GENERAL `GROUP BY`: one key per declared grouping name, the
  *   closed aggregate set over the group's rows, and the projection tree
@@ -133,7 +138,8 @@ export const PLAN_VERSION = 2;
  *   an `agg` node reads one aggregate under its `empty` rule. `order` is
  *   `'first-seen'`, the engine's own order of first appearance, or the
  *   group-key ordering an `$orderby` declared. A plan carrying a group
- *   carries no `bucket`, no `aggregate` and no `rank`.
+ *   carries no `bucket` or `rank`. A `count` aggregate may wrap a
+ * singleton group constructor, counting groups through a subquery.
  *
  * @typedef {{ ref: PlanRef, every: number, origin: number, as: string,
  *   order: 'asc' | 'desc' | 'first-seen',

package/src/derive.js

@@ -383,12 +383,23 @@ export function cellNeighbourhood(cell) {
  * external's bounding box, computed at bind time because a GeoJSON
  * object is not a value any database can bind. `null` when the value
  * has no box, which is what tells the caller to divert.
- * @param {{ kind: string, external: string, axis: string }} derived
- * @param {any} value - the bound external
+ * @param {any} derived
+ * @param {any} value - the bound external for bboxAxis; all externals for circleAxis
  * @returns {number | null}
  */
 export function derivedSlotValue(derived, value) {
-  const box = bboxOf(value);
+  let box;
+  if (derived.kind === 'bboxAxis') box = bboxOf(value);
+  else if (derived.kind === 'circleAxis') {
+    const read = (input) => 'external' in input ? value[input.external] : input.literal;
+    const at = probePosition(read(derived.centre));
+    const radius = read(derived.radius);
+    if (at === null || typeof radius !== 'number' || !Number.isFinite(radius) || radius < 0)
+      return null;
+    box = probeCircleBox(at, radius);
+    if (box !== null && (box[0] < -180 || box[2] > 180)) return null;
+  }
+  else throw new TypeError(`unknown derived parameter kind '${derived.kind}'`);
   return box === null ? null : box[BBOX_AT[derived.axis]];
 }
 

package/src/dialect.js

@@ -185,6 +185,7 @@ function normalizeCapabilities(declared) {
  *   memberPathOf?: (expression: string) => (JsonPathSegment[] | null),
  *   expressionOf?: (expression: string, byName: Record<string, string>) => (any | null),
  *   readGenerated?: (rows: any[]) => { name: string, expression: string }[],
+ *   readChecks?: (rows: any[]) => { name: string, column?: string, values?: any[] }[],
  *   introspect: { version: () => string, compileOptions: () => string,
  *     pragma: (name: string) => string,
  *     tableExists: () => string, columns: (table: string) => string,
@@ -640,6 +641,7 @@ export function createDialect(spec) {
      * one that can read it.
      */
     readGenerated: spec.readGenerated,
+    readChecks: spec.readChecks,
     explainQuery: spec.explainQuery,
     /** The plan narrative, one line per row the engine answered. */
     explainLines: spec.explainLines,