@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/appraise/introspect.js

@@ -0,0 +1,352 @@
+// nodes/appraise/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for the appraise node.
+ *
+ * Defines supported stats, control methods, capabilities, and DSL schema
+ * for a two-layer SNN that accumulates evidence from multiple detection
+ * signals and produces a stable conviction score.
+ *
+ * L1 receptor neurons (per source) provide LIF spiking, BLI intensity,
+ * and rate persistence. L2 decision neuron accumulates weighted spikes
+ * with MM readout. Signed weights enable excitatory/inhibitory synapses.
+ *
+ * Key differences from standard nodes:
+ *   - `from.x`: string array of source field names (like esPairwiseCorrelation)
+ *   - `sources`: keyed object with per-source config (signed weights)
+ *   - `thresholds`: monitor / degraded / critical classification
+ *   - `l2HalfLife`: optional L2 membrane decay (defaults to max L1 tau)
+ *   - `messageRate`: optional messages per timestamp unit (for warmup calc)
+ *
+ * @see ADR-004
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+import { DEVIATION_TYPES } from './deviation.js';
+
+// ── Supported Statistics ────────────────────────────────────────────────────
+
+const SUPPORTED_STATS = [
+    'combined', 'state', 'charge',
+    'rate', 'membrane', 'calibrating'
+];
+
+const STAT_DESCRIPTIONS = {
+    combined: 'Conviction score via MM readout [0, 1)',
+    state: 'Threshold classification label (Normal/Monitor/Degraded/Critical)',
+    charge: 'Per-source BLI charge (published as {storeAs}_{sourceField} scalars)',
+    rate: 'Per-source firing rate (published as {storeAs}_{sourceField} scalars)',
+    membrane: 'L2 decision neuron raw membrane potential',
+    calibrating: 'Burn-in calibration active flag (boolean)'
+};
+
+// ── Control Methods ─────────────────────────────────────────────────────────
+
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears all charges and resets state to Normal',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+// ── Node Identity ───────────────────────────────────────────────────────────
+
+const NODE_TYPE = 'Appraise';
+
+// ── Capabilities ────────────────────────────────────────────────────────────
+
+const CAPABILITIES = {
+    description: 'Two-layer SNN that accumulates evidence from multiple detection signals into a stable conviction score',
+    features: [
+        'L1 receptor neurons: LIF spiking + BLI intensity + Rate persistence per source',
+        'L2 decision neuron: unbounded leaky accumulation with MM readout',
+        'Excitatory/inhibitory synapses via signed weights',
+        'Burn-in calibration: Theta learned from warmup baseline',
+        'Michaelis-Menten normalization — one theta per source',
+        'Five deviation types: identity, absolute, highExceedance, lowExceedance, bandExceedance',
+        'Exponential decay with configurable half-life (global default, per-source override)',
+        'Per-source charge and rate published as named scalars — compose categorize downstream for labels',
+        'Zero allocation in hot path'
+    ]
+};
+
+// ── Default Options ─────────────────────────────────────────────────────────
+
+const DEFAULT_OPTIONS = {};
+
+// ── Validators ──────────────────────────────────────────────────────────────
+
+const deviationTypes = Array.from( DEVIATION_TYPES );
+const isDeviationType = validators.oneOf( deviationTypes );
+
+// Inline validator: non-zero finite number (allows negative for inhibitory synapses)
+const nonZeroFinite = ( v ) => ( Number.isFinite( v ) && ( v !== 0 ) );
+
+// ── 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,
+                    maxItems: 20,
+                    itemSchema: {
+                        type: 'string',
+                        validator: validators.noSpaces,
+                        error: 'source field name must not contain spaces'
+                    }
+                }
+            }
+        },
+        sources: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            maxProperties: 20,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    deviation: {
+                        type: 'string',
+                        required: true,
+                        validator: isDeviationType,
+                        error: `source.deviation must be one of: ${deviationTypes.join( ', ' )}`
+                    },
+                    theta: {
+                        type: 'number',
+                        required: true,
+                        validator: validators.positive,
+                        error: 'source.theta must be a positive number'
+                    },
+                    weight: {
+                        type: 'number',
+                        required: true,
+                        validator: nonZeroFinite,
+                        error: 'source.weight must be a non-zero finite number'
+                    },
+                    halfLife: {
+                        type: 'number',
+                        required: false,
+                        validator: validators.positive,
+                        error: 'source.halfLife must be a positive number'
+                    },
+                    baseline: {
+                        type: 'number',
+                        required: false,
+                        validator: validators.isFinite,
+                        error: 'source.baseline must be a finite number'
+                    },
+                    band: {
+                        type: 'object',
+                        required: false,
+                        properties: {
+                            lower: {
+                                type: 'number',
+                                required: true,
+                                validator: validators.isFinite,
+                                error: 'band.lower must be a finite number'
+                            },
+                            upper: {
+                                type: 'number',
+                                required: true,
+                                validator: validators.isFinite,
+                                error: 'band.upper must be a finite number'
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        halfLife: {
+            type: 'number',
+            required: true,
+            validator: validators.positive,
+            error: 'halfLife must be a positive number'
+        },
+        l2HalfLife: {
+            type: 'number',
+            required: false,
+            validator: validators.positive,
+            error: 'l2HalfLife must be a positive number'
+        },
+        messageRate: {
+            type: 'number',
+            required: false,
+            validator: validators.positive,
+            error: 'messageRate must be a positive number'
+        },
+        thresholds: {
+            type: 'object',
+            required: true,
+            properties: {
+                monitor: {
+                    type: 'object',
+                    required: true,
+                    properties: {
+                        at: {
+                            type: 'number',
+                            required: true,
+                            validator: validators.positive,
+                            error: 'thresholds.monitor.at must be a positive number'
+                        },
+                        action: {
+                            type: 'string',
+                            required: true,
+                            validator: validators.nonEmptyString,
+                            error: 'thresholds.monitor.action must be a non-empty string'
+                        }
+                    }
+                },
+                degraded: {
+                    type: 'object',
+                    required: true,
+                    properties: {
+                        at: {
+                            type: 'number',
+                            required: true,
+                            validator: validators.positive,
+                            error: 'thresholds.degraded.at must be a positive number'
+                        },
+                        action: {
+                            type: 'string',
+                            required: true,
+                            validator: validators.nonEmptyString,
+                            error: 'thresholds.degraded.action must be a non-empty string'
+                        }
+                    }
+                },
+                critical: {
+                    type: 'object',
+                    required: true,
+                    properties: {
+                        at: {
+                            type: 'number',
+                            required: true,
+                            validator: validators.positive,
+                            error: 'thresholds.critical.at must be a positive number'
+                        },
+                        action: {
+                            type: 'string',
+                            required: true,
+                            validator: validators.nonEmptyString,
+                            error: 'thresholds.critical.action must be a non-empty string'
+                        }
+                    }
+                }
+            }
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    crossFieldValidators: [
+        {
+            fields: [ 'thresholds' ],
+            validator: ( spec ) => {
+                const { monitor, degraded, critical } = spec.thresholds;
+                return ( monitor.at < degraded.at ) && ( degraded.at < critical.at );
+            },
+            error: 'Threshold ordering must be: monitor.at < degraded.at < critical.at'
+        },
+        {
+            fields: [ 'from.x' ],
+            validator: ( spec ) => {
+                const fields = spec.from.x;
+                return ( new Set( fields ) ).size === fields.length;
+            },
+            error: 'Source field names in from.x must be unique'
+        },
+        {
+            fields: [ 'from.x', 'sources' ],
+            validator: ( spec ) => {
+                const fields = spec.from.x;
+                const keys = Object.keys( spec.sources );
+                if ( fields.length !== keys.length ) return false;
+                return fields.every( ( f ) => spec.sources[ f ] !== undefined );
+            },
+            error: 'Every from.x entry must have a matching key in sources, and vice versa'
+        },
+        {
+            fields: [ 'sources' ],
+            validator: ( spec ) => Object.values( spec.sources ).every( ( cfg ) => {
+                if ( cfg.deviation === 'highExceedance' || cfg.deviation === 'lowExceedance' ) {
+                    return cfg.baseline !== undefined;
+                }
+                return true;
+            } ),
+            error: 'highExceedance and lowExceedance deviation types require a baseline value'
+        },
+        {
+            fields: [ 'sources' ],
+            validator: ( spec ) => Object.values( spec.sources ).every( ( cfg ) => {
+                if ( cfg.deviation === 'bandExceedance' ) {
+                    return ( cfg.band !== undefined ) &&
+                           ( typeof cfg.band === 'object' ) &&
+                           ( cfg.band.lower < cfg.band.upper );
+                }
+                return true;
+            } ),
+            error: 'bandExceedance deviation type requires a band with lower < upper'
+        },
+        {
+            fields: [ 'sources' ],
+            validator: ( spec ) => Object.values( spec.sources ).some( ( cfg ) => cfg.weight > 0 ),
+            error: 'At least one source must have a positive (excitatory) weight'
+        }
+    ],
+
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } )
+};
+
+// ── 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()
+} );
+export { DEFAULT_OPTIONS };
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,93 @@
+// nodes/appraise/publish-to.js
+
+/**
+ * @fileoverview Publishes appraise node outputs to the message.
+ *
+ * Six stats: combined (number), state (string), charge (per-source scalars),
+ * rate (per-source scalars), membrane (number), calibrating (boolean).
+ *
+ * charge and rate are published as per-source named scalars using pre-built
+ * field names ({storeAs}_{sourceField}), enabling downstream categorize
+ * nodes and proper float64 QuestDB columns per source.
+ *
+ * On validation failure, all numeric stats get NaN — combined, membrane,
+ * and all per-source charge/rate fields. String and boolean stats are skipped.
+ *
+ * @see ADR-004
+ */
+
+/**
+ * Publishes computed values to the output message.
+ *
+ * @param {Object} state - Node state
+ * @param {Object} msg - Output message to populate
+ */
+const publishTo = function ( state, msg ) {
+    // Guard: skip if disabled
+    if ( state.disable ) return;
+
+    const stats = state.stats;
+    const n = state.sourceCount;
+
+    // Custom NaN publishing — cannot use publishNaN helper because charge
+    // and rate are per-source named scalars (chargeFields/rateFields arrays),
+    // not scalar entries in state.stats.
+    if ( state.inputValidationFailed ) {
+        if ( stats.combined ) {
+            msg[ stats.combined.storeAs ] = NaN;
+        }
+        if ( stats.membrane ) {
+            msg[ stats.membrane.storeAs ] = NaN;
+        }
+        if ( stats.charge ) {
+            const fields = state.chargeFields;
+            for ( let i = 0; i < n; i += 1 ) {
+                msg[ fields[ i ] ] = NaN;
+            }
+        }
+        if ( stats.rate ) {
+            const fields = state.rateFields;
+            for ( let i = 0; i < n; i += 1 ) {
+                msg[ fields[ i ] ] = NaN;
+            }
+        }
+        return;
+    }
+
+    // Publish configured stats
+    if ( stats.combined ) {
+        msg[ stats.combined.storeAs ] = state.combined;
+    }
+
+    if ( stats.state ) {
+        msg[ stats.state.storeAs ] = state.stateName;
+    }
+
+    // Per-source charge scalars (pre-built field names from init)
+    if ( stats.charge ) {
+        const fields = state.chargeFields;
+        const charges = state.charges;
+        for ( let i = 0; i < n; i += 1 ) {
+            msg[ fields[ i ] ] = charges[ i ];
+        }
+    }
+
+    if ( stats.membrane ) {
+        msg[ stats.membrane.storeAs ] = state.l2Membrane;
+    }
+
+    // Per-source rate scalars (pre-built field names from init)
+    if ( stats.rate ) {
+        const fields = state.rateFields;
+        const rates = state.rates;
+        for ( let i = 0; i < n; i += 1 ) {
+            msg[ fields[ i ] ] = rates[ i ];
+        }
+    }
+
+    if ( stats.calibrating ) {
+        msg[ stats.calibrating.storeAs ] = state.calibrating;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/appraise/receptor.js

@@ -0,0 +1,69 @@
+// nodes/appraise/receptor.js
+
+/**
+ * @fileoverview L1 receptor neuron processing for the SNN appraise architecture.
+ *
+ * Each source has three parallel channels driven from the same MM-normalised input:
+ *   LIF (Leaky Integrate-and-Fire) — graded spikes forwarded to L2 decision neuron
+ *   BLI (Bounded Leaky Integrator) — charge in [0, 1] for intensity explanation
+ *   Rate — smoothed firing count for persistence explanation
+ *
+ * LIF uses reset-by-subtraction: on spike, V -= Vth, carrying excess potential
+ * into the next cycle. The graded spike value equals V at the moment of firing
+ * (before subtraction), preserving magnitude information through to L2.
+ *
+ * Both functions are stateless, zero-alloc, and hot-path safe.
+ *
+ * @see Gerstner, W. & Kistler, W.M. (2002). Spiking Neuron Models. Cambridge.
+ */
+
+import { integrate } from './integrate.js';
+
+/**
+ * Processes one receptor neuron: LIF spike + BLI integration + Rate tracking.
+ * Called when a valid, finite input is available for source i.
+ *
+ * @param {Object} state - Node state (mutated: membranes, spikes, fired, charges, rates)
+ * @param {number} i - Source index
+ * @param {number} norm - MM-normalised input from [0, 1)
+ * @param {number} decayFactor - exp( -dt / tau_i ), from [0, 1]
+ */
+const processReceptor = function ( state, i, norm, decayFactor ) {
+    // ── LIF Channel ─────────────────────────────────────────────────────────
+    let v = ( state.membranes[ i ] * decayFactor ) + norm;
+
+    if ( v >= state.VTH ) {
+        state.spikes[ i ] = v;
+        state.fired[ i ] = 1;
+        v -= state.VTH;
+    } else {
+        state.spikes[ i ] = 0;
+        state.fired[ i ] = 0;
+    }
+
+    state.membranes[ i ] = v;
+
+    // ── BLI Channel (intensity) ─────────────────────────────────────────────
+    state.charges[ i ] = integrate( state.charges[ i ], norm, decayFactor );
+
+    // ── Rate Channel (persistence) ──────────────────────────────────────────
+    state.rates[ i ] = ( state.rates[ i ] * decayFactor ) + state.fired[ i ];
+}; // processReceptor()
+
+/**
+ * Pure decay on all channels when no valid input is available for source i.
+ * No spike is emitted, and the fired flag is cleared.
+ *
+ * @param {Object} state - Node state (mutated: membranes, spikes, fired, charges, rates)
+ * @param {number} i - Source index
+ * @param {number} decayFactor - exp( -dt / tau_i ), from [0, 1]
+ */
+const decayReceptor = function ( state, i, decayFactor ) {
+    state.membranes[ i ] *= decayFactor;
+    state.charges[ i ] *= decayFactor;
+    state.rates[ i ] *= decayFactor;
+    state.spikes[ i ] = 0;
+    state.fired[ i ] = 0;
+}; // decayReceptor()
+
+export { processReceptor, decayReceptor };

package/src/nodes/appraise/recompute.js

@@ -0,0 +1,79 @@
+// nodes/appraise/recompute.js
+
+/**
+ * @fileoverview Numerical stability handler for two-layer SNN appraise node.
+ *
+ * Checks for NaN in L1 membranes, charges, and L2 membrane. If any NaN
+ * is detected (catastrophic numerical failure), triggers a full reset.
+ * Otherwise, clamps L1 charges to [0, 1], floors L1 membranes and L2
+ * membrane at 0, and recomputes conviction via MM readout.
+ *
+ * @see ADR-004
+ */
+
+import reset from './reset.js';
+import { readout } from './decision.js';
+
+/**
+ * Clamps state values and recomputes combined conviction.
+ *
+ * @param {Object} state - Node state
+ * @returns {boolean} Always returns true
+ */
+const recompute = function ( state ) {
+    const charges = state.charges;
+    const membranes = state.membranes;
+    const n = state.sourceCount;
+
+    // ── NaN Catastrophe Check ───────────────────────────────────────────────
+    // Check L1 charges, L1 membranes, and L2 membrane
+    if ( Number.isNaN( state.l2Membrane ) ) {
+        reset( state );
+        return true;
+    }
+
+    for ( let i = 0; i < n; i += 1 ) {
+        if ( Number.isNaN( charges[ i ] ) || Number.isNaN( membranes[ i ] ) ) {
+            reset( state );
+            return true;
+        }
+    }
+
+    // ── Clamp L1 Charges to [0, 1] ─────────────────────────────────────────
+    for ( let i = 0; i < n; i += 1 ) {
+        if ( charges[ i ] > 1 ) {
+            charges[ i ] = 1;
+        } else if ( charges[ i ] < 0 ) {
+            charges[ i ] = 0;
+        }
+    }
+
+    // ── Floor L1 Membranes at 0 ─────────────────────────────────────────────
+    for ( let i = 0; i < n; i += 1 ) {
+        if ( membranes[ i ] < 0 ) {
+            membranes[ i ] = 0;
+        }
+    }
+
+    // ── Floor L2 Membrane at 0 ──────────────────────────────────────────────
+    if ( state.l2Membrane < 0 ) {
+        state.l2Membrane = 0;
+    }
+
+    // ── Recompute Conviction via MM Readout ─────────────────────────────────
+    state.combined = readout( state.l2Membrane, state.l2Theta );
+
+    // ── Reclassify State ────────────────────────────────────────────────────
+    const levels = state.thresholdLevels;
+    state.stateName = 'Normal';
+    for ( let i = levels.length - 1; i >= 0; i -= 1 ) {
+        if ( state.combined >= levels[ i ].at ) {
+            state.stateName = levels[ i ].name;
+            break;
+        }
+    }
+
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/appraise/reset.js

@@ -0,0 +1,53 @@
+// nodes/appraise/reset.js
+
+/**
+ * @fileoverview Resets the two-layer SNN appraise node state.
+ *
+ * Clears all L1 state (membranes, spikes, fired, charges, rates) and L2
+ * state (membrane, combined, classification). Zeros the timestamp so the
+ * next message behaves as a cold start (no decay on first message after reset).
+ *
+ * Preserves Theta if already calibrated — the learned baseline does not
+ * change on analytical reset. Same principle as lag node ADR-008.
+ * Only re-enters calibration if warmup was still in progress.
+ *
+ * @see ADR-004
+ */
+
+/**
+ * Resets all appraise computation state to initial values.
+ * Preserves l2Theta and calibrating=false if calibration was complete.
+ *
+ * @param {Object} state - Node state to reset
+ * @returns {boolean} Always returns true (success)
+ */
+const reset = function ( state ) {
+    // ── L1 State ────────────────────────────────────────────────────────────
+    state.membranes.fill( 0 );
+    state.spikes.fill( 0 );
+    state.fired.fill( 0 );
+    state.charges.fill( 0 );
+    state.rates.fill( 0 );
+
+    // ── L2 State ────────────────────────────────────────────────────────────
+    state.l2Membrane = 0;
+
+    // ── Calibration ─────────────────────────────────────────────────────────
+    // Preserve Theta if already calibrated; reset warmup counter if still calibrating
+    if ( state.calibrating ) {
+        state.messageCount = 0;
+    }
+
+    // ── Combined Score & Classification ─────────────────────────────────────
+    state.combined = 0;
+    state.stateName = 'Normal';
+
+    // ── Timing ──────────────────────────────────────────────────────────────
+    state.lastTimestamp = 0;
+    state.hasReceivedMessage = false;
+    state.inputValidationFailed = false;
+
+    return true;
+}; // reset()
+
+export default reset;