@winkjs/composer 0.6.0 → 0.8.0

package/src/core/storage-manager/questdb/resolve-options.js

@@ -0,0 +1,266 @@
+// core/storage-manager/questdb/resolve-options.js
+
+/**
+ * @fileoverview Turns the QuestDB storage options into the settings the
+ * adapter runs on.
+ *
+ * The adapter accepts options from two places: the `.storage()` config
+ * in the flow, and the `QUESTDB_*` environment variables read by
+ * `env-vars.js`. This module merges the two, fills in the defaults, and
+ * derives the buffer ceiling from the flush threshold. It also computes
+ * the deadline of one flush from the rows that flush carries. It is a
+ * pure function of its inputs, so it can be tested without a flow, a
+ * client, or a live environment. The adapter calls `resolveOptions`
+ * once, at setup, and `flushDeadlineFor` once per flush. Nothing here
+ * runs on the per-row path.
+ *
+ * Why the derived values live here and not in `env-vars.js`. The buffer
+ * ceiling defaults to ten times the flush threshold. A fixed ceiling in
+ * the environment would fail setup whenever a user raised the threshold
+ * in config without also raising the ceiling. So the environment carries
+ * a value only when the operator set one, and this module derives the
+ * rest from what actually won.
+ *
+ * Why the deadline depends on the row count. The client gives a bigger
+ * request more time: its request timeout is an inactivity timeout that
+ * grows with the bytes sent, at a planning speed of 100 KiB per second
+ * (`request_min_throughput`, a 4.2.0 fact). A fixed deadline would
+ * abandon a large but healthy send over a slow link and report rows
+ * lost that then land. So the deadline is the client's worst case for
+ * that batch, plus a margin. One attempt is the request timeout plus
+ * the transfer time at a planning size of 512 bytes a row. The client
+ * checks its retry window only when an attempt ends, so its last
+ * attempt can run in full past the window. The deadline is therefore
+ * the retry window, two attempts, the longest backoff, and 5 seconds.
+ * One row gets about 36 seconds; 5000 rows get 86 seconds; a full
+ * 50000-row catch-up send gets about 9 minutes. When the operator
+ * sets `flushDeadlineMs`, that fixed value is used for every flush.
+ *
+ * Precedence, highest first (ADR-018 §10): the key in the config
+ * (`flushRows`), then the environment variable (`QUESTDB_FLUSH_ROWS`),
+ * then the default.
+ *
+ * The five legacy keys of 0.7.0 (`flushMode`, `idleFlushAfterMs`,
+ * `idleFlushCheckMs`, `autoFlushRows`, `autoFlushIntervalMs`) are gone
+ * since 0.8.0 (ADR-029 item 10). The adapter's schema refuses each one
+ * as an unknown key, and `env-vars.js` refuses their `QUESTDB_*`
+ * variables at import. Nothing here looks for them.
+ *
+ * The one relation enforced here: the ceiling is never below twice
+ * the threshold. Rows in flight count against the ceiling, so a
+ * ceiling equal to the threshold would refuse every row that arrives
+ * during a row-triggered flush. Twice the threshold holds one batch
+ * in flight and one batch buffering. A smaller ceiling fails setup
+ * with `INVALID_CONFIG`.
+ *
+ * The client constants used in the deadline are `@questdb/nodejs-client`
+ * 4.2.0 facts, cited by line in the client's `dist/es/index.mjs`. The
+ * defaults sit at lines 230 to 234: `request_min_throughput` 102400
+ * bytes a second, `request_timeout` 10 s, `retry_timeout` 10 s. The
+ * throughput option is documented at line 404 and read at line 275.
+ * The request timeout grows with the bytes sent at line 1142.
+ *
+ * The retry clock starts when the first attempt ends, at line 1183.
+ * The window is checked when a later attempt ends, at lines 1186 to
+ * 1188. The backoff between attempts doubles and stops at 1000 ms,
+ * with a jitter of up to 5 ms, at lines 1192 to 1194. Re-verify these
+ * lines on a client upgrade. A configured `requestTimeout` or
+ * `retryTimeout` replaces its default in the sum, so an operator who
+ * lengthens a timeout lengthens the deadline with it.
+ *
+ * The transport setting has two vocabularies. In config, `stdlibHttp`
+ * is a boolean. In the environment, `QUESTDB_STDLIB_HTTP` takes the
+ * client's own words `on` and `off`. This module maps the words to the
+ * boolean, and the default is the standard-library transport
+ * (`DEFAULT_STDLIB_HTTP` explains why).
+ *
+ * @see ADR-029
+ */
+
+// ============================================================================
+// DEFAULTS
+// ============================================================================
+
+/**
+ * Rows that trigger a flush from inside `write()`. At the measured 130
+ * to 290 bytes a row this is 0.65 to 1.5 MB per request, sized for an
+ * edge device and a slow plant link. Larger deployments raise it by
+ * config.
+ * @type {number}
+ */
+const DEFAULT_FLUSH_ROWS = 5000;
+
+/**
+ * Period of the flush timer. Rows land within about this long after
+ * they were written, busy stream or idle stream alike, and a power cut
+ * costs at most about this much data.
+ * @type {number}
+ */
+const DEFAULT_FLUSH_INTERVAL_MS = 1000;
+
+/**
+ * The ceiling is this many flush thresholds. Past it, `write()` sheds
+ * new rows with `STORAGE_FULL`. With flushes held while the endpoint is
+ * unreachable (ADR-029), the ceiling is the outage the adapter rides
+ * through without loss: ten batches hold 50 seconds at 1000 rows a
+ * second and hours at plant rate, in 6.5 to 15 MB of memory.
+ * @type {number}
+ */
+const DEFAULT_CEILING_MULTIPLIER = 10;
+
+/**
+ * The client's standard-library HTTP transport is selected unless the
+ * operator opts out. It is the transport whose requests end: a refused
+ * connection rejects at once, and a stalled request ends within the
+ * retry window plus one request timeout. The client's own default,
+ * undici, retries a refused connection without end, and its abort
+ * cannot end that retry (ADR-029).
+ * @type {boolean}
+ */
+const DEFAULT_STDLIB_HTTP = true;
+
+/**
+ * The client's default `request_timeout` (4.2.0 fact).
+ * @type {number}
+ */
+const CLIENT_DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+
+/**
+ * The client's default `retry_timeout` (4.2.0 fact).
+ * @type {number}
+ */
+const CLIENT_DEFAULT_RETRY_TIMEOUT_MS = 10000;
+
+/**
+ * The client's default `request_min_throughput`, in bytes per second
+ * (4.2.0 fact). The client extends its request timeout by the time the
+ * request would take at this speed.
+ * @type {number}
+ */
+const CLIENT_DEFAULT_MIN_THROUGHPUT_BPS = 102400;
+
+/**
+ * Planning size of one row for the deadline, above the widest row
+ * measured (291 bytes for 16 float columns). A row wider than this over
+ * a link at the planning speed needs an explicit `flushDeadlineMs`.
+ * @type {number}
+ */
+const ROW_BYTES_PLANNING = 512;
+
+/**
+ * The longest pause the client takes between two attempts (4.2.0 fact:
+ * the backoff doubles from 10 ms and stops at 1000 ms).
+ * @type {number}
+ */
+const CLIENT_MAX_RETRY_BACKOFF_MS = 1000;
+
+/**
+ * Added on top of the client's own bound, so the client gets to reject
+ * first with a real error and the deadline stays a backstop for a hang
+ * the client cannot see.
+ * @type {number}
+ */
+const FLUSH_DEADLINE_MARGIN_MS = 5000;
+
+// ============================================================================
+// RESOLUTION
+// ============================================================================
+
+/**
+ * Maps the words of `QUESTDB_STDLIB_HTTP` to a boolean. The words are
+ * the client's own for `stdlib_http`, `on` and `off`, so an operator
+ * reads one vocabulary in the variable and in the config string.
+ * `env-vars.js` has already refused any other word.
+ *
+ * @param {string|undefined} word - `'on'`, `'off'`, or undefined when unset
+ * @returns {boolean|undefined} The boolean, or undefined when unset
+ */
+const onOffToBoolean = function ( word ) {
+    if ( word === undefined ) {
+        return undefined;
+    }
+    return word === 'on';
+}; // onOffToBoolean()
+
+/**
+ * Resolves the storage options into the adapter's settings.
+ * `flushDeadlineMs` is undefined unless the operator set it; the engine
+ * then derives each flush's deadline with `flushDeadlineFor`.
+ *
+ * @param {Object} options - The raw storage options from `.storage()` config
+ * @param {Object} envVars - The `ENV_VARS` object (injected, for purity)
+ * @returns {Object} The resolved settings
+ * @throws {Error} INVALID_CONFIG when the ceiling is below twice the threshold
+ */
+const resolveOptions = function ( options, envVars ) {
+    const flushRows = options.flushRows ?? envVars.questdbFlushRows ?? DEFAULT_FLUSH_ROWS;
+    const flushIntervalMs = options.flushIntervalMs ?? envVars.questdbFlushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    const bufferCeilingRows = options.bufferCeilingRows ??
+        envVars.questdbBufferCeilingRows ??
+        ( flushRows * DEFAULT_CEILING_MULTIPLIER );
+
+    // Rows in flight count against the ceiling. A ceiling equal to the
+    // threshold would refuse every row that arrives during a
+    // row-triggered flush, because the batch in flight fills it. Twice
+    // the threshold is the least that holds one batch in flight and
+    // one batch buffering.
+    if ( bufferCeilingRows < ( 2 * flushRows ) ) {
+        const err = new Error(
+            `winkComposer/questdb: bufferCeilingRows ${bufferCeilingRows} is below twice flushRows ${flushRows} [INVALID_CONFIG]: ` +
+            'the ceiling must hold one batch in flight and one batch buffering; raise bufferCeilingRows or lower flushRows'
+        );
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+
+    return {
+        ilpUrl: options.ilpUrl ?? envVars.questdbIlpUrl,
+        pgUrl: options.pgUrl ?? envVars.questdbPgUrl,
+        flushRows,
+        flushIntervalMs,
+        bufferCeilingRows,
+        flushDeadlineMs: options.flushDeadlineMs ?? envVars.questdbFlushDeadlineMs,
+        stdlibHttp: options.stdlibHttp ?? onOffToBoolean( envVars.questdbStdlibHttp ) ?? DEFAULT_STDLIB_HTTP,
+        requestTimeout: options.requestTimeout ?? envVars.questdbRequestTimeout,
+        retryTimeout: options.retryTimeout ?? envVars.questdbRetryTimeout,
+        initBufSize: options.initBufSize ?? envVars.questdbInitBufSize,
+        maxBufSize: options.maxBufSize ?? envVars.questdbMaxBufSize,
+        partitionBy: options.partitionBy ?? 'DAY',
+        onWarning: options.onWarning,
+        onDeliveryFailure: options.onDeliveryFailure
+    };
+}; // resolveOptions()
+
+/**
+ * The deadline of one flush, in milliseconds. A fixed `flushDeadlineMs`
+ * wins. Otherwise it is the client's worst case for a batch of this
+ * many rows plus a margin. One attempt lasts the request timeout plus
+ * the transfer time at the planning speed and row size (see the
+ * header). The client checks its retry window only when an attempt
+ * ends, and it starts that clock when the first attempt ends. So the
+ * last attempt can begin just inside the window and run in full. The
+ * worst case is two attempts around the window, plus the longest
+ * backoff between attempts. A configured `retryTimeout` or
+ * `requestTimeout` replaces the client default in that sum. One
+ * multiply per flush, nothing per row.
+ *
+ * @param {number} rows - Rows the flush carries
+ * @param {Object} settings - The resolved settings
+ * @returns {number} The deadline in milliseconds
+ */
+const flushDeadlineFor = function ( rows, settings ) {
+    if ( settings.flushDeadlineMs !== undefined ) {
+        return settings.flushDeadlineMs;
+    }
+    const retryTimeout = settings.retryTimeout ?? CLIENT_DEFAULT_RETRY_TIMEOUT_MS;
+    const requestTimeout = settings.requestTimeout ?? CLIENT_DEFAULT_REQUEST_TIMEOUT_MS;
+    const transferMs = Math.ceil( ( rows * ROW_BYTES_PLANNING * 1000 ) / CLIENT_DEFAULT_MIN_THROUGHPUT_BPS );
+    const attemptMs = requestTimeout + transferMs;
+    return retryTimeout + ( 2 * attemptMs ) + CLIENT_MAX_RETRY_BACKOFF_MS + FLUSH_DEADLINE_MARGIN_MS;
+}; // flushDeadlineFor()
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export { resolveOptions, flushDeadlineFor, CLIENT_MAX_RETRY_BACKOFF_MS };

package/src/core/storage-manager/questdb/shutdown-drain.js

@@ -0,0 +1,181 @@
+// core/storage-manager/questdb/shutdown-drain.js
+
+/**
+ * @fileoverview The drain-then-close shutdown of the QuestDB adapter
+ * (ADR-018 §7, ADR-029).
+ *
+ * A clean shutdown resolve is a delivery statement: everything
+ * buffered or in flight was delivered. The drain therefore settles
+ * every flush still in the ledger (engine, recovery, explicit) plus one
+ * final flush for whatever is still buffered. It never fires a blind
+ * flush at a buffer an earlier copy-out emptied. That blind flush is
+ * what once let shutdown report clean over a hung flush.
+ *
+ * The caller's `{ timeout }` bounds the whole drain. Without one, the
+ * deadline on each flush (`flush-tracker.js`) bounds it instead, so a
+ * shutdown with no budget still ends. On loss the drain rejects with a
+ * classified error carrying `dropped: { count }`, exact:
+ * - `DELIVERY_FAILED` when any awaited flush failed or was abandoned.
+ *   The first error is on `cause`; the count is the rows on the
+ *   flushes that failed.
+ * - `SHUTDOWN_TIMEOUT` when the drain did not settle within the budget.
+ *   The count is the rows not confirmed delivered.
+ *
+ * `dropped` is a statement about this session: those rows were not
+ * confirmed delivered before close. An abandoned flush may still land
+ * its rows if the server recovers, so the count is a floor on
+ * uncertainty, not a proof of loss.
+ *
+ * How the tally works. Each entry in the ledger has an `onDone`
+ * handler owned by whoever started the flush. The drain wraps that
+ * handler: the owner's handler still runs, and the drain adds the
+ * entry's rows to delivered or failed. The wrapped promises never
+ * reject, so the only rejection the race can surface is the timeout.
+ *
+ * The transport close runs on every path, clean or lossy. The client's
+ * own `close()` is an empty function on its HTTP transports (a 4.2.0
+ * fact). What ends a request still on the wire is the agent the
+ * factory owns: `closeTransport` closes the sender and then destroys
+ * that agent (ADR-029). In a flow, the shutdown manager's forced exit
+ * is the final backstop. A close failure on a loss path is logged,
+ * because the loss report matters more than the close.
+ *
+ * @see ADR-018
+ * @see ADR-029
+ */
+
+import { logger } from '../../logger/index.js';
+
+/** The final flush has no owner of its own: the drain tallies it. */
+const NOOP = function () {
+    // Intentionally empty.
+}; // NOOP()
+
+/**
+ * Races the drain against the caller's time budget. No budget (0 or
+ * undefined) means no race. The timer is `unref`'d and cleared however
+ * the race ends, so a finished drain leaves nothing behind. The losing
+ * side is left as it is: the drain never rejects, and a cleared timer
+ * never fires.
+ *
+ * @param {Promise} drain - The drain; it settles but never rejects
+ * @param {number} timeoutMs - Budget in ms; 0 or absent disables the race
+ * @returns {Promise} Settles with the drain, or rejects SHUTDOWN_TIMEOUT
+ */
+const raceTimeout = function ( drain, timeoutMs ) {
+    if ( !( timeoutMs > 0 ) ) {
+        return drain;
+    }
+    let timer = null;
+    const timeout = new Promise( function ( resolve, reject ) {
+        timer = setTimeout( function () {
+            const err = new Error( `final flush did not settle within ${timeoutMs} ms` );
+            err.code = 'SHUTDOWN_TIMEOUT';
+            reject( err );
+        }, timeoutMs );
+        timer.unref();
+    } );
+    return Promise.race( [ drain, timeout ] ).finally( function () {
+        clearTimeout( timer );
+    } );
+}; // raceTimeout()
+
+/**
+ * Builds the drain over the engine's sender and ledger.
+ *
+ * @param {Object} parts - What the drain runs on
+ * @param {Object} parts.sender - The connected ILP sender
+ * @param {{entries: Set}} parts.ledger - The tracker's ledger of flushes in flight
+ * @param {function} parts.track - The tracker's `track`, for the final flush
+ * @param {function} parts.takeBufferedRows - `() => number`: returns the buffered count and zeroes it
+ * @param {function} parts.closeTransport - `() => Promise<void>`: closes the sender, then destroys the factory's agent
+ * @returns {function} `drain( timeoutMs ) => Promise<void>`
+ */
+const createShutdownDrain = function ( { sender, ledger, track, takeBufferedRows, closeTransport } ) {
+
+    /**
+     * Best-effort transport close on the lossy path.
+     *
+     * @returns {Promise<void>} Resolves whether or not the close worked
+     */
+    const closeQuietly = function () {
+        return closeTransport().catch( function ( closeErr ) {
+            logger.error( `winkComposer/questdb: transport close failed during lossy shutdown: ${closeErr.message}` );
+        } );
+    }; // closeQuietly()
+
+    /**
+     * Runs the drain once. The engine latches the returned promise so
+     * every caller receives this one outcome.
+     *
+     * @param {number} timeoutMs - The caller's budget; 0 means none
+     * @returns {Promise<void>} Resolves clean, or rejects classified
+     */
+    const drain = async function ( timeoutMs ) {
+        let totalRows = 0;
+        let deliveredRows = 0;
+        let failedRows = 0;
+        let firstFailure = null;
+        const waits = [];
+
+        const awaitDelivery = function ( entry ) {
+            totalRows += entry.rows;
+            const ownerDone = entry.onDone;
+            waits.push( new Promise( function ( resolve ) {
+                entry.onDone = function ( err, abandoned ) {
+                    ownerDone( err, abandoned );
+                    if ( err ) {
+                        failedRows += entry.rows;
+                        if ( !firstFailure ) {
+                            firstFailure = err;
+                        }
+                    } else {
+                        deliveredRows += entry.rows;
+                    }
+                    resolve();
+                };
+            } ) );
+        }; // awaitDelivery()
+
+        // 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.
+        ledger.entries.forEach( awaitDelivery );
+        const buffered = takeBufferedRows();
+        if ( buffered > 0 ) {
+            awaitDelivery( track( sender.flush(), buffered, NOOP ) );
+        }
+
+        if ( waits.length > 0 ) {
+            try {
+                await raceTimeout( Promise.all( waits ), timeoutMs );
+            } 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;
+            }
+        }
+
+        await closeTransport();
+    }; // drain()
+
+    return drain;
+}; // createShutdownDrain()
+
+export { createShutdownDrain };

package/src/core/storage-manager/questdb/skip-warnings.js

@@ -0,0 +1,180 @@
+// core/storage-manager/questdb/skip-warnings.js
+
+/**
+ * @fileoverview How a skipped value is reported.
+ *
+ * The persist plan checks every value before a row opens. A value that
+ * fails its check is skipped, and the skip is reported through
+ * `onWarning`: a column skip lands the column as NULL, a bad designated
+ * timestamp skips the whole row. This module builds the functions the
+ * plan calls at those two sites. It owns the wording of the lines, the
+ * default handler, and the bound on that default.
+ *
+ * Why the default is bounded (ADR-029, the same rule as the flush loss
+ * line). A dead sensor publishes NaN in one column on every row. That
+ * is one warning line per row for as long as the sensor is dead: one
+ * line a second for a whole night, in a log nobody can read. So the
+ * default handler is bounded per column. The first two skips of an
+ * episode print in full. Later skips are counted, and one summary
+ * line prints per minute with the count, the latest reason, and the
+ * latest asset. A quiet minute on that column ends the episode. Rows
+ * skipped for a bad designated timestamp share one bound per insight
+ * type.
+ *
+ * The bound is on the default only. A user `onWarning` hears every
+ * skip with the full line, because the flow chose to listen. A user
+ * handler that throws is strict mode (ADR-027): the throw is the
+ * instruction that rejects the row, so it must reach the plan
+ * unchanged. Neither is bounded.
+ *
+ * Nothing here runs on the happy path. The plan calls a warning only
+ * when a value failed its check, and a counted skip allocates nothing:
+ * the line is rendered only when it prints.
+ *
+ * @see ADR-027
+ * @see ADR-029
+ */
+
+import { createLineBound } from '../../utils/line-rate/index.js';
+import { logger } from '../../logger/index.js';
+
+/**
+ * The bound on the default warning (see the file header). The values
+ * match the flush loss line in flush-engine.js, so an operator reads
+ * one rhythm.
+ */
+const FULL_WARNING_LINES_PER_EPISODE = 2;
+const WARNING_SUMMARY_INTERVAL_MS = 60000;
+
+/**
+ * Default warning handler for invalid column values: one `logger.warn`
+ * line in winkComposer format. The skip sites reach it through the
+ * per-column line bound (see the file header), so under a streak it
+ * prints the first two skips in full and then one summary per minute.
+ *
+ * Validation behavior:
+ * - null/undefined columns: skip column only (QuestDB stores NULL)
+ * - NaN/Infinity in numeric columns: skip column only (QuestDB stores NULL)
+ * - Wrong-typed column values (e.g. a number where the column is string-typed):
+ *   skip column only, never coerce — the warning names the expected and
+ *   received types
+ * - Invalid designatedTimestamp: skip entire row
+ *
+ * For strict mode (throw on any invalid), provide:
+ *   { onWarning: (msg) => { throw new Error(msg); } }
+ *
+ * Future extension: return value may control skip-row vs skip-column behavior.
+ *
+ * @param {string} message - Warning message describing the issue
+ */
+const defaultOnWarning = function ( message ) {
+    logger.warn( `winkComposer/questdb: ${message}` );
+}; // defaultOnWarning()
+
+/**
+ * Builds the reason text for a value that failed its phase-1 acceptance
+ * check. Called only on the rare skip path, so its allocations are
+ * acceptable (same budget as the error returns in index.js).
+ *
+ * @param {*} rawValue - the rejected value
+ * @param {boolean} isNumeric - whether the column type is numeric
+ * @param {string} expectedType - declared column type, named in the message
+ * @returns {string} plain reason text for the skip warning
+ */
+const skipReason = function ( rawValue, isNumeric, expectedType ) {
+    if ( rawValue === null ) return 'null';
+    if ( rawValue === undefined ) return 'undefined';
+    if ( isNumeric && typeof rawValue === 'number' ) {
+        if ( Number.isNaN( rawValue ) ) return 'NaN';
+        // A finite number can only be rejected by the integer-required
+        // types (int64/timestamp/designated timestamp) — float64 accepts
+        // every finite number.
+        return Number.isFinite( rawValue ) ? 'non-integer' : 'non-finite';
+    }
+    return `wrong-typed (expected ${expectedType}, received ${typeof rawValue})`;
+}; // skipReason()
+
+/**
+ * Builds the warning function for one skip site. With a user
+ * `onWarning`, every skip reaches it with the full line. With the
+ * default, the line bound applies. Both renderers run only when a line
+ * prints, so a counted skip allocates nothing.
+ *
+ * @param {Function|undefined} providedOnWarning - The user's handler, or undefined for the default
+ * @param {Function} fullLine - `( rawValue, partitionId ) => string`, without the brand prefix
+ * @param {Function} summaryLine - `( count, seconds, rawValue, partitionId ) => string`, without the brand prefix
+ * @returns {Function} `( rawValue, partitionId ) => void`
+ */
+const makeSkipWarning = function ( providedOnWarning, fullLine, summaryLine ) {
+    if ( providedOnWarning !== undefined ) {
+        return function ( rawValue, partitionId ) {
+            providedOnWarning( fullLine( rawValue, partitionId ) );
+        };
+    }
+    return createLineBound( {
+        fullLines: FULL_WARNING_LINES_PER_EPISODE,
+        intervalMs: WARNING_SUMMARY_INTERVAL_MS,
+        printFull: function ( rawValue, partitionId ) {
+            defaultOnWarning( fullLine( rawValue, partitionId ) );
+        },
+        printSummary: function ( count, seconds, rawValue, partitionId ) {
+            defaultOnWarning( summaryLine( count, seconds, rawValue, partitionId ) );
+        }
+    } );
+}; // makeSkipWarning()
+
+/**
+ * Builds the skip warning for one column of one insight type.
+ *
+ * @param {Function|undefined} providedOnWarning - The user's handler, or undefined for the default
+ * @param {string} insightTypeName - Named in every line
+ * @param {string} columnName - The column the skip is about
+ * @param {boolean} isNumeric - Whether the column type is numeric, for the reason text
+ * @param {string} columnType - The declared column type, for the reason text
+ * @returns {Function} `( rawValue, partitionId ) => void`
+ */
+const makeColumnWarning = function ( providedOnWarning, insightTypeName, columnName, isNumeric, columnType ) {
+    return makeSkipWarning(
+        providedOnWarning,
+        ( rawValue, partitionId ) => (
+            `column '${columnName}' is ${skipReason( rawValue, isNumeric, columnType )} ` +
+            `in insightType '${insightTypeName}' (asset: ${partitionId}) — column skipped`
+        ),
+        ( count, seconds, rawValue, partitionId ) => (
+            `column '${columnName}' skipped in ${count} more row(s) of insightType '${insightTypeName}' ` +
+            `in the last ${seconds} s (latest: ${skipReason( rawValue, isNumeric, columnType )}, asset: ${partitionId})`
+        )
+    );
+}; // makeColumnWarning()
+
+/**
+ * Builds the row-skip warning of one insight type, for a designated
+ * timestamp that is missing or not an integer.
+ *
+ * @param {Function|undefined} providedOnWarning - The user's handler, or undefined for the default
+ * @param {string} insightTypeName - Named in every line
+ * @param {string} designatedTimestamp - The timestamp column, named in every line
+ * @returns {Function} `( tsValue, partitionId ) => void`
+ */
+const makeRowWarning = function ( providedOnWarning, insightTypeName, designatedTimestamp ) {
+    return makeSkipWarning(
+        providedOnWarning,
+        ( tsValue, partitionId ) => (
+            `designatedTimestamp '${designatedTimestamp}' is ${skipReason( tsValue, true, 'timestamp' )} ` +
+            `in insightType '${insightTypeName}' (asset: ${partitionId}) - row skipped`
+        ),
+        ( count, seconds, tsValue, partitionId ) => (
+            `${count} more row(s) of insightType '${insightTypeName}' skipped for designatedTimestamp ` +
+            `'${designatedTimestamp}' in the last ${seconds} s (latest: ${skipReason( tsValue, true, 'timestamp' )}, ` +
+            `asset: ${partitionId})`
+        )
+    );
+}; // makeRowWarning()
+
+export {
+    defaultOnWarning,
+    makeColumnWarning,
+    makeRowWarning,
+    FULL_WARNING_LINES_PER_EPISODE,
+    WARNING_SUMMARY_INTERVAL_MS
+};