@winkjs/composer 0.0.2 → 0.4.0

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

@@ -0,0 +1,149 @@
+// nodes/vector-distance/introspect.js
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** The type of this node */
+const NODE_TYPE = 'Vector Distance';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'mad',        // Mean Absolute Distance
+    'rms',        // Root Mean Square Distance
+    'maximum',    // Maximum Distance (L∞)
+    'cosine',     // Cosine Distance
+    'angular'     // Angular Distance (radians)
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    mad: 'Mean absolute distance between vectors',
+    // For correlations [-1,1]: bounded [0,2]
+    // For general vectors: bounded [0, ∞]
+
+    rms: 'Root mean square distance between vectors',
+    // For correlations [-1,1]: bounded [0,2]
+    // For general vectors: bounded [0, ∞]
+
+    maximum: 'Maximum single element difference',
+    // For correlations [-1,1]: bounded [0,2]
+    // For general vectors: bounded [0, ∞]
+
+    cosine: 'Cosine distance [0,2]',     // Always [0,2] regardless of input
+    angular: 'Angular distance [0,π]'     // Always [0,π] regardless of input
+};
+
+/** 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'
+};
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes multiple distance metrics between numeric vectors',
+    features: [
+        'Five complementary distance metrics (MAD, RMS, Maximum, Cosine, Angular)',
+        'Works with any numeric vectors (correlations, features, histograms, embeddings)',
+        'Direct integration with change detectors (Page-Hinkley, CUSUM, Threshold)'
+    ]
+};
+
+// 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() } );
+
+// DSL Metadata for transpilation
+// Metadata → describes how to build → Specs → initialize → Nodes
+const DSL_METADATA = {
+    // Spec schema for validation
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE,
+        },
+        name: {
+            type: 'string',
+            required: true,
+            minLength: 1,
+            validator: validators.identifier,  // Using standard validator
+            error: 'Name must be a valid identifier'
+        },
+        from: {
+            type: 'object',
+            required: true,
+            properties: {
+                x: {
+                    type: 'string',
+                    required: true,
+                    minLength: 1,
+                    validator: validators.noSpaces,  // Using standard validator
+                    error: 'Field name cannot contain spaces'
+                },
+                y: {
+                    type: 'string',
+                    required: true,
+                    minLength: 1,
+                    validator: validators.noSpaces,  // Using standard validator
+                    error: 'Field name 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,  // Using standard validator
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'from.x', 'from.y' ],
+            validator: ( spec ) => spec.from.x !== spec.from.y,
+            error: 'from.x and from.y must be different fields'
+        },
+        {
+            fields: [ 'stats' ],
+            validator: ( spec ) => {
+                // Ensure no duplicate storeAs values
+                const storeAsValues = Object.values( spec.stats ).map( ( s ) => s.storeAs );
+                return storeAsValues.length === new Set( storeAsValues ).size;
+            },
+            error: 'All storeAs values must be unique'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    // Pattern: NAME_X_Y_OUTPUTS_OPTIONS -> (name, x, y, stats, options)
+    buildSpec: ( name, x, y, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x, y },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ({ ...DSL_METADATA });

package/src/nodes/vector-distance/publish-to.js

@@ -0,0 +1,35 @@
+// nodes/vector-distance/publish-to.js
+
+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;
+    }
+
+    // Publish each configured statistic directly
+    if ( state.stats.mad ) {
+        msg[ state.stats.mad.storeAs ] = state.distances.mad;
+    }
+
+    if ( state.stats.rms ) {
+        msg[ state.stats.rms.storeAs ] = state.distances.rms;
+    }
+
+    if ( state.stats.maximum ) {
+        msg[ state.stats.maximum.storeAs ] = state.distances.maximum;
+    }
+
+    if ( state.stats.cosine ) {
+        msg[ state.stats.cosine.storeAs ] = state.distances.cosine;
+    }
+
+    if ( state.stats.angular ) {
+        msg[ state.stats.angular.storeAs ] = state.distances.angular;
+    }
+}; // publishTo()
+
+export default publishTo;

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

@@ -0,0 +1,11 @@
+// nodes/vector-distance/recompute.js
+
+const recompute = function ( _state ) {
+    // For correlation distance, there's no accumulated state to recompute
+    // Each update is independent
+    // This function exists for API consistency
+
+    return true;
+}; // recompute()
+
+export default recompute;

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

@@ -0,0 +1,20 @@
+// nodes/vector-distance/reset.js
+
+const reset = function ( state ) {
+    // Reset all distance values
+    state.distances.mad = 0;
+    state.distances.rms = 0;
+    state.distances.maximum = 0;
+    state.distances.cosine = 0;
+    state.distances.angular = 0;
+
+    // Reset computation flag
+    state.computed = false;
+
+    // Reset workspace values
+    state.accumulator.fill( 0 );
+
+    return true;
+}; // reset()
+
+export default reset;

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

@@ -0,0 +1,139 @@
+// nodes/vector-distance/update.js
+
+/* eslint-disable no-bitwise */
+
+/**
+ * vector-distance / update.js
+ *
+ * Purpose
+ * Compute distances between two vectors in a single pass:
+ * - Maximum single element difference
+ *      - For correlations [-1,1]: bounded [0,2]
+ *      - For general vectors: bounded [0, ∞]
+ * - RMS distance between vectors
+ *      - For correlations [-1,1]: bounded [0,2]
+ *      - For general vectors: bounded [0, ∞]
+ * - MAD distance between vectors
+ *      - For correlations [-1,1]: bounded [0,2]
+ *      - For general vectors: bounded [0, ∞]
+ * - Angular distance [0,π] regardless of input
+ * - Cosine distance [0,2] regardless of input
+ */
+
+// ---- slot indices for Float64 accumulator --------------
+const ACC_SUM_ABS = 0;
+const ACC_SUM_SQ  = 1;
+const ACC_MAX     = 2;
+const ACC_DOT     = 3;
+const ACC_N1      = 4;
+const ACC_N2      = 5;
+
+// ---- helpers ----------------------------------------------------------------
+
+/**
+ * Quick structural validation. Strict same-length requirement.
+ * Returns null to indicate "do nothing" (pass-through).
+ */
+const validateVectors = function ( state, msg ) {
+    const xVal = msg[ state.x ];
+    const yVal = msg[ state.y ];
+    if ( !xVal || !yVal ) return null;
+    const nx = ( typeof xVal.length === 'number' ) ? xVal.length : -1;
+    const ny = ( typeof yVal.length === 'number' ) ? yVal.length : -1;
+    if ( ( nx <= 0 ) || ( ny <= 0 ) || ( nx !== ny ) ) return null;
+
+    for ( let i = 0; i < nx; i += 1 ) if ( !Number.isFinite( xVal[ i ] ) ) return null;
+    for ( let i = 0; i < nx; i += 1 ) if ( !Number.isFinite( yVal[ i ] ) ) return null;
+    return { xVal, yVal, n: nx };
+}; // validateVectors()
+
+/**
+ * Tight single-pass accumulation. No type checks inside the loop
+ * (assumes upstream generated numeric vectors).
+ */
+const accumulate = function ( acc, v1, v2, n, mask ) {
+    for ( let i = 0; i < n; i += 1 ) {
+        const a = v1[ i ];
+        const b = v2[ i ];
+        const d = ( a - b );
+
+        if ( ( mask & 1 ) !== 0 ) {
+            const ad = Math.abs( d );
+            acc[ ACC_SUM_ABS ] += ad;
+            if ( ad > acc[ ACC_MAX ] ) acc[ ACC_MAX ] = ad;
+        }
+        if ( ( mask & 2 ) !== 0 ) {
+            acc[ ACC_SUM_SQ ] += ( d * d );
+        }
+        if ( ( mask & 4 ) !== 0 ) {
+            acc[ ACC_DOT ] += ( a * b );
+            acc[ ACC_N1 ]  += ( a * a );
+            acc[ ACC_N2 ]  += ( b * b );
+        }
+    }
+}; // accumulate()
+
+/**
+ * Convert accumulators into requested distances and update state.
+ * Clamps cosine similarity to avoid NaN from acos due to FP error.
+ */
+const finalize = function ( state, acc, n ) {
+    if ( state.stats.mad ) {
+        state.distances.mad = acc[ ACC_SUM_ABS ] / n;
+    }
+    if ( state.stats.rms ) {
+        state.distances.rms = Math.sqrt( acc[ ACC_SUM_SQ ] / n );
+    }
+    if ( state.stats.maximum ) {
+        state.distances.maximum = acc[ ACC_MAX ];
+    }
+
+    if ( ( state.mask & 4 ) !== 0 ) {
+        const n1 = acc[ ACC_N1 ];
+        const n2 = acc[ ACC_N2 ];
+
+        // Zero-vector policy: treat as no directional information -> zero distances
+        if ( ( n1 === 0 ) || ( n2 === 0 ) ) {
+            if ( state.stats.cosine ) state.distances.cosine = 0;
+            if ( state.stats.angular ) state.distances.angular = 0;
+            return;
+        }
+
+        const denom = Math.sqrt( n1 ) * Math.sqrt( n2 );
+        let cosSim = acc[ ACC_DOT ] / denom;
+
+        // Clamp for numerical safety
+        if ( cosSim > 1 ) cosSim = 1;
+        else if ( cosSim < -1 ) cosSim = -1;
+
+        if ( state.stats.cosine ) state.distances.cosine = 1 - cosSim;
+        if ( state.stats.angular ) state.distances.angular = Math.acos( cosSim );
+    }
+}; // finalize()
+
+// ---- update (export default) ------------------------------------------------
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    // Reset on each update
+    state.inputValidationFailed = false;
+    const validated = validateVectors( state, msg );
+    if ( !validated ) {
+        // Reset on the downstream node may cause this state.
+        // Will wait until warms up or error goes away.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    const { xVal, yVal, n } = validated;
+
+    const acc = state.accumulator;
+    acc.fill( 0 );
+    accumulate( acc, xVal, yVal, n, state.mask );
+    finalize( state, acc, n );
+
+    state.computed = true;
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/winnow/index.js

@@ -0,0 +1,12 @@
+// nodes/winnow/index.js
+
+export { default as init } from './init.js';
+export { default as update } from './update.js';
+export { default as publishTo } from './publish-to.js';
+export { default as reset } from './reset.js';
+export { default as recompute } from './recompute.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/winnow/init.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Initialisation for the winnow node.
+ *
+ * Creates per-partition state: anchor tracking, slope projection,
+ * and adaptive threshold configuration. All allocations happen here
+ * — update() and publishTo() are zero-allocation hot paths.
+ */
+
+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';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    const state = Object.create( null );
+
+    // ── Standard flags (all nodes) ──────────────────────────────────
+    state.disable = false;
+    state.pause = false;
+    state.inputValidationFailed = false;
+
+    // ── Configuration from spec ─────────────────────────────────────
+    state.x = spec.from.x;
+    state.stats = spec.stats;
+
+    // Pre-built field names — no string ops in hot path
+    state.slopeField = spec.slopeField ?? introspect.DEFAULT_OPTIONS.slopeField;
+    state.noiseField = spec.noiseField ?? introspect.DEFAULT_OPTIONS.noiseField;
+    state.dirField = spec.dirField ?? introspect.DEFAULT_OPTIONS.dirField;
+    state.gateField = spec.gateField ?? introspect.DEFAULT_OPTIONS.gateField;
+
+    // Scalar options (support field-keyed specification)
+    state.chi2Threshold = resolveScalar( spec.chi2Threshold, state.x ) ??
+        introspect.DEFAULT_OPTIONS.chi2Threshold;
+    state.tightenBase = resolveScalar( spec.tightenBase, state.x ) ??
+        introspect.DEFAULT_OPTIONS.tightenBase;
+    state.maxGap = resolveScalar( spec.maxGap, state.x ) ??
+        introspect.DEFAULT_OPTIONS.maxGap;
+
+    // ── Pre-compiled tunable ────────────────────────────────────────
+    const resolvedK = resolveScalar( spec.K, state.x ) ?? introspect.DEFAULT_OPTIONS.K;
+    state.KFn = asTunable( resolvedK );
+    state.K = typeof resolvedK === 'number' ? resolvedK : introspect.DEFAULT_OPTIONS.K;
+    state.tunableErrorLogged = false;
+
+    // ── Accumulated state (per-partition core) ──────────────────────
+    state.anchor = null;
+    state.anchorSlope = 0;
+    state.anchorTime = 0;
+    state.lastPassedAt = 0;
+    state.prevDirection = null;
+    state.counter = 0;
+
+    // ── Outputs ─────────────────────────────────────────────────────
+    state.deviation = 0;
+    state.predicted = 0;
+    state.significant = false;
+
+    // ── 1-sample buffer for spike-region anchoring ──────────────────
+    // When bufferPrev is true, winnow holds the previous tick's input
+    // value and timestamp. On Check 2 (chi-squared gate fire), it
+    // publishes xPrev/tPrev — providing the (k-1) anchor that
+    // eliminates linear-interpolation overshoot around spikes.
+    state.bufferPrev = spec.bufferPrev ?? introspect.DEFAULT_OPTIONS.bufferPrev;
+    state.timestampField = spec.timestampField ?? null;
+    state.bufferedX = NaN;
+    state.bufferedT = NaN;
+    state.keptByGate = false;
+    state.xPrev = NaN;
+    state.tPrev = NaN;
+    state.hasXPrev = spec.stats.xPrev !== undefined;
+    state.hasTPrev = spec.stats.tPrev !== undefined;
+
+    // ── Metadata ────────────────────────────────────────────────────
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;