@hotmeshio/hotmesh 0.25.0 → 0.25.2

package/build/package.json

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

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

@@ -272,6 +272,13 @@ declare class Hook extends Activity {
     doesHook(): boolean;
     doHook(telemetry: TelemetryService): Promise<void>;
     private addEscalationToTransaction;
+    /**
+     * Derive signal_key from the hook rule's expected condition — the same
+     * value registerWebHook stores as the signal lookup key. Used by the Leg1
+     * escalation INSERT and by the timeout path's expiry UPDATE, so both sides
+     * address the identical row.
+     */
+    private deriveEscalationSignalKey;
     /**
      * Re-publishes a pending signal as a WEBHOOK stream message so the
      * normal leg2 dispatch path processes it. Called when leg1's
@@ -308,5 +315,14 @@ declare class Hook extends Activity {
     } | void>;
     processWebHookEvent(status?: StreamStatus, code?: StreamCode): Promise<JobStatus | void>;
     processTimeHookEvent(jobId: string): Promise<JobStatus | void>;
+    /**
+     * The timeout won the race: transition the wait's escalation row
+     * `pending → expired` so the worklist stops offering work whose workflow
+     * has already resumed with `false`, and a late resolve fails as
+     * already-expired instead of delivering a payload into the void. The
+     * UPDATE is guarded by status='pending' — when the signal won (row
+     * already resolved) or the wait carried no escalation, it is a no-op.
+     */
+    private expireEscalationOnTimeout;
 }
 export { Hook };

package/build/services/activities/hook.js

@@ -437,12 +437,7 @@ class Hook extends activity_1.Activity {
         if (params.role == null && params.type == null &&
             params.priority == null && params.metadata == null)
             return null;
-        // Derive signal_key from the hook rule's expected condition — the same
-        // value registerWebHook stores as the signal lookup key.
-        const hookRule = await this.getHookRule(this.config.hook.topic);
-        const signalKey = hookRule?.conditions?.match?.[0]?.expected
-            ? pipe_1.Pipe.resolve(hookRule.conditions.match[0].expected, this.context)
-            : jid;
+        const signalKey = await this.deriveEscalationSignalKey();
         store.addEscalationToTransaction({
             namespace,
             appId,
@@ -453,6 +448,18 @@ class Hook extends activity_1.Activity {
         }, transaction);
         return signalKey;
     }
+    /**
+     * Derive signal_key from the hook rule's expected condition — the same
+     * value registerWebHook stores as the signal lookup key. Used by the Leg1
+     * escalation INSERT and by the timeout path's expiry UPDATE, so both sides
+     * address the identical row.
+     */
+    async deriveEscalationSignalKey() {
+        const hookRule = await this.getHookRule(this.config.hook.topic);
+        return hookRule?.conditions?.match?.[0]?.expected
+            ? pipe_1.Pipe.resolve(hookRule.conditions.match[0].expected, this.context)
+            : this.context.metadata.jid;
+    }
     /**
      * Re-publishes a pending signal as a WEBHOOK stream message so the
      * normal leg2 dispatch path processes it. Called when leg1's
@@ -489,7 +496,16 @@ class Hook extends activity_1.Activity {
     }
     async getHookRule(topic) {
         const rules = await this.store.getHookRules();
-        return rules?.[topic]?.[0];
+        const forTopic = rules?.[topic];
+        if (!forTopic?.length)
+            return undefined;
+        // A topic may carry one rule per waiter activity — the durable factory
+        // registers `waiter` and `signaler_waiter` on the same wait topic. Select
+        // the rule that targets THIS activity: the positional first rule addresses
+        // a sibling branch for every activity but its own, so its expected-pipe
+        // resolves against output that does not exist in this flow (which is how
+        // execHook-context waits were writing signal_key-less escalation rows).
+        return (forTopic.find((rule) => rule.to === this.metadata.aid) ?? forTopic[0]);
     }
     /**
      * Register the time hook (sleep) inside the Leg1 transaction.
@@ -629,8 +645,74 @@ class Hook extends activity_1.Activity {
                     error: e.message,
                 });
             }
+            await this.expireEscalationOnTimeout();
         }
         await this.processEvent(stream_1.StreamStatus.SUCCESS, 200, 'hook');
     }
+    /**
+     * The timeout won the race: transition the wait's escalation row
+     * `pending → expired` so the worklist stops offering work whose workflow
+     * has already resumed with `false`, and a late resolve fails as
+     * already-expired instead of delivering a payload into the void. The
+     * UPDATE is guarded by status='pending' — when the signal won (row
+     * already resolved) or the wait carried no escalation, it is a no-op.
+     */
+    async expireEscalationOnTimeout() {
+        if (!this.config.escalation)
+            return;
+        const store = this.store;
+        if (typeof store.expireEscalationBySignalKey !== 'function')
+            return;
+        // Hydration here is THROWAWAY. getState() REPLACES this.context with
+        // restored job state, which does not carry the per-message dimensional
+        // address (dad) — the stream message is its only carrier for this leg.
+        // processEvent must receive the pristine dispatch state (verifyReentry
+        // hydrates for itself, reading dad from context.metadata), so snapshot
+        // everything getState mutates — the context reference, metadata.dad,
+        // and leg — and restore them on every exit path. Without this, a wait
+        // executing below the root (any dimension) crashes Leg2 notarization.
+        const dispatchContext = this.context;
+        const dispatchDad = this.metadata.dad;
+        const dispatchLeg = this.leg;
+        try {
+            // Hydrate job state so the signal-key pipe expression resolves to the
+            // same value Leg1 stored on the row.
+            this.setLeg(2);
+            await this.getState();
+            const appId = this.engine.appId;
+            const namespace = this.engine.namespace ?? appId;
+            const signalKey = await this.deriveEscalationSignalKey();
+            const row = await store.expireEscalationBySignalKey(signalKey, namespace, appId);
+            if (row?.id && store.eventsPublish) {
+                const ts = new Date().toISOString();
+                const updatedAt = row.updated_at ? new Date(row.updated_at).toISOString() : ts;
+                void Promise.resolve(store.eventsPublish({
+                    event_id: `${row.id}:expired:${updatedAt}`,
+                    type: `system.escalation.${row.id}.expired`,
+                    ts,
+                    namespace: row.namespace ?? namespace,
+                    app_id: row.app_id ?? appId,
+                    workflow_id: row.workflow_id ?? undefined,
+                    topic: row.topic ?? undefined,
+                    origin_id: row.origin_id ?? undefined,
+                    parent_id: row.parent_id ?? undefined,
+                    trace_id: row.trace_id ?? undefined,
+                    span_id: row.span_id ?? undefined,
+                    data: row,
+                })).catch(() => { });
+            }
+        }
+        catch (e) {
+            this.logger.debug('hook-timeout-escalation-expire', {
+                topic: this.config.hook?.topic,
+                error: e.message,
+            });
+        }
+        finally {
+            this.context = dispatchContext;
+            this.metadata.dad = dispatchDad;
+            this.setLeg(dispatchLeg);
+        }
+    }
 }
 exports.Hook = Hook;

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

@@ -61,8 +61,10 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  *     description: 'Approve or reject the regional order',
  *     metadata: { orderId, region },
  *     envelope: { instructions: 'Review the attached order' },
+ *     timeout: '72h',   // SLA: resume with false + expire the row if unresolved
  *   },
  * );
+ * if (decision === false) return 'auto-rejected-sla';  // row is now status='expired'
  *
  * // Elsewhere: list, claim, then resolve (resumes the workflow)
  * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
@@ -70,6 +72,15 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  * await client.escalations.resolve({ id: item.id, resolverPayload: { approved: true } });
  * ```
  *
+ * ## Placement: call escalation-bearing waits from main workflow code
+ *
+ * The resolve/signal delivery pipeline routes to the main flow's waiter.
+ * Inside a hook function (`execHook`), an escalation-bearing wait writes its
+ * row and honors `timeout` (the row expires and the hook resumes with
+ * `false`), while resolution delivery targets the main flow — so structure
+ * SLA-gated human waits in the workflow body and let hook functions report
+ * back via `signal()`.
+ *
  * ## Fan-in: wait for multiple signals in parallel
  *
  * ```typescript
@@ -95,9 +106,13 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  * @param signalId - A unique signal identifier shared by the sender and receiver.
  * @param timeoutOrConfig - Optional timeout string (e.g. `'30s'`, `'24h'`) OR a
  *   {@link ConditionQueueConfig} that writes one row to `public.hmsh_escalations`
- *   atomically at suspension time. Cannot specify both; use the config object's
- *   `expiresAt` field for deadline enforcement when an escalation is involved.
- * @returns The signal payload, `false` if a timeout string was given and it expired,
- *   or `null` if the escalation was cancelled via `client.escalations.cancel()`.
+ *   atomically at suspension time. For an escalation-bearing wait with an SLA,
+ *   set the config's `timeout` field — the wait arms the same resume timer as
+ *   the string form, and when the timer wins the escalation row transitions
+ *   `pending → expired` so a late resolve fails as already-expired. (`expiresAt`
+ *   is display metadata on the row only; it arms nothing.)
+ * @returns The signal payload, `false` when a timeout (string form or
+ *   `config.timeout`) expired first, or `null` if the escalation was cancelled
+ *   via `client.escalations.cancel()`.
  */
 export declare function condition<T>(signalId: string, timeoutOrConfig?: string | ConditionQueueConfig): Promise<T | false | null>;

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

@@ -66,8 +66,10 @@ const didRun_1 = require("./didRun");
  *     description: 'Approve or reject the regional order',
  *     metadata: { orderId, region },
  *     envelope: { instructions: 'Review the attached order' },
+ *     timeout: '72h',   // SLA: resume with false + expire the row if unresolved
  *   },
  * );
+ * if (decision === false) return 'auto-rejected-sla';  // row is now status='expired'
  *
  * // Elsewhere: list, claim, then resolve (resumes the workflow)
  * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
@@ -75,6 +77,15 @@ const didRun_1 = require("./didRun");
  * await client.escalations.resolve({ id: item.id, resolverPayload: { approved: true } });
  * ```
  *
+ * ## Placement: call escalation-bearing waits from main workflow code
+ *
+ * The resolve/signal delivery pipeline routes to the main flow's waiter.
+ * Inside a hook function (`execHook`), an escalation-bearing wait writes its
+ * row and honors `timeout` (the row expires and the hook resumes with
+ * `false`), while resolution delivery targets the main flow — so structure
+ * SLA-gated human waits in the workflow body and let hook functions report
+ * back via `signal()`.
+ *
  * ## Fan-in: wait for multiple signals in parallel
  *
  * ```typescript
@@ -100,14 +111,21 @@ const didRun_1 = require("./didRun");
  * @param signalId - A unique signal identifier shared by the sender and receiver.
  * @param timeoutOrConfig - Optional timeout string (e.g. `'30s'`, `'24h'`) OR a
  *   {@link ConditionQueueConfig} that writes one row to `public.hmsh_escalations`
- *   atomically at suspension time. Cannot specify both; use the config object's
- *   `expiresAt` field for deadline enforcement when an escalation is involved.
- * @returns The signal payload, `false` if a timeout string was given and it expired,
- *   or `null` if the escalation was cancelled via `client.escalations.cancel()`.
+ *   atomically at suspension time. For an escalation-bearing wait with an SLA,
+ *   set the config's `timeout` field — the wait arms the same resume timer as
+ *   the string form, and when the timer wins the escalation row transitions
+ *   `pending → expired` so a late resolve fails as already-expired. (`expiresAt`
+ *   is display metadata on the row only; it arms nothing.)
+ * @returns The signal payload, `false` when a timeout (string form or
+ *   `config.timeout`) expired first, or `null` if the escalation was cancelled
+ *   via `client.escalations.cancel()`.
  */
 async function condition(signalId, timeoutOrConfig) {
-    const timeout = typeof timeoutOrConfig === 'string' ? timeoutOrConfig : undefined;
+    // A string arg is a bare timeout; a config object may carry its own
+    // `timeout` field — the engine's waiter block accepts duration and
+    // queueConfig together (one wait: escalation row + resume timer).
     const queueConfig = timeoutOrConfig && typeof timeoutOrConfig === 'object' ? timeoutOrConfig : undefined;
+    const timeout = typeof timeoutOrConfig === 'string' ? timeoutOrConfig : queueConfig?.timeout;
     const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('wait');
     (0, cancellationScope_1.checkCancellation)();
     if (didRunAlready) {

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

@@ -256,6 +256,14 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     createEscalationForMigration(params: import('../../../../types/hmsh_escalations').MigrateEscalationParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     getEscalation(id: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     getEscalationBySignalKey(signalKey: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
+    /**
+     * Transition a wait's escalation row to `expired` when its resume timer
+     * fires first (`condition(signalId, { ..., timeout })`). Guarded by
+     * `status = 'pending'`: a signal that won the race already resolved the
+     * row and is never touched. Returns the expired row, or null when no
+     * pending row carried the key (signal won, or the wait had no escalation).
+     */
+    expireEscalationBySignalKey(signalKey: string, namespace?: string, appId?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     private _escalationFilterConditions;
     listEscalations(params?: import('../../../../types/hmsh_escalations').ListEscalationsParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry[]>;
     countEscalations(params?: import('../../../../types/hmsh_escalations').ListEscalationsParams): Promise<number>;

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

@@ -1540,6 +1540,30 @@ class PostgresStoreService extends __1.StoreService {
         const result = await this.pgClient.query(`SELECT * FROM public.hmsh_escalations WHERE signal_key = $1${namespace ? ' AND namespace = $2' : ''}`, namespace ? [signalKey, namespace] : [signalKey]);
         return result.rows[0] ?? null;
     }
+    /**
+     * Transition a wait's escalation row to `expired` when its resume timer
+     * fires first (`condition(signalId, { ..., timeout })`). Guarded by
+     * `status = 'pending'`: a signal that won the race already resolved the
+     * row and is never touched. Returns the expired row, or null when no
+     * pending row carried the key (signal won, or the wait had no escalation).
+     */
+    async expireEscalationBySignalKey(signalKey, namespace, appId) {
+        const values = [signalKey];
+        let clause = '';
+        if (namespace) {
+            values.push(namespace);
+            clause += ` AND namespace = $${values.length}`;
+        }
+        if (appId) {
+            values.push(appId);
+            clause += ` AND app_id = $${values.length}`;
+        }
+        const result = await this.pgClient.query(`UPDATE public.hmsh_escalations
+       SET status = 'expired', updated_at = NOW()
+       WHERE signal_key = $1${clause} AND status = 'pending'
+       RETURNING *`, values);
+        return result.rows[0] ?? null;
+    }
     _escalationFilterConditions(params, startIdx = 1) {
         const { namespace, role, roles, type, subtype, entity, status, assignedTo, workflowId, originId, available, priority, metadata, ids, taskId } = params;
         const conditions = [];
@@ -1791,6 +1815,14 @@ class PostgresStoreService extends __1.StoreService {
                 await this.pgClient.query('ROLLBACK');
                 return { ok: false, reason: 'already-cancelled' };
             }
+            if (status === 'expired') {
+                // The wait's SLA timer fired first and the workflow resumed with
+                // false — the resolver payload has nowhere to go. Name it, so the
+                // operator learns the deadline passed rather than believing the
+                // resolution landed.
+                await this.pgClient.query('ROLLBACK');
+                return { ok: false, reason: 'already-expired' };
+            }
             const updateResult = await this.pgClient.query(`UPDATE public.hmsh_escalations
          SET status = 'resolved', resolved_at = NOW(), resolver_payload = $2,
              metadata = CASE WHEN $3::jsonb IS NOT NULL

package/build/types/hmsh_escalations.d.ts

@@ -17,6 +17,14 @@ export interface ConditionQueueConfig {
     /** Unindexed display/form context for resolver UIs */
     envelope?: Record<string, unknown>;
     expiresAt?: Date;
+    /**
+     * SLA timer for the wait itself (e.g. `'30m'`, `'24h'`). Arms the same
+     * resume timer as `condition(signalId, '30m')`: when it fires first, the
+     * workflow resumes with `false` and the escalation row transitions
+     * `pending → expired` (a later resolve fails as already-expired). A signal
+     * that arrives first resolves normally and the timer is inert.
+     */
+    timeout?: string;
 }
 export interface EscalationEntry {
     id: string;
@@ -95,7 +103,7 @@ export type ResolveEscalationResult = {
     entry: EscalationEntry;
 } | {
     ok: false;
-    reason: 'not-found' | 'already-resolved' | 'already-cancelled';
+    reason: 'not-found' | 'already-resolved' | 'already-cancelled' | 'already-expired';
 };
 export type ReleaseEscalationResult = {
     ok: true;

package/package.json

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