quario 0.1.0 → 0.3.0

package/lib/index.js

@@ -12,8 +12,9 @@
  * definition lives in `./plan.js`; what the two of them share lives in the
  * siblings beside it, one seam each. See SCHEMA.md for the document shape.
  */
+import { relocate as relocateQuery } from "padvinder";
 import { MARKING, verify } from "./license.js";
-import { err, locate } from "./locate.js";
+import { err, fault, locate } from "./locate.js";
 import { BLOCKED, NAME, record } from "./names.js";
 import { plan } from "./plan.js";
 import { aggregateValue, startRunners, withPage, withRow } from "./scope.js";
@@ -22,30 +23,25 @@ import { opt } from "./stream.js";
 // The event stream's public seam, single-sourced in ./stream.js, and the
 // diagnostic predicate in ./locate.js. Re-exported here because a consumer
 // imports them from the package, not from a file inside it.
-export { breathe, isReportBand, text, typed, walk } from "./stream.js";
+export { breathe, display, isReportBand, text, typed, walk } from "./stream.js";
+export { format } from "./format.js";
 export { isDiagnostic } from "./locate.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */
 
 /** @type {(data: any) => any} */
 let inputOf = (data) => data ?? {};
-/** @type {(rows: any[], where: any, base: any) => any[]} */
-let filterRows = (rows, where, base) =>
-  where ? rows.filter((row) => where(withRow(base, row))) : rows;
-/** @type {(rows: any[], sort: any, base: any) => any[]} */
-let sortRows = (rows, sort, base) => (sort ? sort(rows, base) : rows);
-/** @type {(rows: any[], n: number | null) => any[]} */
-let takeRows = (rows, n) => (n == null ? rows : rows.slice(0, n));
-/** @type {(aggs: any, rows: any[], base: any) => Scope} */
-let foldAggs = (aggs, rows, base) => {
+// Every aggregate is computed before any is injected, so results never depend
+// on declaration order; a sibling read inside an aggregate expression is always
+// the pre-injection null (see SCHEMA.md, deliberate asymmetries). Hence the two
+// passes: one to fold, one to write the values onto the report root.
+/** @type {(aggs: any, rows: any[], base: any, root: any) => Scope} */
+let foldAggs = (aggs, rows, base, root) => {
   /** @type {Scope} */
   let aggregates = {};
   for (let [name, fold] of aggs) aggregates[name] = aggregateValue(fold, rows, base);
-  return aggregates;
-};
-/** @type {(root: any, aggregates: Scope, aggs: any) => void} */
-let injectAggs = (root, aggregates, aggs) => {
   for (let [name] of aggs) root[name] = aggregates[name];
+  return aggregates;
 };
 /** @type {(band: any, perPage: (items: any) => any) => any} */
 let maybePage = (band, perPage) => band && perPage(band);
@@ -58,23 +54,6 @@ let pageOf = (pageHeader, pageFooter, perPage) => {
   );
 };
 
-/**
- * @type {(parts: any, ctx: any) => Generator<object, void, undefined>}
- */
-function* reportEvents(parts, ctx) {
-  let { header, empty, band, footer, marking, columns } = parts;
-  let { root, aggregates, page, rows, base, runners } = ctx;
-  yield opt(
-    { type: "report-start", params: root.params, aggregates },
-    { page, columns, marking: marking() },
-  );
-  yield* header(base);
-  if (!rows.length && empty) yield* empty(base);
-  else yield* band(rows, base, runners);
-  yield* footer(base);
-  yield { type: "report-end" };
-}
-
 /** @type {(name: any) => void} */
 let checkTargetName = (name) => {
   if (typeof name !== "string" || !NAME.test(name) || BLOCKED.has(name))
@@ -105,9 +84,23 @@ let runTarget = (compile, stream, data) => {
  * @returns {string[]} All definition problems, in document order.
  */
 export function validate(schema, funcs) {
-  return plan(schema, funcs).problems;
+  return plan(schema, funcs).problems.map((problem) => problem.message);
 }
 
+// The structured problems, frozen for handing out: the traversal's own objects
+// go to exactly one caller, so freezing here cannot disturb a second reader.
+// The diagnostic stays an engine-minted error and is deliberately not frozen.
+/** @type {(problems: any[]) => readonly any[]} */
+let freezeProblems = (problems) => Object.freeze(problems.map((problem) => Object.freeze(problem)));
+
+// The per-node anchor sets, as frozen host data (CONTEXT.md, "Freeze"): which
+// anchors and group handles each compiled source reads, keyed by schema path.
+/** @type {(anchors: Map<string, Set<string>>) => any} */
+let freezeAnchors = (anchors) =>
+  Object.freeze(
+    Object.fromEntries(Array.from(anchors, ([path, set]) => [path, Object.freeze([...set])])),
+  );
+
 /**
  * Compile a report once, stream structured render events against data many times.
  *
@@ -125,13 +118,58 @@ export function validate(schema, funcs) {
  *   wording, or false when the render is covered. A thunk, so what it answers
  *   is this render's answer and not the compile's.
  * @returns {{(data?: any): Generator<object, void, undefined>, names: string[],
- *   functions: string[], paths: readonly any[]}} Event stream factory.
+ *   functions: { name: string, arity: number, doc?: string }[],
+ *   paths: readonly any[]}} Event stream factory.
  */
 function events(schema, funcs, options, marking) {
   // The traversal collects every problem, so a thrown error is the first of the
   // same list `validate()` would return.
   let planned = plan(schema, funcs, options);
-  if (planned.problems.length) throw planned.diagnostic() || SyntaxError(planned.problems[0]);
+  if (planned.problems.length)
+    throw planned.diagnostic() || SyntaxError(planned.problems[0].message);
+  return assemble(planned, schema, marking, options);
+}
+
+/** @type {(event: any) => boolean} */
+let occupying = (event) =>
+  event.type === "item" || event.type === "image" || event.type === "split-start";
+/** @type {(n: any) => boolean} */
+let nonzeroLead = (n) => Number.isFinite(n) && n !== 0;
+/** @type {(event: any) => string} */
+let eventPath = (event) => event.path || "header";
+/** @type {(event: any) => void} */
+let refuseLead = (event) => {
+  if (nonzeroLead(event.style?.spaceBefore))
+    fault(eventPath(event) + ".style.spaceBefore", "must be 0 after a height-declared header");
+};
+/** @type {(events: Iterable<any>) => Generator<any>} */
+function* guardPin(events) {
+  let pending = true;
+  for (let event of events) {
+    if (pending && occupying(event)) {
+      pending = false;
+      refuseLead(event);
+    }
+    yield event;
+  }
+}
+
+/**
+ * Build the event stream factory from a settled traversal — the half of the
+ * one compile that runs only when the plan carried no problems, shared by
+ * `report()`'s throwing path and the instance's `plan()`.
+ *
+ * @param {ReturnType<typeof plan>} planned The finished traversal.
+ * @param {any} schema The report document, for locating `data` faults.
+ * @param {() => string | false} marking This render's unlicensed marking.
+ * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
+ *   locale?: string, currency?: string, timeZone?: string} | undefined} options
+ *   Host controls closed over this compile.
+ * @returns {{(data?: any): Generator<object, void, undefined>, names: string[],
+ *   functions: { name: string, arity: number, doc?: string }[],
+ *   paths: readonly any[]}} Event stream factory.
+ */
+function assemble(planned, schema, marking, options) {
   // Null only for a non-object schema, which is itself a collected problem.
   // `select` and `params` come from the traversal too: it checked them, so
   // nothing here compiles or clones a second time.
@@ -143,6 +181,7 @@ function events(schema, funcs, options, marking) {
     take,
     aggs,
     running,
+    style,
     header,
     empty,
     columns,
@@ -150,6 +189,8 @@ function events(schema, funcs, options, marking) {
     band,
     pageHeader,
     pageFooter,
+    headerHeight,
+    margin,
   } = /** @type {NonNullable<typeof planned.compiled>} */ (planned.compiled);
 
   // The runner's own faults are located per render: a budget is spent while
@@ -159,7 +200,7 @@ function events(schema, funcs, options, marking) {
     try {
       return select(data);
     } catch (error) {
-      locate("data", schema.data, error, 0, select.isDiagnostic(error));
+      locate("data", schema.data, error, select.isDiagnostic(error) && relocateQuery);
     }
   };
 
@@ -174,12 +215,11 @@ function events(schema, funcs, options, marking) {
     // aggregates (over the rows that remain). It cannot be lazy because the
     // report header may interpolate report aggregates; only the banded walk
     // itself streams.
-    let rows = takeRows(sortRows(filterRows(runSelect(root.input), where, base), sort, base), take);
-    // Aggregates compute first and inject after, so results never depend on
-    // declaration order; a sibling read inside an aggregate expression is
-    // always the pre-injection null (see SCHEMA.md, deliberate asymmetries).
-    let aggregates = foldAggs(aggs, rows, base);
-    injectAggs(root, aggregates, aggs);
+    let rows = runSelect(root.input);
+    if (where) rows = rows.filter((row) => where(withRow(base, row)));
+    if (sort) rows = sort(rows, base);
+    if (take != null) rows = rows.slice(0, take);
+    let aggregates = foldAggs(aggs, rows, base, root);
     // The report's runners, started per render like everything else here.
     let runners = startRunners(running);
     // Per-render page band closures: a paginated target calls them once per
@@ -188,18 +228,44 @@ function events(schema, funcs, options, marking) {
     /** @type {(items: any) => (page: any) => any[]} */
     let perPage = (items) => (page) => [...items(withPage(base, page))];
     let page = pageOf(pageHeader, pageFooter, perPage);
-    // The marking rides on the opening event — its wording, so that a target
-    // owns only where it goes. Read here, as the event is yielded, so a
-    // render drained before verification settles counts as unlicensed
-    // (SCHEMA.md, "License keys").
-    return reportEvents(
-      { header, empty, band, footer, marking, columns },
-      { root, aggregates, page, rows, base, runners },
-    );
+    // The banded walk itself, over everything the pre-pass settled above. The
+    // marking rides on the opening event — its wording, so that a target owns
+    // only where it goes. Read as the event is yielded, so a render drained
+    // before verification settles counts as unlicensed (SCHEMA.md, "License
+    // keys").
+    /** @type {(options: any) => { locale?: string, currency?: string, timeZone?: string }} */
+    let intlOf = (host) => ({
+      locale: host?.locale,
+      currency: host?.currency,
+      timeZone: host?.timeZone,
+    });
+    /** @type {() => Generator<object, void, undefined>} */
+    function* walked() {
+      yield opt(
+        { type: "report-start", params: root.params, aggregates },
+        {
+          page,
+          columns,
+          style: style(base),
+          marking: marking(),
+          ...intlOf(options),
+          margin,
+          headerHeight,
+        },
+      );
+      yield* header(base);
+      let body = !rows.length && empty ? empty(base) : band(rows, base, runners);
+      yield* headerHeight != null ? guardPin(body) : body;
+      yield* footer(base);
+      yield { type: "report-end" };
+    }
+    return walked();
   };
   return Object.assign(emit, {
     names: Array.from(planned.names),
-    functions: Array.from(planned.functions),
+    // Already signature objects — plan() paired each called name with its
+    // registry metadata through xprsn's signatures().
+    functions: planned.functions,
     paths: select.paths,
   });
 }
@@ -214,34 +280,56 @@ function events(schema, funcs, options, marking) {
  * ("Instances and targets").
  *
  * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
- *   license?: string, trust?: {publicKey?: string, release?: string}}} [options]
+ *   license?: string, trust?: {publicKey?: string, release?: string},
+ *   locale?: string, currency?: string, timeZone?: string}} [options]
  *   Host configuration. `trust` is internal, not API — see ./license.js.
+ *   `locale` / `currency` / `timeZone` present `format` (docs/adr/0041).
  * @returns {{license: Promise<LicenseInfo>,
- *   report: (schema: any, funcs?: Record<string, Function>) => any}} The instance.
+ *   report: (schema: any, funcs?: Record<string, Function>) => any,
+ *   plan: (schema: any, funcs?: Record<string, Function>) => any}} The instance.
  */
 export function quario(options) {
   let { licensed, settled } = verify(options?.license, options?.trust);
+  // The wording is the instance's, where the key is; the stream is what
+  // states it, so nothing wraps a compiled stream to reach its first event.
+  /** @type {() => string | false} */
+  let marking = () => !licensed() && MARKING;
+  // The compiled report around a stream: what `report()` returns, and what
+  // `plan()` carries when the document had no problems.
+  /** @type {(stream: ReturnType<typeof events>) => any} */
+  let wrap = (stream) => ({
+    stream,
+    names: stream.names,
+    functions: stream.functions,
+    paths: stream.paths,
+    // Every render awaits verification before the target pulls its first
+    // event, so no render is marked merely for racing the check and no
+    // target carries that concern itself. Target shape problems throw
+    // synchronously — definition errors, like everything else — while a
+    // render is always a promise, even over a synchronous renderer.
+    render: (/** @type {any} */ target, /** @type {any} */ data) => {
+      checkTarget(target);
+      return settled.then(() => runTarget(target.compile, stream, data));
+    },
+  });
   return {
     license: settled,
     /** @type {(schema: any, funcs?: Record<string, Function>) => any} */
     report(schema, funcs) {
-      // The wording is the instance's, where the key is; the stream is what
-      // states it, so nothing wraps a compiled stream to reach its first event.
-      let stream = events(schema, funcs, options, () => !licensed() && MARKING);
+      return wrap(events(schema, funcs, options, marking));
+    },
+    // The plan (CONTEXT.md): both readings of the one descent, kept.
+    // `report()` and `validate()` name what a caller wanted from it; this
+    // hands over the whole thing — the compiled report (null while the
+    // document has problems), every problem structurally, and the per-node
+    // anchor sets — so an editing host pays one traversal per edit, not two.
+    /** @type {(schema: any, funcs?: Record<string, Function>) => any} */
+    plan(schema, funcs) {
+      let planned = plan(schema, funcs, options);
       return {
-        stream,
-        names: stream.names,
-        functions: stream.functions,
-        paths: stream.paths,
-        // Every render awaits verification before the target pulls its first
-        // event, so no render is marked merely for racing the check and no
-        // target carries that concern itself. Target shape problems throw
-        // synchronously — definition errors, like everything else — while a
-        // render is always a promise, even over a synchronous renderer.
-        render: (/** @type {any} */ target, /** @type {any} */ data) => {
-          checkTarget(target);
-          return settled.then(() => runTarget(target.compile, stream, data));
-        },
+        report: planned.problems.length ? null : wrap(assemble(planned, schema, marking, options)),
+        problems: freezeProblems(planned.problems),
+        anchors: freezeAnchors(planned.anchors),
       };
     },
   };

package/lib/license.js

@@ -11,7 +11,7 @@
 // reassigns them. A key is valid for every version released inside its window
 // (LICENSE section 7), so validity compares ISO date strings and never reads
 // a clock — accepted output stays accepted.
-let RELEASE = "2026-08-27"; // x-release-please-date
+let RELEASE = "2026-09-02"; // x-release-please-date
 // The verifying half of the signing pair: the 65-byte uncompressed P-256
 // point, base64url. The private half never enters the repo;
 // scripts/license/sign.mjs mints keys against it.

package/lib/locate.js

@@ -1,36 +1,25 @@
 /**
  * Located diagnostics: where quario re-throws an engine's error with the
- * band/item path and offending source attached, and the register that keeps
- * the copy authenticated.
+ * band/item path and offending source attached.
  */
 import { isDiagnostic as isQueryDiagnostic } from "padvinder";
 import { isDiagnostic as isXprsnDiagnostic } from "xprsn";
 import { isDiagnostic as isTemplateDiagnostic } from "sjabloon";
 
-// The engines authenticate their diagnostics by identity (WeakMap/WeakSet), so
-// the located copies `locate()` re-throws can't pass the upstream guards.
-// quario registers each copy it makes from an authenticated original here,
-// giving located diagnostics the same identity-based authentication.
-/** @type {WeakSet<any>} */
-let DIAG = new WeakSet();
-
 /**
- * True when an error is one of the stack's authenticated located diagnostics —
- * thrown by quario with an engine (xprsn, sjabloon, or padvinder) original
- * behind it, or by an engine directly — i.e. it safely carries the optional
- * `code`/`start`/`end`/`limit`/`actual`/`blocks` metadata. Authentication is
- * by identity: an error merely shaped like a diagnostic does not pass.
+ * True when an error is one of the stack's authenticated diagnostics — thrown
+ * by an engine (xprsn, sjabloon, or padvinder) directly, or re-thrown by
+ * quario through that engine's `relocate` — i.e. it safely carries the
+ * optional `code`/`start`/`end`/`limit`/`actual`/`blocks` metadata.
+ * Authentication is by identity: an error merely shaped like a diagnostic does
+ * not pass, and a located copy passes because the engine that minted the
+ * original made the copy.
  *
  * @param {unknown} error The caught value.
  * @returns {boolean} Whether `error` is a located diagnostic.
  */
 export function isDiagnostic(error) {
-  return (
-    DIAG.has(/** @type {any} */ (error)) ||
-    isXprsnDiagnostic(error) ||
-    isTemplateDiagnostic(error) ||
-    isQueryDiagnostic(error)
-  );
+  return isXprsnDiagnostic(error) || isTemplateDiagnostic(error) || isQueryDiagnostic(error);
 }
 
 /** @type {(msg: string) => never} */
@@ -38,43 +27,41 @@ export let err = (msg) => {
   throw Error(msg);
 };
 
-/** @type {(error: any) => boolean} */
-let trustedOf = (error) => error instanceof Error && Object.hasOwn(error, "code");
-
-/** @type {(path: string, src: any) => string} */
-let locationOf = (path, src) => (src === undefined ? path : path + " [" + String(src) + "]");
-
-/** @type {(path: string, src: any, error: any) => any} */
-let wrap = (path, src, error) => {
-  let location = locationOf(path, src);
-  if (error instanceof Error)
-    return new /** @type {any} */ (error.constructor)(location + ": " + error.message);
-  return new Error(location + ": " + String(error));
-};
-
-/** @type {(located: any, error: any, keys: string[], extra: (value: any) => any) => void} */
-let copyOwn = (located, error, keys, extra) => {
-  for (let key of keys) if (Object.hasOwn(error, key)) located[key] = extra(error[key]);
-};
-
-/** @type {(located: any, error: any) => void} */
-let copyBlocks = (located, error) => {
-  if (Object.hasOwn(error, "blocks"))
-    Object.defineProperty(located, "blocks", { value: error.blocks, enumerable: true });
-};
+// How a located error remembers where it happened as data: the traversal reads
+// this to build a structured problem, so nothing parses a message back apart.
+// A symbol, so the located copy's public shape stays exactly the engine's.
+export let LOCATION = Symbol("quario.location");
 
-/** @type {(located: any, error: any, shift: number) => void} */
-let stamp = (located, error, shift) => {
-  located.code = error.code;
-  copyOwn(located, error, ["start", "end"], (value) => value + shift);
-  copyOwn(located, error, ["limit", "actual"], (value) => value);
-  copyBlocks(located, error);
-  DIAG.add(located);
+/** @type {(path: string, msg: string) => never} */
+export let fault = (path, msg) => {
+  throw Object.assign(Error(path + ": " + msg), { [LOCATION]: { path } });
 };
 
-/** @type {(path: string, src: any, error: any, shift?: number, trusted?: boolean) => never} */
-export let locate = (path, src, error, shift = 0, trusted = trustedOf(error)) => {
-  let located = wrap(path, src, error);
-  if (trusted) stamp(located, error, shift);
-  throw located;
+/**
+ * Re-throw `error` located at `path`, with `src` — the offending author
+ * source — in the message.
+ *
+ * A diagnostic is relocated by the engine that authenticated it, so the copy
+ * carries every field that engine puts on it and passes that engine's own
+ * guard (ADR 0024). `relocate` is that engine's relocation — and a verdict as
+ * much as a callback: the call site holds the guard, because two of them are
+ * scoped to one evaluator rather than to the module, and `false` is its way of
+ * saying the guard rejected this error. Anything else — a host function's
+ * throw, quario's own verdict on image bytes — is wrapped as a plain error
+ * with no metadata at all.
+ *
+ * @type {(path: string, src: any, error: any, relocate?: false | ((e: any, o: { prefix: string, offset: number }) => any), offset?: number) => never}
+ */
+export let locate = (path, src, error, relocate, offset = 0) => {
+  let prefix = (src === undefined ? path : path + " [" + String(src) + "]") + ": ";
+  let where = { [LOCATION]: { path, source: src } };
+  if (relocate) throw Object.assign(relocate(error, { prefix, offset }), where);
+  // A host throw keeps its own class — the located error is the same kind of
+  // failure, named where it happened — and gains no diagnostic metadata.
+  throw Object.assign(
+    error instanceof Error
+      ? new /** @type {any} */ (error.constructor)(prefix + error.message)
+      : Error(prefix + String(error)),
+    where,
+  );
 };