@cnstra/types 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 type TCNSAfferentPath = {
+    readonly index: number;
     parentAfferentPath?: TCNSAfferentPath;
 };
 
@@ -8,6 +9,7 @@ type TCNSSignal<TCollateral extends ICNSCollateral<unknown>> = {
 };
 
 interface ICNSCollateral<TPayload> {
+    readonly index: number;
     createSignal(): TCNSSignal<ICNSCollateral<TPayload>>;
     createSignal(payload: TPayload): TCNSSignal<ICNSCollateral<TPayload>>;
 }
@@ -37,48 +39,53 @@ type TCNSAxon<TCollaterals extends Record<string, ICNSCollateral<unknown>> = Rec
     [K in keyof TCollaterals]: TCollaterals[K];
 };
 
+/**
+ * A context store: data attached to something the engine is running, in
+ * compartments.
+ *
+ * There are two of them, same shape, different life — the run's
+ * (`stimulationContext`, one per stimulation) and the activation's
+ * (`activationContext`, one per neuron activation). Same shape on purpose: they
+ * are used the same way, serialized the same way, and read the same way.
+ *
+ * A key is a namespace its writer owns, by convention the package name
+ * (`'@cnstra/persist-otel'`), so an integration and your own code cannot
+ * overwrite each other. A caller who owns their whole run does not need a prefix.
+ *
+ * Plain object with string keys rather than a `Map` because this crosses a
+ * process boundary: `JSON.stringify` turns a `Map` into `{}` and drops symbol
+ * keys entirely, so neither could carry anything. What is portable travels with
+ * the serialized frontier; a live handle stays where it was made.
+ */
+type TCNSContextStore = Record<string, unknown>;
+
 /**
  * Allowed return types from a neuron dendrite `response` function.
  *
  * Signals route by collateral object identity (not by name).
  */
-type TNCNeuronResponseReturn<TAxon extends TCNSAxon> = Promise<TCNSSignal<TAxon[keyof TAxon]>> | TCNSSignal<TAxon[keyof TAxon]> | Promise<TCNSSignal<TAxon[keyof TAxon]>[]> | TCNSSignal<TAxon[keyof TAxon]>[] | Promise<void> | void;
-
-type TCNSLocalContextValueStore<TContextValue> = {
-    get: () => TContextValue | undefined;
-    set: (value: TContextValue) => void;
-    delete: () => void;
-};
+type TCNSNeuronResponseReturn<TAxon extends TCNSAxon> = TCNSSignal<TAxon[keyof TAxon]> | TCNSSignal<TAxon[keyof TAxon]>[] | void | Promise<TCNSSignal<TAxon[keyof TAxon]> | TCNSSignal<TAxon[keyof TAxon]>[] | void>;
 
-type TCNSNeuron<TContextValue, TAxonType extends TCNSAxon = TCNSAxon> = {
+type TCNSNeuron<TAxonType extends TCNSAxon = TCNSAxon> = {
+    readonly index: number;
     axon: TAxonType;
     /** Optional per-neuron concurrency limit. If undefined or <= 0, no limit is applied. */
     concurrency?: number;
     /** Optional per-neuron max processing duration in milliseconds. */
     maxDuration?: number;
-    dendrites: TCNSDendrite<TContextValue, ICNSCollateral<unknown>, TAxonType, any>[];
+    dendrites: TCNSDendrite<ICNSCollateral<unknown>, TAxonType, any>[];
 };
 
-type TCNSOptions = {
-    /**
-     * Automatically cleanup context stores when the stimulation is finished.
-     * Default is false.
-     *
-     * CAN AFFECT PERFORMANCE!
-     * Better to use only to solve problems with memory quickly.
-     */
-    autoCleanupContexts?: boolean;
-};
-
-interface ICNSStimulationContextStore {
-    get: (key: object) => unknown;
-    set: (key: object, value: unknown) => void;
-    getAll: () => Map<object, unknown>;
-    setAll: (values: Map<object, unknown>) => void;
-    delete: (key: object) => void;
-}
+/**
+ * Options bag for `new CNS(...)`. Currently empty — the former
+ * `autoCleanupContexts` flag was removed together with the per-neuron mutable
+ * context store. Kept as a named type so the constructor signature and future
+ * engine-level options have a stable home.
+ */
+type TCNSOptions = Record<never, never>;
 
 type TCNSModality = {
+    readonly index: number;
     afferentPaths: Record<string | number, TCNSAfferentPath>;
 };
 
@@ -86,6 +93,20 @@ type TCNSNeuronActivationTask<TNeuron extends object = object, TCollateral exten
     neuron: TNeuron;
     dendriteCollateral: TCollateral;
     input?: TCNSSignal<TCollateral>;
+    /**
+     * Data attached to THIS activation, in namespaced compartments — the
+     * per-activation sibling of `stimulationContext`.
+     *
+     * A response listener can write here before the activation runs (the engine
+     * builds these tasks first and hands them to the listener on the response),
+     * and the dendrite reads them back as `ctx.activationContext`.
+     *
+     * Compartment keys are strings, by convention the writer's package name, so
+     * an integration and your own code cannot overwrite each other. What is
+     * portable travels with the serialized frontier; a live handle does not —
+     * see `portable()` in `@cnstra/persist`.
+     */
+    activationContext?: TCNSContextStore;
 };
 
 type TCNSNeuronActivationTaskFailure<TNeuron extends object = object> = {
@@ -100,7 +121,7 @@ type TCNSNeuronActivationTaskFailure<TNeuron extends object = object> = {
  * `CNSStimulation` class in `@cnstra/core` implements it; internal enqueue/dispatch
  * methods are intentionally not part of the public interface.
  */
-interface ICNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+interface ICNSStimulation<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any> = TCNSDendrite<any, any>> {
     /** Resolves when the run completes; rejects on failed tasks / abort. */
     waitUntilComplete(): Promise<void>;
     /** All activation tasks seen this run. */
@@ -112,47 +133,32 @@ interface ICNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendrite extend
      * pending) plus failed/aborted ones. The set to persist for resume.
      */
     getOutstandingTasks(): TCNSNeuronActivationTask<TNeuron>[];
-    /** The per-neuron context store for this run. */
-    getContext(): ICNSStimulationContextStore;
 }
 
 /**
- * Announced when a stimulation's synchronous turn ends: everything reachable
- * without yielding to the event loop has run, and what remains (if anything) is
- * waiting on a promise or blocked by a concurrency limit.
- *
- * This is the batch boundary. It is a property of the scheduler loop exhausting,
- * not of any individual activation starting or finishing - which is why it cannot
- * be derived from `onResponse`. A turn ends in six ways, and a response is only
- * emitted in the first:
+ * Announced when a stimulation's synchronous turn ends — the batch boundary — or, for a turn inside `cns.batch`, when that batch ends.
  *
- *   1. an activation finished and left the queue empty
- *   2. the last activation *started* and returned a promise
- *   3. the stimulation-level `concurrency` limit was reached
- *   4. the stimulation was aborted
- *   5. subscribers are parked behind an async `onResponse` listener
- *   6. a per-neuron `setConcurrency` gate forced an activation onto a promise
+ * It is a property of the scheduler loop exhausting, not of an activation
+ * finishing, so it cannot be derived from `onResponse`: a turn also ends when the
+ * last activation returned a promise, when a concurrency limit is reached, on
+ * abort, and behind an async listener. Fires once per turn, the final one
+ * included.
  *
- * Fires exactly once per turn, including the final one - so a listener that
- * flushes on every drain needs no separate completion handling.
- *
- * The counters carry the same meaning as on `TCNSStimulationResponse`, but they
- * are measured *after* the loop exhausted rather than before the work runs. On a
- * response `pendingActivations` is a forecast; here it is a fact, and a non-zero
- * value can only mean blocked - by a concurrency limit or by an abort - never
- * "about to run".
+ * The counters mean what they do on `TCNSStimulationResponse`, but measured after
+ * the loop exhausted — so a non-zero `pendingActivations` here is blocked, not
+ * about to run.
  */
 type TCNSStimulationDrain = {
     stimulation: ICNSStimulation<any, any>;
     /** `pendingActivations + activeActivations`. Zero means the stimulation is finished. */
     queueLength: number;
-    /** Activations whose dendrite body has not been invoked. Non-zero here means blocked. */
+    /** Activations whose dendrite response has not been invoked. Non-zero here means blocked. */
     pendingActivations: number;
     /** Activations awaiting an unsettled promise. Non-zero means another drain is coming. */
     activeActivations: number;
 };
 
-type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}> = {
+type TCNSStimulationOptions<TResponse> = {
     maxNeuronHops?: number;
     onResponse?: (response: TResponse) => void | Promise<void>;
     /**
@@ -173,11 +179,17 @@ type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}>
      */
     onDrain?: (drain: TCNSStimulationDrain) => void;
     abortSignal?: AbortSignal;
-    ctx?: ICNSStimulationContextStore;
     concurrency?: number;
     modality?: TCNSModality;
     afferentPath?: TCNSAfferentPath;
-    stimulationContext?: TStimulationContext;
+    /**
+     * Data attached to the whole run, in namespaced compartments — the same
+     * object on every hop. Its per-activation sibling is `activationContext`.
+     *
+     * What is portable travels with the serialized frontier, so a run resumed in
+     * another process reads back what the previous attempt left here.
+     */
+    stimulationContext?: TCNSContextStore;
 };
 
 type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>, TOutputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
@@ -185,7 +197,6 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
     outputSignal?: TCNSSignal<TOutputCollateral>;
     modality?: TCNSModality;
     afferentPath?: TCNSAfferentPath;
-    contextValue: Map<object, unknown>;
     /**
      * Every activation this stimulation still owns, in any state:
      * `pendingActivations + activeActivations`.
@@ -209,17 +220,17 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
      */
     queueLength: number;
     /**
-     * Activations that exist (or are reserved) but whose dendrite body has not
-     * been invoked yet: waiting in the ring buffer, created and held before being
+     * Activations that exist (or are reserved) but whose dendrite response has
+     * not been invoked yet: waiting in the ring buffer, created and held before being
      * enqueued, or reserved by an array fan-out that is still mid-dispatch.
      *
      * Subscribers parked behind an async `onResponse` listener are counted here,
      * not in {@link activeActivations}: the split is by lifecycle stage - whether
-     * the body has started - not by whether something is being awaited.
+     * the response has started - not by whether something is being awaited.
      */
     pendingActivations: number;
     /**
-     * Activations whose dendrite body has been invoked and returned a promise
+     * Activations whose dendrite response has been invoked and returned a promise
      * that has not settled.
      *
      * A synchronous body passes through this state within a single pump
@@ -234,12 +245,52 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
      * task's neuron reliably — including for sink/failed tasks that have no output
      * collateral to trace an owner from.
      */
-    neuron?: TCNSNeuron<any, any>;
+    neuron?: TCNSNeuron<any>;
     error?: Error;
     hops?: number;
+    /**
+     * When the activation's dendrite response was invoked, in epoch milliseconds.
+     *
+     * Present for real neuron activations on every path — success, sync throw and
+     * async rejection alike. Absent on responses that are not an activation (the
+     * entry-signal injection, and the terminal signal emitted on abort).
+     */
+    startedAt?: number;
+    /**
+     * How long the dendrite response took, in milliseconds: the span from
+     * {@link startedAt} to the moment the activation settled.
+     *
+     * This is the only place per-hop latency exists — it is what a trace needs to
+     * draw a waterfall and what a metrics layer needs for a latency histogram.
+     * Present exactly when {@link startedAt} is.
+     */
+    duration?: number;
+    /**
+     * The activations this response is about to create — built, but not yet run.
+     *
+     * The engine resolves the subscribers of the output collateral and builds
+     * their tasks BEFORE handing the response to a listener, then enqueues those
+     * very objects afterwards — on the synchronous path, after an async listener
+     * settles, and even after a listener throws. So a listener can write into
+     * `task.activationContext` here and the dendrite will read it back as
+     * `ctx.activationContext`.
+     *
+     * Empty on a response that starts nothing: a sink neuron, a failure, the
+     * entry injection with no subscribers, the terminal abort signal.
+     */
+    scheduledActivationTasks?: readonly TCNSNeuronActivationTask<any>[];
+    /**
+     * The context store of the activation that produced this response — the same
+     * object its own handler reads as `ctx.activationContext`.
+     *
+     * Here so a recorder can put it in the task's history row without holding the
+     * task itself. Undefined when nothing was attached, and on responses that are
+     * not an activation.
+     */
+    activationContext?: TCNSContextStore;
 };
 
-type TCNSSubscriber<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any>> = {
+type TCNSSubscriber<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any>> = {
     neuron: TNeuron;
     dendrite: TDendrite;
 };
@@ -248,7 +299,7 @@ type TCNSSubscriber<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNS
  * The public contract of the compiled neuron network, exposed on `ICNS.network`.
  * The concrete `CNSNetwork` class in `@cnstra/core` implements it.
  */
-interface ICNSNetwork<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+interface ICNSNetwork<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any> = TCNSDendrite<any, any>> {
     readonly stronglyConnectedComponents: Set<TNeuron>[];
     getSCCSetByNeuron(neuron: TNeuron): Set<TNeuron> | undefined;
     getSccIndexByNeuron(neuron: TNeuron): number | undefined;
@@ -259,7 +310,7 @@ interface ICNSNetwork<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TC
     getSubscribers(collateral: ICNSCollateral<unknown>): TCNSSubscriber<TNeuron, TDendrite>[];
 }
 
-interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+interface ICNS<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any> = TCNSDendrite<any, any>> {
     options?: TCNSOptions;
     network: ICNSNetwork<TNeuron, TDendrite>;
     /**
@@ -269,16 +320,18 @@ interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendr
     addResponseListener(listener: (response: TCNSStimulationResponse) => void): () => void;
     /**
      * Add a global batch-boundary listener applied to all stimulations, called
-     * once at the end of every synchronous turn.
+     * once at the end of every synchronous turn (inside `batch`, when the batch ends).
      * Returns an unsubscribe function.
      */
     addDrainListener(listener: (drain: TCNSStimulationDrain) => void): () => void;
+    batch<TResult>(run: () => TResult): TResult;
     stimulate(signalOrSignals: TCNSSignal<ICNSCollateral<unknown>> | TCNSSignal<ICNSCollateral<unknown>>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): ICNSStimulation<TNeuron, TDendrite>;
     /**
      * Resume a run from a set of activation tasks (e.g. an outstanding frontier
      * hydrated from persisted progress, or `getFailedTasks()` for a partial
      * retry). Unlike {@link stimulate}, no entry signal is derived — the given
-     * tasks are enqueued directly. Pass `options.ctx` to restore neuron context.
+     * tasks are enqueued directly. Each task carries its own input signal (with
+     * payload), so re-driving the frontier needs no extra state.
      */
     activate(tasks: TCNSNeuronActivationTask<TNeuron>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): ICNSStimulation<TNeuron, TDendrite>;
 }
@@ -288,20 +341,30 @@ interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendr
  * lives here. Factory layers add their own fields via the `TExt` extension
  * (see {@link TCNSHandlerContext}), so the base stays clean for neurons that
  * don't opt into anything.
+ *
+ * Internal building block for {@link TCNSHandlerContext} — not part of the public API.
  */
-type TCNSHandlerContextBase<TContextValue> = TCNSLocalContextValueStore<TContextValue> & {
+type TCNSHandlerContextBase = {
     abortSignal?: AbortSignal;
     cns?: ICNS<any, any>;
     stimulation?: any;
     /**
-     * The caller-supplied value passed as `stimulate(sig, { stimulationContext })`
-     * (or `activate(...)`) — the same object on every hop of this stimulation, in
-     * any environment (sync or async, node or browser). Use it to correlate logs
-     * to a run: pass `{ stimulationId, attemptNumber }` and read it here. Typed
-     * `unknown` because the neuron doesn't own the shape — the caller does; cast at
-     * the read site.
+     * The context store of the whole run — what the caller passed as
+     * `stimulate(sig, { stimulationContext })` plus whatever the run has written
+     * into it since, the same object on every hop in any environment (sync or
+     * async, node or browser). Keyed by namespace; the values inside are
+     * `unknown`, so cast at the read site.
      */
-    stimulationContext?: unknown;
+    stimulationContext?: TCNSContextStore;
+    /**
+     * The context store of the activation currently running — data a response
+     * listener attached to THIS activation before it started. Unset when nobody
+     * wrote anything.
+     *
+     * Same shape as {@link stimulationContext}, shorter life: this one is gone
+     * when the activation returns.
+     */
+    activationContext?: TCNSContextStore;
 };
 /**
  * The `ctx` a dendrite handler receives. `TExt` is whatever the factory layers
@@ -312,34 +375,11 @@ type TCNSHandlerContextBase<TContextValue> = TCNSLocalContextValueStore<TContext
  * The handler signature stays `(payload, axon, ctx)` no matter how many layers
  * you stack; each layer widens the type of `ctx`, never the argument list.
  */
-type TCNSHandlerContext<TContextValue, TExt = unknown> = TCNSHandlerContextBase<TContextValue> & TExt;
+type TCNSHandlerContext<TExt = unknown> = TCNSHandlerContextBase & TExt;
 
-type TCNSDendrite<TContextValue, TSenderCollateral extends ICNSCollateral<unknown>, TAxonType extends TCNSAxon, TExt = unknown> = {
+type TCNSDendrite<TSenderCollateral extends ICNSCollateral<unknown>, TAxonType extends TCNSAxon, TExt = unknown> = {
     collateral: TSenderCollateral;
-    response: (payload: TSenderCollateral extends ICNSCollateral<infer P> ? P : never, axon: TAxonType, ctx: TCNSHandlerContext<TContextValue, TExt>) => TNCNeuronResponseReturn<TAxonType>;
-};
-
-type CNSCollateralLike = ICNSCollateral<unknown>;
-type TCNSNeuronPersistOptions<TNeuron extends TCNSNeuron<unknown, any> = TCNSNeuron<unknown, any>> = {
-    name: string;
-    neuron: TNeuron;
-};
-type TCNSCollateralPersistOptions<TCollateral extends CNSCollateralLike = CNSCollateralLike> = {
-    name: string;
-    collateral: TCollateral;
-};
-type TCNSStimulationPersistOptions = {
-    stimulationId: string;
-};
-
-type TCNSStimulationQueueItem<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any>, TInputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
-    neuron: TNeuron;
-    subscriber: TCNSSubscriber<TNeuron, TDendrite>;
-    inputSignal?: TCNSSignal<TInputCollateral>;
-};
-
-type TCNSStimulationSerializedContextValue = {
-    [key: string]: unknown;
+    response: (payload: TSenderCollateral extends ICNSCollateral<infer P> ? P : never, axon: TAxonType, ctx: TCNSHandlerContext<TExt>) => TCNSNeuronResponseReturn<TAxonType>;
 };
 
-export type { ICNS, ICNSCollateral, ICNSNetwork, ICNSStimulation, ICNSStimulationContextStore, TCNSAfferentPath, TCNSAxon, TCNSCollateralPersistOptions, TCNSDendrite, TCNSHandlerContext, TCNSHandlerContextBase, TCNSLocalContextValueStore, TCNSModality, TCNSNeuron, TCNSNeuronActivationTask, TCNSNeuronActivationTaskFailure, TCNSNeuronPersistOptions, TCNSOptions, TCNSSignal, TCNSStimulationDrain, TCNSStimulationOptions, TCNSStimulationPersistOptions, TCNSStimulationQueueItem, TCNSStimulationResponse, TCNSStimulationSerializedContextValue, TCNSSubscriber, TNCNeuronResponseReturn };
+export type { ICNS, ICNSCollateral, ICNSNetwork, ICNSStimulation, TCNSAfferentPath, TCNSAxon, TCNSContextStore, TCNSDendrite, TCNSHandlerContext, TCNSModality, TCNSNeuron, TCNSNeuronActivationTask, TCNSNeuronActivationTaskFailure, TCNSNeuronResponseReturn, TCNSOptions, TCNSSignal, TCNSStimulationDrain, TCNSStimulationOptions, TCNSStimulationResponse, TCNSSubscriber };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 type TCNSAfferentPath = {
+    readonly index: number;
     parentAfferentPath?: TCNSAfferentPath;
 };
 
@@ -8,6 +9,7 @@ type TCNSSignal<TCollateral extends ICNSCollateral<unknown>> = {
 };
 
 interface ICNSCollateral<TPayload> {
+    readonly index: number;
     createSignal(): TCNSSignal<ICNSCollateral<TPayload>>;
     createSignal(payload: TPayload): TCNSSignal<ICNSCollateral<TPayload>>;
 }
@@ -37,48 +39,53 @@ type TCNSAxon<TCollaterals extends Record<string, ICNSCollateral<unknown>> = Rec
     [K in keyof TCollaterals]: TCollaterals[K];
 };
 
+/**
+ * A context store: data attached to something the engine is running, in
+ * compartments.
+ *
+ * There are two of them, same shape, different life — the run's
+ * (`stimulationContext`, one per stimulation) and the activation's
+ * (`activationContext`, one per neuron activation). Same shape on purpose: they
+ * are used the same way, serialized the same way, and read the same way.
+ *
+ * A key is a namespace its writer owns, by convention the package name
+ * (`'@cnstra/persist-otel'`), so an integration and your own code cannot
+ * overwrite each other. A caller who owns their whole run does not need a prefix.
+ *
+ * Plain object with string keys rather than a `Map` because this crosses a
+ * process boundary: `JSON.stringify` turns a `Map` into `{}` and drops symbol
+ * keys entirely, so neither could carry anything. What is portable travels with
+ * the serialized frontier; a live handle stays where it was made.
+ */
+type TCNSContextStore = Record<string, unknown>;
+
 /**
  * Allowed return types from a neuron dendrite `response` function.
  *
  * Signals route by collateral object identity (not by name).
  */
-type TNCNeuronResponseReturn<TAxon extends TCNSAxon> = Promise<TCNSSignal<TAxon[keyof TAxon]>> | TCNSSignal<TAxon[keyof TAxon]> | Promise<TCNSSignal<TAxon[keyof TAxon]>[]> | TCNSSignal<TAxon[keyof TAxon]>[] | Promise<void> | void;
-
-type TCNSLocalContextValueStore<TContextValue> = {
-    get: () => TContextValue | undefined;
-    set: (value: TContextValue) => void;
-    delete: () => void;
-};
+type TCNSNeuronResponseReturn<TAxon extends TCNSAxon> = TCNSSignal<TAxon[keyof TAxon]> | TCNSSignal<TAxon[keyof TAxon]>[] | void | Promise<TCNSSignal<TAxon[keyof TAxon]> | TCNSSignal<TAxon[keyof TAxon]>[] | void>;
 
-type TCNSNeuron<TContextValue, TAxonType extends TCNSAxon = TCNSAxon> = {
+type TCNSNeuron<TAxonType extends TCNSAxon = TCNSAxon> = {
+    readonly index: number;
     axon: TAxonType;
     /** Optional per-neuron concurrency limit. If undefined or <= 0, no limit is applied. */
     concurrency?: number;
     /** Optional per-neuron max processing duration in milliseconds. */
     maxDuration?: number;
-    dendrites: TCNSDendrite<TContextValue, ICNSCollateral<unknown>, TAxonType, any>[];
+    dendrites: TCNSDendrite<ICNSCollateral<unknown>, TAxonType, any>[];
 };
 
-type TCNSOptions = {
-    /**
-     * Automatically cleanup context stores when the stimulation is finished.
-     * Default is false.
-     *
-     * CAN AFFECT PERFORMANCE!
-     * Better to use only to solve problems with memory quickly.
-     */
-    autoCleanupContexts?: boolean;
-};
-
-interface ICNSStimulationContextStore {
-    get: (key: object) => unknown;
-    set: (key: object, value: unknown) => void;
-    getAll: () => Map<object, unknown>;
-    setAll: (values: Map<object, unknown>) => void;
-    delete: (key: object) => void;
-}
+/**
+ * Options bag for `new CNS(...)`. Currently empty — the former
+ * `autoCleanupContexts` flag was removed together with the per-neuron mutable
+ * context store. Kept as a named type so the constructor signature and future
+ * engine-level options have a stable home.
+ */
+type TCNSOptions = Record<never, never>;
 
 type TCNSModality = {
+    readonly index: number;
     afferentPaths: Record<string | number, TCNSAfferentPath>;
 };
 
@@ -86,6 +93,20 @@ type TCNSNeuronActivationTask<TNeuron extends object = object, TCollateral exten
     neuron: TNeuron;
     dendriteCollateral: TCollateral;
     input?: TCNSSignal<TCollateral>;
+    /**
+     * Data attached to THIS activation, in namespaced compartments — the
+     * per-activation sibling of `stimulationContext`.
+     *
+     * A response listener can write here before the activation runs (the engine
+     * builds these tasks first and hands them to the listener on the response),
+     * and the dendrite reads them back as `ctx.activationContext`.
+     *
+     * Compartment keys are strings, by convention the writer's package name, so
+     * an integration and your own code cannot overwrite each other. What is
+     * portable travels with the serialized frontier; a live handle does not —
+     * see `portable()` in `@cnstra/persist`.
+     */
+    activationContext?: TCNSContextStore;
 };
 
 type TCNSNeuronActivationTaskFailure<TNeuron extends object = object> = {
@@ -100,7 +121,7 @@ type TCNSNeuronActivationTaskFailure<TNeuron extends object = object> = {
  * `CNSStimulation` class in `@cnstra/core` implements it; internal enqueue/dispatch
  * methods are intentionally not part of the public interface.
  */
-interface ICNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+interface ICNSStimulation<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any> = TCNSDendrite<any, any>> {
     /** Resolves when the run completes; rejects on failed tasks / abort. */
     waitUntilComplete(): Promise<void>;
     /** All activation tasks seen this run. */
@@ -112,47 +133,32 @@ interface ICNSStimulation<TNeuron extends TCNSNeuron<any, any>, TDendrite extend
      * pending) plus failed/aborted ones. The set to persist for resume.
      */
     getOutstandingTasks(): TCNSNeuronActivationTask<TNeuron>[];
-    /** The per-neuron context store for this run. */
-    getContext(): ICNSStimulationContextStore;
 }
 
 /**
- * Announced when a stimulation's synchronous turn ends: everything reachable
- * without yielding to the event loop has run, and what remains (if anything) is
- * waiting on a promise or blocked by a concurrency limit.
- *
- * This is the batch boundary. It is a property of the scheduler loop exhausting,
- * not of any individual activation starting or finishing - which is why it cannot
- * be derived from `onResponse`. A turn ends in six ways, and a response is only
- * emitted in the first:
+ * Announced when a stimulation's synchronous turn ends — the batch boundary — or, for a turn inside `cns.batch`, when that batch ends.
  *
- *   1. an activation finished and left the queue empty
- *   2. the last activation *started* and returned a promise
- *   3. the stimulation-level `concurrency` limit was reached
- *   4. the stimulation was aborted
- *   5. subscribers are parked behind an async `onResponse` listener
- *   6. a per-neuron `setConcurrency` gate forced an activation onto a promise
+ * It is a property of the scheduler loop exhausting, not of an activation
+ * finishing, so it cannot be derived from `onResponse`: a turn also ends when the
+ * last activation returned a promise, when a concurrency limit is reached, on
+ * abort, and behind an async listener. Fires once per turn, the final one
+ * included.
  *
- * Fires exactly once per turn, including the final one - so a listener that
- * flushes on every drain needs no separate completion handling.
- *
- * The counters carry the same meaning as on `TCNSStimulationResponse`, but they
- * are measured *after* the loop exhausted rather than before the work runs. On a
- * response `pendingActivations` is a forecast; here it is a fact, and a non-zero
- * value can only mean blocked - by a concurrency limit or by an abort - never
- * "about to run".
+ * The counters mean what they do on `TCNSStimulationResponse`, but measured after
+ * the loop exhausted — so a non-zero `pendingActivations` here is blocked, not
+ * about to run.
  */
 type TCNSStimulationDrain = {
     stimulation: ICNSStimulation<any, any>;
     /** `pendingActivations + activeActivations`. Zero means the stimulation is finished. */
     queueLength: number;
-    /** Activations whose dendrite body has not been invoked. Non-zero here means blocked. */
+    /** Activations whose dendrite response has not been invoked. Non-zero here means blocked. */
     pendingActivations: number;
     /** Activations awaiting an unsettled promise. Non-zero means another drain is coming. */
     activeActivations: number;
 };
 
-type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}> = {
+type TCNSStimulationOptions<TResponse> = {
     maxNeuronHops?: number;
     onResponse?: (response: TResponse) => void | Promise<void>;
     /**
@@ -173,11 +179,17 @@ type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}>
      */
     onDrain?: (drain: TCNSStimulationDrain) => void;
     abortSignal?: AbortSignal;
-    ctx?: ICNSStimulationContextStore;
     concurrency?: number;
     modality?: TCNSModality;
     afferentPath?: TCNSAfferentPath;
-    stimulationContext?: TStimulationContext;
+    /**
+     * Data attached to the whole run, in namespaced compartments — the same
+     * object on every hop. Its per-activation sibling is `activationContext`.
+     *
+     * What is portable travels with the serialized frontier, so a run resumed in
+     * another process reads back what the previous attempt left here.
+     */
+    stimulationContext?: TCNSContextStore;
 };
 
 type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>, TOutputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
@@ -185,7 +197,6 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
     outputSignal?: TCNSSignal<TOutputCollateral>;
     modality?: TCNSModality;
     afferentPath?: TCNSAfferentPath;
-    contextValue: Map<object, unknown>;
     /**
      * Every activation this stimulation still owns, in any state:
      * `pendingActivations + activeActivations`.
@@ -209,17 +220,17 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
      */
     queueLength: number;
     /**
-     * Activations that exist (or are reserved) but whose dendrite body has not
-     * been invoked yet: waiting in the ring buffer, created and held before being
+     * Activations that exist (or are reserved) but whose dendrite response has
+     * not been invoked yet: waiting in the ring buffer, created and held before being
      * enqueued, or reserved by an array fan-out that is still mid-dispatch.
      *
      * Subscribers parked behind an async `onResponse` listener are counted here,
      * not in {@link activeActivations}: the split is by lifecycle stage - whether
-     * the body has started - not by whether something is being awaited.
+     * the response has started - not by whether something is being awaited.
      */
     pendingActivations: number;
     /**
-     * Activations whose dendrite body has been invoked and returned a promise
+     * Activations whose dendrite response has been invoked and returned a promise
      * that has not settled.
      *
      * A synchronous body passes through this state within a single pump
@@ -234,12 +245,52 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
      * task's neuron reliably — including for sink/failed tasks that have no output
      * collateral to trace an owner from.
      */
-    neuron?: TCNSNeuron<any, any>;
+    neuron?: TCNSNeuron<any>;
     error?: Error;
     hops?: number;
+    /**
+     * When the activation's dendrite response was invoked, in epoch milliseconds.
+     *
+     * Present for real neuron activations on every path — success, sync throw and
+     * async rejection alike. Absent on responses that are not an activation (the
+     * entry-signal injection, and the terminal signal emitted on abort).
+     */
+    startedAt?: number;
+    /**
+     * How long the dendrite response took, in milliseconds: the span from
+     * {@link startedAt} to the moment the activation settled.
+     *
+     * This is the only place per-hop latency exists — it is what a trace needs to
+     * draw a waterfall and what a metrics layer needs for a latency histogram.
+     * Present exactly when {@link startedAt} is.
+     */
+    duration?: number;
+    /**
+     * The activations this response is about to create — built, but not yet run.
+     *
+     * The engine resolves the subscribers of the output collateral and builds
+     * their tasks BEFORE handing the response to a listener, then enqueues those
+     * very objects afterwards — on the synchronous path, after an async listener
+     * settles, and even after a listener throws. So a listener can write into
+     * `task.activationContext` here and the dendrite will read it back as
+     * `ctx.activationContext`.
+     *
+     * Empty on a response that starts nothing: a sink neuron, a failure, the
+     * entry injection with no subscribers, the terminal abort signal.
+     */
+    scheduledActivationTasks?: readonly TCNSNeuronActivationTask<any>[];
+    /**
+     * The context store of the activation that produced this response — the same
+     * object its own handler reads as `ctx.activationContext`.
+     *
+     * Here so a recorder can put it in the task's history row without holding the
+     * task itself. Undefined when nothing was attached, and on responses that are
+     * not an activation.
+     */
+    activationContext?: TCNSContextStore;
 };
 
-type TCNSSubscriber<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any>> = {
+type TCNSSubscriber<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any>> = {
     neuron: TNeuron;
     dendrite: TDendrite;
 };
@@ -248,7 +299,7 @@ type TCNSSubscriber<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNS
  * The public contract of the compiled neuron network, exposed on `ICNS.network`.
  * The concrete `CNSNetwork` class in `@cnstra/core` implements it.
  */
-interface ICNSNetwork<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+interface ICNSNetwork<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any> = TCNSDendrite<any, any>> {
     readonly stronglyConnectedComponents: Set<TNeuron>[];
     getSCCSetByNeuron(neuron: TNeuron): Set<TNeuron> | undefined;
     getSccIndexByNeuron(neuron: TNeuron): number | undefined;
@@ -259,7 +310,7 @@ interface ICNSNetwork<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TC
     getSubscribers(collateral: ICNSCollateral<unknown>): TCNSSubscriber<TNeuron, TDendrite>[];
 }
 
-interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+interface ICNS<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<any, any> = TCNSDendrite<any, any>> {
     options?: TCNSOptions;
     network: ICNSNetwork<TNeuron, TDendrite>;
     /**
@@ -269,16 +320,18 @@ interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendr
     addResponseListener(listener: (response: TCNSStimulationResponse) => void): () => void;
     /**
      * Add a global batch-boundary listener applied to all stimulations, called
-     * once at the end of every synchronous turn.
+     * once at the end of every synchronous turn (inside `batch`, when the batch ends).
      * Returns an unsubscribe function.
      */
     addDrainListener(listener: (drain: TCNSStimulationDrain) => void): () => void;
+    batch<TResult>(run: () => TResult): TResult;
     stimulate(signalOrSignals: TCNSSignal<ICNSCollateral<unknown>> | TCNSSignal<ICNSCollateral<unknown>>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): ICNSStimulation<TNeuron, TDendrite>;
     /**
      * Resume a run from a set of activation tasks (e.g. an outstanding frontier
      * hydrated from persisted progress, or `getFailedTasks()` for a partial
      * retry). Unlike {@link stimulate}, no entry signal is derived — the given
-     * tasks are enqueued directly. Pass `options.ctx` to restore neuron context.
+     * tasks are enqueued directly. Each task carries its own input signal (with
+     * payload), so re-driving the frontier needs no extra state.
      */
     activate(tasks: TCNSNeuronActivationTask<TNeuron>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): ICNSStimulation<TNeuron, TDendrite>;
 }
@@ -288,20 +341,30 @@ interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendr
  * lives here. Factory layers add their own fields via the `TExt` extension
  * (see {@link TCNSHandlerContext}), so the base stays clean for neurons that
  * don't opt into anything.
+ *
+ * Internal building block for {@link TCNSHandlerContext} — not part of the public API.
  */
-type TCNSHandlerContextBase<TContextValue> = TCNSLocalContextValueStore<TContextValue> & {
+type TCNSHandlerContextBase = {
     abortSignal?: AbortSignal;
     cns?: ICNS<any, any>;
     stimulation?: any;
     /**
-     * The caller-supplied value passed as `stimulate(sig, { stimulationContext })`
-     * (or `activate(...)`) — the same object on every hop of this stimulation, in
-     * any environment (sync or async, node or browser). Use it to correlate logs
-     * to a run: pass `{ stimulationId, attemptNumber }` and read it here. Typed
-     * `unknown` because the neuron doesn't own the shape — the caller does; cast at
-     * the read site.
+     * The context store of the whole run — what the caller passed as
+     * `stimulate(sig, { stimulationContext })` plus whatever the run has written
+     * into it since, the same object on every hop in any environment (sync or
+     * async, node or browser). Keyed by namespace; the values inside are
+     * `unknown`, so cast at the read site.
      */
-    stimulationContext?: unknown;
+    stimulationContext?: TCNSContextStore;
+    /**
+     * The context store of the activation currently running — data a response
+     * listener attached to THIS activation before it started. Unset when nobody
+     * wrote anything.
+     *
+     * Same shape as {@link stimulationContext}, shorter life: this one is gone
+     * when the activation returns.
+     */
+    activationContext?: TCNSContextStore;
 };
 /**
  * The `ctx` a dendrite handler receives. `TExt` is whatever the factory layers
@@ -312,34 +375,11 @@ type TCNSHandlerContextBase<TContextValue> = TCNSLocalContextValueStore<TContext
  * The handler signature stays `(payload, axon, ctx)` no matter how many layers
  * you stack; each layer widens the type of `ctx`, never the argument list.
  */
-type TCNSHandlerContext<TContextValue, TExt = unknown> = TCNSHandlerContextBase<TContextValue> & TExt;
+type TCNSHandlerContext<TExt = unknown> = TCNSHandlerContextBase & TExt;
 
-type TCNSDendrite<TContextValue, TSenderCollateral extends ICNSCollateral<unknown>, TAxonType extends TCNSAxon, TExt = unknown> = {
+type TCNSDendrite<TSenderCollateral extends ICNSCollateral<unknown>, TAxonType extends TCNSAxon, TExt = unknown> = {
     collateral: TSenderCollateral;
-    response: (payload: TSenderCollateral extends ICNSCollateral<infer P> ? P : never, axon: TAxonType, ctx: TCNSHandlerContext<TContextValue, TExt>) => TNCNeuronResponseReturn<TAxonType>;
-};
-
-type CNSCollateralLike = ICNSCollateral<unknown>;
-type TCNSNeuronPersistOptions<TNeuron extends TCNSNeuron<unknown, any> = TCNSNeuron<unknown, any>> = {
-    name: string;
-    neuron: TNeuron;
-};
-type TCNSCollateralPersistOptions<TCollateral extends CNSCollateralLike = CNSCollateralLike> = {
-    name: string;
-    collateral: TCollateral;
-};
-type TCNSStimulationPersistOptions = {
-    stimulationId: string;
-};
-
-type TCNSStimulationQueueItem<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any>, TInputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
-    neuron: TNeuron;
-    subscriber: TCNSSubscriber<TNeuron, TDendrite>;
-    inputSignal?: TCNSSignal<TInputCollateral>;
-};
-
-type TCNSStimulationSerializedContextValue = {
-    [key: string]: unknown;
+    response: (payload: TSenderCollateral extends ICNSCollateral<infer P> ? P : never, axon: TAxonType, ctx: TCNSHandlerContext<TExt>) => TCNSNeuronResponseReturn<TAxonType>;
 };
 
-export type { ICNS, ICNSCollateral, ICNSNetwork, ICNSStimulation, ICNSStimulationContextStore, TCNSAfferentPath, TCNSAxon, TCNSCollateralPersistOptions, TCNSDendrite, TCNSHandlerContext, TCNSHandlerContextBase, TCNSLocalContextValueStore, TCNSModality, TCNSNeuron, TCNSNeuronActivationTask, TCNSNeuronActivationTaskFailure, TCNSNeuronPersistOptions, TCNSOptions, TCNSSignal, TCNSStimulationDrain, TCNSStimulationOptions, TCNSStimulationPersistOptions, TCNSStimulationQueueItem, TCNSStimulationResponse, TCNSStimulationSerializedContextValue, TCNSSubscriber, TNCNeuronResponseReturn };
+export type { ICNS, ICNSCollateral, ICNSNetwork, ICNSStimulation, TCNSAfferentPath, TCNSAxon, TCNSContextStore, TCNSDendrite, TCNSHandlerContext, TCNSModality, TCNSNeuron, TCNSNeuronActivationTask, TCNSNeuronActivationTaskFailure, TCNSNeuronResponseReturn, TCNSOptions, TCNSSignal, TCNSStimulationDrain, TCNSStimulationOptions, TCNSStimulationResponse, TCNSSubscriber };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./types/TCNSAfferentPath\";\nexport * from \"./types/TCNSAxon\";\nexport * from \"./types/TCNSDendrite\";\nexport * from \"./types/TCNSHandlerContext\";\nexport * from \"./types/TCNSLocalContextValueStore\";\nexport * from \"./types/TCNSModality\";\nexport * from \"./types/TCNSNeuron\";\nexport * from \"./types/TCNSNeuronActivationTask\";\nexport * from \"./types/TCNSNeuronActivationTaskFailure\";\nexport * from \"./types/TCNSNeuronResponseReturn\";\nexport * from \"./types/TCNSOptions\";\nexport * from \"./types/TCNSPersist\";\nexport * from \"./types/TCNSSignal\";\nexport * from \"./types/TCNSStimulationDrain\";\nexport * from \"./types/TCNSStimulationOptions\";\nexport * from \"./types/TCNSStimulationQueueItem\";\nexport * from \"./types/TCNSStimulationResponse\";\nexport * from \"./types/TCNSStimulationSerializedContextValue\";\nexport * from \"./types/TCNSSubscriber\";\nexport * from \"./interfaces/ICNS\";\nexport * from \"./interfaces/ICNSCollateral\";\nexport * from \"./interfaces/ICNSNetwork\";\nexport * from \"./interfaces/ICNSStimulation\";\nexport * from \"./interfaces/ICNSStimulationContextStore\";\n"],"mappings":";;;;;;;;;;;;;;;AAAA;;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./types/TCNSAfferentPath\";\nexport * from \"./types/TCNSAxon\";\nexport * from \"./types/TCNSContextStore\";\nexport * from \"./types/TCNSDendrite\";\nexport * from \"./types/TCNSHandlerContext\";\nexport * from \"./types/TCNSModality\";\nexport * from \"./types/TCNSNeuron\";\nexport * from \"./types/TCNSNeuronActivationTask\";\nexport * from \"./types/TCNSNeuronActivationTaskFailure\";\nexport * from \"./types/TCNSNeuronResponseReturn\";\nexport * from \"./types/TCNSOptions\";\nexport * from \"./types/TCNSSignal\";\nexport * from \"./types/TCNSStimulationDrain\";\nexport * from \"./types/TCNSStimulationOptions\";\nexport * from \"./types/TCNSStimulationResponse\";\nexport * from \"./types/TCNSSubscriber\";\nexport * from \"./interfaces/ICNS\";\nexport * from \"./interfaces/ICNSCollateral\";\nexport * from \"./interfaces/ICNSNetwork\";\nexport * from \"./interfaces/ICNSStimulation\";\n"],"mappings":";;;;;;;;;;;;;;;AAAA;;","names":[]}

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@cnstra/types",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Shared TypeScript contract for CNStra: signals, tasks, axons, neuron/collateral/stimulation/network interfaces. Zero runtime — the base package core and integrations build on.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abaikov/cnstra.git",
+    "directory": "packages/types"
+  },
   "keywords": ["cnstra", "types", "contract", "interfaces"],
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -16,6 +21,7 @@
   "sideEffects": false,
   "files": ["dist"],
   "scripts": {
+    "prepublishOnly": "node ../../scripts/check-drift.mjs --gate",
     "build": "tsup",
     "test:types": "tsc --noEmit",
     "clean": "rm -rf dist"