Core Execution & Performance

While the high-level architecture follows a "Digital Organism" metaphor, the internal mechanics rely on a robust transaction-based execution engine.

When a node's data or connection changes, the system triggers the Dirty Chain:

1. Mark Dirty: Identifies the changed node and all downstream dependencies. This is an $O(N)$ operation where $N$ is the number of downstream nodes.
2. Compute Path: Sorts the nodes topologically to prevent circular evaluation and redundant calculations.
3. Lazy Evaluate: Invokes pure Evaluator functions from the NodeRegistry only when a terminal node (e.g., a Plot or Final Output) requests a value.
4. Broadcast: Fires a graphChanged event. All connected UI nodes refresh their display results.

Every persistent mutation to the state (Adding a node, connecting an edge) MUST be wrapped in an atomic Transaction using applyTransaction.

This architecture provides:

• Perfect Undo/Redo: Since every action is recorded as a JSON patch array, the TransactionManager can jump between any point in time with 100% fidelity.
• Serialization: The entire graph state can be exported as a "Recipe" (IOGL structure) and re-hydrated instantly.

To guarantee a smooth 120 FPS experience during continuous UI interactions without blocking the main engine, we use two distinct cycles:

• The Stable Cycle: The deep-thinking mode of the Brain. It handles topological sorting and complex logic. It runs when a stable transaction occurs (e.g., dropping a node).
• The Transient Cycle (Spinal Reflex): During continuous high-frequency interactions (like dragging a slider), the useEye and useEar nerves handle transient state updates. The Brain applies a Light Evaluation Pass and purposefully does NOT record these micro-movements in the history stack, preventing the "Snapshot Trap."

When physically moving a node across the canvas, we rely on useEye's integration with React Flow's CSS transform matrix. The state only syncs the final (X, Y) coordinate back to the Brain upon completion, achieving zero-latency framerates even on massive, logic-heavy canvases.

Design Philosophy

The Input-Output system is designed to handle high-frequency interactions (120 FPS) while maintaining a globally consistent, engineer-ready mathematical state.

The core of our evaluation engine is a Hybrid Push/Pull system. This architecture ensures that we only compute what is strictly necessary, exactly when it needs to be updated.

When a node's internal state or its input connections change (a "Sensory Event"), the Brain triggers a Dirty Chain propagation.

• Direction: From the source node downstream to all children.
• Goal: Mark nodes as "Dirty" (out-of-date) without immediately recalculating them.
• Why: Recalculating everything immediately on every slider movement would freeze the UI. Marking them as dirty takes $O(1)$ time per node.

Calculations are performed only when a value is requested (e.g., by the UI for display or by the Worker for a background pass).

• Direction: Upstream from the target node towards its ancestors.
• Mechanism: The getValue() function recursively pulls values from its inputs. If an input is "Dirty," it is recalculated.
• Why: This minimizes redundant work. If a node is dirty but off-screen and not being used for any current output, it remains uncalculated.

To maintain responsiveness, the system distinguishes between Transient and Persistent states.

• Context: Rapid user actions like dragging a slider or moving a node.
• Behavior: The UI component updates its internal state at 120 FPS. The Brain applies a Light Evaluation Pass.
• History: These transient movements are not recorded in the Undo/Redo stack to prevent "Snapshot Overload."

• Context: Commit events like onDragStop or onSliderRelease.
• Behavior: A full Atomic Transaction is created. The topological graph is updated, and the new state is committed to the linear history.
• History: Every action here creates a perfect JSON patch, allowing for 100% fidelity in undo/redo and file serialization.

• Output Authority: Data flows strictly from Outputs to Inputs. An Input port is a consumer; it has no independent state.
• No Cycles: The topology manager enforces a Directed Acyclic Graph (DAG) for all calculations.
• Unified Precision: All operations within the engine share a single precision context, preventing "Rounding Drifts" common in heterogeneous math systems.