@vorionsys/atsf-core 0.2.3 → 0.3.0

package/dist/paramesphere/activation-collector.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ActivationCollector — Collects and computes activation statistics
+ * from numeric data streams (model hidden states, attention outputs, etc.)
+ *
+ * Uses Welford's online algorithm for numerically stable incremental
+ * computation of mean, variance, skewness, and kurtosis without storing
+ * all raw values in memory.
+ *
+ * Feeds into {@link ParameSphereEngine.computeFingerprint} as activation stats.
+ *
+ * @packageDocumentation
+ */
+import type { ActivationStats } from './types.js';
+/** Configuration for the ActivationCollector. */
+export interface ActivationCollectorConfig {
+    /** Maximum number of samples per layer (rolling window). Default: 1000. */
+    maxSamplesPerLayer: number;
+    /** Minimum samples required before stats are returned. Default: 10. */
+    minSamplesForStats: number;
+    /** Specific layers to collect (undefined = all layers accepted). */
+    layers?: string[];
+}
+/**
+ * Internal accumulator using Welford's online algorithm extended to
+ * compute the first four central moments incrementally.
+ *
+ * References:
+ * - Welford (1962), "Note on a method for calculating corrected sums of
+ *   squares and products"
+ * - Pébay (2008), "Formulas for Robust, One-Pass Parallel Computation of
+ *   Covariances and Arbitrary-Order Statistical Moments" (Sandia TR)
+ *
+ * We track:
+ *   n   — count of values seen
+ *   M1  — running mean
+ *   M2  — sum of squared deviations from the mean  (for variance)
+ *   M3  — sum of cubed deviations from the mean    (for skewness)
+ *   M4  — sum of 4th-power deviations from the mean (for kurtosis)
+ */
+declare class WelfordAccumulator {
+    n: number;
+    M1: number;
+    M2: number;
+    M3: number;
+    M4: number;
+    /**
+     * Add a single value to the accumulator.
+     *
+     * Uses the Terriberry (2007) / Pébay (2008) update formulas for
+     * higher-order central moments.
+     */
+    push(x: number): void;
+    /**
+     * Remove a single value from the accumulator (inverse Welford).
+     *
+     * Used to implement the rolling window: when we exceed maxSamples,
+     * we subtract the oldest value's contribution.
+     *
+     * Note: this is the algebraic inverse of push(). It is numerically
+     * less stable than push() alone, but acceptable for our rolling-window
+     * use case where the window size is large relative to individual values.
+     */
+    remove(x: number): void;
+    /** Arithmetic mean. */
+    get mean(): number;
+    /** Population variance. */
+    get variance(): number;
+    /** Population standard deviation. */
+    get stddev(): number;
+    /**
+     * Excess kurtosis (Fisher's definition).
+     *
+     * excess_kurtosis = (n * M4) / (M2^2) - 3
+     *
+     * Normal distribution has excess kurtosis = 0.
+     * Uniform distribution has excess kurtosis = -1.2.
+     */
+    get kurtosis(): number;
+    /**
+     * Skewness (Fisher's definition, population formula).
+     *
+     * skewness = (sqrt(n) * M3) / (M2^(3/2))
+     *
+     * Symmetric distributions have skewness = 0.
+     */
+    get skewness(): number;
+    /** Clone the accumulator state. */
+    clone(): WelfordAccumulator;
+}
+export declare class ActivationCollector {
+    private readonly config;
+    private readonly layers;
+    constructor(config?: Partial<ActivationCollectorConfig>);
+    /**
+     * Record a batch of activation values for a named layer.
+     *
+     * @param layerName  Identifier for the layer (e.g., "transformer.h.0.attn")
+     * @param values     Activation values from one inference pass.
+     *                   Accepts Float32Array or number[].
+     */
+    record(layerName: string, values: Float32Array | number[]): void;
+    /**
+     * Get computed activation statistics for all recorded layers.
+     *
+     * Layers with fewer samples than `minSamplesForStats` are excluded.
+     * The returned array is ordered by layer name (lexicographic).
+     */
+    getStats(): ActivationStats[];
+    /**
+     * Get computed stats for a specific layer.
+     *
+     * Returns `undefined` if the layer has not been recorded or has fewer
+     * samples than `minSamplesForStats`.
+     */
+    getLayerStats(layerName: string): ActivationStats | undefined;
+    /**
+     * Reset all collected data across all layers.
+     */
+    reset(): void;
+    /**
+     * Get the effective sample count for each layer.
+     *
+     * The count is capped at `maxSamplesPerLayer` (rolling window).
+     */
+    getSampleCounts(): Map<string, number>;
+}
+export { WelfordAccumulator };
+//# sourceMappingURL=activation-collector.d.ts.map

package/dist/paramesphere/activation-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-collector.d.ts","sourceRoot":"","sources":["../../src/paramesphere/activation-collector.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMlD,iDAAiD;AACjD,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,cAAM,kBAAkB;IACtB,CAAC,SAAK;IACN,EAAE,SAAK;IACP,EAAE,SAAK;IACP,EAAE,SAAK;IACP,EAAE,SAAK;IAEP;;;;;OAKG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAuBrB;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAwCvB,uBAAuB;IACvB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,2BAA2B;IAC3B,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,qCAAqC;IACrC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAED;;;;;;OAMG;IACH,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAED,mCAAmC;IACnC,KAAK,IAAI,kBAAkB;CAS5B;AAoBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;gBAEjD,MAAM,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC;IAcvD;;;;;;OAMG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,IAAI;IAmChE;;;;;OAKG;IACH,QAAQ,IAAI,eAAe,EAAE;IAc7B;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAkB7D;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAOvC;AAGD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/paramesphere/activation-collector.js

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Vorion LLC
+const DEFAULT_CONFIG = {
+    maxSamplesPerLayer: 1000,
+    minSamplesForStats: 10,
+};
+// ---------------------------------------------------------------------------
+// Welford Accumulator — tracks running statistics up to 4th central moment
+// ---------------------------------------------------------------------------
+/**
+ * Internal accumulator using Welford's online algorithm extended to
+ * compute the first four central moments incrementally.
+ *
+ * References:
+ * - Welford (1962), "Note on a method for calculating corrected sums of
+ *   squares and products"
+ * - Pébay (2008), "Formulas for Robust, One-Pass Parallel Computation of
+ *   Covariances and Arbitrary-Order Statistical Moments" (Sandia TR)
+ *
+ * We track:
+ *   n   — count of values seen
+ *   M1  — running mean
+ *   M2  — sum of squared deviations from the mean  (for variance)
+ *   M3  — sum of cubed deviations from the mean    (for skewness)
+ *   M4  — sum of 4th-power deviations from the mean (for kurtosis)
+ */
+class WelfordAccumulator {
+    n = 0;
+    M1 = 0;
+    M2 = 0;
+    M3 = 0;
+    M4 = 0;
+    /**
+     * Add a single value to the accumulator.
+     *
+     * Uses the Terriberry (2007) / Pébay (2008) update formulas for
+     * higher-order central moments.
+     */
+    push(x) {
+        const n1 = this.n;
+        this.n += 1;
+        const n = this.n;
+        const delta = x - this.M1;
+        const deltaN = delta / n;
+        const deltaN2 = deltaN * deltaN;
+        const term1 = delta * deltaN * n1;
+        this.M1 += deltaN;
+        // Update M4 before M3 and M2 (they depend on old M2/M3)
+        this.M4 +=
+            term1 * deltaN2 * (n * n - 3 * n + 3) +
+                6 * deltaN2 * this.M2 -
+                4 * deltaN * this.M3;
+        this.M3 += term1 * deltaN * (n - 2) - 3 * deltaN * this.M2;
+        this.M2 += term1;
+    }
+    /**
+     * Remove a single value from the accumulator (inverse Welford).
+     *
+     * Used to implement the rolling window: when we exceed maxSamples,
+     * we subtract the oldest value's contribution.
+     *
+     * Note: this is the algebraic inverse of push(). It is numerically
+     * less stable than push() alone, but acceptable for our rolling-window
+     * use case where the window size is large relative to individual values.
+     */
+    remove(x) {
+        if (this.n <= 1) {
+            this.n = 0;
+            this.M1 = 0;
+            this.M2 = 0;
+            this.M3 = 0;
+            this.M4 = 0;
+            return;
+        }
+        const n = this.n;
+        const n1 = n - 1;
+        const delta = x - this.M1;
+        const deltaN = delta / n1;
+        const deltaN2 = deltaN * deltaN;
+        const term1 = delta * deltaN * n;
+        const newM1 = (this.M1 * n - x) / n1;
+        const newDelta = x - newM1;
+        // Reverse the M4 update
+        this.M4 -=
+            term1 * deltaN2 * (n * n - 3 * n + 3) +
+                6 * deltaN2 * (this.M2 - newDelta * delta) -
+                4 * deltaN * (this.M3 - newDelta * delta * (delta - deltaN));
+        // Reverse the M3 update
+        this.M3 -= term1 * deltaN * (n - 2) - 3 * deltaN * (this.M2 - newDelta * delta);
+        // Reverse the M2 update
+        this.M2 -= newDelta * delta;
+        this.M1 = newM1;
+        this.n = n1;
+        // Clamp M2 to non-negative (floating point can push it slightly below 0)
+        if (this.M2 < 0)
+            this.M2 = 0;
+    }
+    /** Arithmetic mean. */
+    get mean() {
+        return this.n > 0 ? this.M1 : 0;
+    }
+    /** Population variance. */
+    get variance() {
+        return this.n > 1 ? this.M2 / this.n : 0;
+    }
+    /** Population standard deviation. */
+    get stddev() {
+        return Math.sqrt(this.variance);
+    }
+    /**
+     * Excess kurtosis (Fisher's definition).
+     *
+     * excess_kurtosis = (n * M4) / (M2^2) - 3
+     *
+     * Normal distribution has excess kurtosis = 0.
+     * Uniform distribution has excess kurtosis = -1.2.
+     */
+    get kurtosis() {
+        if (this.n < 4 || this.M2 === 0)
+            return 0;
+        return (this.n * this.M4) / (this.M2 * this.M2) - 3;
+    }
+    /**
+     * Skewness (Fisher's definition, population formula).
+     *
+     * skewness = (sqrt(n) * M3) / (M2^(3/2))
+     *
+     * Symmetric distributions have skewness = 0.
+     */
+    get skewness() {
+        if (this.n < 3 || this.M2 === 0)
+            return 0;
+        return (Math.sqrt(this.n) * this.M3) / Math.pow(this.M2, 1.5);
+    }
+    /** Clone the accumulator state. */
+    clone() {
+        const acc = new WelfordAccumulator();
+        acc.n = this.n;
+        acc.M1 = this.M1;
+        acc.M2 = this.M2;
+        acc.M3 = this.M3;
+        acc.M4 = this.M4;
+        return acc;
+    }
+}
+// ---------------------------------------------------------------------------
+// ActivationCollector
+// ---------------------------------------------------------------------------
+export class ActivationCollector {
+    config;
+    layers = new Map();
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        if (this.config.maxSamplesPerLayer < 1) {
+            throw new Error('maxSamplesPerLayer must be >= 1');
+        }
+        if (this.config.minSamplesForStats < 1) {
+            throw new Error('minSamplesForStats must be >= 1');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Record a batch of activation values for a named layer.
+     *
+     * @param layerName  Identifier for the layer (e.g., "transformer.h.0.attn")
+     * @param values     Activation values from one inference pass.
+     *                   Accepts Float32Array or number[].
+     */
+    record(layerName, values) {
+        // If a layer allowlist is configured, skip unlisted layers
+        if (this.config.layers && !this.config.layers.includes(layerName)) {
+            return;
+        }
+        let state = this.layers.get(layerName);
+        if (!state) {
+            state = {
+                accumulator: new WelfordAccumulator(),
+                buffer: new Float64Array(this.config.maxSamplesPerLayer),
+                writePos: 0,
+                totalRecorded: 0,
+            };
+            this.layers.set(layerName, state);
+        }
+        const max = this.config.maxSamplesPerLayer;
+        for (let i = 0; i < values.length; i++) {
+            const val = values[i];
+            // If the buffer is full, remove the oldest value before adding new
+            if (state.totalRecorded >= max) {
+                const oldVal = state.buffer[state.writePos];
+                state.accumulator.remove(oldVal);
+            }
+            state.accumulator.push(val);
+            state.buffer[state.writePos] = val;
+            state.writePos = (state.writePos + 1) % max;
+            state.totalRecorded++;
+        }
+    }
+    /**
+     * Get computed activation statistics for all recorded layers.
+     *
+     * Layers with fewer samples than `minSamplesForStats` are excluded.
+     * The returned array is ordered by layer name (lexicographic).
+     */
+    getStats() {
+        const result = [];
+        const sortedKeys = Array.from(this.layers.keys()).sort();
+        for (const key of sortedKeys) {
+            const stats = this.getLayerStats(key);
+            if (stats) {
+                result.push(stats);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get computed stats for a specific layer.
+     *
+     * Returns `undefined` if the layer has not been recorded or has fewer
+     * samples than `minSamplesForStats`.
+     */
+    getLayerStats(layerName) {
+        const state = this.layers.get(layerName);
+        if (!state)
+            return undefined;
+        const effectiveCount = Math.min(state.totalRecorded, this.config.maxSamplesPerLayer);
+        if (effectiveCount < this.config.minSamplesForStats) {
+            return undefined;
+        }
+        const acc = state.accumulator;
+        return {
+            mean: acc.mean,
+            stddev: acc.stddev,
+            kurtosis: acc.kurtosis,
+            skewness: acc.skewness,
+        };
+    }
+    /**
+     * Reset all collected data across all layers.
+     */
+    reset() {
+        this.layers.clear();
+    }
+    /**
+     * Get the effective sample count for each layer.
+     *
+     * The count is capped at `maxSamplesPerLayer` (rolling window).
+     */
+    getSampleCounts() {
+        const counts = new Map();
+        for (const [name, state] of this.layers) {
+            counts.set(name, Math.min(state.totalRecorded, this.config.maxSamplesPerLayer));
+        }
+        return counts;
+    }
+}
+// Export the accumulator for testing internals
+export { WelfordAccumulator };
+//# sourceMappingURL=activation-collector.js.map

package/dist/paramesphere/activation-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-collector.js","sourceRoot":"","sources":["../../src/paramesphere/activation-collector.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AA+BjC,MAAM,cAAc,GAA8B;IAChD,kBAAkB,EAAE,IAAI;IACxB,kBAAkB,EAAE,EAAE;CACvB,CAAC;AAEF,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,kBAAkB;IACtB,CAAC,GAAG,CAAC,CAAC;IACN,EAAE,GAAG,CAAC,CAAC;IACP,EAAE,GAAG,CAAC,CAAC;IACP,EAAE,GAAG,CAAC,CAAC;IACP,EAAE,GAAG,CAAC,CAAC;IAEP;;;;;OAKG;IACH,IAAI,CAAC,CAAS;QACZ,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACZ,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAEjB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;QAChC,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,EAAE,CAAC;QAElC,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC;QAElB,wDAAwD;QACxD,IAAI,CAAC,EAAE;YACL,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACrC,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE;gBACrB,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;QAEvB,IAAI,CAAC,EAAE,IAAI,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;QAE3D,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC;IACnB,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAS;QACd,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YAChB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACX,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;YACZ,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;YACZ,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;YACZ,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;YACZ,OAAO;QACT,CAAC;QAED,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACjB,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QAEjB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,GAAG,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;QAChC,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC;QAEjC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC;QAE3B,wBAAwB;QACxB,IAAI,CAAC,EAAE;YACL,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACrC,CAAC,GAAG,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,GAAG,KAAK,CAAC;gBAC1C,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,GAAG,KAAK,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC;QAE/D,wBAAwB;QACxB,IAAI,CAAC,EAAE,IAAI,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,GAAG,KAAK,CAAC,CAAC;QAEhF,wBAAwB;QACxB,IAAI,CAAC,EAAE,IAAI,QAAQ,GAAG,KAAK,CAAC;QAE5B,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC;QAChB,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;QAEZ,yEAAyE;QACzE,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC;YAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,uBAAuB;IACvB,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,2BAA2B;IAC3B,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,qCAAqC;IACrC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ;QACV,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;OAMG;IACH,IAAI,QAAQ;QACV,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,EAAE,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,mCAAmC;IACnC,KAAK;QACH,MAAM,GAAG,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACrC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACf,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACjB,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACjB,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACjB,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAgBD,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,OAAO,mBAAmB;IACb,MAAM,CAA4B;IAClC,MAAM,GAA4B,IAAI,GAAG,EAAE,CAAC;IAE7D,YAAY,MAA2C;QACrD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,aAAa;IACb,0EAA0E;IAE1E;;;;;;OAMG;IACH,MAAM,CAAC,SAAiB,EAAE,MAA+B;QACvD,2DAA2D;QAC3D,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,OAAO;QACT,CAAC;QAED,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG;gBACN,WAAW,EAAE,IAAI,kBAAkB,EAAE;gBACrC,MAAM,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC;gBACxD,QAAQ,EAAE,CAAC;gBACX,aAAa,EAAE,CAAC;aACjB,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC;QAE3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YAEtB,mEAAmE;YACnE,IAAI,KAAK,CAAC,aAAa,IAAI,GAAG,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC5C,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC;YAED,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC;YACnC,KAAK,CAAC,QAAQ,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;YAC5C,KAAK,CAAC,aAAa,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACN,MAAM,MAAM,GAAsB,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAEzD,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,SAAiB;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACrF,IAAI,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YACpD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;SACvB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACxC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,+CAA+C;AAC/C,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

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

@@ -0,0 +1,73 @@
+/**
+ * Cognitive Envelope — Hyper-Rectangle Breach Detection
+ *
+ * Implements the patent-specified 6-dimensional cognitive envelope that
+ * monitors an AI model's characteristic vector for anomalous deviations.
+ *
+ * The envelope E is defined as the Cartesian product of per-dimension
+ * intervals [mu_d − k·sigma_d, mu_d + k·sigma_d] for d = 1..D.
+ * With k = 3 (99.7% coverage per dimension), the probability of a
+ * false positive across all 6 independent dimensions is bounded by
+ * (1 − 0.997)^6 ≈ (0.003)^6 ≈ 7.3e-16 for a single sample. Requiring
+ * 3 consecutive breaches reduces the effective FP rate to ~(0.003)^3
+ * ≈ 2.7e-8 per dimension, as specified in the patent.
+ *
+ * Characteristic vector dimensions (defaults):
+ *   0 — Weight Geometry           (Frobenius norm or spectral norm)
+ *   1 — Activation Clustering     (silhouette coefficient)
+ *   2 — Embedding Drift           (cosine distance from baseline)
+ *   3 — Attention Entropy         (average attention entropy)
+ *   4 — Gradient Norm             (global gradient L2 norm)
+ *   5 — Effective Dimensionality  (participation ratio)
+ *
+ * @packageDocumentation
+ */
+import type { EnvelopeConfig, BreachResult, EnvelopeState } from './types.js';
+export declare class CognitiveEnvelope {
+    private readonly config;
+    private mu;
+    private sigma;
+    private lowerBounds;
+    private upperBounds;
+    private baselined;
+    private breachCounter;
+    private lastCheckMs;
+    constructor(config?: Partial<EnvelopeConfig>);
+    /**
+     * 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: number[][]): void;
+    /**
+     * 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: number[]): BreachResult;
+    /**
+     * Get the current internal state of the envelope.
+     */
+    getState(): EnvelopeState;
+    /**
+     * Reset the breach counter to zero without clearing the baseline.
+     */
+    reset(): void;
+    /**
+     * Fully clear the baseline and all state.
+     */
+    clearBaseline(): void;
+    /**
+     * 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)
+     */
+    private currentTrustMultiplier;
+}
+//# sourceMappingURL=cognitive-envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cognitive-envelope.d.ts","sourceRoot":"","sources":["../../src/paramesphere/cognitive-envelope.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkB9E,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IAGxC,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,WAAW,CAAK;gBAEZ,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAiB5C;;;;;;OAMG;IACH,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;IAuDxD;;;;;;OAMG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,YAAY;IAgEjD;;OAEG;IACH,QAAQ,IAAI,aAAa;IAYzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,aAAa,IAAI,IAAI;IAcrB;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;CAK/B"}