baileys-antiban 3.9.0 → 4.7.0

package/README.md

@@ -8,9 +8,9 @@
 
 **Drop-in anti-ban middleware for Baileys WhatsApp bots. Free, self-hosted, TypeScript-first. Whapi.Cloud alternative — zero monthly fees.**
 
-> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
+> Rate limiting with Gaussian jitter, 7-day warmup, session health monitoring, LID resolver, disconnect classification, contact graph enforcement, device fingerprinting, group operation guards, recovery orchestration, cross-instance coordination — all in one `npm install`. Works with [Baileys](https://github.com/WhiskeySockets/Baileys) and [@oxidezap/baileyrs](https://github.com/oxidezap/baileyrs) (Rust/WASM).
 
-> **New in v3.3:** [LID Migration Guide](./docs/lid-migration.md) — survive Baileys v7's @lid default with stable thread keys.
+> **New in v4.7:** HumanEntropyService — background human-like activity (typing indicators, delayed read receipts, presence cycles) to prevent "too perfect bot" detection. Works with WaSP and any session manager, no socket access needed.
 
 ## Why Trust This Package
 
@@ -27,6 +27,167 @@ The npm WhatsApp ecosystem has a malware problem. In April 2026, [`lotusbail`](h
 
 If you can't read the code yourself, lean on these signals: signed releases, public audit trail, no telemetry, and a real product behind it. That's the floor. Everything below is the feature set.
 
+## v4.x New Features — Production-Grade Ban Prevention
+
+v4.0–v4.7 ship seven major anti-ban modules. All are **auto-wired** by default via `wrapSocket()` or `wrapSocketWithFingerprint()`.
+
+### v4.0 — GroupOperationGuard
+
+Rate-limits group operations to prevent `account_reachout_restricted` errors. WA limits: ~3 adds/10min, 2 creates/10min.
+
+```typescript
+import { wrapSocket } from 'baileys-antiban';
+
+const sock = wrapSocket(makeWASocket({ ... }), {
+  groupOpGuard: { limits: { add: { max: 3, windowMs: 600_000 } } },
+});
+```
+
+Classify errors: `classifyGroupOpError(err)` returns `GROUP_OP_ERRORS.REACHOUT_RESTRICTED` | `RATE_OVERLIMIT` | `PRIVACY_BLOCK` | etc.  
+Disable: `groupOpGuard: false`
+
+### v4.1 — LegitimacySignalInjector
+
+Injects realistic imperfections: typos + corrections (2.5% of messages), read gaps, mid-typing pauses. WhatsApp's ML flags accounts that are "too perfect".
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), {
+  legitimacySignals: { typoProbability: 0.03 },
+});
+```
+
+Disable: `legitimacySignals: false`
+
+### v4.2 — BanRecoveryOrchestrator
+
+Structured recovery after ban events. Auto-triggers via HealthMonitor at critical risk.
+
+```typescript
+import { BanRecoveryOrchestrator } from 'baileys-antiban';
+
+const recovery = new BanRecoveryOrchestrator({
+  onPhaseChange: (phase, plan) => console.log(`Phase: ${phase}`),
+  onHardBan: () => { /* replace SIM */ },
+});
+
+recovery.triggerRecovery('timelock');
+const status = recovery.getStatus();
+console.log(status.rateMultiplier); // 0.1 = 10% speed
+```
+
+**Recovery plans:** timelock: 24h pause, 10% resume, 15%/week ramp | rate_overlimit: 4h, 25%, 25%/week | soft_ban: 48h, 5%, 10%/week | hard_ban: dead  
+Access via: `antiban.recoveryOrchestrator`
+
+### v4.3 — wrapSocketWithFingerprint
+
+One-call setup with device fingerprint randomization (appVersion, osVersion, deviceModel).
+
+```typescript
+import { wrapSocketWithFingerprint } from 'baileys-antiban';
+
+const sock = wrapSocketWithFingerprint(makeWASocket, { auth }, { preset: 'moderate' });
+```
+
+**Preset changes:** All presets default `groupProfiles: true`; `aggressive`/`high-volume` now `autoPauseAt: 'high'`
+
+### v4.4 — Per-Contact Risk Delays + DeliveryTracker
+
+Strangers get 2.5× delay, known contacts 1.0×. Active when `contactGraph.enabled: true`.
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), { contactGraph: { enabled: true } });
+// stranger: 2.5×, handshake_sent: 1.8×, handshake_complete: 1.3×, known: 1.0×
+```
+
+**DeliveryTracker** tracks double-tick receipts. <60% delivery = soft-ban signal.
+
+```typescript
+import { DeliveryTracker } from 'baileys-antiban';
+
+const tracker = new DeliveryTracker({
+  lowRateThreshold: 0.6,
+  onLowDeliveryRate: (rate) => console.error(`Delivery: ${rate * 100}%`),
+});
+
+sock.ev.on('messages.upsert', ({ messages }) => {
+  messages.forEach(m => m.key.fromMe && tracker.onMessageSent(m.key.id));
+});
+sock.ev.on('messages.update', (updates) => {
+  updates.forEach(({ key, update }) => {
+    if (update.status >= 3) tracker.onDeliveryReceipt(key.id);
+  });
+});
+```
+
+### v4.5 — Adaptive Rate Limiting
+
+Auto-adjusts rate based on delivery success: ≥85% → 100% speed, <55% → 25% speed. Auto-wired.
+
+```typescript
+import { RateLimiter } from 'baileys-antiban';
+
+const limiter = new RateLimiter({ maxPerMinute: 10 });
+limiter.adaptLimits(0.5); // manual throttle to 50%
+const factor = limiter.getCurrentFactor();
+```
+
+### v4.6 — Cross-Instance Coordination
+
+Shared token bucket across processes. Solves: 5 bots × 8/min = 40/min → flag.
+
+```typescript
+const sock = wrapSocket(makeWASocket({ ... }), {
+  instanceCoordinator: '/tmp/wa-pool.json',
+  instancePoolMaxPerMinute: 20,
+});
+```
+
+All instances share 20/min IP-level budget. Atomic writes via rename-swap.
+
+### v4.7 — HumanEntropyService
+
+Background noise generator that makes a WA session indistinguishable from a real human user during idle periods. Runs independently of your message flow — no socket access required, works with WaSP or any session manager.
+
+**The problem it solves:** WhatsApp's ML flags accounts with "too perfect" patterns — instant read receipts, zero typing activity, always-on presence. A listen-only bot that never idles looks like a bot.
+
+**What it does every 2-6 hours (randomized):**
+- Sends typing indicator to a recent contact for 3-8 seconds, then stops (mimics "started typing, changed mind")
+- Marks a received message as read with 10-60 min delay (mimics "opened notification, read later")
+- Toggles own presence available → unavailable over 30-120s (mimics "checked phone, put it down")
+
+**Safety:** Only contacts people who already messaged you first. Never cold-contacts strangers. All errors caught silently.
+
+```typescript
+import { createHumanEntropyService } from 'baileys-antiban';
+
+// Works with WaSP (no direct socket access needed)
+const entropy = createHumanEntropyService(wasp, sessionId, {
+  enabled: true,
+  minIntervalMs: 2 * 60 * 60 * 1000, // 2 hours
+  maxIntervalMs: 6 * 60 * 60 * 1000, // 6 hours
+});
+
+entropy.start(); // runs in background
+entropy.stop();  // call on shutdown
+
+// Or with direct Baileys socket
+import { HumanEntropyService } from 'baileys-antiban';
+const svc = new HumanEntropyService(socket, { enabled: true });
+svc.start();
+```
+
+**Tracking recent contacts:** Feed incoming messages so the service knows who to interact with:
+
+```typescript
+sock.ev.on('messages.upsert', ({ messages }) => {
+  messages.forEach(m => entropy.addRecentContact(m.key.remoteJid, m.key));
+});
+```
+
+Stats: `entropy.getStats()` returns `{ typingActions, readActions, presenceActions, cycles }`.
+
+---
+
 ## v2.0 New Features — Session Stability Module
 
 ### What's New in v2.0

package/dist/antiban.d.ts

@@ -25,7 +25,10 @@ import { PostReconnectThrottle, type ReconnectThrottleConfig, type ReconnectThro
 import { LidResolver, type LidResolverConfig, type LidResolverStats } from './lidResolver.js';
 import { JidCanonicalizer, type JidCanonicalizerConfig, type JidCanonicalizerStats } from './jidCanonicalizer.js';
 import { SessionHealthMonitor, type SessionHealthStats } from './sessionStability.js';
+import { BanRecoveryOrchestrator, type RecoveryStatus } from './banRecoveryOrchestrator.js';
 import { type AntiBanInput, type ResolvedConfig } from './presets.js';
+import { type DeliveryTrackerStats } from './deliveryTracker.js';
+import { type InstanceCoordinatorStats } from './instanceCoordinator.js';
 export interface AntiBanConfigLegacy {
     rateLimiter?: Partial<RateLimiterConfig>;
     warmUp?: Partial<WarmUpConfig>;
@@ -70,6 +73,9 @@ export interface AntiBanStats {
     lidResolver?: LidResolverStats | null;
     jidCanonicalizer?: JidCanonicalizerStats | null;
     sessionStability?: SessionHealthStats | null;
+    banRecovery?: RecoveryStatus | null;
+    deliveryTracker: DeliveryTrackerStats;
+    instanceCoordinator?: InstanceCoordinatorStats | null;
 }
 export declare class AntiBan {
     private rateLimiter;
@@ -84,6 +90,9 @@ export declare class AntiBan {
     private lidResolverModule;
     private jidCanonicalizerModule;
     private sessionStabilityMonitor;
+    private banRecovery;
+    private deliveryTracker;
+    private instanceCoordinator;
     private stateManager;
     private resolvedConfig;
     private logging;
@@ -98,7 +107,7 @@ export declare class AntiBan {
      * Record a successfully sent message.
      * Call this AFTER every successful sendMessage().
      */
-    afterSend(recipient: string, content: string): void;
+    afterSend(recipient: string, content: string, msgId?: string): void;
     /**
      * Record a failed message send
      */
@@ -119,6 +128,11 @@ export declare class AntiBan {
         shouldReply: boolean;
         suggestedText?: string;
     };
+    /**
+     * Record a delivery receipt (status 3 = DELIVERY_ACK, status 4 = READ).
+     * Call from messages.update handler when delivery status is received.
+     */
+    onDeliveryReceipt(msgId: string): void;
     /**
      * Get the resolved configuration
      */
@@ -145,6 +159,8 @@ export declare class AntiBan {
     get jidCanonicalizer(): JidCanonicalizer | null;
     /** Get the session stability monitor for direct access */
     get sessionStability(): SessionHealthMonitor | null;
+    /** Get the ban recovery orchestrator for direct access */
+    get recoveryOrchestrator(): BanRecoveryOrchestrator;
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -161,6 +177,7 @@ export declare class AntiBan {
      * Reset everything (use after a ban period)
      */
     reset(): void;
+    private runAdaptiveCheck;
     private persistStateDebounced;
     private persistStateImmediate;
     /**

package/dist/antiban.js

@@ -25,9 +25,12 @@ import { PostReconnectThrottle } from './reconnectThrottle.js';
 import { LidResolver } from './lidResolver.js';
 import { JidCanonicalizer } from './jidCanonicalizer.js';
 import { SessionHealthMonitor } from './sessionStability.js';
+import { BanRecoveryOrchestrator } from './banRecoveryOrchestrator.js';
 import { resolveConfig } from './presets.js';
 import { StateManager } from './persist.js';
 import { shouldUseGroupProfile, applyGroupMultiplier } from './profiles.js';
+import { DeliveryTracker } from './deliveryTracker.js';
+import { InstanceCoordinator } from './instanceCoordinator.js';
 function isLegacyConfig(cfg) {
     if (typeof cfg !== 'object' || cfg === null)
         return false;
@@ -103,6 +106,9 @@ export class AntiBan {
     lidResolverModule = null;
     jidCanonicalizerModule = null;
     sessionStabilityMonitor = null;
+    banRecovery;
+    deliveryTracker;
+    instanceCoordinator = null;
     stateManager = null;
     resolvedConfig;
     logging;
@@ -173,14 +179,40 @@ export class AntiBan {
                 if ((status.risk === 'high' || status.risk === 'critical') && cfg.onAtRisk) {
                     cfg.onAtRisk(status);
                 }
+                // Trigger recovery orchestrator on critical risk
+                if (status.risk === 'critical') {
+                    this.banRecovery.recordBanEvent('soft_ban');
+                }
                 cfg.onRiskChange?.(status);
                 legacyPassthrough?.health?.onRiskChange?.(status);
             },
         });
+        // Initialize ban recovery orchestrator
+        this.banRecovery = new BanRecoveryOrchestrator({
+            onPhaseChange: (phase, plan) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🔄 Recovery phase: ${phase} — ${plan.description}`);
+                }
+            },
+            onHardBan: () => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 💀 HARD BAN detected — account likely dead, replace SIM`);
+                }
+            },
+        });
+        // Initialize delivery tracker
+        this.deliveryTracker = new DeliveryTracker({
+            onLowDeliveryRate: (rate) => {
+                if (this.logging) {
+                    console.log(`[baileys-antiban] ⚠️  Low delivery rate detected: ${Math.round(rate * 100)}% — possible soft ban`);
+                }
+            },
+        });
         this.timelockGuard = new TimelockGuard({
             ...(legacyPassthrough?.timelock || {}),
             onTimelockDetected: (state) => {
                 this.health.recordReachoutTimelock(state.enforcementType);
+                this.banRecovery.recordBanEvent('timelock');
                 if (this.logging) {
                     console.log(`[baileys-antiban] REACHOUT TIMELOCKED — ${state.enforcementType || 'unknown'}, expires ${state.expiresAt?.toISOString() || 'unknown'}`);
                 }
@@ -254,6 +286,17 @@ export class AntiBan {
             };
             this.sessionStabilityMonitor = new SessionHealthMonitor(healthConfig);
         }
+        // Initialize instance coordinator if configured
+        if (cfg.instanceCoordinator) {
+            this.instanceCoordinator = new InstanceCoordinator({
+                sharedFilePath: cfg.instanceCoordinator,
+                poolMaxPerMinute: cfg.instancePoolMaxPerMinute,
+                poolMaxPerHour: cfg.instancePoolMaxPerHour,
+            });
+            if (this.logging) {
+                console.log(`[baileys-antiban] 🌐 Instance coordination enabled: ${cfg.instanceCoordinator}`);
+            }
+        }
     }
     /**
      * Check if a message can be sent and get required delay.
@@ -274,6 +317,17 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Recovery orchestrator rate multiplier
+        const recoveryStatus = this.banRecovery.getStatus();
+        if (recoveryStatus.phase === 'paused') {
+            this.stats.messagesBlocked++;
+            return {
+                allowed: false,
+                delayMs: recoveryStatus.pauseRemainingMs || 0,
+                reason: `Ban recovery: ${recoveryStatus.recommendation}`,
+                health: healthStatus,
+            };
+        }
         // Timelock guard (allows existing chats, blocks new contacts)
         const timelockDecision = this.timelockGuard.canSend(recipient);
         if (!timelockDecision.allowed) {
@@ -345,6 +399,22 @@ export class AntiBan {
                 health: healthStatus,
             };
         }
+        // Cross-instance coordination — check shared IP-level pool
+        if (this.instanceCoordinator) {
+            const slot = this.instanceCoordinator.tryAcquireSlot();
+            if (!slot.allowed) {
+                this.stats.messagesBlocked++;
+                if (this.logging) {
+                    console.log(`[baileys-antiban] 🌐 BLOCKED — instance pool exhausted (shared IP limit), retry in ${slot.retryAfterMs}ms`);
+                }
+                return {
+                    allowed: false,
+                    delayMs: slot.retryAfterMs || 5000,
+                    reason: 'Cross-instance rate pool exhausted',
+                    health: healthStatus,
+                };
+            }
+        }
         // Group profile rate check (runs before rateLimiter.getDelay for timing)
         if (this.resolvedConfig.groupProfiles && shouldUseGroupProfile(recipient)) {
             const groupLimits = applyGroupMultiplier({
@@ -384,6 +454,24 @@ export class AntiBan {
             const multiplier = Math.min(5, 1 / activityFactor);
             delay = Math.floor(delay * multiplier);
         }
+        // Per-contact risk multiplier — cold contacts need longer delays
+        // Only apply when contact graph is enabled, otherwise all contacts appear as 'stranger'
+        if (this.contactGraphWarmer['config']?.enabled) {
+            const contactState = this.contactGraphWarmer.getContactState(recipient);
+            const coldMultiplier = {
+                stranger: 2.5,
+                handshake_sent: 1.8,
+                handshake_complete: 1.3,
+                known: 1.0,
+            };
+            const contactRiskMult = coldMultiplier[contactState] ?? 1.0;
+            if (contactRiskMult > 1.0) {
+                delay = Math.floor(delay * contactRiskMult);
+                if (this.logging && contactRiskMult >= 2.0) {
+                    console.log(`[baileys-antiban] ⚠️  Cold contact ${recipient} — ${contactState}, delay ×${contactRiskMult}`);
+                }
+            }
+        }
         // Roll for distraction pause
         const distractionCheck = this.presenceChoreographer.shouldPauseForDistraction();
         if (distractionCheck.pause) {
@@ -411,11 +499,15 @@ export class AntiBan {
      * Record a successfully sent message.
      * Call this AFTER every successful sendMessage().
      */
-    afterSend(recipient, content) {
+    afterSend(recipient, content, msgId) {
         this.rateLimiter.record(recipient, content);
         this.warmUp.record();
         this.replyRatioGuard.recordSent(recipient);
         this.stats.messagesAllowed++;
+        if (msgId) {
+            this.deliveryTracker.onMessageSent(msgId);
+        }
+        this.runAdaptiveCheck();
         this.persistStateDebounced();
     }
     /**
@@ -441,6 +533,7 @@ export class AntiBan {
     onReconnect() {
         this.health.recordReconnect();
         this.reconnectThrottleModule.onReconnect();
+        this.rateLimiter.adaptLimits(1.0);
     }
     /**
      * Handle incoming message — record in reply ratio + contact graph.
@@ -451,6 +544,13 @@ export class AntiBan {
         this.contactGraphWarmer.onIncomingMessage(jid);
         return this.replyRatioGuard.suggestReply(jid, msgText);
     }
+    /**
+     * Record a delivery receipt (status 3 = DELIVERY_ACK, status 4 = READ).
+     * Call from messages.update handler when delivery status is received.
+     */
+    onDeliveryReceipt(msgId) {
+        this.deliveryTracker.onDeliveryReceipt(msgId);
+    }
     /**
      * Get the resolved configuration
      */
@@ -466,6 +566,8 @@ export class AntiBan {
             health: this.health.getStatus(),
             warmUp: this.warmUp.getStatus(),
             rateLimiter: this.rateLimiter.getStats(),
+            banRecovery: this.banRecovery.getStatus(),
+            deliveryTracker: this.deliveryTracker.getStats(),
         };
         // Only include new stats if enabled
         if (this.replyRatioGuard['config']?.enabled) {
@@ -492,6 +594,9 @@ export class AntiBan {
         if (this.sessionStabilityMonitor) {
             stats.sessionStability = this.sessionStabilityMonitor.getStats();
         }
+        if (this.instanceCoordinator) {
+            stats.instanceCoordinator = this.instanceCoordinator.getStats();
+        }
         return stats;
     }
     /** Get the timelock guard for direct access */
@@ -530,6 +635,10 @@ export class AntiBan {
     get sessionStability() {
         return this.sessionStabilityMonitor;
     }
+    /** Get the ban recovery orchestrator for direct access */
+    get recoveryOrchestrator() {
+        return this.banRecovery;
+    }
     /**
      * Export warm-up state for persistence between restarts
      */
@@ -571,6 +680,35 @@ export class AntiBan {
             console.log('[baileys-antiban] 🔄 Reset — starting fresh warm-up');
         }
     }
+    runAdaptiveCheck() {
+        const delivery = this.deliveryTracker.getStats();
+        // Need min sample to be meaningful
+        if (delivery.deliveryRate === null)
+            return;
+        const rate = delivery.deliveryRate;
+        let targetFactor;
+        if (rate >= 0.85) {
+            targetFactor = 1.0; // Excellent — full speed
+        }
+        else if (rate >= 0.70) {
+            targetFactor = 0.75; // Good — slight reduction
+        }
+        else if (rate >= 0.55) {
+            targetFactor = 0.50; // Poor — halve throughput
+        }
+        else {
+            targetFactor = 0.25; // Bad — severe throttle (soft ban likely)
+        }
+        const current = this.rateLimiter.getCurrentFactor();
+        // Only log + adjust when factor changes meaningfully (>5% delta)
+        if (Math.abs(targetFactor - current) > 0.05) {
+            if (this.logging) {
+                const dir = targetFactor > current ? '📈' : '📉';
+                console.log(`[baileys-antiban] ${dir} Adaptive rate: delivery=${(rate * 100).toFixed(0)}% → factor ${current.toFixed(2)}→${targetFactor.toFixed(2)}`);
+            }
+            this.rateLimiter.adaptLimits(targetFactor);
+        }
+    }
     persistStateDebounced() {
         if (!this.stateManager)
             return;

package/dist/banRecoveryOrchestrator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * BanRecoveryOrchestrator — Structured recovery after ban/restriction events
+ *
+ * When WhatsApp restricts your account, the worst thing to do is immediately
+ * resume normal activity. This module provides a evidence-based recovery protocol:
+ *
+ * - Timelocked (reachout_restricted): 24h pause, resume at 10% rate, ramp 15%/week
+ * - Rate-overlimit (429): 4h pause, resume at 25% rate, ramp 25%/week
+ * - Soft-ban (repeated disconnects): 48h pause, resume at 5% rate, ramp 10%/week
+ * - Hard-ban (loggedOut): account is dead, signal for replacement
+ *
+ * Based on observed recovery times from community reports. Not guaranteed —
+ * WA's enforcement is non-deterministic. Treat as best-effort guidance.
+ */
+export type BanEventType = 'timelock' | 'rate_overlimit' | 'soft_ban' | 'hard_ban';
+export type RecoveryPhase = 'paused' | 'recovering' | 'ramping' | 'graduated' | 'dead';
+export interface RecoveryPlan {
+    eventType: BanEventType;
+    pauseDurationMs: number;
+    resumeRateMultiplier: number;
+    weeklyRampPercent: number;
+    estimatedRecoveryDays: number;
+    description: string;
+}
+export interface BanRecoveryConfig {
+    /** Custom recovery plans per event type (overrides defaults) */
+    plans?: Partial<Record<BanEventType, Partial<RecoveryPlan>>>;
+    /** Called when recovery phase changes */
+    onPhaseChange?: (phase: RecoveryPhase, plan: RecoveryPlan) => void;
+    /** Called when account appears dead (hard ban) — signal to replace SIM */
+    onHardBan?: () => void;
+    /** Max weeks before giving up on recovery and declaring dead (default: 8) */
+    maxRecoveryWeeks?: number;
+}
+export interface RecoveryState {
+    active: boolean;
+    eventType?: BanEventType;
+    phase: RecoveryPhase;
+    banDetectedAt?: number;
+    pauseUntil?: number;
+    currentRateMultiplier: number;
+    weeksSinceResume: number;
+    banCount30d: number;
+    lastBanAt?: number;
+}
+export interface RecoveryStatus {
+    phase: RecoveryPhase;
+    rateMultiplier: number;
+    pauseRemainingMs?: number;
+    estimatedFullRecoveryDate?: number;
+    recommendation: string;
+    shouldReplaceNumber: boolean;
+}
+export declare class BanRecoveryOrchestrator {
+    private config;
+    private state;
+    private plans;
+    constructor(config?: BanRecoveryConfig);
+    /**
+     * Record a ban event and start recovery protocol
+     */
+    recordBanEvent(eventType: BanEventType): RecoveryStatus;
+    /**
+     * Get current recovery status (call before sending to check rate)
+     */
+    getStatus(): RecoveryStatus;
+    /**
+     * Current rate multiplier — multiply your normal limits by this
+     */
+    getRateMultiplier(): number;
+    /**
+     * Should be called daily/weekly to advance the ramp
+     */
+    tick(): void;
+    /**
+     * Classify a raw error into a BanEventType
+     */
+    static classifyError(err: unknown): BanEventType | null;
+    /**
+     * Serializable state for persistence
+     */
+    getState(): RecoveryState;
+    /**
+     * Restore from persisted state
+     */
+    static fromState(state: RecoveryState, config?: BanRecoveryConfig): BanRecoveryOrchestrator;
+}