@cnstra/core 1.2.1 → 1.3.0

package/dist/index.cjs

@@ -19,52 +19,337 @@ var CNSStimulationContextStore = class {
       this.ctx.set(key, value);
     }
   }
+  delete(key) {
+    this.ctx.delete(key);
+  }
 };
 
-// src/CNS.ts
-var asArray = (x) => Array.isArray(x) ? x : [x];
-var isPromise = (v) => !!v && typeof v.then === "function";
-var Deque = class {
-  constructor() {
-    this.a = [];
+// src/CNSFunctionalQueue.ts
+var CNSFunctionalQueue = class {
+  constructor(processor, concurrency, abortSignal, initialCapacity) {
+    this.processor = processor;
+    this.concurrency = concurrency;
+    this.abortSignal = abortSignal;
+    this.items = [];
     this.head = 0;
+    this.tail = 0;
+    this.size = 0;
+    this.capacity = 16;
+    this.activeOperations = 0;
+    // NEW: prevent re-entrant pump; defer extra runs
+    this.pumping = false;
+    this.needsPump = false;
+    if (initialCapacity && initialCapacity > 0) {
+      this.capacity = initialCapacity;
+    }
+    this.items = new Array(this.capacity);
   }
-  push(x) {
-    this.a.push(x);
+  get canStartOperation() {
+    const limit = this.concurrency ?? Infinity;
+    return this.activeOperations < limit && !this.abortSignal?.aborted;
+  }
+  resize() {
+    const oldCapacity = this.capacity;
+    this.capacity = oldCapacity * 2;
+    const newItems = new Array(this.capacity);
+    let oldIndex = this.head;
+    for (let i = 0; i < this.size; i++) {
+      newItems[i] = this.items[oldIndex];
+      oldIndex = (oldIndex + 1) % oldCapacity;
+    }
+    this.items = newItems;
+    this.head = 0;
+    this.tail = this.size;
+  }
+  dequeue() {
+    if (this.size === 0) return void 0;
+    const item = this.items[this.head];
+    this.items[this.head] = void 0;
+    this.head = (this.head + 1) % this.capacity;
+    this.size--;
+    return item;
+  }
+  enqueueItem(item) {
+    if (this.size === this.capacity) {
+      this.resize();
+    }
+    this.items[this.tail] = item;
+    this.tail = (this.tail + 1) % this.capacity;
+    this.size++;
   }
-  shift() {
-    if (this.head >= this.a.length) return void 0;
-    const v = this.a[this.head++];
-    if (this.head > 1024 && this.head * 2 > this.a.length) {
-      this.a = this.a.slice(this.head);
-      this.head = 0;
+  pump() {
+    if (this.pumping) {
+      this.needsPump = true;
+      return;
+    }
+    this.pumping = true;
+    while (this.canStartOperation && this.size > 0) {
+      const item = this.dequeue();
+      this.activeOperations++;
+      const ret = this.processor(item);
+      if (ret && typeof ret.then === "function") {
+        ret.then(
+          (cb) => {
+            this.activeOperations--;
+            if (typeof cb === "function") cb();
+            if (this.size > 0 && this.canStartOperation) {
+              if (this.pumping) this.needsPump = true;
+              else this.pump();
+            }
+          },
+          (err) => {
+            this.activeOperations--;
+            if (this.size > 0 && this.canStartOperation) {
+              if (this.pumping) this.needsPump = true;
+              else this.pump();
+            }
+            throw err;
+          }
+        );
+        break;
+      }
+      this.activeOperations--;
+      if (typeof ret === "function") ret();
+    }
+    this.pumping = false;
+    if (this.needsPump) {
+      this.needsPump = false;
+      this.pump();
     }
-    return v;
+  }
+  enqueue(x) {
+    this.enqueueItem(x);
+    if (!this.pumping) this.pump();
+    else this.needsPump = true;
   }
   get length() {
-    return this.a.length - this.head;
+    return this.size;
+  }
+  getActiveOperationsCount() {
+    return this.activeOperations;
+  }
+};
+
+// src/CNSStimulation.ts
+var CNSStimulation = class {
+  constructor(cns, options) {
+    this.cns = cns;
+    this.options = options;
+    this.scheduledCount = 0;
+    /**
+     * Track active SCCs: SCC index -> count of active neurons in that SCC
+     */
+    this.activeSccCounts = /* @__PURE__ */ new Map();
+    this.ctx = options?.ctx ?? options?.createContextStore?.() ?? new CNSStimulationContextStore();
+    this.id = options?.stimulationId || Math.random().toString(36).slice(2);
+    this.queue = new CNSFunctionalQueue(
+      (item) => this.processQueueItem(item),
+      options?.concurrency,
+      options?.abortSignal
+    );
+    if (this.options?.maxNeuronHops) {
+      this.nueronVisitMap = /* @__PURE__ */ new Map();
+    }
+  }
+  get concurrencyEnabled() {
+    return this.options?.concurrency !== void 0 && this.options?.concurrency > 0;
+  }
+  get autoCleanupContextsEnabled() {
+    return this.cns?.options?.autoCleanupContexts ?? false;
+  }
+  /**
+   * Mark a neuron as active (being processed)
+   */
+  markNeuronActive(neuronId) {
+    if (!this.autoCleanupContextsEnabled) return;
+    this.incrementSccCount(neuronId);
+  }
+  /**
+   * Mark a neuron as inactive (finished processing)
+   */
+  markNeuronInactive(neuronId) {
+    if (!this.autoCleanupContextsEnabled) return;
+    this.decrementSccCount(neuronId);
+  }
+  /**
+   * Increment the active count for the SCC containing this neuron
+   */
+  incrementSccCount(neuronId) {
+    const sccIndex = this.cns.getSccIndexByNeuronId(neuronId);
+    if (sccIndex === void 0) return;
+    const currentCount = this.activeSccCounts.get(sccIndex) || 0;
+    this.activeSccCounts.set(sccIndex, currentCount + 1);
+  }
+  /**
+   * Decrement the active count for the SCC containing this neuron
+   */
+  decrementSccCount(neuronId) {
+    const sccIndex = this.cns.getSccIndexByNeuronId(neuronId);
+    if (sccIndex === void 0) return;
+    const currentCount = this.activeSccCounts.get(sccIndex) || 0;
+    const nextCount = Math.max(0, currentCount - 1);
+    this.activeSccCounts.set(sccIndex, nextCount);
+    if (currentCount === 0) {
+      console.warn(
+        `[CNSStimulation] Attempting to decrement SCC count below 0 for neuron ${neuronId}`
+      );
+    }
+  }
+  /**
+   * Check if a neuron can be guaranteed not to be visited again
+   */
+  canNeuronBeGuaranteedDone(neuronId) {
+    if (!this.autoCleanupContextsEnabled) return false;
+    return this.cns.canNeuronBeGuaranteedDone(
+      neuronId,
+      this.activeSccCounts
+    );
+  }
+  cleanupCtxIfNeeded(neuron2) {
+    if (this.autoCleanupContextsEnabled && this.canNeuronBeGuaranteedDone(neuron2.id)) {
+      this.ctx.delete(neuron2.id);
+    }
+  }
+  createSubscriberQueueItem(subscriber, inputSignal) {
+    if (this.options?.maxNeuronHops) {
+      if (this.nueronVisitMap?.get(subscriber.neuron.id) ?? 0 >= this.options?.maxNeuronHops) {
+        throw new Error(
+          `Max neuron hops reached for neuron "${subscriber.neuron.id}" when trying to enqueue subscriber "${subscriber.dendrite.collateral.id}" in stimulation "${this.id}"`
+        );
+      } else {
+        this.nueronVisitMap?.set(
+          subscriber.neuron.id,
+          (this.nueronVisitMap?.get(subscriber.neuron.id) ?? 0) + 1
+        );
+      }
+    }
+    return {
+      neuronId: subscriber.neuron.id,
+      subscriber,
+      inputSignal
+    };
+  }
+  processQueueItem(item) {
+    const { subscriber, inputSignal } = item;
+    const { neuron: neuron2, dendrite } = subscriber;
+    this.markNeuronActive(neuron2.id);
+    const response = dendrite.response(
+      inputSignal?.payload,
+      neuron2.axon,
+      {
+        get: () => this.ctx.get(neuron2.id),
+        set: (value) => this.ctx.set(neuron2.id, value)
+      },
+      this.options?.abortSignal
+    );
+    if (response instanceof Promise) {
+      return response.then(
+        (signal) => {
+          return () => {
+            this.markNeuronInactive(neuron2.id);
+            return this.processResponse(
+              inputSignal,
+              signal
+            );
+          };
+        },
+        (error) => {
+          return () => {
+            this.markNeuronInactive(neuron2.id);
+            return this.processResponse(
+              inputSignal,
+              void 0,
+              error
+            );
+          };
+        }
+      );
+    } else {
+      return () => {
+        this.markNeuronInactive(neuron2.id);
+        return this.processResponse(
+          inputSignal,
+          response
+        );
+      };
+    }
+  }
+  processResponse(inputSignal, outputSignal, error) {
+    const collateral2 = outputSignal?.collateral;
+    const ownerNeuron = collateral2 ? this.cns.getParentNeuronByCollateralId(collateral2.id) : void 0;
+    const subscribers = collateral2 ? this.cns.getSubscribers(collateral2.id) : [];
+    const subscriberQueueItems = [];
+    if (collateral2 && !error) {
+      if (ownerNeuron) {
+        this.cleanupCtxIfNeeded(ownerNeuron);
+      }
+      for (let i = 0; i < subscribers.length; i++) {
+        subscriberQueueItems.push(
+          this.createSubscriberQueueItem(subscribers[i], outputSignal)
+        );
+      }
+    }
+    this.scheduledCount += subscriberQueueItems.length;
+    this.options?.onResponse?.({
+      inputSignal,
+      outputSignal,
+      ctx: this.ctx,
+      queueLength: this.queue.length + this.scheduledCount,
+      hops: this.options?.maxNeuronHops && ownerNeuron ? this.nueronVisitMap?.get(ownerNeuron.id) ?? 0 : void 0,
+      error
+    });
+    for (let i = 0; i < subscriberQueueItems.length; i++) {
+      this.scheduledCount--;
+      this.queue.enqueue(subscriberQueueItems[i]);
+    }
+  }
+  responseToSignal(signal) {
+    const ownerNeuron = this.cns.getParentNeuronByCollateralId(
+      signal.collateral.id
+    );
+    if (ownerNeuron) {
+      this.markNeuronActive(ownerNeuron.id);
+    }
+    this.processResponse(void 0, signal);
   }
-  // Optional convenience if you need to inspect without removing:
-  // peek(): T | undefined { return this.a[this.head]; }
 };
+
+// src/CNS.ts
 var CNS = class {
-  constructor(neurons) {
+  constructor(neurons, options) {
     this.neurons = neurons;
+    this.options = options;
     /**
      * Fast lookup: collateralId -> list of (neuron, dendrite) subscribers.
      * Built once at construction time.
      */
     this.subIndex = /* @__PURE__ */ new Map();
+    this.parentNeuronByCollateralId = /* @__PURE__ */ new Map();
     /**
-     * Cached hashes for stable IDs to optimize dedup key generation.
+     * Strongly Connected Components of the neuron graph.
+     * Each component is a set of neuron IDs that can reach each other.
      */
-    this.neuronHashes = /* @__PURE__ */ new Map();
-    this.collateralHashes = /* @__PURE__ */ new Map();
-    this.buildIndex();
-    this.precomputeHashes();
+    this.stronglyConnectedComponents = [];
+    /**
+     * Quick lookup: neuron ID -> SCC index for fast reachability checks.
+     */
+    this.neuronToSCC = /* @__PURE__ */ new Map();
+    /**
+     * DAG of SCCs: SCC index -> set of SCC indices that can reach this SCC
+     */
+    this.sccDag = /* @__PURE__ */ new Map();
+    /**
+     * Precomputed ancestor sets for each SCC for fast reachability checks
+     */
+    this.sccAncestors = /* @__PURE__ */ new Map();
+    this.buildIndexes();
+    if (this.options?.autoCleanupContexts) {
+      this.buildSCC();
+    }
   }
-  buildIndex() {
+  buildIndexes() {
     this.subIndex.clear();
+    this.parentNeuronByCollateralId.clear();
     for (const neuron2 of this.neurons) {
       for (const dendrite of neuron2.dendrites) {
         const key = dendrite.collateral.id;
@@ -75,218 +360,210 @@ var CNS = class {
           arr
         );
       }
+      Object.values(neuron2.axon).forEach((collateral2) => {
+        this.parentNeuronByCollateralId.set(
+          collateral2.id,
+          neuron2
+        );
+      });
     }
   }
   /**
-   * Precompute hashes for stable neuron and collateral IDs to optimize
-   * dedup key generation during stimulation.
+   * Build the neuron graph where neurons are connected if one can stimulate the other.
    */
-  precomputeHashes() {
+  buildNeuronGraph() {
+    const graph = /* @__PURE__ */ new Map();
+    const neuronIds = this.neurons.map((n) => n.id);
+    for (const neuronId of neuronIds) {
+      graph.set(neuronId, /* @__PURE__ */ new Set());
+    }
     for (const neuron2 of this.neurons) {
-      this.getHash(neuron2.id, this.neuronHashes);
-      for (const dendrite of neuron2.dendrites) {
-        this.getHash(dendrite.collateral.id, this.collateralHashes);
+      const reachableNeurons = /* @__PURE__ */ new Set();
+      for (const axonKey in neuron2.axon) {
+        const collateral2 = neuron2.axon[axonKey];
+        const collateralId = collateral2.id;
+        const subscribers = this.subIndex.get(collateralId);
+        if (subscribers) {
+          for (const { neuron: targetNeuron } of subscribers) {
+            reachableNeurons.add(targetNeuron.id);
+          }
+        }
       }
+      graph.set(neuron2.id, reachableNeurons);
     }
+    return graph;
   }
   /**
-   * Simple but effective hash function for string keys.
+   * Build strongly connected components using Tarjan's algorithm.
    */
-  simpleHash(str) {
-    let hash = 0;
-    for (let i = 0; i < str.length; i++) {
-      const char = str.charCodeAt(i);
-      hash = (hash << 5) - hash + char;
-      hash = hash & hash;
+  buildSCC() {
+    const graph = this.buildNeuronGraph();
+    const neuronIds = this.neurons.map((n) => n.id);
+    const index = /* @__PURE__ */ new Map();
+    const lowlink = /* @__PURE__ */ new Map();
+    const onStack = /* @__PURE__ */ new Set();
+    const stack = [];
+    const components = [];
+    let currentIndex = 0;
+    const strongConnect = (neuronId) => {
+      index.set(neuronId, currentIndex);
+      lowlink.set(neuronId, currentIndex);
+      currentIndex++;
+      stack.push(neuronId);
+      onStack.add(neuronId);
+      const neighbors = graph.get(neuronId) || /* @__PURE__ */ new Set();
+      for (const neighbor of neighbors) {
+        if (!index.has(neighbor)) {
+          strongConnect(neighbor);
+          lowlink.set(
+            neuronId,
+            Math.min(lowlink.get(neuronId), lowlink.get(neighbor))
+          );
+        } else if (onStack.has(neighbor)) {
+          lowlink.set(
+            neuronId,
+            Math.min(lowlink.get(neuronId), index.get(neighbor))
+          );
+        }
+      }
+      if (lowlink.get(neuronId) === index.get(neuronId)) {
+        const component = /* @__PURE__ */ new Set();
+        let w;
+        do {
+          w = stack.pop();
+          onStack.delete(w);
+          component.add(w);
+        } while (w !== neuronId);
+        components.push(component);
+      }
+    };
+    for (const neuronId of neuronIds) {
+      if (!index.has(neuronId)) {
+        strongConnect(neuronId);
+      }
     }
-    return hash;
+    this.stronglyConnectedComponents = components;
+    for (let i = 0; i < components.length; i++) {
+      for (const neuronId of components[i]) {
+        this.neuronToSCC.set(neuronId, i);
+      }
+    }
+    this.buildSCCDAG(graph);
+    this.buildSCCAncestors();
   }
   /**
-   * Get or compute hash for a string, using cache for stable IDs.
+   * Build DAG between SCCs based on the original neuron graph
    */
-  getHash(str, cache) {
-    let hash = cache.get(str);
-    if (hash === void 0) {
-      hash = this.simpleHash(str);
-      if (cache.size > 1e3) {
-        const oldestKey = cache.keys().next().value;
-        if (oldestKey !== void 0) {
-          cache.delete(oldestKey);
+  buildSCCDAG(neuronGraph) {
+    this.sccDag.clear();
+    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
+      this.sccDag.set(i, /* @__PURE__ */ new Set());
+    }
+    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
+      const scc = this.stronglyConnectedComponents[i];
+      for (const neuronId of scc) {
+        const neighbors = neuronGraph.get(neuronId) || /* @__PURE__ */ new Set();
+        for (const neighborId of neighbors) {
+          const neighborSccIndex = this.neuronToSCC.get(neighborId);
+          if (neighborSccIndex !== void 0 && neighborSccIndex !== i) {
+            this.sccDag.get(neighborSccIndex).add(i);
+          }
         }
       }
-      cache.set(str, hash);
-    } else {
-      cache.delete(str);
-      cache.set(str, hash);
     }
-    return hash;
   }
   /**
-   * Create optimized dedup key using composite numeric hash.
-   * This replaces string concatenation with faster numeric operations.
-   * Includes hops to allow signals to pass through the same neuron at different levels.
+   * Precompute ancestor sets for each SCC for fast reachability checks
+   * Uses topological sort for efficient computation
    */
-  createDedupKey(neuronId, collateralId, spikeId, hops) {
-    const nHash = this.getHash(neuronId, this.neuronHashes);
-    const cHash = this.getHash(collateralId, this.collateralHashes);
-    const sHash = this.simpleHash(spikeId);
-    const hHash = this.simpleHash(hops.toString());
-    return `${nHash}:${cHash}:${sHash}:${hHash}`;
-  }
-  /**
-   * Fire-and-forget fan-out for a single queue item.
-   *
-   * Behavior:
-   * - Synchronous dendrite responses enqueue their outgoing signals immediately.
-   * - Asynchronous responses:
-   *     • We DO NOT await them (no per-item barrier).
-   *     • We attach `.then` to enqueue outgoing signals when ready.
-   *     • We notify the scheduler when the first async for this item starts,
-   *       and when the last async for this item settles.
-   * - No error handling: we do not try/catch. Rejections bubble via wireRejectionToRun().
-   *
-   * Returns:
-   *   boolean — whether this item launched any async work (>= 1 promises).
-   */
-  fanOutFireAndForget(incoming, allowType, seen, queue, ctx, enableDedup, onItemFirstAsyncStart, onItemAllAsyncSettled, onAnyAsyncSettled, onTrace) {
-    const subscribers = this.subIndex.get(incoming.collateralId);
-    if (!subscribers || subscribers.length === 0) return false;
-    const nextHop = incoming.hops + 1;
-    const spikeId = incoming.spikeId;
-    const enqueueOut = (out) => {
-      if (out == null) return;
-      for (const spike of asArray(out)) {
-        const t = spike.type;
-        if (allowType && !allowType(t)) continue;
-        queue.push({
-          collateralId: t,
-          payload: spike.payload,
-          hops: nextHop,
-          spikeId
-        });
+  buildSCCAncestors() {
+    this.sccAncestors.clear();
+    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
+      this.sccAncestors.set(i, /* @__PURE__ */ new Set());
+    }
+    const inDegree = /* @__PURE__ */ new Map();
+    const queue = [];
+    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
+      const incomingEdges = this.sccDag.get(i) || /* @__PURE__ */ new Set();
+      inDegree.set(i, incomingEdges.size);
+      if (incomingEdges.size === 0) {
+        queue.push(i);
       }
-    };
-    let openAsync = 0;
-    let itemMarkedAsync = false;
-    for (const { neuron: neuron2, dendrite } of subscribers) {
-      const dedupKey = enableDedup ? this.createDedupKey(
-        neuron2.id,
-        incoming.collateralId,
-        incoming.spikeId,
-        incoming.hops
-      ) : void 0;
-      if (dedupKey && seen.has(dedupKey)) continue;
-      if (dedupKey) seen.add(dedupKey);
-      const res = dendrite.response(incoming.payload, neuron2.axon, {
-        get: () => ctx.get(neuron2.id),
-        set: (value) => ctx.set(neuron2.id, value)
-      });
-      if (isPromise(res)) {
-        if (!itemMarkedAsync) {
-          itemMarkedAsync = true;
-          onItemFirstAsyncStart();
+    }
+    while (queue.length > 0) {
+      const current = queue.shift();
+      const outgoingEdges = this.getOutgoingEdges(current);
+      for (const neighbor of outgoingEdges) {
+        const neighborAncestors = this.sccAncestors.get(neighbor);
+        neighborAncestors.add(current);
+        const currentAncestors = this.sccAncestors.get(current);
+        for (const ancestor of currentAncestors) {
+          neighborAncestors.add(ancestor);
+        }
+        const newInDegree = (inDegree.get(neighbor) || 0) - 1;
+        inDegree.set(neighbor, newInDegree);
+        if (newInDegree === 0) {
+          queue.push(neighbor);
         }
-        openAsync++;
-        res.then(
-          (out) => {
-            enqueueOut(out);
-            openAsync--;
-            onAnyAsyncSettled();
-            if (openAsync === 0) {
-              onItemAllAsyncSettled();
-            }
-          },
-          (err) => {
-            onTrace?.({
-              collateralId: incoming.collateralId,
-              hops: incoming.hops,
-              payload: incoming.payload,
-              queueLength: queue.length,
-              error: err,
-              contextStore: ctx
-              // Pass the context store interface
-            });
-            openAsync--;
-            onAnyAsyncSettled();
-            if (openAsync === 0) {
-              onItemAllAsyncSettled();
-            }
-          }
-        );
-      } else {
-        enqueueOut(res);
       }
     }
-    return itemMarkedAsync;
-  }
-  stimulate(collateral2, payload, opts) {
-    const ctx = opts?.ctx ?? opts?.createContextStore?.() ?? new CNSStimulationContextStore();
-    const spikeId = opts?.spikeId || Math.random().toString(36).slice(2);
-    const maxHops = opts?.maxHops;
-    const limit = (opts?.concurrency ?? 0) > 0 ? opts.concurrency : Infinity;
-    const queue = new Deque();
-    queue.push({
-      collateralId: collateral2.id,
-      payload,
-      hops: 0,
-      spikeId
-    });
-    const seen = /* @__PURE__ */ new Set();
-    let activeOperations = 0;
-    const startOperation = () => {
-      activeOperations++;
-    };
-    const finishOperation = () => {
-      activeOperations--;
-      tryProcessMore();
-    };
-    const canStartOperation = () => {
-      return activeOperations < limit && !opts?.abortSignal?.aborted;
-    };
-    const processItem = (item) => {
-      opts?.onTrace?.({
-        collateralId: item.collateralId,
-        hops: item.hops,
-        payload: item.payload,
-        queueLength: queue.length,
-        contextStore: ctx
-        // Pass the context store
-      });
-      if (maxHops && item.hops >= maxHops) {
-        finishOperation();
-        return;
-      }
-      const onOperationComplete = () => {
-        finishOperation();
-      };
-      const onAsyncStart = () => {
-      };
-      const launchedAsync = this.fanOutFireAndForget(
-        item,
-        opts?.allowType,
-        seen,
-        queue,
-        ctx,
-        maxHops !== void 0,
-        // Enable dedup only if maxHops is set
-        onAsyncStart,
-        onOperationComplete,
-        tryProcessMore,
-        // Continue streaming on any completion
-        opts?.onTrace
-      );
-      if (!launchedAsync) {
-        finishOperation();
+  }
+  /**
+   * Get outgoing edges for a given SCC index
+   */
+  getOutgoingEdges(sccIndex) {
+    const outgoing = /* @__PURE__ */ new Set();
+    for (const [targetScc, incomingEdges] of this.sccDag) {
+      if (incomingEdges.has(sccIndex)) {
+        outgoing.add(targetScc);
       }
-    };
-    const tryProcessMore = () => {
-      while (queue.length && canStartOperation()) {
-        const item = queue.shift();
-        startOperation();
-        processItem(item);
+    }
+    return outgoing;
+  }
+  /**
+   * Check if a neuron can be reached again (including self-calling).
+   * Returns true if the neuron is in a strongly connected component with more than one member,
+   * or if it's in a single-member SCC that can reach itself.
+   */
+  getSCCSetByNeuronId(neuronId) {
+    const sccIndex = this.neuronToSCC.get(neuronId);
+    if (sccIndex === void 0) return;
+    return this.stronglyConnectedComponents[sccIndex];
+  }
+  /**
+   * Get the SCC index for a given neuron ID
+   */
+  getSccIndexByNeuronId(neuronId) {
+    return this.neuronToSCC.get(neuronId);
+  }
+  /**
+   * Check if a neuron can be guaranteed not to be visited again during the current propagation.
+   * This is the core logic for safe context cleanup.
+   */
+  canNeuronBeGuaranteedDone(neuronId, activeSccCounts) {
+    const sccIndex = this.neuronToSCC.get(neuronId);
+    if (sccIndex === void 0) return true;
+    if (activeSccCounts.get(sccIndex) && activeSccCounts.get(sccIndex) > 0) {
+      return false;
+    }
+    const ancestors = this.sccAncestors.get(sccIndex);
+    if (!ancestors) return true;
+    for (const ancestorSccIndex of ancestors) {
+      if (activeSccCounts.get(ancestorSccIndex) && activeSccCounts.get(ancestorSccIndex) > 0) {
+        return false;
       }
-    };
-    tryProcessMore();
+    }
+    return true;
+  }
+  getParentNeuronByCollateralId(collateralId) {
+    return this.parentNeuronByCollateralId.get(collateralId);
+  }
+  getSubscribers(collateralId) {
+    return this.subIndex.get(collateralId) ?? [];
+  }
+  stimulate(signal, options) {
+    const stimulation = new CNSStimulation(this, options);
+    stimulation.responseToSignal(signal);
   }
 };
 
@@ -295,9 +572,8 @@ var CNSCollateral = class {
   constructor(id) {
     this.id = id;
   }
-  createSignal(...args) {
-    const payload = args[0];
-    return { type: this.id, payload };
+  createSignal(payload) {
+    return { collateral: this, payload };
   }
 };