@hotmeshio/hotmesh 0.10.2 → 0.12.0

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

@@ -20,7 +20,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APP_ID = exports.APP_VERSION = exports.getWorkflowYAML = void 0;
-const APP_VERSION = '5';
+const APP_VERSION = '8';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'durable';
 exports.APP_ID = APP_ID;
@@ -66,7 +66,13 @@ const getWorkflowYAML = (app, version) => {
               description: the arguments to pass to the flow
               type: array
             workflowTopic:
-              description: the stream topic the worker is listening on
+              description: concatenated taskQueue-workflowName for engine-internal routing
+              type: string
+            taskQueue:
+              description: the task queue name (stream_name in worker_streams)
+              type: string
+            workflowName:
+              description: the workflow function name (workflow_name in worker_streams)
               type: string
             backoffCoefficient:
               description: the time multiple in seconds to backoff before retrying
@@ -155,7 +161,7 @@ const getWorkflowYAML = (app, version) => {
         worker:
           title: Main Worker - Calls linked Workflow functions
           type: worker
-          topic: '{trigger.output.data.workflowTopic}'
+          topic: '{trigger.output.data.taskQueue}'
           emit: '{$job.data.done}'
           input:
             schema:
@@ -169,6 +175,8 @@ const getWorkflowYAML = (app, version) => {
                   type: array
                 workflowTopic:
                   type: string
+                workflowName:
+                  type: string
                 canRetry:
                   type: boolean
                 expire:
@@ -178,6 +186,7 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{trigger.output.data.workflowId}'
               arguments: '{trigger.output.data.arguments}'
               workflowTopic: '{trigger.output.data.workflowTopic}'
+              workflowName: '{trigger.output.data.workflowName}'
               expire: '{trigger.output.data.expire}'
               canRetry:
                 '@pipe':
@@ -348,6 +357,10 @@ const getWorkflowYAML = (app, version) => {
               properties:
                 workflowTopic:
                   type: string
+                taskQueue:
+                  type: string
+                workflowName:
+                  type: string
                 backoffCoefficient:
                   type: number
                 maximumAttempts:
@@ -387,6 +400,7 @@ const getWorkflowYAML = (app, version) => {
               persistent: '{worker.output.data.persistent}'
               signalIn: '{worker.output.data.signalIn}'
               workflowId: '{worker.output.data.workflowId}'
+              taskQueue: '{worker.output.data.taskQueue}'
               workflowName: '{worker.output.data.workflowName}'
               workflowTopic: '{worker.output.data.workflowTopic}'
               entity: '{worker.output.data.entity}'
@@ -893,7 +907,7 @@ const getWorkflowYAML = (app, version) => {
         signaler_worker:
           title: Signal In - Worker
           type: worker
-          topic: '{signaler.hook.data.workflowTopic}'
+          topic: '{signaler.hook.data.taskQueue}'
           input:
             schema:
               type: object
@@ -906,6 +920,8 @@ const getWorkflowYAML = (app, version) => {
                   type: string
                 arguments:
                   type: array
+                workflowName:
+                  type: string
                 canRetry:
                   type: boolean
                 expire:
@@ -915,6 +931,7 @@ const getWorkflowYAML = (app, version) => {
               originJobId: '{trigger.output.data.originJobId}'
               workflowDimension: '{signaler.output.metadata.dad}'
               arguments: '{signaler.hook.data.arguments}'
+              workflowName: '{signaler.hook.data.workflowName}'
               expire: '{trigger.output.data.expire}'
               canRetry:
                 '@pipe':
@@ -1136,6 +1153,7 @@ const getWorkflowYAML = (app, version) => {
               persistent: '{signaler_worker.output.data.persistent}'
               signalIn: '{signaler_worker.output.data.signalIn}'
               workflowId: '{signaler_worker.output.data.workflowId}'
+              taskQueue: '{signaler_worker.output.data.taskQueue}'
               workflowName: '{signaler_worker.output.data.workflowName}'
               workflowTopic: '{signaler_worker.output.data.workflowTopic}'
               entity: '{signaler_worker.output.data.entity}'
@@ -1942,6 +1960,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
                   - ['{@array.get}', workflowId]
                   - ['{@object.get}']
+              taskQueue:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', taskQueue]
+                  - ['{@object.get}']
               workflowName:
                 '@pipe':
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']

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

@@ -200,7 +200,7 @@ export declare class WorkerService {
     /**
      * @private
      */
-    initWorkflowWorker(config: WorkerConfig, workflowTopic: string, workflowFunction: Function): Promise<HotMesh>;
+    initWorkflowWorker(config: WorkerConfig, taskQueue: string, workflowFunctionName: string, workflowTopic: string, workflowFunction: Function): Promise<HotMesh>;
     /**
      * @private
      */
@@ -213,7 +213,7 @@ export declare class WorkerService {
     /**
      * @private
      */
-    wrapWorkflowFunction(workflowFunction: Function, workflowTopic: string, config: WorkerConfig): Function;
+    wrapWorkflowFunction(workflowFunction: Function, workflowTopic: string, workflowFunctionName: string, config: WorkerConfig): Function;
     /**
      * @private
      */

package/build/services/durable/worker.js

@@ -345,13 +345,15 @@ class WorkerService {
     static async create(config) {
         const workflow = config.workflow;
         const [workflowFunctionName, workflowFunction] = WorkerService.resolveWorkflowTarget(workflow);
-        const baseTopic = `${config.taskQueue}-${workflowFunctionName}`;
-        const activityTopic = `${baseTopic}-activity`;
-        const workflowTopic = `${baseTopic}`;
+        // Separate taskQueue from workflowName - no concatenation for stream_name
+        const taskQueue = config.taskQueue;
+        const activityTopic = `${taskQueue}-activity`;
+        // workflowTopic remains concatenated for engine-internal routing (graph.subscribes)
+        const workflowTopic = `${taskQueue}-${workflowFunctionName}`;
         //initialize supporting workflows
         const worker = new WorkerService();
         worker.activityRunner = await worker.initActivityWorker(config, activityTopic);
-        worker.workflowRunner = await worker.initWorkflowWorker(config, workflowTopic, workflowFunction);
+        worker.workflowRunner = await worker.initWorkflowWorker(config, taskQueue, workflowFunctionName, workflowTopic, workflowFunction);
         search_1.Search.configureSearchIndex(worker.workflowRunner, config.search);
         await WorkerService.activateWorkflow(worker.workflowRunner);
         return worker;
@@ -470,7 +472,7 @@ class WorkerService {
     /**
      * @private
      */
-    async initWorkflowWorker(config, workflowTopic, workflowFunction) {
+    async initWorkflowWorker(config, taskQueue, workflowFunctionName, workflowTopic, workflowFunction) {
         const providerConfig = config.connection;
         const targetNamespace = config?.namespace ?? factory_1.APP_ID;
         const optionsHash = WorkerService.hashOptions(config?.connection);
@@ -483,9 +485,10 @@ class WorkerService {
             engine: { connection: providerConfig },
             workers: [
                 {
-                    topic: workflowTopic,
+                    topic: taskQueue,
+                    workflowName: workflowFunctionName,
                     connection: providerConfig,
-                    callback: this.wrapWorkflowFunction(workflowFunction, workflowTopic, config).bind(this),
+                    callback: this.wrapWorkflowFunction(workflowFunction, workflowTopic, workflowFunctionName, config).bind(this),
                 },
             ],
         });
@@ -495,7 +498,7 @@ class WorkerService {
     /**
      * @private
      */
-    wrapWorkflowFunction(workflowFunction, workflowTopic, config) {
+    wrapWorkflowFunction(workflowFunction, workflowTopic, workflowFunctionName, config) {
         return async (data) => {
             const counter = { counter: 0 };
             const interruptionRegistry = [];
@@ -532,7 +535,8 @@ class WorkerService {
                     replayQuery = '-*[ehklptydr]-*';
                 }
                 context.set('workflowTopic', workflowTopic);
-                context.set('workflowName', workflowTopic.split('-').pop());
+                context.set('workflowName', workflowFunctionName);
+                context.set('taskQueue', config.taskQueue);
                 context.set('workflowTrace', data.metadata.trc);
                 context.set('workflowSpan', data.metadata.spn);
                 const store = this.workflowRunner.engine.store;
@@ -693,6 +697,8 @@ class WorkerService {
                             workflowDimension: err.workflowDimension,
                             workflowId: err.workflowId,
                             workflowTopic: err.workflowTopic,
+                            taskQueue: err.taskQueue,
+                            workflowName: err.workflowName,
                         },
                     };
                 }

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

@@ -57,6 +57,7 @@ function getContext() {
     const interruptionRegistry = store.get('interruptionRegistry');
     const workflowDimension = store.get('workflowDimension') ?? '';
     const workflowTopic = store.get('workflowTopic');
+    const taskQueue = store.get('taskQueue');
     const connection = store.get('connection');
     const namespace = store.get('namespace');
     const originJobId = store.get('originJobId');
@@ -78,6 +79,7 @@ function getContext() {
         originJobId,
         raw,
         replay,
+        taskQueue,
         workflowId,
         workflowDimension,
         workflowTopic,

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

@@ -9,7 +9,7 @@ const didRun_1 = require("./didRun");
  * @private
  */
 function getChildInterruptPayload(context, options, execIndex) {
-    const { workflowId, originJobId, workflowDimension, expire } = context;
+    const { workflowId, originJobId, workflowDimension, expire, taskQueue: parentTaskQueue } = context;
     let childJobId;
     if (options.workflowId) {
         childJobId = options.workflowId;
@@ -21,7 +21,8 @@ function getChildInterruptPayload(context, options, execIndex) {
         childJobId = `-${options.workflowName}-${(0, common_1.guid)()}-${workflowDimension}-${execIndex}`;
     }
     const parentWorkflowId = workflowId;
-    const taskQueueName = options.taskQueue ?? options.entity;
+    // Use explicit taskQueue, or parent's taskQueue, or entity as fallback
+    const taskQueueName = options.taskQueue ?? parentTaskQueue ?? options.entity;
     const workflowName = options.taskQueue
         ? options.workflowName
         : options.entity ?? options.workflowName;
@@ -42,6 +43,8 @@ function getChildInterruptPayload(context, options, execIndex) {
         workflowDimension: workflowDimension,
         workflowId: childJobId,
         workflowTopic,
+        taskQueue: taskQueueName,
+        workflowName: workflowName,
     };
 }
 /**

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

@@ -109,10 +109,16 @@ async function hook(options) {
                     entity: options.entity,
                 }, null, 2)}`);
         }
+        // Extract taskQueue and workflowName from targetTopic
+        const hookTaskQueue = options.taskQueue ?? options.entity ?? targetTopic.split('-')[0];
+        const hookWorkflowName = options.workflowName ?? options.entity ??
+            (targetTopic.startsWith(`${hookTaskQueue}-`) ? targetTopic.substring(hookTaskQueue.length + 1) : targetTopic);
         const payload = {
             arguments: [...options.args],
             id: targetWorkflowId,
             workflowTopic: targetTopic,
+            taskQueue: hookTaskQueue,
+            workflowName: hookWorkflowName,
             backoffCoefficient: options.config?.backoffCoefficient || common_1.HMSH_DURABLE_EXP_BACKOFF,
             maximumAttempts: options.config?.maximumAttempts || common_1.HMSH_DURABLE_MAX_ATTEMPTS,
             maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_DURABLE_MAX_INTERVAL),

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

@@ -9,12 +9,11 @@ const didRun_1 = require("./didRun");
  * @private
  */
 function getProxyInterruptPayload(context, activityName, execIndex, args, options) {
-    const { workflowDimension, workflowId, originJobId, workflowTopic, expire } = context;
-    // Use explicitly provided taskQueue, otherwise derive from workflow (original behavior)
-    // This keeps backward compatibility while allowing explicit global/custom queues
+    const { workflowDimension, workflowId, originJobId, taskQueue, expire } = context;
+    // Activity topic uses the task queue directly (no workflow name concatenation)
     const activityTopic = options?.taskQueue
         ? `${options.taskQueue}-activity`
-        : `${workflowTopic}-activity`;
+        : `${taskQueue}-activity`;
     const activityJobId = `-${workflowId}-$${activityName}${workflowDimension}-${execIndex}`;
     let maximumInterval;
     if (options?.retryPolicy?.maximumInterval) {

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

@@ -16,7 +16,7 @@ import { TaskService } from '../task';
 import { AppVID } from '../../types/app';
 import { ActivityType } from '../../types/activity';
 import { CacheMode } from '../../types/cache';
-import { JobExport } from '../../types/exporter';
+import { ExportOptions, JobExport } from '../../types/exporter';
 import { JobState, JobData, JobMetadata, JobOutput, JobStatus, JobInterruptOptions, JobCompletionOptions, ExtensionType } from '../../types/job';
 import { HotMeshApps, HotMeshConfig, HotMeshManifest, HotMeshSettings } from '../../types/hotmesh';
 import { ProviderClient, ProviderTransaction } from '../../types/provider';
@@ -254,7 +254,7 @@ declare class EngineService {
     /**
      * @private
      */
-    export(jobId: string): Promise<JobExport>;
+    export(jobId: string, options?: ExportOptions): Promise<JobExport>;
     /**
      * @private
      */

package/build/services/engine/index.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EngineService = void 0;
 const key_1 = require("../../modules/key");
+const registry_1 = require("../stream/registry");
 const enums_1 = require("../../modules/enums");
 const utils_1 = require("../../modules/utils");
 const activities_1 = __importDefault(require("../activities"));
@@ -47,10 +48,11 @@ class EngineService {
             await instance.initSubChannel(config.engine.sub, config.engine.pub ?? config.engine.store);
             await instance.initStreamChannel(config.engine.stream, config.engine.store);
             instance.router = await instance.initRouter(config);
-            const streamName = instance.store.mintKey(key_1.KeyType.STREAMS, {
-                appId: instance.appId,
+            // Use singleton consumer via registry for engine stream
+            await registry_1.StreamConsumerRegistry.registerEngine(namespace, appId, guid, instance.processStreamMessage.bind(instance), instance.stream, instance.store, logger, {
+                reclaimDelay: config.engine.reclaimDelay,
+                reclaimCount: config.engine.reclaimCount,
             });
-            instance.router.consumeMessages(streamName, 'ENGINE', instance.guid, instance.processStreamMessage.bind(instance));
             instance.taskService = new task_1.TaskService(instance.store, logger);
             instance.exporter = new exporter_1.ExporterService(instance.appId, instance.store, logger);
             instance.inited = (0, utils_1.formatISODate)(new Date());
@@ -208,6 +210,9 @@ class EngineService {
      */
     async initActivity(topic, data = {}, context) {
         const [activityId, schema] = await this.getSchema(topic);
+        if (!schema) {
+            throw new Error(`Activity schema not found for "${activityId}" (topic: ${topic}) in app ${this.appId}`);
+        }
         const ActivityHandler = activities_1.default[schema.type];
         if (ActivityHandler) {
             const utc = (0, utils_1.formatISODate)(new Date());
@@ -744,8 +749,8 @@ class EngineService {
     /**
      * @private
      */
-    async export(jobId) {
-        return await this.exporter.export(jobId);
+    async export(jobId, options = {}) {
+        return await this.exporter.export(jobId, options);
     }
     /**
      * @private

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

@@ -1,8 +1,8 @@
 import { ILogger } from '../logger';
 import { StoreService } from '../store';
-import { DependencyExport, ExportOptions, JobActionExport, JobExport } from '../../types/exporter';
+import { ActivityDetail, DependencyExport, ExportOptions, JobActionExport, JobExport, StreamHistoryEntry } from '../../types/exporter';
 import { ProviderClient, ProviderTransaction } from '../../types/provider';
-import { StringStringType, Symbols } from '../../types/serializer';
+import { StringAnyType, StringStringType, Symbols } from '../../types/serializer';
 /**
  * Downloads job data and expands process data and
  * includes dependency list
@@ -34,6 +34,20 @@ declare class ExporterService {
      * @returns - the inflated job data
      */
     inflate(jobHash: StringStringType, dependencyList: string[]): JobExport;
+    /**
+     * Build structured activity details by correlating stream messages
+     * (inputs, timing, retries) with the process hierarchy (outputs).
+     *
+     * Stream messages carry the raw data that flowed through each activity:
+     * - `data` contains the activity input arguments
+     * - `dad` (dimensional address) reveals cycle iterations (e.g., ,0,1,0 = 2nd cycle)
+     * - `created_at` / `expired_at` give precise timing
+     * - `retry_attempt` tracks retries
+     *
+     * The process hierarchy carries activity outputs organized by dimension.
+     * This method merges both into a flat, dashboard-friendly list.
+     */
+    buildActivities(process: StringAnyType, streamHistory: StreamHistoryEntry[]): ActivityDetail[];
     /**
      * Inflates the dependency data into a JobExport object by
      * organizing the dimensional isolate in such a way as to interleave

package/build/services/exporter/index.js

@@ -28,6 +28,10 @@ class ExporterService {
         const depData = []; // await this.store.getDependencies(jobId);
         const jobData = await this.store.getRaw(jobId);
         const jobExport = this.inflate(jobData, depData);
+        if (options.enrich_inputs && this.store.getStreamHistory) {
+            const streamHistory = await this.store.getStreamHistory(jobId);
+            jobExport.activities = this.buildActivities(jobExport.process, streamHistory);
+        }
         return jobExport;
     }
     /**
@@ -77,6 +81,78 @@ class ExporterService {
             status: jobHash[':'],
         };
     }
+    /**
+     * Build structured activity details by correlating stream messages
+     * (inputs, timing, retries) with the process hierarchy (outputs).
+     *
+     * Stream messages carry the raw data that flowed through each activity:
+     * - `data` contains the activity input arguments
+     * - `dad` (dimensional address) reveals cycle iterations (e.g., ,0,1,0 = 2nd cycle)
+     * - `created_at` / `expired_at` give precise timing
+     * - `retry_attempt` tracks retries
+     *
+     * The process hierarchy carries activity outputs organized by dimension.
+     * This method merges both into a flat, dashboard-friendly list.
+     */
+    buildActivities(process, streamHistory) {
+        const activities = [];
+        for (const entry of streamHistory) {
+            // Parse dimensional address: ",0,1,0,0" → ["0","1","0","0"]
+            const dimParts = (entry.dad || '').split(',').filter(Boolean);
+            const dimension = dimParts.join('/');
+            // Detect cycle iteration from dimensional address
+            // In a cycling workflow, the 2nd dimension component increments per cycle
+            const cycleIteration = dimParts.length > 1 ? parseInt(dimParts[1]) || 0 : 0;
+            // Look up the corresponding output from the process hierarchy
+            // Process keys are like: process[dimension][activityName].output.data
+            let output;
+            let activityName = entry.aid;
+            // Walk the process hierarchy using the dimension path
+            let node = process;
+            for (const part of dimParts) {
+                if (node && typeof node === 'object' && node[part]) {
+                    node = node[part];
+                }
+                else {
+                    node = undefined;
+                    break;
+                }
+            }
+            if (node && typeof node === 'object') {
+                // node is now at the dimensional level, look for the activity
+                if (node[activityName]?.output?.data) {
+                    output = node[activityName].output.data;
+                }
+            }
+            // Compute timing
+            const startedAt = entry.created_at;
+            const completedAt = entry.expired_at;
+            let durationMs;
+            if (startedAt && completedAt) {
+                durationMs = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+            }
+            activities.push({
+                name: activityName,
+                type: entry.aid,
+                dimension,
+                input: entry.data,
+                output,
+                started_at: startedAt,
+                completed_at: completedAt,
+                duration_ms: durationMs,
+                retry_attempt: entry.code === undefined ? 0 : undefined,
+                cycle_iteration: cycleIteration > 0 ? cycleIteration : undefined,
+                error: null,
+            });
+        }
+        // Sort by time, then by dimension for cycle ordering
+        activities.sort((a, b) => {
+            const timeA = a.started_at || '';
+            const timeB = b.started_at || '';
+            return timeA.localeCompare(timeB);
+        });
+        return activities;
+    }
     /**
      * Inflates the dependency data into a JobExport object by
      * organizing the dimensional isolate in such a way as to interleave

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

@@ -4,7 +4,7 @@ import { QuorumService } from '../quorum';
 import { WorkerService } from '../worker';
 import { JobState, JobData, JobOutput, JobStatus, JobInterruptOptions, ExtensionType } from '../../types/job';
 import { HotMeshConfig, HotMeshManifest } from '../../types/hotmesh';
-import { JobExport } from '../../types/exporter';
+import { ExportOptions, JobExport } from '../../types/exporter';
 import { JobMessageCallback, QuorumMessage, QuorumMessageCallback, QuorumProfile, ThrottleOptions } from '../../types/quorum';
 import { StringAnyType, StringStringType } from '../../types/serializer';
 import { JobStatsInput, GetStatsOptions, IdsResponse, StatsResponse } from '../../types/stats';
@@ -632,7 +632,7 @@ declare class HotMesh {
      * activity data, transitions, and dependency chains. Useful for
      * debugging, auditing, and visualizing workflow execution.
      */
-    export(jobId: string): Promise<JobExport>;
+    export(jobId: string, options?: ExportOptions): Promise<JobExport>;
     /**
      * Returns all raw key-value pairs for a job's HASH record. This is
      * the lowest-level read — it returns internal engine fields alongside

package/build/services/hotmesh/index.js

@@ -769,8 +769,8 @@ class HotMesh {
      * activity data, transitions, and dependency chains. Useful for
      * debugging, auditing, and visualizing workflow execution.
      */
-    async export(jobId) {
-        return await this.engine?.export(jobId);
+    async export(jobId, options = {}) {
+        return await this.engine?.export(jobId, options);
     }
     /**
      * Returns all raw key-value pairs for a job's HASH record. This is

package/build/services/router/config/index.d.ts

@@ -1,4 +1,4 @@
-import { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES } from '../../../modules/enums';
+import { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD } from '../../../modules/enums';
 import { RouterConfig } from '../../../types/stream';
 export declare class RouterConfigManager {
     static validateThrottle(delayInMillis: number): void;
@@ -8,4 +8,4 @@ export declare class RouterConfigManager {
         readonly: boolean;
     };
 }
-export { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, };
+export { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD, };

package/build/services/router/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.MAX_DELAY = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_XCLAIM_COUNT = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_UNACKED = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_BLOCK_TIME_MS = exports.RouterConfigManager = void 0;
+exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.MAX_DELAY = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_XCLAIM_COUNT = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_UNACKED = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_BLOCK_TIME_MS = exports.RouterConfigManager = void 0;
 const enums_1 = require("../../../modules/enums");
 Object.defineProperty(exports, "HMSH_BLOCK_TIME_MS", { enumerable: true, get: function () { return enums_1.HMSH_BLOCK_TIME_MS; } });
 Object.defineProperty(exports, "HMSH_MAX_RETRIES", { enumerable: true, get: function () { return enums_1.HMSH_MAX_RETRIES; } });
@@ -16,6 +16,7 @@ Object.defineProperty(exports, "MAX_DELAY", { enumerable: true, get: function ()
 Object.defineProperty(exports, "MAX_STREAM_BACKOFF", { enumerable: true, get: function () { return enums_1.MAX_STREAM_BACKOFF; } });
 Object.defineProperty(exports, "INITIAL_STREAM_BACKOFF", { enumerable: true, get: function () { return enums_1.INITIAL_STREAM_BACKOFF; } });
 Object.defineProperty(exports, "MAX_STREAM_RETRIES", { enumerable: true, get: function () { return enums_1.MAX_STREAM_RETRIES; } });
+Object.defineProperty(exports, "HMSH_POISON_MESSAGE_THRESHOLD", { enumerable: true, get: function () { return enums_1.HMSH_POISON_MESSAGE_THRESHOLD; } });
 class RouterConfigManager {
     static validateThrottle(delayInMillis) {
         if (!Number.isInteger(delayInMillis) ||

package/build/services/router/consumption/index.js

@@ -356,6 +356,68 @@ class ConsumptionManager {
     }
     async consumeOne(stream, group, id, input, callback) {
         this.logger.debug(`stream-read-one`, { group, stream, id });
+        // Poison message circuit breaker. This is a SAFETY NET that sits above
+        // the normal retry mechanism (ErrorHandler.handleRetry / shouldRetry).
+        //
+        // Normal retry flow: handleRetry() checks metadata.try against the
+        // configured retryPolicy.maximumAttempts (or _streamRetryConfig) and
+        // applies exponential backoff + visibility delays. That mechanism is
+        // the primary retry budget and is what developers configure via
+        // HotMesh.init({ workers: [{ retryPolicy: { maximumAttempts, ... } }] }).
+        //
+        // This check catches messages that have somehow exceeded the normal
+        // budget — e.g., when no retryPolicy is configured, when the retry
+        // logic is bypassed by an infrastructure error, or when a message
+        // re-enters the stream through a path that doesn't increment
+        // metadata.try. The threshold is the HIGHER of the configured retry
+        // budget and the system-wide HMSH_POISON_MESSAGE_THRESHOLD, so it
+        // never interferes with legitimate developer-configured retries.
+        const retryAttempt = input._retryAttempt || 0;
+        const configuredMax = input._streamRetryConfig?.max_retry_attempts
+            ?? this.retryPolicy?.maximumAttempts
+            ?? 0;
+        const poisonThreshold = Math.max(configuredMax, config_1.HMSH_POISON_MESSAGE_THRESHOLD);
+        if (retryAttempt >= poisonThreshold) {
+            this.logger.error(`stream-poison-message-detected`, {
+                group,
+                stream,
+                id,
+                retryAttempt,
+                poisonThreshold,
+                configuredMaxAttempts: configuredMax,
+                systemThreshold: config_1.HMSH_POISON_MESSAGE_THRESHOLD,
+                topic: input.metadata?.topic,
+                activityId: input.metadata?.aid,
+                jobId: input.metadata?.jid,
+                metadata: input.metadata,
+            });
+            const errorOutput = this.errorHandler.structureUnhandledError(input, new Error(`Poison message detected: retry attempt ${retryAttempt} reached ` +
+                `threshold ${poisonThreshold} (configured: ${configuredMax}, ` +
+                `system: ${config_1.HMSH_POISON_MESSAGE_THRESHOLD}). Discarding message ` +
+                `for activity "${input.metadata?.aid || 'unknown'}" ` +
+                `(topic: ${input.metadata?.topic || 'unknown'}, ` +
+                `job: ${input.metadata?.jid || 'unknown'}).`));
+            try {
+                await this.publishMessage(null, errorOutput);
+            }
+            catch (publishErr) {
+                this.logger.error(`stream-poison-message-publish-error`, {
+                    error: publishErr,
+                    stream,
+                    id,
+                    retryAttempt,
+                    poisonThreshold,
+                });
+            }
+            // Mark as dead-lettered if the provider supports it; otherwise just ack
+            if (this.stream.deadLetterMessages) {
+                await this.stream.deadLetterMessages(stream, group, [id]);
+            }
+            else {
+                await this.ackAndDelete(stream, group, id);
+            }
+            return;
+        }
         let output;
         const telemetry = new telemetry_1.RouterTelemetry(this.appId);
         try {
@@ -367,12 +429,25 @@ class ConsumptionManager {
         catch (err) {
             this.logger.error(`stream-read-one-error`, { group, stream, id, err });
             telemetry.setStreamErrorFromException(err);
+            output = this.errorHandler.structureUnhandledError(input, err instanceof Error ? err : new Error(String(err)));
+        }
+        try {
+            const messageId = await this.publishResponse(input, output);
+            telemetry.setStreamAttributes({ 'app.worker.mid': messageId });
+        }
+        catch (publishErr) {
+            // If publishResponse fails, still ack the message to prevent
+            // infinite reprocessing. Log the error for debugging.
+            this.logger.error(`stream-publish-response-error`, {
+                group, stream, id, error: publishErr,
+            });
+            this.errorCount++;
+        }
+        finally {
+            await this.ackAndDelete(stream, group, id);
+            telemetry.endStreamSpan();
+            this.logger.debug(`stream-read-one-end`, { group, stream, id });
         }
-        const messageId = await this.publishResponse(input, output);
-        telemetry.setStreamAttributes({ 'app.worker.mid': messageId });
-        await this.ackAndDelete(stream, group, id);
-        telemetry.endStreamSpan();
-        this.logger.debug(`stream-read-one-end`, { group, stream, id });
     }
     async execStreamLeg(input, stream, id, callback) {
         let output;