@winkjs/composer 0.0.2 → 0.4.1

package/src/nodes/persistence-check/introspect.js

@@ -0,0 +1,144 @@
+// nodes/persistence-check/introspect.js
+
+import { validators, composerValidators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'persistenceConfirmed'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    persistenceConfirmed: 'True if a predicate meets or exceeds the minimum votes out of a given total'
+};
+
+/** 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 = 'Persistence Check';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Confirms persistence when a predicate satisfies a minimum threshold within a window',
+    features: [
+        'Evaluates predicate with filtered inputs and counter arguments',
+        'Voting mechanism for stability confirmation',
+        'Configurable minimum votes and window size',
+        'Automatic reset after publishing confirmation'
+    ]
+};
+
+// 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() } );
+
+// Spec default values
+export const DEFAULT_OPTIONS = {
+    minVotes: 3,
+    outOfTotal: 5
+};
+
+// 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'
+        },
+        predicate: {
+            type: 'function',
+            required: true,
+            arity: 1,
+            error: 'Predicate must be a function with exactly one parameters (msg)'
+        },
+        minVotes: {
+            type: 'number',
+            required: false,
+            default: 3,
+            integer: true,
+            min: 1,
+            validator: validators.positiveInteger,
+            error: 'minVotes must be a positive integer'
+        },
+        outOfTotal: {
+            type: 'number',
+            required: false,
+            default: 5,
+            integer: true,
+            min: 1,
+            validator: validators.positiveInteger,
+            error: 'outOfTotal must be a positive integer'
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            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'
+                    }
+                }
+            }
+        },
+        triggers: {
+            type: 'array',
+            required: false,
+            itemSchema: {
+                type: 'object',
+                validator: composerValidators.trigger,
+                error: 'Invalid trigger specification'
+            }
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [
+        {
+            fields: [ 'minVotes', 'outOfTotal' ],
+            validator: (spec) => {
+                const minVotes = spec.minVotes || 3;
+                const outOfTotal = spec.outOfTotal || 5;
+                return outOfTotal >= minVotes;
+            },
+            error: 'outOfTotal must be greater than or equal to minVotes'
+        },
+        composerValidators.noSelfTriggers
+    ],
+
+    // How to build the spec from DSL params
+    buildSpec: ( name, predicate, stats, options ) => ( {
+            nodeType: NODE_TYPE,
+            name,
+            predicate,
+            stats,
+            ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/persistence-check/publish-to.js

@@ -0,0 +1,11 @@
+// nodes/persistence-check/publish-to.js
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    msg[ state.stats.persistenceConfirmed.storeAs ] = state.persistenceConfirmed;
+    // Reset immediately after publishing it.
+    state.persistenceConfirmed = false;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/persistence-check/recompute.js

@@ -0,0 +1,7 @@
+// nodes/persistence-check/recompute.js
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/persistence-check/reset.js

@@ -0,0 +1,12 @@
+// nodes/persistence-check/reset.js
+
+const reset = function ( state ) {
+    state.voteCount = 0;
+    state.unvoteCount = 0;
+    state.persistenceConfirmed = false;
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+    return state;
+}; // reset()
+
+export default reset;

package/src/nodes/persistence-check/update.js

@@ -0,0 +1,57 @@
+// nodes/persistence-check/update.js
+
+import { executeTriggers } from '../../core/utils/node/index.js';
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    let predicateResult;
+    try {
+        predicateResult = state.predicate( msg );
+        // Recovery: clear log-suppression flag on success
+        if ( state.predicateErrorLogged ) state.predicateErrorLogged = false;
+    } catch ( error ) {
+        // Assume it to be a case of predicate evaluating to false
+        predicateResult = false;
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.predicateErrorLogged ) {
+            state.predicateErrorLogged = true;
+            console.error( `WinkComposer/persistenceCheck: predicate threw exception: ${error.message}` );
+        }
+    }
+
+    // Update vote counts
+    if ( predicateResult ) {
+        state.voteCount += 1;
+    } else {
+        state.unvoteCount += 1;
+    }
+
+    // Check for success
+    if ( state.voteCount >= state.minVotes ) {
+        state.voteCount = 0;
+        state.unvoteCount = 0;
+        state.persistenceConfirmed = true;
+
+        // Trigger controls
+        executeTriggers( state );
+
+        return state;  // Early return on success
+    }
+
+    // Check for window completion or mathematical impossibility
+    const totalProcessed = state.voteCount + state.unvoteCount;
+    const remaining = state.outOfTotal - totalProcessed;
+
+    if ( totalProcessed >= state.outOfTotal || // Window completition check
+         ( state.voteCount + remaining ) < state.minVotes ) { // Mathematical impossibility check
+        // Window complete or success impossible - reset
+        state.voteCount = 0;
+        state.unvoteCount = 0;
+        state.persistenceConfirmed = false;
+    }
+
+    return state;
+}; // update()
+
+export default update;

package/src/nodes/process-index/index.js

@@ -0,0 +1,15 @@
+// nodes/process-index/index.js
+
+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/process-index/init.js

@@ -0,0 +1,48 @@
+// nodes/process-index/init.js
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.js';
+import { DEFAULT_OPTIONS } from './introspect.js';
+
+const init = function ( spec ) {
+    validateSpec( spec, introspect );
+
+    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;
+
+    // Input fields
+    state.x = spec.from.x;  // mean field
+    state.y = spec.from.y;  // stddev field
+
+    // Spec limits (at least one required, validated by specSchema)
+    state.hasUpperSpecLimit = spec.upperSpecLimit !== undefined;
+    state.hasLowerSpecLimit = spec.lowerSpecLimit !== undefined;
+    state.upperSpecLimit = state.hasUpperSpecLimit ? spec.upperSpecLimit : NaN;
+    state.lowerSpecLimit = state.hasLowerSpecLimit ? spec.lowerSpecLimit : NaN;
+
+    // Options
+    state.epsilon = spec.epsilon ?? DEFAULT_OPTIONS.epsilon;
+    state.maxIndex = spec.maxIndex ?? DEFAULT_OPTIONS.maxIndex;
+    state.capableThreshold = spec.capableThreshold ?? DEFAULT_OPTIONS.capableThreshold;
+    state.marginalThreshold = spec.marginalThreshold ?? DEFAULT_OPTIONS.marginalThreshold;
+
+    // Config copy
+    state.stats = spec.stats;
+
+    // Output values
+    state.index = NaN;
+    state.upper = NaN;
+    state.lower = NaN;
+    state.status = 'incapable';
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;
+

package/src/nodes/process-index/introspect.js

@@ -0,0 +1,182 @@
+// nodes/process-index/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for processIndex node.
+ *
+ * Computes process capability/performance index from mean and standard deviation
+ * with specification limits. Uses neutral terminology since interpretation as
+ * Cpk vs Ppk depends on upstream window configuration.
+ *
+ * Formulas:
+ * - upper = (upperSpecLimit - mean) / (3 * stddev)
+ * - lower = (mean - lowerSpecLimit) / (3 * stddev)
+ * - index = min(upper, lower) for two-sided, or the applicable one for one-sided
+ *
+ * DSL: .processIndex( 'tempPI', 'tempMean', 'tempStddev', { index: {...} }, { upperSpecLimit, lowerSpecLimit } )
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+    'index',
+    'upper',
+    'lower',
+    'status'
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+    index: 'Process index: min(upper, lower) for two-sided specs',
+    upper: 'Upper process index: (upperSpecLimit - mean) / (3 * stddev)',
+    lower: 'Lower process index: (mean - lowerSpecLimit) / (3 * stddev)',
+    status: 'Classification: capable, marginal, or incapable'
+};
+
+/** 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 = 'Process Index';
+
+/** Node capabilities for documentation */
+const CAPABILITIES = {
+    description: 'Computes process capability/performance index from mean and stddev',
+    features: [
+        'Two-sided specs: index = min(upper, lower)',
+        'One-sided specs: upperSpecLimit only or lowerSpecLimit only supported',
+        'Status classification: capable (>=1.33), marginal (1.0-1.33), incapable (<1.0)',
+        'Configurable thresholds for status classification',
+        'Caps index at maxIndex (default 12) for near-zero stddev'
+    ]
+};
+
+// 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 = {
+    epsilon: 1e-12,
+    maxIndex: 12,
+    capableThreshold: 1.33,
+    marginalThreshold: 1.0
+};
+
+// 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: 'Mean field name cannot contain spaces'
+                },
+                y: {
+                    type: 'string',
+                    required: true,
+                    validator: validators.noSpaces,
+                    error: 'Stddev field name cannot contain spaces'
+                }
+            }
+        },
+        upperSpecLimit: {
+            type: 'number',
+            required: false
+        },
+        lowerSpecLimit: {
+            type: 'number',
+            required: false
+        },
+        epsilon: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.epsilon
+        },
+        maxIndex: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.maxIndex
+        },
+        capableThreshold: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.capableThreshold
+        },
+        marginalThreshold: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.marginalThreshold
+        },
+        stats: {
+            type: 'object',
+            required: true,
+            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: [ 'upperSpecLimit', 'lowerSpecLimit' ],
+            validator: ( spec ) => spec.upperSpecLimit !== undefined || spec.lowerSpecLimit !== undefined,
+            error: 'At least one of upperSpecLimit or lowerSpecLimit must be provided'
+        },
+        {
+            fields: [ 'from.x', 'from.y' ],
+            validator: ( spec ) => spec.from.x !== spec.from.y,
+            error: 'from.x (mean) and from.y (stddev) must be different fields'
+        }
+    ],
+
+    // How to build the spec from DSL params
+    // DSL: .processIndex( 'tempPI', 'tempMean', 'tempStddev', { index: {...} }, { upperSpecLimit, lowerSpecLimit } )
+    buildSpec: ( name, x, y, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x, y },
+        stats,
+        ...options
+    } ),
+
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );
+

package/src/nodes/process-index/publish-to.js

@@ -0,0 +1,29 @@
+// nodes/process-index/publish-to.js
+
+/**
+ * @fileoverview Publish function for processIndex node.
+ *
+ * Publishes computed index values and status to the message.
+ * On inputValidationFailed, publishes NaN for numeric stats and 'incapable' for status.
+ */
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    if ( state.inputValidationFailed ) {
+        // Publish NaN for numeric stats, 'incapable' for status
+        if ( state.stats.index ) msg[ state.stats.index.storeAs ] = NaN;
+        if ( state.stats.upper ) msg[ state.stats.upper.storeAs ] = NaN;
+        if ( state.stats.lower ) msg[ state.stats.lower.storeAs ] = NaN;
+        if ( state.stats.status ) msg[ state.stats.status.storeAs ] = 'incapable';
+        return;
+    }
+
+    if ( state.stats.index ) msg[ state.stats.index.storeAs ] = state.index;
+    if ( state.stats.upper ) msg[ state.stats.upper.storeAs ] = state.upper;
+    if ( state.stats.lower ) msg[ state.stats.lower.storeAs ] = state.lower;
+    if ( state.stats.status ) msg[ state.stats.status.storeAs ] = state.status;
+}; // publishTo()
+
+export default publishTo;
+

package/src/nodes/process-index/recompute.js

@@ -0,0 +1,8 @@
+// nodes/process-index/recompute.js
+
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;
+

package/src/nodes/process-index/reset.js

@@ -0,0 +1,8 @@
+// nodes/process-index/reset.js
+
+const reset = function () {
+    return true;
+}; // reset()
+
+export default reset;
+

package/src/nodes/process-index/update.js

@@ -0,0 +1,75 @@
+// nodes/process-index/update.js
+
+/**
+ * @fileoverview Update function for processIndex node.
+ *
+ * Computes process capability/performance index from mean and stddev.
+ * Supports two-sided specs (upperSpecLimit + lowerSpecLimit) and one-sided specs.
+ */
+
+/**
+ * Clamp a value to [-maxIdx, maxIdx] range.
+ * @param {number} value - Raw index value
+ * @param {number} maxIdx - Maximum absolute value
+ * @returns {number} Clamped value
+ */
+const clampIndex = function ( value, maxIdx ) {
+    return Math.max( Math.min( value, maxIdx ), -maxIdx );
+}; // clampIndex()
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    state.inputValidationFailed = false;
+
+    const mean = msg[ state.x ];
+    const stddev = msg[ state.y ];
+
+    // Validate inputs: mean must be finite, stddev must be finite and positive
+    if ( !Number.isFinite( mean ) || !Number.isFinite( stddev ) || stddev <= 0 ) {
+        state.inputValidationFailed = true;
+        return state;
+    }
+
+    const maxIdx = state.maxIndex;
+    const denominator = 3 * stddev;
+
+    // Compute upper index (if upperSpecLimit provided)
+    if ( state.hasUpperSpecLimit ) {
+        const rawUpper = ( state.upperSpecLimit - mean ) / denominator;
+        state.upper = clampIndex( rawUpper, maxIdx );
+    } else {
+        state.upper = NaN;
+    }
+
+    // Compute lower index (if lowerSpecLimit provided)
+    if ( state.hasLowerSpecLimit ) {
+        const rawLower = ( mean - state.lowerSpecLimit ) / denominator;
+        state.lower = clampIndex( rawLower, maxIdx );
+    } else {
+        state.lower = NaN;
+    }
+
+    // Combined index: explicit handling to avoid Math.min(NaN, value) = NaN
+    if ( state.hasUpperSpecLimit && state.hasLowerSpecLimit ) {
+        state.index = Math.min( state.upper, state.lower );
+    } else if ( state.hasUpperSpecLimit ) {
+        state.index = state.upper;
+    } else {
+        state.index = state.lower;
+    }
+
+    // Status classification based on combined index
+    if ( state.index >= state.capableThreshold ) {
+        state.status = 'capable';
+    } else if ( state.index >= state.marginalThreshold ) {
+        state.status = 'marginal';
+    } else {
+        state.status = 'incapable';
+    }
+
+    return state;
+}; // update()
+
+export default update;
+

package/src/nodes/ratio/index.js

@@ -0,0 +1,14 @@
+// nodes/ratio/index.js
+
+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/ratio/init.js

@@ -0,0 +1,37 @@
+// nodes/ratio/init.js
+
+import { validateSpec } from '../../core/utils/node/index.js';
+import * as introspect from './introspect.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 names - x is numerator, y is denominator.
+    state.x = spec.from.x;
+    state.y = spec.from.y;
+
+    // Config copy.
+    state.stats = spec.stats;
+
+    // Apply defaults from introspect (validation doesn't enforce them)
+    state.logScale = spec.logScale ?? introspect.DEFAULT_OPTIONS.logScale;
+    state.minY = spec.minY ?? introspect.DEFAULT_OPTIONS.minY;
+    state.scaleBy = spec.scaleBy ?? introspect.DEFAULT_OPTIONS.scaleBy;
+
+    // State variables.
+    state.ratio = 0;
+
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;