@winkjs/composer 0.5.1 → 0.7.0

package/src/core/wiring/wire-node.js

@@ -37,27 +37,27 @@ const wireNode = function ( nodeModule, nodeIndex, nextHops = [], options = {} )
     const maxRecentErrors = options.maxRecentErrors || 5;
     // Validate required node module interface at wire-time
     if ( !nodeModule || typeof nodeModule.update !== 'function' ) {
-        throw new TypeError( `composer/wireNode: Node module must implement update function; found ${typeof nodeModule.update}` );
+        throw new TypeError( `winkComposer/wiring: Node module must implement update function; found ${typeof nodeModule.update}` );
     }
 
     if ( typeof nodeModule.publishTo !== 'function' ) {
-        throw new TypeError( `composer/wireNode: Node module must implement publishTo function; found ${typeof nodeModule.publishTo}` );
+        throw new TypeError( `winkComposer/wiring: Node module must implement publishTo function; found ${typeof nodeModule.publishTo}` );
     }
 
     // Validate next hops are executable functions
     if ( !Array.isArray( nextHops ) ) {
-        throw new TypeError( `composer/wireNode: Next hops must be an array; found ${typeof nextHops}` );
+        throw new TypeError( `winkComposer/wiring: Next hops must be an array; found ${typeof nextHops}` );
     }
 
     for ( let i = 0; i < nextHops.length; i += 1 ) {
         if ( typeof nextHops[ i ] !== 'function' ) {
-            throw new TypeError( `composer/wireNode: Next hop at index ${i} must be a function; found ${typeof nextHops[ i ]}` );
+            throw new TypeError( `winkComposer/wiring: Next hop at index ${i} must be a function; found ${typeof nextHops[ i ]}` );
         }
     }
 
     // Validate node index for state store access
     if ( typeof nodeIndex !== 'number' || nodeIndex < 0 ) {
-        throw new RangeError( `composer/wireNode: Node index must be a non-negative number; found ${nodeIndex}` );
+        throw new RangeError( `winkComposer/wiring: Node index must be a non-negative number; found ${nodeIndex}` );
     }
 
     /**
@@ -142,7 +142,7 @@ const wireNode = function ( nodeModule, nodeIndex, nextHops = [], options = {} )
 
             // Provide node-level error isolation with contextual information
             // This prevents individual node failures from crashing the entire flow
-            const nodeError = new Error( `Node execution failed at index ${nodeIndex}: ${error.message}` );
+            const nodeError = new Error( `winkComposer/wiring: Node execution failed at index ${nodeIndex}: ${error.message}` );
             nodeError.cause = error;
             nodeError.nodeIndex = nodeIndex;
             nodeError.nodeModule = nodeModule.getNodeType ? nodeModule.getNodeType() : 'unknown';

package/src/core/wiring/wire-semantics.js

@@ -151,7 +151,7 @@ const applySemanticsRequirement = function ( adapterId, module, runtimeAssetClas
             // QuestDB's existing createStorage guard; this layer
             // catches it earlier in the lifecycle.
             const err = new Error(
-                `WinkComposer/wiring: adapter '${adapterId}' declares semanticsRequirement.assetClass.required ` +
+                `winkComposer/wiring: adapter '${adapterId}' declares semanticsRequirement.assetClass.required ` +
                 'but the flow has no .assetClass() — add .assetClass(assetClassDef) to the flow definition'
             );
             err.code = 'MISSING_ASSET_CLASS';

package/src/core/wiring/wire-storages.js

@@ -48,6 +48,7 @@
 import { assertHandle } from './assert-handle.js';
 import { assertModuleDurability } from './assert-module.js';
 import { applySemanticsRequirement } from './wire-semantics.js';
+import { logger } from '../logger/index.js';
 
 /**
  * Methods the framework calls on a storage handle later, so they have to
@@ -145,6 +146,13 @@ const storages = ( function () {
     // to assetClass.name if not explicitly specified.
     const wire = async function ( specs, storageConfigs, storageModules, assetClass = null ) {
         const pendingStorages = [];
+        // Names whose factory has been called in THIS wire() call. The
+        // singleton slot is filled only after every pending factory has
+        // settled. Without this set, a flow with several persist-if nodes
+        // on one storage would call the factory once per node and keep
+        // only the last handle. Each orphan would hold a flush timer, an
+        // agent, and a sender for the life of the process.
+        const pendingNames = new Set();
 
         for ( const spec of specs ) {
             // Skip non-persistIf nodes
@@ -154,14 +162,14 @@ const storages = ( function () {
 
             const storageName = spec.storageName;
 
-            // Skip if already in singleton registry
-            if ( singletons[ storageName ] ) {
+            // Skip if already in singleton registry, or already being built
+            if ( singletons[ storageName ] || pendingNames.has( storageName ) ) {
                 continue; // eslint-disable-line no-continue
             }
 
             const module = storageModules[ storageName ];
             if ( !module?.createStorage ) {
-                throw new Error( `composer: Invalid storage module: ${storageName}` );
+                throw new Error( `winkComposer/wiring: Invalid storage module: ${storageName}` );
             }
 
             // ADR-018 module-surface check: the module must say what a
@@ -195,6 +203,7 @@ const storages = ( function () {
 
             // createStorage may return Promise (async) or storage directly (sync)
             const storageOrPromise = module.createStorage( effectiveConfig );
+            pendingNames.add( storageName );
             pendingStorages.push( { storageName, storageOrPromise } );
         }
 
@@ -322,8 +331,8 @@ const storages = ( function () {
             if ( result.status === 'rejected' ) {
                 const err = result.reason || {};
                 const dropped = err.dropped ? ` dropped=${describeDropped( err.dropped )}` : '';
-                console.error(
-                    `WinkComposer/wiring: storage '${names[ i ]}' shutdown failed [${err.code || 'UNKNOWN'}]: ${err.message || String( err )}${dropped}`
+                logger.error(
+                    `winkComposer/wiring: storage '${names[ i ]}' shutdown failed [${err.code || 'UNKNOWN'}]: ${err.message || String( err )}${dropped}`
                 );
             }
         } );

package/src/flow/driver.js

@@ -24,9 +24,18 @@
  * `processMessage`, exactly as a success does — so `feedAll` counts it as
  * processed. See `docs/handbook/headless-flow.md`.
  *
+ * `err.code` vocabulary (console classification; listed per ADR-018):
+ * - `CALLBACK_FAILED` — the user's `onError` itself threw or rejected.
+ *   The shared callback guard contains the fault (ADR-018): the feed
+ *   loop continues, counters stay truthful, and each fault becomes one
+ *   classified console line carrying the detail.
+ *
  * @see docs/handbook/headless-flow.md
  */
 
+import { wrapCallback } from '../core/utils/callback-guard/index.js';
+import { logger } from '../core/logger/index.js';
+
 /**
  * Default fault handler. Surfaces every fault so none is silent. Allocates only
  * when a fault occurs (rare), never on the success path. Provide your own
@@ -37,7 +46,7 @@
  * @returns {void}
  */
 const logFault = function ( error ) {
-    console.error( `composer/headlessDriver: a message failed — ${error.message}` );
+    logger.error( `winkComposer/headlessDriver: a message failed — ${error.message}` );
 }; // logFault()
 
 /**
@@ -56,18 +65,34 @@ const logFault = function ( error ) {
 const headlessDriver = function ( handle, opts = {} ) {
     if ( !handle || typeof handle.processMessage !== 'function' ) {
         throw new TypeError(
-            'composer/headlessDriver: handle must be the object returned by ' +
+            'winkComposer/headlessDriver: handle must be the object returned by ' +
             'flow(...).run() — it has no processMessage() function'
         );
     }
 
-    const onError = opts.onError === undefined ? logFault : opts.onError;
-    if ( typeof onError !== 'function' ) {
+    const userOnError = opts.onError === undefined ? logFault : opts.onError;
+    if ( typeof userOnError !== 'function' ) {
         throw new TypeError(
-            'composer/headlessDriver: onError must be a function'
+            'winkComposer/headlessDriver: onError must be a function'
         );
     }
 
+    // Armed once at construction (validate raw first, then wrap). The
+    // fault reporter is user code too, so it gets the same containment
+    // as the messages it reports on. ADR-018's rule: a misbehaving
+    // user callback never interrupts the operation that invoked it.
+    // A throwing or rejecting onError costs one classified console
+    // line. The feed continues and the counters stay truthful.
+    const onError = wrapCallback( userOnError, {
+        name: 'onError',
+        severity: 'red',
+        report: function ( severity, name, detail ) {
+            logger.error(
+                `winkComposer/headlessDriver: user callback ${name} failed [CALLBACK_FAILED]: ${detail}`
+            );
+        }
+    } );
+
     /**
      * Feed one message. Use this for push sources, where an event hands you a
      * message and there is no loop to own.
@@ -123,7 +148,7 @@ const headlessDriver = function ( handle, opts = {} ) {
         const isSync = typeof source?.[ Symbol.iterator ] === 'function';
         if ( !isAsync && !isSync ) {
             throw new TypeError(
-                'composer/headlessDriver.feedAll: source must be a sync or async ' +
+                'winkComposer/headlessDriver.feedAll: source must be a sync or async ' +
                 'iterable (an array, a generator, or a stream)'
             );
         }

package/src/flow/expand-single-input-array.js

@@ -12,12 +12,12 @@ const expandXOutputsOptions = function ( meta, nodeArgs, flowState ) {
         const param = inputs[ i ];
 
         if ( seenX[ param ] === 1 ) {
-            throw new Error( `WinkComposer/flow: duplicate input found: '${param}'.` );
+            throw new Error( `winkComposer/flow: duplicate input found: '${param}'.` );
         }
         seenX[ param ] = 1;
 
         const instName = `${baseName}_${param}`;
-        if ( isNodeNameDuplicate( instName ) ) throw Error( `WinkComposer/flow: duplicate node ${instName} found.` );
+        if ( isNodeNameDuplicate( instName ) ) throw Error( `winkComposer/flow: duplicate node ${instName} found.` );
         const stats = Object.create( null );
         for ( const st in outputs ) {
             if (Object.prototype.hasOwnProperty.call( outputs, st ) ) {
@@ -47,12 +47,12 @@ const expandXOptions = function ( meta, nodeArgs, flowState ) {
         const param = inputs[ i ];
 
         if ( seenX[ param ] === 1 ) {
-            throw new Error( `WinkComposer/flow: duplicate input found: '${param}'.` );
+            throw new Error( `winkComposer/flow: duplicate input found: '${param}'.` );
         }
         seenX[ param ] = 1;
 
         const instName = `${baseName}_${param}`;
-        if ( isNodeNameDuplicate( instName ) ) throw Error( `WinkComposer/flow: duplicate node ${instName} found.` );
+        if ( isNodeNameDuplicate( instName ) ) throw Error( `winkComposer/flow: duplicate node ${instName} found.` );
 
         const spec = meta.buildSpec( instName, param, ...balanceArgs );
         specs.push( spec );

package/src/flow/flow-api-schemas.js

@@ -226,7 +226,7 @@ export const validateFlowConfig = function ( config, schema, methodName ) {
             valid: false,
             errors,
             throwIfInvalid: () => {
-                throw new Error( `WinkComposer/flow.${methodName}: ${errors[ 0 ]}` );
+                throw new Error( `winkComposer/flow.${methodName}: ${errors[ 0 ]}` );
             }
         };
     }
@@ -241,7 +241,7 @@ export const validateFlowConfig = function ( config, schema, methodName ) {
         throwIfInvalid: () => {
             if ( !validation.valid ) {
                 throw new Error(
-                    `WinkComposer/flow.${methodName}: validation failed:\n  - ${validation.errors.join( '\n  - ' )}`
+                    `winkComposer/flow.${methodName}: validation failed:\n  - ${validation.errors.join( '\n  - ' )}`
                 );
             }
         }
@@ -266,7 +266,7 @@ export const validateFlowArrayConfig = function ( config, schema, methodName ) {
             valid: false,
             errors,
             throwIfInvalid: () => {
-                throw new Error( `WinkComposer/flow.${methodName}: ${errors[ 0 ]}` );
+                throw new Error( `winkComposer/flow.${methodName}: ${errors[ 0 ]}` );
             }
         };
     }
@@ -280,7 +280,7 @@ export const validateFlowArrayConfig = function ( config, schema, methodName ) {
         throwIfInvalid: () => {
             if ( !validation.valid ) {
                 throw new Error(
-                    `WinkComposer/flow.${methodName}: validation failed:\n  - ${validation.errors.join( '\n  - ' )}`
+                    `winkComposer/flow.${methodName}: validation failed:\n  - ${validation.errors.join( '\n  - ' )}`
                 );
             }
         }

package/src/flow/flow.js

@@ -47,6 +47,27 @@ import { validateWithSchema } from '../core/utils/validate/index.js';
 import { assetClassSchema } from '../core/semantics/schemas/index.js';
 import { expandTemplateSpec } from './expand-template-spec.js';
 
+/**
+ * Throws the flow's setup error for an adapter config that the
+ * adapter's own schema rejected. The error carries `INVALID_CONFIG`,
+ * the ADR-018 setup code, and the ADR-028 bracket. A program matches
+ * the code; an operator reads the remedy the schema names.
+ *
+ * @param {{valid: boolean, errors: string[]}} validation - The schema result
+ * @param {string} label - `flow.<method>.<adapterId>`, for the message
+ * @throws {Error} INVALID_CONFIG when the config is invalid
+ */
+const throwIfAdapterConfigInvalid = function ( validation, label ) {
+    if ( validation.valid ) {
+        return;
+    }
+    const err = new Error(
+        `winkComposer/${label}: validation failed [INVALID_CONFIG]:\n  - ${validation.errors.join( '\n  - ' )}`
+    );
+    err.code = 'INVALID_CONFIG';
+    throw err;
+}; // throwIfAdapterConfigInvalid()
+
 const flow = function ( flowName = 'flow1' ) {
     const api = Object.create( null );
 
@@ -91,7 +112,7 @@ const flow = function ( flowName = 'flow1' ) {
     const enforceConfigFirst = function ( methodName ) {
         if ( pipelineStarted ) {
             throw new Error(
-                `WinkComposer/flow: .${methodName}() must be called before any nodes or .switch()/.groupBy()`
+                `winkComposer/flow: .${methodName}() must be called before any nodes or .switch()/.groupBy()`
             );
         }
     };
@@ -100,11 +121,11 @@ const flow = function ( flowName = 'flow1' ) {
     const validateSwitchComplete = function () {
         if ( switchState.active ) {
             if ( switchState.caseOrder.length === 0 ) {
-                throw new Error( 'WinkComposer/flow: .switch() requires at least one .case()' );
+                throw new Error( 'winkComposer/flow: .switch() requires at least one .case()' );
             }
             if ( !switchState.caseEnded ) {
                 throw new Error(
-                    `WinkComposer/flow: case '${switchState.currentCase}' must end with .break()`
+                    `winkComposer/flow: case '${switchState.currentCase}' must end with .break()`
                 );
             }
         }
@@ -118,7 +139,7 @@ const flow = function ( flowName = 'flow1' ) {
         const collisions = collectFlowOutputCollisions( switchState, flowDefinition );
         if ( collisions.length > 0 ) {
             throw new Error(
-                'WinkComposer/flow: output field collision(s) - two nodes on one path ' +
+                'winkComposer/flow: output field collision(s) - two nodes on one path ' +
                 'write the same message field:\n  - ' + collisions.join( '\n  - ' )
             );
         }
@@ -160,10 +181,10 @@ const flow = function ( flowName = 'flow1' ) {
     api.source = function ( adapter, sourceConfig = {} ) {
         enforceConfigFirst( 'source' );
         if ( typeof adapter !== 'object' || adapter === null ) {
-            throw new Error( 'WinkComposer/flow: source adapter must be an imported module' );
+            throw new Error( 'winkComposer/flow: source adapter must be an imported module' );
         }
         if ( typeof adapter.start !== 'function' ) {
-            throw new Error( 'WinkComposer/flow: source adapter must have a start() function' );
+            throw new Error( 'winkComposer/flow: source adapter must have a start() function' );
         }
 
         // If the adapter provides a configSchema, we validate config here.
@@ -171,7 +192,7 @@ const flow = function ( flowName = 'flow1' ) {
         // not later inside adapter.start().
         if ( adapter.configSchema ) {
             const validation = validateWithSchema( adapter.configSchema, sourceConfig, 'source' );
-            validation.throwIfInvalid( `flow/source:${adapter.id || 'unknown'}` );
+            throwIfAdapterConfigInvalid( validation, `flow.source.${adapter.id || 'unknown'}` );
         }
 
         runtime.source = { adapter, config: sourceConfig };
@@ -181,13 +202,13 @@ const flow = function ( flowName = 'flow1' ) {
     api.emitter = function ( adapter, emitterConfig = {} ) {
         enforceConfigFirst( 'emitter' );
         if ( typeof adapter !== 'object' || adapter === null ) {
-            throw new Error( 'WinkComposer/flow: emitter adapter must be an imported module' );
+            throw new Error( 'winkComposer/flow: emitter adapter must be an imported module' );
         }
         if ( typeof adapter.id !== 'string' || !adapter.id ) {
-            throw new Error( 'WinkComposer/flow: emitter adapter must have an id' );
+            throw new Error( 'winkComposer/flow: emitter adapter must have an id' );
         }
         if ( typeof adapter.createEmitter !== 'function' ) {
-            throw new Error( 'WinkComposer/flow: emitter adapter must have a createEmitter() function' );
+            throw new Error( 'winkComposer/flow: emitter adapter must have a createEmitter() function' );
         }
 
         // If the adapter provides a configSchema, we validate config here.
@@ -195,7 +216,7 @@ const flow = function ( flowName = 'flow1' ) {
         // not later inside adapter.createEmitter().
         if ( adapter.configSchema ) {
             const validation = validateWithSchema( adapter.configSchema, emitterConfig, 'emitter' );
-            validation.throwIfInvalid( `flow/emitter:${adapter.id}` );
+            throwIfAdapterConfigInvalid( validation, `flow.emitter.${adapter.id}` );
         }
 
         runtime.emitters[ adapter.id ] = { adapter, config: emitterConfig };
@@ -205,13 +226,13 @@ const flow = function ( flowName = 'flow1' ) {
     api.storage = function ( adapter, storageConfig = {} ) {
         enforceConfigFirst( 'storage' );
         if ( typeof adapter !== 'object' || adapter === null ) {
-            throw new Error( 'WinkComposer/flow: storage adapter must be an imported module' );
+            throw new Error( 'winkComposer/flow: storage adapter must be an imported module' );
         }
         if ( typeof adapter.id !== 'string' || !adapter.id ) {
-            throw new Error( 'WinkComposer/flow: storage adapter must have an id' );
+            throw new Error( 'winkComposer/flow: storage adapter must have an id' );
         }
         if ( typeof adapter.createStorage !== 'function' ) {
-            throw new Error( 'WinkComposer/flow: storage adapter must have a createStorage() function' );
+            throw new Error( 'winkComposer/flow: storage adapter must have a createStorage() function' );
         }
 
         // If the adapter provides a configSchema, we validate config here.
@@ -219,7 +240,7 @@ const flow = function ( flowName = 'flow1' ) {
         // not later inside adapter.createStorage().
         if ( adapter.configSchema ) {
             const validation = validateWithSchema( adapter.configSchema, storageConfig, 'storage' );
-            validation.throwIfInvalid( `flow/storage:${adapter.id}` );
+            throwIfAdapterConfigInvalid( validation, `flow.storage.${adapter.id}` );
         }
 
         runtime.storages[ adapter.id ] = { adapter, config: storageConfig };
@@ -230,7 +251,7 @@ const flow = function ( flowName = 'flow1' ) {
         enforceConfigFirst( 'assetId' );
 
         if ( typeof field !== 'string' || field.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: .assetId() requires a non-empty string field name' );
+            throw new Error( 'winkComposer/flow: .assetId() requires a non-empty string field name' );
         }
 
         // Schema-based validation for robust error handling
@@ -251,7 +272,7 @@ const flow = function ( flowName = 'flow1' ) {
         if ( assetClassDef === null || assetClassDef === undefined || typeof assetClassDef !== 'object' ) {
             const actualType = assetClassDef === null ? 'null' : typeof assetClassDef;
             throw new Error(
-                `WinkComposer/flow.assetClass: Expected object, got ${actualType}`
+                `winkComposer/flow.assetClass: Expected object, got ${actualType}`
             );
         }
 
@@ -266,7 +287,7 @@ const flow = function ( flowName = 'flow1' ) {
         const validation = validateWithSchema( assetClassSchema, assetClassDef, 'assetClass' );
         if ( !validation.valid ) {
             throw new Error(
-                `WinkComposer/flow.assetClass: validation failed:\n  - ${validation.errors.join( '\n  - ' )}`
+                `winkComposer/flow.assetClass: validation failed:\n  - ${validation.errors.join( '\n  - ' )}`
             );
         }
 
@@ -298,7 +319,7 @@ const flow = function ( flowName = 'flow1' ) {
      */
     api.switch = function ( field ) {
         if ( typeof field !== 'string' || field.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: .switch() requires a non-empty string field name' );
+            throw new Error( 'winkComposer/flow: .switch() requires a non-empty string field name' );
         }
 
         // Schema-based validation: field must be a valid identifier (mirrors .assetId())
@@ -307,21 +328,21 @@ const flow = function ( flowName = 'flow1' ) {
 
         // Check groupBy before switchState (endGroup sets switchState.active)
         if ( groupByState.active || groupByState.expanded ) {
-            throw new Error( 'WinkComposer/flow: .switch() cannot be used with .groupBy()' );
+            throw new Error( 'winkComposer/flow: .switch() cannot be used with .groupBy()' );
         }
         if ( switchState.active ) {
-            throw new Error( 'WinkComposer/flow: .switch() can only be called once per flow' );
+            throw new Error( 'winkComposer/flow: .switch() can only be called once per flow' );
         }
         if ( flowDefinition.length > 0 ) {
             throw new Error(
-                'WinkComposer/flow: .switch() cannot be called after nodes - ' +
+                'winkComposer/flow: .switch() cannot be called after nodes - ' +
                 'use .switch() before defining any nodes, or omit .switch() for single-pipeline flows'
             );
         }
 
         // Validate field conflict with partition
         if ( runtime.partitionField === field ) {
-            throw new Error( 'WinkComposer/flow: partition field and switch field must be different' );
+            throw new Error( 'winkComposer/flow: partition field and switch field must be different' );
         }
 
         runtime.specializationField = field;
@@ -340,15 +361,15 @@ const flow = function ( flowName = 'flow1' ) {
      */
     api.case = function ( key ) {
         if ( !switchState.active ) {
-            throw new Error( 'WinkComposer/flow: .case() requires an active .switch()' );
+            throw new Error( 'winkComposer/flow: .case() requires an active .switch()' );
         }
         if ( switchState.currentCase !== null && !switchState.caseEnded ) {
             throw new Error(
-                `WinkComposer/flow: previous case '${switchState.currentCase}' must end with .break() before starting a new case`
+                `winkComposer/flow: previous case '${switchState.currentCase}' must end with .break() before starting a new case`
             );
         }
         if ( switchState.caseSpecs[ key ] !== undefined ) {
-            throw new Error( `WinkComposer/flow: duplicate case key '${key}'` );
+            throw new Error( `winkComposer/flow: duplicate case key '${key}'` );
         }
 
         switchState.currentCase = key;
@@ -367,14 +388,14 @@ const flow = function ( flowName = 'flow1' ) {
      */
     api.break = function () {
         if ( !switchState.active ) {
-            throw new Error( 'WinkComposer/flow: .break() requires an active .switch()' );
+            throw new Error( 'winkComposer/flow: .break() requires an active .switch()' );
         }
         if ( switchState.currentCase === null || switchState.caseEnded ) {
-            throw new Error( 'WinkComposer/flow: .break() must follow a .case() with at least one node' );
+            throw new Error( 'winkComposer/flow: .break() must follow a .case() with at least one node' );
         }
         if ( switchState.caseSpecs[ switchState.currentCase ].length === 0 ) {
             throw new Error(
-                `WinkComposer/flow: case '${switchState.currentCase}' is empty - add at least one node before .break()`
+                `winkComposer/flow: case '${switchState.currentCase}' is empty - add at least one node before .break()`
             );
         }
 
@@ -408,7 +429,7 @@ const flow = function ( flowName = 'flow1' ) {
     api.groupBy = function ( field, values ) {
         // Validation: field must be non-empty string
         if ( typeof field !== 'string' || field.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: .groupBy() requires a non-empty string field name' );
+            throw new Error( 'winkComposer/flow: .groupBy() requires a non-empty string field name' );
         }
 
         // Schema-based validation: field must be a valid identifier (mirrors .assetId())
@@ -417,14 +438,14 @@ const flow = function ( flowName = 'flow1' ) {
 
         // Validation: values must be array with at least 2 elements
         if ( !Array.isArray( values ) || values.length < 2 ) {
-            throw new Error( 'WinkComposer/flow: .groupBy() requires at least 2 group values' );
+            throw new Error( 'winkComposer/flow: .groupBy() requires at least 2 group values' );
         }
 
         // Validation: each value must be string or number
         for ( let i = 0; i < values.length; i += 1 ) {
             const v = values[ i ];
             if ( typeof v !== 'string' && typeof v !== 'number' ) {
-                throw new Error( `WinkComposer/flow: group value at index ${i} must be a string or number` );
+                throw new Error( `winkComposer/flow: group value at index ${i} must be a string or number` );
             }
         }
 
@@ -433,32 +454,32 @@ const flow = function ( flowName = 'flow1' ) {
         for ( let i = 0; i < values.length; i += 1 ) {
             const v = values[ i ];
             if ( seen[ v ] ) {
-                throw new Error( `WinkComposer/flow: duplicate group value '${v}' in .groupBy()` );
+                throw new Error( `winkComposer/flow: duplicate group value '${v}' in .groupBy()` );
             }
             seen[ v ] = 1;
         }
 
         // Validation: cannot call groupBy twice (check this first - user intent is to reuse groupBy)
         if ( groupByState.active || groupByState.expanded ) {
-            throw new Error( 'WinkComposer/flow: .groupBy() can only be called once per flow' );
+            throw new Error( 'winkComposer/flow: .groupBy() can only be called once per flow' );
         }
 
         // Validation: cannot use groupBy if switchState is active (manual switch, not from endGroup)
         if ( switchState.active ) {
-            throw new Error( 'WinkComposer/flow: .groupBy() cannot be used inside .switch()' );
+            throw new Error( 'winkComposer/flow: .groupBy() cannot be used inside .switch()' );
         }
 
         // Validation: must come before any nodes
         if ( flowDefinition.length > 0 ) {
             throw new Error(
-                'WinkComposer/flow: .groupBy() cannot be called after nodes - ' +
+                'winkComposer/flow: .groupBy() cannot be called after nodes - ' +
                 'use .groupBy() before defining any nodes'
             );
         }
 
         // Validation: groupBy field cannot equal partition field
         if ( runtime.partitionField === field ) {
-            throw new Error( 'WinkComposer/flow: partition field and groupBy field must be different' );
+            throw new Error( 'winkComposer/flow: partition field and groupBy field must be different' );
         }
 
         // Initialize groupBy state
@@ -487,12 +508,12 @@ const flow = function ( flowName = 'flow1' ) {
     api.endGroup = function () {
         // Validation: must be in active groupBy state
         if ( !groupByState.active ) {
-            throw new Error( 'WinkComposer/flow: .endGroup() requires an active .groupBy()' );
+            throw new Error( 'winkComposer/flow: .endGroup() requires an active .groupBy()' );
         }
 
         // Validation: must have at least one template node
         if ( groupByState.templateSpecs.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: .groupBy() must contain at least one node before .endGroup()' );
+            throw new Error( 'winkComposer/flow: .groupBy() must contain at least one node before .endGroup()' );
         }
 
         // Set specialization field (same as switch does)
@@ -553,7 +574,7 @@ const flow = function ( flowName = 'flow1' ) {
 
         // Single-pipeline mode (backward compatible)
         if ( flowDefinition.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: Cannot build empty flow - add at least one node' );
+            throw new Error( 'winkComposer/flow: Cannot build empty flow - add at least one node' );
         }
         const imports = Array.from( importSet ).sort();
         return serializeModule( { imports, flowName, specs: flowDefinition } );
@@ -646,7 +667,7 @@ const flow = function ( flowName = 'flow1' ) {
 
         // Single-pipeline mode (backward compatible)
         if ( flowDefinition.length === 0 ) {
-            throw new Error( 'WinkComposer/flow: Cannot run empty flow - add at least one node' );
+            throw new Error( 'winkComposer/flow: Cannot run empty flow - add at least one node' );
         }
         const handle = await runFlow( flowName, flowDefinition, importSet, runtime );
         return handle;