@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/trend/recompute.js

@@ -0,0 +1,15 @@
+// nodes/trend/recompute.js
+
+const recompute = function ( state ) {
+    // Ensure rate variance stays bounded
+    if ( state.rocVariance < 0 ) {
+        state.rocVariance = 0;
+    }
+
+    // No long-running accumulations that need recomputation
+    // Rate-based algorithm is inherently stable
+
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/trend/reset.js

@@ -0,0 +1,26 @@
+// nodes/trend/reset.js
+
+const reset = function ( state ) {
+    state.previousValue = null;
+
+    state.rocMean = 0;
+    state.rocVariance = 0;
+
+    if ( state.stats.accelerationHint ) {
+        state.rocSmoothedFast = 0;
+        state.accelerationHint = null;
+    }
+
+    state.samples = 0;
+    state.consistentSamples = 0;
+
+    state.previousTrend = 'learning';
+    state.trend = 'learning';
+    state.confidence = 0;
+    // Clear error suppression so next error episode is logged
+    state.tunableErrorLogged = false;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/trend/update.js

@@ -0,0 +1,93 @@
+// nodes/trend/update.js
+
+import { computeConfidence } from './compute-confidence.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    const xVal = msg[ state.x ];
+    // Reset on each update
+    state.inputValidationFailed = false;
+    // Handle faults gracefully: ensure their isolation
+    if ( !Number.isFinite( xVal ) ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    state.samples += 1;
+
+    if ( state.previousValue === null ) {
+        state.previousValue = xVal;
+        // This ensures the first roc value is a real one and not 0.
+        return state;
+    }
+
+    // Step 1: Lag(1) for roc
+    const roc = xVal - state.previousValue;
+    state.previousValue = xVal;
+
+    // Step 2: Track roc statistics
+    const rocResidual = roc - state.rocMean;
+    state.rocMean += ( state.rocAlpha * rocResidual );
+    state.rocVariance += ( state.rocAlpha * ( ( rocResidual * rocResidual ) - state.rocVariance ) );
+
+    // Step 3: Track roc at a faster roc for acceleration hint
+    if ( state.stats.accelerationHint ) {
+        state.rocSmoothedFast += ( state.accelAlpha * ( roc - state.rocSmoothedFast ) );
+    }
+
+    // Step 4: Classification
+    state.previousTrend = state.trend;
+
+    // Resolve rocThreshold tunable for this message
+    try {
+        // If tunable throws, last good value is retained.
+        state.rocThreshold = state.rocThresholdFn( msg );
+        if ( state.tunableErrorLogged ) state.tunableErrorLogged = false;
+    } catch ( error ) {
+        if ( !state.tunableErrorLogged ) {
+            state.tunableErrorLogged = true;
+            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+        }
+    }
+
+    if ( state.samples < state.warmupSamples ) {
+        state.trend = 'learning';
+    } else if ( Math.abs( state.rocMean ) < state.rocThreshold ) {
+        state.trend = 'stable';
+    } else {
+        state.trend = state.rocMean > 0 ? 'rising' : 'falling';
+    }
+
+    // Track consistency
+    if ( state.trend === state.previousTrend ) {
+        state.consistentSamples += 1;
+    } else {
+        state.consistentSamples = 0;
+    }
+
+    // Step 5: Confidence computation
+    state.confidence = computeConfidence( state );
+
+    // Step 6: Acceleration hint
+    if ( state.stats.accelerationHint && ( state.samples > ( state.warmupSamplesForAccel ) ) ) {
+        // fast > mean ⇒ likely_accelerating
+        const accelProxy = state.rocSmoothedFast - state.rocMean;
+
+        // Basic SNR & persistence gates
+        const passesSNR = state.snr >= 1.5;   // require decent roc SNR
+        const accelThreshold = 0.75 * state.rocThreshold;  // derive from current rocThreshold
+        const passesBand = Math.abs( accelProxy ) >= accelThreshold;  // ignore tiny curvature
+        const persistent = state.consistentSamples >= 3;    // brief dwell
+
+        if ( passesSNR && passesBand && persistent ) {
+            state.accelerationHint = ( accelProxy > 0 ) ? 'likely_accelerating' : 'likely_decelerating';
+        } else {
+            state.accelerationHint = null;
+        }
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/tw-stats/copy-from.js

@@ -0,0 +1,16 @@
+// nodes/tw-stats/copy-from.js
+
+/**
+ * Copies Pébay accumulators from source to destination.
+ * Used to snapshot live state before reset at window completion or flush.
+ */
+export const copyFrom = function ( source, destination ) {
+    destination.n   = source.n;
+    destination.M1  = source.M1;
+    destination.M2  = source.M2;
+    destination.M3  = source.M3;
+    destination.M4  = source.M4;
+    destination.min = source.min;
+    destination.max = source.max;
+    return destination;
+};

package/src/nodes/tw-stats/flush.js

@@ -0,0 +1,12 @@
+// nodes/tw-stats/flush.js
+
+/**
+ * Forces publication of incomplete window.
+ * Used for graceful shutdown or event-driven snapshots.
+ */
+const flush = function ( state ) {
+    state.flushLatched = true;
+    return true;
+}; // flush()
+
+export default flush;

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

@@ -0,0 +1,41 @@
+// nodes/tw-stats/index.js
+
+/**
+ * @fileoverview
+ * TW Stats — Tumbling window statistics with Pébay's numerically stable
+ * algorithm for incremental moment accumulation.
+ *
+ * ────────────────────────────────────────────────────────────────────────
+ * Replaces the two-node chain (momentsDigest → digestMoments) for the
+ * common case of computing statistics over count-based tumbling windows.
+ *
+ * Key properties:
+ * • O(1) memory per partition — no ring buffer; Pébay incremental accumulation
+ * • Selective moment accumulation — maxMoment (1–4) resolved at init from
+ *   demanded stats; if/then gating in update, not closures (100K-safe)
+ * • Deferred stat conversion — moment-to-stat formulas applied only in
+ *   publishTo on window completion or flush, not every update tick
+ * • Invalid samples skipped (not counted); window fills with valid samples only
+ * • Publishes on window completion or flush; scrubs to undefined on other ticks
+ * • Supports windowSize from 4 to 1,000,000
+ *
+ * ────────────────────────────────────────────────────────────────────────
+ * References
+ * [1] Pébay, P. (2008). Formulas for robust, one-pass parallel computation
+ *     of covariances and arbitrary-order statistical moments.
+ *     Sandia Report SAND2008-6212.
+ */
+
+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';
+export { default as flush } from './flush.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/tw-stats/init.js

@@ -0,0 +1,92 @@
+// nodes/tw-stats/init.js
+
+/**
+ * @fileoverview Initialization for twStats node.
+ *
+ * Resolves the selective accumulation tier (maxMoment 1–4) from demanded
+ * stats at init time. All allocations happen here; update() is zero-alloc.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+// Stats that require M2 accumulation
+const NEEDS_M2 = [ 'variance', 'stddev', 'cv', 'skew', 'kurtosis', 'rms', 'crestFactor' ];
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    const state = Object.create( null );
+
+    // Standard flags (all nodes)
+    state.inputValidationFailed = false;
+    state.disable = false;
+    state.pause = false;
+
+    // Preserve node's name — used for msg[name] = true on publish
+    state.name = spec.name;
+
+    // Input field name
+    state.x = spec.from.x;
+
+    // Resolve options (field-keyed support for windowSize)
+    const windowSizeSpec = resolveScalar( spec.windowSize, state.x );
+    state.windowSize = windowSizeSpec ?? introspect.DEFAULT_OPTIONS.windowSize;
+    state.biased = spec.biased || introspect.DEFAULT_OPTIONS.biased;
+    state.epsilon = spec.epsilon ?? introspect.DEFAULT_OPTIONS.epsilon;
+
+    // Copy stats config (Object.create(null) for clean prototype)
+    state.stats = Object.assign( Object.create( null ), spec.stats );
+
+    // Determine selective accumulation tier from demanded stats
+    const statsList = Object.keys( state.stats );
+    const needsM2 = statsList.some( ( s ) => NEEDS_M2.includes( s ) );
+    const needsM3 = statsList.includes( 'skew' ) || statsList.includes( 'kurtosis' );
+    const needsM4 = statsList.includes( 'kurtosis' );
+
+    if ( needsM4 ) {
+        state.maxMoment = 4;
+    } else if ( needsM3 ) {
+        state.maxMoment = 3;
+    } else if ( needsM2 ) {
+        state.maxMoment = 2;
+    } else {
+        state.maxMoment = 1;
+    }
+
+    state.needsMinMax = !!( state.stats.min || state.stats.max || state.stats.crestFactor );
+    state.needsRms = !!( state.stats.rms || state.stats.crestFactor );
+
+    // Pébay algorithm accumulators
+    state.n = 0;
+    state.M1 = 0;
+    state.M2 = 0;
+    state.M3 = 0;
+    state.M4 = 0;
+    state.min = Infinity;
+    state.max = -Infinity;
+
+    // Window management
+    state.currentCount = 0;
+
+    // Publish control
+    state.planPublish = false;
+    state.flushLatched = false;
+
+    // Snapshot: holds moments at window completion for publishTo to read
+    state.snapshot = Object.create( null );
+
+    // Pre-compute scrubKeys for efficient non-publish scrubbing
+    state.scrubKeys = [];
+    // eslint-disable-next-line guard-for-in
+    for ( const stat in state.stats ) {
+        state.scrubKeys.push( state.stats[ stat ].storeAs );
+    }
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

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

@@ -0,0 +1,171 @@
+// nodes/tw-stats/introspect.js
+
+/**
+ * @fileoverview Introspection module for twStats node.
+ *
+ * Tumbling window statistics: accumulates Pébay moments over a count-based
+ * window, publishes computed statistics (mean, variance, stddev, cv, skew,
+ * kurtosis, min, max, n) on window completion or flush.
+ *
+ * Selective accumulation: only the moments needed by demanded stats are
+ * computed on the hot path. The maxMoment tier (1–4) is resolved at init.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what statistics this node can compute */
+const SUPPORTED_STATS = [
+    'n',
+    'mean',
+    'variance',
+    'stddev',
+    'cv',
+    'skew',
+    'kurtosis',
+    'min',
+    'max',
+    'rms',
+    'crestFactor'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    n: 'Number of valid samples in the completed window',
+    mean: 'Arithmetic mean (first moment M1)',
+    variance: 'Sample variance: M2 / (n - 1) for unbiased, M2 / n for biased',
+    stddev: 'Sample standard deviation: sqrt(variance)',
+    cv: 'Coefficient of variation: stddev / |mean|',
+    skew: 'Population skewness: m3 / m2^1.5',
+    kurtosis: 'Population excess kurtosis: m4 / m2^2 - 3',
+    min: 'Minimum value across all samples in the window',
+    max: 'Maximum value across all samples in the window',
+    rms: 'Root mean square: sqrt(M2/n + M1²)',
+    crestFactor: 'Crest factor: peak / RMS — max(|min|, |max|) / rms'
+};
+
+/** 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 update processing while allowing publishTo to continue',
+    unpause: 'Resumes update processing after a pause',
+    flush: 'Forces immediate output of partial window'
+};
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Tumbling window statistics using Pébay\'s numerically stable algorithm',
+    features: [
+        'Configurable window-based aggregation (4 to 1,000,000 samples)',
+        'Selective moment accumulation: only computes moments needed by demanded stats',
+        'Deferred stat conversion: formulas applied only at publish time',
+        'Numerically stable incremental computation (Pébay 2008)',
+        'Invalid samples skipped without corrupting statistics',
+        'Flush support for graceful shutdown with partial windows',
+        'Zero allocations in hot path for maximum throughput',
+        'O(1) memory regardless of window size'
+    ]
+};
+
+/** The type of this node */
+const NODE_TYPE = 'TW Stats';
+
+// Attach static metadata once, from our constants by making a shallow copy.
+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 = {
+    windowSize: 100,
+    biased: false,
+    epsilon: 1e-12
+};
+
+// DSL Metadata for transpilation
+const DSL_METADATA = {
+    // 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'
+                }
+            }
+        },
+        windowSize: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.windowSize,
+            integer: true,
+            min: 4,
+            max: 1000000,
+            validator: validators.positiveInteger,
+            error: 'Window size must be a positive integer; minimum 4, maximum 1,000,000'
+        },
+        biased: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.biased
+        },
+        epsilon: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.epsilon,
+            min: 0,
+            error: 'Epsilon must be a non-negative number'
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        minLength: 1,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators (none needed for twStats)
+    crossFieldValidators: [],
+
+    // How to build the spec from DSL params
+    // 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/tw-stats/publish-to.js

@@ -0,0 +1,108 @@
+// nodes/tw-stats/publish-to.js
+
+/**
+ * @fileoverview TW Stats Publish — deferred stat conversion from snapshot.
+ *
+ * On publish ticks (window completion or flush): computes final statistics
+ * from the Pébay moment snapshot and writes them to the message.
+ *
+ * On non-publish ticks: scrubs all storeAs fields to undefined to prevent
+ * downstream from reading stale data.
+ *
+ * No publishNaN — invalid samples are skipped in update(); a flush snapshot
+ * planned in the prelude still publishes regardless of the current input.
+ */
+
+import { computeVariance, computeCV, computeSkew, computeKurtosis } from '../../core/utils/stats/formulas.js';
+
+/**
+ * Publish variance-dependent stats when m2 is above epsilon.
+ * Extracted to keep publishTo within nesting depth limits.
+ */
+const publishVarianceStats = function ( state, msg, s, n, m2 ) {
+    const variance = computeVariance( s.M2, n, state.biased );
+    const stddev = Math.sqrt( variance );
+    const stats = state.stats;
+    const eps = state.epsilon;
+
+    if ( stats.variance ) msg[ stats.variance.storeAs ] = variance;
+    if ( stats.stddev ) msg[ stats.stddev.storeAs ] = stddev;
+    if ( stats.cv ) msg[ stats.cv.storeAs ] = computeCV( stddev, s.M1, eps );
+    if ( stats.skew ) msg[ stats.skew.storeAs ] = computeSkew( s.M3, n, m2, eps );
+    if ( stats.kurtosis ) msg[ stats.kurtosis.storeAs ] = computeKurtosis( s.M4, n, m2, eps );
+}; // publishVarianceStats()
+
+/**
+ * Set all variance-dependent stats to NaN.
+ * Used when n < 2 or variance is not computable.
+ */
+const publishVarianceNaN = function ( stats, msg ) {
+    if ( stats.variance ) msg[ stats.variance.storeAs ] = NaN;
+    if ( stats.stddev ) msg[ stats.stddev.storeAs ] = NaN;
+    if ( stats.cv ) msg[ stats.cv.storeAs ] = NaN;
+    if ( stats.skew ) msg[ stats.skew.storeAs ] = NaN;
+    if ( stats.kurtosis ) msg[ stats.kurtosis.storeAs ] = NaN;
+}; // publishVarianceNaN()
+
+/**
+ * Set variance-dependent stats for near-zero variance (m2 < epsilon).
+ * Variance and stddev are 0; cv, skew, kurtosis degenerate.
+ */
+const publishVarianceZero = function ( stats, msg ) {
+    if ( stats.variance ) msg[ stats.variance.storeAs ] = 0;
+    if ( stats.stddev ) msg[ stats.stddev.storeAs ] = 0;
+    if ( stats.cv ) msg[ stats.cv.storeAs ] = NaN;
+    if ( stats.skew ) msg[ stats.skew.storeAs ] = 0;
+    if ( stats.kurtosis ) msg[ stats.kurtosis.storeAs ] = -3;
+}; // publishVarianceZero()
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    if ( state.planPublish ) {
+        const s = state.snapshot;
+        const n = s.n;
+        const stats = state.stats;
+
+        // Always-available stats
+        if ( stats.n ) msg[ stats.n.storeAs ] = n;
+        if ( stats.mean ) msg[ stats.mean.storeAs ] = s.M1;
+        if ( stats.min ) msg[ stats.min.storeAs ] = s.min;
+        if ( stats.max ) msg[ stats.max.storeAs ] = s.max;
+
+        // Variance-dependent stats (require maxMoment >= 2)
+        if ( state.maxMoment >= 2 ) {
+            if ( n >= 2 ) {
+                const m2 = s.M2 / n;
+                if ( m2 >= state.epsilon ) {
+                    publishVarianceStats( state, msg, s, n, m2 );
+                } else {
+                    publishVarianceZero( stats, msg );
+                }
+            } else {
+                publishVarianceNaN( stats, msg );
+            }
+        }
+
+        // Derived stats: RMS and crest factor (cold-path only, from existing accumulators)
+        if ( state.needsRms ) {
+            const rms = Math.sqrt( ( s.M2 / n ) + ( s.M1 * s.M1 ) );
+            if ( stats.rms ) msg[ stats.rms.storeAs ] = rms;
+            if ( stats.crestFactor ) {
+                const peak = Math.max( Math.abs( s.min ), Math.abs( s.max ) );
+                msg[ stats.crestFactor.storeAs ] = ( rms > state.epsilon ) ? ( peak / rms ) : NaN;
+            }
+        }
+
+        msg[ state.name ] = true;
+        return;
+    }
+
+    // Non-publish tick: scrub all storeAs fields to undefined
+    const keys = state.scrubKeys;
+    for ( let i = 0; i < keys.length; i += 1 ) {
+        msg[ keys[ i ] ] = undefined;
+    }
+}; // publishTo()
+
+export default publishTo;

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

@@ -0,0 +1,9 @@
+// nodes/tw-stats/recompute.js
+
+const recompute = function () {
+    // Pébay moments are computed incrementally using a numerically stable
+    // algorithm. No recomputation needed (no ring buffer to reconstruct from).
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,16 @@
+// nodes/tw-stats/reset.js
+
+const reset = function ( state ) {
+    state.n = 0;
+    state.M1 = 0;
+    state.M2 = 0;
+    state.M3 = 0;
+    state.M4 = 0;
+    state.min = Infinity;
+    state.max = -Infinity;
+    state.currentCount = 0;
+
+    return true;
+}; // reset()
+
+export default reset;