@output.ai/core 0.0.16 → 0.1.0

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.16",
+  "version": "0.1.0",
   "description": "The core module of the output framework",
   "type": "module",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./tracing": {
+      "types": "./src/tracing/index.d.ts",
+      "import": "./src/tracing/index.js"
+    }
+  },
   "files": [
     "./src",
     "./bin"
@@ -30,6 +38,8 @@
     "#consts": "./src/consts.js",
     "#configs": "./src/configs.js",
     "#errors": "./src/errors.js",
+    "#tracing": "./src/tracing/index.js",
+    "#async_storage": "./src/async_storage.js",
     "#internal_activities": "./src/internal_activities/index.js"
   }
 }

package/src/configs.js

@@ -7,8 +7,7 @@ const envVarSchema = z.object( {
   TEMPORAL_NAMESPACE: z.string().optional().default( 'default' ),
   TEMPORAL_API_KEY: z.string().optional(),
   CATALOG_ID: z.string().regex( /^[a-z0-9_.@-]+$/i ),
-  API_AUTH_KEY: z.string().optional(),
-  TRACING_ENABLED: z.stringbool().optional()
+  API_AUTH_KEY: z.string().optional()
 } );
 
 const { data: safeEnvVar, error } = envVarSchema.safeParse( process.env );
@@ -30,7 +29,3 @@ export const worker = {
 export const api = {
   authKey: safeEnvVar.API_AUTH_KEY
 };
-
-export const tracing = {
-  enabled: safeEnvVar.TRACING_ENABLED
-};

package/src/configs.spec.js

@@ -181,38 +181,6 @@ describe( 'configs', () => {
         const { api } = await import( './configs.js' );
         expect( api.authKey ).toBeUndefined();
       } );
-
-      it( 'should handle TRACING_ENABLED when true', async () => {
-        process.env = {
-          TEMPORAL_ADDRESS: 'http://localhost:7233',
-          CATALOG_ID: 'test-catalog',
-          TRACING_ENABLED: 'true'
-        };
-
-        const { tracing } = await import( './configs.js' );
-        expect( tracing.enabled ).toBe( true );
-      } );
-
-      it( 'should handle TRACING_ENABLED when false', async () => {
-        process.env = {
-          TEMPORAL_ADDRESS: 'http://localhost:7233',
-          CATALOG_ID: 'test-catalog',
-          TRACING_ENABLED: 'false'
-        };
-
-        const { tracing } = await import( './configs.js' );
-        expect( tracing.enabled ).toBe( false );
-      } );
-
-      it( 'should handle missing TRACING_ENABLED', async () => {
-        process.env = {
-          TEMPORAL_ADDRESS: 'http://localhost:7233',
-          CATALOG_ID: 'test-catalog'
-        };
-
-        const { tracing } = await import( './configs.js' );
-        expect( tracing.enabled ).toBeUndefined();
-      } );
     } );
   } );
 
@@ -253,20 +221,6 @@ describe( 'configs', () => {
       } );
     } );
 
-    it( 'should export tracing config', async () => {
-      process.env = {
-        TEMPORAL_ADDRESS: 'http://localhost:7233',
-        CATALOG_ID: 'test-catalog',
-        TRACING_ENABLED: 'true'
-      };
-
-      const { tracing } = await import( './configs.js' );
-
-      expect( tracing ).toEqual( {
-        enabled: true
-      } );
-    } );
-
     it( 'should have correct static worker config values', async () => {
       process.env = {
         TEMPORAL_ADDRESS: 'http://localhost:7233',
@@ -361,11 +315,10 @@ describe( 'configs', () => {
         TEMPORAL_NAMESPACE: 'production',
         TEMPORAL_API_KEY: 'prod-api-key-123',
         CATALOG_ID: 'prod.catalog@v1',
-        API_AUTH_KEY: 'secure-auth-key',
-        TRACING_ENABLED: 'true'
+        API_AUTH_KEY: 'secure-auth-key'
       };
 
-      const { worker, api, tracing } = await import( './configs.js' );
+      const { worker, api } = await import( './configs.js' );
 
       expect( worker.address ).toBe( 'https://temporal.cloud.example.com' );
       expect( worker.namespace ).toBe( 'production' );
@@ -373,7 +326,6 @@ describe( 'configs', () => {
       expect( worker.catalogId ).toBe( 'prod.catalog@v1' );
       expect( worker.taskQueue ).toBe( 'prod.catalog@v1' );
       expect( api.authKey ).toBe( 'secure-auth-key' );
-      expect( tracing.enabled ).toBe( true );
     } );
   } );
 } );

package/src/consts.js

@@ -1,16 +1,7 @@
-export const SEND_WEBHOOK_ACTIVITY_NAME = '__internal#sendWebhookPost';
-export const READ_TRACE_FILE = '__internal#readTraceFile';
+export const ACTIVITY_SEND_WEBHOOK = '__internal#sendWebhook';
+export const ACTIVITY_READ_TRACE_FILE = '__internal#readTraceFile';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
-export const THIS_LIB_NAME = 'core';
-export const TraceEvent = {
-  WORKFLOW_START: 'workflow_start',
-  WORKFLOW_END: 'workflow_end',
-  STEP_START: 'step_start',
-  STEP_END: 'step_end',
-  EVALUATOR_START: 'evaluator_start',
-  EVALUATOR_END: 'evaluator_end'
-};
 export const ComponentType = {
   EVALUATOR: 'evaluator',
   INTERNAL_STEP: 'internal_step',

package/src/interface/step.js

@@ -16,6 +16,6 @@ export function step( { name, description, inputSchema, outputSchema, fn } ) {
     return output;
   };
 
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.EVALUATOR } );
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.STEP } );
   return wrapper;
 };

package/src/interface/webhook.js

@@ -1,18 +1,30 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { defineSignal, setHandler, proxyActivities, workflowInfo } from '@temporalio/workflow';
-import { SEND_WEBHOOK_ACTIVITY_NAME } from '#consts';
+import { defineSignal, setHandler, proxyActivities, workflowInfo, proxySinks } from '@temporalio/workflow';
+import { ACTIVITY_SEND_WEBHOOK } from '#consts';
+import { FatalError } from '#errors';
 import { validateCreateWebhook } from './validations/static.js';
 
 export async function createWebhook( { url, payload } ) {
   validateCreateWebhook( { url, payload } );
-  const workflowId = workflowInfo();
+  const { workflowId } = workflowInfo();
 
-  await proxyActivities( temporalActivityConfigs )[SEND_WEBHOOK_ACTIVITY_NAME]( { url, workflowId, payload } );
+  await proxyActivities( {
+    startToCloseTimeout: '3m',
+    retry: {
+      initialInterval: '15s',
+      maximumAttempts: 5,
+      nonRetryableErrorTypes: [ FatalError.name ]
+    }
+  } )[ACTIVITY_SEND_WEBHOOK]( { url, workflowId, payload } );
 
+  const sinks = await proxySinks();
   const resumeSignal = defineSignal( 'resume' );
 
+  const traceId = `${workflowId}-${url}-${Date.now()}`;
+  sinks.trace.addEventStart( { id: traceId, name: 'resume', kind: 'webhook' } );
   return new Promise( resolve =>
     setHandler( resumeSignal, responsePayload => {
+      sinks.trace.addEventEnd( { id: traceId, details: responsePayload } );
       resolve( responsePayload );
     } )
   );

package/src/interface/workflow.js

@@ -1,11 +1,11 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, ApplicationFailure, proxySinks } from '@temporalio/workflow';
+import { proxyActivities, inWorkflowContext, executeChild, workflowInfo } from '@temporalio/workflow';
 import { getInvocationDir } from './utils.js';
 import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '#errors';
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
-import { READ_TRACE_FILE, TraceEvent } from '#consts';
+import { ACTIVITY_READ_TRACE_FILE } from '#consts';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -23,62 +23,45 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
   const workflowPath = getInvocationDir();
 
   const steps = proxyActivities( temporalActivityConfigs );
-  const sinks = proxySinks();
 
   const wrapper = async input => {
-    try {
-      if ( inWorkflowContext() ) {
-        sinks.log.trace( { event: TraceEvent.WORKFLOW_START, input } );
-      }
-
-      validateWithSchema( inputSchema, input, `Workflow ${name} input` );
-
-      // this returns a plain function, for example, in unit tests
-      if ( !inWorkflowContext() ) {
-        const output = await fn( input );
-        validateWithSchema( outputSchema, output, `Workflow ${name} output` );
-        return output;
-      }
-
-      const { memo, workflowId } = workflowInfo();
-
-      Object.assign( workflowInfo().memo, { workflowPath } );
-
-      // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
-      const output = await fn.call( {
-        invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
-        invokeEvaluator: async ( evaluatorName, input ) => steps[`${workflowPath}#${evaluatorName}`]( input ),
+    validateWithSchema( inputSchema, input, `Workflow ${name} input` );
 
-        startWorkflow: async ( childName, input ) => {
+    // this returns a plain function, for example, in unit tests
+    if ( !inWorkflowContext() ) {
+      const output = await fn( input );
+      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+      return output;
+    }
 
-          // 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: name };
+    const { workflowId, memo } = workflowInfo();
 
-          return executeChild( childName, { args: input ? [ input ] : [], memo: workflowMemory } );
-        }
-      }, input );
+    // keep trace id and helm from memo if present (child workflow)
+    const traceId = memo.traceId ?? workflowId;
+    const traceHelm = memo.traceHelm ?? name;
 
-      validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+    Object.assign( memo, { traceId, traceHelm } );
 
-      sinks.log.trace( { event: TraceEvent.WORKFLOW_END, output } );
+    // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
+    const output = await fn.call( {
+      invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
+      invokeEvaluator: async ( evaluatorName, input ) => steps[`${workflowPath}#${evaluatorName}`]( input ),
 
-      // add trace if not child
-      if ( !memo.rootWorkflowId ) {
-        const trace = await steps[READ_TRACE_FILE]( { workflowType: name, workflowId } );
-        return { output, trace };
+      startWorkflow: async ( childName, input ) => {
+        return executeChild( childName, { args: input ? [ input ] : [], memo: { traceId, traceHelm, parentId: workflowId } } );
       }
+    }, input );
 
-      return output;
-    } 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 );
+    validateWithSchema( outputSchema, output, `Workflow ${name} output` );
+
+    // Adds trace file content to the output if it is the root workflow
+    // @TODO this will be replaced in favor of a persistent storage elsewhere
+    if ( !memo.parentId ) {
+      const trace = await steps[ACTIVITY_READ_TRACE_FILE]( { traceId, traceHelm } );
+      return { output, trace };
     }
+
+    return output;
   };
 
   setMetadata( wrapper, { name, description, inputSchema, outputSchema } );

package/src/internal_activities/index.js

@@ -15,7 +15,7 @@ const callerDir = process.argv[2];
  * @param {any} options.payload - The payload to send url
  * @throws {FatalError}
  */
-export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
+export const sendWebhook = async ( { url, workflowId, payload } ) => {
   const request = fetch( url, {
     method: 'POST',
     headers: {
@@ -33,41 +33,39 @@ export const sendWebhookPost = async ( { url, workflowId, payload } ) => {
     }
   } )();
 
-  console.log( '[Core.SendWebhookPost]', res.status, res.statusText );
+  console.log( '[Core.SendWebhook]', res.status, res.statusText );
 
   if ( !res.ok ) {
     throw new FatalError( `Webhook fail: ${res.status}` );
   }
 };
 
-setMetadata( sendWebhookPost, { type: ComponentType.INTERNAL_STEP } );
+setMetadata( sendWebhook, { type: ComponentType.INTERNAL_STEP } );
 
 /**
  * Read the trace file of a given execution and returns the content
  *
  * @param {object} options
- * @param {string} options.workflowType - The type of the workflow
- * @param {string} options.workflowId - The workflow execution id
+ * @param {string} options.traceId - The is of the trace
+ * @param {string} options.traceHelm - The helm of the trace file
  * @returns {string[]} Each line of the trace file
  */
-export const readTraceFile = async ( { workflowType, workflowId } ) => {
-  const dir = join( callerDir, 'logs', 'runs', workflowType );
+export const readTraceFile = async ( { traceId, traceHelm } ) => {
+  const dir = join( callerDir, 'logs', 'runs', traceHelm );
 
   if ( !existsSync( dir ) ) {
     console.log( '[Core.ReadTraceFile]', 'Trace folder not found', dir );
     return [];
   }
 
-  const suffix = `-${workflowId}.raw`;
-  const matchingFile = readdirSync( dir ).find( f => f.endsWith( suffix ) );
+  const fileName = readdirSync( dir ).find( f => f.endsWith( `-${traceId}.raw` ) );
 
-  if ( !matchingFile ) {
-    console.log( '[Core.ReadTraceFile]', 'Trace file not found', dir, suffix );
+  if ( !fileName ) {
+    console.log( '[Core.ReadTraceFile]', 'Trace file not found', { traceId, traceHelm } );
     return [];
   }
 
-  const file = join( dir, matchingFile );
-  return existsSync( file ) ? readFileSync( file, 'utf-8' ).split( '\n' ) : [];
+  return readFileSync( join( dir, fileName ), 'utf-8' ).split( '\n' );
 };
 
 setMetadata( readTraceFile, { type: ComponentType.INTERNAL_STEP, skipTrace: true } );

package/src/tracing/index.d.ts

@@ -0,0 +1,47 @@
+/*
+╭───────────╮
+│ T R A C E │╮
+╰───────────╯│
+ ╰───────────╯
+*/
+
+/**
+ * The public namespace for tracing
+ *
+ * @namespace
+ */
+export declare const Tracing: {
+
+  /**
+   * Adds the start phase of a new event at the default trace for the current workflow.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventStart( args: { id: string; kind: string; name: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Adds the end phase at an event at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventEnd( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * Adds the error phase at an event as error at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventError( args: { id: string; details: any } ): void; // eslint-disable-line @typescript-eslint/no-explicit-any
+};

package/src/tracing/index.js

@@ -0,0 +1,154 @@
+import { Storage } from '#async_storage';
+import { mkdirSync, existsSync, readdirSync, appendFileSync } from 'node:fs';
+import { join } from 'path';
+import { EOL } from 'os';
+import { buildLogTree } from './tracer_tree.js';
+import { serializeError } from './utils.js';
+
+const callerDir = process.argv[2];
+// It is is isolated here instead of #configs to allow this module to be exported without all other configs requirements
+const tracingEnabled = [ '1', 'true', 'on' ].includes( process.env.TRACING_ENABLED );
+
+/**
+ * Trace nomenclature
+ *
+ * Trace - The collection of Events;
+ * Event - Any entry in the Trace file, must have the two phases START and END or ERROR;
+ * Phase - An specific part of an Event, either START or the conclusive END or ERROR;
+ */
+
+/**
+ * Adds the Trace Event Phase to the trace file
+ *
+ * @param {string} phase - The phase
+ * @param {object} options - All the trace fields
+ * @returns {void}
+ */
+function addEventPhase( phase, { kind, details, id, name, parentId, traceId, traceHelm } ) {
+  if ( !tracingEnabled || name === 'catalog' ) {
+    return;
+  }
+
+  const parsedDetails = details instanceof Error ? serializeError( details ) : details;
+  const timestamp = Date.now();
+  const entry = { phase, kind, details: parsedDetails, id, name, timestamp, parentId };
+  const outputDir = join( callerDir, 'logs', 'runs', traceHelm );
+
+  if ( !existsSync( outputDir ) ) {
+    mkdirSync( outputDir, { recursive: true } );
+  }
+
+  const suffix = `-${traceId}.raw`;
+  const logFile = readdirSync( outputDir ).find( f => f.endsWith( suffix ) ) ?? `${new Date( timestamp ).toISOString()}-${suffix}`;
+  const logPath = join( outputDir, logFile );
+
+  appendFileSync( logPath, JSON.stringify( entry ) + EOL, 'utf-8' );
+  buildLogTree( logPath );
+};
+
+/**
+ * Internal use only
+ *
+ * Adds the start phase of a new event at the default trace for the current workflow.
+ *
+ * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+ * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+ * @param {string} parentId - The parent Event, used to build a three.
+ * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
+ * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
+ * @returns {void}
+ */
+export const addEventStart = options => addEventPhase( 'start', options );
+
+/**
+ * Internal use only
+ *
+ * Adds the end phase at an event at the default trace for the current workflow.
+ *
+ * It needs to use the same id of the start phase.
+ *
+ * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+ * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+ * @param {string} parentId - The parent Event, used to build a three.
+ * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
+ * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
+ * @returns {void}
+ */
+export const addEventEnd = options => addEventPhase( 'end', options );
+
+/**
+ * Internal use only
+ *
+ * Adds the error phase at an event as error at the default trace for the current workflow.
+ *
+ * It needs to use the same id of the start phase.
+ *
+ * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+ * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+ * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+ * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+ * @param {string} parentId - The parent Event, used to build a three.
+ * @param {string} traceId - The traceId, which identifies from which trace this Event belongs.
+ * @param {string} traceHelm - The trace helm, which is a taxonomical naming of the Trace.
+ * @returns {void}
+ */
+export const addEventError = options => addEventPhase( 'error', options );
+
+/**
+ * Adds an Event Phase reading traceId, traceHelm and parentId from the context.
+ *
+ * @param {object} options - The common trace configurations
+ */
+function addEventPhaseWithContext( phase, options ) {
+  const storeContent = Storage.load();
+  if ( !storeContent ) { // means this was called from a unit test
+    return;
+  }
+  const { parentId, traceId, traceHelm } = storeContent;
+  addEventPhase( phase, { ...options, parentId, traceId, traceHelm } );
+};
+
+/**
+ * The public namespace for tracing
+ *
+ * @namespace
+ */
+export const Tracing = {
+
+  /**
+   * Adds the start phase of a new event at the default trace for the current workflow.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {string} kind - The kind of Event, like HTTP, DiskWrite, DBOp, etc.
+   * @param {string} name - The human friendly name of the Event: eg: query, request, create.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventStart: ( { id, kind, name, details } ) => addEventPhaseWithContext( 'start', { kind, name, details, id } ),
+
+  /**
+   * Adds the end phase at an event at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventEnd: ( { id, details } ) => addEventPhaseWithContext( 'end', { id, details } ),
+
+  /**
+   * Adds the error phase at an event as error at the default trace for the current workflow.
+   *
+   * It needs to use the same id of the start phase.
+   *
+   * @param {string} id - A unique id for the Event, must be the same across all phases: start, end, error.
+   * @param {any} details - All details attached to this Event Phase. Eg: DB queried records, HTTP response body.
+   * @returns {void}
+   */
+  addEventError: ( { id, details } ) => addEventPhaseWithContext( 'error', { id, details } )
+};

package/src/tracing/index.private.spec.js

@@ -0,0 +1,84 @@
+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';
+
+const createTempDir = () => mkdtempSync( join( tmpdir(), 'output-sdk-trace-' ) );
+
+// Use env var to enable tracing
+
+vi.mock( '#async_storage', () => ( { Storage: { load: () => ( { parentId: undefined, traceId: 'trace-1', traceHelm: 'tests' } ) } } ) );
+vi.mock( 'path', async importActual => {
+  const actual = await importActual();
+  return { ...actual, join: ( first, ...rest ) => actual.join( first ?? process.cwd(), ...rest ) };
+} );
+vi.mock( './tracer_tree.js', () => ( { buildLogTree: vi.fn() } ) );
+
+describe( 'tracing private exports', () => {
+  beforeEach( () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    vi.setSystemTime( new Date( '2020-01-01T00:00:00.000Z' ) );
+    process.env.TRACING_ENABLED = '1';
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+    delete process.env.TRACING_ENABLED;
+  } );
+
+  it( 'addEventStart (private) writes start', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { addEventStart } = await import( './index.js?v=private1' );
+    addEventStart( { id: 'a', kind: 'evaluator', name: 'start', details: { foo: 1 }, traceId: 'trace-1', traceHelm: 'tests' } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const entry = JSON.parse( raw.split( EOL )[0] );
+    expect( entry.phase ).toBe( 'start' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'addEventEnd (private) writes end', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { addEventEnd } = await import( './index.js?v=private2' );
+    addEventEnd( { id: 'a', details: { ok: true }, traceId: 'trace-1', traceHelm: 'tests' } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const entry = JSON.parse( raw.split( EOL )[0] );
+    expect( entry.phase ).toBe( 'end' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+
+  it( 'addEventError (private) writes error', async () => {
+    const originalArgv2 = process.argv[2];
+    const tmp = createTempDir();
+    process.argv[2] = tmp;
+
+    const { addEventError } = await import( './index.js?v=private3' );
+    addEventError( { id: 'a', details: new Error( 'oops' ), traceId: 'trace-1', traceHelm: 'tests' } );
+
+    const { buildLogTree } = await import( './tracer_tree.js' );
+    const logPath = buildLogTree.mock.calls[0][0];
+    const raw = readFileSync( logPath, 'utf-8' );
+    const entry = JSON.parse( raw.split( EOL )[0] );
+    expect( entry.phase ).toBe( 'error' );
+
+    rmSync( tmp, { recursive: true, force: true } );
+    process.argv[2] = originalArgv2;
+  } );
+} );