@cnstra/core 3.0.0 → 3.2.1

package/dist/index.cjs

@@ -2,11 +2,14 @@
 
 // src/CNSStimulation.ts
 var TASK_DENDRITE = /* @__PURE__ */ Symbol("cnstra.taskDendrite");
+var TASK_ACTIVE_POSITION = /* @__PURE__ */ Symbol("cnstra.taskActivePosition");
+var TASK_PENDING_POSITION = /* @__PURE__ */ Symbol("cnstra.taskPendingPosition");
 var CNSDendriteContext = class {
-  constructor(stimulation, abortSignal, cns) {
+  constructor(stimulation, abortSignal, cns, task) {
     this.stimulation = stimulation;
     this.abortSignal = abortSignal;
     this.cns = cns;
+    this.task = task;
   }
   // Prototype getter, not a constructor field: you only pay a single `cns.global`
   // read on the dendrites that actually reach for it. Value getter, so
@@ -21,9 +24,15 @@ var CNSDendriteContext = class {
   get stimulationContext() {
     return this.stimulation.options?.stimulationContext;
   }
+  // This activation's own store - written by a response listener before the
+  // activation ran. Prototype getter like the two above: nothing is allocated
+  // for a handler that never reaches for it.
+  get activationContext() {
+    return this.task?.activationContext;
+  }
 };
 var CNSStimulationResponseImpl = class {
-  constructor(stimulation, inputSignal, outputSignal, queueLength, pendingActivations, activeActivations, hops, error, neuron2) {
+  constructor(stimulation, inputSignal, outputSignal, queueLength, pendingActivations, activeActivations, hops, error, neuron, startedAt, duration, scheduledActivationTasks = EMPTY_TASKS, activationContext = void 0) {
     this.stimulation = stimulation;
     this.inputSignal = inputSignal;
     this.outputSignal = outputSignal;
@@ -32,9 +41,15 @@ var CNSStimulationResponseImpl = class {
     this.activeActivations = activeActivations;
     this.hops = hops;
     this.error = error;
-    this.neuron = neuron2;
+    this.neuron = neuron;
+    this.startedAt = startedAt;
+    this.duration = duration;
+    this.scheduledActivationTasks = scheduledActivationTasks;
+    this.activationContext = activationContext;
   }
 };
+var EMPTY_TASKS = [];
+var EMPTY_SUBSCRIBERS = [];
 var CNSStimulation = class {
   constructor(cns, instanceNeuronQueue, options, onResponse, onDrain) {
     this.cns = cns;
@@ -63,8 +78,14 @@ var CNSStimulation = class {
     this.onDrain = onDrain;
     this.instanceNeuronQueue = instanceNeuronQueue;
     this.onResponse = onResponse;
+    this.concurrencyLimit = this.options?.concurrency ?? Infinity;
+    this.abortSignal = this.options?.abortSignal;
+    this.subscribersByCollateralIndex = cns.network.getSubscriberTable(
+      this.options?.modality,
+      this.options?.afferentPath
+    );
     if (this.options?.maxNeuronHops) {
-      this.neuronVisitMap = /* @__PURE__ */ new Map();
+      this.neuronVisitCounts = [];
     }
   }
   pushFailedTask(failure) {
@@ -81,8 +102,7 @@ var CNSStimulation = class {
   }
   // ----- Inlined activation queue / pump -----
   get canStartOperation() {
-    const limit = this.options?.concurrency ?? Infinity;
-    return this.activeOperations < limit && !this.options?.abortSignal?.aborted;
+    return this.activeOperations < this.concurrencyLimit && !this.abortSignal?.aborted;
   }
   qResize() {
     const oldCapacity = this.qCapacity;
@@ -139,48 +159,56 @@ var CNSStimulation = class {
       return;
     }
     this.pumping = true;
-    while (this.canStartOperation && this.qSize > 0) {
-      const task = this.qDequeue();
-      this.activeOperations++;
-      const ret = this.executeActivationTask(task);
-      if (ret && typeof ret.then === "function") {
-        (this.activeTasks ?? (this.activeTasks = /* @__PURE__ */ new Set())).add(task);
-        ret.then(
-          (cb) => {
-            this.activeOperations--;
-            this.activeTasks.delete(task);
-            this.beginTurn();
-            try {
-              if (typeof cb === "function") cb();
-              if (this.qSize > 0 && this.canStartOperation) {
-                if (this.pumping) this.needsPump = true;
-                else this.pump();
+    try {
+      while (this.canStartOperation && this.qSize > 0) {
+        const task = this.qDequeue();
+        this.activeOperations++;
+        const ret = this.executeActivationTask(task);
+        if (ret && typeof ret.then === "function") {
+          this.addPositionedTask(this.activeTasks ?? (this.activeTasks = []), task, TASK_ACTIVE_POSITION);
+          ret.then(
+            (cb) => {
+              this.activeOperations--;
+              this.removeActiveTask(task);
+              this.beginTurn();
+              try {
+                if (typeof cb === "function") cb();
+                if (this.qSize > 0 && this.canStartOperation) {
+                  if (this.pumping) this.needsPump = true;
+                  else this.pump();
+                }
+              } catch (error) {
+                this.endRunWithError(error);
+              } finally {
+                this.endTurn();
               }
-            } finally {
-              this.endTurn();
-            }
-          },
-          (err) => {
-            this.activeOperations--;
-            this.activeTasks.delete(task);
-            this.beginTurn();
-            try {
-              if (this.qSize > 0 && this.canStartOperation) {
-                if (this.pumping) this.needsPump = true;
-                else this.pump();
+            },
+            (err) => {
+              this.activeOperations--;
+              this.removeActiveTask(task);
+              this.beginTurn();
+              try {
+                if (this.qSize > 0 && this.canStartOperation) {
+                  if (this.pumping) this.needsPump = true;
+                  else this.pump();
+                }
+              } finally {
+                this.endTurn();
               }
-            } finally {
-              this.endTurn();
+              throw err;
             }
-            throw err;
-          }
-        );
-        continue;
+          );
+          continue;
+        }
+        this.activeOperations--;
+        if (typeof ret === "function") ret();
       }
-      this.activeOperations--;
-      if (typeof ret === "function") ret();
+    } catch (error) {
+      this.endRunWithError(error);
+      throw error;
+    } finally {
+      this.pumping = false;
     }
-    this.pumping = false;
     if (this.needsPump) {
       this.needsPump = false;
       this.pump();
@@ -222,14 +250,30 @@ var CNSStimulation = class {
     }
   }
   /**
-   * Activations that exist (or are reserved) but whose dendrite body has not
-   * been invoked yet: sitting in the ring buffer, created and held in
+   * Activations that exist (or are reserved) but whose dendrite response has
+   * not been invoked yet: sitting in the ring buffer, created and held in
    * pendingTasks, or reserved by an array fan-out mid-dispatch. Subscribers
    * parked behind an async onResponse land here too - their body has not run.
    */
   get pendingActivations() {
     return this.qSize + this.scheduledCount + this.reservedActivations;
   }
+  /**
+   * End the run because the machinery itself threw. Dendrite bodies never get
+   * here - runStarter catches those and records them as failed tasks; what
+   * lands here is a throw from dispatch, today the hop-limit guard in
+   * createSubscriberQueueItem. Nothing settles the counters after such a
+   * throw, so completion has to be forced: without it the stimulation neither
+   * resolves nor rejects, and a worker holds a job that never finishes and
+   * never fails.
+   */
+  endRunWithError(error) {
+    if (this.isCompleted) return;
+    this.isCompleted = true;
+    this.finalizeReject(
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
   tryResolveCompleted() {
     if (this.isCompleted) return;
     const noActive = this.activeOperations === 0;
@@ -253,6 +297,7 @@ var CNSStimulation = class {
           }
         }
         this.isCompleted = true;
+        if (!noPending) this.emitAbortedResponse();
         this.finalizeReject(new Error("Stimulation aborted"));
         return;
       }
@@ -285,10 +330,34 @@ var CNSStimulation = class {
    */
   getAllActivationTasks() {
     const queuedTasks = this.qGetQueuedTasks();
-    const activeTasks = this.activeTasks ? Array.from(this.activeTasks) : [];
-    const pendingTasks = this.pendingTasks ? Array.from(this.pendingTasks) : [];
+    const activeTasks = this.activeTasks ?? EMPTY_TASKS;
+    const pendingTasks = this.pendingTasks ?? EMPTY_TASKS;
     return [...queuedTasks, ...activeTasks, ...pendingTasks];
   }
+  getSubscribers(collateral) {
+    return this.subscribersByCollateralIndex[collateral.index] ?? EMPTY_SUBSCRIBERS;
+  }
+  addPositionedTask(tasks, task, positionKey) {
+    task[positionKey] = tasks.length;
+    tasks.push(task);
+  }
+  removePositionedTask(tasks, task, positionKey) {
+    if (tasks === void 0) return;
+    const position = task[positionKey];
+    if (position === void 0 || tasks[position] !== task) return;
+    const lastTask = tasks.pop();
+    if (lastTask !== task) {
+      tasks[position] = lastTask;
+      lastTask[positionKey] = position;
+    }
+    task[positionKey] = void 0;
+  }
+  removeActiveTask(task) {
+    this.removePositionedTask(this.activeTasks, task, TASK_ACTIVE_POSITION);
+  }
+  removePendingTask(task) {
+    this.removePositionedTask(this.pendingTasks, task, TASK_PENDING_POSITION);
+  }
   /**
    * Returns all tasks that failed or were aborted
    */
@@ -301,12 +370,25 @@ var CNSStimulation = class {
    * failed/aborted tasks. This is the set to persist for resume: re-activating
    * it re-runs exactly the not-yet-done work. Safe to call at any point during
    * a run (for progress) or after it fails.
+   *
+   * Each task appears exactly once. The two sources overlap: aborting marks
+   * every still-queued task as failed without dequeuing it, so a task sits in
+   * the ring buffer AND in failedTasks. Concatenating them blindly handed the
+   * broker a checkpoint with the whole queued frontier listed twice, and the
+   * resumed run re-executed every one of those tasks a second time - duplicate
+   * charges, emails and POSTs on every graceful shutdown.
    */
   getOutstandingTasks() {
-    return [
-      ...this.getAllActivationTasks(),
-      ...this.getFailedTasks().map((f) => f.task)
-    ];
+    const seen = /* @__PURE__ */ new Set();
+    const outstanding = [];
+    const add = (task) => {
+      if (seen.has(task)) return;
+      seen.add(task);
+      outstanding.push(task);
+    };
+    for (const task of this.getAllActivationTasks()) add(task);
+    for (const failure of this.getFailedTasks()) add(failure.task);
+    return outstanding;
   }
   /**
    * Enqueue activation tasks directly into the stimulation queue
@@ -326,17 +408,16 @@ var CNSStimulation = class {
     return this.options?.concurrency !== void 0 && this.options?.concurrency > 0;
   }
   createSubscriberQueueItem(subscriber, inputSignal) {
-    if (this.options?.maxNeuronHops) {
-      if ((this.neuronVisitMap?.get(subscriber.neuron) ?? 0) >= this.options?.maxNeuronHops) {
+    const neuronVisitCounts = this.neuronVisitCounts;
+    if (neuronVisitCounts !== void 0) {
+      const neuronIndex = subscriber.neuron.index;
+      const neuronVisitCount = neuronVisitCounts[neuronIndex] ?? 0;
+      if (neuronVisitCount >= this.options.maxNeuronHops) {
         throw new Error(
           `Max neuron hops reached when trying to enqueue subscriber`
         );
-      } else {
-        this.neuronVisitMap?.set(
-          subscriber.neuron,
-          (this.neuronVisitMap?.get(subscriber.neuron) ?? 0) + 1
-        );
       }
+      neuronVisitCounts[neuronIndex] = neuronVisitCount + 1;
     }
     const neuronActivationTask = {
       neuron: subscriber.neuron,
@@ -344,12 +425,14 @@ var CNSStimulation = class {
       input: inputSignal
     };
     neuronActivationTask[TASK_DENDRITE] = subscriber;
+    neuronActivationTask[TASK_ACTIVE_POSITION] = void 0;
+    neuronActivationTask[TASK_PENDING_POSITION] = void 0;
     return neuronActivationTask;
   }
   executeActivationTask(neuronActivationTask) {
     let subscriber = neuronActivationTask[TASK_DENDRITE];
     if (!subscriber) {
-      const subscribers = this.cns.network.getSubscribers(
+      const subscribers = this.getSubscribers(
         neuronActivationTask.dendriteCollateral
       );
       for (let i = 0; i < subscribers.length; i++) {
@@ -371,42 +454,46 @@ var CNSStimulation = class {
           void 0,
           neuronActivationTask.input,
           void 0,
-          error
+          error,
+          void 0,
+          neuronActivationTask.activationContext
         );
       };
     }
-    const neuron2 = subscriber.neuron;
+    const neuron = subscriber.neuron;
     const dendrite = subscriber.dendrite;
     const inputSignal = neuronActivationTask.input;
-    const concurrency = neuron2.concurrency;
+    const concurrency = neuron.concurrency;
     if (concurrency === void 0 || concurrency <= 0) {
       return this.runStarter(
-        neuron2,
+        neuron,
         dendrite,
         inputSignal,
         neuronActivationTask
       );
     }
     return this.instanceNeuronQueue.run(
-      neuron2,
+      neuron,
       () => this.runStarter(
-        neuron2,
+        neuron,
         dendrite,
         inputSignal,
         neuronActivationTask
       )
     );
   }
-  runStarter(neuron2, dendrite, inputSignal, neuronActivationTask) {
+  runStarter(neuron, dendrite, inputSignal, neuronActivationTask) {
     let response;
+    const startedAt = this.onResponse === void 0 ? void 0 : Date.now();
     try {
       response = dendrite.response(
         inputSignal?.payload,
-        neuron2.axon,
+        neuron.axon,
         new CNSDendriteContext(
           this,
           this.options?.abortSignal,
-          this.cns
+          this.cns,
+          neuronActivationTask
         )
       );
     } catch (error) {
@@ -418,14 +505,16 @@ var CNSStimulation = class {
       });
       return () => {
         this.processResponseOrResponses(
-          neuron2,
+          neuron,
           inputSignal,
           void 0,
-          error
+          error,
+          startedAt,
+          neuronActivationTask.activationContext
         );
       };
     }
-    const maxDuration = neuron2.maxDuration;
+    const maxDuration = neuron.maxDuration;
     if (response instanceof Promise || maxDuration) {
       const asPromise = response instanceof Promise ? response : Promise.resolve(response);
       const timedPromise = maxDuration && maxDuration > 0 ? new Promise((resolve, reject) => {
@@ -450,9 +539,12 @@ var CNSStimulation = class {
         (signal) => {
           return () => {
             return this.processResponseOrResponses(
-              neuron2,
+              neuron,
               inputSignal,
-              signal
+              signal,
+              void 0,
+              startedAt,
+              neuronActivationTask.activationContext
             );
           };
         },
@@ -465,10 +557,12 @@ var CNSStimulation = class {
               aborted: isAborted
             });
             return this.processResponseOrResponses(
-              neuron2,
+              neuron,
               inputSignal,
               void 0,
-              error
+              error,
+              startedAt,
+              neuronActivationTask.activationContext
             );
           };
         }
@@ -476,17 +570,29 @@ var CNSStimulation = class {
     } else {
       return () => {
         return this.processResponseOrResponses(
-          neuron2,
+          neuron,
           inputSignal,
-          response
+          response,
+          void 0,
+          startedAt,
+          neuronActivationTask.activationContext
         );
       };
     }
   }
-  processResponseOrResponses(emitter, inputSignal, outputSignalOrSignals, error) {
+  processResponseOrResponses(emitter, inputSignal, outputSignalOrSignals, error, startedAt, activationContext) {
+    const duration = startedAt === void 0 ? void 0 : Date.now() - startedAt;
     if (Array.isArray(outputSignalOrSignals)) {
       if (outputSignalOrSignals.length === 0) {
-        this.processResponse(emitter, inputSignal, void 0, error);
+        this.processResponse(
+          emitter,
+          inputSignal,
+          void 0,
+          error,
+          startedAt,
+          duration,
+          activationContext
+        );
         return;
       }
       let perSignal;
@@ -495,31 +601,82 @@ var CNSStimulation = class {
         let reserved = 0;
         for (let i = 0; i < outputSignalOrSignals.length; i++) {
           const c = outputSignalOrSignals[i]?.collateral;
-          const n = c ? this.cns.network.getSubscribers(c).length : 0;
+          const n = c ? this.getSubscribers(c).length : 0;
           perSignal[i] = n;
           reserved += n;
         }
         this.reservedActivations += reserved;
       }
-      for (let i = 0; i < outputSignalOrSignals.length; i++) {
-        if (perSignal) this.reservedActivations -= perSignal[i];
-        this.processResponse(
-          emitter,
-          inputSignal,
-          outputSignalOrSignals[i],
-          error
-        );
+      let dispatchIndex = 0;
+      try {
+        for (; dispatchIndex < outputSignalOrSignals.length; dispatchIndex++) {
+          if (perSignal)
+            this.reservedActivations -= perSignal[dispatchIndex];
+          this.processResponse(
+            emitter,
+            inputSignal,
+            outputSignalOrSignals[dispatchIndex],
+            error,
+            startedAt,
+            duration,
+            activationContext
+          );
+        }
+      } finally {
+        if (perSignal) {
+          for (let j = dispatchIndex + 1; j < perSignal.length; j++) {
+            this.reservedActivations -= perSignal[j];
+          }
+        }
       }
       return;
     }
-    this.processResponse(emitter, inputSignal, outputSignalOrSignals, error);
+    this.processResponse(
+      emitter,
+      inputSignal,
+      outputSignalOrSignals,
+      error,
+      startedAt,
+      duration,
+      activationContext
+    );
+  }
+  /**
+   * The one response an aborted run emits: no neuron, no signals, an empty
+   * queue. It exists so `queueLength === 0` — the completion condition every
+   * listener uses — is reached on the abort path too. Listener errors are
+   * swallowed: the run is already over and rejecting, and there is nothing
+   * left to fail.
+   */
+  emitAbortedResponse() {
+    const onResponse = this.onResponse;
+    if (!onResponse) return;
+    try {
+      void onResponse(
+        new CNSStimulationResponseImpl(
+          this,
+          void 0,
+          void 0,
+          0,
+          0,
+          0,
+          void 0,
+          new Error("Stimulation aborted"),
+          void 0,
+          void 0,
+          void 0
+        )
+      );
+    } catch (e) {
+      this.onResponseError = e instanceof Error ? e : new Error(String(e));
+    }
   }
-  processResponse(emitter, inputSignal, outputSignal, error) {
-    const collateral2 = outputSignal?.collateral;
-    const subscribers = collateral2 ? this.cns.network.getSubscribers(collateral2) : [];
+  processResponse(emitter, inputSignal, outputSignal, error, startedAt, duration, activationContext) {
+    const collateral = outputSignal?.collateral;
+    const subscribers = collateral ? this.getSubscribers(collateral) : EMPTY_SUBSCRIBERS;
     const onResponse = this.onResponse;
     if (!onResponse) {
-      if (collateral2 && !error) {
+      if (collateral && !error) {
         const n = subscribers.length;
         if (n > 0) {
           const tasks = new Array(n);
@@ -539,16 +696,17 @@ var CNSStimulation = class {
       this.tryResolveCompleted();
       return;
     }
-    const subscriberActivationTasks = [];
-    if (collateral2 && !error) {
-      const pending = this.pendingTasks ?? (this.pendingTasks = /* @__PURE__ */ new Set());
+    let subscriberActivationTasks = EMPTY_TASKS;
+    if (collateral && !error && subscribers.length > 0) {
+      const pending = this.pendingTasks ?? (this.pendingTasks = []);
+      subscriberActivationTasks = new Array(subscribers.length);
       for (let i = 0; i < subscribers.length; i++) {
         const task = this.createSubscriberQueueItem(
           subscribers[i],
           outputSignal
         );
-        subscriberActivationTasks.push(task);
-        pending.add(task);
+        subscriberActivationTasks[i] = task;
+        this.addPositionedTask(pending, task, TASK_PENDING_POSITION);
       }
     }
     this.scheduledCount += subscriberActivationTasks.length;
@@ -562,16 +720,20 @@ var CNSStimulation = class {
           this.pendingActivations + this.activeOperations,
           this.pendingActivations,
           this.activeOperations,
-          this.options?.maxNeuronHops && emitter ? this.neuronVisitMap?.get(emitter) ?? 0 : void 0,
+          this.options?.maxNeuronHops && emitter ? this.neuronVisitCounts?.[emitter.index] ?? 0 : void 0,
           error,
-          emitter
+          emitter,
+          startedAt,
+          duration,
+          subscriberActivationTasks,
+          activationContext
         )
       );
     } catch (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.removePendingTask(subscriberActivationTasks[i]);
         this.qEnqueue(subscriberActivationTasks[i]);
       }
       this.tryResolveCompleted();
@@ -584,7 +746,7 @@ var CNSStimulation = class {
           try {
             for (let i = 0; i < subscriberActivationTasks.length; i++) {
               this.scheduledCount--;
-              this.pendingTasks?.delete(
+              this.removePendingTask(
                 subscriberActivationTasks[i]
               );
               this.qEnqueue(subscriberActivationTasks[i]);
@@ -600,7 +762,7 @@ var CNSStimulation = class {
           try {
             for (let i = 0; i < subscriberActivationTasks.length; i++) {
               this.scheduledCount--;
-              this.pendingTasks?.delete(
+              this.removePendingTask(
                 subscriberActivationTasks[i]
               );
               this.qEnqueue(subscriberActivationTasks[i]);
@@ -615,7 +777,7 @@ var CNSStimulation = class {
     }
     for (let i = 0; i < subscriberActivationTasks.length; i++) {
       this.scheduledCount--;
-      this.pendingTasks?.delete(subscriberActivationTasks[i]);
+      this.removePendingTask(subscriberActivationTasks[i]);
       this.qEnqueue(subscriberActivationTasks[i]);
     }
     this.tryResolveCompleted();
@@ -642,36 +804,36 @@ var CNSStimulation = class {
 // src/CNSInstanceNeuronQueue.ts
 var CNSInstanceNeuronQueue = class {
   constructor() {
-    this.gates = /* @__PURE__ */ new Map();
+    this.gatesByNeuronIndex = [];
   }
-  run(neuron2, fn) {
-    const limit = neuron2?.concurrency;
+  run(neuron, fn) {
+    const limit = neuron?.concurrency;
     if (limit === void 0 || limit <= 0) {
       return fn();
     }
-    let gate = this.gates.get(neuron2);
+    let gate = this.gatesByNeuronIndex[neuron.index];
     if (!gate) {
       gate = { limit, active: 0, waiters: [] };
-      this.gates.set(neuron2, gate);
+      this.gatesByNeuronIndex[neuron.index] = gate;
     } else {
       gate.limit = limit;
     }
+    const ownGate = gate;
     const wrap = (cb) => {
       return () => {
         try {
           cb();
         } finally {
-          const g = this.gates.get(neuron2);
-          g.active = Math.max(0, g.active - 1);
-          if (g.waiters.length > 0) {
-            const next = g.waiters.shift();
+          ownGate.active = Math.max(0, ownGate.active - 1);
+          if (ownGate.waiters.length > 0) {
+            const next = ownGate.waiters.shift();
             next();
           }
         }
       };
     };
-    if (gate.active < gate.limit) {
-      gate.active++;
+    if (ownGate.active < ownGate.limit) {
+      ownGate.active++;
       const ret = fn();
       if (ret && typeof ret.then === "function") {
         return ret.then((cb) => wrap(cb));
@@ -680,8 +842,7 @@ var CNSInstanceNeuronQueue = class {
     }
     return new Promise((resolve) => {
       const starter = () => {
-        const g = this.gates.get(neuron2);
-        g.active++;
+        ownGate.active++;
         const ret = fn();
         if (ret && typeof ret.then === "function") {
           ret.then((cb) => resolve(wrap(cb)));
@@ -689,12 +850,52 @@ var CNSInstanceNeuronQueue = class {
           resolve(wrap(ret));
         }
       };
-      gate.waiters.push(starter);
+      ownGate.waiters.push(starter);
     });
   }
 };
 
+// src/utils/cnsResolveModalityHandler.ts
+function cnsResolveModalityHandler(modalitySelection, modality, afferentPath) {
+  if (modality !== void 0) {
+    const modalityConfigs = modalitySelection.modalityConfigs;
+    for (let i = 0; i < modalityConfigs.length; i++) {
+      const modalityConfig = modalityConfigs[i];
+      if (modalityConfig.modality !== modality) continue;
+      for (let path = afferentPath; path !== void 0; path = path.parentAfferentPath) {
+        const handler = modalityConfig.afferentPaths?.get(path);
+        if (handler !== void 0) return handler;
+      }
+      if (modalityConfig.default !== void 0) return modalityConfig.default;
+      break;
+    }
+  }
+  return modalitySelection.defaultHandler;
+}
+
+// src/utils/cnsComposeModalityResponse.ts
+function cnsComposeModalityResponse(handler, output) {
+  return (payload, axon, ctx) => {
+    const maybeResult = handler(payload, axon, ctx);
+    if (maybeResult && typeof maybeResult.then === "function") {
+      return maybeResult.then((result) => output(result, axon, ctx));
+    }
+    try {
+      return output(maybeResult, axon, ctx);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("Cannot read properties of undefined")) {
+        const axonKeys = axon && typeof axon === "object" ? Object.keys(axon) : "not an object";
+        throw new Error(
+          `modalityDendrite: axon.output is undefined. Axon type: ${typeof axon}, Axon keys: ${Array.isArray(axonKeys) ? axonKeys.join(", ") : axonKeys}. Make sure the neuron was created with the correct axon structure. Original error: ${error.message}`
+        );
+      }
+      throw error;
+    }
+  };
+}
+
 // src/CNSNetwork.ts
+var NO_SUBSCRIBERS = [];
 var CNSNetwork = class {
   constructor(neurons) {
     this.neurons = neurons;
@@ -724,16 +925,19 @@ var CNSNetwork = class {
      * Fast lookup: collateral -> list of (neuron, dendrite) subscribers.
      * Built once at construction time.
      */
-    this.subIndex = /* @__PURE__ */ new Map();
+    this.subscribersByCollateralIndex = [];
+    this.allSubscribersByCollateralIndex = [];
+    this.modalityCollateralIndices = [];
+    this.subscriberTablesByModalityIndex = [];
     this.parentNeuronByCollateral = /* @__PURE__ */ new Map();
     this.buildIndexes();
   }
   get stronglyConnectedComponents() {
-    this.ensureSCC();
+    this.buildSccIndex();
     return this._stronglyConnectedComponents;
   }
   /** Build the SCC analysis the first time anything needs it. */
-  ensureSCC() {
+  buildSccIndex() {
     if (this.sccBuilt) return;
     this.sccBuilt = true;
     this.buildSCC();
@@ -743,23 +947,21 @@ var CNSNetwork = class {
    */
   buildNeuronGraph() {
     const graph = /* @__PURE__ */ new Map();
-    for (const neuron2 of this.neurons) {
-      graph.set(neuron2, /* @__PURE__ */ new Set());
+    for (const neuron of this.neurons) {
+      graph.set(neuron, /* @__PURE__ */ new Set());
     }
-    for (const neuron2 of this.neurons) {
+    for (const neuron of this.neurons) {
       const reachableNeurons = /* @__PURE__ */ new Set();
-      for (const axonKey in neuron2.axon) {
-        const collateral2 = neuron2.axon[axonKey];
-        const subscribers = this.subIndex.get(
-          collateral2
-        );
+      for (const axonKey in neuron.axon) {
+        const collateral = neuron.axon[axonKey];
+        const subscribers = this.allSubscribersByCollateralIndex[collateral.index];
         if (subscribers) {
           for (const { neuron: targetNeuron } of subscribers) {
             reachableNeurons.add(targetNeuron);
           }
         }
       }
-      graph.set(neuron2, reachableNeurons);
+      graph.set(neuron, reachableNeurons);
     }
     return graph;
   }
@@ -774,41 +976,41 @@ var CNSNetwork = class {
     const stack = [];
     const components = [];
     let currentIndex = 0;
-    const strongConnect = (neuron2) => {
-      index.set(neuron2, currentIndex);
-      lowlink.set(neuron2, currentIndex);
+    const strongConnect = (neuron) => {
+      index.set(neuron, currentIndex);
+      lowlink.set(neuron, currentIndex);
       currentIndex++;
-      stack.push(neuron2);
-      onStack.add(neuron2);
-      const neighbors = graph.get(neuron2) || /* @__PURE__ */ new Set();
+      stack.push(neuron);
+      onStack.add(neuron);
+      const neighbors = graph.get(neuron) || /* @__PURE__ */ new Set();
       for (const neighbor of Array.from(neighbors)) {
         if (!index.has(neighbor)) {
           strongConnect(neighbor);
           lowlink.set(
-            neuron2,
-            Math.min(lowlink.get(neuron2), lowlink.get(neighbor))
+            neuron,
+            Math.min(lowlink.get(neuron), lowlink.get(neighbor))
           );
         } else if (onStack.has(neighbor)) {
           lowlink.set(
-            neuron2,
-            Math.min(lowlink.get(neuron2), index.get(neighbor))
+            neuron,
+            Math.min(lowlink.get(neuron), index.get(neighbor))
           );
         }
       }
-      if (lowlink.get(neuron2) === index.get(neuron2)) {
+      if (lowlink.get(neuron) === index.get(neuron)) {
         const component = /* @__PURE__ */ new Set();
         let w;
         do {
           w = stack.pop();
           onStack.delete(w);
           component.add(w);
-        } while (w !== neuron2);
+        } while (w !== neuron);
         components.push(component);
       }
     };
-    for (const neuron2 of this.neurons) {
-      if (!index.has(neuron2)) {
-        strongConnect(neuron2);
+    for (const neuron of this.neurons) {
+      if (!index.has(neuron)) {
+        strongConnect(neuron);
       }
     }
     this._stronglyConnectedComponents = components;
@@ -830,8 +1032,8 @@ var CNSNetwork = class {
     }
     for (let i = 0; i < this._stronglyConnectedComponents.length; i++) {
       const scc = this._stronglyConnectedComponents[i];
-      for (const neuron2 of Array.from(scc)) {
-        const neighbors = neuronGraph.get(neuron2) || /* @__PURE__ */ new Set();
+      for (const neuron of Array.from(scc)) {
+        const neighbors = neuronGraph.get(neuron) || /* @__PURE__ */ new Set();
         for (const neighbor of Array.from(neighbors)) {
           const neighborSccIndex = this.neuronToSCC.get(neighbor);
           if (neighborSccIndex !== void 0 && neighborSccIndex !== i) {
@@ -884,26 +1086,26 @@ var CNSNetwork = class {
    * 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.
    */
-  getSCCSetByNeuron(neuron2) {
-    this.ensureSCC();
-    const sccIndex = this.neuronToSCC.get(neuron2);
+  getSCCSetByNeuron(neuron) {
+    this.buildSccIndex();
+    const sccIndex = this.neuronToSCC.get(neuron);
     if (sccIndex === void 0) return;
     return this._stronglyConnectedComponents[sccIndex];
   }
   /**
    * Get the SCC index for a given neuron
    */
-  getSccIndexByNeuron(neuron2) {
-    this.ensureSCC();
-    return this.neuronToSCC.get(neuron2);
+  getSccIndexByNeuron(neuron) {
+    this.buildSccIndex();
+    return this.neuronToSCC.get(neuron);
   }
   /**
    * 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(neuron2, activeSccCounts) {
-    this.ensureSCC();
-    const sccIndex = this.neuronToSCC.get(neuron2);
+  canNeuronBeGuaranteedDone(neuron, activeSccCounts) {
+    this.buildSccIndex();
+    const sccIndex = this.neuronToSCC.get(neuron);
     if (sccIndex === void 0) return true;
     if (activeSccCounts.get(sccIndex) && activeSccCounts.get(sccIndex) > 0) {
       return false;
@@ -917,36 +1119,93 @@ var CNSNetwork = class {
     }
     return true;
   }
+  describeNeuron(neuron) {
+    const axonKeys = Object.keys(neuron.axon);
+    return `neuron #${neuron.index} (${axonKeys.length === 0 ? "no axon" : `axon: ${axonKeys.join(", ")}`})`;
+  }
+  describeCollateral(neuron, collateral) {
+    const axonKey = Object.keys(neuron.axon).find((key) => neuron.axon[key] === collateral);
+    return `"${axonKey}" #${collateral.index}`;
+  }
   buildIndexes() {
-    this.subIndex.clear();
+    var _a;
+    this.allSubscribersByCollateralIndex = [];
+    this.modalityCollateralIndices = [];
+    this.subscriberTablesByModalityIndex = [];
     this.parentNeuronByCollateral.clear();
-    for (const neuron2 of this.neurons) {
-      for (const dendrite of neuron2.dendrites) {
-        const key = dendrite.collateral;
-        const arr = this.subIndex.get(key) ?? [];
-        arr.push({ neuron: neuron2, dendrite });
-        this.subIndex.set(
-          key,
-          arr
-        );
+    const listedNeurons = /* @__PURE__ */ new Set();
+    for (const neuron of this.neurons) {
+      if (listedNeurons.has(neuron)) {
+        throw new Error(`${this.describeNeuron(neuron)} is listed twice; every dendrite of it would run twice`);
+      }
+      listedNeurons.add(neuron);
+      for (const dendrite of neuron.dendrites) {
+        const index = dendrite.collateral.index;
+        const subscribers = (_a = this.allSubscribersByCollateralIndex)[index] ?? (_a[index] = []);
+        subscribers.push({ neuron, dendrite });
+        if (dendrite.modalitySelection !== void 0 && this.modalityCollateralIndices.indexOf(index) < 0) {
+          this.modalityCollateralIndices.push(index);
+        }
       }
-      Object.values(neuron2.axon).forEach((collateral2) => {
+      Object.values(neuron.axon).forEach((collateral) => {
+        const owner = this.parentNeuronByCollateral.get(collateral);
+        if (owner !== void 0 && owner !== neuron) {
+          throw new Error(
+            `collateral ${this.describeCollateral(neuron, collateral)} is in the axons of ${this.describeNeuron(owner)} and ${this.describeNeuron(neuron)}; a collateral is owned by one neuron`
+          );
+        }
         this.parentNeuronByCollateral.set(
-          collateral2,
-          neuron2
+          collateral,
+          neuron
         );
       });
     }
+    this.subscribersByCollateralIndex = this.buildSubscriberTable(void 0, void 0);
+  }
+  getSubscriberTable(modality, afferentPath) {
+    var _a, _b;
+    if (modality === void 0) return this.subscribersByCollateralIndex;
+    const subscriberTablesByAfferentPathIndex = (_a = this.subscriberTablesByModalityIndex)[_b = modality.index] ?? (_a[_b] = []);
+    const afferentPathSlot = afferentPath === void 0 ? 0 : afferentPath.index + 1;
+    return subscriberTablesByAfferentPathIndex[afferentPathSlot] ?? (subscriberTablesByAfferentPathIndex[afferentPathSlot] = this.buildSubscriberTable(modality, afferentPath));
+  }
+  buildSubscriberTable(modality, afferentPath) {
+    const subscriberTable = this.allSubscribersByCollateralIndex.slice();
+    const modalityCollateralIndices = this.modalityCollateralIndices;
+    for (let i = 0; i < modalityCollateralIndices.length; i++) {
+      const index = modalityCollateralIndices[i];
+      const resolvedSubscribers = [];
+      const subscribers = this.allSubscribersByCollateralIndex[index];
+      for (let j = 0; j < subscribers.length; j++) {
+        const subscriber = subscribers[j];
+        const modalitySelection = subscriber.dendrite.modalitySelection;
+        if (modalitySelection === void 0) {
+          resolvedSubscribers.push(subscriber);
+          continue;
+        }
+        const handler = cnsResolveModalityHandler(modalitySelection, modality, afferentPath);
+        if (handler === void 0) continue;
+        resolvedSubscribers.push({
+          neuron: subscriber.neuron,
+          dendrite: {
+            collateral: subscriber.dendrite.collateral,
+            response: cnsComposeModalityResponse(handler, modalitySelection.output)
+          }
+        });
+      }
+      subscriberTable[index] = resolvedSubscribers;
+    }
+    return subscriberTable;
   }
-  getParentNeuronByCollateral(collateral2) {
-    return this.parentNeuronByCollateral.get(collateral2);
+  getParentNeuronByCollateral(collateral) {
+    return this.parentNeuronByCollateral.get(collateral);
   }
   // Computed on demand (rarely used): one dendrite per collateral, last wins —
   // preserving the previous index semantics without building it every construct.
   getDendrites() {
     const byCollateral = /* @__PURE__ */ new Map();
-    for (const neuron2 of this.neurons) {
-      for (const dendrite of neuron2.dendrites) {
+    for (const neuron of this.neurons) {
+      for (const dendrite of neuron.dendrites) {
         byCollateral.set(
           dendrite.collateral,
           dendrite
@@ -957,15 +1216,15 @@ var CNSNetwork = class {
   }
   getCollaterals() {
     const collaterals = /* @__PURE__ */ new Set();
-    for (const neuron2 of this.neurons) {
-      for (const collateral2 of Object.values(neuron2.axon)) {
-        collaterals.add(collateral2);
+    for (const neuron of this.neurons) {
+      for (const collateral of Object.values(neuron.axon)) {
+        collaterals.add(collateral);
       }
     }
     return Array.from(collaterals);
   }
-  getSubscribers(collateral2) {
-    return this.subIndex.get(collateral2) ?? [];
+  getSubscribers(collateral) {
+    return this.subscribersByCollateralIndex[collateral.index] ?? NO_SUBSCRIBERS;
   }
 };
 
@@ -987,6 +1246,8 @@ var CNS = class {
      * Global batch-boundary listeners applied to every stimulation.
      */
     this.globalDrainListeners = [];
+    this.batchDepth = 0;
+    this.batchedDrains = [];
     this.network = new CNSNetwork(this.neurons);
     this.global = global;
   }
@@ -1006,7 +1267,7 @@ var CNS = class {
   }
   /**
    * Register a listener called once at the end of every synchronous turn of
-   * every stimulation - see {@link TCNSStimulationDrain}. This is how an
+   * every stimulation (inside `batch`, when the batch ends) - see {@link TCNSStimulationDrain}. This is how an
    * integration (a state manager, an in-memory database) installs a single
    * commit point for the whole organism instead of passing `onDrain` per call.
    *
@@ -1015,6 +1276,18 @@ var CNS = class {
   addDrainListener(listener) {
     return this.addListener(this.globalDrainListeners, listener);
   }
+  batch(run) {
+    this.batchDepth++;
+    try {
+      return run();
+    } finally {
+      if (--this.batchDepth === 0) {
+        const batchedDrains = this.batchedDrains;
+        this.batchedDrains = [];
+        for (const [announce, drain] of batchedDrains) announce(drain);
+      }
+    }
+  }
   /**
    * Fan a drain out to the local and global listeners, or return undefined when
    * there are none so the stimulation can skip the boundary check entirely.
@@ -1024,7 +1297,7 @@ var CNS = class {
    */
   wrapOnDrain(local) {
     if (this.globalDrainListeners.length === 0 && !local) return void 0;
-    return (d) => {
+    const announce = (d) => {
       if (local) {
         try {
           local(d);
@@ -1040,39 +1313,38 @@ var CNS = class {
         }
       }
     };
+    return (d) => {
+      if (this.batchDepth > 0) this.batchedDrains.push([announce, d]);
+      else announce(d);
+    };
   }
   wrapOnResponse(local) {
     if (this.globalResponseListeners.length === 0 && !local) {
       return void 0;
     }
     return (r) => {
-      let anyPromise = false;
-      const promises = [];
+      let promises;
       if (local) {
         try {
           const res = local(r);
           if (res && typeof res.then === "function") {
-            anyPromise = true;
-            promises.push(res);
+            (promises ?? (promises = [])).push(res);
           }
         } catch (error) {
-          anyPromise = true;
-          promises.push(Promise.reject(error));
+          (promises ?? (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);
+            (promises ?? (promises = [])).push(res);
           }
         } catch (error) {
-          anyPromise = true;
-          promises.push(Promise.reject(error));
+          (promises ?? (promises = [])).push(Promise.reject(error));
         }
       }
-      if (anyPromise) {
+      if (promises) {
         return Promise.allSettled(promises).then((results) => {
           const rejected = results.find(
             (r2) => r2.status === "rejected"
@@ -1107,8 +1379,20 @@ var CNS = class {
   }
 };
 
+// src/createCNS.ts
+var createCNS = (neuronFactories, dependencies, options) => {
+  if (new Set(neuronFactories).size !== neuronFactories.length) {
+    throw new Error("createCNS: a neuron factory is listed twice; every dendrite of its neuron would run twice");
+  }
+  return new CNS(neuronFactories.map((createNeuron) => createNeuron(dependencies)), options);
+};
+
 // src/CNSCollateral.ts
+var nextCollateralIndex = 0;
 var CNSCollateral = class {
+  constructor() {
+    this.index = nextCollateralIndex++;
+  }
   createSignal(payload) {
     return { collateral: this, payload };
   }
@@ -1164,8 +1448,11 @@ var CNSStimulationGate = class {
 };
 
 // src/factory/index.ts
-var collateral = () => new CNSCollateral();
-var neuron = (axon) => {
+var nextNeuronIndex = 0;
+var nextAfferentPathIndex = 0;
+var nextModalityIndex = 0;
+var cnsCollateral = () => new CNSCollateral();
+var cnsNeuron = (axon) => {
   const dendrites = [];
   const api = {
     setConcurrency: (n) => {
@@ -1189,15 +1476,16 @@ var neuron = (axon) => {
       }
       return api;
     }),
+    index: nextNeuronIndex++,
     axon,
     concurrency: void 0,
     maxDuration: void 0,
     dendrites,
     dendrite(s) {
       if ("collateral" in s && "response" in s && Array.isArray(s.collateral)) {
-        for (const collateral2 of s.collateral) {
+        for (const collateral of s.collateral) {
           dendrites.push({
-            collateral: collateral2,
+            collateral,
             response: s.response
           });
         }
@@ -1210,7 +1498,7 @@ var neuron = (axon) => {
     },
     modalityDendrite(s) {
       const {
-        collateral: collateral2,
+        collateral,
         modality: singleModality,
         modalities: multipleModalities,
         afferentPaths: singleAfferentPaths,
@@ -1227,83 +1515,52 @@ var neuron = (axon) => {
       const response = (payload, axon2, ctx) => {
         const stimulation = ctx.stimulation;
         const stimOptions = stimulation?.options;
-        const runGlobalDefault = () => {
-          if (!defaultHandler) {
-            throw new Error(
-              `modalityDendrite: No handler found for modality and no default handler provided`
-            );
-          }
-          const res = defaultHandler(payload, axon2, ctx);
-          if (res && typeof res.then === "function") {
-            return res.then(
-              (result) => output(result, axon2, ctx)
-            );
-          }
-          return output(res, axon2, ctx);
-        };
-        if (!stimOptions || !stimOptions.modality) {
-          return runGlobalDefault();
-        }
-        const matchingConfig = modalityConfigs.find(
-          (config) => config.modality === stimOptions.modality
+        const handler = cnsResolveModalityHandler(
+          modalitySelection,
+          stimOptions?.modality,
+          stimOptions?.afferentPath
         );
-        if (!matchingConfig) {
-          return runGlobalDefault();
-        }
-        const stimAfferentPath = stimOptions.afferentPath;
-        const handler = stimAfferentPath && matchingConfig.afferentPaths ? matchingConfig.afferentPaths.get(stimAfferentPath) : void 0;
-        const effectiveHandler = handler ?? matchingConfig.default ?? defaultHandler;
-        if (!effectiveHandler) {
+        if (handler === void 0) {
           throw new Error(
             `modalityDendrite: No handler found for afferent path in modality and no default handler provided`
           );
         }
-        const maybeResult = effectiveHandler(payload, axon2, ctx);
-        if (maybeResult && typeof maybeResult.then === "function") {
-          return maybeResult.then(
-            (result) => output(result, axon2, ctx)
-          );
-        }
-        try {
-          return output(maybeResult, axon2, ctx);
-        } catch (error) {
-          if (error instanceof Error && error.message.includes(
-            "Cannot read properties of undefined"
-          )) {
-            const axonKeys = axon2 && typeof axon2 === "object" ? Object.keys(axon2) : "not an object";
-            throw new Error(
-              `modalityDendrite: axon.output is undefined. Axon type: ${typeof axon2}, Axon keys: ${Array.isArray(axonKeys) ? axonKeys.join(", ") : axonKeys}. Make sure the neuron was created with the correct axon structure. Original error: ${error.message}`
-            );
-          }
-          throw error;
-        }
+        return cnsComposeModalityResponse(handler, output)(payload, axon2, ctx);
+      };
+      const modalitySelection = {
+        modalityConfigs,
+        defaultHandler,
+        output
       };
       dendrites.push({
-        collateral: collateral2,
-        response
+        collateral,
+        response,
+        modalitySelection
       });
       return api;
     }
   };
   return api;
 };
-var neuronFactory = () => {
+var cnsNeuronFactory = () => {
   const factory = {
     withGlobal: () => factory,
-    neuron: (axon) => neuron(axon)
+    neuron: (axon) => cnsNeuron(axon)
   };
   return factory;
 };
-var withGlobal = () => neuronFactory();
-var afferentPath = (parentAfferentPath) => {
+var withCNSGlobal = () => cnsNeuronFactory();
+var cnsAfferentPath = (parentAfferentPath) => {
   return {
+    index: nextAfferentPathIndex++,
     ...parentAfferentPath !== void 0 && {
       parentAfferentPath
     }
   };
 };
-var modality = (afferentPaths) => {
+var cnsModality = (afferentPaths) => {
   return {
+    index: nextModalityIndex++,
     afferentPaths
   };
 };
@@ -1311,11 +1568,12 @@ var modality = (afferentPaths) => {
 exports.CNS = CNS;
 exports.CNSCollateral = CNSCollateral;
 exports.CNSStimulationGate = CNSStimulationGate;
-exports.afferentPath = afferentPath;
-exports.collateral = collateral;
-exports.modality = modality;
-exports.neuron = neuron;
-exports.neuronFactory = neuronFactory;
-exports.withGlobal = withGlobal;
+exports.cnsAfferentPath = cnsAfferentPath;
+exports.cnsCollateral = cnsCollateral;
+exports.cnsModality = cnsModality;
+exports.cnsNeuron = cnsNeuron;
+exports.cnsNeuronFactory = cnsNeuronFactory;
+exports.createCNS = createCNS;
+exports.withCNSGlobal = withCNSGlobal;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map