@jarenjs/db 0.56.0 → 0.67.0

package/docs/LIVE-FORMAT.md

@@ -118,19 +118,85 @@ const records = await store.changesSince(lastSeq);  // JD2051 when no log
 ```
 
 `seq` is monotonic; with the log enabled the DATABASE allocates it —
-each record's `seq` is `MAX(seq) + 1` computed inside the insert
-statement and read back through `RETURNING` — so two stores over one
-file never collide on the log's key and each sees the other's
-sequence continue; without the log it is per-process. `changesSince`
+one statement, inside the write's own transaction, advances a durable
+singleton row (`_jaren_changes_state`, the highest sequence this file
+ever allocated) and reads the new value back through `RETURNING`, and
+the record is then inserted under it — so two stores over one file
+never collide on the log's key, each sees the other's sequence continue,
+and a write that rolls back takes its allocation back with its row. The
+state row is engine metadata: it is created beside the log, seeded once
+from an existing file's surviving `MAX(seq)` (0 for a file that never
+held a row; a later open changes nothing), never lowered, never pruned,
+and never a capture, live, model or migration subject. Without the log,
+`seq` is per-process. `changesSince`
 answers records in the shape observers receive, `collections`
 included; a cursor that is not a number is a `TypeError`, as is a
 `retention` that is not a positive integer. Retention is
 a bounded count (`retention`, default 1000): older rows are pruned in
-the same transaction. The log is an ordered, replayable stream —
-which is what makes a late-joining consumer possible. **Replication
-is not built here**, and this log alone does not make it safe: there
-is no conflict resolution, no site identity, no causal ordering
-across writers. That sentence is the whole claim.
+the same transaction — every write deletes the records more than
+`retention` behind the one it just appended, and nothing else prunes
+the log. The log is an ordered, replayable stream — which is what
+makes a late-joining consumer possible.
+
+**`changesSince` is unbounded, and unsafe for a reconnecting
+consumer.** It answers every surviving record in one array, with no
+limit, no byte bound and no watermark: a consumer whose last `seq` fell
+below the retention floor receives the suffix that happens to survive
+and cannot distinguish "everything you missed" from "some of what you
+missed, and the rest is gone" — it believes itself caught up with a
+hole in its state. It stays as a published member, and it is not the
+supported path for a consumer that reconnects.
+
+**The bounded reader: `store.changes`.** Present exactly when the log
+is enabled (`JD2051` otherwise, as `changesSince`).
+
+- `changes.bounds()` answers the two watermarks: `earliestAvailable`,
+  the earliest surviving sequence (`MIN(seq)` over the log; `null` when
+  nothing survives), and `highWatermark`, the highest sequence the FILE
+  ever allocated, read from the durable state row — so a log that
+  retention emptied, reopened in a new process, still answers
+  `{ earliestAvailable: null, highWatermark: N }` and a cursor below `N`
+  meets `resetRequired` rather than a plausible empty history. Both are
+  the file's facts, never a process counter or a clock; cheap, and what a
+  consumer needs before it decides whether its cursor is usable.
+- `changes.page({ after, limit, maxBytes, signal })` answers
+  `{ items, next, earliestAvailable, highWatermark, hasMore,
+  resetRequired }`. `after` is the last sequence seen and is required:
+  there is no legitimate "give me everything" for a change log. The
+  page never holds more than `limit` records (default 100, applied as
+  SQL `LIMIT`) nor more than `maxBytes` serialised patch bytes,
+  accumulated at record boundaries; a single record larger than
+  `maxBytes` is the refusal `JD2074` without advancing `next` — the
+  same rule and the same implementation an entity page uses
+  (MODEL-FORMAT §10.5). `hasMore` is decided by one peek past the
+  page; `next` is the sequence to continue from (`after` itself when
+  nothing was delivered); `signal` cancels at a record boundary
+  (`JD2072`).
+- **`resetRequired: true`** when the record after `after` no longer
+  survives — `after + 1 < earliestAvailable` (or the log is empty
+  above `after`'s successor). Then `items` is **empty** and `next` is
+  **absent**: the refusal is total, because a partial suffix beside a
+  reset flag would invite a consumer to use both. The watermarks are
+  read after the rows, so a floor that rose during the read can only
+  make the verdict stricter, never let a pruned gap pass as a
+  continuation.
+
+**The consumer's recovery procedure**, in words: keep the last `seq`
+you applied; on reconnect, call `changes.page({ after: lastSeq })` and
+apply pages while `hasMore`, storing `next` as you go; when a page
+answers `resetRequired: true`, stop applying — your state has a hole —
+re-seed it from a full snapshot of the collections you follow, and
+resume paging from that page's `highWatermark`, because every record
+at or below it is already reflected in the snapshot you just took.
+Choosing how much history to keep is the host's decision
+(`retention`); what the reader owes is that when rows go, it reports
+the gap instead of hiding it.
+
+**Replication is not built here**, and this log alone does not make
+it safe: there is no conflict resolution, no site identity, no causal
+ordering across writers. The bounded reader with its watermarks and
+its explicit gap is the precondition a replication protocol would be
+built on — not the protocol. That sentence is the whole claim.
 
 ## 6. Cross-connection behaviour and non-claims
 
@@ -168,7 +234,17 @@ live.close();
 `store.live(document, options)` registers an entity-root document (the
 multi-entity shape of MODEL-FORMAT §10) the same way. Live queries
 REQUIRE change capture — the patch stream is the invalidation source —
-and registering on a store opened without `capture` is `JD0050`.
+and registering on a store opened without `capture` is `JD0050`. Both
+registrations run under the store gate through their **initial query**
+(MODEL-FORMAT §5.1): a registration made while another transaction is
+open waits for it to settle and initializes from committed rows only, a
+rolled-back row never reaches `result`, and a refused registration
+leaves `stats().liveQueries` unchanged. A registration made from INSIDE
+a transaction view initializes from that transaction's rows and shares
+its fate — kept and maintained on commit, closed on rollback. Once
+registered, the handle is maintained by committed writes alone and takes
+no gate of its own. `changes.page()` takes the same `deadline` every
+other page does (`JD2075` at a record boundary).
 
 A producer may hand a registration a CHAIN instead of a document: the
 `@jarenjs/linq/db` client's `live(chain, options)` passes the chain's
@@ -197,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,
@@ -234,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": "$[*]" },
@@ -353,8 +432,11 @@ Decided by a platform fact: OPFS synchronous access handles are
 all, so "one connection per tab" is not available and never will be.
 Therefore:
 
-- ONE owning context holds the sole connection — a `SharedWorker`
-  where available, else a leader tab elected via `navigator.locks` —
+- ONE owning context holds the sole connection — the first tab's
+  dedicated worker to install the OPFS access-handle pool owns it (the
+  pool is exclusive by construction) and holds a `navigator.locks` lock
+  for its lifetime so a later tab can tell a busy owner from no owner
+  (a `BroadcastChannel` ping is the fallback where locks are absent) —
   and every other tab is a client;
 - queries, writes and the patch stream travel between clients and the
   owner over `BroadcastChannel` / `MessagePort`; a client's live query
@@ -367,8 +449,37 @@ Therefore:
 Node and Bun present the same API with no channel at all — the store
 is its own owner, and application code is identical everywhere. The
 in-browser proof of this topology (delivery across real tabs, the
-refusal, reload survival) belongs to the browser-driver order and its
-Playwright suite; this section is the decided contract it implements.
+refusal, reload survival) is the website's Playwright suite over the
+`#/data` studio; this section is the decided contract it implements.
+
+The wasm session adapter performs an actual disposable create/attach/changeset/delete
+probe. It declares sessions only after success; `sessionReason` explains journal
+fallback. Changeset bytes are detached from wasm-owned memory before transfer, and
+capture cleanup deletes every session even on rollback or connection close.
+
+The studio probes isolated SharedArrayBuffer OPFS, header-free SAH-pool OPFS,
+atomic IndexedDB snapshots, then visibly non-durable memory. IndexedDB snapshots
+require exclusive ownership and acknowledge writes after atomic version replacement.
+They expose no synchronous/live surface; the Store pane explicitly refreshes after
+writes. Failed snapshot persistence invalidates the connection without publishing
+partial state. [Execution hosts](HOSTS.md) specifies bounds and the observed matrix.
+
+**The browser boot is a closed protocol.** Reaching an owner, a client
+or a standalone memory store passes through five named stages —
+`worker-start`, `sqlite-init`, `vfs-acquire`, `topology`,
+`store-open` — and every attempt ends in exactly one of two states:
+ready, or a stable failure record `{ code: 'DATA_BOOT', stage, message }`
+naming the stage that failed. Each stage carries its own budget, so a
+stage that never settles fails under its own name rather than under an
+outer deadline that cannot say which resource to release; an OPFS pool
+that is absent advances to the next persistence probe; an existing owner
+produces the `client` answer above, while a pool install that hangs is a `vfs-acquire` failure
+and never masquerades as absence. A failed attempt releases everything it
+created — worker, port client, channel, listeners, timers — before the
+page hears of it, so a retry (or a reload) starts clean, and the page
+shows the stage and offers the retry. The stage runner is
+`packages/website/src/lib/boot-stages.js`; the site's transport and its
+owner worker are the two halves that run it.
 
 ## 12. Lifecycle, bounds, and non-goals
 
@@ -394,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
@@ -508,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

@@ -166,8 +166,12 @@ store untouched.
 
 The shadow runs over an empty data set; the real-data facts (the
 widening check, key consistency, the assertions over real rows) run on
-the real store inside its transaction. The shadow registers the same
-functions as the real run: `migrate(…, { registerFunctions })` runs on
+the real store inside its transaction. Batched transforms and validation
+include every row identity, including negative integer primary keys;
+target-schema validation visits every declared entity, even after an
+empty entity table.
+The shadow registers the same functions as the real run:
+`migrate(…, { registerFunctions })` runs on
 the shadow, the real and the reference connections before any DDL
 (§10), so a hand-created index over a registered deterministic
 function neither fails the shadow nor is silently dropped by it.
@@ -204,26 +208,115 @@ hash of the `baseline` model when no migration has run.
   an empty history, so a dry run may be pointed at a production
   database and leave its file byte-identical. The API default is to
   run; a CLI SHOULD default to the dry run.
-- `migrationStatus` (and the CLI's `status`/`check`) create the empty
-  history table on a database that has none — the one write a reading
-  command makes, so a fresh file answers `applied: (none)` rather than
-  a missing-table error. This is the one place the two differ: a dry
-  run reports the same state and writes nothing at all.
+- `migrationStatus` (and the CLI's `status`/`check`) write nothing
+  either: the history table is probed, never created, and an absent one
+  reads as an empty history, so a fresh file answers `applied: (none)`
+  and stays byte for byte what it was. The history table is created by
+  the real run alone, before its first migration is recorded.
 - Each pending migration runs in ONE exclusive transaction
   (`BEGIN IMMEDIATE` on SQLite — concurrent writers wait or time out
   under the busy timeout) with a savepoint per step; any failure rolls
   back the whole migration including its earlier steps. Where a driver
   cannot open exclusively, the transaction still isolates; the busy
   policy of MODEL-FORMAT §4 governs contention.
+- A run is cancellable: `migrate(target, migrations, { signal,
+  deadline })` checks both BETWEEN migrations, between steps and
+  between the batches of a data step — never inside a statement, which
+  runs to its end — with the deadline read against `options.runtime`'s
+  clock. An abort is `JD2080` and a passed deadline `JD2075`; the
+  migration in flight rolls back whole (its savepoints, its history
+  row), the migrations already committed stand, and a rerun resumes
+  from the recorded position. The shadow replay is cancellable at the
+  same boundaries. `migrationStatus` refuses a call already cancelled
+  or past its deadline before it opens anything.
+- **An assertion is classified before it runs, and the classification
+  decides what it costs.** One classifier answers for every host — a
+  Store, an array, a file — so they cannot disagree about the price:
+
+  | 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.
+
+  **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
+  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
+  large collection whole now refuses until its bound is raised or its
+  assertion is rewritten.
 - JSLT steps walk the collection in bounded batches
   (`options.batchSize`, default 500) ordered by row identity, report
-  progress through `options.onProgress`, and never hold the whole
-  collection in memory. Assertion steps read the whole collection into
-  one array — a documented cost; keep assertions early, before the
-  data grows.
+  progress through `options.onProgress` (`{ migration, collection,
+  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.
 - A transform MUST NOT change a caller-keyed document's key member —
   the key column would go stale; the run refuses (`JD0023`).
 
+### 6.1 Running without a database
+
+A migration's `jslt` and `query` steps act on DOCUMENTS, so they do not
+need tables. Two surfaces run them against documents a caller already
+holds, sharing one implementation of what a step means with the Store —
+the same transform rule, the same key rule, the same classification of
+an assertion, the same refusals in the same words.
+
+- `migrateDocuments({ collection: [...] }, migrations, options)` answers
+  `{ documents, report }`. The source is REWINDABLE, so every step runs
+  over the whole collection before the next begins, exactly as a Store
+  runs it. This is what makes its answer — and its refusal, on the same
+  step — identical to the Store's for the same documents.
+- `streamDocuments({ collection: iterable }, migrations, { write })`
+  walks a source that can be read only once, writing each document out
+  as it finishes. The input is consumed exactly once and nothing beyond
+  one batch is held, so a collection larger than memory still migrates.
+
+Both refuse, BEFORE asking for the first document, any step this host
+cannot honour (`JD0023`):
+
+| Step kind | Without a database |
+|---|---|
+| `jslt`, `query` | runs |
+| `ddl`, `sql`, `rebuild`, `derive` | refused by name — no tables to change |
+
+A step naming a collection the caller did not supply is refused the same
+way. Nothing is half-applied: a runner without a transaction cannot take
+a partial write back, so the whole refusal happens before the first read.
+
+Two limits are the single pass's, and are stated rather than hidden:
+
+- A CROSS-DOCUMENT assertion needs every document at once, which one
+  pass does not hold. `streamDocuments` refuses it by name; run that
+  collection through `migrateDocuments`, whose source it can re-read.
+- When two different steps would each refuse, `migrateDocuments` and the
+  Store name the EARLIER step, because each step finishes before the
+  next begins. `streamDocuments` carries a batch through every step, so
+  it can name the later one. Both refuse, with the same code and the
+  same words; only which step is named can differ.
+
 ## 7. Non-goals
 
 - **Down migrations are not shipped in 0.1.** A JSLT transform is not
@@ -247,6 +340,7 @@ hash of the `baseline` model when no migration has run.
 | `JD0021` | the migration is missing a required data transform |
 | `JD0022` | an applied migration disagrees with the history record |
 | `JD0023` | a migration step failed |
+| `JD0024` | a document source or target could not be read or written |
 
 These live in the same runtime `DB_CODES` table as the storage codes
 (MODEL-FORMAT §7); the union of both documents is proven in sync with
@@ -351,13 +445,17 @@ jaren-db status   --model <model> --store <db> --baseline <model> [--migrations
 jaren-db apply    --store <db> --baseline <model> --migrations <dir> [--model <m>] [--dry-run] [--yes]
 jaren-db check    --model <model> --store <db> --baseline <model> [--migrations <dir>] [--snapshot <file>]
 jaren-db shape    --model <model>
+jaren-db documents --migrations <dir> --in <file|-> (--out <file|-> | --in-place --yes | --check)
+                   [--format json|jsonl] [--out-format json|jsonl] [--collection <name>]
+                   [--batch-size <n>]
 ```
 
 - **A model or a migration is a `.json` file or a MODULE.** `--model`,
   `--from`, `--to` and `--baseline` accept a `.json` file or a module
   (`.js`, `.mjs`, `.cjs` — and `.ts` where the host strips types: Node
   ≥ 24 does by default, and `--no-strip-types` is refused by name)
-  loaded with `import()` and read as its `default` export or its `model`
+  loaded through `@jarenjs/json/node` — the suite's one document loader,
+  shared with `jaren-contract` — and read as its `default` export or its `model`
   export — the model pen's document, or any object whose `toJSON()`
   emits one; `--migrations <dir>` reads `.json` files and modules
   (`default` or `migration` — the migration pen's builder), sorted by
@@ -400,13 +498,40 @@ jaren-db shape    --model <model>
   `apply` without `--yes` exits 1 after the printout with nothing
   applied — a CI job passes `--yes` deliberately, never by default.
   `apply --dry-run` is the CLI's printout, not §6's `dryRun: true`: it
-  reads the history the way `status` does — creating the empty table on
-  a database that has none — and does NOT replay the chain on the
-  shadow, so a draft step still prints instead of refusing. The
-  shadow's verdict comes with the real `apply`.
+  reads the history the way `status` does — probed, never created — and
+  does NOT replay the chain on the shadow, so a draft step still prints
+  instead of refusing. The shadow's verdict comes with the real `apply`.
 - `status` lists applied/pending and reports drift (§12); on a
-  database without a history table it creates the empty one (§6).
+  database without a history table it creates nothing (§6).
 - `shape` prints the physical mapping a model produces.
+- `documents` runs a migration's DOCUMENT steps over a file instead of a
+  database — §6.1's runners, given a path or stdio. `--in`/`--out` take
+  a file or `-`; the encoding follows the extension (`.jsonl`/`.ndjson`
+  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.
+  - **`--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
+    has survived every step. A failure — a step, a malformed source, a
+    cancelled run — removes the temporary and leaves the target byte for
+    byte as it was.
+  - **`--check` transforms and validates everything and writes nothing**,
+    which is the CI shape: it answers whether this chain still applies
+    to this data.
+  - **Three exit codes, three meanings:** `0` the chain applies and every
+    assertion holds; `1` the run failed (a step refused, the source was
+    malformed, the file was missing, a step needs a database); `2` the
+    command line itself was wrong (a missing or contradictory flag, an
+    unknown format). A script can tell "you asked for the wrong thing"
+    from "what you asked for does not hold".
+  - The report names the strategy §6.1 chose — `streamed`, or
+    `materialized` when a cross-document assertion needs the collection
+    at once.
 
 ## 12. Drift