@jarenjs/db 0.75.0 → 0.83.2

package/ARCHITECTURE.md

@@ -1159,3 +1159,23 @@ 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.
+
+
+## Explicit relational adoption
+
+`introspect.js` owns physical inventory independently of model derivation.
+`physical.js` compiles column codecs and verifies declarations against that
+inventory. The existing entity core, tracker and graph row merger execute both
+hybrid and column layouts; there is no separate relational store. The query
+planner reports decoded evaluation for physical codecs, and refuses physical
+keyset continuation until its identity semantics are qualified.
+
+`sql.js` binds trusted statements to `store.js` transaction views. It reuses the
+read classifier's tokenizer and the driver's scope owner. Writes invalidate all
+clean tracked entities; pending edits and incomplete capture populations refuse.
+`invariants.js` uses the shared Query compiler for store rules; the dialect lowers
+a bounded database subset into ordered trigger bodies. `migrate.js` reuses its
+existing rebuild/receipt transaction and verifies preservation before publication.
+The backup publisher remains shared by Node online and Bun serialized snapshots.
+
+`src/search.js` composes core lexical mechanics and the JSON predicate compiler over complete bounded entity snapshots. Committed capture and data-version checks invalidate derived state; SHA-256 source content validates persisted caches across reopen. Snapshot storage uses existing collection transactions. See [search execution](docs/SEARCH.md); native full-text dialects remain unqualified.

package/README.md

@@ -1,5 +1,7 @@
 # @jarenjs/db
 
+For existing-file adoption with native queries, receipts and jobs, start with the [combined public recipe and evidence ledger](../../docs/ADOPTION-EVIDENCE.md). Adopted-trigger capture, physical keysets and PostgreSQL subsystem gaps retain their documented refusals; synthetic SQLite proof does not retire downstream SQL.
+
 Documents AND entities in SQLite. A **model document** declares
 collections (a JSON Schema, a key, indexes) and — since phase B —
 **entities**: keys, typed columns, relations, defaults and an
@@ -1357,6 +1359,7 @@ Every subpath a consumer can import, derived from the manifest by
 <!--fact:exports.db-->
 | Import | Kind | Declarations |
 |---|---|---|
+| `@jarenjs/db/search` | JavaScript | declared |
 | `@jarenjs/db` | JavaScript | declared |
 | `@jarenjs/db/node` | JavaScript | declared |
 | `@jarenjs/db/postgres` | JavaScript | declared |
@@ -1366,6 +1369,7 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/db/app` | JavaScript | declared |
 | `@jarenjs/db/schemas/jaren-migration.draft-07.schema.json` | schema | — |
 | `@jarenjs/db/schemas/jaren-migration.schema.json` | schema | — |
+| `@jarenjs/db/schemas/jaren-model.authoring.schema.json` | schema | — |
 | `@jarenjs/db/schemas/jaren-model.draft-07.schema.json` | schema | — |
 | `@jarenjs/db/schemas/jaren-model.schema.json` | schema | — |
 | `@jarenjs/db/schemas/jaren-replication-snapshot.draft-07.schema.json` | schema | — |
@@ -1406,3 +1410,24 @@ 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.
+
+
+## Existing relational SQLite files
+
+Use `readSchema(connection)` for physical inventory, then declare an entity's
+`physical` table, ordered keys and column codecs and open with `{ adopt: true }`.
+Opening verifies the existing shape and emits no DDL. Ordinary column tables need
+no document column; integer identities, exact hexadecimal BLOBs, database defaults
+and read-only views have explicit contracts in [MODEL-FORMAT](docs/MODEL-FORMAT.md#12-existing-column-layouts).
+
+Inside `store.transaction`, `tx.sql.prepare(text, { access: 'read' | 'write' })`
+shares the entity/outbox connection and savepoint owner. Statements expire with
+the scope. [The client recipe](../linq/docs/DB-CLIENT.md#trusted-sql-during-adoption)
+documents trust, invalidation and synchronous execution. Schema changes use
+`planPhysicalMigration` and `migrate`; [preservation and forward recovery](docs/MIGRATION-FORMAT.md#existing-physical-files-and-forward-recovery)
+require explicit dispositions and assertions. `planInvariants` supplies declared
+SQLite constraint/audit triggers for installation through that migration boundary.
+
+Native column reads and bounded mutation documents are specified in [NATIVE-PLANS](docs/NATIVE-PLANS.md), including SQL census coverage, resource accounting and refusals.
+
+`@jarenjs/db/search` composes the resident ranker with bounded authoritative entity reads and optional atomic snapshot storage. See [persisted search](docs/SEARCH.md).

package/docs/HOSTS.md

@@ -272,3 +272,20 @@ Checked and dropped:
 - Read-only WAL workers do not accept writes, nested scopes do not migrate,
   transient cursors do not exhaust the statement cap, and failed writes are not
   automatically replayed. The lifecycle and fault corpus exercises each boundary.
+
+
+## Existing-file adoption and backup
+
+Node and Bun qualify explicit SQLite column mappings and scoped prepared SQL.
+The synchronous transaction API exists only when the driver's observed
+`synchronous` capability is true; worker and other async-only hosts expose no
+sync twin. Physical adoption on PostgreSQL refuses pending a separate mapping
+and codec qualification. Unknown application-trigger effects do not qualify
+capture or replication; those combinations refuse before an adoption claim.
+
+Node backups use the built-in online snapshot. Bun uses `Database.serialize()`
+under the store gate, writes and flushes a sibling temporary, then uses the shared
+atomic publisher. Both include committed WAL. Bun's snapshot holds the whole
+image in memory and cancellation takes effect between phases. Process-kill tests
+cover rebuild copy, table drop, commit and backup publication on both hosts;
+these tests do not establish power-loss durability or native executable packaging.

package/docs/JOBS-FORMAT.md

@@ -504,3 +504,29 @@ a cancellation policy, a retry policy are the host's.
 only by `cancel()`; `counts()` reports it. A transaction view's `jobs`
 (the outbox, §3) carries none of the four: an administration call is a
 root call.
+
+## Business receipt and external-effect composition
+
+`jobs.assertLease(lease)` checks current execution authority without a write or
+renewal. It uses the same token/expiry guard and `JD2065`/`JD2066`/`JD2067` refusals
+as settlement; malformed authority is `JD2068`. Inside `tx.jobs`, this read and
+subsequent mapped writes share the transaction lock. Workers receive
+`context.lease()` to read their current token after automatic renewal.
+
+`createWorker({ effectSafety(job, context), ... })` optionally gates each handler
+admission. Only `true` admits; any other resolved value pauses the queue attempt
+in its existing `cancelled` state without running the handler. The worker
+`context.pause()` exposes the same operation. An authorized operator can
+explicitly `requeue` and claim it for reconciliation; it never becomes an
+unreclaimable completed job merely because its external outcome is unknown.
+A thrown policy error follows the ordinary failure path and is checked again on
+a later attempt. `createDagJobRunner` forwards the same hook. The hook supplements
+the mapped effect store's mandatory pre-dispatch fence and durable intent; it is
+not a replacement for them.
+
+Business receipts and external intents belong to application-mapped tables via
+`@jarenjs/linq/db`. Job reset/sweep operate on queue/checkpoint rows only and do
+not erase those facts. An expired lease, reset or retryable job failure cannot
+provide permission to resend unresolved external writes. Local co-commit does
+not mean exactly-once remote delivery. See the contract package's
+[durable composition](../../contract/docs/DURABLE.md).

package/docs/LIVE-FORMAT.md

@@ -692,3 +692,7 @@ 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.
+
+## Structural range adapter
+
+`@jarenjs/linq/db` exposes bounded ranges over captured hybrid entity roots, using the existing keyset pager and committed observer. Its live event is an explicit source reset with monotone revision; this does not promote offset windows or the remaining incremental shapes. See [COLLECTION-PROVIDER](../../app/docs/COLLECTION-PROVIDER.md) for credits, snapshot identity and disposal. Maintained top windows check offscreen rows against their bound and release retained state on close.

package/docs/MIGRATION-FORMAT.md

@@ -598,3 +598,37 @@ difference between a puzzled afternoon and a five-minute fix.
 Down migrations REMAIN a non-goal (§7's reasoning is unchanged): a
 down migration is a data-loss generator wearing a seatbelt; recovery
 is a backup restored plus the forward chain.
+
+## Existing physical files and forward recovery
+
+`planPhysicalMigration(connection, fromModel, toModel, options)` records the
+source schema and explicit DDL/SQL/rebuild steps as an ordinary migration document.
+`options` supplies an `id`, `steps`, a disposition for every source `type:name`
+(`preserve`, `replace`, or `drop`), and optional `{ sql, params, expected }`
+preservation assertions. Assertions are SELECTs evaluated before and after the
+steps. They should cover committed identities, exact BLOB hex and application
+history facts. Unknown objects cannot disappear without a declared disposition.
+Automatic hybrid model diffing refuses column layouts; an explicit plan is required.
+
+Apply through `migrate(target, [plan], { baseline, model, shadow: false })`.
+A physical plan must be qualified on an explicit backup and fresh-target fixture;
+an empty model-generated shadow cannot recreate the original file's application
+programs. The runner uses its existing immediate transaction, ordered steps,
+checksummed receipt and FK checks. It checks the source schema before destructive
+steps and preserved objects and assertions before publication. Target mapped
+columns and declared invariant triggers are verified. A changed source is
+`JD0020`, a lost object/fact is `JD0023`, and an edited applied receipt is `JD0022`.
+
+Migration history is created inside the applying transaction only when needed.
+An identical second run executes no DDL or DML. Failed steps and failed commits
+roll back; after a process kill SQLite recovery leaves the source or the committed
+target. Re-running resumes from committed receipts. Forward repair plans start
+from the newest file, including later application edits; restoring an older
+backup does not qualify as forward repair.
+
+`backupTo()` publishes a sibling temporary only after a complete snapshot.
+Node uses online backup. Bun uses its native serialized SQLite snapshot under
+the store gate, then flushes and atomically renames through the same publisher.
+Bun holds a full database image in memory and cannot offer page-granular copy
+cancellation. Both snapshots include committed WAL; interruption before rename
+leaves the previous destination valid, while a leftover temporary is not published.

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 |
@@ -2283,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/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.75.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.75.0",
-    "@jarenjs/json": "^0.75.0",
-    "@jarenjs/validate": "^0.75.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
         },