@winkjs/composer 0.0.2 → 0.4.0

package/src/flow/validate.js

@@ -0,0 +1,261 @@
+// flow/validate.js
+
+/**
+ * @fileoverview Flow validation without execution.
+ *
+ * Validates specs, checks node references, verifies trigger targets,
+ * verifies that adapters' declared semantic requirements are met by the
+ * flow runtime, and reports any configuration errors. Provides fail-fast
+ * validation at transpile/load time before runtime execution.
+ *
+ * Registered emitters/storages arrive as module maps
+ * `{ id: adapterModule }` (they used to be bare ID arrays).
+ * The IDs are used for the cross-flow target check; the modules
+ * are also used to read each adapter's `semanticsRequirement`
+ * declaration so that "persistIf needs an assetClass" is a derived
+ * fact (driven by the storage adapter's declaration), not a hardcoded
+ * rule baked into validate.js.
+ */
+
+import { validateTriggers } from './validate-triggers.js';
+
+/**
+ * Validates emitter targets in specs against registered emitters.
+ * Ensures all emitIf nodes reference emitters that have been registered.
+ *
+ * @param {Array} specs - Node specifications
+ * @param {Object} registeredEmitters - Map `{ id: adapterModule }` of registered emitters
+ * @returns {Array<string>} Array of error messages (empty if valid)
+ */
+const validateEmitterTargets = function ( specs, registeredEmitters ) {
+    const errors = [];
+    const ids = Object.keys( registeredEmitters );
+
+    for ( let i = 0; i < specs.length; i += 1 ) {
+        const spec = specs[ i ];
+        if ( spec.nodeType === 'Emit If' && spec.target ) {
+            if ( !( spec.target in registeredEmitters ) ) {
+                const registeredList = ids.length > 0 ?
+                    ids.join( ', ' ) :
+                    'none';
+                errors.push(
+                    `emitIf '${spec.name}' targets '${spec.target}' but only these emitters are registered: [${registeredList}]`
+                );
+            }
+        }
+    }
+
+    return errors;
+};
+
+/**
+ * Validates storage targets in specs against registered storages.
+ * Ensures all persistIf nodes reference storages that have been registered.
+ *
+ * @param {Array} specs - Node specifications
+ * @param {Object} registeredStorages - Map `{ id: adapterModule }` of registered storages
+ * @returns {Array<string>} Array of error messages (empty if valid)
+ */
+const validateStorageTargets = function ( specs, registeredStorages ) {
+    const errors = [];
+    const ids = Object.keys( registeredStorages );
+
+    for ( let i = 0; i < specs.length; i += 1 ) {
+        const spec = specs[ i ];
+        if ( spec.nodeType === 'Persist If' && spec.storageName ) {
+            if ( !( spec.storageName in registeredStorages ) ) {
+                const registeredList = ids.length > 0 ?
+                    ids.join( ', ' ) :
+                    'none';
+                errors.push(
+                    `persistIf '${spec.name}' targets '${spec.storageName}' but only these storages are registered: [${registeredList}]`
+                );
+            }
+        }
+    }
+
+    return errors;
+};
+
+/**
+ * Walks every registered emitter and storage module; for each adapter
+ * that declares `semanticsRequirement.assetClass.required: true`, errors
+ * if `assetClass` is null/undefined.
+ *
+ * Replaces the old hardcoded "persistIf requires .assetClass()" rule.
+ * The requirement now lives where it semantically belongs — on the
+ * adapter that actually reads the asset class (e.g., QuestDB declares
+ * required:true; a future storage that doesn't read semantics declares
+ * required:false or no declaration at all).
+ *
+ * One error per missing-required adapter, naming the adapter and its
+ * kind (storage/emitter) so the operator knows what to fix.
+ *
+ * @param {Object} registeredEmitters - Map `{ id: adapterModule }`
+ * @param {Object} registeredStorages - Map `{ id: adapterModule }`
+ * @param {Object|null} assetClass - Asset class from runtime, or null
+ * @returns {Array<string>} Array of error messages (empty if valid)
+ */
+const validateSemanticsRequirements = function ( registeredEmitters, registeredStorages, assetClass ) {
+    if ( assetClass ) {
+        return [];
+    }
+
+    const errors = [];
+
+    const checkOne = function ( id, module, kind ) {
+        const requirement = module && module.semanticsRequirement;
+        if ( requirement && requirement.assetClass && requirement.assetClass.required ) {
+            errors.push(
+                `${kind} '${id}' declares semanticsRequirement.assetClass.required ` +
+                'but the flow has no .assetClass() — add .assetClass(assetClassDef) before declaring this adapter'
+            );
+        }
+    };
+
+    const emitterEntries = Object.entries( registeredEmitters );
+    for ( let i = 0; i < emitterEntries.length; i += 1 ) {
+        const [ id, module ] = emitterEntries[ i ];
+        checkOne( id, module, 'emitter' );
+    }
+
+    const storageEntries = Object.entries( registeredStorages );
+    for ( let i = 0; i < storageEntries.length; i += 1 ) {
+        const [ id, module ] = storageEntries[ i ];
+        checkOne( id, module, 'storage' );
+    }
+
+    return errors;
+};
+
+/**
+ * Validates insightType references in persistIf specs against asset class.
+ *
+ * Each persistIf insightType must exist in the asset class's insightTypes.
+ * The old blanket "persistIf requires .assetClass()" check moved to
+ * `validateSemanticsRequirements` (capability-driven). When `assetClass`
+ * is null here, that earlier check has already produced its error;
+ * this function silently skips the cross-ref to avoid duplicate noise.
+ *
+ * @param {Array} specs - Node specifications
+ * @param {Object|null} assetClass - Asset class from runtime (null if not declared)
+ * @returns {Array<string>} Array of error messages (empty if valid)
+ */
+const validateInsightTypeReferences = function ( specs, assetClass ) {
+    const errors = [];
+
+    if ( !assetClass ) {
+        // Either the flow doesn't need an asset class (no adapter declared
+        // `assetClass.required: true` — see validateSemanticsRequirements),
+        // or it does and that earlier check already reported the missing
+        // .assetClass(). Either way, no useful cross-ref work to do here.
+        return errors;
+    }
+
+    const persistIfNodes = [];
+    for ( let i = 0; i < specs.length; i += 1 ) {
+        const spec = specs[ i ];
+        if ( spec.nodeType === 'Persist If' && spec.insightType ) {
+            persistIfNodes.push( spec );
+        }
+    }
+
+    if ( persistIfNodes.length === 0 ) {
+        return errors;
+    }
+
+    const validInsightTypes = Object.keys( assetClass.insightTypes || {} );
+    for ( let i = 0; i < persistIfNodes.length; i += 1 ) {
+        const spec = persistIfNodes[ i ];
+        const insightType = spec.insightType;
+
+        if ( !validInsightTypes.includes( insightType ) ) {
+            const validList = validInsightTypes.length > 0 ?
+                validInsightTypes.join( ', ' ) :
+                'none defined';
+            errors.push(
+                `persistIf '${spec.name}': insightType '${insightType}' not found in ` +
+                `asset class '${assetClass.name}' (valid: ${validList})`
+            );
+        }
+    }
+
+    return errors;
+};
+
+/**
+ * Validates the flow without executing.
+ *
+ * `registeredEmitters` / `registeredStorages` are `{ id: adapterModule }`
+ * maps (they used to be bare ID arrays; call sites that pass arrays
+ * must be updated). Tests that exercise validateFlow directly pass
+ * module maps. The IDs are used for cross-flow target validation; the
+ * modules are used for capability-driven `semanticsRequirement`
+ * checks.
+ *
+ * @param {string} flowName - Name of the flow
+ * @param {Array} specs - Node specifications
+ * @param {Object} nodeModules - Map of module name to node module
+ * @param {Object} [registeredEmitters={}] - Map `{ id: module }` of registered emitters
+ * @param {Object} [registeredStorages={}] - Map `{ id: module }` of registered storages
+ * @param {Object|null} [assetClass=null] - Asset class for capability + insightType validation
+ * @returns {{valid: boolean, errors: Array<string>}} Validation result
+ */
+export const validateFlow = function ( flowName, specs, nodeModules, registeredEmitters = {}, registeredStorages = {}, assetClass = null ) {
+    const errors = [];
+
+    // Phase 1: Trigger validation (R1, R2, R3)
+    const triggerResult = validateTriggers( specs, nodeModules );
+    if ( !triggerResult.valid ) {
+        errors.push( ...triggerResult.errors );
+    }
+
+    // Phase 2: Emitter target validation
+    const emitterErrors = validateEmitterTargets( specs, registeredEmitters );
+    errors.push( ...emitterErrors );
+
+    // Phase 3: Storage target validation
+    const storageErrors = validateStorageTargets( specs, registeredStorages );
+    errors.push( ...storageErrors );
+
+    // Phase 4: Capability-driven semanticsRequirement check
+    // (replaced the hardcoded "persistIf requires .assetClass()" rule)
+    const semanticsErrors = validateSemanticsRequirements(
+        registeredEmitters,
+        registeredStorages,
+        assetClass
+    );
+    errors.push( ...semanticsErrors );
+
+    // Phase 5: insightType validation against asset class
+    const insightTypeErrors = validateInsightTypeReferences( specs, assetClass );
+    errors.push( ...insightTypeErrors );
+
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+};
+
+/**
+ * Validates flow and throws if invalid.
+ * Convenience wrapper for fail-fast validation in pipelines.
+ *
+ * @param {string} flowName - Name of the flow
+ * @param {Array} specs - Node specifications
+ * @param {Object} nodeModules - Map of module name to node module
+ * @param {Object} [registeredEmitters={}] - Map `{ id: module }` of registered emitters
+ * @param {Object} [registeredStorages={}] - Map `{ id: module }` of registered storages
+ * @param {Object|null} [assetClass=null] - Asset class for capability + insightType validation
+ * @throws {Error} If validation fails
+ */
+export const validateFlowOrThrow = function ( flowName, specs, nodeModules, registeredEmitters = {}, registeredStorages = {}, assetClass = null ) {
+    const result = validateFlow( flowName, specs, nodeModules, registeredEmitters, registeredStorages, assetClass );
+    if ( !result.valid ) {
+        const errorList = result.errors.map( ( e ) => `  - ${e}` ).join( '\n' );
+        throw new Error(
+            `Flow '${flowName}' validation failed:\n${errorList}`
+        );
+    }
+};
+

package/src/nodes/accumulate/index.js

@@ -0,0 +1,21 @@
+// nodes/accumulate/index.js
+
+/**
+ * @fileoverview Accumulate node module exports.
+ *
+ * Simple running sum accumulator for conditional accumulation.
+ * Works with controller disable/enable — no embedded predicate needed.
+ *
+ * @see ADR-004
+ */
+
+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/accumulate/init.js

@@ -0,0 +1,48 @@
+// nodes/accumulate/init.js
+
+/**
+ * @fileoverview Initializes the accumulate node state.
+ *
+ * Creates state object with running sum initialized to zero.
+ * No ring buffer needed — simple accumulation with disable/enable support.
+ *
+ * @see ADR-004
+ */
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+
+/**
+ * Initializes the accumulate 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 to accumulate
+ * @param {Object} spec.stats - Output statistics configuration
+ * @returns {Object} Initialized state object
+ */
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    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.stats = spec.stats;
+
+    // ── Accumulated Value ──────────────────────────────────────────────────
+    state.sum = 0;
+
+    // ── Metadata ───────────────────────────────────────────────────────────
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/accumulate/introspect.js

@@ -0,0 +1,123 @@
+// nodes/accumulate/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for the accumulate node.
+ *
+ * Defines supported stats, control methods, capabilities, and DSL schema
+ * for a simple running sum accumulator. Works with controller disable/enable
+ * for conditional accumulation without embedded predicate.
+ *
+ * @see ADR-004
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+// ── Supported Statistics ────────────────────────────────────────────────────
+
+const SUPPORTED_STATS = [ 'sum' ];
+
+const STAT_DESCRIPTIONS = {
+    sum: 'Running sum of input values'
+};
+
+// ── Control Methods ─────────────────────────────────────────────────────────
+
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears accumulated sum to zero',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses node processing while keeping state visible',
+    unpause: 'Resumes node processing after pause'
+};
+
+// ── Node Identity ───────────────────────────────────────────────────────────
+
+const NODE_TYPE = 'Accumulate';
+
+// ── Capabilities ────────────────────────────────────────────────────────────
+
+const CAPABILITIES = {
+    description: 'Accumulates numeric values into a running sum',
+    features: [
+        'Simple running sum (no windowing)',
+        'Works with controller disable/enable for conditional accumulation',
+        'Expects periodic resets — unbounded sum drifts without them',
+        'No ring buffer — no catch-up problem when disabled',
+        'Zero allocation in hot path'
+    ]
+};
+
+// ── Default Options ─────────────────────────────────────────────────────────
+
+const DEFAULT_OPTIONS = {};
+
+// ── DSL Metadata ────────────────────────────────────────────────────────────
+
+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'
+                }
+            }
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            minProperties: 1,
+            propertyNames: SUPPORTED_STATS,
+            propertySchema: {
+                type: 'object',
+                required: true,
+                properties: {
+                    storeAs: {
+                        type: 'string',
+                        required: true,
+                        validator: validators.identifier,
+                        error: 'storeAs must be a valid identifier'
+                    }
+                }
+            }
+        }
+    },
+
+    crossFieldValidators: [],
+
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...options
+    } )
+};
+
+// ── Getter Functions (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()
+} );
+export { DEFAULT_OPTIONS };
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

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

@@ -0,0 +1,34 @@
+// nodes/accumulate/publish-to.js
+
+/**
+ * @fileoverview Publishes accumulated sum to output message.
+ *
+ * Copies state.sum to the configured output field. On validation failure,
+ * publishes NaN for fault isolation downstream.
+ *
+ * @see ADR-004
+ */
+
+import { publishNaN } from '../../core/utils/node/index.js';
+
+/**
+ * Publishes the accumulated sum to the output message.
+ *
+ * @param {Object} state - Node state
+ * @param {Object} msg - Output message to populate
+ */
+const publishTo = function ( state, msg ) {
+    // Guard: skip if disabled
+    if ( state.disable ) return;
+
+    // Fault isolation: propagate NaN if input validation failed
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    // Publish sum
+    msg[ state.stats.sum.storeAs ] = state.sum;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/accumulate/recompute.js

@@ -0,0 +1,27 @@
+// nodes/accumulate/recompute.js
+
+/**
+ * @fileoverview Numerical stability handler for accumulate node.
+ *
+ * Running sum is numerically stable for bounded accumulation windows —
+ * controller resets prevent unbounded drift. Without resets, IEEE 754
+ * rounding error grows with the number of additions, and precision
+ * degrades when magnitudes vary widely. No recomputation is possible
+ * here (no ring buffer to re-sum from), so timely controller resets
+ * are essential.
+ *
+ * @see ADR-004
+ */
+
+/**
+ * Handles numerical stability (no-op — no history buffer to recompute from).
+ *
+ * @returns {boolean} Always returns true
+ */
+const recompute = function () {
+    // No-op: controller resets bound the accumulation window.
+    // Without resets, sum drifts — but there is no ring buffer to re-sum from.
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/accumulate/reset.js

@@ -0,0 +1,25 @@
+// nodes/accumulate/reset.js
+
+/**
+ * @fileoverview Resets the accumulate node state.
+ *
+ * Clears accumulated sum to zero. Called by controller triggers
+ * to start a new accumulation window.
+ *
+ * @see ADR-004
+ */
+
+/**
+ * Resets the accumulated sum to zero.
+ *
+ * @param {Object} state - Node state to reset
+ * @returns {boolean} Always returns true (success)
+ */
+const reset = function ( state ) {
+    // Reset accumulated sum to zero
+    state.sum = 0;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/accumulate/update.js

@@ -0,0 +1,42 @@
+// nodes/accumulate/update.js
+
+/**
+ * @fileoverview Hot path for accumulate node message processing.
+ *
+ * Simple running sum with zero allocation. When disabled, skips update
+ * entirely — sum remains unchanged. No ring buffer, so no catch-up problem
+ * when re-enabled after disabled period.
+ *
+ * @see ADR-004
+ */
+
+/**
+ * Processes a message and accumulates the input value.
+ *
+ * @param {Object} state - Node state from init()
+ * @param {Object} msg - Incoming message with field values
+ * @returns {Object} Updated state
+ */
+const update = function ( state, msg ) {
+    // Guard: skip if disabled or paused
+    if ( state.disable || state.pause ) return state;
+
+    // Extract input value
+    const xVal = msg[ state.x ];
+
+    // Reset health flag
+    state.inputValidationFailed = false;
+
+    // Validate input (catches NaN, Infinity, undefined)
+    if ( !Number.isFinite( xVal ) ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    // Accumulate
+    state.sum += xVal;
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/appraise/calibrate.js

@@ -0,0 +1,64 @@
+// nodes/appraise/calibrate.js
+
+/**
+ * @fileoverview Burn-in calibration for the L2 decision neuron's Theta parameter.
+ *
+ * During warmup, the system observes baseline membrane activity and derives
+ * Theta such that steady-state conviction sits at c_target (monitor.at / 3).
+ * Uses a deterministic sample count — same pattern as esCorrelation and trend
+ * warmup (halfLifeToWarmupSamples equivalent).
+ *
+ * Formula: Theta = V2 * ( 1 - c_target ) / c_target
+ *   When V2 = 0 at warmup end, Theta defaults to 1.0 (conservative fallback).
+ */
+
+/**
+ * Computes the number of warmup messages needed for calibration.
+ * Five L2 time constants ensures the membrane has reached steady-state
+ * (~99.3% settled).
+ *
+ * @param {number} l2Tau - L2 time constant tau2
+ * @param {number} messageRate - Messages per timestamp unit
+ * @returns {number} Warmup sample count (integer >= 1)
+ */
+const computeWarmupSamples = function ( l2Tau, messageRate ) {
+    return Math.max( 1, Math.ceil( 5 * l2Tau * messageRate ) );
+}; // computeWarmupSamples()
+
+/**
+ * Derives the calibration target conviction from the monitor threshold.
+ * Steady-state baseline should sit at one-third of the monitor threshold —
+ * close enough for sensitivity, far enough to avoid false triggers.
+ *
+ * @param {number} monitorAt - Monitor threshold value
+ * @returns {number} c_target in (0, 1)
+ */
+const deriveCTarget = function ( monitorAt ) {
+    return monitorAt / 3;
+}; // deriveCTarget()
+
+/**
+ * Checks whether calibration is complete and derives Theta if so.
+ * Called once per message during the warmup phase. No-op before
+ * the warmup boundary, no-op after calibration is complete.
+ *
+ * @param {Object} state - Node state (mutated: l2Theta, calibrating)
+ */
+const checkCalibration = function ( state ) {
+    if ( state.messageCount < state.warmupSamples ) return;
+
+    // Derive Theta from observed steady-state membrane potential
+    const v2 = state.l2Membrane;
+
+    if ( v2 <= 0 ) {
+        // No activity during warmup — use conservative default
+        state.l2Theta = 1.0;
+    } else {
+        // Theta = V2 * ( 1 - c_target ) / c_target
+        state.l2Theta = v2 * ( ( 1 - state.cTarget ) / state.cTarget );
+    }
+
+    state.calibrating = false;
+}; // checkCalibration()
+
+export { computeWarmupSamples, deriveCTarget, checkCalibration };