@cnstra/core 2.5.0 → 3.0.0

package/dist/index.d.ts

@@ -1,23 +1,7 @@
 export { CNS } from './CNS';
-export { CNSPersistOptionsRegistry } from './CNSPersistOptionsRegistry';
 export { CNSCollateral } from './CNSCollateral';
-export { CNSStimulationContextStore } from './CNSStimulationContextStore';
 export { CNSStimulationGate } from './utils/CNSStimulationGate';
-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, neuronFactory, withCtx, withGlobal, afferentPath, modality, createPersistRegistry, createCNS, } from './factory/index';
+export type { TCNSStimulationGateOptions } from './utils/CNSStimulationGate';
+export { collateral, neuron, neuronFactory, withGlobal, afferentPath, modality, } 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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAG5B,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAKhE,YAAY,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAG7E,OAAO,EACH,UAAU,EACV,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,QAAQ,GACX,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,56 +1,28 @@
-// src/CNSStimulationContextStore.ts
-var CNSStimulationContextStore = class {
-  constructor(ctx) {
-    this.ctx = ctx;
-  }
-  get(key) {
-    return this.ctx?.get(key);
-  }
-  set(key, value) {
-    (this.ctx ?? (this.ctx = /* @__PURE__ */ new Map())).set(key, value);
-  }
-  getAll() {
-    return this.ctx ? new Map(this.ctx) : /* @__PURE__ */ new Map();
-  }
-  setAll(values) {
-    const ctx = this.ctx ?? (this.ctx = /* @__PURE__ */ new Map());
-    ctx.clear();
-    for (const [key, value] of values) ctx.set(key, value);
-  }
-  delete(key) {
-    this.ctx?.delete(key);
-  }
-};
-
 // src/CNSStimulation.ts
 var TASK_DENDRITE = /* @__PURE__ */ Symbol("cnstra.taskDendrite");
 var CNSDendriteContext = class {
-  constructor(stimulation, neuron2, abortSignal, cns) {
+  constructor(stimulation, abortSignal, cns) {
     this.stimulation = stimulation;
-    this.neuron = neuron2;
     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.
+  // Prototype getter, not a constructor field: 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);
-  }
-  set(value) {
-    this.stimulation.getContext().set(this.neuron, value);
-  }
-  delete() {
-    this.stimulation.getContext().delete(this.neuron);
+  // 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;
   }
 };
 var CNSStimulationResponseImpl = class {
-  constructor(stimulation, store, inputSignal, outputSignal, queueLength, pendingActivations, activeActivations, hops, error) {
+  constructor(stimulation, inputSignal, outputSignal, queueLength, pendingActivations, activeActivations, hops, error, neuron2) {
     this.stimulation = stimulation;
-    this.store = store;
     this.inputSignal = inputSignal;
     this.outputSignal = outputSignal;
     this.queueLength = queueLength;
@@ -58,9 +30,7 @@ var CNSStimulationResponseImpl = class {
     this.activeActivations = activeActivations;
     this.hops = hops;
     this.error = error;
-  }
-  get contextValue() {
-    return this.store ? this.store.getAll() : /* @__PURE__ */ new Map();
+    this.neuron = neuron2;
   }
 };
 var CNSStimulation = class {
@@ -89,15 +59,11 @@ var CNSStimulation = class {
     this.isCompleted = false;
     this.completionRejected = false;
     this.onDrain = onDrain;
-    this.ctxStore = options?.ctx;
     this.instanceNeuronQueue = instanceNeuronQueue;
     this.onResponse = onResponse;
     if (this.options?.maxNeuronHops) {
       this.neuronVisitMap = /* @__PURE__ */ new Map();
     }
-    if (this.autoCleanupContextsEnabled) {
-      this.activeSccCounts = /* @__PURE__ */ new Map();
-    }
   }
   pushFailedTask(failure) {
     (this.failedTasks ?? (this.failedTasks = [])).push(failure);
@@ -111,10 +77,6 @@ var CNSStimulation = class {
     this.completionError = error;
     this.rejectCompleted?.(error);
   }
-  /** Lazily-created neuron context store (see {@link ctxStore}). */
-  get ctx() {
-    return this.ctxStore ?? (this.ctxStore = new CNSStimulationContextStore());
-  }
   // ----- Inlined activation queue / pump -----
   get canStartOperation() {
     const limit = this.options?.concurrency ?? Infinity;
@@ -332,10 +294,17 @@ var CNSStimulation = class {
     return this.failedTasks ? [...this.failedTasks] : [];
   }
   /**
-   * Get the context store for this stimulation
+   * 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.
    */
-  getContext() {
-    return this.ctx;
+  getOutstandingTasks() {
+    return [
+      ...this.getAllActivationTasks(),
+      ...this.getFailedTasks().map((f) => f.task)
+    ];
   }
   /**
    * Enqueue activation tasks directly into the stimulation queue
@@ -354,67 +323,6 @@ var CNSStimulation = class {
   get concurrencyEnabled() {
     return this.options?.concurrency !== void 0 && this.options?.concurrency > 0;
   }
-  get autoCleanupContextsEnabled() {
-    return this.cns?.options?.autoCleanupContexts ?? false;
-  }
-  /**
-   * Mark a neuron as active (being processed)
-   */
-  markNeuronActive(neuron2) {
-    if (!this.autoCleanupContextsEnabled) return;
-    this.incrementSccCount(neuron2);
-  }
-  /**
-   * Mark a neuron as inactive (finished processing)
-   */
-  markNeuronInactive(neuron2) {
-    if (!this.autoCleanupContextsEnabled) return;
-    this.decrementSccCount(neuron2);
-  }
-  /**
-   * Increment the active count for the SCC containing this neuron
-   */
-  incrementSccCount(neuron2) {
-    const counts = this.activeSccCounts;
-    if (!counts) return;
-    const sccIndex = this.cns.network.getSccIndexByNeuron(neuron2);
-    if (sccIndex === void 0) return;
-    const currentCount = counts.get(sccIndex) || 0;
-    counts.set(sccIndex, currentCount + 1);
-  }
-  /**
-   * Decrement the active count for the SCC containing this neuron
-   */
-  decrementSccCount(neuron2) {
-    const counts = this.activeSccCounts;
-    if (!counts) return;
-    const sccIndex = this.cns.network.getSccIndexByNeuron(neuron2);
-    if (sccIndex === void 0) return;
-    const currentCount = counts.get(sccIndex) || 0;
-    const nextCount = Math.max(0, currentCount - 1);
-    counts.set(sccIndex, nextCount);
-    if (currentCount === 0) {
-      console.warn(
-        `[CNSStimulation] Attempting to decrement SCC count below 0 for neuron`
-      );
-    }
-  }
-  /**
-   * Check if a neuron can be guaranteed not to be visited again
-   */
-  canNeuronBeGuaranteedDone(neuron2) {
-    if (!this.autoCleanupContextsEnabled || !this.activeSccCounts)
-      return false;
-    return this.cns.network.canNeuronBeGuaranteedDone(
-      neuron2,
-      this.activeSccCounts
-    );
-  }
-  cleanupCtxIfNeeded(neuron2) {
-    if (this.autoCleanupContextsEnabled && this.canNeuronBeGuaranteedDone(neuron2)) {
-      this.ctxStore?.delete(neuron2);
-    }
-  }
   createSubscriberQueueItem(subscriber, inputSignal) {
     if (this.options?.maxNeuronHops) {
       if ((this.neuronVisitMap?.get(subscriber.neuron) ?? 0) >= this.options?.maxNeuronHops) {
@@ -488,7 +396,6 @@ var CNSStimulation = class {
     );
   }
   runStarter(neuron2, dendrite, inputSignal, neuronActivationTask) {
-    this.markNeuronActive(neuron2);
     let response;
     try {
       response = dendrite.response(
@@ -496,13 +403,11 @@ var CNSStimulation = class {
         neuron2.axon,
         new CNSDendriteContext(
           this,
-          neuron2,
           this.options?.abortSignal,
           this.cns
         )
       );
     } catch (error) {
-      this.markNeuronInactive(neuron2);
       const isAborted = this.options?.abortSignal?.aborted ?? false;
       this.pushFailedTask({
         task: neuronActivationTask,
@@ -542,7 +447,6 @@ var CNSStimulation = class {
       return timedPromise.then(
         (signal) => {
           return () => {
-            this.markNeuronInactive(neuron2);
             return this.processResponseOrResponses(
               neuron2,
               inputSignal,
@@ -552,7 +456,6 @@ var CNSStimulation = class {
         },
         (error) => {
           return () => {
-            this.markNeuronInactive(neuron2);
             const isAborted = this.options?.abortSignal?.aborted ?? false;
             this.pushFailedTask({
               task: neuronActivationTask,
@@ -570,7 +473,6 @@ var CNSStimulation = class {
       );
     } else {
       return () => {
-        this.markNeuronInactive(neuron2);
         return this.processResponseOrResponses(
           neuron2,
           inputSignal,
@@ -616,7 +518,6 @@ var CNSStimulation = class {
     const onResponse = this.onResponse;
     if (!onResponse) {
       if (collateral2 && !error) {
-        if (emitter) this.cleanupCtxIfNeeded(emitter);
         const n = subscribers.length;
         if (n > 0) {
           const tasks = new Array(n);
@@ -638,7 +539,6 @@ var CNSStimulation = class {
     }
     const subscriberActivationTasks = [];
     if (collateral2 && !error) {
-      if (emitter) this.cleanupCtxIfNeeded(emitter);
       const pending = this.pendingTasks ?? (this.pendingTasks = /* @__PURE__ */ new Set());
       for (let i = 0; i < subscribers.length; i++) {
         const task = this.createSubscriberQueueItem(
@@ -655,14 +555,14 @@ var CNSStimulation = class {
       maybePromise = onResponse(
         new CNSStimulationResponseImpl(
           this,
-          this.ctxStore,
           inputSignal,
           outputSignal,
           this.pendingActivations + this.activeOperations,
           this.pendingActivations,
           this.activeOperations,
           this.options?.maxNeuronHops && emitter ? this.neuronVisitMap?.get(emitter) ?? 0 : void 0,
-          error
+          error,
+          emitter
         )
       );
     } catch (e) {
@@ -800,8 +700,9 @@ 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.
+     * Computed lazily on first access: the SCC machinery only drives graph
+     * introspection (`getSCCSetByNeuron`, `canNeuronBeGuaranteedDone`), so a
+     * network that never inspects reachability never pays for it.
      */
     this._stronglyConnectedComponents = [];
     this.sccBuilt = false;
@@ -1087,16 +988,20 @@ var CNS = class {
     this.network = new CNSNetwork(this.neurons);
     this.global = global;
   }
-  addResponseListener(listener) {
-    this.globalResponseListeners.push(listener);
+  /** Push a listener onto a list; return an idempotent unsubscribe. */
+  addListener(list, listener) {
+    list.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);
+      const idx = list.indexOf(listener);
+      if (idx >= 0) list.splice(idx, 1);
     };
   }
+  addResponseListener(listener) {
+    return this.addListener(this.globalResponseListeners, listener);
+  }
   /**
    * Register a listener called once at the end of every synchronous turn of
    * every stimulation - see {@link TCNSStimulationDrain}. This is how an
@@ -1106,14 +1011,7 @@ var CNS = class {
    * 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);
-    };
+    return this.addListener(this.globalDrainListeners, listener);
   }
   /**
    * Fan a drain out to the local and global listeners, or return undefined when
@@ -1182,15 +1080,18 @@ var CNS = class {
       }
     };
   }
-  stimulate(signalOrSignals, options) {
-    const wrapped = this.wrapOnResponse(options?.onResponse);
-    const stimulation = new CNSStimulation(
+  /** Build a stimulation (wired listeners, unseeded). Shared by stimulate/activate. */
+  createStimulation(options) {
+    return new CNSStimulation(
       this,
       this.instanceNeuronQueue,
       options,
-      wrapped,
+      this.wrapOnResponse(options?.onResponse),
       this.wrapOnDrain(options?.onDrain)
     );
+  }
+  stimulate(signalOrSignals, options) {
+    const stimulation = this.createStimulation(options);
     stimulation.responseToSignal(signalOrSignals);
     return stimulation;
   }
@@ -1198,85 +1099,12 @@ var CNS = class {
    * Start a stimulation with activation tasks directly
    */
   activate(tasks, options) {
-    const wrapped = this.wrapOnResponse(options?.onResponse);
-    const stimulation = new CNSStimulation(
-      this,
-      this.instanceNeuronQueue,
-      options,
-      wrapped,
-      this.wrapOnDrain(options?.onDrain)
-    );
+    const stimulation = this.createStimulation(options);
     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) {
@@ -1459,13 +1287,11 @@ var 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 {
@@ -1479,31 +1305,7 @@ 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 };
-};
 
-export { CNS, CNSCollateral, CNSPersistOptionsRegistry, CNSStimulationContextStore, CNSStimulationGate, afferentPath, collateral, createCNS, createPersistRegistry, modality, neuron, neuronFactory, withCtx, withGlobal };
+export { CNS, CNSCollateral, CNSStimulationGate, afferentPath, collateral, modality, neuron, neuronFactory, withGlobal };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map