@hatiolab/figure-model 0.3.2 → 0.3.3

package/dist/graph.js

@@ -708,6 +708,62 @@ function checkedValue(value, type, path) {
     }
     return value;
 }
+/*
+  Who owns what an instance's evaluator returns (completeness review 2026-10-04, F1). Its slots hold the values it runs
+  on, and an unchanged one is handed on, as the same object, to the next result and stays in the results given before.
+  A caller's write into one used to reach the next evaluation (a shape's size.x written as 999 came back as 999).
+
+  Shapes are frozen where they are: they are made when a design value changes, and a renderer keeps its plan while a
+  body's shape is the same object. Everything else a result holds -- poses, placed things, rows, bodies -- is a frozen
+  copy of the slot's value, made when the value changes and handed on unchanged after that; the slots themselves stay
+  as they were made. Freezing the slots in place cost more than the copies: a frozen list of numbers holds them boxed,
+  so a pose step reading frozen poses ran 50% slower, and the 6-axis robot's evaluation with every joint moved took
+  35 us instead of 12 (2026-10-04, Node 24). A whole evaluation keeps nothing, and all of it is the caller's.
+*/
+function frozen(v) {
+    if (!v || typeof v !== 'object' || Object.isFrozen(v))
+        return v;
+    Object.freeze(v);
+    if (Array.isArray(v))
+        for (let i = 0; i < v.length; i++)
+            frozen(v[i]);
+    else
+        for (const k in v)
+            frozen(v[k]);
+    return v;
+}
+/**
+ * The frozen copy of a value a result holds. Something already frozen -- a shape, or a copy made before -- is itself;
+ * \`made\` holds the copies made in this call, so a pose a body and a value both carry is copied once.
+ */
+function publicOf(v, made) {
+    if (!v || typeof v !== 'object' || Object.isFrozen(v))
+        return v;
+    let p = made.get(v);
+    if (p)
+        return p;
+    if (isPose(v)) {
+        const r = new Array(v.r.length);
+        for (let i = 0; i < r.length; i++)
+            r[i] = Object.freeze(v.r[i].slice());
+        p = { r: Object.freeze(r), t: Object.freeze(v.t.slice()) };
+    }
+    else if (Array.isArray(v)) {
+        p = new Array(v.length);
+        for (let i = 0; i < v.length; i++)
+            p[i] = publicOf(v[i], made);
+    }
+    else {
+        p = {};
+        for (const k in v)
+            p[k] = publicOf(v[k], made);
+    }
+    Object.freeze(p);
+    made.set(v, p);
+    return p;
+}
+/** A geometry node's bodies: a placement's one, a row's many. */
+const bodiesOf = (g, id) => (Array.isArray(g) ? g : [{ id, ...g }]);
 /** 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))
@@ -785,6 +841,13 @@ 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'));
+/**
+ * Compiles a graph whatever order its nodes are written in, and however deep its chains (the walk keeps its own stack).
+ * It holds no size limit of its own: the byte and node limits -- 1 MiB of JSON, nesting 64, \`FIGURE_DOCUMENT_NODE_LIMIT\`
+ * nodes -- are the document's and the asset's (\`compileFigureDocument\`, \`compileFigureAsset\`), the entrances for what
+ * arrives from outside. A caller compiling a graph directly answers for its size, and its compile and evaluation take
+ * time and memory in proportion to it.
+ */
 export function compileFigureGraph(source) {
     return compileInternal(source);
 }
@@ -843,41 +906,62 @@ function compileInternal(source) {
             assign(output, n.id);
         nodes.set(n.id, n);
     }
+    /*
+      Depth first, in declaration order: a node is typed once every node it reads is (completeness review 2026-10-04, F3).
+      The walk keeps its own stack -- a chain of 2,000 nodes written last-first overflowed the engine's -- and gives the
+      order, the refusals and the cycle path the recursive walk gave: a cycle is named from where the walk entered it.
+    */
     const visited = new Set();
-    function visit(name) {
-        if (visited.has(name))
-            return;
-        if (active.includes(name))
+    const onPath = new Set();
+    const path = [];
+    const enter = (name) => {
+        if (onPath.has(name))
             fail('CYCLE', name, [...active, name].join(' -> '));
         active.push(name);
-        const n = nodes.get(name), op = ops[n.op];
-        const inputTypes = n.args.map(ref => {
-            if (!writers.has(ref))
-                fail('UNKNOWN_REFERENCE', n.id, ref);
-            if (!types.has(ref))
-                visit(writers.get(ref));
-            return types.get(ref);
-        });
-        const resultTypes = op.types(inputTypes, n.id, n);
-        const depends = new Set();
-        for (const ref of n.args)
-            for (const s of dependence.get(ref) ?? [])
-                depends.add(s);
-        if (depends.size) {
-            if (op.state === undefined)
-                fail('STATE_POLICY', n.id, `${n.op} declares no policy for a state-dependent argument (${[...depends].join(', ')})`);
-            if (op.state === 'refuses')
-                fail('TOPOLOGY_STATE', n.id, `${n.op} must depend on design inputs only; it depends on ${[...depends].join(', ')}`);
+        onPath.add(name);
+        path.push({ n: nodes.get(name), at: 0, inputTypes: [] });
+    };
+    for (const root of nodes.keys()) {
+        if (visited.has(root))
+            continue;
+        enter(root);
+        while (path.length) {
+            const frame = path[path.length - 1];
+            const n = frame.n;
+            if (frame.at < n.args.length) {
+                const ref = n.args[frame.at];
+                if (!writers.has(ref))
+                    fail('UNKNOWN_REFERENCE', n.id, ref);
+                if (!types.has(ref)) {
+                    enter(writers.get(ref));
+                    continue;
+                }
+                frame.inputTypes.push(types.get(ref));
+                frame.at++;
+                continue;
+            }
+            const op = ops[n.op];
+            const resultTypes = op.types(frame.inputTypes, n.id, n);
+            const depends = new Set();
+            for (const ref of n.args)
+                for (const s of dependence.get(ref) ?? [])
+                    depends.add(s);
+            if (depends.size) {
+                if (op.state === undefined)
+                    fail('STATE_POLICY', n.id, `${n.op} declares no policy for a state-dependent argument (${[...depends].join(', ')})`);
+                if (op.state === 'refuses')
+                    fail('TOPOLOGY_STATE', n.id, `${n.op} must depend on design inputs only; it depends on ${[...depends].join(', ')}`);
+            }
+            op.ports.forEach((p, i) => types.set(n.outputs[p], resultTypes[i]));
+            if (depends.size)
+                Object.values(n.outputs).forEach(ref => dependence.set(ref, new Set(depends)));
+            path.pop();
+            active.pop();
+            onPath.delete(n.id);
+            visited.add(n.id);
+            order.push(n);
         }
-        op.ports.forEach((p, i) => types.set(n.outputs[p], resultTypes[i]));
-        if (depends.size)
-            Object.values(n.outputs).forEach(ref => dependence.set(ref, new Set(depends)));
-        active.pop();
-        visited.add(name);
-        order.push(n);
     }
-    for (const name of nodes.keys())
-        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`). */
@@ -938,8 +1022,7 @@ function compileInternal(source) {
                 changed.add(n.outputs[p]);
             });
             if (op.geometry) {
-                const g = op.geometry(args, out, n);
-                const own = Array.isArray(g) ? g : [{ id: n.id, ...g }];
+                const own = bodiesOf(op.geometry(args, out, n), n.id);
                 bodies.set(n.id, own);
                 geometry.push(...own);
             }
@@ -970,6 +1053,8 @@ function compileInternal(source) {
             let ids = [];
             /* What reads this graph does not change under an evaluator: its analysis is looked up once. */
             let analysis;
+            /* Every call, refused or not; a pose step's \`read\` and \`changed\` answer while it is still the last one. */
+            let calls = 0;
             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]))
@@ -978,12 +1063,12 @@ function compileInternal(source) {
                 return result;
             };
             const evaluate = (input) => {
+                calls++;
                 const previous = kept;
                 kept = undefined;
                 if (!previous) {
-                    const whole = run(input, undefined);
-                    kept = hold(whole.kept, whole.result);
-                    return evaluated(whole.result, true);
+                    kept = hold(run(input, undefined).kept);
+                    return evaluated({ values: { ...kept.values }, geometry: kept.geometry.slice() }, true);
                 }
                 const result = step(input, previous);
                 kept = previous;
@@ -998,12 +1083,28 @@ function compileInternal(source) {
                  */
                 advance(input, ordinary) {
                     if (kept && !ordinary) {
+                        const call = ++calls;
                         const previous = kept;
                         kept = undefined;
                         const step = poseStep(input, previous, (analysis ??= poseAnalysisOf(options.reads)));
                         kept = previous;
-                        if ('result' in step)
-                            return { ...step.result, generation };
+                        if ('result' in step) {
+                            /*
+                              A pose step is not a snapshot: \`read\` and \`changed\` look into the evaluator as this step left it, and
+                              the next call moves it on. Past that they are refused rather than answering with a later step's values.
+                            */
+                            const { read, changed } = step.result;
+                            const live = () => {
+                                if (calls !== call)
+                                    fail('STEP_EXPIRED', 'advance', 'read a pose step before the next call on its evaluator');
+                            };
+                            return {
+                                ...step.result,
+                                generation,
+                                read: (ref) => (live(), read(ref)),
+                                changed: (ref) => (live(), changed(ref))
+                            };
+                        }
                         const result = evaluate(input);
                         return { kind: 'evaluation', result, generation, why: step.why };
                     }
@@ -1072,20 +1173,35 @@ function compileInternal(source) {
             readers,
             reach: m.inputs.map((_, i) => reachOf([i])),
             always,
-            shapes: nodes.filter(node => node.op.geometry).map(node => node.index)
+            shapes: nodes.filter(node => node.op.geometry).map(node => node.index),
+            shapeSlot: keys.map(k => types.get(k)?.kind === 'shape')
         };
         return walk;
     }
-    /** What an evaluator keeps between calls: its slots, its bodies by node, and its own copy of the last result. */
-    function hold(whole, result) {
+    /**
+     * What an evaluator keeps between calls: its slots, its bodies by node, and the last result as a caller is given it --
+     * frozen copies of the slots' values and bodies (\`publicOf\`), shapes frozen where they are.
+     */
+    function hold(whole) {
         const w = walkOf();
+        const slots = w.keys.map(k => whole.values.get(k));
+        slots.forEach((v, s) => w.shapeSlot[s] && frozen(v));
+        const bodies = w.nodes.map(node => whole.bodies.get(node.n.id));
+        const made = new Map();
+        const shown = bodies.map(own => own?.map(b => publicOf(b, made)));
+        const values = {};
+        w.keys.forEach((k, s) => (values[k] = publicOf(slots[s], made)));
+        const geometry = [];
+        for (const index of w.shapes)
+            if (shown[index])
+                geometry.push(...shown[index]);
         return {
             raw: m.inputs.map(p => whole.input[p.id]),
-            slots: w.keys.map(k => whole.values.get(k)),
-            bodies: w.nodes.map(node => whole.bodies.get(node.n.id)),
-            /* Copies: the caller owns what it was given, and what it does with it never reaches the next evaluation. */
-            values: { ...result.values },
-            geometry: result.geometry.slice(),
+            slots,
+            bodies,
+            shown,
+            values,
+            geometry,
             mark: new Int32Array(w.keys.length),
             ran: new Int32Array(w.nodes.length),
             epoch: 0
@@ -1094,8 +1210,9 @@ function compileInternal(source) {
     /*
       One evaluation after the first. The result is the one a whole evaluation gives: the same refusals for the same
       inputs, the same values in the same order, an unchanged body as the same object. What is returned is a snapshot
-      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.
+      of its own -- a new values record and a new geometry list, copied from the evaluator's own, holding frozen values and
+      bodies -- 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
@@ -1272,11 +1389,12 @@ function compileInternal(source) {
             generation: 0,
             bodies: bodies.slice(0, written),
             poses: poses.slice(0, written * 12),
+            /* What it hands out is a frozen copy, as an evaluation's values are. */
             read: (ref) => {
                 const s = w.slot.get(ref);
                 if (s === undefined)
                     fail('TARGET_ABSENT', ref, 'no such value');
-                return fast.slots[s];
+                return publicOf(fast.slots[s], new Map());
             },
             changed: (ref) => {
                 const s = w.slot.get(ref);
@@ -1321,6 +1439,8 @@ function compileInternal(source) {
             visit = all.sort((a, b) => a - b);
         }
         let reshaped = false;
+        /* The copies made in this call, so a pose a body and a value both carry is copied once. */
+        let made;
         for (const index of visit) {
             const node = w.nodes[index];
             if (node.op.pure && !node.args.some(s => held.mark[s] === epoch))
@@ -1329,21 +1449,24 @@ function compileInternal(source) {
             const out = node.op.run(args, node.n.id, node.n);
             node.outs.forEach((s, i) => {
                 held.slots[s] = checkedValue(out[i], node.types[i], node.n.id);
+                if (w.shapeSlot[s])
+                    frozen(held.slots[s]);
                 held.mark[s] = epoch;
                 touched.push(s);
             });
             if (node.op.geometry) {
-                const g = node.op.geometry(args, out, node.n);
-                held.bodies[index] = Array.isArray(g) ? g : [{ id: node.n.id, ...g }];
+                const own = bodiesOf(node.op.geometry(args, out, node.n), node.n.id);
+                held.bodies[index] = own;
+                held.shown[index] = own.map(b => publicOf(b, (made ??= new Map())));
                 reshaped = true;
             }
         }
         for (const s of touched)
-            held.values[w.keys[s]] = held.slots[s];
+            held.values[w.keys[s]] = publicOf(held.slots[s], (made ??= new Map()));
         if (reshaped) {
             const geometry = [];
             for (const index of w.shapes) {
-                const own = held.bodies[index];
+                const own = held.shown[index];
                 if (own)
                     geometry.push(...own);
             }