@winkjs/composer 0.4.2 → 0.5.1

package/README.md

@@ -109,11 +109,15 @@ The numbers below come from a pure compute benchmark — every step a live messa
 | Configuration        | Throughput              |
 |----------------------|-------------------------|
 | Raspberry Pi 5       | ~100K messages/second   |
-| Modern server        | ~1.2M messages/second   |
+| MacBook Pro (M4 Max) | ~1.1M messages/second   |
 | Tracking 10K assets  | ~500K messages/second   |
 
+Both non-Pi rows were measured on a MacBook Pro (M4 Max) under Node.js 22. Every figure is single-core.
+
 Two configurations produced these numbers. The first two rows interleave 10 asset pipelines in random order — 4.5 million messages (10 pipelines × 900 data points × 500 iterations). The third row runs the same flow with 10,000 assets — 10,000 isolated states alive at once, 9 million messages, under 140 MB of heap. Pipelines are created dynamically as each asset first appears; timing uses `process.hrtime.bigint()`. The same pipeline [runs in your browser](https://composer.winkjs.org/docs/benchmark) — browser performance varies from native Node.js due to JIT differences.
 
+Reproduce them from a repo clone. `node benchmark/compare.js 10 500` reports the median of three rounds. `node benchmark/run-benchmark.js static 10000 1` gives the 10K-asset row.
+
 
 ## Built for the Real World
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@winkjs/composer",
-    "version": "0.4.2",
+    "version": "0.5.1",
     "description": "Composable Streaming Intelligence — turn streaming data into actionable insights, from edge to cloud",
     "keywords": [
         "streaming",
@@ -27,11 +27,10 @@
     },
     "scripts": {
         "pretest": "npm run lint",
-        "test": "mocha --recursive 'src/**/*.specs.js' --ignore 'src/**/slow-*.specs.js'",
-        "test:hardening": "node --expose-gc node_modules/.bin/mocha --recursive 'src/**/slow-*.specs.js' --timeout 300000 --exit",
-        "test:coverage": "c8 --reporter=html mocha --recursive 'src/**/*.specs.js' --ignore 'src/**/slow-*.specs.js'",
-        "lint": "eslint 'src/**/*.js'",
-        "docs-serve": "docsify serve ./docs"
+        "test": "mocha --recursive \"src/**/*.specs.js\" --ignore \"src/**/slow-*.specs.js\"",
+        "test:hardening": "node --expose-gc node_modules/mocha/bin/mocha.js --recursive \"src/**/slow-*.specs.js\" --timeout 300000 --exit",
+        "test:coverage": "c8 --reporter=html mocha --recursive \"src/**/*.specs.js\" --ignore \"src/**/slow-*.specs.js\"",
+        "lint": "eslint \"src/**/*.js\""
     },
     "repository": {
         "type": "git",
@@ -51,7 +50,8 @@
         "src/tools/**/*.js",
         "src/windowing/**/*.js",
         "!src/**/*.specs.js",
-        "!src/**/test/"
+        "!src/**/test/",
+        "!src/core/emitter-manager/mqtt/mqtt-store.js"
     ],
     "bugs": {
         "url": "https://github.com/winkjs/composer/issues"
@@ -63,6 +63,7 @@
     "devDependencies": {
         "c8": "^10.1.3",
         "chai": "^5.2.0",
+        "classic-level": "^3.0.0",
         "eslint": "^9.21.0",
         "eslint-plugin-security": "^4.0.0",
         "mocha": "^11.1.0",
@@ -70,7 +71,6 @@
     },
     "dependencies": {
         "@questdb/nodejs-client": "^4.2.0",
-        "classic-level": "^3.0.0",
         "glob": "^13.0.6",
         "mqtt": "^5.15.1",
         "msgpackr": "^1.11.10",

package/src/composer.js

@@ -73,3 +73,12 @@ export {
 export { sigmoid, train, predict, classify } from './tools/training/logistic.js';
 export { confusionMatrix, classificationMetrics, sweepThresholds } from './tools/training/metrics.js';
 
+// Stream-preparation utilities — ready-made functions for a source's
+// `transform` option (see docs/handbook/stream-preparation.md)
+export { coerceNumeric, coerceCell } from './tools/stream-prep/coerce-numeric.js';
+export { normalizeTimestamp } from './tools/stream-prep/normalize-timestamp.js';
+export { filterRows } from './tools/stream-prep/filter-rows.js';
+export { labelShift, shiftLabelFor } from './tools/stream-prep/label-shift.js';
+export { trackActivity } from './tools/stream-prep/track-activity.js';
+export { stampPeriod } from './tools/stream-prep/stamp-period.js';
+

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

@@ -41,7 +41,8 @@
  * ├── index.js                 # Module surface: id, schema, factory
  * ├── emitter.js               # The emitter implementation
  * ├── mqtt-store.js            # DORMANT LevelDB store (ADR-021; kept
- * │                            #   for the WAL successor, not wired)
+ * │                            #   for the WAL successor, not wired,
+ * │                            #   not shipped in the npm package)
  * ├── constants.js             # Shared configuration
  * └── test/                    # Spec files
  *

package/src/tools/stream-prep/coerce-numeric.js

@@ -0,0 +1,94 @@
+// src/tools/stream-prep/coerce-numeric.js
+
+/**
+ * @fileoverview coerceNumeric — a stream-preparation utility for a source's
+ * `transform` option. Given a fixed list of fields, it rewrites each field on
+ * the message to a clean finite number or NaN, in place, allocating nothing
+ * per message.
+ *
+ * Why it exists: raw feeds (CSV replay, MQTT, a historian export) deliver
+ * blanks, empty strings, and out-of-range collector garbage mixed with real
+ * numbers. A downstream node's NaN-skip only works if "no value" reads as
+ * NaN, never 0 — and `Number( '' )` is 0 and `Number( null )` is 0, so a
+ * naive coercion silently invents zeros where data is missing. This maps
+ * every not-a-real-number to NaN explicitly, so a blank stays a blank.
+ *
+ * Scope is deliberately narrow and field-agnostic: it does NOT know any
+ * field's physical range. Field-specific validity (a -9999 code, a bath
+ * below 5 degC) is the `sanitize` node's job in the flow (the ADR-018
+ * boundary: a bad value in a parseable record is the pipeline's concern).
+ * This utility only guarantees the value is a finite number or NaN, plus an
+ * optional magnitude cut (`sentinelAbs`) for the huge collector garbage
+ * (e.g. 3.4e38) that is invalid for every field.
+ *
+ * Family contract (ADR-025, stream-preparation utilities): configuration is
+ * captured once at init; the returned function mutates the message in place,
+ * creates no objects per message, and returns the same reference, so it
+ * drops straight into a source `transform` slot ( row -> row ).
+ */
+
+/**
+ * Coerce one raw cell to a number or NaN, without allocating. Empty string and
+ * null/undefined are "no value" -> NaN (never 0). A numeric string parses; a
+ * boolean maps to 1/0; anything unparseable is NaN.
+ *
+ * Known limitation: a whitespace-only string ( '   ' ) coerces to 0, matching
+ * `Number`'s own behaviour — detecting it would cost a per-cell allocation, and
+ * real feeds use '' or null for a missing cell. Add such tokens upstream if a
+ * feed genuinely encodes missing as whitespace.
+ *
+ * @param {*} value - the raw cell
+ * @returns {number} a number, possibly NaN
+ */
+const coerceCell = function ( value ) {
+    if ( typeof value === 'number' ) {
+        return value;
+    }
+    if ( ( value === null ) || ( value === undefined ) || ( value === '' ) ) {
+        return NaN;
+    }
+    return Number( value );
+}; // coerceCell()
+
+/**
+ * Build an in-place numeric coercer for a fixed set of fields.
+ *
+ * @param {string[]} fields - message fields to coerce (non-empty array of
+ *     non-empty strings; validated at init, fail-fast)
+ * @param {Object} [options]
+ * @param {number} [options.sentinelAbs] - if set, any coerced value whose
+ *     magnitude is at or above this becomes NaN. A cut for universally-invalid
+ *     collector garbage, NOT a per-field physical range (that lives in sanitize).
+ * @returns {function( Object ): Object} transform( msg ) -> msg, mutated in place
+ */
+const coerceNumeric = function ( fields, options ) {
+    if ( !Array.isArray( fields ) || ( fields.length === 0 ) ) {
+        throw new Error( 'winkComposer/coerceNumeric: fields must be a non-empty array.' );
+    }
+    for ( let i = 0; i < fields.length; i += 1 ) {
+        if ( ( typeof fields[ i ] !== 'string' ) || ( fields[ i ] === '' ) ) {
+            throw new Error( 'winkComposer/coerceNumeric: every field must be a non-empty string.' );
+        }
+    }
+    const opts = options || {};
+    const sentinelAbs = ( opts.sentinelAbs === undefined ) ? Infinity : opts.sentinelAbs;
+    if ( ( typeof sentinelAbs !== 'number' ) || Number.isNaN( sentinelAbs ) || ( sentinelAbs <= 0 ) ) {
+        throw new Error( 'winkComposer/coerceNumeric: sentinelAbs must be a positive number.' );
+    }
+    // Private copy so the caller cannot mutate the field list after init; index
+    // iteration over a stable local keeps the hot path free of iterator objects.
+    const fieldList = fields.slice();
+    const n = fieldList.length;
+
+    return function ( msg ) {
+        for ( let i = 0; i < n; i += 1 ) {
+            const field = fieldList[ i ];
+            const num = coerceCell( msg[ field ] );
+            msg[ field ] = ( Number.isFinite( num ) && ( Math.abs( num ) < sentinelAbs ) ) ? num : NaN;
+        }
+        return msg;
+    };
+}; // coerceNumeric()
+
+export { coerceCell, coerceNumeric };
+export default coerceNumeric;

package/src/tools/stream-prep/filter-rows.js

@@ -0,0 +1,96 @@
+// src/tools/stream-prep/filter-rows.js
+
+/**
+ * @fileoverview filterRows — a stream-preparation utility for a source's
+ * `transform` option. Keeps only the rows whose timestamp falls inside an
+ * inclusive time window, by returning null for everything outside it. The
+ * source counts each null as a skipped record, so drops stay visible.
+ *
+ * Why it exists: replay work — demos, evaluations, byte-identity reruns —
+ * almost always studies a window of a longer recording. Field flows carried
+ * the same two-compare window filter as inline code many times over; this is
+ * that filter, once. A live production feed normally has no use for it.
+ *
+ * The bounds are a Knob of the run, fixed at init: `from` and `to` accept an
+ * epoch-ms number or an ISO-8601 string (parsed once, at init — never per
+ * row). The hot path is two number compares against the timestamp field.
+ * Run it AFTER `normalizeTimestamp`, so the field already holds epoch ms.
+ *
+ * A row whose timestamp is not a finite number cannot be placed inside or
+ * outside the window, so it is dropped too. Rows with a bad clock never
+ * reach the flow through this filter.
+ *
+ * Deliberately NOT here: arbitrary predicates. The `transform` hook itself
+ * is already "return null to drop", so a custom predicate needs no utility.
+ * This one earns its place only by owning the bounds parsing and the
+ * inclusive-window rule.
+ *
+ * Family contract (ADR-025, stream-preparation utilities): config captured
+ * at init; zero per-row allocation; returns the same message reference, or
+ * null to drop ( row -> row | null ).
+ */
+
+/**
+ * Resolve one bound to epoch ms at init. Numbers must be finite; strings go
+ * through `Date.parse` once. Anything else, or an unparseable string, throws.
+ *
+ * @param {*} value - the bound as given
+ * @param {string} name - option name for the error message
+ * @returns {number} epoch ms
+ */
+const resolveBound = function ( value, name ) {
+    if ( typeof value === 'number' ) {
+        if ( !Number.isFinite( value ) ) {
+            throw new Error( 'winkComposer/filterRows: ' + name + ' must be a finite epoch-ms number or a parseable date string.' );
+        }
+        return value;
+    }
+    if ( typeof value === 'string' ) {
+        const parsed = Date.parse( value );
+        if ( !Number.isFinite( parsed ) ) {
+            throw new Error( 'winkComposer/filterRows: ' + name + ' is not a parseable date string (got \'' + value + '\').' );
+        }
+        return parsed;
+    }
+    throw new Error( 'winkComposer/filterRows: ' + name + ' must be a finite epoch-ms number or a parseable date string.' );
+}; // resolveBound()
+
+/**
+ * Build an inclusive time-window row filter.
+ *
+ * @param {Object} options
+ * @param {string} [options.field='timestamp'] - field holding epoch ms
+ *     (normalize it first — see normalizeTimestamp).
+ * @param {number|string} [options.from] - inclusive lower bound (epoch ms or
+ *     ISO-8601 string). At least one of from/to is required.
+ * @param {number|string} [options.to] - inclusive upper bound (epoch ms or
+ *     ISO-8601 string).
+ * @returns {function( Object ): (Object|null)} transform( msg ) -> msg inside
+ *     the window, null outside it. A non-finite timestamp also returns null.
+ */
+const filterRows = function ( options ) {
+    const opts = options || {};
+    const field = ( opts.field === undefined ) ? 'timestamp' : opts.field;
+    if ( ( typeof field !== 'string' ) || ( field === '' ) ) {
+        throw new Error( 'winkComposer/filterRows: field must be a non-empty string.' );
+    }
+    if ( ( opts.from === undefined ) && ( opts.to === undefined ) ) {
+        throw new Error( 'winkComposer/filterRows: at least one of from/to is required.' );
+    }
+    const fromMs = ( opts.from === undefined ) ? -Infinity : resolveBound( opts.from, 'from' );
+    const toMs = ( opts.to === undefined ) ? Infinity : resolveBound( opts.to, 'to' );
+    if ( fromMs > toMs ) {
+        throw new Error( 'winkComposer/filterRows: from must not be later than to.' );
+    }
+
+    return function ( msg ) {
+        const t = msg[ field ];
+        if ( !Number.isFinite( t ) ) {
+            return null;
+        }
+        return ( ( t >= fromMs ) && ( t <= toMs ) ) ? msg : null;
+    };
+}; // filterRows()
+
+export { filterRows };
+export default filterRows;

package/src/tools/stream-prep/label-shift.js

@@ -0,0 +1,112 @@
+// src/tools/stream-prep/label-shift.js
+
+/**
+ * @fileoverview labelShift — a stream-preparation utility for a source's
+ * `transform` option. Stamps each message with the production shift it falls
+ * in (e.g. S1 / S2 / S3), derived from the event timestamp, in place, with no
+ * per-message allocation.
+ *
+ * The shift schedule is a deployment Knob, not a universal fact — sites
+ * differ in shift count, length, start time, and labels. So everything is
+ * config: give it the schedule, it labels any feed.
+ *
+ * Why alloc-free matters and how: the obvious implementation, `new Date( ms )
+ * .getUTCHours()`, allocates a Date object every message — unacceptable on
+ * the hot path. Instead this reduces the epoch to a minute-of-day by integer
+ * modulo and picks the shift by a short scan over the boundary list. All
+ * configuration (offset, boundaries, labels) is captured once at init; the
+ * returned function reads/writes the message in place, creates no objects,
+ * and returns the same message so it drops into a source `transform` slot
+ * ( row -> row ) — the ADR-025 family contract.
+ *
+ * Local time is a FIXED offset from UTC. Daylight-saving sites are out of
+ * scope: a fixed offset cannot follow a DST change, and the timezone
+ * machinery that could would allocate per message. India (IST, +5:30)
+ * observes no DST; a DST site must resolve local time upstream.
+ *
+ * The shift schedule is given as `boundariesMin` — the minute-of-day at which
+ * each shift starts, ascending — and matching `labels`. A time earlier than
+ * the first boundary belongs to the last shift (it wrapped past midnight), so
+ * a schedule whose first shift starts at 06:00 labels the small hours
+ * correctly.
+ */
+
+import { fieldNameOr, finiteNumberOr, validatedBoundaries } from './validate.js';
+
+const MS_PER_MIN = 60000;
+const MS_PER_DAY = 86400000;
+
+/**
+ * Pure shift lookup: which shift an epoch-ms instant falls in. Reduces the instant to
+ * a local minute-of-day (fixed offset, integer modulo — no Date object) and returns
+ * the label of the last boundary at or below it; a time before the first boundary
+ * wraps to the last shift. Shared by the hot-path labeler below and by any caller that
+ * needs the shift of a one-off instant (e.g. the shift that just ended at a boundary).
+ *
+ * @param {number} t - epoch ms; a non-finite value returns null (no shift known).
+ * @param {number} offsetMinutes - minutes to add to reach local wall-clock (IST = 330).
+ * @param {number[]} boundariesMin - shift start minutes-of-day, ascending.
+ * @param {string[]} labels - one label per boundary.
+ * @returns {string|null} the shift label, or null for a non-finite instant.
+ */
+const shiftLabelFor = function ( t, offsetMinutes, boundariesMin, labels ) {
+    if ( !Number.isFinite( t ) ) {
+        return null;
+    }
+    let intoDay = ( t + ( offsetMinutes * MS_PER_MIN ) ) % MS_PER_DAY;
+    if ( intoDay < 0 ) {
+        intoDay += MS_PER_DAY;
+    }
+    const minute = Math.floor( intoDay / MS_PER_MIN );
+    let idx = labels.length - 1;
+    for ( let i = 0; i < boundariesMin.length; i += 1 ) {
+        if ( minute >= boundariesMin[ i ] ) {
+            idx = i;
+        }
+    }
+    return labels[ idx ];
+}; // shiftLabelFor()
+
+/**
+ * Build an in-place shift labeler.
+ *
+ * @param {Object} options
+ * @param {number[]} options.boundariesMin - shift start minutes-of-day, strictly
+ *     ascending, each in [0, 1440). Required. (e.g. [ 0, 480, 960 ] for three
+ *     8-hour shifts from local midnight.)
+ * @param {string[]} options.labels - shift labels, one per boundary, same length.
+ *     Required. (e.g. [ 'S1', 'S2', 'S3' ].)
+ * @param {number} [options.offsetMinutes=0] - minutes to add to epoch-UTC to reach
+ *     local wall-clock time (IST = 330).
+ * @param {string} [options.field='timestamp'] - source field holding epoch ms.
+ * @param {string} [options.target='shiftLabel'] - field to write the label to.
+ * @returns {function( Object ): Object} transform( msg ) -> msg, mutated in place.
+ *     A non-finite timestamp writes null (no shift known).
+ */
+const labelShift = function ( options ) {
+    const opts = options || {};
+    const field = fieldNameOr( opts.field, 'timestamp', 'labelShift', 'field' );
+    const target = fieldNameOr( opts.target, 'shiftLabel', 'labelShift', 'target' );
+    const offsetMinutes = finiteNumberOr( opts.offsetMinutes, 0, 'labelShift', 'offsetMinutes' );
+    // Private copies from the validators; the hot path touches only these
+    // locals and the shared lookup.
+    const bounds = validatedBoundaries( opts.boundariesMin, 'labelShift' );
+    const labels = opts.labels;
+    if ( !Array.isArray( labels ) || ( labels.length !== bounds.length ) ) {
+        throw new Error( 'winkComposer/labelShift: labels must be an array the same length as boundariesMin.' );
+    }
+    for ( let i = 0; i < labels.length; i += 1 ) {
+        if ( ( typeof labels[ i ] !== 'string' ) || ( labels[ i ] === '' ) ) {
+            throw new Error( 'winkComposer/labelShift: every label must be a non-empty string.' );
+        }
+    }
+    const names = labels.slice();
+
+    return function ( msg ) {
+        msg[ target ] = shiftLabelFor( msg[ field ], offsetMinutes, bounds, names );
+        return msg;
+    };
+}; // labelShift()
+
+export { labelShift, shiftLabelFor };
+export default labelShift;

package/src/tools/stream-prep/normalize-timestamp.js

@@ -0,0 +1,265 @@
+// src/tools/stream-prep/normalize-timestamp.js
+
+/**
+ * @fileoverview normalizeTimestamp — a stream-preparation utility for a
+ * source's `transform` option. Guarantees one message field holds a numeric
+ * epoch-millisecond timestamp, in place, with no per-message allocation.
+ *
+ * Why it exists: every downstream window, dwell, and control node keys off
+ * event time, and raw feeds carry it in different shapes — epoch
+ * milliseconds, epoch seconds, an ISO-8601 string, or a plant historian's
+ * zone-less 'YYYY-MM-DD HH:mm:ss' text. A flow should not branch on which;
+ * this converts the declared field to epoch ms once, at the inlet.
+ *
+ * The input shape is fixed at init (a Knob of the feed, not sniffed per
+ * row), so the hot path carries no shape-detection branch. Two ways to
+ * declare it:
+ *
+ *   unit: 'ms'      the value is already epoch milliseconds
+ *   unit: 's'       the value is epoch seconds -> multiplied by 1000
+ *   unit: 'auto'    numbers pass through as ms; strings go to `Date.parse`
+ *   pattern         the value is text in EXACTLY this layout; parsed by a
+ *                   compiled reader with a declared fixed UTC offset
+ *
+ * The pattern path exists because zone-less historian text is the single
+ * most common field shape, and `Date.parse` on it is engine-dependent. The
+ * one supported pattern is 'YYYY-MM-DD HH:mm:ss'; the data may carry a
+ * trailing '.SSS' fraction (any number of digits; milliseconds kept, the
+ * rest truncated). The reader walks the string by character code and builds
+ * the epoch with the days-from-civil calendar algorithm (Howard Hinnant,
+ * "chrono-Compatible Low-Level Date Algorithms",
+ * https://howardhinnant.github.io/date_algorithms.html) — no `replace`, no
+ * `Date` object, no `Date.parse`, nothing allocated per row.
+ * `offsetMinutes` states the wall clock the text was written in (IST =
+ * 330); the epoch is shifted back to true UTC. Fixed offset only — DST
+ * sites are out of scope, same rule as labelShift.
+ *
+ * An empty or unparseable value becomes NaN, never a throw and never 0; the
+ * caller decides whether to drop the row (see filterRows).
+ *
+ * Family contract (ADR-025, stream-preparation utilities): converter and
+ * field names are captured at init; the returned function reads/writes the
+ * message in place and returns the same reference ( row -> row ).
+ */
+
+import { fieldNameOr, finiteNumberOr } from './validate.js';
+
+const MS_PER_SEC = 1000;
+const MS_PER_MIN = 60000;
+const MS_PER_HOUR = 3600000;
+const MS_PER_DAY = 86400000;
+const ZERO_CODE = 48;
+const SUPPORTED_PATTERN = 'YYYY-MM-DD HH:mm:ss';
+
+// Days in each month (index 1-12) of a non-leap year; February's leap case is
+// handled at the day-of-month validity check.
+const DAYS_IN_MONTH = [ 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 ];
+
+/**
+ * Coerce a raw cell to a number or NaN without allocating. Empty string and
+ * null/undefined are "no value" -> NaN (never 0), so an empty seconds cell does
+ * not become epoch 0.
+ *
+ * @param {*} value - the raw cell
+ * @returns {number} a number, possibly NaN
+ */
+const toNum = function ( value ) {
+    if ( typeof value === 'number' ) {
+        return value;
+    }
+    if ( ( value === null ) || ( value === undefined ) || ( value === '' ) ) {
+        return NaN;
+    }
+    return Number( value );
+}; // toNum()
+
+/**
+ * Read a fixed-width run of ASCII digits as an integer; -1 when any position
+ * is not a digit. The -1 sentinel keeps the caller's malformed-input path a
+ * plain compare, with no exception machinery on the hot path.
+ */
+const readDigits = function ( s, start, len ) {
+    let out = 0;
+    for ( let i = start; i < ( start + len ); i += 1 ) {
+        const d = s.charCodeAt( i ) - ZERO_CODE;
+        if ( ( d < 0 ) || ( d > 9 ) ) {
+            return -1;
+        }
+        out = ( out * 10 ) + d;
+    }
+    return out;
+}; // readDigits()
+
+/** Gregorian leap-year rule. */
+const isLeapYear = function ( y ) {
+    return ( ( ( y % 4 ) === 0 ) && ( ( y % 100 ) !== 0 ) ) || ( ( y % 400 ) === 0 );
+}; // isLeapYear()
+
+/** True for a real calendar date (readDigits' -1 fails the range checks). */
+const isValidDate = function ( year, month, day ) {
+    if ( ( year < 0 ) || ( month < 1 ) || ( month > 12 ) || ( day < 1 ) ) {
+        return false;
+    }
+    const maxDay = ( ( month === 2 ) && isLeapYear( year ) ) ? 29 : DAYS_IN_MONTH[ month ];
+    return day <= maxDay;
+}; // isValidDate()
+
+/** True for a real time of day (readDigits' -1 fails the range checks). */
+const isValidTime = function ( hour, minute, second ) {
+    return ( hour >= 0 ) && ( hour <= 23 ) &&
+           ( minute >= 0 ) && ( minute <= 59 ) &&
+           ( second >= 0 ) && ( second <= 59 );
+}; // isValidTime()
+
+/**
+ * Read the optional '.frac' tail starting at position 19: '.' plus one or
+ * more digits. Returns milliseconds (first three digits; the rest validated
+ * but truncated), or -1 when the tail is malformed.
+ */
+const readFraction = function ( s, len ) {
+    if ( ( s.charCodeAt( 19 ) !== 46 ) || ( len === 20 ) ) {
+        return -1;
+    }
+    let frac = 0;
+    let scale = 100;
+    for ( let i = 20; i < len; i += 1 ) {
+        const d = s.charCodeAt( i ) - ZERO_CODE;
+        if ( ( d < 0 ) || ( d > 9 ) ) {
+            return -1;
+        }
+        if ( scale >= 1 ) {
+            frac += d * scale;
+            scale = ( scale === 1 ) ? 0 : ( scale / 10 );
+        }
+    }
+    return frac;
+}; // readFraction()
+
+/**
+ * Days from the civil epoch (1970-01-01) for a valid calendar date. This is
+ * Howard Hinnant's days_from_civil, an exact integer algorithm — see
+ * https://howardhinnant.github.io/date_algorithms.html.
+ */
+const daysFromCivil = function ( year, month, day ) {
+    const y = ( month <= 2 ) ? ( year - 1 ) : year;
+    const era = Math.floor( y / 400 );
+    const yoe = y - ( era * 400 );
+    const mp = ( month + 9 ) % 12;
+    const doy = Math.floor( ( ( 153 * mp ) + 2 ) / 5 ) + ( day - 1 );
+    const doe = ( yoe * 365 ) + Math.floor( yoe / 4 ) - Math.floor( yoe / 100 ) + doy;
+    return ( era * 146097 ) + doe - 719468;
+}; // daysFromCivil()
+
+/**
+ * Compile the reader for the one supported pattern. Returns a function that
+ * parses 'YYYY-MM-DD HH:mm:ss[.frac]' text written in a fixed-offset wall
+ * clock to true-UTC epoch ms, or NaN for anything malformed.
+ *
+ * @param {number} offsetMs - wall-clock offset from UTC in ms (IST = 330 min)
+ * @returns {function( * ): number} value -> epoch ms | NaN
+ */
+const compilePatternReader = function ( offsetMs ) {
+    return function ( value ) {
+        if ( ( typeof value !== 'string' ) || ( value.length < 19 ) ) {
+            return NaN;
+        }
+        const len = value.length;
+        // Fixed separators first — cheapest rejection for a wrong layout.
+        if ( ( value.charCodeAt( 4 ) !== 45 ) || ( value.charCodeAt( 7 ) !== 45 ) ||
+             ( value.charCodeAt( 10 ) !== 32 ) || ( value.charCodeAt( 13 ) !== 58 ) ||
+             ( value.charCodeAt( 16 ) !== 58 ) ) {
+            return NaN;
+        }
+        const year = readDigits( value, 0, 4 );
+        const month = readDigits( value, 5, 2 );
+        const day = readDigits( value, 8, 2 );
+        const hour = readDigits( value, 11, 2 );
+        const minute = readDigits( value, 14, 2 );
+        const second = readDigits( value, 17, 2 );
+        if ( !isValidDate( year, month, day ) || !isValidTime( hour, minute, second ) ) {
+            return NaN;
+        }
+        const frac = ( len > 19 ) ? readFraction( value, len ) : 0;
+        if ( frac < 0 ) {
+            return NaN;
+        }
+        const days = daysFromCivil( year, month, day );
+        return ( days * MS_PER_DAY ) + ( hour * MS_PER_HOUR ) + ( minute * MS_PER_MIN ) +
+               ( second * MS_PER_SEC ) + frac - offsetMs;
+    };
+}; // compilePatternReader()
+
+// One converter per input shape, chosen once at init so the hot path never
+// branches on the mode string. Dictionary with an externally-supplied key, so
+// Object.create( null ) guards against inherited-property lookups (e.g. a mode of
+// 'constructor' resolving to Object). Each converter returns epoch ms or NaN.
+const CONVERTERS = Object.create( null );
+CONVERTERS.ms = function ( value ) {
+    return toNum( value );
+};
+CONVERTERS.s = function ( value ) {
+    return toNum( value ) * MS_PER_SEC;
+};
+CONVERTERS.auto = function ( value ) {
+    return ( typeof value === 'number' ) ? value : Date.parse( value );
+};
+
+/**
+ * Pick the converter from the options: a compiled pattern reader when
+ * `pattern` is declared, one of the unit converters otherwise. Init-time
+ * only; all option conflicts are rejected here.
+ */
+const resolveConverter = function ( opts ) {
+    if ( opts.pattern === undefined ) {
+        if ( opts.offsetMinutes !== undefined ) {
+            throw new Error( 'winkComposer/normalizeTimestamp: offsetMinutes applies to pattern only.' );
+        }
+        const unit = ( opts.unit === undefined ) ? 'auto' : opts.unit;
+        const convert = CONVERTERS[ unit ];
+        if ( typeof convert !== 'function' ) {
+            throw new Error( 'winkComposer/normalizeTimestamp: unit must be one of ms, s, auto (got ' + unit + ').' );
+        }
+        return convert;
+    }
+    if ( opts.unit !== undefined ) {
+        throw new Error( 'winkComposer/normalizeTimestamp: unit and pattern are mutually exclusive.' );
+    }
+    if ( opts.pattern !== SUPPORTED_PATTERN ) {
+        throw new Error( 'winkComposer/normalizeTimestamp: the supported pattern is \'' + SUPPORTED_PATTERN + '\' (got ' + opts.pattern + ').' );
+    }
+    const offsetMinutes = finiteNumberOr( opts.offsetMinutes, 0, 'normalizeTimestamp', 'offsetMinutes' );
+    return compilePatternReader( offsetMinutes * MS_PER_MIN );
+}; // resolveConverter()
+
+/**
+ * Build an in-place timestamp normalizer.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.field='timestamp'] - source field to read
+ * @param {string} [options.target=field] - field to write; defaults to the source
+ *     field (in place). Set it when the raw column name differs from the field the
+ *     flow reads (e.g. read 'ts', write 'timestamp').
+ * @param {string} [options.unit='auto'] - input shape: 'ms' | 's' | 'auto'.
+ *     Mutually exclusive with pattern.
+ * @param {string} [options.pattern] - fixed text layout; the one supported
+ *     value is 'YYYY-MM-DD HH:mm:ss' (data may carry a trailing '.SSS'
+ *     fraction). Mutually exclusive with unit.
+ * @param {number} [options.offsetMinutes=0] - with pattern only: the fixed
+ *     UTC offset of the wall clock the text was written in (IST = 330).
+ * @returns {function( Object ): Object} transform( msg ) -> msg, mutated in place
+ */
+const normalizeTimestamp = function ( options ) {
+    const opts = options || {};
+    const field = fieldNameOr( opts.field, 'timestamp', 'normalizeTimestamp', 'field' );
+    const target = fieldNameOr( opts.target, field, 'normalizeTimestamp', 'target' );
+    const convert = resolveConverter( opts );
+
+    return function ( msg ) {
+        const out = convert( msg[ field ] );
+        msg[ target ] = Number.isFinite( out ) ? out : NaN;
+        return msg;
+    };
+}; // normalizeTimestamp()
+
+export { normalizeTimestamp };
+export default normalizeTimestamp;