@winkjs/composer 0.0.2 → 0.4.0

package/src/core/test-utils/sealed-record.js

@@ -0,0 +1,80 @@
+// core/test-utils/sealed-record.js
+
+/**
+ * @fileoverview Test harness that proves a sink consumes a record
+ * synchronously.
+ *
+ * ADR-023 obliges every sink to read everything it needs from an incoming
+ * message before its hot-path call returns, and never to keep the
+ * reference for a later read. With a reused record (the handbook's
+ * record-reuse pattern, and the future declarative shaping), a late read
+ * would see a LATER message's values — silently corrupted data. This
+ * harness makes that rule testable: wrap a record, hand it to the sink,
+ * seal it the moment the call returns, and any read arriving after the
+ * seal is recorded as a violation.
+ *
+ * Violations are RECORDED, never thrown. A late read typically happens
+ * inside the sink's own async callback; a throw there would surface as an
+ * unhandled rejection instead of a clean assertion failure. Tests seal,
+ * await a tick, then assert `violations` is empty.
+ *
+ * Symbol-keyed accesses are ignored on purpose: engines and inspection
+ * tools probe symbols (Symbol.toStringTag and friends), while record
+ * columns are always string-named. Counting symbol traffic would produce
+ * false violations that have nothing to do with data reads.
+ */
+
+/**
+ * Wraps a plain record in a Proxy that logs every read and, once sealed,
+ * records further reads as violations.
+ *
+ * @param {Object} fields - Column values the record carries.
+ * @returns {{record: Object, seal: Function, violations: Array, reads: Array}}
+ *   `record` behaves exactly like `fields`; `seal()` marks the moment the
+ *   sink's call returned (idempotent); `reads` holds `{trap, key}` entries
+ *   logged before the seal, `violations` the ones logged after it.
+ */
+const makeSealedRecord = function ( fields ) {
+    const reads = [];
+    const violations = [];
+    let sealed = false;
+
+    const log = function ( trap, key ) {
+        if ( typeof key === 'symbol' ) {
+            return;
+        }
+        const entry = { trap, key };
+        if ( sealed ) {
+            violations.push( entry );
+        } else {
+            reads.push( entry );
+        }
+    }; // log()
+
+    const record = new Proxy( fields, {
+        get: function ( target, key, receiver ) {
+            log( 'get', key );
+            return Reflect.get( target, key, receiver );
+        },
+        has: function ( target, key ) {
+            log( 'has', key );
+            return Reflect.has( target, key );
+        },
+        ownKeys: function ( target ) {
+            log( 'ownKeys', null );
+            return Reflect.ownKeys( target );
+        },
+        getOwnPropertyDescriptor: function ( target, key ) {
+            log( 'getOwnPropertyDescriptor', key );
+            return Reflect.getOwnPropertyDescriptor( target, key );
+        }
+    } );
+
+    const seal = function () {
+        sealed = true;
+    }; // seal()
+
+    return { record, seal, violations, reads };
+}; // makeSealedRecord()
+
+export { makeSealedRecord };

package/src/core/test-utils/soak-signature.js

@@ -0,0 +1,149 @@
+// core/test-utils/soak-signature.js
+
+/**
+ * @fileoverview Release-soak signature policy for the MQTT emitter.
+ *
+ * The release gate runs the emitter soak (`slow-soak-mqtt-emitter.specs.js`)
+ * and has to judge a lossy run. One loss mechanism is documented and
+ * reported upstream: mqtt.js's reconnect-clear race — on every mid-run
+ * reconnect, `_onConnect` wipes the message-id registrations
+ * (client.js:1171) before the store re-drive re-registers them
+ * asynchronously (client.js:1223); a publish landing in that window
+ * overwrites an unacked store entry. The result, measured at
+ * ~12–14k msg/s: 1–6 messages lost per reconnect, the store counter
+ * left one high per loss (drift), and NO error callback anywhere —
+ * so shutdown times out on a phantom count over an empty store.
+ *
+ * The policy as first ratified (2026-07-07) tolerated a lossy run
+ * that carried exactly that signature —
+ *
+ *   1. at least one mid-run reconnect (the mechanism needs one),
+ *   2. loss small and bounded by the reconnect count,
+ *   3. zero delivery-failure callbacks (the race produces none), and
+ *   4. a shutdown throw, when present, classified `SHUTDOWN_TIMEOUT`
+ *      with an exact `dropped.count` — never `DELIVERY_FAILED`.
+ *
+ * **The tolerance was retired by operator ruling on 2026-07-10.**
+ * ADR-021 moved the emitter onto mqtt.js's synchronous memory store,
+ * which is immune to the erase-then-rebuild race — so the signature's
+ * mechanism no longer exists in this build, and a verdict that can
+ * excuse a loss is a hole, not a tolerance. Every lossy run now fails.
+ * The signature detection is kept as DIAGNOSTICS: when a loss matches
+ * the retired signature, the failure reason says so, because "this
+ * looks like the foreclosed upstream race" is the first lead an
+ * investigator needs.
+ *
+ * This is test infrastructure (lives beside `tcp-proxy.js`), but the
+ * policy itself is tested — see `test/soak-signature.specs.js`.
+ */
+
+/**
+ * Per-reconnect loss allowance. Measured losses were 1–6 per reconnect
+ * at ~12–14k msg/s; 10 gives headroom without letting an unrelated
+ * loss mechanism hide behind a single reconnect.
+ *
+ * @type {number}
+ */
+const LOSS_ALLOWANCE_PER_RECONNECT = 10;
+
+/**
+ * Loss floor that counts as clean regardless of reconnects: one packet
+ * per 100,000 accepted (min 1) may be on the wire at the instant the
+ * test process dies. Predates the signature policy (the soak's
+ * original coverage assertion).
+ *
+ * @param {number} accepted - messages accepted by publishNow
+ * @returns {number} allowed gap count for a clean verdict
+ */
+const wireRaceFloor = function ( accepted ) {
+    return Math.max( 1, Math.floor( accepted / 100_000 ) );
+};
+
+/**
+ * Judges a completed soak run against the release-gate policy.
+ *
+ * @param {Object} outcome - What the soak observed
+ * @param {Error|null} outcome.shutdownError - throw from emitter.shutdown(),
+ *   or null when shutdown resolved cleanly
+ * @param {Array} outcome.deliveryFailures - every onDeliveryFailure call
+ * @param {number} outcome.coverageGaps - accepted IDs never received
+ * @param {number} outcome.accepted - messages accepted by publishNow
+ * @param {number} outcome.reconnects - emitter getHealth().stats.reconnects
+ * @returns {{verdict: 'clean'|'regression', reason: string}}
+ */
+const evaluateSoakOutcome = function ( outcome ) {
+    const {
+        shutdownError,
+        deliveryFailures,
+        coverageGaps,
+        accepted,
+        reconnects
+    } = outcome;
+
+    // Any delivery-failure callback is off-signature: the reconnect-clear
+    // race never produces one. Judged first — it blocks even a run that
+    // would otherwise look clean.
+    if ( deliveryFailures.length > 0 ) {
+        return {
+            verdict: 'regression',
+            reason: `${deliveryFailures.length} delivery failure(s) — first: ` +
+                `[${deliveryFailures[ 0 ].code}] ${deliveryFailures[ 0 ].message}`
+        };
+    }
+
+    // Clean: shutdown resolved and gaps are within the wire-race floor.
+    if ( !shutdownError && coverageGaps <= wireRaceFloor( accepted ) ) {
+        return {
+            verdict: 'clean',
+            reason: `no shutdown throw, no delivery failures, gaps ${coverageGaps} ` +
+                `within the wire-race floor (${wireRaceFloor( accepted )})`
+        };
+    }
+
+    // From here the run is lossy and WILL fail. The checks below exist
+    // for the diagnosis in the reason: they tell an off-signature loss
+    // (name the first mismatched fact) apart from one that matches the
+    // retired reconnect-clear signature (name the match — see header).
+    if ( shutdownError && shutdownError.code !== 'SHUTDOWN_TIMEOUT' ) {
+        return {
+            verdict: 'regression',
+            reason: `shutdown threw [${shutdownError.code}] — the race's only throw is ` +
+                'SHUTDOWN_TIMEOUT (a DELIVERY_FAILED means real flush failures)'
+        };
+    }
+    const droppedCount = shutdownError ? shutdownError.dropped?.count : 0;
+    if ( shutdownError && typeof droppedCount !== 'number' ) {
+        return {
+            verdict: 'regression',
+            reason: 'shutdown throw carries no dropped.count — cannot verify the drift signature'
+        };
+    }
+    if ( reconnects < 1 ) {
+        return {
+            verdict: 'regression',
+            reason: `loss with zero mid-run reconnects (gaps ${coverageGaps}, ` +
+                `dropped ${droppedCount || 0}) — the reconnect-clear race needs a reconnect; ` +
+                'this is a different mechanism'
+        };
+    }
+    const totalLoss = Math.max( coverageGaps, droppedCount || 0 );
+    const allowance = LOSS_ALLOWANCE_PER_RECONNECT * reconnects;
+    if ( totalLoss > allowance ) {
+        return {
+            verdict: 'regression',
+            reason: `loss ${totalLoss} exceeds the per-reconnect allowance ` +
+                `(${allowance} for ${reconnects} reconnect(s)) — too large for the race alone`
+        };
+    }
+
+    return {
+        verdict: 'regression',
+        reason: `matches the RETIRED mqtt.js reconnect-clear race signature: ${totalLoss} lost ` +
+            `across ${reconnects} reconnect(s), zero delivery failures` +
+            ( shutdownError ? `, SHUTDOWN_TIMEOUT with dropped.count ${droppedCount}` : '' ) +
+            ' — tolerance retired 2026-07-10 (ADR-021\'s synchronous store forecloses the ' +
+            'mechanism), so this match needs investigation, not acceptance'
+    };
+};
+
+export { evaluateSoakOutcome, LOSS_ALLOWANCE_PER_RECONNECT, wireRaceFloor };

package/src/core/test-utils/tcp-proxy.js

@@ -0,0 +1,106 @@
+// core/test-utils/tcp-proxy.js
+
+/* eslint-disable no-empty-function */
+
+/**
+ * @fileoverview Tiny TCP proxy for outage-recovery tests. Listens on
+ * a port, forwards each connection bidirectionally to a target port.
+ * Closing the proxy server tears down all live sockets so existing
+ * client sockets see the outage immediately; reopening on the same
+ * port restores connectivity.
+ *
+ * Used by the QuestDB recovery tests and the MQTT emitter
+ * recovery tests. Both adapters needed an in-test way to simulate
+ * "service unreachable" without coupling tests to docker daemon
+ * access. The pattern is identical for any TCP-based service.
+ *
+ * Cross-cutting test infrastructure mirrors `src/core/source-manager/test-harness/`
+ * — both live under `src/core/` because they're shared across adapter
+ * modules.
+ *
+ * Socket errors during proxy toggling are deliberately swallowed:
+ * the partner socket may close mid-pipe while the test toggles the
+ * proxy, and unhandled-error events would crash the test runner.
+ * The test asserts higher-level outcomes (delivery counts, health
+ * transitions, pipeline survival), not socket-level cleanliness.
+ *
+ * @module test-utils/tcp-proxy
+ */
+
+import net from 'node:net';
+
+/**
+ * Start a TCP proxy on `listenPort` that forwards to `targetPort` on
+ * 127.0.0.1. Returns the underlying `net.Server` once it's listening;
+ * pass it to `stopProxy()` to tear down.
+ *
+ * **Why we track client sockets ourselves:** `net.Server` doesn't
+ * expose `closeAllConnections()` (only `http.Server` does, since
+ * Node 18.2). Without tracking, `server.close()` waits for client
+ * sockets to close from their end, which never happens for clients
+ * holding persistent connections (mqtt.js with keepalive). We track
+ * incoming sockets in a Set and destroy them explicitly on
+ * `stopProxy()` — that sends RST to the client so it sees the
+ * disconnect immediately.
+ *
+ * @param {number} listenPort
+ * @param {number} targetPort
+ * @returns {Promise<net.Server>}
+ */
+export const startProxy = function ( listenPort, targetPort ) {
+    const sockets = new Set();
+    const server = net.createServer( function ( clientSocket ) {
+        sockets.add( clientSocket );
+        clientSocket.on( 'close', function () {
+            sockets.delete( clientSocket );
+        } );
+        const targetSocket = net.connect( targetPort, '127.0.0.1', function () {
+            clientSocket.pipe( targetSocket );
+            targetSocket.pipe( clientSocket );
+        } );
+        // See file-header note on swallowed errors.
+        clientSocket.on( 'error', function () {} );
+        targetSocket.on( 'error', function () {} );
+    } );
+    // Attach the tracked-socket Set to the server object so
+    // `stopProxy()` can find it. Underscore-prefixed since this is
+    // a test-utility internal, not a public API.
+    // eslint-disable-next-line no-underscore-dangle
+    server._sockets = sockets;
+    return new Promise( function ( resolve ) {
+        server.listen( listenPort, '127.0.0.1', function () {
+            resolve( server );
+        } );
+    } );
+};
+
+/**
+ * Stop a proxy started via `startProxy()`. Force-destroys every
+ * tracked client socket first (sending RST so clients see the
+ * disconnect immediately, not at next keepalive timeout), then
+ * waits for the server to close cleanly.
+ *
+ * Without this, persistent-connection clients (mqtt.js with
+ * keepalive) keep their TCP socket alive indefinitely after the
+ * proxy "closes". `server.close()` would never fire its callback,
+ * and the client would never fire its disconnect events — the
+ * connection appears intact even though the proxy is gone. The MQTT
+ * emitter recovery tests surfaced this; the fix is to destroy from
+ * our side.
+ *
+ * @param {net.Server} server
+ * @returns {Promise<void>}
+ */
+export const stopProxy = function ( server ) {
+    return new Promise( function ( resolve ) {
+        // eslint-disable-next-line no-underscore-dangle
+        const sockets = server._sockets || new Set();
+        for ( const sock of sockets ) {
+            sock.destroy();
+        }
+        sockets.clear();
+        server.close( function () {
+            resolve();
+        } );
+    } );
+};

package/src/core/tunable/helpers.js

@@ -0,0 +1,254 @@
+/**
+ * @fileoverview Helper functions for creating tunable parameters.
+ *
+ * These helpers provide common patterns for dynamic parameters with proper
+ * context capture for LLM/dashboard consumption. Each helper creates a
+ * function with custom toString() and .semantics for introspection.
+ *
+ * @example
+ * // WiFi RSSI thresholds by protocol
+ * .threshold('rssiAlert', 'rssi', { alert: 'rssi_low' }, {
+ *     threshold: lookupByField( 'protocolType', {
+ *         '802.11ac': -70,
+ *         '802.11n': -75
+ *     }, -75 )
+ * })
+ */
+
+/**
+ * Create a tunable parameter that looks up value by a message field.
+ *
+ * Useful for protocol-specific thresholds, asset-class configs, etc.
+ *
+ * @param {string} field - Message field to use as lookup key
+ * @param {Object} map - Lookup map from field values to parameter values
+ * @param {*} defaultVal - Default value if field value not in map
+ * @returns {Function} Tunable function with .semantics attached
+ *
+ * @example
+ * const threshold = lookupByField( 'protocolType', {
+ *     '802.11ac': -70,
+ *     '802.11n': -75
+ * }, -75 );
+ *
+ * threshold( { protocolType: '802.11ac' } );  // → -70
+ * threshold( { protocolType: '802.11g' } );   // → -75 (default)
+ */
+export const lookupByField = function ( field, map, defaultVal ) {
+    const fn = ( msg ) => map[ msg[ field ] ] ?? defaultVal;
+
+    fn.toString = () => `lookupByField("${field}", ${JSON.stringify( map )}, ${JSON.stringify( defaultVal )})`;
+    fn.semantics = {
+        type: 'lookupByField',
+        field,
+        map,
+        default: defaultVal
+    };
+
+    return fn;
+}; // lookupByField()
+
+/**
+ * Create a build-time resolver that picks an option value by the current fan field.
+ *
+ * `pickByField` is `lookupByField`'s build-time sibling, used INSIDE a `forEach`:
+ * it resolves to `map[ each.field ]` once, when the fan expands, and leaves no
+ * function behind at runtime. Use it for an option whose value differs per channel
+ * (a per-string clean range, a per-channel threshold). A field missing from `map`
+ * fails at build, not at the first message.
+ *
+ * It is resolved by the fan, never called per message, so its body throws if it is
+ * ever invoked (that would mean it was used outside a `forEach`). `.semantics`
+ * carries the map for the fan's resolver; `.toString` serializes it.
+ *
+ * @param {Object} map - Map from field name to that channel's option value
+ * @returns {Function} Resolver marked with .semantics for build-time resolution
+ *
+ * @example
+ * .forEach( [ 'scb1', 'scb2' ], ( each ) => each
+ *     .threshold( 'hi', each.field, { active: 'high' },
+ *                 { threshold: pickByField( { scb1: 0.8, scb2: 0.6 } ), mode: 'above' } ) )
+ */
+export const pickByField = function ( map ) {
+    const fn = () => {
+        throw new Error(
+            'WinkComposer/flow: pickByField is resolved at build time inside forEach; ' +
+            'it has no runtime value. Use it only for a forEach option.'
+        );
+    };
+
+    fn.toString = () => `pickByField(${JSON.stringify( map )})`;
+    fn.semantics = {
+        type: 'pickByField',
+        map
+    };
+
+    return fn;
+}; // pickByField()
+
+/**
+ * Create a tunable parameter that scales a message field value.
+ *
+ * Computes: (msg[field] * factor) + offset, optionally snapped to step.
+ * Useful for adaptive sensitivity (e.g., delta = stdev * 0.5).
+ *
+ * @param {string} field - Message field to read
+ * @param {number} factor - Multiplication factor
+ * @param {number} [offset=0] - Additive offset
+ * @param {number} [step=0] - If > 0, snap result to nearest multiple
+ * @returns {Function} Tunable function with .semantics attached
+ *
+ * @example
+ * // Adaptive sensitivity: delta tracks noise level
+ * const delta = scaleBy( 'fuel_stdev', 0.5 );
+ * delta( { fuel_stdev: 0.046 } );  // → 0.023
+ *
+ * @example
+ * // With step snapping
+ * const rounded = scaleBy( 'value', 1.5, 10, 5 );
+ * rounded( { value: 20 } );  // → 40 (30 + 10 = 40, already on step)
+ */
+export const scaleBy = function ( field, factor, offset = 0, step = 0 ) {
+    const fn = ( msg ) => {
+        const raw = ( msg[ field ] * factor ) + offset;
+        return step > 0 ? Math.round( raw / step ) * step : raw;
+    };
+
+    fn.toString = () => `scaleBy("${field}", ${factor}, ${offset}, ${step})`;
+    fn.semantics = {
+        type: 'scaleBy',
+        field,
+        factor,
+        offset,
+        step
+    };
+
+    return fn;
+}; // scaleBy()
+
+/**
+ * Create a conditional tunable parameter that returns different values based on predicate.
+ *
+ * Useful for mode-dependent behavior (warmup vs normal, idle vs active).
+ *
+ * @param {Function} predicate - Function (msg) => boolean
+ * @param {*} trueVal - Value or function when predicate is true
+ * @param {*} falseVal - Value or function when predicate is false
+ * @param {string} predicateDesc - Human-readable description of predicate
+ * @returns {Function} Tunable function with .semantics attached
+ *
+ * @example
+ * // Mode-dependent threshold
+ * const threshold = chooseWhen(
+ *     ( msg ) => msg.isWarmup,
+ *     100,     // warmup: high threshold
+ *     78,      // normal: standard threshold
+ *     'msg.isWarmup'
+ * );
+ *
+ * threshold( { isWarmup: true } );   // → 100
+ * threshold( { isWarmup: false } );  // → 78
+ */
+export const chooseWhen = function ( predicate, trueVal, falseVal, predicateDesc ) {
+    const trueFn = typeof trueVal === 'function' ? trueVal : () => trueVal;
+    const falseFn = typeof falseVal === 'function' ? falseVal : () => falseVal;
+
+    const fn = ( msg ) => ( predicate( msg ) ? trueFn( msg ) : falseFn( msg ) );
+
+    fn.toString = () => `chooseWhen(${predicateDesc}, ${trueVal}, ${falseVal})`;
+    fn.semantics = {
+        type: 'chooseWhen',
+        predicate: predicateDesc,
+        trueVal,
+        falseVal
+    };
+
+    return fn;
+}; // chooseWhen()
+
+/**
+ * Create a tunable parameter that clamps a message field value to [min, max].
+ *
+ * Useful for safety limits or bounded parameters.
+ *
+ * @param {string} field - Message field to read
+ * @param {number} min - Minimum value (inclusive)
+ * @param {number} max - Maximum value (inclusive)
+ * @returns {Function} Tunable function with .semantics attached
+ *
+ * @example
+ * const safeThreshold = clampTo( 'requestedThreshold', 10, 100 );
+ * safeThreshold( { requestedThreshold: 5 } );    // → 10
+ * safeThreshold( { requestedThreshold: 50 } );   // → 50
+ * safeThreshold( { requestedThreshold: 150 } );  // → 100
+ */
+export const clampTo = function ( field, min, max ) {
+    const fn = ( msg ) => {
+        const val = msg[ field ];
+        return val < min ? min : ( val > max ? max : val );
+    };
+
+    fn.toString = () => `clampTo("${field}", ${min}, ${max})`;
+    fn.semantics = {
+        type: 'clampTo',
+        field,
+        min,
+        max
+    };
+
+    return fn;
+}; // clampTo()
+
+/**
+ * Create a tunable parameter that reads a field directly from the message.
+ *
+ * Simplest dynamic parameter — just passes through a message field.
+ * Useful when the parameter should track another field exactly.
+ *
+ * @param {string} field - Message field to read
+ * @param {*} [defaultVal] - Default value if field is missing/undefined
+ * @returns {Function} Tunable function with .semantics attached
+ *
+ * @example
+ * const dynamicThreshold = fromField( 'learnedBaseline', 50 );
+ * dynamicThreshold( { learnedBaseline: 72 } );  // → 72
+ * dynamicThreshold( { otherField: 10 } );       // → 50 (default)
+ */
+export const fromField = function ( field, defaultVal ) {
+    const fn = ( msg ) => msg[ field ] ?? defaultVal;
+
+    fn.toString = () => `fromField("${field}", ${JSON.stringify( defaultVal )})`;
+    fn.semantics = {
+        type: 'fromField',
+        field,
+        default: defaultVal
+    };
+
+    return fn;
+}; // fromField()
+
+/**
+ * Create a tunable parameter that adds an offset to a message field value.
+ *
+ * Simpler than scaleBy when factor is 1.
+ *
+ * @param {string} field - Message field to read
+ * @param {number} offset - Value to add
+ * @returns {Function} Tunable function with .semantics attached
+ *
+ * @example
+ * const threshold = offsetBy( 'baseline', 10 );
+ * threshold( { baseline: 72 } );  // → 82
+ */
+export const offsetBy = function ( field, offset ) {
+    const fn = ( msg ) => msg[ field ] + offset;
+
+    fn.toString = () => `offsetBy("${field}", ${offset})`;
+    fn.semantics = {
+        type: 'offsetBy',
+        field,
+        offset
+    };
+
+    return fn;
+}; // offsetBy()

package/src/core/tunable/index.js

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Tunable pattern for dynamic parameters.
+ *
+ * Enables parameters to adapt to message context (operating mode, regime, etc.)
+ * by normalizing static values and functions to a uniform callable interface.
+ *
+ * All node parameters become functions, enabling dynamic behavior
+ * without type-checking overhead during message processing.
+ *
+ * ## Guard Pattern (for node implementors)
+ *
+ * Dynamic tunables (user-supplied functions) can throw at runtime.
+ * Each node's update.js wraps all tunable resolves in a single try/catch.
+ * On throw, JS assignment semantics guarantee the state field retains its
+ * previous good value (RHS evaluated first; failed RHS ⇒ assignment
+ * never executes). Nodes seed state fields in init.js so the first-message
+ * edge case has a meaningful fallback.
+ *
+ * Log suppression: `state.tunableErrorLogged` flag prevents console
+ * flooding — one log per error episode, reset on successful recovery
+ * or on node reset (reset.js clears the flag).
+ *
+ * Static tunables (`asTunable(42)` → `() => 42`) cannot throw, so the
+ * guard only activates for dynamic tunables.
+ */
+
+/**
+ * Convert value to function. Static values become () => value.
+ * Functions pass through unchanged.
+ *
+ * This enables uniform parameter access in node update() functions:
+ * `const threshold = state.thresholdFn( msg )` works whether threshold
+ * was configured as a static number or a dynamic function.
+ *
+ * @param {*} v - Static value or function
+ * @returns {Function} Always returns a function
+ *
+ * @example
+ * // Static value
+ * const fn = asTunable( 42 );
+ * fn( msg );  // → 42
+ *
+ * @example
+ * // Dynamic function
+ * const fn = asTunable( ( msg ) => msg.stdev * 0.5 );
+ * fn( { stdev: 10 } );  // → 5
+ */
+export const asTunable = ( v ) => ( typeof v === 'function' ? v : () => v );
+
+/**
+ * Extract parameter context for LLM/dashboard consumption.
+ *
+ * Provides introspection metadata about whether a parameter is static
+ * or dynamic, including the formula string for dynamic parameters.
+ * Helper functions can attach `.semantics` for richer context.
+ *
+ * @param {string} name - Parameter name
+ * @param {*} value - Parameter value (static or function)
+ * @returns {Object} Context object with type, value/formula, and semantics
+ *
+ * @example
+ * // Static parameter
+ * extractParamContext( 'threshold', 78 );
+ * // → { name: 'threshold', type: 'static', value: 78 }
+ *
+ * @example
+ * // Dynamic parameter
+ * extractParamContext( 'delta', ( msg ) => msg.stdev * 0.5 );
+ * // → { name: 'delta', type: 'dynamic', formula: '( msg ) => msg.stdev * 0.5', semantics: null }
+ *
+ * @example
+ * // Dynamic parameter with helper semantics
+ * const scaledDelta = scaleBy( 'stdev', 0.5 );
+ * extractParamContext( 'delta', scaledDelta );
+ * // → { name: 'delta', type: 'dynamic', formula: 'scaleBy("stdev", 0.5, 0, 0)', semantics: { type: 'scaleBy', ... } }
+ */
+export const extractParamContext = function ( name, value ) {
+    if ( typeof value === 'function' ) {
+        return {
+            name,
+            type: 'dynamic',
+            formula: value.toString(),
+            semantics: value.semantics || null
+        };
+    }
+    return { name, type: 'static', value };
+}; // extractParamContext()