@cnstra/core 1.7.0 → 1.8.0

package/dist/index.js

@@ -22,8 +22,8 @@ var CNSStimulationContextStore = class {
   }
 };
 
-// src/CNSFunctionalQueue.ts
-var CNSFunctionalQueue = class {
+// src/CNSNeuronActivationPump.ts
+var CNSNeuronActivationPump = class {
   constructor(processor, concurrency, abortSignal, initialCapacity) {
     this.processor = processor;
     this.concurrency = concurrency;
@@ -34,6 +34,7 @@ var CNSFunctionalQueue = class {
     this.size = 0;
     this.capacity = 16;
     this.activeOperations = 0;
+    this.activeTasks = /* @__PURE__ */ new Set();
     // NEW: prevent re-entrant pump; defer extra runs
     this.pumping = false;
     this.needsPump = false;
@@ -61,17 +62,17 @@ var CNSFunctionalQueue = class {
   }
   dequeue() {
     if (this.size === 0) return void 0;
-    const item = this.items[this.head];
+    const neuronActivationTask = this.items[this.head];
     this.items[this.head] = void 0;
     this.head = (this.head + 1) % this.capacity;
     this.size--;
-    return item;
+    return neuronActivationTask;
   }
-  enqueueItem(item) {
+  enqueueItem(neuronActivationTask) {
     if (this.size === this.capacity) {
       this.resize();
     }
-    this.items[this.tail] = item;
+    this.items[this.tail] = neuronActivationTask;
     this.tail = (this.tail + 1) % this.capacity;
     this.size++;
   }
@@ -82,13 +83,15 @@ var CNSFunctionalQueue = class {
     }
     this.pumping = true;
     while (this.canStartOperation && this.size > 0) {
-      const item = this.dequeue();
+      const neuronActivationTask = this.dequeue();
       this.activeOperations++;
-      const ret = this.processor(item);
+      this.activeTasks.add(neuronActivationTask);
+      const ret = this.processor(neuronActivationTask);
       if (ret && typeof ret.then === "function") {
         ret.then(
           (cb) => {
             this.activeOperations--;
+            this.activeTasks.delete(neuronActivationTask);
             if (typeof cb === "function") cb();
             if (this.size > 0 && this.canStartOperation) {
               if (this.pumping) this.needsPump = true;
@@ -97,6 +100,7 @@ var CNSFunctionalQueue = class {
           },
           (err) => {
             this.activeOperations--;
+            this.activeTasks.delete(neuronActivationTask);
             if (this.size > 0 && this.canStartOperation) {
               if (this.pumping) this.needsPump = true;
               else this.pump();
@@ -107,6 +111,7 @@ var CNSFunctionalQueue = class {
         continue;
       }
       this.activeOperations--;
+      this.activeTasks.delete(neuronActivationTask);
       if (typeof ret === "function") ret();
     }
     this.pumping = false;
@@ -115,8 +120,8 @@ var CNSFunctionalQueue = class {
       this.pump();
     }
   }
-  enqueue(x) {
-    this.enqueueItem(x);
+  enqueue(neuronActivationTask) {
+    this.enqueueItem(neuronActivationTask);
     if (!this.pumping) this.pump();
     else this.needsPump = true;
   }
@@ -126,6 +131,18 @@ var CNSFunctionalQueue = class {
   getActiveOperationsCount() {
     return this.activeOperations;
   }
+  getQueuedTasks() {
+    const result = [];
+    let index = this.head;
+    for (let i = 0; i < this.size; i++) {
+      result.push(this.items[index]);
+      index = (index + 1) % this.capacity;
+    }
+    return result;
+  }
+  getActiveTasks() {
+    return Array.from(this.activeTasks);
+  }
 };
 
 // src/CNSStimulation.ts
@@ -134,6 +151,8 @@ var CNSStimulation = class {
     this.cns = cns;
     this.options = options;
     this.scheduledCount = 0;
+    this.pendingTasks = /* @__PURE__ */ new Set();
+    this.failedTasks = [];
     this.completed = new Promise((resolve, reject) => {
       this.resolveCompleted = resolve;
       this.rejectCompleted = reject;
@@ -143,10 +162,12 @@ var CNSStimulation = class {
      * 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.ctx = new CNSStimulationContextStore(
+      new Map(Object.entries(options?.contextValues ?? {}))
+    );
     this.id = options?.stimulationId || Math.random().toString(36).slice(2);
-    this.queue = new CNSFunctionalQueue(
-      (item) => this.processQueueItem(item),
+    this.queue = new CNSNeuronActivationPump(
+      (neuronActivationTask) => this.executeActivationTask(neuronActivationTask),
       options?.concurrency,
       options?.abortSignal
     );
@@ -154,25 +175,81 @@ var CNSStimulation = class {
     if (this.options?.maxNeuronHops) {
       this.nueronVisitMap = /* @__PURE__ */ new Map();
     }
-    if (this.options?.abortSignal) {
-      this.options.abortSignal.addEventListener("abort", () => {
-        this.tryResolveCompleted();
-      });
-    }
   }
   tryResolveCompleted() {
     if (this.isCompleted) return;
     const noActive = this.queue.getActiveOperationsCount() === 0;
     const noPending = this.queue.length + this.scheduledCount === 0;
     const aborted = !!this.options?.abortSignal?.aborted;
-    if (noPending && noActive || aborted && noActive) {
+    if (noPending && noActive || aborted && noActive && !noPending) {
+      if (aborted) {
+        const queuedTasks = this.queue.getQueuedTasks();
+        for (const task of [...queuedTasks]) {
+          const alreadyTracked = this.failedTasks.some(
+            (ft) => ft.task.neuronId === task.neuronId && ft.task.dendriteCollateralName === task.dendriteCollateralName && ft.task.stimulationId === task.stimulationId
+          );
+          if (!alreadyTracked) {
+            this.failedTasks.push({
+              task,
+              error: new Error(
+                "Task aborted - not started due to abort signal"
+              ),
+              aborted: true
+            });
+          }
+        }
+        this.isCompleted = true;
+        this.rejectCompleted(new Error("Stimulation aborted"));
+        return;
+      }
       this.isCompleted = true;
-      this.resolveCompleted();
+      if (this.failedTasks.length > 0 || this.onResponseError) {
+        const error = this.onResponseError || new Error(
+          `Stimulation completed with ${this.failedTasks.length} failed task(s)`
+        );
+        this.rejectCompleted(error);
+      } else {
+        this.resolveCompleted();
+      }
     }
   }
   waitUntilComplete() {
     return this.completed;
   }
+  /**
+   * Returns all current activation tasks: queued, active, and pending (scheduled but not yet enqueued)
+   */
+  getAllActivationTasks() {
+    const queuedTasks = this.queue.getQueuedTasks();
+    const activeTasks = this.queue.getActiveTasks();
+    const pendingTasks = Array.from(this.pendingTasks);
+    return [...queuedTasks, ...activeTasks, ...pendingTasks];
+  }
+  /**
+   * Returns all tasks that failed or were aborted
+   */
+  getFailedTasks() {
+    return [...this.failedTasks];
+  }
+  /**
+   * Get the context store for this stimulation
+   */
+  getContext() {
+    return this.ctx;
+  }
+  /**
+   * Enqueue activation tasks directly into the stimulation queue
+   */
+  enqueueTasks(tasks) {
+    for (const task of tasks) {
+      const taskWithId = {
+        ...task,
+        stimulationId: this.id
+      };
+      this.queue.enqueue(taskWithId);
+    }
+    this.tryResolveCompleted();
+  }
   get concurrencyEnabled() {
     return this.options?.concurrency !== void 0 && this.options?.concurrency > 0;
   }
@@ -197,7 +274,7 @@ var CNSStimulation = class {
    * Increment the active count for the SCC containing this neuron
    */
   incrementSccCount(neuronId) {
-    const sccIndex = this.cns.getSccIndexByNeuronName(neuronId);
+    const sccIndex = this.cns.network.getSccIndexByNeuronName(neuronId);
     if (sccIndex === void 0) return;
     const currentCount = this.activeSccCounts.get(sccIndex) || 0;
     this.activeSccCounts.set(sccIndex, currentCount + 1);
@@ -206,7 +283,7 @@ var CNSStimulation = class {
    * Decrement the active count for the SCC containing this neuron
    */
   decrementSccCount(neuronId) {
-    const sccIndex = this.cns.getSccIndexByNeuronName(neuronId);
+    const sccIndex = this.cns.network.getSccIndexByNeuronName(neuronId);
     if (sccIndex === void 0) return;
     const currentCount = this.activeSccCounts.get(sccIndex) || 0;
     const nextCount = Math.max(0, currentCount - 1);
@@ -222,7 +299,7 @@ var CNSStimulation = class {
    */
   canNeuronBeGuaranteedDone(neuronId) {
     if (!this.autoCleanupContextsEnabled) return false;
-    return this.cns.canNeuronBeGuaranteedDone(
+    return this.cns.network.canNeuronBeGuaranteedDone(
       neuronId,
       this.activeSccCounts
     );
@@ -245,45 +322,70 @@ var CNSStimulation = class {
         );
       }
     }
-    const serialized = {
+    const neuronActivationTask = {
+      stimulationId: this.id,
       neuronId: subscriber.neuron.name,
       dendriteCollateralName: subscriber.dendrite.collateral.name,
-      input: inputSignal ? {
-        collateralName: inputSignal.collateralName,
-        payload: inputSignal.payload
-      } : void 0
+      input: inputSignal
     };
-    return serialized;
+    return neuronActivationTask;
   }
-  processQueueItem(item) {
-    const subscribers = this.cns.getSubscribers(
-      item.dendriteCollateralName
+  executeActivationTask(neuronActivationTask) {
+    const subscribers = this.cns.network.getSubscribers(
+      neuronActivationTask.dendriteCollateralName
     );
     const subscriber = subscribers.find(
-      (s) => s.neuron.name === item.neuronId
+      (s) => s.neuron.name === neuronActivationTask.neuronId
     );
-    if (!subscriber) return () => {
-    };
+    if (!subscriber) {
+      this.failedTasks.push({
+        task: neuronActivationTask,
+        error: new Error(
+          `Subscriber not found for neuron "${neuronActivationTask.neuronId}" and collateral "${neuronActivationTask.dendriteCollateralName}"`
+        ),
+        aborted: false
+      });
+      return () => {
+      };
+    }
     const neuron2 = subscriber.neuron;
     const dendrite = subscriber.dendrite;
-    const inputSignal = item.input ? {
-      collateralName: item.input.collateralName,
-      payload: item.input.payload
+    const inputSignal = neuronActivationTask.input ? {
+      collateralName: neuronActivationTask.input.collateralName,
+      payload: neuronActivationTask.input.payload
     } : void 0;
     const starter = () => {
       this.markNeuronActive(neuron2.name);
-      const response = dendrite.response(
-        inputSignal?.payload,
-        neuron2.axon,
-        {
-          get: () => this.ctx.get(neuron2.name),
-          set: (value) => this.ctx.set(neuron2.name, value),
-          delete: () => this.ctx.delete(neuron2.name),
-          abortSignal: this.options?.abortSignal,
-          cns: this.cns,
-          stimulationId: this.id
-        }
-      );
+      let response;
+      try {
+        response = dendrite.response(
+          inputSignal?.payload,
+          neuron2.axon,
+          {
+            get: () => this.ctx.get(neuron2.name),
+            set: (value) => this.ctx.set(neuron2.name, value),
+            delete: () => this.ctx.delete(neuron2.name),
+            abortSignal: this.options?.abortSignal,
+            cns: this.cns,
+            stimulationId: this.id
+          }
+        );
+      } catch (error) {
+        this.markNeuronInactive(neuron2.name);
+        const isAborted = this.options?.abortSignal?.aborted ?? false;
+        this.failedTasks.push({
+          task: neuronActivationTask,
+          error: error instanceof Error ? error : new Error(String(error)),
+          aborted: isAborted
+        });
+        this.processResponseOrResponses(
+          inputSignal,
+          void 0,
+          error
+        );
+        return () => {
+        };
+      }
       const maxDuration = neuron2.maxDuration;
       const asPromise = response instanceof Promise ? response : Promise.resolve(response);
       const timedPromise = maxDuration && maxDuration > 0 ? new Promise((resolve, reject) => {
@@ -320,6 +422,12 @@ var CNSStimulation = class {
           (error) => {
             return () => {
               this.markNeuronInactive(neuron2.name);
+              const isAborted = this.options?.abortSignal?.aborted ?? false;
+              this.failedTasks.push({
+                task: neuronActivationTask,
+                error: error instanceof Error ? error : new Error(String(error)),
+                aborted: isAborted
+              });
               return this.processResponseOrResponses(
                 inputSignal,
                 void 0,
@@ -355,60 +463,78 @@ var CNSStimulation = class {
   }
   processResponse(inputSignal, outputSignal, error) {
     const collateralName = outputSignal?.collateralName;
-    const ownerNeuron = collateralName ? this.cns.getParentNeuronByCollateralName(collateralName) : void 0;
-    const subscribers = collateralName ? this.cns.getSubscribers(collateralName) : [];
-    const subscriberQueueItems = [];
+    const ownerNeuron = collateralName ? this.cns.network.getParentNeuronByCollateralName(collateralName) : void 0;
+    const subscribers = collateralName ? this.cns.network.getSubscribers(collateralName) : [];
+    const subscriberActivationTasks = [];
     if (collateralName && !error) {
       if (ownerNeuron) {
         this.cleanupCtxIfNeeded(ownerNeuron);
       }
       for (let i = 0; i < subscribers.length; i++) {
-        subscriberQueueItems.push(
-          this.createSubscriberQueueItem(subscribers[i], outputSignal)
+        const task = this.createSubscriberQueueItem(
+          subscribers[i],
+          outputSignal
         );
+        subscriberActivationTasks.push(task);
+        this.pendingTasks.add(task);
       }
     }
-    this.scheduledCount += subscriberQueueItems.length;
+    this.scheduledCount += subscriberActivationTasks.length;
     let maybePromise;
     try {
       maybePromise = this.options?.onResponse?.({
         inputSignal,
         outputSignal,
-        ctx: this.ctx,
+        contextValue: this.ctx.getAll(),
         queueLength: this.queue.length + this.scheduledCount,
+        stimulation: this,
         stimulationId: this.id,
         hops: this.options?.maxNeuronHops && ownerNeuron ? this.nueronVisitMap?.get(ownerNeuron.name) ?? 0 : void 0,
         error
       });
     } catch (e) {
-      this.rejectCompleted(e);
+      this.onResponseError = e instanceof Error ? e : new Error(String(e));
+      for (let i = 0; i < subscriberActivationTasks.length; i++) {
+        this.scheduledCount--;
+        this.pendingTasks.delete(subscriberActivationTasks[i]);
+        this.queue.enqueue(subscriberActivationTasks[i]);
+      }
+      this.tryResolveCompleted();
       return;
     }
     if (maybePromise && typeof maybePromise.then === "function") {
       maybePromise.then(
         () => {
-          for (let i = 0; i < subscriberQueueItems.length; i++) {
+          for (let i = 0; i < subscriberActivationTasks.length; i++) {
             this.scheduledCount--;
-            this.queue.enqueue(subscriberQueueItems[i]);
+            this.pendingTasks.delete(subscriberActivationTasks[i]);
+            this.queue.enqueue(subscriberActivationTasks[i]);
           }
           this.tryResolveCompleted();
         },
         (error2) => {
-          this.rejectCompleted(error2);
+          this.onResponseError = error2 instanceof Error ? error2 : new Error(String(error2));
+          for (let i = 0; i < subscriberActivationTasks.length; i++) {
+            this.scheduledCount--;
+            this.pendingTasks.delete(subscriberActivationTasks[i]);
+            this.queue.enqueue(subscriberActivationTasks[i]);
+          }
+          this.tryResolveCompleted();
         }
       );
       return;
     }
-    for (let i = 0; i < subscriberQueueItems.length; i++) {
+    for (let i = 0; i < subscriberActivationTasks.length; i++) {
       this.scheduledCount--;
-      this.queue.enqueue(subscriberQueueItems[i]);
+      this.pendingTasks.delete(subscriberActivationTasks[i]);
+      this.queue.enqueue(subscriberActivationTasks[i]);
     }
     this.tryResolveCompleted();
   }
   responseToSignal(signalOrSignals) {
     if (Array.isArray(signalOrSignals)) {
       for (const signal of signalOrSignals) {
-        const ownerNeuron2 = this.cns.getParentNeuronByCollateralName(
+        const ownerNeuron2 = this.cns.network.getParentNeuronByCollateralName(
           signal.collateralName
         );
         if (ownerNeuron2) {
@@ -418,7 +544,7 @@ var CNSStimulation = class {
       this.processResponseOrResponses(void 0, signalOrSignals);
       return;
     }
-    const ownerNeuron = this.cns.getParentNeuronByCollateralName(
+    const ownerNeuron = this.cns.network.getParentNeuronByCollateralName(
       signalOrSignals.collateralName
     );
     if (ownerNeuron) {
@@ -429,88 +555,6 @@ var CNSStimulation = class {
   }
 };
 
-// src/CNSTaskQueue.ts
-var CNSTaskQueue = class {
-  constructor(concurrency) {
-    this.concurrency = concurrency;
-    this.pumping = false;
-    this.needsPump = false;
-    this.activeOperations = 0;
-    this.items = [];
-  }
-  get canStartOperation() {
-    const limit = this.concurrency ?? Infinity;
-    return this.activeOperations < limit;
-  }
-  enqueue(task) {
-    return new Promise((resolve, reject) => {
-      this.items.push({ task, resolve, reject });
-      if (!this.pumping) this.pump();
-      else this.needsPump = true;
-    });
-  }
-  pump() {
-    if (this.pumping) {
-      this.needsPump = true;
-      return;
-    }
-    this.pumping = true;
-    while (this.canStartOperation && this.items.length > 0) {
-      const { task, resolve, reject } = this.items.shift();
-      this.activeOperations++;
-      try {
-        const ret = task();
-        if (ret && typeof ret.then === "function") {
-          ret.then(
-            (cb) => {
-              try {
-                if (typeof cb === "function") cb();
-                resolve();
-              } finally {
-                this.activeOperations--;
-                if (this.items.length > 0 && this.canStartOperation) {
-                  if (this.pumping) this.needsPump = true;
-                  else this.pump();
-                }
-              }
-            },
-            (err) => {
-              try {
-                reject(err);
-              } finally {
-                this.activeOperations--;
-                if (this.items.length > 0 && this.canStartOperation) {
-                  if (this.pumping) this.needsPump = true;
-                  else this.pump();
-                }
-              }
-            }
-          );
-          break;
-        } else {
-          try {
-            if (typeof ret === "function") ret();
-            resolve();
-          } finally {
-            this.activeOperations--;
-          }
-        }
-      } catch (e) {
-        try {
-          reject(e);
-        } finally {
-          this.activeOperations--;
-        }
-      }
-    }
-    this.pumping = false;
-    if (this.needsPump) {
-      this.needsPump = false;
-      this.pump();
-    }
-  }
-};
-
 // src/CNSInstanceNeuronQueue.ts
 var CNSInstanceNeuronQueue = class {
   constructor() {
@@ -566,20 +610,10 @@ var CNSInstanceNeuronQueue = class {
   }
 };
 
-// src/CNS.ts
-var CNS = class {
-  constructor(neurons, options) {
+// src/CNSNetwork.ts
+var CNSNetwork = class {
+  constructor(neurons) {
     this.neurons = neurons;
-    this.options = options;
-    /**
-     * Fast lookup: collateralName -> list of (neuron, dendrite) subscribers.
-     * Built once at construction time.
-     */
-    this.subIndex = /* @__PURE__ */ new Map();
-    this.neuronIndex = /* @__PURE__ */ new Map();
-    this.dendriteIndex = /* @__PURE__ */ new Map();
-    this.collateralIndex = /* @__PURE__ */ new Map();
-    this.parentNeuronByCollateralName = /* @__PURE__ */ new Map();
     /**
      * Strongly Connected Components of the neuron graph.
      * Each component is a set of neuron IDs that can reach each other.
@@ -598,24 +632,17 @@ var CNS = class {
      */
     this.sccAncestors = /* @__PURE__ */ new Map();
     /**
-     * Global per-neuron concurrency gates shared across all stimulations.
-     */
-    this.neuronGates = /* @__PURE__ */ new Map();
-    /**
-     * Global task queue used by stimulation to schedule per-neuron gated work.
-     * Does not replace per-stimulation concurrency; only coordinates global per-neuron limits.
-     */
-    this.globalTaskQueue = new CNSTaskQueue();
-    this.instanceNeuronQueue = new CNSInstanceNeuronQueue();
-    /**
-     * Global response listeners applied to every stimulation.
+     * Fast lookup: collateralName -> list of (neuron, dendrite) subscribers.
+     * Built once at construction time.
      */
-    this.globalResponseListeners = [];
+    this.subIndex = /* @__PURE__ */ new Map();
+    this.neuronIndex = /* @__PURE__ */ new Map();
+    this.dendriteIndex = /* @__PURE__ */ new Map();
+    this.collateralIndex = /* @__PURE__ */ new Map();
+    this.parentNeuronByCollateralName = /* @__PURE__ */ new Map();
     this.validateUniqueIdentifiers();
     this.buildIndexes();
-    if (this.options?.autoCleanupContexts) {
-      this.buildSCC();
-    }
+    this.buildSCC();
   }
   /**
    * Validate uniqueness constraints:
@@ -645,126 +672,6 @@ var CNS = class {
       );
     }
   }
-  addResponseListener(listener) {
-    this.globalResponseListeners.push(listener);
-    let active = true;
-    return () => {
-      if (!active) return;
-      active = false;
-      const idx = this.globalResponseListeners.indexOf(listener);
-      if (idx >= 0) this.globalResponseListeners.splice(idx, 1);
-    };
-  }
-  wrapOnResponse(local) {
-    if (this.globalResponseListeners.length === 0 && !local) {
-      return () => {
-      };
-    }
-    return (r) => {
-      let anyPromise = false;
-      const promises = [];
-      if (local) {
-        const res = local(r);
-        if (res && typeof res.then === "function") {
-          anyPromise = true;
-          promises.push(res);
-        }
-      }
-      for (let i = 0; i < this.globalResponseListeners.length; i++) {
-        const res = this.globalResponseListeners[i](r);
-        if (res && typeof res.then === "function") {
-          anyPromise = true;
-          promises.push(res);
-        }
-      }
-      if (anyPromise) {
-        return Promise.allSettled(promises).then((results) => {
-          const rejected = results.find(
-            (r2) => r2.status === "rejected"
-          );
-          if (rejected) throw rejected.reason;
-        });
-      }
-    };
-  }
-  runWithNeuronConcurrency(neuron2, fn) {
-    const limit = neuron2.concurrency;
-    if (limit === void 0 || limit <= 0) {
-      return this.globalTaskQueue.enqueue(fn);
-    }
-    let gate = this.neuronGates.get(neuron2.name);
-    if (!gate) {
-      gate = { limit, active: 0, waiters: [] };
-      this.neuronGates.set(neuron2.name, gate);
-    } else {
-      gate.limit = limit;
-    }
-    const wrap = (cb) => {
-      return () => {
-        try {
-          cb();
-        } finally {
-          gate.active = Math.max(0, gate.active - 1);
-          if (gate.waiters.length > 0) {
-            const next = gate.waiters.shift();
-            next();
-          }
-        }
-      };
-    };
-    if (gate.active < gate.limit) {
-      gate.active++;
-      return this.globalTaskQueue.enqueue(() => {
-        const ret = fn();
-        if (ret && typeof ret.then === "function") {
-          return ret.then((cb) => wrap(cb));
-        }
-        return wrap(ret);
-      });
-    }
-    return new Promise((resolve) => {
-      const starter = () => {
-        gate.active++;
-        this.globalTaskQueue.enqueue(() => {
-          const ret = fn();
-          if (ret && typeof ret.then === "function") {
-            return ret.then(
-              (cb) => wrap(cb)
-            );
-          }
-          return wrap(ret);
-        }).then(resolve);
-      };
-      gate.waiters.push(starter);
-    });
-  }
-  buildIndexes() {
-    this.subIndex.clear();
-    this.parentNeuronByCollateralName.clear();
-    for (const neuron2 of this.neurons) {
-      this.neuronIndex.set(neuron2.name, neuron2);
-      for (const dendrite of neuron2.dendrites) {
-        const key = dendrite.collateral.name;
-        const arr = this.subIndex.get(key) ?? [];
-        arr.push({ neuron: neuron2, dendrite });
-        this.subIndex.set(
-          key,
-          arr
-        );
-        this.dendriteIndex.set(key, dendrite);
-      }
-      Object.values(neuron2.axon).forEach((collateral2) => {
-        this.parentNeuronByCollateralName.set(
-          collateral2.name,
-          neuron2
-        );
-        this.collateralIndex.set(
-          collateral2.name,
-          collateral2
-        );
-      });
-    }
-  }
   /**
    * Build the neuron graph where neurons are connected if one can stimulate the other.
    */
@@ -809,7 +716,7 @@ var CNS = class {
       stack.push(neuronId);
       onStack.add(neuronId);
       const neighbors = graph.get(neuronId) || /* @__PURE__ */ new Set();
-      for (const neighbor of neighbors) {
+      for (const neighbor of Array.from(neighbors)) {
         if (!index.has(neighbor)) {
           strongConnect(neighbor);
           lowlink.set(
@@ -841,7 +748,7 @@ var CNS = class {
     }
     this.stronglyConnectedComponents = components;
     for (let i = 0; i < components.length; i++) {
-      for (const neuronId of components[i]) {
+      for (const neuronId of Array.from(components[i])) {
         this.neuronToSCC.set(neuronId, i);
       }
     }
@@ -858,9 +765,9 @@ var CNS = class {
     }
     for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
       const scc = this.stronglyConnectedComponents[i];
-      for (const neuronId of scc) {
+      for (const neuronId of Array.from(scc)) {
         const neighbors = neuronGraph.get(neuronId) || /* @__PURE__ */ new Set();
-        for (const neighborId of neighbors) {
+        for (const neighborId of Array.from(neighbors)) {
           const neighborSccIndex = this.neuronToSCC.get(neighborId);
           if (neighborSccIndex !== void 0 && neighborSccIndex !== i) {
             this.sccDag.get(neighborSccIndex).add(i);
@@ -890,11 +797,11 @@ var CNS = class {
     while (queue.length > 0) {
       const current = queue.shift();
       const outgoingEdges = this.getOutgoingEdges(current);
-      for (const neighbor of outgoingEdges) {
+      for (const neighbor of Array.from(outgoingEdges)) {
         const neighborAncestors = this.sccAncestors.get(neighbor);
         neighborAncestors.add(current);
         const currentAncestors = this.sccAncestors.get(current);
-        for (const ancestor of currentAncestors) {
+        for (const ancestor of Array.from(currentAncestors)) {
           neighborAncestors.add(ancestor);
         }
         const newInDegree = (inDegree.get(neighbor) || 0) - 1;
@@ -910,7 +817,7 @@ var CNS = class {
    */
   getOutgoingEdges(sccIndex) {
     const outgoing = /* @__PURE__ */ new Set();
-    for (const [targetScc, incomingEdges] of this.sccDag) {
+    for (const [targetScc, incomingEdges] of Array.from(this.sccDag)) {
       if (incomingEdges.has(sccIndex)) {
         outgoing.add(targetScc);
       }
@@ -945,13 +852,40 @@ var CNS = class {
     }
     const ancestors = this.sccAncestors.get(sccIndex);
     if (!ancestors) return true;
-    for (const ancestorSccIndex of ancestors) {
+    for (const ancestorSccIndex of Array.from(ancestors)) {
       if (activeSccCounts.get(ancestorSccIndex) && activeSccCounts.get(ancestorSccIndex) > 0) {
         return false;
       }
     }
     return true;
   }
+  buildIndexes() {
+    this.subIndex.clear();
+    this.parentNeuronByCollateralName.clear();
+    for (const neuron2 of this.neurons) {
+      this.neuronIndex.set(neuron2.name, neuron2);
+      for (const dendrite of neuron2.dendrites) {
+        const key = dendrite.collateral.name;
+        const arr = this.subIndex.get(key) ?? [];
+        arr.push({ neuron: neuron2, dendrite });
+        this.subIndex.set(
+          key,
+          arr
+        );
+        this.dendriteIndex.set(key, dendrite);
+      }
+      Object.values(neuron2.axon).forEach((collateral2) => {
+        this.parentNeuronByCollateralName.set(
+          collateral2.name,
+          neuron2
+        );
+        this.collateralIndex.set(
+          collateral2.name,
+          collateral2
+        );
+      });
+    }
+  }
   getParentNeuronByCollateralName(collateralName) {
     return this.parentNeuronByCollateralName.get(collateralName);
   }
@@ -975,6 +909,80 @@ var CNS = class {
   getSubscribers(collateralName) {
     return this.subIndex.get(collateralName) ?? [];
   }
+};
+
+// src/CNS.ts
+var CNS = class {
+  constructor(neurons, options) {
+    this.neurons = neurons;
+    this.options = options;
+    /**
+     * Global per-neuron concurrency gates shared across all stimulations.
+     */
+    this.neuronGates = /* @__PURE__ */ new Map();
+    /**
+     * Global task queue used by stimulation to schedule per-neuron gated work.
+     * Does not replace per-stimulation concurrency; only coordinates global per-neuron limits.
+     */
+    this.instanceNeuronQueue = new CNSInstanceNeuronQueue();
+    /**
+     * Global response listeners applied to every stimulation.
+     */
+    this.globalResponseListeners = [];
+    this.network = new CNSNetwork(this.neurons);
+  }
+  addResponseListener(listener) {
+    this.globalResponseListeners.push(listener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const idx = this.globalResponseListeners.indexOf(listener);
+      if (idx >= 0) this.globalResponseListeners.splice(idx, 1);
+    };
+  }
+  wrapOnResponse(local) {
+    if (this.globalResponseListeners.length === 0 && !local) {
+      return () => {
+      };
+    }
+    return (r) => {
+      let anyPromise = false;
+      const promises = [];
+      if (local) {
+        try {
+          const res = local(r);
+          if (res && typeof res.then === "function") {
+            anyPromise = true;
+            promises.push(res);
+          }
+        } catch (error) {
+          anyPromise = true;
+          promises.push(Promise.reject(error));
+        }
+      }
+      for (let i = 0; i < this.globalResponseListeners.length; i++) {
+        try {
+          const res = this.globalResponseListeners[i](r);
+          if (res && typeof res.then === "function") {
+            anyPromise = true;
+            promises.push(res);
+          }
+        } catch (error) {
+          anyPromise = true;
+          promises.push(Promise.reject(error));
+        }
+      }
+      if (anyPromise) {
+        return Promise.allSettled(promises).then((results) => {
+          const rejected = results.find(
+            (r2) => r2.status === "rejected"
+          );
+          if (rejected) throw rejected.reason;
+        });
+      }
+    };
+  }
   stimulate(signalOrSignals, options) {
     const wrapped = this.wrapOnResponse(options?.onResponse);
     const stimulation = new CNSStimulation(this, this.instanceNeuronQueue, {
@@ -982,7 +990,19 @@ var CNS = class {
       onResponse: wrapped
     });
     stimulation.responseToSignal(signalOrSignals);
-    return stimulation.waitUntilComplete();
+    return stimulation;
+  }
+  /**
+   * Start a stimulation with activation tasks directly
+   */
+  activate(tasks, options) {
+    const wrapped = this.wrapOnResponse(options?.onResponse);
+    const stimulation = new CNSStimulation(this, this.instanceNeuronQueue, {
+      ...options,
+      onResponse: wrapped
+    });
+    stimulation.enqueueTasks(tasks);
+    return stimulation;
   }
 };