@hotmeshio/hotmesh 0.12.1 → 0.13.0

package/build/modules/errors.d.ts

@@ -21,6 +21,7 @@ declare class DurableWaitForError extends Error {
 declare class DurableProxyError extends Error {
     activityName: string;
     arguments: string[];
+    argumentMetadata?: Record<string, any>;
     backoffCoefficient: number;
     code: number;
     index: number;

package/build/modules/errors.js

@@ -32,6 +32,7 @@ class DurableProxyError extends Error {
         super(`ProxyActivity Interruption`);
         this.type = 'DurableProxyError';
         this.arguments = params.arguments;
+        this.argumentMetadata = params.argumentMetadata;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
         this.parentWorkflowId = params.parentWorkflowId;

package/build/modules/storage.d.ts

@@ -1,3 +1,4 @@
 /// <reference types="node" />
 import { AsyncLocalStorage } from 'async_hooks';
 export declare const asyncLocalStorage: AsyncLocalStorage<Map<string, any>>;
+export declare const activityAsyncLocalStorage: AsyncLocalStorage<Map<string, any>>;

package/build/modules/storage.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.asyncLocalStorage = void 0;
+exports.activityAsyncLocalStorage = exports.asyncLocalStorage = void 0;
 const async_hooks_1 = require("async_hooks");
 exports.asyncLocalStorage = new async_hooks_1.AsyncLocalStorage();
+exports.activityAsyncLocalStorage = new async_hooks_1.AsyncLocalStorage();

package/build/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.12.1",
-    "description": "Permanent-Memory Workflows & AI Agents",
+    "version": "0.13.0",
+    "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
     "homepage": "https://github.com/hotmeshio/sdk-typescript/",
@@ -33,6 +33,7 @@
         "test:durable:fatal": "vitest run tests/durable/fatal",
         "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
         "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",
+        "test:durable:metadata": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts -t 'argumentMetadata'",
         "test:durable:entity": "HMSH_LOGLEVEL=debug vitest run tests/durable/entity/postgres.test.ts",
         "test:durable:agent": "HMSH_LOGLEVEL=debug vitest run tests/durable/agent/postgres.test.ts",
         "test:durable:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=info vitest run tests/durable/helloworld/postgres.test.ts",

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

@@ -29,7 +29,7 @@ import { PostgresClientType } from '../../types/postgres';
  * from completed jobs while preserving:
  * - `jdata` — workflow return data
  * - `udata` — user-searchable data
- * - `jmark` — timeline markers needed for Temporal-compatible export
+ * - `jmark` — timeline markers needed for workflow execution export
  *
  * Set `keepHmark: true` to also preserve `hmark` (activity state markers).
  *
@@ -63,11 +63,14 @@ import { PostgresClientType } from '../../types/postgres';
  *   jobs: false, streams: false, attributes: true,
  * });
  *
- * // Cron 2 — Hourly: remove processed stream messages older than 24h
+ * // Cron 2 — Hourly: aggressive engine stream cleanup, conservative worker streams
  * await DBA.prune({
  *   appId: 'myapp', connection,
- *   expire: '24 hours',
- *   jobs: false, streams: true,
+ *   jobs: false, attributes: false,
+ *   engineStreams: true,
+ *   engineStreamsExpire: '24 hours',
+ *   workerStreams: true,
+ *   workerStreamsExpire: '90 days',  // preserve for export fidelity
  * });
  *
  * // Cron 3 — Weekly: remove expired 'book' jobs older than 30 days
@@ -101,6 +104,13 @@ import { PostgresClientType } from '../../types/postgres';
  *
  * -- Prune everything older than 7 days and strip attributes
  * SELECT * FROM myapp.prune('7 days', true, true, true);
+ *
+ * -- Independent stream retention: engine 24h, worker 90 days
+ * SELECT * FROM myapp.prune(
+ *   '7 days', true, false, false, NULL, false, false,
+ *   true, true,                          -- prune_engine_streams, prune_worker_streams
+ *   INTERVAL '24 hours', INTERVAL '90 days'  -- per-table retention
+ * );
  * ```
  */
 declare class DBA {

package/build/services/dba/index.js

@@ -32,7 +32,7 @@ const postgres_1 = require("../connector/providers/postgres");
  * from completed jobs while preserving:
  * - `jdata` — workflow return data
  * - `udata` — user-searchable data
- * - `jmark` — timeline markers needed for Temporal-compatible export
+ * - `jmark` — timeline markers needed for workflow execution export
  *
  * Set `keepHmark: true` to also preserve `hmark` (activity state markers).
  *
@@ -66,11 +66,14 @@ const postgres_1 = require("../connector/providers/postgres");
  *   jobs: false, streams: false, attributes: true,
  * });
  *
- * // Cron 2 — Hourly: remove processed stream messages older than 24h
+ * // Cron 2 — Hourly: aggressive engine stream cleanup, conservative worker streams
  * await DBA.prune({
  *   appId: 'myapp', connection,
- *   expire: '24 hours',
- *   jobs: false, streams: true,
+ *   jobs: false, attributes: false,
+ *   engineStreams: true,
+ *   engineStreamsExpire: '24 hours',
+ *   workerStreams: true,
+ *   workerStreamsExpire: '90 days',  // preserve for export fidelity
  * });
  *
  * // Cron 3 — Weekly: remove expired 'book' jobs older than 30 days
@@ -104,6 +107,13 @@ const postgres_1 = require("../connector/providers/postgres");
  *
  * -- Prune everything older than 7 days and strip attributes
  * SELECT * FROM myapp.prune('7 days', true, true, true);
+ *
+ * -- Independent stream retention: engine 24h, worker 90 days
+ * SELECT * FROM myapp.prune(
+ *   '7 days', true, false, false, NULL, false, false,
+ *   true, true,                          -- prune_engine_streams, prune_worker_streams
+ *   INTERVAL '24 hours', INTERVAL '90 days'  -- per-table retention
+ * );
  * ```
  */
 class DBA {
@@ -172,11 +182,17 @@ class DBA {
         strip_attributes BOOLEAN DEFAULT FALSE,
         entity_list TEXT[] DEFAULT NULL,
         prune_transient BOOLEAN DEFAULT FALSE,
-        keep_hmark BOOLEAN DEFAULT FALSE
+        keep_hmark BOOLEAN DEFAULT FALSE,
+        prune_engine_streams BOOLEAN DEFAULT NULL,
+        prune_worker_streams BOOLEAN DEFAULT NULL,
+        engine_streams_retention INTERVAL DEFAULT NULL,
+        worker_streams_retention INTERVAL DEFAULT NULL
       )
       RETURNS TABLE(
         deleted_jobs BIGINT,
         deleted_streams BIGINT,
+        deleted_engine_streams BIGINT,
+        deleted_worker_streams BIGINT,
         stripped_attributes BIGINT,
         deleted_transient BIGINT,
         marked_pruned BIGINT
@@ -185,12 +201,22 @@ class DBA {
       AS $$
       DECLARE
         v_deleted_jobs BIGINT := 0;
-        v_deleted_streams BIGINT := 0;
+        v_deleted_engine_streams BIGINT := 0;
+        v_deleted_worker_streams BIGINT := 0;
         v_stripped_attributes BIGINT := 0;
         v_deleted_transient BIGINT := 0;
         v_marked_pruned BIGINT := 0;
-        v_temp_count BIGINT := 0;
+        v_do_engine BOOLEAN;
+        v_do_worker BOOLEAN;
+        v_engine_retention INTERVAL;
+        v_worker_retention INTERVAL;
       BEGIN
+        -- Resolve per-table overrides (fall back to legacy prune_streams + retention)
+        v_do_engine := COALESCE(prune_engine_streams, prune_streams);
+        v_do_worker := COALESCE(prune_worker_streams, prune_streams);
+        v_engine_retention := COALESCE(engine_streams_retention, retention);
+        v_worker_retention := COALESCE(worker_streams_retention, retention);
+
         -- 1. Hard-delete expired jobs older than the retention window.
         --    FK CASCADE on jobs_attributes handles attribute cleanup.
         --    Optionally scoped to an entity allowlist.
@@ -211,22 +237,23 @@ class DBA {
           GET DIAGNOSTICS v_deleted_transient = ROW_COUNT;
         END IF;
 
-        -- 3. Hard-delete expired stream messages older than the retention window.
-        --    Deletes from both engine_streams and worker_streams tables.
-        IF prune_streams THEN
+        -- 3. Hard-delete expired engine stream messages.
+        IF v_do_engine THEN
           DELETE FROM ${schema}.engine_streams
           WHERE expired_at IS NOT NULL
-            AND expired_at < NOW() - retention;
-          GET DIAGNOSTICS v_deleted_streams = ROW_COUNT;
+            AND expired_at < NOW() - v_engine_retention;
+          GET DIAGNOSTICS v_deleted_engine_streams = ROW_COUNT;
+        END IF;
 
+        -- 4. Hard-delete expired worker stream messages.
+        IF v_do_worker THEN
           DELETE FROM ${schema}.worker_streams
           WHERE expired_at IS NOT NULL
-            AND expired_at < NOW() - retention;
-          GET DIAGNOSTICS v_temp_count = ROW_COUNT;
-          v_deleted_streams := v_deleted_streams + v_temp_count;
+            AND expired_at < NOW() - v_worker_retention;
+          GET DIAGNOSTICS v_deleted_worker_streams = ROW_COUNT;
         END IF;
 
-        -- 4. Strip execution artifacts from completed, live, un-pruned jobs.
+        -- 5. Strip execution artifacts from completed, live, un-pruned jobs.
         --    Always preserves: jdata, udata, jmark (timeline/export history).
         --    Optionally preserves: hmark (when keep_hmark is true).
         IF strip_attributes THEN
@@ -261,7 +288,9 @@ class DBA {
         END IF;
 
         deleted_jobs := v_deleted_jobs;
-        deleted_streams := v_deleted_streams;
+        deleted_streams := v_deleted_engine_streams + v_deleted_worker_streams;
+        deleted_engine_streams := v_deleted_engine_streams;
+        deleted_worker_streams := v_deleted_worker_streams;
         stripped_attributes := v_stripped_attributes;
         deleted_transient := v_deleted_transient;
         marked_pruned := v_marked_pruned;
@@ -357,14 +386,24 @@ class DBA {
         const entities = options.entities ?? null;
         const pruneTransient = options.pruneTransient ?? false;
         const keepHmark = options.keepHmark ?? false;
+        // Per-table overrides (NULL = fall back to streams/expire in SQL)
+        const engineStreams = options.engineStreams ?? null;
+        const workerStreams = options.workerStreams ?? null;
+        const engineStreamsExpire = options.engineStreamsExpire ?? null;
+        const workerStreamsExpire = options.workerStreamsExpire ?? null;
         await DBA.deploy(options.connection, options.appId);
         const { client, release } = await DBA.getClient(options.connection);
         try {
-            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean)`, [expire, jobs, streams, attributes, entities, pruneTransient, keepHmark]);
+            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean, $8::boolean, $9::boolean, $10::interval, $11::interval)`, [
+                expire, jobs, streams, attributes, entities, pruneTransient, keepHmark,
+                engineStreams, workerStreams, engineStreamsExpire, workerStreamsExpire,
+            ]);
             const row = result.rows[0];
             return {
                 jobs: Number(row.deleted_jobs),
                 streams: Number(row.deleted_streams),
+                engineStreams: Number(row.deleted_engine_streams),
+                workerStreams: Number(row.deleted_worker_streams),
                 attributes: Number(row.stripped_attributes),
                 transient: Number(row.deleted_transient),
                 marked: Number(row.marked_pruned),

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

@@ -0,0 +1,30 @@
+import { DurableActivityContext } from '../../types/durable';
+/**
+ * The activity-internal API surface, exposed as `Durable.activity`. Methods
+ * on this class are designed to be called **inside** an activity function —
+ * they read from the activity's `AsyncLocalStorage` context that is populated
+ * by the activity worker before invoking the user's function.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function processData(data: string): Promise<string> {
+ *   const ctx = Durable.activity.getContext();
+ *   console.log(`Activity ${ctx.activityName} for workflow ${ctx.workflowId}`);
+ *   console.log(`Metadata:`, ctx.argumentMetadata);
+ *   return `Processed: ${data}`;
+ * }
+ * ```
+ */
+export declare class ActivityService {
+    /**
+     * Returns the current activity's execution context. Only available
+     * inside an activity function invoked by the durable activity worker.
+     *
+     * @returns The activity context including name, args, metadata, and parent workflow info.
+     * @throws If called outside of an activity execution context.
+     */
+    static getContext(): DurableActivityContext;
+}

package/build/services/durable/activity.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityService = void 0;
+const storage_1 = require("../../modules/storage");
+/**
+ * The activity-internal API surface, exposed as `Durable.activity`. Methods
+ * on this class are designed to be called **inside** an activity function —
+ * they read from the activity's `AsyncLocalStorage` context that is populated
+ * by the activity worker before invoking the user's function.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function processData(data: string): Promise<string> {
+ *   const ctx = Durable.activity.getContext();
+ *   console.log(`Activity ${ctx.activityName} for workflow ${ctx.workflowId}`);
+ *   console.log(`Metadata:`, ctx.argumentMetadata);
+ *   return `Processed: ${data}`;
+ * }
+ * ```
+ */
+class ActivityService {
+    /**
+     * Returns the current activity's execution context. Only available
+     * inside an activity function invoked by the durable activity worker.
+     *
+     * @returns The activity context including name, args, metadata, and parent workflow info.
+     * @throws If called outside of an activity execution context.
+     */
+    static getContext() {
+        const store = storage_1.activityAsyncLocalStorage.getStore();
+        if (!store) {
+            throw new Error('Durable.activity.getContext() called outside of an activity execution context');
+        }
+        return {
+            activityName: store.get('activityName'),
+            arguments: store.get('arguments'),
+            argumentMetadata: store.get('argumentMetadata') ?? {},
+            workflowId: store.get('workflowId'),
+            workflowTopic: store.get('workflowTopic'),
+        };
+    }
+}
+exports.ActivityService = ActivityService;

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

@@ -1,8 +1,8 @@
 import { HotMesh } from '../hotmesh';
 import { ClientConfig, ClientWorkflow, Connection, WorkflowOptions } from '../../types/durable';
 /**
- * The Durable `Client` service is functionally
- * equivalent to the Temporal `Client` service.
+ * The Durable `Client` service provides methods for
+ * starting, signaling, and querying workflows.
  * Start a new workflow execution by calling
  * `workflow.start`. Note the direct connection to
  * Postgres.
@@ -81,8 +81,8 @@ export declare class ClientService {
      */
     search: (hotMeshClient: HotMesh, index: string, query: string[]) => Promise<string[]>;
     /**
-     * The Durable `Client` service is functionally
-     * equivalent to the Temporal `Client` service.
+     * The Durable `Client` service provides methods for
+     * starting, signaling, and querying workflows.
      * Starting a workflow is the primary use case and
      * is accessed by calling workflow.start().
      */

package/build/services/durable/client.js

@@ -11,8 +11,8 @@ const search_1 = require("./search");
 const handle_1 = require("./handle");
 const factory_1 = require("./schemas/factory");
 /**
- * The Durable `Client` service is functionally
- * equivalent to the Temporal `Client` service.
+ * The Durable `Client` service provides methods for
+ * starting, signaling, and querying workflows.
  * Start a new workflow execution by calling
  * `workflow.start`. Note the direct connection to
  * Postgres.
@@ -114,8 +114,8 @@ class ClientService {
             return await searchClient.sendIndexedQuery(index, query);
         };
         /**
-         * The Durable `Client` service is functionally
-         * equivalent to the Temporal `Client` service.
+         * The Durable `Client` service provides methods for
+         * starting, signaling, and querying workflows.
          * Starting a workflow is the primary use case and
          * is accessed by calling workflow.start().
          */

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

@@ -54,7 +54,7 @@ declare class ExporterService {
      */
     export(jobId: string, options?: ExportOptions): Promise<DurableJobExport>;
     /**
-     * Export a workflow execution as a Temporal-compatible event history.
+     * Export a workflow execution as a structured event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list. No additional I/O beyond the initial export.
@@ -80,7 +80,7 @@ declare class ExporterService {
     private resolveSymbolField;
     /**
      * Pure transformation: convert a raw DurableJobExport into a
-     * Temporal-compatible WorkflowExecution event history.
+     * WorkflowExecution event history.
      */
     transformToExecution(raw: DurableJobExport, workflowId: string, workflowTopic: string, options: ExecutionExportOptions): WorkflowExecution;
     /**

package/build/services/durable/exporter.js

@@ -173,7 +173,7 @@ class ExporterService {
         return jobExport;
     }
     /**
-     * Export a workflow execution as a Temporal-compatible event history.
+     * Export a workflow execution as a structured event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list. No additional I/O beyond the initial export.
@@ -510,28 +510,43 @@ class ExporterService {
                 }
             }
         }
-        // ── 3. Stream-based fallback for unenriched activity events ──
-        // When job attributes have been pruned, recover inputs from worker_streams
+        // ── 3. Stream-based enrichment from worker_streams ──
+        // Fetches worker invocation messages to recover:
+        // - Workflow input arguments (for workflow_execution_started)
+        // - Activity inputs when job attributes have been pruned
         if (this.store.getStreamHistory) {
-            const unenrichedEvents = execution.events.filter((e) => (e.event_type === 'activity_task_scheduled' ||
+            const unenrichedActivityEvents = execution.events.filter((e) => (e.event_type === 'activity_task_scheduled' ||
                 e.event_type === 'activity_task_completed' ||
                 e.event_type === 'activity_task_failed') &&
                 e.attributes.input === undefined);
-            if (unenrichedEvents.length > 0) {
-                const streamHistory = await this.store.getStreamHistory(workflowId, {
-                    types: ['worker'],
-                });
+            const startedEvent = execution.events.find((e) => e.event_type === 'workflow_execution_started');
+            const startedNeedsInput = startedEvent &&
+                (!(startedEvent.attributes.input) ||
+                    Object.keys(startedEvent.attributes.input).length === 0);
+            if (unenrichedActivityEvents.length > 0 || startedNeedsInput) {
+                const streamHistory = await this.store.getStreamHistory(workflowId);
                 // Build a map of aid -> stream message data (the worker invocation inputs)
                 const streamInputsByAid = new Map();
                 for (const entry of streamHistory) {
-                    if (entry.msg_type === 'worker' && entry.data) {
+                    if (entry.data) {
                         const key = `${entry.aid}:${entry.dad || ''}`;
                         if (!streamInputsByAid.has(key)) {
                             streamInputsByAid.set(key, entry.data);
                         }
                     }
                 }
-                for (const evt of unenrichedEvents) {
+                // Enrich workflow_execution_started with input arguments from the
+                // first worker invocation message (aid="worker", data.arguments=[...])
+                if (startedNeedsInput) {
+                    const workerEntry = streamHistory.find((entry) => entry.aid === 'worker' &&
+                        entry.jid === workflowId &&
+                        entry.data?.arguments);
+                    if (workerEntry) {
+                        startedEvent.attributes.input = workerEntry.data.arguments;
+                    }
+                }
+                // Enrich unenriched activity events
+                for (const evt of unenrichedActivityEvents) {
                     const attrs = evt.attributes;
                     // Try matching by activity_type + dimensional address
                     const key = `${attrs.activity_type}:${attrs.timeline_key || ''}`;
@@ -571,7 +586,7 @@ class ExporterService {
     }
     /**
      * Pure transformation: convert a raw DurableJobExport into a
-     * Temporal-compatible WorkflowExecution event history.
+     * WorkflowExecution event history.
      */
     transformToExecution(raw, workflowId, workflowTopic, options) {
         const events = [];
@@ -761,7 +776,7 @@ class ExporterService {
         for (let i = 0; i < events.length; i++) {
             events[i].event_id = i + 1;
         }
-        // ── Back-references (Temporal-compatible) ────────────────────
+        // ── Back-references ────────────────────────────────────────
         const scheduledMap = new Map();
         const initiatedMap = new Map();
         for (const e of events) {

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

@@ -45,7 +45,7 @@ export declare class WorkflowHandleService {
      */
     export(options?: ExportOptions): Promise<DurableJobExport>;
     /**
-     * Exports the workflow as a Temporal-like execution event history.
+     * Exports the workflow as an execution event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list with workflow lifecycle, activity, child workflow,

package/build/services/durable/handle.js

@@ -44,7 +44,7 @@ class WorkflowHandleService {
         return this.exporter.export(this.workflowId, options);
     }
     /**
-     * Exports the workflow as a Temporal-like execution event history.
+     * Exports the workflow as an execution event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list with workflow lifecycle, activity, child workflow,

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

@@ -4,14 +4,15 @@ import { ClientService } from './client';
 import { ConnectionService } from './connection';
 import { Search } from './search';
 import { Entity } from './entity';
+import { ActivityService } from './activity';
 import { WorkerService } from './worker';
 import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
 import { didInterrupt } from './workflow/interruption';
 /**
- * The Durable service provides a Temporal-compatible workflow framework backed
- * by Postgres. It offers entity-based memory management and composable,
- * fault-tolerant workflows.
+ * The Durable service provides a workflow framework backed by Postgres.
+ * It offers entity-based memory management and composable, fault-tolerant
+ * workflows authored in a familiar procedural style.
  *
  * ## Core Features
  *
@@ -277,12 +278,12 @@ declare class DurableClass {
     constructor();
     /**
      * The Durable `Client` service is functionally
-     * equivalent to the Temporal `Client` service.
+     * provides methods for starting, signaling, and querying workflows.
      */
     static Client: typeof ClientService;
     /**
-     * The Durable `Connection` service is functionally
-     * equivalent to the Temporal `Connection` service.
+     * The Durable `Connection` service
+     * manages database connections for the durable workflow engine.
      */
     static Connection: typeof ConnectionService;
     /**
@@ -301,8 +302,8 @@ declare class DurableClass {
      */
     static Handle: typeof WorkflowHandleService;
     /**
-     * The Durable `Worker` service is functionally
-     * equivalent to the Temporal `Worker` service.
+     * The Durable `Worker` service
+     * registers workflow and activity workers and connects them to the mesh.
      */
     static Worker: typeof WorkerService;
     /**
@@ -349,10 +350,16 @@ declare class DurableClass {
      */
     static registerActivityWorker: typeof WorkerService.registerActivityWorker;
     /**
-     * The Durable `workflow` service is functionally
-     * equivalent to the Temporal `Workflow` service
-     * with additional methods for managing workflows,
-     * including: `execChild`, `waitFor`, `sleep`, etc
+     * The Durable `activity` service provides context to
+     * executing activity functions. Call `Durable.activity.getContext()`
+     * inside an activity to access metadata, workflow ID, and other
+     * context passed from the parent workflow.
+     */
+    static activity: typeof ActivityService;
+    /**
+     * The Durable `workflow` service
+     * provides the workflow-internal API surface with methods for
+     * managing workflows, including: `execChild`, `waitFor`, `sleep`, etc
      */
     static workflow: typeof WorkflowService;
     /**

package/build/services/durable/index.js

@@ -7,15 +7,16 @@ const client_1 = require("./client");
 const connection_1 = require("./connection");
 const search_1 = require("./search");
 const entity_1 = require("./entity");
+const activity_1 = require("./activity");
 const worker_1 = require("./worker");
 const workflow_1 = require("./workflow");
 const handle_1 = require("./handle");
 const interruption_1 = require("./workflow/interruption");
 const interceptor_1 = require("./interceptor");
 /**
- * The Durable service provides a Temporal-compatible workflow framework backed
- * by Postgres. It offers entity-based memory management and composable,
- * fault-tolerant workflows.
+ * The Durable service provides a workflow framework backed by Postgres.
+ * It offers entity-based memory management and composable, fault-tolerant
+ * workflows authored in a familiar procedural style.
  *
  * ## Core Features
  *
@@ -381,12 +382,12 @@ class DurableClass {
 exports.Durable = DurableClass;
 /**
  * The Durable `Client` service is functionally
- * equivalent to the Temporal `Client` service.
+ * provides methods for starting, signaling, and querying workflows.
  */
 DurableClass.Client = client_1.ClientService;
 /**
- * The Durable `Connection` service is functionally
- * equivalent to the Temporal `Connection` service.
+ * The Durable `Connection` service
+ * manages database connections for the durable workflow engine.
  */
 DurableClass.Connection = connection_1.ConnectionService;
 /**
@@ -405,8 +406,8 @@ DurableClass.Entity = entity_1.Entity;
  */
 DurableClass.Handle = handle_1.WorkflowHandleService;
 /**
- * The Durable `Worker` service is functionally
- * equivalent to the Temporal `Worker` service.
+ * The Durable `Worker` service
+ * registers workflow and activity workers and connects them to the mesh.
  */
 DurableClass.Worker = worker_1.WorkerService;
 /**
@@ -453,10 +454,16 @@ DurableClass.Worker = worker_1.WorkerService;
  */
 DurableClass.registerActivityWorker = worker_1.WorkerService.registerActivityWorker;
 /**
- * The Durable `workflow` service is functionally
- * equivalent to the Temporal `Workflow` service
- * with additional methods for managing workflows,
- * including: `execChild`, `waitFor`, `sleep`, etc
+ * The Durable `activity` service provides context to
+ * executing activity functions. Call `Durable.activity.getContext()`
+ * inside an activity to access metadata, workflow ID, and other
+ * context passed from the parent workflow.
+ */
+DurableClass.activity = activity_1.ActivityService;
+/**
+ * The Durable `workflow` service
+ * provides the workflow-internal API surface with methods for
+ * managing workflows, including: `execChild`, `waitFor`, `sleep`, etc
  */
 DurableClass.workflow = workflow_1.WorkflowService;
 /**

package/build/services/durable/schemas/factory.d.ts

@@ -2,8 +2,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
@@ -17,7 +16,7 @@
  * * Service Meshes
  * * Master Data Management systems
  */
-declare const APP_VERSION = "8";
+declare const APP_VERSION = "9";
 declare const APP_ID = "durable";
 /**
  * returns a new durable workflow schema

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 = '9';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'durable';
 exports.APP_ID = APP_ID;
@@ -558,6 +557,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                argumentMetadata:
+                  type: object
+                  description: optional metadata to pass alongside activity arguments
                 expire:
                   type: number
                 backoffCoefficient:
@@ -569,6 +571,7 @@ const getWorkflowYAML = (app, version) => {
             maps:
               activityName: '{worker.output.data.activityName}'
               arguments: '{worker.output.data.arguments}'
+              argumentMetadata: '{worker.output.data.argumentMetadata}'
               workflowDimension: '{worker.output.data.workflowDimension}'
               index: '{worker.output.data.index}'
               originJobId: '{worker.output.data.originJobId}'
@@ -1311,6 +1314,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                argumentMetadata:
+                  type: object
+                  description: optional metadata to pass alongside activity arguments
                 expire:
                   type: number
                 backoffCoefficient:
@@ -1322,6 +1328,7 @@ const getWorkflowYAML = (app, version) => {
             maps:
               activityName: '{signaler_worker.output.data.activityName}'
               arguments: '{signaler_worker.output.data.arguments}'
+              argumentMetadata: '{signaler_worker.output.data.argumentMetadata}'
               workflowDimension: '{signaler_worker.output.data.workflowDimension}'
               index: '{signaler_worker.output.data.index}'
               originJobId: '{signaler_worker.output.data.originJobId}'
@@ -2123,6 +2130,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                argumentMetadata:
+                  type: object
+                  description: optional metadata to pass alongside activity arguments
                 expire:
                   type: number
                 backoffCoefficient:
@@ -2142,6 +2152,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
                   - ['{@array.get}', arguments]
                   - ['{@object.get}']
+              argumentMetadata:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', argumentMetadata]
+                  - ['{@object.get}']
               workflowDimension:
                 '@pipe':
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
@@ -2366,6 +2381,8 @@ const getWorkflowYAML = (app, version) => {
               type: string
             arguments:
               type: array
+            argumentMetadata:
+              type: object
             backoffCoefficient:
               type: number
             maximumAttempts:
@@ -2433,12 +2450,15 @@ const getWorkflowYAML = (app, version) => {
                   type: string
                 arguments:
                   type: array
+                argumentMetadata:
+                  type: object
             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}'
+              argumentMetadata: '{activity_trigger.output.data.argumentMetadata}'
           output:
             schema:
               type: object

package/build/services/durable/worker.js

@@ -240,7 +240,13 @@ class WorkerService {
                 if (!activityFunction) {
                     throw new Error(`Activity '${activityName}' not found in registry`);
                 }
-                const pojoResponse = await activityFunction.apply(null, activityInput.arguments);
+                const activityContext = new Map();
+                activityContext.set('activityName', activityName);
+                activityContext.set('arguments', activityInput.arguments);
+                activityContext.set('argumentMetadata', activityInput.argumentMetadata ?? {});
+                activityContext.set('workflowId', activityInput.workflowId);
+                activityContext.set('workflowTopic', activityInput.workflowTopic);
+                const pojoResponse = await storage_1.activityAsyncLocalStorage.run(activityContext, () => activityFunction.apply(null, activityInput.arguments));
                 return {
                     status: stream_1.StreamStatus.SUCCESS,
                     metadata: { ...data.metadata },
@@ -419,7 +425,13 @@ class WorkerService {
                 const activityInput = data.data;
                 const activityName = activityInput.activityName;
                 const activityFunction = WorkerService.activityRegistry[activityName];
-                const pojoResponse = await activityFunction.apply(this, activityInput.arguments);
+                const activityContext = new Map();
+                activityContext.set('activityName', activityName);
+                activityContext.set('arguments', activityInput.arguments);
+                activityContext.set('argumentMetadata', activityInput.argumentMetadata ?? {});
+                activityContext.set('workflowId', activityInput.workflowId);
+                activityContext.set('workflowTopic', activityInput.workflowTopic);
+                const pojoResponse = await storage_1.activityAsyncLocalStorage.run(activityContext, () => activityFunction.apply(this, activityInput.arguments));
                 return {
                     status: stream_1.StreamStatus.SUCCESS,
                     metadata: { ...data.metadata },
@@ -653,6 +665,7 @@ class WorkerService {
                                 dimension: err.workflowDimension,
                             }),
                             arguments: err.arguments,
+                            argumentMetadata: err.argumentMetadata,
                             workflowDimension: err.workflowDimension,
                             index: err.index,
                             originJobId: err.originJobId,

package/build/services/durable/workflow/didRun.d.ts

@@ -7,7 +7,7 @@
  * If that `sessionId` already exists in the `replay` hash (loaded from
  * the job's stored state), the previously persisted result is
  * deserialized and returned — skipping re-execution entirely. This is
- * analogous to Temporal's event history replay.
+ * analogous to event history replay in durable workflow engines.
  *
  * ## Session ID Format
  *

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

@@ -12,7 +12,7 @@ const context_1 = require("./context");
  * If that `sessionId` already exists in the `replay` hash (loaded from
  * the job's stored state), the previously persisted result is
  * deserialized and returned — skipping re-execution entirely. This is
- * analogous to Temporal's event history replay.
+ * analogous to event history replay in durable workflow engines.
  *
  * ## Session ID Format
  *

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

@@ -21,6 +21,7 @@ function getProxyInterruptPayload(context, activityName, execIndex, args, option
     }
     return {
         arguments: args,
+        argumentMetadata: options?.argumentMetadata ?? undefined,
         workflowDimension,
         index: execIndex,
         originJobId: originJobId || workflowId,
@@ -53,7 +54,7 @@ function wrapActivity(activityName, options) {
         const coreFunction = async () => {
             if (didRunAlready) {
                 if (result?.$error) {
-                    if (options?.retryPolicy?.throwOnError !== false) {
+                    if (activityCtx.options?.retryPolicy?.throwOnError !== false) {
                         const code = result.$error.code;
                         const message = result.$error.message;
                         const stack = result.$error.stack;
@@ -74,7 +75,7 @@ function wrapActivity(activityName, options) {
                 }
                 return result.data;
             }
-            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, activityCtx.args, options);
+            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, activityCtx.args, activityCtx.options);
             interruptionRegistry.push({
                 code: common_1.HMSH_CODE_DURABLE_PROXY,
                 type: 'DurableProxyError',

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

@@ -160,7 +160,7 @@ import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../
  * ## Higher-Level Modules
  *
  * For most use cases, prefer the higher-level wrappers:
- * - **Durable** — Temporal-style durable workflow functions.
+ * - **Durable** — Durable workflow functions with replay and retry.
  * - **Virtual** — Virtual network functions and idempotent RPC.
  *
  * @see {@link https://hotmeshio.github.io/sdk-typescript/} - API reference

package/build/services/hotmesh/index.js

@@ -161,7 +161,7 @@ const enums_1 = require("../../modules/enums");
  * ## Higher-Level Modules
  *
  * For most use cases, prefer the higher-level wrappers:
- * - **Durable** — Temporal-style durable workflow functions.
+ * - **Durable** — Durable workflow functions with replay and retry.
  * - **Virtual** — Virtual network functions and idempotent RPC.
  *
  * @see {@link https://hotmeshio.github.io/sdk-typescript/} - API reference

package/build/types/dba.d.ts

@@ -37,15 +37,47 @@ export interface PruneOptions {
     jobs?: boolean;
     /**
      * If true, hard-deletes expired stream messages older than the
-     * retention window.
+     * retention window from both `engine_streams` and `worker_streams`.
+     * Use `engineStreams` / `workerStreams` for independent control.
      * @default true
      */
     streams?: boolean;
+    /**
+     * Override for `engine_streams` cleanup. When set, takes precedence
+     * over `streams` for the engine table. Engine streams contain internal
+     * routing messages and can be pruned aggressively.
+     * @default undefined (falls back to `streams`)
+     */
+    engineStreams?: boolean;
+    /**
+     * Override for `worker_streams` cleanup. When set, takes precedence
+     * over `streams` for the worker table. Worker streams contain workflow
+     * input arguments and activity payloads needed by the exporter — use
+     * a longer retention to preserve export fidelity.
+     * @default undefined (falls back to `streams`)
+     */
+    workerStreams?: boolean;
+    /**
+     * Retention override for `engine_streams`. When set, uses this interval
+     * instead of the global `expire` for engine stream cleanup.
+     * @default undefined (falls back to `expire`)
+     *
+     * @example '24 hours'
+     */
+    engineStreamsExpire?: string;
+    /**
+     * Retention override for `worker_streams`. When set, uses this interval
+     * instead of the global `expire` for worker stream cleanup.
+     * @default undefined (falls back to `expire`)
+     *
+     * @example '90 days'
+     */
+    workerStreamsExpire?: string;
     /**
      * 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`.
+     * workflow execution export). See `keepHmark` for `hmark`.
      * @default false
      */
     attributes?: boolean;
@@ -79,8 +111,12 @@ export interface PruneOptions {
 export interface PruneResult {
     /** Number of expired job rows hard-deleted */
     jobs: number;
-    /** Number of expired stream message rows hard-deleted */
+    /** Number of expired stream message rows hard-deleted (engine + worker) */
     streams: number;
+    /** Number of expired engine_streams rows hard-deleted */
+    engineStreams: number;
+    /** Number of expired worker_streams rows hard-deleted */
+    workerStreams: number;
     /** Number of execution-artifact attribute rows stripped from completed jobs */
     attributes: number;
     /** Number of transient (entity IS NULL) job rows hard-deleted */

package/build/types/durable.d.ts

@@ -104,6 +104,23 @@ type WorkflowContext = {
      */
     expire?: number;
 };
+/**
+ * Context available inside an executing activity function via
+ * `Durable.activity.getContext()`. Populated by the activity worker
+ * using `activityAsyncLocalStorage`.
+ */
+type DurableActivityContext = {
+    /** The name of the activity function being executed */
+    activityName: string;
+    /** The arguments passed to the activity */
+    arguments: any[];
+    /** Optional metadata provided via `proxyActivities({ argumentMetadata })` */
+    argumentMetadata: Record<string, any>;
+    /** The workflow ID of the parent workflow that dispatched this activity */
+    workflowId: string;
+    /** The workflow topic of the parent workflow */
+    workflowTopic: string;
+};
 /**
  * The schema for the full-text-search
  * @deprecated
@@ -354,6 +371,7 @@ type SignalOptions = {
 type ActivityWorkflowDataType = {
     activityName: string;
     arguments: any[];
+    argumentMetadata?: Record<string, any>;
     workflowId: string;
     workflowTopic: string;
 };
@@ -494,6 +512,10 @@ type ActivityConfig = {
      * ```
      */
     taskQueue?: string;
+    /** Optional metadata to pass alongside activity arguments. This metadata
+     *  is transported as a dedicated schema field (not inside args) and made
+     *  available to the activity function via `Durable.activity.getContext()`. */
+    argumentMetadata?: Record<string, any>;
     /** Retry policy configuration for activities */
     retryPolicy?: {
         /** Maximum number of retry attempts, default is 5 (HMSH_DURABLE_MAX_ATTEMPTS) */
@@ -685,4 +707,4 @@ export interface ActivityInterceptor {
      */
     execute(activityCtx: ActivityInterceptorContext, workflowCtx: Map<string, any>, next: () => Promise<any>): Promise<any>;
 }
-export { ActivityConfig, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ClientWorkflow, ContextType, Connection, FunctionSignature, ProxyResponseType, ProxyType, Registry, SignalOptions, FindJobsOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, SearchResults, WorkerConfig, WorkflowConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, WorkflowContext, };
+export { ActivityConfig, DurableActivityContext, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ClientWorkflow, ContextType, Connection, FunctionSignature, ProxyResponseType, ProxyType, Registry, SignalOptions, FindJobsOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, SearchResults, WorkerConfig, WorkflowConfig, WorkerOptions, WorkflowSearchOptions, WorkflowDataType, WorkflowOptions, WorkflowContext, };

package/build/types/error.d.ts

@@ -29,6 +29,7 @@ export type DurableWaitForAllErrorType = {
 };
 export type DurableProxyErrorType = {
     arguments: string[];
+    argumentMetadata?: Record<string, any>;
     activityName: string;
     backoffCoefficient?: number;
     index: number;

package/build/types/exporter.d.ts

@@ -251,7 +251,7 @@ export interface ExecutionExportOptions {
      * When true, fetches the full stream message history for this workflow
      * from the worker_streams table and attaches it as `stream_history`.
      * This provides raw activity input/output data from the original stream
-     * messages, enabling Temporal-grade export fidelity.
+     * messages, enabling full export fidelity.
      *
      * @default false
      */

package/build/types/index.d.ts

@@ -3,7 +3,7 @@ export { App, AppVID, AppTransitions, AppSubscriptions } from './app';
 export { AsyncSignal } from './async';
 export { CacheMode } from './cache';
 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 { ActivityConfig, DurableActivityContext, 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, ActivityDetail, ActivityInputMap, ActivityTaskCompletedAttributes, ActivityTaskFailedAttributes, ActivityTaskScheduledAttributes, ChildWorkflowExecutionCompletedAttributes, ChildWorkflowExecutionFailedAttributes, ChildWorkflowExecutionStartedAttributes, DependencyExport, DurableJobExport, ExecutionExportOptions, ExportCycles, ExportFields, ExportItem, ExportMode, ExportOptions, ExportTransitions, JobAction, JobActionExport, JobAttributesRow, JobExport, JobRow, JobTimeline, StreamHistoryEntry, TimelineType, TimerFiredAttributes, TimerStartedAttributes, TransitionType, WorkflowEventAttributes, WorkflowEventCategory, WorkflowEventType, WorkflowExecution, WorkflowExecutionCompletedAttributes, WorkflowExecutionEvent, WorkflowExecutionFailedAttributes, WorkflowExecutionSignaledAttributes, WorkflowExecutionStartedAttributes, WorkflowExecutionStatus, WorkflowExecutionSummary, } from './exporter';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.12.1",
-  "description": "Permanent-Memory Workflows & AI Agents",
+  "version": "0.13.0",
+  "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "homepage": "https://github.com/hotmeshio/sdk-typescript/",
@@ -33,6 +33,7 @@
     "test:durable:fatal": "vitest run tests/durable/fatal",
     "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
     "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",
+    "test:durable:metadata": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts -t 'argumentMetadata'",
     "test:durable:entity": "HMSH_LOGLEVEL=debug vitest run tests/durable/entity/postgres.test.ts",
     "test:durable:agent": "HMSH_LOGLEVEL=debug vitest run tests/durable/agent/postgres.test.ts",
     "test:durable:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=info vitest run tests/durable/helloworld/postgres.test.ts",