@forgecharts/sdk 1.1.23 → 1.1.28

package/src/__tests__/candleInvariant.test.ts

@@ -1,500 +0,0 @@
-/**
- * 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, vi } from 'vitest';
-import {
-  assertOhlcRelationships,
-  assertBucketAlignment,
-  assertNotFinalized,
-  assertOpenImmutability,
-  assertNoDuplicateAppend,
-  assertFinalizedUnchanged,
-  _setReporter,
-  _resetReporter,
-} from '../engine/candleInvariants';
-import type { CandleBar } from '../engine/CandleEngine';
-import { CandleEngine } from '../engine/CandleEngine';
-import type { RawOHLCV } from '../engine/CandleEngine';
-import {
-  compareSources,
-  checkAllSources,
-  formatReport,
-} from '../tools/barDivergenceCheck';
-import type { SourceBars } 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: string[] = [];
-
-beforeEach(() => {
-  violations = [];
-  _setReporter((msg) => violations.push(msg));
-});
-
-afterEach(() => {
-  _resetReporter();
-});
-
-// ─── Fixtures ─────────────────────────────────────────────────────────────────
-
-/** Build a valid, closed CandleBar. */
-function validBar(overrides: Partial<CandleBar> = {}): CandleBar {
-  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: string): number => new Date(iso).getTime() / 1000;
-
-/** Build a minimal RawOHLCV tick for the engine. */
-function tick(
-  timeSec: number,
-  open = 100, high = 110, low = 90, close = 105, volume = 1,
-): RawOHLCV {
-  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: CandleBar[] = [
-      { ...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: CandleBar[] = [
-      { ...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 as any);
-    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 as any);
-    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 as any);
-    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 as any);
-    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 as any);
-    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' as any);
-
-    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' as any);
-
-    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: SourceBars = {
-    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: SourceBars = { 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: SourceBars = {
-      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: SourceBars = {
-      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: SourceBars = {
-      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: SourceBars = {
-      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: SourceBars = {
-      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: SourceBars = {
-      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' as const, bars: [] },
-      { source: 'database' as const, bars: [] },
-      { source: 'sdk'      as const, 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: SourceBars = {
-      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: SourceBars = {
-      source: 'provider',
-      bars: [{ time: 1_000_000, open: 100, high: 999, low: 90, close: 105 }],
-    };
-    const db: SourceBars = {
-      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');
-  });
-});