@senpi/trading-runtime 1.0.0

package/dist/scanners/engine/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../src/scanners/engine/lifecycle.ts"],"names":[],"mappings":""}

package/dist/scanners/engine/result-builder.d.ts

@@ -0,0 +1,30 @@
+import type { PersistencePolicy } from "../scanner-definition.js";
+import type { ScanResult, ScannerScanOutput, ScanStatus, ScannerId, Signal } from "../types.js";
+import type { ScanContext } from "../protocol/context.js";
+import type { StrategyScannerRegistration } from "./strategy-registry.js";
+/**
+ * Builds a normalized ScanResult from raw scanner output.
+ * Handles signal normalization, score enforcement, and actionability checks.
+ */
+export declare function buildRunResult(entry: StrategyScannerRegistration, context: ScanContext<unknown, unknown>, output: ScannerScanOutput, now: () => number, logger?: {
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+}): ScanResult;
+/** Determines whether a scan result should be persisted based on the scanner's persistence policy. */
+export declare function shouldPersist(policy: PersistencePolicy, result: ScanResult): boolean;
+/** Constructs a ScanResult with default values for optional fields. */
+export declare function buildResult(params: {
+    address: string;
+    scannerId: ScannerId;
+    timestamp: number;
+    status: ScanStatus;
+    signals?: Signal[];
+    actionableCount?: number;
+    scannedCount?: number;
+    reason?: string;
+    summary: Record<string, unknown>;
+}): ScanResult;
+export declare function coerceTimestamp(value: number, fallback: number): number;
+export declare function coerceCount(value: number, fallback: number): number;
+export declare function formatError(error: unknown): string;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=result-builder.d.ts.map

package/dist/scanners/engine/result-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-builder.d.ts","sourceRoot":"","sources":["../../../src/scanners/engine/result-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,2BAA2B,EAClC,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,MAAM,EAAE,iBAAiB,EACzB,GAAG,EAAE,MAAM,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAAE,GAC5E,UAAU,CAqBZ;AAED,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAWpF;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,UAAU,CAYb;AA4DD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKnE;AAcD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQlD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE"}

package/dist/scanners/engine/result-builder.js

@@ -0,0 +1,129 @@
+import { PersistencePolicy as PersistencePolicyEnum } from "../scanner-definition.js";
+import { enforceScoreRange } from "../score-utils.js";
+import { ScanStatus as ScanStatusEnum } from "../types.js";
+/**
+ * Builds a normalized ScanResult from raw scanner output.
+ * Handles signal normalization, score enforcement, and actionability checks.
+ */
+export function buildRunResult(entry, context, output, now, logger) {
+    const fallbackTimestamp = now();
+    const outputTimestamp = coerceTimestamp(output.timestamp, fallbackTimestamp);
+    const signals = output.signals.map((signal) => normalizeSignal(signal, entry, outputTimestamp, logger));
+    const actionableCount = signals.filter((signal) => isActionable(entry, signal, context, logger)).length;
+    return buildResult({
+        address: entry.address,
+        scannerId: entry.scanner.definition.id,
+        timestamp: outputTimestamp,
+        status: signals.length > 0 ? ScanStatusEnum.OK : ScanStatusEnum.HEARTBEAT,
+        signals,
+        actionableCount,
+        scannedCount: coerceCount(output.scannedCount, signals.length),
+        reason: output.reason,
+        summary: isRecord(output.summary) ? output.summary : {},
+    });
+}
+/** Determines whether a scan result should be persisted based on the scanner's persistence policy. */
+export function shouldPersist(policy, result) {
+    switch (policy) {
+        case PersistencePolicyEnum.ALWAYS:
+            return true;
+        case PersistencePolicyEnum.ACTIONABLE_ONLY:
+            return result.actionableCount > 0;
+        case PersistencePolicyEnum.NEVER:
+            return false;
+        default:
+            return false;
+    }
+}
+/** Constructs a ScanResult with default values for optional fields. */
+export function buildResult(params) {
+    return {
+        address: params.address,
+        scannerId: params.scannerId,
+        timestamp: params.timestamp,
+        status: params.status,
+        signals: params.signals ?? [],
+        actionableCount: params.actionableCount ?? 0,
+        scannedCount: params.scannedCount ?? 0,
+        reason: params.reason,
+        summary: params.summary,
+    };
+}
+/** Normalizes a raw scanner signal: enforces score range, defaults fields. */
+function normalizeSignal(signal, entry, fallbackTimestamp, logger) {
+    return {
+        ...signal,
+        address: entry.address,
+        scannerId: entry.scanner.definition.id,
+        signalType: signal.signalType || entry.scanner.definition.signalType,
+        timestamp: coerceTimestamp(signal.timestamp, fallbackTimestamp),
+        score: enforceScoreRange(signal.score, scoreLogger(logger), {
+            address: entry.address,
+            scannerId: entry.scanner.definition.id,
+            asset: signal.asset,
+        }),
+        factors: normalizeFactors(signal.factors),
+        meta: isRecord(signal.meta) ? signal.meta : {},
+    };
+}
+/** Checks whether a signal is actionable via hooks or default behavior. */
+function isActionable(entry, signal, context, logger) {
+    if (!entry.scanner.hooks?.isActionable) {
+        return true;
+    }
+    try {
+        return entry.scanner.hooks.isActionable(signal, context);
+    }
+    catch (error) {
+        logger?.warn?.("isActionable hook failed; treating signal as non-actionable.", {
+            address: entry.address,
+            scannerId: entry.scanner.definition.id,
+            error,
+        });
+        return false;
+    }
+}
+function scoreLogger(logger) {
+    const warn = logger?.warn;
+    if (!warn) {
+        return undefined;
+    }
+    return {
+        warn: (message, meta) => warn(message, meta),
+    };
+}
+export function coerceTimestamp(value, fallback) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return fallback;
+    }
+    return value;
+}
+export function coerceCount(value, fallback) {
+    if (!Number.isFinite(value) || value < 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function normalizeFactors(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const factors = {};
+    for (const [key, factorValue] of Object.entries(value)) {
+        factors[key] = Boolean(factorValue);
+    }
+    return factors;
+}
+export function formatError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    return "Unknown scanner error.";
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=result-builder.js.map

package/dist/scanners/engine/result-builder.js.map

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

package/dist/scanners/engine/strategy-registry.d.ts

@@ -0,0 +1,45 @@
+import type { Scanner } from "../protocol/scanner.js";
+import type { ScannerId, StrategyRegistration } from "../types.js";
+/**
+ * One scanner runtime registration scoped to one strategy.
+ * PoC constraint: one instance per scanner id within a strategy.
+ */
+export interface StrategyScannerRegistration<Cfg = unknown, St = unknown> {
+    address: string;
+    strategy: StrategyRegistration;
+    scanner: Scanner<Cfg, St>;
+    enabled: boolean;
+    initialized: boolean;
+    /**
+     * Start timestamp for the current in-flight run.
+     * Null means no active run for this strategy/scanner key.
+     */
+    lastScanTime: number | null;
+    intervalSeconds: number;
+    initialConfig: Cfg;
+    timer: NodeJS.Timeout | null;
+}
+/** In-memory registry for strategy and scanner runtime registrations. */
+export declare class StrategyRegistry {
+    private readonly strategies;
+    private readonly scanners;
+    /** Registers or updates strategy metadata. */
+    registerStrategy(strategy: StrategyRegistration): void;
+    /** Registers one scanner instance for a strategy. */
+    registerScanner<Cfg = unknown, St = unknown>(address: string, scanner: Scanner<Cfg, St>): StrategyScannerRegistration<Cfg, St>;
+    /** Looks up one scanner registration by strategy address and scanner id. */
+    get<Cfg = unknown, St = unknown>(address: string, scannerId: ScannerId): StrategyScannerRegistration<Cfg, St> | undefined;
+    /** Lists scanner registrations, optionally constrained to one strategy. */
+    list(address?: string): StrategyScannerRegistration[];
+    /** Enables/disables one scanner registration. */
+    setEnabled(address: string, scannerId: ScannerId, enabled: boolean): void;
+    /** Marks whether initialize() has been completed for one scanner registration. */
+    setInitialized(address: string, scannerId: ScannerId, initialized: boolean): void;
+    /** Stores/clears current in-flight run start time for one scanner registration. */
+    setLastScanTime(address: string, scannerId: ScannerId, lastScanTime: number | null): void;
+    /** Stores scheduler handle for one scanner registration. */
+    setTimer(address: string, scannerId: ScannerId, timer: NodeJS.Timeout | null): void;
+    /** Clears and forgets all active scanner timers. */
+    clearAllTimers(): void;
+}
+//# sourceMappingURL=strategy-registry.d.ts.map

package/dist/scanners/engine/strategy-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-registry.d.ts","sourceRoot":"","sources":["../../../src/scanners/engine/strategy-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAc,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE/E;;;GAGG;AACH,MAAM,WAAW,2BAA2B,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,GAAG,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED,yEAAyE;AACzE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+C;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkD;IAE3E,8CAA8C;IAC9C,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAItD,qDAAqD;IACrD,eAAe,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO,EACzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,GACxB,2BAA2B,CAAC,GAAG,EAAE,EAAE,CAAC;IAmCvC,4EAA4E;IAC5E,GAAG,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO,EAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,GACnB,2BAA2B,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,SAAS;IAMnD,2EAA2E;IAC3E,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,2BAA2B,EAAE;IAOrD,iDAAiD;IACjD,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAUzE,kFAAkF;IAClF,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,OAAO,GACnB,IAAI;IAUP,mFAAmF;IACnF,eAAe,CACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,IAAI;IAUP,4DAA4D;IAC5D,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,GAC3B,IAAI;IAUP,oDAAoD;IACpD,cAAc,IAAI,IAAI;CAQvB"}

package/dist/scanners/engine/strategy-registry.js

@@ -0,0 +1,93 @@
+/** In-memory registry for strategy and scanner runtime registrations. */
+export class StrategyRegistry {
+    strategies = new Map();
+    scanners = new Map();
+    /** Registers or updates strategy metadata. */
+    registerStrategy(strategy) {
+        this.strategies.set(strategy.id, strategy);
+    }
+    /** Registers one scanner instance for a strategy. */
+    registerScanner(address, scanner) {
+        const strategy = this.strategies.get(address);
+        if (!strategy) {
+            throw new Error(`Strategy '${address}' is not registered.`);
+        }
+        const key = compositeKey(address, scanner.definition.id);
+        if (this.scanners.has(key)) {
+            throw new Error(`Scanner '${scanner.definition.id}' is already registered for strategy '${address}'.`);
+        }
+        const override = strategy.scannerOverrides?.[scanner.definition.id];
+        const enabled = strategy.defaultEnabledScanners === undefined
+            ? true
+            : strategy.defaultEnabledScanners.includes(scanner.definition.id);
+        const entry = {
+            address,
+            strategy,
+            scanner,
+            enabled,
+            initialized: false,
+            lastScanTime: null,
+            intervalSeconds: override?.intervalSeconds ?? scanner.definition.intervalSeconds,
+            initialConfig: (override?.config ?? scanner.definition.defaultConfig),
+            timer: null,
+        };
+        this.scanners.set(key, entry);
+        return entry;
+    }
+    /** Looks up one scanner registration by strategy address and scanner id. */
+    get(address, scannerId) {
+        return this.scanners.get(compositeKey(address, scannerId));
+    }
+    /** Lists scanner registrations, optionally constrained to one strategy. */
+    list(address) {
+        if (!address) {
+            return [...this.scanners.values()];
+        }
+        return [...this.scanners.values()].filter((entry) => entry.address === address);
+    }
+    /** Enables/disables one scanner registration. */
+    setEnabled(address, scannerId, enabled) {
+        const entry = this.get(address, scannerId);
+        if (!entry) {
+            throw new Error(`Scanner '${scannerId}' is not registered for strategy '${address}'.`);
+        }
+        entry.enabled = enabled;
+    }
+    /** Marks whether initialize() has been completed for one scanner registration. */
+    setInitialized(address, scannerId, initialized) {
+        const entry = this.get(address, scannerId);
+        if (!entry) {
+            throw new Error(`Scanner '${scannerId}' is not registered for strategy '${address}'.`);
+        }
+        entry.initialized = initialized;
+    }
+    /** Stores/clears current in-flight run start time for one scanner registration. */
+    setLastScanTime(address, scannerId, lastScanTime) {
+        const entry = this.get(address, scannerId);
+        if (!entry) {
+            throw new Error(`Scanner '${scannerId}' is not registered for strategy '${address}'.`);
+        }
+        entry.lastScanTime = lastScanTime;
+    }
+    /** Stores scheduler handle for one scanner registration. */
+    setTimer(address, scannerId, timer) {
+        const entry = this.get(address, scannerId);
+        if (!entry) {
+            throw new Error(`Scanner '${scannerId}' is not registered for strategy '${address}'.`);
+        }
+        entry.timer = timer;
+    }
+    /** Clears and forgets all active scanner timers. */
+    clearAllTimers() {
+        for (const entry of this.scanners.values()) {
+            if (entry.timer) {
+                clearInterval(entry.timer);
+                entry.timer = null;
+            }
+        }
+    }
+}
+function compositeKey(address, scannerId) {
+    return `${address}::${scannerId}`;
+}
+//# sourceMappingURL=strategy-registry.js.map

package/dist/scanners/engine/strategy-registry.js.map

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

package/dist/scanners/events.d.ts

@@ -0,0 +1,41 @@
+import { ScanStatus, type ScanResult, type ScannerId } from "./types.js";
+/** Emitted when one scanner execution attempt starts. */
+export interface ScannerRunStartEvent {
+    address: string;
+    scannerId: ScannerId;
+    timestamp: number;
+}
+/** Emitted when one scanner execution attempt completes without skip/error status. */
+export interface ScannerRunCompleteEvent {
+    address: string;
+    scannerId: ScannerId;
+    timestamp: number;
+    result: ScanResult;
+}
+/** Emitted when one scanner execution attempt terminates with a skip-like status. */
+export interface ScannerRunSkipEvent {
+    address: string;
+    scannerId: ScannerId;
+    timestamp: number;
+    status: ScanStatus;
+    reason: string;
+}
+/** Emitted when one scanner execution attempt fails with an error status. */
+export interface ScannerRunErrorEvent {
+    address: string;
+    scannerId: ScannerId;
+    timestamp: number;
+    error: unknown;
+}
+/** Scanner runtime pub/sub event map. */
+export interface ScannerRuntimeEventMap {
+    "scanner:run:start": ScannerRunStartEvent;
+    "scanner:run:complete": ScannerRunCompleteEvent;
+    "scanner:run:skip": ScannerRunSkipEvent;
+    "scanner:run:error": ScannerRunErrorEvent;
+}
+/** Supported runtime event names for scanner execution lifecycle. */
+export type ScannerRuntimeEventName = keyof ScannerRuntimeEventMap;
+/** Emits the terminal event (`complete|skip|error`) corresponding to a run result. */
+export declare function emitTerminalScannerRunEvent(emit: (eventName: ScannerRuntimeEventName, event: ScannerRuntimeEventMap[ScannerRuntimeEventName]) => void, result: ScanResult): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/scanners/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/scanners/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C,sBAAsB,EAAE,uBAAuB,CAAC;IAChD,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,mBAAmB,EAAE,oBAAoB,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAAG,MAAM,sBAAsB,CAAC;AAEnE,sFAAsF;AACtF,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,CAAC,SAAS,EAAE,uBAAuB,EAAE,KAAK,EAAE,sBAAsB,CAAC,uBAAuB,CAAC,KAAK,IAAI,EAC1G,MAAM,EAAE,UAAU,GACjB,IAAI,CAiCN"}

package/dist/scanners/events.js

@@ -0,0 +1,33 @@
+import { ScanStatus } from "./types.js";
+/** Emits the terminal event (`complete|skip|error`) corresponding to a run result. */
+export function emitTerminalScannerRunEvent(emit, result) {
+    const timestamp = result.timestamp;
+    if (result.status === ScanStatus.ERROR) {
+        emit("scanner:run:error", {
+            address: result.address,
+            scannerId: result.scannerId,
+            timestamp,
+            error: result.reason ?? "Unknown scanner error.",
+        });
+        return;
+    }
+    if (result.status === ScanStatus.SKIPPED ||
+        result.status === ScanStatus.HALTED ||
+        result.status === ScanStatus.DISABLED) {
+        emit("scanner:run:skip", {
+            address: result.address,
+            scannerId: result.scannerId,
+            timestamp,
+            status: result.status,
+            reason: result.reason ?? "Scanner run skipped.",
+        });
+        return;
+    }
+    emit("scanner:run:complete", {
+        address: result.address,
+        scannerId: result.scannerId,
+        timestamp,
+        result,
+    });
+}
+//# sourceMappingURL=events.js.map

package/dist/scanners/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/scanners/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAmC,MAAM,YAAY,CAAC;AA6CzE,sFAAsF;AACtF,MAAM,UAAU,2BAA2B,CACzC,IAA0G,EAC1G,MAAkB;IAElB,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,CAAC,mBAAmB,EAAE;YACxB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS;YACT,KAAK,EAAE,MAAM,CAAC,MAAM,IAAI,wBAAwB;SACjD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IACE,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,OAAO;QACpC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM;QACnC,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,QAAQ,EACrC,CAAC;QACD,IAAI,CAAC,kBAAkB,EAAE;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,sBAAsB;SAChD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,IAAI,CAAC,sBAAsB,EAAE;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS;QACT,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}

package/dist/scanners/implementations/emerging-movers.d.ts

@@ -0,0 +1,212 @@
+import { type Static } from "@sinclair/typebox";
+/**
+ * Discrete signal types emitted by the emerging-movers scanner (v4).
+ *
+ * Each type corresponds to a distinct market behaviour pattern detected in
+ * the SM (smart-money) leaderboard. They are listed in priority order — when
+ * multiple patterns fire for the same token, the highest-priority type wins.
+ *
+ * - **FIRST_JUMP** — Token rockets 10+ ranks from deep in the list and was
+ *   either absent from the previous scan or ranked >= 30. This is the earliest
+ *   possible entry signal; it fires before confirmation to catch moves early.
+ *
+ * - **CONTRIB_EXPLOSION** — Top-trader contribution increased 3x+ in a single
+ *   scan, indicating a sudden concentration of smart-money interest.
+ *
+ * - **IMMEDIATE_MOVER** — 10+ rank jump from >= #25 in one scan, but the token
+ *   was already tracked in the previous top-N (ruling out FIRST_JUMP).
+ *
+ * - **NEW_ENTRY_DEEP** — Token appears in the top-N for the first time and
+ *   lands directly in the top 20, suggesting strong initial positioning.
+ *
+ * - **DEEP_CLIMBER** — Moderate rank improvement (>= minRankJump) from a deep
+ *   starting position (>= #25). Catch-all for significant but non-explosive moves.
+ */
+export type EmergingMoverSignalType = "FIRST_JUMP" | "CONTRIB_EXPLOSION" | "IMMEDIATE_MOVER" | "NEW_ENTRY_DEEP" | "DEEP_CLIMBER";
+declare const emergingMoversConfigSchema: import("@sinclair/typebox").TObject<{
+    topN: import("@sinclair/typebox").TNumber;
+    minRankJump: import("@sinclair/typebox").TNumber;
+    minTopTradersGain: import("@sinclair/typebox").TNumber;
+    minScansBeforeSignals: import("@sinclair/typebox").TNumber;
+    historyLimit: import("@sinclair/typebox").TNumber;
+    immediateJumpThreshold: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    deepClimbRankThreshold: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    contribExplosionMultiplier: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    contribAccelThreshold: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    minVelocityForDeepClimber: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    erraticReversalThreshold: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    climbStreakScans: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    rankClimbThreshold: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    newEntryDeepMaxRank: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    newEntryMaxRank: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    firstJumpMinPrevRank: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    /** Enable regime-aware score gating via market-regime artifact. Default: false (disabled). */
+    regimeScoreGating: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    /** Score threshold when market regime is NEUTRAL. Only used when regimeScoreGating is true. */
+    regimeScoreNeutral: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    /** Score threshold when market regime is BULLISH or BEARISH. Only used when regimeScoreGating is true. */
+    regimeScoreDefault: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    /** Minimum asset max leverage to emit signals. 0 = disabled (no filtering). */
+    minLeverage: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type EmergingMoversConfig = Static<typeof emergingMoversConfigSchema>;
+/**
+ * Config with all optional v4 fields guaranteed present.
+ * Created by {@link resolveConfig} at the start of each scan so detection
+ * rules never need to handle `undefined`.
+ */
+export type ResolvedEmergingMoversConfig = Required<EmergingMoversConfig>;
+/**
+ * Persisted state carried across scan runs.
+ *
+ * The scanner is stateful: it must compare the current leaderboard snapshot
+ * against previous ones to detect rank movements and contribution trends.
+ * This state is saved to disk via `ctx.setState()` after every scan.
+ */
+export interface EmergingMoversState {
+    /** Total number of completed scans. Used to enforce the warm-up gate
+     *  (`minScansBeforeSignals`) — no signals are emitted until enough
+     *  history has accumulated to make comparisons meaningful. */
+    scans: number;
+    /** Per-token rank history (keyed by {@link tokenKey}).
+     *  Each entry is a sliding window of the token's leaderboard rank
+     *  across recent scans, capped at `historyLimit`. Enables multi-scan
+     *  climb detection, streak analysis, and erratic-history filtering. */
+    rankHistory: Record<string, number[]>;
+    /** Per-token contribution history (keyed by {@link tokenKey}).
+     *  Mirrors `rankHistory` but tracks `pctOfTopTradersGain` values.
+     *  Used for contribution velocity, acceleration, and explosion detection. */
+    contribHistory: Record<string, number[]>;
+    /** Token keys present in the previous scan's top-N.
+     *  Compared against the current scan to distinguish "first appearance"
+     *  signals (FIRST_JUMP, NEW_ENTRY_DEEP) from rank movements within
+     *  an already-tracked set. */
+    prevTopTokens: string[];
+}
+/**
+ * Fully enriched alert candidate produced by {@link analyzeMarket}.
+ *
+ * Combines the market's raw data, accumulated detection flags, computed
+ * velocity, and history windows. Passed to {@link classifySignal} for
+ * type resolution and to {@link alertToSignal} for Signal construction.
+ */
+interface AlertCandidate {
+    /** Token symbol (e.g. "SOL", "WIF"). */
+    token: string;
+    /** Optional DEX identifier (e.g. "xyz"). When present, the token is
+     *  qualified as `xyz:<token>` in the emitted signal's `asset` field. */
+    dex: string | undefined;
+    /** Market direction string from the SM data (e.g. "up", "short"). */
+    direction: string;
+    /** 1-based rank in the current scan's top-N. */
+    currentRank: number;
+    /** Raw `pctOfTopTradersGain` in the current scan. */
+    currentContrib: number;
+    /** 4-hour token price change percentage from the SM data source. */
+    priceChg4h: number;
+    /** Number of tracked traders for this token. */
+    traderCount: number;
+    /** Human-readable reason strings from every triggered detection rule. */
+    reasons: string[];
+    /** See {@link DetectionFlags.isDeepClimber}. */
+    isDeepClimber: boolean;
+    /** See {@link DetectionFlags.isImmediate}. */
+    isImmediate: boolean;
+    /** See {@link DetectionFlags.isFirstJump}. */
+    isFirstJump: boolean;
+    /** See {@link DetectionFlags.isContribExplosion}. */
+    isContribExplosion: boolean;
+    /** See {@link DetectionFlags.rankJumpThisScan}. */
+    rankJumpThisScan: number;
+    /** Average contribution change per scan over the recent window.
+     *  Positive = contribution is accelerating; used by the velocity gate. */
+    contribVelocity: number;
+    /** Last <=5 rank values plus the current rank (for metadata / erratic check). */
+    rankHistoryWindow: (number | null)[];
+    /** Last <=5 contribution values plus the current one (as percentages, for metadata). */
+    contribHistoryWindow: (number | null)[];
+}
+/**
+ * Detects zigzag rank patterns that indicate market noise rather than a
+ * genuine trend.
+ *
+ * Scans consecutive rank deltas for direction reversals that exceed the
+ * threshold (e.g. improving 10 ranks then dropping 8). Such zigzags suggest
+ * the token is bouncing rather than sustainably climbing, and are used to
+ * downgrade IMMEDIATE_MOVER signals to the lower-priority DEEP_CLIMBER.
+ *
+ * @param excludeLast - When `true`, the final entry (this scan's rank) is
+ *   removed before checking. This is critical for big-jump signals: the
+ *   jump itself is the signal, not noise, so only the *pre-jump* history
+ *   should be evaluated for erratic behaviour.
+ */
+export declare function isErraticHistory(rankHistory: (number | null)[], erraticReversalThreshold: number, excludeLast?: boolean): boolean;
+/**
+ * Computes average contribution change per scan over the given window.
+ *
+ * Uses (last - first) / (length - 1) rather than summing individual deltas,
+ * which is algebraically identical but avoids floating-point accumulation.
+ * A positive result means contribution is trending up; the velocity gate
+ * uses this to filter out tokens whose rank improvement is not backed by
+ * growing smart-money concentration.
+ */
+export declare function computeContribVelocity(contribs: number[]): number;
+/**
+ * Classifies an alert candidate into a signal type and applies quality
+ * filters (erratic history, velocity gate).
+ *
+ * The classification pipeline is:
+ * 1. **Resolve signal type** from detection flags (priority order).
+ * 2. **Check erratic history** — zigzag rank patterns indicate noise.
+ * 3. **Check velocity gate** — contribution velocity must be positive
+ *    (IMMEDIATE/FIRST_JUMP) or above a minimum (DEEP_CLIMBER).
+ * 4. **Apply downgrades** — IMMEDIATE_MOVER is demoted to DEEP_CLIMBER
+ *    when erratic or low-velocity. FIRST_JUMP and CONTRIB_EXPLOSION are
+ *    immune to downgrades because they represent decisive, one-scan events
+ *    where historical noise is irrelevant.
+ *
+ * @returns Classification result, or `null` if the candidate has no reasons
+ *   (should not happen if called from {@link analyzeMarket}).
+ */
+export declare function classifySignal(alert: AlertCandidate, config: ResolvedEmergingMoversConfig): {
+    signalType: EmergingMoverSignalType;
+    priority: number;
+    conviction: number;
+    erratic: boolean;
+    lowVelocity: boolean;
+} | null;
+/**
+ * Creates the emerging-movers scanner instance (v4).
+ *
+ * This is the entry point registered in the scanner registry. It produces a
+ * stateful scanner that:
+ * 1. Ranks markets by `pctOfTopTradersGain` and tracks the top N.
+ * 2. Maintains per-token rank and contribution history across scans.
+ * 3. Runs 7 detection rules per market to identify emerging movers.
+ * 4. Classifies alerts into 5 signal types with conviction scoring.
+ * 5. Applies erratic-history and velocity-gate filters to reduce noise.
+ */
+export declare function emergingMoversScanner(): import("../index.js").Scanner<{
+    immediateJumpThreshold?: number | undefined;
+    deepClimbRankThreshold?: number | undefined;
+    contribExplosionMultiplier?: number | undefined;
+    contribAccelThreshold?: number | undefined;
+    minVelocityForDeepClimber?: number | undefined;
+    erraticReversalThreshold?: number | undefined;
+    climbStreakScans?: number | undefined;
+    rankClimbThreshold?: number | undefined;
+    newEntryDeepMaxRank?: number | undefined;
+    newEntryMaxRank?: number | undefined;
+    firstJumpMinPrevRank?: number | undefined;
+    regimeScoreGating?: boolean | undefined;
+    regimeScoreNeutral?: number | undefined;
+    regimeScoreDefault?: number | undefined;
+    minLeverage?: number | undefined;
+    topN: number;
+    minRankJump: number;
+    minTopTradersGain: number;
+    minScansBeforeSignals: number;
+    historyLimit: number;
+}, EmergingMoversState>;
+export {};
+//# sourceMappingURL=emerging-movers.d.ts.map

package/dist/scanners/implementations/emerging-movers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emerging-movers.d.ts","sourceRoot":"","sources":["../../../src/scanners/implementations/emerging-movers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAUtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,uBAAuB,GAC/B,YAAY,GACZ,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,CAAC;AA8BnB,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;;;IAiB9B,8FAA8F;;IAE9F,+FAA+F;;IAE/F,0GAA0G;;IAE1G,+EAA+E;;EAE/E,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAI1E;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;kEAE8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IAEd;;;2EAGuE;IACvE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtC;;iFAE6E;IAC7E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEzC;;;kCAG8B;IAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAmHD;;;;;;GAMG;AACH,UAAU,cAAc;IACtB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IAEd;4EACwE;IACxE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IAExB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAElB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IAEpB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IAEvB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IAEnB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IAEpB,yEAAyE;IACzE,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,gDAAgD;IAChD,aAAa,EAAE,OAAO,CAAC;IAEvB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IAErB,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IAErB,qDAAqD;IACrD,kBAAkB,EAAE,OAAO,CAAC;IAE5B,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IAEzB;8EAC0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IAExB,iFAAiF;IACjF,iBAAiB,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAErC,wFAAwF;IACxF,oBAAoB,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;CACzC;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EAC9B,wBAAwB,EAAE,MAAM,EAChC,WAAW,UAAQ,GAClB,OAAO,CAcT;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAIjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,4BAA4B,GACnC;IACD,UAAU,EAAE,uBAAuB,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,IAAI,CAmBP;AA8dD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB;;;;;;;;;;;;;;;;;;;;;wBAoHpC"}