@vorionsys/atsf-core 0.2.3 → 0.3.0

package/dist/paramesphere/cognitive-envelope.js

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Vorion LLC
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_ENVELOPE_CONFIG = {
+    k: 3.0,
+    breachThreshold: 3,
+    dimensions: 6,
+    measurementIntervalMs: 300_000, // 5 minutes
+    maxBreachCounter: 100,
+};
+// ---------------------------------------------------------------------------
+// CognitiveEnvelope
+// ---------------------------------------------------------------------------
+export class CognitiveEnvelope {
+    config;
+    // Baseline statistics
+    mu = [];
+    sigma = [];
+    lowerBounds = [];
+    upperBounds = [];
+    baselined = false;
+    // Breach tracking
+    breachCounter = 0;
+    lastCheckMs = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_ENVELOPE_CONFIG, ...config };
+        if (this.config.dimensions < 1) {
+            throw new Error('dimensions must be >= 1');
+        }
+        if (this.config.k <= 0) {
+            throw new Error('k must be > 0');
+        }
+        if (this.config.breachThreshold < 1) {
+            throw new Error('breachThreshold must be >= 1');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Establish the envelope baseline from an observation period.
+     *
+     * @param measurements  Array of observation vectors. Each inner array has
+     *                      length equal to `config.dimensions`. At least 2
+     *                      observations are required to compute sigma.
+     */
+    baselineFromObservations(measurements) {
+        const D = this.config.dimensions;
+        if (measurements.length < 2) {
+            throw new Error('At least 2 observations required to establish a baseline');
+        }
+        for (const m of measurements) {
+            if (m.length !== D) {
+                throw new Error(`Measurement vector length ${m.length} does not match configured dimensions ${D}`);
+            }
+        }
+        const N = measurements.length;
+        this.mu = new Array(D).fill(0);
+        this.sigma = new Array(D).fill(0);
+        // Compute mean
+        for (const m of measurements) {
+            for (let d = 0; d < D; d++) {
+                this.mu[d] += m[d];
+            }
+        }
+        for (let d = 0; d < D; d++) {
+            this.mu[d] /= N;
+        }
+        // Compute sample standard deviation
+        for (const m of measurements) {
+            for (let d = 0; d < D; d++) {
+                const diff = m[d] - this.mu[d];
+                this.sigma[d] += diff * diff;
+            }
+        }
+        for (let d = 0; d < D; d++) {
+            this.sigma[d] = Math.sqrt(this.sigma[d] / (N - 1));
+            // Guard against zero variance: use a tiny epsilon
+            if (this.sigma[d] < 1e-15) {
+                this.sigma[d] = 1e-15;
+            }
+        }
+        // Compute bounds
+        this.lowerBounds = new Array(D);
+        this.upperBounds = new Array(D);
+        for (let d = 0; d < D; d++) {
+            this.lowerBounds[d] = this.mu[d] - this.config.k * this.sigma[d];
+            this.upperBounds[d] = this.mu[d] + this.config.k * this.sigma[d];
+        }
+        this.baselined = true;
+        this.breachCounter = 0;
+    }
+    /**
+     * Check a current characteristic vector against the envelope.
+     *
+     * Breach counter increments on any-dimension breach and decrements
+     * (towards 0) on a clean check. Trust multiplier is determined by
+     * the counter value relative to the threshold.
+     */
+    checkBreach(currentChars) {
+        if (!this.baselined) {
+            throw new Error('Envelope not baselined — call baselineFromObservations() first');
+        }
+        const D = this.config.dimensions;
+        if (currentChars.length !== D) {
+            throw new Error(`Characteristic vector length ${currentChars.length} does not match dimensions ${D}`);
+        }
+        // Rate-limit checks
+        const now = Date.now();
+        if (this.lastCheckMs > 0 && now - this.lastCheckMs < this.config.measurementIntervalMs) {
+            // Return a clean result without modifying state
+            return {
+                breached: this.breachCounter >= this.config.breachThreshold,
+                trustMultiplier: this.currentTrustMultiplier(),
+                breachCounter: this.breachCounter,
+                dimensionBreaches: new Array(D).fill(false),
+                maxDeviation: 0,
+            };
+        }
+        this.lastCheckMs = now;
+        // Per-dimension breach check
+        const dimensionBreaches = new Array(D);
+        let anyBreach = false;
+        let maxDeviation = 0;
+        for (let d = 0; d < D; d++) {
+            const deviation = Math.abs(currentChars[d] - this.mu[d]) / this.sigma[d];
+            if (deviation > maxDeviation)
+                maxDeviation = deviation;
+            const outside = currentChars[d] < this.lowerBounds[d] || currentChars[d] > this.upperBounds[d];
+            dimensionBreaches[d] = outside;
+            if (outside)
+                anyBreach = true;
+        }
+        // Update breach counter
+        if (anyBreach) {
+            this.breachCounter++;
+            // Clamp to maxBreachCounter to cap recovery cost from sustained attacks
+            if (this.breachCounter > this.config.maxBreachCounter) {
+                this.breachCounter = this.config.maxBreachCounter;
+            }
+        }
+        else {
+            // Decrement towards zero on clean check
+            if (this.breachCounter > 0)
+                this.breachCounter--;
+        }
+        const breached = this.breachCounter >= this.config.breachThreshold;
+        return {
+            breached,
+            trustMultiplier: this.currentTrustMultiplier(),
+            breachCounter: this.breachCounter,
+            dimensionBreaches,
+            maxDeviation,
+        };
+    }
+    /**
+     * Get the current internal state of the envelope.
+     */
+    getState() {
+        return {
+            baselined: this.baselined,
+            mu: [...this.mu],
+            sigma: [...this.sigma],
+            breachCounter: this.breachCounter,
+            lastCheckMs: this.lastCheckMs,
+            lowerBounds: [...this.lowerBounds],
+            upperBounds: [...this.upperBounds],
+        };
+    }
+    /**
+     * Reset the breach counter to zero without clearing the baseline.
+     */
+    reset() {
+        this.breachCounter = 0;
+        this.lastCheckMs = 0;
+    }
+    /**
+     * Fully clear the baseline and all state.
+     */
+    clearBaseline() {
+        this.mu = [];
+        this.sigma = [];
+        this.lowerBounds = [];
+        this.upperBounds = [];
+        this.baselined = false;
+        this.breachCounter = 0;
+        this.lastCheckMs = 0;
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    /**
+     * Compute the trust multiplier based on breach counter.
+     *
+     * - counter == 0              → 1.0 (normal)
+     * - 0 < counter < threshold   → 0.9 (approaching breach)
+     * - counter >= threshold       → 0.7 (full breach)
+     */
+    currentTrustMultiplier() {
+        if (this.breachCounter <= 0)
+            return 1.0;
+        if (this.breachCounter < this.config.breachThreshold)
+            return 0.9;
+        return 0.7;
+    }
+}
+//# sourceMappingURL=cognitive-envelope.js.map

package/dist/paramesphere/cognitive-envelope.js.map

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

package/dist/paramesphere/envelope-integration.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Envelope Integration — Connects CognitiveEnvelope to TrustEngine.
+ *
+ * Thin adapter that periodically runs the envelope's `checkBreach()` against
+ * a caller-supplied dimension vector and, when a breach is detected, records
+ * a trust signal via `TrustEngine.recordSignal()`.
+ *
+ * The monitor runs on an interval (default 60 s) and is fully decoupled:
+ * the envelope decides whether there is a breach, and this module just
+ * translates that into trust signals. Breach history is kept for audit.
+ *
+ * @packageDocumentation
+ */
+import type { CognitiveEnvelope } from './cognitive-envelope.js';
+import type { BreachResult } from './types.js';
+import type { TrustEngine } from '../trust-engine/index.js';
+/** Configuration for the envelope-to-engine integration. */
+export interface EnvelopeIntegrationConfig {
+    /** Interval between automatic breach checks in milliseconds. Default: 60 000 (1 min). */
+    checkIntervalMs?: number;
+    /** Entity ID whose trust score will receive breach signals. */
+    entityId: string;
+    /** Function that returns the current characteristic vector (6 dimensions). */
+    getDimensions: () => number[];
+}
+/** A recorded breach event kept for audit. */
+export interface BreachHistoryEntry {
+    timestamp: string;
+    result: BreachResult;
+    signalId: string;
+}
+/** Handle returned by {@link connectEnvelopeToTrustEngine}. */
+export interface EnvelopeMonitor {
+    /** Stop the interval and release resources. */
+    stop(): void;
+    /** Read-only copy of breach history. */
+    getBreachHistory(): BreachHistoryEntry[];
+    /** Number of checks executed so far. */
+    getCheckCount(): number;
+    /** Whether the monitor interval is currently running. */
+    isRunning(): boolean;
+}
+/**
+ * Wire a CognitiveEnvelope's breach detection to a TrustEngine.
+ *
+ * Starts an interval that calls `envelope.checkBreach(getDimensions())`.
+ * When a breach is detected, a trust signal is recorded with the
+ * `trustMultiplier` as the signal value (0.7 for full breach, 0.9 for
+ * approaching) and metadata describing the breach.
+ *
+ * @returns An {@link EnvelopeMonitor} handle — call `.stop()` to tear down.
+ */
+export declare function connectEnvelopeToTrustEngine(envelope: CognitiveEnvelope, engine: TrustEngine, config: EnvelopeIntegrationConfig): EnvelopeMonitor;
+/**
+ * Stop an EnvelopeMonitor and release its interval.
+ *
+ * Convenience wrapper — equivalent to `monitor.stop()`.
+ */
+export declare function disconnectEnvelope(monitor: EnvelopeMonitor): void;
+//# sourceMappingURL=envelope-integration.d.ts.map

package/dist/paramesphere/envelope-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-integration.d.ts","sourceRoot":"","sources":["../../src/paramesphere/envelope-integration.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM5D,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,MAAM,EAAE,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,IAAI,IAAI,IAAI,CAAC;IACb,wCAAwC;IACxC,gBAAgB,IAAI,kBAAkB,EAAE,CAAC;IACzC,wCAAwC;IACxC,aAAa,IAAI,MAAM,CAAC;IACxB,yDAAyD;IACzD,SAAS,IAAI,OAAO,CAAC;CACtB;AAcD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,yBAAyB,GAChC,eAAe,CA0EjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAEjE"}

package/dist/paramesphere/envelope-integration.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Vorion LLC
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_CHECK_INTERVAL_MS = 60_000;
+const SIGNAL_SOURCE = 'cognitive-envelope';
+const SIGNAL_TYPE_BREACH = 'ENVELOPE_BREACH';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Wire a CognitiveEnvelope's breach detection to a TrustEngine.
+ *
+ * Starts an interval that calls `envelope.checkBreach(getDimensions())`.
+ * When a breach is detected, a trust signal is recorded with the
+ * `trustMultiplier` as the signal value (0.7 for full breach, 0.9 for
+ * approaching) and metadata describing the breach.
+ *
+ * @returns An {@link EnvelopeMonitor} handle — call `.stop()` to tear down.
+ */
+export function connectEnvelopeToTrustEngine(envelope, engine, config) {
+    if (!config.entityId) {
+        throw new Error('entityId is required');
+    }
+    if (typeof config.getDimensions !== 'function') {
+        throw new Error('getDimensions must be a function');
+    }
+    const intervalMs = config.checkIntervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+    if (intervalMs <= 0) {
+        throw new Error('checkIntervalMs must be > 0');
+    }
+    const breachHistory = [];
+    let checkCount = 0;
+    let running = true;
+    // The core check function — also exported on the monitor for manual invocation in tests.
+    function runCheck() {
+        const dims = config.getDimensions();
+        const result = envelope.checkBreach(dims);
+        checkCount++;
+        if (result.breached) {
+            const signalId = `${SIGNAL_SOURCE}-${config.entityId}-${Date.now()}`;
+            const signal = {
+                id: signalId,
+                entityId: config.entityId,
+                type: SIGNAL_TYPE_BREACH,
+                value: result.trustMultiplier,
+                source: SIGNAL_SOURCE,
+                timestamp: new Date().toISOString(),
+                metadata: {
+                    breachCounter: result.breachCounter,
+                    maxDeviation: result.maxDeviation,
+                    dimensionBreaches: result.dimensionBreaches,
+                    trustMultiplier: result.trustMultiplier,
+                },
+            };
+            breachHistory.push({
+                timestamp: signal.timestamp,
+                result,
+                signalId,
+            });
+            void engine.recordSignal(signal);
+        }
+    }
+    const timer = setInterval(runCheck, intervalMs);
+    const monitor = {
+        stop() {
+            if (!running)
+                return;
+            clearInterval(timer);
+            running = false;
+        },
+        getBreachHistory() {
+            return [...breachHistory];
+        },
+        getCheckCount() {
+            return checkCount;
+        },
+        isRunning() {
+            return running;
+        },
+    };
+    return monitor;
+}
+/**
+ * Stop an EnvelopeMonitor and release its interval.
+ *
+ * Convenience wrapper — equivalent to `monitor.stop()`.
+ */
+export function disconnectEnvelope(monitor) {
+    monitor.stop();
+}
+//# sourceMappingURL=envelope-integration.js.map

package/dist/paramesphere/envelope-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-integration.js","sourceRoot":"","sources":["../../src/paramesphere/envelope-integration.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAqDjC,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,yBAAyB,GAAG,MAAM,CAAC;AACzC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAC3C,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAE7C,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAA2B,EAC3B,MAAmB,EACnB,MAAiC;IAEjC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,eAAe,IAAI,yBAAyB,CAAC;IACvE,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,aAAa,GAAyB,EAAE,CAAC;IAC/C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,IAAI,CAAC;IAEnB,yFAAyF;IACzF,SAAS,QAAQ;QACf,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,UAAU,EAAE,CAAC;QAEb,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,GAAG,aAAa,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAErE,MAAM,MAAM,GAAG;gBACb,EAAE,EAAE,QAAQ;gBACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,IAAI,EAAE,kBAAkB;gBACxB,KAAK,EAAE,MAAM,CAAC,eAAe;gBAC7B,MAAM,EAAE,aAAa;gBACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,QAAQ,EAAE;oBACR,aAAa,EAAE,MAAM,CAAC,aAAa;oBACnC,YAAY,EAAE,MAAM,CAAC,YAAY;oBACjC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;oBAC3C,eAAe,EAAE,MAAM,CAAC,eAAe;iBACxC;aACF,CAAC;YAEF,aAAa,CAAC,IAAI,CAAC;gBACjB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,MAAM;gBACN,QAAQ;aACT,CAAC,CAAC;YAEH,KAAK,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAEhD,MAAM,OAAO,GAAoB;QAC/B,IAAI;YACF,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,aAAa,CAAC,KAAK,CAAC,CAAC;YACrB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;QAED,gBAAgB;YACd,OAAO,CAAC,GAAG,aAAa,CAAC,CAAC;QAC5B,CAAC;QAED,aAAa;YACX,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,SAAS;YACP,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAwB;IACzD,OAAO,CAAC,IAAI,EAAE,CAAC;AACjB,CAAC"}

package/dist/paramesphere/fingerprint-monitor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * FingerprintMonitor — Scheduled fingerprinting with automatic alerting.
+ *
+ * Runs fingerprint checks on a configurable interval, emits callbacks on
+ * drift detection, and produces signal-ready objects when tampering is
+ * detected.  Deliberately decoupled from the trust engine — the monitor
+ * detects and reports, it never directly modifies trust scores.
+ *
+ * Key behaviours:
+ * - First check for a given entity establishes its baseline fingerprint.
+ * - Subsequent checks compare against that baseline via
+ *   `ParameSphereEngine.checkDrift()`.
+ * - Drift exceeding `driftThreshold` triggers the `onDriftDetected` callback.
+ * - Drift exceeding `2 × driftThreshold` is classified as *tampering* and
+ *   triggers the `onTamperingDetected` callback.
+ * - When `emitTrustSignal` is true, `MonitorCheckResult` includes a
+ *   signal-ready payload (`trustSignal`) that callers can forward to a
+ *   trust engine without introducing a direct dependency.
+ *
+ * @packageDocumentation
+ */
+import type { ParameSphereFingerprint, DriftResult } from './types.js';
+import type { ParameSphereEngine } from './paramesphere-engine.js';
+/** Configuration for the FingerprintMonitor. */
+export interface FingerprintMonitorConfig {
+    /** ParameSphere engine instance used to compute and compare fingerprints. */
+    engine: ParameSphereEngine;
+    /** Interval between scheduled fingerprint checks, in milliseconds (default: 300 000 = 5 min). */
+    checkIntervalMs?: number;
+    /** Cosine-distance threshold that constitutes drift (default: 0.05). */
+    driftThreshold?: number;
+    /** Called whenever drift is detected. */
+    onDriftDetected?: (entityId: string, result: DriftResult) => void;
+    /** Called each time a fingerprint is successfully computed. */
+    onFingerprintTaken?: (entityId: string, fingerprint: ParameSphereFingerprint) => void;
+    /** Called when drift exceeds 2× threshold (severe — likely tampering). */
+    onTamperingDetected?: (entityId: string, result: DriftResult) => void;
+    /**
+     * When true, `MonitorCheckResult.trustSignal` is populated with a
+     * signal-ready object that consumers can forward to a trust engine.
+     * Default: true.
+     */
+    emitTrustSignal?: boolean;
+}
+/** Result of a single monitor check cycle. */
+export interface MonitorCheckResult {
+    entityId: string;
+    fingerprint: ParameSphereFingerprint;
+    driftDetected: boolean;
+    /** Drift exceeds 2× threshold — severe / likely tampering. */
+    tamperingDetected: boolean;
+    /** Measured cosine distance from baseline (0 on first check). */
+    driftDistance: number;
+    checkedAt: Date;
+    /**
+     * Signal-ready object suitable for forwarding to a trust engine.
+     * Present only when `emitTrustSignal` is enabled AND drift or
+     * tampering was detected.
+     */
+    trustSignal?: TrustSignalPayload;
+}
+/** Lightweight trust signal payload — decoupled from the trust engine's own type. */
+export interface TrustSignalPayload {
+    entityId: string;
+    type: string;
+    value: number;
+    source: string;
+    timestamp: string;
+    metadata: Record<string, unknown>;
+}
+/** Per-entity monitoring status. */
+export interface MonitorStatus {
+    entityId: string;
+    lastCheck: Date | null;
+    checksCompleted: number;
+    driftsDetected: number;
+    tamperingsDetected: number;
+    status: 'monitoring' | 'stopped';
+}
+export declare class FingerprintMonitor {
+    private readonly engine;
+    private readonly checkIntervalMs;
+    private readonly driftThreshold;
+    private readonly emitTrustSignal;
+    private onDriftDetected?;
+    private onFingerprintTaken?;
+    private onTamperingDetected?;
+    private readonly entities;
+    constructor(config: FingerprintMonitorConfig);
+    /**
+     * Start monitoring an entity's model weights.
+     *
+     * The first scheduled check establishes the baseline fingerprint.
+     * Subsequent checks compare against that baseline.
+     *
+     * @param entityId    Unique identifier for the monitored entity / model.
+     * @param getWeights  Callback that returns the current weight matrices.
+     */
+    startMonitoring(entityId: string, getWeights: () => Float32Array[]): void;
+    /**
+     * Stop monitoring an entity.  Clears the interval and marks status
+     * as `stopped`.  The entity remains in the map so stats are queryable.
+     */
+    stopMonitoring(entityId: string): void;
+    /**
+     * Manually trigger a fingerprint check outside the scheduled interval.
+     */
+    checkNow(entityId: string): Promise<MonitorCheckResult>;
+    /**
+     * Get monitoring status for an entity.
+     */
+    getStatus(entityId: string): MonitorStatus | undefined;
+    /**
+     * List all entity IDs currently registered (monitoring or stopped).
+     */
+    getMonitoredEntities(): string[];
+    /**
+     * Replace the drift-detected callback.  Allows integration layers to
+     * wire callbacks after construction without subclassing.
+     */
+    setOnDriftDetected(cb: ((entityId: string, result: DriftResult) => void) | undefined): void;
+    /**
+     * Replace the tampering-detected callback.
+     */
+    setOnTamperingDetected(cb: ((entityId: string, result: DriftResult) => void) | undefined): void;
+    /**
+     * Replace the fingerprint-taken callback.
+     */
+    setOnFingerprintTaken(cb: ((entityId: string, fingerprint: ParameSphereFingerprint) => void) | undefined): void;
+    /**
+     * Stop all monitored entities and clear all state.
+     */
+    shutdown(): void;
+    private runCheck;
+}
+//# sourceMappingURL=fingerprint-monitor.d.ts.map

package/dist/paramesphere/fingerprint-monitor.d.ts.map

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