@jarenjs/linq 0.49.2 → 0.56.0

package/src/expression.js

@@ -15,9 +15,18 @@
  *
  * Method names shadow member access: `u.eq` is the operator, never the
  * data member — reach a colliding member with `u.get('eq')`.
+ *
+ * A root whose items are an entity's rows carries the entity's RELATION
+ * TABLE (QUERY-PEN §3, MODEL-FORMAT §10.1): a member access naming a
+ * relation records a HOP and lowers, right here, to the correlated
+ * phrase the engine and the store both run — `p.author.email` is
+ * `{ $for: { r1: '$.User[*]' }, $where: { $eq: ['$r1.id', '$it.authorId'] },
+ * $return: '$r1.email' }` — so the emitted document never carries a
+ * relation name and never needs a dialect the oracle could not prove.
  */
 
 import { LinqBuildError } from './errors.js';
+import { GROUP_ITEMS } from './document.js';
 
 /** The unwrap key: proxy → its internal record. */
 const NODE = Symbol('jaren-linq-node');
@@ -26,14 +35,71 @@ const NODE = Symbol('jaren-linq-node');
  * goes through a bracketed, single-quoted selector. */
 const SHORTHAND_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
-let activeEpoch = 0;
+/** A bare binding variable (`$it`, `$it2`, `$r1`): the one subject a
+ * hop correlates with directly; a fanned path is bound first. */
+const BARE_VAR_RE = /^\$[A-Za-z_][A-Za-z0-9_]*$/;
+
+let epochCounter = 0;
+
+/**
+ * The captures in progress, innermost last. A proxy is LIVE while its
+ * capture is on this stack and CURRENT only at the top: a nested
+ * capture (a chain built and run inside another callback) leaves the
+ * enclosing proxies usable once it returns, while a proxy of the
+ * enclosing capture used INSIDE the nested one is refused by name —
+ * the inner document would rebind `$it`, so the outer reference would
+ * silently point at the wrong item.
+ * @type {number[]}
+ */
+const captureStack = [];
 
 /** @param {any} record */
 function assertLive(record) {
-  if (record.epoch !== activeEpoch) {
+  if (record.epoch === captureStack[captureStack.length - 1]) return;
+  if (captureStack.includes(record.epoch)) {
     throw new LinqBuildError('JL0002',
-      'an expression proxy escaped its capture callback; expressions cannot be stored and replayed across operators');
+      'an expression proxy of an enclosing capture was used inside a nested capture — '
+      + 'a correlated subquery cannot be spelled this way (the inner document rebinds the '
+      + 'item); compute the inner query first and use its result');
   }
+  throw new LinqBuildError('JL0002',
+    'an expression proxy escaped its capture callback; expressions cannot be stored and replayed across operators');
+}
+
+/**
+ * A member name as an RFC 9535 bracketed name selector. Backslashes and
+ * quotes are escaped, and so are the control characters the grammar
+ * forbids unescaped (U+0000–U+001F): without this a key holding a tab
+ * emitted a path the engine refused at RUN time (`JQ0004`), while
+ * `get()` is documented as the way to reach any key at all.
+ * @param {string} name
+ * @returns {string}
+ */
+function bracketName(name) {
+  let escaped = '';
+  for (const c of name) {
+    const code = c.charCodeAt(0);
+    if (c === '\\') escaped += '\\\\';
+    else if (c === "'") escaped += "\\'";
+    else if (code >= 0x20) escaped += c;
+    else if (c === '\b') escaped += '\\b';
+    else if (c === '\f') escaped += '\\f';
+    else if (c === '\n') escaped += '\\n';
+    else if (c === '\r') escaped += '\\r';
+    else if (c === '\t') escaped += '\\t';
+    else escaped += '\\u' + code.toString(16).padStart(4, '0');
+  }
+  return `['${escaped}']`;
+}
+
+/**
+ * One member step on a path: the shorthand for an identifier, the
+ * bracketed selector for anything else.
+ * @param {string} name
+ * @returns {string}
+ */
+function memberSegment(name) {
+  return SHORTHAND_RE.test(name) ? `.${name}` : bracketName(name);
 }
 
 /**
@@ -63,7 +129,7 @@ function embedString(s) {
  * where the caller can see which value it was.
  * @param {any} value
  */
-function isPlainJson(value) {
+export function isPlainJson(value) {
   if (value === null) return true;
   const type = typeof value;
   if (type === 'string' || type === 'boolean') return true;
@@ -81,17 +147,42 @@ function isPlainJson(value) {
   return true;
 }
 
+/**
+ * Refuse a parameter value that is not query data. A binding travels
+ * into a document as an external, and later into a provider as a bound
+ * SQL parameter, so a `Date`, `Map`, `NaN` or `-0` here would compare
+ * against nothing and answer `[]` with no error anywhere. One check for
+ * both surfaces, one message.
+ * @param {string} name
+ * @param {any} value
+ */
+export function requireJsonBinding(name, value) {
+  if (isPlainJson(value)) return;
+  const what = value !== null && typeof value === 'object'
+    ? `a ${value.constructor?.name ?? 'non-plain'} instance`
+    : typeof value === 'number' ? (Object.is(value, -0) ? '-0' : String(value))
+      : `a ${typeof value}`;
+  throw new LinqBuildError('JL0004',
+    `parameter '${name}' is bound to ${what}, which is not query data — convert it `
+    + 'first (a Date to its ISO string or epoch number, a Map to an object, NaN or -0 to a number)');
+}
+
 /**
  * Turn a captured callback result — a proxy, a literal, or a plain
  * object/array tree containing proxies — into a query expression.
  * Objects without `$`-prefixed keys become Rule 1 constructors; a
  * `$`-keyed data object embeds through `$map` so it stays a
  * constructor rather than colliding with the operator vocabulary;
- * pure data trees embed as `$const`.
+ * pure data trees embed as `$const` — unless `fold` is false, when
+ * they are spelled as constructor trees too (a stylesheet body writes
+ * its output the way the format's own examples do: `{ "level":
+ * "unknown" }`, not `{ "$const": … }` — the same value, the published
+ * spelling).
  * @param {any} value
+ * @param {boolean} [fold] - whether a pure data tree folds into one `$const`
  * @returns {any} a query expression (plain JSON)
  */
-export function toExpression(value) {
+export function toExpression(value, fold = true) {
   if (value === null) return null;
   const t = typeof value;
   if (t === 'string') return embedString(value);
@@ -117,7 +208,7 @@ export function toExpression(value) {
       assertLive(record);
       return record.doc;
     }
-    if (isPlainJson(value)) {
+    if (fold && isPlainJson(value)) {
       // verbatim data: cheaper and clearer than a constructor tree
       return { $const: value };
     }
@@ -128,7 +219,7 @@ export function toExpression(value) {
           'a captured expression cannot embed an Array subclass instance — its behaviour '
           + 'is not expressible as query data');
       }
-      return value.map(toExpression);
+      return value.map((v) => toExpression(v, fold));
     }
     if (proto !== Object.prototype && proto !== null) {
       // a Date, Map, Set, RegExp or class instance: `Object.keys` reports
@@ -142,14 +233,14 @@ export function toExpression(value) {
     }
     const keys = Object.keys(value);
     if (keys.some((k) => k.charCodeAt(0) === 0x24)) {
-      return { $map: keys.map((k) => [embedString(k), toExpression(value[k])]) };
+      return { $map: keys.map((k) => [embedString(k), toExpression(value[k], fold)]) };
     }
     const out = {};
     // an own `__proto__` member is DATA here; plain assignment would set
     // the builder's prototype and drop the member
     for (const key of keys) {
       Object.defineProperty(out, key, {
-        value: toExpression(value[key]),
+        value: toExpression(value[key], fold),
         writable: true,
         enumerable: true,
         configurable: true,
@@ -158,7 +249,9 @@ export function toExpression(value) {
     return out;
   }
   throw new LinqBuildError('JL0005',
-    `a captured expression cannot embed a ${t === 'undefined' ? 'undefined' : t} value`);
+    // `typeof undefined` IS 'undefined', so the two arms of the article
+    // are what differ here — not the noun
+    `a captured expression cannot embed ${t === 'undefined' ? 'an' : 'a'} ${t} value`);
 }
 
 /** Binary operator helper. @param {string} op */
@@ -171,6 +264,18 @@ const unary = (op) => function (/** @type {any} */ record) {
   return makeExpr({ [op]: record.doc }, record.epoch, false);
 };
 
+/**
+ * A unary operator that ranges over ITEMS: on a root that stands for
+ * an array value with a fanned twin (`groupJoin`'s group is bound as an
+ * array so `at`/`all`/member position work, and its aggregates count
+ * the members, not the array), the operator applies to the fanned
+ * path; elsewhere it is `unary`.
+ * @param {string} op
+ */
+const fanned = (op) => function (/** @type {any} */ record) {
+  return makeExpr({ [op]: record.seq ?? record.doc }, record.epoch, false);
+};
+
 /**
  * `$date-add` / `$date-sub`: `[date, duration]` or `[date, amount, unit]`.
  * @param {any} record
@@ -210,7 +315,7 @@ function literalSpec(spec, method) {
 
 /**
  * The operator methods, name → builder(record, ...args). One table so
- * the mapping in LINQ-FORMAT.md §4 has exactly one code counterpart.
+ * the mapping in QUERY-PEN.md §4 has exactly one code counterpart.
  * Null prototype: `constructor`/`toString` must read as member access,
  * never as inherited "methods".
  */
@@ -227,7 +332,7 @@ const METHODS = {
   div: binary('$div'), idiv: binary('$idiv'), mod: binary('$mod'),
   neg: unary('$neg'),
   // §8.2 existence
-  exists: unary('$exists'), isEmpty: unary('$empty'),
+  exists: fanned('$exists'), isEmpty: fanned('$empty'),
   // §8.7 strings
   startsWith: binary('$starts-with'), endsWith: binary('$ends-with'),
   contains: binary('$contains'), matches: binary('$match'),
@@ -247,8 +352,8 @@ const METHODS = {
   },
   // §8.8 aggregates as EXPRESSIONS (a group inside a projection:
   // `(u, g) => ({ n: g.count() })`)
-  count: unary('$count'), sum: unary('$sum'), avg: unary('$avg'),
-  min: unary('$min'), max: unary('$max'),
+  count: fanned('$count'), sum: fanned('$sum'), avg: fanned('$avg'),
+  min: fanned('$min'), max: fanned('$max'),
   // §8.13 dates — the whole family, not a corner of it. A date in this
   // suite is an RFC 3339 STRING, so every one of these is an ordinary
   // string operator with a calendar's worth of rules behind it, and
@@ -342,6 +447,11 @@ const METHODS = {
     return makeExpr({ $get: [record.doc, toExpression(index)] }, record.epoch, false);
   },
   all(record) {
+    // a hop's related rows, fanned: the phrase itself, a sequence
+    if (record.hop !== undefined) return makeHop({ ...record.hop, fan: true }, record.epoch, record.nav);
+    // a bound array's fan carries the array's navigation (a group-join's
+    // group holds the inner rows; a hop off them binds each row first)
+    if (record.seq !== undefined) return makeExpr(record.seq, record.epoch, true, { nav: record.nav });
     if (!record.pathable) {
       throw new LinqBuildError('JL0005',
         "all() fans out a PATH ('$it.tags[*]'); it cannot follow an operator result");
@@ -349,24 +459,249 @@ const METHODS = {
     return makeExpr(`${record.doc}[*]`, record.epoch, true);
   },
   get(record, name) {
-    if (typeof name === 'string' && record.pathable) {
-      return makeExpr(`${record.doc}['${name.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}']`,
-        record.epoch, true);
+    if (typeof name === 'string') {
+      // a relation name hops through get() as it does through member
+      // access — the escape reaches a relation that collides with a
+      // method name (`get('count')`), not a stored member of that name
+      if (navigates(record, name)) return startHop(record, name);
+      if (record.hop !== undefined) return extendHop(record, bracketName(name));
+      if (record.pathable) return pathStep(record, name, bracketName(name));
     }
     return makeExpr({ $get: [record.doc, toExpression(name)] }, record.epoch, false);
   },
 };
 
+//#region relation hops
+
+/**
+ * The root spelling of an entity array in a multi-entity document —
+ * MODEL-FORMAT §10.1's `$.<Entity>[*]`, the one spelling the store's
+ * planner reads. Spelled here, never imported.
+ * @param {string} name
+ */
+const entityRootOf = (name) => `$.${name}[*]`;
+
+/**
+ * Whether a member name on this record is a relation of the entity
+ * whose rows the record stands for: the record carries a relation
+ * table (a binding root, or a hop's target at its root) and the table
+ * names the member. A group-join's group carries its table for its FAN
+ * only — the group itself is an array, not a row.
+ * @param {any} record
+ * @param {string} name
+ */
+function navigates(record, name) {
+  return record.nav !== undefined && !record.navOnFan
+    && Object.hasOwn(record.nav.table, name);
+}
+
+/**
+ * The relation entry a hop may lower from, or the coded refusal: a
+ * many-to-many member has no queryable join-table root in this version
+ * (the phrase would need one — `load({ include })` reads the
+ * memberships), and a foreign-key relation needs its key column and the
+ * single key it references (a composite key would need a tuple equality
+ * the vocabulary does not spell).
+ * @param {any} relation
+ * @param {string} member
+ */
+function checkRelation(relation, member) {
+  if (relation === null || typeof relation !== 'object' || typeof relation.to !== 'string') {
+    throw new LinqBuildError('JL0105',
+      `the relation table names '${member}' but its entry is not a relation record `
+      + '({ to, kind, via, fkEntity, fkTargets, targetKey } — MODEL-FORMAT §10.1)');
+  }
+  if (relation.kind === 'manyToMany') {
+    throw new LinqBuildError('JL0105',
+      `'${member}' is a many-to-many relation: the join table '${relation.joinTable}' is not a `
+      + 'queryable root in this version, so the hop has no phrase to lower to — read the '
+      + `memberships with load({ include: { ${member}: true } })`);
+  }
+  if (relation.kind !== 'oneToOne' && relation.kind !== 'oneToMany') {
+    throw new LinqBuildError('JL0105',
+      `'${member}' has relation kind '${String(relation.kind)}', which is not one this `
+      + 'surface lowers (oneToOne, oneToMany)');
+  }
+  if (typeof relation.via !== 'string' || typeof relation.targetKey !== 'string') {
+    throw new LinqBuildError('JL0105',
+      `'${member}' cannot lower: its foreign key or the key it references is composite or `
+      + 'undeclared, and the hop\'s equality would need a tuple the vocabulary does not spell');
+  }
+}
+
+/**
+ * A hop chain as one nested document: each link binds its source,
+ * correlates through its `$where`, and returns the next link — the
+ * innermost returns `ret`, the path over the last binding.
+ * @param {readonly { binding: string, source: any, where?: any }[]} chain
+ * @param {any} ret
+ * @returns {any}
+ */
+function hopDocument(chain, ret) {
+  let doc = ret;
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const link = chain[i];
+    /** @type {any} */
+    const phrase = { $for: { [link.binding]: link.source } };
+    if (link.where !== undefined) phrase.$where = link.where;
+    phrase.$return = doc;
+    doc = phrase;
+  }
+  return doc;
+}
+
+/**
+ * The proxy over a hop: as a VALUE a to-one hop is its phrase (zero or
+ * one row — an object member's one value, an empty operand elsewhere)
+ * and a to-many hop is the phrase packed into an array (`[phrase]`, the
+ * array of related rows a member holds); fanned (`all()`), either is the
+ * bare phrase, a sequence the aggregates and `exists()` range over. The
+ * fanned twin is the phrase in every case, so `count()`/`exists()` on
+ * the value count the rows, as they do on a group-join's group.
+ * @param {{ chain: any[], ret: string, many: boolean, fan: boolean }} hop
+ * @param {number} epoch
+ * @param {any} nav - the target entity's navigation, while `ret` is its root
+ */
+function makeHop(hop, epoch, nav) {
+  const phrase = hopDocument(hop.chain, hop.ret);
+  return makeExpr(hop.many && !hop.fan ? [phrase] : phrase, epoch, false,
+    { seq: phrase, nav, hop });
+}
+
+/**
+ * Record one hop: `member` is a relation of the rows `target` stands
+ * for. The subject the new binding correlates with is a bare binding
+ * variable — the root (`$it`), or the previous hop's binding (`$r1`) —
+ * or a fanned path (`$g[*]`), which is bound to a binding of its own
+ * first so the equality reads one row. The equality follows the
+ * table's placement of the foreign key: on the declaring entity
+ * (`oneToOne`) the target's key equals the subject's `via`; on the
+ * target (`oneToMany`) the target's `via` equals the subject's key.
+ * @param {any} target - the record the member was read on
+ * @param {string} member
+ */
+function startHop(target, member) {
+  const { table, resolve, sink } = target.nav;
+  const relation = table[member];
+  checkRelation(relation, member);
+  const chain = target.hop === undefined ? [] : [...target.hop.chain];
+  let subject = target.hop === undefined ? target.doc : target.hop.ret;
+  // a hop off a FANNED subject (a fanned to-many hop, a bound fan) is a
+  // sequence — one target per subject row, flattened by the outer
+  // phrase — never an array value; off a singular subject it is a
+  // value: the row (to-one) or the array of rows (to-many)
+  let many = target.hop !== undefined && target.hop.many;
+  let fan = target.hop !== undefined && target.hop.fan;
+  if (!BARE_VAR_RE.test(subject)) {
+    const binding = `r${sink.next++}`;
+    chain.push({ binding, source: subject });
+    subject = '$' + binding;
+    many = true;
+    fan = true;
+  }
+  const binding = `r${sink.next++}`;
+  const where = relation.kind === 'oneToMany'
+    ? { $eq: [`$${binding}${memberSegment(relation.via)}`, `${subject}${memberSegment(relation.targetKey)}`] }
+    : { $eq: [`$${binding}${memberSegment(relation.targetKey)}`, `${subject}${memberSegment(relation.via)}`] };
+  chain.push({ binding, source: entityRootOf(relation.to), where });
+  sink.hops.push({ member, kind: relation.kind, binding });
+  const targetTable = resolve(relation.to);
+  return makeHop(
+    { chain, ret: '$' + binding, many: many || relation.kind === 'oneToMany', fan },
+    target.epoch,
+    targetTable === undefined ? undefined : { table: targetTable, resolve, sink });
+}
+
+/**
+ * A member of the hop's target row: the phrase returns the path over its
+ * last binding, extended. A to-many hop is an ARRAY of rows until it is
+ * fanned — a member read off the array is refused with the fix named,
+ * where the same read off a stored array would answer nothing.
+ * @param {any} target
+ * @param {string} segment - the spelled path step (`.email`, `['odd key']`)
+ */
+function extendHop(target, segment) {
+  const hop = target.hop;
+  if (hop.many && !hop.fan) {
+    throw new LinqBuildError('JL0005',
+      `${segment} is read off a to-many relation, which holds an array of related rows — `
+      + `fan them first (.all()${segment}), index one (.at(0)), or aggregate the array`);
+  }
+  return makeHop({ ...hop, ret: `${hop.ret}${segment}` }, target.epoch, undefined);
+}
+
+/**
+ * A fresh hop sink for one capture: the bindings allocated so far
+ * (`r1`, `r2`, … — numbered per capture, across all its roots) and the
+ * hops recorded, in the order the callback navigated them.
+ * @returns {{ hops: { member: string, kind: string, binding: string }[], next: number }}
+ */
+export function createHopSink() {
+  return { hops: [], next: 1 };
+}
+
+/**
+ * A binding root whose items are an entity's rows: the bare name when
+ * there is nothing to carry, else the root record with the relation
+ * table, the resolver for the other roots of its scope, the capture's
+ * sink, and — after a `groupBy` — the member the group's rows live in.
+ * @param {string} name - the binding (`it`, `it2`)
+ * @param {{ table: any, resolve: (name: string) => any } | null} relations
+ * @param {ReturnType<typeof createHopSink>} sink
+ * @param {boolean} [grouped] - whether the items are a `{ key, items }`
+ *   group, whose `items` aggregate as rows ({@link pathStep})
+ * @returns {any}
+ */
+export function rowRoot(name, relations, sink, grouped = false) {
+  if (relations === null && !grouped) return name;
+  const root = { doc: '$' + name, pathable: true };
+  if (grouped) root.group = GROUP_ITEMS;
+  if (relations !== null) {
+    root.nav = { table: relations.table, resolve: relations.resolve, sink };
+  }
+  return root;
+}
+
+/**
+ * A group-join's group root: the `$g` array value with its `$g[*]` fan
+ * — and, when the inner rows have a relation table, that table on the
+ * FAN, so `g.all().author` hops from each row.
+ * @param {{ table: any, resolve: (name: string) => any } | null} relations
+ * @param {ReturnType<typeof createHopSink>} sink
+ * @returns {any}
+ */
+export function groupRoot(relations, sink) {
+  const root = { doc: '$g', pathable: true, seq: '$g[*]' };
+  return relations === null
+    ? root
+    : { ...root, nav: { table: relations.table, resolve: relations.resolve, sink }, navOnFan: true };
+}
+
+//#endregion
+
 /**
  * Build one expression proxy.
  * @param {any} doc - the expression JSON so far
  * @param {number} epoch - the owning capture
  * @param {boolean} pathable - whether `doc` is a pure path string that
  *   member access may extend
+ * @param {{ seq?: any, nav?: any, navOnFan?: boolean, hop?: any,
+ *   group?: string }} [extra] -
+ *   `seq`: for a value standing for an array or a hop, the fanned form
+ *   its aggregates range over (`'$g[*]'`, a hop's phrase); `nav`: the
+ *   relation table of the rows the value stands for, with the resolver
+ *   for the other roots and the capture's hop sink; `navOnFan`: the
+ *   table applies to the fan, not the value; `hop`: the hop chain;
+ *   `group`: the member this value carries a GROUP's rows in, whose
+ *   aggregates therefore range over the rows
  * @returns {any}
  */
-function makeExpr(doc, epoch, pathable) {
-  const record = { doc, epoch, pathable };
+function makeExpr(doc, epoch, pathable, extra = undefined) {
+  const record = {
+    doc, epoch, pathable,
+    seq: extra?.seq, nav: extra?.nav, navOnFan: extra?.navOnFan === true, hop: extra?.hop,
+    group: extra?.group,
+  };
   return new Proxy(record, {
     get(target, prop) {
       if (prop === NODE) return target;
@@ -379,17 +714,43 @@ function makeExpr(doc, epoch, pathable) {
         };
       }
       assertLive(target);
-      if (target.pathable) {
-        const step = SHORTHAND_RE.test(prop)
-          ? `${target.doc}.${prop}`
-          : `${target.doc}['${prop.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}']`;
-        return makeExpr(step, target.epoch, true);
-      }
-      return makeExpr({ $get: [target.doc, prop] }, target.epoch, false);
+      return member(target, prop);
     },
   });
 }
 
+/**
+ * Member access: a relation name records a hop; a hop's target extends
+ * the phrase's return path; a pathable path extends; anything else is
+ * a `$get` over the operator result.
+ * @param {any} target
+ * @param {string} prop
+ */
+function member(target, prop) {
+  if (navigates(target, prop)) return startHop(target, prop);
+  if (target.hop !== undefined) return extendHop(target, memberSegment(prop));
+  if (target.pathable) return pathStep(target, prop, memberSegment(prop));
+  return makeExpr({ $get: [target.doc, prop] }, target.epoch, false);
+}
+
+/**
+ * One path step off a pathable value, member access or `get()`.
+ *
+ * A GROUP's rows aggregate as rows: after `groupBy` the item is
+ * `{ key, items }` and `items` holds the group, so `g.items.count()`
+ * ranges over the rows the way a group-join's `g.count()` already does
+ * ({@link groupRoot}). `g.items` itself is still the array — a member
+ * takes it whole (`{ matches: g.items }`), `at()` indexes it and
+ * `all()` fans it — so only the aggregates change, and only for the one
+ * member the emitter writes the group into.
+ * @param {any} target @param {string|number} prop @param {string} segment
+ */
+function pathStep(target, prop, segment) {
+  const doc = `${target.doc}${segment}`;
+  return makeExpr(doc, target.epoch, true,
+    target.group === prop ? { seq: `${doc}[*]` } : undefined);
+}
+
 /**
  * The parameters proxy: `p.tenantId` emits the external `$tenantId` —
  * when the name was declared via `.params({...})`. Undeclared use is
@@ -415,24 +776,64 @@ function makeParams(declared, epoch) {
  * Run one capture: `fn` receives a proxy per root (plus the parameters
  * proxy last) and its result becomes an expression via
  * {@link toExpression}. A root is a binding NAME (`'it'` → the pathable
- * `$it`) or a `{ doc, pathable }` record for an expression-valued root
- * (groupJoin's inner group). Proxies die with the capture — reuse is
- * `JL0002`.
+ * `$it`) or a `{ doc, pathable, seq?, nav?, navOnFan? }` record for a
+ * bound root ({@link rowRoot}: an entity's rows with their relation
+ * table; {@link groupRoot}: groupJoin's group, the `$g` array whose
+ * aggregates fan over `$g[*]`). Captures nest — a chain built and run
+ * inside a callback is ordinary — but a proxy used outside its capture,
+ * or an enclosing capture's proxy used inside a nested one, is `JL0002`.
  * @param {(...roots: any[]) => any} fn - the user callback
- * @param {readonly (string | { doc: any, pathable: boolean })[]} roots
+ * @param {readonly (string | { doc: any, pathable: boolean, seq?: string,
+ *   nav?: any, navOnFan?: boolean })[]} roots
  * @param {Set<string>} declaredParams
+ * @param {boolean} [fold] - whether a pure data tree folds into one
+ *   `$const` (the chain's spelling) or is a constructor tree (a pen's)
  * @returns {any} the captured expression (plain JSON)
  */
-export function captureExpression(fn, roots, declaredParams) {
-  const epoch = ++activeEpoch;
+export function captureExpression(fn, roots, declaredParams, fold = true) {
+  const epoch = ++epochCounter;
   const proxies = roots.map((root) => (typeof root === 'string'
     ? makeExpr('$' + root, epoch, true)
-    : makeExpr(root.doc, epoch, root.pathable)));
+    : makeExpr(root.doc, epoch, root.pathable, root)));
   proxies.push(makeParams(declaredParams, epoch));
+  captureStack.push(epoch);
   try {
-    return toExpression(fn(...proxies));
+    return toExpression(fn(...proxies), fold);
   }
   finally {
-    activeEpoch++; // every proxy of this capture is now dead
+    captureStack.pop(); // every proxy of this capture is now dead
+  }
+}
+
+/**
+ * Whether `value` is an expression proxy of some capture (live or not).
+ * A pen walking a captured result before it lowers needs to tell a
+ * proxy from the plain object it would otherwise descend into.
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isExpression(value) {
+  return value !== null && typeof value === 'object' && value[NODE] !== undefined;
+}
+
+/**
+ * Lift a hand-spelled operator expression into the capture in
+ * progress: the escape for an operator the method table does not name
+ * — a registered one (`{ $npv: [...] }`, JSLT-FORMAT §13) or a
+ * body-local one (`$apply`, §6). The document is taken as given — the
+ * engine's compiler is the judge of it (`JQ0002` for an operator it
+ * does not know) — and the proxy it answers is bound to the innermost
+ * capture, so it composes with that capture's own proxies and dies
+ * with them. Outside a capture there is nothing to bind it to:
+ * `JL0005`.
+ * @param {any} doc - the operator expression, plain JSON
+ * @returns {any} an expression proxy over `doc`
+ */
+export function liftExpression(doc) {
+  if (captureStack.length === 0) {
+    throw new LinqBuildError('JL0005',
+      'an operator expression can only be lifted inside a capture callback — no capture '
+      + 'is in progress to bind it to');
   }
+  return makeExpr(doc, captureStack[captureStack.length - 1], false);
 }

package/src/flow/capture.js

@@ -0,0 +1,33 @@
+//@ts-check
+/**
+ * @file The one capture under every query-valued member of the flow
+ * documents: a transition guard and an effect's `with` over
+ * FLOW-FORMAT §3's step scope, a `query` node's document, a task's
+ * `with` and an edge's `select` over §6.1's input scope.
+ *
+ * The scope binds NO externals — both engines evaluate these with a
+ * single `$` and nothing else — so a name read off the capture's second
+ * argument is `JL0104` here, where the fix can be named, rather than
+ * `JQ2006` at step time, where a guard that cannot bind reads as a
+ * recorded false (FLOW-FORMAT §5.2). A returned literal is spelled as
+ * the format's own constructor and never folded into `$const`:
+ * §2's `{ "text": "retrying" }` is what a machine document carries.
+ */
+
+import { cloneJson } from '@jarenjs/core/object';
+import { captureQuery } from '../capture-root.js';
+import { requireJson } from '../json-boundary.js';
+
+/**
+ * One query-valued member: a callback captured over `$`, or a query
+ * document written by hand, copied.
+ * @param {string} what - the method, for the message
+ * @param {string} scope - what `$` is bound to, for the `JL0104` advice
+ * @param {any} value - a callback `(s) => …`, or a query document
+ * @returns {any} the query document (plain JSON)
+ */
+export function queryMember(what, scope, value) {
+  if (typeof value !== 'function') return cloneJson(requireJson(value, what));
+  const advice = () => ` — ${what} evaluates over ${scope}, which its argument IS`;
+  return cloneJson(captureQuery(what, [], value, { advice, fold: false, noun: 'callback' }));
+}