@forgecharts/sdk 1.1.23

package/src/__tests__/timeframeBoundary.test.ts

@@ -0,0 +1,583 @@
+/**
+ * Timeframe Boundary Tests
+ *
+ * Verifies correctness of `getBucketStart` (from `@forgecharts/shared`) and the
+ * `CandleEngine` live-update / reconnect behaviour at every critical boundary.
+ *
+ * Test categories:
+ *   1. Fixed intervals — standard and previously-missing timeframes
+ *   2. Weekly alignment — Monday start (ISO 8601)
+ *   3. Monthly alignment — calendar first-of-month, incl. leap-year February
+ *   4. Live update semantics — open immutability, high/low expansion, close,
+ *      same-bucket vs new-bucket
+ *   5. Reconnect — gap backfill, historical bars override provisional,
+ *      forming candle survives reconnect
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  getBucketStart,
+  getWeekBucketStart,
+  getMonthBucketStart,
+  isSameBucket,
+  normalizeTimestamp,
+  timeframeToMs,
+  TIMEFRAMES,
+} from '@forgecharts/shared/time';
+import { CandleEngine } from '../engine/CandleEngine';
+import type { RawOHLCV } from '../engine/CandleEngine';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Parse an ISO-8601 UTC string to Unix milliseconds. */
+const ms = (iso: string): number => new Date(iso).getTime();
+/** Parse an ISO-8601 UTC string to Unix seconds. */
+const sec = (iso: string): number => new Date(iso).getTime() / 1000;
+
+/** Build a minimal RawOHLCV tick (all values in Unix seconds by default). */
+function tick(
+  timeSecOrMs: number,
+  open = 100,
+  high = 110,
+  low  = 90,
+  close = 105,
+  volume = 1,
+): RawOHLCV {
+  return { time: timeSecOrMs, open, high, low, close, volume };
+}
+
+// ─── 1. Fixed intervals ───────────────────────────────────────────────────────
+
+describe('getBucketStart — fixed intervals', () => {
+  /**
+   * Reference point: 2025-03-09 14:37:42 UTC
+   *   ms  = 1741528662000
+   *   sec = 1741528662
+   */
+  const REF_MS  = ms('2025-03-09T14:37:42Z');
+
+  it('1m: floors to the minute boundary', () => {
+    expect(getBucketStart(REF_MS, '1m')).toBe(ms('2025-03-09T14:37:00Z'));
+  });
+
+  it('2m: floors to the 2-minute boundary', () => {
+    // 14:37 → bucket start is 14:36 (36 is divisible by 2)
+    expect(getBucketStart(REF_MS, '2m')).toBe(ms('2025-03-09T14:36:00Z'));
+  });
+
+  it('3m (previously missing): floors correctly', () => {
+    // 14:37 → bucket start is 14:36 (36 is divisible by 3)
+    expect(getBucketStart(REF_MS, '3m')).toBe(ms('2025-03-09T14:36:00Z'));
+    // 14:37:42 inside [14:36, 14:39) — confirm
+    expect(getBucketStart(ms('2025-03-09T14:38:59Z'), '3m')).toBe(ms('2025-03-09T14:36:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:39:00Z'), '3m')).toBe(ms('2025-03-09T14:39:00Z'));
+  });
+
+  it('4m (previously missing): floors correctly', () => {
+    // 14:37 → bucket start is 14:36 (36 is divisible by 4)
+    expect(getBucketStart(REF_MS, '4m')).toBe(ms('2025-03-09T14:36:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:39:59Z'), '4m')).toBe(ms('2025-03-09T14:36:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:40:00Z'), '4m')).toBe(ms('2025-03-09T14:40:00Z'));
+  });
+
+  it('5m: floors to the 5-minute boundary', () => {
+    expect(getBucketStart(REF_MS, '5m')).toBe(ms('2025-03-09T14:35:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:39:59Z'), '5m')).toBe(ms('2025-03-09T14:35:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:40:00Z'), '5m')).toBe(ms('2025-03-09T14:40:00Z'));
+  });
+
+  it('10m (previously missing): floors correctly', () => {
+    expect(getBucketStart(REF_MS, '10m')).toBe(ms('2025-03-09T14:30:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:39:59Z'), '10m')).toBe(ms('2025-03-09T14:30:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:40:00Z'), '10m')).toBe(ms('2025-03-09T14:40:00Z'));
+  });
+
+  it('15m: floors to the 15-minute boundary', () => {
+    expect(getBucketStart(REF_MS, '15m')).toBe(ms('2025-03-09T14:30:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:44:59Z'), '15m')).toBe(ms('2025-03-09T14:30:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:45:00Z'), '15m')).toBe(ms('2025-03-09T14:45:00Z'));
+  });
+
+  it('20m (previously missing): floors correctly', () => {
+    expect(getBucketStart(REF_MS, '20m')).toBe(ms('2025-03-09T14:20:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:39:59Z'), '20m')).toBe(ms('2025-03-09T14:20:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:40:00Z'), '20m')).toBe(ms('2025-03-09T14:40:00Z'));
+  });
+
+  it('30m: floors to the 30-minute boundary', () => {
+    expect(getBucketStart(REF_MS, '30m')).toBe(ms('2025-03-09T14:30:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:59:59Z'), '30m')).toBe(ms('2025-03-09T14:30:00Z'));
+    expect(getBucketStart(ms('2025-03-09T15:00:00Z'), '30m')).toBe(ms('2025-03-09T15:00:00Z'));
+  });
+
+  it('45m (previously missing): floors correctly', () => {
+    // 14:37 → bucket start is 14:00 (14*60=840, 840/45=18.666 → floor*45=810=13:30)?
+    // Actually 14:00 = 840 min from epoch day. 840 / 45 = 18.666... → floor = 18 → 18*45 = 810 min
+    // 810 min = 13:30. So 14:37 falls in the [13:30, 14:15) bucket.
+    // Wait — getBucketStart uses epoch ms, not minutes within a day.
+    // Let me recalculate: epoch for 14:37 on 2025-03-09, then floor to 45-min intervals.
+    const bucket = getBucketStart(REF_MS, '45m');
+    const INTERVAL = TIMEFRAMES['45m']!.ms!; // 2_700_000
+    expect(bucket % INTERVAL).toBe(0); // must be on a 45-min epoch boundary
+    expect(bucket).toBeLessThanOrEqual(REF_MS);
+    expect(bucket + INTERVAL).toBeGreaterThan(REF_MS);
+  });
+
+  it('1h: floors to the hour boundary', () => {
+    expect(getBucketStart(REF_MS, '1h')).toBe(ms('2025-03-09T14:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T14:59:59Z'), '1h')).toBe(ms('2025-03-09T14:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T15:00:00Z'), '1h')).toBe(ms('2025-03-09T15:00:00Z'));
+  });
+
+  it('2h: floors to the 2-hour boundary', () => {
+    expect(getBucketStart(REF_MS, '2h')).toBe(ms('2025-03-09T14:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T15:59:59Z'), '2h')).toBe(ms('2025-03-09T14:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T16:00:00Z'), '2h')).toBe(ms('2025-03-09T16:00:00Z'));
+  });
+
+  it('4h: floors to the 4-hour boundary', () => {
+    expect(getBucketStart(REF_MS, '4h')).toBe(ms('2025-03-09T12:00:00Z'));
+  });
+
+  it('6h: floors to the 6-hour boundary', () => {
+    expect(getBucketStart(REF_MS, '6h')).toBe(ms('2025-03-09T12:00:00Z'));
+  });
+
+  it('12h: floors to the 12-hour boundary', () => {
+    expect(getBucketStart(REF_MS, '12h')).toBe(ms('2025-03-09T12:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T11:59:59Z'), '12h')).toBe(ms('2025-03-09T00:00:00Z'));
+  });
+
+  it('1d: floors to UTC midnight', () => {
+    expect(getBucketStart(REF_MS, '1d')).toBe(ms('2025-03-09T00:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T23:59:59Z'), '1d')).toBe(ms('2025-03-09T00:00:00Z'));
+    expect(getBucketStart(ms('2025-03-10T00:00:00Z'), '1d')).toBe(ms('2025-03-10T00:00:00Z'));
+  });
+
+  it('3d: floors to the 3-day epoch boundary', () => {
+    const bucket = getBucketStart(REF_MS, '3d');
+    const INTERVAL = TIMEFRAMES['3d']!.ms!; // 259_200_000
+    expect(bucket % INTERVAL).toBe(0);
+    expect(bucket).toBeLessThanOrEqual(REF_MS);
+    expect(bucket + INTERVAL).toBeGreaterThan(REF_MS);
+  });
+
+  it('exact boundary: timestamp == bucket start maps to itself', () => {
+    const hourStart = ms('2025-03-09T14:00:00Z');
+    expect(getBucketStart(hourStart, '1h')).toBe(hourStart);
+
+    const minuteStart = ms('2025-03-09T14:37:00Z');
+    expect(getBucketStart(minuteStart, '1m')).toBe(minuteStart);
+  });
+
+  it('isSameBucket: two timestamps in the same 1h bucket', () => {
+    expect(isSameBucket(
+      ms('2025-03-09T14:01:00Z'),
+      ms('2025-03-09T14:59:00Z'),
+      '1h',
+    )).toBe(true);
+  });
+
+  it('isSameBucket: timestamps on either side of an hour boundary', () => {
+    expect(isSameBucket(
+      ms('2025-03-09T13:59:59Z'),
+      ms('2025-03-09T14:00:01Z'),
+      '1h',
+    )).toBe(false);
+  });
+
+  it('timeframeToMs: returns null for calendar types and unknown keys', () => {
+    expect(timeframeToMs('1w')).toBeNull();
+    expect(timeframeToMs('1M')).toBeNull();
+    expect(timeframeToMs('3h')).toBeNull(); // orphaned — excluded from registry
+    expect(timeframeToMs('8h')).toBeNull(); // orphaned — excluded from registry
+  });
+
+  it('timeframeToMs: returns correct ms for all fixed timeframes', () => {
+    expect(timeframeToMs('1m')).toBe(60_000);
+    expect(timeframeToMs('5m')).toBe(300_000);
+    expect(timeframeToMs('15m')).toBe(900_000);
+    expect(timeframeToMs('1h')).toBe(3_600_000);
+    expect(timeframeToMs('4h')).toBe(14_400_000);
+    expect(timeframeToMs('1d')).toBe(86_400_000);
+  });
+});
+
+// ─── 2. Weekly alignment ──────────────────────────────────────────────────────
+
+describe('getBucketStart — weekly (Monday alignment)', () => {
+  it('Sunday maps to the immediately preceding Monday', () => {
+    // 2025-03-09 is a Sunday → bucket should be Mon 2025-03-03
+    expect(getWeekBucketStart(ms('2025-03-09T12:00:00Z'))).toBe(ms('2025-03-03T00:00:00Z'));
+    expect(getBucketStart(ms('2025-03-09T12:00:00Z'), '1w')).toBe(ms('2025-03-03T00:00:00Z'));
+  });
+
+  it('Monday midnight maps to itself', () => {
+    expect(getWeekBucketStart(ms('2025-03-03T00:00:00Z'))).toBe(ms('2025-03-03T00:00:00Z'));
+    expect(getBucketStart(ms('2025-03-03T00:00:00Z'), '1w')).toBe(ms('2025-03-03T00:00:00Z'));
+  });
+
+  it('Monday 00:00:01 maps to the same Monday', () => {
+    expect(getBucketStart(ms('2025-03-03T00:00:01Z'), '1w')).toBe(ms('2025-03-03T00:00:00Z'));
+  });
+
+  it('Saturday 23:59:59 maps to the week-opening Monday', () => {
+    expect(getBucketStart(ms('2025-03-08T23:59:59Z'), '1w')).toBe(ms('2025-03-03T00:00:00Z'));
+  });
+
+  it('does NOT anchor to Thursday (Unix epoch)', () => {
+    // The naive floor(t / 604800)*604800 anchors to Thursday 1970-01-01.
+    // Our implementation must yield a Monday for any input.
+    for (const iso of [
+      '2025-01-01T00:00:00Z', // Wednesday
+      '2025-02-15T12:00:00Z', // Saturday
+      '2024-12-25T00:00:00Z', // Wednesday (Christmas)
+      '2025-03-09T23:59:59Z', // Sunday
+    ]) {
+      const bucket = getWeekBucketStart(ms(iso));
+      const day = new Date(bucket).getUTCDay();
+      expect(day, `${iso} → bucket day should be Monday (1), got ${day}`).toBe(1);
+    }
+  });
+
+  it('successive week buckets are exactly 7 days apart', () => {
+    const w1 = getWeekBucketStart(ms('2025-03-03T00:00:00Z'));
+    const w2 = getWeekBucketStart(ms('2025-03-10T00:00:00Z'));
+    expect(w2 - w1).toBe(7 * 24 * 60 * 60 * 1000);
+  });
+
+  it('isSameBucket: Monday and Sunday of the same ISO week', () => {
+    expect(isSameBucket(
+      ms('2025-03-03T00:00:00Z'), // Monday
+      ms('2025-03-09T23:59:59Z'), // Sunday
+      '1w',
+    )).toBe(true);
+  });
+
+  it('isSameBucket: Sunday and the next Monday are different buckets', () => {
+    expect(isSameBucket(
+      ms('2025-03-09T23:59:59Z'), // Sunday (week of Mar-03)
+      ms('2025-03-10T00:00:00Z'), // Monday (next week)
+      '1w',
+    )).toBe(false);
+  });
+});
+
+// ─── 3. Monthly alignment ─────────────────────────────────────────────────────
+
+describe('getBucketStart — monthly (calendar first-of-month)', () => {
+  it('mid-month maps to the first of that month', () => {
+    expect(getMonthBucketStart(ms('2025-03-15T18:30:00Z'))).toBe(ms('2025-03-01T00:00:00Z'));
+    expect(getBucketStart(ms('2025-03-15T18:30:00Z'), '1M')).toBe(ms('2025-03-01T00:00:00Z'));
+  });
+
+  it('first of month 00:00 UTC maps to itself', () => {
+    expect(getBucketStart(ms('2025-03-01T00:00:00Z'), '1M')).toBe(ms('2025-03-01T00:00:00Z'));
+  });
+
+  it('last second of January maps to January 1st', () => {
+    expect(getBucketStart(ms('2025-01-31T23:59:59Z'), '1M')).toBe(ms('2025-01-01T00:00:00Z'));
+  });
+
+  it('January → February rollover (Feb 1st maps to Feb 1st)', () => {
+    expect(getBucketStart(ms('2025-02-01T00:00:00Z'), '1M')).toBe(ms('2025-02-01T00:00:00Z'));
+    expect(getBucketStart(ms('2025-01-31T23:59:59Z'), '1M')).toBe(ms('2025-01-01T00:00:00Z'));
+  });
+
+  it('February (non-leap): entire month maps to Feb 1', () => {
+    expect(getBucketStart(ms('2025-02-14T12:00:00Z'), '1M')).toBe(ms('2025-02-01T00:00:00Z'));
+    expect(getBucketStart(ms('2025-02-28T23:59:59Z'), '1M')).toBe(ms('2025-02-01T00:00:00Z'));
+  });
+
+  it('February (leap year 2024): Feb 29 maps to Feb 1', () => {
+    expect(getBucketStart(ms('2024-02-29T12:00:00Z'), '1M')).toBe(ms('2024-02-01T00:00:00Z'));
+  });
+
+  it('month-end rollover: March 1st is a new bucket', () => {
+    expect(isSameBucket(
+      ms('2025-02-28T23:59:59Z'),
+      ms('2025-03-01T00:00:00Z'),
+      '1M',
+    )).toBe(false);
+  });
+
+  it('isSameBucket: Feb 1 and Feb 28 (non-leap)', () => {
+    expect(isSameBucket(
+      ms('2025-02-01T00:00:00Z'),
+      ms('2025-02-28T23:59:59Z'),
+      '1M',
+    )).toBe(true);
+  });
+
+  it('does NOT use 30-day approximation', () => {
+    // Using epoch / 2_592_000_000 (30 days) would shift December 2024 to wrong month.
+    // Date.UTC-based implementation must be correct.
+    expect(getBucketStart(ms('2024-12-31T23:59:59Z'), '1M')).toBe(ms('2024-12-01T00:00:00Z'));
+    expect(getBucketStart(ms('2025-01-01T00:00:00Z'), '1M')).toBe(ms('2025-01-01T00:00:00Z'));
+  });
+});
+
+// ─── 4. Live update semantics ─────────────────────────────────────────────────
+
+describe('CandleEngine — live update semantics', () => {
+  let engine: CandleEngine;
+  const TF = '1m';
+
+  // A round 1-minute boundary in Unix seconds: 2025-03-09 14:00:00 UTC
+  const T0 = sec('2025-03-09T14:00:00Z'); // candle 0 open
+  const T1 = sec('2025-03-09T14:01:00Z'); // candle 1 open
+
+  beforeEach(() => {
+    engine = new CandleEngine();
+    engine.initialize([], TF as any);
+  });
+
+  it('first tick creates the candle', () => {
+    const result = engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    expect(result.type).toBe('append');
+    const bar = engine.getLastBar()!;
+    expect(bar.open).toBe(100);
+    expect(bar.high).toBe(110);
+    expect(bar.low).toBe(90);
+    expect(bar.close).toBe(105);
+  });
+
+  it('same-bucket update: open is immutable', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    // Second tick with different open — open must stay 100
+    engine.applyLiveUpdate(tick(T0 + 30, 200, 215, 195, 210));
+    const bar = engine.getLastBar()!;
+    expect(bar.open).toBe(100);  // unchanged
+    expect(bar.close).toBe(210); // updated
+  });
+
+  it('same-bucket update: high expands upward', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 150, 90, 145));
+    expect(engine.getLastBar()!.high).toBe(150);
+  });
+
+  it('same-bucket update: high never decreases', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 150, 90, 145));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 110, 90, 105));
+    expect(engine.getLastBar()!.high).toBe(150);
+  });
+
+  it('same-bucket update: low expands downward', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 110, 70, 80));
+    expect(engine.getLastBar()!.low).toBe(70);
+  });
+
+  it('same-bucket update: low never increases', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 70, 80));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 110, 90, 105));
+    expect(engine.getLastBar()!.low).toBe(70);
+  });
+
+  it('same-bucket update: close always updates to the latest tick', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 110, 90, 108));
+    engine.applyLiveUpdate(tick(T0 + 45, 100, 110, 90, 111));
+    expect(engine.getLastBar()!.close).toBe(111);
+  });
+
+  it('same-bucket update: bar count stays the same', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T0 + 30, 100, 110, 90, 108));
+    expect(engine.getBars().length).toBe(1);
+  });
+
+  it('new-bucket: creates a new bar and closes the previous', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    const result = engine.applyLiveUpdate(tick(T1, 106, 120, 100, 115));
+    expect(result.type).toBe('append');
+    expect(engine.getBars().length).toBe(2);
+
+    const bars = engine.getBars();
+    expect(bars[0]!.isClosed).toBe(true);
+    expect(bars[1]!.isClosed).toBe(false);
+  });
+
+  it('new-bucket: previous bar open is unchanged', () => {
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    engine.applyLiveUpdate(tick(T1, 106, 120, 100, 115));
+    expect(engine.getBars()[0]!.open).toBe(100);
+  });
+
+  it('out-of-order tick: ignored and bar count unchanged', () => {
+    engine.applyLiveUpdate(tick(T1, 106, 120, 100, 115)); // candle 1
+    const result = engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105)); // older — ignore
+    expect(result.type).toBe('ignore');
+    expect(engine.getBars().length).toBe(1);
+  });
+
+  it('gap detection: skipping multiple buckets emits gap result', () => {
+    const T5 = sec('2025-03-09T14:05:00Z'); // 5 minutes after T0
+    engine.applyLiveUpdate(tick(T0, 100, 110, 90, 105));
+    const result = engine.applyLiveUpdate(tick(T5, 106, 120, 100, 115));
+    expect(result.type).toBe('gap');
+    if (result.type === 'gap') {
+      expect(result.missingCount).toBe(4); // T1, T2, T3, T4 missing
+    }
+  });
+});
+
+// ─── 5. Reconnect tests ───────────────────────────────────────────────────────
+
+describe('CandleEngine — reconnect and backfill', () => {
+  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');
+  const T3 = sec('2025-03-09T14:03:00Z');
+  const T4 = sec('2025-03-09T14:04:00Z');
+
+  it('backfillGap: merges missing bars into existing array', () => {
+    const engine = new CandleEngine();
+    engine.initialize([tick(T0, 100, 110, 90, 105)], TF as any);
+    engine.applyLiveUpdate(tick(T4, 130, 140, 120, 135)); // jumps over T1–T3
+
+    // Backfill T1–T3 from REST
+    engine.backfillGap([
+      tick(T1, 106, 115, 100, 112),
+      tick(T2, 112, 118, 105, 116),
+      tick(T3, 116, 125, 110, 120),
+    ]);
+
+    const bars = engine.getBars();
+    expect(bars.length).toBe(5);
+    expect(bars.map(b => b.time)).toEqual([T0, T1, T2, T3, T4]);
+  });
+
+  it('backfillGap: historical bars override closed provisional bars', () => {
+    const engine = new CandleEngine();
+    engine.initialize([
+      tick(T0, 100, 110, 90, 105),
+      tick(T1, 106, 115, 100, 112), // provisional T1 (currently live/open)
+    ], TF as any);
+
+    // Advance to T2 — this closes T1, making it eligible for REST override
+    engine.applyLiveUpdate(tick(T2, 112, 118, 105, 116));
+
+    // REST returns authoritative data for the now-closed T1
+    engine.backfillGap([tick(T1, 106, 120, 98, 119)]);
+
+    const bars = engine.getBars();
+    const t1bar = bars.find(b => b.time === T1)!;
+    expect(t1bar.high).toBe(120);  // authoritative REST value wins for CLOSED bars
+    expect(t1bar.low).toBe(98);
+    expect(t1bar.close).toBe(119);
+  });
+
+  it('backfillGap: forming candle is preserved after merge', () => {
+    const engine = new CandleEngine();
+    engine.initialize([tick(T0, 100, 110, 90, 105)], TF as any);
+    engine.applyLiveUpdate(tick(T3, 130, 140, 120, 135)); // live bar at T3
+
+    // Backfill T1–T2 (gap bars before the live bar)
+    engine.backfillGap([
+      tick(T1, 106, 115, 100, 112),
+      tick(T2, 112, 118, 105, 116),
+    ]);
+
+    const last = engine.getLastBar()!;
+    expect(last.time).toBe(T3);
+    expect(last.close).toBe(135); // forming candle values preserved
+  });
+
+  it('handleReconnect: REST overlap corrects stale candles', () => {
+    const engine = new CandleEngine();
+    engine.initialize([
+      tick(T0, 100, 110, 90, 105),
+      tick(T1, 106, 112, 100, 110), // stale — missed a major move during outage
+      tick(T2, 110, 115, 105, 113),
+    ], TF as any);
+
+    // Reconnect supplies corrected data for T1
+    engine.handleReconnect([
+      tick(T1, 106, 150, 80, 145),  // correct high/low for T1
+      tick(T2, 145, 160, 130, 155), // correct T2
+    ]);
+
+    const bars = engine.getBars();
+    const t1 = bars.find(b => b.time === T1)!;
+    expect(t1.high).toBe(150);
+    expect(t1.low).toBe(80);
+
+    const t2 = bars.find(b => b.time === T2)!;
+    expect(t2.high).toBe(160);
+  });
+
+  it('handleReconnect: forming candle survives a reconnect', () => {
+    const engine = new CandleEngine();
+    engine.initialize([tick(T0, 100, 110, 90, 105)], TF as any);
+    engine.applyLiveUpdate(tick(T2, 112, 120, 108, 118)); // forming candle at T2
+
+    // The overlap window includes T0–T1 history but not yet T2
+    engine.handleReconnect([
+      tick(T0, 100, 115, 88, 108), // slightly different authoritative T0
+      tick(T1, 108, 120, 104, 116),
+    ]);
+
+    // T2 (live bar) should survive untouched
+    const last = engine.getLastBar()!;
+    expect(last.time).toBe(T2);
+    expect(last.close).toBe(118);
+  });
+
+  it('handleReconnect: gaps between reconnect bars are handled', () => {
+    const engine = new CandleEngine();
+    engine.initialize([
+      tick(T0, 100, 110, 90, 105),
+    ], TF as any);
+
+    engine.handleReconnect([
+      tick(T0, 100, 115, 88, 112),
+      tick(T2, 112, 120, 108, 118), // T1 is missing from the REST window
+      tick(T4, 120, 130, 115, 128),
+    ]);
+
+    // Result must be sorted and include all available bars
+    const bars = engine.getBars();
+    const times = bars.map(b => b.time);
+    expect(times).toEqual(times.slice().sort((a, b) => a - b));
+  });
+});
+
+// ─── 6. normalizeTimestamp edge cases ────────────────────────────────────────
+
+describe('normalizeTimestamp — boundary cases', () => {
+  it('Unix seconds (≤ 1e12) are multiplied by 1000', () => {
+    expect(normalizeTimestamp(1_741_528_662)).toBe(1_741_528_662_000);
+  });
+
+  it('Unix milliseconds (> 1e12) are returned as-is', () => {
+    expect(normalizeTimestamp(1_741_528_662_000)).toBe(1_741_528_662_000);
+  });
+
+  it('numeric string in seconds is treated as seconds', () => {
+    expect(normalizeTimestamp('1741528662')).toBe(1_741_528_662_000);
+  });
+
+  it('numeric string in ms is returned as-is', () => {
+    expect(normalizeTimestamp('1741528662000')).toBe(1_741_528_662_000);
+  });
+
+  it('Date object returns its getTime()', () => {
+    const d = new Date('2025-03-09T14:37:42Z');
+    expect(normalizeTimestamp(d)).toBe(d.getTime());
+  });
+
+  it('throws RangeError on NaN', () => {
+    expect(() => normalizeTimestamp(NaN)).toThrow(RangeError);
+  });
+
+  it('throws RangeError on Infinity', () => {
+    expect(() => normalizeTimestamp(Infinity)).toThrow(RangeError);
+  });
+
+  it('throws RangeError on invalid date string', () => {
+    expect(() => normalizeTimestamp('not-a-date')).toThrow(RangeError);
+  });
+});