@winkjs/composer 0.6.0 → 0.7.0

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

@@ -28,8 +28,8 @@
  * - Two unavoidable residuals, both bounded: (1) `Set.add`/`Set.delete`
  *   maintain V8's internal hash table — amortized O(1), memory bounded
  *   by `maxEntries`, and the identical profile the pre-ADR-022 cache
- *   already had (JS offers no pre-sized Set). (2) `Date.now()` exceeds
- *   the small-integer range, so the timestamp is transiently boxed; it
+ *   already had (JS offers no pre-sized Set). (2) The clock returns a
+ *   fractional number, so the timestamp is transiently boxed; it
  *   unboxes on store into the Float64Array and dies in the nursery.
  * - Eviction clears the ring slot so an evicted id string is not
  *   retained past its window — that release is deliberate.
@@ -48,9 +48,12 @@
  *   -----------
  *   1. A dedup id is unique per message and repeats only on a QoS-1
  *      retransmission (the emitter stamps UUIDs).
- *   2. The clock moves forward at millisecond granularity. A backward
- *      clock jump can expire entries early or hold them one window too
- *      long — bounded either way, and self-healing within one window.
+ *   2. The clock counts up, in milliseconds. The default is the
+ *      stopwatch clock (`performance`), which a wall-clock step cannot
+ *      move. A forward step of the wall clock would otherwise expire
+ *      every entry at once; a backward step would hold entries one
+ *      step too long (ADR-018, long-running stability). An injected
+ *      `nowFn` must count up too.
  *
  *   LIMITATIONS
  *   -----------
@@ -62,9 +65,9 @@
  *      effective window is maxEntries ÷ rate (the full 120 s up to
  *      about 550 msg/s at defaults; ~6.5 s at 10 k msg/s). Stated in
  *      ADR-022, not hidden.
- *   3. Memory, measured (benchmark/mqtt-source/dedup-memory.js,
- *      2026-07-09): 86 bytes per production-shaped id, ~6.7 MB worst
- *      case at the 65,536 cap including bounded V8 Set slack.
+ *   3. Memory, measured on the private benchmark harness (2026-07-09):
+ *      86 bytes per production-shaped id, ~6.7 MB worst case at the
+ *      65,536 cap including bounded V8 Set slack.
  *
  * @see ADR-022 - The full decision
  */
@@ -73,6 +76,7 @@ import {
     DEFAULT_DEDUP_WINDOW_MS,
     DEFAULT_DEDUP_MAX_ENTRIES
 } from './constants.js';
+import { monotonicNow } from '../../utils/clock/index.js';
 
 // ============================================================================
 // VALIDATION HELPER
@@ -108,8 +112,9 @@ const assertPositiveInteger = function ( value, name ) {
  *   expires once its age reaches this many milliseconds
  * @param {number} [options.maxEntries=65536] - Count cap: the memory
  *   guarantee; the oldest entry is evicted when the ring is full
- * @param {function} [options.nowFn=Date.now] - Clock source. Injection
- *   point for deterministic tests; production uses the default
+ * @param {function} [options.nowFn=monotonicNow] - Clock source, in
+ *   milliseconds and counting up. Injection point for deterministic
+ *   tests; production uses the stopwatch clock
  * @returns {Object} Cache instance with isDuplicate, size, clear, has
  */
 const createDedupCache = function ( options = {} ) {
@@ -122,7 +127,7 @@ const createDedupCache = function ( options = {} ) {
     const {
         windowMs = DEFAULT_DEDUP_WINDOW_MS,
         maxEntries = DEFAULT_DEDUP_MAX_ENTRIES,
-        nowFn = Date.now
+        nowFn = monotonicNow
     } = options;
 
     assertPositiveInteger( windowMs, 'windowMs' );

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

@@ -31,7 +31,9 @@
  * of `configSchema` — the wiring layer adds them to the config at start
  * time, after DSL validation. A user-supplied `onMessage` would be
  * silently overwritten; the unknown-key rejection turns that mistake
- * into a fail-fast error instead.
+ * into a fail-fast error instead. `onMessage` is also outside the
+ * callback guard on purpose: the flow's dispatch guard owns it, so a
+ * pipeline throw is contained once, at that one chokepoint (ADR-027).
  *
  *   ASSUMPTIONS
  *   -----------
@@ -49,6 +51,10 @@
  *   2. Duplicate filtering is opt-in per message: only messages that
  *      carry `winkDedupId` are protected. Watch the `dedupBypassed`
  *      counter to spot publishers that are not stamping ids.
+ *   3. No payload size cap and no intake rate cap. The broker's own
+ *      per-client limits are the first line against a flood; TCP
+ *      back-pressure bounds the rest. A cap is ADR-026 work
+ *      (proposed), together with TLS and authentication.
  *
  * Usage in flow:
  *   import mqtt from './core/source-manager/mqtt/index.js';
@@ -65,8 +71,24 @@
  */
 
 import { validators } from '../../utils/validate/index.js';
+import { classifyAddress } from '../../utils/address/index.js';
 import { createMQTTSourceClient } from './client.js';
 
+/**
+ * Schema validator for `brokerUrl`: non-empty and never `localhost`
+ * (ADR-030). A value the URL grammar cannot read passes; the MQTT
+ * library reports its own error for it.
+ *
+ * @param {*} value - The configured value
+ * @returns {boolean} Whether the value is allowed
+ */
+const isAllowedBrokerUrl = function ( value ) {
+    if ( !validators.nonEmptyString( value ) ) {
+        return false;
+    }
+    return classifyAddress( value, 'url' ).kind !== 'localhost';
+}; // isAllowedBrokerUrl()
+
 // ============================================================================
 // SOURCE ADAPTER
 // ============================================================================
@@ -83,7 +105,9 @@ const id = 'mqtt';
  * Crash-survival class per ADR-018. For a source the value describes
  * the INPUT it can recover after a disconnect: the persistent broker
  * session holds subscribed QoS-1 messages across the gap and replays
- * them on reconnect.
+ * them on reconnect. The class is earned only under a fixed
+ * `clientId` and a broker with persistence on. The auto-generated name
+ * changes on every start, so a restart under it claims no backlog.
  *
  * @type {string}
  */
@@ -97,7 +121,9 @@ const durabilityClass = 'broker-queue';
  * @returns {boolean}
  */
 const isTopicOrTopicArray = function ( value ) {
-    if ( typeof value === 'string' && value.length > 0 ) return true;
+    if ( typeof value === 'string' && value.length > 0 ) {
+        return true;
+    }
     if ( Array.isArray( value ) && value.length > 0 ) {
         return value.every( ( t ) => typeof t === 'string' && t.length > 0 );
     }
@@ -163,8 +189,9 @@ const configSchema = {
     brokerUrl: {
         type: 'string',
         required: true,
-        validator: validators.nonEmptyString,
-        error: 'brokerUrl must be a non-empty string (e.g., mqtt://broker.local:1883)'
+        validator: isAllowedBrokerUrl,
+        error: 'brokerUrl must be a non-empty broker URL with a literal address or a name, never ' +
+            'localhost; e.g., mqtt://127.0.0.1:1883'
     },
     topics: {
         required: true,

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

@@ -29,6 +29,25 @@
  *   later failed on still counts here. Failure visibility belongs
  *   to the flow's MESSAGE_HANDLER_FAILED reports (ADR-018), not to
  *   this counter.
+ * - The logger facade (ADR-028) — one line per health edge, and a
+ *   bounded line per record fault. These lines print with or without
+ *   an `onStatus` handler. Inside a flow the runtime's own status
+ *   wrapper forwards only red payloads when the user gave no handler,
+ *   so a yellow edge that reached only the payload channel used to
+ *   vanish. The line is the guaranteed audience. The payload
+ *   additionally reaches a listening handler.
+ *
+ *     yellow edge    → warn   source degraded [CODE]: <detail>
+ *     red edge       → error  source error [CODE]: <detail>
+ *     back to green  → warn   source recovered [CODE]: cleared after N s
+ *     forced stop    → warn   source stopped: <note>
+ *
+ *   An edge is a change of status or code. A phase change inside the
+ *   same status and code prints nothing, so a retry storm cannot fill
+ *   the log. A clean stop prints nothing. The per-record lines
+ *   (`decode failed [DECODE_ERROR]`, `transform failed
+ *   [CALLBACK_FAILED]`) print the first two of an episode in full and
+ *   then one summary a minute, the emitter's attempt-line shape.
  *
  * Health rules (evaluated on events and on tick):
  * - RED    — a subscribe failure (connected but deaf — no retry
@@ -44,6 +63,12 @@
  * Precedence is the order above; the first rule that matches names
  * the code.
  *
+ * Clock: the default `nowFn` is the stopwatch clock (`performance`),
+ * which only counts up. The wall clock can step when NTP corrects a
+ * board after boot or after a long time without network. A forward
+ * step would fire the 30 s red early; a backward step would delay it
+ * (ADR-018, long-running stability). Tests inject their own clock.
+ *
  * Hot-path allocation profile (ADR-018 zero-alloc — allocation only where
  * unavoidable, each residual stated):
  * - Counter bumps, ring writes, and the health evaluation are plain
@@ -54,20 +79,18 @@
  *   metrics snapshots (1 Hz). Snapshots are fresh objects because a
  *   consumer may retain them; mutating a shared one under the
  *   caller's feet is a footgun we refuse.
- * - `nowFn()` (Date.now) runs once per received message to feed the
- *   quiet-period clock — the same transient boxing the dedup cache
- *   already documents.
- *
- * Callers without an `onStatus` handler still see error-path
- * payloads via a classified `console.error` line (the CSV source's
- * fallback pattern); lifecycle payloads stay quiet.
+ * - `nowFn()` runs once per received message to feed the quiet-period
+ *   clock. It returns a fractional number, so the value is transiently
+ *   boxed — the same profile the dedup cache documents.
+ * - The facade lines are built only on an edge or a record fault,
+ *   never on the success path.
  *
  *   ASSUMPTIONS
  *   -----------
  *   1. All reporter calls come from one event loop (mqtt.js event
  *      handlers plus one interval) — there is no locking.
- *   2. The clock (`nowFn`) moves forward; the time rules use plain
- *      subtraction.
+ *   2. An injected `nowFn` counts up, in milliseconds. The time rules
+ *      use plain subtraction.
  *
  *   LIMITATIONS
  *   -----------
@@ -79,9 +102,13 @@
  *   2. Counters are plain JS numbers: exact to 2^53. At one million
  *      messages per second that is ~285 years of uptime — not the
  *      binding constraint.
+ *   3. The per-record line bound paces on the stopwatch clock too
+ *      (the shared line-rate helper), so a wall-clock step moves
+ *      neither a summary nor what the health rules decide.
  *
  * @see src/core/source-manager/mqtt/client.js - The transport wiring
  * @see ADR-018 - lifecycle phases, status shapes, error codes
+ * @see ADR-028 - the line grammar
  */
 
 import {
@@ -89,8 +116,16 @@ import {
     DECODE_RING_SIZE
 } from './constants.js';
 import { wrapCallback } from '../../utils/callback-guard/index.js';
+import { createLineBound } from '../../utils/line-rate/index.js';
+import { monotonicNow } from '../../utils/clock/index.js';
 import { logger } from '../../logger/index.js';
 
+/** How many per-record fault lines per episode print in full. */
+const FULL_RECORD_LINES_PER_EPISODE = 2;
+
+/** The per-record summary interval, also the quiet gap that ends an episode. */
+const RECORD_SUMMARY_INTERVAL_MS = 60000;
+
 // ============================================================================
 // VALIDATION HELPERS
 // ============================================================================
@@ -110,6 +145,31 @@ const assertOptionalFunction = function ( value, name ) {
     }
 };
 
+// ============================================================================
+// FACADE LINES
+// ============================================================================
+
+/**
+ * Builds the bounded facade line for one per-record fault family. The
+ * first FULL_RECORD_LINES_PER_EPISODE faults of an episode print in
+ * full; later ones are counted into one summary a minute.
+ *
+ * @param {string} label - The line's message, e.g. `decode failed [DECODE_ERROR]`
+ * @returns {Function} `( detail ) => void`
+ */
+const createRecordLine = function ( label ) {
+    return createLineBound( {
+        fullLines: FULL_RECORD_LINES_PER_EPISODE,
+        intervalMs: RECORD_SUMMARY_INTERVAL_MS,
+        printFull: function ( detail ) {
+            logger.warn( `winkComposer/mqttSource: ${label}: ${detail}` );
+        },
+        printSummary: function ( count, seconds, detail ) {
+            logger.warn( `winkComposer/mqttSource: ${label}: ${detail}; ${count} more in the last ${seconds} s` );
+        }
+    } );
+}; // createRecordLine()
+
 // ============================================================================
 // STATUS REPORTER FACTORY
 // ============================================================================
@@ -123,8 +183,9 @@ const assertOptionalFunction = function ( value, name ) {
  * @param {number} [options.expectedQuietPeriodMs] - Opt-in quiet rule:
  *   yellow when no packet arrives for longer than this
  * @param {function} [options.dedupSizeFn] - Live dedup-cache size read
- * @param {function} [options.nowFn=Date.now] - Clock source. Injection
- *   point for deterministic tests; production uses the default
+ * @param {function} [options.nowFn=monotonicNow] - Clock source, in
+ *   milliseconds and counting up. Injection point for deterministic
+ *   tests; production uses the stopwatch clock
  * @returns {Object} Reporter with lifecycle notes, hot-path counters,
  *   tick and snapshot
  */
@@ -140,7 +201,7 @@ const createStatusReporter = function ( options = {} ) {
         onMetrics = null,
         expectedQuietPeriodMs = null,
         dedupSizeFn = null,
-        nowFn = Date.now
+        nowFn = monotonicNow
     } = options;
 
     assertOptionalFunction( onStatus, 'onStatus' );
@@ -192,6 +253,18 @@ const createStatusReporter = function ( options = {} ) {
     let lastPhase = null;
     let lastCode = null;
 
+    // ── Facade-line state (ADR-028) ──────────────────────────────────
+    // The edge lines key on status and code only, so a phase change
+    // inside one degraded episode prints nothing. `degradedSince` and
+    // `degradedPhase` remember the first non-green edge of the
+    // episode for the recovery line.
+    let printedStatus = 'green';
+    let printedCode = null;
+    let degradedSince = 0;
+    let degradedPhase = null;
+    const decodeLine = createRecordLine( 'decode failed [DECODE_ERROR]' );
+    const transformLine = createRecordLine( 'transform failed [CALLBACK_FAILED]' );
+
     /**
      * Record one decode outcome in the ring.
      *
@@ -229,9 +302,9 @@ const createStatusReporter = function ( options = {} ) {
     // 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
+    // code and never fails silently). A broken onStatus reports
+    // through the facade 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',
@@ -242,18 +315,15 @@ const createStatusReporter = function ( options = {} ) {
     } );
 
     /**
-     * Route a status payload: to the caller's handler when supplied;
-     * otherwise error-path payloads go to a classified console.error
-     * (never silent — ADR-018's two-party rule) and lifecycle
-     * payloads stay quiet.
+     * Hand a status payload to the caller's handler, when there is
+     * one. The facade lines are printed by the callers of this
+     * function, so a payload with no handler is not silent.
      *
      * @param {Object} payload - The structured status payload
      */
     const emitStatus = function ( payload ) {
         if ( safeOnStatus ) {
             safeOnStatus( payload );
-        } else if ( payload.error ) {
-            logger.error( `winkComposer/mqttSource: source error [${payload.error.code}]: ${payload.error.message}` );
         }
     };
 
@@ -261,31 +331,27 @@ const createStatusReporter = function ( options = {} ) {
     // `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.
+    // The facade line comes first and always fires. It is the
+    // guaranteed audience. Inside a flow the runtime installs its own
+    // onStatus wrapper. That wrapper 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.
     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
-                    }
-                } );
-            }
+            emitStatus( {
+                status: severity,
+                connected,
+                phase,
+                error: {
+                    code: 'CALLBACK_FAILED',
+                    message: `user callback ${name} failed: ${detail}`
+                }
+            } );
         }
     } );
 
@@ -352,7 +418,7 @@ const createStatusReporter = function ( options = {} ) {
             return lastSubscribeError;
         }
         if ( code === 'CONNECTION_LOST' ) {
-            return `not connected for ${now - disconnectedAt}ms (red threshold ${DISCONNECT_RED_MS}ms)`;
+            return `not connected for ${Math.round( now - disconnectedAt )}ms (red threshold ${DISCONNECT_RED_MS}ms)`;
         }
         if ( code === 'CONNECT_FAILED' ) {
             return lastConnectError;
@@ -361,7 +427,43 @@ const createStatusReporter = function ( options = {} ) {
             return `decode-error ratio above 1% over the last ${ringCount} messages`;
         }
         // QUIET_PERIOD_EXCEEDED — the only code left.
-        return `no message received for ${now - lastReceivedAt}ms (expected quiet period ${expectedQuietPeriodMs}ms)`;
+        return `no message received for ${Math.round( now - lastReceivedAt )}ms (expected quiet period ${expectedQuietPeriodMs}ms)`;
+    };
+
+    /**
+     * Print one facade line per health edge (ADR-028). An edge is a
+     * change of status or code. A yellow edge prints at warn, a red
+     * edge at error. The return to green prints at warn with the
+     * seconds since the first non-green edge of the episode. A stop
+     * is not a recovery, so it prints nothing.
+     *
+     * @param {string} status - The status just computed
+     * @param {number} now - Current timestamp
+     */
+    const printEdge = function ( status, now ) {
+        if ( status === printedStatus && healthCode === printedCode ) {
+            return;
+        }
+        if ( status === 'green' ) {
+            if ( phase !== 'stopped' ) {
+                const seconds = Math.round( ( now - degradedSince ) / 1000 );
+                const what = printedCode === null ? `: ${degradedPhase} cleared` : ` [${printedCode}]: cleared`;
+                logger.warn( `winkComposer/mqttSource: source recovered${what} after ${seconds} s` );
+            }
+        } else {
+            if ( printedStatus === 'green' ) {
+                degradedSince = now;
+                degradedPhase = phase;
+            }
+            const what = healthCode === null ? `: ${phase}` : ` [${healthCode}]: ${healthMessage( healthCode, now )}`;
+            if ( status === 'red' ) {
+                logger.error( `winkComposer/mqttSource: source error${what}` );
+            } else {
+                logger.warn( `winkComposer/mqttSource: source degraded${what}` );
+            }
+        }
+        printedStatus = status;
+        printedCode = healthCode;
     };
 
     /**
@@ -379,11 +481,12 @@ const createStatusReporter = function ( options = {} ) {
         lastPhase = phase;
         lastCode = healthCode;
 
+        printEdge( status, now );
         const payload = {
             status,
             connected,
             phase,
-            msSinceLastMsg: now - lastReceivedAt
+            msSinceLastMsg: Math.round( now - lastReceivedAt )
         };
         if ( healthCode !== null ) {
             payload.error = { code: healthCode, message: healthMessage( healthCode, now ) };
@@ -476,7 +579,8 @@ const createStatusReporter = function ( options = {} ) {
         /**
          * The stop's time budget ran out and the socket was forced
          * closed. Reported with the sources' shared `note` convention
-         * (CSV and testHarness use the same wording).
+         * (CSV and testHarness use the same wording), and as one warn
+         * line.
          *
          * @param {number} timeoutMs - The exceeded budget
          */
@@ -484,15 +588,19 @@ const createStatusReporter = function ( options = {} ) {
             phase = 'stopped';
             connected = false;
             const now = nowFn();
+            const note = `Stop took longer than ${timeoutMs}ms — forced.`;
             lastStatus = 'yellow';
             lastPhase = 'stopped';
             lastCode = null;
+            printedStatus = 'yellow';
+            printedCode = null;
+            logger.warn( `winkComposer/mqttSource: source stopped: ${note}` );
             emitStatus( {
                 status: 'yellow',
                 connected: false,
                 phase: 'stopped',
-                msSinceLastMsg: now - lastReceivedAt,
-                note: `Stop took longer than ${timeoutMs}ms — forced.`
+                msSinceLastMsg: Math.round( now - lastReceivedAt ),
+                note
             } );
             emitMetrics();
         },
@@ -527,9 +635,10 @@ const createStatusReporter = function ( options = {} ) {
         },
 
         /**
-         * A payload could not be decoded. Emits the mandated
-         * per-record report (ADR-018: skip, classify, continue — never
-         * silent), then re-evaluates the ratio rule.
+         * A payload could not be decoded. Prints the bounded facade
+         * line, emits the mandated per-record report (ADR-018: skip,
+         * classify, continue — never silent), then re-evaluates the
+         * ratio rule.
          *
          * @param {string} detail - Operator-facing description
          */
@@ -538,6 +647,7 @@ const createStatusReporter = function ( options = {} ) {
             skipped += 1;
             lastReceivedAt = nowFn();
             ringPush( 1 );
+            decodeLine( detail );
             emitStatus( {
                 status: 'yellow',
                 connected,
@@ -555,17 +665,19 @@ const createStatusReporter = function ( options = {} ) {
         },
 
         /**
-         * The user's transform threw. Emits the mandated per-record
-         * report (skip, classify, continue — the transform contract,
-         * source-transform-uniformity 2026-07-11), classified as
-         * CALLBACK_FAILED: user code, never a transport failure. No
-         * evaluate() — a transform throw feeds no health rule, so
-         * there is no transition to re-derive.
+         * The user's transform threw. Prints the bounded facade line
+         * and emits the mandated per-record report (skip, classify,
+         * continue — the transform contract, source-transform-
+         * uniformity 2026-07-11), classified as CALLBACK_FAILED: user
+         * code, never a transport failure. No evaluate() — a transform
+         * throw feeds no health rule, so there is no transition to
+         * re-derive.
          *
          * @param {string} detail - Operator-facing description
          */
         transformFailed: function ( detail ) {
             skipped += 1;
+            transformLine( detail );
             emitStatus( {
                 status: 'yellow',
                 connected,