@hotmeshio/hotmesh 0.22.8 → 0.24.1

package/build/package.json

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

package/build/services/durable/exporter.js

@@ -285,6 +285,14 @@ class ExporterService {
         if (options.enrich_inputs) {
             await this.enrichExecutionInputs(execution, jobId);
         }
+        // Opt-in upward lineage pointer — one indexed lookup; surfaces the real
+        // spawning parent (not the collator $C job) and the root ancestor.
+        if (options.include_lineage && this.store.getJobLineage) {
+            const jobKey = `hmsh:${this.appId}:j:${jobId}`;
+            const lineage = await this.store.getJobLineage(jobKey);
+            execution.parent_workflow_id = lineage?.parent_id ?? null;
+            execution.origin_id = lineage?.origin_id ?? null;
+        }
         return execution;
     }
     /**

package/build/services/durable/schemas/factory.d.ts

@@ -1,4 +1,4 @@
-declare const APP_VERSION = "16";
+declare const APP_VERSION = "17";
 declare const APP_ID = "durable";
 /**
  * returns a new durable workflow schema

package/build/services/durable/schemas/factory.js

@@ -6,8 +6,9 @@ exports.APP_ID = exports.APP_VERSION = exports.getWorkflowYAML = void 0;
 // schema upgrade and hot-swap to it (see WorkerService.activateWorkflow and
 // ClientService.deployAndActivate). Changing the YAML without a bump leaves
 // every already-deployed database on the old schema forever. Numeric string —
-// compared with `Number()` for ordering. (v16: condition() escalation hook.)
-const APP_VERSION = '16';
+// compared with `Number()` for ordering. (v17: collator_waiter escalation block —
+// escalation-bearing condition() inside Promise.all writes its hmsh_escalations row.)
+const APP_VERSION = '17';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'durable';
 exports.APP_ID = APP_ID;
@@ -1944,6 +1945,49 @@ const getWorkflowYAML = (app, version) => {
               - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
               - ['{@array.get}', duration]
               - ['{@object.get}']
+          # Flatten the CURRENT item's escalation config into this activity's own
+          # output so the escalation block below can address it with flat symbols.
+          # mapOutputData runs before the escalation INSERT in Leg1, so these are
+          # resolved in time. For a plain (non-escalation) collated condition these
+          # resolve to undefined and the INSERT is skipped, just like the inline waiter.
+          output:
+            maps:
+              queueConfig:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', queueConfig]
+                  - ['{@object.get}']
+              taskQueue:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', taskQueue]
+                  - ['{@object.get}']
+              workflowName:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', workflowName]
+                  - ['{@object.get}']
+          # Identical in principle to the inline waiter escalation block, but sourced
+          # from the collated item. The escalation signal_key is auto-derived from this
+          # activity's reentry hook rule (wfs.signal, matching item.signalId), so resolve()
+          # and signal() — which double-fire wfs.signal + wfs.wait — reach it correctly.
+          escalation:
+            type: '{$self.output.data.queueConfig.type}'
+            subtype: '{$self.output.data.queueConfig.subtype}'
+            entity: '{$self.output.data.queueConfig.entity}'
+            description: '{$self.output.data.queueConfig.description}'
+            role: '{$self.output.data.queueConfig.role}'
+            priority: '{$self.output.data.queueConfig.priority}'
+            metadata: '{$self.output.data.queueConfig.metadata}'
+            envelope: '{$self.output.data.queueConfig.envelope}'
+            originId: '{$self.output.data.queueConfig.originId}'
+            parentId: '{$self.output.data.queueConfig.parentId}'
+            initiatedBy: '{$self.output.data.queueConfig.initiatedBy}'
+            traceId: '{$self.output.data.queueConfig.traceId}'
+            spanId: '{$self.output.data.queueConfig.spanId}'
+            expiresAt: '{$self.output.data.queueConfig.expiresAt}'
+            taskQueue: '{$self.output.data.taskQueue}'
+            workflowType: '{$self.output.data.workflowName}'
           hook:
             type: object
             properties:

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/durable/workflow/condition.js

@@ -160,7 +160,16 @@ async function condition(signalId, timeoutOrConfig) {
         type: 'DurableWaitForError',
         code: common_1.HMSH_CODE_DURABLE_WAIT,
         ...(timeout ? { duration: (0, common_1.s)(timeout) } : {}),
-        ...(queueConfig ? { queueConfig } : {}),
+        // taskQueue + workflowName ride along so a collated wait (Promise.all) can
+        // write a faithful hmsh_escalations row from inside the collator flow —
+        // matching the inline waiter, which sources these from its trigger.
+        ...(queueConfig
+            ? {
+                queueConfig,
+                taskQueue: store.get('taskQueue'),
+                workflowName: store.get('workflowName'),
+            }
+            : {}),
     };
     interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();

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/index.d.ts

@@ -157,5 +157,18 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
         };
         attributes: Record<string, string>;
     }>;
+    /**
+     * Fetch just the lineage columns (`parent_id`, `origin_id`) for a job via a
+     * single indexed lookup on `key`. Powers the exporter's opt-in
+     * `include_lineage` pointer — `parent_id` is the real spawning workflow (never
+     * the synthetic collator `$C` job), `origin_id` is the root ancestor.
+     *
+     * @param jobKey - The job key (e.g., "hmsh:durable:j:workflowId")
+     * @returns parent/origin ids (null when absent — a null `parent_id` marks a root)
+     */
+    getJobLineage?(jobKey: string): Promise<{
+        parent_id: string | null;
+        origin_id: string | null;
+    } | null>;
 }
 export { StoreService };

package/build/services/store/providers/postgres/exporter-sql.d.ts

@@ -6,6 +6,11 @@
  * Fetch job record by key.
  */
 export declare const GET_JOB_BY_KEY = "\n  SELECT id, key, status, created_at, updated_at, expired_at, is_live\n  FROM {schema}.jobs\n  WHERE key = $1\n  LIMIT 1\n";
+/**
+ * Fetch just the lineage columns for a job — a single indexed lookup on `key`.
+ * Backs the exporter's opt-in `include_lineage` pointer.
+ */
+export declare const GET_JOB_LINEAGE = "\n  SELECT parent_id, origin_id\n  FROM {schema}.jobs\n  WHERE key = $1\n  LIMIT 1\n";
 /**
  * Fetch all attributes for a job.
  */

package/build/services/store/providers/postgres/exporter-sql.js

@@ -4,7 +4,7 @@
  * These queries support the exporter's input enrichment and direct query features.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildChildWorkflowInputsQuery = exports.GET_STREAM_HISTORY_BY_JID_AND_AID = exports.GET_STREAM_HISTORY_BY_JID_AND_TYPE = exports.GET_STREAM_HISTORY_BY_JID = exports.GET_PROXYER_STREAM_INPUTS = exports.GET_ACTIVITY_INPUTS = exports.GET_JOB_ATTRIBUTES = exports.GET_JOB_BY_KEY = void 0;
+exports.buildChildWorkflowInputsQuery = exports.GET_STREAM_HISTORY_BY_JID_AND_AID = exports.GET_STREAM_HISTORY_BY_JID_AND_TYPE = exports.GET_STREAM_HISTORY_BY_JID = exports.GET_PROXYER_STREAM_INPUTS = exports.GET_ACTIVITY_INPUTS = exports.GET_JOB_ATTRIBUTES = exports.GET_JOB_LINEAGE = exports.GET_JOB_BY_KEY = void 0;
 /**
  * Fetch job record by key.
  */
@@ -14,6 +14,16 @@ exports.GET_JOB_BY_KEY = `
   WHERE key = $1
   LIMIT 1
 `;
+/**
+ * Fetch just the lineage columns for a job — a single indexed lookup on `key`.
+ * Backs the exporter's opt-in `include_lineage` pointer.
+ */
+exports.GET_JOB_LINEAGE = `
+  SELECT parent_id, origin_id
+  FROM {schema}.jobs
+  WHERE key = $1
+  LIMIT 1
+`;
 /**
  * Fetch all attributes for a job.
  */

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

@@ -216,6 +216,14 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
         };
         attributes: Record<string, string>;
     }>;
+    /**
+     * Single indexed lookup of the lineage columns for a job key. Returns the real
+     * spawning parent (never the synthetic collator `$C` job) and the root ancestor.
+     */
+    getJobLineage(jobKey: string): Promise<{
+        parent_id: string | null;
+        origin_id: string | null;
+    } | null>;
     /**
      * Fetch stream message history for a job from worker_streams.
      * Returns raw activity input/output data from soft-deleted messages.

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

@@ -1338,6 +1338,20 @@ class PostgresStoreService extends __1.StoreService {
         }
         return { job, attributes };
     }
+    /**
+     * Single indexed lookup of the lineage columns for a job key. Returns the real
+     * spawning parent (never the synthetic collator `$C` job) and the root ancestor.
+     */
+    async getJobLineage(jobKey) {
+        const { GET_JOB_LINEAGE } = await Promise.resolve().then(() => __importStar(require('./exporter-sql')));
+        const schemaName = this.kvsql().safeName(this.appId);
+        const sql = GET_JOB_LINEAGE.replace(/{schema}/g, schemaName);
+        const result = await this.pgClient.query(sql, [jobKey]);
+        if (result.rows.length === 0)
+            return null;
+        const { parent_id, origin_id } = result.rows[0];
+        return { parent_id: parent_id ?? null, origin_id: origin_id ?? null };
+    }
     /**
      * Fetch stream message history for a job from worker_streams.
      * Returns raw activity input/output data from soft-deleted messages.
@@ -1755,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.
@@ -1775,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' };
@@ -1791,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
@@ -1813,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' };
@@ -1993,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 = {}) {

package/build/types/exporter.d.ts

@@ -265,6 +265,19 @@ export interface WorkflowExecution {
     summary: WorkflowExecutionSummary;
     children?: WorkflowExecution[];
     stream_history?: StreamHistoryEntry[];
+    /**
+     * Upward lineage pointer to the real spawning workflow — never the synthetic
+     * collator `$C` job. `null` marks a root. Only present when the export was
+     * requested with `include_lineage: true`.
+     */
+    parent_workflow_id?: string | null;
+    /**
+     * Root ancestor of this execution; `null` for a root itself (identify roots
+     * via a null `parent_workflow_id`). Every descendant carries the same
+     * `origin_id`, so a subtree is recoverable in one query. Only present when the
+     * export was requested with `include_lineage: true`.
+     */
+    origin_id?: string | null;
 }
 /**
  * Options for `handle.exportExecution()`. Controls event filtering, enrichment,
@@ -310,6 +323,17 @@ export interface ExecutionExportOptions {
      * @default false
      */
     allow_direct_query?: boolean;
+    /**
+     * When true, populates the export's `parent_workflow_id` and `origin_id` from
+     * the jobs table via a single indexed lookup. `parent_workflow_id` is the real
+     * spawning workflow (never the synthetic collator `$C` job); `origin_id` is the
+     * root ancestor (a null `parent_workflow_id` marks a root). Opt-in so the extra
+     * query is only paid when a UI needs upward lineage. Requires a provider that
+     * implements `getJobLineage` (e.g., Postgres); a no-op otherwise.
+     *
+     * @default false
+     */
+    include_lineage?: boolean;
     /**
      * When true, fetches the full stream message history for this workflow
      * from the worker_streams table and attaches it as `stream_history`.

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