@cnstra/types 0.2.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,14 +39,35 @@ 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 TCNSNeuronResponseReturn<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 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<TAxonType extends TCNSAxon = TCNSAxon> = {
+    readonly index: number;
     axon: TAxonType;
     /** Optional per-neuron concurrency limit. If undefined or <= 0, no limit is applied. */
     concurrency?: number;
@@ -62,6 +85,7 @@ type TCNSNeuron<TAxonType extends TCNSAxon = TCNSAxon> = {
 type TCNSOptions = Record<never, never>;
 
 type TCNSModality = {
+    readonly index: number;
     afferentPaths: Record<string | number, TCNSAfferentPath>;
 };
 
@@ -69,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> = {
@@ -98,42 +136,29 @@ interface ICNSStimulation<TNeuron extends TCNSNeuron<any>, TDendrite extends TCN
 }
 
 /**
- * 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.
+ * Announced when a stimulation's synchronous turn ends — the batch boundary — or, for a turn inside `cns.batch`, when that batch ends.
  *
- * 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:
+ * 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.
  *
- *   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
- *
- * 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>;
     /**
@@ -157,7 +182,14 @@ type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}>
     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>> = {
@@ -188,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
@@ -216,6 +248,46 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
     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>, TDendrite extends TCNSDendrite<any, any>> = {
@@ -248,10 +320,11 @@ interface ICNS<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<a
     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
@@ -276,14 +349,22 @@ type TCNSHandlerContextBase = {
     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
@@ -301,17 +382,4 @@ type TCNSDendrite<TSenderCollateral extends ICNSCollateral<unknown>, TAxonType e
     response: (payload: TSenderCollateral extends ICNSCollateral<infer P> ? P : never, axon: TAxonType, ctx: TCNSHandlerContext<TExt>) => TCNSNeuronResponseReturn<TAxonType>;
 };
 
-type CNSCollateralLike = ICNSCollateral<unknown>;
-type TCNSNeuronPersistOptions<TNeuron extends TCNSNeuron<any> = TCNSNeuron<any>> = {
-    name: string;
-    neuron: TNeuron;
-};
-type TCNSCollateralPersistOptions<TCollateral extends CNSCollateralLike = CNSCollateralLike> = {
-    name: string;
-    collateral: TCollateral;
-};
-type TCNSStimulationPersistOptions = {
-    stimulationId: string;
-};
-
-export type { ICNS, ICNSCollateral, ICNSNetwork, ICNSStimulation, TCNSAfferentPath, TCNSAxon, TCNSCollateralPersistOptions, TCNSDendrite, TCNSHandlerContext, TCNSModality, TCNSNeuron, TCNSNeuronActivationTask, TCNSNeuronActivationTaskFailure, TCNSNeuronPersistOptions, TCNSNeuronResponseReturn, TCNSOptions, TCNSSignal, TCNSStimulationDrain, TCNSStimulationOptions, TCNSStimulationPersistOptions, TCNSStimulationResponse, TCNSSubscriber };
+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,14 +39,35 @@ 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 TCNSNeuronResponseReturn<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 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<TAxonType extends TCNSAxon = TCNSAxon> = {
+    readonly index: number;
     axon: TAxonType;
     /** Optional per-neuron concurrency limit. If undefined or <= 0, no limit is applied. */
     concurrency?: number;
@@ -62,6 +85,7 @@ type TCNSNeuron<TAxonType extends TCNSAxon = TCNSAxon> = {
 type TCNSOptions = Record<never, never>;
 
 type TCNSModality = {
+    readonly index: number;
     afferentPaths: Record<string | number, TCNSAfferentPath>;
 };
 
@@ -69,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> = {
@@ -98,42 +136,29 @@ interface ICNSStimulation<TNeuron extends TCNSNeuron<any>, TDendrite extends TCN
 }
 
 /**
- * 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.
+ * Announced when a stimulation's synchronous turn ends — the batch boundary — or, for a turn inside `cns.batch`, when that batch ends.
  *
- * 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:
+ * 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.
  *
- *   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
- *
- * 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>;
     /**
@@ -157,7 +182,14 @@ type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}>
     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>> = {
@@ -188,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
@@ -216,6 +248,46 @@ type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> =
     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>, TDendrite extends TCNSDendrite<any, any>> = {
@@ -248,10 +320,11 @@ interface ICNS<TNeuron extends TCNSNeuron<any>, TDendrite extends TCNSDendrite<a
     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
@@ -276,14 +349,22 @@ type TCNSHandlerContextBase = {
     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
@@ -301,17 +382,4 @@ type TCNSDendrite<TSenderCollateral extends ICNSCollateral<unknown>, TAxonType e
     response: (payload: TSenderCollateral extends ICNSCollateral<infer P> ? P : never, axon: TAxonType, ctx: TCNSHandlerContext<TExt>) => TCNSNeuronResponseReturn<TAxonType>;
 };
 
-type CNSCollateralLike = ICNSCollateral<unknown>;
-type TCNSNeuronPersistOptions<TNeuron extends TCNSNeuron<any> = TCNSNeuron<any>> = {
-    name: string;
-    neuron: TNeuron;
-};
-type TCNSCollateralPersistOptions<TCollateral extends CNSCollateralLike = CNSCollateralLike> = {
-    name: string;
-    collateral: TCollateral;
-};
-type TCNSStimulationPersistOptions = {
-    stimulationId: string;
-};
-
-export type { ICNS, ICNSCollateral, ICNSNetwork, ICNSStimulation, TCNSAfferentPath, TCNSAxon, TCNSCollateralPersistOptions, TCNSDendrite, TCNSHandlerContext, TCNSModality, TCNSNeuron, TCNSNeuronActivationTask, TCNSNeuronActivationTaskFailure, TCNSNeuronPersistOptions, TCNSNeuronResponseReturn, TCNSOptions, TCNSSignal, TCNSStimulationDrain, TCNSStimulationOptions, TCNSStimulationPersistOptions, TCNSStimulationResponse, TCNSSubscriber };
+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/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/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":[]}
+{"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.2.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",