@hotmeshio/hotmesh 0.14.4 → 0.14.6

package/build/modules/enums.d.ts

@@ -55,6 +55,12 @@ export declare const HMSH_TELEMETRY: "debug" | "info";
  * Default cleanup time for signal in the db when its associated job is completed.
  */
 export declare const HMSH_SIGNAL_EXPIRE = 3600;
+/**
+ * Default TTL for pending signals (signals that arrived before the hook registered).
+ * The signaler can override this via the `$expire` field in the signal data
+ * using a natural-language duration (e.g., '1h', '24h').
+ */
+export declare const HMSH_PENDING_SIGNAL_EXPIRE = 600;
 export declare const HMSH_CODE_SUCCESS = 200;
 export declare const HMSH_CODE_PENDING = 202;
 export declare const HMSH_CODE_NOTFOUND = 404;
@@ -155,6 +161,42 @@ export declare const HMSH_BLOCK_TIME_MS: number;
 export declare const HMSH_XCLAIM_DELAY_MS: number;
 export declare const HMSH_XCLAIM_COUNT: number;
 export declare const HMSH_XPENDING_COUNT: number;
+export declare const HMSH_BATCH_SIZE: number;
+/**
+ * Postgres stream reservation timeout in seconds (default: 30).
+ *
+ * This is the **starting** reservation timeout for the Postgres stream
+ * consumer. When a consumer reserves a message from the stream, it must
+ * acknowledge it within this window. If processing takes longer, the
+ * message becomes available to other consumers — causing duplicate
+ * delivery, collation errors, and wasted CPU.
+ *
+ * **Adaptive behavior:** The router automatically adjusts this timeout
+ * at runtime based on stream depth. When the queue backs up (depth > 100),
+ * the timeout doubles (up to 600s). When the queue drains (depth < 10),
+ * it halves back toward this configured default. This prevents duplicate
+ * delivery under burst load without manual intervention.
+ *
+ * **When to increase this value:** If you see `process-event-*-error`
+ * warnings at `warn` level or `stream-reservation-timeout-adjusted` logs
+ * scaling up frequently, your baseline is too low for your workload.
+ * Setting a higher default reduces how aggressively the system must
+ * adapt during load spikes.
+ *
+ * **Symptoms of a value that is too low:**
+ *   - `collation-error` from `verifySyntheticInteger` (warn level)
+ *   - `process-event-collation-rate-exceeded` warning with guidance
+ *   - `stream-reservation-timeout-adjusted` logs showing rapid scaling
+ *   - Workflow stalls or timeouts under sustained concurrent load
+ *
+ * @example
+ * // Production with sustained high concurrency
+ * HMSH_RESERVATION_TIMEOUT_S=120
+ *
+ * // Low-latency environments with fast processing
+ * HMSH_RESERVATION_TIMEOUT_S=30  (default)
+ */
+export declare const HMSH_RESERVATION_TIMEOUT_S: number;
 export declare const HMSH_EXPIRE_DURATION: number;
 export declare const HMSH_FIDELITY_SECONDS: number;
 export declare const HMSH_SCOUT_INTERVAL_SECONDS: number;

package/build/modules/enums.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_GUID_SIZE = exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = 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_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = 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_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_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_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = void 0;
+exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_RESERVATION_TIMEOUT_S = exports.HMSH_BATCH_SIZE = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_POISON_MESSAGE_THRESHOLD = 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_DURABLE_RETRYABLE = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_CHILD = exports.HMSH_CODE_DURABLE_ALL = exports.HMSH_CODE_DURABLE_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_PENDING_SIGNAL_EXPIRE = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.HMSH_ROUTER_POLL_FALLBACK_INTERVAL = exports.HMSH_NOTIFY_PAYLOAD_LIMIT = exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_ROUTER_SCOUT_INTERVAL_MS = exports.HMSH_ROUTER_SCOUT_INTERVAL_SECONDS = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -58,6 +58,12 @@ exports.HMSH_TELEMETRY = process.env.HMSH_TELEMETRY || 'info';
  * Default cleanup time for signal in the db when its associated job is completed.
  */
 exports.HMSH_SIGNAL_EXPIRE = 3600; //seconds
+/**
+ * Default TTL for pending signals (signals that arrived before the hook registered).
+ * The signaler can override this via the `$expire` field in the signal data
+ * using a natural-language duration (e.g., '1h', '24h').
+ */
+exports.HMSH_PENDING_SIGNAL_EXPIRE = 600; //seconds (10 minutes)
 // HOTMESH STATUS CODES
 exports.HMSH_CODE_SUCCESS = 200;
 exports.HMSH_CODE_PENDING = 202;
@@ -172,6 +178,42 @@ exports.HMSH_BLOCK_TIME_MS = process.env.HMSH_BLOCK_TIME_MS
 exports.HMSH_XCLAIM_DELAY_MS = parseInt(process.env.HMSH_XCLAIM_DELAY_MS, 10) || 1000 * 60;
 exports.HMSH_XCLAIM_COUNT = parseInt(process.env.HMSH_XCLAIM_COUNT, 10) || 3;
 exports.HMSH_XPENDING_COUNT = parseInt(process.env.HMSH_XPENDING_COUNT, 10) || 10;
+exports.HMSH_BATCH_SIZE = parseInt(process.env.HMSH_BATCH_SIZE, 10) || 10;
+/**
+ * Postgres stream reservation timeout in seconds (default: 30).
+ *
+ * This is the **starting** reservation timeout for the Postgres stream
+ * consumer. When a consumer reserves a message from the stream, it must
+ * acknowledge it within this window. If processing takes longer, the
+ * message becomes available to other consumers — causing duplicate
+ * delivery, collation errors, and wasted CPU.
+ *
+ * **Adaptive behavior:** The router automatically adjusts this timeout
+ * at runtime based on stream depth. When the queue backs up (depth > 100),
+ * the timeout doubles (up to 600s). When the queue drains (depth < 10),
+ * it halves back toward this configured default. This prevents duplicate
+ * delivery under burst load without manual intervention.
+ *
+ * **When to increase this value:** If you see `process-event-*-error`
+ * warnings at `warn` level or `stream-reservation-timeout-adjusted` logs
+ * scaling up frequently, your baseline is too low for your workload.
+ * Setting a higher default reduces how aggressively the system must
+ * adapt during load spikes.
+ *
+ * **Symptoms of a value that is too low:**
+ *   - `collation-error` from `verifySyntheticInteger` (warn level)
+ *   - `process-event-collation-rate-exceeded` warning with guidance
+ *   - `stream-reservation-timeout-adjusted` logs showing rapid scaling
+ *   - Workflow stalls or timeouts under sustained concurrent load
+ *
+ * @example
+ * // Production with sustained high concurrency
+ * HMSH_RESERVATION_TIMEOUT_S=120
+ *
+ * // Low-latency environments with fast processing
+ * HMSH_RESERVATION_TIMEOUT_S=30  (default)
+ */
+exports.HMSH_RESERVATION_TIMEOUT_S = parseInt(process.env.HMSH_RESERVATION_TIMEOUT_S, 10) || 30;
 // TASK WORKER
 exports.HMSH_EXPIRE_DURATION = parseInt(process.env.HMSH_EXPIRE_DURATION, 10) || 1;
 const BASE_FIDELITY_SECONDS = 5;

package/build/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.14.4",
+    "version": "0.14.6",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
-    "homepage": "https://github.com/hotmeshio/sdk-typescript/",
+    "homepage": "https://docs.hotmesh.io/",
     "publishConfig": {
         "access": "public"
     },
@@ -30,6 +30,7 @@
         "test:durable:postgres": "HMSH_LOGLEVEL=info vitest run tests/durable",
         "test:durable:basic": "HMSH_LOGLEVEL=info vitest run tests/durable/basic/postgres.test.ts",
         "test:durable:collision": "vitest run tests/durable/collision/postgres.test.ts",
+        "test:durable:contention": "vitest run tests/durable/contention/postgres.test.ts",
         "test:durable:fatal": "vitest run tests/durable/fatal",
         "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
         "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",

package/build/services/activities/activity/process.js

@@ -6,6 +6,11 @@ const errors_1 = require("../../../modules/errors");
 const collator_1 = require("../../collator");
 const telemetry_1 = require("../../telemetry");
 const stream_1 = require("../../../types/stream");
+// Per-instance collation error tracking for reservation timeout detection
+let collationErrorCount = 0;
+let collationWindowStart = Date.now();
+const COLLATION_WARN_THRESHOLD = 10;
+const COLLATION_WINDOW_MS = 60000;
 async function processEvent(instance, status = stream_1.StreamStatus.SUCCESS, code = 200, type = 'output') {
     instance.setLeg(2);
     const jid = instance.context.metadata.jid;
@@ -66,7 +71,32 @@ async function processEvent(instance, status = stream_1.StreamStatus.SUCCESS, co
     }
     catch (error) {
         if (error instanceof errors_1.CollationError) {
-            instance.logger.info(`process-event-${error.fault}-error`, { error });
+            // INACTIVE is legitimate duplicate detection — the Postgres atomic
+            // CTE (collateLeg2Entry) serializes via row locks, so the GUID
+            // ledger value is correct. Silent ack is the right behavior:
+            // the work was already done by a prior delivery of this message.
+            const now = Date.now();
+            if (now - collationWindowStart > COLLATION_WINDOW_MS) {
+                collationErrorCount = 0;
+                collationWindowStart = now;
+            }
+            collationErrorCount++;
+            if (collationErrorCount === COLLATION_WARN_THRESHOLD) {
+                instance.logger.warn('process-event-collation-rate-exceeded', {
+                    count: collationErrorCount,
+                    windowMs: COLLATION_WINDOW_MS,
+                    reservationTimeoutS: enums_1.HMSH_RESERVATION_TIMEOUT_S,
+                    message: `${COLLATION_WARN_THRESHOLD} collation errors in ${COLLATION_WINDOW_MS / 1000}s. ` +
+                        `This typically means HMSH_RESERVATION_TIMEOUT_S (currently ${enums_1.HMSH_RESERVATION_TIMEOUT_S}s) ` +
+                        `is too short for your workload — messages are being re-reserved before processing completes, ` +
+                        `causing duplicate delivery. Increase HMSH_RESERVATION_TIMEOUT_S.`,
+                });
+            }
+            instance.logger.warn(`process-event-${error.fault}-error`, {
+                jid: instance.context.metadata.jid,
+                aid: instance.metadata.aid,
+                error,
+            });
             return;
         }
         else if (error instanceof errors_1.InactiveJobError) {

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

@@ -152,9 +152,18 @@ declare class Hook extends Activity {
     isConfiguredAsHook(): boolean;
     doesHook(): boolean;
     doHook(telemetry: TelemetryService): Promise<void>;
+    /**
+     * Re-publishes a pending signal as a WEBHOOK stream message so the
+     * normal leg2 dispatch path processes it. Called when leg1's
+     * setHookSignal atomically detected and consumed a pending signal.
+     */
+    private redeliverPendingSignal;
     doPassThrough(telemetry: TelemetryService): Promise<void>;
     getHookRule(topic: string): Promise<HookRule | undefined>;
-    registerHook(transaction?: ProviderTransaction): Promise<string | void>;
+    registerHook(transaction?: ProviderTransaction): Promise<{
+        jobId?: string;
+        pending?: string;
+    } | void>;
     processWebHookEvent(status?: StreamStatus, code?: StreamCode): Promise<JobStatus | void>;
     processTimeHookEvent(jobId: string): Promise<JobStatus | void>;
 }

package/build/services/activities/hook.js

@@ -6,6 +6,7 @@ const pipe_1 = require("../pipe");
 const task_1 = require("../task");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
+const utils_1 = require("../../modules/utils");
 const activity_1 = require("./activity");
 /**
  * A versatile pause/resume activity that supports three distinct patterns:
@@ -203,7 +204,7 @@ class Hook extends activity_1.Activity {
     }
     async doHook(telemetry) {
         const transaction = this.store.transact();
-        await this.registerHook(transaction);
+        const hookResult = await this.registerHook(transaction);
         this.mapOutputData();
         this.mapJobData();
         await this.setState(transaction);
@@ -211,6 +212,38 @@ class Hook extends activity_1.Activity {
         await this.setStatus(0, transaction);
         await transaction.exec();
         telemetry.mapActivityAttributes();
+        //if a pending signal was detected (signal arrived before hook
+        //registered), re-publish the WEBHOOK so leg2 processes it
+        //now that the hook signal is committed and state is saved
+        if (hookResult && hookResult.pending) {
+            await this.redeliverPendingSignal(hookResult.pending);
+        }
+    }
+    /**
+     * Re-publishes a pending signal as a WEBHOOK stream message so the
+     * normal leg2 dispatch path processes it. Called when leg1's
+     * setHookSignal atomically detected and consumed a pending signal.
+     */
+    async redeliverPendingSignal(pendingJson) {
+        const data = JSON.parse(pendingJson);
+        const hookRule = await this.getHookRule(this.config.hook.topic);
+        this.logger.warn('hook-pending-signal-redelivery', {
+            topic: this.config.hook.topic,
+            aid: hookRule?.to || this.metadata.aid,
+            jid: this.context.metadata.jid,
+        });
+        const streamData = {
+            type: stream_1.StreamDataType.WEBHOOK,
+            status: stream_1.StreamStatus.SUCCESS,
+            code: 200,
+            metadata: {
+                guid: (0, utils_1.guid)(),
+                aid: hookRule?.to || this.metadata.aid,
+                topic: this.config.hook.topic,
+            },
+            data,
+        };
+        await this.engine.router?.publishMessage(null, streamData);
     }
     async doPassThrough(telemetry) {
         this.adjacencyList = await this.filterAdjacent();
@@ -225,19 +258,25 @@ class Hook extends activity_1.Activity {
         return rules?.[topic]?.[0];
     }
     async registerHook(transaction) {
-        let result;
+        let jobId;
+        let pending;
         if (this.config.hook?.topic) {
-            result = await this.engine.taskService.registerWebHook(this.config.hook.topic, this.context, this.resolveDad(), this.context.metadata.expire, transaction);
+            //hook signal is set standalone (not in the transaction) so the
+            //single CTE query can atomically detect a pending signal collision
+            const hookResult = await this.engine.taskService.registerWebHook(this.config.hook.topic, this.context, this.resolveDad(), this.context.metadata.expire);
+            jobId = hookResult.jobId;
+            pending = hookResult.pending;
         }
         if (this.config.sleep) {
             const duration = pipe_1.Pipe.resolve(this.config.sleep, this.context);
             if (!isNaN(duration) && Number(duration) > 0) {
                 await this.engine.taskService.registerTimeHook(this.context.metadata.jid, this.context.metadata.gid, `${this.metadata.aid}${this.metadata.dad || ''}`, 'sleep', duration, this.metadata.dad || '', transaction);
-                if (!result)
-                    result = this.context.metadata.jid;
+                if (!jobId)
+                    jobId = this.context.metadata.jid;
             }
         }
-        return result;
+        if (jobId)
+            return { jobId, pending };
     }
     async processWebHookEvent(status = stream_1.StreamStatus.SUCCESS, code = 200) {
         this.logger.debug('hook-process-web-hook-event', {

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

@@ -14,6 +14,7 @@ import { PostgresClientType } from '../../types/postgres';
  * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `status`, `other`) that are only needed during workflow execution |
  * | `{appId}.engine_streams` | Processed engine stream messages with `expired_at` set |
  * | `{appId}.worker_streams` | Processed worker stream messages with `expired_at` set |
+ * | `{appId}.signal_registry` | Consumed hook signals and stale pending signals with `expiry` set |
  *
  * The `DBA` service addresses this with two methods:
  *

package/build/services/dba/index.js

@@ -17,6 +17,7 @@ const postgres_1 = require("../connector/providers/postgres");
  * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `status`, `other`) that are only needed during workflow execution |
  * | `{appId}.engine_streams` | Processed engine stream messages with `expired_at` set |
  * | `{appId}.worker_streams` | Processed worker stream messages with `expired_at` set |
+ * | `{appId}.signal_registry` | Consumed hook signals and stale pending signals with `expiry` set |
  *
  * The `DBA` service addresses this with two methods:
  *
@@ -186,7 +187,8 @@ class DBA {
         prune_engine_streams BOOLEAN DEFAULT NULL,
         prune_worker_streams BOOLEAN DEFAULT NULL,
         engine_streams_retention INTERVAL DEFAULT NULL,
-        worker_streams_retention INTERVAL DEFAULT NULL
+        worker_streams_retention INTERVAL DEFAULT NULL,
+        prune_signals BOOLEAN DEFAULT TRUE
       )
       RETURNS TABLE(
         deleted_jobs BIGINT,
@@ -195,7 +197,8 @@ class DBA {
         deleted_worker_streams BIGINT,
         stripped_attributes BIGINT,
         deleted_transient BIGINT,
-        marked_pruned BIGINT
+        marked_pruned BIGINT,
+        deleted_signals BIGINT
       )
       LANGUAGE plpgsql
       AS $$
@@ -206,6 +209,7 @@ class DBA {
         v_stripped_attributes BIGINT := 0;
         v_deleted_transient BIGINT := 0;
         v_marked_pruned BIGINT := 0;
+        v_deleted_signals BIGINT := 0;
         v_do_engine BOOLEAN;
         v_do_worker BOOLEAN;
         v_engine_retention INTERVAL;
@@ -287,6 +291,15 @@ class DBA {
           GET DIAGNOSTICS v_marked_pruned = ROW_COUNT;
         END IF;
 
+        -- 6. Hard-delete expired signal_registry rows.
+        --    Includes consumed hook signals and stale pending signals.
+        IF prune_signals THEN
+          DELETE FROM ${schema}.signal_registry
+          WHERE expiry IS NOT NULL
+            AND expiry <= NOW();
+          GET DIAGNOSTICS v_deleted_signals = ROW_COUNT;
+        END IF;
+
         deleted_jobs := v_deleted_jobs;
         deleted_streams := v_deleted_engine_streams + v_deleted_worker_streams;
         deleted_engine_streams := v_deleted_engine_streams;
@@ -294,6 +307,7 @@ class DBA {
         stripped_attributes := v_stripped_attributes;
         deleted_transient := v_deleted_transient;
         marked_pruned := v_marked_pruned;
+        deleted_signals := v_deleted_signals;
         RETURN NEXT;
       END;
       $$;
@@ -391,12 +405,14 @@ class DBA {
         const workerStreams = options.workerStreams ?? null;
         const engineStreamsExpire = options.engineStreamsExpire ?? null;
         const workerStreamsExpire = options.workerStreamsExpire ?? null;
+        const signals = options.signals ?? true;
         await DBA.deploy(options.connection, options.appId);
         const { client, release } = await DBA.getClient(options.connection);
         try {
-            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean, $8::boolean, $9::boolean, $10::interval, $11::interval)`, [
+            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean, $8::boolean, $9::boolean, $10::interval, $11::interval, $12::boolean)`, [
                 expire, jobs, streams, attributes, entities, pruneTransient, keepHmark,
                 engineStreams, workerStreams, engineStreamsExpire, workerStreamsExpire,
+                signals,
             ]);
             const row = result.rows[0];
             return {
@@ -407,6 +423,7 @@ class DBA {
                 attributes: Number(row.stripped_attributes),
                 transient: Number(row.deleted_transient),
                 marked: Number(row.marked_pruned),
+                signals: Number(row.deleted_signals),
             };
         }
         finally {

package/build/services/durable/client.js

@@ -156,11 +156,21 @@ class ClientService {
                 return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId);
             },
             /**
-             * Sends a message payload to a running workflow that is paused and awaiting the signal
+             * Sends a message payload to a running workflow that is paused and awaiting the signal.
+             *
+             * If the signal arrives before the workflow has registered its hook
+             * (race condition under load), it is buffered as a pending signal
+             * for up to `expire` (default 10 minutes). Use a longer duration
+             * when signaling "early on purpose" (e.g., depositing a payload
+             * hours before the workflow starts).
              */
-            signal: async (signalId, data, namespace) => {
+            signal: async (signalId, data, namespace, expire) => {
                 const topic = `${namespace ?? factory_1.APP_ID}.wfs.signal`;
-                return await (await this.getHotMeshClient(topic, namespace)).signal(topic, { id: signalId, data });
+                return await (await this.getHotMeshClient(topic, namespace)).signal(topic, {
+                    id: signalId,
+                    data,
+                    ...(expire ? { $expire: expire } : {}),
+                });
             },
             /**
              * Spawns an a new, isolated execution cycle within the same job.

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

@@ -57,10 +57,17 @@ export declare class WorkflowHandleService {
      * on `Durable.workflow.condition(signalId)`, it resumes with the
      * provided data.
      *
+     * If the signal arrives before the workflow has registered its hook
+     * (race condition under load), it is buffered as a pending signal
+     * for up to `expire` (default 10 minutes). Use a longer duration
+     * when signaling "early on purpose" (e.g., depositing a payload
+     * hours before the workflow starts).
+     *
      * @param signalId - Matches the `signalId` passed to `condition()`.
      * @param data - Payload delivered to the waiting workflow.
+     * @param expire - Optional pending signal TTL (e.g., '1h', '30d'). Default '10m'.
      */
-    signal(signalId: string, data: Record<any, any>): Promise<void>;
+    signal(signalId: string, data: Record<any, any>, expire?: string): Promise<void>;
     /**
      * Returns the current workflow state. For a completed workflow this
      * is the final output; for a running workflow it reflects the latest

package/build/services/durable/handle.js

@@ -58,13 +58,21 @@ class WorkflowHandleService {
      * on `Durable.workflow.condition(signalId)`, it resumes with the
      * provided data.
      *
+     * If the signal arrives before the workflow has registered its hook
+     * (race condition under load), it is buffered as a pending signal
+     * for up to `expire` (default 10 minutes). Use a longer duration
+     * when signaling "early on purpose" (e.g., depositing a payload
+     * hours before the workflow starts).
+     *
      * @param signalId - Matches the `signalId` passed to `condition()`.
      * @param data - Payload delivered to the waiting workflow.
+     * @param expire - Optional pending signal TTL (e.g., '1h', '30d'). Default '10m'.
      */
-    async signal(signalId, data) {
+    async signal(signalId, data, expire) {
         await this.hotMesh.signal(`${this.hotMesh.appId}.wfs.signal`, {
             id: signalId,
             data,
+            ...(expire ? { $expire: expire } : {}),
         });
     }
     /**

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

@@ -55,4 +55,4 @@
  * @param {Record<any, any>} data - The payload to deliver to the waiting workflow.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
-export declare function signal(signalId: string, data: Record<any, any>): Promise<string>;
+export declare function signal(signalId: string, data: Record<any, any>, expire?: string): Promise<string>;

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

@@ -60,7 +60,7 @@ const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
  * @param {Record<any, any>} data - The payload to deliver to the waiting workflow.
  * @returns {Promise<string>} The resulting hook/stream ID.
  */
-async function signal(signalId, data) {
+async function signal(signalId, data, expire) {
     const store = common_1.asyncLocalStorage.getStore();
     const workflowTopic = store.get('workflowTopic');
     const connection = store.get('connection');
@@ -73,6 +73,7 @@ async function signal(signalId, data) {
         return await hotMeshClient.signal(`${namespace}.wfs.signal`, {
             id: signalId,
             data,
+            ...(expire ? { $expire: expire } : {}),
         });
     }
 }

package/build/services/router/config/index.d.ts

@@ -1,4 +1,4 @@
-import { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD } from '../../../modules/enums';
+import { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, HMSH_BATCH_SIZE, HMSH_RESERVATION_TIMEOUT_S, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD } from '../../../modules/enums';
 import { RouterConfig } from '../../../types/stream';
 export declare class RouterConfigManager {
     static validateThrottle(delayInMillis: number): void;
@@ -8,4 +8,4 @@ export declare class RouterConfigManager {
         readonly: boolean;
     };
 }
-export { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD, };
+export { HMSH_BLOCK_TIME_MS, HMSH_MAX_RETRIES, HMSH_MAX_TIMEOUT_MS, HMSH_GRADUATED_INTERVAL_MS, HMSH_CODE_UNACKED, HMSH_CODE_UNKNOWN, HMSH_STATUS_UNKNOWN, HMSH_XCLAIM_COUNT, HMSH_XCLAIM_DELAY_MS, HMSH_XPENDING_COUNT, HMSH_BATCH_SIZE, HMSH_RESERVATION_TIMEOUT_S, MAX_DELAY, MAX_STREAM_BACKOFF, INITIAL_STREAM_BACKOFF, MAX_STREAM_RETRIES, HMSH_POISON_MESSAGE_THRESHOLD, };

package/build/services/router/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.MAX_DELAY = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_XCLAIM_COUNT = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_UNACKED = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_BLOCK_TIME_MS = exports.RouterConfigManager = void 0;
+exports.HMSH_POISON_MESSAGE_THRESHOLD = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.MAX_DELAY = exports.HMSH_RESERVATION_TIMEOUT_S = exports.HMSH_BATCH_SIZE = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_XCLAIM_COUNT = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_UNACKED = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.HMSH_BLOCK_TIME_MS = exports.RouterConfigManager = void 0;
 const enums_1 = require("../../../modules/enums");
 Object.defineProperty(exports, "HMSH_BLOCK_TIME_MS", { enumerable: true, get: function () { return enums_1.HMSH_BLOCK_TIME_MS; } });
 Object.defineProperty(exports, "HMSH_MAX_RETRIES", { enumerable: true, get: function () { return enums_1.HMSH_MAX_RETRIES; } });
@@ -12,6 +12,8 @@ Object.defineProperty(exports, "HMSH_STATUS_UNKNOWN", { enumerable: true, get: f
 Object.defineProperty(exports, "HMSH_XCLAIM_COUNT", { enumerable: true, get: function () { return enums_1.HMSH_XCLAIM_COUNT; } });
 Object.defineProperty(exports, "HMSH_XCLAIM_DELAY_MS", { enumerable: true, get: function () { return enums_1.HMSH_XCLAIM_DELAY_MS; } });
 Object.defineProperty(exports, "HMSH_XPENDING_COUNT", { enumerable: true, get: function () { return enums_1.HMSH_XPENDING_COUNT; } });
+Object.defineProperty(exports, "HMSH_BATCH_SIZE", { enumerable: true, get: function () { return enums_1.HMSH_BATCH_SIZE; } });
+Object.defineProperty(exports, "HMSH_RESERVATION_TIMEOUT_S", { enumerable: true, get: function () { return enums_1.HMSH_RESERVATION_TIMEOUT_S; } });
 Object.defineProperty(exports, "MAX_DELAY", { enumerable: true, get: function () { return enums_1.MAX_DELAY; } });
 Object.defineProperty(exports, "MAX_STREAM_BACKOFF", { enumerable: true, get: function () { return enums_1.MAX_STREAM_BACKOFF; } });
 Object.defineProperty(exports, "INITIAL_STREAM_BACKOFF", { enumerable: true, get: function () { return enums_1.INITIAL_STREAM_BACKOFF; } });

package/build/services/router/consumption/index.d.ts

@@ -26,7 +26,20 @@ export declare class ConsumptionManager<S extends StreamService<ProviderClient,
     private set hasReachedMaxBackoff(value);
     private router;
     private retry;
+    private adaptiveReservationTimeout;
+    private lastDepthCheckAt;
+    private static readonly DEPTH_CHECK_INTERVAL_MS;
+    private static readonly DEPTH_SCALE_UP_THRESHOLD;
+    private static readonly DEPTH_SCALE_DOWN_THRESHOLD;
+    private static readonly RESERVATION_TIMEOUT_MAX_S;
     constructor(stream: S, logger: ILogger, throttleManager: ThrottleManager, errorHandler: ErrorHandler, lifecycleManager: LifecycleManager<S>, reclaimDelay: number, reclaimCount: number, appId: string, role: any, router: any, retry?: import('../../../types/stream').RetryPolicy);
+    /**
+     * Adjusts reservation timeout based on stream depth. Called periodically
+     * from the consume loop. When depth is high, messages take longer to
+     * process, so the reservation window must grow to prevent re-delivery.
+     * When depth drops, the timeout shrinks back toward the configured default.
+     */
+    private adjustReservationTimeout;
     createGroup(stream: string, group: string): Promise<void>;
     publishMessage(topic: string, streamData: StreamData | StreamDataResponse, transaction?: ProviderTransaction): Promise<string | ProviderTransaction>;
     consumeMessages(stream: string, group: string, consumer: string, callback: (streamData: StreamData) => Promise<StreamDataResponse | void>): Promise<void>;

package/build/services/router/consumption/index.js

@@ -17,6 +17,11 @@ class ConsumptionManager {
     get hasReachedMaxBackoff() { return this.router.hasReachedMaxBackoff; }
     set hasReachedMaxBackoff(v) { this.router.hasReachedMaxBackoff = v; }
     constructor(stream, logger, throttleManager, errorHandler, lifecycleManager, reclaimDelay, reclaimCount, appId, role, router, retry) {
+        // Adaptive reservation timeout — scales with stream depth to prevent
+        // duplicate message delivery under load. When the stream backs up,
+        // processing takes longer, so the reservation window must grow.
+        this.adaptiveReservationTimeout = config_1.HMSH_RESERVATION_TIMEOUT_S;
+        this.lastDepthCheckAt = 0;
         this.stream = stream;
         this.logger = logger;
         this.throttleManager = throttleManager;
@@ -29,6 +34,46 @@ class ConsumptionManager {
         this.router = router;
         this.retry = retry;
     }
+    /**
+     * Adjusts reservation timeout based on stream depth. Called periodically
+     * from the consume loop. When depth is high, messages take longer to
+     * process, so the reservation window must grow to prevent re-delivery.
+     * When depth drops, the timeout shrinks back toward the configured default.
+     */
+    async adjustReservationTimeout(stream) {
+        const now = Date.now();
+        if (now - this.lastDepthCheckAt < ConsumptionManager.DEPTH_CHECK_INTERVAL_MS) {
+            return;
+        }
+        this.lastDepthCheckAt = now;
+        try {
+            const depth = await this.stream.getStreamDepth(stream);
+            const prev = this.adaptiveReservationTimeout;
+            if (depth > ConsumptionManager.DEPTH_SCALE_UP_THRESHOLD) {
+                // Scale up: double the timeout, capped at max
+                this.adaptiveReservationTimeout = Math.min(this.adaptiveReservationTimeout * 2, ConsumptionManager.RESERVATION_TIMEOUT_MAX_S);
+            }
+            else if (depth < ConsumptionManager.DEPTH_SCALE_DOWN_THRESHOLD) {
+                // Scale down: halve toward the configured default
+                this.adaptiveReservationTimeout = Math.max(Math.floor(this.adaptiveReservationTimeout / 2), config_1.HMSH_RESERVATION_TIMEOUT_S);
+            }
+            if (this.adaptiveReservationTimeout !== prev) {
+                // Update the stream provider so notification-path fetches
+                // also use the adaptive timeout
+                this.stream.reservationTimeout = this.adaptiveReservationTimeout;
+                this.logger.info('stream-reservation-timeout-adjusted', {
+                    stream,
+                    depth,
+                    previousTimeoutS: prev,
+                    newTimeoutS: this.adaptiveReservationTimeout,
+                    configuredDefaultS: config_1.HMSH_RESERVATION_TIMEOUT_S,
+                });
+            }
+        }
+        catch {
+            // Stream depth check is best-effort; don't fail the consume loop
+        }
+    }
     async createGroup(stream, group) {
         try {
             await this.stream.createConsumerGroup(stream, group);
@@ -107,6 +152,8 @@ class ConsumptionManager {
             if (this.lifecycleManager.isStopped(group, consumer, stream)) {
                 return;
             }
+            // Adapt reservation timeout based on stream depth
+            await this.adjustReservationTimeout(stream);
             await this.throttleManager.customSleep(); // respect throttle
             if (this.lifecycleManager.isStopped(group, consumer, stream) ||
                 this.throttleManager.isPaused()) {
@@ -183,6 +230,7 @@ class ConsumptionManager {
                 enableNotifications: true,
                 notificationCallback,
                 blockTimeout: config_1.HMSH_BLOCK_TIME_MS,
+                reservationTimeout: config_1.HMSH_RESERVATION_TIMEOUT_S,
             });
             // Don't block here - let the worker initialization complete
             // The notification system will handle message processing asynchronously
@@ -225,14 +273,17 @@ class ConsumptionManager {
             const streamDuration = config_1.HMSH_BLOCK_TIME_MS + Math.round(config_1.HMSH_BLOCK_TIME_MS * Math.random());
             try {
                 let messages = [];
+                // Adapt reservation timeout based on stream depth
+                await this.adjustReservationTimeout(stream);
                 if (!this.hasReachedMaxBackoff) {
                     // Normal mode: try with backoff and finite retries
                     const features = this.stream.getProviderSpecificFeatures();
                     const isPostgres = features.supportsParallelProcessing;
-                    const batchSize = isPostgres ? 10 : 1; // Use batch size of 10 for PostgreSQL, 1 for others
+                    const batchSize = isPostgres ? config_1.HMSH_BATCH_SIZE : 1;
                     messages = await this.stream.consumeMessages(stream, group, consumer, {
                         blockTimeout: streamDuration,
                         batchSize,
+                        reservationTimeout: this.adaptiveReservationTimeout,
                         enableBackoff: true,
                         initialBackoff: config_1.INITIAL_STREAM_BACKOFF,
                         maxBackoff: config_1.MAX_STREAM_BACKOFF,
@@ -243,10 +294,11 @@ class ConsumptionManager {
                     // Fallback mode: just try once, no backoff
                     const features = this.stream.getProviderSpecificFeatures();
                     const isPostgres = features.supportsParallelProcessing;
-                    const batchSize = isPostgres ? 10 : 1; // Use batch size of 10 for PostgreSQL, 1 for others
+                    const batchSize = isPostgres ? config_1.HMSH_BATCH_SIZE : 1;
                     messages = await this.stream.consumeMessages(stream, group, consumer, {
                         blockTimeout: streamDuration,
                         batchSize,
+                        reservationTimeout: this.adaptiveReservationTimeout,
                         enableBackoff: false,
                         maxRetries: 1,
                     });
@@ -542,4 +594,8 @@ class ConsumptionManager {
         return Array.isArray(result) && Array.isArray(result[0]);
     }
 }
+ConsumptionManager.DEPTH_CHECK_INTERVAL_MS = 10000;
+ConsumptionManager.DEPTH_SCALE_UP_THRESHOLD = 100;
+ConsumptionManager.DEPTH_SCALE_DOWN_THRESHOLD = 10;
+ConsumptionManager.RESERVATION_TIMEOUT_MAX_S = 600;
 exports.ConsumptionManager = ConsumptionManager;

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

@@ -64,8 +64,21 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
     abstract setHookRules(hookRules: Record<string, HookRule[]>): Promise<any>;
     abstract getHookRules(): Promise<Record<string, HookRule[]>>;
     abstract getAllSymbols(): Promise<Symbols>;
-    abstract setHookSignal(hook: HookSignal, transaction?: TransactionProvider): Promise<any>;
-    abstract getHookSignal(topic: string, resolved: string): Promise<string | undefined>;
+    /**
+     * Leg1: Attempts to set the hook signal. If a pending signal occupies
+     * the key (race condition), overwrites it and returns the pending data.
+     * When called with a transaction, queues the setnxex (no pending detection).
+     */
+    abstract setHookSignal(hook: HookSignal, transaction?: TransactionProvider): Promise<{
+        success: boolean;
+        pendingData?: string;
+    }>;
+    /**
+     * Leg2: Atomically gets the hook signal OR inserts a pending signal
+     * if no hook is registered yet (early signal). Returns the hook
+     * signal value, or undefined if we stored a pending signal instead.
+     */
+    abstract getHookSignal(topic: string, resolved: string, pendingData?: string, pendingExpire?: number): Promise<string | undefined>;
     abstract deleteHookSignal(topic: string, resolved: string): Promise<number | undefined>;
     abstract addTaskQueues(keys: string[]): Promise<void>;
     abstract getActiveTaskQueue(): Promise<string | null>;

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

@@ -10,6 +10,7 @@ export declare const KVTables: (context: PostgresStoreService) => {
     hashStringToInt(str: string): number;
     waitForTablesCreation(lockId: number, appName: string): Promise<void>;
     checkIfTablesExist(client: PostgresClientType, appName: string): Promise<boolean>;
+    migrate(client: PostgresClientType | PostgresPoolClientType, appName: string): Promise<void>;
     createTables(client: PostgresClientType | PostgresPoolClientType, appName: string): Promise<void>;
     getTableNames(appName: string): string[];
     getTableDefinitions(appName: string): Array<{

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

@@ -26,7 +26,8 @@ const KVTables = (context) => ({
             // First, check if tables already exist (no lock needed)
             const tablesExist = await this.checkIfTablesExist(client, appName);
             if (tablesExist) {
-                // Tables already exist, no need to acquire lock or create tables
+                // Tables exist; apply any pending migrations
+                await this.migrate(client, appName);
                 return;
             }
             // Tables don't exist, need to acquire lock and create them
@@ -128,6 +129,31 @@ const KVTables = (context) => ({
         const results = await Promise.all(checkTablePromises);
         return results.every((res) => res.rows[0].table !== null);
     },
+    async migrate(client, appName) {
+        const schemaName = context.storeClient.safeName(appName);
+        const jobsTable = `${schemaName}.jobs`;
+        // v0.14.5: track updated_at on job status changes
+        const { rows } = await client.query(`SELECT 1 FROM pg_trigger WHERE tgname = 'trg_update_jobs_updated_at' LIMIT 1`);
+        if (rows.length === 0) {
+            await client.query(`
+        CREATE OR REPLACE FUNCTION ${schemaName}.update_jobs_updated_at()
+        RETURNS TRIGGER AS $$
+        BEGIN
+          IF NEW.status <> OLD.status THEN
+            NEW.updated_at = NOW();
+          END IF;
+          RETURN NEW;
+        END;
+        $$ LANGUAGE plpgsql;
+      `);
+            await client.query(`
+        DROP TRIGGER IF EXISTS trg_update_jobs_updated_at ON ${jobsTable};
+        CREATE TRIGGER trg_update_jobs_updated_at
+        BEFORE UPDATE ON ${jobsTable}
+        FOR EACH ROW EXECUTE FUNCTION ${schemaName}.update_jobs_updated_at();
+      `);
+        }
+    },
     async createTables(client, appName) {
         try {
             await client.query('BEGIN');
@@ -302,6 +328,25 @@ const KVTables = (context) => ({
               CREATE TRIGGER trg_enforce_live_job_uniqueness
               BEFORE INSERT OR UPDATE ON ${fullTableName}
               FOR EACH ROW EXECUTE PROCEDURE ${schemaName}.enforce_live_job_uniqueness();
+            `);
+                        // Create function to update updated_at on status changes
+                        await client.query(`
+              CREATE OR REPLACE FUNCTION ${schemaName}.update_jobs_updated_at()
+              RETURNS TRIGGER AS $$
+              BEGIN
+                IF NEW.status <> OLD.status THEN
+                  NEW.updated_at = NOW();
+                END IF;
+                RETURN NEW;
+              END;
+              $$ LANGUAGE plpgsql;
+            `);
+                        // Create trigger for updated_at on job status changes
+                        await client.query(`
+              DROP TRIGGER IF EXISTS trg_update_jobs_updated_at ON ${fullTableName};
+              CREATE TRIGGER trg_update_jobs_updated_at
+              BEFORE UPDATE ON ${fullTableName}
+              FOR EACH ROW EXECUTE FUNCTION ${schemaName}.update_jobs_updated_at();
             `);
                         // Create the attributes table with partitioning
                         const attributesTableName = `${fullTableName}_attributes`;

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

@@ -115,8 +115,31 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     getTransitions(appVersion: AppVID): Promise<Transitions>;
     setHookRules(hookRules: Record<string, HookRule[]>): Promise<any>;
     getHookRules(): Promise<Record<string, HookRule[]>>;
-    setHookSignal(hook: HookSignal, transaction?: ProviderTransaction): Promise<any>;
-    getHookSignal(topic: string, resolved: string): Promise<string | undefined>;
+    /**
+     * Leg1: set hook signal, atomically detecting a pending signal.
+     *
+     * Standalone (no transaction): single CTE query that reads any existing
+     * pending value, then inserts the hook signal (overwriting pending or
+     * expired entries). Returns `{success, pendingData}` in one round trip.
+     *
+     * In a transaction: queues the setnxex; pending detection deferred.
+     */
+    setHookSignal(hook: HookSignal, transaction?: ProviderTransaction): Promise<{
+        success: boolean;
+        pendingData?: string;
+    }>;
+    /**
+     * Leg2: get hook signal OR atomically set a pending signal.
+     *
+     * When `pendingData` is provided and no hook signal exists, the
+     * pending value is inserted in the SAME SQL statement — no second
+     * round trip. This is the transactional edge that prevents the
+     * signal from being lost: by the time the query returns, the
+     * pending key is already visible to leg1's setnxex.
+     *
+     * When `pendingData` is omitted, behaves as a plain read.
+     */
+    getHookSignal(topic: string, resolved: string, pendingData?: string, pendingExpire?: number): Promise<string | undefined>;
     deleteHookSignal(topic: string, resolved: string): Promise<number | undefined>;
     addTaskQueues(keys: string[]): Promise<void>;
     getActiveTaskQueue(): Promise<string | null>;

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

@@ -754,16 +754,133 @@ class PostgresStoreService extends __1.StoreService {
             return patterns;
         }
     }
+    /**
+     * Leg1: set hook signal, atomically detecting a pending signal.
+     *
+     * Standalone (no transaction): single CTE query that reads any existing
+     * pending value, then inserts the hook signal (overwriting pending or
+     * expired entries). Returns `{success, pendingData}` in one round trip.
+     *
+     * In a transaction: queues the setnxex; pending detection deferred.
+     */
     async setHookSignal(hook, transaction) {
         const key = this.mintKey(key_1.KeyType.SIGNALS, { appId: this.appId });
         const { topic, resolved, jobId } = hook;
         const signalKey = `${topic}:${resolved}`;
-        await this.kvsql(transaction).setnxex(`${key}:${signalKey}`, jobId, Math.max(hook.expire, enums_1.HMSH_SIGNAL_EXPIRE));
+        const fullKey = `${key}:${signalKey}`;
+        const delay = Math.max(hook.expire, enums_1.HMSH_SIGNAL_EXPIRE);
+        if (transaction) {
+            await this.kvsql(transaction).setnxex(fullKey, jobId, delay);
+            return { success: true };
+        }
+        const kv = this.kvsql();
+        const tableName = kv.tableForKey(fullKey);
+        const storedKey = kv.storageKey(fullKey);
+        const sql = `
+      WITH pre AS (
+        SELECT value FROM ${tableName}
+        WHERE key = $1 AND (expiry IS NULL OR expiry > NOW())
+      ),
+      ins AS (
+        INSERT INTO ${tableName} (key, value, expiry)
+        VALUES ($1, $2, NOW() + INTERVAL '${delay} seconds')
+        ON CONFLICT (key) DO UPDATE
+          SET value = EXCLUDED.value, expiry = EXCLUDED.expiry
+          WHERE ${tableName}.expiry IS NULL
+            OR ${tableName}.expiry <= NOW()
+            OR ${tableName}.value LIKE '$pending::%'
+        RETURNING true as success
+      )
+      SELECT
+        COALESCE((SELECT success FROM ins), false) as success,
+        (SELECT value FROM pre) as existing_value
+    `;
+        try {
+            const res = await this.pgClient.query(sql, [storedKey, jobId]);
+            const row = res.rows[0] || {};
+            const success = row.success === true;
+            const existing = row.existing_value;
+            if (success && existing?.startsWith('$pending::')) {
+                return {
+                    success: true,
+                    pendingData: existing.slice('$pending::'.length),
+                };
+            }
+            return { success };
+        }
+        catch (error) {
+            if (error?.message?.includes('closed') ||
+                error?.message?.includes('queryable')) {
+                return { success: false };
+            }
+            throw error;
+        }
     }
-    async getHookSignal(topic, resolved) {
+    /**
+     * Leg2: get hook signal OR atomically set a pending signal.
+     *
+     * When `pendingData` is provided and no hook signal exists, the
+     * pending value is inserted in the SAME SQL statement — no second
+     * round trip. This is the transactional edge that prevents the
+     * signal from being lost: by the time the query returns, the
+     * pending key is already visible to leg1's setnxex.
+     *
+     * When `pendingData` is omitted, behaves as a plain read.
+     */
+    async getHookSignal(topic, resolved, pendingData, pendingExpire) {
         const key = this.mintKey(key_1.KeyType.SIGNALS, { appId: this.appId });
-        const response = await this.kvsql().get(`${key}:${topic}:${resolved}`);
-        return response ? response.toString() : undefined;
+        const fullKey = `${key}:${topic}:${resolved}`;
+        if (!pendingData) {
+            //plain read (used by deleteWebHookSignal path, tests, etc.)
+            const response = await this.kvsql().get(fullKey);
+            if (!response)
+                return undefined;
+            const value = response.toString();
+            if (value.startsWith('$pending::'))
+                return undefined;
+            return value;
+        }
+        //atomic get-or-set-pending: one round trip
+        const kv = this.kvsql();
+        const tableName = kv.tableForKey(fullKey);
+        const storedKey = kv.storageKey(fullKey);
+        const expire = pendingExpire || enums_1.HMSH_PENDING_SIGNAL_EXPIRE;
+        const pendingValue = `$pending::${pendingData}`;
+        const sql = `
+      WITH existing AS (
+        SELECT value FROM ${tableName}
+        WHERE key = $1 AND (expiry IS NULL OR expiry > NOW())
+      ),
+      pending AS (
+        INSERT INTO ${tableName} (key, value, expiry)
+        SELECT $1, $2, NOW() + INTERVAL '${expire} seconds'
+        WHERE NOT EXISTS (SELECT 1 FROM existing)
+        ON CONFLICT (key) DO UPDATE
+          SET value = EXCLUDED.value, expiry = EXCLUDED.expiry
+          WHERE ${tableName}.expiry IS NULL OR ${tableName}.expiry <= NOW()
+        RETURNING true as inserted
+      )
+      SELECT
+        (SELECT value FROM existing) as hook_value,
+        (SELECT inserted FROM pending) as pending_inserted
+    `;
+        try {
+            const res = await this.pgClient.query(sql, [storedKey, pendingValue]);
+            const row = res.rows[0] || {};
+            const hookValue = row.hook_value;
+            if (hookValue && !hookValue.startsWith('$pending::')) {
+                return hookValue;
+            }
+            //no hook signal; pending was inserted (or already existed)
+            return undefined;
+        }
+        catch (error) {
+            if (error?.message?.includes('closed') ||
+                error?.message?.includes('queryable')) {
+                return undefined;
+            }
+            throw error;
+        }
     }
     async deleteHookSignal(topic, resolved) {
         const key = this.mintKey(key_1.KeyType.SIGNALS, { appId: this.appId });

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

@@ -22,6 +22,7 @@ export declare abstract class StreamService<ClientProvider extends ProviderClien
         batchSize?: number;
         blockTimeout?: number;
         autoAck?: boolean;
+        reservationTimeout?: number;
         enableBackoff?: boolean;
         initialBackoff?: number;
         maxBackoff?: number;
@@ -41,6 +42,7 @@ export declare abstract class StreamService<ClientProvider extends ProviderClien
         maxRetries?: number;
         limit?: number;
     }): Promise<StreamMessage[]>;
+    reservationTimeout: number;
     abstract getStreamStats(streamName: string): Promise<StreamStats>;
     abstract getStreamDepth(streamName: string): Promise<number>;
     abstract getStreamDepths(streamName: {

package/build/services/stream/index.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamService = void 0;
 class StreamService {
     constructor(streamClient, storeClient, config = {}) {
+        // Adaptive reservation timeout — set by the consumption manager
+        // based on stream depth. Providers read this when reserving messages.
+        this.reservationTimeout = 30;
         this.streamClient = streamClient;
         this.storeClient = storeClient;
         this.config = config;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryMessages = exports.deadLetterMessages = exports.ackAndDelete = exports.deleteMessages = exports.acknowledgeMessages = exports.fetchMessages = exports.buildPublishSQL = exports.publishMessages = void 0;
+const enums_1 = require("../../../../modules/enums");
 const utils_1 = require("../../../../modules/utils");
 /**
  * Publish messages to a stream. Can be used within a transaction.
@@ -205,7 +206,7 @@ async function fetchMessages(client, tableName, streamName, isEngine, consumerNa
         while (retries < maxRetries) {
             retries++;
             const batchSize = options?.batchSize || 1;
-            const reservationTimeout = options?.reservationTimeout || 30;
+            const reservationTimeout = options?.reservationTimeout || enums_1.HMSH_RESERVATION_TIMEOUT_S;
             const res = await client.query(`UPDATE ${tableName}
          SET reserved_at = NOW(), reserved_by = $3
          WHERE id IN (

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

@@ -79,12 +79,12 @@ class PostgresStreamService extends index_1.StreamService {
     }
     async checkForMissedMessages() {
         await this.notificationManager.checkForMissedMessages(async (instance, consumer) => {
-            return await instance.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, enableBackoff: false, maxRetries: 1 });
+            return await instance.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, reservationTimeout: instance.reservationTimeout, enableBackoff: false, maxRetries: 1 });
         });
     }
     async fetchAndDeliverMessages(consumer) {
         try {
-            const messages = await this.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, enableBackoff: false, maxRetries: 1 });
+            const messages = await this.fetchMessages(consumer.streamName, consumer.groupName, consumer.consumerName, { batchSize: 10, reservationTimeout: this.reservationTimeout, enableBackoff: false, maxRetries: 1 });
             if (messages.length > 0) {
                 consumer.callback(messages);
             }

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

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishMessagesSecured = exports.deadLetterMessagesSecured = exports.ackAndDeleteSecured = exports.fetchMessagesSecured = void 0;
+const enums_1 = require("../../../../modules/enums");
 const utils_1 = require("../../../../modules/utils");
 const utils_2 = require("../../../../modules/utils");
 /**
@@ -19,7 +20,7 @@ async function fetchMessagesSecured(client, schema, streamName, consumerName, op
     const maxBackoff = options?.maxBackoff ?? 3000;
     const maxRetries = options?.maxRetries ?? 3;
     const batchSize = options?.batchSize || 1;
-    const reservationTimeout = options?.reservationTimeout || 30;
+    const reservationTimeout = options?.reservationTimeout || enums_1.HMSH_RESERVATION_TIMEOUT_S;
     let backoff = initialBackoff;
     let retries = 0;
     try {

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

@@ -29,7 +29,10 @@ declare class TaskService {
     processTimeHooks(timeEventCallback: (jobId: string, gId: string, activityId: string, type: WorkListTaskType) => Promise<void>, listKey?: string): Promise<void>;
     cancelCleanup(): void;
     getHookRule(topic: string): Promise<HookRule | undefined>;
-    registerWebHook(topic: string, context: JobState, dad: string, expire: number, transaction?: ProviderTransaction): Promise<string>;
+    registerWebHook(topic: string, context: JobState, dad: string, expire: number): Promise<{
+        jobId: string;
+        pending?: string;
+    }>;
     processWebHookSignal(topic: string, data: Record<string, unknown>): Promise<[string, string, string, string] | undefined>;
     deleteWebHookSignal(topic: string, data: Record<string, unknown>): Promise<number>;
     /**

package/build/services/task/index.js

@@ -134,7 +134,7 @@ class TaskService {
         const rules = await this.store.getHookRules();
         return rules?.[topic]?.[0];
     }
-    async registerWebHook(topic, context, dad, expire, transaction) {
+    async registerWebHook(topic, context, dad, expire) {
         const hookRule = await this.getHookRule(topic);
         if (hookRule) {
             const mapExpression = hookRule.conditions.match[0].expected;
@@ -150,8 +150,27 @@ class TaskService {
                 jobId: compositeJobKey,
                 expire,
             };
-            await this.store.setHookSignal(hook, transaction);
-            return jobId;
+            //called standalone (no transaction) so the single CTE query can
+            //atomically detect and return pending signal data on collision
+            const result = await this.store.setHookSignal(hook);
+            if (result.pendingData) {
+                this.logger.warn('task-signal-race-pending-consumed', {
+                    topic,
+                    resolved,
+                    jobId,
+                });
+                return { jobId, pending: result.pendingData };
+            }
+            if (!result.success) {
+                //setnxex failed but no pending signal; likely a retry where
+                //our own hook signal was already set. continue normally.
+                this.logger.debug('task-signal-hook-already-set', {
+                    topic,
+                    resolved,
+                    jobId,
+                });
+            }
+            return { jobId };
         }
         else {
             throw new Error('signaler.registerWebHook:error: hook rule not found');
@@ -165,10 +184,19 @@ class TaskService {
             const context = { $self: { hook: { data } }, $hook: { data } };
             const mapExpression = hookRule.conditions.match[0].actual;
             const resolved = pipe_1.Pipe.resolve(mapExpression, context);
-            const hookSignalId = await this.store.getHookSignal(topic, resolved);
+            //resolve $expire override from the signal data (e.g., '1h', '30d')
+            const pendingExpire = typeof data.$expire === 'string'
+                ? (0, utils_1.s)(data.$expire)
+                : enums_1.HMSH_PENDING_SIGNAL_EXPIRE;
+            //atomic: returns the hook signal, or stores a pending signal
+            //in the same SQL statement if no hook is registered yet
+            const hookSignalId = await this.store.getHookSignal(topic, resolved, JSON.stringify(data), pendingExpire);
             if (!hookSignalId) {
-                //messages can be double-processed; not an issue; return `undefined`
-                //users can also provide a bogus topic; not an issue; return `undefined`
+                this.logger.warn('task-signal-race-pending-stored', {
+                    topic,
+                    resolved,
+                    expire: pendingExpire,
+                });
                 return undefined;
             }
             //`aid` is part of composite key, but the hook `topic` is its public interface;

package/build/types/dba.d.ts

@@ -103,6 +103,15 @@ export interface PruneOptions {
      * @default false
      */
     keepHmark?: boolean;
+    /**
+     * If true, hard-deletes expired rows from `signal_registry`.
+     * These include consumed hook signals and stale pending signals
+     * (signals that arrived before hook registration but were never
+     * claimed). All signal_registry entries have a natural `expiry`
+     * column; this operation removes rows whose expiry has passed.
+     * @default true
+     */
+    signals?: boolean;
 }
 /**
  * Result returned by `DBA.prune()`, providing deletion
@@ -123,4 +132,6 @@ export interface PruneResult {
     transient: number;
     /** Number of jobs marked as pruned (pruned_at set) */
     marked: number;
+    /** Number of expired signal_registry rows hard-deleted */
+    signals: number;
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.14.4",
+  "version": "0.14.6",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
-  "homepage": "https://github.com/hotmeshio/sdk-typescript/",
+  "homepage": "https://docs.hotmesh.io/",
   "publishConfig": {
     "access": "public"
   },
@@ -30,6 +30,7 @@
     "test:durable:postgres": "HMSH_LOGLEVEL=info vitest run tests/durable",
     "test:durable:basic": "HMSH_LOGLEVEL=info vitest run tests/durable/basic/postgres.test.ts",
     "test:durable:collision": "vitest run tests/durable/collision/postgres.test.ts",
+    "test:durable:contention": "vitest run tests/durable/contention/postgres.test.ts",
     "test:durable:fatal": "vitest run tests/durable/fatal",
     "test:durable:goodbye": "HMSH_LOGLEVEL=debug vitest run tests/durable/goodbye/postgres.test.ts",
     "test:durable:interceptor": "HMSH_LOGLEVEL=info vitest run tests/durable/interceptor/postgres.test.ts",