@senpi/runtime 1.0.95-dev.20260408174401

package/dist/scanners/runtime-module.js

@@ -0,0 +1,362 @@
+import { EventEmitter } from "node:events";
+import { createLogger } from "../utils/logger.js";
+import { ScannerEngine, } from "./engine/engine.js";
+import { buildScannerComposition } from "../runtime/scanner-composition.js";
+const logger = createLogger("[senpi-core][scanner-module]");
+import { emitTerminalScannerRunEvent, } from "./events.js";
+import { RuntimeStore } from "./store/runtime-store.js";
+import { SharedArtifactStore } from "./store/shared-artifact-store.js";
+import { SignalStore } from "./store/signal-store.js";
+import { prepareScannerInputs, } from "./prepare-scanner-inputs.js";
+/**
+ * Creates a standalone scanner runtime module with strategy-scoped scanner instances.
+ * Registered scanners are supplied as factories so the module never reuses mutable scanner objects.
+ */
+export function createScannerRuntimeModule(options) {
+    return new DefaultScannerRuntimeModule(options);
+}
+class DefaultScannerRuntimeModule {
+    signalStore;
+    runtimeStore;
+    engine;
+    events = new EventEmitter();
+    now;
+    telemetry = new Map();
+    constructor(options) {
+        const now = options.now ?? Date.now;
+        this.now = now;
+        this.signalStore = new SignalStore(options.stateDir);
+        this.runtimeStore = new RuntimeStore(options.stateDir, now);
+        this.engine = new ScannerEngine({
+            now,
+            logger: options.logger ?? logger,
+            providers: options.providers,
+            stores: {
+                runtimeStore: this.runtimeStore,
+                signalStore: this.signalStore,
+                sharedArtifactStore: new SharedArtifactStore(options.stateDir, now),
+            },
+            lifecycle: {
+                onRunStart: (event) => {
+                    this.events.emit("scanner:run:start", event);
+                },
+                onRunResult: (result) => {
+                    emitTerminalScannerRunEvent((eventName, event) => {
+                        this.events.emit(eventName, event);
+                    }, result);
+                },
+            },
+        }, options.composition);
+        registerForStrategy(options.strategy, options.scanners, this.engine);
+        this.wireTelemetryListeners();
+    }
+    async start() {
+        logger.info("scanner module start() entered");
+        await this.engine.start();
+        logger.info("scanner module start() complete");
+    }
+    async stop() {
+        await this.engine.stop();
+    }
+    async runOnce(address, scannerId) {
+        return this.engine.runOnce(address, scannerId);
+    }
+    async runChain(address, scannerId) {
+        return this.engine.runChain(address, scannerId);
+    }
+    async listScanners(address) {
+        return this.engine.list(address);
+    }
+    async enableScanner(address, scannerId) {
+        this.engine.enable(address, scannerId);
+    }
+    async disableScanner(address, scannerId) {
+        this.engine.disable(address, scannerId);
+    }
+    async getScannerConfig(address, scannerId) {
+        return this.engine.getConfig(address, scannerId);
+    }
+    async setScannerConfig(address, scannerId, config) {
+        await this.engine.setConfig(address, scannerId, config);
+    }
+    async getScannerContext(address, scannerId) {
+        return this.engine.getScannerContext(address, scannerId);
+    }
+    async querySignals(filter) {
+        return this.signalStore.readSignals(filter);
+    }
+    async getHealthStatus() {
+        const registrations = this.engine.describeRegistrations();
+        const scannerStates = this.buildScannerHealthRows(registrations);
+        const enabled = registrations.filter((registration) => registration.enabled);
+        const counts = countScannerHealthRows(scannerStates);
+        const componentHealth = deriveWorstHealth(scannerStates
+            .filter((scanner) => scanner.enabled)
+            .map((scanner) => scanner.health), registrations.length);
+        return {
+            component: "scanners",
+            health: componentHealth,
+            updatedAt: new Date(this.now()).toISOString(),
+            summary: buildScannerSummary(componentHealth, registrations.length, enabled.length, counts.degraded, counts.unhealthy),
+            totals: {
+                registered: registrations.length,
+                enabled: enabled.length,
+                inFlight: counts.inFlight,
+                degraded: counts.degraded,
+                unhealthy: counts.unhealthy,
+            },
+            scanners: scannerStates.map(({ enabled: _enabled, inFlight: _inFlight, ...scanner }) => scanner),
+        };
+    }
+    async getSystemState() {
+        const registrations = this.engine.describeRegistrations();
+        const scanners = await Promise.all(registrations.map(async (registration) => {
+            const telemetry = this.ensureTelemetry(registration.address, registration.scannerId);
+            const runtime = await this.runtimeStore.read(registration.address, registration.scannerId);
+            const health = this.deriveScannerHealth(registration, telemetry);
+            return {
+                address: registration.address,
+                scannerId: registration.scannerId,
+                health,
+                enabled: registration.enabled,
+                initialized: registration.initialized,
+                intervalSeconds: registration.intervalSeconds,
+                inFlight: registration.inFlight || telemetry.inFlight,
+                lastRunStartedAt: telemetry.lastRunStartedAt,
+                lastRunFinishedAt: telemetry.lastRunFinishedAt,
+                lastRunStatus: telemetry.lastRunStatus,
+                lastRunReason: telemetry.lastRunReason,
+                lastError: telemetry.lastError,
+                lastErrorAt: telemetry.lastErrorAt,
+                nextRunAt: registration.nextRunAt,
+                runCount: telemetry.runCount,
+                errorCount: telemetry.errorCount,
+                consecutiveErrorCount: telemetry.consecutiveErrorCount,
+                configVersion: runtime?.configVersion ?? null,
+                runtimeUpdatedAt: runtime?.updatedAt ?? null,
+                config: runtime?.config ?? null,
+                state: runtime?.state ?? null,
+            };
+        }));
+        return {
+            component: "scanners",
+            health: deriveWorstHealth(scanners.map((scanner) => scanner.health), registrations.length),
+            updatedAt: new Date(this.now()).toISOString(),
+            state: {
+                totalRegistered: registrations.length,
+                totalEnabled: registrations.filter((registration) => registration.enabled).length,
+                scanners,
+            },
+        };
+    }
+    on(eventName, listener) {
+        this.events.on(eventName, listener);
+    }
+    off(eventName, listener) {
+        this.events.off(eventName, listener);
+    }
+    ensureTelemetry(address, scannerId) {
+        const key = telemetryKey(address, scannerId);
+        let telemetry = this.telemetry.get(key);
+        if (!telemetry) {
+            telemetry = {
+                inFlight: false,
+                lastRunStartedAt: null,
+                lastRunFinishedAt: null,
+                lastRunStatus: null,
+                lastRunReason: null,
+                lastError: null,
+                lastErrorAt: null,
+                runCount: 0,
+                errorCount: 0,
+                consecutiveErrorCount: 0,
+            };
+            this.telemetry.set(key, telemetry);
+        }
+        return telemetry;
+    }
+    wireTelemetryListeners() {
+        this.events.on("scanner:run:start", (event) => {
+            this.recordRunStart(event);
+        });
+        this.events.on("scanner:run:complete", (event) => {
+            this.recordRunComplete(event);
+        });
+        this.events.on("scanner:run:skip", (event) => {
+            this.recordRunSkip(event);
+        });
+        this.events.on("scanner:run:error", (event) => {
+            this.recordRunError(event);
+        });
+    }
+    recordRunStart(event) {
+        const telemetry = this.ensureTelemetry(event.address, event.scannerId);
+        telemetry.inFlight = true;
+        telemetry.lastRunStartedAt = event.timestamp;
+    }
+    recordRunComplete(event) {
+        const telemetry = this.ensureTelemetry(event.address, event.scannerId);
+        telemetry.inFlight = false;
+        telemetry.lastRunFinishedAt = this.now();
+        telemetry.lastRunStatus = event.result.status;
+        telemetry.lastRunReason = event.result.reason ?? null;
+        telemetry.runCount += 1;
+        telemetry.consecutiveErrorCount = 0;
+    }
+    recordRunSkip(event) {
+        const telemetry = this.ensureTelemetry(event.address, event.scannerId);
+        telemetry.inFlight = false;
+        // HALTED = overlap guard: no scan was attempted, so preserve existing error
+        // state. Only genuine completions (ok/heartbeat) should reset error counters.
+        if (event.status === "halted") {
+            return;
+        }
+        telemetry.lastRunFinishedAt = this.now();
+        telemetry.lastRunStatus = event.status;
+        telemetry.lastRunReason = event.reason;
+        telemetry.runCount += 1;
+        telemetry.consecutiveErrorCount = 0;
+    }
+    recordRunError(event) {
+        const telemetry = this.ensureTelemetry(event.address, event.scannerId);
+        telemetry.inFlight = false;
+        telemetry.lastRunFinishedAt = this.now();
+        telemetry.lastRunStatus = "error";
+        telemetry.lastRunReason = String(event.error);
+        telemetry.lastError = String(event.error);
+        telemetry.lastErrorAt = event.timestamp;
+        telemetry.runCount += 1;
+        telemetry.errorCount += 1;
+        telemetry.consecutiveErrorCount += 1;
+    }
+    buildScannerHealthRows(registrations) {
+        return registrations.map((registration) => {
+            const telemetry = this.ensureTelemetry(registration.address, registration.scannerId);
+            return {
+                address: registration.address,
+                scannerId: registration.scannerId,
+                enabled: registration.enabled,
+                inFlight: registration.inFlight || telemetry.inFlight,
+                health: this.deriveScannerHealth(registration, telemetry),
+            };
+        });
+    }
+    deriveScannerHealth(registration, telemetry) {
+        const intervalMs = Math.max(registration.intervalSeconds, 1) * 1000;
+        if (!registration.enabled) {
+            return "disabled";
+        }
+        if (telemetry.inFlight) {
+            if (telemetry.lastRunStartedAt == null) {
+                return "unknown";
+            }
+            const runningMs = this.now() - telemetry.lastRunStartedAt;
+            if (runningMs > intervalMs * 4) {
+                return "unhealthy";
+            }
+            if (runningMs > intervalMs * 2) {
+                return "degraded";
+            }
+            return "healthy";
+        }
+        const now = this.now();
+        const baseline = registration.nextRunAt ??
+            (telemetry.lastRunStartedAt != null
+                ? telemetry.lastRunStartedAt + intervalMs
+                : telemetry.lastRunFinishedAt);
+        if (baseline == null) {
+            return "unknown";
+        }
+        const overdueMs = now - baseline;
+        if (telemetry.lastRunStatus === "error" && telemetry.consecutiveErrorCount >= 2) {
+            return "unhealthy";
+        }
+        if (overdueMs > intervalMs * 4) {
+            return "unhealthy";
+        }
+        if (telemetry.lastRunStatus === "error" || overdueMs > intervalMs * 2) {
+            return "degraded";
+        }
+        return "healthy";
+    }
+}
+function countScannerHealthRows(rows) {
+    let inFlight = 0;
+    let degraded = 0;
+    let unhealthy = 0;
+    for (const row of rows) {
+        if (row.inFlight) {
+            inFlight += 1;
+        }
+        if (row.health === "degraded") {
+            degraded += 1;
+        }
+        if (row.health === "unhealthy") {
+            unhealthy += 1;
+        }
+    }
+    return { inFlight, degraded, unhealthy };
+}
+/**
+ * Builds a scanner composition from scanner factories.
+ *
+ * Convenience wrapper for the programmatic API: instantiates each factory once
+ * to extract definitions, validates the dependency graph, and returns both the
+ * composition and deduplicated factories ready to pass to `createScannerRuntimeModule`.
+ *
+ * Scanner definitions that consume shared artifacts from other scanners must
+ * declare `dependsOn` explicitly — no auto-inference is performed.
+ */
+export function buildCompositionFromScanners(scanners) {
+    const prepared = prepareScannerInputs(scanners);
+    const composition = buildScannerComposition({
+        name: "scanner-runtime-module",
+        strategy: { wallet: "0x0000000000000000000000000000000000000000" },
+        actions: [],
+    }, prepared.map((s) => s.definition));
+    return {
+        composition,
+        scanners: prepared.map((s) => s.factory),
+    };
+}
+/** Registers every scanner factory for the strategy so each gets a fresh instance. */
+function registerForStrategy(strategy, scanners, engine) {
+    for (const scannerFactory of scanners) {
+        engine.register(strategy, scannerFactory());
+    }
+}
+function telemetryKey(address, scannerId) {
+    return `${address}::${scannerId}`;
+}
+function deriveWorstHealth(healths, totalRegistrations) {
+    if (totalRegistrations === 0) {
+        return "disabled";
+    }
+    const active = healths.filter((health) => health !== "disabled");
+    if (active.length === 0) {
+        return "disabled";
+    }
+    if (active.includes("unhealthy")) {
+        return "unhealthy";
+    }
+    if (active.includes("degraded")) {
+        return "degraded";
+    }
+    if (active.includes("unknown")) {
+        return "unknown";
+    }
+    return "healthy";
+}
+function buildScannerSummary(health, total, enabled, degraded, unhealthy) {
+    if (total === 0) {
+        return "No scanners registered.";
+    }
+    if (enabled === 0) {
+        return "All scanners are disabled.";
+    }
+    if (health === "healthy") {
+        return `${enabled}/${total} scanners enabled and healthy.`;
+    }
+    return `${enabled}/${total} scanners enabled (${degraded} degraded, ${unhealthy} unhealthy).`;
+}
+//# sourceMappingURL=runtime-module.js.map

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

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

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

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

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

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

package/dist/scanners/scanner-definition.js

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

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

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

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

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

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

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

package/dist/scanners/schema-utils.js

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

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

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

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

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

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

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

package/dist/scanners/score-utils.js

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

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

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

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

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

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

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