@hotmeshio/hotmesh 0.6.1 → 0.7.0

package/build/types/index.d.ts

@@ -3,11 +3,11 @@ export { App, AppVID, AppTransitions, AppSubscriptions } from './app';
 export { AsyncSignal } from './async';
 export { CacheMode } from './cache';
 export { CollationFaultType, CollationStage } from './collator';
-export { ActivityConfig, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ClientWorkflow, ContextType, Connection, ProxyResponseType, ProxyType, Registry, SignalOptions, FindJobsOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, SearchResults, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowContext, WorkflowSearchOptions, WorkflowSearchSchema, WorkflowDataType, WorkflowOptions, } from './memflow';
+export { ActivityConfig, 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 './memflow';
 export { MemFlowChildErrorType, MemFlowProxyErrorType, MemFlowSleepErrorType, MemFlowWaitForAllErrorType, MemFlowWaitForErrorType, } from './error';
 export { ActivityAction, DependencyExport, MemFlowJobExport, ExportCycles, ExportItem, ExportOptions, ExportTransitions, JobAction, JobExport, JobActionExport, JobTimeline, } from './exporter';
 export { HookCondition, HookConditions, HookGate, HookInterface, HookRule, HookRules, HookSignal, } from './hook';
-export { HotMesh, HotMeshEngine, HotMeshWorker, HotMeshSettings, HotMeshApp, HotMeshApps, HotMeshConfig, HotMeshManifest, HotMeshGraph, KeyType, KeyStoreParams, } from './hotmesh';
+export { HotMesh, HotMeshEngine, HotMeshWorker, HotMeshSettings, HotMeshApp, HotMeshApps, HotMeshConfig, HotMeshManifest, HotMeshGraph, KeyType, KeyStoreParams, ScoutType, } from './hotmesh';
 export { ILogger, LogLevel } from './logger';
 export { ExtensionType, JobCompletionOptions, JobData, JobsData, JobInterruptOptions, JobMetadata, JobOutput, JobState, JobStatus, PartialJobState, } from './job';
 export { MappingStatements } from './map';
@@ -20,7 +20,7 @@ export { NatsAckPolicy, NatsAckPolicyExplicitType, NatsClassType, NatsClientType
 export { RedisClass, RedisRedisClientType, RedisRedisClientOptions, RedisRedisClassType, IORedisClientType, RedisClient, RedisMulti, RedisRedisMultiType, IORedisClientOptions, IORedisClassType, IORedisMultiType, RedisOptions, isRedisClient, isIORedisClient, } from './redis';
 export { JSONSchema, StringAnyType, StringScalarType, StringStringType, SymbolMap, SymbolMaps, SymbolRanges, Symbols, SymbolSets, } from './serializer';
 export { AggregatedData, CountByFacet, GetStatsOptions, IdsData, Measure, MeasureIds, MetricTypes, StatType, StatsType, IdsResponse, JobStats, JobStatsInput, JobStatsRange, StatsResponse, Segment, TimeSegment, } from './stats';
-export { ReclaimedMessageType, RouterConfig, StreamCode, StreamConfig, StreamData, StreamDataType, StreamError, StreamDataResponse, StreamMessage, StreamMessageMetadata, StreamProviderType, StreamRetryPolicy, StreamRole, StreamStats, StreamStatus, } from './stream';
+export { ReclaimedMessageType, RetryPolicy, RouterConfig, StreamCode, StreamConfig, StreamData, StreamDataType, StreamError, StreamDataResponse, StreamMessage, StreamMessageMetadata, StreamProviderType, StreamRetryPolicy, StreamRole, StreamStats, StreamStatus, PublishMessageConfig, } from './stream';
 export { context, Context, Counter, Meter, metrics, propagation, SpanContext, Span, SpanStatus, SpanStatusCode, SpanKind, trace, Tracer, ValueType, } from './telemetry';
 export { WorkListTaskType } from './task';
 export { TransitionMatch, TransitionRule, Transitions } from './transition';

package/build/types/memflow.d.ts

@@ -457,6 +457,38 @@ type ActivityConfig = {
     startToCloseTimeout?: string;
     /** Configuration for specific activities, type not yet specified */
     activities?: any;
+    /**
+     * Optional explicit task queue for activities.
+     *
+     * **Default Behavior (no taskQueue specified):**
+     * Activities use the workflow's task queue + "-activity" suffix.
+     * Example: workflow "my-workflow" → activity queue "my-workflow-activity"
+     *
+     * **Explicit Task Queue (when specified):**
+     * Activities use the specified task queue + "-activity" suffix.
+     * Useful for:
+     * - Shared activity pools across multiple workflows
+     * - Interceptors (prevents per-workflow queue creation)
+     * - Isolated activity worker pools
+     *
+     * @example
+     * ```typescript
+     * // Default: uses workflow's task queue (backward compatible)
+     * const activities = MemFlow.workflow.proxyActivities<typeof activities>({
+     *   activities,
+     *   retryPolicy: { maximumAttempts: 3 }
+     * });
+     * // If workflow taskQueue is "orders", uses "orders-activity"
+     *
+     * // Explicit: shared queue for interceptors (prevents explosion)
+     * const { auditLog } = MemFlow.workflow.proxyActivities<typeof activities>({
+     *   activities: { auditLog },
+     *   taskQueue: 'shared-activities', // Uses "shared-activities-activity"
+     *   retryPolicy: { maximumAttempts: 3 }
+     * });
+     * ```
+     */
+    taskQueue?: string;
     /** Retry policy configuration for activities */
     retryPolicy?: {
         /** Maximum number of retry attempts, default is 5 (HMSH_MEMFLOW_MAX_ATTEMPTS) */

package/build/types/provider.d.ts

@@ -62,6 +62,22 @@ export type ProviderConfig = {
      * can still read/write to the store and can still pub/sub events.
      */
     readonly?: boolean;
+    /**
+     * Retry policy for stream messages. Configures automatic retry
+     * behavior with exponential backoff for failed operations.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   retryPolicy: {
+     *     maximumAttempts: 5,
+     *     backoffCoefficient: 2,
+     *     maximumInterval: '300s'
+     *   }
+     * }
+     * ```
+     */
+    retryPolicy?: import('./stream').RetryPolicy;
 };
 export type ProvidersConfig = {
     sub: ProviderConfig;

package/build/types/stream.d.ts

@@ -1,4 +1,40 @@
 import { ProviderTransaction } from './provider';
+/**
+ * Structured retry policy configuration for stream messages.
+ * Controls retry behavior with exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const retryPolicy: RetryPolicy = {
+ *   maximumAttempts: 5,
+ *   backoffCoefficient: 2,
+ *   maximumInterval: '300s',
+ * };
+ * // Results in delays: 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s, 300s (capped)
+ * ```
+ */
+export interface RetryPolicy {
+    /**
+     * Maximum number of retry attempts before the message fails.
+     * @default 3
+     * @example 5
+     */
+    maximumAttempts?: number;
+    /**
+     * Base coefficient for exponential backoff calculation.
+     * Retry delay = min(backoffCoefficient ^ attemptNumber, maximumInterval)
+     * @default 10
+     * @example 2
+     */
+    backoffCoefficient?: number;
+    /**
+     * Maximum interval between retries in seconds or as a duration string.
+     * Caps the exponential backoff to prevent excessive delays.
+     * @default "120s"
+     * @example "60s" or 60
+     */
+    maximumInterval?: string | number;
+}
 /** Represents a policy for retrying stream operations based on error codes */
 export interface StreamRetryPolicy {
     /**
@@ -133,6 +169,8 @@ export type RouterConfig = {
     reclaimCount?: number;
     /** if true, will not process stream messages; default true */
     readonly?: boolean;
+    /** Retry policy for worker messages. Applied when worker callback throws an error */
+    retryPolicy?: RetryPolicy;
 };
 export type StreamProviderType = 'postgres' | 'nats' | 'sqs';
 export interface StreamConfig {
@@ -142,6 +180,20 @@ export interface StreamConfig {
     maxRetries?: number;
     batchSize?: number;
     timeout?: number;
+    /**
+     * Default retry policy for all streams in this app.
+     * Can be overridden per message using PublishMessageConfig.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   maximumAttempts: 5,
+     *   backoffCoefficient: 2,
+     *   maximumInterval: '300s',
+     * }
+     * ```
+     */
+    retryPolicy?: RetryPolicy;
     postgres?: {
         pollInterval?: number;
         vacuumInterval?: number;
@@ -169,6 +221,11 @@ export interface StreamMessage {
     id: string;
     data: StreamData;
     metadata?: StreamMessageMetadata;
+    /**
+     * Retry policy configuration for this message.
+     * Populated from database columns when available.
+     */
+    retryPolicy?: RetryPolicy;
 }
 export interface StreamMessageMetadata {
     timestamp?: number;
@@ -195,8 +252,42 @@ export interface StreamStats {
 /**
  * When publishing a message to the stream, the configuration
  * can include a transaction object to execute the operation
- * atomically.
+ * atomically and/or a retry policy to control retry behavior.
  */
 export interface PublishMessageConfig {
     transaction?: ProviderTransaction;
+    /**
+     * Retry policy for this specific message.
+     * Overrides stream-level and app-level defaults.
+     *
+     * @example
+     * ```typescript
+     * await streamService.publishMessages('my-topic', [msg], {
+     *   retryPolicy: {
+     *     maximumAttempts: 10,
+     *     backoffCoefficient: 2,
+     *     maximumInterval: '600s',
+     *   }
+     * });
+     * ```
+     */
+    retryPolicy?: RetryPolicy;
+}
+/**
+ * Notification consumer configuration for PostgreSQL stream provider.
+ * Manages notification-based message consumption with fallback polling.
+ */
+export interface NotificationConsumer {
+    /** Name of the stream being consumed */
+    streamName: string;
+    /** Name of the consumer group */
+    groupName: string;
+    /** Unique name identifying this consumer */
+    consumerName: string;
+    /** Callback function invoked when messages are available */
+    callback: (messages: StreamMessage[]) => void;
+    /** Whether this consumer is actively listening for notifications */
+    isListening: boolean;
+    /** Timestamp of the last fallback check (used for periodic polling) */
+    lastFallbackCheck: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -29,7 +29,7 @@
     "test:connect:nats": "NODE_ENV=test jest ./tests/unit/services/connector/providers/nats.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow": "NODE_ENV=test jest ./tests/memflow/*/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:basic": "HMSH_LOGLEVEL=info NODE_ENV=test jest ./tests/memflow/basic/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:fatal": "NODE_ENV=test jest ./tests/memflow/fatal/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:goodbye": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/goodbye/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:interceptor": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/interceptor/postgres.test.ts --detectOpenHandles --forceExit --verbose",
@@ -37,30 +37,32 @@
     "test:memflow:agent": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/agent/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug NODE_ENV=test jest ./tests/memflow/helloworld/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:memflow:loopactivity": "NODE_ENV=test jest ./tests/memflow/loopactivity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:loopactivity": "NODE_ENV=test jest ./tests/memflow/loopactivity/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:nested": "NODE_ENV=test jest ./tests/memflow/nested/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:pipeline": "NODE_ENV=test jest ./tests/memflow/pipeline/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:retry": "NODE_ENV=test jest ./tests/memflow/retry/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:retrypolicy": "NODE_ENV=test jest ./tests/memflow/retry-policy/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:sleep": "NODE_ENV=test jest ./tests/memflow/sleep/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:signal": "NODE_ENV=test jest ./tests/memflow/signal/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:functional": "NODE_ENV=test jest ./tests/functional/* --detectOpenHandles --forceExit --verbose",
     "test:emit": "NODE_ENV=test jest ./tests/functional/emit/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:pending": "NODE_ENV=test jest ./tests/functional/pending/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:hmsh": "NODE_ENV=test jest ./tests/functional/*.test.ts --detectOpenHandles --verbose --forceExit",
-    "test:hook": "NODE_ENV=test jest ./tests/functional/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:hook": "NODE_ENV=test jest ./tests/functional/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:interrupt": "NODE_ENV=test jest ./tests/functional/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:parallel": "NODE_ENV=test jest ./tests/functional/parallel/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:pipe": "NODE_ENV=test jest ./tests/unit/services/pipe/index.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:quorum": "NODE_ENV=test jest ./tests/functional/quorum/*.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:quorum": "NODE_ENV=test jest ./tests/functional/quorum/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:redeploy": "NODE_ENV=test jest ./tests/functional/redeploy/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:reporter": "NODE_ENV=test jest ./tests/unit/services/reporter/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:retry": "NODE_ENV=test jest ./tests/functional/retry/*.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:retrypolicy": "NODE_ENV=test jest ./tests/functional/retry-policy/*.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:signal": "NODE_ENV=test jest ./tests/functional/signal/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:status": "NODE_ENV=test jest ./tests/functional/status/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:providers": "NODE_ENV=test jest ./tests/functional/*/providers/*/*.test.ts --detectOpenHandles --forceExit --verbose",