@hotmeshio/hotmesh 0.10.0 → 0.10.2

package/build/services/durable/interceptor.js

@@ -183,6 +183,79 @@ exports.InterceptorService = void 0;
  *   }
  * };
  * ```
+ *
+ * ## 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
  */
 class InterceptorService {
     constructor() {

package/build/services/durable/workflow/proxyActivities.js

@@ -42,36 +42,40 @@ exports.getProxyInterruptPayload = getProxyInterruptPayload;
  */
 function wrapActivity(activityName, options) {
     return async function (...args) {
+        // Increment counter first for deterministic replay ordering
         const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('proxy');
-        if (didRunAlready) {
-            if (result?.$error) {
-                if (options?.retryPolicy?.throwOnError !== false) {
-                    const code = result.$error.code;
-                    const message = result.$error.message;
-                    const stack = result.$error.stack;
-                    if (code === common_1.HMSH_CODE_DURABLE_FATAL) {
-                        throw new common_1.DurableFatalError(message, stack);
-                    }
-                    else if (code === common_1.HMSH_CODE_DURABLE_MAXED) {
-                        throw new common_1.DurableMaxedError(message, stack);
-                    }
-                    else if (code === common_1.HMSH_CODE_DURABLE_TIMEOUT) {
-                        throw new common_1.DurableTimeoutError(message, stack);
-                    }
-                    else {
-                        // For any other error code, throw a DurableFatalError to stop the workflow
-                        throw new common_1.DurableFatalError(message, stack);
+        const context = (0, context_1.getContext)();
+        const { interruptionRegistry } = context;
+        // Build activityCtx so interceptors can inspect/modify args
+        const activityCtx = { activityName, args, options };
+        // Core function: returns stored result on replay, or registers
+        // the interruption and throws on first execution. Reads args
+        // from activityCtx so "before" interceptors can modify them.
+        const coreFunction = async () => {
+            if (didRunAlready) {
+                if (result?.$error) {
+                    if (options?.retryPolicy?.throwOnError !== false) {
+                        const code = result.$error.code;
+                        const message = result.$error.message;
+                        const stack = result.$error.stack;
+                        if (code === common_1.HMSH_CODE_DURABLE_FATAL) {
+                            throw new common_1.DurableFatalError(message, stack);
+                        }
+                        else if (code === common_1.HMSH_CODE_DURABLE_MAXED) {
+                            throw new common_1.DurableMaxedError(message, stack);
+                        }
+                        else if (code === common_1.HMSH_CODE_DURABLE_TIMEOUT) {
+                            throw new common_1.DurableTimeoutError(message, stack);
+                        }
+                        else {
+                            throw new common_1.DurableFatalError(message, stack);
+                        }
                     }
+                    return result.$error;
                 }
-                return result.$error;
+                return result.data;
             }
-            return result.data;
-        }
-        const context = (0, context_1.getContext)();
-        const { interruptionRegistry } = context;
-        // Core activity registration logic
-        const executeActivity = async () => {
-            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, args, options);
+            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, activityCtx.args, options);
             interruptionRegistry.push({
                 code: common_1.HMSH_CODE_DURABLE_PROXY,
                 type: 'DurableProxyError',
@@ -80,13 +84,13 @@ function wrapActivity(activityName, options) {
             await (0, common_1.sleepImmediate)();
             throw new common_1.DurableProxyError(interruptionMessage);
         };
-        // Check for activity interceptors
+        // Run through interceptor chain if interceptors exist
         const store = common_1.asyncLocalStorage.getStore();
         const interceptorService = store?.get('activityInterceptorService');
         if (interceptorService?.activityInterceptors?.length > 0) {
-            return await interceptorService.executeActivityChain({ activityName, args, options }, store, executeActivity);
+            return await interceptorService.executeActivityChain(activityCtx, store, coreFunction);
         }
-        return await executeActivity();
+        return await coreFunction();
     };
 }
 exports.wrapActivity = wrapActivity;

package/build/services/store/providers/postgres/kvtables.js

@@ -182,6 +182,7 @@ const KVTables = (context) => ({
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 expired_at TIMESTAMP WITH TIME ZONE,
+                pruned_at TIMESTAMP WITH TIME ZONE,
                 is_live BOOLEAN DEFAULT TRUE,
                 PRIMARY KEY (id)
               ) PARTITION BY HASH (id);
@@ -214,8 +215,12 @@ const KVTables = (context) => ({
               ON ${fullTableName} (entity, status);
             `);
                         await client.query(`
-              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_expired_at 
+              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_expired_at
               ON ${fullTableName} (expired_at);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_pruned_at
+              ON ${fullTableName} (pruned_at) WHERE pruned_at IS NULL;
             `);
                         // Create function to update is_live flag in the schema
                         await client.query(`

package/build/types/dba.d.ts

@@ -31,7 +31,7 @@ export interface PruneOptions {
     /**
      * If true, hard-deletes expired jobs older than the retention window.
      * FK CASCADE on `jobs_attributes` automatically removes associated
-     * attribute rows.
+     * attribute rows. When `entities` is set, only matching jobs are deleted.
      * @default true
      */
     jobs?: boolean;
@@ -42,13 +42,35 @@ export interface PruneOptions {
      */
     streams?: boolean;
     /**
-     * If true, strips execution-artifact attributes (`adata`, `hmark`,
-     * `jmark`, `status`, `other`) from completed jobs (status = 0),
-     * retaining only `jdata` (workflow return data) and `udata`
-     * (user-searchable data).
+     * If true, strips execution-artifact attributes from completed,
+     * un-pruned jobs. Preserves `jdata` (return data), `udata`
+     * (searchable data), and `jmark` (timeline/event history for
+     * Temporal-compatible export). See `keepHmark` for `hmark`.
      * @default false
      */
     attributes?: boolean;
+    /**
+     * Entity allowlist. When provided, only jobs whose `entity` column
+     * matches one of these values are eligible for pruning/stripping.
+     * Jobs with `entity IS NULL` are excluded unless `pruneTransient`
+     * is also true.
+     * @default undefined (all entities)
+     */
+    entities?: string[];
+    /**
+     * If true, hard-deletes expired jobs where `entity IS NULL`
+     * (transient workflow runs). Must also satisfy the retention
+     * window (`expire`).
+     * @default false
+     */
+    pruneTransient?: boolean;
+    /**
+     * If true, `hmark` attributes are preserved during stripping
+     * (along with `jdata`, `udata`, and `jmark`). If false, `hmark`
+     * rows are stripped.
+     * @default false
+     */
+    keepHmark?: boolean;
 }
 /**
  * Result returned by `DBA.prune()`, providing deletion
@@ -61,4 +83,8 @@ export interface PruneResult {
     streams: number;
     /** Number of execution-artifact attribute rows stripped from completed jobs */
     attributes: number;
+    /** Number of transient (entity IS NULL) job rows hard-deleted */
+    transient: number;
+    /** Number of jobs marked as pruned (pruned_at set) */
+    marked: number;
 }

package/build/types/durable.d.ts

@@ -596,15 +596,21 @@ export interface WorkflowInterceptor {
     execute(ctx: Map<string, any>, next: () => Promise<any>): Promise<any>;
 }
 /**
- * Registry for workflow interceptors that are executed in order
- * for each workflow execution
+ * Registry for workflow and activity interceptors that are executed in order
+ * for each workflow or activity execution.
  */
 export interface InterceptorRegistry {
     /**
-     * Array of registered interceptors that will wrap workflow execution
-     * in the order they were registered (first registered = outermost wrapper)
+     * Array of registered workflow interceptors that will wrap workflow execution
+     * in the order they were registered (first registered = outermost wrapper).
      */
     interceptors: WorkflowInterceptor[];
+    /**
+     * Array of registered activity interceptors that will wrap individual
+     * proxied activity calls in the order they were registered
+     * (first registered = outermost wrapper).
+     */
+    activityInterceptors: ActivityInterceptor[];
 }
 /**
  * Context provided to an activity interceptor, containing metadata
@@ -624,11 +630,21 @@ export interface ActivityInterceptorContext {
  * workflow methods (proxyActivities, sleepFor, waitFor, execChild, etc.)
  * are available.
  *
- * Activity interceptors execute BEFORE the activity registers with the
- * interruptionRegistry and throws. Any Durable operations called within
- * the interceptor will register their own interruptions first, and those
- * will be processed before the wrapped activity's interruption during
- * the replay cycle.
+ * Activity interceptors wrap proxied activity calls in an onion pattern,
+ * supporting both **before** and **after** phases:
+ *
+ * - **Before phase** (code before `await next()`): Runs before the activity
+ *   executes. The interceptor can inspect or modify `activityCtx.args` to
+ *   transform the activity input before it is sent.
+ *
+ * - **After phase** (code after `await next()`): Runs on replay once the
+ *   activity result is available. The interceptor receives the activity
+ *   output as the return value of `next()` and can inspect or transform it.
+ *
+ * On first execution, `next()` registers the activity with the interruption
+ * system and throws (the activity has not completed yet). On replay, `next()`
+ * returns the stored result and the after-phase code executes. This follows
+ * the same deterministic replay pattern as workflow interceptors.
  *
  * @example
  * ```typescript
@@ -653,11 +669,13 @@ export interface ActivityInterceptorContext {
  */
 export interface ActivityInterceptor {
     /**
-     * Called before each proxied activity invocation.
+     * Called around each proxied activity invocation. Code before `next()`
+     * runs in the before phase; code after `next()` runs in the after phase
+     * once the activity result is available on replay.
      *
-     * @param activityCtx - Metadata about the activity being called
+     * @param activityCtx - Metadata about the activity being called (args may be modified)
      * @param workflowCtx - The workflow context map (same as WorkflowInterceptor receives)
-     * @param next - Call to proceed to the next interceptor or the actual activity registration
+     * @param next - Call to proceed to the next interceptor or the core activity function
      * @returns The activity result (from replay or after interruption/re-execution)
      */
     execute(activityCtx: ActivityInterceptorContext, workflowCtx: Map<string, any>, next: () => Promise<any>): Promise<any>;

package/build/types/exporter.d.ts

@@ -79,3 +79,130 @@ export interface JobExport {
     process: StringAnyType;
     status: string;
 }
+export type ExportMode = 'sparse' | 'verbose';
+export type WorkflowEventType = 'workflow_execution_started' | 'workflow_execution_completed' | 'workflow_execution_failed' | 'activity_task_scheduled' | 'activity_task_completed' | 'activity_task_failed' | 'child_workflow_execution_started' | 'child_workflow_execution_completed' | 'child_workflow_execution_failed' | 'timer_started' | 'timer_fired' | 'workflow_execution_signaled';
+export type WorkflowEventCategory = 'workflow' | 'activity' | 'child_workflow' | 'timer' | 'signal';
+export interface WorkflowExecutionStartedAttributes {
+    kind: 'workflow_execution_started';
+    workflow_type: string;
+    task_queue: string;
+    input?: any;
+}
+export interface WorkflowExecutionCompletedAttributes {
+    kind: 'workflow_execution_completed';
+    result?: any;
+}
+export interface WorkflowExecutionFailedAttributes {
+    kind: 'workflow_execution_failed';
+    failure?: string;
+}
+export interface ActivityTaskScheduledAttributes {
+    kind: 'activity_task_scheduled';
+    activity_type: string;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ActivityTaskCompletedAttributes {
+    kind: 'activity_task_completed';
+    activity_type: string;
+    result?: any;
+    scheduled_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ActivityTaskFailedAttributes {
+    kind: 'activity_task_failed';
+    activity_type: string;
+    failure?: any;
+    scheduled_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ChildWorkflowExecutionStartedAttributes {
+    kind: 'child_workflow_execution_started';
+    child_workflow_id: string;
+    awaited: boolean;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ChildWorkflowExecutionCompletedAttributes {
+    kind: 'child_workflow_execution_completed';
+    child_workflow_id: string;
+    result?: any;
+    initiated_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ChildWorkflowExecutionFailedAttributes {
+    kind: 'child_workflow_execution_failed';
+    child_workflow_id: string;
+    failure?: any;
+    initiated_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface TimerStartedAttributes {
+    kind: 'timer_started';
+    duration_ms?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface TimerFiredAttributes {
+    kind: 'timer_fired';
+    timeline_key: string;
+    execution_index: number;
+}
+export interface WorkflowExecutionSignaledAttributes {
+    kind: 'workflow_execution_signaled';
+    signal_name: string;
+    input?: any;
+    timeline_key: string;
+    execution_index: number;
+}
+export type WorkflowEventAttributes = WorkflowExecutionStartedAttributes | WorkflowExecutionCompletedAttributes | WorkflowExecutionFailedAttributes | ActivityTaskScheduledAttributes | ActivityTaskCompletedAttributes | ActivityTaskFailedAttributes | ChildWorkflowExecutionStartedAttributes | ChildWorkflowExecutionCompletedAttributes | ChildWorkflowExecutionFailedAttributes | TimerStartedAttributes | TimerFiredAttributes | WorkflowExecutionSignaledAttributes;
+export interface WorkflowExecutionEvent {
+    event_id: number;
+    event_type: WorkflowEventType;
+    category: WorkflowEventCategory;
+    event_time: string;
+    duration_ms: number | null;
+    is_system: boolean;
+    attributes: WorkflowEventAttributes;
+}
+export interface WorkflowExecutionSummary {
+    total_events: number;
+    activities: {
+        total: number;
+        completed: number;
+        failed: number;
+        system: number;
+        user: number;
+    };
+    child_workflows: {
+        total: number;
+        completed: number;
+        failed: number;
+    };
+    timers: number;
+    signals: number;
+}
+export type WorkflowExecutionStatus = 'running' | 'completed' | 'failed';
+export interface WorkflowExecution {
+    workflow_id: string;
+    workflow_type: string;
+    task_queue: string;
+    status: WorkflowExecutionStatus;
+    start_time: string | null;
+    close_time: string | null;
+    duration_ms: number | null;
+    result: any;
+    events: WorkflowExecutionEvent[];
+    summary: WorkflowExecutionSummary;
+    children?: WorkflowExecution[];
+}
+export interface ExecutionExportOptions {
+    mode?: ExportMode;
+    exclude_system?: boolean;
+    omit_results?: boolean;
+    max_depth?: number;
+}

package/build/types/index.d.ts

@@ -6,7 +6,7 @@ export { CollationFaultType, CollationStage } from './collator';
 export { ActivityConfig, ActivityInterceptor, ActivityInterceptorContext, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ClientWorkflow, ContextType, Connection, ProxyResponseType, ProxyType, Registry, SignalOptions, FindJobsOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, SearchResults, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowContext, WorkflowSearchOptions, WorkflowSearchSchema, WorkflowDataType, WorkflowOptions, WorkflowInterceptor, InterceptorRegistry, } from './durable';
 export { PruneOptions, PruneResult, } from './dba';
 export { DurableChildErrorType, DurableProxyErrorType, DurableSleepErrorType, DurableWaitForAllErrorType, DurableWaitForErrorType, } from './error';
-export { ActivityAction, DependencyExport, DurableJobExport, ExportCycles, ExportItem, ExportOptions, ExportTransitions, JobAction, JobExport, JobActionExport, JobTimeline, } from './exporter';
+export { ActivityAction, DependencyExport, DurableJobExport, ExecutionExportOptions, ExportCycles, ExportItem, ExportMode, ExportOptions, ExportTransitions, JobAction, JobExport, JobActionExport, JobTimeline, WorkflowEventAttributes, WorkflowEventCategory, WorkflowEventType, WorkflowExecution, WorkflowExecutionEvent, WorkflowExecutionStatus, WorkflowExecutionSummary, } from './exporter';
 export { HookCondition, HookConditions, HookGate, HookInterface, HookRule, HookRules, HookSignal, } from './hook';
 export { HotMesh, HotMeshEngine, HotMeshWorker, HotMeshSettings, HotMeshApp, HotMeshApps, HotMeshConfig, HotMeshManifest, HotMeshGraph, KeyType, KeyStoreParams, ScoutType, } from './hotmesh';
 export { ILogger, LogLevel } from './logger';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -46,6 +46,8 @@
     "test:durable:sleep": "vitest run tests/durable/sleep/postgres.test.ts",
     "test:durable:signal": "vitest run tests/durable/signal/postgres.test.ts",
     "test:durable:unknown": "vitest run tests/durable/unknown/postgres.test.ts",
+    "test:durable:exporter": "vitest run tests/durable/exporter/exporter.test.ts",
+    "test:durable:exporter:debug": "EXPORT_DEBUG=1 HMSH_LOGLEVEL=error vitest run tests/durable/basic/postgres.test.ts",
     "test:dba": "vitest run tests/dba",
     "test:cycle": "vitest run tests/functional/cycle",
     "test:functional": "vitest run tests/functional",
@@ -110,13 +112,12 @@
     "nats": "^2.28.0",
     "openai": "^5.9.0",
     "pg": "^8.10.0",
-    "rimraf": "^4.4.1",
+    "rimraf": "^6.1.3",
     "terser": "^5.37.0",
     "ts-node": "^10.9.1",
-    "ts-node-dev": "^2.0.0",
     "typedoc": "^0.26.4",
     "typescript": "^5.0.4",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "nats": "^2.0.0",