webspresso 0.0.104 → 0.0.106

package/.agents/ORM.md

@@ -116,11 +116,33 @@ const product = await productRepo.findById(1);
 const activeProducts = await productRepo.find({ active: true });
 const singleProduct = await productRepo.findOne({ slug: 'laptop' });
 
-// 2. Insert, Update, Delete
+// 2. Insert, Update, Delete & Batch Operations
 const newProduct = await productRepo.create({ name: 'Laptop', price: 999, category_id: 1 });
 const updated = await productRepo.update(newProduct.id, { price: 899 });
 await productRepo.delete(newProduct.id); // Soft or hard delete based on model config
 
+// 2.1 Batch Insert (Auto-Chunked with SQL Variable Limit Protection)
+// Automatically chunks rows to stay safely within SQLite/Postgres parameter limits (prevents 'too many SQL variables' error)
+// and executes inside an atomic transaction (all succeed or all rollback).
+const products = await productRepo.createBatch([
+  { name: 'Tablet', price: 499, category_id: 1 },
+  { name: 'Phone', price: 799, category_id: 1 },
+], { chunkSize: 500, transaction: true });
+
+// 2.2 Upsert & Batch Upsert (onConflict Merge)
+// Inserts new records or updates existing records on conflict target (e.g. sku or primaryKey)
+const upserted = await productRepo.upsert(
+  { sku: 'SKU-001', name: 'Keyboard', price: 59 },
+  'sku',
+  ['name', 'price']
+);
+
+const batchUpserted = await productRepo.upsertBatch(
+  catalogItems,
+  'sku',
+  { updateColumns: ['name', 'price', 'updated_at'] }
+);
+
 // 3. Query Builder & Pagination
 const result = await productRepo.query()
   .where('price', '>', 500)
@@ -468,5 +490,137 @@ const user = await UserFactory.create({ db });
 const admins = await UserFactory.count(3).apply('admin').create({ db });
 ```
 
+---
+
+## 12. Dynamic Model Row-Level Security (RLS)
+
+Webspresso ORM features zero-dependency, declarative Row-Level Security (RLS) directly on model definitions, ensuring data isolation across users, organizations, and multi-tenant systems.
+
+### 12.1 Declaring RLS Policies on Models
+
+Models declare row-level access rules with `rls` inside `defineModel`:
+
+```javascript
+const { defineModel, zdb } = require('webspresso');
+
+module.exports = defineModel({
+  name: 'Document',
+  table: 'documents',
+  schema: zdb.schema({
+    id: zdb.id(),
+    user_id: zdb.integer(),
+    tenant_id: zdb.string().optional(),
+    title: zdb.string(),
+    content: zdb.text(),
+    status: zdb.string().default('draft'),
+    is_public: zdb.boolean().default(false),
+  }),
+  rls: {
+    // Shorthand: automatically scopes queries and mutations to user.id
+    userColumn: 'user_id',
+
+    // Multi-tenant shorthand: scopes to user.tenant_id or scopeContext.tenantId
+    tenantColumn: 'tenant_id',
+
+    // Role-based bypass: admins and superadmins bypass RLS by default
+    bypassRoles: ['admin', 'superadmin'],
+
+    // Granular action rules:
+    // Read / Select: public documents are visible to anyone, drafts only to author
+    read: (user, qb) => {
+      if (!user) return { is_public: true };
+      return (q) => q.where('user_id', user.id).orWhere('is_public', true);
+    },
+
+    // Update: only allow modifying draft documents
+    update: (user, qb) => {
+      if (!user) return false;
+      return (q) => q.where('user_id', user.id).where('status', 'draft');
+    },
+
+    // Delete: completely disabled or owner only
+    delete: (user, qb) => {
+      if (!user) return false;
+      return { user_id: user.id };
+    },
+
+    // Create: auto-populates user_id, validates permissions or modifies payload
+    create: (user, data) => {
+      if (!user) return false; // Throws UnauthorizedError/ForbiddenError
+      return { status: 'draft' }; // Enforce default state
+    },
+  },
+});
+```
+
+### 12.2 Scoping Repositories and Query Builders
+
+Repositories and query builders provide fluent scoping methods:
+
+```javascript
+const repo = db.getRepository('Document');
+
+// Scoped to specific user:
+const userRepo = repo.forUser(currentUser);
+const myDocs = await userRepo.findAll();
+const myDoc = await userRepo.findById(docId); // null if not owned
+
+// Auto-populates user_id and rejects spoofed user IDs:
+const newDoc = await userRepo.create({ title: 'My Report' });
+
+// QueryBuilder chaining:
+const count = await repo.query().forUser(currentUser).where('status', 'draft').count();
+const paged = await repo.query().forUser(currentUser).paginate(1, 10);
+
+// Explicit bypass (system/admin operations):
+const allDocs = await repo.withoutRls().findAll();
+const total = await repo.query().withoutRls().count();
+
+// Multi-tenant scoping:
+const tenantRepo = repo.forTenant('org_acme');
+```
+
+### 12.3 Database Scoped Accessors
+
+```javascript
+// Scoped database instance:
+const userDb = db.forUser(currentUser);
+const docs = await userDb.getRepository('Document').findAll();
+const drafts = await userDb.query('Document').where('status', 'draft').list();
+
+// Ambient transaction scoping:
+await db.transaction(async (trx) => {
+  const noteRepo = trx.forUser(currentUser).getRepository('Document');
+  await noteRepo.create({ title: 'Transaction Document' });
+});
+```
+
+### 12.4 Automatic Express Integration (`rlsPlugin`)
+
+Register `rlsPlugin()` to automatically wrap `req.db.getRepository()` with `req.user` in API endpoints and SSR loaders:
+
+```javascript
+const { createApp, rlsPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    rlsPlugin({
+      bypassRoles: ['admin', 'superadmin'], // default
+      getUser: (req) => req.user,           // default
+    }),
+  ],
+});
+
+// Inside any API route (pages/api/documents.get.js):
+module.exports = defineApi({
+  handler: async (req, res) => {
+    // req.db.getRepository('Document') is automatically scoped to req.user!
+    const docs = await req.db.getRepository('Document').findAll();
+    return res.json(docs);
+  },
+});
+```
+
+
 
 

package/.agents/PLUGINS.md

@@ -161,12 +161,19 @@ Schema-driven headless CMS & inline content editing.
 - **Features**: Dynamic content types & entries, public API (`/api/content/:type/:slug`), visual inline editor widget.
 
 ### 2.4 `uploadPlugin` (`plugins/upload`)
-Multipart file upload manager with local / cloud storage providers.
-- **Options**: `{ path: '/api/upload', local: { destDir, publicBasePath }, maxBytes: 10000000, mimeAllowlist: ['image/png', 'image/jpeg'] }`
-- **Features**: Single & multi-file uploads, file size & extension validation, storage drivers.
+Multipart file upload manager with local disk, AWS S3, Google Cloud Storage (GCS), and Cloudflare R2 drivers.
+- **Options**: `{ path: '/api/upload', provider, local: { destDir, publicBasePath }, maxBytes: 10000000, mimeAllowlist: ['image/png', 'image/jpeg'], presigned: true, presignedRoute: '/api/upload/presign' }`
+- **Supported Storage Drivers**:
+  - `createLocalFileProvider({ destDir, publicBasePath })`: Local disk storage (monolith / VPS).
+  - `createS3FileProvider({ s3Client, bucket, publicBaseUrl, prefix })`: AWS S3, MinIO, or S3-compatible endpoints with direct presigned PUT URLs (`createSignedUploadUrl`).
+  - `createGcsFileProvider({ bucket, storageClient, publicBaseUrl, prefix })`: Google Cloud Storage with V4 signed URLs for serverless direct uploads.
+  - `createR2FileProvider({ bucket, publicBaseUrl, prefix })`: Cloudflare Workers native R2 binding.
+- **Direct-to-Cloud Presigned Uploads**: Set `presigned: true` to mount `POST /api/upload/presign`, allowing web browsers to upload directly to S3 or GCS without passing large payloads through memory-limited or ephemeral containers.
+- **Static Asset Sync**: `webspresso assets:sync [--bucket <name>] [--provider s3|gcs|r2] [--dry-run]` to upload compiled JS/CSS bundles to cloud storage with `Cache-Control: public, max-age=31536000, immutable`.
 - **Orphan Pruning**: `scanOrphanedUploads({ db, destDir })` and `pruneOrphanedUploads({ db, destDir, dryRun })` to detect and remove disk files no longer referenced by any database model, accompanied by CLI command `webspresso upload:prune [--dry-run]`.
 
 
+
 ### 2.5 `fileManagerPlugin` (`plugins/file-manager`)
 Filesystem-first media library, directory explorer, and modal asset picker for Admin Panel.
 - **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'File Manager', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true, lazy: false }`
@@ -692,3 +699,31 @@ Zero-dependency on-demand plugin hydration wrapper that defers heavy plugin init
   - Mounts a lightweight Express router proxy at `prefix`.
   - Stubs placeholder services into `ServiceRegistry` and proxy helpers into Nunjucks context.
   - Intercepts incoming requests/calls, executes the plugin factory function, runs `register(ctx)` and `onRoutesReady(ctx)`, replaces proxies seamlessly with the real router/services, and forwards the initial call with zero dropped requests.
+
+### 2.21 `rlsPlugin` (`plugins/rls`)
+Zero-dependency Dynamic Model Row-Level Security (RLS) plugin that bridges request authentication (`req.user`, `req.auth`, `req.tenantId`) to ORM repositories with automatic query scoping, role-based bypass, and route-level overrides.
+- **Why**: Eliminates manual `where({ user_id: req.user.id })` boilerplate across all API endpoints, prevents accidental cross-tenant/cross-user data leakage, and provides declarative data access boundaries.
+- **Options**:
+  - `bypassRoles`: Global roles that bypass RLS across all models (default: `['admin', 'superadmin']`). Set to `false` to disable.
+  - `getUser`: Custom extractor for current user from `req` (default: `req.user || req.adminUser || req.auth?.user`).
+  - `getTenantId`: Custom extractor for current tenant ID from `req` (default: `req.tenantId || req.user?.tenant_id`).
+  - `global`: Mount global middleware wrapping `req.db` (default: `true`).
+  - `enabled`: Toggle RLS plugin active state (default: `true`).
+- **Usage**:
+  ```javascript
+  const { createApp, rlsPlugin } = require('webspresso');
+
+  const app = createApp({
+    plugins: [
+      rlsPlugin({
+        bypassRoles: ['admin', 'superadmin'],
+      }),
+    ],
+  });
+  ```
+- **How It Works**:
+  - Automatically wraps `req.db.getRepository()` and `req.db.query()` with the active `user` and `tenantId`.
+  - Admins bypass filters automatically unless model specifies `bypassRoles: false`.
+  - Endpoints can explicitly bypass RLS when needed via `req.db.getRepository('Model').withoutRls()`.
+  - Named middleware `middleware: ['rls']` available for selective route application.
+

package/.agents/QUEUE.md

@@ -92,6 +92,48 @@ queuePlugin({
 });
 ```
 
+### 4. `SqsQueueAdapter` (AWS SQS)
+Zero-dependency AWS SQS adapter powered by native Node.js HTTP and standard AWS SigV4 request signing. Supports long-polling worker loops (`dequeue`), direct enqueue with delay seconds calculation, and AWS Lambda push batch execution (`processBatch`).
+
+```js
+const { SqsQueueAdapter } = require('webspresso');
+
+// Worker daemon or long-polling runner:
+const adapter = new SqsQueueAdapter({
+  queueUrl: process.env.AWS_SQS_QUEUE_URL,
+  region: process.env.AWS_REGION || 'us-east-1',
+  waitTimeSeconds: 10,
+  visibilityTimeout: 30,
+});
+
+// AWS Lambda SQS Event Handler:
+exports.handler = async (event) => {
+  return adapter.processBatch(event.Records, queueManager);
+};
+```
+
+### 5. `PubSubQueueAdapter` (Google Cloud Pub/Sub)
+Zero-dependency Google Cloud Pub/Sub adapter using standard REST API (`:publish`, `:pull`, `:acknowledge`, `:modifyAckDeadline`) with base64 payload serialization. Supports both background pull workers and Cloud Run / App Engine Push Subscription HTTP webhooks (`processPushRequest`).
+
+```js
+const { PubSubQueueAdapter } = require('webspresso');
+
+const adapter = new PubSubQueueAdapter({
+  projectId: process.env.GOOGLE_CLOUD_PROJECT,
+  topic: 'app-jobs',
+  subscription: 'app-jobs-sub',
+});
+
+// Cloud Run Push Subscription Webhook Route:
+app.post('/api/queue/push', async (req, res) => {
+  await adapter.processPushRequest(req, res, req.queue);
+});
+```
+
+### 6. `WaitUntilQueueAdapter` & `CloudflareQueueAdapter`
+- `WaitUntilQueueAdapter`: Serverless & Edge execution (Cloudflare Workers `ctx.waitUntil`, Vercel Edge).
+- `CloudflareQueueAdapter`: Cloudflare Queues integration (`env.MY_QUEUE.send`).
+
 ---
 
 ## 4. File-Based Auto-Discovery (`jobs/`)

package/.agents/RATE_LIMIT.md

@@ -0,0 +1,147 @@
+# Native Zero-Dependency Rate Limiting Engine (`core/rate-limit`)
+
+Webspresso features a high-performance, zero-dependency Rate Limiting Engine located in `core/rate-limit/`. It works seamlessly across both traditional Express middleware pipelines and modern edge/serverless contexts (such as Hono), providing standard RFC 6585 and IETF Draft rate limit headers with memory leak-free in-memory and distributed Redis sliding-window stores.
+
+---
+
+## 🎯 Native Core vs. Plugin Comparison
+
+| Feature | Core Rate Limiter (`core/rate-limit`) | Rate Limit Plugin (`plugins/rate-limit`) |
+| :--- | :--- | :--- |
+| **Dependencies** | **Zero external dependencies** (pure Node.js) | Requires `express-rate-limit` peer dependency |
+| **Import** | `const { rateLimit, RateLimiter } = require('webspresso')` | `const { rateLimitPlugin } = require('webspresso')` |
+| **Framework Agnostic** | ✅ Express `(req, res, next)` & Hono `(c, next)` | Express only |
+| **Stores** | Native Sliding Window `MemoryRateLimitStore` & `RedisRateLimitStore` | `express-rate-limit` memory or external store |
+| **Headers** | RFC 6585 `RateLimit-*`, `Retry-After`, legacy `X-RateLimit-*` | `standardHeaders: 'draft-7'`, `legacyHeaders` |
+| **File Route Usage** | Universal middleware in API routes and standalone apps | Named middleware via `ctx.middlewares.rateLimit` |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Basic Express Route Limiting
+
+```javascript
+const { rateLimit } = require('webspresso');
+
+// 60 requests per minute
+const apiLimiter = rateLimit({
+  window: '1m',
+  limit: 60,
+});
+
+// Use as standard middleware
+app.use('/api', apiLimiter);
+```
+
+### 2. File-Based API Route (`pages/api/...`)
+
+```javascript
+const { defineApi, rateLimit } = require('webspresso');
+
+const strictLimiter = rateLimit({
+  window: '10s',
+  limit: 5,
+  message: { error: 'Too many requests. Please slow down.' },
+});
+
+module.exports = defineApi({
+  middleware: [strictLimiter],
+  handler: async (req, res) => {
+    return res.json({ success: true });
+  },
+});
+```
+
+### 3. Distributed Redis Rate Limiting (Scale-Out)
+
+```javascript
+const { rateLimit, RedisRateLimitStore } = require('webspresso');
+const Redis = require('ioredis');
+
+const redis = new Redis(process.env.REDIS_URL);
+
+const limiter = rateLimit({
+  window: '15m',
+  limit: 100,
+  store: new RedisRateLimitStore({
+    client: redis,
+    prefix: 'rl:auth:',
+    passOnStoreError: true, // Fail-open if Redis drops
+  }),
+});
+```
+
+### 4. Edge / Hono Application Usage
+
+The middleware automatically detects Hono's `(c, next)` context signature:
+
+```javascript
+const { Hono } = require('hono');
+const { rateLimit } = require('webspresso');
+
+const app = new Hono();
+const limiter = rateLimit({ limit: 100, window: '1m' });
+
+app.use('*', (c, next) => limiter(c, next));
+```
+
+---
+
+## ⚙️ Options Reference
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `limit` / `max` | `number` | `60` | Maximum number of allowed requests within the time window. |
+| `window` / `windowMs`| `string\|number` | `'1m'` | Window duration in ms or string shorthand (`'500ms'`, `'10s'`, `'1m'`, `'1h'`, `'1d'`). |
+| `store` | `RateLimitStore` | `MemoryRateLimitStore` | Underlying storage engine. Defaults to sliding window in-memory store. |
+| `keyGenerator` | `(req) => string` | `extractClientIp` | Function to identify client. Extracts Cloudflare, X-Forwarded-For, or socket IP by default. |
+| `skip` | `(req) => boolean` | `() => false` | Condition to skip rate limiting (e.g. internal healthchecks). |
+| `standardHeaders` | `boolean` | `true` | Send standard RFC headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`). |
+| `legacyHeaders` | `boolean` | `false` | Send legacy `X-RateLimit-*` headers. |
+| `skipFailedRequests` | `boolean` | `false` | When `true`, failed requests (`statusCode >= 400`) decrement hit count upon finish. |
+| `skipSuccessfulRequests`| `boolean` | `false` | When `true`, successful requests (`statusCode < 400`) decrement hit count upon finish. |
+| `statusCode` | `number` | `429` | HTTP status code returned when limit is exceeded. |
+| `message` | `string\|object` | `{ error: 'Too Many Requests', ... }` | Response payload on limit exceeded. |
+| `handler` | `Function` | `null` | Custom callback when limit is exceeded `(req, res, next, info) => void`. |
+
+---
+
+## 📡 HTTP Response Headers
+
+When enabled, the rate limiter emits standard headers:
+
+```http
+HTTP/1.1 200 OK
+RateLimit-Limit: 60
+RateLimit-Remaining: 58
+RateLimit-Reset: 42
+RateLimit-Policy: 60;w=60
+```
+
+When the limit is exceeded (HTTP 429 Too Many Requests):
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 42
+RateLimit-Limit: 60
+RateLimit-Remaining: 0
+RateLimit-Reset: 42
+RateLimit-Policy: 60;w=60
+Content-Type: application/json
+
+{"error":"Too Many Requests","message":"Too many requests, please try again later.","statusCode":429}
+```
+
+---
+
+## 🛡️ Reverse Proxy & Client IP Extraction
+
+`extractClientIp(req)` extracts client IP in the following priority order:
+1. `req.ip` (Express `trust proxy`)
+2. `CF-Connecting-IP` (Cloudflare)
+3. `Fastly-Client-IP` / `True-Client-IP` (Fastly / Akamai)
+4. `X-Forwarded-For` (First client IP in comma-separated list)
+5. `X-Real-IP` (Nginx / HAProxy)
+6. `socket.remoteAddress` (Normalized IPv4 / IPv6)
+7. Fallback `127.0.0.1`

package/.agents/RESILIENCE.md

@@ -0,0 +1,235 @@
+# Enterprise Resilience, Circuit Breaker & Retry Engine (`core/resilience`)
+
+Webspresso includes a zero-dependency, enterprise-grade resilience and fault tolerance engine built directly on native Node.js primitives (`events`, `perf_hooks`, `async_hooks`). It prevents cascading downstream outages, protects critical services, and recovers automatically from transient network spikes.
+
+---
+
+## 🚦 Architectural Overview
+
+```
+                      ┌───────────────────────────────────────┐
+                      │            Incoming Request           │
+                      └───────────────────┬───────────────────┘
+                                          │
+                                          ▼
+                      ┌───────────────────────────────────────┐
+                      │    Circuit Breaker (Fast Fail / OPEN) │
+                      └───────┬───────────────────────▲───────┘
+                     (Closed) │                       │ (Trips on failure)
+                              ▼                       │
+                      ┌───────────────────────────────┴───────┐
+                      │    Retry Engine (Backoff + Jitter)    │
+                      └───────┬───────────────────────▲───────┘
+                     (Attempt)│                       │ (Transient Error)
+                              ▼                       │
+                      ┌───────────────────────────────┴───────┐
+                      │   Service Handler / Remote Upstream   │
+                      └───────────────────────────────────────┘
+```
+
+1. **State Machine (`CircuitBreaker`)**:
+   - `CLOSED`: Normal operation. Requests pass through. Failures are tracked in a rolling time window.
+   - `OPEN`: Downstream is degraded/unhealthy. Subsequent calls **fail fast immediately** with `CircuitBreakerOpenError` (HTTP 503) without hitting the downstream resource, or return a predefined `fallback`.
+   - `HALF_OPEN`: Trial recovery state entered automatically once `resetTimeout` elapses. A controlled number of probe requests (`successThreshold`) test the downstream. If they succeed, the breaker resets to `CLOSED`. If any probe fails, it trips back to `OPEN`.
+
+2. **Retry with Exponential Backoff & Full Jitter (`retry`, `withRetry`)**:
+   - Automatically retries transient network errors (`ECONNRESET`, `ETIMEDOUT`, `ENOTFOUND`, 429 Too Many Requests, and 5xx Gateway errors).
+   - Skips client-side 4xx errors (e.g. 400 Bad Request, 401, 403, 404, 422) since retrying client errors produces identical failures.
+   - Full jitter prevents synchronization spikes (the "thundering herd" problem) against recovering third-party services.
+   - Respects `AbortSignal` for cancellation.
+
+3. **Seamless Services Layer Integration**:
+   - Declare `circuitBreaker` and `retry` declaratively inside `defineService({ ... })`.
+   - Automatically protects service calls from SSR pages, API routes, or worker jobs.
+
+---
+
+## 🛠️ Quick Start & Usage Examples
+
+### 1. Declarative Service Protection (`defineService`)
+
+```javascript
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  // Automatic retry on transient network errors
+  retry: {
+    retries: 3,
+    delay: '100ms',
+    factor: 2,
+    jitter: true,
+  },
+
+  // Circuit breaker with fast-fail and graceful fallback
+  circuitBreaker: {
+    failureThreshold: 3,          // Open after 3 consecutive failures
+    failureRateThreshold: 0.5,    // Or if >= 50% fail in rolling window
+    rollingWindow: '10s',         // 10-second sample window
+    resetTimeout: '15s',          // Stay open for 15s before trial recovery
+    timeout: '3s',                // Per-call execution timeout (ms or string)
+    fallback: (err, input) => {
+      // Graceful fallback returned when OPEN or when all retries fail
+      return { fromCache: true, id: input.id, data: null, degraded: true };
+    },
+  },
+
+  schema: ({ z }) => ({
+    id: z.string(),
+  }),
+
+  handler: async (input, ctx) => {
+    // Call external payment or inventory API
+    const response = await fetch(`https://api.external.com/items/${input.id}`);
+    if (!response.ok) {
+      const err = new Error(`Upstream API responded with status ${response.status}`);
+      err.statusCode = response.status;
+      throw err;
+    }
+    return await response.json();
+  },
+});
+```
+
+### 2. Standalone Circuit Breaker Usage
+
+```javascript
+const { createCircuitBreaker } = require('webspresso');
+
+const paymentBreaker = createCircuitBreaker({
+  name: 'stripe-gateway',
+  failureThreshold: 5,
+  resetTimeout: '30s',
+  timeout: '5s',
+  fallback: (err) => {
+    return { status: 'queued_offline', message: 'Payment queued for processing' };
+  },
+});
+
+// Execute async function wrapped by breaker
+const result = await paymentBreaker.execute(async () => {
+  return await stripeClient.charges.create({ ... });
+});
+
+// Or wrap a function
+const safeCharge = paymentBreaker.wrap(chargeFunction);
+await safeCharge(args);
+```
+
+### 3. Standalone Retry Engine (`retry`)
+
+```javascript
+const { retry, isTransientError } = require('webspresso');
+
+const data = await retry(
+  async (attempt) => {
+    return await fetchRemoteData();
+  },
+  {
+    retries: 3,
+    delay: 200,          // Initial 200ms delay
+    factor: 2,           // 200ms -> 400ms -> 800ms
+    jitter: true,        // Randomized jitter
+    onRetry: ({ attempt, error, delayMs }) => {
+      console.warn(`Retry attempt ${attempt} after error: ${error.message} (waiting ${delayMs}ms)`);
+    },
+  }
+);
+```
+
+### 4. Accessing Breakers & Retry from Route Handlers & Context
+
+In API routes and SSR loaders:
+
+```javascript
+// Inside API route handler or SSR loader
+export async function handler(req, res) {
+  // Named circuit breaker from central registry
+  const crmBreaker = req.breaker('hubspot-api', { failureThreshold: 3 });
+
+  // Retry engine available on req
+  const lead = await req.retry(async () => {
+    return await pushLeadToCrm(req.body);
+  }, { retries: 2 });
+
+  return res.json(lead);
+}
+```
+
+In services handlers (`ctx`):
+
+```javascript
+module.exports = defineService({
+  handler: async (input, ctx) => {
+    // Access circuit breaker
+    const breaker = ctx.breaker('custom-api');
+    
+    // Access retry helper
+    return await ctx.retry(async (attempt) => {
+      return await queryDownstream();
+    });
+  },
+});
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+### `CircuitBreakerOptions`
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `string` | `'default'` | Identifier for logging and registry lookup. |
+| `failureThreshold` | `number` | `5` | Consecutive failures before opening circuit. |
+| `failureRateThreshold` | `number` | `null` | Failure rate (0.01 - 1.0) in rolling window to open circuit (e.g. `0.5` = 50%). |
+| `minimumRequests` | `number` | `5` | Minimum calls in rolling window before failure rate check activates. |
+| `rollingWindow` | `number \| string` | `10000` (10s) | Rolling time window for metrics sample pruning. |
+| `successThreshold` | `number` | `2` | Consecutive successes in `HALF_OPEN` state required to close circuit. |
+| `resetTimeout` | `number \| string` | `10000` (10s) | Duration circuit stays `OPEN` before attempting `HALF_OPEN` probe. |
+| `timeout` | `number \| string` | `0` (disabled) | Per-call execution timeout in milliseconds or duration string (`'2s'`). |
+| `fallback` | `Function` | `null` | Fallback handler `(error, ...args) => any` called when `OPEN` or call fails. |
+| `isFailure` | `Function` | `defaultIsFailure` | Predicate `(error) => boolean`. By default ignores 4xx client errors (except 429). |
+| `onStateChange` | `Function` | `null` | Callback `(fromState, toState, breaker) => void`. |
+
+### `RetryOptions`
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `retries` | `number` | `3` | Maximum retry attempts before giving up. |
+| `delay` / `minTimeout` | `number \| string` | `100` | Initial delay in ms or duration string (`'100ms'`). |
+| `maxTimeout` | `number \| string` | `10000` (10s) | Maximum capped delay for exponential backoff. |
+| `factor` | `number` | `2` | Exponential backoff multiplier. |
+| `jitter` | `boolean` | `true` | Apply full randomized jitter (`Math.random() * delay`). |
+| `shouldRetry` | `Function` | `isTransientError` | Predicate `(error, attempt) => boolean`. Retries network/5xx/429 errors. |
+| `onRetry` | `Function` | `null` | Hook `({ attempt, error, delayMs }) => void`. |
+| `signal` | `AbortSignal` | `null` | Optional signal to cancel pending retry delays immediately. |
+
+---
+
+## 📊 Telemetry & Monitoring
+
+Inspect health and failure metrics at any time:
+
+```javascript
+// Breaker instance stats
+const stats = breaker.getStats();
+// {
+//   name: 'stripe-gateway',
+//   state: 'CLOSED',
+//   totalCalls: 120,
+//   successfulCalls: 118,
+//   failedCalls: 2,
+//   rejectedCalls: 0,
+//   timedOutCalls: 0,
+//   fallbackCalls: 0,
+//   consecutiveFailures: 0,
+//   consecutiveSuccesses: 118,
+//   failureRate: 0.016,
+//   lastFailureTime: 1713430000000,
+//   lastSuccessTime: 1713430001000,
+//   lastStateChange: 1713429000000
+// }
+
+// Global registry stats across all breakers
+const allStats = app.breakers.getStats();
+```