@goodandready/dsh-key-rotation 0.7.39 → 0.8.0

package/README.md

@@ -28,6 +28,17 @@
 
 ## ⚡ Overview & The Problem
 
+### 🛠️ What's New in v0.8.0 (Stability)
+- **🔌 Circuit breaker**: after N consecutive provider failures the circuit opens and requests fail fast (`CIRCUIT_OPEN`) until a cool-down; half-open probes recover automatically.
+- **🕒 Monotonic clock**: cooldown/breaker durations use process monotonic time so NTP steps cannot invert remaining times.
+- **📮 Non-blocking webhooks**: alerts go through a bounded queue with backoff — stream rotation never waits on webhook HTTP.
+- **🧱 Atomic I/O helpers**: crash-safe writes; corrupt JSON never overwrites previous in-memory state.
+- **🧹 Clone-route GC**: orphaned auto-created clone routes are dropped from the runtime set.
+- **🧭 Error taxonomy**: explicit switch/surface/soft classification for 408/425/429/5xx, sockets and gRPC codes.
+- **📡 Status extras**: per-provider `circuit` plus `meta.expectedClones` / `meta.notifyQueue`.
+- **🧪 Smoke harness**: scripted 429 → next-key → success path in `test/smoke-rotation-080.test.mjs`.
+
+
 ### 🛠️ What's New in v0.7.33 (Stability & Bugfix Release)
 - **🔍 Resolved Key Probing BaseURL**: Fixed `resolveBaseUrl` to map key credential refs to owning provider pools, restoring live `probeModels` testing.
 - **🛡️ Guarded Cascade Recursion**: Prevented call stack overflow in cross-provider failover when circular cascade chains occur.
@@ -57,7 +68,7 @@ Unlike naive routing proxies that alter provider identifiers, `dsh-key-rotation`
 * **The provider identity never changes**: Agent replay states, multi-call turns, and tool schemas remain 100% consistent.
 * **Pre-emptive Token Bucket**: Throttled keys are skipped *before* issuing network calls, eliminating retry latency.
 * **Least-Connections Concurrency Control**: Balances in-flight streams across keys to prevent burst saturation.
-* **Autonomous Self-Healing & Cascades**: Proactively tests quarantined keys via canary probes and smoothly escalates to fallback providers if an entire pool is exhausted.
+* **Autonomous Self-Healing & Cascades**: Lifts expired quarantines on idle keys and smoothly escalates to fallback providers if an entire pool is exhausted.
 
 ---
 
@@ -85,8 +96,8 @@ graph LR
         Failover -.->|All Pool Keys Exhausted| CascadeEngine["Cross-Provider Cascade"]
         
         BackoffCalc --> QuotaWindow["Calendar Reset / Midnight Window"]
-        BackoffCalc --> CanaryProbe["Active Canary Prober (Sandbox Ping)"]
-        CanaryProbe -->|Verified Healthy| PoolReady["Restored to Ready Pool"]
+        BackoffCalc --> SelfHeal["Self-Heal Idle Sweep"]
+        SelfHeal -->|Cooldown Expired| PoolReady["Restored to Ready Pool"]
     end
 
     subgraph UpstreamLayer ["Model Provider Endpoints"]
@@ -117,21 +128,18 @@ graph LR
 
 ### 🛡️ 3. Autonomous Healing & Cascade Escalation
 * **Cross-Provider Failover Cascade (`lib/cascade.js`)**: If all keys for a selected provider are in cooldown, requests automatically cascade to an alternative fallback provider pool (e.g., primary provider → fallback proxy / secondary provider).
-* **Active Canary Prober (`lib/canary.js`)**: Before releasing a key from quarantine, a lightweight background probe (`/models` probe or single-token check via `SandboxRunner`) validates upstream availability without exposing real user traffic to risk.
+* **Sandbox Key Probes (`lib/sandbox.js`)**: On-demand `/models` probes validate a key before returning it to rotation; idle cooldowns are lifted by the self-heal sweep.
 * **Calendar & Rolling Quota Reset Windows (`lib/quota-window.js`)**: Supports scheduled quota reset alignments (`midnight_utc`, `midnight_pst`, and `rolling_24h`) so daily free/tier quotas unfreeze exactly when upstream resets them.
 * **Adaptive Exponential Backoff (`lib/pool.js`)**: Successive failures on a key double its quarantine duration (base → ×2 → ×4 → cap ×8). Successful requests gradually restore healthy status.
 
-### 🎯 4. Model-Aware & Geolocation Routing
+### 🎯 4. Model-Aware Routing
 * **Model Sub-Pools (`lib/pool.js`)**: Configure dedicated key pools for specific model tiers (e.g. reasoning/heavy models vs fast/cheap utility models).
 * **Tag-Based Routing**: Assign operational tags (`production`, `background`, `eval`) to match key usage with workload priorities.
-* **Region Mapping (`lib/region.js`)**: Route queries through geographically optimal credentials and endpoints.
 
 ### 📊 5. Observability, Telemetry & Webhooks
 * **Interactive Multi-Platform Webhooks (`lib/webhook.js`)**: Dispatches rich notifications with HMAC-signed action buttons for **Telegram** (Inline Keyboards), **Discord** (Action Rows), and **Slack** (Block Kit). Administrators can click buttons to reset cooldowns or pause providers directly from their mobile chat.
 * **Usage & Cost Reporting (`lib/usage-report.js`)**: Per-key daily request counters and estimated cost breakdown with one-click CSV/JSON export (`GET /dsh-key-rotation/usage-report`).
 * **Latency SLO & Histogram (`lib/histogram.js`)**: Tracks Time-To-First-Token (TTFT) and stream durations with health score degradation scoring (`0..100`).
-* **Automated Incident Reporting (`lib/incident.js`)**: Lazily creates structured GitHub Issues on sustained upstream outages.
-* **Shadow Traffic Routing (`lib/shadow.js`)**: Fork a configurable percentage of live requests to evaluate secondary providers in shadow mode.
 
 ---
 
@@ -195,7 +203,11 @@ dsh-key-rotation:
     - UNKNOWN_MODEL
     - AUTH
   cooldownMs: 60000
-  canaryProbing: true
+  # v0.8.0 circuit breaker
+  circuitBreakerEnabled: true
+  circuitBreakerThreshold: 5
+  circuitBreakerOpenMs: 30000
+  circuitBreakerHalfOpenProbes: 1
   concurrencyLimit: 5
   quotaResetWindow:
     type: midnight_utc
@@ -224,7 +236,11 @@ dsh-key-rotation:
 |---|---|---|---|
 | `switchCodes` | `string[]` | `[QUOTA, RATE_LIMIT, ...]` | List of error codes that immediately trigger failover. |
 | `cooldownMs` | `number` | `60000` (1 min) | Base penalty duration (in ms) for quarantined keys. |
-| `canaryProbing` | `boolean` | `true` | Runs background ping probe before restoring quarantined keys. |
+| `circuitBreakerEnabled` | `boolean` | `true` | Enable per-provider circuit breaker (v0.8.0). |
+| `circuitBreakerThreshold` | `number` | `5` | Consecutive failures before opening the circuit. |
+| `circuitBreakerOpenMs` | `number` | `30000` | How long the circuit stays open (ms). |
+| `circuitBreakerHalfOpenProbes` | `number` | `1` | Probe requests allowed in half-open state. |
+| `verboseLogging` | `boolean` | `false` | Per-request rotation logs (noisy; off by default). |
 | `concurrencyLimit` | `number` | `0` (disabled) | Max concurrent in-flight streams per key (0 = unlimited). |
 | `quotaResetWindow` | `object` | `null` | Calendar reset alignment (`midnight_utc`, `midnight_pst`, `rolling_24h`). |
 | `cascade` | `array` | `[]` | Fallback provider chain when primary pool is completely exhausted. |
@@ -239,7 +255,7 @@ All management routes require loopback authentication (`127.0.0.1` / `::1`) with
 
 | Route | Method | Description |
 |---|---|---|
-| `/dsh-key-rotation/status` | `GET` | Returns real-time health snapshots, active keys, and cooldown states. |
+| `/dsh-key-rotation/status` | `GET` | Real-time health, keys, cooldowns. Since v0.8.0 also `providers[].circuit` and `meta` (`expectedClones`, `notifyQueue`). |
 | `/dsh-key-rotation/config` | `GET` / `PUT` | Read and update active key rotation settings and provider pools. |
 | `/dsh-key-rotation/key` | `PUT` / `DELETE` | Add, update, or remove credentials in host storage and pool. |
 | `/dsh-key-rotation/reset` | `POST` | Instantly resets all cooldowns and restores all keys to `ready`. |

package/README.ru.md

@@ -28,6 +28,17 @@
 
 ## ⚡ Обзор и решаемая проблема
 
+### 🛠️ Что нового в версии 0.8.0 (Стабильность)
+- **🔌 Автомат выключения провайдера**: после N подряд ошибок контур открывается, запросы быстро завершаются (`CIRCUIT_OPEN`); half-open пробы восстанавливают сервис.
+- **🕒 Монотонные часы**: cooldown/breaker считаются по процессным часам, NTP не ломает оставшееся время.
+- **📮 Неблокирующие webhook**: очередь с backoff — `rotate()` не ждёт HTTP.
+- **🧱 Атомарная запись файлов**: повреждённый JSON не затирает прежнее состояние.
+- **🧹 GC clone-маршрутов**: осиротевшие авто-роуты убираются из runtime-набора.
+- **🧭 Таксономия ошибок**: явная классификация switch/surface/soft (408/425/429/5xx, сокеты, gRPC).
+- **📡 Status**: `circuit` у провайдера + `meta.expectedClones` / `meta.notifyQueue`.
+- **🧪 Smoke**: сценарий 429 → следующий ключ → успех.
+
+
 ### 🛠️ Что нового в версии 0.7.33 (Хотфикс и повышение стабильности)
 - **🔍 Исправление проверки ключей**: Функция `resolveBaseUrl` теперь сопоставляет ref ключа с его пулом, восстанавливая работу живого тестирования моделей.
 - **🛡️ Защита от зацикливания каскада**: Устранена возможность переполнения стека при взаимных кольцевых цепочках failover.
@@ -57,7 +68,7 @@
 * **Идентичность провайдера остаётся неизменной**: Внутреннее Replay-состояние агента `pi-ai` и контекст инструментов остаются на 100% консистентными.
 * **Предиктивный Token Bucket**: Перегруженные ключи пропускаются **до** выполнения сетевого запроса, устраняя задержку на сетевой ретрай.
 * **Балансировка Least-Connections**: Запросы равномерно распределяются по свободным ключам с контролем параллелизма (`maxConcurrency`).
-* **Автономное самовосстановление и каскад**: Фоновые canary-зонды проверяют заблокированные ключи, а при полном исчерпании пула запрос бесшовно передаётся запасному провайдеру.
+* **Автономное самовосстановление и каскад**: Просроченные кулдауны простаивающих ключей снимаются автоматически, а при полном исчерпании пула запрос бесшовно передаётся запасному провайдеру.
 
 ---
 
@@ -85,8 +96,8 @@ graph LR
         Failover -.->|Все ключи в кулдауне| CascadeEngine["Межпровайдерный каскад"]
         
         BackoffCalc --> QuotaWindow["Календарный сброс / Полночь UTC/PST"]
-        BackoffCalc --> CanaryProbe["Active Canary-зонд (Sandbox Ping)"]
-        CanaryProbe -->|Ключ работоспособен| PoolReady["Возврат в пул готовых ключей"]
+        BackoffCalc --> SelfHeal["Self-Heal sweep простаивания"]
+        SelfHeal -->|Кулдаун истёк| PoolReady["Возврат в пул готовых ключей"]
     end
 
     subgraph UpstreamLayer ["Эндпоинты провайдеров"]
@@ -117,21 +128,18 @@ graph LR
 
 ### 🛡️ 3. Автономное самовосстановление и каскадный Failover
 * **Межпровайдерный каскад (`lib/cascade.js`)**: При исчерпании всех ключей выбранного провайдера запрос автоматически каскадируется на настроенного резервного провайдера (`cascade: [{ provider, model }]`).
-* **Active Canary Prober (`lib/canary.js`)**: Перед выводом ключа из кулдауна плагин выполняет легкий фоновый зонд (`/models` probe через `SandboxRunner`), защищая боевой трафик от повторных сбоев.
+* **Sandbox-пробы ключей (`lib/sandbox.js`)**: По запросу выполняется `/models`-проба ключа перед возвратом в ротацию; простаивающие кулдауны снимаются self-heal sweep.
 * **Календарный сброс квот (`lib/quota-window.js`)**: Учитывает окна сброса суточных квот провайдеров (`midnight_utc`, `midnight_pst`, `rolling_24h`), снимая карантин ровно в момент обновления лимитов у апстрима.
 * **Экспоненциальный бэкофф (`lib/pool.js`)**: Повторные сбои на ключе прогрессивно увеличивают время кулдауна (базовое → ×2 → ×4 → максимум ×8).
 
-### 🎯 4. Маршрутизация по моделям и гео-регионам
+### 🎯 4. Маршрутизация по моделям
 * **Модельные подпулы (`lib/pool.js`)**: Назначение выделенных ключей под конкретные модели (например, отдельные ключи для тяжелых reasoning-моделей и дешевые ключи для утилит).
 * **Тегирование ключей**: Метки приоритета (`production`, `background`, `eval`) для разделения квот между интерактивными и фоновыми задачами.
-* **Гео-роутинг (`lib/region.js`)**: Маршрутизация запросов через оптимальные региональные эндпоинты.
 
 ### 📊 5. Телеметрия, аналитика и интерактивные вебхуки
 * **Интерактивные вебхуки (`lib/webhook.js`)**: Отправка форматированных алертов с кнопками действий в **Telegram** (Inline Keyboards), **Discord** (Action Rows) и **Slack** (Block Kit). Администратор может сбросить кулдаун или отключить провайдер прямо из мессенджера.
 * **Отчеты об использовании и расходах (`lib/usage-report.js`)**: Учет суточного числа запросов и расчетной стоимости по каждому ключу с экспортом в CSV/JSON (`GET /dsh-key-rotation/usage-report`).
 * **Гистограмма задержек SLO (`lib/histogram.js`)**: Измерение времени до первого токена (TTFT) и расчет индекса здоровья пула (`0..100`).
-* **Автоматические инциденты (`lib/incident.js`)**: Создание issue в GitHub при масштабных системных сбоях провайдеров.
-* **Shadow-трафик (`lib/shadow.js`)**: Теневое дублирование процента запросов для тестирования альтернативных провайдеров.
 
 ---
 
@@ -195,7 +203,10 @@ dsh-key-rotation:
     - UNKNOWN_MODEL
     - AUTH
   cooldownMs: 60000
-  canaryProbing: true
+  circuitBreakerEnabled: true
+  circuitBreakerThreshold: 5
+  circuitBreakerOpenMs: 30000
+  circuitBreakerHalfOpenProbes: 1
   concurrencyLimit: 5
   quotaResetWindow:
     type: midnight_utc
@@ -224,7 +235,6 @@ dsh-key-rotation:
 |---|---|---|---|
 | `switchCodes` | `string[]` | `[QUOTA, RATE_LIMIT, ...]` | Список кодов ошибок, инициирующих немедленный переход на следующий ключ. |
 | `cooldownMs` | `number` | `60000` (1 мин) | Базовая длительность нахождения ключа в карантине (в мс). |
-| `canaryProbing` | `boolean` | `true` | Фоновая проверка ключа canary-зондом перед возвратом из карантина. |
 | `concurrencyLimit` | `number` | `0` (отключено) | Лимит одновременных активных запросов на ключ (0 = без ограничений). |
 | `quotaResetWindow` | `object` | `null` | Календарное расписание сброса квот (`midnight_utc`, `midnight_pst`, `rolling_24h`). |
 | `cascade` | `array` | `[]` | Цепочка резервных провайдеров при исчерпании всех ключей основного пула. |
@@ -287,3 +297,16 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 - **Архитектура настроек**: Добавлена нативная интеграция со снимками `settingsScope` в карточке настроек с безопасным фоллбеком на HTTP-мост (#235).
 - **Локализация**: Фоллбек секции настроек `settings.section` переведён на локализованную метку `t('title')` со слотом `locale: NS`, а китайский словарь `zh` зарегистрирован в `ctx.locale` наряду с `en` и `ru` (#236).
 - **Удаление мёртвого кода**: Удалена неиспользуемая функция `mountDashboard` после перехода на header chip (#240).
+
+### Параметры circuit breaker (Changed in v0.8.0)
+
+| Параметр | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `circuitBreakerEnabled` | boolean | `true` | Включить/выключить breaker |
+| `circuitBreakerThreshold` | number | `5` | Число подряд ошибок до открытия |
+| `circuitBreakerOpenMs` | number | `30000` | Длительность open, мс |
+| `circuitBreakerHalfOpenProbes` | number | `1` | Проб в half-open |
+| `verboseLogging` | boolean | `false` | Подробные логи rotation (шумно) |
+
+Status API (v0.8.0): у каждого провайдера `circuit`, в корне ответа `meta.expectedClones` и `meta.notifyQueue`.
+

package/README.zh.md

@@ -28,6 +28,17 @@
 
 ## ⚡ 概述与核心痛点
 
+### 🛠️ v0.8.0 版本新特性（稳定性）
+- **🔌 熔断器**：连续失败后快速失败（`CIRCUIT_OPEN`），半开探测自动恢复。
+- **🕒 单调时钟**：冷却/熔断使用进程单调时间，NTP 校时不会颠倒剩余时间。
+- **📮 非阻塞 Webhook**：有界队列 + backoff，轮换不等待 HTTP。
+- **🧱 原子写文件**：损坏 JSON 不会覆盖既有状态。
+- **🧹 克隆路由 GC**：清理孤儿自动路由。
+- **🧭 错误分类**：408/425/429/5xx、套接字与 gRPC 的 switch/surface/soft。
+- **📡 Status**：提供商 `circuit` + `meta`。
+- **🧪 Smoke**：429 → 切换密钥 → 成功。
+
+
 ### 🛠️ v0.7.33 版本新特性 (稳定性与问题修复)
 - **🔍 修复密钥探测 BaseURL 解析**：`resolveBaseUrl` 现已支持从密钥 ref 反查归属提供商池，恢复在线模型连通性探测。
 - **🛡️ 防御级联无限递归**：在跨提供商故障转移中增加递归深度防护，彻底杜绝循环级联导致的堆栈溢出。
@@ -117,7 +128,7 @@ graph LR
 
 ### 🛡️ 3. 自动愈合与跨提供商级联
 * **跨提供商故障转移级联 (`lib/cascade.js`)**：主提供商密钥全部冷却时，自动级联路由到备用提供商池。
-* **金丝雀探针探活 (`lib/canary.js`)**：密钥出冷却期前，自动发起轻量探测验证上游可用性，避免影响用户真实请求。
+* **沙箱密钥探测 (`lib/sandbox.js`)**：按需对密钥执行 `/models` 探测后再回到轮换；空闲冷却由 self-heal sweep 解除。
 * **配额日历重置对齐 (`lib/quota-window.js`)**：支持 `midnight_utc`、`midnight_pst` 与 `rolling_24h` 配额刷新窗口。
 * **自适应指数退避 (`lib/pool.js`)**：连续失败使冷却时间呈指数递增（基准 → ×2 → ×4 → 上限 ×8）。
 
@@ -125,7 +136,6 @@ graph LR
 * **交互式 Webhook (`lib/webhook.js`)**：向 **Telegram**、**Discord**、**Slack** 推送带交互按钮的富文本警报，可在移动聊天中一键重置冷却或暂停提供商。
 * **使用量与成本报表 (`lib/usage-report.js`)**：按日统计各密钥请求数与预估成本，支持一键导出 CSV/JSON (`GET /dsh-key-rotation/usage-report`)。
 * **延迟 SLO 监控 (`lib/histogram.js`)**：记录首字延迟（TTFT）与健康度评分 (`0..100`)。
-* **影子流量测试 (`lib/shadow.js`)**：支持配置百分比的流量镜像复制以评估次要提供商。
 
 ---
 
@@ -185,7 +195,10 @@ dsh-key-rotation:
     - UNKNOWN_MODEL
     - AUTH
   cooldownMs: 60000
-  canaryProbing: true
+  circuitBreakerEnabled: true
+  circuitBreakerThreshold: 5
+  circuitBreakerOpenMs: 30000
+  circuitBreakerHalfOpenProbes: 1
   concurrencyLimit: 5
   quotaResetWindow:
     type: midnight_utc
@@ -248,3 +261,13 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 - **设置架构与状态**: 在设置卡片中增加原生 `settingsScope` 绑定支持，保留 HTTP 桥接安全回退机制 (#235)。
 - **本地化与文案**: 侧边栏备用项 `settings.section` 标签支持本地化 `t('title')` 并配置 `locale: NS`，并在 `ctx.locale` 中注册 `zh` 中文字典 (#236)。
 - **死代码清理**: 移除 header-chip 迁移后残留的废弃 `mountDashboard` 函数 (#240)。
+
+
+### 熔断器参数（v0.8.0）
+
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `circuitBreakerEnabled` | boolean | `true` | 启用熔断 |
+| `circuitBreakerThreshold` | number | `5` | 连续失败阈值 |
+| `circuitBreakerOpenMs` | number | `30000` | 打开时长 ms |
+| `circuitBreakerHalfOpenProbes` | number | `1` | 半开探测次数 |

package/lib/atomic-io.js

@@ -0,0 +1,60 @@
+// lib/atomic-io.js — crash-safe file writes and safe JSON loads (#264).
+// Never overwrite a non-empty destination with empty/corrupt parse results.
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+/**
+ * Atomically write data to filePath (temp + rename in same directory).
+ * @param {string} filePath
+ * @param {string|Buffer} data
+ */
+export async function atomicWriteFile(filePath, data) {
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  const fh = await fs.open(tmp, 'w');
+  try {
+    await fh.writeFile(data);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await fs.rename(tmp, filePath);
+}
+
+/**
+ * Parse JSON safely. On failure returns fallback — never null-by-default wipe.
+ * @param {string|Buffer|null|undefined} text
+ * @param {any} fallback
+ */
+export function safeParseJson(text, fallback = null) {
+  if (text == null || text === '') return fallback;
+  try {
+    const v = JSON.parse(typeof text === 'string' ? text : String(text));
+    return v == null ? fallback : v;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Read JSON file; corrupt/missing → fallback (previous in-memory value).
+ * @param {string} filePath
+ * @param {any} fallback
+ */
+export async function safeReadJson(filePath, fallback = null) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return safeParseJson(raw, fallback);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Write JSON atomically. */
+export async function atomicWriteJson(filePath, value) {
+  await atomicWriteFile(filePath, JSON.stringify(value, null, 2));
+}

package/lib/bounded-map.js

@@ -0,0 +1,65 @@
+// lib/bounded-map.js — Map with max size + optional TTL (#262).
+
+export class BoundedMap {
+  /** @param {{ max?: number, ttlMs?: number|null }} opts */
+  constructor({ max = 1000, ttlMs = null } = {}) {
+    if (!Number.isFinite(max) || max < 1) throw new Error('BoundedMap: max must be >= 1');
+    this.max = max;
+    this.ttlMs = Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : null;
+    this._m = new Map(); // insertion order = LRU order when we re-insert on get/set
+  }
+
+  get size() { return this._m.size; }
+
+  _expired(entry, now) {
+    if (!this.ttlMs || !entry) return false;
+    return now - entry.at >= this.ttlMs;
+  }
+
+  get(key, now = Date.now()) {
+    const e = this._m.get(key);
+    if (!e) return undefined;
+    if (this._expired(e, now)) {
+      this._m.delete(key);
+      return undefined;
+    }
+    // refresh LRU
+    this._m.delete(key);
+    this._m.set(key, e);
+    return e.v;
+  }
+
+  set(key, value, now = Date.now()) {
+    if (this._m.has(key)) this._m.delete(key);
+    this._m.set(key, { v: value, at: now });
+    while (this._m.size > this.max) {
+      const oldest = this._m.keys().next().value;
+      this._m.delete(oldest);
+    }
+    return this;
+  }
+
+  has(key, now = Date.now()) {
+    return this.get(key, now) !== undefined;
+  }
+
+  delete(key) { return this._m.delete(key); }
+  clear() { this._m.clear(); }
+
+  *entries(now = Date.now()) {
+    for (const [k, e] of [...this._m.entries()]) {
+      if (this._expired(e, now)) { this._m.delete(k); continue; }
+      yield [k, e.v];
+    }
+  }
+
+  *keys(now = Date.now()) {
+    for (const [k] of this.entries(now)) yield k;
+  }
+
+  toObject(now = Date.now()) {
+    const out = {};
+    for (const [k, v] of this.entries(now)) out[k] = v;
+    return out;
+  }
+}

package/lib/circuit-breaker.js

@@ -0,0 +1,93 @@
+// lib/circuit-breaker.js — per-provider circuit breaker (#260).
+// closed --(threshold consecutive failures)--> open --(openMs)--> half-open
+// half-open: allow limited probes; success => closed, failure => open again.
+
+export const BREAKER_CLOSED = 'closed';
+export const BREAKER_OPEN = 'open';
+export const BREAKER_HALF_OPEN = 'half_open';
+
+export class CircuitBreaker {
+  /**
+   * @param {{ threshold?: number, openMs?: number, halfOpenProbes?: number, now?: () => number }} opts
+   */
+  constructor({ threshold = 5, openMs = 30_000, halfOpenProbes = 1, now = Date.now } = {}) {
+    this.threshold = Math.max(1, threshold | 0);
+    this.openMs = Math.max(100, openMs | 0);
+    this.halfOpenProbes = Math.max(1, halfOpenProbes | 0);
+    this._now = now;
+    /** @type {Map<string, {state:string, fails:number, openedAt:number, probes:number}>} */
+    this._st = new Map();
+  }
+
+  _entry(provider) {
+    let e = this._st.get(provider);
+    if (!e) {
+      e = { state: BREAKER_CLOSED, fails: 0, openedAt: 0, probes: 0 };
+      this._st.set(provider, e);
+    }
+    return e;
+  }
+
+  /** @returns {boolean} whether a request may be dispatched to this provider */
+  canRequest(provider) {
+    const e = this._entry(provider);
+    const now = this._now();
+    if (e.state === BREAKER_OPEN) {
+      if (now - e.openedAt >= this.openMs) {
+        e.state = BREAKER_HALF_OPEN;
+        e.probes = 0;
+        return true;
+      }
+      return false;
+    }
+    if (e.state === BREAKER_HALF_OPEN) {
+      if (e.probes < this.halfOpenProbes) {
+        e.probes += 1;
+        return true;
+      }
+      return false;
+    }
+    return true;
+  }
+
+  onSuccess(provider) {
+    const e = this._entry(provider);
+    e.fails = 0;
+    e.probes = 0;
+    e.state = BREAKER_CLOSED;
+  }
+
+  onFailure(provider) {
+    const e = this._entry(provider);
+    const now = this._now();
+    if (e.state === BREAKER_HALF_OPEN) {
+      e.state = BREAKER_OPEN;
+      e.openedAt = now;
+      e.fails = this.threshold;
+      return e.state;
+    }
+    e.fails += 1;
+    if (e.fails >= this.threshold) {
+      e.state = BREAKER_OPEN;
+      e.openedAt = now;
+    }
+    return e.state;
+  }
+
+  state(provider) {
+    return this._entry(provider).state;
+  }
+
+  snapshot() {
+    const out = {};
+    for (const [k, e] of this._st) {
+      out[k] = { state: e.state, fails: e.fails, openedAt: e.openedAt || null };
+    }
+    return out;
+  }
+
+  reset(provider) {
+    if (provider) this._st.delete(provider);
+    else this._st.clear();
+  }
+}

package/lib/clock.js

@@ -0,0 +1,24 @@
+// lib/clock.js — monotonic process clock for durations (#261).
+// performance.timeOrigin + performance.now() tracks process time and does not
+// jump when NTP adjusts the wall clock. Wall clock remains for display/cron.
+
+const hasPerformance = typeof performance !== 'undefined'
+  && typeof performance.now === 'function'
+  && Number.isFinite(performance.timeOrigin);
+
+/** Wall-clock epoch ms (Date.now). Use only for display / calendar buckets. */
+export function nowWall() {
+  return Date.now();
+}
+
+/**
+ * Monotonic-in-process epoch ms. Stable under NTP steps for the process lifetime.
+ * Falls back to Date.now() if performance is unavailable.
+ */
+export function nowMono() {
+  if (!hasPerformance) return Date.now();
+  return performance.timeOrigin + performance.now();
+}
+
+/** Default clock injectable into pure helpers. */
+export const defaultClock = { nowWall, nowMono };

package/lib/error-taxonomy.js

@@ -0,0 +1,66 @@
+// lib/error-taxonomy.js — complete failure classification (#267).
+// action: 'switch' | 'surface' | 'cooldown'
+
+const SWITCH_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const SURFACE_STATUS = new Set([400, 404, 422]);
+const AUTH_STATUS = new Set([401, 403]);
+
+const SWITCH_CODES = new Set([
+  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE',
+  'UNKNOWN_MODEL', 'AUTH', 'RESOURCE_EXHAUSTED', 'UNAVAILABLE', 'INTERNAL',
+  'DEADLINE_EXCEEDED', 'UNAUTHENTICATED', 'PERMISSION_DENIED', 'ABORTED',
+]);
+const SOCKET_SWITCH = new Set([
+  'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ENOTFOUND',
+  'ECONNABORTED', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET', 'UND_ERR_HEADERS_TIMEOUT',
+]);
+
+/**
+ * Classify a failure for rotation.
+ * @param {any} failureOrPayload
+ * @returns {{ action: 'switch'|'surface'|'cooldown', code: string, soft: boolean, reason: string }}
+ */
+export function classifyFailure(failureOrPayload) {
+  if (!failureOrPayload) {
+    return { action: 'surface', code: 'UNKNOWN', soft: false, reason: 'empty' };
+  }
+  const failure = failureOrPayload.failure ?? failureOrPayload;
+  const status = Number(failure.status ?? failure.statusCode ?? failure.httpStatus ?? 0);
+  const code = String(failure.code ?? failure.reason ?? failure.name ?? '').toUpperCase();
+  const message = String(failure.message ?? failureOrPayload.message ?? '');
+
+  if (AUTH_STATUS.has(status) || code === 'AUTH' || code === 'UNAUTHENTICATED' || code === 'PERMISSION_DENIED') {
+    return { action: 'switch', code: status ? String(status) : (code || 'AUTH'), soft: false, reason: 'auth' };
+  }
+  if (status === 429 || code === 'RATE_LIMIT' || code === 'RESOURCE_EXHAUSTED' || code === 'QUOTA') {
+    return { action: 'switch', code: status ? '429' : (code || 'RATE_LIMIT'), soft: false, reason: 'quota' };
+  }
+  if (SWITCH_STATUS.has(status)) {
+    const soft = status === 500 || status === 502 || status === 503 || status === 504;
+    return { action: 'switch', code: String(status), soft, reason: 'http' };
+  }
+  if (SURFACE_STATUS.has(status)) {
+    return { action: 'surface', code: String(status), soft: false, reason: 'client' };
+  }
+  if (code === 'TIMEOUT' || code === 'DEADLINE_EXCEEDED' || /timeout/i.test(message)) {
+    return { action: 'switch', code: 'TIMEOUT', soft: true, reason: 'timeout' };
+  }
+  if (SOCKET_SWITCH.has(code) || /ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket hang up|premature close/i.test(message)) {
+    return { action: 'switch', code: 'TRANSPORT', soft: true, reason: 'socket' };
+  }
+  if (code === 'UNAVAILABLE' || code === 'INTERNAL' || code === 'SERVER') {
+    return { action: 'switch', code: code || 'SERVER', soft: true, reason: 'grpc' };
+  }
+  if (code === 'TRANSPORT' || code === 'EMPTY_RESPONSE' || code === 'UNKNOWN_MODEL') {
+    return { action: 'switch', code, soft: code !== 'UNKNOWN_MODEL', reason: 'named' };
+  }
+  if (SWITCH_CODES.has(code)) {
+    return { action: 'switch', code, soft: false, reason: 'named' };
+  }
+  return { action: 'surface', code: code || 'UNKNOWN', soft: false, reason: 'unclassified' };
+}
+
+/** True when classification says switch to next key. */
+export function shouldSwitch(failureOrPayload) {
+  return classifyFailure(failureOrPayload).action === 'switch';
+}