@winkjs/composer 0.0.2 → 0.4.1

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

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Exponentially weighted Welford update for mean, variance,
+ * stdev, and derived signal-quality metrics (SNR, CV, zScore).
+ *
+ * Uses the numerically stable two-pass delta form:
+ *   delta  = x - mean;  mean += alpha * delta;
+ *   delta2 = x - mean;  m2   = decay * m2 + alpha * delta * delta2
+ *
+ * The "unbiased" variance is normalized as m2/weightSum. This intentionally
+ * diverges from the pandas ewm().var(bias=False) Bessel-type correction;
+ * both converge as n -> infinity (weightSum -> 1). See golden-truth-es-stats.py
+ * for cross-validation details.
+ *
+ * Zero allocations; all reads/writes via the pre-allocated state object.
+ */
+// nodes/es-stats/update-welford.js
+
+const updateWelford = function ( state, xVal ) {
+    state.weightSum = ( state.decay * state.weightSum ) + state.alpha;
+    if ( state.weightSum > 1 ) state.weightSum = 1; // defensive clamp against drift
+
+    // Z-Score: How many standard deviations away from established mean?
+    // Computed BEFORE update to detect anomalies in incoming value
+    // Uses pre-update stats to preserve causality in anomaly detection
+    if ( state.stats.zScore ) {
+        if ( state.stdev > state.EPS ) {
+            // Use current baseline
+            state.zScore = ( xVal - state.mean ) / state.stdev;
+        } else {
+            state.zScore = 0;
+        }
+    }
+
+    // NOW incorporate this value into running statistics
+    const delta = xVal - state.mean;
+    state.mean += ( state.alpha * delta );
+    const delta2 = xVal - state.mean;
+
+    state.m2 = ( state.decay * state.m2 ) + ( state.alpha * delta * delta2 );
+
+    state.variance = state.biased ? state.m2 :
+        ( state.weightSum > state.EPS ? ( state.m2 / state.weightSum ) : state.m2 );
+
+    if ( state.variance < 0 ) state.variance = 0;
+    state.stdev = Math.sqrt( state.variance );
+
+    if ( state.stats.snrDB ) {
+        if ( state.stdev < state.EPS ) {
+            state.snrDB = state.snrDbCap; // No noise — clean signal → 60 dB cap
+        } else if ( Math.abs( state.mean ) < state.EPS ) {
+            state.snrDB = 0; // No signal — noise dominates → 0 dB
+        } else {
+            state.snrDB = 20 * Math.log10( Math.abs( state.mean ) / state.stdev );
+        }
+    }
+
+    if ( state.stats.cv ) {
+        state.cv = ( Math.abs( state.mean ) > state.EPS ) ?
+            ( state.stdev / Math.abs( state.mean ) ) : state.cvLarge;
+    }
+}; // updateWelford()
+
+export default updateWelford;
+

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

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Hot-path dispatcher for the esStats node.
+ *
+ * Routes incoming values through first-sample initialization (seeds mean,
+ * floor, ceiling), then delegates to updateWelford (mean, variance, SNR,
+ * CV, zScore) and updateEnvelope (floor, ceiling, envScore) based on
+ * computation-path flags resolved at init. Zero allocations; all
+ * reads/writes via the pre-allocated state object.
+ */
+// nodes/es-stats/update.js
+
+import updateEnvelope from './update-envelope.js';
+import updateWelford from './update-welford.js';
+
+/**
+ * Update all requested statistics in a single pass.
+ * Updates statistics using Welford's online algorithm
+ * for numerical stability.
+ *
+ * @param {Object} state - Node state
+ * @param {Object} msg - Message containing input value
+ * @returns {Object} Updated state
+ */
+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;
+    }
+
+    // First sample initialization
+    if ( state.sampleCount === 0 ) {
+        state.mean = xVal;
+        state.m2 = 0;
+        state.variance = 0;
+        state.stdev = 0;
+        state.floor = xVal;
+        state.ceiling = xVal;
+        state.envelope = 0;
+        state.mid = xVal;
+        state.weightSum = state.alpha;
+        state.sampleCount = 1;
+        return state;
+    }
+
+    state.sampleCount += 1;
+
+    if ( state.needsWelford ) updateWelford( state, xVal );
+    if ( state.needsEnvelope ) updateEnvelope( state, xVal );
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/index.js

@@ -0,0 +1,83 @@
+// nodes/index.js
+
+// Import all nodes
+import * as accumulate from './accumulate/index.js';
+import * as appraise from './appraise/index.js';
+import * as butterworthFilter from './butterworth-filter/index.js';
+import * as categorize from './categorize/index.js';
+import * as controller from './controller/index.js';
+import * as diff from './diff/index.js';
+import * as lag from './lag/index.js';
+import * as digestMoments from './digest-moments/index.js';
+import * as dwellTimeTracker from './dwell-time-tracker/index.js';
+import * as emitIf from './emit-if/index.js';
+import * as esMean from './es-mean/index.js';
+import * as invertFlag from './invert-flag/index.js';
+import * as kalman1d from './kalman1d/index.js';
+import * as esCorrelation from './es-correlation/index.js';
+import * as esPairwiseCorrelation from './es-pairwise-correlation/index.js';
+import * as esStats from './es-stats/index.js';
+import * as kernel from './kernel/index.js';
+import * as median3 from './median3/index.js';
+import * as pageHinkley from './page-hinkley/index.js';
+import * as passIf from './pass-if/index.js';
+import * as persistIf from './persist-if/index.js';
+import * as persistenceCheck from './persistence-check/index.js';
+import * as processIndex from './process-index/index.js';
+import * as ratio from './ratio/index.js';
+import * as sanitize from './sanitize/index.js';
+import * as spikeGuard from './spike-guard/index.js';
+import * as stateChangeDetector from './state-change-detector/index.js';
+import * as momentsDigest from './moments-digest/index.js';
+import * as swStats from './sw-stats/index.js';
+import * as swingWatch from './swing-watch/index.js';
+import * as tally from './tally/index.js';
+import * as threshold from './threshold/index.js';
+import * as transform from './transform/index.js';
+import * as trend from './trend/index.js';
+import * as twStats from './tw-stats/index.js';
+import * as unbalance from './unbalance/index.js';
+import * as vectorDistance from './vector-distance/index.js';
+import * as winnow from './winnow/index.js';
+
+
+export {
+    accumulate,
+    appraise,
+    butterworthFilter,
+    categorize,
+    controller,
+    diff,
+    digestMoments,
+    dwellTimeTracker,
+    emitIf,
+    esMean,
+    esCorrelation,
+    esPairwiseCorrelation,
+    esStats,
+    invertFlag,
+    kalman1d,
+    kernel,
+    lag,
+    median3,
+    pageHinkley,
+    passIf,
+    persistIf,
+    persistenceCheck,
+    processIndex,
+    ratio,
+    sanitize,
+    spikeGuard,
+    stateChangeDetector,
+    momentsDigest,
+    swStats,
+    swingWatch,
+    tally,
+    threshold,
+    transform,
+    trend,
+    twStats,
+    unbalance,
+    vectorDistance,
+    winnow
+};

package/src/nodes/invert-flag/index.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Entry point for invertFlag node.
+ *
+ * Re-exports all lifecycle functions (init, update, publishTo, reset, recompute),
+ * shared control signals (disable, enable, pause, unpause), and 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';
+

package/src/nodes/invert-flag/init.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Initialization for invertFlag node.
+ *
+ * Validates the spec, extracts the input field name, and returns
+ * the fully initialized state object.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+
+const init = function ( spec ) {
+    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;
+
+    // Extract field name
+    state.x = spec.from.x;
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // State variable
+    state.inverted = false;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;
+

package/src/nodes/invert-flag/introspect.js

@@ -0,0 +1,115 @@
+// nodes/invert-flag/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for invertFlag node.
+ *
+ * Inverts a boolean field (e.g., dwell emits active=false on transition,
+ * dashboard shows "wasActive=true").
+ *
+ * DSL: .invertFlag( 'invert', 'active', { inverted: { storeAs: 'wasActive' } } )
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'inverted'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    inverted: 'Inverted boolean value (!x)',
+};
+
+/** 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 = 'Invert Flag';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Inverts a boolean field in the message',
+    features: [
+        'Boolean inversion: true → false, false → true',
+        'Handles truthy/falsy values via JavaScript coercion',
+        'Useful for inverting state transition flags'
+    ]
+};
+
+// 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 = Object.create( null );
+
+// 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'
+                }
+            }
+        },
+        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'
+                    }
+                }
+            }
+        }
+    },
+
+    // How to build the spec from DSL params
+    // DSL: .invertFlag( 'myInvert', 'active', { inverted: { storeAs: 'wasActive' } } )
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );
+

package/src/nodes/invert-flag/publish-to.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Publish function for invertFlag node.
+ *
+ * Copies the inverted flag to the output message, or propagates
+ * NaN if the last input was invalid. Skipped entirely when disabled.
+ */
+
+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.inverted.storeAs ] = state.inverted;
+}; // publishTo()
+
+export default publishTo;
+

package/src/nodes/invert-flag/recompute.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Recompute for invertFlag node.
+ *
+ * No-op: inversion is computed fresh from raw input on every update
+ * — there is no accumulated state that can drift over time.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/invert-flag/reset.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Reset invertFlag node state.
+ *
+ * Clears the inverted flag back to its initial value.
+ */
+
+const reset = function ( state ) {
+    state.inverted = false;
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/invert-flag/update.js

@@ -0,0 +1,32 @@
+// nodes/invert-flag/update.js
+
+/**
+ * @fileoverview Update function for invertFlag node.
+ *
+ * Inverts a boolean field using JavaScript's ! operator.
+ * Accepts boolean and truthy/falsy values (e.g., 0/1).
+ */
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    // Reset on each update
+    state.inputValidationFailed = false;
+
+    const value = msg[ state.x ];
+
+    // Handle faults gracefully: null/undefined signals missing data
+    if ( value === undefined || value === null ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Invert the value using JavaScript's ! operator
+    // Works with booleans (true/false) and truthy/falsy values (1/0)
+    state.inverted = !value;
+
+    return state;
+}; // update()
+
+export default update;
+

package/src/nodes/kalman1d/index.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Public API barrel for kalman1d node.
+ *
+ * Re-exports all standard node interface functions and introspection metadata.
+ * The kalman1d node implements a 1-D Kalman filter for model-based state
+ * estimation with control inputs and statistical outlier detection — the
+ * foundation for context-aware monitoring and data-driven digital twin
+ * capability in Composer pipelines.
+ */
+
+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 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';
+export * from './introspect.js';

package/src/nodes/kalman1d/init.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Initialization for kalman1d node.
+ *
+ * Validates the spec, resolves field-keyed parameters, computes derived
+ * Kalman coefficients, and returns fully initialized state.
+ *
+ * **Q and R parameterization:**
+ * `processVariance` is the process noise variance Q in absolute units
+ * (state²). `sensorVariance` is the measurement noise variance R in
+ * absolute units (measurement²). Both are independent — neither is
+ * computed from the other. This matches the textbook 1-D Kalman filter
+ * (Bar-Shalom, Welch & Bishop) and the upstream `winkjs/wink-statistics/
+ * src/streaming-1d-kalman-filter.js` from which this node was ported.
+ *
+ * **Auto-initialization:**
+ * State starts uninitialized (isInitialized = false). The first valid
+ * measurement sets xHat = z/H and P = R/H², bootstrapping the filter
+ * without requiring a prior estimate. Innovation is 0 on the first tick
+ * (no prediction to compare against).
+ *
+ * **Variance floor (Pmin):**
+ * Prevents P from collapsing to zero, which would cause the filter to
+ * ignore all future measurements — a known Kalman failure mode called
+ * "filter lock." Pmin = 1e-10 × R is small enough to never affect
+ * normal operation but catches the degenerate case.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+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;
+
+    // ── Input field ─────────────────────────────────────────────────────
+    state.x = spec.from.x;
+
+    // ── Control input (optional) ────────────────────────────────────────
+    // Any causal influence: heater power → temperature, fuel rate → tank
+    // level, motor current → bearing temperature. When absent, the
+    // prediction step simplifies to xPred = F·xHat (zero-control Kalman).
+    state.controlField = spec.control ?? null;
+
+    // ── Resolve field-keyed tunables (per-sensor differentiation) ────────
+    const sensorVarianceSpec = resolveScalar( spec.sensorVariance, state.x );
+    const processVarianceSpec = resolveScalar( spec.processVariance, state.x );
+    const chi2ThresholdSpec = resolveScalar( spec.chi2Threshold, state.x );
+    const controlModelSpec = resolveScalar( spec.controlModel, state.x );
+
+    // ── Apply defaults ──────────────────────────────────────────────────
+    const R = sensorVarianceSpec ?? introspect.DEFAULT_OPTIONS.sensorVariance;
+    const Q = processVarianceSpec ?? introspect.DEFAULT_OPTIONS.processVariance;
+
+    // ── Core Kalman parameters ──────────────────────────────────────────
+    // State-space model: x(k+1) = F·x(k) + G·u(k) + w, z(k) = H·x(k) + v
+    // Q (process noise variance) and R (measurement noise variance) are
+    // independent absolute values. Q is in state² units, R in measurement².
+    state.R = R;
+    state.Q = Q;
+    state.F = spec.stateTransition ?? introspect.DEFAULT_OPTIONS.stateTransition;
+    state.G = controlModelSpec ?? introspect.DEFAULT_OPTIONS.controlModel;
+    state.H = spec.measurement ?? introspect.DEFAULT_OPTIONS.measurement;
+
+    // ── Outlier detection ───────────────────────────────────────────────
+    // Innovation gate: chi-squared(1) test on (innovation²/S).
+    // 6.63 = 99% confidence → 1% false alarm rate.
+    state.chi2Threshold = chi2ThresholdSpec ?? introspect.DEFAULT_OPTIONS.chi2Threshold;
+    state.followMode = spec.followMode ?? introspect.DEFAULT_OPTIONS.followMode;
+
+    // ── Numerical safeguards ────────────────────────────────────────────
+    const varLimit = spec.varianceLimit ?? introspect.DEFAULT_OPTIONS.varianceLimit;
+    state.Pmax = varLimit * R;
+    state.Pmin = 1e-10 * R;
+
+    // ── State variables (pre-first-measurement) ─────────────────────────
+    state.xHat = 0;
+    state.P = 0;
+    state.isInitialized = false;
+
+    // ── Innovation outputs ──────────────────────────────────────────────
+    // Always available, even on excluded outlier measurements.
+    state.innovation = 0;
+    state.innovationGate = 0;
+
+    // ── Diagnostics ─────────────────────────────────────────────────────
+    state.updateCount = 0;
+    state.outlierCount = 0;
+
+    // ── Output configuration ────────────────────────────────────────────
+    state.stats = spec.stats;
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;