@winkjs/composer 0.6.0 → 0.8.0

package/src/core/env-vars.js

@@ -4,6 +4,8 @@
 
 import os from 'os';
 
+import { classifyAddress, localhostRefusalDetail } from './utils/address/index.js';
+
 // ============================================================================
 // ENVIRONMENT VARIABLE DEFINITIONS
 // ============================================================================
@@ -63,7 +65,7 @@ const ENV_VARS = {
     // `processMessage` (file replays, testHarness, the headless driver):
     // for them the yield tick is the only planned chance for sink flush
     // timers and socket I/O to run. 500 ms is half the tightest background
-    // timer it must not starve (QUESTDB_IDLE_FLUSH_CHECK_MS, 1000).
+    // timer it must not starve (QUESTDB_FLUSH_INTERVAL_MS, default 1000).
     // Per-flow override: `.yield( { threshold } )`. Infinity = never yield.
     yieldTimeThresholdMs: rawYieldMs === '' ? NaN : Number( rawYieldMs ),
 
@@ -89,22 +91,45 @@ const ENV_VARS = {
     mqttSourceDedupWindowMs: parseInt( process.env.MQTT_SOURCE_DEDUP_WINDOW_MS ?? '120000', 10 ),
     mqttSourceDedupMaxEntries: parseInt( process.env.MQTT_SOURCE_DEDUP_MAX_ENTRIES ?? '65536', 10 ),
 
-    // QuestDB Configuration
-    questdbIlpUrl: ( process.env.QUESTDB_ILP_URL ?? 'localhost:9000' ).trim(),
-    questdbPgUrl: ( process.env.QUESTDB_PG_URL ?? 'localhost:8812' ).trim(),
-    questdbFlushMode: ( process.env.QUESTDB_FLUSH_MODE ?? 'auto' ).trim(),
-    questdbIdleFlushAfterMs: parseInt( process.env.QUESTDB_IDLE_FLUSH_AFTER_MS ?? '5000', 10 ),
-    questdbIdleFlushCheckMs: parseInt( process.env.QUESTDB_IDLE_FLUSH_CHECK_MS ?? '1000', 10 ),
+    // QuestDB Configuration. The address defaults are loopback literals,
+    // never the name `localhost` (ADR-030). A name can resolve to two
+    // addresses, `::1` and `127.0.0.1`, and QuestDB may listen on only
+    // one; the run-5 soak lost its write path for four hours that way.
+    // The `hostPort` and `mqttUrl` validators below refuse `localhost`
+    // outright, so a deployment that sets it stops here, at import.
+    questdbIlpUrl: ( process.env.QUESTDB_ILP_URL ?? '127.0.0.1:9000' ).trim(),
+    questdbPgUrl: ( process.env.QUESTDB_PG_URL ?? '127.0.0.1:8812' ).trim(),
     // Optional QuestDB settings (undefined if not set)
-    questdbAutoFlushRows: process.env.QUESTDB_AUTO_FLUSH_ROWS ?
-        parseInt( process.env.QUESTDB_AUTO_FLUSH_ROWS, 10 ) : undefined,
-    questdbAutoFlushIntervalMs: process.env.QUESTDB_AUTO_FLUSH_INTERVAL_MS ?
-        parseInt( process.env.QUESTDB_AUTO_FLUSH_INTERVAL_MS, 10 ) : undefined,
     questdbMaxBufSize: process.env.QUESTDB_MAX_BUF_SIZE ?
         parseInt( process.env.QUESTDB_MAX_BUF_SIZE, 10 ) : undefined,
     questdbRetryTimeout: process.env.QUESTDB_RETRY_TIMEOUT ?
         parseInt( process.env.QUESTDB_RETRY_TIMEOUT, 10 ) : undefined,
 
+    // QuestDB flush settings owned by composer (ADR-029). Each carries a
+    // value only when the operator set one. The adapter's option
+    // resolver supplies the defaults and derives the ceiling and the
+    // deadline from the values that won, so a fixed default here would
+    // fight a threshold raised in the flow's config.
+    questdbFlushRows: process.env.QUESTDB_FLUSH_ROWS ?
+        parseInt( process.env.QUESTDB_FLUSH_ROWS, 10 ) : undefined,
+    questdbFlushIntervalMs: process.env.QUESTDB_FLUSH_INTERVAL_MS ?
+        parseInt( process.env.QUESTDB_FLUSH_INTERVAL_MS, 10 ) : undefined,
+    questdbBufferCeilingRows: process.env.QUESTDB_BUFFER_CEILING_ROWS ?
+        parseInt( process.env.QUESTDB_BUFFER_CEILING_ROWS, 10 ) : undefined,
+    questdbFlushDeadlineMs: process.env.QUESTDB_FLUSH_DEADLINE_MS ?
+        parseInt( process.env.QUESTDB_FLUSH_DEADLINE_MS, 10 ) : undefined,
+
+    // QuestDB transport settings (ADR-029). QUESTDB_STDLIB_HTTP takes
+    // the client's own words for `stdlib_http`, `on` or `off`. The
+    // adapter's option resolver maps them to a boolean and supplies the
+    // default, so each field here carries a value only when set.
+    questdbStdlibHttp: process.env.QUESTDB_STDLIB_HTTP ?
+        process.env.QUESTDB_STDLIB_HTTP.trim() : undefined,
+    questdbRequestTimeout: process.env.QUESTDB_REQUEST_TIMEOUT ?
+        parseInt( process.env.QUESTDB_REQUEST_TIMEOUT, 10 ) : undefined,
+    questdbInitBufSize: process.env.QUESTDB_INIT_BUF_SIZE ?
+        parseInt( process.env.QUESTDB_INIT_BUF_SIZE, 10 ) : undefined,
+
     // QuestDB Credentials
     questdbDatabase: ( process.env.QUESTDB_DATABASE ?? 'qdb' ).trim(),
     questdbUser: ( process.env.QUESTDB_USER ?? 'admin' ).trim(),
@@ -161,20 +186,27 @@ const validators = {
         return null;
     },
 
+    // host:port, with the port required. Accepts a name, an IPv4
+    // literal, or a bracketed IPv6 literal (`[::1]:8812`). Refuses
+    // `localhost` in every spelling (ADR-030); the shared helper is the
+    // one check the adapter schema and factory layers use too.
     hostPort: function ( value ) {
         if ( !value ) return 'Cannot be empty';
-        // Match host:port pattern (host can be hostname or IP)
-        const hostPortRegex = /^[\w.\-]+:\d+$/;
-        if ( !hostPortRegex.test( value ) ) {
+        const address = classifyAddress( value, 'hostPort' );
+        if ( ( address.kind === 'unparsed' ) || ( address.port === undefined ) ) {
             return `Must be host:port format, got: "${value}"`;
         }
+        if ( address.kind === 'localhost' ) {
+            return localhostRefusalDetail( address );
+        }
         return null;
     },
 
-    questdbFlushMode: function ( value ) {
-        const validModes = [ 'auto', 'manual' ];
-        if ( !validModes.includes( value ) ) {
-            return `Must be one of ${validModes.join( ', ' )}, got: "${value}"`;
+    questdbStdlibHttp: function ( value ) {
+        if ( value === undefined ) return null;
+        const validWords = [ 'on', 'off' ];
+        if ( !validWords.includes( value ) ) {
+            return `Must be one of ${validWords.join( ', ' )}, got: "${value}"`;
         }
         return null;
     },
@@ -208,11 +240,18 @@ const validators = {
         return null;
     },
 
+    // A broker URL. The scheme check comes first; then `localhost` is
+    // refused (ADR-030). A URL the parser cannot read is left to the
+    // MQTT library, which reports its own error.
     mqttUrl: function ( value ) {
         if ( !value ) return 'Cannot be empty';
         if ( !value.startsWith( 'mqtt://' ) && !value.startsWith( 'mqtts://' ) ) {
             return `Must start with 'mqtt://' or 'mqtts://', got: "${value}"`;
         }
+        const address = classifyAddress( value, 'url' );
+        if ( address.kind === 'localhost' ) {
+            return localhostRefusalDetail( address );
+        }
         return null;
     }
 };
@@ -241,30 +280,59 @@ const validationConfig = [
     // QuestDB Configuration
     { field: 'questdbIlpUrl', validator: validators.hostPort, label: 'QUESTDB_ILP_URL' },
     { field: 'questdbPgUrl', validator: validators.hostPort, label: 'QUESTDB_PG_URL' },
-    { field: 'questdbFlushMode', validator: validators.questdbFlushMode, label: 'QUESTDB_FLUSH_MODE' },
-    { field: 'questdbIdleFlushAfterMs', validator: validators.nonNegativeInt, originalEnv: 'QUESTDB_IDLE_FLUSH_AFTER_MS' },
-    { field: 'questdbIdleFlushCheckMs', validator: validators.positiveInt, originalEnv: 'QUESTDB_IDLE_FLUSH_CHECK_MS' },
-    { field: 'questdbAutoFlushRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_AUTO_FLUSH_ROWS' },
-    { field: 'questdbAutoFlushIntervalMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_AUTO_FLUSH_INTERVAL_MS' },
     { field: 'questdbMaxBufSize', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_MAX_BUF_SIZE' },
     { field: 'questdbRetryTimeout', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_RETRY_TIMEOUT' },
+    { field: 'questdbFlushRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_FLUSH_ROWS' },
+    { field: 'questdbFlushIntervalMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_FLUSH_INTERVAL_MS' },
+    { field: 'questdbBufferCeilingRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_BUFFER_CEILING_ROWS' },
+    { field: 'questdbFlushDeadlineMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_FLUSH_DEADLINE_MS' },
+    { field: 'questdbStdlibHttp', validator: validators.questdbStdlibHttp, label: 'QUESTDB_STDLIB_HTTP' },
+    { field: 'questdbRequestTimeout', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_REQUEST_TIMEOUT' },
+    { field: 'questdbInitBufSize', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_INIT_BUF_SIZE' },
     // QuestDB Credentials
     { field: 'questdbDatabase', validator: validators.nonEmptyString, label: 'QUESTDB_DATABASE' },
     { field: 'questdbUser', validator: validators.nonEmptyString, label: 'QUESTDB_USER' }
     // questdbPassword: no validation — allows empty for passwordless auth
 ];
 
+// The five QuestDB flush variables 0.7.0 deprecated and 0.8.0 removed
+// (ADR-029 item 10). A deployment that still sets one stops here, at
+// import, and the failure line names what to do instead. Ignoring the
+// variable would let an operator believe a setting took effect.
+const REMOVED_ENV_VARS = [
+    { name: 'QUESTDB_FLUSH_MODE', action: 'delete it, composer owns every flush' },
+    { name: 'QUESTDB_IDLE_FLUSH_AFTER_MS', action: 'delete it, composer owns every flush' },
+    { name: 'QUESTDB_IDLE_FLUSH_CHECK_MS', action: 'use QUESTDB_FLUSH_INTERVAL_MS' },
+    { name: 'QUESTDB_AUTO_FLUSH_ROWS', action: 'use QUESTDB_FLUSH_ROWS' },
+    { name: 'QUESTDB_AUTO_FLUSH_INTERVAL_MS', action: 'delete it, composer owns every flush' }
+];
+
 // ============================================================================
 // VALIDATION RUNNER
 // ============================================================================
 const validate = function () {
     const errors = [];
 
+    // A removed variable is refused by name, even when empty, so a
+    // leftover line in an env file is found.
+    for ( const removed of REMOVED_ENV_VARS ) {
+        if ( process.env[ removed.name ] !== undefined ) {
+            errors.push( `${removed.name}: Removed in 0.8.0; ${removed.action}` );
+        }
+    }
+
     // Run each validator
     for ( const config of validationConfig ) {
         const value = ENV_VARS[ config.field ];
         const originalEnv = config.originalEnv ? process.env[ config.originalEnv ] : value;
-        const label = config.label || config.field.toUpperCase().replace( /([a-z])([A-Z])/g, '$1_$2' );
+        // The label is the variable name as the operator typed it. A row
+        // that records the variable uses it; otherwise the name is
+        // derived from the field, inserting the underscores BEFORE
+        // uppercasing (the other order finds no boundaries and printed
+        // QUESTDBRETRYTIMEOUT until 2026-09-05).
+        const label = config.label ||
+            config.originalEnv ||
+            config.field.replace( /([a-z])([A-Z])/g, '$1_$2' ).toUpperCase();
 
         const error = config.validator( value, originalEnv || value, label );
         if ( error ) {

package/src/core/logger/index.js

@@ -87,7 +87,7 @@ const silentTransport = {
 };
 
 // The env-selectable transports. The mqtt transport joins this map
-// when ADR-029 lands.
+// when ADR-031 lands.
 const transports = {
     console: consoleTransport,
     json: jsonTransport,

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

@@ -33,7 +33,11 @@
  * `err.code` vocabulary (per-adapter, documented here per ADR-018):
  * - `INVALID_CONFIG`         — setup-time; missing or malformed config
  *   field. Thrown synchronously from the factory (ADR-018 fail-fast
- *   setup), never emitted.
+ *   setup), never emitted. Includes a `brokerUrl` whose host is
+ *   `localhost` (ADR-030): the name can resolve to two addresses and
+ *   the broker may listen on only one. The message names the literal
+ *   to set. Refused before the client is created, at the schema (flow
+ *   definition) and here (direct callers).
  * - `DECODE_ERROR`           — runtime, yellow. Two faces: a per-record
  *   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
@@ -69,6 +73,15 @@
  * - `QUIET_PERIOD_EXCEEDED`  — runtime, yellow, opt-in. No packet for
  *   longer than the configured `expectedQuietPeriodMs`.
  *
+ * Console classification (a token on a log line, not an `err.code`):
+ * - `ADDRESS_IS_NAME`        — the `brokerUrl` host is a name other
+ *   than `localhost`. One `logger.warn` line at setup, before the
+ *   client is created (ADR-030). A name is allowed and the source
+ *   proceeds; the line tells the operator that only a literal address
+ *   is immune to a resolver that changes its answer under a running
+ *   process. This source refuses and warns; it does not probe, because
+ *   its posture is recovering (ADR-018 §5).
+ *
  * Metrics (optional `onMetrics`, ~1 Hz + on transitions): monotonic
  * counters `{delivered, skipped, decodeErrors, reconnects, dedupHits,
  * dedupMisses, dedupBypassed, dedupCacheSize}`. `dedupBypassed` counts
@@ -107,15 +120,34 @@
  *      clears. The operator tells them apart, not the code.
  *   4. Safe to kill and re-create: no disk state, no side effects.
  *      The cost of a crash is the dedup cache (see dedup.js).
+ *   5. No payload size cap and no intake rate cap. A flood of large
+ *      messages is bounded only by the broker's own per-client limits
+ *      and by TCP back-pressure on the socket. ADR-026 (proposed) is
+ *      the home for a cap; the handbook states the limit.
+ *
+ * Performance, measured on the private benchmark harness (2026-04-24,
+ * M4 Max; pre-ADR-022 dedup, whose replacement has the same O(1)
+ * per-message profile): composer's own decode/dedup/dispatch path
+ * sustains 897 k msg/s at 100 B payloads (317 k at 1 KB). End-to-end
+ * through Mosquitto at QoS 1 the single-process ceiling was
+ * ~12.9 k msg/s, owned by mqtt.js and the broker round-trip, not this
+ * code. At 10 k msg/s steady state every cell ran clean; a
+ * 30 M-message run showed no subscriber-side leak.
  *
- * Performance (benchmark/mqtt-source/BASELINE.md, 2026-04-24, M4 Max;
- * pre-ADR-022 dedup, whose replacement has the same O(1) per-message
- * profile): composer's own decode/dedup/dispatch path sustains
- * 897 k msg/s at 100 B payloads (317 k at 1 KB); end-to-end through
- * Mosquitto at QoS 1 the single-process ceiling was ~12.9 k msg/s —
- * owned by mqtt.js and the broker round-trip, not this code. At
- * 10 k msg/s steady state every cell ran clean; a 30 M-message run
- * showed no subscriber-side leak.
+ * Decisions this file follows:
+ * - ADR-004 and ADR-013 — the message handler is synchronous and
+ *   allocates nothing on the success path. The flow's dispatch never
+ *   waits on it.
+ * - ADR-018 — the adapter contract: phases, status shape, codes.
+ * - ADR-022 — the dedup cache and its two bounds.
+ * - ADR-027 — the callback wrapper scope. `transform` runs under the
+ *   shared guard. `onMessage` is not wrapped here; the flow's dispatch
+ *   guard owns it.
+ * - ADR-028 — the grammar of every facade line printed here and in
+ *   status.js.
+ * - ADR-030 — `localhost` is refused; a name is warned about.
+ * - ADR-026 (proposed) — the external-threat surface. TLS,
+ *   authentication, and payload caps belong there, not here.
  *
  * @see src/core/source-manager/mqtt/status.js - The reporting rules
  * @see src/core/emitter-manager/mqtt/emitter.js - Emitter counterpart
@@ -135,7 +167,48 @@ 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 { jitteredPeriod } from '../../utils/jitter/index.js';
 import { logger } from '../../logger/index.js';
+import { classifyAddress, localhostRefusalMessage, nameWarningMessage } from '../../utils/address/index.js';
+
+// ============================================================================
+// ADDRESS POLICY (ADR-030)
+// ============================================================================
+
+/**
+ * Classifies the broker address and refuses `localhost`. The schema
+ * already refused it at flow definition; this call covers direct
+ * callers and carries the classified code. The source has no
+ * environment fallback for `brokerUrl`, so no env var is named.
+ *
+ * @param {string} brokerUrl - The broker URL as configured
+ * @returns {Object} The classified address
+ * @throws {Error} INVALID_CONFIG when the host is `localhost`
+ */
+const assertBrokerNotLocalhost = function ( brokerUrl ) {
+    const address = classifyAddress( brokerUrl, 'url' );
+    if ( address.kind === 'localhost' ) {
+        const err = new Error(
+            `winkComposer/mqttSource: ${localhostRefusalMessage( { field: 'brokerUrl', address } )}`
+        );
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+    return address;
+}; // assertBrokerNotLocalhost()
+
+/**
+ * Prints the one ADDRESS_IS_NAME line when the broker host is a name.
+ *
+ * @param {Object} address - The classified broker address
+ */
+const warnIfBrokerIsName = function ( address ) {
+    if ( address.kind === 'name' ) {
+        logger.warn(
+            `winkComposer/mqttSource: ${nameWarningMessage( { field: 'brokerUrl', host: address.host } )}`
+        );
+    }
+}; // warnIfBrokerIsName()
 
 // ============================================================================
 // CLIENT FACTORY
@@ -146,7 +219,7 @@ import { logger } from '../../logger/index.js';
  * health/metrics reporting.
  *
  * @param {Object} config - Client configuration
- * @param {string} config.brokerUrl - MQTT broker URL (e.g., 'mqtt://localhost:1883')
+ * @param {string} config.brokerUrl - MQTT broker URL (e.g., 'mqtt://127.0.0.1:1883'; never localhost)
  * @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)
@@ -192,6 +265,9 @@ const createMQTTSourceClient = function ( config ) {
         err.code = 'INVALID_CONFIG';
         throw err;
     }
+    // Address policy (ADR-030): `localhost` is refused before the
+    // client is created; a name is warned about just before connect.
+    const brokerAddress = assertBrokerNotLocalhost( brokerUrl );
     if ( !topics || ( Array.isArray( topics ) && topics.length === 0 ) ) {
         const err = new Error( 'winkComposer/mqttSource: topics is required' );
         err.code = 'INVALID_CONFIG';
@@ -232,15 +308,20 @@ const createMQTTSourceClient = function ( config ) {
     };
     const guardedTransform = transform ? wrapTransform( transform, reportTransformFault ) : null;
 
-    // Generate client ID if not provided
-    const generatedClientId = clientId || `wink-source-${Date.now()}`;
+    // The auto-generated name carries the start time and a random
+    // part, the emitter's shape. Two sources that start in the same
+    // millisecond still get different names. That matters because the
+    // broker allows one live connection per name. When a second client
+    // arrives under a name in use, the broker disconnects the first.
+    // Two clients then take the session from each other on every
+    // reconnect.
+    const generatedClientId = clientId || `wink-source-${Date.now()}-${Math.random().toString( 36 ).slice( 2, 9 )}`;
 
     // A persistent session is filed at the broker under the client's
     // name. The auto-generated name changes on every start, so the
-    // backlog the broker saved under the previous run's name is never
-    // delivered — it waits, unclaimed, until the session expires.
-    // Warn once at startup; the fix is one config line. Setup path
-    // only — nothing here touches the message path.
+    // backlog saved under the previous run's name is never delivered.
+    // Warn once at startup. The fix is one config line, on the setup
+    // path only.
     if ( !clientId && cleanStart !== true ) {
         logger.warn(
             'winkComposer/mqttSource: no clientId configured — this session ' +
@@ -251,10 +332,14 @@ const createMQTTSourceClient = function ( config ) {
         );
     }
 
-    // Build MQTT options, allowing cleanStart override
+    // Build MQTT options, allowing cleanStart override. The reconnect
+    // period is the configured one plus a random share of up to 20%,
+    // drawn once here. So a fleet that lost one broker does not retry
+    // in step. The configured period is the floor.
     const mqttOptions = {
         ...MQTT_SOURCE_CONFIG,
-        clientId: generatedClientId
+        clientId: generatedClientId,
+        reconnectPeriod: jitteredPeriod( MQTT_SOURCE_CONFIG.reconnectPeriod )
     };
 
     // Map the user-facing `cleanStart` key (MQTT 5 term) onto the
@@ -264,7 +349,9 @@ const createMQTTSourceClient = function ( config ) {
         mqttOptions.clean = cleanStart;
     }
 
-    // Create MQTT client
+    // Create MQTT client. The name warning goes first, so it prints
+    // before any socket opens (ADR-030).
+    warnIfBrokerIsName( brokerAddress );
     const client = mqttConnectFn( brokerUrl, mqttOptions );
 
     // One heartbeat per second: re-evaluates the time-based health
@@ -303,7 +390,10 @@ const createMQTTSourceClient = function ( config ) {
         const dedupId = userProps ? userProps[ WINK_NAMESPACE.dedupId ] : undefined;
 
         // Dedup is opt-in by construction (ADR-022): no id → bypass.
-        if ( dedupId === null || dedupId === undefined ) {
+        // A repeated MQTT 5 user property parses to an array, and an
+        // array can never equal an earlier one. So any non-string id
+        // bypasses too, counted in dedupBypassed rather than cached.
+        if ( typeof dedupId !== 'string' ) {
             reporter.bypassed();
         } else if ( dedup.isDuplicate( dedupId ) ) {
             reporter.dupSkipped();
@@ -312,16 +402,17 @@ const createMQTTSourceClient = function ( config ) {
             reporter.idAccepted();
         }
 
-        // 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. 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.
+        // Decode the payload, check its shape, and attach metadata in
+        // one guarded region. A failure anywhere in it is skipped,
+        // classified, and reported per record (ADR-018). The stream
+        // 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. 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' ) {
@@ -341,7 +432,15 @@ const createMQTTSourceClient = function ( config ) {
 
             reporter.decodeOk();
         } catch ( err ) {
-            reporter.decodeFailed( `topic '${topic}': ${err.message} — message skipped` );
+            // The parser's own message can echo a fragment of the
+            // payload. Payload text is data, so it stays below the
+            // warn level (ADR-028). The report names the topic and
+            // the size. The parser's reason goes to a debug line,
+            // guarded so the hot path builds nothing when debug is off.
+            reporter.decodeFailed( `topic '${topic}': payload of ${payload.length} bytes could not be decoded — message skipped` );
+            if ( logger.debugOn ) {
+                logger.debug( `winkComposer/mqttSource: decode failed [DECODE_ERROR]: topic '${topic}': ${err.message}` );
+            }
             return;
         }
 
@@ -349,12 +448,13 @@ const createMQTTSourceClient = function ( config ) {
         // 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.
+        // (transform contract, 2026-07-11).
+        //
+        // The return is held to the same record shape as the payload.
+        // A null or 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. The plain path pays nothing.
         let finalMessage;
         if ( guardedTransform ) {
             finalMessage = guardedTransform( message, topic );
@@ -398,51 +498,85 @@ const createMQTTSourceClient = function ( config ) {
     // STOP FUNCTION
     // ========================================================================
 
+    // The stop outcome is latched on the first call. A second caller
+    // receives the same promise, so it can never report a clean stop
+    // while the first call is still closing.
+    let stopPromise = null;
+
     /**
      * Stop the MQTT client, with a time budget.
      *
-     * Per ADR-018, source stop functions take a `{ timeout }`. We
-     * first ask the broker for a clean disconnect (`client.end(false)`),
-     * which waits for any messages still being sent. If that does not
-     * finish within `timeout` ms, we ask for a forced disconnect
-     * (`client.end(true)`), which closes the socket right away — so the
-     * rest of the shutdown can proceed even if the broker is slow or
-     * unreachable. The forced path is reported with the sources' shared
-     * `note` convention.
+     * Per ADR-018, source stop functions take a `{ timeout }`. How the
+     * close detaches follows the library's own rules (mqtt.js 5.15.1):
      *
-     * The timer is `unref()`ed so it does not keep Node alive while a
-     * clean disconnect is in progress.
+     * - Not connected (the first connect still pending, the link down,
+     *   or the library waiting to retry): `end( true )` at once. The
+     *   library destroys the stream, clears its connect and reconnect
+     *   timers, and calls back on the next tick. A graceful
+     *   `end( false )` would call back at once here too, but it would
+     *   not destroy the stream (`client.js:921-924`). A pending
+     *   connect would then hold the process for the whole connect
+     *   timeout.
+     * - Connected: `end( false )` sends DISCONNECT and half-closes the
+     *   socket, then waits for the broker to close its side. A timer
+     *   bounds that wait. At the budget the timer destroys the stream
+     *   directly. That is the call the library's own connect timeout
+     *   makes. A second `end()` would do nothing: it returns at once
+     *   behind the library's `disconnecting` flag (`client.js:731-734`).
+     *   The forced path is reported with the sources' shared `note`
+     *   convention.
      *
-     * Default time budget (5000 ms) matches what sinks use.
+     * The timer is `unref()`ed so it does not keep Node alive while a
+     * clean disconnect is in progress. Either path settles the promise
+     * once. The default time budget (5000 ms) matches the sinks.
      *
      * @param {Object} [options] - Stop options
-     * @param {number} [options.timeout=5000] - Max ms to wait for clean disconnect
+     * @param {number} [options.timeout=5000] - Max ms to wait for the clean disconnect
      * @returns {Promise<void>} Resolves once the client is closed (clean or forced)
      */
     const stop = function ( { timeout = 5000 } = {} ) {
+        if ( stopPromise ) {
+            return stopPromise;
+        }
         clearInterval( cadence );
-        return new Promise( function ( resolve ) {
+        stopPromise = new Promise( function ( resolve ) {
             let settled = false;
-            let forceTimer = null;
-            const onClosed = function () {
-                if ( settled ) return;
-                settled = true;
-                if ( forceTimer ) clearTimeout( forceTimer );
+            const reportClean = function () {
                 reporter.stopped();
+            };
+            const reportForced = function () {
+                reporter.stopForced( timeout );
+            };
+            // The library's close callback also fires after the timer's
+            // destroy, so the second arrival must settle nothing.
+            const settle = function ( report ) {
+                if ( settled ) {
+                    return;
+                }
+                settled = true;
+                report();
                 resolve();
             };
-            forceTimer = setTimeout( function () {
 
-                /* c8 ignore next -- defensive: settle always clears this timer (it is assigned before client.end can call back), so reaching here settled requires the timer callback to already sit in the event queue when settle runs — a race with no producer in the current design. Same guard shape as the testHarness stop. */
-                if ( settled ) return;
-                reporter.stopForced( timeout );
-                client.end( true, {}, onClosed );
+            if ( !client.connected ) {
+                client.end( true, {}, function () {
+                    settle( reportClean );
+                } );
+                return;
+            }
+
+            const forceTimer = setTimeout( function () {
+                client.stream.destroy();
+                settle( reportForced );
             }, timeout );
-            // Don't keep Node alive on the timer while the broker is
-            // closing cleanly. Either path resolves the Promise.
             forceTimer.unref();
-            client.end( false, {}, onClosed );
+
+            client.end( false, {}, function () {
+                clearTimeout( forceTimer );
+                settle( reportClean );
+            } );
         } );
+        return stopPromise;
     };
 
     // Expose for testing