@output.ai/core 0.0.16 → 0.1.1

package/src/tracing/processors/s3/index.js

@@ -0,0 +1,51 @@
+import { upload } from './s3_client.js';
+import { getRedisClient } from './redis_client.js';
+import buildTraceTree from '../../tools/build_trace_tree.js';
+import { EOL } from 'node:os';
+
+const oneMonthInSeconds = 60 * 60 * 24 * 30;
+
+const accumulate = async ( { entry, executionContext: { workflowName, workflowId } } ) => {
+  const key = `traces/${workflowName}/${workflowId}`;
+  const transaction = ( await getRedisClient() ).multi();
+
+  transaction.zAdd( key, [
+    { score: entry.timestamp, value: JSON.stringify( entry ) }
+  ], { NX: true } );
+  transaction.expire( key, oneMonthInSeconds, 'GT' );
+  transaction.zRange( key, 0, -1 );
+  const [ ,, zList ] = await transaction.exec();
+  return zList.map( v => JSON.parse( v ) );
+};
+
+const getS3Key = ( { startTime, workflowId, workflowName } ) => {
+  const isoDate = new Date( startTime ).toISOString();
+  const [ year, month, day ] = isoDate.split( /\D/, 3 );
+  const timeStamp = isoDate.replace( /[:T.]/g, '-' );
+  return `${workflowName}/${year}/${month}/${day}/${timeStamp}_${workflowId}.json`;
+};
+
+/**
+ * Init this processor
+ */
+export const init = async () => {
+  await getRedisClient();
+};
+
+/**
+ * Execute this processor: send a complete trace tree file to S3 when the workflow finishes
+ *
+ * @param {object} args
+ * @param {object} entry - Trace event phase
+ * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ */
+export const exec = async ( { entry, executionContext } ) => {
+  const { workflowName, workflowId, startTime } = executionContext;
+  const content = buildTraceTree( await accumulate( { entry, executionContext } ) );
+
+  const isRootWorkflowEnd = !entry.parentId && entry.phase !== 'start';
+  return isRootWorkflowEnd ? upload( {
+    key: getS3Key( { workflowId, workflowName, startTime } ),
+    content: JSON.stringify( content, undefined, 2 ) + EOL
+  } ) : 0;
+};

package/src/tracing/processors/s3/index.spec.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const redisMulti = {
+  zAdd: vi.fn().mockReturnThis(),
+  expire: vi.fn().mockReturnThis(),
+  zRange: vi.fn().mockReturnThis(),
+  exec: vi.fn()
+};
+const getRedisClientMock = vi.fn( async () => ( { multi: () => redisMulti } ) );
+vi.mock( './redis_client.js', () => ( { getRedisClient: getRedisClientMock } ) );
+
+const uploadMock = vi.fn();
+vi.mock( './s3_client.js', () => ( { upload: uploadMock } ) );
+
+const buildTraceTreeMock = vi.fn( entries => ( { count: entries.length } ) );
+vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMock } ) );
+
+describe( 'tracing/processors/s3', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    process.env.TRACE_REMOTE_S3_BUCKET = 'bkt';
+  } );
+
+  it( 'init(): ensures redis client is created', async () => {
+    const { init } = await import( './index.js' );
+    await init();
+    expect( getRedisClientMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'exec(): accumulates via redis, uploads only on root workflow end', async () => {
+    const { exec } = await import( './index.js' );
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    // Redis will return progressively larger sorted sets
+    redisMulti.exec
+      .mockResolvedValueOnce( [ , , [ JSON.stringify( { name: 'A', phase: 'start', timestamp: startTime } ) ] ] )
+      .mockResolvedValueOnce( [ , , [
+        JSON.stringify( { name: 'A', phase: 'start', timestamp: startTime } ),
+        JSON.stringify( { name: 'A', phase: 'tick', timestamp: startTime + 1 } )
+      ] ] )
+      .mockResolvedValueOnce( [ , , [
+        JSON.stringify( { name: 'A', phase: 'start', timestamp: startTime } ),
+        JSON.stringify( { name: 'A', phase: 'tick', timestamp: startTime + 1 } ),
+        JSON.stringify( { name: 'A', phase: 'end', timestamp: startTime + 2 } )
+      ] ] );
+
+    await exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime, parentId: 'root' } } );
+    await exec( { ...ctx, entry: { name: 'A', phase: 'tick', timestamp: startTime + 1, parentId: 'root' } } );
+    // Root end: no parentId and not start
+    await exec( { ...ctx, entry: { name: 'A', phase: 'end', timestamp: startTime + 2 } } );
+
+    // Accumulation happened 3 times
+    expect( redisMulti.zAdd ).toHaveBeenCalledTimes( 3 );
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 3 );
+
+    // Only last call triggers upload
+    expect( uploadMock ).toHaveBeenCalledTimes( 1 );
+    const { key, content } = uploadMock.mock.calls[0][0];
+    expect( key ).toMatch( /^WF\/2020\/01\/02\// );
+    expect( JSON.parse( content.trim() ).count ).toBe( 3 );
+  } );
+} );
+

package/src/tracing/processors/s3/redis_client.js

@@ -0,0 +1,19 @@
+import { createClient } from 'redis';
+import { throws } from '#utils';
+
+const state = { client: null };
+
+/**
+ * Return a connected Redis instance
+ * @returns {redis.RedisClientType}
+ */
+export async function getRedisClient() {
+  const url = process.env.REDIS_URL ?? throws( new Error( 'Missing REDIS_URL environment variable' ) );
+  if ( await state.client?.ping().catch( _ => 0 ) === 'PONG' ) {
+    return state.client;
+  };
+
+  const client = createClient( { url, socket: { keepAlive: 15000 } } );
+  await client.connect();
+  return state.client = client;
+};

package/src/tracing/processors/s3/redis_client.spec.js

@@ -0,0 +1,50 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock( '#utils', () => ( {
+  throws: e => {
+    throw e;
+  }
+} ) );
+
+const createClientImpl = vi.fn();
+vi.mock( 'redis', () => ( { createClient: opts => createClientImpl( opts ) } ) );
+
+async function loadModule() {
+  vi.resetModules();
+  return import( './redis_client.js' );
+}
+
+describe( 'tracing/processors/s3/redis_client', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    delete process.env.REDIS_URL;
+  } );
+
+  it( 'throws if REDIS_URL is missing', async () => {
+    const { getRedisClient } = await loadModule();
+    await expect( getRedisClient() ).rejects.toThrow( 'Missing REDIS_URL' );
+  } );
+
+  it( 'creates client with url, connects once, then reuses cached when ping is PONG', async () => {
+    process.env.REDIS_URL = 'redis://localhost:6379';
+
+    const pingMock = vi.fn().mockResolvedValue( 'PONG' );
+    const connectMock = vi.fn().mockResolvedValue();
+    const created = [];
+    createClientImpl.mockImplementation( opts => {
+      created.push( opts );
+      return { connect: connectMock, ping: pingMock };
+    } );
+
+    const { getRedisClient } = await loadModule();
+
+    const c1 = await getRedisClient();
+    const c2 = await getRedisClient();
+
+    expect( created ).toHaveLength( 1 );
+    expect( connectMock ).toHaveBeenCalledTimes( 1 );
+    expect( pingMock ).toHaveBeenCalledTimes( 1 );
+    expect( c1 ).toBe( c2 );
+    expect( created[0] ).toMatchObject( { url: 'redis://localhost:6379', socket: { keepAlive: 15000 } } );
+  } );
+} );

package/src/tracing/processors/s3/s3_client.js

@@ -0,0 +1,33 @@
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { throws } from '#utils';
+
+const state = { s3Client: null };
+
+/**
+ * Return a S3 Client instance
+ * @returns {S3Client}
+ */
+const getS3Client = () => {
+  if ( state.s3Client ) {
+    return state.s3Client;
+  }
+
+  const region = process.env.AWS_REGION ?? throws( new Error( 'Missing AWS_REGION env var' ) );
+  const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY ?? throws( new Error( 'Missing AWS_SECRET_ACCESS_KEY env var' ) );
+  const accessKeyId = process.env.AWS_ACCESS_KEY_ID ?? throws( new Error( 'Missing AWS_ACCESS_KEY_ID env var' ) );
+
+  return state.s3Client = new S3Client( { region, secretAccessKey, accessKeyId } );
+};
+
+/**
+ * Upload given file to S3
+ * @param {object} args
+ * @param {string} key - S3 file key
+ * @param {string} content - File content
+ */
+export const upload = ( { key, content } ) =>
+  getS3Client().send( new PutObjectCommand( {
+    Bucket: process.env.TRACE_REMOTE_S3_BUCKET ?? throws( new Error( 'Missing TRACE_REMOTE_S3_BUCKET env var' ) ),
+    Key: key,
+    Body: content
+  } ) );

package/src/tracing/processors/s3/s3_client.spec.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock( '#utils', () => ( {
+  throws: e => {
+    throw e;
+  }
+} ) );
+
+const sendMock = vi.fn();
+const ctorState = { args: null };
+class S3ClientMock {
+  constructor( args ) {
+    ctorState.args = args;
+  } send = sendMock;
+}
+class PutObjectCommandMock {
+  constructor( input ) {
+    this.input = input;
+  }
+}
+
+vi.mock( '@aws-sdk/client-s3', () => ( {
+  S3Client: S3ClientMock,
+  PutObjectCommand: PutObjectCommandMock
+} ) );
+
+async function loadModule() {
+  vi.resetModules();
+  return import( './s3_client.js' );
+}
+
+describe( 'tracing/processors/s3/s3_client', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    delete process.env.AWS_REGION;
+    delete process.env.AWS_SECRET_ACCESS_KEY;
+    delete process.env.AWS_ACCESS_KEY_ID;
+    delete process.env.TRACE_REMOTE_S3_BUCKET;
+  } );
+
+  it( 'fails fast when required env vars are missing for client creation', async () => {
+    const { upload } = await loadModule();
+    expect( () => upload( { key: 'k', content: 'c' } ) ).toThrow();
+  } );
+
+  it( 'creates client once with env and uploads with bucket/key/content', async () => {
+    process.env.AWS_REGION = 'us-east-1';
+    process.env.AWS_SECRET_ACCESS_KEY = 'sek';
+    process.env.AWS_ACCESS_KEY_ID = 'id';
+    process.env.TRACE_REMOTE_S3_BUCKET = 'bucket';
+
+    const { upload } = await loadModule();
+
+    await upload( { key: 'wf/key.json', content: '{"a":1}' } );
+
+    expect( ctorState.args ).toEqual( { region: 'us-east-1', secretAccessKey: 'sek', accessKeyId: 'id' } );
+    expect( sendMock ).toHaveBeenCalledTimes( 1 );
+    const cmd = sendMock.mock.calls[0][0];
+    expect( cmd ).toBeInstanceOf( PutObjectCommandMock );
+    expect( cmd.input ).toEqual( { Bucket: 'bucket', Key: 'wf/key.json', Body: '{"a":1}' } );
+
+    // subsequent upload uses cached client
+    await upload( { key: 'wf/key2.json', content: '{}' } );
+    expect( sendMock ).toHaveBeenCalledTimes( 2 );
+  } );
+} );
+

package/src/tracing/tools/build_trace_tree.js

@@ -0,0 +1,76 @@
+/**
+ * @typedef {object} NodeEntry
+ * @property {string} id
+ * @property {string} kind
+ * @property {string} name
+ * @property {number} startedAt
+ * @property {number} endedAt
+ * @property {object} [input]
+ * @property {object} [output]
+ * @property {object} [error]
+ * @property {NodeTree[]} children
+ */
+/**
+ * Create a node entry for the tree.
+ *
+ * Properties are sorted the way they should be in the final file, as this makes it easier to read.
+ *
+ * @param {string} id - Node id
+ * @returns {NodeEntry} The entry without any values
+ */
+const createEntry = id => ( {
+  id,
+  kind: '',
+  name: '',
+  startedAt: 0,
+  endedAt: 0,
+  input: undefined,
+  output: undefined,
+  error: undefined,
+  children: []
+} );
+
+/**
+ * Build a tree of nodes from a list of entries
+ *
+ * Each node will have: id, name, kind, children, input, output or error, startedAt, endedAt.
+ *
+ * Entries with same id will be combined according to their phase (start, end OR error).
+ * - The details of the start phase becomes input, timestamp becomes startedAt;
+ * - The details of the end phase become output, timestamp becomes endedAt;
+ * - The details of the error phase become error, timestamp becomes endedAt;
+ * - Only start phase's kind and name are used;
+ *
+ *
+ * Children are added according to the parentId of each entry.
+ * The result tree has a single root: the only node without parentId, normally the workflow itself.
+ *
+ * @param {object[]} entries - The list of entries
+ * @returns {void}
+ */
+export default entries => {
+  const nodes = new Map();
+  const ensureNode = id => nodes.get( id ) ?? nodes.set( id, createEntry( id ) ).get( id );
+
+  for ( const entry of entries ) {
+    const { kind, id, name, parentId, details, phase, timestamp } = entry;
+    const node = ensureNode( id );
+
+    if ( phase === 'start' ) {
+      Object.assign( node, { input: details, startedAt: timestamp, kind, name } );
+    } else if ( phase === 'end' ) {
+      Object.assign( node, { output: details, endedAt: timestamp } );
+    } else if ( phase === 'error' ) {
+      Object.assign( node, { error: details, endedAt: timestamp } );
+    }
+
+    if ( parentId && phase === 'start' ) {
+      const parent = ensureNode( parentId );
+      parent.children.push( node );
+      parent.children.sort( ( a, b ) => a.startedAt - b.startedAt );
+    }
+  }
+
+  const root = nodes.get( entries.find( e => !e.parentId ).id );
+  return root;
+};

package/src/tracing/tools/build_trace_tree.spec.js

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import buildLogTree from './build_trace_tree.js';
+
+describe( 'build_trace_tree', () => {
+  it( 'builds a tree from workflow/step/IO entries with grouping and sorting', () => {
+    const entries = [
+      // workflow start
+      { kind: 'workflow', phase: 'start', name: 'wf', id: 'wf', parentId: undefined, details: { a: 1 }, timestamp: 1000 },
+      // evaluator start/stop
+      { kind: 'evaluator', phase: 'start', name: 'eval', id: 'eval', parentId: 'wf', details: { z: 0 }, timestamp: 1500 },
+      { kind: 'evaluator', phase: 'end', name: 'eval', id: 'eval', parentId: 'wf', details: { z: 1 }, timestamp: 1600 },
+      // step1 start
+      { kind: 'step', phase: 'start', name: 'step-1', id: 's1', parentId: 'wf', details: { x: 1 }, timestamp: 2000 },
+      // IO under step1
+      { kind: 'IO', phase: 'start', name: 'test-1', id: 'io1', parentId: 's1', details: { y: 2 }, timestamp: 2300 },
+      // step2 start
+      { kind: 'step', phase: 'start', name: 'step-2', id: 's2', parentId: 'wf', details: { x: 2 }, timestamp: 2400 },
+      // IO under step2
+      { kind: 'IO', phase: 'start', name: 'test-2', id: 'io2', parentId: 's2', details: { y: 3 }, timestamp: 2500 },
+      { kind: 'IO', phase: 'end', name: 'test-2', id: 'io2', parentId: 's2', details: { y: 4 }, timestamp: 2600 },
+      // IO under step1 ends
+      { kind: 'IO', phase: 'end', name: 'test-1', id: 'io1', parentId: 's1', details: { y: 5 }, timestamp: 2700 },
+      // step1 end
+      { kind: 'step', phase: 'end', name: 'step-1', id: 's1', parentId: 'wf', details: { done: true }, timestamp: 2800 },
+      // step2 end
+      { kind: 'step', phase: 'end', name: 'step-2', id: 's2', parentId: 'wf', details: { done: true }, timestamp: 2900 },
+      // workflow end
+      { kind: 'workflow', phase: 'end', name: 'wf', id: 'wf', parentId: undefined, details: { ok: true }, timestamp: 3000 }
+    ];
+
+    const result = buildLogTree( entries );
+
+    const expected = {
+      id: 'wf',
+      kind: 'workflow',
+      name: 'wf',
+      startedAt: 1000,
+      endedAt: 3000,
+      input: { a: 1 },
+      output: { ok: true },
+      children: [
+        {
+          id: 'eval',
+          kind: 'evaluator',
+          name: 'eval',
+          startedAt: 1500,
+          endedAt: 1600,
+          input: { z: 0 },
+          output: { z: 1 },
+          children: []
+        },
+        {
+          id: 's1',
+          kind: 'step',
+          name: 'step-1',
+          startedAt: 2000,
+          endedAt: 2800,
+          input: { x: 1 },
+          output: { done: true },
+          children: [
+            {
+              id: 'io1',
+              kind: 'IO',
+              name: 'test-1',
+              startedAt: 2300,
+              endedAt: 2700,
+              input: { y: 2 },
+              output: { y: 5 },
+              children: []
+            }
+          ]
+        },
+        {
+          id: 's2',
+          kind: 'step',
+          name: 'step-2',
+          startedAt: 2400,
+          endedAt: 2900,
+          input: { x: 2 },
+          output: { done: true },
+          children: [
+            {
+              id: 'io2',
+              kind: 'IO',
+              name: 'test-2',
+              startedAt: 2500,
+              endedAt: 2600,
+              input: { y: 3 },
+              output: { y: 4 },
+              children: []
+            }
+          ]
+        }
+      ]
+    };
+
+    expect( result ).toMatchObject( expected );
+  } );
+} );

package/src/tracing/tools/utils.js

@@ -0,0 +1,28 @@
+/**
+ * @typedef {object} SerializedError
+ * @property {string} name - The error constructor name
+ * @property {string} message - The error message
+ * @property {string} stack - The error stack trace
+ */
+
+/**
+ * Serialize an error object.
+ *
+ * If it has ".cause", recursive serialize its cause until finally found an error without it.
+ *
+ * @param {Error} error
+ * @returns {SerializedError}
+ */
+export const serializeError = error =>
+  error.cause ? serializeError( error.cause ) : {
+    name: error.constructor.name,
+    message: error.message,
+    stack: error.stack
+  };
+
+/**
+ * Returns true if string value is stringbool and true
+ * @param {string} v
+ * @returns
+ */
+export const isStringboolTrue = v => [ '1', 'true', 'on' ].includes( v );

package/src/tracing/tools/utils.spec.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { serializeError } from './utils.js';
+
+describe( 'tracing/utils', () => {
+  it( 'serializeError unwraps causes and keeps message/stack', () => {
+    const inner = new Error( 'inner' );
+    const outer = new Error( 'outer', { cause: inner } );
+
+    const out = serializeError( outer );
+    expect( out.name ).toBe( 'Error' );
+    expect( out.message ).toBe( 'inner' );
+    expect( typeof out.stack ).toBe( 'string' );
+  } );
+} );

package/src/tracing/trace_engine.js

@@ -0,0 +1,63 @@
+import { Storage } from '#async_storage';
+import { EventEmitter } from 'node:events';
+import { serializeError, isStringboolTrue } from './tools/utils.js';
+import * as localProcessor from './processors/local/index.js';
+import * as s3Processor from './processors/s3/index.js';
+
+const traceBus = new EventEmitter();
+const processors = [
+  {
+    isOn: isStringboolTrue( process.env.TRACE_LOCAL_ON ),
+    init: localProcessor.init,
+    exec: localProcessor.exec
+  },
+  {
+    isOn: isStringboolTrue( process.env.TRACE_REMOTE_ON ),
+    init: s3Processor.init,
+    exec: s3Processor.exec
+  }
+];
+
+/**
+ * Starts processors based on env vars and attach them to the main bus to listen trace events
+ */
+export const init = async () => {
+  for ( const p of processors.filter( p => p.isOn ) ) {
+    await p.init();
+    traceBus.addListener( 'entry', p.exec );
+  }
+};
+
+/**
+ * Serialize details of an event
+ */
+const serializeDetails = details => details instanceof Error ? serializeError( details ) : details;
+
+/**
+ * Creates a new trace event phase and sens to be written
+ *
+ * @param {string} phase - The phase
+ * @param {object} fields - All the trace fields
+ * @returns {void}
+ */
+export const addEventPhase = ( phase, { kind, name, id, parentId, details, executionContext } ) =>
+  traceBus.emit( 'entry', {
+    executionContext,
+    entry: { kind, phase, name, id, parentId, phase, timestamp: Date.now(), details: serializeDetails( details ) }
+  } );
+
+/**
+ * Adds an Event Phase, complementing the options with parentId and executionContext from the async storage.
+ *
+ * This function will have no effect if called from outside an Temporal Workflow/Activity environment,
+ * so it is safe to be used on unit tests or any dependencies that might be used elsewhere
+ *
+ * @param {object} options - The common trace configurations
+ */
+export function addEventPhaseWithContext( phase, options ) {
+  const storeContent = Storage.load();
+  if ( storeContent ) { // If there is no storageContext this was not called from an Temporal Environment
+    const { parentId, executionContext } = storeContent;
+    addEventPhase( phase, { ...options, parentId, executionContext } );
+  }
+};

package/src/tracing/trace_engine.spec.js

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const storageLoadMock = vi.fn();
+vi.mock( '#async_storage', () => ( {
+  Storage: { load: storageLoadMock }
+} ) );
+
+const localInitMock = vi.fn( async () => {} );
+const localExecMock = vi.fn();
+vi.mock( './processors/local/index.js', () => ( {
+  init: localInitMock,
+  exec: localExecMock
+} ) );
+
+const s3InitMock = vi.fn( async () => {} );
+const s3ExecMock = vi.fn();
+vi.mock( './processors/s3/index.js', () => ( {
+  init: s3InitMock,
+  exec: s3ExecMock
+} ) );
+
+async function loadTraceEngine() {
+  vi.resetModules();
+  return import( './trace_engine.js' );
+}
+
+describe( 'tracing/trace_engine', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    delete process.env.TRACE_LOCAL_ON;
+    delete process.env.TRACE_REMOTE_ON;
+    storageLoadMock.mockReset();
+  } );
+
+  it( 'init() starts only enabled processors and attaches listeners', async () => {
+    process.env.TRACE_LOCAL_ON = '1';
+    process.env.TRACE_REMOTE_ON = '0';
+    const { init, addEventPhase } = await loadTraceEngine();
+
+    await init();
+
+    expect( localInitMock ).toHaveBeenCalledTimes( 1 );
+    expect( s3InitMock ).not.toHaveBeenCalled();
+
+    addEventPhase( 'start', { kind: 'step', name: 'N', id: '1', parentId: 'p', details: { ok: true } } );
+    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
+    const payload = localExecMock.mock.calls[0][0];
+    expect( payload.entry.name ).toBe( 'N' );
+    expect( payload.entry.kind ).toBe( 'step' );
+    expect( payload.entry.phase ).toBe( 'start' );
+    expect( payload.entry.details ).toEqual( { ok: true } );
+  } );
+
+  it( 'addEventPhase() emits an entry consumed by processors', async () => {
+    process.env.TRACE_LOCAL_ON = 'on';
+    const { init, addEventPhase } = await loadTraceEngine();
+    await init();
+
+    addEventPhase( 'end', { kind: 'workflow', name: 'W', id: '2', parentId: 'p2', details: 'done' } );
+    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
+    const payload = localExecMock.mock.calls[0][0];
+    expect( payload.entry.name ).toBe( 'W' );
+    expect( payload.entry.phase ).toBe( 'end' );
+    expect( payload.entry.details ).toBe( 'done' );
+  } );
+
+  it( 'addEventPhaseWithContext() uses storage when available', async () => {
+    process.env.TRACE_LOCAL_ON = 'true';
+    storageLoadMock.mockReturnValue( { parentId: 'ctx-p', executionContext: { runId: 'r1' } } );
+    const { init, addEventPhaseWithContext } = await loadTraceEngine();
+    await init();
+
+    addEventPhaseWithContext( 'tick', { kind: 'step', name: 'S', id: '3', details: 1 } );
+    expect( localExecMock ).toHaveBeenCalledTimes( 1 );
+    const payload = localExecMock.mock.calls[0][0];
+    expect( payload.executionContext ).toEqual( { runId: 'r1' } );
+    expect( payload.entry.parentId ).toBe( 'ctx-p' );
+    expect( payload.entry.name ).toBe( 'S' );
+    expect( payload.entry.phase ).toBe( 'tick' );
+  } );
+
+  it( 'addEventPhaseWithContext() is a no-op when storage is absent', async () => {
+    process.env.TRACE_LOCAL_ON = '1';
+    storageLoadMock.mockReturnValue( undefined );
+    const { init, addEventPhaseWithContext } = await loadTraceEngine();
+    await init();
+
+    addEventPhaseWithContext( 'noop', { kind: 'step', name: 'X', id: '4', details: null } );
+    expect( localExecMock ).not.toHaveBeenCalled();
+  } );
+} );

package/src/utils.js

@@ -0,0 +1,8 @@
+/**
+ * Throw given error
+ * @param {Error} e
+ * @throws {e}
+ */
+export const throws = e => {
+  throw e;
+};