@winkjs/composer 0.0.2 → 0.4.0

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

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Initializes esMean node state from a validated spec.
+ *
+ * Derives the smoothing factor (alpha) from the configured half-life,
+ * pre-computes the MAD alpha for adaptive tracking (half-life × 1.5 to
+ * dampen flapping), and allocates all state properties up-front on a
+ * prototype-free object — no allocations occur on the hot path.
+ */
+
+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';
+
+const init = function ( spec ) {
+    // Validate against (updated) schema
+    validateSpec( spec, introspect );
+
+    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;
+
+    // Required
+    state.x = spec.from.x;
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // half-life based configuration (samples)
+    // Supports both direct: { halfLife: 20 } and field-keyed: { halfLife: { temp: 5, pressure: 20 } }
+    const halfLifeSpec = resolveScalar( spec.halfLife, state.x );
+    state.halfLife = ( typeof halfLifeSpec === 'number' ) ? halfLifeSpec : introspect.DEFAULT_OPTIONS.halfLife;
+
+    // Derive base alpha from half-life for hot-path math
+    state.alpha = halfLifeToAlpha( state.halfLife );
+    state.currentAlpha = state.alpha;
+
+    // New: adaptive half-life flag (renamed)
+    state.adaptiveHalfLife = !!spec.adaptiveHalfLife;
+
+    // Exponential smoothing of |innovation| (MAD-ish); alpha derived from main half-life
+    // Using a slightly longer half-life (×1.5) to avoid flapping under noise
+    state.madAlpha = halfLifeToAlpha( state.halfLife * 1.5 );
+    state.esAbsInnovation = null;
+
+    // State
+    state.esmValue = null;
+    state.isInitialized = false;
+    state.lastValue = null;
+
+    state.nodeType = introspect.getNodeType();
+    return state;
+}; // init()
+
+export default init;

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

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Single source of truth for esMean node metadata.
+ *
+ * Exports supported stats, control methods, capabilities, default options,
+ * and the DSL spec schema used by both validation (init-time) and
+ * transpilation (DSL → spec). All getters return defensive copies.
+ */
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'mean'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    mean: 'Exponentially Smoothed Mean'
+};
+
+/** 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 Mean';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes exponentially smoothed mean for smoothing time series data',
+    features: [
+        'Half-life based smoothing (samples) for intuitive tuning',
+        'Optional adaptive half-life based on absolute innovation (robust MAD-ish estimator)',
+        'Numerically stable update form'
+    ]
+};
+
+// 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() } );
+
+// Spec default values
+export const DEFAULT_OPTIONS = {
+    // ≈ alpha 0.2
+    halfLife: 3.1062837195053903
+};
+
+// 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'
+                }
+            }
+        },
+        halfLife: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.halfLife,
+            validator: composerValidators.halfLife,
+            error: 'halfLife must be > 0 and < 999999'
+        },
+        adaptiveHalfLife: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            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
+    crossFieldValidators: [],
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, x, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Copies the current EWMA estimate onto the message for
+ * downstream consumption. Propagates NaN when input validation has failed,
+ * ensuring downstream nodes see an explicit fault rather than stale data.
+ */
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    msg[ state.stats.mean.storeAs ] = state.esmValue;
+}; // publishTo()
+
+export default publishTo;

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

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Recompute handler for the esMean node (intentional no-op).
+ *
+ * EWMA cannot be recomputed without the full observation history. The
+ * incremental update form is already numerically stable and bounded by
+ * the input range, so precision drift is not a concern.
+ */
+
+const recompute = function () {
+    // It cannot be recomputed without full historical data.
+    // The incremental update form used is already numerically stable
+    // and bounded by input range, preventing unbounded error growth.
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Resets accumulated EWMA state to its pre-observation condition.
+ *
+ * Clears the estimate, initialization flag, adaptive innovation tracker, and
+ * last observed value. Restores currentAlpha to the base alpha derived at init,
+ * so the next observation seeds the estimate afresh.
+ */
+
+const reset = function ( state ) {
+    state.esmValue = null;
+    state.isInitialized = false;
+
+    // Restore base alpha (derived from half-life at init)
+    state.currentAlpha = state.alpha;
+
+    // New adaptive state
+    state.esAbsInnovation = null;
+
+    state.lastValue = null;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/es-mean/update.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Hot-path EWMA computation for the esMean node.
+ *
+ * Applies the numerically stable incremental form: esmValue += α·(x − esmValue).
+ * When adaptive half-life is enabled, alpha is modulated per-message based on
+ * surprise — |innovation| relative to a MAD-estimated σ (σ ≈ 1.2533·E[|inno|],
+ * the normal-equivalence relation). A bounded boost keeps alpha within [base, 0.95],
+ * preventing degeneration to passthrough. Zero allocations; all reads from state.
+ */
+
+// Sensible fixed constants (hot path reads only)
+const adaptGain = 0.2;     // sensitivity of alpha to surprise (bounded map)
+const epsilon = 1e-12;     // numerical floor
+
+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;
+    }
+
+    if ( state.isInitialized ) {
+        // Optional adaptive half-life
+        if ( state.adaptiveHalfLife ) {
+            // Innovation relative to current estimate
+            const innovation = xVal - state.esmValue;
+
+            // Exponential smoothing of |innovation| (MAD-ish); using precomputed alpha for hot path
+            const absInnovation = Math.abs( innovation );
+            state.esAbsInnovation = ( state.esAbsInnovation === null ) ?
+                absInnovation :
+                state.esAbsInnovation + ( state.madAlpha * ( absInnovation - state.esAbsInnovation ) );
+
+            // σ ≈ 1.2533 * E[ |innovation| ] (normal equivalence), robust & sqrt-free
+            const sigma = ( 1.2533 * state.esAbsInnovation ) + epsilon;
+
+            // Surprise (unitless)
+            const z = Math.abs( innovation ) / sigma;
+
+            // Bounded boost of alpha: base * ( 1 + gain * z / ( 1 + z ) )
+            const targetAlpha = state.alpha * ( 1 + ( adaptGain * ( z / ( 1 + z ) ) ) );
+
+            // Preserve Exponential smoothing behavior (never degenerate to passthrough)
+            state.currentAlpha = ( targetAlpha > 0.95 ) ? 0.95 : targetAlpha;
+        }
+
+        // Numerically stable update
+        state.esmValue += state.currentAlpha * ( xVal - state.esmValue );
+    } else {
+        // Initialize
+        state.esmValue = xVal;
+        state.isInitialized = true;
+
+        // Initialize MAD tracker lazily when adaptive is enabled
+        if ( state.adaptiveHalfLife ) {
+            state.esAbsInnovation = 0;
+        }
+    }
+
+    state.lastValue = xVal;
+    return state;
+}; // update()
+
+export default update;

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

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Barrel module for the es-pairwise-correlation node. Re-exports
+ * lifecycle methods (init, update, reset, recompute, publishTo), shared control
+ * signals (disable, enable, pause, unpause), and all introspection metadata.
+ */
+// nodes/es-pairwise-correlation/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-pairwise-correlation/init.js

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Initializes es-pairwise-correlation node state from a validated spec.
+ * Derives the smoothing factor (alpha) from the configured half-life, pre-allocates
+ * all buffers (means, variances, covariances, correlations) on a prototype-free
+ * object — no allocations occur on the hot path.
+ */
+// nodes/es-pairwise-correlation/init.js
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { halfLifeToAlpha, halfLifeToWarmupSamples } from '../../core/utils/half-life/index.js';
+
+const fisherZCapDefault = 0.9999;
+
+const init = function ( spec ) {
+    // Validate against updated schema (halfLife-based)
+    validateSpec( spec, introspect ); // uses specSchema from introspect.js
+
+    // 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;
+
+    // ── Configuration ────────────────────────────────────────────────────────────
+    // Input variables
+    state.x = spec.from.x;
+    state.n = state.x.length;
+    state.pairCount = ( state.n * ( state.n - 1 ) ) / 2;
+
+    // For publishing
+    state.varNames = state.x.slice( 0 );
+
+    // Output mappings
+    state.stats = spec.stats;  // guaranteed by validateSpec
+
+    // Half-life config (samples) → derive alpha for hot path
+    state.halfLife = spec.halfLife ?? introspect.DEFAULT_OPTIONS.halfLife;
+    state.alpha = halfLifeToAlpha( state.halfLife );
+
+    // Numerics
+    state.minVariance = spec.minVariance ?? introspect.DEFAULT_OPTIONS.minVariance;
+
+    // Warm-up: default to ~85% settled if not provided
+    state.minSamples = ( spec.minSamples === undefined ) ?
+        halfLifeToWarmupSamples( state.halfLife, 0.85 ) :
+        spec.minSamples;
+
+    // Fisher-Z toggle uses the same cap semantics as the pair node
+    state.fisherZCap = ( spec.fisherZT === true ) ? fisherZCapDefault : 1;
+
+    // ── State & preallocations (zero-alloc hot path) ─────────────────────────────
+    // Per-variable stats
+    state.means = new Float64Array( state.n );
+    state.variances = new Float64Array( state.n );
+
+    // Pairwise stats (upper triangle order)
+    state.covariances = new Float64Array( state.pairCount );
+    state.correlations = new Float64Array( state.pairCount );
+
+    // Optional Fisher-Z vector
+    if ( spec.fisherZT ) {
+        state.fisherZT = new Float64Array( state.pairCount );
+    }
+
+    // Workspaces
+    state.values = new Float64Array( state.n );
+    state.deltas = new Float64Array( state.n );
+
+    // O(1) variable index lookup
+    state.variableLookup = Object.create( null );
+    for ( let i = 0; i < state.n; i += 1 ) {
+        state.variableLookup[ state.x[ i ] ] = i;
+    }
+
+    // Optional static pair names for debugging/visualization (precomputed)
+    if ( spec.stats?.pairNames ) {
+        const pairNames = new Array( state.pairCount );
+        let idx = 0;
+        for ( let i = 0; i < state.n; i += 1 ) {
+            for ( let j = i + 1; j < state.n; j += 1 ) {
+                pairNames[ idx ] = `${state.x[ i ]}-${state.x[ j ]}`;
+                idx += 1;
+            }
+        }
+        state.pairNames = pairNames;
+    }
+
+    // Counters / identity
+    state.sampleCount = 0;
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

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

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Single source of truth for the es-pairwise-correlation node's
+ * supported stats, control methods, capabilities, default options, and DSL schema.
+ * All getters return defensive copies to prevent caller mutation.
+ */
+// nodes/es-pairwise-correlation/introspect.js
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'correlations',      // Raw correlation coefficients vector
+    'fisherZT',   // Fisher Z transformed correlations
+    'covariances',       // Raw covariances vector
+    'pairNames',        // Pair identifiers (e.g., "temp-pressure")
+    'varNames'           // Original input variable names
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    correlations: 'Pairwise correlation coefficients (upper triangle)',
+    fisherZT: 'Fisher Z transformed correlation values',
+    covariances: 'Pairwise covariances (upper triangle)',
+    pairNames: 'Labels identifying each variable pair',
+    varNames: 'Original variable names in order'
+};
+
+/** 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 Pairwise Correlation';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes all pairwise correlations between multiple variables using exponential smoothing',
+    features: [
+        'Single-pass correlation computation for up to 12 variables',
+        'Numerically stable exponentially smoothed (Welford-style) algorithm',
+        'Zero-allocation operation after initialization',
+        'Vector-native processing (no matrix overhead)',
+        'Cache-efficient memory layout',
+        'O(n²/2) optimal complexity for upper triangle',
+        'Fisher Z transformation support',
+        'Handles missing/invalid data gracefully',
+        'Half-life (samples) supported for intuitive tuning'
+    ]
+};
+
+// Introspection accessors (return safe copies)
+export const getSupportedStats = () => SUPPORTED_STATS.slice();
+export const getStatDescriptions = () => ( { ...STAT_DESCRIPTIONS } );
+export const getSupportedControlMethods = () => ( { ...SUPPORTED_CONTROL_METHODS } );
+export const getNodeType = () => NODE_TYPE;
+// Deep-enough copy: clone root object and clone the features array
+export const getCapabilities = () => ( { ...CAPABILITIES, features: CAPABILITIES.features.slice() } );
+
+/** Defaults (aligned with pair node) */
+export const DEFAULT_OPTIONS = {
+    // halfLife roughly equivalent to alpha ≈ 0.05
+    halfLife: 13.5,
+    minVariance: 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: 'array',
+                    required: true,
+                    minItems: 2,
+                    maxItems: 12,
+                    itemSchema: {
+                        type: 'string',
+                        validator: validators.noSpaces,
+                        error: 'Field names cannot contain spaces'
+                    }
+                }
+            }
+        },
+        halfLife: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.halfLife,
+            validator: composerValidators.halfLife,
+            error: 'halfLife must be > 0 and < 999999'
+        },
+        minSamples: {
+            type: 'number',
+            required: false,
+            default: 10,
+            integer: true,
+            min: 1,
+            validator: validators.positiveInteger,
+            error: 'Minimum samples must be a positive integer'
+        },
+        minVariance: {
+            type: 'number',
+            required: false,
+            default: 1e-12,
+            validator: validators.positive,
+            error: 'Minimum variance must be positive'
+        },
+        fisherZT: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        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
+    crossFieldValidators: [
+        {
+            fields: [ 'from.x' ],
+            validator: ( spec ) => {
+                const fields = spec.from.x;
+                const uniqueFields = new Set( fields );
+                return uniqueFields.size === fields.length;
+            },
+            error: 'Field names must be unique'
+        },
+        {
+            fields: [ 'fisherZT', 'stats.fisherZT' ],
+            validator: ( spec ) => {
+                // If fisherZT stat is requested, fisherZT must be enabled
+                if ( spec.stats && spec.stats.fisherZT ) {
+                    return spec.fisherZT === true;
+                }
+                return true; // No fisherZT stat requested, so no constraint
+            },
+            error: 'stats.fisherZT requires fisherZT to be enabled'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/es-pairwise-correlation/publish-to.js

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Copies the current pairwise correlation estimates, covariances,
+ * Fisher Z values, and/or pair labels onto the message for downstream consumption.
+ * Propagates NaN when input validation has failed; gates output until minSamples
+ * is reached.
+ */
+// nodes/es-pairwise-correlation/publish-to.js
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+    // Don't publish until we have reliable estimates
+    if ( state.sampleCount < state.minSamples ) {
+        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;