@output.ai/core 0.0.8 → 0.0.10

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

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { validateStep, validateWorkflow, validateCreateWebhook, StaticValidationError } from './static.js';
+
+const validArgs = Object.freeze( {
+  name: 'valid_name',
+  description: 'desc',
+  inputSchema: { type: 'object' },
+  outputSchema: { type: 'object' },
+  fn: () => {}
+} );
+
+describe( 'interface/validator', () => {
+  describe( 'validateStep', () => {
+    it( 'passes for valid args', () => {
+      expect( () => validateStep( { ...validArgs } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing name', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received undefined\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: undefined } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-string name', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received number\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: 123 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateStep( { ...validArgs, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-string description', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received number\n  → at description' );
+      expect( () => validateStep( { ...validArgs, description: 10 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-object inputSchema', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected object, received string\n  → at inputSchema' );
+      expect( () => validateStep( { ...validArgs, inputSchema: 'not-an-object' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid inputSchema structure', () => {
+      const error = new StaticValidationError( '✖ data/type must be equal to one of the allowed values, \
+data/type must be array, data/type must match a schema in anyOf\n  → at inputSchema' );
+      expect( () => validateStep( { ...validArgs, inputSchema: { type: 1 } } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-object outputSchema', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected object, received number\n  → at outputSchema' );
+      expect( () => validateStep( { ...validArgs, outputSchema: 10 } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid outputSchema structure', () => {
+      const error = new StaticValidationError( '✖ data/type must be equal to one of the allowed values, \
+data/type must be array, data/type must match a schema in anyOf\n  → at outputSchema' );
+      expect( () => validateStep( { ...validArgs, outputSchema: { type: 1 } } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateStep( { ...validArgs, fn: undefined } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-function fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received string\n  → at fn' );
+      expect( () => validateStep( { ...validArgs, fn: 'not-fn' } ) ).toThrow( error );
+    } );
+  } );
+
+  describe( 'validateWorkflow', () => {
+    it( 'passes for valid args', () => {
+      expect( () => validateWorkflow( { ...validArgs } ) ).not.toThrow();
+    } );
+  } );
+
+  describe( 'validate webhook', () => {
+    it( 'passes with valid http url', () => {
+      expect( () => validateCreateWebhook( { url: 'http://example.com' } ) ).not.toThrow();
+    } );
+
+    it( 'passes with valid https url', () => {
+      expect( () => validateCreateWebhook( { url: 'https://example.com/path?q=1' } ) ).not.toThrow();
+    } );
+
+    it( 'rejects missing url', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected string, received undefined\n  → at url' );
+      expect( () => validateCreateWebhook( { } ) ).toThrow( error );
+    } );
+
+    it( 'rejects invalid scheme', () => {
+      const error = new StaticValidationError( '✖ Invalid URL\n  → at url' );
+      expect( () => validateCreateWebhook( { url: 'ftp://example.com' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects malformed url', () => {
+      const error = new StaticValidationError( '✖ Invalid URL\n  → at url' );
+      expect( () => validateCreateWebhook( { url: 'http:////' } ) ).toThrow( error );
+    } );
+  } );
+} );

package/src/interface/webhook.js

@@ -1,8 +1,10 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
 import { defineSignal, setHandler, proxyActivities, workflowInfo } from '@temporalio/workflow';
 import { SEND_WEBHOOK_ACTIVITY_NAME } from '#consts';
+import { validateCreateWebhook } from './validations/static.js';
 
 export async function createWebhook( { url, payload } ) {
+  validateCreateWebhook( { url, payload } );
   const workflowId = workflowInfo();
 
   await proxyActivities( temporalActivityConfigs )[SEND_WEBHOOK_ACTIVITY_NAME]( { url, workflowId, payload } );

package/src/interface/workflow.js

@@ -1,8 +1,10 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, inWorkflowContext, executeChild, workflowInfo } from '@temporalio/workflow';
-import { getInvocationDir } from './utils.js';
+import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, ApplicationFailure } from '@temporalio/workflow';
+import { getInvocationDir, invokeFnAndValidateOutputPreservingExecutionModel } from './utils.js';
 import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '../errors.js';
+import { validateWorkflow } from './validations/static.js';
+import { validateWorkflowInput, validateWorkflowOutput } from './validations/runtime.js';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -16,32 +18,55 @@ const temporalActivityConfigs = {
 };
 
 export function workflow( { name, description, inputSchema, outputSchema, fn } ) {
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn } );
   const workflowPath = getInvocationDir();
 
   const steps = proxyActivities( temporalActivityConfigs );
 
   const wrapper = async input => {
-    // this returns a plain function, for example, in unit tests
-    if ( !inWorkflowContext() ) { return fn( input ); }
+    try {
+      if ( inputSchema ) {
+        validateWorkflowInput( name, inputSchema, input );
+      }
+
+      // this returns a plain function, for example, in unit tests
+      if ( !inWorkflowContext() ) {
+        if ( outputSchema ) {
+          return invokeFnAndValidateOutputPreservingExecutionModel( fn, input, validateWorkflowOutput.bind( null, name, outputSchema ) );
+        }
+        return fn( input );
+      }
+
+      Object.assign( workflowInfo().memo, { workflowPath } );
 
-    Object.assign( workflowInfo().memo, { workflowPath } );
+      // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
+      const boundFn = fn.bind( {
+        invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
 
-    // call the function with custom context
-    return fn.call( {
-      invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
+        startWorkflow: async ( name, input ) => {
+          const { memo, workflowId, workflowType } = workflowInfo();
 
-      startWorkflow: async ( name, input ) => {
-        const { memo, workflowId, workflowType } = workflowInfo();
+          // Checks if current memo has rootWorkflowId, which means current execution is already a child
+          // Then it sets the memory for the child execution passing along who's the original workflow is and its type
+          const workflowMemory = memo.rootWorkflowId ?
+            { parentWorkflowId: workflowId, rootWorkflowType: memo.rootWorkflowType, rootWorkflowId: memo.rootWorkflowId } :
+            { parentWorkflowId: workflowId, rootWorkflowId: workflowId, rootWorkflowType: workflowType };
 
-        // Checks if current memo has rootWorkflowId, which means current execution is already a child
-        // Then it sets the memory for the child execution passing along who's the original workflow is and its type
-        const workflowMemory = memo.rootWorkflowId ?
-          { parentWorkflowId: workflowId, rootWorkflowType: memo.rootWorkflowType, rootWorkflowId: memo.rootWorkflowId } :
-          { parentWorkflowId: workflowId, rootWorkflowId: workflowId, rootWorkflowType: workflowType };
+          return executeChild( name, { args: input ? [ input ] : [], memo: workflowMemory } );
+        }
+      } );
 
-        return executeChild( name, { args: input ? [ input ] : [], memo: workflowMemory } );
+      if ( outputSchema ) {
+        return invokeFnAndValidateOutputPreservingExecutionModel( boundFn, input, validateWorkflowOutput.bind( null, name, outputSchema ) );
       }
-    }, input );
+      return boundFn( input );
+    } catch ( error ) {
+      /*
+       * Any errors in the workflow will interrupt its execution since the workflow is designed to orchestrate and
+       * IOs should be made in steps
+       */
+      throw new ApplicationFailure( error.message, error.constructor.name );
+    }
   };
 
   setMetadata( wrapper, { name, description, inputSchema, outputSchema } );

package/src/worker/index.js

@@ -15,7 +15,7 @@ const __dirname = dirname( fileURLToPath( import.meta.url ) );
 // expose the coreTracker so other parts of the SDK can use it
 setupGlobalTracer();
 
-const { address, apiKey, maxActivities, maxWorkflows, namespace, taskQueue } = workerConfig;
+const { address, apiKey, maxActivities, maxWorkflows, namespace, taskQueue, catalogId } = workerConfig;
 
 // Get caller directory from command line arguments
 const callerDir = process.argv[2];
@@ -53,8 +53,12 @@ const callerDir = process.argv[2];
     maxConcurrentActivityTaskExecutions: maxActivities,
     bundlerOptions: {
       webpackConfigHook: config => {
-        if ( !config.module ) { config.module = { }; }
-        if ( !config.module.rules ) { config.module.rules = []; }
+        if ( !config.module ) {
+          config.module = { };
+        }
+        if ( !config.module.rules ) {
+          config.module.rules = [];
+        }
         // Use AST-based loader for rewriting steps/workflows
         config.module.rules.push( {
           test: /\.js$/,
@@ -71,7 +75,7 @@ const callerDir = process.argv[2];
   console.log( '[Core]', 'Starting catalog workflow...' );
   await new Client( { connection, namespace } ).workflow.start( 'catalog', {
     taskQueue,
-    workflowId: taskQueue, // use the name of the task queue as the catalog name, ensuring uniqueness
+    workflowId: catalogId, // use the name of the task queue as the catalog name, ensuring uniqueness
     workflowIdConflictPolicy: WorkflowIdConflictPolicy.TERMINATE_EXISTING,
     args: [ catalog ]
   } );

package/src/worker/interceptors/activity.js

@@ -3,6 +3,7 @@ import { Storage } from '../async_storage.js';
 import { trace } from '../tracer/index.js';
 import { TraceEvent } from '../tracer/types.js';
 import { headersToObject } from '../sandboxed_utils.js';
+import { THIS_LIB_NAME } from '#consts';
 
 /*
   This interceptor is called for every activity execution
@@ -19,9 +20,9 @@ export class ActivityExecutionInterceptor {
     const context = { workflowId, workflowType, activityId, activityType, ...headersToObject( input.headers ) };
 
     return Storage.runWithContext( async _ => {
-      trace( { lib: 'core', event: TraceEvent.STEP_START, input: input.args } );
+      trace( { lib: THIS_LIB_NAME, event: TraceEvent.STEP_START, input: input.args } );
       const output = await next( input );
-      trace( { lib: 'core', event: TraceEvent.STEP_END, output } );
+      trace( { lib: THIS_LIB_NAME, event: TraceEvent.STEP_END, output } );
       return output;
     }, context );
   }

package/src/worker/internal_utils.js

@@ -16,7 +16,9 @@ import { writeFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
  * */
 export function recursiveNavigateWhileCollecting( path, filenames, collection = [], ignoreDirNames = [ 'vendor', 'node_modules' ] ) {
   for ( const entry of readdirSync( path, { withFileTypes: true } ) ) {
-    if ( ignoreDirNames.includes( entry.name ) ) { continue; }
+    if ( ignoreDirNames.includes( entry.name ) ) {
+      continue;
+    }
 
     const pathname = resolve( path, entry.name );
     if ( entry.isDirectory() ) {
@@ -38,7 +40,9 @@ export async function *iteratorOverImportedComponents( paths ) {
     const imported = await import( url );
     for ( const component of Object.values( imported ) ) {
       const metadata = component[METADATA_ACCESS_SYMBOL];
-      if ( !metadata ) { continue; }
+      if ( !metadata ) {
+        continue;
+      }
       yield { component, metadata, path, pathname };
     }
   }
@@ -49,6 +53,8 @@ export async function *iteratorOverImportedComponents( paths ) {
  */
 export function writeFileOnLocationSync( path, content ) {
   const targetDir = path.split( '/' ).slice( 0, -1 ).join( '/' );
-  if ( targetDir && !existsSync( targetDir ) ) { mkdirSync( targetDir, { recursive: true } ); }
+  if ( targetDir && !existsSync( targetDir ) ) {
+    mkdirSync( targetDir, { recursive: true } );
+  }
   writeFileSync( path, content, 'utf-8' );
 };

package/src/worker/sinks.js

@@ -1,5 +1,6 @@
 import { Storage } from './async_storage.js';
 import { trace } from './tracer/index.js';
+import { THIS_LIB_NAME } from '#consts';
 
 export const sinks = {
   // This sink allow for sandbox Temporal environment to send trace logs back to the main thread.
@@ -7,7 +8,7 @@ export const sinks = {
     trace: {
       fn( workflowInfo, args ) {
         const { workflowId, workflowType, memo } = workflowInfo;
-        Storage.runWithContext( _ => trace( { lib: 'core', ...args } ), { workflowId, workflowType, ...memo } );
+        Storage.runWithContext( _ => trace( { lib: THIS_LIB_NAME, ...args } ), { workflowId, workflowType, ...memo } );
       },
       callDuringReplay: false
     }

package/src/worker/tracer/index.js

@@ -7,12 +7,35 @@ import { tracing as tracingConfig } from '#configs';
 
 const callerDir = process.argv[2];
 
+/**
+ * Appends new information to a file
+ *
+ * Information has to be a JSON
+ *
+ * File is encoded in utf-8
+ *
+ * @param {string} path - The full filename
+ * @param {object} json - The content
+ */
 const flushEntry = ( path, json ) => appendFileSync( path, JSON.stringify( json ) + EOL, 'utf-8' );
 
-export function trace( { lib, event, input, output } ) {
+/**
+ * Add an event to the execution trace file.
+ *
+ * Events normally are the result of an operation, either a function call or an IO.
+ *
+ * @param {object} options
+ * @param {string} options.lib - The macro part of the platform that triggered the event
+ * @param {string} options.event - The name of the event
+ * @param {any} [options.input] - The input of the operation
+ * @param {any} [options.output] - The output of the operation
+ */
+export function trace( { lib, event, input = undefined, output = undefined } ) {
   const now = Date.now();
 
-  if ( !tracingConfig.enabled ) { return; }
+  if ( !tracingConfig.enabled ) {
+    return;
+  }
 
   const {
     activityId: stepId,
@@ -29,7 +52,9 @@ export function trace( { lib, event, input, output } ) {
 
   // test for rootWorkflow to append to the same file as the parent/grandparent
   const outputDir = join( callerDir, 'logs', 'runs', rootWorkflowType ?? workflowType );
-  if ( !existsSync( outputDir ) ) { mkdirSync( outputDir, { recursive: true } ); }
+  if ( !existsSync( outputDir ) ) {
+    mkdirSync( outputDir, { recursive: true } );
+  }
 
   const suffix = `-${rootWorkflowId ?? workflowId}.raw`;
   const logFile = readdirSync( outputDir ).find( f => f.endsWith( suffix ) ) ?? `${new Date( now ).toISOString()}-${suffix}`;
@@ -39,5 +64,12 @@ export function trace( { lib, event, input, output } ) {
   buildLogTree( logPath );
 };
 
+/**
+ * Setup the global tracer function, so it is available to be used by other libraries
+ *
+ * It will be situated in the global object, under Symbol.for('__trace')
+ *
+ * @returns {object} The assigned globalThis
+ */
 export const setupGlobalTracer = () =>
   Object.defineProperty( globalThis, Symbol.for( '__trace' ), { value: trace, writable: false, enumerable: false, configurable: false } );

package/src/worker/tracer/index.test.js

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir, EOL } from 'node:os';
+import { join } from 'path';
+import { THIS_LIB_NAME } from '#consts';
+
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'flow-sdk-trace-' ) );
+
+// Single mocks (configured per-test by mutating the backing objects)
+const mockConfig = { tracing: { enabled: false } };
+vi.mock( '#configs', () => mockConfig );
+
+const mockStorageData = {
+  activityId: 's1',
+  activityType: 'Step 1',
+  workflowId: 'wf1',
+  workflowType: 'prompt',
+  workflowPath: '/workflows/prompt.js',
+  parentWorkflowId: undefined,
+  rootWorkflowId: undefined,
+  rootWorkflowType: undefined
+};
+vi.mock( '../async_storage.js', () => ( {
+  Storage: { load: () => mockStorageData }
+} ) );
+
+vi.mock( './tracer_tree.js', () => ( { buildLogTree: vi.fn() } ) );
+
+describe( 'tracer/index', () => {
+  beforeEach( () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    vi.setSystemTime( new Date( '2020-01-01T00:00:00.000Z' ) );
+
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+  } );
+
+  it( 'writes a raw log entry and calls buildLogTree (mocked)', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    mockConfig.tracing.enabled = true;
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const { trace } = await import( './index.js' );
+
+    const input = { foo: 1 };
+    trace( { lib: THIS_LIB_NAME, event: 'workflow_start', input, output: null } );
+
+    expect( buildLogTree ).toHaveBeenCalledTimes( 1 );
+    const logPath = buildLogTree.mock.calls[0][0];
+
+    const raw = readFileSync( logPath, 'utf-8' );
+    const [ firstLine ] = raw.split( EOL );
+    const entry = JSON.parse( firstLine );
+
+    expect( entry ).toMatchObject( {
+      lib: THIS_LIB_NAME,
+      event: 'workflow_start',
+      input,
+      output: null,
+      stepId: 's1',
+      stepName: 'Step 1',
+      workflowId: 'wf1',
+      workflowType: 'prompt',
+      workflowPath: '/workflows/prompt.js'
+    } );
+    expect( typeof entry.timestamp ).toBe( 'number' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'does nothing when tracing is disabled', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    mockConfig.tracing.enabled = false;
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const { trace } = await import( './index.js' );
+
+    trace( { lib: THIS_LIB_NAME, event: 'workflow_start', input: {}, output: null } );
+
+    expect( buildLogTree ).not.toHaveBeenCalled();
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'setupGlobalTracer installs global symbol', async () => {
+    mockConfig.tracing.enabled = false;
+    const { setupGlobalTracer } = await import( './index.js' );
+    setupGlobalTracer();
+    const sym = Symbol.for( '__trace' );
+    expect( typeof globalThis[sym] ).toBe( 'function' );
+  } );
+} );

package/src/worker/tracer/tracer_tree.js

@@ -1,16 +1,40 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { EOL } from 'os';
 import { TraceEvent } from './types.js';
+import { THIS_LIB_NAME } from '#consts';
 
-const timestampAscSort = ( a, b ) => a.timestamp > b.timestamp ? -1 : 1;
+/**
+ * Sorting function that compares two objects and ASC sort them by either .startedAt or, if not present, .timestamp
+ *
+ * @param {object} a
+ * @param {object} b
+ * @returns {number} The sorting result [1,-1]
+ */
+const timestampAscSort = ( a, b ) => {
+  if ( a.startedAt ) {
+    return a.startedAt > b.startedAt ? 1 : 1;
+  }
+  return a.timestamp > b.timestamp ? 1 : -1;
+};
 
+/**
+ * Add a member to an array an sort it. It is a mutating method.
+ *
+ * @param {array} arr - The arr to be changed
+ * @param {any} entry - The entry to be added
+ * @param {Function} sorter - The sort function to be used (within .filter)
+ */
 const pushSort = ( arr, entry, sorter ) => {
   arr.push( entry );
   arr.sort( sorter );
 };
 
-const coreLib = 'core';
-
+/**
+ * Transform the trace file into a tree of events, where nested events are represented as children of parent events.
+ * And the events STEP_START/STEP_END and WORKFLOW_START/WORKFLOW_END are combined into single events with start and end timestamps.
+ *
+ * @param {string} src - The trace src filename
+ */
 export const buildLogTree = src => {
   const content = readFileSync( src, 'utf-8' );
   const entries = content.split( EOL ).slice( 0, -1 ).map( c => JSON.parse( c ) );
@@ -19,7 +43,7 @@ export const buildLogTree = src => {
   const workflowsMap = new Map();
 
   // close steps/workflows
-  for ( const entry of entries.filter( e => e.lib === coreLib ) ) {
+  for ( const entry of entries.filter( e => e.lib === THIS_LIB_NAME ) ) {
     const { event, workflowId, workflowType, workflowPath, parentWorkflowId, stepId, stepName, input, output, timestamp } = entry;
 
     const baseEntry = { children: [], startedAt: timestamp, workflowId };
@@ -41,7 +65,7 @@ export const buildLogTree = src => {
   }
 
   // insert operations inside steps
-  for ( const entry of entries.filter( e => e.lib !== coreLib ) ) {
+  for ( const entry of entries.filter( e => e.lib !== THIS_LIB_NAME ) ) {
     pushSort( stepsMap.get( `${entry.workflowId}:${entry.stepId}` ).children, entry, timestampAscSort );
   }
 

package/src/worker/tracer/tracer_tree.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'path';
+import { EOL } from 'os';
+import { buildLogTree } from './tracer_tree.js';
+import { TraceEvent } from './types.js';
+import { THIS_LIB_NAME } from '#consts';
+
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'flow-sdk-trace-tree-' ) );
+
+describe( 'tracer/tracer_tree', () => {
+  it( 'builds a tree JSON from a raw log file', () => {
+    const tmp = createTempDir();
+    const rawPath = join( tmp, 'run-123.raw' );
+
+    const entries = [
+      // root workflow start
+      {
+        lib: THIS_LIB_NAME,
+        event: TraceEvent.WORKFLOW_START,
+        input: { a: 1 },
+        output: null,
+        timestamp: 1000,
+        stepId: undefined,
+        stepName: undefined,
+        workflowId: 'wf1',
+        workflowType: 'prompt',
+        workflowPath: '/workflows/prompt.js',
+        parentWorkflowId: undefined
+      },
+      // step start
+      {
+        lib: THIS_LIB_NAME,
+        event: TraceEvent.STEP_START,
+        input: { x: 1 },
+        output: null,
+        timestamp: 2000,
+        stepId: 's1',
+        stepName: 'Step 1',
+        workflowId: 'wf1',
+        workflowType: 'prompt',
+        workflowPath: '/workflows/prompt.js',
+        parentWorkflowId: undefined
+      },
+      // non-core operation within step
+      {
+        lib: 'tool',
+        event: 'call',
+        input: { y: 2 },
+        output: { y: 3 },
+        timestamp: 3000,
+        stepId: 's1',
+        stepName: 'Step 1',
+        workflowId: 'wf1'
+      },
+      // step end
+      {
+        lib: THIS_LIB_NAME,
+        event: TraceEvent.STEP_END,
+        input: null,
+        output: { done: true },
+        timestamp: 4000,
+        stepId: 's1',
+        stepName: 'Step 1',
+        workflowId: 'wf1',
+        workflowType: 'prompt',
+        workflowPath: '/workflows/prompt.js',
+        parentWorkflowId: undefined
+      },
+      // workflow end
+      {
+        lib: THIS_LIB_NAME,
+        event: TraceEvent.WORKFLOW_END,
+        input: null,
+        output: { ok: true },
+        timestamp: 5000,
+        stepId: undefined,
+        stepName: undefined,
+        workflowId: 'wf1',
+        workflowType: 'prompt',
+        workflowPath: '/workflows/prompt.js',
+        parentWorkflowId: undefined
+      }
+    ];
+
+    writeFileSync( rawPath, entries.map( e => JSON.stringify( e ) ).join( EOL ) + EOL, 'utf-8' );
+
+    buildLogTree( rawPath );
+
+    const tree = JSON.parse( readFileSync( rawPath.replace( /.raw$/, '.json' ), 'utf-8' ) );
+
+    expect( tree.event ).toBe( 'workflow' );
+    expect( tree.workflowId ).toBe( 'wf1' );
+    expect( tree.workflowType ).toBe( 'prompt' );
+    expect( tree.startedAt ).toBe( 1000 );
+    expect( tree.endedAt ).toBe( 5000 );
+    expect( tree.output ).toEqual( { ok: true } );
+    expect( Array.isArray( tree.children ) ).toBe( true );
+    expect( tree.children.length ).toBe( 1 );
+
+    const step = tree.children[0];
+    expect( step.event ).toBe( 'step' );
+    expect( step.stepId ).toBe( 's1' );
+    expect( step.startedAt ).toBe( 2000 );
+    expect( step.endedAt ).toBe( 4000 );
+    expect( step.output ).toEqual( { done: true } );
+    expect( step.children.length ).toBe( 1 );
+    expect( step.children[0].lib ).toBe( 'tool' );
+    expect( step.children[0].timestamp ).toBe( 3000 );
+
+    rmSync( tmp, { recursive: true, force: true } );
+  } );
+} );
+