@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/es-pairwise-correlation/recompute.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Numerical stability handler for the es-pairwise-correlation node.
+ * Floors negative variances (floating-point guard), recomputes all pairwise
+ * correlations from current accumulated state, clamps results, and re-derives
+ * Fisher Z transforms when enabled.
+ */
+// nodes/es-pairwise-correlation/recompute.js
+
+const recompute = function ( state ) {
+    // Recompute correlations from current statistics
+    // This ensures numerical consistency and fixes any accumulated errors
+
+    const {
+        n, variances, covariances, correlations,
+        minVariance, fisherZCap, pairCount
+    } = state;
+
+    // Step 1: Ensure variances are non-negative (fix numerical errors)
+    for ( let i = 0; i < n; i += 1 ) {
+        if ( variances[ i ] < 0 ) {
+            variances[ i ] = 0;
+        }
+    }
+
+    // Step 2: Recompute all correlations using direct nested loops
+    let idx = 0;
+    for ( let i = 0; i < n; i += 1 ) {
+        // Pre-compute variance for variable i with protection
+        const varX = Math.max( variances[ i ], minVariance );
+        const stdX = Math.sqrt( varX );
+
+        for ( let j = i + 1; j < n; j += 1 ) {
+            // Pre-compute variance for variable j with protection
+            const varY = Math.max( variances[ j ], minVariance );
+            const stdY = Math.sqrt( varY );
+
+            // Compute correlation from covariance
+            const cov = covariances[ idx ];
+            correlations[ idx ] = cov / ( stdX * stdY );
+
+            // Ensure valid range [-1, 1] with Fisher Z cap if applicable
+            if ( correlations[ idx ] >= fisherZCap ) {
+                correlations[ idx ] = fisherZCap;
+            } else if ( correlations[ idx ] <= -fisherZCap ) {
+                correlations[ idx ] = -fisherZCap;
+            } else if ( Number.isNaN( correlations[ idx ] ) ) {
+                // Handle edge case where both variances were zero
+                correlations[ idx ] = 0;
+            }
+
+            idx += 1;
+        }
+    }
+
+    // Step 3: Recompute Fisher Z transformation if present
+    if ( state.fisherZT ) {
+        for ( let i = 0; i < pairCount; i += 1 ) {
+            const r = correlations[ i ];
+            // Fisher Z: 0.5 * ln((1+r)/(1-r))
+            // Note: r is already clamped to [-fisherZCap, fisherZCap]
+            // so we're guaranteed (1+r)/(1-r) > 0
+            state.fisherZT[ i ] = 0.5 * Math.log( ( 1 + r ) / ( 1 - r ) );
+        }
+    }
+
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/es-pairwise-correlation/reset.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Resets all statistical accumulators (means, variances,
+ * covariances, correlations) and output values (fisherZT) to their initial
+ * state, allowing the node to restart computation from scratch.
+ */
+// nodes/es-pairwise-correlation/reset.js
+
+const reset = function ( state ) {
+    // Reset all statistics to zero
+    state.means.fill( 0 );
+    state.variances.fill( 0 );
+    state.covariances.fill( 0 );
+    state.correlations.fill( 0 );
+
+    if ( state.fisherZT ) {
+        state.fisherZT.fill( 0 );
+    }
+
+    // Reset sample counter
+    state.sampleCount = 0;
+
+    // Clear workspace arrays
+    state.values.fill( 0 );
+    state.deltas.fill( 0 );
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/es-pairwise-correlation/update.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Hot-path exponentially weighted pairwise correlation computation.
+ * Uses a Welford-style incremental algorithm with exponential decay on means,
+ * variance, and covariance for all n*(n-1)/2 variable pairs. Zero allocations;
+ * all reads/writes via the pre-allocated state object.
+ */
+// nodes/es-pairwise-correlation/update.js
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    const {
+        x, n, alpha, minVariance,
+        values, deltas, means, variances, covariances,
+        correlations, fisherZCap, pairCount
+    } = state;
+
+    state.inputValidationFailed = false;
+    // Extract and validate & Handle faults gracefully: ensure their isolation
+    for ( let i = 0; i < n; i += 1 ) {
+        const val = msg[ x[ i ] ];
+        if ( val === undefined || val === null ) {
+            // Signals publishing NaN for all demanded `stats` in publishTo.
+            state.inputValidationFailed = true;
+            return state;
+        }
+        values[ i ] = val;
+        if ( !Number.isFinite( values[ i ] ) ) {
+            // Signals publishing NaN for all demanded `stats` in publishTo.
+            state.inputValidationFailed = true;
+            return state;
+        }
+    }
+
+    // Initialize on first sample: set means and count, no variance/covariance yet.
+    if ( state.sampleCount === 0 ) {
+        for ( let i = 0; i < n; i += 1 ) {
+            means[ i ] = values[ i ];
+        }
+        state.sampleCount = 1;
+        return state;
+    }
+
+    // Increment sample count for subsequent observations.
+    state.sampleCount += 1;
+
+    // Update deltas, means, variances
+    for ( let i = 0; i < n; i += 1 ) {
+        deltas[ i ] = values[ i ] - means[ i ];
+        means[ i ] += alpha * deltas[ i ];
+        variances[ i ] += alpha * ( ( deltas[ i ] * ( values[ i ] - means[ i ] ) ) - variances[ i ] );
+    }
+
+    // Update covariances and correlations
+    let idx = 0;
+    for ( let i = 0; i < n; i += 1 ) {
+        for ( let j = i + 1; j < n; j += 1 ) {
+            // Update covariance
+            covariances[ idx ] += alpha * ( ( deltas[ i ] * ( values[ j ] - means[ j ] ) ) - covariances[ idx ] );
+
+            // Compute correlation if ready
+            if ( state.sampleCount >= state.minSamples ) {
+                const varX = Math.max( variances[ i ], minVariance );
+                const varY = Math.max( variances[ j ], minVariance );
+                correlations[ idx ] = covariances[ idx ] / Math.sqrt( varX * varY );
+
+                // Clamp
+                if ( correlations[ idx ] >= fisherZCap ) {
+                    correlations[ idx ] = fisherZCap;
+                } else if ( correlations[ idx ] <= -fisherZCap ) {
+                    correlations[ idx ] = -fisherZCap;
+                }
+            }
+
+            idx += 1;
+        }
+    }
+
+    // Fisher Z transform if needed
+    if ( state.fisherZT && state.sampleCount >= state.minSamples ) {
+        for ( let i = 0; i < pairCount; i += 1 ) {
+            const r = correlations[ i ];
+            state.fisherZT[ i ] = 0.5 * Math.log( ( 1 + r ) / ( 1 - r ) );
+        }
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/es-stats/index.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Barrel module for the esStats node.
+ *
+ * Re-exports the standard node lifecycle methods (init, update, reset,
+ * recompute, publishTo), shared control signals (disable, enable, pause,
+ * unpause), and all introspection metadata.
+ */
+// nodes/es-stats/index.js
+
+export { default as init } from './init.js';
+export { default as update } from './update.js';
+export { default as reset } from './reset.js';
+export { default as recompute } from './recompute.js';
+export { default as publishTo } from './publish-to.js';
+// Direct imports for common control functions
+export { default as disable } from '../../core/utils/node/disable.js';
+export { default as enable } from '../../core/utils/node/enable.js';
+export { default as pause } from '../../core/utils/node/pause.js';
+export { default as unpause } from '../../core/utils/node/unpause.js';
+// Re-export everything from introspection.js
+export * from './introspect.js';

package/src/nodes/es-stats/init.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Initializes esStats node state from a validated spec.
+ *
+ * Derives the exponential smoothing factor (alpha) from halfLife, pre-allocates
+ * all statistical accumulators on a prototype-free state object, and determines
+ * which computation paths (Welford for mean/variance, envelope for floor/ceiling)
+ * are required by the requested stats. All allocation happens here; the hot path
+ * is zero-allocation.
+ */
+// nodes/es-stats/init.js
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { halfLifeToAlpha } from '../../core/utils/half-life/index.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+/**
+ * Initialize ES Stats node with comprehensive streaming statistics.
+ *
+ * @param {Object} spec - Node specification
+ * @returns {Object} Initial state for statistics computation
+ */
+const init = function ( spec ) {
+    // Validate against schema
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+    // Standard input parameter health flag during update: false means healthy
+    state.inputValidationFailed = false;
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Input field
+    state.x = spec.from.x;
+
+    // Config copy for output field mapping
+    const stats = spec.stats;
+    state.stats = stats;
+
+    // Half-life configuration with defaults
+    // Supports both direct: { halfLife: 20 } and field-keyed: { halfLife: { temp: 5, pressure: 20 } }
+    const defaults = introspect.DEFAULT_OPTIONS;
+    const halfLifeSpec = resolveScalar( spec.halfLife, state.x );
+    state.halfLife = halfLifeSpec ?? defaults.halfLife;
+
+    // Convert half-life to alpha for hot-path efficiency
+    state.alpha = halfLifeToAlpha( state.halfLife );
+    state.decay = 1 - state.alpha;  // Pre-compute for efficiency
+
+    // Biased/unbiased estimator choice
+    state.biased = spec.biased ?? defaults.biased;
+
+    // Constants
+    state.EPS = 1e-12;
+    state.snrDbCap = 60;
+    state.cvLarge = 1e6;
+
+    // Core statistics (Welford's algorithm)
+    state.mean = 0;
+    state.m2 = 0;          // Sum of squared deviations
+    state.variance = 0;
+    state.stdev = 0;
+
+    // Envelope statistics (leaky min/max)
+    state.floor = 0;
+    state.ceiling = 0;
+    state.envelope = 0;
+    state.mid = 0;
+
+    // Signal quality metrics
+    state.snrDB = 0;
+    state.cv = 0;
+
+    // Current value scores
+    state.zScore = 0;
+    state.envScore = 0;
+
+    // Warmup normalization for unbiased mode
+    state.weightSum = 0;   // Sum of exponentially smoothed weights: 1 - (1 - alpha)^t
+
+    // Sample counter
+    state.sampleCount = 0;
+
+    // Determine computation paths needed
+    state.needsWelford = stats.mean !== undefined ||
+                        stats.variance !== undefined ||
+                        stats.stdev !== undefined ||
+                        stats.snrDB !== undefined ||
+                        stats.cv !== undefined ||
+                        stats.zScore !== undefined;
+
+    state.needsEnvelope = stats.floor !== undefined ||
+                         stats.ceiling !== undefined ||
+                         stats.envelope !== undefined ||
+                         stats.mid !== undefined ||
+                         stats.envScore !== undefined;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/es-stats/introspect.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Single source of truth for esStats node metadata.
+ *
+ * Exports supported stats (11 metrics across Welford, envelope, and
+ * signal-quality categories), human-readable stat descriptions, control
+ * methods, node capabilities, default options, and the DSL spec schema
+ * with validators. All getter functions return defensive copies.
+ */
+// nodes/es-stats/introspect.js
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    // Core Statistics (Welford's algorithm)
+    'mean',
+    'variance',
+    'stdev',
+
+    // Envelope Statistics (Leaky min/max)
+    'floor',
+    'ceiling',
+    'envelope',
+    'mid',
+
+    // Signal Quality Metrics
+    'snrDB',
+    'cv',
+
+    // Current Value Scores (computed per sample)
+    'zScore',
+    'envScore'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    mean: 'Exponentially smoothed mean',
+    variance: 'Exponentially smoothed variance (Welford\'s algorithm)',
+    stdev: 'Square root of variance',
+    floor: 'Recent minimum with exponential decay (envelope follower)',
+    ceiling: 'Recent maximum with exponential decay (envelope follower)',
+    envelope: 'Signal envelope width (ceiling - floor)',
+    mid: 'Envelope midpoint ((floor + ceiling) / 2)',
+    snrDB: 'Signal-to-noise ratio in dB (20*log10(|mean|/stdev))',
+    cv: 'Coefficient of variation (stdev/|mean|)',
+    zScore: 'Normalized deviation of current value ((x - mean)/stdev)',
+    envScore: 'Envelope-normalized score ((x - mid)/(envelope/2))'
+};
+
+/** Control methods available for triggers */
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears accumulated state and restarts computation',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+/** The type of this node */
+const NODE_TYPE = 'ES Stats';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Comprehensive exponentially weighted statistics for streaming signals',
+    features: [
+        'Numerically stable Welford\'s algorithm for mean/variance',
+        'Leaky envelope tracking (floor/ceiling) with fast attack/slow release',
+        'Signal quality metrics (SNR, CV)',
+        'Real-time anomaly scores (z-score, envelope score)',
+        'No allocations in hot path',
+        'Single half-life for consistent weighting'
+    ]
+};
+
+// Export functions for accessing metadata
+export const getSupportedStats = () => SUPPORTED_STATS.slice();
+export const getStatDescriptions = () => ( { ...STAT_DESCRIPTIONS } );
+export const getSupportedControlMethods = () => ( { ...SUPPORTED_CONTROL_METHODS } );
+export const getNodeType = () => NODE_TYPE;
+export const getCapabilities = () => ( { ...CAPABILITIES, features: CAPABILITIES.features.slice() } );
+
+export const DEFAULT_OPTIONS = {
+    halfLife: 10,
+    biased: false
+};
+
+// DSL Metadata for transpilation
+const DSL_METADATA = {
+    // Full spec schema for validation
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE
+        },
+        name: {
+            type: 'string',
+            required: true,
+            validator: validators.identifier,
+            error: 'Name must be a valid identifier'
+        },
+        from: {
+            type: 'object',
+            required: true,
+            properties: {
+                x: {
+                    type: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        halfLife: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.halfLife,
+            validator: composerValidators.halfLife,
+            error: 'halfLife must be > 0 and < 999999'
+        },
+        biased: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.biased
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Build spec from DSL parameters
+    // Pattern: NAME_X_OUTPUTS_OPTIONS -> (name, x, stats, options)
+    buildSpec: ( name, x, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/es-stats/publish-to.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Copies requested esStats statistics onto the message for
+ * downstream consumption.
+ *
+ * Propagates NaN for all configured stats when input validation has failed.
+ * Gates output until the warmup period (3 samples) is complete to ensure
+ * statistical meaningfulness. Iterates only over stats declared in the spec;
+ * zero allocations on the hot path.
+ */
+// nodes/es-stats/publish-to.js
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+/**
+ * Publish computed statistics to message.
+ * Only publishes stats that were requested and after warmup.
+ *
+ * @param {Object} state - Node state with computed statistics
+ * @param {Object} msg - Message to annotate with outputs
+ */
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+    // Only publish after at least 3 samples for statistical meaning
+    if ( state.sampleCount < 3 ) {
+        return;
+    }
+
+    // Iterate only over configured stats
+    const stats = state.stats;
+    for ( const statName in stats ) {
+        if ( Object.prototype.hasOwnProperty.call( stats, statName ) ) {
+            msg[ stats[ statName ].storeAs ] = state[ statName ];
+        }
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/es-stats/recompute.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Numerical stability handler for the esStats node.
+ *
+ * Floors negative m2 and variance to zero, corrects inverted floor/ceiling
+ * order, and recomputes variance from m2 using the appropriate normalization
+ * (biased or unbiased). On catastrophic NaN/Infinity in critical state fields,
+ * triggers a full reset. Since exponentially weighted statistics have inherently
+ * bounded state (each update is a weighted blend, not unbounded accumulation),
+ * consistency corrections suffice — no sample buffer is available for full
+ * recomputation.
+ */
+// nodes/es-stats/recompute.js
+
+import reset from './reset.js';
+
+/**
+ * Recompute statistics from current state to ensure numerical consistency.
+ * Handles numerical drift in long-running streams.
+ *
+ * @param {Object} state - Node state
+ * @returns {boolean} Always true (successful recomputation)
+ */
+const recompute = function ( state ) {
+    // Ensure m2 is non-negative (second moment)
+    if ( state.m2 < 0 ) {
+        state.m2 = 0;
+    }
+
+    // Ensure variance is non-negative
+    if ( state.variance < 0 ) {
+        state.variance = 0;
+        state.stdev = 0;
+    }
+
+    const stats = state.stats;
+    // Recompute variance from m2 to ensure consistency
+    if ( state.sampleCount >= 2 && stats.variance !== undefined ) {
+        if ( state.biased ) {
+            state.variance = state.m2;
+        } else {
+            const w = state.weightSum;
+            state.variance = ( w > 1e-12 ) ? ( state.m2 / w ) : state.m2;
+        }
+        state.stdev = Math.sqrt( state.variance );
+    }
+
+    // Ensure envelope consistency
+    if ( stats.envelope !== undefined ) {
+        // Floor should not exceed ceiling
+        if ( state.floor > state.ceiling ) {
+            const temp = state.floor;
+            state.floor = state.ceiling;
+            state.ceiling = temp;
+        }
+
+        // Recompute derived envelope metrics
+        state.envelope = state.ceiling - state.floor;
+        state.mid = ( state.floor + state.ceiling ) * 0.5;
+    }
+
+    // Check for NaN and reset if found
+    if ( !Number.isFinite( state.mean ) ||
+         !Number.isFinite( state.variance ) ||
+         !Number.isFinite( state.floor ) ||
+         !Number.isFinite( state.ceiling ) ) {
+        // Catastrophic numerical failure - reset
+        reset( state );
+        return true;
+    }
+
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/es-stats/reset.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Resets all esStats accumulated state to its pre-observation
+ * condition.
+ *
+ * Clears mean, m2, variance, stdev, envelope metrics, signal-quality scores,
+ * weightSum, and sampleCount. Configuration (alpha, decay, halfLife, biased,
+ * stats, computation-path flags) is preserved so the next observation seeds
+ * the estimate afresh. Returns true per ADR-004 control-signal contract.
+ */
+// nodes/es-stats/reset.js
+
+/**
+ * Reset all statistical accumulators to initial state.
+ * Called by control signals to restart statistics tracking.
+ *
+ * @param {Object} state - Node state to reset
+ * @returns {boolean} Always true (ADR-004)
+ */
+const reset = function ( state ) {
+    // Reset core statistics
+    state.mean = 0;
+    state.m2 = 0;
+    state.variance = 0;
+    state.stdev = 0;
+
+    // Reset envelope statistics
+    state.floor = 0;
+    state.ceiling = 0;
+    state.envelope = 0;
+    state.mid = 0;
+
+    // Reset signal quality
+    state.snrDB = 0;
+    state.cv = 0;
+
+    // Reset current value scores
+    state.zScore = 0;
+    state.envScore = 0;
+
+    // Reset weight accumulator
+    state.weightSum = 0;
+
+    // Reset sample counter
+    state.sampleCount = 0;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/es-stats/update-envelope.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Leaky envelope follower with fast-attack / slow-release
+ * semantics for the esStats node.
+ *
+ * New extremes are adopted immediately (fast attack); non-extreme values
+ * relax floor/ceiling toward the current value at rate alpha (slow release).
+ * Computes envelope width (ceiling - floor), midpoint, and envScore
+ * (normalized distance from midpoint, unclamped to preserve severity).
+ *
+ * Zero allocations; all reads/writes via the pre-allocated state object.
+ */
+// nodes/es-stats/update-envelope.js
+
+const updateEnvelope = function ( state, xVal ) {
+    // Envelope Score: Normalized distance from range midpoint
+    // Score = (value - mid) / halfRange; 0=center, ±1=bounds, >1=outside
+    // Computed BEFORE update to detect range breakouts
+    // Unclamped to preserve severity (e.g., score=3 means 3x beyond normal)
+    if ( state.stats.envScore ) {
+        const halfEnv = state.envelope * 0.5;
+        state.envScore = ( halfEnv > state.EPS ) ?
+            ( ( xVal - state.mid ) / halfEnv ) : 0;
+        // optional clamp:
+        // state.envScore = Math.max( -1, Math.min( 1, state.envScore ) );
+    }
+
+    // NOW update envelope with fast-attack/slow-release
+    if ( xVal < state.floor ) {
+        state.floor = xVal;
+    } else {
+        state.floor += ( state.alpha * ( xVal - state.floor ) );
+    }
+
+    if ( xVal > state.ceiling ) {
+        state.ceiling = xVal;
+    } else {
+        state.ceiling -= ( state.alpha * ( state.ceiling - xVal ) );
+    }
+
+    state.envelope = state.ceiling - state.floor;
+    state.mid = ( state.floor + state.ceiling ) * 0.5;
+}; // updateEnvelope()
+
+export default updateEnvelope;