CycleChecker class

A specialized Traversal Guard and Topology Validator, responsible for preventing infinite recursion and ensuring the reactive graph remains a Directed Acyclic Graph (DAG) during signal propagation.

CycleChecker acts as the "Short-Term Memory" of a reactive wave. It tracks the path of a Pulse as it traverses through various nodes, identifying and halting any attempts to re-enter a node that has already participated in the current execution cycle.

When to use

• Graph Integrity: Use whenever a signal propagates through a network where complex, interdependent relationships might lead to circular triggers.
• Stack Protection: Use to prevent StackOverflowError in deeply nested or recursively defined reactive structures.
• Traversal Auditing: Use during debugging to trace the causal path of a specific stimulus.

How it works

1. Registry Synthesis: Maintains a transient set of Cell identities representing the "Visited Nodes" of the current propagation wave.
2. Causal Registration: Before a Receptor processes a pulse, it registers itself via the add method.
3. Conflict Detection: If the registration fails (node already visited), a Circular Dependency is identified.
4. Graceful Termination: Instead of crashing, the system suppresses further propagation along the offending branch, allowing the rest of the graph to settle normally.

Non‑obvious

• Identity-Based: Tracking is performed using referential identity of the Cell instances, not their values or states.
• Single-Wave Lifecycle: Instances are intended to be ephemeral, typically mapping 1:1 with the lifespan of a single Pulse wave.
• Concurrency Bridge: While optimized for synchronous execution, it seamlessly transitions to thread-safe mode via the async property (SyncCycleChecker) when crossing asynchronous boundaries.
• Zero-Overhead for Linear Paths: The internal _visited set is highly optimized for small collections, minimizing the latency penalty for most propagation paths.

Example

void propagate(Pulse pulse, Cell node) {
  // Check for cycles before processing
  if (!pulse.checker.add(node)) {
    print('Cycle detected at $node; halting branch.');
    return;
  }

  // Safe to proceed with transformation
  node.process(pulse);
}

See Also:

• SyncCycleChecker: The synchronized counterpart for asynchronous flows.
• Pulse: The stimulus that carries the checker through the graph.
• Receptor: The primary component that implements this guard.