@hotmeshio/hotmesh 0.8.0 → 0.9.0

package/.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npx tsc:*)"
+      "Bash(npx tsc:*)",
+      "Bash(wc:*)"
     ]
   }
 }

package/README.md

@@ -4,27 +4,41 @@
 
 Run durable workflows on Postgres. No servers, no queues, just your database.
 
+```bash
+npm install @hotmeshio/hotmesh
+```
+
+## Use HotMesh for
 
-## Common Use Cases
+- **Durable pipelines** — Orchestrate long-running, multi-step pipelines transactionally.
+- **Temporal replacement** — MemFlow provides a Temporal-compatible API that runs directly on Postgres. No app server required.
+- **Distributed state machines** — Build stateful applications where every component can [fail and recover](https://github.com/hotmeshio/sdk-typescript/blob/main/services/collator/README.md).
+- **AI and training pipelines** — Multi-step AI workloads where each stage is expensive and must not be repeated on failure. A crashed pipeline resumes from the last committed step, not from the beginning.
 
-### 1. Pipeline Database
-Transform Postgres into a durable pipeline processor. Orchestrate long-running, multi-step pipelines transactionally and durably.
+> **MemFlow** is HotMesh's Temporal-compatible workflow module — a static class (`MemFlow.Client`, `MemFlow.Worker`, `MemFlow.workflow`) that provides the same developer experience as Temporal's SDK but runs entirely on Postgres.
 
-### 2. Temporal You Own
-Get the power of Temporal without the infrastructure. HotMesh includes MemFlow, a Temporal-compatible API that runs directly on your Postgres database. No app server required.
+## How it works in 30 seconds
 
-### 3. Distributed State Machine
-Build resilient, stateful applications where every component can [fail and recover](https://github.com/hotmeshio/sdk-typescript/blob/main/services/collator/README.md). HotMesh manages state transitions, retries, and coordination.
+1. **You write workflow functions.** Plain TypeScript — branching, loops, error handling. HotMesh also supports a YAML syntax for declarative, functional workflows.
+2. **HotMesh compiles them into a transactional execution plan.** Each step becomes a committed database row. If the process crashes mid-workflow, it resumes from the last committed step.
+3. **Your Postgres database is the engine.** It stores state, coordinates retries, and delivers messages. Every connected client participates in execution — there is no central server.
 
-### 4. Workflow-as-Code Platform
-Choose your style: procedural workflows with MemFlow's Temporal API, or functional workflows with HotMesh's YAML syntax.
+## Quickstart
 
-## Installation
+Start Postgres locally (or use an existing instance), then:
 
 ```bash
 npm install @hotmeshio/hotmesh
 ```
 
+The repo includes a `docker-compose.yml` that starts Postgres (and NATS, if needed):
+
+```bash
+docker compose up -d postgres
+```
+
+Then follow the [Quick Start guide](./docs/quickstart.md) for a progressive walkthrough — from a single trigger to conditional, parallel, and compositional workflows.
+
 ## Two ways to write workflows
 
 Both approaches reuse your activity functions:
@@ -52,13 +66,13 @@ import { MemFlow } from '@hotmeshio/hotmesh';
 import * as activities from './activities';
 
 export async function orderWorkflow(itemId: string, qty: number) {
-  const { checkInventory, reserveItem, notifyBackorder } = 
+  const { checkInventory, reserveItem, notifyBackorder } =
     MemFlow.workflow.proxyActivities<typeof activities>({
       taskQueue: 'inventory-tasks'
     });
-  
+
   const available = await checkInventory(itemId);
-  
+
   if (available >= qty) {
     return await reserveItem(itemId, qty);
   } else {
@@ -102,23 +116,23 @@ const result = await handle.result();
 activities:
   trigger:
     type: trigger
-    
+
   checkInventory:
     type: worker
     topic: inventory.check
-    
+
   reserveItem:
     type: worker
     topic: inventory.reserve
-    
+
   notifyBackorder:
     type: worker
     topic: inventory.backorder.notify
-    
+
 transitions:
   trigger:
     - to: checkInventory
-    
+
   checkInventory:
     - to: reserveItem
       conditions:
@@ -128,7 +142,7 @@ transitions:
               '@pipe':
                 - ['{checkInventory.output.data.availableQty}', '{trigger.output.data.requestedQty}']
                 - ['{@conditional.gte}']
-    
+
     - to: notifyBackorder
       conditions:
         match:
@@ -139,6 +153,7 @@ transitions:
                 - ['{@conditional.gte}']
 ```
 
+Deploy and run as follows:
 ```typescript
 // main.ts (reuses same activities.ts)
 import * as activities from './activities';
@@ -185,42 +200,147 @@ const result = await hotMesh.pubsub('order.requested', {
 
 Both compile to the same distributed execution model.
 
-## Core features
+## Common patterns
 
-- **Durable execution** - Survives crashes, retries automatically
-- **No infrastructure** - Runs on your existing Postgres
-- **Temporal compatible** - Drop-in replacement for many use cases
-- **Distributed** - Every client participates in execution
-- **Observable** - Full execution history in your database
+All snippets below run inside a workflow function (like `orderWorkflow` above). MemFlow methods are available as static imports:
 
-## Common patterns
+```typescript
+import { MemFlow } from '@hotmeshio/hotmesh';
+```
 
-**Long-running workflows**
+**Long-running workflows** — `sleepFor` is durable. The process can restart; the timer survives.
 
 ```typescript
-await sleep('30 days');
+// sendFollowUp is a proxied activity from proxyActivities()
+await MemFlow.workflow.sleepFor('30 days');
 await sendFollowUp();
 ```
 
-**Parallel execution**
+**Parallel execution** — fan out to multiple activities and wait for all results.
 
 ```typescript
-const results = await Promise.all([
-  processPayment(),
-  updateInventory(),
-  notifyWarehouse()
+// proxied activities run as durable, retryable steps
+const [payment, inventory, shipment] = await Promise.all([
+  processPayment(orderId),
+  updateInventory(orderId),
+  notifyWarehouse(orderId)
 ]);
 ```
 
-**Child workflows**
+**Child workflows** — compose workflows from other workflows.
 
 ```typescript
-const childHandle = await startChild(validateOrder, { args: [orderId] });
+const childHandle = await MemFlow.workflow.startChild(validateOrder, {
+  args: [orderId],
+  taskQueue: 'validation',
+  workflowId: `validate-${orderId}`
+});
 const validation = await childHandle.result();
 ```
 
-## License
+**Signals** — pause a workflow until an external event arrives.
 
-HotMesh is licensed under the Apache License, Version 2.0.
+```typescript
+const approval = await MemFlow.workflow.waitFor<{ approved: boolean }>('manager-approval');
+if (!approval.approved) return 'rejected';
+```
+
+## Retries and error handling
+
+Activities retry automatically on failure. Configure the policy per activity or per worker:
+
+```typescript
+// MemFlow: per-activity retry policy
+const { reserveItem } = MemFlow.workflow.proxyActivities<typeof activities>({
+  taskQueue: 'inventory-tasks',
+  retryPolicy: {
+    maximumAttempts: 5,
+    backoffCoefficient: 2,
+    maximumInterval: '60s'
+  }
+});
+```
+
+```typescript
+// HotMesh: worker-level retry policy
+const hotMesh = await HotMesh.init({
+  appId: 'orders',
+  engine: { connection },
+  workers: [{
+    topic: 'inventory.reserve',
+    connection,
+    retryPolicy: {
+      maximumAttempts: 5,
+      backoffCoefficient: 2,
+      maximumInterval: '60s'
+    },
+    callback: async (data) => { /* ... */ }
+  }]
+});
+```
+
+Defaults: 3 attempts, coefficient 10, 120s cap. Delay formula: `min(coefficient ^ attempt, maximumInterval)`. Duration strings like `'5 seconds'`, `'2 minutes'`, and `'1 hour'` are supported.
+
+If all retries are exhausted, the activity fails and the error propagates to the workflow function — handle it with a standard `try/catch`.
+
+## It's just data
+
+There is nothing between you and your data. Workflow state lives in your database as ordinary rows — `jobs` and `jobs_attributes`. Query it directly, back it up with pg_dump, replicate it, join it against your application tables.
+
+```sql
+SELECT
+  j.key          AS job_key,
+  j.status       AS semaphore,
+  j.entity       AS workflow,
+  a.field        AS attribute,
+  a.value        AS value,
+  j.created_at,
+  j.updated_at
+FROM
+  jobs j
+  JOIN jobs_attributes a ON a.job_id = j.id
+WHERE
+  j.key = 'order-456'
+ORDER BY
+  a.field;
+```
+
+What happened? Consult the database. What's still running? Query the semaphore. What failed? Read the row. The execution state isn't reconstructed from a log — it was committed transactionally as each step ran.
+
+You can also use the Temporal-compatible API:
+
+```typescript
+const handle = client.workflow.getHandle('orders', 'orderWorkflow', 'order-456');
+
+const result = await handle.result();           // final output
+const status = await handle.status();           // semaphore (0 = complete)
+const state  = await handle.state(true);        // full state with metadata
+const exported = await handle.export({          // selective export
+  allow: ['data', 'state', 'status', 'timeline']
+});
+```
+
+## Observability
+
+There is no proprietary dashboard. Workflow state lives in Postgres, so use whatever tools you already have:
+
+- **Direct SQL** — query `jobs` and `jobs_attributes` to inspect state, as shown above.
+- **Handle API** — `handle.status()`, `handle.state(true)`, and `handle.export()` give programmatic access to any running or completed workflow.
+- **Logging** — set `HMSH_LOGLEVEL` (`debug`, `info`, `warn`, `error`, `silent`) to control log verbosity.
+- **OpenTelemetry** — set `HMSH_TELEMETRY=true` to emit spans and metrics. Plug in any OTel-compatible collector (Jaeger, Datadog, etc.).
+
+## Architecture
+
+For a deep dive into the transactional execution model — how every step is crash-safe, how the monotonic collation ledger guarantees exactly-once delivery, and how cycles and retries remain correct under arbitrary failure — see the [Collation Design Document](https://github.com/hotmeshio/sdk-typescript/blob/main/services/collator/README.md). The symbolic system (how to design workflows) and lifecycle details (how to deploy workflows) are covered in the [Architectural Overview](https://zenodo.org/records/12168558).
+
+## Familiar with Temporal?
+
+MemFlow is designed as a drop-in-compatible alternative for common Temporal patterns.
+
+**What's the same:** `Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`/`execChild`, signals (`waitFor`/`signal`), retry policies, and the overall workflow-as-code programming model.
+
+**What's different:** No Temporal server or cluster to operate. Postgres is the only infrastructure dependency — it stores state, coordinates workers, and delivers messages. HotMesh also offers a YAML-based approach for declarative workflows that compile to the same execution model.
+
+## License
 
-You may use, modify, and distribute HotMesh in accordance with the license, including as part of your own applications and services. However, offering HotMesh itself as a standalone, hosted commercial orchestration service (or a substantially similar service) requires prior written permission from the author.
+HotMesh is source-available under the [HotMesh Source Available License](./LICENSE).

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.8.0",
+    "version": "0.9.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -19,72 +19,69 @@
         "lint": "eslint . --ext .ts",
         "lint:fix": "eslint . --fix --ext .ts",
         "start": "ts-node src/index.ts",
-        "test": "NODE_ENV=test jest --detectOpenHandles --forceExit --verbose",
-        "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:compile": "NODE_ENV=test jest ./tests/functional/compile/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:connect": "NODE_ENV=test jest ./tests/unit/services/connector/* --detectOpenHandles --forceExit --verbose",
-        "test:connect:postgres": "NODE_ENV=test jest ./tests/unit/services/connector/providers/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "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:postgres": "HMSH_LOGLEVEL=info NODE_ENV=test jest ./tests/memflow/*/postgres.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/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=info jest ./tests/memflow/interceptor/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 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: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:cycle": "NODE_ENV=test jest ./tests/functional/cycle/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:functional": "NODE_ENV=test jest ./tests/functional/**/postgres.test.ts --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/postgres.test.ts --detectOpenHandles --verbose --forceExit",
-        "test:hook": "NODE_ENV=test jest ./tests/functional/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:interrupt": "NODE_ENV=test jest ./tests/functional/interrupt/postgres.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/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:redeploy": "NODE_ENV=test jest ./tests/functional/redeploy/postgres.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/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:retry": "NODE_ENV=test jest ./tests/functional/retry/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=info jest ./tests/functional/sequence/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:signal": "NODE_ENV=test jest ./tests/functional/signal/postgres.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",
-        "test:store:postgres": "NODE_ENV=test jest ./tests/functional/store/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:stream:postgres": "NODE_ENV=test jest ./tests/functional/stream/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:stream:nats": "NODE_ENV=test jest ./tests/functional/stream/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sub:postgres": "NODE_ENV=test jest ./tests/functional/sub/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sub:nats": "NODE_ENV=test jest ./tests/functional/sub/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:meshcall": "NODE_ENV=test jest ./tests/meshcall/*.test.ts --forceExit --verbose --detectOpenHandles",
-        "test:unit": "NODE_ENV=test jest ./tests/unit/*/*/index.test.ts --detectOpenHandles --forceExit --verbose"
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:await": "vitest run tests/functional/awaiter/postgres.test.ts",
+        "test:compile": "vitest run tests/functional/compile/index.test.ts",
+        "test:connect": "vitest run tests/unit/services/connector",
+        "test:connect:postgres": "vitest run tests/unit/services/connector/providers/postgres.test.ts",
+        "test:connect:nats": "vitest run tests/unit/services/connector/providers/nats.test.ts",
+        "test:memflow": "vitest run tests/memflow",
+        "test:memflow:postgres": "HMSH_LOGLEVEL=info vitest run tests/memflow",
+        "test:memflow:basic": "HMSH_LOGLEVEL=info vitest run tests/memflow/basic/postgres.test.ts",
+        "test:memflow:collision": "vitest run tests/memflow/collision/postgres.test.ts",
+        "test:memflow:fatal": "vitest run tests/memflow/fatal",
+        "test:memflow:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/memflow/goodbye/postgres.test.ts",
+        "test:memflow:interceptor": "HMSH_LOGLEVEL=info vitest run tests/memflow/interceptor/postgres.test.ts",
+        "test:memflow:entity": "HMSH_LOGLEVEL=debug vitest run tests/memflow/entity/postgres.test.ts",
+        "test:memflow:agent": "HMSH_LOGLEVEL=debug vitest run tests/memflow/agent/postgres.test.ts",
+        "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=info vitest run tests/memflow/helloworld/postgres.test.ts",
+        "test:memflow:hook": "vitest run tests/memflow/hook/postgres.test.ts",
+        "test:memflow:interrupt": "vitest run tests/memflow/interrupt/postgres.test.ts",
+        "test:memflow:loopactivity": "vitest run tests/memflow/loopactivity/postgres.test.ts",
+        "test:memflow:nested": "vitest run tests/memflow/nested/postgres.test.ts",
+        "test:memflow:pipeline": "vitest run tests/memflow/pipeline/postgres.test.ts",
+        "test:memflow:retry": "vitest run tests/memflow/retry/postgres.test.ts",
+        "test:memflow:retrypolicy": "vitest run tests/memflow/retry-policy",
+        "test:memflow:sleep": "vitest run tests/memflow/sleep/postgres.test.ts",
+        "test:memflow:signal": "vitest run tests/memflow/signal/postgres.test.ts",
+        "test:memflow:unknown": "vitest run tests/memflow/unknown/postgres.test.ts",
+        "test:cycle": "vitest run tests/functional/cycle",
+        "test:functional": "vitest run tests/functional",
+        "test:emit": "vitest run tests/functional/emit",
+        "test:pending": "vitest run tests/functional/pending/index.test.ts",
+        "test:hmsh": "vitest run tests/functional/postgres.test.ts",
+        "test:hook": "vitest run tests/functional/hook/postgres.test.ts",
+        "test:interrupt": "vitest run tests/functional/interrupt/postgres.test.ts",
+        "test:parallel": "vitest run tests/functional/parallel/index.test.ts",
+        "test:pipe": "vitest run tests/unit/services/pipe/index.test.ts",
+        "test:quorum": "vitest run tests/functional/quorum/postgres.test.ts",
+        "test:reclaim": "vitest run tests/functional/reclaim/postgres.test.ts",
+        "test:redeploy": "vitest run tests/functional/redeploy/postgres.test.ts",
+        "test:reporter": "vitest run tests/unit/services/reporter/index.test.ts",
+        "test:reentrant": "vitest run tests/functional/reentrant/postgres.test.ts",
+        "test:retry": "vitest run tests/functional/retry/postgres.test.ts",
+        "test:retrypolicy": "vitest run tests/functional/retry-policy",
+        "test:sequence": "HMSH_LOGLEVEL=info vitest run tests/functional/sequence/postgres.test.ts",
+        "test:signal": "vitest run tests/functional/signal/postgres.test.ts",
+        "test:status": "vitest run tests/functional/status/index.test.ts",
+        "test:providers": "vitest run tests/functional/*/providers",
+        "test:store:postgres": "vitest run tests/functional/store/providers/postgres/postgres.test.ts",
+        "test:stream:postgres": "vitest run tests/functional/stream/providers/postgres/postgres.test.ts",
+        "test:stream:nats": "vitest run tests/functional/stream/providers/nats/nats.test.ts",
+        "test:sub:postgres": "vitest run tests/functional/sub/providers/postgres/postgres.test.ts",
+        "test:sub:nats": "vitest run tests/functional/sub/providers/nats/nats.test.ts",
+        "test:trigger": "vitest run tests/unit/services/activities/trigger.test.ts",
+        "test:meshcall": "vitest run tests/meshcall",
+        "test:unit": "vitest run tests/unit"
     },
     "keywords": [
         "Headless Orchestration",
-        "Persistent Workflow",
-        "Durable Workflow",
-        "Operational Data",
+        "Durable Workflows",
+        "Data in Motion",
         "Service Mesh",
         "HotMesh",
-        "Postgres",
-        "OLAP",
-        "OLTP",
-        "HTAP"
+        "Postgres"
     ],
     "author": "luke.birdeau@gmail.com",
     "license": "SEE LICENSE IN LICENSE",
@@ -99,8 +96,7 @@
         "winston": "^3.8.2"
     },
     "devDependencies": {
-        "@types/jest": "^29.5.0",
-        "@types/node": "^18.15.11",
+        "@types/node": "^20.19.33",
         "@types/pg": "^8.10.0",
         "@typescript-eslint/eslint-plugin": "^5.62.0",
         "@typescript-eslint/parser": "^5.62.0",
@@ -110,17 +106,16 @@
         "eslint-plugin-import": "^2.29.1",
         "eslint-plugin-prettier": "^5.1.3",
         "javascript-obfuscator": "^0.6.2",
-        "jest": "^29.5.0",
         "nats": "^2.28.0",
         "openai": "^5.9.0",
         "pg": "^8.10.0",
         "rimraf": "^4.4.1",
         "terser": "^5.37.0",
-        "ts-jest": "^29.0.5",
         "ts-node": "^10.9.1",
         "ts-node-dev": "^2.0.0",
         "typedoc": "^0.26.4",
-        "typescript": "^5.0.4"
+        "typescript": "^5.0.4",
+        "vitest": "^2.1.9"
     },
     "peerDependencies": {
         "nats": "^2.0.0",

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

@@ -7,13 +7,69 @@ import { JobState, JobStatus } from '../../types/job';
 import { StringAnyType } from '../../types/serializer';
 import { StreamCode, StreamData, StreamStatus } from '../../types/stream';
 /**
- * The base class for all activities
+ * Base class for all HotMesh activity types. Activities are the execution
+ * units within a YAML-defined workflow graph. Each activity represents a
+ * node in a Directed Acyclic Graph (DAG) that the engine orchestrates.
+ *
+ * ## Activity Categories
+ *
+ * Activities fall into three execution categories:
+ *
+ * - **Category A (Duplex)**: Two-phase activities with Leg 1 (dispatch) and
+ *   Leg 2 (response). Used by `Worker` and `Await`. Leg 1
+ *   publishes a message and waits; Leg 2 handles the response via
+ *   `processEvent` and transitions to adjacent activities.
+ *
+ * - **Category B (Leg1-only with children)**: Single-phase activities that
+ *   execute work and transition to children using the crash-safe
+ *   `executeLeg1StepProtocol`. Used by `Hook` (passthrough mode),
+ *   `Signal`, and `Interrupt` (target mode).
+ *
+ * - **Category C (Leg1-only, no children)**: Terminal activities that
+ *   execute without spawning children. Used by `Interrupt` (self mode).
+ *
+ * ## Shared YAML Configuration
+ *
+ * All activity types support these base properties in the YAML descriptor:
+ *
+ * | Property             | Type    | Description |
+ * |----------------------|---------|-------------|
+ * | `type`               | string  | Activity type: `trigger`, `worker`, `await`, `hook`, `signal`, `interrupt`, `cycle` |
+ * | `title`              | string  | Human-readable label for the activity |
+ * | `input.schema`       | object  | JSON Schema for input validation |
+ * | `input.maps`         | object  | Maps data from other activities into this activity's input |
+ * | `output.schema`      | object  | JSON Schema for output validation |
+ * | `output.maps`        | object  | Maps/transforms the activity's own output data |
+ * | `job.maps`           | object  | Maps activity data to the shared job state |
+ * | `emit`               | boolean | If `true`, emits a message to the graph's `publishes` topic |
+ * | `persist`            | boolean | If `true`, emits the job-completed event while keeping the job active |
+ * | `expire`             | number  | Seconds until the job expires after completion (`-1` = forever) |
+ * | `statusThreshold`    | number  | Custom semaphore threshold for Dynamic Activation Control |
+ * | `cycle`              | boolean | If `true`, leaves Leg 2 open so the activity can be re-entered |
+ *
+ * ## Data Mapping Syntax
+ *
+ * Mapping expressions use curly-brace references to bind data between
+ * activities and the shared job state:
+ *
+ * ```yaml
+ * input:
+ *   maps:
+ *     x: '{t1.output.data.fieldName}'      # reference another activity's output
+ *     y: '{$self.output.data.fieldName}'    # reference own output
+ *     z: '{$job.data.fieldName}'            # reference shared job state
+ *     s: '{$app.settings.configKey}'        # reference app-level settings
+ * ```
+ *
+ * @see {@link https://hotmeshio.github.io/sdk-typescript/docs/quickstart | Quick Start Guide}
+ * @see [Model Driven Development](https://hotmeshio.github.io/sdk-typescript/docs/model_driven_development)
  */
 declare class Activity {
     config: ActivityType;
     data: ActivityData;
     hook: ActivityData;
     metadata: ActivityMetadata;
+    /** @hidden */
     store: StoreService<ProviderClient, ProviderTransaction>;
     context: JobState;
     engine: EngineService;
@@ -95,7 +151,7 @@ declare class Activity {
     getTriggerConfig(): Promise<ActivityType>;
     getJobStatus(): null | number;
     setStatus(amount: number, transaction?: ProviderTransaction): Promise<void | any>;
-    authorizeEntry(state: StringAnyType): string[];
+    authorizeEntry(_state: StringAnyType): string[];
     bindDimensionalAddress(state: StringAnyType): void;
     setState(transaction?: ProviderTransaction): Promise<string>;
     bindJobMetadata(): void;
@@ -127,11 +183,6 @@ declare class Activity {
      * @private
      */
     shouldPersistJob(): boolean;
-    /**
-     * Transition method for Category C (Leg1-only, no children, no semaphore change)
-     * and Category D (Trigger) activities. NOT used by the Leg2 step protocol.
-     */
-    transition(adjacencyList: StreamData[], jobStatus: JobStatus): Promise<string[]>;
     /**
      * A job with a vale < -100_000_000 is considered interrupted,
      * as the interruption event decrements the job status by 1billion.