hbengine 0.2.3 → 0.4.0

package/engine-conformance/scan.mjs

@@ -16,10 +16,11 @@
  * rules (CSP, base, refresh, object/embed, srcdoc, outside URLs) that a tag
  * walk serves as well as a parser would.
  */
-import { closeSync, lstatSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs';
+import { closeSync, lstatSync, openSync, readdirSync, readFileSync, readSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { Worker } from 'node:worker_threads';
-import { join, relative, extname, posix } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { join, relative, extname, posix, sep } from 'node:path';
 import { checkAssetManifest } from '../engine-sdk/assets.js';
 import { RULES } from './analyse.mjs';
 
@@ -52,6 +53,9 @@ const GZIP_TIMEOUT = 120 * 1000;
 // files, Kraken half a second. A bundle whose code is still being read at the
 // deadline is refused unread.
 const ANALYSE_TIMEOUT = 120 * 1000;
+// When the analysis runs out of time, what can be told from syntax alone
+// (minified files, their source maps) gets this long: a parse, milliseconds.
+const CENSUS_TIMEOUT = 30 * 1000;
 
 const TEXT = new Set(['.html', '.htm', '.js', '.mjs', '.css', '.json', '.svg', '.xml', '.xhtml', '.xsl', '.xslt', '.txt']);
 // The languages the site ships (arbitrium-frontend apps/web/messages).
@@ -99,13 +103,21 @@ const FORBIDDEN_MARKUP = [
 // (no eval, connect-src self, base-uri none, no plugins) is the law, and the
 // run proves the bets reach the engine.
 
-// Libraries a studio ships under vendor/ that we know by name. A file named
-// like one, carrying the banner its releases carry in the first 4 KB, is read
-// as that library: what the analyser would refuse in it is named for the
-// reviewer instead (the browser's policy blocks it at run time, and the run
-// proves the game works without it), and its being minified is expected.
-// Anything else under vendor/ is the game's own code to the scan. A studio
-// with another library asks us to add it here.
+// Libraries a studio ships under vendor/. A file there is read as a library
+// only when its bytes are a release's as published (KNOWN_JS, by SHA-256,
+// js-releases.json): what the analyser would refuse in it is then named for
+// the reviewer instead (the browser's policy blocks it at run time, and the
+// run proves the game works without it), its being minified is expected, and
+// the game's own code does not follow values into it (bundle.mjs, the pool).
+// Anything else under vendor/ is the game's own code to the scan, whatever its
+// name or banner. A studio with another library or release asks us to add it
+// (js-releases.mjs).
+export const KNOWN_JS = new Map(Object.entries(JSON.parse(readFileSync(new URL('./js-releases.json', import.meta.url), 'utf8')).files));
+
+// The libraries we know by name: a vendor/ file named like one, carrying the
+// banner its releases carry in the first 4 KB, claims to be it. A claim alone
+// makes nothing a library (KNOWN_JS does); a file that claims one and is not
+// one of its releases is named for review (unreleased-library).
 export const KNOWN_LIBRARIES = [
     { name: 'PixiJS', file: /^(?:pixi|unsafe-eval|pixi-[\w.-]+)(?:[.-][\w.-]*)?\.m?js$/i, banner: /pixi\.?js/i },
     { name: 'howler.js', file: /^howler(?:[.-][\w.-]*)?\.m?js$/i, banner: /howler/i },
@@ -137,7 +149,9 @@ const BANNER_BYTES = 4096;
 // A scheme is a word of its own: `--turn:180deg` (a CSS custom property) and
 // `.turn:hover` (a class) are not TURN server addresses, so a scheme preceded
 // by a word character, `-`, `.` or `#` is not one.
-const URL_RE = /(?<![\w.#-])(?:https?|wss?|stuns?|turns?):\/?\/?[^\s"'`)<>]+/g;
+// A STUN/TURN address names a dotted host (turn:relay.example.com, turn:1.2.3.4): an object's
+// `{turns: 1}` or `turns:1` in minified code is not one.
+const URL_RE = /(?<![\w.#-])(?:(?:https?|wss?):\/?\/?[^\s"'`)<>]+|(?:stuns?|turns?):(?:\/\/)?[\w-]+\.[^\s"'`)<>]*)/g;
 // Hosts that appear in markup as identifiers, not as network destinations.
 const URL_IGNORE = /^https?:\/\/(www\.w3\.org|schema\.org|xmlns\.com)\//;
 
@@ -155,7 +169,7 @@ function walk(dir, root = dir, out = []) {
         const p = join(dir, name);
         const st = lstatSync(p);
         if (st.isDirectory()) walk(p, root, out);
-        else out.push({ path: relative(root, p), abs: p, bytes: st.size, link: st.isSymbolicLink() });
+        else out.push({ path: relative(root, p).split(sep).join('/'), abs: p, bytes: st.size, link: st.isSymbolicLink() });
     }
     return out;
 }
@@ -179,6 +193,8 @@ const gzipSizes = (paths, timeout) => onWorker('./gzip-sizes.mjs', paths, timeou
 // The analyser's findings per code file (analyse-worker.mjs). The thread's heap
 // is bounded: a 4 MB file's syntax tree is tens of megabytes, not a gigabyte.
 const analyseFiles = (files, timeout) => onWorker('./analyse-worker.mjs', { files }, timeout, 'analysing the code', { maxOldGenerationSizeMb: 1024 });
+// The quick census of the scripts (census-worker.mjs), when the analysis did not finish.
+const censusFiles = (files, timeout) => onWorker('./census-worker.mjs', { files }, timeout, 'counting the names', { maxOldGenerationSizeMb: 1024 });
 
 // Does this HTML frame another page of the bundle (an <iframe>, <frame>,
 // <embed> or <object> whose src/data is a relative .html address)? A tag walk,
@@ -218,9 +234,16 @@ function head(abs) {
     } finally { closeSync(fd); }
 }
 
-// Which known library a vendor/ file is, by its name and the banner in its
-// head; null for anything else.
-export function recognisedLibrary(path, head) {
+// Which known library a vendor/ file is, by the SHA-256 of its bytes (a
+// release as published: KNOWN_JS); null for anything else.
+export function recognisedLibrary(path, sha) {
+    if (!path.startsWith('vendor/')) return null;
+    return KNOWN_JS.get(sha)?.library ?? null;
+}
+
+// Which known library a vendor/ file claims to be, by its name and the banner
+// in its head; null for none.
+export function claimedLibrary(path, head) {
     if (!path.startsWith('vendor/')) return null;
     const base = posix.basename(path);
     const lib = KNOWN_LIBRARIES.find((l) => l.file.test(base));
@@ -382,9 +405,39 @@ export async function scan(dir, { gzipTimeout = GZIP_TIMEOUT, analyseTimeout = A
     const code = files.filter((f) => !f.link && ((CODE.has(ext(f)) && f.bytes <= BUDGETS.codeBytes) || (XML_PAGES.has(ext(f)) && f.bytes <= BUDGETS.fileBytes) || isData(f)));
     const kind = (f) => (XML_PAGES.has(ext(f)) ? 'xml' : MARKUP.has(ext(f)) ? 'html' : CODE.has(ext(f)) ? 'script' : 'data');
     let analysed = [];
-    try { analysed = await analyseFiles(code.map((f) => ({ path: f.path, abs: f.abs, kind: kind(f) })), analyseTimeout); }
-    catch (e) { add('fail', 'analyser', `${RULES.analyser.text}: ${e.message}`); }
-    const library = new Map(code.map((f) => [f.path, recognisedLibrary(f.path, f.path.startsWith('vendor/') ? head(f.abs) : '')]));
+    let unfinished = false;
+    // A recognised library (a release's bytes) is read on its own: the game's
+    // code does not follow values into it (bundle.mjs, the pool). A vendor/
+    // file that claims a library by its name and banner without being one of
+    // its releases is the game's code, and named for review.
+    const library = new Map();
+    for (const f of code) {
+        if (!f.path.startsWith('vendor/') || !CODE.has(ext(f))) continue;
+        const sha = sha256(f.abs);
+        const lib = recognisedLibrary(f.path, sha);
+        if (lib) { library.set(f.path, lib); continue; }
+        const claim = claimedLibrary(f.path, head(f.abs));
+        if (claim) add('warn', 'unreleased-library', `${RULES['unreleased-library'].text}: named and bannered like ${claim}, sha256 ${sha}`, f.path);
+    }
+    try { analysed = await analyseFiles(code.map((f) => ({ path: f.path, abs: f.abs, kind: kind(f), library: library.get(f.path) })), analyseTimeout); }
+    catch (e) { unfinished = true; add('fail', 'analyser', `${RULES.analyser.text}: ${e.message}`); }
+    // The analysis did not finish: what the studio can act on is still told
+    // (the reason it usually does not: minified files without their source
+    // maps, libraries shipped as bundle chunks that are read as the game's
+    // own code), so the report is never only "it took too long".
+    if (unfinished) {
+        const scripts = code.filter((f) => kind(f) === 'script');
+        try {
+            for (const c of await censusFiles(scripts.map((f) => ({ path: f.path, abs: f.abs })), CENSUS_TIMEOUT)) {
+                if (library.get(c.path) || !c.minified) continue;
+                const problem = minifiedProblem(c.path, c.sourceMappingURL, byPath);
+                if (problem) add('fail', 'minified', `${RULES.minified.text}: ${c.short} of ${c.names} names are one or two letters; ${problem}`, c.path);
+            }
+        } catch { /* the analyser's own refusal already stands */ }
+        for (const f of scripts) {
+            if (f.path.startsWith('vendor/') && !library.get(f.path)) add('warn', 'unknown-library', RULES['unknown-library'].text, f.path);
+        }
+    }
     // A WebAssembly module is a program the analyser cannot read. One whose
     // bytes are a known library's release (KNOWN_WASM, by SHA-256) is named for
     // the reviewer, like the rest of what that library would be refused for;
@@ -463,7 +516,7 @@ export async function scan(dir, { gzipTimeout = GZIP_TIMEOUT, analyseTimeout = A
 const mb = (b) => (b / 1024 / 1024).toFixed(1);
 const kb = (b) => Math.round(b / 1024);
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
     const dir = process.argv[2];
     if (!dir) { console.error('usage: scan.mjs <bundle-dir> [--json]'); process.exit(2); }
     const r = await scan(dir);

package/engine-conformance/sound.mjs

@@ -0,0 +1,45 @@
+// The sound rule of the conformance run (run.mjs): nothing plays before the
+// player's first tap, and the game gives a way to mute it.
+//
+// soundProbe runs in every frame of the game (its text is put in the init
+// script, as the rest of the instrumentation): it wraps what starts a sound,
+// a media element's play() unmuted and a Web Audio source's start(), and says
+// once per kind and phase whether the frame had been touched yet (its user
+// activation). soundVerdict turns what was said, and the label of a control
+// found, into the run's check.
+
+export const soundProbe = (scope, say) => {
+    const said = new Set();
+    const sound = (what) => {
+        let active = false;
+        try { active = !!(scope.navigator.userActivation && scope.navigator.userActivation.hasBeenActive); } catch { /* no activation API: counted as before */ }
+        const key = (active ? 'after:' : 'before:') + what;
+        if (!said.has(key)) { said.add(key); say(key); }
+    };
+    const media = scope.HTMLMediaElement && scope.HTMLMediaElement.prototype;
+    if (media && typeof media.play === 'function') {
+        media.play = new Proxy(media.play, { apply(t, self, a) { try { if (!self.muted && self.volume > 0) sound('media'); } catch { /* a detached element */ } return Reflect.apply(t, self, a); } });
+    }
+    const source = scope.AudioScheduledSourceNode && scope.AudioScheduledSourceNode.prototype;
+    if (source && typeof source.start === 'function') {
+        source.start = new Proxy(source.start, { apply(t, self, a) { sound('webaudio'); return Reflect.apply(t, self, a); } });
+    }
+};
+
+// What a control that mutes is called: its label, title or text.
+export const SOUND_CONTROL = /\b(mute|unmute|sound|audio|volume|music)\b/i;
+
+// soundControls lists, in a frame, the labels of the controls that look like a
+// sound control (run in the page; SOUND_CONTROL given as its source).
+export const soundControls = (pattern) => [...document.querySelectorAll('button, [role=button], [role=switch], input, a, [aria-label], [title]')]
+    .map((e) => [e.getAttribute('aria-label'), e.getAttribute('title'), e.textContent].filter(Boolean).join(' ').trim())
+    .filter((t) => new RegExp(pattern, 'i').test(t)).slice(0, 1);
+
+// soundVerdict: a fail for sound before the first tap; a warning when no
+// control to mute it was found; else a pass.
+export function soundVerdict(said, control) {
+    const early = [...new Set(said.filter((x) => x.startsWith('before:')).map((x) => x.slice(7)))];
+    if (early.length) return { ok: false, detail: `sound started before the player's first tap (${early.join(', ')})` };
+    if (control) return { ok: true, detail: `no sound before the first tap; a sound control is there ("${control.slice(0, 40)}")` };
+    return { ok: true, detail: 'no sound before the first tap; no control labelled mute or sound was found: check the game can be muted', status: 'warning' };
+}

package/engine-conformance/travel.mjs

@@ -68,9 +68,34 @@ export const CANARY_VARIANTS = Object.freeze(['base', 'plus1d', 'plus7d', 'plus3
 /** The screenshot a variant writes after boot, as the job uploads it and the studio keeps it. */
 export const shotName = (id) => `travel-${id}.png`;
 /** The screenshot a short variant writes after a day of game time, kept when it differs. */
+export const failureShotName = (id) => `travel-${id}-failure.png`;
 export const lateShotName = (id) => `travel-${id}-late.png`;
 /** Every screenshot name a set of variants may write (what the studio signs for). */
-export const shotNames = (variants) => variants.flatMap((v) => (v.rounds ? [shotName(v.id)] : [shotName(v.id), lateShotName(v.id)]));
+/**
+ * The long session's outcome screenshots: one after each of the first rounds
+ * whose forced row is new (a loss, then each pay tier, lowest first), at most
+ * OUTCOME_SHOTS, for the reviewer to compare what the screen shows with what
+ * the maths pays.
+ */
+export const OUTCOME_SHOTS = 8;
+export const outcomeShotName = (k) => `outcome-${k}.png`;
+export const outcomeShotNames = () => Array.from({ length: OUTCOME_SHOTS }, (_, i) => outcomeShotName(i + 1));
+export const shotNames = (variants) => variants.flatMap((v) => [failureShotName(v.id), ...(v.rounds ? [shotName(v.id), ...outcomeShotNames()] : [shotName(v.id), lateShotName(v.id)])]);
+
+/**
+ * What the maths pays for a forced row of the played mode and bet, in basis
+ * points of the stake: the tier whose outcomes hold it, 0 for a row no tier
+ * holds (a loss), null when the mode is not a table or the row is unknown.
+ */
+export function tierOf(manifest, played, row) {
+    const modes = Array.isArray(manifest?.modes) ? manifest.modes : [];
+    const mode = (played?.mode && modes.find((m) => m.id === played.mode)) || modes[0];
+    const bets = Array.isArray(mode?.bets) ? mode.bets : [];
+    const bet = (played?.bet && bets.find((b) => b.id === played.bet)) || bets[0];
+    if (!mode || mode.kind !== 'table' || !Array.isArray(bet?.tiers) || !Number.isInteger(row)) return null;
+    const t = bet.tiers.find((x) => (x.outcomes || []).some(([a, b]) => row >= a && row <= b));
+    return t ? Number(t.multBp) : 0;
+}
 
 /**
  * The variants to play, in the order they are played: the whole matrix, or
@@ -103,6 +128,43 @@ export function variantsFor(set, now = new Date()) {
     return [base, long, ...byClock(rest.filter((v) => v !== long), now)];
 }
 
+/**
+ * A caller's clocks for the dated variants (run.mjs --travel-clocks), checked:
+ * {id: {at, tz, locale}} for ids of the matrix that travel, an instant within
+ * three years of now (a report's clock replayed later is in the past), a zone
+ * this runtime knows, a language tag. Anything else
+ * throws: a run told to play at a clock it cannot must not quietly play another.
+ */
+export function travelClocks(text, now = new Date()) {
+    if (!text) return null;
+    const given = JSON.parse(text);
+    if (!given || typeof given !== 'object' || Array.isArray(given)) throw new Error('--travel-clocks: an object of variants');
+    const out = {};
+    for (const [id, c] of Object.entries(given)) {
+        const v = VARIANTS.find((x) => x.id === id);
+        if (!v || v.clock === 'now') throw new Error(`--travel-clocks: ${id} is not a dated variant`);
+        const at = Date.parse(c && c.at);
+        if (!Number.isFinite(at) || Math.abs(at - now.getTime()) > 3 * 366 * DAY) throw new Error(`--travel-clocks: ${id}'s instant is not within three years of now`);
+        try { new Intl.DateTimeFormat('en', { timeZone: c.tz }); } catch { throw new Error(`--travel-clocks: ${id}'s zone ${c.tz} is not one`); }
+        if (!/^[a-z]{2,3}(-[A-Z]{2})?$/.test(String(c.locale))) throw new Error(`--travel-clocks: ${id}'s language ${c.locale} is not a tag`);
+        out[id] = { at: new Date(at).toISOString(), tz: c.tz, locale: c.locale };
+    }
+    return out;
+}
+
+/**
+ * The variants with the caller's clocks in place of their own, the dated ones
+ * again in the order of their instants (each starts from the storage the one
+ * before it left). Those at the real time keep their place at the front.
+ */
+export function withClocks(variants, clocks, now = new Date()) {
+    if (!clocks) return variants;
+    const head = variants.filter((v) => v.clock === 'now');
+    const dated = variants.filter((v) => v.clock !== 'now').map((v) => (clocks[v.id] ? { ...v, ...clocks[v.id], given: true } : v));
+    const t = (v) => (v.at ? Date.parse(v.at) : clockFor(v, now).getTime());
+    return [...head, ...dated.map((v, i) => ({ v, i })).sort((a, b) => t(a.v) - t(b.v) || a.i - b.i).map((x) => x.v)];
+}
+
 /** The variants in the order of their clocks at `now`, the earliest first; two at one instant keep their order. */
 const byClock = (variants, now) => variants.map((v, i) => ({ v, i, t: clockFor(v, now).getTime() })).sort((a, b) => a.t - b.t || a.i - b.i).map((x) => x.v);
 
@@ -812,6 +874,46 @@ export const trapOptions = (token, clock = null) => ({ token, shimSrc: String(cl
 export const clockCommand = (token, op, id, ms) => `${token}:clock:${op}:${id}:${ms}`;
 export const clockAnswer = (token, id) => `${token}:clockdone:${id}:`;
 
+/**
+ * A `then` step's press that did not land (run.mjs thenSteps): `on`, its
+ * control is visible and enabled now; `covered`, Playwright's log of the click
+ * says something else took the pointer (a cover that later goes off with the
+ * round is still a cover); `missed`, the step's misses in a row before this
+ * one. A control that went off or away on its own while the click waited (the
+ * round outran the press, ticket #14) is let go and the count starts again;
+ * anything else is a miss, and `tries` misses in a row break the run.
+ */
+export function missedPress({ on, covered, missed = 0, tries = 1 }) {
+    if (!on && !covered) return { verdict: 'let go', missed: 0 };
+    const n = missed + 1;
+    return n >= tries ? { verdict: 'break', missed: 0 } : { verdict: 'again', missed: n };
+}
+
+/**
+ * After a jump some window did not answer: the URLs of the silent windows when
+ * none of them is the game's, or null when one may be or nothing is known.
+ * `frames` ({url, game}) are the page's frames now, `answered` the hrefs the
+ * answers named (cut at 120, as clockTrap cuts them), `posted` how many
+ * windows the jump was sent to. Answers are counted per URL, so two frames
+ * of one URL are two; and the frames now must be the windows the jump went
+ * to (none came or went meanwhile), or nothing is said.
+ */
+export function checkerOnlySilent(frames, answered, posted) {
+    const list = frames || [];
+    if (!list.length || list.length !== posted) return null;
+    const left = new Map();
+    for (const a of answered || []) left.set(String(a), (left.get(String(a)) || 0) + 1);
+    const silent = [];
+    for (const f of list) {
+        const url = String(f.url).slice(0, 120), n = left.get(url) || 0;
+        if (n > 0) left.set(url, n - 1);
+        else silent.push(f);
+    }
+    // Two frames of one URL, one silent: either may be the one, so the game's counts.
+    const shared = (f) => list.some((g) => g !== f && g.game && String(g.url).slice(0, 120) === String(f.url).slice(0, 120));
+    return silent.length && silent.every((f) => !f.game && !shared(f)) ? silent.map((f) => String(f.url).slice(0, 80)) : null;
+}
+
 // ---- the long session's forced rows -----------------------------------------------------
 
 /**
@@ -1065,6 +1167,10 @@ export const SHORT_VARIANT_MS = 60 * 1000;
 export const SHORT_VARIANT_MIN_MS = 15 * 1000;
 /** The least a long session is worth starting with. */
 export const LONG_MIN_MS = 60 * 1000;
+/** The share of the matrix's time the long session keeps however slow the short variants are estimated. */
+export const LONG_SHARE = 0.25;
+/** What a long session needs past its rounds (the boot before them, the screenshots after). */
+const LONG_MARGIN_MS = 15 * 1000;
 
 /**
  * What a short variant is estimated to take, from the short variants played
@@ -1085,15 +1191,28 @@ export function shortVariantEstimate(variants) {
  * Whether the next variant fits what is left of the matrix's real time
  * (`totalMs`, none when 0), and how much of it a long session may take: the
  * rest of the matrix, kept for the `after` variants after it at `perVariantMs`
- * each (shortVariantEstimate). A variant that does not fit is skipped and
- * says so, instead of the whole matrix being killed at its deadline with no
- * report.
+ * each (shortVariantEstimate), and never less than its own share of the
+ * matrix (LONG_SHARE) while that much is left. A variant that does not fit is
+ * skipped and says so, instead of the whole matrix being killed at its
+ * deadline with no report.
+ *
+ * The share is what a slow game's long session lives on. Reserving the
+ * variants after it at half again the slowest one played left it nothing
+ * once the baseline took 38 s or more (seven variants at 57 s and up, out of
+ * at most 510 s), so the long session of a slow but valid game was always
+ * skipped. With the share it keeps 97–128 s, and the dated variants at the
+ * end that then no longer fit are skipped in its place (in a 510 s matrix
+ * after a 48 s baseline, one of seven; none after a 38 s one). The long
+ * session keeps its place right after the baseline (variantsFor): played
+ * last, it would start from storage written at the dated variants' later
+ * clocks, a clock that ran backwards.
  */
 export function fitsBudget({ elapsedMs, totalMs, rounds, longBudgetMs, after = 0, perVariantMs = SHORT_VARIANT_MS }) {
     if (!totalMs) return { fits: true, longBudgetMs };
     const left = totalMs - elapsedMs;
     if (!rounds) return { fits: left >= perVariantMs, longBudgetMs };
-    const room = left - after * perVariantMs - 15 * 1000;
+    const share = Math.min(Math.round(totalMs * LONG_SHARE), left - LONG_MARGIN_MS);
+    const room = Math.max(left - after * perVariantMs - LONG_MARGIN_MS, share);
     if (room < LONG_MIN_MS) return { fits: false, longBudgetMs };
     return { fits: true, longBudgetMs: Math.min(longBudgetMs, room) };
 }
@@ -1169,6 +1288,7 @@ export function compareVariant(variant, baseline) {
         if (variant.stuck || !variant.outOfTime) failures.push(`${variant.settled || 0} of ${variant.rounds} fast rounds settled${variant.stuck ? ': ' + variant.stuck : ''}`);
         else warnings.push(`only ${variant.settled || 0} of ${variant.rounds} fast rounds fit the session's ${Math.round((variant.budgetMs || 0) / 1000)} s (this game's rounds are long): a trigger past round ${variant.settled || 0} is not seen`);
     }
+    if (variant.shotMissing) warnings.push(`the screenshot after the session could not be taken (${variant.shotMissing}): the game may have stopped drawing after many rounds, or the checker's renderer was too slow; play a long session in the sandbox`);
     if (variant.rounds && variant.forced && variant.forcedAsked > 0 && (variant.forcedApplied || 0) < variant.forcedAsked * FORCED_HONOURED_SHARE) {
         warnings.push(`the sandbox honoured ${variant.forcedApplied || 0} of ${variant.forcedAsked} forced rows${variant.forcedRefused ? ` (${variant.forcedRefused} refused)` : ''}: not every pay tier was shown`);
     }
@@ -1185,8 +1305,14 @@ export function compareVariant(variant, baseline) {
 const pct = (d) => (d.changed > STRONG_SHARE || !d.region ? `${Math.round(d.changed * 100)}%` : `a region of ${Math.round(d.region * 100)}%`);
 
 /** The variant as one line of the report, for a person. */
+// What each dated variant stands for when an upload draws its instant (pipeline/sync/clocks.mjs):
+// the id names the fixed clock `hbengine test` plays, not the drawn one.
+const KINDS = { plus1d: 'a day or two on', plus7d: 'about a week on', plus30d: 'a month or two on', plus365d: 'one to two years on', saturday: 'a weekend day', dec25: 'a holiday', jan1: 'the first of a month' };
+
 export function describe(variant) {
-    const when = variant.clock === 'now' ? 'real time' : `clock ${variant.clock === 'saturday' ? 'next Saturday' : variant.clock === 'dec25' ? 'next 25 December' : variant.clock === 'jan1' ? 'next 1 January' : variant.clock}`;
+    // A clock the caller gave is named by its kind and its instant (what `--travel-clocks` replays),
+    // so `jan1` at 1 March reads as the first of a month, not as a wrong 1 January.
+    const when = variant.given ? `${KINDS[variant.id] ? KINDS[variant.id] + ', ' : ''}clock ${variant.at}` : variant.clock === 'now' ? 'real time' : `clock ${variant.clock === 'saturday' ? 'next Saturday' : variant.clock === 'dec25' ? 'next 25 December' : variant.clock === 'jan1' ? 'next 1 January' : variant.clock}`;
     return `${when}, ${variant.tz}, ${variant.locale}${variant.rounds ? `, ${variant.rounds} fast rounds` : ''}`;
 }
 

package/engine-examples/keno/math-kit/pack.mjs

@@ -10,7 +10,7 @@
  *
  * Every number here is an integer: weights are BigInt, RTP is a fraction.
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 const MAX_SUM = 1n << 63n;
@@ -121,16 +121,55 @@ function ranges(ids) {
     return out;
 }
 
+// The verifier's bound on one bet's pay tiers (housegames-backend mathpack.MaxTiers).
+export const MAX_TIERS = 16384;
+
+// The most a pack's maths may be: the files in math/ together, as their bytes
+// on disk. Housebets' limit, not a verifier's: the live engine holds a game's
+// tables in memory, and the upload's checks slow as they grow. Checked here,
+// by hbengine before it sends a pack, and by the upload's own check
+// (pipeline/job), so no way in passes a bigger one. The Go side's figure is
+// internal/archive MaxMathBytes (pack.test.mjs holds the two together).
+export const MAX_MATH_BYTES = 200 * 1024 * 1024;
+
+// The refusal of maths over MAX_MATH_BYTES, in the same words wherever it is
+// checked; the size is rounded up, so maths just over never reads as 200 MB.
+export const mathTooLarge = (bytes) => `The maths is ${Math.ceil((bytes * 10) / 1048576) / 10} MB; a pack's maths may be at most ${MAX_MATH_BYTES / 1048576} MB.`;
+
+// The bytes of the maths in dir: its files together (math/ holds nothing below them).
+export const mathBytes = (dir) => readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).reduce((n, e) => n + statSync(join(dir, e.name)).size, 0);
+
+/**
+ * What a meter adds to the RTP of every bet of its modes, exactly (GUIDE:
+ * Meters): E[award] ÷ fill, in basis points of the stake. `rows` are the
+ * award's outcomes, `pay` the multiplier of the reference in bp.
+ */
+export function meterRtp({ fill, rows }) {
+    const den = rows.reduce((s, r) => s + r.weight, 0n) * BigInt(fill);
+    const num = rows.reduce((s, r) => s + r.weight * BigInt(r.pay || 0), 0n);
+    return { num, den, bp: bp4(num, den) };
+}
+
 /**
  * Writes manifest.json and one table per mode. A mode is { id, label?, rows,
- * bets: [id | {id, label}] }; its rows are sorted by what the first bet pays,
+ * bets: [id | {id, label}], meter? }; its rows are sorted by what the first bet pays,
  * so each pay tier is one range. Prints every bet's exact RTP, hit rate and
  * largest multiplier; returns them.
+ *
+ * meters: [{ id, label?, fill, rows }] — progress that pays (GUIDE: Meters).
+ * A meter's rows are its award's outcomes, each { weight, pay, data? } with
+ * `pay` in bp of the meter's reference (20000 = twice the reference); a mode
+ * names the meter its rounds fill with `meter: id`. Every bet of such a mode
+ * reports base + meter RTP, and the base must clear 90% on its own.
  */
-export function writePack(dir, { game, rtpBp, modes }) {
-    mkdirSync(dir, { recursive: true });
+export function writePack(dir, { game, rtpBp, modes, meters = [] }) {
+    if (!Array.isArray(modes) || modes.length < 1 || modes.length > 64) throw new Error('a pack needs 1 to 64 modes');
+    for (const mode of modes) {
+        if (!Array.isArray(mode.bets) || mode.bets.length < 1 || mode.bets.length > 256) throw new Error(`${mode.id}: 1 to 256 bets per mode`);
+    }
     const manifest = { format: 'house-engine-math/1', game, rtpBp, modes: [] };
     const report = [];
+    const tables = new Map();
     for (const mode of modes) {
         const bets = mode.bets.map((b) => (typeof b === 'string' ? { id: b } : b));
         const first = bets[0].id;
@@ -141,25 +180,63 @@ export function writePack(dir, { game, rtpBp, modes }) {
         const lines = rows.map((r) => {
             if (r.weight <= 0n) throw new Error(`${mode.id}: a weight is not positive`);
             const json = r.data === undefined ? '' : JSON.stringify(r.data);
-            if (json.length > 4096) throw new Error(`${mode.id}: a row's data is over 4096 bytes`);
+            if (Buffer.byteLength(json) > 4096) throw new Error(`${mode.id}: a row's data is over 4096 UTF-8 bytes`);
             return json ? `${r.weight}\t${json}` : String(r.weight);
         });
         const table = `${game}-${mode.id}.tsv`;
-        writeFileSync(join(dir, table), lines.join('\n') + '\n');
+        tables.set(table, lines.join('\n') + '\n');
         manifest.modes.push({
-            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table,
+            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table, ...(mode.meter ? { meter: mode.meter } : {}),
             bets: bets.map((b) => {
                 const tiers = new Map();
                 rows.forEach((r, i) => { const m = r.pay[b.id] || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
                 const { num, den, bp } = rtp(rows, b.id);
                 const hit = rows.reduce((s, r) => s + (r.pay[b.id] > 0 ? r.weight : 0n), 0n);
+                // The engine's verifier refuses a bet with more pay tiers than this (one tier per distinct
+                // multiplier): refused here, at the build, not at the upload (mathpack.MaxTiers).
+                if (tiers.size > MAX_TIERS) throw new Error(`${mode.id}: bet "${b.id}": ${tiers.size} distinct payouts (tiers), at most ${MAX_TIERS}: round the multipliers to fewer values`);
                 const max = Math.max(...tiers.keys());
-                report.push({ mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n });
+                const entry = { mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n };
+                if (mode.meter) {
+                    const mt = meters.find((x) => x.id === mode.meter);
+                    if (!mt) throw new Error(`${mode.id}: meter "${mode.meter}" is not in meters`);
+                    const add = meterRtp(mt);
+                    // base + E[award]/fill, as one exact fraction
+                    const tn = num * add.den + add.num * den, td = den * add.den;
+                    Object.assign(entry, { baseRtp: bp, meter: mode.meter, rtp: bp4(tn, td), exact: tn % td === 0n });
+                }
+                report.push(entry);
                 return { id: b.id, ...(b.label ? { label: b.label } : {}), tiers: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) };
             }),
         });
     }
-    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest) + '\n');
-    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
+    for (const mt of meters) {
+        if (!Number.isSafeInteger(mt.fill) || mt.fill < 2 || mt.fill > 1_000_000) throw new Error(`meter ${mt.id}: fill must be 2 to 1,000,000`);
+        if (!modes.some((m) => m.meter === mt.id)) throw new Error(`meter ${mt.id}: no mode fills it`);
+        const rows = [...mt.rows].sort((a, b) => (a.pay || 0) - (b.pay || 0));
+        if (rows.length < 1) throw new Error(`meter ${mt.id}: an award needs rows`);
+        const table = `${game}-meter-${mt.id}.tsv`;
+        tables.set(table, rows.map((r) => {
+            if (r.weight <= 0n) throw new Error(`meter ${mt.id}: a weight is not positive`);
+            const json = r.data === undefined ? '' : JSON.stringify(r.data);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        }).join('\n') + '\n');
+        const tiers = new Map();
+        rows.forEach((r, i) => { const m = r.pay || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
+        if (!tiers.size) throw new Error(`meter ${mt.id}: the award never pays`);
+        (manifest.meters ||= []).push({ id: mt.id, ...(mt.label ? { label: mt.label } : {}), fill: mt.fill, table,
+            award: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) });
+        const ev = meterRtp({ fill: 1, rows });
+        console.log(`meter ${mt.id}: fill ${mt.fill}  award E ${bp4(ev.num, ev.den * 10000n)}× the reference  adds ${meterRtp({ fill: mt.fill, rows }).bp} bp`);
+    }
+    tables.set('manifest.json', JSON.stringify(manifest) + '\n');
+    // The pack as it will be on disk, with what else is in dir already (the
+    // generator, often), measured before a file is written.
+    mkdirSync(dir, { recursive: true });
+    const others = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && !tables.has(e.name));
+    const bytes = [...tables.values()].reduce((n, text) => n + Buffer.byteLength(text), 0) + others.reduce((n, e) => n + statSync(join(dir, e.name)).size, 0);
+    if (bytes > MAX_MATH_BYTES) throw new Error(mathTooLarge(bytes));
+    for (const [name, text] of tables) writeFileSync(join(dir, name), text);
+    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp${r.meter ? ` (base ${r.baseRtp} + meter ${r.meter})` : ''}  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
     return report;
 }