quario 0.6.0 → 0.8.0

package/lib/format.js

@@ -17,6 +17,7 @@
  * carries no count presents nothing here and the caller falls back to
  * `display()`.
  */
+import { boundedMemo } from "./memo.js";
 import { currencyOf, formatOf } from "./style.js";
 import { finiteDate, finiteNum, reviveDate } from "./stream.js";
 /** @type {(options: any) => string} */
@@ -24,11 +25,9 @@ let localeOf = (options) => options?.locale || "en-US";
 /** @type {(options: any) => string} */
 let zoneOf = (options) => options?.timeZone || "UTC";
 
-// Building an `Intl` formatter costs about 22 µs; using one costs 0.3 µs. A
-// report presents cell after cell from a handful of distinct formats, so
-// constructing per token spent 3.2 s on a hundred thousand presented cells
-// where 0.2 s does (a report of mixed currencies rendered to HTML), and the
-// formatters are memoised.
+// The formatters are memoised behind `./memo.js`'s bounded store, which
+// carries the rules a bounded memo has; what is here is what only this call
+// site knows -- its key, and its cap.
 //
 // **The key is everything the formatter is made from**, and it is values
 // rather than an object identity because no identity survives both paths: a
@@ -48,12 +47,6 @@ let zoneOf = (options) => options?.timeZone || "UTC";
 // single locale. Measured at 244 bytes retained per entry, that is about 90 MB
 // held for the life of the process on data nobody vetted.
 //
-// So the map is bounded, and past the bound it is emptied rather than grown.
-// A workload presenting more distinct formats than the cap pays what it paid
-// before any of this and never more, which is the one cost that needs no
-// argument -- and it can never hand back a formatter built for another cell,
-// because clearing forgets rather than reuses.
-//
 // 2048 leaves the margin a threshold like this wants on both sides: about
 // 500 KB at the cap, against a real report reaching a small multiple of the
 // ISO codes actually in circulation, which is under two hundred. Raising it
@@ -62,23 +55,7 @@ let zoneOf = (options) => options?.timeZone || "UTC";
 //
 // Memoising a fact that cannot change within an ICU version, like
 // `fractionDigits`' own minor-units map (docs/adr/0025).
-let CAP = 2048;
-/** @type {Map<string, any>} */
-let formatters = new Map();
-// A construction that throws -- an unreadable locale, zone, or currency code
-// -- caches nothing: it reaches `format()`'s own catch, and a later cell asks
-// again rather than finding nothing sitting in the map under a good key.
-// Missing on `undefined` rather than `has()`, which is what `precision.js`
-// needs because *it* caches an absent answer; a formatter is never one.
-/** @type {(key: string, make: () => any) => any} */
-let memo = (key, make) => {
-  let formatter = formatters.get(key);
-  if (formatter !== undefined) return formatter;
-  formatter = make();
-  if (formatters.size >= CAP) formatters.clear();
-  formatters.set(key, formatter);
-  return formatter;
-};
+let memo = boundedMemo(2048);
 
 // The kind leads, so a number's key can never read as a date's; the currency
 // is empty for the two kinds that wear none.

package/lib/image.js

@@ -0,0 +1,92 @@
+/**
+ * What the engine reads out of an image item's bytes: which format they are,
+ * and how big the picture is. Read, never decoded -- a magic number, a PNG's
+ * IHDR and a JPEG's frame header, and nothing here looks at a pixel.
+ *
+ * Both answers ride on the image event, so no target reads these headers
+ * again. That is the whole of `docs/adr/0067`: two targets used to keep a
+ * parser each, in different units and with the same bug, and the engine was
+ * already in these bytes to name the format.
+ */
+
+// The two raster formats an image item may carry, as the bytes announce
+// themselves: PNG's 8-byte signature and JPEG's start-of-image marker. Read,
+// never decoded -- the engine answers which format the bytes are, not what
+// they depict.
+let PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+let JPEG = [0xff, 0xd8, 0xff];
+
+/**
+ * The image seam: name the format a `source` expression's bytes hold, or null
+ * when they are not image bytes at all -- including when they are not bytes.
+ * The traversal sniffs once per image event and the answer rides on the event,
+ * so no consumer repeats it.
+ *
+ * @param {any} bytes The value a `source` expression yielded.
+ * @returns {"png" | "jpeg" | null} The format, or null when unreadable.
+ */
+export function sniff(bytes) {
+  if (!(bytes instanceof Uint8Array)) return null;
+  if (PNG.every((byte, i) => bytes[i] === byte)) return "png";
+  if (JPEG.every((byte, i) => bytes[i] === byte)) return "jpeg";
+  return null;
+}
+
+/** @type {(bytes: Uint8Array, at: number) => number} */
+let word = (bytes, at) => (bytes[at] << 8) | bytes[at + 1];
+
+// A PNG states each dimension in four bytes, so two words make one number.
+/** @type {(bytes: Uint8Array, at: number) => number} */
+let long = (bytes, at) => word(bytes, at) * 0x10000 + word(bytes, at + 2);
+
+// The three codes in C0..CF that are not frame headers: DHT, the JPG
+// extension, and DAC. Named as a set so the frame test is one range and one
+// lookup rather than a chain of exclusions.
+let NOT_FRAME = new Set([0xc4, 0xc8, 0xcc]);
+
+// The dimensions live in the frame header, which is the first SOFn marker.
+// SOF2 is a frame like SOF0, so a progressive file is read like a baseline one.
+/** @type {(code: number) => boolean} */
+let isFrame = (code) => code >= 0xc0 && code <= 0xcf && !NOT_FRAME.has(code);
+
+// A PNG carries the two numbers in its IHDR at a fixed offset.
+/** @type {(bytes: Uint8Array) => { width: number, height: number } } */
+let pngSize = (bytes) => ({ width: long(bytes, 16), height: long(bytes, 20) });
+
+/** @type {(bytes: Uint8Array) => { width: number, height: number } } */
+let jpegSize = (bytes) => {
+  for (let at = 2; at + 9 < bytes.length; at += 2 + word(bytes, at + 2)) {
+    if (bytes[at] !== 0xff) break;
+    if (isFrame(bytes[at + 1])) return { width: word(bytes, at + 7), height: word(bytes, at + 5) };
+  }
+  return { width: 0, height: 0 };
+};
+
+// One reader per format `sniff` names.
+/** @type {Record<string, (bytes: Uint8Array) => { width: number, height: number }>} */
+let READERS = { png: pngSize, jpeg: jpegSize };
+
+/**
+ * The image's own size in pixels, or null when the header does not carry one
+ * -- bytes whose magic numbers `sniff` vouched for, truncated before the
+ * dimensions. Read, never decoded: a PNG's IHDR and a JPEG's frame header
+ * carry the two numbers, and nothing here looks at a pixel.
+ *
+ * The size rides on the image event beside the format, so every target places
+ * a picture from a field rather than parsing the same two headers again, and a
+ * file too short to state its size fails once, in the engine, for every target
+ * alike (`docs/adr/0067`).
+ *
+ * @param {Uint8Array} bytes The image file.
+ * @param {"png" | "jpeg"} format The format `sniff` named.
+ * @returns {{ width: number, height: number } | null} The size, if readable.
+ */
+export function dimensions(bytes, format) {
+  // Keyed rather than a ternary so the format list lives in one place: a
+  // format `sniff` learns later and this table does not would throw here
+  // rather than be read silently as the one on the ternary's else branch.
+  let size = READERS[format](bytes);
+  // A zero is how either reader says "the header stopped before this" -- an
+  // absent byte reads as zero, and no image is zero wide.
+  return size.width > 0 && size.height > 0 ? size : null;
+}

package/lib/index.d.ts

@@ -118,8 +118,52 @@ export interface SortKey {
   dir?: "asc" | "desc";
 }
 
-/** A cell value: one template string. */
-export type CellValue = string;
+/**
+ * The names a styled run may wear, in the vocabulary's own order. A tool that
+ * offers them — the editor's style rail — reads this rather than keeping a
+ * copy, exactly as it reads `STYLE_NAMES` for the whole set.
+ */
+export const RUN_STYLE_NAMES: readonly string[];
+
+/**
+ * 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`
+ * describes a line, and neither means anything on part of one — so a run is
+ * narrowed from the other end than an image item is. A narrowing of the one
+ * vocabulary rather than a second list of its own, so the two cannot drift.
+ */
+export type RunStyleDeclarations = Pick<
+  StyleDeclarations,
+  | "family"
+  | "size"
+  | "bold"
+  | "italic"
+  | "underline"
+  | "strikethrough"
+  | "color"
+  | "background"
+  | "uppercase"
+  | "format"
+  | "currency"
+>;
+
+/**
+ * One styled run: a stretch of a cell's text with its own declarations. A
+ * closed two-key object — `{{#if}}` already conditions a run's own text, so
+ * there is no `visible` on one.
+ */
+export interface StyledRun {
+  value: string;
+  /** Literal only — never an expression. */
+  style?: RunStyleDeclarations;
+}
+
+/**
+ * A cell value: one template string, or a non-empty array of styled runs. A
+ * cell written as one template string is one run, so a one-run array says
+ * exactly what that string says.
+ */
+export type CellValue = string | StyledRun[];
 
 export type Align = "left" | "center" | "right";
 export type VAlign = "top" | "middle" | "bottom";
@@ -194,8 +238,12 @@ export interface ImageItem {
   source: `=${string}`;
   /** Defaults to `"natural"`. */
   fit?: ImageFit;
-  /** The image's textual stand-in, as a cell value. */
-  alt?: CellValue;
+  /**
+   * The image's textual stand-in: one template string. A styled run means
+   * nothing on a stand-in for a picture, so this is the one cell value the
+   * widened type does not reach.
+   */
+  alt?: string;
   visible?: ExpressionValue<boolean>;
   style?: ImageStyleDeclarations;
 }
@@ -445,14 +493,55 @@ export type ItemRole =
   | "page-header"
   | "page-footer";
 
+/**
+ * The resolved declarations for one stretch of a cell's text: the cell's own
+ * with its styled run's layered over them, already composed, so a consumer
+ * applies it exactly where it applies the cell's `style` rather than merging
+ * the two. Present only where it differs from the cell's own.
+ */
+export interface TokenStyle {
+  style?: Record<string, unknown>;
+}
+
 /** One static text run of a cell's template, verbatim (sjabloon's literal token). */
-export type LiteralToken = SjabloonLiteralToken;
+export type LiteralToken = SjabloonLiteralToken & TokenStyle;
+
+/** Which page value a token *is*, on the two whose interpolation says so. */
+export type PageField = "page.number" | "page.total";
 
-/** One interpolation's pre-stringify value (sjabloon's value token). */
-export type ValueToken = SjabloonValueToken;
+/**
+ * One interpolation's pre-stringify value (sjabloon's value token).
+ *
+ * `field` is present where the interpolation is exactly `{{ page.number }}` or
+ * `{{ page.total }}`. The value is unchanged -- the number this render saw --
+ * and `field` says which page value the token stands for, so a target whose
+ * own document format numbers pages writes a live field there instead
+ * (SCHEMA.md, "Page bands"). Anything computed from a page value carries no
+ * `field`, and a target that paginates itself, or not at all, ignores the key.
+ */
+export type ValueToken = SjabloonValueToken & TokenStyle & { field?: PageField };
 
 export type Token = LiteralToken | ValueToken;
 
+/** One of a cell's styled runs, as `styledRuns` groups them back out. */
+export interface TokenRun {
+  /** The style this run's tokens carry, or `null` where the cell's applies. */
+  style: Record<string, unknown> | null;
+  tokens: Token[];
+}
+
+/**
+ * Group a cell's tokens into its styled runs, in order. Consecutive tokens
+ * with equal styles are one run — a lossless rule, because equal styles render
+ * identically, so grouping survives a JSON round trip. Equality is compared
+ * one level deep, which is exhaustive rather than approximate: `format` is the
+ * only object-valued declaration and is itself flat.
+ *
+ * The built-in targets consume it, so a custom target grouping through it
+ * cannot drift from them.
+ */
+export function styledRuns(tokens: Token[]): TokenRun[];
+
 export interface EventCell {
   tokens: Token[];
   style?: Record<string, unknown>;
@@ -552,6 +641,14 @@ export interface ImageEvent {
   bytes: Uint8Array;
   /** Sniffed from the bytes' magic numbers, so no consumer repeats it. */
   format: ImageFormat;
+  /**
+   * The image's own width in pixels, read from the same header. Bytes too
+   * short to state a size never reach a target: that is a render error on
+   * every target alike.
+   */
+  width: number;
+  /** The image's own height in pixels, read from the same header. */
+  height: number;
   fit: ImageFit;
   /** The rendered `alt` template, present when the item declares one. */
   alt?: Token[];
@@ -744,17 +841,35 @@ export interface Problem {
   readonly diagnostic?: QuarioDiagnostic;
 }
 
+/**
+ * An advisory: the document declares something nothing will read. Not a
+ * `Problem` at lower severity, and not its shape either — a problem carries
+ * the engine's located `diagnostic` when one authenticated the fault, and a
+ * `source` when it came from compiling one. Neither can happen here: nothing
+ * raises, and the engine decides a declaration will not be read after every
+ * compile has already succeeded. A warning that did locate into an authored
+ * source would add the field back; carrying one nothing sets would promise a
+ * location that never arrives.
+ */
+export interface Warning {
+  readonly path: string;
+  readonly message: string;
+}
+
 /**
  * The plan: both readings of the one traversal, kept. `report` is the
  * compiled report, or null while the document has problems; `problems` is the
- * structured list `validate()` flattens to strings; `anchors` maps each
- * compiled source's schema path to the anchors and group handles it reads —
- * the unfiltered complement of `names`, which excludes them.
+ * structured list `validate()` flattens to strings; `warnings` is the advisory
+ * half, which never nulls the report; `anchors` maps each compiled source's
+ * schema path to the anchors and group handles it reads — the unfiltered
+ * complement of `names`, which excludes them. `problems` is fatal and
+ * `warnings` is advisory, both in document order from the one descent.
  */
 export interface Plan {
   readonly report: CompiledReport | null;
   readonly problems: readonly Problem[];
   readonly anchors: Readonly<Record<string, readonly string[]>>;
+  readonly warnings: readonly Warning[];
 }
 
 export interface Quario {
@@ -767,8 +882,8 @@ export interface Quario {
   report(schema: ReportSchema, functions?: FunctionRegistry): CompiledReport;
   /**
    * The one traversal, whole: compiled report (null on problems), structured
-   * problems, and per-node anchor sets — one descent per edit for a host that
-   * validates and renders in a loop.
+   * problems, advisory warnings, and per-node anchor sets — one descent per
+   * edit for a host that validates and renders in a loop.
    */
   plan(schema: unknown, functions?: FunctionRegistry): Plan;
 }

package/lib/index.js

@@ -24,9 +24,15 @@ 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, display, isReportBand, text, typed, walk } from "./stream.js";
+export { breathe, display, isReportBand, styledRuns, text, typed, walk } from "./stream.js";
 export { format } from "./format.js";
-export { currencyOf, FORMAT_VOCABULARY, fractionDigits, STYLE_NAMES } from "./style.js";
+export {
+  currencyOf,
+  FORMAT_VOCABULARY,
+  fractionDigits,
+  RUN_STYLE_NAMES,
+  STYLE_NAMES,
+} from "./style.js";
 export { imageError, isDiagnostic } from "./locate.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */
@@ -89,11 +95,13 @@ export function validate(schema, funcs) {
   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 structured problems and warnings, 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. One helper for both lists, because a warning is a
+// problem's shape less the field that cannot occur on one.
+/** @type {(entries: any[]) => readonly any[]} */
+let freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
 
 // 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.
@@ -333,8 +341,9 @@ export function quario(options) {
       let planned = plan(schema, funcs, options);
       return {
         report: planned.problems.length ? null : wrap(assemble(planned, schema, marking, options)),
-        problems: freezeProblems(planned.problems),
+        problems: freezeEntries(planned.problems),
         anchors: freezeAnchors(planned.anchors),
+        warnings: freezeEntries(planned.warnings),
       };
     },
   };

package/lib/license.js

@@ -5,13 +5,13 @@
 // Verification is entirely offline, and asynchronous only because WebCrypto
 // is.
 
-// Release date of this version, written into the version commit by
-// release-please (`x-release-please-date`). Both constants keep the `let`
-// spelling that `scripts/license/keygen.mjs` matches on, though nothing
-// reassigns them. A key is valid for every version released inside its window
+// Release date of this version, written into the Version PR's commit by
+// `scripts/stamp-release-date.mjs` (the `release-date` mark). Both constants
+// keep the `let` spelling that `scripts/license/keygen.mjs` matches on,
+// though nothing 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-09-07"; // x-release-please-date
+let RELEASE = "2026-09-14"; // release-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/math.js

@@ -15,17 +15,44 @@
  * table, is in docs/adr/0050. The locale is hardcoded `en-US` rather than the
  * instance's: this is arithmetic, not presentation, and a locale with
  * non-ASCII digits or its own grouping would not parse back through `Number`.
- * Formatters are built per call, deliberately -- see the ADR.
  */
+import { boundedMemo } from "./memo.js";
+
+// The formatters are memoised behind `./memo.js`, the same seam `format()`
+// uses -- one bounded store each, not one between them. ADR 0050 declined this
+// cache and records why the decline expired; what is here is what only this
+// call site knows, its key and its cap.
+//
+// **The key is the mode and the count**, which is all that varies: the locale
+// and `useGrouping` are constants here rather than configuration, precisely so
+// the answer parses back through `Number`, so they are not in it. The mode
+// leads, as the kind does in `format()`'s key, and the two shapes read the
+// same way. Drop either piece and a `floor` presents a `round`'s answer, or a
+// three-digit call presents two -- pinned a piece at a time in
+// `test/frozen.test.js`.
+//
+// **The cap is unreachable, and that is the point of stating it.** `places`
+// admits 0 to 100 and there are three modes, so this store holds at most 303
+// entries however hostile the data is -- `n` may be an `=` result, but it
+// cannot be an unbounded one. 512 is headroom over that rather than a
+// threshold: if the admitted range ever widened, the store would empty and
+// rebuild rather than grow without limit, which is the same degradation
+// `format()`'s cap buys and no correctness knob either way.
+let memo = boundedMemo(512);
+
 /** @type {(x: number, n: number, mode: string) => number} */
 let decimal = (x, n, mode) =>
   Number(
-    new Intl.NumberFormat("en-US", {
-      minimumFractionDigits: n,
-      maximumFractionDigits: n,
-      useGrouping: false,
-      roundingMode: /** @type {any} */ (mode),
-    }).format(x),
+    memo(
+      mode + "|" + n,
+      () =>
+        new Intl.NumberFormat("en-US", {
+          minimumFractionDigits: n,
+          maximumFractionDigits: n,
+          useGrouping: false,
+          roundingMode: /** @type {any} */ (mode),
+        }),
+    ).format(x),
   );
 // The one test both halves make of `x`. Named because the rule it stands for
 // is the interesting part: rounding a value that is not a finite number would
@@ -47,16 +74,36 @@ let honourable = (digits) => Number.isFinite(digits) && digits >= 0 && digits <=
 // `maximumFractionDigits`, an option the author never wrote, so the message is
 // ours. Fractional `n` truncates rather than throwing, which is what Intl does
 // with it and is not worth a second rule for an author to hold.
-/** @type {(n: any) => number} */
-let places = (n) => {
-  let digits = Math.trunc(+(n ?? 0));
-  if (!honourable(digits)) throw new RangeError("n must be a number from 0 to 100");
+/** @type {(fn: string, n: any) => number} */
+let places = (fn, n) => {
+  let digits = NaN;
+  // `+` is the other way `n` fails, and it used to fail rawly: a BigInt or a
+  // Symbol makes the coercion throw a TypeError of its own, and an object
+  // carrying a hostile `valueOf` throws whatever it likes. Each arrived
+  // located at the cell and naming nothing -- the very fault this rule closes
+  // -- and render data may be untrusted (SCHEMA.md, "Trust and Content
+  // Security Policy"), so an `n` that cannot even be read is folded into the
+  // one answer an author can act on rather than surfacing V8's.
+  try {
+    digits = Math.trunc(+(n ?? 0));
+  } catch {
+    digits = NaN;
+  }
+  if (!honourable(digits)) throw new RangeError(fn + "'s n must be a number from 0 to 100");
   return digits;
 };
 
-/** @type {(mode: string) => (x: any, n: any) => any} */
-let rounder = (mode) => (x, n) => {
-  let digits = places(n);
+// The name is threaded rather than prefixed by a wrapper around the registry.
+// `places` is the only place a built-in refuses an argument -- `abs` and the
+// folds never do -- so a catch on every built-in call would exist to serve one
+// function's messages. A mechanical prefix would also cost both halves their
+// own sentence: a reducer names itself inside its (`min is a reducer over an
+// array`) where a scalar names an argument it owns (`round's n`), and a
+// uniform `name: ` joiner fits neither without rewriting the other
+// (quario-gr4h).
+/** @type {(fn: string, mode: string) => (x: any, n: any) => any} */
+let rounder = (fn, mode) => (x, n) => {
+  let digits = places(fn, n);
   return finite(x) ? decimal(x, digits, mode) : x;
 };
 /** @type {Record<string, (...args: any[]) => any>} */
@@ -64,8 +111,8 @@ export let MATH = {
   // Written `(x, n)` rather than `(x, n = 0)` on purpose: xprsn's signatures()
   // reports arity from `fn.length`, and a default parameter would describe
   // these to an editor as taking one argument.
-  round: rounder("halfExpand"),
-  floor: rounder("floor"),
-  ceil: rounder("ceil"),
+  round: rounder("round", "halfExpand"),
+  floor: rounder("floor", "floor"),
+  ceil: rounder("ceil", "ceil"),
   abs: (x) => (finite(x) ? Math.abs(x) : x),
 };

package/lib/memo.js

@@ -0,0 +1,49 @@
+/**
+ * The bounded store the engine's `Intl` call sites are memoised behind.
+ *
+ * Building an `Intl` formatter costs about 20 µs and using one costs about
+ * 0.4 µs, so every path that builds one per call spends fifty times what it
+ * needs to. Two do: `./format.js` presents a token at the markup edge, and
+ * `./math.js` reaches a decimal through a formatter's `roundingMode`
+ * (docs/adr/0050). One rule, stated once, rather than the same six lines
+ * twice.
+ *
+ * **A factory, so each site owns its store.** One shared map would let a
+ * report turning over thousands of currency formatters evict the three a
+ * rounder ever holds, which is the caller with no unbounded key space paying
+ * for the caller that has one. The cap is passed rather than fixed here for
+ * the same reason: it is a claim about a key space, and only the call site
+ * knows what its keys are made of.
+ *
+ * **Past the cap the store is emptied rather than grown.** A workload with
+ * more distinct keys than the cap pays what it paid before any of this and
+ * never more, and it can never be handed a value built for another key,
+ * because clearing forgets rather than reuses.
+ *
+ * **The seam is the store, not the key.** The two keys have no shape in
+ * common -- four pieces off a resolved style declaration against a rounding
+ * mode and a count -- so a shared builder would be a joiner both callers
+ * already have in `+`, and it would put the piece that decides correctness a
+ * module away from the site that knows what the pieces are. They were
+ * designed together and each says so; nothing else about them is shared.
+ *
+ * **A `make` that throws caches nothing.** It reaches the caller's own catch
+ * and a later call asks again, rather than finding nothing sitting under a
+ * good key. That is why a miss is `undefined` rather than `has()`:
+ * `./precision.js` deliberately caches an *absent* answer and so needs
+ * `has()`, which is why it is not on this seam.
+ */
+
+/** @type {(cap: number) => (key: string, make: () => any) => any} */
+export let boundedMemo = (cap) => {
+  /** @type {Map<string, any>} */
+  let store = new Map();
+  return (key, make) => {
+    let value = store.get(key);
+    if (value !== undefined) return value;
+    value = make();
+    if (store.size >= cap) store.clear();
+    store.set(key, value);
+    return value;
+  };
+};