@jarenjs/db 0.66.1 → 0.72.0

package/ARCHITECTURE.md

@@ -1095,3 +1095,22 @@ processes creating one fresh file never meet the deferred-upgrade
 `SQLITE_BUSY` the busy handler cannot retry. The job queue's
 administration (`page`, `cancel`, `requeue`, `sweep`) lives in
 `src/jobs.js` beside the fence it authorises through (JOBS-FORMAT §10).
+
+
+## Replication and bounded dependency maintenance
+
+`replication-format.js` owns JSON normalization; `replication.js` persists replica
+identity, frontiers, canonical receipts, before-images, outbox and conflict
+evidence through the capture transaction's `beforeCommit` seam. `logical-rows.js`
+shares mapped, validated row access between replication and live dependencies.
+Remote application suppresses only local envelope allocation: its data still
+invalidates capture subscribers after commit. Snapshot reset carries complete
+receipt evidence and refuses histories beyond its explicit credits.
+
+`live-join.js` compiles indexed dependency descriptors from the entity planner
+and mapping. The same cache strategy maintains inner/left joins and eligible
+nested graph projections. `live-nested.js` maintains explicit two-level groups
+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).

package/README.md

@@ -688,6 +688,15 @@ opinion: <!--fact:vector.ceiling-->5.142 ns per vector component — one query r
 Past that this design is the wrong tool and no margin changes it; what
 lies beyond is an approximate index, and this store does not have one.
 
+The [labelled retrieval comparison](../../benchmark/README.md#labelled-recall-and-repeated-refinement)
+also scores an optional storage adapter with approximate candidates against
+exact cosine on cached live embeddings. The AI ledger reports the adapter's
+algorithm, exhaustive flag and returned candidate count, validates candidate
+identity/vector shape, and re-scores candidates itself. The DB ledger recipe
+continues to normalize as an exact adapter. No ANN runtime dependency is added.
+
+Index decision: <!--fact:recall.annDecision-->0/6 contender rows cleared all bars; retain exact. Required exact-top-10 recall ≥ 0.95, p95 speedup ≥ 2×, and a measured exact p95 ≥ 100 ms. The largest reference corpus contains 5183 documents; scale beyond it remains unmeasured.<!--/fact-->
+
 **One document, three executors, proven to agree.** As with the spatial
 family, the k-nearest shapes of a committed corpus
 (`test/json/fixtures/vector-corpus.json`) run through the JavaScript
@@ -990,11 +999,17 @@ shutdown limits, the browser persistence matrix and measured latency/memory loss
   `sessionReason`. One diff
   format runs store → patch → live query → O(k) render. Capture is
   opt-in; the overhead is published, not waved away.
+- **Portable replication** ([REPLICATION-FORMAT](docs/REPLICATION-FORMAT.md)):
+  opt-in replica identities, causal frontiers, bounded logical envelopes,
+  durable replay receipts, explicit conflict evidence and snapshot resets.
+  Data and acknowledgements commit together. Hosts supply transport and any
+  conflict resolver; the default preserves both contenders and rejects the write.
 - **Live queries** (LIVE-FORMAT §§7–13): `collection.live(document)`
   maintains a result as writes arrive and emits patches — incremental
   for `where`/`select`/`orderBy`+`limit`/aggregates/single-level
   `groupBy` and a spatial `where` over a derived index (the geofence;
-  the normative maintenance table), re-run for everything else,
+  the normative maintenance table), indexed inner/left entity joins, bounded
+  graph projections and explicit two-level groups; re-run for other shapes,
   **declared, never silent** (`live.mode` names the reason).
   Unaffected rows stay reference-identical; a seeded oracle holds the
   maintained result equal to a fresh re-query after every mutation.
@@ -1022,6 +1037,10 @@ shutdown limits, the browser persistence matrix and measured latency/memory loss
   and `worker.stop()` quiesces every claim, renewal, checkpoint and
   settlement before it resolves, so closing the store releases the
   database file deterministically.
+  DAG jobs inspect persisted workflow/input/task identity before reading
+  checkpoint values. `jobs.reset(id, { expectedGeneration })` explicitly
+  discards an inactive run's checkpoints and restarts it under a new fence;
+  live leases and stale observations refuse (JOBS-FORMAT §10).
 - **The browser** (`@jarenjs/db/wasm`): the same store, the same
   queries, the same live updates run on the official SQLite wasm build
   over a probed persistence ladder: isolated SharedArrayBuffer OPFS,
@@ -1276,7 +1295,8 @@ its side-effect-free status read are in
   there. Same-host processes over WAL are the supported topology. No
   priority classes, no cron, no workflow compensation.
 - **Live-query maintenance is limited to the declared table** (§7);
-  joins, entity queries and non-canonical shapes re-run, reported.
+  indexed joins and graph projections require bounded dependencies. Offset
+  windows, unindexed joins, load-spec graphs and non-canonical shapes re-run, reported.
 - **`eventTime.retention` bounds repair work, not memory.** It is the
   horizon a view claims and is checked against the window it maintains;
   the maintained state is still bounded by `live.maxMaintained`, and no
@@ -1287,8 +1307,8 @@ its side-effect-free status read are in
   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, incremental joins, other SQL dialects,
-  replication, database introspection (MODEL-FORMAT §10.6, the roadmap).
+  on an auto-keyed pending insert, additional join/group shapes, other SQL dialects,
+  transport policy, database introspection (MODEL-FORMAT §10.6, the roadmap).
 
 The normative formats are
 [docs/MODEL-FORMAT.md](docs/MODEL-FORMAT.md) (storage §§1–7, safe
@@ -1320,7 +1340,27 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/db/schemas/jaren-migration.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 | — |
+| `@jarenjs/db/schemas/jaren-replication-snapshot.schema.json` | schema | — |
+| `@jarenjs/db/schemas/jaren-replication.draft-07.schema.json` | schema | — |
+| `@jarenjs/db/schemas/jaren-replication.schema.json` | schema | — |
 | `@jarenjs/db/package.json` | metadata | — |
 | `@jarenjs/db/node-worker` | JavaScript | declared |
 | `@jarenjs/db/node-pool` | JavaScript | declared |
 <!--/fact-->
+
+
+The [durable AI ledger recipe](../ai/README.md#a-durable-ledger-over-jarenjsdb)
+exposes optional atomic namespace mutation as well as its base storage and rank
+capabilities. It reads and publishes through one immediate transaction, using the
+transaction's synchronous collection facade so another SQLite connection on the
+same event loop cannot block an awaiting writer. A rejected callback changes
+neither records nor counters; ledger id minting and guarded multi-record updates
+use that boundary.
+
+Document-only migrations also accept named files:
+`jaren-db documents --migrations migrations --in users=users.json --in events=events.jsonl --out migrated.json`.
+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).

package/docs/JOBS-FORMAT.md

@@ -390,7 +390,10 @@ await store.jobs.enqueue('sync-report', { input: { day: '2026-08-05' } });
 
   **The legacy rule is deterministic, and never reads unknown as equal.**
   A run checkpointed by a release that did not record task identity has
-  no `taskVersionsHash`. If it recorded no node value yet, there is
+  no `taskVersionsHash`. Identity inspection reads only the reserved metadata
+  value and probes whether other rows exist; it does not load or parse node
+  values. Missing metadata with saved values refuses `JD2069`. Refused
+  legacy upgrades leave the original identity untouched. If it recorded no node value yet, there is
   nothing that could be replayed wrongly, so the identity is upgraded in
   place and the run proceeds. If it DID record values, the implementation
   that produced them cannot be confirmed and the resume is refused,
@@ -471,6 +474,16 @@ a cancellation policy, a retry policy are the host's.
   and counts it under `stats().cancellations`; an attempt held by
   another process meets the fence at its next settling call and records
   a loss, as any superseded attempt does.
+- **`reset(id, { expectedGeneration })`** — explicitly discard one inactive
+  run's checkpoints and restart its attempts at zero. Read the job's
+  `leaseGeneration` first and pass that observation. One transaction
+  conditionally updates the job, increments its fence generation and deletes
+  its checkpoint rows. A concurrent generation change refuses `JD2066`, a
+  live lease `JD2068`, an unknown or completed job `JD2065`; no refusal
+  discards values. The next claim recomputes the workflow under current
+  identity. Reset does not undo external task effects; their idempotency
+  keys remain the host's responsibility. It is root-only administration,
+  with the same signal/deadline options as requeue.
 - **`requeue(id)`** — returns a failed, dead, cancelled or lease-expired
   job to `pending` at the clock's instant (the queue's own order). The
   attempt history is KEPT: `attempts` counts every claim the job ever

package/docs/LIVE-FORMAT.md

@@ -273,7 +273,10 @@ what the pushdown planner already means by it.
 | a spatial predicate the planner **refused** (no `derive` index on the member, an untyped member, an unbounded probe) | **re-run on invalidation**, the refusal named — it never translated, so nothing narrows the fetch | the previous result, for diffing |
 | a `$resample` or `$rolling` document over the collection, with an explicit `eventTime` and a fixed width (§13) | **event-time bucket / rolling state**: rows kept by bucket, or in instant order; only what a write can reach is folded again, through `@jarenjs/core/series` itself | the contributing rows, plus one fold per bucket |
 | the same document with no `eventTime`, a calendar width, a named zone, a `locf`/`linear` fill, a `first`/`last` aggregate, or a retention that does not cover the window | **re-run on invalidation**, the member that stopped it named (§13.2) | the previous result, for diffing |
-| joins, multi-entity roots, graph loads, every entity query | **re-run on invalidation — declared, not attempted** in this version | the previous result, for diffing |
+| indexed inner equi-joins and canonical allowing-empty left joins over mapped entity roots | **join dependency maintenance**; point-read changed keys and reevaluate their bounded outer owners | source rows, key indexes and projected tuples, bounded by `maxMaintained` and `maxBytes` |
+| nested entity graph projections with indexed equality edges and unique binding names | **graph dependency maintenance**; a child change refreshes its bounded owners | source rows, reverse key indexes and graph outputs |
+| explicit two-level collection groups with a singular parent key and bounded nested input | **nested-group maintenance**; recompute affected parents through the query engine | source leaves and parent outputs |
+| unindexed/non-equi joins, self joins, explicit entity ordering/windows, object-root documents and load-spec graphs | **re-run on invalidation**, with the dependency or planner reason | previous result for diffing |
 | anything else: non-translatable predicates, `limit` without `orderBy`, `offset` > 0, windowed aggregates, `@jarenjs/linq`'s nested two-level `groupBy` emission, non-canonical group returns | **re-run on invalidation**, the reason named | the previous result, for diffing |
 
 The **physical mapping** of a `derive: 'bbox'` index (MODEL-FORMAT §2.1,
@@ -310,8 +313,8 @@ refuses at registration (`JD0051`), the same shape as capture's
 demanded session — an application that needs the property can refuse
 to start.
 
-The **canonical group form** the classifier recognises (and the only
-one — the linq chain's nested emission re-runs, stated plainly):
+The **canonical group form** the classifier recognises (the linq chain's group-of-groups emission still re-runs; explicit
+nested groups have a separate bounded strategy below):
 
 ```json
 { "$for": { "it": "$[*]" },
@@ -502,13 +505,14 @@ ERRORING rather than degrading (the D14 rule — the bound is printed):
   delete-correctness, and a count over a table larger than the bound
   is a conscious `maxMaintained` raise, not a silent one.
 
-Non-claims, in one place: no incremental joins (re-run is the declared
-strategy), no cross-connection invalidation (§6's `data_version` is
+Non-claims, in one place: no maintenance of unindexed or non-equality joins,
+no cross-connection invalidation (§6's `data_version` is
 the signal), no maintenance over asynchronous connections —
 `capabilities.live` is `false` there and a registration is `JD0051`
 naming the reason, because maintenance point-reads rows synchronously
 inside delivery (the wasm driver's oo1 API is synchronous, which is
-why the browser has live queries at all) — no replication, and no ordering guarantee for
+why the browser has live queries at all). Replication is specified separately in
+[REPLICATION-FORMAT](REPLICATION-FORMAT.md). There is no ordering guarantee for
 unordered queries beyond §9's determinism.
 
 ## 13. Event time
@@ -616,3 +620,40 @@ holds a shuffled stream of inserts, in-place updates, instant moves and
 deletes against `resampleSeries` / `rollingSeries` over the whole
 collection after each one, which is the only oracle that cannot drift
 with the implementation.
+
+
+## Bounded joins, graph projections and nested groups
+
+`join`, `graph` and `nested-group` strategies charge their source rows and
+result entries to `live.maxMaintained`, and serialized input/output payloads to
+`live.maxBytes` (default 4 MiB). These credits bound cached payloads rather than
+claiming to measure JavaScript heap overhead. Initialization uses a limited
+source read; updates read changed keys, then visit cached indexed dependencies.
+Bounds are checked while caches grow. Overflow is `JD2060`, emits one error,
+closes the subscription and releases dependency caches. It never relabels an
+unbounded query as incremental.
+
+Entity equality columns need a primary-key prefix, declared index or mapped
+foreign-key index. Every binding needs a key and a distinct root. The projected
+identity is the tuple of source identities, so duplicate projected values remain
+distinct. Default entity result order follows physical row insertion order;
+point reads preserve that order even when a key is deleted and reinserted. A
+left join uses a canonical `$allowing-empty` binding over an equality-filtered
+inner subquery. Its absent child can be defaulted to null. Graph projections
+embed equality-filtered child queries in a single outer row's return object.
+Global-root reads outside those bindings re-run because changing one row can
+change every projected graph.
+
+`dependencyReads`, `refreshedRoots` and `refreshedGroups` expose the work done.
+`dependencyReads` counts logical changed-row reads; a row-position lookup is an
+additional statement. No full query reruns occur under these strategy labels.
+Materializing and diffing the final bounded output still costs work proportional
+to its size. See the equal-correctness [measurements](REPLICATION-FORMAT.md#measurements)
+for startup and high-fan-out losses beside selective wins.
+
+Two-level grouping currently accepts an explicit parent `$groupby` over a
+singular member, with one nested group over that parent's bound row sequence.
+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.

package/docs/MIGRATION-FORMAT.md

@@ -235,25 +235,34 @@ hash of the `baseline` model when no migration has run.
 
   | strategy | which assertions | what it costs |
   |---|---|---|
-  | per-document | a FLWOR over `$[*]` whose `$where`/`$return` read only the binding | one keyset batch at a time; fails fast at the first batch that violates |
-  | fold | exactly one of `$count`, `$sum`, `$min`, `$max` over the root | one batch at a time; each batch is answered by the ENGINE and the partial answers combine |
-  | materialize | everything else (`$let`, `$distinct`, a nested `$for`, two aggregates) | every document at once, under `assertionBounds` |
-
-  A fold is sound because the operator is associative: the answer over a
-  collection is the combination of the answers over any partition of it.
-  Nothing reimplements an operator — each batch is evaluated by the same
-  compiled query the whole-collection path would use, and only the
-  COMBINE step is written here, so null handling, empty-sequence answers
-  and type coercions are the engine's. A suite runs every fold shape both
-  ways, over ten corpora and six partitions, and requires the value and
-  the verdict to be indistinguishable; a shape that cannot pass it is not
-  in the set.
+  | provider | a collection `$count` that the existing query planner proves native without a typed intermediate schema | one aggregate result, with no assertion document fetch |
+  | per-document | an independent, unwindowed FLWOR over `$[*]`, with the default empty-sequence expectation | one keyset batch; fails at the first violation |
+  | fold | `$count`, `$sum`, `$avg`, `$min`, `$max` over a partition-independent operand; sequence EBV of an independent FLWOR | one batch plus fixed accumulator state |
+  | fold with bounds | `$distinct` over such an operand with an explicit positive `maxDistinct` | one batch plus unique items under cardinality and byte bounds |
+  | materialize | global or positional operands, nested scans, unsupported shapes, or unbounded distinct | the collection under `assertionBounds` |
+
+  Folds feed the operand's sequence items, in original order, into the
+  query engine's shared accumulator. Floating-point addition is **not
+  associative**: combining batch totals changes answers. The ordered state
+  preserves the whole-query result, including singleton arrays, negative
+  zero, NaN, mixed-type refusals and Unicode code-point ordering. Sequence
+  EBV is checked once across all batches, including an empty source.
+  `$[0]`, root-dependent filters and positional bindings never qualify as
+  independent merely because they occur inside an aggregate.
+
+  `classifyAssertion(query, { expect, maxDistinct })` exposes the portable
+  strategy. `onAssertionPlan(plan)` reports migration, step, collection,
+  strategy, shape, reason and bounds before the assertion reads documents;
+  Store dry-run query statements also expose strategy and reason. Provider
+  promotion reuses the query planner with no assumed typed columns. Typed
+  SQL aggregates still need a trustworthy intermediate schema and proof
+  that their numeric/order semantics match; otherwise the ordered fold runs.
 
   **A materializing assertion is bounded.** `options.assertionBounds`
   defaults to `{ maxRows: 100000, maxBytes: 67108864 }` and is crossed
   BEFORE the excess is held — the walk stops at the row that would break
   it, refusing `JD2007` (rows) or `JD2076` (bytes) and naming the two
-  assertion shapes that are answered in batches instead. `null` on either
+  assertion strategies that are answered in batches instead. `null` on either
   member removes that bound, which a caller must ask for: an unbounded
   read nobody declared is exactly what this classification removes. This
   is a deliberate behavior change — a migration that used to read a very
@@ -265,14 +274,11 @@ hash of the `baseline` model when no migration has run.
   transformed | derived | asserted }`, one event per batch), and never
   hold the whole collection in memory. A PER-DOCUMENT assertion — a
   FLWOR over `$[*]` whose `$where` and `$return` read only the binding
-  — walks the same batches and fails fast at the first batch that
-  violates, because its answer over each batch is its answer over the
-  whole. A cross-document assertion (one that reads the root: `$count:
-  '$[*]'`, a `$let`, a `$distinct`, a nested `$for`) reads the whole
-  collection into one array — a stated cost; keep such assertions
-  early, before the data grows. A cross-document assertion that is one
-  associative aggregate no longer costs that read at all — see the
-  classification table above.
+  — with the default empty expectation walks the same batches and fails
+  fast. Other assertions follow the classification table above.
+  `batchSize` must be a positive safe integer. `maxDistinct` opts into a
+  distinct fold and bounds retained unique items; `maxBytes` applies to
+  those items. Duplicates do not consume additional cardinality.
 - A transform MUST NOT change a caller-keyed document's key member —
   the key column would go stale; the run refuses (`JD0023`).
 
@@ -510,10 +516,23 @@ jaren-db documents --migrations <dir> --in <file|-> (--out <file|-> | --in-place
   line-delimited, everything else one JSON array) unless `--format` /
   `--out-format` says otherwise, and stdio defaults to JSONL. Input and
   output encodings are independent, so this is also the converter.
-  - **A file holds ONE collection.** The migrations name it; a chain
-    whose document steps touch more than one cannot be applied to a
-    file, and is refused rather than partly run. `--collection` asserts
-    which collection the file holds and refuses a mismatch.
+  - **Named sources share one collection bundle.** Repeat
+    `--in users=users.json --in events=events.jsonl --out migrated.json`.
+    Output defaults to `--out-format collections`: a standard JSON object
+    mapping collection names to arrays, including empty collections.
+    Publication is one atomic rename after every collection succeeds.
+    Multiple source files cannot use `--in-place`, because separate
+    renames cannot give this guarantee. Single-source `--collection`
+    still asserts the collection name and refuses a mismatch.
+  - **A bundle can be read explicitly** with `--format collections`, then
+    replaced using `--in-place --yes`. Bundle input is materialized under
+    a whole-file `maxBytes` ceiling before parsing and per-collection
+    `maxRows` validation after parsing. JSON and JSONL single-collection
+    sources remain streaming. `--max-rows`, `--max-bytes`, and
+    `--max-distinct` configure assertion admission too; the first two
+    accept `none` to remove their limit deliberately. A materializing
+    file run admits rows before retaining them. Physical-step and query
+    compilation refusals precede every input read.
   - **`--out` writes elsewhere; `--in-place` replaces the input and
     needs `--yes`.** Either way the documents land in a sibling
     temporary that is renamed over the target only once every document

package/docs/MODEL-FORMAT.md

@@ -1078,6 +1078,14 @@ 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 |
+| `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 |
+| `JD2102` | the replica identity or model revision disagrees |
+| `JD2103` | a resolver fails its synchronous decision contract |
+| `JD2104` | a logical row or snapshot disagrees with its causal history |
+| `JD2105` | an explicit snapshot reset is required, or reset would discard acknowledged history |
+| `JD2106` | a replication operation or snapshot exceeds its configured bound |
 
 The table above is proven in sync with the runtime `DB_CODES` table by
 a test.

package/docs/REPLICATION-FORMAT.md

@@ -0,0 +1,208 @@
+# Replication format and runtime
+
+`jaren-replication` 0.1 is a transport-neutral logical transaction. Open an empty
+store with `replication: { replica: 'host-issued-id' }`; capture is enabled when
+omitted. Existing replication stores must reopen with the same identity and
+model. Every writer of that file must enable replication. External SQL writes
+and opening a replicated file without replication are outside the history
+contract; a detected before-image disagreement refuses with `JD2104`.
+
+The host owns network transport, authentication, replica identity allocation and
+resolver policy. A replica id must remain unique to its writer lineage. The
+runtime works on SQLite Node, worker and wasm hosts through session or journal
+capture. Drivers without `changeCapture` refuse at open; PostgreSQL capture is
+not implemented. Journal replication refuses models with cascading or set-null
+child foreign keys (`JD0051`), because the journal cannot observe those effects.
+Session capture includes them. Both modes support membership cascades and
+roll back an envelope whose side effects are absent from its logical operations.
+
+## Envelope
+
+```json
+{
+  "$replication": "0.1",
+  "replica": "site-a",
+  "seq": 1,
+  "frontier": {},
+  "model": "application-model-revision",
+  "operations": [
+    { "table": "notes", "key": "note/one", "before": null,
+      "after": { "id": "note/one", "body": "hello" } }
+  ]
+}
+```
+
+`model` is the store's `shapeHash(model)` revision. `seq` is a positive safe
+integer, allocated from the replica's durable frontier in the data transaction.
+The identity is `replicationIdentity(replica, seq)`, the JSON encoding of their
+pair, so separators inside host ids cannot collide. A frontier maps host ids to
+non-negative safe sequences. The sender's frontier entry must equal `seq - 1`,
+with an absent entry meaning zero. Property names such as `__proto__` and
+`constructor` remain ordinary replica ids.
+
+Each operation is one net row transition. `before: null` inserts, `after: null`
+deletes, and two objects replace the complete logical row. A table/key occurs
+once per envelope. Composite keys use the capture format's JSON-array token;
+single keys use their scalar text. Entity documents include mapped scalar and
+foreign-key fields, omit relation projections and retain authored version and
+timestamp values. Membership tables carry their two keys. Application performs
+schema validation through the store's configured validator and reuses physical
+column plans; it does not generate fresh defaults or version stamps.
+
+`normalizeReplication` validates and detaches the document. `encodeReplication`
+produces deterministic JSON. Object members are canonically ordered; operation
+array order remains part of identity. Capture sorts net rows by table/key, making
+physical session and journal output equal. Envelope order preserves transaction
+order. Physical insertion order inside a netted transaction or snapshot is not a
+portable query ordering: use an explicit query order when comparing replicas.
+Receipts retain the entire canonical payload, avoiding hash-collision ambiguity.
+
+Unknown members and versions, empty ids, unsafe sequences, non-JSON values,
+cycles, duplicate net rows and unchanged operations are `JD0060`. Nesting is
+limited to 128 object/array ancestors. JSON Schema artifacts describe structural
+validation; cross-field sequence, uniqueness and causal checks are runtime
+constraints. Current and draft-07 artifacts ship for envelopes and snapshots:
+
+- `@jarenjs/db/schemas/jaren-replication.schema.json`
+- `@jarenjs/db/schemas/jaren-replication.draft-07.schema.json`
+- `@jarenjs/db/schemas/jaren-replication-snapshot.schema.json`
+- `@jarenjs/db/schemas/jaren-replication-snapshot.draft-07.schema.json`
+
+## Applying and exporting
+
+```js
+const source = await openStore(model, {
+  driver, replication: { replica: 'site-a', retention: 1000 }
+});
+const page = await source.replication.page({ after: 0, limit: 100, maxBytes: 1048576 });
+for (const envelope of page.items) {
+  const result = await target.replication.apply(envelope);
+  if (result.status === 'conflict') hostReport(result.conflicts);
+}
+```
+
+`apply` returns `applied`, `duplicate` or `conflict`, together with the committed
+frontier and conflict records. Successful duplicate delivery performs no row
+write or live emission. An acknowledged identity with different bytes is
+`JD2101`. A sequence or causal gap is `JD2100`: no suffix is applied. Deliver
+missing envelopes first, then retry, or perform an explicit reset. Model mismatch
+is `JD2102`. Imported envelopes keep their original identity and produce no local
+outbox entry, preventing echoes. A host forwarding between peers must preserve
+the original envelopes; `page()` exports this replica's own commits only.
+
+Data, receipt, per-row causal metadata, capture record and frontier settle in
+the same transaction. Replication is available only on the root Store; transaction
+views expose no replication API. Failed validation, cancellation, constraint checks or
+commit roll everything back. Subscribers run through the existing committed
+capture delivery path. Tests kill a process immediately before and after commit
+and verify both data and frontier after reopening.
+
+Pages use the shared cursor and byte-credit drain. `limit` counts whole envelopes;
+`maxBytes` counts complete canonical envelope bytes. An indivisible oversize
+envelope is `JD2074`. Retention loss returns `resetRequired: true`, no items and
+no continuation. `earliestAvailable`, `highWatermark`, `next` and `hasMore` describe
+the local outbox. Pages and snapshots take a consistent store transaction.
+`signal` and `deadline` are honored through existing cancellation contracts:
+queue cancellation is `JD2064`, operation-boundary cancellation `JD2072`, and an
+expired deadline `JD2075`.
+
+Defaults are `retention: 1000`, `maxOperations: 10000`, `maxBytes: 4194304`.
+Operation overflow is `JD2106`; all credits are positive safe integers. Retention
+prunes only outgoing envelope history. Replay receipts, row tombstones and
+conflict evidence remain durable. They are deliberately not claimed to be a
+bounded total database size. Internal tables use the reserved `_jaren_replica`
+prefix. No schema migration or revision rewrite of this protocol is implicit.
+
+## Conflicts
+
+Concurrent incompatible whole-row writes reject by default. A `conflict` result
+does not acknowledge the remote envelope and leaves the local row intact.
+`replication.conflicts({ limit, maxBytes, signal, deadline })` reads persisted evidence: the common base,
+local value and frontier, remote value and envelope position, resolver identity
+and decision. A rejected envelope reserves its canonical identity too, so retries
+cannot replace its contender with different content.
+
+An optional `replication.resolver` has `{ id, resolve }`. Its synchronous pure
+function receives frozen evidence and returns `{ action: 'local' }`,
+`{ action: 'remote' }`, or `{ action: 'merged', value }`; a merged value may be
+null for deletion. Invalid decisions refuse with `JD2103`. Both contenders and
+the resolver id are retained for every resolution. No resolver is bundled.
+Determinism and convergence of a custom policy are the host's responsibility:
+choosing the receiver's local value on each replica is deterministic but does
+not make replicas agree. Independent non-conflicting deliveries converge without
+resolver policy. Concurrent changes to different fields of the same row are
+conservatively whole-row conflicts in this version.
+
+## Reset handshake
+
+`source.replication.snapshot()` returns a `jaren-replication-snapshot` 0.1
+document containing `model`, `frontier`, logical `rows` with their causal
+frontiers, and complete acknowledged `receipts`.
+`target.replication.reset(snapshot)` validates and atomically installs it while
+emitting ordinary live invalidations. The snapshot must dominate all target
+acknowledgements and preserve every known receipt's bytes. It cannot discard
+unsynchronized local history (`JD2105`) or rewrite identities (`JD2101`).
+Snapshot receipt sequences must completely cover their frontier, and row
+frontiers cannot be ahead of it. Subsequent duplicate deliveries remain
+verifiable because the receipts travel with the snapshot.
+
+Resets are intentionally bounded single documents: rows plus receipts must fit
+`maxOperations`, and the complete encoding must fit `maxBytes`. Snapshot and
+conflict readers pull through the shared cursor and stop before accumulating
+beyond the configured credits. Resolver outputs and conflict evidence also
+obey `maxBytes`. Very large
+histories require a separately designed paged snapshot/receipt compaction
+protocol; this implementation refuses them rather than splicing partial state.
+A reset preserves the receiver's own replica identity and clears its outgoing
+history. Future writes continue its sequence from the imported frontier.
+
+## Authoring
+
+`@jarenjs/linq/db` exports a deterministic pen using the same validator:
+
+```js
+const envelope = defineReplication({ replica: 'site-a', seq: 1,
+  frontier: {}, model: revision })
+  .change('notes', 'one', null, { id: 'one', body: 'hello' })
+  .toDocument();
+```
+
+The pen snapshots its input and emits the same canonical bytes as hand-authored
+JSON. Normal applications export committed Store envelopes; constructing an
+envelope does not allocate or acknowledge a Store sequence.
+
+## Measurements
+
+Run `npm run benchmark:changeflow`. Every timed mutation is followed by a fresh
+query and a patch-only consumer comparison; every measured mutation changes its
+visible result. Graph measurements mutate a child of one owner. Replication deliveries compare
+complete database state, including relations. Conflict timings retry one
+rejected contender and assert unchanged data/frontier plus durable evidence. Timing includes capture and live
+delivery; oracle time is reported separately. Heap deltas are uncollected
+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.
+
+| 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 |
+
+| 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 |
+
+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.
+
+<!--/fact-->

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.66.1",
+  "version": "0.72.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.66.1",
-    "@jarenjs/json": "^0.66.1",
-    "@jarenjs/validate": "^0.66.1"
+    "@jarenjs/core": "^0.72.0",
+    "@jarenjs/json": "^0.72.0",
+    "@jarenjs/validate": "^0.72.0"
   },
   "bin": {
     "jaren-db": "./src/cli.js"