@cnstra/types 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,345 @@
+type TCNSAfferentPath = {
+    parentAfferentPath?: TCNSAfferentPath;
+};
+
+type TCNSSignal<TCollateral extends ICNSCollateral<unknown>> = {
+    collateral: TCollateral;
+    payload?: TCollateral extends ICNSCollateral<infer P> ? P : never;
+};
+
+interface ICNSCollateral<TPayload> {
+    createSignal(): TCNSSignal<ICNSCollateral<TPayload>>;
+    createSignal(payload: TPayload): TCNSSignal<ICNSCollateral<TPayload>>;
+}
+
+/**
+ * Axon type used by neurons.
+ *
+ * Historically this type only took a collateral name union and a single payload
+ * type, which meant every collateral on the axon was typed with the same
+ * payload (typically a union of all possible payloads).
+ *
+ * That broke property-level typing on `axon.*.createSignal(...)` – the payload
+ * parameter became a big union instead of the specific payload for that
+ * collateral.
+ *
+ * To fix this while keeping existing generic call sites mostly intact, we add
+ * a third type parameter that carries the original heterogeneous axon object.
+ * When that third parameter is provided, we preserve the precise payload type
+ * for each collateral.
+ *
+ * - `TCollateralName` / `TInputPayload` are still useful for higher-level
+ *   generic constraints (unions of names / payloads).
+ * - `TCollaterals` is the concrete axon map used to recover the per-key
+ *   payload types.
+ */
+type TCNSAxon<TCollaterals extends Record<string, ICNSCollateral<unknown>> = Record<string, ICNSCollateral<unknown>>> = {
+    [K in keyof TCollaterals]: TCollaterals[K];
+};
+
+/**
+ * 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 TCNSNeuron<TContextValue, TAxonType extends TCNSAxon = TCNSAxon> = {
+    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>[];
+};
+
+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;
+}
+
+type TCNSModality = {
+    afferentPaths: Record<string | number, TCNSAfferentPath>;
+};
+
+type TCNSNeuronActivationTask<TNeuron extends object = object, TCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
+    neuron: TNeuron;
+    dendriteCollateral: TCollateral;
+    input?: TCNSSignal<TCollateral>;
+};
+
+type TCNSNeuronActivationTaskFailure<TNeuron extends object = object> = {
+    task: TCNSNeuronActivationTask<TNeuron>;
+    error: Error;
+    aborted: boolean;
+};
+
+/**
+ * The public contract of a running stimulation, as seen by consumers (via the
+ * return of `stimulate`/`activate` and `response.stimulation`). The concrete
+ * `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>> {
+    /** Resolves when the run completes; rejects on failed tasks / abort. */
+    waitUntilComplete(): Promise<void>;
+    /** All activation tasks seen this run. */
+    getAllActivationTasks(): TCNSNeuronActivationTask<TNeuron>[];
+    /** Tasks that failed or were aborted. */
+    getFailedTasks(): Array<TCNSNeuronActivationTaskFailure<TNeuron>>;
+    /**
+     * The current outstanding frontier — not-yet-completed tasks (queued, active,
+     * 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:
+ *
+ *   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".
+ */
+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. */
+    pendingActivations: number;
+    /** Activations awaiting an unsettled promise. Non-zero means another drain is coming. */
+    activeActivations: number;
+};
+
+type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}> = {
+    maxNeuronHops?: number;
+    onResponse?: (response: TResponse) => void | Promise<void>;
+    /**
+     * Called once at the end of every synchronous turn - see
+     * {@link TCNSStimulationDrain}. This is the batch boundary for integrations
+     * that commit accumulated writes (state managers, in-memory databases).
+     *
+     * Returns `void` by design: a returned promise is not awaited. There is
+     * nothing to gate on - the next turn is started by someone else's promise
+     * settling, so awaiting here would only delay the callback. For asynchronous
+     * work at a boundary use `onResponse`, which does support promises.
+     *
+     * Re-entrant calls are safe. A nested `stimulate()` is a separate stimulation
+     * and announces its own boundary inline - that is the supported way to react
+     * to a drain. Feeding work back into the *same* stimulation via
+     * `enqueueTasks()` runs it, but folds it into the turn that is already
+     * closing, so it produces no additional boundary of its own.
+     */
+    onDrain?: (drain: TCNSStimulationDrain) => void;
+    abortSignal?: AbortSignal;
+    ctx?: ICNSStimulationContextStore;
+    concurrency?: number;
+    modality?: TCNSModality;
+    afferentPath?: TCNSAfferentPath;
+    stimulationContext?: TStimulationContext;
+};
+
+type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>, TOutputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
+    inputSignal?: TCNSSignal<TInputCollateral>;
+    outputSignal?: TCNSSignal<TOutputCollateral>;
+    modality?: TCNSModality;
+    afferentPath?: TCNSAfferentPath;
+    contextValue: Map<object, unknown>;
+    /**
+     * Every activation this stimulation still owns, in any state:
+     * `pendingActivations + activeActivations`.
+     *
+     * The unit is an activation - one `TCNSNeuronActivationTask`, i.e. one
+     * (neuron, dendrite, signal) triple. A single signal produces one activation
+     * per subscriber of its collateral.
+     *
+     * Active activations are counted deliberately: the queue owns work that has
+     * been handed to a neuron but not finished, the same way an AMQP queue counts
+     * unacknowledged messages in its total. `getAllActivationTasks()` follows the
+     * same model.
+     *
+     * `queueLength === 0` means the stimulation is finished - it is the exact
+     * condition used internally to settle `waitUntilComplete()`, so it holds on
+     * the terminal response and nowhere else.
+     *
+     * NOT a synchronous-batch boundary. A response is emitted when an activation
+     * finishes, but a batch can also end when one *starts* and goes async, and no
+     * response is emitted at that moment. Use `onDrain` for batch boundaries.
+     */
+    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
+     * 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.
+     */
+    pendingActivations: number;
+    /**
+     * Activations whose dendrite body has been invoked and returned a promise
+     * that has not settled.
+     *
+     * A synchronous body passes through this state within a single pump
+     * iteration and is decremented before its response is emitted, so only
+     * genuinely asynchronous activations are ever observed here.
+     */
+    activeActivations: number;
+    stimulation: ICNSStimulation<any, any>;
+    /**
+     * The neuron that produced this response (present on both the success and the
+     * throw path). Enables name-based consumers (persist, devtools) to resolve the
+     * task's neuron reliably — including for sink/failed tasks that have no output
+     * collateral to trace an owner from.
+     */
+    neuron?: TCNSNeuron<any, any>;
+    error?: Error;
+    hops?: number;
+};
+
+type TCNSSubscriber<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any>> = {
+    neuron: TNeuron;
+    dendrite: TDendrite;
+};
+
+/**
+ * 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>> {
+    readonly stronglyConnectedComponents: Set<TNeuron>[];
+    getSCCSetByNeuron(neuron: TNeuron): Set<TNeuron> | undefined;
+    getSccIndexByNeuron(neuron: TNeuron): number | undefined;
+    canNeuronBeGuaranteedDone(neuron: TNeuron, activeSccCounts: Map<number, number>): boolean;
+    getParentNeuronByCollateral(collateral: ICNSCollateral<unknown>): TNeuron | undefined;
+    getDendrites(): TDendrite[];
+    getCollaterals(): ICNSCollateral<unknown>[];
+    getSubscribers(collateral: ICNSCollateral<unknown>): TCNSSubscriber<TNeuron, TDendrite>[];
+}
+
+interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+    options?: TCNSOptions;
+    network: ICNSNetwork<TNeuron, TDendrite>;
+    /**
+     * Add a global response listener applied to all stimulations.
+     * Returns an unsubscribe function.
+     */
+    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.
+     * Returns an unsubscribe function.
+     */
+    addDrainListener(listener: (drain: TCNSStimulationDrain) => void): () => void;
+    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.
+     */
+    activate(tasks: TCNSNeuronActivationTask<TNeuron>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): ICNSStimulation<TNeuron, TDendrite>;
+}
+
+/**
+ * The base `ctx` bag handed to every dendrite handler — nothing app-specific
+ * 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.
+ */
+type TCNSHandlerContextBase<TContextValue> = TCNSLocalContextValueStore<TContextValue> & {
+    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.
+     */
+    stimulationContext?: unknown;
+};
+/**
+ * The `ctx` a dendrite handler receives. `TExt` is whatever the factory layers
+ * poured in (e.g. `withGlobal<T>()` adds `{ global: T }`) — it's a plain
+ * intersection, so layers add exactly what they want and nothing else, and a
+ * base neuron (no layers) gets `TExt = unknown`, i.e. just the base bag.
+ *
+ * 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 TCNSDendrite<TContextValue, 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;
+};
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,345 @@
+type TCNSAfferentPath = {
+    parentAfferentPath?: TCNSAfferentPath;
+};
+
+type TCNSSignal<TCollateral extends ICNSCollateral<unknown>> = {
+    collateral: TCollateral;
+    payload?: TCollateral extends ICNSCollateral<infer P> ? P : never;
+};
+
+interface ICNSCollateral<TPayload> {
+    createSignal(): TCNSSignal<ICNSCollateral<TPayload>>;
+    createSignal(payload: TPayload): TCNSSignal<ICNSCollateral<TPayload>>;
+}
+
+/**
+ * Axon type used by neurons.
+ *
+ * Historically this type only took a collateral name union and a single payload
+ * type, which meant every collateral on the axon was typed with the same
+ * payload (typically a union of all possible payloads).
+ *
+ * That broke property-level typing on `axon.*.createSignal(...)` – the payload
+ * parameter became a big union instead of the specific payload for that
+ * collateral.
+ *
+ * To fix this while keeping existing generic call sites mostly intact, we add
+ * a third type parameter that carries the original heterogeneous axon object.
+ * When that third parameter is provided, we preserve the precise payload type
+ * for each collateral.
+ *
+ * - `TCollateralName` / `TInputPayload` are still useful for higher-level
+ *   generic constraints (unions of names / payloads).
+ * - `TCollaterals` is the concrete axon map used to recover the per-key
+ *   payload types.
+ */
+type TCNSAxon<TCollaterals extends Record<string, ICNSCollateral<unknown>> = Record<string, ICNSCollateral<unknown>>> = {
+    [K in keyof TCollaterals]: TCollaterals[K];
+};
+
+/**
+ * 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 TCNSNeuron<TContextValue, TAxonType extends TCNSAxon = TCNSAxon> = {
+    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>[];
+};
+
+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;
+}
+
+type TCNSModality = {
+    afferentPaths: Record<string | number, TCNSAfferentPath>;
+};
+
+type TCNSNeuronActivationTask<TNeuron extends object = object, TCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
+    neuron: TNeuron;
+    dendriteCollateral: TCollateral;
+    input?: TCNSSignal<TCollateral>;
+};
+
+type TCNSNeuronActivationTaskFailure<TNeuron extends object = object> = {
+    task: TCNSNeuronActivationTask<TNeuron>;
+    error: Error;
+    aborted: boolean;
+};
+
+/**
+ * The public contract of a running stimulation, as seen by consumers (via the
+ * return of `stimulate`/`activate` and `response.stimulation`). The concrete
+ * `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>> {
+    /** Resolves when the run completes; rejects on failed tasks / abort. */
+    waitUntilComplete(): Promise<void>;
+    /** All activation tasks seen this run. */
+    getAllActivationTasks(): TCNSNeuronActivationTask<TNeuron>[];
+    /** Tasks that failed or were aborted. */
+    getFailedTasks(): Array<TCNSNeuronActivationTaskFailure<TNeuron>>;
+    /**
+     * The current outstanding frontier — not-yet-completed tasks (queued, active,
+     * 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:
+ *
+ *   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".
+ */
+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. */
+    pendingActivations: number;
+    /** Activations awaiting an unsettled promise. Non-zero means another drain is coming. */
+    activeActivations: number;
+};
+
+type TCNSStimulationOptions<TResponse, TStimulationContext extends Object = {}> = {
+    maxNeuronHops?: number;
+    onResponse?: (response: TResponse) => void | Promise<void>;
+    /**
+     * Called once at the end of every synchronous turn - see
+     * {@link TCNSStimulationDrain}. This is the batch boundary for integrations
+     * that commit accumulated writes (state managers, in-memory databases).
+     *
+     * Returns `void` by design: a returned promise is not awaited. There is
+     * nothing to gate on - the next turn is started by someone else's promise
+     * settling, so awaiting here would only delay the callback. For asynchronous
+     * work at a boundary use `onResponse`, which does support promises.
+     *
+     * Re-entrant calls are safe. A nested `stimulate()` is a separate stimulation
+     * and announces its own boundary inline - that is the supported way to react
+     * to a drain. Feeding work back into the *same* stimulation via
+     * `enqueueTasks()` runs it, but folds it into the turn that is already
+     * closing, so it produces no additional boundary of its own.
+     */
+    onDrain?: (drain: TCNSStimulationDrain) => void;
+    abortSignal?: AbortSignal;
+    ctx?: ICNSStimulationContextStore;
+    concurrency?: number;
+    modality?: TCNSModality;
+    afferentPath?: TCNSAfferentPath;
+    stimulationContext?: TStimulationContext;
+};
+
+type TCNSStimulationResponse<TInputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>, TOutputCollateral extends ICNSCollateral<unknown> = ICNSCollateral<unknown>> = {
+    inputSignal?: TCNSSignal<TInputCollateral>;
+    outputSignal?: TCNSSignal<TOutputCollateral>;
+    modality?: TCNSModality;
+    afferentPath?: TCNSAfferentPath;
+    contextValue: Map<object, unknown>;
+    /**
+     * Every activation this stimulation still owns, in any state:
+     * `pendingActivations + activeActivations`.
+     *
+     * The unit is an activation - one `TCNSNeuronActivationTask`, i.e. one
+     * (neuron, dendrite, signal) triple. A single signal produces one activation
+     * per subscriber of its collateral.
+     *
+     * Active activations are counted deliberately: the queue owns work that has
+     * been handed to a neuron but not finished, the same way an AMQP queue counts
+     * unacknowledged messages in its total. `getAllActivationTasks()` follows the
+     * same model.
+     *
+     * `queueLength === 0` means the stimulation is finished - it is the exact
+     * condition used internally to settle `waitUntilComplete()`, so it holds on
+     * the terminal response and nowhere else.
+     *
+     * NOT a synchronous-batch boundary. A response is emitted when an activation
+     * finishes, but a batch can also end when one *starts* and goes async, and no
+     * response is emitted at that moment. Use `onDrain` for batch boundaries.
+     */
+    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
+     * 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.
+     */
+    pendingActivations: number;
+    /**
+     * Activations whose dendrite body has been invoked and returned a promise
+     * that has not settled.
+     *
+     * A synchronous body passes through this state within a single pump
+     * iteration and is decremented before its response is emitted, so only
+     * genuinely asynchronous activations are ever observed here.
+     */
+    activeActivations: number;
+    stimulation: ICNSStimulation<any, any>;
+    /**
+     * The neuron that produced this response (present on both the success and the
+     * throw path). Enables name-based consumers (persist, devtools) to resolve the
+     * task's neuron reliably — including for sink/failed tasks that have no output
+     * collateral to trace an owner from.
+     */
+    neuron?: TCNSNeuron<any, any>;
+    error?: Error;
+    hops?: number;
+};
+
+type TCNSSubscriber<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any>> = {
+    neuron: TNeuron;
+    dendrite: TDendrite;
+};
+
+/**
+ * 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>> {
+    readonly stronglyConnectedComponents: Set<TNeuron>[];
+    getSCCSetByNeuron(neuron: TNeuron): Set<TNeuron> | undefined;
+    getSccIndexByNeuron(neuron: TNeuron): number | undefined;
+    canNeuronBeGuaranteedDone(neuron: TNeuron, activeSccCounts: Map<number, number>): boolean;
+    getParentNeuronByCollateral(collateral: ICNSCollateral<unknown>): TNeuron | undefined;
+    getDendrites(): TDendrite[];
+    getCollaterals(): ICNSCollateral<unknown>[];
+    getSubscribers(collateral: ICNSCollateral<unknown>): TCNSSubscriber<TNeuron, TDendrite>[];
+}
+
+interface ICNS<TNeuron extends TCNSNeuron<any, any>, TDendrite extends TCNSDendrite<any, any, any> = TCNSDendrite<any, any, any>> {
+    options?: TCNSOptions;
+    network: ICNSNetwork<TNeuron, TDendrite>;
+    /**
+     * Add a global response listener applied to all stimulations.
+     * Returns an unsubscribe function.
+     */
+    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.
+     * Returns an unsubscribe function.
+     */
+    addDrainListener(listener: (drain: TCNSStimulationDrain) => void): () => void;
+    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.
+     */
+    activate(tasks: TCNSNeuronActivationTask<TNeuron>[], options?: TCNSStimulationOptions<TCNSStimulationResponse>): ICNSStimulation<TNeuron, TDendrite>;
+}
+
+/**
+ * The base `ctx` bag handed to every dendrite handler — nothing app-specific
+ * 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.
+ */
+type TCNSHandlerContextBase<TContextValue> = TCNSLocalContextValueStore<TContextValue> & {
+    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.
+     */
+    stimulationContext?: unknown;
+};
+/**
+ * The `ctx` a dendrite handler receives. `TExt` is whatever the factory layers
+ * poured in (e.g. `withGlobal<T>()` adds `{ global: T }`) — it's a plain
+ * intersection, so layers add exactly what they want and nothing else, and a
+ * base neuron (no layers) gets `TExt = unknown`, i.e. just the base bag.
+ *
+ * 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 TCNSDendrite<TContextValue, 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;
+};
+
+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 };

package/dist/index.js

@@ -0,0 +1,18 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/dist/index.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@cnstra/types",
+  "version": "0.1.0",
+  "description": "Shared TypeScript contract for CNStra: signals, tasks, axons, neuron/collateral/stimulation/network interfaces. Zero runtime — the base package core and integrations build on.",
+  "keywords": ["cnstra", "types", "contract", "interfaces"],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "test:types": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "tsup": "8.5.1",
+    "typescript": "5.7.2"
+  },
+  "author": "Andrei Baikov <abaikov23@gmail.com>",
+  "license": "MIT",
+  "publishConfig": { "access": "public" }
+}