@output.ai/core 0.3.0-dev.pr263-5d2eaa9 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.3.0-dev.pr263-5d2eaa9",
+  "version": "0.3.1",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/index.d.ts

@@ -79,6 +79,15 @@ export type HttpMethod = 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  */
 export type TemporalActivityOptions = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;
 
+/**
+ * Result of a single job executed by `executeInParallel`.
+ *
+ * @typeParam T - The return type of the job function
+ */
+export type ParallelJobResult<T> =
+  | { ok: true; result: T; index: number } |
+  { ok: false; error: unknown; index: number };
+
 /*
 ╭─────────╮
 │ S T E P │╮
@@ -480,6 +489,81 @@ export declare function workflow<
  ╰───────────────────╯
 */
 
+/**
+ * A single feedback for an EvaluationResult
+ */
+export class EvaluationFeedback {
+  /**
+   * Issue found
+   */
+  issue: string;
+
+  /**
+   * Improvement suggestion
+   */
+  suggestion?: string;
+
+  /**
+   * Reference for the issue
+   */
+  reference?: string;
+
+  /**
+   * Issue priority
+   */
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+
+  /**
+   * @constructor
+   * @param args
+   * @param args.issue
+   * @param args.suggestion
+   * @param args.reference
+   * @param args.priority
+   */
+  constructor( args: {
+    issue: string;
+    suggestion?: string;
+    reference?: string;
+    priority?: 'low' | 'medium' | 'high' | 'critical';
+  } );
+
+  /**
+   * @returns The zod schema for this class
+   */
+  static get schema(): z.ZodType;
+}
+
+/**
+ * Base constructor arguments for EvaluationResult classes
+ */
+export type EvaluationResultArgs<TValue = any> = { // eslint-disable-line @typescript-eslint/no-explicit-any
+  /**
+   * The value of the evaluation
+   */
+  value: TValue;
+  /**
+   * The confidence in the evaluation
+   */
+  confidence: number;
+  /**
+   * The name of the evaluation
+   */
+  name?: string;
+  /**
+   * The reasoning behind the result
+   */
+  reasoning?: string;
+  /**
+   * Feedback for this evaluation
+   */
+  feedback?: EvaluationFeedback[];
+  /**
+   * Dimensions of this evaluation
+   */
+  dimensions?: Array<EvaluationStringResult | EvaluationNumberResult | EvaluationBooleanResult>;
+};
+
 /**
  * Represents the result of an evaluation.
  *
@@ -487,33 +571,45 @@ export declare function workflow<
  */
 export class EvaluationResult {
   /**
-   * @constructor
-   * @param args
-   * @param args.value - The value of the evaluation
-   * @param args.confidence - The confidence in the evaluation
-   * @param args.reasoning - The reasoning behind the result
+   * The name of the evaluation result
+   */
+  name?: string;
+
+  /**
+   * The evaluation result value
+   */
+  value: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * The evaluation result confidence
    */
-  constructor( args: { value: any; confidence: number; reasoning?: string } ); // eslint-disable-line @typescript-eslint/no-explicit-any
+  confidence: number;
 
   /**
-   * @returns The evaluation result value
+   * The evaluation result reasoning
    */
-  get value(): any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  reasoning?: string;
 
   /**
-   * @returns The evaluation result confidence
+   * Feedback for this evaluation
    */
-  get confidence(): number;
+  feedback: EvaluationFeedback[];
 
   /**
-   * @returns The evaluation result reasoning
+   * Dimensions of this evaluation
    */
-  get reasoning(): string;
+  dimensions: Array<EvaluationStringResult | EvaluationNumberResult | EvaluationBooleanResult>;
 
   /**
-   * @returns A zod schema representing this class
+   * @constructor
+   * @param args
+   */
+  constructor( args: EvaluationResultArgs );
+
+  /**
+   * @returns The zod schema for this class
    */
-  get schema(): string;
+  static get schema(): z.ZodType;
 }
 
 /**
@@ -524,16 +620,8 @@ export class EvaluationStringResult extends EvaluationResult {
   /**
    * @constructor
    * @param args
-   * @param args.value - The value of the evaluation
-   * @param args.confidence - The confidence on the evaluation
-   * @param args.reasoning - The reasoning behind the result
    */
-  constructor( args: { value: string; confidence: number; reasoning?: string } );
-
-  /**
-   * @returns The evaluation result value
-   */
-  get value(): string;
+  constructor( args: EvaluationResultArgs<string> );
 }
 
 /**
@@ -544,16 +632,8 @@ export class EvaluationNumberResult extends EvaluationResult {
   /**
    * @constructor
    * @param args
-   * @param args.value - The value of the evaluation
-   * @param args.confidence - The confidence on the evaluation
-   * @param args.reasoning - The reasoning behind the result
-   */
-  constructor( args: { value: number; confidence: number; reasoning?: string } );
-
-  /**
-   * @returns The evaluation result value
    */
-  get value(): number;
+  constructor( args: EvaluationResultArgs<number> );
 }
 
 /**
@@ -564,16 +644,8 @@ export class EvaluationBooleanResult extends EvaluationResult {
   /**
    * @constructor
    * @param args
-   * @param args.value - The value of the evaluation
-   * @param args.confidence - The confidence on the evaluation
-   * @param args.reasoning - The reasoning behind the result
    */
-  constructor( args: { value: boolean; confidence: number; reasoning?: string } );
-
-  /**
-   * @returns The evaluation result value
-   */
-  get value(): boolean;
+  constructor( args: EvaluationResultArgs<boolean> );
 }
 
 /**
@@ -717,6 +789,51 @@ export declare function sendHttpRequest( params: {
   headers?: Record<string, string>;
 } ): Promise<SerializedFetchResponse>;
 
+/**
+ * Execute jobs in parallel with optional concurrency limit.
+ *
+ * Returns all job results (successes and failures) sorted by original job index.
+ * Each result contains `ok` (boolean), `index` (original position), and either
+ * `result` (on success) or `error` (on failure).
+ *
+ * Jobs must be wrapped in arrow functions—do not pass promises directly.
+ *
+ * @example
+ * ```ts
+ * const results = await executeInParallel( {
+ *   jobs: [
+ *     () => myStep( data1 ),
+ *     () => myStep( data2 ),
+ *     () => myStep( data3 )
+ *   ],
+ *   concurrency: 2
+ * } );
+ *
+ * // Handle the discriminated union (result only exists when ok is true)
+ * const successfulResults = results.filter( r => r.ok ).map( r => r.result );
+ *
+ * // Or handle each result individually
+ * for ( const r of results ) {
+ *   if ( r.ok ) {
+ *     console.log( `Job ${r.index} succeeded:`, r.result );
+ *   } else {
+ *     console.log( `Job ${r.index} failed:`, r.error );
+ *   }
+ * }
+ * ```
+ *
+ * @param params - Parameters object
+ * @param params.jobs - Array of arrow functions returning step/activity calls (not promises directly)
+ * @param params.concurrency - Max concurrent jobs (default: Infinity)
+ * @param params.onJobCompleted - Optional callback invoked as each job completes (in completion order)
+ * @returns Array of results sorted by original job index
+ */
+export declare function executeInParallel<T>( params: {
+  jobs: Array<() => Promise<T> | T>;
+  concurrency?: number;
+  onJobCompleted?: ( result: ParallelJobResult<T> ) => void;
+} ): Promise<Array<ParallelJobResult<T>>>;
+
 /*
 ╭─────────────╮
 │ E R R O R S │╮

package/src/index.js

@@ -1,6 +1,7 @@
 import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult } from './interface/evaluator.js';
 import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
+import { executeInParallel } from './interface/workflow_utils.js';
 import { sendHttpRequest, sendPostRequestAndAwaitWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
 export { continueAsNew, sleep } from '@temporalio/workflow';
@@ -16,6 +17,7 @@ export {
   EvaluationStringResult,
   EvaluationBooleanResult,
   // webhook tools
+  executeInParallel,
   sendHttpRequest,
   sendPostRequestAndAwaitWebhook,
   // errors

package/src/interface/evaluator.js

@@ -11,56 +11,158 @@ import * as z from 'zod';
 class EvaluationResultValidationError extends ValidationError {};
 
 /**
- * Generic EvaluationResult class, represents the result
- * of an evaluation
+ * A single feedback for an EvaluationResult
+ */
+export class EvaluationFeedback {
+
+  /**
+   * Issue found
+   * @type {string}
+   */
+  issue;
+
+  /**
+   * Improvement suggestion
+   * @type {string}
+   */
+  suggestion;
+
+  /**
+   * Reference for the issue
+   * @type {string}
+   */
+  reference;
+
+  /**
+   * Issue priority
+   * @type {'low' | 'medium' | 'high' | 'critical' | undefined}
+   */
+  priority;
+
+  /**
+   * The zod schema for this class
+   * @type {z.ZodType}
+   */
+  static get schema() {
+    return z.object( {
+      issue: z.string(),
+      suggestion: z.string().optional(),
+      reference: z.string().optional(),
+      priority: z.enum( [ 'low', 'medium', 'high', 'critical' ] ).optional()
+    } );
+  };
+
+  /**
+   * @constructor
+   * @param {object} args
+   * @param {string} args.issue
+   * @param {string} [args.suggestion]
+   * @param {string} [args.reference]
+   * @param {'low' | 'medium' | 'high' | 'critical'} [args.priority]
+   */
+  constructor( { issue, suggestion = undefined, reference = undefined, priority = undefined } ) {
+    const result = this.constructor.schema.safeParse( { issue, suggestion, reference, priority } );
+    if ( result.error ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    this.issue = issue;
+    this.suggestion = suggestion;
+    this.reference = reference;
+    this.priority = priority;
+  }
+}
+
+/**
+ * Generic EvaluationResult class, represents the result of an evaluation.
  */
 export class EvaluationResult {
 
   /**
-   * Returns the evaluation result value
+   * The name of the evaluation result
+   * @type {string}
+   */
+  name;
+
+  /**
+   * The evaluation result value
    * @type {any}
    */
   value = null;
 
   /**
-   * Returns the confidence value, between 0 and 1.
+   * The confidence value, between 0 and 1
    * @type {number}
    */
-  confidence = undefined;
+  confidence;
 
   /**
-   * Returns the reasoning value.
+   * The reasoning value
    * @type {string}
    */
-  reasoning = undefined;
+  reasoning;
 
-  static get valueSchema() {
-    return z.any();
-  };
+  /**
+   * Feedback for this evaluation
+   * @type {EvaluationFeedback[]}
+   */
+  feedback = [];
+
+  /**
+   * Dimensions of this evaluation
+   * @type {EvaluationResult[]}
+   */
+  dimensions = [];
 
+  /**
+   * The schema main field
+   * @type {z.ZodAny}
+   */
+  static valueSchema = z.any();
+
+  /**
+   * The zod schema for this class
+   * @type {z.ZodType}
+   */
   static get schema() {
-    return z.object( {
+    const baseSchema = z.object( {
       value: this.valueSchema,
       confidence: z.number(),
-      reasoning: z.string().optional()
+      reasoning: z.string().optional(),
+      name: z.string().optional(),
+      feedback: z.array( EvaluationFeedback.schema ).optional()
+    } );
+
+    // Adds dimension but keep it only one level deep
+    return baseSchema.extend( {
+      dimensions: z.array(
+        baseSchema.extend( {
+          value: z.union( [ z.string(), z.number(), z.boolean() ] )
+        } )
+      ).optional()
     } );
   };
 
   /**
    * @constructor
    * @param {object} args
-   * @param {any} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param {any} args.value
+   * @param {number} args.confidence
+   * @param {string} [args.name]
+   * @param {EvaluationResult[]} [args.dimensions]
+   * @param {EvaluationFeedback[]} [args.feedback]
+   * @param {string} [args.reasoning]
    */
-  constructor( args ) {
-    const result = this.constructor.schema.safeParse( args );
+  constructor( { value, confidence, dimensions = [], feedback = [], name = undefined, reasoning = undefined } ) {
+    const result = this.constructor.schema.safeParse( { value, confidence, dimensions, feedback, name, reasoning } );
     if ( result.error ) {
       throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
     }
-    this.value = args.value;
-    this.confidence = args.confidence;
-    this.reasoning = args.reasoning;
+    this.confidence = confidence;
+    this.value = value;
+    this.dimensions = dimensions;
+    this.feedback = feedback;
+    this.name = name;
+    this.reasoning = reasoning;
   }
 };
 
@@ -68,71 +170,51 @@ export class EvaluationResult {
  * An evaluation result that uses a string value
  * @extends EvaluationResult
  * @property {string} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {string} args.value - The value of the evaluation (must be a string)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
  */
 export class EvaluationStringResult extends EvaluationResult {
-  static get valueSchema() {
-    return z.string();
-  };
-
-  /**
-   * @constructor
-   * @param {object} args
-   * @param {string} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
-   */
-  // eslint-disable-next-line no-useless-constructor
-  constructor( args ) {
-    super( args );
-  }
+  static valueSchema = z.string();
 };
 
 /**
  * An evaluation result that uses a boolean value
  * @extends EvaluationResult
  * @property {boolean} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {boolean} args.value - The value of the evaluation (must be a boolean)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
  */
 export class EvaluationBooleanResult extends EvaluationResult {
-  static get valueSchema() {
-    return z.boolean();
-  };
-
-  /**
-   * @constructor
-   * @param {object} args
-   * @param {boolean} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
-   */
-  // eslint-disable-next-line no-useless-constructor
-  constructor( args ) {
-    super( args );
-  }
+  static valueSchema = z.boolean();
 };
 
 /**
  * An evaluation result that uses a number value
  * @extends EvaluationResult
  * @property {number} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {number} args.value - The value of the evaluation (must be a number)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
  */
 export class EvaluationNumberResult extends EvaluationResult {
-  static get valueSchema() {
-    return z.number();
-  };
-
-  /**
-   * @constructor
-   * @param {object} args
-   * @param {number} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
-   */
-  // eslint-disable-next-line no-useless-constructor
-  constructor( args ) {
-    super( args );
-  }
+  static valueSchema = z.number();
 };
 
+/**
+ * Expose the function to create a new evaluator
+ * @param {object} opts
+ * @param {string} opts.name
+ * @param {string} opts.description
+ * @param {z.ZodType} opts.inputSchema
+ * @param {Function} opts.fn
+ * @param {object} opts.options
+ * @returns {Function}
+ */
 export function evaluator( { name, description, inputSchema, fn, options } ) {
   validateEvaluator( { name, description, inputSchema, fn, options } );
 

package/src/interface/evaluator.spec.js

@@ -3,7 +3,8 @@ import {
   EvaluationResult,
   EvaluationStringResult,
   EvaluationNumberResult,
-  EvaluationBooleanResult
+  EvaluationBooleanResult,
+  EvaluationFeedback
 } from './evaluator.js';
 import { ValidationError } from '#errors';
 
@@ -98,6 +99,467 @@ describe( 'interface/evaluator - EvaluationResult classes', () => {
       const bad = EvaluationBooleanResult.schema.safeParse( { value: 'false', confidence: 1 } );
       expect( bad.success ).toBe( false );
     } );
+
+    it( 'schema getter does not cause infinite recursion', () => {
+      // Access schema multiple times to ensure no stack overflow
+      const schema1 = EvaluationResult.schema;
+      const schema2 = EvaluationResult.schema;
+      const schema3 = EvaluationStringResult.schema;
+      const schema4 = EvaluationNumberResult.schema;
+      const schema5 = EvaluationBooleanResult.schema;
+
+      expect( schema1 ).toBeDefined();
+      expect( schema2 ).toBeDefined();
+      expect( schema3 ).toBeDefined();
+      expect( schema4 ).toBeDefined();
+      expect( schema5 ).toBeDefined();
+
+      // Verify schemas can be used for validation
+      const result = schema1.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'dim1', confidence: 0.9 },
+          { value: 42, confidence: 0.8 }
+        ]
+      } );
+      expect( result.success ).toBe( true );
+    } );
+
+    it( 'schema includes dimensions field', () => {
+      const schema = EvaluationResult.schema;
+      const result = schema.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'string-dim', confidence: 0.9 },
+          { value: 42, confidence: 0.8 },
+          { value: true, confidence: 0.7 }
+        ]
+      } );
+      expect( result.success ).toBe( true );
+      if ( result.success ) {
+        expect( result.data.dimensions ).toHaveLength( 3 );
+      }
+    } );
+
+    it( 'schema validates dimensions value types', () => {
+      const schema = EvaluationResult.schema;
+
+      // Valid: primitive value types
+      const valid = schema.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'string', confidence: 0.9 },
+          { value: 42, confidence: 0.8 },
+          { value: true, confidence: 0.7 }
+        ]
+      } );
+      expect( valid.success ).toBe( true );
+
+      // Invalid: non-primitive value type in dimensions
+      const invalid = schema.safeParse( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: { object: 'not allowed' }, confidence: 0.9 }
+        ]
+      } );
+      expect( invalid.success ).toBe( false );
+    } );
+  } );
+
+  describe( 'new fields: name, dimensions, feedback', () => {
+    it( 'accepts optional name field', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        name: 'test-evaluation'
+      } );
+      expect( result.name ).toBe( 'test-evaluation' );
+    } );
+
+    it( 'name defaults to undefined when not provided', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8
+      } );
+      expect( result.name ).toBeUndefined();
+    } );
+
+    it( 'validates name must be string if provided', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        name: 123
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts dimensions array with EvaluationResult instances', () => {
+      const dim1 = new EvaluationStringResult( { value: 'dim1', confidence: 0.9 } );
+      const dim2 = new EvaluationNumberResult( { value: 42, confidence: 0.8 } );
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [ dim1, dim2 ]
+      } );
+      expect( result.dimensions ).toHaveLength( 2 );
+      expect( result.dimensions[0] ).toBe( dim1 );
+      expect( result.dimensions[1] ).toBe( dim2 );
+    } );
+
+    it( 'dimensions defaults to empty array when not provided', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8
+      } );
+      expect( result.dimensions ).toEqual( [] );
+    } );
+
+    it( 'validates dimensions must match subclass schema', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [ { invalid: 'object' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'validates dimensions array structure', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'valid', confidence: 0.9 },
+          { invalid: 'missing confidence' }
+        ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts dimensions with all three subclass types', () => {
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [
+          new EvaluationStringResult( { value: 'string-dim', confidence: 0.9 } ),
+          new EvaluationNumberResult( { value: 42, confidence: 0.8 } ),
+          new EvaluationBooleanResult( { value: true, confidence: 0.7 } )
+        ]
+      } );
+      expect( result.dimensions ).toHaveLength( 3 );
+      expect( result.dimensions[0] ).toBeInstanceOf( EvaluationStringResult );
+      expect( result.dimensions[1] ).toBeInstanceOf( EvaluationNumberResult );
+      expect( result.dimensions[2] ).toBeInstanceOf( EvaluationBooleanResult );
+    } );
+
+    it( 'accepts plain objects matching subclass schemas in dimensions', () => {
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [
+          { value: 'string-dim', confidence: 0.9 },
+          { value: 42, confidence: 0.8 },
+          { value: true, confidence: 0.7 }
+        ]
+      } );
+      expect( result.dimensions ).toHaveLength( 3 );
+      expect( result.dimensions[0].value ).toBe( 'string-dim' );
+      expect( result.dimensions[1].value ).toBe( 42 );
+      expect( result.dimensions[2].value ).toBe( true );
+    } );
+
+    it( 'accepts string dimension value type', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 'string-value', confidence: 0.9 }
+        ]
+      } );
+      expect( result.dimensions[0].value ).toBe( 'string-value' );
+    } );
+
+    it( 'accepts number dimension value type', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: 123, confidence: 0.9 }
+        ]
+      } );
+      expect( result.dimensions[0].value ).toBe( 123 );
+    } );
+
+    it( 'accepts boolean dimension value type', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: true, confidence: 0.9 }
+        ]
+      } );
+      expect( result.dimensions[0].value ).toBe( true );
+    } );
+
+    it( 'rejects dimensions with non-primitive value types', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: { object: 'not allowed' }, confidence: 0.9 }
+        ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'rejects dimensions with array value types', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        dimensions: [
+          { value: [ 1, 2, 3 ], confidence: 0.9 }
+        ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts nested dimensions (recursive)', () => {
+      const nestedDim = new EvaluationStringResult( {
+        value: 'nested',
+        confidence: 0.9,
+        dimensions: [
+          new EvaluationNumberResult( { value: 10, confidence: 0.8 } )
+        ]
+      } );
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [ nestedDim ]
+      } );
+      expect( result.dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions[0].value ).toBe( 10 );
+    } );
+
+    it( 'accepts nested dimensions with plain objects', () => {
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.7,
+        dimensions: [
+          {
+            value: 'nested',
+            confidence: 0.9,
+            dimensions: [
+              { value: 10, confidence: 0.8 }
+            ]
+          }
+        ]
+      } );
+      expect( result.dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions ).toHaveLength( 1 );
+      expect( result.dimensions[0].dimensions[0].value ).toBe( 10 );
+    } );
+
+    it( 'accepts feedback array with EvaluationFeedback instances', () => {
+      const feedback1 = new EvaluationFeedback( {
+        issue: 'Issue 1',
+        suggestion: 'Fix this',
+        priority: 'high'
+      } );
+      const feedback2 = new EvaluationFeedback( {
+        issue: 'Issue 2',
+        reference: 'ref-123'
+      } );
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ feedback1, feedback2 ]
+      } );
+      expect( result.feedback ).toHaveLength( 2 );
+      expect( result.feedback[0] ).toBe( feedback1 );
+      expect( result.feedback[1] ).toBe( feedback2 );
+    } );
+
+    it( 'accepts feedback array with plain objects matching schema', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [
+          { issue: 'Issue 1', suggestion: 'Fix', priority: 'high' },
+          { issue: 'Issue 2', reference: 'ref-123' }
+        ]
+      } );
+      expect( result.feedback ).toHaveLength( 2 );
+      expect( result.feedback[0].issue ).toBe( 'Issue 1' );
+      expect( result.feedback[1].issue ).toBe( 'Issue 2' );
+    } );
+
+    it( 'feedback defaults to empty array when not provided', () => {
+      const result = new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8
+      } );
+      expect( result.feedback ).toEqual( [] );
+    } );
+
+    it( 'validates feedback must match EvaluationFeedback schema', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ { invalid: 'object' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'validates feedback issue is required', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ { suggestion: 'missing issue' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'validates feedback priority enum values', () => {
+      expect( () => new EvaluationResult( {
+        value: 'test',
+        confidence: 0.8,
+        feedback: [ { issue: 'test', priority: 'invalid' } ]
+      } ) ).toThrow( ValidationError );
+    } );
+
+    it( 'accepts all new fields together', () => {
+      const dim = new EvaluationStringResult( { value: 'dim', confidence: 0.9 } );
+      const feedback = new EvaluationFeedback( { issue: 'test issue', priority: 'medium' } );
+      const result = new EvaluationResult( {
+        value: 'main',
+        confidence: 0.8,
+        name: 'comprehensive-test',
+        dimensions: [ dim ],
+        feedback: [ feedback ],
+        reasoning: 'test reasoning'
+      } );
+      expect( result.name ).toBe( 'comprehensive-test' );
+      expect( result.dimensions ).toHaveLength( 1 );
+      expect( result.feedback ).toHaveLength( 1 );
+      expect( result.reasoning ).toBe( 'test reasoning' );
+    } );
+  } );
+} );
+
+describe( 'interface/evaluator - EvaluationFeedback class', () => {
+  describe( 'constructor', () => {
+    it( 'creates feedback with required issue', () => {
+      const feedback = new EvaluationFeedback( { issue: 'Test issue' } );
+      expect( feedback.issue ).toBe( 'Test issue' );
+      expect( feedback.suggestion ).toBeUndefined();
+      expect( feedback.reference ).toBeUndefined();
+      expect( feedback.priority ).toBeUndefined();
+    } );
+
+    it( 'creates feedback with all fields', () => {
+      const feedback = new EvaluationFeedback( {
+        issue: 'Critical bug',
+        suggestion: 'Fix immediately',
+        reference: 'BUG-123',
+        priority: 'critical'
+      } );
+      expect( feedback.issue ).toBe( 'Critical bug' );
+      expect( feedback.suggestion ).toBe( 'Fix immediately' );
+      expect( feedback.reference ).toBe( 'BUG-123' );
+      expect( feedback.priority ).toBe( 'critical' );
+    } );
+
+    it( 'accepts optional fields', () => {
+      const feedback = new EvaluationFeedback( {
+        issue: 'Minor issue',
+        suggestion: 'Consider fixing'
+      } );
+      expect( feedback.issue ).toBe( 'Minor issue' );
+      expect( feedback.suggestion ).toBe( 'Consider fixing' );
+      expect( feedback.reference ).toBeUndefined();
+      expect( feedback.priority ).toBeUndefined();
+    } );
+  } );
+
+  describe( 'static schema getter', () => {
+    it( 'validates required issue field', () => {
+      const ok = EvaluationFeedback.schema.safeParse( { issue: 'Test issue' } );
+      expect( ok.success ).toBe( true );
+
+      const bad = EvaluationFeedback.schema.safeParse( {} );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'validates issue must be string', () => {
+      const bad = EvaluationFeedback.schema.safeParse( { issue: 123 } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts optional suggestion field', () => {
+      const ok = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        suggestion: 'Fix it'
+      } );
+      expect( ok.success ).toBe( true );
+    } );
+
+    it( 'validates suggestion must be string if provided', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        suggestion: 123
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts optional reference field', () => {
+      const ok = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        reference: 'REF-123'
+      } );
+      expect( ok.success ).toBe( true );
+    } );
+
+    it( 'validates reference must be string if provided', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        reference: 123
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts valid priority enum values', () => {
+      const priorities = [ 'low', 'medium', 'high', 'critical' ];
+      for ( const priority of priorities ) {
+        const ok = EvaluationFeedback.schema.safeParse( {
+          issue: 'Test',
+          priority
+        } );
+        expect( ok.success ).toBe( true );
+      }
+    } );
+
+    it( 'rejects invalid priority values', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        priority: 'invalid'
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'validates priority must be string if provided', () => {
+      const bad = EvaluationFeedback.schema.safeParse( {
+        issue: 'Test',
+        priority: 123
+      } );
+      expect( bad.success ).toBe( false );
+    } );
+
+    it( 'accepts all fields together', () => {
+      const ok = EvaluationFeedback.schema.safeParse( {
+        issue: 'Critical bug',
+        suggestion: 'Fix immediately',
+        reference: 'BUG-123',
+        priority: 'critical'
+      } );
+      expect( ok.success ).toBe( true );
+    } );
   } );
 } );
 

package/src/interface/validations/static.js

@@ -17,6 +17,12 @@ const refineSchema = ( value, ctx ) => {
   } );
 };
 
+export const executeInParallelSchema = z.object( {
+  jobs: z.array( z.function() ),
+  concurrency: z.number().min( 1 ).or( z.literal( Infinity ) ),
+  onJobCompleted: z.function().optional()
+} );
+
 export const durationSchema = z.union( [ z.string().regex(
   /^(\d+)(ms|s|m|h|d)$/,
   'Expected duration like "500ms", "10s", "5m", "2h", or "1d"'
@@ -108,3 +114,13 @@ export function validateWorkflow( args ) {
 export function validateRequestPayload( args ) {
   validateAgainstSchema( httpRequestSchema, args );
 };
+
+/**
+ * Validate executeInParallel
+ *
+ * @param {object} args - The request arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateExecuteInParallel( args ) {
+  validateAgainstSchema( executeInParallelSchema, args );
+};

package/src/interface/validations/static.spec.js

@@ -1,6 +1,13 @@
 import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
-import { validateStep, validateWorkflow, validateRequestPayload, validateEvaluator, StaticValidationError } from './static.js';
+import {
+  validateStep,
+  validateWorkflow,
+  validateRequestPayload,
+  validateEvaluator,
+  validateExecuteInParallel,
+  StaticValidationError
+} from './static.js';
 
 const validArgs = Object.freeze( {
   name: 'valid_name',
@@ -259,4 +266,75 @@ describe( 'interface/validator', () => {
       expect( () => validateRequestPayload( request ) ).not.toThrow();
     } );
   } );
+
+  describe( 'validateExecuteInParallel', () => {
+    const validArgs = Object.freeze( {
+      jobs: [ () => {}, () => {} ],
+      concurrency: 5
+    } );
+
+    it( 'passes for valid args', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing concurrency', () => {
+      const error = new StaticValidationError( '✖ Invalid input\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs } ) ).toThrow( error );
+    } );
+
+    it( 'passes with onJobCompleted callback', () => {
+      const args = {
+        ...validArgs,
+        onJobCompleted: () => {}
+      };
+      expect( () => validateExecuteInParallel( args ) ).not.toThrow();
+    } );
+
+    it( 'passes with concurrency 1', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: 1 } ) ).not.toThrow();
+    } );
+
+    it( 'passes with concurrency Infinity', () => {
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: Infinity } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing jobs', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected array, received undefined\n  → at jobs' );
+      expect( () => validateExecuteInParallel( { concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-array jobs', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected array, received string\n  → at jobs' );
+      expect( () => validateExecuteInParallel( { jobs: 'not-array', concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'passes with empty jobs array', () => {
+      expect( () => validateExecuteInParallel( { jobs: [], concurrency: 5 } ) ).not.toThrow();
+    } );
+
+    it( 'rejects jobs array with non-function', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at jobs[1]' );
+      expect( () => validateExecuteInParallel( { jobs: [ () => {}, 'not-function' ], concurrency: 5 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-number concurrency', () => {
+      const error = new StaticValidationError( '✖ Invalid input\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs, concurrency: '5' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects zero concurrency', () => {
+      const error = new StaticValidationError( '✖ Too small: expected number to be >=1\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { jobs: validArgs.jobs, concurrency: 0 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects negative concurrency', () => {
+      const error = new StaticValidationError( '✖ Too small: expected number to be >=1\n  → at concurrency' );
+      expect( () => validateExecuteInParallel( { ...validArgs, concurrency: -1 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-function onJobCompleted', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at onJobCompleted' );
+      expect( () => validateExecuteInParallel( { ...validArgs, onJobCompleted: 'not-function' } ) ).toThrow( error );
+    } );
+  } );
 } );

package/src/interface/workflow_utils.js

@@ -0,0 +1,49 @@
+import { validateExecuteInParallel } from './validations/static.js';
+
+/**
+ * Execute jobs in parallel with optional concurrency limit.
+ *
+ * Returns all job results (successes and failures) sorted by original job index.
+ *
+ * @param {Array<Function>} jobs Array of functions to execute
+ * @param {Number} [concurrency] Max concurrent jobs, default is Infinity (no concurrency limit)
+ * @param {Function} [onJobCompleted] Optional callback invoked as each job completes
+ */
+export const executeInParallel = async ( { jobs, concurrency = Infinity, onJobCompleted } ) => {
+  validateExecuteInParallel( { jobs, concurrency, onJobCompleted } );
+  // allows this function to be called without testing over and over to check if it is not null;
+  const onJobCompletedSafeCb = onJobCompleted ?? ( _ => 0 );
+  const results = [];
+  const jobsCount = jobs.length;
+  const jobsPool = jobs.slice().map( ( job, index ) => ( {
+    index,
+    fn: async () => {
+      try {
+        const result = await job();
+        return { ok: true, result, index };
+      } catch ( error ) {
+        return { ok: false, error, index };
+      }
+    },
+    promise: null
+  } ) );
+
+  const activeJobs = jobsPool.splice( 0, concurrency );
+  activeJobs.forEach( job => job.promise = job.fn() ); // start jobs
+
+  while ( results.length < jobsCount ) {
+    const result = await Promise.race( activeJobs.map( job => job.promise ) );
+    results.push( result );
+    onJobCompletedSafeCb( result );
+
+    activeJobs.splice( activeJobs.findIndex( job => job.index === result.index ), 1 ); // remove completed job
+
+    if ( jobsPool.length > 0 ) {
+      const nextJob = jobsPool.shift();
+      nextJob.promise = nextJob.fn();
+      activeJobs.push( nextJob );
+    }
+  }
+
+  return results.sort( ( a, b ) => a.index - b.index );
+};

package/src/interface/workflow_utils.spec.js

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi } from 'vitest';
+import { executeInParallel } from './workflow_utils.js';
+
+describe( 'executeInParallel', () => {
+  it( 'returns empty array for empty jobs', async () => {
+    const results = await executeInParallel( { jobs: [] } );
+    expect( results ).toEqual( [] );
+  } );
+
+  it( 'executes all jobs and returns results', async () => {
+    const jobs = [
+      () => Promise.resolve( 'a' ),
+      () => Promise.resolve( 'b' ),
+      () => Promise.resolve( 'c' )
+    ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results ).toHaveLength( 3 );
+    expect( results ).toContainEqual( { ok: true, result: 'a', index: 0 } );
+    expect( results ).toContainEqual( { ok: true, result: 'b', index: 1 } );
+    expect( results ).toContainEqual( { ok: true, result: 'c', index: 2 } );
+  } );
+
+  it( 'handles job failures without throwing', async () => {
+    const error = new Error( 'job failed' );
+    const jobs = [
+      () => Promise.resolve( 'ok' ),
+      () => Promise.reject( error )
+    ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results ).toHaveLength( 2 );
+    expect( results ).toContainEqual( { ok: true, result: 'ok', index: 0 } );
+    expect( results ).toContainEqual( { ok: false, error, index: 1 } );
+  } );
+
+  it( 'handles all jobs failing', async () => {
+    const errors = [ new Error( 'e1' ), new Error( 'e2' ) ];
+    const jobs = [
+      () => Promise.reject( errors[0] ),
+      () => Promise.reject( errors[1] )
+    ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results ).toHaveLength( 2 );
+    expect( results ).toContainEqual( { ok: false, error: errors[0], index: 0 } );
+    expect( results ).toContainEqual( { ok: false, error: errors[1], index: 1 } );
+  } );
+
+  it( 'respects concurrency limit', async () => {
+    const tracker = { active: 0, max: 0 };
+
+    const createJob = ( id, delay ) => async () => {
+      tracker.active++;
+      tracker.max = Math.max( tracker.max, tracker.active );
+      await new Promise( r => setTimeout( r, delay ) );
+      tracker.active--;
+      return id;
+    };
+
+    const jobs = [
+      createJob( 'a', 50 ),
+      createJob( 'b', 50 ),
+      createJob( 'c', 50 ),
+      createJob( 'd', 50 )
+    ];
+
+    await executeInParallel( { jobs, concurrency: 2 } );
+
+    expect( tracker.max ).toBe( 2 );
+  } );
+
+  it( 'runs all jobs concurrently when concurrency is Infinity', async () => {
+    const tracker = { active: 0, max: 0 };
+
+    const createJob = delay => async () => {
+      tracker.active++;
+      tracker.max = Math.max( tracker.max, tracker.active );
+      await new Promise( r => setTimeout( r, delay ) );
+      tracker.active--;
+      return 'done';
+    };
+
+    const jobs = [ createJob( 30 ), createJob( 30 ), createJob( 30 ), createJob( 30 ) ];
+
+    await executeInParallel( { jobs } );
+
+    expect( tracker.max ).toBe( 4 );
+  } );
+
+  it( 'calls onJobCompleted for each job', async () => {
+    const onJobCompleted = vi.fn();
+    const jobs = [
+      () => Promise.resolve( 'a' ),
+      () => Promise.resolve( 'b' )
+    ];
+
+    await executeInParallel( { jobs, onJobCompleted } );
+
+    expect( onJobCompleted ).toHaveBeenCalledTimes( 2 );
+    expect( onJobCompleted ).toHaveBeenCalledWith( expect.objectContaining( { ok: true, result: 'a', index: 0 } ) );
+    expect( onJobCompleted ).toHaveBeenCalledWith( expect.objectContaining( { ok: true, result: 'b', index: 1 } ) );
+  } );
+
+  it( 'works without onJobCompleted callback', async () => {
+    const jobs = [ () => Promise.resolve( 'x' ) ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results ).toEqual( [ { ok: true, result: 'x', index: 0 } ] );
+  } );
+
+  it( 'handles synchronous job functions', async () => {
+    const jobs = [
+      () => 'sync-a',
+      () => 'sync-b'
+    ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results ).toContainEqual( { ok: true, result: 'sync-a', index: 0 } );
+    expect( results ).toContainEqual( { ok: true, result: 'sync-b', index: 1 } );
+  } );
+
+  it( 'handles synchronous throwing job functions', async () => {
+    const error = new Error( 'sync throw' );
+    const jobs = [
+      () => {
+        throw error;
+      }
+    ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results ).toEqual( [ { ok: false, error, index: 0 } ] );
+  } );
+
+  it( 'handles concurrency greater than job count', async () => {
+    const jobs = [ () => 'only-one' ];
+
+    const results = await executeInParallel( { jobs, concurrency: 10 } );
+
+    expect( results ).toEqual( [ { ok: true, result: 'only-one', index: 0 } ] );
+  } );
+
+  it( 'calls onJobCompleted in completion order, not submission order', async () => {
+    const completionOrder = [];
+    const onJobCompleted = result => completionOrder.push( result.index );
+
+    const jobs = [
+      async () => {
+        await new Promise( r => setTimeout( r, 60 ) );
+        return 'slow';
+      },
+      async () => {
+        await new Promise( r => setTimeout( r, 10 ) );
+        return 'fast';
+      }
+    ];
+
+    await executeInParallel( { jobs, onJobCompleted } );
+
+    expect( completionOrder ).toEqual( [ 1, 0 ] ); // fast (index 1) completes before slow (index 0)
+  } );
+
+  it( 'returns results sorted by job index for determinism', async () => {
+    const jobs = [
+      async () => {
+        await new Promise( r => setTimeout( r, 60 ) );
+        return 'slow';
+      },
+      async () => {
+        await new Promise( r => setTimeout( r, 10 ) );
+        return 'fast';
+      }
+    ];
+
+    const results = await executeInParallel( { jobs } );
+
+    expect( results[0].index ).toBe( 0 );
+    expect( results[1].index ).toBe( 1 );
+    expect( results ).toEqual( [
+      { ok: true, result: 'slow', index: 0 },
+      { ok: true, result: 'fast', index: 1 }
+    ] );
+  } );
+} );