@cnstra/core 1.3.1 → 1.5.2

package/dist/index.cjs

@@ -132,7 +132,7 @@ var CNSFunctionalQueue = class {
 
 // src/CNSStimulation.ts
 var CNSStimulation = class {
-  constructor(cns, options) {
+  constructor(cns, instanceNeuronQueue, options) {
     this.cns = cns;
     this.options = options;
     this.scheduledCount = 0;
@@ -147,6 +147,7 @@ var CNSStimulation = class {
       options?.concurrency,
       options?.abortSignal
     );
+    this.instanceNeuronQueue = instanceNeuronQueue;
     if (this.options?.maxNeuronHops) {
       this.nueronVisitMap = /* @__PURE__ */ new Map();
     }
@@ -175,7 +176,7 @@ var CNSStimulation = class {
    * Increment the active count for the SCC containing this neuron
    */
   incrementSccCount(neuronId) {
-    const sccIndex = this.cns.getSccIndexByNeuronId(neuronId);
+    const sccIndex = this.cns.getSccIndexByNeuronName(neuronId);
     if (sccIndex === void 0) return;
     const currentCount = this.activeSccCounts.get(sccIndex) || 0;
     this.activeSccCounts.set(sccIndex, currentCount + 1);
@@ -184,7 +185,7 @@ var CNSStimulation = class {
    * Decrement the active count for the SCC containing this neuron
    */
   decrementSccCount(neuronId) {
-    const sccIndex = this.cns.getSccIndexByNeuronId(neuronId);
+    const sccIndex = this.cns.getSccIndexByNeuronName(neuronId);
     if (sccIndex === void 0) return;
     const currentCount = this.activeSccCounts.get(sccIndex) || 0;
     const nextCount = Math.max(0, currentCount - 1);
@@ -206,25 +207,25 @@ var CNSStimulation = class {
     );
   }
   cleanupCtxIfNeeded(neuron2) {
-    if (this.autoCleanupContextsEnabled && this.canNeuronBeGuaranteedDone(neuron2.id)) {
-      this.ctx.delete(neuron2.id);
+    if (this.autoCleanupContextsEnabled && this.canNeuronBeGuaranteedDone(neuron2.name)) {
+      this.ctx.delete(neuron2.name);
     }
   }
   createSubscriberQueueItem(subscriber, inputSignal) {
     if (this.options?.maxNeuronHops) {
-      if (this.nueronVisitMap?.get(subscriber.neuron.id) ?? 0 >= this.options?.maxNeuronHops) {
+      if (this.nueronVisitMap?.get(subscriber.neuron.name) ?? 0 >= this.options?.maxNeuronHops) {
         throw new Error(
-          `Max neuron hops reached for neuron "${subscriber.neuron.id}" when trying to enqueue subscriber "${subscriber.dendrite.collateral.id}" in stimulation "${this.id}"`
+          `Max neuron hops reached for neuron "${subscriber.neuron.name}" when trying to enqueue subscriber "${subscriber.dendrite.collateral.name}" in stimulation "${this.id}"`
         );
       } else {
         this.nueronVisitMap?.set(
-          subscriber.neuron.id,
-          (this.nueronVisitMap?.get(subscriber.neuron.id) ?? 0) + 1
+          subscriber.neuron.name,
+          (this.nueronVisitMap?.get(subscriber.neuron.name) ?? 0) + 1
         );
       }
     }
     return {
-      neuronId: subscriber.neuron.id,
+      neuronId: subscriber.neuron.name,
       subscriber,
       inputSignal
     };
@@ -232,52 +233,57 @@ var CNSStimulation = class {
   processQueueItem(item) {
     const { subscriber, inputSignal } = item;
     const { neuron: neuron2, dendrite } = subscriber;
-    this.markNeuronActive(neuron2.id);
-    const response = dendrite.response(
-      inputSignal?.payload,
-      neuron2.axon,
-      {
-        get: () => this.ctx.get(neuron2.id),
-        set: (value) => this.ctx.set(neuron2.id, value)
-      },
-      this.options?.abortSignal
-    );
-    if (response instanceof Promise) {
-      return response.then(
-        (signal) => {
-          return () => {
-            this.markNeuronInactive(neuron2.id);
-            return this.processResponse(
-              inputSignal,
-              signal
-            );
-          };
-        },
-        (error) => {
-          return () => {
-            this.markNeuronInactive(neuron2.id);
-            return this.processResponse(
-              inputSignal,
-              void 0,
-              error
-            );
-          };
+    const starter = () => {
+      this.markNeuronActive(neuron2.name);
+      const response = dendrite.response(
+        inputSignal?.payload,
+        neuron2.axon,
+        {
+          get: () => this.ctx.get(neuron2.name),
+          set: (value) => this.ctx.set(neuron2.name, value),
+          delete: () => this.ctx.delete(neuron2.name),
+          abortSignal: this.options?.abortSignal,
+          cns: this.cns
         }
       );
-    } else {
-      return () => {
-        this.markNeuronInactive(neuron2.id);
-        return this.processResponse(
-          inputSignal,
-          response
+      if (response instanceof Promise) {
+        return response.then(
+          (signal) => {
+            return () => {
+              this.markNeuronInactive(neuron2.name);
+              return this.processResponse(
+                inputSignal,
+                signal
+              );
+            };
+          },
+          (error) => {
+            return () => {
+              this.markNeuronInactive(neuron2.name);
+              return this.processResponse(
+                inputSignal,
+                void 0,
+                error
+              );
+            };
+          }
         );
-      };
-    }
+      } else {
+        return () => {
+          this.markNeuronInactive(neuron2.name);
+          return this.processResponse(
+            inputSignal,
+            response
+          );
+        };
+      }
+    };
+    return this.instanceNeuronQueue.run(neuron2, starter);
   }
   processResponse(inputSignal, outputSignal, error) {
     const collateral2 = outputSignal?.collateral;
-    const ownerNeuron = collateral2 ? this.cns.getParentNeuronByCollateralId(collateral2.id) : void 0;
-    const subscribers = collateral2 ? this.cns.getSubscribers(collateral2.id) : [];
+    const ownerNeuron = collateral2 ? this.cns.getParentNeuronByCollateralName(collateral2.name) : void 0;
+    const subscribers = collateral2 ? this.cns.getSubscribers(collateral2.name) : [];
     const subscriberQueueItems = [];
     if (collateral2 && !error) {
       if (ownerNeuron) {
@@ -295,7 +301,8 @@ var CNSStimulation = class {
       outputSignal,
       ctx: this.ctx,
       queueLength: this.queue.length + this.scheduledCount,
-      hops: this.options?.maxNeuronHops && ownerNeuron ? this.nueronVisitMap?.get(ownerNeuron.id) ?? 0 : void 0,
+      stimulationId: this.id,
+      hops: this.options?.maxNeuronHops && ownerNeuron ? this.nueronVisitMap?.get(ownerNeuron.name) ?? 0 : void 0,
       error
     });
     for (let i = 0; i < subscriberQueueItems.length; i++) {
@@ -304,27 +311,167 @@ var CNSStimulation = class {
     }
   }
   responseToSignal(signal) {
-    const ownerNeuron = this.cns.getParentNeuronByCollateralId(
-      signal.collateral.id
+    const ownerNeuron = this.cns.getParentNeuronByCollateralName(
+      signal.collateral.name
     );
     if (ownerNeuron) {
-      this.markNeuronActive(ownerNeuron.id);
+      this.markNeuronActive(ownerNeuron.name);
     }
     this.processResponse(void 0, signal);
   }
 };
 
+// src/CNSTaskQueue.ts
+var CNSTaskQueue = class {
+  constructor(concurrency) {
+    this.concurrency = concurrency;
+    this.pumping = false;
+    this.needsPump = false;
+    this.activeOperations = 0;
+    this.items = [];
+  }
+  get canStartOperation() {
+    const limit = this.concurrency ?? Infinity;
+    return this.activeOperations < limit;
+  }
+  enqueue(task) {
+    return new Promise((resolve, reject) => {
+      this.items.push({ task, resolve, reject });
+      if (!this.pumping) this.pump();
+      else this.needsPump = true;
+    });
+  }
+  pump() {
+    if (this.pumping) {
+      this.needsPump = true;
+      return;
+    }
+    this.pumping = true;
+    while (this.canStartOperation && this.items.length > 0) {
+      const { task, resolve, reject } = this.items.shift();
+      this.activeOperations++;
+      try {
+        const ret = task();
+        if (ret && typeof ret.then === "function") {
+          ret.then(
+            (cb) => {
+              try {
+                if (typeof cb === "function") cb();
+                resolve();
+              } finally {
+                this.activeOperations--;
+                if (this.items.length > 0 && this.canStartOperation) {
+                  if (this.pumping) this.needsPump = true;
+                  else this.pump();
+                }
+              }
+            },
+            (err) => {
+              try {
+                reject(err);
+              } finally {
+                this.activeOperations--;
+                if (this.items.length > 0 && this.canStartOperation) {
+                  if (this.pumping) this.needsPump = true;
+                  else this.pump();
+                }
+              }
+            }
+          );
+          break;
+        } else {
+          try {
+            if (typeof ret === "function") ret();
+            resolve();
+          } finally {
+            this.activeOperations--;
+          }
+        }
+      } catch (e) {
+        try {
+          reject(e);
+        } finally {
+          this.activeOperations--;
+        }
+      }
+    }
+    this.pumping = false;
+    if (this.needsPump) {
+      this.needsPump = false;
+      this.pump();
+    }
+  }
+};
+
+// src/CNSInstanceNeuronQueue.ts
+var CNSInstanceNeuronQueue = class {
+  constructor() {
+    this.gates = /* @__PURE__ */ new Map();
+  }
+  run(neuron2, fn) {
+    const limit = neuron2?.concurrency;
+    if (limit === void 0 || limit <= 0) {
+      return fn();
+    }
+    let gate = this.gates.get(neuron2.name);
+    if (!gate) {
+      gate = { limit, active: 0, waiters: [] };
+      this.gates.set(neuron2.name, gate);
+    } else {
+      gate.limit = limit;
+    }
+    const wrap = (cb) => {
+      return () => {
+        try {
+          cb();
+        } finally {
+          const g = this.gates.get(neuron2.name);
+          g.active = Math.max(0, g.active - 1);
+          if (g.waiters.length > 0) {
+            const next = g.waiters.shift();
+            next();
+          }
+        }
+      };
+    };
+    if (gate.active < gate.limit) {
+      gate.active++;
+      const ret = fn();
+      if (ret && typeof ret.then === "function") {
+        return ret.then((cb) => wrap(cb));
+      }
+      return wrap(ret);
+    }
+    return new Promise((resolve) => {
+      const starter = () => {
+        const g = this.gates.get(neuron2.name);
+        g.active++;
+        const ret = fn();
+        if (ret && typeof ret.then === "function") {
+          ret.then((cb) => resolve(wrap(cb)));
+        } else {
+          resolve(wrap(ret));
+        }
+      };
+      gate.waiters.push(starter);
+    });
+  }
+};
+
 // src/CNS.ts
 var CNS = class {
   constructor(neurons, options) {
     this.neurons = neurons;
     this.options = options;
     /**
-     * Fast lookup: collateralId -> list of (neuron, dendrite) subscribers.
+     * Fast lookup: collateralName -> list of (neuron, dendrite) subscribers.
      * Built once at construction time.
      */
     this.subIndex = /* @__PURE__ */ new Map();
-    this.parentNeuronByCollateralId = /* @__PURE__ */ new Map();
+    this.neuronIndex = /* @__PURE__ */ new Map();
+    this.dendriteIndex = /* @__PURE__ */ new Map();
+    this.collateralIndex = /* @__PURE__ */ new Map();
+    this.parentNeuronByCollateralName = /* @__PURE__ */ new Map();
     /**
      * Strongly Connected Components of the neuron graph.
      * Each component is a set of neuron IDs that can reach each other.
@@ -342,29 +489,157 @@ var CNS = class {
      * Precomputed ancestor sets for each SCC for fast reachability checks
      */
     this.sccAncestors = /* @__PURE__ */ new Map();
+    /**
+     * Global per-neuron concurrency gates shared across all stimulations.
+     */
+    this.neuronGates = /* @__PURE__ */ new Map();
+    /**
+     * Global task queue used by stimulation to schedule per-neuron gated work.
+     * Does not replace per-stimulation concurrency; only coordinates global per-neuron limits.
+     */
+    this.globalTaskQueue = new CNSTaskQueue();
+    this.instanceNeuronQueue = new CNSInstanceNeuronQueue();
+    /**
+     * Global response listeners applied to every stimulation.
+     */
+    this.globalResponseListeners = [];
+    this.validateUniqueIdentifiers();
     this.buildIndexes();
     if (this.options?.autoCleanupContexts) {
       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
+   * 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(`
+ - `)
+      );
+    }
+  }
+  addResponseListener(listener) {
+    this.globalResponseListeners.push(listener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const idx = this.globalResponseListeners.indexOf(listener);
+      if (idx >= 0) this.globalResponseListeners.splice(idx, 1);
+    };
+  }
+  wrapOnResponse(local) {
+    if (this.globalResponseListeners.length === 0 && !local) {
+      return () => {
+      };
+    }
+    return (r) => {
+      try {
+        if (local) local(r);
+      } finally {
+        for (let i = 0; i < this.globalResponseListeners.length; i++) {
+          try {
+            this.globalResponseListeners[i](r);
+          } catch (e) {
+          }
+        }
+      }
+    };
+  }
+  runWithNeuronConcurrency(neuron2, fn) {
+    const limit = neuron2.concurrency;
+    if (limit === void 0 || limit <= 0) {
+      return this.globalTaskQueue.enqueue(fn);
+    }
+    let gate = this.neuronGates.get(neuron2.name);
+    if (!gate) {
+      gate = { limit, active: 0, waiters: [] };
+      this.neuronGates.set(neuron2.name, gate);
+    } else {
+      gate.limit = limit;
+    }
+    const wrap = (cb) => {
+      return () => {
+        try {
+          cb();
+        } finally {
+          gate.active = Math.max(0, gate.active - 1);
+          if (gate.waiters.length > 0) {
+            const next = gate.waiters.shift();
+            next();
+          }
+        }
+      };
+    };
+    if (gate.active < gate.limit) {
+      gate.active++;
+      return this.globalTaskQueue.enqueue(() => {
+        const ret = fn();
+        if (ret && typeof ret.then === "function") {
+          return ret.then((cb) => wrap(cb));
+        }
+        return wrap(ret);
+      });
+    }
+    return new Promise((resolve) => {
+      const starter = () => {
+        gate.active++;
+        this.globalTaskQueue.enqueue(() => {
+          const ret = fn();
+          if (ret && typeof ret.then === "function") {
+            return ret.then(
+              (cb) => wrap(cb)
+            );
+          }
+          return wrap(ret);
+        }).then(resolve);
+      };
+      gate.waiters.push(starter);
+    });
+  }
   buildIndexes() {
     this.subIndex.clear();
-    this.parentNeuronByCollateralId.clear();
+    this.parentNeuronByCollateralName.clear();
     for (const neuron2 of this.neurons) {
+      this.neuronIndex.set(neuron2.name, neuron2);
       for (const dendrite of neuron2.dendrites) {
-        const key = dendrite.collateral.id;
+        const key = dendrite.collateral.name;
         const arr = this.subIndex.get(key) ?? [];
         arr.push({ neuron: neuron2, dendrite });
         this.subIndex.set(
           key,
           arr
         );
+        this.dendriteIndex.set(key, dendrite);
       }
       Object.values(neuron2.axon).forEach((collateral2) => {
-        this.parentNeuronByCollateralId.set(
-          collateral2.id,
+        this.parentNeuronByCollateralName.set(
+          collateral2.name,
           neuron2
         );
+        this.collateralIndex.set(
+          collateral2.name,
+          collateral2
+        );
       });
     }
   }
@@ -373,7 +648,7 @@ var CNS = class {
    */
   buildNeuronGraph() {
     const graph = /* @__PURE__ */ new Map();
-    const neuronIds = this.neurons.map((n) => n.id);
+    const neuronIds = this.neurons.map((n) => n.name);
     for (const neuronId of neuronIds) {
       graph.set(neuronId, /* @__PURE__ */ new Set());
     }
@@ -381,15 +656,15 @@ var CNS = class {
       const reachableNeurons = /* @__PURE__ */ new Set();
       for (const axonKey in neuron2.axon) {
         const collateral2 = neuron2.axon[axonKey];
-        const collateralId = collateral2.id;
-        const subscribers = this.subIndex.get(collateralId);
+        const collateralName = collateral2.name;
+        const subscribers = this.subIndex.get(collateralName);
         if (subscribers) {
           for (const { neuron: targetNeuron } of subscribers) {
-            reachableNeurons.add(targetNeuron.id);
+            reachableNeurons.add(targetNeuron.name);
           }
         }
       }
-      graph.set(neuron2.id, reachableNeurons);
+      graph.set(neuron2.name, reachableNeurons);
     }
     return graph;
   }
@@ -398,7 +673,7 @@ var CNS = class {
    */
   buildSCC() {
     const graph = this.buildNeuronGraph();
-    const neuronIds = this.neurons.map((n) => n.id);
+    const neuronIds = this.neurons.map((n) => n.name);
     const index = /* @__PURE__ */ new Map();
     const lowlink = /* @__PURE__ */ new Map();
     const onStack = /* @__PURE__ */ new Set();
@@ -525,23 +800,23 @@ var CNS = 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.
    */
-  getSCCSetByNeuronId(neuronId) {
-    const sccIndex = this.neuronToSCC.get(neuronId);
+  getSCCSetByNeuronName(neuronName) {
+    const sccIndex = this.neuronToSCC.get(neuronName);
     if (sccIndex === void 0) return;
     return this.stronglyConnectedComponents[sccIndex];
   }
   /**
    * Get the SCC index for a given neuron ID
    */
-  getSccIndexByNeuronId(neuronId) {
-    return this.neuronToSCC.get(neuronId);
+  getSccIndexByNeuronName(neuronName) {
+    return this.neuronToSCC.get(neuronName);
   }
   /**
    * 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(neuronId, activeSccCounts) {
-    const sccIndex = this.neuronToSCC.get(neuronId);
+  canNeuronBeGuaranteedDone(neuronName, activeSccCounts) {
+    const sccIndex = this.neuronToSCC.get(neuronName);
     if (sccIndex === void 0) return true;
     if (activeSccCounts.get(sccIndex) && activeSccCounts.get(sccIndex) > 0) {
       return false;
@@ -555,22 +830,35 @@ var CNS = class {
     }
     return true;
   }
-  getParentNeuronByCollateralId(collateralId) {
-    return this.parentNeuronByCollateralId.get(collateralId);
+  getParentNeuronByCollateralName(collateralName) {
+    return this.parentNeuronByCollateralName.get(collateralName);
+  }
+  getDendrites() {
+    return Array.from(this.dendriteIndex.values());
   }
-  getSubscribers(collateralId) {
-    return this.subIndex.get(collateralId) ?? [];
+  getCollaterals() {
+    return Array.from(this.collateralIndex.values());
+  }
+  getNeurons() {
+    return Array.from(this.neuronIndex.values());
+  }
+  getSubscribers(collateralName) {
+    return this.subIndex.get(collateralName) ?? [];
   }
   stimulate(signal, options) {
-    const stimulation = new CNSStimulation(this, options);
+    const wrapped = this.wrapOnResponse(options?.onResponse);
+    const stimulation = new CNSStimulation(this, this.instanceNeuronQueue, {
+      ...options,
+      onResponse: wrapped
+    });
     stimulation.responseToSignal(signal);
   }
 };
 
 // src/CNSCollateral.ts
 var CNSCollateral = class {
-  constructor(id) {
-    this.id = id;
+  constructor(name) {
+    this.name = name;
   }
   createSignal(payload) {
     return { collateral: this, payload };
@@ -578,12 +866,30 @@ var CNSCollateral = class {
 };
 
 // src/factory/index.ts
-var collateral = (id) => new CNSCollateral(id);
-var neuron = (id, axon) => {
+var collateral = (name) => new CNSCollateral(name);
+var neuron = (name, axon) => {
   const dendrites = [];
   const api = {
+    setConcurrency: (n) => {
+      api.concurrency = n;
+      return api;
+    },
+    bind: ((axon2, newDendrites) => {
+      for (const key in newDendrites) {
+        const value = newDendrites[key];
+        const dendrite = typeof value === "function" ? {
+          collateral: axon2[key],
+          response: value
+        } : value;
+        dendrites.push(
+          dendrite
+        );
+      }
+      return api;
+    }),
     axon,
-    id,
+    name,
+    concurrency: void 0,
     dendrites,
     dendrite(s) {
       dendrites.push(
@@ -595,13 +901,14 @@ var neuron = (id, axon) => {
   return api;
 };
 var withCtx = () => ({
-  neuron: (id, axon) => {
-    return neuron(id, axon);
+  neuron: (name, axon) => {
+    return neuron(name, axon);
   }
 });
 
 exports.CNS = CNS;
 exports.CNSCollateral = CNSCollateral;
+exports.CNSStimulationContextStore = CNSStimulationContextStore;
 exports.collateral = collateral;
 exports.neuron = neuron;
 exports.withCtx = withCtx;