@git-stunts/alfred 0.2.1 → 0.3.0

package/README.md

@@ -14,20 +14,22 @@ o88o     o8888o o888o o888o   d888b    `Y8bod8P' `Y8bod88P"
 [![NPM Version](https://img.shields.io/npm/v/@git-stunts/alfred)](https://www.npmjs.com/package/@git-stunts/alfred)
 [![CI](https://github.com/git-stunts/alfred/actions/workflows/ci.yml/badge.svg)](https://github.com/git-stunts/alfred/actions/workflows/ci.yml)
 
-> *"Why do we fall, Bruce?"*
+> _"Why do we fall, Bruce?"_
 >
-> *"So we can `retry({ backoff: 'exponential', jitter: 'decorrelated' })`."*
+> _"So we can `retry({ backoff: 'exponential', jitter: 'decorrelated' })`."_
 
-Resilience patterns for async operations. *Tuff 'nuff for most stuff!*
+Resilience patterns for async operations. _Tuff 'nuff for most stuff!_
 
 ## Installation
 
 ### NPM
+
 ```bash
 npm install @git-stunts/alfred
 ```
 
 ### JSR (Deno, Bun, Node)
+
 ```bash
 npx jsr add @git-stunts/alfred
 ```
@@ -35,6 +37,7 @@ npx jsr add @git-stunts/alfred
 ## Multi-Runtime Support
 
 Alfred is designed to be platform-agnostic and is tested against:
+
 - **Node.js** (>= 20.0.0)
 - **Bun** (>= 1.0.0)
 - **Deno** (>= 1.35.0)
@@ -47,10 +50,11 @@ It uses standard Web APIs (AbortController, AbortSignal) and provides runtime-aw
 import { retry, circuitBreaker, timeout, compose } from '@git-stunts/alfred';
 
 // Simple retry with exponential backoff
-const data = await retry(
-  () => fetch('https://api.example.com/data'),
-  { retries: 3, backoff: 'exponential', delay: 100 }
-);
+const data = await retry(() => fetch('https://api.example.com/data'), {
+  retries: 3,
+  backoff: 'exponential',
+  delay: 100,
+});
 
 // Circuit breaker - fail fast when service is down
 const breaker = circuitBreaker({ threshold: 5, duration: 60000 });
@@ -84,13 +88,13 @@ await retry(() => mightFail(), {
   retries: 5,
   backoff: 'exponential',
   delay: 100,
-  maxDelay: 10000
+  maxDelay: 10000,
 });
 
 // Only retry specific errors
 await retry(() => mightFail(), {
   retries: 3,
-  shouldRetry: (err) => err.code === 'ECONNREFUSED'
+  shouldRetry: (err) => err.code === 'ECONNREFUSED',
 });
 
 // With jitter to prevent thundering herd
@@ -98,21 +102,21 @@ await retry(() => mightFail(), {
   retries: 3,
   backoff: 'exponential',
   delay: 100,
-  jitter: 'full' // or 'equal' or 'decorrelated'
+  jitter: 'full', // or 'equal' or 'decorrelated'
 });
 ```
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `retries` | `number` | `3` | Maximum retry attempts |
-| `delay` | `number` | `1000` | Base delay in milliseconds |
-| `maxDelay` | `number` | `30000` | Maximum delay cap |
-| `backoff` | `'constant' \| 'linear' \| 'exponential'` | `'constant'` | Backoff strategy |
-| `jitter` | `'none' \| 'full' \| 'equal' \| 'decorrelated'` | `'none'` | Jitter strategy |
-| `shouldRetry` | `(error) => boolean` | `() => true` | Predicate to filter retryable errors |
-| `onRetry` | `(error, attempt, delay) => void` | - | Callback on each retry |
+| Option        | Type                                            | Default      | Description                          |
+| ------------- | ----------------------------------------------- | ------------ | ------------------------------------ |
+| `retries`     | `number`                                        | `3`          | Maximum retry attempts               |
+| `delay`       | `number`                                        | `1000`       | Base delay in milliseconds           |
+| `maxDelay`    | `number`                                        | `30000`      | Maximum delay cap                    |
+| `backoff`     | `'constant' \| 'linear' \| 'exponential'`       | `'constant'` | Backoff strategy                     |
+| `jitter`      | `'none' \| 'full' \| 'equal' \| 'decorrelated'` | `'none'`     | Jitter strategy                      |
+| `shouldRetry` | `(error) => boolean`                            | `() => true` | Predicate to filter retryable errors |
+| `onRetry`     | `(error, attempt, delay) => void`               | -            | Callback on each retry               |
 
 ### `circuitBreaker(options)`
 
@@ -122,11 +126,11 @@ Fails fast when a service is degraded, preventing cascade failures.
 import { circuitBreaker } from '@git-stunts/alfred';
 
 const breaker = circuitBreaker({
-  threshold: 5,      // Open after 5 failures
-  duration: 60000,   // Stay open for 60 seconds
+  threshold: 5, // Open after 5 failures
+  duration: 60000, // Stay open for 60 seconds
   onOpen: () => console.log('Circuit opened!'),
   onClose: () => console.log('Circuit closed!'),
-  onHalfOpen: () => console.log('Testing recovery...')
+  onHalfOpen: () => console.log('Testing recovery...'),
 });
 
 // Circuit has three states:
@@ -145,15 +149,15 @@ try {
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `threshold` | `number` | required | Failures before opening |
-| `duration` | `number` | required | How long to stay open (ms) |
-| `successThreshold` | `number` | `1` | Successes to close from half-open |
-| `shouldTrip` | `(error) => boolean` | `() => true` | Which errors count as failures |
-| `onOpen` | `() => void` | - | Called when circuit opens |
-| `onClose` | `() => void` | - | Called when circuit closes |
-| `onHalfOpen` | `() => void` | - | Called when entering half-open |
+| Option             | Type                 | Default      | Description                       |
+| ------------------ | -------------------- | ------------ | --------------------------------- |
+| `threshold`        | `number`             | required     | Failures before opening           |
+| `duration`         | `number`             | required     | How long to stay open (ms)        |
+| `successThreshold` | `number`             | `1`          | Successes to close from half-open |
+| `shouldTrip`       | `(error) => boolean` | `() => true` | Which errors count as failures    |
+| `onOpen`           | `() => void`         | -            | Called when circuit opens         |
+| `onClose`          | `() => void`         | -            | Called when circuit closes        |
+| `onHalfOpen`       | `() => void`         | -            | Called when entering half-open    |
 
 ### `bulkhead(options)`
 
@@ -163,8 +167,8 @@ Limits the number of concurrent executions to prevent resource exhaustion.
 import { bulkhead } from '@git-stunts/alfred';
 
 const limiter = bulkhead({
-  limit: 10,       // Max 10 concurrent executions
-  queueLimit: 20   // Max 20 pending requests in queue
+  limit: 10, // Max 10 concurrent executions
+  queueLimit: 20, // Max 20 pending requests in queue
 });
 
 // Returns an object with:
@@ -183,10 +187,10 @@ console.log(`Current load: ${limiter.stats.active} active tasks`);
 
 **Options:**
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `limit` | `number` | required | Maximum concurrent executions |
-| `queueLimit` | `number` | `0` | Maximum pending requests in queue |
+| Option       | Type     | Default  | Description                       |
+| ------------ | -------- | -------- | --------------------------------- |
+| `limit`      | `number` | required | Maximum concurrent executions     |
+| `queueLimit` | `number` | `0`      | Maximum pending requests in queue |
 
 ### `timeout(ms, options)`
 
@@ -200,7 +204,7 @@ const result = await timeout(5000, () => slowOperation());
 
 // With callback
 const result = await timeout(5000, () => slowOperation(), {
-  onTimeout: (elapsed) => console.log(`Timed out after ${elapsed}ms`)
+  onTimeout: (elapsed) => console.log(`Timed out after ${elapsed}ms`),
 });
 ```
 
@@ -231,10 +235,10 @@ Combines multiple policies. Policies execute from left to right (outermost to in
 import { compose, retry, circuitBreaker, timeout } from '@git-stunts/alfred';
 
 const resilient = compose(
-  timeout(30000),                                    // Total timeout
-  retry({ retries: 3, backoff: 'exponential' }),     // Retry failures
+  timeout(30000), // Total timeout
+  retry({ retries: 3, backoff: 'exponential' }), // Retry failures
   circuitBreaker({ threshold: 5, duration: 60000 }), // Fail fast if broken
-  bulkhead({ limit: 5, queueLimit: 10 })             // Limit concurrency
+  bulkhead({ limit: 5, queueLimit: 10 }) // Limit concurrency
 );
 
 // Execution order:
@@ -249,23 +253,15 @@ await resilient.execute(() => riskyOperation());
 Alfred provides a composable telemetry system to monitor policy behavior.
 
 ```javascript
-import {
-  Policy,
-  ConsoleSink,
-  InMemorySink,
-  MultiSink
-} from '@git-stunts/alfred';
+import { Policy, ConsoleSink, InMemorySink, MultiSink } from '@git-stunts/alfred';
 
 // 1. Create a sink (or multiple)
-const sink = new MultiSink([
-  new ConsoleSink(),
-  new InMemorySink()
-]);
+const sink = new MultiSink([new ConsoleSink(), new InMemorySink()]);
 
 // 2. Attach to policies
 const policy = Policy.retry({
   retries: 3,
-  telemetry: sink
+  telemetry: sink,
 });
 
 // All policies emit events:
@@ -297,7 +293,7 @@ test('retries with exponential backoff', async () => {
     retries: 3,
     backoff: 'exponential',
     delay: 1000,
-    clock
+    clock,
   });
 
   // First attempt fails immediately
@@ -319,11 +315,7 @@ test('retries with exponential backoff', async () => {
 ## Error Types
 
 ```javascript
-import {
-  RetryExhaustedError,
-  CircuitOpenError,
-  TimeoutError
-} from '@git-stunts/alfred';
+import { RetryExhaustedError, CircuitOpenError, TimeoutError } from '@git-stunts/alfred';
 
 try {
   await resilientOperation();

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@git-stunts/alfred",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Why do we fall, Bruce? Production-grade resilience patterns for async operations.",
-
   "type": "module",
   "main": "src/index.js",
   "types": "./src/index.d.ts",

package/src/compose.js

@@ -33,7 +33,7 @@
 export function compose(...policies) {
   if (policies.length === 0) {
     return {
-      execute: (fn) => fn()
+      execute: (fn) => fn(),
     };
   }
 
@@ -55,7 +55,7 @@ export function compose(...policies) {
       }
 
       return chain();
-    }
+    },
   };
 }
 
@@ -86,7 +86,7 @@ export function fallback(primary, secondary) {
       } catch {
         return await secondary.execute(fn);
       }
-    }
+    },
   };
 }
 
@@ -148,6 +148,6 @@ export function race(policyA, policyB) {
         policyA.execute(fn).then(handleSuccess, (e) => handleFailure(e, true));
         policyB.execute(fn).then(handleSuccess, (e) => handleFailure(e, false));
       });
-    }
+    },
   };
 }

package/src/index.d.ts

@@ -2,35 +2,40 @@
  * @module @git-stunts/alfred
  * @description Production-grade resilience patterns for async operations.
  * Includes Retry, Circuit Breaker, Timeout, and Bulkhead policies.
- * 
+ *
  * @example
  * ```ts
  * import { compose, retry, circuitBreaker, timeout } from "@git-stunts/alfred";
- * 
+ *
  * const policy = compose(
  *   retry({ retries: 3 }),
  *   circuitBreaker({ threshold: 5, duration: 60000 }),
  *   timeout(5000)
  * );
- * 
+ *
  * await policy.execute(() => fetch("https://api.example.com"));
  * ```
  */
 
+/**
+ * A value that can be either static or resolved dynamically via a function.
+ */
+export type Resolvable<T> = T | (() => T);
+
 /**
  * Options for the Retry policy.
  */
 export interface RetryOptions {
   /** Maximum number of retry attempts. Default: 3 */
-  retries?: number;
+  retries?: Resolvable<number>;
   /** Base delay in milliseconds. Default: 1000 */
-  delay?: number;
+  delay?: Resolvable<number>;
   /** Maximum delay cap in milliseconds. Default: 30000 */
-  maxDelay?: number;
+  maxDelay?: Resolvable<number>;
   /** Backoff strategy. Default: 'constant' */
-  backoff?: 'constant' | 'linear' | 'exponential';
+  backoff?: Resolvable<'constant' | 'linear' | 'exponential'>;
   /** Jitter strategy to prevent thundering herd. Default: 'none' */
-  jitter?: 'none' | 'full' | 'equal' | 'decorrelated';
+  jitter?: Resolvable<'none' | 'full' | 'equal' | 'decorrelated'>;
   /** Predicate to determine if an error is retryable. Default: always true */
   shouldRetry?: (error: Error) => boolean;
   /** Callback invoked before each retry. */
@@ -46,11 +51,11 @@ export interface RetryOptions {
  */
 export interface CircuitBreakerOptions {
   /** Number of failures before opening the circuit. */
-  threshold: number;
+  threshold: Resolvable<number>;
   /** Milliseconds to stay open before transitioning to half-open. */
-  duration: number;
+  duration: Resolvable<number>;
   /** Consecutive successes required to close the circuit from half-open. Default: 1 */
-  successThreshold?: number;
+  successThreshold?: Resolvable<number>;
   /** Predicate to determine if an error counts as a failure. Default: always true */
   shouldTrip?: (error: Error) => boolean;
   /** Callback when circuit opens. */
@@ -80,9 +85,23 @@ export interface TimeoutOptions {
  */
 export interface BulkheadOptions {
   /** Maximum concurrent executions. */
-  limit: number;
+  limit: Resolvable<number>;
   /** Maximum pending requests in queue. Default: 0 */
-  queueLimit?: number;
+  queueLimit?: Resolvable<number>;
+  /** Telemetry sink for observability. */
+  telemetry?: TelemetrySink;
+  /** Clock implementation for testing. */
+  clock?: any;
+}
+
+/**
+ * Options for the Hedge policy.
+ */
+export interface HedgeOptions {
+  /** Milliseconds to wait before spawning a hedge. */
+  delay: Resolvable<number>;
+  /** Maximum number of hedged attempts to spawn. Default: 1 */
+  maxHedges?: Resolvable<number>;
   /** Telemetry sink for observability. */
   telemetry?: TelemetrySink;
   /** Clock implementation for testing. */
@@ -97,6 +116,8 @@ export interface TelemetryEvent {
   type: string;
   /** Unix timestamp of the event. */
   timestamp: number;
+  /** Metric increments (counters) to be aggregated by MetricsSink. */
+  metrics?: Record<string, number>;
   /** Additional metadata (error, duration, attempts, etc.). */
   [key: string]: any;
 }
@@ -143,6 +164,34 @@ export class MultiSink implements TelemetrySink {
   emit(event: TelemetryEvent): void;
 }
 
+/**
+ * Sink that aggregates metrics in memory.
+ */
+export class MetricsSink implements TelemetrySink {
+  emit(event: TelemetryEvent): void;
+  /** Returns a snapshot of the current metrics. */
+  get stats(): {
+    retries: number;
+    failures: number;
+    successes: number;
+    circuitBreaks: number;
+    circuitRejections: number;
+    bulkheadRejections: number;
+    timeouts: number;
+    hedges: number;
+    latency: {
+      count: number;
+      sum: number;
+      min: number;
+      max: number;
+      avg: number;
+    };
+    [key: string]: number | { count: number; sum: number; min: number; max: number; avg: number };
+  };
+  /** Resets all metrics to zero. */
+  clear(): void;
+}
+
 /**
  * Error thrown when all retry attempts are exhausted.
  */
@@ -181,7 +230,7 @@ export class BulkheadRejectedError extends Error {
 
 /**
  * Executes an async function with configurable retry logic.
- * 
+ *
  * @param fn The async operation to execute.
  * @param options Retry configuration options.
  * @returns The result of the operation.
@@ -205,19 +254,23 @@ export interface CircuitBreaker {
 
 /**
  * Creates a Circuit Breaker policy.
- * 
+ *
  * @param options Configuration options.
  */
 export function circuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
 /**
  * Executes a function with a time limit.
- * 
+ *
  * @param ms Timeout duration in milliseconds.
  * @param fn The function to execute. Accepts an AbortSignal if defined.
  * @param options Configuration options.
  */
-export function timeout<T>(ms: number, fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>), options?: TimeoutOptions): Promise<T>;
+export function timeout<T>(
+  ms: Resolvable<number>,
+  fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>),
+  options?: TimeoutOptions
+): Promise<T>;
 
 /**
  * Represents a Bulkhead instance.
@@ -235,15 +288,28 @@ export interface Bulkhead {
 
 /**
  * Creates a Bulkhead policy for concurrency limiting.
- * 
+ *
  * @param options Configuration options.
  */
 export function bulkhead(options: BulkheadOptions): Bulkhead;
 
+/**
+ * Represents a Hedge policy instance.
+ */
+export interface Hedge {
+  execute<T>(fn: (signal?: AbortSignal) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Creates a Hedge policy for speculative execution.
+ * @param options Configuration options.
+ */
+export function hedge(options: HedgeOptions): Hedge;
+
 /**
  * Composes multiple policies into a single executable policy.
  * Policies execute from left to right (outermost to innermost).
- * 
+ *
  * @param policies The policies to compose.
  */
 export function compose(...policies: any[]): { execute<T>(fn: () => Promise<T>): Promise<T> };
@@ -251,12 +317,18 @@ export function compose(...policies: any[]): { execute<T>(fn: () => Promise<T>):
 /**
  * Creates a fallback policy. If the primary policy fails, the secondary is executed.
  */
-export function fallback(primary: any, secondary: any): { execute<T>(fn: () => Promise<T>): Promise<T> };
+export function fallback(
+  primary: any,
+  secondary: any
+): { execute<T>(fn: () => Promise<T>): Promise<T> };
 
 /**
  * Creates a race policy. Executes both policies concurrently; the first to succeed wins.
  */
-export function race(primary: any, secondary: any): { execute<T>(fn: () => Promise<T>): Promise<T> };
+export function race(
+  primary: any,
+  secondary: any
+): { execute<T>(fn: () => Promise<T>): Promise<T> };
 
 /**
  * Fluent API for building resilience policies.
@@ -268,9 +340,11 @@ export class Policy {
   /** Creates a Circuit Breaker policy wrapper. */
   static circuitBreaker(options: CircuitBreakerOptions): Policy;
   /** Creates a Timeout policy wrapper. */
-  static timeout(ms: number, options?: TimeoutOptions): Policy;
+  static timeout(ms: Resolvable<number>, options?: TimeoutOptions): Policy;
   /** Creates a Bulkhead policy wrapper. */
   static bulkhead(options: BulkheadOptions): Policy;
+  /** Creates a Hedge policy wrapper. */
+  static hedge(options: HedgeOptions): Policy;
   /** Creates a pass-through (no-op) policy. */
   static noop(): Policy;
 
@@ -294,4 +368,4 @@ export class TestClock {
   sleep(ms: number): Promise<void>;
   tick(ms?: number): Promise<void>;
   advance(ms: number): Promise<void>;
-}
+}

package/src/index.js

@@ -6,11 +6,11 @@
 // @ts-self-types="./index.d.ts"
 
 // Error types
-export { 
-  RetryExhaustedError, 
-  CircuitOpenError, 
+export {
+  RetryExhaustedError,
+  CircuitOpenError,
   TimeoutError,
-  BulkheadRejectedError 
+  BulkheadRejectedError,
 } from './errors.js';
 
 // Resilience policies
@@ -18,6 +18,7 @@ export { retry } from './policies/retry.js';
 export { circuitBreaker } from './policies/circuit-breaker.js';
 export { timeout } from './policies/timeout.js';
 export { bulkhead } from './policies/bulkhead.js';
+export { hedge } from './policies/hedge.js';
 
 // Composition utilities
 export { compose, fallback, race } from './compose.js';
@@ -27,3 +28,6 @@ export { Policy, Policy as default } from './policy.js';
 
 // Clock utilities
 export { SystemClock, TestClock } from './utils/clock.js';
+
+// Telemetry
+export { InMemorySink, ConsoleSink, NoopSink, MultiSink, MetricsSink } from './telemetry.js';

package/src/policies/bulkhead.js

@@ -10,6 +10,7 @@
 import { BulkheadRejectedError } from '../errors.js';
 import { SystemClock } from '../utils/clock.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve as resolveValue } from '../utils/resolvable.js';
 
 /**
  * @typedef {Object} BulkheadOptions
@@ -28,11 +29,11 @@ import { NoopSink } from '../telemetry.js';
 
 class BulkheadPolicy {
   constructor(options) {
-    const { 
-      limit, 
-      queueLimit = 0, 
+    const {
+      limit,
+      queueLimit = 0,
       telemetry = new NoopSink(),
-      clock = new SystemClock() 
+      clock = new SystemClock(),
     } = options;
 
     if (limit <= 0) {
@@ -49,24 +50,38 @@ class BulkheadPolicy {
   }
 
   processQueue() {
-    if (this.active < this.limit && this.queue.length > 0) {
-      const { fn, resolve, reject } = this.queue.shift();
+    const limit = resolveValue(this.limit);
+    if (this.active < limit && this.queue.length > 0) {
+      const { fn, resolve: promiseResolve, reject } = this.queue.shift();
       this.active++;
-      
+
       this.emitEvent('bulkhead.execute', {
         active: this.active,
-        pending: this.queue.length
+        pending: this.queue.length,
       });
 
       Promise.resolve()
         .then(() => fn())
-        .then(resolve, reject)
+        .then(
+          (result) => {
+            this.emitEvent('bulkhead.complete', {
+              active: this.active,
+              pending: this.queue.length,
+              metrics: { successes: 1 },
+            });
+            promiseResolve(result);
+          },
+          (error) => {
+            this.emitEvent('bulkhead.complete', {
+              active: this.active,
+              pending: this.queue.length,
+              metrics: { failures: 1 },
+            });
+            reject(error);
+          }
+        )
         .finally(() => {
           this.active--;
-          this.emitEvent('bulkhead.complete', {
-            active: this.active,
-            pending: this.queue.length
-          });
           this.processQueue();
         });
     }
@@ -76,36 +91,48 @@ class BulkheadPolicy {
     this.telemetry.emit({
       type,
       timestamp: this.clock.now(),
-      ...data
+      ...data,
     });
   }
 
   async execute(fn) {
-    if (this.active < this.limit) {
+    const limit = resolveValue(this.limit);
+    const queueLimit = resolveValue(this.queueLimit);
+
+    if (this.active < limit) {
       this.active++;
       this.emitEvent('bulkhead.execute', {
         active: this.active,
-        pending: this.queue.length
+        pending: this.queue.length,
       });
 
       try {
-        return await fn();
-      } finally {
-        this.active--;
+        const result = await fn();
+        this.emitEvent('bulkhead.complete', {
+          active: this.active,
+          pending: this.queue.length,
+          metrics: { successes: 1 },
+        });
+        return result;
+      } catch (error) {
         this.emitEvent('bulkhead.complete', {
           active: this.active,
-          pending: this.queue.length
+          pending: this.queue.length,
+          metrics: { failures: 1 },
         });
+        throw error;
+      } finally {
+        this.active--;
         this.processQueue();
       }
     }
 
-    if (this.queue.length < this.queueLimit) {
+    if (this.queue.length < queueLimit) {
       this.emitEvent('bulkhead.queued', {
         active: this.active,
-        pending: this.queue.length + 1
+        pending: this.queue.length + 1,
       });
-      
+
       return new Promise((resolve, reject) => {
         this.queue.push({ fn, resolve, reject });
       });
@@ -113,16 +140,17 @@ class BulkheadPolicy {
 
     this.emitEvent('bulkhead.reject', {
       active: this.active,
-      pending: this.queue.length
+      pending: this.queue.length,
+      metrics: { bulkheadRejections: 1 },
     });
-    throw new BulkheadRejectedError(this.limit, this.queueLimit);
+    throw new BulkheadRejectedError(limit, queueLimit);
   }
 
   get stats() {
-    return { 
-      active: this.active, 
-      pending: this.queue.length, 
-      available: Math.max(0, this.limit - this.active) 
+    return {
+      active: this.active,
+      pending: this.queue.length,
+      available: Math.max(0, resolveValue(this.limit) - this.active),
     };
   }
 }
@@ -135,11 +163,11 @@ class BulkheadPolicy {
  */
 export function bulkhead(options) {
   const policy = new BulkheadPolicy(options);
-  
+
   return {
     execute: (fn) => policy.execute(fn),
     get stats() {
       return policy.stats;
-    }
+    },
   };
-}
+}

package/src/policies/circuit-breaker.js

@@ -1,6 +1,7 @@
 import { CircuitOpenError } from '../errors.js';
 import { SystemClock } from '../utils/clock.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
 
 /**
  * Circuit breaker states.
@@ -10,7 +11,7 @@ import { NoopSink } from '../telemetry.js';
 const State = {
   CLOSED: 'CLOSED',
   OPEN: 'OPEN',
-  HALF_OPEN: 'HALF_OPEN'
+  HALF_OPEN: 'HALF_OPEN',
 };
 
 /**
@@ -43,7 +44,7 @@ class CircuitBreakerPolicy {
       onClose,
       onHalfOpen,
       clock = new SystemClock(),
-      telemetry = new NoopSink()
+      telemetry = new NoopSink(),
     } = options;
 
     if (threshold === undefined || threshold === null) {
@@ -62,7 +63,7 @@ class CircuitBreakerPolicy {
       onClose,
       onHalfOpen,
       clock,
-      telemetry
+      telemetry,
     };
 
     this._state = State.CLOSED;
@@ -79,7 +80,7 @@ class CircuitBreakerPolicy {
     this.options.telemetry.emit({
       type,
       timestamp: this.options.clock.now(),
-      ...data
+      ...data,
     });
   }
 
@@ -87,7 +88,10 @@ class CircuitBreakerPolicy {
     this._state = State.OPEN;
     this.openedAt = new Date(this.options.clock.now());
     this.options.onOpen?.();
-    this.emitEvent('circuit.open', { failureCount: this.failureCount });
+    this.emitEvent('circuit.open', {
+      failureCount: this.failureCount,
+      metrics: { circuitBreaks: 1 },
+    });
   }
 
   close() {
@@ -111,15 +115,18 @@ class CircuitBreakerPolicy {
       return false;
     }
     const elapsed = this.options.clock.now() - this.openedAt.getTime();
-    return elapsed >= this.options.duration;
+    return elapsed >= resolve(this.options.duration);
   }
 
   recordSuccess() {
-    this.emitEvent('circuit.success', { state: this._state });
+    this.emitEvent('circuit.success', {
+      state: this._state,
+      metrics: { successes: 1 },
+    });
 
     if (this._state === State.HALF_OPEN) {
       this.successCount++;
-      if (this.successCount >= this.options.successThreshold) {
+      if (this.successCount >= resolve(this.options.successThreshold)) {
         this.close();
       }
     } else if (this._state === State.CLOSED) {
@@ -134,14 +141,15 @@ class CircuitBreakerPolicy {
 
     this.emitEvent('circuit.failure', {
       error,
-      state: this._state
+      state: this._state,
+      metrics: { failures: 1 },
     });
 
     if (this._state === State.HALF_OPEN) {
       this.open();
     } else if (this._state === State.CLOSED) {
       this.failureCount++;
-      if (this.failureCount >= this.options.threshold) {
+      if (this.failureCount >= resolve(this.options.threshold)) {
         this.open();
       }
     }
@@ -155,7 +163,8 @@ class CircuitBreakerPolicy {
     if (this._state === State.OPEN) {
       this.emitEvent('circuit.reject', {
         openedAt: this.openedAt,
-        failureCount: this.failureCount
+        failureCount: this.failureCount,
+        metrics: { circuitRejections: 1 },
       });
       throw new CircuitOpenError(this.openedAt, this.failureCount);
     }
@@ -184,6 +193,6 @@ export function circuitBreaker(options) {
     execute: (fn) => policy.execute(fn),
     get state() {
       return policy.state;
-    }
+    },
   };
-}
+}

package/src/policies/hedge.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Hedge policy for speculative execution.
+ *
+ * Starts concurrent "hedged" attempts if the primary attempt takes too long,
+ * helping to reduce tail latency in distributed systems.
+ *
+ * @module @git-stunts/alfred/policies/hedge
+ */
+
+import { SystemClock } from '../utils/clock.js';
+import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
+
+/**
+ * @typedef {Object} HedgeOptions
+ * @property {number} delay - Milliseconds to wait before spawning a hedge.
+ * @property {number} [maxHedges=1] - Maximum number of hedged attempts to spawn.
+ * @property {import('../telemetry.js').TelemetrySink} [telemetry] - Telemetry sink.
+ * @property {{ now(): number, sleep(ms: number): Promise<void> }} [clock] - Clock for testing.
+ */
+
+class HedgeExecutor {
+  constructor(fn, options) {
+    this.fn = fn;
+    this.options = {
+      telemetry: new NoopSink(),
+      clock: new SystemClock(),
+      maxHedges: 1,
+      ...options,
+    };
+    this.abortControllers = [];
+    this._finished = false;
+  }
+
+  async execute() {
+    const delay = resolve(this.options.delay);
+    const maxHedges = resolve(this.options.maxHedges);
+    const attempts = [];
+
+    // Start primary attempt
+    attempts.push(this.createAttempt(0));
+
+    // Schedule hedges
+    for (let i = 1; i <= maxHedges; i++) {
+      attempts.push(this.scheduleHedge(i, delay * i));
+    }
+
+    try {
+      return await Promise.any(attempts);
+    } finally {
+      this.cancelAll();
+    }
+  }
+
+  createAttempt(index) {
+    const controller = new AbortController();
+    this.abortControllers.push(controller);
+    const { clock, telemetry } = this.options;
+
+    const startTime = clock.now();
+    telemetry.emit({
+      type: 'hedge.attempt',
+      timestamp: startTime,
+      index,
+      metrics: index > 0 ? { hedges: 1 } : {},
+    });
+
+    return this.fn(controller.signal)
+      .then((result) => {
+        const endTime = clock.now();
+        telemetry.emit({
+          type: 'hedge.success',
+          timestamp: endTime,
+          index,
+          duration: endTime - startTime,
+          metrics: { successes: 1 },
+        });
+        return result;
+      })
+      .catch((error) => {
+        if (error.name !== 'AbortError') {
+          const endTime = clock.now();
+          telemetry.emit({
+            type: 'hedge.failure',
+            timestamp: endTime,
+            index,
+            error,
+            duration: endTime - startTime,
+            metrics: { failures: 1 },
+          });
+        }
+        throw error;
+      });
+  }
+
+  scheduleHedge(index, delayMs) {
+    return this.options.clock.sleep(delayMs).then(() => {
+      if (this._finished) {
+        return new Promise(() => {}); // Never resolve if we are done
+      }
+      return this.createAttempt(index);
+    });
+  }
+
+  cancelAll() {
+    this._finished = true;
+    for (const controller of this.abortControllers) {
+      controller.abort();
+    }
+  }
+}
+
+/**
+ * Creates a Hedge policy.
+ *
+ * @param {HedgeOptions} options - Hedge configuration
+ * @returns {{ execute: <T>(fn: () => Promise<T>) => Promise<T> }}
+ */
+export function hedge(options) {
+  return {
+    execute: (fn) => new HedgeExecutor(fn, options).execute(),
+  };
+}

package/src/policies/retry.js

@@ -11,6 +11,7 @@ import { SystemClock } from '../utils/clock.js';
 import { createJitter } from '../utils/jitter.js';
 import { RetryExhaustedError } from '../errors.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
 
 /**
  * @typedef {'constant' | 'linear' | 'exponential'} BackoffStrategy
@@ -38,7 +39,7 @@ const DEFAULT_OPTIONS = {
   delay: 1000,
   maxDelay: 30000,
   backoff: 'constant',
-  jitter: 'none'
+  jitter: 'none',
 };
 
 function calculateBackoff(strategy, baseDelay, attempt) {
@@ -59,34 +60,38 @@ class RetryExecutor {
     this.options = { ...DEFAULT_OPTIONS, ...options };
     this.clock = options.clock || new SystemClock();
     this.telemetry = options.telemetry || new NoopSink();
-    this.applyJitter = createJitter(this.options.jitter);
-    this.prevDelay = this.options.delay;
+    // this.applyJitter is now created dynamically in calculateDelay
+    this.prevDelay = resolve(this.options.delay);
   }
 
   calculateDelay(attempt) {
-    const { backoff, delay: baseDelay, maxDelay, jitter } = this.options;
+    const backoff = resolve(this.options.backoff);
+    const baseDelay = resolve(this.options.delay);
+    const maxDelay = resolve(this.options.maxDelay);
+    const jitter = resolve(this.options.jitter);
+
     const rawDelay = calculateBackoff(backoff, baseDelay, attempt);
+    const applyJitter = createJitter(jitter);
 
     if (jitter === 'decorrelated') {
-      const actual = this.applyJitter(baseDelay, this.prevDelay, maxDelay);
+      const actual = applyJitter(baseDelay, this.prevDelay, maxDelay);
       this.prevDelay = actual;
       return actual;
     }
-    
-    return Math.min(this.applyJitter(rawDelay), maxDelay);
+
+    return Math.min(applyJitter(rawDelay), maxDelay);
   }
 
   async execute() {
-    const totalAttempts = this.options.retries + 1;
-
-    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
-      const shouldStop = await this.tryAttempt(attempt, totalAttempts);
+    // Loop condition: attempt <= (current_retries + 1)
+    // We start at 1.
+    for (let attempt = 1; attempt <= resolve(this.options.retries) + 1; attempt++) {
+      const shouldStop = await this.tryAttempt(attempt);
       if (shouldStop) {
         return shouldStop.result;
       }
     }
-    
-    // Should be unreachable if logic is correct, but satisfied strict returns
+
     throw new Error('Unexpected retry loop termination');
   }
 
@@ -102,22 +107,24 @@ class RetryExecutor {
       // But we need to calculate delay first
       const delay = this.calculateDelay(attempt);
       this.emitScheduled(attempt, delay, error);
-      
+
       if (this.options.onRetry) {
         this.options.onRetry(error, attempt, delay);
       }
-      
+
       await this.clock.sleep(delay);
       return null; // Continue loop
     }
   }
 
   emitSuccess(attempt, startTime) {
+    const endTime = this.clock.now();
     this.telemetry.emit({
       type: 'retry.success',
-      timestamp: this.clock.now(),
+      timestamp: endTime,
       attempt,
-      duration: this.clock.now() - startTime
+      duration: endTime - startTime,
+      metrics: { successes: 1 },
     });
   }
 
@@ -127,30 +134,33 @@ class RetryExecutor {
       timestamp: this.clock.now(),
       attempt,
       delay,
-      error
+      error,
+      metrics: { retries: 1 },
     });
   }
 
   handleFailure(error, attempt, startTime) {
+    const endTime = this.clock.now();
     this.telemetry.emit({
       type: 'retry.failure',
-      timestamp: this.clock.now(),
+      timestamp: endTime,
       attempt,
       error,
-      duration: this.clock.now() - startTime
+      duration: endTime - startTime,
+      metrics: { failures: 1 },
     });
 
     if (this.options.shouldRetry && !this.options.shouldRetry(error)) {
       throw error;
     }
 
-    const totalAttempts = this.options.retries + 1;
+    const totalAttempts = resolve(this.options.retries) + 1;
     if (attempt >= totalAttempts) {
       this.telemetry.emit({
         type: 'retry.exhausted',
-        timestamp: this.clock.now(),
+        timestamp: endTime,
         attempts: attempt,
-        error
+        error,
       });
       throw new RetryExhaustedError(attempt, error);
     }
@@ -167,4 +177,4 @@ class RetryExecutor {
  */
 export async function retry(fn, options = {}) {
   return new RetryExecutor(fn, options).execute();
-}
+}

package/src/policies/timeout.js

@@ -9,6 +9,7 @@
 
 import { TimeoutError } from '../errors.js';
 import { NoopSink } from '../telemetry.js';
+import { resolve } from '../utils/resolvable.js';
 
 /**
  * @typedef {Object} TimeoutOptions
@@ -45,6 +46,7 @@ import { NoopSink } from '../telemetry.js';
  */
 export async function timeout(ms, fn, options = {}) {
   const { onTimeout, telemetry = new NoopSink() } = options;
+  const timeoutMs = resolve(ms);
   const controller = new AbortController();
   const startTime = Date.now();
 
@@ -58,16 +60,17 @@ export async function timeout(ms, fn, options = {}) {
       if (onTimeout) {
         onTimeout(elapsed);
       }
-      
+
       telemetry.emit({
         type: 'timeout',
         timestamp: Date.now(),
-        timeout: ms,
-        elapsed
+        timeout: timeoutMs,
+        elapsed,
+        metrics: { timeouts: 1, failures: 1 },
       });
 
-      reject(new TimeoutError(ms, elapsed));
-    }, ms);
+      reject(new TimeoutError(timeoutMs, elapsed));
+    }, timeoutMs);
   });
 
   try {

package/src/policy.js

@@ -34,6 +34,7 @@ import { retry } from './policies/retry.js';
 import { circuitBreaker } from './policies/circuit-breaker.js';
 import { timeout } from './policies/timeout.js';
 import { bulkhead } from './policies/bulkhead.js';
+import { hedge } from './policies/hedge.js';
 import { compose, fallback, race } from './compose.js';
 
 /**
@@ -134,6 +135,17 @@ export class Policy {
     return new Policy((fn) => limiter.execute(fn));
   }
 
+  /**
+   * Creates a Policy that speculatively executes hedged attempts.
+   *
+   * @param {import('./policies/hedge.js').HedgeOptions} options
+   * @returns {Policy}
+   */
+  static hedge(options) {
+    const hedger = hedge(options);
+    return new Policy((fn) => hedger.execute(fn));
+  }
+
   /**
    * Creates a no-op Policy that passes through to the function directly.
    *
@@ -181,10 +193,7 @@ export class Policy {
     return new Policy((fn) => {
       // Compose: outer wraps inner
       // When outer calls its "fn", that fn is actually inner's execution
-      return compose(
-        { execute: outer },
-        { execute: inner }
-      ).execute(fn);
+      return compose({ execute: outer }, { execute: inner }).execute(fn);
     });
   }
 
@@ -212,10 +221,7 @@ export class Policy {
     const secondary = otherPolicy._executor;
 
     return new Policy((fn) => {
-      return fallback(
-        { execute: primary },
-        { execute: secondary }
-      ).execute(fn);
+      return fallback({ execute: primary }, { execute: secondary }).execute(fn);
     });
   }
 
@@ -243,10 +249,7 @@ export class Policy {
     const second = otherPolicy._executor;
 
     return new Policy((fn) => {
-      return race(
-        { execute: first },
-        { execute: second }
-      ).execute(fn);
+      return race({ execute: first }, { execute: second }).execute(fn);
     });
   }
 

package/src/telemetry.js

@@ -5,8 +5,9 @@
 
 /**
  * @typedef {Object} TelemetryEvent
- * @property {string} type - Event type (e.g. 'retry', 'circuit.open')
+ * @property {string} type - Event type (e.g. 'retry.failure', 'circuit.open')
  * @property {number} timestamp - Event timestamp
+ * @property {Record<string, number>} [metrics] - Metric increments (counters)
  * @property {Object} [metadata] - Additional event data
  */
 
@@ -73,3 +74,85 @@ export class MultiSink {
     }
   }
 }
+
+/**
+ * Sink that aggregates metrics in memory based on the `metrics` field in events.
+ * @implements {TelemetrySink}
+ */
+export class MetricsSink {
+  constructor() {
+    this.clear();
+  }
+
+  /**
+   * Processes a telemetry event and updates internal counters.
+   * @param {TelemetryEvent} event
+   */
+  emit(event) {
+    const { duration, metrics } = event;
+
+    if (metrics && typeof metrics === 'object') {
+      this._updateMetrics(metrics);
+    }
+
+    if (typeof duration === 'number' && Number.isFinite(duration) && duration >= 0) {
+      this._updateLatency(duration);
+    }
+  }
+
+  _updateMetrics(metrics) {
+    for (const [key, value] of Object.entries(metrics)) {
+      if (typeof value !== 'number') {
+        continue;
+      }
+
+      const current = this.metrics[key];
+      if (current === undefined || typeof current === 'number') {
+        this.metrics[key] = (current || 0) + value;
+      }
+    }
+  }
+
+  _updateLatency(ms) {
+    const { latency } = this.metrics;
+    latency.count++;
+    latency.sum += ms;
+    latency.min = Math.min(latency.min, ms);
+    latency.max = Math.max(latency.max, ms);
+  }
+
+  /**
+   * Returns a snapshot of the current metrics.
+   */
+  get stats() {
+    const { latency, ...rest } = this.metrics;
+    const hasData = latency.count > 0;
+
+    return {
+      ...rest,
+      latency: {
+        ...latency,
+        min: hasData ? latency.min : 0,
+        max: hasData ? latency.max : 0,
+        avg: hasData ? latency.sum / latency.count : 0,
+      },
+    };
+  }
+
+  /**
+   * Resets all metrics to zero.
+   */
+  clear() {
+    this.metrics = {
+      retries: 0,
+      failures: 0,
+      successes: 0,
+      circuitBreaks: 0,
+      circuitRejections: 0,
+      bulkheadRejections: 0,
+      timeouts: 0,
+      hedges: 0,
+      latency: { count: 0, sum: 0, min: Infinity, max: 0 },
+    };
+  }
+}

package/src/testing.d.ts

@@ -37,6 +37,7 @@ export interface BulkheadOptions {
 export interface TelemetryEvent {
   type: string;
   timestamp: number;
+  metrics?: Record<string, number>;
   [key: string]: any;
 }
 
@@ -96,7 +97,11 @@ export interface CircuitBreaker {
 
 export function circuitBreaker(options: CircuitBreakerOptions): CircuitBreaker;
 
-export function timeout<T>(ms: number, fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>), options?: TimeoutOptions): Promise<T>;
+export function timeout<T>(
+  ms: number,
+  fn: ((signal: AbortSignal) => Promise<T>) | (() => Promise<T>),
+  options?: TimeoutOptions
+): Promise<T>;
 
 export interface Bulkhead {
   execute<T>(fn: () => Promise<T>): Promise<T>;
@@ -106,8 +111,14 @@ export interface Bulkhead {
 export function bulkhead(options: BulkheadOptions): Bulkhead;
 
 export function compose(...policies: any[]): { execute<T>(fn: () => Promise<T>): Promise<T> };
-export function fallback(primary: any, secondary: any): { execute<T>(fn: () => Promise<T>): Promise<T> };
-export function race(primary: any, secondary: any): { execute<T>(fn: () => Promise<T>): Promise<T> };
+export function fallback(
+  primary: any,
+  secondary: any
+): { execute<T>(fn: () => Promise<T>): Promise<T> };
+export function race(
+  primary: any,
+  secondary: any
+): { execute<T>(fn: () => Promise<T>): Promise<T> };
 
 export class Policy {
   constructor(executor: (fn: () => Promise<any>) => Promise<any>);

package/src/utils/clock.js

@@ -7,7 +7,7 @@ export class SystemClock {
   }
 
   async sleep(ms) {
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
       const timer = setTimeout(resolve, ms);
       if (typeof timer === 'object' && typeof timer.unref === 'function') {
         timer.unref();
@@ -39,10 +39,10 @@ export class TestClock {
    * @returns {Promise<void>}
    */
   sleep(ms) {
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
       this._pendingTimers.push({
         triggerAt: this._time + ms,
-        resolve
+        resolve,
       });
       // Sort by trigger time
       this._pendingTimers.sort((a, b) => a.triggerAt - b.triggerAt);

package/src/utils/resolvable.js

@@ -0,0 +1,10 @@
+/**
+ * Resolves a value that might be dynamic.
+ *
+ * @template T
+ * @param {T | (() => T)} value - The value or a function returning the value.
+ * @returns {T} The resolved value.
+ */
+export function resolve(value) {
+  return typeof value === 'function' ? value() : value;
+}