wyrm-mcp 7.3.2 → 7.3.3

package/dist/resilience.js

@@ -1 +1,591 @@
-import{existsSync as l,readFileSync as p,writeFileSync as g,mkdirSync as S,unlinkSync as m,renameSync as b,readdirSync as O}from"fs";import{join as u}from"path";import{homedir as v}from"os";import{WyrmLogger as D}from"./logger.js";import{isSqliteBusyError as y,WYRM_CIRCUIT_OPEN_CODE as C}from"./sqlite-busy.js";const E={maxAttempts:5,baseDelayMs:100,maxDelayMs:1e4,backoffMultiplier:2,retryableErrors:["SQLITE_LOCKED","ECONNRESET","ETIMEDOUT","ENOTFOUND","EAI_AGAIN","EPIPE","ECONNREFUSED"]},M={failureThreshold:5,successThreshold:3,timeout:3e4};class T{logger;checkpointDir;retryConfig;circuitConfig;circuitState="closed";failureCount=0;successCount=0;lastFailureTime=0;activeOperations=new Map;constructor(e,r,t){this.logger=e||new D,this.retryConfig={...E,...r},this.circuitConfig={...M,...t},this.checkpointDir=u(v(),".wyrm","checkpoints"),l(this.checkpointDir)||S(this.checkpointDir,{recursive:!0}),this.recoverIncompleteOperations()}async withRetry(e,r,t){const i={...this.retryConfig,...t};let c,s=0;for(;s<i.maxAttempts;){s++;try{if(!this.checkCircuit())return{success:!1,error:Object.assign(new Error("Circuit breaker is open - service unavailable"),{code:C}),attempts:s,recoverable:!0};const o=await e();return this.recordSuccess(),{success:!0,data:o,attempts:s,recoverable:!1}}catch(o){if(c=o,y(o))return{success:!1,error:c,attempts:s,recoverable:!0};this.recordFailure();const n=o.code||"",f=o.message||"";if(!i.retryableErrors?.some(a=>n.includes(a)||f.includes(a))&&s===1)return this.logger.error(`${r} failed with non-retryable error`,{error:f,code:n}),{success:!1,error:c,attempts:s,recoverable:!1};if(s<i.maxAttempts){const a=Math.min(i.baseDelayMs*Math.pow(i.backoffMultiplier,s-1),i.maxDelayMs);this.logger.warn(`${r} failed, retrying in ${a}ms`,{attempt:s,maxAttempts:i.maxAttempts,error:f}),await this.sleep(a)}}}return this.logger.error(`${r} failed after ${s} attempts`,{error:c?.message}),{success:!1,error:c,attempts:s,recoverable:!0}}withRetrySync(e,r,t){const i={...this.retryConfig,...t};let c,s=0;for(;s<i.maxAttempts;){s++;try{if(!this.checkCircuit())return{success:!1,error:Object.assign(new Error("Circuit breaker is open"),{code:C}),attempts:s,recoverable:!0};const o=e();return this.recordSuccess(),{success:!0,data:o,attempts:s,recoverable:!1}}catch(o){if(c=o,y(o))return{success:!1,error:c,attempts:s,recoverable:!0};this.recordFailure();const n=o.code||"",f=o.message||"";if(!i.retryableErrors?.some(a=>n.includes(a)||f.includes(a))&&s===1)return{success:!1,error:c,attempts:s,recoverable:!1};if(s<i.maxAttempts){const a=Math.min(i.baseDelayMs*Math.pow(i.backoffMultiplier,s-1),i.maxDelayMs);this.logger.warn(`${r} sync retry ${s}/${i.maxAttempts}`),this.sleepSync(a)}}}return{success:!1,error:c,attempts:s,recoverable:!0}}checkCircuit(){switch(this.circuitState){case"closed":return!0;case"open":return Date.now()-this.lastFailureTime>=this.circuitConfig.timeout?(this.circuitState="half-open",this.logger.info("Circuit breaker transitioning to half-open"),!0):!1;case"half-open":return!0}}recordSuccess(){this.circuitState==="half-open"?(this.successCount++,this.successCount>=this.circuitConfig.successThreshold&&(this.circuitState="closed",this.failureCount=0,this.successCount=0,this.logger.info("Circuit breaker closed - service recovered"))):this.failureCount=0}recordFailure(){this.failureCount++,this.lastFailureTime=Date.now(),this.circuitState==="half-open"?(this.circuitState="open",this.successCount=0,this.logger.warn("Circuit breaker reopened after half-open failure")):this.failureCount>=this.circuitConfig.failureThreshold&&(this.circuitState="open",this.logger.warn("Circuit breaker opened due to failure threshold",{failures:this.failureCount,threshold:this.circuitConfig.failureThreshold}))}getCircuitStatus(){return{state:this.circuitState,failures:this.failureCount,lastFailure:this.lastFailureTime}}resetCircuit(){this.circuitState="closed",this.failureCount=0,this.successCount=0,this.logger.info("Circuit breaker manually reset")}createCheckpoint(e,r,t,i){const c={id:e,operation:r,stage:t,data:i,timestamp:new Date().toISOString(),completed:!1},s=u(this.checkpointDir,`${e}.json`);g(s,JSON.stringify(c,null,2)),this.activeOperations.set(e,c),this.logger.debug(`Checkpoint created: ${r}/${t}`,{operationId:e})}updateCheckpoint(e,r,t){const i=this.activeOperations.get(e);if(!i){this.logger.warn("Checkpoint not found for update",{operationId:e});return}const c={...i,stage:r,data:t?{...i.data,...t}:i.data,timestamp:new Date().toISOString()},s=u(this.checkpointDir,`${e}.json`);g(s,JSON.stringify(c,null,2)),this.activeOperations.set(e,c)}completeCheckpoint(e){const r=u(this.checkpointDir,`${e}.json`);if(l(r)){const t=this.activeOperations.get(e);t&&(t.completed=!0,g(r,JSON.stringify(t,null,2)));try{m(r)}catch{}}this.activeOperations.delete(e),this.logger.debug("Checkpoint completed",{operationId:e})}getCheckpoint(e){const r=this.activeOperations.get(e);if(r)return r;const t=u(this.checkpointDir,`${e}.json`);if(l(t))try{return JSON.parse(p(t,"utf-8"))}catch{return null}return null}recoverIncompleteOperations(){try{const e=O(this.checkpointDir),r=[];for(const t of e){if(!t.endsWith(".json"))continue;const i=u(this.checkpointDir,t);try{const c=JSON.parse(p(i,"utf-8"));c.completed?m(i):(r.push(c),this.activeOperations.set(c.id,c))}catch{try{m(i)}catch{}}}r.length>0&&this.logger.warn("Found incomplete operations from previous run",{count:r.length,operations:r.map(t=>t.operation)})}catch{}}getIncompleteOperations(){return Array.from(this.activeOperations.values()).filter(e=>!e.completed)}executeTransaction(e,r){const t=`txn-${Date.now()}-${Math.random().toString(36).slice(2,8)}`;this.createCheckpoint(t,"transaction","begin",{});try{e.prepare("BEGIN IMMEDIATE").run(),this.updateCheckpoint(t,"executing");const i=r();return e.prepare("COMMIT").run(),this.completeCheckpoint(t),{success:!0,data:i,attempts:1,recoverable:!1}}catch(i){this.logger.error("Transaction failed, rolling back",{operationId:t,error:i.message});try{e.prepare("ROLLBACK").run()}catch(c){this.logger.error("Rollback failed",{error:c.message})}return this.updateCheckpoint(t,"rolled_back",{error:i.message}),{success:!1,error:i,attempts:1,recoverable:!0}}}atomicWriteFile(e,r){const t=`${e}.tmp.${Date.now()}`;try{return g(t,r,{encoding:"utf-8",flag:"w"}),b(t,e),!0}catch(i){this.logger.error("Atomic write failed",{filePath:e,error:i.message});try{l(t)&&m(t)}catch{}return!1}}safeReadFile(e,r){try{if(l(e))return p(e,"utf-8")}catch{this.logger.warn("Failed to read primary file",{filePath:e})}if(r)try{if(l(r))return this.logger.info("Using backup file",{backupPath:r}),p(r,"utf-8")}catch{this.logger.error("Failed to read backup file",{backupPath:r})}return null}sleep(e){return new Promise(r=>{setTimeout(r,e)})}sleepSync(e){e<=0||Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,e)}generateOperationId(e="op"){return`${e}-${Date.now()}-${Math.random().toString(36).slice(2,8)}`}}let d=null;function k(){return d||(d=new T),d}function I(h){return function(e,r,t){const i=t.value;return t.value=async function(...c){const o=await k().withRetry(()=>i.apply(this,c),r,h);if(!o.success)throw o.error;return o.data},t}}function _(h){return function(e,r,t){const i=t.value;return t.value=async function(...c){const s=k(),o=s.generateOperationId(h);s.createCheckpoint(o,h,"started",{args:c});try{const n=await i.apply(this,c);return s.completeCheckpoint(o),n}catch(n){throw s.updateCheckpoint(o,"failed",{error:n.message}),n}},t}}export{T as ResilienceManager,k as getResilienceManager,_ as withCheckpoint,I as withRetry};
+/**
+ * Wyrm Resilience Module - Professional-grade fault tolerance
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ * @module resilience
+ * @version 3.0.0
+ *
+ * Features:
+ * - Transaction safety with automatic rollback
+ * - Exponential backoff retry logic
+ * - Circuit breaker pattern
+ * - Operation checkpointing
+ * - Crash recovery via WAL
+ * - Graceful degradation
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, renameSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { WyrmLogger } from './logger.js';
+import { isSqliteBusyError, WYRM_CIRCUIT_OPEN_CODE } from './sqlite-busy.js';
+// ==================== DEFAULT CONFIGS ====================
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 5,
+    baseDelayMs: 100,
+    maxDelayMs: 10000,
+    backoffMultiplier: 2,
+    // v7 F2 review fix: SQLITE_BUSY is deliberately NOT in this list. By the
+    // time better-sqlite3 surfaces it, SQLite has ALREADY retried internally for
+    // the full busy_timeout window (5000ms — database.ts); re-retrying here
+    // multiplied one contended write into a ~26.5s synchronous stall (5×5000ms
+    // busy_timeout + backoff sleeps) and the per-attempt failure count tripped
+    // the shared circuit breaker, hiding the structured WYRM_BUSY classification
+    // behind a code-less circuit-open error for 30s. One busy_timeout window IS
+    // the retry; BUSY now propagates immediately with its code intact (see the
+    // isSqliteBusyError early-outs in withRetry/withRetrySync).
+    retryableErrors: [
+        'SQLITE_LOCKED',
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'ENOTFOUND',
+        'EAI_AGAIN',
+        'EPIPE',
+        'ECONNREFUSED',
+    ],
+};
+const DEFAULT_CIRCUIT_CONFIG = {
+    failureThreshold: 5,
+    successThreshold: 3,
+    timeout: 30000,
+};
+// ==================== RESILIENCE MANAGER ====================
+export class ResilienceManager {
+    logger;
+    checkpointDir;
+    retryConfig;
+    circuitConfig;
+    // Circuit breaker state
+    circuitState = 'closed';
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime = 0;
+    // Active operations for tracking
+    activeOperations = new Map();
+    constructor(logger, retryConfig, circuitConfig) {
+        this.logger = logger || new WyrmLogger();
+        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...retryConfig };
+        this.circuitConfig = { ...DEFAULT_CIRCUIT_CONFIG, ...circuitConfig };
+        // Initialize checkpoint directory
+        this.checkpointDir = join(homedir(), '.wyrm', 'checkpoints');
+        if (!existsSync(this.checkpointDir)) {
+            mkdirSync(this.checkpointDir, { recursive: true });
+        }
+        // Recover any incomplete operations on startup
+        this.recoverIncompleteOperations();
+    }
+    // ==================== RETRY WITH BACKOFF ====================
+    /**
+     * Execute an operation with exponential backoff retry
+     */
+    async withRetry(operation, operationName, config) {
+        const cfg = { ...this.retryConfig, ...config };
+        let lastError;
+        let attempts = 0;
+        while (attempts < cfg.maxAttempts) {
+            attempts++;
+            try {
+                // Check circuit breaker. The error carries WYRM_CIRCUIT_OPEN (v7 F2
+                // review fix) so the MCP dispatcher can map it to the structured
+                // retryable body instead of an opaque plain Error.
+                if (!this.checkCircuit()) {
+                    return {
+                        success: false,
+                        error: Object.assign(new Error('Circuit breaker is open - service unavailable'), { code: WYRM_CIRCUIT_OPEN_CODE }),
+                        attempts,
+                        recoverable: true,
+                    };
+                }
+                const result = await operation();
+                this.recordSuccess();
+                return {
+                    success: true,
+                    data: result,
+                    attempts,
+                    recoverable: false,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                // v7 F2 review fix: SQLITE_BUSY already burned its full busy_timeout
+                // retry window inside SQLite — propagate immediately with the code
+                // intact (the dispatcher owns the structured WYRM_BUSY body) and do
+                // NOT count it toward the circuit breaker (cross-process contention is
+                // not a service failure).
+                if (isSqliteBusyError(error)) {
+                    return { success: false, error: lastError, attempts, recoverable: true };
+                }
+                this.recordFailure();
+                const errorCode = error.code || '';
+                const errorMessage = error.message || '';
+                // Check if error is retryable
+                const isRetryable = cfg.retryableErrors?.some(code => errorCode.includes(code) || errorMessage.includes(code));
+                if (!isRetryable && attempts === 1) {
+                    // Non-retryable error on first attempt
+                    this.logger.error(`${operationName} failed with non-retryable error`, {
+                        error: errorMessage,
+                        code: errorCode,
+                    });
+                    return {
+                        success: false,
+                        error: lastError,
+                        attempts,
+                        recoverable: false,
+                    };
+                }
+                if (attempts < cfg.maxAttempts) {
+                    const delay = Math.min(cfg.baseDelayMs * Math.pow(cfg.backoffMultiplier, attempts - 1), cfg.maxDelayMs);
+                    this.logger.warn(`${operationName} failed, retrying in ${delay}ms`, {
+                        attempt: attempts,
+                        maxAttempts: cfg.maxAttempts,
+                        error: errorMessage,
+                    });
+                    await this.sleep(delay);
+                }
+            }
+        }
+        this.logger.error(`${operationName} failed after ${attempts} attempts`, {
+            error: lastError?.message,
+        });
+        return {
+            success: false,
+            error: lastError,
+            attempts,
+            recoverable: true,
+        };
+    }
+    /**
+     * Synchronous retry for database operations
+     */
+    withRetrySync(operation, operationName, config) {
+        const cfg = { ...this.retryConfig, ...config };
+        let lastError;
+        let attempts = 0;
+        while (attempts < cfg.maxAttempts) {
+            attempts++;
+            try {
+                // WYRM_CIRCUIT_OPEN code: see withRetry above (v7 F2 review fix).
+                if (!this.checkCircuit()) {
+                    return {
+                        success: false,
+                        error: Object.assign(new Error('Circuit breaker is open'), { code: WYRM_CIRCUIT_OPEN_CODE }),
+                        attempts,
+                        recoverable: true,
+                    };
+                }
+                const result = operation();
+                this.recordSuccess();
+                return {
+                    success: true,
+                    data: result,
+                    attempts,
+                    recoverable: false,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                // SQLITE_BUSY: already retried inside SQLite for the busy_timeout
+                // window — propagate with code intact, never feed the breaker
+                // (v7 F2 review fix; see withRetry above).
+                if (isSqliteBusyError(error)) {
+                    return { success: false, error: lastError, attempts, recoverable: true };
+                }
+                this.recordFailure();
+                const errorCode = error.code || '';
+                const errorMessage = error.message || '';
+                const isRetryable = cfg.retryableErrors?.some(code => errorCode.includes(code) || errorMessage.includes(code));
+                if (!isRetryable && attempts === 1) {
+                    return {
+                        success: false,
+                        error: lastError,
+                        attempts,
+                        recoverable: false,
+                    };
+                }
+                if (attempts < cfg.maxAttempts) {
+                    const delay = Math.min(cfg.baseDelayMs * Math.pow(cfg.backoffMultiplier, attempts - 1), cfg.maxDelayMs);
+                    this.logger.warn(`${operationName} sync retry ${attempts}/${cfg.maxAttempts}`);
+                    this.sleepSync(delay);
+                }
+            }
+        }
+        return {
+            success: false,
+            error: lastError,
+            attempts,
+            recoverable: true,
+        };
+    }
+    // ==================== CIRCUIT BREAKER ====================
+    /**
+     * Check if circuit allows operations
+     */
+    checkCircuit() {
+        switch (this.circuitState) {
+            case 'closed':
+                return true;
+            case 'open':
+                // Check if timeout has passed
+                if (Date.now() - this.lastFailureTime >= this.circuitConfig.timeout) {
+                    this.circuitState = 'half-open';
+                    this.logger.info('Circuit breaker transitioning to half-open');
+                    return true;
+                }
+                return false;
+            case 'half-open':
+                return true;
+        }
+    }
+    /**
+     * Record a successful operation
+     */
+    recordSuccess() {
+        if (this.circuitState === 'half-open') {
+            this.successCount++;
+            if (this.successCount >= this.circuitConfig.successThreshold) {
+                this.circuitState = 'closed';
+                this.failureCount = 0;
+                this.successCount = 0;
+                this.logger.info('Circuit breaker closed - service recovered');
+            }
+        }
+        else {
+            this.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed operation
+     */
+    recordFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.circuitState === 'half-open') {
+            this.circuitState = 'open';
+            this.successCount = 0;
+            this.logger.warn('Circuit breaker reopened after half-open failure');
+        }
+        else if (this.failureCount >= this.circuitConfig.failureThreshold) {
+            this.circuitState = 'open';
+            this.logger.warn('Circuit breaker opened due to failure threshold', {
+                failures: this.failureCount,
+                threshold: this.circuitConfig.failureThreshold,
+            });
+        }
+    }
+    /**
+     * Get circuit breaker status
+     */
+    getCircuitStatus() {
+        return {
+            state: this.circuitState,
+            failures: this.failureCount,
+            lastFailure: this.lastFailureTime,
+        };
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    resetCircuit() {
+        this.circuitState = 'closed';
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.logger.info('Circuit breaker manually reset');
+    }
+    // ==================== CHECKPOINTING ====================
+    /**
+     * Create a checkpoint for an operation
+     */
+    createCheckpoint(operationId, operation, stage, data) {
+        const checkpoint = {
+            id: operationId,
+            operation,
+            stage,
+            data,
+            timestamp: new Date().toISOString(),
+            completed: false,
+        };
+        const filePath = join(this.checkpointDir, `${operationId}.json`);
+        writeFileSync(filePath, JSON.stringify(checkpoint, null, 2));
+        this.activeOperations.set(operationId, checkpoint);
+        this.logger.debug(`Checkpoint created: ${operation}/${stage}`, { operationId });
+    }
+    /**
+     * Update checkpoint stage
+     */
+    updateCheckpoint(operationId, stage, data) {
+        const existing = this.activeOperations.get(operationId);
+        if (!existing) {
+            this.logger.warn('Checkpoint not found for update', { operationId });
+            return;
+        }
+        const updated = {
+            ...existing,
+            stage,
+            data: data ? { ...existing.data, ...data } : existing.data,
+            timestamp: new Date().toISOString(),
+        };
+        const filePath = join(this.checkpointDir, `${operationId}.json`);
+        writeFileSync(filePath, JSON.stringify(updated, null, 2));
+        this.activeOperations.set(operationId, updated);
+    }
+    /**
+     * Complete a checkpoint (mark as done and remove)
+     */
+    completeCheckpoint(operationId) {
+        const filePath = join(this.checkpointDir, `${operationId}.json`);
+        if (existsSync(filePath)) {
+            // Mark as completed before deletion
+            const checkpoint = this.activeOperations.get(operationId);
+            if (checkpoint) {
+                checkpoint.completed = true;
+                writeFileSync(filePath, JSON.stringify(checkpoint, null, 2));
+            }
+            // Move to completed folder or delete
+            try {
+                unlinkSync(filePath);
+            }
+            catch {
+                // Ignore deletion errors
+            }
+        }
+        this.activeOperations.delete(operationId);
+        this.logger.debug('Checkpoint completed', { operationId });
+    }
+    /**
+     * Get a checkpoint by ID
+     */
+    getCheckpoint(operationId) {
+        const cached = this.activeOperations.get(operationId);
+        if (cached)
+            return cached;
+        const filePath = join(this.checkpointDir, `${operationId}.json`);
+        if (existsSync(filePath)) {
+            try {
+                const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+                return data;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Recover incomplete operations on startup
+     */
+    recoverIncompleteOperations() {
+        try {
+            const files = readdirSync(this.checkpointDir);
+            const checkpoints = [];
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                const filePath = join(this.checkpointDir, file);
+                try {
+                    const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+                    if (!data.completed) {
+                        checkpoints.push(data);
+                        this.activeOperations.set(data.id, data);
+                    }
+                    else {
+                        // Clean up completed checkpoints
+                        unlinkSync(filePath);
+                    }
+                }
+                catch {
+                    // Corrupted checkpoint file, remove it
+                    try {
+                        unlinkSync(filePath);
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+            }
+            if (checkpoints.length > 0) {
+                this.logger.warn('Found incomplete operations from previous run', {
+                    count: checkpoints.length,
+                    operations: checkpoints.map(c => c.operation),
+                });
+            }
+        }
+        catch {
+            // Checkpoint directory doesn't exist or not readable
+        }
+    }
+    /**
+     * Get all incomplete operations for recovery
+     */
+    getIncompleteOperations() {
+        return Array.from(this.activeOperations.values()).filter(c => !c.completed);
+    }
+    // ==================== TRANSACTION WRAPPER ====================
+    /**
+     * Execute a database transaction with automatic rollback on failure
+     */
+    executeTransaction(db, operations) {
+        const operationId = `txn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.createCheckpoint(operationId, 'transaction', 'begin', {});
+        try {
+            db.prepare('BEGIN IMMEDIATE').run();
+            this.updateCheckpoint(operationId, 'executing');
+            const result = operations();
+            db.prepare('COMMIT').run();
+            this.completeCheckpoint(operationId);
+            return {
+                success: true,
+                data: result,
+                attempts: 1,
+                recoverable: false,
+            };
+        }
+        catch (error) {
+            this.logger.error('Transaction failed, rolling back', {
+                operationId,
+                error: error.message,
+            });
+            try {
+                db.prepare('ROLLBACK').run();
+            }
+            catch (rollbackError) {
+                this.logger.error('Rollback failed', {
+                    error: rollbackError.message,
+                });
+            }
+            this.updateCheckpoint(operationId, 'rolled_back', {
+                error: error.message,
+            });
+            return {
+                success: false,
+                error: error,
+                attempts: 1,
+                recoverable: true,
+            };
+        }
+    }
+    // ==================== SAFE FILE OPERATIONS ====================
+    /**
+     * Write file atomically (write to temp, then rename)
+     */
+    atomicWriteFile(filePath, content) {
+        const tempPath = `${filePath}.tmp.${Date.now()}`;
+        try {
+            writeFileSync(tempPath, content, { encoding: 'utf-8', flag: 'w' });
+            renameSync(tempPath, filePath);
+            return true;
+        }
+        catch (error) {
+            this.logger.error('Atomic write failed', {
+                filePath,
+                error: error.message,
+            });
+            // Clean up temp file if it exists
+            try {
+                if (existsSync(tempPath)) {
+                    unlinkSync(tempPath);
+                }
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            return false;
+        }
+    }
+    /**
+     * Read file with fallback to backup
+     */
+    safeReadFile(filePath, backupPath) {
+        // Try primary file
+        try {
+            if (existsSync(filePath)) {
+                return readFileSync(filePath, 'utf-8');
+            }
+        }
+        catch {
+            this.logger.warn('Failed to read primary file', { filePath });
+        }
+        // Try backup if provided
+        if (backupPath) {
+            try {
+                if (existsSync(backupPath)) {
+                    this.logger.info('Using backup file', { backupPath });
+                    return readFileSync(backupPath, 'utf-8');
+                }
+            }
+            catch {
+                this.logger.error('Failed to read backup file', { backupPath });
+            }
+        }
+        return null;
+    }
+    // ==================== UTILITIES ====================
+    sleep(ms) {
+        return new Promise(resolve => { setTimeout(resolve, ms); });
+    }
+    sleepSync(ms) {
+        // Block the calling thread for `ms` WITHOUT a CPU busy-wait. Atomics.wait on
+        // an unshared int never gets notified, so it just times out after `ms` —
+        // sleeping the thread (0% CPU) instead of spinning the event loop.
+        if (ms <= 0)
+            return;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    /**
+     * Generate a unique operation ID
+     */
+    generateOperationId(prefix = 'op') {
+        return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+}
+// ==================== SINGLETON INSTANCE ====================
+let _resilienceManager = null;
+export function getResilienceManager() {
+    if (!_resilienceManager) {
+        _resilienceManager = new ResilienceManager();
+    }
+    return _resilienceManager;
+}
+// ==================== HELPER DECORATORS ====================
+/**
+ * Decorator to add retry logic to a method
+ */
+export function withRetry(config) {
+    return function (_target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const manager = getResilienceManager();
+            const result = await manager.withRetry(() => originalMethod.apply(this, args), propertyKey, config);
+            if (!result.success) {
+                throw result.error;
+            }
+            return result.data;
+        };
+        return descriptor;
+    };
+}
+/**
+ * Decorator to add checkpointing to a method
+ */
+export function withCheckpoint(operationName) {
+    return function (_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const manager = getResilienceManager();
+            const operationId = manager.generateOperationId(operationName);
+            manager.createCheckpoint(operationId, operationName, 'started', { args });
+            try {
+                const result = await originalMethod.apply(this, args);
+                manager.completeCheckpoint(operationId);
+                return result;
+            }
+            catch (error) {
+                manager.updateCheckpoint(operationId, 'failed', {
+                    error: error.message,
+                });
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=resilience.js.map