@hotmeshio/hotmesh 0.4.2 → 0.5.0

package/README.md

@@ -4,12 +4,12 @@
 
 ![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 a permanent, JSON-backed context that persists independently of the workflow itself.
+**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.
 
 This means:
 
 * Any number of lightweight, thread-safe **hook workers** can attach to the same workflow record at any time.
-* These hooks can safely **read and incrementally write** to shared state.
+* 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**.
 
 ---
@@ -18,7 +18,7 @@ This means:
 
 1. 🚀 Quick Start
 2. 🧠 How Permanent Memory Works
-3. 🔌 Hooks & Context API
+3. 🔌 Hooks & Entity API
 4. 🤖 Building Durable AI Agents
 5. 🔬 Advanced Patterns & Recipes
 6. 📚 Documentation & Links
@@ -51,9 +51,11 @@ async function main() {
 
   // Kick off a workflow
   const handle = await mf.workflow.start({
-    workflowName: 'example',
+    entity: 'user',
+    workflowName: 'userExample',
+    workflowId: 'jane@hotmesh.com',
     args: ['Jane'],
-    taskQueue: 'contextual'
+    taskQueue: 'entityqueue'
   });
 
   console.log('Result:', await handle.result());
@@ -66,17 +68,16 @@ main().catch(console.error);
 
 ## 🧠 How Permanent Memory Works
 
-* **Context = persistent JSON record** – each workflow's memory is stored as a JSONB row in your Postgres database
+* **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
-
-* Context data is stored as JSONB; add partial indexes for improved query analysis.
+* **Index-friendly** - entity data is stored as JSONB; add partial indexes for improved query analysis.
 
 **Example: Adding a Partial Index for Specific Entity Types**
 ```sql
--- Create a partial index for 'user' entities with specific context values
+-- Create a partial index for 'user' entities with specific entity values
 CREATE INDEX idx_user_premium ON your_app.jobs (id)
 WHERE entity = 'user' AND (context->>'isPremium')::boolean = true;
 ```
@@ -84,42 +85,44 @@ This index will only be used for queries that match both conditions, making look
 
 ---
 
-## 🔌 Hooks & Context API – Full Example
+## 🔌 Hooks & Entity API – Full Example
+
+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:
+
+* 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
+
+Here's a complete example showing both internal and external hook usage:
 
 ```typescript
 import { MemFlow } from '@hotmeshio/hotmesh';
 
 /* ------------ Main workflow ------------ */
-export async function example(name: string): Promise<any> {
-  //the context method provides transactional, replayable access to shared job state 
-  const ctx = await MemFlow.workflow.context();
+export async function userExample(name: string): Promise<any> {
+  //the entity method provides transactional, replayable access to shared job state 
+  const entity = await MemFlow.workflow.entity();
 
-  //create the initial context (even arrays are supported)
-  await ctx.set({
+  //create the initial entity (even arrays are supported)
+  await entity.set({
     user: { name },
     hooks: {},
     metrics: { count: 0 }
   });
 
-  // Call two hooks in parallel to updaet the same shared context
-  const [r1, r2] = await Promise.all([
-    MemFlow.workflow.execHook({
-      taskQueue: 'contextual',
-      workflowName: 'hook1',
-      args: [name, 'hook1'],
-      signalId: 'hook1-complete',
-    }),
-    MemFlow.workflow.execHook({
-      taskQueue: 'contextual',
-      workflowName: 'hook2',
-      args: [name, 'hook2'],
-      signalId: 'hook2-complete',
-    })
-  ]);
-
-  // merge here (or have the hooks merge in...everyone can access context)
-  await ctx.merge({ hooks: { r1, r2 } });
-  await ctx.increment('metrics.count', 2);
+  // Call one hook internally
+  const result1 = await MemFlow.workflow.execHook({
+    taskQueue: 'entityqueue',
+    workflowName: 'hook1',
+    args: [name, 'hook1'],
+    signalId: 'hook1-complete'
+  });
+
+  // merge the result
+  await entity.merge({ hooks: { r1: result1 } });
+  await entity.increment('metrics.count', 1);
 
   return "The main has completed; the db record persists and can be hydrated; hook in from the outside!";
 }
@@ -131,10 +134,10 @@ export async function hook1(name: string, kind: string): Promise<any> {
   await MemFlow.workflow.signal('hook1-complete', res);
 }
 
-/* ------------ Hook 2 (hooks can access shared job context) ------------ */
+/* ------------ Hook 2 (hooks can access shared job entity) ------------ */
 export async function hook2(name: string, kind: string): Promise<void> {
-  const ctx = await MemFlow.workflow.context();
-  await ctx.merge({ user: { lastSeen: new Date().toISOString() } });
+  const entity = await MemFlow.workflow.entity();
+  await entity.merge({ user: { lastSeen: new Date().toISOString() } });
   await MemFlow.workflow.signal('hook2-complete', { ok: true });
 }
 
@@ -151,17 +154,17 @@ async function startWorker() {
   });
 
   const worker = await mf.worker.create({
-    taskQueue: 'contextual',
+    taskQueue: 'entityqueue',
     workflow: example
   });
 
   await mf.worker.create({
-    taskQueue: 'contextual',
+    taskQueue: 'entityqueue',
     workflow: hook1
   });
 
   await mf.worker.create({
-    taskQueue: 'contextual',
+    taskQueue: 'entityqueue',
     workflow: hook2
   });
 
@@ -169,19 +172,195 @@ async function startWorker() {
 }
 ```
 
+### 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:
+
+* 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
+
+Here's how to hook into an existing workflow from the outside:
+
+```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 }
+      }
+    }
+  });
+
+  // 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']
+  });
+}
+```
+
 ---
 
 ## 🤖 Building Durable AI Agents
 
-Permanent memory unlocks a straightforward pattern for agentic systems:
+HotMesh's permanent memory enables a revolutionary approach to AI agents: **perspective-oriented intelligence**. Instead of monolithic agents, you build **multi-faceted agents** where:
+
+* **Entity state** = the agent's living, evolving context
+* **Hooks** = different perspectives that operate on that context
+* **Child workflows** = specialized co-agents with their own entity types
+* **Shared memory** = enables rich self-reflection and multi-agent collaboration
+
+### Example: A Research Agent with Multiple Perspectives
+
+```typescript
+/* ------------ Main Research Agent ------------ */
+export async function researchAgent(query: string): Promise<any> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Initialize agent context
+  await entity.set({
+    query,
+    findings: [],
+    perspectives: {},
+    confidence: 0,
+    status: 'researching'
+  });
+
+  // Spawn perspective hooks that operate on shared context
+  const optimisticView = MemFlow.workflow.execHook({
+    taskQueue: 'perspectives',
+    workflowName: 'optimisticPerspective',
+    args: [query]
+  });
+
+  const skepticalView = MemFlow.workflow.execHook({
+    taskQueue: 'perspectives', 
+    workflowName: 'skepticalPerspective',
+    args: [query]
+  });
+
+  // Spawn a fact-checker child agent with its own entity type
+  const factChecker = await MemFlow.workflow.execChild({
+    entity: 'fact-checker',
+    workflowName: 'factCheckAgent',
+    workflowId: `fact-check-${Date.now()}`,
+    args: [query],
+    taskQueue: 'agents'
+  });
+
+  // Wait for all perspectives to contribute
+  await Promise.all([optimisticView, skepticalView, factChecker]);
+
+  // Self-reflection: analyze conflicting perspectives
+  await MemFlow.workflow.execHook({
+    taskQueue: 'perspectives',
+    workflowName: 'synthesizePerspectives',
+    args: []
+  });
+
+  const finalContext = await entity.get();
+  return finalContext;
+}
+
+/* ------------ Optimistic Perspective Hook ------------ */
+export async function optimisticPerspective(query: string): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Optimistic perspective: look for supporting evidence
+  const findings = await searchForSupportingEvidence(query);
+  
+  await entity.merge({
+    perspectives: {
+      optimistic: {
+        findings,
+        confidence: 0.8,
+        bias: 'Tends to emphasize positive evidence'
+      }
+    }
+  });
+}
+
+/* ------------ Skeptical Perspective Hook ------------ */
+export async function skepticalPerspective(query: string): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Skeptical perspective: challenge assumptions
+  const counterEvidence = await searchForCounterEvidence(query);
+  
+  await entity.merge({
+    perspectives: {
+      skeptical: {
+        counterEvidence,
+        confidence: 0.6,
+        bias: 'Challenges assumptions and seeks contradictory evidence'
+      }
+    }
+  });
+}
+
+/* ------------ Fact-Checker Child Agent ------------ */
+export async function factCheckAgent(query: string): Promise<any> {
+  // This child has its own entity type for specialized fact-checking context
+  const entity = await MemFlow.workflow.entity();
+  
+  await entity.set({
+    query,
+    sources: [],
+    verifications: [],
+    credibilityScore: 0
+  });
+
+  // Fact-checker can spawn its own specialized hooks
+  await MemFlow.workflow.execHook({
+    taskQueue: 'verification',
+    workflowName: 'verifySourceCredibility',
+    args: [query]
+  });
+
+  return await entity.get();
+}
+
+/* ------------ Synthesis Perspective Hook ------------ */
+export async function synthesizePerspectives(): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  const context = await entity.get();
+  
+  // Analyze conflicting perspectives and synthesize
+  const synthesis = await analyzePerspectives(context.perspectives);
+  
+  await entity.merge({
+    perspectives: {
+      synthesis: {
+        finalAssessment: synthesis,
+        confidence: calculateConfidence(context.perspectives),
+        reasoning: 'Balanced analysis of optimistic and skeptical viewpoints'
+      }
+    },
+    status: 'completed'
+  });
+}
+```
+
+### The Power of Perspective-Oriented Agents
+
+This approach enables agents that can:
 
-1. **Planner workflow** – sketches a task list, seeds context.
-2. **Tool hooks** – execute individual tasks, feeding intermediate results back into context.
-3. **Reflector hook** – periodically summarises context into long-term memory embeddings.
-4. **Supervisor workflow** – monitors metrics stored in context and decides when to finish.
+* **Question themselves** – different hooks challenge each other's assumptions
+* **Spawn specialized co-agents** – child workflows with their own entity types tackle specific domains
+* **Maintain rich context** – all perspectives contribute to a shared, evolving knowledge base
+* **Scale horizontally** – each perspective can run on different workers
+* **Learn continuously** – entity state accumulates insights across all interactions
+* **Self-reflect** – synthesis hooks analyze conflicting perspectives and improve decision-making
 
-Because every step is durable *and* shares the same knowledge object, agents can pause,
-restart, scale horizontally, and keep evolving their world-model indefinitely.
+Because every perspective operates on the same durable entity, agents can pause, restart, and evolve their world-model indefinitely while maintaining coherent, multi-faceted intelligence.
 
 ---
 

package/build/index.d.ts

@@ -5,6 +5,7 @@ import { MemFlow } from './services/memflow';
 import { ClientService as Client } from './services/memflow/client';
 import { ConnectionService as Connection } from './services/memflow/connection';
 import { Search } from './services/memflow/search';
+import { Entity } from './services/memflow/entity';
 import { WorkerService as Worker } from './services/memflow/worker';
 import { WorkflowService as workflow } from './services/memflow/workflow';
 import { WorkflowHandleService as WorkflowHandle } from './services/memflow/handle';
@@ -21,5 +22,5 @@ import { RedisConnection as ConnectorIORedis } from './services/connector/provid
 import { RedisConnection as ConnectorRedis } from './services/connector/providers/redis';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
 export { Connector, //factory
-ConnectorIORedis, ConnectorNATS, ConnectorPostgres, ConnectorRedis, HotMesh, HotMeshConfig, MeshCall, MeshData, MemFlow, MeshOS, Client, Connection, proxyActivities, Search, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
+ConnectorIORedis, ConnectorNATS, ConnectorPostgres, ConnectorRedis, HotMesh, HotMeshConfig, MeshCall, MeshData, MemFlow, MeshOS, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
 export * as Types from './types';

package/build/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.MeshOS = exports.MemFlow = exports.MeshData = exports.MeshCall = exports.HotMesh = exports.ConnectorRedis = exports.ConnectorPostgres = exports.ConnectorNATS = exports.ConnectorIORedis = exports.Connector = void 0;
+exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.MeshOS = exports.MemFlow = exports.MeshData = exports.MeshCall = exports.HotMesh = exports.ConnectorRedis = exports.ConnectorPostgres = exports.ConnectorNATS = exports.ConnectorIORedis = exports.Connector = void 0;
 const hotmesh_1 = require("./services/hotmesh");
 Object.defineProperty(exports, "HotMesh", { enumerable: true, get: function () { return hotmesh_1.HotMesh; } });
 const meshcall_1 = require("./services/meshcall");
@@ -36,6 +36,8 @@ const connection_1 = require("./services/memflow/connection");
 Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return connection_1.ConnectionService; } });
 const search_1 = require("./services/memflow/search");
 Object.defineProperty(exports, "Search", { enumerable: true, get: function () { return search_1.Search; } });
+const entity_1 = require("./services/memflow/entity");
+Object.defineProperty(exports, "Entity", { enumerable: true, get: function () { return entity_1.Entity; } });
 const worker_1 = require("./services/memflow/worker");
 Object.defineProperty(exports, "Worker", { enumerable: true, get: function () { return worker_1.WorkerService; } });
 const workflow_1 = require("./services/memflow/workflow");

package/build/modules/errors.d.ts

@@ -35,6 +35,7 @@ declare class MemFlowProxyError extends Error {
 }
 declare class MemFlowChildError extends Error {
     await: boolean;
+    entity: string;
     arguments: string[];
     backoffCoefficient: number;
     code: number;

package/build/modules/errors.js

@@ -56,6 +56,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;

package/build/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.4.2",
+    "version": "0.5.0",
     "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"
     },
@@ -33,7 +33,8 @@
         "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.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 jest ./tests/memflow/goodbye/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:context": "NODE_ENV=test jest ./tests/memflow/context/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:entity": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/entity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "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 HMSH_IS_CLUSTER=true NODE_ENV=test jest ./tests/memflow/helloworld/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",

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): 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);
+            //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);
@@ -228,9 +231,9 @@ class Trigger extends activity_1.Activity {
         const jobKey = this.config.stats?.key;
         return jobKey ? pipe_1.Pipe.resolve(jobKey, context) : '';
     }
-    async setStateNX(status) {
+    async setStateNX(status, entity) {
         const jobId = this.context.metadata.jid;
-        if (!await this.store.setStateNX(jobId, this.engine.appId, status)) {
+        if (!await this.store.setStateNX(jobId, this.engine.appId, status, entity)) {
             throw new errors_1.DuplicateJobError(jobId);
         }
     }

package/build/services/memflow/client.js

@@ -125,7 +125,7 @@ class ClientService {
              */
             start: async (options) => {
                 const taskQueueName = options.taskQueue ?? options.entity;
-                const workflowName = options.entity ?? options.workflowName;
+                const workflowName = options.taskQueue ? options.workflowName : (options.entity ?? options.workflowName);
                 const trc = options.workflowTrace;
                 const spn = options.workflowSpan;
                 //hotmesh `topic` is equivalent to `queue+workflowname` pattern in other systems
@@ -151,6 +151,7 @@ class ClientService {
                     search: options?.search?.data,
                     marker: options?.marker,
                     pending: options?.pending,
+                    entity: options?.entity,
                 });
                 return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId);
             },

package/build/services/memflow/{context.d.ts → entity.d.ts}

@@ -1,26 +1,26 @@
 import { HotMesh } from '../hotmesh';
 import { SearchService } from '../search';
 /**
- * The Context module provides methods for reading and writing
- * JSONB data to a workflow's context. The instance methods
+ * The Entity module provides methods for reading and writing
+ * JSONB data to a workflow's entity. The instance methods
  * exposed by this class are available for use from within
  * a running workflow.
  *
  * @example
  * ```typescript
- * //contextWorkflow.ts
+ * //entityWorkflow.ts
  * import { workflow } from '@hotmeshio/hotmesh';
  *
- * export async function contextExample(): Promise<void> {
- *   const context = await workflow.context();
- *   await context.set({ user: { id: 123 } });
- *   await context.merge({ user: { name: "John" } });
- *   const user = await context.get("user");
+ * export async function entityExample(): Promise<void> {
+ *   const entity = await workflow.entity();
+ *   await entity.set({ user: { id: 123 } });
+ *   await entity.merge({ user: { name: "John" } });
+ *   const user = await entity.get("user");
  *   // user = { id: 123, name: "John" }
  * }
  * ```
  */
-export declare class Context {
+export declare class Entity {
     /**
      * @private
      */
@@ -56,84 +56,84 @@ export declare class Context {
      */
     getSearchSessionGuid(): string;
     /**
-     * Sets the entire context object. This replaces any existing context.
+     * Sets the entire entity object. This replaces any existing entity.
      *
      * @example
-     * const context = await workflow.context();
-     * await context.set({ user: { id: 123, name: "John" } });
+     * const entity = await workflow.entity();
+     * await entity.set({ user: { id: 123, name: "John" } });
      */
     set(value: any): Promise<any>;
     /**
-     * Deep merges the provided object with the existing context
+     * Deep merges the provided object with the existing entity
      *
      * @example
-     * const context = await workflow.context();
-     * await context.merge({ user: { email: "john@example.com" } });
+     * const entity = await workflow.entity();
+     * await entity.merge({ user: { email: "john@example.com" } });
      */
     merge<T>(value: T): Promise<T>;
     /**
-     * Gets a value from the context by path
+     * Gets a value from the entity by path
      *
      * @example
-     * const context = await workflow.context();
-     * const user = await context.get("user");
-     * const email = await context.get("user.email");
+     * const entity = await workflow.entity();
+     * const user = await entity.get("user");
+     * const email = await entity.get("user.email");
      */
     get(path?: string): Promise<any>;
     /**
-     * Deletes a value from the context by path
+     * Deletes a value from the entity by path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.delete("user.email");
+     * const entity = await workflow.entity();
+     * await entity.delete("user.email");
      */
     delete(path: string): Promise<any>;
     /**
      * Appends a value to an array at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.append("items", { id: 1, name: "New Item" });
+     * const entity = await workflow.entity();
+     * await entity.append("items", { id: 1, name: "New Item" });
      */
     append(path: string, value: any): Promise<any[]>;
     /**
      * Prepends a value to an array at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.prepend("items", { id: 0, name: "First Item" });
+     * const entity = await workflow.entity();
+     * await entity.prepend("items", { id: 0, name: "First Item" });
      */
     prepend(path: string, value: any): Promise<any[]>;
     /**
      * Removes an item from an array at the specified path and index
      *
      * @example
-     * const context = await workflow.context();
-     * await context.remove("items", 0); // Remove first item
+     * const entity = await workflow.entity();
+     * await entity.remove("items", 0); // Remove first item
      */
     remove(path: string, index: number): Promise<any[]>;
     /**
      * Increments a numeric value at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.increment("counter", 5);
+     * const entity = await workflow.entity();
+     * await entity.increment("counter", 5);
      */
     increment(path: string, value?: number): Promise<number>;
     /**
      * Toggles a boolean value at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.toggle("settings.enabled");
+     * const entity = await workflow.entity();
+     * await entity.toggle("settings.enabled");
      */
     toggle(path: string): Promise<boolean>;
     /**
      * Sets a value at the specified path only if it doesn't already exist
      *
      * @example
-     * const context = await workflow.context();
-     * await context.setIfNotExists("user.id", 123);
+     * const entity = await workflow.entity();
+     * await entity.setIfNotExists("user.id", 123);
      */
     setIfNotExists(path: string, value: any): Promise<any>;
     /**