@winkjs/composer 0.0.2 → 0.4.1

package/src/core/env-vars.js

@@ -0,0 +1,245 @@
+// core/env-vars.js
+
+/* eslint-disable no-process-env */
+
+import os from 'os';
+
+// ============================================================================
+// ENVIRONMENT VARIABLE DEFINITIONS
+// ============================================================================
+
+// Yield threshold parses with Number(), not parseInt(): 'Infinity' must map
+// to Infinity — the documented never-yield sentinel (`.yield( { threshold:
+// Infinity } )` uses the same value). An empty string is forced to NaN so
+// validation fails fast; Number( '' ) would silently give 0, which means
+// "breathe after every message" — not what an operator who set the variable
+// to nothing intended.
+const rawYieldMs = ( process.env.YIELD_TIME_THRESHOLD_MS ?? '500' ).trim();
+
+const ENV_VARS = {
+    // Core Configuration
+    edgeDeviceId: ( process.env.EDGE_DEVICE_ID ?? os.hostname() ).trim(),
+    nodeEnv: ( process.env.NODE_ENV ?? 'development' ).trim(),
+
+    // Partition Management (see ADR-016)
+    maxPartitionsAllowed: parseInt( process.env.COMPOSER_MAX_PARTITIONS_ALLOWED ?? '10000', 10 ),
+
+    // STORAGE_DIR retired 2026-07-09 — the emitter's LevelDB store
+    // (removed by ADR-021) was the only thing that ever wrote there.
+    // A future WAL adapter defines its own disk-path configuration.
+
+    // Flow lifecycle — top-level forced-shutdown timeout (process layer)
+    // Bounds the entire `handle.shutdown()` drain. If `shutdown-manager`
+    // doesn't see graceful completion within this many milliseconds, it
+    // logs and force-exits with code 1 (vs 0 on graceful). Matches
+    // Kubernetes' default `terminationGracePeriodSeconds` of 30. See
+    // ADR-018 (flow lifecycle and signal handling).
+    shutdownForceTimeoutMs: parseInt( process.env.SHUTDOWN_FORCE_TIMEOUT_MS ?? '30000', 10 ),
+
+    // Flow yield — default time threshold between deliberate event-loop
+    // breaths (ADR-024). Matters only to callers that wait on
+    // `processMessage` (file replays, testHarness, the headless driver):
+    // for them the yield tick is the only planned chance for sink flush
+    // timers and socket I/O to run. 500 ms is half the tightest background
+    // timer it must not starve (QUESTDB_IDLE_FLUSH_CHECK_MS, 1000).
+    // Per-flow override: `.yield( { threshold } )`. Infinity = never yield.
+    yieldTimeThresholdMs: rawYieldMs === '' ? NaN : Number( rawYieldMs ),
+
+    // MQTT Configuration
+    mqttBrokerUrl: ( process.env.MQTT_BROKER_URL ?? 'mqtt://127.0.0.1:1883' ).trim(),
+    mqttMsgExpiry: parseInt( process.env.MQTT_MSG_EXPIRY ?? '3600', 10 ),
+    mqttKeepalive: parseInt( process.env.MQTT_KEEPALIVE ?? '60', 10 ),
+    mqttReconnectMs: parseInt( process.env.MQTT_RECONNECT_MS ?? '5000', 10 ),
+    mqttConnectTimeoutMs: parseInt( process.env.MQTT_CONNECT_TIMEOUT_MS ?? '30000', 10 ),
+    // How long the MQTT emitter factory waits at startup for the
+    // broker's first connection acknowledgment before handing the
+    // flow its handle anyway (recovering posture — the wait expiring
+    // is not an error). 0 disables the wait. Per-emitter override:
+    // the `connectGraceMs` config key.
+    mqttConnectGraceMs: parseInt( process.env.MQTT_CONNECT_GRACE_MS ?? '500', 10 ),
+    mqttSessionExpiryS: parseInt( process.env.MQTT_SESSION_EXPIRY_S ?? '604800', 10 ),
+    mqttMaxQueueSize: parseInt( process.env.MQTT_MAX_QUEUE_SIZE ?? '10000', 10 ),
+    // MQTT_MAX_QUEUE_BYTES retired with the emitter's disk store
+    // (ADR-021) — the in-memory emitter bounds memory by count alone.
+    // MQTT_DEDUP_WINDOW (count-only dedup) retired 2026-07-09 by
+    // ADR-022 — the source dedup cache is now time-bounded AND
+    // count-capped, with its own two variables below.
+    mqttSourceDedupWindowMs: parseInt( process.env.MQTT_SOURCE_DEDUP_WINDOW_MS ?? '120000', 10 ),
+    mqttSourceDedupMaxEntries: parseInt( process.env.MQTT_SOURCE_DEDUP_MAX_ENTRIES ?? '65536', 10 ),
+
+    // QuestDB Configuration
+    questdbIlpUrl: ( process.env.QUESTDB_ILP_URL ?? 'localhost:9000' ).trim(),
+    questdbPgUrl: ( process.env.QUESTDB_PG_URL ?? 'localhost:8812' ).trim(),
+    questdbFlushMode: ( process.env.QUESTDB_FLUSH_MODE ?? 'auto' ).trim(),
+    questdbIdleFlushAfterMs: parseInt( process.env.QUESTDB_IDLE_FLUSH_AFTER_MS ?? '5000', 10 ),
+    questdbIdleFlushCheckMs: parseInt( process.env.QUESTDB_IDLE_FLUSH_CHECK_MS ?? '1000', 10 ),
+    // Optional QuestDB settings (undefined if not set)
+    questdbAutoFlushRows: process.env.QUESTDB_AUTO_FLUSH_ROWS ?
+        parseInt( process.env.QUESTDB_AUTO_FLUSH_ROWS, 10 ) : undefined,
+    questdbAutoFlushIntervalMs: process.env.QUESTDB_AUTO_FLUSH_INTERVAL_MS ?
+        parseInt( process.env.QUESTDB_AUTO_FLUSH_INTERVAL_MS, 10 ) : undefined,
+    questdbMaxBufSize: process.env.QUESTDB_MAX_BUF_SIZE ?
+        parseInt( process.env.QUESTDB_MAX_BUF_SIZE, 10 ) : undefined,
+    questdbRetryTimeout: process.env.QUESTDB_RETRY_TIMEOUT ?
+        parseInt( process.env.QUESTDB_RETRY_TIMEOUT, 10 ) : undefined,
+
+    // QuestDB Credentials
+    questdbDatabase: ( process.env.QUESTDB_DATABASE ?? 'qdb' ).trim(),
+    questdbUser: ( process.env.QUESTDB_USER ?? 'admin' ).trim(),
+    questdbPassword: process.env.QUESTDB_PASSWORD ?? 'quest'
+};
+
+// ============================================================================
+// VALIDATORS
+// ============================================================================
+const validators = {
+    edgeDeviceId: function ( value ) {
+        if ( !value ) return 'Cannot be empty';
+        if ( !( /^[\w\-\/.]+$/ ).test( value ) ) {
+            return `Invalid characters for MQTT topic: "${value}"`;
+        }
+        return null;
+    },
+
+    nodeEnv: function ( value ) {
+        const validEnvs = [ 'development', 'production', 'test' ];
+        if ( !validEnvs.includes( value ) ) {
+            return `Must be one of ${validEnvs.join( ', ' )}, got: "${value}"`;
+        }
+        return null;
+    },
+
+    mqttMsgExpiry: function ( value, originalEnv ) {
+        if ( isNaN( value ) || value <= 0 ) {
+            return `Must be positive integer, got: "${originalEnv}"`;
+        }
+        return null;
+    },
+
+    positiveInt: function ( value, originalEnv ) {
+        if ( isNaN( value ) || value <= 0 ) {
+            return `Must be positive integer, got: "${originalEnv}"`;
+        }
+        return null;
+    },
+
+    hostPort: function ( value ) {
+        if ( !value ) return 'Cannot be empty';
+        // Match host:port pattern (host can be hostname or IP)
+        const hostPortRegex = /^[\w.\-]+:\d+$/;
+        if ( !hostPortRegex.test( value ) ) {
+            return `Must be host:port format, got: "${value}"`;
+        }
+        return null;
+    },
+
+    questdbFlushMode: function ( value ) {
+        const validModes = [ 'auto', 'manual' ];
+        if ( !validModes.includes( value ) ) {
+            return `Must be one of ${validModes.join( ', ' )}, got: "${value}"`;
+        }
+        return null;
+    },
+
+    positiveIntOrUndefined: function ( value, originalEnv ) {
+        if ( value === undefined ) return null;
+        if ( isNaN( value ) || value <= 0 ) {
+            return `Must be positive integer, got: "${originalEnv}"`;
+        }
+        return null;
+    },
+
+    nonNegativeInt: function ( value, originalEnv ) {
+        if ( isNaN( value ) || value < 0 ) {
+            return `Must be non-negative integer, got: "${originalEnv}"`;
+        }
+        return null;
+    },
+
+    nonNegativeNumberOrInfinity: function ( value, originalEnv ) {
+        if ( isNaN( value ) || value < 0 ) {
+            return `Must be a non-negative number or Infinity, got: "${originalEnv}"`;
+        }
+        return null;
+    },
+
+    nonEmptyString: function ( value ) {
+        if ( !value || value.trim() === '' ) {
+            return `Cannot be empty, got: "${value}"`;
+        }
+        return null;
+    },
+
+    mqttUrl: function ( value ) {
+        if ( !value ) return 'Cannot be empty';
+        if ( !value.startsWith( 'mqtt://' ) && !value.startsWith( 'mqtts://' ) ) {
+            return `Must start with 'mqtt://' or 'mqtts://', got: "${value}"`;
+        }
+        return null;
+    }
+};
+
+// ============================================================================
+// VALIDATION CONFIGURATION
+// ============================================================================
+const validationConfig = [
+    { field: 'edgeDeviceId', validator: validators.edgeDeviceId },
+    { field: 'nodeEnv', validator: validators.nodeEnv },
+    { field: 'maxPartitionsAllowed', validator: validators.positiveInt, originalEnv: 'COMPOSER_MAX_PARTITIONS_ALLOWED' },
+    { field: 'yieldTimeThresholdMs', validator: validators.nonNegativeNumberOrInfinity, originalEnv: 'YIELD_TIME_THRESHOLD_MS' },
+    { field: 'mqttBrokerUrl', validator: validators.mqttUrl, label: 'MQTT_BROKER_URL' },
+    { field: 'mqttMsgExpiry', validator: validators.mqttMsgExpiry, originalEnv: 'MQTT_MSG_EXPIRY' },
+    { field: 'mqttKeepalive', validator: validators.positiveInt, originalEnv: 'MQTT_KEEPALIVE' },
+    { field: 'mqttReconnectMs', validator: validators.positiveInt, originalEnv: 'MQTT_RECONNECT_MS' },
+    { field: 'mqttConnectTimeoutMs', validator: validators.positiveInt, originalEnv: 'MQTT_CONNECT_TIMEOUT_MS' },
+    { field: 'mqttConnectGraceMs', validator: validators.nonNegativeInt, originalEnv: 'MQTT_CONNECT_GRACE_MS' },
+    { field: 'mqttSessionExpiryS', validator: validators.positiveInt, originalEnv: 'MQTT_SESSION_EXPIRY_S' },
+    { field: 'mqttMaxQueueSize', validator: validators.positiveInt, originalEnv: 'MQTT_MAX_QUEUE_SIZE' },
+    { field: 'mqttSourceDedupWindowMs', validator: validators.positiveInt, originalEnv: 'MQTT_SOURCE_DEDUP_WINDOW_MS' },
+    { field: 'mqttSourceDedupMaxEntries', validator: validators.positiveInt, originalEnv: 'MQTT_SOURCE_DEDUP_MAX_ENTRIES' },
+    // QuestDB Configuration
+    { field: 'questdbIlpUrl', validator: validators.hostPort, label: 'QUESTDB_ILP_URL' },
+    { field: 'questdbPgUrl', validator: validators.hostPort, label: 'QUESTDB_PG_URL' },
+    { field: 'questdbFlushMode', validator: validators.questdbFlushMode, label: 'QUESTDB_FLUSH_MODE' },
+    { field: 'questdbIdleFlushAfterMs', validator: validators.nonNegativeInt, originalEnv: 'QUESTDB_IDLE_FLUSH_AFTER_MS' },
+    { field: 'questdbIdleFlushCheckMs', validator: validators.positiveInt, originalEnv: 'QUESTDB_IDLE_FLUSH_CHECK_MS' },
+    { field: 'questdbAutoFlushRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_AUTO_FLUSH_ROWS' },
+    { field: 'questdbAutoFlushIntervalMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_AUTO_FLUSH_INTERVAL_MS' },
+    { field: 'questdbMaxBufSize', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_MAX_BUF_SIZE' },
+    { field: 'questdbRetryTimeout', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_RETRY_TIMEOUT' },
+    // QuestDB Credentials
+    { field: 'questdbDatabase', validator: validators.nonEmptyString, label: 'QUESTDB_DATABASE' },
+    { field: 'questdbUser', validator: validators.nonEmptyString, label: 'QUESTDB_USER' }
+    // questdbPassword: no validation — allows empty for passwordless auth
+];
+
+// ============================================================================
+// VALIDATION RUNNER
+// ============================================================================
+const validate = function () {
+    const errors = [];
+
+    // Run each validator
+    for ( const config of validationConfig ) {
+        const value = ENV_VARS[ config.field ];
+        const originalEnv = config.originalEnv ? process.env[ config.originalEnv ] : value;
+        const label = config.label || config.field.toUpperCase().replace( /([a-z])([A-Z])/g, '$1_$2' );
+
+        const error = config.validator( value, originalEnv || value, label );
+        if ( error ) {
+            errors.push( `${label}: ${error}` );
+        }
+    }
+
+    // Fail fast with clear error message
+    if ( errors.length > 0 ) {
+        console.error( 'composer: Environment variable validation failed:' );
+        errors.forEach( ( err ) => console.error( `   - ${err}` ) );
+        process.exit( 1 ); // eslint-disable-line no-process-exit
+    }
+}; // validate()
+
+// Run validation immediately on import
+validate();
+
+export { ENV_VARS, validators };

package/src/core/mqtt-protocol.js

@@ -0,0 +1,47 @@
+// core/mqtt-protocol.js
+
+/**
+ * @fileoverview Shared MQTT protocol invariants for WinkComposer.
+ *
+ * These are design decisions, NOT deployment-configurable values.
+ * Both source and emitter depend on identical values for interoperability:
+ * - QoS 1 (at-least-once) is coupled to the dedup strategy
+ * - Protocol v5 is required for user properties and message expiry
+ * - WINK_NAMESPACE keys must match between publisher and subscriber
+ *
+ * Deployment-configurable MQTT settings (keepalive, reconnect, etc.)
+ * live in ENV_VARS and are consumed by each manager's constants.js.
+ */
+
+// ============================================================================
+// PROTOCOL INVARIANTS
+// ============================================================================
+
+/**
+ * MQTT v5 user property keys for WinkComposer metadata.
+ * Publisher (emitter) writes these; subscriber (source) reads them.
+ *
+ * @type {Object}
+ */
+export const WINK_NAMESPACE = {
+    dedupId: 'winkDedupId',
+    timestamp: 'winkTimestamp',
+    version: 'winkVersion'
+};
+
+/**
+ * QoS level — fixed at 1 (at-least-once delivery).
+ * Duplicates handled by backend deduplication via winkDedupId UUID.
+ * Must match between emitter and source for session resumption.
+ *
+ * @type {number}
+ */
+export const MQTT_QOS = 1;
+
+/**
+ * MQTT protocol version — fixed at 5.
+ * Required for user properties (dedup metadata) and message expiry.
+ *
+ * @type {number}
+ */
+export const MQTT_PROTOCOL_V = 5;

package/src/core/partition-manager/index.js

@@ -0,0 +1,7 @@
+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.js
+export * from './introspect.js';

package/src/core/partition-manager/init.js

@@ -0,0 +1,44 @@
+import validateFlow from './validate-flow.js';
+
+const init = function ( flow ) {
+    // Fail-fast: reject malformed flow config at flow start rather than
+    // at first-message time. All three live callers (src/flow/run.js,
+    // composer-website demo-runner, benchmark-runner) pass through here.
+    validateFlow( flow );
+
+    const composerState = Object.create( null );
+
+    // Two-level structure: partitionId → specializationType → graph
+    composerState.partitionSpecializations = new Map();
+
+    composerState.flow = flow;
+
+    // Cumulative counter of partition-creation attempts (accepted or rejected).
+    // Pre-cap: equals partitionSpecializations.size. Post-cap: diverges by the
+    // rejection count. See ADR-016.
+    composerState.totalPartitionsCreated = 0;
+
+    // Yield state (ADR-024): update() sets `yieldPending` when the time
+    // threshold is crossed; the flow runtime clears it and takes the
+    // event-loop breath after running the message's pipeline.
+    composerState.partitionState = Object.create( null );
+    composerState.partitionState.lastYield = Date.now();
+    composerState.partitionState.yieldPending = false;
+
+    // Registry of sinks that expose getPressure(). Populated by `flow/run.js`
+    // immediately after this init returns, by querying the wire-emitters and
+    // wire-storages registries. The pressure-aware yield decision (ADR-020,
+    // Draft) will read this registry as one of its yield conditions when it
+    // lands; until then the registry is forward-compat plumbing.
+    //
+    // Object.create(null) keyed by 'emitter:<target>' / 'storage:<storageName>'
+    // — a runtime-string-keyed registry per the codebase convention. Keys are
+    // self-describing in debug logs ("which sink crossed the threshold?"
+    // becomes a one-glance answer); for-in iteration over Object.create(null)
+    // is allocation-free on the amortized check path.
+    composerState.partitionState.backpressureAwareSinks = Object.create( null );
+
+    return composerState;
+}; // init()
+
+export default init;

package/src/core/partition-manager/introspect.js

@@ -0,0 +1,15 @@
+/** Single source of truth for what this plugin can do */
+const SUPPORTED_STATS = [
+];
+
+/** Human-readable descriptions (for introspection) */
+const STAT_DESCRIPTIONS = {
+};
+
+/** The type of this node */
+const NODE_TYPE = 'Partition Manager';
+
+// 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 getNodeType = () => NODE_TYPE.slice();

package/src/core/partition-manager/publish-to.js

@@ -0,0 +1,6 @@
+// eslint-disable-next-line no-empty-function
+const publishTo = function ( _state, _msg ) {
+
+}; // publishTo()
+
+export default publishTo;

package/src/core/partition-manager/recompute.js

@@ -0,0 +1,5 @@
+const recompute = function () {
+    return true;
+}; // recompute()
+
+export default recompute;

package/src/core/partition-manager/reset.js

@@ -0,0 +1,5 @@
+const reset = function () {
+    return true;
+}; // reset()
+
+export default reset;

package/src/core/partition-manager/update.js

@@ -0,0 +1,264 @@
+import nodeTypeToModule from '../wiring/node-type-to-module.js';
+
+import { ENV_VARS } from '../env-vars.js';
+
+/**
+ * This function transforms trigger specifications that reference nodes by name
+ * into executable triggers with actual function references and state objects.
+ *
+ * Key Design Drivers:
+ * - All targets in a single trigger must be homogeneous (same node type)
+ * - Control methods are resolved from the target node type
+ * - Target resolution uses spec names for maintainable transpilation
+ * - Comprehensive validation prevents runtime errors
+ *
+ * @param {Array} stateStore - Initialized state store for target state resolution
+ * @param {Array<Object>} triggers - Trigger specifications with named targets
+ * @param {Object} scopedFlow - Specialization-scoped flow data containing specs and nodeModules
+ * @returns {Array<Object>} Resolved triggers with function and state references
+ *
+ * @example
+ * const triggers = [
+ *     { control: 'reset', targets: [ 'fastEWMA', 'slowEWMA' ] }
+ * ];
+ * const resolved = resolveTriggers( stateStore, triggers, scopedFlow );
+ */
+const resolveTriggers = function ( stateStore, triggers, scopedFlow ) {
+    // Handle empty or undefined triggers gracefully
+    if ( triggers === undefined || triggers.length === 0 ) {
+        return [];
+    }
+
+    // Pre-allocate for performance
+    const resolvedTriggers = new Array( triggers.length );
+
+    for ( let i = 0; i < triggers.length; i += 1 ) {
+        const trigger = triggers[ i ];
+        const targets = trigger.targets;
+        const control = trigger.control;
+
+        // Initialize resolved trigger object
+        const resolvedTrigger = Object.create( null );
+        const resolvedTargets = new Array( targets.length );
+
+        // Resolve first target to establish reference node type
+        const firstTargetName = targets[ 0 ];
+        if ( typeof firstTargetName !== 'string' || firstTargetName.length === 0 ) {
+            throw new TypeError( `Target name at trigger ${i}, target 0 must be a non-empty string; found '${firstTargetName}'` );
+        }
+
+        const firstTargetIndex = scopedFlow.specs.findIndex( ( spec ) => spec.name === firstTargetName );
+        if ( firstTargetIndex === -1 ) {
+            throw new Error( `Target node '${firstTargetName}' not found in flow specs for trigger ${i}` );
+        }
+
+        // Get reference node module and validate control method exists
+        const firstSpec = scopedFlow.specs[ firstTargetIndex ];
+        const moduleName = nodeTypeToModule( firstSpec.nodeType );
+        const referenceNode = scopedFlow.nodeModules[ moduleName ];
+
+        if ( !referenceNode ) {
+            throw new Error( `Node module '${moduleName}' not found for nodeType '${firstSpec.nodeType}' in trigger ${i}` );
+        }
+
+        if ( typeof referenceNode[ control ] !== 'function' ) {
+            throw new Error( `Control method '${control}' not found on node type '${referenceNode.getNodeType?.() || firstSpec.nodeType}' for trigger ${i}` );
+        }
+
+        // Store first resolved target
+        resolvedTargets[ 0 ] = stateStore[ firstTargetIndex ];
+
+        // Resolve remaining targets and validate homogeneity
+        for ( let j = 1; j < targets.length; j += 1 ) {
+            const targetName = targets[ j ];
+
+            if ( typeof targetName !== 'string' || targetName.length === 0 ) {
+                throw new TypeError( `Target name at trigger ${i}, target ${j} must be a non-empty string; found '${targetName}'` );
+            }
+
+            const targetIndex = scopedFlow.specs.findIndex( ( spec ) => spec.name === targetName );
+            if ( targetIndex === -1 ) {
+                throw new Error( `Target node '${targetName}' not found in flow specs for trigger ${i}, target ${j}` );
+            }
+
+            // Ensure all targets are homogeneous (same node type)
+            const targetSpec = scopedFlow.specs[ targetIndex ];
+            const targetModuleName = nodeTypeToModule( targetSpec.nodeType );
+            const targetNode = scopedFlow.nodeModules[ targetModuleName ];
+
+            if ( targetNode !== referenceNode ) {
+                const refNodeType = referenceNode.getNodeType?.() || firstSpec.nodeType;
+                const targetNodeType = targetNode.getNodeType?.() || targetSpec.nodeType;
+                throw new Error( `Target node '${targetName}' (type: ${targetNodeType}) is incompatible with reference node type '${refNodeType}' for trigger ${i}` );
+            }
+
+            resolvedTargets[ j ] = stateStore[ targetIndex ];
+        }
+
+        // Store resolved trigger with function reference and state objects
+        resolvedTrigger.control = referenceNode[ control ];
+        resolvedTrigger.targets = resolvedTargets;
+        resolvedTriggers[ i ] = resolvedTrigger;
+    }
+
+    return resolvedTriggers;
+}; // resolveTriggers()
+
+/**
+ * Partition state manager's update with integrated trigger resolution and specialization support.
+ * Resolved triggers are co-located with each node's state for zero hot-path overhead.
+ *
+ * Uses two-level lookup: partitionId → specializationType → graph
+ * Zero allocation in hot path: direct field access with default to 0.
+ *
+ * @param {Object} composerState - Contains partitionSpecializations and flow specification
+ * @param {Object} message - Input message for partition and specialization extraction
+ * @returns {Array|null} Graph (node state array) with resolved triggers, or null if specialization unknown
+ */
+const update = function ( composerState, msg ) {
+    const { partitionSpecializations, flow, partitionState } = composerState;
+
+    // Zero allocation: direct field access, default to 0
+    const partitionId = flow.partitionField ?
+        msg[ flow.partitionField ] :
+        0;
+
+    const specializationType = flow.specializationField ?
+        msg[ flow.specializationField ] :
+        0;
+
+    // Level 1: Partition lookup
+    let specializedGraphs = partitionSpecializations.get( partitionId );
+
+    // Level 2: Specialization lookup (graph may exist or need creation)
+    let graph = specializedGraphs ? specializedGraphs[ specializationType ] : undefined;
+
+    if ( !graph ) {
+        const specs = flow.specsBySpecialization[ specializationType ];
+
+        if ( !specs ) {
+            // Log error and skip message - no default fallback
+            // Note: Do NOT create partition entry for unknown specialization
+            console.error( `[PartitionManager] Unknown specialization '${specializationType}' for partition '${partitionId}'. Message dropped.` );
+            return null;
+        }
+
+        // Create partition entry only after validating specialization exists.
+        // Cap check (ADR-016): enforced here — the sole site where
+        // partitionSpecializations.size increases. Increment-first,
+        // strict-`>` comparison: the Nth partition succeeds, the (N+1)th is
+        // rejected with a console.error mirroring the unknown-specialization
+        // drop pattern above.
+        if ( !specializedGraphs ) {
+            composerState.totalPartitionsCreated += 1;
+            if ( composerState.totalPartitionsCreated > ENV_VARS.maxPartitionsAllowed ) {
+                console.error(
+                    `[PartitionManager] Partition creation for assetId '${partitionId}' ` +
+                    `failed — maxPartitionsAllowed (${ENV_VARS.maxPartitionsAllowed}) reached. ` +
+                    'Message dropped.'
+                );
+                return null;
+            }
+            specializedGraphs = Object.create( null );
+            partitionSpecializations.set( partitionId, specializedGraphs );
+        }
+
+        // Create state array sized for this specialization
+        graph = new Array( specs.length );
+
+        for ( let k = 0; k < specs.length; k += 1 ) {
+            const spec = specs[ k ];
+
+            // Look up node module using nodeTypeToModule
+            const moduleName = nodeTypeToModule( spec.nodeType );
+            const node = flow.nodeModules[ moduleName ];
+
+            if ( !node ) {
+                throw new Error( `Node module '${moduleName}' not found for nodeType '${spec.nodeType}' at index ${k}` );
+            }
+
+            // Initialize node state
+            graph[ k ] = node.init( spec );
+
+            // ====================================================================
+            // MQTT TOPIC INJECTION IN EMIT IF NODE
+            // ====================================================================
+            // Precompute partition-specific MQTT topic at initialization to avoid
+            // reconstruction on every emission (performance optimization).
+            //
+            // Topic structure: edgeDeviceId/partitionId/specialization/insightType
+            // Example: "edge-001/sensor-42/temperature/changeDetected"
+            //
+            // The edgeDeviceId can encode ISA-95 hierarchy for Unified Namespace:
+            // - Simple: "edge-001"
+            // - UNS: "northwind/riverton/plant2/line3" (enterprise/site/area/cell)
+            //
+            // Enables powerful MQTT subscription patterns:
+            // - All from edge: "edge-001/#" or "northwind/riverton/#"
+            // - Specific sensor: "+/sensor-42/#"
+            if ( spec.nodeType === 'Emit If' && ( graph[ k ].target === 'mqtt' || graph[ k ].target === 'terminal' ) ) {
+                graph[ k ].topic = `${ENV_VARS.edgeDeviceId}/${partitionId}/${specializationType}/${graph[ k ].insightType}`;
+            }
+
+            // ====================================================================
+            // STORAGE AND PARTITION INJECTION IN PERSIST IF NODE
+            // ====================================================================
+            // Inject the storage singleton and partition ID at initialization.
+            // Storage reference is set during wiring (spec.storage), but partition
+            // ID is partition-specific and must be injected here.
+            //
+            // Zero hot-path overhead: All references are pre-resolved.
+            if ( spec.nodeType === 'Persist If' && spec.storage ) {
+                graph[ k ].storage = spec.storage;
+                graph[ k ].partitionId = partitionId;
+            }
+
+            // Resolve triggers with specialization-scoped data
+            graph[ k ].resolvedTriggers = resolveTriggers( graph, spec.triggers, {
+                specs: specs,
+                nodeModules: flow.nodeModules
+            });
+        } // for ( let k = 0; k < specs.length; k += 1 )
+
+        // Special handling for Controller nodes with nested triggers
+        // Only controller node allows FORWARD node control.
+        // That is why it has to be performed only after all nodes have
+        // been initialized.
+        for ( let k = 0; k < specs.length; k += 1 ) {
+            const spec = specs[ k ];
+            if ( spec.nodeType === 'Controller' && graph[ k ].logic ) {
+                // Resolve triggers for each condition in the logic array
+                for ( let j = 0; j < graph[ k ].logic.length; j += 1 ) {
+                    graph[ k ].logic[ j ].resolvedTriggers = resolveTriggers(
+                        graph,
+                        graph[ k ].logic[ j ].triggers,
+                        {
+                            specs: specs,
+                            nodeModules: flow.nodeModules
+                        }
+                    );
+                }
+                // No top-level resolvedTriggers for controller
+                graph[ k ].resolvedTriggers = null;
+            }
+        } // for ( let k = 0; k < specs.length; k += 1 )
+
+        specializedGraphs[ specializationType ] = graph;
+    }
+
+    // Yield decision (ADR-024, process-then-breathe): when the threshold is
+    // crossed, ask the caller to give the event loop a turn AFTER it has run
+    // this message's pipeline. The graph always goes back synchronously —
+    // returning a Promise here (the pre-ADR-024 shape) deferred this
+    // message's processing past later ones, reordering updates within a
+    // partition for callers that do not await. flow/run.js owns clearing
+    // the flag and taking the breath.
+    if ( Date.now() - partitionState.lastYield > flow.yieldThreshold ) {
+        partitionState.lastYield = Date.now();
+        partitionState.yieldPending = true;
+    }
+
+    return graph;
+};
+
+export default update;