@hotmeshio/hotmesh 0.10.0 → 0.10.2

package/build/services/durable/exporter.js

@@ -1,8 +1,158 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExporterService = void 0;
+exports.mapStatus = exports.isSystemActivity = exports.extractActivityName = exports.extractOperation = exports.computeDuration = exports.parseTimestamp = exports.ExporterService = void 0;
 const utils_1 = require("../../modules/utils");
 const serializer_1 = require("../serializer");
+// ── Timestamp helpers ────────────────────────────────────────────────────────
+/**
+ * Parse a HotMesh compact timestamp (YYYYMMDDHHmmss.mmm) into ISO 8601.
+ * Also accepts ISO 8601 strings directly.
+ */
+function parseTimestamp(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const m = raw.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?:\.?(\d+))?$/);
+    if (m) {
+        const [, yr, mo, dy, hr, mi, sc, ms] = m;
+        const frac = ms ? `.${ms.padEnd(3, '0').slice(0, 3)}` : '.000';
+        return `${yr}-${mo}-${dy}T${hr}:${mi}:${sc}${frac}Z`;
+    }
+    // Try ISO 8601
+    if (raw.includes('T') || raw.includes('-')) {
+        const d = new Date(raw);
+        if (!isNaN(d.getTime()))
+            return d.toISOString();
+    }
+    return null;
+}
+exports.parseTimestamp = parseTimestamp;
+/**
+ * Compute duration in milliseconds between two HotMesh timestamps.
+ */
+function computeDuration(ac, au) {
+    const start = parseTimestamp(ac);
+    const end = parseTimestamp(au);
+    if (!start || !end)
+        return null;
+    return new Date(end).getTime() - new Date(start).getTime();
+}
+exports.computeDuration = computeDuration;
+// ── Timeline key parsing ─────────────────────────────────────────────────────
+/**
+ * Extract the operation type (proxy, child, start, wait, sleep, hook)
+ * from a timeline key like `-proxy,0,0-1-`.
+ */
+function extractOperation(key) {
+    const parts = key.split('-').filter(Boolean);
+    return parts[0]?.split(',')[0] || 'unknown';
+}
+exports.extractOperation = extractOperation;
+// ── Name extraction ──────────────────────────────────────────────────────────
+/**
+ * Extract the activity name from a timeline entry value's job_id.
+ *
+ * Job ID format: `-{workflowId}-$${activityName}{dimension}-{execIndex}`
+ * Examples:
+ *   `-wfId-$analyzeContent-5`  → `'analyzeContent'`
+ *   `-wfId-$processOrder,0,0-3` → `'processOrder'`
+ */
+function extractActivityName(value) {
+    const jobId = value?.job_id;
+    if (!jobId || typeof jobId !== 'string')
+        return 'unknown';
+    const dollarIdx = jobId.lastIndexOf('$');
+    if (dollarIdx === -1)
+        return jobId;
+    const afterDollar = jobId.substring(dollarIdx + 1);
+    const dashIdx = afterDollar.lastIndexOf('-');
+    const nameWithDim = dashIdx > 0 ? afterDollar.substring(0, dashIdx) : afterDollar;
+    // Strip dimension suffix (,N,N...)
+    const commaIdx = nameWithDim.indexOf(',');
+    return (commaIdx > 0 ? nameWithDim.substring(0, commaIdx) : nameWithDim) || 'unknown';
+}
+exports.extractActivityName = extractActivityName;
+/**
+ * Check if an activity name is a system (interceptor) operation.
+ */
+function isSystemActivity(name) {
+    return name.startsWith('lt');
+}
+exports.isSystemActivity = isSystemActivity;
+/**
+ * Extract a child workflow ID from a child/start timeline value.
+ */
+function extractChildWorkflowId(value) {
+    return value?.job_id || 'unknown';
+}
+// ── Status mapping ───────────────────────────────────────────────────────────
+/**
+ * Map HotMesh job state to a human-readable execution status.
+ *
+ * HotMesh semaphore: `0` = idle, `> 0` = pending activities,
+ * `< 0` = failed / interrupted.
+ *
+ * A workflow can be "done" (`state.data.done === true`) while the
+ * semaphore is still > 0 (cleanup activities pending). We check
+ * both the `done` flag and the semaphore to determine status.
+ */
+function mapStatus(rawStatus, isDone, hasError) {
+    if (hasError || (rawStatus !== undefined && !isNaN(rawStatus) && rawStatus < 0)) {
+        return 'failed';
+    }
+    if (isDone || rawStatus === 0)
+        return 'completed';
+    if (rawStatus === undefined || isNaN(rawStatus))
+        return 'running';
+    return 'running';
+}
+exports.mapStatus = mapStatus;
+// ── Event construction ───────────────────────────────────────────────────────
+function makeEvent(event_id, event_type, category, event_time, duration_ms, is_system, attributes) {
+    return { event_id, event_type, category, event_time, duration_ms, is_system, attributes };
+}
+function computeSummary(events) {
+    const summary = {
+        total_events: events.length,
+        activities: { total: 0, completed: 0, failed: 0, system: 0, user: 0 },
+        child_workflows: { total: 0, completed: 0, failed: 0 },
+        timers: 0,
+        signals: 0,
+    };
+    for (const e of events) {
+        switch (e.event_type) {
+            case 'activity_task_scheduled':
+                summary.activities.total++;
+                if (e.is_system)
+                    summary.activities.system++;
+                else
+                    summary.activities.user++;
+                break;
+            case 'activity_task_completed':
+                summary.activities.completed++;
+                break;
+            case 'activity_task_failed':
+                summary.activities.failed++;
+                break;
+            case 'child_workflow_execution_started':
+                summary.child_workflows.total++;
+                break;
+            case 'child_workflow_execution_completed':
+                summary.child_workflows.completed++;
+                break;
+            case 'child_workflow_execution_failed':
+                summary.child_workflows.failed++;
+                break;
+            case 'timer_started':
+                summary.timers++;
+                break;
+            case 'workflow_execution_signaled':
+                summary.signals++;
+                break;
+        }
+    }
+    return summary;
+}
+// ── Exporter Service ─────────────────────────────────────────────────────────
 class ExporterService {
     constructor(appId, store, logger) {
         this.appId = appId;
@@ -10,7 +160,7 @@ class ExporterService {
         this.store = store;
     }
     /**
-     * Convert the job hash from its compiles format into a DurableJobExport object with
+     * Convert the job hash from its compiled format into a DurableJobExport object with
      * facets that describe the workflow in terms relevant to narrative storytelling.
      */
     async export(jobId, options = {}) {
@@ -22,6 +172,284 @@ class ExporterService {
         const jobExport = this.inflate(jobData, options);
         return jobExport;
     }
+    /**
+     * Export a workflow execution as a Temporal-compatible event history.
+     *
+     * **Sparse mode** (default): transforms the main workflow's timeline
+     * into a flat event list. No additional I/O beyond the initial export.
+     *
+     * **Verbose mode**: recursively fetches child workflow jobs and attaches
+     * their executions as nested `children`.
+     */
+    async exportExecution(jobId, workflowTopic, options = {}) {
+        const raw = await this.export(jobId);
+        const execution = this.transformToExecution(raw, jobId, workflowTopic, options);
+        if (options.mode === 'verbose') {
+            const maxDepth = options.max_depth ?? 5;
+            execution.children = await this.fetchChildren(raw, workflowTopic, options, 1, maxDepth);
+        }
+        return execution;
+    }
+    /**
+     * Pure transformation: convert a raw DurableJobExport into a
+     * Temporal-compatible WorkflowExecution event history.
+     */
+    transformToExecution(raw, workflowId, workflowTopic, options) {
+        const events = [];
+        let nextId = 1;
+        // ── Extract timing from state metadata ─────────────────────────
+        const state = raw.state;
+        const metadata = state?.output?.metadata ?? state?.metadata;
+        const stateData = state?.output?.data ?? state?.data;
+        const jobCreated = metadata?.jc ?? stateData?.jc ?? metadata?.ac;
+        const jobUpdated = metadata?.ju ?? stateData?.ju ?? metadata?.au;
+        const startTime = parseTimestamp(jobCreated);
+        const closeTime = parseTimestamp(jobUpdated);
+        // ── Synthetic workflow_execution_started ─────────────────────────
+        if (startTime) {
+            events.push(makeEvent(nextId++, 'workflow_execution_started', 'workflow', startTime, null, false, {
+                kind: 'workflow_execution_started',
+                workflow_type: workflowTopic,
+                task_queue: workflowTopic,
+                input: options.omit_results ? undefined : raw.data,
+            }));
+        }
+        // ── Transform timeline entries ───────────────────────────────
+        const timeline = raw.timeline || [];
+        for (const entry of timeline) {
+            const operation = extractOperation(entry.key);
+            const val = (typeof entry.value === 'object' && entry.value !== null)
+                ? entry.value
+                : null;
+            const ac = val?.ac;
+            const au = val?.au;
+            const acIso = parseTimestamp(ac);
+            const auIso = parseTimestamp(au);
+            const dur = computeDuration(ac, au);
+            const hasError = val != null && '$error' in val;
+            switch (operation) {
+                case 'proxy': {
+                    const name = extractActivityName(val);
+                    const isSys = isSystemActivity(name);
+                    if (options.exclude_system && isSys)
+                        break;
+                    if (acIso) {
+                        events.push(makeEvent(nextId++, 'activity_task_scheduled', 'activity', acIso, null, isSys, {
+                            kind: 'activity_task_scheduled',
+                            activity_type: name,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    if (auIso) {
+                        if (hasError) {
+                            events.push(makeEvent(nextId++, 'activity_task_failed', 'activity', auIso, dur, isSys, {
+                                kind: 'activity_task_failed',
+                                activity_type: name,
+                                failure: val?.$error,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                        else {
+                            events.push(makeEvent(nextId++, 'activity_task_completed', 'activity', auIso, dur, isSys, {
+                                kind: 'activity_task_completed',
+                                activity_type: name,
+                                result: options.omit_results ? undefined : val?.data,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                    }
+                    break;
+                }
+                case 'child': {
+                    const childId = extractChildWorkflowId(val);
+                    if (acIso) {
+                        events.push(makeEvent(nextId++, 'child_workflow_execution_started', 'child_workflow', acIso, null, false, {
+                            kind: 'child_workflow_execution_started',
+                            child_workflow_id: childId,
+                            awaited: true,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    if (auIso) {
+                        if (hasError) {
+                            events.push(makeEvent(nextId++, 'child_workflow_execution_failed', 'child_workflow', auIso, dur, false, {
+                                kind: 'child_workflow_execution_failed',
+                                child_workflow_id: childId,
+                                failure: val?.$error,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                        else {
+                            events.push(makeEvent(nextId++, 'child_workflow_execution_completed', 'child_workflow', auIso, dur, false, {
+                                kind: 'child_workflow_execution_completed',
+                                child_workflow_id: childId,
+                                result: options.omit_results ? undefined : val?.data,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                    }
+                    break;
+                }
+                case 'start': {
+                    const childId = extractChildWorkflowId(val);
+                    const ts = acIso || auIso;
+                    if (ts) {
+                        events.push(makeEvent(nextId++, 'child_workflow_execution_started', 'child_workflow', ts, null, false, {
+                            kind: 'child_workflow_execution_started',
+                            child_workflow_id: childId,
+                            awaited: false,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    break;
+                }
+                case 'wait': {
+                    const signalName = val?.id
+                        || val?.data?.id
+                        || val?.data?.data?.id
+                        || `signal-${entry.index}`;
+                    const ts = auIso || acIso;
+                    if (ts) {
+                        events.push(makeEvent(nextId++, 'workflow_execution_signaled', 'signal', ts, dur, false, {
+                            kind: 'workflow_execution_signaled',
+                            signal_name: signalName,
+                            input: options.omit_results ? undefined : val?.data?.data,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    break;
+                }
+                case 'sleep': {
+                    if (acIso) {
+                        events.push(makeEvent(nextId++, 'timer_started', 'timer', acIso, null, false, {
+                            kind: 'timer_started',
+                            duration_ms: dur ?? undefined,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    if (auIso) {
+                        events.push(makeEvent(nextId++, 'timer_fired', 'timer', auIso, dur, false, {
+                            kind: 'timer_fired',
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    break;
+                }
+                // Unknown operation types are silently skipped (forward-compatible)
+            }
+        }
+        // ── Determine status ─────────────────────────────────────────
+        const isDone = stateData?.done === true;
+        const hasError = !!stateData?.$error;
+        const status = mapStatus(raw.status, isDone, hasError);
+        // ── Extract workflow result ──────────────────────────────────
+        const result = stateData?.response ?? (raw.data && Object.keys(raw.data).length > 0 ? raw.data : null);
+        // ── Synthetic workflow_execution_completed / failed ───────────
+        if (status === 'completed' && closeTime) {
+            const totalDur = startTime
+                ? new Date(closeTime).getTime() - new Date(startTime).getTime()
+                : null;
+            events.push(makeEvent(nextId++, 'workflow_execution_completed', 'workflow', closeTime, totalDur, false, {
+                kind: 'workflow_execution_completed',
+                result: options.omit_results ? undefined : result,
+            }));
+        }
+        else if (status === 'failed' && closeTime) {
+            const totalDur = startTime
+                ? new Date(closeTime).getTime() - new Date(startTime).getTime()
+                : null;
+            events.push(makeEvent(nextId++, 'workflow_execution_failed', 'workflow', closeTime, totalDur, false, {
+                kind: 'workflow_execution_failed',
+                failure: stateData?.err,
+            }));
+        }
+        // ── Sort chronologically ─────────────────────────────────────
+        events.sort((a, b) => {
+            const cmp = a.event_time.localeCompare(b.event_time);
+            return cmp !== 0 ? cmp : a.event_id - b.event_id;
+        });
+        // ── Re-number event IDs after sort ───────────────────────────
+        for (let i = 0; i < events.length; i++) {
+            events[i].event_id = i + 1;
+        }
+        // ── Back-references (Temporal-compatible) ────────────────────
+        const scheduledMap = new Map();
+        const initiatedMap = new Map();
+        for (const e of events) {
+            const attrs = e.attributes;
+            if (e.event_type === 'activity_task_scheduled' && attrs.timeline_key) {
+                scheduledMap.set(attrs.timeline_key, e.event_id);
+            }
+            if (e.event_type === 'child_workflow_execution_started' && attrs.timeline_key) {
+                initiatedMap.set(attrs.timeline_key, e.event_id);
+            }
+            if ((e.event_type === 'activity_task_completed' || e.event_type === 'activity_task_failed') && attrs.timeline_key) {
+                attrs.scheduled_event_id = scheduledMap.get(attrs.timeline_key) ?? null;
+            }
+            if ((e.event_type === 'child_workflow_execution_completed' || e.event_type === 'child_workflow_execution_failed') && attrs.timeline_key) {
+                attrs.initiated_event_id = initiatedMap.get(attrs.timeline_key) ?? null;
+            }
+        }
+        // ── Compute total duration ───────────────────────────────────
+        const totalDuration = (startTime && closeTime)
+            ? new Date(closeTime).getTime() - new Date(startTime).getTime()
+            : null;
+        return {
+            workflow_id: workflowId,
+            workflow_type: workflowTopic,
+            task_queue: workflowTopic,
+            status,
+            start_time: startTime,
+            close_time: (status !== 'running') ? closeTime : null,
+            duration_ms: totalDuration,
+            result,
+            events,
+            summary: computeSummary(events),
+        };
+    }
+    /**
+     * Recursively fetch child workflow executions for verbose mode.
+     */
+    async fetchChildren(raw, workflowTopic, options, depth, maxDepth) {
+        if (depth >= maxDepth)
+            return [];
+        const children = [];
+        const timeline = raw.timeline || [];
+        for (const entry of timeline) {
+            const operation = extractOperation(entry.key);
+            if (operation !== 'child' && operation !== 'start')
+                continue;
+            const val = (typeof entry.value === 'object' && entry.value !== null)
+                ? entry.value
+                : null;
+            const childJobId = val?.job_id;
+            if (!childJobId || typeof childJobId !== 'string')
+                continue;
+            try {
+                const childRaw = await this.export(childJobId);
+                const childTopic = childRaw.data?.workflowTopic ?? workflowTopic;
+                const childExecution = this.transformToExecution(childRaw, childJobId, childTopic, options);
+                if (options.mode === 'verbose') {
+                    childExecution.children = await this.fetchChildren(childRaw, childTopic, options, depth + 1, maxDepth);
+                }
+                children.push(childExecution);
+            }
+            catch {
+                // Child job may have expired or been cleaned up
+            }
+        }
+        return children;
+    }
     /**
      * Inflates the job data into a DurableJobExport object
      * @param jobHash - the job data

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

@@ -1,5 +1,5 @@
 import { HotMesh } from '../hotmesh';
-import { DurableJobExport, ExportOptions } from '../../types/exporter';
+import { DurableJobExport, ExportOptions, ExecutionExportOptions, WorkflowExecution } from '../../types/exporter';
 import { JobInterruptOptions } from '../../types/job';
 import { StreamError } from '../../types/stream';
 import { ExporterService } from './exporter';
@@ -44,6 +44,17 @@ export declare class WorkflowHandleService {
      * Exports the workflow state to a JSON object.
      */
     export(options?: ExportOptions): Promise<DurableJobExport>;
+    /**
+     * Exports the workflow as a Temporal-like execution event history.
+     *
+     * **Sparse mode** (default): transforms the main workflow's timeline
+     * into a flat event list with workflow lifecycle, activity, child workflow,
+     * timer, and signal events.
+     *
+     * **Verbose mode**: recursively fetches child workflow jobs and attaches
+     * their full execution histories as nested `children`.
+     */
+    exportExecution(options?: ExecutionExportOptions): Promise<WorkflowExecution>;
     /**
      * Sends a signal to the workflow. This is a way to send
      * a message to a workflow that is paused due to having

package/build/services/durable/handle.js

@@ -43,6 +43,19 @@ class WorkflowHandleService {
     async export(options) {
         return this.exporter.export(this.workflowId, options);
     }
+    /**
+     * Exports the workflow as a Temporal-like execution event history.
+     *
+     * **Sparse mode** (default): transforms the main workflow's timeline
+     * into a flat event list with workflow lifecycle, activity, child workflow,
+     * timer, and signal events.
+     *
+     * **Verbose mode**: recursively fetches child workflow jobs and attaches
+     * their full execution histories as nested `children`.
+     */
+    async exportExecution(options) {
+        return this.exporter.exportExecution(this.workflowId, this.workflowTopic, options);
+    }
     /**
      * Sends a signal to the workflow. This is a way to send
      * a message to a workflow that is paused due to having

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

@@ -364,12 +364,41 @@ declare class DurableClass {
     static didInterrupt: typeof didInterrupt;
     private static interceptorService;
     /**
-     * Register a workflow interceptor
+     * Register a workflow interceptor that wraps the entire workflow execution
+     * in an onion-like pattern. Interceptors execute in registration order
+     * (first registered is outermost) and can perform actions before and after
+     * workflow execution, handle errors, and add cross-cutting concerns like
+     * logging, metrics, or tracing.
+     *
+     * Workflow interceptors run inside the workflow's async local storage context,
+     * so all Durable workflow methods (`proxyActivities`, `sleepFor`, `waitFor`,
+     * `execChild`, etc.) are available. When using Durable functions, always check
+     * for interruptions with `Durable.didInterrupt(err)` and rethrow them.
+     *
      * @param interceptor The interceptor to register
+     *
+     * @example
+     * ```typescript
+     * // Logging interceptor
+     * Durable.registerInterceptor({
+     *   async execute(ctx, next) {
+     *     console.log(`Workflow ${ctx.get('workflowName')} starting`);
+     *     try {
+     *       const result = await next();
+     *       console.log(`Workflow ${ctx.get('workflowName')} completed`);
+     *       return result;
+     *     } catch (err) {
+     *       if (Durable.didInterrupt(err)) throw err;
+     *       console.error(`Workflow ${ctx.get('workflowName')} failed`);
+     *       throw err;
+     *     }
+     *   }
+     * });
+     * ```
      */
     static registerInterceptor(interceptor: WorkflowInterceptor): void;
     /**
-     * Clear all registered interceptors (both workflow and activity)
+     * Clear all registered interceptors (both workflow and activity).
      */
     static clearInterceptors(): void;
     /**

package/build/services/durable/index.js

@@ -280,14 +280,43 @@ class DurableClass {
      */
     constructor() { }
     /**
-     * Register a workflow interceptor
+     * Register a workflow interceptor that wraps the entire workflow execution
+     * in an onion-like pattern. Interceptors execute in registration order
+     * (first registered is outermost) and can perform actions before and after
+     * workflow execution, handle errors, and add cross-cutting concerns like
+     * logging, metrics, or tracing.
+     *
+     * Workflow interceptors run inside the workflow's async local storage context,
+     * so all Durable workflow methods (`proxyActivities`, `sleepFor`, `waitFor`,
+     * `execChild`, etc.) are available. When using Durable functions, always check
+     * for interruptions with `Durable.didInterrupt(err)` and rethrow them.
+     *
      * @param interceptor The interceptor to register
+     *
+     * @example
+     * ```typescript
+     * // Logging interceptor
+     * Durable.registerInterceptor({
+     *   async execute(ctx, next) {
+     *     console.log(`Workflow ${ctx.get('workflowName')} starting`);
+     *     try {
+     *       const result = await next();
+     *       console.log(`Workflow ${ctx.get('workflowName')} completed`);
+     *       return result;
+     *     } catch (err) {
+     *       if (Durable.didInterrupt(err)) throw err;
+     *       console.error(`Workflow ${ctx.get('workflowName')} failed`);
+     *       throw err;
+     *     }
+     *   }
+     * });
+     * ```
      */
     static registerInterceptor(interceptor) {
         DurableClass.interceptorService.register(interceptor);
     }
     /**
-     * Clear all registered interceptors (both workflow and activity)
+     * Clear all registered interceptors (both workflow and activity).
      */
     static clearInterceptors() {
         DurableClass.interceptorService.clear();

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

@@ -181,6 +181,79 @@ import { WorkflowInterceptor, InterceptorRegistry, ActivityInterceptor, Activity
  *   }
  * };
  * ```
+ *
+ * ## Activity Interceptors
+ *
+ * Activity interceptors wrap individual proxied activity calls, supporting
+ * both **before** and **after** phases. The before phase receives the activity
+ * input (and can modify `activityCtx.args`). The after phase receives the
+ * activity output as the return value of `next()`.
+ *
+ * This enables patterns like publishing activity results to an external
+ * system (e.g., SNS, audit log) without modifying the workflow itself.
+ *
+ * **Important:** The after-phase proxy activity calls go through the same
+ * interceptor chain. Guard against recursion by checking `activityCtx.activityName`
+ * to skip the interceptor's own calls.
+ *
+ * @example
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import type { ActivityInterceptor } from '@hotmeshio/hotmesh/types/durable';
+ * import * as activities from './activities';
+ *
+ * // Activity interceptor that publishes results via a proxy activity
+ * const publishResultInterceptor: ActivityInterceptor = {
+ *   async execute(activityCtx, workflowCtx, next) {
+ *     try {
+ *       // BEFORE: inspect or modify the activity input
+ *       console.log(`Calling ${activityCtx.activityName}`, activityCtx.args);
+ *
+ *       // Execute the activity (returns stored result on replay)
+ *       const result = await next();
+ *
+ *       // AFTER: use the activity output (only runs on replay,
+ *       // once the result is available)
+ *
+ *       // Guard: skip for the interceptor's own proxy calls
+ *       if (activityCtx.activityName !== 'publishToSNS') {
+ *         const { publishToSNS } = Durable.workflow.proxyActivities<{
+ *           publishToSNS: (topic: string, payload: any) => Promise<void>;
+ *         }>({
+ *           taskQueue: 'shared-notifications',
+ *           retryPolicy: { maximumAttempts: 3, throwOnError: true },
+ *         });
+ *
+ *         await publishToSNS('activity-results', {
+ *           workflowId: workflowCtx.get('workflowId'),
+ *           activityName: activityCtx.activityName,
+ *           input: activityCtx.args,
+ *           output: result,
+ *         });
+ *       }
+ *
+ *       return result;
+ *     } catch (err) {
+ *       if (Durable.didInterrupt(err)) throw err;
+ *       throw err;
+ *     }
+ *   },
+ * };
+ *
+ * Durable.registerActivityInterceptor(publishResultInterceptor);
+ * ```
+ *
+ * ## Activity Interceptor Replay Pattern
+ *
+ * Activity interceptors participate in the interruption/replay cycle:
+ *
+ * 1. **First execution**: Before-phase runs → `next()` registers the activity
+ *    interruption and throws `DurableProxyError` → workflow pauses
+ * 2. **Second execution**: Before-phase replays → `next()` returns the stored
+ *    activity result → after-phase runs → after-phase proxy call (e.g.,
+ *    `publishToSNS`) registers its own interruption → workflow pauses
+ * 3. **Third execution**: Everything replays → after-phase proxy call returns
+ *    its stored result → interceptor returns → workflow continues
  */
 export declare class InterceptorService implements InterceptorRegistry {
     interceptors: WorkflowInterceptor[];