@forgecharts/sdk 1.1.23 → 1.1.28

package/dist/__tests__/backwardCompatibility.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Backward compatibility — unit tests
+ *
+ * Verifies that the introduction of licensing, unmanaged mode, and managed
+ * foundations does NOT break the existing SDK contract:
+ *
+ *   1. All expected exports exist and have the correct shape/type
+ *   2. CandleEngine works unchanged (no side-effects from new code)
+ *   3. Default mode is unmanaged (safe default — nothing breaks by default)
+ *   4. The RapidAPI datafeed path is unaffected (DatafeedConnector still exports)
+ *   5. New modules export correctly from the package root (index.ts)
+ */
+export {};
+//# sourceMappingURL=backwardCompatibility.test.d.ts.map

package/dist/__tests__/backwardCompatibility.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backwardCompatibility.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/backwardCompatibility.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/backwardCompatibility.test.js

@@ -0,0 +1,159 @@
+/**
+ * Backward compatibility — unit tests
+ *
+ * Verifies that the introduction of licensing, unmanaged mode, and managed
+ * foundations does NOT break the existing SDK contract:
+ *
+ *   1. All expected exports exist and have the correct shape/type
+ *   2. CandleEngine works unchanged (no side-effects from new code)
+ *   3. Default mode is unmanaged (safe default — nothing breaks by default)
+ *   4. The RapidAPI datafeed path is unaffected (DatafeedConnector still exports)
+ *   5. New modules export correctly from the package root (index.ts)
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { LicenseManager } from '../licensing/LicenseManager';
+import { CandleEngine } from '../engine/CandleEngine';
+// ─── License cleanup ──────────────────────────────────────────────────────────
+beforeEach(() => {
+    LicenseManager.getInstance().clear();
+});
+// ─── Existing exports remain intact ──────────────────────────────────────────
+describe('Backward compatibility — SDK exports', () => {
+    it('CandleEngine is exported', async () => {
+        const mod = await import('../engine/CandleEngine');
+        expect(mod.CandleEngine).toBeDefined();
+        expect(typeof mod.CandleEngine).toBe('function');
+    });
+    it('timeframeToMs and getBucketStart are exported', async () => {
+        const mod = await import('../engine/timeframeUtils');
+        expect(typeof mod.timeframeToMs).toBe('function');
+        expect(typeof mod.getBucketStart).toBe('function');
+    });
+    it('LicenseManager is exported', async () => {
+        const mod = await import('../licensing/LicenseManager');
+        expect(mod.LicenseManager).toBeDefined();
+    });
+    it('ChartRuntimeResolver is exported', async () => {
+        const mod = await import('../licensing/ChartRuntimeResolver');
+        expect(mod.ChartRuntimeResolver).toBeDefined();
+        expect(typeof mod.isManagedMode).toBe('function');
+        expect(typeof mod.isUnmanagedMode).toBe('function');
+        expect(typeof mod.canRenderOrderEntry).toBe('function');
+        expect(typeof mod.canRenderManagedTradingControls).toBe('function');
+        expect(typeof mod.canRenderExternalOverlayOnlyMode).toBe('function');
+    });
+    it('TradingOverlayStore is exported', async () => {
+        const mod = await import('../trading/TradingOverlayStore');
+        expect(mod.TradingOverlayStore).toBeDefined();
+        expect(typeof mod.TradingOverlayStore).toBe('function');
+    });
+    it('UnmanagedIngestion is exported', async () => {
+        const mod = await import('../trading/UnmanagedIngestion');
+        expect(mod.UnmanagedIngestion).toBeDefined();
+        expect(typeof mod.UnmanagedIngestion).toBe('function');
+    });
+    it('ManagedTradingController is exported', async () => {
+        const mod = await import('../trading/managed/ManagedTradingController');
+        expect(mod.ManagedTradingController).toBeDefined();
+        expect(typeof mod.ManagedTradingController).toBe('function');
+    });
+    it('DatafeedConnector is exported (default RapidAPI path intact)', async () => {
+        const mod = await import('../datafeed/DatafeedConnector');
+        expect(mod.DatafeedConnector).toBeDefined();
+        expect(typeof mod.DatafeedConnector).toBe('function');
+    });
+});
+// ─── CandleEngine unchanged ───────────────────────────────────────────────────
+describe('Backward compatibility — CandleEngine still works with no license', () => {
+    // T0 = 2024-07-03T10:00:00Z in seconds
+    const T0 = 1_719_997_200;
+    const T1 = T0 + 60;
+    function raw(time, close) {
+        return { time, open: 100, high: close + 5, low: close - 5, close, volume: 1 };
+    }
+    it('can be instantiated and used without any license', () => {
+        const engine = new CandleEngine();
+        expect(() => engine.initialize([], '1m')).not.toThrow();
+    });
+    it('basic OHLCV update works — no licensing side-effects', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(raw(T0, 100));
+        engine.applyLiveUpdate(raw(T0, 105));
+        engine.applyLiveUpdate(raw(T1, 110));
+        expect(engine.getBars()).toHaveLength(2);
+        expect(engine.getBars()[0].close).toBe(105);
+        expect(engine.getBars()[1].close).toBe(110);
+    });
+    it('initialize() resets state completely', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], '1m');
+        engine.applyLiveUpdate(raw(T0, 100));
+        engine.initialize([], '5m');
+        expect(engine.getBars()).toHaveLength(0);
+    });
+});
+// ─── Default license mode — safe unmanaged defaults ──────────────────────────
+describe('Backward compatibility — default mode is unmanaged', () => {
+    it('LicenseManager.getMode() returns unmanaged with no license', () => {
+        const lm = LicenseManager.getInstance();
+        expect(lm.getMode()).toBe('unmanaged');
+        expect(lm.getLicense()).toBeNull();
+    });
+    it('isUnmanagedMode() is true with no license', async () => {
+        const { isUnmanagedMode } = await import('../licensing/ChartRuntimeResolver');
+        expect(isUnmanagedMode()).toBe(true);
+    });
+    it('isManagedMode() is false with no license', async () => {
+        const { isManagedMode } = await import('../licensing/ChartRuntimeResolver');
+        expect(isManagedMode()).toBe(false);
+    });
+    it('canRenderCandles() is true with no license', async () => {
+        const { canRenderCandles } = await import('../licensing/ChartRuntimeResolver');
+        expect(canRenderCandles()).toBe(true);
+    });
+    it('canRenderorderEntry() is false with no license', async () => {
+        const { canRenderOrderEntry } = await import('../licensing/ChartRuntimeResolver');
+        expect(canRenderOrderEntry()).toBe(false);
+    });
+    it('canRenderManagedTradingControls() is false with no license', async () => {
+        const { canRenderManagedTradingControls } = await import('../licensing/ChartRuntimeResolver');
+        expect(canRenderManagedTradingControls()).toBe(false);
+    });
+});
+// ─── Unmanaged ingestion is additive — does not replace the existing datafeed ─
+describe('Backward compatibility — unmanaged ingestion is opt-in and additive', () => {
+    it('UnmanagedIngestion can be instantiated without affecting CandleEngine state', async () => {
+        const standaloneEngine = new CandleEngine();
+        standaloneEngine.initialize([], '1m');
+        // Creating an UnmanagedIngestion constructs its OWN internal CandleEngine
+        const { UnmanagedIngestion } = await import('../trading/UnmanagedIngestion');
+        const ing = new UnmanagedIngestion('1m');
+        // The standalone engine is still clean
+        expect(standaloneEngine.getBars()).toHaveLength(0);
+        // The ingestion engine also starts empty
+        expect(ing.getBars()).toHaveLength(0);
+    });
+    it('DatafeedConnector can still be constructed independently', async () => {
+        const { DatafeedConnector } = await import('../datafeed/DatafeedConnector');
+        const mockDatafeed = {
+            getHistoricalBars: () => Promise.resolve({ bars: [], noData: true }),
+            subscribeBars: () => { },
+            unsubscribeBars: () => { },
+        };
+        const mockSeries = {
+            setData: () => { },
+            update: () => { },
+            data: () => [],
+            applyOptions: () => { },
+            options: () => ({}),
+        };
+        const mockCallbacks = {
+            onLoading: () => { },
+            onLoaded: () => { },
+            onError: () => { },
+        };
+        expect(() => new DatafeedConnector(mockDatafeed, mockSeries, mockCallbacks)).not.toThrow();
+    });
+});
+//# sourceMappingURL=backwardCompatibility.test.js.map

package/dist/__tests__/backwardCompatibility.test.js.map

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

package/dist/__tests__/candleInvariant.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Candle Invariant Tests
+ *
+ * Verifies that the invariant guards in `candleInvariants.ts` fire correctly,
+ * and that `CandleEngine.applyLiveUpdate` maintains all invariants during
+ * normal operation (no warnings) and surfaces violations during abnormal
+ * conditions (mocked guard paths).
+ *
+ * Test categories:
+ *   1. assertOhlcRelationships — each OHLC violation is detected independently
+ *   2. assertBucketAlignment — misaligned timestamps are caught
+ *   3. assertNotFinalized — mutating a closed bar triggers the guard
+ *   4. assertOpenImmutability — open-price overwrite is detected
+ *   5. assertNoDuplicateAppend — same-bucket spurious append is detected
+ *   6. assertFinalizedUnchanged — new-bucket finalisation is verified
+ *   7. CandleEngine integration — no spurious warnings during correct operation
+ *   8. barDivergenceCheck — compareSources and formatReport
+ */
+export {};
+//# sourceMappingURL=candleInvariant.test.d.ts.map

package/dist/__tests__/candleInvariant.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candleInvariant.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/candleInvariant.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/__tests__/candleInvariant.test.js

@@ -0,0 +1,415 @@
+/**
+ * Candle Invariant Tests
+ *
+ * Verifies that the invariant guards in `candleInvariants.ts` fire correctly,
+ * and that `CandleEngine.applyLiveUpdate` maintains all invariants during
+ * normal operation (no warnings) and surfaces violations during abnormal
+ * conditions (mocked guard paths).
+ *
+ * Test categories:
+ *   1. assertOhlcRelationships — each OHLC violation is detected independently
+ *   2. assertBucketAlignment — misaligned timestamps are caught
+ *   3. assertNotFinalized — mutating a closed bar triggers the guard
+ *   4. assertOpenImmutability — open-price overwrite is detected
+ *   5. assertNoDuplicateAppend — same-bucket spurious append is detected
+ *   6. assertFinalizedUnchanged — new-bucket finalisation is verified
+ *   7. CandleEngine integration — no spurious warnings during correct operation
+ *   8. barDivergenceCheck — compareSources and formatReport
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { assertOhlcRelationships, assertBucketAlignment, assertNotFinalized, assertOpenImmutability, assertNoDuplicateAppend, assertFinalizedUnchanged, _setReporter, _resetReporter, } from '../engine/candleInvariants';
+import { CandleEngine } from '../engine/CandleEngine';
+import { compareSources, checkAllSources, formatReport, } from '../tools/barDivergenceCheck';
+// ─── Reporter harness ─────────────────────────────────────────────────────────
+/**
+ * During tests we capture invariant violation messages instead of printing
+ * them to console.  This lets us assert on the exact message content.
+ */
+let violations = [];
+beforeEach(() => {
+    violations = [];
+    _setReporter((msg) => violations.push(msg));
+});
+afterEach(() => {
+    _resetReporter();
+});
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+/** Build a valid, closed CandleBar. */
+function validBar(overrides = {}) {
+    return {
+        timeMs: 60_000,
+        time: 60,
+        open: 100,
+        high: 110,
+        low: 90,
+        close: 105,
+        volume: 1,
+        isClosed: true,
+        ...overrides,
+    };
+}
+/** Unix seconds helper. */
+const sec = (iso) => new Date(iso).getTime() / 1000;
+/** Build a minimal RawOHLCV tick for the engine. */
+function tick(timeSec, open = 100, high = 110, low = 90, close = 105, volume = 1) {
+    return { time: timeSec, open, high, low, close, volume };
+}
+// ─── 1. assertOhlcRelationships ───────────────────────────────────────────────
+describe('assertOhlcRelationships', () => {
+    it('passes for a valid OHLC bar with no violations', () => {
+        assertOhlcRelationships(validBar(), 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('detects high < open', () => {
+        assertOhlcRelationships(validBar({ open: 120, high: 110 }), 'ctx');
+        expect(violations.some(v => v.includes('high') && v.includes('open'))).toBe(true);
+    });
+    it('detects high < close', () => {
+        assertOhlcRelationships(validBar({ close: 120, high: 110 }), 'ctx');
+        expect(violations.some(v => v.includes('high') && v.includes('close'))).toBe(true);
+    });
+    it('detects high < low', () => {
+        assertOhlcRelationships(validBar({ high: 80, low: 90 }), 'ctx');
+        expect(violations.some(v => v.includes('high') && v.includes('low'))).toBe(true);
+    });
+    it('detects low > open', () => {
+        assertOhlcRelationships(validBar({ open: 80, low: 90 }), 'ctx');
+        expect(violations.some(v => v.includes('low') && v.includes('open'))).toBe(true);
+    });
+    it('detects low > close', () => {
+        assertOhlcRelationships(validBar({ close: 80, low: 90 }), 'ctx');
+        expect(violations.some(v => v.includes('low') && v.includes('close'))).toBe(true);
+    });
+    it('open === high === low === close is valid (doji candle)', () => {
+        assertOhlcRelationships(validBar({ open: 100, high: 100, low: 100, close: 100 }), 'ctx');
+        expect(violations).toHaveLength(0);
+    });
+    it('includes context and timeMs in violation message', () => {
+        assertOhlcRelationships(validBar({ open: 120, high: 110, timeMs: 99_000 }), 'myCtx');
+        expect(violations[0]).toContain('[CANDLE_INVARIANT]');
+        expect(violations[0]).toContain('myCtx');
+        expect(violations[0]).toContain('99000');
+    });
+});
+// ─── 2. assertBucketAlignment ─────────────────────────────────────────────────
+describe('assertBucketAlignment', () => {
+    it('passes when timeMs is exactly on the 1m boundary', () => {
+        // 60_000 ms = exactly 1 minute from epoch — valid 1m bucket start
+        assertBucketAlignment(validBar({ timeMs: 60_000, time: 60 }), '1m', 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('detects timeMs not on a 1m boundary', () => {
+        // 62_500 ms is NOT on a 60_000-ms boundary
+        assertBucketAlignment(validBar({ timeMs: 62_500, time: 62 }), '1m', 'test');
+        expect(violations.length).toBeGreaterThan(0);
+        expect(violations[0]).toContain('timeMs');
+    });
+    it('passes for 1h boundary', () => {
+        const hourStart = new Date('2025-03-09T14:00:00Z').getTime();
+        assertBucketAlignment(validBar({ timeMs: hourStart, time: hourStart / 1000 }), '1h', 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('detects misaligned 1h timestamp (30 min off)', () => {
+        const thirtyMin = new Date('2025-03-09T14:30:00Z').getTime();
+        assertBucketAlignment(validBar({ timeMs: thirtyMin, time: thirtyMin / 1000 }), '1h', 'test');
+        expect(violations.length).toBeGreaterThan(0);
+    });
+    it('passes for a Monday 00:00 UTC timestamp with 1w', () => {
+        const monday = new Date('2025-03-03T00:00:00Z').getTime();
+        assertBucketAlignment(validBar({ timeMs: monday, time: monday / 1000 }), '1w', 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('detects misaligned 1w timestamp (mid-week)', () => {
+        const wednesday = new Date('2025-03-05T12:00:00Z').getTime();
+        assertBucketAlignment(validBar({ timeMs: wednesday, time: wednesday / 1000 }), '1w', 'test');
+        expect(violations.length).toBeGreaterThan(0);
+    });
+    it('passes for first-of-month timestamp with 1M', () => {
+        const monthStart = new Date('2025-03-01T00:00:00Z').getTime();
+        assertBucketAlignment(validBar({ timeMs: monthStart, time: monthStart / 1000 }), '1M', 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('detects mid-month timestamp with 1M', () => {
+        const midMonth = new Date('2025-03-15T00:00:00Z').getTime();
+        assertBucketAlignment(validBar({ timeMs: midMonth, time: midMonth / 1000 }), '1M', 'test');
+        expect(violations.length).toBeGreaterThan(0);
+    });
+});
+// ─── 3. assertNotFinalized ────────────────────────────────────────────────────
+describe('assertNotFinalized', () => {
+    it('passes for an open (live) candle', () => {
+        assertNotFinalized(validBar({ isClosed: false }), 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('fires for a closed candle', () => {
+        assertNotFinalized(validBar({ isClosed: true }), 'test');
+        expect(violations.length).toBeGreaterThan(0);
+        expect(violations[0]).toContain('finalized');
+    });
+    it('violation message contains context and timeMs', () => {
+        assertNotFinalized(validBar({ isClosed: true, timeMs: 180_000 }), 'liveUpdate');
+        expect(violations[0]).toContain('liveUpdate');
+        expect(violations[0]).toContain('180000');
+    });
+});
+// ─── 4. assertOpenImmutability ────────────────────────────────────────────────
+describe('assertOpenImmutability', () => {
+    it('passes when open is unchanged', () => {
+        const bar = validBar({ open: 100 });
+        assertOpenImmutability(100, bar, 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('fires when open changed', () => {
+        const bar = validBar({ open: 200 });
+        assertOpenImmutability(100, bar, 'ctx');
+        expect(violations.length).toBeGreaterThan(0);
+        expect(violations[0]).toContain('open');
+    });
+    it('violation message shows previous and new open', () => {
+        const bar = validBar({ open: 200, timeMs: 120_000 });
+        assertOpenImmutability(100, bar, 'ctx');
+        expect(violations[0]).toContain('100');
+        expect(violations[0]).toContain('200');
+        expect(violations[0]).toContain('120000');
+    });
+});
+// ─── 5. assertNoDuplicateAppend ───────────────────────────────────────────────
+describe('assertNoDuplicateAppend', () => {
+    it('passes when count is unchanged', () => {
+        assertNoDuplicateAppend(5, 5, 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('fires when count increased (spurious append)', () => {
+        assertNoDuplicateAppend(5, 6, 'ctx');
+        expect(violations.length).toBeGreaterThan(0);
+        expect(violations[0]).toContain('same-bucket');
+    });
+});
+// ─── 6. assertFinalizedUnchanged ─────────────────────────────────────────────
+describe('assertFinalizedUnchanged', () => {
+    it('passes when the previous bar is now isClosed', () => {
+        const prev = validBar({ timeMs: 60_000, isClosed: false });
+        const current = [
+            { ...prev, isClosed: true },
+            validBar({ timeMs: 120_000, isClosed: false }),
+        ];
+        assertFinalizedUnchanged(prev, current, 'test');
+        expect(violations).toHaveLength(0);
+    });
+    it('fires when the previous bar is still open after a new-bucket append', () => {
+        const prev = validBar({ timeMs: 60_000, isClosed: false });
+        const current = [
+            { ...prev, isClosed: false }, // not closed — violation
+            validBar({ timeMs: 120_000, isClosed: false }),
+        ];
+        assertFinalizedUnchanged(prev, current, 'test');
+        expect(violations.length).toBeGreaterThan(0);
+        expect(violations[0]).toContain('isClosed');
+    });
+    it('passes when the bar was removed (e.g. after a merge)', () => {
+        const prev = validBar({ timeMs: 60_000 });
+        // prev is not in `current` at all — should not fire
+        assertFinalizedUnchanged(prev, [], 'test');
+        expect(violations).toHaveLength(0);
+    });
+});
+// ─── 7. CandleEngine integration — no spurious warnings ──────────────────────
+describe('CandleEngine integration — clean operation produces no violations', () => {
+    const TF = '1m';
+    const T0 = sec('2025-03-09T14:00:00Z');
+    const T1 = sec('2025-03-09T14:01:00Z');
+    const T2 = sec('2025-03-09T14:02:00Z');
+    it('single tick produces no invariant violations', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], TF);
+        engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+        expect(violations).toHaveLength(0);
+    });
+    it('same-bucket updates produce no violations', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], TF);
+        engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+        engine.applyLiveUpdate(tick(T0 + 30, 100, 120, 85, 115));
+        engine.applyLiveUpdate(tick(T0 + 45, 100, 120, 85, 112));
+        expect(violations).toHaveLength(0);
+    });
+    it('new-bucket append produces no violations', () => {
+        const engine = new CandleEngine();
+        engine.initialize([], TF);
+        engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+        engine.applyLiveUpdate(tick(T1, 106, 120, 100, 115));
+        engine.applyLiveUpdate(tick(T2, 116, 125, 110, 120));
+        expect(violations).toHaveLength(0);
+    });
+    it('backfillGap produces no violations', () => {
+        const T4 = sec('2025-03-09T14:04:00Z');
+        const engine = new CandleEngine();
+        engine.initialize([tick(T0, 100, 110, 90, 105)], TF);
+        engine.applyLiveUpdate(tick(T4, 130, 140, 120, 135));
+        engine.backfillGap([
+            tick(T1, 106, 115, 100, 112),
+            tick(T2, 112, 118, 105, 116),
+        ]);
+        expect(violations).toHaveLength(0);
+    });
+    it('handleReconnect produces no violations', () => {
+        const engine = new CandleEngine();
+        engine.initialize([
+            tick(T0, 100, 110, 90, 105),
+            tick(T1, 106, 112, 100, 110),
+        ], TF);
+        engine.handleReconnect([
+            tick(T0, 100, 115, 88, 112),
+            tick(T1, 106, 118, 96, 115),
+        ]);
+        expect(violations).toHaveLength(0);
+    });
+    it('weekly timeframe: calendar-aligned ticks produce no violations', () => {
+        const MONDAY = sec('2025-03-03T00:00:00Z');
+        const WEDNESDAY = sec('2025-03-05T12:00:00Z');
+        const FRIDAY = sec('2025-03-07T18:00:00Z');
+        const engine = new CandleEngine();
+        engine.initialize([], '1w');
+        engine.applyLiveUpdate(tick(MONDAY, 40000, 42000, 39000, 41000));
+        // Wed and Fri are in the same 1w bucket — updates only
+        engine.applyLiveUpdate(tick(WEDNESDAY, 40000, 45000, 38000, 44000));
+        engine.applyLiveUpdate(tick(FRIDAY, 40000, 46000, 37500, 43000));
+        expect(violations).toHaveLength(0);
+        expect(engine.getBars().length).toBe(1); // still the same weekly candle
+    });
+    it('monthly timeframe: calendar-aligned ticks produce no violations', () => {
+        const MAR_01 = sec('2025-03-01T00:00:00Z');
+        const MAR_15 = sec('2025-03-15T12:00:00Z');
+        const APR_01 = sec('2025-04-01T00:00:00Z');
+        const engine = new CandleEngine();
+        engine.initialize([], '1M');
+        engine.applyLiveUpdate(tick(MAR_01, 40000, 42000, 39000, 41000));
+        engine.applyLiveUpdate(tick(MAR_15, 40000, 45000, 38000, 44000)); // same month
+        engine.applyLiveUpdate(tick(APR_01, 44000, 46000, 43000, 45000)); // new month
+        expect(violations).toHaveLength(0);
+        expect(engine.getBars().length).toBe(2); // March + April
+    });
+});
+// ─── 8. barDivergenceCheck ────────────────────────────────────────────────────
+describe('compareSources — identical sources', () => {
+    const BARS = {
+        source: 'provider',
+        bars: [
+            { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+            { time: 1_000_060, open: 105, high: 115, low: 100, close: 112 },
+            { time: 1_000_120, open: 112, high: 120, low: 108, close: 118 },
+        ],
+    };
+    const DB_BARS = { source: 'database', bars: BARS.bars };
+    it('returns diverged=false when both sources are identical', () => {
+        const report = compareSources(BARS, DB_BARS, '1m', 'BTC', 1_000_000, 1_000_180);
+        expect(report.diverged).toBe(false);
+        expect(report.totalMismatches).toBe(0);
+        expect(report.firstMismatch).toBeNull();
+    });
+    it('correct source counts', () => {
+        const report = compareSources(BARS, DB_BARS, '1m', 'BTC', 1_000_000, 1_000_180);
+        expect(report.sourceACount).toBe(3);
+        expect(report.sourceBCount).toBe(3);
+    });
+});
+describe('compareSources — OHLC divergence', () => {
+    it('detects first high mismatch and reports field name', () => {
+        const provider = {
+            source: 'provider',
+            bars: [
+                { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+                { time: 1_000_060, open: 105, high: 115, low: 100, close: 112 },
+            ],
+        };
+        const db = {
+            source: 'database',
+            bars: [
+                { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+                { time: 1_000_060, open: 105, high: 999, low: 100, close: 112 }, // high differs
+            ],
+        };
+        const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_120);
+        expect(report.diverged).toBe(true);
+        expect(report.firstMismatch).not.toBeNull();
+        expect(report.firstMismatch.time).toBe(1_000_060);
+        expect(report.firstMismatch.differences.some(d => d.field === 'high')).toBe(true);
+    });
+    it('detects missing bar in one source', () => {
+        const provider = {
+            source: 'provider',
+            bars: [
+                { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+                { time: 1_000_060, open: 105, high: 115, low: 100, close: 112 },
+            ],
+        };
+        const db = {
+            source: 'database',
+            bars: [
+                { time: 1_000_000, open: 100, high: 110, low: 90, close: 105 },
+                // 1_000_060 is missing
+            ],
+        };
+        const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_120);
+        expect(report.diverged).toBe(true);
+        expect(report.firstMismatch.time).toBe(1_000_060);
+        expect(report.firstMismatch.notes.some(n => n.includes('missing'))).toBe(true);
+    });
+    it('reports first mismatch in time order even if later mismatches exist', () => {
+        const provider = {
+            source: 'provider',
+            bars: [
+                { time: 1_000_000, open: 100, high: 200, low: 90, close: 150 }, // high differs
+                { time: 1_000_060, open: 105, high: 300, low: 100, close: 200 }, // high also differs
+            ],
+        };
+        const db = {
+            source: 'database',
+            bars: [
+                { time: 1_000_000, open: 100, high: 110, low: 90, close: 150 },
+                { time: 1_000_060, open: 105, high: 115, low: 100, close: 200 },
+            ],
+        };
+        const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_120);
+        expect(report.firstMismatch.time).toBe(1_000_000); // oldest first
+        expect(report.totalMismatches).toBe(2);
+    });
+});
+describe('checkAllSources', () => {
+    it('produces N*(N-1)/2 pairwise reports', () => {
+        const sources = [
+            { source: 'provider', bars: [] },
+            { source: 'database', bars: [] },
+            { source: 'sdk', bars: [] },
+        ];
+        const reports = checkAllSources(sources, 'BTC', '1h', 0, 100_000);
+        expect(reports.length).toBe(3); // C(3,2) = 3
+    });
+});
+describe('formatReport', () => {
+    it('includes IDENTICAL when no divergence', () => {
+        const bars = {
+            source: 'provider',
+            bars: [{ time: 1_000_000, open: 100, high: 110, low: 90, close: 105 }],
+        };
+        const report = compareSources(bars, { source: 'database', bars: bars.bars }, '1m', 'BTC', 1_000_000, 1_000_060);
+        const text = formatReport(report);
+        expect(text).toContain('IDENTICAL');
+    });
+    it('includes DIVERGED and mismatch details when sources differ', () => {
+        const provider = {
+            source: 'provider',
+            bars: [{ time: 1_000_000, open: 100, high: 999, low: 90, close: 105 }],
+        };
+        const db = {
+            source: 'database',
+            bars: [{ time: 1_000_000, open: 100, high: 110, low: 90, close: 105 }],
+        };
+        const report = compareSources(provider, db, '1m', 'BTC', 1_000_000, 1_000_060);
+        const text = formatReport(report);
+        expect(text).toContain('DIVERGED');
+        expect(text).toContain('1000000'); // time
+        expect(text).toContain('high');
+    });
+});
+//# sourceMappingURL=candleInvariant.test.js.map