quario 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # quario
 
+## 0.12.0
+
+### Minor Changes
+
+- A registered function may be asynchronous. The engine resolves every such call before the banded walk, in one wave, and the walk itself stays synchronous.
+
+  Write the call as the whole value of a cell in a detail row, and take its arguments from the row:
+
+  ```jsonc
+  { "data": "$.orders[*]", "detail": [{ "type": "text", "value": "{{ customerName(@.customerId) }}" }] }
+  ```
+
+  The engine calls the function once for every row it renders, starts every call together, and waits for all of them before the first event reaches a target. A row that `where` or `take` removed is never fetched. Deduplication and any limit on how many calls run at once belong to the function itself: a report over ten thousand rows starts ten thousand calls.
+
+  Three rules hold. The call is the whole value of a cell, so `{{ lookup(@.id).name }}` and `{{ "#" + lookup(@.id) }}` are errors that name the function and the cell. The arguments come from the row, so a cell that reads no row cannot hold one. And `render()` resolves, while `stream()` reports the call it cannot wait for.
+
+  A function that rejects fails the render with an error that names the function and the cell, and keeps the class the function threw.
+
+### Patch Changes
+
+- **The declarations now refuse what the engine refuses.** Eight style declarations type-checked at nodes the engine rejects them on, so a report that compiled could still fail to render: `valign` on a stacked item, flow spacing on a table cell or a total cell, and `format`, `currency`, `href` and flow spacing on a row box. Each site now states the narrowing the engine has always applied, through four new exported types — `StackedStyleDeclarations`, `CellStyleDeclarations`, `RowStyleDeclarations`, and the `SlotStyleDeclarations` that was already there.
+
+  No document that the engine accepts has stopped type-checking. The narrowing removes only names the engine was already refusing.
+
+  **`SCHEMA.md` now states two keys it always admitted.** The document-shape block never listed `required`, and the group-definition block never listed `collapsed` — the latter while three target sections linked to that section for it, and while the section said a group is collapsible without a field for it. Both are stated now, `collapsed` with the paragraph it never had.
+
+- **The declarations now carry `required`, and a group's `label` and `collapsed`.** `ReportSchema` states `required`, and `Group` states both `label` and `collapsed`. The engine has admitted all three and `SCHEMA.md` specifies them, so a TypeScript author marking a declaration required, naming an instance for navigation, or opening a group shut was told it was an error and had to cast.
+
+  `required` is keyed by a new exported type, `RequirableName`, which spells the same names `REQUIRABLE` carries. A marking no target could answer for is therefore an error where an author writes it, rather than a `plan` problem after the fact — `{ "negative": true }` names a modifier inside `format` rather than a declaration a target answers for, and the compiler now says so. `collapsed` reads `boolean`, because the engine accepts `false` for it as plainly as `true`.
+
+## 0.11.1
+
+### Patch Changes
+
+- **The declarations now carry `href` and `schemes`.** `StyleDeclarations` states `href`, `RunStyleDeclarations` picks it up as the twelfth inline name, and `QuarioOptions` states the `schemes` allowlist beside the three names that present `format`. The engine has admitted both since 0.11.0 and `SCHEMA.md` specifies them; the published types said otherwise, so a TypeScript consumer writing a link, or the allowlist that admits one, was told it was an error. The `format` declaration's own comment said a kind carries one modifier, which stopped being true when a number kind took three. `test/types.check.ts` exercises the allowlist and both spellings of a link, since a hand-written surface drifts exactly where nothing reads it.
+
 ## 0.11.0
 
 ### Minor Changes

package/lib/index.d.ts

@@ -95,8 +95,9 @@ export interface StyleDeclarations extends BoxDeclarations {
   valign?: ExpressionValue<VAlign>;
   /**
    * How a number or date is presented: a kind, or an object naming one and
-   * carrying the single modifier that kind understands — `digits` for the
-   * three number kinds, `form` for `date`. Locale stays on the instance.
+   * carrying the modifiers that kind understands — `digits`, `negative` and
+   * `zero` for the three number kinds, `form` for `date`. Locale stays on the
+   * instance.
    */
   format?: ExpressionValue<FormatDeclaration>;
   /**
@@ -107,6 +108,14 @@ export interface StyleDeclarations extends BoxDeclarations {
    * than falling back to the instance's currency. Unread without the kind.
    */
   currency?: ExpressionValue<string>;
+  /**
+   * Where this cell's text points: a URL, or `#` and a group's `label` for a
+   * destination inside the document. The one declaration the engine judges
+   * rather than passes on — a URL is admitted against the instance's `schemes`
+   * allowlist before it crosses, and a refused value is omitted, so the text
+   * renders and the link does not. A table row refuses it.
+   */
+  href?: ExpressionValue<string>;
   /** Blank space before this item, in points. */
   spaceBefore?: ExpressionValue<number>;
   /** Blank space after this item, in points. */
@@ -147,6 +156,36 @@ export const ZERO_DASH: string;
  */
 export const REQUIRABLE: readonly string[];
 
+/**
+ * The same names as a type, so a marking no target could answer for is an
+ * error where an author writes it rather than a
+ * [`plan`](../../../SCHEMA.md#validation) problem after the fact. This
+ * package's suite holds the two to each other in both directions, so neither
+ * can gain a name the other lacks.
+ */
+export type RequirableName =
+  | "page.header"
+  | "page.footer"
+  | "break"
+  | "reset"
+  | "page.margin"
+  | "header.height"
+  | "groups"
+  | "label"
+  | "collapsed"
+  | "column.width"
+  | "slot.width"
+  | "span"
+  | "uppercase"
+  | "href"
+  | "spaceBefore"
+  | "spaceAfter"
+  | "format"
+  | "family"
+  | "valign"
+  | "runs"
+  | "alt";
+
 /**
  * The declarations a styled run accepts: the inline half of the vocabulary,
  * and nothing else. The box and flow spacing describe a block and `align`
@@ -167,6 +206,7 @@ export type RunStyleDeclarations = Pick<
   | "uppercase"
   | "format"
   | "currency"
+  | "href"
 >;
 
 /**
@@ -240,8 +280,10 @@ export interface Cell {
   style?: StyleDeclarations;
 }
 
-export interface TextItem extends Cell {
+export interface TextItem extends Omit<Cell, "style"> {
   type: "text";
+  /** Literal only — never an expression. */
+  style?: StackedStyleDeclarations;
 }
 
 /** How an image is sized: at its intrinsic size, or scaled to the content width. */
@@ -292,6 +334,32 @@ export interface ImageItem {
  */
 export type SlotStyleDeclarations = Omit<StyleDeclarations, "spaceBefore" | "spaceAfter">;
 
+/**
+ * What a stacked item declares: the vocabulary less `valign`. A stacked item
+ * sits in a band's flow and its box is its own height, so there is nothing for
+ * it to align against — where a slot's box is the split's height, which is why
+ * a slot keeps the name.
+ */
+export type StackedStyleDeclarations = Omit<StyleDeclarations, "valign">;
+
+/**
+ * What a table cell declares: the vocabulary less flow spacing. The same
+ * narrowing a slot takes, under its own name because the engine refuses the
+ * two in their own words and a reader follows the wording to the node.
+ */
+export type CellStyleDeclarations = Omit<StyleDeclarations, "spaceBefore" | "spaceAfter">;
+
+/**
+ * What a row box declares: a cell's names less the three that present a value.
+ * A box wraps cells and holds no value of its own, so `format`, `currency` and
+ * `href` have nothing to act on. Worn by the detail row, the header row's box
+ * and both halves of the totals block.
+ */
+export type RowStyleDeclarations = Omit<
+  StyleDeclarations,
+  "format" | "currency" | "href" | "spaceBefore" | "spaceAfter"
+>;
+
 /**
  * What an image slot declares: an image item's names less flow spacing, plus
  * `valign` — the one name an image accepts in a slot and nowhere else, because
@@ -343,7 +411,9 @@ export interface TableHeader {
   span?: number;
 }
 
-export interface TableColumn extends Cell {
+export interface TableColumn extends Omit<Cell, "style"> {
+  /** Literal only — never an expression. */
+  style?: CellStyleDeclarations;
   /**
    * Absent exactly when a neighbour's header `span` covers this column: every
    * column's header slot is filled once, by its own or by a span.
@@ -355,14 +425,16 @@ export interface TableColumn extends Cell {
 
 export interface TableRow {
   visible?: ExpressionValue<boolean>;
-  style?: StyleDeclarations;
+  style?: RowStyleDeclarations;
 }
 
 /**
  * One cell of a total row: an ordinary cell, plus the columns it covers. The
  * spans in a row must sum to the column count exactly.
  */
-export type TotalCell = Cell & {
+export type TotalCell = Omit<Cell, "style"> & {
+  /** Literal only — never an expression. */
+  style?: CellStyleDeclarations;
   /**
    * How many columns this cell covers — a literal integer >= 1, never an
    * expression; absent is 1.
@@ -373,7 +445,7 @@ export type TotalCell = Cell & {
 export interface TotalRow {
   cells: [TotalCell, ...TotalCell[]];
   visible?: ExpressionValue<boolean>;
-  style?: StyleDeclarations;
+  style?: RowStyleDeclarations;
 }
 
 /**
@@ -392,7 +464,7 @@ export interface TotalBlock extends TableRow {
  * header cells on every page continuation.
  */
 export interface TableHeaderBox {
-  style?: StyleDeclarations;
+  style?: RowStyleDeclarations;
 }
 
 export interface TableDetail {
@@ -405,6 +477,23 @@ export interface TableDetail {
 export interface Group {
   name: string;
   by: `=${string}`;
+  /**
+   * This instance's name for **navigation** rather than for the page: one
+   * template, resolved once per instance in group scope, where the handle and
+   * `$` are bound and `@` is unbound. A target with somewhere to put a
+   * navigation name spends it there and the rest withdraw it, so it never
+   * changes what the page shows.
+   */
+  label?: string;
+  /**
+   * Open every instance of this group shut: its own header and footer show,
+   * and the content between them does not. A target with a way to hide a row
+   * and keep it -- the worksheet -- hides those rows, where a reader opens the
+   * group again. The rest drop them, and the
+   * [matrix](../../../SCHEMA.md#what-each-target-makes-of-a-declaration) says
+   * which does which.
+   */
+  collapsed?: boolean;
   /**
    * Where this group turns a page (paginated targets). Every boundary between
    * consecutive instances turns; `before` adds the run's leading edge, `after`
@@ -448,6 +537,15 @@ export interface PageBands {
 
 export interface ReportSchema {
   params?: Record<string, JsonValue>;
+  /**
+   * The declarations this document cannot do without, each marked `true`.
+   * Only [`plan`](../../../SCHEMA.md#validation) reads it, against the target
+   * descriptors its caller names: every required declaration one of them
+   * withdraws or leaves unread becomes a problem of its own at
+   * `required.<name>`, which nulls the report as any other problem does. No
+   * target sees the marking, and no render changes because of it.
+   */
+  required?: Partial<Record<RequirableName, true>>;
   data: string;
   where?: `=${string}`;
   sort?: SortKey[];
@@ -516,6 +614,14 @@ export interface QuarioOptions {
   currency?: string;
   /** Timezone for `format: "date"`. Defaults to `"UTC"`. */
   timeZone?: string;
+  /**
+   * The URL schemes an `href` may use, each lower-case and ending in a colon.
+   * Defaults to `https:` and `mailto:`. The allowlist is the host's, never the
+   * document's, and a value this cannot read throws at construction rather
+   * than falling back — an allowlist quietly replaced is a host believing it
+   * restricted something it had not.
+   */
+  schemes?: readonly string[];
 }
 
 /** The settled result of an instance's license key verification. */

package/lib/index.js

@@ -18,7 +18,7 @@ import { MARKING, verify } from "./license.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";
+import { aggregateValue, RESOLVED, startRunners, withPage, withRow } from "./scope.js";
 import { opt } from "./stream.js";
 
 // The event stream's public seam, single-sourced in ./stream.js, and the
@@ -199,7 +199,8 @@ let freezeAnchors = (anchors) =>
  * @param {() => string | false} marking This render's unlicensed marking — its
  *   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[],
+ * @returns {{(data?: any, pre?: any): Generator<object, void, undefined>,
+ *   names: string[],
  *   functions: { name: string, arity: number, doc?: string }[],
  *   paths: readonly any[]}} Event stream factory.
  */
@@ -239,6 +240,12 @@ function* guardPin(events) {
   }
 }
 
+// How `render` reaches the resolve wave without publishing it. A host drives a
+// compiled report through `render()` or `stream()` and never settles one
+// itself, so this is the engine talking to itself: a symbol, so the compiled
+// report's public shape stays exactly what `lib/index.d.ts` declares.
+let SETTLE = Symbol("quario.settle");
+
 /**
  * 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
@@ -250,7 +257,8 @@ function* guardPin(events) {
  * @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[],
+ * @returns {{(data?: any, pre?: any): Generator<object, void, undefined>,
+ *   names: string[],
  *   functions: { name: string, arity: number, doc?: string }[],
  *   paths: readonly any[]}} Event stream factory.
  */
@@ -276,6 +284,7 @@ function assemble(planned, schema, marking, options) {
     pageFooter,
     headerHeight,
     margin,
+    slotted,
   } = /** @type {NonNullable<typeof planned.compiled>} */ (planned.compiled);
 
   // The runner's own faults are located per render: a budget is spent while
@@ -289,23 +298,99 @@ function assemble(planned, schema, marking, options) {
     }
   };
 
-  /** @type {(data: any) => Generator<any>} */
-  let emit = (data) => {
+  // The eager pre-pass: select → filter → report sort → report take →
+  // aggregates (over the rows that remain). It cannot be lazy because the
+  // report header may interpolate report aggregates; only the banded walk
+  // itself streams. Lifted out of `emit` so a render that has to settle async
+  // calls first runs it once and hands the result on: a second run would
+  // re-spend the data query's budget and could fail a render that works.
+  /** @type {(data: any) => any} */
+  let prepare = (data) => {
     let root = Object.create(null);
     root.params = params;
     root.input = inputOf(data);
     let base = Object.create(null);
     base["$"] = root;
-    // The eager pre-pass: select → filter → report sort → report take →
-    // 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 = 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.
+    return {
+      root,
+      base,
+      rows,
+      aggregates: foldAggs(aggs, rows, base, root),
+    };
+  };
+
+  // The wave settles what it can and leaves the rest to the walk. A slot it
+  // cannot evaluate against the row alone -- a synchronous host call reading
+  // `run.x` or a group handle, which is ordinary and stays ordinary -- goes
+  // back unsupplied, so the walk evaluates it with the scope it always had.
+  // Nothing is swallowed: a fault that is real throws again there, at the same
+  // cell path, and an async call whose arguments were not row-local reaches
+  // `runCell` as a promise nothing resolved and is refused by name.
+  let UNSETTLED = Symbol("quario.unsettled");
+  /** @type {(slot: any, scope: any) => any} */
+  let attempt = (slot, scope) => {
+    try {
+      return slot(scope);
+    } catch {
+      return UNSETTLED;
+    }
+  };
+
+  // The resolve wave (docs/adr/0088): every async call the surviving rows make,
+  // issued together and settled once, before the walk sees a single row. The
+  // walk then reads the answers off the render base and stays synchronous.
+  // A row the pre-pass dropped is never fetched.
+  /** @type {(data: any) => Promise<any>} */
+  let resolve = async (data) => {
+    let pre = prepare(data),
+      held = new Map(),
+      waiting = [];
+    // The map is parked whether or not anything filled it: its presence is how
+    // a cell tells a render from a caller draining `stream()`, and the two owe
+    // the author different sentences.
+    pre.base[RESOLVED] = held;
+    if (!slotted.length) return pre;
+    for (let row of pre.rows) {
+      let scope = withRow(pre.base, row),
+        forRow = Object.create(null);
+      held.set(row, forRow);
+      for (let { path, source, live } of slotted) {
+        /** @type {any[]} */
+        let supply = [];
+        forRow[path] = supply;
+        // A slot's own scope is the row and nothing else: no runners, no group
+        // handle. That is the rule, and it is what makes one call per row
+        // answerable without the walk having run.
+        for (let [at, slot] of live) {
+          let answer = attempt(slot, scope);
+          if (answer === UNSETTLED) continue;
+          supply[at] = answer;
+          if (typeof answer?.then === "function")
+            waiting.push(
+              Promise.resolve(answer).then(
+                (value) => (supply[at] = value),
+                // No relocation: the template finished evaluating before this
+                // promise settled, so what rejected is host code and keeps
+                // its own class behind the cell path (docs/adr/0057).
+                (error) => locate(path, source, error),
+              ),
+            );
+        }
+      }
+    }
+    await Promise.all(waiting);
+    return pre;
+  };
+
+  /** @type {(data: any, pre?: any) => Generator<any>} */
+  let emit = (data, pre = prepare(data)) => {
+    let { root, base, rows, aggregates } = pre;
+    // The report's runners belong to this drain, not to the pre-pass: a target
+    // that drains the same stream twice counts from one again both times.
     let runners = startRunners(running);
     // Per-render page band closures: a paginated target calls them once per
     // page with `{ number, total }` (1-based) and receives resolved item
@@ -347,6 +432,7 @@ function assemble(planned, schema, marking, options) {
     return walked();
   };
   return Object.assign(emit, {
+    [SETTLE]: resolve,
     names: Array.from(planned.names),
     // Already signature objects — plan() paired each called name with its
     // registry metadata through xprsn's signatures().
@@ -412,7 +498,26 @@ export function quario(options) {
     // 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));
+      // The resolve wave runs before the target compiles, so the stream the
+      // target drains is the one carrying its answers (docs/adr/0088). The
+      // bound stream keeps the compiled report's own metadata: a target reads
+      // it off the function it was handed.
+      return settled
+        .then(() => /** @type {any} */ (stream)[SETTLE](data))
+        .then((pre) =>
+          runTarget(
+            target.compile,
+            // Only the render's own document reads the settled wave. A target
+            // that drains the stream over something else gets an ordinary
+            // stream, because nothing resolved that document's rows.
+            Object.assign((/** @type {any} */ d) => (d === data ? stream(d, pre) : stream(d)), {
+              names: stream.names,
+              functions: stream.functions,
+              paths: stream.paths,
+            }),
+            data,
+          ),
+        );
     },
   });
   return {

package/lib/plan.js

@@ -51,7 +51,7 @@ import { LOCATION, fault, isDiagnostic, locate } from "./locate.js";
 import { ANCHORS, BLOCKED, NAME, RESERVED, isRequirable, record } from "./names.js";
 import { MATH } from "./math.js";
 import { REDUCERS, reducerFor } from "./reducers.js";
-import { aggregateValue, withRow } from "./scope.js";
+import { aggregateValue, RESOLVED, withRow } from "./scope.js";
 import { dimensions, sniff } from "./image.js";
 import { oneValue, opt, sameStyle } from "./stream.js";
 import {
@@ -149,12 +149,68 @@ let collect = (from, into) => {
 /** @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"];
+// Every closed key set on the authoring surface, named in one place. The
+// readers below are what enforce them, and the gates that hold the other two
+// descriptions of the surface to this one -- the declarations and SCHEMA.md --
+// read the same object, so no gate keeps a list of its own (ADR 0086). A set
+// that lives only at its call site is one nothing can check.
+//
+// A slot's set is its item's plus the width share, derived rather than
+// restated, so the two cannot part.
+let TEXT = ["type", "value", "visible", "style"];
+let IMAGE = ["type", "source", "fit", "alt", "visible", "style"];
+export let KEY_SETS = Object.freeze({
+  report: [
+    "params",
+    "required",
+    "data",
+    "where",
+    "sort",
+    "take",
+    "aggregates",
+    "run",
+    "style",
+    "header",
+    "empty",
+    "columns",
+    "groups",
+    "detail",
+    "footer",
+    "page",
+  ],
+  reportHeader: ["height", "items"],
+  page: ["header", "footer", "margin"],
+  group: [
+    "name",
+    "by",
+    "label",
+    "collapsed",
+    "break",
+    "reset",
+    "columns",
+    "sort",
+    "take",
+    "aggregates",
+    "run",
+    "header",
+    "footer",
+  ],
+  sortKey: ["by", "dir"],
+  text: TEXT,
+  textSlot: [...TEXT, "width"],
+  image: IMAGE,
+  imageSlot: [...IMAGE, "width"],
+  split: ["type", "slots", "visible", "style"],
+  styledRun: ["value", "style"],
+  detail: ["header", "row", "columns", "total"],
+  detailHeader: ["style"],
+  detailRow: ["visible", "style"],
+  column: ["header", "value", "visible", "style", "width"],
+  columnHeader: ["value", "style", "span"],
+  totalBlock: ["style", "visible", "rows"],
+  totalRow: ["cells", "style", "visible"],
+  totalCell: ["value", "visible", "style", "span"],
+});
 
 // A group's two structural literals. `break` names a position rather than a
 // unit (ADR 0077), and this table is the whole of what its four values mean:
@@ -446,6 +502,10 @@ let planState = (schema, funcs) => {
   // keeps the anchor-and-handle subset a consumer placing a node needs.
   /** @type {Map<string, Set<string>>} */
   let anchors = new Map();
+  /** @type {{ path: string, source: string,
+   *   live: [number, (scope: any) => any][] }[]} */
+  let slotted = [];
+
   /** @type {(path: string, reads: { name: string }[]) => void} */
   let anchorsOf = (path, reads) => {
     for (let { name } of reads) {
@@ -458,11 +518,19 @@ let planState = (schema, funcs) => {
 
   return {
     FNS,
+    // The host's own registry keys, which is what separates a call that may
+    // hand back a promise from one of the engine's synchronous built-ins. A
+    // host that shadows a built-in owns that name, and its key says so.
+    HOSTS: new Set(Object.keys(funcs || {})),
     names,
     functions,
     BND,
     problems,
     warnings,
+    // Every cell the resolve wave has to settle before the walk, in compile
+    // order (docs/adr/0088). Empty for a document that calls nothing async,
+    // which is what lets a render skip the wave entirely.
+    slotted,
     runNames,
     anchors,
     anchorsOf,
@@ -492,13 +560,27 @@ let compileProp = (source, path, FNS, BND) => {
     locate(path, source, error, isXprsnDiagnostic(error) && relocateXprsn, 1);
   }
 };
+// A promise nothing settled, refused where it stands. It is worse than a wrong
+// value, because it is truthy: an unrefused one keeps every row a `where`
+// should drop and shows every item a `visible` should hide. One helper, so the
+// three places that can meet one say it the same way (docs/adr/0088).
+/** @type {(value: any, path: string, source: any, said: string) => any} */
+let refuseThenable = (value, path, source, said) => {
+  if (typeof value?.then === "function") locate(path, source, TypeError(said));
+  return value;
+};
+let ONLY_A_CELL = "an async function is read from a cell's value and nowhere else";
 /** @type {(expression: any, path: string, source: any) => Eval} */
 let runProp = (expression, path, source) => (scope) => {
+  let out;
   try {
-    return expression(scope);
+    out = expression(scope);
   } catch (error) {
     locate(path, source, error, expression.isDiagnostic(error) && relocateXprsn, 1);
   }
+  // The resolve wave settles a cell's value and only that, so nothing ever
+  // settles a computed property.
+  return refuseThenable(out, path, source, ONLY_A_CELL);
 };
 // The [live field](../../../CONTEXT.md#live-field): which page value a token
 // *is*, for a target whose own format numbers pages. sjabloon offers each
@@ -524,13 +606,52 @@ let compileCell = (src, path, FNS, BND) => {
     locate(path, src, 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);
-  }
+// A promise that reached a token is one nothing resolved: either the caller
+// drained `stream()`, which cannot wait, or the cell sits where no row does.
+// xprsn already refuses one an operator consumed, so what arrives here is a
+// whole-token call, and saying so is the only thing left to do about it.
+/** @type {(out: any, path: string, source: any, resolving: boolean) => any} */
+let refusePending = (out, path, source, resolving) => {
+  let said = resolving
+    ? "an async function is read from a detail row's cell and nowhere else"
+    : "an async function is resolved by render(), and stream() cannot wait for one";
+  for (let token of out) refuseThenable(token.value, path, source, said);
+  return out;
+};
+// This cell's settled values for the row in scope, or nothing when the wave
+// did not reach it. `held` is the render's whole map; a caller that already
+// read it passes it in, because its presence is also how a cell tells a render
+// from a caller draining `stream()`.
+/** @type {(held: any, scope: Scope, path: string) => any} */
+let settledFor = (held, scope, path) => {
+  let forRow = held && held.get(scope["@"]);
+  return forRow && forRow[path];
+};
+/** @type {(tokens: any, path: string, source: any, live: any[]) => (scope: Scope) => any} */
+let runCell = (tokens, path, source, live) => {
+  // The branch is the compile's, not the render's: a cell that calls no host
+  // function is the overwhelming majority and reads nothing off the chain.
+  if (!live.length)
+    return (scope) => {
+      try {
+        return tokens.scoped(scope);
+      } catch (error) {
+        locate(path, source, error, tokens.isDiagnostic(error) && relocateTemplate);
+      }
+    };
+  return (scope) => {
+    let held = /** @type {any} */ (scope)[RESOLVED],
+      supply = settledFor(held, scope, path);
+    let out;
+    try {
+      out = tokens.scoped(scope, supply);
+    } catch (error) {
+      locate(path, source, error, tokens.isDiagnostic(error) && relocateTemplate);
+    }
+    // Outside the catch: the refusal locates itself, and locating it twice
+    // would print the cell path twice.
+    return supply ? out : refusePending(out, path, source, !!held);
+  };
 };
 /** @type {(spec: string) => { fn: string, src: string, colon: number }} */
 let splitFold = (spec) => {
@@ -554,7 +675,7 @@ let checkExprFold = (src, fn, path) => {
 };
 
 /** @param {State} state */
-let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
+let primitives = ({ FNS, HOSTS, BND, names, functions, anchorsOf, slotted }) => {
   // 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} */
@@ -583,7 +704,25 @@ let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
     collect(tokens.names, names);
     collect(tokens.functions, functions);
     anchorsOf(path, tokens.reads);
-    return runCell(tokens, path, source);
+    // A slot is any registry call, and most of them are the engine's own
+    // reducers and rounders, which are synchronous by construction. Only a
+    // call into the host's registry can hand back a promise, so only those
+    // reach the resolve wave; every index stays sjabloon's, because the
+    // supply array is indexed by slot.
+    /** @type {[number, any][]} */
+    let live = tokens.slots
+      .map((/** @type {any} */ slot, /** @type {number} */ at) => [at, slot])
+      .filter((/** @type {any} */ pair) =>
+        pair[1].functions.some((/** @type {string} */ n) => HOSTS.has(n)),
+      );
+    // A host call's arguments come from the row (docs/adr/0088), so only a cell
+    // that reads `@` can be projected. The rest are not refused here: most
+    // host functions are synchronous, a footer calling one is ordinary, and
+    // whether a call is async is not a fact a compile holds. A promise that
+    // reaches a token unresolved is what says so, and `runCell` refuses it.
+    if (live.length && tokens.reads.some((/** @type {any} */ read) => read.name === "@"))
+      slotted.push({ path, source, live });
+    return runCell(tokens, path, source, live);
   };
 
   // Parse "reducer:=expr" into a reducer name and a compiled per-row expression,
@@ -958,7 +1097,7 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
       bad(path, "expected an object");
       return NO_STYLED_RUN;
     }
-    keys(def, ["value", "style"], path);
+    keys(def, KEY_SETS.styledRun, path);
     let tpl = textValue(def.value, path + ".value");
     unreadFormat(def.value, def.style, path);
     let entries = entriesOf(def, path, checkRunStyle);
@@ -1043,7 +1182,7 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
   let sortKey = (spec, i, path) => {
     let keyPath = path + "[" + i + "]";
     if (!obj(spec, keyPath)) return [];
-    keys(spec, ["by", "dir"], keyPath);
+    keys(spec, KEY_SETS.sortKey, keyPath);
     let by = expression(spec.by, keyPath + ".by");
     checkDir(spec.dir, keyPath + ".dir");
     return [{ by, sign: spec.dir === "desc" ? -1 : 1 }];
@@ -1261,7 +1400,7 @@ let nodes = (
       bad(path, "expected a template string or object");
       return { cell: cellShape(NO_STYLED_RUNS, null, NO_LOOK), span: 1, box: NO_LOOK.box };
     }
-    keys(def, ["value", "style", "span"], path);
+    keys(def, KEY_SETS.columnHeader, path);
     return { ...cellOf(def, path), span: spanOf(def, path) };
   };
 
@@ -1298,7 +1437,7 @@ let nodes = (
   /** @type {(def: any, path: string, slot: string) => any} */
   let columnOf = (def, path, slot) => {
     if (!obj(def, path)) return null;
-    keys(def, ["header", "value", "visible", "style", "width"], path);
+    keys(def, KEY_SETS.column, path);
     let header = headerSlot(def.header, path + ".header", slot);
     let { styled, visible, look } = cellParts(def, path, checkCellStyle);
     // A width is a percentage of the table width, resolved by every target.
@@ -1319,7 +1458,7 @@ let nodes = (
    */
   let totalOf = (def, path) => {
     if (!obj(def, path)) return null;
-    keys(def, ["value", "visible", "style", "span"], path);
+    keys(def, KEY_SETS.totalCell, path);
     return { ...cellOf(def, path), span: spanOf(def, path) };
   };
 
@@ -1329,7 +1468,7 @@ let nodes = (
   // 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);
+    keys(def, inSlot ? KEY_SETS.textSlot : KEY_SETS.text, path);
     checkTextType(def.type, path);
     let { styled, visible, look } = cellParts(def, path, inSlot ? checkSlotStyle : checkItemStyle);
     let shape = cellShape(styled, inSlot ? visible : null, look);
@@ -1415,7 +1554,7 @@ let nodes = (
   let imageLook = (inSlot) => (inSlot ? checkSlotImageStyle : checkImageStyle);
   /** @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);
+    keys(def, inSlot ? KEY_SETS.imageSlot : KEY_SETS.image, 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
@@ -1469,7 +1608,7 @@ let nodes = (
   // 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);
+    keys(def, KEY_SETS.split, 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,
@@ -1589,7 +1728,7 @@ let bands = (
   let rowLook = (value) => {
     if (value.row == null || !obj(value.row, "detail.row"))
       return { rowVisible: null, rowStyles: NO_ROW_STYLE };
-    keys(value.row, ["visible", "style"], "detail.row");
+    keys(value.row, KEY_SETS.detailRow, "detail.row");
     return {
       rowVisible: visibleOf(value.row, "detail.row"),
       rowStyles: rowStylesOf(value.row, "detail.row"),
@@ -1600,7 +1739,7 @@ let bands = (
   /** @type {(value: any) => RowStyles} */
   let headerLook = (value) => {
     if (value.header == null || !obj(value.header, "detail.header")) return NO_ROW_STYLE;
-    keys(value.header, ["style"], "detail.header");
+    keys(value.header, KEY_SETS.detailHeader, "detail.header");
     return rowStylesOf(value.header, "detail.header");
   };
   // Which slot each column's header sits in, walked positionally rather than
@@ -1675,7 +1814,7 @@ let bands = (
   /** @type {(value: any, defs: any[] | null) => TotalBlock} */
   let tableTotals = (value, defs) => {
     if (value.total == null || !obj(value.total, "detail.total")) return NO_TOTALS;
-    keys(value.total, ["style", "visible", "rows"], "detail.total");
+    keys(value.total, KEY_SETS.totalBlock, "detail.total");
     let block = rowEntriesOf(value.total, "detail.total");
     return {
       visible: visibleOf(value.total, "detail.total"),
@@ -1701,7 +1840,7 @@ let bands = (
   /** @type {(def: any, path: string, defs: any[] | null, block: RowEntries) => TotalRow} */
   let totalRowOf = (def, path, defs, block) => {
     if (!obj(def, path)) return { styles: foldRow(block), visible: null, cells: [], fan: [] };
-    keys(def, ["cells", "style", "visible"], path);
+    keys(def, KEY_SETS.totalRow, path);
     let cells = counted(arr(def.cells, path + ".cells", true), defs, path);
     let styles = foldRow(underRow(block, rowEntriesOf(def, path)));
     let mapped = mapTotals(cells, path + ".cells");
@@ -1789,7 +1928,7 @@ let bands = (
   };
   /** @type {(value: any) => Band} */
   let tableOf = (value) => {
-    keys(value, ["header", "row", "columns", "total"], "detail");
+    keys(value, KEY_SETS.detail, "detail");
     let headerStyles = headerLook(value);
     let { rowVisible, rowStyles } = rowLook(value);
     let { defs, columns } = tableColumns(value);
@@ -1950,25 +2089,7 @@ let bands = (
     };
   /** @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",
-        "label",
-        "collapsed",
-        "break",
-        "reset",
-        "columns",
-        "sort",
-        "take",
-        "aggregates",
-        "run",
-        "header",
-        "footer",
-      ],
-      path,
-    );
+    keys(def, KEY_SETS.group, path);
     named(def.name, path + ".name", RESERVED);
     noteGroup(def.name, path + ".name");
     let by = expression(def.by, path + ".by");
@@ -2101,7 +2222,7 @@ let reportHeaderOf = (value, keys, itemsOf, bad) => {
     bad("header", "expected an array of items or { height, items }");
     return { items: itemsOf(null, "header", "report-header"), height: null };
   }
-  keys(value, ["height", "items"], "header");
+  keys(value, KEY_SETS.reportHeader, "header");
   return {
     items: itemsOf(value.items, "header.items", "report-header"),
     height: headerHeightOf(value.height, bad),
@@ -2118,7 +2239,7 @@ let pageMarginOf = (margin, bad) => {
 let pageBands = (schema, obj, keys, itemsOf, bad) => {
   if (schema.page == null || !obj(schema.page, "page"))
     return { pageHeader: null, pageFooter: null, margin: null };
-  keys(schema.page, ["header", "footer", "margin"], "page");
+  keys(schema.page, KEY_SETS.page, "page");
   return {
     pageHeader: maybeItems(schema.page.header, "page.header", "page-header", itemsOf),
     pageFooter: maybeItems(schema.page.footer, "page.footer", "page-footer", itemsOf),
@@ -2148,7 +2269,7 @@ let needPinnedMargin = (headerHeight, schema, bad) => {
  *   render may traverse, never what this descent reports.
  */
 let traverse = (
-  { add, bad, attempt, pin, runNames },
+  { add, bad, attempt, pin, runNames, slotted },
   { arr, obj, keys, named, expression, columnsOf, takeOf, foldsOf, sortOf, stylesOf },
   { itemsOf },
   { bandOf },
@@ -2159,28 +2280,7 @@ let traverse = (
     add("schema: expected an object");
     return null;
   }
-  keys(
-    schema,
-    [
-      "params",
-      "required",
-      "data",
-      "where",
-      "sort",
-      "take",
-      "aggregates",
-      "run",
-      "style",
-      "header",
-      "empty",
-      "columns",
-      "groups",
-      "detail",
-      "footer",
-      "page",
-    ],
-    "",
-  );
+  keys(schema, KEY_SETS.report, "");
   // 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`.
@@ -2234,6 +2334,7 @@ let traverse = (
     pageFooter,
     margin,
     required,
+    slotted,
   };
 };
 

package/lib/scope.js

@@ -17,6 +17,13 @@ import { REDUCERS, runnerFor } from "./reducers.js";
  *   bind: (scope: Scope, row: any) => Scope }} RunnerSet
  */
 
+// Where a render parks the values its resolve wave settled: a Map from row to
+// that row's supplies, keyed by cell path (docs/adr/0088). It sits on the
+// render base, so every scope under it inherits the one object and a cell that
+// holds no slot never looks. A symbol, so it cannot collide with an author's
+// name and never reaches an expression.
+export let RESOLVED = Symbol("quario.resolved");
+
 // Bind a row as `@` on a child of `scope`, ready for an xprsn per-row read.
 /** @type {(scope: Scope, row: any) => Scope} */
 export let withRow = (scope, row) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Tiny, CSP-safe report engine for JavaScript. One JSON document renders to HTML, PDF, XLSX, CSV and Word.",
   "keywords": [
     "csp",
@@ -43,12 +43,12 @@
   },
   "dependencies": {
     "padvinder": "^0.9.0",
-    "sjabloon": "^0.13.0",
-    "xprsn": "^0.11.1"
+    "sjabloon": "^0.14.0",
+    "xprsn": "^0.12.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
-    "@size-limit/preset-small-lib": "^13.0.3",
+    "@size-limit/preset-small-lib": "^13.1.1",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
@@ -60,7 +60,7 @@
         "sjabloon",
         "padvinder"
       ],
-      "limit": "15.3 kB"
+      "limit": "16.2 kB"
     }
   ],
   "engines": {