@winkjs/composer 0.6.0 → 0.7.0

package/src/core/utils/jitter/index.js

@@ -0,0 +1,51 @@
+// core/utils/jitter/index.js
+
+/**
+ * @fileoverview Adds a random share to a reconnect period, once per
+ * client, so a fleet does not retry in step.
+ *
+ * mqtt.js retries at a fixed period. When one broker goes away, every
+ * client that used it fails at the same moment and retries on the same
+ * beat. Attempt `k` from every client lands on the recovering broker
+ * at `k` times the period, all at once. This module gives each client
+ * its own period: the configured one plus a random share of up to a
+ * fifth of it. The share is drawn once at setup, and because attempt
+ * `k` fires at `k` times the period, a fixed offset spreads the fleet
+ * further with each attempt.
+ *
+ * The configured period is the operator's floor. The helper never
+ * shortens it, and a period of zero stays zero, so a reconnect that
+ * was switched off stays off. Both MQTT adapters use this module; the
+ * reconnect loop itself stays the library's (ADR-018).
+ *
+ * The random source is a parameter, so a spec can name its result.
+ * Nothing here runs on a message path.
+ *
+ * @see ADR-018
+ */
+
+/** The largest share of the period the jitter may add. */
+export const RECONNECT_JITTER_FRACTION = 0.2;
+
+/**
+ * Returns the period plus the floor of a random share of it.
+ *
+ * @param {number} periodMs - The configured period, a finite number of milliseconds, zero or more
+ * @param {Object} [options]
+ * @param {number} [options.fraction=RECONNECT_JITTER_FRACTION] - The largest share to add, in `[0, 1]`
+ * @param {Function} [options.random=Math.random] - Returns a number in `[0, 1)`
+ * @returns {number} `periodMs + Math.floor( random() * periodMs * fraction )`
+ * @throws {TypeError} when an argument is out of range
+ */
+export const jitteredPeriod = function ( periodMs, { fraction = RECONNECT_JITTER_FRACTION, random = Math.random } = {} ) {
+    if ( ( typeof periodMs !== 'number' ) || !Number.isFinite( periodMs ) || ( periodMs < 0 ) ) {
+        throw new TypeError( `winkComposer/jitter: periodMs must be a finite number of milliseconds, zero or more, got ${String( periodMs )}` );
+    }
+    if ( ( typeof fraction !== 'number' ) || !( ( fraction >= 0 ) && ( fraction <= 1 ) ) ) {
+        throw new TypeError( `winkComposer/jitter: fraction must be a number in [0, 1], got ${String( fraction )}` );
+    }
+    if ( typeof random !== 'function' ) {
+        throw new TypeError( 'winkComposer/jitter: random must be a function' );
+    }
+    return periodMs + Math.floor( random() * periodMs * fraction );
+}; // jitteredPeriod()

package/src/core/utils/line-rate/index.js

@@ -0,0 +1,104 @@
+// core/utils/line-rate/index.js
+
+/**
+ * @fileoverview Bounds how often a repeating event reaches the log.
+ *
+ * A dead sensor, a stuck callback, or an unreachable database produces
+ * the same event once per row. Printing every one fills a log file with
+ * one line per second for a whole night, and the line that matters is
+ * lost in the repeats. This module keeps the first lines of such an
+ * episode in full and then prints one summary per interval. An episode
+ * is a run of events with no quiet interval between them. A quiet
+ * interval ends the episode, so the next event prints in full again.
+ *
+ * The bound is a pure closure over a stopwatch reading, `monotonicNow`,
+ * so a step in the wall clock can neither end an episode nor move a
+ * summary (ADR-018, long-running stability). It holds no timer, so it
+ * needs no shutdown and cannot keep a process alive. The
+ * summary prints at the next event after the interval, never on a
+ * timer. So a burst that stops shows its count only when the next
+ * episode starts, or never. That is the accepted trade for zero timers.
+ *
+ * Two sites share this shape. The QuestDB adapter's flush-failure loss
+ * line uses the same algorithm inline (ADR-029, the bounded loss line).
+ * The adapter's default row-skip warning and the callback guard's
+ * `CALLBACK_FAILED` line both use this module.
+ */
+
+import { monotonicNow } from '../clock/index.js';
+
+/**
+ * Creates a line bound.
+ *
+ * The returned function takes the event's arguments, up to three, and
+ * forwards them by identity to `printFull` for the first `fullLines`
+ * events of an episode. What the arguments mean is the caller's
+ * business: the callback guard passes a severity, a callback name and
+ * a fault description; the row-skip warning passes a raw value and a
+ * partition id. Later events inside the interval are counted. The
+ * first event a full interval after the last printed line calls
+ * `printSummary` with the count since that line, the seconds elapsed,
+ * and the latest arguments. When an episode ends with counted events,
+ * their summary prints before the next episode's first full line.
+ *
+ * Three named parameters stand in for a rest parameter on purpose. A
+ * rest parameter builds an array on every call, and the row-skip
+ * warning runs once per skipped row.
+ *
+ * @param {Object} options
+ * @param {number} options.fullLines - How many events per episode print in full.
+ * @param {number} options.intervalMs - The summary interval, also the quiet gap that ends an episode.
+ * @param {Function} options.printFull - Called as `printFull( arg1, arg2, arg3 )` with the event's arguments.
+ * @param {Function} options.printSummary - Called as `printSummary( count, seconds, arg1, arg2, arg3 )`.
+ * @returns {Function} `( arg1, arg2, arg3 ) => void`.
+ */
+export const createLineBound = function ( { fullLines, intervalMs, printFull, printSummary } ) {
+    let lastEventAt = 0;
+    let lastLineAt = 0;
+    let printed = 0;
+    let counted = 0;
+
+    // The state clears before the printer runs, as on the full-line
+    // path. A printer that throws then costs that one line only. With
+    // the old order a throw left the count and the stamp behind, and
+    // every later event ran straight into the printer again.
+    const summarize = function ( now, arg1, arg2, arg3 ) {
+        const seconds = Math.round( ( now - lastLineAt ) / 1000 );
+        const count = counted;
+        lastLineAt = now;
+        counted = 0;
+        printSummary( count, seconds, arg1, arg2, arg3 );
+    }; // summarize()
+
+    // The latest arguments are kept for the summary that closes an
+    // episode. They belong to the last counted event, not the new one.
+    let lastArg1;
+    let lastArg2;
+    let lastArg3;
+
+    return function ( arg1, arg2, arg3 ) {
+        const now = monotonicNow();
+        if ( ( now - lastEventAt ) >= intervalMs ) {
+            // A quiet interval ended the previous episode.
+            if ( counted > 0 ) {
+                summarize( now, lastArg1, lastArg2, lastArg3 );
+            }
+            printed = 0;
+        }
+        lastEventAt = now;
+        lastArg1 = arg1;
+        lastArg2 = arg2;
+        lastArg3 = arg3;
+        if ( printed < fullLines ) {
+            printed += 1;
+            lastLineAt = now;
+            printFull( arg1, arg2, arg3 );
+            return;
+        }
+        counted += 1;
+        if ( ( now - lastLineAt ) < intervalMs ) {
+            return;
+        }
+        summarize( now, arg1, arg2, arg3 );
+    };
+}; // createLineBound()

package/src/core/utils/quantize/index.js

@@ -11,24 +11,30 @@
  * for human reading. Both used to carry their own copy of the same
  * formula; this module is the single source.
  *
- * The quantizer pre-computes the inverse resolution and the appropriate
- * decimal-place count at build time, so the per-message hot path is one
- * multiply, one round, one multiply, one `toFixed` — no allocation, no
- * recomputation.
+ * The quantizer chooses its arithmetic once, at build time, so the
+ * per-message hot path is a few float operations and no allocation.
+ * Three shapes of resolution get three paths:
  *
- * Decimal places follow the natural rule:
- * - `resolution = 0.001` → 3 decimal places
- * - `resolution = 0.01`  → 2 decimal places
- * - `resolution = 0.1`   → 1 decimal place
- * - `resolution = 1`     → 0 (returns `null`, signalling passthrough)
- * - `resolution = 5`     → 0 (whole-number resolution; values still
- *                          snap to multiples of 5, but no decimals to
- *                          format)
+ * - The inverse is a whole number (0.1, 0.01, 0.001, 0.25, 0.5, 0.2,
+ *   0.125). The value is `Math.round( v * inverse ) / inverse`. A
+ *   division by an exact whole number is correctly rounded, so it
+ *   returns the nearest double to the grid value: 101 / 10 is 10.1
+ *   and 95 / 4 is 23.75. No string is built.
+ * - The resolution is a whole number (5, 10, 7). The value is
+ *   `Math.round( v / resolution ) * resolution`, exact for whole
+ *   numbers. No string is built.
+ * - Anything else (0.3, 0.15, 2.5). The old path stays: multiply,
+ *   round, multiply, then `toFixed` to trim the noise and `Number` to
+ *   parse it back. The trim keeps as many decimals as the resolution
+ *   itself has. This path allocates one short string per value. It is
+ *   rare: a declared resolution is nearly always a power of ten.
  *
- * The `toFixed` step cleans up floating-point noise — for example,
- * `Math.round( 10.1 * 10 ) * 0.1` produces `10.100000000001` because
- * of IEEE-754 rounding, and `toFixed(1)` returns the tidy `"10.1"`
- * which `Number(...)` parses back to `10.1`.
+ * Why not `toFixed` for everything. `Math.round( 10.1 * 10 ) * 0.1` is
+ * `10.100000000000001`, because 0.1 is not exact in binary, so a
+ * multiply by the resolution needs a trim. The trim built a string per
+ * value on the storage hot path. It also cut grid values short: with a
+ * resolution of 0.25 the trim kept one decimal, so 23.75 became 23.8,
+ * off the grid. Division by the exact inverse has neither problem.
  *
  * Returning `null` for `resolution === 1` (or undefined) is a small but
  * load-bearing optimisation: the common case is "no resolution declared"
@@ -62,9 +68,27 @@ const buildResolutionQuantizer = function ( resolution ) {
     if ( resolution === undefined || resolution === 1 ) return null;
 
     const invResolution = 1 / resolution;
-    const decimalPlaces = resolution < 1 ?
-        Math.ceil( -Math.log10( resolution ) ) :
-        0;
+
+    if ( Number.isInteger( invResolution ) ) {
+        return function ( v ) {
+            return Math.round( v * invResolution ) / invResolution;
+        };
+    }
+
+    if ( Number.isInteger( resolution ) ) {
+        return function ( v ) {
+            return Math.round( v / resolution ) * resolution;
+        };
+    }
+
+    // The string path trims the noise to the decimals the grid needs.
+    // The count comes from the resolution's own digits, so 0.15 gets
+    // two and 2.5 gets one. A resolution below one millionth prints in
+    // exponent form, so it takes the count from its magnitude instead.
+    const text = String( resolution );
+    const decimalPlaces = ( text.indexOf( 'e' ) === -1 ) ?
+        ( text.length - text.indexOf( '.' ) - 1 ) :
+        Math.ceil( -Math.log10( resolution ) );
 
     return function ( v ) {
         const quantized = Math.round( v * invResolution ) * resolution;

package/src/core/wiring/wire-emitters.js

@@ -54,8 +54,10 @@ import { logger } from '../logger/index.js';
  * contract's method surface.
  * `getPressure` is optional — its presence decides whether the handle is
  * collected into `backpressureAwareSinks`, not whether the wire succeeds.
+ * `flush` is required, as it is for storages: ADR-018 §6 lists it in
+ * the sink floor for both roles.
  */
-const REQUIRED_EMITTER_METHODS = [ 'publishNow', 'shutdown', 'getHealth' ];
+const REQUIRED_EMITTER_METHODS = [ 'publishNow', 'flush', 'shutdown', 'getHealth' ];
 
 /**
  * Serializes a rejection's `dropped` payload for the shutdown log. A

package/src/core/wiring/wire-storages.js

@@ -146,6 +146,13 @@ const storages = ( function () {
     // to assetClass.name if not explicitly specified.
     const wire = async function ( specs, storageConfigs, storageModules, assetClass = null ) {
         const pendingStorages = [];
+        // Names whose factory has been called in THIS wire() call. The
+        // singleton slot is filled only after every pending factory has
+        // settled. Without this set, a flow with several persist-if nodes
+        // on one storage would call the factory once per node and keep
+        // only the last handle. Each orphan would hold a flush timer, an
+        // agent, and a sender for the life of the process.
+        const pendingNames = new Set();
 
         for ( const spec of specs ) {
             // Skip non-persistIf nodes
@@ -155,8 +162,8 @@ const storages = ( function () {
 
             const storageName = spec.storageName;
 
-            // Skip if already in singleton registry
-            if ( singletons[ storageName ] ) {
+            // Skip if already in singleton registry, or already being built
+            if ( singletons[ storageName ] || pendingNames.has( storageName ) ) {
                 continue; // eslint-disable-line no-continue
             }
 
@@ -196,6 +203,7 @@ const storages = ( function () {
 
             // createStorage may return Promise (async) or storage directly (sync)
             const storageOrPromise = module.createStorage( effectiveConfig );
+            pendingNames.add( storageName );
             pendingStorages.push( { storageName, storageOrPromise } );
         }
 

package/src/flow/flow.js

@@ -47,6 +47,27 @@ import { validateWithSchema } from '../core/utils/validate/index.js';
 import { assetClassSchema } from '../core/semantics/schemas/index.js';
 import { expandTemplateSpec } from './expand-template-spec.js';
 
+/**
+ * Throws the flow's setup error for an adapter config that the
+ * adapter's own schema rejected. The error carries `INVALID_CONFIG`,
+ * the ADR-018 setup code, and the ADR-028 bracket. A program matches
+ * the code; an operator reads the remedy the schema names.
+ *
+ * @param {{valid: boolean, errors: string[]}} validation - The schema result
+ * @param {string} label - `flow.<method>.<adapterId>`, for the message
+ * @throws {Error} INVALID_CONFIG when the config is invalid
+ */
+const throwIfAdapterConfigInvalid = function ( validation, label ) {
+    if ( validation.valid ) {
+        return;
+    }
+    const err = new Error(
+        `winkComposer/${label}: validation failed [INVALID_CONFIG]:\n  - ${validation.errors.join( '\n  - ' )}`
+    );
+    err.code = 'INVALID_CONFIG';
+    throw err;
+}; // throwIfAdapterConfigInvalid()
+
 const flow = function ( flowName = 'flow1' ) {
     const api = Object.create( null );
 
@@ -171,7 +192,7 @@ const flow = function ( flowName = 'flow1' ) {
         // not later inside adapter.start().
         if ( adapter.configSchema ) {
             const validation = validateWithSchema( adapter.configSchema, sourceConfig, 'source' );
-            validation.throwIfInvalid( `flow.source.${adapter.id || 'unknown'}` );
+            throwIfAdapterConfigInvalid( validation, `flow.source.${adapter.id || 'unknown'}` );
         }
 
         runtime.source = { adapter, config: sourceConfig };
@@ -195,7 +216,7 @@ const flow = function ( flowName = 'flow1' ) {
         // not later inside adapter.createEmitter().
         if ( adapter.configSchema ) {
             const validation = validateWithSchema( adapter.configSchema, emitterConfig, 'emitter' );
-            validation.throwIfInvalid( `flow.emitter.${adapter.id}` );
+            throwIfAdapterConfigInvalid( validation, `flow.emitter.${adapter.id}` );
         }
 
         runtime.emitters[ adapter.id ] = { adapter, config: emitterConfig };
@@ -219,7 +240,7 @@ const flow = function ( flowName = 'flow1' ) {
         // not later inside adapter.createStorage().
         if ( adapter.configSchema ) {
             const validation = validateWithSchema( adapter.configSchema, storageConfig, 'storage' );
-            validation.throwIfInvalid( `flow.storage.${adapter.id}` );
+            throwIfAdapterConfigInvalid( validation, `flow.storage.${adapter.id}` );
         }
 
         runtime.storages[ adapter.id ] = { adapter, config: storageConfig };

package/src/flow/run.js

@@ -272,6 +272,21 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
         }
     }; // runDrainStage()
 
+    // A sink stage returns `Promise.allSettled` results. The wiring
+    // logs each adapter whose drain rejected and lets its siblings
+    // finish, so one failing sink never strands another's data. The
+    // loss must still reach this handle's caller. A rejected drain is
+    // how the shutdown manager knows to exit 1 (ADR-018 §7). So once
+    // every adapter in the stage has drained, the stage throws the
+    // first rejected reason, code and dropped count intact.
+    const throwFirstRejection = function ( results ) {
+        for ( let i = 0; i < results.length; i += 1 ) {
+            if ( results[ i ].status === 'rejected' ) {
+                throw results[ i ].reason;
+            }
+        }
+    }; // throwFirstRejection()
+
     const drainAll = async function () {
         const stageErrors = [];
         try {
@@ -281,9 +296,9 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
                     () => stopSource( { timeout: STAGE_TIMEOUT_MS } ) );
             }
             await runDrainStage( 'emitter', stageErrors,
-                () => emitters.shutdown( { timeout: STAGE_TIMEOUT_MS } ) );
+                async () => throwFirstRejection( await emitters.shutdown( { timeout: STAGE_TIMEOUT_MS } ) ) );
             await runDrainStage( 'storage', stageErrors,
-                () => storages.shutdown( { timeout: STAGE_TIMEOUT_MS } ) );
+                async () => throwFirstRejection( await storages.shutdown( { timeout: STAGE_TIMEOUT_MS } ) ) );
         } finally {
             // Whatever the path here — clean drain or a stage that threw —
             // the source has stopped producing, so unblock any
@@ -311,8 +326,15 @@ export const runFlow = async function ( flowName, specsOrSpecsByCase, importSet,
     // the process as unhandled. The classified log keeps the loss
     // loud without the crash, and a caller that later awaits
     // `handle.shutdown()` still receives the memoized rejection.
+    //
+    // The exit code carries the loss too. This drain has no awaiting
+    // caller, and the flow left the shutdown manager's list when the
+    // drain began, so no other path can set it. A batch script that
+    // replays a file and loses rows at the end must exit 1, the same
+    // as the signal path does (ADR-018 §7).
     const observedShutdown = function () {
         shutdown().catch( function ( err ) {
+            process.exitCode = 1;
             logger.error(
                 `winkComposer/flow '${flowName}': shutdown failed ` +
                 `[${( err && err.code ) || 'UNKNOWN'}]: ${( err && err.message ) || String( err )}`