@winkjs/composer 0.5.1 → 0.7.0

package/src/flow/for-each.js

@@ -31,6 +31,7 @@ import { getSignaturePattern } from './get-signature-pattern.js';
 import { specBuilder } from './spec-builder.js';
 import { getTargetArray } from './get-target-array.js';
 import { resolvePickByField } from './resolve-pick-by-field.js';
+import { logger } from '../core/logger/index.js';
 
 /**
  * Locate the index of a named argument slot in a signature schema (the source of
@@ -90,7 +91,7 @@ export const makeForEach = function ( api, flowState ) {
             // rather than emit a silently-wrong per-field controller.
             if ( pattern === SIGNATURE_PATTERNS.nameLogic ) {
                 throw new Error(
-                    `WinkComposer/flow: forEach cannot fan a controller ('${args[ 0 ]}'); ` +
+                    `winkComposer/flow: forEach cannot fan a controller ('${args[ 0 ]}'); ` +
                     'fan data-processing nodes only.'
                 );
             }
@@ -109,7 +110,7 @@ export const makeForEach = function ( api, flowState ) {
             // Node-name collision check before building stats (matches make-node-method),
             // so a rejected node never registers its output params in the global checker.
             if ( isNodeNameDuplicate( t[ 0 ] ) ) {
-                throw new Error( `WinkComposer/flow: duplicate node ${t[ 0 ]} found.` );
+                throw new Error( `winkComposer/flow: duplicate node ${t[ 0 ]} found.` );
             }
 
             // Outputs: store each labelled output as `${field}_${label}`, and record the
@@ -121,8 +122,8 @@ export const makeForEach = function ( api, flowState ) {
                 for ( let i = 0; i < outKeys.length; i += 1 ) {
                     const label = rawOutputs[ outKeys[ i ] ];
                     if ( Object.prototype.hasOwnProperty.call( recorded, label ) ) {
-                        console.warn(
-                            `WinkComposer/flow: forEach output label '${label}' written by ` +
+                        logger.warn(
+                            `winkComposer/flow: forEach output label '${label}' written by ` +
                             `more than one step on field '${field}'; each.out will return the last.`
                         );
                     }
@@ -146,7 +147,7 @@ export const makeForEach = function ( api, flowState ) {
             targetArray.push( spec );
         } catch ( error ) {
             throw new Error(
-                `WinkComposer/flow: Failed to process "${callContext}"\n` +
+                `winkComposer/flow: Failed to process "${callContext}"\n` +
                 `  Reason: ${error.message}\n`
             );
         }
@@ -170,7 +171,7 @@ export const makeForEach = function ( api, flowState ) {
         each.out = function ( label ) {
             if ( !Object.prototype.hasOwnProperty.call( recorded, label ) ) {
                 throw new Error(
-                    `WinkComposer/flow: each.out( '${label}' ) on field '${field}': ` +
+                    `winkComposer/flow: each.out( '${label}' ) on field '${field}': ` +
                     `no earlier step in this chain wrote an output labelled '${label}'.`
                 );
             }
@@ -191,25 +192,25 @@ export const makeForEach = function ( api, flowState ) {
         // that only resolves at .endGroup(), so the callback cannot run where written.
         if ( groupByState.active ) {
             throw new Error(
-                'WinkComposer/flow: forEach inside groupBy is not supported yet; ' +
+                'winkComposer/flow: forEach inside groupBy is not supported yet; ' +
                 'the field list must be a concrete array at the call site.'
             );
         }
         if ( !Array.isArray( fields ) || fields.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: forEach requires a non-empty array of field names.' );
+            throw new Error( 'winkComposer/flow: forEach requires a non-empty array of field names.' );
         }
         if ( typeof callback !== 'function' ) {
-            throw new Error( 'WinkComposer/flow: forEach requires a callback function.' );
+            throw new Error( 'winkComposer/flow: forEach requires a callback function.' );
         }
 
         const seen = Object.create( null );
         for ( let i = 0; i < fields.length; i += 1 ) {
             const field = fields[ i ];
             if ( typeof field !== 'string' || field.length === 0 ) {
-                throw new Error( 'WinkComposer/flow: forEach field names must be non-empty strings.' );
+                throw new Error( 'winkComposer/flow: forEach field names must be non-empty strings.' );
             }
             if ( Object.prototype.hasOwnProperty.call( seen, field ) ) {
-                throw new Error( `WinkComposer/flow: forEach duplicate field '${field}' in field list.` );
+                throw new Error( `winkComposer/flow: forEach duplicate field '${field}' in field list.` );
             }
             seen[ field ] = 1;
         }

package/src/flow/get-target-array.js

@@ -29,13 +29,13 @@ export const getTargetArray = function ( switchState, groupByState, flowDefiniti
     if ( switchState && switchState.active ) {
         if ( switchState.currentCase === null ) {
             throw new Error(
-                'WinkComposer/flow: node called outside of a .case() block - ' +
+                'winkComposer/flow: node called outside of a .case() block - ' +
                 'after .switch(), you must call .case() before adding nodes'
             );
         }
         if ( switchState.caseEnded ) {
             throw new Error(
-                'WinkComposer/flow: node called after .break() - ' +
+                'winkComposer/flow: node called after .break() - ' +
                 'start a new .case() before adding more nodes'
             );
         }

package/src/flow/load-node-module.js

@@ -31,7 +31,7 @@ const moduleCache = new Map();
 export const loadNodeModule = async function ( nodeName ) {
     // Validate node name
     if ( !isValidNodeName( nodeName ) ) {
-        throw new Error( `Unknown node type: "${nodeName}"` );
+        throw new Error( `winkComposer/flow: Unknown node type: "${nodeName}"` );
     }
 
     // Return cached module if available

package/src/flow/make-node-method.js

@@ -8,7 +8,7 @@ import { specBuilder } from './spec-builder.js';
 import { getTargetArray } from './get-target-array.js';
 
 /**
- * Creates a chainable DSL method for a WinkComposer node.
+ * Creates a chainable DSL method for a winkComposer node.
  *
  * @param {Object} api - The fluent API object to extend
  * @param {string} node - Node type name (e.g., 'esMean')
@@ -79,9 +79,9 @@ export const makeNodeMethod = function ( api, node, meta, flowState ) {
             } else {
                 // Canonical builder path
                 const instName = args[ 0 ];
-                if ( effectiveNodeChecker( instName ) ) throw Error( `WinkComposer/flow: duplicate node ${instName} found.` );
+                if ( effectiveNodeChecker( instName ) ) throw Error( `winkComposer/flow: duplicate node ${instName} found.` );
                 const pattern = getSignaturePattern( schema );
-                if ( pattern === SIGNATURE_PATTERNS.unknown ) throw Error( `WinkComposer/flow: unknown signature pattern found for ${instName}.` );
+                if ( pattern === SIGNATURE_PATTERNS.unknown ) throw Error( `winkComposer/flow: unknown signature pattern found for ${instName}.` );
                 const status = validateWithSchema( schemas[ pattern ], [ ...args ], 'Arg' );
                 status.throwIfInvalid( 'argument' );
                 built = buildSpecFor[ pattern ]( [ ...args ] );
@@ -101,7 +101,7 @@ export const makeNodeMethod = function ( api, node, meta, flowState ) {
             }
         } catch ( error ) {
             const enhancedError = new Error(
-                `WinkComposer/flow: Failed to process "${callContext}"\n` +
+                `winkComposer/flow: Failed to process "${callContext}"\n` +
                 `  Reason: ${error.message}\n`
             );
 

package/src/flow/resolve-pick-by-field.js

@@ -35,7 +35,7 @@ export const resolvePickByField = function ( value, field ) {
         const map = value.semantics.map;
         if ( !Object.prototype.hasOwnProperty.call( map, field ) ) {
             throw new Error(
-                `WinkComposer/flow: pickByField has no entry for field '${field}' ` +
+                `winkComposer/flow: pickByField has no entry for field '${field}' ` +
                 `(map keys: ${Object.keys( map ).join( ', ' )}).`
             );
         }

package/src/flow/run.js

@@ -17,6 +17,8 @@ import * as partitionManager from '../core/partition-manager/index.js';
 import { wireLinearGraph, emitters, storages, assertModuleDurability } from '../core/wiring/index.js';
 import shutdownManager from '../core/shutdown-manager/index.js';
 import { ENV_VARS } from '../core/env-vars.js';
+import { wrapCallback } from '../core/utils/callback-guard/index.js';
+import { logger } from '../core/logger/index.js';
 
 /**
  * Wires and starts the pipeline for direct execution.
@@ -27,7 +29,8 @@ import { ENV_VARS } from '../core/env-vars.js';
  * @param {Set} importSet - Set of node names used
  * @param {Object} runtime - Runtime configuration
  * @param {Array} [caseOrder] - Order of case keys (only for multi-specialization)
- * @returns {Promise<Object>} Pipeline handle with shutdown method
+ * @returns {Promise<Object>} Pipeline handle: processMessage, shutdown,
+ *   whenComplete, getStats, flowName, composerState
  */
 export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet, runtime, caseOrder ) {
     // Determine if this is multi-specialization mode
@@ -156,10 +159,16 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
     // caller that ignores the Promise (a push source such as the MQTT
     // subscriber) can never see messages update a partition out of order.
     //
-    // The caller contract (ADR-013) is unchanged: `undefined` on the hot
-    // path, a Promise on the yield tick; `await` works with both, and the
-    // Promise never rejects — a pipeline fault throws synchronously here,
-    // the same as on every other message.
+    // The caller contract (ADR-013) is unchanged in shape: `undefined` on
+    // the hot path, a Promise on the yield tick; `await` works with both,
+    // and the Promise never rejects. Fault delivery depends on the flow
+    // kind (ADR-018 — the runtime owns per-message dispatch failure). With
+    // a source present, a pipeline fault is contained here: the message is
+    // skipped, one red MESSAGE_HANDLER_FAILED travels the status channel,
+    // and a run of consecutive failures stops the flow in the terminal
+    // 'errored' phase. A headless flow (no source) has no status channel,
+    // so the fault throws synchronously to the caller — the headless
+    // driver's catch and `failed` counter are that path's containment.
     //
     // The default threshold comes from YIELD_TIME_THRESHOLD_MS (500 ms);
     // `.yield( { threshold } )` overrides it per flow, and Infinity turns
@@ -187,26 +196,10 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
 
     const partitionState = composerState.partitionState;
 
-    const processMessage = function ( msg ) {
-        const graph = partitionManager.update( composerState, msg );
-
-        // Process first — pmUpdate always returns the graph synchronously
-        // (or null for a dropped message, which never sets the flag).
-        if ( graph ) {
-            runPipeline( graph, msg );
-        }
-
-        // Breathe after (yield tick, rare): hand the awaiting caller a
-        // Promise that resolves once the event loop has had a full turn.
-        if ( partitionState.yieldPending ) {
-            partitionState.yieldPending = false;
-            return new Promise( ( resolve ) => {
-                setImmediate( resolve );
-            } );
-        }
-
-        return undefined;
-    };
+    // The dispatch function itself is defined AFTER the shutdown
+    // closure below — its escalation path drains the flow, so it
+    // needs `shutdown` in scope. No message can arrive before then:
+    // the source only receives processMessage at start, further down.
 
     // 6. Setup the flow's shutdown closure.
     //
@@ -272,13 +265,28 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
             await stage();
         } catch ( err ) {
             stageErrors.push( err );
-            console.error(
-                `WinkComposer/flow: ${label} drain stage failed [${( err && err.code ) || 'UNKNOWN'}]: ` +
+            logger.error(
+                `winkComposer/flow: ${label} drain stage failed [${( err && err.code ) || 'UNKNOWN'}]: ` +
                 `${( err && err.message ) || String( err )} — later drain stages still ran`
             );
         }
     }; // runDrainStage()
 
+    // A sink stage returns `Promise.allSettled` results. The wiring
+    // logs each adapter whose drain rejected and lets its siblings
+    // finish, so one failing sink never strands another's data. The
+    // loss must still reach this handle's caller. A rejected drain is
+    // how the shutdown manager knows to exit 1 (ADR-018 §7). So once
+    // every adapter in the stage has drained, the stage throws the
+    // first rejected reason, code and dropped count intact.
+    const throwFirstRejection = function ( results ) {
+        for ( let i = 0; i < results.length; i += 1 ) {
+            if ( results[ i ].status === 'rejected' ) {
+                throw results[ i ].reason;
+            }
+        }
+    }; // throwFirstRejection()
+
     const drainAll = async function () {
         const stageErrors = [];
         try {
@@ -288,9 +296,9 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
                     () => stopSource( { timeout: STAGE_TIMEOUT_MS } ) );
             }
             await runDrainStage( 'emitter', stageErrors,
-                () => emitters.shutdown( { timeout: STAGE_TIMEOUT_MS } ) );
+                async () => throwFirstRejection( await emitters.shutdown( { timeout: STAGE_TIMEOUT_MS } ) ) );
             await runDrainStage( 'storage', stageErrors,
-                () => storages.shutdown( { timeout: STAGE_TIMEOUT_MS } ) );
+                async () => throwFirstRejection( await storages.shutdown( { timeout: STAGE_TIMEOUT_MS } ) ) );
         } finally {
             // Whatever the path here — clean drain or a stage that threw —
             // the source has stopped producing, so unblock any
@@ -311,6 +319,100 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
         return shutdownPromise;
     };
 
+    // Run the drain with its rejection observed. Both fire-and-forget
+    // call sites use this: the natural-completion trigger and the
+    // consecutive-failure escalation. drainAll rethrows the first
+    // stage error; with no awaiting caller that rejection would end
+    // the process as unhandled. The classified log keeps the loss
+    // loud without the crash, and a caller that later awaits
+    // `handle.shutdown()` still receives the memoized rejection.
+    //
+    // The exit code carries the loss too. This drain has no awaiting
+    // caller, and the flow left the shutdown manager's list when the
+    // drain began, so no other path can set it. A batch script that
+    // replays a file and loses rows at the end must exit 1, the same
+    // as the signal path does (ADR-018 §7).
+    const observedShutdown = function () {
+        shutdown().catch( function ( err ) {
+            process.exitCode = 1;
+            logger.error(
+                `winkComposer/flow '${flowName}': shutdown failed ` +
+                `[${( err && err.code ) || 'UNKNOWN'}]: ${( err && err.message ) || String( err )}`
+            );
+        } );
+    };
+
+    // ── Message dispatch with fault containment (ADR-018: the flow
+    // runtime owns per-message dispatch failure at this chokepoint) ──
+    // All containment state is flow-scoped policy, kept in this
+    // closure beside the shutdown state — never on the handle-exposed
+    // composerState. `reportDispatchFailure` stays null for a headless
+    // flow (no source); the source block below assigns it before the
+    // source ever receives processMessage.
+    let consecutiveFailures = 0;
+    let errored = false;
+    let erroredDropReported = false;
+    let reportDispatchFailure = null;
+
+    const processMessage = function ( msg ) {
+        // Terminal 'errored': drop everything. The first drop is
+        // reported once, classified; a flood of per-drop reports
+        // would bury the one terminal red that matters.
+        if ( errored ) {
+            if ( !erroredDropReported ) {
+                erroredDropReported = true;
+                logger.error(
+                    `winkComposer/flow '${flowName}': flow is in the terminal 'errored' ` +
+                    'phase [MESSAGE_HANDLER_FAILED] — dropping this and all further messages'
+                );
+            }
+            return undefined;
+        }
+
+        // Process first — pmUpdate always returns the graph synchronously
+        // (or null for a dropped message, which never sets the flag).
+        // The guard covers pmUpdate too: a first message for a new asset
+        // runs every node's init lazily, so an init throw surfaces here.
+        try {
+            const graph = partitionManager.update( composerState, msg );
+            if ( graph ) {
+                runPipeline( graph, msg );
+                // Reset on success only — a dropped message is neither
+                // a success nor a failure. Branch-guarded so the
+                // healthy steady state never writes.
+                if ( consecutiveFailures !== 0 ) {
+                    consecutiveFailures = 0;
+                }
+            }
+        } catch ( err ) {
+            if ( reportDispatchFailure === null ) {
+                // Headless: the caller is the reporting channel — the
+                // driver's catch and `failed` counter own the fault.
+                throw err;
+            }
+            consecutiveFailures += 1;
+            const isTerminal = consecutiveFailures >= ENV_VARS.messageFailureThreshold;
+            reportDispatchFailure( err, isTerminal );
+            if ( isTerminal ) {
+                errored = true;
+                observedShutdown();
+            }
+        }
+
+        // Breathe after (yield tick, rare): hand the awaiting caller a
+        // Promise that resolves once the event loop has had a full turn.
+        // Runs on the catch path too — pmUpdate may have set the flag
+        // before the pipeline threw, and the breath must not be lost.
+        if ( partitionState.yieldPending ) {
+            partitionState.yieldPending = false;
+            return new Promise( ( resolve ) => {
+                setImmediate( resolve );
+            } );
+        }
+
+        return undefined;
+    };
+
     // 7. Start source (singleton).
     if ( runtime.source ) {
         const { adapter, config } = runtime.source;
@@ -321,17 +423,42 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
         // too (they bypass the DSL entirely).
         assertModuleDurability( adapter.id || 'source', adapter );
 
+        // The callback guard below turns a non-function into null
+        // (absent). Validate raw first, so a misconfigured handler
+        // fails loudly at setup instead of silently vanishing. Placed
+        // here for the same reason as the durability check above:
+        // direct runFlow() callers bypass the DSL schema.
+        if ( config.onStatus !== undefined && config.onStatus !== null && typeof config.onStatus !== 'function' ) {
+            const err = new Error( `winkComposer/flow '${flowName}': onStatus must be a function` );
+            err.code = 'INVALID_CONFIG';
+            throw err;
+        }
+
         // Wrap user's onStatus so the runtime can spot the natural-
         // completion signal without taking it away from the user.
         // When the source signals `phase: 'complete'`:
         //   1. Resolve the whenComplete Promise so callers can stop
         //      waiting for natural completion.
-        //   2. Trigger the drain (`shutdown()` is fire-and-forget —
-        //      it's concurrent-safe and stages have their own timeouts).
-        const userOnStatus = config.onStatus;
+        //   2. Trigger the drain via observedShutdown — fire-and-forget
+        //      with its rejection logged; shutdown is concurrent-safe
+        //      and stages have their own timeouts.
+        // The user's handler is armed by the shared callback guard
+        // (ADR-018: a misbehaving user callback never interrupts the
+        // runtime that called it). Null when the flow has no handler,
+        // so the classified fallback branch below keeps red statuses
+        // loud.
+        const safeUserOnStatus = wrapCallback( config.onStatus, {
+            name: 'onStatus',
+            severity: 'red',
+            report: function ( severity, name, detail ) {
+                logger.error(
+                    `winkComposer/flow '${flowName}': user callback ${name} failed [CALLBACK_FAILED]: ${detail}`
+                );
+            }
+        } );
         const wrappedOnStatus = function ( s ) {
-            if ( userOnStatus ) {
-                userOnStatus( s );
+            if ( safeUserOnStatus ) {
+                safeUserOnStatus( s );
             } else if ( s && s.status === 'red' ) {
                 // No user handler: log the failure here, classified. The
                 // source's own console fallback fires only when NO handler
@@ -341,13 +468,39 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
                 const code = ( s.error && s.error.code ) || 'UNKNOWN';
                 const message = ( s.error && s.error.message ) ||
                     'source reported status red with no error detail';
-                console.error( `WinkComposer/flow '${flowName}': source error [${code}]: ${message}` );
+                logger.error( `winkComposer/flow '${flowName}': source error [${code}]: ${message}` );
             }
+            // Completion bookkeeping runs after — and independently of —
+            // the user's reporter. A throwing onStatus must never swallow
+            // the flow's own completion: whenComplete waiters would hang
+            // and the source would never stop.
             if ( s && s.phase === 'complete' ) {
                 resolveWhenComplete();
-                shutdown();
+                observedShutdown();
             }
         };
+
+        // The dispatch guard's reporting channel. Routing through
+        // wrappedOnStatus keeps the two-party rule: a flow without a
+        // user handler still gets the classified console fallback for
+        // red statuses. No local guard is needed here: the callback
+        // guard above contains a throwing user handler, and every other
+        // branch of wrappedOnStatus is throw-free.
+        reportDispatchFailure = function ( err, isTerminal ) {
+            const payload = {
+                status: 'red',
+                connected: true,
+                phase: isTerminal ? 'errored' : 'running',
+                error: {
+                    code: 'MESSAGE_HANDLER_FAILED',
+                    message: isTerminal ?
+                        `${ENV_VARS.messageFailureThreshold} consecutive message failures — ` +
+                        `flow stopped. Last: ${err.message}` :
+                        `${err.message} — message skipped`
+                }
+            };
+            wrappedOnStatus( payload );
+        };
         stopSource = adapter.start( {
             ...config,
             // Override any source-level auto-shutdown setting. The
@@ -362,10 +515,12 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
             onShutdown: shutdown
         } );
     } else {
-
-        /* c8 ignore next 3 -- defensive: the flow API rejects empty flows before run() is called, so a flow without a source cannot reach this branch via the public API. Kept as a safety net for direct runFlow() callers. */
-        // No source means "nothing to wait for" — resolve immediately
-        // so any `await handle.whenComplete()` is a no-op.
+        // The headless branch: a flow with no source is a documented
+        // DSL path (the headless driver feeds it). No source means
+        // "nothing to wait for" — resolve immediately so any
+        // `await handle.whenComplete()` is a no-op. And with no
+        // status channel, `reportDispatchFailure` stays null, so the
+        // dispatch guard rethrows pipeline faults to the caller.
         resolveWhenComplete();
     }
 
@@ -384,6 +539,11 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
         composerState,
         shutdown,
         processMessage,
+        // Cold-path counter snapshot (drops, partitions). Allocates one
+        // small object per call; never called by the pipeline itself.
+        getStats: function () {
+            return partitionManager.getStats( composerState );
+        },
         whenComplete: function () {
             return whenCompletePromise;
         }

package/src/flow/serialize.js

@@ -59,7 +59,7 @@ const serializeValue = function ( value, indent ) {
 
     if ( t === 'function' ) {
         const funcStr = value.toString();
-        if ( funcStr.includes( '[native code]' ) ) throw Error( 'WinkComposer/flow: only regular or arrow functions are supported.' );
+        if ( funcStr.includes( '[native code]' ) ) throw Error( 'winkComposer/flow: only regular or arrow functions are supported.' );
         return funcStr;
     }
 

package/src/flow/spec-builder.js

@@ -11,7 +11,7 @@ const buildStatsFromOutputs = function ( outputs ) {
         // overwrite case, caught at build time by check-output-collisions.js.
         if ( seenStoreAs[ storeAs ] ) {
             throw new Error(
-                `WinkComposer/flow: Node has duplicate storeAs '${storeAs}' ` +
+                `winkComposer/flow: Node has duplicate storeAs '${storeAs}' ` +
                 `for stats '${seenStoreAs[ storeAs ]}' and '${stat}'`
             );
         }

package/src/flow/validate.js

@@ -254,7 +254,7 @@ export const validateFlowOrThrow = function ( flowName, specs, nodeModules, regi
     if ( !result.valid ) {
         const errorList = result.errors.map( ( e ) => `  - ${e}` ).join( '\n' );
         throw new Error(
-            `Flow '${flowName}' validation failed:\n${errorList}`
+            `winkComposer/flow '${flowName}': validation failed:\n${errorList}`
         );
     }
 };

package/src/nodes/butterworth-filter/init.js

@@ -10,6 +10,7 @@
 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 { logger } from '../../core/logger/index.js';
 
 const init = function ( spec ) {
     validateSpec( spec, introspect );
@@ -74,14 +75,14 @@ const init = function ( spec ) {
     // Validate the computed cutoff
     if ( cutoffHz <= 0 || cutoffHz >= nyquistHz ) {
         throw new RangeError(
-            `Computed cutoff ${cutoffHz.toFixed(1)}Hz is outside valid range (0, ${nyquistHz}Hz)`
+            `winkComposer/butterworthFilter: Computed cutoff ${cutoffHz.toFixed(1)}Hz is outside valid range (0, ${nyquistHz}Hz)`
         );
     }
 
     // Warn about potential numerical issues
     const normalizedCutoff = cutoffHz / nyquistHz;
     if ( normalizedCutoff < 0.001 && !state.acceptNumericalRisk ) {
-        console.warn( `Very low cutoff (${cutoffHz.toFixed(3)}Hz) may cause numerical instability` );
+        logger.warn( `winkComposer/butterworthFilter: Very low cutoff (${cutoffHz.toFixed(3)}Hz) may cause numerical instability` );
     }
 
     // Store configuration for reference
@@ -127,14 +128,14 @@ const init = function ( spec ) {
     /* c8 ignore next 5 -- defensive: bilinear transform produces stable coefficients for valid Nyquist-bounded cutoff */
     if ( Math.abs( state.a2 ) >= 1 ) {
         throw new Error(
-            `Filter unstable: coefficient a2 (${state.a2.toFixed(4)}) is outside stability bounds`
+            `winkComposer/butterworthFilter: Filter unstable: coefficient a2 (${state.a2.toFixed(4)}) is outside stability bounds`
         );
     }
 
     /* c8 ignore next 5 -- defensive: same Nyquist guard prevents a1 stability violation */
     if ( Math.abs( state.a1 ) >= 1 + state.a2 ) {
         throw new Error(
-            `Filter unstable: coefficient a1 (${state.a1.toFixed(4)}) violates stability condition |a1| < 1 + a2`
+            `winkComposer/butterworthFilter: Filter unstable: coefficient a1 (${state.a1.toFixed(4)}) violates stability condition |a1| < 1 + a2`
         );
     }
 

package/src/nodes/categorize/update.js

@@ -6,6 +6,8 @@
  * threshold counts (3–5), linear search outperforms binary search.
  */
 
+import { logger } from '../../core/logger/index.js';
+
 const update = function ( state, msg ) {
     if ( state.disable || state.pause ) return state;
     const xVal = msg[ state.x ];
@@ -25,7 +27,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/controller/update.js

@@ -1,6 +1,7 @@
 // nodes/controller/update.js
 
 import { executeTriggers } from '../../core/utils/node/index.js';
+import { logger } from '../../core/logger/index.js';
 
 const update = function ( state, msg ) {
     // Track whether any predicate threw during this pass
@@ -22,7 +23,7 @@ const update = function ( state, msg ) {
             // Log first error per episode; suppress subsequent until recovery
             if ( !state.predicateErrorLogged ) {
                 state.predicateErrorLogged = true;
-                console.error( `WinkComposer/controller: predicate threw exception: ${error.message}` );
+                logger.error( `winkComposer/controller: predicate threw exception: ${error.message}` );
             }
             // Skip to next condition
             continue;  // eslint-disable-line no-continue

package/src/nodes/dwell-time-tracker/update.js

@@ -1,6 +1,7 @@
 // nodes/dwell-time-tracker/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;
@@ -20,7 +21,7 @@ const update = function ( state, msg ) {
         // Log first error per episode; suppress subsequent until recovery
         if ( !state.predicateErrorLogged ) {
             state.predicateErrorLogged = true;
-            console.error( `WinkComposer/dwellTimeTracker: predicate threw exception: ${error.message}` );
+            logger.error( `winkComposer/dwellTimeTracker: predicate threw exception: ${error.message}` );
         }
         return state;
     }