@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/archive/csv/update.js

@@ -0,0 +1,63 @@
+// nodes/csv-source/update.js
+const update = function ( state, msg ) {
+    // Source nodes are special - they generate messages
+    // The msg parameter here is typically a trigger/timer signal
+
+    if ( !state.isLoaded || state.isPaused ) {
+        return null;  // Nothing to emit
+    }
+
+    if ( state.currentIndex >= state.data.length ) {
+        if ( state.loop ) {
+            state.currentIndex = 0;  // Reset to beginning
+        } else {
+            state.isPaused = true;  // Stop emitting
+            return null;
+        }
+    }
+
+    // Rate limiting for stream mode
+    if ( state.mode === 'stream' ) {
+        const now = Date.now();
+        const timeSinceLastEmit = now - state.lastEmitTime;
+        const minInterval = 1000 / state.rate;
+
+        if ( timeSinceLastEmit < minInterval ) {
+            return null;  // Too soon, skip this update
+        }
+
+        state.lastEmitTime = now;
+    }
+
+    // Get next row
+    const row = state.data[ state.currentIndex ];
+    state.currentIndex += 1;
+
+    // Create output message
+    const output = Object.create( null );
+
+    // Add metadata
+    output._source = {
+        type: 'csv',
+        index: state.currentIndex - 1,
+        total: state.data.length,
+        timestamp: Date.now()
+    };
+
+    // Map columns
+    if ( state.columns === 'auto' ) {
+        // Use all columns as-is
+        Object.assign( output, row );
+    } else {
+        // Custom column mapping
+        for ( const [ csvCol, msgField ] of Object.entries( state.columns ) ) {
+            if ( row.hasOwnProperty( csvCol ) ) {
+                output[ msgField ] = row[ csvCol ];
+            }
+        }
+    }
+
+    return output;  // This will be the new message
+}; // update()
+
+export default update;

package/src/nodes/butterworth-filter/index.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Public API barrel for butterworth-filter node.
+ *
+ * Re-exports all standard node interface functions and introspection metadata.
+ */
+
+export { default as init } from './init.js';
+export { default as update } from './update.js';
+export { default as reset } from './reset.js';
+export { default as recompute } from './recompute.js';
+export { default as publishTo } from './publish-to.js';
+// Direct imports for common control functions
+export { default as disable } from '../../core/utils/node/disable.js';
+export { default as enable } from '../../core/utils/node/enable.js';
+export { default as pause } from '../../core/utils/node/pause.js';
+export { default as unpause } from '../../core/utils/node/unpause.js';
+// Re-export everything from introspection.js
+export * from './introspect.js';

package/src/nodes/butterworth-filter/init.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Initialization for butterworth-filter node.
+ *
+ * Validates the spec, computes 2nd-order Butterworth coefficients via the
+ * bilinear transform with frequency pre-warping, and returns fully
+ * initialized state. Supports lowpass/highpass, three cutoff specification
+ * methods, cascade adjustment, and DC initialization for transient reduction.
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+    // Standard input parameter health flag during update: false means healthy
+    state.inputValidationFailed = false;
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Extract field name
+    state.x = spec.from.x;
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    // Supports both direct and field-keyed specification for tunable params
+    const filterTypeSpec = resolveScalar( spec.filterType, state.x );
+    state.filterType = filterTypeSpec ?? introspect.DEFAULT_OPTIONS.filterType;
+    state.acceptNumericalRisk = spec.acceptNumericalRisk ?? introspect.DEFAULT_OPTIONS.acceptNumericalRisk;
+
+    // Extract sample rate (required field, validated by schema)
+    const sampleRateHz = spec.sampleRateHz;
+    const nyquistHz = sampleRateHz / 2;
+
+    // Resolve tunable params (supports field-keying)
+    const cutoffHzSpec = resolveScalar( spec.cutoffHz, state.x );
+    const settlingTimeMsSpec = resolveScalar( spec.settlingTimeMs, state.x );
+    const cutoffRatioSpec = resolveScalar( spec.cutoffRatio, state.x );
+
+    // Determine cutoff frequency from various possible inputs
+    let cutoffHz;
+    let configIntent = 'direct';
+
+    if ( cutoffHzSpec ) {
+        // Direct specification
+        cutoffHz = cutoffHzSpec;
+
+    } else if ( settlingTimeMsSpec && spec.sampleRateHz ) {
+        // Calculate from settling time requirement
+        // For 2nd order Butterworth: settling time ≈ 4 / (2π * fc) for 98% settling
+        const settlingTimeSec = settlingTimeMsSpec / 1000;
+        cutoffHz = 4 / ( 2 * Math.PI * settlingTimeSec );
+        configIntent = 'settling-time';
+
+    } else if ( cutoffRatioSpec ) {
+        // Relative to Nyquist
+        cutoffHz = cutoffRatioSpec * nyquistHz;
+        configIntent = 'ratio';
+    }
+
+    // Adjust for cascading if specified
+    let cascadeAdjustment = 1;
+    if ( spec.adjustForCascade && spec.adjustForCascade > 1 ) {
+        // For N cascaded stages to have -3dB at fc:
+        // Each stage needs fc * 2^(1/N - 1)
+        cascadeAdjustment = Math.pow( 2, ( 1 / spec.adjustForCascade ) - 1 );
+        cutoffHz /= cascadeAdjustment;
+        configIntent += '-cascade-adjusted';
+    }
+
+    // Validate the computed cutoff
+    if ( cutoffHz <= 0 || cutoffHz >= nyquistHz ) {
+        throw new RangeError(
+            `Computed cutoff ${cutoffHz.toFixed(1)}Hz is outside valid range (0, ${nyquistHz}Hz)`
+        );
+    }
+
+    // Warn about potential numerical issues
+    const normalizedCutoff = cutoffHz / nyquistHz;
+    if ( normalizedCutoff < 0.001 && !state.acceptNumericalRisk ) {
+        console.warn( `Very low cutoff (${cutoffHz.toFixed(3)}Hz) may cause numerical instability` );
+    }
+
+    // Store configuration for reference
+    state.config = {
+        cutoffHz,
+        sampleRateHz,
+        normalizedCutoff,
+        intent: configIntent,
+        cascadeAdjustment,
+        dcEstimate: spec.dcEstimate  // Store for reset functionality
+    };
+
+    // Calculate filter coefficients using bilinear transform
+    // Pre-warp the frequency to compensate for bilinear transform warping
+    const wc = ( Math.PI * normalizedCutoff ) / 2;  // Bilinear pre-warp: tan(π·fc/fs)
+    const warpedWc = Math.tan( wc );                // Pre-warped cutoff frequency
+
+    // Butterworth prototype has Q = 1/√2 for maximally flat response
+    const Q = 1 / Math.sqrt( 2 );
+
+    // Bilinear transform coefficients
+    const K = warpedWc;
+    const K2 = K * K;
+    const norm = 1 / ( K2 + ( K / Q ) + 1 );
+
+    if ( state.filterType === 'lowpass' ) {
+        // H(s) = 1 / (s² + s/Q + 1) -> H(z) via bilinear transform
+        state.b0 = K2 * norm;
+        state.b1 = 2 * K2 * norm;
+        state.b2 = K2 * norm;
+        state.a1 = 2 * ( K2 - 1 ) * norm;
+        state.a2 = ( K2 - ( K / Q ) + 1 ) * norm;
+    } else { // highpass
+        // H(s) = s² / (s² + s/Q + 1) -> H(z) via bilinear transform
+        state.b0 = norm;
+        state.b1 = -2 * norm;
+        state.b2 = norm;
+        state.a1 = 2 * ( K2 - 1 ) * norm;
+        state.a2 = ( K2 - ( K / Q ) + 1 ) * norm;
+    }
+
+    // Validate filter stability (poles inside unit circle)
+    /* c8 ignore next 5 -- defensive: bilinear transform produces stable coefficients for valid Nyquist-bounded cutoff */
+    if ( Math.abs( state.a2 ) >= 1 ) {
+        throw new Error(
+            `Filter unstable: coefficient a2 (${state.a2.toFixed(4)}) is outside stability bounds`
+        );
+    }
+
+    /* c8 ignore next 5 -- defensive: same Nyquist guard prevents a1 stability violation */
+    if ( Math.abs( state.a1 ) >= 1 + state.a2 ) {
+        throw new Error(
+            `Filter unstable: coefficient a1 (${state.a1.toFixed(4)}) violates stability condition |a1| < 1 + a2`
+        );
+    }
+
+    // State variables for Direct Form II
+    state.z1 = 0;
+    state.z2 = 0;
+
+    // CRITICAL: Initialize output storage for publishTo()
+    // This ensures edge cases (NaN/Inf) work correctly on first call
+    state.output = 0;
+
+    // Initialization strategy
+    if ( spec.initStrategy === 'dc' && spec.dcEstimate !== undefined ) {
+        // Initialize DF2T state to steady-state for known DC level.
+        // At steady state with constant input D: output = D·G, z1 = G·D - b0·D,
+        // z2 = b2·D - a2·G·D, where G = H(1) = Σb / (1 + a1 + a2).
+        const dcGain = ( state.b0 + state.b1 + state.b2 ) / ( 1 + state.a1 + state.a2 );
+        if ( Math.abs( dcGain ) > 1e-10 ) {
+            const steadyOutput = spec.dcEstimate * dcGain;
+            state.z1 = steadyOutput - ( state.b0 * spec.dcEstimate );
+            state.z2 = ( state.b2 * spec.dcEstimate ) - ( state.a2 * steadyOutput );
+            state.output = steadyOutput;
+        }
+    }
+
+    // Auto-compute performance characteristics
+    state.performance = {
+        multipliesPerSample: 5,
+        addsPerSample: 4,
+        memoryBytes: 56, // 7 Float64s (6 coeffs + 2 state + 1 output)
+        // Group delay approximation at cutoff (in samples)
+        groupDelaySamples: Math.round( 0.5 / ( Math.PI * normalizedCutoff ) ),
+        // Settling time to 98% (in samples)
+        settlingTimeSamples: Math.round( 4 / ( 2 * Math.PI * normalizedCutoff ) ),
+        // Useful for debugging
+        actualCutoffHz: cutoffHz,
+        normalizedCutoff: normalizedCutoff
+    };
+
+    // Output configuration
+    state.stats = spec.stats;
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/butterworth-filter/introspect.js

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview Introspection metadata for butterworth-filter node.
+ *
+ * Defines supported stats, control methods, capabilities, DSL schema,
+ * and default options. All getters return defensive copies.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for capabilities */
+const SUPPORTED_STATS = [ 'filtered' ];
+
+const STAT_DESCRIPTIONS = {
+    filtered: 'Butterworth filtered signal'
+};
+
+/** Control methods available for triggers */
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears accumulated state and restarts computation',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+const NODE_TYPE = 'Butterworth Filter';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'High-performance 2nd-order Butterworth filter for real-time streaming',
+    features: [
+        'Lowpass and highpass filtering',
+        'Multiple cutoff specification methods',
+        'DC initialization for transient reduction',
+        'Cascade adjustment for multi-stage filtering'
+    ]
+};
+
+// Static metadata exports
+export const getSupportedStats = () => SUPPORTED_STATS.slice();
+export const getStatDescriptions = () => ( { ...STAT_DESCRIPTIONS } );
+export const getSupportedControlMethods = () => ( { ...SUPPORTED_CONTROL_METHODS } );
+export const getNodeType = () => NODE_TYPE;
+export const getCapabilities = () => ( { ...CAPABILITIES, features: CAPABILITIES.features.slice() } );
+
+export const DEFAULT_OPTIONS = {
+    filterType: 'lowpass',
+    acceptNumericalRisk: false
+};
+
+// DSL Metadata for transpilation
+const DSL_METADATA = {
+    // Spec schema for validation
+    specSchema: {
+        nodeType: {
+            type: 'string',
+            required: true,
+            value: NODE_TYPE
+        },
+        name: {
+            type: 'string',
+            required: true,
+            validator: validators.identifier,
+            error: 'Name must be a valid identifier'
+        },
+        from: {
+            type: 'object',
+            required: true,
+            properties: {
+                x: {
+                    type: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        filterType: {
+            type: 'stringOrFieldKeyed',
+            required: false,
+            default: 'lowpass',
+            validator: validators.oneOf([ 'lowpass', 'highpass' ]),
+            error: 'filterType must be "lowpass" or "highpass"'
+        },
+        sampleRateHz: {
+            type: 'number',
+            required: true,
+            validator: validators.positive,
+            error: 'sampleRateHz must be positive'
+        },
+        // One of these cutoff specifications is required
+        cutoffHz: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            validator: validators.positive,
+            error: 'cutoffHz must be positive'
+        },
+        settlingTimeMs: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            validator: validators.positive,
+            error: 'settlingTimeMs must be positive'
+        },
+        cutoffRatio: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            validator: validators.inRange(0, 1),
+            error: 'cutoffRatio must be between 0 and 1'
+        },
+        adjustForCascade: {
+            type: 'number',
+            required: false,
+            integer: true,
+            min: 2,
+            validator: validators.positiveInteger,
+            error: 'adjustForCascade must be an integer >= 2'
+        },
+        initStrategy: {
+            type: 'string',
+            required: false,
+            validator: validators.oneOf([ 'dc' ]),
+            error: 'initStrategy must be "dc" if specified'
+        },
+        dcEstimate: {
+            type: 'number',
+            required: false
+        },
+        acceptNumericalRisk: {
+            type: 'boolean',
+            required: false,
+            default: false
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'cutoffHz', 'settlingTimeMs', 'cutoffRatio' ],
+            // At least one cutoff specification method must be provided
+            validator: ( spec ) => ( spec.cutoffHz || spec.settlingTimeMs || spec.cutoffRatio ),
+            error: 'Must specify cutoffHz, settlingTimeMs, or cutoffRatio'
+        },
+        {
+            fields: [ 'cutoffHz', 'settlingTimeMs', 'cutoffRatio' ],
+            validator: ( spec ) => {
+                // Only one cutoff specification method should be provided
+                const methods = [ spec.cutoffHz, spec.settlingTimeMs, spec.cutoffRatio ].filter( Boolean );
+                return methods.length === 1;
+            },
+            error: 'Specify only one of: cutoffHz, settlingTimeMs, or cutoffRatio'
+        },
+        {
+            fields: [ 'initStrategy', 'dcEstimate' ],
+            validator: ( spec ) => {
+                // If initStrategy is 'dc', dcEstimate must be provided
+                if ( spec.initStrategy === 'dc' ) {
+                    return spec.dcEstimate !== undefined;
+                }
+                return true;
+            },
+            error: 'dcEstimate is required when initStrategy is "dc"'
+        },
+        {
+            fields: [ 'initStrategy', 'dcEstimate' ],
+            validator: ( spec ) => {
+                // If dcEstimate is provided, initStrategy must be 'dc'
+                if ( spec.dcEstimate !== undefined ) {
+                    return spec.initStrategy === 'dc';
+                }
+                return true;
+            },
+            error: 'initStrategy must be "dc" when dcEstimate is provided'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    // Pattern: NAME_X_OUTPUTS_OPTIONS -> (name, x, stats, options)
+    buildSpec: ( name, x, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );
+
+// Performance and design info exports
+export const getPerformance = ( state ) => ( { ...state.performance } );
+
+export const getDesignInfo = ( state ) => ( {
+    filterType: state.filterType,
+    actualCutoffHz: state.config.cutoffHz,
+    sampleRateHz: state.config.sampleRateHz,
+    configMethod: state.config.intent,
+    normalized3dBFreq: state.config.normalizedCutoff,
+    cascadeAdjustment: state.config.cascadeAdjustment,
+    // Phase delay at cutoff in ms
+    phaseDelayMs: ( state.performance.groupDelaySamples / state.config.sampleRateHz ) * 1000,
+    // Settling time in ms
+    settlingTimeMs: ( state.performance.settlingTimeSamples / state.config.sampleRateHz ) * 1000
+} );
+
+// Human-readable description
+export const describe = ( state ) => {
+    const info = getDesignInfo( state );
+    return `${state.filterType} filter: ${info.actualCutoffHz.toFixed(1)}Hz @ ${info.sampleRateHz}Hz ` +
+           `(settles in ~${info.settlingTimeMs.toFixed(0)}ms, delay ~${info.phaseDelayMs.toFixed(1)}ms)`;
+};

package/src/nodes/butterworth-filter/publish-to.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Publish function for butterworth-filter node.
+ *
+ * Copies the filtered output to the message, or propagates NaN if the last
+ * input was invalid. Skipped entirely when disabled.
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    msg[ state.stats.filtered.storeAs ] = state.output;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/butterworth-filter/recompute.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Recompute for butterworth-filter node.
+ *
+ * No-op: stable 2nd-order IIR — state variables z1/z2 are bounded by
+ * exponential decay. No accumulated statistics susceptible to drift.
+ */
+
+const recompute = function ( _state ) {
+    // Stable 2nd-order IIR: z1/z2 bounded by exponential decay; no drift.
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/butterworth-filter/reset.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Reset for butterworth-filter node.
+ *
+ * Clears delay elements and output. When a DC estimate is configured,
+ * restores steady-state z1/z2 and output to minimize transient on restart.
+ */
+
+const reset = function ( state ) {
+    // Clear delay elements
+    state.z1 = 0;
+    state.z2 = 0;
+
+    // Clear output
+    state.output = 0;
+
+    // Re-initialize to steady-state if DC estimate is known
+    if ( state.config.dcEstimate !== undefined ) {
+        const dcGain = ( state.b0 + state.b1 + state.b2 ) / ( 1 + state.a1 + state.a2 );
+        if ( Math.abs( dcGain ) > 1e-10 ) {
+            const steadyOutput = state.config.dcEstimate * dcGain;
+            state.z1 = steadyOutput - ( state.b0 * state.config.dcEstimate );
+            state.z2 = ( state.b2 * state.config.dcEstimate ) - ( state.a2 * steadyOutput );
+            state.output = steadyOutput;
+        }
+    }
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/butterworth-filter/update.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Update function for butterworth-filter node.
+ *
+ * Implements Direct Form II Transposed structure for a 2nd-order Butterworth
+ * filter. Denormals are flushed to zero to avoid performance degradation on
+ * x86 hardware.
+ */
+
+const DENORMAL_THRESHOLD = 1e-30;
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+    const xVal = msg[ state.x ];
+    // Reset on each update
+    state.inputValidationFailed = false;
+    // Handle faults gracefully: ensure their isolation
+    if ( !Number.isFinite( xVal ) ) {
+        // Signals publishing NaN for all demanded `stats` in publishTo.
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Direct Form II implementation
+    const output = ( state.b0 * xVal ) + state.z1;
+    state.z1 = ( state.b1 * xVal ) - ( state.a1 * output ) + state.z2;
+    state.z2 = ( state.b2 * xVal ) - ( state.a2 * output );
+
+    // Flush denormals to zero (performance optimization)
+    if ( Math.abs( state.z1 ) < DENORMAL_THRESHOLD ) state.z1 = 0;
+    if ( Math.abs( state.z2 ) < DENORMAL_THRESHOLD ) state.z2 = 0;
+
+    // Store output in state for publishTo() to access
+    state.output = output;
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/categorize/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Entry point for categorize node.
+ *
+ * Re-exports all lifecycle functions (init, update, publishTo, reset, recompute),
+ * shared control signals (disable, enable, pause, unpause), and introspection metadata.
+ */
+
+export { default as init } from './init.js';
+export { default as update } from './update.js';
+export { default as reset } from './reset.js';
+export { default as recompute } from './recompute.js';
+export { default as publishTo } from './publish-to.js';
+// Direct imports for common control functions
+export { default as disable } from '../../core/utils/node/disable.js';
+export { default as enable } from '../../core/utils/node/enable.js';
+export { default as pause } from '../../core/utils/node/pause.js';
+export { default as unpause } from '../../core/utils/node/unpause.js';
+// Re-export everything from introspection.js
+export * from './introspect.js';

package/src/nodes/categorize/init.js

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Initialization for categorize node.
+ *
+ * Validates the spec, resolves thresholds (static or tunable via asTunable),
+ * resolves field-keyed categories, and builds the initial state with the
+ * default category (first element).
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { resolveArray } from '../../core/utils/options/resolve-field-keyed.js';
+import { asTunable } from '../../core/tunable/index.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+    // Standard input parameter health flag during update: false means healthy
+    state.inputValidationFailed = false;
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Extract configuration
+    state.x = spec.from.x;
+    state.stats = spec.stats;
+
+    // Supports direct: { thresholds: [15, 25] }
+    // field-keyed: { thresholds: { temp: [15, 25], pressure: [30, 60] } }
+    // and tunable: { thresholds: lookupByField('shift', { day: [...], night: [...] }, [...]) }
+    if ( typeof spec.thresholds === 'function' ) {
+        // Dynamic thresholds (tunable) - resolve at runtime
+        state.thresholdsFn = spec.thresholds;
+        state.resolvedThresholds = null;  // Not yet resolved — first message must succeed
+    } else {
+        // Static thresholds - resolve field-keying at init time
+        const thresholdsResolved = resolveArray( spec.thresholds, state.x );
+        state.thresholdsFn = asTunable( thresholdsResolved );
+        state.resolvedThresholds = thresholdsResolved;  // Known at init
+    }
+    state.tunableErrorLogged = false;
+
+    // Categories remain static (structural)
+    state.categories = resolveArray( spec.categories, state.x );
+
+    // Current categorization state
+    state.categoryIndex = 0;
+    state.category = state.categories[ 0 ];  // Default to first category
+
+    // Node metadata
+    state.nodeType = introspect.getNodeType();
+    state.inControlPhase = false;
+
+    return state;
+}; // init()
+
+export default init;