@winkjs/composer 0.6.0 → 0.8.0

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

@@ -0,0 +1,312 @@
+// core/emitter-manager/mqtt/resolve-config.js
+
+/**
+ * @fileoverview Resolves and validates the MQTT emitter's configuration
+ * before the factory opens anything (ADR-018, fail-fast setup).
+ *
+ * The factory in `emitter.js` calls `resolveConfig` once. Every
+ * refusal here is a classified `INVALID_CONFIG` TypeError. The checks
+ * run in one fixed order: the broker URL, the address policy, the
+ * codec, the three callbacks, the grace, the queue size, and the will.
+ * The factory is async, so a caller sees each refusal as a rejection.
+ *
+ * The module also arms the three notification callbacks through the
+ * shared callback guard. A user throw inside the publish ack chain
+ * then becomes one `CALLBACK_FAILED` line instead of a fault inside
+ * mqtt.js (ADR-018, ADR-027).
+ *
+ * Nothing here runs on the message path. Every value is resolved once
+ * and captured by the closures the other modules build.
+ *
+ * @see ADR-018
+ * @see ADR-021
+ * @see ADR-030
+ */
+
+import mqtt from 'mqtt';
+import { ENV_VARS } from '../../env-vars.js';
+import {
+    QOS,
+    MQTT_CONFIG,
+    DEFAULT_MAX_QUEUE_SIZE,
+    MQTT_INFLIGHT_ID_LIMIT
+} from './constants.js';
+import { wrapCallback } from '../../utils/callback-guard/index.js';
+import { jitteredPeriod } from '../../utils/jitter/index.js';
+import { logger } from '../../logger/index.js';
+import { classifyAddress, localhostRefusalMessage } from '../../utils/address/index.js';
+
+/**
+ * Build a config-error TypeError tagged for ADR-018 fail-fast setup routing.
+ * @param {string} message
+ * @returns {TypeError}
+ */
+export const invalidConfig = function ( message ) {
+    const err = new TypeError( 'winkComposer/mqttEmitter: ' + message );
+    err.code = 'INVALID_CONFIG';
+    return err;
+};
+
+/**
+ * Classifies the broker address and refuses `localhost` (ADR-030).
+ * The schema already refused it at flow definition; this call covers
+ * the `MQTT_BROKER_URL` fallback and direct callers, and carries the
+ * classified code.
+ *
+ * @param {string} brokerUrl - The broker URL, config or env fallback
+ * @returns {Object} The classified address
+ * @throws {TypeError} INVALID_CONFIG when the host is `localhost`
+ */
+const assertBrokerNotLocalhost = function ( brokerUrl ) {
+    const address = classifyAddress( brokerUrl, 'url' );
+    if ( address.kind === 'localhost' ) {
+        throw invalidConfig( localhostRefusalMessage( { field: 'brokerUrl', address, envVar: 'MQTT_BROKER_URL' } ) );
+    }
+    return address;
+}; // assertBrokerNotLocalhost()
+
+/**
+ * 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.
+ *
+ * @param {Object} will - config.will as supplied
+ * @param {Object} codec - config.codec (pack + contentType)
+ * @returns {Object} the mqtt.js connect-options `will` object
+ */
+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;
+};
+
+/**
+ * Resolves the broker URL from config or the env fallback, refuses an
+ * empty one, and applies the address policy.
+ *
+ * `??` so explicit '' is the user's choice (not "fall back to env");
+ * `.trim()` rejects whitespace-only. Symmetric with QuestDB, which
+ * throws on `ilpUrl: ''`. Broker URLs may carry credentials
+ * (mqtt://user:pass@host), so the redacted form is built here for
+ * every later log line.
+ *
+ * @param {Object} config - emitter config
+ * @returns {{brokerUrl: string, brokerAddress: Object, redactedBrokerUrl: string}}
+ */
+const resolveBrokerUrl = function ( config ) {
+    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' );
+    }
+    // Address policy (ADR-030): `localhost` is refused before the
+    // client is created; a name is warned about just before connect.
+    const brokerAddress = assertBrokerNotLocalhost( brokerUrl );
+    const redactedBrokerUrl = brokerUrl.replace( /\/\/[^@/]*@/, '//***@' );
+    return { brokerUrl, brokerAddress, redactedBrokerUrl };
+}; // resolveBrokerUrl()
+
+/**
+ * Refuses a missing codec or one without `pack()`.
+ * @param {Object} codec - config.codec
+ */
+const assertCodec = function ( codec ) {
+    if ( !codec ) {
+        throw invalidConfig( 'config.codec is required' );
+    }
+    if ( typeof codec.pack !== 'function' ) {
+        throw invalidConfig( 'config.codec must have a pack() function' );
+    }
+}; // assertCodec()
+
+/**
+ * Validates the three notification callbacks and arms them through
+ * the shared callback guard.
+ *
+ * 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 keeps its exact meaning. That includes the
+ * deliberate unhandled-rejection escape hatch for an unhandled
+ * delivery failure.
+ *
+ * @param {Object} config - emitter config
+ * @returns {{onDeliveryFailure: function|null, onCritical: function|null, onBackpressure: function|null}}
+ */
+const armCallbacks = function ( config ) {
+    assertOptionalCallback( config.onDeliveryFailure, 'onDeliveryFailure' );
+    assertOptionalCallback( config.onCritical, 'onCritical' );
+    assertOptionalCallback( config.onBackpressure, 'onBackpressure' );
+
+    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
+    } );
+    return { onDeliveryFailure, onCritical, onBackpressure };
+}; // armCallbacks()
+
+/**
+ * Resolves the first-connack grace: explicit config → MQTT_CONNECT_GRACE_MS
+ * env fallback → 500 ms default (ADR-018 precedence; the fallback lives
+ * here, 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.
+ *
+ * @param {Object} config - emitter config
+ * @returns {number} the grace in milliseconds, 0 for no wait
+ */
+const resolveGrace = function ( config ) {
+    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' );
+    }
+    return connectGraceMs;
+}; // resolveGrace()
+
+/**
+ * Resolves 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).
+ *
+ * @param {Object} config - emitter config
+ * @returns {number} the effective cap
+ */
+const resolveQueueSize = function ( config ) {
+    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}`
+        );
+    }
+    return Math.min( requestedQueueSize, MQTT_INFLIGHT_ID_LIMIT );
+}; // resolveQueueSize()
+
+/**
+ * Builds the mqtt.js connect 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.
+ *
+ * @param {Object} config - emitter config
+ * @returns {Object} the options handed to `mqtt.connect`
+ */
+const buildClientOptions = function ( config ) {
+    // Generate unique client ID if not provided
+    const clientId = config.clientId || `wink-${Date.now()}-${Math.random().toString( 36 ).slice( 2, 9 )}`;
+
+    const mqttOptions = {
+        ...MQTT_CONFIG,
+        clientId,
+        // The configured period plus a random share of up to 20%,
+        // drawn once here, so a fleet that lost one broker does not
+        // retry in step. The configured period is the floor.
+        reconnectPeriod: jitteredPeriod( MQTT_CONFIG.reconnectPeriod ),
+        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 );
+    }
+    return mqttOptions;
+}; // buildClientOptions()
+
+/**
+ * Resolves the whole configuration in the factory's fixed order.
+ * Every refusal is a classified `INVALID_CONFIG` throw, and no check
+ * has a side effect beyond the clamp warning.
+ *
+ * @param {Object} config - emitter config (see configSchema in index.js)
+ * @returns {Object} the resolved values the factory hands to its modules
+ */
+export const resolveConfig = function ( config ) {
+    const { brokerUrl, brokerAddress, redactedBrokerUrl } = resolveBrokerUrl( config );
+    assertCodec( config.codec );
+    const { onDeliveryFailure, onCritical, onBackpressure } = armCallbacks( config );
+    const connectGraceMs = resolveGrace( config );
+    const maxQueueSize = resolveQueueSize( config );
+    const mqttOptions = buildClientOptions( config );
+
+    return {
+        brokerUrl,
+        brokerAddress,
+        redactedBrokerUrl,
+        codec: config.codec,
+        onDeliveryFailure,
+        onCritical,
+        onBackpressure,
+        connectGraceMs,
+        maxQueueSize,
+        mqttOptions,
+        // Injectable for testing (ADR-018 module surface keeps this
+        // out of the schema's documented options).
+        connect: config.mqttConnectFn || mqtt.connect,
+        debug: Boolean( config.debug )
+    };
+}; // resolveConfig()

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

@@ -0,0 +1,247 @@
+// core/emitter-manager/mqtt/shutdown-drain.js
+
+/**
+ * @fileoverview The drain of the MQTT emitter: `flush()` and the
+ * drain-then-close `shutdown()` (ADR-018 §6 and §7, ADR-021).
+ *
+ * A clean shutdown resolve is a delivery statement: every accepted
+ * message reached a settled outcome before the client closed. The
+ * drain is a wait on the emitter's own unacked counter, because
+ * mqtt.js's own `end()` does not reliably drain in-flight publishes
+ * (a sustained-load finding, kept through the ADR-021 rework).
+ *
+ * `flush()` runs the same wait and nothing else. It closes nothing and
+ * refuses no new work. It resolves when the counter reaches zero
+ * within its budget. When the budget passes first it rejects with
+ * `DELIVERY_FAILED` and `pending: { count }`, the code QuestDB's
+ * flush uses when its own deadline passes. The messages stay in
+ * flight; a later acknowledgment still settles them.
+ *
+ * The shutdown outcome is latched on the first call. Every later
+ * caller receives the same promise, so a second call can never
+ * contradict the first with an instant clean resolve.
+ *
+ * The budget reads a monotonic clock. A wall-clock correction during
+ * a drain would otherwise shorten or lengthen the wait by the size of
+ * the step.
+ *
+ * How the close detaches (ADR-018 §7). A graceful `end( false )` waits
+ * for the client's outgoing map to empty, which a lossy drain cannot
+ * deliver. So when rows remain, or the link is down, the close is
+ * forced at once: the library destroys the stream and the keepalive
+ * timer. A forced close sends no DISCONNECT packet. With a clean
+ * session and an in-memory store, nothing is lost that the drain had
+ * not already lost. When the drain finished on a live link, the close
+ * is graceful, and a timer bounds it. That timer destroys the stream
+ * directly, the call the library's own connack timeout makes, because
+ * a second `end()` returns at once behind the library's
+ * `disconnecting` flag (mqtt.js 5.15.1, `client.js:731-734`).
+ *
+ * @see ADR-018
+ * @see ADR-021
+ */
+
+import { performance } from 'node:perf_hooks';
+
+/**
+ * The graceful close, bounded by a timer. The library sends DISCONNECT
+ * and half-closes the socket. A broker that never answers leaves the
+ * socket half-open for ever, so at the deadline the timer destroys the
+ * stream itself. The timer runs outside every promise, so a throw
+ * there would end the process; it is counted instead.
+ *
+ * @param {Object} client - mqtt.js client
+ * @param {Object} state - The emitter's core state, for the error count
+ * @param {number} closeBudget - Milliseconds the broker gets to answer
+ * @returns {Promise<void>} resolves when the client closed or the timer fired
+ */
+const closeGracefully = function ( client, state, closeBudget ) {
+    return new Promise( ( resolve ) => {
+        const forceTimer = setTimeout( () => {
+            try {
+                client.stream.destroy();
+            } catch {
+                state.stats.errors += 1;
+            }
+            resolve();
+        }, closeBudget );
+
+        client.end( false, {}, () => {
+            clearTimeout( forceTimer );
+            resolve();
+        } );
+    } );
+}; // closeGracefully()
+
+/** The drain budget when the caller gives none, in milliseconds. */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5000;
+
+/** One cheap counter read per tick of the drain wait. */
+const DRAIN_POLL_INTERVAL_MS = 25;
+
+/**
+ * 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.
+ *
+ * @param {*} timeout - The caller's timeout
+ * @returns {number} a positive finite budget in milliseconds
+ */
+const resolveBudget = function ( timeout ) {
+    return ( Number.isFinite( timeout ) && timeout > 0 ) ? timeout : DEFAULT_SHUTDOWN_TIMEOUT_MS;
+}; // resolveBudget()
+
+/**
+ * Builds `flush` and the latched `shutdown` over the shared state.
+ *
+ * @param {Object} deps
+ * @param {Object} deps.client - mqtt.js client
+ * @param {Object} deps.state - The emitter's core state
+ * @returns {{flush: function, shutdown: function}}
+ */
+export const createShutdown = function ( { client, state } ) {
+    // 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;
+
+    /**
+     * Waits for the unacked counter to reach zero, up to the budget.
+     * The deadline reads a monotonic clock, so a wall-clock step cannot
+     * move it. Sequential awaits are the wait-for-condition pattern.
+     *
+     * @param {number} budget - Milliseconds to wait, positive and finite
+     * @returns {Promise<number>} the milliseconds left in the budget, negative when it ran out
+     */
+    const waitForDrain = async function ( budget ) {
+        const deadline = performance.now() + budget;
+        while ( ( performance.now() < deadline ) && ( state.unacked > 0 ) ) {
+            // eslint-disable-next-line no-await-in-loop
+            await new Promise( ( r ) => setTimeout( r, DRAIN_POLL_INTERVAL_MS ) );
+        }
+        return deadline - performance.now();
+    }; // waitForDrain()
+
+    /**
+     * Waits for every accepted message to settle, without closing the
+     * client or refusing new work (ADR-018 §6).
+     *
+     * @param {{timeout?: number}} [options] - The budget, default 5000 ms
+     * @returns {Promise<void>} resolves when nothing is unacknowledged
+     * @throws {Error} DELIVERY_FAILED with `pending: { count }` when the budget passes first
+     */
+    const flush = async function ( { timeout = DEFAULT_SHUTDOWN_TIMEOUT_MS } = {} ) {
+        const budget = resolveBudget( timeout );
+        await waitForDrain( budget );
+        if ( state.unacked > 0 ) {
+            const err = new Error(
+                `winkComposer/mqttEmitter: flush ended with ${state.unacked} message(s) unacknowledged [DELIVERY_FAILED]: no acknowledgment within ${budget} ms`
+            );
+            err.code = 'DELIVERY_FAILED';
+            err.pending = { count: state.unacked };
+            throw err;
+        }
+    }; // flush()
+
+    /**
+     * 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. With the
+     *     default 5 s budget and 5 s reconnect period, at most one
+     *     reconnect attempt can land inside the drain, and a connect
+     *     that hangs cannot complete within it (the connect timeout is
+     *     30 s).
+     *  3. Once drained on a live link, calls `client.end( false )` with
+     *     the remaining time as the broker-DISCONNECT budget. With rows
+     *     still unacknowledged, or the link down, calls
+     *     `client.end( true )` at once instead.
+     *  4. If the broker hangs the DISCONNECT, the timer destroys the
+     *     stream directly (see the file header).
+     *
+     * 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;
+
+        const remaining = await waitForDrain( resolveBudget( timeout ) );
+
+        // 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 closeBudget = remaining > 0 ? remaining : 1;
+
+        if ( ( undeliveredCount > 0 ) || !state.connected ) {
+            // Forced: the library destroys the stream and the keepalive
+            // at once, and the call returns synchronously.
+            client.end( true );
+        } else {
+            await closeGracefully( client, state, closeBudget );
+        }
+
+        // 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()
+
+    /**
+     * 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()
+
+    return { flush, shutdown };
+}; // createShutdown()

package/src/core/emitter-manager/terminal/index.js

@@ -21,6 +21,9 @@
  * - `getPressure()` returns `0` — Terminal has no observable buffer (stdout drains
  *   to the kernel); a trivial sink meets the pressure obligation with a
  *   constant 0 (ADR-018).
+ * - `flush()` resolves at once, for the same reason. It is on the handle
+ *   because the wiring layer requires the whole sink floor of every
+ *   emitter (ADR-018 §6).
  * - `getHealth()` returns `{ status: 'green', connected: true, pressure: 0 }` —
  *   Terminal is always healthy and always "connected" to stdout (there is no
  *   connection to lose). Uniform semantics with MQTT emitter / QuestDB.
@@ -237,7 +240,7 @@ const formatVerbose = function ( msg, formatValue ) {
  *   the global `precision` config. Without an asset class entirely,
  *   every column falls back — the original global-precision behaviour,
  *   unchanged.
- * @returns {Object} Emitter instance with publishNow, getPressure, getHealth, shutdown
+ * @returns {Object} Emitter instance with publishNow, flush, getPressure, getHealth, shutdown
  */
 export const createEmitter = function ( config = {} ) {
     const {
@@ -305,6 +308,18 @@ export const createEmitter = function ( config = {} ) {
             return 0;
         },
 
+        /**
+         * No-op flush (the sink floor, ADR-018 §6). Terminal has nothing
+         * buffered to wait for: stdout drains to the kernel without our
+         * help. The unused option keeps the same shape as `shutdown`.
+         *
+         * @param {{timeout?: number}} [_options]
+         * @returns {Promise<void>}
+         */
+        flush: async function ( { timeout: _timeout = 0 } = {} ) {
+            // Nothing to wait for.
+        },
+
         /**
          * Health snapshot for operator monitoring. Terminal is always healthy
          * and always "connected" to stdout — there is no transport state to