@hotmeshio/hotmesh 0.5.7 → 0.6.0

package/README.md

@@ -1,289 +1,189 @@
 # HotMesh
 
-**Durable Memory + Coordinated Execution**
+**Integrate AI automation into your current stack — without breaking it**
 
 ![beta release](https://img.shields.io/badge/release-beta-blue.svg)
 
-HotMesh removes the repetitive glue of building durable agents, pipelines, and long‑running workflows. You focus on *what* to change; HotMesh handles *how*, safely and durably.
+HotMesh modernizes existing business systems by introducing a durable workflow layer that connects AI, automation, and human-in-the-loop steps — **without replacing your current stack**.
+Each process runs with persistent memory in Postgres, surviving retries, crashes, and human delays.
 
----
-
-## Why Choose HotMesh
-
-- **Zero Boilerplate** - Transactional Postgres without the setup hassle
-- **Built-in Durability** - Automatic crash recovery and replay protection
-- **Parallel by Default** - Run hooks concurrently without coordination
-- **SQL-First** - Query pipeline status and agent memory directly
+```bash
+npm install @hotmeshio/hotmesh
+```
 
 ---
 
-## Core Abstractions
-
-### 1. Entities
-
-Durable JSONB documents representing *process memory*. Each entity:
-
-* Has a stable identity (`workflowId` / logical key).
-* Evolves via atomic commands.
-* Is versioned implicitly by transactional history.
-* Can be partially indexed for targeted query performance.
-
-> **Design Note:** Treat entity shape as *contractual surface* + *freeform interior*. Index only the minimal surface required for lookups or dashboards.
-
-### 2. Hooks
-
-Re‑entrant, idempotent, interruptible units of work that *maintain* an entity. Hooks can:
-
-* Start, stop, or be re‑invoked without corrupting state.
-* Run concurrently (Postgres ensures isolation on write).
-* Emit signals to let coordinators or sibling hooks know a perspective / phase completed.
-
-### 3. Workflow Coordinators
+## What It Solves
 
-Thin entrypoints that:
+Modernization often stalls where systems meet people and AI.
+HotMesh builds a **durable execution bridge** across those seams — linking your database, APIs, RPA, and AI agents into one recoverable process.
 
-* Seed initial entity state.
-* Fan out perspective / phase hooks.
-* Optionally synthesize or finalize.
-* Return a snapshot (often the final entity state) — *the workflow result is just memory*.
-
-### 4. Commands (Entity Mutation Primitives)
-
-| Command     | Purpose                                   | Example                                          |
-| ----------- | ----------------------------------------- | ------------------------------------------------ |
-| `set`       | Replace full value (first write or reset) | `await e.set({ user: { id: 123, name: "John" } })` |
-| `merge`     | Deep JSON merge                           | `await e.merge({ user: { email: "john@example.com" } })` |
-| `append`    | Append to an array field                  | `await e.append('items', { id: 1, name: "New Item" })` |
-| `prepend`   | Add to start of array field              | `await e.prepend('items', { id: 0, name: "First Item" })` |
-| `remove`    | Remove item from array by index          | `await e.remove('items', 0)` |
-| `increment` | Numeric counters / progress               | `await e.increment('counter', 5)` |
-| `toggle`    | Toggle boolean value                      | `await e.toggle('settings.enabled')` |
-| `setIfNotExists` | Set value only if path doesn't exist | `await e.setIfNotExists('user.id', 123)` |
-| `delete`    | Remove field at specified path           | `await e.delete('user.email')` |
-| `get`       | Read value at path (or full entity)      | `await e.get('user.email')` |
-| `signal`    | Mark hook milestone / unlock waiters      | `await MemFlow.workflow.signal('phase-x', data)` |
+* **AI that can fail safely** — retries, resumable state, and confidence tracking
+* **Human steps that don’t block** — pause for days, resume instantly
+* **Legacy systems that stay connected** — SQL and RPA coexist seamlessly
+* **Full visibility** — query workflows and outcomes directly in SQL
 
 ---
 
-## Table of Contents
+## Core Model
 
-1. [Quick Start](#quick-start)
-2. [Memory Architecture](#memory-architecture)
-3. [Durable AI Agents](#durable-ai-agents)
-4. [Stateful Pipelines](#stateful-pipelines)
-5. [Indexing Strategy](#indexing-strategy)
-6. [Operational Notes](#operational-notes)
-7. [Documentation & Links](#documentation--links)
-
----
+### Entity — the Business Process Record
 
-## Quick Start
+Every workflow writes to a durable JSON document in Postgres called an **Entity**.
+It becomes the shared memory between APIs, RPA jobs, LLM agents, and human operators.
 
-### Install
-
-```bash
-npm install @hotmeshio/hotmesh
-```
-
-### Minimal Setup
 ```ts
-import { MemFlow } from '@hotmeshio/hotmesh';
-import { Client as Postgres } from 'pg';
-
-async function main() {
-  // Auto-provisions required tables/index scaffolding on first run
-  const mf = await MemFlow.init({
-    appId: 'my-app',
-    engine: {
-      connection: {
-        class: Postgres,
-        options: { connectionString: process.env.DATABASE_URL }
-      }
-    }
-  });
-
-  // Start a durable research agent (entity-backed workflow)
-  const handle = await mf.workflow.start({
-    entity: 'research-agent',
-    workflowName: 'researchAgent',
-    workflowId: 'agent-session-jane-001',
-    args: ['Long-term impacts of renewable energy subsidies'],
-    taskQueue: 'agents'
-  });
-
-  console.log('Final Memory Snapshot:', await handle.result());
-}
-
-main().catch(console.error);
+const e = await MemFlow.workflow.entity();
+
+// initialize from a source event
+await e.set({
+  caseId: "A42",
+  stage: "verification",
+  retries: 0,
+  notes: []
+});
+
+// AI step adds structured output
+await e.merge({
+  aiSummary: { result: "Verified coverage", confidence: 0.93 },
+  stage: "approval",
+});
+
+// human operator review
+await e.append("notes", { reviewer: "ops1", comment: "ok to proceed" });
+
+// maintain counters
+await e.increment("retries", 1);
+
+// retrieve current process state
+const data = await e.get();
 ```
 
-### Value Checklist (What You Did *Not* Have To Do)
-- Create tables / migrations
-- Define per-agent caches
-- Implement optimistic locking
-- Build a queue fan‑out mechanism
-- Hand-roll replay protection
+**Minimal surface contract**
 
----
-
-## Memory Architecture
-Each workflow = **1 durable entity**. Hooks are stateless functions *shaped by* that entity's evolving JSON. You can inspect or modify it at any time using ordinary SQL or the provided API.
+| Command       | Purpose                            |
+| ------------- | ---------------------------------- |
+| `set()`       | Initialize workflow state          |
+| `merge()`     | Update any JSON path               |
+| `append()`    | Add entries to lists (logs, notes) |
+| `increment()` | Maintain counters or metrics       |
+| `get()`       | Retrieve current state             |
 
-### Programmatic Indexing
-```ts
-// Create index for premium research agents
-await MemFlow.Entity.createIndex('research-agent', 'isPremium', hotMeshClient);
-
-// Find premium agents needing verification
-const agents = await MemFlow.Entity.find('research-agent', {
-  isPremium: true,
-  needsVerification: true
-}, hotMeshClient);
-```
+Entities are stored in plain SQL tables, directly queryable:
 
-### Direct SQL Access
 ```sql
--- Same index via SQL (more control over index type/conditions)
-CREATE INDEX idx_research_agents_premium ON my_app.jobs (id)
-WHERE entity = 'research-agent' AND (context->>'isPremium')::boolean = true;
-
--- Ad hoc query example
-SELECT id, context->>'status' as status, context->>'confidence' as confidence
+SELECT id, context->>'stage', context->'aiSummary'->>'result'
 FROM my_app.jobs
-WHERE entity = 'research-agent'
-  AND (context->>'isPremium')::boolean = true
-  AND (context->>'confidence')::numeric > 0.8;
+WHERE entity = 'claims-review'
+  AND context->>'stage' != 'complete';
 ```
 
-**Guidelines:**
-1. *Model intent, not mechanics.* Keep ephemeral calculation artifacts minimal; store derived values only if reused.
-2. *Index sparingly.* Each index is a write amplification cost. Start with 1–2 selective partial indexes.
-3. *Keep arrays append‑only where possible.* Supports audit and replay semantics cheaply.
-4. *Choose your tool:* Use Entity methods for standard queries, raw SQL for complex analytics or custom indexes.
-
 ---
 
-## Durable AI Agents
-Agents become simpler: the *agent* is the memory record; hooks supply perspectives, verification, enrichment, or lifecycle progression.
+### Hook — Parallel Work Units
+
+Hooks are stateless functions that operate on the shared Entity.
+Each hook executes independently (API, RPA, or AI), retrying automatically until success.
 
-### Coordinator (Research Agent)
 ```ts
-export async function researchAgent(query: string) {
-  const entity = await MemFlow.workflow.entity();
-
-  const initial = {
-    query,
-    findings: [],
-    perspectives: {},
-    confidence: 0,
-    verification: {},
-    status: 'researching',
-    startTime: new Date().toISOString()
-  };
-  await entity.set<typeof initial>(initial);
-
-  // Fan-out perspectives
-  await MemFlow.workflow.execHook({ taskQueue: 'agents', workflowName: 'optimisticPerspective', args: [query], signalId: 'optimistic-complete' });
-  await MemFlow.workflow.execHook({ taskQueue: 'agents', workflowName: 'skepticalPerspective', args: [query], signalId: 'skeptical-complete' });
-  await MemFlow.workflow.execHook({ taskQueue: 'agents', workflowName: 'verificationHook', args: [query], signalId: 'verification-complete' });
-  await MemFlow.workflow.execHook({ taskQueue: 'agents', workflowName: 'synthesizePerspectives', args: [], signalId: 'synthesis-complete' });
-
-  return await entity.get();
-}
+await MemFlow.workflow.execHook({
+  workflowName: "verifyCoverage",
+  args: ["A42"]
+});
 ```
 
-### Synthesis Hook
+To run independent work in parallel, use a **batch execution** pattern:
+
 ```ts
-export async function synthesizePerspectives({ signal }: { signal: string }) {
-  const e = await MemFlow.workflow.entity();
-  const ctx = await e.get();
-
-  const synthesized = await analyzePerspectives(ctx.perspectives);
-  await e.merge({
-    perspectives: {
-      synthesis: {
-        finalAssessment: synthesized,
-        confidence: calculateConfidence(ctx.perspectives)
-      }
-    },
-    status: 'completed'
-  });
-  await MemFlow.workflow.signal(signal, {});
-}
+// Run independent research perspectives in parallel using batch execution
+await MemFlow.workflow.execHookBatch([
+  {
+    key: 'optimistic',
+    options: {
+      taskQueue: 'agents',
+      workflowName: 'optimisticPerspective',
+      args: [query],
+      signalId: 'optimistic-complete'
+    }
+  },
+  {
+    key: 'skeptical',
+    options: {
+      taskQueue: 'agents',
+      workflowName: 'skepticalPerspective',
+      args: [query],
+      signalId: 'skeptical-complete'
+    }
+  }
+]);
 ```
 
-> **Pattern:** Fan-out hooks that write *adjacent* subtrees (e.g., `perspectives.optimistic`, `perspectives.skeptical`). A final hook merges a compact synthesis object. Avoid cross-hook mutation of the same nested branch.
+Each hook runs in its own recoverable context, allowing AI, API, and RPA agents to operate independently while writing to the same durable Entity.
 
 ---
 
-## Stateful Pipelines
-Pipelines are identical in structure to agents: a coordinator seeds memory; phase hooks advance state; the entity is the audit trail.
+## Example — AI-Assisted Claims Review
 
-### Document Processing Pipeline (Coordinator)
 ```ts
-export async function documentProcessingPipeline() {
-  const pipeline = await MemFlow.workflow.entity();
-
-  const initial = {
-    documentId: `doc-${Date.now()}`,
-    status: 'started',
-    startTime: new Date().toISOString(),
-    imageRefs: [],
-    extractedInfo: [],
-    validationResults: [],
-    finalResult: null,
-    processingSteps: [],
-    errors: [],
-    pageSignals: {}
-  };
-  await pipeline.set<typeof initial>(initial);
-
-  await pipeline.merge({ status: 'loading-images' });
-  await pipeline.append('processingSteps', 'image-load-started');
-  const imageRefs = await activities.loadImagePages();
-  if (!imageRefs?.length) throw new Error('No image references found');
-  await pipeline.merge({ imageRefs });
-  await pipeline.append('processingSteps', 'image-load-completed');
-
-  // Page hooks
-  for (const [i, ref] of imageRefs.entries()) {
-    const page = i + 1;
-    await MemFlow.workflow.execHook({
-      taskQueue: 'pipeline',
-      workflowName: 'pageProcessingHook',
-      args: [ref, page, initial.documentId],
-      signalId: `page-${page}-complete`
-    });
-  }
+export async function claimsWorkflow(caseId: string) {
+  const e = await MemFlow.workflow.entity();
+  await e.set({ caseId, stage: "intake", approved: false });
+
+  // Run verification and summarization in parallel
+  await MemFlow.workflow.execHookBatch([
+    {
+      key: 'verifyCoverage',
+      options: {
+        taskQueue: 'agents',
+        workflowName: 'verifyCoverage',
+        args: [caseId],
+        signalId: 'verify-complete'
+      }
+    },
+    {
+      key: 'generateSummary',
+      options: {
+        taskQueue: 'agents',
+        workflowName: 'generateSummary',
+        args: [caseId],
+        signalId: 'summary-complete'
+      }
+    }
+  ]);
 
-  // Validation
-  await MemFlow.workflow.execHook({ taskQueue: 'pipeline', workflowName: 'validationHook', args: [initial.documentId], signalId: 'validation-complete' });
-  // Approval
-  await MemFlow.workflow.execHook({ taskQueue: 'pipeline', workflowName: 'approvalHook', args: [initial.documentId], signalId: 'approval-complete' });
-  // Notification
-  await MemFlow.workflow.execHook({ taskQueue: 'pipeline', workflowName: 'notificationHook', args: [initial.documentId], signalId: 'processing-complete' });
+  // Wait for human sign-off
+  const approval = await MemFlow.workflow.waitFor("human-approval");
+  await e.merge({ approved: approval === true, stage: "complete" });
 
-  await pipeline.merge({ status: 'completed', completedAt: new Date().toISOString() });
-  await pipeline.append('processingSteps', 'pipeline-completed');
-  return await pipeline.get();
+  return await e.get();
 }
 ```
 
-**Operational Characteristics:**
-- *Replay Friendly*: Each hook can be retried; pipeline memory records invariant progress markers (`processingSteps`).
-- *Parallelizable*: Pages fan out naturally without manual queue wiring.
-- *Auditable*: Entire lifecycle captured in a single evolving JSON record.
+This bridges:
+
+* an existing insurance or EHR system (status + audit trail)
+* LLM agents for data validation and summarization
+* a human reviewer for final sign-off
+
+—all within one recoverable workflow record.
 
 ---
 
-## Documentation & Links
-* **SDK Reference** – https://hotmeshio.github.io/sdk-typescript
-* **Agent Example Tests** – https://github.com/hotmeshio/sdk-typescript/tree/main/tests/memflow/agent
-* **Pipeline Example Tests** – https://github.com/hotmeshio/sdk-typescript/tree/main/tests/memflow/pipeline
-* **Sample Projects** – https://github.com/hotmeshio/samples-typescript
+## Why It Fits Integration Work
+
+HotMesh is purpose-built for **incremental modernization**.
+
+| Need                          | What HotMesh Provides                    |
+| ----------------------------- | ---------------------------------------- |
+| Tie AI into legacy apps       | Durable SQL bridge with full visibility  |
+| Keep human review steps       | Wait-for-signal workflows                |
+| Handle unstable APIs          | Built-in retries and exponential backoff |
+| Trace process across systems  | Unified JSON entity per workflow         |
+| Store long-running AI results | Durable state for agents and automations |
 
 ---
 
 ## License
-Apache 2.0 with commercial restrictions* – see `LICENSE`.
->*NOTE: It's open source with one commercial exception: Build, sell, and share solutions made with HotMesh. But don't white-label the orchestration core and repackage it as your own workflow-as-a-service.
+
+Apache 2.0 — free to build, integrate, and deploy.
+Do not resell the core engine as a hosted service.

package/build/modules/enums.d.ts

@@ -107,3 +107,9 @@ export declare const HMSH_GUID_SIZE: number;
  * Default task queue name used when no task queue is specified
  */
 export declare const DEFAULT_TASK_QUEUE = "default";
+/**
+ * PostgreSQL NOTIFY payload limit. If a job message exceeds this size,
+ * a reference message is sent instead and the subscriber fetches via getState.
+ * PostgreSQL hard limit is 8000 bytes; default 7500 provides safety margin.
+ */
+export declare const HMSH_NOTIFY_PAYLOAD_LIMIT: number;

package/build/modules/enums.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_MEMFLOW_RETRYABLE = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_CHILD = exports.HMSH_CODE_MEMFLOW_ALL = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_MEMFLOW_RETRYABLE = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_CHILD = exports.HMSH_CODE_MEMFLOW_ALL = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -131,3 +131,9 @@ exports.HMSH_GUID_SIZE = Math.min(parseInt(process.env.HMSH_GUID_SIZE, 10) || 22
  * Default task queue name used when no task queue is specified
  */
 exports.DEFAULT_TASK_QUEUE = 'default';
+/**
+ * PostgreSQL NOTIFY payload limit. If a job message exceeds this size,
+ * a reference message is sent instead and the subscriber fetches via getState.
+ * PostgreSQL hard limit is 8000 bytes; default 7500 provides safety margin.
+ */
+exports.HMSH_NOTIFY_PAYLOAD_LIMIT = parseInt(process.env.HMSH_NOTIFY_PAYLOAD_LIMIT, 10) || 7500;

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.5.7",
+    "version": "0.6.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -106,7 +106,7 @@
         "eslint-config-prettier": "^9.1.0",
         "eslint-plugin-import": "^2.29.1",
         "eslint-plugin-prettier": "^5.1.3",
-        "javascript-obfuscator": "^4.1.1",
+        "javascript-obfuscator": "^0.6.2",
         "jest": "^29.5.0",
         "nats": "^2.28.0",
         "openai": "^5.9.0",

package/build/services/engine/index.js

@@ -547,7 +547,12 @@ class EngineService {
      */
     async sub(topic, callback) {
         const subscriptionCallback = async (topic, message) => {
-            callback(message.topic, message.job);
+            let jobOutput = message.job;
+            // If _ref is true, payload was too large - fetch full job data via getState
+            if (message._ref && message.job?.metadata) {
+                jobOutput = await this.getState(message.job.metadata.tpc, message.job.metadata.jid);
+            }
+            callback(message.topic, jobOutput);
         };
         return await this.subscribe.subscribe(key_1.KeyType.QUORUM, subscriptionCallback, this.appId, topic);
     }
@@ -562,7 +567,12 @@ class EngineService {
      */
     async psub(wild, callback) {
         const subscriptionCallback = async (topic, message) => {
-            callback(message.topic, message.job);
+            let jobOutput = message.job;
+            // If _ref is true, payload was too large - fetch full job data via getState
+            if (message._ref && message.job?.metadata) {
+                jobOutput = await this.getState(message.job.metadata.tpc, message.job.metadata.jid);
+            }
+            callback(message.topic, jobOutput);
         };
         return await this.subscribe.psubscribe(key_1.KeyType.QUORUM, subscriptionCallback, this.appId, wild);
     }

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

@@ -0,0 +1,54 @@
+import { ExecHookOptions } from './execHook';
+/**
+ * Configuration for a single hook in a batch execution
+ */
+export interface BatchHookConfig<T = any> {
+    /** Unique key to identify this hook's result in the returned object */
+    key: string;
+    /** Hook execution options */
+    options: ExecHookOptions;
+}
+/**
+ * Executes multiple hooks in parallel and awaits all their signal responses.
+ * This solves the race condition where Promise.all() with execHook() would prevent
+ * all waitFor() registrations from completing.
+ *
+ * The method ensures all waitFor() registrations happen before any hooks execute,
+ * preventing signals from being sent before the framework is ready to receive them.
+ *
+ * @template T - Object type with keys matching the batch hook keys and values as expected response types
+ * @param {BatchHookConfig[]} hookConfigs - Array of hook configurations with unique keys
+ * @returns {Promise<T>} Object with keys from hookConfigs and values as the signal responses
+ *
+ * @example
+ * ```typescript
+ * // Execute multiple research perspectives in parallel
+ * const results = await MemFlow.workflow.execHookBatch<{
+ *   optimistic: OptimisticResult;
+ *   skeptical: SkepticalResult;
+ * }>([
+ *   {
+ *     key: 'optimistic',
+ *     options: {
+ *       taskQueue: 'agents',
+ *       workflowName: 'optimisticPerspective',
+ *       args: [query],
+ *       signalId: 'optimistic-complete'
+ *     }
+ *   },
+ *   {
+ *     key: 'skeptical',
+ *     options: {
+ *       taskQueue: 'agents',
+ *       workflowName: 'skepticalPerspective',
+ *       args: [query],
+ *       signalId: 'skeptical-complete'
+ *     }
+ *   }
+ * ]);
+ *
+ * // results.optimistic contains the OptimisticResult
+ * // results.skeptical contains the SkepticalResult
+ * ```
+ */
+export declare function execHookBatch<T extends Record<string, any>>(hookConfigs: BatchHookConfig[]): Promise<T>;

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

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execHookBatch = void 0;
+const hook_1 = require("./hook");
+const waitFor_1 = require("./waitFor");
+/**
+ * Executes multiple hooks in parallel and awaits all their signal responses.
+ * This solves the race condition where Promise.all() with execHook() would prevent
+ * all waitFor() registrations from completing.
+ *
+ * The method ensures all waitFor() registrations happen before any hooks execute,
+ * preventing signals from being sent before the framework is ready to receive them.
+ *
+ * @template T - Object type with keys matching the batch hook keys and values as expected response types
+ * @param {BatchHookConfig[]} hookConfigs - Array of hook configurations with unique keys
+ * @returns {Promise<T>} Object with keys from hookConfigs and values as the signal responses
+ *
+ * @example
+ * ```typescript
+ * // Execute multiple research perspectives in parallel
+ * const results = await MemFlow.workflow.execHookBatch<{
+ *   optimistic: OptimisticResult;
+ *   skeptical: SkepticalResult;
+ * }>([
+ *   {
+ *     key: 'optimistic',
+ *     options: {
+ *       taskQueue: 'agents',
+ *       workflowName: 'optimisticPerspective',
+ *       args: [query],
+ *       signalId: 'optimistic-complete'
+ *     }
+ *   },
+ *   {
+ *     key: 'skeptical',
+ *     options: {
+ *       taskQueue: 'agents',
+ *       workflowName: 'skepticalPerspective',
+ *       args: [query],
+ *       signalId: 'skeptical-complete'
+ *     }
+ *   }
+ * ]);
+ *
+ * // results.optimistic contains the OptimisticResult
+ * // results.skeptical contains the SkepticalResult
+ * ```
+ */
+async function execHookBatch(hookConfigs) {
+    // Generate signal IDs for hooks that don't have them
+    const processedConfigs = hookConfigs.map(config => ({
+        ...config,
+        options: {
+            ...config.options,
+            signalId: config.options.signalId || `memflow-hook-${crypto.randomUUID()}`
+        }
+    }));
+    // STEP 1: Fire off all hooks (but don't await them)
+    // This registers the hooks/streams with the system immediately
+    await Promise.all(processedConfigs.map(config => {
+        const hookOptions = {
+            ...config.options,
+            args: [...config.options.args, {
+                    signal: config.options.signalId,
+                    $memflow: true
+                }]
+        };
+        return (0, hook_1.hook)(hookOptions);
+    }));
+    // STEP 2: Await all waitFor operations 
+    // This ensures all waitFor registrations happen in the same call stack
+    // before any MemFlowWaitForError is thrown (via setImmediate mechanism)
+    const results = await Promise.all(processedConfigs.map(config => (0, waitFor_1.waitFor)(config.options.signalId)));
+    // STEP 3: Return results as a keyed object
+    return Object.fromEntries(processedConfigs.map((config, i) => [config.key, results[i]]));
+}
+exports.execHookBatch = execHookBatch;

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

@@ -6,6 +6,7 @@ import { enrich } from './enrich';
 import { emit } from './emit';
 import { execChild, startChild } from './execChild';
 import { execHook } from './execHook';
+import { execHookBatch } from './execHookBatch';
 import { proxyActivities } from './proxyActivities';
 import { search } from './searchMethods';
 import { random } from './random';
@@ -53,6 +54,7 @@ export declare class WorkflowService {
     static executeChild: typeof execChild;
     static startChild: typeof startChild;
     static execHook: typeof execHook;
+    static execHookBatch: typeof execHookBatch;
     static proxyActivities: typeof proxyActivities;
     static search: typeof search;
     static entity: typeof entity;

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

@@ -9,6 +9,7 @@ const enrich_1 = require("./enrich");
 const emit_1 = require("./emit");
 const execChild_1 = require("./execChild");
 const execHook_1 = require("./execHook");
+const execHookBatch_1 = require("./execHookBatch");
 const proxyActivities_1 = require("./proxyActivities");
 const searchMethods_1 = require("./searchMethods");
 const random_1 = require("./random");
@@ -71,6 +72,7 @@ WorkflowService.execChild = execChild_1.execChild;
 WorkflowService.executeChild = execChild_1.executeChild;
 WorkflowService.startChild = execChild_1.startChild;
 WorkflowService.execHook = execHook_1.execHook;
+WorkflowService.execHookBatch = execHookBatch_1.execHookBatch;
 WorkflowService.proxyActivities = proxyActivities_1.proxyActivities;
 WorkflowService.search = searchMethods_1.search;
 WorkflowService.entity = entityMethods_1.entity;

package/build/services/quorum/index.js

@@ -88,7 +88,24 @@ class QuorumService {
                 self.engine.processWebHooks();
             }
             else if (message.type === 'job') {
-                self.engine.routeToSubscribers(message.topic, message.job);
+                let jobOutput = message.job;
+                // If _ref is true, payload was too large - fetch full job data via getState
+                if (message._ref && message.job?.metadata) {
+                    try {
+                        jobOutput = await self.engine.getState(message.job.metadata.tpc, message.job.metadata.jid);
+                        self.logger.debug('quorum-job-ref-resolved', {
+                            jid: message.job.metadata.jid,
+                        });
+                    }
+                    catch (err) {
+                        self.logger.error('quorum-job-ref-error', {
+                            jid: message.job.metadata.jid,
+                            error: err,
+                        });
+                        return; // Can't route without job data
+                    }
+                }
+                self.engine.routeToSubscribers(message.topic, jobOutput);
             }
             else if (message.type === 'cron') {
                 self.engine.processTimeHooks();

package/build/services/store/providers/postgres/kvtables.js

@@ -267,9 +267,32 @@ const KVTables = (context) => ({
                 field TEXT NOT NULL,
                 value TEXT,
                 type ${schemaName}.type_enum NOT NULL,
+                created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+                updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 PRIMARY KEY (job_id, field),
                 FOREIGN KEY (job_id) REFERENCES ${fullTableName} (id) ON DELETE CASCADE
               ) PARTITION BY HASH (job_id);
+            `);
+                        // Create trigger function for updating updated_at only for mutable types
+                        await client.query(`
+              CREATE OR REPLACE FUNCTION ${schemaName}.update_attributes_updated_at()
+              RETURNS TRIGGER AS $$
+              BEGIN
+                  IF NEW.type IN ('udata', 'jdata', 'hmark', 'jmark') AND 
+                     (OLD.value IS NULL OR NEW.value <> OLD.value) THEN
+                      NEW.updated_at = NOW();
+                  END IF;
+                  RETURN NEW;
+              END;
+              $$ LANGUAGE plpgsql;
+            `);
+                        // Create trigger for updated_at updates
+                        await client.query(`
+              DROP TRIGGER IF EXISTS trg_update_attributes_updated_at ON ${attributesTableName};
+              CREATE TRIGGER trg_update_attributes_updated_at
+                  BEFORE UPDATE ON ${attributesTableName}
+                  FOR EACH ROW
+                  EXECUTE FUNCTION ${schemaName}.update_attributes_updated_at();
             `);
                         // Create partitions for attributes table
                         await client.query(`

package/build/services/store/providers/postgres/postgres.js

@@ -33,6 +33,7 @@ const cache_1 = require("../../cache");
 const __1 = require("../..");
 const kvsql_1 = require("./kvsql");
 const kvtables_1 = require("./kvtables");
+const time_notify_1 = require("./time-notify");
 class PostgresStoreService extends __1.StoreService {
     transact() {
         return this.storeClient.transact();
@@ -1039,11 +1040,8 @@ class PostgresStoreService extends __1.StoreService {
         const schemaName = this.kvsql().safeName(appId);
         const client = this.pgClient;
         try {
-            // Read the SQL template and replace schema placeholder
-            const fs = await Promise.resolve().then(() => __importStar(require('fs')));
-            const path = await Promise.resolve().then(() => __importStar(require('path')));
-            const sqlTemplate = fs.readFileSync(path.join(__dirname, 'time-notify.sql'), 'utf8');
-            const sql = sqlTemplate.replace(/{schema}/g, schemaName);
+            // Get the SQL with schema placeholder replaced
+            const sql = (0, time_notify_1.getTimeNotifySql)(schemaName);
             // Execute the entire SQL as one statement (functions contain $$ blocks with semicolons)
             await client.query(sql);
             this.logger.info('postgres-time-notifications-deployed', {

package/build/services/store/providers/postgres/time-notify.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Time-aware notification system for PostgreSQL
+ * This system minimizes polling by using LISTEN/NOTIFY for time-based task awakening
+ *
+ * Exported as a function that returns the SQL with schema placeholder replaced.
+ */
+export declare function getTimeNotifySql(schema: string): string;

package/build/services/store/providers/postgres/time-notify.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTimeNotifySql = void 0;
+/**
+ * Time-aware notification system for PostgreSQL
+ * This system minimizes polling by using LISTEN/NOTIFY for time-based task awakening
+ *
+ * Exported as a function that returns the SQL with schema placeholder replaced.
+ */
+function getTimeNotifySql(schema) {
+    return `
+-- Time-aware notification system for PostgreSQL
+-- This system minimizes polling by using LISTEN/NOTIFY for time-based task awakening
+
+-- Function to calculate the next awakening time from the sorted set
+CREATE OR REPLACE FUNCTION ${schema}.get_next_awakening_time(app_key TEXT)
+RETURNS TIMESTAMP WITH TIME ZONE AS $$
+DECLARE
+    next_score DOUBLE PRECISION;
+    next_time TIMESTAMP WITH TIME ZONE;
+BEGIN
+    -- Get the earliest (lowest score) entry from the time range ZSET
+    SELECT score INTO next_score
+    FROM ${schema}.task_schedules
+    WHERE key = app_key
+    AND (expiry IS NULL OR expiry > NOW())
+    ORDER BY score ASC
+    LIMIT 1;
+    
+    IF next_score IS NULL THEN
+        RETURN NULL;
+    END IF;
+    
+    -- Convert epoch milliseconds to timestamp
+    next_time := to_timestamp(next_score / 1000.0);
+    
+    -- Only return if it's in the future
+    IF next_time > NOW() THEN
+        RETURN next_time;
+    END IF;
+    
+    RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to schedule a notification for the next awakening time
+CREATE OR REPLACE FUNCTION ${schema}.schedule_time_notification(
+    app_id TEXT,
+    new_awakening_time TIMESTAMP WITH TIME ZONE DEFAULT NULL
+)
+RETURNS VOID AS $$
+DECLARE
+    channel_name TEXT;
+    current_next_time TIMESTAMP WITH TIME ZONE;
+    app_key TEXT;
+BEGIN
+    -- Build the time range key for this app
+    app_key := app_id || ':time_range';
+    channel_name := 'time_hooks_' || app_id;
+    
+    -- Get the current next awakening time
+    current_next_time := ${schema}.get_next_awakening_time(app_key);
+    
+    -- If we have a specific new awakening time, check if it's earlier
+    IF new_awakening_time IS NOT NULL THEN
+        IF current_next_time IS NULL OR new_awakening_time < current_next_time THEN
+            current_next_time := new_awakening_time;
+        END IF;
+    END IF;
+    
+    -- If there's a next awakening time, schedule immediate notification
+    -- The application will handle the timing logic
+    IF current_next_time IS NOT NULL THEN
+        PERFORM pg_notify(channel_name, json_build_object(
+            'type', 'time_schedule_updated',
+            'app_id', app_id,
+            'next_awakening', extract(epoch from current_next_time) * 1000,
+            'updated_at', extract(epoch from NOW()) * 1000
+        )::text);
+    END IF;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to notify when time hooks are ready
+CREATE OR REPLACE FUNCTION ${schema}.notify_time_hooks_ready(app_id TEXT)
+RETURNS VOID AS $$
+DECLARE
+    channel_name TEXT;
+BEGIN
+    channel_name := 'time_hooks_' || app_id;
+    
+    PERFORM pg_notify(channel_name, json_build_object(
+        'type', 'time_hooks_ready',
+        'app_id', app_id,
+        'ready_at', extract(epoch from NOW()) * 1000
+    )::text);
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger function for when time hooks are added/updated
+CREATE OR REPLACE FUNCTION ${schema}.on_time_hook_change()
+RETURNS TRIGGER AS $$
+DECLARE
+    app_id_extracted TEXT;
+    awakening_time TIMESTAMP WITH TIME ZONE;
+BEGIN
+    -- Extract app_id from the key (assumes format: app_id:time_range)
+    app_id_extracted := split_part(NEW.key, ':time_range', 1);
+    
+    -- Convert the score (epoch milliseconds) to timestamp
+    awakening_time := to_timestamp(NEW.score / 1000.0);
+    
+    -- Schedule notification for this new awakening time
+    PERFORM ${schema}.schedule_time_notification(app_id_extracted, awakening_time);
+    
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger function for when time hooks are removed
+CREATE OR REPLACE FUNCTION ${schema}.on_time_hook_remove()
+RETURNS TRIGGER AS $$
+DECLARE
+    app_id_extracted TEXT;
+BEGIN
+    -- Extract app_id from the key
+    app_id_extracted := split_part(OLD.key, ':time_range', 1);
+    
+    -- Recalculate and notify about the schedule update
+    PERFORM ${schema}.schedule_time_notification(app_id_extracted);
+    
+    RETURN OLD;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create triggers on the sorted_set table for time hooks
+-- Note: These will be created per app schema
+-- Drop existing triggers first to avoid conflicts
+DROP TRIGGER IF EXISTS trg_time_hook_insert ON ${schema}.task_schedules;
+DROP TRIGGER IF EXISTS trg_time_hook_update ON ${schema}.task_schedules;
+DROP TRIGGER IF EXISTS trg_time_hook_delete ON ${schema}.task_schedules;
+
+-- Create new triggers
+CREATE TRIGGER trg_time_hook_insert
+    AFTER INSERT ON ${schema}.task_schedules
+    FOR EACH ROW
+    WHEN (NEW.key LIKE '%:time_range')
+    EXECUTE FUNCTION ${schema}.on_time_hook_change();
+
+CREATE TRIGGER trg_time_hook_update
+    AFTER UPDATE ON ${schema}.task_schedules
+    FOR EACH ROW
+    WHEN (NEW.key LIKE '%:time_range')
+    EXECUTE FUNCTION ${schema}.on_time_hook_change();
+
+CREATE TRIGGER trg_time_hook_delete
+    AFTER DELETE ON ${schema}.task_schedules
+    FOR EACH ROW
+    WHEN (OLD.key LIKE '%:time_range')
+    EXECUTE FUNCTION ${schema}.on_time_hook_remove();
+`;
+}
+exports.getTimeNotifySql = getTimeNotifySql;

package/build/services/stream/providers/postgres/kvtables.js

@@ -1,25 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNotificationChannelName = exports.deploySchema = void 0;
+const enums_1 = require("../../../../modules/enums");
+const utils_1 = require("../../../../modules/utils");
 async function deploySchema(streamClient, appId, logger) {
-    const client = 'connect' in streamClient && 'release' in streamClient
-        ? await streamClient.connect()
-        : streamClient;
-    const releaseClient = 'release' in streamClient;
+    const isPool = streamClient?.totalCount !== undefined &&
+        streamClient?.idleCount !== undefined;
+    const client = isPool ? await streamClient.connect() : streamClient;
+    const releaseClient = isPool;
     try {
+        const schemaName = appId.replace(/[^a-zA-Z0-9_]/g, '_');
+        const tableName = `${schemaName}.streams`;
+        // First, check if tables already exist (no lock needed)
+        const tablesExist = await checkIfTablesExist(client, schemaName, tableName);
+        if (tablesExist) {
+            // Tables already exist, no need to acquire lock or create tables
+            return;
+        }
+        // Tables don't exist, need to acquire lock and create them
         const lockId = getAdvisoryLockId(appId);
         const lockResult = await client.query('SELECT pg_try_advisory_lock($1) AS locked', [lockId]);
         if (lockResult.rows[0].locked) {
-            await client.query('BEGIN');
-            const schemaName = appId.replace(/[^a-zA-Z0-9_]/g, '_');
-            const tableName = `${schemaName}.streams`;
-            await createTables(client, schemaName, tableName);
-            await createNotificationTriggers(client, schemaName, tableName);
-            await client.query('COMMIT');
-            await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
+            try {
+                await client.query('BEGIN');
+                // Double-check tables don't exist (race condition safety)
+                const tablesStillMissing = !(await checkIfTablesExist(client, schemaName, tableName));
+                if (tablesStillMissing) {
+                    await createTables(client, schemaName, tableName);
+                    await createNotificationTriggers(client, schemaName, tableName);
+                }
+                await client.query('COMMIT');
+            }
+            finally {
+                await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
+            }
         }
         else {
-            throw new Error('Table deployment in progress by another process.');
+            // Release the client before waiting (if it's a pool connection)
+            if (releaseClient && client.release) {
+                await client.release();
+            }
+            // Wait for the deploy process to complete
+            await waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger);
+            return; // Already released client, don't release again in finally
         }
     }
     catch (error) {
@@ -27,8 +50,13 @@ async function deploySchema(streamClient, appId, logger) {
         throw error;
     }
     finally {
-        if (releaseClient) {
-            await client.release();
+        if (releaseClient && client.release) {
+            try {
+                await client.release();
+            }
+            catch {
+                // Client may have been released already
+            }
         }
     }
 }
@@ -44,6 +72,45 @@ function hashStringToInt(str) {
     }
     return Math.abs(hash);
 }
+async function checkIfTablesExist(client, schemaName, tableName) {
+    const result = await client.query(`SELECT to_regclass('${tableName}') AS t`);
+    return result.rows[0].t !== null;
+}
+async function waitForTablesCreation(streamClient, lockId, schemaName, tableName, logger) {
+    let retries = 0;
+    const maxRetries = Math.round(enums_1.HMSH_DEPLOYMENT_DELAY / enums_1.HMSH_DEPLOYMENT_PAUSE);
+    while (retries < maxRetries) {
+        await (0, utils_1.sleepFor)(enums_1.HMSH_DEPLOYMENT_PAUSE);
+        const isPool = streamClient?.totalCount !== undefined &&
+            streamClient?.idleCount !== undefined;
+        const client = isPool ? await streamClient.connect() : streamClient;
+        try {
+            // Check if tables exist directly (most efficient check)
+            const tablesExist = await checkIfTablesExist(client, schemaName, tableName);
+            if (tablesExist) {
+                // Tables now exist, deployment is complete
+                return;
+            }
+            // Fallback: check if the lock has been released (indicates completion)
+            const lockCheck = await client.query("SELECT NOT EXISTS (SELECT 1 FROM pg_locks WHERE locktype = 'advisory' AND objid = $1::bigint) AS unlocked", [lockId]);
+            if (lockCheck.rows[0].unlocked) {
+                // Lock has been released, tables should exist now
+                const tablesExistAfterLock = await checkIfTablesExist(client, schemaName, tableName);
+                if (tablesExistAfterLock) {
+                    return;
+                }
+            }
+        }
+        finally {
+            if (isPool && client.release) {
+                await client.release();
+            }
+        }
+        retries++;
+    }
+    logger.error('stream-table-create-timeout', { schemaName, tableName });
+    throw new Error('Timeout waiting for stream table creation');
+}
 async function createTables(client, schemaName, tableName) {
     await client.query(`CREATE SCHEMA IF NOT EXISTS ${schemaName};`);
     // Main table creation with partitions

package/build/services/sub/providers/postgres/postgres.d.ts

@@ -8,6 +8,7 @@ declare class PostgresSubService extends SubService<PostgresClientType & Provide
     private static clientSubscriptions;
     private static clientHandlers;
     private instanceSubscriptions;
+    private instanceId;
     constructor(eventClient: PostgresClientType & ProviderClient, storeClient?: PostgresClientType & ProviderClient);
     init(namespace: string, appId: string, engineId: string, logger: ILogger): Promise<void>;
     private setupNotificationHandler;

package/build/services/sub/providers/postgres/postgres.js

@@ -5,13 +5,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresSubService = void 0;
 const crypto_1 = __importDefault(require("crypto"));
+const enums_1 = require("../../../../modules/enums");
 const key_1 = require("../../../../modules/key");
 const index_1 = require("../../index");
 class PostgresSubService extends index_1.SubService {
     constructor(eventClient, storeClient) {
         super(eventClient, storeClient);
         // Instance-level subscriptions for cleanup
-        this.instanceSubscriptions = new Set();
+        this.instanceSubscriptions = new Map(); // topic -> callbackKey mapping
+        this.instanceId = crypto_1.default.randomUUID();
     }
     async init(namespace = key_1.HMNS, appId, engineId, logger) {
         this.namespace = namespace;
@@ -36,8 +38,10 @@ class PostgresSubService extends index_1.SubService {
             if (callbacks && callbacks.size > 0) {
                 try {
                     const payload = JSON.parse(msg.payload || '{}');
-                    // Call all callbacks registered for this channel across all SubService instances
-                    callbacks.forEach((callback) => {
+                    // Collect callbacks first to avoid modification during iteration
+                    const callbackArray = Array.from(callbacks.entries());
+                    // Call all callbacks
+                    callbackArray.forEach(([callbackKey, callback], index) => {
                         try {
                             callback(msg.channel, payload);
                         }
@@ -97,13 +101,16 @@ class PostgresSubService extends index_1.SubService {
             // Start listening to the safe topic (only once per channel across all instances)
             await this.eventClient.query(`LISTEN "${safeKey}"`);
         }
-        // Add this callback to the list
-        callbacks.set(this, callback);
+        // Generate unique callback key to avoid overwrites
+        const callbackKey = `${this.instanceId}-${Date.now()}-${Math.random()}`;
+        // Add this callback to the list with unique key
+        callbacks.set(callbackKey, callback);
         // Track this subscription for cleanup
-        this.instanceSubscriptions.add(safeKey);
+        this.instanceSubscriptions.set(safeKey, callbackKey);
         this.logger.debug(`postgres-subscribe`, {
             originalKey,
             safeKey,
+            callbackKey,
             totalCallbacks: callbacks.size,
         });
     }
@@ -117,11 +124,12 @@ class PostgresSubService extends index_1.SubService {
             return;
         }
         const callbacks = clientSubscriptions.get(safeKey);
-        if (!callbacks || callbacks.size === 0) {
+        const callbackKey = this.instanceSubscriptions.get(safeKey);
+        if (!callbacks || callbacks.size === 0 || !callbackKey) {
             return;
         }
-        // Remove callback from this specific instance
-        callbacks.delete(this);
+        // Remove callback using the tracked unique key
+        callbacks.delete(callbackKey);
         // Remove from instance tracking
         this.instanceSubscriptions.delete(safeKey);
         // Stop listening to the safe topic if no more callbacks exist
@@ -132,6 +140,7 @@ class PostgresSubService extends index_1.SubService {
         this.logger.debug(`postgres-unsubscribe`, {
             originalKey,
             safeKey,
+            callbackKey,
             remainingCallbacks: callbacks.size,
         });
     }
@@ -144,10 +153,10 @@ class PostgresSubService extends index_1.SubService {
         if (!clientSubscriptions) {
             return;
         }
-        for (const safeKey of this.instanceSubscriptions) {
+        for (const [safeKey, callbackKey] of this.instanceSubscriptions) {
             const callbacks = clientSubscriptions.get(safeKey);
             if (callbacks) {
-                callbacks.delete(this);
+                callbacks.delete(callbackKey);
                 // If no more callbacks exist for this channel, stop listening
                 if (callbacks.size === 0) {
                     clientSubscriptions.delete(safeKey);
@@ -172,8 +181,34 @@ class PostgresSubService extends index_1.SubService {
             appId,
             engineId: topic,
         });
+        let messageToPublish = message;
+        let payload = JSON.stringify(message);
+        // PostgreSQL NOTIFY has a payload limit. If job message exceeds limit,
+        // send a reference message instead - subscriber will fetch via getState.
+        if (payload.length > enums_1.HMSH_NOTIFY_PAYLOAD_LIMIT &&
+            message.type === 'job' &&
+            message.job?.metadata) {
+            const { jid, tpc, app, js } = message.job.metadata;
+            messageToPublish = {
+                type: 'job',
+                topic: message.topic,
+                job: {
+                    metadata: { jid, tpc, app, js },
+                    data: null,
+                },
+                _ref: true,
+            };
+            payload = JSON.stringify(messageToPublish);
+            this.logger.debug('postgres-publish-ref', {
+                originalKey,
+                safeKey,
+                originalSize: JSON.stringify(message).length,
+                refSize: payload.length,
+                jid,
+            });
+        }
         // Publish the message using the safe topic
-        const payload = JSON.stringify(message).replace(/'/g, "''");
+        payload = payload.replace(/'/g, "''");
         await this.storeClient.query(`NOTIFY "${safeKey}", '${payload}'`);
         this.logger.debug(`postgres-publish`, { originalKey, safeKey });
         return true;

package/build/types/quorum.d.ts

@@ -94,6 +94,8 @@ export interface JobMessage extends QuorumMessageBase {
     entity?: string;
     topic: string;
     job: JobOutput;
+    /** if true, job.data is null due to payload size - subscriber should fetch via getState */
+    _ref?: boolean;
 }
 export interface ThrottleMessage extends QuorumMessageBase {
     type: 'throttle';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -106,7 +106,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-prettier": "^5.1.3",
-    "javascript-obfuscator": "^4.1.1",
+    "javascript-obfuscator": "^0.6.2",
     "jest": "^29.5.0",
     "nats": "^2.28.0",
     "openai": "^5.9.0",