@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/durable/schemas/factory.js

@@ -3,8 +3,7 @@
  *********** HOTMESH 'DURABLE' MODULE APPLICATION GRAPH **********
  *
  * This HotMesh application spec uses 50 activities and 25 transitions
- * to model and emulate the Temporal Application & Query servers using
- * a pluggable backend.
+ * to model a durable workflow engine using a pluggable backend.
  *
  * This YAML file can also serve as a useful starting point for building
  * Integration/BPM/Workflow servers in general (MuleSoft, etc) without the need
@@ -20,7 +19,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APP_ID = exports.APP_VERSION = exports.getWorkflowYAML = void 0;
-const APP_VERSION = '8';
+const APP_VERSION = '11';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'durable';
 exports.APP_ID = APP_ID;
@@ -77,6 +76,9 @@ const getWorkflowYAML = (app, version) => {
             backoffCoefficient:
               description: the time multiple in seconds to backoff before retrying
               type: number
+            initialInterval:
+              description: the initial interval in seconds before the first retry
+              type: number
             maximumAttempts:
               description: the maximum number of retries to attempt before failing the workflow
               type: number
@@ -184,10 +186,14 @@ const getWorkflowYAML = (app, version) => {
             maps:
               originJobId: '{trigger.output.data.originJobId}'
               workflowId: '{trigger.output.data.workflowId}'
-              arguments: '{trigger.output.data.arguments}'
+              arguments:
+                '@pipe':
+                  - ['{cycle_hook.output.data.continueArgs}', '{trigger.output.data.arguments}']
+                  - ['{@conditional.nullish}']
               workflowTopic: '{trigger.output.data.workflowTopic}'
               workflowName: '{trigger.output.data.workflowName}'
               expire: '{trigger.output.data.expire}'
+              continueGeneration: '{cycle_hook.output.data.continueGeneration}'
               canRetry:
                 '@pipe':
                   - '@pipe':
@@ -305,6 +311,19 @@ const getWorkflowYAML = (app, version) => {
                   index:
                     type: number
                     description: the replay index (COUNTER++)
+            592:
+              schema:
+                type: object
+                properties:
+                  arguments:
+                    type: array
+                    description: the arguments to pass to the restarted workflow
+                    items:
+                      type: any
+                  index:
+                    type: number
+                  workflowDimension:
+                    type: string
             595:
               schema:
                 type: object
@@ -320,6 +339,7 @@ const getWorkflowYAML = (app, version) => {
           job:
             maps:
               response: '{$self.output.data.response}'
+              patch-marker[-]: '{$self.output.data.patchMarkers}'
 
         sleeper:
           title: Pauses the main thread for a set amount of time; all other subprocess threads remain active, and new ones may be started
@@ -345,6 +365,8 @@ const getWorkflowYAML = (app, version) => {
             maps:
               retryCount: 0
               throttleSeconds: 0
+              continueGeneration: '{cycle_hook.output.data.continueGeneration}'
+              continueArgs: '{cycle_hook.output.data.continueArgs}'
 
         childer:
           title: Awaits a child flow to be executed/started
@@ -409,6 +431,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
                   - ['{@conditional.nullish}', 10]
                   - ['{@conditional.nullish}']
+              initialInterval:
+                '@pipe':
+                  - ['{worker.output.data.initialInterval}','{trigger.output.data.initialInterval}']
+                  - ['{@conditional.nullish}', 1]
+                  - ['{@conditional.nullish}']
               maximumAttempts:
                 '@pipe':
                   - ['{worker.output.data.maximumAttempts}','{trigger.output.data.maximumAttempts}']
@@ -520,12 +547,17 @@ const getWorkflowYAML = (app, version) => {
                   - '@pipe':
                     - '@pipe':
                       - '@pipe':
-                        - ['{trigger.output.data.backoffCoefficient}', 10]
-                        - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{trigger.output.data.backoffCoefficient}', 10]
+                          - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{cycle_hook.output.data.retryCount}', 0]
+                          - ['{@conditional.nullish}']
+                        - ['{@math.pow}']
                       - '@pipe':
-                        - ['{cycle_hook.output.data.retryCount}', 0]
+                        - ['{trigger.output.data.initialInterval}', 1]
                         - ['{@conditional.nullish}']
-                      - ['{@math.pow}']
+                      - ['{@math.multiply}']
                     - '@pipe':
                       - ['{trigger.output.data.maximumInterval}', 120]
                       - ['{@logical.or}']
@@ -533,6 +565,8 @@ const getWorkflowYAML = (app, version) => {
                   - '@pipe':
                     - [0]
                   - ['{@conditional.ternary}']
+              continueGeneration: '{cycle_hook.output.data.continueGeneration}'
+              continueArgs: '{cycle_hook.output.data.continueArgs}'
 
         proxyer:
           title: Invokes the activity flow and awaits the response
@@ -558,6 +592,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                headers:
+                  type: object
+                  description: optional metadata to pass alongside activity arguments
                 expire:
                   type: number
                 backoffCoefficient:
@@ -566,9 +603,12 @@ const getWorkflowYAML = (app, version) => {
                   type: number
                 maximumInterval:
                   type: number
+                startToCloseTimeout:
+                  type: number
             maps:
               activityName: '{worker.output.data.activityName}'
               arguments: '{worker.output.data.arguments}'
+              headers: '{worker.output.data.headers}'
               workflowDimension: '{worker.output.data.workflowDimension}'
               index: '{worker.output.data.index}'
               originJobId: '{worker.output.data.originJobId}'
@@ -576,11 +616,17 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{worker.output.data.workflowId}'
               workflowTopic: '{worker.output.data.workflowTopic}'
               expire: '{worker.output.data.expire}'
+              startToCloseTimeout: '{worker.output.data.startToCloseTimeout}'
               backoffCoefficient:
                 '@pipe':
                   - ['{worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
                   - ['{@conditional.nullish}', 10]
                   - ['{@conditional.nullish}']
+              initialInterval:
+                '@pipe':
+                  - ['{worker.output.data.initialInterval}','{trigger.output.data.initialInterval}']
+                  - ['{@conditional.nullish}', 1]
+                  - ['{@conditional.nullish}']
               maximumAttempts:
                 '@pipe':
                   - ['{worker.output.data.maximumAttempts}','{trigger.output.data.maximumAttempts}']
@@ -664,12 +710,17 @@ const getWorkflowYAML = (app, version) => {
                   - '@pipe':
                     - '@pipe':
                       - '@pipe':
-                        - ['{trigger.output.data.backoffCoefficient}', 10]
-                        - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{trigger.output.data.backoffCoefficient}', 10]
+                          - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{cycle_hook.output.data.retryCount}', 0]
+                          - ['{@conditional.nullish}']
+                        - ['{@math.pow}']
                       - '@pipe':
-                        - ['{cycle_hook.output.data.retryCount}', 0]
+                        - ['{trigger.output.data.initialInterval}', 1]
                         - ['{@conditional.nullish}']
-                      - ['{@math.pow}']
+                      - ['{@math.multiply}']
                     - '@pipe':
                       - ['{trigger.output.data.maximumInterval}', 120]
                       - ['{@logical.or}']
@@ -677,6 +728,8 @@ const getWorkflowYAML = (app, version) => {
                   - '@pipe':
                     - [0]
                   - ['{@conditional.ternary}']
+              continueGeneration: '{cycle_hook.output.data.continueGeneration}'
+              continueArgs: '{cycle_hook.output.data.continueArgs}'
 
         collator:
           title: Awaits the collator flow to simultaneously resolve the idempotent items and return as a sequential set
@@ -780,6 +833,8 @@ const getWorkflowYAML = (app, version) => {
             maps:
               retryCount: 0
               throttleSeconds: 0
+              continueGeneration: '{cycle_hook.output.data.continueGeneration}'
+              continueArgs: '{cycle_hook.output.data.continueArgs}'
 
         retryer:
           title: Cycles back to the cycle_hook pivot, increasing the retryCount (the exponential)
@@ -806,6 +861,24 @@ const getWorkflowYAML = (app, version) => {
                     - ['{trigger.output.data.maximumInterval}', 120]
                     - ['{@logical.or}']
                   - ['{@math.min}']
+              continueGeneration: '{cycle_hook.output.data.continueGeneration}'
+              continueArgs: '{cycle_hook.output.data.continueArgs}'
+
+        continuer:
+          title: Cycles back to cycle_hook after continueAsNew, resetting execution with new arguments
+          type: cycle
+          ancestor: cycle_hook
+          input:
+            maps:
+              retryCount: 0
+              throttleSeconds: 0
+              continueArgs: '{worker.output.data.arguments}'
+              continueGeneration:
+                '@pipe':
+                  - ['{cycle_hook.output.data.continueGeneration}', 0]
+                  - ['{@logical.or}', 1]
+                  - ['{@math.add}']
+
         ender:
           title: Sets job data; ignores the \`Signal In\` Hook Channel which was suppressed; sends the final response
           type: hook
@@ -1162,6 +1235,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{signaler_worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
                   - ['{@conditional.nullish}', 10]
                   - ['{@conditional.nullish}']
+              initialInterval:
+                '@pipe':
+                  - ['{signaler_worker.output.data.initialInterval}','{trigger.output.data.initialInterval}']
+                  - ['{@conditional.nullish}', 1]
+                  - ['{@conditional.nullish}']
               maximumAttempts:
                 '@pipe':
                   - ['{signaler_worker.output.data.maximumAttempts}','{trigger.output.data.maximumAttempts}']
@@ -1273,12 +1351,17 @@ const getWorkflowYAML = (app, version) => {
                   - '@pipe':
                     - '@pipe':
                       - '@pipe':
-                        - ['{trigger.output.data.backoffCoefficient}', 10]
-                        - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{trigger.output.data.backoffCoefficient}', 10]
+                          - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{signaler_cycle_hook.output.data.retryCount}', 0]
+                          - ['{@conditional.nullish}']
+                        - ['{@math.pow}']
                       - '@pipe':
-                        - ['{signaler_cycle_hook.output.data.retryCount}', 0]
+                        - ['{trigger.output.data.initialInterval}', 1]
                         - ['{@conditional.nullish}']
-                      - ['{@math.pow}']
+                      - ['{@math.multiply}']
                     - '@pipe':
                       - ['{trigger.output.data.maximumInterval}', 120]
                       - ['{@logical.or}']
@@ -1311,6 +1394,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                headers:
+                  type: object
+                  description: optional metadata to pass alongside activity arguments
                 expire:
                   type: number
                 backoffCoefficient:
@@ -1319,9 +1405,12 @@ const getWorkflowYAML = (app, version) => {
                   type: number
                 maximumInterval:
                   type: number
+                startToCloseTimeout:
+                  type: number
             maps:
               activityName: '{signaler_worker.output.data.activityName}'
               arguments: '{signaler_worker.output.data.arguments}'
+              headers: '{signaler_worker.output.data.headers}'
               workflowDimension: '{signaler_worker.output.data.workflowDimension}'
               index: '{signaler_worker.output.data.index}'
               originJobId: '{signaler_worker.output.data.originJobId}'
@@ -1329,11 +1418,17 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{signaler_worker.output.data.workflowId}'
               workflowTopic: '{signaler_worker.output.data.workflowTopic}'
               expire: '{signaler_worker.output.data.expire}'
+              startToCloseTimeout: '{signaler_worker.output.data.startToCloseTimeout}'
               backoffCoefficient:
                 '@pipe':
                   - ['{signaler_worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
                   - ['{@conditional.nullish}', 10]
                   - ['{@conditional.nullish}']
+              initialInterval:
+                '@pipe':
+                  - ['{signaler_worker.output.data.initialInterval}','{trigger.output.data.initialInterval}']
+                  - ['{@conditional.nullish}', 1]
+                  - ['{@conditional.nullish}']
               maximumAttempts:
                 '@pipe':
                   - ['{signaler_worker.output.data.maximumAttempts}','{trigger.output.data.maximumAttempts}']
@@ -1417,12 +1512,17 @@ const getWorkflowYAML = (app, version) => {
                   - '@pipe':
                     - '@pipe':
                       - '@pipe':
-                        - ['{trigger.output.data.backoffCoefficient}', 10]
-                        - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{trigger.output.data.backoffCoefficient}', 10]
+                          - ['{@conditional.nullish}']
+                        - '@pipe':
+                          - ['{signaler_cycle_hook.output.data.retryCount}', 0]
+                          - ['{@conditional.nullish}']
+                        - ['{@math.pow}']
                       - '@pipe':
-                        - ['{signaler_cycle_hook.output.data.retryCount}', 0]
+                        - ['{trigger.output.data.initialInterval}', 1]
                         - ['{@conditional.nullish}']
-                      - ['{@math.pow}']
+                      - ['{@math.multiply}']
                     - '@pipe':
                       - ['{trigger.output.data.maximumInterval}', 120]
                       - ['{@logical.or}']
@@ -1617,6 +1717,9 @@ const getWorkflowYAML = (app, version) => {
           - to: proxyer
             conditions:
               code: 591
+          - to: continuer
+            conditions:
+              code: 592
           - to: retryer
             conditions:
               code: 599
@@ -1852,8 +1955,13 @@ const getWorkflowYAML = (app, version) => {
                   - ['{@object.create}']
 
         collator_waiter:
-          title: Waits for a matching signal to be sent to the collator workflow
+          title: Waits for a matching signal or optional timeout
           type: hook
+          sleep:
+            '@pipe':
+              - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+              - ['{@array.get}', duration]
+              - ['{@object.get}']
           hook:
             type: object
             properties:
@@ -1863,12 +1971,18 @@ const getWorkflowYAML = (app, version) => {
             maps:
               response[25]:
                 '@pipe':
-                  - ['{collator_trigger.output.data.items}']
                   - '@pipe':
                     - ['{collator_cycle_hook.output.data.cur_index}']
                   - '@pipe':
-                    - [type, wait, data, '{$self.hook.data}', ac, '{$job.metadata.jc}', au, '{$self.output.metadata.au}']
-                    - ['{@object.create}']
+                    - '@pipe':
+                      - ['{$self.hook.data.id}']
+                    - '@pipe':
+                      - [type, wait, data, '{$self.hook.data}', ac, '{$job.metadata.jc}', au, '{$self.output.metadata.au}']
+                      - ['{@object.create}']
+                    - '@pipe':
+                      - [type, wait, timedOut, true, ac, '{$self.output.metadata.ac}', au, '{$self.output.metadata.au}']
+                      - ['{@object.create}']
+                    - ['{@conditional.ternary}']
                   - ['{@object.create}']
 
         collator_childer:
@@ -2123,6 +2237,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                headers:
+                  type: object
+                  description: optional metadata to pass alongside activity arguments
                 expire:
                   type: number
                 backoffCoefficient:
@@ -2131,6 +2248,8 @@ const getWorkflowYAML = (app, version) => {
                   type: number
                 maximumInterval:
                   type: number
+                startToCloseTimeout:
+                  type: number
             maps:
               activityName:
                 '@pipe':
@@ -2142,6 +2261,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
                   - ['{@array.get}', arguments]
                   - ['{@object.get}']
+              headers:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', headers]
+                  - ['{@object.get}']
               workflowDimension:
                 '@pipe':
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
@@ -2192,6 +2316,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
                   - ['{@array.get}', maximumInterval]
                   - ['{@object.get}']
+              startToCloseTimeout:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', startToCloseTimeout]
+                  - ['{@object.get}']
           output:
             schema:
               type: object
@@ -2347,7 +2476,11 @@ const getWorkflowYAML = (app, version) => {
 
       expire:
         '@pipe':
-          - ['{activity_trigger.output.data.expire}', 1]
+          - '@pipe':
+            - ['{activity_trigger.output.data.startToCloseTimeout}']
+          - '@pipe':
+            - ['{activity_trigger.output.data.expire}', 1]
+            - ['{@conditional.nullish}']
           - ['{@conditional.nullish}']
 
       input:
@@ -2366,12 +2499,18 @@ const getWorkflowYAML = (app, version) => {
               type: string
             arguments:
               type: array
+            headers:
+              type: object
             backoffCoefficient:
               type: number
+            initialInterval:
+              type: number
             maximumAttempts:
               type: number
             maximumInterval:
               type: number
+            startToCloseTimeout:
+              type: number
             expire:
               type: number
       output:
@@ -2433,12 +2572,18 @@ const getWorkflowYAML = (app, version) => {
                   type: string
                 arguments:
                   type: array
+                headers:
+                  type: object
+                startToCloseTimeout:
+                  type: number
             maps:
               parentWorkflowId: '{activity_trigger.output.data.parentWorkflowId}'
               workflowId: '{activity_trigger.output.data.workflowId}'
               workflowTopic: '{activity_trigger.output.data.workflowTopic}'
               activityName: '{activity_trigger.output.data.activityName}'
               arguments: '{activity_trigger.output.data.arguments}'
+              headers: '{activity_trigger.output.data.headers}'
+              startToCloseTimeout: '{activity_trigger.output.data.startToCloseTimeout}'
           output:
             schema:
               type: object
@@ -2455,9 +2600,14 @@ const getWorkflowYAML = (app, version) => {
           sleep:
             '@pipe':
               - '@pipe':
-                - ['{activity_trigger.output.data.backoffCoefficient}', 10]
-                - ['{@logical.or}', '{activity_cycle_hook.output.data.retryCount}']
-                - ['{@math.pow}']
+                - '@pipe':
+                  - ['{activity_trigger.output.data.backoffCoefficient}', 10]
+                  - ['{@logical.or}', '{activity_cycle_hook.output.data.retryCount}']
+                  - ['{@math.pow}']
+                - '@pipe':
+                  - ['{activity_trigger.output.data.initialInterval}', 1]
+                  - ['{@conditional.nullish}']
+                - ['{@math.multiply}']
               - '@pipe':
                 - ['{activity_trigger.output.data.maximumInterval}', 120]
                 - ['{@math.min}']
@@ -2517,7 +2667,7 @@ const getWorkflowYAML = (app, version) => {
                       - '@pipe':
                         - ['{activity_cycle_hook.output.data.retryCount}']
                       - '@pipe':
-                        - ['{activity_trigger.output.data.maximumAttempts}', 5]
+                        - ['{activity_trigger.output.data.maximumAttempts}', 50]
                         - ['{@conditional.nullish}']
                       - ['{@conditional.greater_than_or_equal}']
 
@@ -2531,7 +2681,7 @@ const getWorkflowYAML = (app, version) => {
                       - '@pipe':
                         - ['{activity_cycle_hook.output.data.retryCount}']
                       - '@pipe':
-                        - ['{activity_trigger.output.data.maximumAttempts}', 5]
+                        - ['{activity_trigger.output.data.maximumAttempts}', 50]
                         - ['{@conditional.nullish}']
                       - ['{@conditional.less_than}']
         activity_retryer:

package/build/services/durable/telemetry.d.ts

@@ -0,0 +1,80 @@
+import { Context, Span, SpanStatusCode } from '../../types/telemetry';
+/**
+ * Emits OpenTelemetry spans for durable workflow execution. All methods
+ * are no-ops when no OTel SDK is registered — `@opentelemetry/api`
+ * returns a no-op tracer by default, so there is zero overhead without
+ * a configured exporter.
+ *
+ * ## Span Categories
+ *
+ * | Span | When | Mode |
+ * |------|------|------|
+ * | `WORKFLOW/START/{name}` | First execution (not replay) | `info` |
+ * | `WORKFLOW/COMPLETE/{name}` | Workflow returns successfully | `info` |
+ * | `WORKFLOW/ERROR/{name}` | Workflow throws a fatal error | `info` |
+ * | `ACTIVITY/{name}` | Real wall-clock activity execution on the worker | `info` |
+ * | `DISPATCH/{type}/{name}/{idx}` | Operation dispatched (first execution only) | `debug` |
+ * | `RETURN/{type}/{name}/{idx}` | Operation result returned (with ac/au duration) | `debug` |
+ *
+ * ## Gating
+ *
+ * - `isEnabled()` — true when `HMSH_TELEMETRY` is set (any value)
+ * - `isVerbose()` — true only when `HMSH_TELEMETRY === 'debug'`
+ *
+ * In `info` mode, engine-layer spans (stream hops, DAG activity spans)
+ * are suppressed for durable workflows — only the spans above are
+ * emitted. This keeps dashboards clean and focused on the user's
+ * workflow story. Set `HMSH_TELEMETRY=debug` to also see engine
+ * internals and per-operation DISPATCH/RETURN spans.
+ *
+ * ## Setup
+ *
+ * Register an OTel SDK with a trace exporter before starting workers:
+ *
+ * ```typescript
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+ * import { resourceFromAttributes } from '@opentelemetry/resources';
+ * import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+ *
+ * const sdk = new NodeSDK({
+ *   resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-service' }),
+ *   traceExporter: new OTLPTraceExporter({
+ *     url: 'https://api.honeycomb.io/v1/traces',
+ *     headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY },
+ *   }),
+ * });
+ * sdk.start();
+ * ```
+ *
+ * ```bash
+ * # Concise workflow telemetry (recommended for production)
+ * HMSH_TELEMETRY=info node worker.js
+ *
+ * # Full operational detail (debugging)
+ * HMSH_TELEMETRY=debug node worker.js
+ * ```
+ */
+export declare class DurableTelemetryService {
+    static isEnabled(): boolean;
+    static isVerbose(): boolean;
+    static getParentContext(traceId: string, spanId: string): Context;
+    /**
+     * Emit a point-in-time span (starts and ends immediately).
+     */
+    static emitPointSpan(traceId: string, parentSpanId: string, spanName: string, attributes: Record<string, string | number | boolean>, statusCode?: SpanStatusCode, statusMessage?: string): void;
+    /**
+     * Emit a duration span with explicit start/end times.
+     * Used for reconstructing operation durations from stored timestamps.
+     */
+    static emitDurationSpan(traceId: string, parentSpanId: string, spanName: string, startTimeMs: number, endTimeMs: number, attributes: Record<string, string | number | boolean>): void;
+    /**
+     * Start a span and return it for manual end (e.g., wrapping activity execution).
+     */
+    static startSpan(traceId: string, parentSpanId: string, spanName: string, attributes: Record<string, string | number | boolean>): Span;
+    /**
+     * Parse ac/au timestamps from jmark results to epoch ms.
+     * Handles both ISO strings and numeric epoch values.
+     */
+    static parseTimestamp(ts: string | number): number;
+}