@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/plans/21.research.batch.concurrency.md

@@ -1,1888 +0,0 @@
-# Pesquisa: Batch Scraping e Concorrência (2026)
-
-## Sumário
-
-1. [Concurrent URL Scraping](#1-concurrent-url-scraping)
-2. [Progress Tracking](#2-progress-tracking)
-3. [Browser Pooling](#3-browser-pooling)
-4. [Crawlee AutoscaledPool](#4-crawlee-autoscaledpool)
-5. [Work Stealing/Distribution Patterns](#5-work-stealingdistribution-patterns)
-6. [Graceful Degradation](#6-graceful-degradation)
-7. [Layered Resilience](#7-layered-resilience)
-8. [Adaptive Concurrency](#8-adaptive-concurrency)
-9. [Complete Code Examples](#9-complete-code-examples)
-
----
-
-## 1. Concurrent URL Scraping
-
-### p-limit 7.3.0 (Simplest)
-
-The simplest way to limit concurrency. Returns a wrapper function that limits how many promises run simultaneously.
-
-```typescript
-import pLimit from 'p-limit';
-
-// Create a limiter with max 5 concurrent operations
-const limit = pLimit(5);
-
-async function scrapeUrl(url: string): Promise<ScrapedItem> {
-  const html = await fetch(url).then(r => r.text());
-  return parseHtml(html);
-}
-
-// Usage
-const urls = [
-  'https://example.com/1',
-  'https://example.com/2',
-  'https://example.com/3',
-  'https://example.com/4',
-  'https://example.com/5',
-  'https://example.com/6',
-  'https://example.com/7',
-  'https://example.com/8',
-  'https://example.com/9',
-  'https://example.com/10',
-];
-
-// limit() wraps each call — only 5 run at a time
-const results = await Promise.all(
-  urls.map(url => limit(() => scrapeUrl(url)))
-);
-
-// You can also use limit.activeCount and limit.pendingCount
-console.log(`Active: ${limit.activeCount}, Pending: ${limit.pendingCount}`);
-```
-
-### p-map 7.0.4 (Best for Mapping)
-
-Like `Array.map()` but with concurrency control. Great for one-shot batch processing.
-
-```typescript
-import pMap from 'p-map';
-
-const urls = [
-  'https://example.com/1',
-  'https://example.com/2',
-  'https://example.com/3',
-];
-
-// Map with concurrency of 3
-const results = await pMap(
-  urls,
-  async (url) => {
-    const html = await fetch(url).then(r => r.text());
-    return parseHtml(html);
-  },
-  { concurrency: 3 }
-);
-
-// With signal (abort support)
-const controller = new AbortController();
-
-const results = await pMap(
-  urls,
-  async (url) => {
-    const html = await fetch(url, { signal: controller.signal }).then(r => r.text());
-    return parseHtml(html);
-  },
-  {
-    concurrency: 5,
-    signal: controller.signal,
-    // Stop on first error (optional)
-    stopOnError: true,
-  }
-);
-
-// With individual error handling
-const results = await pMap(
-  urls,
-  async (url) => {
-    try {
-      return await scrapeUrl(url);
-    } catch (error) {
-      console.error(`Failed: ${url}`, error);
-      return null; // Skip failed URLs
-    }
-  },
-  { concurrency: 5 }
-);
-
-const successful = results.filter((r): r is ScrapedItem => r !== null);
-```
-
-### p-queue 9.1.2 (Best for Dynamic/Streaming)
-
-A priority queue with concurrency control. Best when URLs arrive dynamically or you need priorities.
-
-```typescript
-import PQueue from 'p-queue';
-
-// Create queue with concurrency of 5
-const queue = new PQueue({
-  concurrency: 5,
-  intervalCap: 10,       // Max operations per interval
-  interval: 1000,         // Interval in ms (rate limiting)
-  timeout: 30_000,        // Timeout for each item
-});
-
-// Add tasks with priority (lower = higher priority)
-queue.add(
-  () => scrapeUrl('https://example.com/critical'),
-  { priority: 1 } // High priority
-);
-
-queue.add(
-  () => scrapeUrl('https://example.com/normal'),
-  { priority: 5 } // Normal priority
-);
-
-queue.add(
-  () => scrapeUrl('https://example.com/low'),
-  { priority: 10 } // Low priority
-);
-
-// Dynamic URL submission
-async function processUrlStream(urlStream: AsyncIterable<string>) {
-  for await (const url of urlStream) {
-    queue.add(() => scrapeUrl(url));
-  }
-}
-
-// Wait for completion
-await queue.onIdle();
-console.log(`Processed ${queue.size} items`);
-
-// Event listeners
-queue.on('active', () => {
-  console.log(`Active: ${queue.active}, Pending: ${queue.pending}`);
-});
-
-queue.on('completed', (result) => {
-  console.log('Task completed');
-});
-
-queue.on('error', (error) => {
-  console.error('Task failed:', error);
-});
-
-queue.on('idle', () => {
-  console.log('All tasks completed');
-});
-
-// Pause/resume
-queue.pause();
-// ... later
-queue.resume();
-
-// Clear pending tasks
-queue.clear();
-```
-
-### Comparison
-
-| Feature | p-limit | p-map | p-queue |
-|---------|---------|-------|---------|
-| Use case | Wrap individual calls | Map array with concurrency | Dynamic task queue |
-| Priority | ❌ | ❌ | ✅ |
-| Rate limiting | ❌ | ❌ | ✅ |
-| Abort signal | ❌ | ✅ | ✅ |
-| Events | ❌ | ❌ | ✅ |
-| Pause/resume | ❌ | ❌ | ✅ |
-| Size | ~1KB | ~2KB | ~4KB |
-| Complexity | Simple | Simple | Moderate |
-
-**Recommendation**: Use `p-map` for batch scraping (simplest), `p-queue` for complex workflows, `p-limit` when you need to wrap existing code.
-
----
-
-## 2. Progress Tracking
-
-### cli-progress 3.12.0 (Terminal Progress Bars)
-
-```typescript
-import cliProgress from 'cli-progress';
-
-// Create progress bar
-const progressBar = new cliProgress.SingleBar(
-  {
-    format: 'Scraping |{bar}| {percentage}% | {value}/{total} | {url} | Speed: {speed} url/s | ETA: {eta_formatted}',
-    barCompleteChar: '\u2588',
-    barIncompleteChar: '\u2591',
-    hideCursor: true,
-    clearOnComplete: false,
-    stopOnComplete: true,
-    etaBuffer: 10, // Calculate ETA from last 10 updates
-  },
-  cliProgress.Presets.shades_classic
-);
-
-// Start with total
-progressBar.start(totalUrls, 0, { url: '', speed: 0 });
-
-// Update for each completed URL
-for (const url of urls) {
-  try {
-    const result = await scrapeUrl(url);
-    progressBar.increment(1, {
-      url: truncateUrl(url, 40),
-      speed: (progressBar.getCurrent() / ((Date.now() - startTime) / 1000)).toFixed(1),
-    });
-  } catch (error) {
-    progressBar.increment(1, { url: `FAILED: ${truncateUrl(url, 30)}` });
-  }
-}
-
-progressBar.stop();
-
-function truncateUrl(url: string, maxLen: number): string {
-  try {
-    const parsed = new URL(url);
-    const path = parsed.pathname + parsed.search;
-    if (path.length > maxLen) return path.slice(0, maxLen - 3) + '...';
-    return path;
-  } catch {
-    return url.slice(0, maxLen);
-  }
-}
-```
-
-### Multi-Progress Bars
-
-```typescript
-import MultiProgress from 'multi-progress';
-import cliProgress from 'cli-progress';
-
-const multi = new MultiProgress(process.stderr);
-
-// Multiple concurrent progress bars
-const bars = new Map<string, cliProgress.SingleBar>();
-
-function createBar(name: string, total: number): cliProgress.SingleBar {
-  const bar = multi.newBar(
-    `${name} |{bar}| {percentage}% | {value}/{total}`,
-    {
-      complete: '\u2588',
-      incomplete: '\u2591',
-      width: 30,
-    }
-  );
-  bar.start(total, 0);
-  bars.set(name, bar);
-  return bar;
-}
-
-// Usage
-const mainBar = createBar('Total   ', urls.length);
-const successBar = createBar('Success ', 0);
-const errorBar = createBar('Errors  ', 0);
-
-// Process with p-limit
-const limit = pLimit(5);
-
-await Promise.all(
-  urls.map(url =>
-    limit(async () => {
-      try {
-        await scrapeUrl(url);
-        mainBar.increment(1);
-        successBar.increment(1);
-      } catch {
-        mainBar.increment(1);
-        errorBar.increment(1);
-      }
-    })
-  )
-);
-
-// Stop all bars
-bars.forEach(bar => bar.stop());
-```
-
-### ora (Spinner for Single Operations)
-
-```typescript
-import ora from 'ora';
-
-const spinner = ora('Starting scraper...').start();
-
-try {
-  // Phase 1
-  spinner.text = 'Launching browser...';
-  const browser = await launchBrowser();
-  spinner.succeed('Browser launched');
-
-  // Phase 2
-  spinner.start('Scraping URLs...');
-  let completed = 0;
-  for (const url of urls) {
-    await scrapeUrl(url);
-    completed++;
-    spinner.text = `Scraping... (${completed}/${urls.length})`;
-  }
-  spinner.succeed(`Scraped ${urls.length} URLs`);
-
-} catch (error) {
-  spinner.fail(`Failed: ${error.message}`);
-}
-```
-
-### Combined Progress Pattern
-
-```typescript
-import cliProgress from 'cli-progress';
-import ora from 'ora';
-import PQueue from 'p-queue';
-
-interface ProgressState {
-  total: number;
-  completed: number;
-  succeeded: number;
-  failed: number;
-  activeRequests: number;
-  startTime: number;
-}
-
-class ProgressTracker {
-  private bar: cliProgress.SingleBar;
-  private spinner: ora.Ora;
-  private state: ProgressState;
-
-  constructor(total: number) {
-    this.state = {
-      total,
-      completed: 0,
-      succeeded: 0,
-      failed: 0,
-      activeRequests: 0,
-      startTime: Date.now(),
-    };
-
-    this.bar = new cliProgress.SingleBar({
-      format: 'Progress |{bar}| {percentage}% | {value}/{total} | ✓ {succeeded} ✗ {failed} | {speed} url/s',
-      barCompleteChar: '\u2588',
-      barIncompleteChar: '\u2591',
-      hideCursor: true,
-    });
-
-    this.spinner = ora({ spinner: 'dots' });
-  }
-
-  start(): void {
-    this.bar.start(this.state.total, 0);
-  }
-
-  update(type: 'success' | 'error'): void {
-    this.state.completed++;
-    if (type === 'success') this.state.succeeded++;
-    else this.state.failed++;
-
-    const elapsed = (Date.now() - this.state.startTime) / 1000;
-    const speed = (this.state.completed / elapsed).toFixed(1);
-
-    this.bar.update(this.state.completed, {
-      succeeded: this.state.succeeded,
-      failed: this.state.failed,
-      speed,
-    });
-  }
-
-  setActiveRequests(count: number): void {
-    this.state.activeRequests = count;
-    this.spinner.text = `Active requests: ${count}`;
-  }
-
-  stop(): void {
-    this.bar.stop();
-    const elapsed = ((Date.now() - this.state.startTime) / 1000).toFixed(1);
-    console.log(`\nCompleted in ${elapsed}s`);
-    console.log(`  Total: ${this.state.total}`);
-    console.log(`  Succeeded: ${this.state.succeeded}`);
-    console.log(`  Failed: ${this.state.failed}`);
-  }
-}
-
-// Usage
-const progress = new ProgressTracker(urls.length);
-progress.start();
-
-const queue = new PQueue({ concurrency: 5 });
-
-for (const url of urls) {
-  queue.add(async () => {
-    try {
-      await scrapeUrl(url);
-      progress.update('success');
-    } catch {
-      progress.update('error');
-    }
-  });
-}
-
-await queue.onIdle();
-progress.stop();
-```
-
----
-
-## 3. Browser Pooling
-
-### Core Pattern: Acquire/Release
-
-```typescript
-import { chromium, type Browser, type BrowserContext } from 'playwright';
-
-interface BrowserPoolOptions {
-  minBrowsers: number;
-  maxBrowsers: number;
-  maxPagesPerBrowser: number;
-  idleTimeout: number;
-  launchTimeout: number;
-}
-
-interface PooledBrowser {
-  browser: Browser;
-  contexts: BrowserContext[];
-  lastUsed: number;
-  busy: boolean;
-}
-
-class BrowserPool {
-  private browsers: PooledBrowser[] = [];
-  private waitQueue: Array<{
-    resolve: (context: BrowserContext) => void;
-    reject: (error: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-  }> = [];
-  private options: BrowserPoolOptions;
-  private cleanupInterval: ReturnType<typeof setInterval>;
-
-  constructor(options: Partial<BrowserPoolOptions> = {}) {
-    this.options = {
-      minBrowsers: 1,
-      maxBrowsers: 5,
-      maxPagesPerBrowser: 10,
-      idleTimeout: 60_000,
-      launchTimeout: 30_000,
-      ...options,
-    };
-
-    // Pre-launch minimum browsers
-    this.initialize();
-
-    // Cleanup idle browsers periodically
-    this.cleanupInterval = setInterval(
-      () => this.cleanupIdleBrowsers(),
-      this.options.idleTimeout / 2
-    );
-  }
-
-  private async initialize(): Promise<void> {
-    for (let i = 0; i < this.options.minBrowsers; i++) {
-      await this.launchBrowser();
-    }
-  }
-
-  private async launchBrowser(): Promise<PooledBrowser> {
-    const browser = await chromium.launch({
-      headless: true,
-      args: ['--no-sandbox', '--disable-setuid-sandbox'],
-    });
-
-    const pooled: PooledBrowser = {
-      browser,
-      contexts: [],
-      lastUsed: Date.now(),
-      busy: false,
-    };
-
-    this.browsers.push(pooled);
-    return pooled;
-  }
-
-  private findAvailableBrowser(): PooledBrowser | null {
-    // Find a browser with available pages
-    for (const pooled of this.browsers) {
-      if (!pooled.busy && pooled.contexts.length < this.options.maxPagesPerBrowser) {
-        return pooled;
-      }
-    }
-    return null;
-  }
-
-  private async waitForBrowser(): Promise<PooledBrowser> {
-    return new Promise(async (resolve, reject) => {
-      const timeout = setTimeout(() => {
-        const idx = this.waitQueue.findIndex(w => w.resolve === resolve);
-        if (idx !== -1) this.waitQueue.splice(idx, 1);
-        reject(new Error('Timeout waiting for available browser'));
-      }, this.options.launchTimeout);
-
-      this.waitQueue.push({ resolve, reject, timeout });
-
-      // Try to launch a new browser if under limit
-      if (this.browsers.length < this.options.maxBrowsers) {
-        try {
-          const pooled = await this.launchBrowser();
-          // Resolve one waiter with this new browser
-          const waiter = this.waitQueue.shift();
-          if (waiter) {
-            clearTimeout(waiter.timeout);
-            waiter.resolve(pooled);
-          }
-        } catch (error) {
-          console.error('Failed to launch browser:', error);
-        }
-      }
-    });
-  }
-
-  /**
-   * Acquire a browser context for scraping.
-   * Returns a context that must be released when done.
-   */
-  async acquire(): Promise<{ context: BrowserContext; release: () => Promise<void> }> {
-    let pooled = this.findAvailableBrowser();
-
-    if (!pooled) {
-      pooled = await this.waitForBrowser();
-    }
-
-    const context = await pooled.browser.newContext({
-      userAgent: this.getRandomUserAgent(),
-      viewport: {
-        width: 1920 + Math.floor(Math.random() * 100),
-        height: 1080 + Math.floor(Math.random() * 100),
-      },
-    });
-
-    pooled.contexts.push(context);
-    pooled.lastUsed = Date.now();
-
-    let released = false;
-    const release = async (): Promise<void> => {
-      if (released) return;
-      released = true;
-
-      try {
-        await context.close();
-      } catch {
-        // Context may already be closed
-      }
-
-      pooled.contexts = pooled.contexts.filter(c => c !== context);
-      pooled.lastUsed = Date.now();
-
-      // Check if any waiters need this browser
-      if (this.waitQueue.length > 0 && pooled.contexts.length < this.options.maxPagesPerBrowser) {
-        const waiter = this.waitQueue.shift();
-        if (waiter) {
-          clearTimeout(waiter.timeout);
-          waiter.resolve(pooled);
-        }
-      }
-    };
-
-    return { context, release };
-  }
-
-  private async cleanupIdleBrowsers(): Promise<void> {
-    const now = Date.now();
-    const toRemove: PooledBrowser[] = [];
-
-    for (const pooled of this.browsers) {
-      if (
-        pooled.contexts.length === 0 &&
-        now - pooled.lastUsed > this.options.idleTimeout &&
-        this.browsers.length - toRemove.length > this.options.minBrowsers
-      ) {
-        toRemove.push(pooled);
-      }
-    }
-
-    for (const pooled of toRemove) {
-      try {
-        await pooled.browser.close();
-      } catch {
-        // Ignore close errors
-      }
-      this.browsers = this.browsers.filter(b => b !== pooled);
-    }
-  }
-
-  /**
-   * Graceful cleanup — close all browsers and reject pending waiters.
-   */
-  async destroy(): Promise<void> {
-    clearInterval(this.cleanupInterval);
-
-    // Reject all pending waiters
-    for (const waiter of this.waitQueue) {
-      clearTimeout(waiter.timeout);
-      waiter.reject(new Error('Browser pool is shutting down'));
-    }
-    this.waitQueue = [];
-
-    // Close all browsers
-    for (const pooled of this.browsers) {
-      for (const ctx of pooled.contexts) {
-        try {
-          await ctx.close();
-        } catch { /* ignore */ }
-      }
-      try {
-        await pooled.browser.close();
-      } catch { /* ignore */ }
-    }
-    this.browsers = [];
-  }
-
-  private getRandomUserAgent(): string {
-    const agents = [
-      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0.0.0',
-      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120.0.0.0',
-      'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/120.0.0.0',
-    ];
-    return agents[Math.floor(Math.random() * agents.length)];
-  }
-
-  get stats() {
-    return {
-      totalBrowsers: this.browsers.length,
-      activeBrowsers: this.browsers.filter(b => b.contexts.length > 0).length,
-      totalContexts: this.browsers.reduce((sum, b) => sum + b.contexts.length, 0),
-      pendingRequests: this.waitQueue.length,
-    };
-  }
-}
-
-// Usage
-const pool = new BrowserPool({ maxBrowsers: 3, maxPagesPerBrowser: 5 });
-
-async function scrapeWithBrowser(url: string): Promise<string> {
-  const { context, release } = await pool.acquire();
-
-  try {
-    const page = await context.newPage();
-    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
-    const content = await page.content();
-    return content;
-  } finally {
-    await release();
-  }
-}
-
-// Process URLs with browser pool
-const limit = pLimit(5);
-
-await Promise.all(
-  urls.map(url =>
-    limit(async () => {
-      const html = await scrapeWithBrowser(url);
-      return parseHtml(html);
-    })
-  )
-);
-
-// Graceful shutdown
-await pool.destroy();
-```
-
----
-
-## 4. Crawlee AutoscaledPool
-
-Crawlee's `AutoscaledPool` dynamically adjusts concurrency based on system load and success rate. It's the gold standard for adaptive scraping.
-
-### Core Concepts
-
-```typescript
-import { AutoscaledPool } from 'crawlee';
-
-const pool = new AutoscaledPool({
-  // Min/max concurrency bounds
-  minConcurrency: 1,
-  maxConcurrency: 20,
-
-  // System metrics
-  snapshotterOptions: {
-    // CPU/memory thresholds
-    cpuSnapshotInterval: 1000,
-    memSnapshotInterval: 2000,
-  },
-
-  // Scaling behavior
-  scaleUpInterval: 1000,         // Check every 1s
-  scaleDownInterval: 5000,       // Check every 5s
-  maxScaledUpRate: 2,            // Max 2x scale-up per interval
-  maxScaledDownRate: 0.5,        // Max 0.5x scale-down per interval
-
-  // Task function
-  taskFunction: async () => {
-    const url = getNextUrl();
-    if (!url) return false; // No more tasks
-
-    try {
-      await scrapeUrl(url);
-      return true; // Task completed
-    } catch (error) {
-      if (isRetryable(error)) {
-        // Return the URL to the queue
-        addUrlBack(url);
-        return true; // Task "completed" (will be retried)
-      }
-      throw error; // Non-retryable error
-    }
-  },
-});
-
-// Start the pool
-await pool.run();
-```
-
-### How AutoscaledPool Works
-
-1. **Snapshotter**: Continuously monitors CPU and memory usage
-2. **Scaler**: Adjusts concurrency based on metrics:
-   - If CPU < 50% and memory < 70% → scale up
-   - If CPU > 80% or memory > 85% → scale down
-3. **Task runner**: Runs tasks at current concurrency level
-4. **Idle detection**: Stops when no more tasks are available
-
-### Custom Scaling Logic
-
-```typescript
-import { AutoscaledPool, AutoscaledPoolOptions } from 'crawlee';
-
-class SmartAutoscaledPool extends AutoscaledPool {
-  private errorRate = 0;
-  private recentErrors = 0;
-  private recentSuccesses = 0;
-
-  constructor(options: AutoscaledPoolOptions) {
-    super({
-      ...options,
-      // Custom scaling logic
-      desiredConcurrencyCallback: () => {
-        // If error rate is high, reduce concurrency
-        if (this.errorRate > 0.3) {
-          return Math.max(1, this.desiredConcurrency - 2);
-        }
-        // If error rate is low and system is healthy, increase
-        if (this.errorRate < 0.1 && this.isSystemHealthy()) {
-          return Math.min(
-            this.maxConcurrency,
-            this.desiredConcurrency + 1
-          );
-        }
-        return this.desiredConcurrency;
-      },
-    });
-  }
-
-  trackSuccess(): void {
-    this.recentSuccesses++;
-    this.updateErrorRate();
-  }
-
-  trackError(): void {
-    this.recentErrors++;
-    this.updateErrorRate();
-  }
-
-  private updateErrorRate(): void {
-    const total = this.recentErrors + this.recentSuccesses;
-    if (total >= 100) {
-      this.errorRate = this.recentErrors / total;
-      this.recentErrors = 0;
-      this.recentSuccesses = 0;
-    }
-  }
-
-  private isSystemHealthy(): boolean {
-    // Check CPU and memory
-    const memUsage = process.memoryUsage();
-    const memPercent = memUsage.heapUsed / memUsage.heapTotal;
-    return memPercent < 0.7;
-  }
-}
-```
-
----
-
-## 5. Work Stealing/Distribution Patterns
-
-### Producer-Consumer Pattern
-
-```typescript
-import PQueue from 'p-queue';
-import { EventEmitter } from 'events';
-
-interface ScrapingTask {
-  id: string;
-  url: string;
-  priority: number;
-  retries: number;
-  maxRetries: number;
-}
-
-class WorkDistributor extends EventEmitter {
-  private queue: PQueue;
-  private workers: Map<string, Worker> = new Map();
-  private tasks: Map<string, ScrapingTask> = new Map();
-
-  constructor(concurrency: number = 10) {
-    super();
-    this.queue = new PQueue({ concurrency });
-  }
-
-  addTask(task: ScrapingTask): void {
-    this.tasks.set(task.id, task);
-    this.queue.add(() => this.executeTask(task));
-  }
-
-  addTasks(tasks: ScrapingTask[]): void {
-    tasks.forEach(t => this.addTask(t));
-  }
-
-  private async executeTask(task: ScrapingTask): Promise<void> {
-    this.emit('task:start', task);
-
-    try {
-      const result = await scrapeUrl(task.url);
-      this.tasks.delete(task.id);
-      this.emit('task:complete', { task, result });
-    } catch (error) {
-      if (task.retries < task.maxRetries) {
-        // Re-queue with incremented retry count
-        task.retries++;
-        this.emit('task:retry', { task, attempt: task.retries, error });
-        this.queue.add(() => this.executeTask(task));
-      } else {
-        this.tasks.delete(task.id);
-        this.emit('task:failed', { task, error });
-      }
-    }
-  }
-
-  get stats() {
-    return {
-      pending: this.queue.pending,
-      active: this.queue.active,
-      totalTasks: this.tasks.size,
-      isIdle: this.queue.idle,
-    };
-  }
-
-  async drain(): Promise<void> {
-    await this.queue.onIdle();
-  }
-}
-
-// Usage
-const distributor = new WorkDistributor(10);
-
-distributor.on('task:complete', ({ task, result }) => {
-  console.log(`✓ ${task.url}`);
-});
-
-distributor.on('task:failed', ({ task, error }) => {
-  console.error(`✗ ${task.url}: ${error.message}`);
-});
-
-distributor.addTasks(
-  urls.map((url, i) => ({
-    id: `task-${i}`,
-    url,
-    priority: 5,
-    retries: 0,
-    maxRetries: 3,
-  }))
-);
-
-await distributor.drain();
-```
-
-### Domain-Based Distribution
-
-Distribute work by domain to respect per-domain rate limits.
-
-```typescript
-import PQueue from 'p-queue';
-
-class DomainDistributor {
-  private domainQueues = new Map<string, PQueue>();
-  private globalQueue: PQueue;
-
-  constructor(
-    private globalConcurrency: number = 50,
-    private perDomainConcurrency: number = 3
-  ) {
-    this.globalQueue = new PQueue({ concurrency: globalConcurrency });
-  }
-
-  private getDomainQueue(domain: string): PQueue {
-    if (!this.domainQueues.has(domain)) {
-      const queue = new PQueue({
-        concurrency: this.perDomainConcurrency,
-        interval: 1000, // Rate limit: 1 request per second
-        intervalCap: 5,  // Max 5 requests per interval
-      });
-      this.domainQueues.set(domain, queue);
-    }
-    return this.domainQueues.get(domain)!;
-  }
-
-  async add(url: string, task: () => Promise<unknown>): Promise<void> {
-    const domain = new URL(url).hostname;
-    const domainQueue = this.getDomainQueue(domain);
-
-    // Wrap domain-specific task in global queue
-    this.globalQueue.add(() => domainQueue.add(task));
-  }
-
-  async drain(): Promise<void> {
-    await this.globalQueue.onIdle();
-    // Wait for all domain queues too
-    for (const queue of this.domainQueues.values()) {
-      await queue.onIdle();
-    }
-  }
-
-  getStats() {
-    const domainStats: Record<string, { pending: number; active: number }> = {};
-    for (const [domain, queue] of this.domainQueues) {
-      domainStats[domain] = {
-        pending: queue.pending,
-        active: queue.active,
-      };
-    }
-    return {
-      global: {
-        pending: this.globalQueue.pending,
-        active: this.globalQueue.active,
-      },
-      domains: domainStats,
-    };
-  }
-}
-
-// Usage
-const distributor = new DomainDistributor(50, 3);
-
-await Promise.all(
-  urls.map(url =>
-    distributor.add(url, async () => {
-      const html = await fetch(url).then(r => r.text());
-      return parseHtml(html);
-    })
-  )
-);
-```
-
----
-
-## 6. Graceful Degradation
-
-### Circuit Breaker (cockatiel 4.0.0)
-
-The circuit breaker pattern prevents cascading failures by stopping requests to a failing service.
-
-```typescript
-import { CircuitBreaker, handle } from 'cockatiel';
-
-// Create a circuit breaker
-const breaker = CircuitBreaker.byPercentage({
-  threshold: 50,           // Open circuit when 50% of requests fail
-  duration: 30_000,        // Stay open for 30 seconds
-  halfOpenAfter: 10_000,   // Try again after 10 seconds
-});
-
-// Wrap fetch calls with the circuit breaker
-async function resilientFetch(url: string): Promise<Response> {
-  return handle(
-    breaker,
-    () => fetch(url),
-    (error) => {
-      // Fallback when circuit is open
-      console.warn(`Circuit open for ${new URL(url).hostname}, using fallback`);
-      return new Response(JSON.stringify({ error: 'Service unavailable' }), {
-        status: 503,
-        headers: { 'Content-Type': 'application/json' },
-      });
-    }
-  ).promise();
-}
-
-// Or with more control
-const circuit = CircuitBreaker.byPercentage({
-  threshold: 50,
-  duration: 30_000,
-  halfOpenAfter: 10_000,
-});
-
-// Listen for state changes
-circuit.onBreak(() => console.log('Circuit OPEN — requests blocked'));
-circuit.onReset(() => console.log('Circuit CLOSED — requests allowed'));
-circuit.onHalfOpen(() => console.log('Circuit HALF-OPEN — testing'));
-
-// Manual circuit breaker
-async function fetchWithCircuitBreaker(url: string): Promise<Response> {
-  const result = await handle(
-    circuit,
-    () => fetch(url),
-    () => {
-      // Fallback
-      return new Response('{}', { status: 503 });
-    }
-  ).promise();
-
-  return result;
-}
-```
-
-### Bulkhead Isolation
-
-Bulkhead pattern isolates failures to specific domains or operation types.
-
-```typescript
-import PQueue from 'p-queue';
-
-class BulkheadPool {
-  private bulkheads = new Map<string, PQueue>();
-  private maxPerBulkhead: number;
-  private maxTotal: number;
-  private totalActive = 0;
-
-  constructor(maxPerBulkhead: number = 5, maxTotal: number = 50) {
-    this.maxPerBulkhead = maxPerBulkhead;
-    this.maxTotal = maxTotal;
-  }
-
-  private getBulkhead(name: string): PQueue {
-    if (!this.bulkheads.has(name)) {
-      this.bulkheads.set(name, new PQueue({
-        concurrency: this.maxPerBulkhead,
-      }));
-    }
-    return this.bulkheads.get(name)!;
-  }
-
-  async execute<T>(bulkheadName: string, fn: () => Promise<T>): Promise<T> {
-    if (this.totalActive >= this.maxTotal) {
-      throw new Error('Total concurrency limit reached');
-    }
-
-    const bulkhead = this.getBulkhead(bulkheadName);
-
-    this.totalActive++;
-    try {
-      return await bulkhead.add(fn);
-    } finally {
-      this.totalActive--;
-    }
-  }
-
-  getStats() {
-    const stats: Record<string, { pending: number; active: number }> = {};
-    for (const [name, queue] of this.bulkheads) {
-      stats[name] = {
-        pending: queue.pending,
-        active: queue.active,
-      };
-    }
-    return {
-      totalActive: this.totalActive,
-      bulkheads: stats,
-    };
-  }
-}
-
-// Usage: isolate failures by domain
-const bulkhead = new BulkheadPool(3, 30);
-
-await Promise.all(
-  urls.map(url => {
-    const domain = new URL(url).hostname;
-    return bulkhead.execute(domain, async () => {
-      const html = await fetch(url).then(r => r.text());
-      return parseHtml(html);
-    });
-  })
-);
-```
-
-### Fallback Strategies
-
-```typescript
-interface FallbackStrategy<T> {
-  name: string;
-  execute: () => Promise<T>;
-  condition?: (error: Error) => boolean;
-}
-
-class FallbackChain<T> {
-  private strategies: FallbackStrategy<T>[] = [];
-
-  add(strategy: FallbackStrategy<T>): this {
-    this.strategies.push(strategy);
-    return this;
-  }
-
-  async execute(): Promise<T> {
-    let lastError: Error | undefined;
-
-    for (const strategy of this.strategies) {
-      if (strategy.condition && lastError && !strategy.condition(lastError)) {
-        continue;
-      }
-
-      try {
-        return await strategy.execute();
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-        console.warn(`Fallback "${strategy.name}" failed: ${lastError.message}`);
-      }
-    }
-
-    throw lastError ?? new Error('All fallback strategies failed');
-  }
-}
-
-// Usage
-const fetchWithFallback = new FallbackChain<string>()
-  .add({
-    name: 'primary-fetch',
-    execute: async () => {
-      const res = await fetch(url);
-      return res.text();
-    },
-  })
-  .add({
-    name: 'cache',
-    condition: (err) => err.message.includes('fetch'),
-    execute: async () => {
-      const cached = await cache.get(url);
-      if (!cached) throw new Error('No cache');
-      return cached;
-    },
-  })
-  .add({
-    name: 'archive.org',
-    condition: (err) => err.message.includes('404'),
-    execute: async () => {
-      const res = await fetch(`https://web.archive.org/web/2024/${url}`);
-      return res.text();
-    },
-  })
-  .add({
-    name: 'default',
-    execute: async () => '<html><body>Content unavailable</body></html>',
-  });
-
-const html = await fetchWithFallback.execute();
-```
-
----
-
-## 7. Layered Resilience
-
-### Retry + Circuit Breaker + Timeout Stack
-
-```typescript
-import { CircuitBreaker, handle, retry, timeout } from 'cockatiel';
-
-// Layer 1: Retry with exponential backoff
-const retryPolicy = retry({
-  maxAttempts: 3,
-  backoff: {
-    initialDelay: 1000,
-    maxDelay: 10_000,
-    multiplier: 2,
-    jitter: true,
-  },
-  handle: (error) => {
-    // Only retry specific errors
-    return error instanceof TypeError ||
-           (error instanceof ScraperError && error.retryable);
-  },
-});
-
-// Layer 2: Circuit breaker
-const circuitBreaker = CircuitBreaker.byPercentage({
-  threshold: 50,
-  duration: 30_000,
-  halfOpenAfter: 10_000,
-});
-
-// Layer 3: Timeout
-const timeoutPolicy = timeout(30_000);
-
-// Combine all layers
-async function resilientScrape(url: string): Promise<string> {
-  // Stack: timeout → circuit breaker → retry → fetch
-  const result = await handle(
-    circuitBreaker,
-    () =>
-      retryPolicy.execute(async () => {
-        const response = await timeoutPolicy.execute(async () => {
-          const res = await fetch(url, {
-            signal: AbortSignal.timeout(30_000),
-          });
-          return res;
-        });
-        return response.text();
-      }),
-    (error) => {
-      // Circuit breaker fallback
-      console.warn(`Circuit open, fallback for ${url}`);
-      return getCachedVersion(url) ?? '';
-    }
-  ).promise();
-
-  return result;
-}
-```
-
-### Complete Resilient Scraper
-
-```typescript
-import { CircuitBreaker, handle, retry, timeout, bulkhead } from 'cockatiel';
-import PQueue from 'p-queue';
-
-interface ResilientScraperOptions {
-  maxConcurrency: number;
-  maxRetries: number;
-  timeout: number;
-  circuitBreakerThreshold: number;
-  circuitBreakerResetTimeout: number;
-  perDomainConcurrency: number;
-}
-
-class ResilientScraper {
-  private queue: PQueue;
-  private circuits = new Map<string, CircuitBreaker>();
-  private options: ResilientScraperOptions;
-
-  constructor(options: Partial<ResilientScraperOptions> = {}) {
-    this.options = {
-      maxConcurrency: 10,
-      maxRetries: 3,
-      timeout: 30_000,
-      circuitBreakerThreshold: 50,
-      circuitBreakerResetTimeout: 30_000,
-      perDomainConcurrency: 3,
-      ...options,
-    };
-
-    this.queue = new PQueue({ concurrency: this.options.maxConcurrency });
-  }
-
-  private getCircuit(domain: string): CircuitBreaker {
-    if (!this.circuits.has(domain)) {
-      this.circuits.set(
-        domain,
-        CircuitBreaker.byPercentage({
-          threshold: this.options.circuitBreakerThreshold,
-          duration: this.options.circuitBreakerResetTimeout,
-          halfOpenAfter: this.options.circuitBreakerResetTimeout / 3,
-        })
-      );
-    }
-    return this.circuits.get(domain)!;
-  }
-
-  async scrape(url: string): Promise<ScrapedItem> {
-    const domain = new URL(url).hostname;
-    const circuit = this.getCircuit(domain);
-
-    return this.queue.add(async () => {
-      const result = await handle(
-        circuit,
-        () =>
-          retry({
-            maxAttempts: this.options.maxRetries,
-            backoff: {
-              initialDelay: 1000,
-              maxDelay: 15_000,
-              multiplier: 2,
-              jitter: true,
-            },
-          }).execute(async () => {
-            const response = await timeout(this.options.timeout).execute(async () => {
-              const res = await fetch(url, {
-                signal: AbortSignal.timeout(this.options.timeout),
-              });
-              if (!res.ok) {
-                throw new HttpError(`HTTP ${res.status}`, res.status);
-              }
-              return res;
-            });
-
-            const html = await response.text();
-            return this.parseHtml(html, url);
-          }),
-        (error) => {
-          console.warn(`Circuit open for ${domain}, using cache`);
-          return this.getCachedResult(url);
-        }
-      ).promise();
-
-      // Store in cache
-      this.cacheResult(url, result);
-
-      return result;
-    }) as Promise<ScrapedItem>;
-  }
-
-  async scrapeAll(urls: string[]): Promise<Map<string, ScrapedItem | null>> {
-    const results = new Map<string, ScrapedItem | null>();
-
-    await Promise.all(
-      urls.map(async (url) => {
-        try {
-          const result = await this.scrape(url);
-          results.set(url, result);
-        } catch (error) {
-          console.error(`Failed: ${url}`, error);
-          results.set(url, null);
-        }
-      })
-    );
-
-    return results;
-  }
-
-  private async parseHtml(html: string, url: string): Promise<ScrapedItem> {
-    // ... parsing logic
-    return { url, title: '', content: html };
-  }
-
-  private cacheResult(url: string, result: ScrapedItem): void {
-    // Implement caching
-  }
-
-  private getCachedResult(url: string): ScrapedItem | null {
-    // Return cached result or null
-    return null;
-  }
-}
-```
-
----
-
-## 8. Adaptive Concurrency
-
-### Dynamic Concurrency Based on Error Rate
-
-```typescript
-class AdaptiveConcurrency {
-  private currentConcurrency: number;
-  private minConcurrency: number;
-  private maxConcurrency: number;
-  private errorWindow: Array<{ timestamp: number; success: boolean }> = [];
-  private windowSize: number = 100;
-  private targetErrorRate: number = 0.1; // 10% target error rate
-  private adjustmentInterval: ReturnType<typeof setInterval>;
-
-  constructor(options: {
-    initialConcurrency?: number;
-    minConcurrency?: number;
-    maxConcurrency?: number;
-    targetErrorRate?: number;
-    adjustmentInterval?: number;
-  } = {}) {
-    this.currentConcurrency = options.initialConcurrency ?? 5;
-    this.minConcurrency = options.minConcurrency ?? 1;
-    this.maxConcurrency = options.maxConcurrency ?? 50;
-    this.targetErrorRate = options.targetErrorRate ?? 0.1;
-
-    this.adjustmentInterval = setInterval(
-      () => this.adjustConcurrency(),
-      options.adjustmentInterval ?? 10_000
-    );
-  }
-
-  track(success: boolean): void {
-    this.errorWindow.push({
-      timestamp: Date.now(),
-      success,
-    });
-
-    // Keep only recent results
-    if (this.errorWindow.length > this.windowSize) {
-      this.errorWindow.shift();
-    }
-  }
-
-  private adjustConcurrency(): void {
-    if (this.errorWindow.length < 10) return; // Not enough data
-
-    const errorRate = this.getErrorRate();
-
-    if (errorRate > this.targetErrorRate * 1.5) {
-      // Too many errors — reduce concurrency
-      const reduction = Math.max(1, Math.floor(this.currentConcurrency * 0.3));
-      this.currentConcurrency = Math.max(
-        this.minConcurrency,
-        this.currentConcurrency - reduction
-      );
-      console.log(`↓ Concurrency: ${this.currentConcurrency} (error rate: ${(errorRate * 100).toFixed(1)}%)`);
-    } else if (errorRate < this.targetErrorRate * 0.5) {
-      // Low errors — increase concurrency
-      const increase = Math.max(1, Math.floor(this.currentConcurrency * 0.2));
-      this.currentConcurrency = Math.min(
-        this.maxConcurrency,
-        this.currentConcurrency + increase
-      );
-      console.log(`↑ Concurrency: ${this.currentConcurrency} (error rate: ${(errorRate * 100).toFixed(1)}%)`);
-    }
-  }
-
-  private getErrorRate(): number {
-    const errors = this.errorWindow.filter(e => !e.success).length;
-    return errors / this.errorWindow.length;
-  }
-
-  get concurrency(): number {
-    return this.currentConcurrency;
-  }
-
-  get errorRate(): number {
-    return this.getErrorRate();
-  }
-
-  destroy(): void {
-    clearInterval(this.adjustmentInterval);
-  }
-}
-
-// Usage
-const adaptive = new AdaptiveConcurrency({
-  initialConcurrency: 5,
-  minConcurrency: 1,
-  maxConcurrency: 30,
-  targetErrorRate: 0.1,
-});
-
-const limit = pLimit(adaptive.concurrency);
-
-// Dynamic concurrency — re-evaluate periodically
-async function scrapeWithAdaptiveConcurrency(urls: string[]): Promise<void> {
-  const results: Promise<void>[] = [];
-
-  for (const url of urls) {
-    const promise = limit(async () => {
-      try {
-        await scrapeUrl(url);
-        adaptive.track(true);
-      } catch (error) {
-        adaptive.track(false);
-      }
-    });
-
-    results.push(promise);
-
-    // Re-create limiter when concurrency changes
-    if (results.length % 10 === 0) {
-      await Promise.race(results);
-      // Update limiter's concurrency (p-limit doesn't support this,
-      // so you'd need to recreate or use a different approach)
-    }
-  }
-
-  await Promise.all(results);
-}
-```
-
-### Performance-Based Adaptive Concurrency
-
-```typescript
-class PerformanceAdaptiveConcurrency {
-  private latencyWindow: number[] = [];
-  private targetLatency: number;
-  private windowSize: number = 50;
-  private currentConcurrency: number;
-  private minConcurrency: number;
-  private maxConcurrency: number;
-
-  constructor(options: {
-    initialConcurrency?: number;
-    minConcurrency?: number;
-    maxConcurrency?: number;
-    targetLatency?: number; // ms
-  } = {}) {
-    this.currentConcurrency = options.initialConcurrency ?? 5;
-    this.minConcurrency = options.minConcurrency ?? 1;
-    this.maxConcurrency = options.maxConcurrency ?? 50;
-    this.targetLatency = options.targetLatency ?? 2000;
-  }
-
-  trackLatency(latencyMs: number): void {
-    this.latencyWindow.push(latencyMs);
-    if (this.latencyWindow.length > this.windowSize) {
-      this.latencyWindow.shift();
-    }
-  }
-
-  getOptimalConcurrency(): number {
-    if (this.latencyWindow.length < 5) return this.currentConcurrency;
-
-    const avgLatency = this.latencyWindow.reduce((a, b) => a + b, 0)
-      / this.latencyWindow.length;
-
-    const p95Latency = this.getPercentile(95);
-    const p99Latency = this.getPercentile(99);
-
-    // If p99 is 2x target, reduce concurrency
-    if (p99Latency > this.targetLatency * 2) {
-      this.currentConcurrency = Math.max(
-        this.minConcurrency,
-        Math.floor(this.currentConcurrency * 0.7)
-      );
-    }
-    // If avg latency is below target, increase concurrency
-    else if (avgLatency < this.targetLatency * 0.5) {
-      this.currentConcurrency = Math.min(
-        this.maxConcurrency,
-        Math.ceil(this.currentConcurrency * 1.3)
-      );
-    }
-
-    return this.currentConcurrency;
-  }
-
-  private getPercentile(percentile: number): number {
-    const sorted = [...this.latencyWindow].sort((a, b) => a - b);
-    const index = Math.ceil((percentile / 100) * sorted.length) - 1;
-    return sorted[Math.max(0, index)];
-  }
-
-  get stats() {
-    const sorted = [...this.latencyWindow].sort((a, b) => a - b);
-    return {
-      currentConcurrency: this.currentConcurrency,
-      avgLatency: this.latencyWindow.length > 0
-        ? this.latencyWindow.reduce((a, b) => a + b, 0) / this.latencyWindow.length
-        : 0,
-      p50: this.getPercentile(50),
-      p95: this.getPercentile(95),
-      p99: this.getPercentile(99),
-      sampleSize: this.latencyWindow.length,
-    };
-  }
-}
-```
-
----
-
-## 9. Complete Code Examples
-
-### Full Batch Scraper with All Patterns
-
-```typescript
-import PQueue from 'p-queue';
-import { CircuitBreaker, handle, retry, timeout } from 'cockatiel';
-import cliProgress from 'cli-progress';
-import { z } from 'zod';
-
-// ============================================
-// Schema
-// ============================================
-
-const BatchJobSchema = z.object({
-  urls: z.array(z.string().url()).min(1).max(10_000),
-  concurrency: z.number().int().min(1).max(100).default(10),
-  maxRetries: z.number().int().min(0).max(10).default(3),
-  timeout: z.number().int().min(1000).max(300_000).default(30_000),
-  targetErrorRate: z.number().min(0).max(1).default(0.1),
-  outputDir: z.string().default('./output'),
-});
-
-type BatchJob = z.infer<typeof BatchJobSchema>;
-
-// ============================================
-// Progress Tracker
-// ============================================
-
-class ProgressTracker {
-  private bar: cliProgress.SingleBar;
-  private succeeded = 0;
-  private failed = 0;
-  private startTime: number;
-
-  constructor(total: number) {
-    this.startTime = Date.now();
-    this.bar = new cliProgress.SingleBar({
-      format: 'Scraping |{bar}| {percentage}% | {value}/{total} | ✓ {succeeded} ✗ {failed} | {speed} url/s',
-      barCompleteChar: '\u2588',
-      barIncompleteChar: '\u2591',
-      hideCursor: true,
-    });
-    this.bar.start(total, 0);
-  }
-
-  success(): void {
-    this.succeeded++;
-    this.update();
-  }
-
-  error(): void {
-    this.failed++;
-    this.update();
-  }
-
-  private update(): void {
-    const elapsed = (Date.now() - this.startTime) / 1000;
-    const speed = ((this.succeeded + this.failed) / elapsed).toFixed(1);
-    this.bar.update(this.succeeded + this.failed, {
-      succeeded: this.succeeded,
-      failed: this.failed,
-      speed,
-    });
-  }
-
-  stop(): void {
-    this.bar.stop();
-    const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
-    console.log(`\nCompleted in ${elapsed}s`);
-    console.log(`  ✓ Succeeded: ${this.succeeded}`);
-    console.log(`  ✗ Failed: ${this.failed}`);
-  }
-}
-
-// ============================================
-// Adaptive Concurrency Manager
-// ============================================
-
-class AdaptiveConcurrencyManager {
-  private errorWindow: boolean[] = [];
-  private currentConcurrency: number;
-  private minConcurrency: number;
-  private maxConcurrency: number;
-  private targetErrorRate: number;
-
-  constructor(options: {
-    initial: number;
-    min: number;
-    max: number;
-    targetErrorRate: number;
-  }) {
-    this.currentConcurrency = options.initial;
-    this.minConcurrency = options.min;
-    this.maxConcurrency = options.max;
-    this.targetErrorRate = options.targetErrorRate;
-  }
-
-  track(success: boolean): void {
-    this.errorWindow.push(success);
-    if (this.errorWindow.length > 100) this.errorWindow.shift();
-    this.adjust();
-  }
-
-  private adjust(): void {
-    if (this.errorWindow.length < 20) return;
-
-    const errorRate = 1 - (this.errorWindow.filter(Boolean).length / this.errorWindow.length);
-
-    if (errorRate > this.targetErrorRate * 2) {
-      this.currentConcurrency = Math.max(
-        this.minConcurrency,
-        Math.floor(this.currentConcurrency * 0.6)
-      );
-    } else if (errorRate < this.targetErrorRate * 0.3) {
-      this.currentConcurrency = Math.min(
-        this.maxConcurrency,
-        Math.ceil(this.currentConcurrency * 1.4)
-      );
-    }
-  }
-
-  get concurrency(): number {
-    return this.currentConcurrency;
-  }
-
-  get errorRate(): number {
-    if (this.errorWindow.length === 0) return 0;
-    return 1 - (this.errorWindow.filter(Boolean).length / this.errorWindow.length);
-  }
-}
-
-// ============================================
-// Circuit Breaker per Domain
-// ============================================
-
-class CircuitBreakerPool {
-  private circuits = new Map<string, CircuitBreaker>();
-
-  get(domain: string): CircuitBreaker {
-    if (!this.circuits.has(domain)) {
-      this.circuits.set(
-        domain,
-        CircuitBreaker.byPercentage({
-          threshold: 50,
-          duration: 30_000,
-          halfOpenAfter: 10_000,
-        })
-      );
-    }
-    return this.circuits.get(domain)!;
-  }
-}
-
-// ============================================
-// Main Batch Scraper
-// ============================================
-
-class BatchScraper {
-  private job: BatchJob;
-  private adaptive: AdaptiveConcurrencyManager;
-  private circuits: CircuitBreakerPool;
-  private progress: ProgressTracker;
-  private queue: PQueue;
-  private results: Map<string, { success: boolean; data?: unknown; error?: string }> = new Map();
-
-  constructor(job: BatchJob) {
-    this.job = job;
-    this.adaptive = new AdaptiveConcurrencyManager({
-      initial: job.concurrency,
-      min: 1,
-      max: job.concurrency * 2,
-      targetErrorRate: job.targetErrorRate,
-    });
-    this.circuits = new CircuitBreakerPool();
-    this.progress = new ProgressTracker(job.urls.length);
-    this.queue = new PQueue({ concurrency: job.concurrency });
-  }
-
-  async run(): Promise<Map<string, { success: boolean; data?: unknown; error?: string }>> {
-    console.log(`Starting batch scrape of ${this.job.urls.length} URLs`);
-    console.log(`Initial concurrency: ${this.job.concurrency}`);
-    console.log(`Max retries: ${this.job.maxRetries}`);
-    console.log('');
-
-    for (const url of this.job.urls) {
-      this.queue.add(() => this.scrapeUrl(url));
-    }
-
-    await this.queue.onIdle();
-    this.progress.stop();
-
-    // Print summary
-    const succeeded = [...this.results.values()].filter(r => r.success).length;
-    const failed = [...this.results.values()].filter(r => !r.success).length;
-    console.log(`\nResults: ${succeeded} succeeded, ${failed} failed`);
-    console.log(`Final concurrency: ${this.adaptive.concurrency}`);
-    console.log(`Error rate: ${(this.adaptive.errorRate * 100).toFixed(1)}%`);
-
-    return this.results;
-  }
-
-  private async scrapeUrl(url: string): Promise<void> {
-    const domain = new URL(url).hostname;
-    const circuit = this.circuits.get(domain);
-
-    try {
-      const result = await handle(
-        circuit,
-        () =>
-          retry({
-            maxAttempts: this.job.maxRetries,
-            backoff: {
-              initialDelay: 1000,
-              maxDelay: 15_000,
-              multiplier: 2,
-              jitter: true,
-            },
-          }).execute(async () => {
-            const response = await timeout(this.job.timeout).execute(async () => {
-              const res = await fetch(url, {
-                headers: {
-                  'User-Agent': 'Mozilla/5.0 (compatible; BatchScraper/1.0)',
-                },
-              });
-              if (!res.ok) throw new Error(`HTTP ${res.status}`);
-              return res;
-            });
-
-            const html = await response.text();
-            return this.parseHtml(html, url);
-          }),
-        () => {
-          // Circuit breaker fallback
-          return { cached: true, title: 'Content unavailable (circuit open)' };
-        }
-      ).promise();
-
-      this.results.set(url, { success: true, data: result });
-      this.adaptive.track(true);
-      this.progress.success();
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      this.results.set(url, { success: false, error: errorMsg });
-      this.adaptive.track(false);
-      this.progress.error();
-    }
-  }
-
-  private async parseHtml(html: string, url: string): Promise<unknown> {
-    // Simple extraction
-    const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
-    return {
-      url,
-      title: titleMatch?.[1]?.trim() ?? '',
-      length: html.length,
-      scrapedAt: new Date().toISOString(),
-    };
-  }
-}
-
-// ============================================
-// Usage
-// ============================================
-
-async function main() {
-  const job = BatchJobSchema.parse({
-    urls: [
-      'https://example.com/1',
-      'https://example.com/2',
-      'https://example.com/3',
-      // ... more URLs
-    ],
-    concurrency: 10,
-    maxRetries: 3,
-    timeout: 30_000,
-  });
-
-  const scraper = new BatchScraper(job);
-  const results = await scraper.run();
-
-  // Save results
-  const fs = await import('fs/promises');
-  const outputPath = `${job.outputDir}/results-${Date.now()}.json`;
-  await fs.writeFile(outputPath, JSON.stringify([...results.entries()], null, 2));
-  console.log(`\nResults saved to ${outputPath}`);
-}
-
-main().catch(console.error);
-```
-
----
-
-## Summary: Quick Reference
-
-| Pattern | Package | Use Case |
-|---------|---------|----------|
-| Simple concurrency | p-limit | Wrap existing functions |
-| Map with concurrency | p-map | Batch process arrays |
-| Priority queue | p-queue | Dynamic task submission |
-| Terminal progress | cli-progress | Single progress bar |
-| Spinner | ora | Single operation feedback |
-| Browser pooling | Custom / Crawlee | Playwright/Puppeteer |
-| Autoscaled pool | Crawlee | Dynamic scaling |
-| Circuit breaker | cockatiel | Prevent cascading failures |
-| Retry + backoff | cockatiel | Transient error handling |
-| Timeout | cockatiel / AbortSignal | Prevent hanging |
-| Adaptive concurrency | Custom | Self-tuning systems |
-| Domain distribution | Custom | Per-domain rate limits |
-| Fallback chain | Custom | Graceful degradation |