@winkjs/composer 0.0.2 → 0.4.0

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

@@ -0,0 +1,113 @@
+// nodes/tw-stats/update.js
+
+/**
+ * @fileoverview TW Stats Update — Pébay incremental moment accumulation
+ * with selective tier gating and tumbling window management.
+ *
+ * ────────────────────────────────────────────────────────────────────────
+ * Execution Flow (per message)
+ *
+ * 1) Prelude
+ *    • Clear planPublish from last tick.
+ *    • If flush is latched and n > 0: snapshot → planPublish → reset.
+ *      The current message becomes the first sample of the next window.
+ *
+ * 2) Core update
+ *    • Guard: disabled, invalid input (skip and return).
+ *    • Pébay accumulation with tier gates (maxMoment 1–4).
+ *    • Critical: update order is M4 → M3 → M2 → M1 because each
+ *      formula uses the previous values of lower moments.
+ *
+ * 3) Epilogue
+ *    • Increment valid sample counter.
+ *    • If window complete and no flush snapshot already planned:
+ *      snapshot → planPublish → reset.
+ *
+ * ────────────────────────────────────────────────────────────────────────
+ * Invalid input handling
+ *    • Non-finite samples are skipped (not counted).
+ *    • currentCount only increments on valid samples.
+ *    • A flush snapshot planned in prelude still publishes this tick.
+ *
+ * ────────────────────────────────────────────────────────────────────────
+ * References
+ * [1] Pébay, P. (2008). Formulas for robust, one-pass parallel computation
+ *     of covariances and arbitrary-order statistical moments.
+ *     Sandia Report SAND2008-6212.
+ */
+
+/* eslint-disable camelcase */
+import { copyFrom } from './copy-from.js';
+import reset from './reset.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    // ── Prelude ─────────────────────────────────────────────────────────
+    state.planPublish = false;
+
+    if ( state.flushLatched ) {
+        if ( state.n > 0 ) {
+            copyFrom( state, state.snapshot );
+            state.planPublish = true;
+            reset( state );
+        }
+        state.flushLatched = false;
+    }
+
+    // ── Core update ─────────────────────────────────────────────────────
+    state.inputValidationFailed = false;
+
+    const xVal = msg[ state.x ];
+
+    if ( !Number.isFinite( xVal ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Pébay single-value update with selective tier gating
+    const n1 = state.n;
+    state.n += 1;
+
+    const delta = xVal - state.M1;
+    const delta_n = delta / state.n;
+    const delta_n2 = delta_n * delta_n;
+    const term1 = delta * delta_n * n1;
+
+    // Update order: M1, then M4 → M3 → M2 (matches momentsDigest).
+    // M4 and M3 formulas use the previous values of M2 and M3;
+    // none depend on M1 (delta_n is already computed from old M1).
+    state.M1 += delta_n;
+
+    if ( state.maxMoment >= 4 ) {
+        state.M4 += ( term1 * delta_n2 * ( ( state.n * state.n ) - ( 3 * state.n ) + 3 ) ) +
+                    ( 6 * delta_n2 * state.M2 ) - ( 4 * delta_n * state.M3 );
+    }
+
+    if ( state.maxMoment >= 3 ) {
+        state.M3 += ( term1 * delta_n * ( state.n - 2 ) ) - ( 3 * delta_n * state.M2 );
+    }
+
+    if ( state.maxMoment >= 2 ) {
+        state.M2 += term1;
+    }
+
+    // Min/max tracking
+    if ( state.needsMinMax ) {
+        if ( xVal < state.min ) state.min = xVal;
+        if ( xVal > state.max ) state.max = xVal;
+    }
+
+    // ── Epilogue ────────────────────────────────────────────────────────
+    state.currentCount += 1;
+
+    if ( ( state.currentCount >= state.windowSize ) && !state.planPublish ) {
+        copyFrom( state, state.snapshot );
+        state.planPublish = true;
+        reset( state );
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/unbalance/index.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Entry point for the unbalance node. Re-exports lifecycle
+ * functions, the shared control signals, 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';
+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/unbalance/init.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Initializes unbalance node state from a validated spec.
+ * Pre-resolves the field-name list, the missing-channel policy, and which stats
+ * need the deviation step. Keeps state.stats so publishNaN() can target every
+ * configured output. Stateless: no buffers, no temporal state.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+
+/** Mean magnitudes below this make the percentage undefined. */
+const EPSILON = 1e-12;
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    const state = Object.create( null );
+    state.inputValidationFailed = false;
+    state.disable = false;
+    state.pause = false;
+
+    state.fields = spec.from.x.slice( 0 );
+    state.n = state.fields.length;
+    state.stats = spec.stats;
+    state.epsilon = EPSILON;
+
+    // Missing-channel policy, resolved once. With skipOnNaN off (the default) any
+    // non-finite input blanks the tick, so the floor is the full width n. With
+    // skipOnNaN on, the metric is computed over the present channels, down to
+    // minPresent ( default 2, the fewest where a spread is defined ). The hot path
+    // only compares the present count against state.minPresent.
+    state.skipOnNaN = spec.skipOnNaN ?? introspect.DEFAULT_OPTIONS.skipOnNaN;
+    state.minPresent = state.skipOnNaN ?
+        ( spec.minPresent ?? introspect.DEFAULT_OPTIONS.minPresent ) :
+        state.n;
+
+    // The deviation step is only needed for these four stats.
+    state.needDev = Boolean(
+        spec.stats.maxDev || spec.stats.unbalance ||
+        spec.stats.worstIndex || spec.stats.worstDev
+    );
+
+    // Computed outputs (fixed shape, overwritten each tick).
+    state.mean = 0;
+    state.min = 0;
+    state.max = 0;
+    state.range = 0;
+    state.maxDev = 0;
+    state.unbalance = 0;
+    state.worstIndex = 0;
+    state.worstDev = 0;
+    state.presentCount = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/unbalance/introspect.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Single source of truth for the unbalance node — supported
+ * stats, capabilities, control methods, and the DSL/validation schema.
+ * All getters return defensive copies. The `unbalance` stat is the general
+ * normalized maximum deviation from the mean across N nominally-equal
+ * channels; NEMA / IEEE PVUR is the named electrical instance of the same
+ * computation. The `unbalance` percentage is relative: it divides by the mean,
+ * so it means something only when the channels are energized/loaded. At idle the
+ * inputs are sensor noise and the value comes out large but meaningless; gate
+ * idle/off states upstream (the operating-gated metric composition pattern).
+ *
+ * Missing channels: by default any non-finite input blanks every output, because
+ * an incomplete set is an undefined cross-field metric. The opt-in `skipOnNaN`
+ * mode instead reports over the channels that are present, down to a `minPresent`
+ * floor. The `presentCount` output reports how many channels reported and is
+ * always the real count, even on a blanked tick.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+const SUPPORTED_STATS = [
+    'mean',
+    'min',
+    'max',
+    'range',
+    'maxDev',
+    'unbalance',
+    'worstIndex',
+    'worstDev',
+    'presentCount'
+];
+
+const STAT_DESCRIPTIONS = {
+    mean: 'Arithmetic mean of the N input magnitudes',
+    min: 'Minimum input magnitude',
+    max: 'Maximum input magnitude',
+    range: 'max - min (peak-to-peak spread)',
+    maxDev: 'Maximum absolute deviation from the mean',
+    unbalance: 'Normalized max-deviation: ( maxDev / |mean| ) * 100. Relative metric — meaningful only when channels are energized/loaded; gate idle/off states (see the operating-gated metric pattern)',
+    worstIndex: 'Zero-based index of the most-deviating input',
+    worstDev: 'Signed deviation ( value - mean ) of the worst input',
+    presentCount: 'How many channels reported (were finite) this tick. Always the real count, even when the metric blanks, because it describes the input not the result. Use it with skipOnNaN to gate on coverage'
+};
+
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'No-op (stateless node)',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses update() while keeping last values visible via publishTo()',
+    unpause: 'Resumes update() after pause'
+};
+
+const NODE_TYPE = 'Unbalance';
+
+const CAPABILITIES = {
+    description: 'Instantaneous cross-field unbalance over N nominally-equal magnitudes',
+    features: [
+        'Stateless and allocation-free',
+        'Domain-agnostic (electrical, thermal, mechanical, process)',
+        'Blank-on-miss by default: any missing channel makes every output NaN',
+        'Opt-in skipOnNaN: report over the present channels, down to a minPresent floor',
+        'presentCount output: how many channels reported, always the real count',
+        'Worst-channel diagnostics (index and signed deviation)',
+        'Single pass: worst channel derived from the min/max extremes'
+    ]
+};
+
+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 = {
+    skipOnNaN: false,   // blank every output if any channel is missing (the safe default)
+    minPresent: 2       // when skipOnNaN is true, the fewest present channels that still compute
+};
+
+const DSL_METADATA = {
+    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,
+                    itemSchema: {
+                        type: 'string',
+                        validator: validators.noSpaces,
+                        error: 'field names cannot contain spaces'
+                    }
+                }
+            }
+        },
+        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'
+                    }
+                }
+            }
+        },
+        skipOnNaN: {
+            type: 'boolean',
+            required: false
+        },
+        minPresent: {
+            // The effective default is conditional — n channels in blank mode, 2 in
+            // skip mode (see DEFAULT_OPTIONS), so it is not a flat schema default. The
+            // floor of 2 is where a spread is defined.
+            type: 'number',
+            required: false,
+            integer: true,
+            min: 2,
+            error: 'minPresent must be an integer >= 2'
+        }
+    },
+
+    crossFieldValidators: [
+        {
+            fields: [ 'from.x' ],
+            validator: ( spec ) => ( new Set( spec.from.x ).size === spec.from.x.length ),
+            error: 'field names must be unique'
+        },
+        {
+            fields: [ 'minPresent', 'skipOnNaN' ],
+            validator: ( spec ) => ( spec.minPresent === undefined ) || ( spec.skipOnNaN === true ),
+            error: 'minPresent applies only when skipOnNaN is true'
+        },
+        {
+            fields: [ 'minPresent', 'from.x' ],
+            validator: ( spec ) => ( spec.minPresent === undefined ) || ( spec.minPresent <= spec.from.x.length ),
+            error: 'minPresent cannot exceed the number of fields'
+        }
+    ],
+
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } )
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/unbalance/publish-to.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Copies the computed unbalance stats onto the message, or
+ * propagates NaN to every configured metric when the last input was invalid.
+ * presentCount is written separately and always carries the real count, because
+ * it describes the input, not the result. Skipped when disabled; still runs when
+ * paused so last values stay visible.
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    const stats = state.stats;
+
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+    } else {
+        if ( stats.mean ) {
+            msg[ stats.mean.storeAs ] = state.mean;
+        }
+        if ( stats.min ) {
+            msg[ stats.min.storeAs ] = state.min;
+        }
+        if ( stats.max ) {
+            msg[ stats.max.storeAs ] = state.max;
+        }
+        if ( stats.range ) {
+            msg[ stats.range.storeAs ] = state.range;
+        }
+        if ( stats.maxDev ) {
+            msg[ stats.maxDev.storeAs ] = state.maxDev;
+        }
+        if ( stats.unbalance ) {
+            msg[ stats.unbalance.storeAs ] = state.unbalance;
+        }
+        if ( stats.worstIndex ) {
+            msg[ stats.worstIndex.storeAs ] = state.worstIndex;
+        }
+        if ( stats.worstDev ) {
+            msg[ stats.worstDev.storeAs ] = state.worstDev;
+        }
+    }
+
+    // presentCount describes the input, so it carries the real count on every
+    // tick — including a blanked one, where publishNaN above set it to NaN.
+    if ( stats.presentCount ) {
+        msg[ stats.presentCount.storeAs ] = state.presentCount;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/unbalance/recompute.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Recompute for the unbalance node. The computation is exact and
+ * stateless — there is no incremental drift to correct — so recompute is a
+ * no-op.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/unbalance/reset.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Reset for the unbalance node. Nothing accumulates — every
+ * output is recomputed from scratch each tick — so reset is a no-op.
+ */
+
+const reset = function () {
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/unbalance/update.js

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Hot path for the unbalance node.
+ *
+ * One linear pass computes the sum, the min and max, and the indices of those
+ * extremes. The most-deviating-from-mean channel is always one of the extremes
+ * ( for any xi, |xi - mean| <= max( max - mean, mean - min ) ), so maxDev,
+ * worstIndex and worstDev follow with no second pass.
+ *
+ * Missing channels: a non-finite field ( NaN or +/-Infinity ) is skipped and the
+ * present channels are counted. The tick blanks ( publishTo writes NaN to every
+ * metric ) when fewer than state.minPresent channels are present. In the default
+ * blank mode minPresent equals the full width, so any one missing field blanks
+ * the tick — an incomplete set is an undefined cross-field metric. In skip mode
+ * minPresent is lower, so the metric is computed over the channels present.
+ * presentCount always carries the real count, even on a blanked tick.
+ */
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    state.inputValidationFailed = false;
+
+    const fields = state.fields;
+    const n = state.n;
+
+    let sum = 0;
+    let minVal = Infinity;
+    let maxVal = -Infinity;
+    let minIdx = 0;
+    let maxIdx = 0;
+    let present = 0;
+    let i = 0;
+
+    while ( i < n ) {
+        const v = msg[ fields[ i ] ];
+        if ( Number.isFinite( v ) ) {
+            sum += v;
+            present += 1;
+            if ( v < minVal ) {
+                minVal = v;
+                minIdx = i;
+            }
+            if ( v > maxVal ) {
+                maxVal = v;
+                maxIdx = i;
+            }
+        }
+        i += 1;
+    }
+
+    // A fact about the input, always defined — set before any blank return.
+    state.presentCount = present;
+
+    if ( present < state.minPresent ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    const mean = sum / present;
+    state.mean = mean;
+    state.min = minVal;
+    state.max = maxVal;
+    state.range = ( maxVal - minVal );
+
+    if ( state.needDev === false ) return state;
+
+    const devHigh = ( maxVal - mean );
+    const devLow = ( mean - minVal );
+    const highWins = ( devHigh >= devLow );
+
+    const maxAbsDev = highWins ? devHigh : devLow;
+    state.maxDev = maxAbsDev;
+    state.worstIndex = highWins ? maxIdx : minIdx;
+    state.worstDev = highWins ? devHigh : ( -devLow );
+
+    const absMean = Math.abs( mean );
+    state.unbalance = ( absMean < state.epsilon ) ?
+        NaN :
+        ( ( 100 * maxAbsDev ) / absMean );
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/vector-distance/index.js

@@ -0,0 +1,14 @@
+// nodes/vector-distance/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/vector-distance/init.js

@@ -0,0 +1,54 @@
+// nodes/vector-distance/init.js
+
+/* eslint-disable no-bitwise */
+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;
+
+    // Vector source configuration - following standard pattern
+    state.x = spec.from.x;
+    state.y = spec.from.y;
+
+    state.accumulator = new Float64Array( 6 );
+    state.accumulator.fill( 0 );
+
+    // Distance values - pre-allocate all even if not used
+    state.distances = Object.create( null );
+    state.distances.mad = 0;
+    state.distances.rms = 0;
+    state.distances.maximum = 0;
+    state.distances.cosine = 0;
+    state.distances.angular = 0;
+
+    // Track if we've computed at least once i.e. downstream
+    // node has warmed up!
+    state.computed = false;
+
+    // Output configuration
+    state.stats = spec.stats;
+
+    state.mask = 0;
+    if ( state.stats.mad || state.stats.maximum ) state.mask |= 1;
+    if ( state.stats.rms ) state.mask |= 2;
+    if ( state.stats.cosine || state.stats.angular ) state.mask |= 4;
+
+    // Optimization flags based on requested stats
+    state.needsAbs = state.stats.mad || state.stats.maximum;
+    state.needsSquare = state.stats.rms;
+    state.needsDotProduct = state.stats.cosine || state.stats.angular;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;