@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/moments-digest/index.js

@@ -0,0 +1,132 @@
+// nodes/moments-digest/index.js
+
+/**
+ * @fileoverview
+ * Moments Digest — numerically stable, windowed M1..M4 with min/max, designed for
+ * arbitrary-depth cascades (fan-in = 1 per chain) using a single shared field space.
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * TL;DR
+ * • Consumes raw samples `msg[ x ]` and produces per-window statistics:
+ *   `x_n, x_M1, x_M2, x_M3, x_M4, x_min, x_max` plus a boolean `msg[ name ] = true`.
+ * • Central moments are carried as unnormalized sums (Pébay 2008):
+ *   M2 = Σ (x−μ)², M3 = Σ (x−μ)³, M4 = Σ (x−μ)⁴. Compute variance/kurtosis downstream.
+ * • Supports arbitrary cascade depth: root and all downstream levels read/write the SAME `x_*` keys.
+ * • Publishes only on **window completion** or **flush**; on all other ticks it **scrubs** `x_*`
+ *   to `undefined` so downstream nodes cannot accidentally ingest partials.
+ * • Uniform flush key: `x_flush`. **Only the root sets it;** cascades react to it.
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Execution model (per message)
+ * The node is split into three conceptual phases. All state mutation happens in
+ * `update()`; `publishTo()` is a pure renderer of what `update()` planned.
+ *
+ * 1) Prelude (top of update)
+ *    • Clear last tick's publish plan: `planPublish = false`, `propagateFlush = false`.
+ *    • ROOT ONLY: If flush is latched:
+ *        – If `n > 0`: **copy → reset → planPublish** (publish the snapshot this tick).
+ *          Root sets `propagateFlush = true` so `publishTo()` will emit `x_flush`.
+ *        – If `n === 0`: **signal-only flush**. Root sets `propagateFlush = true`,
+ *          but does not plan a stats publish (no data to emit).
+ *    • CASCADE: Does NOT handle flush in prelude (deferred to after ingestion).
+ *
+ * 2) Core update
+ *    • Raw level: read `msg[ x ]`; if non-finite → mark input invalid and return (no plan).
+ *      Otherwise, update moments and counters with the new sample.
+ *    • Cascade level:
+ *        – **Always merge when** `msg[ x_n ] !== undefined` (ingest parent's moments).
+ *        – **After ingestion**, if `msg[ x_flush ] === true` and `n > 0`:
+ *          **copy → reset → planPublish** (ensures cascade includes parent's flush data).
+ *
+ * 3) Epilogue (end of update)
+ *    • If the window just completed (and no flush snapshot was already planned, and input is valid):
+ *        – **copy → reset → planPublish** (publish the completed window this tick).
+ *
+ * 4) publishTo (pure render; no state mutation)
+ *    • If `propagateFlush === true` and this is the root: set `msg[ x_flush ] = true`.
+ *    • If `planPublish === true`: write all `x_*` fields **from the snapshot** and set `msg[ name ] = true`.
+ *    • Otherwise (non-publish tick): scrub `x_*` to `undefined`. Never touch `x_flush`.
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * "Before/After" semantics (UX via placement)
+ * • Controller **upstream of the root** ("BEFORE"):
+ *     – Flush latch is seen in Prelude on the **same** message → snapshot/reset now.
+ *       The current message becomes the **first sample of the next window**.
+ *       Root publishes the snapshot and emits `x_flush`; cascades see `x_flush`,
+ *       ingest parent's moments FIRST, then publish their accumulated state and reset.
+ * • Controller **downstream of the root** ("AFTER"):
+ *     – Flush latch is seen on the **next** message. The previous message is included
+ *       in the snapshot that publishes next tick. (If no next message arrives, nothing
+ *       triggers the deferred publish — controller may emit a final synthetic tick if needed.)
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Inputs
+ * • from.x        : string (required)  → base field name, e.g., 'temperature'.
+ * • windowSize    : number (required)  → samples per window at this level (≥ 4).
+ * • name          : string (optional)  → node identifier; sets `msg[ name ] = true` on publish.
+ * • cascade       : boolean (optional) → false for raw level, true for cascade level.
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Outputs (on publish)
+ * • msg[ x + '_n'   ] : number
+ * • msg[ x + '_M1'  ] : number (mean)
+ * • msg[ x + '_M2'  ] : number (Σ centered squares)
+ * • msg[ x + '_M3'  ] : number (Σ centered cubes)
+ * • msg[ x + '_M4'  ] : number (Σ centered fourth powers)
+ * • msg[ x + '_min' ] : number
+ * • msg[ x + '_max' ] : number
+ * • msg[ name ]       : true (flag marking "this node published now")
+ * • msg[ x + '_flush' ] : true (root only, on flush ticks)
+ *
+ * On non-publish cycles, **all** `x_*` fields are set to `undefined` (keys kept, never deleted).
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Flush semantics (action + state)
+ * • Root:
+ *     – A flush request latches a boundary. In Prelude the node **copies → resets → plans**
+ *       a publish from the snapshot (if `n > 0`) and will **emit `x_flush`** at publish time.
+ *     – If `n === 0`, it is a **signal-only** flush: emit `x_flush` without stats.
+ * • Cascades:
+ *     – Never set/clear `x_flush`. They **observe** `x_flush` and publish accumulated state.
+ *     – Critical: cascades ingest parent's moments BEFORE handling flush, ensuring
+ *       parent's flush data is included in cascade's flush output (no data loss).
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * NaN / invalid input handling
+ * • Raw level:
+ *     – A non-finite current input suppresses planning of a **window** publish.
+ *     – A **flush snapshot planned in Prelude** still publishes this tick; `publishTo()`
+ *       does not early-bail on invalid input. This preserves the boundary and keeps
+ *       cascades aligned (root still emits `x_flush`).
+ * • Cascade level:
+ *     – No raw input is read. The node merges only when `x_*` fields are present.
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Invariants
+ * • Uniform flush key across the chain: `x_flush` (root only writes).
+ * • No data loss: cascades always ingest before responding to flush.
+ * • Scrub on every non-publish tick: `x_*` → `undefined`.
+ * • Publish is **snapshot-only**; `publishTo()` never mutates node state.
+ * • O(1) time and O(1) memory per message; no hot-path allocations (snapshot object is reused).
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * References
+ * [1] Pébay, P. (2008). Formulas for robust, one-pass parallel computation of covariances
+ *     and arbitrary-order statistical moments. Sandia Report SAND2008-6212.
+ * [2] Chan, T. F., Golub, G. H., & LeVeque, R. J. (1983). Algorithms for computing the
+ *     sample variance: Analysis and recommendation. The American Statistician, 37(3), 242-247.
+ */
+
+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';
+export { default as flush } from './flush.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/moments-digest/init.js

@@ -0,0 +1,84 @@
+// nodes/moments-digest/init.js
+
+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;
+    // Preserve node's name
+    state.name = spec.name;
+
+    // Extract configuration
+    state.x = spec.from.x;
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    // Supports both direct and field-keyed specification
+    const windowSizeSpec = resolveScalar( spec.windowSize, state.x );
+    state.windowSize = windowSizeSpec ?? introspect.DEFAULT_OPTIONS.windowSize;
+
+    // Determine mode: raw or cascade
+    state.isCascading = spec.cascade || introspect.DEFAULT_OPTIONS.cascade;
+
+    // Extract base field name
+    state.baseField = state.x;
+
+    // Pre-compute ALL field names for hot path (no string concat in update!)
+    // Input names are same output names in the case of cascade
+    state.fieldMap = Object.create( null );
+    state.fieldMap.n   = state.baseField + '_n';
+    state.fieldMap.M1  = state.baseField + '_M1';
+    state.fieldMap.M2  = state.baseField + '_M2';
+    state.fieldMap.M3  = state.baseField + '_M3';
+    state.fieldMap.M4  = state.baseField + '_M4';
+    state.fieldMap.min = state.baseField + '_min';
+    state.fieldMap.max = state.baseField + '_max';
+
+
+    // Pébay algorithm state
+    state.n = 0;
+    state.M1 = 0;
+    state.M2 = 0;
+    state.M3 = 0;
+    state.M4 = 0;
+    state.min = Infinity;
+    state.max = -Infinity;
+    // Signal for digest completion.
+    state[ state.name ] = false;
+    // This is used to signal downstream nodes to flush as the primary control
+    // path works only for the root (i.e. the first or the non-cascade one) node
+    // in the chain. Control signalling for cascaded nodes is disabled as the
+    // chain sequence for flush operation needs to be respected by the downstream
+    // nodes. This flag is set to true by the root node on flush event and is used
+    // subsequently by the cascaded downstream nodes to flush accordingly. BUT
+    // we need to create the **key** irrespective of being root or cascade.
+    state.flushSignalKey = state.x + '_flush';  // e.g. 'temperature_flush'
+
+
+    // Window management
+    state.currentCount = 0;
+    state.windowComplete = false;
+
+    // Set by flush method
+    state.flushLatched = false;
+    // Publish stats (from snapshot) this tick
+    state.planPublish = false;
+    // Root should emit x_flush this tick
+    state.propagateFlush = false;
+    // Always copy moments here on window completion or flush event
+    state.snapshot = Object.create( null );
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/moments-digest/introspect.js

@@ -0,0 +1,122 @@
+// nodes/moments-digest/introspect.js
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'n',     // Sample count
+    'M1',    // Mean (first moment)
+    'M2',    // Second central moment
+    'M3',    // Third central moment
+    'M4',    // Fourth central moment
+    'min',   // Minimum value
+    'max'    // Maximum value
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    n: 'Number of samples in the aggregated window',
+    M1: 'Arithmetic mean of values in the window',
+    M2: 'Second central moment (sum of squared deviations from mean)',
+    M3: 'Third central moment (sum of cubed deviations from mean)',
+    M4: 'Fourth central moment (sum of quartic deviations from mean)',
+    min: 'Minimum value across all samples',
+    max: 'Maximum value across all samples'
+};
+
+/** 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',
+    flush: 'Forces immediate output of partial window'
+};
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'High-performance streaming aggregation using Pébay\'s numerically stable algorithm for statistical moments',
+    features: [
+        'Configurable window-based aggregation (4-1024 samples)',
+        'Numerically stable incremental mean and moment computation',
+        'Cascade mode for multi-level aggregation (seconds → minutes → hours)',
+        'Automatic mean and moment combining for cascaded windows',
+        'Window completion signaling via msg[nodeName] = true',
+        'Intelligent message filtering in cascade mode (processes only moment messages)',
+        'NaN resilience - skips invalid samples without corrupting statistics',
+        'Zero allocations in hot path for maximum throughput',
+        'Flush support for graceful shutdown with incomplete windows'
+    ]
+};
+
+/** The type of this node */
+const NODE_TYPE = 'Moments Digest';
+
+// Attach static metadata once, from our constants by making a shallow copy.
+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 = {
+    windowSize: 100,
+    cascade: 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'
+                }
+            }
+        },
+        windowSize: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.windowSize,
+            integer: true,
+            min: 4,
+            max: 1024,
+            validator: validators.positiveInteger,
+            error: 'Window size must be a positive integer'
+        },
+        cascade: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.cascade
+        }
+    },
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, x, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/moments-digest/prelude.js

@@ -0,0 +1,28 @@
+// nodes/moments-digest/prelude.js
+
+import { copyFrom } from './copy-from.js';
+import reset from './reset.js';
+
+export const prelude = function ( state, msg ) {
+    // Clear last tick’s plan
+    state.planPublish = false;
+    state.propagateFlush = false;
+
+    if ( !state.flushLatched && !msg[ state.flushSignalKey ] ) return;
+    // Either `state.flushLatched` or `msg[ state.flushSignalKey ]` is true
+    // implies that it is time to copy and plan a publish.
+
+    // Only ROOT nodes handle flush in prelude
+    if ( !state.isCascading ) {
+        state.propagateFlush = true;
+
+        if ( state.n > 0 ) {
+            copyFrom( state, state.snapshot );      // copy previous window
+            state.planPublish = true;               // we will publish stats this tick
+            reset( state );                         // exclude current message
+        }
+    }
+    // Otherwise: signal-only flush (no stats) via planPublish === false
+
+    state.flushLatched = false;                 // consume latch
+}; // prelude()

package/src/nodes/moments-digest/publish-to.js

@@ -0,0 +1,31 @@
+// nodes/moments-digest/publish-to.js
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Do not Skip publishing if we encountered NaN in this update cycle
+    // `update()` already suppresses planning on invalid samples;
+    // a flush snapshot planned in `prelude()` must still render.
+    const f = state.fieldMap;
+
+    if ( state.propagateFlush && ( !state.isCascading ) ) {
+        msg[ state.flushSignalKey ] = true;
+    }
+
+    if ( state.planPublish ) {
+        const s = state.snapshot;
+        msg[ f.n ]   = s.n;
+        msg[ f.M1 ]  = s.M1;
+        msg[ f.M2 ]  = s.M2;
+        msg[ f.M3 ]  = s.M3;
+        msg[ f.M4 ]  = s.M4;
+        msg[ f.min ] = s.min;
+        msg[ f.max ] = s.max;
+        msg[ state.name ] = true;
+        return;
+    }
+
+    // signal-only or no publish → scrub
+    msg[ f.n ] = msg[ f.M1 ] = msg[ f.M2 ] = msg[ f.M3 ] = msg[ f.M4 ] = msg[ f.min ] = msg[ f.max ] = undefined;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/moments-digest/recompute.js

@@ -0,0 +1,9 @@
+// nodes/moments-digest/recompute.js
+
+const recompute = function () {
+    // Stats digest doesn't need recomputation
+    // Moments are computed incrementally using numerically stable algorithm
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/moments-digest/reset.js

@@ -0,0 +1,20 @@
+// nodes/moments-digest/reset.js
+
+const reset = function ( state ) {
+    // Reset all statistical state
+    state.n = 0;
+    state.M1 = 0;
+    state.M2 = 0;
+    state.M3 = 0;
+    state.M4 = 0;
+    state.min = Infinity;
+    state.max = -Infinity;
+
+    // Reset window management
+    state.currentCount = 0;
+    state.windowComplete = false;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/moments-digest/update.js

@@ -0,0 +1,182 @@
+// nodes/moments-digest/update.js
+
+/**
+ * @fileoverview
+ * Moments Digest Update — Incremental moment accumulation with flush synchronization
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Core Processing Logic
+ * • Raw nodes: Process individual samples using Pébay's algorithm
+ * • Cascade nodes: Merge moment sets from parent digests
+ * • Window completion: Both node types publish on window completion
+ * • Flush override: Immediate publish of partial windows
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Flush Synchronization (Critical for Data Integrity)
+ *
+ * ROOT NODES:
+ * • Handle flush in prelude (snapshot → reset → plan)
+ * • Controller placement determines current message inclusion:
+ *   - BEFORE: Exclude current (it starts next window)
+ *   - AFTER: Include current (it's in the snapshot)
+ * • Propagate x_flush signal to downstream cascades
+ *
+ * CASCADE NODES:
+ * • Never snapshot/reset in prelude (only root does)
+ * • Process parent's moments FIRST (if present)
+ * • THEN check for flush signal to publish accumulated state
+ * • This sequence ensures cascade includes exactly what root decided
+ *
+ * Key invariant: Cascades ingest whatever root published before responding
+ * to flush. This prevents data loss regardless of controller placement.
+ *
+ * ────────────────────────────────────────────────────────────────────────────────
+ * Execution Flow (per message)
+ * 1. Process input (raw sample or parent moments)
+ * 2. For cascades with flush signal: snapshot → reset after ingestion
+ * 3. Check window completion (both node types)
+ * 4. Plan publish if window complete or flush triggered
+ */
+
+/* eslint-disable camelcase */
+import { copyFrom } from './copy-from.js';
+import { prelude } from './prelude.js';
+import reset from './reset.js';
+
+// Pébay's algorithm for single value update
+const updateFromRaw = function ( state, value ) {
+    const n1 = state.n;
+    state.n += 1;
+
+    const delta = value - state.M1;
+    const delta_n = delta / state.n;
+    const delta_n2 = delta_n * delta_n;
+    const term1 = delta * delta_n * n1;
+
+    // Update moments
+    state.M1 += delta_n;
+    state.M4 += ( term1 * delta_n2 * ( ( state.n * state.n ) - ( 3 * state.n ) + 3 ) ) +
+                ( 6 * delta_n2 * state.M2 ) - ( 4 * delta_n * state.M3 );
+    state.M3 += ( term1 * delta_n * ( state.n - 2 ) ) - ( 3 * delta_n * state.M2 );
+    state.M2 += term1;
+
+    // Update min/max
+    if ( value < state.min ) state.min = value;
+    if ( value > state.max ) state.max = value;
+}; // updateFromRaw()
+
+// Combine moments from cascaded input
+const updateFromCascade = function ( state, n, M1, M2, M3, M4, min, max ) {
+    // Initialize combined state if first cascade
+    if ( state.n === 0 ) {
+        state.n = n;
+        state.M1 = M1;
+        state.M2 = M2;
+        state.M3 = M3;
+        state.M4 = M4;
+        state.min = min;
+        state.max = max;
+        return;
+    }
+
+    // Combine using parallel moment algorithm
+    const a_n = state.n;
+    const a_M1 = state.M1;
+    const a_M2 = state.M2;
+    const a_M3 = state.M3;
+    const a_M4 = state.M4;
+
+    const combined_n = a_n + n;
+    const delta = M1 - a_M1;
+    const delta2 = delta * delta;
+    const delta3 = delta * delta2;
+    const delta4 = delta2 * delta2;
+
+    state.M1 = ( ( a_n * a_M1 ) + ( n * M1 ) ) / combined_n;
+
+    state.M2 = a_M2 + M2 +
+                      ( delta2 * a_n * n / combined_n );
+
+    state.M3 = a_M3 + M3 +
+                      ( ( delta3 * a_n * n * ( a_n - n ) ) / ( combined_n * combined_n ) ) +
+                      ( 3 * delta * ( ( a_n * M2 ) - ( n * a_M2 ) ) / combined_n );
+
+    state.M4 = a_M4 + M4 +
+                      ( delta4 * a_n * n * ( ( a_n * a_n ) - ( a_n * n ) + ( n * n ) ) / ( combined_n * combined_n * combined_n ) ) +
+                      ( 6 * delta2 * ( ( a_n * a_n * M2 ) + ( n * n * a_M2 ) ) / ( combined_n * combined_n ) ) +
+                      ( 4 * delta * ( ( a_n * M3 ) - ( n * a_M3 ) ) / combined_n );
+
+    state.n = combined_n;
+
+    // Update min/max
+    if ( min < state.min ) state.min = min;
+    if ( max > state.max ) state.max = max;
+}; // updateFromCascade()
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    prelude( state, msg );
+
+    // Reset on each update
+    state.inputValidationFailed = false;
+
+    if ( state.isCascading ) {
+        // Extract ALL moments using pre-computed field names
+        const fmap = state.fieldMap;
+
+        // Always process parent's moments if available
+        if ( msg[ fmap.n ] !== undefined ) {
+            updateFromCascade(
+                state,
+                msg[ fmap.n ],
+                msg[ fmap.M1 ],
+                msg[ fmap.M2 ],
+                msg[ fmap.M3 ],
+                msg[ fmap.M4 ],
+                msg[ fmap.min ],
+                msg[ fmap.max ]
+            );
+            state.currentCount += 1;
+        }
+
+        // Handle flush signal (overrides window completion)
+        if ( msg[ state.flushSignalKey ] === true && state.n > 0 ) {
+            copyFrom( state, state.snapshot );
+            state.planPublish = true;
+            reset( state );
+            return state;  // Skip window completion check
+        }
+
+        // Fall through to shared window completion logic
+    } else {
+        const xVal = msg[ state.x ];
+        // Handle faults gracefully: ensure their isolation: applies to RAW updates only
+        if ( !Number.isFinite( xVal ) ) {
+            // Signals publishing NaN for all demanded `stats` in publishTo.
+            state.inputValidationFailed = true;
+            return state;
+        }
+        // Update using Pébay's algorithm
+        updateFromRaw( state, xVal );
+        // Increment window counter
+        state.currentCount += 1;
+    }
+
+    // Epilogue: shared window completion logic
+    state.windowComplete = state.currentCount >= state.windowSize;
+    // End-of-window: schedule a publish (unless a flush snapshot is already planned)
+    if ( state.windowComplete && ( !state.planPublish ) && ( !state.inputValidationFailed ) ) {
+        // copy completed window
+        copyFrom( state, state.snapshot );
+        // Will publish snapshot this tick
+        state.planPublish = true;
+        // No flush propagation for plain window completion
+        // Start next window cleanly
+        reset( state );
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/node-names.js

@@ -0,0 +1,67 @@
+// nodes/node-names.js
+
+/**
+ * @fileoverview Single source of truth for valid node names.
+ *
+ * Used for validation when nodes appear in DSL specs. Modules are
+ * loaded lazily at runtime via load-node-module.js.
+ *
+ * Names are camelCase, matching DSL method names. Directory paths
+ * are derived via toKebab() (e.g., 'esMean' -> 'es-mean').
+ */
+
+/**
+ * Set of valid node names for O(1) lookup.
+ * @type {Set<string>}
+ */
+export const NODE_NAMES = new Set( [
+    'accumulate',
+    'appraise',
+    'butterworthFilter',
+    'categorize',
+    'controller',
+    'diff',
+    'digestMoments',
+    'dwellTimeTracker',
+    'emitIf',
+    'esCorrelation',
+    'esMean',
+    'esPairwiseCorrelation',
+    'esStats',
+    'kalman1d',
+    'invertFlag',
+    'kernel',
+    'lag',
+    'median3',
+    'pageHinkley',
+    'passIf',
+    'persistIf',
+    'persistenceCheck',
+    'processIndex',
+    'ratio',
+    'sanitize',
+    'spikeGuard',
+    'stateChangeDetector',
+    'momentsDigest',
+    'swStats',
+    'swingWatch',
+    'tally',
+    'threshold',
+    'transform',
+    'trend',
+    'twStats',
+    'unbalance',
+    'vectorDistance',
+    'winnow'
+] );
+
+/**
+ * Checks if a node name is valid.
+ *
+ * @param {string} name - camelCase node name
+ * @returns {boolean} true if valid
+ */
+export const isValidNodeName = function ( name ) {
+    return NODE_NAMES.has( name );
+};
+