@winkjs/composer 0.4.2 → 0.5.0

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.0",
     "description": "Composable Streaming Intelligence — turn streaming data into actionable insights, from edge to cloud",
     "keywords": [
         "streaming",

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/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;

package/src/tools/stream-prep/stamp-period.js

@@ -0,0 +1,111 @@
+// src/tools/stream-prep/stamp-period.js
+
+/**
+ * @fileoverview stampPeriod — a stream-preparation utility for a source's
+ * `transform` option. Stamps each message with a monotonic integer key naming
+ * the calendar period — the local day, or the shift — its timestamp falls in.
+ * In place, with no per-message allocation.
+ *
+ * Why a key and not a "period rolled" flag: the roll (the first message of a
+ * new period, per asset) needs per-asset state, and per-asset state belongs
+ * to partitions. With the key on the message, a per-partition
+ * `stateChangeDetector` on it gives the per-asset roll edge in-flow, and a
+ * `controller` can flush windows on it. The utility stays stateless and
+ * stream-level; the flow owns the roll.
+ *
+ * The keys and their arithmetic (all integer, no Date objects):
+ *   'day'    dayIndex   = floor( (t + offset) / 86400000 ) — days since the
+ *            epoch, counted in local wall-clock time (fixed offset).
+ *   'shift'  shiftKey   = (dayIndex * shiftsPerDay) + shiftIdx — unique and
+ *            monotonic across days. A time earlier than the first boundary
+ *            belongs to the PREVIOUS day's last shift (it wrapped past
+ *            midnight), so the key never jumps backward at a boundary.
+ *
+ * Local time is a FIXED offset from UTC, same rule as labelShift: DST sites
+ * are out of scope; resolve local time upstream there.
+ *
+ * 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
+ * ( row -> row ). A non-finite timestamp writes null (no period known).
+ */
+
+import { fieldNameOr, finiteNumberOr, validatedBoundaries } from './validate.js';
+
+const MS_PER_MIN = 60000;
+const MS_PER_DAY = 86400000;
+
+/**
+ * Build an in-place period-key stamper.
+ *
+ * @param {Object} options
+ * @param {string} options.period - 'day' or 'shift'. Required.
+ * @param {number[]} [options.boundariesMin] - shift start minutes-of-day,
+ *     strictly ascending, each in [0, 1440). Required for 'shift';
+ *     not allowed for 'day'.
+ * @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] - field to write the key to. Defaults to
+ *     'dayKey' or 'shiftKey' by period.
+ * @returns {function( Object ): Object} transform( msg ) -> msg, mutated in
+ *     place. A non-finite timestamp writes null.
+ */
+const stampPeriod = function ( options ) {
+    const opts = options || {};
+    const period = opts.period;
+    if ( ( period !== 'day' ) && ( period !== 'shift' ) ) {
+        throw new Error( 'winkComposer/stampPeriod: period must be day or shift.' );
+    }
+    const field = fieldNameOr( opts.field, 'timestamp', 'stampPeriod', 'field' );
+    const defaultTarget = ( period === 'day' ) ? 'dayKey' : 'shiftKey';
+    const target = fieldNameOr( opts.target, defaultTarget, 'stampPeriod', 'target' );
+    const offsetMinutes = finiteNumberOr( opts.offsetMinutes, 0, 'stampPeriod', 'offsetMinutes' );
+    const offsetMs = offsetMinutes * MS_PER_MIN;
+
+    if ( period === 'day' ) {
+        if ( opts.boundariesMin !== undefined ) {
+            throw new Error( 'winkComposer/stampPeriod: boundariesMin applies to shift only.' );
+        }
+        return function ( msg ) {
+            const t = msg[ field ];
+            msg[ target ] = Number.isFinite( t ) ? Math.floor( ( t + offsetMs ) / MS_PER_DAY ) : null;
+            return msg;
+        };
+    }
+
+    // period === 'shift' — the schedule is validated exactly as labelShift's.
+    const bounds = validatedBoundaries( opts.boundariesMin, 'stampPeriod' );
+    const shiftsPerDay = bounds.length;
+
+    return function ( msg ) {
+        const t = msg[ field ];
+        if ( !Number.isFinite( t ) ) {
+            msg[ target ] = null;
+            return msg;
+        }
+        const local = t + offsetMs;
+        const dayIndex = Math.floor( local / MS_PER_DAY );
+        let intoDay = local % MS_PER_DAY;
+        if ( intoDay < 0 ) {
+            intoDay += MS_PER_DAY;
+        }
+        const minute = Math.floor( intoDay / MS_PER_MIN );
+        if ( minute < bounds[ 0 ] ) {
+            // Wrapped past midnight: previous day's last shift, keeping the key monotonic.
+            msg[ target ] = ( ( dayIndex - 1 ) * shiftsPerDay ) + ( shiftsPerDay - 1 );
+            return msg;
+        }
+        let idx = 0;
+        for ( let i = 0; i < shiftsPerDay; i += 1 ) {
+            if ( minute >= bounds[ i ] ) {
+                idx = i;
+            }
+        }
+        msg[ target ] = ( dayIndex * shiftsPerDay ) + idx;
+        return msg;
+    };
+}; // stampPeriod()
+
+export { stampPeriod };
+export default stampPeriod;

package/src/tools/stream-prep/track-activity.js

@@ -0,0 +1,223 @@
+// src/tools/stream-prep/track-activity.js
+
+/**
+ * @fileoverview trackActivity — a stream-preparation utility for a source's
+ * `transform` option. It turns an intermittent activity signal into a
+ * sustained active/idle state and reports how long that state has held, in
+ * place, allocating nothing per message.
+ *
+ * Why it exists: many plant questions reduce to "has this thing shown
+ * activity recently, and for how long?" — is the conveyor line running (a
+ * pulse toggled lately), is a sensor dead or stuck (its value has not changed
+ * in a long time), is a machine idle (its meter has stopped advancing). These
+ * are one measurement read from two ends: track the time since the last
+ * activity; recent means active, stale means idle/dead. This utility is that
+ * one measurement.
+ *
+ * What counts as "activity": a watched field's value CHANGED since the
+ * previous message. With several fields, any one changing is activity.
+ * `epsilon` ignores a numeric change smaller than itself (consecutive-step
+ * jitter). A field with no value this message (null / undefined / NaN)
+ * contributes no activity and does not disturb the baseline.
+ *
+ * The state model: hold "active" for `windowSec` after the last activity.
+ * `active` starts false and turns true only once a change has actually been
+ * observed — a gate never claims "running" without evidence, and a signal
+ * that never changes reads as never-active (dead). Reported per message:
+ *   active         is it active now (a change within the window)
+ *   activeFor      ms the current active run has lasted (0 when idle)
+ *   sinceActivity  ms since the last activity (null before any; the "stale" end)
+ *   activeStart    epoch-ms clock reading when the current active run began. Unlike
+ *                  the others it HOLDS its value while idle, keeping the last run's
+ *                  start, so an event that ends after the run stopped can still be
+ *                  dated back to the run it belonged to (null before any activity).
+ *
+ * Scope: this is for a STREAM-LEVEL / shared signal (a line, a plant)
+ * computed once upstream of partitioning. Because it compares to the previous
+ * message, it is correct when the watched fields are the same across a tick's
+ * messages (as shared line pulses are) — the change is caught once on the
+ * tick boundary and every message of that tick gets the same reading.
+ * Per-asset activity (a different value per message) needs per-key state,
+ * which is out of scope here.
+ *
+ * Family contract (ADR-025): fields, window, and output names are captured at
+ * init; the previous-value store is one object built once. The returned
+ * function reads and writes the message in place, creates nothing per
+ * message, and returns the same message so it drops into a source `transform`
+ * slot ( row -> row ). Durations are clamped to >= 0; timestamps are assumed
+ * monotonic per stream.
+ */
+
+import { fieldNameOr, finiteNumberOr } from './validate.js';
+
+/** True when a value is "no value this message" — never counts as activity. */
+const isNoValue = function ( v ) {
+    return ( v === null ) || ( v === undefined ) || ( ( typeof v === 'number' ) && Number.isNaN( v ) );
+}; // isNoValue()
+
+/**
+ * Whether a value differs from its predecessor. Numbers compare by magnitude
+ * against `epsilon` (jitter gate); anything else compares strictly.
+ */
+const differs = function ( cur, prev, epsilon ) {
+    if ( ( typeof cur === 'number' ) && ( typeof prev === 'number' ) ) {
+        return Math.abs( cur - prev ) > epsilon;
+    }
+    return cur !== prev;
+}; // differs()
+
+const ALLOWED_WRITES = [ 'active', 'activeFor', 'sinceActivity', 'activeStart' ];
+
+/**
+ * Resolve the `from` option to a private array of watched field names.
+ * Init-time only; throws on anything that is not a name or a non-empty
+ * array of names.
+ */
+const resolveFields = function ( from ) {
+    if ( typeof from === 'string' ) {
+        if ( from === '' ) {
+            throw new Error( 'winkComposer/trackActivity: from must be a non-empty field name.' );
+        }
+        return [ from ];
+    }
+    if ( Array.isArray( from ) && ( from.length > 0 ) ) {
+        for ( let i = 0; i < from.length; i += 1 ) {
+            if ( ( typeof from[ i ] !== 'string' ) || ( from[ i ] === '' ) ) {
+                throw new Error( 'winkComposer/trackActivity: every from field must be a non-empty string.' );
+            }
+        }
+        return from.slice();
+    }
+    throw new Error( 'winkComposer/trackActivity: from must be a field name or a non-empty array of field names.' );
+}; // resolveFields()
+
+/**
+ * Resolve the `writes` option to the four output names (null = not stamped).
+ * Init-time only; rejects unknown keys and empty names.
+ */
+const resolveWrites = function ( writes ) {
+    if ( ( typeof writes !== 'object' ) || ( writes === null ) || Array.isArray( writes ) ) {
+        throw new Error( 'winkComposer/trackActivity: writes must be an object naming at least one output.' );
+    }
+    const writeKeys = Object.keys( writes );
+    if ( writeKeys.length === 0 ) {
+        throw new Error( 'winkComposer/trackActivity: writes must name at least one of active, activeFor, sinceActivity, activeStart.' );
+    }
+    for ( let i = 0; i < writeKeys.length; i += 1 ) {
+        const key = writeKeys[ i ];
+        if ( !ALLOWED_WRITES.includes( key ) ) {
+            throw new Error( 'winkComposer/trackActivity: unknown write \'' + key + '\' (allowed: active, activeFor, sinceActivity, activeStart).' );
+        }
+        if ( ( typeof writes[ key ] !== 'string' ) || ( writes[ key ] === '' ) ) {
+            throw new Error( 'winkComposer/trackActivity: writes.' + key + ' must be a non-empty field name.' );
+        }
+    }
+    return {
+        active: ( writes.active === undefined ) ? null : writes.active,
+        activeFor: ( writes.activeFor === undefined ) ? null : writes.activeFor,
+        sinceActivity: ( writes.sinceActivity === undefined ) ? null : writes.sinceActivity,
+        activeStart: ( writes.activeStart === undefined ) ? null : writes.activeStart
+    };
+}; // resolveWrites()
+
+/**
+ * Build an in-place activity-state stamper.
+ *
+ * @param {Object} options
+ * @param {string|string[]} options.from - field(s) to watch for change. Required.
+ * @param {number} options.windowSec - hold "active" this long after the last
+ *     activity (seconds). Required, positive.
+ * @param {number} [options.epsilon=0] - ignore a numeric change at or below this
+ *     between consecutive messages (a noise gate; 0 = any change counts).
+ * @param {string} [options.timestampField='timestamp'] - epoch-ms clock field.
+ * @param {Object} options.writes - names the outputs to stamp; at least one of
+ *     `active`, `activeFor`, `sinceActivity`, `activeStart`, each a non-empty field name.
+ * @returns {function( Object ): Object} transform( msg ) -> msg, mutated in place.
+ *     A non-finite timestamp writes null to the configured outputs and does not
+ *     advance the state.
+ */
+const trackActivity = function ( options ) {
+    const opts = options || {};
+    const fields = resolveFields( opts.from );
+    const windowSec = finiteNumberOr( opts.windowSec, undefined, 'trackActivity', 'windowSec' );
+    if ( windowSec <= 0 ) {
+        throw new Error( 'winkComposer/trackActivity: windowSec must be a positive number.' );
+    }
+    const windowMs = windowSec * 1000;
+    const epsilon = finiteNumberOr( opts.epsilon, 0, 'trackActivity', 'epsilon' );
+    if ( epsilon < 0 ) {
+        throw new Error( 'winkComposer/trackActivity: epsilon must be a non-negative number.' );
+    }
+    const tsField = fieldNameOr( opts.timestampField, 'timestamp', 'trackActivity', 'timestampField' );
+    const w = resolveWrites( opts.writes );
+
+    // State captured at init — the hot path allocates nothing. prev is a private
+    // dictionary of last-seen values ( external field-name keys -> Object.create(null) ).
+    const n = fields.length;
+    const prev = Object.create( null );
+    let lastActivityTs = null;
+    let activeStartTs = null;
+    let wasActive = false;
+
+    return function ( msg ) {
+        const t = msg[ tsField ];
+        if ( !Number.isFinite( t ) ) {
+            if ( w.active !== null ) {
+                msg[ w.active ] = null;
+            }
+            if ( w.activeFor !== null ) {
+                msg[ w.activeFor ] = null;
+            }
+            if ( w.sinceActivity !== null ) {
+                msg[ w.sinceActivity ] = null;
+            }
+            if ( w.activeStart !== null ) {
+                msg[ w.activeStart ] = null;
+            }
+            return msg;
+        }
+
+        let activity = false;
+        for ( let i = 0; i < n; i += 1 ) {
+            const f = fields[ i ];
+            const cur = msg[ f ];
+            if ( !isNoValue( cur ) ) {
+                const p = prev[ f ];
+                if ( p === undefined ) {
+                    prev[ f ] = cur;     // first value for this field — seed, no change
+                } else {
+                    if ( differs( cur, p, epsilon ) ) {
+                        activity = true;
+                    }
+                    prev[ f ] = cur;
+                }
+            }
+        }
+
+        if ( activity ) {
+            lastActivityTs = t;
+        }
+        const active = ( lastActivityTs !== null ) && ( ( t - lastActivityTs ) <= windowMs );
+        if ( active && ( wasActive === false ) ) {
+            activeStartTs = t;       // rising edge — the active run begins now
+        }
+        wasActive = active;
+
+        if ( w.active !== null ) {
+            msg[ w.active ] = active;
+        }
+        if ( w.activeFor !== null ) {
+            msg[ w.activeFor ] = active ? Math.max( 0, t - activeStartTs ) : 0;
+        }
+        if ( w.sinceActivity !== null ) {
+            msg[ w.sinceActivity ] = ( lastActivityTs === null ) ? null : Math.max( 0, t - lastActivityTs );
+        }
+        if ( w.activeStart !== null ) {
+            msg[ w.activeStart ] = activeStartTs;
+        }
+        return msg;
+    };
+}; // trackActivity()
+
+export { trackActivity };
+export default trackActivity;

package/src/tools/stream-prep/validate.js

@@ -0,0 +1,76 @@
+// src/tools/stream-prep/validate.js
+
+/**
+ * @fileoverview Shared init-time validation helpers for the stream-preparation
+ * utilities. Nothing here runs on the hot path — every helper is called once,
+ * inside a factory, and throws immediately with the calling utility's name
+ * leading the message, so a bad config names its own site (fail-fast, the
+ * ADR-025 family contract; same error style as the training utilities).
+ */
+
+const MINUTES_PER_DAY = 1440;
+
+/**
+ * Resolve an optional field-name option: undefined takes the fallback; the
+ * result must be a non-empty string.
+ *
+ * @param {*} value - the option as given
+ * @param {string} fallback - default when the option is undefined
+ * @param {string} ctx - calling utility name, for the error message
+ * @param {string} name - option name, for the error message
+ * @returns {string} the validated field name
+ */
+const fieldNameOr = function ( value, fallback, ctx, name ) {
+    const out = ( value === undefined ) ? fallback : value;
+    if ( ( typeof out !== 'string' ) || ( out === '' ) ) {
+        throw new Error( 'winkComposer/' + ctx + ': ' + name + ' must be a non-empty string.' );
+    }
+    return out;
+}; // fieldNameOr()
+
+/**
+ * Resolve an optional numeric option: undefined takes the fallback; the
+ * result must be a finite number.
+ *
+ * @param {*} value - the option as given
+ * @param {number} fallback - default when the option is undefined
+ * @param {string} ctx - calling utility name, for the error message
+ * @param {string} name - option name, for the error message
+ * @returns {number} the validated number
+ */
+const finiteNumberOr = function ( value, fallback, ctx, name ) {
+    const out = ( value === undefined ) ? fallback : value;
+    if ( ( typeof out !== 'number' ) || !Number.isFinite( out ) ) {
+        throw new Error( 'winkComposer/' + ctx + ': ' + name + ' must be a finite number.' );
+    }
+    return out;
+}; // finiteNumberOr()
+
+/**
+ * Validate a shift schedule's boundary list: a non-empty array of strictly
+ * ascending minutes-of-day, each in [0, 1440). Returns a private copy so the
+ * caller's hot path cannot be disturbed by later mutation of the original.
+ *
+ * @param {*} boundariesMin - the option as given
+ * @param {string} ctx - calling utility name, for the error message
+ * @returns {number[]} a validated private copy
+ */
+const validatedBoundaries = function ( boundariesMin, ctx ) {
+    if ( !Array.isArray( boundariesMin ) || ( boundariesMin.length === 0 ) ) {
+        throw new Error( 'winkComposer/' + ctx + ': boundariesMin must be a non-empty array.' );
+    }
+    let prev = -1;
+    for ( let i = 0; i < boundariesMin.length; i += 1 ) {
+        const b = boundariesMin[ i ];
+        if ( ( typeof b !== 'number' ) || !Number.isFinite( b ) || ( b < 0 ) || ( b >= MINUTES_PER_DAY ) ) {
+            throw new Error( 'winkComposer/' + ctx + ': each boundary must be a minute-of-day in [0, 1440).' );
+        }
+        if ( b <= prev ) {
+            throw new Error( 'winkComposer/' + ctx + ': boundariesMin must be strictly ascending.' );
+        }
+        prev = b;
+    }
+    return boundariesMin.slice();
+}; // validatedBoundaries()
+
+export { fieldNameOr, finiteNumberOr, validatedBoundaries };