@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/state-change-detector/introspect.js

@@ -0,0 +1,146 @@
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this node can do */
+const SUPPORTED_STATS = [
+    'dwellTime',
+    'dwellSamples'
+];
+
+/** Human-readable descriptions */
+const STAT_DESCRIPTIONS = {
+    dwellTime: 'Duration in milliseconds spent in previous state (never negative — a backward clock step reports 0)',
+    dwellSamples: 'Number of samples observed in previous state'
+};
+
+/** The type of this node */
+const NODE_TYPE = 'State Change Detector';
+
+/** 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'
+};
+
+/** Default configuration options */
+const DEFAULT_OPTIONS = {
+    debounce: 3,
+    changeMode: 'any'
+};
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Detects and confirms transitions between categorical states with debounce filtering',
+    features: [
+        'Multi-field state monitoring with any/all logic',
+        'Debounce protection against boundary oscillation',
+        'Dwell time and sample count tracking',
+        'Trigger support for adaptive behavior'
+    ]
+};
+
+// 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()
+} );
+export { DEFAULT_OPTIONS };
+
+// DSL Metadata
+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: 1,
+                    itemSchema: {
+                        type: 'string',
+                        validator: validators.noSpaces,
+                        error: 'Field names must not contain spaces'
+                    }
+                }
+            }
+        },
+        debounce: {
+            type: 'number',
+            required: false,
+            default: 3,
+            validator: composerValidators.windowSize,
+            error: 'Debounce must be a positive integer'
+        },
+        changeMode: {
+            type: 'string',
+            required: false,
+            default: 'any',
+            validator: validators.oneOf( [ 'any', 'all' ] ),
+            error: 'changeMode must be "any" or "all"'
+        },
+        timestampField: {
+            type: 'string',
+            required: false,
+            validator: validators.identifier,
+            error: 'timestampField must be a valid identifier'
+        },
+        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'
+                    }
+                }
+            }
+        },
+        triggers: {
+            type: 'array',
+            required: false,
+            itemSchema: {
+                type: 'object',
+                validator: composerValidators.trigger,
+                error: 'Invalid trigger specification'
+            }
+        }
+    },
+
+    crossFieldValidators: [],
+
+    // 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/state-change-detector/publish-to.js

@@ -0,0 +1,20 @@
+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;
+    }
+
+    // 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/state-change-detector/recompute.js

@@ -0,0 +1,6 @@
+const recompute = function ( /* state */ ) {
+    // No numerical stability concerns for categorical state tracking
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/state-change-detector/reset.js

@@ -0,0 +1,20 @@
+const reset = function ( state ) {
+    // Reset all fields to null (forces re-initialization)
+    for ( let i = 0; i < state.fieldCount; i += 1 ) {
+        const field = state.fieldNames[ i ];
+        state.prevValues[ field ] = null;
+    }
+
+    // Reset counters and timing
+    state.debounceCount = 0;
+    state.stateStartTime = null;
+    state.samplesInState = 0;
+
+
+    state.dwellSamples = null;
+    state.dwellTime = null;
+
+    return state;
+}; // reset()
+
+export default reset;

package/src/nodes/state-change-detector/update.js

@@ -0,0 +1,97 @@
+import { executeTriggers } from '../../core/utils/node/index.js';
+import { validateCategoricalFields } from './helpers.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    // Reset on each update
+    state.inputValidationFailed = false;
+    // Validate all required fields are present and categorical
+    if ( !validateCategoricalFields( msg, state.fieldNames, state.fieldCount ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // These will be set only and only if change is spotted && debounced;
+    // otherwise they will remain null.
+    state.dwellTime = null;
+    state.dwellSamples = null;
+
+    // Get timestamp once for this message
+    const timestamp = state.useTimestampField ? msg[ state.timestampField ] : Date.now();
+
+    // ADR-004 fault handling: a message-supplied timestamp is a
+    // numerical input, so a missing or non-numeric value faults this
+    // ONE message and leaves the measurement in progress untouched
+    // (same guard as dwellTimeTracker). The device clock never fails
+    // this check.
+    if ( state.useTimestampField && !Number.isFinite( timestamp ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // First message initialization
+    if ( state.prevValues[ state.fieldNames[ 0 ] ] === null ) {
+        // Initialize prevValues and timing
+        for ( let i = 0; i < state.fieldCount; i += 1 ) {
+            const field = state.fieldNames[ i ];
+            state.prevValues[ field ] = msg[ field ];
+        }
+        state.stateStartTime = timestamp;
+        state.samplesInState = 1;
+        return state;
+    }
+
+    // Count fields that differ from last confirmed state
+    let changedFieldCount = 0;
+    for ( let i = 0; i < state.fieldCount; i += 1 ) {
+        const field = state.fieldNames[ i ];
+        if ( state.prevValues[ field ] !== msg[ field ] ) {
+            changedFieldCount += 1;
+        }
+    }
+
+    // Apply changeMode logic
+    const changeSpotted = state.changeMode ?
+        ( changedFieldCount === state.fieldCount ) :  // 'all': every field changed
+        ( changedFieldCount > 0 );                    // 'any': at least one changed
+
+    if ( changeSpotted ) {
+        // Different from last confirmed state
+        state.debounceCount += 1;
+
+        // Check if debounce threshold reached
+        if ( state.debounceCount >= state.debounce ) {
+            // Change CONFIRMED!
+            // Calculate stats BEFORE updating prevValues
+            state.dwellTime = timestamp - state.stateStartTime;
+            // A dwell can never be negative. A backward clock step
+            // (an NTP correction landing mid-measurement) would make
+            // the subtraction negative — publish 0 instead, matching
+            // dwellTimeTracker's guard (its update.js:74).
+            if ( state.dwellTime < 0 ) state.dwellTime = 0;
+            state.dwellSamples = state.samplesInState;
+
+            // Commit new state - update prevValues
+            for ( let i = 0; i < state.fieldCount; i += 1 ) {
+                const field = state.fieldNames[ i ];
+                state.prevValues[ field ] = msg[ field ];
+            }
+
+            // Reset counters for next transition
+            state.debounceCount = 0;
+            state.stateStartTime = timestamp;
+            state.samplesInState = 1;
+
+            // Execute triggers
+            executeTriggers( state );
+        }
+    } else {
+        // Matches last confirmed state - reset debounce
+        state.debounceCount = 0;
+        state.samplesInState += 1;
+    }
+
+    return state;
+}; // update()
+
+export default update;

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

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

@@ -0,0 +1,51 @@
+// nodes/sw-stats/init.js
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { create } from '../../windowing/count-sliding/index.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+const init = function ( spec ) {
+    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;
+
+    // Extract field name.
+    state.x = spec.from.x;
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    // Supports both direct and field-keyed specification
+    const windowSizeSpec = resolveScalar( spec.windowSize, state.x );
+    const windowSize = windowSizeSpec ?? introspect.DEFAULT_OPTIONS.windowSize;
+
+    // Underlying ring buffer storing the windowed values.
+    state.ring = create( windowSize );
+
+    // Config copy.
+    state.stats = Object.assign( Object.create( null ), spec.stats );
+
+    // Which of the SUPPORTED_STATS the user actually requested.
+    const statsList = Object.keys( state.stats );
+    // Determine which moments we need to compute and save it as state constants
+    state.need2 = statsList.some( ( m ) => [ 'variance', 'stdev', 'skewness', 'kurtosis', 'rms' ].includes( m ) );
+    state.need3 = statsList.some( ( m ) => [ 'skewness', 'kurtosis' ].includes( m ) );
+    state.need4 = statsList.includes( 'kurtosis' );
+
+    // State variables for incremental computation (s=sum, n=power).
+    state.s1 = 0;
+    state.s2 = ( state.need2 ) ? 0 : undefined;
+    state.s3 = ( state.need3 ) ? 0 : undefined;
+    state.s4 = ( state.need4 ) ? 0 : undefined;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

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

@@ -0,0 +1,131 @@
+// nodes/sw-stats/introspect.js
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+  'mean',
+  'variance',
+  'stdev',
+  'skewness',
+  'kurtosis',
+  'rms'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+  mean: 'Average of the last N samples',
+  variance: 'Sample variance (denominator N–1)',
+  stdev: 'Sample standard deviation',
+  skewness: 'Normalized third central moment',
+  kurtosis: 'Excess kurtosis (μ₄/σ⁴ – 3)',
+  rms: 'Root mean square'
+};
+
+/** 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 = 'SW Stats';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+  description: 'Computes running statistics over a sliding window',
+  features: [
+    'Efficient incremental computation',
+    'Configurable window size',
+    'Multiple statistics in single pass',
+    'Numerically stable algorithms'
+  ]
+};
+
+// 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: 10
+};
+
+// 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: 10,
+            integer: true,
+            min: 4,
+            validator: validators.positiveInteger,
+            error: 'Window size must be a positive integer; minimum 4'
+        },
+        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: [],
+
+    // 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/sw-stats/publish-to.js

@@ -0,0 +1,45 @@
+// nodes/sw-stats/publish-to.js
+
+import { isNotFull, size } from '../../windowing/count-sliding/index.js';
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const EPS = 1e-9;
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+    // Do not publish partial results.
+    if ( isNotFull( state.ring ) ) return;
+
+    const windowSize = size( state.ring );
+    const mean = state.s1 / windowSize;
+    if ( state.stats.mean ) msg[ state.stats.mean.storeAs ] = mean;
+    if ( state.need2 ) {
+        const sumSquaredDeviations = state.s2 - ( state.s1 * mean );
+        const m2 =       sumSquaredDeviations / windowSize;
+        const variance = sumSquaredDeviations / ( windowSize - 1 );
+        const safeVariance = ( variance < EPS ) ? 0 : variance;
+        // --- Use `stats.variance` in the if statement to check ---------------------
+        if ( state.stats.variance ) msg[ state.stats.variance.storeAs ] = safeVariance;
+        if ( state.stats.stdev )    msg[ state.stats.stdev.storeAs ]    = Math.sqrt( safeVariance );
+        if ( state.stats.rms )      msg[ state.stats.rms.storeAs ]      = Math.sqrt( state.s2 / windowSize );
+        if ( state.need3 ) {
+            // Formula: m3 = ( s3 - 3 μ s2 + 2 μ^3 N ) / N
+            const m3 = ( state.s3 - (3 * mean * state.s2 ) + ( 2 * mean * mean * mean * windowSize ) ) / windowSize;
+            const denom = Math.pow( m2, 1.5 );
+            if ( state.stats.skewness ) msg[ state.stats.skewness.storeAs ] = ( denom > EPS ) ? m3 / denom : 0;
+        }
+        if ( state.need4 ) {
+            const m4 = ( state.s4 - ( 4 * ( mean * state.s3 ) ) + ( 6 * mean * mean * state.s2 ) -
+                       ( 3 * mean * mean * mean * mean * windowSize ) ) / windowSize;
+            const denom = m2 * m2;
+            if ( state.stats.kurtosis ) msg[ state.stats.kurtosis.storeAs ] = ( denom > EPS ) ? ( ( m4 / denom ) - 3 ) : -3;
+        }
+    }
+}; // publishTo()
+
+export default publishTo;

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

@@ -0,0 +1,33 @@
+// nodes/sw-stats/recompute.js
+
+const recompute = function ( state ) {
+    // Reset accumulators first
+    state.s1 = 0;
+    state.s2 = state.need2 ? 0 : undefined;
+    state.s3 = state.need3 ? 0 : undefined;
+    state.s4 = state.need4 ? 0 : undefined;
+
+    const buf = state.ring.buffer;
+    // Only process actual values
+    const used = state.ring.used;
+
+    for ( let k = 0; k < used; k += 1 ) {
+        const value = buf[ k ];
+        state.s1 += value;
+        if ( state.need2 || state.need3 || state.need4 ) {
+            const value2 = value * value;
+            if ( state.need2 ) state.s2 += value2;
+            if ( state.need3 || state.need4 ) {
+                const value3 = value2 * value;
+                if ( state.need3 ) state.s3 += value3;
+                if ( state.need4 ) {
+                    const value4 = value3 * value;
+                    state.s4 += value4;
+                }
+            }
+        }
+    }
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,15 @@
+// nodes/sw-stats/reset.js
+
+import { reset as resetRing }  from '../../windowing/count-sliding/index.js';
+const reset = function ( state ) {
+    state.s1 = 0;
+    state.s2 = state.need2 ? 0 : undefined;
+    state.s3 = state.need3 ? 0 : undefined;
+    state.s4 = state.need4 ? 0 : undefined;
+
+    resetRing( state.ring );
+
+    return true;
+}; // reset()
+
+export default reset;

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

@@ -0,0 +1,39 @@
+// nodes/sw-stats/update.js
+
+import { push } from '../../windowing/count-sliding/index.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 evicted = push( state.ring, xVal ) ?? 0;
+
+    state.s1 += xVal - evicted;
+    if ( state.need2 ) {
+        const value2 = xVal * xVal;
+        const evicted2 = evicted * evicted;
+        state.s2 += value2 - evicted2;
+        if ( state.need3 ) {
+            const value3 = value2 * xVal;
+            const evicted3 = evicted2 * evicted;
+            state.s3 += value3 - evicted3;
+            if ( state.need4 ) {
+                const value4 = value3 * xVal;
+                const evicted4 = evicted3 * evicted;
+                state.s4 += value4 - evicted4;
+            }
+        }
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/swing-watch/index.js

@@ -0,0 +1,17 @@
+// @fileoverview
+// index.js — standard node exports per ADR-004.
+//
+// Re-exports all lifecycle functions and shared control signals. The
+// introspection metadata (getSupportedStats, getDSLMetadata, etc.) is
+// re-exported via the wildcard export from introspect.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';
+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';