@winkjs/composer 0.0.2 → 0.4.0

package/src/nodes/pass-if/update.js

@@ -0,0 +1,37 @@
+// nodes/pass-if/update.js
+
+/**
+ * @fileoverview Update function for passIf node
+ *
+ * Hot path — evaluates user-supplied predicate with message and
+ * counter. Returns null to stop downstream flow when predicate
+ * is false. Predicate errors are caught and tracked per-episode.
+ */
+
+const update = function ( state, msg ) {
+    if ( state.disable || state.pause ) return state;
+
+    // Increment counter for this message
+    state.counter += 1;
+
+    let shouldPass;
+    try {
+        // Evaluate predicate with message and current counter
+        shouldPass = state.predicate( msg, state.counter );
+        // 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
+        shouldPass = false;
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.predicateErrorLogged ) {
+            state.predicateErrorLogged = true;
+            console.error( `WinkComposer/passIf: predicate threw exception: ${error.message}` );
+        }
+    }
+
+    // Return null to stop flow, state to continue
+    return shouldPass ? state : null;
+}; // update()
+
+export default update;

package/src/nodes/persist-if/helpers.js

@@ -0,0 +1,111 @@
+// nodes/persist-if/helpers.js
+
+/**
+ * @fileoverview Helper functions for persistIf node
+ *
+ * The shared write-failure recording used by update.js, and the static
+ * fallback error for adapters that break the return contract. Mirrors
+ * emit-if/helpers.js — the two output gates share one failure model.
+ */
+
+/**
+ * Static fallback error the framework substitutes when an adapter breaks
+ * the return contract — no result object at all, or `{ ok: false }` with
+ * no `error` (ADR-018 error vocabulary). A module-level singleton, so the
+ * hot path allocates nothing. Mirrors emit-if.
+ */
+const MALFORMED_RESULT_ERROR = {
+    code: 'MALFORMED_RESULT',
+    message: 'storage returned a malformed write result (expected { ok, error? })'
+};
+
+/**
+ * Throws when an annotate return is not a plain object — arrays pass a
+ * bare typeof check but are just as wrong. A flow-authoring bug surfaces
+ * in the node's own error episode (the predicate/annotate try in
+ * update.js), never downstream where it would masquerade as an adapter
+ * failure. Mirrors emit-if.
+ *
+ * @param {*} record - The annotate return value
+ * @throws {Error} Naming the offending type
+ */
+const assertAnnotateReturn = function ( record ) {
+    const got = record === null ? 'null' :
+        ( Array.isArray( record ) ? 'array' : typeof record );
+    if ( got === 'object' ) {
+        return;
+    }
+    throw new Error( `annotate must return an object, got ${got}` );
+}; // assertAnnotateReturn()
+
+/**
+ * Warns, once per gate, about invented keys in an annotate record.
+ *
+ * An invented key is one the annotate function added that is neither a
+ * declared column nor a field of the message. Such a key is almost always
+ * a typo, and today it fails silently: the persist plan writes only
+ * declared columns, so the value never reaches storage. Keys that also
+ * exist in the message are skipped on purpose — a `...msg` spread carries
+ * many working fields, and naming those would bury the real finding.
+ *
+ * Runs once per gate. The `checked` flag lives on the wiring-stamped sweep
+ * object that every partition shares, and it flips before the comparison,
+ * so the check cannot repeat. The Object.keys call and the warning string
+ * allocate — once, on this single firing, inside the per-event allocation
+ * the function-form annotate already makes. Later firings never reach this
+ * function (update.js short-circuits on the flag), so the steady-state hot
+ * path stays allocation-free per ADR-004.
+ *
+ * @param {Object} state - Node state (name, insightType, annotateSweep)
+ * @param {Object} record - The record the annotate function returned
+ * @param {Object} msg - The message that produced it
+ */
+const sweepAnnotateKeys = function ( state, record, msg ) {
+    const sweep = state.annotateSweep;
+    sweep.checked = true;
+
+    const recordKeys = Object.keys( record );
+    const invented = [];
+    for ( let i = 0; i < recordKeys.length; i += 1 ) {
+        const key = recordKeys[ i ];
+        if ( !sweep.declaredColumns.has( key ) && !( key in msg ) ) {
+            invented.push( key );
+        }
+    }
+
+    if ( invented.length > 0 ) {
+        console.warn(
+            `WinkComposer/persistIf: annotate for node '${state.name}' ` +
+            `(insightType '${state.insightType}') returned keys that are not declared columns: ` +
+            `${invented.join( ', ' )}. These values are never stored, because the persist plan ` +
+            'writes only declared columns. Check the key names against the asset class. ' +
+            'Reported once per gate.'
+        );
+    }
+}; // sweepAnnotateKeys()
+
+/**
+ * Records a failed write into the node's failure episode: updates the
+ * last* fields, and on the first failure of an episode captures the first*
+ * fields and logs one console.error (repeats stay quiet until a successful
+ * write closes the episode — see update.js). The first* fields keep the
+ * episode-opening error (the cause; later failures in a cascade are
+ * symptoms).
+ *
+ * @param {Object} state - Node state
+ * @param {Object} error - The `{ code, message }` from the storage's
+ *   `{ ok: false }` return (ADR-018 sink return contract)
+ */
+const recordPersistFailure = function ( state, error ) {
+    state.persistErrors += 1;
+    state.lastPersistError = error.message;
+    state.lastPersistErrorCode = error.code;
+    if ( !state.writeErrorLogged ) {
+        state.writeErrorLogged = true;
+        state.firstPersistError = error.message;
+        state.firstPersistErrorCode = error.code;
+        console.error( state.writeErrorLogPrefix + error.code + '): ' + error.message );
+    }
+}; // recordPersistFailure()
+
+export { assertAnnotateReturn, sweepAnnotateKeys, recordPersistFailure, MALFORMED_RESULT_ERROR };

package/src/nodes/persist-if/index.js

@@ -0,0 +1,9 @@
+// nodes/persist-if/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';
+// Re-export everything from introspection
+export * from './introspect.js';

package/src/nodes/persist-if/init.js

@@ -0,0 +1,98 @@
+// nodes/persist-if/init.js
+
+/**
+ * @fileoverview Initialization for persistIf node
+ *
+ * Validates specification and creates initial state with pre-allocated
+ * structures for zero-allocation hot path.
+ */
+
+import { validateWithSchema } from '../../core/utils/validate/index.js';
+import { getDSLMetadata, getNodeType } from './introspect.js';
+
+/**
+ * Initialize persistIf node state.
+ *
+ * @param {Object} spec - Node specification
+ * @param {string} spec.nodeType - Must be 'Persist If'
+ * @param {string} spec.name - Node identifier
+ * @param {Function} spec.predicate - Function to evaluate for persistence
+ * @param {string} spec.insightType - Insight type (maps to storage table)
+ * @param {string} spec.storageName - Name of registered storage adapter
+ * @param {Function} [spec.annotate] - Shapes the stored record: write annotate( msg )
+ *   instead of msg. Mirrors emitIf's annotate; the persist plan still writes only
+ *   the insight type's declared columns, so the hook cannot widen the schema.
+ * @param {Object} [spec.annotateSweep] - Stamped by wiring, not by flow authors:
+ *   the declared-column set plus a shared once-flag for the first-firing
+ *   unknown-key warning (see helpers.js sweepAnnotateKeys)
+ * @returns {Object} Initialized state
+ */
+const init = function ( spec ) {
+    // Validate specification
+    const metadata = getDSLMetadata();
+    const validation = validateWithSchema(
+        {
+            ...metadata.specSchema,
+            _crossFieldValidators: metadata.crossFieldValidators
+        },
+        spec,
+        'spec'
+    );
+    validation.throwIfInvalid( getNodeType() );
+
+    // Create state after validation passes
+    const state = Object.create( null );
+
+    // Core configuration
+    state.nodeType = getNodeType();
+    state.name = spec.name;
+    state.predicate = spec.predicate;
+    state.insightType = spec.insightType;
+    state.storageName = spec.storageName;
+    state.annotate = spec.annotate || null;
+    // Annotate key-sweep support, stamped by wiring (wire-storages) when a
+    // function-form annotate can be checked against declared columns. The
+    // object is shared by every partition of this gate on purpose: its
+    // `checked` flag makes the unknown-key warning fire once per gate, not
+    // once per partition. Unit tests and flows without an asset class have
+    // no stamp; null disables the check.
+    state.annotateSweep = spec.annotateSweep || null;
+
+    // Storage reference (injected by partition manager at runtime)
+    state.storage = null;
+
+    // State transition tracking (semantic — controls error tracking)
+    state.inErrorState = false;
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    // Statistics for observability
+    state.persistCount = 0;
+    state.passCount = 0;
+    state.lastPersistTime = null;
+
+    // Error tracking
+    state.persistErrors = 0;
+    state.lastPersistError = null;
+    // Per ADR-018 the storage write returns { ok: false, error: { code, message } }
+    // on failure. We surface both fields: lastPersistError is the human message
+    // (predicate exceptions also write here as a string), lastPersistErrorCode
+    // is the structured code (null when the error came from a predicate exception
+    // since predicate failures are not classified by the contract).
+    state.lastPersistErrorCode = null;
+    // Write-failure episode: one console.error per episode; a successful
+    // write closes it. The first* fields keep the episode-opening error —
+    // in a cascade the LAST error is the symptom and the FIRST is the
+    // cause. They survive recovery for post-mortem reads and are
+    // overwritten only when the next episode opens.
+    state.writeErrorLogged = false;
+    state.firstPersistError = null;
+    state.firstPersistErrorCode = null;
+    // Static log prefix pre-built here per ADR-004 (no string building in
+    // update beyond the two runtime fields, and only once per episode).
+    state.writeErrorLogPrefix = `WinkComposer/persistIf: storage write failed (node=${state.name}, insightType=${state.insightType}, code=`;
+
+    return state;
+}; // init()
+
+export default init;

package/src/nodes/persist-if/introspect.js

@@ -0,0 +1,106 @@
+// nodes/persist-if/introspect.js
+
+/**
+ * @fileoverview Introspection metadata for persistIf node
+ *
+ * Single source of truth for DSL metadata, validation schema,
+ * and node capabilities. Used by flow transpiler and documentation.
+ */
+
+import { validators } from '../../core/utils/validate/index.js';
+
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [];  // Pass-through node, no stats to publish
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {};  // No stats, no descriptions
+
+/** Control methods available for triggers (none - side-effect only node) */
+const SUPPORTED_CONTROL_METHODS = {};
+
+/** The type of this node */
+const NODE_TYPE = 'Persist If';
+
+/** Node capabilities for documentation (kept accurate to shipping code) */
+const CAPABILITIES = {
+    description: 'Conditionally persists messages to storage without disrupting pipeline flow',
+    features: [
+        'Pure pass-through behavior - messages continue unchanged',
+        'Conditional persistence based on predicate function',
+        'Optional annotate hook shapes the stored record (mirrors emitIf); the persist plan still writes only the insight type\'s declared columns',
+        'On the first firing, annotate record keys are checked once per gate: a key that is neither a declared column nor a message field is named in a warning, because its value would otherwise vanish silently',
+        'Columns and types come from the declared semantics (asset class), never inferred from data',
+        'Writes through the storage handle\'s write and reads its classified { ok, error } result',
+        'Write failures open a loud error episode (one console.error per episode); the pipeline never stops',
+        'Per-partition persistence tracking'
+    ]
+};
+
+// 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 = {};
+
+// DSL Metadata for transpilation
+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 JavaScript identifier'
+        },
+        predicate: {
+            type: 'function',
+            required: true,
+            arity: 1,
+            error: 'Predicate must be a function with exactly one parameter (msg)'
+        },
+        insightType: {
+            type: 'string',
+            required: true,
+            error: 'Insight type must be specified (maps to storage table)'
+        },
+        storageName: {
+            type: 'string',
+            required: true,
+            error: 'Storage name must reference a registered storage adapter'
+        },
+        annotate: {
+            type: 'function',
+            required: false,
+            arity: 1,
+            error: 'Annotate must be a function with exactly one parameter (msg)'
+        },
+        stats: {
+            type: 'object',
+            required: false,
+            propertyNames: [],  // No stats for pass-through node
+            error: 'PersistIf is a pass-through node and does not support stats'
+        }
+    },
+
+    // Cross-field validators
+    crossFieldValidators: [],
+
+    // Build spec from DSL
+    buildSpec: ( name, predicate, options ) => ( {
+        nodeType: NODE_TYPE,
+        name,
+        predicate,
+        ...options
+    } )
+};
+
+export const getDSLMetadata = () => ( { ...DSL_METADATA } );

package/src/nodes/persist-if/publish-to.js

@@ -0,0 +1,21 @@
+// nodes/persist-if/publish-to.js
+
+/**
+ * @fileoverview PublishTo function for persistIf node
+ *
+ * Pass-through node - message continues unchanged.
+ * No fields are added to the outgoing message.
+ */
+
+/**
+ * Publish computed results to message.
+ *
+ * @param {Object} _state - Node state (unused)
+ * @param {Object} _msg - Outgoing message (unchanged)
+ */
+const publishTo = function ( _state, _msg ) {
+    // Pure pass-through node - message continues unchanged
+    // No fields are added to the message
+}; // publishTo()
+
+export default publishTo;

package/src/nodes/persist-if/recompute.js

@@ -0,0 +1,20 @@
+// nodes/persist-if/recompute.js
+
+/**
+ * @fileoverview Recompute function for persistIf node
+ *
+ * No numerical computation to stabilize.
+ */
+
+/**
+ * Recompute for numerical stability.
+ *
+ * @param {Object} _state - Node state (unused)
+ * @returns {boolean} Always true (no recomputation needed)
+ */
+const recompute = function ( _state ) {
+    // No numerical computation to stabilize
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/nodes/persist-if/reset.js

@@ -0,0 +1,35 @@
+// nodes/persist-if/reset.js
+
+/**
+ * @fileoverview Reset function for persistIf node
+ *
+ * Resets statistics and state tracking.
+ */
+
+/**
+ * Reset node state.
+ *
+ * @param {Object} state - Node state
+ * @returns {boolean} Always true (ADR-004; parity with emitIf)
+ */
+const reset = function ( state ) {
+    // Reset statistics
+    state.persistCount = 0;
+    state.passCount = 0;
+    state.lastPersistTime = null;
+    state.persistErrors = 0;
+    state.lastPersistError = null;
+    state.lastPersistErrorCode = null;
+    state.firstPersistError = null;
+    state.firstPersistErrorCode = null;
+
+    // Reset state tracking
+    state.inErrorState = false;
+    // Clear error suppression so next error episode is logged
+    state.predicateErrorLogged = false;
+    state.writeErrorLogged = false;
+
+    return true;
+}; // reset()
+
+export default reset;

package/src/nodes/persist-if/update.js

@@ -0,0 +1,112 @@
+// nodes/persist-if/update.js
+
+/**
+ * @fileoverview Update function for persistIf node
+ *
+ * Hot path - zero allocation after first message (annotate, when configured,
+ * allocates only on the ticks that actually persist - the same per-event
+ * asymmetry as emitIf's annotate).
+ * Evaluates predicate, optionally shapes the record via annotate, and writes
+ * it to the storage buffer if the predicate passed.
+ */
+
+import { assertAnnotateReturn, sweepAnnotateKeys, recordPersistFailure, MALFORMED_RESULT_ERROR } from './helpers.js';
+
+/**
+ * Process incoming message.
+ *
+ * @param {Object} state - Node state
+ * @param {Object} msg - Incoming message
+ * @returns {Object} Updated state (always returns state for pass-through)
+ */
+const update = function ( state, msg ) {
+    // Always increment pass count for observability
+    state.passCount += 1;
+
+    // Early exit if storage not available
+    if ( !state.storage ) {
+        return state;
+    }
+
+    // Evaluate predicate, then shape the record when persisting. Annotate
+    // mirrors emitIf: both run inside one try, so predicate and annotate
+    // share the same error episode (tracking, log suppression, recovery).
+    let shouldPersist = false;
+    let record = msg;
+    try {
+        shouldPersist = state.predicate( msg );
+        if ( shouldPersist && state.annotate ) {
+            record = state.annotate( msg );
+            // A flow-authoring bug (non-object return) throws here, into
+            // this node's error episode — never into storage.write where
+            // it would masquerade as a storage failure (SEND_FAILED).
+            assertAnnotateReturn( record );
+            // First firing only: warn about invented record keys — typos
+            // that would otherwise vanish silently (the persist plan writes
+            // only declared columns). Every later firing takes this
+            // two-read short-circuit; nothing allocates here.
+            if ( state.annotateSweep && !state.annotateSweep.checked ) {
+                sweepAnnotateKeys( state, record, msg );
+            }
+        }
+
+        // Clear error state on successful evaluation
+        if ( state.inErrorState ) {
+            state.inErrorState = false;
+        }
+        // Recovery: clear log-suppression flag on success
+        if ( state.predicateErrorLogged ) state.predicateErrorLogged = false;
+    } catch ( error ) {
+        // Handle predicate/annotate errors (semantic — tracks error state)
+        if ( !state.inErrorState ) {
+            state.inErrorState = true;
+        }
+        // Log first error per episode; suppress subsequent until recovery
+        if ( !state.predicateErrorLogged ) {
+            state.predicateErrorLogged = true;
+            console.error( `WinkComposer/persistIf: predicate threw exception: ${error.message}` );
+        }
+        state.persistErrors += 1;
+        state.lastPersistError = error.message;
+        // Predicate exceptions are persist-if-internal, not part of the
+        // ADR-018 adapter err.code vocabulary. Clear the code so the two
+        // fields stay in sync (a stale code from a prior storage error
+        // would mislead readers).
+        state.lastPersistErrorCode = null;
+        return state;
+    }
+
+    // Write to storage if predicate returned true
+    if ( shouldPersist ) {
+        // Build record for storage (zero-alloc: storage.write handles it).
+        // storage.write() is synchronous per ADR-013; the actual I/O happens
+        // asynchronously via the storage adapter's background flush.
+        // Per the ADR-018 sink return contract, the storage answers
+        // { ok: true } on success or
+        // { ok: false, error: { code, message } } on failure.
+        const result = state.storage.write(
+            state.insightType,
+            record,
+            state.partitionId
+        );
+
+        if ( result && result.ok ) {
+            state.persistCount += 1;
+            // Wall-clock marker of the last successful write (post-mortem
+            // reads only, like the first* error fields).
+            state.lastPersistTime = Date.now();
+            // Recovery: a successful write closes the failure episode.
+            if ( state.writeErrorLogged ) state.writeErrorLogged = false;
+        } else {
+            // A malformed result (no object at all, or ok:false with no
+            // error) counts as a failure with the static fallback error,
+            // so a non-conforming adapter can neither fail silently
+            // nor throw out of the hot path.
+            recordPersistFailure( state, ( result && result.error ) || MALFORMED_RESULT_ERROR );
+        }
+    }
+
+    return state;
+}; // update()
+
+export default update;

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

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

@@ -0,0 +1,38 @@
+// nodes/persistence-check/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 );
+    // Ensure node is enabled by default
+    state.disable = false;
+    state.pause = false;
+
+    // Extract validated predicate
+    state.predicate = spec.predicate;
+    state.requires = spec.requires;
+    state.stats = spec.stats;
+
+    // Apply defaults manually (validation doesn't enforce them)
+    state.minVotes = spec.minVotes || introspect.DEFAULT_OPTIONS.minVotes;
+    state.outOfTotal = spec.outOfTotal || introspect.DEFAULT_OPTIONS.outOfTotal;
+
+    // State variables
+    state.persistenceConfirmed = false;
+    state.voteCount = 0;
+    state.unvoteCount = 0;
+
+    state.nodeType = introspect.getNodeType();
+    state.inControlPhase = false;
+
+    // Log suppression: one log per error episode; reset on recovery.
+    state.predicateErrorLogged = false;
+
+    return state;
+}; // init()
+
+export default init;