@cnstra/core 2.2.1 → 2.4.0

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { ICNS } from './interfaces/ICNS';
 export type { TCNSNeuron } from './types/TCNSNeuron';
 export type { TCNSAxon } from './types/TCNSAxon';
 export type { TCNSDendrite } from './types/TCNSDendrite';
+export type { TCNSHandlerContext } from './types/TCNSHandlerContext';
 export type { TCNSSignal } from './types/TCNSSignal';
 export type { TCNSNeuronActivationTask } from './types/TCNSNeuronActivationTask';
 export type { TCNSStimulationOptions } from './types/TCNSStimulationOptions';
@@ -15,5 +16,6 @@ export type { TCNSAfferentPath } from './types/TCNSAfferentPath';
 export type { TCNSNeuronActivationTaskFailure } from './types/TCNSNeuronActivationTaskFailure';
 export type { TCNSNeuronPersistOptions, TCNSCollateralPersistOptions, TCNSStimulationPersistOptions } from './types/TCNSPersist';
 export type { TCNSStimulationGateOptions, TCNSStimulationGateSignal } from './utils/CNSStimulationGate';
-export { collateral, neuron, withCtx, afferentPath, modality, createPersistRegistry, } from './factory/index';
+export { collateral, neuron, neuronFactory, withCtx, withGlobal, afferentPath, modality, createPersistRegistry, createCNS, } from './factory/index';
+export type { TNeuronFactory } from './factory/index';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,YAAY,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,YAAY,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAC/F,YAAY,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACjI,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAGxG,OAAO,EACH,UAAU,EACV,MAAM,EACN,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,qBAAqB,GACxB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,YAAY,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,YAAY,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAC/F,YAAY,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACjI,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAGxG,OAAO,EACH,UAAU,EACV,MAAM,EACN,aAAa,EACb,OAAO,EACP,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,SAAS,GACZ,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

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;
@@ -30,6 +31,12 @@ var CNSDendriteContext = class {
     this.abortSignal = abortSignal;
     this.cns = cns;
   }
+  // Prototype getter, not a constructor field: the per-activation allocation is
+  // unchanged (still 4 fields) and you only pay a single `cns.global` read on the
+  // dendrites that actually reach for it. Value getter, so `{ global }` destructuring is safe.
+  get global() {
+    return this.cns.global;
+  }
   get() {
     return this.stimulation.getContext().get(this.neuron);
   }
@@ -73,7 +80,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 +345,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 +361,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 +564,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 +679,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 +702,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 +788,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 +802,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 +824,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 +856,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 +879,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 +897,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 +906,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) ?? [];
@@ -931,7 +948,7 @@ var CNSNetwork = class {
 
 // src/CNS.ts
 var CNS = class {
-  constructor(neurons, options) {
+  constructor(neurons, options, global) {
     this.neurons = neurons;
     this.options = options;
     /**
@@ -944,6 +961,7 @@ var CNS = class {
      */
     this.globalResponseListeners = [];
     this.network = new CNSNetwork(this.neurons);
+    this.global = global;
   }
   addResponseListener(listener) {
     this.globalResponseListeners.push(listener);
@@ -1196,27 +1214,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 +1252,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`
@@ -1270,11 +1287,16 @@ var neuron = (axon) => {
   };
   return api;
 };
-var withCtx = () => ({
-  neuron: (axon) => {
-    return neuron(axon);
-  }
-});
+var neuronFactory = () => {
+  const factory = {
+    withCtx: () => factory,
+    withGlobal: () => factory,
+    neuron: (axon) => neuron(axon)
+  };
+  return factory;
+};
+var withCtx = () => neuronFactory();
+var withGlobal = () => neuronFactory();
 var afferentPath = (parentAfferentPath) => {
   return {
     ...parentAfferentPath !== void 0 && {
@@ -1303,7 +1325,15 @@ var createPersistRegistry = (namedNeurons) => {
   }
   return registry;
 };
+var createCNS = (namedNeurons, options) => {
+  const neurons = Object.values(namedNeurons).map(
+    (entry) => entry && typeof entry === "object" && "neuron" in entry ? entry.neuron : entry
+  );
+  const cns = new CNS(neurons, options, options?.global);
+  const registry = createPersistRegistry(namedNeurons);
+  return { cns, registry };
+};
 
-export { CNS, CNSCollateral, CNSPersistOptionsRegistry, CNSStimulationContextStore, CNSStimulationGate, afferentPath, collateral, createPersistRegistry, modality, neuron, withCtx };
+export { CNS, CNSCollateral, CNSPersistOptionsRegistry, CNSStimulationContextStore, CNSStimulationGate, afferentPath, collateral, createCNS, createPersistRegistry, modality, neuron, neuronFactory, withCtx, withGlobal };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map