@hotmeshio/hotmesh 0.4.3 → 0.5.1

package/README.md

@@ -1,44 +1,52 @@
 # HotMesh
 
-**Permanent-Memory Workflows & AI Agents**
+**🧠 Workflow That Remembers**
 
 ![beta release](https://img.shields.io/badge/release-beta-blue.svg)  ![made with typescript](https://img.shields.io/badge/built%20with-typescript-lightblue.svg)
 
-**HotMesh** is a Temporal-style workflow engine that runs natively on PostgreSQL — with a powerful twist: every workflow maintains permanent, state that persists independently of the workflow itself.
+HotMesh brings a **memory model** to your automation: durable entities that hold context, support concurrency, and evolve across runs. Built on PostgreSQL, it treats your database not just as storage—but as the runtime hub for agents, pipelines, and long-lived processes.
 
-This means:
+Use HotMesh to:
 
-* Any number of lightweight, thread-safe **hook workers** can attach to the same workflow record at any time.
-* These hooks can safely **read and write** to shared state.
-* The result is a **durable execution model** with **evolving memory**, ideal for **human-in-the-loop processes** and **AI agents that learn over time**.
+* **Store Evolving State** – Retain memory/state between executions
+* **Coordinate Distributed Work** – Safely allow multiple workers to act on shared state
+* **Track and Replay** – Full audit history and replay support by default
 
 ---
 
 ## Table of Contents
 
-1. 🚀 Quick Start
-2. 🧠 How Permanent Memory Works
-3. 🔌 Hooks & Entity API
-4. 🤖 Building Durable AI Agents
-5. 🔬 Advanced Patterns & Recipes
-6. 📚 Documentation & Links
+1. [Quick Start](#-quick-start)
+2. [Permanent Memory Architecture](#-permanent-memory-architecture)
+3. [Durable AI Agents](#-durable-ai-agents)
+4. [Building Pipelines with State](#-building-pipelines-with-state)
+5. [Documentation & Links](#-documentation--links)
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
+
+### Prerequisites
+
+* PostgreSQL (or Supabase)
+* Node.js 16+
 
 ### Install
+
 ```bash
 npm install @hotmeshio/hotmesh
 ```
 
-### Start a workflow
-```typescript
-// index.ts
+### Connect to a Database
+
+HotMesh leverages Temporal.io's developer-friendly syntax for authoring workers, workflows, and clients. The `init` and `start` methods should look familiar.
+
+```ts
 import { MemFlow } from '@hotmeshio/hotmesh';
 import { Client as Postgres } from 'pg';
 
 async function main() {
+  // MemFlow will auto-provision the database upon init
   const mf = await MemFlow.init({
     appId: 'my-app',
     engine: {
@@ -49,13 +57,13 @@ async function main() {
     }
   });
 
-  // Kick off a workflow
+  // Start a workflow with an assigned ID and arguments
   const handle = await mf.workflow.start({
-    entity: 'user',
-    workflowName: 'userExample',
-    workflowId: 'jane@hotmesh.com',
-    args: ['Jane'],
-    taskQueue: 'entityqueue'
+    entity: 'research-agent',
+    workflowName: 'researchAgent',
+    workflowId: 'agent-session-jane-001',
+    args: ['What are the long-term impacts of renewable energy subsidies?'],
+    taskQueue: 'agents'
   });
 
   console.log('Result:', await handle.result());
@@ -64,172 +72,298 @@ async function main() {
 main().catch(console.error);
 ```
 
+### System Benefits
+
+* **No Setup Required** – Tables and indexes are provisioned automatically
+* **Shared State** – Every worker shares access to the same entity memory
+* **Coordination by Design** – PostgreSQL handles consistency and isolation
+* **Tenant Isolation** – Each app maintains its own schema
+* **Scalable Defaults** – Partitioned tables and index support included
+
 ---
 
-## 🧠 How Permanent Memory Works
+## Permanent Memory Architecture
+
+Every workflow in HotMesh is backed by an "entity": a versioned, JSONB record that tracks its memory and state transitions.
 
-* **Entity = persistent JSON record** – each workflow's memory is stored as a JSONB row in your Postgres database
-* **Atomic operations** (`set`, `merge`, `append`, `increment`, `toggle`, `delete`, …)
-* **Transactional** – every update participates in the workflow/DB transaction
-* **Time-travel-safe** – full replay compatibility; side-effect detector guarantees determinism
-* **Hook-friendly** – any worker with the record ID can attach and mutate its slice of the JSON
-* **Index-friendly** - entity data is stored as JSONB; add partial indexes for improved query analysis.
+* **Entities** – Represent long-lived state for a workflow or agent
+* **Commands** – Modify state with methods like `set`, `merge`, `append`, `increment`
+* **Consistency** – All updates are transactional with Postgres
+* **Replay Safety** – Protects against duplicated side effects during re-execution
+* **Partial Indexing** – Optimized querying of fields within large JSON structures
+
+### Example: Partial Index for Premium Users
 
-**Example: Adding a Partial Index for Specific Entity Types**
 ```sql
--- Create a partial index for 'user' entities with specific entity values
+-- Index only those user entities that are marked as premium
 CREATE INDEX idx_user_premium ON your_app.jobs (id)
 WHERE entity = 'user' AND (context->>'isPremium')::boolean = true;
 ```
-This index will only be used for queries that match both conditions, making lookups for premium users much faster.
+
+This index improves performance for filtered queries while reducing index size.
 
 ---
 
-## 🔌 Hooks & Entity API – Full Example
+## Durable AI Agents
 
-HotMesh hooks are powerful because they can be called both internally (from within a workflow) and externally (from outside, even after the workflow completes). This means you can:
+Agents often require memory—context that persists between invocations, spans multiple perspectives, or outlives a single process. HotMesh supports that natively.
 
-* Start a workflow that sets up initial state
-* Have the workflow call some hooks internally
-* Let the workflow complete
-* Continue to update the workflow's entity state from the outside via hooks
-* Build long-running processes that evolve over time
+The following example builds a "research agent" that runs sub-flows and self-reflects on the results.
 
-Here's a complete example showing both internal and external hook usage:
+### Research Agent Example
 
-```typescript
-import { MemFlow } from '@hotmeshio/hotmesh';
+#### Main Coordinator Agent
 
-/* ------------ Main workflow ------------ */
-export async function userExample(name: string): Promise<any> {
-  //the entity method provides transactional, replayable access to shared job state 
+```ts
+export async function researchAgent(query: string): Promise<any> {
   const entity = await MemFlow.workflow.entity();
 
-  //create the initial entity (even arrays are supported)
+  // Set up shared memory for this agent session
   await entity.set({
-    user: { name },
-    hooks: {},
-    metrics: { count: 0 }
+    query,
+    findings: [],
+    perspectives: {},
+    confidence: 0,
+    status: 'researching'
+  });
+
+  // Launch perspective hooks in parallel (no need to await here)
+  const optimistic = MemFlow.workflow.execHook({
+    taskQueue: 'agents',
+    workflowName: 'optimisticPerspective',
+    args: [query]
+  });
+
+  const skeptical = MemFlow.workflow.execHook({
+    taskQueue: 'agents',
+    workflowName: 'skepticalPerspective',
+    args: [query]
   });
 
-  // Call one hook internally
-  const result1 = await MemFlow.workflow.execHook({
-    taskQueue: 'entityqueue',
-    workflowName: 'hook1',
-    args: [name, 'hook1'],
-    signalId: 'hook1-complete'
+  // Launch a child workflow with its own isolated entity/state
+  const factChecker = await MemFlow.workflow.execChild({
+    entity: 'fact-checker',
+    workflowName: 'factCheckAgent',
+    workflowId: `fact-check-${Date.now()}`,
+    args: [query],
+    taskQueue: 'agents'
   });
 
-  // merge the result
-  await entity.merge({ hooks: { r1: result1 } });
-  await entity.increment('metrics.count', 1);
+  // Wait for all views to complete before analyzing
+  await Promise.all([optimistic, skeptical, factChecker]);
 
-  return "The main has completed; the db record persists and can be hydrated; hook in from the outside!";
+  // Final synthesis: aggregate and compare all perspectives
+  await MemFlow.workflow.execHook({
+    taskQueue: 'perspectives',
+    workflowName: 'synthesizePerspectives',
+    args: []
+  });
+
+  return await entity.get();
 }
+```
+
+#### Hooks: Perspectives
 
-/* ------------ Hook 1 (hooks have access to methods like sleepFor) ------------ */
-export async function hook1(name: string, kind: string): Promise<any> {
-  await MemFlow.workflow.sleepFor('2 seconds');
-  const res = { kind, processed: true, at: Date.now() };
-  await MemFlow.workflow.signal('hook1-complete', res);
+```ts
+// Optimistic hook looks for affirming evidence
+export async function optimisticPerspective(query: string, config: {signal: string}): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  const findings = await searchForSupportingEvidence(query);
+  await entity.merge({ perspectives: { optimistic: { findings, confidence: 0.8 }}});
+  //signal the caller to notify all done
+  await MemFlow.workflow.signal(config.signal, {});
 }
 
-/* ------------ Hook 2 (hooks can access shared job entity) ------------ */
-export async function hook2(name: string, kind: string): Promise<void> {
+// Skeptical hook seeks out contradictions and counterpoints
+export async function skepticalPerspective(query: string, config: {signal: string}): Promise<void> {
   const entity = await MemFlow.workflow.entity();
-  await entity.merge({ user: { lastSeen: new Date().toISOString() } });
-  await MemFlow.workflow.signal('hook2-complete', { ok: true });
+  const counterEvidence = await searchForCounterEvidence(query);
+  await entity.merge({ perspectives: { skeptical: { counterEvidence, confidence: 0.6 }}});
+  await MemFlow.workflow.signal(config.signal, {});
 }
+```
 
-/* ------------ Worker/Hook Registration ------------ */
-async function startWorker() {
-  const mf = await MemFlow.init({
-    appId: 'my-app',
-    engine: {
-      connection: {
-        class: Postgres,
-        options: { connectionString: process.env.DATABASE_URL }
-      }
-    }
-  });
+#### Child Agent: Fact Checker
 
-  const worker = await mf.worker.create({
-    taskQueue: 'entityqueue',
-    workflow: example
-  });
+```ts
+// A dedicated child agent with its own entity type and context
+export async function factCheckAgent(query: string): Promise<any> {
+  const entity = await MemFlow.workflow.entity();
+  await entity.set({ query, sources: [], verifications: [] });
 
-  await mf.worker.create({
-    taskQueue: 'entityqueue',
-    workflow: hook1
+  await MemFlow.workflow.execHook({
+    taskQueue: 'agents',
+    workflowName: 'verifySourceCredibility',
+    args: [query]
   });
 
-  await mf.worker.create({
-    taskQueue: 'entityqueue',
-    workflow: hook2
-  });
+  return await entity.get();
+}
+```
+
+#### Synthesis
+
+```ts
+// Synthesis hook aggregates different viewpoints
+export async function synthesizePerspectives(config: {signal: string}): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  const context = await entity.get();
+
+  const result = await analyzePerspectives(context.perspectives);
 
-  console.log('Workers and hooks started and listening...');
+  await entity.merge({
+    perspectives: {
+      synthesis: {
+        finalAssessment: result,
+        confidence: calculateConfidence(context.perspectives)
+      }
+    },
+    status: 'completed'
+  });
+  await MemFlow.workflow.signal(config.signal, {});
 }
 ```
 
-### The Power of External Hooks
+---
 
-One of HotMesh's most powerful features is that workflow entities remain accessible even after the main workflow completes. By providing the original workflow ID, any authorized client can:
+## Building Pipelines with State
 
-* Hook into existing workflow entities
-* Update state and trigger new processing
-* Build evolving, long-running processes
-* Enable human-in-the-loop workflows
-* Create AI agents that learn over time
+HotMesh treats pipelines as long-lived records, not ephemeral jobs. Every pipeline run is stateful, resumable, and traceable.
 
-Here's how to hook into an existing workflow from the outside:
+### Setup a Data Pipeline
 
-```typescript
-/* ------------ External Hook Example ------------ */
-async function externalHookExample() {
-  const client = new MemFlow.Client({
-    appId: 'my-app',
-    engine: {
-      connection: {
-        class: Postgres,
-        options: { connectionString: process.env.DATABASE_URL }
-      }
-    }
+```ts
+export async function dataPipeline(source: string): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+
+  // Initial policy and tracking setup
+  await entity.set({
+    source,
+    pipeline: { version: 1, policy: { refreshInterval: '24 hours' } },
+    changeLog: []
   });
 
-  // Start hook2 externally by providing the original workflow ID
-  await client.workflow.hook({
-    workflowId: 'jane@hotmesh.com', //id of the target workflow
-    taskQueue: 'entityqueue',
-    workflowName: 'hook2',
-    args: [name, 'external-hook']
+  // Trigger the recurring orchestration pipeline
+  await MemFlow.workflow.execHook({
+    taskQueue: 'pipeline',
+    workflowName: 'runPipeline',
+    args: [true]
   });
 }
 ```
 
----
+### Orchestration Hook
+
+```ts
+export async function runPipeline(repeat = false): Promise<void> {
+  do {
+    // Perform transformation step
+    await MemFlow.workflow.execHook({
+      taskQueue: 'transform',
+      workflowName: 'cleanData',
+      args: []
+    });
+
+    if (repeat) {
+      // Schedule next execution
+      await MemFlow.workflow.execHook({
+        taskQueue: 'scheduler',
+        workflowName: 'scheduleRefresh',
+        args: []
+      });
+    }
+  } while (repeat)
+}
 
-## 🤖 Building Durable AI Agents
+/**
+ * Hook to clean and transform data
+ */
+export async function cleanData(signalInfo?: { signal: string }): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Simulate data cleaning
+  await entity.merge({
+    status: 'cleaning',
+    lastCleanedAt: new Date().toISOString()
+  });
+
+  // Add to changelog
+  await entity.append('changeLog', {
+    action: 'clean',
+    timestamp: new Date().toISOString()
+  });
+
+  // Signal completion if called via execHook
+  if (signalInfo?.signal) {
+    await MemFlow.workflow.signal(signalInfo.signal, { 
+      status: 'cleaned',
+      timestamp: new Date().toISOString()
+    });
+  }
+}
+
+/**
+ * Hook to schedule the next refresh based on policy
+ */
+export async function scheduleRefresh(signalInfo?: { signal: string }): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Get refresh interval from policy
+  const currentEntity = await entity.get();
+  const refreshInterval = currentEntity.pipeline.policy.refreshInterval;
+  
+  // Sleep for the configured interval
+  await MemFlow.workflow.sleepFor(refreshInterval);
+  
+  // Update status after sleep
+  await entity.merge({
+    status: 'ready_for_refresh',
+    nextRefreshAt: new Date().toISOString()
+  });
 
-Permanent memory unlocks a straightforward pattern for agentic systems:
+  // Add to changelog
+  await entity.append('changeLog', {
+    action: 'schedule_refresh',
+    timestamp: new Date().toISOString(),
+    nextRefresh: new Date().toISOString()
+  });
+
+  // Signal completion if called via execHook
+  if (signalInfo?.signal) {
+    await MemFlow.workflow.signal(signalInfo.signal, {
+      status: 'scheduled',
+      nextRefresh: new Date().toISOString()
+    });
+  }
+}
+```
+
+### Trigger from Outside
 
-1. **Planner workflow** – sketches a task list, seeds entity state.
-2. **Tool hooks** – execute individual tasks, feeding intermediate results back into state.
-3. **Reflector hook** – periodically summarizes state into long-term memory embeddings.
-4. **Supervisor workflow** – monitors metrics stored in state and decides when to finish.
+```ts
+// External systems can trigger a single pipeline run
+export async function triggerRefresh() {
+  const client = new MemFlow.Client({/*...*/});
 
-Because every step is durable *and* shares the same knowledge object, agents can pause,
-restart, scale horizontally, and keep evolving their world-model indefinitely.
+  await client.workflow.hook({
+    workflowId: 'pipeline-123',
+    taskQueue: 'pipeline',
+    workflowName: 'runPipeline',
+    args: []
+  });
+}
+```
 
 ---
 
-## 📚 Documentation & Links
+## Documentation & Links
 
-* SDK API – [https://hotmeshio.github.io/sdk-typescript](https://hotmeshio.github.io/sdk-typescript)
-* Examples – [https://github.com/hotmeshio/samples-typescript](https://github.com/hotmeshio/samples-typescript)
+* SDK Reference – [hotmeshio.github.io/sdk-typescript](https://hotmeshio.github.io/sdk-typescript)
+* Examples – [github.com/hotmeshio/samples-typescript](https://github.com/hotmeshio/samples-typescript)
 
 ---
 
 ## License
 
-Apache 2.0 – see `LICENSE` for details.
+Apache 2.0 – See `LICENSE` for details.

package/build/modules/errors.d.ts

@@ -15,6 +15,7 @@ declare class MemFlowWaitForError extends Error {
     workflowId: string;
     index: number;
     workflowDimension: string;
+    type: string;
     constructor(params: MemFlowWaitForErrorType);
 }
 declare class MemFlowProxyError extends Error {
@@ -31,10 +32,12 @@ declare class MemFlowProxyError extends Error {
     workflowDimension: string;
     workflowId: string;
     workflowTopic: string;
+    type: string;
     constructor(params: MemFlowProxyErrorType);
 }
 declare class MemFlowChildError extends Error {
     await: boolean;
+    entity: string;
     arguments: string[];
     backoffCoefficient: number;
     code: number;
@@ -49,6 +52,7 @@ declare class MemFlowChildError extends Error {
     parentWorkflowId: string;
     workflowId: string;
     workflowTopic: string;
+    type: string;
     constructor(params: MemFlowChildErrorType);
 }
 declare class MemFlowWaitForAllError extends Error {
@@ -61,6 +65,7 @@ declare class MemFlowWaitForAllError extends Error {
     parentWorkflowId: string;
     workflowId: string;
     workflowTopic: string;
+    type: string;
     constructor(params: MemFlowWaitForAllErrorType);
 }
 declare class MemFlowSleepError extends Error {
@@ -69,22 +74,27 @@ declare class MemFlowSleepError extends Error {
     duration: number;
     index: number;
     workflowDimension: string;
+    type: string;
     constructor(params: MemFlowSleepErrorType);
 }
 declare class MemFlowTimeoutError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stack?: string);
 }
 declare class MemFlowMaxedError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stackTrace?: string);
 }
 declare class MemFlowFatalError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stackTrace?: string);
 }
 declare class MemFlowRetryError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stackTrace?: string);
 }
 declare class MapDataError extends Error {

package/build/modules/errors.js

@@ -19,6 +19,7 @@ exports.SetStateError = SetStateError;
 class MemFlowWaitForError extends Error {
     constructor(params) {
         super(`WaitFor Interruption`);
+        this.type = 'MemFlowWaitForError';
         this.signalId = params.signalId;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
@@ -29,6 +30,7 @@ exports.MemFlowWaitForError = MemFlowWaitForError;
 class MemFlowProxyError extends Error {
     constructor(params) {
         super(`ProxyActivity Interruption`);
+        this.type = 'MemFlowProxyError';
         this.arguments = params.arguments;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
@@ -48,6 +50,7 @@ exports.MemFlowProxyError = MemFlowProxyError;
 class MemFlowChildError extends Error {
     constructor(params) {
         super(`ExecChild Interruption`);
+        this.type = 'MemFlowChildError';
         this.arguments = params.arguments;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
@@ -56,6 +59,7 @@ class MemFlowChildError extends Error {
         this.persistent = params.persistent;
         this.signalIn = params.signalIn;
         this.originJobId = params.originJobId;
+        this.entity = params.entity;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
         this.code = enums_1.HMSH_CODE_MEMFLOW_CHILD;
@@ -69,6 +73,7 @@ exports.MemFlowChildError = MemFlowChildError;
 class MemFlowWaitForAllError extends Error {
     constructor(params) {
         super(`Collation Interruption`);
+        this.type = 'MemFlowWaitForAllError';
         this.items = params.items;
         this.size = params.size;
         this.workflowId = params.workflowId;
@@ -84,6 +89,7 @@ exports.MemFlowWaitForAllError = MemFlowWaitForAllError;
 class MemFlowSleepError extends Error {
     constructor(params) {
         super(`SleepFor Interruption`);
+        this.type = 'MemFlowSleepError';
         this.duration = params.duration;
         this.workflowId = params.workflowId;
         this.index = params.index;
@@ -95,6 +101,7 @@ exports.MemFlowSleepError = MemFlowSleepError;
 class MemFlowTimeoutError extends Error {
     constructor(message, stack) {
         super(message);
+        this.type = 'MemFlowTimeoutError';
         if (this.stack) {
             this.stack = stack;
         }
@@ -105,6 +112,7 @@ exports.MemFlowTimeoutError = MemFlowTimeoutError;
 class MemFlowMaxedError extends Error {
     constructor(message, stackTrace) {
         super(message);
+        this.type = 'MemFlowMaxedError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
@@ -115,6 +123,7 @@ exports.MemFlowMaxedError = MemFlowMaxedError;
 class MemFlowFatalError extends Error {
     constructor(message, stackTrace) {
         super(message);
+        this.type = 'MemFlowFatalError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
@@ -125,6 +134,7 @@ exports.MemFlowFatalError = MemFlowFatalError;
 class MemFlowRetryError extends Error {
     constructor(message, stackTrace) {
         super(message);
+        this.type = 'MemFlowRetryError';
         if (stackTrace) {
             this.stack = stackTrace;
         }

package/build/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.4.2",
+    "version": "0.5.1",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
-    "homepage": "https://hotmesh.io/",
+    "homepage": "https://github.com/hotmeshio/sdk-typescript/",
     "publishConfig": {
         "access": "public"
     },

package/build/services/activities/trigger.d.ts

@@ -31,7 +31,7 @@ declare class Trigger extends Activity {
     getJobStatus(): number;
     resolveJobId(context: Partial<JobState>): string;
     resolveJobKey(context: Partial<JobState>): string;
-    setStateNX(status?: number, entity?: string): Promise<void>;
+    setStateNX(status?: number, entity?: string | undefined): Promise<void>;
     setStats(transaction?: ProviderTransaction): Promise<void>;
 }
 export { Trigger };

package/build/services/activities/trigger.js

@@ -9,6 +9,7 @@ const reporter_1 = require("../reporter");
 const serializer_1 = require("../serializer");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+const mapper_1 = require("../mapper");
 class Trigger extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -27,7 +28,9 @@ class Trigger extends activity_1.Activity {
             this.mapJobData();
             this.adjacencyList = await this.filterAdjacent();
             const initialStatus = this.initStatus(options, this.adjacencyList.length);
-            await this.setStateNX(initialStatus, options?.entity);
+            //config.entity is a pipe expression; if 'entity' exists, it will resolve
+            const resolvedEntity = new mapper_1.MapperService({ entity: this.config.entity }, this.context).mapRules()?.entity;
+            await this.setStateNX(initialStatus, options?.entity || resolvedEntity);
             await this.setStatus(initialStatus);
             this.bindSearchData(options);
             this.bindMarkerData(options);

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

@@ -6,6 +6,7 @@ import { Entity } from './entity';
 import { WorkerService } from './worker';
 import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
+import { didInterrupt } from './workflow/interruption';
 /**
  * The MemFlow service is a collection of services that
  * emulate Temporal's capabilities, but instead are
@@ -106,6 +107,13 @@ declare class MemFlowClass {
      * including: `execChild`, `waitFor`, `sleep`, etc
      */
     static workflow: typeof WorkflowService;
+    /**
+     * Checks if an error is a HotMesh reserved error type that indicates
+     * a workflow interruption rather than a true error condition.
+     *
+     * @see {@link utils/interruption.didInterrupt} for detailed documentation
+     */
+    static didInterrupt: typeof didInterrupt;
     /**
      * Shutdown everything. All connections, workers, and clients will be closed.
      * Include in your signal handlers to ensure a clean shutdown.

package/build/services/memflow/index.js

@@ -9,6 +9,7 @@ const entity_1 = require("./entity");
 const worker_1 = require("./worker");
 const workflow_1 = require("./workflow");
 const handle_1 = require("./handle");
+const interruption_1 = require("./workflow/interruption");
 /**
  * The MemFlow service is a collection of services that
  * emulate Temporal's capabilities, but instead are
@@ -120,3 +121,10 @@ MemFlowClass.Worker = worker_1.WorkerService;
  * including: `execChild`, `waitFor`, `sleep`, etc
  */
 MemFlowClass.workflow = workflow_1.WorkflowService;
+/**
+ * Checks if an error is a HotMesh reserved error type that indicates
+ * a workflow interruption rather than a true error condition.
+ *
+ * @see {@link utils/interruption.didInterrupt} for detailed documentation
+ */
+MemFlowClass.didInterrupt = interruption_1.didInterrupt;

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

@@ -17,7 +17,7 @@
  * * Service Meshes
  * * Master Data Management systems
  */
-declare const APP_VERSION = "4";
+declare const APP_VERSION = "5";
 declare const APP_ID = "memflow";
 /**
  * returns a new memflow workflow schema

package/build/services/memflow/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 = '4';
+const APP_VERSION = '5';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'memflow';
 exports.APP_ID = APP_ID;
@@ -86,6 +86,9 @@ const getWorkflowYAML = (app, version) => {
             signalIn:
               description: if false, the job will not support subordinated hooks
               type: boolean
+            entity:
+              description: the entity type for this workflow instance
+              type: string
 
       output:
         schema:
@@ -120,6 +123,7 @@ const getWorkflowYAML = (app, version) => {
         trigger:
           title: Main Flow Trigger
           type: trigger
+          entity: '{$self.input.data.entity}'
           job:
             maps:
               done: false
@@ -249,6 +253,9 @@ const getWorkflowYAML = (app, version) => {
                   await:
                     type: string
                     description: when set to false, do not await the child flow's completion
+                  entity:
+                    type: string
+                    description: the entity type for the child workflow
             591:
               schema:
                 type: object
@@ -367,6 +374,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                entity:
+                  type: string
+                  description: the entity type for the child workflow
             maps:
               arguments: '{worker.output.data.arguments}'
               workflowDimension: '{worker.output.data.workflowDimension}'
@@ -379,6 +389,7 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{worker.output.data.workflowId}'
               workflowName: '{worker.output.data.workflowName}'
               workflowTopic: '{worker.output.data.workflowTopic}'
+              entity: '{worker.output.data.entity}'
               backoffCoefficient:
                 '@pipe':
                   - ['{worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
@@ -992,6 +1003,9 @@ const getWorkflowYAML = (app, version) => {
                   await:
                     type: string
                     description: when set to false, do not await the child flow's completion
+                  entity:
+                    type: string
+                    description: the entity type for the child workflow
             591:
               schema:
                 type: object
@@ -1109,6 +1123,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                entity:
+                  type: string
+                  description: the entity type for the child workflow
             maps:
               arguments: '{signaler_worker.output.data.arguments}'
               workflowDimension: '{signaler_worker.output.data.workflowDimension}'
@@ -1121,6 +1138,7 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{signaler_worker.output.data.workflowId}'
               workflowName: '{signaler_worker.output.data.workflowName}'
               workflowTopic: '{signaler_worker.output.data.workflowTopic}'
+              entity: '{signaler_worker.output.data.entity}'
               backoffCoefficient:
                 '@pipe':
                   - ['{signaler_worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
@@ -1875,6 +1893,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                entity:
+                  type: string
+                  description: the entity type for the child workflow
             maps:
               arguments:
                 '@pipe':
@@ -1946,6 +1967,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
                   - ['{@array.get}', maximumInterval]
                   - ['{@object.get}']
+              entity:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', entity]
+                  - ['{@object.get}']
           output:
             schema:
               type: object

package/build/services/memflow/worker.js

@@ -322,6 +322,31 @@ class WorkerService {
                 const workflowResponse = await storage_1.asyncLocalStorage.run(context, async () => {
                     return await workflowFunction.apply(this, workflowInput.arguments);
                 });
+                //if the embedded function has a try/catch, it can interrup the throw
+                // throw here to interrupt the workflow if the embedded function caught and suppressed
+                if (interruptionRegistry.length > 0) {
+                    const payload = interruptionRegistry[0];
+                    switch (payload.type) {
+                        case 'MemFlowWaitForError':
+                            throw new errors_1.MemFlowWaitForError(payload);
+                        case 'MemFlowProxyError':
+                            throw new errors_1.MemFlowProxyError(payload);
+                        case 'MemFlowChildError':
+                            throw new errors_1.MemFlowChildError(payload);
+                        case 'MemFlowSleepError':
+                            throw new errors_1.MemFlowSleepError(payload);
+                        case 'MemFlowTimeoutError':
+                            throw new errors_1.MemFlowTimeoutError(payload.message, payload.stack);
+                        case 'MemFlowMaxedError':
+                            throw new errors_1.MemFlowMaxedError(payload.message, payload.stack);
+                        case 'MemFlowFatalError':
+                            throw new errors_1.MemFlowFatalError(payload.message, payload.stack);
+                        case 'MemFlowRetryError':
+                            throw new errors_1.MemFlowRetryError(payload.message, payload.stack);
+                        default:
+                            throw new errors_1.MemFlowRetryError(`Unknown interruption type: ${payload.type}`);
+                    }
+                }
                 return {
                     code: 200,
                     status: stream_1.StreamStatus.SUCCESS,
@@ -431,6 +456,7 @@ class WorkerService {
                             maximumAttempts: err.maximumAttempts || enums_1.HMSH_MEMFLOW_MAX_ATTEMPTS,
                             maximumInterval: err.maximumInterval || (0, utils_1.s)(enums_1.HMSH_MEMFLOW_MAX_INTERVAL),
                             originJobId: err.originJobId,
+                            entity: err.entity,
                             parentWorkflowId: err.parentWorkflowId,
                             expire: err.expire,
                             persistent: err.persistent,

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

@@ -22,7 +22,7 @@ function getChildInterruptPayload(context, options, execIndex) {
     }
     const parentWorkflowId = workflowId;
     const taskQueueName = options.taskQueue ?? options.entity;
-    const workflowName = options.entity ?? options.workflowName;
+    const workflowName = options.taskQueue ? options.workflowName : (options.entity ?? options.workflowName);
     const workflowTopic = `${taskQueueName}-${workflowName}`;
     return {
         arguments: [...(options.args || [])],
@@ -32,6 +32,7 @@ function getChildInterruptPayload(context, options, execIndex) {
         maximumAttempts: options?.config?.maximumAttempts ?? common_1.HMSH_MEMFLOW_MAX_ATTEMPTS,
         maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_MEMFLOW_MAX_INTERVAL),
         originJobId: originJobId ?? workflowId,
+        entity: options.entity,
         expire: options.expire ?? expire,
         persistent: options.persistent,
         signalIn: options.signalIn,
@@ -81,6 +82,7 @@ async function execChild(options) {
     const interruptionMessage = getChildInterruptPayload(context, options, execIndex);
     interruptionRegistry.push({
         code: common_1.HMSH_CODE_MEMFLOW_CHILD,
+        type: 'MemFlowChildError',
         ...interruptionMessage,
     });
     await (0, common_1.sleepImmediate)();

package/build/services/memflow/workflow/execHook.d.ts

@@ -3,8 +3,8 @@ import { HookOptions } from './common';
  * Extended hook options that include signal configuration
  */
 export interface ExecHookOptions extends HookOptions {
-    /** Signal ID to send after hook execution */
-    signalId: string;
+    /** Signal ID to send after hook execution; if not provided, a random one will be generated */
+    signalId?: string;
 }
 /**
  * Executes a hook function and awaits the signal response.

package/build/services/memflow/workflow/execHook.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.execHook = void 0;
 const hook_1 = require("./hook");
 const waitFor_1 = require("./waitFor");
+const interruption_1 = require("./interruption");
 /**
  * Executes a hook function and awaits the signal response.
  * This is a convenience method that combines `hook()` and `waitFor()` operations.
@@ -60,14 +61,23 @@ const waitFor_1 = require("./waitFor");
  * ```
  */
 async function execHook(options) {
-    // Create hook options with signal field added to args
-    const hookOptions = {
-        ...options,
-        args: [...options.args, { signal: options.signalId }]
-    };
-    // Execute the hook with the signal information
-    await (0, hook_1.hook)(hookOptions);
-    // Wait for the signal response and return it
-    return await (0, waitFor_1.waitFor)(options.signalId);
+    try {
+        if (!options.signalId) {
+            options.signalId = 'memflow-hook-' + crypto.randomUUID();
+        }
+        const hookOptions = {
+            ...options,
+            args: [...options.args, { signal: options.signalId, $memflow: true }]
+        };
+        // Execute the hook with the signal information
+        await (0, hook_1.hook)(hookOptions);
+        // Wait for the signal response and return it
+        return await (0, waitFor_1.waitFor)(options.signalId);
+    }
+    catch (error) {
+        if ((0, interruption_1.didInterrupt)(error)) {
+            throw error;
+        }
+    }
 }
 exports.execHook = execHook;

package/build/services/memflow/workflow/interruption.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Checks if an error is a HotMesh reserved error type that indicates
+ * a workflow interruption rather than a true error condition.
+ *
+ * When this returns true, you can safely return from your workflow function.
+ * The workflow engine will handle the interruption automatically.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someWorkflowOperation();
+ * } catch (error) {
+ *   // Check if this is a HotMesh interruption
+ *   if (didInterrupt(error)) {
+ *     // Rethrow the error if HotMesh interruption
+ *     throw error;
+ *   }
+ *   // Handle actual error
+ *   console.error('Workflow failed:', error);
+ * }
+ * ```
+ *
+ * @param error - The error to check
+ * @returns true if the error is a HotMesh interruption
+ */
+export declare function didInterrupt(error: Error): boolean;

package/build/services/memflow/workflow/interruption.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didInterrupt = void 0;
+const errors_1 = require("../../../modules/errors");
+/**
+ * Checks if an error is a HotMesh reserved error type that indicates
+ * a workflow interruption rather than a true error condition.
+ *
+ * When this returns true, you can safely return from your workflow function.
+ * The workflow engine will handle the interruption automatically.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someWorkflowOperation();
+ * } catch (error) {
+ *   // Check if this is a HotMesh interruption
+ *   if (didInterrupt(error)) {
+ *     // Rethrow the error if HotMesh interruption
+ *     throw error;
+ *   }
+ *   // Handle actual error
+ *   console.error('Workflow failed:', error);
+ * }
+ * ```
+ *
+ * @param error - The error to check
+ * @returns true if the error is a HotMesh interruption
+ */
+function didInterrupt(error) {
+    return (error instanceof errors_1.MemFlowChildError ||
+        error instanceof errors_1.MemFlowFatalError ||
+        error instanceof errors_1.MemFlowMaxedError ||
+        error instanceof errors_1.MemFlowProxyError ||
+        error instanceof errors_1.MemFlowRetryError ||
+        error instanceof errors_1.MemFlowSleepError ||
+        error instanceof errors_1.MemFlowTimeoutError ||
+        error instanceof errors_1.MemFlowWaitForError ||
+        error instanceof errors_1.MemFlowWaitForAllError);
+}
+exports.didInterrupt = didInterrupt;

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

@@ -67,6 +67,7 @@ function wrapActivity(activityName, options) {
         const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, args, options);
         interruptionRegistry.push({
             code: common_1.HMSH_CODE_MEMFLOW_PROXY,
+            type: 'MemFlowProxyError',
             ...interruptionMessage,
         });
         await (0, common_1.sleepImmediate)();

package/build/services/memflow/workflow/sleepFor.js

@@ -43,6 +43,7 @@ async function sleepFor(duration) {
     };
     interruptionRegistry.push({
         code: common_1.HMSH_CODE_MEMFLOW_SLEEP,
+        type: 'MemFlowSleepError',
         ...interruptionMessage,
     });
     await (0, common_1.sleepImmediate)();

package/build/services/memflow/workflow/waitFor.js

@@ -45,11 +45,10 @@ async function waitFor(signalId) {
         signalId,
         index: execIndex,
         workflowDimension,
-    };
-    interruptionRegistry.push({
+        type: 'MemFlowWaitForError',
         code: common_1.HMSH_CODE_MEMFLOW_WAIT,
-        ...interruptionMessage,
-    });
+    };
+    interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();
     throw new common_1.MemFlowWaitForError(interruptionMessage);
 }

package/build/types/activity.d.ts

@@ -9,6 +9,7 @@ interface BaseActivity {
     statusThreshold?: number;
     statusThresholdType?: 'stop' | 'throw' | 'stall';
     input?: Record<string, any>;
+    entity?: string;
     output?: Record<string, any>;
     settings?: Record<string, any>;
     job?: Record<string, any>;
@@ -73,6 +74,7 @@ interface TriggerActivityStats {
 interface TriggerActivity extends BaseActivity {
     type: 'trigger';
     stats?: TriggerActivityStats;
+    entity?: string;
 }
 interface AwaitActivity extends BaseActivity {
     type: 'await';

package/build/types/error.d.ts

@@ -6,6 +6,7 @@ export type MemFlowChildErrorType = {
     expire?: number;
     persistent?: boolean;
     signalIn?: boolean;
+    entity?: string;
     maximumAttempts?: number;
     maximumInterval?: number;
     originJobId: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",