@winkjs/composer 0.5.0 → 0.6.0

package/src/core/source-manager/csv/start.js

@@ -25,6 +25,11 @@
  *                           malformed, transform-dropped, or
  *                           transform-failed. For in-range rows,
  *                           count + skipped covers every data row read.
+ *                           `count` means handed to the flow: a row the
+ *                           pipeline later failed on still counts here.
+ *                           Failure visibility belongs to the flow's
+ *                           MESSAGE_HANDLER_FAILED reports (ADR-018),
+ *                           not to this counter.
  *     `phase: 'errored'`  — terminal red: the run loop failed and the
  *                           stream is dead (the ADR-018 two-tier rule).
  *     `phase: 'stopped'`  — forced stop exceeded its time budget
@@ -40,19 +45,45 @@
  *   stream continues — per-record skip-classify-continue (ADR-018).
  *   A bad field VALUE in a parseable row is NOT a decode error;
  *   it passes through for the pipeline (`sanitize`) to judge.
- * - `CALLBACK_FAILED`    — the user's `transform` threw on one row. The
- *   row is skipped (counted in `skipped`), the throw is reported per
- *   record with `status: 'yellow'`, and the stream continues — user
- *   code is never reported as a stream failure. Fix the transform
- *   function; the report names the data row. Uniform with the MQTT
- *   source (transform contract, 2026-07-11).
+ * - `CALLBACK_FAILED`    — a piece of user code failed. It covers two
+ *   cases. Case one: the user's `transform` threw on one row, or
+ *   returned a scalar or array where a record object was needed. The
+ *   row is skipped (counted in `skipped`), the fault is reported per
+ *   record with `status: 'yellow'`, and the stream continues. User
+ *   code is never reported as a stream failure. A null/undefined
+ *   return is NOT this case: it is the documented intentional drop.
+ *   Fix the transform function; the report names the data row.
+ *   Uniform with the MQTT source (transform contract, 2026-07-11).
+ *   Case two: the user's `onStatus` itself threw or rejected. The
+ *   shared callback guard contains that fault (ADR-018). The replay
+ *   continues, and each fault becomes one classified console line
+ *   that carries the detail.
  * - `READ_ERROR`         — stream read failed mid-stream (encoding error,
  *   truncation, decoder failure, etc.). Catch-all for non-open failures.
+ *   Narrowed by the flow's dispatch guard (ADR-018): in a flow, a
+ *   pipeline fault is contained at the flow's own chokepoint and
+ *   reported as MESSAGE_HANDLER_FAILED, so it never surfaces here and
+ *   never ends the replay. The code remains live for genuine stream
+ *   failures, and for direct callers of start() whose own onMessage
+ *   throws.
  */
 
 import fs from 'node:fs';
 import readline from 'node:readline';
 
+import { isUsableRecord, describeShape } from '../record-shape.js';
+import { wrapCallback, wrapTransform, TRANSFORM_THREW } from '../../utils/callback-guard/index.js';
+import { logger } from '../../logger/index.js';
+
+/**
+ * Console channel for the callback guard: one classified line in this
+ * source's family. Receives an already-safe detail string, never the
+ * raw thrown value.
+ */
+const reportCallbackFault = function ( severity, name, detail ) {
+    logger.error( `winkComposer/csvSource: user callback ${name} failed [CALLBACK_FAILED]: ${detail}` );
+}; // reportCallbackFault()
+
 /**
  * Detects delimiter from header line.
  * @param {string} headerLine - First line of CSV
@@ -187,7 +218,8 @@ const checkRange = function ( rangeKey, wasInRange, startMsgId, endMsgId ) {
  * @param {boolean} [config.dynamicTyping=true] - Auto-cast values
  * @param {Function} [config.transform] - Optional row transform:
  *   ( row ) => row; return null/undefined to drop (counted in skipped);
- *   a throw skips the row (CALLBACK_FAILED) and the stream continues
+ *   a throw or a scalar/array return skips the row (CALLBACK_FAILED)
+ *   and the stream continues
  * @param {Function} [config.onStatus] - Status callback; completion arrives
  *   here as `{phase: 'complete', count, skipped}` (per ADR-018 there is
  *   no onComplete callback)
@@ -213,12 +245,30 @@ export const start = function ( config ) {
         endMsgId = null
     } = config;
 
+    // The guard below turns a non-function into null (absent). So a
+    // misconfigured handler must be rejected here, loudly, before the
+    // wrap can silently erase it. Null stays legal as "no handler".
+    if ( onStatus !== null && typeof onStatus !== 'function' ) {
+        const err = new Error( 'winkComposer/csvSource: onStatus must be a function' );
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+
     let stopped = false;
     let rowCount = 0;
     let rowIndex = 0;
     let skippedCount = 0;
     let inRange = ( startMsgId === null );  // Start immediately if no startMsgId
 
+    // The user's onStatus is armed once by the shared callback guard
+    // (ADR-018). A throw or rejection inside it becomes one classified
+    // CALLBACK_FAILED console line, and the replay continues. Absent
+    // stays null, so every no-handler console fallback below keeps
+    // its exact meaning.
+    const safeOnStatus = wrapCallback( onStatus, {
+        name: 'onStatus', severity: 'red', report: reportCallbackFault
+    } );
+
     // Per-record skip-classify-continue (ADR-018): a structurally
     // malformed row is skipped and signalled — never a silent drop. When
     // the caller owns reporting (onStatus supplied) the framework stays
@@ -226,50 +276,73 @@ export const start = function ( config ) {
     // visible (ADR-018's two-party rule).
     const reportDecodeError = function ( dataRowIndex, fault ) {
         const message = `data row ${dataRowIndex}: ${fault} — row skipped`;
-        if ( onStatus ) {
-            onStatus( {
+        if ( safeOnStatus ) {
+            safeOnStatus( {
                 status: 'yellow',
                 connected: true,
                 phase: 'running',
                 error: { code: 'DECODE_ERROR', message }
             } );
         } else {
-            console.error( `CSV source error [DECODE_ERROR]: ${message}` );
+            logger.error( `winkComposer/csvSource: decode failed [DECODE_ERROR]: ${message}` );
         }
     };
 
-    // A throwing transform is user code, never a stream failure: the
+    // A faulty transform is user code, never a stream failure: the
     // row is skipped with a per-record CALLBACK_FAILED report and the
     // stream continues (transform contract, uniform with the MQTT
     // source, 2026-07-11). Same two-party reporting rule as decode
-    // errors above.
-    const reportCallbackError = function ( dataRowIndex, err ) {
-        const message = `data row ${dataRowIndex}: transform threw: ${err.message} — row skipped`;
-        if ( onStatus ) {
-            onStatus( {
+    // errors above. `detail` names the fault (a throw, or an
+    // unusable return shape).
+    const reportCallbackError = function ( dataRowIndex, detail ) {
+        const message = `data row ${dataRowIndex}: ${detail} — row skipped`;
+        if ( safeOnStatus ) {
+            safeOnStatus( {
                 status: 'yellow',
                 connected: true,
                 phase: 'running',
                 error: { code: 'CALLBACK_FAILED', message }
             } );
         } else {
-            console.error( `CSV source error [CALLBACK_FAILED]: ${message}` );
+            logger.error( `winkComposer/csvSource: source error [CALLBACK_FAILED]: ${message}` );
         }
     };
 
+    // The user's transform is pre-armed by the shared callback guard,
+    // once here — never per row (ADR-018). A throw inside it becomes
+    // the sentinel plus one per-record CALLBACK_FAILED report. The
+    // row index travels as the guard's per-call context, so the
+    // success path allocates nothing.
+    const reportTransformFault = function ( detail, dataRowIndex ) {
+        reportCallbackError( dataRowIndex, `transform threw: ${detail}` );
+    };
+    const guardedTransform = transform ? wrapTransform( transform, reportTransformFault ) : null;
+
     // Run the user's transform under guard. Returns the transformed
-    // row; null when the transform threw (reported above) — the caller
-    // counts every null/undefined result as skipped.
+    // row; null when the row must be skipped — the caller counts
+    // every null/undefined result as skipped. Three skip faces: a
+    // throw (reported), a scalar or array return (reported — an
+    // unusable record), and a null/undefined return (the documented
+    // intentional drop, counted but never reported).
     const applyTransform = function ( row, dataRowIndex ) {
-        if ( !transform ) {
+        if ( !guardedTransform ) {
             return row;
         }
-        try {
-            return transform( row );
-        } catch ( err ) {
-            reportCallbackError( dataRowIndex, err );
+        const out = guardedTransform( row, dataRowIndex );
+        // The sentinel check runs FIRST: the sentinel is a plain
+        // object, so a later isUsableRecord check would wave it
+        // through as a row.
+        if ( out === TRANSFORM_THREW ) {
+            return null;
+        }
+        if ( out === null || out === undefined ) {
+            return null;
+        }
+        if ( !isUsableRecord( out ) ) {
+            reportCallbackError( dataRowIndex, `transform returned ${describeShape( out )} — a record object (or null/undefined to drop) is required` );
             return null;
         }
+        return out;
     };
 
     // Holds the file stream so the stop function can close it if the
@@ -292,7 +365,7 @@ export const start = function ( config ) {
         let headers = null;
         let delimiter = ',';
 
-        if ( onStatus ) onStatus( {
+        if ( safeOnStatus ) safeOnStatus( {
             status: 'green',
             connected: true,
             phase: 'starting',
@@ -308,7 +381,7 @@ export const start = function ( config ) {
                 if ( !headers ) {
                     delimiter = detectDelimiter( line );
                     headers = parseLine( line, delimiter ).values;
-                    if ( onStatus ) onStatus( {
+                    if ( safeOnStatus ) safeOnStatus( {
                         status: 'green',
                         connected: true,
                         phase: 'headers',
@@ -340,9 +413,10 @@ export const start = function ( config ) {
                 if ( inRange ) {
                     const msg = applyTransform( row, rowIndex );
 
-                    // Only null/undefined mean drop — any other return,
-                    // however falsy, is delivered (transform contract,
-                    // uniform with the MQTT source, 2026-07-11).
+                    // applyTransform maps every skip face (throw, bad
+                    // shape, intentional drop) to null/undefined; the
+                    // caller only counts (transform contract, uniform
+                    // with the MQTT source, 2026-07-11).
                     if ( msg !== null && msg !== undefined ) {
                         await onMessage( msg );
                         rowCount += 1;
@@ -365,7 +439,7 @@ export const start = function ( config ) {
 
         // Completion travels onStatus with the uniform `count` field
         // (per ADR-018 there is no onComplete callback).
-        if ( onStatus ) onStatus( {
+        if ( safeOnStatus ) safeOnStatus( {
             status: 'green',
             connected: false,
             phase: 'complete',
@@ -391,17 +465,17 @@ export const start = function ( config ) {
             'SOURCE_UNREACHABLE' :
             'READ_ERROR';
         const message = ( err && err.message ) ? err.message : String( err );
-        if ( onStatus ) {
+        if ( safeOnStatus ) {
             // Terminal red: the stream is dead. Uniform payload with
             // phase 'errored' per the ADR-018 two-tier rule.
-            onStatus( {
+            safeOnStatus( {
                 status: 'red',
                 connected: false,
                 phase: 'errored',
                 error: { code, message }
             } );
         } else {
-            console.error( `CSV source error [${code}]: ${message}` );
+            logger.error( `winkComposer/csvSource: source error [${code}]: ${message}` );
         }
     } ).finally( () => {
         resolveFinished();
@@ -438,8 +512,8 @@ export const start = function ( config ) {
             };
             forceTimer = setTimeout( () => {
                 if ( activeStream ) activeStream.destroy();
-                if ( onStatus ) {
-                    onStatus( {
+                if ( safeOnStatus ) {
+                    safeOnStatus( {
                         status: 'yellow',
                         connected: false,
                         phase: 'stopped',

package/src/core/source-manager/mqtt/client.js

@@ -15,7 +15,8 @@
  * Message flow:
  *   MQTT broker → subscribe → extract userProperties → check dedup cache
  *       → if duplicate: skip, count (dedupHits — not a status event)
- *       → if new: decode payload → transform (optional) → onMessage(msg)
+ *       → if new: decode payload → shape guard + metadata attach
+ *         → transform (optional) → onMessage(msg)
  *
  * Status shape — the ADR-018 core, plus this adapter's additions:
  *   `{status: 'green' | 'yellow' | 'red', connected, phase,
@@ -34,14 +35,27 @@
  *   field. Thrown synchronously from the factory (ADR-018 fail-fast
  *   setup), never emitted.
  * - `DECODE_ERROR`           — runtime, yellow. Two faces: a per-record
- *   report for every payload that cannot be decoded (skip, classify,
- *   continue — ADR-018), and a health flip when the decode-error ratio over
- *   the last 1,000 messages exceeds 1 %.
- * - `CALLBACK_FAILED`        — runtime, yellow. The user's `transform`
- *   threw; that one message is skipped (counted in `skipped`) and the
- *   stream continues. Fix the transform function — the report names
- *   the topic and the thrown message. Uniform with the CSV source
- *   (transform contract, 2026-07-11).
+ *   report for every payload that does not yield a usable record, and
+ *   a health flip when the decode-error ratio over the last 1,000
+ *   messages exceeds 1 %. The per-record face covers more than parse
+ *   failures (a widening of ADR-018 §9's original wording): a payload
+ *   that decodes to a scalar, null, or a bare array is rejected too,
+ *   and so is a record the metadata attach cannot write to (a frozen
+ *   record from a custom codec). Skip, classify, continue — the
+ *   report names what arrived. A bare scalar landing here usually
+ *   means a too-wide topic subscription; narrow the topic filter.
+ * - `CALLBACK_FAILED`        — runtime, yellow. A piece of user code
+ *   failed. It covers two cases. Case one: the user's `transform`
+ *   threw, or returned a scalar or array where a record object was
+ *   needed. That one message is skipped (counted in `skipped`) and
+ *   the stream continues. Fix the transform function — the report
+ *   names the topic and the fault. A null/undefined return is NOT
+ *   this case: it is the documented intentional drop. Uniform with
+ *   the CSV source (transform contract, 2026-07-11). Case two: the
+ *   user's `onStatus` or `onMetrics` itself threw or rejected. The
+ *   shared callback guard contains that fault (ADR-018, wired in
+ *   status.js). The stream continues, and each fault is reported
+ *   once with the detail.
  * - `SUBSCRIBE_FAILED`       — runtime, red. The broker refused the
  *   subscription (typically ACL). Red immediately: nothing retries a
  *   subscribe until the next reconnect, so a deaf-but-connected source
@@ -119,6 +133,9 @@ import {
 } from './constants.js';
 import { createDedupCache } from './dedup.js';
 import { createStatusReporter } from './status.js';
+import { isUsableRecord, describeShape } from '../record-shape.js';
+import { wrapTransform, TRANSFORM_THREW } from '../../utils/callback-guard/index.js';
+import { logger } from '../../logger/index.js';
 
 // ============================================================================
 // CLIENT FACTORY
@@ -133,7 +150,10 @@ import { createStatusReporter } from './status.js';
  * @param {string|string[]} config.topics - Topic(s) to subscribe to (supports wildcards)
  * @param {function} config.onMessage - Message handler: (message) => void
  * @param {Object} [config.codec] - Codec for payload decoding (default: JSON.parse)
- * @param {function} [config.transform] - Optional message transform: (msg) => transformedMsg
+ * @param {function} [config.transform] - Optional message transform:
+ *   (msg) => transformedMsg; return null/undefined to drop (counted in
+ *   skipped); a throw or a scalar/array return skips the message
+ *   (CALLBACK_FAILED) and the stream continues
  * @param {number} [config.dedupWindowMs=120000] - Dedup time bound (ADR-022)
  * @param {number} [config.dedupMaxEntries=65536] - Dedup count cap (ADR-022)
  * @param {string} [config.clientId] - MQTT client ID (auto-generated if omitted)
@@ -168,17 +188,17 @@ const createMQTTSourceClient = function ( config ) {
     // Validate required config. Per ADR-018, setup-time throws carry
     // classified err.code (INVALID_CONFIG for missing/malformed config fields).
     if ( !brokerUrl ) {
-        const err = new Error( 'WinkComposer/mqtt-source: brokerUrl is required' );
+        const err = new Error( 'winkComposer/mqttSource: brokerUrl is required' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
     if ( !topics || ( Array.isArray( topics ) && topics.length === 0 ) ) {
-        const err = new Error( 'WinkComposer/mqtt-source: topics is required' );
+        const err = new Error( 'winkComposer/mqttSource: topics is required' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
     if ( typeof onMessage !== 'function' ) {
-        const err = new Error( 'WinkComposer/mqtt-source: onMessage must be a function' );
+        const err = new Error( 'winkComposer/mqttSource: onMessage must be a function' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -201,6 +221,17 @@ const createMQTTSourceClient = function ( config ) {
 
     reporter.starting();
 
+    // The user's transform runs under the shared callback guard, armed
+    // once here — never per message. A throw inside it becomes the
+    // sentinel plus one per-record CALLBACK_FAILED report through the
+    // reporter; the message handler turns the sentinel into a skip.
+    // The topic travels as the guard's per-call context, so the
+    // success path allocates nothing (ADR-018).
+    const reportTransformFault = function ( detail, topic ) {
+        reporter.transformFailed( `topic '${topic}': transform threw: ${detail} — message skipped` );
+    };
+    const guardedTransform = transform ? wrapTransform( transform, reportTransformFault ) : null;
+
     // Generate client ID if not provided
     const generatedClientId = clientId || `wink-source-${Date.now()}`;
 
@@ -211,8 +242,8 @@ const createMQTTSourceClient = function ( config ) {
     // Warn once at startup; the fix is one config line. Setup path
     // only — nothing here touches the message path.
     if ( !clientId && cleanStart !== true ) {
-        console.warn(
-            'WinkComposer/mqtt-source: no clientId configured — this session ' +
+        logger.warn(
+            'winkComposer/mqttSource: no clientId configured — this session ' +
             `is persistent under the auto-generated name '${generatedClientId}'. ` +
             'After a restart, composer connects under a NEW name, so messages ' +
             'the broker saved during the downtime are never delivered. Set a ' +
@@ -281,9 +312,16 @@ const createMQTTSourceClient = function ( config ) {
             reporter.idAccepted();
         }
 
-        // Decode payload. A payload that cannot be decoded is skipped,
+        // Decode payload, check its shape, and attach metadata — one
+        // guarded region. A failure anywhere in it is skipped,
         // classified, and reported per record (ADR-018) — the stream
-        // continues.
+        // continues. The shape guard is needed because a valid JSON
+        // document can be a scalar or a bare array; the attach is
+        // inside the guard because a codec can return a frozen record
+        // (or one with a non-writable _topic), and the assignment then
+        // throws in strict mode. decodeOk() runs only when the whole
+        // record survived, so the ring gets exactly one entry per
+        // message.
         let message;
         try {
             if ( codec && typeof codec.unpack === 'function' ) {
@@ -291,35 +329,56 @@ const createMQTTSourceClient = function ( config ) {
             } else {
                 message = JSON.parse( payload.toString() );
             }
+
+            if ( !isUsableRecord( message ) ) {
+                reporter.decodeFailed( `topic '${topic}': payload decoded to ${describeShape( message )} — a record object is required — message skipped` );
+                return;
+            }
+
+            // Attach metadata for downstream use
+            message._topic = topic;  // eslint-disable-line no-underscore-dangle
+            message._dedupId = dedupId;  // eslint-disable-line no-underscore-dangle
+
             reporter.decodeOk();
         } catch ( err ) {
             reporter.decodeFailed( `topic '${topic}': ${err.message} — message skipped` );
             return;
         }
 
-        // Attach metadata for downstream use
-        message._topic = topic;  // eslint-disable-line no-underscore-dangle
-        message._dedupId = dedupId;  // eslint-disable-line no-underscore-dangle
-
-        // Apply optional transform. Guarded: a throw skips this one
-        // message with a per-record CALLBACK_FAILED report and the
-        // stream continues — user code must never propagate into
-        // mqtt.js's event processing (transform contract, 2026-07-11).
+        // Apply the optional transform, pre-armed by the shared guard
+        // at startup. A throw skips this one message with a per-record
+        // CALLBACK_FAILED report, and the stream continues. User code
+        // must never propagate into mqtt.js's event processing
+        // (transform contract, 2026-07-11). The return is held to the
+        // same record shape as the payload. A null/undefined return
+        // stays the intentional silent drop. A scalar or array return
+        // is one per-record CALLBACK_FAILED. The shape check runs only
+        // when a transform is configured, so the plain path pays
+        // nothing.
         let finalMessage;
-        try {
-            finalMessage = transform ? transform( message ) : message;
-        } catch ( err ) {
-            reporter.transformFailed( `topic '${topic}': transform threw: ${err.message} — message skipped` );
-            return;
+        if ( guardedTransform ) {
+            finalMessage = guardedTransform( message, topic );
+            // The sentinel check runs FIRST: the sentinel is a plain
+            // object, so a later isUsableRecord check would wave it
+            // through into onMessage as a message.
+            if ( finalMessage === TRANSFORM_THREW ) {
+                return;
+            }
+            if ( finalMessage === null || finalMessage === undefined ) {
+                reporter.transformDropped();
+                return;
+            }
+            if ( !isUsableRecord( finalMessage ) ) {
+                reporter.transformFailed( `topic '${topic}': transform returned ${describeShape( finalMessage )} — a record object (or null/undefined to drop) is required — message skipped` );
+                return;
+            }
+        } else {
+            finalMessage = message;
         }
 
         // Deliver to handler
-        if ( finalMessage !== null && finalMessage !== undefined ) {
-            onMessage( finalMessage );
-            reporter.delivered();
-        } else {
-            reporter.transformDropped();
-        }
+        onMessage( finalMessage );
+        reporter.delivered();
     } );
 
     client.on( 'offline', function () {

package/src/core/source-manager/mqtt/dedup.js

@@ -87,7 +87,7 @@ import {
  */
 const assertPositiveInteger = function ( value, name ) {
     if ( typeof value !== 'number' || value < 1 || !Number.isInteger( value ) ) {
-        const err = new Error( `WinkComposer/mqtt-source: ${name} must be a positive integer` );
+        const err = new Error( `winkComposer/mqttSource: ${name} must be a positive integer` );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -114,7 +114,7 @@ const assertPositiveInteger = function ( value, name ) {
  */
 const createDedupCache = function ( options = {} ) {
     if ( typeof options !== 'object' || options === null ) {
-        const err = new Error( 'WinkComposer/mqtt-source: dedup options must be an object' );
+        const err = new Error( 'winkComposer/mqttSource: dedup options must be an object' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -128,7 +128,7 @@ const createDedupCache = function ( options = {} ) {
     assertPositiveInteger( windowMs, 'windowMs' );
     assertPositiveInteger( maxEntries, 'maxEntries' );
     if ( typeof nowFn !== 'function' ) {
-        const err = new Error( 'WinkComposer/mqtt-source: nowFn must be a function' );
+        const err = new Error( 'winkComposer/mqttSource: nowFn must be a function' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }

package/src/core/source-manager/mqtt/index.js

@@ -1,7 +1,7 @@
 // core/source-manager/mqtt/index.js
 
 /**
- * @fileoverview MQTT source adapter for WinkComposer aggregator.
+ * @fileoverview MQTT source adapter for winkComposer.
  *
  * Subscribes to edge composer MQTT outputs with deduplication for QoS 1.
  * Extracts winkDedupId from MQTT v5 user properties to filter retransmissions.