@vorionsys/atsf-core 0.2.4 → 0.3.0

package/dist/paramesphere/paramesphere-engine.d.ts

@@ -0,0 +1,111 @@
+import type { ParameSphereConfig, ParameSphereFingerprint, ActivationStats, FingerprintComparison, DriftResult } from './types.js';
+/**
+ * Compute the top-K singular values of a matrix using the deflated
+ * power-iteration method.
+ *
+ * Given an m × n matrix A (stored row-major in a flat Float64Array),
+ * this iteratively finds the largest singular value via the power method
+ * on A^T A, then deflates the matrix and repeats for the next largest.
+ *
+ * @param data  Row-major flat array of the matrix.
+ * @param rows  Number of rows (m).
+ * @param cols  Number of columns (n).
+ * @param k     Number of singular values to extract.
+ * @returns     Float64Array of length min(k, min(m,n)) with the top
+ *              singular values in descending order.
+ */
+declare function topKSingularValues(data: Float64Array, rows: number, cols: number, k: number): Float64Array;
+declare function cosineSimilarity(a: Float64Array, b: Float64Array): number;
+declare function l2Distance(a: Float64Array, b: Float64Array): number;
+/**
+ * Select which layer indices to sample.
+ *
+ * Uses a deterministic spread strategy: always include first and last layer,
+ * then fill in evenly-spaced layers up to the target count.
+ */
+declare function selectLayers(totalLayers: number, ratio: number): number[];
+export declare class ParameSphereEngine {
+    private readonly config;
+    private baseline;
+    private cache;
+    /** Cached singular values from the last computation, keyed by layer index. */
+    private prevSingularValues;
+    /** Optional persistent store for fingerprints and baselines. */
+    private readonly store;
+    /** Entity ID for store operations. */
+    private readonly entityId;
+    constructor(config?: Partial<ParameSphereConfig>);
+    /**
+     * Compute a full fingerprint from scratch.
+     *
+     * @param weights          Array of weight matrices, one per layer.
+     *                         Each Float32Array is treated as a flat row-major
+     *                         matrix. The engine infers rows/cols by assuming a
+     *                         roughly square shape (sqrt heuristic) unless the
+     *                         layer is clearly rectangular.
+     * @param activationStats  Optional per-layer activation statistics.
+     */
+    computeFingerprint(weights: Float32Array[], activationStats?: ActivationStats[]): ParameSphereFingerprint;
+    /**
+     * Incremental fingerprint update.
+     *
+     * Re-uses cached singular values where the delta is negligible, only
+     * recomputing layers whose weights have changed significantly.
+     */
+    updateFingerprint(newWeights: Float32Array[], activationStats?: ActivationStats[]): ParameSphereFingerprint;
+    /**
+     * Compare two fingerprints.
+     */
+    compareFingerprints(a: ParameSphereFingerprint, b: ParameSphereFingerprint): FingerprintComparison;
+    /**
+     * Store a fingerprint as the drift-detection baseline.
+     *
+     * When a persistent store is configured, the baseline is also saved
+     * to the store so it survives process restarts.
+     */
+    setBaseline(fingerprint: ParameSphereFingerprint): void;
+    /**
+     * Check drift of a current fingerprint against the stored baseline.
+     *
+     * When a persistent store is configured and no in-memory baseline exists,
+     * the engine attempts to load the baseline from the store before comparing.
+     * Use the async overload `checkDriftAsync` if your store backend is truly
+     * async; this synchronous version will throw if neither in-memory nor store
+     * baseline is available.
+     */
+    checkDrift(current: ParameSphereFingerprint): DriftResult;
+    /**
+     * Async drift check that loads baseline from store if needed.
+     *
+     * Preferred when using a persistent store: on the first call after a
+     * restart, this method transparently restores the baseline from the
+     * store so drift detection resumes seamlessly.
+     */
+    checkDriftAsync(current: ParameSphereFingerprint): Promise<DriftResult>;
+    /**
+     * Clear the incremental cache and baseline.
+     */
+    clearCache(): void;
+    /** Get the current cache of recent fingerprints. */
+    getCache(): readonly ParameSphereFingerprint[];
+    private buildFingerprint;
+    /** Pull activation stats into a flat Float64Array for the composite vector. */
+    private extractActivationVector;
+    private emptyFingerprint;
+    /** Convert a ParameSphereFingerprint to a StoredFingerprint for persistence. */
+    private toStoredFingerprint;
+    /** Reconstruct a ParameSphereFingerprint from a StoredFingerprint. */
+    private fromStoredFingerprint;
+}
+/**
+ * Infer a (rows, cols) shape from a flat array length.
+ *
+ * Heuristic: find the factor pair closest to sqrt that gives a valid
+ * factorisation. Falls back to (1, length) for primes / small arrays.
+ */
+declare function inferShape(length: number): {
+    rows: number;
+    cols: number;
+};
+export { topKSingularValues, selectLayers, inferShape, cosineSimilarity, l2Distance };
+//# sourceMappingURL=paramesphere-engine.d.ts.map

package/dist/paramesphere/paramesphere-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paramesphere-engine.d.ts","sourceRoot":"","sources":["../../src/paramesphere/paramesphere-engine.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,WAAW,EACZ,MAAM,YAAY,CAAC;AAuBpB;;;;;;;;;;;;;;GAcG;AACH,iBAAS,kBAAkB,CACzB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,CAAC,EAAE,MAAM,GACR,YAAY,CAoDd;AAoED,iBAAS,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAYlE;AAED,iBAAS,UAAU,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAQ5D;AAMD;;;;;GAKG;AACH,iBAAS,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBlE;AAMD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAwC;IACxD,OAAO,CAAC,KAAK,CAAiC;IAE9C,8EAA8E;IAC9E,OAAO,CAAC,kBAAkB,CAAwC;IAElE,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;gBAElC,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC;IAmBhD;;;;;;;;;OASG;IACH,kBAAkB,CAChB,OAAO,EAAE,YAAY,EAAE,EACvB,eAAe,CAAC,EAAE,eAAe,EAAE,GAClC,uBAAuB;IAoB1B;;;;;OAKG;IACH,iBAAiB,CACf,UAAU,EAAE,YAAY,EAAE,EAC1B,eAAe,CAAC,EAAE,eAAe,EAAE,GAClC,uBAAuB;IAsC1B;;OAEG;IACH,mBAAmB,CACjB,CAAC,EAAE,uBAAuB,EAC1B,CAAC,EAAE,uBAAuB,GACzB,qBAAqB;IAsBxB;;;;;OAKG;IACH,WAAW,CAAC,WAAW,EAAE,uBAAuB,GAAG,IAAI;IAWvD;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW;IAazD;;;;;;OAMG;IACG,eAAe,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IAU7E;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB,oDAAoD;IACpD,QAAQ,IAAI,SAAS,uBAAuB,EAAE;IAQ9C,OAAO,CAAC,gBAAgB;IA8CxB,+EAA+E;IAC/E,OAAO,CAAC,uBAAuB;IAiB/B,OAAO,CAAC,gBAAgB;IAkBxB,gFAAgF;IAChF,OAAO,CAAC,mBAAmB;IA6B3B,sEAAsE;IACtE,OAAO,CAAC,qBAAqB;CAc9B;AAwBD;;;;;GAKG;AACH,iBAAS,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAWlE;AAGD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC"}

package/dist/paramesphere/paramesphere-engine.js

@@ -0,0 +1,542 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Vorion LLC
+/**
+ * ParameSphere SVD Fingerprinting Engine
+ *
+ * Production implementation of the SVD-based model fingerprinting system
+ * described in the Vorion patent specification. Uses power-iteration to
+ * extract the top-K singular values from sampled weight matrices, combines
+ * them with activation statistics, and produces a cryptographic hash of
+ * the composite fingerprint vector.
+ *
+ * Key design choices:
+ * - Power iteration for SVD: no external linear-algebra library needed.
+ * - Float64Array internally for precision; inputs accepted as Float32Array.
+ * - Incremental updates cache previous singular values and compute deltas.
+ * - Dual-hash option (SHA-256 + SHA3-256) for high-assurance use cases.
+ *
+ * @packageDocumentation
+ */
+import * as nodeCrypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    K: 64,
+    layerSampleRatio: 0.15,
+    cacheSize: 5,
+    driftThreshold: 0.05,
+    dualHash: false,
+};
+// Power iteration parameters
+const POWER_ITER_MAX = 300;
+const POWER_ITER_TOL = 1e-10;
+// ---------------------------------------------------------------------------
+// Helpers — Linear Algebra via Power Iteration
+// ---------------------------------------------------------------------------
+/**
+ * Compute the top-K singular values of a matrix using the deflated
+ * power-iteration method.
+ *
+ * Given an m × n matrix A (stored row-major in a flat Float64Array),
+ * this iteratively finds the largest singular value via the power method
+ * on A^T A, then deflates the matrix and repeats for the next largest.
+ *
+ * @param data  Row-major flat array of the matrix.
+ * @param rows  Number of rows (m).
+ * @param cols  Number of columns (n).
+ * @param k     Number of singular values to extract.
+ * @returns     Float64Array of length min(k, min(m,n)) with the top
+ *              singular values in descending order.
+ */
+function topKSingularValues(data, rows, cols, k) {
+    const rank = Math.min(rows, cols, k);
+    const sigmas = new Float64Array(rank);
+    // Work on a copy so deflation doesn't mutate the input.
+    const A = new Float64Array(data);
+    for (let s = 0; s < rank; s++) {
+        // --- power iteration on A^T A to find the dominant right singular vector ---
+        let v = new Float64Array(cols);
+        // Initialise v with a deterministic pseudo-random vector (seeded on s).
+        for (let j = 0; j < cols; j++) {
+            v[j] = Math.sin((s + 1) * (j + 1) * 0.7071);
+        }
+        normalizeVec(v);
+        let sigma = 0;
+        for (let iter = 0; iter < POWER_ITER_MAX; iter++) {
+            // u = A * v
+            const u = matVecMul(A, rows, cols, v);
+            sigma = vecNorm(u);
+            if (sigma < 1e-15)
+                break;
+            scaleVec(u, 1 / sigma);
+            // v_new = A^T * u
+            const vNew = matTransVecMul(A, rows, cols, u);
+            const sigmaNew = vecNorm(vNew);
+            if (sigmaNew < 1e-15)
+                break;
+            scaleVec(vNew, 1 / sigmaNew);
+            // Convergence check: |sigma - sigmaNew| / sigma
+            const diff = Math.abs(sigma - sigmaNew);
+            v = vNew;
+            sigma = sigmaNew;
+            if (diff < POWER_ITER_TOL * sigma)
+                break;
+        }
+        sigmas[s] = sigma;
+        // Deflate: A <- A - sigma * u * v^T
+        const u = matVecMul(A, rows, cols, v);
+        const uNorm = vecNorm(u);
+        if (uNorm > 1e-15) {
+            scaleVec(u, 1 / uNorm);
+            for (let i = 0; i < rows; i++) {
+                for (let j = 0; j < cols; j++) {
+                    A[i * cols + j] -= sigma * u[i] * v[j];
+                }
+            }
+        }
+    }
+    return sigmas;
+}
+/** Multiply matrix A (m×n, row-major) by vector v (length n). */
+function matVecMul(A, m, n, v) {
+    const result = new Float64Array(m);
+    for (let i = 0; i < m; i++) {
+        let sum = 0;
+        const rowOff = i * n;
+        for (let j = 0; j < n; j++) {
+            sum += A[rowOff + j] * v[j];
+        }
+        result[i] = sum;
+    }
+    return result;
+}
+/** Multiply A^T (n×m) by vector u (length m). */
+function matTransVecMul(A, m, n, u) {
+    const result = new Float64Array(n);
+    for (let j = 0; j < n; j++) {
+        let sum = 0;
+        for (let i = 0; i < m; i++) {
+            sum += A[i * n + j] * u[i];
+        }
+        result[j] = sum;
+    }
+    return result;
+}
+/** Euclidean norm of a vector. */
+function vecNorm(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++)
+        sum += v[i] * v[i];
+    return Math.sqrt(sum);
+}
+/** In-place normalisation. */
+function normalizeVec(v) {
+    const n = vecNorm(v);
+    if (n > 1e-15)
+        scaleVec(v, 1 / n);
+}
+/** In-place scalar multiply. */
+function scaleVec(v, s) {
+    for (let i = 0; i < v.length; i++)
+        v[i] *= s;
+}
+// ---------------------------------------------------------------------------
+// Helpers — Hashing
+// ---------------------------------------------------------------------------
+function sha256Hex(bytes) {
+    return nodeCrypto.createHash('sha256').update(bytes).digest('hex');
+}
+function sha3_256Hex(bytes) {
+    return nodeCrypto.createHash('sha3-256').update(bytes).digest('hex');
+}
+/** Convert a Float64Array to its raw byte representation. */
+function float64ToBytes(arr) {
+    return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+}
+// ---------------------------------------------------------------------------
+// Helpers — Geometry
+// ---------------------------------------------------------------------------
+function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom < 1e-15 ? 0 : dot / denom;
+}
+function l2Distance(a, b) {
+    const len = Math.min(a.length, b.length);
+    let sum = 0;
+    for (let i = 0; i < len; i++) {
+        const d = a[i] - b[i];
+        sum += d * d;
+    }
+    return Math.sqrt(sum);
+}
+// ---------------------------------------------------------------------------
+// Layer Sampling
+// ---------------------------------------------------------------------------
+/**
+ * Select which layer indices to sample.
+ *
+ * Uses a deterministic spread strategy: always include first and last layer,
+ * then fill in evenly-spaced layers up to the target count.
+ */
+function selectLayers(totalLayers, ratio) {
+    if (totalLayers <= 0)
+        return [];
+    if (totalLayers === 1)
+        return [0];
+    const count = Math.max(2, Math.min(totalLayers, Math.ceil(totalLayers * ratio)));
+    if (count >= totalLayers) {
+        return Array.from({ length: totalLayers }, (_, i) => i);
+    }
+    const indices = new Set();
+    indices.add(0);
+    indices.add(totalLayers - 1);
+    const step = (totalLayers - 1) / (count - 1);
+    for (let i = 1; i < count - 1; i++) {
+        indices.add(Math.round(i * step));
+    }
+    return Array.from(indices).sort((a, b) => a - b);
+}
+// ---------------------------------------------------------------------------
+// ParameSphereEngine
+// ---------------------------------------------------------------------------
+export class ParameSphereEngine {
+    config;
+    baseline = null;
+    cache = [];
+    /** Cached singular values from the last computation, keyed by layer index. */
+    prevSingularValues = new Map();
+    /** Optional persistent store for fingerprints and baselines. */
+    store;
+    /** Entity ID for store operations. */
+    entityId;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        if (this.config.layerSampleRatio <= 0 || this.config.layerSampleRatio > 1) {
+            throw new Error('layerSampleRatio must be in (0, 1]');
+        }
+        if (this.config.K < 1) {
+            throw new Error('K must be >= 1');
+        }
+        this.store = this.config.store;
+        this.entityId = this.config.entityId;
+        if (this.store && !this.entityId) {
+            throw new Error('entityId is required when a fingerprint store is provided');
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Compute a full fingerprint from scratch.
+     *
+     * @param weights          Array of weight matrices, one per layer.
+     *                         Each Float32Array is treated as a flat row-major
+     *                         matrix. The engine infers rows/cols by assuming a
+     *                         roughly square shape (sqrt heuristic) unless the
+     *                         layer is clearly rectangular.
+     * @param activationStats  Optional per-layer activation statistics.
+     */
+    computeFingerprint(weights, activationStats) {
+        if (weights.length === 0) {
+            return this.emptyFingerprint(0);
+        }
+        const sampledLayers = selectLayers(weights.length, this.config.layerSampleRatio);
+        const allSigmas = [];
+        for (const idx of sampledLayers) {
+            const w = weights[idx];
+            const { rows, cols } = inferShape(w.length);
+            const data = float32ToFloat64(w);
+            const sigmas = topKSingularValues(data, rows, cols, this.config.K);
+            allSigmas.push(sigmas);
+            this.prevSingularValues.set(idx, new Float64Array(sigmas));
+        }
+        return this.buildFingerprint(allSigmas, sampledLayers, weights.length, activationStats);
+    }
+    /**
+     * Incremental fingerprint update.
+     *
+     * Re-uses cached singular values where the delta is negligible, only
+     * recomputing layers whose weights have changed significantly.
+     */
+    updateFingerprint(newWeights, activationStats) {
+        if (newWeights.length === 0) {
+            return this.emptyFingerprint(0);
+        }
+        const sampledLayers = selectLayers(newWeights.length, this.config.layerSampleRatio);
+        const allSigmas = [];
+        for (const idx of sampledLayers) {
+            const w = newWeights[idx];
+            const { rows, cols } = inferShape(w.length);
+            const data = float32ToFloat64(w);
+            const sigmas = topKSingularValues(data, rows, cols, this.config.K);
+            // Compute delta from cached if available
+            const prev = this.prevSingularValues.get(idx);
+            if (prev && prev.length === sigmas.length) {
+                // Use incremental low-rank update: if delta is tiny, blend with prev
+                let maxDelta = 0;
+                for (let i = 0; i < sigmas.length; i++) {
+                    const d = Math.abs(sigmas[i] - prev[i]);
+                    if (d > maxDelta)
+                        maxDelta = d;
+                }
+                // If max delta < 1% of largest singular value, use cached (saves downstream noise)
+                const largest = Math.max(sigmas[0] || 0, prev[0] || 0);
+                if (largest > 0 && maxDelta / largest < 0.01) {
+                    allSigmas.push(prev);
+                    continue;
+                }
+            }
+            this.prevSingularValues.set(idx, new Float64Array(sigmas));
+            allSigmas.push(sigmas);
+        }
+        return this.buildFingerprint(allSigmas, sampledLayers, newWeights.length, activationStats);
+    }
+    /**
+     * Compare two fingerprints.
+     */
+    compareFingerprints(a, b) {
+        const sim = cosineSimilarity(a.vector, b.vector);
+        const dist = 1 - sim;
+        const l2 = l2Distance(a.vector, b.vector);
+        // Max singular-value delta across sampled layers
+        let maxSVDelta = 0;
+        const len = Math.min(a.singularValues.length, b.singularValues.length);
+        for (let i = 0; i < len; i++) {
+            const d = Math.abs(a.singularValues[i] - b.singularValues[i]);
+            if (d > maxSVDelta)
+                maxSVDelta = d;
+        }
+        return {
+            cosineSimilarity: sim,
+            cosineDistance: dist,
+            l2Distance: l2,
+            driftDetected: dist > this.config.driftThreshold,
+            maxSingularValueDelta: maxSVDelta,
+        };
+    }
+    /**
+     * Store a fingerprint as the drift-detection baseline.
+     *
+     * When a persistent store is configured, the baseline is also saved
+     * to the store so it survives process restarts.
+     */
+    setBaseline(fingerprint) {
+        this.baseline = fingerprint;
+        if (this.store && this.entityId) {
+            const stored = this.toStoredFingerprint(fingerprint);
+            this.store.setBaseline(this.entityId, stored).catch(() => {
+                /* persistence is best-effort */
+            });
+        }
+    }
+    /**
+     * Check drift of a current fingerprint against the stored baseline.
+     *
+     * When a persistent store is configured and no in-memory baseline exists,
+     * the engine attempts to load the baseline from the store before comparing.
+     * Use the async overload `checkDriftAsync` if your store backend is truly
+     * async; this synchronous version will throw if neither in-memory nor store
+     * baseline is available.
+     */
+    checkDrift(current) {
+        if (!this.baseline) {
+            throw new Error('No baseline set — call setBaseline() first');
+        }
+        const comparison = this.compareFingerprints(this.baseline, current);
+        return {
+            drifted: comparison.driftDetected,
+            cosineDistance: comparison.cosineDistance,
+            maxSingularValueDelta: comparison.maxSingularValueDelta,
+            comparison,
+        };
+    }
+    /**
+     * Async drift check that loads baseline from store if needed.
+     *
+     * Preferred when using a persistent store: on the first call after a
+     * restart, this method transparently restores the baseline from the
+     * store so drift detection resumes seamlessly.
+     */
+    async checkDriftAsync(current) {
+        if (!this.baseline && this.store && this.entityId) {
+            const stored = await this.store.getBaseline(this.entityId);
+            if (stored) {
+                this.baseline = this.fromStoredFingerprint(stored);
+            }
+        }
+        return this.checkDrift(current);
+    }
+    /**
+     * Clear the incremental cache and baseline.
+     */
+    clearCache() {
+        this.prevSingularValues.clear();
+        this.cache = [];
+        this.baseline = null;
+    }
+    /** Get the current cache of recent fingerprints. */
+    getCache() {
+        return this.cache;
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    buildFingerprint(allSigmas, sampledLayers, totalLayers, activationStats) {
+        // Flatten singular values
+        const flatSigmas = concatFloat64Arrays(allSigmas);
+        // Build composite vector: singular values ‖ activation stat values
+        const statValues = this.extractActivationVector(activationStats, sampledLayers);
+        const vector = concatFloat64Arrays([flatSigmas, statValues]);
+        // Cryptographic hash
+        const bytes = float64ToBytes(vector);
+        const sha256 = sha256Hex(bytes);
+        const sha3 = this.config.dualHash ? sha3_256Hex(bytes) : undefined;
+        const fp = {
+            vector,
+            sha256,
+            sha3_256: sha3,
+            sampledLayers,
+            singularValues: flatSigmas,
+            timestamp: new Date().toISOString(),
+            totalLayers,
+        };
+        // Cache management
+        this.cache.push(fp);
+        if (this.cache.length > this.config.cacheSize) {
+            this.cache.shift();
+        }
+        // Persist to store (fire-and-forget — errors are intentionally swallowed
+        // so the hot path is never blocked by a slow or failing backend).
+        if (this.store && this.entityId) {
+            const stored = this.toStoredFingerprint(fp, activationStats);
+            this.store.saveFingerprint(this.entityId, stored).catch(() => {
+                /* persistence is best-effort */
+            });
+        }
+        return fp;
+    }
+    /** Pull activation stats into a flat Float64Array for the composite vector. */
+    extractActivationVector(stats, sampledLayers) {
+        if (!stats || stats.length === 0)
+            return new Float64Array(0);
+        // Four values per sampled layer with stats
+        const values = [];
+        for (const idx of sampledLayers) {
+            if (idx < stats.length) {
+                const s = stats[idx];
+                values.push(s.mean, s.stddev, s.kurtosis, s.skewness);
+            }
+        }
+        return Float64Array.from(values);
+    }
+    emptyFingerprint(totalLayers) {
+        const vector = new Float64Array(0);
+        const bytes = float64ToBytes(vector);
+        return {
+            vector,
+            sha256: sha256Hex(bytes),
+            sha3_256: this.config.dualHash ? sha3_256Hex(bytes) : undefined,
+            sampledLayers: [],
+            singularValues: new Float64Array(0),
+            timestamp: new Date().toISOString(),
+            totalLayers,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Store conversion helpers
+    // -----------------------------------------------------------------------
+    /** Convert a ParameSphereFingerprint to a StoredFingerprint for persistence. */
+    toStoredFingerprint(fp, activationStats) {
+        const stored = {
+            entityId: this.entityId,
+            hash: fp.sha256,
+            singularValues: Array.from(fp.singularValues),
+            createdAt: new Date(fp.timestamp),
+            metadata: {
+                sampledLayers: fp.sampledLayers,
+                totalLayers: fp.totalLayers,
+                sha3_256: fp.sha3_256,
+                vectorLength: fp.vector.length,
+                // Store the full vector as a plain array for reconstruction
+                vector: Array.from(fp.vector),
+            },
+        };
+        if (activationStats && activationStats.length > 0) {
+            stored.activationStats = activationStats.map((s) => ({
+                mean: s.mean,
+                stddev: s.stddev,
+                kurtosis: s.kurtosis,
+                skewness: s.skewness,
+            }));
+        }
+        return stored;
+    }
+    /** Reconstruct a ParameSphereFingerprint from a StoredFingerprint. */
+    fromStoredFingerprint(stored) {
+        const meta = (stored.metadata ?? {});
+        const vectorArr = meta.vector;
+        const vector = vectorArr ? Float64Array.from(vectorArr) : Float64Array.from(stored.singularValues);
+        return {
+            vector,
+            sha256: stored.hash,
+            sha3_256: meta.sha3_256,
+            sampledLayers: meta.sampledLayers ?? [],
+            singularValues: Float64Array.from(stored.singularValues),
+            timestamp: stored.createdAt.toISOString(),
+            totalLayers: meta.totalLayers ?? 0,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+function float32ToFloat64(src) {
+    const dst = new Float64Array(src.length);
+    for (let i = 0; i < src.length; i++)
+        dst[i] = src[i];
+    return dst;
+}
+function concatFloat64Arrays(arrays) {
+    let totalLen = 0;
+    for (const a of arrays)
+        totalLen += a.length;
+    const result = new Float64Array(totalLen);
+    let offset = 0;
+    for (const a of arrays) {
+        result.set(a, offset);
+        offset += a.length;
+    }
+    return result;
+}
+/**
+ * Infer a (rows, cols) shape from a flat array length.
+ *
+ * Heuristic: find the factor pair closest to sqrt that gives a valid
+ * factorisation. Falls back to (1, length) for primes / small arrays.
+ */
+function inferShape(length) {
+    if (length <= 0)
+        return { rows: 0, cols: 0 };
+    if (length === 1)
+        return { rows: 1, cols: 1 };
+    const sqrt = Math.floor(Math.sqrt(length));
+    for (let r = sqrt; r >= 1; r--) {
+        if (length % r === 0) {
+            return { rows: r, cols: length / r };
+        }
+    }
+    return { rows: 1, cols: length };
+}
+// Export helpers for testing
+export { topKSingularValues, selectLayers, inferShape, cosineSimilarity, l2Distance };
+//# sourceMappingURL=paramesphere-engine.js.map