@cnstra/core 2.2.1 → 2.3.0

package/dist/index.js

@@ -23,6 +23,7 @@ var CNSStimulationContextStore = class {
 };
 
 // src/CNSStimulation.ts
+var TASK_DENDRITE = /* @__PURE__ */ Symbol("cnstra.taskDendrite");
 var CNSDendriteContext = class {
   constructor(stimulation, neuron2, abortSignal, cns) {
     this.stimulation = stimulation;
@@ -73,7 +74,7 @@ var CNSStimulation = class {
     this.instanceNeuronQueue = instanceNeuronQueue;
     this.onResponse = onResponse;
     if (this.options?.maxNeuronHops) {
-      this.nueronVisitMap = /* @__PURE__ */ new Map();
+      this.neuronVisitMap = /* @__PURE__ */ new Map();
     }
     if (this.autoCleanupContextsEnabled) {
       this.activeSccCounts = /* @__PURE__ */ new Map();
@@ -338,14 +339,14 @@ var CNSStimulation = class {
   }
   createSubscriberQueueItem(subscriber, inputSignal) {
     if (this.options?.maxNeuronHops) {
-      if ((this.nueronVisitMap?.get(subscriber.neuron) ?? 0) >= this.options?.maxNeuronHops) {
+      if ((this.neuronVisitMap?.get(subscriber.neuron) ?? 0) >= this.options?.maxNeuronHops) {
         throw new Error(
           `Max neuron hops reached when trying to enqueue subscriber`
         );
       } else {
-        this.nueronVisitMap?.set(
+        this.neuronVisitMap?.set(
           subscriber.neuron,
-          (this.nueronVisitMap?.get(subscriber.neuron) ?? 0) + 1
+          (this.neuronVisitMap?.get(subscriber.neuron) ?? 0) + 1
         );
       }
     }
@@ -354,17 +355,20 @@ var CNSStimulation = class {
       dendriteCollateral: subscriber.dendrite.collateral,
       input: inputSignal
     };
+    neuronActivationTask[TASK_DENDRITE] = subscriber;
     return neuronActivationTask;
   }
   executeActivationTask(neuronActivationTask) {
-    const subscribers = this.cns.network.getSubscribers(
-      neuronActivationTask.dendriteCollateral
-    );
-    let subscriber;
-    for (let i = 0; i < subscribers.length; i++) {
-      if (subscribers[i].neuron === neuronActivationTask.neuron) {
-        subscriber = subscribers[i];
-        break;
+    let subscriber = neuronActivationTask[TASK_DENDRITE];
+    if (!subscriber) {
+      const subscribers = this.cns.network.getSubscribers(
+        neuronActivationTask.dendriteCollateral
+      );
+      for (let i = 0; i < subscribers.length; i++) {
+        if (subscribers[i].neuron === neuronActivationTask.neuron) {
+          subscriber = subscribers[i];
+          break;
+        }
       }
     }
     if (!subscriber) {
@@ -554,7 +558,7 @@ var CNSStimulation = class {
           inputSignal,
           outputSignal,
           this.qSize + this.scheduledCount,
-          this.options?.maxNeuronHops && emitter ? this.nueronVisitMap?.get(emitter) ?? 0 : void 0,
+          this.options?.maxNeuronHops && emitter ? this.neuronVisitMap?.get(emitter) ?? 0 : void 0,
           error
         )
       );
@@ -669,8 +673,12 @@ var CNSNetwork = class {
     /**
      * Strongly Connected Components of the neuron graph.
      * Each component is a set of neuron objects that can reach each other.
+     *
+     * Computed lazily on first access: the SCC machinery is only needed for
+     * `autoCleanupContexts` (off by default), so most networks never pay for it.
      */
-    this.stronglyConnectedComponents = [];
+    this._stronglyConnectedComponents = [];
+    this.sccBuilt = false;
     /**
      * Quick lookup: neuron -> SCC index for fast reachability checks.
      */
@@ -688,21 +696,18 @@ var CNSNetwork = class {
      * Built once at construction time.
      */
     this.subIndex = /* @__PURE__ */ new Map();
-    this.dendriteIndex = /* @__PURE__ */ new Map();
-    this.collateralIndex = /* @__PURE__ */ new Set();
     this.parentNeuronByCollateral = /* @__PURE__ */ new Map();
-    this.validateUniqueIdentifiers();
     this.buildIndexes();
-    this.buildSCC();
   }
-  /**
-   * Validate uniqueness constraints:
-   * - (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() {
+  get stronglyConnectedComponents() {
+    this.ensureSCC();
+    return this._stronglyConnectedComponents;
+  }
+  /** Build the SCC analysis the first time anything needs it. */
+  ensureSCC() {
+    if (this.sccBuilt) return;
+    this.sccBuilt = true;
+    this.buildSCC();
   }
   /**
    * Build the neuron graph where neurons are connected if one can stimulate the other.
@@ -777,7 +782,7 @@ var CNSNetwork = class {
         strongConnect(neuron2);
       }
     }
-    this.stronglyConnectedComponents = components;
+    this._stronglyConnectedComponents = components;
     for (let i = 0; i < components.length; i++) {
       for (const neuronId of Array.from(components[i])) {
         this.neuronToSCC.set(neuronId, i);
@@ -791,11 +796,11 @@ var CNSNetwork = class {
    */
   buildSCCDAG(neuronGraph) {
     this.sccDag.clear();
-    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
+    for (let i = 0; i < this._stronglyConnectedComponents.length; i++) {
       this.sccDag.set(i, /* @__PURE__ */ new Set());
     }
-    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
-      const scc = this.stronglyConnectedComponents[i];
+    for (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 neighbor of Array.from(neighbors)) {
@@ -813,25 +818,27 @@ var CNSNetwork = class {
    */
   buildSCCAncestors() {
     this.sccAncestors.clear();
-    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
+    for (let i = 0; i < this._stronglyConnectedComponents.length; i++) {
       this.sccAncestors.set(i, /* @__PURE__ */ new Set());
     }
+    const n = this._stronglyConnectedComponents.length;
+    const forward = Array.from({ length: n }, () => []);
     const inDegree = /* @__PURE__ */ new Map();
     const queue = [];
-    for (let i = 0; i < this.stronglyConnectedComponents.length; i++) {
-      const incomingEdges = this.sccDag.get(i) || /* @__PURE__ */ new Set();
-      inDegree.set(i, incomingEdges.size);
-      if (incomingEdges.size === 0) {
-        queue.push(i);
+    for (let target = 0; target < n; target++) {
+      const sources = this.sccDag.get(target) || /* @__PURE__ */ new Set();
+      inDegree.set(target, sources.size);
+      if (sources.size === 0) queue.push(target);
+      for (const source of Array.from(sources)) {
+        forward[source].push(target);
       }
     }
     while (queue.length > 0) {
       const current = queue.shift();
-      const outgoingEdges = this.getOutgoingEdges(current);
-      for (const neighbor of Array.from(outgoingEdges)) {
+      const currentAncestors = this.sccAncestors.get(current);
+      for (const neighbor of forward[current]) {
         const neighborAncestors = this.sccAncestors.get(neighbor);
         neighborAncestors.add(current);
-        const currentAncestors = this.sccAncestors.get(current);
         for (const ancestor of Array.from(currentAncestors)) {
           neighborAncestors.add(ancestor);
         }
@@ -843,32 +850,22 @@ var CNSNetwork = class {
       }
     }
   }
-  /**
-   * Get outgoing edges for a given SCC index
-   */
-  getOutgoingEdges(sccIndex) {
-    const outgoing = /* @__PURE__ */ new Set();
-    for (const [targetScc, incomingEdges] of Array.from(this.sccDag)) {
-      if (incomingEdges.has(sccIndex)) {
-        outgoing.add(targetScc);
-      }
-    }
-    return outgoing;
-  }
   /**
    * Check if a neuron can be reached again (including self-calling).
    * Returns true if the neuron is in a strongly connected component with more than one member,
    * or if it's in a single-member SCC that can reach itself.
    */
   getSCCSetByNeuron(neuron2) {
+    this.ensureSCC();
     const sccIndex = this.neuronToSCC.get(neuron2);
     if (sccIndex === void 0) return;
-    return this.stronglyConnectedComponents[sccIndex];
+    return this._stronglyConnectedComponents[sccIndex];
   }
   /**
    * Get the SCC index for a given neuron
    */
   getSccIndexByNeuron(neuron2) {
+    this.ensureSCC();
     return this.neuronToSCC.get(neuron2);
   }
   /**
@@ -876,6 +873,7 @@ var CNSNetwork = class {
    * This is the core logic for safe context cleanup.
    */
   canNeuronBeGuaranteedDone(neuron2, activeSccCounts) {
+    this.ensureSCC();
     const sccIndex = this.neuronToSCC.get(neuron2);
     if (sccIndex === void 0) return true;
     if (activeSccCounts.get(sccIndex) && activeSccCounts.get(sccIndex) > 0) {
@@ -893,8 +891,6 @@ var CNSNetwork = class {
   buildIndexes() {
     this.subIndex.clear();
     this.parentNeuronByCollateral.clear();
-    this.dendriteIndex.clear();
-    this.collateralIndex.clear();
     for (const neuron2 of this.neurons) {
       for (const dendrite of neuron2.dendrites) {
         const key = dendrite.collateral;
@@ -904,25 +900,40 @@ var CNSNetwork = class {
           key,
           arr
         );
-        this.dendriteIndex.set(key, dendrite);
       }
       Object.values(neuron2.axon).forEach((collateral2) => {
         this.parentNeuronByCollateral.set(
           collateral2,
           neuron2
         );
-        this.collateralIndex.add(collateral2);
       });
     }
   }
   getParentNeuronByCollateral(collateral2) {
     return this.parentNeuronByCollateral.get(collateral2);
   }
+  // Computed on demand (rarely used): one dendrite per collateral, last wins —
+  // preserving the previous index semantics without building it every construct.
   getDendrites() {
-    return Array.from(this.dendriteIndex.values());
+    const byCollateral = /* @__PURE__ */ new Map();
+    for (const neuron2 of this.neurons) {
+      for (const dendrite of neuron2.dendrites) {
+        byCollateral.set(
+          dendrite.collateral,
+          dendrite
+        );
+      }
+    }
+    return Array.from(byCollateral.values());
   }
   getCollaterals() {
-    return Array.from(this.collateralIndex.values());
+    const collaterals = /* @__PURE__ */ new Set();
+    for (const neuron2 of this.neurons) {
+      for (const collateral2 of Object.values(neuron2.axon)) {
+        collaterals.add(collateral2);
+      }
+    }
+    return Array.from(collaterals);
   }
   getSubscribers(collateral2) {
     return this.subIndex.get(collateral2) ?? [];
@@ -1196,27 +1207,26 @@ var neuron = (axon) => {
         modality: singleModality,
         modalities: multipleModalities,
         afferentPaths: singleAfferentPaths,
-        default: singleDefaultHandler,
-        default: globalDefaultHandler,
+        default: defaultHandler,
         output
       } = s;
       const modalityConfigs = multipleModalities ? multipleModalities : singleModality ? [
         {
           modality: singleModality,
           afferentPaths: singleAfferentPaths,
-          default: singleDefaultHandler
+          default: defaultHandler
         }
       ] : [];
       const response = (payload, axon2, ctx) => {
         const stimulation = ctx.stimulation;
         const stimOptions = stimulation?.options;
         const runGlobalDefault = () => {
-          if (!globalDefaultHandler) {
+          if (!defaultHandler) {
             throw new Error(
               `modalityDendrite: No handler found for modality and no default handler provided`
             );
           }
-          const res = globalDefaultHandler(payload, axon2, ctx);
+          const res = defaultHandler(payload, axon2, ctx);
           if (res && typeof res.then === "function") {
             return res.then(
               (result) => output(result, axon2, ctx)
@@ -1235,7 +1245,7 @@ var neuron = (axon) => {
         }
         const stimAfferentPath = stimOptions.afferentPath;
         const handler = stimAfferentPath && matchingConfig.afferentPaths ? matchingConfig.afferentPaths.get(stimAfferentPath) : void 0;
-        const effectiveHandler = handler ?? matchingConfig.default ?? globalDefaultHandler;
+        const effectiveHandler = handler ?? matchingConfig.default ?? defaultHandler;
         if (!effectiveHandler) {
           throw new Error(
             `modalityDendrite: No handler found for afferent path in modality and no default handler provided`