@hatiolab/figure-model 0.2.13 → 0.2.15

package/dist/graph.js

@@ -643,6 +643,22 @@ for (const [name, op] of Object.entries(ops))
 const IMPURE_OPERATORS = [];
 for (const [name, op] of Object.entries(ops))
     op.pure = !IMPURE_OPERATORS.includes(name);
+/*
+  The operators a pose step may run (ADR-0108 decision 3): arithmetic, transforms, and what carries a pose -- placing,
+  assembling, repeating, selecting. Not a shape, a layout, a pitch or a feature of a shape: an input that reaches one
+  changes what is drawn, not only where. An operator added without a form here is left out of the fast path, and the
+  test that holds \`FIGURE_POSE_EXCLUDED_OPERATORS\` still says so.
+*/
+const POSE_FORMS = [
+    'add@1', 'mul@1', 'div@1', 'sin@1', 'geomean@1', 'curve@1', 'at-least@1', 'max@1', 'min@1', 'affine-bounds@1', 'between@1',
+    'assembly@1', 'repeat@1', 'select-item@1', 'rigid@1', 'axis-turn@1', 'axis-slide@1', 'compose@1', 'attach@1',
+    'point@1', 'map-point@1', 'distance@1', 'place@1', 'member@1'
+];
+for (const [name, op] of Object.entries(ops))
+    if (op.pure && POSE_FORMS.includes(name))
+        op.poseForm = 'run';
+/** The operators a pose step does not run: an input whose reach holds one goes by an ordinary evaluation. */
+export const FIGURE_POSE_EXCLUDED_OPERATORS = Object.freeze(Object.keys(ops).filter(k => !ops[k].poseForm));
 /** Every operator's state policy, by name, for the guard test and for readers of the contract. */
 export const FIGURE_OPERATOR_STATE_POLICY = Object.freeze(Object.fromEntries(Object.entries(ops).map(([k, op]) => [k, op.state])));
 /** Every operator's purity, by name, for the guard test and for readers of the evaluator. */
@@ -675,9 +691,64 @@ function checkedValue(value, type, path) {
             fail('COUNT', path, 'nonnegative safe integer required');
         return value;
     }
-    finite(value, path);
+    /*
+      By the value's type, where it says where the numbers are: a transform's are its r and t; a placed thing's are its
+      pose, its shape being the very object its shape node produced and this check already passed. The same numbers in
+      the same order as the walk below, without its bookkeeping for the two kinds a moving figure makes most of.
+    */
+    if (type.kind === 'transform' && isPose(value))
+        finitePose(value, path);
+    else if (type.kind === 'placed' && keysAre(value, 'shape', 'pose') && finiteObjects.has(value.shape) && isPose(value.pose))
+        finitePose(value.pose, path);
+    else {
+        finite(value, path);
+        /* A shape is what copies and placed things carry again and again: it is remembered, nothing else is. */
+        if (type.kind === 'shape' && value && typeof value === 'object')
+            finiteObjects.add(value);
+    }
     return value;
 }
+/** Whether a value's own keys are exactly these two, in this order -- without making the list of them. */
+const keysAre = (v, a, b) => {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    let n = 0;
+    for (const k in v) {
+        if (!Object.hasOwn(v, k))
+            continue;
+        if (n > 1 || k !== (n === 0 ? a : b))
+            return false;
+        n++;
+    }
+    return n === 2;
+};
+const isPose = (v) => keysAre(v, 'r', 't') && Array.isArray(v.r) && Array.isArray(v.t);
+/** A list's numbers in order, the first one not finite refused; anything else in it walked as \`finite\` walks it. */
+function finiteList(list, path) {
+    for (let i = 0; i < list.length; i++) {
+        if (!(i in list))
+            continue;
+        const x = list[i];
+        if (typeof x === 'number') {
+            if (!Number.isFinite(x))
+                fail('NON_FINITE', path, String(x));
+        }
+        else
+            finite(x, path);
+    }
+}
+function finitePose(p, path) {
+    for (let i = 0; i < p.r.length; i++) {
+        if (!(i in p.r))
+            continue;
+        const row = p.r[i];
+        if (Array.isArray(row))
+            finiteList(row, path);
+        else
+            finite(row, path);
+    }
+    finiteList(p.t, path);
+}
 /*
   Every number in a value is finite: the first one that is not, depth first in key order, is refused. A plain loop:
   a repeat's output holds every copy's pose, and the walk with a closure and forEach per level was most of what
@@ -695,10 +766,25 @@ function finite(v, path) {
     }
     else if (v && typeof v === 'object') {
         const keys = Object.keys(v);
+        /* A pose -- two lists of numbers -- is walked: remembering it costs more than walking it. */
+        const small = keys.length <= 2 && Array.isArray(v[keys[0]]) && (keys.length < 2 || Array.isArray(v[keys[1]]));
+        if (!small && finiteObjects.has(v))
+            return;
         for (let i = 0; i < keys.length; i++)
             finite(v[keys[i]], path);
     }
 }
+/*
+  Shapes already found finite. A computed value is never written after it is made (the evaluator hands unchanged
+  values on as the same objects), so one found finite stays so: a row's twenty-four copies carry the one shape of the
+  member they copy, and that shape -- most of the numbers -- was walked again for every copy at every turn (51% of a
+  turning roller row, 2026-10-03). Only shapes are remembered: remembering every object kept a table the size of the
+  busiest moment (4 MB after 500 conveyors were made and dropped).
+*/
+const finiteObjects = new WeakSet();
+/** What a pose step may change: numbers, transforms, and what carries a pose. A shape, a layout, a count or a flag may not. */
+const POSE_KINDS = ['transform', 'placed', 'assembly', 'collection', 'point'];
+const notPose = (t) => (Array.isArray(t) || POSE_KINDS.includes(t?.kind) ? undefined : String(t?.kind ?? 'value'));
 export function compileFigureGraph(source) {
     return compileInternal(source);
 }
@@ -794,6 +880,29 @@ function compileInternal(source) {
         visit(name);
     /** An instance evaluator's walk, made on first use (`walkOf`). */
     let walk;
+    /** The pose analyses made so far, by what reads the graph (`poseAnalysisOf`). */
+    const analyses = new Map();
+    /*
+      The one check of an input record (ADR-0108 C1): a whole evaluation, an instance's next evaluation and a pose step
+      all take their inputs through these two, so a value refused one way is refused every way.
+    */
+    const inputIds = new Set(m.inputs.map(p => p.id));
+    function inputFields(input) {
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            fail('SCHEMA', 'input values', 'object required');
+        for (const p of m.inputs)
+            if (!Object.hasOwn(input, p.id))
+                fail('SCHEMA', 'input values', `missing ${p.id}`);
+        for (const k of Object.keys(input))
+            if (!inputIds.has(k))
+                fail('SCHEMA', 'input values', `unknown ${k}`);
+    }
+    function inputValue(p, given) {
+        const raw = num(given, p.id);
+        if (raw < p.min || raw > p.max)
+            fail('INPUT_RANGE', p.id, `${raw} outside [${p.min},${p.max}]`);
+        return checkedValue(raw * unit(p.unit, p.id)[1], types.get(p.id), p.id);
+    }
     /*
       One evaluation. Given the last one, only what the changed inputs reach runs again (user's decision 2026-09-26: a
       figure whose controls move re-evaluated every body every frame -- 2.2 us a body, 26.7 ms for sixty turning
@@ -802,14 +911,11 @@ function compileInternal(source) {
       tests compare the two over random sequences of inputs.
     */
     function run(input, previous) {
-        fields(input, m.inputs.map(p => p.id), [], 'input values');
+        inputFields(input);
         const values = new Map(), geometry = [], bodies = new Map(), changed = new Set();
         for (const p of m.inputs) {
-            const raw = num(input[p.id], p.id);
-            if (raw < p.min || raw > p.max)
-                fail('INPUT_RANGE', p.id, `${raw} outside [${p.min},${p.max}]`);
-            values.set(p.id, checkedValue(raw * unit(p.unit, p.id)[1], types.get(p.id), p.id));
-            if (!previous || previous.input[p.id] !== raw)
+            values.set(p.id, inputValue(p, input[p.id]));
+            if (!previous || previous.input[p.id] !== input[p.id])
                 changed.add(p.id);
         }
         for (const p of m.constants)
@@ -853,20 +959,61 @@ function compileInternal(source) {
          * (chief architect's ruling 2026-09-26: the compiled graph is shared, the last values belong to the instance -- sixty
          * conveyors of one type sharing one cache would break it at every call). A throw drops what it kept.
          */
-        evaluator() {
+        evaluator(options = {}) {
             let kept;
+            /*
+              The generation (ADR-0108): while it stands, body slot n is the same body -- the same id at the same place in the
+              geometry. It moves on with a whole evaluation (the first, and the one after a refusal) and with an evaluation
+              whose bodies differ from the last one's.
+            */
+            let generation = 0;
+            let ids = [];
+            /* What reads this graph does not change under an evaluator: its analysis is looked up once. */
+            let analysis;
+            const evaluated = (result, whole) => {
+                const now = result.geometry.map((g) => g.id);
+                if (whole || now.length !== ids.length || now.some((id, i) => id !== ids[i]))
+                    generation++;
+                ids = now;
+                return result;
+            };
+            const evaluate = (input) => {
+                const previous = kept;
+                kept = undefined;
+                if (!previous) {
+                    const whole = run(input, undefined);
+                    kept = hold(whole.kept, whole.result);
+                    return evaluated(whole.result, true);
+                }
+                const result = step(input, previous);
+                kept = previous;
+                return evaluated(result, false);
+            };
             return {
-                evaluate(input) {
-                    const previous = kept;
-                    kept = undefined;
-                    if (!previous) {
-                        const whole = run(input, undefined);
-                        kept = hold(whole.kept, whole.result);
-                        return whole.result;
+                evaluate,
+                /**
+                 * One step (ADR-0108): poses alone when every changed input takes the fast path, an evaluation otherwise --
+                 * with why. The inputs are checked as an evaluation checks them; a refusal drops what was kept, as it does there.
+                 * \`evaluate\` (\`ordinary\` names why) takes no fast path.
+                 */
+                advance(input, ordinary) {
+                    if (kept && !ordinary) {
+                        const previous = kept;
+                        kept = undefined;
+                        const step = poseStep(input, previous, (analysis ??= poseAnalysisOf(options.reads)));
+                        kept = previous;
+                        if ('result' in step)
+                            return { ...step.result, generation };
+                        const result = evaluate(input);
+                        return { kind: 'evaluation', result, generation, why: step.why };
                     }
-                    const result = step(input, previous);
-                    kept = previous;
-                    return result;
+                    const bound = !!kept;
+                    const result = evaluate(input);
+                    return { kind: 'evaluation', result, generation, why: { code: bound ? ordinary : 'NOT_BOUND' } };
+                },
+                /** Which inputs take the fast path for what reads this graph, and why the others do not. */
+                poseInputs() {
+                    return poseAnalysisOf(options.reads).inputs.map(a => ({ ...a }));
                 }
             };
         }
@@ -920,13 +1067,12 @@ function compileInternal(source) {
         const always = [...new Set([...impure.map(node => node.index), ...reachOf(impure.flatMap(node => node.outs))])].sort((a, b) => a - b);
         walk = {
             keys,
+            slot,
             nodes,
-            ids: new Set(m.inputs.map(p => p.id)),
+            readers,
             reach: m.inputs.map((_, i) => reachOf([i])),
             always,
-            shapes: nodes.filter(node => node.op.geometry).map(node => node.index),
-            scale: m.inputs.map(p => unit(p.unit, p.id)[1]),
-            inputTypes: m.inputs.map(p => types.get(p.id))
+            shapes: nodes.filter(node => node.op.geometry).map(node => node.index)
         };
         return walk;
     }
@@ -951,16 +1097,198 @@ function compileInternal(source) {
       of its own -- a new values record and a new geometry list, copied from the evaluator's own -- so a result kept by a
       caller does not change when the evaluator moves on, and a caller writing into one does not change the next.
     */
+    /*
+      Which inputs take the fast path (ADR-0108 decision 2), decided from everything each one reaches: every node it
+      reaches has a pose form, every value it changes is a number or carries a pose, and nothing outside the graph that
+      may not change reads one. Made once per plan and what reads it.
+    */
+    function poseAnalysisOf(reads = {}) {
+        const key = JSON.stringify([reads.forbidden ?? {}, [...(reads.external ?? [])].sort()]);
+        const held = analyses.get(key);
+        if (held)
+            return held;
+        const w = walkOf();
+        const forbidden = reads.forbidden ?? {};
+        const external = new Set(reads.external ?? []);
+        const inputs = m.inputs.map((p, i) => {
+            const kind = notPose(types.get(p.id));
+            if (kind)
+                return { fast: false, code: 'INPUT_NOT_POSE', input: p.id, node: p.id, reaches: kind };
+            if (Object.hasOwn(forbidden, p.id))
+                return { fast: false, code: 'INPUT_NOT_POSE', input: p.id, node: p.id, reaches: forbidden[p.id] };
+            for (const index of w.reach[i]) {
+                const node = w.nodes[index];
+                if (!node.op.poseForm)
+                    return { fast: false, code: 'UNSUPPORTED_OPERATOR', input: p.id, node: node.n.id, op: node.n.op };
+                for (const [k, s] of node.outs.entries()) {
+                    const kind = notPose(node.types[k]);
+                    if (kind)
+                        return { fast: false, code: 'INPUT_NOT_POSE', input: p.id, node: node.n.id, reaches: kind };
+                    const ref = w.keys[s];
+                    if (Object.hasOwn(forbidden, ref))
+                        return { fast: false, code: 'INPUT_NOT_POSE', input: p.id, node: node.n.id, reaches: forbidden[ref] };
+                }
+            }
+            return { fast: true };
+        });
+        /* A row whose copies nothing reads -- no node, nothing outside -- is written by its poses alone. */
+        const terminal = w.nodes.map(node => node.n.op === 'repeat@1' && !node.n.params?.within && node.outs.every(s => !w.readers[s].length && !external.has(w.keys[s])));
+        const made = { inputs, terminal, visits: new Map() };
+        analyses.set(key, made);
+        return made;
+    }
+    /* The nodes a set of changed inputs reaches, once each, in order -- made once per set and kept with the analysis. */
+    function visitOf(moved, analysis) {
+        const w = walkOf();
+        if (moved.length === 1)
+            return w.reach[moved[0]];
+        const key = moved.join();
+        let visit = analysis.visits.get(key);
+        if (!visit) {
+            const seen = new Set();
+            for (const i of moved)
+                for (const n of w.reach[i])
+                    seen.add(n);
+            visit = [...seen].sort((a, b) => a - b);
+            if (analysis.visits.size < 256)
+                analysis.visits.set(key, visit);
+        }
+        return visit;
+    }
+    function bindFast(held) {
+        const w = walkOf();
+        const start = new Int32Array(w.nodes.length).fill(-1);
+        let at = 0;
+        for (const index of w.shapes) {
+            start[index] = at;
+            at += held.bodies[index]?.length ?? 0;
+        }
+        return { raw: held.raw.slice(), slots: held.slots.slice(), mark: new Int32Array(w.keys.length), epoch: 0, start, bodyCount: at, prefix: new Map() };
+    }
+    /*
+      A pose step (ADR-0108): every changed input takes the fast path, so only poses move. The reach of the changed inputs
+      runs once, in order, each node by its own run as an evaluation runs it -- the same operations in the same order, so
+      the poses are an evaluation's to the bit (same engine). A row nothing reads has its copies composed straight into the
+      pose list: compose(compose(pose, offset), member), the offset part made once while the row's pose stands.
+      Returns undefined, having changed nothing, when an input does not take the fast path.
+    */
+    function poseStep(input, held, analysis) {
+        const w = walkOf();
+        inputFields(input);
+        const fast = (held.fast ??= bindFast(held));
+        const moved = [];
+        const values = [];
+        for (let i = 0; i < m.inputs.length; i++) {
+            const p = m.inputs[i];
+            const given = input[p.id];
+            if (given === fast.raw[i])
+                continue;
+            values.push(inputValue(p, given));
+            moved.push(i);
+        }
+        for (const i of moved)
+            if (!analysis.inputs[i].fast)
+                return { why: analysis.inputs[i] };
+        const epoch = ++fast.epoch;
+        moved.forEach((i, k) => {
+            fast.raw[i] = input[m.inputs[i].id];
+            fast.slots[i] = values[k];
+            fast.mark[i] = epoch;
+        });
+        const visit = visitOf(moved, analysis);
+        const bodies = new Int32Array(fast.bodyCount);
+        const poses = new Float64Array(fast.bodyCount * 12);
+        let written = 0;
+        const write = (slot, pose) => {
+            const r = pose.r, t = pose.t, o = written * 12;
+            bodies[written++] = slot;
+            poses[o] = r[0][0];
+            poses[o + 1] = r[0][1];
+            poses[o + 2] = r[0][2];
+            poses[o + 3] = r[1][0];
+            poses[o + 4] = r[1][1];
+            poses[o + 5] = r[1][2];
+            poses[o + 6] = r[2][0];
+            poses[o + 7] = r[2][1];
+            poses[o + 8] = r[2][2];
+            poses[o + 9] = t[0];
+            poses[o + 10] = t[1];
+            poses[o + 11] = t[2];
+        };
+        for (const index of visit) {
+            const node = w.nodes[index];
+            let reached = false;
+            for (const s of node.args)
+                if (fast.mark[s] === epoch) {
+                    reached = true;
+                    break;
+                }
+            if (!reached)
+                continue;
+            const args = new Array(node.args.length);
+            for (let k = 0; k < node.args.length; k++)
+                args[k] = fast.slots[node.args[k]];
+            if (analysis.terminal[index]) {
+                const [layout, assembly, pose, rise] = args;
+                const axis = ['x', 'y', 'z'].indexOf(node.n.params.axis), up = ['x', 'y', 'z'].indexOf(node.n.params.riseAxis);
+                /* The offsets stand while the row's own pose and rise do (its layout is never a pose step's to change). */
+                const steady = fast.mark[node.args[2]] !== epoch && (node.args[3] === undefined || fast.mark[node.args[3]] !== epoch);
+                let prefix = steady ? fast.prefix.get(index) : undefined;
+                if (!prefix) {
+                    prefix = [];
+                    for (let i = 0; i < layout.count; i++) {
+                        const t = [0, 0, 0];
+                        t[axis] = layout.centers[i];
+                        if (rise !== undefined)
+                            t[up] = i * rise;
+                        prefix.push(compose(pose, { r: identity(), t }));
+                    }
+                    fast.prefix.set(index, prefix);
+                }
+                let slot = fast.start[index];
+                for (let i = 0; i < layout.count; i++)
+                    for (const member of assembly.members) {
+                        const p = compose(prefix[i], member.pose);
+                        finite(p, node.n.id);
+                        write(slot++, p);
+                    }
+                continue;
+            }
+            const out = node.op.run(args, node.n.id, node.n);
+            node.outs.forEach((s, i) => {
+                fast.slots[s] = checkedValue(out[i], node.types[i], node.n.id);
+                fast.mark[s] = epoch;
+            });
+            if (node.op.geometry) {
+                const g = node.op.geometry(args, out, node.n);
+                const own = Array.isArray(g) ? g : [g];
+                let slot = fast.start[index];
+                for (const body of own)
+                    write(slot++, body.pose);
+            }
+        }
+        const result = {
+            kind: 'poses',
+            generation: 0,
+            bodies: bodies.slice(0, written),
+            poses: poses.slice(0, written * 12),
+            read: (ref) => {
+                const s = w.slot.get(ref);
+                if (s === undefined)
+                    fail('TARGET_ABSENT', ref, 'no such value');
+                return fast.slots[s];
+            },
+            changed: (ref) => {
+                const s = w.slot.get(ref);
+                return s !== undefined && fast.mark[s] === epoch;
+            }
+        };
+        return { result };
+    }
     function step(input, held) {
         const w = walkOf();
-        if (!input || typeof input !== 'object' || Array.isArray(input))
-            fail('SCHEMA', 'input values', 'object required');
-        for (const p of m.inputs)
-            if (!Object.hasOwn(input, p.id))
-                fail('SCHEMA', 'input values', `missing ${p.id}`);
-        for (const k of Object.keys(input))
-            if (!w.ids.has(k))
-                fail('SCHEMA', 'input values', `unknown ${k}`);
+        inputFields(input);
+        held.fast = undefined;
         const epoch = ++held.epoch;
         const touched = [];
         let moved = -1;
@@ -970,11 +1298,8 @@ function compileInternal(source) {
             /* The same number as last time passed every check then. */
             if (given === held.raw[i])
                 return;
-            const raw = num(given, p.id);
-            if (raw < p.min || raw > p.max)
-                fail('INPUT_RANGE', p.id, `${raw} outside [${p.min},${p.max}]`);
-            held.slots[i] = checkedValue(raw * w.scale[i], w.inputTypes[i], p.id);
-            held.raw[i] = raw;
+            held.slots[i] = inputValue(p, given);
+            held.raw[i] = given;
             held.mark[i] = epoch;
             touched.push(i);
             if (moved >= 0)