@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/kernel/introspect.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Introspection metadata for kernel node.
+ *
+ * Defines supported stats, control methods, capabilities, DSL schema,
+ * preset validation, default options, and custom kernel validation.
+ * All getters return defensive copies.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+import PRESETS, { getPresetNames } from './presets.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'filtered'
+];
+
+/** Human-readable descriptions */
+const STAT_DESCRIPTIONS = {
+    filtered: 'Result of applying the kernel (weighted sum over sliding window)'
+};
+
+/** 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'
+};
+
+/** The type of this node */
+const NODE_TYPE = 'Kernel';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Apply weighted operations (kernels) over sliding windows in streaming data',
+    features: [
+        'Zero-allocation circular buffer',
+        'Scientifically validated presets (Savitzky-Golay, binomial, etc.)',
+        'Custom kernel support',
+        'Automatic time alignment'
+    ],
+    categories: {
+        smoothing: [ 'smooth3', 'smooth5', 'sg5', 'sg7', 'binomial5', 'binomial7' ],
+        derivatives: [ 'rate', 'rate3', 'accel', 'sgRate5', 'shock', 'jerk' ],
+        detection: [ 'spike3', 'edge5', 'impulse' ],
+        slope: [ 'trend5', 'trend7', 'trend9', 'trend11', 'momentum5' ],
+        industrial: [ 'debounce5', 'envelope', 'volatility' ]
+    }
+};
+
+// Export functions for accessing metadata
+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(),
+    categories: { ...CAPABILITIES.categories }
+} );
+export const getPresets = () => ( { ...PRESETS } );
+
+/** Default options — kernel has no optional parameters. */
+export const DEFAULT_OPTIONS = {};
+
+// Custom validators
+// Describes one kernel: an array of 2-100 finite numbers. The validation engine
+// applies this per entry of a field-keyed map { field: [ ... ] }, so this stays a
+// plain single-value check (see runCustomValidator in validate/helpers.js).
+const kernelValidator = ( value ) => {
+    if ( !Array.isArray( value ) ) return false;
+    if ( value.length < 2 ) return false;
+    if ( value.length > 100 ) return false; // Reasonable limit
+    return value.every( ( v ) => Number.isFinite( v ) );
+};
+
+// DSL Metadata for transpiler
+const DSL_METADATA = {
+    // Validation schema
+    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'
+                }
+            }
+        },
+        // Either preset OR kernel must be provided
+        preset: {
+            type: 'stringOrFieldKeyed',
+            required: false,
+            validator: validators.oneOf( getPresetNames() ),
+            error: `Preset must be one of: ${getPresetNames().join(', ')}`
+        },
+        kernel: {
+            type: 'arrayOrFieldKeyed',
+            required: false,
+            validator: kernelValidator,
+            error: 'Kernel must be an array of 2-100 numbers'
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'preset', 'kernel' ],
+            validator: ( spec ) => {
+                // Exactly one must be provided
+                const hasPreset = spec.preset !== undefined;
+                const hasKernel = spec.kernel !== undefined;
+                return ( hasPreset && !hasKernel ) || ( !hasPreset && hasKernel );
+            },
+            error: 'Must provide either preset or kernel, but not both'
+        }
+    ],
+
+    // Build spec from DSL
+    // 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 } );

package/src/nodes/kernel/presets.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Scientifically validated filter kernels for common streaming operations.
+ *
+ * Each preset is optimized for specific use cases in industrial, financial,
+ * and quality control applications. Kernels are defined in newest-to-oldest
+ * order (kernel[0] = weight for x[n]).
+ */
+
+const PRESETS = Object.create( null );
+// Basic smoothing operations
+PRESETS.smooth3 = [ 0.25, 0.5, 0.25 ];                      // 3-point Gaussian approximation
+PRESETS.smooth5 = [ 0.1, 0.2, 0.4, 0.2, 0.1 ];              // 5-point Gaussian approximation
+
+// Derivatives
+PRESETS.rate = [ -1, 1 ];                                   // Simple difference (1st derivative)
+PRESETS.rate3 = [ -1, 0, 1 ];                               // Centered difference (less noise)
+PRESETS.accel = [ 1, -2, 1 ];                               // 2nd derivative (acceleration)
+
+// Savitzky-Golay filters (preserves peaks while smoothing)
+PRESETS.sg5 = [ -3 / 35, 12 / 35, 17 / 35, 12 / 35, -3 / 35 ]; // 5-point, 2nd order polynomial
+PRESETS.sg7 = [ -2 / 21, 3 / 21, 6 / 21, 7 / 21, 6 / 21, 3 / 21, -2 / 21 ]; // 7-point, 2nd order
+PRESETS.sgRate5 = [ -2 / 10, -1 / 10, 0, 1 / 10, 2 / 10 ];     // SG 1st derivative
+
+// Trend kernels — Savitzky-Golay 1st-derivative (slope) filters, with
+// the sign chosen so that a rising signal produces a POSITIVE slope and
+// a falling signal produces a NEGATIVE slope. This matches the standard
+// calculus/academic convention and reads naturally in thresholding code:
+// `threshold({ below: -0.06 })` fires on a downward trend.
+//
+// Note: the older `sgRate5` preset uses the opposite sign (falling →
+// positive) because kernel weights are user-defined newest-to-oldest
+// and sgRate5 pre-dates this convention discussion. The trend family
+// is independent — use these when the sign should read as a slope.
+//
+// weights_i = −i / Σi²   for i = −N..N (newest-to-oldest user order).
+// Wider windows trade latency for smoothness: trend5 is the most
+// responsive, trend11 the smoothest. Pair with threshold +
+// persistenceCheck to detect sustained rising or falling trends.
+// Reference: Savitzky & Golay (1964), Anal. Chem. 36(8), 1627.
+PRESETS.trend5  = [ 2 / 10, 1 / 10, 0, -1 / 10, -2 / 10 ];            // Σi² = 10
+PRESETS.trend7  = [ 3 / 28, 2 / 28, 1 / 28, 0, -1 / 28, -2 / 28, -3 / 28 ];  // Σi² = 28
+PRESETS.trend9  = [ 4 / 60, 3 / 60, 2 / 60, 1 / 60, 0,
+                    -1 / 60, -2 / 60, -3 / 60, -4 / 60 ];              // Σi² = 60
+PRESETS.trend11 = [ 5 / 110, 4 / 110, 3 / 110, 2 / 110, 1 / 110, 0,
+                    -1 / 110, -2 / 110, -3 / 110, -4 / 110, -5 / 110 ]; // Σi² = 110
+
+// Binomial filters (optimal noise reduction)
+PRESETS.binomial5 = [ 1 / 16, 4 / 16, 6 / 16, 4 / 16, 1 / 16 ]; // Pascal's triangle row 4
+PRESETS.binomial7 = [ 1 / 64, 6 / 64, 15 / 64, 20 / 64, 15 / 64, 6 / 64, 1 / 64 ]; // Row 6
+
+// Industrial process control
+PRESETS.debounce5 = [ 0.1, 0.2, 0.4, 0.2, 0.1 ];            // Digital signal debouncing
+
+// Detection filters
+PRESETS.spike3 = [ -1, 2, -1 ];                             // Spike/transient detection
+PRESETS.edge5 = [ -1, -1, 5, -1, -1 ];                      // Edge enhancement (Laplacian)
+PRESETS.impulse = [ 0.25, -1, 1.5, -1, 0.25 ];              // Impulse/event detection
+
+// Mechanical/vibration analysis
+PRESETS.shock = [ 1, -2, 1 ];                               // Shock/impact detection
+PRESETS.jerk = [ -1, 3, -3, 1 ];                            // 3rd derivative (jerk)
+PRESETS.envelope = [ 0.1, 0.15, 0.5, 0.15, 0.1 ];           // Envelope extraction
+
+// Business/financial metrics
+PRESETS.momentum5 = [ -0.3, -0.1, 0, 0.1, 0.3 ];            // Weighted momentum
+PRESETS.volatility = [ -1, 2, -1 ];                         // Local variance proxy
+
+export default PRESETS;
+
+// Helper to validate preset names
+export const isValidPreset = ( name ) => Object.prototype.hasOwnProperty.call( PRESETS, name );
+
+// Get list of all preset names for validation
+export const getPresetNames = () => Object.keys( PRESETS );

package/src/nodes/kernel/publish-to.js

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Publish function for kernel node.
+ *
+ * Copies the convolution result to the outgoing message. Gates on warmup
+ * (ring buffer not yet full) and input validation failure (publishes NaN).
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+import { isNotFull } from '../../windowing/count-sliding/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+    // Propagate NaN if unhealthy
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    // Ring is full (warmup complete) — publish the result
+    if ( !isNotFull( state.ring ) ) {
+        msg[ state.stats.filtered.storeAs ] = state.result;
+    }
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/kernel/recompute.js

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Recompute for kernel node.
+ *
+ * No-op — returns true. The convolution result is computed fresh from ring
+ * buffer contents on every message, so there is no accumulator drift to
+ * correct. Unlike recursive filters (e.g., Kalman), FIR convolution is
+ * inherently stable.
+ */
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/kernel/reset.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Reset for kernel node.
+ *
+ * Clears the ring buffer and result. Configuration properties (kernel,
+ * field names, stats) are preserved across reset.
+ */
+
+import * as ring from '../../windowing/count-sliding/index.js';
+
+const reset = function ( state ) {
+    // Reset window state
+    ring.reset( state.ring );
+
+    // Clear result
+    state.result = 0;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/kernel/update.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Core FIR convolution for kernel node (hot path).
+ *
+ * Pushes each valid input into a doubled ring buffer — each value is written
+ * at `buffer[ head ]` AND `buffer[ head + size ]` so the convolution window
+ * is always contiguous at `buffer[ head .. head + size - 1 ]`, eliminating
+ * the wrap branch inside the inner loop. Push and fullness check are
+ * inlined. The kernel array has been reversed at init (see init.js) so the
+ * buffer is read oldest-to-newest with the kernel indexed 0..L-1.
+ *
+ * Zero allocations in the hot path — all arithmetic on pre-allocated
+ * structures created in init(). Fault isolation via `inputValidationFailed`
+ * flag propagates NaN downstream through publishTo().
+ *
+ * References:
+ *  - Oppenheim & Schafer, "Discrete-Time Signal Processing", Ch. 2.3
+ *    (Convolution Sum).
+ *  - "Duplicated head" ring-buffer pattern (FFTW small-transform codelets,
+ *    https://www.fftw.org/fftw-paper-ieee.pdf Sec. III.B).
+ *  - Benchmark: 2.2-2.6× speedup vs. the prior single-size ring
+ *    implementation (measured; ADR-012).
+ */
+
+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: flag and continue — downstream sees NaN
+    if ( !Number.isFinite( xVal ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    const ring = state.ring;
+    const size = ring.size;
+    const buffer = ring.buffer;
+    let head = ring.head;
+
+    // Doubled-buffer push: write at head AND head + size.
+    // Head advances within [ 0, size ); the mirror half makes the read
+    // window contiguous without a modulus or wrap branch.
+    buffer[ head ] = xVal;
+    buffer[ head + size ] = xVal;
+    head = ( head + 1 < size ) ? head + 1 : 0;
+    ring.head = head;
+
+    // Warmup: grow `used` up to `size`, then skip convolution while still
+    // partial. Once `used === size` on the current push, fall through to
+    // compute the first convolution output on that same message — matches
+    // baseline semantics (fill-then-compute on the boundary push).
+    if ( ring.used < size ) {
+        ring.used += 1;
+        if ( ring.used < size ) return state;
+    }
+
+    // Contiguous convolution — no wrap branch in the inner loop.
+    const kernel = state.kernel;
+    const kernelLength = state.kernelLength;
+    let sum = 0;
+    for ( let i = 0; i < kernelLength; i += 1 ) {
+        sum += buffer[ head + i ] * kernel[ i ];
+    }
+
+    state.result = sum;
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/lag/index.js

@@ -0,0 +1,21 @@
+// nodes/lag/index.js
+
+/**
+ * @fileoverview Exports for the lag node.
+ *
+ * The lag node computes five lag-based statistics: delta, ratio, roc,
+ * slope, and logReturn. This replaces and extends the former delta node.
+ *
+ * @see ADR-004 for patterns
+ */
+
+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 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';
+export * from './introspect.js';

package/src/nodes/lag/init.js

@@ -0,0 +1,87 @@
+// nodes/lag/init.js
+
+/**
+ * @fileoverview Initializes the lag node state.
+ *
+ * Creates pre-allocated ring buffer(s) and pre-computes stat flags for
+ * zero-allocation hot path execution. Follows ADR-004 patterns.
+ *
+ * @see ADR-004
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { create } from '../../windowing/count-sliding/index.js';
+import { resolveScalar } from '../../core/utils/options/resolve-field-keyed.js';
+
+/**
+ * Initializes the lag node state from a validated spec.
+ *
+ * @param {Object} spec - Node specification
+ * @param {string} spec.name - Unique node identifier
+ * @param {Object} spec.from - Input field configuration
+ * @param {string} spec.from.x - Input field name for values
+ * @param {string} [spec.timestamp] - Input field name for timestamps (required for slope)
+ * @param {number|Object} [spec.lag=1] - Lag window size (supports field-keyed)
+ * @param {boolean} [spec.absolute=false] - Apply Math.abs to delta and slope
+ * @param {Object} spec.stats - Output statistics configuration
+ * @returns {Object} Initialized state object
+ */
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    // Create state with null prototype (ADR-004: avoid prototype pollution)
+    const state = Object.create( null );
+
+    // ── Standard Flags ─────────────────────────────────────────────────────
+    state.inputValidationFailed = false;
+    state.disable = false;
+    state.pause = false;
+
+    // ── Configuration from Spec ────────────────────────────────────────────
+    state.x = spec.from.x;
+    state.timestamp = spec.timestamp ?? null;
+    state.stats = spec.stats;
+
+    // Resolve lag (supports field-keyed specification)
+    const lagSpec = resolveScalar( spec.lag, state.x );
+    state.lag = lagSpec ?? introspect.DEFAULT_OPTIONS.lag;
+
+    // Apply defaults for optional parameters
+    state.absolute = spec.absolute ?? introspect.DEFAULT_OPTIONS.absolute;
+
+    // ── Pre-allocated Ring Buffers ─────────────────────────────────────────
+    // Primary ring buffer for x values (always allocated)
+    state.ringX = create( state.lag );
+
+    // Secondary ring buffer for timestamps (only if slope is requested)
+    state.ringT = ( spec.stats.slope === undefined ) ? null : create( state.lag );
+
+    // ── Pre-computed Stat Flags (zero-branch hot path) ─────────────────────
+    // These flags avoid object property iteration in update()
+    state.hasDelta = spec.stats.delta !== undefined;
+    state.hasRatio = spec.stats.ratio !== undefined;
+    state.hasRoc = spec.stats.roc !== undefined;
+    state.hasSlope = spec.stats.slope !== undefined;
+    state.hasLogReturn = spec.stats.logReturn !== undefined;
+    state.hasCumDelta = spec.stats.cumDelta !== undefined;
+    state.hasXLag = spec.stats.xLag !== undefined;
+
+    // ── Computed Values (output storage) ───────────────────────────────────
+    // Initialize to NaN (startup state before buffer fills)
+    state.delta = NaN;
+    state.ratio = NaN;
+    state.roc = NaN;
+    state.slope = NaN;
+    state.logReturn = NaN;
+    state.xLag = NaN;
+    // cumDelta initializes to 0 (integral from a to a = 0)
+    state.cumDelta = 0;
+
+    // ── Metadata ───────────────────────────────────────────────────────────
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/lag/introspect.js

@@ -0,0 +1,202 @@
+// nodes/lag/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for the lag node.
+ *
+ * The lag node computes five lag-based statistics from a single ring buffer:
+ * delta, ratio, roc (rate of change), slope (time-normalized), and logReturn.
+ * This replaces and extends the former delta node.
+ *
+ * @see ADR-004 for patterns
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/**
+ * Supported output statistics.
+ * At least one must be specified in the spec.
+ * @type {string[]}
+ */
+const SUPPORTED_STATS = [
+    'delta',
+    'ratio',
+    'roc',
+    'slope',
+    'logReturn',
+    'cumDelta',
+    'xLag'
+];
+
+/**
+ * Human-readable descriptions for each statistic.
+ * @type {Object<string, string>}
+ */
+const STAT_DESCRIPTIONS = {
+    delta: 'Absolute change: x - x_lag',
+    ratio: 'Relative value: x / x_lag',
+    roc: 'Rate of change (percentage): (x - x_lag) / x_lag',
+    slope: 'Time-normalized change: (x - x_lag) / (t - t_lag)',
+    logReturn: 'Log return (continuously compounded): ln(x / x_lag)',
+    cumDelta: 'Cumulative delta: running sum of (x - x_lag), reset sets lower limit',
+    xLag: 'Lagged input value: the value pushed lag samples ago. NaN during the warmup window (first lag samples).'
+};
+
+/**
+ * Control methods available for triggers.
+ * @type {Object<string, string>}
+ */
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Resets computed values; preserves ring buffer when cumDelta is configured (ADR-008)',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+/**
+ * Node type identifier.
+ * @type {string}
+ */
+const NODE_TYPE = 'Lag';
+
+/**
+ * Node capabilities for documentation and introspection.
+ * @type {Object}
+ */
+const CAPABILITIES = {
+    description: 'Computes lag-based statistics comparing current and historical values',
+    features: [
+        'Seven statistics: delta, ratio, roc, slope, logReturn, cumDelta, xLag',
+        'Configurable lag window for historical comparison',
+        'Optional absolute value transformation for delta and slope',
+        'Shared ring buffer for memory efficiency',
+        'Optional timestamp support for slope computation',
+        'Handles missing/invalid data gracefully with NaN propagation',
+        'Cumulative delta for integration-style computations with reset',
+        'Direct xLag publication for lookback-based downstream patterns'
+    ]
+};
+
+// ── Exported Getters (defensive copies) ────────────────────────────────────
+
+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()
+} );
+
+// ── Default Options ────────────────────────────────────────────────────────
+
+/**
+ * Default values for optional spec parameters.
+ * @type {Object}
+ */
+export const DEFAULT_OPTIONS = {
+    lag: 1,
+    absolute: false
+};
+
+// ── DSL Metadata ───────────────────────────────────────────────────────────
+
+/**
+ * DSL metadata for transpilation and validation.
+ *
+ * Signature pattern: NAME_X_OUTPUTS_OPTIONS
+ * DSL call: .lag( name, x, stats, options )
+ */
+const DSL_METADATA = {
+    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: 'from.x must not contain spaces'
+                }
+            }
+        },
+        lag: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            integer: true,
+            min: 1,
+            default: DEFAULT_OPTIONS.lag
+        },
+        timestamp: {
+            type: 'string',
+            required: false,
+            validator: validators.noSpaces,
+            error: 'timestamp must not contain spaces'
+        },
+        absolute: {
+            type: 'boolean',
+            required: false,
+            default: DEFAULT_OPTIONS.absolute
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        minLength: 1,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'stats', 'timestamp' ],
+            validator: ( spec ) => {
+                // If slope stat is requested, timestamp field is required
+                if ( spec.stats?.slope !== undefined ) {
+                    return spec.timestamp !== undefined;
+                }
+                return true;
+            },
+            error: 'timestamp is required when slope stat is requested'
+        }
+    ],
+
+    // Build spec from DSL arguments
+    buildSpec: ( name, x, stats, options ) => {
+        const spec = {
+            nodeType: NODE_TYPE,
+            name,
+            from: { x },
+            stats,
+            ...options
+        };
+        return spec;
+    }
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );