@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/kalman1d/introspect.js

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Introspection metadata for kalman1d node.
+ *
+ * Defines supported stats, control methods, capabilities, DSL schema,
+ * and default options. All getters return defensive copies.
+ *
+ * The kalman1d node is a 1-D Kalman filter for model-based state estimation
+ * with statistical outlier detection via an innovation gate (chi-squared test).
+ *
+ * **Compositional value — the innovation signal:**
+ * The node's primary differentiator is publishing the innovation (prediction
+ * error) as a first-class stat. This enables powerful downstream compositions:
+ *
+ * - **innovation → appraise**: Detect "temperature is SURPRISING given the
+ *   current draw" rather than "temperature is high" — the Kalman model
+ *   accounts for expected variation from control inputs, leaving only the
+ *   unexplained component as anomaly evidence.
+ *
+ * - **innovation → esStats → threshold**: Monitor mean(|innovation|) over
+ *   time to detect model mismatch and trigger recalibration.
+ *
+ * - **innovationGate → predict**: Classify the PATTERN of normalized
+ *   surprises across multiple signals for fault diagnosis.
+ *
+ * - **ghost + innovation**: In shadow partitions, innovation grows as
+ *   simulated degradation diverges — enabling data-driven prognosis.
+ *
+ * **Control input generalization:**
+ * "Control" is not limited to actuator commands — it is any measurable causal
+ * influence: fuel rate → tank level, occupancy → CO2, current → temperature.
+ * This makes Kalman applicable wherever an approximate physical model exists.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+// ── Supported Features ──────────────────────────────────────────────────────
+
+const SUPPORTED_STATS = [ 'filtered', 'variance', 'innovation', 'innovationGate' ];
+
+const STAT_DESCRIPTIONS = {
+    filtered: 'Optimal state estimate (Kalman-filtered value)',
+    variance: 'Estimation error covariance — quantifies uncertainty in the estimate',
+    innovation: 'Prediction error (signed): z - H·xHat. The anomaly signal — ' +
+                'feeds appraise for surprise detection, esStats for model monitoring',
+    innovationGate: 'Normalized innovation squared (chi-squared(1) statistic). ' +
+                    'Unitless anomaly score — directly thresholdable with known false-alarm rates'
+};
+
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears accumulated state; next measurement auto-initializes',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+const NODE_TYPE = 'Kalman 1d';
+
+const CAPABILITIES = {
+    description: 'Model-based state estimation with statistical outlier detection via innovation gating',
+    features: [
+        'Optimal state estimation for linear systems with Gaussian noise',
+        'Control-aware prediction using any causal influence as input',
+        'Innovation signal as first-class output for downstream anomaly detection',
+        'Statistical outlier detection via Mahalanobis distance (chi-squared gate)',
+        'Dual-mode operation: exclude outliers OR track sudden changes (follow mode)',
+        'Gap-tolerant prediction with bounded uncertainty growth',
+        'Auto-initialization from first measurement',
+        'Variance floor prevents filter lock on long-running streams'
+    ]
+};
+
+// ── Getter Functions (defensive copies) ─────────────────────────────────────
+
+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()
+} );
+
+// ── Default Options ─────────────────────────────────────────────────────────
+
+export const DEFAULT_OPTIONS = {
+    sensorVariance: 1,
+    processVariance: 0.01,
+    chi2Threshold: 6.63,
+    followMode: false,
+    stateTransition: 1,
+    measurement: 1,
+    controlModel: 0,
+    varianceLimit: 100
+};
+
+// ── 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: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'from.x must not contain spaces'
+                }
+            }
+        },
+
+        // ── Control input field (optional) ──────────────────────────
+        // Any measurable causal influence: heater power, fuel rate,
+        // motor current, occupancy. Not just actuator commands.
+        control: {
+            type: 'string',
+            required: false,
+            validator: validators.noSpaces,
+            error: 'control field name must not contain spaces'
+        },
+
+        // ── Noise covariances ───────────────────────────────────────
+        // R: measurement noise variance, in measurement² units. The
+        // expected variance of the sensor noise on each measurement.
+        // Per-sensor via field-keyed objects.
+        sensorVariance: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.sensorVariance,
+            validator: validators.positive,
+            error: 'sensorVariance must be positive'
+        },
+        // Q: process noise variance, in state² units. The expected
+        // variance of the unmodeled change in state from one step to
+        // the next. Used directly in the predict step (PPred = F·P·F + Q).
+        // Larger Q → filter trusts new measurements more (responsive).
+        // Smaller Q → filter trusts its model more (smoother).
+        processVariance: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.processVariance,
+            validator: validators.positive,
+            error: 'processVariance must be positive'
+        },
+
+        // ── Outlier detection ───────────────────────────────────────
+        // Chi-squared(1) threshold for innovation gate.
+        // 3.84 = 95%, 6.63 = 99%, 10.84 = 99.9%
+        chi2Threshold: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.chi2Threshold,
+            validator: validators.positive,
+            error: 'chi2Threshold must be positive'
+        },
+        // Follow mode tracks jumps; exclude mode rejects outliers.
+        followMode: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.followMode
+        },
+
+        // ── State-space model coefficients ──────────────────────────
+        // F: state transition (how state evolves between measurements).
+        // Default 1 = random walk / constant-state model.
+        stateTransition: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.stateTransition
+        },
+        // H: measurement model (how state appears in measurements).
+        // Default 1 = direct observation. H=0 is never valid — makes
+        // the state unobservable and causes division by zero in update.
+        measurement: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.measurement,
+            validator: validators.nonZero,
+            error: 'measurement (H) must be nonzero'
+        },
+        // G: control coefficient. Can be zero (no control), positive
+        // (e.g., heater adding heat), or negative (e.g., fuel consumption
+        // depleting tank level). Per-sensor via field-keyed objects.
+        controlModel: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.controlModel
+        },
+
+        // ── Numerical safeguards ────────────────────────────────────
+        // Pmax = varianceLimit * R. Bounds uncertainty growth during
+        // prediction-only periods (missing data, gaps).
+        varianceLimit: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.varianceLimit,
+            validator: validators.positive,
+            error: 'varianceLimit must be positive'
+        },
+
+        // ── Output configuration ────────────────────────────────────
+        stats: {
+            type: 'object',
+            required: true,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // No cross-field constraints needed:
+    // - controlModel != 0 without `control` is valid (control defaults to 0)
+    // - All parameter combinations are mathematically valid
+    crossFieldValidators: [],
+
+    // Pattern: nameXOutputsOptions
+    // DSL: .kalman1d( name, field, { filtered: 'est' }, { control: 'power' } )
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } )
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Publish function for kalman1d node.
+ *
+ * Copies computed state values to the output message, or propagates NaN
+ * if the last input was invalid. Skipped entirely when disabled.
+ *
+ * All four stats (filtered, variance, innovation, innovationGate) are
+ * published on every tick — including after outlier exclusion. This is
+ * intentional: innovation reflects what reality looked like (measurement-
+ * space), while filtered/variance reflect the predict-only state. Downstream
+ * nodes (appraise, esStats, predict) need the innovation from excluded
+ * measurements to detect model mismatch and build anomaly conviction.
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    // Propagate NaN if unhealthy (fault isolation)
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    // Publish only the stats the user requested
+    const stats = state.stats;
+    if ( stats.filtered ) msg[ stats.filtered.storeAs ] = state.xHat;
+    if ( stats.variance ) msg[ stats.variance.storeAs ] = state.P;
+    if ( stats.innovation ) msg[ stats.innovation.storeAs ] = state.innovation;
+    if ( stats.innovationGate ) msg[ stats.innovationGate.storeAs ] = state.innovationGate;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/kalman1d/recompute.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Recompute for kalman1d node.
+ *
+ * Clamps the estimation error covariance P to [Pmin, Pmax]. The update()
+ * function already clamps after prediction, but recompute provides a periodic
+ * safety net for very long-running pipelines where floating-point drift could
+ * push P outside its valid bounds.
+ *
+ * Unlike butterworth-filter (which is a no-op), Kalman's recompute is active
+ * because the covariance evolves recursively and is susceptible to long-term
+ * drift in edge cases (e.g., extended prediction-only periods with near-zero
+ * process noise).
+ */
+
+const recompute = function ( state ) {
+    // Clamp covariance to valid range
+    if ( state.P > state.Pmax ) state.P = state.Pmax;
+    if ( state.P < state.Pmin ) state.P = state.Pmin;
+
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/kalman1d/reset.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Reset for kalman1d node.
+ *
+ * Clears all accumulated state to pre-first-measurement condition. The next
+ * valid measurement will auto-initialize the filter (xHat = z/H, P = R/H²).
+ *
+ * Idempotent: multiple reset() calls produce the same state as a single call.
+ * Model parameters (R, Q, F, G, H, thresholds) are preserved — only the
+ * estimation state is cleared.
+ */
+
+const reset = function ( state ) {
+    // ── Estimation state ────────────────────────────────────────────────
+    state.xHat = 0;
+    state.P = 0;
+    state.isInitialized = false;
+
+    // ── Innovation outputs ──────────────────────────────────────────────
+    state.innovation = 0;
+    state.innovationGate = 0;
+
+    // ── Diagnostics ─────────────────────────────────────────────────────
+    state.updateCount = 0;
+    state.outlierCount = 0;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/kalman1d/update.js

@@ -0,0 +1,144 @@
+/**
+ * @fileoverview Core Kalman filter algorithm for kalman1d node (hot path).
+ *
+ * Implements the standard 1-D Kalman filter: predict → innovate → gate →
+ * update/exclude/follow. Zero allocations — all scalar arithmetic.
+ *
+ * **Why innovation is stored BEFORE the gate branch:**
+ *
+ * Innovation (prediction error) is a measurement-space signal about reality,
+ * not a filter-state signal about the filter's decision. When the filter
+ * excludes an outlier, the innovation that triggered the exclusion is itself
+ * valuable diagnostic information for downstream nodes:
+ *
+ * 1. **innovation → appraise**: "Temperature is SURPRISING given the heater
+ *    power" — the Kalman model accounts for expected heating; only the
+ *    UNEXPLAINED component triggers appraise conviction. Excluded outlier
+ *    innovation tells appraise about a real event the filter chose to ignore.
+ *
+ * 2. **innovation → esStats → threshold**: Sustained mean(|innovation|)
+ *    detects model mismatch. If we suppressed innovation on excluded
+ *    measurements, esStats would underestimate the mismatch.
+ *
+ * 3. **innovation → predict (fault classification)**: Classify the PATTERN
+ *    of surprises across multiple Kalman-filtered signals. Missing the
+ *    outlier innovation breaks the pattern.
+ *
+ * 4. **ghost + innovation**: In shadow partitions running degradation
+ *    scenarios, innovation grows as the perturbation diverges from the
+ *    real model — enabling data-driven prognosis without a physics model.
+ *
+ * 5. **Signed innovation + control direction**: "Positive innovation with
+ *    negative control input = external heat source" — directional
+ *    diagnostics require the raw signed innovation even on excluded ticks.
+ *
+ * References:
+ * - Bar-Shalom, Li, Kirubarajan, "Estimation with Applications to Tracking
+ *   and Navigation" (Wiley, 2001), Ch. 5: 1-D Kalman filter, innovation gate.
+ * - Mahalanobis distance ≡ |innovation|/√S; innovationGate = D² ~ χ²(1).
+ */
+
+const DENORMAL_THRESHOLD = 1e-30;
+
+const update = function ( state, msg ) {
+    // ── Guard ───────────────────────────────────────────────────────────
+    if ( state.disable || state.pause ) return state;
+
+    const z = msg[ state.x ];
+
+    // Reset health flag on each update
+    state.inputValidationFailed = false;
+
+    // ── Fault handling: NaN, Infinity, undefined ────────────────────────
+    // Missing data → prediction-only: covariance grows (via the predict
+    // step on the next valid measurement), innovation is NaN downstream.
+    if ( !Number.isFinite( z ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // ── Control input (optional, defaults to 0) ─────────────────────────
+    // When absent or invalid, no control influence this tick.
+    // "Control" = any measurable causal influence, not just actuators:
+    // fuel rate → tank level, occupancy → CO₂, current → temperature.
+    const u = state.controlField ? ( msg[ state.controlField ] ?? 0 ) : 0;
+    const uSafe = Number.isFinite( u ) ? u : 0;
+
+    // ── Auto-initialize from first measurement ──────────────────────────
+    // No prior estimate needed: x₀ = z/H, P₀ = R/H².
+    // Innovation is 0 (no prediction to compare against).
+    if ( !state.isInitialized ) {
+        state.xHat = z / state.H;
+        state.P = state.R / ( state.H * state.H );
+        state.innovation = 0;
+        state.innovationGate = 0;
+        state.isInitialized = true;
+        state.updateCount += 1;
+        return state;
+    }
+
+    // ── PREDICT ─────────────────────────────────────────────────────────
+    // State prediction:  x̂(k|k-1) = F·x̂(k-1) + G·u(k)
+    // Covariance prediction: P(k|k-1) = F·P(k-1)·F + Q
+    const xPred = ( state.F * state.xHat ) + ( state.G * uSafe );
+    let PPred = ( state.F * state.P * state.F ) + state.Q;
+
+    // Clamp covariance to valid range
+    if ( PPred > state.Pmax ) PPred = state.Pmax;
+    if ( PPred < state.Pmin ) PPred = state.Pmin;
+
+    // ── INNOVATE (always computed, always stored) ───────────────────────
+    // Innovation: ν = z - H·x̂(k|k-1)
+    // Innovation covariance: S = H·P(k|k-1)·H + R
+    // Innovation gate: ν²/S ~ χ²(1) when model is correct
+    const innovation = z - ( state.H * xPred );
+    const S = ( state.H * PPred * state.H ) + state.R;
+    const innovationGate = ( innovation * innovation ) / S;
+
+    // Store BEFORE branching — downstream always sees what reality
+    // looked like, regardless of the filter's gate decision.
+    state.innovation = innovation;
+    state.innovationGate = innovationGate;
+
+    // ── OUTLIER GATE ────────────────────────────────────────────────────
+    // Mahalanobis distance² > χ²(1) threshold → statistically unlikely
+    if ( innovationGate > state.chi2Threshold ) {
+        state.outlierCount += 1;
+
+        if ( state.followMode ) {
+            // Follow mode: reset estimate to track the jump.
+            // Use case: systems with legitimate step changes (valve
+            // positions, load changes, operating mode switches).
+            state.xHat = z / state.H;
+            state.P = state.R / ( state.H * state.H );
+        } else {
+            // Exclude mode: reject measurement, advance with prediction.
+            // Time marches on — xHat and P reflect the predict-only state.
+            // Innovation IS published (stored above) so downstream sees
+            // the anomalous measurement even though the filter ignored it.
+            // Use case: continuous processes where outliers are sensor
+            // glitches (temperature, pressure, tank level).
+            state.xHat = xPred;
+            state.P = PPred;
+            state.updateCount += 1;
+            return state;
+        }
+    } else {
+        // ── NORMAL KALMAN UPDATE ────────────────────────────────────
+        // Kalman gain: K = P(k|k-1)·H / S
+        // State update: x̂(k) = x̂(k|k-1) + K·ν
+        // Covariance update: P(k) = (1 - K·H)·P(k|k-1)
+        const K = ( PPred * state.H ) / S;
+        state.xHat = xPred + ( K * innovation );
+        state.P = ( 1 - ( K * state.H ) ) * PPred;
+    }
+
+    // ── Denormal flushing ───────────────────────────────────────────────
+    // Prevents 100x slowdown on x86/ARM when P approaches zero.
+    if ( Math.abs( state.P ) < DENORMAL_THRESHOLD ) state.P = 0;
+
+    state.updateCount += 1;
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/kernel/index.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Public API for kernel node.
+ *
+ * Re-exports all lifecycle functions and shared control signals.
+ */
+
+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/kernel/init.js

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Initialization for kernel node.
+ *
+ * Validates the spec, resolves the kernel (from preset name or custom array),
+ * reverses it for efficient sequential memory access during convolution,
+ * allocates a doubled ring buffer (2 × kernelLength) that enables a
+ * branch-free contiguous read window during convolution (see update.js for
+ * the "duplicated head" pattern), and returns the fully initialized state.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import PRESETS from './presets.js';
+import { resolveScalar, resolveArray } from '../../core/utils/options/resolve-field-keyed.js';
+
+const init = function ( spec ) {
+    // 1. Validate
+    validateSpec( spec, introspect );
+
+    // 2. Initialize state
+    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;
+
+    // Store field name and output configuration
+    state.x = spec.from.x;
+    state.stats = spec.stats;
+
+    // Get kernel from preset or custom kernel
+    // Supports both direct and field-keyed specification
+    const presetSpec = resolveScalar( spec.preset, state.x );
+    const kernelSpec = resolveArray( spec.kernel, state.x );
+
+    // Reverse kernel for efficient sequential memory access during convolution
+    state.kernel = presetSpec ?
+        PRESETS[ presetSpec ].slice().reverse() :
+        kernelSpec.slice().reverse();
+    // For debugging/introspection
+    state.presetName = presetSpec || 'userDefined';
+
+    // Pre-compute kernel length for hot path
+    state.kernelLength = state.kernel.length;
+
+    // Doubled ring buffer: size is the logical window length, buffer holds
+    // 2 × size doubles so every push writes to both halves (see update.js).
+    // Preserves the { size, buffer, head, used } shape expected by
+    // publishTo (via isNotFull) and reset (via ring.reset).
+    state.ring = Object.create( null );
+    state.ring.size = state.kernelLength;
+    state.ring.buffer = new Float64Array( state.kernelLength * 2 );
+    state.ring.head = 0;
+    state.ring.used = 0;
+
+    // Result storage
+    state.result = 0;
+
+    // Node type for debugging
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;