@cnstra/core 2.3.0 → 2.5.0

package/dist/index.d.ts

@@ -7,13 +7,17 @@ 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';
+export type { TCNSStimulationResponse } from './types/TCNSStimulationResponse';
+export type { TCNSStimulationDrain } from './types/TCNSStimulationDrain';
 export type { TCNSModality } from './types/TCNSModality';
 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,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC/E,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,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

@@ -31,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);
   }
@@ -42,12 +48,14 @@ var CNSDendriteContext = class {
   }
 };
 var CNSStimulationResponseImpl = class {
-  constructor(stimulation, store, inputSignal, outputSignal, queueLength, hops, error) {
+  constructor(stimulation, store, inputSignal, outputSignal, queueLength, pendingActivations, activeActivations, hops, error) {
     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;
   }
@@ -56,7 +64,7 @@ var CNSStimulationResponseImpl = class {
   }
 };
 var CNSStimulation = class {
-  constructor(cns, instanceNeuronQueue, options, onResponse) {
+  constructor(cns, instanceNeuronQueue, options, onResponse, onDrain) {
     this.cns = cns;
     this.options = options;
     this.qHead = 0;
@@ -67,9 +75,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;
@@ -166,18 +185,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;
           }
@@ -193,10 +222,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) {
@@ -268,10 +341,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;
@@ -372,14 +450,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;
@@ -426,13 +509,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;
@@ -502,8 +585,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;
     }
@@ -557,7 +658,9 @@ 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
         )
@@ -575,21 +678,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;
@@ -602,12 +719,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();
   }
 };
 
@@ -942,7 +1068,7 @@ var CNSNetwork = class {
 
 // src/CNS.ts
 var CNS = class {
-  constructor(neurons, options) {
+  constructor(neurons, options, global) {
     this.neurons = neurons;
     this.options = options;
     /**
@@ -954,7 +1080,12 @@ 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;
   }
   addResponseListener(listener) {
     this.globalResponseListeners.push(listener);
@@ -966,6 +1097,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;
@@ -1013,7 +1188,8 @@ var CNS = class {
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped
+      wrapped,
+      this.wrapOnDrain(options?.onDrain)
     );
     stimulation.responseToSignal(signalOrSignals);
     return stimulation;
@@ -1027,7 +1203,8 @@ var CNS = class {
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped
+      wrapped,
+      this.wrapOnDrain(options?.onDrain)
     );
     stimulation.enqueueTasks(tasks);
     return stimulation;
@@ -1280,11 +1457,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 && {
@@ -1313,7 +1495,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