@senpi/runtime 1.0.95-dev.20260408174401

package/dist/scanners/engine/input-resolver.js

@@ -0,0 +1,216 @@
+import { isConsumedArtifactBinding, isProviderInputDescriptor, } from "../input-descriptors.js";
+import { inferBuiltInSourceScannerId } from "../context-source-mapping.js";
+import { SkipScan } from "../protocol/hooks.js";
+/**
+ * Builds one scan-input payload from provider needs plus scanner context dependencies.
+ * Shared market intelligence is loaded from retained scanner context; market data is
+ * loaded from providers.
+ */
+export async function resolveScanInputs(options) {
+    const { address, definition, providers, sharedArtifactStore, availableScanners, } = options;
+    const now = options.now ?? Date.now;
+    const providerInputs = definition.inputs.filter(isProviderInputDescriptor);
+    const consumedArtifacts = definition.inputs.filter(isConsumedArtifactBinding);
+    const resolvedInputs = {
+        artifacts: {},
+    };
+    let instruments;
+    const candlesInput = findProviderInput(providerInputs, "candles");
+    const requiresInstruments = candlesInput !== undefined || hasProviderInput(providerInputs, "instruments");
+    if (requiresInstruments) {
+        if (!providers.getInstruments) {
+            throw new Error(`Scanner '${definition.id}' requires instruments provider for strategy '${address}'.`);
+        }
+        instruments = await providers.getInstruments(address);
+    }
+    if (hasProviderInput(providerInputs, "instruments")) {
+        resolvedInputs.instruments = instruments ?? [];
+    }
+    const dependencies = await loadConsumedArtifacts({
+        bindings: consumedArtifacts,
+        inputs: resolvedInputs,
+        address,
+        providers,
+        sharedArtifactStore,
+        scannerId: definition.id,
+        definitionDependencies: definition.dependsOn ?? [],
+        availableScanners,
+        now,
+    });
+    if (candlesInput) {
+        if (!providers.getCandles) {
+            throw new Error(`Scanner '${definition.id}' requires candles provider for strategy '${address}'.`);
+        }
+        resolvedInputs.candles = await providers.getCandles(address, instruments ?? [], {
+            scannerId: definition.id,
+            preferredAssets: resolvePreferredAssets(resolvedInputs.artifacts, candlesInput),
+        });
+    }
+    if (hasProviderInput(providerInputs, "smData")) {
+        if (!providers.getSmData) {
+            throw new Error(`Scanner '${definition.id}' requires smData provider for strategy '${address}'.`);
+        }
+        resolvedInputs.smData = await providers.getSmData(address);
+    }
+    if (hasProviderInput(providerInputs, "activePositions")) {
+        if (!providers.getActivePositions) {
+            throw new Error(`Scanner '${definition.id}' requires activePositions provider for strategy '${address}'.`);
+        }
+        resolvedInputs.activePositions = await providers.getActivePositions(address);
+    }
+    if (hasProviderInput(providerInputs, "clearingHouseState")) {
+        if (!providers.getClearingHouseState) {
+            throw new Error(`Scanner '${definition.id}' requires clearingHouseState provider for strategy '${address}'.`);
+        }
+        resolvedInputs.clearingHouseState = await providers.getClearingHouseState(address) ?? undefined;
+    }
+    if (hasProviderInput(providerInputs, "dslStates") && providers.getDslStatesForStrategy) {
+        resolvedInputs.dslStates = await providers.getDslStatesForStrategy(address);
+    }
+    return {
+        inputs: resolvedInputs,
+        dependencies,
+    };
+}
+/** Returns true when one provider-backed input kind appears anywhere in the descriptor list. */
+function hasProviderInput(inputs, kind) {
+    return inputs.some((input) => input.kind === kind);
+}
+/** Returns the first provider-backed input descriptor of the requested kind, if present. */
+function findProviderInput(inputs, kind) {
+    return inputs.find((input) => input.kind === kind);
+}
+async function loadConsumedArtifacts(options) {
+    const dependencies = [];
+    for (const binding of options.bindings) {
+        const resolved = await resolveConsumedArtifact(binding, options);
+        if (!resolved) {
+            continue;
+        }
+        assignArtifactInput(options.inputs, binding.contract.key, resolved.value);
+        if (resolved.dependency) {
+            dependencies.push(resolved.dependency);
+        }
+    }
+    return dependencies;
+}
+async function resolveConsumedArtifact(binding, options) {
+    const policy = resolveEffectivePolicy(binding, options.definitionDependencies, options.availableScanners);
+    const providerValue = await loadArtifactFromProvider(binding, options.address, options.providers);
+    if (providerValue !== undefined) {
+        return { value: providerValue };
+    }
+    if (!policy.sourceScannerId) {
+        return handleMissingArtifact(binding, options, policy);
+    }
+    const envelope = await options.sharedArtifactStore.loadEnvelopeByScanner(options.address, policy.sourceScannerId, { contract: binding.contract });
+    if (!envelope) {
+        return handleMissingArtifact(binding, options, policy);
+    }
+    const stale = typeof policy.maxAgeMs === "number"
+        ? options.now() - envelope.updatedAt > policy.maxAgeMs
+        : false;
+    if (stale && policy.onStale === "fail") {
+        throw new Error(`Scanner '${options.scannerId}' requires fresh context '${binding.contract.key}' from scanner '${policy.sourceScannerId}' for strategy '${options.address}', but the latest committed context is stale.`);
+    }
+    if (stale && policy.onStale === "skip") {
+        throw new SkipScan(`Scanner '${options.scannerId}' skipped because context '${binding.contract.key}' from scanner '${policy.sourceScannerId}' is stale for strategy '${options.address}'.`);
+    }
+    return {
+        value: envelope.data,
+        dependency: {
+            scanner: policy.sourceScannerId,
+            contextKey: binding.contract.key,
+            updatedAt: envelope.updatedAt,
+            maxAgeMs: policy.maxAgeMs,
+            stale,
+            onMissing: policy.onMissing,
+            onStale: policy.onStale,
+            value: envelope.data,
+        },
+    };
+}
+function resolveEffectivePolicy(binding, dependencies, availableScanners) {
+    const wiredDependency = dependencies.find((dependency) => {
+        const producedContract = getProducedContract(availableScanners.get(dependency.scanner));
+        return producedContract?.key === binding.contract.key;
+    });
+    const required = wiredDependency?.required ?? binding.required ?? false;
+    const sourceScannerId = wiredDependency?.scanner ?? inferSourceScannerId(binding.contract.key, availableScanners);
+    return {
+        sourceScannerId,
+        required,
+        maxAgeMs: wiredDependency?.maxAgeMs ?? binding.maxAgeMs,
+        onMissing: wiredDependency?.onMissing ?? binding.onMissing ?? (required ? "fail" : "degrade"),
+        onStale: wiredDependency?.onStale ?? binding.onStale ?? (required ? "fail" : "degrade"),
+    };
+}
+function inferSourceScannerId(contractKey, availableScanners) {
+    for (const [scannerId, definition] of availableScanners) {
+        if (getProducedContract(definition)?.key === contractKey) {
+            return scannerId;
+        }
+    }
+    return inferBuiltInSourceScannerId(contractKey);
+}
+function getProducedContract(definition) {
+    return definition?.artifacts?.produces?.[0];
+}
+function handleMissingArtifact(binding, options, policy) {
+    if (policy.onMissing === "fail") {
+        throw new Error(`Scanner '${options.scannerId}' requires context '${binding.contract.key}' for strategy '${options.address}', but no committed source scanner context is available.`);
+    }
+    if (policy.onMissing === "skip") {
+        throw new SkipScan(`Scanner '${options.scannerId}' skipped because context '${binding.contract.key}' is missing for strategy '${options.address}'.`);
+    }
+    return undefined;
+}
+/** Loads a retained-context value from an optional provider-backed equivalent, when configured. */
+async function loadArtifactFromProvider(binding, address, providers) {
+    switch (binding.providerSource) {
+        case "oiHistory":
+            return providers.getOiHistory
+                ? await providers.getOiHistory(address)
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+/** Writes one resolved retained-context value into the mutable scan-input draft. */
+function assignArtifactInput(inputs, key, value) {
+    inputs.artifacts[key] = value;
+}
+/** Extracts candidate asset names from the prescreener artifact for candle fanout hints. */
+function readPreferredAssets(artifact) {
+    if (!artifact) {
+        return undefined;
+    }
+    const assets = artifact.candidates
+        .map((candidate) => {
+        return typeof candidate.name === "string" ? candidate.name : null;
+    })
+        .filter((asset) => asset !== null);
+    return assets.length > 0 ? assets : undefined;
+}
+/**
+ * Resolves candle preferred-asset hints from previously loaded retained context
+ * or from a hardcoded `fixedAssets` list on the descriptor.
+ */
+function resolvePreferredAssets(artifacts, descriptor) {
+    if (descriptor.fixedAssets && descriptor.fixedAssets.length > 0) {
+        return descriptor.fixedAssets;
+    }
+    if (!descriptor.preferredAssetsFrom) {
+        return undefined;
+    }
+    const preferredAssetsKey = typeof descriptor.preferredAssetsFrom === "string"
+        ? descriptor.preferredAssetsFrom
+        : descriptor.preferredAssetsFrom.key;
+    switch (preferredAssetsKey) {
+        case "prescreened":
+            return readPreferredAssets(artifacts.prescreened);
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=input-resolver.js.map

package/dist/scanners/engine/input-resolver.js.map

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

package/dist/scanners/engine/lifecycle.d.ts

@@ -0,0 +1,21 @@
+import type { ScanResult, ScannerId } from "../types.js";
+/** Payload emitted immediately before one scanner execution attempt starts. */
+export interface ScannerRunStart {
+    address: string;
+    scannerId: ScannerId;
+    timestamp: number;
+}
+/** Optional lifecycle callbacks emitted by the engine around each run attempt. */
+export interface ScannerEngineLifecycle {
+    /**
+     * Fires once per execution attempt before any early-exit or scanner work begins.
+     * This callback should be treated as observational and must not throw.
+     */
+    onRunStart?: (event: ScannerRunStart) => void;
+    /**
+     * Fires exactly once per execution attempt with the terminal run result.
+     * This callback receives successful, skipped, disabled, halted, and error results.
+     */
+    onRunResult?: (result: ScanResult) => void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/scanners/engine/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/scanners/engine/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kFAAkF;AAClF,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAE9C;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CAC5C"}

package/dist/scanners/engine/lifecycle.js

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/scanners/events.d.ts

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