@jarenjs/linq 0.49.2 → 0.66.1

package/src/jslt/rules.js

@@ -0,0 +1,202 @@
+//@ts-check
+/**
+ * @file `rule()` and `stylesheet()` — the rule object of JSLT-FORMAT
+ * §2.2 and the envelope of §2.1, emitted as plain deep-frozen JSON in
+ * one member order (`mode`, `match`, `priority`, `body`; `$jslt`,
+ * `unmatched`, `modes`, `rules` — the order Appendix A writes). A
+ * `match` is a JSONPath string, `{ path?, schema? }` — the schema a
+ * schema-pen builder or a document — or absent for the unconditional
+ * rule; a body is `body()`'s document, a callback captured as one, or a
+ * query document verbatim. What the pen refuses is what the compiler
+ * would refuse and the pen can already see (`JT0001`–`JT0003`,
+ * mirrored as `JL0101`/`JL0102`); everything else — path syntax, the
+ * body's operators, the schema — is the compiler's.
+ */
+
+import { deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
+import { LinqBuildError } from '../errors.js';
+import { isSchemaBuilder, schemaOf } from '../schema/brand.js';
+import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
+import { body } from './body.js';
+
+const DISPOSITIONS = ['share', 'fresh', 'error'];
+
+/** A JSON value, copied: the document is a value of its own. @param {any} v */
+const copy = (v) => JSON.parse(JSON.stringify(v));
+
+/**
+ * The `match` member (§3.1), or `undefined` for the unconditional rule.
+ * @param {any} match
+ * @returns {any}
+ */
+function readMatch(match) {
+  if (match === undefined || match === null) return undefined;
+  if (typeof match === 'string') return match;
+  if (!isJsonObject(match)) {
+    throw new LinqBuildError('JL0101',
+      `rule() match is a JSONPath string or { path?, schema? }, got ${describeValue(match)}`,
+      '/match');
+  }
+  const keys = Object.keys(match);
+  if (keys.length === 0) {
+    throw new LinqBuildError('JL0102',
+      'rule() match {} would match nothing — write no match for the unconditional rule '
+      + '(JSLT-FORMAT §3.1, the compiler\'s JT0003)', '/match');
+  }
+  for (const key of keys) {
+    if (key !== 'path' && key !== 'schema') {
+      throw new LinqBuildError('JL0101',
+        `rule() match takes 'path' and/or 'schema', not '${key}' (JSLT-FORMAT §3.1)`,
+        `/match/${key}`);
+    }
+  }
+  const out = {};
+  if (match.path !== undefined) {
+    if (typeof match.path !== 'string') {
+      throw new LinqBuildError('JL0101',
+        `rule() match.path is an RFC 9535 query string, got ${describeValue(match.path)}`,
+        '/match/path');
+    }
+    out.path = match.path;
+  }
+  if (match.schema !== undefined) {
+    out.schema = isSchemaBuilder(match.schema)
+      ? schemaOf(match.schema)
+      : copy(requireJson(match.schema, 'rule() match.schema'));
+  }
+  return out;
+}
+
+/**
+ * The `body` member: a callback captured as `body(fn)`, or a document
+ * verbatim (a `body()` result, or a hand-written query document).
+ * @param {any} value
+ */
+function readBody(value) {
+  if (typeof value === 'function') return body(value);
+  if (value === undefined) {
+    throw new LinqBuildError('JL0101',
+      'rule() takes a body: a callback (value, x) => …, body(…), or a query document',
+      '/body');
+  }
+  return copy(requireJson(value, 'rule() body'));
+}
+
+/**
+ * One template rule (§2.2): `{ mode?, match?, priority?, body }`.
+ * @param {any} match - a JSONPath string, `{ path?, schema? }`, or `null`
+ * @param {any} bodyOrFn - `body(…)`, a callback, or a query document
+ * @param {{ mode?: string, priority?: number }} [options]
+ * @returns {any} the rule document, deep-frozen
+ */
+export function rule(match, bodyOrFn, options = undefined) {
+  const out = {};
+  if (options !== undefined) {
+    if (!isJsonObject(options)) {
+      throw new LinqBuildError('JL0101',
+        `rule() options are { mode?, priority? }, got ${describeValue(options)}`);
+    }
+    for (const key of Object.keys(options)) {
+      if (key !== 'mode' && key !== 'priority') {
+        throw new LinqBuildError('JL0101', `rule() does not take '${key}' (JSLT-FORMAT §2.2)`);
+      }
+    }
+    if (options.mode !== undefined) {
+      if (typeof options.mode !== 'string') {
+        throw new LinqBuildError('JL0101',
+          `rule() mode is a string naming the rule's mode, got ${describeValue(options.mode)}`,
+          '/mode');
+      }
+      out.mode = options.mode;
+    }
+  }
+  const m = readMatch(match);
+  if (m !== undefined) out.match = m;
+  if (options !== undefined && options.priority !== undefined) {
+    const p = options.priority;
+    if (typeof p !== 'number' || !Number.isFinite(p) || Object.is(p, -0)) {
+      throw new LinqBuildError('JL0101',
+        `rule() priority is a finite JSON number, got ${describeValue(p)}`, '/priority');
+    }
+    out.priority = p;
+  }
+  out.body = readBody(bodyOrFn);
+  return deepFreeze(out);
+}
+
+/**
+ * A disposition (§5): one of the three, or `JL0101`.
+ * @param {any} value
+ * @param {string} where
+ */
+function readDisposition(value, where) {
+  if (DISPOSITIONS.includes(value)) return value;
+  throw new LinqBuildError('JL0101',
+    `${where} is one of 'share', 'fresh' or 'error' (JSLT-FORMAT §5), got `
+    + `${typeof value === 'string' ? `'${value}'` : describeValue(value)}`, `/${where}`);
+}
+
+/**
+ * The stylesheet envelope (§2.1): `{ $jslt: '0.1', unmatched?, modes?,
+ * rules }`, deep-frozen. (The bare-array form is the rules array
+ * itself; the envelope says what the document is.)
+ * @param {readonly any[]} rules - rule documents, from `rule()` or by hand
+ * @param {{ unmatched?: string, modes?: Record<string, { unmatched: string }> }} [options]
+ * @returns {any} the stylesheet document
+ */
+export function stylesheet(rules, options = undefined) {
+  if (!Array.isArray(rules)) {
+    throw new LinqBuildError('JL0101',
+      `stylesheet() takes an array of rules, got ${describeValue(rules)}`, '/rules');
+  }
+  const out = { $jslt: '0.1' };
+  if (options !== undefined) {
+    if (!isJsonObject(options)) {
+      throw new LinqBuildError('JL0101',
+        `stylesheet() options are { unmatched?, modes? }, got ${describeValue(options)}`);
+    }
+    for (const key of Object.keys(options)) {
+      if (key !== 'unmatched' && key !== 'modes') {
+        throw new LinqBuildError('JL0101',
+          `stylesheet() does not take '${key}' (JSLT-FORMAT §2.1)`);
+      }
+    }
+    if (options.unmatched !== undefined) {
+      out.unmatched = readDisposition(options.unmatched, 'unmatched');
+    }
+    if (options.modes !== undefined) {
+      if (!isJsonObject(options.modes)) {
+        throw new LinqBuildError('JL0101',
+          `stylesheet() modes is { name: { unmatched } }, got ${describeValue(options.modes)}`,
+          '/modes');
+      }
+      requireNameMap(options.modes, 'stylesheet() modes', '/modes');
+      const modes = {};
+      for (const name of Object.keys(options.modes)) {
+        const mode = options.modes[name];
+        if (!isJsonObject(mode) || Object.keys(mode).length !== 1 || mode.unmatched === undefined) {
+          throw new LinqBuildError('JL0101',
+            `stylesheet() mode '${name}' is { unmatched } and nothing else (JSLT-FORMAT §2.1)`,
+            `/modes/${name}`);
+        }
+        setObjectMember(modes, name,
+          { unmatched: readDisposition(mode.unmatched, `modes/${name}/unmatched`) });
+      }
+      out.modes = modes;
+    }
+  }
+  out.rules = rules.map((r, i) => {
+    if (!isJsonObject(r)) {
+      throw new LinqBuildError('JL0101',
+        `stylesheet() rule ${i} is an object — rule(match, body) — got ${describeValue(r)}`,
+        `/rules/${i}`);
+    }
+    if (r.body === undefined) {
+      throw new LinqBuildError('JL0101',
+        `stylesheet() rule ${i} has no body (JSLT-FORMAT §2.2, the compiler's JT0002)`,
+        `/rules/${i}/body`);
+    }
+    return copy(requireJson(r, `stylesheet() rule ${i}`));
+  });
+  return deepFreeze(out);
+}

package/src/json-boundary.js

@@ -0,0 +1,90 @@
+//@ts-check
+/**
+ * @file The JSON boundary every value entering a pen's document crosses
+ * (`JL0101`): a default, a literal, an annotation, a hand-written
+ * schema or query document, a mode name, a priority. One predicate for
+ * every pen — the constant rule of QUERY-PEN §5 ('a captured constant
+ * crosses a real JSON boundary'), applied at the door:
+ * null, booleans, finite numbers (never `-0`), strings, arrays and plain
+ * objects, and nothing else — a function, symbol, bigint, `NaN`,
+ * `±Infinity`, a class instance or a cycle is refused by name.
+ *
+ * Beside it, one predicate for the OTHER door a pen has: the name → value
+ * map it reads its members out of (`requireNameMap`). There the hazard is
+ * not a value the document cannot carry but a member that never arrived —
+ * `{ __proto__: builder }` sets the object's prototype instead of adding
+ * a key — and the prototype is the only trace of it left to refuse by.
+ */
+
+import { isJsonValue } from '@jarenjs/core/object';
+import { LinqBuildError } from './errors.js';
+import { isExpression } from './expression.js';
+
+/**
+ * `-0` is JSON-representable by text and not by value: it shares its
+ * text with `0` while dividing to the opposite infinity, so a document
+ * holding it cannot be keyed, stored or compared faithfully.
+ * @param {any} value
+ * @returns {boolean}
+ */
+function hasNegativeZero(value) {
+  if (typeof value === 'number') return Object.is(value, -0);
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return value.some(hasNegativeZero);
+  return Object.keys(value).some((key) => hasNegativeZero(value[key]));
+}
+
+/** What a refused value is, for a message. `-0` is spelled out: it is
+ * the one value whose `String()` names a DIFFERENT value (`'0'`), so a
+ * reader who greps their source for the literal the message names would
+ * find the wrong one — and it is exactly the value the tail of the
+ * message goes on to forbid by name. @param {any} value */
+export function describeValue(value) {
+  if (value === null) return 'null';
+  if (typeof value === 'number') return Object.is(value, -0) ? '-0' : String(value);
+  if (isExpression(value)) return 'an expression'; // a proxy: reading `.constructor` would record a path
+  if (typeof value === 'object') return `a ${value.constructor?.name ?? 'non-plain'} instance`;
+  return `a ${typeof value}`;
+}
+
+/**
+ * The value, when it is JSON; `JL0101` naming what it was otherwise.
+ * @template T
+ * @param {T} value
+ * @param {string} what - the keyword or method, for the message
+ * @returns {T}
+ */
+export function requireJson(value, what) {
+  if (isJsonValue(value) && !hasNegativeZero(value)) return value;
+  throw new LinqBuildError('JL0101',
+    `${what} received ${describeValue(value)}, which is not JSON — a document carries `
+    + 'null, booleans, finite numbers (never -0), strings, arrays and plain objects, '
+    + 'and nothing else');
+}
+
+/**
+ * A name → value map a pen reads by its OWN keys — an object of
+ * builders, operations, nodes, actions or modes.
+ *
+ * `{ __proto__: x }` in an object LITERAL sets the object's prototype
+ * instead of adding a member, so that member never reaches the pen:
+ * there is nothing to emit and nothing to see. The one thing that IS
+ * visible is the prototype, and no plain map has one — so the map is
+ * refused by it rather than emitted a member short. A computed key
+ * (`{ ['__proto__']: x }`) is an ordinary own property and passes, as
+ * does `Object.create(null)`.
+ *
+ * @template T
+ * @param {T} value - a non-null, non-array object
+ * @param {string} what - the method, for the message
+ * @param {string} [at] - the docPath of the node being assembled
+ * @returns {T}
+ */
+export function requireNameMap(value, what, at) {
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null || proto === Object.prototype) return value;
+  throw new LinqBuildError('JL0101',
+    `${what} received a map whose prototype was replaced: a '__proto__:' key in an object `
+    + 'literal sets the prototype instead of adding a member, so that member is not there to '
+    + "emit — spell it { ['__proto__']: … }, which is an own key", at);
+}

package/src/migration/define.js

@@ -0,0 +1,318 @@
+//@ts-check
+/**
+ * @file `defineMigration()` and `fromPlanned()` — a `$migration` 0.1
+ * document by code (MIGRATION-FORMAT §2). Identity stays the shape hash:
+ * `from`/`to` are `hashContent(canonicalizeJson(model))` with the
+ * `x-rename` planning hints stripped — the store's own rule, pinned equal
+ * to its `shapeHash` by a test over every corpus model. Steps are
+ * appended in the order they are called; a `transform` over a planned
+ * document REPLACES the draft the planner left for that name, in place,
+ * 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
+ * declare (`JL0106`).
+ */
+
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { hashContent } from '@jarenjs/core/string';
+import { deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { describeValue, requireJson } from '../json-boundary.js';
+import {
+  ddlStep, sqlStep, transformStep, assertStep, deriveStep, rawStep,
+} from './steps.js';
+
+const MIGRATION_VERSION = '0.1';
+const HEAD_MEMBERS = ['$migration', 'id', 'from', 'to', 'note', 'steps'];
+
+/** A JSON value, copied: the document is a value of its own. @param {any} v */
+const copy = (v) => JSON.parse(JSON.stringify(v));
+
+/**
+ * The model without its `x-rename` hints. A hint is a PLANNING
+ * instruction, not shape (MIGRATION-FORMAT §3): two models that differ
+ * only by it describe one database and hash the same.
+ * @param {any} model
+ * @returns {any}
+ */
+function withoutRenameHints(model) {
+  const out = {};
+  for (const key of Object.keys(model)) setObjectMember(out, key, model[key]);
+  for (const member of ['collections', 'entities']) {
+    const declared = model[member];
+    if (!isJsonObject(declared)) continue;
+    const stripped = {};
+    for (const name of Object.keys(declared)) {
+      const spec = declared[name];
+      if (isJsonObject(spec) && Object.hasOwn(spec, 'x-rename')) {
+        const { 'x-rename': _hint, ...rest } = spec;
+        setObjectMember(stripped, name, rest);
+      }
+      else {
+        setObjectMember(stripped, name, spec);
+      }
+    }
+    out[member] = stripped;
+  }
+  return out;
+}
+
+/**
+ * The signature-grade identity of a model SHAPE — what a migration's
+ * `from`/`to` name, and what a database records.
+ * @param {any} model
+ * @returns {string}
+ */
+function shapeHashOf(model) {
+  return hashContent(canonicalizeJson(withoutRenameHints(model)));
+}
+
+/**
+ * A `$model` 0.1 document — the model pen's, or its JSON — or `JL0101`.
+ * @param {any} model
+ * @param {string} what
+ * @returns {any}
+ */
+function requireModel(model, what) {
+  const doc = requireJson(model, what);
+  if (!isJsonObject(doc) || doc.$model !== '0.1') {
+    throw new LinqBuildError('JL0101',
+      `${what} is a $model 0.1 document (defineModel(…), or its JSON), got `
+      + `${isJsonObject(doc) ? 'an object without $model: \'0.1\'' : describeValue(model)}`);
+  }
+  return doc;
+}
+
+/**
+ * The tables a model declares: its entities and its collections.
+ * @param {any} model
+ * @returns {string[]}
+ */
+function declaredNames(model) {
+  const names = [];
+  for (const member of ['entities', 'collections']) {
+    if (isJsonObject(model[member])) names.push(...Object.keys(model[member]));
+  }
+  return names;
+}
+
+/**
+ * The migration under construction. Immutable: every step method answers
+ * a new builder; `.document` (memoized) and `toJSON()` are the deep-frozen
+ * `$migration` 0.1 document.
+ */
+export class Migration {
+  #head;
+  #steps;
+  #names;
+  #document;
+
+  /**
+   * @param {any} head - `$migration`, `id`, `from`, `to`, `note?`
+   * @param {readonly any[]} steps
+   * @param {readonly string[] | null} names - the target model's tables,
+   *   or `null` when no target model is known (a planned document alone)
+   */
+  constructor(head, steps, names) {
+    this.#head = head;
+    this.#steps = steps;
+    this.#names = names;
+    this.#document = null;
+  }
+
+  /** @param {readonly any[]} steps */
+  #with(steps) {
+    return new Migration(this.#head, steps, this.#names);
+  }
+
+  /** @param {any} step */
+  #append(step) {
+    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)) {
+      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(', ')));
+    }
+  }
+
+  /** One rendered DDL statement. @param {string} sql @param {string} [note] */
+  ddl(sql, note = undefined) {
+    return this.#append(ddlStep(sql, note));
+  }
+
+  /** One data statement spelled directly (§9.4). @param {string} sql @param {string} [note] */
+  sql(sql, note = undefined) {
+    return this.#append(sqlStep(sql, note));
+  }
+
+  /**
+   * 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`.
+   * @param {string} name
+   * @param {any} spelling - a callback `(row, x) => …`, a `stylesheet(…)`
+   *   document, or a rules array
+   */
+  transform(name, spelling) {
+    const step = transformStep(name, spelling);
+    const drafts = [];
+    this.#steps.forEach((s, i) => {
+      if (s.kind === 'jslt' && s.draft === true && s.collection === name) drafts.push(i);
+    });
+    if (drafts.length > 1) {
+      throw new LinqBuildError('JL0106',
+        `transform() cannot tell which draft to replace: the planned migration carries `
+        + `${drafts.length} draft transforms for '${name}'`);
+    }
+    if (drafts.length === 1) {
+      const next = [...this.#steps];
+      next[drafts[0]] = step;
+      return this.#with(next);
+    }
+    if (this.#names === null) {
+      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()');
+    }
+    this.#requireDeclared(name, 'transform()');
+    return this.#append(step);
+  }
+
+  /**
+   * 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]
+   */
+  assert(name, spelling, options = undefined) {
+    const step = assertStep(name, spelling, options);
+    this.#requireDeclared(name, 'assert()');
+    return this.#append(step);
+  }
+
+  /**
+   * A backfill of stored derived columns (§2.1).
+   * @param {string} name
+   * @param {readonly any[]} columns
+   */
+  derive(name, columns) {
+    const step = deriveStep(name, columns);
+    this.#requireDeclared(name, 'derive()');
+    return this.#append(step);
+  }
+
+  /** Any planner-emitted step, verbatim. @param {any} raw */
+  step(raw) {
+    return this.#append(rawStep(raw));
+  }
+
+  /** The `$migration` 0.1 document, deep-frozen. */
+  get document() {
+    if (this.#document === null) {
+      this.#document = deepFreeze({ ...this.#head, steps: this.#steps.map(copy) });
+    }
+    return this.#document;
+  }
+
+  toJSON() {
+    return this.document;
+  }
+}
+
+/**
+ * A migration between two model documents: `from`/`to` are their shape
+ * hashes, the steps what the methods append.
+ * @param {{ id: string, from: any, to: any, note?: string }} spec
+ * @returns {Migration}
+ */
+export function defineMigration(spec) {
+  if (!isJsonObject(spec)) {
+    throw new LinqBuildError('JL0101', 'defineMigration() takes { id, from, to, note? }');
+  }
+  for (const key of Object.keys(spec)) {
+    if (!['id', 'from', 'to', 'note'].includes(key)) {
+      throw new LinqBuildError('JL0101', `defineMigration() does not take '${key}'`);
+    }
+  }
+  if (typeof spec.id !== 'string' || spec.id === '') {
+    throw new LinqBuildError('JL0101',
+      `defineMigration() id is a non-empty string, got ${describeValue(spec.id)}`, '/id');
+  }
+  const from = requireModel(spec.from, 'defineMigration() from');
+  const to = requireModel(spec.to, 'defineMigration() to');
+  const head = { $migration: MIGRATION_VERSION, id: spec.id, from: shapeHashOf(from), to: shapeHashOf(to) };
+  if (spec.note !== undefined) {
+    if (typeof spec.note !== 'string') {
+      throw new LinqBuildError('JL0101',
+        `defineMigration() note is a string, got ${describeValue(spec.note)}`, '/note');
+    }
+    head.note = spec.note;
+  }
+  return new Migration(head, [], declaredNames(to));
+}
+
+/**
+ * A planner's document, taken up so its draft steps can be replaced by
+ * typed transforms. `from`/`to` model documents type the transforms and
+ * are checked against the document's hashes — a model that is not the
+ * one the planner planned from is refused (`JL0102`).
+ * @param {any} document - a `$migration` 0.1 document, as `jaren-db plan` writes it
+ * @param {{ from?: any, to?: any }} [options]
+ * @returns {Migration}
+ */
+export function fromPlanned(document, options = undefined) {
+  const doc = copy(requireJson(document, 'fromPlanned() document'));
+  if (!isJsonObject(doc) || doc.$migration !== MIGRATION_VERSION
+    || typeof doc.id !== 'string' || doc.id === ''
+    || typeof doc.from !== 'string' || typeof doc.to !== 'string' || !Array.isArray(doc.steps)) {
+    throw new LinqBuildError('JL0101',
+      'fromPlanned() takes a $migration 0.1 document — { $migration, id, from, to, steps } — '
+      + 'as jaren-db plan writes it');
+  }
+  for (const key of Object.keys(doc)) {
+    if (!HEAD_MEMBERS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `fromPlanned() document carries '${key}', which the migration format does not declare`,
+        `/${key}`);
+    }
+  }
+  let names = null;
+  if (options !== undefined) {
+    if (!isJsonObject(options)) {
+      throw new LinqBuildError('JL0101', `fromPlanned() options are { from?, to? }, got ${describeValue(options)}`);
+    }
+    for (const key of Object.keys(options)) {
+      if (key !== 'from' && key !== 'to') throw new LinqBuildError('JL0101', `fromPlanned() does not take '${key}'`);
+    }
+    for (const side of ['from', 'to']) {
+      if (options[side] === undefined) continue;
+      const model = requireModel(options[side], `fromPlanned() ${side}`);
+      const hash = shapeHashOf(model);
+      if (hash !== doc[side]) {
+        throw new LinqBuildError('JL0102',
+          `fromPlanned() ${side} model has shape '${hash}', but the planned migration's ${side} is `
+          + `'${doc[side]}' — the model given is not the one the planner planned ${side === 'from' ? 'from' : 'to'}`,
+          `/${side}`);
+      }
+      if (side === 'to') names = declaredNames(model);
+    }
+  }
+  const head = { $migration: MIGRATION_VERSION, id: doc.id, from: doc.from, to: doc.to };
+  if (doc.note !== undefined) {
+    if (typeof doc.note !== 'string') {
+      throw new LinqBuildError('JL0101', `fromPlanned() document note is a string, got ${describeValue(doc.note)}`, '/note');
+    }
+    head.note = doc.note;
+  }
+  return new Migration(head, doc.steps.map((step) => rawStep(step)), names);
+}

package/src/migration/index.js

@@ -0,0 +1,15 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/migration` — `$migration` 0.1 documents by code.
+ * `defineMigration({ id, from, to })` names two model documents and
+ * hashes their shapes as the store does; the steps follow in the order
+ * they are called — `ddl`, `sql`, `transform` (a `jslt` step whose
+ * callback is captured over the old row shape and typed to the new one),
+ * `assert` (a `query` step), `derive`, and `step` for any planner-emitted
+ * step verbatim. `fromPlanned(document)` takes a planner's document up so
+ * a typed `transform` replaces the draft it left. The document is the
+ * deliverable: plain, deep-frozen JSON the migration runner takes
+ * unchanged; nothing here imports the store or an engine.
+ */
+
+export { defineMigration, fromPlanned, Migration } from './define.js';