@senpi/trading-runtime 1.0.0

package/dist/scanners/implementations/emerging-movers.js

@@ -0,0 +1,702 @@
+import { Type } from "@sinclair/typebox";
+import { createScanner } from "../create-scanner.js";
+import { consumeSharedArtifact, MarketRegime, marketRegimeArtifact } from "../artifacts.js";
+import { providerInput } from "../input-descriptors.js";
+import { clamp01 } from "../score-utils.js";
+import { PersistencePolicy, RetentionPolicy } from "../scanner-definition.js";
+/**
+ * Numeric priority per signal type (1 = highest).
+ * Used to sort signals so that the action layer processes the most urgent first.
+ */
+const SIGNAL_PRIORITY = {
+    FIRST_JUMP: 1,
+    CONTRIB_EXPLOSION: 2,
+    IMMEDIATE_MOVER: 3,
+    NEW_ENTRY_DEEP: 4,
+    DEEP_CLIMBER: 5,
+};
+/**
+ * Default conviction score per signal type, mapped to the [0, 1] range
+ * consumed by the action layer. Higher conviction = stronger entry signal.
+ * These are used as the signal's `score` field so downstream consumers can
+ * sort/filter without knowing the signal type taxonomy.
+ */
+const SIGNAL_CONVICTION = {
+    FIRST_JUMP: 0.95,
+    CONTRIB_EXPLOSION: 0.90,
+    IMMEDIATE_MOVER: 0.85,
+    NEW_ENTRY_DEEP: 0.80,
+    DEEP_CLIMBER: 0.60,
+};
+// ─── Config ─────────────────────────────────────────────────────────────────
+const emergingMoversConfigSchema = Type.Object({
+    topN: Type.Number({ minimum: 1, default: 50 }),
+    minRankJump: Type.Number({ minimum: 1, default: 5 }),
+    minTopTradersGain: Type.Number({ minimum: 0, default: 0.1 }),
+    minScansBeforeSignals: Type.Number({ minimum: 1, default: 2 }),
+    historyLimit: Type.Number({ minimum: 2, default: 60 }),
+    immediateJumpThreshold: Type.Optional(Type.Number({ minimum: 1, default: 10 })),
+    deepClimbRankThreshold: Type.Optional(Type.Number({ minimum: 1, default: 25 })),
+    contribExplosionMultiplier: Type.Optional(Type.Number({ minimum: 1, default: 3.0 })),
+    contribAccelThreshold: Type.Optional(Type.Number({ minimum: 0, default: 0.003 })),
+    minVelocityForDeepClimber: Type.Optional(Type.Number({ minimum: 0, default: 0.0003 })),
+    erraticReversalThreshold: Type.Optional(Type.Number({ minimum: 1, default: 5 })),
+    climbStreakScans: Type.Optional(Type.Number({ minimum: 2, default: 3 })),
+    rankClimbThreshold: Type.Optional(Type.Number({ minimum: 1, default: 3 })),
+    newEntryDeepMaxRank: Type.Optional(Type.Number({ minimum: 1, default: 20 })),
+    newEntryMaxRank: Type.Optional(Type.Number({ minimum: 1, default: 35 })),
+    firstJumpMinPrevRank: Type.Optional(Type.Number({ minimum: 1, default: 30 })),
+    /** Enable regime-aware score gating via market-regime artifact. Default: false (disabled). */
+    regimeScoreGating: Type.Optional(Type.Boolean({ default: false })),
+    /** Score threshold when market regime is NEUTRAL. Only used when regimeScoreGating is true. */
+    regimeScoreNeutral: Type.Optional(Type.Number({ minimum: 0, maximum: 1, default: 0.8 })),
+    /** Score threshold when market regime is BULLISH or BEARISH. Only used when regimeScoreGating is true. */
+    regimeScoreDefault: Type.Optional(Type.Number({ minimum: 0, maximum: 1, default: 0.7 })),
+    /** Minimum asset max leverage to emit signals. 0 = disabled (no filtering). */
+    minLeverage: Type.Optional(Type.Number({ minimum: 0, default: 0 })),
+});
+const emergingMoversStateSchema = Type.Object({
+    scans: Type.Number({ minimum: 0 }),
+    rankHistory: Type.Record(Type.String(), Type.Array(Type.Number())),
+    contribHistory: Type.Record(Type.String(), Type.Array(Type.Number())),
+    prevTopTokens: Type.Array(Type.String()),
+});
+// ─── Defaults ───────────────────────────────────────────────────────────────
+const defaultConfig = {
+    topN: 50,
+    minRankJump: 5,
+    minTopTradersGain: 0.1,
+    minScansBeforeSignals: 2,
+    historyLimit: 60,
+    immediateJumpThreshold: 10,
+    deepClimbRankThreshold: 25,
+    contribExplosionMultiplier: 3.0,
+    contribAccelThreshold: 0.003,
+    minVelocityForDeepClimber: 0.0003,
+    erraticReversalThreshold: 5,
+    climbStreakScans: 3,
+    rankClimbThreshold: 3,
+    newEntryDeepMaxRank: 20,
+    newEntryMaxRank: 35,
+    firstJumpMinPrevRank: 30,
+    regimeScoreGating: false,
+    regimeScoreNeutral: 0.8,
+    regimeScoreDefault: 0.7,
+    minLeverage: 0,
+};
+const defaultState = {
+    scans: 0,
+    rankHistory: {},
+    contribHistory: {},
+    prevTopTokens: [],
+};
+// ─── Pure helpers (exported for testing) ────────────────────────────────────
+/**
+ * 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 function isErraticHistory(rankHistory, erraticReversalThreshold, excludeLast = false) {
+    let nums = rankHistory.filter((r) => r !== null);
+    if (excludeLast && nums.length > 1) {
+        nums = nums.slice(0, -1);
+    }
+    if (nums.length < 3)
+        return false;
+    for (let i = 1; i < nums.length - 1; i++) {
+        const prevDelta = nums[i] - nums[i - 1];
+        const nextDelta = nums[i + 1] - nums[i];
+        if (prevDelta < 0 && nextDelta > erraticReversalThreshold)
+            return true;
+        if (prevDelta > 0 && nextDelta < -erraticReversalThreshold)
+            return true;
+    }
+    return false;
+}
+/**
+ * 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 function computeContribVelocity(contribs) {
+    if (contribs.length < 2)
+        return 0;
+    const total = contribs[contribs.length - 1] - contribs[0];
+    return total / (contribs.length - 1);
+}
+/**
+ * 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 function classifySignal(alert, config) {
+    if (alert.reasons.length === 0)
+        return null;
+    let signalType = resolveSignalType(alert);
+    const erratic = checkErratic(alert, config);
+    const lowVelocity = checkLowVelocity(alert, config);
+    // FIRST_JUMP and CONTRIB_EXPLOSION are never downgraded
+    if (signalType === "IMMEDIATE_MOVER" && (erratic || lowVelocity)) {
+        signalType = "DEEP_CLIMBER";
+    }
+    return {
+        signalType,
+        priority: SIGNAL_PRIORITY[signalType],
+        conviction: SIGNAL_CONVICTION[signalType],
+        erratic,
+        lowVelocity,
+    };
+}
+// ─── Signal type resolution ─────────────────────────────────────────────────
+/**
+ * Maps detection flags to the highest-priority applicable signal type.
+ *
+ * The check order is deliberate:
+ * - FIRST_JUMP before everything — it's the strongest "catch it early" signal.
+ * - CONTRIB_EXPLOSION before IMMEDIATE — contribution spike is independent of rank.
+ * - NEW_ENTRY_DEEP before IMMEDIATE — a brand-new token appearing in the top 20
+ *   is semantically different from an existing token jumping ranks.
+ * - IMMEDIATE_MOVER before DEEP_CLIMBER — larger, faster jumps rank higher.
+ * - DEEP_CLIMBER is the fallback for any remaining alert with reasons.
+ */
+function resolveSignalType(alert) {
+    if (alert.isFirstJump)
+        return "FIRST_JUMP";
+    if (alert.isContribExplosion)
+        return "CONTRIB_EXPLOSION";
+    if (alert.isDeepClimber && alert.reasons.some((r) => r.includes("NEW_ENTRY_DEEP"))) {
+        return "NEW_ENTRY_DEEP";
+    }
+    if (alert.isImmediate)
+        return "IMMEDIATE_MOVER";
+    return "DEEP_CLIMBER";
+}
+/**
+ * Determines whether the alert's rank history is erratic (zigzag).
+ *
+ * CONTRIB_EXPLOSION is exempt because the contribution spike itself is the
+ * signal — past rank noise doesn't diminish it. For big single-scan jumps
+ * (IMMEDIATE/FIRST_JUMP), only the *pre-jump* history is checked because
+ * the jump itself shouldn't count as a reversal.
+ */
+function checkErratic(alert, cfg) {
+    if (alert.isContribExplosion)
+        return false;
+    const excludeLast = alert.rankJumpThisScan >= cfg.immediateJumpThreshold || alert.isFirstJump;
+    return isErraticHistory(alert.rankHistoryWindow, cfg.erraticReversalThreshold, excludeLast);
+}
+/**
+ * Determines whether the alert's contribution velocity is too low.
+ *
+ * The threshold is split by urgency:
+ * - IMMEDIATE/FIRST_JUMP only require velocity > 0. These are one-scan
+ *   signals where velocity hasn't had time to build; demanding more
+ *   would filter out exactly the early entries the scanner is designed to catch.
+ * - DEEP_CLIMBER (slower, multi-scan) requires velocity >= `minVelocityForDeepClimber`
+ *   to confirm that the rank improvement is backed by growing SM concentration.
+ */
+function checkLowVelocity(alert, cfg) {
+    if (alert.isImmediate || alert.isFirstJump)
+        return alert.contribVelocity <= 0;
+    return alert.contribVelocity < cfg.minVelocityForDeepClimber;
+}
+// ─── Detection rules ────────────────────────────────────────────────────────
+// Each rule inspects the immutable MarketContext and appends reasons / flips
+// flags in the mutable DetectionFlags. Rules are ordered to match the Python
+// v4 detection pipeline so that flag interactions (e.g. isImmediate being set
+// before FIRST_JUMP is checked) are preserved.
+/**
+ * Rule 1 — Fresh entry detection.
+ *
+ * Fires when the token was not in the previous scan's top-N (`prevRank === null`).
+ * If the token lands directly in the top 20, it's flagged as NEW_ENTRY_DEEP
+ * with `isImmediate` (the market didn't gradually climb — it appeared strong).
+ * Tokens landing between #20 and #35 get a lower-priority NEW_ENTRY tag.
+ */
+function detectNewEntry(mctx, cfg, flags) {
+    if (mctx.prevRank !== null)
+        return;
+    if (mctx.rank <= cfg.newEntryDeepMaxRank) {
+        flags.reasons.push(`NEW_ENTRY_DEEP at rank #${mctx.rank}`);
+        flags.isDeepClimber = true;
+        flags.isImmediate = true;
+    }
+    else if (mctx.rank <= cfg.newEntryMaxRank) {
+        flags.reasons.push(`NEW_ENTRY at rank #${mctx.rank}`);
+    }
+}
+/**
+ * Rule 2 — Single-scan rank jump detection.
+ *
+ * Compares the token's rank in this scan vs. the previous one. Three tiers:
+ *
+ * - **FIRST_JUMP**: jump >= `immediateJumpThreshold` from >= `deepClimbRankThreshold`,
+ *   AND the token was either absent from the previous top-N or ranked >= `firstJumpMinPrevRank`.
+ *   This is the highest-priority signal — it catches tokens accelerating into
+ *   the leaderboard before they're widely noticed.
+ *
+ * - **IMMEDIATE_MOVER**: same jump magnitude but the token was already tracked
+ *   in the top-N at a rank < `firstJumpMinPrevRank` — still a strong signal
+ *   but with less surprise value than FIRST_JUMP.
+ *
+ * - **DEEP_CLIMBER**: jump >= `minRankJump` from >= `deepClimbRankThreshold`.
+ *   Moderate but notable improvement from deep in the list.
+ *
+ * Also records a RANK_UP reason for any jump >= 2 (informational, even if no
+ * signal type is triggered).
+ */
+function detectSingleScanJump(mctx, cfg, flags, prevTopTokenSet) {
+    if (mctx.prevRank === null)
+        return;
+    const jump = mctx.prevRank - mctx.rank;
+    flags.rankJumpThisScan = jump;
+    if (jump >= 2) {
+        flags.reasons.push(`RANK_UP +${jump} (#${mctx.prevRank}→#${mctx.rank})`);
+    }
+    if (jump >= cfg.immediateJumpThreshold && mctx.prevRank >= cfg.deepClimbRankThreshold) {
+        flags.isDeepClimber = true;
+        flags.isImmediate = true;
+        flags.reasons.push(`IMMEDIATE_MOVER +${jump} from #${mctx.prevRank} in ONE scan`);
+        const wasInPrev = prevTopTokenSet.has(mctx.tk);
+        if (!wasInPrev || mctx.prevRank >= cfg.firstJumpMinPrevRank) {
+            flags.isFirstJump = true;
+            flags.reasons.push(`FIRST_JUMP from #${mctx.prevRank}→#${mctx.rank} — highest priority`);
+        }
+    }
+    else if (jump >= cfg.minRankJump && mctx.prevRank >= cfg.deepClimbRankThreshold) {
+        flags.isDeepClimber = true;
+        flags.reasons.push(`DEEP_CLIMBER +${jump} from #${mctx.prevRank}`);
+    }
+}
+/**
+ * Rule 3 — Contribution explosion detection.
+ *
+ * Fires when the token's `pctOfTopTradersGain` increased by
+ * `contribExplosionMultiplier`x or more in a single scan. This indicates a
+ * sudden concentration of smart-money capital into the token — often the
+ * earliest sign of a coordinated move.
+ *
+ * When the explosion originates from a deep position (prevRank >= 20),
+ * the alert is also flagged as immediate/deep-climber to boost its priority.
+ */
+function detectContribExplosion(mctx, cfg, flags) {
+    if (mctx.prevContrib === null || mctx.prevContrib <= 0)
+        return;
+    const ratio = mctx.currentContrib / mctx.prevContrib;
+    if (ratio < cfg.contribExplosionMultiplier)
+        return;
+    const prev = (mctx.prevContrib * 100).toFixed(2);
+    const curr = (mctx.currentContrib * 100).toFixed(2);
+    flags.reasons.push(`CONTRIB_EXPLOSION ${ratio.toFixed(1)}x in one scan (${prev}→${curr})`);
+    flags.isContribExplosion = true;
+    if (mctx.prevRank !== null && mctx.prevRank >= cfg.newEntryDeepMaxRank) {
+        flags.isImmediate = true;
+        flags.isDeepClimber = true;
+    }
+}
+/**
+ * Rule 4 — Multi-scan cumulative climb detection.
+ *
+ * Looks back up to 5 scans and compares the oldest available rank to the
+ * current one. A total climb >= `rankClimbThreshold` adds a CLIMBING reason.
+ *
+ * If the cumulative climb is large enough (>= `immediateJumpThreshold`) and
+ * started from rank >= 30, it additionally flags as DEEP_CLIMBER — the token
+ * may not have jumped dramatically in any single scan but has been steadily
+ * rising from the depths.
+ */
+function detectMultiScanClimb(mctx, cfg, flags) {
+    const lookback = Math.min(mctx.prevRankHistory.length, 5);
+    if (lookback < 1)
+        return;
+    const oldRank = mctx.prevRankHistory[mctx.prevRankHistory.length - lookback];
+    if (oldRank === undefined)
+        return;
+    const totalClimb = oldRank - mctx.rank;
+    if (totalClimb >= cfg.rankClimbThreshold) {
+        flags.reasons.push(`CLIMBING +${totalClimb} over ${lookback} scans`);
+    }
+    if (totalClimb >= cfg.immediateJumpThreshold && oldRank >= 30) {
+        flags.isDeepClimber = true;
+        const alreadyTagged = flags.reasons.some((r) => r.includes("DEEP_CLIMBER") || r.includes("IMMEDIATE"));
+        if (!alreadyTagged) {
+            flags.reasons.push(`DEEP_CLIMBER +${totalClimb} from #${oldRank} over ${lookback} scans`);
+        }
+    }
+}
+/**
+ * Rule 5 — Single-scan contribution acceleration.
+ *
+ * Fires when the contribution delta (current - previous) exceeds
+ * `contribAccelThreshold`. Unlike the explosion rule (which checks
+ * *ratios*), this catches absolute contribution increases — relevant
+ * when the previous contribution was already substantial.
+ */
+function detectContribAccel(mctx, cfg, flags) {
+    if (mctx.prevContrib === null)
+        return;
+    const delta = mctx.currentContrib - mctx.prevContrib;
+    if (delta >= cfg.contribAccelThreshold) {
+        flags.reasons.push(`ACCEL +${delta.toFixed(3)} contribution`);
+    }
+}
+/**
+ * Rule 6 — Consistent climb streak detection.
+ *
+ * Checks whether the token's rank has improved (or stayed equal) in every
+ * scan over the last `climbStreakScans + 1` data points (including the current
+ * scan). A monotonically improving rank over multiple scans is a strong
+ * trend signal even when no single scan's jump is dramatic.
+ */
+function detectClimbStreak(mctx, cfg, flags) {
+    if (mctx.prevRankHistory.length < cfg.climbStreakScans)
+        return;
+    const window = [...mctx.prevRankHistory.slice(-cfg.climbStreakScans), mctx.rank];
+    const isMonotonic = window.every((r, i) => i === 0 || window[i - 1] >= r);
+    const totalGain = window[0] - window[window.length - 1];
+    if (isMonotonic && totalGain >= 2) {
+        flags.reasons.push(`STREAK climbing ${totalGain} ranks over ${window.length} checks`);
+    }
+}
+/**
+ * Rule 7 — Contribution velocity as a standalone signal.
+ *
+ * Computes the average contribution change per scan over the last 5 scans.
+ * If velocity exceeds 0.2%/scan, at least 3 data points are available, and
+ * *no other detection rule has fired*, a VELOCITY reason is emitted.
+ *
+ * This acts as a catch-all for tokens that are gaining SM concentration
+ * gradually — not enough for an explosion or a big rank jump, but sustained
+ * enough to be noteworthy.
+ *
+ * @returns The computed velocity value (always returned, regardless of whether
+ *   a reason was added) so that the caller can attach it to the alert.
+ */
+function detectVelocitySignal(mctx, flags) {
+    const recent = [...mctx.prevContribHistory.slice(-5), mctx.currentContrib];
+    const velocity = computeContribVelocity(recent);
+    if (velocity > 0.002 && recent.length >= 3 && flags.reasons.length === 0) {
+        flags.reasons.push(`VELOCITY +${(velocity * 100).toFixed(3)}%/scan sustained`);
+    }
+    return velocity;
+}
+// ─── Market analysis pipeline ───────────────────────────────────────────────
+/**
+ * Runs all detection rules against a single ranked market.
+ *
+ * This is the core of the scanner: it initialises empty detection flags,
+ * runs each rule in sequence (order matters — flags set by earlier rules
+ * affect later ones), computes contribution velocity, and assembles the
+ * full {@link AlertCandidate} if any reasons were found.
+ *
+ * @returns An alert candidate, or `null` if no detection rule fired.
+ */
+function analyzeMarket(mctx, cfg, prevTopTokenSet) {
+    const flags = {
+        reasons: [],
+        isDeepClimber: false,
+        isImmediate: false,
+        isFirstJump: false,
+        isContribExplosion: false,
+        rankJumpThisScan: 0,
+    };
+    detectNewEntry(mctx, cfg, flags);
+    detectSingleScanJump(mctx, cfg, flags, prevTopTokenSet);
+    detectContribExplosion(mctx, cfg, flags);
+    detectMultiScanClimb(mctx, cfg, flags);
+    detectContribAccel(mctx, cfg, flags);
+    detectClimbStreak(mctx, cfg, flags);
+    const contribVelocity = detectVelocitySignal(mctx, flags);
+    if (flags.reasons.length === 0)
+        return null;
+    return {
+        token: mctx.market.token,
+        dex: mctx.market.dex,
+        direction: mctx.market.direction,
+        currentRank: mctx.rank,
+        currentContrib: mctx.currentContrib,
+        priceChg4h: mctx.market.tokenPriceChangePct4h,
+        traderCount: mctx.market.traderCount,
+        ...flags,
+        contribVelocity,
+        rankHistoryWindow: [...mctx.prevRankHistory.slice(-5), mctx.rank],
+        contribHistoryWindow: [
+            ...mctx.prevContribHistory.slice(-5).map((c) => Math.round(c * 10000) / 100),
+            Math.round(mctx.currentContrib * 10000) / 100,
+        ],
+    };
+}
+// ─── Alert → Signal conversion ──────────────────────────────────────────────
+/**
+ * Converts a classified alert candidate into the canonical {@link Signal} shape.
+ *
+ * Handles DEX-qualified asset naming (`xyz:TOKEN`), direction normalisation
+ * (the SM data uses lowercase strings, signals require "LONG" | "SHORT"),
+ * and packs all detection metadata into the signal's `factors` and `meta`
+ * fields for downstream transparency.
+ *
+ * @returns A signal, or `null` if classification returned null (defensive).
+ */
+function alertToSignal(alert, cfg, ctx) {
+    const classification = classifySignal(alert, cfg);
+    if (classification === null)
+        return null;
+    return {
+        address: ctx.address,
+        scannerId: ctx.scannerId,
+        signalType: classification.signalType,
+        asset: alert.dex === "xyz" ? `xyz:${alert.token}` : alert.token,
+        direction: alert.direction.toUpperCase() === "SHORT" ? "SHORT" : "LONG",
+        score: clamp01(classification.conviction),
+        timestamp: ctx.timestamp,
+        factors: {
+            rank_jump: alert.rankJumpThisScan > 0,
+            new_entry: alert.reasons.some((r) => r.startsWith("NEW_ENTRY")),
+            contrib_explosion: alert.isContribExplosion,
+            deep_climber: alert.isDeepClimber,
+            immediate_mover: alert.isImmediate,
+            first_jump: alert.isFirstJump,
+            erratic: classification.erratic,
+            low_velocity: classification.lowVelocity,
+        },
+        meta: {
+            signalPriority: classification.priority,
+            rank: alert.currentRank,
+            prevRank: alert.rankHistoryWindow.length > 1
+                ? alert.rankHistoryWindow[alert.rankHistoryWindow.length - 2]
+                : null,
+            jump: alert.rankJumpThisScan,
+            dex: alert.dex ?? null,
+            direction: alert.direction,
+            topTradersGain: alert.currentContrib,
+            priceChg4h: alert.priceChg4h,
+            traderCount: alert.traderCount,
+            contribVelocity: Math.round(alert.contribVelocity * 10000) / 10000,
+            rankHistory: alert.rankHistoryWindow,
+            contribHistory: alert.contribHistoryWindow,
+            reasons: alert.reasons,
+            marketRegime: ctx.marketRegime ?? "UNKNOWN",
+        },
+    };
+}
+/**
+ * Sorts signals in-place by descending urgency.
+ *
+ * Primary key: signal priority (1 = most urgent).
+ * Secondary key: absolute contribution velocity (higher = more active).
+ * Tertiary key: number of detection reasons (more reasons = richer signal).
+ *
+ * This ordering ensures the action layer processes the most time-sensitive
+ * signals first when iterating through the FIFO queue.
+ */
+function sortByPriority(signals) {
+    signals.sort((a, b) => {
+        const pa = a.meta.signalPriority ?? 99;
+        const pb = b.meta.signalPriority ?? 99;
+        if (pa !== pb)
+            return pa - pb;
+        const va = Math.abs(a.meta.contribVelocity ?? 0);
+        const vb = Math.abs(b.meta.contribVelocity ?? 0);
+        if (va !== vb)
+            return vb - va;
+        return (b.meta.reasons ?? []).length - (a.meta.reasons ?? []).length;
+    });
+}
+/**
+ * Builds the scan result summary with per-signal-type counts.
+ *
+ * Exposed in the scan result's `summary` field for observability dashboards
+ * and health checks — operators can see at a glance which signal categories
+ * fired in a given scan without parsing individual signals.
+ */
+function buildSummary(signals, rankedCount, scans) {
+    return {
+        rankedCount,
+        scans,
+        signalBreakdown: {
+            firstJumps: signals.filter((s) => s.signalType === "FIRST_JUMP").length,
+            contribExplosions: signals.filter((s) => s.signalType === "CONTRIB_EXPLOSION").length,
+            immediateMovers: signals.filter((s) => s.signalType === "IMMEDIATE_MOVER").length,
+            newEntryDeep: signals.filter((s) => s.signalType === "NEW_ENTRY_DEEP").length,
+            deepClimbers: signals.filter((s) => s.signalType === "DEEP_CLIMBER").length,
+        },
+    };
+}
+// ─── Utility ────────────────────────────────────────────────────────────────
+/**
+ * Fills in default values for optional config fields.
+ *
+ * v4 added many config knobs that are optional in the TypeBox schema (so
+ * existing YAML configs don't break). This function merges them with
+ * defaults so detection rules always see a fully populated config.
+ */
+function resolveConfig(config) {
+    return {
+        ...defaultConfig,
+        ...Object.fromEntries(Object.entries(config).filter(([, v]) => v !== undefined)),
+    };
+}
+/**
+ * Produces a unique key for a market, incorporating the DEX when present.
+ *
+ * The same token symbol can appear on multiple DEXes (e.g. "SOL" on main
+ * vs. "SOL" on xyz). Keying history by `dex:token` prevents cross-DEX
+ * rank comparisons that would produce spurious signals.
+ */
+function tokenKey(market) {
+    return market.dex ? `${market.dex}:${market.token}` : market.token;
+}
+/**
+ * Filters out malformed market rows that would cause NaN in scoring.
+ *
+ * The SM data provider may return rows with missing or non-numeric fields
+ * (e.g. newly listed tokens with incomplete data). These are silently
+ * dropped to avoid polluting rank calculations.
+ */
+function normalizeMarkets(markets) {
+    return markets.filter((m) => typeof m.token === "string" && m.token.length > 0 &&
+        Number.isFinite(m.pctOfTopTradersGain) && Number.isFinite(m.traderCount));
+}
+/** Returns the last element of an array, or `null` if empty. */
+function lastOf(arr) {
+    return arr.length > 0 ? arr[arr.length - 1] : null;
+}
+// ─── Scanner factory ────────────────────────────────────────────────────────
+/**
+ * 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 function emergingMoversScanner() {
+    return createScanner({
+        id: "emerging-movers",
+        signalType: "EMERGING_MOVER",
+        description: "Detects top-trader rank movers with persistent local history (v4: multi-signal).",
+        intervalSeconds: 180,
+        retention: RetentionPolicy.ROLLING_WINDOW,
+        retentionMaxRuns: 300,
+        persistence: PersistencePolicy.ACTIONABLE_ONLY,
+        inputs: [
+            providerInput.smData(),
+            providerInput.instruments(),
+            consumeSharedArtifact(marketRegimeArtifact, {
+                required: false,
+                maxAgeMs: 7_200_000,
+            }),
+        ],
+        configSchema: emergingMoversConfigSchema,
+        defaultConfig,
+        stateSchema: emergingMoversStateSchema,
+        defaultState,
+        hooks: {
+            isActionable: (signal, ctx) => {
+                const cfg = resolveConfig(ctx.config);
+                // 2A: Regime-aware score gating (disabled by default)
+                if (cfg.regimeScoreGating) {
+                    const regime = ctx.inputs.artifacts?.["market-regime"];
+                    const threshold = regime?.regime === MarketRegime.NEUTRAL
+                        ? cfg.regimeScoreNeutral
+                        : cfg.regimeScoreDefault;
+                    if (signal.score < threshold)
+                        return false;
+                }
+                // 2D: Leverage floor (disabled when minLeverage = 0)
+                if (cfg.minLeverage > 0 && ctx.inputs.instruments) {
+                    const instrument = ctx.inputs.instruments.find((i) => i.name === signal.asset);
+                    if (instrument && instrument.maxLeverage < cfg.minLeverage) {
+                        return false;
+                    }
+                }
+                return true;
+            },
+        },
+        scan: async (ctx) => {
+            const now = ctx.now();
+            const state = ctx.state;
+            const cfg = resolveConfig(ctx.config);
+            const ranked = normalizeMarkets(ctx.inputs.smData ?? [])
+                .sort((a, b) => b.pctOfTopTradersGain - a.pctOfTopTradersGain)
+                .slice(0, cfg.topN);
+            const prevTopTokenSet = new Set(state.prevTopTokens);
+            const nextState = {
+                scans: state.scans + 1,
+                rankHistory: { ...state.rankHistory },
+                contribHistory: { ...state.contribHistory },
+                prevTopTokens: ranked.map(tokenKey),
+            };
+            // Analyze each ranked market and collect alerts
+            const alerts = [];
+            for (let i = 0; i < ranked.length; i++) {
+                const market = ranked[i];
+                const tk = tokenKey(market);
+                const prevRankHistory = state.rankHistory[tk] ?? [];
+                const prevContribHistory = state.contribHistory[tk] ?? [];
+                const rank = i + 1;
+                // Update state histories
+                nextState.rankHistory[tk] = [...prevRankHistory, rank].slice(-cfg.historyLimit);
+                nextState.contribHistory[tk] = [...prevContribHistory, market.pctOfTopTradersGain].slice(-cfg.historyLimit);
+                if (nextState.scans < cfg.minScansBeforeSignals)
+                    continue;
+                const mctx = {
+                    market,
+                    tk,
+                    rank,
+                    currentContrib: market.pctOfTopTradersGain,
+                    prevRank: lastOf(prevRankHistory),
+                    prevContrib: lastOf(prevContribHistory),
+                    prevRankHistory,
+                    prevContribHistory,
+                };
+                const alert = analyzeMarket(mctx, cfg, prevTopTokenSet);
+                if (alert)
+                    alerts.push(alert);
+            }
+            // Convert alerts to signals, sort, persist
+            const regimeArtifact = ctx.inputs.artifacts?.["market-regime"];
+            const marketRegime = regimeArtifact?.regime;
+            const signals = alerts
+                .map((a) => alertToSignal(a, cfg, { address: ctx.address, scannerId: ctx.scannerId, timestamp: now, marketRegime }))
+                .filter((s) => s !== null);
+            sortByPriority(signals);
+            await ctx.setState(nextState);
+            return {
+                timestamp: now,
+                scannedCount: ranked.length,
+                signals,
+                summary: buildSummary(signals, ranked.length, nextState.scans),
+            };
+        },
+    });
+}
+//# sourceMappingURL=emerging-movers.js.map