agentic-qe 3.7.21 → 3.8.0

package/dist/integrations/ruvector/sona-wrapper.d.ts

@@ -8,6 +8,7 @@
  * @module integrations/ruvector/sona-wrapper
  */
 import type { RLState, RLAction, DomainName } from '../rl-suite/interfaces.js';
+import { SONAThreeLoopEngine, type ThreeLoopConfig, type AdaptationResult, type ConsolidationResult, type PeerState, type EWCMetrics } from './sona-three-loop.js';
 /**
  * Pattern types supported by QE SONA (extends @ruvector/sona with QE specifics)
  */
@@ -136,6 +137,9 @@ export declare class QESONA {
     private adaptationTimes;
     private cacheHits;
     private totalAdaptations;
+    private threeLoopEngine;
+    private fisherPersistFn;
+    private fisherDomain;
     constructor(config?: Partial<QESONAConfig>);
     /**
      * Adapt pattern based on context - leverages @ruvector/sona's fast pattern matching
@@ -259,6 +263,98 @@ export declare class QESONA {
      * Get maximum adaptation time
      */
     private maxAdaptationTime;
+    /**
+     * Initialize the three-loop coordination engine.
+     *
+     * The three-loop engine adds:
+     * - Instant MicroLoRA adaptation per request (<100us)
+     * - Background EWC++ consolidation to prevent forgetting
+     * - Cross-agent state synchronization
+     *
+     * When available, delegates MicroLoRA and background learning to the
+     * native @ruvector/sona engine for true rank-1 LoRA operations.
+     *
+     * This is an additive enhancement; all existing QESONA methods continue
+     * to work the same way with or without the three-loop engine.
+     *
+     * @param config - Optional three-loop configuration overrides
+     */
+    initThreeLoopEngine(config?: Partial<ThreeLoopConfig>): void;
+    /**
+     * Get the three-loop engine instance.
+     * Returns null if not initialized via initThreeLoopEngine().
+     */
+    getThreeLoopEngine(): SONAThreeLoopEngine | null;
+    /**
+     * Perform instant MicroLoRA adaptation for a request.
+     * Delegates to the three-loop engine's instant loop.
+     *
+     * @param requestFeatures - Feature vector for the current request
+     * @returns Adaptation result, or null if three-loop engine not initialized
+     */
+    instantAdapt(requestFeatures: number[]): AdaptationResult | null;
+    /**
+     * Record the outcome of a request for REINFORCE-style gradient estimation.
+     * Delegates to the three-loop engine's recordOutcome().
+     *
+     * Must be called after instantAdapt() with the reward signal.
+     *
+     * @param reward - Scalar reward (e.g., 1.0 for success, -1.0 for failure, 0.0 for neutral)
+     * @param requestIndex - Optional requestIndex from AdaptationResult for matching
+     */
+    recordOutcome(reward: number, requestIndex?: number): void;
+    /**
+     * Run background consolidation cycle.
+     * Delegates to the three-loop engine's background loop.
+     *
+     * **Important**: This method performs synchronous SQLite writes (Fisher matrix
+     * persistence via better-sqlite3) when the persistence callback is set.
+     * Call from a background timer or idle callback, NOT from the request hot path.
+     *
+     * @returns Consolidation result, or null if three-loop engine not initialized
+     */
+    backgroundConsolidate(): ConsolidationResult | null;
+    /**
+     * Set the Fisher matrix persistence callback and domain.
+     *
+     * When set, `backgroundConsolidate()` automatically persists Fisher state
+     * to SQLite after each consolidation or task boundary detection.
+     *
+     * @param persistFn - Callback that writes Fisher data to SQLite
+     *   (typically PersistentSONAEngine.saveFisherMatrix.bind(engine))
+     * @param domain - Domain identifier for the Fisher state
+     */
+    setFisherPersistence(persistFn: (domain: string, fisher: Float32Array, optimal: Float32Array, base: Float32Array, meta: {
+        taskBoundaries: number;
+        consolidationCycles: number;
+        requestCount: number;
+        ewcLambda: number;
+    }) => void, domain: string): void;
+    /**
+     * Synchronize with peer agents.
+     * Delegates to the three-loop engine's coordination loop.
+     *
+     * @param peerStates - Peer states to synchronize with
+     */
+    syncWithPeers(peerStates: PeerState[]): void;
+    /**
+     * Get EWC++ metrics for monitoring.
+     *
+     * @returns EWC metrics, or null if three-loop engine not initialized
+     */
+    getEWCMetrics(): EWCMetrics | null;
+    /**
+     * Check if background consolidation is due.
+     */
+    shouldConsolidate(): boolean;
+    /**
+     * Get local peer state for sharing with other agents.
+     */
+    getLocalPeerState(peerId: string, domain: string): PeerState | null;
+    /**
+     * Check if the three-loop engine is initialized.
+     */
+    isThreeLoopEnabled(): boolean;
     /**
      * Verify performance target
      */
@@ -273,6 +369,7 @@ export declare class QESONA {
         }>;
     }>;
 }
+export type { AdaptationResult, ConsolidationResult, PeerState, EWCMetrics, ThreeLoopConfig, } from './sona-three-loop.js';
 /**
  * Create a QE SONA instance with default configuration
  */

package/dist/integrations/ruvector/sona-wrapper.js

@@ -10,6 +10,7 @@
 import { randomUUID } from 'crypto';
 import { SonaEngine } from '@ruvector/sona';
 import { secureRandom } from '../../shared/utils/crypto-random.js';
+import { SONAThreeLoopEngine, } from './sona-three-loop.js';
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -137,6 +138,9 @@ export class QESONA {
     adaptationTimes = [];
     cacheHits = 0;
     totalAdaptations = 0;
+    threeLoopEngine = null;
+    fisherPersistFn = null;
+    fisherDomain = 'default';
     constructor(config = {}) {
         this.config = { ...DEFAULT_QE_SONA_CONFIG, ...config };
         // Initialize @ruvector/sona engine with config
@@ -577,6 +581,149 @@ export class QESONA {
             return 0;
         return Math.max(...this.adaptationTimes);
     }
+    // ========================================================================
+    // Three-Loop Engine (MicroLoRA + EWC++ + Coordination)
+    // ========================================================================
+    /**
+     * Initialize the three-loop coordination engine.
+     *
+     * The three-loop engine adds:
+     * - Instant MicroLoRA adaptation per request (<100us)
+     * - Background EWC++ consolidation to prevent forgetting
+     * - Cross-agent state synchronization
+     *
+     * When available, delegates MicroLoRA and background learning to the
+     * native @ruvector/sona engine for true rank-1 LoRA operations.
+     *
+     * This is an additive enhancement; all existing QESONA methods continue
+     * to work the same way with or without the three-loop engine.
+     *
+     * @param config - Optional three-loop configuration overrides
+     */
+    initThreeLoopEngine(config) {
+        this.threeLoopEngine = new SONAThreeLoopEngine({
+            dimension: this.config.embeddingDim ?? 384,
+            microLoraLr: this.config.microLoraLr ?? 0.001,
+            ewcLambda: this.config.ewcLambda ?? 1000.0,
+            ...config,
+        }, this.engine);
+    }
+    /**
+     * Get the three-loop engine instance.
+     * Returns null if not initialized via initThreeLoopEngine().
+     */
+    getThreeLoopEngine() {
+        return this.threeLoopEngine;
+    }
+    /**
+     * Perform instant MicroLoRA adaptation for a request.
+     * Delegates to the three-loop engine's instant loop.
+     *
+     * @param requestFeatures - Feature vector for the current request
+     * @returns Adaptation result, or null if three-loop engine not initialized
+     */
+    instantAdapt(requestFeatures) {
+        if (!this.threeLoopEngine)
+            return null;
+        return this.threeLoopEngine.instantAdapt(requestFeatures);
+    }
+    /**
+     * Record the outcome of a request for REINFORCE-style gradient estimation.
+     * Delegates to the three-loop engine's recordOutcome().
+     *
+     * Must be called after instantAdapt() with the reward signal.
+     *
+     * @param reward - Scalar reward (e.g., 1.0 for success, -1.0 for failure, 0.0 for neutral)
+     * @param requestIndex - Optional requestIndex from AdaptationResult for matching
+     */
+    recordOutcome(reward, requestIndex) {
+        if (!this.threeLoopEngine)
+            return;
+        this.threeLoopEngine.recordOutcome(reward, requestIndex);
+    }
+    /**
+     * Run background consolidation cycle.
+     * Delegates to the three-loop engine's background loop.
+     *
+     * **Important**: This method performs synchronous SQLite writes (Fisher matrix
+     * persistence via better-sqlite3) when the persistence callback is set.
+     * Call from a background timer or idle callback, NOT from the request hot path.
+     *
+     * @returns Consolidation result, or null if three-loop engine not initialized
+     */
+    backgroundConsolidate() {
+        if (!this.threeLoopEngine)
+            return null;
+        const result = this.threeLoopEngine.backgroundConsolidate();
+        // Persist Fisher matrix after consolidation when a persistence callback is set
+        if (result && (result.consolidated || result.taskBoundaryDetected) && this.fisherPersistFn) {
+            try {
+                this.threeLoopEngine.persistFisher(this.fisherPersistFn, this.fisherDomain);
+            }
+            catch (err) {
+                // Persistence failures must not break the consolidation path
+                console.warn('[QESONA] Fisher persistence failed:', err instanceof Error ? err.message : err);
+            }
+        }
+        return result;
+    }
+    /**
+     * Set the Fisher matrix persistence callback and domain.
+     *
+     * When set, `backgroundConsolidate()` automatically persists Fisher state
+     * to SQLite after each consolidation or task boundary detection.
+     *
+     * @param persistFn - Callback that writes Fisher data to SQLite
+     *   (typically PersistentSONAEngine.saveFisherMatrix.bind(engine))
+     * @param domain - Domain identifier for the Fisher state
+     */
+    setFisherPersistence(persistFn, domain) {
+        this.fisherPersistFn = persistFn;
+        this.fisherDomain = domain;
+    }
+    /**
+     * Synchronize with peer agents.
+     * Delegates to the three-loop engine's coordination loop.
+     *
+     * @param peerStates - Peer states to synchronize with
+     */
+    syncWithPeers(peerStates) {
+        if (!this.threeLoopEngine)
+            return;
+        this.threeLoopEngine.syncWithPeers(peerStates);
+    }
+    /**
+     * Get EWC++ metrics for monitoring.
+     *
+     * @returns EWC metrics, or null if three-loop engine not initialized
+     */
+    getEWCMetrics() {
+        if (!this.threeLoopEngine)
+            return null;
+        return this.threeLoopEngine.getEWCMetrics();
+    }
+    /**
+     * Check if background consolidation is due.
+     */
+    shouldConsolidate() {
+        if (!this.threeLoopEngine)
+            return false;
+        return this.threeLoopEngine.shouldConsolidate();
+    }
+    /**
+     * Get local peer state for sharing with other agents.
+     */
+    getLocalPeerState(peerId, domain) {
+        if (!this.threeLoopEngine)
+            return null;
+        return this.threeLoopEngine.getLocalPeerState(peerId, domain);
+    }
+    /**
+     * Check if the three-loop engine is initialized.
+     */
+    isThreeLoopEnabled() {
+        return this.threeLoopEngine !== null;
+    }
     /**
      * Verify performance target
      */
@@ -608,9 +755,6 @@ export class QESONA {
         };
     }
 }
-// ============================================================================
-// Factory Functions
-// ============================================================================
 /**
  * Create a QE SONA instance with default configuration
  */

package/dist/integrations/ruvector/spectral-math.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Spectral Graph Theory Utilities
+ *
+ * Mathematical primitives for spectral analysis of graph structures.
+ * Provides Laplacian construction, power-iteration eigenvalue approximation,
+ * effective resistance estimation, and coherence scoring.
+ *
+ * These utilities are used by the HNSW Health Monitor to assess the
+ * structural health of HNSW index graphs without requiring native
+ * ruvector-coherence.
+ *
+ * @module integrations/ruvector/spectral-math
+ */
+/**
+ * Build the graph Laplacian from an adjacency list.
+ * L = D - A where D is the degree matrix and A is the adjacency matrix.
+ *
+ * Returns the Laplacian as a dense matrix (suitable for small graphs).
+ * For large graphs, we use the adjacency list directly with power iteration.
+ */
+export declare function buildLaplacian(adjacency: number[][], n: number): Float64Array[];
+/**
+ * Multiply Laplacian (in adjacency list form) by a vector.
+ * L * v = D*v - A*v
+ * This avoids materializing the full Laplacian matrix.
+ */
+export declare function laplacianMultiply(adjacency: number[][], v: Float64Array): Float64Array;
+/**
+ * Compute the L2 norm of a vector.
+ */
+export declare function vectorNorm(v: Float64Array): number;
+/**
+ * Normalize a vector in-place.
+ */
+export declare function normalizeInPlace(v: Float64Array): void;
+/**
+ * Remove the component of v along the direction of u (projection).
+ * v = v - (v . u) * u
+ * Assumes u is normalized.
+ */
+export declare function deflateVector(v: Float64Array, u: Float64Array): void;
+/**
+ * Approximate the Fiedler value (second smallest eigenvalue of L)
+ * using power iteration on L with deflation of the trivial eigenvector.
+ *
+ * The trivial eigenvector of L is the all-ones vector (eigenvalue = 0).
+ * We deflate it out and use power iteration to find the smallest
+ * non-trivial eigenvalue.
+ *
+ * Since power iteration finds the LARGEST eigenvalue, we use the shift-
+ * invert approach: we run power iteration on (lambda_max * I - L) to
+ * find the second smallest eigenvalue of L.
+ *
+ * @param adjacency - Adjacency list
+ * @param n - Number of nodes
+ * @param maxIter - Maximum iterations
+ * @param tol - Convergence tolerance
+ * @returns Approximate Fiedler value
+ */
+export declare function approximateFiedlerValue(adjacency: number[][], n: number, maxIter?: number, tol?: number): number;
+/**
+ * Estimate the spectral gap: difference between the second smallest
+ * and smallest eigenvalues of the Laplacian.
+ *
+ * For a connected graph, the smallest eigenvalue is 0, so the spectral
+ * gap equals the Fiedler value.
+ */
+export declare function approximateSpectralGap(adjacency: number[][], n: number, maxIter?: number, tol?: number): number;
+/**
+ * Estimate the average effective resistance between sampled node pairs.
+ *
+ * Effective resistance between nodes i and j is:
+ *   R_ij = (e_i - e_j)^T * L^+ * (e_i - e_j)
+ * where L^+ is the pseudo-inverse of the Laplacian.
+ *
+ * We approximate this by using the spectral decomposition:
+ *   R_ij = sum_{k>=2} (1/lambda_k) * (v_k[i] - v_k[j])^2
+ *
+ * For a lightweight check, we approximate using only the Fiedler eigenvector
+ * and value, which gives the dominant contribution.
+ *
+ * @param adjacency - Adjacency list
+ * @param n - Number of nodes
+ * @param sampleSize - Number of pairs to sample
+ * @param fiedlerValue - Pre-computed Fiedler value (pass to avoid recomputation)
+ * @returns Average effective resistance estimate
+ */
+export declare function estimateEffectiveResistance(adjacency: number[][], n: number, sampleSize?: number, fiedlerValue?: number): number;
+/**
+ * Compute a combined coherence score from spectral metrics.
+ *
+ * Combines Fiedler value, spectral gap, and effective resistance into
+ * a single 0-1 score where 1 = perfectly healthy and 0 = critically unhealthy.
+ *
+ * @param fiedler - Fiedler value
+ * @param spectralGap - Spectral gap
+ * @param resistance - Average effective resistance
+ * @returns Coherence score in [0, 1]
+ */
+export declare function computeCoherenceScore(fiedler: number, spectralGap: number, resistance: number): number;
+//# sourceMappingURL=spectral-math.d.ts.map

package/dist/integrations/ruvector/spectral-math.js

@@ -0,0 +1,254 @@
+/**
+ * Spectral Graph Theory Utilities
+ *
+ * Mathematical primitives for spectral analysis of graph structures.
+ * Provides Laplacian construction, power-iteration eigenvalue approximation,
+ * effective resistance estimation, and coherence scoring.
+ *
+ * These utilities are used by the HNSW Health Monitor to assess the
+ * structural health of HNSW index graphs without requiring native
+ * ruvector-coherence.
+ *
+ * @module integrations/ruvector/spectral-math
+ */
+// ============================================================================
+// Laplacian Construction
+// ============================================================================
+/**
+ * Build the graph Laplacian from an adjacency list.
+ * L = D - A where D is the degree matrix and A is the adjacency matrix.
+ *
+ * Returns the Laplacian as a dense matrix (suitable for small graphs).
+ * For large graphs, we use the adjacency list directly with power iteration.
+ */
+export function buildLaplacian(adjacency, n) {
+    const L = Array.from({ length: n }, () => new Float64Array(n));
+    for (let i = 0; i < n; i++) {
+        const degree = adjacency[i].length;
+        L[i][i] = degree; // Diagonal = degree
+        for (const j of adjacency[i]) {
+            L[i][j] = -1; // Off-diagonal = -1 for each edge
+        }
+    }
+    return L;
+}
+// ============================================================================
+// Linear Algebra Helpers
+// ============================================================================
+/**
+ * Multiply Laplacian (in adjacency list form) by a vector.
+ * L * v = D*v - A*v
+ * This avoids materializing the full Laplacian matrix.
+ */
+export function laplacianMultiply(adjacency, v) {
+    const n = v.length;
+    const result = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const degree = adjacency[i].length;
+        result[i] = degree * v[i]; // D * v
+        for (const j of adjacency[i]) {
+            result[i] -= v[j]; // -A * v
+        }
+    }
+    return result;
+}
+/**
+ * Compute the L2 norm of a vector.
+ */
+export function vectorNorm(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++)
+        sum += v[i] * v[i];
+    return Math.sqrt(sum);
+}
+/**
+ * Normalize a vector in-place.
+ */
+export function normalizeInPlace(v) {
+    const norm = vectorNorm(v);
+    if (norm > 0) {
+        for (let i = 0; i < v.length; i++)
+            v[i] /= norm;
+    }
+}
+/**
+ * Remove the component of v along the direction of u (projection).
+ * v = v - (v . u) * u
+ * Assumes u is normalized.
+ */
+export function deflateVector(v, u) {
+    let dot = 0;
+    for (let i = 0; i < v.length; i++)
+        dot += v[i] * u[i];
+    for (let i = 0; i < v.length; i++)
+        v[i] -= dot * u[i];
+}
+// ============================================================================
+// Eigenvalue Approximation
+// ============================================================================
+/**
+ * Approximate the Fiedler value (second smallest eigenvalue of L)
+ * using power iteration on L with deflation of the trivial eigenvector.
+ *
+ * The trivial eigenvector of L is the all-ones vector (eigenvalue = 0).
+ * We deflate it out and use power iteration to find the smallest
+ * non-trivial eigenvalue.
+ *
+ * Since power iteration finds the LARGEST eigenvalue, we use the shift-
+ * invert approach: we run power iteration on (lambda_max * I - L) to
+ * find the second smallest eigenvalue of L.
+ *
+ * @param adjacency - Adjacency list
+ * @param n - Number of nodes
+ * @param maxIter - Maximum iterations
+ * @param tol - Convergence tolerance
+ * @returns Approximate Fiedler value
+ */
+export function approximateFiedlerValue(adjacency, n, maxIter = 100, tol = 1e-6) {
+    if (n <= 1)
+        return 0;
+    if (n === 2) {
+        // For 2 nodes: Fiedler = number of edges between them
+        return adjacency[0].includes(1) ? 2 : 0;
+    }
+    // The trivial eigenvector of L: normalized all-ones
+    const trivial = new Float64Array(n).fill(1 / Math.sqrt(n));
+    // First, estimate lambda_max using a few power iterations on L
+    let maxVec = new Float64Array(n);
+    for (let i = 0; i < n; i++)
+        maxVec[i] = Math.random() - 0.5;
+    deflateVector(maxVec, trivial);
+    normalizeInPlace(maxVec);
+    let lambdaMax = 0;
+    for (let iter = 0; iter < 30; iter++) {
+        const Lv = laplacianMultiply(adjacency, maxVec);
+        deflateVector(Lv, trivial);
+        lambdaMax = vectorNorm(Lv);
+        if (lambdaMax > 0) {
+            for (let i = 0; i < n; i++)
+                maxVec[i] = Lv[i] / lambdaMax;
+        }
+    }
+    if (lambdaMax < tol)
+        return 0; // Disconnected or trivial graph
+    // Now use power iteration on (lambdaMax * I - L) to find the
+    // eigenvector corresponding to the LARGEST eigenvalue of (lambdaMax*I - L),
+    // which corresponds to the SMALLEST non-trivial eigenvalue of L.
+    let v = new Float64Array(n);
+    for (let i = 0; i < n; i++)
+        v[i] = Math.random() - 0.5;
+    deflateVector(v, trivial);
+    normalizeInPlace(v);
+    let eigenvalue = 0;
+    for (let iter = 0; iter < maxIter; iter++) {
+        // Compute (lambdaMax * I - L) * v = lambdaMax * v - L * v
+        const Lv = laplacianMultiply(adjacency, v);
+        const shifted = new Float64Array(n);
+        for (let i = 0; i < n; i++) {
+            shifted[i] = lambdaMax * v[i] - Lv[i];
+        }
+        // Deflate the trivial eigenvector
+        deflateVector(shifted, trivial);
+        const norm = vectorNorm(shifted);
+        if (norm < tol)
+            break;
+        const newEigenvalue = norm;
+        for (let i = 0; i < n; i++)
+            v[i] = shifted[i] / norm;
+        if (Math.abs(newEigenvalue - eigenvalue) < tol)
+            break;
+        eigenvalue = newEigenvalue;
+    }
+    // The Fiedler value is lambdaMax - eigenvalue of (lambdaMax*I - L)
+    const fiedler = lambdaMax - eigenvalue;
+    return Math.max(0, fiedler);
+}
+/**
+ * Estimate the spectral gap: difference between the second smallest
+ * and smallest eigenvalues of the Laplacian.
+ *
+ * For a connected graph, the smallest eigenvalue is 0, so the spectral
+ * gap equals the Fiedler value.
+ */
+export function approximateSpectralGap(adjacency, n, maxIter = 100, tol = 1e-6) {
+    // For the Laplacian, lambda_1 = 0 always (connected or not)
+    // So spectral gap = lambda_2 - lambda_1 = Fiedler value
+    return approximateFiedlerValue(adjacency, n, maxIter, tol);
+}
+// ============================================================================
+// Effective Resistance
+// ============================================================================
+/**
+ * Estimate the average effective resistance between sampled node pairs.
+ *
+ * Effective resistance between nodes i and j is:
+ *   R_ij = (e_i - e_j)^T * L^+ * (e_i - e_j)
+ * where L^+ is the pseudo-inverse of the Laplacian.
+ *
+ * We approximate this by using the spectral decomposition:
+ *   R_ij = sum_{k>=2} (1/lambda_k) * (v_k[i] - v_k[j])^2
+ *
+ * For a lightweight check, we approximate using only the Fiedler eigenvector
+ * and value, which gives the dominant contribution.
+ *
+ * @param adjacency - Adjacency list
+ * @param n - Number of nodes
+ * @param sampleSize - Number of pairs to sample
+ * @param fiedlerValue - Pre-computed Fiedler value (pass to avoid recomputation)
+ * @returns Average effective resistance estimate
+ */
+export function estimateEffectiveResistance(adjacency, n, sampleSize = 50, fiedlerValue) {
+    if (n <= 1)
+        return 0;
+    const fiedler = fiedlerValue ?? approximateFiedlerValue(adjacency, n);
+    if (fiedler < 1e-10)
+        return Infinity; // Disconnected graph
+    // For a well-connected graph with Fiedler value lambda_2,
+    // the average effective resistance is approximately n / (n * lambda_2)
+    // = 1 / lambda_2 for a regular graph.
+    // For a more accurate estimate, we use the trace formula:
+    //   sum of all R_ij = n * sum_{k>=2} 1/lambda_k
+    // We approximate by assuming eigenvalues are distributed uniformly
+    // between lambda_2 and lambda_max ~ 2 * max_degree.
+    const maxDeg = Math.max(...adjacency.map(a => a.length), 1);
+    const lambdaMax = 2 * maxDeg;
+    // Approximate: eigenvalues roughly uniform in [fiedler, lambdaMax]
+    // Average 1/lambda over this range:
+    // integral from fiedler to lambdaMax of (1/x) dx / (lambdaMax - fiedler)
+    // = ln(lambdaMax/fiedler) / (lambdaMax - fiedler)
+    const avgInvLambda = Math.log(lambdaMax / fiedler) / (lambdaMax - fiedler);
+    // Average resistance over random pairs is approximately:
+    // 2 * avgInvLambda (two endpoints contribute)
+    const avgResistance = 2 * avgInvLambda;
+    return Math.max(0, avgResistance);
+}
+// ============================================================================
+// Coherence Score
+// ============================================================================
+/**
+ * Compute a combined coherence score from spectral metrics.
+ *
+ * Combines Fiedler value, spectral gap, and effective resistance into
+ * a single 0-1 score where 1 = perfectly healthy and 0 = critically unhealthy.
+ *
+ * @param fiedler - Fiedler value
+ * @param spectralGap - Spectral gap
+ * @param resistance - Average effective resistance
+ * @returns Coherence score in [0, 1]
+ */
+export function computeCoherenceScore(fiedler, spectralGap, resistance) {
+    // Fiedler component: sigmoid-like scaling
+    // Score approaches 1 when fiedler >> threshold, 0 when fiedler << threshold
+    const fiedlerScore = 1 - Math.exp(-fiedler / 0.05);
+    // Spectral gap component
+    const gapScore = 1 - Math.exp(-spectralGap / 0.5);
+    // Resistance component: lower resistance = healthier
+    // Use inverse scaling: score = 1 / (1 + resistance/threshold)
+    const resistanceScore = resistance === Infinity
+        ? 0
+        : 1 / (1 + resistance / 5.0);
+    // Weighted combination
+    const score = 0.4 * fiedlerScore + 0.3 * gapScore + 0.3 * resistanceScore;
+    return Math.max(0, Math.min(1, score));
+}
+//# sourceMappingURL=spectral-math.js.map