@hotmeshio/hotmesh 0.24.1 → 0.25.1

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.24.1",
+    "version": "0.25.1",
     "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
@@ -629,8 +636,59 @@ 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;
+        try {
+            // The TIMEHOOK dispatch context carries metadata only — 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,
+            });
+        }
+    }
 }
 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' });
@@ -95,9 +97,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' });
@@ -100,14 +102,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/kvtables.js

@@ -315,6 +315,26 @@ const KVTables = (context) => ({
       CREATE INDEX IF NOT EXISTS idx_hmsh_esc_task
         ON public.hmsh_escalations(task_id)
         WHERE task_id IS NOT NULL;
+    `);
+        // v0.25.0: escalationStats indexes. Callers filter by role (optional) and
+        // namespace (optional) — never namespace-first — so the pending index leads
+        // with role and the two windowed indexes lead with their time column: the
+        // scan stays window-bounded even for unfiltered (admin) calls. Trailing
+        // columns cover every column the stats aggregates touch, keeping each of
+        // the three CTE scans index-only.
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_stats_pending
+        ON public.hmsh_escalations(role, type, assigned_to, assigned_until, namespace)
+        WHERE status = 'pending';
+    `);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_stats_created
+        ON public.hmsh_escalations(created_at, role, namespace);
+    `);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_stats_resolved
+        ON public.hmsh_escalations(resolved_at, type, role, namespace)
+        WHERE status = 'resolved';
     `);
         await client.query('COMMIT');
     },
@@ -440,6 +460,23 @@ const KVTables = (context) => ({
               CREATE INDEX IF NOT EXISTS idx_hmsh_esc_task
                 ON public.hmsh_escalations(task_id)
                 WHERE task_id IS NOT NULL;
+            `);
+                        // escalationStats indexes: role/time-led so aggregate scans stay
+                        // bounded (backlog or window) and index-only. See migrate() for
+                        // the column-order rationale.
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsh_esc_stats_pending
+                ON public.hmsh_escalations(role, type, assigned_to, assigned_until, namespace)
+                WHERE status = 'pending';
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsh_esc_stats_created
+                ON public.hmsh_escalations(created_at, role, namespace);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsh_esc_stats_resolved
+                ON public.hmsh_escalations(resolved_at, type, role, namespace)
+                WHERE status = 'resolved';
             `);
                         break;
                     case 'relational_connection':

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
@@ -2051,45 +2083,65 @@ class PostgresStoreService extends __1.StoreService {
             queryParams.push(namespace);
         if (roles?.length)
             queryParams.push(roles);
+        // Three bounded sources instead of one all-history scan (v0.25.0):
+        //   backlog  — status='pending' partial (bounded by queue depth, never history)
+        //   created  — created_at window range (all statuses)
+        //   resolved — status='resolved' + resolved_at window range
+        // Totals derive from the grouped CTEs (NULL role/type groups included, so
+        // totals match the pre-0.25.0 all-row counts); NULL groups are excluded
+        // only from the by_role/by_type rollups, as before. resolved_at is only
+        // ever set alongside status='resolved' (and never survives a transition
+        // back to pending), so the status predicate is a pure index enabler.
+        // Roles/types with no pending rows and no window activity no longer emit
+        // zero-count rollup entries.
         const result = await this.pgClient.query(`
-      WITH base AS (
-        SELECT * FROM public.hmsh_escalations
-        WHERE true ${nsClause} ${rolClause}
-      ),
-      totals AS (
-        SELECT
-          COUNT(*) FILTER (WHERE status = 'pending')::int AS pending,
-          COUNT(*) FILTER (WHERE status = 'pending'
-            AND assigned_to IS NOT NULL
-            AND assigned_until IS NOT NULL AND assigned_until > NOW())::int AS claimed,
-          COUNT(*) FILTER (WHERE created_at  >= NOW() - ($1 * INTERVAL '1 hour'))::int AS created,
-          COUNT(*) FILTER (WHERE resolved_at >= NOW() - ($1 * INTERVAL '1 hour'))::int AS resolved
-        FROM base
-      ),
-      by_role AS (
+      WITH pending_by_role AS (
         SELECT role,
-          COUNT(*) FILTER (WHERE status = 'pending')::int AS pending,
-          COUNT(*) FILTER (WHERE status = 'pending'
-            AND assigned_to IS NOT NULL
+          COUNT(*)::int AS pending,
+          COUNT(*) FILTER (WHERE assigned_to IS NOT NULL
             AND assigned_until IS NOT NULL AND assigned_until > NOW())::int AS claimed
-        FROM base WHERE role IS NOT NULL
+        FROM public.hmsh_escalations
+        WHERE status = 'pending' ${nsClause} ${rolClause}
         GROUP BY role
       ),
-      by_type AS (
+      pending_by_type AS (
         SELECT type,
-          COUNT(*) FILTER (WHERE status = 'pending')::int AS pending,
-          COUNT(*) FILTER (WHERE status = 'pending'
-            AND assigned_to IS NOT NULL
-            AND assigned_until IS NOT NULL AND assigned_until > NOW())::int AS claimed,
-          COUNT(*) FILTER (WHERE resolved_at >= NOW() - ($1 * INTERVAL '1 hour'))::int AS resolved
-        FROM base WHERE type IS NOT NULL
+          COUNT(*)::int AS pending,
+          COUNT(*) FILTER (WHERE assigned_to IS NOT NULL
+            AND assigned_until IS NOT NULL AND assigned_until > NOW())::int AS claimed
+        FROM public.hmsh_escalations
+        WHERE status = 'pending' ${nsClause} ${rolClause}
+        GROUP BY type
+      ),
+      created_agg AS (
+        SELECT COUNT(*)::int AS created
+        FROM public.hmsh_escalations
+        WHERE created_at >= NOW() - ($1 * INTERVAL '1 hour') ${nsClause} ${rolClause}
+      ),
+      resolved_by_type AS (
+        SELECT type, COUNT(*)::int AS resolved
+        FROM public.hmsh_escalations
+        WHERE status = 'resolved'
+          AND resolved_at >= NOW() - ($1 * INTERVAL '1 hour') ${nsClause} ${rolClause}
         GROUP BY type
       )
       SELECT
-        t.pending, t.claimed, t.created, t.resolved,
-        COALESCE((SELECT json_agg(json_build_object('role',role,'pending',pending,'claimed',claimed)) FROM by_role), '[]'::json) AS by_role,
-        COALESCE((SELECT json_agg(json_build_object('type',type,'pending',pending,'claimed',claimed,'resolved',resolved)) FROM by_type), '[]'::json) AS by_type
-      FROM totals t
+        COALESCE((SELECT SUM(pending)::int  FROM pending_by_role), 0)  AS pending,
+        COALESCE((SELECT SUM(claimed)::int  FROM pending_by_role), 0)  AS claimed,
+        (SELECT created FROM created_agg)                              AS created,
+        COALESCE((SELECT SUM(resolved)::int FROM resolved_by_type), 0) AS resolved,
+        COALESCE((SELECT json_agg(json_build_object('role',role,'pending',pending,'claimed',claimed))
+          FROM pending_by_role WHERE role IS NOT NULL), '[]'::json) AS by_role,
+        COALESCE((SELECT json_agg(json_build_object('type',t.type,'pending',t.pending,'claimed',t.claimed,'resolved',t.resolved))
+          FROM (
+            SELECT COALESCE(p.type, r.type) AS type,
+                   COALESCE(p.pending, 0)   AS pending,
+                   COALESCE(p.claimed, 0)   AS claimed,
+                   COALESCE(r.resolved, 0)  AS resolved
+            FROM pending_by_type p
+            FULL OUTER JOIN resolved_by_type r ON r.type = p.type
+            WHERE COALESCE(p.type, r.type) IS NOT NULL
+          ) t), '[]'::json) AS by_type
     `, queryParams);
         const row = result.rows[0];
         return {

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.24.1",
+  "version": "0.25.1",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",