@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/page-hinkley/index.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Page-Hinkley change detection node — public API barrel file.
+ *
+ * Re-exports the standard node interface (init, update, publishTo, reset,
+ * recompute) plus shared control functions (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';

package/src/nodes/page-hinkley/init.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Initializes Page-Hinkley node state from a validated spec.
+ *
+ * Creates the complete state object: input mapping, tunable parameters
+ * (delta, lambda), structural options (halfLife, detectDrop, minWarmUpSamples),
+ * and all accumulator/output fields at their initial values. No allocations
+ * occur after init — the hot path (update/publishTo) is allocation-free.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+import { asTunable } from '../../core/tunable/index.js';
+import { halfLifeToAlpha } from '../../core/utils/half-life/index.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;
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    // Supports direct, field-keyed, and tunable specification for tunable params
+    const deltaSpec = resolveScalar( spec.delta, state.x );
+    const lambdaSpec = resolveScalar( spec.lambda, state.x );
+    // delta and lambda support tunables for adaptive change detection
+    state.deltaFn = asTunable( deltaSpec ?? introspect.DEFAULT_OPTIONS.delta );
+    state.lambdaFn = asTunable( lambdaSpec ?? introspect.DEFAULT_OPTIONS.lambda );
+    // halfLife is structural: selects exponentially smoothed vs running mean baseline.
+    // When absent → running mean (alpha=0). When present → alpha derived from halfLife.
+    const halfLifeSpec = resolveScalar( spec.halfLife, state.x );
+    state.alpha = ( typeof halfLifeSpec === 'number' ) ? halfLifeToAlpha( halfLifeSpec ) : 0;
+    state.detectDrop = spec.detectDrop ?? introspect.DEFAULT_OPTIONS.detectDrop;
+    state.minWarmUpSamples = spec.minWarmUpSamples ?? introspect.DEFAULT_OPTIONS.minWarmUpSamples;
+
+    // Seed tunable state fields with defaults — overwritten on every successful update()
+    state.delta = introspect.DEFAULT_OPTIONS.delta;
+    state.lambda = introspect.DEFAULT_OPTIONS.lambda;
+    state.tunableErrorLogged = false;
+
+    // State variables
+    state.cumSum = 0;        // Cumulative sum
+    state.minCumSum = 0;     // Running minimum of cumulative sum
+    state.mean = 0;          // Adaptive mean estimate
+    state.count = 0;         // Sample count for mean estimation
+    state.shiftDetected = false; // Previous shift detection state
+    state.testStatistic = 0; // Page-Hinkley test statistic
+
+    state.nodeType = introspect.getNodeType();
+    state.inControlPhase = false;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/page-hinkley/introspect.js

@@ -0,0 +1,193 @@
+/**
+ * @fileoverview Page-Hinkley node introspection metadata.
+ *
+ * Defines supported stats (phShift, phTestStatistic, phMean), control methods,
+ * default options, DSL spec schema with validators, and the buildSpec function
+ * for DSL transpilation. Single source of truth for the node's public contract.
+ */
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'phTestStatistic',
+    'phMean',
+    'phShift'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    phTestStatistic: 'Page-Hinkley change detection statistic',
+    phMean: 'Running mean or EWMA based on value of alpha',
+    phShift: 'Boolean indicator of detected shift'
+};
+
+/** 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 = 'Page Hinkley';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Detects changes in data distribution using the Page-Hinkley test',
+    features: [
+        'Sequential change point detection algorithm',
+        'Configurable sensitivity via lambda threshold',
+        'Adaptive baseline with running mean or EWMA',
+        'Can detect both increases and decreases in mean'
+    ]
+};
+
+// 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 const DEFAULT_OPTIONS = {
+    delta: 0.005,
+    lambda: 45,
+    // halfLife: not specified → running mean (alpha=0). When specified,
+    // init.js converts halfLife → alpha via halfLifeToAlpha().
+    detectDrop: false,
+    minWarmUpSamples: 10
+};
+
+/** Parameters that support tunable (dynamic) values.
+ *  halfLife is structural (selects running mean vs exponentially smoothed
+ *  baseline at init time), not tunable per-message. */
+export const TUNABLE_PARAMS = [ 'delta', 'lambda' ];
+
+// 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'
+                }
+            }
+        },
+        delta: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: false,
+            default: 0.005,
+            validator: validators.positiveOrFunction,
+            error: 'Delta must be a positive number or function'
+        },
+        lambda: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: false,
+            default: 45,
+            validator: validators.positiveOrFunction,
+            error: 'Lambda must be a positive number or function'
+        },
+        halfLife: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            validator: composerValidators.halfLife,
+            error: 'halfLife must be > 0 and < 999999'
+        },
+        detectDrop: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        minWarmUpSamples: {
+            type: 'number',
+            required: false,
+            default: 10,
+            integer: true,
+            validator: validators.positiveInteger,
+            error: 'Minimum warm-up samples must be a positive integer'
+        },
+        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'
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'delta', 'lambda' ],
+            validator: ( spec ) => {
+                // Resolve each for the node's field so a direct value and a
+                // field-keyed map are compared the same way (each resolves to a
+                // number, a function, or undefined).
+                const delta = resolveScalar( spec.delta, spec.from?.x );
+                const lambda = resolveScalar( spec.lambda, spec.from?.x );
+                // If either is a function (tunable), defer validation to runtime
+                if ( typeof delta === 'function' || typeof lambda === 'function' ) {
+                    return true;
+                }
+                // Delta should be small relative to lambda for proper sensitivity
+                if ( !delta || !lambda ) return true; // Use defaults
+                return delta < lambda * 0.1;
+            },
+            error: 'Delta should be less than 10% of lambda for proper sensitivity'
+        },
+        composerValidators.noSelfTriggers
+    ],
+
+    // Build spec from DSL parameters
+    // 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/page-hinkley/publish-to.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Publishes Page-Hinkley results to the downstream message.
+ *
+ * Copies requested stats (phShift, phTestStatistic, phMean) from internal
+ * state to the message. Gated by minWarmUpSamples — no output until the
+ * baseline has accumulated enough observations. Propagates NaN downstream
+ * when the input was invalid.
+ */
+
+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;
+    }
+
+    // Require minimum samples before publishing results.
+    if ( state.count < state.minWarmUpSamples ) return;
+    // Publish whatever is asked for.
+    if ( state.stats.phShift ) msg[ state.stats.phShift.storeAs ] = state.shiftDetected;
+    if ( state.stats.phTestStatistic ) msg[ state.stats.phTestStatistic.storeAs ] = state.testStatistic;
+    if ( state.stats.phMean ) msg[ state.stats.phMean.storeAs ] = state.mean;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/page-hinkley/recompute.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Recompute handler for Page-Hinkley — intentional no-op.
+ *
+ * The PHT cumulative sum depends on the entire history of observations.
+ * Unlike ring-buffer nodes (es-stats, kernel), there is no stored window
+ * to recompute from. The no-op is the correct implementation.
+ */
+
+const recompute = function () {
+    // Page-Hinkley is inherently sequential — cannot recompute from stored values
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/page-hinkley/reset.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Resets Page-Hinkley state to initial values.
+ *
+ * Clears all accumulated state (cumulative sum, running minimum, baseline
+ * mean, sample count) and detection outputs (shiftDetected, testStatistic).
+ * Configuration (alpha, detectDrop, tunables, stats) is preserved.
+ */
+
+const reset = function ( state ) {
+    // Reset accumulated computation state
+    state.cumSum = 0;
+    state.minCumSum = 0;
+    state.mean = 0;
+    state.count = 0;
+    // Reset detection outputs — avoids publishing stale results after reset
+    state.shiftDetected = false;
+    state.testStatistic = 0;
+    // Clear error suppression so next error episode is logged
+    state.tunableErrorLogged = false;
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/page-hinkley/update.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Page-Hinkley Test update function — processes one observation.
+ *
+ * Implements the standard PHT sequential recurrence (Page 1954, Hinkley 1971):
+ * 1. Update baseline estimate (running mean, or exponentially smoothed when
+ *    halfLife is configured)
+ * 2. Accumulate cumulative sum of deviations from baseline minus drift allowance
+ * 3. Track running minimum of cumulative sum
+ * 4. Detect shift when test statistic (cumSum - minCumSum) exceeds lambda
+ *
+ * On detection, cumSum and minCumSum reset to 0; mean and count continue
+ * tracking the new regime. Triggers (if any) fire on detection.
+ *
+ * Design rationale — exponentially smoothed baseline vs exponentially smoothed
+ * cumsum (as in river.drift.PageHinkley):
+ *
+ *   The composer applies exponential smoothing to the baseline mean, not the
+ *   cumulative sum. This is deliberate for industrial streaming:
+ *
+ *   1. Non-stationary signals: Industrial sensors drift with operating
+ *      conditions, ambient temperature, and equipment wear. A running mean
+ *      of 10,000 samples is effectively a constant — useless as "current
+ *      normal." An exponentially smoothed baseline tracks the actual
+ *      operating point.
+ *
+ *   2. Undecayed evidence accumulation: The raw cumsum grows monotonically under
+ *      a sustained shift — the mathematical foundation of the PHT.
+ *      Exponentially smoothing the cumsum (river's approach) decays evidence
+ *      over time; a gradual shift can decay away before reaching threshold.
+ *
+ *   3. Orthogonal tuning: halfLife controls baseline responsiveness;
+ *      delta/lambda control detection sensitivity — independent knobs.
+ *      river's alpha couples evidence decay with the effective detection
+ *      window.
+ *
+ *   4. Architectural recovery: The control plane (controller node) explicitly
+ *      resets baselines on confirmed change — clean, debuggable, no loss of
+ *      detection power. river needs cumsum forgetting as a workaround.
+ */
+
+import { executeTriggers } from '../../core/utils/node/index.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    let 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.detectDrop ) {
+        xVal = -xVal;
+    }
+
+    // Resolve tunable parameters for this message
+    try {
+        state.delta = state.deltaFn( msg );
+        state.lambda = state.lambdaFn( msg );
+        if ( state.tunableErrorLogged ) state.tunableErrorLogged = false;
+    } catch ( error ) {
+        if ( !state.tunableErrorLogged ) {
+            state.tunableErrorLogged = true;
+            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+        }
+    }
+
+    state.count += 1;
+    // Choose baseline update rule.
+    if ( state.alpha === 0 ) {                // running mean
+        state.mean += ( xVal - state.mean ) / state.count;
+    } else if ( state.count === 1 ) {     // ES baseline: seed with first observation
+        state.mean = xVal;
+    } else {                             // ES baseline: exponential smoothing
+        state.mean += state.alpha * ( xVal - state.mean );
+    }
+
+    // Page-Hinkley cumulative sum calculation.
+    // Detects positive changes (increase in mean).
+    state.cumSum += xVal - state.mean - state.delta;
+
+    // Update running minimum.
+    if ( state.cumSum < state.minCumSum ) {
+        state.minCumSum = state.cumSum;
+    }
+
+    // Change detection: test statistic exceeds threshold.
+    state.testStatistic = state.cumSum - state.minCumSum;
+    state.shiftDetected = state.testStatistic > state.lambda;
+    if ( state.shiftDetected ) {
+        state.minCumSum = 0;
+        state.cumSum = 0;
+
+        // Trigger controls if present.
+        executeTriggers( state );
+    }
+
+    return state;
+}; // update()
+
+export default update;
+

package/src/nodes/pass-if/index.js

@@ -0,0 +1,21 @@
+// nodes/pass-if/index.js
+
+/**
+ * @fileoverview Public API for passIf node
+ *
+ * Re-exports lifecycle functions, shared control utilities,
+ * 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/pass-if/init.js

@@ -0,0 +1,37 @@
+// nodes/pass-if/init.js
+
+/**
+ * @fileoverview Initialization for passIf node
+ *
+ * Validates spec via standard pipeline, creates state with
+ * counter, predicate reference, and control flags.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Extract validated predicate
+    state.predicate = spec.predicate;
+
+    // Initialize counter
+    state.counter = 0;
+
+    // Store node type for debugging
+    state.nodeType = introspect.getNodeType();
+
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/pass-if/introspect.js

@@ -0,0 +1,93 @@
+// nodes/pass-if/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for passIf node
+ *
+ * Single source of truth for DSL metadata, validation schema,
+ * default options, and node capabilities. Used by flow transpiler
+ * and documentation.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [];  // passIf doesn't publish stats - it's a pure gate
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {};
+
+/** 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 = 'Pass If';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Binary gate that passes or stops messages based on a predicate function',
+    features: [
+        'Evaluates predicate with message and counter arguments',
+        'Stops downstream flow when predicate returns false',
+        'Maintains message counter for deterministic sampling patterns',
+        'Pure predicate functions with no side effects'
+    ]
+};
+
+// 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 const DEFAULT_OPTIONS = {};
+
+// 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'
+        },
+        predicate: {
+            type: 'function',
+            required: true,
+            arity: 2,
+            error: 'Predicate must be a function with exactly two parameters (msg, counter)'
+        },
+        stats: {
+            type: 'object',
+            required: false,
+            propertyNames: [],  // No stats for pass-through node
+            error: 'PassIf is a gating node and does not support stats'
+        }
+    },
+
+    // No cross-field validators needed
+    crossFieldValidators: [],
+
+    // How to build the spec from DSL params
+    // Pattern: NAME_PREDICATE_OPTIONS -> (name, predicate, options)
+    buildSpec: ( name, predicate, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        predicate,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/pass-if/publish-to.js

@@ -0,0 +1,15 @@
+// nodes/pass-if/publish-to.js
+
+/**
+ * @fileoverview Publish-to function for passIf node
+ *
+ * No-op — pure gate node does not add any fields to the
+ * message. Messages that pass the predicate continue unchanged.
+ */
+
+const publishTo = function ( _state, _msg ) {
+    // PassIf is a pure gate - it doesn't publish any data to the message
+    // Messages that pass through are unchanged
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/pass-if/recompute.js

@@ -0,0 +1,15 @@
+// nodes/pass-if/recompute.js
+
+/**
+ * @fileoverview Recompute function for passIf node
+ *
+ * No-op — counter is a simple integer with no numerical
+ * stability concerns.
+ */
+
+const recompute = function () {
+    // Nothing to recompute - counter is a simple integer
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,18 @@
+// nodes/pass-if/reset.js
+
+/**
+ * @fileoverview Reset function for passIf node
+ *
+ * Clears message counter and error suppression flag,
+ * allowing counter-based predicates to restart.
+ */
+
+const reset = function ( state ) {
+    // Reset counter to initial state
+    state.counter = 0;
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+    return true;
+}; // reset()
+
+export default reset;