@jarenjs/db 0.73.0 → 0.83.2

package/docs/MODEL-FORMAT.md

@@ -12,6 +12,17 @@ entities, §10 relational translation, §11 the unit of work.
 
 ## 1. Scope
 
+`readSchema(connection)` inventories physical facts independently of model
+representability. SQLite keys include rowid aliases and ordered composite keys;
+columns retain defaults, nullability and key ordinals, foreign keys retain groups
+and update/delete actions. `tables[].sql` and `objects[].sql` retain source DDL,
+including collations, generated expressions, predicates and trigger programs.
+PostgreSQL catalogs retain available object definitions; unavailable source table
+DDL is explicitly `null`. `introspectModel()` also returns an `inventory` with
+`derived` or `preserve` dispositions. A disposition never authorizes a drop.
+Application triggers appear as `unmapped-object` losses with their owner and SQL.
+Repeated inspection is read-only; `strict: true` refuses losses with `JD0002`.
+
 A **model document** declares the collections of a store: each
 collection is a JSON Schema for its documents, a key declaration, and
 a set of declared indexes. `openStore(model, { driver, ... })` opens
@@ -808,7 +819,7 @@ cannot retry; with the lock taken first that wait is an ordinary busy
 wait the `busyTimeout` covers, and two processes claiming one key see
 one `new`. The default `'deferred'` is unchanged, `tx.transaction()`
 inside either mode is a savepoint, `signal` and `unitOfWork` behave the
-same, and the synchronous twin has no mode. The open path already
+same; the synchronous twin also accepts writer admission mode and refuses thenable callbacks. The open path already
 brackets every first-open object — collection, entity and join tables,
 indexes, the change log and its state row, the job tables — the same
 way (§2.4).
@@ -1037,6 +1048,7 @@ error.
 | `JD0035` | the continuation does not belong to this ordering |
 | `JD0036` | a snapshot page needs an immutable ordering |
 | `JD0037` | strictStreaming refused a plan that buffers |
+| `JD0038` | the native mutation document is unsupported or invalid |
 | `JD0040` | the save spans a relation cycle |
 | `JD0050` | live queries require change capture |
 | `JD0051` | the demanded live mode is unavailable |
@@ -1087,6 +1099,8 @@ error.
 | `JD2092` | a worker row, compatibility result or remote identity count exceeds its declared bound |
 | `JD2093` | malformed worker protocol request |
 | `JD2094` | invalid or uncommitted durable snapshot; reopen the last committed version |
+| `JD2095` | trusted SQL or synchronous callback authority refused |
+| `JD2096` | persistence invariant rejected the mutation; constraint class |
 | `JD0060` | a replication envelope or snapshot is invalid |
 | `JD2100` | a replica sequence or causal dependency has a gap |
 | `JD2101` | an envelope identity names different content or an unknown local origin |
@@ -1503,10 +1517,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 +1840,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 +2056,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:
@@ -2266,3 +2297,120 @@ const report = await store.saveChanges();      // { joinInserted: 1, joinDeleted
 
 Worker/pool options, synchronous cursors, wasm session probing and the browser
 persistence ladder are specified in [execution hosts](HOSTS.md).
+
+## 12. Existing column layouts
+
+An entity's optional `physical` member declares a column-only SQLite layout.
+Omitting it retains the hybrid mapping. Opening a physical entity MUST verify
+its existing table or view and MUST NOT create it. `adopt: true` also prevents
+creation of hybrid tables and infrastructure. Inspection, adoption and explicit
+migration are separate operations.
+
+`adopt: true` with `jobs: true` can attach the existing current SQLite job
+tables and claim index without executing DDL. The engine checks its own schema
+declaration, preserving SQL literal values; a missing or differently shaped
+object refuses `JD0002` and requires an explicit migration. Adoption never
+provisions or upgrades the queue. Capture and replication still refuse in
+adopted mode; existing application triggers do not imply complete live capture.
+
+```json
+{
+  "$model": "0.1",
+  "entities": {
+    "Setting": {
+      "schema": { "type": "object", "properties": {
+        "id": { "type": "string", "x-entity": { "key": true } },
+        "value": {}, "updated": { "type": "string" }
+      } },
+      "physical": { "table": "app_settings", "columns": {
+        "id": { "name": "key", "codec": "text", "null": "reject" },
+        "value": { "name": "value", "codec": "json", "null": "absent" },
+        "updated": { "name": "updated_at", "codec": "datetime", "null": "reject", "default": "database" }
+      } }
+    }
+  }
+}
+```
+
+Every stored property MUST have a distinct physical column name, an explicit
+codec and SQL NULL policy. `physical.keys` orders the declared key properties;
+without it, property declaration order applies. The physical primary key must
+agree in order. `kind: "view"` requires declared logical keys and refuses writes.
+Join tables can be declared as ordinary entities with ordered composite keys;
+relation navigation across physical layouts is not qualified.
+
+| Codec | Public representation | Required SQLite affinity |
+|---|---|---|
+| `text` | string | TEXT |
+| `integer` | safe integer | INTEGER |
+| `number` | finite number, safe when integral | REAL |
+| `boolean` | boolean | INTEGER |
+| `json` | JSON value | TEXT |
+| `date`, `datetime` | validated RFC 3339 text | TEXT |
+| `epoch-ms` | canonical UTC date-time text | INTEGER |
+| `bigint` | signed integer decimal string within SQLite's integer range | INTEGER |
+| `decimal` | exact decimal string, including trailing zeros | TEXT |
+| `blob-hex` | lowercase hexadecimal string | BLOB |
+
+Unsafe narrowing refuses `JD2003`. A byte handle never enters the public entity.
+`null: "null"` maps SQL NULL to present JSON null; `"absent"` omits the property;
+`"reject"` refuses it. With the JSON codec, JSON null is stored as the text `null`,
+so SQL NULL can independently mean absence. `default: "database"` omits an absent
+insert column and reads back the database result. `generated: true` gives column
+writes to the database. A generated integer identity uses the existing
+`x-entity.default: "auto"` declaration. Direct updates with identical values and
+identical tracked saves produce no effective writes.
+
+Mapped query documents execute through the existing decoded-row evaluator;
+explanations report this residual and strict pushdown refuses it. Scalar graph
+loads use mapped names; complex codec predicates require query documents.
+Physical `page` and `after` continuation refuse until codec-aware keysets are
+qualified; an explicit `take`/`skip` load remains available.
+Capture/live/replication for adopted application triggers is not qualified and
+is refused, rather than advertised as a complete change stream. PostgreSQL
+column adoption is not qualified; physical inventory remains available.
+
+## 13. Persistence invariants
+
+An entity may declare `invariants`: each has `name`, `on` (insert/update/delete),
+`assert` (a Query expression), and explicit `enforcement` (`database` or `store`).
+The evaluator receives `{ old, new, op }`; the missing record is null. A rule
+passes only on boolean true. Update rules and audit effects skip identical rows.
+Store enforcement covers direct and tracked model writes; arbitrary external
+SQL is outside that population. Trusted SQL writes refuse while store rules are
+present. Failed rules use `JD2096`, with constraint classification.
+
+Database enforcement requires a writable physical layout and a bounded scalar
+query expression: `$eq`, `$ne`, `$lt`, `$le`, `$gt`, `$ge`, `$and`, `$or`, `$not`,
+scalar literals, `$.op`, and `$.old.member` / `$.new.member` references. Unsupported
+expressions refuse at planning. `planInvariants(model, { dialect })` returns
+reviewable trigger DDL; an explicit migration installs it. Opening verifies those
+programs. A rule such as `{ "$le": ["$.new.start", "$.new.end"] }` declares an
+interval constraint without claiming interval indexing.
+
+An optional database `audit: { entity, values }` inserts into an application-owned
+mapped table after the accepted mutation, after identity allocation. Values use
+old/new scalar references. Self-referential or chained audit effects refuse;
+all effects share the writer transaction. Existing unrecognized triggers remain
+application-owned physical objects requiring preservation dispositions.
+
+
+One AFTER trigger per operation evaluates assertions in declaration order, then
+runs audit inserts in declaration order. Assertions see the allocated identity
+and generated columns. A failed assertion aborts the entire statement, including
+its trigger effects. Existing application triggers keep SQLite's ordering relative to these
+programs. Equality uses JSON-style scalar types and null equality; an ordered
+comparison involving SQL NULL is false; `$not` negates that boolean. An absent-column
+policy cannot be lowered to a database rule and refuses. Existing optimistic
+version properties remain owned by the model writer; an external SQL writer must
+supply its own declared revision discipline. Store validation and codec checks
+are not a substitute for database constraints on external inputs.
+
+References to a property of the unavailable old/insert or new/delete record
+refuse database lowering, because absence differs from SQL NULL. Referenced
+scalar storage types are checked by the assertion trigger; numeric references
+must stay in the safe-number range.
+
+## Native column mutation documents
+
+Asynchronous entity sets expose `mutate(document)` for conditional updates, conflict-aware upserts and bounded same-entity insert-select. The closed grammar, no-op/revision behavior, output bounds and transactional qualifications are specified in [NATIVE-PLANS](NATIVE-PLANS.md).

package/docs/NATIVE-PLANS.md

@@ -0,0 +1,111 @@
+# Native plans over adopted columns
+
+The executable census in `test/db/fixtures/adoption-sql.json` retains its SQL
+reference alongside public documents. Five read families execute as one native
+statement: settings projections, environment joins, correlated counts, nullable
+grouped sums/counts, and compound-key point reads. Receipt history retains its SQL
+reference because the source table has no declared primary key. Inventing an
+entity identity would change the adoption contract.
+
+## Reads
+
+Use `store.execute(document, { strict: true })` to require a native plan;
+`{ pushdown: false }` executes the decoded-row reference path. The JSON language
+is unchanged: projections use object/array constructors, correlations use nested
+`$for` and `$count`, and groups use `$groupby`. LINQ chains emit the same documents.
+For example, a projection with a correlated count is:
+
+```js
+const document = [{
+  $for: { c: '$.Catalog[*]' },
+  $orderby: '$c.sku',
+  $return: { sku: '$c.sku', inventories: { $count: {
+    $for: { i: '$.Inventory[*]' },
+    $where: { $eq: ['$i.sku', '$c.sku'] }, $return: '$i'
+  } } }
+}];
+const rows = await store.execute(document, { strict: true });
+const explanation = await store.explain(document);
+```
+
+Native correlations require one inner entity root, equality edges to outer
+bindings, a bare inner return, and supported scalar predicates. Windows, grouping
+and ordering inside a correlation, and arbitrary computed inner returns remain residual. Mandatory profile filters
+apply to correlated roots too. Scalar column projections preserve declared NULL
+policies. Codecs needing transformed representations remain decoded-row work.
+
+Grouping is restricted to one root and reconstructible keys/aggregates. A nullable
+SQL sum needs an explicit query expression: test existence of non-null values,
+then sum those values, otherwise return literal null. An ordinary JSON sum over
+an empty sequence remains zero. Compound physical identities without explicit
+group ordering remain residual; the first-seen order cannot be replaced with
+independent SQL minima. Unsupported shapes give a reason in `explain`; strict
+mode refuses them with `JD0010`.
+Physical integer sums/averages also prove the group's magnitude/count bound
+inside SQL. When intermediate exactness cannot be guaranteed, ordinary execution
+uses the existing decoded evaluator and reports that diversion; strict execution
+refuses `JD0010`. This can cost an additional statement and full decoded scans.
+Floating sums/averages and date/datetime grouping remain residual. Physical text
+comparisons explicitly use codepoint collation, independent of a column's declared
+collation; an incompatible index may therefore stop helping that query.
+
+`explain` reports the emitted SQL, scan narrative, profile bounds and last
+execution's admitted statement/returned-row/serialized-wire-byte counts. These
+are application admission costs. SQLite does not expose visited-row counts or
+statement time enforcement; a correlated subquery can visit many rows despite
+returning a small projection. Use indexes and inspect the scan narrative. Profile
+row limits bound fetched results; byte limits bound each decoded result item.
+
+## Mutations
+
+The asynchronous entity set exposes `mutate(document)`. It compiles and caches a
+closed document into one parameterized SQLite data statement, inside the same
+guarded transaction used by the entity writer. It supports adopted writable
+column layouts. Hybrid entities, PostgreSQL physical layouts, arbitrary SQL,
+store-enforced before/after invariants and unsupported expression shapes refuse
+with `JD0038`. Database constraints and invariant triggers retain enforcement.
+
+```js
+const result = await store.entity('Inventory').mutate({
+  op: 'update', key: { environment: 'test', sku: '0012' },
+  expectedRevision: 1, set: { quantity: 4 },
+  returning: ['quantity', 'revision'], maxRows: 16, maxBytes: 16384
+});
+```
+
+The three operations are:
+
+| Operation | Required document members | Meaning |
+|---|---|---|
+| `update` | `key`, `set`; `expectedRevision` for a versioned entity | Complete primary key and revision predicate; writes only changed columns and increments the revision once. Missing/stale/identical rows yield zero affected rows. |
+| `upsert` | `values`, `conflict`, `update` | Insert or update the named supplied members only if their stored values differ. `conflict` is the complete ordered primary key. |
+| `insert-select` | `source`, `where`, `select`, `conflict`, `onConflict: 'nothing'` | Same-entity scalar/literal projection, bounded source rows, conflict-ignore insertion. Source and target path codecs and NULL policies must match. |
+
+`returning` is a nonempty list of logical stored members (default: all). `maxRows`
+defaults to 100 and `maxBytes` to 1048576; both must be finite positive safe
+integers. The result is `{ mode: 'native', affected, rows, admitted }`.
+`admitted` names one data statement, returned rows and full decoded-row bytes,
+including columns omitted by `returning`. SQL transaction control is separate.
+
+Insert-select materializes at most `maxRows + 1` source rows and refuses overflow
+before insertion, even if all rows would conflict. Output bounds and codec/schema
+validation run inside the transaction; failure rolls back rows and trigger effects.
+The byte bound checks decoded output, not a database allocation interrupt.
+The statement's `RETURNING` view follows SQLite timing; later AFTER-trigger
+modifications are not an extra readback. Same-input replay yields no effective
+write, no revision increment and no additional trigger effects.
+
+Mutations are untracked. Re-read affected rows before subsequent tracked editing;
+a previously tracked revision remains stale and retains normal conflict checks.
+Use `tx.entity(name).mutate(document)` to compose writes, receipts and jobs in one
+transaction. An outer failure rolls everything back. No synchronous `mutate`
+facade or generic bulk mutation expression language is declared.
+
+## Bounded ranges and live qualification
+
+The headless adapter is exported by `@jarenjs/linq/db`; its structural contract is
+[COLLECTION-PROVIDER.md](../../app/docs/COLLECTION-PROVIDER.md). It uses existing
+entity cursors, keyset pages and committed capture, with no app import.
+Initial qualification is captured hybrid entity roots. Physical keyset identities
+and physical capture retain their explicit refusals. Live notifications are
+source resets; offset windows retain their existing rerun classification.

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/docs/SEARCH.md

@@ -0,0 +1,55 @@
+# Persisted lexical search
+
+`@jarenjs/db/search` exports `createDbSearchStorage` and `createDbSearch`.
+The adapter imports the same core ranker and JSON predicate compiler as resident
+execution. `explain()` reports resident residual work and finite source credits;
+SQLite/PostgreSQL native FTS is unqualified and is not substituted silently.
+
+```js
+import { createDbSearch, createDbSearchStorage } from '@jarenjs/db/search';
+// The model declares an Item entity and a snapshots collection keyed by /id.
+const storage = createDbSearchStorage(store, 'snapshots', { maxBytes: 8388608 });
+const search = await createDbSearch(store, 'Item', {
+  version: 1, fields: ['title', 'sku'],
+}, { source: 'catalog', maxRows: 10000, maxBytes: 8388608, storage });
+const page = await search.search('gren tea', {
+  where: { $eq: ['$.available', true] }, facets: ['category'], limit: 20,
+});
+await search.dispose();
+```
+
+The source entity must expose a string `id`; reads order by that key to make cold
+build order reproducible. The store must have committed capture. A complete
+bounded source is read inside a store transaction, and its canonical JSON is
+hashed by host WebCrypto SHA-256 into a source-backed revision. The digest includes
+non-indexed fields, so changed filter/facet facts invalidate search results too.
+Captured source writes issue resets; `dataVersion` checks detect external-connection
+SQL on requests. A cold open reads the source again, so uncaptured edits while the
+adapter was closed cannot validate a stale cache. A host without capture or the
+required data-version capability refuses freshness. PostgreSQL external capture
+remains unqualified; no native full-text claim is made for either dialect.
+
+`search(text, request)` refreshes a dirty source, compiles the request through
+`createLexicalProvider`, then evaluates complete membership before result limits.
+`refresh()` reports zero changes on identical input. `row(id, revision)` supplies
+a detached authoritative row only under the current clean snapshot. `subscribe`
+receives explicit resets, not a claim of incremental SQL maintenance. Refresh
+rebuilds rank statistics from the complete bounded source; core incremental
+updates remain available to other hosts. Source rows and index costs are separate
+from a collection's page cache and mounted cells.
+
+The optional storage collection holds `{id, payload}` derived snapshots. Publication
+is one transaction, and equal payloads perform zero writes. Corruption, stale
+source and incompatible configuration trigger a source rebuild. Failed storage
+publication is reported and retried; an incomplete snapshot cannot count as a
+successful publication. Storage can be the same store or another declared store.
+It is never queried as a catalog. `stats()` reports reads, writes, restores,
+rebuilds, recovery reasons and retained resources. Disposal unsubscribes, cancels
+and drains in-flight reads, clears rows and indexes, and leaves store ownership
+with the caller.
+
+`createLexicalRangeProvider` from `@jarenjs/linq/db` composes this source with the
+shared range provider. It requires complete membership within explicit match and
+source-byte credits; a truncated top-k refuses construction. The adapter preserves
+query and source identities, exposes exact counts only for complete membership,
+and invalidates continuations after changes. Call `refresh()` after invalidation.

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.83.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
   "sideEffects": false,
   "exports": {
+    "./search": {
+      "types": "./types/search.d.ts",
+      "default": "./src/search.js"
+    },
     ".": {
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
@@ -84,9 +88,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.83.2",
+    "@jarenjs/json": "^0.83.2",
+    "@jarenjs/validate": "^0.83.2"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/schemas/jaren-migration.draft-07.schema.json

@@ -29,11 +29,60 @@
       "type": "string"
     },
     "steps": {
-      "description": "Ordered steps; the order is the contract. A pure widening may carry NO steps — the migration then only moves the recorded shape.",
+      "description": "Ordered steps; the order is the contract. A pure widening may carry NO steps \u2014 the migration then only moves the recorded shape.",
       "type": "array",
       "items": {
         "$ref": "#/definitions/step"
       }
+    },
+    "physical": {
+      "type": "object",
+      "required": [
+        "source",
+        "dispositions",
+        "assertions"
+      ],
+      "properties": {
+        "source": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "dispositions": {
+          "type": "object",
+          "additionalProperties": {
+            "enum": [
+              "preserve",
+              "replace",
+              "drop"
+            ]
+          }
+        },
+        "assertions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "sql",
+              "expected"
+            ],
+            "properties": {
+              "sql": {
+                "type": "string"
+              },
+              "params": {
+                "type": "array"
+              },
+              "expected": {
+                "type": "array"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": [
@@ -150,7 +199,7 @@
       "additionalProperties": false
     },
     "deriveStep": {
-      "description": "Recompute named STORED derived index columns from the documents already in a collection. A spatial column is stored only under the physical mapping that cannot index a registered deterministic function (the generated mapping populates itself); a vector column is stored under both. The step is idempotent — a derived value is a pure function of the document — so a replay writes what the first run wrote.",
+      "description": "Recompute named STORED derived index columns from the documents already in a collection. A spatial column is stored only under the physical mapping that cannot index a registered deterministic function (the generated mapping populates itself); a vector column is stored under both. The step is idempotent \u2014 a derived value is a pure function of the document \u2014 so a replay writes what the first run wrote.",
       "type": "object",
       "properties": {
         "kind": {
@@ -224,7 +273,7 @@
       "additionalProperties": false
     },
     "sqlStep": {
-      "description": "A DATA step spelled directly as one SQL statement (MIGRATION-FORMAT §9.4): the planner's fold of a dropped column into the document, the move of a document member into its new column, an R*Tree backfill. Executed exactly as a ddl step; distinct in kind so a reviewer reads intent and a dry run shows it as data.",
+      "description": "A DATA step spelled directly as one SQL statement (MIGRATION-FORMAT \u00a79.4): the planner's fold of a dropped column into the document, the move of a document member into its new column, an R*Tree backfill. Executed exactly as a ddl step; distinct in kind so a reviewer reads intent and a dry run shows it as data.",
       "type": "object",
       "properties": {
         "kind": {
@@ -245,7 +294,7 @@
       "additionalProperties": false
     },
     "rebuildStep": {
-      "description": "The ALTER TABLE procedure SQLite lacks (MIGRATION-FORMAT §10), self-contained: create the target shape under `<table>__rebuild`, copy the rows through the rendered column mapping, drop the old table, rename, recreate the indexes, then `PRAGMA foreign_key_check` inside the transaction.",
+      "description": "The ALTER TABLE procedure SQLite lacks (MIGRATION-FORMAT \u00a710), self-contained: create the target shape under `<table>__rebuild`, copy the rows through the rendered column mapping, drop the old table, rename, recreate the indexes, then `PRAGMA foreign_key_check` inside the transaction.",
       "type": "object",
       "properties": {
         "kind": {
@@ -265,7 +314,7 @@
           }
         },
         "copy": {
-          "description": "The INSERT … SELECT that carries every row across the column mapping.",
+          "description": "The INSERT \u2026 SELECT that carries every row across the column mapping.",
           "type": "string",
           "minLength": 1
         },

package/schemas/jaren-migration.schema.json

@@ -34,6 +34,55 @@
    "items": {
     "$ref": "#/$defs/step"
    }
+  },
+  "physical": {
+   "type": "object",
+   "required": [
+    "source",
+    "dispositions",
+    "assertions"
+   ],
+   "properties": {
+    "source": {
+     "type": "array",
+     "items": {
+      "type": "object"
+     }
+    },
+    "dispositions": {
+     "type": "object",
+     "additionalProperties": {
+      "enum": [
+       "preserve",
+       "replace",
+       "drop"
+      ]
+     }
+    },
+    "assertions": {
+     "type": "array",
+     "items": {
+      "type": "object",
+      "required": [
+       "sql",
+       "expected"
+      ],
+      "properties": {
+       "sql": {
+        "type": "string"
+       },
+       "params": {
+        "type": "array"
+       },
+       "expected": {
+        "type": "array"
+       }
+      },
+      "additionalProperties": false
+     }
+    }
+   },
+   "additionalProperties": false
   }
  },
  "required": [