@winkjs/composer 0.0.2 → 0.4.0

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

@@ -0,0 +1,157 @@
+/**
+ * This function transforms individual nodes into executable closures that automatically
+ * handle message processing and flow control.
+ *
+ * The returned closure executes the node's update/publishTo cycle and automatically
+ * routes the processed message to all configured next hops, enabling declarative
+ * flow composition from imperative node definitions.
+ *
+ * Key features:
+ * - Enables automatic flow execution without manual sequencing
+ * - Provides node-level error isolation to prevent cascade failures
+ * - Supports complex routing patterns (fan-out, conditional, parallel)
+ * - Built-in error tracking and observability at the node level
+ *
+ * @param {Object} nodeModule - Node implementation containing init, update, publishTo, etc.
+ * @param {number} nodeIndex - Index position in the state store array
+ * @param {Array<Function>} nextHops - Array of downstream node closures to invoke
+ * @param {Object} [options={}] - Configuration options for error tracking and behavior
+ * @param {boolean} [options.trackErrors=true] - Enable error count and details tracking
+ * @param {number} [options.maxRecentErrors=5] - Maximum recent errors to retain
+ * @returns {Function} Executable closure that processes messages and routes to next hops
+ *
+ * @example
+ * const median3Node = wireNode( median3, [ ewmaFastNode ], 0 );
+ * const ewmaNode = wireNode( ewma, [ diffNode ], 1 );
+ *
+ * // Execute the wired flow
+ * median3Node( stateStore, message );
+ *
+ * // Access error statistics
+ * console.log( stateStore[0].errorStats.totalErrors );
+ * console.log( stateStore[0].errorStats.recentErrors );
+ */
+const wireNode = function ( nodeModule, nodeIndex, nextHops = [], options = {} ) {
+    // Extract options with defaults
+    const trackErrors = options.trackErrors !== false; // Default to true
+    const maxRecentErrors = options.maxRecentErrors || 5;
+    // Validate required node module interface at wire-time
+    if ( !nodeModule || typeof nodeModule.update !== 'function' ) {
+        throw new TypeError( `composer/wireNode: Node module must implement update function; found ${typeof nodeModule.update}` );
+    }
+
+    if ( typeof nodeModule.publishTo !== 'function' ) {
+        throw new TypeError( `composer/wireNode: Node module must implement publishTo function; found ${typeof nodeModule.publishTo}` );
+    }
+
+    // Validate next hops are executable functions
+    if ( !Array.isArray( nextHops ) ) {
+        throw new TypeError( `composer/wireNode: Next hops must be an array; found ${typeof nextHops}` );
+    }
+
+    for ( let i = 0; i < nextHops.length; i += 1 ) {
+        if ( typeof nextHops[ i ] !== 'function' ) {
+            throw new TypeError( `composer/wireNode: Next hop at index ${i} must be a function; found ${typeof nextHops[ i ]}` );
+        }
+    }
+
+    // Validate node index for state store access
+    if ( typeof nodeIndex !== 'number' || nodeIndex < 0 ) {
+        throw new RangeError( `composer/wireNode: Node index must be a non-negative number; found ${nodeIndex}` );
+    }
+
+    /**
+     * The wired node closure - executes this node and routes to downstream nodes.
+     *
+     * This closure maintains the reactive flow execution pattern while providing
+     * This closure automatically routes to next hops. It ensures node-level error isolation and
+     * maintains referential transparency for functional composition.
+     *
+     * Includes optional error tracking that maintains statistics directly in the
+     * node's state for built-in observability and debugging support.
+     *
+     * @param {Array} stateStore - Partitioned state array containing node states
+     * @param {Object} message - Input message to process through this node
+     * @param {Array} [triggers=[]] - Control signal definitions for inter-node high priority communication
+     * @returns {void}
+     *
+     * @throws {Error} Node execution errors are isolated and re-thrown with context
+     */
+    const executeWiredNode = function ( stateStore, message ) {
+        // Extract this node's state from the partitioned state store
+        const nodeState = stateStore[ nodeIndex ];
+
+        // Initialize error tracking if enabled and not already present
+        if ( trackErrors && !nodeState.errorStats ) {
+            nodeState.errorStats = {
+                totalErrors: 0,
+                lastErrorTime: null,
+                lastErrorMessage: null,
+                recentErrors: [], // Circular buffer of recent error details
+                errorsByType: Object.create( null ) // Count by error type
+            };
+        }
+
+        try {
+            // Execute the node's update logic with control signals
+            // This modifies the node's internal state based on the incoming message
+            const state = nodeModule.update( nodeState, message );
+
+            // The `update` may return null, typically for filter node.
+            if ( state === null ) return;
+
+            // Publish computed results to the message for downstream consumption
+            // This enriches the message with this node's output without side effects
+            nodeModule.publishTo( nodeState, message );
+
+            // Route the enriched message to all configured downstream nodes
+            // Each next hop receives the same enriched message and state store
+            for ( let i = 0; i < nextHops.length; i += 1 ) {
+                nextHops[ i ]( stateStore, message );
+            }
+
+        } catch ( error ) {
+            // Track error statistics if enabled
+            if ( trackErrors ) {
+                const errorStats = nodeState.errorStats;
+                const timestamp = Date.now();
+
+                // Update error counters
+                errorStats.totalErrors += 1;
+                errorStats.lastErrorTime = timestamp;
+                errorStats.lastErrorMessage = error.message;
+
+                // Track errors by type for pattern analysis
+                const errorType = error.constructor.name || 'Error';
+                errorStats.errorsByType[ errorType ] = ( errorStats.errorsByType[ errorType ] || 0 ) + 1;
+
+                // Maintain circular buffer of recent errors
+                const errorDetail = {
+                    timestamp,
+                    message: error.message,
+                    type: errorType,
+                    stack: error.stack ? error.stack.split( '\n' )[ 0 ] : null // First line only
+                };
+
+                // Add to recent errors, maintaining max size
+                errorStats.recentErrors.push( errorDetail );
+                if ( errorStats.recentErrors.length > maxRecentErrors ) {
+                    errorStats.recentErrors.shift(); // Remove oldest
+                }
+            }
+
+            // Provide node-level error isolation with contextual information
+            // This prevents individual node failures from crashing the entire flow
+            const nodeError = new Error( `Node execution failed at index ${nodeIndex}: ${error.message}` );
+            nodeError.cause = error;
+            nodeError.nodeIndex = nodeIndex;
+            nodeError.nodeModule = nodeModule.getNodeType ? nodeModule.getNodeType() : 'unknown';
+
+            throw nodeError;
+        }
+    };
+
+    return executeWiredNode;
+}; // wireNode()
+
+export default wireNode;

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

@@ -0,0 +1,173 @@
+// core/wiring/wire-semantics.js
+
+/**
+ * @fileoverview Reads each adapter's `semanticsRequirement` declaration and
+ * injects only the slice of `assetClass` that the adapter says it needs.
+ *
+ * Some adapters need to know about the asset class to do their job — for
+ * example QuestDB reads `name`, `columns`, and `insightTypes` to create
+ * tables and to know what to write into them. Other adapters (a stdout
+ * emitter, an MQTT broker) usually don't care.
+ *
+ * Each adapter declares what it needs via a `semanticsRequirement` export
+ * on its module. The wiring layer reads that declaration and acts on it
+ * before calling the adapter's factory:
+ *
+ *   semanticsRequirement: {
+ *       assetClass: {
+ *           required: true,
+ *           fields: [ 'name', 'insightTypes', 'columns' ]
+ *       }
+ *   }
+ *
+ * `required: true` means: if the flow author did not call `.assetClass()`,
+ * fail at startup with a clear message — never call the adapter's factory
+ * with a missing assetClass.
+ *
+ * `fields` is an allowlist: the adapter receives a fresh object containing
+ * exactly those top-level fields and nothing else. This is the documented
+ * top-level dependency surface — anyone reading the adapter's declaration
+ * sees exactly which assetClass fields the adapter touches without
+ * grep-hunting through its consumption code. ADR-018 calls this
+ * "capability-indexed" and explicitly rejects the type-indexed
+ * alternative ("storage gets assetClass, others don't") that this
+ * mechanism replaces.
+ *
+ * The slicing is **top-level only**. Adapters that read column-internal
+ * facts (QuestDB reads `columns.*.type` and `columns.*.resolution`;
+ * terminal reads `columns.*.resolution`) currently express
+ * those needs through adapter-side defensive validation in their
+ * `createStorage` / `createEmitter` plus adapter-side consumption code.
+ * The declarative mechanism for column-internal capability is deferred
+ * to a future ADR; it waits for a second adapter with different
+ * column-internal needs.
+ *
+ * Why capability-indexed (declaration on the adapter) instead of
+ * type-indexed (a wiring rule like "all storages get assetClass"):
+ * because type-indexed rules don't generalise. Today only QuestDB needs
+ * assetClass; a future structured emitter that publishes to
+ * `${assetClass}/${insightType}` topics would want the same slice. With
+ * this declaration mechanism it just opts in — no edit to the wiring
+ * layer required.
+ *
+ * `err.code` (setup-time throws carry a classified code per ADR-018):
+ * - `MISSING_ASSET_CLASS` — the adapter declared `assetClass.required: true`
+ *   but the flow runtime has no assetClass to give. Operator remediation:
+ *   add `.assetClass(assetClassDef)` to the flow definition. Same `err.code`
+ *   that QuestDB's createStorage already throws; this layer
+ *   catches the problem earlier in the lifecycle, before the factory is
+ *   called.
+ *
+ * @see ADR-018 (semantic capability declaration)
+ * @see ADR-017 (adapters read facts; never make decisions)
+ */
+
+/**
+ * Build a fresh object containing only the fields the adapter declared it
+ * reads.
+ *
+ * Uses `Object.create( null )` because the keys come from the adapter's
+ * declaration array — external to this module — so we treat the result
+ * as a runtime-keyed dictionary rather than a fixed-shape struct. This
+ * also sidesteps the (small) prototype-pollution surface where a field
+ * named `__proto__` would mutate the prototype on a plain `{}` literal.
+ * Field names are nominally adapter-controlled, but defensive cost is
+ * zero so we take it.
+ *
+ * Fields that the source assetClass does not have come through as
+ * `undefined` (same as if the field were absent on the original object).
+ * The adapter sees exactly what it asked for; any gap is its own
+ * responsibility to handle.
+ *
+ * @param {Object} assetClass - the full assetClass object from runtime
+ * @param {string[]} fields - the allowlist of top-level field names
+ * @returns {Object} a new object containing only the requested fields
+ */
+const sliceAssetClass = function ( assetClass, fields ) {
+    const slice = Object.create( null );
+    for ( let i = 0; i < fields.length; i += 1 ) {
+        const field = fields[ i ];
+        slice[ field ] = assetClass[ field ];
+    }
+    return slice;
+};
+
+/**
+ * Apply an adapter's `semanticsRequirement` to its config object before
+ * the factory is called. Mutates `effectiveConfig` in place — the caller
+ * passes a freshly-spread copy of user config that we are free to enrich.
+ *
+ * Behaviour matrix:
+ *
+ *   declaration absent           → no-op (returns false)
+ *   declared, runtime supplied   → slice of assetClass injected as
+ *                                  effectiveConfig.assetClass; returns true
+ *   declared+required, missing   → throws with err.code MISSING_ASSET_CLASS
+ *   declared+optional, missing   → no injection, no error; returns true
+ *                                  (declaration was honored — there was
+ *                                  just nothing to inject)
+ *
+ * Today only the `assetClass` key is recognised within the declaration;
+ * the shape is extensible for future capability needs (e.g., a
+ * `streamSchema` slice once such a thing exists). When the declaration
+ * names a key we don't recognise yet, we ignore it silently — adapters
+ * are free to use newer wiring features against older composer
+ * installations without breaking.
+ *
+ * Returns a boolean so callers can tell "did this declaration touch my
+ * config?". Used by wire-storages during the transitional window when
+ * the legacy hardcoded fallback only fires for adapters that DON'T
+ * declare semanticsRequirement.
+ *
+ * @param {string} adapterId - identifier used in the error message
+ * @param {Object} module - the imported adapter module/object
+ * @param {Object|null} runtimeAssetClass - the assetClass passed via
+ *   flow.assetClass(), or null/undefined if the flow author did not call it
+ * @param {Object} effectiveConfig - the config object that will be passed
+ *   to the adapter factory; mutated in place when injection happens
+ * @returns {boolean} true if the adapter declared a semanticsRequirement
+ *   that this helper recognised (whether or not it injected anything);
+ *   false if no declaration was present
+ * @throws {Error} `err.code === 'MISSING_ASSET_CLASS'` when the adapter
+ *   declared `assetClass.required: true` and runtimeAssetClass is null
+ */
+const applySemanticsRequirement = function ( adapterId, module, runtimeAssetClass, effectiveConfig ) {
+    const requirement = module && module.semanticsRequirement;
+
+    // Adapters that don't read semantics declare nothing (or `{}`). Either
+    // way we have nothing to inject and nothing to validate.
+    if ( !requirement || !requirement.assetClass ) {
+        return false;
+    }
+
+    const assetClassReq = requirement.assetClass;
+
+    if ( !runtimeAssetClass ) {
+        if ( assetClassReq.required ) {
+            // Per ADR-018, setup-time throws carry a classified err.code.
+            // MISSING_ASSET_CLASS (not INVALID_CONFIG) so operator tooling
+            // can route on it — the remediation is to add a `.assetClass()`
+            // call to the flow, not to fix transport config. Same code as
+            // QuestDB's existing createStorage guard; this layer
+            // catches it earlier in the lifecycle.
+            const err = new Error(
+                `WinkComposer/wiring: adapter '${adapterId}' declares semanticsRequirement.assetClass.required ` +
+                'but the flow has no .assetClass() — add .assetClass(assetClassDef) to the flow definition'
+            );
+            err.code = 'MISSING_ASSET_CLASS';
+            throw err;
+        }
+        // Declared but not required, and not supplied — leave the
+        // adapter's config alone. The adapter is responsible for handling
+        // the no-assetClass case if it opted-in optionally.
+        return true;
+    }
+
+    // Slice only the declared fields. Adapter never sees more than it
+    // asked for; declaration is the auditable contract.
+    const fields = assetClassReq.fields || [];
+    effectiveConfig.assetClass = sliceAssetClass( runtimeAssetClass, fields );
+    return true;
+};
+
+export { applySemanticsRequirement, sliceAssetClass };

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

@@ -0,0 +1,344 @@
+// core/wiring/wire-storages.js
+
+/**
+ * @fileoverview Holds the running storage instances for a flow and creates
+ * them on demand from the spec.
+ *
+ * A "storage" is the thing that persists messages to a time-series database
+ * (QuestDB today; potentially others later). One storage per name is enough
+ * — many partitions and many persist-if nodes can share it — so we keep
+ * them in a small registry keyed by storage name and only build a new one
+ * if we haven't seen that name before.
+ *
+ * This file is responsible for four things:
+ * - Building each storage at flow startup, by calling its module's
+ *   `createStorage(config)` factory and storing the returned handle.
+ *   The factory may be async (QuestDB needs to negotiate tables via
+ *   PostgreSQL before the ILP sender is ready); both async and sync
+ *   factories are supported.
+ * - Calling `applySemanticsRequirement` (from `wire-semantics.js`) on each
+ *   storage so adapters that declare `semanticsRequirement` get the
+ *   requested slice of `assetClass` injected before their factory is
+ *   called (capability-indexed injection per ADR-018).
+ *   The earlier hardcoded "every storage gets the full assetClass
+ *   plus a tablePrefix default" pattern was removed; adapters that need
+ *   defaulting (e.g., QuestDB's `tablePrefix ?? assetClass.name`) own
+ *   that logic themselves.
+ * - Checking, the moment we get the handle back, that it has the methods
+ *   the rest of the framework will call later (fail loudly at startup
+ *   rather than crash deep in the per-message hot path). See
+ *   `assert-handle.js` for the check helper and the error format.
+ * - Telling the partition manager which storages expose `getPressure()` so
+ *   the pressure-aware yield decision (ADR-020, Draft) can poll them. The
+ *   list is exposed via `getBackpressureAwareSinks()` and assembled by
+ *   `flow/run.js` after the flow's partition state is set up.
+ *
+ * Restart safety: `shutdown()` clears the registry after stopping every
+ * storage, so a follow-up `wire()` call on the same process gets a fresh
+ * set of handles. (See the longer comment on shutdown for the production
+ * and testing rationale.)
+ *
+ * The IIFE around the registry hides it from outside callers; only the
+ * exported methods can read or change it.
+ *
+ * @see ADR-018 (sink method surface)
+ * @see ADR-020 (backpressure-aware-sinks collection; Draft)
+ */
+
+import { assertHandle } from './assert-handle.js';
+import { assertModuleDurability } from './assert-module.js';
+import { applySemanticsRequirement } from './wire-semantics.js';
+
+/**
+ * Methods the framework calls on a storage handle later, so they have to
+ * be present at wire time per ADR-018.
+ * `getStats` was previously here and was later removed from the
+ * contract's method surface.
+ * `getPressure` is optional — its presence decides whether the handle is
+ * collected into `backpressureAwareSinks`, not whether the wire succeeds.
+ */
+const REQUIRED_STORAGE_METHODS = [ 'write', 'flush', 'shutdown', 'getHealth' ];
+
+/**
+ * Serializes a rejection's `dropped` payload for the shutdown log. A
+ * third-party adapter can reject with anything — including structures
+ * JSON.stringify throws on (circular references). The log line must never
+ * throw: a throw here used to skip the registry clear that followed it.
+ * Mirrors `wire-emitters.js`.
+ *
+ * @param {*} dropped - the rejection's dropped payload
+ * @returns {string} JSON, or a fallback marker when unserializable
+ */
+const describeDropped = function ( dropped ) {
+    try {
+        return JSON.stringify( dropped );
+    } catch {
+        return '[unserializable]';
+    }
+}; // describeDropped()
+
+/**
+ * Stamps the annotate key-sweep support object onto a persistIf spec.
+ *
+ * The persistIf node warns, once per gate, when a function-form annotate
+ * returns a record with invented keys — keys that are neither declared
+ * columns nor message fields. Such a key is almost always a typo, and it
+ * fails silently: the persist plan writes only declared columns, so the
+ * value never reaches storage. The node needs two things for that check,
+ * both known only here at wire time: the declared-column set for the
+ * spec's insightType, and a once-flag every partition shares. Both ride
+ * the spec, exactly like `spec.storage` — `init` copies the reference into
+ * each partition's state, so one flag covers all partitions of the gate.
+ *
+ * No stamp when there is nothing to check: no function-form annotate, no
+ * asset class, or an insightType the asset class does not declare (flow
+ * validation rejects that last case already; this guard stays defensive).
+ *
+ * @param {Object} spec - persistIf node spec (mutated: gains annotateSweep)
+ * @param {Object|null} assetClass - The flow's asset class, when provided
+ */
+const stampAnnotateSweep = function ( spec, assetClass ) {
+    if ( typeof spec.annotate !== 'function' ) {
+        return;
+    }
+    const insightTypeSpec = assetClass && assetClass.insightTypes && assetClass.insightTypes[ spec.insightType ];
+    if ( !insightTypeSpec ) {
+        return;
+    }
+    spec.annotateSweep = {
+        declaredColumns: new Set( insightTypeSpec.columns ),
+        checked: false
+    };
+}; // stampAnnotateSweep()
+
+const storages = ( function () {
+    // ========================================================================
+    // PRIVATE STATE: Singleton Registry
+    // ========================================================================
+    // The registry holds all storage singletons keyed by their storage name.
+    // This ensures exactly one instance per storage across the entire system,
+    // preventing resource waste from duplicate connections/handles.
+    const singletons = Object.create( null );
+
+    // ========================================================================
+    // WIRE: Discover and Create Storage Singletons
+    // ========================================================================
+    // Scans node specifications to find Persist If nodes and creates singleton
+    // storages for their targets. This is called during flow initialization
+    // for each specialization, but the singleton check ensures each storage
+    // is created and initialized exactly once.
+    //
+    // Storage Lifecycle:
+    // 1. createStorage(config) - Creates and initializes storage (may be async)
+    // 2. write() - Called during message processing
+    // 3. shutdown() - Graceful termination
+    //
+    // The createStorage() call may be async (e.g., QuestDB needs to create tables
+    // via PostgreSQL before the storage is ready). For backwards compatibility,
+    // sync createStorage functions are also supported.
+    //
+    // Legacy init() support: If storage.init() exists, it's called after creation
+    // for backwards compatibility with older storage adapters.
+    //
+    // assetClass: Optional asset class object from flow's .assetClass() method.
+    // When provided, it is injected into storage config and tablePrefix defaults
+    // to assetClass.name if not explicitly specified.
+    const wire = async function ( specs, storageConfigs, storageModules, assetClass = null ) {
+        const pendingStorages = [];
+
+        for ( const spec of specs ) {
+            // Skip non-persistIf nodes
+            if ( spec.nodeType !== 'Persist If' || !spec.storageName ) {
+                continue; // eslint-disable-line no-continue
+            }
+
+            const storageName = spec.storageName;
+
+            // Skip if already in singleton registry
+            if ( singletons[ storageName ] ) {
+                continue; // eslint-disable-line no-continue
+            }
+
+            const module = storageModules[ storageName ];
+            if ( !module?.createStorage ) {
+                throw new Error( `composer: Invalid storage module: ${storageName}` );
+            }
+
+            // ADR-018 module-surface check: the module must say what a
+            // crash costs — before the factory runs.
+            assertModuleDurability( storageName, module );
+
+            // Build effective config starting from user config; we layer
+            // adapter-driven injection on top.
+            const userConfig = storageConfigs[ storageName ] || {};
+            const effectiveConfig = { ...userConfig };
+
+            // Capability-indexed injection per ADR-018. The helper
+            // reads `module.semanticsRequirement` and injects the declared
+            // slice of assetClass when one is present. Adapters that don't
+            // need semantics declare nothing and the helper is a no-op for
+            // them. Adapters that do (e.g., QuestDB) declare what they
+            // need and only that slice is injected.
+            //
+            // The earlier hardcoded "every storage gets the full
+            // assetClass plus a tablePrefix default" path was removed.
+            // Adapters that need a
+            // tablePrefix default now own that logic themselves (e.g.,
+            // QuestDB's createStorage defaults `tablePrefix` from
+            // `assetClass.name` when not supplied).
+            applySemanticsRequirement(
+                storageName,
+                module,
+                assetClass,
+                effectiveConfig
+            );
+
+            // createStorage may return Promise (async) or storage directly (sync)
+            const storageOrPromise = module.createStorage( effectiveConfig );
+            pendingStorages.push( { storageName, storageOrPromise } );
+        }
+
+        // Await all pending storage creations (handles both async and sync)
+        // Sequential to ensure proper resource ordering (file locks, ports)
+        for ( const { storageName, storageOrPromise } of pendingStorages ) {
+            const storage = await storageOrPromise; // eslint-disable-line no-await-in-loop
+
+            // Wire-time shape check (ADR-018). Fails fast with a
+            // descriptive error instead of letting a missing method crash
+            // the per-message hot path later.
+            assertHandle( storageName, storage, REQUIRED_STORAGE_METHODS );
+
+            singletons[ storageName ] = storage;
+
+            // Legacy init() support for backwards compatibility
+            if ( storage.init ) {
+                await storage.init(); // eslint-disable-line no-await-in-loop
+            }
+        }
+
+        // Assign storage references to specs, plus the annotate key-sweep
+        // support the node reads at init (see stampAnnotateSweep above).
+        for ( const spec of specs ) {
+            if ( spec.nodeType === 'Persist If' && spec.storageName ) {
+                spec.storage = singletons[ spec.storageName ];
+                stampAnnotateSweep( spec, assetClass );
+            }
+        }
+    }; // wire()
+
+    // ========================================================================
+    // GET BACKPRESSURE-AWARE SINKS
+    // ========================================================================
+    /**
+     * Returns the subset of wired storages that expose `getPressure()`.
+     * Keys are namespaced as `storage:<storageName>` so a debug log at
+     * the call site (the pressure-aware yield decision, ADR-020)
+     * immediately tells the operator which sink crossed the threshold.
+     * See `flow/run.js` for the assembly into
+     * `composerState.partitionState.backpressureAwareSinks`.
+     */
+    const getBackpressureAwareSinks = function () {
+        const map = Object.create( null );
+        for ( const [ storageName, handle ] of Object.entries( singletons ) ) {
+            if ( typeof handle.getPressure === 'function' ) {
+                map[ `storage:${storageName}` ] = handle;
+            }
+        }
+        return map;
+    }; // getBackpressureAwareSinks()
+
+    // ========================================================================
+    // GET: Retrieve All Singletons (Defensive Copy)
+    // ========================================================================
+    // Returns a shallow copy of the singleton registry to prevent external
+    // mutation. This is useful for health monitoring and debugging.
+    const get = function () {
+        return { ...singletons };
+    }; // get()
+
+    // ========================================================================
+    // SHUTDOWN: Graceful Termination of All Storages
+    // ========================================================================
+    // Coordinates the shutdown of all storage singletons, ensuring connections
+    // are properly closed and buffered data is flushed. Uses Promise.allSettled
+    // to ensure all shutdowns are attempted even if some fail, preventing one
+    // failed shutdown from blocking others. Returns a Promise that resolves
+    // when all shutdown attempts complete (successfully or not).
+    //
+    // IMPORTANT: Registry Clearing Behavior
+    // -------------------------------------
+    // After calling shutdown() on all storages, the singleton registry is cleared.
+    // This design decision serves two purposes:
+    //
+    // 1. PRODUCTION: Enables clean restart scenarios. If a pipeline shuts down
+    //    and needs to restart (e.g., after reconfiguration), fresh storage
+    //    instances will be created on the next wire() call. Without clearing,
+    //    stale/closed storage references would persist and cause errors.
+    //
+    // 2. TESTING: Enables test isolation. Each test can call shutdown() in
+    //    afterEach() to ensure a clean slate for the next test. Without this,
+    //    the singleton pattern would cause state leakage between tests.
+    //
+    // Usage Guidelines:
+    // - In production: Call shutdown() only during pipeline termination or
+    //   when intentionally restarting the pipeline with new configuration.
+    // - In tests: Call shutdown() in afterEach() to ensure test isolation.
+    // - After shutdown(): Any subsequent wire() calls will create new instances.
+    //
+    // Per ADR-018, each storage's own shutdown takes `{ timeout }`.
+    // We pass it through so the flow's per-stage time budget (set in
+    // flow/run.js) reaches every storage the same way.
+    const shutdown = async function ( { timeout } = {} ) {
+        const opts = ( timeout === undefined ) ? undefined : { timeout };
+        const names = Object.keys( singletons );
+        const results = await Promise.allSettled(
+            names.map( ( name ) => {
+                // A non-conforming adapter may THROW from shutdown()
+                // instead of rejecting. Convert the throw into this
+                // adapter's own rejection slot — escaping here would
+                // skip the siblings' drain and the registry clear.
+                try {
+                    return opts ? singletons[ name ].shutdown( opts ) : singletons[ name ].shutdown();
+                } catch ( err ) {
+                    return Promise.reject( err );
+                }
+            } )
+        );
+        // Clear the registry FIRST for clean restart capability (see
+        // documentation above for the rationale). This must not depend
+        // on the logging below — a hostile rejection payload used to
+        // throw mid-log and leave the stale handles behind.
+        for ( const key of names ) {
+            delete singletons[ key ];
+        }
+        // A rejected drain must reach a human (ADR-018's two-party
+        // rule). allSettled keeps one failing storage from blocking its
+        // siblings' drain — but the swallowed rejection is a data loss
+        // that would otherwise be visible only to callers inspecting the
+        // settled results. Log each one, classified, naming the adapter.
+        // String( err ) rather than interpolation: a Symbol rejection
+        // reason throws inside a template literal.
+        results.forEach( ( result, i ) => {
+            if ( result.status === 'rejected' ) {
+                const err = result.reason || {};
+                const dropped = err.dropped ? ` dropped=${describeDropped( err.dropped )}` : '';
+                console.error(
+                    `WinkComposer/wiring: storage '${names[ i ]}' shutdown failed [${err.code || 'UNKNOWN'}]: ${err.message || String( err )}${dropped}`
+                );
+            }
+        } );
+        return results;
+    }; // shutdown()
+
+    // ========================================================================
+    // PUBLIC API
+    // ========================================================================
+    return {
+        wire,
+        get,
+        getBackpressureAwareSinks,
+        shutdown
+    };
+}() ); // storages()
+
+export default storages;