@winkjs/composer 0.0.2 → 0.4.1

package/src/core/source-manager/test-harness/comparator.js

@@ -0,0 +1,226 @@
+// core/source-manager/test-harness/comparator.js
+
+/**
+ * @fileoverview Check tool for testHarness.
+ *
+ * Takes the messages the harness generated (the ground truth) and
+ * one capture per sink (terminal stdout, MQTT subscriber messages,
+ * QuestDB rows) and checks each sink's output against the harness
+ * input, matched on `_harnessId`.
+ *
+ * Why ground-truth-driven: the harness deterministically produced a
+ * known sequence of messages. The "correct" output for any sink is
+ * exactly that sequence. Comparing sinks to each other only catches
+ * alignment drift; comparing each sink to the harness input also
+ * catches a whole pipeline going wrong in the same way (a uniform
+ * error every sink shares).
+ *
+ * Per-message rules:
+ *  - Every checked sink must have the message (matched by _harnessId).
+ *  - For each column declared in the asset class:
+ *      - float64 with declared resolution: the sink's value must
+ *        round to the same grid step as the harness input.
+ *      - other numerics, strings, bools, timestamps: exact match.
+ *  - Fuzz messages (those carrying `_harnessFuzzPattern`) skip the
+ *    value check — fuzz inputs legitimately produce different sink
+ *    outputs (NaN becomes "NaN" in terminal, null in MQTT JSON,
+ *    dropped in QDB). The check is "every sink saw it" only.
+ *
+ * The report:
+ *   {
+ *       ok: boolean,
+ *       errors: [ '<diagnostic line>', ... ],
+ *       summary: {
+ *           messageCount,
+ *           sinkCounts: { terminal, mqtt, qdb }
+ *       }
+ *   }
+ *
+ * Error strings name the harnessId, the column, the harness input,
+ * the sink's observed value, and the declared resolution when it
+ * applies.
+ */
+
+const HARNESS_ID_FIELD = '_harnessId';
+const FUZZ_MARKER_FIELD = '_harnessFuzzPattern';
+
+/**
+ * Walks captured terminal stdout and pulls out each message that
+ * was printed in pretty-JSON form (the terminal emitter's
+ * `verbose: true` output).
+ *
+ * Relies on a flat-message layout: each top-level `{` and matching
+ * `}` sit at column 0; everything in between is indented. We
+ * collect lines between those bookends and JSON.parse the result.
+ *
+ * @param {string} text - Captured stdout buffer
+ * @returns {Object[]} Parsed messages in the order they appeared
+ */
+export const parseTerminalOutput = function ( text ) {
+    const messages = [];
+    let buffer = null;
+
+    const lines = text.split( '\n' );
+    for ( let i = 0; i < lines.length; i += 1 ) {
+        const line = lines[ i ];
+        if ( line === '{' ) {
+            buffer = `${line}\n`;
+        } else if ( line === '}' && buffer !== null ) {
+            buffer += line;
+            messages.push( JSON.parse( buffer ) );
+            buffer = null;
+        } else if ( buffer !== null ) {
+            buffer += `${line}\n`;
+        }
+    }
+
+    return messages;
+};
+
+/**
+ * Returns an array indexed by message harness id. Each entry is the
+ * parsed message; missing ids show up as `undefined`. The id field
+ * is fixed (`_harnessId`) — the harness always adds it.
+ *
+ * @param {Object[]} messages - Parsed messages from one sink
+ * @returns {Map<number, Object>}
+ */
+export const indexById = function ( messages ) {
+    const map = new Map();
+    for ( const msg of messages ) {
+        const id = msg[ HARNESS_ID_FIELD ];
+        if ( id !== undefined && id !== null ) {
+            map.set( id, msg );
+        }
+    }
+    return map;
+};
+
+/**
+ * Tells whether a column should be compared with resolution-aware
+ * tolerance. Only float64 columns with a declared resolution use
+ * the grid-snap check; everything else uses exact equality.
+ */
+const usesResolutionTolerance = function ( columnSpec ) {
+    return columnSpec && columnSpec.type === 'float64' && typeof columnSpec.resolution === 'number';
+};
+
+/**
+ * For two float values that should sit on the same resolution grid,
+ * tells whether they round to the same grid step. Equivalent to
+ * "within half a resolution step of each other".
+ */
+const onSameGrid = function ( a, b, resolution ) {
+    if ( typeof a !== 'number' || typeof b !== 'number' ) return false;
+    if ( Number.isNaN( a ) || Number.isNaN( b ) ) return Number.isNaN( a ) === Number.isNaN( b );
+    return Math.round( a / resolution ) === Math.round( b / resolution );
+};
+
+/**
+ * Returns true when the sink's value matches the harness's value,
+ * applying resolution tolerance for float64 columns that declare it.
+ */
+const valuesAgree = function ( harnessValue, sinkValue, columnSpec ) {
+    if ( usesResolutionTolerance( columnSpec ) ) {
+        return onSameGrid( harnessValue, sinkValue, columnSpec.resolution );
+    }
+    if ( Number.isNaN( harnessValue ) || Number.isNaN( sinkValue ) ) {
+        return Number.isNaN( harnessValue ) === Number.isNaN( sinkValue );
+    }
+    return harnessValue === sinkValue;
+};
+
+/**
+ * Builds a diagnostic line for one column where a sink's value
+ * disagrees with the harness input.
+ */
+const formatColumnError = function ( harnessId, sinkName, columnName, columnSpec, harnessValue, sinkValue ) {
+    const head = `harnessId=${harnessId}, column '${columnName}' — harness sent ${JSON.stringify( harnessValue )}, ${sinkName} saw ${JSON.stringify( sinkValue )}`;
+    if ( usesResolutionTolerance( columnSpec ) ) {
+        return `${head}, declared resolution: ${columnSpec.resolution} — beyond resolution`;
+    }
+    return `${head} — values differ`;
+};
+
+/**
+ * Compares one sink's captured messages against the harness inputs,
+ * column by column. Returns the error strings for this sink.
+ */
+const checkSinkAgainstInputs = function ( sinkName, sinkIndex, harnessIndex, columnNames, columns ) {
+    const errors = [];
+    for ( const [ harnessId, harnessMsg ] of harnessIndex.entries() ) {
+        const sinkMsg = sinkIndex.get( harnessId );
+        if ( !sinkMsg ) {
+            errors.push( `harnessId=${harnessId} missing from ${sinkName}` );
+            continue; // eslint-disable-line no-continue
+        }
+        // Fuzz messages skip the column-by-column check — presence
+        // alone is the fuzz assertion.
+        if ( harnessMsg[ FUZZ_MARKER_FIELD ] !== undefined ) {
+            continue; // eslint-disable-line no-continue
+        }
+        for ( const columnName of columnNames ) {
+            if ( columnName === HARNESS_ID_FIELD ) continue; // eslint-disable-line no-continue
+            const harnessValue = harnessMsg[ columnName ];
+            const sinkValue = sinkMsg[ columnName ];
+            if ( !valuesAgree( harnessValue, sinkValue, columns[ columnName ] ) ) {
+                errors.push( formatColumnError( harnessId, sinkName, columnName, columns[ columnName ], harnessValue, sinkValue ) );
+            }
+        }
+    }
+    return errors;
+};
+
+/**
+ * Checks each captured sink against the harness inputs (the ground
+ * truth). Skips per-column value checks for fuzz messages — those
+ * legitimately produce different sink outputs.
+ *
+ * @param {Object[]} harnessInputs       - Messages the harness produced (ground truth)
+ * @param {Object} captures
+ * @param {string}   [captures.terminal] - Raw stdout buffer
+ * @param {Object[]} [captures.mqtt]     - Messages received over MQTT
+ * @param {Object[]} [captures.qdb]      - Rows queried from QuestDB
+ * @param {Object} assetClass            - Declares column types and resolutions
+ * @returns {{ok: boolean, errors: string[], summary: Object}}
+ */
+export const compareCaptures = function ( harnessInputs, captures, assetClass ) {
+    const harnessIndex = indexById( harnessInputs || [] );
+
+    const sinkIndices = {};
+    const sinkCounts = {};
+
+    if ( captures.terminal !== undefined ) {
+        const parsed = parseTerminalOutput( captures.terminal );
+        sinkIndices.terminal = indexById( parsed );
+        sinkCounts.terminal = parsed.length;
+    }
+    if ( captures.mqtt !== undefined ) {
+        sinkIndices.mqtt = indexById( captures.mqtt );
+        sinkCounts.mqtt = captures.mqtt.length;
+    }
+    if ( captures.qdb !== undefined ) {
+        sinkIndices.qdb = indexById( captures.qdb );
+        sinkCounts.qdb = captures.qdb.length;
+    }
+
+    const columnNames = ( assetClass && assetClass.columns ) ? Object.keys( assetClass.columns ) : [];
+    const columns = ( assetClass && assetClass.columns ) ? assetClass.columns : {};
+
+    const errors = [];
+    for ( const sinkName of Object.keys( sinkIndices ) ) {
+        const sinkErrors = checkSinkAgainstInputs(
+            sinkName, sinkIndices[ sinkName ], harnessIndex, columnNames, columns
+        );
+        errors.push( ...sinkErrors );
+    }
+
+    return {
+        ok: errors.length === 0,
+        errors,
+        summary: {
+            messageCount: harnessIndex.size,
+            sinkCounts
+        }
+    };
+};

package/src/core/source-manager/test-harness/field-generator.js

@@ -0,0 +1,85 @@
+// core/source-manager/test-harness/field-generator.js
+
+/**
+ * @fileoverview Generates one value for one field of a generated message.
+ *
+ * Each call returns a value of the field's declared type, drawn from
+ * the random generator (or built from message index for timestamps).
+ * Float values snap to the declared resolution so the harness's output
+ * matches what real sensors would produce — and what QuestDB will
+ * store after its own quantization.
+ *
+ * The field spec shape (`type`, `range`, `resolution`, `values`) is
+ * enforced at startup by `validate.js` (FIELD_SPEC_SCHEMA).
+ */
+
+const generateFloat = function ( spec, prng ) {
+    const range = spec.range || [ 0, 1 ];
+    const raw = prng.floatInRange( range[ 0 ], range[ 1 ] );
+    if ( spec.resolution ) {
+        // Snap to grid. Sensors quantize, so generated data should
+        // too — otherwise the cross-sink check fails on values that
+        // QuestDB rounds and terminal does not.
+        return Math.round( raw / spec.resolution ) * spec.resolution;
+    }
+    return raw;
+};
+
+const generateInt = function ( spec, prng ) {
+    const range = spec.range || [ 0, 100 ];
+    return prng.intInRange( range[ 0 ], range[ 1 ] );
+};
+
+const generateBool = function ( spec, prng ) {
+    if ( spec.values ) {
+        return prng.pickFrom( spec.values );
+    }
+    return prng.next() < 0.5;
+};
+
+const generateString = function ( spec, prng ) {
+    // Strings always need an explicit `values` list — validate.js
+    // enforces this at startup.
+    return prng.pickFrom( spec.values );
+};
+
+const generateTimestamp = function ( spec, msgIndex, intervalMs ) {
+    if ( spec.mode === 'static' ) {
+        return spec.seedValue || 0;
+    }
+    // monotonic-ms (default): timestamps go up by the message
+    // gap, or 1ms per message when the harness is running flat
+    // out (intervalMs = 0). First message gets the seed value.
+    const start = spec.seedValue || 0;
+    const step = ( intervalMs > 0 ) ? intervalMs : 1;
+    return start + ( ( msgIndex - 1 ) * step );
+};
+
+/**
+ * Returns one generated value for the given field spec.
+ *
+ * @param {Object} fieldSpec  - One entry from messageTemplate.fields
+ * @param {Object} prng       - The random generator (from prng.js)
+ * @param {number} msgIndex   - 1-based index of the current message
+ * @param {number} intervalMs - Gap between messages; used as the
+ *                              timestamp step for monotonic-ms mode
+ * @returns {*} A value of the declared type
+ */
+export const generateField = function ( fieldSpec, prng, msgIndex, intervalMs ) {
+    switch ( fieldSpec.type ) {
+        case 'float64':
+            return generateFloat( fieldSpec, prng );
+        case 'int64':
+            return generateInt( fieldSpec, prng );
+        case 'bool':
+            return generateBool( fieldSpec, prng );
+        case 'string':
+            return generateString( fieldSpec, prng );
+        case 'timestamp':
+            return generateTimestamp( fieldSpec, msgIndex, intervalMs );
+        default:
+            // Unreachable in practice — validate.js rejects unknown
+            // types at startup. Kept for clarity at the boundary.
+            throw new Error( `testHarness: unknown field type "${fieldSpec.type}"` );
+    }
+};

package/src/core/source-manager/test-harness/fuzz.js

@@ -0,0 +1,87 @@
+// core/source-manager/test-harness/fuzz.js
+
+/**
+ * @fileoverview Fuzz patterns for testHarness.
+ *
+ * When a test enables fuzz, the harness injects one bad value into
+ * the target column every Nth message. The patterns below are the
+ * minimal set we agreed on — common ways production data goes wrong
+ * (null, NaN, JS quirks). For each fuzz message, the harness picks
+ * one pattern in rotation, so over the run every pattern gets
+ * exercised the same number of times.
+ *
+ * If the chosen pattern does not make sense for the target field's
+ * type (for example, NaN on a string field), we fall back to null —
+ * always valid, always a useful "bad value" — so the rotation
+ * still progresses.
+ *
+ * Both the pattern set and the null fallback were settled as design
+ * decisions on 2026-04-29.
+ */
+
+/**
+ * Names of the six fuzz patterns, in rotation order.
+ * @type {string[]}
+ */
+export const FUZZ_PATTERN_NAMES = [
+    'null',
+    'NaN',
+    'string-where-number',
+    'undefined',
+    'infinity',
+    'empty-string'
+];
+
+const FUZZ_VALUES = {
+    'null': null,
+    'NaN': NaN,
+    'string-where-number': 'not-a-number',
+    'undefined': undefined,
+    'infinity': Infinity,
+    'empty-string': ''
+};
+
+/**
+ * Tells whether a given fuzz pattern makes sense for a given
+ * declared field type. Patterns that do not match the type fall
+ * back to null at injection time.
+ *
+ * @param {string} patternName
+ * @param {string} fieldType - 'float64' | 'int64' | 'bool' | 'string' | 'timestamp'
+ * @returns {boolean}
+ */
+export const isCompatible = function ( patternName, fieldType ) {
+    switch ( patternName ) {
+        case 'null':
+        case 'undefined':
+            return true;
+        case 'NaN':
+        case 'infinity':
+            return fieldType === 'float64';
+        case 'string-where-number':
+            return fieldType === 'float64' || fieldType === 'int64';
+        case 'empty-string':
+            return fieldType === 'string';
+        default:
+            return false;
+    }
+};
+
+/**
+ * Replaces the target column on the message with a fuzz value, and
+ * adds a `_harnessFuzzPattern` field naming the pattern that was
+ * applied. Mutates `msg` in place.
+ *
+ * @param {Object} msg          - The message being built
+ * @param {string} fuzzTarget   - Name of the column to fuzz
+ * @param {Object} targetSpec   - The target column's spec from messageTemplate.fields
+ * @param {number} patternIndex - Index into FUZZ_PATTERN_NAMES (rotates)
+ */
+export const applyFuzz = function ( msg, fuzzTarget, targetSpec, patternIndex ) {
+    const patternName = FUZZ_PATTERN_NAMES[ patternIndex ];
+    const compatible = isCompatible( patternName, targetSpec.type );
+    const value = compatible ? FUZZ_VALUES[ patternName ] : null;
+
+    msg[ fuzzTarget ] = value;
+    msg._harnessFuzzPattern = patternName;  // eslint-disable-line no-underscore-dangle
+};

package/src/core/source-manager/test-harness/index.js

@@ -0,0 +1,115 @@
+// core/source-manager/test-harness/index.js
+
+/**
+ * @fileoverview testHarness Source Adapter.
+ *
+ * A synthetic source used by integration tests to push messages
+ * through every sink and check that all sinks agree. The harness
+ * does not read from a file or a network — it invents messages on
+ * demand from a test-author-supplied `messageTemplate`.
+ *
+ * Each generated message carries a running number `_harnessId` so
+ * the cross-sink check tool can match the same message in every
+ * sink, regardless of arrival order.
+ *
+ * Built native to ADR-018's source role — same
+ * `stopFn({ timeout })` shape as CSV and MQTT sources, structured
+ * `onStatus` lifecycle phases, classified `err.code` on setup
+ * throws (`INVALID_CONFIG`). Module exports follow the contract: `id`,
+ * `configSchema`, `start`, `durabilityClass`, and the default
+ * aggregate referencing the same constants.
+ *
+ * Durability (ADR-018): `'best-effort'` — the harness keeps no recovery
+ * state; a crashed run is simply re-generated (same seed, same
+ * messages).
+ *
+ * @example
+ *   import { flow, testHarness } from '@winkjs/composer';
+ *
+ *   const assetClass = {
+ *       columns: {
+ *           _harnessId:  { type: 'int64' },
+ *           temperature: { type: 'float64', resolution: 0.01 }
+ *       }
+ *   };
+ *
+ *   flow( 'check' )
+ *       .assetClass( assetClass )
+ *       .source( testHarness, {
+ *           messageTemplate: {
+ *               seed: 42,
+ *               messageCount: 100,
+ *               fields: {
+ *                   temperature: { type: 'float64', range: [ 20, 30 ], resolution: 0.01 }
+ *               }
+ *           },
+ *           assetClass
+ *       } )
+ *       .run();
+ */
+
+import { start } from './start.js';
+import { MESSAGE_TEMPLATE_SCHEMA, ASSET_CLASS_SCHEMA } from './validate.js';
+
+/**
+ * Source identifier — used by the flow runtime for lookup.
+ * @type {string}
+ */
+export const id = 'testHarness';
+
+/**
+ * Crash-survival class per ADR-018. For a source the value describes
+ * the input it can recover after a disconnect: the harness recovers
+ * nothing — a crashed run is re-generated deterministically.
+ * @type {string}
+ */
+export const durabilityClass = 'best-effort';
+
+/**
+ * Schema for the harness's public config — the `messageTemplate`
+ * and `assetClass` it accepts, plus the caller-suppliable `onStatus`
+ * and `shutdownOnComplete`. Exposed for DSL-time validation.
+ *
+ * `_propertyNames` rejects unknown keys at DSL time (the validator's
+ * only unknown-key mechanism, validate.js:68-77) — added by the
+ * 2026-07-09 uniformity sweep. The retired `onComplete` key is
+ * rejected here: completion travels `onStatus` as
+ * `{phase: 'complete', count}` per ADR-018. Runtime-injected
+ * callbacks (`onMessage`, `onShutdown`) are deliberately absent.
+ *
+ * The harness's runtime entry (`start`) re-validates with
+ * `validateMessageTemplate` and `validateAssetClass` so any
+ * problem fails at startup with classified `err.code`.
+ */
+export const configSchema = {
+    _propertyNames: [
+        'messageTemplate',
+        'assetClass',
+        'onStatus',
+        'shutdownOnComplete'
+    ],
+    messageTemplate: {
+        type: 'object',
+        required: true,
+        properties: MESSAGE_TEMPLATE_SCHEMA
+    },
+    assetClass: {
+        type: 'object',
+        required: true,
+        properties: ASSET_CLASS_SCHEMA
+    },
+    onStatus: {
+        type: 'function',
+        required: false,
+        error: 'onStatus must be a function'
+    },
+    shutdownOnComplete: {
+        type: 'boolean',
+        required: false,
+        error: 'shutdownOnComplete must be a boolean'
+    }
+};
+
+export { start };
+
+export default { id, configSchema, durabilityClass, start };

package/src/core/source-manager/test-harness/prng.js

@@ -0,0 +1,57 @@
+// core/source-manager/test-harness/prng.js
+
+/* eslint-disable no-bitwise -- Mulberry32 is fundamentally a bit-shuffling PRNG; bitwise ops are intentional and load-bearing. */
+
+/**
+ * @fileoverview Seeded random number generator for testHarness.
+ *
+ * Tests need to be reproducible: the same seed must give the same
+ * sequence of numbers every run. We use Mulberry32 — a small, fast
+ * generator with 32-bit state. Good enough for test data; not
+ * suitable for anything cryptographic.
+ *
+ * Reference: https://github.com/bryc/code/blob/master/jshash/PRNGs.md
+ */
+
+/**
+ * Builds a random-number generator from a numeric seed.
+ *
+ * @param {number} seed - any finite number; same seed → same sequence
+ * @returns {{next: function(): number, intInRange: function(number, number): number, floatInRange: function(number, number): number, pickFrom: function(Array): *}}
+ */
+export const createPrng = function ( seed ) {
+    // Force the seed into an unsigned 32-bit integer so the maths
+    // below behaves the same on every platform.
+    let state = seed >>> 0;
+
+    const next = function () {
+        state = ( state + 0x6D2B79F5 ) | 0;
+        let t = state;
+        t = Math.imul( t ^ ( t >>> 15 ), t | 1 );
+        t ^= t + Math.imul( t ^ ( t >>> 7 ), t | 61 );
+        return ( ( t ^ ( t >>> 14 ) ) >>> 0 ) / 4294967296;
+    };
+
+    /**
+     * Whole number in the inclusive range [min, max].
+     */
+    const intInRange = function ( min, max ) {
+        return Math.floor( min + ( next() * ( ( max - min ) + 1 ) ) );
+    };
+
+    /**
+     * Decimal number in the half-open range [min, max).
+     */
+    const floatInRange = function ( min, max ) {
+        return min + ( next() * ( max - min ) );
+    };
+
+    /**
+     * Picks one element from a non-empty array.
+     */
+    const pickFrom = function ( arr ) {
+        return arr[ Math.floor( next() * arr.length ) ];
+    };
+
+    return { next, intInRange, floatInRange, pickFrom };
+};