@hotmeshio/hotmesh 0.20.1 → 0.21.1

package/README.md

@@ -14,6 +14,7 @@ npm install @hotmeshio/hotmesh
 - **Crash-safe execution** — Every step is a committed row. If the process dies, it picks up where it left off.
 - **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.
+- **Human-in-the-loop queues** — Suspend workflows until an operator claims and resolves the task. Pending suspensions become discoverable, claimable rows in Postgres. Concurrent workers receive exact reason codes (`conflict`, `already-resolved`, `signal-failed`) instead of opaque nulls.
 
 ## How it works in 30 seconds
 
@@ -166,10 +167,37 @@ const result = await Durable.workflow.executeChild({
 **Signals** — pause a workflow until an external event arrives.
 
 ```typescript
+// Basic: pause until any caller sends the matching signal
 const approval = await Durable.workflow.condition<{ approved: boolean }>('manager-approval');
 if (!approval.approved) return 'rejected';
 ```
 
+Pass a `ConditionQueueConfig` as the second argument to also create a claimable task record in Postgres (see [Signal queue](#signal-queue-postgres-only) below):
+
+```typescript
+// With queue config: atomically suspend the workflow AND enqueue a claimable task record
+const approval = await Durable.workflow.condition<{ approved: boolean }>('manager-approval', {
+  role: 'manager',
+  description: `Approve order ${orderId}`,
+  metadata: { orderId, region: 'us-west' }, // GIN-indexed; used for claimByMetadata queries
+  envelope: { formSchema: [...] },           // unindexed display context; safe for large blobs
+});
+// approval is false if a timeout was set and no signal arrived
+if (approval === false) return 'timed-out';
+if (!approval.approved) return 'rejected';
+```
+
+The optional first string argument is a timeout; the queue config can appear as the second or third argument:
+
+```typescript
+// With timeout AND queue config
+const approval = await Durable.workflow.condition<{ approved: boolean }>(
+  'manager-approval',
+  '72 hours',                  // workflow times out if nobody acts
+  { role: 'manager', metadata: { orderId } },
+);
+```
+
 ## Retries and error handling
 
 Activities retry automatically on failure. Configure the policy per activity or per worker:
@@ -243,6 +271,112 @@ const exported = await handle.export({          // selective export
 });
 ```
 
+## Signal queue (Postgres only)
+
+When `condition()` is called with a `ConditionQueueConfig`, HotMesh atomically writes a row to `hotmesh_signals` inside the same Postgres transaction that suspends the workflow. The result is a durable, queryable task queue backed by the same database — no separate service, no double-write, no gap between "task created" and "workflow suspended".
+
+**Workflow side** — declare what kind of task this suspension represents:
+
+```typescript
+// workflows/approval.ts
+export async function orderApproval(orderId: string) {
+  const signalId = `approve-${orderId}`;
+
+  const result = await Durable.workflow.condition<{ approved: boolean; notes: string }>(
+    signalId,
+    {
+      role: 'pharmacist',
+      type: 'approval',
+      priority: 3,
+      description: `Review order ${orderId}`,
+      taskQueue: 'rx-approvals',
+      workflowType: 'orderApproval',
+      metadata: { orderId },               // GIN-indexed; query with claimByMetadata
+      envelope: {                          // not indexed; pass form schemas, display context
+        formSchema: [{ name: 'notes', type: 'textarea', required: true }],
+      },
+    },
+  );
+
+  if (result === false) return { status: 'timed-out' };
+  return result;
+}
+```
+
+**Resolver side** — claim and resolve from any process (API handler, worker, dashboard):
+
+```typescript
+// resolver.ts
+import { Durable } from '@hotmeshio/hotmesh';
+
+const client = new Durable.Client({ connection });
+
+// List all pending tasks for a role
+const pending = await client.signalQueue.list({ role: 'pharmacist', status: 'pending' });
+
+// Claim by metadata — atomic; concurrent workers get 'conflict', not a silent null
+const claim = await client.signalQueue.claimByMetadata({
+  key: 'orderId',
+  value: orderId,
+  assignee: 'jane@example.com',
+  durationMinutes: 30,
+});
+
+if (!claim.ok) {
+  // claim.reason: 'not-found' (nothing queued) | 'conflict' (another worker beat you)
+  return;
+}
+
+// Resolve — marks the DB record resolved AND delivers the signal to the paused workflow
+const resolution = await client.signalQueue.resolve({
+  id: claim.entry.id,
+  resolverPayload: { approved: true, notes: 'LGTM' },
+});
+
+if (!resolution.ok) {
+  if (resolution.reason === 'signal-failed') {
+    // DB updated but workflow signal not delivered — retry with resolution.signalKey
+  }
+}
+```
+
+**All `signalQueue` methods:**
+
+| Method | Description |
+|---|---|
+| `list(params)` | List signals filtered by `role`, `status`, `taskQueue` |
+| `get(id)` | Fetch a single signal record by UUID |
+| `claim({ id, assignee?, durationMinutes? })` | Claim by record ID |
+| `claimByMetadata({ key, value, assignee?, durationMinutes? })` | Claim by GIN-indexed metadata field |
+| `release({ id })` | Return a claimed signal to `pending` |
+| `releaseExpired()` | Sweep all past-expiry claims back to `pending` |
+| `resolve({ id, resolverPayload? })` | Resolve by ID and deliver signal to the workflow |
+| `resolveByMetadata({ key, value, resolverPayload? })` | Resolve by metadata field and deliver signal |
+
+**Result types** — all mutating methods return a discriminated union so callers can handle every outcome without guessing what `null` meant:
+
+```typescript
+// Claim
+type ClaimSignalResult =
+  | { ok: true; entry: SignalQueueEntry }
+  | { ok: false; reason: 'not-found' | 'conflict' };
+
+// Release
+type ReleaseSignalResult =
+  | { ok: true }
+  | { ok: false; reason: 'not-found' | 'wrong-status' };
+
+// Resolve
+type ResolveSignalResult =
+  | { ok: true }
+  | { ok: false; reason: 'not-found' | 'already-resolved' }
+  | { ok: false; reason: 'signal-failed'; signalKey: string };
+```
+
+`signal-failed` means the database record was updated but `workflow.signal()` threw (network blip, workflow already complete). The `signalKey` is returned so callers can retry signal delivery independently without re-resolving the record.
+
+> **Postgres only.** The `signalQueue.*` methods require the Postgres provider. Workflows using `condition()` without a queue config are unaffected on any provider.
+
 ## Observability
 
 There is no proprietary dashboard. Workflow state lives in Postgres, so use whatever tools you already have:

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.20.1",
+    "version": "0.21.1",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

package/build/services/durable/client.d.ts

@@ -82,6 +82,73 @@ export declare class ClientService {
      * is accessed by calling workflow.start().
      */
     workflow: ClientWorkflow;
+    /**
+     * Signal queue API for managing paused-workflow task records.
+     * Operations: list, get, claim, claimByMetadata, release, resolve,
+     * resolveByMetadata, releaseExpired.
+     *
+     * Requires a Postgres store provider. Methods are no-ops (return null/false)
+     * when called against a non-Postgres store.
+     *
+     * @example
+     * ```typescript
+     * // Claim a pending task by metadata key
+     * const task = await client.signalQueue.claimByMetadata({
+     *   key: 'orderId', value: 'RX-123',
+     *   assignee: 'pharmacist-jane',
+     *   durationMinutes: 30,
+     * });
+     *
+     * if (task) {
+     *   await client.signalQueue.resolve({
+     *     id: task.id,
+     *     resolverPayload: { approved: true },
+     *   });
+     *   // → paused workflow resumes with { approved: true }
+     * }
+     * ```
+     */
+    signalQueue: {
+        list: (params?: {
+            namespace?: string;
+            taskQueue?: string;
+            status?: 'pending' | 'claimed' | 'resolved' | 'expired' | 'released';
+            role?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<any>;
+        get: (id: string, namespace?: string) => Promise<any>;
+        getBySignalKey: (signalKey: string, namespace?: string) => Promise<any>;
+        claim: (params: {
+            id: string;
+            namespace?: string;
+            assignee?: string;
+            durationMinutes?: number;
+        }) => Promise<import('../../types/signal').ClaimSignalResult>;
+        claimByMetadata: (params: {
+            key: string;
+            value: unknown;
+            namespace?: string;
+            assignee?: string;
+            durationMinutes?: number;
+        }) => Promise<import('../../types/signal').ClaimSignalResult>;
+        release: (params: {
+            id: string;
+            namespace?: string;
+        }) => Promise<import('../../types/signal').ReleaseSignalResult>;
+        resolve: (params: {
+            id: string;
+            namespace?: string;
+            resolverPayload?: Record<string, unknown>;
+        }) => Promise<import('../../types/signal').ResolveSignalResult>;
+        resolveByMetadata: (params: {
+            key: string;
+            value: unknown;
+            namespace?: string;
+            resolverPayload?: Record<string, unknown>;
+        }) => Promise<import('../../types/signal').ResolveSignalResult>;
+        releaseExpired: (namespace?: string) => Promise<number>;
+    };
     /**
      * Any router can be used to deploy and activate the HotMesh
      * distributed executable to the active quorum EXCEPT for

package/build/services/durable/client.js

@@ -284,6 +284,165 @@ class ClientService {
                 }
             },
         };
+        /**
+         * Signal queue API for managing paused-workflow task records.
+         * Operations: list, get, claim, claimByMetadata, release, resolve,
+         * resolveByMetadata, releaseExpired.
+         *
+         * Requires a Postgres store provider. Methods are no-ops (return null/false)
+         * when called against a non-Postgres store.
+         *
+         * @example
+         * ```typescript
+         * // Claim a pending task by metadata key
+         * const task = await client.signalQueue.claimByMetadata({
+         *   key: 'orderId', value: 'RX-123',
+         *   assignee: 'pharmacist-jane',
+         *   durationMinutes: 30,
+         * });
+         *
+         * if (task) {
+         *   await client.signalQueue.resolve({
+         *     id: task.id,
+         *     resolverPayload: { approved: true },
+         *   });
+         *   // → paused workflow resumes with { approved: true }
+         * }
+         * ```
+         */
+        this.signalQueue = {
+            list: async (params = {}) => {
+                const hotMesh = await this.getHotMeshClient(null, params.namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.listSignals !== 'function')
+                    return [];
+                const ns = params.namespace ?? factory_1.APP_ID;
+                return store.listSignals({
+                    namespace: ns,
+                    appId: store.appId,
+                    status: params.status,
+                    role: params.role,
+                    taskQueue: params.taskQueue,
+                    limit: params.limit,
+                    offset: params.offset,
+                });
+            },
+            get: async (id, namespace) => {
+                const hotMesh = await this.getHotMeshClient(null, namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.getSignal !== 'function')
+                    return null;
+                const ns = namespace ?? factory_1.APP_ID;
+                return store.getSignal({ namespace: ns, appId: store.appId, id });
+            },
+            getBySignalKey: async (signalKey, namespace) => {
+                const hotMesh = await this.getHotMeshClient(null, namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.getSignalBySignalKey !== 'function')
+                    return null;
+                const ns = namespace ?? factory_1.APP_ID;
+                return store.getSignalBySignalKey({ namespace: ns, appId: store.appId, signalKey });
+            },
+            claim: async (params) => {
+                const hotMesh = await this.getHotMeshClient(null, params.namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.claimSignal !== 'function') {
+                    return { ok: false, reason: 'not-found' };
+                }
+                const ns = params.namespace ?? factory_1.APP_ID;
+                return store.claimSignal({
+                    namespace: ns,
+                    appId: store.appId,
+                    id: params.id,
+                    assignee: params.assignee,
+                    durationMinutes: params.durationMinutes,
+                });
+            },
+            claimByMetadata: async (params) => {
+                const hotMesh = await this.getHotMeshClient(null, params.namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.claimSignalByMetadata !== 'function') {
+                    return { ok: false, reason: 'not-found' };
+                }
+                const ns = params.namespace ?? factory_1.APP_ID;
+                return store.claimSignalByMetadata({
+                    namespace: ns,
+                    appId: store.appId,
+                    key: params.key,
+                    value: params.value,
+                    assignee: params.assignee,
+                    durationMinutes: params.durationMinutes,
+                });
+            },
+            release: async (params) => {
+                const hotMesh = await this.getHotMeshClient(null, params.namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.releaseSignal !== 'function') {
+                    return { ok: false, reason: 'not-found' };
+                }
+                const ns = params.namespace ?? factory_1.APP_ID;
+                return store.releaseSignal({
+                    namespace: ns,
+                    appId: store.appId,
+                    id: params.id,
+                });
+            },
+            resolve: async (params) => {
+                const hotMesh = await this.getHotMeshClient(null, params.namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.resolveSignal !== 'function') {
+                    return { ok: false, reason: 'not-found' };
+                }
+                const ns = params.namespace ?? factory_1.APP_ID;
+                const storeResult = await store.resolveSignal({
+                    namespace: ns,
+                    appId: store.appId,
+                    id: params.id,
+                    resolverPayload: params.resolverPayload,
+                });
+                if (!storeResult.ok)
+                    return storeResult;
+                try {
+                    await this.workflow.signal(storeResult.signalKey, params.resolverPayload ?? {}, params.namespace);
+                    return { ok: true };
+                }
+                catch {
+                    return { ok: false, reason: 'signal-failed', signalKey: storeResult.signalKey };
+                }
+            },
+            resolveByMetadata: async (params) => {
+                const hotMesh = await this.getHotMeshClient(null, params.namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.resolveSignalByMetadata !== 'function') {
+                    return { ok: false, reason: 'not-found' };
+                }
+                const ns = params.namespace ?? factory_1.APP_ID;
+                const storeResult = await store.resolveSignalByMetadata({
+                    namespace: ns,
+                    appId: store.appId,
+                    key: params.key,
+                    value: params.value,
+                    resolverPayload: params.resolverPayload,
+                });
+                if (!storeResult.ok)
+                    return storeResult;
+                try {
+                    await this.workflow.signal(storeResult.signalKey, params.resolverPayload ?? {}, params.namespace);
+                    return { ok: true };
+                }
+                catch {
+                    return { ok: false, reason: 'signal-failed', signalKey: storeResult.signalKey };
+                }
+            },
+            releaseExpired: async (namespace) => {
+                const hotMesh = await this.getHotMeshClient(null, namespace);
+                const store = hotMesh.engine.store;
+                if (typeof store.releaseExpiredSignals !== 'function')
+                    return 0;
+                const ns = namespace ?? factory_1.APP_ID;
+                return store.releaseExpiredSignals({ namespace: ns, appId: store.appId });
+            },
+        };
         this.connection = config.connection;
     }
     hashOptions() {

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

@@ -318,3 +318,5 @@ declare class DurableClass {
 }
 export { DurableClass as Durable };
 export type { ContextType };
+export type { ConditionQueueConfig } from './workflow/condition';
+export type { ClaimSignalResult, ReleaseSignalResult, ResolveSignalResult, SignalQueueEntry, } from '../../types/signal';

package/build/services/durable/worker.js

@@ -806,6 +806,31 @@ class WorkerService {
                     const workflowInput = data.data;
                     const execIndex = counter.counter;
                     const { workflowId, workflowDimension, originJobId } = workflowInput;
+                    const payload = interruptionRegistry[0];
+                    //if condition() was called with queueConfig, create a signal queue record
+                    if (payload.queueConfig) {
+                        const store = this.workflowRunner.engine.store;
+                        if (typeof store.enqueueSignal === 'function') {
+                            const ns = config.namespace ?? factory_1.APP_ID;
+                            try {
+                                await store.enqueueSignal({
+                                    namespace: ns,
+                                    appId: store.appId,
+                                    signalKey: payload.signalId,
+                                    workflowId,
+                                    topic: `${ns}.wfs.wait`,
+                                    taskQueue: config.taskQueue ?? payload.queueConfig.taskQueue,
+                                    ...payload.queueConfig,
+                                });
+                            }
+                            catch (enqueueErr) {
+                                this.workflowRunner.engine.logger.warn('signal-queue-enqueue-err', {
+                                    signalId: payload.signalId,
+                                    error: enqueueErr,
+                                });
+                            }
+                        }
+                    }
                     return withPatchMarkers({
                         status: stream_1.StreamStatus.SUCCESS,
                         code: enums_1.HMSH_CODE_DURABLE_WAIT,

package/build/services/durable/workflow/condition.d.ts

@@ -1,3 +1,5 @@
+import type { ConditionQueueConfig } from '../../../types/signal';
+export type { ConditionQueueConfig };
 /**
  * Pauses the workflow until a signal with the given `signalId` is received.
  * The workflow suspends durably — it survives process restarts and will
@@ -61,7 +63,8 @@
  *
  * @template T - The type of data expected in the signal payload.
  * @param {string} signalId - A unique signal identifier shared by the sender and receiver.
- * @param {string} [timeout] - Optional duration (e.g., '30s', '5m', '1h'). Returns `false` on timeout.
+ * @param {string | ConditionQueueConfig} [timeoutOrConfig] - Optional timeout string (e.g. '30s') OR queue config object.
+ * @param {ConditionQueueConfig} [queueConfig] - Optional queue config when timeout is also provided.
  * @returns {Promise<T | false>} The signal data, or `false` if the timeout expired first.
  */
-export declare function condition<T>(signalId: string, timeout?: string): Promise<T | false>;
+export declare function condition<T>(signalId: string, timeoutOrConfig?: string | ConditionQueueConfig, queueConfig?: ConditionQueueConfig): Promise<T | false>;

package/build/services/durable/workflow/condition.js

@@ -67,10 +67,15 @@ const didRun_1 = require("./didRun");
  *
  * @template T - The type of data expected in the signal payload.
  * @param {string} signalId - A unique signal identifier shared by the sender and receiver.
- * @param {string} [timeout] - Optional duration (e.g., '30s', '5m', '1h'). Returns `false` on timeout.
+ * @param {string | ConditionQueueConfig} [timeoutOrConfig] - Optional timeout string (e.g. '30s') OR queue config object.
+ * @param {ConditionQueueConfig} [queueConfig] - Optional queue config when timeout is also provided.
  * @returns {Promise<T | false>} The signal data, or `false` if the timeout expired first.
  */
-async function condition(signalId, timeout) {
+async function condition(signalId, timeoutOrConfig, queueConfig) {
+    const timeout = typeof timeoutOrConfig === 'string' ? timeoutOrConfig : undefined;
+    const resolvedQueueConfig = typeof timeoutOrConfig === 'object' && timeoutOrConfig !== null
+        ? timeoutOrConfig
+        : queueConfig;
     const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('wait');
     (0, cancellationScope_1.checkCancellation)();
     if (didRunAlready) {
@@ -117,6 +122,7 @@ async function condition(signalId, timeout) {
         type: 'DurableWaitForError',
         code: common_1.HMSH_CODE_DURABLE_WAIT,
         ...(timeout ? { duration: (0, common_1.s)(timeout) } : {}),
+        ...(resolvedQueueConfig ? { queueConfig: resolvedQueueConfig } : {}),
     };
     interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();

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

@@ -166,6 +166,65 @@ const KVTables = (context) => ({
         ON ${jobsTable} (key) WHERE is_live;
       `);
         }
+        // v0.21.0: signal queue table for first-class HITL escalation primitives
+        const sigTable = `${schemaName}.hotmesh_signals`;
+        const { rows: sigRows } = await client.query(`SELECT to_regclass('${sigTable}') AS tbl`);
+        if (!sigRows[0].tbl) {
+            await client.query(`
+        CREATE TABLE IF NOT EXISTS ${sigTable} (
+          id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          namespace       TEXT NOT NULL,
+          app_id          TEXT NOT NULL,
+          signal_key      TEXT NOT NULL,
+          workflow_id     TEXT NOT NULL,
+          job_id          TEXT,
+          topic           TEXT,
+          status          TEXT NOT NULL DEFAULT 'pending',
+          role            TEXT,
+          type            TEXT,
+          subtype         TEXT,
+          priority        INT  NOT NULL DEFAULT 5,
+          description     TEXT,
+          task_queue      TEXT,
+          workflow_type   TEXT,
+          assigned_to     TEXT,
+          claimed_at      TIMESTAMPTZ,
+          claim_expires_at TIMESTAMPTZ,
+          resolved_at     TIMESTAMPTZ,
+          resolver_payload JSONB,
+          envelope        JSONB,
+          metadata        JSONB,
+          expires_at      TIMESTAMPTZ,
+          created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          UNIQUE(namespace, app_id, signal_key)
+        );
+      `);
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_hmsig_namespace_status
+          ON ${sigTable}(namespace, app_id, status);
+      `);
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_hmsig_signal_key
+          ON ${sigTable}(namespace, app_id, signal_key);
+      `);
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_hmsig_role_status
+          ON ${sigTable}(namespace, app_id, role, status);
+      `);
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_hmsig_task_queue
+          ON ${sigTable}(namespace, app_id, task_queue, status);
+      `);
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_hmsig_metadata_gin
+          ON ${sigTable} USING GIN(metadata);
+      `);
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_hmsig_claim_expiry
+          ON ${sigTable}(claim_expires_at) WHERE status = 'claimed';
+      `);
+        }
     },
     async createTables(client, appName) {
         try {
@@ -476,6 +535,64 @@ const KVTables = (context) => ({
               ON ${fullTableName} (key, score, member);
             `);
                         break;
+                    case 'signal_queue': {
+                        const tbl = fullTableName;
+                        await client.query(`
+              CREATE TABLE IF NOT EXISTS ${tbl} (
+                id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                namespace       TEXT NOT NULL,
+                app_id          TEXT NOT NULL,
+                signal_key      TEXT NOT NULL,
+                workflow_id     TEXT NOT NULL,
+                job_id          TEXT,
+                topic           TEXT,
+                status          TEXT NOT NULL DEFAULT 'pending',
+                role            TEXT,
+                type            TEXT,
+                subtype         TEXT,
+                priority        INT  NOT NULL DEFAULT 5,
+                description     TEXT,
+                task_queue      TEXT,
+                workflow_type   TEXT,
+                assigned_to     TEXT,
+                claimed_at      TIMESTAMPTZ,
+                claim_expires_at TIMESTAMPTZ,
+                resolved_at     TIMESTAMPTZ,
+                resolver_payload JSONB,
+                envelope        JSONB,
+                metadata        JSONB,
+                expires_at      TIMESTAMPTZ,
+                created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                UNIQUE(namespace, app_id, signal_key)
+              );
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsig_namespace_status
+                ON ${tbl}(namespace, app_id, status);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsig_signal_key
+                ON ${tbl}(namespace, app_id, signal_key);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsig_role_status
+                ON ${tbl}(namespace, app_id, role, status);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsig_task_queue
+                ON ${tbl}(namespace, app_id, task_queue, status);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsig_metadata_gin
+                ON ${tbl} USING GIN(metadata);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsig_claim_expiry
+                ON ${tbl}(claim_expires_at) WHERE status = 'claimed';
+            `);
+                        break;
+                    }
                     default:
                         context.logger.warn(`Unknown table type for ${tableDef.name}`);
                         break;
@@ -593,6 +710,11 @@ const KVTables = (context) => ({
                 name: 'signal_registry',
                 type: 'string',
             },
+            {
+                schema: schemaName,
+                name: 'hotmesh_signals',
+                type: 'signal_queue',
+            },
         ];
         return tableDefinitions;
     },

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

@@ -11,6 +11,7 @@ import { Transitions } from '../../../../types/transition';
 import { JobInterruptOptions } from '../../../../types/job';
 import { WorkListTaskType } from '../../../../types/task';
 import { ThrottleOptions } from '../../../../types/quorum';
+import { SignalQueueEntry } from '../../../../types/signal';
 import { StoreService } from '../..';
 import { PostgresClientType } from '../../../../types';
 import { KVSQL } from './kvsql';
@@ -222,6 +223,194 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
         activity?: string;
         types?: string[];
     }): Promise<import('../../../../types/exporter').StreamHistoryEntry[]>;
+    private signalQueueTable;
+    private rowToSignalEntry;
+    enqueueSignal(params: {
+        namespace: string;
+        appId: string;
+        signalKey: string;
+        workflowId: string;
+        jobId?: string;
+        topic?: string;
+        role?: string;
+        type?: string;
+        subtype?: string;
+        priority?: number;
+        description?: string;
+        taskQueue?: string;
+        workflowType?: string;
+        assignedTo?: string;
+        metadata?: Record<string, unknown>;
+        envelope?: Record<string, unknown>;
+        expiresAt?: Date;
+    }): Promise<{
+        id: string;
+    } | null>;
+    claimSignal(params: {
+        namespace: string;
+        appId: string;
+        id: string;
+        assignee?: string;
+        durationMinutes?: number;
+    }): Promise<{
+        ok: true;
+        entry: SignalQueueEntry;
+    } | {
+        ok: false;
+        reason: 'not-found' | 'conflict';
+    }>;
+    claimSignalByMetadata(params: {
+        namespace: string;
+        appId: string;
+        key: string;
+        value: unknown;
+        assignee?: string;
+        durationMinutes?: number;
+    }): Promise<{
+        ok: true;
+        entry: SignalQueueEntry;
+    } | {
+        ok: false;
+        reason: 'not-found' | 'conflict';
+    }>;
+    releaseSignal(params: {
+        namespace: string;
+        appId: string;
+        id: string;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: 'not-found' | 'wrong-status';
+    }>;
+    resolveSignal(params: {
+        namespace: string;
+        appId: string;
+        id: string;
+        resolverPayload?: Record<string, unknown>;
+    }): Promise<{
+        ok: true;
+        signalKey: string;
+        topic: string;
+    } | {
+        ok: false;
+        reason: 'not-found' | 'already-resolved';
+    }>;
+    resolveSignalByMetadata(params: {
+        namespace: string;
+        appId: string;
+        key: string;
+        value: unknown;
+        resolverPayload?: Record<string, unknown>;
+    }): Promise<{
+        ok: true;
+        signalKey: string;
+        topic: string;
+    } | {
+        ok: false;
+        reason: 'not-found';
+    }>;
+    releaseExpiredSignals(params: {
+        namespace: string;
+        appId: string;
+    }): Promise<number>;
+    listSignals(params: {
+        namespace: string;
+        appId: string;
+        status?: string;
+        role?: string;
+        taskQueue?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        id: string;
+        namespace: string;
+        appId: string;
+        signalKey: string;
+        workflowId: string;
+        jobId: string;
+        topic: string;
+        status: "pending" | "claimed" | "resolved" | "expired" | "released";
+        role: string;
+        type: string;
+        subtype: string;
+        priority: number;
+        description: string;
+        taskQueue: string;
+        workflowType: string;
+        assignedTo: string;
+        claimedAt: Date;
+        claimExpiresAt: Date;
+        resolvedAt: Date;
+        resolverPayload: Record<string, unknown>;
+        envelope: Record<string, unknown>;
+        metadata: Record<string, unknown>;
+        expiresAt: Date;
+        createdAt: Date;
+        updatedAt: Date;
+    }[]>;
+    getSignal(params: {
+        namespace: string;
+        appId: string;
+        id: string;
+    }): Promise<{
+        id: string;
+        namespace: string;
+        appId: string;
+        signalKey: string;
+        workflowId: string;
+        jobId: string;
+        topic: string;
+        status: "pending" | "claimed" | "resolved" | "expired" | "released";
+        role: string;
+        type: string;
+        subtype: string;
+        priority: number;
+        description: string;
+        taskQueue: string;
+        workflowType: string;
+        assignedTo: string;
+        claimedAt: Date;
+        claimExpiresAt: Date;
+        resolvedAt: Date;
+        resolverPayload: Record<string, unknown>;
+        envelope: Record<string, unknown>;
+        metadata: Record<string, unknown>;
+        expiresAt: Date;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
+    getSignalBySignalKey(params: {
+        namespace: string;
+        appId: string;
+        signalKey: string;
+    }): Promise<{
+        id: string;
+        namespace: string;
+        appId: string;
+        signalKey: string;
+        workflowId: string;
+        jobId: string;
+        topic: string;
+        status: "pending" | "claimed" | "resolved" | "expired" | "released";
+        role: string;
+        type: string;
+        subtype: string;
+        priority: number;
+        description: string;
+        taskQueue: string;
+        workflowType: string;
+        assignedTo: string;
+        claimedAt: Date;
+        claimExpiresAt: Date;
+        resolvedAt: Date;
+        resolverPayload: Record<string, unknown>;
+        envelope: Record<string, unknown>;
+        metadata: Record<string, unknown>;
+        expiresAt: Date;
+        createdAt: Date;
+        updatedAt: Date;
+    }>;
     /**
      * Parse a HotMesh-encoded value string.
      * Values may be prefixed with `/s` (JSON), `/d` (number), `/t` or `/f` (boolean), `/n` (null).

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

@@ -1368,6 +1368,289 @@ class PostgresStoreService extends __1.StoreService {
             };
         });
     }
+    // ─── Signal Queue Methods ─────────────────────────────────────────────────
+    signalQueueTable() {
+        return `${this.kvsql().safeName(this.appId)}.hotmesh_signals`;
+    }
+    rowToSignalEntry(row) {
+        return {
+            id: row.id,
+            namespace: row.namespace,
+            appId: row.app_id,
+            signalKey: row.signal_key,
+            workflowId: row.workflow_id,
+            jobId: row.job_id,
+            topic: row.topic,
+            status: row.status,
+            role: row.role,
+            type: row.type,
+            subtype: row.subtype,
+            priority: row.priority,
+            description: row.description,
+            taskQueue: row.task_queue,
+            workflowType: row.workflow_type,
+            assignedTo: row.assigned_to,
+            claimedAt: row.claimed_at ? new Date(row.claimed_at) : undefined,
+            claimExpiresAt: row.claim_expires_at ? new Date(row.claim_expires_at) : undefined,
+            resolvedAt: row.resolved_at ? new Date(row.resolved_at) : undefined,
+            resolverPayload: row.resolver_payload,
+            envelope: row.envelope,
+            metadata: row.metadata,
+            expiresAt: row.expires_at ? new Date(row.expires_at) : undefined,
+            createdAt: new Date(row.created_at),
+            updatedAt: new Date(row.updated_at),
+        };
+    }
+    async enqueueSignal(params) {
+        const tbl = this.signalQueueTable();
+        const result = await this.pgClient.query(`INSERT INTO ${tbl}
+         (namespace, app_id, signal_key, workflow_id, job_id, topic,
+          role, type, subtype, priority, description,
+          task_queue, workflow_type, assigned_to,
+          metadata, envelope, expires_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17)
+       ON CONFLICT (namespace, app_id, signal_key) DO NOTHING
+       RETURNING id`, [
+            params.namespace,
+            params.appId,
+            params.signalKey,
+            params.workflowId,
+            params.jobId ?? null,
+            params.topic ?? null,
+            params.role ?? null,
+            params.type ?? null,
+            params.subtype ?? null,
+            params.priority ?? 5,
+            params.description ?? null,
+            params.taskQueue ?? null,
+            params.workflowType ?? null,
+            params.assignedTo ?? null,
+            params.metadata ? JSON.stringify(params.metadata) : null,
+            params.envelope ? JSON.stringify(params.envelope) : null,
+            params.expiresAt ?? null,
+        ]);
+        if (result.rows.length === 0)
+            return null;
+        return { id: result.rows[0].id };
+    }
+    async claimSignal(params) {
+        const tbl = this.signalQueueTable();
+        const minutes = params.durationMinutes ?? 30;
+        const result = await this.pgClient.query(`WITH found AS (
+         SELECT id, status FROM ${tbl}
+         WHERE namespace = $1 AND app_id = $2 AND id = $4
+       ),
+       claimed AS (
+         UPDATE ${tbl}
+         SET status = 'claimed',
+             claimed_at = NOW(),
+             claim_expires_at = NOW() + INTERVAL '${minutes} minutes',
+             assigned_to = COALESCE($3, assigned_to),
+             updated_at = NOW()
+         WHERE namespace = $1 AND app_id = $2
+           AND id = $4
+           AND status = 'pending'
+         RETURNING *
+       )
+       SELECT c.*, f.id AS f_id
+       FROM found f
+       LEFT JOIN claimed c ON c.id = f.id`, [params.namespace, params.appId, params.assignee ?? null, params.id]);
+        if (result.rows.length === 0 || !result.rows[0].f_id) {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (!result.rows[0].id) {
+            return { ok: false, reason: 'conflict' };
+        }
+        return { ok: true, entry: this.rowToSignalEntry(result.rows[0]) };
+    }
+    async claimSignalByMetadata(params) {
+        const tbl = this.signalQueueTable();
+        const minutes = params.durationMinutes ?? 30;
+        const containsJson = JSON.stringify({ [params.key]: params.value });
+        const result = await this.pgClient.query(`WITH found AS (
+         SELECT id, status FROM ${tbl}
+         WHERE namespace = $1 AND app_id = $2
+           AND metadata @> $4::jsonb
+         ORDER BY priority ASC, created_at ASC
+         LIMIT 1
+       ),
+       claimed AS (
+         UPDATE ${tbl}
+         SET status = 'claimed',
+             claimed_at = NOW(),
+             claim_expires_at = NOW() + INTERVAL '${minutes} minutes',
+             assigned_to = COALESCE($3, assigned_to),
+             updated_at = NOW()
+         WHERE namespace = $1 AND app_id = $2
+           AND id = (SELECT id FROM found)
+           AND status = 'pending'
+         RETURNING *
+       )
+       SELECT c.*, f.id AS f_id
+       FROM found f
+       LEFT JOIN claimed c ON c.id = f.id`, [params.namespace, params.appId, params.assignee ?? null, containsJson]);
+        if (result.rows.length === 0 || !result.rows[0].f_id) {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (!result.rows[0].id) {
+            return { ok: false, reason: 'conflict' };
+        }
+        return { ok: true, entry: this.rowToSignalEntry(result.rows[0]) };
+    }
+    async releaseSignal(params) {
+        const tbl = this.signalQueueTable();
+        const result = await this.pgClient.query(`WITH found AS (
+         SELECT id, status FROM ${tbl}
+         WHERE namespace = $1 AND app_id = $2 AND id = $3
+       ),
+       released AS (
+         UPDATE ${tbl}
+         SET status = 'pending',
+             claimed_at = NULL,
+             claim_expires_at = NULL,
+             assigned_to = NULL,
+             updated_at = NOW()
+         WHERE namespace = $1 AND app_id = $2
+           AND id = $3
+           AND status = 'claimed'
+         RETURNING id
+       )
+       SELECT r.id AS r_id, f.id AS f_id
+       FROM found f
+       LEFT JOIN released r ON r.id = f.id`, [params.namespace, params.appId, params.id]);
+        if (result.rows.length === 0 || !result.rows[0].f_id) {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (!result.rows[0].r_id) {
+            return { ok: false, reason: 'wrong-status' };
+        }
+        return { ok: true };
+    }
+    async resolveSignal(params) {
+        const tbl = this.signalQueueTable();
+        const result = await this.pgClient.query(`WITH found AS (
+         SELECT id, status, signal_key, topic FROM ${tbl}
+         WHERE namespace = $1 AND app_id = $2 AND id = $4
+       ),
+       resolved AS (
+         UPDATE ${tbl}
+         SET status = 'resolved',
+             resolved_at = NOW(),
+             resolver_payload = $3::jsonb,
+             updated_at = NOW()
+         WHERE namespace = $1 AND app_id = $2
+           AND id = $4
+           AND status IN ('pending', 'claimed')
+         RETURNING id, signal_key, topic
+       )
+       SELECT r.id AS r_id, r.signal_key, r.topic, f.id AS f_id
+       FROM found f
+       LEFT JOIN resolved r ON r.id = f.id`, [
+            params.namespace,
+            params.appId,
+            params.resolverPayload ? JSON.stringify(params.resolverPayload) : null,
+            params.id,
+        ]);
+        if (result.rows.length === 0 || !result.rows[0].f_id) {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (!result.rows[0].r_id) {
+            return { ok: false, reason: 'already-resolved' };
+        }
+        return {
+            ok: true,
+            signalKey: result.rows[0].signal_key,
+            topic: result.rows[0].topic,
+        };
+    }
+    async resolveSignalByMetadata(params) {
+        const tbl = this.signalQueueTable();
+        const containsJson = JSON.stringify({ [params.key]: params.value });
+        const result = await this.pgClient.query(`WITH found AS (
+         SELECT id, signal_key, topic FROM ${tbl}
+         WHERE namespace = $1 AND app_id = $2
+           AND status IN ('pending', 'claimed')
+           AND metadata @> $4::jsonb
+         LIMIT 1
+       ),
+       resolved AS (
+         UPDATE ${tbl}
+         SET status = 'resolved',
+             resolved_at = NOW(),
+             resolver_payload = $3::jsonb,
+             updated_at = NOW()
+         WHERE namespace = $1 AND app_id = $2
+           AND id = (SELECT id FROM found)
+           AND status IN ('pending', 'claimed')
+         RETURNING id, signal_key, topic
+       )
+       SELECT r.id AS r_id, r.signal_key, r.topic, f.id AS f_id
+       FROM found f
+       LEFT JOIN resolved r ON r.id = f.id`, [
+            params.namespace,
+            params.appId,
+            params.resolverPayload ? JSON.stringify(params.resolverPayload) : null,
+            containsJson,
+        ]);
+        if (result.rows.length === 0 || !result.rows[0].f_id) {
+            return { ok: false, reason: 'not-found' };
+        }
+        return {
+            ok: true,
+            signalKey: result.rows[0].signal_key,
+            topic: result.rows[0].topic,
+        };
+    }
+    async releaseExpiredSignals(params) {
+        const tbl = this.signalQueueTable();
+        const result = await this.pgClient.query(`UPDATE ${tbl}
+       SET status = 'pending',
+           claimed_at = NULL,
+           claim_expires_at = NULL,
+           updated_at = NOW()
+       WHERE namespace = $1 AND app_id = $2
+         AND status = 'claimed'
+         AND claim_expires_at < NOW()`, [params.namespace, params.appId]);
+        return result.rowCount ?? 0;
+    }
+    async listSignals(params) {
+        const tbl = this.signalQueueTable();
+        const conditions = ['namespace = $1', 'app_id = $2'];
+        const values = [params.namespace, params.appId];
+        let idx = 3;
+        if (params.status) {
+            conditions.push(`status = $${idx++}`);
+            values.push(params.status);
+        }
+        if (params.role) {
+            conditions.push(`role = $${idx++}`);
+            values.push(params.role);
+        }
+        if (params.taskQueue) {
+            conditions.push(`task_queue = $${idx++}`);
+            values.push(params.taskQueue);
+        }
+        const where = conditions.join(' AND ');
+        const limit = params.limit ?? 50;
+        const offset = params.offset ?? 0;
+        const result = await this.pgClient.query(`SELECT * FROM ${tbl} WHERE ${where} ORDER BY priority ASC, created_at ASC LIMIT $${idx++} OFFSET $${idx}`, [...values, limit, offset]);
+        return result.rows.map(r => this.rowToSignalEntry(r));
+    }
+    async getSignal(params) {
+        const tbl = this.signalQueueTable();
+        const result = await this.pgClient.query(`SELECT * FROM ${tbl} WHERE namespace = $1 AND app_id = $2 AND id = $3`, [params.namespace, params.appId, params.id]);
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToSignalEntry(result.rows[0]);
+    }
+    async getSignalBySignalKey(params) {
+        const tbl = this.signalQueueTable();
+        const result = await this.pgClient.query(`SELECT * FROM ${tbl} WHERE namespace = $1 AND app_id = $2 AND signal_key = $3 LIMIT 1`, [params.namespace, params.appId, params.signalKey]);
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToSignalEntry(result.rows[0]);
+    }
+    // ─────────────────────────────────────────────────────────────────────────
     /**
      * Parse a HotMesh-encoded value string.
      * Values may be prefixed with `/s` (JSON), `/d` (number), `/t` or `/f` (boolean), `/n` (null).

package/build/types/index.d.ts

@@ -25,3 +25,4 @@ export { ReclaimedMessageType, RetryPolicy, RouterConfig, StreamCode, StreamConf
 export { context, Context, Counter, Meter, metrics, propagation, SpanContext, Span, SpanStatus, SpanStatusCode, SpanKind, trace, Tracer, ValueType, } from './telemetry';
 export { WorkListTaskType } from './task';
 export { TransitionMatch, TransitionRule, Transitions } from './transition';
+export { ClaimSignalByMetadataParams, ClaimSignalParams, ClaimSignalResult, ConditionQueueConfig, EnqueueSignalParams, ListSignalsParams, ReleaseSignalResult, ResolveSignalByMetadataParams, ResolveSignalParams, ResolveSignalResult, SignalQueueEntry, } from './signal';

package/build/types/signal.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Represents a queued signal record in the hotmesh_signals table.
+ * Created atomically with workflow suspension when condition() is called
+ * with a queue configuration.
+ */
+export interface SignalQueueEntry {
+    id: string;
+    namespace: string;
+    appId: string;
+    signalKey: string;
+    workflowId: string;
+    jobId?: string;
+    topic?: string;
+    status: 'pending' | 'claimed' | 'resolved' | 'expired' | 'released';
+    role?: string;
+    type?: string;
+    subtype?: string;
+    priority: number;
+    description?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    assignedTo?: string;
+    claimedAt?: Date;
+    claimExpiresAt?: Date;
+    resolvedAt?: Date;
+    resolverPayload?: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Optional queue configuration passed to condition() to create a
+ * richly-typed, indexed, claimable signal record alongside workflow suspension.
+ *
+ * metadata is GIN-indexed and used for claimByMetadata / resolveByMetadata queries.
+ * envelope is unindexed and intended for display context (form schemas, etc.).
+ */
+export interface ConditionQueueConfig {
+    role?: string;
+    type?: string;
+    subtype?: string;
+    priority?: number;
+    description?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    assignedTo?: string;
+    metadata?: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    durationMinutes?: number;
+}
+export interface EnqueueSignalParams {
+    namespace: string;
+    appId: string;
+    signalKey: string;
+    workflowId: string;
+    jobId?: string;
+    topic?: string;
+    role?: string;
+    type?: string;
+    subtype?: string;
+    priority?: number;
+    description?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    assignedTo?: string;
+    metadata?: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+export interface ClaimSignalParams {
+    id: string;
+    assignee?: string;
+    durationMinutes?: number;
+}
+export interface ClaimSignalByMetadataParams {
+    key: string;
+    value: unknown;
+    assignee?: string;
+    durationMinutes?: number;
+}
+export interface ResolveSignalParams {
+    id: string;
+    resolverPayload?: Record<string, unknown>;
+}
+export interface ResolveSignalByMetadataParams {
+    key: string;
+    value: unknown;
+    resolverPayload?: Record<string, unknown>;
+}
+export interface ListSignalsParams {
+    status?: 'pending' | 'claimed' | 'resolved' | 'expired' | 'released';
+    role?: string;
+    taskQueue?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Result of a claim operation (by ID or by metadata).
+ *
+ * - ok: true  → signal was claimed; entry contains the full record
+ * - ok: false, reason: 'not-found'  → no signal exists for the given id/metadata
+ * - ok: false, reason: 'conflict'   → signal exists but was already claimed concurrently
+ */
+export type ClaimSignalResult = {
+    ok: true;
+    entry: SignalQueueEntry;
+} | {
+    ok: false;
+    reason: 'not-found' | 'conflict';
+};
+/**
+ * Result of a resolve operation (by ID or by metadata).
+ *
+ * - ok: true  → signal marked resolved and workflow signal delivered
+ * - ok: false, reason: 'not-found'       → no pending/claimed signal found
+ * - ok: false, reason: 'already-resolved' → signal exists but was already resolved (id-based only)
+ * - ok: false, reason: 'signal-failed'    → DB record updated but workflow signal delivery failed;
+ *                                            signalKey is provided so callers can retry delivery
+ */
+export type ResolveSignalResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-found';
+} | {
+    ok: false;
+    reason: 'already-resolved';
+} | {
+    ok: false;
+    reason: 'signal-failed';
+    signalKey: string;
+};
+/**
+ * Result of a release operation.
+ *
+ * - ok: true  → signal returned to pending
+ * - ok: false, reason: 'not-found'    → no signal exists for this id
+ * - ok: false, reason: 'wrong-status' → signal exists but is not in 'claimed' status
+ */
+export type ReleaseSignalResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-found' | 'wrong-status';
+};

package/build/types/signal.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",