@winkjs/composer 0.6.0 → 0.8.0

package/src/core/emitter-manager/mqtt/emitter.js

@@ -15,6 +15,20 @@
  * closes that gap by construction; the composer-owned WAL that restores
  * crash durability is ADR-021's planned successor.
  *
+ * The adapter is one closure factory per concern, the shape QuestDB's
+ * flush engine uses. This file is the factory. It resolves the
+ * configuration, builds the state, opens the client, and assembles the
+ * handle from the modules beside it:
+ * - `resolve-config.js` validates every option in one fixed order and
+ *   arms the three callbacks through the shared guard.
+ * - `connection.js` opens the client, waits for the first connack, and
+ *   keeps `state.connected` and the counters current.
+ * - `health.js` reads pressure and health, and signals backpressure.
+ * - `publish.js` is the hot path, `publishNow`.
+ * - `shutdown-drain.js` is the latched drain-then-close shutdown.
+ * Each module captures what it needs at setup. Nothing moves onto a
+ * per-message argument list.
+ *
  * DESIGN DECISIONS:
  *
  * 1. FIRE-AND-FORGET WITH QoS 1
@@ -37,6 +51,12 @@
  * 3. MESSAGE EXPIRY (MQTT v5)
  *    - Configurable per message type
  *    - Prevents flooding backend after extended offline periods
+ *    - The type lookup is a null-prototype table. A prototype key such
+ *      as 'constructor' would hand the library a function, and
+ *      mqtt-packet then destroys the stream with an error that carries
+ *      no code. mqtt.js swallows such an error, so no handler sees it,
+ *      and the poison packet replays on every reconnect. An unknown
+ *      key falls back to the default expiry instead.
  *
  * 4. NO FORCED IDENTITY / OPTIONAL WILL — unchanged transport behavior.
  *
@@ -48,8 +68,10 @@
  *      reachable broker the real wait is one connack round trip; on an
  *      unreachable one the flow starts with `connected: false` and the
  *      client keeps retrying in the background.
- *    - Return shape: the handle itself at grace 0, otherwise a Promise
- *      of it. The wiring layer awaits either (ADR-018).
+ *    - Return shape: always a Promise of the handle, as QuestDB's
+ *      factory returns. At grace 0 the promise resolves without a
+ *      wait. A configuration refusal arrives as a rejection carrying
+ *      the classified code. The wiring layer awaits it (ADR-018).
  *    - This replaced the wire-time `sleep(240)` that once papered over
  *      the pre-connack loss ADR-021 eliminated.
  *
@@ -61,7 +83,12 @@
  *   when supplied (ctx = `{ topic }`); without a handler the adapter
  *   surfaces the failure via `Promise.reject(deliveryErr)` — loud failure
  *   beats silent loss (parity with QuestDB). `onCritical` is
- *   reserved for the high-pressure `QUEUE_CRITICAL` warning (no loss yet).
+ *   reserved for the high-pressure `QUEUE_CRITICAL` warning (no loss
+ *   yet). It fires once per climb past 0.8 and re-arms below 0.66;
+ *   `onBackpressure` reports the pressure after every acknowledgment.
+ * - `flush( { timeout }? )` waits for every accepted message to settle,
+ *   closing nothing and refusing nothing. On its deadline it rejects
+ *   `DELIVERY_FAILED` with `pending: { count }` (ADR-018 §6).
  * - `getPressure()` returns unacked / maxQueueSize in `[0, 1]` (sync,
  *   O(1), allocation-free per ADR-018).
  * - `getHealth()` returns the ADR-018 health floor `{status, connected,
@@ -100,7 +127,12 @@
  * - `SHUTTING_DOWN`    — emitter is mid-shutdown; new publishes are dropped.
  * - `INVALID_CONFIG`   — setup-time; missing or malformed config field
  *   (brokerUrl, codec.pack, callback type, connectGraceMs). On the
- *   thrown TypeError per ADR-018's fail-fast setup rule.
+ *   thrown TypeError per ADR-018's fail-fast setup rule. Includes a
+ *   `brokerUrl` whose host is `localhost` (ADR-030): the name can
+ *   resolve to two addresses and the broker may listen on only one.
+ *   The message names the literal to set. Refused before the client
+ *   is created, at the schema (flow definition) and here (the
+ *   `MQTT_BROKER_URL` fallback and direct callers).
  * - `SHUTDOWN_TIMEOUT` — shutdown closed with unacknowledged messages;
  *   carries `dropped: { count }` (the exact counter value). Fires whether
  *   connected or not: with no disk store, nothing survives the process,
@@ -113,240 +145,49 @@
  *   keeps publishing and each fault becomes one classified console
  *   line. Fix the callback; the line names it and carries the detail.
  *
- * @module mqtt-emitter
- */
-
-import mqtt from 'mqtt';
-import crypto from 'crypto';
-import { ENV_VARS } from '../../env-vars.js';
-import {
-    QOS,
-    MQTT_CONFIG,
-    WINK_NAMESPACE,
-    QUEUE_CRITICAL_THRESHOLD,
-    MESSAGE_EXPIRY,
-    DEFAULT_MAX_QUEUE_SIZE,
-    MQTT_INFLIGHT_ID_LIMIT
-} from './constants.js';
-import { wrapCallback } from '../../utils/callback-guard/index.js';
-import { logger } from '../../logger/index.js';
-
-/**
- * Pre-flight reject threshold on store pressure.
- * 0.9 = 10% headroom for in-flight drain on shutdown, plus a clean band
- * between the yellow-health threshold (0.66, shared with the yield level the
- * ADR-020 Draft proposes) and store exhaustion (1.0). At or above this,
- * `publishNow` returns `STORAGE_FULL` synchronously; the message is not buffered.
- * @type {number}
- */
-const STORAGE_PRESSURE_LIMIT = 0.9;
-
-/**
- * Pressure threshold above which `getHealth().status` elevates to at least
- * 'yellow' (uniform with Terminal/QuestDB). The value matches the
- * pressure-aware-yield design (ADR-020, still a Draft). That design
- * proposes 0.66 as the pressure level where the flow would start yielding
- * to let sinks drain; a benchmark still has to confirm the number. Today
- * the yield trigger is time-only (ADR-024), so this alignment is
- * forward-looking.
- * @type {number}
- */
-const HEALTH_PRESSURE_YELLOW_THRESHOLD = 0.66;
-
-/**
- * Singleton success result reused on every successful publish. Hot-path zero
- * allocation per ADR-013 / ADR-004. Plain literal — not frozen.
- * @type {{ok: true}}
- */
-const RESULT_OK = { ok: true };
-
-/**
- * Singleton error result for the pre-flight pressure-limit reject. Reused on
- * every occurrence; rare in healthy operation (pressure this close to the
- * limit means delivery has stopped draining), but a defined contract path.
- * @type {{ok: false, error: {code: string, message: string}}}
- */
-const ERR_STORAGE_FULL = {
-    ok: false,
-    error: {
-        code: 'STORAGE_FULL',
-        message: 'Store at or above pressure limit (0.9) — cannot accept message'
-    }
-};
-
-/**
- * Singleton error result for publishes attempted while shutdown is in progress.
- * @type {{ok: false, error: {code: string, message: string}}}
- */
-const ERR_SHUTTING_DOWN = {
-    ok: false,
-    error: {
-        code: 'SHUTTING_DOWN',
-        message: 'Emitter is shutting down — message dropped'
-    }
-};
-
-/**
- * Build a config-error TypeError tagged for ADR-018 fail-fast setup routing.
- * @param {string} message
- * @returns {TypeError}
- */
-const invalidConfig = function ( message ) {
-    const err = new TypeError( 'winkComposer/mqttEmitter: ' + message );
-    err.code = 'INVALID_CONFIG';
-    return err;
-};
-
-/**
- * Throw classified when an optional callback option is set to a non-function.
- * @param {*} value - the configured option value
- * @param {string} name - the option name for the error message
- */
-const assertOptionalCallback = function ( value, name ) {
-    if ( value !== undefined && typeof value !== 'function' ) {
-        throw invalidConfig( `${name} must be a function` );
-    }
-};
-
-/**
- * Validate and build the mqtt.js will (last-will testament) options.
- *
- * Direct createEmitter callers bypass the DSL schema, so the factory
- * checks the will shape itself, and the payload encoding runs behind
- * the same classified-throw rule as every other setup failure
- * (ADR-018, fail-fast setup) — a raw codec TypeError would reach the
- * caller unclassified.
+ * Console classification (a token on a log line, not an `err.code`):
+ * - `DELIVERY_HEALTH`  — the link changed state. One line per change,
+ *   with or without `debug`: going offline at error, the next connack
+ *   at warn with the outage length. Both carry the in-flight count.
+ *   Nothing prints while a state persists (see `connection.js`).
+ * - `CONNECT_FAILED`   — the client's `error` event, at warn, with
+ *   the reason (a refused connect, a connack timeout). Bounded: two
+ *   per episode in full, then one summary a minute.
+ * - `ADDRESS_IS_NAME`  — the `brokerUrl` host is a name other than
+ *   `localhost`. One `logger.warn` line at setup, before the client is
+ *   created (ADR-030). A name is allowed and the emitter proceeds; the
+ *   line tells the operator that only a literal address is immune to a
+ *   resolver that changes its answer under a running process. This
+ *   emitter refuses and warns; it does not probe, because its posture
+ *   is recovering (ADR-018 §5).
  *
- * @param {Object} will - config.will as supplied
- * @param {Object} codec - config.codec (pack + contentType)
- * @returns {Object} the mqtt.js connect-options `will` object
+ * @module mqtt-emitter
  */
-const buildWillOptions = function ( will, codec ) {
-    if ( typeof will.topic !== 'string' || will.topic.length === 0 ) {
-        throw invalidConfig( 'will.topic is required — a non-empty string' );
-    }
-    if ( will.message === undefined || will.message === null ) {
-        throw invalidConfig( 'will.message is required' );
-    }
-    let willPayload;
-    try {
-        willPayload = Buffer.from( codec.pack( will.message ) );
-    } catch ( packErr ) {
-        throw invalidConfig( `will.message could not be encoded by the codec: ${packErr.message}` );
-    }
-    const willOptions = {
-        topic: will.topic,
-        payload: willPayload,
-        // `??`, not `||`: 0 is a valid QoS.
-        qos: will.qos ?? QOS,
-        retain: will.retain !== false,  // Default true
-        properties: {
-            contentType: codec.contentType
-        }
-    };
-    if ( codec.payloadFormatIndicator === 1 ) {
-        willOptions.properties.payloadFormatIndicator = true;
-    }
-    return willOptions;
-};
 
-/**
- * Bounded wait for the client's first 'connect' event (the broker's
- * connection acknowledgment). Resolves when the event fires or when
- * graceMs elapses, whichever comes first. Expiry is NOT an error —
- * the startup posture stays 'recovering' (ADR-018): the caller gets
- * a working handle that reports `connected: false` while mqtt.js
- * retries in the background. The one-shot listener is removed on
- * expiry so a late connack reaches only the permanent state handler;
- * the timer is cleared on connect so nothing pins the event loop.
- *
- * @param {Object} client - mqtt.js client (EventEmitter surface)
- * @param {number} graceMs - positive wait budget, milliseconds
- * @returns {Promise<void>} resolves on first connect or expiry; never rejects
- */
-const waitForFirstConnect = function ( client, graceMs ) {
-    return new Promise( ( resolve ) => {
-        let timer = null;
-        const onConnect = function () {
-            clearTimeout( timer );
-            resolve();
-        };
-        timer = setTimeout( () => {
-            client.removeListener( 'connect', onConnect );
-            resolve();
-        }, graceMs );
-        client.once( 'connect', onConnect );
-    } );
-}; // waitForFirstConnect()
+import { resolveConfig } from './resolve-config.js';
+import { openClient, waitForFirstConnect, attachConnectionHandlers } from './connection.js';
+import { createHealth } from './health.js';
+import { createPublishNow } from './publish.js';
+import { createShutdown } from './shutdown-drain.js';
 
 /**
  * Create production MQTT emitter.
  *
- * Validation is synchronous — bad config throws before any side
- * effect. The return shape depends on the effective grace:
- * `connectGraceMs === 0` returns the handle directly (today's callers
- * that need synchronous creation pass 0); otherwise returns a Promise
- * resolving to the handle after the first connack or the grace budget.
- * The wiring layer awaits either shape (ADR-018).
+ * Validation runs before any side effect. Bad config rejects the
+ * returned promise with a classified `INVALID_CONFIG` error, so a
+ * refusal and a handle arrive through the same channel, the way
+ * QuestDB's factory works. With a positive grace the promise resolves
+ * after the first connack or the grace budget; at grace 0 it resolves
+ * without a wait. The wiring layer awaits it (ADR-018).
  *
  * @param {Object} config - emitter config (see configSchema in index.js)
- * @returns {Object|Promise<Object>} the emitter handle, or a Promise of it
+ * @returns {Promise<Object>} the emitter handle
  */
-export const createEmitter = function ( config ) {
-    // Per ADR-018, setup-time throws carry classified err.code.
-    //
-    // brokerUrl: `??` so explicit '' is the user's choice (not "fall back
-    // to env"); `.trim()` rejects whitespace-only. Symmetric with QuestDB,
-    // which throws on `ilpUrl: ''`.
-    const rawBrokerUrl = config.brokerUrl ?? ENV_VARS.mqttBrokerUrl;
-    const brokerUrl = typeof rawBrokerUrl === 'string' ? rawBrokerUrl.trim() : '';
-    if ( !brokerUrl ) {
-        throw invalidConfig( 'brokerUrl required — set a non-empty string in .emitter() config or MQTT_BROKER_URL env var' );
-    }
-    if ( !config.codec ) {
-        throw invalidConfig( 'config.codec is required' );
-    }
-    if ( typeof config.codec.pack !== 'function' ) {
-        throw invalidConfig( 'config.codec must have a pack() function' );
-    }
-    assertOptionalCallback( config.onDeliveryFailure, 'onDeliveryFailure' );
-    assertOptionalCallback( config.onCritical, 'onCritical' );
-    assertOptionalCallback( config.onBackpressure, 'onBackpressure' );
-
-    // The three notification callbacks are armed by the shared
-    // callback guard. They were validated raw above and are wrapped
-    // once here. The wrap matters because all three run inside
-    // mqtt.js's publish ack chain, where a user throw would land in
-    // the client library (ADR-018). Each wrap is null when the
-    // callback is absent, so every no-handler path below keeps its
-    // exact meaning. That includes the deliberate unhandled-rejection
-    // escape hatch for an unhandled delivery failure.
-    const reportCallbackFault = function ( severity, name, detail ) {
-        logger.error(
-            `winkComposer/mqttEmitter: user callback ${name} failed [CALLBACK_FAILED]: ${detail}`
-        );
-    };
-    const onDeliveryFailure = wrapCallback( config.onDeliveryFailure, {
-        name: 'onDeliveryFailure', severity: 'red', report: reportCallbackFault
-    } );
-    const onCritical = wrapCallback( config.onCritical, {
-        name: 'onCritical', severity: 'red', report: reportCallbackFault
-    } );
-    const onBackpressure = wrapCallback( config.onBackpressure, {
-        name: 'onBackpressure', severity: 'yellow', report: reportCallbackFault
-    } );
-
-    // First-connack grace: explicit config → MQTT_CONNECT_GRACE_MS env
-    // fallback → 500 ms default (ADR-018 precedence; the fallback lives
-    // here in the factory body, never as a schema sigil). `??` keeps an
-    // explicit 0 — "hand the handle back immediately" — from falling
-    // through to the env value. Number.isInteger also rejects Infinity,
-    // so the wait is bounded by construction. Validated here, before
-    // mqtt.connect opens anything (fail-fast setup per ADR-018).
-    const connectGraceMs = config.connectGraceMs ?? ENV_VARS.mqttConnectGraceMs;
-    if ( !Number.isInteger( connectGraceMs ) || connectGraceMs < 0 ) {
-        throw invalidConfig( 'connectGraceMs must be a non-negative integer (milliseconds); 0 disables the first-connect wait' );
-    }
+export const createEmitter = async function ( config ) {
+    // Per ADR-018, setup-time refusals carry a classified err.code and
+    // run before any side effect. `resolveConfig` throws in one fixed
+    // order, and this async function turns each throw into a rejection.
+    const resolved = resolveConfig( config );
 
     // Core state. `unacked` is THE counter (ADR-021): +1 on accepted
     // publish, -1 when the publish callback fires. Pressure, refusal,
@@ -365,446 +206,50 @@ export const createEmitter = function ( config ) {
         }
     };
 
-    // Broker URLs may carry credentials (mqtt://user:pass@host). Debug
-    // logs print this redacted form, so a debug flag flipped on in
-    // production cannot leak the password into whatever collects stdout.
-    const redactedBrokerUrl = brokerUrl.replace( /\/\/[^@/]*@/, '//***@' );
-
-    // Generate unique client ID if not provided
-    const clientId = config.clientId || `wink-${Date.now()}-${Math.random().toString( 36 ).slice( 2, 9 )}`;
-
-    // The unacked cap. Clamped to the 16-bit packet-id space: every
-    // unacknowledged QoS-1 message holds a packet id, so one connection
-    // can never carry more than 65,535; 60,000 leaves working headroom
-    // (same clamp the LevelDB store applied, kept with the same warning).
-    const requestedQueueSize = config.maxQueueSize || DEFAULT_MAX_QUEUE_SIZE;
-    if ( requestedQueueSize > MQTT_INFLIGHT_ID_LIMIT ) {
-        logger.warn(
-            `winkComposer/mqttEmitter: maxQueueSize ${requestedQueueSize} exceeds the MQTT ` +
-            `packet-id ceiling — clamped to ${MQTT_INFLIGHT_ID_LIMIT}`
-        );
-    }
-    const maxQueueSize = Math.min( requestedQueueSize, MQTT_INFLIGHT_ID_LIMIT );
-
-    // Build MQTT options.
-    //
-    // NO outgoingStore: the client runs its default SYNCHRONOUS memory
-    // store (ADR-021). mqtt.js erases its packet-id bookkeeping on every
-    // connack and rebuilds it from a store snapshot asynchronously; with
-    // an asynchronous store, writes still in flight at that instant are
-    // invisible to the snapshot and get overwritten by id reuse — real
-    // QoS-1 loss, measured scaling with store write latency. The
-    // synchronous store makes the gap zero-width (validated 2026-07-09,
-    // nine-run matrix incl. reconnects at 45k in flight).
-    //
-    // messageIdProvider: the client's default provider cycles the 16-bit
-    // id space with NO in-use check — at 14 k msg/s it wraps every ~5 s,
-    // and an id whose PUBACK never arrived gets reassigned, overwriting
-    // the unacked packet's memory-store entry (same key). Measured at
-    // about one lost publish per 700,000 under sustained load.
-    // UniqueMessageIdProvider never reissues an in-use id.
-    const mqttOptions = {
-        ...MQTT_CONFIG,
-        clientId,
-        messageIdProvider: new mqtt.UniqueMessageIdProvider()
-    };
-
-    // Only add will if explicitly provided (validated + encoded by the
-    // helper above; classified throws per ADR-018)
-    if ( config.will ) {
-        mqttOptions.will = buildWillOptions( config.will, config.codec );
-    }
-
-    // Create MQTT client (injectable for testing). mqtt.connect throws
-    // its own raw TypeError on a malformed url; classify it like every
-    // other setup failure. The error text uses the redacted url — a
-    // malformed url can still carry credentials.
-    const connect = config.mqttConnectFn || mqtt.connect;
-    let client;
-    try {
-        client = connect( brokerUrl, mqttOptions );
-    } catch ( connectErr ) {
-        throw invalidConfig( `brokerUrl rejected by the MQTT client ('${redactedBrokerUrl}'): ${connectErr.message}` );
-    }
-
-    /**
-     * Fill ratio of the unacked window: unacked / maxQueueSize, capped
-     * at 1. Sync, O(1), allocation-free (ADR-018).
-     * @returns {number}
-     */
-    const getPressure = function () {
-        const ratio = state.unacked / maxQueueSize;
-        return ratio > 1 ? 1 : ratio;
-    };
-
-    /**
-     * Check and signal backpressure
-     */
-    const checkBackpressure = function () {
-        const pressure = getPressure();
-
-        if ( ( pressure > QUEUE_CRITICAL_THRESHOLD ) && onCritical ) {
-            onCritical( 'QUEUE_CRITICAL', pressure );
-        }
-
-        if ( onBackpressure ) {
-            onBackpressure( pressure );
-        }
-    };
-
-    /**
-     * Publish message immediately (fire-and-forget).
-     *
-     * Sync return per the ADR-018 sink contract:
-     * - `{ ok: true }` on successful buffer.
-     * - `{ ok: false, error: { code: 'STORAGE_FULL', message } }` if pre-flight
-     *   pressure check rejects (pressure >= STORAGE_PRESSURE_LIMIT).
-     * - `{ ok: false, error: { code: 'SHUTTING_DOWN', message } }` if called
-     *   while shutdown is in progress.
-     *
-     * Async store-write or publish failures (after the message was buffered)
-     * route through `onDeliveryFailure(err, { topic })` when supplied; without
-     * a handler the adapter surfaces the failure via `Promise.reject`,
-     * which Node logs as unhandledRejection (and v15+ exits on). Loud failure
-     * beats silent loss.
-     *
-     * @param {string} topic - MQTT topic
-     * @param {*} message - Message payload (will be encoded via config.codec)
-     * @param {Object} [options] - Per-message options
-     * @param {string} [options.type] - Message-type key for MESSAGE_EXPIRY lookup
-     * @returns {{ok: true} | {ok: false, error: {code: string, message: string}}}
-     */
-    const publishNow = function ( topic, message, options ) {
-        if ( state.shuttingDown ) {
-            return ERR_SHUTTING_DOWN;
-        }
-
-        // Pre-flight pressure check — reject above STORAGE_PRESSURE_LIMIT to
-        // leave headroom for in-flight drain and to surface backpressure to
-        // producers before the store is literally full.
-        if ( getPressure() >= STORAGE_PRESSURE_LIMIT ) {
-            return ERR_STORAGE_FULL;
-        }
-
-        // Encode BEFORE the counter moves. A message the codec cannot
-        // encode was never in flight, so it must not occupy a slot: a
-        // leaked slot never drains, pressure ratchets up, and the
-        // emitter ends up refusing everything. The
-        // refusal is synchronous and classified; building it allocates,
-        // which is fine on an error path this rare.
-        let payload;
-        try {
-            payload = config.codec.pack( message );
-        } catch ( packErr ) {
-            state.stats.encodeErrors += 1;
-            return {
-                ok: false,
-                error: {
-                    code: 'ENCODE_ERROR',
-                    message: `Message could not be encoded (topic=${topic}): ${packErr.message}`
-                }
-            };
-        }
-
-        const dedupId = crypto.randomUUID();
-        const messageType = ( options && options.type ) || 'default';
-        const expiry = MESSAGE_EXPIRY[ messageType ] || MESSAGE_EXPIRY.default;
-
-        // Per-message allocations from here to the publish call (the
-        // uuid, the properties object, the callback closure) cannot be
-        // pre-allocated and reused: mqtt.js keeps the packet — properties
-        // included — until PUBACK so it can retransmit, and a shared
-        // mutated object would corrupt every queued retransmission (the
-        // unavoidable-residual justification ADR-018 asks for).
-        const properties = {
-            messageExpiryInterval: expiry,
-            userProperties: {
-                [ WINK_NAMESPACE.dedupId ]: dedupId,
-                [ WINK_NAMESPACE.timestamp ]: Date.now().toString(),
-                [ WINK_NAMESPACE.version ]: '1.0'
-            },
-            contentType: config.codec.contentType
-        };
-
-        if ( config.codec.payloadFormatIndicator === 1 ) {
-            properties.payloadFormatIndicator = true;
-        }
-
-        // Accept: the message is now in flight. The counter rises HERE,
-        // synchronously with the accept decision, so the very next
-        // publishNow call sees the true pressure (the old design's
-        // optimistic-increment lesson, kept).
-        state.unacked += 1;
-
-        // Fire-and-forget publish with QoS 1. Outcome of this async callback is
-        // observability-only — the publishNow caller has already received a
-        // synchronous result. The callback fires exactly once per publish
-        // (acknowledgment or failure), so the decrement below is the
-        // counter's single exit — paired with the catch, which releases
-        // the slot when the client rejects the call before accepting it.
-        try {
-            client.publish(
-                topic,
-                payload,
-                { qos: QOS, properties },
-                ( err ) => {
-                    state.unacked -= 1;
-                    if ( err ) {
-                        state.stats.publishErrors += 1;
-                        const deliveryErr = new Error(
-                            `winkComposer/mqttEmitter: publish failed (topic=${topic}): ${err.message || err.code || 'unknown'}`
-                        );
-                        deliveryErr.code = 'DELIVERY_FAILED';
-                        deliveryErr.cause = err;
-                        if ( onDeliveryFailure ) {
-                            onDeliveryFailure( deliveryErr, { topic } );
-                        } else {
-                            // No handler — surface as unhandledRejection so the
-                            // process logs loudly and (Node 15+) exits. Mirrors
-                            // QuestDB's persist-plan.js catch-and-throw: both
-                            // adapters route undeclared async failures
-                            // through the same Node-level escape hatch.
-                            Promise.reject( deliveryErr );
-                        }
-                    } else {
-                        state.stats.published += 1;
-                    }
-                    checkBackpressure();
-                }
-            );
-        } catch ( publishErr ) {
-            // The client threw before accepting the message; its callback
-            // will never fire, so the slot is released here — the sync
-            // face of DELIVERY_FAILED (see the header vocabulary).
-            state.unacked -= 1;
-            state.stats.publishErrors += 1;
-            return {
-                ok: false,
-                error: {
-                    code: 'DELIVERY_FAILED',
-                    message: `MQTT publish rejected (topic=${topic}): ${publishErr.message}`
-                }
-            };
-        }
-
-        return RESULT_OK;
-    };
-
-    // Shutdown outcome, latched on the first call. A second
-    // caller used to get an instant clean resolve — mid-drain, or even
-    // after a shutdown that recorded dropped messages. Every caller now
-    // receives the first call's promise.
-    let shutdownPromise = null;
-
-    const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5000;
-
-    /**
-     * The real shutdown body. `shutdown` below latches its promise so
-     * every caller receives this one outcome.
-     *
-     * **Drain-then-close** (a sustained-load finding, kept through the
-     * ADR-021 rework): mqtt.js's own `end()` does not reliably drain
-     * in-flight publishes, so the emitter waits on its own counter.
-     *
-     *  1. Sets `state.shuttingDown` so `publishNow` rejects new work
-     *     (returns `SHUTTING_DOWN` immediately).
-     *  2. **Polls the unacked counter until zero**, using the whole
-     *     `timeout` budget — no early give-up. The wait runs whether or
-     *     not the connection is up at the moment of the call: mqtt.js
-     *     auto-reconnects, so a mid-drain reconnect can still deliver
-     *     the backlog inside the budget.
-     *  3. Once drained (or budget expired), calls `client.end(...)`
-     *     with the remaining time as the broker-DISCONNECT budget.
-     *  4. Force-closes if the broker hangs the DISCONNECT.
-     *
-     * The old design's shutdown re-drive (re-sending stragglers through
-     * a store stream scan) died with the disk store: with the memory
-     * store there is no store to scan, and a message whose PUBACK was
-     * lost in-session is re-sent by the client itself on the next
-     * reconnect. If it is still unacknowledged at the deadline, the
-     * loss report counts it.
-     *
-     * A clean resolve is a delivery statement (ADR-018). When the
-     * drain could not complete, shutdown rejects with classified
-     * `SHUTDOWN_TIMEOUT` and `dropped: { count }` — the counter's exact
-     * value — after the close has already happened (teardown first,
-     * then the report). This fires CONNECTED OR NOT: with no disk
-     * store, nothing survives the process, so a disconnected shutdown
-     * with pending messages is a real loss and is reported as one. (The
-     * wal-backed design resolved that case clean on purpose — its disk
-     * store held the messages for the next session. ADR-021 traded that
-     * away and says so.)
-     */
-    const doShutdown = async function ( timeout ) {
-        state.shuttingDown = true;
-
-        // A non-finite or non-positive timeout collapses the drain
-        // (Infinity overflows setTimeout, which clamps it to ~1 ms;
-        // NaN fails every deadline comparison), so it falls back to
-        // the default budget.
-        const budget = ( Number.isFinite( timeout ) && timeout > 0 ) ? timeout : DEFAULT_SHUTDOWN_TIMEOUT_MS;
-        const deadline = Date.now() + budget;
-        const drainPollIntervalMs = 25;
-
-        // Drain wait — one cheap counter read per tick; sequential
-        // awaits are the wait-for-condition pattern.
-        while ( Date.now() < deadline && state.unacked > 0 ) {
-            // eslint-disable-next-line no-await-in-loop
-            await new Promise( ( r ) => setTimeout( r, drainPollIntervalMs ) );
-        }
-
-        // Whatever is still unacknowledged goes undelivered — publishNow
-        // stopped accepting work at step 1, so the counter has settled
-        // into its final value. It becomes the `dropped` payload below.
-        const undeliveredCount = state.unacked;
-        const remaining = Date.now() - deadline;
-        const closeBudget = remaining < 0 ? Math.abs( remaining ) : 1;
-
-        await new Promise( ( resolve ) => {
-            const forceTimer = setTimeout( () => {
-                client.end( true );
-                resolve();
-            }, closeBudget );
-
-            if ( state.connected ) {
-                client.end( false, {}, () => {
-                    clearTimeout( forceTimer );
-                    resolve();
-                } );
-            } else {
-                clearTimeout( forceTimer );
-                client.end( true );
-                resolve();
-            }
-        } );
-
-        // Teardown first, then the report: the close has already happened;
-        // an incomplete drain must not read as a clean one (ADR-018).
-        if ( undeliveredCount > 0 ) {
-            const err = new Error(
-                `winkComposer/mqttEmitter: shutdown closed with ${undeliveredCount} message(s) unacknowledged`
-            );
-            err.code = 'SHUTDOWN_TIMEOUT';
-            err.dropped = { count: undeliveredCount };
-            throw err;
-        }
-        return undefined;
-    }; // doShutdown()
+    const client = openClient( resolved );
 
-    /**
-     * Graceful shutdown — drain semantics with a timeout floor.
-     *
-     * Accepts the ADR-018 shutdown-contract shape `{ timeout }` (defaults to
-     * 5000ms). The destructure with `= {}` lets callers invoke
-     * `shutdown()` with no argument, `shutdown( {} )`, or
-     * `shutdown( { timeout: N } )`.
-     *
-     * The outcome is latched: the first call runs the shutdown, every
-     * later call returns the same promise. A caller
-     * arriving mid-drain waits for the real teardown; a caller arriving
-     * after a lossy shutdown sees the same classified rejection, never
-     * a contradicting clean resolve. One consequence: the first
-     * caller's `{ timeout }` governs; a later caller's is ignored.
-     *
-     * @param {{timeout?: number}} [options]
-     * @returns {Promise<void>}
-     */
-    const shutdown = function ( { timeout = DEFAULT_SHUTDOWN_TIMEOUT_MS } = {} ) {
-        if ( !shutdownPromise ) {
-            shutdownPromise = doShutdown( timeout );
-        }
-        return shutdownPromise;
-    }; // shutdown()
-
-    // Connection handlers - minimal, no automatic status
-    client.on( 'connect', () => {
-        state.connected = true;
-        // mqtt.js fires 'connect' on every connack, including mid-run
-        // reconnects. Counting the later ones gives operators — and the
-        // release-soak signature policy — an observable "a reconnect
-        // happened during this run" fact via getHealth().stats.
-        if ( state.hasConnectedOnce ) {
-            state.stats.reconnects += 1;
-        }
-        state.hasConnectedOnce = true;
-        if ( config.debug ) {
-            logger.info( `winkComposer/mqttEmitter: Connected to ${redactedBrokerUrl}` );
-        }
+    const { getPressure, checkCritical, checkBackpressure, getHealth } = createHealth( {
+        state,
+        maxQueueSize: resolved.maxQueueSize,
+        onCritical: resolved.onCritical,
+        onBackpressure: resolved.onBackpressure
     } );
-
-    client.on( 'offline', () => {
-        state.connected = false;
-        if ( config.debug ) {
-            logger.info( `winkComposer/mqttEmitter: Offline - ${state.unacked} messages in flight` );
-        }
+    const publishNow = createPublishNow( {
+        client,
+        state,
+        codec: resolved.codec,
+        getPressure,
+        checkCritical,
+        checkBackpressure,
+        onDeliveryFailure: resolved.onDeliveryFailure
     } );
-
-    client.on( 'error', ( err ) => {
-        state.stats.errors += 1;
-        if ( config.debug ) {
-            logger.error( `winkComposer/mqttEmitter: client error: ${err.message}` );
-        }
+    const { flush, shutdown } = createShutdown( { client, state } );
+
+    // The permanent handlers attach before the grace wait's one-shot
+    // listener, so a handle resolved via connack already reports
+    // `connected: true`.
+    attachConnectionHandlers( {
+        client,
+        state,
+        debug: resolved.debug,
+        redactedBrokerUrl: resolved.redactedBrokerUrl
     } );
 
-    /**
-     * Health snapshot for operator monitoring (uniform across sinks).
-     *
-     * Returns the ADR-018 health floor `{status, connected, pressure}` plus
-     * this adapter's own `stats` addition. `stats.unacked` is the live
-     * counter — the number of messages
-     * accepted but not yet acknowledged by the broker; exactly what a
-     * process crash at this instant would cost (ADR-021).
-     *
-     * Status derivation (uniform with Terminal/QuestDB; see file header):
-     * - `red`    when `!connected`
-     * - `yellow` when connected AND `pressure >= HEALTH_PRESSURE_YELLOW_THRESHOLD`
-     * - `green`  otherwise
-     *
-     * The wal-backed design's `storeHealth`, `circuitState`, and `metrics`
-     * diagnostics died with the LevelDB store (ADR-021).
-     *
-     * @returns {Object} Health snapshot — required floor + live counter
-     */
-    const getHealth = function () {
-        const pressure = getPressure();
-
-        let status;
-        if ( !state.connected ) {
-            status = 'red';
-        } else if ( pressure >= HEALTH_PRESSURE_YELLOW_THRESHOLD ) {
-            status = 'yellow';
-        } else {
-            status = 'green';
-        }
-
-        return {
-            // Required floor (ADR-018)
-            status,
-            connected: state.connected,
-            pressure,
-            // This adapter's addition beyond the floor
-            stats: { ...state.stats, unacked: state.unacked }
-        };
-    };
-
     const handle = {
         publishNow,
+        flush,
         getHealth,
         shutdown,
         getPressure
     };
 
-    // First-connack grace (bounded). With a grace, the return is a
-    // Promise the wiring layer awaits (ADR-018 allows sync or async
-    // factories): by the time wire() hands the emitter to the flow,
-    // the client has either seen its first connack or spent the
-    // budget. Expiry is not an error — the posture stays 'recovering'.
-    // With connectGraceMs 0 the handle returns synchronously, exactly
-    // the pre-grace behavior. The permanent 'connect' handler above is
-    // attached before the wait's one-shot listener, so a handle
-    // resolved via connack already reports `connected: true`.
-    if ( connectGraceMs === 0 ) {
-        return handle;
+    // First-connack grace (bounded). By the time wire() hands the
+    // emitter to the flow, the client has either seen its first
+    // connack or spent the budget. Expiry is not an error — the
+    // posture stays 'recovering'. With connectGraceMs 0 no wait is
+    // armed and the promise resolves at once.
+    if ( resolved.connectGraceMs > 0 ) {
+        await waitForFirstConnect( client, resolved.connectGraceMs );
     }
-    return waitForFirstConnect( client, connectGraceMs ).then( () => handle );
-}; // createMQTTEmitter()
+    return handle;
+}; // createEmitter()