@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/appraise/decision.js

@@ -0,0 +1,66 @@
+// nodes/appraise/decision.js
+
+/**
+ * @fileoverview L2 decision neuron for the SNN appraise architecture.
+ *
+ * A single non-spiking neuron that accumulates weighted spike input from
+ * all L1 receptor neurons. Signed weights enable excitatory (+) and
+ * inhibitory (-) synapses — failure evidence drives conviction up,
+ * recovery evidence drives it down.
+ *
+ * Pipeline: synaptic current -> leaky membrane -> MM readout.
+ *   I2 = sum( wi * si ) / sum( |wi| )   normalised synaptic current
+ *   V2 = max( 0, V2 * decay + I2 )      unbounded leaky accumulation, floored at 0
+ *   conviction = V2 / ( V2 + Theta )     MM readout bounds to [0, 1)
+ *
+ * All functions are pure, stateless, and zero-alloc.
+ *
+ * @see Dayan, P. & Abbott, L.F. (2001). Theoretical Neuroscience. MIT Press.
+ */
+
+/**
+ * Computes normalised synaptic current from L1 graded spikes.
+ * Signed weights allow excitatory (positive) and inhibitory (negative) inputs.
+ *
+ * @param {Float64Array} spikes - Per-source graded spike values
+ * @param {Float64Array} weights - Signed weights (+ excitatory, - inhibitory)
+ * @param {number} totalAbsWeight - Pre-computed sum( |wi| )
+ * @param {number} n - Source count
+ * @returns {number} Normalised synaptic current I2
+ */
+const computeSynapticCurrent = function ( spikes, weights, totalAbsWeight, n ) {
+    let sum = 0;
+    for ( let i = 0; i < n; i += 1 ) {
+        sum += weights[ i ] * spikes[ i ];
+    }
+    return sum / totalAbsWeight;
+}; // computeSynapticCurrent()
+
+/**
+ * Updates the L2 membrane potential with leaky accumulation.
+ * Floors at zero — negative conviction is not meaningful.
+ *
+ * @param {number} membrane - Current V2
+ * @param {number} current - Synaptic current I2
+ * @param {number} decayFactor - exp( -dt / tau2 )
+ * @returns {number} Updated V2, always >= 0
+ */
+const updateMembrane = function ( membrane, current, decayFactor ) {
+    const v = ( membrane * decayFactor ) + current;
+    return v > 0 ? v : 0;
+}; // updateMembrane()
+
+/**
+ * Michaelis-Menten readout — bounds unbounded membrane to [0, 1).
+ * Guards against theta <= 0 (returns 0 to prevent division by zero).
+ *
+ * @param {number} membrane - V2, always >= 0
+ * @param {number} theta - Half-saturation constant (must be > 0)
+ * @returns {number} Conviction from [0, 1)
+ */
+const readout = function ( membrane, theta ) {
+    if ( theta <= 0 ) return 0;
+    return membrane / ( membrane + theta );
+}; // readout()
+
+export { computeSynapticCurrent, updateMembrane, readout };

package/src/nodes/appraise/deviation.js

@@ -0,0 +1,140 @@
+// nodes/appraise/deviation.js
+
+/**
+ * @fileoverview Pure deviation functions for the SNN appraise node.
+ *
+ * Each deviation type converts a raw detection signal into a non-negative
+ * "badness" value. All five functions are module-level singletons shared
+ * across every partition instance — no per-instance closures.
+ *
+ * The monomorphic dispatch function `computeDeviation` uses a switch on
+ * dense integer type indices (0–4), enabling V8 to generate a jump table
+ * and inline the entire dispatch into the caller's loop.
+ *
+ * Parameter encoding for typed arrays:
+ *   identity, absolute       — p1 and p2 unused (0 from Float64Array default)
+ *   highExceedance           — p1 = baseline
+ *   lowExceedance            — p1 = baseline
+ *   bandExceedance           — p1 = lower, p2 = upper
+ */
+
+// ── Type Constants (dense integers for switch jump table) ───────────────────
+
+const IDENTITY = 0;
+const ABSOLUTE = 1;
+const HIGH_EXCEEDANCE = 2;
+const LOW_EXCEEDANCE = 3;
+const BAND_EXCEEDANCE = 4;
+
+// ── Deviation Type Set (consumed by introspect.js for validation) ───────────
+
+const DEVIATION_TYPES = new Set( [
+    'identity',
+    'absolute',
+    'highExceedance',
+    'lowExceedance',
+    'bandExceedance'
+] );
+
+// ── String-to-Index Lookup (used at init time only) ─────────────────────────
+
+const DEVIATION_TYPE_INDEX = Object.create( null );
+DEVIATION_TYPE_INDEX.identity = IDENTITY;
+DEVIATION_TYPE_INDEX.absolute = ABSOLUTE;
+DEVIATION_TYPE_INDEX.highExceedance = HIGH_EXCEEDANCE;
+DEVIATION_TYPE_INDEX.lowExceedance = LOW_EXCEEDANCE;
+DEVIATION_TYPE_INDEX.bandExceedance = BAND_EXCEEDANCE;
+
+// ── Pure Deviation Functions (module-level, shared across all instances) ────
+
+/**
+ * Identity — raw is already non-negative badness. Clamps negative to 0.
+ *
+ * @param {number} raw - Raw signal value
+ * @returns {number} Non-negative deviation
+ */
+const identity = ( raw ) => ( raw > 0 ? raw : 0 );
+
+/**
+ * Absolute — both directions are bad.
+ *
+ * @param {number} raw - Raw signal value
+ * @returns {number} Non-negative deviation
+ */
+const absolute = ( raw ) => Math.abs( raw );
+
+/**
+ * High exceedance — only exceeding a baseline is bad.
+ *
+ * @param {number} raw - Raw signal value
+ * @param {number} baseline - Reference value (p1)
+ * @returns {number} Non-negative deviation
+ */
+const highExceedance = function ( raw, baseline ) {
+    const d = raw - baseline;
+    return d > 0 ? d : 0;
+}; // highExceedance()
+
+/**
+ * Low exceedance — only dropping below a baseline is bad.
+ *
+ * @param {number} raw - Raw signal value
+ * @param {number} baseline - Reference value (p1)
+ * @returns {number} Non-negative deviation
+ */
+const lowExceedance = function ( raw, baseline ) {
+    const d = baseline - raw;
+    return d > 0 ? d : 0;
+}; // lowExceedance()
+
+/**
+ * Band exceedance — normal is a range; either direction is bad.
+ *
+ * @param {number} raw - Raw signal value
+ * @param {number} lower - Lower bound of normal range (p1)
+ * @param {number} upper - Upper bound of normal range (p2)
+ * @returns {number} Non-negative deviation
+ */
+const bandExceedance = function ( raw, lower, upper ) {
+    const above = raw - upper;
+    const below = lower - raw;
+    return ( above > 0 ? above : 0 ) + ( below > 0 ? below : 0 );
+}; // bandExceedance()
+
+// ── Monomorphic Dispatch ────────────────────────────────────────────────────
+
+/**
+ * Computes deviation via switch dispatch on integer type index.
+ * V8 compiles dense-integer switch as a jump table; the single call site
+ * is monomorphic, so the entire function (including named function calls)
+ * is inlined into the caller's loop body.
+ *
+ * @param {number} type - Deviation type index (0–4, from Uint8Array)
+ * @param {number} raw - Raw signal value
+ * @param {number} p1 - Parameter 1 (baseline or band.lower, 0 if unused)
+ * @param {number} p2 - Parameter 2 (band.upper, 0 if unused)
+ * @returns {number} Non-negative deviation
+ */
+const computeDeviation = function ( type, raw, p1, p2 ) {
+    switch ( type ) {
+        case IDENTITY:
+            return identity( raw );
+        case ABSOLUTE:
+            return absolute( raw );
+        case HIGH_EXCEEDANCE:
+            return highExceedance( raw, p1 );
+        case LOW_EXCEEDANCE:
+            return lowExceedance( raw, p1 );
+        case BAND_EXCEEDANCE:
+            return bandExceedance( raw, p1, p2 );
+        default:
+            return 0;
+    }
+}; // computeDeviation()
+
+export {
+    computeDeviation,
+    identity, absolute, highExceedance, lowExceedance, bandExceedance,
+    DEVIATION_TYPES, DEVIATION_TYPE_INDEX,
+    IDENTITY, ABSOLUTE, HIGH_EXCEEDANCE, LOW_EXCEEDANCE, BAND_EXCEEDANCE
+};

package/src/nodes/appraise/index.js

@@ -0,0 +1,23 @@
+// nodes/appraise/index.js
+
+/**
+ * @fileoverview Appraise node module exports.
+ *
+ * Two-layer SNN that accumulates evidence from multiple detection signals
+ * into a stable conviction score. L1 receptor neurons (LIF + BLI + Rate)
+ * feed an L2 decision neuron with signed weights (excitatory/inhibitory)
+ * and MM readout. Burn-in calibration derives Theta from warmup baseline.
+ *
+ * @see ADR-004
+ */
+
+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';

package/src/nodes/appraise/init.js

@@ -0,0 +1,165 @@
+// nodes/appraise/init.js
+
+/**
+ * @fileoverview Initializes the two-layer SNN appraise node state.
+ *
+ * Validates the spec, resolves deviation type indices and parameters into
+ * typed arrays, pre-allocates all typed arrays for L1 receptor neurons
+ * (membranes, spikes, fired, charges, rates) and L2 decision neuron
+ * (membrane, tau, theta). Computes signed weight infrastructure
+ * (absWeights, totalAbsWeight) and calibration parameters
+ * (warmupSamples, cTarget). All allocation happens here —
+ * the hot path is zero-alloc.
+ *
+ * @see ADR-004
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { DEVIATION_TYPE_INDEX } from './deviation.js';
+import { computeWarmupSamples, deriveCTarget } from './calibrate.js';
+
+/**
+ * Initializes the appraise node state from a validated spec.
+ *
+ * @param {Object} spec - Node specification
+ * @param {string} spec.name - Unique node identifier
+ * @param {Object} spec.from - Input field specification
+ * @param {string[]} spec.from.x - Source field names (ordered)
+ * @param {Object} spec.sources - Per-source config keyed by field name (signed weights)
+ * @param {number} spec.halfLife - L1 decay half-life (same units as timestamps)
+ * @param {number} [spec.l2HalfLife] - L2 decay half-life (defaults to max L1 tau * ln2)
+ * @param {number} [spec.messageRate=1] - Messages per timestamp unit (for warmup calc)
+ * @param {Object} spec.thresholds - Classification thresholds
+ * @param {Object} spec.stats - Output statistics configuration
+ * @returns {Object} Initialized state object
+ */
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    const state = Object.create( null );
+    const fields = spec.from.x;
+    const configs = spec.sources;
+    const n = fields.length;
+
+    // ── Standard Flags ──────────────────────────────────────────────────────
+    state.inputValidationFailed = false;
+    state.disable = false;
+    state.pause = false;
+
+    // ── Configuration from Spec ─────────────────────────────────────────────
+    state.stats = spec.stats;
+    state.sourceCount = n;
+
+    // ── Deviation Type Dispatch (module-level pure functions, no closures) ───
+    state.deviationTypes = new Uint8Array( n );
+    state.deviationP1 = new Float64Array( n );
+    state.deviationP2 = new Float64Array( n );
+    state.sourceFields = new Array( n );
+
+    // ── Pre-build Per-Source Field Names (zero string ops in hot path) ────
+    const chargePrefix = spec.stats.charge ? spec.stats.charge.storeAs : null;
+    const ratePrefix = spec.stats.rate ? spec.stats.rate.storeAs : null;
+    state.chargeFields = chargePrefix ? new Array( n ) : null;
+    state.rateFields = ratePrefix ? new Array( n ) : null;
+
+    for ( let i = 0; i < n; i += 1 ) {
+        const fieldName = fields[ i ];
+        const cfg = configs[ fieldName ];
+        state.sourceFields[ i ] = fieldName;
+        state.deviationTypes[ i ] = DEVIATION_TYPE_INDEX[ cfg.deviation ];
+
+        if ( cfg.deviation === 'highExceedance' || cfg.deviation === 'lowExceedance' ) {
+            state.deviationP1[ i ] = cfg.baseline;
+        } else if ( cfg.deviation === 'bandExceedance' ) {
+            state.deviationP1[ i ] = cfg.band.lower;
+            state.deviationP2[ i ] = cfg.band.upper;
+        }
+        // identity, absolute: p1=0, p2=0 (Float64Array default)
+
+        if ( chargePrefix ) state.chargeFields[ i ] = chargePrefix + '_' + fieldName;
+        if ( ratePrefix ) state.rateFields[ i ] = ratePrefix + '_' + fieldName;
+    }
+
+    // ── Per-Source Config (pre-compiled) ─────────────────────────────────────
+    state.thetas = new Float64Array( n );
+    state.weights = new Float64Array( n );
+    state.absWeights = new Float64Array( n );
+
+    let totalAbsWeight = 0;
+    for ( let i = 0; i < n; i += 1 ) {
+        const cfg = configs[ fields[ i ] ];
+        state.thetas[ i ] = cfg.theta;
+        state.weights[ i ] = cfg.weight;
+        state.absWeights[ i ] = Math.abs( cfg.weight );
+        totalAbsWeight += state.absWeights[ i ];
+    }
+    state.totalAbsWeight = totalAbsWeight;
+
+    // ── Pre-compute Per-Source Decay Constants ───────────────────────────────
+    const globalTau = spec.halfLife / Math.LN2;
+    state.taus = new Float64Array( n );
+
+    let uniform = true;
+    let maxTau = 0;
+    for ( let i = 0; i < n; i += 1 ) {
+        const hl = configs[ fields[ i ] ].halfLife;
+        state.taus[ i ] = ( hl === undefined ) ? globalTau : ( hl / Math.LN2 );
+        if ( state.taus[ i ] !== globalTau ) uniform = false;
+        if ( state.taus[ i ] > maxTau ) maxTau = state.taus[ i ];
+    }
+    state.uniformDecay = uniform;
+
+    // Pre-allocate for non-uniform path (zero-alloc hot path)
+    state.decayFactors = new Float64Array( n );
+
+    // ── L1 LIF State ────────────────────────────────────────────────────────
+    state.membranes = new Float64Array( n );
+    state.spikes = new Float64Array( n );
+    state.fired = new Uint8Array( n );
+
+    // ── L1 BLI State (intensity explanation) ────────────────────────────────
+    state.charges = new Float64Array( n );
+
+    // ── L1 Rate State (persistence explanation) ─────────────────────────────
+    state.rates = new Float64Array( n );
+
+    // ── L2 Decision Neuron ──────────────────────────────────────────────────
+    const l2Tau = spec.l2HalfLife ?
+        ( spec.l2HalfLife / Math.LN2 ) :
+        maxTau;
+    state.l2Tau = l2Tau;
+    state.l2Membrane = 0;
+    state.l2Theta = 1.0; // placeholder until calibrated
+
+    // ── Calibration ─────────────────────────────────────────────────────────
+    const messageRate = spec.messageRate || 1.0;
+    state.calibrating = true;
+    state.warmupSamples = computeWarmupSamples( l2Tau, messageRate );
+    state.messageCount = 0;
+    state.cTarget = deriveCTarget( spec.thresholds.monitor.at );
+
+    // ── Threshold Configuration ─────────────────────────────────────────────
+    // Sorted ascending for classification loop
+    state.thresholdLevels = [
+        { at: spec.thresholds.monitor.at, name: 'Monitor', action: spec.thresholds.monitor.action },
+        { at: spec.thresholds.degraded.at, name: 'Degraded', action: spec.thresholds.degraded.action },
+        { at: spec.thresholds.critical.at, name: 'Critical', action: spec.thresholds.critical.action }
+    ];
+
+    // ── Timing State ────────────────────────────────────────────────────────
+    state.lastTimestamp = 0;
+    state.hasReceivedMessage = false;
+
+    // ── Combined Score & Classification ─────────────────────────────────────
+    state.combined = 0;
+    state.stateName = 'Normal';
+
+    // ── Constants ───────────────────────────────────────────────────────────
+    state.VTH = 1.0;
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/appraise/integrate.js

@@ -0,0 +1,45 @@
+// nodes/appraise/integrate.js
+
+/**
+ * @fileoverview Pure functions for MM normalization and leaky integration.
+ *
+ * Both functions are stateless, zero-alloc, and used in the hot-path loop.
+ *
+ * MM normalization — Michaelis-Menten saturation:
+ *   n = d / ( d + θ )
+ * Properties: bounded [0, 1), output = 0.5 when d = θ.
+ *
+ * Integration — two-step: decay first, inject into post-decay headroom:
+ *   charge = decayed + n × ( 1 - decayed )
+ * This guarantees charge ∈ [0, 1] — the ceiling is provably unreachable
+ * from below because injection fills only a fraction of the headroom.
+ *
+ * @see Michaelis, L. & Menten, M.L. (1913). Die Kinetik der Invertinwirkung.
+ */
+
+/**
+ * Michaelis-Menten saturation. Maps non-negative deviation to [0, 1).
+ *
+ * @param {number} deviation - Non-negative deviation (from deviation closure)
+ * @param {number} theta - Half-saturation constant (output = 0.5 when d = θ)
+ * @returns {number} Normalised signal ∈ [0, 1)
+ */
+const normalise = function ( deviation, theta ) {
+    return deviation / ( deviation + theta );
+}; // normalise()
+
+/**
+ * Bounded leaky integration. Decays existing charge, then injects
+ * normalised signal into the post-decay headroom.
+ *
+ * @param {number} charge - Current charge ∈ [0, 1]
+ * @param {number} normalised - MM-normalised signal ∈ [0, 1)
+ * @param {number} decayFactor - exp( -Δt / τ ), ∈ [0, 1]
+ * @returns {number} Updated charge ∈ [0, 1]
+ */
+const integrate = function ( charge, normalised, decayFactor ) {
+    const decayed = charge * decayFactor;
+    return decayed + ( normalised * ( 1 - decayed ) );
+}; // integrate()
+
+export { normalise, integrate };