@winkjs/composer 0.5.1 → 0.7.0

package/src/core/storage-manager/questdb/index.js

@@ -1,64 +1,134 @@
 // core/storage-manager/questdb/index.js
 
 /**
- * @fileoverview QuestDB storage adapter for time-series data persistence.
- *
- * Creates storage interface that integrates with partition-manager:
- * - ensureTables: Creates tables via PostgreSQL wire protocol at startup
- * - write(insightType, msg, partitionId): Writes row via ILP, sync return
- *   per the ADR-018 sink contract — `{ ok: true }` on success,
- *   `{ ok: false, error: { code, message } }` on failure.
- * - flush(): Manual flush (in manual mode) or no-op (in auto mode)
- * - shutdown(): Graceful shutdown
- * - getPressure(): Buffer fill ratio in [0, 1] per ADR-018 (sync, O(1),
- *   allocation-free).
- *
- * Two flush modes:
- * - auto: QuestDB client handles flushing based on rows/interval
- * - manual: Application controls flush timing via idle timer
- *
- * Adapter contract (ADR-018, structured-sink role):
- * - Module-level exports per the ADR-018 module surface: `id`, `configSchema`,
- *   `createStorage`, `durabilityClass`, `semanticsRequirement`, and the
- *   default aggregate (`questdbAdapter`) referencing the same constants.
- * - Durability class (ADR-018): `'in-memory'` — rows accepted by `write()`
- *   live in the ILP client's in-process buffer until a flush reaches the
- *   server.
- *   A process crash loses every un-flushed row; the shutdown drain and
- *   its classified loss reporting exist precisely to shrink that window.
- * - Hot-path `write` returns sync per ADR-013; the partition-manager never
- *   awaits a Promise on the per-message path.
- * - `getPressure()` returns `(bufferedRows + inFlightRows) / autoFlushRows`,
- *   clamped to 1.0. `bufferedRows` counts rows awaiting the next flush and
- *   increments synchronously when the persist plan opens a row; a flush call
- *   moves its rows to `inFlightRows` (the client copies them out of the
- *   buffer synchronously — copy-out), where they stay until the flush
- *   settles. In auto mode the counter mirrors QuestDB's internal flush
- *   trigger via a heuristic reset at the `autoFlushRows` boundary; the
- *   `auto_flush_interval` trigger is not directly observable but self-heals
- *   via `checkIdleFlush` after `idleFlushAfterMs` of write-idle.
- *
- * Health-status semantics (uniform across sinks):
- * - `getHealth()` returns `{status, connected, pressure, ...}` — the ADR-018
- *   health floor.
- * - `connected = !shuttingDown && consecutiveWriteErrors < HEALTH_ERROR_RED_THRESHOLD`.
- *   QuestDB has no persistent connection state to inspect (ILP sender is
- *   fire-and-forget); `connected` is *derived* from recent write success.
- * - Status derivation:
- *     `red`    if `!connected` (transport unhealthy or shutting down)
- *     `yellow` if `pressure >= 0.66` (threshold shared with ADR-020's
- *                  Draft yield proposal) OR
- *                  `consecutiveWriteErrors >= 1` (any error elevates concern)
- *     `green`  otherwise
- * - The counter resets to 0 on every successful write, so a single recovery
- *   write returns `status` to `green`.
+ * @fileoverview QuestDB storage adapter. It writes rows to QuestDB over
+ * ILP (InfluxDB Line Protocol) on HTTP, and creates the tables over the
+ * PostgreSQL wire protocol at startup.
+ *
+ * Contract role (ADR-018): storage, buffered. Startup posture: eager.
+ * Setup throws when either endpoint does not answer, so a flow never
+ * starts against a dead database.
+ *
+ * Module layout. This file holds the factory, the config schema, and
+ * the adapter export. The work lives in four modules next to it:
+ * - `resolve-options.js` merges the config and the environment into
+ *   the settings, and derives the ceiling and the deadline.
+ * - `address-policy.js` holds the ADR-030 address checks, the setup
+ *   probe wrapper, and the classification of a connect failure.
+ * - `flush-engine.js` owns the hot path, every flush, the counters
+ *   behind pressure and health, and the shutdown drain (ADR-029).
+ * - `persist-plan.js` compiles one row writer per insight type.
+ *
+ * The handle the factory returns:
+ * - `write(insightType, msg, partitionId)`: the hot path. Appends one
+ *   row to the client's buffer and returns at once. `{ ok: true }`
+ *   means accepted into the buffer, not delivered. `{ ok: false,
+ *   error: { code, message } }` names the refusal. Never throws.
+ * - `flush()`: sends everything buffered now. Resolves when the server
+ *   confirmed the rows, rejects when it did not.
+ * - `shutdown({ timeout })`: drain, then close. A clean resolve means
+ *   every row was delivered. A loss is a classified rejection.
+ * - `getPressure()`: buffer fill in [0, 1]. Sync, O(1), no allocation.
+ * - `getHealth()`: `{ status, connected, pressure, ... }`.
+ * `flush-engine.js` documents how each one behaves.
+ *
+ * Composer owns every flush (ADR-029). The client's own trigger is
+ * off (`auto_flush=off`), so a batch leaves the process only when the
+ * engine says so. A write that brings the buffer to `flushRows` starts
+ * a flush at once. A timer starts a flush every `flushIntervalMs` when
+ * anything is buffered. Only one engine flush runs at a time. A failed
+ * flush is reported once, with the exact rows lost, and the process
+ * keeps running. Every flush has a deadline, derived from the rows it
+ * carries, and a flush past it is abandoned and reported. A failed or
+ * abandoned flush runs the ADR-030 probe. While the probe fails,
+ * delivery pauses: rows are held up to the ceiling and each tick
+ * probes again. `flush-engine.js` carries the detail.
+ *
+ * Row order. Rows reach QuestDB in write order. The engine runs one
+ * flush at a time, each flush carries its rows in write order, and
+ * the standard-library transport keeps one socket (`maxSockets: 1`),
+ * so a later request waits for the earlier one. Two sends can be
+ * outstanding only at shutdown, when the drain's final flush starts
+ * while an earlier flush is still on the wire. On the undici
+ * transport those two batches can land out of order. QuestDB orders
+ * each table by its designated timestamp, so a query never sees the
+ * difference.
+ *
+ * Durability in plain words (ADR-018). `durabilityClass` is
+ * `'in-memory'`. Rows live in the client's buffer until a flush reaches
+ * the server. Three things lose rows: a process crash loses everything
+ * buffered or in flight, a failed flush loses its batch, and the
+ * ceiling sheds new rows. The shed policy: once the rows buffered plus
+ * the rows in flight reach `bufferCeilingRows`, `write()` refuses new
+ * rows with `STORAGE_FULL` and the rows already accepted stay safe.
+ * Outage budget with the defaults: the ceiling of 50,000 rows holds
+ * 50 seconds at 1,000 rows a second and about 14 hours at one row a
+ * second, in 6.5 to 15 MB of memory at the measured 130 to 290 bytes
+ * a row.
+ *
+ * Edge-baseline defaults (every one runs within a 2 GB device):
+ *
+ *   | Setting             | Default          | Environment variable         |
+ *   |---------------------|------------------|------------------------------|
+ *   | `flushRows`         | 5000             | `QUESTDB_FLUSH_ROWS`         |
+ *   | `flushIntervalMs`   | 1000             | `QUESTDB_FLUSH_INTERVAL_MS`  |
+ *   | `bufferCeilingRows` | 10 × `flushRows` | `QUESTDB_BUFFER_CEILING_ROWS`|
+ *   | `flushDeadlineMs`   | derived per flush| `QUESTDB_FLUSH_DEADLINE_MS`  |
+ *   | `stdlibHttp`        | true             | `QUESTDB_STDLIB_HTTP`        |
+ *   | `requestTimeout`    | client default   | `QUESTDB_REQUEST_TIMEOUT`    |
+ *   | `retryTimeout`      | client default   | `QUESTDB_RETRY_TIMEOUT`      |
+ *   | `initBufSize`       | client default   | `QUESTDB_INIT_BUF_SIZE`      |
+ *   | `maxBufSize`        | client default   | `QUESTDB_MAX_BUF_SIZE`       |
+ *
+ *   `resolve-options.js` merges the config and the environment and
+ *   explains each default. `ilpUrl` and `pgUrl` fall back to
+ *   `QUESTDB_ILP_URL` and `QUESTDB_PG_URL`; the credentials come from
+ *   `QUESTDB_DATABASE`, `QUESTDB_USER` and `QUESTDB_PASSWORD`.
+ *
+ * Long-running commitments (ADR-018 §12). One timer, created at setup
+ * and cleared at shutdown; it does not hold the process open. Every
+ * counter is bounded by the ceiling. The per-row path allocates
+ * nothing beyond the one derived promise `persist-plan.js` documents.
+ * Reconnection and request retries belong to the client. No listeners
+ * are attached. `flush-engine.js` carries the detail.
+ *
+ * The transport (ADR-029). The client's default HTTP library, undici,
+ * retries a refused connection without end, and its abort cannot end
+ * that retry. So the adapter selects the client's standard-library
+ * transport (`stdlib_http=on`) unless `stdlibHttp` is false. With it, a refused connection rejects at once and every
+ * request ends within `retryTimeout` plus one request timeout. The
+ * adapter owns one `http.Agent` for that transport, keep-alive on one
+ * socket, and destroys it after the sender closes on every shutdown
+ * path. Destroying the agent ends a request still on its socket, so
+ * the process can exit. The agent also closes its socket after 4
+ * seconds idle, before QuestDB's own idle close at 5 minutes, so no
+ * flush meets a socket the server has just closed. An operator who
+ * selects undici accepts that an abandoned flush can keep the process
+ * alive.
+ *
+ * Health (ADR-018 §8). `status` is `red` when not connected or at
+ * capacity. It is `yellow` at `pressure >= 0.66`, on an outstanding
+ * write error, or after one failed flush. Otherwise it is `green`.
+ * `connected` is derived, because the ILP client exposes no socket
+ * state. It is false while delivery is paused, after five write errors
+ * in a row, after two failed flushes in a row, or after one abandoned
+ * flush. The health object carries `pausedSince`, `abandonedFlushes`,
+ * `consecutiveFlushFailures`, `lastFlushAt`, and `lastFlushError`.
+ * `flush-engine.js` documents the derivation.
+ *
+ * Deprecated options (ADR-029, removed in 0.8.0). `autoFlushRows` maps
+ * to `flushRows` and `idleFlushCheckMs` maps to `flushIntervalMs`.
+ * `flushMode`, `idleFlushAfterMs` and `autoFlushIntervalMs` are
+ * accepted and ignored. The same holds for their `QUESTDB_*`
+ * variables. Setup prints one `DEPRECATED_OPTION` line naming every
+ * legacy key in use and what happened to it.
  *
  * `err.code` vocabulary (per-adapter; ADR-018 has each adapter document
  * its own codes in this header):
  *
  * Setup-time throws (ADR-018 fail-fast setup):
  * - `INVALID_CONFIG`         — the supplied configuration does not
- *   work. Five current sub-cases:
+ *   work. Ten current sub-cases:
  *     (a) required transport URL missing (`ilpUrl`, `pgUrl`);
  *     (b) PostgreSQL endpoint answered but rejected the connection
  *         — wrong credentials or a protocol-level refusal;
@@ -72,18 +142,57 @@
  *         of wedging the sender mid-row at runtime;
  *     (e) an insightType uses the reserved column name `assetId`.
  *         Composer writes that column itself, from the partition id.
- *         Checked at plan build in `persist-plan.js`.
+ *         Checked at plan build in `persist-plan.js`;
+ *     (f) `ilpUrl` or `pgUrl` names `localhost` (ADR-030). The name
+ *         can resolve to two addresses, `::1` and `127.0.0.1`, and
+ *         QuestDB may listen on only one. Refused before any socket
+ *         opens, at the schema (flow definition) and here (the env
+ *         fallback and direct callers). The message names the
+ *         literal to set;
+ *     (g) `ilpUrl` is an IPv6 literal. The client (4.2.0) splits the
+ *         address on its first colon and cannot read one. `pgUrl`
+ *         accepts `[::1]:8812`;
+ *     (h) the ILP client rejected the sender configuration for a
+ *         reason that is not a network error (`fromConfig`);
+ *     (i) `bufferCeilingRows` is below twice `flushRows` (ADR-029).
+ *         Rows in flight count against the ceiling, so it must hold
+ *         one batch in flight and one batch buffering. A smaller
+ *         ceiling would refuse every row that arrives during a
+ *         row-triggered flush. Checked in `resolve-options.js`;
+ *     (j) `tablePrefix` is not an identifier: letters, digits, `_`
+ *         and `$`, not starting with a digit. The prefix opens every
+ *         table name, and `ensure-tables.js` writes that name unquoted
+ *         in CREATE TABLE. QuestDB reads an unquoted name as one
+ *         token. So a hyphen, a space, a dot, a semicolon or a
+ *         backtick ends the statement early with "unexpected token"
+ *         (verified live on 9.4.3). QuestDB's own rule for a quoted
+ *         name is wider. Its CREATE TABLE reference says a name with
+ *         a space or a dot must be double-quoted. The server's
+ *         `TableUtils.isValidTableName` forbids `? , ' " \ / : ( ) +
+ *         * % ~`, control characters, and a leading or trailing dot
+ *         or space. Sources: https://questdb.com/docs/query/sql/create-table/
+ *         and https://questdb.com/docs/connect/compatibility/ilp/advanced-settings/.
+ *         The identifier rule is the one the semantics schema applies
+ *         to asset class, insight type and column names, so every
+ *         part of a table name follows one rule. Checked at the
+ *         schema and here, which covers the default prefix (the asset
+ *         class name) and a direct caller.
  *   Operator remediation: fix the supplied config or the relevant
- *   `QUESTDB_*` env var. The underlying transport error (sub-case b)
- *   is preserved on `err.cause` for diagnostics.
- * - `TRANSPORT_UNREACHABLE`  — the PostgreSQL endpoint did not answer
- *   at setup: nothing listening on the port, host unresolvable, no
- *   route, or the attempt timed out (a Node syscall code —
- *   `ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, ...). Distinct from
- *   `INVALID_CONFIG` per the one split the ADR-018 error vocabulary
- *   mandates: the
- *   connection string may be fine — check the network, the firewall,
- *   whether QuestDB is running. Underlying error on `err.cause`.
+ *   `QUESTDB_*` env var. The underlying error (sub-cases b and h) is
+ *   preserved on `err.cause` for diagnostics.
+ * - `TRANSPORT_UNREACHABLE`  — an endpoint did not answer at setup.
+ *   Three sources. (1) The setup probe (ADR-030 item 4): before any
+ *   client is built, `pgUrl` and then `ilpUrl` are probed with one
+ *   TCP connect per address. A name is resolved with Node's default
+ *   lookup and every address it resolves to must answer; the message
+ *   lists each address with its result and names the literal to set.
+ *   (2) The PostgreSQL connect failed with a Node syscall code
+ *   (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`, ...). (3) The ILP
+ *   client could not be built for the same class of reason.
+ *   Distinct from `INVALID_CONFIG` per the one split the ADR-018
+ *   error vocabulary mandates: the connection string may be fine —
+ *   check the network, the firewall, whether QuestDB is running.
+ *   Underlying error on `err.cause` for (2) and (3).
  * - `MISSING_ASSET_CLASS`    — `assetClass` not provided to `createStorage`.
  *   Distinct from `INVALID_CONFIG` because operator remediation differs:
  *   they need to add `.assetClass(assetClassDef)` to the flow, not edit env
@@ -91,24 +200,80 @@
  * - `SCHEMA_ERROR`           — DDL `CREATE TABLE` failed for a reason other
  *   than already-exists (see `ensure-tables.js`).
  *
- * Runtime returns:
- * - `INVALID_INSIGHT_TYPE` — sync; the insightType has no persist plan
+ * Runtime returns (sync, from `write()`):
+ * - `INVALID_INSIGHT_TYPE` — the insightType has no persist plan
  *   (typically a config typo or asset-class drift).
- * - `SEND_FAILED`          — sync; the persist plan threw while invoking
- *   sender methods (ILP buffer overflow, type coercion failure, etc.).
+ * - `STORAGE_FULL`         — the buffer is at `bufferCeilingRows`. The
+ *   row was shed. One shared result object; shedding allocates
+ *   nothing. Remediation: the endpoint is not taking rows; check it.
+ *   Raise the ceiling only when memory allows.
+ * - `SHUTTING_DOWN`        — `shutdown()` has been called; no flusher
+ *   is left for a new row. One shared result object.
+ * - `SEND_FAILED`          — the persist plan threw while invoking
+ *   sender methods (type coercion failure, a client throw). The
+ *   half-written row is cancelled (mid-row recovery, in
+ *   `flush-engine.js`).
  * - `INVALID_TIMESTAMP`    — reserved; today persist-plan handles invalid
  *   timestamps via `onWarning + skip-row`. It may later be surfaced as a
  *   hard return error.
  *
  * Shutdown-time throws (ADR-018 — a clean shutdown resolve means
  * everything buffered or in flight was delivered; both carry
- * `dropped: { count }`, exact). Shutdown settles every unsettled flush
- * (idle, recovery) plus one final flush, raced against `{ timeout }`;
- * its outcome is latched so repeated calls cannot contradict it:
+ * `dropped: { count }`, exact):
  * - `DELIVERY_FAILED`  — a flush failed; first flush error on `cause`.
  * - `SHUTDOWN_TIMEOUT` — delivery did not settle within the caller's
- *   `{ timeout }` (a send against an unreachable server never settles —
- *   see the mid-row recovery section below).
+ *   `{ timeout }`.
+ *
+ * Runtime console classification (tokens, not `err.code` values):
+ * - `DELIVERY_FAILED`  — an engine or recovery flush failed or was
+ *   abandoned at its deadline, or the client refused a row append, and
+ *   no `onDeliveryFailure` was given. One `logger.error` line per
+ *   event, carrying the exact rows lost and the client's message. A
+ *   flush line ends with the probe finding when a probe ran. The
+ *   process keeps running: an unattended deployment must report a lost
+ *   batch, not stop on it. The health surface carries the same fact.
+ * - `CIRCUIT_OPEN`     — delivery paused or resumed (ADR-029 hold and
+ *   probe). One `logger.warn` line when a failing probe pauses
+ *   delivery, naming the held rows and the finding. One `logger.warn`
+ *   line when a tick probe passes and delivery resumes, at warn so a
+ *   log transport with a warn floor carries the episode end. Nothing
+ *   per tick. Remediation: the endpoint refused a TCP connect; check
+ *   that QuestDB is running and reachable. Rows are held up to the
+ *   ceiling meanwhile, and health reads red with `pausedSince`.
+ * - `DELIVERY_HEALTH` — the delivery ladder changed state. One
+ *   `logger.warn` line when it enters yellow (the first failed flush),
+ *   one `logger.error` line when it enters red (two failed in a row,
+ *   one abandoned, or a failing probe pausing delivery, printed just
+ *   before the `CIRCUIT_OPEN` line), and one `logger.warn` line when
+ *   it returns to green, naming the episode length and the rows
+ *   reported lost in it.
+ *   Nothing while a state persists, whatever the outage length, and
+ *   the lines print with or without `onDeliveryFailure`. Remediation:
+ *   the detail is the client's message or the deadline; a red with no
+ *   `pausedSince` in health is a server that answers and refuses.
+ * - `STORAGE_FULL` (lines) — one `logger.warn` line when the first row
+ *   of an episode is refused at the ceiling, and one when the buffer
+ *   has room again, with the count refused. The end is found at the
+ *   interval tick, so its line can lag the first free slot by one
+ *   interval. Remediation: the endpoint is not taking rows; read the
+ *   `CIRCUIT_OPEN` and `DELIVERY_HEALTH` lines beside it, and raise
+ *   `bufferCeilingRows` when a longer outage must be ridden through.
+ * - `DEPRECATED_OPTION` — one `logger.warn` line at setup naming the
+ *   legacy keys in use (see Deprecated options above).
+ * - `ADDRESS_IS_NAME`  — `ilpUrl` or `pgUrl` is a name other than
+ *   `localhost`. One `logger.warn` line per field at setup, before any
+ *   socket opens (ADR-030). A name is allowed and the adapter
+ *   proceeds. The line tells the operator that only a literal address
+ *   is immune to a resolver that changes its answer under a running
+ *   process.
+ * - `CALLBACK_FAILED`  — the user's `onDeliveryFailure` itself threw or
+ *   rejected. The shared callback guard contains the fault (ADR-018).
+ *   The adapter keeps writing and flushing, and each fault becomes one
+ *   classified console line carrying the detail. `onWarning` is
+ *   deliberately NOT guarded. A throwing `onWarning` is strict mode:
+ *   the throw is the instruction that rejects the row. Wrapping it
+ *   would erase that contract (the ADR-027 exclusion, pinned by the
+ *   strict-mode specs).
  *
  * Column-internal facts consumed (the ADR-018 column-internal facts
  * pattern):
@@ -132,31 +297,22 @@
  * extend this section and add corresponding assertions in
  * `assert-columns.js`.
  *
- * Async-rejection containment:
- * - QuestDB's `sender.at(...)` is `async` — the buffer mutation is sync but
- *   the trailing `await this.tryFlush()` can fire a network flush. To prevent
- *   silent loss when that flush fails, `persist-plan.js` attaches a `.catch()`
- *   to the `at()` Promise and routes the failure to `onDeliveryFailure` when
- *   provided — otherwise it throws a classified `DELIVERY_FAILED` so the loss
- *   is loud. See `persist-plan.js` for the wrapper.
- *
- * Mid-row recovery (ADR-018 — a rejected message costs that message,
- * nothing else):
- * - A persist plan that throws between sender.table() and sender.at() leaves
- *   the client holding a half-written row. Without recovery, every later
- *   write fails with "Table name has already been set" — the 2026-06-10
- *   silent-write-failure incident lost 98.6% of a replay's rows this way.
- * - write()'s catch therefore calls recoverSender(), which composes two
- *   documented client calls: flush() ships every COMPLETED row out of the
- *   buffer (the copy-out happens synchronously, before any network I/O; the
- *   client documents that an unfinished row stays behind), then reset()
- *   clears the buffer — at that point holding only the broken stub — and
- *   lowers the client's row-in-progress flags.
- * - The client (4.2.0) has no row-cancel API, while its sibling clients do
- *   (.NET CancelRow, Rust/C rewind_to_marker, Java recovers automatically).
- *   Upstream issue #60 tracks the gap:
- *   https://github.com/questdb/nodejs-questdb-client/issues/60
- *   When a release ships cancelRow(), recoverSender() becomes that one call.
+ * Row append rejections. The client declares `sender.at()` as `async`,
+ * so its promise can reject. With the client trigger off, the only
+ * rejection left is the client's own byte ceiling (`max_buf_size`,
+ * 100 MiB by default): the append throws inside the async function
+ * and arrives as a rejection, and the row never completed.
+ * `persist-plan.js` attaches one handler per insight type to that
+ * promise and routes the failure to `onDeliveryFailure` as
+ * `( err, { tableName } )`, or prints one `DELIVERY_FAILED` line. The
+ * next write finds the sender holding the unfinished row, throws, and
+ * the mid-row recovery in `flush-engine.js` clears it.
+ *
+ * Client dependency note. `package.json` pins `@questdb/nodejs-client`
+ * to `~4.2.0`. `flush-engine.js` lists the five facts of that release
+ * the engine relies on; re-verify each on an upgrade. `persist-plan.js`
+ * also imports `SenderBufferV1`, an exported but undocumented member,
+ * for name validation at setup only.
  *
  * Integration with persist-if node:
  * - persist-if calls: state.storage.write(insightType, msg, partitionId)
@@ -191,240 +347,269 @@
  * @see https://questdb.com/docs/clients/ingest-node/
  * @see docs/architecture/storage-layer.md
  * @see ADR-018
+ * @see ADR-029
  */
 
+import http from 'node:http';
+
 import { Sender } from '@questdb/nodejs-client';
 import pg from 'pg';
 
 import { ENV_VARS } from '../../env-vars.js';
+import { logger } from '../../logger/index.js';
 import { validators } from '../../utils/validate/index.js';
+import { probeAddress, describeProbe } from '../../utils/address/probe.js';
 import { buildPersistPlans } from './persist-plan.js';
 import { ensureTables } from './ensure-tables.js';
 import { assertColumnFacts } from './assert-columns.js';
-
-// ============================================================================
-// HOT-PATH SINGLETONS
-// ============================================================================
-
-/**
- * Singleton success result reused on every successful write. Hot-path zero
- * allocation per ADR-013 / ADR-004. Plain literal — not frozen (V8 hot paths
- * handle plain objects more predictably; no caller mutates this).
- * @type {{ok: true}}
- */
-const RESULT_OK = { ok: true };
-
-// Error results (INVALID_INSIGHT_TYPE, SEND_FAILED) are constructed per-call
-// because each carries dynamic content (the offending insightType name and the
-// underlying err.message respectively). These paths are rare; per-occurrence
-// allocation on errors is acceptable. The RESULT_OK singleton above covers the
-// per-message hot path.
-
-/**
- * Health status thresholds. consecutiveWriteErrors crossing the YELLOW
- * threshold elevates status to 'yellow'; crossing the RED threshold flips
- * `connected` to false (and therefore `status` to 'red'). Tuned for "any
- * error is worth flagging" + "sustained errors mean the transport is gone."
- */
-const HEALTH_ERROR_YELLOW_THRESHOLD = 1;
-const HEALTH_ERROR_RED_THRESHOLD = 5;
-
-/**
- * Pressure threshold above which `status` elevates to at least 'yellow'.
- * 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; the number still needs
- * benchmark confirmation. Today the yield trigger is time-only (ADR-024), so
- * this alignment is forward-looking, not a description of current yield
- * behaviour. Numeric — the constant exists once here rather than scattered
- * as a magic number.
- */
-const HEALTH_PRESSURE_YELLOW_THRESHOLD = 0.66;
+import { resolveOptions, deprecationMessage } from './resolve-options.js';
+import {
+    isAllowedIlpUrl,
+    isAllowedPgUrl,
+    assertNotLocalhost,
+    assertIlpNotIPv6,
+    warnIfName,
+    assertReachable,
+    pgConnectionTarget,
+    NETWORK_ERROR_CODES,
+    buildSender
+} from './address-policy.js';
+import { createFlushEngine } from './flush-engine.js';
 
 // ============================================================================
 // CONFIGURATION BUILDER
 // ============================================================================
 
 /**
- * Build QuestDB Sender configuration from options.
+ * Build the QuestDB Sender configuration string. The client's own flush
+ * trigger is always off (ADR-029): composer starts every flush itself,
+ * so the client never sends a batch this module did not ask for. The
+ * transport is stated either way, `stdlib_http=on` unless `stdlibHttp`
+ * is false, so a printed config reads the same however it was set.
  *
- * @param {Object} options - Storage options
+ * @param {Object} options - Resolved settings
  * @param {string} options.ilpUrl - ILP endpoint (host:port)
- * @param {string} options.flushMode - 'auto' or 'manual'
- * @param {number} [options.autoFlushRows] - Rows before auto-flush
- * @param {number} [options.autoFlushIntervalMs] - Time interval for auto-flush
- * @param {number} [options.maxBufSize] - Maximum buffer size
- * @param {number} [options.retryTimeout] - Retry timeout in ms
+ * @param {boolean} [options.stdlibHttp] - False selects undici; anything else the standard library
+ * @param {number} [options.initBufSize] - Initial client buffer size in bytes
+ * @param {number} [options.maxBufSize] - Byte ceiling of the client buffer
+ * @param {number} [options.requestTimeout] - Client request timeout in ms
+ * @param {number} [options.retryTimeout] - Client retry window in ms
  * @returns {string} Configuration string for Sender.fromConfig()
  */
 const buildSenderConfig = function ( options ) {
-    const { ilpUrl, flushMode, autoFlushRows, autoFlushIntervalMs, maxBufSize, retryTimeout } = options;
+    const { ilpUrl, stdlibHttp, initBufSize, maxBufSize, requestTimeout, retryTimeout } = options;
 
-    // Base configuration: HTTP transport
-    let config = `http::addr=${ilpUrl};`;
+    let config = `http::addr=${ilpUrl};auto_flush=off;stdlib_http=${( stdlibHttp === false ) ? 'off' : 'on'};`;
 
-    // Auto-flush configuration
-    if ( flushMode === 'auto' ) {
-        // Use QuestDB's built-in auto-flush
-        if ( autoFlushRows !== undefined ) {
-            config += `auto_flush_rows=${autoFlushRows};`;
-        }
-        if ( autoFlushIntervalMs !== undefined ) {
-            config += `auto_flush_interval=${autoFlushIntervalMs};`;
-        }
-    } else {
-        // Manual mode: disable auto-flush, we control timing
-        config += 'auto_flush=off;';
+    if ( initBufSize !== undefined ) {
+        config += `init_buf_size=${initBufSize};`;
     }
-
-    // Optional buffer/retry settings
     if ( maxBufSize !== undefined ) {
-        config += `init_buf_size=${maxBufSize};`;
+        config += `max_buf_size=${maxBufSize};`;
+    }
+    if ( requestTimeout !== undefined ) {
+        config += `request_timeout=${requestTimeout};`;
     }
     if ( retryTimeout !== undefined ) {
         config += `retry_timeout=${retryTimeout};`;
     }
 
     return config;
-};
+}; // buildSenderConfig()
 
 // ============================================================================
-// STORAGE FACTORY
+// THE TRANSPORT
 // ============================================================================
 
 /**
- * Race a final flush against the shutdown time budget. No budget
- * (0/undefined) means no enforcement — the await is unbounded, preserving
- * direct-caller behavior. On timeout the flush promise is deliberately
- * left pending: the client's send may never settle (see the file header),
- * and the process is shutting down anyway. Its eventual rejection, if
- * any, is absorbed by the race's own handlers — never an
- * unhandledRejection.
- *
- * @param {Promise} flushPromise - the in-flight sender.flush()
- * @param {number} timeoutMs - budget in ms; 0/absent disables the race
- * @returns {Promise} settles with the flush, or rejects SHUTDOWN_TIMEOUT
+ * How long an idle socket stays open before the adapter closes it.
+ * QuestDB closes an idle connection after 300 seconds and announces no
+ * keep-alive timeout, so Node gets no hint. A flush that starts in the
+ * moment between the server's close and Node's notice of it writes
+ * into a dead socket, and this transport does not retry a reset. That
+ * would report one batch lost for an outage that never happened.
+ * Closing first removes that moment (ADR-029). The value sits below
+ * QuestDB's advertised keep-alive of 5 seconds and below the 5-second
+ * timeout of Node's own default agent. Node applies it to free sockets
+ * only; a request in flight keeps the client's own request timeout.
  */
-const raceFlushTimeout = function ( flushPromise, timeoutMs ) {
-    if ( !( timeoutMs > 0 ) ) {
-        return flushPromise;
-    }
-    return new Promise( function ( resolve, reject ) {
-        const timer = setTimeout( function () {
-            const err = new Error( `final flush did not settle within ${timeoutMs} ms` );
-            err.code = 'SHUTDOWN_TIMEOUT';
-            reject( err );
-        }, timeoutMs );
-        timer.unref();
-        flushPromise.then(
-            function ( value ) {
-                clearTimeout( timer );
-                resolve( value );
-            },
+const IDLE_SOCKET_TIMEOUT_MS = 4000;
 
-            /* c8 ignore start -- unreachable from the sole caller:
-               doShutdown races a Promise.all over waits that absorb
-               their own rejections (that is what keeps the dropped
-               count exact), so the raced promise cannot reject today.
-               The handler stays because this utility's contract is
-               generic — without it, a rejecting promise from a future
-               caller would become an unhandled rejection and a race
-               that never settles. */
-            function ( err ) {
-                clearTimeout( timer );
-                reject( err );
-            }
-
-            /* c8 ignore stop */
-        );
-    } );
-}; // raceFlushTimeout()
+/**
+ * Builds the one HTTP agent the standard-library transport uses. One
+ * socket is enough, because composer starts one flush at a time
+ * (ADR-029). Keep-alive reuses that socket from flush to flush, and
+ * the adapter closes it after `IDLE_SOCKET_TIMEOUT_MS` without a flush.
+ * The adapter destroys the agent at shutdown, which ends any request
+ * still on the socket.
+ *
+ * @returns {http.Agent} The agent
+ */
+const createKeepAliveAgent = function () {
+    return new http.Agent( { keepAlive: true, maxSockets: 1, timeout: IDLE_SOCKET_TIMEOUT_MS } );
+}; // createKeepAliveAgent()
 
 /**
- * Node syscall codes that mean the PostgreSQL endpoint did not answer.
- * Used at setup to classify a connect failure as TRANSPORT_UNREACHABLE
- * (the one split the ADR-018 error vocabulary mandates — see the
- * connect wrap below).
- * Module-level Set: allocated once at load, membership check at setup.
- *
- * @type {Set<string>}
+ * Opens the ILP transport: the agent when the standard-library
+ * transport is selected, then the sender. Returns the sender and the
+ * function that closes both at the end of the drain. A failed sender
+ * build destroys the agent before the classified error goes on, so no
+ * agent outlives a failed setup.
+ *
+ * `closeTransport` closes the sender first, then destroys the agent
+ * whatever the sender's close did. Destroying the agent ends any
+ * request still on its socket, so the process can exit (ADR-029). With
+ * undici there is no agent, and `closeTransport` is the sender's close.
+ *
+ * @param {Object} parts - The transport inputs
+ * @param {Object} parts.SenderClass - The client's Sender class
+ * @param {string} parts.senderConfig - The sender configuration string
+ * @param {string} parts.ilpUrl - The configured `ilpUrl`, for messages
+ * @param {boolean} parts.stdlibHttp - Whether the standard-library transport is selected
+ * @param {function} parts.createAgent - Builds the agent
+ * @returns {Promise<{sender: Object, closeTransport: function}>} The sender and its close
+ * @throws {Error} TRANSPORT_UNREACHABLE or INVALID_CONFIG from `buildSender`
  */
-const NETWORK_ERROR_CODES = new Set( [
-    'ECONNREFUSED',
-    'ENOTFOUND',
-    'ETIMEDOUT',
-    'EHOSTUNREACH',
-    'ENETUNREACH',
-    'ECONNRESET',
-    'EAI_AGAIN',
-    'EPIPE'
-] );
+const openTransport = async function ( { SenderClass, senderConfig, ilpUrl, stdlibHttp, createAgent } ) {
+    if ( stdlibHttp === false ) {
+        const sender = await buildSender( SenderClass, senderConfig, ilpUrl, null );
+        const closeTransport = function () {
+            return sender.close();
+        }; // closeTransport()
+        return { sender, closeTransport };
+    }
+
+    const agent = createAgent();
+    let sender;
+    try {
+        sender = await buildSender( SenderClass, senderConfig, ilpUrl, agent );
+    } catch ( err ) {
+        agent.destroy();
+        throw err;
+    }
+    const closeTransport = async function () {
+        try {
+            await sender.close();
+        } finally {
+            agent.destroy();
+        }
+    }; // closeTransport()
+    return { sender, closeTransport };
+}; // openTransport()
+
+// ============================================================================
+// STORAGE FACTORY
+// ============================================================================
 
 /**
  * Create QuestDB storage adapter.
  *
+ * The options are resolved by `resolve-options.js` (config over
+ * environment over default; legacy aliases mapped or ignored). Only the
+ * keys that reach the engine are listed here; the resolver documents
+ * the rest.
+ *
  * @param {Object} assetClass - Asset class definition with columns and insightTypes
  * @param {string} tablePrefix - Prefix for table names (typically assetClass.name)
  * @param {Object} options - Configuration options
- * @param {string} options.ilpUrl - ILP endpoint (host:port)
- * @param {string} options.pgUrl - PostgreSQL endpoint (host:port)
- * @param {string} [options.flushMode='auto'] - 'auto' or 'manual'
- * @param {number} [options.idleFlushAfterMs=5000] - Idle time before flush (manual mode)
- * @param {number} [options.idleFlushCheckMs=1000] - Idle check interval (manual mode)
- * @param {number} [options.autoFlushRows] - Rows before auto-flush (auto mode)
- * @param {number} [options.autoFlushIntervalMs] - Time interval for auto-flush (auto mode)
- * @param {number} [options.maxBufSize] - Maximum buffer size
- * @param {number} [options.retryTimeout] - Retry timeout in ms
+ * @param {string} [options.ilpUrl] - ILP endpoint (host:port)
+ * @param {string} [options.pgUrl] - PostgreSQL endpoint (host:port)
+ * @param {number} [options.flushRows=5000] - Rows that start a flush from inside write()
+ * @param {number} [options.flushIntervalMs=1000] - Period of the flush timer
+ * @param {number} [options.bufferCeilingRows] - Most rows held; default ten times flushRows
+ * @param {number} [options.flushDeadlineMs] - Fixed deadline per flush; derived from the rows when unset
+ * @param {boolean} [options.stdlibHttp=true] - The standard-library transport; false selects undici
+ * @param {number} [options.requestTimeout] - Client request timeout in ms
+ * @param {number} [options.retryTimeout] - Client retry window in ms
+ * @param {number} [options.initBufSize] - Initial client buffer size in bytes
+ * @param {number} [options.maxBufSize] - Byte ceiling of the client buffer
  * @param {string} [options.partitionBy='DAY'] - Table partition interval
- * @param {function} [options.onWarning] - Warning callback for null column values
+ * @param {function} [options.onWarning] - Warning callback for skipped values
+ * @param {function} [options.onDeliveryFailure] - Called once per lost flush
  * @param {Object} [deps={}] - Injectable dependencies (for testing)
  * @param {Object} [deps.SenderClass] - QuestDB Sender class (default: @questdb/nodejs-client Sender)
  * @param {Object} [deps.PgClientClass] - PostgreSQL Client class (default: pg.Client)
- * @returns {Promise<Object>} Storage adapter with write, flush, close methods
+ * @param {function} [deps.probeFn] - Setup probe (default: `probeAddress`, ADR-030)
+ * @param {function} [deps.createAgent] - Builds the transport agent (default: `createKeepAliveAgent`)
+ * @returns {Promise<Object>} Storage adapter with write, flush, shutdown, getPressure, getHealth
  */
 const createQuestDBStorage = async function ( assetClass, tablePrefix, options, deps = {} ) {
+    // Options become settings here, once (ADR-029). A ceiling below the
+    // threshold fails setup inside the resolver with INVALID_CONFIG.
+    const { settings, deprecations } = resolveOptions( options, ENV_VARS );
     const {
-        ilpUrl = ENV_VARS.questdbIlpUrl,
-        pgUrl = ENV_VARS.questdbPgUrl,
-        flushMode = ENV_VARS.questdbFlushMode,
-        idleFlushAfterMs = ENV_VARS.questdbIdleFlushAfterMs,
-        idleFlushCheckMs = ENV_VARS.questdbIdleFlushCheckMs,
-        autoFlushRows = ENV_VARS.questdbAutoFlushRows,
-        autoFlushIntervalMs = ENV_VARS.questdbAutoFlushIntervalMs,
-        maxBufSize = ENV_VARS.questdbMaxBufSize,
-        retryTimeout = ENV_VARS.questdbRetryTimeout,
-        partitionBy = 'DAY',
-        onWarning,
-        onDeliveryFailure
-    } = options;
+        ilpUrl, pgUrl, stdlibHttp, requestTimeout, retryTimeout, initBufSize, maxBufSize,
+        partitionBy, onWarning, onDeliveryFailure
+    } = settings;
+
+    // One line names every legacy key in use and what happened to it.
+    if ( deprecations.length > 0 ) {
+        logger.warn( deprecationMessage( deprecations ) );
+    }
 
     // Runtime validation — required from either DSL config or ENV_VARS.
     // Per ADR-018, setup-time throws carry classified err.code.
     if ( !ilpUrl ) {
-        const err = new Error( 'WinkComposer/questdb: ilpUrl required — set in .storage() config or QUESTDB_ILP_URL env var' );
+        const err = new Error( 'winkComposer/questdb: ilpUrl required — set in .storage() config or QUESTDB_ILP_URL env var' );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
     if ( !pgUrl ) {
-        const err = new Error( 'WinkComposer/questdb: pgUrl required — set in .storage() config or QUESTDB_PG_URL env var' );
+        const err = new Error( 'winkComposer/questdb: pgUrl required — set in .storage() config or QUESTDB_PG_URL env var' );
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+
+    // The prefix opens every table name, and CREATE TABLE writes that
+    // name unquoted (header sub-case (j)). The schema checks a flow's
+    // config. This check covers a direct caller and the default, which
+    // is the asset class name.
+    if ( !validators.identifier( tablePrefix ) ) {
+        const err = new Error(
+            `winkComposer/questdb: tablePrefix '${tablePrefix}' is not a valid table name prefix [INVALID_CONFIG]: ` +
+            'use letters, digits, _ and $ only, and do not start with a digit'
+        );
         err.code = 'INVALID_CONFIG';
         throw err;
     }
 
+    // Address policy (ADR-030), before any socket opens. `localhost` is
+    // refused. An IPv6 literal is refused for the ILP path. A name gets
+    // one warning per field. See header sub-cases (f), (g) and the
+    // ADDRESS_IS_NAME console token.
+    const ilpAddress = assertNotLocalhost( 'ilpUrl', ilpUrl, 'QUESTDB_ILP_URL' );
+    const pgAddress = assertNotLocalhost( 'pgUrl', pgUrl, 'QUESTDB_PG_URL' );
+    assertIlpNotIPv6( ilpAddress );
+    warnIfName( 'ilpUrl', ilpAddress );
+    warnIfName( 'pgUrl', pgAddress );
+
     // Injectable dependencies with defaults
     const {
         SenderClass = Sender,
-        PgClientClass = pg.Client
+        PgClientClass = pg.Client,
+        probeFn = probeAddress,
+        createAgent = createKeepAliveAgent
     } = deps;
 
-    // Build persist plans (pre-compiled closures)
+    // Build persist plans (pre-compiled closures). The callbacks go in
+    // RAW: buildPersistPlans validates them itself and arms its own
+    // guarded copy for the row-append site. Handing it a pre-wrapped
+    // function would defeat that validation (the guard turns a
+    // non-function into null instead of the fail-fast INVALID_CONFIG).
+    // The engine wraps its own copy after this validation (ADR-027:
+    // wrap once, after the site's own validation).
     const persistPlans = buildPersistPlans( assetClass, tablePrefix, { onWarning, onDeliveryFailure } );
 
+    // Setup probe, PostgreSQL side (ADR-030 item 4): every address the
+    // endpoint resolves to must answer before the client opens. The
+    // ILP side is probed below, before the sender is built.
+    await assertReachable( 'pgUrl', pgAddress, probeFn );
+
     // Ensure tables exist via PostgreSQL wire protocol
-    const [ pgHost, pgPort ] = pgUrl.split( ':' );
+    const { host: pgHost, port: pgPort } = pgConnectionTarget( pgUrl, pgAddress );
     const pgClient = new PgClientClass( {
         host: pgHost,
-        port: parseInt( pgPort, 10 ),
+        port: pgPort,
         database: ENV_VARS.questdbDatabase,
         user: ENV_VARS.questdbUser,
         password: ENV_VARS.questdbPassword
@@ -432,20 +617,21 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
 
     // Wrap the PostgreSQL connect so the failure carries a classified
     // `err.code` an operator can route on. The ADR-018 error vocabulary
-    // mandates one split here: an endpoint that does not answer (a Node syscall
-    // code like ECONNREFUSED — see NETWORK_ERROR_CODES above) is
-    // TRANSPORT_UNREACHABLE, because the remediation is "check the
-    // network, the firewall, whether the service is running" — the
-    // connection string may be perfectly fine. Everything else — an
-    // auth failure (the host answered), a protocol error, an
-    // unclassified throw — stays INVALID_CONFIG: fix the supplied
-    // config. The underlying error is preserved via `err.cause` for
-    // diagnostics either way.
+    // mandates one split here. An endpoint that does not answer is
+    // TRANSPORT_UNREACHABLE: a Node syscall code like ECONNREFUSED (see
+    // NETWORK_ERROR_CODES in address-policy.js). The remediation there
+    // is "check the network, the firewall, whether the service is
+    // running", and the connection string may be fine.
+    //
+    // Everything else stays INVALID_CONFIG: an auth failure (the host
+    // answered), a protocol error, an unclassified throw. The fix there
+    // is the supplied config. The underlying error is preserved on
+    // `err.cause` for diagnostics either way.
     try {
         await pgClient.connect();
     } catch ( connErr ) {
         const err = new Error(
-            `WinkComposer/questdb: could not connect to PostgreSQL at ${pgUrl} — ${connErr.message}`
+            `winkComposer/questdb: could not connect to PostgreSQL at ${pgUrl} — ${connErr.message}`
         );
         err.code = NETWORK_ERROR_CODES.has( connErr.code ) ?
             'TRANSPORT_UNREACHABLE' :
@@ -460,539 +646,52 @@ const createQuestDBStorage = async function ( assetClass, tablePrefix, options,
         await pgClient.end();
     }
 
-    // Create ILP sender
+    // The sender config. The client trigger is off and the transport is
+    // stated: see buildSenderConfig.
     const senderConfig = buildSenderConfig( {
-        ilpUrl,
-        flushMode,
-        autoFlushRows,
-        autoFlushIntervalMs,
-        maxBufSize,
-        retryTimeout
+        ilpUrl, stdlibHttp, initBufSize, maxBufSize, requestTimeout, retryTimeout
     } );
 
-    // fromConfig returns a Promise that resolves to a connected sender
-    const sender = await SenderClass.fromConfig( senderConfig );
-
-    // Buffer state — `bufferedRows` counts rows awaiting the NEXT flush.
-    // The client's flush() copies its rows out of the buffer synchronously
-    // (copy-out) before any network I/O, so the moment a flush is called
-    // its rows are no longer buffered — they move to the in-flight tally
-    // below. Conflating the two quantities in one counter let shutdown
-    // report clean over a hung idle flush.
-    let lastWriteTime = 0;
-    let idleFlushTimer = null;
-    let bufferedRows = 0;
-
-    // Rows inside flush copies that have not settled yet, plus the flush
-    // promises carrying them. getPressure() adds this to bufferedRows (a
-    // hung flush is undelivered data and must read as pressure), and
-    // shutdown() settles these entries instead of firing a blind flush
-    // at a buffer the copy-out already emptied.
-    let inFlightRows = 0;
-    const inFlightFlushes = new Set();
-
-    // Shutdown outcome, latched on the first call. A lossy shutdown's
-    // failed flush already emptied the buffer via copy-out, so a re-run
-    // would find nothing to flush and resolve clean — contradicting the
-    // recorded loss. Every caller gets the first call's promise instead.
-    let shutdownPromise = null;
-
-    // Health state — drives getHealth()'s status/connected derivation.
-    // shuttingDown flips true at the start of shutdown(); never resets.
-    // consecutiveWriteErrors increments on every write() catch and resets to 0
-    // on every successful persist plan call (recovery). Pure derived signal —
-    // no extra hot-path allocation; just two integer/boolean operations.
-    let shuttingDown = false;
-    let consecutiveWriteErrors = 0;
-
-    // One idle flush in flight at a time. Against an unreachable server a
-    // flush can never settle (the client's retry loop — see the mid-row
-    // recovery section in the file header); without this guard every check
-    // interval would start ANOTHER stuck flush. A hung flush leaves the
-    // flag set, the buffer keeps filling, and the condition surfaces as
-    // rising pressure in getHealth() — visible, not multiplied.
-    let idleFlushInFlight = false;
-
-    /**
-     * Registers a flush the moment it is called. Copy-out means the rows
-     * leave the buffer NOW, delivered or not, so the caller hands them
-     * over in the same breath. Settlement — either way — removes them
-     * from the in-flight tally: resolved means delivered; rejected means
-     * lost, and loss REPORTING stays at the call site (the idle flush
-     * logs or routes to onDeliveryFailure, recovery routes to
-     * onDeliveryFailure, shutdown throws classified).
-     *
-     * @param {Promise} flushPromise - the just-fired sender.flush()
-     * @param {number} rows - row count the flush copy carries
-     * @returns {{promise: Promise, rows: number}} the tracked entry
-     */
-    const trackFlush = function ( flushPromise, rows ) {
-        const entry = { promise: flushPromise, rows };
-        inFlightRows += rows;
-        inFlightFlushes.add( entry );
-        const settle = function () {
-            inFlightFlushes.delete( entry );
-            inFlightRows -= rows;
-        };
-        flushPromise.then( settle, settle );
-        return entry;
-    }; // trackFlush()
-
-    /**
-     * Check and flush if idle for idleFlushAfterMs.
-     *
-     * Runs in BOTH modes (see longer comment block at the setInterval call
-     * below). The rows move to the in-flight tally the moment the flush
-     * fires; a successful settle clears them, which also bounds the
-     * worst-case pressure-counter lag in auto mode (when QuestDB's silent
-     * `auto_flush_interval` trigger fires without us observing it, this
-     * is the self-healing point).
-     */
-    const checkIdleFlush = async function () {
-        if ( idleFlushInFlight || bufferedRows === 0 ) {
-            return;
-        }
-
-        const now = Date.now();
-        const idleTime = now - lastWriteTime;
-
-        if ( idleTime >= idleFlushAfterMs ) {
-            idleFlushInFlight = true;
-            const rows = bufferedRows;
-            bufferedRows = 0;
-            const entry = trackFlush( sender.flush(), rows );
-            try {
-                await entry.promise;
-            } catch ( err ) {
-                // Copy-out: the failed flush carried the rows with it —
-                // the buffer no longer holds them and a retry cannot
-                // resend them. They are lost, and this is the report
-                // (the settle handler already cleared them from
-                // pressure). Same routing policy as the recovery flush:
-                // the caller owns the response when it asked to.
-                if ( onDeliveryFailure ) {
-                    onDeliveryFailure( err, { idleFlush: true, rowsLost: rows } );
-                } else {
-                    console.error(
-                        `WinkComposer/questdb: idle flush failed; ${rows} buffered row(s) lost: ${err.message}`
-                    );
-                }
-            } finally {
-                idleFlushInFlight = false;
-            }
-        }
-    };
-
-    // Start idle flush timer as safety net for "data stopped flowing" case.
-    // QuestDB's auto_flush_interval only checks elapsed time when NEW data is added -
-    // it is NOT a real background timer. If no more data arrives, the buffer sits
-    // indefinitely. QuestDB docs recommend: "implement your own timer-based logic."
-    // See: https://py-questdb-client.readthedocs.io/en/stable/conf.html
-    //
-    // This timer runs in BOTH modes:
-    // - Auto mode: Safety net for when data stops flowing (QuestDB won't flush on its own)
-    // - Manual mode: Primary flush mechanism (QuestDB auto-flush is disabled)
-    idleFlushTimer = setInterval( checkIdleFlush, idleFlushCheckMs );
-    // Don't block process exit
-    idleFlushTimer.unref();
-
-    // ========================================================================
-    // STORAGE INTERFACE
-    // ========================================================================
-
-    /**
-     * Cancels a half-written ILP row after a mid-row throw, so the NEXT write
-     * starts clean (see "Mid-row recovery" in the file header for the full
-     * account and the upstream issue link).
-     *
-     * flush() copies every completed row out of the buffer synchronously and
-     * sends them in the background; the unfinished row stays behind. reset()
-     * then clears the buffer — only the broken stub remains at that point —
-     * and lowers the client's row-in-progress flags. Net effect: the broken
-     * row vanishes, every good row is on its way, the sender accepts the
-     * next write.
-     *
-     * The early flush carries real data. If its send ultimately fails (after
-     * the client's own retries), that loss is reported like any other
-     * delivery failure: routed to `onDeliveryFailure` when provided,
-     * otherwise thrown as a classified unhandled rejection — the same policy
-     * as persist-plan's sender.at() failure path. Never silent.
-     */
-    const recoverSender = function () {
-        try {
-            // flush() is an async function: it can never throw synchronously,
-            // and the rows it sends live in its own copy of the buffer.
-            // Tracked like every flush, so shutdown settles it and its
-            // rows stay visible as pressure until it settles.
-            const entry = trackFlush( sender.flush(), bufferedRows );
-            sender.reset();
-            bufferedRows = 0;
-
-            entry.promise.catch( ( flushErr ) => {
-                if ( onDeliveryFailure ) {
-                    onDeliveryFailure( flushErr, { recovery: true } );
-                    return;
-                }
-                const failure = new Error(
-                    `WinkComposer/questdb: recovery flush failed after a mid-row write error: ${flushErr.message}. ` +
-                    'Completed rows in that batch were dropped. Provide an `onDeliveryFailure` callback ' +
-                    'in the storage config to handle these explicitly.'
-                );
-                failure.code = 'DELIVERY_FAILED';
-                failure.cause = flushErr;
-                throw failure;
-            } );
-        } catch ( recoveryErr ) {
-            // Defensive: with the 4.2.0 client neither call can throw here
-            // (flush is async, reset is trivial buffer bookkeeping). If a
-            // future client changes that, the sender may stay wedged — but
-            // write() must still return its classified result rather than
-            // throw (ADR-018: the hot path never throws), and the
-            // failure must be visible.
-            console.error( `WinkComposer/questdb: sender recovery failed: ${recoveryErr.message}` );
-        }
-    }; // recoverSender()
-
-    /**
-     * Write a message to QuestDB for a given insightType.
-     *
-     * Sync hot-path return per ADR-018 / ADR-013:
-     * - `RESULT_OK` (singleton) on successful enqueue.
-     * - `{ ok: false, error: { code: 'INVALID_INSIGHT_TYPE', message } }`
-     *   when the insightType has no persist plan (config error).
-     * - `{ ok: false, error: { code: 'SEND_FAILED', message } }` when the
-     *   persist plan throws (sender method failure: ILP buffer overflow,
-     *   type coercion failure, etc.).
-     *
-     * Never throws. Async tryFlush rejections inside `sender.at()` are
-     * contained at the call site in `persist-plan.js` (see file header).
-     *
-     * @param {string} insightType - SignalType name (must exist in assetClass)
-     * @param {Object} message - Message with column values
-     * @param {string} partitionId - Partition identifier (stored as SYMBOL)
-     * @returns {{ok: true} | {ok: false, error: {code: string, message: string}}}
-     */
-    const write = function ( insightType, message, partitionId ) {
-        if ( shuttingDown ) {
-            // The idle timer is already stopped and the final flush may
-            // have run: a row accepted now would have no flusher left.
-            // Refuse loudly instead of stranding it — uniform with the
-            // MQTT emitter's SHUTTING_DOWN refusal.
-            return {
-                ok: false,
-                error: {
-                    code: 'SHUTTING_DOWN',
-                    message: 'WinkComposer/questdb: write rejected — storage is shutting down'
-                }
-            };
-        }
-
-        const persistPlan = persistPlans[ insightType ];
-
-        if ( !persistPlan ) {
-            return {
-                ok: false,
-                error: {
-                    code: 'INVALID_INSIGHT_TYPE',
-                    message: `No persist plan for insightType '${insightType}'`
-                }
-            };
-        }
-
-        try {
-            // The plan reports whether it actually opened a row. A row
-            // skipped in phase 1 (bad designated timestamp) never touched
-            // the sender and must not count as buffered — it would inflate
-            // pressure and shutdown's dropped count.
-            const written = persistPlan( sender, message, partitionId );
-            consecutiveWriteErrors = 0;  // recovery — health flips back to green
-            if ( written ) {
-                lastWriteTime = Date.now();
-                bufferedRows += 1;
-                // Auto mode: QuestDB triggers an internal flush on the sender.at()
-                // call that brings pendingRowCount to autoFlushRows (verified
-                // against @questdb/nodejs-client v4.2.0 dist/cjs/index.js
-                // tryFlush: pendingRowCount >= autoFlushRows). Mirror that reset
-                // so getPressure() reflects QuestDB's actual buffer state.
-                //
-                // Guarded on `autoFlushRows > 0` because the value is optional in
-                // ENV_VARS / config; when unset, QuestDB falls back to its own
-                // internal default which we cannot observe. In that case the
-                // heuristic does not fire and QuestDB contributes no pressure
-                // signal — `getPressure()` (below) returns 0.
-                if ( flushMode === 'auto' && autoFlushRows > 0 && bufferedRows >= autoFlushRows ) {
-                    bufferedRows = 0;
-                }
-            }
-            return RESULT_OK;
-        } catch ( err ) {
-            consecutiveWriteErrors += 1;  // health degradation signal
-            // The throw may have left a half-written row in the sender;
-            // cancel it so this failure costs one row, not the rest of the
-            // run (ADR-018). Safe to call even when no row was open: flushing
-            // early is harmless and reset() on a consistent buffer is a no-op.
-            recoverSender();
-            return {
-                ok: false,
-                error: {
-                    code: 'SEND_FAILED',
-                    message: err.message
-                }
-            };
-        }
-    };
-
-    /**
-     * Flush pending rows to QuestDB.
-     * In auto mode, this is a no-op (QuestDB handles it).
-     * In manual mode, this forces an immediate flush. The rows move to
-     * the in-flight tally at the call (copy-out); a failure rejects to
-     * the caller exactly as before, and the settle handler keeps the
-     * pressure accounting straight either way.
-     *
-     * @returns {Promise<void>}
-     */
-    const flush = async function () {
-        if ( flushMode === 'manual' && bufferedRows > 0 ) {
-            const entry = trackFlush( sender.flush(), bufferedRows );
-            bufferedRows = 0;
-            await entry.promise;
-        }
-        // Auto mode: no-op, QuestDB handles flushing
-    };
-
-    /**
-     * Backpressure metric for the partition manager. Returns the buffer fill
-     * ratio in [0, 1] per ADR-018 (sync, O(1), allocation-free). Clamped
-     * to 1.0 — the codebase invariant for getPressure across adapters.
-     *
-     * Accuracy by mode:
-     * - Manual mode: exact (we own every flush).
-     * - Auto mode, heavy flow: exact (autoFlushRows heuristic reset matches).
-     * - Auto mode, slow flow + auto_flush_interval triggers: over-states by
-     *   up to `idleFlushAfterMs`, self-heals via `checkIdleFlush`.
-     *
-     * Rows inside unsettled flush copies count as pressure: a hung flush
-     * is undelivered data, and hiding it is what let shutdown report
-     * clean over it. They leave the tally when their flush settles —
-     * delivered or reported lost.
-     *
-     * When `autoFlushRows` is not configured (left to QuestDB's internal
-     * default), we have no observable capacity reference and return
-     * 0 — QuestDB then contributes nothing to the flow's pressure signal.
-     * The time-based yield (ADR-024) and message-count safety nets remain
-     * effective.
-     *
-     * @returns {number} Pressure value in [0, 1]
-     */
-    const getPressure = function () {
-        if ( !( autoFlushRows > 0 ) ) {
-            return 0;
-        }
-        return Math.min( 1.0, ( bufferedRows + inFlightRows ) / autoFlushRows );
-    };
+    // Setup probe, ILP side (ADR-030 item 4). Before this change the
+    // write path was never opened at setup; the first sign of a dead
+    // endpoint was the first flush.
+    await assertReachable( 'ilpUrl', ilpAddress, probeFn );
 
-    /**
-     * Health snapshot for operator monitoring (uniform across sinks).
-     * Returns the ADR-018 health floor `{status, connected, ...}`, plus a
-     * small set of QuestDB-specific diagnostic fields.
-     *
-     * Status derivation (kept in code, not config — operator mental model is
-     * load-bearing institutional knowledge):
-     * - `red`    if `!connected` (shutting down or sustained write failure)
-     * - `yellow` if `pressure >= HEALTH_PRESSURE_YELLOW_THRESHOLD` OR
-     *               `consecutiveWriteErrors >= HEALTH_ERROR_YELLOW_THRESHOLD`
-     * - `green`  otherwise
-     *
-     * `connected` here is *derived* — QuestDB's ILP sender is fire-and-forget
-     * with no observable socket state, so we infer transport health from
-     * recent write success.
-     *
-     * @returns {{status: 'green'|'yellow'|'red', connected: boolean, pressure: number, consecutiveWriteErrors: number, bufferedRows: number, flushMode: string}}
-     */
-    const getHealth = function () {
-        const pressure = getPressure();
-        const connected = !shuttingDown && consecutiveWriteErrors < HEALTH_ERROR_RED_THRESHOLD;
+    // The agent, when the standard-library transport is selected, then
+    // the sender. A failure is classified, cause attached (see
+    // buildSender), and leaves no agent behind (see openTransport).
+    const { sender, closeTransport } = await openTransport( {
+        SenderClass, senderConfig, ilpUrl, stdlibHttp, createAgent
+    } );
 
-        let status;
-        if ( !connected ) {
-            status = 'red';
-        } else if ( pressure >= HEALTH_PRESSURE_YELLOW_THRESHOLD || consecutiveWriteErrors >= HEALTH_ERROR_YELLOW_THRESHOLD ) {
-            status = 'yellow';
-        } else {
-            status = 'green';
+    // The probe the engine runs after a failed flush (ADR-029 hold and
+    // probe), bound to the ILP address so the engine knows nothing
+    // about addresses. Setup ran the same probe on both endpoints.
+    const probe = {
+        run: function () {
+            return probeFn( ilpAddress );
+        },
+        describe: function ( outcome ) {
+            return describeProbe( outcome, 'ilpUrl', ilpAddress );
         }
-
-        return {
-            // Required health floor (ADR-018)
-            status,
-            connected,
-            pressure,
-            // Adapter-specific diagnostics
-            consecutiveWriteErrors,
-            bufferedRows,
-            flushMode
-        };
     };
 
-    /**
-     * Best-effort transport close on the lossy path: the loss report
-     * (the classified throw that follows) matters more than a close
-     * failure, which is only logged.
-     */
-    const closeQuietly = function () {
-        return sender.close().catch( function ( closeErr ) {
-            console.error( `WinkComposer/questdb: transport close failed during lossy shutdown: ${closeErr.message}` );
-        } );
-    }; // closeQuietly()
-
-    /**
-     * The real shutdown body. `shutdown` below latches its promise so
-     * every caller — including re-entrant and post-failure callers —
-     * receives this one outcome.
-     *
-     * A clean resolve is a delivery statement (ADR-018): everything
-     * buffered OR in flight was delivered. Shutdown therefore settles
-     * every unsettled flush (idle, recovery) plus one final flush for
-     * whatever is still buffered, all raced against the caller's
-     * `{ timeout }` (ADR-018 drain-then-close). It never fires a blind flush at a
-     * buffer an earlier copy-out emptied — that is what let it report
-     * clean over a hung idle flush.
-     *
-     * On loss it rejects classified, `dropped: { count }` exact:
-     * - any awaited flush fails → `DELIVERY_FAILED`, first flush error
-     *   on `cause`, count = rows on the flushes that failed;
-     * - the combined wait does not settle in time → `SHUTDOWN_TIMEOUT`,
-     *   count = rows not confirmed delivered. A send against an
-     *   unreachable server never settles (the client's retry loop — see
-     *   the file header), so the bound is what keeps shutdown finite.
-     * `dropped` is a statement about THIS session: those rows were not
-     * confirmed delivered before close. An abandoned flush keeps
-     * retrying and may still land its rows later if the server
-     * recovers — the count is a floor on uncertainty, not a proof of
-     * loss.
-     *
-     * The transport close is attempted in both loss paths, but on the
-     * HTTP transport the client's `close()` is an empty function
-     * (verified against @questdb/nodejs-client 4.2.0), so nothing can
-     * abort an abandoned flush's retry timers from here; they keep the
-     * event loop alive. Process exit is the final backstop — in a flow,
-     * the shutdown manager's `SHUTDOWN_FORCE_TIMEOUT_MS` exit covers
-     * this. No timeout supplied = no enforcement (unbounded await),
-     * preserving direct-caller behavior.
-     */
-    const doShutdown = async function ( timeout ) {
-        // Flip the health flag first so any concurrent getHealth() call
-        // immediately sees the shutdown and returns red/disconnected —
-        // and write() starts refusing new rows (SHUTTING_DOWN).
-        shuttingDown = true;
-
-        // Stop idle flush timer
-        if ( idleFlushTimer ) {
-            clearInterval( idleFlushTimer );
-            idleFlushTimer = null;
-        }
-
-        // Everything delivery still owes: flushes already in flight
-        // (their rows left the buffer at their call) plus one final
-        // flush for whatever is still buffered. Each wait records its
-        // outcome into the tallies below; the mapped promises never
-        // reject, so the only rejection the race can surface is the
-        // timeout itself.
-        let totalRows = 0;
-        let deliveredRows = 0;
-        let failedRows = 0;
-        let firstFailure = null;
-        const waits = [];
-
-        const awaitDelivery = function ( entry ) {
-            totalRows += entry.rows;
-            waits.push( entry.promise.then(
-                function () {
-                    deliveredRows += entry.rows;
-                },
-                function ( err ) {
-                    failedRows += entry.rows;
-                    if ( !firstFailure ) {
-                        firstFailure = err;
-                    }
-                }
-            ) );
-        }; // awaitDelivery()
-
-        inFlightFlushes.forEach( awaitDelivery );
-        if ( bufferedRows > 0 ) {
-            const entry = trackFlush( sender.flush(), bufferedRows );
-            bufferedRows = 0;
-            awaitDelivery( entry );
-        }
-
-        if ( waits.length > 0 ) {
-            try {
-                await raceFlushTimeout( Promise.all( waits ), timeout );
-            } catch ( err ) {
-                await closeQuietly();
-                const dropped = totalRows - deliveredRows;
-                const timedOut = new Error(
-                    `WinkComposer/questdb: ${err.message}; ${dropped} buffered row(s) dropped`
-                );
-                timedOut.code = 'SHUTDOWN_TIMEOUT';
-                timedOut.dropped = { count: dropped };
-                throw timedOut;
-            }
-
-            if ( failedRows > 0 ) {
-                await closeQuietly();
-                const failure = new Error(
-                    `WinkComposer/questdb: flush failed during shutdown: ${firstFailure.message}; ${failedRows} buffered row(s) dropped`
-                );
-                failure.code = 'DELIVERY_FAILED';
-                failure.dropped = { count: failedRows };
-                failure.cause = firstFailure;
-                throw failure;
-            }
-        }
-
-        // Close sender
-        await sender.close();
-    }; // doShutdown()
-
-    /**
-     * Shutdown the storage adapter gracefully.
-     * Flushes pending data and closes connections.
-     *
-     * Called by wire-storages.shutdown() which is invoked during:
-     * - Pipeline shutdown (flowHandle.shutdown())
-     * - Process signal handlers (SIGINT, SIGTERM)
-     *
-     * The outcome is latched: the first call runs the shutdown, every
-     * later call returns the same promise. A lossy shutdown's failed
-     * flush already emptied the buffer (copy-out), so a re-run would
-     * find nothing to flush and resolve clean, contradicting the
-     * recorded loss. 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 = 0 } = {} ) {
-        if ( !shutdownPromise ) {
-            shutdownPromise = doShutdown( timeout );
-        }
-        return shutdownPromise;
-    }; // shutdown()
+    // Everything after setup is the engine's: the hot path, the
+    // flushes, the counters, the drain. The transport close stays the
+    // factory's, because the factory owns the agent.
+    const engine = createFlushEngine( { sender, persistPlans, settings, onDeliveryFailure, probe, closeTransport } );
 
     return {
-        write,
-        flush,
-        shutdown,
-        getPressure,
-        getHealth,
+        write: engine.write,
+        flush: engine.flush,
+        shutdown: engine.shutdown,
+        getPressure: engine.getPressure,
+        getHealth: engine.getHealth,
         // Expose for testing/debugging
         _sender: sender,
         _persistPlans: persistPlans
     };
-};
+}; // createQuestDBStorage()
 
 // ============================================================================
 // CONFIG SCHEMA
@@ -1022,65 +721,116 @@ const configSchema = {
         'idleFlushCheckMs',
         'autoFlushRows',
         'autoFlushIntervalMs',
-        'maxBufSize',
+        'flushRows',
+        'flushIntervalMs',
+        'bufferCeilingRows',
+        'flushDeadlineMs',
+        'stdlibHttp',
+        'requestTimeout',
         'retryTimeout',
+        'initBufSize',
+        'maxBufSize',
         'partitionBy',
         'onWarning',
         'onDeliveryFailure'
     ],
+    // Both addresses refuse `localhost` at flow definition (ADR-030).
+    // The non-empty rule lives inside the validator, so one static
+    // error string covers every refusal.
     ilpUrl: {
         type: 'string',
         required: false,
-        minLength: 1,
-        error: 'ilpUrl must be a non-empty string (e.g., localhost:9000)'
+        validator: isAllowedIlpUrl,
+        error: 'ilpUrl must be host:port with a literal address or a name, never localhost and never ' +
+            'an IPv6 literal (the QuestDB client cannot read one); e.g., 127.0.0.1:9000'
     },
     pgUrl: {
         type: 'string',
         required: false,
-        minLength: 1,
-        error: 'pgUrl must be a non-empty string (e.g., localhost:8812)'
+        validator: isAllowedPgUrl,
+        error: 'pgUrl must be host:port with a literal address or a name, never localhost; e.g., 127.0.0.1:8812'
     },
     tablePrefix: {
         type: 'string',
         required: false,
         minLength: 1,
-        error: 'tablePrefix must be a non-empty string (defaults to assetClass.name when omitted)'
+        // The prefix opens every table name, written unquoted in CREATE
+        // TABLE. See header sub-case (j) for the rule and its sources.
+        validator: validators.identifier,
+        error: 'tablePrefix must use letters, digits, _ and $ only, and not start with a digit ' +
+            '(defaults to assetClass.name when omitted)'
     },
+    // The five legacy keys (deprecated, ADR-029; removed in 0.8.0). They
+    // keep their old validation so an existing flow still passes the
+    // schema. The option resolver maps or ignores them and setup prints
+    // one DEPRECATED_OPTION line.
     flushMode: {
         type: 'string',
         required: false,
         validator: validators.oneOf( [ 'auto', 'manual' ] ),
-        error: 'flushMode must be "auto" or "manual"'
+        error: 'flushMode must be "auto" or "manual" (deprecated: composer owns every flush)'
     },
     idleFlushAfterMs: {
         type: 'number',
         required: false,
         validator: validators.positiveInteger,
-        error: 'idleFlushAfterMs must be a positive integer'
+        error: 'idleFlushAfterMs must be a positive integer (deprecated: ignored)'
     },
     idleFlushCheckMs: {
         type: 'number',
         required: false,
         validator: validators.positiveInteger,
-        error: 'idleFlushCheckMs must be a positive integer'
+        error: 'idleFlushCheckMs must be a positive integer (deprecated: use flushIntervalMs)'
     },
     autoFlushRows: {
         type: 'number',
         required: false,
         validator: validators.positiveInteger,
-        error: 'autoFlushRows must be a positive integer'
+        error: 'autoFlushRows must be a positive integer (deprecated: use flushRows)'
     },
     autoFlushIntervalMs: {
         type: 'number',
         required: false,
         validator: validators.positiveInteger,
-        error: 'autoFlushIntervalMs must be a positive integer'
+        error: 'autoFlushIntervalMs must be a positive integer (deprecated: ignored)'
     },
-    maxBufSize: {
+    // The flush settings composer owns (ADR-029). The relation between
+    // the ceiling and the threshold is checked by the option resolver
+    // at setup, where both values are known.
+    flushRows: {
         type: 'number',
         required: false,
         validator: validators.positiveInteger,
-        error: 'maxBufSize must be a positive integer'
+        error: 'flushRows must be a positive integer'
+    },
+    flushIntervalMs: {
+        type: 'number',
+        required: false,
+        validator: validators.positiveInteger,
+        error: 'flushIntervalMs must be a positive integer'
+    },
+    bufferCeilingRows: {
+        type: 'number',
+        required: false,
+        validator: validators.positiveInteger,
+        error: 'bufferCeilingRows must be a positive integer'
+    },
+    flushDeadlineMs: {
+        type: 'number',
+        required: false,
+        validator: validators.positiveInteger,
+        error: 'flushDeadlineMs must be a positive integer'
+    },
+    stdlibHttp: {
+        type: 'boolean',
+        required: false,
+        error: 'stdlibHttp must be a boolean'
+    },
+    requestTimeout: {
+        type: 'number',
+        required: false,
+        validator: validators.positiveInteger,
+        error: 'requestTimeout must be a positive integer'
     },
     retryTimeout: {
         type: 'number',
@@ -1088,6 +838,18 @@ const configSchema = {
         validator: validators.positiveInteger,
         error: 'retryTimeout must be a positive integer'
     },
+    initBufSize: {
+        type: 'number',
+        required: false,
+        validator: validators.positiveInteger,
+        error: 'initBufSize must be a positive integer'
+    },
+    maxBufSize: {
+        type: 'number',
+        required: false,
+        validator: validators.positiveInteger,
+        error: 'maxBufSize must be a positive integer'
+    },
     partitionBy: {
         type: 'string',
         required: false,
@@ -1128,23 +890,24 @@ const durabilityClass = 'in-memory';
 
 // Capability declaration per ADR-018.
 //
-// QuestDB needs the asset class because (a) ensure-tables.js reads
-// `columns` and `insightTypes` to issue CREATE TABLE statements, and
-// (b) persist-plan.js reads the same to dispatch column writers and
+// QuestDB needs the asset class for two reasons. `ensure-tables.js`
+// reads `columns` and `insightTypes` to issue CREATE TABLE statements.
+// `persist-plan.js` reads the same to dispatch column writers and
 // pre-compile resolution-aware quantization. `name` drives the default
 // `tablePrefix` when the caller did not pass one.
 //
 // Declared `required: true` because there is no useful behaviour for
-// QuestDB without an assetClass — the wiring layer fails fast with
-// MISSING_ASSET_CLASS rather than calling `createStorage` and letting
+// QuestDB without an assetClass. The wiring layer fails fast with
+// MISSING_ASSET_CLASS instead of calling `createStorage` and letting
 // the failure surface deeper.
 //
 // `fields` lists exactly the top-level fields read. The slicing is
-// top-level only; column-internal fields (`type`, `resolution`) are
+// top-level only. Column-internal fields (`type`, `resolution`) are
 // read directly from the `columns` slice and validated by Layer 2
-// assertions inside `createStorage` below. A declarative shape for
-// column-internal capability is deferred until a second adapter
-// needs it.
+// assertions inside `createStorage` below.
+//
+// A declarative shape for column-internal capability is deferred
+// until a second adapter needs it.
 const semanticsRequirement = {
     assetClass: {
         required: true,
@@ -1158,17 +921,20 @@ const semanticsRequirement = {
  * @param {Object} config - Configuration object
  * @param {Object} config.assetClass - Asset class definition with columns and insightTypes
  * @param {string} config.tablePrefix - Prefix for table names (defaults to assetClass.name)
- * @param {string} config.ilpUrl - ILP endpoint (host:port)
- * @param {string} config.pgUrl - PostgreSQL endpoint (host:port)
- * @param {string} [config.flushMode='auto'] - 'auto' or 'manual'
- * @param {number} [config.idleFlushAfterMs=5000] - Idle time before flush (manual mode)
- * @param {number} [config.idleFlushCheckMs=1000] - Idle check interval (manual mode)
- * @param {number} [config.autoFlushRows] - Rows before auto-flush (auto mode)
- * @param {number} [config.autoFlushIntervalMs] - Time interval for auto-flush (auto mode)
- * @param {number} [config.maxBufSize] - Maximum buffer size
- * @param {number} [config.retryTimeout] - Retry timeout in ms
+ * @param {string} [config.ilpUrl] - ILP endpoint (host:port)
+ * @param {string} [config.pgUrl] - PostgreSQL endpoint (host:port)
+ * @param {number} [config.flushRows=5000] - Rows that start a flush from inside write()
+ * @param {number} [config.flushIntervalMs=1000] - Period of the flush timer
+ * @param {number} [config.bufferCeilingRows] - Most rows held; default ten times flushRows
+ * @param {number} [config.flushDeadlineMs] - Fixed deadline per flush
+ * @param {boolean} [config.stdlibHttp=true] - The standard-library transport; false selects undici
+ * @param {number} [config.requestTimeout] - Client request timeout in ms
+ * @param {number} [config.retryTimeout] - Client retry window in ms
+ * @param {number} [config.initBufSize] - Initial client buffer size in bytes
+ * @param {number} [config.maxBufSize] - Byte ceiling of the client buffer
  * @param {string} [config.partitionBy='DAY'] - Table partition interval
- * @param {function} [config.onWarning] - Warning callback for null column values
+ * @param {function} [config.onWarning] - Warning callback for skipped values
+ * @param {function} [config.onDeliveryFailure] - Called once per lost flush
  * @param {Object} [config._deps] - Injectable dependencies (for testing)
  * @returns {Promise<Object>} Storage instance with write, flush, shutdown methods
  */
@@ -1183,22 +949,21 @@ const createStorage = function ( config ) {
         // remediation differs — they need to add .assetClass() to the
         // flow definition, not edit env vars or storage config.
         const err = new Error(
-            'WinkComposer/questdb: assetClass is required - add .assetClass(assetClassDef) to flow before .storage()'
+            'winkComposer/questdb: assetClass is required - add .assetClass(assetClassDef) to flow before .storage()'
         );
         err.code = 'MISSING_ASSET_CLASS';
         throw err;
     }
 
     // Adapter-side defensive validation of column-internal facts
-    // QuestDB consumes. Per the ADR-018 column-internal facts
-    // pattern: the universal semantics
-    // schema validates top-level
-    // structure (type required, type in COLUMN_TYPES) at load and
-    // at .assetClass() time; this layer catches bypasses (e.g.,
-    // direct createStorage call from test code) and adapter-specific
-    // requirements like "float64 columns with declared resolution
-    // must have a positive value." See `assert-columns.js` for the
-    // full rationale.
+    // QuestDB consumes (the ADR-018 column-internal facts pattern). The
+    // universal semantics schema validates the top-level structure at
+    // load and at .assetClass() time: type required, type in
+    // COLUMN_TYPES. This layer catches bypasses, such as a direct
+    // createStorage call from test code. It also checks adapter-specific
+    // requirements, such as "a float64 column with a declared resolution
+    // must have a positive value". See `assert-columns.js` for the full
+    // rationale.
     assertColumnFacts( assetClass );
 
     // Default `tablePrefix` to the asset class name when the caller
@@ -1226,8 +991,8 @@ const createStorage = function ( config ) {
  *       .assetClass( assetClassDef )   // wire-storages injects the slice
  *       .storage( questdbAdapter, {
  *           tablePrefix: 'myPrefix',
- *           ilpUrl: 'localhost:9000',
- *           pgUrl: 'localhost:8812'
+ *           ilpUrl: '127.0.0.1:9000',
+ *           pgUrl: '127.0.0.1:8812'
  *       } )
  *
  * @type {Object}