@cnstra/core 2.4.0 → 2.5.0

package/dist/CNS.d.ts

@@ -6,6 +6,7 @@ import { CNSStimulation } from './CNSStimulation';
 import { TCNSSignal } from './types/TCNSSignal';
 import { CNSInstanceNeuronQueue } from './CNSInstanceNeuronQueue';
 import { TCNSStimulationResponse } from './types/TCNSStimulationResponse';
+import { TCNSStimulationDrain } from './types/TCNSStimulationDrain';
 import { TCNSNeuronActivationTask } from './types/TCNSNeuronActivationTask';
 import { CNSNetwork } from './CNSNetwork';
 import { ICNS } from './interfaces/ICNS';
@@ -26,6 +27,10 @@ export declare class CNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends
      * Global response listeners applied to every stimulation.
      */
     private readonly globalResponseListeners;
+    /**
+     * Global batch-boundary listeners applied to every stimulation.
+     */
+    private readonly globalDrainListeners;
     /**
      * Shared, app/organism-wide value handed to every dendrite as `ctx.global`.
      * Stored untyped (the type is baked into neurons via `neuronFactory().withGlobal<T>()`);
@@ -34,6 +39,23 @@ export declare class CNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends
     readonly global?: unknown;
     constructor(neurons: TNeuron[], options?: TCNSOptions | undefined, global?: unknown);
     addResponseListener(listener: (response: TCNSStimulationResponse) => void | Promise<void>): () => void;
+    /**
+     * 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: (drain: TCNSStimulationDrain) => void): () => void;
+    /**
+     * 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.
+     */
+    private wrapOnDrain;
     private wrapOnResponse;
     stimulate(signalOrSignals: TCNSSignal<CNSCollateral<unknown>> | TCNSSignal<CNSCollateral<unknown>>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): CNSStimulation<TNeuron, TDendrite>;
     /**

package/dist/CNS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CNS.d.ts","sourceRoot":"","sources":["../src/CNS.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,qBAAa,GAAG,CACZ,OAAO,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,SAAS,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAC7E,YAAW,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;IA6B7B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE;aACrB,OAAO,CAAC,EAAE,WAAW;IA5BzC;;OAEG;IACH,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAExD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,kCACI;IAE1C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAEjC;IAEP;;;;OAIG;IACH,SAAgB,MAAM,CAAC,EAAE,OAAO,CAAC;gBAGV,OAAO,EAAE,OAAO,EAAE,EACrB,OAAO,CAAC,EAAE,WAAW,YAAA,EACrC,MAAM,CAAC,EAAE,OAAO;IAMb,mBAAmB,CACtB,QAAQ,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACtE,MAAM,IAAI;IAWb,OAAO,CAAC,cAAc;IAmDf,SAAS,CACZ,eAAe,EACT,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,GAClC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,EAAE,EAC1C,OAAO,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,GAC1D,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC;IAYrC;;OAEG;IACI,QAAQ,CACX,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,EAAE,EAC1C,OAAO,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,GAC1D,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC;CAWxC"}
+{"version":3,"file":"CNS.d.ts","sourceRoot":"","sources":["../src/CNS.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,qBAAa,GAAG,CACZ,OAAO,SAAS,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EACpC,SAAS,SAAS,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAC7E,YAAW,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;IAoC7B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE;aACrB,OAAO,CAAC,EAAE,WAAW;IAnCzC;;OAEG;IACH,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAExD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,kCACI;IAE1C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAEjC;IAEP;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAE9B;IAEP;;;;OAIG;IACH,SAAgB,MAAM,CAAC,EAAE,OAAO,CAAC;gBAGV,OAAO,EAAE,OAAO,EAAE,EACrB,OAAO,CAAC,EAAE,WAAW,YAAA,EACrC,MAAM,CAAC,EAAE,OAAO;IAMb,mBAAmB,CACtB,QAAQ,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACtE,MAAM,IAAI;IAWb;;;;;;;OAOG;IACI,gBAAgB,CACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAChD,MAAM,IAAI;IAWb;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,cAAc;IAmDf,SAAS,CACZ,eAAe,EACT,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,GAClC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,EAAE,EAC1C,OAAO,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,GAC1D,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC;IAarC;;OAEG;IACI,QAAQ,CACX,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,EAAE,EAC1C,OAAO,CAAC,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,GAC1D,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC;CAYxC"}

package/dist/CNSStimulation.d.ts

@@ -9,6 +9,7 @@ import { TCNSNeuronActivationTask } from './types/TCNSNeuronActivationTask';
 import { CNS } from './CNS';
 import { TCNSNeuronActivationTaskFailure } from './types/TCNSNeuronActivationTaskFailure';
 import { TCNSStimulationResponse } from './types/TCNSStimulationResponse';
+import { TCNSStimulationDrain } from './types/TCNSStimulationDrain';
 import { CNSCollateral } from './CNSCollateral';
 export declare class CNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
     readonly cns: CNS<TNeuron, TDendrite>;
@@ -23,9 +24,11 @@ export declare class CNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendr
     private activeTasks?;
     private pumping;
     private needsPump;
+    private turnDepth;
     private readonly neuronVisitMap?;
     private readonly instanceNeuronQueue;
     private scheduledCount;
+    private reservedActivations;
     private pendingTasks?;
     private failedTasks?;
     private completed?;
@@ -40,12 +43,18 @@ export declare class CNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendr
      * undefined when there is neither a local nor any global listener.
      */
     private readonly onResponse?;
+    /**
+     * The (already wrapped) drain listener, or undefined when there is neither a
+     * local nor any global one. When undefined, endTurn() bails immediately, so a
+     * stimulation with no drain listener pays only the turn depth counter.
+     */
+    private readonly onDrain?;
     /**
      * Track active SCCs: SCC index -> count of active neurons in that SCC.
      * Only allocated when context auto-cleanup is enabled.
      */
     private readonly activeSccCounts?;
-    constructor(cns: CNS<TNeuron, TDendrite>, instanceNeuronQueue: CNSInstanceNeuronQueue<TNeuron>, options?: TCNSStimulationOptions<TCNSStimulationResponse> | undefined, onResponse?: (response: TCNSStimulationResponse) => void | Promise<void>);
+    constructor(cns: CNS<TNeuron, TDendrite>, instanceNeuronQueue: CNSInstanceNeuronQueue<TNeuron>, options?: TCNSStimulationOptions<TCNSStimulationResponse> | undefined, onResponse?: (response: TCNSStimulationResponse) => void | Promise<void>, onDrain?: (drain: TCNSStimulationDrain) => void);
     private pushFailedTask;
     private finalizeResolve;
     private finalizeReject;
@@ -59,6 +68,29 @@ export declare class CNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendr
     private qEnqueue;
     private qGetQueuedTasks;
     private 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.
+     */
+    private beginTurn;
+    /**
+     * 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.
+     */
+    private endTurn;
+    /**
+     * 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.
+     */
+    private get pendingActivations();
     private tryResolveCompleted;
     waitUntilComplete(): Promise<void>;
     /**

package/dist/CNSStimulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CNSStimulation.d.ts","sourceRoot":"","sources":["../src/CNSStimulation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CNSStimulation.d.ts","sourceRoot":"","sources":["../src/CNSStimulation.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -50,12 +50,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;
   }
@@ -64,7 +66,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;
@@ -75,9 +77,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 +187,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 +224,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) {
@@ -276,10 +343,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 +452,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 +511,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 +587,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,7 +660,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
         )
@@ -583,21 +680,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 +721,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 +1082,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 +1099,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 +1190,8 @@ var CNS = class {
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped
+      wrapped,
+      this.wrapOnDrain(options?.onDrain)
     );
     stimulation.responseToSignal(signalOrSignals);
     return stimulation;
@@ -1036,7 +1205,8 @@ var CNS = class {
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped
+      wrapped,
+      this.wrapOnDrain(options?.onDrain)
     );
     stimulation.enqueueTasks(tasks);
     return stimulation;