@winkjs/composer 0.5.1 → 0.7.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',