@jarenjs/linq 0.86.0 → 0.89.0

package/README.md

@@ -387,6 +387,14 @@ model that moved without a plan (`jaren-db check`). The mapping table
 and the worked examples are
 [docs/MIGRATION-PEN.md](docs/MIGRATION-PEN.md).
 
+For existing physical tables, `.step({ kind: 'table', plan })` preserves
+the complete guarded `planTableMigration` artifact. `fromPlanned` keeps the
+physical source/dispositions/assertions/target header. An optional `{ model }`
+on `transform` or `assert` selects the layout at that point in the chain,
+including an old name absent from the final model. Execution, complete target
+acceptance, fixture replay and receipts remain in db; the pen imports no engine.
+See the [runnable physical lifecycle](../db/docs/MIGRATION-FORMAT.md#runnable-physical-lifecycle).
+
 ## By code: the contract pen
 
 `@jarenjs/linq/contract` writes `$contract` 0.1 documents — the

package/docs/DB-CLIENT.md

@@ -843,10 +843,10 @@ never builds one; the migration between two of them is
 
 ## 7. Cost
 
-`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->724,181<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->728,423<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.db.kb-->724<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.db.kb-->728<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 It is by far the largest of the ten, and the reason is §1.1's edge rather

package/docs/JSLT-PEN.md

@@ -948,7 +948,7 @@ source. That makes it the SMALLEST of the nine pen bundles, and the
 reason is that a stylesheet is mostly bodies, and a body is the shared
 machine every pen already pays for.
 
-Two figures worth reading beside it: `./migration` (<!--fact:bundle.migration-->22,827<!--/fact--> bytes)
+Two figures worth reading beside it: `./migration` (<!--fact:bundle.migration-->23,806<!--/fact--> bytes)
 carries this pen's `body()` and pays for it, which is why the two prices
 sit so close; and `./flow` (<!--fact:bundle.flow-->18,478<!--/fact--> bytes) is within 60 bytes of this one
 despite writing two formats, because it shares the same capture and adds

package/docs/LINQ-FORMAT.md

@@ -36,12 +36,12 @@ is the index of those guides, and it is how a reader reaches any of them.
 <!--fact:pens.index-->
 | Document | Lines | What it writes, and when to open it |
 |---|---:|---|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 944 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 945 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
 | [QUERY-PEN.md](QUERY-PEN.md) | 1,761 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 1,205 | `./schema` — JSON Schema 2020-12: the structural keywords, the constraints and the annotations, each with a method of its own, plus `$query`, `$defs`/`$ref` recursion and the normalizer's per-field predicates. **Read it when** you are describing the shape of data — for validation, for a form, or as the base of an entity |
 | [MODEL-PEN.md](MODEL-PEN.md) | 1,116 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
 | [JSLT-PEN.md](JSLT-PEN.md) | 955 | `./jslt` — `$jslt` 0.1 stylesheets: the envelope and its rules, whose bodies are captured over the matched value. **Read it when** you are transforming one document into another |
-| [MIGRATION-PEN.md](MIGRATION-PEN.md) | 781 | `./migration` — `$migration` 0.1 documents: the two shape hashes and the ordered steps the runner takes. **Read it when** you are moving a store from one model to the next |
+| [MIGRATION-PEN.md](MIGRATION-PEN.md) | 808 | `./migration` — `$migration` 0.1 documents: the two shape hashes and the ordered steps the runner takes. **Read it when** you are moving a store from one model to the next |
 | [CONTRACT-PEN.md](CONTRACT-PEN.md) | 1,221 | `./contract` — `$contract` 0.1 documents: the operations, their schemas, their declared behavior and their REST binding. **Read it when** you are declaring an API and want its client, its server and its tools typed from one document |
 | [FLOW-PEN.md](FLOW-PEN.md) | 1,033 | `./flow` — `jaren-fsm` 0.1 machines and `jaren-dag` 0.1 dataflows, every query-valued member captured. **Read it when** you are declaring a state machine or a dependency graph of tasks |
 | [APP-PEN.md](APP-PEN.md) | 1,143 | `./app` — the `jaren-app` 0.1 document `createApp` runs, and the JSON Schema of its state beside it. **Read it when** you are declaring a whole application: state, view, actions, effects |
@@ -203,12 +203,12 @@ and the bundle is the byte count the tree-shaking probe builds.
 <!--fact:pens.census-->
 | Document | Subpath | Lines | Mapping rows | Worked examples | Refusals | Bundle |
 |---|---|---:|---:|---:|---:|---:|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 944 | — | — | — | — |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 945 | — | — | — | — |
 | [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,761 | 34 | 8 | 15 | 175,560 B |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,205 | 82 | 10 | 4 | 35,285 B |
 | [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,116 | 30 | 6 | 3 | 44,143 B |
 | [JSLT-PEN.md](JSLT-PEN.md) | `./jslt` | 955 | 17 | 8 | 3 | 18,424 B |
-| [MIGRATION-PEN.md](MIGRATION-PEN.md) | `./migration` | 781 | 11 | 5 | 4 | 22,827 B |
+| [MIGRATION-PEN.md](MIGRATION-PEN.md) | `./migration` | 808 | 12 | 5 | 4 | 23,806 B |
 | [CONTRACT-PEN.md](CONTRACT-PEN.md) | `./contract` | 1,221 | 38 | 6 | 3 | 47,427 B |
 | [FLOW-PEN.md](FLOW-PEN.md) | `./flow` | 1,033 | 16 | 7 | 3 | 18,478 B |
 | [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 49,574 B |
@@ -217,9 +217,9 @@ and the bundle is the byte count the tree-shaking probe builds.
 | [JTLT-PEN.md](JTLT-PEN.md) | `./jtlt` | 83 | 13 | 1 | 2 | 15,293 B |
 | [PROJECT-PEN.md](PROJECT-PEN.md) | `./project` | 81 | 9 | 1 | 1 | 13,793 B |
 | [CHARTS-PEN.md](CHARTS-PEN.md) | `./charts` | 94 | 21 | 1 | 1 | 15,582 B |
-| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 1,085 | 46 | 4 | 2 | 724,181 B |
+| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 1,085 | 46 | 4 | 2 | 728,423 B |
 | [FORMULA-PEN.md](FORMULA-PEN.md) | `./formula` | 41 | 2 | — | — | 14,850 B |
-| **16 documents** | | **12,588** | **368** | **72** | | |
+| **16 documents** | | **12,616** | **369** | **72** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -265,7 +265,7 @@ it and each document publishes it. The rounded column is what
 | `@jarenjs/linq/schema` | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 35,285 B | 35 kB |
 | `@jarenjs/linq/model` | [MODEL-PEN.md](MODEL-PEN.md) | 44,143 B | 44 kB |
 | `@jarenjs/linq/jslt` | [JSLT-PEN.md](JSLT-PEN.md) | 18,424 B | 18 kB |
-| `@jarenjs/linq/migration` | [MIGRATION-PEN.md](MIGRATION-PEN.md) | 22,827 B | 23 kB |
+| `@jarenjs/linq/migration` | [MIGRATION-PEN.md](MIGRATION-PEN.md) | 23,806 B | 24 kB |
 | `@jarenjs/linq/contract` | [CONTRACT-PEN.md](CONTRACT-PEN.md) | 47,427 B | 47 kB |
 | `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 18,478 B | 18 kB |
 | `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 49,574 B | 50 kB |
@@ -274,7 +274,7 @@ it and each document publishes it. The rounded column is what
 | `@jarenjs/linq/jtlt` | [JTLT-PEN.md](JTLT-PEN.md) | 15,293 B | 15 kB |
 | `@jarenjs/linq/project` | [PROJECT-PEN.md](PROJECT-PEN.md) | 13,793 B | 14 kB |
 | `@jarenjs/linq/charts` | [CHARTS-PEN.md](CHARTS-PEN.md) | 15,582 B | 16 kB |
-| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 724,181 B | 724 kB |
+| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 728,423 B | 728 kB |
 | `@jarenjs/linq/formula` | [FORMULA-PEN.md](FORMULA-PEN.md) | 14,850 B | 15 kB |
 <!--/fact-->
 
@@ -597,10 +597,11 @@ it says.
 | `.transform(name, (row, x) => …)` | `{ kind: 'jslt', collection: name, stylesheet: [{ match: '$', body }] }` — one root rule, the body captured through the JSLT pen's `body()` over the WHOLE row, `x.root`/`x.path` the externals the engine binds (JSLT-FORMAT §8.2) | `row` is `Expr<Old>` (`DocOf<From, name>`); the result must spell `New` — a dropped, mistyped or foreign member does not compile; the honest top (`get()`) is admitted where a precise value is | native; a table the target model does not declare `JL0106`; an undeclared external `JL0104` |
 | `.transform(name, stylesheet(…))`, `.transform(name, rules)` | the rules ARRAY — a `jslt` step carries the array, so the envelope's `unmatched`/`modes` have no place in it | a typed stylesheet's or first rule's `Out` must be `New`; a hand-written rule is the honest top | native; a disposition or a mode table `JL0102`; not JSON `JL0101` |
 | `.assert(name, (row) => …, { expect? })` | `{ kind: 'query', collection: name, assert: { $for: { it: '$[*]' }, $where: <predicate>, $return: '$it' }, expect? }` — the format's own `$for` over the rows; the predicate names the VIOLATION (`expect: 'empty'`, the default, absent from the document) or the witness (`expect: 'ebv'`) | `row` is the members the two shapes share — a precondition sees old rows, a postcondition new ones, and what both agree on is what neither lies about; annotate (`(row: Expr<User>) => …`) when one shape is meant | native; another `expect` `JL0101`; an external `JL0104`; an undeclared table `JL0106` |
-| `.assert(name, query, { expect? })` | the query document verbatim | — | native |
+| `.assert(name, query, { expect?, model? })` | the query document verbatim, plus an optional current model | — | native |
+| `.transform(name, spelling, { model })`, `.assert(name, spelling, { model, expect? })` | the ordinary step plus an immutable current `$model` document | transform input/output and assertion rows use this model's layout; names may be absent from the final model | native; an invalid model `JL0101`; a name absent from the selected model `JL0106` |
 | `.derive(name, columns)` | `{ kind: 'derive', collection: name, columns }` — a backfill of stored derived columns (§2.1), the columns verbatim | `readonly DeriveColumn[]` | native; no columns `JL0101`; an undeclared table `JL0106` |
-| `.step(raw)` | any planner-emitted step, verbatim — the escape that keeps `rebuild` (§10) authorable without the pen re-implementing it; a `draft` flag rides untouched | `MigrationStep` | native; an unrecognised kind or a missing member (the runner's `JD0023` rules, seen early) `JL0101` |
-| `fromPlanned(document, { from?, to? })` | the planner's document, taken up: `.transform(name, …)` replaces its draft for `name` in place; every other method appends | the models type the transforms and are checked against the document's hashes | native; a model that is not the planned one `JL0102`; two drafts for one name, or no draft and no target model `JL0106` |
+| `.step(raw)` | any planner-emitted step, including a complete guarded `{ kind: 'table', plan }` or a hybrid `rebuild`; a `draft` flag rides untouched | `MigrationStep`, including `TableStep`/`ReviewedTablePlan` | native; an unrecognised kind or incomplete plan/step `JL0101` |
+| `fromPlanned(document, { from?, to? })` | the planner's document, including its `physical` header and complete saved plans; `.transform(name, …)` replaces its draft in place, and other methods append | the models type transforms and are checked against the hashes | native; a model that is not the planned one `JL0102`; two drafts for one name, or no draft and neither target nor step model `JL0106` |
 | `.document`, `.toJSON()` | the deep-frozen `$migration` document — assembled once and memoized, so `a.document === a.document` | `MigrationDocument` | native |
 
 ### The Jaren contract pen — [CONTRACT-PEN.md §2](CONTRACT-PEN.md)

package/docs/MIGRATION-PEN.md

@@ -114,19 +114,16 @@ naming the reason).
 | `.transform(name, (row, x) => …)` | `{ kind: 'jslt', collection: name, stylesheet: [{ match: '$', body }] }` — one root rule, the body captured through the JSLT pen's `body()` over the WHOLE row, `x.root`/`x.path` the externals the engine binds (JSLT-FORMAT §8.2) | `row` is `Expr<Old>` (`DocOf<From, name>`); the result must spell `New` — a dropped, mistyped or foreign member does not compile; the honest top (`get()`) is admitted where a precise value is | native; a table the target model does not declare `JL0106`; an undeclared external `JL0104` |
 | `.transform(name, stylesheet(…))`, `.transform(name, rules)` | the rules ARRAY — a `jslt` step carries the array, so the envelope's `unmatched`/`modes` have no place in it | a typed stylesheet's or first rule's `Out` must be `New`; a hand-written rule is the honest top | native; a disposition or a mode table `JL0102`; not JSON `JL0101` |
 | `.assert(name, (row) => …, { expect? })` | `{ kind: 'query', collection: name, assert: { $for: { it: '$[*]' }, $where: <predicate>, $return: '$it' }, expect? }` — the format's own `$for` over the rows; the predicate names the VIOLATION (`expect: 'empty'`, the default, absent from the document) or the witness (`expect: 'ebv'`) | `row` is the members the two shapes share — a precondition sees old rows, a postcondition new ones, and what both agree on is what neither lies about; annotate (`(row: Expr<User>) => …`) when one shape is meant | native; another `expect` `JL0101`; an external `JL0104`; an undeclared table `JL0106` |
-| `.assert(name, query, { expect? })` | the query document verbatim | — | native |
+| `.assert(name, query, { expect?, model? })` | the query document verbatim, plus an optional current model | — | native |
+| `.transform(name, spelling, { model })`, `.assert(name, spelling, { model, expect? })` | the ordinary step plus an immutable current `$model` document | transform input/output and assertion rows use this model's layout; names may be absent from the final model | native; an invalid model `JL0101`; a name absent from the selected model `JL0106` |
 | `.derive(name, columns)` | `{ kind: 'derive', collection: name, columns }` — a backfill of stored derived columns (§2.1), the columns verbatim | `readonly DeriveColumn[]` | native; no columns `JL0101`; an undeclared table `JL0106` |
-| `.step(raw)` | any planner-emitted step, verbatim — the escape that keeps `rebuild` (§10) authorable without the pen re-implementing it; a `draft` flag rides untouched | `MigrationStep` | native; an unrecognised kind or a missing member (the runner's `JD0023` rules, seen early) `JL0101` |
-| `fromPlanned(document, { from?, to? })` | the planner's document, taken up: `.transform(name, …)` replaces its draft for `name` in place; every other method appends | the models type the transforms and are checked against the document's hashes | native; a model that is not the planned one `JL0102`; two drafts for one name, or no draft and no target model `JL0106` |
+| `.step(raw)` | any planner-emitted step, including a complete guarded `{ kind: 'table', plan }` or a hybrid `rebuild`; a `draft` flag rides untouched | `MigrationStep`, including `TableStep`/`ReviewedTablePlan` | native; an unrecognised kind or incomplete plan/step `JL0101` |
+| `fromPlanned(document, { from?, to? })` | the planner's document, including its `physical` header and complete saved plans; `.transform(name, …)` replaces its draft in place, and other methods append | the models type transforms and are checked against the hashes | native; a model that is not the planned one `JL0102`; two drafts for one name, or no draft and neither target nor step model `JL0106` |
 | `.document`, `.toJSON()` | the deep-frozen `$migration` document — assembled once and memoized, so `a.document === a.document` | `MigrationDocument` | native |
 
-**This table is complete, and deliberately short.** Ten callable names
-against eleven rows: the step vocabulary of `$migration` 0.1 is six kinds
-(`ddl`, `jslt`, `query`, `derive`, `sql`, `rebuild`), five of them have a
-method here and the sixth is `step()`. What makes this pen worth reading
-is not the size of its surface but what each step is checked against —
-§4 is the richest refusal section in the family relative to the pen's
-size, and it is the reason.
+The `$migration` 0.1 vocabulary has seven kinds: `ddl`, `jslt`, `query`,
+`derive`, `sql`, `rebuild` and `table`. The two structural artifact kinds use
+`step()`; the pen preserves their plans without implementing SQL execution.
 
 Three rules the table implies, spelled out:
 
@@ -137,13 +134,11 @@ Three rules the table implies, spelled out:
   instruction, not shape, so a model that keeps carrying a satisfied hint
   hashes the same as one without it and plans nothing (MIGRATION-FORMAT
   §3 — a rename is idempotent across `plan` runs).
-- **A step's table is one the target model declares.** The runner would
-  fail the statement on a table that does not exist; the pen says so
-  first (`JL0106`) — for `transform`, `assert` and `derive` alike,
-  whenever it knows the target. Entities and collections both count as
-  declared. Over a planned document alone it knows only the drafts, so
-  every other name is the runner's to judge and a transform for another
-  table is spelled with `step()`.
+- **A step's name belongs to its selected model.** `transform` and
+  `assert` use an explicit `{ model }` when supplied, or the known target
+  otherwise; `derive` uses the target. Entities and collections both count.
+  A planned transform with no draft and no known model refuses `JL0106`;
+  supply its current model or spell the raw step explicitly.
 - **Steps are appended in the order they are called**, and `transform`
   over a planned document is the one exception: it replaces the draft for
   that name IN PLACE, so the planner's ordering — DDL before the data
@@ -480,7 +475,7 @@ else.
 | `m().assert('User', p, { other: 1 })` | `assert() does not take 'other'` | `{ expect }` |
 | `m().assert('User', undefined)` | `assert() takes a predicate (row) => … or a query document over the rows` | a predicate |
 | `m().derive('User', [])` | `derive() takes a non-empty array of derived-column records ({ name, derive, segments }), got a Array instance` | the columns the planner emitted |
-| `m().step({ kind: 'nope' })`, `m().step(42)` | `step() takes a migration step with a recognised kind (ddl, jslt, query, derive, sql, rebuild), got kind a string` | one of the six kinds |
+| `m().step({ kind: 'nope' })`, `m().step(42)` | `step() takes a migration step with a recognised kind (ddl, jslt, query, derive, sql, rebuild, table), got kind a string` | one of the seven kinds |
 | `m().step({ kind: 'rebuild', table: 'User' })` | `step() 'rebuild' needs 'create' (MIGRATION-FORMAT §2)` — `docPath` `/create` | the rendered parts |
 | `m().step({ kind: 'sql' })` | `step() 'sql' needs 'sql' (MIGRATION-FORMAT §2)` — `docPath` `/sql` | the statement |
 | `m().step({ kind: 'jslt', collection: 'User' })` | `step() 'jslt' needs 'stylesheet' (MIGRATION-FORMAT §2)` — `docPath` `/stylesheet` | a rules array |
@@ -532,8 +527,9 @@ exactly what it must not have.
 
 This pen's own code. Two conditions, and no other pen raises either.
 
-**A step naming a table the target model does not declare.** Checked for
-`transform`, `assert` and `derive`, whenever the target model is known.
+**A step naming a table its selected model does not declare.** Checked for
+`transform` and `assert` against an explicit current model when supplied,
+or the known target otherwise. `derive` checks the known target.
 
 | The spelling that trips it | The message | The spelling that works |
 |---|---|---|
@@ -553,20 +549,20 @@ no steps, so there is never a draft.
 
 | The spelling that trips it | The message | The spelling that works |
 |---|---|---|
-| `fromPlanned(planned).transform('Nope', fn)` — no models given | `transform() over 'Nope': the planned migration drafts no transform for it and no target model was given — pass { to } to fromPlanned(), or spell the step with step()` | `fromPlanned(planned, { from: v1, to: v2 })`, or `.step({ kind: 'jslt', … })` |
+| `fromPlanned(planned).transform('Nope', fn)` — no models given | `transform() over 'Nope': the planned migration drafts no transform for it and no target model or explicit step model was given — pass { model } to transform(), { to } to fromPlanned(), or spell the step with step()` | supply the current `{ model }`, give `fromPlanned` its `{ to }`, or use `.step({ kind: 'jslt', … })` |
 | `fromPlanned(twoDrafts).transform('User', fn)` | `transform() cannot tell which draft to replace: the planned migration carries 2 draft transforms for 'User'` | edit the planned document down to one draft per table, or replace them with `step()` calls |
 
 The first is not a mistake so much as a missing fact: without a target
 model the pen knows only which tables the planner drafted, so a name it
 has never seen could be a typo or could be perfectly good. It refuses and
-names both ways out rather than guessing. The second cannot arise from
+names the available ways to supply that fact. The second cannot arise from
 `jaren-db plan`, which drafts at most one transform per table; it arises
 when a planned document is edited or two are concatenated, and a pen that
 picked one would be picking which of the author's two transforms to
 throw away.
 
-Note what is NOT checked: with no target model, `ddl`, `sql`, `assert`,
-`derive` and `step` take any identifier, and the runner judges. That is
+With neither a target nor an explicit step model, `ddl`, `sql`, `assert`,
+`derive` and `step` leave undeclared-name checks to the runner. That is
 the honest position — the pen refuses what it can see, and it cannot see
 a model it was not given.
 
@@ -609,6 +605,14 @@ over old rows and a postcondition over new ones, and the pen cannot know
 which this one is, so what both agree on is what neither lies about;
 annotate (`(u: Expr<NewUser>) => …`) when one shape is meant.
 
+An explicit `{ model: current }` overrides these default type readings.
+The transform row and result both use `DocOf<typeof current, name>`;
+an assertion reads that current shape. `fromPlanned` retains the entire
+physical header as immutable JSON. Db's generic `PhysicalMigrationDocument`
+preserves supplied step types, so `fromPlanned(await planPhysicalMigration(...))`
+composes directly when the steps are typed. Unknown saved input remains
+unknown until validated; incomplete table artifacts do not gain missing guards.
+
 ### 5.2 The honest limits, and the two routes past them
 
 **From a JSON snapshot the old row is `unknown`.** A JSON literal is
@@ -674,6 +678,27 @@ be re-implementing the planner. The alternative for all three is the same
 one the format intends: let `jaren-db plan` render them, and take the
 document up with `fromPlanned`.
 
+`table` also uses `step()`, carrying the entire reviewed
+`planTableMigration` artifact. Its `source`, `after`, row/storage and identity
+guards must not be replaced by a loop over `statements` and `finish`.
+The pen checks the complete artifact's structure and preserves it; db checks
+the source/checksum and executes its guarded transaction.
+
+Historical models can precede and follow that structural step:
+
+```js
+const steps = defineMigration({ id: 'upgrade', from: before, to: after })
+  .transform('Item', (row) => ({ id: row.id, value: row.value.upper() }), { model: before })
+  .step({ kind: 'table', plan: reviewedTablePlan })
+  .assert('Item', (row) => row.revision.lt(1), { model: after }).document.steps;
+```
+
+The [runnable db example](../../db/docs/MIGRATION-FORMAT.md#runnable-physical-lifecycle)
+supplies the complete model/table declarations, reviewed target fixture,
+physical dispositions, populated replay and checked second startup. Synthetic
+fixture rows stay outside the shared migration document. Physical model diffing
+still refuses changed declarations; the author reviews structural plans.
+
 ### 6.2 `defineMigration` does not validate a migration against a database
 
 This is the sentence a reader most needs, because believing otherwise
@@ -687,8 +712,10 @@ below is `@jarenjs/db`'s `migrate()`, and none of it has happened when
 - **The shadow replay.** Before the real store is touched, the WHOLE
   chain — baseline, applied and pending — replays on a shadow database:
   every DDL statement runs, every stylesheet and assertion compiles and
-  executes, and the end shape is verified against the target model
-  (MIGRATION-FORMAT §4). A step the pen accepted and SQLite rejects fails
+  executes, and the selected model or complete physical target is checked.
+  `shadowFixture` may initialize an application-owned historical schema;
+  replay still uses the same migration/history executor (MIGRATION-FORMAT §4).
+  A step the pen accepted and SQLite rejects fails
   there, with the real store untouched.
 - **The widening/narrowing check against real data.** At the end of the
   run, inside its transaction, every stored document is validated against
@@ -745,10 +772,10 @@ from a drop plus a create, and guessing risks silent data loss.
 
 ## 7. Cost
 
-`@jarenjs/linq/migration` builds to **<!--fact:bundle.migration-->22,827<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/migration` builds to **<!--fact:bundle.migration-->23,806<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.migration.kb-->23<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.migration.kb-->24<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 The probe is a gate, not a report: building a two-step migration as a

package/docs/QUERY-PEN.md

@@ -1717,7 +1717,7 @@ making:
 `docs/CONSUMING.md` states the rounded price of all ten subpaths in one
 table, each figure held equal to the same measurements. Two of its rows
 are the ones to read together: the chain at <!--fact:bundle.chain.kb-->176<!--/fact--> kB and
-`./db` at <!--fact:bundle.db.kb-->724<!--/fact--> kB.
+`./db` at <!--fact:bundle.db.kb-->728<!--/fact--> kB.
 The client costs what the store costs, by construction, and the chain
 costs what running a query costs.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.86.0",
+  "version": "0.89.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -108,13 +108,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.86.0",
-    "@jarenjs/json": "^0.86.0"
+    "@jarenjs/core": "^0.89.0",
+    "@jarenjs/json": "^0.89.0"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.86.0",
-    "@jarenjs/formats": "^0.86.0",
-    "@jarenjs/validate": "^0.86.0"
+    "@jarenjs/db": "^0.89.0",
+    "@jarenjs/formats": "^0.89.0",
+    "@jarenjs/validate": "^0.89.0"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/migration/define.js

@@ -10,7 +10,7 @@
  * and nothing here ever clears a `draft` flag: a draft left in place
  * still refuses to run (`JD0021`, the runner's rule). The pen refuses
  * what it cannot spell and what the runner would refuse later and the
- * pen can see now — a step over a table the target model does not
+ * pen can see now — a step over a table the selected model does not
  * declare (`JL0106`).
  */
 
@@ -25,7 +25,7 @@ import {
 } from './steps.js';
 
 const MIGRATION_VERSION = '0.1';
-const HEAD_MEMBERS = ['$migration', 'id', 'from', 'to', 'note', 'steps'];
+const HEAD_MEMBERS = ['$migration', 'id', 'from', 'to', 'note', 'steps', 'physical'];
 
 /** A JSON value, copied: the document is a value of its own. @param {any} v */
 const copy = (v) => JSON.parse(JSON.stringify(v));
@@ -132,14 +132,14 @@ export class Migration {
     return this.#with([...this.#steps, step]);
   }
 
-  /** A step's table must be one the target model declares — when the
-   * target is known; the runner would fail the statement on a table
-   * that does not exist, and the pen can say so first. */
-  #requireDeclared(name, what) {
-    if (this.#names !== null && !this.#names.includes(name)) {
+  /** A step's table must be one its explicit current model or the known
+   * target model declares; the pen catches a missing name before execution. */
+  #requireDeclared(name, what, model = undefined) {
+    const names = model === undefined ? this.#names : declaredNames(model);
+    if (names !== null && !names.includes(name)) {
       throw new LinqBuildError('JL0106',
-        `${what} names '${name}', which the target model does not declare — it declares `
-        + (this.#names.length === 0 ? 'nothing' : this.#names.map((n) => `'${n}'`).join(', ')));
+        `${what} names '${name}', which the ${model === undefined ? 'target' : 'step'} model does not declare — it declares `
+        + (names.length === 0 ? 'nothing' : names.map((n) => `'${n}'`).join(', ')));
     }
   }
 
@@ -156,15 +156,17 @@ export class Migration {
   /**
    * The transform of one table's rows (a `jslt` step). Over a planned
    * document it REPLACES the draft the planner left for that table, in
-   * place; otherwise it is appended, for a table the target model
-   * declares. Two drafts for one name, a draft-less planned document with
-   * no target model, or an undeclared name are `JL0106`.
+   * place; otherwise it is appended, for a table the explicit current or
+   * target model declares. Two drafts for one name, a draft-less planned
+   * document with neither model, or an undeclared name are `JL0106`.
    * @param {string} name
    * @param {any} spelling - a callback `(row, x) => …`, a `stylesheet(…)`
    *   document, or a rules array
+   * @param {{ model?: any }} [options] - The layout at this step, before later DDL
    */
-  transform(name, spelling) {
-    const step = transformStep(name, spelling);
+  transform(name, spelling, options = undefined) {
+    const step = transformStep(name, spelling, options);
+    if (step.model !== undefined) this.#requireDeclared(name, 'transform()', step.model);
     const drafts = [];
     this.#steps.forEach((s, i) => {
       if (s.kind === 'jslt' && s.draft === true && s.collection === name) drafts.push(i);
@@ -179,12 +181,12 @@ export class Migration {
       next[drafts[0]] = step;
       return this.#with(next);
     }
-    if (this.#names === null) {
+    if (this.#names === null && step.model === undefined) {
       throw new LinqBuildError('JL0106',
         `transform() over '${name}': the planned migration drafts no transform for it and no `
-        + 'target model was given — pass { to } to fromPlanned(), or spell the step with step()');
+        + 'target model or explicit step model was given — pass { model } to transform(), { to } to fromPlanned(), or spell the step with step()');
     }
-    this.#requireDeclared(name, 'transform()');
+    this.#requireDeclared(name, 'transform()', step.model);
     return this.#append(step);
   }
 
@@ -192,11 +194,11 @@ export class Migration {
    * An assertion over one table's rows (a `query` step).
    * @param {string} name
    * @param {any} spelling - a predicate `(row) => …`, or a query document
-   * @param {{ expect?: 'empty' | 'ebv' }} [options]
+   * @param {{ expect?: 'empty' | 'ebv', model?: any }} [options]
    */
   assert(name, spelling, options = undefined) {
     const step = assertStep(name, spelling, options);
-    this.#requireDeclared(name, 'assert()');
+    this.#requireDeclared(name, 'assert()', step.model);
     return this.#append(step);
   }
 
@@ -314,5 +316,13 @@ export function fromPlanned(document, options = undefined) {
     }
     head.note = doc.note;
   }
+  if (doc.physical !== undefined) {
+    if (!isJsonObject(doc.physical) || !Array.isArray(doc.physical.source)
+      || !isJsonObject(doc.physical.dispositions) || !Array.isArray(doc.physical.assertions)) {
+      throw new LinqBuildError('JL0101',
+        'fromPlanned() physical header needs source, dispositions and assertions', '/physical');
+    }
+    head.physical = doc.physical;
+  }
   return new Migration(head, doc.steps.map((step) => rawStep(step)), names);
 }

package/src/migration/steps.js

@@ -20,7 +20,7 @@ import { describeValue, requireJson } from '../json-boundary.js';
 import { LinqBuildError } from '../errors.js';
 
 /** The kinds the runner accepts, in the artifact's order. */
-const STEP_KINDS = ['ddl', 'jslt', 'query', 'derive', 'sql', 'rebuild'];
+const STEP_KINDS = ['ddl', 'jslt', 'query', 'derive', 'sql', 'rebuild', 'table'];
 const EXPECTS = ['empty', 'ebv'];
 const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** An assertion evaluates with no externals: `p.x` cannot appear. */
@@ -61,6 +61,15 @@ function readNote(note, what) {
   return note;
 }
 
+/** A current layout travels as immutable JSON, without importing the model pen. */
+function withModel(step, model) {
+  if (model === undefined) return step;
+  const doc = requireJson(model, 'step model');
+  if (!isJsonObject(doc) || doc.$model !== '0.1')
+    throw new LinqBuildError('JL0101', 'a step model must be a $model 0.1 document');
+  return { ...step, model: copy(doc) };
+}
+
 /** The externals proxy an assertion's predicate sees: nothing. */
 const NO_EXTERNALS = new Proxy(Object.freeze({}), {
   get(_target, prop) {
@@ -104,8 +113,10 @@ export function sqlStep(sql, note = undefined) {
  * @param {string} name
  * @param {any} spelling
  */
-export function transformStep(name, spelling) {
+export function transformStep(name, spelling, options = undefined) {
   requireName(name, 'transform()');
+  if (options !== undefined && (!isJsonObject(options) || Object.keys(options).some((key) => key !== 'model')))
+    throw new LinqBuildError('JL0101', 'transform() options are { model? }');
   let stylesheet;
   if (typeof spelling === 'function') {
     stylesheet = [{ match: '$', body: body(spelling) }];
@@ -133,7 +144,7 @@ export function transformStep(name, spelling) {
       'transform() takes a callback (row, x) => …, a stylesheet(…) document or a rules array, '
       + `got ${describeValue(spelling)}`);
   }
-  return { kind: 'jslt', collection: name, stylesheet };
+  return withModel({ kind: 'jslt', collection: name, stylesheet }, options?.model);
 }
 
 /**
@@ -145,7 +156,7 @@ export function transformStep(name, spelling) {
  * are the witness. A document is taken verbatim.
  * @param {string} name
  * @param {any} spelling
- * @param {{ expect?: 'empty' | 'ebv' }} [options]
+ * @param {{ expect?: 'empty' | 'ebv', model?: any }} [options]
  */
 export function assertStep(name, spelling, options = undefined) {
   requireName(name, 'assert()');
@@ -155,7 +166,7 @@ export function assertStep(name, spelling, options = undefined) {
       throw new LinqBuildError('JL0101', `assert() options are { expect? }, got ${describeValue(options)}`);
     }
     for (const key of Object.keys(options)) {
-      if (key !== 'expect') throw new LinqBuildError('JL0101', `assert() does not take '${key}'`);
+      if (key !== 'expect' && key !== 'model') throw new LinqBuildError('JL0101', `assert() does not take '${key}'`);
     }
     if (options.expect !== undefined) {
       if (!EXPECTS.includes(options.expect)) {
@@ -180,7 +191,7 @@ export function assertStep(name, spelling, options = undefined) {
   }
   const out = { kind: 'query', collection: name, assert: query };
   if (expect === 'ebv') out.expect = 'ebv';
-  return out;
+  return withModel(out, options?.model);
 }
 
 /**
@@ -219,6 +230,14 @@ export function rawStep(step) {
     }
   };
   switch (raw.kind) {
+    case 'table':
+      need('plan', isJsonObject(raw.plan) && raw.plan.version === 1
+        && ['id', 'table', 'checksum', 'temporary'].every((key) => typeof raw.plan[key] === 'string' && raw.plan[key].length > 0)
+        && typeof raw.plan.rebuild === 'boolean'
+        && ['source', 'after'].every((key) => Array.isArray(raw.plan[key]) && raw.plan[key].every(isJsonObject))
+        && ['unchanged', 'statements', 'finish'].every((key) => Array.isArray(raw.plan[key])
+          && raw.plan[key].every((value) => typeof value === 'string' && value.length > 0)));
+      break;
     case 'ddl': case 'sql':
       need('sql', typeof raw.sql === 'string' && raw.sql !== '');
       break;
@@ -240,5 +259,5 @@ export function rawStep(step) {
       need('copy', typeof raw.copy === 'string');
       need('indexes', Array.isArray(raw.indexes));
   }
-  return raw;
+  return ['jslt', 'query'].includes(raw.kind) ? withModel(raw, raw.model) : raw;
 }

package/types/migration.d.ts

@@ -18,6 +18,8 @@
  * assertion's row is typed by the members the two shapes SHARE (a
  * precondition sees old rows, a postcondition new ones; what both agree
  * on is what neither lies about), annotated when one shape is meant.
+ * With an explicit step `model`, transform input/output and assertion
+ * rows use that model's layout, including names absent from the final model.
  * Every claim here has a runtime twin in
  * `test/linq/migration-pen.test.js` and a compile-level pin in
  * `test/consumer/linq-migration.ts`.
@@ -39,6 +41,8 @@ export interface JsltStep {
   /** A planner placeholder; the runner refuses it (`JD0021`). The pen never sets or clears it. */
   readonly draft?: boolean;
   readonly note?: string;
+  /** The immutable model for this step's current layout. */
+  readonly model?: object;
 }
 export interface QueryStep {
   readonly kind: 'query';
@@ -46,6 +50,7 @@ export interface QueryStep {
   readonly assert: Json;
   readonly expect?: 'empty' | 'ebv';
   readonly note?: string;
+  readonly model?: object;
 }
 export interface DeriveColumn {
   readonly name: string;
@@ -69,7 +74,39 @@ export interface RebuildStep {
   readonly indexes: readonly string[];
   readonly note?: string;
 }
-export type MigrationStep = DdlStep | SqlStep | JsltStep | QueryStep | DeriveStep | RebuildStep;
+/** The complete serializable artifact returned by planTableMigration. */
+export interface ReviewedTablePlan {
+  readonly version: 1;
+  readonly id: string;
+  readonly table: string;
+  readonly checksum: string;
+  readonly source: readonly unknown[];
+  readonly after: readonly unknown[];
+  readonly rebuild: boolean;
+  readonly temporary: string;
+  readonly unchanged: readonly string[];
+  readonly statements: readonly string[];
+  readonly finish: readonly string[];
+}
+export interface TableStep {
+  readonly kind: 'table';
+  readonly plan: ReviewedTablePlan;
+  readonly note?: string;
+}
+export type MigrationStep = DdlStep | SqlStep | JsltStep | QueryStep | DeriveStep | RebuildStep | TableStep;
+
+export interface PhysicalObject {
+  readonly type: 'table' | 'view' | 'index' | 'trigger';
+  readonly name: string;
+  readonly owner: string;
+  readonly sql: string | null;
+}
+export interface PhysicalHeader {
+  readonly source: readonly PhysicalObject[];
+  readonly dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
+  readonly assertions: readonly { readonly sql: string; readonly params?: readonly unknown[]; readonly expected: readonly unknown[] }[];
+  readonly target?: { readonly objects: readonly PhysicalObject[]; readonly tables?: readonly string[] };
+}
 
 /** The `$migration` 0.1 document (MIGRATION-FORMAT §2). */
 export interface MigrationDocument {
@@ -79,6 +116,7 @@ export interface MigrationDocument {
   readonly to: string;
   readonly note?: string;
   readonly steps: readonly MigrationStep[];
+  readonly physical?: PhysicalHeader;
 }
 
 // ————— what a model document types —————
@@ -124,7 +162,11 @@ export type SheetFor<S, New> = S extends { readonly __out: infer O }
   ? (unknown extends O ? unknown : O extends New ? unknown : never)
   : unknown;
 
-export interface AssertOptions {
+export interface TransformOptions<Current = never> {
+  /** Override the final model with the layout at this step. */
+  readonly model?: Current;
+}
+export interface AssertOptions<Current = never> extends TransformOptions<Current> {
   /** `'empty'` (the default, absent from the document): no row may
    * satisfy the predicate — it names the violation; `'ebv'`: the matching
    * rows are the witness. */
@@ -141,6 +183,22 @@ export class Migration<From = unknown, To = unknown> {
   ddl(sql: string, note?: string): Migration<From, To>;
   /** One data statement spelled directly (`sql`, MIGRATION-FORMAT §9.4). */
   sql(sql: string, note?: string): Migration<From, To>;
+  /** With an explicit current model, both the row and result use that layout. */
+  transform<Current extends object, N extends DeclaredNames<Current>, V extends ExprBase<unknown> = MemberExpr<DocOf<Current, N>>>(
+    name: N,
+    rule: (row: V, x: Externals<{}, ValueOf<V>>) => Spell<DocOf<Current, N>>,
+    options: TransformOptions<Current> & { readonly model: Current },
+  ): Migration<From, To>;
+  transform<Current extends object, N extends DeclaredNames<Current>, S extends StylesheetLike>(
+    name: N,
+    stylesheet: S & SheetFor<S, DocOf<Current, N>>,
+    options: TransformOptions<Current> & { readonly model: Current },
+  ): Migration<From, To>;
+  transform<Current extends object, N extends DeclaredNames<Current>, const R extends readonly RuleDocument[]>(
+    name: N,
+    rules: R & RulesFor<R, DocOf<Current, N>>,
+    options: TransformOptions<Current> & { readonly model: Current },
+  ): Migration<From, To>;
   /** A `jslt` step: one root rule captured over the OLD row (`root`/`path`
    * as externals), whose result spells the NEW row. Over a planned
    * document it replaces the draft for `name`; otherwise it is appended
@@ -148,6 +206,7 @@ export class Migration<From = unknown, To = unknown> {
   transform<N extends DeclaredNames<To>, V extends ExprBase<unknown> = MemberExpr<DocOf<From, N>>>(
     name: N,
     rule: (row: V, x: Externals<{}, ValueOf<V>>) => Spell<DocOf<To, N>>,
+    options?: TransformOptions,
   ): Migration<From, To>;
   /** A `stylesheet(…)` document — its output must be the new row when it
    * is typed; a hand-written envelope is the honest top. A disposition or
@@ -155,12 +214,23 @@ export class Migration<From = unknown, To = unknown> {
   transform<N extends DeclaredNames<To>, S extends StylesheetLike>(
     name: N,
     stylesheet: S & SheetFor<S, DocOf<To, N>>,
+    options?: TransformOptions,
   ): Migration<From, To>;
   /** A rules array: a typed first rule must produce the new row; a
    * hand-written rule is the honest top. */
   transform<N extends DeclaredNames<To>, const R extends readonly RuleDocument[]>(
     name: N,
     rules: R & RulesFor<R, DocOf<To, N>>,
+    options?: TransformOptions,
+  ): Migration<From, To>;
+  /** An explicit current model types a historical assertion's row. */
+  assert<Current extends object, N extends DeclaredNames<Current>, V extends ExprBase<unknown> = MemberExpr<DocOf<Current, N>>>(
+    name: N,
+    predicate: (row: V) => BoolExpr | boolean,
+    options: AssertOptions<Current> & { readonly model: Current },
+  ): Migration<From, To>;
+  assert<Current extends object, N extends DeclaredNames<Current>>(
+    name: N, query: Json, options: AssertOptions<Current> & { readonly model: Current },
   ): Migration<From, To>;
   /** A `query` step over `name`'s rows: the predicate names the VIOLATION
    * (`expect: 'empty'`, the default) or the witness (`'ebv'`); the row is