@senpi/trading-runtime 1.0.0

package/dist/scanners/providers/factory.js

@@ -0,0 +1,156 @@
+import { normalizeAssetCandles, normalizeInstrumentsWithDiagnostics, normalizeSmMarketsWithDiagnostics, } from "./adapter.js";
+import { createConsoleProviderLogger, createProviderClient, createWinstonProviderLogger, } from "./client.js";
+import { ProviderCache } from "./cache.js";
+/** Creates a `ScannerDataProviders` bundle backed by Senpi MCP tools. */
+export function createSenpiScannerProviders(options) {
+    const cache = new ProviderCache();
+    const logger = toProviderLogger(options.logger) ?? createConsoleProviderLogger();
+    const client = createProviderClient(options.client, {
+        logger,
+        logLevel: options.logLevel ?? "info",
+        retries: options.retries ?? 2,
+        timeoutMs: 10_000,
+    });
+    const candleIntervals = options.candleIntervals ?? ["1h", "4h"];
+    const maxCandleAssets = options.maxCandleAssets ?? 10;
+    const cacheTtl = {
+        instruments: options.cacheTtlMs?.instruments ?? 30_000,
+        smData: options.cacheTtlMs?.smData ?? 120_000,
+        candles: options.cacheTtlMs?.candles ?? 30_000,
+    };
+    const timeouts = {
+        marketListInstruments: options.timeouts?.marketListInstruments ?? 10_000,
+        marketGetAssetData: options.timeouts?.marketGetAssetData ?? 10_000,
+        leaderboardGetMarkets: options.timeouts?.leaderboardGetMarkets ?? 8_000,
+    };
+    const toolNames = {
+        marketListInstruments: options.toolNames?.marketListInstruments ?? "market_list_instruments",
+        marketGetAssetData: options.toolNames?.marketGetAssetData ?? "market_get_asset_data",
+        leaderboardGetMarkets: options.toolNames?.leaderboardGetMarkets ?? "leaderboard_get_markets",
+    };
+    return {
+        getInstruments: async (address) => cache.getOrLoad(cacheKey("instruments", address), cacheTtl.instruments, async () => {
+            const normalized = normalizeInstrumentsWithDiagnostics(await client.callTool(toolNames.marketListInstruments, {}, {
+                address,
+                timeoutMs: timeouts.marketListInstruments,
+            }));
+            warnOnNormalizationIssues(logger, {
+                tool: toolNames.marketListInstruments,
+                address,
+                diagnostics: normalized.diagnostics,
+            });
+            return normalized.value;
+        }),
+        getCandles: async (address, instruments, requestOptions) => {
+            const assets = selectCandleAssets(instruments, requestOptions, maxCandleAssets);
+            if (assets.length === 0) {
+                return {};
+            }
+            const result = {};
+            await Promise.all(assets.map(async (asset) => {
+                const key = cacheKey("candles", address, asset, candleIntervals.join(","));
+                const candles = await cache.getOrLoad(key, cacheTtl.candles, async () => {
+                    const payload = await client.callTool(toolNames.marketGetAssetData, {
+                        asset,
+                        candle_intervals: candleIntervals,
+                        include_order_book: false,
+                        include_funding: false,
+                    }, {
+                        address,
+                        scannerId: requestOptions?.scannerId,
+                        timeoutMs: timeouts.marketGetAssetData,
+                    });
+                    const normalized = normalizeAssetCandles(payload);
+                    if (normalized.error) {
+                        logger.warn("Provider candle payload had recoverable issues.", {
+                            tool: toolNames.marketGetAssetData,
+                            address,
+                            scannerId: requestOptions?.scannerId,
+                            asset,
+                            error: normalized.error,
+                        });
+                    }
+                    return normalized;
+                });
+                result[asset] = candles;
+            }));
+            return result;
+        },
+        getSmData: async (address) => cache.getOrLoad(cacheKey("sm-data", address), cacheTtl.smData, async () => {
+            const normalized = normalizeSmMarketsWithDiagnostics(await client.callTool(toolNames.leaderboardGetMarkets, {
+                limit: 100,
+            }, {
+                address,
+                timeoutMs: timeouts.leaderboardGetMarkets,
+            }));
+            warnOnNormalizationIssues(logger, {
+                tool: toolNames.leaderboardGetMarkets,
+                address,
+                diagnostics: normalized.diagnostics,
+            });
+            return normalized.value;
+        }),
+    };
+}
+/** Adapts either the provider-local logger or a winston-style logger into one provider logger surface. */
+function toProviderLogger(logger) {
+    if (!logger) {
+        return undefined;
+    }
+    if (isProviderLogger(logger)) {
+        return logger;
+    }
+    return createWinstonProviderLogger(logger);
+}
+/** Runtime guard for objects that already satisfy the provider logger contract. */
+function isProviderLogger(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const logger = value;
+    return (typeof logger.debug === "function" &&
+        typeof logger.info === "function" &&
+        typeof logger.warn === "function" &&
+        typeof logger.error === "function");
+}
+/**
+ * Chooses which assets should receive candle requests for one run.
+ * Preferred assets win when they are present in the current instrument universe;
+ * otherwise the provider falls back to the deduplicated instrument list.
+ */
+function selectCandleAssets(instruments, requestOptions, maxCandleAssets) {
+    const preferred = requestOptions?.preferredAssets ?? [];
+    const preferredSet = new Set(preferred);
+    const validPreferred = instruments
+        .map((instrument) => instrument.name)
+        .filter((asset) => preferredSet.has(asset));
+    if (validPreferred.length > 0) {
+        return dedupeAssets(validPreferred).slice(0, maxCandleAssets);
+    }
+    return dedupeAssets(instruments.map((instrument) => instrument.name)).slice(0, maxCandleAssets);
+}
+/** Removes duplicate asset symbols while preserving first-seen order. */
+function dedupeAssets(assets) {
+    return [...new Set(assets)];
+}
+/** Builds a stable cache key for one provider payload family. */
+function cacheKey(prefix, ...parts) {
+    return `${prefix}:${parts.join(":")}`;
+}
+/** Emits one warning when normalization discarded rows or recorded parse issues. */
+function warnOnNormalizationIssues(logger, params) {
+    const { diagnostics } = params;
+    if (diagnostics.discardedCount === 0 &&
+        Object.keys(diagnostics.issueCounts).length === 0) {
+        return;
+    }
+    logger.warn("Provider normalization reported discarded rows.", {
+        tool: params.tool,
+        address: params.address,
+        scannerId: params.scannerId,
+        acceptedCount: diagnostics.acceptedCount,
+        discardedCount: diagnostics.discardedCount,
+        issueCounts: diagnostics.issueCounts,
+    });
+}
+//# sourceMappingURL=factory.js.map

package/dist/scanners/providers/factory.js.map

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

package/dist/scanners/providers/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Raw MCP payload contracts used by scanner provider adapters.
+ * These types reflect the expected wire shape before normalization.
+ */
+/** Common MCP envelope shape (`{ success, data }`) returned by some clients. */
+export interface SenpiEnvelope<T> {
+    success: boolean;
+    data: T;
+}
+/** Raw instrument context payload returned by `market_list_instruments`. */
+export interface RawInstrumentContext {
+    markPx: unknown;
+    prevDayPx: unknown;
+    midPx: unknown;
+    dayNtlVlm: unknown;
+    openInterest: unknown;
+    funding: unknown;
+    [key: string]: unknown;
+}
+/** Raw instrument row returned by `market_list_instruments`. */
+export interface RawInstrument {
+    name: unknown;
+    is_delisted: unknown;
+    max_leverage: unknown;
+    context: RawInstrumentContext | unknown;
+}
+/** Raw response shape for `market_list_instruments`. */
+export interface RawMarketListInstrumentsResponse {
+    instruments: RawInstrument[] | unknown;
+}
+/** Raw candle row returned by `market_get_asset_data`. */
+export interface RawCandleRow {
+    t: unknown;
+    o: unknown;
+    h: unknown;
+    l: unknown;
+    c: unknown;
+    v: unknown;
+}
+/** Raw response shape for `market_get_asset_data`. */
+export interface RawMarketAssetDataResponse {
+    candles?: Record<string, RawCandleRow[] | unknown> | unknown;
+    error?: unknown;
+}
+/** Raw smart-money market row returned by `leaderboard_get_markets`. */
+export interface RawSmMarket {
+    token: unknown;
+    dex?: unknown;
+    direction: unknown;
+    pct_of_top_traders_gain: unknown;
+    trader_count: unknown;
+    token_price_change_pct_4h: unknown;
+    [key: string]: unknown;
+}
+/** Raw response shape for `leaderboard_get_markets`. */
+export interface RawLeaderboardMarketsResponse {
+    markets?: {
+        markets?: RawSmMarket[] | unknown;
+    } | RawSmMarket[] | unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/scanners/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/scanners/providers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gFAAgF;AAChF,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;CACT;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;CACzC;AAED,wDAAwD;AACxD,MAAM,WAAW,gCAAgC;IAC/C,WAAW,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;CACxC;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;IACX,CAAC,EAAE,OAAO,CAAC;CACZ;AAED,sDAAsD;AACtD,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,uBAAuB,EAAE,OAAO,CAAC;IACjC,YAAY,EAAE,OAAO,CAAC;IACtB,yBAAyB,EAAE,OAAO,CAAC;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,6BAA6B;IAC5C,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAAA;KAAE,GAAG,WAAW,EAAE,GAAG,OAAO,CAAC;CAC3E"}

package/dist/scanners/providers/types.js

@@ -0,0 +1,6 @@
+/**
+ * Raw MCP payload contracts used by scanner provider adapters.
+ * These types reflect the expected wire shape before normalization.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/scanners/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/scanners/providers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/scanners/runtime-module.d.ts

@@ -0,0 +1,54 @@
+import type { ScannerDataProviders } from "./engine/data-providers.js";
+import { type ScannerRegistrationSummary } from "./engine/engine.js";
+import { type ScannerRuntimeEventMap, type ScannerRuntimeEventName } from "./events.js";
+import type { ScannerLogger } from "./protocol/context.js";
+import type { Scanner } from "./protocol/scanner.js";
+import type { ReadSignalsFilter, ScanResult, ScannerId, Signal, StrategyRegistration } from "./types.js";
+/** Factory that creates one scanner instance for one strategy registration. */
+export type ScannerFactory<Cfg = unknown, St = unknown> = () => Scanner<Cfg, St>;
+/**
+ * Scanner registration input accepted by module bootstrap.
+ * Each entry must build a fresh scanner instance for each strategy registration.
+ */
+export type ScannerInput<Cfg = unknown, St = unknown> = ScannerFactory<Cfg, St>;
+/** Runtime-module bootstrap options for scanner registration and state wiring. */
+export interface ScannerRuntimeModuleOptions {
+    stateDir: string;
+    strategies: StrategyRegistration[];
+    scanners: ScannerInput[];
+    providers?: ScannerDataProviders;
+    logger?: ScannerLogger;
+    now?: () => number;
+}
+/** Public control surface exposed by the standalone scanner runtime module. */
+export interface ScannerRuntimeModule {
+    /** Starts interval scheduling for all enabled strategy/scanner registrations. */
+    start(): Promise<void>;
+    /** Stops interval scheduling; in-flight runs are allowed to finish. */
+    stop(): Promise<void>;
+    /** Runs one scanner immediately for one strategy. */
+    runOnce(address: string, scannerId: ScannerId): Promise<ScanResult>;
+    /** Lists registered scanners and enablement state, optionally for one strategy. */
+    listScanners(address?: string): Promise<ScannerRegistrationSummary[]>;
+    /** Enables one scanner registration for future scheduled/manual runs. */
+    enableScanner(address: string, scannerId: ScannerId): Promise<void>;
+    /** Disables one scanner registration for future scheduled/manual runs. */
+    disableScanner(address: string, scannerId: ScannerId): Promise<void>;
+    /** Reads current persisted config for one scanner registration. */
+    getScannerConfig(address: string, scannerId: ScannerId): Promise<unknown>;
+    /** Writes validated config for one scanner registration. */
+    setScannerConfig(address: string, scannerId: ScannerId, config: unknown): Promise<void>;
+    /** Queries persisted latest signals across strategy/scanner boundaries. */
+    querySignals(filter?: ReadSignalsFilter): Promise<Signal[]>;
+    /** Subscribes one event listener to runtime lifecycle events. */
+    on<Name extends ScannerRuntimeEventName>(eventName: Name, listener: (event: ScannerRuntimeEventMap[Name]) => void): void;
+    /** Unsubscribes one event listener from runtime lifecycle events. */
+    off<Name extends ScannerRuntimeEventName>(eventName: Name, listener: (event: ScannerRuntimeEventMap[Name]) => void): void;
+}
+/**
+ * Creates a standalone scanner runtime module with strategy-scoped scanner instances.
+ * Registered scanners are supplied as factories so the module never reuses mutable
+ * scanner objects across strategies.
+ */
+export declare function createScannerRuntimeModule(options: ScannerRuntimeModuleOptions): ScannerRuntimeModule;
+//# sourceMappingURL=runtime-module.d.ts.map

package/dist/scanners/runtime-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-module.d.ts","sourceRoot":"","sources":["../../src/scanners/runtime-module.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAiB,KAAK,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,MAAM,EACN,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,MAAM,MAAM,cAAc,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO,IAAI,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAEjF;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO,IAAI,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAEhF,kFAAkF;AAClF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,uEAAuE;IACvE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,qDAAqD;IACrD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEpE,mFAAmF;IACnF,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAAC;IAEtE,yEAAyE;IACzE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE,0EAA0E;IAC1E,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE,mEAAmE;IACnE,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1E,4DAA4D;IAC5D,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,2EAA2E;IAC3E,YAAY,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5D,iEAAiE;IACjE,EAAE,CAAC,IAAI,SAAS,uBAAuB,EACrC,SAAS,EAAE,IAAI,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,IAAI,CAAC,KAAK,IAAI,GACtD,IAAI,CAAC;IAER,qEAAqE;IACrE,GAAG,CAAC,IAAI,SAAS,uBAAuB,EACtC,SAAS,EAAE,IAAI,EACf,QAAQ,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,IAAI,CAAC,KAAK,IAAI,GACtD,IAAI,CAAC;CACT;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAEtB"}

package/dist/scanners/runtime-module.js

@@ -0,0 +1,94 @@
+import { EventEmitter } from "node:events";
+import { createLogger } from "../utils/logger.js";
+import { ScannerEngine } from "./engine/engine.js";
+const logger = createLogger("[senpi-core][scanner-module]");
+import { emitTerminalScannerRunEvent, } from "./events.js";
+import { RuntimeStore } from "./store/runtime-store.js";
+import { SharedArtifactStore } from "./store/shared-artifact-store.js";
+import { SignalStore } from "./store/signal-store.js";
+/**
+ * Creates a standalone scanner runtime module with strategy-scoped scanner instances.
+ * Registered scanners are supplied as factories so the module never reuses mutable
+ * scanner objects across strategies.
+ */
+export function createScannerRuntimeModule(options) {
+    return new DefaultScannerRuntimeModule(options);
+}
+class DefaultScannerRuntimeModule {
+    signalStore;
+    engine;
+    events = new EventEmitter();
+    constructor(options) {
+        const now = options.now ?? Date.now;
+        this.signalStore = new SignalStore(options.stateDir);
+        this.engine = new ScannerEngine({
+            now,
+            logger: options.logger ?? logger,
+            providers: options.providers,
+            stores: {
+                runtimeStore: new RuntimeStore(options.stateDir, now),
+                signalStore: this.signalStore,
+                sharedArtifactStore: new SharedArtifactStore(options.stateDir, now),
+            },
+            lifecycle: {
+                onRunStart: (event) => {
+                    this.events.emit("scanner:run:start", event);
+                },
+                onRunResult: (result) => {
+                    emitTerminalScannerRunEvent((eventName, event) => {
+                        this.events.emit(eventName, event);
+                    }, result);
+                },
+            },
+        });
+        registerAll(options.strategies, options.scanners, this.engine);
+    }
+    async start() {
+        logger.info("scanner module start() entered");
+        logger.debug("scanner module start begin");
+        await this.engine.start();
+        logger.info("scanner module start() complete");
+        logger.debug("scanner module start complete");
+    }
+    async stop() {
+        logger.debug("scanner module stop begin");
+        await this.engine.stop();
+        logger.debug("scanner module stop complete");
+    }
+    async runOnce(address, scannerId) {
+        return this.engine.runOnce(address, scannerId);
+    }
+    async listScanners(address) {
+        return this.engine.list(address);
+    }
+    async enableScanner(address, scannerId) {
+        this.engine.enable(address, scannerId);
+    }
+    async disableScanner(address, scannerId) {
+        this.engine.disable(address, scannerId);
+    }
+    async getScannerConfig(address, scannerId) {
+        return this.engine.getConfig(address, scannerId);
+    }
+    async setScannerConfig(address, scannerId, config) {
+        await this.engine.setConfig(address, scannerId, config);
+    }
+    async querySignals(filter) {
+        return this.signalStore.readSignals(filter);
+    }
+    on(eventName, listener) {
+        this.events.on(eventName, listener);
+    }
+    off(eventName, listener) {
+        this.events.off(eventName, listener);
+    }
+}
+/** Registers every scanner factory once for every strategy so each registration gets a fresh instance. */
+function registerAll(strategies, scanners, engine) {
+    for (const strategy of strategies) {
+        for (const scannerFactory of scanners) {
+            engine.register(strategy, scannerFactory());
+        }
+    }
+}
+//# sourceMappingURL=runtime-module.js.map

package/dist/scanners/runtime-module.js.map

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

package/dist/scanners/scanner-definition.d.ts

@@ -0,0 +1,58 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { SharedArtifactContract } from "./artifacts.js";
+import type { ScannerInputDescriptor } from "./input-descriptors.js";
+import type { ScannerId } from "./types.js";
+/** Controls how much signal history is retained on disk. */
+export declare enum RetentionPolicy {
+    /** Keep only the latest run and remove history. */
+    LAST_ONLY = "last_only",
+    /** Keep latest plus a bounded tail of previous runs. */
+    ROLLING_WINDOW = "rolling_window"
+}
+/** Controls when a run result should be persisted. */
+export declare enum PersistencePolicy {
+    /** Persist every run result. */
+    ALWAYS = "always",
+    /** Persist only when at least one signal is actionable. */
+    ACTIONABLE_ONLY = "actionable_only",
+    /** Never persist; return result in-memory only. */
+    NEVER = "never"
+}
+/**
+ * Immutable scanner definition shared across all strategy runtimes.
+ * Runtime state/config for a scanner instance is kept separately in RuntimeStore.
+ */
+export interface ScannerDefinition<Cfg = unknown, St = unknown> {
+    /** Scanner identifier; unique per strategy runtime instance. */
+    id: ScannerId;
+    /** Domain-level signal type emitted by this scanner. */
+    signalType: string;
+    /** Human-readable purpose/behavior summary. */
+    description: string;
+    /** Default schedule interval in seconds. */
+    intervalSeconds: number;
+    /** Signal retention behavior for persisted runs. */
+    retention: RetentionPolicy;
+    /** Maximum number of history rows when using ROLLING_WINDOW. */
+    retentionMaxRuns?: number;
+    /** Persistence decision policy used by engine when hooks do not override. */
+    persistence: PersistencePolicy;
+    /** Declarative provider-backed and artifact-backed input requirements for each scan run. */
+    inputs: ScannerInputDescriptor[];
+    /**
+     * Optional metadata describing which shared artifacts the scanner produces.
+     * These artifacts are shared market intelligence between scanners, not trading signals.
+     */
+    artifacts?: {
+        produces?: SharedArtifactContract[];
+    };
+    /** Config validation schema enforced by engine before initialization/runs. */
+    configSchema: TSchema;
+    /** Default config used when runtime config does not exist yet. */
+    defaultConfig: Cfg;
+    /** Optional state validation schema enforced by the engine before initialize()/scan(). */
+    stateSchema?: TSchema;
+    /** Default state used when runtime state is missing or must be repaired. */
+    defaultState?: St;
+}
+//# sourceMappingURL=scanner-definition.d.ts.map

package/dist/scanners/scanner-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner-definition.d.ts","sourceRoot":"","sources":["../../src/scanners/scanner-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,4DAA4D;AAC5D,oBAAY,eAAe;IACzB,mDAAmD;IACnD,SAAS,cAAc;IACvB,wDAAwD;IACxD,cAAc,mBAAmB;CAClC;AAED,sDAAsD;AACtD,oBAAY,iBAAiB;IAC3B,gCAAgC;IAChC,MAAM,WAAW;IACjB,2DAA2D;IAC3D,eAAe,oBAAoB;IACnC,mDAAmD;IACnD,KAAK,UAAU;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;IAC5D,gEAAgE;IAChE,EAAE,EAAE,SAAS,CAAC;IACd,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAC;IAExB,oDAAoD;IACpD,SAAS,EAAE,eAAe,CAAC;IAC3B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,6EAA6E;IAC7E,WAAW,EAAE,iBAAiB,CAAC;IAE/B,4FAA4F;IAC5F,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAEjC;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV,QAAQ,CAAC,EAAE,sBAAsB,EAAE,CAAC;KACrC,CAAC;IAEF,8EAA8E;IAC9E,YAAY,EAAE,OAAO,CAAC;IACtB,kEAAkE;IAClE,aAAa,EAAE,GAAG,CAAC;IACnB,0FAA0F;IAC1F,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,EAAE,CAAC;CACnB"}

package/dist/scanners/scanner-definition.js

@@ -0,0 +1,19 @@
+/** Controls how much signal history is retained on disk. */
+export var RetentionPolicy;
+(function (RetentionPolicy) {
+    /** Keep only the latest run and remove history. */
+    RetentionPolicy["LAST_ONLY"] = "last_only";
+    /** Keep latest plus a bounded tail of previous runs. */
+    RetentionPolicy["ROLLING_WINDOW"] = "rolling_window";
+})(RetentionPolicy || (RetentionPolicy = {}));
+/** Controls when a run result should be persisted. */
+export var PersistencePolicy;
+(function (PersistencePolicy) {
+    /** Persist every run result. */
+    PersistencePolicy["ALWAYS"] = "always";
+    /** Persist only when at least one signal is actionable. */
+    PersistencePolicy["ACTIONABLE_ONLY"] = "actionable_only";
+    /** Never persist; return result in-memory only. */
+    PersistencePolicy["NEVER"] = "never";
+})(PersistencePolicy || (PersistencePolicy = {}));
+//# sourceMappingURL=scanner-definition.js.map

package/dist/scanners/scanner-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner-definition.js","sourceRoot":"","sources":["../../src/scanners/scanner-definition.ts"],"names":[],"mappings":"AAKA,4DAA4D;AAC5D,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,mDAAmD;IACnD,0CAAuB,CAAA;IACvB,wDAAwD;IACxD,oDAAiC,CAAA;AACnC,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED,sDAAsD;AACtD,MAAM,CAAN,IAAY,iBAOX;AAPD,WAAY,iBAAiB;IAC3B,gCAAgC;IAChC,sCAAiB,CAAA;IACjB,2DAA2D;IAC3D,wDAAmC,CAAA;IACnC,mDAAmD;IACnD,oCAAe,CAAA;AACjB,CAAC,EAPW,iBAAiB,KAAjB,iBAAiB,QAO5B"}

package/dist/scanners/schema-utils.d.ts

@@ -0,0 +1,6 @@
+import type { TSchema } from "@sinclair/typebox";
+/** Returns true when a value conforms to the provided TypeBox schema. */
+export declare function isSchemaValueValid(schema: TSchema | undefined, value: unknown): boolean;
+/** Formats the first TypeBox validation error into a compact human-readable string. */
+export declare function describeSchemaValidationError(schema: TSchema, value: unknown): string;
+//# sourceMappingURL=schema-utils.d.ts.map

package/dist/scanners/schema-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.d.ts","sourceRoot":"","sources":["../../src/scanners/schema-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,yEAAyE;AACzE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,KAAK,EAAE,OAAO,GACb,OAAO,CAKT;AAED,uFAAuF;AACvF,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,OAAO,GACb,MAAM,CAGR"}

package/dist/scanners/schema-utils.js

@@ -0,0 +1,14 @@
+import { Value } from "@sinclair/typebox/value";
+/** Returns true when a value conforms to the provided TypeBox schema. */
+export function isSchemaValueValid(schema, value) {
+    if (!schema) {
+        return true;
+    }
+    return Value.Check(schema, value);
+}
+/** Formats the first TypeBox validation error into a compact human-readable string. */
+export function describeSchemaValidationError(schema, value) {
+    const firstError = Value.Errors(schema, value).First();
+    return firstError ? `${firstError.path} ${firstError.message}` : "Unknown reason";
+}
+//# sourceMappingURL=schema-utils.js.map

package/dist/scanners/schema-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.js","sourceRoot":"","sources":["../../src/scanners/schema-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAEhD,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAChC,MAA2B,EAC3B,KAAc;IAEd,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,6BAA6B,CAC3C,MAAe,EACf,KAAc;IAEd,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;IACvD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;AACpF,CAAC"}

package/dist/scanners/score-utils.d.ts

@@ -0,0 +1,19 @@
+/** Logger surface required by score guard utilities. */
+export interface ScoreGuardLogger {
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+}
+/** Clamps non-finite/out-of-range numbers into the [0, 1] interval. */
+export declare function clamp01(value: number): number;
+/**
+ * Coerces any non-finite/out-of-range score into the valid [0, 1] interval.
+ * Alias for clamp01 — kept for backward compatibility and semantic clarity.
+ */
+export declare const clampScore: typeof clamp01;
+/** Normalizes one value into [0, 1] based on the provided range. */
+export declare function normalizeRange(value: number, min: number, max: number): number;
+/**
+ * Enforces score range and emits a warning when a clamp occurs.
+ * Use this in engine output normalization before persistence.
+ */
+export declare function enforceScoreRange(score: number, logger?: ScoreGuardLogger, context?: Record<string, unknown>): number;
+//# sourceMappingURL=score-utils.d.ts.map

package/dist/scanners/score-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-utils.d.ts","sourceRoot":"","sources":["../../src/scanners/score-utils.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACjE;AAED,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7C;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,gBAAU,CAAC;AAElC,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAW9E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,gBAAgB,EACzB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,MAAM,CAUR"}

package/dist/scanners/score-utils.js

@@ -0,0 +1,47 @@
+/** Clamps non-finite/out-of-range numbers into the [0, 1] interval. */
+export function clamp01(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 1) {
+        return 1;
+    }
+    return value;
+}
+/**
+ * Coerces any non-finite/out-of-range score into the valid [0, 1] interval.
+ * Alias for clamp01 — kept for backward compatibility and semantic clarity.
+ */
+export const clampScore = clamp01;
+/** Normalizes one value into [0, 1] based on the provided range. */
+export function normalizeRange(value, min, max) {
+    if (!Number.isFinite(value) || max <= min) {
+        return 0;
+    }
+    if (value <= min) {
+        return 0;
+    }
+    if (value >= max) {
+        return 1;
+    }
+    return (value - min) / (max - min);
+}
+/**
+ * Enforces score range and emits a warning when a clamp occurs.
+ * Use this in engine output normalization before persistence.
+ */
+export function enforceScoreRange(score, logger, context = {}) {
+    const clamped = clamp01(score);
+    if (clamped !== score && logger) {
+        logger.warn("Signal score out of range; clamped to [0, 1].", {
+            originalScore: score,
+            clampedScore: clamped,
+            ...context,
+        });
+    }
+    return clamped;
+}
+//# sourceMappingURL=score-utils.js.map

package/dist/scanners/score-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-utils.js","sourceRoot":"","sources":["../../src/scanners/score-utils.ts"],"names":[],"mappings":"AAKA,uEAAuE;AACvE,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC;AAElC,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IACpE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QAC1C,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;QACjB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;QACjB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAa,EACb,MAAyB,EACzB,UAAmC,EAAE;IAErC,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,OAAO,KAAK,KAAK,IAAI,MAAM,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,+CAA+C,EAAE;YAC3D,aAAa,EAAE,KAAK;YACpB,YAAY,EAAE,OAAO;YACrB,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/scanners/store/fs-utils.d.ts

@@ -0,0 +1,12 @@
+/** Returns true when a filesystem path exists and is accessible. */
+export declare function pathExists(path: string): Promise<boolean>;
+/** Serializes JSON with stable formatting and writes atomically. */
+export declare function writeJsonAtomic(path: string, data: unknown): Promise<void>;
+/**
+ * Writes text atomically by writing to a temporary file then renaming in-place.
+ * Ensures readers never observe partial content.
+ */
+export declare function writeTextAtomic(path: string, content: string): Promise<void>;
+/** Reads and parses JSON; returns null when file does not exist or is invalid. */
+export declare function readJsonFile<T>(path: string): Promise<T | null>;
+//# sourceMappingURL=fs-utils.d.ts.map

package/dist/scanners/store/fs-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../../../src/scanners/store/fs-utils.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED,oEAAoE;AACpE,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhF;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclF;AAED,kFAAkF;AAClF,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOrE"}