@emmvish/stable-request 2.8.4 → 3.0.0

package/README.md

@@ -1,2520 +1,1354 @@
 # @emmvish/stable-request
 
-A stability-first production-grade TypeScript framework for resilient API integrations, batch processing, and orchestrating complex workflows with deterministic error handling, type safety, and comprehensive observability.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Core Concepts](#core-concepts)
-- [Core Modules](#core-modules)
-  - [stableRequest](#stablerequest)
-  - [stableFunction](#stablefunction)
-  - [stableApiGateway](#stableapigateway)
-  - [stableWorkflow](#stableworkflow)
-  - [stableWorkflowGraph](#stableworkflowgraph)
-  - [StableScheduler](#stablescheduler)
-  - [StableBuffer](#stablebuffer)
-- [Stable Runner](#stable-runner)
-- [Resilience Mechanisms](#resilience-mechanisms)
-  - [Retry Strategies](#retry-strategies)
-  - [Circuit Breaker](#circuit-breaker)
-  - [Caching](#caching)
-  - [Rate Limiting](#rate-limiting)
-  - [Concurrency Limiting](#concurrency-limiting)
-- [Workflow Patterns](#workflow-patterns)
-  - [Sequential & Concurrent Phases](#sequential--concurrent-phases)
-  - [Non-Linear Workflows](#non-linear-workflows)
-  - [Branched Workflows](#branched-workflows)
-- [Graph-based Workflow Patterns](#graph-based-workflow-patterns)
-  - [Graph-Based Workflows with Mixed Items](#graph-based-workflows-with-mixed-items)
-  - [Parallel Phase Execution](#parallel-phase-execution)
-  - [Merge Points](#merge-points)
-  - [Linear Helper](#linear-helper)
-  - [Branch Racing in Graphs](#branch-racing-in-graphs)
-- [Configuration & State](#configuration--state)
-  - [Config Cascading](#config-cascading)
-  - [Shared & State Buffers](#shared--state-buffers)
-- [Hooks & Observability](#hooks--observability)
-  - [Pre-Execution Hooks](#pre-execution-hooks)
-  - [Analysis Hooks](#analysis-hooks)
-  - [Handler Hooks](#handler-hooks)
-  - [Decision Hooks](#decision-hooks)
-  - [Metrics & Logging](#metrics--logging)
-- [Advanced Features](#advanced-features)
-  - [Trial Mode](#trial-mode)
-  - [State Persistence](#state-persistence)
-  - [Mixed Request & Function Phases](#mixed-request--function-phases)
-- [Best Practices](#best-practices)
+> ⚠️ **Maintenance Mode Notice**: This library is now in maintenance mode. For the full-featured execution engine with workflows, schedulers, API gateways, and more, please use [**stable-infra**](https://npmjs.com/package/@emmvish/stable-infra) - the natural evolution of stable-request. If you wish to continue using stable-request for workflows / gateway / scheduling, then, refer to its docs in version 2.8.5.
 
----
+A resilient HTTP request framework for Node.js with built-in intelligent retry strategies, circuit breakers, caching, state persistence, and comprehensive observability. 
+I created this framework when I was integrating with **unreliable, flaky APIs** and needed a simple solution for retrying the requests. While such libraries do exist already, I needed something more... an intelligent, fully customizable and stable framework that would not throw errors randomly, but rather, give me only the most important information on why my requests were failing or succeeding, with metrics and type-safety.
 
-## Overview
+## 🚀 Try stable-infra Instead
 
-**@emmvish/stable-request** evolved from a focused library for resilient API calls to a comprehensive execution framework. Originally addressing **API integration** challenges via `stableRequest`, it expanded to include:
+**stable-request** has evolved into **stable-infra** - a complete execution infrastructure that includes:
 
-1. **Batch orchestration** via `stableApiGateway` for processing groups of mixed requests/functions
-2. **Phased workflows** via `stableWorkflow` for array-based multi-phase execution with dynamic control flow
-3. **Graph-based workflows** via `stableWorkflowGraph` for DAG execution with higher parallelism
-4. **Generic function execution** via `stableFunction`, inheriting all resilience guards
-5. **Queue based scheduling** via `StableScheduler`, with option to preserve scheduler state and recover from saved state
-6. **Transactional shared state** via `StableBuffer`, a concurrency-safe buffer you can pass as `commonBuffer` or `sharedBuffer`
+- Everything in `stable-request` and more updates
+- `stableWorkflow` - Multi-phase workflow orchestration with branching
+- `stableApiGateway` - Batch request execution with grouping
+- `stableFunction` - Resilient function execution with retries
+- `stableWorkflowGraph` - DAG-based workflow execution
+- `StableScheduler` - Job scheduling with cron, intervals, and timestamps
+- `StableBuffer` - A safe shared-state buffer for all the stable modules
+- `stableRunner` - CLI runner for all execution types
 
-All seven core modules support the same resilience stack: retries, jitter, circuit breaking, caching, rate/concurrency limits, config cascading, shared buffers, trial mode, comprehensive hooks, and metrics. This uniformity makes it trivial to compose requests and functions in any topology. Finally, `Stable Runner` executes jobs from config.
+**[Get started with stable-infra →](https://npmjs.com/package/@emmvish/stable-infra)**
 
 ---
 
-## Core Concepts
+## Installation
 
-### Resilience as Default
+```bash
+npm install stable-request
+```
 
-Every execution—whether a single request, a pure function, or an entire workflow—inherits built-in resilience:
+## Why stable-request?
 
-- **Retries** with configurable backoff strategies (FIXED, LINEAR, EXPONENTIAL)
-- **Jitter** to prevent thundering herd
-- **Circuit breaker** to fail fast and protect downstream systems
-- **Caching** for idempotent read operations
-- **Rate & concurrency limits** to respect external constraints
-- **Metrics guardrails** to validate execution against thresholds with automatic anomaly detection
+Traditional retry libraries blindly retry on network failures or non-2xx HTTP status codes. But in the real world, **HTTP 200 doesn't always mean success**:
 
-### Type Safety
+- ✅ An API returns `200 OK` with `{ "status": "pending" }` - you need to retry until it's `"completed"`
+- ✅ A payment gateway returns `200 OK` but the transaction is still processing
+- ✅ A search API returns `200 OK` with empty results due to eventual consistency
+- ✅ An external API returns `200 OK` with `{ "error": "rate_limited" }` in the body
+- ✅ You need to validate response data against business rules before accepting it
 
-All examples in this guide use TypeScript generics for type-safe request/response data and function arguments/returns. Analyzers validate shapes at runtime; TypeScript ensures compile-time safety.
+**stable-request** lets you inject business intelligence into every stage of the request lifecycle through **hooks** - making your HTTP requests truly resilient to both infrastructure and business-level failures.
 
-### Config Cascading
+## Features
 
-Global defaults → group overrides → phase overrides → branch overrides → item overrides. Lower levels always win, preventing repetition while maintaining expressiveness.
+### 🔄 Configurable Retry Strategies
 
-### Shared State
+Automatically retry failed requests with customizable backoff strategies:
 
-Workflows and gateways support `sharedBuffer` for passing computed state across phases/branches/items without global state.
+```typescript
+import { stableRequest, RETRY_STRATEGIES, REQUEST_METHODS } from 'stable-request';
+import type { STABLE_REQUEST_RESULT } from 'stable-request';
 
----
+interface ApiResponse {
+  data: string[];
+  total: number;
+}
+
+(async () => {
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: {
+      hostname: 'api.example.com',
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    attempts: 5,
+    wait: 1000,
+    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,  // FIXED, LINEAR, or EXPONENTIAL
+    jitter: 0.2,  // Add ±20% randomness to delays
+    maxAllowedWait: 30000  // Cap maximum wait time
+  });
 
-## Core Modules
+  if (result.success) {
+    console.log('Data:', result.data);
+  }
+})();
+```
 
-### stableRequest
+### ⚡ Circuit Breaker Pattern
 
-Single API call with resilience, type-safe request and response types.
+Protect your services from cascading failures:
 
 ```typescript
-import { stableRequest, REQUEST_METHODS, VALID_REQUEST_PROTOCOLS } from '@emmvish/stable-request';
+import { stableRequest, REQUEST_METHODS } from 'stable-request';
+import type { STABLE_REQUEST_RESULT, CircuitBreakerConfig } from 'stable-request';
 
-interface GetUserRequest {
-  // Empty for GET requests with no body
+interface ApiResponse {
+  status: string;
 }
 
-interface User {
-  id: number;
-  name: string;
-}
+(async () => {
+  const circuitBreakerConfig: CircuitBreakerConfig = {
+    failureThresholdPercentage: 50,  // Open circuit at 50% failure rate
+    minimumRequests: 10,              // Minimum requests before evaluation
+    recoveryTimeoutMs: 30000,         // Time before attempting recovery
+    halfOpenMaxRequests: 5,           // Requests allowed in half-open state
+    trackIndividualAttempts: true     // Track each retry attempt
+  };
+
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    circuitBreaker: circuitBreakerConfig
+  });
+})();
+```
 
-const result = await stableRequest<GetUserRequest, User>({
-  reqData: {
-    method: REQUEST_METHODS.GET,
-    protocol: VALID_REQUEST_PROTOCOLS.HTTPS,
-    hostname: 'api.example.com',
-    path: '/users/1'
-  },
-  resReq: true,
-  attempts: 3,
-  wait: 500,
-  jitter: 100,
-  cache: { enabled: true, ttl: 5000 },
-  rateLimit: { maxRequests: 10, windowMs: 1000 },
-  maxConcurrentRequests: 5,
-  responseAnalyzer: ({ data }) => {
-    return typeof data === 'object' && data !== null && 'id' in data;
-  },
-  handleSuccessfulAttemptData: ({ successfulAttemptData }) => {
-    console.log(`User loaded: ${successfulAttemptData.data.name}`);
-  }
-});
+### 💾 Intelligent Response Caching
 
-if (result.success) {
-  console.log(result.data.name, result.metrics.totalAttempts);
-} else {
-  console.error(result.error);
+Cache responses with full HTTP cache-control support:
+
+```typescript
+import { stableRequest, REQUEST_METHODS } from 'stable-request';
+import type { STABLE_REQUEST_RESULT, CacheConfig } from 'stable-request';
+
+interface ApiResponse {
+  items: { id: number; name: string }[];
 }
-```
 
-**Key responsibilities:**
-- Execute a single HTTP request with automatic retry and backoff
-- Validate response shape via analyzer; retry if invalid
-- Cache successful responses with TTL
-- Apply rate and concurrency limits
-- Throw or gracefully suppress errors via finalErrorAnalyzer
-- Collect attempt metrics and infra dashboards (circuit breaker, cache, rate limiter state)
+(async () => {
+  const cacheConfig: CacheConfig = {
+    enabled: true,
+    ttl: 300000,               // 5 minutes default TTL
+    maxSize: 100,              // Maximum cache entries
+    respectCacheControl: true, // Honor HTTP cache headers
+    cacheableStatusCodes: [200, 203, 204, 206, 300, 301],
+    excludeMethods: [REQUEST_METHODS.POST, REQUEST_METHODS.PUT, REQUEST_METHODS.PATCH, REQUEST_METHODS.DELETE]
+  };
+
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    cache: cacheConfig
+  });
+})();
+```
 
-### stableFunction
+### 🔒 StableBuffer - Thread-Safe State Management
 
-Generic async/sync function execution with identical resilience.
+Manage shared state safely across concurrent operations:
 
 ```typescript
-import { stableFunction, RETRY_STRATEGIES } from '@emmvish/stable-request';
-
-type ComputeArgs = [number, number];
-type ComputeResult = number;
-
-const multiply = (a: number, b: number) => a * b;
-
-const result = await stableFunction<ComputeArgs, ComputeResult>({
-  fn: multiply,
-  args: [5, 3],
-  returnResult: true,
-  attempts: 2,
-  wait: 100,
-  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-  responseAnalyzer: ({ data }) => data > 0,
-  cache: { enabled: true, ttl: 10000 }
-});
+import { StableBuffer } from 'stable-request';
+import type { StableBufferOptions, StableBufferTransactionLog, StableBufferState } from 'stable-request';
 
-if (result.success) {
-  console.log('Result:', result.data); // 15
+interface BufferState extends StableBufferState {
+  counter: number;
+  items: { id: number; timestamp: number }[];
 }
-```
 
-**Key responsibilities:**
-- Execute any async or sync function with typed arguments and return
-- Support argument-based cache key generation
-- Retry on error or analyzer rejection
-- Enforce success criteria via analyzer
-- Optionally suppress exceptions
+(async () => {
+  const bufferOptions: StableBufferOptions = {
+    initialState: { counter: 0, items: [] } as BufferState,
+    transactionTimeoutMs: 5000,
+    logTransaction: async (log: StableBufferTransactionLog): Promise<void> => {
+      // Persist transaction logs for replay/audit
+      await saveToDatabase(log);
+    }
+  };
+
+  const buffer = new StableBuffer(bufferOptions);
+
+  // Safe concurrent updates
+  await buffer.run(async (state): Promise<void> => {
+    const typedState = state as BufferState;
+    typedState.counter += 1;
+    typedState.items.push({ id: typedState.counter, timestamp: Date.now() });
+  });
+
+  // Read state (returns a clone)
+  const currentState = buffer.read() as BufferState;
+})();
+```
 
-### stableApiGateway
+### 📜 Transaction Logs & State Replay
 
-Batch orchestration of mixed requests and functions.
+Replay transactions for recovery or auditing:
 
 ```typescript
-import {
-  stableApiGateway,
-  REQUEST_METHODS,
-  VALID_REQUEST_PROTOCOLS,
-  RequestOrFunction
-} from '@emmvish/stable-request';
-import type { API_GATEWAY_ITEM } from '@emmvish/stable-request';
-
-// Define request types
-interface ApiRequestData {
-  filters?: Record<string, any>;
+import { replayStableBufferTransactions } from 'stable-request';
+import type { StableBufferTransactionLog, StableBufferReplayResult, StableBufferReplayHandler } from 'stable-request';
+
+interface OrderState {
+  orders: string[];
+  inventory: Record<string, number>;
 }
 
-interface ApiResponse {
-  id: number;
-  value: string;
+interface OrderHookParams {
+  orderId: string;
 }
 
-// Define function types
-type TransformArgs = [ApiResponse[], number];
-type TransformResult = {
-  transformed: ApiResponse[];
-  count: number;
-};
+interface InventoryHookParams {
+  sku: string;
+  quantity: number;
+}
 
-type ValidateArgs = [TransformResult];
-type ValidateResult = boolean;
+(async () => {
+  // Load saved transaction logs
+  const logs: StableBufferTransactionLog[] = await loadTransactionLogsFromDB();
 
-const items: API_GATEWAY_ITEM<ApiRequestData, ApiResponse, TransformArgs | ValidateArgs, TransformResult | ValidateResult>[] = [
-  {
-    type: RequestOrFunction.REQUEST,
-    request: {
-      id: 'fetch-data',
-      requestOptions: {
-        reqData: {
-          method: REQUEST_METHODS.GET,
-          protocol: VALID_REQUEST_PROTOCOLS.HTTPS,
-          hostname: 'api.example.com',
-          path: '/data'
-        },
-        resReq: true,
-        attempts: 3
-      }
-    }
-  },
-  {
-    type: RequestOrFunction.FUNCTION,
-    function: {
-      id: 'transform-data',
-      functionOptions: {
-        fn: (data: ApiResponse[], threshold: number): TransformResult => ({
-          transformed: data.filter(item => item.id > threshold),
-          count: data.length
-        }),
-        args: [[], 10] as TransformArgs,
-        returnResult: true,
-        attempts: 2,
-        cache: { enabled: true, ttl: 5000 }
-      }
-    }
-  },
-  {
-    type: RequestOrFunction.FUNCTION,
-    function: {
-      id: 'validate-result',
-      functionOptions: {
-        fn: (result: TransformResult): ValidateResult => result.count > 0,
-        args: [{ transformed: [], count: 0 }] as ValidateArgs,
-        returnResult: true
-      }
+  // Define replay handlers
+  const handlers: Record<string, StableBufferReplayHandler> = {
+    'processOrder': async (state, log): Promise<void> => {
+      const typedState = state as OrderState;
+      const params = log.hookParams as OrderHookParams;
+      typedState.orders.push(params.orderId);
+    },
+    'updateInventory': async (state, log): Promise<void> => {
+      const typedState = state as OrderState;
+      const params = log.hookParams as InventoryHookParams;
+      typedState.inventory[params.sku] -= params.quantity;
     }
-  }
-];
-
-const responses = await stableApiGateway<ApiRequestData, ApiResponse>(items, {
-  concurrentExecution: true,
-  stopOnFirstError: false,
-  sharedBuffer: {},
-  commonAttempts: 2,
-  commonWait: 300,
-  maxConcurrentRequests: 3
-});
+  };
 
-// Access individual responses
-responses.forEach((resp, i) => {
-  console.log(`Item ${i}: success=${resp.success}`);
-});
+  // Replay with custom handlers
+  const result: StableBufferReplayResult = await replayStableBufferTransactions({
+    logs,
+    handlers,
+    initialState: { orders: [], inventory: {} } as OrderState,
+    dedupe: true,     // Skip duplicate transactions
+    sort: true        // Order by timestamp
+  });
 
-// Access aggregate metrics
-console.log(`Success rate: ${responses.metrics.successRate.toFixed(2)}%`);
-console.log(`Execution time: ${responses.metrics.executionTime}ms`);
-console.log(`Throughput: ${responses.metrics.throughput.toFixed(2)} req/s`);
-console.log(`Average duration: ${responses.metrics.averageRequestDuration.toFixed(2)}ms`);
+  console.log('Replayed state:', result.buffer.read() as OrderState);
+})();
 ```
 
-#### Request/Function Racing
+### 💾 State Persistence
 
-Enable racing to accept the first successful request or function and cancel others, useful for redundant API calls or failover scenarios.
+Persist and restore state across executions:
 
 ```typescript
-const responses = await stableApiGateway(items, {
-  concurrentExecution: true,
-  enableRacing: true, // First successful item wins, others cancelled
-  maxConcurrentRequests: 10
-});
+import { stableRequest, StableBuffer, PersistenceStage, REQUEST_METHODS } from 'stable-request';
+import type { STABLE_REQUEST_RESULT, StatePersistenceConfig, StatePersistenceOptions } from 'stable-request';
 
-// responses contains only the winning result
-// Losing items marked as cancelled with appropriate error
-```
+interface ApiResponse {
+  data: string;
+}
+
+interface BufferState {
+  lastFetched: string | null;
+}
 
-**Key responsibilities:**
-- Execute a batch of requests and functions concurrently or sequentially
-- Apply global, group-level, and item-level config overrides
-- Maintain shared buffer across items for state passing
-- Stop on first error or continue despite failures
-- Collect per-item and aggregate metrics (success rates, execution time, throughput)
-- Support request grouping with group-specific config
-- Track infrastructure metrics (circuit breaker, cache, rate limiter, concurrency)
+(async () => {
+  const buffer = new StableBuffer({
+    initialState: { lastFetched: null } as BufferState
+  });
+
+  const statePersistence: StatePersistenceConfig = {
+    persistenceFunction: async (options: StatePersistenceOptions): Promise<Record<string, any>> => {
+      const { executionContext, buffer, persistenceStage } = options;
+      if (persistenceStage === PersistenceStage.BEFORE_HOOK) {
+        return await loadStateFromDB(executionContext);
+      } else {
+        await saveStateToDB(executionContext, buffer);
+        return buffer;
+      }
+    },
+    loadBeforeHooks: true,
+    storeAfterHooks: true
+  };
 
-### stableWorkflow
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    commonBuffer: buffer,
+    statePersistence
+  });
+})();
+```
 
-Phased array-based workflows with sequential/concurrent phases, mixed items, and non-linear control flow.
+### 🪝 Lifecycle Hooks
 
-You can start a workflow from a specific phase using `startPhaseIndex` (0-based). When starting inside a concurrent group (`markConcurrentPhase`), execution aligns to the group’s first phase.
+Tap into every stage of request execution:
 
 ```typescript
-import { stableWorkflow, PHASE_DECISION_ACTIONS, RequestOrFunction, REQUEST_METHODS } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE, API_GATEWAY_ITEM } from '@emmvish/stable-request';
-
-// Define types for requests
-interface FetchRequestData {}
-interface FetchResponse {
-  users: Array<{ id: number; name: string }>;
-  posts: Array<{ id: number; title: string }>;
-}
+import { stableRequest, REQUEST_METHODS } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  STABLE_REQUEST,
+  PreExecutionHookOptions,
+  ResponseAnalysisHookOptions,
+  HandleErrorHookOptions,
+  HandleSuccessfulAttemptDataHookOptions,
+  FinalErrorAnalysisHookOptions
+} from 'stable-request';
 
-// Define types for functions
-type ProcessArgs = [FetchResponse];
-type ProcessResult = {
-  merged: Array<{ userId: number; userName: string; postTitle: string }>;
-};
-
-type AuditArgs = [ProcessResult, string];
-type AuditResult = { logged: boolean; timestamp: string };
+interface ApiResponse {
+  status: 'success' | 'pending' | 'failed';
+  data?: unknown;
+}
 
-const phases: STABLE_WORKFLOW_PHASE<FetchRequestData, FetchResponse, ProcessArgs | AuditArgs, ProcessResult | AuditResult>[] = [
-  {
-    id: 'fetch-data',
-    requests: [
-      {
-        id: 'get-users-posts',
-        requestOptions: {
+(async () => {
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,  // Return response data
+    
+    // Pre-execution hook
+    preExecution: {
+      preExecutionHook: async (options: PreExecutionHookOptions<void, ApiResponse>): Promise<Partial<STABLE_REQUEST<void, ApiResponse>>> => {
+        const { inputParams, commonBuffer, stableRequestOptions } = options;
+        // Modify options before execution
+        return { 
           reqData: {
-            hostname: 'api.example.com',
-            path: '/users-and-posts'
-          },
-          resReq: true,
-          attempts: 3
-        }
-      }
-    ]
-  },
-  {
-    id: 'process-and-audit',
-    markConcurrentPhase: true,
-    items: [
-      {
-        type: RequestOrFunction.FUNCTION,
-        function: {
-          id: 'process-data',
-          functionOptions: {
-            fn: (data: FetchResponse): ProcessResult => ({
-              merged: data.users.map((user, idx) => ({
-                userId: user.id,
-                userName: user.name,
-                postTitle: data.posts[idx]?.title || 'No post'
-              }))
-            }),
-            args: [{ users: [], posts: [] }] as ProcessArgs,
-            returnResult: true
+            ...stableRequestOptions.reqData,
+            headers: { 'X-Custom': 'value' }
           }
-        }
+        };
       },
-      {
-        type: RequestOrFunction.FUNCTION,
-        function: {
-          id: 'audit-processing',
-          functionOptions: {
-            fn: async (result: ProcessResult, auditId: string): Promise<AuditResult> => {
-              console.log(`Audit ${auditId}:`, result);
-              return { logged: true, timestamp: new Date().toISOString() };
-            },
-            args: [{ merged: [] }, 'audit-123'] as AuditArgs,
-            returnResult: true
-          }
-        }
-      }
-    ],
-    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
-      if (!phaseResult.success) {
-        return { action: PHASE_DECISION_ACTIONS.TERMINATE };
-      }
-      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
+      applyPreExecutionConfigOverride: true
+    },
+    
+    // Response validation
+    responseAnalyzer: async (options: ResponseAnalysisHookOptions<void, ApiResponse>): Promise<boolean> => {
+      const { data, trialMode, commonBuffer } = options;
+      return data.status === 'success';  // Return true if response is valid
+    },
+    
+    // Error handling
+    logAllErrors: true,
+    handleErrors: async (options: HandleErrorHookOptions<void>): Promise<void> => {
+      const { reqData, errorLog, commonBuffer } = options;
+      await logToMonitoring(errorLog);
+    },
+    
+    // Success tracking
+    logAllSuccessfulAttempts: true,
+    handleSuccessfulAttemptData: async (options: HandleSuccessfulAttemptDataHookOptions<void, ApiResponse>): Promise<void> => {
+      const { successfulAttemptData } = options;
+      await trackMetric('request_success', successfulAttemptData);
+    },
+    
+    // Final error analysis
+    finalErrorAnalyzer: async (options: FinalErrorAnalysisHookOptions<void>): Promise<boolean> => {
+      const { error, commonBuffer } = options;
+      return error.message.includes('temporary');  // Return true if handled
     }
-  },
-  {
-    id: 'finalize',
-    requests: [
-      {
-        id: 'store-result',
-        requestOptions: {
-          reqData: {
-            hostname: 'api.example.com',
-            path: '/store',
-            method: REQUEST_METHODS.POST
-          },
-          resReq: false
-        }
-      }
-    ]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'data-pipeline',
-  concurrentPhaseExecution: false, // Phases sequential
-  enableNonLinearExecution: true,
-  sharedBuffer: { userId: '123' },
-  commonAttempts: 2,
-  commonWait: 200,
-  handlePhaseCompletion: ({ phaseResult, workflowId }) => {
-    console.log(`Phase ${phaseResult.phaseId} complete in workflow ${workflowId}`);
-  }
-});
+  });
+})();
+```
+
+---
 
-console.log(`Workflow succeeded: ${result.success}, phases: ${result.totalPhases}`);
+## 🎣 Hook Reference
+
+stable-request provides **5 hooks** that let you inject business logic into the request lifecycle. Each hook serves a specific purpose and receives contextual information to make intelligent decisions.
+
+### Hook Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         stableRequest() called                          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│  1. preExecutionHook                                                    │
+│     • Modify request config, inject auth tokens, validate inputs        │
+│     • Can override any stableRequest option                             │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │      Execute HTTP Request     │
+                    │        (attempt 1 of N)       │
+                    └───────────────────────────────┘
+                           │               │
+                     Success (2xx)    Network/HTTP Error
+                           │               │
+                           ▼               ▼
+┌──────────────────────────────────┐  ┌─────────────────────────────────────┐
+│  2. responseAnalyzer             │  │  3. handleErrors                    │
+│     • Validate business logic    │  │     • Log error, alert, track       │
+│     • Return false = retry       │  │     • Called for each failed attempt│
+└──────────────────────────────────┘  └─────────────────────────────────────┘
+         │           │                              │
+    Return true  Return false                       │
+    (valid)      (invalid = retry)                  │
+         │           │                              │
+         │           └──────────────────────────────┤
+         │                                          │
+         ▼                                          ▼
+┌──────────────────────────────────┐     ┌─────────────────────────────────┐
+│  4. handleSuccessfulAttemptData  │     │  (Retry with backoff if         │
+│     • Track successful attempts  │     │   attempts remaining)            │
+│     • Audit logging              │     └─────────────────────────────────┘
+└──────────────────────────────────┘                │
+         │                                          │
+         │                         All attempts exhausted
+         │                                          │
+         ▼                                          ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Return Result                              │
+│                                    │                                    │
+│                    ┌───────────────┴───────────────┐                    │
+│               success: true                   success: false            │
+│                                                    │                    │
+│                                                    ▼                    │
+│                              ┌─────────────────────────────────────┐    │
+│                              │  5. finalErrorAnalyzer              │    │
+│                              │     • Analyze final failure         │    │
+│                              │     • Determine if error is fatal   │    │
+│                              │     • Control throwOnFailedError    │    │
+│                              └─────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────────────────┘
 ```
 
-**Key responsibilities:**
-- Execute phases sequentially or concurrently
-- Support mixed requests and functions per phase
-- Enable non-linear flow (CONTINUE, SKIP, REPLAY, JUMP, TERMINATE)
-- Maintain shared buffer across all phases
-- Apply phase-level and request-level config cascading
-- Support branching with parallel/sequential branches
-- Collect per-phase metrics and workflow aggregates
+---
 
-### stableWorkflowGraph
+### 1. `preExecutionHook` - Pre-Request Setup
 
-DAG-based execution for higher parallelism and explicit phase dependencies.
+Called **once** before any attempt is made. Use it to modify request configuration, inject dynamic values, or validate preconditions.
 
 ```typescript
-import { stableWorkflowGraph, WorkflowGraphBuilder } from '@emmvish/stable-request';
-
-const graph = new WorkflowGraphBuilder()
-  .addPhase('fetch-posts', {
-    requests: [{
-      id: 'get-posts',
-      requestOptions: {
-        reqData: { hostname: 'api.example.com', path: '/posts' },
-        resReq: true
-      }
-    }]
-  })
-  .addPhase('fetch-users', {
-    requests: [{
-      id: 'get-users',
-      requestOptions: {
-        reqData: { hostname: 'api.example.com', path: '/users' },
-        resReq: true
-      }
-    }]
-  })
-  .addParallelGroup('fetch-all', ['fetch-posts', 'fetch-users'])
-  .addPhase('aggregate', {
-    functions: [{
-      id: 'combine',
-      functionOptions: {
-        fn: () => ({ posts: [], users: [] }),
-        args: [],
-        returnResult: true
-      }
-    }]
-  })
-  .addMergePoint('sync', ['fetch-all'])
-  .connectSequence('fetch-all', 'sync', 'aggregate')
-  .setEntryPoint('fetch-all')
-  .build();
-
-const result = await stableWorkflowGraph(graph, {
-  workflowId: 'data-aggregation'
-});
+import { stableRequest, REQUEST_METHODS } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  STABLE_REQUEST,
+  PreExecutionHookOptions,
+  RequestPreExecutionOptions
+} from 'stable-request';
 
-console.log(`Graph workflow success: ${result.success}`);
-```
+interface OrderRequest {
+  productId: string;
+  quantity: number;
+}
 
-**Key responsibilities:**
-- Define phases as DAG nodes with explicit dependency edges
-- Execute independent phases in parallel automatically
-- Support parallel groups, merge points, and conditional routing
-- Validate graph structure (cycle detection, reachability, orphan detection)
-- Provide deterministic execution order
-- Offer higher parallelism than phased workflows for complex topologies
+interface OrderResponse {
+  orderId: string;
+  status: string;
+}
+
+(async () => {
+  const preExecutionConfig: RequestPreExecutionOptions<OrderRequest, OrderResponse> = {
+    preExecutionHook: async (options: PreExecutionHookOptions<OrderRequest, OrderResponse>): Promise<Partial<STABLE_REQUEST<OrderRequest, OrderResponse>>> => {
+      const { inputParams, commonBuffer, stableRequestOptions, transactionLogs } = options;
+      
+      // Inject fresh auth token
+      const token: string = await getAuthToken();
+      
+      // Validate business preconditions
+      if (!commonBuffer?.userId) {
+        throw new Error('User ID required');
+      }
+      
+      // Return partial config to merge (if applyPreExecutionConfigOverride is true)
+      return {
+        reqData: {
+          ...stableRequestOptions.reqData,
+          headers: {
+            ...stableRequestOptions.reqData.headers,
+            'Authorization': `Bearer ${token}`,
+            'X-User-Id': commonBuffer.userId
+          }
+        }
+      };
+    },
+    preExecutionHookParams: { customData: 'value' },  // Passed as inputParams
+    applyPreExecutionConfigOverride: true,             // Merge returned config
+    continueOnPreExecutionHookFailure: false           // Fail fast if hook throws
+  };
+
+  const result: STABLE_REQUEST_RESULT<OrderResponse> = await stableRequest<OrderRequest, OrderResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/orders',
+      method: REQUEST_METHODS.POST
+    },
+    resReq: true,
+    preExecution: preExecutionConfig
+  });
+})();
+```
 
-### StableScheduler
+**💡 Use cases:**
+- Inject fresh authentication tokens
+- Add request signing/HMAC
+- Validate preconditions before making the request
+- Dynamically modify endpoints based on state
+- Load configuration from external sources
 
-Queue-based scheduler for cron/interval/timestamp execution with concurrency limits and recoverable state via custom persistence handlers.
+---
 
-**Key responsibilities:**
-- Enforce max-parallel job execution
-- Schedule jobs with cron, interval, or timestamp(s)
-- Persist and restore scheduler state via user-provided handlers
+### 2. `responseAnalyzer` - Business Logic Validation
 
-### StableBuffer
+Called after **each successful HTTP response** (2xx status). This is where you validate that the response meets your business requirements.
 
-Transactional, concurrency-safe shared state. It’s opt-in: pass a `StableBuffer` instance as `commonBuffer` or `sharedBuffer` to serialize updates across concurrent executions.
+> **Key insight:** Return `true` if the response is acceptable, `false` to trigger a retry.
 
-Key features:
-- Serialized transactions via FIFO queue
-- Snapshot reads with `read()`
-- Optional transaction timeouts
-- Optional transaction logging with `logTransaction`
+```typescript
+import { stableRequest, StableBuffer, REQUEST_METHODS, RETRY_STRATEGIES } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  ResponseAnalysisHookOptions,
+  HookParams
+} from 'stable-request';
 
-```ts
-import { StableBuffer } from '@emmvish/stable-request';
+interface PaymentRequest {
+  cardToken: string;
+  amount: number;
+}
 
-const buffer = new StableBuffer({
-  initialState: { counter: 0 },
-  transactionTimeoutMs: 500,
-  logTransaction: (log) => {
-    // persist log.transactionId, log.activity, log.hookName, log.stateBefore, log.stateAfter
-  }
-});
+interface PaymentResponse {
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  transactionId?: string;
+  receiptUrl?: string;
+  amount?: number;
+  error?: string;
+  errorCode?: string;
+}
 
-await buffer.run(
-  (state) => { state.counter += 1; },
-  { activity: 'workflow-phase', hookName: 'phase-1', workflowId: 'wf-1' }
-);
+(async () => {
+  // Create buffer to track state across retries
+  const buffer = new StableBuffer({
+    initialState: { expectedAmount: 100, transactionId: null }
+  });
+
+  const hookParams: HookParams = {
+    responseAnalyzerParams: { expectedStatus: 'completed' }  // Passed as params
+  };
+
+  const result: STABLE_REQUEST_RESULT<PaymentResponse> = await stableRequest<PaymentRequest, PaymentResponse>({
+    reqData: { 
+      hostname: 'payment.api.com', 
+      path: '/charge',
+      method: REQUEST_METHODS.POST,
+      body: { cardToken: 'tok_xxx', amount: 100 }
+    },
+    resReq: true,  // Must be true to receive response data
+    attempts: 5,
+    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+    commonBuffer: buffer,
+    
+    responseAnalyzer: async (options: ResponseAnalysisHookOptions<PaymentRequest, PaymentResponse>): Promise<boolean> => {
+      const { reqData, data, trialMode, params, commonBuffer, executionContext } = options;
+      
+      // Example 1: Wait for async processing to complete
+      if (data.status === 'pending' || data.status === 'processing') {
+        console.log('Payment still processing, will retry...');
+        return false;  // Retry
+      }
+      
+      // Example 2: Validate response has required data
+      if (!data.transactionId || !data.receiptUrl) {
+        console.log('Incomplete response, will retry...');
+        return false;  // Retry
+      }
+      
+      // Example 3: Check for soft errors in response body
+      if (data.error || data.errorCode) {
+        console.log(`Soft error: ${data.errorCode}, will retry...`);
+        return false;  // Retry
+      }
+      
+      // Example 4: Validate against business rules
+      if (data.amount !== commonBuffer?.expectedAmount) {
+        console.log('Amount mismatch, will retry...');
+        return false;  // Retry
+      }
+      
+      // Success - accept this response
+      if (commonBuffer) {
+        commonBuffer.transactionId = data.transactionId;
+      }
+      return true;
+    },
+    
+    hookParams
+  });
+})();
 ```
 
-Replay utility (transaction logs → deterministic state replay):
+**💡 Use cases:**
+- Poll until async operation completes (`status: pending` → `status: completed`)
+- Validate response data integrity
+- Check for soft errors in response body (APIs that return 200 with error payloads)
+- Ensure eventual consistency (retry until data propagates)
+- Validate business invariants
 
-```ts
-import { replayStableBufferTransactions } from '@emmvish/stable-request';
+---
 
-const replay = await replayStableBufferTransactions({
-  logs, // StableBufferTransactionLog[]
-  handlers: {
-    'phase-1': (state) => { state.counter += 1; }
-  },
-  initialState: { counter: 0 }
-});
+### 3. `handleErrors` - Error Observation & Logging
 
-console.log(replay.buffer.getState());
-```
+Called after **each failed attempt** (network error, non-2xx status, or `responseAnalyzer` returning `false`). Use for observability - this hook doesn't affect retry behavior.
 
----
+> **Note:** Only called when `logAllErrors: true`
 
-## Stable Runner
+```typescript
+import { stableRequest, StableBuffer, REQUEST_METHODS, RETRY_STRATEGIES } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  HandleErrorHookOptions,
+  ERROR_LOG,
+  HookParams
+} from 'stable-request';
 
-Config-driven runner that executes core module jobs from JSON/ESM configs and can use StableScheduler for scheduled jobs.
+interface ApiResponse {
+  data: unknown;
+}
 
----
+interface ErrorHistoryEntry {
+  timestamp: string;
+  attempt: string;
+  error: string;
+  statusCode: number;
+}
 
-## Resilience Mechanisms
+(async () => {
+  // Create buffer to track errors
+  const buffer = new StableBuffer({
+    initialState: { errorHistory: [] as ErrorHistoryEntry[] }
+  });
+
+  const hookParams: HookParams = {
+    handleErrorsParams: { alertChannel: '#api-errors' }
+  };
+
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    attempts: 3,
+    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+    logAllErrors: true,  // Required to trigger handleErrors
+    commonBuffer: buffer,
+    
+    handleErrors: async (options: HandleErrorHookOptions<void>): Promise<void> => {
+      const { reqData, errorLog, maxSerializableChars, params, commonBuffer, executionContext } = options;
+      
+      // errorLog contains detailed error information
+      const { timestamp, attempt, error, type, isRetryable, executionTime, statusCode }: ERROR_LOG = errorLog;
+      
+      // Log to monitoring system
+      await sendToDatadog({
+        level: 'error',
+        message: error,
+        tags: {
+          attempt,
+          statusCode,
+          isRetryable,
+          workflowId: executionContext?.workflowId,
+          requestId: executionContext?.requestId
+        },
+        executionTime
+      });
+      
+      // Track in shared buffer for analysis
+      if (commonBuffer) {
+        commonBuffer.errorHistory = commonBuffer.errorHistory || [];
+        commonBuffer.errorHistory.push({
+          timestamp,
+          attempt,
+          error,
+          statusCode
+        });
+      }
+      
+      // Alert on specific error types
+      if (statusCode === 503) {
+        await sendSlackAlert(`Service unavailable: ${reqData.url}`);
+      }
+    },
+    
+    hookParams
+  });
+})();
+```
+
+**Error Log Structure:**
+```typescript
+interface ERROR_LOG {
+  timestamp: string;      // ISO timestamp of the error
+  attempt: string;        // e.g., "2/5" (attempt 2 of 5)
+  error: string;          // Error message
+  type: 'HTTP_ERROR' | 'INVALID_CONTENT';  // HTTP error or responseAnalyzer rejection
+  isRetryable: boolean;   // Whether this error qualifies for retry
+  executionTime: number;  // Time taken for this attempt (ms)
+  statusCode: number;     // HTTP status code (0 for network errors)
+}
+```
 
-### Execution Timeouts
+**💡 Use cases:**
+- Send errors to monitoring (Datadog, New Relic, Sentry)
+- Track error patterns for circuit breaker decisions
+- Alert on specific error types
+- Build error history for debugging
+- Audit logging
 
-Set maximum execution time for functions to prevent indefinite hangs. Timeouts are enforced at multiple levels with proper inheritance.
+---
 
-You can also set a **workflow/gateway-level `maxTimeout`** to cap total execution time (applies to `stableWorkflow`, `stableWorkflowGraph`, and `stableApiGateway`).
+### 4. `handleSuccessfulAttemptData` - Success Observation
 
-#### Function-Level Timeout
+Called after **each successful attempt** (HTTP 2xx + `responseAnalyzer` returns `true`). Use for observability and tracking.
 
-Set timeout directly on a function:
+> **Note:** Only called when `logAllSuccessfulAttempts: true`. Most useful with `performAllAttempts: true` for polling scenarios.
 
 ```typescript
-import { stableFunction } from '@emmvish/stable-request';
-
-const result = await stableFunction({
-  fn: async () => {
-    // Long-running operation
-    await processLargeDataset();
-    return 'success';
-  },
-  args: [],
-  returnResult: true,
-  executionTimeout: 5000, // 5 seconds max
-  attempts: 3,
-});
+import { stableRequest, StableBuffer, REQUEST_METHODS, RETRY_STRATEGIES } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  HandleSuccessfulAttemptDataHookOptions,
+  SUCCESSFUL_ATTEMPT_DATA
+} from 'stable-request';
 
-if (!result.success && result.error?.includes('timeout')) {
-  console.log('Function timed out');
+interface HealthResponse {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  uptime: number;
 }
-```
 
-#### Gateway-Level Timeout
+interface ResponseHistoryEntry {
+  attempt: string;
+  timestamp: string;
+  status: string;
+  latency: number;
+}
 
-Apply timeout to all functions in a gateway:
+(async () => {
+  // Create buffer to track response history
+  const buffer = new StableBuffer({
+    initialState: { responseHistory: [] as ResponseHistoryEntry[] }
+  });
+
+  const result: STABLE_REQUEST_RESULT<HealthResponse> = await stableRequest<void, HealthResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/health',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    attempts: 10,
+    retryStrategy: RETRY_STRATEGIES.LINEAR,
+    performAllAttempts: true,          // Continue even after success
+    logAllSuccessfulAttempts: true,    // Required to trigger this hook
+    commonBuffer: buffer,
+    
+    handleSuccessfulAttemptData: async (options: HandleSuccessfulAttemptDataHookOptions<void, HealthResponse>): Promise<void> => {
+      const { reqData, successfulAttemptData, maxSerializableChars, params, commonBuffer } = options;
+      const { attempt, timestamp, data, executionTime, statusCode }: SUCCESSFUL_ATTEMPT_DATA<HealthResponse> = successfulAttemptData;
+      
+      // Track latency metrics
+      await sendMetric('api_latency', executionTime, {
+        endpoint: reqData.url,
+        attempt
+      });
+      
+      // Build response history (useful for polling scenarios)
+      if (commonBuffer) {
+        commonBuffer.responseHistory = commonBuffer.responseHistory || [];
+        commonBuffer.responseHistory.push({
+          attempt,
+          timestamp,
+          status: data.status,
+          latency: executionTime
+        });
+      }
+      
+      // Log successful recovery
+      if (attempt !== '1/10') {
+        console.log(`Recovered on attempt ${attempt} after ${executionTime}ms`);
+      }
+    }
+  });
+})();
+```
 
+**Successful Attempt Data Structure:**
 ```typescript
-import { stableApiGateway, RequestOrFunction } from '@emmvish/stable-request';
-
-const results = await stableApiGateway(
-  [
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'task1',
-        functionOptions: {
-          fn: async () => await task1(),
-          args: [],
-          // No timeout specified - inherits from gateway
-        },
-      },
-    },
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'task2',
-        functionOptions: {
-          fn: async () => await task2(),
-          args: [],
-          executionTimeout: 10000, // Override gateway timeout
-        },
-      },
-    },
-  ],
-  {
-    commonExecutionTimeout: 3000, // Default 3s for all functions
-  }
-);
+interface SUCCESSFUL_ATTEMPT_DATA<ResponseDataType> {
+  attempt: string;        // e.g., "3/5"
+  timestamp: string;      // ISO timestamp
+  data: ResponseDataType; // Response data
+  executionTime: number;  // Time taken (ms)
+  statusCode: number;     // HTTP status code
+}
 ```
 
-#### Request Group Timeout
+**💡 Use cases:**
+- Track latency percentiles
+- Monitor recovery patterns (which attempts succeed?)
+- Build response history for polling workflows
+- Celebrate successful retries in observability dashboards
 
-Different timeouts for different groups:
+---
 
-```typescript
-const results = await stableApiGateway(
-  [
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'critical',
-        groupId: 'criticalOps',
-        functionOptions: { fn: criticalOp, args: [] },
-      },
-    },
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'background',
-        groupId: 'backgroundOps',
-        functionOptions: { fn: backgroundOp, args: [] },
-      },
-    },
-  ],
-  {
-    requestGroups: [
-      {
-        id: 'criticalOps',
-        commonConfig: {
-          commonExecutionTimeout: 1000, // Strict 1s timeout
-        },
-      },
-      {
-        id: 'backgroundOps',
-        commonConfig: {
-          commonExecutionTimeout: 30000, // Lenient 30s timeout
-        },
-      },
-    ],
-  }
-);
-```
+### 5. `finalErrorAnalyzer` - Final Failure Analysis
 
-#### Workflow Phase Timeout
+Called **once** when all retry attempts have been exhausted and the request has failed. This is your last chance to analyze the failure and decide how to handle it.
 
-Apply timeout at phase level in workflows:
+> **Key insight:** Return `true` if you've handled the error gracefully, `false` to let it propagate. Works with `throwOnFailedErrorAnalysis` option.
 
 ```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-
-const result = await stableWorkflow(
-  [
-    {
-      id: 'initialization',
-      functions: [
-        {
-          id: 'init',
-          functionOptions: {
-            fn: initializeSystem,
-            args: [],
-          },
-        },
-      ],
-      commonConfig: {
-        commonExecutionTimeout: 5000, // 5s for initialization
-      },
+import { stableRequest, StableBuffer, REQUEST_METHODS, RETRY_STRATEGIES } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  FinalErrorAnalysisHookOptions,
+  HookParams,
+  ERROR_LOG
+} from 'stable-request';
+
+interface CriticalResponse {
+  result: string;
+}
+
+(async () => {
+  // Create buffer with fallback state
+  const buffer = new StableBuffer({
+    initialState: {
+      errorHistory: [] as ERROR_LOG[],
+      isMaintenanceMode: false,
+      cachedResponse: null as CriticalResponse | null,
+      useFallback: false
+    }
+  });
+
+  const hookParams: HookParams = {
+    finalErrorAnalyzerParams: { allowFailure: false }
+  };
+
+  const result: STABLE_REQUEST_RESULT<CriticalResponse> = await stableRequest<void, CriticalResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/critical-operation',
+      method: REQUEST_METHODS.POST
     },
-    {
-      id: 'processing',
-      functions: [
-        {
-          id: 'process',
-          functionOptions: {
-            fn: processData,
-            args: [],
-          },
-        },
-      ],
-      commonConfig: {
-        commonExecutionTimeout: 30000, // 30s for processing
-      },
+    resReq: true,
+    attempts: 5,
+    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+    throwOnFailedErrorAnalysis: true,  // Throw if finalErrorAnalyzer returns false
+    commonBuffer: buffer,
+    
+    finalErrorAnalyzer: async (options: FinalErrorAnalysisHookOptions<void>): Promise<boolean> => {
+      const { reqData, error, trialMode, params, commonBuffer, executionContext } = options;
+      
+      // Log comprehensive failure report
+      await logFinalFailure({
+        request: reqData,
+        error: error.message,
+        errorHistory: commonBuffer?.errorHistory,
+        context: executionContext
+      });
+      
+      // Check if this is a known/acceptable failure
+      if (error.message.includes('MAINTENANCE_MODE')) {
+        if (commonBuffer) commonBuffer.isMaintenanceMode = true;
+        return true;  // Handled - won't throw
+      }
+      
+      // Check if we should fall back to cached data
+      if (commonBuffer?.cachedResponse) {
+        commonBuffer.useFallback = true;
+        return true;  // Handled - use fallback
+      }
+      
+      // Check if this is a non-critical operation
+      if (params?.allowFailure) {
+        return true;  // Handled - operation is optional
+      }
+      
+      // Unhandled critical failure
+      await sendPagerDutyAlert({
+        severity: 'critical',
+        message: `Critical API failure after 5 attempts`,
+        context: executionContext
+      });
+      
+      return false;  // Not handled - will throw if throwOnFailedErrorAnalysis is true
     },
-  ],
-  {
-    commonExecutionTimeout: 10000, // Default for phases without specific timeout
-  }
-);
+    
+    hookParams
+  });
+})();
 ```
 
-#### Timeout Precedence
+**💡 Use cases:**
+- Comprehensive failure reporting
+- Determine if failure is recoverable vs. fatal
+- Trigger fallback mechanisms
+- Escalate to PagerDuty/on-call
+- Mark operation as gracefully degraded
+- Decide whether to throw or return error result
 
-Timeouts follow the configuration cascade pattern:
+---
 
-**Function > Group > Phase/Branch > Gateway**
+### Hook Parameters Summary
+
+All hooks receive contextual information through their options parameter:
+
+| Parameter | Description | Available In |
+|-----------|-------------|--------------|
+| `reqData` | Axios request configuration | responseAnalyzer, handleErrors, handleSuccessfulAttemptData, finalErrorAnalyzer |
+| `data` | Response data | responseAnalyzer |
+| `error` | Error object | finalErrorAnalyzer |
+| `errorLog` | Detailed error information | handleErrors |
+| `successfulAttemptData` | Success details | handleSuccessfulAttemptData |
+| `trialMode` | Trial mode configuration | responseAnalyzer, finalErrorAnalyzer |
+| `params` | Custom params from hookParams | All hooks |
+| `preExecutionResult` | Return value from preExecutionHook | responseAnalyzer, handleErrors, handleSuccessfulAttemptData, finalErrorAnalyzer |
+| `commonBuffer` | Shared state buffer | All hooks |
+| `executionContext` | Workflow/phase/request IDs | All hooks |
+| `transactionLogs` | Historical transaction logs | All hooks |
+| `inputParams` | preExecutionHookParams | preExecutionHook |
+| `stableRequestOptions` | Full stableRequest config | preExecutionHook |
 
-- Function-level `executionTimeout` always wins
-- If not set, inherits from request group's `commonExecutionTimeout`
-- If not set, inherits from phase/branch's `commonExecutionTimeout`
-- If not set, inherits from gateway's `commonExecutionTimeout`
-- If not set, no timeout is applied
+---
 
-#### Timeout Behavior
+### 📊 Comprehensive Metrics
 
-- Timeout applies to **entire function execution** including all retry attempts
-- When timeout is exceeded, function returns failed result with timeout error
-- Timeout does NOT stop execution mid-flight (no AbortController)
-- Metrics are still collected even when timeout occurs
-- Use with retries: timeout encompasses all attempts, not per-attempt
+Get detailed metrics for every request:
 
 ```typescript
-const result = await stableFunction({
-  fn: slowFunction,
-  args: [],
-  attempts: 5,
-  wait: 1000,
-  executionTimeout: 3000, // Total time for all 5 attempts
-});
+import { stableRequest, REQUEST_METHODS, RETRY_STRATEGIES } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  MetricsGuardrails,
+  StableRequestMetrics
+} from 'stable-request';
 
-// If each attempt takes 800ms:
-// - Attempt 1: 800ms
-// - Attempt 2: starts at 1800ms (after 1s wait)
-// - Attempt 3: would start at 3600ms → TIMEOUT at 3000ms
-```
-
-### Retry Strategies
-
-When a request or function fails and is retryable, retry with configurable backoff.
+interface ApiResponse {
+  data: string[];
+}
 
-#### FIXED Strategy
+(async () => {
+  const metricsGuardrails: MetricsGuardrails = {
+    request: {
+      totalAttempts: { max: 5 },
+      totalExecutionTime: { max: 10000 },
+      failedAttempts: { max: 2 }
+    }
+  };
 
-Constant wait between retries.
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+    logAllErrors: true,
+    logAllSuccessfulAttempts: true,
+    metricsGuardrails
+  });
 
-```typescript
-import { stableRequest, RETRY_STRATEGIES } from '@emmvish/stable-request';
-
-interface DataRequest {}
-interface DataResponse { data: any; }
-
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { hostname: 'api.example.com', path: '/data' },
-  resReq: true,
-  attempts: 4,
-  wait: 500,
-  retryStrategy: RETRY_STRATEGIES.FIXED
-  // Retries at: 500ms, 1000ms, 1500ms
-});
+  const metrics: StableRequestMetrics | undefined = result.metrics;
+  console.log(metrics);
+  // {
+  //   totalAttempts: 3,
+  //   successfulAttempts: 1,
+  //   failedAttempts: 2,
+  //   totalExecutionTime: 4532,
+  //   averageAttemptTime: 1510,
+  //   infrastructureMetrics: {
+  //     circuitBreaker: { state: 'CLOSED', failurePercentage: 10, ... },
+  //     cache: { hitRate: 45.5, missRate: 54.5, ... }
+  //   },
+  //   validation: { isValid: true, anomalies: [] }
+  // }
+})();
 ```
 
-#### LINEAR Strategy
+### 🧪 Trial Mode (Chaos Engineering)
 
-Wait increases linearly with attempt number.
+Test your error handling without hitting real endpoints:
 
 ```typescript
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { hostname: 'api.example.com', path: '/data' },
-  resReq: true,
-  attempts: 4,
-  wait: 100,
-  retryStrategy: RETRY_STRATEGIES.LINEAR
-  // Retries at: 100ms, 200ms, 300ms (wait * attempt)
-});
-```
-
-#### EXPONENTIAL Strategy
+import { stableRequest, REQUEST_METHODS } from 'stable-request';
+import type { STABLE_REQUEST_RESULT, TRIAL_MODE_OPTIONS } from 'stable-request';
 
-Wait increases exponentially; useful for heavily loaded services.
+interface ApiResponse {
+  data: unknown;
+}
 
-```typescript
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { hostname: 'api.example.com', path: '/data' },
-  resReq: true,
-  attempts: 4,
-  wait: 100,
-  maxAllowedWait: 10000,
-  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
-  // Retries at: 100ms, 200ms, 400ms (wait * 2^(attempt-1))
-  // Capped at maxAllowedWait
-});
+(async () => {
+  const trialMode: TRIAL_MODE_OPTIONS = {
+    enabled: true,
+    reqFailureProbability: 0.3,   // 30% chance of request failure
+    retryFailureProbability: 0.2  // 20% chance retry is not allowed
+  };
+
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    trialMode
+  });
+})();
 ```
 
-#### Jitter
+### 🎯 Execution Context
 
-Add random milliseconds to prevent synchronization.
+Track requests across distributed systems:
 
 ```typescript
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { hostname: 'api.example.com', path: '/data' },
-  resReq: true,
-  attempts: 3,
-  wait: 500,
-  jitter: 200, // Add 0-200ms randomness
-  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL
-});
-```
-
-#### Perform All Attempts
+import { stableRequest, REQUEST_METHODS } from 'stable-request';
+import type { STABLE_REQUEST_RESULT, ExecutionContext } from 'stable-request';
 
-Collect all outcomes instead of failing on first error.
+interface ApiResponse {
+  data: unknown;
+}
 
-```typescript
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { hostname: 'api.example.com', path: '/data' },
-  resReq: true,
-  attempts: 3,
-  performAllAttempts: true
-  // All 3 attempts execute; check result.successfulAttempts
-});
+(async () => {
+  const executionContext: ExecutionContext = {
+    workflowId: 'order-processing-123',
+    phaseId: 'payment-validation',
+    requestId: 'req-456'
+  };
+
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
+    },
+    resReq: true,
+    executionContext
+  });
+  // Logs will include: [Workflow: order-processing-123] [Phase: payment-validation] [Request: req-456]
+})();
 ```
 
-### Circuit Breaker
+## StableBuffer API
 
-Prevent cascading failures by failing fast when a dependency becomes unhealthy.
+### Constructor Options
 
 ```typescript
-import { stableApiGateway, CircuitBreaker } from '@emmvish/stable-request';
-
-interface FlakyRequest {}
-interface FlakyResponse { status: string; }
+import { StableBuffer } from 'stable-request';
+import type { StableBufferOptions, StableBufferTransactionLog, MetricsGuardrailsStableBuffer, StableBufferState } from 'stable-request';
 
-const breaker = new CircuitBreaker({
-  failureThresholdPercentage: 50,
-  minimumRequests: 10,
-  recoveryTimeoutMs: 30000,
-  successThresholdPercentage: 80,
-  halfOpenMaxRequests: 5
-});
+const bufferOptions: StableBufferOptions = {
+  initialState: {},              // Starting state
+  clone: (state: StableBufferState): StableBufferState => ({ ...state }),  // Custom cloning function
+  transactionTimeoutMs: 5000,    // Transaction timeout
+  logTransaction: async (log: StableBufferTransactionLog): Promise<void> => {}, // Transaction logger
+  metricsGuardrails: {           // Validation rules
+    totalTransactions: { max: 1000 },
+    averageQueueWaitMs: { max: 100 }
+  }
+};
 
-const requests = [
-  { id: 'req-1', requestOptions: { reqData: { path: '/flaky' }, resReq: true } },
-  { id: 'req-2', requestOptions: { reqData: { path: '/flaky' }, resReq: true } }
-];
+const buffer = new StableBuffer(bufferOptions);
+```
 
-const responses = await stableApiGateway<FlakyRequest, FlakyResponse>(requests, {
-  circuitBreaker: breaker
-});
+### Methods
 
-// Circuit breaker states:
-// CLOSED: Normal operation (accept all requests)
-// OPEN: Too many failures; reject immediately
-// HALF_OPEN: Testing recovery; allow limited requests
-```
+```typescript
+import { StableBuffer } from 'stable-request';
+import type { StableBufferMetrics, StableBufferState } from 'stable-request';
 
-**State Transitions:**
+interface BufferState extends StableBufferState {
+  value: string;
+  counter: number;
+  newState?: boolean;
+}
 
-- **CLOSED → OPEN:** Failure rate exceeds threshold after minimum requests
-- **OPEN → HALF_OPEN:** Recovery timeout elapsed; attempt recovery
-- **HALF_OPEN → CLOSED:** Success rate exceeds recovery threshold
-- **HALF_OPEN → OPEN:** Success rate below recovery threshold; reopen
+const buffer = new StableBuffer({
+  initialState: { value: '', counter: 0 } as BufferState
+});
+
+(async () => {
+  // Read current state (cloned)
+  const state = buffer.read() as BufferState;
+
+  // Get direct state reference
+  const directState = buffer.getState() as BufferState;
+
+  // Set entire state
+  buffer.setState({ value: '', counter: 0, newState: true } as BufferState);
+
+  // Run transaction
+  const result: string = await buffer.run(async (state): Promise<string> => {
+    const typedState = state as BufferState;
+    typedState.value = 'updated';
+    return typedState.value;
+  });
+
+  // Update state (no return value)
+  await buffer.run(async (state): Promise<void> => {
+    const typedState = state as BufferState;
+    typedState.counter += 1;
+  });
+
+  // Get metrics
+  const metrics: StableBufferMetrics = buffer.getMetrics();
+})();
+```
+
+### Transaction Logs
+
+Each transaction generates a log entry:
+
+```typescript
+interface StableBufferTransactionLog {
+  transactionId: string;
+  queuedAt: string;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  queueWaitMs: number;
+  success: boolean;
+  errorMessage?: string;
+  stateBefore: Record<string, any>;
+  stateAfter: Record<string, any>;
+  activity?: string;
+  hookName?: string;
+  hookParams?: any;
+  workflowId?: string;
+  branchId?: string;
+  phaseId?: string;
+  requestId?: string;
+}
+```
 
-### Caching
+## Infrastructure Persistence
 
-Cache responses to avoid redundant calls.
+Persist circuit breaker and cache state for recovery:
 
 ```typescript
-import { stableRequest, CacheManager } from '@emmvish/stable-request';
+import { stableRequest, StableBuffer, REQUEST_METHODS } from 'stable-request';
+import type { 
+  STABLE_REQUEST_RESULT, 
+  CircuitBreakerConfig, 
+  CacheConfig,
+  CircuitBreakerPersistedState,
+  CacheManagerPersistedState,
+  InfrastructurePersistence
+} from 'stable-request';
 
-interface UserRequest {}
-interface UserResponse {
-  id: number;
-  name: string;
-  email: string;
-}
-
-const cache = new CacheManager({
-  enabled: true,
-  ttl: 5000 // 5 seconds
-});
-
-// First call: cache miss, hits API
-const result1 = await stableRequest<UserRequest, UserResponse>({
-  reqData: { hostname: 'api.example.com', path: '/user/1' },
-  resReq: true,
-  cache
-});
-
-// Second call within 5s: cache hit, returns cached response
-const result2 = await stableRequest<UserRequest, UserResponse>({
-  reqData: { hostname: 'api.example.com', path: '/user/1' },
-  resReq: true,
-  cache
-});
-
-// Respects Cache-Control headers if enabled
-const cache2 = new CacheManager({
-  enabled: true,
-  ttl: 60000,
-  respectCacheControl: true // Uses max-age, no-cache, no-store
-});
-```
-
-**Function Caching:**
-
-Arguments become cache key; identical args hit cache.
-
-```typescript
-import { stableFunction } from '@emmvish/stable-request';
-
-const expensive = (x: number) => x * x * x; // Cubic calculation
-
-const result1 = await stableFunction({
-  fn: expensive,
-  args: [5],
-  returnResult: true,
-  cache: { enabled: true, ttl: 10000 }
-});
-
-const result2 = await stableFunction({
-  fn: expensive,
-  args: [5], // Same args → cache hit
-  returnResult: true,
-  cache: { enabled: true, ttl: 10000 }
-});
-```
-
-### Rate Limiting
-
-Enforce max requests per time window.
-
-```typescript
-import { stableApiGateway } from '@emmvish/stable-request';
-
-interface ItemRequest {}
-interface ItemResponse {
-  id: number;
-  data: any;
-}
-
-const requests = Array.from({ length: 20 }, (_, i) => ({
-  id: `req-${i}`,
-  requestOptions: {
-    reqData: { path: `/item/${i}` },
-    resReq: true
-  }
-}));
-
-const responses = await stableApiGateway<ItemRequest, ItemResponse>(requests, {
-  concurrentExecution: true,
-  rateLimit: {
-    maxRequests: 5,
-    windowMs: 1000 // 5 requests per second
-  }
-  // Requests queued until window allows; prevents overwhelming API
-});
-```
-
-### Concurrency Limiting
-
-Limit concurrent in-flight requests.
-
-```typescript
-import { stableApiGateway } from '@emmvish/stable-request';
-
-interface ItemRequest {}
-interface ItemResponse {
-  id: number;
-  data: any;
-}
-
-const requests = Array.from({ length: 50 }, (_, i) => ({
-  id: `req-${i}`,
-  requestOptions: {
-    reqData: { path: `/item/${i}` },
-    resReq: true,
-    attempts: 1
-  }
-}));
-
-const responses = await stableApiGateway<ItemRequest, ItemResponse>(requests, {
-  concurrentExecution: true,
-  maxConcurrentRequests: 5 // Only 5 requests in-flight at a time
-  // Others queued and executed as slots free
-});
-```
-
----
-
-## Workflow Patterns
-
-### Sequential & Concurrent Phases
-
-#### Sequential (Default)
-
-Each phase waits for the previous to complete.
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'phase-1',
-    requests: [{ id: 'r1', requestOptions: { reqData: { path: '/p1' }, resReq: true } }]
-  },
-  {
-    id: 'phase-2',
-    requests: [{ id: 'r2', requestOptions: { reqData: { path: '/p2' }, resReq: true } }]
-  },
-  {
-    id: 'phase-3',
-    requests: [{ id: 'r3', requestOptions: { reqData: { path: '/p3' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'sequential-phases',
-  concurrentPhaseExecution: false // Phase-1 → Phase-2 → Phase-3
-});
-```
-
-#### Concurrent Phases
-
-Multiple phases run in parallel.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'fetch-users',
-    requests: [{ id: 'get-users', requestOptions: { reqData: { path: '/users' }, resReq: true } }]
-  },
-  {
-    id: 'fetch-posts',
-    requests: [{ id: 'get-posts', requestOptions: { reqData: { path: '/posts' }, resReq: true } }]
-  },
-  {
-    id: 'fetch-comments',
-    requests: [{ id: 'get-comments', requestOptions: { reqData: { path: '/comments' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'parallel-phases',
-  concurrentPhaseExecution: true // All 3 phases in parallel
-});
-```
-
-#### Mixed Phases
-
-Combine sequential and concurrent phases in one workflow.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'init', // Sequential
-    requests: [{ id: 'setup', requestOptions: { reqData: { path: '/init' }, resReq: true } }]
-  },
-  {
-    id: 'fetch-a',
-    markConcurrentPhase: true, // Concurrent with next
-    requests: [{ id: 'data-a', requestOptions: { reqData: { path: '/a' }, resReq: true } }]
-  },
-  {
-    id: 'fetch-b',
-    markConcurrentPhase: true, // Concurrent with fetch-a
-    requests: [{ id: 'data-b', requestOptions: { reqData: { path: '/b' }, resReq: true } }]
-  },
-  {
-    id: 'finalize', // Sequential after fetch-a/b complete
-    requests: [{ id: 'done', requestOptions: { reqData: { path: '/finalize' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  concurrentPhaseExecution: false // Respects markConcurrentPhase per phase
-});
-```
-
-### Non-Linear Workflows
-
-Use decision hooks to dynamically control phase flow.
-
-#### CONTINUE
-
-Standard flow to next sequential phase.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'check-status',
-    requests: [{ id: 'api', requestOptions: { reqData: { path: '/status' }, resReq: true } }],
-    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
-      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
-    }
-  },
-  {
-    id: 'process', // Executes after check-status
-    requests: [{ id: 'process-data', requestOptions: { reqData: { path: '/process' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  enableNonLinearExecution: true
-});
-```
-
-#### SKIP
-
-Skip the next phase; execute the one after.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'phase-1',
-    requests: [{ id: 'r1', requestOptions: { reqData: { path: '/p1' }, resReq: true } }],
-    phaseDecisionHook: async () => ({
-      action: PHASE_DECISION_ACTIONS.SKIP
-    })
-  },
-  {
-    id: 'phase-2', // Skipped
-    requests: [{ id: 'r2', requestOptions: { reqData: { path: '/p2' }, resReq: true } }]
-  },
-  {
-    id: 'phase-3', // Executes
-    requests: [{ id: 'r3', requestOptions: { reqData: { path: '/p3' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  enableNonLinearExecution: true
-});
-
-// Execution: phase-1 → phase-3
-```
-
-#### JUMP
-
-Jump to a specific phase by ID.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'phase-1',
-    requests: [{ id: 'r1', requestOptions: { reqData: { path: '/p1' }, resReq: true } }],
-    phaseDecisionHook: async () => ({
-      action: PHASE_DECISION_ACTIONS.JUMP,
-      targetPhaseId: 'recovery'
-    })
-  },
-  {
-    id: 'phase-2', // Skipped
-    requests: [{ id: 'r2', requestOptions: { reqData: { path: '/p2' }, resReq: true } }]
-  },
-  {
-    id: 'recovery',
-    requests: [{ id: 'recover', requestOptions: { reqData: { path: '/recovery' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  enableNonLinearExecution: true
-});
-
-// Execution: phase-1 → recovery
-```
-
-#### REPLAY
-
-Re-execute current phase; useful for polling.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'wait-for-job',
-    allowReplay: true,
-    maxReplayCount: 5,
-    requests: [
-      {
-        id: 'check-job',
-        requestOptions: { reqData: { path: '/job/status' }, resReq: true, attempts: 1 }
-      }
-    ],
-    phaseDecisionHook: async ({ phaseResult, executionHistory }) => {
-      const lastResponse = phaseResult.responses?.[0];
-      if ((lastResponse as any)?.data?.status === 'pending' && executionHistory.length < 5) {
-        return { action: PHASE_DECISION_ACTIONS.REPLAY };
-      }
-      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
-    }
-  },
-  {
-    id: 'process-result',
-    requests: [{ id: 'process', requestOptions: { reqData: { path: '/process' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  enableNonLinearExecution: true,
-  maxWorkflowIterations: 100
-});
-
-// Polls up to 5 times before continuing
-```
-
-#### TERMINATE
-
-Stop workflow early.
-
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'validate',
-    requests: [{ id: 'validate-input', requestOptions: { reqData: { path: '/validate' }, resReq: true } }],
-    phaseDecisionHook: async ({ phaseResult, sharedBuffer }) => {
-      if (!phaseResult.success) {
-        return { action: PHASE_DECISION_ACTIONS.TERMINATE };
-      }
-      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
-    }
-  },
-  {
-    id: 'phase-2', // Won't execute if validation fails
-    requests: [{ id: 'r2', requestOptions: { reqData: { path: '/p2' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  enableNonLinearExecution: true
-});
-
-console.log(result.terminatedEarly); // true if TERMINATE triggered
-```
-
-### Branched Workflows
-
-Execute multiple independent branches with shared state.
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_BRANCH } from '@emmvish/stable-request';
-
-const branches: STABLE_WORKFLOW_BRANCH[] = [
-  {
-    id: 'branch-payment',
-    phases: [
-      {
-        id: 'process-payment',
-        requests: [
-          {
-            id: 'charge-card',
-            requestOptions: {
-              reqData: { path: '/payment/charge' },
-              resReq: true
-            }
-          }
-        ]
-      }
-    ]
-  },
-  {
-    id: 'branch-notification',
-    phases: [
-      {
-        id: 'send-email',
-        requests: [
-          {
-            id: 'send',
-            requestOptions: {
-              reqData: { path: '/notify/email' },
-              resReq: false
-            }
-          }
-        ]
-      }
-    ]
-  }
-];
-
-const result = await stableWorkflow([], {
-  workflowId: 'checkout',
-  enableBranchExecution: true,
-  branches,
-  sharedBuffer: { orderId: '12345' },
-  markConcurrentBranch: true // Branches run in parallel
-});
-
-// Both branches access/modify sharedBuffer
-```
-
-#### Branch Racing
-
-When multiple branches execute concurrently, enable racing to accept the first successful branch and cancel others.
-
-```typescript
-const result = await stableWorkflow([], {
-  workflowId: 'payment-racing',
-  enableBranchExecution: true,
-  enableBranchRacing: true, // First successful branch wins
-  branches: [
-    {
-      id: 'payment-provider-a',
-      phases: [/* ... */]
-    },
-    {
-      id: 'payment-provider-b',
-      phases: [/* ... */]
-    }
-  ],
-  markConcurrentBranch: true
-});
-
-// Only winning branch's execution history recorded
-// Losing branches marked as cancelled
-```
-
-## Graph-based Workflow Patterns
-
-**Key responsibilities:**
-- Define phases as DAG nodes with explicit dependency edges
-- Execute independent phases in parallel automatically
-- Support parallel groups, merge points, and conditional routing
-- Validate graph structure (cycle detection, reachability, orphan detection)
-- Provide deterministic execution order
-- Offer higher parallelism than phased workflows for complex topologies
-
-### Graph-Based Workflows with Mixed Items
-
-For complex topologies with explicit dependencies, use DAG execution mixing requests and functions.
-
-```typescript
-import { stableWorkflowGraph, WorkflowGraphBuilder, RequestOrFunction } from '@emmvish/stable-request';
-import type { API_GATEWAY_ITEM } from '@emmvish/stable-request';
-
-// Request types
-interface PostsRequest {}
-interface PostsResponse { posts: Array<{ id: number; title: string }> };
-
-interface UsersRequest {}
-interface UsersResponse { users: Array<{ id: number; name: string }> };
-
-// Function types
-type AggregateArgs = [PostsResponse, UsersResponse];
-type AggregateResult = {
-  combined: Array<{ userId: number; userName: string; postCount: number }>;
-};
-
-type AnalyzeArgs = [AggregateResult];
-type AnalyzeResult = { totalPosts: number; activeUsers: number };
-
-const graph = new WorkflowGraphBuilder<
-  PostsRequest | UsersRequest,
-  PostsResponse | UsersResponse,
-  AggregateArgs | AnalyzeArgs,
-  AggregateResult | AnalyzeResult
->()
-  .addPhase('fetch-posts', {
-    requests: [{
-      id: 'get-posts',
-      requestOptions: {
-        reqData: { path: '/posts' },
-        resReq: true
-      }
-    }]
-  })
-  .addPhase('fetch-users', {
-    requests: [{
-      id: 'get-users',
-      requestOptions: {
-        reqData: { path: '/users' },
-        resReq: true
-      }
-    }]
-  })
-  .addParallelGroup('fetch-all', ['fetch-posts', 'fetch-users'])
-  .addPhase('aggregate', {
-    functions: [{
-      id: 'combine-data',
-      functionOptions: {
-        fn: (posts: PostsResponse, users: UsersResponse): AggregateResult => ({
-          combined: users.users.map(user => ({
-            userId: user.id,
-            userName: user.name,
-            postCount: posts.posts.filter(p => p.id === user.id).length
-          }))
-        }),
-        args: [{ posts: [] }, { users: [] }] as AggregateArgs,
-        returnResult: true
-      }
-    }]
-  })
-  .addPhase('analyze', {
-    functions: [{
-      id: 'analyze-data',
-      functionOptions: {
-        fn: (aggregated: AggregateResult): AnalyzeResult => ({
-          totalPosts: aggregated.combined.reduce((sum, u) => sum + u.postCount, 0),
-          activeUsers: aggregated.combined.filter(u => u.postCount > 0).length
-        }),
-        args: [{ combined: [] }] as AnalyzeArgs,
-        returnResult: true
-      }
-    }]
-  })
-  .addMergePoint('sync', ['fetch-all'])
-  .connectSequence('fetch-all', 'sync', 'aggregate', 'analyze')
-  .setEntryPoint('fetch-all')
-  .build();
-
-const result = await stableWorkflowGraph(graph, {
-  workflowId: 'data-aggregation'
-});
-
-console.log(`Graph workflow success: ${result.success}`);
-```
-
-### Parallel Phase Execution
-
-Execute multiple phases concurrently within a group.
-
-```typescript
-import { stableWorkflowGraph, WorkflowGraphBuilder } from '@emmvish/stable-request';
-
-const graph = new WorkflowGraphBuilder()
-  .addPhase('fetch-users', {
-    requests: [{
-      id: 'users',
-      requestOptions: { reqData: { path: '/users' }, resReq: true }
-    }]
-  })
-  .addPhase('fetch-posts', {
-    requests: [{
-      id: 'posts',
-      requestOptions: { reqData: { path: '/posts' }, resReq: true }
-    }]
-  })
-  .addPhase('fetch-comments', {
-    requests: [{
-      id: 'comments',
-      requestOptions: { reqData: { path: '/comments' }, resReq: true }
-    }]
-  })
-  .addParallelGroup('data-fetch', ['fetch-users', 'fetch-posts', 'fetch-comments'])
-  .setEntryPoint('data-fetch')
-  .build();
-
-const result = await stableWorkflowGraph(graph, {
-  workflowId: 'data-aggregation'
-});
-
-// All 3 phases run concurrently
-```
-
-### Merge Points
-
-Synchronize multiple predecessor phases.
-
-```typescript
-const graph = new WorkflowGraphBuilder()
-  .addPhase('fetch-a', {
-    requests: [{ id: 'a', requestOptions: { reqData: { path: '/a' }, resReq: true } }]
-  })
-  .addPhase('fetch-b', {
-    requests: [{ id: 'b', requestOptions: { reqData: { path: '/b' }, resReq: true } }]
-  })
-  .addMergePoint('sync', ['fetch-a', 'fetch-b'])
-  .addPhase('aggregate', {
-    functions: [{
-      id: 'combine',
-      functionOptions: {
-        fn: () => 'combined',
-        args: [],
-        returnResult: true
-      }
-    }]
-  })
-  .connectSequence('fetch-a', 'sync')
-  .connectSequence('fetch-b', 'sync')
-  .connectSequence('sync', 'aggregate')
-  .setEntryPoint('fetch-a')
-  .build();
-
-const result = await stableWorkflowGraph(graph, {
-  workflowId: 'parallel-sync'
-});
-
-// fetch-a and fetch-b run in parallel
-// aggregate waits for both to complete
-```
-
-### Linear Helper
-
-Convenience function for sequential phase chains.
-
-```typescript
-import { createLinearWorkflowGraph } from '@emmvish/stable-request';
-
-const phases = [
-  {
-    id: 'init',
-    requests: [{ id: 'setup', requestOptions: { reqData: { path: '/init' }, resReq: true } }]
-  },
-  {
-    id: 'process',
-    requests: [{ id: 'do-work', requestOptions: { reqData: { path: '/work' }, resReq: true } }]
-  },
-  {
-    id: 'finalize',
-    requests: [{ id: 'cleanup', requestOptions: { reqData: { path: '/cleanup' }, resReq: true } }]
-  }
-];
-
-const graph = createLinearWorkflowGraph(phases);
-
-const result = await stableWorkflowGraph(graph, {
-  workflowId: 'linear-workflow'
-});
-```
-
-### Branch Racing in Graphs
-
-Enable branch racing in workflow graphs to accept the first successful branch node when multiple branches are executed in parallel.
-
-```typescript
-import { stableWorkflowGraph, WorkflowGraphBuilder } from '@emmvish/stable-request';
-
-const branch1 = {
-  id: 'provider-a',
-  phases: [{ /* ... */ }]
-};
-
-const branch2 = {
-  id: 'provider-b',
-  phases: [{ /* ... */ }]
-};
-
-const graph = new WorkflowGraphBuilder()
-  .addBranch('provider-a', branch1)
-  .addBranch('provider-b', branch2)
-  .addParallelGroup('race', ['provider-a', 'provider-b'])
-  .setEntryPoint('race')
-  .build();
-
-const result = await stableWorkflowGraph(graph, {
-  workflowId: 'provider-racing',
-  enableBranchRacing: true // First successful branch wins
-});
-
-// Only winning branch's results recorded
-// Losing branch marked as cancelled
-```
-
----
-
-## Configuration & State
-
-### Config Cascading
-
-Define defaults globally; override at group, phase, branch, or item level.
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'phase-1',
-    attempts: 5, // Override global attempts for this phase
-    wait: 1000,
-    requests: [
-      {
-        id: 'req-1',
-        requestOptions: {
-          reqData: { path: '/data' },
-          resReq: true,
-          attempts: 2 // Override phase attempts for this item
-        }
-      }
-    ]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'cascade-demo',
-  commonAttempts: 1, // Global default
-  commonWait: 500,
-  retryStrategy: 'LINEAR' // Global default
-  // Final config per item: merge common → phase → request
-});
-```
-
-Hierarchy: global → group → phase → branch → item. Lower levels override.
-
-### Shared & State Buffers
-
-Pass mutable state across phases, branches, and items. For concurrency-safe shared state, pass a `StableBuffer` instance instead of a plain object.
-
-#### Shared Buffer (Workflow/Gateway)
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'fetch',
-    requests: [
-      {
-        id: 'user-data',
-        requestOptions: {
-          reqData: { path: '/users/1' },
-          resReq: true,
-          handleSuccessfulAttemptData: ({ successfulAttemptData, stableRequestOptions }) => {
-            // Mutate shared buffer
-            const sharedBuffer = (stableRequestOptions as any).sharedBuffer;
-            sharedBuffer.userId = (successfulAttemptData.data as any).id;
-          }
-        }
-      }
-    ]
-  },
-  {
-    id: 'use-shared-data',
-    requests: [
-      {
-        id: 'dependent-call',
-        requestOptions: {
-          reqData: { path: '/user-posts' },
-          resReq: true,
-          preExecution: {
-            preExecutionHook: async ({ stableRequestOptions, commonBuffer }) => {
-              const sharedBuffer = (stableRequestOptions as any).sharedBuffer;
-              console.log(`Using userId: ${sharedBuffer.userId}`);
-            }
-          }
-        }
-      }
-    ]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'shared-state-demo',
-  sharedBuffer: {} // Mutable across phases
-});
-```
-
-#### Common Buffer (Request Level)
-
-```typescript
-import { stableRequest, PersistenceStage } from '@emmvish/stable-request';
-
-const commonBuffer = { transactionId: null };
-
-const result = await stableRequest({
-  reqData: { path: '/transaction/start' },
-  resReq: true,
-  commonBuffer,
-  preExecution: {
-    preExecutionHook: async ({ commonBuffer, stableRequestOptions }) => {
-      // commonBuffer writable here
-      commonBuffer.userId = '123';
-    }
-  },
-  handleSuccessfulAttemptData: ({ successfulAttemptData }) => {
-    // commonBuffer readable in handlers
-    console.log(`Transaction for user ${commonBuffer.userId} done`);
-  }
-});
-```
-
----
-
-## Hooks & Observability
-
-### Pre-Execution Hooks
-
-Modify config or state before execution.
-
-```typescript
-import { stableRequest } from '@emmvish/stable-request';
-
-interface SecureRequest {}
-interface SecureResponse {
-  data: any;
-  token?: string;
-}
-
-const result = await stableRequest<SecureRequest, SecureResponse>({
-  reqData: { path: '/secure-data' },
-  resReq: true,
-  preExecution: {
-    preExecutionHook: async ({ inputParams, commonBuffer, stableRequestOptions }) => {
-      // Dynamically fetch auth token
-      const token = await getAuthToken();
-      
-      // Return partial config override
-      return {
-        reqData: {
-          headers: { Authorization: `Bearer ${token}` }
-        }
-      };
-    },
-    preExecutionHookParams: { context: 'auth-fetch' },
-    applyPreExecutionConfigOverride: true,
-    continueOnPreExecutionHookFailure: false
-  }
-});
-```
-
-### Analysis Hooks
-
-Validate responses and errors.
-
-#### Response Analyzer
-
-```typescript
-import { stableRequest } from '@emmvish/stable-request';
-
-interface ResourceRequest {}
 interface ApiResponse {
-  id: number;
-  status: 'active' | 'inactive';
-}
-
-const result = await stableRequest<ResourceRequest, ApiResponse>({
-  reqData: { path: '/resource' },
-  resReq: true,
-  responseAnalyzer: ({ data, reqData, trialMode }) => {
-    // Return true to accept, false to retry
-    if (!data || typeof data !== 'object') return false;
-    if (!('id' in data)) return false;
-    if ((data as any).status !== 'active') return false;
-    return true;
-  }
-});
-```
-
-#### Error Analyzer
-
-Decide whether to suppress error gracefully.
-
-```typescript
-import { stableRequest } from '@emmvish/stable-request';
-
-interface FeatureRequest {}
-interface FeatureResponse {
-  enabled: boolean;
-  data?: any;
-}
-
-const result = await stableRequest<FeatureRequest, FeatureResponse>({
-  reqData: { path: '/optional-feature' },
-  resReq: true,
-  finalErrorAnalyzer: ({ error, reqData, trialMode }) => {
-    // Return true to suppress error and return failure result
-    // Return false to throw error
-    if (error.code === 'ECONNREFUSED') {
-      console.warn('Service unavailable, continuing with fallback');
-      return true; // Suppress, don't throw
-    }
-    return false; // Throw
-  }
-});
-
-if (result.success) {
-  console.log('Got data:', result.data);
-} else {
-  console.log('Service offline, but we continue');
-}
-```
-
-### Handler Hooks
-
-Custom logging and processing.
-
-#### Success Handler
-
-```typescript
-import { stableRequest } from '@emmvish/stable-request';
-
-interface DataRequest {}
-interface DataResponse {
-  id: number;
-  value: string;
-}
-
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { path: '/data' },
-  resReq: true,
-  logAllSuccessfulAttempts: true,
-  handleSuccessfulAttemptData: ({
-    successfulAttemptData,
-    reqData,
-    maxSerializableChars,
-    executionContext
-  }) => {
-    // Custom logging, metrics, state updates
-    console.log(
-      `Success in context ${executionContext.workflowId}`,
-      `data:`,
-      successfulAttemptData.data
-    );
-  }
-});
-```
-
-#### Error Handler
-
-```typescript
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { path: '/data' },
-  resReq: true,
-  logAllErrors: true,
-  handleErrors: ({ errorLog, reqData, executionContext }) => {
-    // Custom error logging, alerting, retry logic
-    console.error(
-      `Error in ${executionContext.workflowId}:`,
-      errorLog.errorMessage,
-      `Retryable: ${errorLog.isRetryable}`
-    );
-  }
-});
-```
-
-#### Phase Handlers (Workflow)
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'phase-1',
-    requests: [{ id: 'r1', requestOptions: { reqData: { path: '/data' }, resReq: true } }]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'wf-handlers',
-  handlePhaseCompletion: ({ phaseResult, workflowId }) => {
-    console.log(`Phase ${phaseResult.phaseId} complete in ${workflowId}`);
-  },
-  handlePhaseError: ({ phaseResult, error, workflowId }) => {
-    console.error(`Phase ${phaseResult.phaseId} failed:`, error);
-  },
-  handlePhaseDecision: ({ decision, phaseResult }) => {
-    console.log(`Phase decision: ${decision.action}`);
-  }
-});
-```
-
-### Decision Hooks
-
-Dynamically determine workflow flow.
-
-```typescript
-import { stableWorkflow, PHASE_DECISION_ACTIONS } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'fetch-data',
-    requests: [{ id: 'api', requestOptions: { reqData: { path: '/data' }, resReq: true } }],
-    phaseDecisionHook: async ({ phaseResult, sharedBuffer, executionHistory }) => {
-      if (!phaseResult.success) {
-        return { action: PHASE_DECISION_ACTIONS.TERMINATE };
-      }
-      if (phaseResult.responses[0].data?.needsRetry) {
-        return { action: PHASE_DECISION_ACTIONS.REPLAY };
-      }
-      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
-    }
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  enableNonLinearExecution: true
-});
-```
-
-### Metrics & Logging
-
-Automatic metrics collection across all execution modes.
-
-#### Request Metrics
-
-```typescript
-import { stableRequest } from '@emmvish/stable-request';
-
-interface DataRequest {}
-interface DataResponse { data: any; }
-
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { path: '/data' },
-  resReq: true,
-  attempts: 3
-});
-
-console.log(result.metrics); // {
-//   totalAttempts: 2,
-//   successfulAttempts: 1,
-//   failedAttempts: 1,
-//   totalExecutionTime: 450,
-//   averageAttemptTime: 225,
-//   infrastructureMetrics: {
-//     circuitBreaker: { /* state, stats, config */ },
-//     cache: { /* hits, misses, size */ },
-//     rateLimiter: { /* limit, current rate */ },
-//     concurrencyLimiter: { /* limit, in-flight */ }
-//   },
-//   validation: {
-//     isValid: true,
-//     anomalies: [],
-//     validatedAt: '2026-01-20T...'
-//   }
-// }
-```
-
-#### API Gateway Metrics
-
-```typescript
-import { stableApiGateway } from '@emmvish/stable-request';
-import type { API_GATEWAY_REQUEST } from '@emmvish/stable-request';
-
-interface ApiRequest {}
-interface ApiResponse { data: any; }
-
-const requests: API_GATEWAY_REQUEST<ApiRequest, ApiResponse>[] = [
-  { id: 'req-1', requestOptions: { reqData: { path: '/data/1' }, resReq: true } },
-  { id: 'req-2', requestOptions: { reqData: { path: '/data/2' }, resReq: true } },
-  { id: 'req-3', requestOptions: { reqData: { path: '/data/3' }, resReq: true } }
-];
-
-const result = await stableApiGateway<ApiRequest, ApiResponse>(requests, {
-  concurrentExecution: true,
-  maxConcurrentRequests: 5
-});
-
-console.log(result.metrics); // {
-//   totalRequests: 3,
-//   successfulRequests: 3,
-//   failedRequests: 0,
-//   successRate: 100,
-//   failureRate: 0,
-//   executionTime: 450,              // Total execution time in ms
-//   timestamp: '2026-01-20T...',     // ISO 8601 completion timestamp
-//   throughput: 6.67,                // Requests per second
-//   averageRequestDuration: 150,     // Average time per request in ms
-//   requestGroups: [/* per-group stats */],
-//   infrastructureMetrics: {
-//     circuitBreaker: { /* state, stats, config */ },
-//     cache: { /* hit rate, size, utilization */ },
-//     rateLimiter: { /* throttle rate, queue length */ },
-//     concurrencyLimiter: { /* utilization, queue */ }
-//   },
-//   validation: {
-//     isValid: true,
-//     anomalies: [],
-//     validatedAt: '2026-01-20T...'
-//   }
-// }
-```
-
-#### Workflow Metrics
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  { id: 'p1', requests: [{ id: 'r1', requestOptions: { reqData: { path: '/a' }, resReq: true } }] },
-  { id: 'p2', requests: [{ id: 'r2', requestOptions: { reqData: { path: '/b' }, resReq: true } }] }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'wf-metrics'
-});
-
-console.log(result); // {
-//   workflowId: 'wf-metrics',
-//   success: true,
-//   totalPhases: 2,
-//   completedPhases: 2,
-//   totalRequests: 2,
-//   successfulRequests: 2,
-//   failedRequests: 0,
-//   workflowExecutionTime: 1200,
-//   phases: [
-//     { phaseId: 'p1', success: true, responses: [...], validation: {...}, ... },
-//     { phaseId: 'p2', success: true, responses: [...], validation: {...}, ... }
-//   ],
-//   validation: {
-//     isValid: true,
-//     anomalies: [],
-//     validatedAt: '2026-01-20T...'
-//   }
-// }
-```
-
-#### Structured Error Logs
-
-```typescript
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { path: '/flaky' },
-  resReq: true,
-  attempts: 3,
-  logAllErrors: true,
-  handleErrors: ({ errorLog }) => {
-    console.log(errorLog); // {
-    //   attempt: '1/3',
-    //   type: 'NetworkError',
-    //   error: 'ECONNREFUSED',
-    //   isRetryable: true,
-    //   timestamp: 1234567890
-    // }
-  }
-});
-
-if (result.errorLogs) {
-  console.log(`${result.errorLogs.length} errors logged`);
+  data: unknown;
 }
-```
 
----
-
-## Advanced Features
-
-### Trial Mode
-
-Dry-run workflows without side effects; simulate failures.
-
-```typescript
-import { stableWorkflow } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'process',
-    requests: [
-      {
-        id: 'api-call',
-        requestOptions: {
-          reqData: { path: '/payment/charge' },
-          resReq: true,
-          trialMode: {
-            enabled: true,
-            requestFailureProbability: 0.3 // 30% simulated failure rate
-          }
-        }
-      }
-    ]
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'payment-trial',
-  trialMode: {
+(async () => {
+  const sharedBuffer = new StableBuffer({
+    initialState: {}
+  });
+
+  const circuitBreakerPersistence: InfrastructurePersistence<CircuitBreakerPersistedState> = {
+    load: async (): Promise<CircuitBreakerPersistedState | null> => await loadCircuitBreakerState(),
+    store: async (state: CircuitBreakerPersistedState): Promise<void> => await saveCircuitBreakerState(state),
+    buffer: sharedBuffer  // Use StableBuffer for coordination
+  };
+
+  const circuitBreakerConfig: CircuitBreakerConfig = {
+    failureThresholdPercentage: 50,
+    minimumRequests: 10,
+    recoveryTimeoutMs: 30000,
+    persistence: circuitBreakerPersistence
+  };
+
+  const cachePersistence: InfrastructurePersistence<CacheManagerPersistedState> = {
+    load: async (): Promise<CacheManagerPersistedState | null> => await loadCacheState(),
+    store: async (state: CacheManagerPersistedState): Promise<void> => await saveCacheState(state)
+  };
+
+  const cacheConfig: CacheConfig = {
     enabled: true,
-    functionFailureProbability: 0.2
-  }
-});
-
-// Requests/functions execute but failures are simulated
-// Real API calls happen; real side effects occur only if enabled
-// Useful for testing retry logic, decision hooks, workflow topology
-```
-
-### State Persistence
-
-Persist state across retry attempts for distributed tracing.
-
-The `persistenceFunction` receives a `persistenceStage` parameter (`PersistenceStage.BEFORE_HOOK` or `PersistenceStage.AFTER_HOOK`) to indicate when it is called.
-
-```typescript
-import { stableRequest, PersistenceStage } from '@emmvish/stable-request';
-
-interface DataRequest {}
-interface DataResponse { data: any; }
-
-const result = await stableRequest<DataRequest, DataResponse>({
-  reqData: { path: '/data' },
-  resReq: true,
-  attempts: 3,
-  statePersistence: {
-    persistenceFunction: async ({ executionContext, buffer, params, persistenceStage }) => {
-      const key = `${executionContext.workflowId}:${executionContext.requestId}`;
-      if (persistenceStage === PersistenceStage.BEFORE_HOOK || params?.operation === 'load') {
-        // Load state for recovery
-        return await loadFromDatabase(key);
-      }
-      // Save state to database or distributed cache
-      await saveToDatabase({ key, state: buffer });
-      return buffer;
+    persistence: cachePersistence
+  };
+
+  const result: STABLE_REQUEST_RESULT<ApiResponse> = await stableRequest<void, ApiResponse>({
+    reqData: { 
+      hostname: 'api.example.com', 
+      path: '/data',
+      method: REQUEST_METHODS.GET
     },
-    persistenceParams: { operation: 'save' },
-    loadBeforeHooks: true,
-    storeAfterHooks: true
-  }
-});
-```
-
-### Mixed Request & Function Phases
-
-Combine API calls and computations in single phases with full type safety.
-
-```typescript
-import { stableWorkflow, RequestOrFunction } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE, API_GATEWAY_ITEM } from '@emmvish/stable-request';
-
-// Request types
-interface ProductRequest {}\ninterface ProductResponse {
-  id: number;
+    resReq: true,
+    circuitBreaker: circuitBreakerConfig,
+    cache: cacheConfig
+  });
+})();
+```
+
+## Complete Example
+
+```typescript
+import { 
+  stableRequest, 
+  StableBuffer, 
+  RETRY_STRATEGIES,
+  REQUEST_METHODS 
+} from 'stable-request';
+import type {
+  STABLE_REQUEST_RESULT,
+  StableBufferTransactionLog,
+  CircuitBreakerConfig,
+  CacheConfig,
+  MetricsGuardrails,
+  ExecutionContext,
+  ResponseAnalysisHookOptions,
+  HandleErrorHookOptions,
+  ERROR_LOG
+} from 'stable-request';
+
+// Define response and request types
+interface UserRequest {
   name: string;
-  price: number;
-}
-
-interface InventoryRequest {}
-interface InventoryResponse {
-  productId: number;
-  stock: number;
 }
 
-// Function types
-type EnrichArgs = [ProductResponse[], InventoryResponse[]];
-type EnrichResult = Array<{
-  id: number;
-  name: string;
-  price: number;
-  stock: number;
-  inStock: boolean;
-}>;
-
-type CalculateArgs = [EnrichResult];
-type CalculateResult = {
-  totalValue: number;
-  lowStockItems: number;
-};
-
-type NotifyArgs = [CalculateResult, string];
-type NotifyResult = { notified: boolean };
-
-const phase: STABLE_WORKFLOW_PHASE<
-  ProductRequest | InventoryRequest,
-  ProductResponse | InventoryResponse,
-  EnrichArgs | CalculateArgs | NotifyArgs,
-  EnrichResult | CalculateResult | NotifyResult
-> = {
-  id: 'mixed-phase',
-  items: [
-    {
-      type: RequestOrFunction.REQUEST,
-      request: {
-        id: 'fetch-products',
-        requestOptions: {
-          reqData: { path: '/products' },
-          resReq: true
-        }
-      }
-    },
-    {
-      type: RequestOrFunction.REQUEST,
-      request: {
-        id: 'fetch-inventory',
-        requestOptions: {
-          reqData: { path: '/inventory' },
-          resReq: true
-        }
-      }
-    },
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'enrich-products',
-        functionOptions: {
-          fn: (products: ProductResponse[], inventory: InventoryResponse[]): EnrichResult => {
-            return products.map(product => {
-              const inv = inventory.find(i => i.productId === product.id);
-              return {
-                ...product,
-                stock: inv?.stock || 0,
-                inStock: (inv?.stock || 0) > 0
-              };
-            });
-          },
-          args: [[], []] as EnrichArgs,
-          returnResult: true,
-          cache: { enabled: true, ttl: 30000 }
-        }
-      }
-    },
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'calculate-metrics',
-        functionOptions: {
-          fn: (enriched: EnrichResult): CalculateResult => ({
-            totalValue: enriched.reduce((sum, p) => sum + (p.price * p.stock), 0),
-            lowStockItems: enriched.filter(p => p.stock < 10 && p.stock > 0).length
-          }),
-          args: [[]] as CalculateArgs,
-          returnResult: true
-        }
-      }
-    },
-    {
-      type: RequestOrFunction.FUNCTION,
-      function: {
-        id: 'notify-if-needed',
-        functionOptions: {
-          fn: async (metrics: CalculateResult, channel: string): Promise<NotifyResult> => {
-            if (metrics.lowStockItems > 5) {
-              console.log(`Sending alert to ${channel}: ${metrics.lowStockItems} items low`);
-              return { notified: true };
-            }
-            return { notified: false };
-          },
-          args: [{ totalValue: 0, lowStockItems: 0 }, 'slack'] as NotifyArgs,
-          returnResult: true,
-          attempts: 3,
-          wait: 1000
-        }
-      }
-    }
-  ]
-};
-
-const result = await stableWorkflow([phase], {
-  workflowId: 'mixed-execution',
-  sharedBuffer: {}
-});
-```
-
----
-
-## Best Practices
-
-### 1. Start Conservative, Override When Needed
-
-Define global defaults; override only where necessary.
-
-```typescript
-await stableWorkflow(phases, {
-  // Global defaults (conservative)
-  commonAttempts: 3,
-  commonWait: 500,
-  retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
-  
-  // Override for specific phase
-  phases: [
-    {
-      id: 'fast-phase',
-      attempts: 1, // Override: no retries
-      requests: [...]
-    }
-  ]
-});
-```
-
-### 2. Validate Responses
-
-Use analyzers to ensure data shape and freshness.
-
-```typescript
-interface DataRequest {}
-interface ApiResponse {
-  id: number;
-  lastUpdated: string;
-}
-
-const result = await stableRequest<DataRequest, ApiResponse>({
-  reqData: { path: '/data' },
-  resReq: true,
-  responseAnalyzer: ({ data }) => {
-    if (!data || typeof data !== 'object') return false;
-    if (!('id' in data && 'lastUpdated' in data)) return false;
-    const age = Date.now() - new Date((data as any).lastUpdated).getTime();
-    if (age > 60000) return false; // Data older than 1 minute
-    return true;
-  }
-});
-```
-
-### 3. Cache Idempotent Reads Aggressively
-
-Reduce latency and load on dependencies.
-
-```typescript
-interface UserRequest {}
 interface UserResponse {
-  id: number;
+  id: string;
   name: string;
+  createdAt: string;
 }
 
-const userCache = new CacheManager({
-  enabled: true,
-  ttl: 30000, // 30 seconds
-  respectCacheControl: true
-});
-
-await stableRequest<UserRequest, UserResponse>({
-  reqData: { path: '/users/1' },
-  resReq: true,
-  cache: userCache
-});
-
-await stableRequest<UserRequest, UserResponse>({
-  reqData: { path: '/users/1' },
-  resReq: true,
-  cache: userCache // Cached within 30s
-});
-```
-
-### 4. Use Circuit Breaker for Unstable Services
-
-Protect against cascading failures.
-
-```typescript
-interface ServiceRequest {}
-interface ServiceResponse { status: string; data: any; }
-
-const unstabledServiceBreaker = new CircuitBreaker({
-  failureThresholdPercentage: 40,
-  minimumRequests: 5,
-  recoveryTimeoutMs: 30000,
-  successThresholdPercentage: 80
-});
+(async () => {
+  // Create shared buffer for state management
+  const buffer = new StableBuffer({
+    initialState: { 
+      requestCount: 0,
+      errors: [] as ERROR_LOG[]
+    },
+    logTransaction: async (log: StableBufferTransactionLog): Promise<void> => {
+      await persistTransactionLog(log);
+    }
+  });
 
-await stableApiGateway<ServiceRequest, ServiceResponse>(requests, {
-  circuitBreaker: unstabledServiceBreaker
-});
-```
+  // Define typed configurations
+  const circuitBreakerConfig: CircuitBreakerConfig = {
+    failureThresholdPercentage: 50,
+    minimumRequests: 5,
+    recoveryTimeoutMs: 30000
+  };
 
-### 6. Define Metrics Guardrails for SLA Monitoring
+  const cacheConfig: CacheConfig = {
+    enabled: true,
+    ttl: 60000
+  };
 
-Enforce performance and reliability SLAs with automatic validation.
+  const executionContext: ExecutionContext = {
+    workflowId: 'user-creation',
+    requestId: 'create-user-001'
+  };
 
-```typescript
-import { stableWorkflow, MetricsGuardrails } from '@emmvish/stable-request';
-import type { STABLE_WORKFLOW_PHASE } from '@emmvish/stable-request';
-
-interface ApiRequest {}
-interface ApiResponse { data: any; }
-
-const phases: STABLE_WORKFLOW_PHASE<ApiRequest, ApiResponse>[] = [
-  {
-    id: 'critical-phase',
-    requests: [{ id: 'req-1', requestOptions: { reqData: { path: '/critical' }, resReq: true } }],
-    metricsGuardrails: {
-      phase: {
-        executionTime: { max: 3000 },        // SLA: <3s
-        requestSuccessRate: { min: 99.5 }    // SLA: 99.5% success
-      }
-    }
-  }
-];
-
-const result = await stableWorkflow(phases, {
-  workflowId: 'sla-monitored',
-  metricsGuardrails: {
-    workflow: {
-      executionTime: { max: 10000 },         // Workflow SLA: <10s
-      requestSuccessRate: { min: 99 }        // Workflow SLA: 99% success
+  const metricsGuardrails: MetricsGuardrails = {
+    request: {
+      totalExecutionTime: { max: 15000 },
+      failedAttempts: { max: 2 }
     }
+  };
+
+  // Make a resilient request
+  const result: STABLE_REQUEST_RESULT<UserResponse> = await stableRequest<UserRequest, UserResponse>({
+    reqData: {
+      hostname: 'api.example.com',
+      path: '/users',
+      method: REQUEST_METHODS.POST,
+      body: { name: 'John Doe' },
+      headers: { 'Content-Type': 'application/json' },
+      timeout: 10000
+    },
+    resReq: true,
+    attempts: 3,
+    wait: 1000,
+    retryStrategy: RETRY_STRATEGIES.EXPONENTIAL,
+    jitter: 0.2,
+    
+    commonBuffer: buffer,
+    
+    circuitBreaker: circuitBreakerConfig,
+    cache: cacheConfig,
+    
+    responseAnalyzer: async (options: ResponseAnalysisHookOptions<UserRequest, UserResponse>): Promise<boolean> => {
+      const { data, commonBuffer } = options;
+      if (commonBuffer) commonBuffer.requestCount += 1;
+      return data.id !== undefined;
+    },
+    
+    logAllErrors: true,
+    handleErrors: async (options: HandleErrorHookOptions<UserRequest>): Promise<void> => {
+      const { errorLog, commonBuffer } = options;
+      if (commonBuffer) commonBuffer.errors.push(errorLog);
+    },
+    
+    executionContext,
+    metricsGuardrails
+  });
+
+  if (result.success) {
+    console.log('User created:', result.data);
+  } else {
+    console.error('Failed:', result.error);
   }
-});
-
-// Automatic SLA violation detection
-if (result.validation && !result.validation.isValid) {
-  const criticalAnomalies = result.validation.anomalies.filter(a => a.severity === 'CRITICAL');
-  if (criticalAnomalies.length > 0) {
-    // Trigger alerts for SLA violations
-    console.error('SLA violated:', criticalAnomalies);
-  }
-}
-```
-
-### 6. Apply Rate & Concurrency Limits
-
-Respect external quotas and capacity.
-
-```typescript
-interface ApiRequest {}
-interface ApiResponse { result: any; }
-
-// API allows 100 req/second, use 80% headroom
-const rateLimit = { maxRequests: 80, windowMs: 1000 };
-
-// Database connection pool has 10 slots, use 5
-const maxConcurrent = 5;
 
-await stableApiGateway<ApiRequest, ApiResponse>(requests, {
-  rateLimit,
-  maxConcurrentRequests: maxConcurrent
-});
+  console.log('Metrics:', result.metrics);
+  console.log('Buffer state:', buffer.read());
+})();
 ```
 
-### 6. Use Shared Buffers for Cross-Phase Coordination
+## TypeScript Support
 
-Avoid global state; pass computed data cleanly.
+This library is written in TypeScript and includes full type definitions:
 
 ```typescript
-const sharedBuffer = {};
-
-await stableWorkflow(phases, {
-  sharedBuffer,
-  // Phase 1 writes userId to sharedBuffer
-  // Phase 2 reads userId from sharedBuffer
-  // Phase 3 uses both
-});
+import type {
+  STABLE_REQUEST,
+  STABLE_REQUEST_RESULT,
+  StableBufferOptions,
+  StableBufferTransactionLog,
+  CircuitBreakerConfig,
+  CacheConfig,
+  MetricsGuardrails
+} from 'stable-request';
 ```
 
-### 7. Log Selectively with Max Serialization Cap
+## Migration to stable-infra
 
-Prevent noisy logs from large payloads.
+If you need workflows, schedulers, or advanced orchestration, migrating to stable-infra is straightforward:
 
 ```typescript
-interface DataRequest {}
-interface DataResponse { data: any; }
-
-await stableRequest<DataRequest, DataResponse>({
-  reqData: { path: '/data' },
-  resReq: true,
-  maxSerializableChars: 500, // Truncate logs to 500 chars
-  handleSuccessfulAttemptData: ({ successfulAttemptData, maxSerializableChars }) => {
-    console.log(safelyStringify(successfulAttemptData, maxSerializableChars));
-  }
-});
-```
-
-### 8. Use Non-Linear Workflows for Polling
-
-REPLAY action simplifies polling logic.
+// stable-request
+import { stableRequest } from 'stable-request';
 
-```typescript
-const phases: STABLE_WORKFLOW_PHASE[] = [
-  {
-    id: 'wait-for-job',
-    allowReplay: true,
-    maxReplayCount: 10,
-    requests: [
-      {
-        id: 'check-status',
-        requestOptions: {
-          reqData: { path: '/jobs/123' },
-          resReq: true,
-          attempts: 1
-        }
-      }
-    ],
-    phaseDecisionHook: async ({ phaseResult }) => {
-      const status = (phaseResult.responses[0].data as any)?.status;
-      if (status === 'pending') {
-        return { action: PHASE_DECISION_ACTIONS.REPLAY };
-      }
-      return { action: PHASE_DECISION_ACTIONS.CONTINUE };
-    }
-  }
-];
+// stable-infra (same API, more features)
+import { stableRequest } from 'stable-infra';
 
-await stableWorkflow(phases, {
-  enableNonLinearExecution: true
-});
-```
-
-### 9. Use Graph Workflows for Complex Parallelism
-
-DAGs make dependencies explicit and enable maximum parallelism.
-
-```typescript
-// Clearer than 6 phases with conditional concurrency markers
-const graph = new WorkflowGraphBuilder()
-  .addParallelGroup('fetch', ['fetch-users', 'fetch-posts', 'fetch-comments'])
-  .addMergePoint('sync', ['fetch'])
-  .addPhase('aggregate', {...})
-  .connectSequence('fetch', 'sync', 'aggregate')
-  .build();
-
-await stableWorkflowGraph(graph);
+// Plus you get access to:
+import { 
+  stableWorkflow,
+  stableApiGateway,
+  stableFunction,
+  stableScheduler,
+  stableWorkflowGraph
+} from 'stable-infra';
 ```
 
-### 10. Prefer Dry-Run (Trial Mode) Before Production
+## License
 
-Test workflows and retry logic safely.
-
-```typescript
-await stableWorkflow(phases, {
-  workflowId: 'payment-pipeline',
-  trialMode: { enabled: true }, // Dry-run before production
-  handlePhaseCompletion: ({ phaseResult }) => {
-    console.log(`Trial phase: ${phaseResult.phaseId}, success=${phaseResult.success}`);
-  }
-});
-
-// If satisfied, deploy with trialMode: { enabled: false }
-```
+MIT
 
 ---
 
-## Summary
-
-@emmvish/stable-request provides a unified, type-safe framework for resilient execution:
-
-- **Single calls** via `stableRequest` (APIs) or `stableFunction` (pure functions)
-- **Batch orchestration** via `stableApiGateway` (concurrent/sequential mixed items)
-- **Phased workflows** via `stableWorkflow` (array-based, non-linear, branched)
-- **Graph workflows** via `stableWorkflowGraph` (DAG, explicit parallelism)
-
-All modes inherit robust resilience (retries, jitter, circuit breaking, caching, rate/concurrency limits), config cascading, shared state, hooks, and metrics. Use together or independently; compose freely.
-
-Build resilient, observable, type-safe systems with confidence.
+**stable-request** is now in maintenance mode. For new projects, please use [**stable-infra**](https://npmjs.com/package/@emmvish/stable-infra).