observability-toolkit 2.0.0 → 2.1.1

package/dist/lib/quality/quality-visualization.test.js

@@ -0,0 +1,189 @@
+/**
+ * Tests for Quality Visualization helpers (Pipeline View & Coverage Heatmap)
+ */
+import { describe, it } from 'vitest';
+import * as assert from 'node:assert';
+import { COUNT_FIFTY, COUNT_FIVE, COUNT_FOUR, COUNT_HUNDRED, COUNT_TWO, } from '../../test-helpers/test-constants.js';
+import { computePipelineView, computeCoverageHeatmap, computeDashboardSummary, } from './quality-metrics.js';
+import { requireDefined } from '../../test-helpers/assertions.js';
+describe('quality-visualization', () => {
+    // ==========================================================================
+    // Pipeline Visualization (G8)
+    // ==========================================================================
+    describe('computePipelineView', () => {
+        it('computes 4 pipeline stages from evaluation data', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8 },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'relevance', scoreValue: 0.9 },
+                        { timestamp: '2026-01-01T00:02:00Z', evaluationName: 'relevance', scoreValue: 0.7 },
+                    ]],
+                ['hallucination', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'hallucination', scoreValue: 0.05 },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'hallucination', scoreValue: 0.08 },
+                    ]],
+            ]);
+            const dashboard = computeDashboardSummary(evaluationsByMetric);
+            const pipeline = computePipelineView(evaluationsByMetric, dashboard);
+            assert.strictEqual(pipeline.stages.length, COUNT_FOUR);
+            assert.strictEqual(pipeline.stages[0].name, 'ingested');
+            assert.strictEqual(pipeline.stages[0].entryCount, COUNT_FIVE); // 3 + 2 total
+            assert.strictEqual(pipeline.stages[1].name, 'scored');
+            assert.strictEqual(pipeline.stages[2].name, 'evaluated');
+            assert.strictEqual(pipeline.stages[3].name, 'alerted');
+        });
+        it('computes drop-off within stages', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8 },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'relevance' }, // no scoreValue
+                    ]],
+            ]);
+            const dashboard = computeDashboardSummary(evaluationsByMetric);
+            const pipeline = computePipelineView(evaluationsByMetric, dashboard);
+            assert.strictEqual(pipeline.dropoffs.length, COUNT_FOUR); // one per stage
+            // Ingested stage: 2 entry, 1 exit (undefined score filtered)
+            const ingestedDropoff = requireDefined(pipeline.dropoffs.find(d => d.stage === 'ingested'), 'Expected ingested stage dropoff');
+            assert.strictEqual(ingestedDropoff.dropped, 1);
+            assert.strictEqual(ingestedDropoff.dropoffPercent, COUNT_FIFTY);
+        });
+        it('handles empty evaluation map', () => {
+            const evaluationsByMetric = new Map();
+            const dashboard = computeDashboardSummary(evaluationsByMetric);
+            const pipeline = computePipelineView(evaluationsByMetric, dashboard);
+            assert.strictEqual(pipeline.stages[0].entryCount, 0);
+            assert.strictEqual(pipeline.overallConversionPercent, 0);
+        });
+        it('computes overall conversion rate', () => {
+            const evaluationsByMetric = new Map([
+                ['hallucination', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'hallucination', scoreValue: 0.3 },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'hallucination', scoreValue: 0.25 },
+                    ]],
+            ]);
+            const dashboard = computeDashboardSummary(evaluationsByMetric);
+            const pipeline = computePipelineView(evaluationsByMetric, dashboard);
+            // If hallucination triggers alerts, alerted count > 0
+            assert.ok(pipeline.overallConversionPercent >= 0);
+            assert.ok(pipeline.overallConversionPercent <= COUNT_HUNDRED);
+        });
+    });
+    // ==========================================================================
+    // Coverage Heatmap (G9)
+    // ==========================================================================
+    describe('computeCoverageHeatmap', () => {
+        it('computes coverage matrix from evaluation data', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, traceId: 'trace-1' },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'relevance', scoreValue: 0.9, traceId: 'trace-2' },
+                    ]],
+                ['hallucination', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'hallucination', scoreValue: 0.05, traceId: 'trace-1' },
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric);
+            assert.strictEqual(heatmap.metrics.length, COUNT_TWO);
+            assert.strictEqual(heatmap.inputs.length, COUNT_TWO);
+            assert.strictEqual(heatmap.cells.length, COUNT_FOUR); // 2 metrics x 2 inputs
+        });
+        it('identifies coverage gaps', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, traceId: 'trace-1' },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'relevance', scoreValue: 0.9, traceId: 'trace-2' },
+                    ]],
+                ['hallucination', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'hallucination', scoreValue: 0.05, traceId: 'trace-1' },
+                        // Missing trace-2 for hallucination
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric);
+            // hallucination is missing trace-2
+            const hallucinationGap = requireDefined(heatmap.gaps.find(g => g.metric === 'hallucination'), 'Expected hallucination gap');
+            assert.ok(hallucinationGap.missingInputs.includes('trace-2'));
+            assert.strictEqual(hallucinationGap.coveragePercent, COUNT_FIFTY);
+        });
+        it('computes overall coverage percentage', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, traceId: 'trace-1' },
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric);
+            // 1 metric, 1 input, fully covered
+            assert.strictEqual(heatmap.overallCoveragePercent, COUNT_HUNDRED);
+        });
+        it('handles empty evaluation map', () => {
+            const evaluationsByMetric = new Map();
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric);
+            assert.strictEqual(heatmap.metrics.length, 0);
+            assert.strictEqual(heatmap.inputs.length, 0);
+            assert.strictEqual(heatmap.cells.length, 0);
+            assert.strictEqual(heatmap.overallCoveragePercent, 0);
+        });
+        it('supports sessionId as input key', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, sessionId: 'session-a' },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'relevance', scoreValue: 0.9, sessionId: 'session-b' },
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric, { inputKey: 'sessionId' });
+            assert.strictEqual(heatmap.inputs.length, COUNT_TWO);
+            assert.ok(heatmap.inputs.includes('session-a'));
+            assert.ok(heatmap.inputs.includes('session-b'));
+        });
+        it('supports legacy string inputKey argument', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, sessionId: 'session-a' },
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric, 'sessionId');
+            assert.ok(heatmap.inputs.includes('session-a'));
+        });
+        it('count=1 is covered with default threshold', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, traceId: 'trace-1' },
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric);
+            const cell = requireDefined(heatmap.cells.find(c => c.metric === 'relevance' && c.input === 'trace-1'), 'Expected relevance/trace-1 heatmap cell');
+            assert.strictEqual(cell.status, 'covered');
+            assert.strictEqual(cell.count, 1);
+        });
+        it('supports configurable coverage thresholds', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, traceId: 'trace-1' },
+                        { timestamp: '2026-01-01T00:01:00Z', evaluationName: 'relevance', scoreValue: 0.9, traceId: 'trace-1' },
+                        { timestamp: '2026-01-01T00:02:00Z', evaluationName: 'relevance', scoreValue: 0.7, traceId: 'trace-2' },
+                    ]],
+            ]);
+            // Require 2+ for 'covered', 1 for 'partial'
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric, { coveredThreshold: COUNT_TWO, partialThreshold: 0 });
+            const cell1 = requireDefined(heatmap.cells.find(c => c.input === 'trace-1'), 'Expected trace-1 heatmap cell');
+            const cell2 = requireDefined(heatmap.cells.find(c => c.input === 'trace-2'), 'Expected trace-2 heatmap cell');
+            assert.strictEqual(cell1.status, 'covered'); // count=2 >= 2
+            assert.strictEqual(cell2.status, 'partial'); // count=1 > 0 but < 2
+        });
+        it('assigns missing status for missing trace coverage', () => {
+            const evaluationsByMetric = new Map([
+                ['relevance', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'relevance', scoreValue: 0.8, traceId: 'trace-1' },
+                    ]],
+                ['faithfulness', [
+                        { timestamp: '2026-01-01T00:00:00Z', evaluationName: 'faithfulness', scoreValue: 0.9, traceId: 'trace-2' },
+                    ]],
+            ]);
+            const heatmap = computeCoverageHeatmap(evaluationsByMetric);
+            // relevance missing trace-2, faithfulness missing trace-1
+            const relevanceTrace2 = requireDefined(heatmap.cells.find(c => c.metric === 'relevance' && c.input === 'trace-2'), 'Expected relevance/trace-2 heatmap cell');
+            assert.strictEqual(relevanceTrace2.status, 'missing');
+            assert.strictEqual(relevanceTrace2.count, 0);
+        });
+    });
+});
+//# sourceMappingURL=quality-visualization.test.js.map

package/dist/lib/quality/quality-visualization.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-visualization.test.js","sourceRoot":"","sources":["../../../src/lib/quality/quality-visualization.test.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EACL,WAAW,EACX,UAAU,EACV,UAAU,EACV,aAAa,EACb,SAAS,GACV,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAElE,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,6EAA6E;IAC7E,8BAA8B;IAC9B,6EAA6E;IAE7E,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;QACnC,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;YACzD,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE;wBACnF,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE;wBACnF,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE;qBACpF,CAAC;gBACF,CAAC,eAAe,EAAE;wBAChB,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE;wBACxF,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE;qBACzF,CAAC;aACH,CAAC,CAAC;YACH,MAAM,SAAS,GAAG,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;YAC/D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YAErE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YACvD,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACxD,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,cAAc;YAC7E,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtD,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YACzD,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;YACzC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE;wBACnF,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,EAAE,gBAAgB;qBACrF,CAAC;aACH,CAAC,CAAC;YACH,MAAM,SAAS,GAAG,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;YAC/D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YAErE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,gBAAgB;YAC1E,6DAA6D;YAC7D,MAAM,eAAe,GAAG,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,EAAE,iCAAiC,CAAC,CAAC;YAC/H,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC/C,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACtC,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAA8B,CAAC;YAClE,MAAM,SAAS,GAAG,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;YAC/D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YAErE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;YACrD,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,wBAAwB,EAAE,CAAC,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;YAC1C,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,eAAe,EAAE;wBAChB,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,EAAE;wBACvF,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE;qBACzF,CAAC;aACH,CAAC,CAAC;YACH,MAAM,SAAS,GAAG,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;YAC/D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;YAErE,sDAAsD;YACtD,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,wBAAwB,IAAI,CAAC,CAAC,CAAC;YAClD,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,wBAAwB,IAAI,aAAa,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,wBAAwB;IACxB,6EAA6E;IAE7E,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;QACtC,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;YACvD,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;wBACvG,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBACxG,CAAC;gBACF,CAAC,eAAe,EAAE;wBAChB,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE;qBAC7G,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;YAE5D,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACtD,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACrD,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,uBAAuB;QAC/E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;YAClC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;wBACvG,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBACxG,CAAC;gBACF,CAAC,eAAe,EAAE;wBAChB,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE;wBAC5G,oCAAoC;qBACrC,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;YAE5D,mCAAmC;YACnC,MAAM,gBAAgB,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,CAAC,EAAE,4BAA4B,CAAC,CAAC;YAC5H,MAAM,CAAC,EAAE,CAAC,gBAAgB,CAAC,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9D,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;YAC9C,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBACxG,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;YAE5D,mCAAmC;YACnC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,sBAAsB,EAAE,aAAa,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACtC,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAA8B,CAAC;YAClE,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;YAE5D,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC9C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC7C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC5C,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;YACzC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE;wBAC3G,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE;qBAC5G,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;YAEvF,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACrD,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;YAChD,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;YAClD,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE;qBAC5G,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAC;YACzE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;YACnD,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBACxG,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;YAC5D,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,EAAE,yCAAyC,CAAC,CAAC;YACnJ,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC3C,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;YACnD,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;wBACvG,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;wBACvG,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBACxG,CAAC;aACH,CAAC,CAAC;YACH,4CAA4C;YAC5C,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAC,CAAC;YAClH,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,EAAE,+BAA+B,CAAC,CAAC;YAC9G,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,EAAE,+BAA+B,CAAC,CAAC;YAC9G,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,eAAe;YAC5D,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,sBAAsB;QACrE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC3D,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA6B;gBAC9D,CAAC,WAAW,EAAE;wBACZ,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBACxG,CAAC;gBACF,CAAC,cAAc,EAAE;wBACf,EAAE,SAAS,EAAE,sBAAsB,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE;qBAC3G,CAAC;aACH,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;YAE5D,0DAA0D;YAC1D,MAAM,eAAe,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,EAAE,yCAAyC,CAAC,CAAC;YAC9J,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACtD,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/lib/resilience/cache.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+/**
+ * Cache statistics for monitoring and observability
+ */
+export declare const cacheStatsSchema: z.ZodObject<{
+    hits: z.ZodNumber;
+    misses: z.ZodNumber;
+    evictions: z.ZodNumber;
+    size: z.ZodNumber;
+    hitRate: z.ZodNumber;
+}, z.core.$strip>;
+export type CacheStats = z.infer<typeof cacheStatsSchema>;
+export declare const CACHE_TTL_MS: number;
+/** Default cache size: 100 entries per instance */
+export declare const DEFAULT_CACHE_SIZE = 100;
+/**
+ * Valid cache type identifiers for metrics.
+ * Restricts cardinality of cache_type metric label to prevent unbounded growth.
+ */
+export declare const cacheTypeSchema: z.ZodEnum<{
+    metrics: "metrics";
+    unknown: "unknown";
+    traces: "traces";
+    logs: "logs";
+    llmEvents: "llmEvents";
+    evaluations: "evaluations";
+}>;
+export type CacheType = z.infer<typeof cacheTypeSchema>;
+/**
+ * LRU cache with TTL expiration.
+ *
+ * Backed by lru-cache. Eviction OTel metrics fire only on LRU capacity eviction
+ * (reason === 'evict'), not on TTL expiry or explicit deletes.
+ *
+ * @typeParam T - Type of cached data (typically arrays of query results)
+ */
+export declare class QueryCache<T extends NonNullable<unknown>> {
+    private cache;
+    private hits;
+    private misses;
+    private evictions;
+    private readonly cacheType;
+    constructor(maxSize?: number, ttlMs?: number, cacheType?: CacheType);
+    get(key: string): T | undefined;
+    set(key: string, data: T): void;
+    has(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    getStats(): CacheStats;
+}
+/**
+ * Generate a stable cache key from query options (key order independent).
+ * Uses fast-json-stable-stringify for recursive key sorting.
+ */
+export declare function makeCacheKey(prefix: string, options: object): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/lib/resilience/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/lib/resilience/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;iBAM3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK1D,eAAO,MAAM,YAAY,QAAiF,CAAC;AAE3G,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;EAA+E,CAAC;AAE5G,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,WAAW,CAAC,OAAO,CAAC;IACpD,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,OAAO,SAAqB,EAAE,KAAK,SAAe,EAAE,SAAS,GAAE,SAAqB;IAchG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAY/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAI/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,QAAQ,IAAI,UAAU;CAUvB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/lib/resilience/cache.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { normalizedScoreSchema } from '../core/shared-schemas.js';
+import { LRUCache } from 'lru-cache';
+import stringify from 'fast-json-stable-stringify';
+import { recordCacheHit, recordCacheMiss, recordCacheEviction } from '../observability/metrics.js';
+/**
+ * Cache statistics for monitoring and observability
+ */
+export const cacheStatsSchema = z.object({
+    hits: z.number().int().nonnegative(),
+    misses: z.number().int().nonnegative(),
+    evictions: z.number().int().nonnegative(),
+    size: z.number().int().nonnegative(),
+    hitRate: normalizedScoreSchema,
+});
+/** Default TTL: 60 seconds, configurable via CACHE_TTL_MS env var */
+const DEFAULT_CACHE_TTL_MS = 60_000;
+const parsedTtl = parseInt(process.env.CACHE_TTL_MS || String(DEFAULT_CACHE_TTL_MS), 10);
+export const CACHE_TTL_MS = Number.isFinite(parsedTtl) && parsedTtl > 0 ? parsedTtl : DEFAULT_CACHE_TTL_MS;
+/** Default cache size: 100 entries per instance */
+export const DEFAULT_CACHE_SIZE = 100;
+/**
+ * Valid cache type identifiers for metrics.
+ * Restricts cardinality of cache_type metric label to prevent unbounded growth.
+ */
+export const cacheTypeSchema = z.enum(['traces', 'logs', 'metrics', 'llmEvents', 'evaluations', 'unknown']);
+/**
+ * LRU cache with TTL expiration.
+ *
+ * Backed by lru-cache. Eviction OTel metrics fire only on LRU capacity eviction
+ * (reason === 'evict'), not on TTL expiry or explicit deletes.
+ *
+ * @typeParam T - Type of cached data (typically arrays of query results)
+ */
+export class QueryCache {
+    cache;
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    cacheType;
+    constructor(maxSize = DEFAULT_CACHE_SIZE, ttlMs = CACHE_TTL_MS, cacheType = 'unknown') {
+        this.cacheType = cacheType;
+        this.cache = new LRUCache({
+            max: maxSize,
+            ttl: ttlMs,
+            dispose: (_value, _key, reason) => {
+                if (reason === 'evict') {
+                    this.evictions++;
+                    recordCacheEviction(this.cacheType);
+                }
+            },
+        });
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value === undefined) {
+            this.misses++;
+            recordCacheMiss(this.cacheType);
+        }
+        else {
+            this.hits++;
+            recordCacheHit(this.cacheType);
+        }
+        return value;
+    }
+    set(key, data) {
+        this.cache.set(key, data);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+    getStats() {
+        const total = this.hits + this.misses;
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            evictions: this.evictions,
+            size: this.cache.size,
+            hitRate: total > 0 ? this.hits / total : 0,
+        };
+    }
+}
+/**
+ * Generate a stable cache key from query options (key order independent).
+ * Uses fast-json-stable-stringify for recursive key sorting.
+ */
+export function makeCacheKey(prefix, options) {
+    return `${prefix}:${stringify(options)}`;
+}
+//# sourceMappingURL=cache.js.map

package/dist/lib/resilience/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/lib/resilience/cache.ts"],"names":[],"mappings":"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"}

package/dist/lib/resilience/cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.d.ts","sourceRoot":"","sources":["../../../src/lib/resilience/cache.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/lib/resilience/cache.test.js

@@ -0,0 +1,106 @@
+/**
+ * Tests for QueryCache statistics
+ */
+import { describe, it } from 'vitest';
+import * as assert from 'node:assert';
+import { CACHE_TTL_MS, QueryCache } from './cache.js';
+import { P_VALUE_STRICT, COUNT_FOUR, COUNT_TEN, COUNT_THREE, COUNT_TWENTY, COUNT_TWO, } from '../../test-helpers/test-constants.js';
+describe('QueryCache stats', () => {
+    describe('hit counter', () => {
+        it('increments hits on cache hit', () => {
+            const cache = new QueryCache(COUNT_THREE, CACHE_TTL_MS);
+            cache.set('key1', 'value1');
+            cache.get('key1');
+            cache.get('key1');
+            const stats = cache.getStats();
+            assert.strictEqual(stats.hits, COUNT_TWO);
+            assert.strictEqual(stats.misses, 0);
+        });
+    });
+    describe('miss counter', () => {
+        it('increments misses on cache miss', () => {
+            const cache = new QueryCache(COUNT_THREE, CACHE_TTL_MS);
+            cache.get('nonexistent');
+            cache.get('also-nonexistent');
+            const stats = cache.getStats();
+            assert.strictEqual(stats.hits, 0);
+            assert.strictEqual(stats.misses, COUNT_TWO);
+        });
+        it('increments misses on TTL expiration', async () => {
+            // Use a very short TTL for testing
+            const cache = new QueryCache(COUNT_THREE, COUNT_TEN); // 10ms TTL
+            cache.set('key1', 'value1');
+            // Wait for TTL to expire
+            await new Promise(resolve => setTimeout(resolve, COUNT_TWENTY));
+            const result = cache.get('key1');
+            assert.strictEqual(result, undefined);
+            const stats = cache.getStats();
+            assert.strictEqual(stats.hits, 0);
+            assert.strictEqual(stats.misses, 1);
+        });
+    });
+    describe('eviction counter', () => {
+        it('increments evictions when cache is full', () => {
+            const cache = new QueryCache(COUNT_THREE, CACHE_TTL_MS); // maxSize=3
+            cache.set('key1', 'value1');
+            cache.set('key2', 'value2');
+            cache.set('key3', 'value3');
+            // Cache is now full
+            cache.set('key4', 'value4'); // Should evict key1
+            cache.set('key5', 'value5'); // Should evict key2
+            const stats = cache.getStats();
+            assert.strictEqual(stats.evictions, COUNT_TWO);
+            assert.strictEqual(stats.size, COUNT_THREE);
+        });
+        it('does not increment evictions when updating existing key', () => {
+            const cache = new QueryCache(COUNT_THREE, CACHE_TTL_MS);
+            cache.set('key1', 'value1');
+            cache.set('key2', 'value2');
+            cache.set('key3', 'value3');
+            // Update existing key - should not evict
+            cache.set('key1', 'updated-value1');
+            const stats = cache.getStats();
+            assert.strictEqual(stats.evictions, 0);
+            assert.strictEqual(stats.size, COUNT_THREE);
+        });
+    });
+    describe('getStats', () => {
+        it('returns correct values after mixed operations', () => {
+            const cache = new QueryCache(COUNT_THREE, CACHE_TTL_MS);
+            cache.set('key1', 'value1');
+            cache.set('key2', 'value2');
+            cache.get('key1'); // hit
+            cache.get('key2'); // hit
+            cache.get('key3'); // miss
+            cache.set('key3', 'value3');
+            cache.set('key4', 'value4'); // eviction (key1 is oldest after gets moved it)
+            const stats = cache.getStats();
+            assert.strictEqual(stats.hits, COUNT_TWO);
+            assert.strictEqual(stats.misses, 1);
+            assert.strictEqual(stats.evictions, 1);
+            assert.strictEqual(stats.size, COUNT_THREE);
+            // hitRate = 2 / (2 + 1) = 0.666...
+            assert.ok(Math.abs(stats.hitRate - (COUNT_TWO / COUNT_THREE)) < P_VALUE_STRICT);
+        });
+        it('returns hitRate of 0 when no requests', () => {
+            const cache = new QueryCache(COUNT_THREE, CACHE_TTL_MS);
+            const stats = cache.getStats();
+            assert.strictEqual(stats.hitRate, 0);
+            assert.strictEqual(stats.hits, 0);
+            assert.strictEqual(stats.misses, 0);
+        });
+    });
+    describe('hitRate calculation', () => {
+        it('calculates hitRate correctly', () => {
+            const cache = new QueryCache(COUNT_TEN, CACHE_TTL_MS);
+            cache.set('key1', 'value1');
+            cache.get('key1'); // hit
+            cache.get('key1'); // hit
+            cache.get('key1'); // hit
+            cache.get('nonexistent'); // miss
+            const stats = cache.getStats();
+            assert.strictEqual(stats.hitRate, COUNT_THREE / COUNT_FOUR); // 3 hits / 4 total
+        });
+    });
+});
+//# sourceMappingURL=cache.test.js.map

package/dist/lib/resilience/cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.js","sourceRoot":"","sources":["../../../src/lib/resilience/cache.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/resilience/circuit-breaker.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Circuit breaker pattern implementation for resilient I/O operations
+ *
+ * Prevents cascading failures by temporarily stopping requests to a failing service.
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Service failing, requests are rejected immediately
+ * - HALF-OPEN: Testing if service recovered, allows one request through
+ *
+ * ## Thread Safety
+ * This implementation is safe for Node.js single-threaded event loop.
+ * The half-open slot claim uses synchronous check-and-set which is atomic
+ * within a single event loop tick (no await/yield between check and set).
+ * NOT safe for worker_threads without additional synchronization.
+ *
+ * ## OTel Metrics (P3-2)
+ * When OTEL_ENABLED=true, state transitions are exported as OTel metrics:
+ * - obs_toolkit.circuit_breaker.state: State value (0=closed, 1=half-open, 2=open)
+ */
+import { z } from 'zod';
+/**
+ * Check whether an error represents a rate-limit / throttling response.
+ * Useful as a `failureFilter` to exempt transient 429s from tripping the breaker.
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+export declare const circuitStateSchema: z.ZodEnum<{
+    open: "open";
+    closed: "closed";
+    "half-open": "half-open";
+}>;
+export type CircuitState = z.infer<typeof circuitStateSchema>;
+export declare const circuitBreakerOptionsSchema: z.ZodObject<{
+    maxFailures: z.ZodOptional<z.ZodNumber>;
+    resetMs: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Circuit breaker options.
+ * `failureFilter` is a function and cannot be represented in a Zod schema,
+ * so the full options type extends the schema-derived type.
+ */
+export type CircuitBreakerOptions = z.infer<typeof circuitBreakerOptionsSchema> & {
+    /**
+     * Optional predicate applied in `evaluate()`: return `false` to exempt
+     * an error from counting as a failure (e.g. rate-limit 429s).
+     * Default: all errors count.
+     */
+    failureFilter?: (error: unknown) => boolean;
+};
+/**
+ * Circuit breaker for I/O operations (API calls, file operations, LLM judge calls)
+ *
+ * Manual usage:
+ * ```ts
+ * const breaker = new CircuitBreaker({ name: 'local-file' });
+ *
+ * if (!breaker.canRequest()) {
+ *   return []; // Circuit is open, fail fast
+ * }
+ *
+ * try {
+ *   const result = await riskyOperation();
+ *   breaker.recordSuccess();
+ *   return result;
+ * } catch (error) {
+ *   breaker.recordFailure();
+ *   throw error;
+ * }
+ * ```
+ *
+ * Wrapped usage:
+ * ```ts
+ * const breaker = new CircuitBreaker({
+ *   name: 'judge',
+ *   failureFilter: (e) => !isRateLimitError(e),
+ * });
+ * const result = await breaker.evaluate(() => callLLM(), () => fallbackScore());
+ * ```
+ */
+export declare class CircuitBreaker {
+    private failures;
+    private lastFailure;
+    private state;
+    /** Prevents multiple concurrent requests during half-open state */
+    private halfOpenRequestInFlight;
+    private openCount;
+    private resetCount;
+    private readonly maxFailures;
+    private readonly resetMs;
+    private readonly name;
+    private readonly failureFilter;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * Atomically claim the half-open slot for testing recovery.
+     * Returns true if this caller won the slot, false if another caller already has it.
+     *
+     * Thread safety: This is atomic in Node.js single-threaded event loop because
+     * there's no await/yield between the check and set operations.
+     */
+    private claimHalfOpenSlot;
+    /**
+     * Check if a request can proceed
+     * Returns false if circuit is open (and not ready to retry)
+     * In half-open state, only one request is allowed through at a time
+     */
+    canRequest(): boolean;
+    /**
+     * Record a successful operation
+     * Closes the circuit if in half-open state
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed operation
+     * Opens the circuit after maxFailures consecutive failures
+     */
+    recordFailure(): void;
+    /**
+     * Execute an async function with circuit breaker protection.
+     * Applies `failureFilter` when set — filtered errors are rethrown but not counted.
+     * Delegates to `fallback` when the circuit is open, or throws if no fallback.
+     */
+    evaluate<T>(fn: () => Promise<T>, fallback?: () => Promise<T>): Promise<T>;
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Get current failure count
+     */
+    getFailureCount(): number;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        openCount: number;
+        resetCount: number;
+    };
+    /**
+     * Reset circuit to closed state (useful for testing)
+     */
+    reset(): void;
+    /**
+     * Check if a half-open request is in flight (for testing)
+     */
+    isHalfOpenRequestInFlight(): boolean;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/lib/resilience/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/lib/resilience/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwBxB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAwBxD;AAED,eAAO,MAAM,kBAAkB;;;;EAA0C,CAAC;AAE1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,2BAA2B;;;;iBAOtC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,GAAG;IAChF;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC7C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,KAAK,CAA0B;IACvC,mEAAmE;IACnE,OAAO,CAAC,uBAAuB,CAAS;IACxC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;gBAE9D,OAAO,GAAE,qBAA0B;IAO/C;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IASzB;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAqBrB;;;OAGG;IACH,aAAa,IAAI,IAAI;IAarB;;;OAGG;IACH,aAAa,IAAI,IAAI;IAarB;;;;OAIG;IACG,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqBhF;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,QAAQ,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAIrD;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,yBAAyB,IAAI,OAAO;CAGrC"}