@forgecharts/sdk 1.1.23

package/src/engine/__tests__/CandleEngine.test.ts

@@ -0,0 +1,402 @@
+import { describe, it, expect, vi } from 'vitest';
+import { CandleEngine } from '../CandleEngine';
+import type { CandleBar, RawOHLCV, UpdateResult, GapInfo } from '../CandleEngine';
+import { timeframeToMs, getBucketStart } from '../timeframeUtils';
+import { getMissingBarCount, mergeBars } from '../mergeUtils';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Build a minimal raw bar with time in seconds. */
+function rawBar(
+  timeSec: number,
+  open: number,
+  high: number,
+  low: number,
+  close: number,
+  volume = 1,
+  isClosed = false,
+): RawOHLCV {
+  return { time: timeSec, open, high, low, close, volume, isClosed };
+}
+
+/** Build a raw bar with time in milliseconds. */
+function rawBarMs(timeSec: number, open: number, high: number, low: number, close: number): RawOHLCV {
+  return { time: timeSec * 1000, open, high, low, close, volume: 1 };
+}
+
+// 1-minute boundary: 2024-07-03T10:00:00Z = 1719997200 seconds
+const T0 = 1_719_997_200;
+const T1 = T0 + 60;
+const T2 = T0 + 120;
+const T3 = T0 + 180;
+const T4 = T0 + 240;
+
+// ─── 1. Same-candle update ────────────────────────────────────────────────────
+
+describe('same-candle update (3 ticks, same bucket)', () => {
+  it('produces exactly one candle with correct O/H/L/C', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+    engine.applyLiveUpdate(rawBar(T0, 100, 108, 96, 107)); // high rises, low drops
+    engine.applyLiveUpdate(rawBar(T0, 100, 107, 97, 106)); // high recedes — not applied
+
+    expect(engine.getBars().length).toBe(1);
+
+    const bar = engine.getLastBar()!;
+    expect(bar.open).toBe(100);   // open preserved from first tick
+    expect(bar.high).toBe(108);   // max of all ticks
+    expect(bar.low).toBe(96);     // min of all ticks
+    expect(bar.close).toBe(106);  // close from latest tick
+  });
+
+  it('returns UpdateResult type "update" for same-candle ticks', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    const r1 = engine.applyLiveUpdate(rawBar(T0, 100, 100, 100, 100));
+    const r2 = engine.applyLiveUpdate(rawBar(T0, 100, 110, 90, 105));
+
+    expect(r1.type).toBe('append');  // first tick is an append
+    expect(r2.type).toBe('update');
+  });
+
+  it('high can never decrease within a candle', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 50, 120, 40, 100));
+    engine.applyLiveUpdate(rawBar(T0, 50,  80, 60,  90)); // high=80 < 120
+
+    expect(engine.getLastBar()!.high).toBe(120);
+  });
+
+  it('low can never increase within a candle', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 50, 120, 40, 100));
+    engine.applyLiveUpdate(rawBar(T0, 50, 110, 75, 105)); // low=75 > 40
+
+    expect(engine.getLastBar()!.low).toBe(40);
+  });
+});
+
+// ─── 2. New-candle append ─────────────────────────────────────────────────────
+
+describe('new-candle append (time advances)', () => {
+  it('appends a second candle and marks first as closed', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+    const result = engine.applyLiveUpdate(rawBar(T1, 103, 110, 101, 108));
+
+    expect(result.type).toBe('append');
+    expect(engine.getBars().length).toBe(2);
+    expect(engine.getBars()[0]!.isClosed).toBe(true);
+    expect(engine.getBars()[1]!.isClosed).toBe(false);
+  });
+
+  it('appended candle uses the new tick\'s open price', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+    engine.applyLiveUpdate(rawBar(T1, 200, 210, 195, 205));
+
+    expect(engine.getBars()[1]!.open).toBe(200);
+  });
+});
+
+// ─── 3. Out-of-order discard ──────────────────────────────────────────────────
+
+describe('out-of-order ticks', () => {
+  it('discards ticks older than the current live candle', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T1, 103, 110, 100, 107));  // at T1
+    const result = engine.applyLiveUpdate(rawBar(T0, 100, 120, 95, 115)); // T0 < T1
+
+    expect(result.type).toBe('ignore');
+    expect(engine.getBars().length).toBe(1);
+    expect(engine.getLastBar()!.time).toBe(T1);
+  });
+
+  it('does not change any OHLCV values after discarding', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T1, 103, 110, 100, 107));
+    const snapBefore = { ...engine.getLastBar()! };
+
+    engine.applyLiveUpdate(rawBar(T0, 999, 999, 1, 999));
+
+    expect(engine.getLastBar()!.open).toBe(snapBefore.open);
+    expect(engine.getLastBar()!.high).toBe(snapBefore.high);
+    expect(engine.getLastBar()!.low).toBe(snapBefore.low);
+    expect(engine.getLastBar()!.close).toBe(snapBefore.close);
+  });
+});
+
+// ─── 4. Gap detection ─────────────────────────────────────────────────────────
+
+describe('gap detection', () => {
+  it('fires onGapDetected when a bucket is skipped', () => {
+    const gaps: GapInfo[] = [];
+
+    const engine = new CandleEngine({ onGapDetected: (g) => gaps.push(g) });
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+    // Jump 3 minutes — T1 and T2 are missing
+    engine.applyLiveUpdate(rawBar(T3, 110, 115, 108, 113));
+
+    expect(gaps.length).toBe(1);
+    expect(gaps[0]!.missingCount).toBe(2);
+    expect(gaps[0]!.fromTimeMs).toBe(T0 * 1000);
+    expect(gaps[0]!.toTimeMs).toBe(T3 * 1000);
+  });
+
+  it('returns UpdateResult type "gap" when a gap occurs', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+    const result = engine.applyLiveUpdate(rawBar(T4, 103, 108, 101, 106));
+
+    expect(result.type).toBe('gap');
+    if (result.type === 'gap') {
+      expect(result.missingCount).toBe(3);
+    }
+  });
+
+  it('does not fire onGapDetected for consecutive candles', () => {
+    const gapFn = vi.fn();
+    const engine = new CandleEngine({ onGapDetected: gapFn });
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
+    engine.applyLiveUpdate(rawBar(T1, 103, 108, 101, 106));
+
+    expect(gapFn).not.toHaveBeenCalled();
+  });
+});
+
+// ─── 5. Reconnect reconciliation ─────────────────────────────────────────────
+
+describe('handleReconnect', () => {
+  it('deduplicates bars correctly when there is overlap', () => {
+    const engine = new CandleEngine();
+    engine.initialize([
+      rawBar(T0, 100, 105, 98, 103, 10, true),
+      rawBar(T1, 103, 108, 101, 106, 12, true),
+      rawBar(T2, 106, 110, 104, 109, 8,  false), // live
+    ], '1m');
+
+    // Reconnect brings T1 and T2 with corrected values
+    engine.handleReconnect([
+      rawBar(T1, 103, 112, 99, 111, 15, true),   // corrected T1
+      rawBar(T2, 106, 111, 103, 110, 9, false),   // corrected T2 (live)
+    ]);
+
+    expect(engine.getBars().length).toBe(3);
+    expect(engine.getBars()[1]!.high).toBe(112);   // T1 updated
+    expect(engine.getBars()[2]!.high).toBe(111);   // T2 updated
+  });
+
+  it('fires onResync after handleReconnect', () => {
+    const resyncFn = vi.fn();
+    const engine = new CandleEngine({ onResync: resyncFn });
+    engine.initialize([rawBar(T0, 100, 105, 98, 103)], '1m');
+
+    engine.handleReconnect([rawBar(T0, 100, 107, 96, 104)]);
+
+    expect(resyncFn).toHaveBeenCalledOnce();
+  });
+});
+
+// ─── 6. ms → s timestamp conversion ─────────────────────────────────────────
+
+describe('millisecond vs second timestamp normalisation', () => {
+  it('converts ms timestamps to seconds correctly', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    // T0 in ms
+    engine.applyLiveUpdate(rawBarMs(T0, 100, 105, 98, 103));
+
+    const bar = engine.getLastBar()!;
+    expect(bar.time).toBe(T0);              // chart field = seconds
+    expect(bar.timeMs).toBe(T0 * 1000);     // engine field = ms
+  });
+
+  it('handles both ms and s inputs in the same session without corruption', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    engine.applyLiveUpdate(rawBarMs(T0, 100, 105, 98, 103));   // ms
+    engine.applyLiveUpdate(rawBar(T0, 100, 110, 95, 108));      // seconds, same bucket
+
+    expect(engine.getBars().length).toBe(1);  // same bucket → still one candle
+    expect(engine.getLastBar()!.high).toBe(110);
+  });
+
+  it('floors ms timestamp to candle boundary', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    // T0 + 30s (mid-candle) in ms → should still map to T0 bucket
+    engine.applyLiveUpdate({ time: (T0 + 30) * 1000, open: 100, high: 105, low: 98, close: 103 });
+
+    expect(engine.getLastBar()!.time).toBe(T0);
+  });
+});
+
+// ─── 7. Custom timeframe aggregation (timeframeUtils) ────────────────────────
+
+describe('timeframeUtils helpers', () => {
+  it('timeframeToMs returns correct durations', () => {
+    expect(timeframeToMs('1m')).toBe(60_000);
+    expect(timeframeToMs('5m')).toBe(300_000);
+    expect(timeframeToMs('1h')).toBe(3_600_000);
+    expect(timeframeToMs('4h')).toBe(14_400_000);
+    expect(timeframeToMs('1d')).toBe(86_400_000);
+    // 1w and 1M are calendar timeframes — no fixed ms duration.
+    // timeframeUtils returns the 60_000 compat fallback so CandleEngine
+    // always receives a finite number (calendar alignment is handled separately).
+    expect(timeframeToMs('1w')).toBe(60_000);
+  });
+
+  it('timeframeToMs falls back to 60_000 for unknown labels', () => {
+    // '3h' and '8h' are orphaned (excluded from canonical registry) → 60_000 fallback.
+    // '2m' is now registered (120_000) — use genuinely unknown keys here.
+    expect(timeframeToMs('3h')).toBe(60_000);
+    expect(timeframeToMs('')).toBe(60_000);
+  });
+
+  it('getBucketStart floors to candle boundary', () => {
+    expect(getBucketStart(62_000, 60_000)).toBe(60_000);        // 1m01s → 1m00s
+    expect(getBucketStart(3_720_000, 3_600_000)).toBe(3_600_000); // 1h02m → 1h00m
+    expect(getBucketStart(0, 60_000)).toBe(0);
+  });
+
+  it('5m candle engine buckets a mid-bar tick to the 5m open', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '5m');
+
+    const T5m = getBucketStart(T0 * 1000, timeframeToMs('5m')); // floor T0 to 5m
+    const mid  = T5m / 1000 + 120; // 2 minutes into the 5m bucket
+
+    engine.applyLiveUpdate({ time: mid, open: 50, high: 55, low: 48, close: 52 });
+
+    expect(engine.getLastBar()!.timeMs).toBe(T5m);
+  });
+});
+
+// ─── 8. mergeUtils helpers ────────────────────────────────────────────────────
+
+describe('mergeUtils helpers', () => {
+  const makeBar = (timeSec: number, close: number, isClosed: boolean): CandleBar => ({
+    timeMs: timeSec * 1000,
+    time: timeSec,
+    open: 100, high: 110, low: 90, close,
+    volume: 1, isClosed,
+  });
+
+  it('getMissingBarCount returns 0 for consecutive bars', () => {
+    expect(getMissingBarCount(T0 * 1000, T1 * 1000, 60_000)).toBe(0);
+  });
+
+  it('getMissingBarCount returns correct count for gap', () => {
+    expect(getMissingBarCount(T0 * 1000, T3 * 1000, 60_000)).toBe(2); // T1 and T2
+    expect(getMissingBarCount(T0 * 1000, T4 * 1000, 60_000)).toBe(3); // T1, T2, T3
+  });
+
+  it('mergeBars deduplicates by timeMs with incoming winning', () => {
+    const existing = [makeBar(T0, 103, true), makeBar(T1, 106, true)];
+    const incoming = [makeBar(T1, 999, true), makeBar(T2, 110, false)]; // T1 override
+
+    const merged = mergeBars(existing, incoming);
+
+    expect(merged.length).toBe(3);
+    expect(merged[1]!.close).toBe(999); // incoming wins for closed bar
+    expect(merged[2]!.time).toBe(T2);
+  });
+
+  it('mergeBars preserves existing live candle when incoming is also live and same time', () => {
+    const existing = [makeBar(T0, 103, false)]; // live, close=103
+    const incoming = [makeBar(T0, 107, false)]; // fresher live tick, close=107
+
+    const merged = mergeBars(existing, incoming);
+
+    // Live bar: incoming wins because it is the freshest tick
+    expect(merged[0]!.close).toBe(107);
+  });
+
+  it('mergeBars sorts output by timeMs', () => {
+    const bars = [makeBar(T2, 100, true), makeBar(T0, 100, true), makeBar(T1, 100, true)];
+    const sorted = mergeBars(bars, []);
+    expect(sorted.map(b => b.time)).toEqual([T0, T1, T2]);
+  });
+});
+
+// ─── 9. backfillGap ───────────────────────────────────────────────────────────
+
+describe('backfillGap', () => {
+  it('fills missing buckets and fires onResync', () => {
+    const resyncFn = vi.fn();
+
+    const engine = new CandleEngine({ onResync: resyncFn });
+    engine.initialize([
+      rawBar(T0, 100, 105, 98, 103),
+      rawBar(T3, 110, 115, 108, 113),  // gap: T1, T2 missing
+    ], '1m');
+
+    engine.backfillGap([
+      rawBar(T1, 103, 108, 101, 106),
+      rawBar(T2, 106, 110, 104, 109),
+    ]);
+
+    expect(engine.getBars().length).toBe(4);
+    expect(resyncFn).toHaveBeenCalledOnce();
+
+    const times = engine.getBars().map(b => b.time);
+    expect(times).toEqual([T0, T1, T2, T3]);
+  });
+});
+
+// ─── 10. CandleEngine lifecycle ──────────────────────────────────────────────
+
+describe('lifecycle', () => {
+  it('reset() clears all bars', () => {
+    const engine = new CandleEngine();
+    engine.initialize([rawBar(T0, 100, 105, 98, 103)], '1m');
+
+    engine.reset();
+
+    expect(engine.getBars().length).toBe(0);
+    expect(engine.getLastBar()).toBeNull();
+  });
+
+  it('handles initialize() with empty history', () => {
+    const engine = new CandleEngine();
+    engine.initialize([], '1m');
+
+    expect(engine.getBars().length).toBe(0);
+    expect(engine.getLastBar()).toBeNull();
+  });
+
+  it('handles duplicate historical bars (keeps last per timeMs)', () => {
+    const engine = new CandleEngine();
+    engine.initialize([
+      rawBar(T0, 100, 105, 98, 103),
+      rawBar(T0, 100, 110, 96, 108), // same time, last should win
+    ], '1m');
+
+    expect(engine.getBars().length).toBe(1);
+    expect(engine.getLastBar()!.high).toBe(110);
+  });
+});

package/src/engine/candleInvariants.ts

@@ -0,0 +1,172 @@
+/**
+ * Candle Invariant Guards
+ *
+ * Defensive assertions for the CandleEngine update pipeline.
+ * All guards are no-ops in production (`NODE_ENV === 'production'`).
+ *
+ * Design principles:
+ *   - Each guard checks exactly ONE invariant and logs a descriptive warning.
+ *   - Guards never throw by default — they warn so streaming data is never blocked.
+ *   - Call sites pass a `context` string that identifies where the check ran.
+ *   - A test harness can replace `_reporter` to assert on violations.
+ *
+ * Usage:
+ *   import { assertOhlcRelationships, assertNotFinalized } from './candleInvariants';
+ */
+
+import type { CandleBar } from './CandleEngine';
+import { getCalendarBucketStart } from './timeframeUtils';
+
+// ─── Reporter (swappable in tests) ───────────────────────────────────────────
+
+/** Called for every invariant violation.  Replaced in unit tests. */
+export let _reporter: (message: string) => void = (msg) => console.warn(msg);
+
+/** Replace the violation reporter (for unit-test assertions). */
+export function _setReporter(fn: (message: string) => void): void {
+  _reporter = fn;
+}
+
+/** Re-install the default console.warn reporter. */
+export function _resetReporter(): void {
+  _reporter = (msg) => console.warn(msg);
+}
+
+// ─── Dev guard ───────────────────────────────────────────────────────────────
+
+function isDevMode(): boolean {
+  // Access process via globalThis to avoid relying on @types/node in browser builds
+  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } })
+    .process?.env?.['NODE_ENV'];
+  return nodeEnv !== 'production';
+}
+
+function violation(context: string, message: string): void {
+  _reporter(`[CANDLE_INVARIANT] ${context}: ${message}`);
+}
+
+// ─── Guards ───────────────────────────────────────────────────────────────────
+
+/**
+ * Verify that `high >= open, close, low` and `low <= open, close`.
+ *
+ * Floats from external feeds can occasionally violate these due to rounding.
+ * This guard surfaces them immediately rather than silently corrupting the chart.
+ */
+export function assertOhlcRelationships(bar: CandleBar, context: string): void {
+  if (!isDevMode()) return;
+
+  const { open, high, low, close, timeMs } = bar;
+
+  if (high < open)  violation(context, `high(${high}) < open(${open})  at timeMs=${timeMs}`);
+  if (high < close) violation(context, `high(${high}) < close(${close}) at timeMs=${timeMs}`);
+  if (high < low)   violation(context, `high(${high}) < low(${low})   at timeMs=${timeMs}`);
+  if (low  > open)  violation(context, `low(${low}) > open(${open})   at timeMs=${timeMs}`);
+  if (low  > close) violation(context, `low(${low}) > close(${close}) at timeMs=${timeMs}`);
+}
+
+/**
+ * Verify that `bar.timeMs` is exactly equal to the candle-open boundary for the
+ * given timeframe.  If it is not, `normalizeOhlcv` or `getCalendarBucketStart`
+ * has a bug.
+ */
+export function assertBucketAlignment(bar: CandleBar, tf: string, context: string): void {
+  if (!isDevMode()) return;
+
+  const expected = getCalendarBucketStart(bar.timeMs, tf);
+  if (bar.timeMs !== expected) {
+    violation(
+      context,
+      `timeMs(${bar.timeMs}) ≠ bucketStart(${expected}) for tf=${tf} ` +
+      `(delta=${bar.timeMs - expected} ms)`,
+    );
+  }
+}
+
+/**
+ * Verify that we are NOT about to mutate a candle that has already been finalised
+ * (`isClosed === true`).  Mutating a closed candle corrupts the historical record.
+ *
+ * Triggers on: same-bucket update landing on a bar already marked closed.
+ */
+export function assertNotFinalized(bar: CandleBar, context: string): void {
+  if (!isDevMode()) return;
+
+  if (bar.isClosed) {
+    violation(
+      context,
+      `attempted to mutate a finalized (isClosed=true) candle at timeMs=${bar.timeMs}`,
+    );
+  }
+}
+
+/**
+ * Verify that a same-bucket update did NOT silently overwrite the candle's `open`.
+ *
+ * The first tick's open is authoritative; subsequent updates for the same bucket
+ * must preserve it.  Call this AFTER the in-place mutation with the captured
+ * `prevOpen` value.
+ */
+export function assertOpenImmutability(
+  prevOpen: number,
+  bar: CandleBar,
+  context: string,
+): void {
+  if (!isDevMode()) return;
+
+  if (bar.open !== prevOpen) {
+    violation(
+      context,
+      `open changed from ${prevOpen} → ${bar.open} on same-bucket update ` +
+      `at timeMs=${bar.timeMs} — first-tick open is authoritative`,
+    );
+  }
+}
+
+/**
+ * Verify that a same-bucket update does NOT append a new bar instead of
+ * updating the existing one.
+ *
+ * Call after an in-place update with the pre- and post-update bar counts.
+ */
+export function assertNoDuplicateAppend(
+  prevCount: number,
+  nextCount: number,
+  context: string,
+): void {
+  if (!isDevMode()) return;
+
+  if (nextCount > prevCount) {
+    violation(
+      context,
+      `same-bucket update incremented bar count from ${prevCount} → ${nextCount} ` +
+      `(should have updated in-place, not appended)`,
+    );
+  }
+}
+
+/**
+ * Verify that a new-bucket append does NOT reduce the bar count or silently
+ * overwrite a finalized candle (would require bar count to stay the same while
+ * the last bar's timeMs changes, which the engine never does).
+ *
+ * Call after appending a new bar with the previous last bar for comparison.
+ */
+export function assertFinalizedUnchanged(
+  prevLastBar: Readonly<CandleBar>,
+  currentBars: readonly CandleBar[],
+  context: string,
+): void {
+  if (!isDevMode()) return;
+
+  const prevIndex = currentBars.findIndex(b => b.timeMs === prevLastBar.timeMs);
+  if (prevIndex === -1) return; // bar may have been legitimately removed by merge
+
+  const preserved = currentBars[prevIndex]!;
+  if (!preserved.isClosed) {
+    violation(
+      context,
+      `bar at timeMs=${prevLastBar.timeMs} should be isClosed=true after new-bucket append`,
+    );
+  }
+}

package/src/engine/mergeUtils.ts

@@ -0,0 +1,93 @@
+/**
+ * Merge / reconciliation helpers for the candle engine.
+ *
+ * These utilities operate on plain data objects and have no side-effects,
+ * making them easy to test and reuse.
+ */
+
+/**
+ * Normalised candle shape.  Defined here so that mergeUtils has no dependency
+ * on CandleEngine (avoids circular imports).  CandleEngine re-exports this type.
+ */
+export interface CandleBar {
+  /** Candle open-time in milliseconds — the primary bucket key. */
+  timeMs: number;
+  /** Candle open-time in seconds — passed directly to the chart library. */
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+  /** True once the next candle has started and this bar is fully formed. */
+  isClosed: boolean;
+}
+
+/**
+ * Count the number of missing candle buckets between two consecutive bar times.
+ *
+ * Returns 0 when bars are adjacent (no gap), ≥1 when candles are missing.
+ *
+ * @example
+ * getMissingBarCount(60_000,  120_000, 60_000)  // → 0  (consecutive 1m bars)
+ * getMissingBarCount(60_000,  240_000, 60_000)  // → 2  (10:01 and 10:02 missing)
+ * getMissingBarCount(60_000, 3_660_000, 60_000) // → 59 (whole hour gap)
+ */
+export function getMissingBarCount(
+  lastTimeMs: number,
+  nextTimeMs: number,
+  intervalMs: number,
+): number {
+  return Math.max(0, Math.floor((nextTimeMs - lastTimeMs) / intervalMs) - 1);
+}
+
+/**
+ * Merge two candle arrays into a single deduplicated, time-sorted array.
+ *
+ * Conflict resolution when both arrays contain a bar with the same `timeMs`:
+ *   - Closed bars from `incoming` always override `existing` candles —
+ *     REST-fetched data is treated as authoritative for finished candles.
+ *   - The live (open) candle: `incoming` also wins — it is the freshest tick.
+ *
+ * This covers both gap backfill (REST data fills missing closed bars) and
+ * reconnect reconciliation (recent REST window corrects stale candles).
+ *
+ * @param existing   Current engine bar array (read-only — not mutated).
+ * @param incoming   New bars to merge in (read-only — not mutated).
+ * @returns A new sorted array with duplicates removed.
+ */
+export function mergeBars(
+  existing: readonly CandleBar[],
+  incoming: readonly CandleBar[],
+): CandleBar[] {
+  const map = new Map<number, CandleBar>();
+
+  // Load existing bars first
+  for (const bar of existing) {
+    map.set(bar.timeMs, bar);
+  }
+
+  // Incoming bars override based on conflict resolution rules
+  for (const bar of incoming) {
+    const prev = map.get(bar.timeMs);
+    // Incoming wins when:
+    //   a) no previous bar at this time (simple insert)
+    //   b) previous bar is closed — REST data is authoritative for closed candles
+    //   c) incoming bar is open (live) — always prefer the latest live tick
+    if (!prev || prev.isClosed || !bar.isClosed) {
+      map.set(bar.timeMs, bar);
+    }
+  }
+
+  return Array.from(map.values()).sort((a, b) => a.timeMs - b.timeMs);
+}
+
+/**
+ * Deduplicate a single sorted array by `timeMs`, keeping the last occurrence
+ * of any duplicate (latest data wins).
+ */
+export function deduplicateBars(bars: CandleBar[]): CandleBar[] {
+  const map = new Map<number, CandleBar>();
+  for (const bar of bars) map.set(bar.timeMs, bar);
+  return Array.from(map.values()).sort((a, b) => a.timeMs - b.timeMs);
+}