@cnstra/core 1.8.1 → 2.0.1

package/dist/index.cjs

@@ -12,12 +12,11 @@ var CNSStimulationContextStore = class {
     this.ctx.set(key, value);
   }
   getAll() {
-    return Object.fromEntries(this.ctx);
+    return new Map(this.ctx);
   }
   setAll(values) {
-    for (const [key, value] of Object.entries(values)) {
-      this.ctx.set(key, value);
-    }
+    this.ctx.clear();
+    for (const [key, value] of values) this.ctx.set(key, value);
   }
   delete(key) {
     this.ctx.delete(key);
@@ -164,10 +163,7 @@ var CNSStimulation = class {
      * Track active SCCs: SCC index -> count of active neurons in that SCC
      */
     this.activeSccCounts = /* @__PURE__ */ new Map();
-    this.ctx = options?.ctx ?? new CNSStimulationContextStore(
-      new Map(Object.entries(options?.contextValues ?? {}))
-    );
-    this.id = options?.stimulationId || Math.random().toString(36).slice(2);
+    this.ctx = options?.ctx ?? new CNSStimulationContextStore();
     this.queue = new CNSNeuronActivationPump(
       (neuronActivationTask) => this.executeActivationTask(neuronActivationTask),
       options?.concurrency,
@@ -188,7 +184,7 @@ var CNSStimulation = class {
         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
+            (ft) => ft.task === task
           );
           if (!alreadyTracked) {
             this.failedTasks.push({
@@ -244,11 +240,7 @@ var CNSStimulation = class {
    */
   enqueueTasks(tasks) {
     for (const task of tasks) {
-      const taskWithId = {
-        ...task,
-        stimulationId: this.id
-      };
-      this.queue.enqueue(taskWithId);
+      this.queue.enqueue(task);
     }
     this.tryResolveCompleted();
   }
@@ -261,22 +253,22 @@ var CNSStimulation = class {
   /**
    * Mark a neuron as active (being processed)
    */
-  markNeuronActive(neuronId) {
+  markNeuronActive(neuron2) {
     if (!this.autoCleanupContextsEnabled) return;
-    this.incrementSccCount(neuronId);
+    this.incrementSccCount(neuron2);
   }
   /**
    * Mark a neuron as inactive (finished processing)
    */
-  markNeuronInactive(neuronId) {
+  markNeuronInactive(neuron2) {
     if (!this.autoCleanupContextsEnabled) return;
-    this.decrementSccCount(neuronId);
+    this.decrementSccCount(neuron2);
   }
   /**
    * Increment the active count for the SCC containing this neuron
    */
-  incrementSccCount(neuronId) {
-    const sccIndex = this.cns.network.getSccIndexByNeuronName(neuronId);
+  incrementSccCount(neuron2) {
+    const sccIndex = this.cns.network.getSccIndexByNeuron(neuron2);
     if (sccIndex === void 0) return;
     const currentCount = this.activeSccCounts.get(sccIndex) || 0;
     this.activeSccCounts.set(sccIndex, currentCount + 1);
@@ -284,66 +276,65 @@ var CNSStimulation = class {
   /**
    * Decrement the active count for the SCC containing this neuron
    */
-  decrementSccCount(neuronId) {
-    const sccIndex = this.cns.network.getSccIndexByNeuronName(neuronId);
+  decrementSccCount(neuron2) {
+    const sccIndex = this.cns.network.getSccIndexByNeuron(neuron2);
     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}`
+        `[CNSStimulation] Attempting to decrement SCC count below 0 for neuron`
       );
     }
   }
   /**
    * Check if a neuron can be guaranteed not to be visited again
    */
-  canNeuronBeGuaranteedDone(neuronId) {
+  canNeuronBeGuaranteedDone(neuron2) {
     if (!this.autoCleanupContextsEnabled) return false;
     return this.cns.network.canNeuronBeGuaranteedDone(
-      neuronId,
+      neuron2,
       this.activeSccCounts
     );
   }
   cleanupCtxIfNeeded(neuron2) {
-    if (this.autoCleanupContextsEnabled && this.canNeuronBeGuaranteedDone(neuron2.name)) {
-      this.ctx.delete(neuron2.name);
+    if (this.autoCleanupContextsEnabled && this.canNeuronBeGuaranteedDone(neuron2)) {
+      this.ctx.delete(neuron2);
     }
   }
   createSubscriberQueueItem(subscriber, inputSignal) {
     if (this.options?.maxNeuronHops) {
-      if (this.nueronVisitMap?.get(subscriber.neuron.name) ?? 0 >= this.options?.maxNeuronHops) {
+      if ((this.nueronVisitMap?.get(subscriber.neuron) ?? 0) >= this.options?.maxNeuronHops) {
         throw new Error(
-          `Max neuron hops reached for neuron "${subscriber.neuron.name}" when trying to enqueue subscriber "${subscriber.dendrite.collateral.name}" in stimulation "${this.id}"`
+          `Max neuron hops reached when trying to enqueue subscriber`
         );
       } else {
         this.nueronVisitMap?.set(
-          subscriber.neuron.name,
-          (this.nueronVisitMap?.get(subscriber.neuron.name) ?? 0) + 1
+          subscriber.neuron,
+          (this.nueronVisitMap?.get(subscriber.neuron) ?? 0) + 1
         );
       }
     }
     const neuronActivationTask = {
-      stimulationId: this.id,
-      neuronId: subscriber.neuron.name,
-      dendriteCollateralName: subscriber.dendrite.collateral.name,
+      neuron: subscriber.neuron,
+      dendriteCollateral: subscriber.dendrite.collateral,
       input: inputSignal
     };
     return neuronActivationTask;
   }
   executeActivationTask(neuronActivationTask) {
     const subscribers = this.cns.network.getSubscribers(
-      neuronActivationTask.dendriteCollateralName
+      neuronActivationTask.dendriteCollateral
     );
     const subscriber = subscribers.find(
-      (s) => s.neuron.name === neuronActivationTask.neuronId
+      (s) => s.neuron === neuronActivationTask.neuron
     );
     if (!subscriber) {
       this.failedTasks.push({
         task: neuronActivationTask,
         error: new Error(
-          `Subscriber not found for neuron "${neuronActivationTask.neuronId}" and collateral "${neuronActivationTask.dendriteCollateralName}"`
+          `Subscriber not found for activation task`
         ),
         aborted: false
       });
@@ -352,28 +343,25 @@ var CNSStimulation = class {
     }
     const neuron2 = subscriber.neuron;
     const dendrite = subscriber.dendrite;
-    const inputSignal = neuronActivationTask.input ? {
-      collateralName: neuronActivationTask.input.collateralName,
-      payload: neuronActivationTask.input.payload
-    } : void 0;
+    const inputSignal = neuronActivationTask.input;
     const starter = () => {
-      this.markNeuronActive(neuron2.name);
+      this.markNeuronActive(neuron2);
       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),
+            get: () => this.ctx.get(neuron2),
+            set: (value) => this.ctx.set(neuron2, value),
+            delete: () => this.ctx.delete(neuron2),
             abortSignal: this.options?.abortSignal,
             cns: this.cns,
-            stimulationId: this.id
+            stimulation: this
           }
         );
       } catch (error) {
-        this.markNeuronInactive(neuron2.name);
+        this.markNeuronInactive(neuron2);
         const isAborted = this.options?.abortSignal?.aborted ?? false;
         this.failedTasks.push({
           task: neuronActivationTask,
@@ -381,6 +369,7 @@ var CNSStimulation = class {
           aborted: isAborted
         });
         this.processResponseOrResponses(
+          neuron2,
           inputSignal,
           void 0,
           error
@@ -393,9 +382,7 @@ var CNSStimulation = class {
       const timedPromise = maxDuration && maxDuration > 0 ? new Promise((resolve, reject) => {
         const t = setTimeout(() => {
           const err = new Error(
-            `Neuron "${String(
-              neuron2.name
-            )}" exceeded maxDuration ${maxDuration}ms`
+            `Neuron exceeded maxDuration ${maxDuration}ms`
           );
           reject(err);
         }, maxDuration);
@@ -414,8 +401,9 @@ var CNSStimulation = class {
         return timedPromise.then(
           (signal) => {
             return () => {
-              this.markNeuronInactive(neuron2.name);
+              this.markNeuronInactive(neuron2);
               return this.processResponseOrResponses(
+                neuron2,
                 inputSignal,
                 signal
               );
@@ -423,7 +411,7 @@ var CNSStimulation = class {
           },
           (error) => {
             return () => {
-              this.markNeuronInactive(neuron2.name);
+              this.markNeuronInactive(neuron2);
               const isAborted = this.options?.abortSignal?.aborted ?? false;
               this.failedTasks.push({
                 task: neuronActivationTask,
@@ -431,6 +419,7 @@ var CNSStimulation = class {
                 aborted: isAborted
               });
               return this.processResponseOrResponses(
+                neuron2,
                 inputSignal,
                 void 0,
                 error
@@ -440,8 +429,9 @@ var CNSStimulation = class {
         );
       } else {
         return () => {
-          this.markNeuronInactive(neuron2.name);
+          this.markNeuronInactive(neuron2);
           return this.processResponseOrResponses(
+            neuron2,
             inputSignal,
             response
           );
@@ -450,28 +440,25 @@ var CNSStimulation = class {
     };
     return this.instanceNeuronQueue.run(neuron2, starter);
   }
-  processResponseOrResponses(inputSignal, outputSignalOrSignals, error) {
+  processResponseOrResponses(emitter, inputSignal, outputSignalOrSignals, error) {
     if (Array.isArray(outputSignalOrSignals)) {
       if (outputSignalOrSignals.length === 0) {
-        this.processResponse(inputSignal, void 0, error);
+        this.processResponse(emitter, inputSignal, void 0, error);
         return;
       }
       for (const signal of outputSignalOrSignals) {
-        this.processResponse(inputSignal, signal, error);
+        this.processResponse(emitter, inputSignal, signal, error);
       }
       return;
     }
-    this.processResponse(inputSignal, outputSignalOrSignals, error);
+    this.processResponse(emitter, inputSignal, outputSignalOrSignals, error);
   }
-  processResponse(inputSignal, outputSignal, error) {
-    const collateralName = outputSignal?.collateralName;
-    const ownerNeuron = collateralName ? this.cns.network.getParentNeuronByCollateralName(collateralName) : void 0;
-    const subscribers = collateralName ? this.cns.network.getSubscribers(collateralName) : [];
+  processResponse(emitter, inputSignal, outputSignal, error) {
+    const collateral2 = outputSignal?.collateral;
+    const subscribers = collateral2 ? this.cns.network.getSubscribers(collateral2) : [];
     const subscriberActivationTasks = [];
-    if (collateralName && !error) {
-      if (ownerNeuron) {
-        this.cleanupCtxIfNeeded(ownerNeuron);
-      }
+    if (collateral2 && !error) {
+      if (emitter) this.cleanupCtxIfNeeded(emitter);
       for (let i = 0; i < subscribers.length; i++) {
         const task = this.createSubscriberQueueItem(
           subscribers[i],
@@ -490,8 +477,7 @@ var CNSStimulation = class {
         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,
+        hops: this.options?.maxNeuronHops && emitter ? this.nueronVisitMap?.get(emitter) ?? 0 : void 0,
         error
       });
     } catch (e) {
@@ -535,24 +521,10 @@ var CNSStimulation = class {
   }
   responseToSignal(signalOrSignals) {
     if (Array.isArray(signalOrSignals)) {
-      for (const signal of signalOrSignals) {
-        const ownerNeuron2 = this.cns.network.getParentNeuronByCollateralName(
-          signal.collateralName
-        );
-        if (ownerNeuron2) {
-          this.markNeuronActive(ownerNeuron2.name);
-        }
-      }
-      this.processResponseOrResponses(void 0, signalOrSignals);
+      this.processResponseOrResponses(void 0, void 0, signalOrSignals);
       return;
     }
-    const ownerNeuron = this.cns.network.getParentNeuronByCollateralName(
-      signalOrSignals.collateralName
-    );
-    if (ownerNeuron) {
-      this.markNeuronActive(ownerNeuron.name);
-    }
-    this.processResponse(void 0, signalOrSignals);
+    this.processResponse(void 0, void 0, signalOrSignals);
     this.tryResolveCompleted();
   }
 };
@@ -567,10 +539,10 @@ var CNSInstanceNeuronQueue = class {
     if (limit === void 0 || limit <= 0) {
       return fn();
     }
-    let gate = this.gates.get(neuron2.name);
+    let gate = this.gates.get(neuron2);
     if (!gate) {
       gate = { limit, active: 0, waiters: [] };
-      this.gates.set(neuron2.name, gate);
+      this.gates.set(neuron2, gate);
     } else {
       gate.limit = limit;
     }
@@ -579,7 +551,7 @@ var CNSInstanceNeuronQueue = class {
         try {
           cb();
         } finally {
-          const g = this.gates.get(neuron2.name);
+          const g = this.gates.get(neuron2);
           g.active = Math.max(0, g.active - 1);
           if (g.waiters.length > 0) {
             const next = g.waiters.shift();
@@ -598,7 +570,7 @@ var CNSInstanceNeuronQueue = class {
     }
     return new Promise((resolve) => {
       const starter = () => {
-        const g = this.gates.get(neuron2.name);
+        const g = this.gates.get(neuron2);
         g.active++;
         const ret = fn();
         if (ret && typeof ret.then === "function") {
@@ -618,11 +590,11 @@ var CNSNetwork = class {
     this.neurons = neurons;
     /**
      * Strongly Connected Components of the neuron graph.
-     * Each component is a set of neuron IDs that can reach each other.
+     * Each component is a set of neuron objects that can reach each other.
      */
     this.stronglyConnectedComponents = [];
     /**
-     * Quick lookup: neuron ID -> SCC index for fast reachability checks.
+     * Quick lookup: neuron -> SCC index for fast reachability checks.
      */
     this.neuronToSCC = /* @__PURE__ */ new Map();
     /**
@@ -634,68 +606,48 @@ var CNSNetwork = class {
      */
     this.sccAncestors = /* @__PURE__ */ new Map();
     /**
-     * Fast lookup: collateralName -> list of (neuron, dendrite) subscribers.
+     * Fast lookup: collateral -> 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();
+    this.collateralIndex = /* @__PURE__ */ new Set();
+    this.parentNeuronByCollateral = /* @__PURE__ */ new Map();
     this.validateUniqueIdentifiers();
     this.buildIndexes();
     this.buildSCC();
   }
   /**
    * Validate uniqueness constraints:
-   * - neuron names are unique and non-empty
-   * - axon collateral types are globally unique (single owner)
-   * - the same collateral instance cannot be owned by multiple neurons
+   * - (legacy) collateral instances used to be single-owner; in object-identity routing
+   *   a collateral can be emitted by multiple neurons (fan-in), so we no longer
+   *   enforce single ownership here.
    * Throws aggregated error if violations are found.
    */
   validateUniqueIdentifiers() {
-    const errors = [];
-    const seenNeuronNames = /* @__PURE__ */ new Set();
-    for (const neuron2 of this.neurons) {
-      const name = neuron2?.name ?? "";
-      if (!name || typeof name !== "string" || name.trim().length === 0) {
-        errors.push(`Neuron has empty or invalid name: "${name}"`);
-      } else if (seenNeuronNames.has(name)) {
-        errors.push(`Duplicate neuron name: "${name}"`);
-      } else {
-        seenNeuronNames.add(name);
-      }
-    }
-    if (errors.length > 0) {
-      throw new Error(
-        `[CNS] Topology uniqueness validation failed:
- - ` + errors.join(`
- - `)
-      );
-    }
   }
   /**
    * Build the neuron graph where neurons are connected if one can stimulate the other.
    */
   buildNeuronGraph() {
     const graph = /* @__PURE__ */ new Map();
-    const neuronIds = this.neurons.map((n) => n.name);
-    for (const neuronId of neuronIds) {
-      graph.set(neuronId, /* @__PURE__ */ new Set());
+    for (const neuron2 of this.neurons) {
+      graph.set(neuron2, /* @__PURE__ */ new Set());
     }
     for (const neuron2 of this.neurons) {
       const reachableNeurons = /* @__PURE__ */ new Set();
       for (const axonKey in neuron2.axon) {
         const collateral2 = neuron2.axon[axonKey];
-        const collateralName = collateral2.name;
-        const subscribers = this.subIndex.get(collateralName);
+        const subscribers = this.subIndex.get(
+          collateral2
+        );
         if (subscribers) {
           for (const { neuron: targetNeuron } of subscribers) {
-            reachableNeurons.add(targetNeuron.name);
+            reachableNeurons.add(targetNeuron);
           }
         }
       }
-      graph.set(neuron2.name, reachableNeurons);
+      graph.set(neuron2, reachableNeurons);
     }
     return graph;
   }
@@ -704,48 +656,47 @@ var CNSNetwork = class {
    */
   buildSCC() {
     const graph = this.buildNeuronGraph();
-    const neuronIds = this.neurons.map((n) => n.name);
     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);
+    const strongConnect = (neuron2) => {
+      index.set(neuron2, currentIndex);
+      lowlink.set(neuron2, currentIndex);
       currentIndex++;
-      stack.push(neuronId);
-      onStack.add(neuronId);
-      const neighbors = graph.get(neuronId) || /* @__PURE__ */ new Set();
+      stack.push(neuron2);
+      onStack.add(neuron2);
+      const neighbors = graph.get(neuron2) || /* @__PURE__ */ new Set();
       for (const neighbor of Array.from(neighbors)) {
         if (!index.has(neighbor)) {
           strongConnect(neighbor);
           lowlink.set(
-            neuronId,
-            Math.min(lowlink.get(neuronId), lowlink.get(neighbor))
+            neuron2,
+            Math.min(lowlink.get(neuron2), lowlink.get(neighbor))
           );
         } else if (onStack.has(neighbor)) {
           lowlink.set(
-            neuronId,
-            Math.min(lowlink.get(neuronId), index.get(neighbor))
+            neuron2,
+            Math.min(lowlink.get(neuron2), index.get(neighbor))
           );
         }
       }
-      if (lowlink.get(neuronId) === index.get(neuronId)) {
+      if (lowlink.get(neuron2) === index.get(neuron2)) {
         const component = /* @__PURE__ */ new Set();
         let w;
         do {
           w = stack.pop();
           onStack.delete(w);
           component.add(w);
-        } while (w !== neuronId);
+        } while (w !== neuron2);
         components.push(component);
       }
     };
-    for (const neuronId of neuronIds) {
-      if (!index.has(neuronId)) {
-        strongConnect(neuronId);
+    for (const neuron2 of this.neurons) {
+      if (!index.has(neuron2)) {
+        strongConnect(neuron2);
       }
     }
     this.stronglyConnectedComponents = components;
@@ -767,10 +718,10 @@ var CNSNetwork = class {
     }
     for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
       const scc = this.stronglyConnectedComponents[i];
-      for (const neuronId of Array.from(scc)) {
-        const neighbors = neuronGraph.get(neuronId) || /* @__PURE__ */ new Set();
-        for (const neighborId of Array.from(neighbors)) {
-          const neighborSccIndex = this.neuronToSCC.get(neighborId);
+      for (const neuron2 of Array.from(scc)) {
+        const neighbors = neuronGraph.get(neuron2) || /* @__PURE__ */ new Set();
+        for (const neighbor of Array.from(neighbors)) {
+          const neighborSccIndex = this.neuronToSCC.get(neighbor);
           if (neighborSccIndex !== void 0 && neighborSccIndex !== i) {
             this.sccDag.get(neighborSccIndex).add(i);
           }
@@ -831,23 +782,23 @@ 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.
    */
-  getSCCSetByNeuronName(neuronName) {
-    const sccIndex = this.neuronToSCC.get(neuronName);
+  getSCCSetByNeuron(neuron2) {
+    const sccIndex = this.neuronToSCC.get(neuron2);
     if (sccIndex === void 0) return;
     return this.stronglyConnectedComponents[sccIndex];
   }
   /**
-   * Get the SCC index for a given neuron ID
+   * Get the SCC index for a given neuron
    */
-  getSccIndexByNeuronName(neuronName) {
-    return this.neuronToSCC.get(neuronName);
+  getSccIndexByNeuron(neuron2) {
+    return this.neuronToSCC.get(neuron2);
   }
   /**
    * 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(neuronName, activeSccCounts) {
-    const sccIndex = this.neuronToSCC.get(neuronName);
+  canNeuronBeGuaranteedDone(neuron2, activeSccCounts) {
+    const sccIndex = this.neuronToSCC.get(neuron2);
     if (sccIndex === void 0) return true;
     if (activeSccCounts.get(sccIndex) && activeSccCounts.get(sccIndex) > 0) {
       return false;
@@ -863,11 +814,12 @@ var CNSNetwork = class {
   }
   buildIndexes() {
     this.subIndex.clear();
-    this.parentNeuronByCollateralName.clear();
+    this.parentNeuronByCollateral.clear();
+    this.dendriteIndex.clear();
+    this.collateralIndex.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 key = dendrite.collateral;
         const arr = this.subIndex.get(key) ?? [];
         arr.push({ neuron: neuron2, dendrite });
         this.subIndex.set(
@@ -877,19 +829,16 @@ var CNSNetwork = class {
         this.dendriteIndex.set(key, dendrite);
       }
       Object.values(neuron2.axon).forEach((collateral2) => {
-        this.parentNeuronByCollateralName.set(
-          collateral2.name,
+        this.parentNeuronByCollateral.set(
+          collateral2,
           neuron2
         );
-        this.collateralIndex.set(
-          collateral2.name,
-          collateral2
-        );
+        this.collateralIndex.add(collateral2);
       });
     }
   }
-  getParentNeuronByCollateralName(collateralName) {
-    return this.parentNeuronByCollateralName.get(collateralName);
+  getParentNeuronByCollateral(collateral2) {
+    return this.parentNeuronByCollateral.get(collateral2);
   }
   getDendrites() {
     return Array.from(this.dendriteIndex.values());
@@ -897,19 +846,8 @@ var CNSNetwork = class {
   getCollaterals() {
     return Array.from(this.collateralIndex.values());
   }
-  getNeurons() {
-    return Array.from(this.neuronIndex.values());
-  }
-  getCollateralByName(collateralName) {
-    return this.collateralIndex.get(
-      collateralName
-    );
-  }
-  getNeuronByName(neuronName) {
-    return this.neuronIndex.get(neuronName);
-  }
-  getSubscribers(collateralName) {
-    return this.subIndex.get(collateralName) ?? [];
+  getSubscribers(collateral2) {
+    return this.subIndex.get(collateral2) ?? [];
   }
 };
 
@@ -918,10 +856,6 @@ 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.
@@ -987,10 +921,14 @@ var CNS = class {
   }
   stimulate(signalOrSignals, options) {
     const wrapped = this.wrapOnResponse(options?.onResponse);
-    const stimulation = new CNSStimulation(this, this.instanceNeuronQueue, {
-      ...options,
-      onResponse: wrapped
-    });
+    const stimulation = new CNSStimulation(
+      this,
+      this.instanceNeuronQueue,
+      {
+        ...options,
+        onResponse: wrapped
+      }
+    );
     stimulation.responseToSignal(signalOrSignals);
     return stimulation;
   }
@@ -999,10 +937,14 @@ var CNS = class {
    */
   activate(tasks, options) {
     const wrapped = this.wrapOnResponse(options?.onResponse);
-    const stimulation = new CNSStimulation(this, this.instanceNeuronQueue, {
-      ...options,
-      onResponse: wrapped
-    });
+    const stimulation = new CNSStimulation(
+      this,
+      this.instanceNeuronQueue,
+      {
+        ...options,
+        onResponse: wrapped
+      }
+    );
     stimulation.enqueueTasks(tasks);
     return stimulation;
   }
@@ -1010,17 +952,63 @@ var CNS = class {
 
 // src/CNSCollateral.ts
 var CNSCollateral = class {
-  constructor(name) {
-    this.name = name;
-  }
   createSignal(payload) {
-    return { collateralName: this.name, payload };
+    return { collateral: this, payload };
+  }
+};
+
+// src/utils/CNSDrainGuard.ts
+var CNSDrainGuard = class {
+  constructor(guardOptions) {
+    this.guardOptions = guardOptions;
+  }
+  isDraining() {
+    return this.currentDrain !== void 0;
+  }
+  getCurrentStimulation() {
+    return this.currentStimulation;
+  }
+  drain() {
+    if (this.currentDrain) return this.currentDrain;
+    const stimulation = this.guardOptions.cns.stimulate(
+      this.guardOptions.signal,
+      this.createStimulationOptions()
+    );
+    const drain = stimulation.waitUntilComplete().finally(() => {
+      if (this.currentDrain !== drain) return;
+      this.currentDrain = void 0;
+      this.currentStimulation = void 0;
+      this.currentAbortController = void 0;
+    });
+    this.currentStimulation = stimulation;
+    this.currentDrain = drain;
+    return drain;
+  }
+  abort(reason) {
+    if (!this.currentAbortController) return false;
+    if (this.currentAbortController.signal.aborted) return false;
+    this.currentAbortController.abort(reason);
+    return true;
+  }
+  createStimulationOptions() {
+    const options = this.guardOptions.options;
+    if (options?.abortSignal) {
+      return options;
+    }
+    if (typeof AbortController === "undefined") {
+      return options ?? {};
+    }
+    this.currentAbortController = new AbortController();
+    return {
+      ...options,
+      abortSignal: this.currentAbortController.signal
+    };
   }
 };
 
 // src/factory/index.ts
-var collateral = (name) => new CNSCollateral(name);
-var neuron = (name, axon) => {
+var collateral = () => new CNSCollateral();
+var neuron = (axon) => {
   const dendrites = [];
   const api = {
     setConcurrency: (n) => {
@@ -1045,29 +1033,129 @@ var neuron = (name, axon) => {
       return api;
     }),
     axon,
-    name,
     concurrency: void 0,
     maxDuration: void 0,
     dendrites,
     dendrite(s) {
-      dendrites.push(
-        s
-      );
+      if ("collateral" in s && "response" in s && Array.isArray(s.collateral)) {
+        for (const collateral2 of s.collateral) {
+          dendrites.push({
+            collateral: collateral2,
+            response: s.response
+          });
+        }
+      } else {
+        dendrites.push(
+          s
+        );
+      }
+      return api;
+    },
+    modalityDendrite(s) {
+      const {
+        collateral: collateral2,
+        modality: singleModality,
+        modalities: multipleModalities,
+        afferentPaths: singleAfferentPaths,
+        default: singleDefaultHandler,
+        default: globalDefaultHandler,
+        output
+      } = s;
+      const modalityConfigs = multipleModalities ? multipleModalities : singleModality ? [
+        {
+          modality: singleModality,
+          afferentPaths: singleAfferentPaths,
+          default: singleDefaultHandler
+        }
+      ] : [];
+      const response = (payload, axon2, ctx) => {
+        const stimulation = ctx.stimulation;
+        const stimOptions = stimulation?.options;
+        const runGlobalDefault = () => {
+          if (!globalDefaultHandler) {
+            throw new Error(
+              `modalityDendrite: No handler found for modality and no default handler provided`
+            );
+          }
+          const res = globalDefaultHandler(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
+        );
+        if (!matchingConfig) {
+          return runGlobalDefault();
+        }
+        const stimAfferentPath = stimOptions.afferentPath;
+        const handler = stimAfferentPath && matchingConfig.afferentPaths ? matchingConfig.afferentPaths.get(stimAfferentPath) : void 0;
+        const effectiveHandler = handler ?? matchingConfig.default ?? globalDefaultHandler;
+        if (!effectiveHandler) {
+          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;
+        }
+      };
+      dendrites.push({
+        collateral: collateral2,
+        response
+      });
       return api;
     }
   };
   return api;
 };
 var withCtx = () => ({
-  neuron: (name, axon) => {
-    return neuron(name, axon);
+  neuron: (axon) => {
+    return neuron(axon);
   }
 });
+var afferentPath = (parentAfferentPath) => {
+  return {
+    ...parentAfferentPath !== void 0 && {
+      parentAfferentPath
+    }
+  };
+};
+var modality = (afferentPaths) => {
+  return {
+    afferentPaths
+  };
+};
 
 exports.CNS = CNS;
 exports.CNSCollateral = CNSCollateral;
+exports.CNSDrainGuard = CNSDrainGuard;
 exports.CNSStimulationContextStore = CNSStimulationContextStore;
+exports.afferentPath = afferentPath;
 exports.collateral = collateral;
+exports.modality = modality;
 exports.neuron = neuron;
 exports.withCtx = withCtx;
 //# sourceMappingURL=index.cjs.map