@hotmeshio/hotmesh 0.14.4 → 0.14.5

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;

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_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_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 = 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;

package/build/package.json

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

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/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/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,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.14.4",
+  "version": "0.14.5",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",