@hotmeshio/hotmesh 0.23.0 → 0.25.0

package/build/package.json

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

package/build/services/durable/worker.js

@@ -885,7 +885,12 @@ class WorkerService {
                             code: enums_1.HMSH_CODE_DURABLE_ALL,
                             items: [...interruptionRegistry],
                             size: interruptionRegistry.length,
-                            workflowDimension: workflowDimension || '',
+                            // Use the items' execution dimension (all items in one Promise.all share it),
+                            // not the raw input dimension. In a continued generation (post-continueAsNew)
+                            // the effective dimension is the generation prefix `$N`, which the items carry
+                            // but `workflowInput.workflowDimension` does not — mirrors the single-condition
+                            // path above so the collator's harvested markers land where condition() replays.
+                            workflowDimension: interruptionRegistry[0].workflowDimension || workflowDimension || '',
                             index: execIndex,
                             originJobId: originJobId || workflowId,
                             parentWorkflowId: workflowId,

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

@@ -143,11 +143,21 @@ export declare class EscalationClientService {
      * durable proof. Signal delivery is best-effort post-commit — the resolved
      * row is the recovery record for any missed delivery. Returns the updated
      * row as `entry` on success.
+     *
+     * Pass `params.metadata` to merge the resolution outcome ("what actually
+     * happened") into the row's GIN-indexed `metadata` in the same atomic UPDATE,
+     * making it `@>`-queryable alongside the creation metadata ("what was
+     * intended"). This is distinct from `resolverPayload`, which is delivered to
+     * the waiting workflow as `condition()`'s return value and is not GIN-indexed.
      */
     resolve(params: ResolveEscalationParams, namespace?: string): Promise<ResolveEscalationResult>;
     /**
      * Resolves the highest-priority matching escalation by metadata filter,
      * then delivers its signal. Same transaction + WHERE guard semantics as `resolve()`.
+     *
+     * The `key`/`value` are the *selector* used to find the row; pass
+     * `params.metadata` to additionally merge a resolution patch into that row's
+     * GIN-indexed `metadata` in the same atomic UPDATE. See {@link resolve}.
      */
     resolveByMetadata(params: ResolveByMetadataParams, namespace?: string): Promise<ResolveEscalationResult>;
     /**
@@ -182,6 +192,10 @@ export declare class EscalationClientService {
      * Bulk-resolves pending escalations by id-set. No signal delivery — intended
      * for redirect-to-triage flows where no workflow is waiting. Returns the
      * resolved rows.
+     *
+     * Pass `params.metadata` to merge a resolution patch into every winning
+     * (still-pending) row's GIN-indexed `metadata` in the single atomic UPDATE.
+     * See {@link resolve}.
      */
     resolveMany(params: ResolveManyParams): Promise<EscalationEntry[]>;
     /**

package/build/services/escalations/client.js

@@ -281,12 +281,18 @@ class EscalationClientService {
      * durable proof. Signal delivery is best-effort post-commit — the resolved
      * row is the recovery record for any missed delivery. Returns the updated
      * row as `entry` on success.
+     *
+     * Pass `params.metadata` to merge the resolution outcome ("what actually
+     * happened") into the row's GIN-indexed `metadata` in the same atomic UPDATE,
+     * making it `@>`-queryable alongside the creation metadata ("what was
+     * intended"). This is distinct from `resolverPayload`, which is delivered to
+     * the waiting workflow as `condition()`'s return value and is not GIN-indexed.
      */
     async resolve(params, namespace) {
         const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
         const hm = await this._engine(null, ns);
         const store = hm.engine.store;
-        const dbResult = await store.resolveEscalation({ id: params.id, resolverPayload: params.resolverPayload });
+        const dbResult = await store.resolveEscalation({ id: params.id, resolverPayload: params.resolverPayload, metadata: params.metadata });
         if (!dbResult.ok)
             return dbResult;
         if (dbResult.signalKey) {
@@ -301,12 +307,16 @@ class EscalationClientService {
     /**
      * Resolves the highest-priority matching escalation by metadata filter,
      * then delivers its signal. Same transaction + WHERE guard semantics as `resolve()`.
+     *
+     * The `key`/`value` are the *selector* used to find the row; pass
+     * `params.metadata` to additionally merge a resolution patch into that row's
+     * GIN-indexed `metadata` in the same atomic UPDATE. See {@link resolve}.
      */
     async resolveByMetadata(params, namespace) {
         const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
         const hm = await this._engine(null, ns);
         const store = hm.engine.store;
-        const dbResult = await store.resolveEscalationByMetadata({ key: params.key, value: params.value, resolverPayload: params.resolverPayload, roles: params.roles });
+        const dbResult = await store.resolveEscalationByMetadata({ key: params.key, value: params.value, resolverPayload: params.resolverPayload, roles: params.roles, metadata: params.metadata });
         if (!dbResult.ok)
             return dbResult;
         if (dbResult.signalKey) {
@@ -366,6 +376,10 @@ class EscalationClientService {
      * Bulk-resolves pending escalations by id-set. No signal delivery — intended
      * for redirect-to-triage flows where no workflow is waiting. Returns the
      * resolved rows.
+     *
+     * Pass `params.metadata` to merge a resolution patch into every winning
+     * (still-pending) row's GIN-indexed `metadata` in the single atomic UPDATE.
+     * See {@link resolve}.
      */
     async resolveMany(params) {
         const hm = await this._engine(null, params.namespace);

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.js

@@ -1769,8 +1769,11 @@ class PostgresStoreService extends __1.StoreService {
         return { ok: true, entry: row.entry_json };
     }
     async resolveEscalation(params) {
-        const { id, namespace, resolverPayload } = params;
+        const { id, namespace, resolverPayload, metadata } = params;
         const payloadJson = resolverPayload ? JSON.stringify(resolverPayload) : null;
+        // metaJson is bound at a fixed index; the CASE no-ops when null so resolution
+        // can merge into the GIN-indexed metadata without disturbing the param layout.
+        const metaJson = metadata ? JSON.stringify(metadata) : null;
         // Explicit transaction: FOR UPDATE locks the row; WHERE guard on UPDATE is the TOCTOU
         // barrier — a concurrent caller whose UPDATE matches 0 rows sees 'already-resolved'.
         // On crash before COMMIT neither write lands; on crash after COMMIT both are durable.
@@ -1789,9 +1792,13 @@ class PostgresStoreService extends __1.StoreService {
                 return { ok: false, reason: 'already-cancelled' };
             }
             const updateResult = await this.pgClient.query(`UPDATE public.hmsh_escalations
-         SET status = 'resolved', resolved_at = NOW(), resolver_payload = $2, updated_at = NOW()
-         WHERE id = $1 ${namespace ? 'AND namespace = $3' : ''} AND status = 'pending'
-         RETURNING *`, namespace ? [id, payloadJson, namespace] : [id, payloadJson]);
+         SET status = 'resolved', resolved_at = NOW(), resolver_payload = $2,
+             metadata = CASE WHEN $3::jsonb IS NOT NULL
+                             THEN COALESCE(metadata, '{}'::jsonb) || $3::jsonb
+                             ELSE metadata END,
+             updated_at = NOW()
+         WHERE id = $1 ${namespace ? 'AND namespace = $4' : ''} AND status = 'pending'
+         RETURNING *`, namespace ? [id, payloadJson, metaJson, namespace] : [id, payloadJson, metaJson]);
             if (!updateResult.rows[0]) {
                 await this.pgClient.query('ROLLBACK');
                 return { ok: false, reason: 'already-resolved' };
@@ -1805,9 +1812,10 @@ class PostgresStoreService extends __1.StoreService {
         }
     }
     async resolveEscalationByMetadata(params) {
-        const { key, value, namespace, resolverPayload, roles } = params;
+        const { key, value, namespace, resolverPayload, roles, metadata } = params;
         const filter = JSON.stringify({ [key]: value });
         const payloadJson = resolverPayload ? JSON.stringify(resolverPayload) : null;
+        const metaJson = metadata ? JSON.stringify(metadata) : null;
         await this.pgClient.query('BEGIN');
         try {
             const lockResult = await this.pgClient.query(`SELECT id, signal_key, topic, status FROM public.hmsh_escalations
@@ -1827,9 +1835,13 @@ class PostgresStoreService extends __1.StoreService {
                 return { ok: false, reason: 'already-cancelled' };
             }
             const updateResult = await this.pgClient.query(`UPDATE public.hmsh_escalations
-         SET status = 'resolved', resolved_at = NOW(), resolver_payload = $2, updated_at = NOW()
+         SET status = 'resolved', resolved_at = NOW(), resolver_payload = $2,
+             metadata = CASE WHEN $3::jsonb IS NOT NULL
+                             THEN COALESCE(metadata, '{}'::jsonb) || $3::jsonb
+                             ELSE metadata END,
+             updated_at = NOW()
          WHERE id = $1 AND status = 'pending'
-         RETURNING *`, [id, payloadJson]);
+         RETURNING *`, [id, payloadJson, metaJson]);
             if (!updateResult.rows[0]) {
                 await this.pgClient.query('ROLLBACK');
                 return { ok: false, reason: 'already-resolved' };
@@ -2007,17 +2019,21 @@ class PostgresStoreService extends __1.StoreService {
         return result.rowCount ?? 0;
     }
     async resolveManyEscalations(params) {
-        const { ids, namespace, resolverPayload } = params;
+        const { ids, namespace, resolverPayload, metadata } = params;
         const payloadJson = resolverPayload ? JSON.stringify(resolverPayload) : null;
+        const metaJson = metadata ? JSON.stringify(metadata) : null;
         const result = await this.pgClient.query(`UPDATE public.hmsh_escalations
        SET status           = 'resolved',
            resolved_at      = NOW(),
            resolver_payload = $1,
+           metadata         = CASE WHEN $3::jsonb IS NOT NULL
+                                   THEN COALESCE(metadata, '{}'::jsonb) || $3::jsonb
+                                   ELSE metadata END,
            updated_at       = NOW()
        WHERE id = ANY($2::uuid[])
-         ${namespace ? 'AND namespace = $3' : ''}
+         ${namespace ? 'AND namespace = $4' : ''}
          AND status = 'pending'
-       RETURNING *`, namespace ? [payloadJson, ids, namespace] : [payloadJson, ids]);
+       RETURNING *`, namespace ? [payloadJson, ids, metaJson, namespace] : [payloadJson, ids, metaJson]);
         return result.rows;
     }
     async escalationStats(params = {}) {
@@ -2035,45 +2051,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

@@ -256,6 +256,14 @@ export interface ResolveEscalationParams {
     id: string;
     namespace?: string;
     resolverPayload?: Record<string, unknown>;
+    /**
+     * Merged (not replaced) into the resolved row's `metadata` in the same atomic
+     * UPDATE — and only on the winning resolve. Records "what actually happened"
+     * into the GIN-indexed (`@>`-queryable) surface alongside the creation metadata.
+     * Distinct from `resolverPayload`, which is delivered to the waiting workflow as
+     * `condition()`'s return value and is not GIN-indexed.
+     */
+    metadata?: Record<string, unknown>;
 }
 export interface ResolveByMetadataParams {
     key: string;
@@ -263,6 +271,12 @@ export interface ResolveByMetadataParams {
     namespace?: string;
     resolverPayload?: Record<string, unknown>;
     roles?: string[];
+    /**
+     * Merge patch applied to the matched row's `metadata` (shallow, not replaced) in
+     * the same atomic UPDATE. Note this is the resolution patch — distinct from the
+     * `key`/`value` selector used to find the row. See {@link ResolveEscalationParams.metadata}.
+     */
+    metadata?: Record<string, unknown>;
 }
 export interface EscalateToRoleParams {
     id: string;
@@ -289,6 +303,11 @@ export interface ResolveManyParams {
     ids: string[];
     namespace?: string;
     resolverPayload?: Record<string, unknown>;
+    /**
+     * Merged (not replaced) into every winning (still-pending) row's `metadata` in
+     * the single bulk UPDATE. See {@link ResolveEscalationParams.metadata}.
+     */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Full-fidelity migration params. Extends `CreateEscalationParams` with:

package/package.json

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