@senpi/trading-runtime 1.0.0

package/dist/scanners/implementations/sm-flip.js

@@ -0,0 +1,200 @@
+import { Type } from "@sinclair/typebox";
+import { createScanner } from "../create-scanner.js";
+import { providerInput } from "../input-descriptors.js";
+import { clamp01 } from "../score-utils.js";
+import { PersistencePolicy, RetentionPolicy } from "../scanner-definition.js";
+// ─── Config ─────────────────────────────────────────────────────────────────
+const smFlipConfigSchema = Type.Object({
+    minConviction: Type.Optional(Type.Number({ minimum: 0, default: 4 })),
+});
+const smFlipStateSchema = Type.Object({
+    scans: Type.Number({ minimum: 0 }),
+    totalFlips: Type.Number({ minimum: 0 }),
+});
+// ─── Defaults ───────────────────────────────────────────────────────────────
+const defaultConfig = {
+    minConviction: 4,
+};
+const defaultState = {
+    scans: 0,
+    totalFlips: 0,
+};
+// ─── Conviction scoring ─────────────────────────────────────────────────────
+/**
+ * Scores smart-money conviction for a flip event.
+ *
+ * Based on Fox's sm-flip-check.py conviction algorithm:
+ * - pctOfTopTradersGain contribution (0-3 points)
+ * - traderCount concentration (0-3 points)
+ *
+ * Returns a score from 0 to 6. Fox uses minConviction=4 as default threshold.
+ */
+export function scoreConviction(sm) {
+    let score = 0;
+    // Contribution scoring
+    if (sm.pctOfTopTradersGain > 0.05)
+        score += 3;
+    else if (sm.pctOfTopTradersGain > 0.02)
+        score += 2;
+    else if (sm.pctOfTopTradersGain > 0)
+        score += 1;
+    // Trader count scoring
+    if (sm.traderCount >= 5)
+        score += 3;
+    else if (sm.traderCount >= 3)
+        score += 2;
+    else if (sm.traderCount >= 1)
+        score += 1;
+    return score;
+}
+/**
+ * Normalizes the SM data direction string to "LONG" | "SHORT".
+ * SM data uses "up"/"long" for longs and "short"/"down" for shorts.
+ */
+function normalizeSmDirection(direction) {
+    const lower = direction.toLowerCase();
+    return lower === "short" || lower === "down" ? "SHORT" : "LONG";
+}
+/**
+ * Detects whether a smart-money direction flips against a position direction.
+ */
+export function isFlipped(positionDirection, smDirection) {
+    const posDir = positionDirection.toUpperCase();
+    const smDir = normalizeSmDirection(smDirection);
+    return posDir !== smDir;
+}
+/**
+ * Extracts asset and direction from a loosely-typed active position record.
+ * Returns null if required fields are missing or invalid.
+ */
+function parsePosition(record) {
+    const asset = typeof record.coin === "string"
+        ? record.coin
+        : typeof record.asset === "string"
+            ? record.asset
+            : null;
+    if (!asset)
+        return null;
+    let direction = null;
+    if (typeof record.direction === "string") {
+        const d = record.direction.toUpperCase();
+        if (d === "LONG" || d === "SHORT")
+            direction = d;
+    }
+    // Hyperliquid clearinghouse uses szi (signed size): positive = long, negative = short
+    if (!direction && typeof record.szi === "string") {
+        const szi = parseFloat(record.szi);
+        if (Number.isFinite(szi) && szi !== 0) {
+            direction = szi > 0 ? "LONG" : "SHORT";
+        }
+    }
+    if (!direction && typeof record.size === "number") {
+        if (record.size > 0)
+            direction = "LONG";
+        else if (record.size < 0)
+            direction = "SHORT";
+    }
+    if (!direction)
+        return null;
+    return { asset, direction };
+}
+// ─── Token key helpers ──────────────────────────────────────────────────────
+/** Extracts the base token symbol from an SM market (ignoring DEX qualifier). */
+function smTokenKey(market) {
+    return market.token;
+}
+// ─── Scanner factory ────────────────────────────────────────────────────────
+/**
+ * Creates the SM Flip scanner.
+ *
+ * Monitors open positions against the smart-money leaderboard and detects
+ * when smart-money conviction reverses direction against a held position.
+ * Emits high-priority FLIP_NOW signals that should trigger immediate
+ * position closure.
+ *
+ * Inputs:
+ * - smData: smart-money leaderboard from `leaderboard_get_markets`
+ * - activePositions: current positions from `strategy_get_clearinghouse_state`
+ */
+export function smFlipScanner() {
+    return createScanner({
+        id: "sm-flip",
+        signalType: "SM_FLIP",
+        description: "Detects smart-money conviction reversal against open positions.",
+        intervalSeconds: 300,
+        retention: RetentionPolicy.ROLLING_WINDOW,
+        retentionMaxRuns: 100,
+        persistence: PersistencePolicy.ACTIONABLE_ONLY,
+        inputs: [providerInput.smData(), providerInput.activePositions()],
+        configSchema: smFlipConfigSchema,
+        defaultConfig,
+        stateSchema: smFlipStateSchema,
+        defaultState,
+        scan: async (ctx) => {
+            const now = ctx.now();
+            const cfg = ctx.config;
+            const smData = ctx.inputs.smData ?? [];
+            const positions = ctx.inputs.activePositions ?? [];
+            const signals = [];
+            // Build a lookup map for SM data by token
+            const smByToken = new Map();
+            for (const sm of smData) {
+                smByToken.set(smTokenKey(sm), sm);
+            }
+            for (const posRecord of positions) {
+                const pos = parsePosition(posRecord);
+                if (!pos)
+                    continue;
+                const smEntry = smByToken.get(pos.asset);
+                if (!smEntry)
+                    continue;
+                if (!isFlipped(pos.direction, smEntry.direction))
+                    continue;
+                const conviction = scoreConviction(smEntry);
+                if (conviction < (cfg.minConviction ?? 4))
+                    continue;
+                const newSmDirection = normalizeSmDirection(smEntry.direction);
+                signals.push({
+                    address: ctx.address,
+                    scannerId: ctx.scannerId,
+                    signalType: "FLIP_NOW",
+                    asset: pos.asset,
+                    direction: newSmDirection,
+                    score: clamp01(conviction / 6),
+                    timestamp: now,
+                    factors: {
+                        sm_direction_flip: true,
+                        high_conviction: conviction >= 5,
+                        deep_reversal: smEntry.pctOfTopTradersGain > 0.05,
+                    },
+                    meta: {
+                        positionDirection: pos.direction,
+                        smDirection: smEntry.direction,
+                        newDirection: newSmDirection,
+                        conviction,
+                        traderCount: smEntry.traderCount,
+                        pctOfTopTradersGain: smEntry.pctOfTopTradersGain,
+                        positionAsset: pos.asset,
+                    },
+                });
+            }
+            const nextState = {
+                scans: ctx.state.scans + 1,
+                totalFlips: ctx.state.totalFlips + signals.length,
+            };
+            await ctx.setState(nextState);
+            return {
+                timestamp: now,
+                scannedCount: positions.length,
+                signals,
+                summary: {
+                    positionsChecked: positions.length,
+                    smMarketsAvailable: smData.length,
+                    flipsDetected: signals.length,
+                    scans: nextState.scans,
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=sm-flip.js.map

package/dist/scanners/implementations/sm-flip.js.map

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

package/dist/scanners/index.d.ts

@@ -0,0 +1,24 @@
+export { type ScannerRuntimeEventMap, type ScannerRuntimeEventName, type ScannerRunCompleteEvent, type ScannerRunErrorEvent, type ScannerRunSkipEvent, type ScannerRunStartEvent, } from "./events.js";
+export { createScannerRuntimeModule, type ScannerFactory, type ScannerInput, type ScannerRuntimeModule, type ScannerRuntimeModuleOptions, } from "./runtime-module.js";
+export { createScanner, type CreateScannerOptions } from "./create-scanner.js";
+export { providerInput, type ActivePositionsInputDescriptor, type CandlesInputDescriptor, type InstrumentsInputDescriptor, type ProviderInputDescriptor, type ScannerInputDescriptor, type SmDataInputDescriptor, } from "./input-descriptors.js";
+export type { ScannerDataProviders } from "./engine/data-providers.js";
+export type { ScannerRegistrationSummary } from "./engine/engine.js";
+export type { Scanner } from "./protocol/scanner.js";
+export type { ScannerHooks } from "./protocol/hooks.js";
+export { SkipScan } from "./protocol/hooks.js";
+export { PersistencePolicy, RetentionPolicy, type ScannerDefinition, } from "./scanner-definition.js";
+export { consumeSharedArtifact, btcCacheArtifact, defineSharedArtifact, oiHistoryArtifact, prescreenedArtifact, type ArtifactProviderSource, type BtcCacheArtifact, type ConsumedArtifactBinding, type OiHistoryArtifact, type PrescreenedArtifact, type PrescreenedCandidate, type SharedArtifactContract, type SharedArtifactValue, type SharedArtifactValueMap, } from "./artifacts.js";
+export { type Candidate, type Instrument, type OiSnapshot, type ReadSignalsFilter, type ScanResult, ScanStatus, type ScannerId, type Signal, type StrategyId, type StrategyRegistration, } from "./types.js";
+export type { Candle, CandleResult, InstrumentContext, ParsedCandles, SmMarket, } from "./types.js";
+export { createSenpiScannerProviders, type SenpiScannerProviderFactoryOptions, type SenpiProviderCacheTtlMs, type SenpiProviderTimeouts, type SenpiProviderToolNames, } from "./providers/factory.js";
+export type { ProviderLogLevel, ProviderLogger, ProviderToolClient, SenpiToolClient, } from "./providers/client.js";
+export { emergingMoversScanner } from "./implementations/emerging-movers.js";
+export { momentumScanner } from "./implementations/momentum.js";
+export { oiTrackerScanner } from "./implementations/oi-tracker.js";
+export { prescreenerScanner } from "./implementations/prescreener.js";
+export { marketRegimeScanner } from "./implementations/market-regime.js";
+export { smFlipScanner } from "./implementations/sm-flip.js";
+export { opportunityScanner } from "./implementations/opportunity.js";
+export { marketRegimeArtifact, MarketRegime, type MarketRegimeArtifact, } from "./artifacts.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scanners/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,0BAA0B,EAC1B,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,GACjC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,iBAAiB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,UAAU,EACV,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,MAAM,EACN,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,2BAA2B,EAC3B,KAAK,kCAAkC,EACvC,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC"}

package/dist/scanners/index.js

@@ -0,0 +1,17 @@
+export { createScannerRuntimeModule, } from "./runtime-module.js";
+export { createScanner } from "./create-scanner.js";
+export { providerInput, } from "./input-descriptors.js";
+export { SkipScan } from "./protocol/hooks.js";
+export { PersistencePolicy, RetentionPolicy, } from "./scanner-definition.js";
+export { consumeSharedArtifact, btcCacheArtifact, defineSharedArtifact, oiHistoryArtifact, prescreenedArtifact, } from "./artifacts.js";
+export { ScanStatus, } from "./types.js";
+export { createSenpiScannerProviders, } from "./providers/factory.js";
+export { emergingMoversScanner } from "./implementations/emerging-movers.js";
+export { momentumScanner } from "./implementations/momentum.js";
+export { oiTrackerScanner } from "./implementations/oi-tracker.js";
+export { prescreenerScanner } from "./implementations/prescreener.js";
+export { marketRegimeScanner } from "./implementations/market-regime.js";
+export { smFlipScanner } from "./implementations/sm-flip.js";
+export { opportunityScanner } from "./implementations/opportunity.js";
+export { marketRegimeArtifact, MarketRegime, } from "./artifacts.js";
+//# sourceMappingURL=index.js.map

package/dist/scanners/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scanners/index.ts"],"names":[],"mappings":"AASA,OAAO,EACL,0BAA0B,GAK3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,aAAa,GAOd,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EACjB,eAAe,GAEhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,GAUpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAML,UAAU,GAKX,MAAM,YAAY,CAAC;AAQpB,OAAO,EACL,2BAA2B,GAK5B,MAAM,wBAAwB,CAAC;AAOhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EACL,oBAAoB,EACpB,YAAY,GAEb,MAAM,gBAAgB,CAAC"}

package/dist/scanners/input-descriptors.d.ts

@@ -0,0 +1,49 @@
+import type { ConsumedArtifactBinding, SharedArtifactContract } from "./artifacts.js";
+import type { SharedArtifactKey } from "./types.js";
+/** Provider-backed instruments input for one scan run. */
+export interface InstrumentsInputDescriptor {
+    kind: "instruments";
+}
+/** Provider-backed candle input for one scan run. */
+export interface CandlesInputDescriptor<Key extends SharedArtifactKey = SharedArtifactKey> {
+    kind: "candles";
+    /** Optional shared artifact used to narrow the candle asset fanout. */
+    preferredAssetsFrom?: Key | SharedArtifactContract<Key>;
+    /** Optional hardcoded asset list to narrow the candle request. Takes precedence over `preferredAssetsFrom`. */
+    fixedAssets?: string[];
+}
+/** Provider-backed smart-money leaderboard input for one scan run. */
+export interface SmDataInputDescriptor {
+    kind: "smData";
+}
+/** Provider-backed active-position input for one scan run. */
+export interface ActivePositionsInputDescriptor {
+    kind: "activePositions";
+}
+/** Declarative provider-backed scanner inputs. */
+export type ProviderInputDescriptor = InstrumentsInputDescriptor | CandlesInputDescriptor | SmDataInputDescriptor | ActivePositionsInputDescriptor;
+/** Declarative scanner input descriptor covering providers and shared artifacts. */
+export type ScannerInputDescriptor = ProviderInputDescriptor | ConsumedArtifactBinding;
+/** Builder helpers for provider-backed scanner inputs. */
+export declare const providerInput: {
+    /** Declares that a scanner needs the current instrument universe for each run. */
+    instruments(): InstrumentsInputDescriptor;
+    /**
+     * Declares that a scanner needs candle data for each run.
+     * `preferredAssetsFrom` lets upstream shared artifacts narrow the requested asset set.
+     * `fixedAssets` provides a hardcoded asset list (takes precedence over `preferredAssetsFrom`).
+     */
+    candles<Key extends SharedArtifactKey>(options?: {
+        preferredAssetsFrom?: Key | SharedArtifactContract<Key>;
+        fixedAssets?: string[];
+    }): CandlesInputDescriptor<Key>;
+    /** Declares that a scanner needs smart-money leaderboard data for each run. */
+    smData(): SmDataInputDescriptor;
+    /** Declares that a scanner needs the currently active positions for each run. */
+    activePositions(): ActivePositionsInputDescriptor;
+};
+/** Runtime guard for provider-backed input descriptors. */
+export declare function isProviderInputDescriptor(input: ScannerInputDescriptor): input is ProviderInputDescriptor;
+/** Runtime guard for consumed shared-artifact bindings in the inputs array. */
+export declare function isConsumedArtifactBinding(input: ScannerInputDescriptor): input is ConsumedArtifactBinding;
+//# sourceMappingURL=input-descriptors.d.ts.map

package/dist/scanners/input-descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-descriptors.d.ts","sourceRoot":"","sources":["../../src/scanners/input-descriptors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB,CACrC,GAAG,SAAS,iBAAiB,GAAG,iBAAiB;IAEjD,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,mBAAmB,CAAC,EAAE,GAAG,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;IACxD,+GAA+G;IAC/G,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,8DAA8D;AAC9D,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,kDAAkD;AAClD,MAAM,MAAM,uBAAuB,GAC/B,0BAA0B,GAC1B,sBAAsB,GACtB,qBAAqB,GACrB,8BAA8B,CAAC;AAEnC,oFAAoF;AACpF,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,uBAAuB,CAAC;AAE5B,0DAA0D;AAC1D,eAAO,MAAM,aAAa;IACxB,kFAAkF;mBACnE,0BAA0B;IAIzC;;;;OAIG;YACK,GAAG,SAAS,iBAAiB,YAC1B;QAAE,mBAAmB,CAAC,EAAE,GAAG,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC3F,sBAAsB,CAAC,GAAG,CAAC;IAO9B,+EAA+E;cACrE,qBAAqB;IAI/B,iFAAiF;uBAC9D,8BAA8B;CAGlD,CAAC;AAEF,2DAA2D;AAC3D,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,sBAAsB,GAC5B,KAAK,IAAI,uBAAuB,CAElC;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,sBAAsB,GAC5B,KAAK,IAAI,uBAAuB,CAElC"}

package/dist/scanners/input-descriptors.js

@@ -0,0 +1,35 @@
+/** Builder helpers for provider-backed scanner inputs. */
+export const providerInput = {
+    /** Declares that a scanner needs the current instrument universe for each run. */
+    instruments() {
+        return { kind: "instruments" };
+    },
+    /**
+     * Declares that a scanner needs candle data for each run.
+     * `preferredAssetsFrom` lets upstream shared artifacts narrow the requested asset set.
+     * `fixedAssets` provides a hardcoded asset list (takes precedence over `preferredAssetsFrom`).
+     */
+    candles(options = {}) {
+        return {
+            kind: "candles",
+            ...options,
+        };
+    },
+    /** Declares that a scanner needs smart-money leaderboard data for each run. */
+    smData() {
+        return { kind: "smData" };
+    },
+    /** Declares that a scanner needs the currently active positions for each run. */
+    activePositions() {
+        return { kind: "activePositions" };
+    },
+};
+/** Runtime guard for provider-backed input descriptors. */
+export function isProviderInputDescriptor(input) {
+    return "kind" in input;
+}
+/** Runtime guard for consumed shared-artifact bindings in the inputs array. */
+export function isConsumedArtifactBinding(input) {
+    return "contract" in input;
+}
+//# sourceMappingURL=input-descriptors.js.map

package/dist/scanners/input-descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-descriptors.js","sourceRoot":"","sources":["../../src/scanners/input-descriptors.ts"],"names":[],"mappings":"AAyCA,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,kFAAkF;IAClF,WAAW;QACT,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,OAAO,CACL,UAA+F,EAAE;QAEjG,OAAO;YACL,IAAI,EAAE,SAAS;YACf,GAAG,OAAO;SACX,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,MAAM;QACJ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED,iFAAiF;IACjF,eAAe;QACb,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;IACrC,CAAC;CACF,CAAC;AAEF,2DAA2D;AAC3D,MAAM,UAAU,yBAAyB,CACvC,KAA6B;IAE7B,OAAO,MAAM,IAAI,KAAK,CAAC;AACzB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,yBAAyB,CACvC,KAA6B;IAE7B,OAAO,UAAU,IAAI,KAAK,CAAC;AAC7B,CAAC"}

package/dist/scanners/protocol/context.d.ts

@@ -0,0 +1,71 @@
+import type { SharedArtifactContract, SharedArtifactValue, SharedArtifactValueMap } from "../artifacts.js";
+import type { ScannerDefinition } from "../scanner-definition.js";
+import type { ScannerRuntimeState } from "../store/runtime-store.js";
+import type { CandleResult, Instrument, OiSnapshot, ScannerId, SharedArtifactKey, SmMarket } from "../types.js";
+type ReadonlyPrimitive = bigint | boolean | null | number | string | symbol | undefined;
+type ReadonlyDeepArray<Item> = ReadonlyArray<ReadonlyDeep<Item>>;
+type ReadonlyDeepObject<T extends object> = {
+    readonly [Key in keyof T]: ReadonlyDeep<T[Key]>;
+};
+/**
+ * Recursively marks nested scan-input payloads as readonly.
+ * This is used for artifact-backed inputs so scanners cannot mutate shared
+ * market intelligence snapshots in place.
+ */
+type ReadonlyDeep<T> = T extends ReadonlyPrimitive ? T : T extends (...args: never[]) => unknown ? T : T extends readonly (infer Item)[] ? ReadonlyDeepArray<Item> : T extends object ? ReadonlyDeepObject<T> : T;
+/** Candle data indexed first by asset, then by timeframe within each candle result. */
+export type CandlesByAsset = Readonly<Record<string, Readonly<CandleResult>>>;
+/** Open-interest history indexed by asset name. */
+export type OiHistoryByAsset = Readonly<Record<string, readonly Readonly<OiSnapshot>[]>>;
+/**
+ * Shared market intelligence resolved for one scan run.
+ * These values come from shared artifact bindings rather than direct provider needs.
+ */
+export type ScanArtifactInputs = Partial<{
+    readonly [Key in keyof SharedArtifactValueMap]: ReadonlyDeep<SharedArtifactValueMap[Key]>;
+}>;
+/**
+ * Data payload assembled by engine for one scan run.
+ * Top-level fields are provider-backed inputs; `artifacts` contains shared
+ * market intelligence. Scanners should treat this snapshot as read-only input.
+ */
+export interface ScanInputs {
+    readonly instruments?: readonly Readonly<Instrument>[];
+    readonly candles?: CandlesByAsset;
+    readonly smData?: readonly Readonly<SmMarket>[];
+    readonly activePositions?: readonly Readonly<Record<string, unknown>>[];
+    readonly artifacts: ScanArtifactInputs;
+}
+/** Optional logger surface exposed to scanners and hooks. */
+export interface ScannerLogger {
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    error?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/** Shared-artifact accessors available to scanners for reading and writing shared market intelligence. */
+export interface SharedArtifactAccessor {
+    loadSharedArtifact: <Key extends SharedArtifactKey>(artifact: Key | SharedArtifactContract<Key>, opts?: {
+        maxAgeMs?: number;
+    }) => Promise<SharedArtifactValue<Key> | null>;
+    saveSharedArtifact: <Key extends SharedArtifactKey>(artifact: Key | SharedArtifactContract<Key>, value: SharedArtifactValue<Key>) => Promise<void>;
+}
+/** Context passed once during scanner bootstrap. */
+export interface ScannerInitContext<Cfg = unknown, St = unknown> extends SharedArtifactAccessor {
+    address: string;
+    scannerId: ScannerId;
+    definition: ScannerDefinition<Cfg, St>;
+    runtime: ScannerRuntimeState<Cfg, St>;
+    config: Cfg;
+    state: St;
+    now: () => number;
+    logger?: ScannerLogger;
+    setState: (nextState: St) => Promise<void>;
+}
+/** Context passed on each scan run after runtime and inputs are loaded. */
+export interface ScanContext<Cfg = unknown, St = unknown> extends ScannerInitContext<Cfg, St> {
+    runStartedAt: number;
+    inputs: ScanInputs;
+}
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/scanners/protocol/context.d.ts.map

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

package/dist/scanners/protocol/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/scanners/protocol/context.js.map

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

package/dist/scanners/protocol/hooks.d.ts

@@ -0,0 +1,18 @@
+import { ScanStatus } from "../types.js";
+import type { Signal } from "../types.js";
+import type { ScanContext } from "./context.js";
+/** Optional pre/post scan behavior customizations for one scanner. */
+export interface ScannerHooks<Cfg = unknown, St = unknown> {
+    beforeScan?: (ctx: ScanContext<Cfg, St>) => ScanContext<Cfg, St> | Promise<ScanContext<Cfg, St>>;
+    isActionable?: (signal: Signal, ctx: ScanContext<Cfg, St>) => boolean;
+}
+export interface SkipScanOptions {
+    status?: ScanStatus;
+    cause?: unknown;
+}
+/** Error used by scanner hooks or scanner code to halt one run with a status. */
+export declare class SkipScan extends Error {
+    readonly status: ScanStatus;
+    constructor(message?: string, options?: SkipScanOptions);
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/scanners/protocol/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/scanners/protocol/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,sEAAsE;AACtE,MAAM,WAAW,YAAY,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;IACvD,UAAU,CAAC,EAAE,CACX,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,KACtB,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC;CACvE;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,iFAAiF;AACjF,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;gBAEhB,OAAO,SAAkB,EAAE,OAAO,GAAE,eAAoB;CAOrE"}

package/dist/scanners/protocol/hooks.js

@@ -0,0 +1,12 @@
+import { ScanStatus } from "../types.js";
+/** Error used by scanner hooks or scanner code to halt one run with a status. */
+export class SkipScan extends Error {
+    status;
+    constructor(message = "Scan skipped.", options = {}) {
+        const errorOptions = options.cause === undefined ? undefined : { cause: options.cause };
+        super(message, errorOptions);
+        this.name = "SkipScan";
+        this.status = options.status ?? ScanStatus.SKIPPED;
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/scanners/protocol/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/scanners/protocol/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiBzC,iFAAiF;AACjF,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAa;IAE5B,YAAY,OAAO,GAAG,eAAe,EAAE,UAA2B,EAAE;QAClE,MAAM,YAAY,GAChB,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACrE,KAAK,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC,OAAO,CAAC;IACrD,CAAC;CACF"}

package/dist/scanners/protocol/index.d.ts

@@ -0,0 +1,5 @@
+export type { Scanner } from "./scanner.js";
+export type { ScannerHooks } from "./hooks.js";
+export { SkipScan, type SkipScanOptions } from "./hooks.js";
+export type { CandlesByAsset, OiHistoryByAsset, ScanInputs, ScannerLogger, SharedArtifactAccessor, ScannerInitContext, ScanContext, } from "./context.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/scanners/protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/scanners/protocol/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,WAAW,GACZ,MAAM,cAAc,CAAC"}

package/dist/scanners/protocol/index.js

@@ -0,0 +1,2 @@
+export { SkipScan } from "./hooks.js";
+//# sourceMappingURL=index.js.map

package/dist/scanners/protocol/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/scanners/protocol/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAwB,MAAM,YAAY,CAAC"}

package/dist/scanners/protocol/scanner.d.ts

@@ -0,0 +1,47 @@
+import type { ScannerDefinition } from "../scanner-definition.js";
+import type { ScannerScanOutput } from "../types.js";
+import type { ScanContext, ScannerInitContext } from "./context.js";
+import type { ScannerHooks } from "./hooks.js";
+/**
+ * Core scanner contract implemented by all strategy-runtime scanners.
+ *
+ * Each scanner declares a {@link ScannerDefinition} describing its identity,
+ * provider-backed inputs, shared market intelligence contracts, scheduling interval, and persistence/retention policies. The engine
+ * calls {@link initialize} once per (address, scannerId) registration, then
+ * calls {@link scan} on each scheduled or manual run.
+ *
+ * **Lifecycle:**
+ * 1. Engine loads/creates runtime state and builds an init context.
+ * 2. `initialize(ctx)` is called once — use it to bootstrap scanner-local state
+ *    or validate prerequisites. The init context provides `setState()` for persisting
+ *    initial state and `loadSharedArtifact()` / `saveSharedArtifact()` for shared market intelligence.
+ * 3. On each run, the engine builds a scan context with resolved provider-backed
+ *    inputs plus shared market intelligence under `ctx.inputs.artifacts`.
+ * 4. If `hooks.beforeScan` is defined, it runs first and may throw `SkipScan` to abort.
+ * 5. `scan(ctx)` executes scanner logic and returns signals + metadata.
+ * 6. The engine normalizes scores to [0, 1], applies `hooks.isActionable` filtering,
+ *    and persists results according to the scanner's policies.
+ *
+ * @typeParam Cfg - Scanner configuration type (validated against `definition.configSchema`).
+ * @typeParam St  - Scanner-local mutable state type (persisted across runs via `ctx.setState()`).
+ */
+export interface Scanner<Cfg = unknown, St = unknown> {
+    /** Static scanner metadata: identity, input contracts, scheduling, persistence. */
+    definition: ScannerDefinition<Cfg, St>;
+    /** Optional pre/post-scan behavior customizations. */
+    hooks?: ScannerHooks<Cfg, St>;
+    /**
+     * Called once per (address, scannerId) registration before the first scan.
+     * Use this to initialize scanner-local state, validate config, or load prerequisites.
+     * The context provides `setState()` for persisting initial state to disk.
+     */
+    initialize: (ctx: ScannerInitContext<Cfg, St>) => Promise<void>;
+    /**
+     * Executes one scanner run and returns signals with execution metadata.
+     * The context includes resolved provider-backed inputs, shared market intelligence,
+     * current config/state, and shared artifact accessors. Signals returned here are normalized by the
+     * engine (score clamping, factor coercion) before persistence.
+     */
+    scan: (ctx: ScanContext<Cfg, St>) => Promise<ScannerScanOutput>;
+}
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanners/protocol/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../../src/scanners/protocol/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,OAAO,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;IAClD,mFAAmF;IACnF,UAAU,EAAE,iBAAiB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAEvC,sDAAsD;IACtD,KAAK,CAAC,EAAE,YAAY,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAE9B;;;;OAIG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACjE"}

package/dist/scanners/protocol/scanner.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scanner.js.map

package/dist/scanners/protocol/scanner.js.map

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

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

@@ -0,0 +1,23 @@
+import type { CandleResult, Instrument, SmMarket } from "../types.js";
+/** Summary of rows/issues encountered while normalizing one provider payload. */
+export interface NormalizationDiagnostics {
+    acceptedCount: number;
+    discardedCount: number;
+    issueCounts: Record<string, number>;
+}
+/** Normalized value paired with diagnostics describing discarded rows/issues. */
+export interface NormalizationResult<T> {
+    value: T;
+    diagnostics: NormalizationDiagnostics;
+}
+/** Strictly maps `market_list_instruments` payload into scanner `Instrument[]`. */
+export declare function normalizeInstruments(raw: unknown): Instrument[];
+/** Strictly maps `market_list_instruments` payload and reports discarded-row diagnostics. */
+export declare function normalizeInstrumentsWithDiagnostics(raw: unknown): NormalizationResult<Instrument[]>;
+/** Strictly maps one `market_get_asset_data` payload into scanner `CandleResult`. */
+export declare function normalizeAssetCandles(raw: unknown): CandleResult;
+/** Strictly maps `leaderboard_get_markets` payload into scanner `SmMarket[]`. */
+export declare function normalizeSmMarkets(raw: unknown): SmMarket[];
+/** Strictly maps `leaderboard_get_markets` payload and reports discarded-row diagnostics. */
+export declare function normalizeSmMarketsWithDiagnostics(raw: unknown): NormalizationResult<SmMarket[]>;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/scanners/providers/adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAU,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAS9E,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,KAAK,EAAE,CAAC,CAAC;IACT,WAAW,EAAE,wBAAwB,CAAC;CACvC;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,EAAE,CAE/D;AAED,6FAA6F;AAC7F,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,OAAO,GACX,mBAAmB,CAAC,UAAU,EAAE,CAAC,CAuEnC;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAqChE;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,EAAE,CAE3D;AAED,6FAA6F;AAC7F,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,OAAO,GACX,mBAAmB,CAAC,QAAQ,EAAE,CAAC,CAiDjC"}