@cnstra/core 2.4.0 → 2.6.0

package/dist/index.cjs

@@ -39,6 +39,13 @@ var CNSDendriteContext = class {
   get global() {
     return this.cns.global;
   }
+  // The caller-supplied per-stimulation context (`stimulate(sig, {stimulationContext})`),
+  // the same value on every hop — the environment-agnostic way to correlate logs to a
+  // run (pass `{ stimulationId, attemptNumber }`). Prototype getter like `global`:
+  // zero extra allocation, read only where a handler reaches for it.
+  get stimulationContext() {
+    return this.stimulation.options?.stimulationContext;
+  }
   get() {
     return this.stimulation.getContext().get(this.neuron);
   }
@@ -50,21 +57,24 @@ var CNSDendriteContext = class {
   }
 };
 var CNSStimulationResponseImpl = class {
-  constructor(stimulation, store, inputSignal, outputSignal, queueLength, hops, error) {
+  constructor(stimulation, store, inputSignal, outputSignal, queueLength, pendingActivations, activeActivations, hops, error, neuron2) {
     this.stimulation = stimulation;
     this.store = store;
     this.inputSignal = inputSignal;
     this.outputSignal = outputSignal;
     this.queueLength = queueLength;
+    this.pendingActivations = pendingActivations;
+    this.activeActivations = activeActivations;
     this.hops = hops;
     this.error = error;
+    this.neuron = neuron2;
   }
   get contextValue() {
     return this.store ? this.store.getAll() : /* @__PURE__ */ new Map();
   }
 };
 var CNSStimulation = class {
-  constructor(cns, instanceNeuronQueue, options, onResponse) {
+  constructor(cns, instanceNeuronQueue, options, onResponse, onDrain) {
     this.cns = cns;
     this.options = options;
     this.qHead = 0;
@@ -75,9 +85,20 @@ var CNSStimulation = class {
     // Re-entrancy guard for the pump loop.
     this.pumping = false;
     this.needsPump = false;
+    // Nesting depth of the current synchronous turn. Only the outermost close
+    // announces a drain - see beginTurn/endTurn.
+    this.turnDepth = 0;
     this.scheduledCount = 0;
+    // Activations belonging to signals of an in-progress array fan-out that have
+    // not been handed to processResponse yet, so the task objects do not exist.
+    // processResponse enqueues synchronously, so the first signal's whole subtree
+    // drains before the second signal is even looked at; without this counter
+    // that subtree's leaf sees an empty queue and reads as "all work done".
+    // Counted in activations, not signals, so every public counter shares a unit.
+    this.reservedActivations = 0;
     this.isCompleted = false;
     this.completionRejected = false;
+    this.onDrain = onDrain;
     this.ctxStore = options?.ctx;
     this.instanceNeuronQueue = instanceNeuronQueue;
     this.onResponse = onResponse;
@@ -174,18 +195,28 @@ var CNSStimulation = class {
           (cb) => {
             this.activeOperations--;
             this.activeTasks.delete(task);
-            if (typeof cb === "function") cb();
-            if (this.qSize > 0 && this.canStartOperation) {
-              if (this.pumping) this.needsPump = true;
-              else this.pump();
+            this.beginTurn();
+            try {
+              if (typeof cb === "function") cb();
+              if (this.qSize > 0 && this.canStartOperation) {
+                if (this.pumping) this.needsPump = true;
+                else this.pump();
+              }
+            } finally {
+              this.endTurn();
             }
           },
           (err) => {
             this.activeOperations--;
             this.activeTasks.delete(task);
-            if (this.qSize > 0 && this.canStartOperation) {
-              if (this.pumping) this.needsPump = true;
-              else this.pump();
+            this.beginTurn();
+            try {
+              if (this.qSize > 0 && this.canStartOperation) {
+                if (this.pumping) this.needsPump = true;
+                else this.pump();
+              }
+            } finally {
+              this.endTurn();
             }
             throw err;
           }
@@ -201,10 +232,54 @@ var CNSStimulation = class {
       this.pump();
     }
   }
+  /**
+   * Open a synchronous turn. Turns nest: a drain is announced only when the
+   * outermost one closes, so an enqueue that happens while the pump is already
+   * running does not produce its own boundary.
+   */
+  beginTurn() {
+    this.turnDepth++;
+  }
+  /**
+   * Close a synchronous turn and, if it was the outermost and nothing more can
+   * run without yielding to the event loop, announce the drain.
+   *
+   * This is the only place the synchronous frontier is observable. A response
+   * cannot serve the purpose: responses are emitted when an activation
+   * *finishes*, but a turn just as often ends when one *starts* and returns a
+   * promise - at which point there is nothing left to emit a response from.
+   */
+  endTurn() {
+    if (--this.turnDepth > 0) return;
+    const onDrain = this.onDrain;
+    if (!onDrain) return;
+    if (this.pumping) return;
+    if (this.qSize > 0 && this.canStartOperation) return;
+    this.turnDepth++;
+    try {
+      onDrain({
+        stimulation: this,
+        queueLength: this.pendingActivations + this.activeOperations,
+        pendingActivations: this.pendingActivations,
+        activeActivations: this.activeOperations
+      });
+    } finally {
+      this.turnDepth--;
+    }
+  }
+  /**
+   * Activations that exist (or are reserved) but whose dendrite body 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;
+  }
   tryResolveCompleted() {
     if (this.isCompleted) return;
     const noActive = this.activeOperations === 0;
-    const noPending = this.qSize + this.scheduledCount === 0;
+    const noPending = this.pendingActivations === 0;
     const aborted = !!this.options?.abortSignal?.aborted;
     if (noPending && noActive || aborted && noActive && !noPending) {
       if (aborted) {
@@ -266,6 +341,19 @@ var CNSStimulation = class {
   getFailedTasks() {
     return this.failedTasks ? [...this.failedTasks] : [];
   }
+  /**
+   * The current outstanding frontier — every task that has not completed:
+   * queued, active, and pending (awaiting an async onResponse), plus any
+   * 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.
+   */
+  getOutstandingTasks() {
+    return [
+      ...this.getAllActivationTasks(),
+      ...this.getFailedTasks().map((f) => f.task)
+    ];
+  }
   /**
    * Get the context store for this stimulation
    */
@@ -276,10 +364,15 @@ var CNSStimulation = class {
    * Enqueue activation tasks directly into the stimulation queue
    */
   enqueueTasks(tasks) {
-    for (const task of tasks) {
-      this.qEnqueue(task);
+    this.beginTurn();
+    try {
+      for (const task of tasks) {
+        this.qEnqueue(task);
+      }
+      this.tryResolveCompleted();
+    } finally {
+      this.endTurn();
     }
-    this.tryResolveCompleted();
   }
   get concurrencyEnabled() {
     return this.options?.concurrency !== void 0 && this.options?.concurrency > 0;
@@ -380,14 +473,19 @@ var CNSStimulation = class {
       }
     }
     if (!subscriber) {
+      const error = new Error(`Subscriber not found for activation task`);
       this.pushFailedTask({
         task: neuronActivationTask,
-        error: new Error(
-          `Subscriber not found for activation task`
-        ),
+        error,
         aborted: false
       });
       return () => {
+        this.processResponseOrResponses(
+          void 0,
+          neuronActivationTask.input,
+          void 0,
+          error
+        );
       };
     }
     const neuron2 = subscriber.neuron;
@@ -434,13 +532,13 @@ var CNSStimulation = class {
         error: error instanceof Error ? error : new Error(String(error)),
         aborted: isAborted
       });
-      this.processResponseOrResponses(
-        neuron2,
-        inputSignal,
-        void 0,
-        error
-      );
       return () => {
+        this.processResponseOrResponses(
+          neuron2,
+          inputSignal,
+          void 0,
+          error
+        );
       };
     }
     const maxDuration = neuron2.maxDuration;
@@ -510,8 +608,26 @@ var CNSStimulation = class {
         this.processResponse(emitter, inputSignal, void 0, error);
         return;
       }
-      for (const signal of outputSignalOrSignals) {
-        this.processResponse(emitter, inputSignal, signal, error);
+      let perSignal;
+      if (!error) {
+        perSignal = new Array(outputSignalOrSignals.length);
+        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;
+          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
+        );
       }
       return;
     }
@@ -565,9 +681,12 @@ var CNSStimulation = class {
           this.ctxStore,
           inputSignal,
           outputSignal,
-          this.qSize + this.scheduledCount,
+          this.pendingActivations + this.activeOperations,
+          this.pendingActivations,
+          this.activeOperations,
           this.options?.maxNeuronHops && emitter ? this.neuronVisitMap?.get(emitter) ?? 0 : void 0,
-          error
+          error,
+          emitter
         )
       );
     } catch (e) {
@@ -583,21 +702,35 @@ var CNSStimulation = class {
     if (maybePromise && typeof maybePromise.then === "function") {
       maybePromise.then(
         () => {
-          for (let i = 0; i < subscriberActivationTasks.length; i++) {
-            this.scheduledCount--;
-            this.pendingTasks?.delete(subscriberActivationTasks[i]);
-            this.qEnqueue(subscriberActivationTasks[i]);
+          this.beginTurn();
+          try {
+            for (let i = 0; i < subscriberActivationTasks.length; i++) {
+              this.scheduledCount--;
+              this.pendingTasks?.delete(
+                subscriberActivationTasks[i]
+              );
+              this.qEnqueue(subscriberActivationTasks[i]);
+            }
+            this.tryResolveCompleted();
+          } finally {
+            this.endTurn();
           }
-          this.tryResolveCompleted();
         },
         (error2) => {
           this.onResponseError = error2 instanceof Error ? error2 : new Error(String(error2));
-          for (let i = 0; i < subscriberActivationTasks.length; i++) {
-            this.scheduledCount--;
-            this.pendingTasks?.delete(subscriberActivationTasks[i]);
-            this.qEnqueue(subscriberActivationTasks[i]);
+          this.beginTurn();
+          try {
+            for (let i = 0; i < subscriberActivationTasks.length; i++) {
+              this.scheduledCount--;
+              this.pendingTasks?.delete(
+                subscriberActivationTasks[i]
+              );
+              this.qEnqueue(subscriberActivationTasks[i]);
+            }
+            this.tryResolveCompleted();
+          } finally {
+            this.endTurn();
           }
-          this.tryResolveCompleted();
         }
       );
       return;
@@ -610,12 +743,21 @@ var CNSStimulation = class {
     this.tryResolveCompleted();
   }
   responseToSignal(signalOrSignals) {
-    if (Array.isArray(signalOrSignals)) {
-      this.processResponseOrResponses(void 0, void 0, signalOrSignals);
-      return;
+    this.beginTurn();
+    try {
+      if (Array.isArray(signalOrSignals)) {
+        this.processResponseOrResponses(
+          void 0,
+          void 0,
+          signalOrSignals
+        );
+        return;
+      }
+      this.processResponse(void 0, void 0, signalOrSignals);
+      this.tryResolveCompleted();
+    } finally {
+      this.endTurn();
     }
-    this.processResponse(void 0, void 0, signalOrSignals);
-    this.tryResolveCompleted();
   }
 };
 
@@ -962,6 +1104,10 @@ var CNS = class {
      * Global response listeners applied to every stimulation.
      */
     this.globalResponseListeners = [];
+    /**
+     * Global batch-boundary listeners applied to every stimulation.
+     */
+    this.globalDrainListeners = [];
     this.network = new CNSNetwork(this.neurons);
     this.global = global;
   }
@@ -975,6 +1121,50 @@ var CNS = class {
       if (idx >= 0) this.globalResponseListeners.splice(idx, 1);
     };
   }
+  /**
+   * Register a listener called once at the end of every synchronous turn of
+   * every stimulation - 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.
+   *
+   * Returns an unsubscribe function.
+   */
+  addDrainListener(listener) {
+    this.globalDrainListeners.push(listener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const idx = this.globalDrainListeners.indexOf(listener);
+      if (idx >= 0) this.globalDrainListeners.splice(idx, 1);
+    };
+  }
+  /**
+   * 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.
+   *
+   * Listener errors are isolated: a drain is a notification, and one broken
+   * flush must not stop the others or derail the stimulation that triggered it.
+   */
+  wrapOnDrain(local) {
+    if (this.globalDrainListeners.length === 0 && !local) return void 0;
+    return (d) => {
+      if (local) {
+        try {
+          local(d);
+        } catch (error) {
+          console.error("[CNS] onDrain listener threw", error);
+        }
+      }
+      for (let i = 0; i < this.globalDrainListeners.length; i++) {
+        try {
+          this.globalDrainListeners[i](d);
+        } catch (error) {
+          console.error("[CNS] drain listener threw", error);
+        }
+      }
+    };
+  }
   wrapOnResponse(local) {
     if (this.globalResponseListeners.length === 0 && !local) {
       return void 0;
@@ -1022,7 +1212,8 @@ var CNS = class {
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped
+      wrapped,
+      this.wrapOnDrain(options?.onDrain)
     );
     stimulation.responseToSignal(signalOrSignals);
     return stimulation;
@@ -1036,79 +1227,14 @@ var CNS = class {
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped
+      wrapped,
+      this.wrapOnDrain(options?.onDrain)
     );
     stimulation.enqueueTasks(tasks);
     return stimulation;
   }
 };
 
-// src/CNSPersistOptionsRegistry.ts
-var CNSPersistOptionsRegistry = class {
-  constructor() {
-    this.neurons = /* @__PURE__ */ new Map();
-    this.neuronNames = /* @__PURE__ */ new WeakMap();
-    this.collaterals = /* @__PURE__ */ new Map();
-    this.stimulations = /* @__PURE__ */ new Map();
-  }
-  addNeuron(neuron2, options) {
-    this.neurons.set(options.name, neuron2);
-    this.neuronNames.set(neuron2, options.name);
-  }
-  getNeuron(name) {
-    return this.neurons.get(name);
-  }
-  getNeuronName(neuron2) {
-    return this.neuronNames.get(neuron2);
-  }
-  getNamedNeurons() {
-    return this.neurons;
-  }
-  getCollateralName(collateral2) {
-    for (const [name, col] of this.collaterals) {
-      if (col === collateral2) return name;
-    }
-    return void 0;
-  }
-  removeNeuron(name) {
-    const neuron2 = this.neurons.get(name);
-    if (neuron2) this.neuronNames.delete(neuron2);
-    this.neurons.delete(name);
-  }
-  addCollateral(collateral2, options) {
-    this.collaterals.set(options.name, collateral2);
-  }
-  getCollateral(name) {
-    return this.collaterals.get(name);
-  }
-  removeCollateral(name) {
-    this.collaterals.delete(name);
-  }
-  addStimulation(stimulation, options) {
-    this.stimulations.set(options.stimulationId, stimulation);
-  }
-  getStimulation(stimulationId) {
-    return this.stimulations.get(stimulationId);
-  }
-  removeStimulation(stimulationId) {
-    this.stimulations.delete(stimulationId);
-  }
-  register(name, neuron2, collateralNames) {
-    this.addNeuron(neuron2, { name, neuron: neuron2 });
-    for (const [key, col] of Object.entries(neuron2.axon)) {
-      this.addCollateral(col, {
-        name: collateralNames?.[key] ?? key,
-        collateral: col
-      });
-    }
-    return this;
-  }
-  registerCollateral(name, collateral2) {
-    this.addCollateral(collateral2, { name, collateral: collateral2 });
-    return this;
-  }
-};
-
 // src/CNSCollateral.ts
 var CNSCollateral = class {
   createSignal(payload) {
@@ -1311,40 +1437,13 @@ var modality = (afferentPaths) => {
     afferentPaths
   };
 };
-var createPersistRegistry = (namedNeurons) => {
-  const registry = new CNSPersistOptionsRegistry();
-  for (const [name, entry] of Object.entries(namedNeurons)) {
-    const isEntry = "neuron" in entry && !("axon" in entry);
-    const neuron2 = isEntry ? entry.neuron : entry;
-    const colNames = isEntry ? entry.collaterals ?? {} : {};
-    registry.addNeuron(neuron2, { name, neuron: neuron2 });
-    for (const [key, col] of Object.entries(neuron2.axon)) {
-      registry.addCollateral(col, {
-        name: colNames[key] ?? key,
-        collateral: col
-      });
-    }
-  }
-  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 };
-};
 
 exports.CNS = CNS;
 exports.CNSCollateral = CNSCollateral;
-exports.CNSPersistOptionsRegistry = CNSPersistOptionsRegistry;
 exports.CNSStimulationContextStore = CNSStimulationContextStore;
 exports.CNSStimulationGate = CNSStimulationGate;
 exports.afferentPath = afferentPath;
 exports.collateral = collateral;
-exports.createCNS = createCNS;
-exports.createPersistRegistry = createPersistRegistry;
 exports.modality = modality;
 exports.neuron = neuron;
 exports.neuronFactory = neuronFactory;