@winkjs/composer 0.0.2 → 0.4.1

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

@@ -0,0 +1,232 @@
+// core/source-manager/test-harness/start.js
+
+/**
+ * @fileoverview Synthetic source for end-to-end contract checks.
+ *
+ * testHarness invents messages on demand and feeds them to the
+ * pipeline. It does not read from a file or a network — it is a
+ * verification adapter, used by integration tests to push messages
+ * through every sink and check that all sinks agree.
+ *
+ * Each generated message carries a running number `_harnessId` so
+ * the cross-sink check tool can find the same message in every
+ * sink, regardless of arrival order. Field values come from the
+ * test author's `messageTemplate`. Tests can opt into a small set
+ * of fuzz patterns that inject bad values every Nth message; with
+ * fuzz on, the only check is "no adapter crashed".
+ *
+ * Adapter contract (ADR-018, source role):
+ * - Every `onStatus` payload carries the uniform structured shape per
+ *   ADR-018: `{status: 'green' | 'yellow' | 'red', connected,
+ *   phase}`; the error path adds `error: {code, message}`. One payload
+ *   rule, no exceptions (uniformity sweep, 2026-07-09).
+ * - Lifecycle phases:
+ *     `phase: 'starting'`   — harness is about to begin
+ *     `phase: 'generating'` — first message about to be sent
+ *     `phase: 'complete'`   — all messages sent (`connected: false`);
+ *                             carries the uniform `count` of produced
+ *                             messages (per ADR-018 there is no
+ *                             onComplete callback)
+ *     `phase: 'errored'`    — terminal red: the run loop failed and
+ *                             generation stopped (the ADR-018 two-tier
+ *                             rule)
+ *     `phase: 'stopped'`    — yellow status when forced to stop
+ *
+ * `err.code` vocabulary (per-adapter, listed here per ADR-018):
+ * - `INVALID_CONFIG`   — setup-time; bad messageTemplate or asset
+ *                        class. Thrown synchronously from start().
+ * - `GENERATOR_ERROR`  — runtime; a downstream `onMessage` call
+ *                        threw inside the loop. Routed through
+ *                        onStatus, not re-thrown.
+ *
+ * Design decisions date from 2026-04-29. The `messageTemplate` shape
+ * is enforced at startup by `validate.js`; the per-field spec shape
+ * is documented in `field-generator.js`.
+ */
+
+import { createPrng } from './prng.js';
+import { generateField } from './field-generator.js';
+import { applyFuzz, FUZZ_PATTERN_NAMES } from './fuzz.js';
+import { validateMessageTemplate, validateAssetClass } from './validate.js';
+
+const DEFAULT_MESSAGE_COUNT = 1000;
+const DEFAULT_INTERVAL_MS   = 0;
+const DEFAULT_FUZZ_INTERVAL = 0;
+const DEFAULT_STOP_TIMEOUT  = 5000;
+
+/**
+ * Starts the synthetic source.
+ *
+ * @param {Object}   config
+ * @param {Object}   config.messageTemplate       - Required. Shape enforced by validate.js.
+ * @param {Object}   config.assetClass            - Required. Must declare `_harnessId` as int64.
+ * @param {Function} config.onMessage             - Required. Pipeline-injected handler.
+ * @param {Function} [config.onStatus]            - Status callback (structured shape per ADR-018);
+ *                                                  completion arrives as `{phase: 'complete', count}`.
+ * @param {Function} [config.onShutdown]          - Pipeline shutdown hook (injected by runtime).
+ * @param {boolean}  [config.shutdownOnComplete=true] - Auto-shutdown pipeline when generation ends.
+ * @returns {Function} stopFn — accepts `{ timeout }`, returns Promise resolving when stopped.
+ */
+export const start = function ( config ) {
+    const {
+        messageTemplate,
+        assetClass,
+        onMessage,
+        onStatus = null,
+        onShutdown = null,
+        shutdownOnComplete = true
+    } = config;
+
+    // Setup-time validation. Both throw INVALID_CONFIG on any
+    // problem, listing every issue found.
+    validateMessageTemplate( messageTemplate );
+    validateAssetClass( assetClass );
+
+    if ( typeof onMessage !== 'function' ) {
+        const err = new Error( 'testHarness: onMessage must be a function' );
+        err.code = 'INVALID_CONFIG';
+        throw err;
+    }
+
+    // Pull out template options with defaults.
+    const seed         = messageTemplate.seed;
+    const messageCount = messageTemplate.messageCount ?? DEFAULT_MESSAGE_COUNT;
+    const intervalMs   = messageTemplate.intervalMs   ?? DEFAULT_INTERVAL_MS;
+    const fuzzInterval = messageTemplate.fuzzInterval ?? DEFAULT_FUZZ_INTERVAL;
+    const fuzzTarget   = messageTemplate.fuzzTarget   ?? null;
+    const fields       = messageTemplate.fields;
+    const fieldNames   = Object.keys( fields );
+
+    // Stop / finished bookkeeping. `finished` resolves when the run
+    // loop fully exits (success or error) — the stop function races
+    // it against the timeout, mirroring CSV's shape (ADR-018).
+    const prng = createPrng( seed );
+    let stopped = false;
+    let sentCount = 0;
+    let resolveFinished;
+    const finished = new Promise( ( resolve ) => {
+        resolveFinished = resolve;
+    } );
+
+    if ( onStatus ) onStatus( {
+        status: 'green',
+        connected: true,
+        phase: 'starting',
+        messageCount,
+        fuzzInterval
+    } );
+
+    const run = async function () {
+        if ( onStatus ) onStatus( {
+            status: 'green',
+            connected: true,
+            phase: 'generating'
+        } );
+
+        for ( let i = 1; i <= messageCount; i += 1 ) {
+            if ( stopped ) break;
+
+            const msg = Object.create( null );
+            msg._harnessId = i;  // eslint-disable-line no-underscore-dangle
+
+            for ( const name of fieldNames ) {
+                msg[ name ] = generateField( fields[ name ], prng, i, intervalMs );
+            }
+
+            // Fuzz: inject one bad value every Nth message.
+            if ( fuzzInterval > 0 && i % fuzzInterval === 0 ) {
+                const fuzzNumber = i / fuzzInterval;
+                const patternIndex = ( fuzzNumber - 1 ) % FUZZ_PATTERN_NAMES.length;
+                applyFuzz( msg, fuzzTarget, fields[ fuzzTarget ], patternIndex );
+            }
+
+            // eslint-disable-next-line no-await-in-loop -- Source must wait for the consumer before sending the next message; flooding the consumer would defeat the purpose of an integration check.
+            await onMessage( msg );
+            sentCount = i;
+
+            if ( intervalMs > 0 && !stopped ) {
+                // eslint-disable-next-line no-await-in-loop -- Paced send between messages is part of the contract for tests that exercise idle-flush timing.
+                await new Promise( ( r ) => setTimeout( r, intervalMs ) );
+            }
+        }
+
+        // Completion travels onStatus with the uniform `count` field
+        // (per ADR-018 there is no onComplete callback).
+        if ( onStatus ) onStatus( {
+            status: 'green',
+            connected: false,
+            phase: 'complete',
+            count: sentCount
+        } );
+
+        if ( shutdownOnComplete && onShutdown ) {
+            await onShutdown();
+        }
+    };
+
+    // Kick off. Failures inside the loop come from a downstream
+    // onMessage handler (the harness itself has no transport that
+    // can fail). Route through onStatus so the test sees the error
+    // without losing it. Always resolve `finished` so stop() can
+    // wait on it.
+    run().catch( ( err ) => {
+        const message = ( err && err.message ) ? err.message : String( err );
+        if ( onStatus ) {
+            // Terminal red: generation stopped. Uniform payload with
+            // phase 'errored' per the ADR-018 two-tier rule.
+            onStatus( {
+                status: 'red',
+                connected: false,
+                phase: 'errored',
+                error: { code: 'GENERATOR_ERROR', message }
+            } );
+        } else {
+            console.error( `testHarness error [GENERATOR_ERROR]: ${message}` );
+        }
+    } ).finally( () => {
+        resolveFinished();
+    } );
+
+    // Stop function with `{ timeout }` symmetry per ADR-018.
+    //
+    // What it does:
+    //  - Asks the loop to stop at the next message by setting `stopped`.
+    //  - Waits for the loop to finish. If it finishes within `timeout`
+    //    ms, the stop returns right away.
+    //  - If the loop is stuck inside an `await onMessage(msg)` that
+    //    never returns, the time budget runs out. The stop returns
+    //    anyway so the rest of the shutdown can proceed.
+    //  - When the budget runs out, sends a yellow status so callers
+    //    can see the stop was forced rather than clean.
+    //
+    // The timer is `unref()`ed so it does not keep Node alive while
+    // the loop is finishing in time.
+    return function ( { timeout = DEFAULT_STOP_TIMEOUT } = {} ) {
+        stopped = true;
+        return new Promise( ( resolve ) => {
+            let settled = false;
+            let forceTimer = null;
+            const settle = function () {
+
+                /* c8 ignore next -- defensive: in normal lifecycle, settle is invoked exactly once (timer fires OR finished resolves; clean path clears the timer before it can fire). The guard protects against a race that requires both paths to fire concurrently, which has no producer in the current design. */
+                if ( settled ) return;
+                settled = true;
+                if ( forceTimer ) clearTimeout( forceTimer );
+                resolve();
+            };
+            forceTimer = setTimeout( () => {
+                if ( onStatus ) {
+                    onStatus( {
+                        status: 'yellow',
+                        connected: false,
+                        phase: 'stopped',
+                        note: `Stop took longer than ${timeout}ms — forced.`
+                    } );
+                }
+                settle();
+            }, timeout );
+            forceTimer.unref();
+            finished.then( settle, settle );
+        } );
+    };
+};

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

@@ -0,0 +1,213 @@
+// core/source-manager/test-harness/validate.js
+
+/**
+ * @fileoverview Startup validation for testHarness.
+ *
+ * Two things to check before the harness starts running:
+ *
+ * 1. The `messageTemplate` config — it must declare a seed, at least
+ *    one field, valid types, and (when fuzz is on) a target column.
+ * 2. The asset class — it must declare `_harnessId` as an int64
+ *    column. The cross-sink check tool uses this number to find the
+ *    same message in every sink, so every sink must be able to
+ *    store and report it.
+ *
+ * Validation runs through the shared `validateWithSchema` helper
+ * (see `core/utils/validate`). On any failure we re-throw as a single
+ * Error with `code = 'INVALID_CONFIG'` — the classified shape
+ * ADR-018 mandates for setup failures. The message lists every
+ * problem found so
+ * the test author can fix them in one pass.
+ */
+
+import { validateWithSchema, validators } from '../../utils/validate/index.js';
+
+const FIELD_TYPES = [ 'float64', 'int64', 'bool', 'string', 'timestamp' ];
+
+/**
+ * Schema for one entry in messageTemplate.fields.
+ */
+const FIELD_SPEC_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            required: true,
+            validator: validators.oneOf( FIELD_TYPES ),
+            error: `must be one of ${FIELD_TYPES.join( ', ' )}`
+        },
+        range: {
+            type: 'array',
+            minItems: 2,
+            maxItems: 2,
+            itemSchema: { type: 'number' },
+            validator: function ( arr ) {
+                return arr[ 0 ] < arr[ 1 ];
+            },
+            error: 'must be [ min, max ] with min < max'
+        },
+        resolution: {
+            type: 'number',
+            validator: validators.positive,
+            error: 'must be a positive number'
+        },
+        values: {
+            type: 'array',
+            minItems: 1
+        },
+        mode: {
+            type: 'string',
+            validator: validators.oneOf( [ 'monotonic-ms', 'static' ] ),
+            error: 'must be "monotonic-ms" or "static"'
+        }
+        // `seedValue` accepts any type, so we omit it from the schema.
+    }
+};
+
+/**
+ * Schema for the messageTemplate config.
+ *
+ * Cross-field rules (handled by `_crossFieldValidators`):
+ *   - fuzzTarget is required when fuzzInterval > 0
+ *   - fuzzTarget must name a declared field
+ *   - fields must not declare `_harnessId` (the harness adds it)
+ */
+export const MESSAGE_TEMPLATE_SCHEMA = {
+    seed: {
+        type: 'number',
+        required: true,
+        validator: validators.isFinite,
+        error: 'seed must be a finite number'
+    },
+    messageCount: {
+        type: 'number',
+        validator: validators.positiveInteger,
+        error: 'messageCount must be a positive integer'
+    },
+    intervalMs: {
+        type: 'number',
+        validator: validators.nonNegativeFinite,
+        error: 'intervalMs must be a non-negative finite number'
+    },
+    fuzzInterval: {
+        type: 'number',
+        validator: function ( v ) {
+            return Number.isInteger( v ) && v >= 0;
+        },
+        error: 'fuzzInterval must be a non-negative integer'
+    },
+    fuzzTarget: {
+        type: 'string'
+    },
+    fields: {
+        type: 'object',
+        required: true,
+        minProperties: 1,
+        propertySchema: FIELD_SPEC_SCHEMA
+    },
+    _crossFieldValidators: [
+        {
+            fields: [ 'fuzzInterval', 'fuzzTarget' ],
+            validator: function ( obj ) {
+                if ( !( obj.fuzzInterval > 0 ) ) return true;
+                return typeof obj.fuzzTarget === 'string' && obj.fuzzTarget.length > 0;
+            },
+            error: 'fuzzTarget is required when fuzzInterval > 0'
+        },
+        {
+            fields: [ 'fuzzTarget', 'fields' ],
+            validator: function ( obj ) {
+                if ( !obj.fuzzTarget ) return true;
+                return obj.fuzzTarget in obj.fields;
+            },
+            error: 'fuzzTarget must name a declared field'
+        },
+        {
+            fields: [ 'fields' ],
+            validator: function ( obj ) {
+                return !( '_harnessId' in obj.fields );
+            },
+            error: 'fields must not declare "_harnessId" — the harness adds it automatically'
+        },
+        {
+            fields: [ 'fields' ],
+            validator: function ( obj ) {
+                for ( const spec of Object.values( obj.fields ) ) {
+                    if ( spec.type === 'string' ) {
+                        if ( !Array.isArray( spec.values ) || spec.values.length === 0 ) {
+                            return false;
+                        }
+                    }
+                }
+                return true;
+            },
+            error: 'fields with type "string" must declare a non-empty values: [ ... ] list'
+        }
+    ]
+};
+
+/**
+ * Schema for the asset class. Only checks the parts the harness
+ * cares about — `_harnessId` declared as an int64 column. Other
+ * columns may exist; we do not look at them here.
+ */
+export const ASSET_CLASS_SCHEMA = {
+    columns: {
+        type: 'object',
+        required: true,
+        properties: {
+            _harnessId: {
+                type: 'object',
+                required: true,
+                properties: {
+                    type: {
+                        type: 'string',
+                        required: true,
+                        value: 'int64',
+                        error: 'must be int64'
+                    }
+                }
+            }
+        }
+    }
+};
+
+const throwInvalidConfig = function ( errors ) {
+    const err = new Error( `testHarness: ${errors.join( '; ' )}` );
+    err.code = 'INVALID_CONFIG';
+    throw err;
+};
+
+/**
+ * Validates the messageTemplate. Throws Error with
+ * `code = 'INVALID_CONFIG'` if anything fails.
+ *
+ * @param {Object} template - messageTemplate from config
+ */
+export const validateMessageTemplate = function ( template ) {
+    if ( !template || typeof template !== 'object' ) {
+        throwInvalidConfig( [ 'messageTemplate is required (object)' ] );
+    }
+    const result = validateWithSchema( MESSAGE_TEMPLATE_SCHEMA, template, 'messageTemplate' );
+    if ( !result.valid ) {
+        throwInvalidConfig( result.errors );
+    }
+};
+
+/**
+ * Validates the asset class. The harness needs `_harnessId` as an
+ * int64 column — the check tool uses this number to find the same
+ * message across sinks. Throws Error with
+ * `code = 'INVALID_CONFIG'` if anything fails.
+ *
+ * @param {Object} assetClass - The asset class declared by the test
+ */
+export const validateAssetClass = function ( assetClass ) {
+    if ( !assetClass || typeof assetClass !== 'object' ) {
+        throwInvalidConfig( [ 'assetClass is required in config' ] );
+    }
+    const result = validateWithSchema( ASSET_CLASS_SCHEMA, assetClass, 'assetClass' );
+    if ( !result.valid ) {
+        throwInvalidConfig( result.errors );
+    }
+};

package/src/core/storage-manager/questdb/assert-columns.js

@@ -0,0 +1,120 @@
+// core/storage-manager/questdb/assert-columns.js
+
+/**
+ * @fileoverview Walks every column in an asset class and checks that the
+ * column-internal facts QuestDB actually reads are well-formed. Throws
+ * with `err.code = 'INVALID_CONFIG'` on the first problem found, naming
+ * the offending column and field in the message.
+ *
+ * Why this file exists separately from the universal semantics schema:
+ *
+ * The semantics schema (in `core/semantics/schemas/`) validates what a
+ * well-formed asset class looks like in the abstract. It says "every
+ * column needs a `type`" because that is true for any consumer; it does
+ * NOT say "if `type === 'float64'` then `resolution` must be positive"
+ * because that is QuestDB-specific knowledge — other adapters may not
+ * care about resolution at all. Adapter-specific contracts belong in
+ * the adapter, not in the universal schema.
+ *
+ * Per ADR-018's column-internal facts pattern: each adapter that
+ * consumes column-internal facts MUST validate them defensively at
+ * startup AND document those assertions in its `@fileoverview`. This
+ * file is QuestDB's enforcement point; the documentation lives in the
+ * `Column-internal facts consumed` section of `index.js`'s top-of-file
+ * comment block.
+ *
+ * What this layer catches that the universal semantics schema does not:
+ *
+ * - **Type drift.** The universal schema accepts any type the semantics
+ *   layer knows about. QuestDB knows how to write a fixed set (the keys
+ *   of `DDL_TYPES` — float64, int64, bool, string, timestamp). If a new
+ *   type joins semantics tomorrow but QuestDB's writers haven't caught
+ *   up, the silent fallback (in `ensure-tables.js` and `persist-plan.js`)
+ *   would coerce values to VARCHAR. This check makes the gap loud.
+ * - **Bypassed schema validation.** Any path that builds an asset class
+ *   without going through `loadSemantics()` AND without going through
+ *   `flow.assetClass()` (e.g., a test calling `createStorage` directly)
+ *   skips the schema. This file is the last line of defense.
+ * - **Resolution sanity for float64.** Resolution is optional in the
+ *   schema (defaults to 1, treated as passthrough by `writers.js:54`).
+ *   But if the caller declares `resolution: 0` or `resolution: -0.1`,
+ *   the writer would compute `invResolution = 1 / resolution` as
+ *   Infinity / negative — silently corrupting every persisted value.
+ *   The schema does not enforce positivity (since absent resolution is
+ *   valid); this layer does, when present.
+ *
+ * Family: same shape as `core/wiring/assert-handle.js`. Both are pure
+ * functions that throw diagnostically at startup when an adapter
+ * contract is violated.
+ *
+ * `err.code` thrown:
+ * - `INVALID_CONFIG` — column-internal fact missing or malformed.
+ *   Per ADR-018, setup-time throws carry a classified `err.code`.
+ *
+ * @see ADR-018 (capability declaration)
+ * @see ./writers.js (resolution handling at write time)
+ */
+
+import { DDL_TYPES } from './ensure-tables.js';
+
+/**
+ * Walk every column in `assetClass.columns` and assert the facts QuestDB
+ * reads are well-formed. Throws on the first violation.
+ *
+ * Behaviour:
+ * - Each column's `type` must be set and writable by QuestDB
+ *   (i.e., a key in `DDL_TYPES`).
+ * - For columns where `type === 'float64'` and `resolution` is defined,
+ *   `resolution` must be a positive finite number. (Absent resolution
+ *   is fine — the writer treats undefined as passthrough.)
+ *
+ * @param {Object} assetClass - asset class with `columns` map
+ * @throws {Error} `err.code === 'INVALID_CONFIG'` on any column-internal
+ *   fact violation; message names the column and the offending field
+ */
+const assertColumnFacts = function ( assetClass ) {
+    const columns = assetClass.columns || Object.create( null );
+    const colNames = Object.keys( columns );
+
+    for ( let i = 0; i < colNames.length; i += 1 ) {
+        const colName = colNames[ i ];
+        const colSpec = columns[ colName ];
+
+        // Column type must be set and writable by QuestDB. Closes the
+        // silent fallback to VARCHAR / writeAsString for any missing or
+        // unsupported type. The `colSpec` truthy check also catches a
+        // null / undefined column entry — caller bug, but we surface it
+        // clearly rather than crashing on `.type` access.
+        if ( !colSpec || !( colSpec.type in DDL_TYPES ) ) {
+            const supportedTypes = Object.keys( DDL_TYPES ).join( ', ' );
+            const actualType = colSpec ? String( colSpec.type ) : 'undefined';
+            const err = new Error(
+                `WinkComposer/questdb: column '${colName}' has invalid or missing type '${actualType}'; ` +
+                `expected one of: ${supportedTypes}`
+            );
+            err.code = 'INVALID_CONFIG';
+            throw err;
+        }
+
+        // Float64 columns may declare a resolution for quantization. When
+        // present, must be a positive finite number — invResolution at
+        // 0 / negative / non-finite would silently corrupt every value.
+        // Absent resolution is fine: writers.js:54 treats undefined and
+        // 1 as passthrough (no quantization).
+        if ( colSpec.type === 'float64' && colSpec.resolution !== undefined ) {
+            if ( typeof colSpec.resolution !== 'number' ||
+                !Number.isFinite( colSpec.resolution ) ||
+                colSpec.resolution <= 0 ) {
+                const err = new Error(
+                    `WinkComposer/questdb: column '${colName}' has type 'float64' ` +
+                    `but resolution is '${colSpec.resolution}'; ` +
+                    'expected positive finite number (or omit for passthrough)'
+                );
+                err.code = 'INVALID_CONFIG';
+                throw err;
+            }
+        }
+    }
+};
+
+export { assertColumnFacts };