quario 0.0.1 → 0.2.0

package/lib/plan.js

@@ -0,0 +1,1388 @@
+/**
+ * The schema traversal: one descent through the report document that checks
+ * each node against its closed key set — in the documented key order, which is
+ * the order the allowed-key list spells out — and compiles the closures that
+ * render it, collecting problems instead of throwing. `validate()` reads the
+ * problems, `events()` the closures. One traversal, read two ways: a schema key
+ * is checked once, beside the code that compiles it, and never in two walkers.
+ * (The safety suite greps every source file for the forbidden string-to-code
+ * constructs, so they must not appear even in a comment.)
+ *
+ * It is a traversal, never a walk: that word belongs to the event stream and
+ * its driver (CONTEXT.md). Six layers hold it, each a factory named for what it
+ * returns and taking the layers it builds on, composed by `plan()` at the foot
+ * of the file:
+ *
+ *   1. `planState`  — what the whole descent accumulates: problems, names,
+ *                     functions, and the stubs a failed compile stands in
+ *   2. `primitives` — authored source to located evaluator; the only layer that
+ *                     throws, which is why every reader wraps it in `attempt`
+ *   3. `readers`    — one per kind of declared value: each checks, compiles and
+ *                     reports, and the nodes call them in documented key order
+ *   4. `nodes`      — the document's addressable pieces: cells, headers,
+ *                     columns, totals, items
+ *   5. `bands`      — the generators those pieces render through: the detail
+ *                     band and the group chain around it
+ *   6. `traverse`   — the root descent, in the schema's documented key order
+ *
+ * Only `plan` is exported. A layer reachable from outside this file is the
+ * first step toward the validate/compile split the single traversal rules out.
+ */
+// Each engine's own predicate, not the union `locate.js` exports: every call
+// site knows which engine it just called, and asking that one is what stops a
+// sjabloon-shaped error being trusted where an xprsn error was expected.
+import { isDiagnostic as isQueryDiagnostic, query, relocate as relocateQuery } from "padvinder";
+import {
+  compile,
+  isDiagnostic as isXprsnDiagnostic,
+  relocate as relocateXprsn,
+  signatures,
+} from "xprsn";
+import {
+  isDiagnostic as isTemplateDiagnostic,
+  relocate as relocateTemplate,
+  template,
+} from "sjabloon";
+import { LOCATION, fault, isDiagnostic, locate } from "./locate.js";
+import { ANCHORS, BLOCKED, NAME, RESERVED, record } from "./names.js";
+import { AGG, REDUCERS, RUN, aggregateValue, withRow } from "./scope.js";
+import { opt, sniff } from "./stream.js";
+import { checkImageStyle, checkReportStyle, checkStyle } from "./style.js";
+
+// Tolerance on the column-width sum. Widths are literal numbers an author may
+// write as thirds, so an exact comparison rejects 33.3 x 3 for a rounding error
+// nobody wrote. Small enough that it can never excuse a real over-commitment.
+let WIDTH_EPS = 1e-9;
+
+// What a failed compile stands in. Stateless, so one of each serves every
+// plan rather than riding the state a plan accumulates.
+/** @type {any} */
+let NIL = () => null;
+/** @type {any} */
+let EMPTY = () => [];
+// What `$.params` reads when a report declares none.
+let NONE = Object.freeze({});
+
+/** @type {(value: any) => boolean} */
+let isExpr = (value) => typeof value === "string" && value[0] === "=";
+/** @type {(from: Iterable<string>, into: Set<string>) => void} */
+let collect = (from, into) => {
+  for (let name of from) into.add(name);
+};
+/** @type {(visible: any, scope: any) => any} */
+let hidden = (visible, scope) => visible && visible(scope) === false;
+
+// A text item's closed key set, and the same set inside a split, where the
+// slot's width share joins it.
+let TEXT_KEYS = ["type", "value", "visible", "style"];
+let TEXT_SLOT_KEYS = [...TEXT_KEYS, "width"];
+let IMAGE_KEYS = ["type", "source", "fit", "alt", "visible", "style"];
+let IMAGE_SLOT_KEYS = [...IMAGE_KEYS, "width"];
+
+// Which detail events carry the row's running values: the ones holding a cell.
+// A split's bracket holds none, so run rides the item and image events inside
+// it rather than the bracket around them.
+/** @type {(event: any) => boolean} */
+let carriesRun = (event) => event.type === "item" || event.type === "image";
+/** @type {(value: any, path: string, role: string, itemsOf: any) => any} */
+let maybeItems = (value, path, role, itemsOf) =>
+  value != null ? itemsOf(value, path, role) : null;
+
+// The width-share rule, shared by a table's columns and a split's slots: the
+// two carry the same percentages under the same arithmetic, and one reader for
+// both is what keeps them from drifting into two rules wearing one name.
+/** @type {(sized: boolean, noun: string) => string} */
+let shareMsg = (sized, noun) =>
+  sized
+    ? "expected " + noun + " widths to total at most 100"
+    : "expected " +
+      noun +
+      " widths to total under 100, leaving room for the " +
+      noun +
+      "s without one";
+// The authored shares worth summing, or null when there is nothing to decide.
+// Nothing authored is nothing to check; a width out of range (a NaN, per the
+// width verdict) already carries its own problem, and one nobody can read
+// leaves it undecidable whether its part is one of those needing room.
+/** @type {(parts: { width?: any }[]) => number[] | null} */
+let sharesOf = (parts) => {
+  let shares = parts.map((part) => part.width).filter((width) => width != null);
+  return !shares.length || shares.some(Number.isNaN) ? null : shares;
+};
+// Authored shares must leave room for the parts without one. Widths are
+// literal, so the sum is known here; a tolerance keeps three at 33.3 from
+// summing to 100.00000000000001 and failing on IEEE 754 alone.
+/** @type {(bad: any, parts: { width?: any }[], path: string, noun: string) => void} */
+let checkShares = (bad, parts, path, noun) => {
+  let shares = sharesOf(parts);
+  if (!shares) return;
+  let total = shares.reduce((all, width) => all + width, 0);
+  let sized = shares.length === parts.length;
+  if (total > (sized ? 100 + WIDTH_EPS : 100 - WIDTH_EPS)) bad(path, shareMsg(sized, noun));
+};
+
+// One pass over a report's constants: it checks each value, copies it, and
+// freezes the copy. Copying is what keeps a consumer from reaching back into
+// the compiled schema through a nested object; freezing is what stops them
+// mutating what they were handed.
+//
+// The vocabulary is JSON's, not structured clone's, because the document a
+// report is written in is JSON (SCHEMA.md, "Deliberate asymmetries"): a Date,
+// a Map or a typed array cannot appear in one, so accepting them here would
+// only ever serve a schema built in JS -- and it is what forced the caveat
+// about the values freezing cannot lock. Rejecting them makes the freeze
+// total. NaN and Infinity go with them: JSON cannot hold either, and
+// coercing them to null would turn a definition error into a wrong value
+// three bands away.
+//
+// `seen` rejects cycles rather than surviving them, for the same reason: a
+// JSON document has no way to write one.
+/** @type {(value: any) => boolean} */
+let isJsonAtom = (value) =>
+  value === null || typeof value === "boolean" || typeof value === "string";
+/** @type {(value: any, reject: () => any) => any} */
+let jsonNumber = (value, reject) => {
+  // NaN and Infinity are numbers no JSON document can hold.
+  if (typeof value !== "number") return undefined;
+  if (Number.isFinite(value)) return value;
+  return reject();
+};
+/** @type {(value: any) => boolean} */
+let isPlain = (value) => {
+  // Plain objects and arrays only. A Date, Map, Set, typed array or class
+  // instance all pass a bare `typeof value === "object"`; the prototype is
+  // what separates them from something `JSON.parse` could have produced.
+  let proto = Object.getPrototypeOf(value);
+  return Array.isArray(value) || proto === Object.prototype || proto === null;
+};
+/** @type {(value: any, path: string, bad: (path: string, msg: string) => void, seen: Set<object>) => any} */
+let jsonChildren = (value, path, bad, seen) => {
+  if (Array.isArray(value))
+    return value.map((nested, i) => jsonCopy(nested, path + "[" + i + "]", bad, seen));
+  return Object.fromEntries(
+    Object.entries(value).map(([key, nested]) => [
+      key,
+      jsonCopy(nested, path + "." + key, bad, seen),
+    ]),
+  );
+};
+/** @type {(value: any, path: string, bad: (path: string, msg: string) => void, seen: Set<object>, reject: () => any) => any} */
+let jsonObject = (value, path, bad, seen, reject) => {
+  if (typeof value !== "object") return reject();
+  // `seen` holds the ancestors of the value being copied, not everything
+  // visited, so a value referenced twice as a sibling -- legal JSON, and what
+  // a DAG looks like -- is copied twice rather than rejected. Only a value
+  // that contains itself is refused, and the path names the key that closes
+  // the loop.
+  if (!isPlain(value) || seen.has(value)) return reject();
+  seen.add(value);
+  let copy = jsonChildren(value, path, bad, seen);
+  seen.delete(value);
+  return Object.freeze(copy);
+};
+/** @type {(value: any, path: string, bad: (path: string, msg: string) => void, seen: Set<object>) => any} */
+let jsonCopy = (value, path, bad, seen) => {
+  let reject = () => {
+    bad(path, "expected a JSON value");
+    return null;
+  };
+  if (isJsonAtom(value)) return value;
+  let number = jsonNumber(value, reject);
+  if (number !== undefined) return number;
+  return jsonObject(value, path, bad, seen, reject);
+};
+
+/** @typedef {import("./scope.js").Scope} Scope */
+/** @typedef {import("./scope.js").Eval} Eval */
+/** @typedef {import("./scope.js").Fold} Fold */
+/** @typedef {import("./scope.js").RunnerSet} RunnerSet */
+/** @typedef {(rows: any[], scope: Scope, runners: RunnerSet) => Generator<any>} Band */
+/** @typedef {ReturnType<typeof planState>} State */
+/** @typedef {ReturnType<typeof primitives>} Primitives */
+/** @typedef {ReturnType<typeof readers>} Readers */
+/** @typedef {ReturnType<typeof nodes>} Nodes */
+/** @typedef {ReturnType<typeof bands>} Bands */
+
+// --- 1. plan state --------------------------------------------------------
+//
+// Everything the descent accumulates, and the two ways it records a fault:
+// `bad`/`add` for a problem it can describe itself, `attempt` for a compile
+// step that threw.
+
+/**
+ * @param {any} group
+ * @param {Set<string>} bound
+ */
+let bindHandle = (group, bound) => {
+  if (record(group) && typeof group.name === "string") bound.add(group.name);
+};
+/**
+ * @param {any} schema
+ * @param {Set<string>} bound
+ */
+let bindHandles = (schema, bound) => {
+  if (!record(schema) || !Array.isArray(schema.groups)) return;
+  for (let group of schema.groups) bindHandle(group, bound);
+};
+
+/**
+ * @param {any} schema The report document.
+ * @param {Record<string, Function>} [funcs] Functions callable from expressions.
+ */
+let planState = (schema, funcs) => {
+  /** @type {Record<string, (...args: any[]) => any>} */
+  let FNS = /** @type {any} */ ({ ...REDUCERS, ...funcs });
+  /** @type {Set<string>} */
+  let names = new Set();
+  /** @type {Set<string>} */
+  let functions = new Set();
+  // Engine-provided anchors plus this report's group handles: bound at
+  // evaluation time, so they are not free variables and stay out of `names`.
+  // Seeded from ANCHORS, not RESERVED -- a name merely held for a future anchor
+  // is still a free variable today and must keep showing up in `names`.
+  let BND = new Set(ANCHORS);
+  bindHandles(schema, BND);
+
+  // Structured problems: the path was a live value at every site that reports
+  // one, so it is kept as a field rather than recovered from the message. The
+  // message stays the whole located string — `validate()`'s view is
+  // `problems.map((p) => p.message)`, unchanged.
+  /** @type {{ path: string, source?: string, message: string, diagnostic?: any }[]} */
+  let problems = [];
+  // Kept so `events()` rethrows the engine's located error, not a bare one.
+  /** @type {any} */
+  let firstDiag = null;
+  // Where a caught error says it happened: `locate()` stamps that on the copy
+  // it throws, so nothing here parses a message back apart.
+  /** @type {(error: any) => { path: string, source?: any }} */
+  let where = (error) => (error && error[LOCATION]) || { path: "" };
+  // A caught error carries its location as data (locate.js), so the problem
+  // keeps the path and source structurally; the diagnostic rides along per
+  // problem — every problem keeps its offsets, not only the first.
+  /** @type {(msg: string, error?: any) => any} */
+  let located = (msg, error) => {
+    let at = where(error);
+    /** @type {any} */
+    let problem = { path: at.path, message: msg };
+    if (at.source !== undefined) problem.source = String(at.source);
+    if (isDiagnostic(error)) problem.diagnostic = error;
+    return problem;
+  };
+  /** @type {(msg: string, error?: any) => void} */
+  let add = (msg, error) => {
+    // Identity, not shape: locate() copies an untrusted host throw with
+    // `new error.constructor(...)`, so a host class that stamps `code` on
+    // itself produces a copy shaped like a diagnostic. Only an error the
+    // engines authenticated is worth rethrowing as one (quario-lkz).
+    if (!problems.length && isDiagnostic(error)) firstDiag = error;
+    problems.push(located(msg, error));
+  };
+  /** @type {(path: string, msg: string) => void} */
+  let bad = (path, msg) => problems.push({ path, message: path + ": " + msg });
+  // Record a throwing compile step and stand in a stub, so the traversal reports
+  // the whole definition rather than only its first fault.
+  /** @type {<T>(fn: () => T, fallback: T) => T} */
+  let attempt = (compileStep, fallback) => {
+    try {
+      return compileStep();
+    } catch (error) {
+      add(/** @type {any} */ (error).message, error);
+      return fallback;
+    }
+  };
+  // The one register two layers share: a report-level `run` block and every
+  // group's are one namespace, so a name declared twice across them is a
+  // definition error. `groupNames` needs no such sharing and stays in `bands`.
+  /** @type {Set<string>} */
+  let runNames = new Set();
+
+  // Which anchors each compiled source actually reads, keyed by its schema
+  // path. Retention, not computation: the engines report every root-name read
+  // in `.reads` — the unfiltered view `bound` keeps out of `.names` — and this
+  // keeps the anchor-and-handle subset a consumer placing a node needs.
+  /** @type {Map<string, Set<string>>} */
+  let anchors = new Map();
+  /** @type {(path: string, reads: { name: string }[]) => void} */
+  let anchorsOf = (path, reads) => {
+    for (let { name } of reads) {
+      if (!BND.has(name)) continue;
+      let set = anchors.get(path);
+      if (!set) anchors.set(path, (set = new Set()));
+      set.add(name);
+    }
+  };
+
+  return {
+    FNS,
+    names,
+    functions,
+    BND,
+    problems,
+    runNames,
+    anchors,
+    anchorsOf,
+    add,
+    bad,
+    attempt,
+    diagnostic: () => firstDiag,
+  };
+};
+
+// --- 2. compile primitives ------------------------------------------------
+//
+// Authored source becomes a located evaluator. These throw; every caller wraps
+// them in `attempt`, which is what keeps one bad cell from ending the descent.
+
+/** @type {(source: any, path: string, FNS: any, BND: Set<string>) => any} */
+let compileProp = (source, path, FNS, BND) => {
+  try {
+    return compile(source.slice(1), FNS, { bound: BND });
+  } catch (error) {
+    locate(path, source, error, isXprsnDiagnostic(error) && relocateXprsn, 1);
+  }
+};
+/** @type {(expression: any, path: string, source: any) => Eval} */
+let runProp = (expression, path, source) => (scope) => {
+  try {
+    return expression(scope);
+  } catch (error) {
+    locate(path, source, error, expression.isDiagnostic(error) && relocateXprsn, 1);
+  }
+};
+/** @type {(src: string, path: string, source: any, FNS: any, BND: Set<string>) => any} */
+let compileCell = (src, path, source, FNS, BND) => {
+  try {
+    return template(src, FNS, { bound: BND });
+  } catch (error) {
+    locate(path, source, error, isTemplateDiagnostic(error) && relocateTemplate);
+  }
+};
+/** @type {(tokens: any, path: string, source: any) => (scope: Scope) => any} */
+let runCell = (tokens, path, source) => (scope) => {
+  try {
+    return tokens.scoped(scope);
+  } catch (error) {
+    locate(path, source, error, tokens.isDiagnostic(error) && relocateTemplate);
+  }
+};
+/** @type {(source: any) => string} */
+let asText = (source) => (typeof source === "string" ? source : "");
+/** @type {(spec: string) => { fn: string, src: string, colon: number }} */
+let splitFold = (spec) => {
+  let colon = spec.indexOf(":");
+  if (colon < 0) return { fn: spec, src: "", colon };
+  return { fn: spec.slice(0, colon), src: spec.slice(colon + 1), colon };
+};
+/** @type {(colon: number, path: string) => void} */
+let checkCount = (colon, path) => {
+  // oxlint-disable-next-line no-unused-expressions
+  colon < 0 || fault(path, "count does not take an expression");
+};
+/** @type {(src: string, fn: string, path: string) => void} */
+let checkExprFold = (src, fn, path) => {
+  // oxlint-disable-next-line no-unused-expressions
+  (src.startsWith("=") && src.length > 1) || fault(path, 'expected "' + fn + ':=<expression>"');
+};
+
+/** @param {State} state */
+let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
+  // A computed property: a literal, or an `=` xprsn expression. xprsn's
+  // `bound` keeps engine-provided anchors/handles out of the reported `names`.
+  /** @type {(spec: any, path: string) => Eval} */
+  let prop = (source, path) => {
+    if (!isExpr(source)) return () => source;
+    let expression = compileProp(source, path, FNS, BND);
+    collect(expression.names, names);
+    collect(expression.functions, functions);
+    anchorsOf(path, expression.reads);
+    return runProp(expression, path, source);
+  };
+
+  // A text cell: a sjabloon template, compiled with the token edition and
+  // rendered over quario's own scope chain, which already binds the anchors:
+  // `$` at the render base, `@` on the detail row, neither anywhere else — so
+  // a group or report band leaves `@` unbound and a stray `@.field` throws.
+  // sjabloon's `bound` excludes its loop vars / `$` / `@` and quario's engine
+  // names alike from the reported `names`. A render yields the cell's public
+  // token stream: literal runs verbatim plus each interpolation's
+  // pre-stringify value. Templates have no raw form — a `{{{ }}}` tag is a
+  // located SJABLOON_RAW_TAG definition error — so escaping is entirely a
+  // render-target concern at the markup edge, with no exceptions to carry
+  // through the stream.
+  /** @type {(str: any, path: string) => (scope: Scope) => any} */
+  let cell = (source, path) => {
+    let tokens = compileCell(asText(source), path, source, FNS, BND);
+    collect(tokens.names, names);
+    collect(tokens.functions, functions);
+    anchorsOf(path, tokens.reads);
+    return runCell(tokens, path, source);
+  };
+
+  // Parse "reducer:=expr" into a reducer name and a compiled per-row expression
+  // (null for `count`, which takes no expression).
+  /** @type {(spec: string, path: string, allowed: Set<string>) => Fold} */
+  let parseFold = (spec, path, allowed) => {
+    let { fn, src, colon } = splitFold(spec);
+    // oxlint-disable-next-line no-unused-expressions
+    allowed.has(fn) || fault(path, 'unknown reducer "' + fn + '"');
+    if (fn === "count") checkCount(colon, path);
+    else checkExprFold(src, fn, path);
+    return { fn, per: src ? prop(src, path) : null };
+  };
+
+  return { prop, cell, parseFold };
+};
+
+// --- 3. readers -----------------------------------------------------------
+//
+// One reader per kind of declared value. Each checks, compiles and reports; the
+// nodes below call them in the documented key order.
+
+/**
+ * @param {State} state
+ * @param {Primitives} primitives
+ */
+let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
+  /** @type {(value: any, path: string) => boolean} */
+  let obj = (value, path) => {
+    if (record(value)) return true;
+    bad(path, "expected an object");
+    return false;
+  };
+  /** @type {(value: any, path: string, required?: boolean) => any[] | null} */
+  let arr = (value, path, required = false) => {
+    if (value == null && !required) return null;
+    if (Array.isArray(value)) return value;
+    bad(path, "expected an array");
+    return null;
+  };
+  // Every schema object is a closed set, so typos and misplaced fields
+  // (page.size, sort on a table detail) fail loud instead of doing nothing.
+  // One schema path from a parent's and a key. The document root's path is the
+  // empty string, so the dot is conditional -- `style.family`, never
+  // `.style.family`. Every reader that can be reached with the root joins
+  // through here rather than restating the rule.
+  /** @type {(path: string, key: string) => string} */
+  let pathTo = (path, key) => (path ? path + "." + key : key);
+  /** @type {(value: any, allowed: string[], path: string) => void} */
+  let keys = (value, allowed, path) => {
+    for (let key of Object.keys(value))
+      if (!allowed.includes(key)) bad(pathTo(path, key), 'unknown key "' + key + '"');
+  };
+  /** @type {(name: string, path: string, reserved?: Set<string> | null) => void} */
+  let checkName = (name, path, reserved) => {
+    if (BLOCKED.has(name)) bad(path, '"' + name + '" is blocked');
+    if (reserved && reserved.has(name)) bad(path, '"' + name + '" is reserved');
+  };
+  /** @type {(name: any, path: string, reserved?: Set<string> | null) => void} */
+  let named = (name, path, reserved) => {
+    if (typeof name !== "string" || !NAME.test(name)) bad(path, "expected an expression name");
+    else checkName(name, path, reserved);
+  };
+  // A required `=expression`: a group's `by`, `where`, a sort key.
+  /** @type {(value: any, path: string) => Eval} */
+  let expression = (value, path) => {
+    if (!isExpr(value) || value.length === 1) {
+      bad(path, "expected an =expression");
+      return NIL;
+    }
+    return attempt(() => prop(value, path), NIL);
+  };
+  // A literal `visible` must be an actual boolean; only expressions may
+  // compute one (the same strictness split as style literals).
+  /** @type {(def: any, path: string) => Eval | null} */
+  let visibleOf = (def, path) => {
+    let value = def.visible;
+    if (value == null) return null;
+    if (typeof value === "boolean" || isExpr(value))
+      return attempt(() => prop(value, path + ".visible"), null);
+    bad(path + ".visible", "expected a boolean or an =expression");
+    return null;
+  };
+  // Page columns: how many vertical strips the declaring node's flow content
+  // is laid out in. Literal only — nothing computes a count — and at least
+  // two, because one column is the absence of the key and two spellings for
+  // one document is spec surface (ADR 0013). `enclosed` says an outer node
+  // already columns this content: nesting is a definition error located here,
+  // on the inner declaration, since the outer one is the valid one.
+  /** @type {(value: any, path: string, enclosed?: boolean) => string | null} */
+  let badColumns = (value, path, enclosed) => {
+    if (enclosed) return "page columns cannot nest in a columned region";
+    if (!Number.isInteger(value) || value < 2) return "expected an integer count (columns >= 2)";
+    return null;
+  };
+  /** @type {(value: any, path: string, enclosed?: boolean) => number | null} */
+  let columnsOf = (value, path, enclosed) => {
+    if (value == null) return null;
+    let problem = badColumns(value, path, enclosed);
+    if (problem) bad(path, problem);
+    return problem ? null : value;
+  };
+  // Literal integer ≥ 1. Omitting the key keeps every row; `take: 0` would be
+  // a second spelling for empty (ADR 0013).
+  /** @type {(value: any, path: string) => number | null} */
+  let takeOf = (value, path) => {
+    if (value == null) return null;
+    if (!Number.isInteger(value) || value < 1) {
+      bad(path, "expected an integer count (take >= 1)");
+      return null;
+    }
+    return value;
+  };
+  // A declared style block resolves to plain data — the closed vocabulary's
+  // names in declaration order, null when empty — and stays data; a render
+  // target maps it to its own formatting model (the HTML target to inline
+  // CSS). An all-literal block folds to one frozen object at compile time.
+  /**
+   * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
+   *   => [string, Eval][]}
+   */
+  let readStyles = (block, path, check) => {
+    /** @type {[string, Eval][]} */
+    let entries = [];
+    for (let [name, value] of Object.entries(block)) {
+      let stylePath = path + "." + name;
+      let problem = check(name, value);
+      if (problem) bad(stylePath, problem);
+      else entries.push([name, attempt(() => prop(value, stylePath), NIL)]);
+    }
+    return entries;
+  };
+  /** @type {(entries: [string, Eval][]) => (scope: Scope) => Scope} */
+  let styleFn = (entries) => (scope) => {
+    /** @type {Scope} */
+    let style = {};
+    for (let [name, value] of entries) style[name] = value(scope);
+    return style;
+  };
+  /** @type {(block: any) => boolean} */
+  let isComputed = (block) => Object.values(block).some(isExpr);
+  /**
+   * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
+   *   => (scope: Scope) => any}
+   */
+  let compileStyles = (block, path, check) => {
+    let entries = readStyles(block, path, check);
+    if (!entries.length) return NIL;
+    let resolve = styleFn(entries);
+    if (isComputed(block)) return resolve;
+    let constant = Object.freeze(resolve({}));
+    return () => constant;
+  };
+  /**
+   * @type {(def: any, path: string, check?: (name: string, value: any) => string | null)
+   *   => (scope: Scope) => any}
+   */
+  let stylesOf = (def, path, check = checkStyle) => {
+    let block = def.style;
+    let stylePath = pathTo(path, "style");
+    if (block == null || !obj(block, stylePath)) return NIL;
+    return compileStyles(block, stylePath, check);
+  };
+  // A cell value: one sjabloon template. Emphasis is the cell's own `style`;
+  // markup in literal text is meaningful only to the HTML target.
+  /** @type {(value: any, path: string) => (scope: Scope, opts?: any) => any} */
+  let cellValue = (value, path) => {
+    if (typeof value === "string") return attempt(() => cell(value, path), EMPTY);
+    bad(path, "expected a template string");
+    return EMPTY;
+  };
+  /** @type {(seen: Set<string> | undefined, name: string, foldPath: string) => void} */
+  let noteRun = (seen, name, foldPath) => {
+    if (!seen) return;
+    if (seen.has(name)) bad(foldPath, 'duplicate run name "' + name + '"');
+    else seen.add(name);
+  };
+  /** @type {(spec: any, foldPath: string, allowed: Set<string>) => Fold | null} */
+  let readFold = (spec, foldPath, allowed) => {
+    if (typeof spec !== "string") {
+      bad(foldPath, "expected a reducer specification");
+      return null;
+    }
+    return attempt(() => parseFold(spec, foldPath, allowed), null);
+  };
+  /** @type {(name: string, spec: any, path: string, allowed: Set<string>, reserved: Set<string> | null, seen?: Set<string>) => [string, Fold] | null} */
+  let oneFold = (name, spec, path, allowed, reserved, seen) => {
+    let foldPath = path + "." + name;
+    named(name, foldPath, reserved);
+    noteRun(seen, name, foldPath);
+    let fold = readFold(spec, foldPath, allowed);
+    return fold && [name, fold];
+  };
+  /**
+   * @type {(value: any, path: string, allowed: Set<string>,
+   *   reserved: Set<string> | null, seen?: Set<string>) => [string, Fold][]}
+   */
+  let readFolds = (value, path, allowed, reserved, seen) => {
+    /** @type {[string, Fold][]} */
+    let out = [];
+    for (let [name, spec] of Object.entries(value)) {
+      let fold = oneFold(name, spec, path, allowed, reserved, seen);
+      if (fold) out.push(fold);
+    }
+    return out;
+  };
+  // Declared aggregates and running values, both spelled "reducer:=expr".
+  /**
+   * @type {(value: any, path: string, allowed: Set<string>,
+   *   reserved: Set<string> | null, seen?: Set<string>) => [string, Fold][]}
+   */
+  let foldsOf = (value, path, allowed, reserved, seen) => {
+    if (value == null || !obj(value, path)) return [];
+    return readFolds(value, path, allowed, reserved, seen);
+  };
+  /** @type {(dir: any, path: string) => void} */
+  let checkDir = (dir, path) => {
+    if (dir == null || dir === "asc" || dir === "desc") return;
+    bad(path, 'unknown sort direction "' + dir + '"');
+  };
+  /** @type {(spec: any, i: number, path: string) => { by: Eval, sign: number }[]} */
+  let sortKey = (spec, i, path) => {
+    let keyPath = path + "[" + i + "]";
+    if (!obj(spec, keyPath)) return [];
+    keys(spec, ["by", "dir"], keyPath);
+    let by = expression(spec.by, keyPath + ".by");
+    checkDir(spec.dir, keyPath + ".dir");
+    return [{ by, sign: spec.dir === "desc" ? -1 : 1 }];
+  };
+  // A sort spec (array of { by, dir }) becomes a comparator over rows.
+  /** @type {(value: any, path: string) => ((rows: any[], scope: Scope) => any[]) | null} */
+  let sortOf = (value, path) => {
+    let specs = arr(value, path);
+    if (!specs || !specs.length) return null;
+    let sortKeys = specs.flatMap((spec, i) => sortKey(spec, i, path));
+    if (!sortKeys.length) return null;
+    let width = sortKeys.length;
+    // Resolve every row's keys once, sort an index array, then materialise.
+    // Still one evaluation per row per key rather than one per comparison,
+    // but the keys live in a single flat row-major array and the rows are
+    // reordered through their indices. Both shapes build a few arrays across
+    // the pass; what this one drops is the per-row wrapper object and key
+    // array, and the scope child it used to build once *per key* per row.
+    return (rows, scope) => {
+      let resolved = [];
+      for (let row of rows) {
+        // One scope child per row: every key of that row reads the same one.
+        let bound = withRow(scope, row);
+        for (let key of sortKeys) resolved.push(key.by(bound));
+      }
+      // `sort` is stable, so a full tie leaves the indices — and with them
+      // the rows — in the order they arrived.
+      let order = Array.from(rows, (_, i) => i);
+      order.sort((a, b) => {
+        let aAt = a * width;
+        let bAt = b * width;
+        for (let i = 0; i < width; i++) {
+          let x = resolved[aAt + i];
+          let y = resolved[bAt + i];
+          if (x < y) return -sortKeys[i].sign;
+          if (x > y) return sortKeys[i].sign;
+        }
+        return 0;
+      });
+      return order.map((i) => rows[i]);
+    };
+  };
+  return {
+    obj,
+    arr,
+    keys,
+    named,
+    expression,
+    visibleOf,
+    columnsOf,
+    takeOf,
+    stylesOf,
+    cellValue,
+    foldsOf,
+    sortOf,
+  };
+};
+
+// --- 4. node compilers ----------------------------------------------------
+//
+// The document's addressable pieces. Each returns a closure that renders one
+// piece of the stream from a scope.
+
+/**
+ * @param {State} state
+ * @param {Readers} readers
+ */
+let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, stylesOf }) => {
+  // `tokens` plus its truthy `style`. A hidden cell keeps its slot with no
+  // tokens so a column keeps its alignment; items pass `visible` null and drop
+  // themselves instead, having no slot to keep. The anchor story lives on
+  // `cell` in primitives: the scope chain itself carries `$` and `@`.
+  /**
+   * @type {(tpl: any, visible: Eval | null, styles: (scope: Scope) => any)
+   *   => (scope: Scope) => any}
+   */
+  let cellShape = (tpl, visible, styles) => (scope) =>
+    opt({ tokens: hidden(visible, scope) ? [] : tpl(scope) }, { style: styles(scope) });
+
+  // A table cell: the shape of a total cell and of an object column header.
+  /** @type {(def: any, path: string, valuePath?: string) => (scope: Scope) => any} */
+  let cellOf = (def, path, valuePath = path + ".value") => {
+    let tpl = cellValue(def.value, valuePath);
+    let visible = visibleOf(def, path);
+    return cellShape(tpl, visible, stylesOf(def, path));
+  };
+
+  // A cell without a row, so `@` stays unbound. A bare string is shorthand for
+  // `{ value }` and keeps its authored path, so problems locate where written.
+  /** @type {(def: any, path: string) => (scope: Scope) => any} */
+  let headerOf = (def, path) => {
+    if (typeof def === "string") return cellShape(cellValue(def, path), null, NIL);
+    if (!record(def)) {
+      bad(path, "expected a template string or object");
+      return cellShape(EMPTY, null, NIL);
+    }
+    keys(def, ["value", "style"], path);
+    return cellOf(def, path);
+  };
+
+  /** @type {(width: any) => boolean} */
+  let validWidth = (width) => typeof width === "number" && width > 0 && width <= 100;
+  /** @type {(width: any, path: string) => any} */
+  let widthOf = (width, path) => {
+    if (width == null || validWidth(width)) return width;
+    bad(path + ".width", "expected a percentage number (0 < width <= 100)");
+    return NaN;
+  };
+  /** @type {(def: any, path: string) => any} */
+  let columnOf = (def, path) => {
+    if (!obj(def, path)) return null;
+    keys(def, ["header", "value", "visible", "style", "width"], path);
+    let header = headerOf(def.header, path + ".header");
+    let tpl = cellValue(def.value, path + ".value");
+    let visible = visibleOf(def, path);
+    let styles = stylesOf(def, path);
+    // A width is a percentage of the table width, resolved by every target.
+    // The range verdict is owned here: an unreadable width comes back as NaN,
+    // so the total check below reads the verdict instead of re-deciding it.
+    return { header, cell: cellShape(tpl, visible, styles), width: widthOf(def.width, path), path };
+  };
+
+  /** @type {(def: any, path: string) => ((scope: Scope) => any) | null} */
+  let totalOf = (def, path) => {
+    if (!obj(def, path)) return null;
+    keys(def, ["value", "visible", "style"], path);
+    return cellOf(def, path);
+  };
+
+  // A text item: a cell with no slot to keep, so a hidden one drops itself
+  // instead of keeping empty tokens the way a table cell does. Inside a split
+  // it is the other way round -- a slot holds its place with empty tokens, so
+  // the line's geometry does not move with the data (SCHEMA.md, "Split item").
+  /** @type {(def: any, path: string, role: string, inSlot?: boolean) => (scope: Scope) => any} */
+  let textOf = (def, path, role, inSlot = false) => {
+    keys(def, inSlot ? TEXT_SLOT_KEYS : TEXT_KEYS, path);
+    checkTextType(def.type, path);
+    let tpl = cellValue(def.value, path + ".value");
+    let visible = visibleOf(def, path);
+    let shape = cellShape(tpl, inSlot ? visible : null, stylesOf(def, path));
+    // The cell shape first, then the item's own fields, so a cell reads
+    // the same wherever it appears in the stream.
+    return (scope) => {
+      if (!inSlot && hidden(visible, scope)) return null;
+      let event = shape(scope);
+      event.type = "item";
+      event.role = role;
+      event.path = path;
+      return event;
+    };
+  };
+
+  // The fallback shape's verdict on a `type` it does not name, reported after
+  // this node's key set and in the documented key order -- and then read as
+  // text, so the rest of its keys are checked rather than left behind the one
+  // problem.
+  /** @type {(type: any, path: string) => void} */
+  let checkTextType = (type, path) => {
+    if (type === "text") return;
+    bad(path + ".type", type == null ? "required" : 'unknown item type "' + type + '"');
+  };
+
+  /** @type {(fit: any, path: string) => void} */
+  let checkFit = (fit, path) => {
+    if (fit == null || fit === "natural" || fit === "width") return;
+    bad(path, 'unknown fit "' + fit + '"');
+  };
+  /** @type {(def: any, path: string) => any} */
+  let altOf = (def, path) => (def.alt != null ? cellValue(def.alt, path + ".alt") : null);
+  /** @type {(alt: any, scope: Scope) => any} */
+  let imageAlt = (alt, scope) => alt && alt(scope);
+  /** @type {(fields: any, scope: Scope, bytes: any) => any} */
+  let imageEvent = (fields, scope, bytes) => {
+    // The bytes stay bytes. Sniffing reads their magic numbers -- it never
+    // decodes the image, and nothing here turns them into a string -- and
+    // the answer rides on the event so no target sniffs a second time.
+    let format = sniff(bytes);
+    // The one place `locate` originates an error instead of re-throwing a
+    // caught one: the fault is quario's own verdict on the bytes, so it
+    // carries the location every other render error does and, having no
+    // engine diagnostic behind it, stays out of `isDiagnostic`.
+    if (!format)
+      locate(
+        fields.path + ".source",
+        fields.sourceSpec,
+        TypeError("expected a Uint8Array of PNG or JPEG bytes"),
+      );
+    return opt(
+      { type: "image", role: fields.role, bytes, format, fit: fields.fit, path: fields.path },
+      { alt: imageAlt(fields.alt, scope), style: fields.styles(scope) },
+    );
+  };
+  /** @type {(fields: any) => (scope: Scope) => any} */
+  let renderImage = (fields) => (scope) => {
+    if (hidden(fields.visible, scope)) return null;
+    let bytes = fields.source(scope);
+    // Nullish is the missing-data twin of `visible: false`: no event and no
+    // error, so a report whose input sometimes lacks a logo needs no guard.
+    if (bytes == null) return null;
+    return imageEvent(fields, scope, bytes);
+  };
+  // An image item: bytes an `=` expression yields, sized by `fit`, with an
+  // optional textual stand-in. JSON has no way to write bytes, so `source` is
+  // expression-only; the vocabulary an image accepts is `style.js`'s to narrow.
+  /** @type {(def: any, path: string, role: string, inSlot?: boolean) => (scope: Scope) => any} */
+  let imageOf = (def, path, role, inSlot = false) => {
+    keys(def, inSlot ? IMAGE_SLOT_KEYS : IMAGE_KEYS, path);
+    let source = expression(def.source, path + ".source");
+    checkFit(def.fit, path + ".fit");
+    // Read in the documented key order, and each read once: `stylesOf` reports
+    // as it reads, so compiling it twice would report this node's style
+    // problems twice, and reading it early would report them out of order.
+    let alt = altOf(def, path);
+    let visible = visibleOf(def, path);
+    let styles = stylesOf(def, path, checkImageStyle);
+    let render = renderImage({
+      source,
+      fit: def.fit ?? "natural",
+      alt,
+      visible,
+      styles,
+      path,
+      sourceSpec: def.source,
+      role,
+    });
+    if (!inSlot) return render;
+    // A slot keeps its place whatever the data does: a hidden image, or a
+    // nullish source, leaves the same empty-token placeholder a hidden text
+    // slot leaves, so the widths either side of it do not move. `cellShape`
+    // with no template is that placeholder, so the two cannot drift.
+    let empty = cellShape(EMPTY, null, styles);
+    return (scope) => render(scope) ?? { ...empty(scope), type: "item", role };
+  };
+
+  // One slot of a split: an ordinary item, plus the width share that is a slot
+  // property rather than an item one -- which is why `width` reaches an item's
+  // key set only here (docs/adr/0029).
+  /**
+   * @type {(def: any, path: string, role: string)
+   *   => { render: (scope: Scope) => any, width: any } | null}
+   */
+  let slotOf = (def, path, role) => {
+    if (!obj(def, path)) return null;
+    // Placement inside placement is the coordinate system quario does not
+    // have, so the nesting verdict is named rather than left to read as an
+    // unknown item type.
+    if (def.type === "split") {
+      bad(path + ".type", "a split cannot nest");
+      return null;
+    }
+    return {
+      render: (def.type === "image" ? imageOf : textOf)(def, path, role, true),
+      width: widthOf(def.width, path),
+    };
+  };
+
+  // A split: slots placed across the content width, bracketed in the stream so
+  // every slot crosses as the ordinary item or image event it already is.
+  /** @type {(def: any, path: string, role: string) => (scope: Scope) => any} */
+  let splitOf = (def, path, role) => {
+    keys(def, ["type", "slots", "visible", "style"], path);
+    let list = arr(def.slots, path + ".slots", true);
+    let defs = list || [];
+    // Two is the floor: a one-slot split is a text item wearing more syntax,
+    // and permitting it would be a second way to say one thing. Read off the
+    // array `arr` accepted, so a missing `slots` reports "required" once
+    // rather than that and this.
+    if (list && defs.length < 2) bad(path + ".slots", "expected at least two slots");
+    let slots = defs
+      .map((slot, i) => slotOf(slot, path + ".slots[" + i + "]", role))
+      .filter((slot) => slot != null);
+    checkShares(bad, slots, path + ".slots", "slot");
+    let visible = visibleOf(def, path);
+    let styles = stylesOf(def, path);
+    // Every width is a literal the traversal already resolved, so the geometry
+    // the bracket carries is the same array on every render -- built here
+    // rather than rebuilt per row in a detail band. Frozen because one array
+    // now reaches every render: a consumer must not be able to reach back
+    // through an event and change what a later render sees.
+    let geometry = Object.freeze(
+      slots.map((slot) => Object.freeze(opt({}, { width: slot.width }))),
+    );
+    return (scope) => {
+      if (hidden(visible, scope)) return null;
+      let out = [opt({ type: "split-start", role, slots: geometry }, { style: styles(scope) })];
+      for (let slot of slots) out.push(slot.render(scope));
+      out.push({ type: "split-end" });
+      return out;
+    };
+  };
+
+  /** @type {(def: any, itemPath: string, role: string) => ((scope: Scope) => any) | null} */
+  let itemOf = (def, itemPath, role) => {
+    if (!obj(def, itemPath)) return null;
+    // `type` picks the item's shape; `textOf` owns the verdict on the ones
+    // it does not name, having the closed key set that reports first.
+    if (def.type === "split") return splitOf(def, itemPath, role);
+    return (def.type === "image" ? imageOf : textOf)(def, itemPath, role);
+  };
+  /** @type {(list: ((scope: Scope) => any)[]) => (scope: Scope) => Generator<any>} */
+  let yieldItems = (list) =>
+    function* (scope) {
+      for (let render of list) {
+        let event = render(scope);
+        // A split renders to its whole bracket; every other item to one event.
+        if (Array.isArray(event)) yield* event;
+        else if (event) yield event;
+      }
+    };
+
+  // `role` (`detail`, `group-header`, ...) becomes the HTML target's stable
+  // `q-<role>` class, which print CSS targets for styling and breaks.
+  /**
+   * @type {(value: any, path: string, role: string)
+   *   => (scope: Scope) => Generator<any>}
+   */
+  let itemsOf = (value, path, role) => {
+    /** @type {((scope: Scope) => any)[]} */
+    let list = [];
+    for (let [i, def] of (arr(value, path) || []).entries()) {
+      let render = itemOf(def, path + "[" + i + "]", role);
+      if (render) list.push(render);
+    }
+    return yieldItems(list);
+  };
+
+  return { columnOf, itemsOf, totalOf };
+};
+
+// --- 5. band generators ---------------------------------------------------
+//
+// The generators a report is a stack of: the detail band at the leaf, and the
+// group chain that partitions rows around it.
+
+/**
+ * @param {State} state
+ * @param {Readers} readers
+ * @param {Nodes} nodes
+ */
+let bands = (
+  { bad, runNames },
+  { arr, obj, keys, named, expression, visibleOf, columnsOf, takeOf, stylesOf, foldsOf, sortOf },
+  { columnOf, itemsOf, totalOf },
+) => {
+  // Stacked items, one pass per row.
+  /** @type {(items: (scope: Scope) => Generator<any>) => Band} */
+  let itemsBand = (items) =>
+    function* (rows, scope, runners) {
+      for (let row of rows) {
+        let scopeOfRow = runners.bind(scope, row);
+        // Detail items carry the row's run values as data; group and report
+        // band items never do (they have no current row).
+        for (let event of items(scopeOfRow))
+          yield carriesRun(event) ? opt(event, { run: scopeOfRow.run }) : event;
+      }
+    };
+
+  /** @type {(value: any) => { rowVisible: Eval | null, rowStyles: (scope: Scope) => any }} */
+  let rowLook = (value) => {
+    if (value.row == null || !obj(value.row, "detail.row"))
+      return { rowVisible: null, rowStyles: NIL };
+    keys(value.row, ["visible", "style"], "detail.row");
+    return {
+      rowVisible: visibleOf(value.row, "detail.row"),
+      rowStyles: stylesOf(value.row, "detail.row"),
+    };
+  };
+  /** @type {(value: any) => { defs: any[] | null, columns: any[] }} */
+  let tableColumns = (value) => {
+    let defs = arr(value.columns, "detail.columns", true);
+    if (defs && !defs.length) bad("detail.columns", "expected at least one column");
+    let columns = (defs || [])
+      .map((def, i) => columnOf(def, "detail.columns[" + i + "]"))
+      .filter((column) => column != null);
+    checkShares(bad, columns, "detail.columns", "column");
+    return { defs, columns };
+  };
+  /** @type {(totals: any[] | null, defs: any[] | null) => void} */
+  let checkTotalCount = (totals, defs) => {
+    if (totals && defs && totals.length !== defs.length)
+      bad("detail.total", "expected one cell per column");
+  };
+  /** @type {(totals: any[]) => any[]} */
+  let mapTotals = (totals) =>
+    totals
+      .map((def, i) => {
+        let cell = totalOf(def, "detail.total[" + i + "]");
+        return cell && { cell, path: "detail.total[" + i + "]" };
+      })
+      .filter((entry) => entry != null);
+  /** @type {(value: any, defs: any[] | null) => any[] | null} */
+  let tableTotals = (value, defs) => {
+    let totals = arr(value.total, "detail.total");
+    checkTotalCount(totals, defs);
+    return totals ? mapTotals(totals) : null;
+  };
+  /**
+   * @type {(rows: any[], scope: Scope, runners: RunnerSet, columns: any[],
+   *   rowVisible: Eval | null, rowStyles: (scope: Scope) => any) => Generator<any>}
+   */
+  function* tableRows(rows, scope, runners, columns, rowVisible, rowStyles) {
+    for (let row of rows) {
+      let scopeOfRow = runners.bind(scope, row);
+      if (!hidden(rowVisible, scopeOfRow))
+        yield opt(
+          {
+            type: "row",
+            cells: columns.map((column) =>
+              Object.assign(column.cell(scopeOfRow), { path: column.path }),
+            ),
+          },
+          { style: rowStyles(scopeOfRow), run: scopeOfRow.run },
+        );
+    }
+  }
+  /** @type {(columns: any[], total: any[] | null, rowVisible: Eval | null, rowStyles: (scope: Scope) => any) => Band} */
+  let tableBand = (columns, total, rowVisible, rowStyles) =>
+    function* (rows, scope, runners) {
+      yield {
+        type: "table-start",
+        path: "detail",
+        columns: columns.map((column) =>
+          opt({ header: column.header(scope), path: column.path }, { width: column.width }),
+        ),
+      };
+      yield* tableRows(rows, scope, runners, columns, rowVisible, rowStyles);
+      if (total)
+        yield {
+          type: "total-row",
+          cells: total.map(({ cell, path }) => Object.assign(cell(scope), { path })),
+        };
+      yield { type: "table-end" };
+    };
+  /** @type {(value: any) => Band} */
+  let tableOf = (value) => {
+    keys(value, ["row", "columns", "total"], "detail");
+    let { rowVisible, rowStyles } = rowLook(value);
+    let { defs, columns } = tableColumns(value);
+    return tableBand(columns, tableTotals(value, defs), rowVisible, rowStyles);
+  };
+
+  // The detail band is polymorphic: an array of items stacks them per row, a
+  // `{ columns, total }` object is a real table.
+  /** @type {(value: any) => Band} */
+  let detailOf = (value) => {
+    if (Array.isArray(value) || value == null) return itemsBand(itemsOf(value, "detail", "detail"));
+    if (!record(value)) {
+      bad("detail", "expected an array of items or a table object");
+      return itemsBand(itemsOf(null, "detail", "detail"));
+    }
+    return tableOf(value);
+  };
+  // Group names are unique across the whole report, so the register outlives
+  // any one call of the recursion below.
+  /** @type {Set<string>} */
+  let groupNames = new Set();
+
+  /** @type {(name: any, path: string) => void} */
+  let noteGroup = (name, path) => {
+    if (typeof name !== "string") return;
+    if (groupNames.has(name)) bad(path, 'duplicate group name "' + name + '"');
+    else groupNames.add(name);
+  };
+  /** @type {(value: any, path: string, kind: string) => void} */
+  let checkHint = (value, path, kind) => {
+    if (value == null || value === "page") return;
+    bad(path, "unknown " + kind + ' "' + value + '"');
+  };
+  /** @type {(aggs: [string, Fold][], rows: any[], scope: Scope, handle: Scope) => Scope} */
+  let applyAggs = (aggs, rows, scope, handle) => {
+    /** @type {Scope} */
+    let aggregates = {};
+    for (let [aggName, fold] of aggs)
+      aggregates[aggName] = handle[aggName] = aggregateValue(fold, rows, scope);
+    return aggregates;
+  };
+  // Without `take`, aggregates fold over the whole partition before its rows
+  // are ordered, so a group sort key may read the handle. With `take`, the
+  // rank filter has to run first — sort then slice — and aggregates fold over
+  // what remains, so a sort key that reads this group's own aggregates is
+  // null, the same rule a report sort already has. The handle is bound after
+  // applyAggs when there is no take, so a sibling aggregate still throws.
+  /** @type {(ctx: any, key: any, groupRows: any[], scope: Scope) => any} */
+  let openInstance = (ctx, key, groupRows, scope) => {
+    let groupScope = Object.create(scope);
+    /** @type {Scope} */
+    let handle = { key };
+    if (ctx.take == null) {
+      let aggregates = applyAggs(ctx.aggs, groupRows, groupScope, handle);
+      groupScope[ctx.name] = handle;
+      return {
+        groupScope,
+        aggregates,
+        rows: ctx.sort ? ctx.sort(groupRows, groupScope) : groupRows,
+      };
+    }
+    groupScope[ctx.name] = handle;
+    let rows = (ctx.sort ? ctx.sort(groupRows, groupScope) : groupRows).slice(0, ctx.take);
+    return { groupScope, aggregates: applyAggs(ctx.aggs, rows, groupScope, handle), rows };
+  };
+  /** @type {(ctx: any) => Band} */
+  let groupWalk = (ctx) =>
+    function* (rows, scope, runners) {
+      let parts = Map.groupBy(rows, (row) => ctx.by(withRow(scope, row)));
+      for (let [key, groupRows] of parts) {
+        // A group band has no current row, so `@` stays unbound here.
+        let { groupScope, aggregates, rows: ordered } = openInstance(ctx, key, groupRows, scope);
+        yield opt(
+          {
+            type: "group-start",
+            name: ctx.name,
+            depth: ctx.index,
+            key,
+            aggregates,
+            path: ctx.path,
+          },
+          { break: ctx.pageBreak, reset: ctx.reset, columns: ctx.columns },
+        );
+        yield* ctx.header(groupScope);
+        yield* ctx.inner(ordered, groupScope, runners.extend(ctx.running));
+        yield* ctx.footer(groupScope);
+        yield { type: "group-end", name: ctx.name, depth: ctx.index };
+      }
+    };
+  /** @type {(def: any, path: string, defs: any[], index: number, detail: any, columned?: boolean) => Band} */
+  let compileGroup = (def, path, defs, index, detail, columned) => {
+    keys(
+      def,
+      [
+        "name",
+        "by",
+        "break",
+        "reset",
+        "columns",
+        "sort",
+        "take",
+        "aggregates",
+        "run",
+        "header",
+        "footer",
+      ],
+      path,
+    );
+    named(def.name, path + ".name", RESERVED);
+    noteGroup(def.name, path + ".name");
+    let by = expression(def.by, path + ".by");
+    checkHint(def.break, path + ".break", "break");
+    checkHint(def.reset, path + ".reset", "reset");
+    let columns = columnsOf(def.columns, path + ".columns", columned);
+    return groupWalk({
+      by,
+      sort: sortOf(def.sort, path + ".sort"),
+      take: takeOf(def.take, path + ".take"),
+      aggs: foldsOf(def.aggregates, path + ".aggregates", AGG, new Set(["key"])),
+      running: foldsOf(def.run, path + ".run", RUN, null, runNames),
+      header: itemsOf(def.header, path + ".header", "group-header"),
+      footer: itemsOf(def.footer, path + ".footer", "group-footer"),
+      inner: bandOf(defs, index + 1, detail, columned || columns != null),
+      name: def.name,
+      path,
+      pageBreak: def.break,
+      reset: def.reset,
+      columns,
+      index,
+    });
+  };
+
+  // The band chain, outermost group first: each group partitions its rows and
+  // recurses; the detail band sits at the leaf.
+  /** @type {(defs: any[], index: number, detail: any, columned?: boolean) => Band} */
+  let bandOf = (defs, index, detail, columned) => {
+    if (index >= defs.length) return detailOf(detail);
+    let path = "groups[" + index + "]";
+    let def = defs[index];
+    if (!obj(def, path)) return bandOf(defs, index + 1, detail, columned);
+    return compileGroup(def, path, defs, index, detail, columned);
+  };
+
+  return { bandOf };
+};
+
+// --- 6. the traversal -----------------------------------------------------
+
+/** @type {(source: string, options: any) => any} */
+let compileQuery = (source, options) => {
+  try {
+    // padvinder itself defaults maxDepth to 500 (safety by construction since
+    // 0.6.0), so untrusted deep documents throw typed with no quario-side
+    // budget; hosts override per key — Infinity opts a budget out.
+    return query(source, undefined, options && options.query);
+  } catch (error) {
+    locate("data", source, error, isQueryDiagnostic(error) && relocateQuery);
+  }
+};
+/** @type {(schema: any, obj: any, named: any, bad: any) => any} */
+let paramsOf = (schema, obj, named, bad) => {
+  if (schema.params == null || !obj(schema.params, "params")) return NONE;
+  for (let name of Object.keys(schema.params)) named(name, "params." + name);
+  return jsonCopy(schema.params, "params", bad, new Set());
+};
+/** @type {(schema: any, bad: any, attempt: any, options: any) => any} */
+let selectOf = (schema, bad, attempt, options) => {
+  if (typeof schema.data !== "string") {
+    bad("data", "expected a JSONPath string");
+    return null;
+  }
+  return attempt(() => compileQuery(schema.data, options), null);
+};
+/** @type {(value: any, path: string, expression: any) => any} */
+let maybeExpr = (value, path, expression) => (value != null ? expression(value, path) : null);
+/** @type {(schema: any, obj: any, keys: any, itemsOf: any) => { pageHeader: any, pageFooter: any }} */
+let pageBands = (schema, obj, keys, itemsOf) => {
+  if (schema.page == null || !obj(schema.page, "page"))
+    return { pageHeader: null, pageFooter: null };
+  keys(schema.page, ["header", "footer"], "page");
+  return {
+    pageHeader: maybeItems(schema.page.header, "page.header", "page-header", itemsOf),
+    pageFooter: maybeItems(schema.page.footer, "page.footer", "page-footer", itemsOf),
+  };
+};
+
+/**
+ * The root descent, in the schema's documented key order. `params` and `data`
+ * are checked here the way every other key is — by compiling what they declare
+ * — so the frozen params copy and the compiled query runner come back with the
+ * band closures instead of being made a second time at render.
+ *
+ * @param {State} state
+ * @param {Readers} readers
+ * @param {Nodes} nodes
+ * @param {Bands} bands
+ * @param {any} schema The report document.
+ * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number}}} [options]
+ *   Host controls. The query budgets are per-execution, so they change what a
+ *   render may traverse, never what this descent reports.
+ */
+let traverse = (
+  { add, bad, attempt, runNames },
+  { arr, obj, keys, named, expression, columnsOf, takeOf, foldsOf, sortOf, stylesOf },
+  { itemsOf },
+  { bandOf },
+  schema,
+  options,
+) => {
+  if (!record(schema)) {
+    add("schema: expected an object");
+    return null;
+  }
+  keys(
+    schema,
+    [
+      "params",
+      "data",
+      "where",
+      "sort",
+      "take",
+      "aggregates",
+      "run",
+      "style",
+      "header",
+      "empty",
+      "columns",
+      "groups",
+      "detail",
+      "footer",
+      "page",
+    ],
+    "",
+  );
+  // Frozen either way, so `$.params` reads the same whether or not a report
+  // declares any. A count here columns every group inside it, so the band
+  // chain below carries the verdict down as `enclosed`.
+  let params = paramsOf(schema, obj, named, bad);
+  let select = selectOf(schema, bad, attempt, options);
+  let where = maybeExpr(schema.where, "where", expression);
+  let sort = sortOf(schema.sort, "sort");
+  let take = takeOf(schema.take, "take");
+  let aggs = foldsOf(schema.aggregates, "aggregates", AGG, new Set(["params", "input"]));
+  let running = foldsOf(schema.run, "run", RUN, null, runNames);
+  // The report default: one style block for the whole document, narrowed to
+  // the declarations a typeface is made of. It resolves once per render in
+  // report scope rather than per node, which is why it crosses the seam as a
+  // `report-start` field instead of being merged into every item's style --
+  // nothing here allocates per cell (docs/adr/0033).
+  let style = stylesOf(schema, "", checkReportStyle);
+  let header = itemsOf(schema.header, "header", "report-header");
+  // Null when undeclared, so the render decides on the compiled band rather
+  // than reading `schema.empty` a second time from outside the traversal.
+  let empty = maybeItems(schema.empty, "empty", "empty", itemsOf);
+  let columns = columnsOf(schema.columns, "columns");
+  let band = bandOf(arr(schema.groups, "groups") || [], 0, schema.detail, columns != null);
+  let footer = itemsOf(schema.footer, "footer", "report-footer");
+  // Page bands compile like any other band, but render per page, so the
+  // stream hands paginated targets closures instead of events.
+  let { pageHeader, pageFooter } = pageBands(schema, obj, keys, itemsOf);
+  return {
+    select,
+    params,
+    where,
+    sort,
+    take,
+    aggs,
+    running,
+    style,
+    header,
+    empty,
+    columns,
+    footer,
+    band,
+    pageHeader,
+    pageFooter,
+  };
+};
+
+/**
+ * One compilation of one report definition: the six layers above, composed.
+ * Each takes the state and the layers it builds on, so what a layer reads is
+ * visible in its signature.
+ *
+ * @param {any} schema The report document.
+ * @param {Record<string, Function>} [funcs] Functions callable from expressions.
+ * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number}}} [options]
+ *   Host controls, for the one key that has any: the data query's budgets.
+ */
+export let plan = (schema, funcs, options) => {
+  let state = planState(schema, funcs);
+  let prim = primitives(state);
+  let read = readers(state, prim);
+  let node = nodes(state, read);
+  let band = bands(state, read, node);
+  return {
+    compiled: traverse(state, read, node, band, schema, options),
+    problems: state.problems,
+    anchors: state.anchors,
+    names: state.names,
+    // Registry metadata comes from xprsn's one signature convention, described
+    // over just the called subset — every called name resolved from the
+    // registry at compile time, and the rebuilt object keeps the flat name
+    // set's call-first-seen order.
+    functions: signatures(
+      Object.fromEntries(Array.from(state.functions, (name) => [name, state.FNS[name]])),
+    ),
+    diagnostic: state.diagnostic,
+  };
+};