@juspay/yama 1.4.1 → 1.5.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [1.5.1](https://github.com/juspay/yama/compare/v1.5.0...v1.5.1) (2025-09-24)
+
+### Bug Fixes
+
+- **allocation:** Added fix for batch token allocation ([11f7192](https://github.com/juspay/yama/commit/11f719257a75ba946c45612e336db69a17cf278d))
+
+# [1.5.0](https://github.com/juspay/yama/compare/v1.4.1...v1.5.0) (2025-09-19)
+
+### Features
+
+- **summary:** Added config support for summary comment ([666ea5c](https://github.com/juspay/yama/commit/666ea5c78b93d2ef3df24a09f95581a4b8e75650))
+
 ## [1.4.1](https://github.com/juspay/yama/compare/v1.4.0...v1.4.1) (2025-09-18)
 
 ### Bug Fixes

package/dist/core/providers/BitbucketProvider.js

@@ -5,6 +5,7 @@
 import { ProviderError, } from "../../types/index.js";
 import { logger } from "../../utils/Logger.js";
 import { cache, Cache } from "../../utils/Cache.js";
+import { RetryManager } from "../../utils/RetryManager.js";
 export class BitbucketProvider {
     apiClient;
     branchHandlers;
@@ -85,14 +86,14 @@ export class BitbucketProvider {
             throw new ProviderError("Branch name is required");
         }
         const cacheKey = Cache.keys.branchInfo(workspace, repository, branch);
-        return cache.getOrSet(cacheKey, async () => {
+        return cache.getOrSetResilient(cacheKey, async () => {
             logger.debug(`Finding PR for branch: ${workspace}/${repository}@${branch}`);
-            const rawBranchData = await this.branchHandlers.handleGetBranch({
+            const rawBranchData = await RetryManager.withRetry(() => this.branchHandlers.handleGetBranch({
                 workspace,
                 repository,
                 branch_name: branch,
                 include_merged_prs: false,
-            });
+            }), `Find PR for branch ${workspace}/${repository}@${branch}`);
             const branchData = this.parseMCPResponse(rawBranchData);
             // Direct data extraction
             if (branchData.open_pull_requests &&
@@ -131,13 +132,13 @@ export class BitbucketProvider {
             throw new ProviderError("Pull request ID is required");
         }
         const cacheKey = Cache.keys.prInfo(workspace, repository, pullRequestId);
-        return cache.getOrSet(cacheKey, async () => {
+        return cache.getOrSetResilient(cacheKey, async () => {
             logger.debug(`Getting PR details: ${workspace}/${repository}#${pullRequestId}`);
-            const rawPRDetails = await this.pullRequestHandlers.handleGetPullRequest({
+            const rawPRDetails = await RetryManager.withRetry(() => this.pullRequestHandlers.handleGetPullRequest({
                 workspace,
                 repository,
                 pull_request_id: pullRequestId,
-            });
+            }), `Get PR details ${workspace}/${repository}#${pullRequestId}`);
             const prData = this.parseMCPResponse(rawPRDetails);
             // Debug author data structure
             logger.debug(`PR Details author data structure: ${JSON.stringify(prData.author, null, 2)}`);
@@ -175,7 +176,7 @@ export class BitbucketProvider {
         const cacheKey = includePatterns && includePatterns.length === 1
             ? `file-diff:${workspace}:${repository}:${pullRequestId}:${includePatterns[0]}`
             : Cache.keys.prDiff(workspace, repository, pullRequestId);
-        return cache.getOrSet(cacheKey, async () => {
+        return cache.getOrSetResilient(cacheKey, async () => {
             logger.debug(`Getting PR diff: ${workspace}/${repository}#${pullRequestId}`);
             if (includePatterns) {
                 logger.debug(`Include patterns: ${includePatterns.join(", ")}`);
@@ -191,7 +192,7 @@ export class BitbucketProvider {
             if (includePatterns) {
                 args.include_patterns = includePatterns;
             }
-            const rawDiff = await this.reviewHandlers.handleGetPullRequestDiff(args);
+            const rawDiff = await RetryManager.withRetry(() => this.reviewHandlers.handleGetPullRequestDiff(args), `Get PR diff ${workspace}/${repository}#${pullRequestId}`);
             const diffData = this.parseMCPResponse(rawDiff);
             return {
                 diff: diffData.diff || "",
@@ -207,18 +208,28 @@ export class BitbucketProvider {
     async getFileContent(workspace, repository, filePath, branch) {
         await this.initialize();
         const cacheKey = Cache.keys.fileContent(workspace, repository, filePath, branch);
-        return cache.getOrSet(cacheKey, async () => {
+        return cache.getOrSetResilient(cacheKey, async () => {
             logger.debug(`Getting file content: ${workspace}/${repository}/${filePath}@${branch}`);
-            const result = await this.fileHandlers.handleGetFileContent({
+            const result = await RetryManager.withRetry(() => this.fileHandlers.handleGetFileContent({
                 workspace,
                 repository,
                 file_path: filePath,
                 branch,
-            });
-            // Handle file content response directly (don't JSON parse)
-            if (result.content && result.content[0] && result.content[0].text) {
-                const fileResponse = JSON.parse(result.content[0].text);
-                return fileResponse.content || "";
+            }), `Get file content ${workspace}/${repository}/${filePath}@${branch}`);
+            // Handle file content response with proper error handling for plain text files
+            if (result.content &&
+                result.content[0] &&
+                result.content[0].text) {
+                try {
+                    const fileResponse = JSON.parse(result.content[0].text);
+                    return fileResponse.content || "";
+                }
+                catch (parseError) {
+                    // If JSON parsing fails, the content might be plain text (like .clinerules)
+                    // Return the text content directly
+                    logger.debug(`JSON parsing failed for ${filePath}, treating as plain text: ${parseError.message}`);
+                    return result.content[0].text || "";
+                }
             }
             // Handle direct response format
             return result.content || "";
@@ -230,14 +241,14 @@ export class BitbucketProvider {
     async listDirectoryContent(workspace, repository, path, branch) {
         await this.initialize();
         const cacheKey = Cache.keys.directoryContent(workspace, repository, path, branch);
-        return cache.getOrSet(cacheKey, async () => {
+        return cache.getOrSetResilient(cacheKey, async () => {
             logger.debug(`Listing directory: ${workspace}/${repository}/${path}@${branch}`);
-            const result = await this.fileHandlers.handleListDirectoryContent({
+            const result = await RetryManager.withRetry(() => this.fileHandlers.handleListDirectoryContent({
                 workspace,
                 repository,
                 path,
                 branch,
-            });
+            }), `List directory ${workspace}/${repository}/${path}@${branch}`);
             const dirData = this.parseMCPResponse(result);
             return dirData.contents || [];
         }, 3600);
@@ -254,12 +265,12 @@ export class BitbucketProvider {
         try {
             logger.debug(`Updating PR description: ${workspace}/${repository}#${pullRequestId}`);
             logger.debug(`Description length: ${description.length} characters`);
-            const result = await this.pullRequestHandlers.handleUpdatePullRequest({
+            const result = await RetryManager.withRetry(() => this.pullRequestHandlers.handleUpdatePullRequest({
                 workspace,
                 repository,
                 pull_request_id: pullRequestId,
                 description: description,
-            });
+            }), `Update PR description ${workspace}/${repository}#${pullRequestId}`);
             // Log the raw MCP response
             logger.debug(`Raw MCP update response: ${JSON.stringify(result, null, 2)}`);
             const updateData = this.parseMCPResponse(result);
@@ -335,10 +346,12 @@ export class BitbucketProvider {
                 logger.debug(`   Type: ${options.lineType || "CONTEXT"}`);
             }
             logger.debug(`🔍 MCP addComment args: ${JSON.stringify(args, null, 2)}`);
-            const result = await this.pullRequestHandlers.handleAddComment(args);
+            const result = await RetryManager.withRetry(() => this.pullRequestHandlers.handleAddComment(args), `Add comment to PR ${workspace}/${repository}#${pullRequestId}`);
             // Parse response exactly like pr-police.js
             let commentData;
-            if (result.content && result.content[0] && result.content[0].text) {
+            if (result.content &&
+                result.content[0] &&
+                result.content[0].text) {
                 commentData = JSON.parse(result.content[0].text);
             }
             else {
@@ -361,7 +374,7 @@ export class BitbucketProvider {
                         pull_request_id: pullRequestId,
                         comment_text: `**File: ${options.filePath}**\n\n${commentText}`,
                     };
-                    const fallbackResult = await this.pullRequestHandlers.handleAddComment(fallbackArgs);
+                    const fallbackResult = await RetryManager.withRetry(() => this.pullRequestHandlers.handleAddComment(fallbackArgs), `Add fallback comment to PR ${workspace}/${repository}#${pullRequestId}`);
                     let fallbackData;
                     if (fallbackResult.content &&
                         fallbackResult.content[0] &&

package/dist/features/CodeReviewer.d.ts

@@ -108,6 +108,18 @@ export declare class CodeReviewer {
      * Process batches serially (original implementation)
      */
     private processSerially;
+    /**
+     * Pre-allocate tokens based on distribution strategy with proper integer arithmetic
+     */
+    private preAllocateTokens;
+    /**
+     * Try weighted allocation for batches
+     */
+    private tryWeightedAllocation;
+    /**
+     * Try equal allocation for batches
+     */
+    private tryEqualAllocation;
     /**
      * Process a single batch with concurrency control
      */

package/dist/features/CodeReviewer.js

@@ -465,8 +465,9 @@ Return ONLY valid JSON:
                 });
             }
         }
-        // Post summary comment (include failed comments info if any)
-        if (uniqueViolations.length > 0) {
+        // Post summary comment (include failed comments info if any) - only if enabled in config
+        const shouldPostSummary = this.reviewConfig.postSummaryComment !== false; // Default to true if not specified
+        if (uniqueViolations.length > 0 && shouldPostSummary) {
             try {
                 const summaryComment = this.generateSummaryComment(uniqueViolations, context, failedComments);
                 await this.bitbucketProvider.addComment(context.identifier, summaryComment);
@@ -477,6 +478,9 @@ Return ONLY valid JSON:
                 logger.debug(`❌ Failed to post summary comment: ${error.message}`);
             }
         }
+        else if (uniqueViolations.length > 0 && !shouldPostSummary) {
+            logger.debug("📝 Summary comment posting disabled in configuration");
+        }
         logger.success(`✅ Posted ${commentsPosted} comments successfully`);
         if (commentsFailed > 0) {
             logger.warn(`⚠️ Failed to post ${commentsFailed} inline comments`);
@@ -918,7 +922,25 @@ ${recommendation}
         // Initialize concurrency control
         const semaphore = new Semaphore(optimalConcurrency);
         const tokenBudget = new TokenBudgetManager(this.getSafeTokenLimit() * 0.8); // 80% for safety
-        logger.info(`🎯 Parallel processing: ${optimalConcurrency} concurrent batches, ${tokenBudget.getTotalBudget()} token budget`);
+        // NEW: Pre-allocate tokens based on distribution strategy
+        const distributionStrategy = parallelConfig.tokenBudgetDistribution || "equal";
+        logger.info(`🎯 Using ${distributionStrategy} token distribution strategy for ${batches.length} batches`);
+        const tokenAllocations = this.preAllocateTokens(batches, tokenBudget, distributionStrategy);
+        if (!tokenAllocations) {
+            const totalRequired = batches.reduce((sum, b) => sum + b.estimatedTokens, 0);
+            const totalBudget = tokenBudget.getTotalBudget();
+            throw new Error(`Insufficient token budget: required ${totalRequired}, available ${totalBudget}. ` +
+                `Consider reducing batch count (current: ${batches.length}) or increasing token limit.`);
+        }
+        // Apply pre-allocated tokens to the budget manager
+        if (!tokenBudget.preAllocateAllBatches(tokenAllocations)) {
+            throw new Error("Failed to pre-allocate tokens for all batches");
+        }
+        logger.info(`🎯 Parallel processing: ${optimalConcurrency} concurrent batches, ${tokenBudget.getTotalBudget()} token budget (${distributionStrategy} distribution)`);
+        // Log allocation details
+        tokenAllocations.forEach((tokens, batchIndex) => {
+            logger.debug(`Batch ${batchIndex + 1}: ${tokens} tokens allocated`);
+        });
         const batchResults = new Array(batches.length);
         const allViolations = [];
         const processingPromises = [];
@@ -1002,6 +1024,149 @@ ${recommendation}
         logger.success(`🎯 Serial processing completed: ${allViolations.length} total violations from ${batches.length} batches in ${Math.round(totalTime / 1000)}s (avg ${avgBatchSize.toFixed(1)} files/batch)`);
         return { violations: allViolations, batchResults };
     }
+    /**
+     * Pre-allocate tokens based on distribution strategy with proper integer arithmetic
+     */
+    preAllocateTokens(batches, tokenBudget, strategy) {
+        // Ensure we're working with integer budget to avoid floating-point issues
+        const totalBudget = Math.floor(tokenBudget.getTotalBudget());
+        const allocations = new Map();
+        if (strategy === "equal") {
+            // Equal distribution: divide budget equally among all batches with proper remainder handling
+            const baseTokens = Math.floor(totalBudget / batches.length);
+            const remainder = totalBudget % batches.length;
+            if (baseTokens < 1000) {
+                // Minimum viable tokens per batch
+                logger.error(`Equal distribution would give ${baseTokens} tokens per batch, which is insufficient`);
+                return null;
+            }
+            let totalAllocated = 0;
+            for (let i = 0; i < batches.length; i++) {
+                // Distribute remainder to first few batches
+                const tokens = baseTokens + (i < remainder ? 1 : 0);
+                allocations.set(i, tokens);
+                totalAllocated += tokens;
+            }
+            // Double-check that we haven't exceeded budget due to any calculation errors
+            if (totalAllocated > totalBudget) {
+                logger.error(`Equal distribution calculation error: ${totalAllocated} > ${totalBudget}`);
+                // Adjust the last batch to fit within budget
+                const lastBatchIndex = batches.length - 1;
+                const lastBatchTokens = allocations.get(lastBatchIndex);
+                const adjustment = totalAllocated - totalBudget;
+                const newLastBatchTokens = lastBatchTokens - adjustment;
+                if (newLastBatchTokens < 1000) {
+                    logger.error(`Adjustment would result in last batch having ${newLastBatchTokens} tokens, which is below the minimum threshold (1000). Aborting allocation.`);
+                    return null;
+                }
+                allocations.set(lastBatchIndex, newLastBatchTokens);
+                totalAllocated = totalBudget;
+                logger.warn(`Adjusted last batch by -${adjustment} tokens to fit budget`);
+            }
+            logger.info(`Equal distribution: ${baseTokens} tokens per batch for ${batches.length} batches`);
+            logger.debug(`Pre-allocated ${totalAllocated} tokens across ${batches.length} batches (${totalBudget - totalAllocated} remaining)`);
+        }
+        else if (strategy === "weighted") {
+            // Weighted distribution: try weighted first, automatically fallback to equal if needed
+            logger.debug(`Attempting weighted distribution...`);
+            const weightedResult = this.tryWeightedAllocation(batches, totalBudget);
+            if (weightedResult) {
+                // Weighted allocation succeeded
+                weightedResult.forEach((tokens, batchIndex) => {
+                    allocations.set(batchIndex, tokens);
+                });
+                logger.info(`✅ Weighted distribution: optimal allocation successful`);
+                logger.debug(`Pre-allocated ${Array.from(weightedResult.values()).reduce((sum, tokens) => sum + tokens, 0)} tokens across ${batches.length} batches`);
+            }
+            else {
+                // Weighted allocation failed, automatically fallback to equal distribution
+                logger.warn(`⚠️ Weighted distribution: insufficient budget for optimal allocation, falling back to equal distribution`);
+                const equalResult = this.tryEqualAllocation(batches, totalBudget);
+                if (!equalResult) {
+                    logger.error(`Weighted distribution: both optimal and equal allocation failed`);
+                    return null;
+                }
+                equalResult.forEach((tokens, batchIndex) => {
+                    allocations.set(batchIndex, tokens);
+                });
+                logger.info(`✅ Weighted distribution: equal allocation fallback successful`);
+                logger.debug(`Pre-allocated ${Array.from(equalResult.values()).reduce((sum, tokens) => sum + tokens, 0)} tokens across ${batches.length} batches`);
+            }
+        }
+        // Final validation with strict integer checking
+        const totalAllocated = Array.from(allocations.values()).reduce((sum, tokens) => sum + tokens, 0);
+        if (totalAllocated > totalBudget) {
+            logger.error(`CRITICAL: Total allocation (${totalAllocated}) exceeds budget (${totalBudget}) - this should never happen`);
+            logger.error(`Budget type: ${typeof totalBudget}, Allocation type: ${typeof totalAllocated}`);
+            logger.error(`Individual allocations: ${Array.from(allocations.entries())
+                .map(([i, tokens]) => `batch${i}:${tokens}`)
+                .join(", ")}`);
+            throw new Error(`Total allocation (${totalAllocated}) exceeds budget (${totalBudget}) - this should never happen`);
+        }
+        return allocations;
+    }
+    /**
+     * Try weighted allocation for batches
+     */
+    tryWeightedAllocation(batches, totalBudget) {
+        const totalEstimated = batches.reduce((sum, batch) => sum + batch.estimatedTokens, 0);
+        if (totalEstimated > totalBudget) {
+            logger.debug(`Total estimated tokens (${totalEstimated}) exceed budget (${totalBudget})`);
+            return null;
+        }
+        let totalAllocated = 0;
+        const minTokensPerBatch = 1000;
+        const allocations = new Map();
+        for (let i = 0; i < batches.length; i++) {
+            const batch = batches[i];
+            const weight = batch.estimatedTokens / totalEstimated;
+            const allocation = Math.floor(weight * totalBudget);
+            const finalAllocation = Math.max(allocation, minTokensPerBatch);
+            allocations.set(i, finalAllocation);
+            totalAllocated += finalAllocation;
+        }
+        // Check if we exceeded budget due to minimum allocations
+        if (totalAllocated > totalBudget) {
+            logger.debug(`Weighted allocation with minimums (${totalAllocated}) exceeds budget (${totalBudget})`);
+            return null;
+        }
+        return allocations;
+    }
+    /**
+     * Try equal allocation for batches
+     */
+    tryEqualAllocation(batches, totalBudget) {
+        const baseTokens = Math.floor(totalBudget / batches.length);
+        const remainder = totalBudget % batches.length;
+        if (baseTokens < 1000) {
+            // Minimum viable tokens per batch
+            logger.debug(`Equal distribution would give ${baseTokens} tokens per batch, which is insufficient`);
+            return null;
+        }
+        const allocations = new Map();
+        let totalAllocated = 0;
+        for (let i = 0; i < batches.length; i++) {
+            // Distribute remainder to first few batches
+            const tokens = baseTokens + (i < remainder ? 1 : 0);
+            allocations.set(i, tokens);
+            totalAllocated += tokens;
+        }
+        // Double-check that we haven't exceeded budget due to any calculation errors
+        if (totalAllocated > totalBudget) {
+            logger.debug(`Equal distribution calculation error: ${totalAllocated} > ${totalBudget}`);
+            // Adjust the last batch to fit within budget
+            const lastBatchIndex = batches.length - 1;
+            const lastBatchTokens = allocations.get(lastBatchIndex);
+            const adjustment = totalAllocated - totalBudget;
+            const newLastBatchTokens = lastBatchTokens - adjustment;
+            if (newLastBatchTokens < 1000) {
+                logger.error(`Adjustment would result in last batch having ${newLastBatchTokens} tokens, which is below the minimum threshold (1000). Aborting allocation.`);
+                return null;
+            }
+            allocations.set(lastBatchIndex, newLastBatchTokens);
+        }
+        return allocations;
+    }
     /**
      * Process a single batch with concurrency control
      */
@@ -1009,9 +1174,22 @@ ${recommendation}
         // Acquire semaphore permit
         await semaphore.acquire();
         try {
-            // Check token budget
-            if (!tokenBudget.allocateForBatch(batchIndex, batch.estimatedTokens)) {
-                throw new Error(`Insufficient token budget for batch ${batchIndex + 1}`);
+            // NEW: In pre-allocation mode, tokens are already allocated, just verify and mark as processing
+            if (tokenBudget.isPreAllocationMode()) {
+                const batchState = tokenBudget.getBatchState(batchIndex);
+                if (batchState !== "pending") {
+                    throw new Error(`Batch ${batchIndex + 1} is not in pending state (current: ${batchState})`);
+                }
+                // Mark as processing (this is handled in allocateForBatch for pre-allocation mode)
+                if (!tokenBudget.allocateForBatch(batchIndex, batch.estimatedTokens)) {
+                    throw new Error(`Failed to mark batch ${batchIndex + 1} as processing`);
+                }
+            }
+            else {
+                // Legacy mode: allocate tokens dynamically
+                if (!tokenBudget.allocateForBatch(batchIndex, batch.estimatedTokens)) {
+                    throw new Error(`Insufficient token budget for batch ${batchIndex + 1}`);
+                }
             }
             logger.info(`🔄 Processing batch ${batchIndex + 1}/${totalBatches} (${batch.files.length} files, parallel)`);
             // Process the batch (existing logic)
@@ -1019,6 +1197,11 @@ ${recommendation}
             logger.info(`✅ Batch ${batchIndex + 1} completed: ${result.violations.length} violations in ${Math.round(result.processingTime / 1000)}s`);
             return result;
         }
+        catch (error) {
+            // Mark batch as failed in token budget
+            tokenBudget.markBatchFailed(batchIndex, error.message);
+            throw error;
+        }
         finally {
             // Always release resources
             tokenBudget.releaseBatch(batchIndex);

package/dist/features/MultiInstanceProcessor.js

@@ -237,8 +237,9 @@ export class MultiInstanceProcessor {
             minLimit = Math.min(minLimit, instanceLimit);
         }
         // Total budget is the sum of all instance limits, but with safety margin
-        const totalBudget = instances.length * minLimit * 0.8; // 80% safety margin
-        logger.debug(`Calculated total token budget: ${totalBudget} (${instances.length} instances × ${minLimit} × 0.8)`);
+        // Use Math.floor to ensure integer result and avoid floating-point precision issues
+        const totalBudget = Math.floor(instances.length * minLimit * 0.8); // 80% safety margin
+        logger.debug(`Calculated total token budget: ${totalBudget} (${instances.length} instances × ${minLimit} × 0.8, floored)`);
         return totalBudget;
     }
     /**

package/dist/types/index.d.ts

@@ -283,6 +283,7 @@ export interface CodeReviewConfig {
     systemPrompt?: string;
     analysisTemplate?: string;
     focusAreas?: string[];
+    postSummaryComment?: boolean;
     batchProcessing?: BatchProcessingConfig;
     multiInstance?: MultiInstanceConfig;
     semanticDeduplication?: SemanticDeduplicationConfig;
@@ -568,6 +569,7 @@ export interface TokenBudgetManagerInterface {
     getAvailableBudget(): number;
     getTotalBudget(): number;
     getUsedTokens(): number;
+    preAllocateAllBatches(allocations: Map<number, number>): boolean;
 }
 export declare class GuardianError extends Error {
     code: string;
@@ -583,4 +585,40 @@ export declare class ProviderError extends GuardianError {
 export declare class ValidationError extends GuardianError {
     constructor(message: string, context?: any);
 }
+export declare enum CacheErrorCode {
+    CACHE_SYSTEM_FAILURE = "CACHE_SYSTEM_FAILURE",
+    CACHE_MEMORY_EXHAUSTED = "CACHE_MEMORY_EXHAUSTED",
+    CACHE_INITIALIZATION_FAILED = "CACHE_INITIALIZATION_FAILED",
+    CACHE_STORAGE_FULL = "CACHE_STORAGE_FULL",
+    CACHE_STORAGE_PERMISSION = "CACHE_STORAGE_PERMISSION",
+    CACHE_STORAGE_CORRUPTION = "CACHE_STORAGE_CORRUPTION",
+    CACHE_NETWORK_CONNECTION = "CACHE_NETWORK_CONNECTION",
+    CACHE_NETWORK_TIMEOUT = "CACHE_NETWORK_TIMEOUT",
+    CACHE_NETWORK_AUTH = "CACHE_NETWORK_AUTH",
+    CACHE_CONFIG_INVALID = "CACHE_CONFIG_INVALID",
+    CACHE_CONFIG_MISSING = "CACHE_CONFIG_MISSING",
+    CACHE_OPERATION_FAILED = "CACHE_OPERATION_FAILED",
+    CACHE_SERIALIZATION_ERROR = "CACHE_SERIALIZATION_ERROR",
+    CACHE_KEY_INVALID = "CACHE_KEY_INVALID"
+}
+export declare abstract class CacheError extends GuardianError {
+    operation?: string | undefined;
+    key?: string | undefined;
+    constructor(code: CacheErrorCode, message: string, operation?: string | undefined, key?: string | undefined, context?: any);
+}
+export declare class CacheSystemError extends CacheError {
+    constructor(message: string, operation?: string, key?: string, context?: any);
+}
+export declare class CacheStorageError extends CacheError {
+    constructor(code: CacheErrorCode | undefined, message: string, operation?: string, key?: string, context?: any);
+}
+export declare class CacheNetworkError extends CacheError {
+    constructor(code: CacheErrorCode | undefined, message: string, operation?: string, key?: string, context?: any);
+}
+export declare class CacheConfigurationError extends CacheError {
+    constructor(code: CacheErrorCode | undefined, message: string, operation?: string, key?: string, context?: any);
+}
+export declare class CacheOperationError extends CacheError {
+    constructor(code: CacheErrorCode | undefined, message: string, operation?: string, key?: string, context?: any);
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -34,6 +34,71 @@ export class ValidationError extends GuardianError {
     }
 }
 // ============================================================================
+// Cache Error Types
+// ============================================================================
+export var CacheErrorCode;
+(function (CacheErrorCode) {
+    // System-level cache errors
+    CacheErrorCode["CACHE_SYSTEM_FAILURE"] = "CACHE_SYSTEM_FAILURE";
+    CacheErrorCode["CACHE_MEMORY_EXHAUSTED"] = "CACHE_MEMORY_EXHAUSTED";
+    CacheErrorCode["CACHE_INITIALIZATION_FAILED"] = "CACHE_INITIALIZATION_FAILED";
+    // Storage-related errors
+    CacheErrorCode["CACHE_STORAGE_FULL"] = "CACHE_STORAGE_FULL";
+    CacheErrorCode["CACHE_STORAGE_PERMISSION"] = "CACHE_STORAGE_PERMISSION";
+    CacheErrorCode["CACHE_STORAGE_CORRUPTION"] = "CACHE_STORAGE_CORRUPTION";
+    // Network-related errors (for future Redis support)
+    CacheErrorCode["CACHE_NETWORK_CONNECTION"] = "CACHE_NETWORK_CONNECTION";
+    CacheErrorCode["CACHE_NETWORK_TIMEOUT"] = "CACHE_NETWORK_TIMEOUT";
+    CacheErrorCode["CACHE_NETWORK_AUTH"] = "CACHE_NETWORK_AUTH";
+    // Configuration errors
+    CacheErrorCode["CACHE_CONFIG_INVALID"] = "CACHE_CONFIG_INVALID";
+    CacheErrorCode["CACHE_CONFIG_MISSING"] = "CACHE_CONFIG_MISSING";
+    // Operation errors
+    CacheErrorCode["CACHE_OPERATION_FAILED"] = "CACHE_OPERATION_FAILED";
+    CacheErrorCode["CACHE_SERIALIZATION_ERROR"] = "CACHE_SERIALIZATION_ERROR";
+    CacheErrorCode["CACHE_KEY_INVALID"] = "CACHE_KEY_INVALID";
+})(CacheErrorCode || (CacheErrorCode = {}));
+export class CacheError extends GuardianError {
+    operation;
+    key;
+    constructor(code, message, operation, key, context) {
+        super(code, message, context);
+        this.operation = operation;
+        this.key = key;
+        this.name = "CacheError";
+    }
+}
+export class CacheSystemError extends CacheError {
+    constructor(message, operation, key, context) {
+        super(CacheErrorCode.CACHE_SYSTEM_FAILURE, message, operation, key, context);
+        this.name = "CacheSystemError";
+    }
+}
+export class CacheStorageError extends CacheError {
+    constructor(code = CacheErrorCode.CACHE_STORAGE_FULL, message, operation, key, context) {
+        super(code, message, operation, key, context);
+        this.name = "CacheStorageError";
+    }
+}
+export class CacheNetworkError extends CacheError {
+    constructor(code = CacheErrorCode.CACHE_NETWORK_CONNECTION, message, operation, key, context) {
+        super(code, message, operation, key, context);
+        this.name = "CacheNetworkError";
+    }
+}
+export class CacheConfigurationError extends CacheError {
+    constructor(code = CacheErrorCode.CACHE_CONFIG_INVALID, message, operation, key, context) {
+        super(code, message, operation, key, context);
+        this.name = "CacheConfigurationError";
+    }
+}
+export class CacheOperationError extends CacheError {
+    constructor(code = CacheErrorCode.CACHE_OPERATION_FAILED, message, operation, key, context) {
+        super(code, message, operation, key, context);
+        this.name = "CacheOperationError";
+    }
+}
+// ============================================================================
 // Export all types - Main file, no re-exports needed
 // ============================================================================
 //# sourceMappingURL=index.js.map

package/dist/utils/Cache.d.ts

@@ -8,7 +8,7 @@ export declare class Cache implements ICache {
     private statsData;
     constructor(options?: CacheOptions);
     /**
-     * Get value from cache
+     * Get value from cache with resilient error handling
      */
     get<T>(key: string): T | undefined;
     /**
@@ -39,15 +39,21 @@ export declare class Cache implements ICache {
         misses: number;
         keys: number;
         size: number;
+        cacheErrors: number;
+        nonCacheErrors: number;
     };
     /**
      * Get detailed cache statistics from node-cache
      */
     getDetailedStats(): any;
     /**
-     * Get or set pattern - common caching pattern
+     * Get or set pattern with automatic fallback on cache failures
      */
     getOrSet<T>(key: string, fetchFn: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Resilient get or set pattern that bypasses cache entirely on cache system failures
+     */
+    getOrSetResilient<T>(key: string, fetchFn: () => Promise<T>, ttl?: number): Promise<T>;
     /**
      * Cache with tags for group invalidation
      */