@winkjs/composer 0.6.0 → 0.8.0

package/src/core/utils/address/probe.js

@@ -0,0 +1,210 @@
+// core/utils/address/probe.js
+
+/**
+ * @fileoverview The setup probe: does the configured address answer on
+ * every address it resolves to?
+ *
+ * Why it exists (ADR-030 item 4): a name such as `db.plant.local` can
+ * resolve to two addresses, `::1` and `127.0.0.1`, and a service may
+ * listen on only one. Node connects to the first address the resolver
+ * returns. On the run-5 rig the first address refused while the
+ * second answered, the flow ran on the second for 32 hours, and then
+ * the name stopped working with no change composer could see. So the
+ * QuestDB adapter probes both of its endpoints at setup, before any
+ * client is built, and fails setup unless every resolved address
+ * answers. The message names each address and its result and, when
+ * one answered, the literal to set.
+ *
+ * How it probes:
+ * - An IP literal is probed once. A name is resolved with Node's
+ *   default lookup, all addresses, no family or order forced. That is
+ *   the same resolve path the QuestDB client takes, so the probe sees
+ *   what the client will see. A shell tool cannot stand in for it:
+ *   `curl` and `nc` resolve and fall back differently from Node.
+ * - The lookup has the same time limit as a connect. A resolver pool
+ *   that stalls is a real failure mode: on the run-5 rig one held
+ *   every flush open for minutes. A lookup that does not answer in
+ *   time fails the probe as `timeout`, and no address is dialled.
+ * - Every address is probed in resolver order, one at a time, with a
+ *   time limit each. A probe is one TCP connect; the socket is
+ *   destroyed the moment it answers, fails, or times out. The socket
+ *   is not `unref`'d: an unref'd socket would let the process exit
+ *   with the probe still pending when nothing else holds the event
+ *   loop open, which is the case for a headless flow at setup. The
+ *   time limit bounds the wait instead.
+ * - A late event after the first (an error after a connect) changes
+ *   nothing; each attempt settles once.
+ * - Results are `answers`, `refused` (ECONNREFUSED), `timeout`
+ *   (ETIMEDOUT or the time limit), or the Node error code as is.
+ *
+ * The lookup and the connect are injectable so the adapter specs run
+ * against scripted sockets. ADR-029's adapter calls the same probe
+ * once when a flush fails to connect, off the hot path, to attach a
+ * diagnosis to the report. Setup path only; nothing here runs per
+ * message.
+ */
+
+import dns from 'node:dns';
+import net from 'node:net';
+
+import { formatHostPort, suggestLiteral } from './index.js';
+
+const DEFAULT_PROBE_TIMEOUT_MS = 2000;
+
+/**
+ * Names the outcome of a failed connect.
+ *
+ * @param {Error} err - The socket error
+ * @returns {string} `refused`, `timeout`, the Node code, or `error`
+ */
+const resultForError = function ( err ) {
+    if ( err.code === 'ECONNREFUSED' ) {
+        return 'refused';
+    }
+    if ( err.code === 'ETIMEDOUT' ) {
+        return 'timeout';
+    }
+    return err.code || 'error';
+}; // resultForError()
+
+/**
+ * Builds the one-address dialler over the injected connect.
+ *
+ * @param {function} connectFn - `net.connect`-shaped: `( { host, port } ) => socket`
+ * @param {number} timeoutMs - The time limit per attempt
+ * @returns {function} `( address, port ) => Promise<string>` resolving to the result name
+ */
+const makeDial = function ( connectFn, timeoutMs ) {
+    return function ( address, port ) {
+        return new Promise( ( resolve ) => {
+            const socket = connectFn( { host: address, port } );
+            let settled = false;
+            const finish = function ( result ) {
+                if ( settled ) {
+                    return;
+                }
+                settled = true;
+                socket.destroy();
+                resolve( result );
+            };
+            socket.once( 'connect', () => finish( 'answers' ) );
+            socket.once( 'error', ( err ) => finish( resultForError( err ) ) );
+            socket.setTimeout( timeoutMs, () => finish( 'timeout' ) );
+        } );
+    };
+}; // makeDial()
+
+/**
+ * Resolves a name within the time limit. The timer is cleared the
+ * moment the lookup settles, so a normal lookup leaves nothing behind.
+ * The timer is not `unref`'d, for the same reason as the socket above.
+ *
+ * @param {function} lookupFn - The resolver, `( host, { all: true } ) => Promise<targets>`
+ * @param {string} host - The name to resolve
+ * @param {number} timeoutMs - The time limit
+ * @returns {Promise<Array>} The resolved targets; rejects with code `timeout` at the limit
+ */
+const lookupWithin = function ( lookupFn, host, timeoutMs ) {
+    return new Promise( ( resolve, reject ) => {
+        const pending = lookupFn( host, { all: true } );
+        const timer = setTimeout( () => {
+            const err = new Error( `lookup of '${host}' did not answer within ${timeoutMs} ms` );
+            err.code = 'timeout';
+            reject( err );
+        }, timeoutMs );
+        pending.then(
+            ( targets ) => {
+                clearTimeout( timer );
+                resolve( targets );
+            },
+            ( err ) => {
+                clearTimeout( timer );
+                reject( err );
+            }
+        );
+    } );
+}; // lookupWithin()
+
+/**
+ * Probes the targets one at a time, in order. Written as a recursion
+ * rather than a loop so no `await` sits inside a loop body; the depth
+ * is the number of resolved addresses, two or three in practice.
+ *
+ * @param {Array<{address: string, family: number}>} targets - Resolved addresses
+ * @param {number} port - The port to probe
+ * @param {function} dial - The dialler from `makeDial`
+ * @param {Array} attempts - The results so far
+ * @returns {Promise<Array>} One `{ address, family, result }` per target
+ */
+const probeEach = async function ( targets, port, dial, attempts ) {
+    if ( attempts.length === targets.length ) {
+        return attempts;
+    }
+    const target = targets[ attempts.length ];
+    const result = await dial( target.address, port );
+    attempts.push( { address: target.address, family: target.family, result } );
+    return probeEach( targets, port, dial, attempts );
+}; // probeEach()
+
+/**
+ * Probes one classified address. Passes only when every resolved
+ * address answers.
+ *
+ * @param {Object} address - A `classifyAddress` result of kind `ip` or `name`, with a port
+ * @param {Object} [options] - Injection points
+ * @param {function} [options.lookupFn=dns.promises.lookup] - The resolver
+ * @param {function} [options.connectFn=net.connect] - The connect
+ * @param {number} [options.timeoutMs=2000] - The time limit per address, and for the lookup
+ * @returns {Promise<Object>} `{ ok, host, port, attempts }`, or
+ *   `{ ok: false, host, port, lookupError, attempts: [] }` when the name did not resolve in time
+ */
+const probeAddress = async function ( address, options = {} ) {
+    const {
+        lookupFn = dns.promises.lookup,
+        connectFn = net.connect,
+        timeoutMs = DEFAULT_PROBE_TIMEOUT_MS
+    } = options;
+    const dial = makeDial( connectFn, timeoutMs );
+
+    let targets;
+    if ( address.kind === 'ip' ) {
+        targets = [ { address: address.host, family: address.family } ];
+    } else {
+        try {
+            targets = await lookupWithin( lookupFn, address.host, timeoutMs );
+        } catch ( err ) {
+            return { ok: false, host: address.host, port: address.port, lookupError: err.code || err.message, attempts: [] };
+        }
+    }
+
+    const attempts = await probeEach( targets, address.port, dial, [] );
+    const ok = attempts.every( ( attempt ) => attempt.result === 'answers' );
+    return { ok, host: address.host, port: address.port, attempts };
+}; // probeAddress()
+
+/**
+ * Renders a probe outcome for an operator: each address with its
+ * result and, when one answered but another did not, the literal to
+ * set. The rig's own case reads
+ * `[::1]:9000 refused, 127.0.0.1:9000 answers; set ilpUrl to 127.0.0.1:9000`.
+ *
+ * @param {Object} outcome - A `probeAddress` result
+ * @param {string} field - The config key, for the suggestion
+ * @param {Object} address - The classified address that was probed
+ * @returns {string} The detail sentence
+ */
+const describeProbe = function ( outcome, field, address ) {
+    if ( outcome.lookupError !== undefined ) {
+        return `'${outcome.host}' did not resolve (${outcome.lookupError})`;
+    }
+    const listed = outcome.attempts
+        .map( ( attempt ) => `${formatHostPort( attempt.address, outcome.port )} ${attempt.result}` )
+        .join( ', ' );
+    const answering = outcome.attempts.find( ( attempt ) => attempt.result === 'answers' );
+    if ( outcome.ok || ( answering === undefined ) ) {
+        return listed;
+    }
+    return `${listed}; set ${field} to ${suggestLiteral( address, answering.address )}`;
+}; // describeProbe()
+
+export { probeAddress, describeProbe, DEFAULT_PROBE_TIMEOUT_MS };

package/src/core/utils/callback-guard/index.js

@@ -32,9 +32,22 @@
  *   thrown value. When the report closure itself fails, the guard
  *   falls back to one bare log line with no user-value
  *   interpolation.
+ * - The fault report is bounded per wrapped callback (ADR-029, the
+ *   bounded loss line). A callback that fails on every call would
+ *   print one line per call, which for a status callback on a busy
+ *   source is a line per message. So the first two faults of an
+ *   episode report in full, later faults are counted, and one summary
+ *   reports per minute with the count. A quiet minute ends the
+ *   episode. The summary goes through the site's own channel with the
+ *   count appended to the detail, so no site changes.
  */
 
 import { logger } from '../../logger/index.js';
+import { createLineBound } from '../line-rate/index.js';
+
+/** The bound on the fault report (see the file header). */
+const FULL_FAULT_LINES_PER_EPISODE = 2;
+const FAULT_SUMMARY_INTERVAL_MS = 60000;
 
 /**
  * Frozen sentinel `wrapTransform` returns when the transform threw.
@@ -92,9 +105,17 @@ const wrapCallback = function ( fn, { name, severity, report } ) {
     if ( typeof fn !== 'function' ) {
         return null;
     }
+    const bounded = createLineBound( {
+        fullLines: FULL_FAULT_LINES_PER_EPISODE,
+        intervalMs: FAULT_SUMMARY_INTERVAL_MS,
+        printFull: report,
+        printSummary: function ( count, seconds, sev, callbackName, detail ) {
+            report( sev, callbackName, `${detail}; ${count} more fault(s) in the last ${seconds} s` );
+        }
+    } );
     const faultFn = function ( err ) {
         try {
-            report( severity, name, describeFault( err ) );
+            bounded( severity, name, describeFault( err ) );
         } catch {
             reportFallback();
         }
@@ -152,4 +173,4 @@ const wrapTransform = function ( fn, onFault ) {
     };
 }; // wrapTransform()
 
-export { wrapCallback, wrapTransform, TRANSFORM_THREW };
+export { wrapCallback, wrapTransform, TRANSFORM_THREW, FULL_FAULT_LINES_PER_EPISODE, FAULT_SUMMARY_INTERVAL_MS };

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

@@ -0,0 +1,34 @@
+// core/utils/clock/index.js
+
+/**
+ * @fileoverview The stopwatch clock for time rules that must not
+ * follow the wall clock.
+ *
+ * `Date.now()` reads the wall clock, and the wall clock can step. NTP
+ * corrects a board after boot or after a long time without network,
+ * and an operator can set the time by hand. A rule such as "red after
+ * 30 s disconnected" or "expire a dedup entry after 120 s" would then
+ * fire early or late by the size of the step. `performance.now()`
+ * reads a clock that only counts up, from process start, in
+ * milliseconds with a fraction. A step in the wall clock does not
+ * move it (ADR-018, long-running stability).
+ *
+ * The function reads `globalThis.performance` at every call, for two
+ * reasons. The method must be called on its own object, so the bare
+ * method cannot be passed around as a clock. And a test that fakes the
+ * stopwatch replaces the global object rather than patching the
+ * method, so a captured reference would keep reading the real clock.
+ *
+ * Use this clock for durations and expiry. Use `Date.now()` for
+ * timestamps that leave the process, such as a record's time field.
+ */
+
+/**
+ * Reads the stopwatch clock.
+ *
+ * @returns {number} Milliseconds since process start, with a fraction;
+ *   never decreases.
+ */
+export const monotonicNow = function () {
+    return globalThis.performance.now();
+}; // monotonicNow()

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 };