@winkjs/composer 0.5.0 → 0.6.0

package/src/nodes/persist-if/helpers.js

@@ -8,6 +8,8 @@
  * emit-if/helpers.js — the two output gates share one failure model.
  */
 
+import { logger } from '../../core/logger/index.js';
+
 /**
  * Static fallback error the framework substitutes when an adapter breaks
  * the return contract — no result object at all, or `{ ok: false }` with
@@ -74,8 +76,8 @@ const sweepAnnotateKeys = function ( state, record, msg ) {
     }
 
     if ( invented.length > 0 ) {
-        console.warn(
-            `WinkComposer/persistIf: annotate for node '${state.name}' ` +
+        logger.warn(
+            `winkComposer/persistIf: annotate for node '${state.name}' ` +
             `(insightType '${state.insightType}') returned keys that are not declared columns: ` +
             `${invented.join( ', ' )}. These values are never stored, because the persist plan ` +
             'writes only declared columns. Check the key names against the asset class. ' +
@@ -104,8 +106,62 @@ const recordPersistFailure = function ( state, error ) {
         state.writeErrorLogged = true;
         state.firstPersistError = error.message;
         state.firstPersistErrorCode = error.code;
-        console.error( state.writeErrorLogPrefix + error.code + '): ' + error.message );
+        logger.error( state.writeErrorLogPrefix + error.code + '): ' + error.message );
     }
 }; // recordPersistFailure()
 
-export { assertAnnotateReturn, sweepAnnotateKeys, recordPersistFailure, MALFORMED_RESULT_ERROR };
+/**
+ * Substituted error for a storage adapter that THREW from write() —
+ * the other face of a broken return contract (ADR-018: the hot path
+ * never throws; a sink answers { ok }). Same code as the
+ * malformed-result face: the remediation is identical (fix the
+ * non-conforming adapter), and the message names the difference.
+ * Allocates on the failure path only. Mirrors emit-if.
+ *
+ * @param {Error} error - The thrown value
+ * @returns {Object} `{ code, message }` for the failure episode
+ */
+const thrownSinkError = function ( error ) {
+    return {
+        code: 'MALFORMED_RESULT',
+        message: `storage write threw instead of returning { ok, error? }: ${error.message}`
+    };
+}; // thrownSinkError()
+
+/**
+ * Writes one record to the wired storage with the sink call fully
+ * guarded. A conforming adapter never throws; a throwing one is a
+ * broken adapter, recorded in the persist episode — never escaped
+ * into the pipeline where it would also cost the message's other
+ * outputs. Returns true only on `{ ok: true }`. Mirrors emit-if's
+ * deliverToEmitter.
+ *
+ * @param {Object} state - Node state containing storage, insightType,
+ *   and partitionId
+ * @param {Object} record - Record to persist
+ * @returns {boolean} True when the storage accepted the record
+ */
+const writeToStorage = function ( state, record ) {
+    try {
+        const result = state.storage.write(
+            state.insightType,
+            record,
+            state.partitionId
+        );
+        if ( result && result.ok ) {
+            return true;
+        }
+        recordPersistFailure( state, ( result && result.error ) || MALFORMED_RESULT_ERROR );
+    } catch ( sinkError ) {
+        recordPersistFailure( state, thrownSinkError( sinkError ) );
+    }
+    return false;
+}; // writeToStorage()
+
+export {
+    assertAnnotateReturn,
+    sweepAnnotateKeys,
+    recordPersistFailure,
+    writeToStorage,
+    MALFORMED_RESULT_ERROR
+};

package/src/nodes/persist-if/init.js

@@ -90,7 +90,7 @@ const init = function ( spec ) {
     state.firstPersistErrorCode = null;
     // Static log prefix pre-built here per ADR-004 (no string building in
     // update beyond the two runtime fields, and only once per episode).
-    state.writeErrorLogPrefix = `WinkComposer/persistIf: storage write failed (node=${state.name}, insightType=${state.insightType}, code=`;
+    state.writeErrorLogPrefix = `winkComposer/persistIf: storage write failed (node=${state.name}, insightType=${state.insightType}, code=`;
 
     return state;
 }; // init()

package/src/nodes/persist-if/update.js

@@ -10,7 +10,8 @@
  * it to the storage buffer if the predicate passed.
  */
 
-import { assertAnnotateReturn, sweepAnnotateKeys, recordPersistFailure, MALFORMED_RESULT_ERROR } from './helpers.js';
+import { assertAnnotateReturn, sweepAnnotateKeys, writeToStorage } from './helpers.js';
+import { logger } from '../../core/logger/index.js';
 
 /**
  * Process incoming message.
@@ -64,7 +65,7 @@ const update = function ( state, msg ) {
         // Log first error per episode; suppress subsequent until recovery
         if ( !state.predicateErrorLogged ) {
             state.predicateErrorLogged = true;
-            console.error( `WinkComposer/persistIf: predicate threw exception: ${error.message}` );
+            logger.error( `winkComposer/persistIf: predicate threw exception: ${error.message}` );
         }
         state.persistErrors += 1;
         state.lastPersistError = error.message;
@@ -78,31 +79,22 @@ const update = function ( state, msg ) {
 
     // Write to storage if predicate returned true
     if ( shouldPersist ) {
-        // Build record for storage (zero-alloc: storage.write handles it).
         // storage.write() is synchronous per ADR-013; the actual I/O happens
         // asynchronously via the storage adapter's background flush.
         // Per the ADR-018 sink return contract, the storage answers
         // { ok: true } on success or
         // { ok: false, error: { code, message } } on failure.
-        const result = state.storage.write(
-            state.insightType,
-            record,
-            state.partitionId
-        );
-
-        if ( result && result.ok ) {
+        // writeToStorage guards the call itself too: a THROWING adapter
+        // is the other face of a broken contract, recorded in the same
+        // adapter episode — a non-conforming adapter can neither fail
+        // silently nor throw out of the hot path.
+        if ( writeToStorage( state, record ) ) {
             state.persistCount += 1;
             // Wall-clock marker of the last successful write (post-mortem
             // reads only, like the first* error fields).
             state.lastPersistTime = Date.now();
             // Recovery: a successful write closes the failure episode.
             if ( state.writeErrorLogged ) state.writeErrorLogged = false;
-        } else {
-            // A malformed result (no object at all, or ok:false with no
-            // error) counts as a failure with the static fallback error,
-            // so a non-conforming adapter can neither fail silently
-            // nor throw out of the hot path.
-            recordPersistFailure( state, ( result && result.error ) || MALFORMED_RESULT_ERROR );
         }
     }
 

package/src/nodes/persistence-check/update.js

@@ -1,6 +1,7 @@
 // nodes/persistence-check/update.js
 
 import { executeTriggers } from '../../core/utils/node/index.js';
+import { logger } from '../../core/logger/index.js';
 
 const update = function ( state, msg ) {
     if ( state.disable || state.pause ) return state;
@@ -16,7 +17,7 @@ const update = function ( state, msg ) {
         // Log first error per episode; suppress subsequent until recovery
         if ( !state.predicateErrorLogged ) {
             state.predicateErrorLogged = true;
-            console.error( `WinkComposer/persistenceCheck: predicate threw exception: ${error.message}` );
+            logger.error( `winkComposer/persistenceCheck: predicate threw exception: ${error.message}` );
         }
     }
 

package/src/nodes/sanitize/update.js

@@ -1,3 +1,5 @@
+import { logger } from '../../core/logger/index.js';
+
 // Helper: Check value against range
 const checkRange = function ( state, value, rangeSpec ) {
     if ( !state.hasRange || !rangeSpec ) {
@@ -34,7 +36,7 @@ const checkPredicate = function ( state, value, msg ) {
         // Log first error per episode; suppress subsequent until recovery
         if ( !state.predicateErrorLogged ) {
             state.predicateErrorLogged = true;
-            console.error( `WinkComposer/sanitize: predicate threw exception: ${error.message}` );
+            logger.error( `winkComposer/sanitize: predicate threw exception: ${error.message}` );
         }
         return false;
     }
@@ -64,7 +66,7 @@ const update = function ( state, msg ) {
         } catch ( error ) {
             if ( !state.tunableErrorLogged ) {
                 state.tunableErrorLogged = true;
-                console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+                logger.error( `winkComposer/${state.nodeType}: tunable threw: ${error.message}` );
             }
         }
     }

package/src/nodes/swing-watch/update.js

@@ -66,6 +66,7 @@
 //     https://github.com/weinkauf/Persistence1D
 
 import { push, isNotFull } from '../../windowing/count-sliding/index.js';
+import { logger } from '../../core/logger/index.js';
 
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -624,8 +625,8 @@ const resolveThreshold = function ( state, msg ) {
     } catch ( error ) {
         if ( !state.tunableErrorLogged ) {
             state.tunableErrorLogged = true;
-            const errMsg = 'WinkComposer/' + state.nodeType + ': tunable threw: ' + error.message;
-            console.error( errMsg );
+            const errMsg = 'winkComposer/' + state.nodeType + ': tunable threw: ' + error.message;
+            logger.error( errMsg );
         }
     }
     const epsBase = state.currentThreshold;

package/src/nodes/threshold/update.js

@@ -1,6 +1,7 @@
 // nodes/threshold/update.js
 
 import { executeTriggers } from '../../core/utils/node/index.js';
+import { logger } from '../../core/logger/index.js';
 
 const update = function ( state, msg ) {
     if ( state.disable || state.pause ) return state;
@@ -27,7 +28,7 @@ const update = function ( state, msg ) {
         // Log first error per episode; suppress subsequent until recovery
         if ( !state.tunableErrorLogged ) {
             state.tunableErrorLogged = true;
-            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+            logger.error( `winkComposer/${state.nodeType}: tunable threw: ${error.message}` );
         }
     }
 

package/src/nodes/trend/compute-confidence.js

@@ -5,7 +5,7 @@ const computeConfidence = function ( state ) {
     // Provides gradual trust building as statistics stabilize
     if ( state.samples < state.warmupSamples ) {
         const ramp = state.samples / Math.max( state.warmupSamples, 1 );
-        return ( ramp < 0 ) ? 0 : ( ramp > 1 ? 1 : ramp );
+        return Math.min( 1, Math.max( 0, ramp ) );
     }
 
     const epsilon = state.epsilon ?? 1e-12;
@@ -45,7 +45,7 @@ const computeConfidence = function ( state ) {
 
         // Combine factors: far from edge AND low noise AND persistent = high confidence
         const confStable = margin * quietness * persistenceFactor;
-        return ( confStable < 0 ) ? 0 : ( confStable > 1 ? 1 : confStable );
+        return Math.min( 1, Math.max( 0, confStable ) );
     }
 
     // TRENDING CONFIDENCE: "How confident are we in this trend direction?"
@@ -105,8 +105,8 @@ const computeConfidence = function ( state ) {
     // Therefore, we omit the quietness factor for rising/falling states.
     const confTrend = signalClarity * boundaryClarity * persistenceFactor;
 
-    // Ensure output is strictly in [0,1] despite numerical errors
-    return ( confTrend < 0 ) ? 0 : ( confTrend > 1 ? 1 : confTrend );
+    // Clamp to [0,1] — the published confidence contract
+    return Math.min( 1, Math.max( 0, confTrend ) );
 }; // computeConfidence()
 
 export { computeConfidence };

package/src/nodes/trend/update.js

@@ -1,6 +1,7 @@
 // nodes/trend/update.js
 
 import { computeConfidence } from './compute-confidence.js';
+import { logger } from '../../core/logger/index.js';
 
 const update = function ( state, msg ) {
     if ( state.disable || state.pause ) return state;
@@ -47,7 +48,7 @@ const update = function ( state, msg ) {
     } catch ( error ) {
         if ( !state.tunableErrorLogged ) {
             state.tunableErrorLogged = true;
-            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+            logger.error( `winkComposer/${state.nodeType}: tunable threw: ${error.message}` );
         }
     }
 

package/src/nodes/winnow/update.js

@@ -22,6 +22,8 @@
 // Extracted helper: set anchor and mark significant.
 // Called from each of the five checks. Zero allocation — scalar
 // assignments only. Reduces update() cyclomatic complexity.
+import { logger } from '../../core/logger/index.js';
+
 const setAnchor = function ( state, xVal, slope ) {
     state.anchor = xVal;
     state.anchorSlope = Number.isFinite( slope ) ? slope : 0;
@@ -80,7 +82,7 @@ const update = function ( state, msg ) {
     } catch ( error ) {
         if ( !state.tunableErrorLogged ) {
             state.tunableErrorLogged = true;
-            console.error( `WinkComposer/${state.nodeType}: tunable threw: ${error.message}` );
+            logger.error( `winkComposer/${state.nodeType}: tunable threw: ${error.message}` );
         }
     }
 

package/src/tools/training/features.js

@@ -38,13 +38,13 @@ const AVAILABLE_STATS = [ 'max', 'sum', 'countAbove' ];
  */
 const group = function ( name, ids, accessor, options ) {
     if ( typeof name !== 'string' || name.length === 0 ) {
-        throw new Error( 'features.group: name must be a non-empty string' );
+        throw new Error( 'winkComposer/features.group: name must be a non-empty string' );
     }
     if ( !Array.isArray( ids ) || ids.length === 0 ) {
-        throw new Error( 'features.group: ids must be a non-empty array' );
+        throw new Error( 'winkComposer/features.group: ids must be a non-empty array' );
     }
     if ( typeof accessor !== 'function' ) {
-        throw new Error( 'features.group: accessor must be a function' );
+        throw new Error( 'winkComposer/features.group: accessor must be a function' );
     }
 
     const stats = ( options && Array.isArray( options.stats ) ) ?
@@ -54,7 +54,7 @@ const group = function ( name, ids, accessor, options ) {
     for ( let i = 0; i < stats.length; i += 1 ) {
         if ( AVAILABLE_STATS.indexOf( stats[ i ] ) === -1 ) {
             throw new Error(
-                'features.group: unknown stat "' + stats[ i ] +
+                'winkComposer/features.group: unknown stat "' + stats[ i ] +
                 '". Available: ' + AVAILABLE_STATS.join( ', ' )
             );
         }
@@ -65,7 +65,7 @@ const group = function ( name, ids, accessor, options ) {
         1.5;
 
     if ( typeof countAboveThreshold !== 'number' ) {
-        throw new Error( 'features.group: countAboveThreshold must be a number' );
+        throw new Error( 'winkComposer/features.group: countAboveThreshold must be a number' );
     }
 
     return {
@@ -90,10 +90,10 @@ const group = function ( name, ids, accessor, options ) {
  */
 const scalar = function ( name, accessor ) {
     if ( typeof name !== 'string' || name.length === 0 ) {
-        throw new Error( 'features.scalar: name must be a non-empty string' );
+        throw new Error( 'winkComposer/features.scalar: name must be a non-empty string' );
     }
     if ( typeof accessor !== 'function' ) {
-        throw new Error( 'features.scalar: accessor must be a function' );
+        throw new Error( 'winkComposer/features.scalar: accessor must be a function' );
     }
     return { type: SCALAR, name: name, accessor: accessor };
 };
@@ -112,13 +112,13 @@ const scalar = function ( name, accessor ) {
  */
 const counter = function ( name, sourceAccessor, predicate ) {
     if ( typeof name !== 'string' || name.length === 0 ) {
-        throw new Error( 'features.counter: name must be a non-empty string' );
+        throw new Error( 'winkComposer/features.counter: name must be a non-empty string' );
     }
     if ( typeof sourceAccessor !== 'function' ) {
-        throw new Error( 'features.counter: sourceAccessor must be a function' );
+        throw new Error( 'winkComposer/features.counter: sourceAccessor must be a function' );
     }
     if ( typeof predicate !== 'function' ) {
-        throw new Error( 'features.counter: predicate must be a function' );
+        throw new Error( 'winkComposer/features.counter: predicate must be a function' );
     }
     return { type: COUNTER, name: name, sourceAccessor: sourceAccessor, predicate: predicate };
 };
@@ -134,7 +134,7 @@ const counter = function ( name, sourceAccessor, predicate ) {
  */
 const buildExtractor = function ( schema ) {
     if ( !Array.isArray( schema ) || schema.length === 0 ) {
-        throw new Error( 'features.buildExtractor: schema must be a non-empty array' );
+        throw new Error( 'winkComposer/features.buildExtractor: schema must be a non-empty array' );
     }
 
     // Build feature names from schema
@@ -149,7 +149,7 @@ const buildExtractor = function ( schema ) {
             names.push( col.name );
         } else {
             throw new Error(
-                'features.buildExtractor: unknown column type "' +
+                'winkComposer/features.buildExtractor: unknown column type "' +
                 String( col.type ) + '" at index ' + i
             );
         }
@@ -160,7 +160,7 @@ const buildExtractor = function ( schema ) {
     for ( let i = 0; i < names.length; i += 1 ) {
         if ( seen[ names[ i ] ] ) {
             throw new Error(
-                'features.buildExtractor: duplicate feature name "' + names[ i ] + '"'
+                'winkComposer/features.buildExtractor: duplicate feature name "' + names[ i ] + '"'
             );
         }
         seen[ names[ i ] ] = true;

package/src/tools/training/logistic.js

@@ -93,7 +93,7 @@ const train = function ( X, y, options ) {
         for ( let i = 0; i < n; i += 1 ) n1 += y[ i ];
         const n0 = n - n1;
         if ( n0 === 0 || n1 === 0 ) {
-            throw new Error( 'train: y must contain both classes (0 and 1).' );
+            throw new Error( 'winkComposer/train: y must contain both classes (0 and 1).' );
         }
         w[ 0 ] = n / ( 2 * n0 );
         w[ 1 ] = n / ( 2 * n1 );

package/src/tools/training/metrics.js

@@ -24,7 +24,7 @@ import { validateBinaryArray } from './validate.js';
  */
 const confusionMatrix = function ( predictions, labels ) {
     if ( predictions.length !== labels.length ) {
-        throw new Error( 'confusionMatrix: predictions and labels must have the same length.' );
+        throw new Error( 'winkComposer/confusionMatrix: predictions and labels must have the same length.' );
     }
 
     validateBinaryArray( predictions, 'predictions', 'confusionMatrix' );
@@ -85,7 +85,7 @@ const classificationMetrics = function ( cm ) {
  */
 const sweepThresholds = function ( probabilities, labels, thresholds ) {
     if ( probabilities.length !== labels.length ) {
-        throw new Error( 'sweepThresholds: probabilities and labels must have the same length.' );
+        throw new Error( 'winkComposer/sweepThresholds: probabilities and labels must have the same length.' );
     }
 
     validateBinaryArray( labels, 'labels', 'sweepThresholds' );

package/src/tools/training/scale.js

@@ -177,7 +177,7 @@ const computeRobustParams = function ( X ) {
  */
 const scale = function ( X, params ) {
     if ( !Array.isArray( X ) || X.length === 0 ) {
-        throw new Error( 'scale: X must be a non-empty array of rows.' );
+        throw new Error( 'winkComposer/scale: X must be a non-empty array of rows.' );
     }
 
     const n = X.length;
@@ -221,7 +221,7 @@ const scale = function ( X, params ) {
             result[ i ] = out;
         }
     } else {
-        throw new Error( 'scale: unknown method "' + method + '".' );
+        throw new Error( 'winkComposer/scale: unknown method "' + method + '".' );
     }
 
     return result;

package/src/tools/training/validate.js

@@ -24,21 +24,21 @@ import { validators } from '../../core/utils/validate/validators.js';
  */
 const validateMatrix = function ( X, caller ) {
     if ( !Array.isArray( X ) || X.length === 0 ) {
-        throw new Error( caller + ': X must be a non-empty array of rows.' );
+        throw new Error( 'winkComposer/' + caller + ': X must be a non-empty array of rows.' );
     }
 
     const n = X.length;
     const p = X[ 0 ].length;
 
     if ( p === 0 ) {
-        throw new Error( caller + ': rows must have at least one feature.' );
+        throw new Error( 'winkComposer/' + caller + ': rows must have at least one feature.' );
     }
 
     for ( let i = 0; i < n; i += 1 ) {
         const row = X[ i ];
         if ( !Array.isArray( row ) || row.length !== p ) {
             throw new Error(
-                caller + ': row ' + i + ' has length ' +
+                'winkComposer/' + caller + ': row ' + i + ' has length ' +
                 ( Array.isArray( row ) ? row.length : 'N/A' ) +
                 ', expected ' + p + '.'
             );
@@ -46,7 +46,7 @@ const validateMatrix = function ( X, caller ) {
         for ( let j = 0; j < p; j += 1 ) {
             if ( !validators.isFinite( row[ j ] ) ) {
                 throw new Error(
-                    caller + ': non-finite value at row ' + i +
+                    'winkComposer/' + caller + ': non-finite value at row ' + i +
                     ', column ' + j + '.'
                 );
             }
@@ -67,7 +67,7 @@ const validateMatrix = function ( X, caller ) {
 const validateBinaryLabels = function ( y, n, caller ) {
     if ( !Array.isArray( y ) || y.length !== n ) {
         throw new Error(
-            caller + ': y must be an array with length ' + n +
+            'winkComposer/' + caller + ': y must be an array with length ' + n +
             ', got ' + ( Array.isArray( y ) ? y.length : typeof y ) + '.'
         );
     }
@@ -75,7 +75,7 @@ const validateBinaryLabels = function ( y, n, caller ) {
     for ( let i = 0; i < n; i += 1 ) {
         if ( y[ i ] !== 0 && y[ i ] !== 1 ) {
             throw new Error(
-                caller + ': y[' + i + '] = ' + y[ i ] +
+                'winkComposer/' + caller + ': y[' + i + '] = ' + y[ i ] +
                 ', expected 0 or 1.'
             );
         }
@@ -93,7 +93,7 @@ const validateBinaryArray = function ( arr, name, caller ) {
     for ( let i = 0; i < arr.length; i += 1 ) {
         if ( arr[ i ] !== 0 && arr[ i ] !== 1 ) {
             throw new Error(
-                caller + ': ' + name + '[' + i + '] = ' + arr[ i ] +
+                'winkComposer/' + caller + ': ' + name + '[' + i + '] = ' + arr[ i ] +
                 ', expected 0 or 1.'
             );
         }