@descix/frqtl-node 0.0.0-stage → 0.6.0-p0.1

package/dist/shim/experiment-frame/index.js

@@ -0,0 +1,296 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/experiment-frame — THE fail-loud guard for a host that embeds a
+ * canonical experiment page in an iframe.
+ *
+ * ── Why this module exists (the false-200 trap, observed 2026-07-28) ─────────
+ * A dev/prod vite host answers an UNKNOWN path with its SPA fallback: HTTP 200,
+ * `text/html`, the host app's OWN `index.html`. So when an experiment id stops
+ * existing (a retirement), `GET /frqtl/experiments/<gone>/index.html` does not
+ * 404 — it returns the SITE. The host's hero iframe then embeds the host inside
+ * itself, recursively: the nav bar renders three times, the stage is blank, and
+ * EVERY automated signal is clean (0 HTTP 4xx/5xx, 0 `requestfailed`, 0
+ * `pageerror`). A missing experiment degraded SILENTLY into a self-embed.
+ *
+ * This module makes that impossible to miss. It does NOT trust the HTTP status
+ * (which lies) — it inspects the DOCUMENT that actually loaded and asserts it is
+ * a canonical experiment page, by two independent signals:
+ *
+ *   1. POSITIVE PROOF — the boot record markers. Every canonical experiment
+ *      page boots through `_shared/boot.js`, whose boot record writes
+ *      `EXPERIMENT_PAGE_MARKERS` on its own <html> while the page's module script
+ *      evaluates — before the document reaches `readyState === 'complete'`. No
+ *      other document in this repo writes them. Their presence is what "an
+ *      experiment page booted" MEANS; their absence at document-complete is a
+ *      hard failure.
+ *   2. POSITIVE IDENTIFICATION of the impostor — the host SPA shell root
+ *      (`HOST_SHELL_ROOT_SELECTOR`, the `<div id="root">` in
+ *      `apps/ide/index.html`). A document that
+ *      has the shell root and none of the markers IS the SPA fallback, and the
+ *      guard says so by name rather than reporting a generic timeout.
+ *
+ * A 200 cannot fool either signal: the check reads the loaded document, and the
+ * SPA shell provably lacks every marker.
+ *
+ * ── Layer 1: API contract ───────────────────────────────────────────────────
+ *   classifyFrameProbe(probe)  — PURE verdict function (no DOM). Unit-testable.
+ *   probeExperimentFrame(el)   — DOM adapter: iframe element → probe bag.
+ *   watchExperimentFrame(el,o) — poll + paint a visible overlay on failure.
+ *
+ * ── Layer 2: physics behavior ───────────────────────────────────────────────
+ * None. This is host-side plumbing: it observes whether a document booted and
+ * never touches the engine, a universe, or a tick.
+ */
+
+'use strict';
+
+/**
+ * The <html> attributes the boot record (`lib/frqtl/experiments/_shared/boot.js`
+ * `createBootRecord`) writes the moment a page's boot begins — during the page's
+ * module-script evaluation, so both exist by the time the document reaches
+ * `readyState === 'complete'`, regardless of whether the engine has finished
+ * fetching WASM.
+ *
+ * This is the ONE list; a consumer asserts against it, never against a
+ * hand-picked attribute of its own.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export var EXPERIMENT_PAGE_MARKERS = Object.freeze([
+    'data-egpt-boot-phase',
+    'data-egpt-boot-progress'
+]);
+
+/**
+ * The mount point the host SPA shell renders React into (`apps/ide/index.html`).
+ * Its presence inside an experiment iframe is the fingerprint of the vite SPA
+ * fallback having answered the request with the host's own page.
+ * @type {string}
+ */
+export var HOST_SHELL_ROOT_SELECTOR = '#root';
+
+/**
+ * The verdict vocabulary. `ok` and `pending` are non-failures; everything else
+ * is a FAIL-LOUD outcome the host must surface visibly.
+ * @type {Readonly<Record<string,string>>}
+ */
+export var FRAME_VERDICTS = Object.freeze({
+    OK:             'ok',
+    PENDING:        'pending',
+    CROSS_ORIGIN:   'cross-origin',
+    SPA_SHELL:      'spa-shell',
+    NOT_EXPERIMENT: 'not-an-experiment-page'
+});
+
+/** Default grace period before a not-yet-complete document is called failed. */
+export var DEFAULT_FRAME_TIMEOUT_MS = 10000;
+
+/**
+ * classifyFrameProbe(probe) — the PURE verdict function.
+ *
+ * @param {{
+ *   src?: string,            // the URL the host ASKED for
+ *   href?: string,           // the URL the frame's document actually has
+ *   sameOrigin?: boolean,    // false when reading contentWindow threw
+ *   readyState?: string,     // the frame document's readyState
+ *   markers?: string[],      // which EXPERIMENT_PAGE_MARKERS were found
+ *   hasHostShellRoot?: boolean,
+ *   elapsedMs?: number,
+ *   timeoutMs?: number
+ * }} probe
+ * @returns {{verdict:string, ok:boolean, done:boolean, message:string}}
+ *   `done` is false only for `pending` (keep polling).
+ */
+export function classifyFrameProbe(probe) {
+    var p        = probe || {};
+    var src      = p.src || '(unknown src)';
+    var href     = typeof p.href === 'string' ? p.href : '';
+    var found    = Array.isArray(p.markers) ? p.markers : [];
+    var timeout  = typeof p.timeoutMs === 'number' ? p.timeoutMs : DEFAULT_FRAME_TIMEOUT_MS;
+    var elapsed  = typeof p.elapsedMs === 'number' ? p.elapsedMs : 0;
+
+    // A cross-origin frame cannot be inspected at all — say so rather than
+    // silently trusting it. The /frqtl mount is same-origin BY DESIGN (that is
+    // the precondition every host-side runner grab already relies on), so this
+    // verdict means the host built the wrong URL.
+    if (p.sameOrigin === false) {
+        return _verdict(FRAME_VERDICTS.CROSS_ORIGIN, false, true,
+            'the experiment frame is CROSS-ORIGIN, so the host cannot verify what loaded.\n' +
+            'requested: ' + src + '\n' +
+            'Experiment pages must be served from the host\'s own origin (the /frqtl mount).');
+    }
+
+    // A frame that has not navigated to the requested document yet (about:blank
+    // between src assignments) is PENDING, never a failure.
+    if (href === '' || href === 'about:blank') {
+        return _pendingOrTimeout(elapsed, timeout, src,
+            'the frame is still on about:blank — it never navigated to the requested URL.');
+    }
+
+    // POSITIVE PROOF: every boot marker present ⇒ a canonical experiment page.
+    var missing = EXPERIMENT_PAGE_MARKERS.filter(function (m) { return found.indexOf(m) === -1; });
+    if (missing.length === 0) {
+        return _verdict(FRAME_VERDICTS.OK, true, true, 'experiment page booted: ' + src);
+    }
+
+    // POSITIVE IDENTIFICATION of the impostor. The SPA shell verdict does NOT
+    // wait for the timeout: a document carrying the host's own React root and
+    // none of the boot markers is definitively not an experiment page, whatever
+    // status code delivered it.
+    if (p.hasHostShellRoot === true) {
+        return _verdict(FRAME_VERDICTS.SPA_SHELL, false, true,
+            'THE FALSE-200 TRAP: the request returned HTTP 200 text/html, but the document is the\n' +
+            'HOST\'S OWN SPA SHELL (it has ' + HOST_SHELL_ROOT_SELECTOR + ' and none of the experiment-page\n' +
+            'boot markers [' + EXPERIMENT_PAGE_MARKERS.join(', ') + ']).\n' +
+            'requested: ' + src + '\n' +
+            'loaded:    ' + href + '\n' +
+            'The dev server answers an UNKNOWN path with its SPA fallback, so a MISSING experiment id\n' +
+            'looks like a successful load and this host ends up embedding ITSELF, recursively.\n' +
+            'Fix the id at its single declaration site — do not add a fallback id here.');
+    }
+
+    // Document finished loading and it is neither an experiment page nor the
+    // recognised shell — still a hard failure, reported honestly.
+    if (p.readyState === 'complete') {
+        return _verdict(FRAME_VERDICTS.NOT_EXPERIMENT, false, true,
+            'the frame finished loading but it is NOT a canonical experiment page.\n' +
+            'requested: ' + src + '\n' +
+            'loaded:    ' + href + '\n' +
+            'missing boot markers: [' + missing.join(', ') + ']\n' +
+            'A canonical experiment page boots through _shared/boot.js, whose boot record writes all of\n' +
+            '[' + EXPERIMENT_PAGE_MARKERS.join(', ') + '] on its <html> as the boot begins.');
+    }
+
+    return _pendingOrTimeout(elapsed, timeout, src,
+        'missing boot markers: [' + missing.join(', ') + '] (document readyState=' +
+        (p.readyState || 'unknown') + ').');
+}
+
+function _verdict(verdict, ok, done, message) {
+    return { verdict: verdict, ok: ok, done: done, message: '[experiment-frame] ' + message };
+}
+
+function _pendingOrTimeout(elapsed, timeout, src, detail) {
+    if (elapsed >= timeout) {
+        return _verdict(FRAME_VERDICTS.NOT_EXPERIMENT, false, true,
+            'the frame never became a canonical experiment page within ' + timeout + 'ms.\n' +
+            'requested: ' + src + '\n' + detail);
+    }
+    return _verdict(FRAME_VERDICTS.PENDING, false, false, 'waiting for ' + src + ' — ' + detail);
+}
+
+/**
+ * probeExperimentFrame(iframeEl, opts) — the DOM adapter. Reads the frame's own
+ * document (same-origin) and returns the probe bag `classifyFrameProbe` consumes.
+ *
+ * @param {HTMLIFrameElement} iframeEl
+ * @param {{elapsedMs?:number, timeoutMs?:number}} [opts]
+ * @returns {object} the probe bag.
+ */
+export function probeExperimentFrame(iframeEl, opts) {
+    var o = opts || {};
+    var probe = {
+        src:      iframeEl && iframeEl.src ? iframeEl.src : '',
+        href:     '',
+        sameOrigin: true,
+        readyState: undefined,
+        markers:  [],
+        hasHostShellRoot: false,
+        elapsedMs: o.elapsedMs,
+        timeoutMs: o.timeoutMs
+    };
+    var cw = null;
+    try {
+        cw = iframeEl && iframeEl.contentWindow;
+        if (!cw) { return probe; }              // not attached yet → PENDING
+        probe.href = (cw.location && cw.location.href) || '';
+        var doc = cw.document;
+        probe.readyState = doc ? doc.readyState : undefined;
+        var root = doc && doc.documentElement;
+        probe.markers = EXPERIMENT_PAGE_MARKERS.filter(function (m) {
+            return !!(root && root.hasAttribute && root.hasAttribute(m));
+        });
+        probe.hasHostShellRoot = !!(doc && doc.querySelector &&
+            doc.querySelector(HOST_SHELL_ROOT_SELECTOR));
+    } catch (e) {
+        // A same-origin read that throws means the document is cross-origin.
+        probe.sameOrigin = false;
+    }
+    return probe;
+}
+
+/**
+ * paintFrameGuardOverlay(hostEl, message) — the VISIBLE failure. Mirrors the
+ * empty page's own `_egptPaintWalkthroughError` styling so a guard failure and a
+ * recipe failure read as one family.
+ *
+ * @param {Element} hostEl — the element to overlay (the iframe's wrapper).
+ * @param {string} message
+ * @returns {Element} the overlay node.
+ */
+export function paintFrameGuardOverlay(hostEl, message) {
+    var host = hostEl || (typeof document !== 'undefined' ? document.body : null);
+    if (!host) { return null; }
+    var existing = host.querySelector && host.querySelector('[data-role="experiment-frame-error"]');
+    if (existing) { existing.parentNode.removeChild(existing); }
+    var box = host.ownerDocument.createElement('div');
+    box.setAttribute('data-role', 'experiment-frame-error');
+    box.style.cssText =
+        'position:absolute;inset:0;z-index:9999;padding:16px;overflow:auto;' +
+        'white-space:pre-wrap;background:#1a0000;color:#ff6b6b;border:2px solid #b6161c;' +
+        'font:12px/1.55 ui-monospace,Menlo,Consolas,monospace;';
+    box.textContent = message;
+    if (host.style && (!host.style.position || host.style.position === 'static')) {
+        host.style.position = 'relative';
+    }
+    host.appendChild(box);
+    return box;
+}
+
+/**
+ * watchExperimentFrame(iframeEl, opts) — poll the frame until it is proven to be
+ * a canonical experiment page, or FAIL LOUD (console.error + a visible overlay +
+ * `onError`).
+ *
+ * @param {HTMLIFrameElement} iframeEl
+ * @param {{
+ *   overlayHost?: Element,      // defaults to iframeEl.parentNode
+ *   timeoutMs?: number,
+ *   pollMs?: number,
+ *   onOk?: function(Window):void,
+ *   onError?: function({verdict:string,message:string}):void
+ * }} [opts]
+ * @returns {function():void} stop() — cancels the watch (call from useEffect cleanup).
+ */
+export function watchExperimentFrame(iframeEl, opts) {
+    var o        = opts || {};
+    var timeout  = typeof o.timeoutMs === 'number' ? o.timeoutMs : DEFAULT_FRAME_TIMEOUT_MS;
+    var pollMs   = typeof o.pollMs === 'number' ? o.pollMs : 150;
+    var started  = Date.now();
+    var stopped  = false;
+    var timer    = setInterval(tick, pollMs);
+    tick();
+
+    function tick() {
+        if (stopped) { return; }
+        var probe  = probeExperimentFrame(iframeEl, { elapsedMs: Date.now() - started, timeoutMs: timeout });
+        var result = classifyFrameProbe(probe);
+        if (!result.done) { return; }
+        stop();
+        if (result.ok) {
+            if (typeof o.onOk === 'function') { o.onOk(iframeEl.contentWindow); }
+            return;
+        }
+        if (typeof console !== 'undefined' && console.error) { console.error(result.message); }
+        paintFrameGuardOverlay(o.overlayHost || (iframeEl && iframeEl.parentNode), result.message);
+        if (typeof o.onError === 'function') { o.onError(result); }
+    }
+
+    function stop() {
+        if (stopped) { return; }
+        stopped = true;
+        clearInterval(timer);
+    }
+    return stop;
+}

package/dist/shim/expr/ast-schema.js

@@ -0,0 +1,369 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * ast-schema.js — Expression AST WIRE CONTRACT for FRQTL op-programs.
+ *
+ * This module is the cross-engine authority for op-program AST node shapes,
+ * operator vocabularies, and evaluation conventions.  It is read-contract-shaped
+ * (like lib/shim/frame-data SECTION_KEYS) — it exports node SHAPES and vocab
+ * LISTS; it does NOT contain any parsing or evaluation logic.
+ *
+ * Architecture: lib/shim/expr/ (this file) ← imported by lib/frqtl/objects/
+ *   sugar (JS-side parser → ast-schema shapes)
+ *   and by the dual-native evaluators in the JS reference and Rust engines.
+ * Arrow-legality: lib/frqtl/objects imports lib/shim (downward — legal).
+ *
+ * Gate-2 architect binding (2026-06-21, slice 3):
+ *   • Rust NEVER parses — AST-only payload; this schema is the data shape.
+ *   • NODE_KINDS and vocab lists are the conformance iteration surface
+ *     (binding item 3 — conformance iterates these lists).
+ *   • Integer-first evaluation convention is documented here (binding item 4).
+ *   • Named refs compile to integer handles JS-side (binding item 5) — this
+ *     schema defines the Ref shape ({handle:number, prop:string}).
+ *
+ * HOW TO READ THIS FILE
+ * ─────────────────────
+ * An ExprAST is one of:
+ *
+ *   Lit    { kind:'Lit',  value: number }
+ *          A numeric literal. Floating-point JSON number; rounded to integer
+ *          by integer-first eval where the target property is integer-domain.
+ *
+ *   Ref    { kind:'Ref',  handle: number, prop: string }
+ *          Read handle.prop at eval time. handle is an integer index into the
+ *          scope's object table (compiled JS-side — NOT a string name).
+ *          Special handles: HANDLE_FRAME / HANDLE_SELF / HANDLE_UNIVERSE (below).
+ *
+ *   Bin    { kind:'Bin',  op: BIN_OP, a: ExprAST, b: ExprAST }
+ *          Binary arithmetic. INTEGER-FIRST: '/' is integer division (truncate
+ *          toward zero). Result of '/' is Math.trunc(a/b) in JS, a/b as i64
+ *          truncated in Rust.  Never produces a float in integer-domain props.
+ *
+ *   Cmp    { kind:'Cmp',  op: CMP_OP, a: ExprAST, b: ExprAST }
+ *          Comparison. Returns 1 (true) or 0 (false) — integer, not boolean.
+ *          Required for Cond tests and guard expressions.
+ *
+ *   Cond   { kind:'Cond', test: ExprAST, then: ExprAST, else: ExprAST }
+ *          Conditional: if test != 0 then 'then' else 'else'.
+ *          test is truthy when non-zero (follows from Cmp returning 0/1).
+ *
+ *   Fn     { kind:'Fn',   name: FN_NAME, args: ExprAST[] }
+ *          Built-in function. min/max accept two args; floor accepts one.
+ *          INTEGER-FIRST: floor(x) is already integer in integer-domain
+ *          contexts; on float-domain props it applies Math.floor / Rust floor.
+ *
+ *   StrLit { kind:'StrLit', value: string }
+ *          A string literal — valid ONLY as the `to` value of a `set` op
+ *          whose target is `<handle>.data.<key>` (a string-map write).
+ *          MUST throw (JS) / panic (Rust) if used as a child of Bin, Cmp,
+ *          Fn, or Cond.test — eval_expr stays numeric-pure (INTEGER-FIRST
+ *          ruling; Gate-2 2026-06-21 item 2). The op-apply layer
+ *          (_runOpProgram / apply_set_op) detects StrLit before calling
+ *          eval_expr and routes it to the string-map writer.
+ *
+ * OP-PROGRAM SHAPE
+ * ─────────────────
+ *   { on: TRIGGER, ops: [ { set: '<handle>.<prop>', to: ExprAST }, ... ] }
+ *
+ *   TRIGGER:
+ *     'collision' — ops run per colliding frame (scope: frame, self, universe)
+ *     'tick'      — ops run per LO per tick (scope: self, named refs, universe)
+ *
+ *   set target format: '<integer-handle>.<prop-name>'
+ *     The JS sugar compiles readable names ('frame', 'self', 'emitterA', …)
+ *     to integer handles before the AST crosses the boundary. Rust parses
+ *     '<number>.<string>' — no string-name registry on the Rust side.
+ *
+ * EVALUATION SCOPE
+ * ─────────────────
+ *   on:'collision':
+ *     HANDLE_FRAME     (0) — the colliding frame  (Frame properties)
+ *     HANDLE_SELF      (1) — this LO / emitter     (LO/emitter properties)
+ *     HANDLE_UNIVERSE  (2) — universe read-only    (tick, activeQuanta)
+ *
+ *   on:'tick':
+ *     HANDLE_SELF      (1) — this LO/emitter
+ *     HANDLE_UNIVERSE  (2) — universe
+ *     3, 4, 5, …       — named refs (other registered objects by handle)
+ *
+ * INTEGER-FIRST EVALUATION CONVENTION (binding item 4)
+ * ──────────────────────────────────────────────────────
+ *   All arithmetic operates on the raw numeric values from the scope.
+ *   '/' is INTEGER DIVISION: Math.trunc(a / b) in JS; (a as i64) / (b as i64)
+ *       in Rust.  Division by zero → 0 (not an error; matches discrete physics).
+ *   '==' / '<' / '>' return 1 (true) or 0 (false) — integer.
+ *   'floor' on an already-integer value is a no-op (included for completeness).
+ *   NO silent float result is written into an integer-domain property (x, y, vx,
+ *   vy, mass, count, etc.).  The 'set' op applies Math.round() / Rust f64.round()
+ *   before writing integer-domain props identified in the Frame / LO tables.
+ *
+ * ADVERSARIAL CASES (conformance must cover these — binding item 4):
+ *   Bin('/', Lit(7), Lit(2))   → 3   (truncate, not round or floor)
+ *   Bin('/', Lit(-7), Lit(2))  → -3  (truncate toward zero, not floor: -4)
+ *   Fn('floor', [Lit(7.9)])    → 7   (floor, not truncate: same for positives,
+ *                                     differs for negatives: floor(-7.9)=-8 ≠ trunc(-7.9)=-7)
+ *   Cmp('==', Lit(1), Lit(1))  → 1
+ *   Cmp('==', Lit(1), Lit(2))  → 0
+ *   Cmp('<', Lit(3), Lit(5))   → 1
+ *   Cmp('>', Lit(5), Lit(3))   → 1
+ *   nested Cond(Cmp…, Lit, Lit)
+ */
+
+
+
+// ── Node kind names ────────────────────────────────────────────────────────────
+
+/**
+ * NODE_KINDS — the complete, ordered list of expression AST node kinds.
+ *
+ * Conformance iterates this list to assert coverage (binding item 3):
+ *   every kind must have at least one representative scenario in
+ *   expr_program_scenarios.js.
+ *
+ * THIS LIST IS CLOSED AT 7 — do NOT add structural op kinds here.
+ * Structural op kinds live in OP_KINDS (below). The two lists are orthogonal.
+ *
+ * NOTE on StrLit (item 7): StrLit is ONLY valid as the `to` value of a `set`
+ * op targeting `<handle>.data.<key>` (a string-map write). Using StrLit as a
+ * child of Bin, Cmp, Fn, or Cond.test MUST throw/panic — eval_expr is
+ * numeric-pure (INTEGER-FIRST ruling, Gate-2 2026-06-21 item 2).
+ *
+ * @type {string[]}
+ */
+var NODE_KINDS = Object.freeze([
+    'Lit',    // numeric literal
+    'Ref',    // property read via handle
+    'Bin',    // binary arithmetic
+    'Cmp',    // comparison → 0/1
+    'Cond',   // conditional
+    'Fn',     // built-in function
+    'StrLit'  // string literal — ONLY valid as `to` in data.<key> set ops
+]);
+
+/**
+ * OP_KINDS — the complete, ordered list of op-program STATEMENT kinds.
+ *
+ * These are the kinds of ops that can appear in program.ops[].
+ * They are DISTINCT from the value-grammar node kinds in NODE_KINDS.
+ *
+ * §2e (2026-06-24): OP_KINDS is closed at ['set'].
+ *   addFrames / subtractFrames / addDimension were NEVER implemented as op-kinds
+ *   in the Rust engine (OpProgram = ops: Vec<SetOp>; SetOp = {set, to}).  Their
+ *   structural analogs are engine METHODS, not op-program statements:
+ *     - Frame injection  → emitters / makeLeafFrame / createFrameFromRect / insert
+ *     - Frame removal    → set 0.is_alive=0 + dead-parent GC
+ *     - Dimension alloc  → universe.addDimension(n) / add_dimension engine method
+ *
+ * Gate-2 architect binding (2026-06-21, §10.8 B3):
+ *   • B3.2 — 'collect' is NOT a 2nd op.  It compiles to:
+ *     { kind:'set', set:'1.count', to: Bin('+', Ref(HANDLE_SELF,'count'), Lit(1)) }
+ *     i.e. a plain 'set' op on the LO's 'count' property.  No special sink.
+ *
+ * Op shapes:
+ *   set — { kind:'set', set:'<handle>.<prop>', to: ExprAST }
+ *
+ * Conformance iterates this list (binding item 3):
+ *   every kind must have at least one scenario in control_loop_scenarios.js.
+ *
+ * @type {string[]}
+ */
+var OP_KINDS = Object.freeze([
+    'set'   // property write: routes through setFrameProperty / setObjectProperty
+]);
+
+// ── Operator vocabularies ──────────────────────────────────────────────────────
+
+/**
+ * BIN_OPS — binary arithmetic operators.
+ * '/' is INTEGER DIVISION (truncate toward zero) — see convention above.
+ *
+ * Conformance must cover all four.
+ * @type {string[]}
+ */
+var BIN_OPS = Object.freeze(['+', '-', '*', '/']);
+
+/**
+ * CMP_OPS — comparison operators.  All return 1 or 0.
+ * Conformance must cover all three.
+ * @type {string[]}
+ */
+var CMP_OPS = Object.freeze(['<', '>', '==']);
+
+/**
+ * FN_NAMES — built-in function names.
+ * min/max: 2 args. floor: 1 arg. random: 0 args.
+ * Conformance must cover all four.
+ *
+ * NOTE on 'random' (G2, 2026-06-24):
+ *   Fn('random', []) draws one value from the engine's single Mulberry32 stream.
+ *   It is a SIDE-EFFECTING draw — each eval call advances the RNG by one step.
+ *   JS eval: closes over the engine's _rng() function (already in scope in
+ *     _runOpProgram).
+ *   Rust eval: eval_expr receives &mut rng so the draw advances the shared stream.
+ *   Draw order: the ops array is evaluated left-to-right (op 0 before op 1 etc.)
+ *   and each Fn('random',[]) in a `to` expression is evaluated in tree order
+ *   (left child before right child for Bin/Fn). This is deterministic.
+ *   RNG discipline: velocity set-ops MUST appear LAST in the op-program ops array
+ *   (after any ABSORB/COUNT/MARK/BLOCK ops) so that random() draws land at the
+ *   same point in the global RNG sequence as the native RANDOM_* dispatch did
+ *   (which ran AFTER action dispatch in the collision loop).
+ *
+ * NOTE on 'intersects' (G2b, 2026-06-25):
+ *   Fn('intersects', [Lit(h0), Lit(h1)]) is a NATIVE GEOMETRY CALL — not numeric
+ *   arithmetic. It calls the native Rectangle::intersects primitive on the
+ *   scope-resolved rects for handle h0 and h1 (reading left/right/top/bottom from
+ *   the scope bag for each handle). Returns 1 (true) or 0 (false).
+ *
+ *   In practice args are always [Lit(HANDLE_FRAME), Lit(HANDLE_SELF)] (frame vs LO).
+ *   Compiled exclusively by actionCompiler._buildTriggerExpr — do NOT construct
+ *   manually.
+ *
+ *   This is the canonical overlap test for op-programs (replaces the native
+ *   overlaps/past_wall gate that was deleted from process_large_object_collisions in
+ *   G2b). The JS reference (EGPTfrqtl.js) is FROZEN — intersects is a WASM-canonical
+ *   addition only (JS reference keeps the old native gate).
+ *
+ *   Draw discipline: intersects draws ZERO RNG values (deterministic geometry).
+ * @type {string[]}
+ */
+var FN_NAMES = Object.freeze(['min', 'max', 'floor', 'random', 'intersects']);
+
+// ── Trigger vocabulary ─────────────────────────────────────────────────────────
+
+/**
+ * TRIGGERS — valid values for program.on.
+ * @type {string[]}
+ */
+var TRIGGERS = Object.freeze(['collision', 'tick']);
+
+// ── Reserved scope handles ─────────────────────────────────────────────────────
+
+/**
+ * HANDLE_FRAME — scope handle for the colliding frame in on:'collision' programs.
+ * Reads Frame properties (§2.3 table: x, y, vx, vy, mass, …).
+ * @type {number}
+ */
+var HANDLE_FRAME = 0;
+
+/**
+ * HANDLE_SELF — scope handle for the owning LO/emitter.
+ * Reads LO descriptor properties (rect, count, …) or emitter properties.
+ * @type {number}
+ */
+var HANDLE_SELF = 1;
+
+/**
+ * HANDLE_UNIVERSE — scope handle for universe read-only state.
+ * Properties: 'tick' (u64), 'activeQuanta' (usize).
+ * @type {number}
+ */
+var HANDLE_UNIVERSE = 2;
+
+// ── Node shape helpers (JS-side construction) ──────────────────────────────────
+//
+// These are OPTIONAL helpers for constructing AST nodes from JS sugar.
+// The shapes they produce are the canonical wire format — Rust deserializes
+// the same JSON structure.  Using these helpers is not required; you may
+// construct the object literal directly.
+
+/**
+ * Lit(n) — numeric literal node.
+ * @param {number} value
+ * @returns {{ kind:'Lit', value:number }}
+ */
+function Lit(value) {
+    return { kind: 'Lit', value: value };
+}
+
+/**
+ * Ref(handle, prop) — property read node.
+ * @param {number} handle  — integer scope handle (HANDLE_FRAME / HANDLE_SELF / HANDLE_UNIVERSE / …)
+ * @param {string} prop    — property name
+ * @returns {{ kind:'Ref', handle:number, prop:string }}
+ */
+function Ref(handle, prop) {
+    return { kind: 'Ref', handle: handle, prop: prop };
+}
+
+/**
+ * Bin(op, a, b) — binary arithmetic node.
+ * op must be a member of BIN_OPS.
+ * @param {string} op
+ * @param {*} a — ExprAST
+ * @param {*} b — ExprAST
+ * @returns {{ kind:'Bin', op:string, a:*, b:* }}
+ */
+function Bin(op, a, b) {
+    return { kind: 'Bin', op: op, a: a, b: b };
+}
+
+/**
+ * Cmp(op, a, b) — comparison node.  Returns 1 or 0.
+ * op must be a member of CMP_OPS.
+ * @param {string} op
+ * @param {*} a — ExprAST
+ * @param {*} b — ExprAST
+ * @returns {{ kind:'Cmp', op:string, a:*, b:* }}
+ */
+function Cmp(op, a, b) {
+    return { kind: 'Cmp', op: op, a: a, b: b };
+}
+
+/**
+ * Cond(test, then_, else_) — conditional node.
+ * @param {*} test  — ExprAST; truthy when non-zero
+ * @param {*} then_ — ExprAST; result when test != 0
+ * @param {*} else_ — ExprAST; result when test == 0
+ * @returns {{ kind:'Cond', test:*, then:*, else:* }}
+ */
+function Cond(test, then_, else_) {
+    return { kind: 'Cond', test: test, then: then_, else: else_ };
+}
+
+/**
+ * Fn(name, args) — built-in function node.
+ * name must be a member of FN_NAMES.
+ * @param {string} name
+ * @param {Array<*>} args — ExprAST[]
+ * @returns {{ kind:'Fn', name:string, args:Array }}
+ */
+function Fn(name, args) {
+    return { kind: 'Fn', name: name, args: args };
+}
+
+/**
+ * StrLit(value) — string literal node (NODE_KINDS item 7).
+ *
+ * ONLY valid as the `to` value of a `set` op whose target is
+ * `<handle>.data.<key>` (a string-map write into the frame bubble).
+ *
+ * ILLEGAL as a child of Bin / Cmp / Fn / Cond.test — eval_expr is
+ * numeric-pure. The op-apply layer detects StrLit before calling eval_expr.
+ *
+ * @param {string} value
+ * @returns {{ kind:'StrLit', value:string }}
+ */
+function StrLit(value) {
+    return { kind: 'StrLit', value: value };
+}
+
+// ── Exports ────────────────────────────────────────────────────────────────────
+
+export {
+    NODE_KINDS,
+    OP_KINDS,
+    BIN_OPS,
+    CMP_OPS,
+    FN_NAMES,
+    TRIGGERS,
+    HANDLE_FRAME,
+    HANDLE_SELF,
+    HANDLE_UNIVERSE,
+    Lit,
+    Ref,
+    Bin,
+    Cmp,
+    Cond,
+    Fn,
+    StrLit
+};