@cnstra/core 1.2.2 → 1.3.1

package/README.md

@@ -9,23 +9,26 @@ You explicitly start a run with `cns.stimulate(...)`; CNStra then performs a **d
 
 > **Zero dependencies:** CNS has no third-party dependencies, making it suitable for any JavaScript/TypeScript environment - browsers, Node.js, serverless, edge functions, React Native, or embedded systems.
 
-> **Not pub/sub:** there are no ambient listeners or global `emit`. Only the **signal you return** from a dendrite continues the traversal; returning `null`/`undefined` ends that branch. `maxHops` guards against cycles.
+> **Not pub/sub:** there are no ambient listeners or global `emit`. Only the **signal you return** from a dendrite continues the traversal; returning `null`/`undefined` ends that branch. Hop limits guard against cycles.
 
 ## 🏗️ Core Model
 
 ### Neurons
 Units of logic with clear DI and sharp boundaries:
 - **ID** — unique name
-- **Axon** — the neuron’s **output channels** (its collaterals)
+- **Axon** — the neuron's **output channels** (its collaterals)  
 - **Dendrites** — **input receptors** (typed reactions bound to specific collaterals)
 
 ### Collaterals
 Typed **output channels** that mint signals:
 - **ID** — string identifier (e.g., `'user:created'`)
 - **Payload** — the shape carried by the signal
-- `createSignal(payload)` → `{ type, payload }`
+- `createSignal(payload)` → `{ collateral, payload }`
 
-> **Afferent axon:** the object of collaterals you expose publicly. Its **keys** (e.g., `userCreated`) are what you pass to `cns.stimulate(...)`, not the string IDs.
+### Signals
+The data structures that flow through the system:
+- **collateral** — reference to the collateral that created this signal
+- **payload** — the typed data being transmitted
 
 ## 🚀 Quick Start
 
@@ -64,10 +67,10 @@ const userService = neuron('user-service', {
 const cns = new CNS([userService]);
 
 // Stimulate the system
-await cns.stimulate(userCreated, {
+await cns.stimulate(userCreated.createSignal({
   id: '123',
   name: 'John Doe'
-});
+}));
 ```
 
 ## 📚 API Reference
@@ -113,58 +116,76 @@ The main orchestrator that manages signal flow between neurons.
 
 #### Constructor
 ```typescript
-new CNS(neurons)
+new CNS(neurons, options?)
 ```
 
 **Parameters:**
 - `neurons`: Array of neurons that process signals
+- `options`: Optional CNS configuration
 
 #### `stimulate()` Method
 ```typescript
-cns.stimulate(collateral, payload, options?)
+cns.stimulate(signal, options?)
 ```
 
 **Parameters:**
-- `collateral`: The collateral instance to trigger
-- `payload`: Signal payload data
-- `options`: Optional configuration object
+- `signal`: A signal created by `collateral.createSignal(payload)`
+- `options`: Optional stimulation configuration
+
+**Returns:** `Promise<void>` that resolves when stimulation completes
+
+**Example:**
+```typescript
+await cns.stimulate(
+  userCreated.createSignal({ id: '123', name: 'John' })
+);
+```
+
+## ⚙️ Stimulation Options
 
-**Options:**
+### `maxNeuronHops?: number` (default: 1000)
+Prevents infinite loops by limiting signal traversal depth.
 
-##### `maxHops?: number` (default: 1000)
-Prevents infinite loops by limiting signal traversal depth. Each signal hop increments the counter.
 ```typescript
-// Prevent runaway recursion
-cns.stimulate(input, data, {
-  maxHops: 50 // Stop after 50 signal hops
+await cns.stimulate(signal, {
+  maxNeuronHops: 50 // Stop after 50 neuron hops
 });
 ```
-⚠️ **Memory Impact**: Higher values allow deeper graphs but increase memory usage.
 
-##### `onTrace?: (trace) => void`
-Real-time callback for monitoring signal flow, errors, and completion. Essential for fire-and-forget pattern.
+### `onResponse?: (response) => void`
+Real-time callback for monitoring signal flow and completion.
+
 ```typescript
-cns.stimulate(input, data, {
-  onTrace: (trace) => {
-    console.log(`Signal: ${trace.collateralId}, Hops: ${trace.hops}`);
+await cns.stimulate(signal, {
+  onResponse: (response) => {
+    console.log(`Signal: ${response.outputSignal?.collateral.id}`);
+    console.log(`Hops: ${response.hops}`);
     
-    if (trace.error) {
-      console.error('Processing failed:', trace.error);
+    if (response.error) {
+      console.error('Processing failed:', response.error);
     }
     
-    if (trace.queueLength === 0) {
+    if (response.queueLength === 0) {
       console.log('Stimulation completed');
     }
   }
 });
 ```
 
-##### `abortSignal?: AbortSignal`
-Gracefully stop stimulation using AbortController. Already-running operations complete, but no new work starts.
+**Response Object:**
+- `outputSignal` — The signal being processed (if any)
+- `hops` — Number of neuron hops taken so far
+- `queueLength` — Remaining signals in processing queue (0 = complete)
+- `error` — Any error that occurred during processing
+- `stimulationId` — Unique identifier for this stimulation
+
+### `abortSignal?: AbortSignal`
+Gracefully stop stimulation using AbortController.
+
 ```typescript
 const controller = new AbortController();
 
-cns.stimulate(input, data, {
+cns.stimulate(signal, {
   abortSignal: controller.signal
 });
 
@@ -172,632 +193,296 @@ cns.stimulate(input, data, {
 setTimeout(() => controller.abort(), 5000);
 ```
 
-##### `ctx?: ICNSStimulationContextStore`
-Provide existing context store for recovery/retry scenarios. Restores neuron state from previous stimulation.
+### `stimulationId?: string`
+Custom identifier for this stimulation cascade. Auto-generated if not provided.
+
 ```typescript
-// Retry with preserved context
-cns.stimulate(failedCollateral, payload, {
-  ctx: savedContextStore, // Restore previous state
-  onTrace: (trace) => { /* monitor retry */ }
+await cns.stimulate(signal, {
+  stimulationId: 'user-action-' + Date.now()
 });
 ```
 
-##### `createContextStore?: () => ICNSStimulationContextStore`
-Factory for custom context store implementations. Useful for persistence, encryption, or specialized storage.
+### `allowType?: (collateralId: string) => boolean`
+Filter which collateral types can be processed.
+
 ```typescript
-cns.stimulate(input, data, {
-  createContextStore: () => new RedisContextStore('session-123'),
-  onTrace: (trace) => {
-    // trace.contextStore is your custom RedisContextStore
-  }
+await cns.stimulate(signal, {
+  allowType: (type) => type.startsWith('user:') // Only process user-related signals
 });
 ```
 
-##### `spikeId?: string`
-Custom identifier for this stimulation cascade. Auto-generated if not provided. Useful for debugging and correlation.
+### `concurrency?: number` (default: unlimited)
+Limit concurrent operations to prevent resource exhaustion.
+
 ```typescript
-cns.stimulate(input, data, {
-  spikeId: 'user-action-' + Date.now(),
-  onTrace: (trace) => {
-    console.log('Spike ID:', trace.spikeId);
-  }
+await cns.stimulate(signal, {
+  concurrency: 10 // Max 10 operations at once
 });
 ```
 
-##### `allowType?: (collateralId: string) => boolean`
-Filter which collateral types can be processed. Useful for selective stimulation or debugging specific paths.
+### `ctx?: ICNSStimulationContextStore`
+Provide existing context store for recovery/retry scenarios.
+
 ```typescript
-cns.stimulate(input, data, {
-  allowType: (type) => type.startsWith('user:'), // Only process user-related signals
-  onTrace: (trace) => {
-    // Only user: collaterals will appear in traces
-  }
+await cns.stimulate(signal, {
+  ctx: savedContextStore // Restore previous state
 });
 ```
 
-##### `concurrency?: number` (default: unlimited)
-Limit concurrent operations to prevent resource exhaustion. Both sync and async operations count toward this limit.
+### `createContextStore?: () => ICNSStimulationContextStore`
+Factory for custom context store implementations.
+
 ```typescript
-cns.stimulate(input, data, {
-  concurrency: 10, // Max 10 operations at once
-  onTrace: (trace) => {
-    // Processing respects concurrency limit
-  }
+await cns.stimulate(signal, {
+  createContextStore: () => new CustomContextStore()
 });
 ```
 
-**Why These Options Matter:**
-- **Control**: Fine-tune behavior for your specific use case
-- **Performance**: Manage memory and concurrency based on system constraints  
-- **Reliability**: Implement timeouts, retries, and error recovery
-- **Debugging**: Filter signals, add correlation IDs, and monitor execution
-- **Integration**: Work with existing systems via custom context stores
-
-## 🧠 Memory Policy & Error Handling
-
-### Memory-First Design
-CNS is designed with strict memory efficiency and universal compatibility in mind:
-
-- **Zero dependencies**: No third-party packages - runs in any JavaScript/TypeScript environment
-- **No error storage**: Errors are immediately passed to your `onTrace` callback and not stored in memory
-- **Streaming traces**: Signal traces are delivered via callbacks, not accumulated in arrays
-- **Context on-demand**: Context stores are created only when needed and passed via traces
-- **No global state**: The system maintains no persistent state between stimulations
-- **Context scope**: Context stores exist only for the duration of a single stimulation - they are automatically cleaned up when stimulation completes
-- **Context content warning**: ⚠️ Context values dictionary is kept in memory during stimulation - store minimal data only (IDs, counters, flags) rather than large objects or payloads
-- **Context mutation**: CNS modifies context dictionaries in-place - create new context objects if you need versioning or rollback capabilities
-
-### maxHops Memory Impact
-⚠️ **Warning**: Using `maxHops` parameter increases memory consumption proportionally:
-- Default hop limit: 1000
-- Higher `maxHops` = more potential concurrent signals = more memory usage
-- For infinite recursion scenarios, keep `maxHops` reasonable (100-1000 range)
-
-### Error Handling Philosophy
-CNS handles errors through immediate callback delivery rather than storage because:
-1. **Memory efficiency**: No error accumulation in library memory
-2. **Real-time feedback**: Immediate error notification to your application
-3. **Recovery control**: You decide how to handle and store errors
-4. **Context preservation**: Error traces include full context for recovery scenarios
+## 🔄 Signal Flow Patterns
+
+### Basic Chain Processing
 
 ```typescript
-// Error handling example
-cns.stimulate(input, payload, {
-  onTrace: (trace) => {
-    if (trace.error) {
-      // Handle immediately - error won't be stored by CNS
-      logError(trace.error);
-      saveErrorContext(trace.contextStore);
-    }
+const input = collateral<{ value: number }>('input');
+const middle = collateral<{ doubled: number }>('middle');
+const output = collateral<{ result: string }>('output');
+
+const step1 = neuron('step1', { middle }).dendrite({
+  collateral: input,
+  response: (payload, axon) => {
+    return axon.middle.createSignal({ doubled: payload.value * 2 });
   }
 });
 
-// ✅ Good: Minimal context data
-const goodContext = { 
-  retryCount: 3, 
-  userId: "123", 
-  lastAttempt: Date.now() 
-};
-
-// ❌ Bad: Large objects in context
-const badContext = { 
-  fullUserProfile: largeUserObject,
-  historicalData: massiveArray,
-  fileBuffer: binaryData
-};
-```
+const step2 = neuron('step2', { output }).dendrite({
+  collateral: middle,
+  response: (payload, axon) => {
+    return axon.output.createSignal({ result: `Final: ${payload.doubled}` });
+  }
+});
+
+const cns = new CNS([step1, step2]);
 
-## 🔄 Key Behavior
+await cns.stimulate(input.createSignal({ value: 5 }));
+// Flows: input(5) → middle(10) → output("Final: 10")
+```
 
-### Sync-First Processing with Async Support
-CNS processes signals synchronously by default, avoiding microtask scheduling until absolutely necessary. This provides predictable, immediate execution for synchronous operations while seamlessly handling async when needed.
+### Fan-out Processing
 
-**Synchronous Path** - No async/await overhead:
 ```typescript
-const syncNeuron = neuron('sync-processor', { output })
-  .dendrite({
-    collateral: input,
-    response: (payload, axon) => {
-      // Pure synchronous processing - runs immediately
-      // No Promise creation, no microtask scheduling
-      const result = processSync(payload);
-      return axon.output.createSignal({ result });
-    }
-  });
+const trigger = collateral<{ data: string }>('trigger');
+const branch1 = collateral<{ result: string }>('branch1');
+const branch2 = collateral<{ result: string }>('branch2');
 
-// Chain of sync neurons executes immediately in single tick
-const chainStart = collateral<{ value: number }>('start');
-const chainMiddle = collateral<{ doubled: number }>('middle');  
-const chainEnd = collateral<{ final: string }>('end');
+const processor1 = neuron('proc1', { branch1 }).dendrite({
+  collateral: trigger,
+  response: (payload, axon) => {
+    return axon.branch1.createSignal({ result: `A-${payload.data}` });
+  }
+});
 
-const step1 = neuron('step1', { chainMiddle })
-  .dendrite({
-    collateral: chainStart,
-    response: (payload, axon) => {
-      return axon.chainMiddle.createSignal({ doubled: payload.value * 2 });
-    }
-  });
+const processor2 = neuron('proc2', { branch2 }).dendrite({
+  collateral: trigger,
+  response: (payload, axon) => {
+    return axon.branch2.createSignal({ result: `B-${payload.data}` });
+  }
+});
 
-const step2 = neuron('step2', { chainEnd })
-  .dendrite({
-    collateral: chainMiddle,
-    response: (payload, axon) => {
-      return axon.chainEnd.createSignal({ final: `Result: ${payload.doubled}` });
-    }
-  });
+const cns = new CNS([processor1, processor2]);
 
-// This entire chain executes synchronously in one tick
-cns.stimulate(chainStart, { value: 5 });
+await cns.stimulate(trigger.createSignal({ data: 'test' }));
+// Flows: trigger("test") → [branch1("A-test"), branch2("B-test")]
 ```
 
-**Mixed Sync/Async** - Async only where needed:
+### Context-Aware Processing
+
 ```typescript
-const mixedNeuron = neuron('mixed-processor', { output })
+import { withCtx } from '@cnstra/core';
+
+const input = collateral<{ increment: number }>('input');
+const output = collateral<{ count: number }>('output');
+
+const counter = withCtx<{ total: number }>()
+  .neuron('counter', { output })
   .dendrite({
     collateral: input,
-    response: async (payload, axon) => {
-      // Synchronous preprocessing - runs immediately
-      const validated = validateInput(payload);
-      const transformed = transformData(validated);
+    response: async (payload, axon, ctx) => {
+      const current = ctx.get()?.total || 0;
+      const newTotal = current + payload.increment;
       
-      // Only here do we enter async context
-      const result = await fetchFromAPI(transformed);
+      ctx.set({ total: newTotal });
       
-      // Synchronous postprocessing
-      const formatted = formatResult(result);
-      return axon.output.createSignal({ formatted });
+      return axon.output.createSignal({ count: newTotal });
     }
   });
+
+const cns = new CNS([counter]);
+
+await cns.stimulate(input.createSignal({ increment: 5 })); // count: 5
+await cns.stimulate(input.createSignal({ increment: 3 })); // count: 8 (separate context)
 ```
 
-**Key Performance Benefits:**
-- **Sync chains execute in single tick**: No microtask delays between neurons
-- **Minimal Promise overhead**: Async context created only when needed
-- **Predictable execution**: Sync operations complete before any async work starts
-- **No unnecessary await**: Sync neurons don't use async/await syntax
+## 🧠 Memory & Performance
 
-### Isolated Stimulation Scope
-Each `cns.stimulate()` call creates an isolated signal cascade. You never need to worry about "messageId" or signal correlation - all signals in your trace belong exclusively to your stimulation.
+### Memory-Efficient Design
+- **Zero dependencies**: No third-party packages
+- **No error storage**: Errors delivered via callbacks, not stored
+- **Streaming responses**: Signal traces delivered via callbacks
+- **Context on-demand**: Context stores created only when needed
+- **No global state**: Clean slate between stimulations
 
-#### Complex Orchestration Example: Card & Deck Creation
+### Performance Characteristics
+- **Sync-first**: Synchronous chains execute in single tick
+- **Minimal async overhead**: Promises created only when needed
+- **Stack-safe**: Handles deep chains without stack overflow
+- **Bounded execution**: `maxNeuronHops` prevents runaway processing
 
-```typescript
-// Define collaterals for the orchestration
-const httpRequest = collateral<{ cardText: string }>('http:request');
-const requestProcessed = collateral<{ cardText: string }>('request:processed');
-const deckCreated = collateral<{ deckId: string; cardText: string }>('deck:created');
-const cardCreated = collateral<{ cardId: string; deckId: string }>('card:created');
-
-// Controller neuron: orchestrates the entire process
-const controllerNeuron = withCtx<{
-  cardText?: string;
-  deckId?: string;
-  cardId?: string;
-}>().neuron('controller', { requestProcessed, cardCreated })
-  .dendrite({
-    collateral: httpRequest,
-    response: async (payload, axon, ctx) => {
-      // Step 1: Store card text in context and signal processing started
-      ctx.set({ cardText: payload.cardText });
-      return axon.requestProcessed.createSignal({ cardText: payload.cardText });
-    }
-  })
-  .dendrite({
-    collateral: deckCreated,
-    response: async (payload, axon, ctx) => {
-      // Step 3: Deck created, now create the card
-      const context = ctx.get()!;
-      ctx.set({ ...context, deckId: payload.deckId });
-      return axon.cardCreated.createSignal({
-        deckId: payload.deckId,
-        cardText: context.cardText!
-      });
-    }
-  });
+### Best Practices
+- Keep context data minimal (IDs, counters, flags)
+- Use synchronous responses when possible
+- Set reasonable `maxNeuronHops` limits
+- Implement proper error handling in `onResponse`
 
-// Deck service: creates deck when request is processed
-const deckNeuron = neuron('deck-service', { deckCreated })
-  .dendrite({
-    collateral: requestProcessed,
-    response: async (payload, axon) => {
-      // Step 2: Create deck (async operation)
-      const deckId = await createDeck();
-      return axon.deckCreated.createSignal({
-        deckId,
-        cardText: payload.cardText
-      });
-    }
-  });
+## 🎯 Common Use Cases
 
-// Card service: creates card when deck is ready
-const cardNeuron = neuron('card-service', { cardCreated })
-  .dendrite({
-    collateral: cardCreated,
-    response: async (payload, axon) => {
-      // Step 4: Create card (async operation)  
-      const cardId = await createCard(payload.deckId, payload.cardText);
-      return axon.cardCreated.createSignal({
-        cardId,
-        deckId: payload.deckId
-      });
-    }
-  });
+### HTTP Request Processing
+```typescript
+const httpRequest = collateral<{ method: string; url: string }>('http:request');
+const requestValidated = collateral<{ method: string; url: string }>('request:validated');
+const responseReady = collateral<{ status: number; body: any }>('response:ready');
 
-// HTTP handler using CNS orchestration
-app.post('/create-card', async (req, res) => {
-  const cns = new CNS([controllerNeuron, deckNeuron, cardNeuron]);
-  
-  let deckId: string | undefined;
-  let cardId: string | undefined;
-  
-  cns.stimulate(httpRequest, { cardText: req.body.text }, {
-    onTrace: (trace) => {
-      // Collect results as they become available
-      if (trace.collateralId === 'deck:created') {
-        deckId = (trace.payload as any).deckId;
-      }
-      if (trace.collateralId === 'card:created') {
-        cardId = (trace.payload as any).cardId;
-      }
-      
-      // Process complete when queue is empty
-      if (trace.queueLength === 0) {
-        res.json({ deckId, cardId, success: true });
-      }
+const validator = neuron('validator', { requestValidated }).dendrite({
+  collateral: httpRequest,
+  response: (payload, axon) => {
+    if (!payload.url.startsWith('https://')) {
+      throw new Error('Only HTTPS URLs allowed');
     }
-  });
+    return axon.requestValidated.createSignal(payload);
+  }
 });
-```
-
-**Key Benefits of Isolated Stimulation:**
-
-1. **No Signal Pollution**: Every signal in your trace belongs to your request - no cross-contamination
-2. **No Correlation IDs**: No need to track "messageId" or "requestId" through the system
-3. **Guaranteed Ordering**: Signals process in deterministic order within your stimulation
-4. **Clean Scoping**: Each HTTP request gets its own isolated signal cascade
-5. **Context Safety**: Context store is private to your stimulation - no shared state issues
 
-### Only Returned Signals Are Processed
-**Important**: In CNS, only the signal returned from the `reaction` function is processed and propagated to other neurons. Signals created with `axon.collateral.createSignal()` but not returned are NOT processed by the system.
-
-```typescript
-const processor = neuron('processor', {
-  output: outputCollateral
-})
-.dendrite({
-  collateral: inputCollateral,
+const handler = neuron('handler', { responseReady }).dendrite({
+  collateral: requestValidated,
   response: async (payload, axon) => {
-    // This signal is created but NOT processed
-    axon.output.createSignal({ message: 'Hello' });
-    
-    // Only this returned signal is processed
-    return axon.output.createSignal({ message: 'World' });
+    const response = await fetch(payload.url, { method: payload.method });
+    const body = await response.json();
+    return axon.responseReady.createSignal({ status: response.status, body });
   }
 });
-```
-
-### Multiple Neurons on Same Collateral
-Multiple neurons can listen to the same collateral:
 
-```typescript
-const emailService = neuron('email-service', { emailSent })
-  .dendrite({
-    collateral: userCreated,
-    response: (payload, axon) => {
-      return axon.emailSent.createSignal({ to: 'user@example.com' });
-    }
-  });
-
-const notificationService = neuron('notification-service', { notificationSent })
-  .dendrite({
-    collateral: userCreated,
-    response: (payload, axon) => {
-      return axon.notificationSent.createSignal({ message: 'User created' });
-    }
-  });
-
-// Both neurons will process the userCreated signal
-const cns = new CNS([emailService, notificationService]);
+const cns = new CNS([validator, handler]);
 ```
 
-### Conditional Logic
+### Event Sourcing
 ```typescript
-const router = neuron('router', {
-  success: successCollateral,
-  error: errorCollateral
-})
-.dendrite({
-  collateral: requestCollateral,
+const eventReceived = collateral<{ type: string; data: any }>('event:received');
+const eventStored = collateral<{ eventId: string }>('event:stored');
+const stateUpdated = collateral<{ aggregateId: string }>('state:updated');
+
+const eventStore = neuron('event-store', { eventStored }).dendrite({
+  collateral: eventReceived,
   response: async (payload, axon) => {
-    try {
-      const result = await processRequest(payload);
-      return axon.success.createSignal(result);
-    } catch (error) {
-      return axon.error.createSignal({ error: error.message });
-    }
+    const eventId = await saveEvent(payload);
+    return axon.eventStored.createSignal({ eventId });
   }
 });
-```
-
-### Context Management
 
-Neurons can maintain local state using the context parameter:
+const stateManager = neuron('state-manager', { stateUpdated }).dendrite({
+  collateral: eventStored,
+  response: async (payload, axon) => {
+    const aggregateId = await updateState(payload.eventId);
+    return axon.stateUpdated.createSignal({ aggregateId });
+  }
+});
 
-```typescript
-const statefulNeuron = withCtx().neuron('stateful', { output: outputCollateral })
-  .dendrite({
-    collateral: inputCollateral,
-    response: (payload, axon, ctx) => {
-      // Get current state
-      const currentState = ctx.get();
-      
-      // Update state
-      ctx.set({ count: (currentState?.count || 0) + 1 });
-      
-      return axon.output.createSignal({ count: ctx.get()?.count });
-    }
-  });
+const cns = new CNS([eventStore, stateManager]);
 ```
 
-### Context-Based Retry Mechanisms
+## 🚨 Error Handling
 
-CNS supports robust retry mechanisms using context stores to maintain state across stimulation attempts. This is particularly useful for handling transient failures:
+Errors are delivered immediately via `onResponse` callbacks:
 
-#### Stateful Retry Pattern
 ```typescript
-type RetryContext = {
-  tryNumber: number;
-};
-
-const retryableNeuron = withCtx<RetryContext>().neuron('retryable', { output })
-  .dendrite({
-    collateral: input,
-    response: async (payload, axon, ctx) => {
-      const current = ctx.get() || { tryNumber: 0 };
-      const tryNumber = current.tryNumber + 1;
+await cns.stimulate(signal, {
+  onResponse: (response) => {
+    if (response.error) {
+      console.error(`Error in neuron processing:`, response.error);
       
-      // Update context with incremented try number
-      ctx.set({ tryNumber });
-
-      if (tryNumber === 1) {
-        // First attempt: simulate failure
-        throw new Error('Transient failure');
-      } else {
-        // Second attempt: succeed
-        return axon.output.createSignal({
-          result: `Success on try ${tryNumber}`,
-          payload
-        });
-      }
-    }
-  });
-```
-
-#### Retry Orchestration
-```typescript
-let contextStore: ICNSStimulationContextStore | undefined;
-
-const handleStimulation = (isRetry = false) => {
-  cns.stimulate(input, payload, {
-    ctx: contextStore, // Use preserved context for retries
-    onTrace: (trace) => {
-      // Detect stimulation end
-      if (trace.queueLength === 0) {
-        if (trace.error && !isRetry) {
-          // Capture context and retry
-          contextStore = trace.contextStore;
-          setTimeout(() => handleStimulation(true), 100);
-        } else if (!trace.error && trace.collateralId === 'output') {
-          // Success - process result
-          console.log('Retry succeeded:', trace.payload);
-        }
-      }
-    }
-  });
-};
-
-handleStimulation();
-```
-
-#### Context Versioning for Selective Recovery
-Since CNS modifies the context dictionary in-place, you can create new context objects for version control and selective recovery:
-
-```typescript
-// Create context snapshots for version control
-const createContextSnapshot = (store: ICNSStimulationContextStore) => {
-  const snapshot = new CNSStimulationContextStore();
-  snapshot.setAll(store.getAll());
-  return snapshot;
-};
-
-const retryWithVersionControl = () => {
-  let preFailureContext: ICNSStimulationContextStore | undefined;
-  
-  cns.stimulate(input, payload, {
-    onTrace: (trace) => {
-      // Save context before potential failure points
-      if (trace.collateralId === 'risky-operation') {
-        preFailureContext = createContextSnapshot(trace.contextStore);
-      }
+      // Log error details
+      console.error(`Signal: ${response.outputSignal?.collateral.id}`);
+      console.error(`Stimulation: ${response.stimulationId}`);
       
-      if (trace.queueLength === 0 && trace.error) {
-        // Option 1: Retry with context from just before failure
-        // (excludes the failed step's context changes)
-        cns.stimulate(failedCollateral, payload, {
-          ctx: preFailureContext,
-          onTrace: (retryTrace) => { /* handle retry */ }
-        });
-        
-        // Option 2: Retry with full context including failed step
-        // (useful when failure was transient, not logic error)
-        cns.stimulate(failedCollateral, payload, {
-          ctx: trace.contextStore,
-          onTrace: (retryTrace) => { /* handle retry */ }
-        });
+      // Handle specific error types
+      if (response.error instanceof ValidationError) {
+        handleValidationError(response.error);
       }
     }
-  });
-};
+  }
+});
 ```
 
-### State Recovery and Restart
-
-CNS provides built-in support for recovering from failures and restarting operations. The `onTrace` callback includes the current context state, allowing you to:
-
-1. **Capture context on failure**: When an error occurs, the trace contains the complete context state
-2. **Restart with preserved context**: Use the saved context to restore neuron states
-3. **Resume from failure point**: Continue processing from where it left off
-4. **Implement retry logic**: Context preserves attempt counts and other stateful retry data
-
+**Error Recovery with Context:**
 ```typescript
-// Example: Advanced recovery with persistence
-let savedContextStore: ICNSStimulationContextStore | undefined;
-
-cns.stimulate(input, payload, {
-  onTrace: (trace) => {
-    if (trace.queueLength === 0) {
-      if (trace.error) {
-        // Failure: save context for recovery
-        savedContextStore = trace.contextStore;
-        await persistContextToStorage(trace.contextStore.getAll());
-        console.log('Context saved for recovery');
-      }
+let savedContext: ICNSStimulationContextStore | undefined;
+
+await cns.stimulate(signal, {
+  onResponse: (response) => {
+    if (response.error) {
+      // Save context for retry
+      savedContext = response.contextStore;
     }
   }
 });
 
-// Recovery from persistent storage
-const restoreAndRetry = async () => {
-  const persistedState = await loadContextFromStorage();
-  const contextStore = createContextStore();
-  contextStore.setAll(persistedState);
-  
-  cns.stimulate(failedCollateral, originalPayload, {
-    ctx: contextStore, // Restore full state
-    onTrace: (trace) => {
-      // Monitor recovery attempt
-    }
+// Retry with preserved context
+if (savedContext) {
+  await cns.stimulate(retrySignal, {
+    ctx: savedContext
   });
-};
+}
 ```
 
-**Custom Context Store Implementations**: You can create your own context store implementations by implementing the `ICNSStimulationContextStore` interface:
+## 🔧 Advanced Configuration
 
+### Custom Context Store
 ```typescript
-import { ICNSStimulationContextStore } from '@cnstra/core';
-
-// Example: Redis-backed context store for distributed systems
 class RedisContextStore implements ICNSStimulationContextStore {
-  constructor(private redis: RedisClient, private keyPrefix: string) {}
-
-  get(key: string): unknown {
-    // Synchronous get - consider caching for performance
-    return this.redis.getSync(`${this.keyPrefix}:${key}`);
-  }
-
-  set(key: string, value: unknown): void {
-    this.redis.set(`${this.keyPrefix}:${key}`, JSON.stringify(value));
-  }
-
-  getAll(): Record<string, unknown> {
-    const keys = this.redis.keys(`${this.keyPrefix}:*`);
-    const result: Record<string, unknown> = {};
-    for (const key of keys) {
-      const shortKey = key.replace(`${this.keyPrefix}:`, '');
-      result[shortKey] = JSON.parse(this.redis.getSync(key));
-    }
-    return result;
-  }
-
-  setAll(values: Record<string, unknown>): void {
-    for (const [key, value] of Object.entries(values)) {
-      this.set(key, value);
-    }
-  }
-}
-
-// Example: Immutable context store for versioning
-class ImmutableContextStore implements ICNSStimulationContextStore {
-  private data: Record<string, unknown> = {};
-  private version = 0;
-
-  get(key: string): unknown {
-    return this.data[key];
-  }
-
-  set(key: string, value: unknown): void {
-    // Create new instance instead of mutating
-    this.data = { ...this.data, [key]: value };
-    this.version++;
-  }
-
-  getAll(): Record<string, unknown> {
-    return { ...this.data }; // Return copy
-  }
-
-  setAll(values: Record<string, unknown>): void {
-    this.data = { ...values };
-    this.version++;
+  constructor(private client: RedisClient, private sessionId: string) {}
+  
+  get<T>(): T | undefined {
+    // Implement Redis-backed context retrieval
   }
-
-  getVersion(): number {
-    return this.version;
+  
+  set<T>(value: T): void {
+    // Implement Redis-backed context storage
   }
 }
 
-// Usage with custom context store
-cns.stimulate(input, payload, {
-  createContextStore: () => new RedisContextStore(redisClient, 'session-123'),
-  onTrace: (trace) => {
-    // trace.contextStore is your custom RedisContextStore
-    console.log('Using Redis-backed context');
-  }
+await cns.stimulate(signal, {
+  createContextStore: () => new RedisContextStore(redisClient, 'session-123')
 });
 ```
 
-**Context Store Interface**:
+### CNS Configuration
 ```typescript
-interface ICNSStimulationContextStore {
-  get(key: string): unknown;
-  set(key: string, value: unknown): void;
-  getAll(): Record<string, unknown>;
-  setAll(values: Record<string, unknown>): void;
-}
-```
-
-**Custom Store Use Cases**:
-- **Persistence**: Redis, database, or file-based storage
-- **Distribution**: Share context across multiple CNS instances
-- **Immutability**: Version-controlled context for advanced debugging
-- **Encryption**: Secure sensitive context data
-- **Compression**: Optimize memory usage for large context objects
-- **Auditing**: Log all context changes for compliance
-
-## 🧪 Testing
-
-```bash
-npm test
-npm run test:types
-```
-
-## 📦 Build
-
-```bash
-npm run build
+const cns = new CNS(neurons, {
+  autoCleanupContexts: true, // Auto-cleanup unused contexts
+  defaultConcurrency: 50     // Default concurrency limit
+});
 ```
 
-## 🚀 Examples
-
-Run the examples to see CNS in action:
-
-```bash
-npm run examples
-```
+⚠️ **Performance Warning**: `autoCleanupContexts` adds computational overhead due to:
+- **O(V²) initialization cost** - building SCC (Strongly Connected Components) structures
+- **O(1 + A) runtime cost** per cleanup check (where A = number of SCC ancestors)
+- **Memory overhead** for storing SCC graphs and ancestor relationships
 
-## 🤝 Contributing
+**Use only when:**
+- Memory leaks are a critical issue
+- You have a small to medium-sized neuron graph (< 1000 neurons)
+- Performance is less critical than memory management
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+**For production systems**, consider manual context cleanup or custom cleanup strategies instead.
 
-## 📄 License
+---
 
-MIT
+*CNStra provides deterministic, type-safe orchestration without the complexity of traditional event systems. Build reliable, maintainable reactive applications with clear data flow and predictable behavior.*