@cnstra/core 2.5.0 → 3.0.0

package/dist/index.cjs

@@ -1,58 +1,30 @@
 'use strict';
 
-// 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;
@@ -60,9 +32,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 {
@@ -91,15 +61,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);
@@ -113,10 +79,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;
@@ -334,10 +296,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
@@ -356,67 +325,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) {
@@ -490,7 +398,6 @@ var CNSStimulation = class {
     );
   }
   runStarter(neuron2, dendrite, inputSignal, neuronActivationTask) {
-    this.markNeuronActive(neuron2);
     let response;
     try {
       response = dendrite.response(
@@ -498,13 +405,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,
@@ -544,7 +449,6 @@ var CNSStimulation = class {
       return timedPromise.then(
         (signal) => {
           return () => {
-            this.markNeuronInactive(neuron2);
             return this.processResponseOrResponses(
               neuron2,
               inputSignal,
@@ -554,7 +458,6 @@ var CNSStimulation = class {
         },
         (error) => {
           return () => {
-            this.markNeuronInactive(neuron2);
             const isAborted = this.options?.abortSignal?.aborted ?? false;
             this.pushFailedTask({
               task: neuronActivationTask,
@@ -572,7 +475,6 @@ var CNSStimulation = class {
       );
     } else {
       return () => {
-        this.markNeuronInactive(neuron2);
         return this.processResponseOrResponses(
           neuron2,
           inputSignal,
@@ -618,7 +520,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);
@@ -640,7 +541,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(
@@ -657,14 +557,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) {
@@ -802,8 +702,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;
@@ -1089,16 +990,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
@@ -1108,14 +1013,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
@@ -1184,15 +1082,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;
   }
@@ -1200,85 +1101,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) {
@@ -1461,13 +1289,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 {
@@ -1481,44 +1307,15 @@ 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;
-exports.withCtx = withCtx;
 exports.withGlobal = withGlobal;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map