@forgecharts/sdk 1.1.23 → 1.1.28

package/dist/tools/barDivergenceCheck.d.ts

@@ -0,0 +1,120 @@
+/**
+ * First-Divergence Bar Comparison Tool
+ *
+ * Compares OHLCV bars from multiple data sources (provider REST, database,
+ * aggregated from 1m, SDK engine) and reports the **first** mismatch found.
+ *
+ * Usage:
+ *
+ *   import { compareSources, checkAllSources, formatReport } from '@forgecharts/sdk/tools/barDivergenceCheck';
+ *
+ *   const report = compareSources(
+ *     { source: 'provider',   bars: providerBars   },
+ *     { source: 'database',   bars: databaseBars   },
+ *     '1h',
+ *     'BINANCE:BTCUSDT',
+ *     from,
+ *     to,
+ *   );
+ *
+ *   if (report.diverged) console.log(formatReport(report));
+ *
+ * All bar arrays are expected to contain Unix **second** timestamps in the
+ * `time` field (matching the CandleBar.time convention).  Use `from`/`to`
+ * as Unix seconds to scope the comparison window.
+ */
+/** Identifies which pipeline stage produced a bar array. */
+export type BarSource = 'provider' | 'database' | 'aggregated' | 'sdk';
+/** Minimal OHLCV shape accepted by the divergence checker. */
+export interface OhlcvBar {
+    /** Unix seconds (same as CandleBar.time). */
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/** A labelled set of bars from one pipeline source. */
+export interface SourceBars {
+    source: BarSource;
+    bars: readonly OhlcvBar[];
+}
+/** A single field-level difference between two bars at the same timestamp. */
+export interface FieldDiff {
+    field: 'open' | 'high' | 'low' | 'close' | 'volume';
+    valueA: number;
+    valueB: number;
+    /** valueA − valueB */
+    delta: number;
+}
+/** Full description of a single mismatched candle. */
+export interface BarMismatch {
+    /** Unix seconds — the candle open time where divergence was first detected. */
+    time: number;
+    /** Canonical candle-open boundary in milliseconds for the given timeframe. */
+    bucketStartMs: number;
+    sourceA: BarSource;
+    sourceB: BarSource;
+    /** OHLCV field deltas — empty when the only problem is a missing bar. */
+    differences: FieldDiff[];
+    /**
+     * True when the two bars carry the same `time` but their canonical
+     * `bucketStart` values differ — indicates a misaligned timestamp on one side.
+     */
+    bucketMismatch: boolean;
+    /** Human-readable diagnostic notes. */
+    notes: string[];
+}
+/** Summary of a pairwise source comparison. */
+export interface DivergenceReport {
+    symbol: string;
+    timeframe: string;
+    /** Unix seconds — inclusive window start. */
+    from: number;
+    /** Unix seconds — inclusive window end. */
+    to: number;
+    diverged: boolean;
+    /** The first mismatch found, or null when the sources are identical. */
+    firstMismatch: BarMismatch | null;
+    totalMismatches: number;
+    /** Number of bars from source A inside [from, to]. */
+    sourceACount: number;
+    /** Number of bars from source B inside [from, to]. */
+    sourceBCount: number;
+}
+/**
+ * Compare all timestamps from both sources inside [from, to] and return the
+ * first mismatch found, scanning oldest-first.
+ *
+ * Mismatch criteria (any one triggers a report):
+ *   1. Bar present in one source but absent in the other.
+ *   2. OHLCV field values differ by more than floating-point epsilon.
+ *   3. Canonical `getBucketStart` for the bar's time differs between sources
+ *      (indicates one source has a misaligned timestamp).
+ *
+ * @param a          Source A bars.
+ * @param b          Source B bars.
+ * @param timeframe  Canonical timeframe label (e.g. `'1h'`, `'1w'`).
+ * @param symbol     Symbol string — stored in the report for identification.
+ * @param from       Window start, Unix seconds (inclusive).
+ * @param to         Window end, Unix seconds (inclusive).
+ */
+export declare function compareSources(a: SourceBars, b: SourceBars, timeframe: string, symbol: string, from: number, to: number): DivergenceReport;
+/**
+ * Run all pairwise comparisons across every combination of the provided sources.
+ *
+ * For N sources this produces N*(N-1)/2 reports.  Use `formatReport` to render
+ * each one for console output.
+ */
+export declare function checkAllSources(sources: SourceBars[], symbol: string, timeframe: string, from: number, to: number): DivergenceReport[];
+/**
+ * Render a `DivergenceReport` as a multi-line human-readable string suitable
+ * for console output or log files.
+ *
+ * @example
+ * const report = compareSources(a, b, '1h', 'BINANCE:BTCUSDT', from, to);
+ * console.log(formatReport(report));
+ */
+export declare function formatReport(report: DivergenceReport): string;
+//# sourceMappingURL=barDivergenceCheck.d.ts.map

package/dist/tools/barDivergenceCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barDivergenceCheck.d.ts","sourceRoot":"","sources":["../../src/tools/barDivergenceCheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,4DAA4D;AAC5D,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,KAAK,CAAC;AAEvE,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,SAAS,CAAC;IACnB,yEAAyE;IACzE,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,uCAAuC;IACvC,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;CACtB;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,gBAAgB,CAmGlB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,gBAAgB,EAAE,CAQpB;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CA6B7D"}

package/dist/tools/barDivergenceCheck.js

@@ -0,0 +1,200 @@
+/**
+ * First-Divergence Bar Comparison Tool
+ *
+ * Compares OHLCV bars from multiple data sources (provider REST, database,
+ * aggregated from 1m, SDK engine) and reports the **first** mismatch found.
+ *
+ * Usage:
+ *
+ *   import { compareSources, checkAllSources, formatReport } from '@forgecharts/sdk/tools/barDivergenceCheck';
+ *
+ *   const report = compareSources(
+ *     { source: 'provider',   bars: providerBars   },
+ *     { source: 'database',   bars: databaseBars   },
+ *     '1h',
+ *     'BINANCE:BTCUSDT',
+ *     from,
+ *     to,
+ *   );
+ *
+ *   if (report.diverged) console.log(formatReport(report));
+ *
+ * All bar arrays are expected to contain Unix **second** timestamps in the
+ * `time` field (matching the CandleBar.time convention).  Use `from`/`to`
+ * as Unix seconds to scope the comparison window.
+ */
+import { getBucketStart } from '@forgecharts/shared';
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Index bars by their Unix-second open time for O(1) lookup. */
+function indexByTime(bars) {
+    const map = new Map();
+    for (const bar of bars) {
+        // Last-write-wins if the source has duplicate timestamps
+        map.set(bar.time, bar);
+    }
+    return map;
+}
+/**
+ * Compare two numeric values with a floating-point epsilon tolerance.
+ * Returns true when they differ by more than the tolerance.
+ */
+function differ(a, b, eps = 1e-9) {
+    return Math.abs(a - b) > eps;
+}
+// ─── Core comparison ──────────────────────────────────────────────────────────
+/**
+ * Compare all timestamps from both sources inside [from, to] and return the
+ * first mismatch found, scanning oldest-first.
+ *
+ * Mismatch criteria (any one triggers a report):
+ *   1. Bar present in one source but absent in the other.
+ *   2. OHLCV field values differ by more than floating-point epsilon.
+ *   3. Canonical `getBucketStart` for the bar's time differs between sources
+ *      (indicates one source has a misaligned timestamp).
+ *
+ * @param a          Source A bars.
+ * @param b          Source B bars.
+ * @param timeframe  Canonical timeframe label (e.g. `'1h'`, `'1w'`).
+ * @param symbol     Symbol string — stored in the report for identification.
+ * @param from       Window start, Unix seconds (inclusive).
+ * @param to         Window end, Unix seconds (inclusive).
+ */
+export function compareSources(a, b, timeframe, symbol, from, to) {
+    const aIndex = indexByTime(a.bars);
+    const bIndex = indexByTime(b.bars);
+    // All timestamps seen in either source, filtered to the requested window
+    const allTimes = new Set([...aIndex.keys(), ...bIndex.keys()]);
+    const sortedTimes = Array.from(allTimes)
+        .filter(t => t >= from && t <= to)
+        .sort((x, y) => x - y);
+    let totalMismatches = 0;
+    let firstMismatch = null;
+    const countA = a.bars.filter(bar => bar.time >= from && bar.time <= to).length;
+    const countB = b.bars.filter(bar => bar.time >= from && bar.time <= to).length;
+    for (const time of sortedTimes) {
+        const barA = aIndex.get(time);
+        const barB = bIndex.get(time);
+        // ── Missing bar ────────────────────────────────────────────────────────
+        if (!barA || !barB) {
+            totalMismatches++;
+            if (!firstMismatch) {
+                const notes = [];
+                if (!barA)
+                    notes.push(`${a.source} is missing bar at time=${time}`);
+                if (!barB)
+                    notes.push(`${b.source} is missing bar at time=${time}`);
+                firstMismatch = {
+                    time,
+                    bucketStartMs: getBucketStart(time * 1000, timeframe),
+                    sourceA: a.source,
+                    sourceB: b.source,
+                    differences: [],
+                    bucketMismatch: false,
+                    notes,
+                };
+            }
+            continue;
+        }
+        // ── OHLCV field comparison ─────────────────────────────────────────────
+        const diffs = [];
+        const OHLCV_FIELDS = [
+            'open', 'high', 'low', 'close', 'volume',
+        ];
+        for (const field of OHLCV_FIELDS) {
+            const vA = barA[field] ?? 0;
+            const vB = barB[field] ?? 0;
+            if (differ(vA, vB)) {
+                diffs.push({ field, valueA: vA, valueB: vB, delta: vA - vB });
+            }
+        }
+        // ── Bucket alignment comparison ────────────────────────────────────────
+        const bucketA = getBucketStart(barA.time * 1000, timeframe);
+        const bucketB = getBucketStart(barB.time * 1000, timeframe);
+        const bucketMismatch = bucketA !== bucketB;
+        const notes = [];
+        if (bucketMismatch) {
+            notes.push(`bucket start mismatch: ${a.source}=${bucketA}ms vs ${b.source}=${bucketB}ms ` +
+                `(delta=${bucketA - bucketB} ms)`);
+        }
+        for (const diff of diffs) {
+            notes.push(`${diff.field}: ${a.source}=${diff.valueA} vs ${b.source}=${diff.valueB} ` +
+                `(delta=${diff.delta.toPrecision(6)})`);
+        }
+        if (diffs.length > 0 || bucketMismatch) {
+            totalMismatches++;
+            if (!firstMismatch) {
+                firstMismatch = {
+                    time,
+                    bucketStartMs: bucketA,
+                    sourceA: a.source,
+                    sourceB: b.source,
+                    differences: diffs,
+                    bucketMismatch,
+                    notes,
+                };
+            }
+        }
+    }
+    return {
+        symbol,
+        timeframe,
+        from,
+        to,
+        diverged: totalMismatches > 0,
+        firstMismatch,
+        totalMismatches,
+        sourceACount: countA,
+        sourceBCount: countB,
+    };
+}
+/**
+ * Run all pairwise comparisons across every combination of the provided sources.
+ *
+ * For N sources this produces N*(N-1)/2 reports.  Use `formatReport` to render
+ * each one for console output.
+ */
+export function checkAllSources(sources, symbol, timeframe, from, to) {
+    const reports = [];
+    for (let i = 0; i < sources.length; i++) {
+        for (let j = i + 1; j < sources.length; j++) {
+            reports.push(compareSources(sources[i], sources[j], timeframe, symbol, from, to));
+        }
+    }
+    return reports;
+}
+// ─── Formatter ───────────────────────────────────────────────────────────────
+/**
+ * Render a `DivergenceReport` as a multi-line human-readable string suitable
+ * for console output or log files.
+ *
+ * @example
+ * const report = compareSources(a, b, '1h', 'BINANCE:BTCUSDT', from, to);
+ * console.log(formatReport(report));
+ */
+export function formatReport(report) {
+    const lines = [];
+    const status = report.diverged
+        ? `DIVERGED (${report.totalMismatches} mismatch${report.totalMismatches === 1 ? '' : 'es'})`
+        : 'IDENTICAL';
+    lines.push('─'.repeat(72));
+    lines.push(`Bar Divergence Report — ${status}`);
+    lines.push(`  Symbol    : ${report.symbol}`);
+    lines.push(`  Timeframe : ${report.timeframe}`);
+    lines.push(`  Window    : ${report.from} → ${report.to} (Unix seconds)`);
+    lines.push(`  Bars      : sourceA=${report.sourceACount}  sourceB=${report.sourceBCount}`);
+    if (report.firstMismatch) {
+        const m = report.firstMismatch;
+        lines.push('');
+        lines.push(`  First mismatch at time=${m.time} (bucketStart=${m.bucketStartMs} ms)`);
+        lines.push(`  Sources  : ${m.sourceA}  vs  ${m.sourceB}`);
+        if (m.bucketMismatch) {
+            lines.push(`  ✗ Bucket alignment differs`);
+        }
+        for (const note of m.notes) {
+            lines.push(`  · ${note}`);
+        }
+    }
+    lines.push('─'.repeat(72));
+    return lines.join('\n');
+}
+//# sourceMappingURL=barDivergenceCheck.js.map

package/dist/tools/barDivergenceCheck.js.map

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

package/dist/trading/TradingOverlayStore.d.ts

@@ -0,0 +1,86 @@
+/**
+ * TradingOverlayStore
+ *
+ * Shared, mode-agnostic store for trade overlay state.
+ * Used by both unmanaged mode (externally supplied data) and managed mode
+ * (internally generated data from the managed trading service).
+ *
+ * Supports:
+ *   - Full replace  (setOrders / setPositions)
+ *   - Incremental   (upsertOrder / upsertPosition / pushExecution)
+ *   - Remove by id  (removeOrder / removePosition)
+ *
+ * Subscribers are notified via callbacks registered with onChange().
+ * The store is intentionally free of React/DOM dependencies so it can be
+ * consumed from any rendering layer (canvas, React, etc.).
+ *
+ * @example
+ * ```ts
+ * const store = new TradingOverlayStore();
+ *
+ * // Subscribe to changes (e.g. trigger a canvas repaint)
+ * store.onChange(() => chart.markDirty());
+ *
+ * // Feed data
+ * store.setOrders([...]);
+ * store.upsertOrder({ id: 'o1', role: 'entry', side: 'buy', ... });
+ * store.removeOrder('o1');
+ * ```
+ */
+import type { ChartOrder, ChartPosition, ExecutionFill } from './tradingTypes';
+type ChangeListener = () => void;
+export declare class TradingOverlayStore {
+    private _orders;
+    private _positions;
+    private _fills;
+    private _listeners;
+    /**
+     * Register a callback that fires whenever any state changes.
+     * Returns an unsubscribe function.
+     */
+    onChange(listener: ChangeListener): () => void;
+    private _notify;
+    /** Replace the entire order set. */
+    setOrders(orders: ChartOrder[]): void;
+    /**
+     * Insert or replace a single order.
+     * Matching is done by `order.id`.
+     */
+    upsertOrder(order: ChartOrder): void;
+    /** Remove an order by id. Silent no-op if not found. */
+    removeOrder(orderId: string): void;
+    /** Returns a snapshot of all orders as an array (insertion order). */
+    getOrders(): ChartOrder[];
+    /** Returns orders that share the given `groupId`. */
+    getOrdersByGroup(groupId: string): ChartOrder[];
+    /** Replace the entire position set. */
+    setPositions(positions: ChartPosition[]): void;
+    /**
+     * Insert or replace a single position.
+     * Matching is done by `position.id`.
+     */
+    upsertPosition(position: ChartPosition): void;
+    /** Remove a position by id. Silent no-op if not found. */
+    removePosition(positionId: string): void;
+    /** Returns a snapshot of all positions as an array (insertion order). */
+    getPositions(): ChartPosition[];
+    /**
+     * Append an execution fill to the fill log.
+     * Fills are append-only — they are never updated or removed.
+     */
+    pushExecution(fill: ExecutionFill): void;
+    /** Returns all fills in insertion (chronological) order. */
+    getFills(): readonly ExecutionFill[];
+    /** Returns fills associated with a specific order id. */
+    getFillsByOrder(orderId: string): ExecutionFill[];
+    /** Wipes all overlay state (orders, positions, fills). */
+    clear(): void;
+    /** Returns the full overlay state as a plain object — useful for debug / serialisation. */
+    snapshot(): {
+        orders: ChartOrder[];
+        positions: ChartPosition[];
+        fills: readonly ExecutionFill[];
+    };
+}
+export {};
+//# sourceMappingURL=TradingOverlayStore.d.ts.map

package/dist/trading/TradingOverlayStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TradingOverlayStore.d.ts","sourceRoot":"","sources":["../../src/trading/TradingOverlayStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/E,KAAK,cAAc,GAAG,MAAM,IAAI,CAAC;AAEjC,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,MAAM,CAA4B;IAE1C,OAAO,CAAC,UAAU,CAAwB;IAI1C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI;IAO9C,OAAO,CAAC,OAAO;IAMf,oCAAoC;IACpC,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI;IAMrC;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAKpC,wDAAwD;IACxD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlC,sEAAsE;IACtE,SAAS,IAAI,UAAU,EAAE;IAIzB,qDAAqD;IACrD,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE;IAM/C,uCAAuC;IACvC,YAAY,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI;IAM9C;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAK7C,0DAA0D;IAC1D,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIxC,yEAAyE;IACzE,YAAY,IAAI,aAAa,EAAE;IAM/B;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAKxC,4DAA4D;IAC5D,QAAQ,IAAI,SAAS,aAAa,EAAE;IAIpC,yDAAyD;IACzD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE;IAMjD,0DAA0D;IAC1D,KAAK,IAAI,IAAI;IASb,2FAA2F;IAC3F,QAAQ,IAAI;QAAE,MAAM,EAAE,UAAU,EAAE,CAAC;QAAC,SAAS,EAAE,aAAa,EAAE,CAAC;QAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;KAAE;CAOlG"}

package/dist/trading/TradingOverlayStore.js

@@ -0,0 +1,139 @@
+/**
+ * TradingOverlayStore
+ *
+ * Shared, mode-agnostic store for trade overlay state.
+ * Used by both unmanaged mode (externally supplied data) and managed mode
+ * (internally generated data from the managed trading service).
+ *
+ * Supports:
+ *   - Full replace  (setOrders / setPositions)
+ *   - Incremental   (upsertOrder / upsertPosition / pushExecution)
+ *   - Remove by id  (removeOrder / removePosition)
+ *
+ * Subscribers are notified via callbacks registered with onChange().
+ * The store is intentionally free of React/DOM dependencies so it can be
+ * consumed from any rendering layer (canvas, React, etc.).
+ *
+ * @example
+ * ```ts
+ * const store = new TradingOverlayStore();
+ *
+ * // Subscribe to changes (e.g. trigger a canvas repaint)
+ * store.onChange(() => chart.markDirty());
+ *
+ * // Feed data
+ * store.setOrders([...]);
+ * store.upsertOrder({ id: 'o1', role: 'entry', side: 'buy', ... });
+ * store.removeOrder('o1');
+ * ```
+ */
+export class TradingOverlayStore {
+    _orders = new Map();
+    _positions = new Map();
+    _fills = [];
+    _listeners = [];
+    // ── Change subscription ──────────────────────────────────────────────────────
+    /**
+     * Register a callback that fires whenever any state changes.
+     * Returns an unsubscribe function.
+     */
+    onChange(listener) {
+        this._listeners.push(listener);
+        return () => {
+            this._listeners = this._listeners.filter(l => l !== listener);
+        };
+    }
+    _notify() {
+        for (const l of this._listeners)
+            l();
+    }
+    // ── Orders ───────────────────────────────────────────────────────────────────
+    /** Replace the entire order set. */
+    setOrders(orders) {
+        this._orders.clear();
+        for (const o of orders)
+            this._orders.set(o.id, o);
+        this._notify();
+    }
+    /**
+     * Insert or replace a single order.
+     * Matching is done by `order.id`.
+     */
+    upsertOrder(order) {
+        this._orders.set(order.id, order);
+        this._notify();
+    }
+    /** Remove an order by id. Silent no-op if not found. */
+    removeOrder(orderId) {
+        if (this._orders.delete(orderId))
+            this._notify();
+    }
+    /** Returns a snapshot of all orders as an array (insertion order). */
+    getOrders() {
+        return Array.from(this._orders.values());
+    }
+    /** Returns orders that share the given `groupId`. */
+    getOrdersByGroup(groupId) {
+        return this.getOrders().filter(o => o.groupId === groupId);
+    }
+    // ── Positions ────────────────────────────────────────────────────────────────
+    /** Replace the entire position set. */
+    setPositions(positions) {
+        this._positions.clear();
+        for (const p of positions)
+            this._positions.set(p.id, p);
+        this._notify();
+    }
+    /**
+     * Insert or replace a single position.
+     * Matching is done by `position.id`.
+     */
+    upsertPosition(position) {
+        this._positions.set(position.id, position);
+        this._notify();
+    }
+    /** Remove a position by id. Silent no-op if not found. */
+    removePosition(positionId) {
+        if (this._positions.delete(positionId))
+            this._notify();
+    }
+    /** Returns a snapshot of all positions as an array (insertion order). */
+    getPositions() {
+        return Array.from(this._positions.values());
+    }
+    // ── Fills ────────────────────────────────────────────────────────────────────
+    /**
+     * Append an execution fill to the fill log.
+     * Fills are append-only — they are never updated or removed.
+     */
+    pushExecution(fill) {
+        this._fills.push(fill);
+        this._notify();
+    }
+    /** Returns all fills in insertion (chronological) order. */
+    getFills() {
+        return this._fills;
+    }
+    /** Returns fills associated with a specific order id. */
+    getFillsByOrder(orderId) {
+        return this._fills.filter(f => f.orderId === orderId);
+    }
+    // ── Bulk clear ───────────────────────────────────────────────────────────────
+    /** Wipes all overlay state (orders, positions, fills). */
+    clear() {
+        this._orders.clear();
+        this._positions.clear();
+        this._fills = [];
+        this._notify();
+    }
+    // ── Snapshot ─────────────────────────────────────────────────────────────────
+    /** Returns the full overlay state as a plain object — useful for debug / serialisation. */
+    snapshot() {
+        return {
+            orders: this.getOrders(),
+            positions: this.getPositions(),
+            fills: this.getFills(),
+        };
+    }
+}
+//# sourceMappingURL=TradingOverlayStore.js.map

package/dist/trading/TradingOverlayStore.js.map

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

package/dist/trading/UnmanagedIngestion.d.ts

@@ -0,0 +1,91 @@
+/**
+ * UnmanagedIngestion
+ *
+ * External candle data ingestion for unmanaged mode.
+ *
+ * In unmanaged mode the client owns their data pipeline. They pass
+ * normalised candle data to us; this layer validates the license gate,
+ * delegates to the existing CandleEngine for bucket management, and
+ * notifies callers via callbacks mirroring the CandleEngine contract.
+ *
+ * Critical constraint: the default RapidAPI-backed datafeed is completely
+ * untouched. UnmanagedIngestion is an additive, opt-in path.
+ *
+ * Candle rules (matches CandleEngine behaviour):
+ *   same timeMs   → update current candle
+ *   newer timeMs  → append / new bucket
+ *   older timeMs  → silently ignored (logged in debug mode)
+ *
+ * @example
+ * ```ts
+ * const ingestion = new UnmanagedIngestion('1m', {
+ *   onBarUpdated: (bar) => series.update(bar),
+ *   onResync:     (bars) => series.setData(bars),
+ * });
+ *
+ * // Feed a full history snapshot first
+ * ingestion.setHistory(historicalBars);
+ *
+ * // Then stream live ticks
+ * ingestion.pushCandle(latestBar);
+ * ```
+ */
+import type { CandleBar, UpdateResult, GapInfo } from '../engine/CandleEngine';
+import type { CandleInput } from './tradingTypes';
+import type { Timeframe } from '@forgecharts/types';
+export interface UnmanagedIngestionOptions {
+    /** Enable debug logging on the underlying CandleEngine. */
+    debug?: boolean;
+    /**
+     * Fired after every bar mutation (update or append from a live push).
+     * Corresponds to CandleEngine.onBarUpdated.
+     */
+    onBarUpdated?: (bar: CandleBar, result: UpdateResult) => void;
+    /**
+     * Fired when the full bar array changes (after setHistory or gap backfill).
+     * The chart adapter should call `series.setData(bars)`.
+     */
+    onResync?: (bars: readonly CandleBar[]) => void;
+    /** Fired when a candle bucket closes. */
+    onBarClosed?: (bar: CandleBar) => void;
+    /** Fired when the engine detects skipped buckets in the live stream. */
+    onGapDetected?: (info: GapInfo) => void;
+}
+export declare class UnmanagedIngestion {
+    private readonly _engine;
+    private readonly _opts;
+    private _timeframe;
+    constructor(timeframe: Timeframe, opts?: UnmanagedIngestionOptions);
+    private _assertUnmanaged;
+    /**
+     * Load a full historical bar snapshot.
+     * Replaces the engine's bar array and triggers `onResync` so the chart
+     * series is fully redrawn.
+     *
+     * Call this once at startup (or on symbol/interval change) before
+     * streaming live candles via `pushCandle`.
+     *
+     * @throws If the active license is not in unmanaged mode.
+     */
+    setHistory(bars: CandleInput[]): void;
+    /**
+     * Push a single live candle tick.
+     *
+     * Behaviour follows CandleEngine rules:
+     *   - same bucket  → updates existing bar (OHLCV merging)
+     *   - new bucket   → appends a new bar (previous bar is finalised)
+     *   - older bucket → silently ignored; debug-logged when `debug: true`
+     *
+     * @throws If the active license is not in unmanaged mode.
+     */
+    pushCandle(bar: CandleInput): UpdateResult;
+    /** Returns the current bar array (chronological, ascending). */
+    getBars(): readonly CandleBar[];
+    /** Returns the latest candle, or null if no data has been loaded. */
+    getLatestBar(): CandleBar | null;
+    /** Changes the active timeframe and clears all bar data. */
+    setTimeframe(timeframe: Timeframe): void;
+    /** Clears all bars (e.g. on symbol change before calling setHistory again). */
+    reset(): void;
+}
+//# sourceMappingURL=UnmanagedIngestion.d.ts.map

package/dist/trading/UnmanagedIngestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnmanagedIngestion.d.ts","sourceRoot":"","sources":["../../src/trading/UnmanagedIngestion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAE9D;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,KAAK,IAAI,CAAC;IAEhD,yCAAyC;IACzC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,IAAI,CAAC;IAEvC,wEAAwE;IACxE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACzC;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,UAAU,CAAY;gBAElB,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE,yBAA8B;IAgBtE,OAAO,CAAC,gBAAgB;IAWxB;;;;;;;;;OASG;IACH,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,IAAI;IAYrC;;;;;;;;;OASG;IACH,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY;IAO1C,gEAAgE;IAChE,OAAO,IAAI,SAAS,SAAS,EAAE;IAI/B,qEAAqE;IACrE,YAAY,IAAI,SAAS,GAAG,IAAI;IAKhC,4DAA4D;IAC5D,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAMxC,+EAA+E;IAC/E,KAAK,IAAI,IAAI;CAGd"}