@jarenjs/linq 0.49.2 → 0.66.1

package/src/forms/index.js

@@ -0,0 +1,43 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/forms` — the form by code. The schema pen's every
+ * name, rebuilt from SUBCLASSES that carry the `x-form` vocabulary
+ * (`form({ visible, enabled, assert, computed, message })`), plus
+ * `assertOnSubmit()`, the one call that answers the same rules' Layer-3
+ * `$query` twin. A rule is an ANNOTATION: the document a form pen writes
+ * validates exactly as the schema pen's does, and `buildFormModel`,
+ * `compileFormRules` and `evaluateFormRules` read the rules off it.
+ * Nothing here imports `@jarenjs/forms`.
+ */
+
+import {
+  SchemaBuilder, StringBuilder, NumberBuilder, ArrayBuilder, TupleBuilder,
+  ObjectBuilder, WhenBuilder, NeverBuilder,
+} from '../schema/builders.js';
+import { createFactories } from '../schema/factories.js';
+import { withForm } from './rules.js';
+
+/** The rule-aware classes: new classes, one mixin, no patched prototype. */
+export const FormBuilder = withForm(SchemaBuilder);
+export const FormStringBuilder = withForm(StringBuilder);
+export const FormNumberBuilder = withForm(NumberBuilder);
+export const FormArrayBuilder = withForm(ArrayBuilder);
+export const FormTupleBuilder = withForm(TupleBuilder);
+export const FormObjectBuilder = withForm(ObjectBuilder);
+export const FormWhenBuilder = withForm(WhenBuilder);
+export const FormNeverBuilder = withForm(NeverBuilder);
+
+export const {
+  string, number, integer, boolean, nil, literal, enumOf,
+  object, array, tuple, record, union, discriminated, intersection,
+  named, ref, lazy, any, never, when, from, document,
+  datetime, date, time, duration,
+} = /** @type {any} */ (createFactories({
+  Base: FormBuilder, String: FormStringBuilder, Number: FormNumberBuilder,
+  Array: FormArrayBuilder, Tuple: FormTupleBuilder, Object: FormObjectBuilder,
+  When: FormWhenBuilder, Never: FormNeverBuilder,
+}));
+
+export { withForm } from './rules.js';
+export { assertOnSubmit } from './submit.js';
+export { isSchemaBuilder, schemaOf, SCHEMA_BUILDER } from '../schema/brand.js';

package/src/forms/rules.js

@@ -0,0 +1,170 @@
+//@ts-check
+/**
+ * @file The `x-form` vocabulary as one builder method: `withForm(Base)`,
+ * a mixin applied to every schema-pen class at module scope, so
+ * `./forms` is a set of NEW classes (never a patched prototype) on which
+ * any member can carry a cross-field rule.
+ *
+ * `form({ visible, enabled, assert, computed, message })` writes the one
+ * `x-form` annotation the forms README's layer 2 specifies. The three
+ * predicates and `computed` are CALLBACKS captured over the rule
+ * context, never paths typed as strings: `$` is the whole form document
+ * (cross-field is the point), and `value`/`pointer` are the two
+ * externals `compileFormRules` binds per evaluation — so the callback
+ * receives one context object spelling all three, `c.root`, `c.value`
+ * and `c.pointer`, and any other name is `JL0104` here rather than a
+ * compile error from forms naming the same two.
+ *
+ * What the pen refuses is what the reader would refuse and the builder
+ * can already see: a member `x-form` does not define, and `preview` —
+ * which is not an authored member at all but the format registry's own
+ * hint (`getFormatInfo(format).preview`), so spelling it here would
+ * write a keyword nothing reads.
+ */
+
+import { LinqBuildError } from '../errors.js';
+import { captureQuery } from '../capture-root.js';
+import { describeValue, requireJson } from '../json-boundary.js';
+
+/** The keyword every rule method writes. */
+export const KEYWORD = 'x-form';
+
+/** The members `x-form` defines, in the order the README's table lists them. */
+const RULE_MEMBERS = Object.freeze(['visible', 'enabled', 'assert', 'computed', 'message']);
+
+/** The members captured as queries over the rule context. */
+const QUERY_MEMBERS = Object.freeze(['visible', 'enabled', 'assert', 'computed']);
+
+/** The two externals `compileFormRules` binds, beside the document at `$`. */
+const EXTERNALS = Object.freeze(['value', 'pointer']);
+
+/** Where an unbound name could have come from, appended to `JL0104`. */
+const ADVICE = () => ' — the document being edited is the context\'s root (c.root), the '
+  + 'field\'s own value c.value and its pointer c.pointer';
+
+/**
+ * The rule context: one object over the capture's document root and its
+ * two externals. `root` is the value proxy (`$`), so `c.root.company`
+ * writes `"$.company"`; anything the evaluator does not bind falls
+ * through to the externals proxy, which refuses it by name.
+ * @param {any} doc - the `$` proxy
+ * @param {any} externals - the externals proxy (`value`, `pointer`)
+ * @returns {any}
+ */
+function contextProxy(doc, externals) {
+  return new Proxy(Object.freeze({}), {
+    get(_target, prop) {
+      if (prop === 'root') return doc;
+      if (typeof prop === 'symbol') return undefined;
+      return externals[prop];
+    },
+  });
+}
+
+/**
+ * One query-valued rule member: a callback captured over the context, or
+ * a query document written by hand, copied.
+ * @param {string} member - `visible`, `enabled`, `assert` or `computed`
+ * @param {any} value
+ * @returns {any} the query document (plain JSON)
+ */
+function ruleMember(member, value) {
+  if (typeof value !== 'function') {
+    return JSON.parse(JSON.stringify(requireJson(value, `form() ${member}`)));
+  }
+  return captureQuery(`form() ${member}`, EXTERNALS,
+    (doc, externals) => value(contextProxy(doc, externals)),
+    { advice: ADVICE, fold: false });
+}
+
+/**
+ * The `message` member: a plain string (an inline template) or a
+ * MessageSpec object, verbatim.
+ * @param {any} value
+ * @returns {any}
+ */
+function readMessage(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new LinqBuildError('JL0101',
+      'form() message is an inline string or a MessageSpec { $msgid?, message?, params? }, '
+      + `got ${describeValue(value)}`, '/message');
+  }
+  if (value.$msgid === undefined && value.message === undefined) {
+    throw new LinqBuildError('JL0101',
+      "form() message as a MessageSpec needs '$msgid' and/or 'message'", '/message');
+  }
+  return JSON.parse(JSON.stringify(requireJson(value, 'form() message')));
+}
+
+/**
+ * The mixin: a subclass of `Base` carrying `form()`.
+ * @template {new (state: any) => any} B
+ * @param {B} Base - a schema-pen builder class
+ * @returns {B} a new class, `Base` plus the vocabulary
+ */
+export function withForm(Base) {
+  return class extends Base {
+    /**
+     * One `x-form` annotation (the forms README, layer 2): cross-field
+     * visibility, enablement, a preemptive assertion, a derived value
+     * and the message an assertion failure renders. A rule is an
+     * ANNOTATION — it never changes what the schema validates, so
+     * `additionalProperties` and every other keyword stay exactly what
+     * the schema pen wrote.
+     *
+     * @param {{ visible?: any, enabled?: any, assert?: any, computed?: any, message?: any }} spec
+     * @returns {this}
+     * @throws {LinqBuildError} `JL0101` a member `x-form` does not define,
+     *   or a message that is neither a string nor a MessageSpec;
+     *   `JL0102` `preview`, which the format registry derives from the
+     *   field's own `format`; `JL0104` a name the rule context does not bind
+     * @example
+     * s.string().form({ visible: (c) => c.root.company.ne('') });
+     * s.number().form({ computed: (c) => c.root.lines.all().amount.sum() });
+     */
+    form(spec) {
+      if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+        throw new LinqBuildError('JL0101',
+          'form() takes { visible?, enabled?, assert?, computed?, message? }, got '
+          + describeValue(spec));
+      }
+      for (const key of Object.keys(spec)) {
+        if (key === 'preview') {
+          throw new LinqBuildError('JL0102',
+            "form() cannot write 'preview' — a field's preview hint is DERIVED from its "
+            + 'format by the registry (getFormatInfo(format).preview), never authored, and '
+            + 'buildFormModel reads it from there; spell the format instead, and a host '
+            + 'that understands the hint draws it beside the control', '/preview');
+        }
+        if (!RULE_MEMBERS.includes(key)) {
+          throw new LinqBuildError('JL0101',
+            `form() does not take '${key}' — x-form defines ${RULE_MEMBERS.join(', ')}`,
+            `/${key}`);
+        }
+      }
+      const current = this.annotation(KEYWORD) ?? {};
+      const rules = { ...current };
+      for (const member of QUERY_MEMBERS) {
+        if (spec[member] !== undefined) rules[member] = ruleMember(member, spec[member]);
+      }
+      if (spec.message !== undefined) rules.message = readMessage(spec.message);
+      // the README's own member order, whatever order the caller wrote
+      const ordered = {};
+      for (const member of RULE_MEMBERS) {
+        if (rules[member] !== undefined) ordered[member] = rules[member];
+      }
+      return this.annotate(KEYWORD, Object.freeze(ordered));
+    }
+
+    /** As in the schema pen, but `x-form` is owned here. @param {Record<string, any>} annotations */
+    meta(annotations) {
+      if (annotations !== null && typeof annotations === 'object' && KEYWORD in annotations) {
+        throw new LinqBuildError('JL0104',
+          `meta() cannot write '${KEYWORD}' — the forms pen owns that keyword; spell it `
+          + 'through form()');
+      }
+      return super.meta(annotations);
+    }
+  };
+}

package/src/forms/submit.js

@@ -0,0 +1,177 @@
+//@ts-check
+/**
+ * @file `assertOnSubmit()` — the second spelling of a rule written once.
+ * An `x-form.assert` is evaluated per keystroke by `evaluateFormRules`;
+ * the same constraint is authoritative at submit through the validator's
+ * `$query` keyword, and the forms README's layer 3 is the transform that
+ * copies one into the other. The pen offers it as ONE call over the
+ * document it wrote, so an author spells the rule once and asks for both
+ * documents.
+ *
+ * The rules the copy keeps are the README's, and each is a place a naive
+ * copy went wrong: an absent field binds `null` (through `$default`), an
+ * item-template assert quantifies over the ELEMENTS rather than the
+ * selected leaves, and an assert on a field that also declares `visible`
+ * is guarded by it so it holds vacuously while the field is hidden. The
+ * branches land on the ROOT, where `$` is the instance root the rule
+ * context expects; the message travels with them so submit renders the
+ * same text the keystroke path does.
+ *
+ * Nothing here imports `@jarenjs/forms`: the transform reads the emitted
+ * document, and the pen test pins it equal to
+ * `formRulesToQueryAssertions` over the corpus.
+ */
+
+import { deepFreeze } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { isSchemaBuilder, schemaOf } from '../schema/brand.js';
+import { describeValue } from '../json-boundary.js';
+import { KEYWORD } from './rules.js';
+
+/**
+ * The loop-variable prefix for element quantification — the same one the
+ * forms transform uses, so the two documents are byte-equal.
+ */
+const ITEM_VAR = '_item';
+
+/** RFC 6901: `~` and `/` escape inside a pointer segment. @param {string} key */
+const escapePointer = (key) => key.replaceAll('~', '~0').replaceAll('/', '~1');
+
+/**
+ * The RFC 9535 name selector `['…']` for one member name.
+ * @param {string} key
+ * @returns {string}
+ */
+function nameSelector(key) {
+  let out = "['";
+  for (const ch of key) {
+    const code = /** @type {number} */ (ch.codePointAt(0));
+    if (ch === '\\' || ch === "'") out += `\\${ch}`;
+    else if (code < 0x20) out += `\\u${code.toString(16).padStart(4, '0')}`;
+    else out += ch;
+  }
+  return `${out}']`;
+}
+
+/** A new chunk list with `selector` appended to its last chunk. */
+function extendChunks(chunks, selector) {
+  const next = chunks.slice();
+  next[next.length - 1] += selector;
+  return next;
+}
+
+/**
+ * The `$query` document for one assert, from its location expressed as
+ * path chunks split at each array expansion.
+ * @param {readonly string[]} chunks
+ * @param {any} assert - the authored rule document
+ * @param {string} pointer - the field's data pointer
+ * @param {any} [visible] - the field's `visible` rule, when it has one
+ * @returns {any}
+ */
+function assertQuery(chunks, assert, pointer, visible) {
+  const depth = chunks.length - 1;
+  const at = (k) => (k === 0 ? chunks[0] : `$${ITEM_VAR}${k - 1}${chunks[k]}`);
+  const body = visible === undefined ? assert : { $or: [{ $not: visible }, assert] };
+  let query = {
+    $let: { value: { $default: [at(depth), { $const: null }] }, pointer: { $const: pointer } },
+    $return: body,
+  };
+  for (let k = depth - 1; k >= 0; k--) {
+    query = { $every: { [`${ITEM_VAR}${k}`]: at(k) }, $satisfies: query };
+  }
+  return query;
+}
+
+/**
+ * The `errorMessage.$query` spec one assert carries: the rule's message
+ * with `params` merged over `{ pointer }`, or the catalog default.
+ * @param {any} message
+ * @param {string} pointer
+ * @returns {any}
+ */
+function messageSpec(message, pointer) {
+  if (typeof message === 'string') return { message, params: { pointer } };
+  if (message !== null && typeof message === 'object' && !Array.isArray(message)) {
+    return { ...message, params: { pointer, ...(message.params || {}) } };
+  }
+  return { $msgid: 'x-form/assert', params: { pointer } };
+}
+
+/**
+ * Walk the structural spine `buildFormModel` walks — `properties`,
+ * `prefixItems`, `items`, `allOf` — collecting every `x-form.assert`
+ * with its data location. `$ref`s are NOT resolved: a definition's data
+ * location depends on its use site.
+ * @param {any} schema
+ * @param {string} pointer
+ * @param {readonly string[]} chunks
+ * @param {any[]} out
+ */
+function collect(schema, pointer, chunks, out) {
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) return;
+
+  const rules = schema[KEYWORD];
+  if (rules !== null && typeof rules === 'object' && !Array.isArray(rules)
+    && rules.assert !== undefined) {
+    out.push({
+      query: assertQuery(chunks, rules.assert, pointer, rules.visible),
+      pointer,
+      message: rules.message,
+    });
+  }
+  if (schema.properties !== null && typeof schema.properties === 'object') {
+    for (const [key, sub] of Object.entries(schema.properties)) {
+      collect(sub, `${pointer}/${escapePointer(key)}`, extendChunks(chunks, nameSelector(key)), out);
+    }
+  }
+  if (Array.isArray(schema.prefixItems)) {
+    for (let i = 0; i < schema.prefixItems.length; i++) {
+      collect(schema.prefixItems[i], `${pointer}/${i}`, extendChunks(chunks, `[${i}]`), out);
+    }
+  }
+  if (schema.items !== null && typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+    collect(schema.items, `${pointer}/-`, [...extendChunks(chunks, '[*]'), ''], out);
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const branch of schema.allOf) collect(branch, pointer, chunks, out);
+  }
+}
+
+/**
+ * The submit twin of a document's `x-form.assert` rules: every assert
+ * copied onto the ROOT as its own `allOf` branch
+ * `{ $query, errorMessage }`, so the rule an author wrote once for
+ * per-keystroke feedback is also what the compiled validator enforces.
+ *
+ * A document with no assert answers the document itself — there is
+ * nothing to copy, and a needless `allOf` would be a second spelling of
+ * the same schema.
+ *
+ * @param {any} root - the root builder, or a document
+ * @returns {any} the deep-frozen submit document
+ * @throws {LinqBuildError} `JL0101` a value that is not a builder or an
+ *   object schema
+ * @example
+ * const schema = s.object({ vatId: s.string().form({ assert: …, message: … }) });
+ * new JarenValidator().compile(assertOnSubmit(schema));   // app-side
+ */
+export function assertOnSubmit(root) {
+  const schema = isSchemaBuilder(root) ? schemaOf(root) : root;
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+    throw new LinqBuildError('JL0101',
+      'assertOnSubmit() takes the document\'s root builder or its schema object, got '
+      + describeValue(root));
+  }
+  /** @type {any[]} */
+  const asserts = [];
+  collect(schema, '', ['$'], asserts);
+  if (asserts.length === 0) return deepFreeze(JSON.parse(JSON.stringify(schema)));
+  const branches = asserts.map((entry) => ({
+    $query: entry.query,
+    errorMessage: { $query: messageSpec(entry.message, entry.pointer) },
+  }));
+  const allOf = Array.isArray(schema.allOf) ? schema.allOf : [];
+  return deepFreeze(JSON.parse(JSON.stringify({ ...schema, allOf: [...allOf, ...branches] })));
+}

package/src/index.js

@@ -4,11 +4,14 @@
  * expressions as plain Jaren query documents (QUERY-FORMAT.md),
  * executes deferred over any iterable, and hands the SAME document
  * whole to any provider exposing `execute(document, options)` (D2:
- * contract-level coupling, never an import edge). The normative
- * surface, mapping table and error codes live in docs/LINQ-FORMAT.md.
+ * contract-level coupling — the chain imports no provider; the client
+ * subpath `./db` is the package's one declared edge, toward the
+ * store). The normative surface, mapping table and error codes live
+ * in docs/QUERY-PEN.md.
  */
 
 export { from, fromDocument, Sequence } from './sequence.js';
 export { fromAsync, AsyncSequence } from './async.js';
 export { createPushQueue } from './sources.js';
+export { federate } from './federate.js';
 export { LinqBuildError, LinqRuntimeError, LINQ_CODES } from './errors.js';

package/src/jslt/body.js

@@ -0,0 +1,226 @@
+//@ts-check
+/**
+ * @file `body()` — a JSLT rule body captured through the chain's own
+ * recording proxy over the shared root capture: `fn(value, x)` with
+ * `value` rooted at `$` (the matched value) and `x` the externals —
+ * `root` and `path`, which the engine binds on every dispatch
+ * (JSLT-FORMAT §8.2), plus the parameters the body declares (§8.1); an
+ * undeclared name is `JL0104` at build time, where the fix can be
+ * named. `apply()` spells the one body-local operator (§6) and `op()`
+ * any registered one (§13): both lift a hand-spelled operator into the
+ * capture, and the engine's compiler stays the only judge of what it
+ * means. A returned literal is spelled as the format's own constructor
+ * (`{ "level": "unknown" }`), never folded into `$const` as the chain
+ * spells a constant; a string starting `$` is escaped `$$`. The one
+ * rule the pen checks itself is the `[]` idiom of §6.3 —
+ * an `apply` as a bare object member is refused HERE because the
+ * engine would only refuse it at run time, on the second child.
+ */
+
+import { liftExpression, toExpression } from '../expression.js';
+import { captureQuery } from '../capture-root.js';
+import { describeValue } from '../json-boundary.js';
+import { LinqBuildError } from '../errors.js';
+import { deepFreeze } from '@jarenjs/core/object';
+
+/** The two names the engine binds on every dispatch (§8.2). */
+const RESERVED = ['root', 'path'];
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The `{ $apply: … }` NODES `apply()` built, by identity. The node, not
+ * the proxy over it: a proxy is consumed the moment its value is lowered
+ * (into a member, an operand, an argument), while the node it carries is
+ * the very object that lands in the emitted document. */
+const APPLY_NODES = new WeakSet();
+/** How many `body()` captures are in progress (captures nest). */
+let bodies = 0;
+
+/**
+ * The declared parameter names, or `JL0101`/`JL0104` naming the problem.
+ * @param {any} options
+ * @returns {string[]}
+ */
+function readExternals(options) {
+  if (options === undefined) return [];
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new LinqBuildError('JL0101',
+      `body() options are { externals?: string[] }, got ${describeValue(options)}`);
+  }
+  for (const key of Object.keys(options)) {
+    if (key !== 'externals') throw new LinqBuildError('JL0101', `body() does not take '${key}'`);
+  }
+  const list = options.externals;
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) {
+    throw new LinqBuildError('JL0101',
+      `body() externals is an array of parameter names, got ${describeValue(list)}`);
+  }
+  /** @type {string[]} */
+  const names = [];
+  for (const name of list) {
+    if (typeof name !== 'string' || !NAME_RE.test(name)) {
+      throw new LinqBuildError('JL0101',
+        `body() externals are identifiers ('rate'), got ${describeValue(name)}`);
+    }
+    if (RESERVED.includes(name)) {
+      throw new LinqBuildError('JL0104',
+        `'${name}' is engine-bound on every dispatch (JSLT-FORMAT §8.2) — it needs no `
+        + 'declaration and is always present on the externals argument');
+    }
+    if (!names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * `an object member takes exactly one value` — the `[]` idiom's refusal.
+ * @param {string} key @param {string} at
+ */
+function bareApply(key, at) {
+  return new LinqBuildError('JL0102',
+    `an object member takes exactly one value — '${key}' holds an apply(), which yields `
+    + 'a SEQUENCE and fails at run time on the second child (JQ2001); wrap the apply in '
+    + `[] (JSLT-FORMAT §6.3: ${key}: [apply(…)])`, at);
+}
+
+/**
+ * The `[]` idiom (§6.3): an object member holds exactly one value, and
+ * an `$apply` yields a sequence — so an `apply()` in a member position
+ * is refused. Inside an array constructor it is the idiom itself (the
+ * brackets splice the sequence); as an operator's operand it is an
+ * ordinary expression (`apply(…).count()`); at the top of the body it is
+ * the body's own sequence.
+ *
+ * The walk runs over the CAPTURED DOCUMENT rather than over the value
+ * the callback returned, because a callback may hand an `apply()` to an
+ * operator (`op('$if', [f, { children: apply(…) }, null])`) and the
+ * object literal is lowered before the callback ever returns — the
+ * marker is gone, and only the node it left in the document is still
+ * there to find. The document is plain JSON at this point and the nodes
+ * are the same objects `apply()` built, so identity is the whole test.
+ *
+ * Member position is read the way `toExpression` writes it, three lines
+ * earlier: a map CONSTRUCTOR has no `$`-prefixed key (a data object that
+ * does is spelled `$map`, as pairs), and everything else with one is an
+ * operator or FLWOR phrase whose operands are expressions.
+ * @param {any} node - a node of the captured document
+ * @param {string} at - its JSON pointer, for `docPath`
+ */
+function refuseBareApply(node, at) {
+  if (node === null || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) refuseBareApply(node[i], `${at}/${i}`);
+    return;
+  }
+  const keys = Object.keys(node);
+  if (!keys.some((k) => k.charCodeAt(0) === 0x24)) {
+    for (const key of keys) {
+      if (APPLY_NODES.has(node[key])) throw bareApply(key, `${at}/${key}`);
+      refuseBareApply(node[key], `${at}/${key}`);
+    }
+    return;
+  }
+  // `$map` is the one phrase whose operands ARE members: it spells a data
+  // object with `$`-prefixed keys as [key, value] pairs (`toExpression`).
+  if (keys.length === 1 && keys[0] === '$map' && Array.isArray(node.$map)) {
+    node.$map.forEach((pair, i) => {
+      if (!Array.isArray(pair) || pair.length !== 2) {
+        refuseBareApply(pair, `${at}/$map/${i}`);
+        return;
+      }
+      if (APPLY_NODES.has(pair[1])) {
+        throw bareApply(typeof pair[0] === 'string' ? pair[0] : String(i), `${at}/$map/${i}/1`);
+      }
+      refuseBareApply(pair[1], `${at}/$map/${i}/1`);
+    });
+    return;
+  }
+  for (const key of keys) refuseBareApply(node[key], `${at}/${key}`);
+}
+
+/**
+ * `{ $apply: selector }` or `{ $apply: [selector, mode] }` — the
+ * apply-templates operator (§6), inside a `body()` callback. The
+ * selector is an expression (`v.chapters.all()`), a JSONPath string
+ * taken verbatim (`'$.chapters[*]'`), or plain data (`[1, 2]` embeds as
+ * `$const`); the mode is a literal string naming the target mode (a
+ * mode is not an expression, §6.2). The result is an expression: it
+ * composes as one (`apply(…).count()`), and as an array element it is
+ * the `[]` idiom — as a bare object member it is refused (`JL0102`).
+ * @param {any} selector
+ * @param {string} [mode]
+ * @returns {any} an expression over the `$apply` document
+ */
+export function apply(selector, mode = undefined) {
+  if (bodies === 0) {
+    throw new LinqBuildError('JL0102',
+      'apply() spells $apply, which exists only inside a rule body (JSLT-FORMAT §6.1) — '
+      + 'call it inside body()');
+  }
+  if (selector === undefined) {
+    throw new LinqBuildError('JL0101',
+      "apply() takes a selector: a path (v.chapters.all(), '$.chapters[*]') or an expression");
+  }
+  const doc = typeof selector === 'string' ? selector : toExpression(selector);
+  let node;
+  if (mode === undefined) node = { $apply: doc };
+  else {
+    if (typeof mode !== 'string') {
+      throw new LinqBuildError('JL0101',
+        `apply() takes the target mode as a literal string (a mode is not an expression, `
+        + `JSLT-FORMAT §6.2), got ${describeValue(mode)}`);
+    }
+    node = { $apply: [doc, mode] };
+  }
+  APPLY_NODES.add(node);
+  return liftExpression(node);
+}
+
+/**
+ * `{ [name]: operands }` — a registered operator (§13), spelled without
+ * judging it: the pen writes the name it is given and the engine's
+ * compiler decides (`JQ0002` for a name no registry answers). Works in
+ * any capture in progress — a body, or a chain callback over an
+ * in-memory source compiled with the same registry.
+ * @param {string} name - the operator name, `$`-prefixed (`'$npv'`)
+ * @param {any} [operands] - one operand, or an array of them
+ * @returns {any} an expression over the operator document
+ */
+export function op(name, operands = []) {
+  if (typeof name !== 'string' || name.length < 2 || name.charCodeAt(0) !== 0x24) {
+    throw new LinqBuildError('JL0101',
+      `op() takes an operator name starting with '$' ('$npv'), got ${describeValue(name)}`);
+  }
+  const value = Array.isArray(operands) ? operands.map(toExpression) : toExpression(operands);
+  return liftExpression({ [name]: value });
+}
+
+/**
+ * Capture one rule body: `fn(value, x)` over the matched value at `$`,
+ * with `x.root`, `x.path` and every declared parameter; the result is
+ * the body's query document, plain and deep-frozen.
+ * @param {(value: any, externals: any) => any} fn
+ * @param {{ externals?: readonly string[] }} [options]
+ * @returns {any} the body document (plain JSON)
+ */
+export function body(fn, options = undefined) {
+  if (typeof fn !== 'function') {
+    throw new LinqBuildError('JL0101',
+      `body() takes a callback (value, x) => …, got ${describeValue(fn)}`);
+  }
+  const declared = readExternals(options);
+  const advice = (/** @type {string} */ name) =>
+    ` — a stylesheet parameter is declared first: body(fn, { externals: ['${name}'] })`;
+  bodies++;
+  try {
+    const doc = captureQuery('body()', RESERVED.concat(declared), fn, { advice, fold: false });
+    refuseBareApply(doc, '');
+    // a body spells a literal as the format's own constructor (never a
+    // folded `$const`); the tree may still share a caller's array or
+    // object, so it is copied before it is frozen
+    return deepFreeze(JSON.parse(JSON.stringify(doc)));
+  }
+  finally {
+    bodies--;
+  }
+}

package/src/jslt/index.js

@@ -0,0 +1,18 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/jslt` — `$jslt` 0.1 stylesheets by code. Rule
+ * bodies are callbacks captured over `$` through the chain's own
+ * recording proxy, with `root`/`path` and the declared parameters as
+ * typed externals; `apply()` spells the apply-templates operator and
+ * `op()` any registered one; `rule()` and `stylesheet()` write the
+ * rule object and the envelope of JSLT-FORMAT §2. The document is the
+ * deliverable: plain, deep-frozen JSON that `compileJsltStylesheet`
+ * takes unchanged; nothing here imports an engine. `body()` is the
+ * migration pen's body-capture entry point too (a `jslt` step's body
+ * binds the same `root`/`path`); the flow and app pens capture through
+ * `captureQuery` directly, because their evaluators bind nothing and a
+ * body's two reserved names would be a promise neither engine keeps.
+ */
+
+export { body, apply, op } from './body.js';
+export { rule, stylesheet } from './rules.js';