@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/swing-watch/init.js

@@ -0,0 +1,144 @@
+// @fileoverview
+// init.js — pre-allocates all state for the swingWatch node.
+//
+// Every typed array, ring buffer, and accumulator is allocated here and never
+// again during the hot path (update / publishTo). Total memory per instance
+// at W=100 is ~7.9 KB — fits comfortably in L1 cache.
+
+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';
+import { asTunable } from '../../core/tunable/index.js';
+
+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 = Object.assign( Object.create( null ), spec.stats );
+    state.direction = spec.direction ?? introspect.DEFAULT_OPTIONS.direction;
+    state.minAbsoluteThreshold = spec.minAbsoluteThreshold ?? introspect.DEFAULT_OPTIONS.minAbsoluteThreshold;
+
+    // ── Window size (field-keyed support) ─────────────────────
+    const windowSizeSpec = resolveScalar( spec.windowSize, state.x );
+    const W = windowSizeSpec ?? introspect.DEFAULT_OPTIONS.windowSize;
+    state.windowSize = W;
+
+    // ── Ring buffer (reuse composer's count-sliding module) ──
+    state.ring = create( W );
+
+    // ── Threshold tunable ────────────────────────────────────
+    state.thresholdFn = asTunable( spec.threshold );
+    state.currentThreshold = 0;
+    state.tunableErrorLogged = false;
+
+    // ── Pre-allocated typed arrays (zero allocation in hot path) ─
+
+    // Linearized copy of ring buffer (contiguous for sort)
+    state.linear = new Float64Array( W );
+
+    // Sort workspace: indices [0..W-1] sorted by linear[i]
+    state.sortedIndices = new Int32Array( W );
+
+    // Pre-built comparator — avoids per-tick closure allocation at the
+    // .sort() call site. Captures state.linear by reference; its contents
+    // are overwritten in place each tick but the binding is stable.
+    state.compareIndices = ( a, b ) => {
+        const d = state.linear[ a ] - state.linear[ b ];
+        if ( d !== 0 ) return d;
+        return a - b;
+    };
+
+    // Union-find arrays (reused for both min and max sweeps)
+    state.ufParent   = new Int32Array( W );
+    state.ufBirthVal = new Float64Array( W );
+    state.ufBirthIdx = new Int32Array( W );
+
+    // Processed flags for sweep (cleared between min/max sweeps)
+    state.processed = new Uint8Array( W );
+
+    // Accounted-emission flags, one byte per ring slot per direction
+    // (exactly-once rule c in update.js Section 3). A set byte means the
+    // sample in that slot has already driven — or been recognized as a
+    // duplicate of — a completion emission. Cleared per-slot on overwrite.
+    state.minEmitFlag = new Uint8Array( W );
+    state.maxEmitFlag = new Uint8Array( W );
+
+    // Pair storage — parallel typed arrays, max pairs = floor(W/2)
+    const maxPairs = Math.floor( W / 2 );
+    state.maxPairs = maxPairs;
+
+    // Current tick's min pairs
+    state.minBirthValArr = new Float64Array( maxPairs );
+    state.minBirthIdxArr = new Int32Array( maxPairs );
+    state.minDeathValArr = new Float64Array( maxPairs );
+    state.minDeathIdxArr = new Int32Array( maxPairs );
+    state.minPersArr     = new Float64Array( maxPairs );
+    state.minPairCount   = 0;
+
+    // Current tick's max pairs
+    state.maxBirthValArr = new Float64Array( maxPairs );
+    state.maxBirthIdxArr = new Int32Array( maxPairs );
+    state.maxDeathValArr = new Float64Array( maxPairs );
+    state.maxDeathIdxArr = new Int32Array( maxPairs );
+    state.maxPersArr     = new Float64Array( maxPairs );
+    state.maxPairCount   = 0;
+
+    // Previous tick's pairs (for diffing — only need indices to compare)
+    state.prevMinBirthIdx = new Int32Array( maxPairs );
+    state.prevMinDeathIdx = new Int32Array( maxPairs );
+    state.prevMinPairCount = 0;
+
+    state.prevMaxBirthIdx = new Int32Array( maxPairs );
+    state.prevMaxDeathIdx = new Int32Array( maxPairs );
+    state.prevMaxPairCount = 0;
+
+    // ── Completion event slots (Mode A) ──────────────────────
+    state.dipCompleted  = false;
+    state.dipValue      = NaN;
+    state.dipLag        = 0;
+    state.dipSize       = NaN;
+
+    state.peakCompleted = false;
+    state.peakValue     = NaN;
+    state.peakLag       = 0;
+    state.peakSize      = NaN;
+
+    // ── Pre-built field-key maps (zero string-concat in diff hot path) ──
+    // diffOneSide writes to state[ keys.completed ] etc. using these
+    // pre-built strings instead of runtime concatenation. The min/max keys
+    // name the sweep side (signal minima/maxima); the values are the
+    // published dip/peak stat fields those sides feed.
+    state.fieldKeys = Object.create( null );
+    state.fieldKeys.min = Object.create( null );
+    state.fieldKeys.min.completed   = 'dipCompleted';
+    state.fieldKeys.min.birthValue  = 'dipValue';
+    state.fieldKeys.min.birthLag    = 'dipLag';
+    state.fieldKeys.min.persistence = 'dipSize';
+    state.fieldKeys.max = Object.create( null );
+    state.fieldKeys.max.completed   = 'peakCompleted';
+    state.fieldKeys.max.birthValue  = 'peakValue';
+    state.fieldKeys.max.birthLag    = 'peakLag';
+    state.fieldKeys.max.persistence = 'peakSize';
+
+    // ── Diagnostic counters ──────────────────────────────────
+    state.received       = 0;
+    state.emitted        = 0;
+    state.swingsThisTick = 0;
+    state.swingRate      = 0;
+
+    // ── Metadata ─────────────────────────────────────────────
+    state.nodeType = introspect.getNodeType();
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/swing-watch/introspect.js

@@ -0,0 +1,188 @@
+// @fileoverview
+// Introspection metadata for the swingWatch node.
+//
+// swingWatch watches a signal for swings — dips and peaks — over a sliding
+// window and reports the size of each swing when it completes. A swing's
+// size is its topological persistence: how far the value travels between a
+// turning point and the level that closes the round trip. On each tick the
+// node runs a batch persistence sweep (sort by value + union-find, the
+// Huber/Persistence1D algorithm) on the current window and emits completion
+// events for pairs that are new compared to the previous tick.
+//
+// Convention: topological persistence — the global extremum in the window is
+// unpaired (infinite persistence). This matches Persistence1D, not scipy's
+// peak-prominence convention.
+//
+// References:
+//   Edelsbrunner, Letscher & Zomorodian (2002). Topological Persistence and
+//     Simplification. Discrete & Computational Geometry, 28, 511–533.
+//   Huber, S. Persistent Topology for Peak Detection.
+//     https://www.sthu.org/blog/13-perstopology-peakdetection/index.html
+
+import { validators } from '../../core/utils/validate/index.js';
+
+// ── Supported Features ───────────────────────────────────────
+const SUPPORTED_STATS = [
+    'dipCompleted',
+    'dipValue',
+    'dipLag',
+    'dipSize',
+    'peakCompleted',
+    'peakValue',
+    'peakLag',
+    'peakSize',
+    'swingsThisTick',
+    'swingRate'
+];
+
+const STAT_DESCRIPTIONS = {
+    dipCompleted: 'True on the tick a significant dip completes (false otherwise)',
+    dipValue: 'Signal value at the bottom of the completed dip (undefined when not completing)',
+    dipLag: 'Samples back to the bottom of the completed dip within the window (undefined when not completing)',
+    dipSize: 'Size (depth) of the completed dip: deathVal - birthVal (undefined when not completing)',
+    peakCompleted: 'True on the tick a significant peak completes',
+    peakValue: 'Signal value at the top of the completed peak (undefined when not completing)',
+    peakLag: 'Samples back to the top of the completed peak within the window (undefined when not completing)',
+    peakSize: 'Size (height) of the completed peak: birthVal - deathVal (undefined when not completing)',
+    swingsThisTick: 'Number of swings newly accounted this tick; when several finish at once the dip/peak stats detail the largest',
+    swingRate: 'Cumulative swings per received sample (emitted / received); can exceed 1.0 with direction "both" when one tick completes both a dip and a peak'
+};
+
+const SUPPORTED_CONTROL_METHODS = {
+    reset: 'Clears ring buffer and all completion history',
+    enable: 'Enables node processing',
+    disable: 'Disables node processing',
+    pause: 'Pauses update but keeps publishTo outputs visible',
+    unpause: 'Resumes update after pause'
+};
+
+const NODE_TYPE = 'Swing Watch';
+
+const CAPABILITIES = {
+    description: 'Watches a signal for swings — dips and peaks — over a sliding window and reports the size of each completed swing',
+    features: [
+        'Windowed batch persistence sweep (sort + union-find) per tick',
+        'Topological convention — consistent with Persistence1D and Huber',
+        'Adaptive threshold via tunable pattern (k × σ from upstream stats)',
+        'Configurable minimum absolute threshold floor for quiet signals',
+        'Bidirectional detection (dips, peaks, or both)',
+        'Output scrubbing on non-completion ticks (undefined) per momentsDigest convention',
+        'Zero allocation in hot path — all typed arrays pre-allocated in init',
+        'Exactly-once completion events — flag-based emission suppressing window-boundary artifacts (left-edge eviction re-fires, right-edge provisional extrema)'
+    ]
+};
+
+// ── Default Options ──────────────────────────────────────────
+export const DEFAULT_OPTIONS = {
+    windowSize: 100,
+    direction: 'both',
+    minAbsoluteThreshold: 0
+};
+
+/** Parameters that support tunable (dynamic) values. */
+export const TUNABLE_PARAMS = [ 'threshold' ];
+
+// ── 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()
+} );
+
+// ── 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: 'Field name cannot contain spaces'
+                }
+            }
+        },
+        threshold: {
+            type: 'numberOrFunctionOrFieldKeyed',
+            required: true,
+            min: 0,
+            error: 'threshold must be a non-negative number, function, or per-field map'
+        },
+        // Upper bound chosen so the two copy loops and the per-tick sort stay
+        // in L1 cache. Algorithm is correct for larger W but performance has
+        // not been validated beyond 256. integer+min+max are applied per
+        // numeric value — including inside a field-keyed object — by the
+        // numberOrFieldKeyed type validator. A custom `validator` would run on
+        // the outer value (the object itself), which would reject any
+        // field-keyed spec.
+        windowSize: {
+            type: 'numberOrFieldKeyed',
+            required: false,
+            default: DEFAULT_OPTIONS.windowSize,
+            integer: true,
+            min: 4,
+            max: 256
+        },
+        direction: {
+            type: 'string',
+            required: false,
+            default: DEFAULT_OPTIONS.direction,
+            validator: validators.oneOf( [ 'both', 'dips', 'peaks' ] ),
+            error: 'direction must be "both", "dips", or "peaks"'
+        },
+        minAbsoluteThreshold: {
+            type: 'number',
+            required: false,
+            default: DEFAULT_OPTIONS.minAbsoluteThreshold,
+            min: 0,
+            error: 'minAbsoluteThreshold must be a non-negative number'
+        },
+        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'
+                    }
+                }
+            }
+        }
+    },
+
+    crossFieldValidators: [],
+
+    buildSpec: ( name, x, stats, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        from: { x },
+        stats,
+        ...( options || {} )
+    } )
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/swing-watch/publish-to.js

@@ -0,0 +1,53 @@
+// @fileoverview
+// publish-to.js — copy computed completion fields to the output message.
+//
+// Follows the momentsDigest output-scrubbing convention: on non-completion
+// ticks, detail fields (birthValue, birthLag, persistence) are explicitly
+// set to `undefined` — not left as stale values from a previous tick. This
+// prevents downstream nodes from acting on outdated event data.
+//
+// The completion booleans (dipCompleted, peakCompleted) are always published
+// so downstream can branch on them. Diagnostic fields (swingsThisTick,
+// swingRate) are always published when the window is full.
+//
+// Guard order (per ADR-004):
+//   1. disable → skip entirely (node invisible downstream)
+//   2. inputValidationFailed → publishNaN for all stats (fault isolation)
+//   3. isNotFull → skip (warmup, no meaningful output yet)
+
+import { isNotFull } from '../../windowing/count-sliding/index.js';
+import { publishNaN } from '../../core/utils/node/index.js';
+
+const publishTo = function ( state, msg ) {
+    if ( state.disable ) return;
+
+    if ( state.inputValidationFailed ) {
+        publishNaN( state, msg );
+        return;
+    }
+
+    // Do not publish during warmup (window not yet full)
+    if ( isNotFull( state.ring ) ) return;
+
+    const s = state.stats;
+
+    // ── Completion booleans (always published) ────────────────
+    if ( s.dipCompleted )  msg[ s.dipCompleted.storeAs ]  = state.dipCompleted;
+    if ( s.peakCompleted ) msg[ s.peakCompleted.storeAs ] = state.peakCompleted;
+
+    // ── Dip detail fields (scrubbed to undefined on non-completion ticks) ─
+    if ( s.dipValue ) msg[ s.dipValue.storeAs ] = state.dipCompleted ? state.dipValue : undefined;
+    if ( s.dipLag )   msg[ s.dipLag.storeAs ]   = state.dipCompleted ? state.dipLag   : undefined;
+    if ( s.dipSize )  msg[ s.dipSize.storeAs ]  = state.dipCompleted ? state.dipSize  : undefined;
+
+    // ── Peak detail fields (scrubbed to undefined on non-completion ticks) ─
+    if ( s.peakValue ) msg[ s.peakValue.storeAs ] = state.peakCompleted ? state.peakValue : undefined;
+    if ( s.peakLag )   msg[ s.peakLag.storeAs ]   = state.peakCompleted ? state.peakLag   : undefined;
+    if ( s.peakSize )  msg[ s.peakSize.storeAs ]  = state.peakCompleted ? state.peakSize  : undefined;
+
+    // ── Diagnostics (always published when window is full) ───
+    if ( s.swingsThisTick ) msg[ s.swingsThisTick.storeAs ] = state.swingsThisTick;
+    if ( s.swingRate )      msg[ s.swingRate.storeAs ]      = state.swingRate;
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/swing-watch/recompute.js

@@ -0,0 +1,22 @@
+// @fileoverview
+// recompute.js — re-establish numerical ground truth per ADR-004.
+//
+// Unlike incremental-accumulator nodes (esMean, swStats) where floating-point
+// drift can compound over millions of updates, swingWatch recomputes the
+// entire persistence diagram from scratch on every tick (the windowed batch
+// sweep sorts and sweeps the full window). There is no accumulated state that
+// can drift.
+//
+// The only action needed is to clear the previous-tick pair storage, which
+// forces the next tick's diff to re-derive every current pair as unmatched.
+// The accounted-emission flags (exactly-once rule c in update.js) survive
+// recompute deliberately: every re-derived pair's birth vertex is still
+// flagged as accounted, so recompute causes no spurious re-emission burst.
+
+const recompute = function ( state ) {
+    state.prevMinPairCount = 0;
+    state.prevMaxPairCount = 0;
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/swing-watch/reset.js

@@ -0,0 +1,55 @@
+// @fileoverview
+// reset.js — idempotent reset per ADR-004.
+//
+// Clears the ring buffer, all pair storage (current and previous tick),
+// completion event slots, and diagnostic counters. After reset, the node
+// re-enters the warmup phase (isNotFull returns true) and will not publish
+// until the window fills again.
+//
+// Multiple calls produce the same state as a single call (idempotent).
+
+import { reset as resetRing } from '../../windowing/count-sliding/index.js';
+
+const reset = function ( state ) {
+    // Clear the ring buffer — head, used, and buffer contents all zeroed
+    resetRing( state.ring );
+
+    // Clear current tick's pair counts (typed arrays contents are irrelevant
+    // when count is 0 — no need to zero the arrays themselves)
+    state.minPairCount = 0;
+    state.maxPairCount = 0;
+
+    // Clear previous tick's pair counts (forces fresh diff on next tick —
+    // all pairs in the first full-window tick will appear as "new")
+    state.prevMinPairCount = 0;
+    state.prevMaxPairCount = 0;
+
+    // Clear the accounted-emission flags (exactly-once rule c) — after a
+    // reset every vertex of the refilled window may emit afresh
+    state.minEmitFlag.fill( 0 );
+    state.maxEmitFlag.fill( 0 );
+
+    // Clear completion event slots
+    state.dipCompleted  = false;
+    state.peakCompleted = false;
+    state.dipValue      = NaN;
+    state.peakValue     = NaN;
+    state.dipLag        = 0;
+    state.peakLag       = 0;
+    state.dipSize       = NaN;
+    state.peakSize      = NaN;
+
+    // Clear diagnostics
+    state.received       = 0;
+    state.emitted        = 0;
+    state.swingsThisTick = 0;
+    state.swingRate      = 0;
+
+    // Clear health and tunable error flags
+    state.inputValidationFailed = false;
+    state.tunableErrorLogged    = false;
+
+    return true;
+}; // reset()
+
+export default reset;