@winkjs/composer 0.0.2 → 0.4.1

package/src/nodes/appraise/update.js

@@ -0,0 +1,130 @@
+// nodes/appraise/update.js
+
+/**
+ * @fileoverview Hot path for two-layer SNN appraise node message processing.
+ *
+ * Pipeline per message:
+ *   1. Guard / validate timestamp
+ *   2. Compute decay factors (L1 uniform or per-source, L2 single)
+ *   3. L1 receptor loop: deviation -> normalise -> processReceptor (LIF+BLI+Rate)
+ *   4. L2 decision: synaptic current -> membrane update
+ *   5. Calibration check (burn-in Theta derivation)
+ *   6. MM readout -> conviction
+ *   7. Threshold classification
+ *
+ * Zero allocation. All arrays and objects are pre-allocated in init.
+ * Missing source fields cause pure decay (no injection) on that source.
+ *
+ * @see ADR-004
+ */
+
+import { computeDeviation } from './deviation.js';
+import { normalise } from './integrate.js';
+import { processReceptor, decayReceptor } from './receptor.js';
+import { computeSynapticCurrent, updateMembrane, readout } from './decision.js';
+import { checkCalibration } from './calibrate.js';
+
+/**
+ * Processes a message through the two-layer SNN pipeline.
+ *
+ * @param {Object} state - Node state from init()
+ * @param {Object} msg - Incoming message with field values and timestamp
+ * @returns {Object} Updated state
+ */
+const update = function ( state, msg ) {
+    // Guard: skip if disabled
+    if ( state.disable || state.pause ) return state;
+
+    // Extract timestamp
+    const timestamp = msg.timestamp;
+
+    // Reset health flag
+    state.inputValidationFailed = false;
+
+    // Validate timestamp
+    if ( !Number.isFinite( timestamp ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // ── Compute Decay ───────────────────────────────────────────────────────
+    const isFirst = !state.hasReceivedMessage;
+    const dt = timestamp - state.lastTimestamp;
+    state.lastTimestamp = timestamp;
+    state.hasReceivedMessage = true;
+    state.messageCount += 1;
+
+    // ── L1 Per-Source Receptor Loop ─────────────────────────────────────────
+    const thetas = state.thetas;
+    const fields = state.sourceFields;
+    const types = state.deviationTypes;
+    const dp1 = state.deviationP1;
+    const dp2 = state.deviationP2;
+    const n = state.sourceCount;
+
+    if ( state.uniformDecay ) {
+        // Fast path: single decay factor for all L1 sources
+        const decayFactor = isFirst ? 1 : Math.exp( -dt / state.taus[ 0 ] );
+
+        for ( let i = 0; i < n; i += 1 ) {
+            const raw = msg[ fields[ i ] ];
+            if ( Number.isFinite( raw ) ) {
+                const norm = normalise( computeDeviation( types[ i ], raw, dp1[ i ], dp2[ i ] ), thetas[ i ] );
+                processReceptor( state, i, norm, decayFactor );
+            } else {
+                decayReceptor( state, i, decayFactor );
+            }
+        }
+    } else {
+        // Per-source path: each source decays at its own rate
+        const taus = state.taus;
+        const decayFactors = state.decayFactors;
+
+        if ( isFirst ) {
+            decayFactors.fill( 1 );
+        } else {
+            for ( let i = 0; i < n; i += 1 ) {
+                decayFactors[ i ] = Math.exp( -dt / taus[ i ] );
+            }
+        }
+
+        for ( let i = 0; i < n; i += 1 ) {
+            const raw = msg[ fields[ i ] ];
+            if ( Number.isFinite( raw ) ) {
+                const norm = normalise( computeDeviation( types[ i ], raw, dp1[ i ], dp2[ i ] ), thetas[ i ] );
+                processReceptor( state, i, norm, decayFactors[ i ] );
+            } else {
+                decayReceptor( state, i, decayFactors[ i ] );
+            }
+        }
+    }
+
+    // ── L2 Decision Neuron ──────────────────────────────────────────────────
+    const l2DecayFactor = isFirst ? 1 : Math.exp( -dt / state.l2Tau );
+    const current = computeSynapticCurrent(
+        state.spikes, state.weights, state.totalAbsWeight, n
+    );
+    state.l2Membrane = updateMembrane( state.l2Membrane, current, l2DecayFactor );
+
+    // ── Calibration Check ───────────────────────────────────────────────────
+    if ( state.calibrating ) {
+        checkCalibration( state );
+    }
+
+    // ── Conviction Readout ──────────────────────────────────────────────────
+    state.combined = readout( state.l2Membrane, state.l2Theta );
+
+    // ── Threshold Classification ────────────────────────────────────────────
+    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 state;
+}; // update()
+
+export default update;

package/src/nodes/archive/csv/index.js

@@ -0,0 +1,6 @@
+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 * from './introspect.js';

package/src/nodes/archive/csv/init.js

@@ -0,0 +1,36 @@
+// import { getNodeType } from './introspect.js';
+
+const init = function ( spec ) {
+    const state = Object.create( null );
+
+    // CSV source configuration
+    state.source = spec.source;  // URL or file path
+    state.mode = spec.mode || 'stream';  // 'stream' or 'batch'
+    state.rate = spec.rate || 100;  // Messages per second (for stream mode)
+    state.loop = spec.loop !== false;  // Loop when reaching end
+    state.columns = spec.columns || 'auto';  // Column mapping
+
+    // Parsing options for Papaparse
+    state.parseOptions = {
+        header: true,
+        dynamicTyping: true,
+        skipEmptyLines: true,
+        ...( spec.parseOptions || {} )
+    };
+
+    // Runtime state
+    state.data = null;  // Parsed CSV data
+    state.currentIndex = 0;
+    state.lastEmitTime = 0;
+    state.isLoaded = false;
+    state.isPaused = false;
+
+    // For browser environment - store fetch promise
+    state.loadPromise = null;
+
+    state.nodeType = 'CSV'; // getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/archive/csv/load.js

@@ -0,0 +1,70 @@
+// nodes/csv-source/load.js
+import SimpleCSV from './simple-parser.js';
+
+const loadCSV = async function ( state ) {
+    try {
+        let csvText;
+
+        // Check if source looks like CSV data (has newlines or commas)
+        const isEmbeddedData = state.source.includes('\n') ||
+                               (state.source.includes(',') && !state.source.endsWith('.csv'));
+
+        // Determine environment and load CSV text
+        if ( typeof window === 'object' ) {
+            // Browser environment
+            if ( isEmbeddedData ) {
+                // Embedded data
+                csvText = state.source;
+            } else if ( state.source.startsWith( 'http' ) || state.source.startsWith( '/' ) ) {
+                // Fetch from URL
+                const response = await fetch( state.source );
+                csvText = await response.text();
+            } else {
+                // Assume it's embedded data if not a URL
+                csvText = state.source;
+            }
+        } else if ( typeof process === 'object' && process.versions && process.versions.node ) {
+            // Node.js environment
+            if ( isEmbeddedData ) {
+                // Embedded data
+                csvText = state.source;
+            } else if ( state.source.startsWith( 'http' ) ) {
+                // Fetch from URL
+                const response = await fetch( state.source );
+                csvText = await response.text();
+            } else {
+                // Read from file
+                const fs = await import( 'fs/promises' );
+                csvText = await fs.readFile( state.source, 'utf8' );
+            }
+        } else {
+            throw new Error( 'Unable to determine environment for CSV loading' );
+        }
+
+        // Parse CSV using SimpleCSV
+        const parsed = SimpleCSV.parse( csvText, state.parseOptions );
+
+        // Handle any parsing errors
+        if ( parsed.errors && parsed.errors.length > 0 ) {
+            console.warn( 'CSV parsing warnings:', parsed.errors );
+        }
+
+        // Store parsed data
+        state.data = parsed.data;
+        state.isLoaded = true;
+        state.currentIndex = 0;
+
+        // Log summary
+        console.log( `Loaded ${state.data.length} rows from CSV` );
+        if ( parsed.meta && parsed.meta.fields ) {
+            console.log( `Columns: ${parsed.meta.fields.join( ', ' )}` );
+        }
+
+    } catch ( error ) {
+        console.error( 'Failed to load CSV:', error );
+        state.data = [];
+        state.isLoaded = false;
+    }
+};
+
+export default loadCSV;

package/src/nodes/archive/csv/reset.js

@@ -0,0 +1,14 @@
+// nodes/csv-source/reset.js
+const reset = function ( state ) {
+    // Reset to initial state
+    state.currentIndex = 0;
+    state.lastEmitTime = 0;
+    state.isPaused = false;
+
+    // Don't clear the data - just reset the reading position
+    // This allows resuming from the beginning without reloading
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/archive/csv/simple-parser.js

@@ -0,0 +1,216 @@
+// nodes/csv-source/simple-csv-parser.js
+
+const SimpleCSV = {
+    parse: function ( csvText, config = {} ) {
+        // Default configuration
+        const options = {
+            delimiter: config.delimiter || ',',
+            header: config.header !== false,
+            dynamicTyping: config.dynamicTyping !== false,
+            skipEmptyLines: config.skipEmptyLines !== false,
+            transformHeader: config.transformHeader || null,
+            transform: config.transform || null,
+            comments: config.comments || false,
+            quoteChar: config.quoteChar || '"',
+            parseDates: config.parseDates || false
+        };
+
+        const result = {
+            data: [],
+            errors: [],
+            meta: {
+                delimiter: options.delimiter,
+                linebreak: '\n',
+                aborted: false,
+                fields: []
+            }
+        };
+
+        try {
+            // Normalize line breaks
+            csvText = csvText.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+            // Split into lines (handling quoted newlines)
+            const lines = this.splitLines( csvText, options.quoteChar );
+
+            // Filter empty lines and comments
+            const processedLines = lines.filter( (line, index) => {
+                if ( options.skipEmptyLines && line.trim() === '' ) return false;
+                if ( options.comments && line.trim().startsWith( options.comments ) ) return false;
+                return true;
+            });
+
+            if ( processedLines.length === 0 ) {
+                return result;
+            }
+
+            // Parse header if present
+            let headers = [];
+            let dataStartIndex = 0;
+
+            if ( options.header ) {
+                headers = this.parseLine( processedLines[0], options );
+
+                // Transform headers if function provided
+                if ( options.transformHeader ) {
+                    headers = headers.map( (h) => options.transformHeader( h ) );
+                }
+
+                result.meta.fields = headers;
+                dataStartIndex = 1;
+            }
+
+            // Parse data rows
+            for ( let i = dataStartIndex; i < processedLines.length; i += 1 ) {
+                const values = this.parseLine( processedLines[i], options );
+
+                if ( values.length === 0 ) continue;
+
+                // Create row object or array
+                let row;
+                if ( options.header && headers.length > 0 ) {
+                    row = {};
+                    headers.forEach( (header, index) => {
+                        let value = values[index];
+
+                        // Apply dynamic typing
+                        if ( options.dynamicTyping ) {
+                            value = this.castValue( value, options );
+                        }
+
+                        // Apply transform if provided
+                        if ( options.transform ) {
+                            value = options.transform( value, header );
+                        }
+
+                        row[header] = value;
+                    });
+                } else {
+                    row = values.map( (value) => {
+                        if ( options.dynamicTyping ) {
+                            return this.castValue( value );
+                        }
+                        return value;
+                    });
+                }
+
+                result.data.push( row );
+            }
+
+        } catch ( error ) {
+            result.errors.push({
+                type: 'ParseError',
+                code: 'ParseError',
+                message: error.message,
+                row: result.data.length
+            });
+        }
+
+        return result;
+    },
+
+    // Split CSV into lines, respecting quoted newlines
+    splitLines: function ( text, quoteChar ) {
+        const lines = [];
+        let currentLine = '';
+        let inQuotes = false;
+
+        for ( let i = 0; i < text.length; i += 1 ) {
+            const char = text[i];
+            const nextChar = text[i + 1];
+
+            if ( char === quoteChar ) {
+                // Check if it's an escaped quote
+                if ( nextChar === quoteChar && inQuotes ) {
+                    currentLine += quoteChar;
+                    i += 1; // Skip next quote
+                } else {
+                    inQuotes = !inQuotes;
+                    currentLine += char;
+                }
+            } else if ( char === '\n' && !inQuotes ) {
+                lines.push( currentLine );
+                currentLine = '';
+            } else {
+                currentLine += char;
+            }
+        }
+
+        // Don't forget the last line
+        if ( currentLine !== '' ) {
+            lines.push( currentLine );
+        }
+
+        return lines;
+    },
+
+    // Parse a single line into values
+    parseLine: function ( line, options ) {
+        const values = [];
+        let currentValue = '';
+        let inQuotes = false;
+        const delimiter = options.delimiter;
+        const quoteChar = options.quoteChar;
+
+        for ( let i = 0; i < line.length; i += 1 ) {
+            const char = line[i];
+            const nextChar = line[i + 1];
+
+            if ( char === quoteChar ) {
+                if ( inQuotes && nextChar === quoteChar ) {
+                    // Escaped quote
+                    currentValue += quoteChar;
+                    i += 1; // Skip next quote
+                } else if ( inQuotes && ( nextChar === delimiter || nextChar === undefined || i === line.length - 1 ) ) {
+                    // End of quoted value
+                    inQuotes = false;
+                } else if ( !inQuotes && ( currentValue === '' || currentValue === ' '.repeat( currentValue.length ) ) ) {
+                    // Start of quoted value
+                    inQuotes = true;
+                } else {
+                    currentValue += char;
+                }
+            } else if ( char === delimiter && !inQuotes ) {
+                // End of value
+                values.push( currentValue.trim() );
+                currentValue = '';
+            } else {
+                currentValue += char;
+            }
+        }
+
+        // Don't forget the last value
+        values.push( currentValue.trim() );
+
+        return values;
+    },
+
+    // Convert string values to appropriate types
+    castValue: function ( value, options ) {
+        if ( value === '' || value === null || value === undefined ) {
+            return value;
+        }
+
+        // Boolean
+        if ( value.toLowerCase() === 'true' ) return true;
+        if ( value.toLowerCase() === 'false' ) return false;
+
+        // Number
+        if ( !isNaN( value ) && !isNaN( parseFloat( value ) ) ) {
+            return value.indexOf( '.' ) > -1 ? parseFloat( value ) : parseInt( value, 10 );
+        }
+
+        // Date (only if parseDates is true)
+        if ( options.parseDates && (/^\d{4}-\d{2}-\d{2}/).test( value ) ) {
+            const date = new Date( value );
+            if ( !isNaN( date.getTime() ) ) {
+                return date;
+            }
+        }
+
+        // String (default)
+        return value;
+    }
+};
+
+export default SimpleCSV;

package/src/nodes/archive/csv/test.js

@@ -0,0 +1,173 @@
+// nodes/csv-source/test.js
+import * as csvSource from './index.js';
+import loadCSV from './load.js';
+
+// Sample CSV data for testing
+const sampleCSV = `timestamp,temperature,pressure,humidity,location
+2024-01-01T00:00:00,23.5,1013.25,65,sensor_01
+2024-01-01T00:00:10,23.7,1013.20,64,sensor_01
+2024-01-01T00:00:20,24.1,1013.15,63,sensor_01
+2024-01-01T00:00:30,24.5,1013.10,62,sensor_01
+2024-01-01T00:00:40,25.2,1013.05,61,sensor_01`;
+
+// Test 1: Basic initialization and loading
+console.log('=== Test 1: Basic CSV Loading ===');
+const basicSpec = {
+    source: sampleCSV,  // Embedded CSV data
+    mode: 'batch',      // Get all at once
+    parseOptions: {
+        header: true,
+        dynamicTyping: true,
+        skipEmptyLines: true
+    }
+};
+
+const basicState = csvSource.init( basicSpec );
+console.log( 'Initial state:', {
+    mode: basicState.mode,
+    isLoaded: basicState.isLoaded,
+    currentIndex: basicState.currentIndex
+});
+
+// Load the CSV data
+await loadCSV( basicState );
+console.log( `Loaded ${basicState.data.length} rows` );
+console.log( 'First row:', basicState.data[0] );
+console.log( 'Data types:', Object.entries( basicState.data[0] ).map(
+    ([ k, v ]) => `${k}: ${typeof v}`
+));
+
+// Test 2: Message generation
+console.log( '\n=== Test 2: Message Generation ===');
+const msg1 = csvSource.update( basicState, {} );
+console.log( 'Message 1:', msg1 );
+
+const msg2 = csvSource.update( basicState, {} );
+console.log( 'Message 2:', msg2 );
+
+// Test 3: Stream mode with rate limiting
+console.log( '\n=== Test 3: Stream Mode ===');
+const streamSpec = {
+    source: sampleCSV,
+    mode: 'stream',
+    rate: 100,  // 100 messages per second
+    loop: true,
+    parseOptions: {
+        header: true,
+        dynamicTyping: true
+    }
+};
+
+const streamState = csvSource.init( streamSpec );
+await loadCSV( streamState );
+
+// Simulate rapid updates - should be rate limited
+const startTime = Date.now();
+let messageCount = 0;
+
+for ( let i = 0; i < 10; i += 1 ) {
+    const msg = csvSource.update( streamState, {} );
+    if ( msg ) {
+        messageCount += 1;
+        console.log( `Stream message ${messageCount}:`, msg._source );
+    }
+    // Small delay to show rate limiting
+    await new Promise( (resolve) => setTimeout( resolve, 5 ) );
+}
+
+const elapsed = Date.now() - startTime;
+console.log( `Generated ${messageCount} messages in ${elapsed}ms` );
+console.log( `Effective rate: ${(messageCount / elapsed * 1000).toFixed(1)} msg/sec` );
+
+// Test 4: Loop behavior
+console.log( '\n=== Test 4: Loop Behavior ===');
+const loopState = csvSource.init({
+    source: sampleCSV,
+    mode: 'batch',
+    loop: true
+});
+await loadCSV( loopState );
+
+// Read all messages twice to test looping
+console.log( 'First pass:' );
+for ( let i = 0; i < 5; i += 1 ) {
+    const msg = csvSource.update( loopState, {} );
+    console.log( `  Row ${i + 1}: temp=${msg.temperature}°C` );
+}
+
+console.log( 'Second pass (should loop):' );
+for ( let i = 0; i < 3; i += 1 ) {
+    const msg = csvSource.update( loopState, {} );
+    console.log( `  Row ${i + 1}: temp=${msg.temperature}°C` );
+}
+
+// Test 5: Column mapping
+console.log( '\n=== Test 5: Column Mapping ===');
+const mappedState = csvSource.init({
+    source: sampleCSV,
+    columns: {
+        'temperature': 'temp',
+        'pressure': 'press',
+        'location': 'id'
+    }
+});
+await loadCSV( mappedState );
+
+const mappedMsg = csvSource.update( mappedState, {} );
+console.log( 'Mapped message:', mappedMsg );
+console.log( 'Should have: temp, press, id fields' );
+
+// Test 6: CSV with different delimiter
+console.log( '\n=== Test 6: Tab-Delimited CSV ===');
+const tabCSV = `name	age	score
+John Doe	30	95.5
+Jane Smith	25	87.3`;
+
+const tabState = csvSource.init({
+    source: tabCSV,
+    parseOptions: {
+        delimiter: '\t',
+        header: true,
+        dynamicTyping: true
+    }
+});
+await loadCSV( tabState );
+
+const tabMsg = csvSource.update( tabState, {} );
+console.log( 'Tab-delimited data:', tabMsg );
+
+// Test 7: File loading simulation (Node.js only)
+if ( typeof process === 'object' ) {
+    console.log( '\n=== Test 7: File Loading (Node.js) ===');
+
+    // Create a temporary CSV file
+    const fs = await import( 'fs/promises' );
+    const tempFile = './test-data.csv';
+    await fs.writeFile( tempFile, sampleCSV );
+
+    const fileState = csvSource.init({
+        source: tempFile,
+        mode: 'batch'
+    });
+
+    await loadCSV( fileState );
+    console.log( `Loaded ${fileState.data.length} rows from file` );
+
+    // Clean up
+    await fs.unlink( tempFile );
+}
+
+// Test 8: Reset functionality
+console.log( '\n=== Test 8: Reset ===');
+console.log( 'Before reset:', {
+    currentIndex: basicState.currentIndex,
+    isLoaded: basicState.isLoaded
+});
+
+csvSource.reset( basicState );
+console.log( 'After reset:', {
+    currentIndex: basicState.currentIndex,
+    isLoaded: basicState.isLoaded
+});
+
+console.log( '\n✅ All tests completed!' );