@jarenjs/linq 0.49.2 → 0.66.1

package/src/db/live.js

@@ -0,0 +1,43 @@
+//@ts-check
+/**
+ * @file `live(source, options)`: a chain's document and bound externals —
+ * or a hand-written document — handed to the store's own registration
+ * (`store.live` for an entity-root chain, `collection.live` for a
+ * collection's), so the mode, the reason and the maintenance are the
+ * store's (LIVE-FORMAT §7): an entity document re-runs on invalidation,
+ * declared, and a store opened without capture refuses (`JD0050`)
+ * exactly as it does for a document. The chain's `params()` bindings are
+ * the externals, fixed at registration; `options.externals` adds to them.
+ */
+
+/** Whether a source is a chain: a document and an explanation to give. */
+const isChain = (source) => source !== null && typeof source === 'object'
+  && typeof source.toDocument === 'function' && typeof source.explain === 'function';
+
+/**
+ * The document a source stands for, with the values it bound.
+ * @param {any} source - a chain (either surface) or a query document
+ * @returns {{ document: any, bindings: Record<string, unknown> }}
+ */
+function documentOf(source) {
+  if (!isChain(source)) return { document: source, bindings: {} };
+  const explained = source.explain();
+  // a chain split by a host callback has no document; its own refusal
+  // (`JL0005`) names why
+  if (explained.document === undefined) source.toDocument();
+  return { document: explained.document, bindings: explained.bindings };
+}
+
+/**
+ * Register a live query through the store's own registration.
+ * @param {(document: any, options: any) => Promise<any>} register - the
+ *   store's `live` (entity roots) or a collection's
+ * @param {any} source - a chain or a document
+ * @param {any} [options] - LIVE-FORMAT §7 options; `externals` merge over
+ *   the chain's bindings
+ * @returns {Promise<any>} the store's live query
+ */
+export function registerLive(register, source, options = {}) {
+  const { document, bindings } = documentOf(source);
+  return register(document, { ...options, externals: { ...bindings, ...(options.externals ?? {}) } });
+}

package/src/db/membership.js

@@ -0,0 +1,37 @@
+//@ts-check
+/**
+ * @file `link`/`unlink` on a handle: the relation table decides. The
+ * member must be a many-to-many relation of the entity — `JL0107`
+ * otherwise, naming the kind it is or the members that are declared —
+ * and then the store's own `link`/`unlink` record the change
+ * (MODEL-FORMAT §11.7) for `saveChanges()` to write. The store would
+ * refuse the same members itself (`JD2003`); the client sees it earlier
+ * from the table it already reads, mirrored, never invented.
+ */
+
+import { LinqBuildError } from '../errors.js';
+
+/**
+ * The many-to-many relation entry a membership operation names.
+ * @param {Record<string, any>} relations - the handle's relation table
+ * @param {string} entityName
+ * @param {string} member
+ * @param {string} verb - `link` or `unlink`, for the message
+ * @returns {any} the relation entry
+ */
+export function requireMembership(relations, entityName, member, verb) {
+  const entry = relations[member];
+  if (entry === undefined) {
+    const declared = Object.keys(relations).filter((name) => relations[name].kind === 'manyToMany');
+    throw new LinqBuildError('JL0107',
+      `'${member}' is not a relation member of '${entityName}' — ${verb}() attaches a many-to-many `
+      + `membership${declared.length === 0 ? `, and '${entityName}' declares none`
+        : ` (${declared.map((name) => `'${name}'`).join(', ')})`}`);
+  }
+  if (entry.kind !== 'manyToMany') {
+    throw new LinqBuildError('JL0107',
+      `'${member}' is a ${entry.kind} relation of '${entityName}' — ${verb}() attaches many-to-many `
+      + "memberships only; write the related entity's foreign key instead");
+  }
+  return entry;
+}

package/src/db/open.js

@@ -0,0 +1,130 @@
+//@ts-check
+/**
+ * @file `open(model, options)`: `openStore` with every option forwarded
+ * verbatim, plus `validator` — a `JarenValidator` wired as the store's
+ * `compileSchema`. The default validator reproduces the configuration
+ * MIGRATING-FROM-ZOD's recipe uses (`collectErrors`, the string and
+ * date-time formats registered), so `s.string().email()` asserts out
+ * of the box; a host that already has a `compileSchema` passes it and
+ * wins; `validator: null` opens the store unvalidated — the store's own
+ * declared downgrade (`capabilities.validated === false`), chosen by
+ * name, never by omission. The client is a frozen record of handles built ONCE at open
+ * from the names the store declares — no Proxy anywhere: an unknown
+ * name is `undefined`, and for a pen model a compile error.
+ */
+
+import { openStore } from '@jarenjs/db';
+import { JarenValidator } from '@jarenjs/validate';
+import { stringFormats, dateTimeFormats } from '@jarenjs/formats';
+import { setObjectMember } from '@jarenjs/core/object';
+
+import { createEntityHandle, createCollectionHandle } from './handle.js';
+import { registerLive } from './live.js';
+
+/**
+ * The validator the client compiles entity and collection schemas with
+ * when none is given: every issue collected, formats asserting.
+ * @returns {JarenValidator}
+ */
+export function defaultValidator() {
+  return new JarenValidator({ collectErrors: true })
+    .addFormats(stringFormats)
+    .addFormats(dateTimeFormats);
+}
+
+/**
+ * Open a store and front it.
+ * @param {any} model - a `$model` document: the model pen's, or JSON
+ * @param {any} options - `openStore`'s options (`driver` required), plus
+ *   `validator?` (a `JarenValidator`, wired as `compileSchema` unless an
+ *   explicit `compileSchema` is given; `null` for an unvalidated store)
+ * @returns {Promise<any>} the client
+ */
+export async function open(model, options) {
+  if (options === null || typeof options !== 'object') {
+    throw new TypeError('open needs { driver } from @jarenjs/db/node, /bun or /wasm');
+  }
+  const { validator, ...storeOptions } = options;
+  if (validator !== undefined && validator !== null
+    && (typeof validator !== 'object' || typeof validator.compile !== 'function')) {
+    throw new TypeError('open: validator must be a JarenValidator (an object with compile(schema)), '
+      + 'or null for an unvalidated store');
+  }
+  if (storeOptions.compileSchema === undefined && validator !== null) {
+    const jaren = validator ?? defaultValidator();
+    storeOptions.compileSchema = (schema) => jaren.compile(schema);
+  }
+  const store = await openStore(model, storeOptions);
+
+  /**
+   * The typed handles over ONE store view — the root store, or the one
+   * a transaction callback received. Building them from the same two
+   * constructors is what keeps a transaction's `entities.X` the same
+   * surface, with the same inference, as the client's own.
+   * @param {any} over
+   */
+  const handlesOf = (over) => {
+    const entities = {};
+    for (const name of over.roots ?? []) {
+      setObjectMember(entities, name, createEntityHandle(over, name));
+    }
+    const collections = {};
+    for (const name of Object.keys(model.collections ?? {})) {
+      setObjectMember(collections, name, createCollectionHandle(over, name));
+    }
+    return { entities: Object.freeze(entities), collections: Object.freeze(collections) };
+  };
+
+  /**
+   * The client a transaction callback receives: the same shape as the
+   * root client, over the store that is INSIDE the transaction. Its
+   * handles run as the transaction's owner rather than waiting for a
+   * commit they are part of, and its `transaction` nests.
+   *
+   * Built per transaction, because the handles bind to the store view —
+   * and the whole point of a transaction's own unit of work is that two
+   * handlers do not share one.
+   * @param {any} tx - the store the callback received
+   */
+  const transactionClient = (tx) => {
+    /** @type {Record<string, any>} */
+    const inner = {
+      store: tx,
+      capabilities: tx.capabilities,
+      ...handlesOf(tx),
+      transaction: (fn) => tx.transaction((nested) => fn(transactionClient(nested))),
+      // the named-savepoint group (MODEL-FORMAT §5.2), forwarded as it
+      // is: partial rollback belongs to the transaction that owns the
+      // connection, so the root client deliberately has no twin
+      savepoints: tx.savepoints,
+    };
+    if (tx.saveChanges !== undefined) {
+      inner.saveChanges = () => tx.saveChanges();
+      inner.live = (source, liveOptions) => registerLive(tx.live, source, liveOptions);
+    }
+    return Object.freeze(inner);
+  };
+
+  /** @type {Record<string, any>} */
+  const client = {
+    store,
+    capabilities: store.capabilities,
+    ...handlesOf(store),
+    // A transaction gets its own unit of work by default: two handlers
+    // on one client then hold two records for the same entity key and
+    // neither can see the other's pending state. `unitOfWork: 'shared'`
+    // opts back into the store's, for a caller who staged changes
+    // outside the transaction and means to save them inside it.
+    transaction: (fn, transactionOptions) => store.transaction(
+      (tx) => fn(transactionClient(tx)),
+      { unitOfWork: 'own', ...transactionOptions }),
+    close: (closeOptions) => store.close(closeOptions),
+  };
+  // the unit of work and entity live queries exist exactly when the
+  // model declares entities — as on the store
+  if (store.saveChanges !== undefined) {
+    client.saveChanges = () => store.saveChanges();
+    client.live = (source, liveOptions) => registerLive(store.live, source, liveOptions);
+  }
+  return Object.freeze(client);
+}

package/src/document.js

@@ -21,24 +21,142 @@
  * not tell an absent clause from a null-valued one, and silently emitted
  * the document WITHOUT the clause. Every such query then returned its
  * unfiltered, unprojected source.
+ *
+ * An item is an item. The engine's `$for` unpacks an item that is an
+ * array into its members, one level (QUERY-FORMAT §6.2, D4) — the
+ * ergonomic default for a path like `$.tags`, and the wrong default for
+ * a chain, where an array-valued ROW (a CSV record, a pair) is one item
+ * the C# contract never splits. So every source a phrase iterates is
+ * bound through an ARRAY CONSTRUCTOR — `{ "$for": { "it": ["$[*]"] } }`
+ * — whose one array item is unpacked exactly once, into the rows as
+ * they are; a reseated phrase is packed the same way, because a `$for`
+ * over an inner phrase's result would unpack again. The one source left
+ * bare is a PROVIDER's own root (`'$.Post[*]'`): a stored document is an
+ * object, so D4 never applies there, and the bare root is the shape the
+ * provider's planner pushes. The streaming async surface keeps items by
+ * construction, so the two surfaces agree on every row shape.
  */
 
 import { LinqBuildError } from './errors.js';
 
+/** The binding names the emitted documents own (QUERY-PEN §7): the
+ * item bindings, the accumulator and the group — and the relation-hop
+ * bindings `r1`, `r2`, … a capture allocates (expression.js). A
+ * parameter may shadow none of them. */
+export const RESERVED_BINDINGS = Object.freeze(['it', 'it2', 'acc', 'g']);
+const HOP_BINDING_RE = /^r[1-9][0-9]*$/;
+
+/**
+ * Whether a parameter name collides with a binding the document owns.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isReservedBinding(name) {
+  return RESERVED_BINDINGS.includes(name) || HOP_BINDING_RE.test(name);
+}
+
+/** The reserved names, for a refusal's message. */
+export const RESERVED_BINDINGS_TEXT = 'it, it2, acc, g, and r1, r2, … for relation hops';
+
+/** The member a `groupBy`'s items carry the group's rows in. Spelled
+ * once: the emitter writes it here and `expression.js` gives that member
+ * its fan, so `g.items.count()` counts the ROWS the way a group-join's
+ * `g.count()` already does. */
+export const GROUP_ITEMS = 'items';
+
+/** The stage kinds after which the items are no longer the source's
+ * rows: a relation name on them is an ordinary member (QUERY-PEN §3).
+ * The async surface adds its host boundary, `mapAsync`. */
+export const PROJECTING_STAGES = new Set(['select', 'groupBy', 'join', 'groupJoin', 'aggregate']);
+
 /** The fixed clause order a phrase may fill left-to-right. */
-const SLOT_ORDER = ['where', 'groupby', 'orderby', 'return'];
+const SLOT_ORDER = ['bindings', 'where', 'groupby', 'orderby', 'return'];
 
 /** The "this clause slot is unfilled" sentinel: a fresh object, so no
  * value a caller can express is ever mistaken for it. */
 const EMPTY = Symbol('linq.emptySlot');
 
-/** An open FLWOR phrase under construction. */
-function openPhrase(source) {
+/**
+ * An open FLWOR phrase under construction. `bare` marks a source the
+ * phrase iterates WITHOUT packing (a provider's root); every other
+ * source is packed so an array item stays one item.
+ * @param {any} source
+ * @param {boolean} [bare]
+ */
+function openPhrase(source, bare = false) {
   return {
-    source, fold: EMPTY, where: EMPTY, groupby: EMPTY, orderby: EMPTY, ret: EMPTY,
+    source, bare,
+    fold: EMPTY, bindings: EMPTY, where: EMPTY, groupby: EMPTY, orderby: EMPTY, ret: EMPTY,
   };
 }
 
+/** Whether no clause of the phrase has been filled. */
+function untouched(phrase) {
+  return phrase.fold === EMPTY && phrase.bindings === EMPTY && phrase.where === EMPTY
+    && phrase.groupby === EMPTY && phrase.orderby === EMPTY && phrase.ret === EMPTY;
+}
+
+/**
+ * The expression a phrase's items come from, as a `$for` source: packed
+ * (D4 unpacks the one array item back into the rows) unless the source
+ * is a bare provider root.
+ * @param {any} phrase
+ */
+function iterated(phrase) {
+  return phrase.bare ? phrase.source : [phrase.source];
+}
+
+/**
+ * A closed phrase as the SOURCE of another `$for` (a join side): a bare
+ * untouched root stays bare; anything else is packed.
+ * @param {any} phrase
+ */
+function packed(phrase) {
+  return phrase.bare && untouched(phrase) ? phrase.source : [closePhrase(phrase)];
+}
+
+/**
+ * A `selectMany` projection: the projected value iterated one level —
+ * an array member's elements, a constructed array's members, a scalar
+ * as itself — so `Seq<R[]>` really flattens to `Seq<R>`. The nested
+ * phrase rebinds `it` legally: its source is evaluated in the enclosing
+ * scope (the row), its body sees the element.
+ * @param {any} projection - a captured expression
+ * @returns {any}
+ */
+export function fanProjection(projection) {
+  return { $for: { it: projection }, $return: '$it' };
+}
+
+/**
+ * A deep, independent copy of an emitted query document. Plain data
+ * only, which is exactly what a document is — every captured expression
+ * has already passed the JSON-domain boundary in `expression.js`, so
+ * there is nothing here a structural copy would lose.
+ * @param {any} node
+ * @returns {any}
+ */
+export function snapshot(node) {
+  if (node === null || typeof node !== 'object') return node;
+  if (Array.isArray(node)) return node.map(snapshot);
+  /** @type {Record<string, any>} */
+  const out = {};
+  for (const key of Object.keys(node)) defineOwn(out, key, snapshot(node[key]));
+  return out;
+}
+
+/**
+ * Assign an OWN property, so a `__proto__` member stays a member instead
+ * of silently replacing the object's prototype and vanishing.
+ * @param {Record<string, any>} target
+ * @param {string} key
+ * @param {any} value
+ */
+function defineOwn(target, key, value) {
+  Object.defineProperty(target, key,
+    { value, writable: true, enumerable: true, configurable: true });
+}
+
 /** Whether every slot AFTER `slot` is still empty — chain order must
  * agree with the phrase's fixed semantic order. */
 function laterSlotsFree(phrase, slot) {
@@ -57,12 +175,11 @@ function slotFree(phrase, slot) {
 
 /** Close a phrase into a query expression. */
 function closePhrase(phrase) {
-  const untouched = phrase.fold === EMPTY && phrase.where === EMPTY
-    && phrase.groupby === EMPTY && phrase.orderby === EMPTY && phrase.ret === EMPTY;
-  if (untouched) return phrase.source;
+  if (untouched(phrase)) return phrase.source;
   const doc = {};
   if (phrase.fold !== EMPTY) doc.$fold = { acc: phrase.fold };
-  doc.$for = { it: phrase.source };
+  doc.$for = { it: iterated(phrase) };
+  if (phrase.bindings !== EMPTY) doc.$let = phrase.bindings;
   if (phrase.where !== EMPTY) doc.$where = phrase.where;
   if (phrase.groupby !== EMPTY) doc.$groupby = { g: phrase.groupby };
   if (phrase.orderby !== EMPTY) {
@@ -72,7 +189,7 @@ function closePhrase(phrase) {
   // so the member sequence packs into an array constructor and an
   // empty grouping key reads as null
   doc.$return = phrase.ret !== EMPTY ? phrase.ret : (phrase.groupby !== EMPTY
-    ? { key: { $default: ['$g', null] }, items: ['$it'] }
+    ? { key: { $default: ['$g', null] }, [GROUP_ITEMS]: ['$it'] }
     : '$it');
   return doc;
 }
@@ -86,10 +203,12 @@ const andJoin = (a, b) => (a === EMPTY ? b : { $and: [a, b] });
  *   (`'$[*]'` for a plain source; a stripped document for
  *   `fromDocument`)
  * @param {readonly any[]} stages
+ * @param {{ bareRoot?: boolean }} [options] - `bareRoot` iterates the
+ *   root without packing (a provider's own root; see the header)
  * @returns {any} the emitted query document (plain JSON)
  */
-export function emitDocument(root, stages) {
-  let phrase = openPhrase(root);
+export function emitDocument(root, stages, options = undefined) {
+  let phrase = openPhrase(root, options?.bareRoot === true);
   /** Close the open phrase and reopen over its result. */
   const reseat = () => { phrase = openPhrase(closePhrase(phrase)); };
 
@@ -125,13 +244,24 @@ export function emitDocument(root, stages) {
         break;
       case 'join':
         // the hash-join shape: nested bindings + equality (the engine's
-        // compile-time rewrite turns exactly this into a hash probe)
+        // compile-time rewrite turns exactly this into a hash probe;
+        // packed sources keep it — the probe is keyed on the bindings,
+        // not on the sources' spelling)
         phrase = openPhrase({
-          $for: { it: closePhrase(phrase), it2: stage.inner },
+          $for: { it: packed(phrase), it2: stage.innerBare ? stage.inner : [stage.inner] },
           $where: stage.on,
           $return: stage.result,
         });
         break;
+      case 'groupJoin':
+        // the matching group bound as an ARRAY value (`$let`, one item)
+        // so the projection can index it, fan it and place it in a
+        // member; its aggregates fan over the members (expression.js)
+        if (!slotFree(phrase, 'bindings')) reseat();
+        phrase.bindings = { g: [stage.group] };
+        phrase.ret = stage.projection;
+        reseat();
+        break;
       case 'aggregate': {
         // the seeded fold: its own phrase, closed immediately — the
         // result is one accumulated value, not a tuple stream

package/src/effect.js

@@ -0,0 +1,65 @@
+//@ts-check
+/**
+ * @file The effect descriptor two formats spell identically —
+ * `{ run, with? }` — under a machine's `entry`/`exit`/`effects`
+ * (FLOW-FORMAT §2) and under an app transition's `effects`
+ * (APP-FORMAT §5.1). One shape, one brand, one reader; what differs is
+ * only where the props come from, which each pen passes in: the flow
+ * pen captures them over the step scope, the app pen leaves them to the
+ * action capture already in progress.
+ *
+ * `run` is a name the pen writes and never resolves — the host's
+ * registry owns the handler. What an unregistered name costs differs by
+ * engine and neither cost is the pen's: an app document's action loop
+ * refuses it (`JA2006`), while `compileFsm` never looks one up at all,
+ * because FLOW-FORMAT §1.1 makes effect EXECUTION a non-goal — the
+ * descriptor comes back as data and the host decides what to do with it.
+ */
+
+import { LinqBuildError } from './errors.js';
+import { describeValue } from './json-boundary.js';
+
+/** The descriptor brand: how a pen tells `effect()`'s result apart. */
+export const EFFECT = Symbol.for('@jarenjs/linq/effect-descriptor');
+
+/**
+ * One `{ run, with? }` descriptor, branded and frozen.
+ * @param {string} run - the host-registered handler name
+ * @param {any} props - the `with` member, or `undefined`
+ * @param {(props: any) => any} readProps - how this pen spells the props
+ * @returns {any} the effect declaration
+ */
+export function effectDescriptor(run, props, readProps) {
+  if (typeof run !== 'string' || run === '') {
+    throw new LinqBuildError('JL0101',
+      `effect() takes the handler name as a non-empty string, got ${describeValue(run)}`, '/run');
+  }
+  const out = { run };
+  if (props !== undefined) out.with = readProps(props);
+  Object.defineProperty(out, EFFECT, { value: true, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * An effects list, as a document carries it: plain `{ run, with? }`
+ * objects, the brand dropped.
+ * @param {any} list
+ * @param {string} what - the member, for the message
+ * @returns {any[]}
+ */
+export function readEffects(list, what) {
+  if (!Array.isArray(list)) {
+    throw new LinqBuildError('JL0101',
+      `${what} is an array of effect() descriptors, got ${describeValue(list)}`);
+  }
+  return list.map((declared, i) => {
+    if (declared === null || typeof declared !== 'object' || Array.isArray(declared)
+      || declared[EFFECT] !== true) {
+      throw new LinqBuildError('JL0101',
+        `${what}[${i}] is effect(run, with?), got ${describeValue(declared)}`);
+    }
+    const out = { run: declared.run };
+    if (declared.with !== undefined) out.with = declared.with;
+    return out;
+  });
+}

package/src/errors.js

@@ -4,7 +4,7 @@
  * contract: every failure carries a stable `code` (JL0xxx build, JL2xxx
  * runtime), a bare `reason`, a composed `message`, and — where a
  * document position exists — a `docPath`. The normative table lives in
- * docs/LINQ-FORMAT.md §9, proven in sync with `LINQ_CODES` below by a
+ * docs/QUERY-PEN.md §9, proven in sync with `LINQ_CODES` below by a
  * test.
  */
 
@@ -12,7 +12,7 @@ import { CodedError } from '@jarenjs/core/errors';
 
 /**
  * The runtime code table (the `CSV_CODES` shape): one entry per code
- * this package can raise, proven in sync with LINQ-FORMAT.md §9's
+ * this package can raise, proven in sync with QUERY-PEN.md §9's
  * normative table by a test.
  */
 export const LINQ_CODES = Object.freeze({
@@ -22,10 +22,22 @@ export const LINQ_CODES = Object.freeze({
   JL0004: 'an undeclared or reserved parameter name was used',
   JL0005: 'an operator was used invalidly at build time',
   JL0006: 'an unsupported operator was invoked',
+  JL0007: 'a provider serves several entity roots and has no root of its own',
+  JL0101: 'a pen received a value it cannot spell: not JSON, or not what the keyword takes',
+  JL0102: 'a pen was asked for a construct the format cannot carry',
+  JL0103: 'a $defs name collision, a dangling ref, or an unnamed recursion',
+  JL0104: 'a pen-owned keyword through meta(), or an external a captured rule did not declare',
+  JL0105: 'a relation hop cannot lower: a composite or undeclared key, an incomplete many-to-many entry, or a malformed relation record',
+  JL0106: 'a migration step names a table the target model does not declare, or a draft it cannot match',
+  JL0107: 'a client operation named a member that is not the relation kind it needs',
   JL2001: 'first/single found no element',
   JL2002: 'single found more than one element',
   JL2003: 'elementAt is out of range',
   JL2004: 'an asynchronous provider cannot back the synchronous surface',
+  JL2005: 'a push queue was fed after it ended',
+  JL2006: 'a provider answered an element terminal with something other than one array',
+  JL2007: 'a ledger settlement named a ref that settles no started record',
+  JL2008: 'a federated fetch reached its row or byte budget',
 });
 
 /**
@@ -42,13 +54,60 @@ export const LINQ_CODES = Object.freeze({
  *    compileTypeTest })`, e.g. `createTypeTestCompiler()` from
  *    `@jarenjs/validate/query`)
  *  - `JL0004` — a parameter was referenced without being declared via
- *    `.params({...})`, or a declared name is reserved (`it`, `acc`,
- *    `g` — the document's own binding names)
+ *    `.params({...})`, a declared name is reserved (`it`, `it2`, `acc`,
+ *    `g`, and the relation-hop bindings `r1`, `r2`, … — the document's
+ *    own binding names), a binding is not query data, or the two sides
+ *    of a `join`/`groupJoin`/`concat` bind one name to different values
  *  - `JL0005` — an operator was used invalidly at build time (`thenBy`
- *    without `orderBy`, `all()` off a plain path, a negative
- *    `skip`/`take`, a value that cannot embed in a document)
+ *    without `orderBy`, `all()` off an operator result rather than a
+ *    path, a member read off a to-many relation before `all()`, a
+ *    negative `skip`/`take`, a value that cannot embed in a document)
  *  - `JL0006` — an operator the mapping table records as
  *    `unsupported` was invoked (`zip`); the table names the reason
+ *  - `JL0007` — `from()`/`fromAsync()` received a provider that serves
+ *    several entity roots (`roots`) and has no `root` of its own — a
+ *    store with entities; chain over one of them (`store.entity(name)`)
+ *
+ * The pens (`@jarenjs/linq/schema`, `/model`, `/jslt`, `/migration`,
+ * `/contract`, `/flow`) and the client (`/db`; LINQ-FORMAT.md §1.3)
+ * refuse with the `JL01xx` codes:
+ *
+ *  - `JL0101` — a pen received a value it cannot spell: a function,
+ *    symbol, bigint, `NaN`, `±Infinity`, `-0`, a class instance or a
+ *    cycle where JSON was needed, or a value that is not what the
+ *    keyword takes (`min('x')`, a non-builder member)
+ *  - `JL0102` — a construct the format cannot carry: a function
+ *    `refine`/`transform`, a coercion the normalizer would never run,
+ *    closed objects under `allOf`, an annotation on `never()`, an
+ *    `apply()` as a bare object member, a `match` of `{}`, a path
+ *    template form CONTRACT-FORMAT §4.2 reserves, an operation `kind`
+ *    outside the three, a flow guard given as a plain string
+ *    (FLOW-FORMAT §3 makes a non-`$` literal vacuously true), a state
+ *    or node id no declaration carries
+ *  - `JL0103` — two distinct builders under one `$defs` name, a
+ *    `ref()` no definition answers, or a `lazy()` that is not named
+ *  - `JL0104` — a pen-owned keyword written through `meta()`, or a
+ *    captured rule naming an external it did not declare (a `check()`
+ *    or `body()` external other than `root`/`path` and, for a body,
+ *    its declared parameters; a `compute()` external at all, or a flow
+ *    guard/`with`/node-query/`select` external at all — both flow
+ *    engines evaluate with one `$` and nothing else)
+ *  - `JL0105` — a relation hop on the chain (the query pen) cannot
+ *    lower: the member is a many-to-many relation, whose join table is
+ *    not a queryable root in this version (`load({ include })` reads the
+ *    memberships); or the relation's key column or the key it references
+ *    is composite or undeclared; or the provider's relation table holds
+ *    something that is not a relation record
+ *  - `JL0106` — a migration step names an entity or collection the
+ *    target model does not declare (`transform`, `assert`, `derive`),
+ *    or a `transform` over a planned document finds no draft to
+ *    replace, or two drafts for one name
+ *  - `JL0107` — the client was handed a member that is not the relation
+ *    kind the operation needs: `include()` picks a declared relation
+ *    member (a scalar member, or a name the model does not declare, is
+ *    refused naming the declared ones); `link()`/`unlink()` attach
+ *    many-to-many memberships only (a to-one or to-many relation is
+ *    refused naming its kind)
  */
 export class LinqBuildError extends CodedError {
   /**
@@ -77,6 +136,19 @@ export class LinqBuildError extends CodedError {
  *    `Sequence` terminal is a value (`toArray(): T[]`), so a promise
  *    cannot be returned under that type; emit `toDocument()` and await
  *    the provider directly instead.
+ *  - `JL2005` — `feed()` was called on a push queue after `end()`
+ *    closed it (a condition of the running stream, not of the build)
+ *  - `JL2007` — `createDbLedger`'s `commit`/`fail` named a ref that
+ *    settles no started record: the key expired, was reclaimed under a
+ *    newer generation, or was settled already (DB-CLIENT.md §2.6)
+ *  - `JL2006` — a provider answered an element terminal (`toArray`,
+ *    `first`, …) with something other than exactly one array; the
+ *    emitted document is an array constructor, so a conforming
+ *    `execute()` never answers `undefined` there
+ *  - `JL2008` — a `federate()` fetch reached one side's row or byte
+ *    budget. A budget is a REFUSAL, not a spill: the fetch stops at the
+ *    row that would have broken it, every cursor it opened is closed,
+ *    and the reason names the side and the bound (QUERY-PEN.md §13)
  */
 export class LinqRuntimeError extends CodedError {
   /**