@vorionsys/atsf-core 0.4.1 → 0.4.3

package/dist/enforce/trust-cache.d.ts

@@ -0,0 +1,118 @@
+import type { TrustLevel, TrustScore, ID } from '../common/types.js';
+/**
+ * Cached trust data for a single agent.
+ */
+export interface CachedTrustEntry {
+    trustScore: TrustScore;
+    trustTier: TrustLevel;
+    integrityScore: number;
+    observationTier: TrustLevel;
+    cachedAt: number;
+}
+/**
+ * Configuration for the trust lookup cache.
+ */
+export interface TrustLookupCacheConfig {
+    /** Time-to-live in milliseconds (default: 5000) */
+    ttlMs: number;
+    /** Maximum number of entries to hold (LRU eviction) */
+    maxEntries: number;
+}
+/**
+ * Statistics snapshot for monitoring.
+ */
+export interface TrustCacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    missRate: number;
+    avgAgeMs: number;
+    invalidations: number;
+    size: number;
+}
+/**
+ * Trust signal event shape for invalidation subscription.
+ */
+export interface TrustSignalEvent {
+    entityId: ID;
+    [key: string]: unknown;
+}
+/**
+ * Minimal interface for subscribing to trust signals.
+ */
+export interface TrustSignalBus {
+    on(event: string, handler: (signal: TrustSignalEvent) => void): void;
+    off(event: string, handler: (signal: TrustSignalEvent) => void): void;
+}
+/**
+ * Minimal TrustEngine interface for warm-up lookups.
+ */
+export interface TrustScoreProvider {
+    getScore(entityId: ID): Promise<{
+        score: TrustScore;
+        level: TrustLevel;
+    } | null>;
+}
+export declare class TrustLookupCache {
+    private readonly config;
+    private readonly cache;
+    private _hits;
+    private _misses;
+    private _invalidations;
+    private signalBus;
+    private boundInvalidateHandler;
+    constructor(config?: Partial<TrustLookupCacheConfig>);
+    /**
+     * Get a cached trust entry for the given agent.
+     * Returns `null` on miss or TTL expiry.
+     */
+    get(agentId: ID): CachedTrustEntry | null;
+    /**
+     * Store a trust entry in the cache.
+     */
+    set(agentId: ID, entry: Omit<CachedTrustEntry, 'cachedAt'>): void;
+    /**
+     * Invalidate (evict) a single agent entry.
+     * Called on trust signal receipt.
+     */
+    invalidate(agentId: ID): boolean;
+    /**
+     * Invalidate all entries.
+     */
+    invalidateAll(): void;
+    /**
+     * Pre-populate the cache for a list of agent IDs.
+     * Uses the provided TrustScoreProvider (typically the TrustEngine).
+     */
+    warmUp(agentIds: ID[], provider: TrustScoreProvider): Promise<number>;
+    /**
+     * Subscribe to a trust signal bus for event-driven invalidation.
+     * On any trust signal, the cache entry for that agent is evicted.
+     */
+    subscribeToSignals(bus: TrustSignalBus): void;
+    /**
+     * Unsubscribe from the trust signal bus.
+     */
+    unsubscribeFromSignals(): void;
+    /**
+     * Get a snapshot of cache statistics.
+     */
+    getStats(): TrustCacheStats;
+    /**
+     * Reset all statistics counters.
+     */
+    resetStats(): void;
+    /**
+     * Get the current cache size.
+     */
+    get size(): number;
+    /**
+     * Clear all cache entries and statistics.
+     */
+    clear(): void;
+    /**
+     * Dispose: clear cache and unsubscribe from signals.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=trust-cache.d.ts.map

package/dist/enforce/trust-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-cache.d.ts","sourceRoot":"","sources":["../../src/enforce/trust-cache.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAQrE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,UAAU,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,UAAU,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,EAAE,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAAC;IACrE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAAC;CACvE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAClF;AAeD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IAGzD,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,cAAc,CAAK;IAG3B,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,sBAAsB,CAAqD;gBAEvE,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC;IAQpD;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,EAAE,GAAG,gBAAgB,GAAG,IAAI;IAmBzC;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GAAG,IAAI;IAejE;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO;IAQhC;;OAEG;IACH,aAAa,IAAI,IAAI;IAUrB;;;OAGG;IACG,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IA6B3E;;;OAGG;IACH,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAW7C;;OAEG;IACH,sBAAsB,IAAI,IAAI;IAY9B;;OAEG;IACH,QAAQ,IAAI,eAAe;IAwB3B;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,IAAI,IAAI;CAIhB"}

package/dist/enforce/trust-cache.js

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Vorion LLC
+/**
+ * Trust Lookup Cache
+ *
+ * Enforcement-level in-memory cache for trust score lookups.
+ * Eliminates redundant TrustEngine.getScore() calls during high-throughput
+ * enforcement windows. At 10K concurrent agents the trust lookup (~0.5ms)
+ * compounds under contention; this cache reduces it to <0.01ms for the
+ * common case where trust has not changed since the last lookup.
+ *
+ * Design choices:
+ * - Map-based O(1) lookup keyed by agentId
+ * - TTL-based expiry (default 5 seconds) — trust scores are EWA-smoothed
+ *   and do not change faster than this in practice
+ * - Event-driven invalidation via trust signal subscription
+ * - Warm-up API for pre-populating top-N active agents
+ *
+ * @packageDocumentation
+ */
+import { createLogger } from '../common/logger.js';
+const logger = createLogger({ component: 'trust-cache' });
+// =============================================================================
+// DEFAULT CONFIGURATION
+// =============================================================================
+const DEFAULT_CONFIG = {
+    ttlMs: 5_000,
+    maxEntries: 50_000,
+};
+// =============================================================================
+// TRUST LOOKUP CACHE
+// =============================================================================
+export class TrustLookupCache {
+    config;
+    cache = new Map();
+    // Stats counters
+    _hits = 0;
+    _misses = 0;
+    _invalidations = 0;
+    // Signal bus binding (stored for cleanup)
+    signalBus = null;
+    boundInvalidateHandler = null;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ===========================================================================
+    // Core API
+    // ===========================================================================
+    /**
+     * Get a cached trust entry for the given agent.
+     * Returns `null` on miss or TTL expiry.
+     */
+    get(agentId) {
+        const entry = this.cache.get(agentId);
+        if (!entry) {
+            this._misses++;
+            return null;
+        }
+        const age = Date.now() - entry.cachedAt;
+        if (age > this.config.ttlMs) {
+            // Expired — evict and count as miss
+            this.cache.delete(agentId);
+            this._misses++;
+            return null;
+        }
+        this._hits++;
+        return entry;
+    }
+    /**
+     * Store a trust entry in the cache.
+     */
+    set(agentId, entry) {
+        // Enforce max entries — evict oldest if at capacity
+        if (this.cache.size >= this.config.maxEntries && !this.cache.has(agentId)) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined) {
+                this.cache.delete(oldest);
+            }
+        }
+        this.cache.set(agentId, {
+            ...entry,
+            cachedAt: Date.now(),
+        });
+    }
+    /**
+     * Invalidate (evict) a single agent entry.
+     * Called on trust signal receipt.
+     */
+    invalidate(agentId) {
+        const existed = this.cache.delete(agentId);
+        if (existed) {
+            this._invalidations++;
+        }
+        return existed;
+    }
+    /**
+     * Invalidate all entries.
+     */
+    invalidateAll() {
+        const count = this.cache.size;
+        this.cache.clear();
+        this._invalidations += count;
+    }
+    // ===========================================================================
+    // Warm-up
+    // ===========================================================================
+    /**
+     * Pre-populate the cache for a list of agent IDs.
+     * Uses the provided TrustScoreProvider (typically the TrustEngine).
+     */
+    async warmUp(agentIds, provider) {
+        let loaded = 0;
+        const promises = agentIds.map(async (id) => {
+            try {
+                const record = await provider.getScore(id);
+                if (record) {
+                    this.set(id, {
+                        trustScore: record.score,
+                        trustTier: record.level,
+                        integrityScore: record.score, // Approximate; real integrity comes from ParameSphere
+                        observationTier: record.level,
+                    });
+                    loaded++;
+                }
+            }
+            catch {
+                // Warm-up is best-effort — skip failures
+                logger.warn({ agentId: id }, 'Trust cache warm-up failed for agent');
+            }
+        });
+        await Promise.all(promises);
+        logger.info({ requested: agentIds.length, loaded }, 'Trust cache warm-up complete');
+        return loaded;
+    }
+    // ===========================================================================
+    // Signal bus integration
+    // ===========================================================================
+    /**
+     * Subscribe to a trust signal bus for event-driven invalidation.
+     * On any trust signal, the cache entry for that agent is evicted.
+     */
+    subscribeToSignals(bus) {
+        if (this.signalBus) {
+            this.unsubscribeFromSignals();
+        }
+        this.signalBus = bus;
+        this.boundInvalidateHandler = (signal) => {
+            this.invalidate(signal.entityId);
+        };
+        bus.on('trust-signal', this.boundInvalidateHandler);
+    }
+    /**
+     * Unsubscribe from the trust signal bus.
+     */
+    unsubscribeFromSignals() {
+        if (this.signalBus && this.boundInvalidateHandler) {
+            this.signalBus.off('trust-signal', this.boundInvalidateHandler);
+        }
+        this.signalBus = null;
+        this.boundInvalidateHandler = null;
+    }
+    // ===========================================================================
+    // Stats / monitoring
+    // ===========================================================================
+    /**
+     * Get a snapshot of cache statistics.
+     */
+    getStats() {
+        const total = this._hits + this._misses;
+        const hitRate = total > 0 ? this._hits / total : 0;
+        const missRate = total > 0 ? this._misses / total : 0;
+        // Compute average age of live entries
+        let totalAge = 0;
+        const now = Date.now();
+        for (const entry of this.cache.values()) {
+            totalAge += now - entry.cachedAt;
+        }
+        const avgAgeMs = this.cache.size > 0 ? totalAge / this.cache.size : 0;
+        return {
+            hits: this._hits,
+            misses: this._misses,
+            hitRate,
+            missRate,
+            avgAgeMs,
+            invalidations: this._invalidations,
+            size: this.cache.size,
+        };
+    }
+    /**
+     * Reset all statistics counters.
+     */
+    resetStats() {
+        this._hits = 0;
+        this._misses = 0;
+        this._invalidations = 0;
+    }
+    /**
+     * Get the current cache size.
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Clear all cache entries and statistics.
+     */
+    clear() {
+        this.cache.clear();
+        this.resetStats();
+    }
+    /**
+     * Dispose: clear cache and unsubscribe from signals.
+     */
+    dispose() {
+        this.unsubscribeFromSignals();
+        this.clear();
+    }
+}
+//# sourceMappingURL=trust-cache.js.map

package/dist/enforce/trust-cache.js.map

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

package/dist/paramesphere/gpu-svd.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Provider interface for SVD computation.
+ *
+ * All implementations must produce results within 1e-6 tolerance of
+ * the CPU power-iteration baseline for the same input.
+ */
+export interface GpuSvdProvider {
+    /** Check whether this provider's backend is available at runtime. */
+    available(): Promise<boolean>;
+    /**
+     * Compute the top-K singular values of a row-major matrix.
+     *
+     * @param data  Row-major flat Float64Array of the matrix.
+     * @param rows  Number of rows.
+     * @param cols  Number of columns.
+     * @param k     Number of singular values to extract.
+     * @returns     Float64Array of length min(k, min(rows, cols)) with
+     *              the top singular values in descending order.
+     */
+    topKSingularValues(data: Float64Array, rows: number, cols: number, k: number): Promise<Float64Array>;
+}
+/**
+ * CPU fallback provider that delegates to the existing power-iteration
+ * implementation. This is the baseline — all other providers must match
+ * its output within 1e-6 tolerance.
+ */
+export declare class CpuFallbackProvider implements GpuSvdProvider {
+    available(): Promise<boolean>;
+    topKSingularValues(data: Float64Array, rows: number, cols: number, k: number): Promise<Float64Array>;
+}
+/**
+ * WebGPU-based SVD provider.
+ *
+ * Uses a compute shader for the expensive A^T*A*v products in the power
+ * iteration loop. Falls back to CPU if WebGPU is unavailable.
+ *
+ * Note: This provider is primarily useful in browser or Deno environments
+ * that expose the WebGPU API. In Node.js, prefer `OnnxSvdProvider`.
+ */
+export declare class WebGpuSvdProvider implements GpuSvdProvider {
+    private device;
+    private pipeline;
+    private fallback;
+    private initPromise;
+    /** Power iteration parameters matching the CPU implementation. */
+    private static readonly POWER_ITER_MAX;
+    private static readonly POWER_ITER_TOL;
+    available(): Promise<boolean>;
+    topKSingularValues(data: Float64Array, rows: number, cols: number, k: number): Promise<Float64Array>;
+    private initGpu;
+    private computeOnGpu;
+}
+/**
+ * ONNX Runtime-based SVD provider for Node.js server environments.
+ *
+ * Uses ONNX Runtime's CUDA execution provider when available, falling
+ * back to the CPU execution provider. This is the recommended GPU path
+ * for Node.js where WebGPU is not yet available.
+ *
+ * Implementation strategy: Since ONNX doesn't have a direct SVD op,
+ * we implement the same power-iteration algorithm but offload the
+ * matrix-vector multiplications (the expensive inner loop) to ONNX
+ * Runtime which can run them on GPU via CUDA/cuDNN.
+ */
+export declare class OnnxSvdProvider implements GpuSvdProvider {
+    private session;
+    private onnxAvailable;
+    private executionProvider;
+    private fallback;
+    private initPromise;
+    /** Power iteration parameters matching the CPU implementation. */
+    private static readonly POWER_ITER_MAX;
+    private static readonly POWER_ITER_TOL;
+    available(): Promise<boolean>;
+    topKSingularValues(data: Float64Array, rows: number, cols: number, k: number): Promise<Float64Array>;
+    /** Returns the active execution provider name ('cuda' or 'cpu'). */
+    getExecutionProvider(): string;
+    private initOnnx;
+    private computeWithOnnx;
+    /**
+     * GPU-accelerated matrix-vector multiply via ONNX Runtime.
+     * Falls back to CPU implementation if ONNX session is unavailable.
+     */
+    private onnxMatVecMul;
+    /**
+     * GPU-accelerated A^T * u via ONNX Runtime.
+     */
+    private onnxMatTransVecMul;
+}
+/**
+ * Create the best available SVD provider.
+ *
+ * Auto-detection order:
+ * 1. WebGPU (if `preference` is 'gpu' or unset and WebGPU is available)
+ * 2. ONNX Runtime with CUDA (if `preference` is 'onnx' or unset and onnxruntime-node is installed)
+ * 3. CPU fallback (always available)
+ *
+ * @param preference - Force a specific provider. Omit to auto-detect.
+ * @returns The best available provider.
+ */
+export declare function createSvdProvider(preference?: 'gpu' | 'onnx' | 'cpu'): Promise<GpuSvdProvider>;
+//# sourceMappingURL=gpu-svd.d.ts.map

package/dist/paramesphere/gpu-svd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-svd.d.ts","sourceRoot":"","sources":["../../src/paramesphere/gpu-svd.ts"],"names":[],"mappings":"AA8BA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9B;;;;;;;;;OASG;IACH,kBAAkB,CAChB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAMD;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAClD,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,kBAAkB,CACtB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,YAAY,CAAC;CAGzB;AAiED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IACtD,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,WAAW,CAAiC;IAEpD,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAO;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAS;IAEzC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAM7B,kBAAkB,CACtB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,YAAY,CAAC;YAkBV,OAAO;YAoCP,YAAY;CAkI3B;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,WAAW,CAAiC;IAEpD,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAO;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAS;IAEzC,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAM7B,kBAAkB,CACtB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,YAAY,CAAC;IAcxB,oEAAoE;IACpE,oBAAoB,IAAI,MAAM;YAQhB,QAAQ;YAwCR,eAAe;IAwD7B;;;OAGG;YACW,aAAa;IAkC3B;;OAEG;YACW,kBAAkB;CAmCjC;AAmJD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAClC,OAAO,CAAC,cAAc,CAAC,CA0BzB"}