@winkjs/composer 0.5.0 → 0.6.0

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

@@ -25,6 +25,10 @@
  *   dedupHits, dedupMisses, dedupBypassed, dedupCacheSize}`, emitted
  *   on every tick() (the client's 1 Hz cadence) and on every health
  *   transition. Consumers diff snapshots; nothing is ever reset.
+ *   `delivered` means handed to the flow: a message 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.
  *
  * Health rules (evaluated on events and on tick):
  * - RED    — a subscribe failure (connected but deaf — no retry
@@ -84,6 +88,8 @@ import {
     DISCONNECT_RED_MS,
     DECODE_RING_SIZE
 } from './constants.js';
+import { wrapCallback } from '../../utils/callback-guard/index.js';
+import { logger } from '../../logger/index.js';
 
 // ============================================================================
 // VALIDATION HELPERS
@@ -98,7 +104,7 @@ import {
  */
 const assertOptionalFunction = function ( value, name ) {
     if ( value !== undefined && value !== null && typeof value !== 'function' ) {
-        const err = new Error( `WinkComposer/mqtt-source: ${name} must be a function` );
+        const err = new Error( `winkComposer/mqttSource: ${name} must be a function` );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -124,7 +130,7 @@ const assertOptionalFunction = function ( value, name ) {
  */
 const createStatusReporter = function ( options = {} ) {
     if ( typeof options !== 'object' || options === null ) {
-        const err = new Error( 'WinkComposer/mqtt-source: status reporter options must be an object' );
+        const err = new Error( 'winkComposer/mqttSource: status reporter options must be an object' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -141,7 +147,7 @@ const createStatusReporter = function ( options = {} ) {
     assertOptionalFunction( onMetrics, 'onMetrics' );
     assertOptionalFunction( dedupSizeFn, 'dedupSizeFn' );
     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;
     }
@@ -149,7 +155,7 @@ const createStatusReporter = function ( options = {} ) {
          ( typeof expectedQuietPeriodMs !== 'number' ||
            expectedQuietPeriodMs < 1 ||
            !Number.isInteger( expectedQuietPeriodMs ) ) ) {
-        const err = new Error( 'WinkComposer/mqtt-source: expectedQuietPeriodMs must be a positive integer' );
+        const err = new Error( 'winkComposer/mqttSource: expectedQuietPeriodMs must be a positive integer' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -220,14 +226,20 @@ const createStatusReporter = function ( options = {} ) {
         };
     };
 
-    /**
-     * Emit a metrics snapshot when the caller asked for one.
-     */
-    const emitMetrics = function () {
-        if ( onMetrics ) {
-            onMetrics( snapshot() );
+    // Both user callbacks are armed by the shared callback guard.
+    // They were validated raw above and are wrapped here, once
+    // (ADR-018: a misbehaving user callback never reaches transport
+    // code and never fails silently). A broken onStatus reports to
+    // the console in this adapter's classified line family. It
+    // cannot report through itself. A broken onMetrics reports on
+    // both channels; the comment at its wrap below explains why.
+    const safeOnStatus = wrapCallback( onStatus, {
+        name: 'onStatus',
+        severity: 'red',
+        report: function ( severity, name, detail ) {
+            logger.error( `winkComposer/mqttSource: user callback ${name} failed [CALLBACK_FAILED]: ${detail}` );
         }
-    };
+    } );
 
     /**
      * Route a status payload: to the caller's handler when supplied;
@@ -238,10 +250,51 @@ const createStatusReporter = function ( options = {} ) {
      * @param {Object} payload - The structured status payload
      */
     const emitStatus = function ( payload ) {
-        if ( onStatus ) {
-            onStatus( payload );
+        if ( safeOnStatus ) {
+            safeOnStatus( payload );
         } else if ( payload.error ) {
-            console.error( `MQTT source error [${payload.error.code}]: ${payload.error.message}` );
+            logger.error( `winkComposer/mqttSource: source error [${payload.error.code}]: ${payload.error.message}` );
+        }
+    };
+
+    // The metrics fault report allocates on the failure path only.
+    // `connected` and `phase` read the reporter's live state at fault
+    // time, so the payload tells the truth about the moment it fired.
+    //
+    // The console line comes first and always fires. It is the
+    // guaranteed audience: inside a flow the runtime installs its own
+    // onStatus wrapper, which forwards only red payloads when the
+    // user gave no handler, so the yellow payload alone could vanish
+    // (fresh-eyes find, 2026-08-28). The payload then additionally
+    // reaches a listening handler, so a health view sees the
+    // degradation. With no handler at all, emitStatus would print
+    // the same line a second time — skip the payload there.
+    const safeOnMetrics = wrapCallback( onMetrics, {
+        name: 'onMetrics',
+        severity: 'yellow',
+        report: function ( severity, name, detail ) {
+            const message = `user callback ${name} failed: ${detail}`;
+            logger.error( `winkComposer/mqttSource: user callback ${name} failed [CALLBACK_FAILED]: ${detail}` );
+            if ( safeOnStatus ) {
+                emitStatus( {
+                    status: severity,
+                    connected,
+                    phase,
+                    error: {
+                        code: 'CALLBACK_FAILED',
+                        message
+                    }
+                } );
+            }
+        }
+    } );
+
+    /**
+     * Emit a metrics snapshot when the caller asked for one.
+     */
+    const emitMetrics = function () {
+        if ( safeOnMetrics ) {
+            safeOnMetrics( snapshot() );
         }
     };
 

package/src/core/source-manager/record-shape.js

@@ -0,0 +1,55 @@
+// core/source-manager/record-shape.js
+
+/**
+ * @fileoverview One definition of "usable record" for every source.
+ *
+ * A source hands the pipeline record objects. A decoded payload or a
+ * transform return can instead be a scalar, null, undefined, or a
+ * bare array. All of those are valid JSON documents, so decoding
+ * alone cannot reject them. Attaching metadata to them throws in
+ * strict mode. This module gives every source the same two tools:
+ * the guard predicate, and the plain name of the rejected shape for
+ * the per-record report (skip-classify-continue, ADR-018).
+ *
+ * Kept as one shared module so the MQTT and CSV sources cannot
+ * drift apart on what a usable record is (the cross-source
+ * transform contract).
+ */
+
+/**
+ * Tell whether a decoded value can carry pipeline fields: a real
+ * object, not null, not an array. Hot-path cost is one comparison,
+ * one typeof, and one Array.isArray — no allocation.
+ *
+ * @param {*} value - Decoded payload or transform return
+ * @returns {boolean} True when the value is a usable record
+ */
+const isUsableRecord = function ( value ) {
+    return ( value !== null ) && ( typeof value === 'object' ) && !Array.isArray( value );
+};
+
+/**
+ * Name a rejected value's shape for an operator-facing report.
+ * Called on the failure path only, so the string cost is fine.
+ *
+ * @param {*} value - The rejected value
+ * @returns {string} Plain shape name, e.g. 'a number', 'an array'
+ */
+const describeShape = function ( value ) {
+    if ( value === null ) {
+        return 'null';
+    }
+    if ( value === undefined ) {
+        return 'undefined';
+    }
+    if ( Array.isArray( value ) ) {
+        return 'an array';
+    }
+    return `a ${typeof value}`;
+};
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export { isUsableRecord, describeShape };

package/src/core/source-manager/test-harness/field-generator.js

@@ -80,6 +80,6 @@ export const generateField = function ( fieldSpec, prng, msgIndex, intervalMs )
         default:
             // Unreachable in practice — validate.js rejects unknown
             // types at startup. Kept for clarity at the boundary.
-            throw new Error( `testHarness: unknown field type "${fieldSpec.type}"` );
+            throw new Error( `winkComposer/testHarness: unknown field type "${fieldSpec.type}"` );
     }
 };

package/src/core/source-manager/test-harness/start.js

@@ -37,7 +37,20 @@
  *                        class. Thrown synchronously from start().
  * - `GENERATOR_ERROR`  — runtime; a downstream `onMessage` call
  *                        threw inside the loop. Routed through
- *                        onStatus, not re-thrown.
+ *                        onStatus, not re-thrown. 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
+ *                        reaches this loop. The code remains live
+ *                        for direct callers of start() whose own
+ *                        onMessage throws.
+ * - `CALLBACK_FAILED`  — runtime; the user's `onStatus` itself threw
+ *                        or rejected. The shared callback guard
+ *                        contains the fault (ADR-018): generation
+ *                        continues and each fault becomes one
+ *                        classified console line. Fix the onStatus
+ *                        handler; the line carries the fault detail.
  *
  * Design decisions date from 2026-04-29. The `messageTemplate` shape
  * is enforced at startup by `validate.js`; the per-field spec shape
@@ -48,6 +61,17 @@ import { createPrng } from './prng.js';
 import { generateField } from './field-generator.js';
 import { applyFuzz, FUZZ_PATTERN_NAMES } from './fuzz.js';
 import { validateMessageTemplate, validateAssetClass } from './validate.js';
+import { wrapCallback } 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/testHarness: user callback ${name} failed [CALLBACK_FAILED]: ${detail}` );
+}; // reportCallbackFault()
 
 const DEFAULT_MESSAGE_COUNT = 1000;
 const DEFAULT_INTERVAL_MS   = 0;
@@ -83,7 +107,16 @@ export const start = function ( config ) {
     validateAssetClass( assetClass );
 
     if ( typeof onMessage !== 'function' ) {
-        const err = new Error( 'testHarness: onMessage must be a function' );
+        const err = new Error( 'winkComposer/testHarness: onMessage must be a function' );
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+
+    // 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/testHarness: onStatus must be a function' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -108,7 +141,16 @@ export const start = function ( config ) {
         resolveFinished = resolve;
     } );
 
-    if ( onStatus ) onStatus( {
+    // 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 generation continues. Absent
+    // stays null, so the no-handler console fallback below keeps its
+    // exact meaning.
+    const safeOnStatus = wrapCallback( onStatus, {
+        name: 'onStatus', severity: 'red', report: reportCallbackFault
+    } );
+
+    if ( safeOnStatus ) safeOnStatus( {
         status: 'green',
         connected: true,
         phase: 'starting',
@@ -117,7 +159,7 @@ export const start = function ( config ) {
     } );
 
     const run = async function () {
-        if ( onStatus ) onStatus( {
+        if ( safeOnStatus ) safeOnStatus( {
             status: 'green',
             connected: true,
             phase: 'generating'
@@ -152,7 +194,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',
@@ -171,17 +213,17 @@ export const start = function ( config ) {
     // wait on it.
     run().catch( ( err ) => {
         const message = ( err && err.message ) ? err.message : String( err );
-        if ( onStatus ) {
+        if ( safeOnStatus ) {
             // Terminal red: generation stopped. Uniform payload with
             // phase 'errored' per the ADR-018 two-tier rule.
-            onStatus( {
+            safeOnStatus( {
                 status: 'red',
                 connected: false,
                 phase: 'errored',
                 error: { code: 'GENERATOR_ERROR', message }
             } );
         } else {
-            console.error( `testHarness error [GENERATOR_ERROR]: ${message}` );
+            logger.error( `winkComposer/testHarness: generator failed [GENERATOR_ERROR]: ${message}` );
         }
     } ).finally( () => {
         resolveFinished();
@@ -215,8 +257,8 @@ export const start = function ( config ) {
                 resolve();
             };
             forceTimer = setTimeout( () => {
-                if ( onStatus ) {
-                    onStatus( {
+                if ( safeOnStatus ) {
+                    safeOnStatus( {
                         status: 'yellow',
                         connected: false,
                         phase: 'stopped',

package/src/core/source-manager/test-harness/validate.js

@@ -173,7 +173,7 @@ export const ASSET_CLASS_SCHEMA = {
 };
 
 const throwInvalidConfig = function ( errors ) {
-    const err = new Error( `testHarness: ${errors.join( '; ' )}` );
+    const err = new Error( `winkComposer/testHarness: ${errors.join( '; ' )}` );
     err.code = 'INVALID_CONFIG';
     throw err;
 };

package/src/core/storage-manager/questdb/assert-columns.js

@@ -89,7 +89,7 @@ const assertColumnFacts = function ( assetClass ) {
             const supportedTypes = Object.keys( DDL_TYPES ).join( ', ' );
             const actualType = colSpec ? String( colSpec.type ) : 'undefined';
             const err = new Error(
-                `WinkComposer/questdb: column '${colName}' has invalid or missing type '${actualType}'; ` +
+                `winkComposer/questdb: column '${colName}' has invalid or missing type '${actualType}'; ` +
                 `expected one of: ${supportedTypes}`
             );
             err.code = 'INVALID_CONFIG';
@@ -106,7 +106,7 @@ const assertColumnFacts = function ( assetClass ) {
                 !Number.isFinite( colSpec.resolution ) ||
                 colSpec.resolution <= 0 ) {
                 const err = new Error(
-                    `WinkComposer/questdb: column '${colName}' has type 'float64' ` +
+                    `winkComposer/questdb: column '${colName}' has type 'float64' ` +
                     `but resolution is '${colSpec.resolution}'; ` +
                     'expected positive finite number (or omit for passthrough)'
                 );

package/src/core/storage-manager/questdb/ensure-tables.js

@@ -162,7 +162,7 @@ const ensureTables = async function ( pgClient, assetClass, tablePrefix, options
                 // originates from QuestDB's PG-wire DDL response, not from
                 // our pre-validation of caller-supplied config.
                 const wrapped = new Error(
-                    `Failed to create table '${tableName}': ${err.message}`
+                    `winkComposer/questdb: Failed to create table '${tableName}': ${err.message}`
                 );
                 wrapped.code = 'SCHEMA_ERROR';
                 throw wrapped;

package/src/core/storage-manager/questdb/index.js

@@ -110,6 +110,16 @@
  *   `{ timeout }` (a send against an unreachable server never settles —
  *   see the mid-row recovery section below).
  *
+ * Runtime console classification:
+ * - `CALLBACK_FAILED`  — the user's `onDeliveryFailure` itself threw or
+ *   rejected. The shared callback guard contains the fault (ADR-018).
+ *   The adapter keeps writing and flushing, and each fault becomes one
+ *   classified console line carrying the detail. `onWarning` is
+ *   deliberately NOT guarded. A throwing `onWarning` is strict mode:
+ *   the throw is the instruction that rejects the row. Wrapping it
+ *   would erase that contract (the ADR-027 exclusion, pinned by the
+ *   strict-mode specs).
+ *
  * Column-internal facts consumed (the ADR-018 column-internal facts
  * pattern):
  *
@@ -197,7 +207,9 @@ import { Sender } from '@questdb/nodejs-client';
 import pg from 'pg';
 
 import { ENV_VARS } from '../../env-vars.js';
+import { logger } from '../../logger/index.js';
 import { validators } from '../../utils/validate/index.js';
+import { wrapCallback } from '../../utils/callback-guard/index.js';
 import { buildPersistPlans } from './persist-plan.js';
 import { ensureTables } from './ensure-tables.js';
 import { assertColumnFacts } from './assert-columns.js';
@@ -214,6 +226,17 @@ import { assertColumnFacts } from './assert-columns.js';
  */
 const RESULT_OK = { ok: true };
 
+/**
+ * Console channel for the callback guard: one classified line in this
+ * adapter's family. Receives an already-safe detail string, never the
+ * raw thrown value.
+ */
+const reportCallbackFault = function ( severity, name, detail ) {
+    logger.error(
+        `winkComposer/questdb: user callback ${name} failed [CALLBACK_FAILED]: ${detail}`
+    );
+}; // reportCallbackFault()
+
 // Error results (INVALID_INSIGHT_TYPE, SEND_FAILED) are constructed per-call
 // because each carries dynamic content (the offending insightType name and the
 // underlying err.message respectively). These paths are rare; per-occurrence
@@ -401,12 +424,12 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
     // Runtime validation — required from either DSL config or ENV_VARS.
     // Per ADR-018, setup-time throws carry classified err.code.
     if ( !ilpUrl ) {
-        const err = new Error( 'WinkComposer/questdb: ilpUrl required — set in .storage() config or QUESTDB_ILP_URL env var' );
+        const err = new Error( 'winkComposer/questdb: ilpUrl required — set in .storage() config or QUESTDB_ILP_URL env var' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
     if ( !pgUrl ) {
-        const err = new Error( 'WinkComposer/questdb: pgUrl required — set in .storage() config or QUESTDB_PG_URL env var' );
+        const err = new Error( 'winkComposer/questdb: pgUrl required — set in .storage() config or QUESTDB_PG_URL env var' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
@@ -417,9 +440,24 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
         PgClientClass = pg.Client
     } = deps;
 
-    // Build persist plans (pre-compiled closures)
+    // Build persist plans (pre-compiled closures). The callbacks go in
+    // RAW: buildPersistPlans validates them itself and arms its own
+    // guarded copy for the at-flush site. Handing it a pre-wrapped
+    // function would defeat that validation (the guard turns a
+    // non-function into null instead of the fail-fast INVALID_CONFIG).
     const persistPlans = buildPersistPlans( assetClass, tablePrefix, { onWarning, onDeliveryFailure } );
 
+    // Arm the delivery-failure callback for this module's own report
+    // sites: the idle-flush timer and the mid-row recovery flush. Both
+    // fire inside promise chains, where a broken handler used to become
+    // an unhandled rejection. The guard classifies the fault instead
+    // (ADR-018) and its cost stays inside the handler. Absent stays
+    // null, so the no-handler console/throw fallbacks keep their
+    // meaning.
+    const safeOnDeliveryFailure = wrapCallback( onDeliveryFailure, {
+        name: 'onDeliveryFailure', severity: 'red', report: reportCallbackFault
+    } );
+
     // Ensure tables exist via PostgreSQL wire protocol
     const [ pgHost, pgPort ] = pgUrl.split( ':' );
     const pgClient = new PgClientClass( {
@@ -445,7 +483,7 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
         await pgClient.connect();
     } catch ( connErr ) {
         const err = new Error(
-            `WinkComposer/questdb: could not connect to PostgreSQL at ${pgUrl} — ${connErr.message}`
+            `winkComposer/questdb: could not connect to PostgreSQL at ${pgUrl} — ${connErr.message}`
         );
         err.code = NETWORK_ERROR_CODES.has( connErr.code ) ?
             'TRANSPORT_UNREACHABLE' :
@@ -570,11 +608,11 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
                 // (the settle handler already cleared them from
                 // pressure). Same routing policy as the recovery flush:
                 // the caller owns the response when it asked to.
-                if ( onDeliveryFailure ) {
-                    onDeliveryFailure( err, { idleFlush: true, rowsLost: rows } );
+                if ( safeOnDeliveryFailure ) {
+                    safeOnDeliveryFailure( err, { idleFlush: true, rowsLost: rows } );
                 } else {
-                    console.error(
-                        `WinkComposer/questdb: idle flush failed; ${rows} buffered row(s) lost: ${err.message}`
+                    logger.error(
+                        `winkComposer/questdb: idle flush failed; ${rows} buffered row(s) lost: ${err.message}`
                     );
                 }
             } finally {
@@ -629,12 +667,12 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
             bufferedRows = 0;
 
             entry.promise.catch( ( flushErr ) => {
-                if ( onDeliveryFailure ) {
-                    onDeliveryFailure( flushErr, { recovery: true } );
+                if ( safeOnDeliveryFailure ) {
+                    safeOnDeliveryFailure( flushErr, { recovery: true } );
                     return;
                 }
                 const failure = new Error(
-                    `WinkComposer/questdb: recovery flush failed after a mid-row write error: ${flushErr.message}. ` +
+                    `winkComposer/questdb: recovery flush failed after a mid-row write error: ${flushErr.message}. ` +
                     'Completed rows in that batch were dropped. Provide an `onDeliveryFailure` callback ' +
                     'in the storage config to handle these explicitly.'
                 );
@@ -649,7 +687,7 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
             // write() must still return its classified result rather than
             // throw (ADR-018: the hot path never throws), and the
             // failure must be visible.
-            console.error( `WinkComposer/questdb: sender recovery failed: ${recoveryErr.message}` );
+            logger.error( `winkComposer/questdb: sender recovery failed: ${recoveryErr.message}` );
         }
     }; // recoverSender()
 
@@ -682,7 +720,7 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
                 ok: false,
                 error: {
                     code: 'SHUTTING_DOWN',
-                    message: 'WinkComposer/questdb: write rejected — storage is shutting down'
+                    message: 'winkComposer/questdb: write rejected — storage is shutting down'
                 }
             };
         }
@@ -842,7 +880,7 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
      */
     const closeQuietly = function () {
         return sender.close().catch( function ( closeErr ) {
-            console.error( `WinkComposer/questdb: transport close failed during lossy shutdown: ${closeErr.message}` );
+            logger.error( `winkComposer/questdb: transport close failed during lossy shutdown: ${closeErr.message}` );
         } );
     }; // closeQuietly()
 
@@ -934,7 +972,7 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
                 await closeQuietly();
                 const dropped = totalRows - deliveredRows;
                 const timedOut = new Error(
-                    `WinkComposer/questdb: ${err.message}; ${dropped} buffered row(s) dropped`
+                    `winkComposer/questdb: ${err.message}; ${dropped} buffered row(s) dropped`
                 );
                 timedOut.code = 'SHUTDOWN_TIMEOUT';
                 timedOut.dropped = { count: dropped };
@@ -944,7 +982,7 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
             if ( failedRows > 0 ) {
                 await closeQuietly();
                 const failure = new Error(
-                    `WinkComposer/questdb: flush failed during shutdown: ${firstFailure.message}; ${failedRows} buffered row(s) dropped`
+                    `winkComposer/questdb: flush failed during shutdown: ${firstFailure.message}; ${failedRows} buffered row(s) dropped`
                 );
                 failure.code = 'DELIVERY_FAILED';
                 failure.dropped = { count: failedRows };
@@ -1183,7 +1221,7 @@ const createStorage = function ( config ) {
         // remediation differs — they need to add .assetClass() to the
         // flow definition, not edit env vars or storage config.
         const err = new Error(
-            'WinkComposer/questdb: assetClass is required - add .assetClass(assetClassDef) to flow before .storage()'
+            'winkComposer/questdb: assetClass is required - add .assetClass(assetClassDef) to flow before .storage()'
         );
         err.code = 'MISSING_ASSET_CLASS';
         throw err;

package/src/core/storage-manager/questdb/persist-plan.js

@@ -83,6 +83,19 @@
 import { SenderBufferV1 } from '@questdb/nodejs-client';
 
 import { QUEST_WRITERS, writeAsString, createFloat64Writer } from './writers.js';
+import { wrapCallback } from '../../utils/callback-guard/index.js';
+import { logger } from '../../logger/index.js';
+
+/**
+ * Console channel for the callback guard: one classified line in this
+ * adapter's family. Receives an already-safe detail string, never the
+ * raw thrown value.
+ */
+const reportCallbackFault = function ( severity, name, detail ) {
+    logger.error(
+        `winkComposer/questdb: user callback ${name} failed [CALLBACK_FAILED]: ${detail}`
+    );
+}; // reportCallbackFault()
 
 // ============================================================================
 // DEFAULT WARNING HANDLER
@@ -90,7 +103,7 @@ import { QUEST_WRITERS, writeAsString, createFloat64Writer } from './writers.js'
 
 /**
  * Default warning handler for invalid column values.
- * Logs to console in WinkComposer format.
+ * Logs to console in winkComposer format.
  *
  * Validation behavior:
  * - null/undefined columns: skip column only (QuestDB stores NULL)
@@ -108,7 +121,7 @@ import { QUEST_WRITERS, writeAsString, createFloat64Writer } from './writers.js'
  * @param {string} message - Warning message describing the issue
  */
 const defaultOnWarning = function ( message ) {
-    console.warn( `WinkComposer/questdb: ${message}` );
+    logger.warn( `winkComposer/questdb: ${message}` );
 };
 
 /**
@@ -213,7 +226,7 @@ const assertIlpNames = function ( tableName, columnNames ) {
         }
     } catch ( err ) {
         const wrapped = new Error(
-            `WinkComposer/questdb: invalid ILP ${kind} '${current}' — ${err.message}`
+            `winkComposer/questdb: invalid ILP ${kind} '${current}' — ${err.message}`
         );
         wrapped.code = 'INVALID_CONFIG';
         wrapped.cause = err;
@@ -264,18 +277,29 @@ const buildPersistPlans = function ( assetClass, tablePrefix, options ) {
 
     if ( providedOnWarning !== undefined && typeof providedOnWarning !== 'function' ) {
         // Per ADR-018, setup-time throws carry classified err.code.
-        const err = new Error( 'WinkComposer/questdb: onWarning must be a function' );
+        const err = new Error( 'winkComposer/questdb: onWarning must be a function' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
     if ( providedOnDeliveryFailure !== undefined && typeof providedOnDeliveryFailure !== 'function' ) {
-        const err = new Error( 'WinkComposer/questdb: onDeliveryFailure must be a function' );
+        const err = new Error( 'winkComposer/questdb: onDeliveryFailure must be a function' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
 
     const onWarning = providedOnWarning || defaultOnWarning;
-    const onDeliveryFailure = providedOnDeliveryFailure || null;
+    // onWarning stays raw on purpose. A strict-mode onWarning throws,
+    // and that throw is the instruction that rejects the row. ADR-027
+    // keeps such callbacks — ones whose throw or return the adapter
+    // acts on — out of the guard's scope. onDeliveryFailure only
+    // notifies, so the shared guard arms it. It was validated raw
+    // above and is wrapped once here (ADR-018: a broken handler costs
+    // its own output, never the flush chain). Absent stays null, so
+    // the no-handler DELIVERY_FAILED escape hatch below keeps its
+    // exact meaning.
+    const onDeliveryFailure = wrapCallback( providedOnDeliveryFailure || null, {
+        name: 'onDeliveryFailure', severity: 'red', report: reportCallbackFault
+    } );
     const plansByInsightType = Object.create( null );
     const insightTypes = assetClass.insightTypes || Object.create( null );
     const columns = assetClass.columns;
@@ -298,7 +322,7 @@ const buildPersistPlans = function ( assetClass, tablePrefix, options ) {
         // 'assetId' that no insightType persists stays legal.
         if ( persistedColumnNames.includes( 'assetId' ) || designatedTimestamp === 'assetId' ) {
             const err = new Error(
-                `WinkComposer/questdb: insightType '${insightTypeName}' uses reserved column name 'assetId' — ` +
+                `winkComposer/questdb: insightType '${insightTypeName}' uses reserved column name 'assetId' — ` +
                 'composer writes this column automatically from the flow\'s .assetId() field (the partition id); ' +
                 'rename the semantics column or remove it from this insightType'
             );
@@ -464,7 +488,7 @@ const buildPersistPlans = function ( assetClass, tablePrefix, options ) {
                         return;
                     }
                     const failure = new Error(
-                        `WinkComposer/questdb: silent data loss — sender.at() async flush failed for table '${tableName}': ${err.message}. ` +
+                        `winkComposer/questdb: silent data loss — sender.at() async flush failed for table '${tableName}': ${err.message}. ` +
                         'Rows in this batch were dropped. Per the no-silent-failures contract this is a hard failure. ' +
                         'Provide an `onDeliveryFailure` callback in the storage config to handle these explicitly.'
                     );

package/src/core/tunable/helpers.js

@@ -72,7 +72,7 @@ export const lookupByField = function ( field, map, defaultVal ) {
 export const pickByField = function ( map ) {
     const fn = () => {
         throw new Error(
-            'WinkComposer/flow: pickByField is resolved at build time inside forEach; ' +
+            'winkComposer/flow: pickByField is resolved at build time inside forEach; ' +
             'it has no runtime value. Use it only for a forEach option.'
         );
     };