@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/emit-if/reset.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Reset function for emitIf node
+ *
+ * Resets statistics and state tracking.
+ */
+
+const reset = function ( state ) {
+    // Reset statistics
+    state.emissionCount = 0;
+    state.passCount = 0;
+    state.lastEmissionTime = null;
+    state.emissionErrors = 0;
+    state.lastEmissionError = null;
+    state.lastEmissionErrorCode = null;
+    state.firstEmissionError = null;
+    state.firstEmissionErrorCode = null;
+
+    // Reset state tracking
+    state.inErrorState = false;
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+    state.emitErrorLogged = false;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/emit-if/update.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Update function for emitIf node
+ *
+ * Hot path — evaluates user-supplied predicate and emits to external
+ * systems when true. Predicate errors are caught and tracked per-episode.
+ *
+ * Publishes unconditionally — no connectivity pre-check (ADR-018). The
+ * old isConnected() guard skipped publishes during MQTT disconnects, which
+ * kept messages OUT of the emitter's buffer: the exact loss buffering
+ * exists to prevent. (ADR-021 later replaced the on-disk offline store
+ * with an in-process buffer; the invariant is unchanged.) The emitter's
+ * { ok } return is the only truth
+ * the node consumes; a failure opens a loud episode (mirroring persistIf —
+ * the two output gates share one failure model).
+ */
+
+import { assertAnnotateReturn, emitStatusSignal, recordEmissionFailure, MALFORMED_RESULT_ERROR } from './helpers.js';
+
+const update = function ( state, msg ) {
+    // Always increment pass count for observability
+    state.passCount += 1;
+
+    // Early exit if emitter not available (mirrors persistIf's storage guard)
+    if ( !state.emitter ) {
+        return state;
+    }
+
+    // Evaluate predicate, then shape the payload when emitting. Annotate
+    // mirrors persistIf: both run inside one try, so predicate and
+    // annotate share the same error episode (tracking, log suppression,
+    // recovery).
+    try {
+        const shouldEmit = state.predicate( msg );
+        let data = msg;
+        if ( shouldEmit && state.annotate ) {
+            data = state.annotate( msg );
+            // A flow-authoring bug (non-object return) throws here, into
+            // this node's error episode — never published as-is (mirrors
+            // persistIf).
+            assertAnnotateReturn( data );
+        }
+
+        if ( shouldEmit ) {
+            // Per the ADR-018 sink return contract, the emitter answers
+            // { ok: true } on success or
+            // { ok: false, error: { code, message } } on failure.
+            const result = state.emitter.publishNow( state.topic, data );
+
+            if ( result && result.ok ) {
+                state.emissionCount += 1;
+                state.lastEmissionTime = Date.now();
+                // Recovery: a successful publish closes the failure episode.
+                if ( state.emitErrorLogged ) state.emitErrorLogged = false;
+            } else {
+                // A malformed result (no object at all, or ok:false with no
+                // error) counts as a failure with the static fallback error,
+                // so a non-conforming adapter can neither fail silently
+                // nor throw out of the hot path.
+                recordEmissionFailure( state, ( result && result.error ) || MALFORMED_RESULT_ERROR );
+            }
+        }
+
+        // Clear error state on successful evaluation
+        if ( state.inErrorState ) {
+            state.inErrorState = false;
+            emitStatusSignal( state, false, 'recovered' );
+        }
+        // Recovery: clear log-suppression flag on success
+        if ( state.predicateErrorLogged ) state.predicateErrorLogged = false;
+    } catch ( error ) {
+        // Handle predicate errors (semantic — emits status signal)
+        if ( !state.inErrorState ) {
+            state.inErrorState = true;
+            emitStatusSignal( state, true, error.message );
+        }
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.predicateErrorLogged ) {
+            state.predicateErrorLogged = true;
+            console.error( `WinkComposer/emitIf: predicate threw exception: ${error.message}` );
+        }
+        state.emissionErrors += 1;
+        state.lastEmissionError = error.message;
+        // Predicate exceptions are emit-if-internal, not part of the
+        // ADR-018 adapter err.code vocabulary. Clear the code so the two
+        // fields stay in sync (a stale code from a prior publish failure
+        // would mislead readers).
+        state.lastEmissionErrorCode = null;
+    }
+
+    return state;
+}; // update()
+
+export default update;

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

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

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Initializes es-correlation node state from a validated spec.
+ * Derives the smoothing factor (alpha) from the configured half-life,
+ * pre-allocates all state properties on a prototype-free object — no
+ * allocations occur on the hot path.
+ */
+// nodes/es-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 fisherZCap = 0.9999;
+
+const init = function ( spec ) {
+    // Validate against (updated) schema that uses halfLife
+    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;
+
+    // Required fields for correlation computation
+    state.x = spec.from.x;
+    state.y = spec.from.y;
+
+    // Config copy for output field mapping
+    state.stats = spec.stats;
+
+    // Half-life based configuration (samples). If not provided, fall back to introspect defaults.
+    state.halfLife = spec.halfLife ?? introspect.DEFAULT_OPTIONS.halfLife;
+
+    // Derive alpha from half-life for hot-path math
+    state.alpha = halfLifeToAlpha( state.halfLife );
+
+    // Variance floor (retain existing default behavior if unspecified)
+    state.minVariance = spec.minVariance ?? introspect.DEFAULT_OPTIONS.minVariance;
+
+    // Warmup: if not provided, compute minSamples to reach ~95% settled response
+    // Using HL→samples mapping keeps early estimates reliable without manual tuning
+    state.minSamples = spec.minSamples ?? halfLifeToWarmupSamples( state.halfLife, 0.85 );
+
+    // Optional Fisher Z transformation enablement; keep existing cap behavior
+    state.fisherZCap = ( spec.fisherZT === true ) ? fisherZCap : 1;
+
+    // Core state variables for numerically stable ES computation.
+    // Using Welford-style incremental updates with exponential weighting.
+    // Means will be initialized with first observation (x₀, y₀) in update() for
+    // faster convergence and more natural variance evolution.
+    state.meanX = 0;
+    state.meanY = 0;
+    state.varianceX = 0;
+    state.varianceY = 0;
+    state.covariance = 0;
+
+    // Output values.
+    state.correlation = 0;
+    state.r2 = 0;               // Coefficient of determination (correlation squared)
+    state.fisherZT = 0;
+
+    // Track sample count for initialization phase.
+    state.sampleCount = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

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

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Single source of truth for the es-correlation node's supported
+ * stats, control methods, capabilities, default options, and DSL schema.
+ * All getters return defensive copies to prevent caller mutation.
+ */
+// nodes/es-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 = [
+    'correlation',
+    'covariance',
+    'r2',
+    'fisherZT'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    correlation: 'Pearson correlation coefficient between x and y using EWMA, range [-1, 1]',
+    covariance: 'Covariance between x and y using EWMA',
+    r2: 'Coefficient of determination (r-squared), proportion of variance explained, range [0, 1]',
+    fisherZT: 'Fisher Z transformation of correlation to normalize it'
+};
+
+/** 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 Correlation';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes exponentially smoothed correlation and covariance between two variables',
+    features: [
+        'Numerically stable Welford-style algorithm',
+        'Exponential weighting for dynamic tracking',
+        'Handles near-zero variance gracefully',
+        'Supports correlation, covariance, and r² output',
+        'Half-life (samples) supported for intuitive tuning'
+    ]
+};
+
+// 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 = {
+    // halfLife roughly equivalent to alpha = 0.05
+    halfLife: 13.5,
+    minVariance: 1e-12
+};
+
+// 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'
+                },
+                y: {
+                    type: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        halfLife: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.halfLife,
+            validator: composerValidators.halfLife,
+            error: 'halfLife must be > 0 and < 999999'
+        },
+        minVariance: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.minVariance,
+            min: 0,
+            validator: validators.positive,
+            error: 'Minimum variance must be positive'
+        },
+        minSamples: {
+            type: 'number',
+            required: false,
+            default: 10,
+            integer: true,
+            min: 1,
+            validator: validators.positiveInteger,
+            error: 'Minimum samples must be a positive integer'
+        },
+        fisherZT: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        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'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'from.x', 'from.y' ],
+            validator: ( spec ) => spec.from.x !== spec.from.y,
+            error: 'from.x and from.y must be different fields'
+        },
+        {
+            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'
+        }
+    ],
+
+    // Build spec from DSL parameters
+    // Pattern: NAME_X_Y_OUTPUTS_OPTIONS -> (name, x, y, stats, options)
+    buildSpec: ( name, x, y, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x, y },
+        stats,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Copies the current correlation, covariance, r², and/or Fisher Z
+ * estimates onto the message for downstream consumption. Propagates NaN when
+ * input validation has failed; gates output until minSamples is reached.
+ */
+// nodes/es-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;
+    }
+    // Publish only after minimum samples collected to avoid unreliable early estimates.
+    // Align with update/recompute behavior by allowing publish at minSamples as well.
+    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;

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

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Numerical stability handler for the es-correlation node.
+ * Floors negative variances (floating-point guard), recomputes correlation
+ * from current accumulated state, and clamps the result to [-1, 1].
+ */
+// nodes/es-correlation/recompute.js
+
+const recompute = function ( state ) {
+    // It doesn't store historical data, so traditional recomputation isn't possible.
+    // Instead, we perform numerical stability checks and adjustments.
+
+    // Check for numerical issues in variances.
+    // Variance should never be negative due to our update formula,
+    // but floating point errors could theoretically cause issues.
+    if ( state.varianceX < 0 ) {
+        state.varianceX = 0;
+    }
+    if ( state.varianceY < 0 ) {
+        state.varianceY = 0;
+    }
+
+    // Recompute correlation from current statistics to ensure consistency.
+    if ( state.sampleCount >= state.minSamples ) {
+        const stdX = Math.sqrt( Math.max( state.varianceX, state.minVariance ) );
+        const stdY = Math.sqrt( Math.max( state.varianceY, state.minVariance ) );
+
+        state.correlation = state.covariance / ( stdX * stdY );
+
+        // Ensure correlation is in valid range.
+        if ( state.correlation > 1 ) {
+            state.correlation = 1;
+        } else if ( state.correlation < -1 ) {
+            state.correlation = -1;
+        }
+
+        // Check for NaN (could occur if both variances are zero despite protection).
+        if ( Number.isNaN( state.correlation ) ) {
+            state.correlation = 0;
+        }
+
+        // Keep derived stats consistent with adjusted correlation.
+        if ( state.stats && state.stats.r2 ) {
+            state.r2 = state.correlation * state.correlation;
+        }
+        if ( ( state.fisherZCap < 1 ) && state.stats && state.stats.fisherZT ) {
+            const r = state.correlation;
+            const capped = ( r > state.fisherZCap ) ? state.fisherZCap :
+                ( r < -state.fisherZCap ? -state.fisherZCap : r );
+            state.fisherZT = 0.5 * Math.log( ( 1 + capped ) / ( 1 - capped ) );
+        }
+    }
+
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Resets all statistical accumulators (means, variances,
+ * covariance) and output values (correlation, r², fisherZT) to their
+ * initial state, allowing the node to restart computation from scratch.
+ */
+// nodes/es-correlation/reset.js
+
+const reset = function ( state ) {
+    // Reset all statistical accumulators to initial values.
+    state.meanX = 0;
+    state.meanY = 0;
+    state.varianceX = 0;
+    state.varianceY = 0;
+    state.covariance = 0;
+
+    // Reset output values.
+    state.correlation = 0;
+    state.r2 = 0;
+    state.fisherZT = 0;
+
+    // Reset sample counter.
+    state.sampleCount = 0;
+
+    return true;
+}; // reset()
+
+export default reset;

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

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Hot-path exponentially weighted moving correlation computation.
+ * Uses a Welford-style incremental algorithm with exponential decay on means,
+ * variance, and covariance. Optionally computes r² and Fisher Z transform.
+ * Zero allocations; all reads/writes via the pre-allocated state object.
+ */
+// nodes/es-correlation/update.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;
+    }
+
+    const yVal = msg[ state.y ];
+    // Handle faults gracefully: ensure their isolation
+    if ( !Number.isFinite( yVal ) ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Special handling for first observation:
+    // Initialize means with the first sample for faster convergence
+    // and more natural variance evolution; no variance/covariance yet.
+    if ( state.sampleCount === 0 ) {
+        state.meanX = xVal;
+        state.meanY = yVal;
+        state.sampleCount = 1;  // count the first sample
+        return state;
+    }
+
+    // Increment sample count for subsequent observations.
+    state.sampleCount += 1;
+
+    // Compute deltas BEFORE updating means (critical for numerical stability).
+    const deltaX = xVal - state.meanX;
+    const deltaY = yVal - state.meanY;
+
+    // Exponentially smoothed update for means.
+    state.meanX += state.alpha * deltaX;
+    state.meanY += state.alpha * deltaY;
+
+    // Numerically stable variance and covariance updates.
+    // Note: We use the NEW mean for the second delta computation.
+
+    // Update covariance using the stable formula.
+    // cov += α * δx * (y - mean_y_new)
+    state.covariance += state.alpha * ( ( deltaX * ( yVal - state.meanY ) ) - state.covariance );
+
+    // If neither correlation nor r2 is requested, we can skip the
+    // variance/correlation path (keeps hot path lean). r2 implies
+    // correlation at compute-time even if not explicitly requested.
+    if ( ( state.stats.correlation === undefined ) && ( state.stats.r2 === undefined ) ) {
+        return state;
+    }
+
+    // Update variances using the stable formula.
+    // var_x += α * δx * (x - mean_x_new)
+    state.varianceX += state.alpha * ( ( deltaX * ( xVal - state.meanX ) ) - state.varianceX );
+    state.varianceY += state.alpha * ( ( deltaY * ( yVal - state.meanY ) ) - state.varianceY );
+
+    // Compute correlation only after minimum samples collected.
+    if ( state.sampleCount >= state.minSamples ) {
+        // Compute standard deviations with minimum variance protection.
+        const stdX = Math.sqrt( Math.max( state.varianceX, state.minVariance ) );
+        const stdY = Math.sqrt( Math.max( state.varianceY, state.minVariance ) );
+
+        // Compute correlation coefficient.
+        // The max() ensures we never divide by zero.
+        state.correlation = state.covariance / ( stdX * stdY );
+
+        // Clamp correlation to [-1, 1] to handle numerical errors.
+        // Due to floating point arithmetic, we might get values like 1.0000000002.
+        if ( state.correlation >= 1 ) {
+            // Note: fisherZCap currently couples clamping and Z-publish enabling.
+            // We will decouple this in a subsequent Fisher-Z clarity pass.
+            state.correlation = state.fisherZCap;
+        } else if ( state.correlation <= -1 ) {
+            state.correlation = -state.fisherZCap;
+        }
+
+        // Compute r² (coefficient of determination) at publish time (if required)
+        // by squaring the correlation. r² is always in [0,1] and has a direct
+        // percentage interpretation (model quality, sensor agreement, etc).
+        if ( state.stats && state.stats.r2 ) {
+            state.r2 = state.correlation * state.correlation;
+        }
+
+        // Compute Fisher Z transform only when:
+        // - feature enabled (fisherZCap < 1), and
+        // - output mapping provided in stats.fisherZ.
+        if ( ( state.fisherZCap < 1 ) && state.stats && state.stats.fisherZT ) {
+            // Guard against |r| → 1 to prevent infinities; clamp with current cap.
+            const r = state.correlation;
+            const capped = ( r > state.fisherZCap ) ? state.fisherZCap : ( r < -state.fisherZCap ? -state.fisherZCap : r );
+            state.fisherZT = 0.5 * Math.log( ( 1 + capped ) / ( 1 - capped ) );
+        }
+    }
+
+    return state;
+}; // update()
+
+export default update;

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

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