@hotmeshio/hotmesh 0.22.7 → 0.23.0

package/build/package.json

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

package/build/services/durable/client.js

@@ -167,7 +167,7 @@ class ClientService {
                     pending: options?.pending,
                     entity: options?.entity,
                 });
-                return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId);
+                return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId, this.escalations);
             },
             /**
              * Sends a message payload to a running workflow that is paused and awaiting the signal.
@@ -267,7 +267,7 @@ class ClientService {
             getHandle: async (taskQueue, workflowName, workflowId, namespace) => {
                 const workflowTopic = `${taskQueue}-${workflowName}`;
                 const hotMeshClient = await this.getHotMeshClient(taskQueue, namespace);
-                return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, workflowId);
+                return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, workflowId, this.escalations);
             },
             /**
              * Provides direct access to the SEARCH backend

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

@@ -3,6 +3,7 @@ import { DurableJobExport, ExportOptions, ExecutionExportOptions, WorkflowExecut
 import { JobInterruptOptions } from '../../types/job';
 import { StreamError } from '../../types/stream';
 import { ExporterService } from './exporter';
+import { EscalationClientService } from '../escalations/client';
 /**
  * Handle to a running or completed workflow execution. Returned by
  * `client.workflow.start()` and `client.workflow.getHandle()`.
@@ -32,10 +33,12 @@ export declare class WorkflowHandleService {
     hotMesh: HotMesh;
     workflowTopic: string;
     workflowId: string;
+    /** @private */
+    escalationClient?: EscalationClientService;
     /**
      * @private
      */
-    constructor(hotMesh: HotMesh, workflowTopic: string, workflowId: string);
+    constructor(hotMesh: HotMesh, workflowTopic: string, workflowId: string, escalationClient?: EscalationClientService);
     /**
      * Export the raw workflow state as a {@link DurableJobExport} with five sections:
      *
@@ -126,6 +129,12 @@ export declare class WorkflowHandleService {
      * subscribers are notified, and the job hash is expired. Unlike
      * {@link cancel}, this does **not** give the workflow a chance to
      * run cleanup code.
+     *
+     * Any pending escalations for this workflow are cancelled in the same
+     * Postgres transaction that decrements the job semaphore — one atomic
+     * write, no TOCTOU. A `system.escalation.*.cancelled` event is emitted
+     * locally for each cancelled row via the configured `events.publish`
+     * sink — instance-local only, never broadcast.
      */
     terminate(options?: JobInterruptOptions): Promise<string>;
     /**

package/build/services/durable/handle.js

@@ -27,10 +27,11 @@ class WorkflowHandleService {
     /**
      * @private
      */
-    constructor(hotMesh, workflowTopic, workflowId) {
+    constructor(hotMesh, workflowTopic, workflowId, escalationClient) {
         this.workflowTopic = workflowTopic;
         this.workflowId = workflowId;
         this.hotMesh = hotMesh;
+        this.escalationClient = escalationClient;
         this.exporter = new exporter_1.ExporterService(this.hotMesh.appId, this.hotMesh.engine.store, this.hotMesh.engine.logger);
     }
     /**
@@ -157,9 +158,23 @@ class WorkflowHandleService {
      * subscribers are notified, and the job hash is expired. Unlike
      * {@link cancel}, this does **not** give the workflow a chance to
      * run cleanup code.
+     *
+     * Any pending escalations for this workflow are cancelled in the same
+     * Postgres transaction that decrements the job semaphore — one atomic
+     * write, no TOCTOU. A `system.escalation.*.cancelled` event is emitted
+     * locally for each cancelled row via the configured `events.publish`
+     * sink — instance-local only, never broadcast.
      */
     async terminate(options) {
-        return await this.hotMesh.interrupt(`${this.hotMesh.appId}.execute`, this.workflowId, options);
+        let cancelledEntries = [];
+        const result = await this.hotMesh.interrupt(`${this.hotMesh.appId}.execute`, this.workflowId, {
+            ...options,
+            onEscalationsCancelled: (entries) => { cancelledEntries = entries; },
+        });
+        if (this.escalationClient && cancelledEntries.length > 0) {
+            this.escalationClient.emitCancelledBatch(cancelledEntries);
+        }
+        return result;
     }
     /**
      * Requests cooperative cancellation of the workflow. Unlike

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

@@ -97,6 +97,7 @@ import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
  *   {@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, or `false` if a timeout string was given and it expired.
+ * @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()`.
  */
-export declare function condition<T>(signalId: string, timeoutOrConfig?: string | ConditionQueueConfig): Promise<T | false>;
+export declare function condition<T>(signalId: string, timeoutOrConfig?: string | ConditionQueueConfig): Promise<T | false | null>;

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

@@ -102,7 +102,8 @@ const didRun_1 = require("./didRun");
  *   {@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, or `false` if a timeout string was given and it expired.
+ * @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()`.
  */
 async function condition(signalId, timeoutOrConfig) {
     const timeout = typeof timeoutOrConfig === 'string' ? timeoutOrConfig : undefined;
@@ -127,7 +128,13 @@ async function condition(signalId, timeoutOrConfig) {
         if (result?.timedOut) {
             return false;
         }
-        return result.data.data;
+        const signalData = result.data?.data;
+        // If the escalation was cancelled via cancel(), the signal carries this marker.
+        // Return null so the workflow can distinguish cancellation from a real resolution.
+        if (signalData && typeof signalData === 'object' && signalData.__escalation_cancelled === true) {
+            return null;
+        }
+        return signalData;
     }
     const store = common_1.asyncLocalStorage.getStore();
     // Emit DISPATCH span in debug mode
@@ -153,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

@@ -120,10 +120,22 @@ export declare class EscalationClientService {
      */
     escalateToRole(params: EscalateToRoleParams): Promise<EscalationEntry | null>;
     /**
-     * Cancels a pending escalation without delivering a signal. Terminal rows
-     * return `already-terminal`.
+     * Cancels a pending escalation and delivers a cancellation signal to the
+     * waiting workflow so that `condition()` returns `null`. Terminal rows
+     * return `already-terminal`. Signal delivery is best-effort post-commit —
+     * the committed cancelled row is the durable record; any missed delivery
+     * can be detected via a sweep of rows with `status = 'cancelled'` and a
+     * non-null `signal_key`.
      */
     cancel(id: string, namespace?: string): Promise<CancelEscalationResult>;
+    /**
+     * Emits local `cancelled` events for a batch of already-cancelled escalation
+     * entries. Called by `WorkflowHandleService.terminate()` after the single
+     * atomic transaction that interrupts the workflow and cancels its escalations
+     * has committed. Fire-and-forget via the configured `events.publish` sink
+     * (e.g. NATS) — instance-local, never broadcast via Postgres LISTEN/NOTIFY.
+     */
+    emitCancelledBatch(entries: EscalationEntry[]): void;
     /**
      * Resolves a pending escalation by UUID. Uses an explicit Postgres transaction
      * with FOR UPDATE + WHERE guard: only one concurrent caller can commit the

package/build/services/escalations/client.js

@@ -242,16 +242,38 @@ class EscalationClientService {
         return entry;
     }
     /**
-     * Cancels a pending escalation without delivering a signal. Terminal rows
-     * return `already-terminal`.
+     * Cancels a pending escalation and delivers a cancellation signal to the
+     * waiting workflow so that `condition()` returns `null`. Terminal rows
+     * return `already-terminal`. Signal delivery is best-effort post-commit —
+     * the committed cancelled row is the durable record; any missed delivery
+     * can be detected via a sweep of rows with `status = 'cancelled'` and a
+     * non-null `signal_key`.
      */
     async cancel(id, namespace) {
-        const hm = await this._engine(null, namespace);
+        const ns = namespace ?? factory_1.APP_ID;
+        const hm = await this._engine(null, ns);
         const result = await hm.engine.store.cancelEscalation(id, namespace);
-        if (result.ok === true)
+        if (result.ok === true) {
             this._emit('cancelled', result.entry);
+            if (result.entry.signal_key) {
+                await this._deliverEscalationSignal(ns, result.entry.topic, {
+                    id: result.entry.signal_key,
+                    data: { __escalation_cancelled: true },
+                });
+            }
+        }
         return result;
     }
+    /**
+     * Emits local `cancelled` events for a batch of already-cancelled escalation
+     * entries. Called by `WorkflowHandleService.terminate()` after the single
+     * atomic transaction that interrupts the workflow and cancels its escalations
+     * has committed. Fire-and-forget via the configured `events.publish` sink
+     * (e.g. NATS) — instance-local, never broadcast via Postgres LISTEN/NOTIFY.
+     */
+    emitCancelledBatch(entries) {
+        this._emitMany('cancelled', entries);
+    }
     /**
      * Resolves a pending escalation by UUID. Uses an explicit Postgres transaction
      * with FOR UPDATE + WHERE guard: only one concurrent caller can commit the

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

@@ -1009,32 +1009,23 @@ class PostgresStoreService extends __1.StoreService {
      */
     async interrupt(topic, jobId, options = {}) {
         try {
-            //verify job exists
+            //pre-flight: bail early if already inactive (optimization; hincrbyfloat is the real guard)
             const status = await this.getStatus(jobId, this.appId);
             if (status <= 0) {
-                //verify still active; job already completed
                 throw new Error(`Job ${jobId} already completed`);
             }
-            //decrement job status (:) by 1bil
             const amount = -1000000000;
-            const jobKey = this.mintKey(key_1.KeyType.JOB_STATE, {
-                appId: this.appId,
-                jobId,
-            });
-            const result = await this.kvsql().hincrbyfloat(jobKey, ':', amount);
-            if (result <= amount) {
-                //verify active state; job already interrupted
-                throw new Error(`Job ${jobId} already completed`);
-            }
-            //persist the error unless specifically told not to
+            const jobKey = this.mintKey(key_1.KeyType.JOB_STATE, { appId: this.appId, jobId });
+            //build error symbol BEFORE opening the transaction — symbol lookup is read-only
+            let errSymbol;
+            let err;
             if (options.throw !== false) {
-                const errKey = `metadata/err`; //job errors are stored at the path `metadata/err`
-                const symbolNames = [`$${topic}`]; //the symbol for `metadata/err` is in the backend
+                const errKey = `metadata/err`;
+                const symbolNames = [`$${topic}`];
                 const symKeys = await this.getSymbolKeys(symbolNames);
                 const symVals = await this.getSymbolValues();
                 this.serializer.resetSymbols(symKeys, symVals, {});
-                //persists the standard 410 error (job is `gone`)
-                const err = JSON.stringify({
+                err = JSON.stringify({
                     code: options.code ?? enums_1.HMSH_CODE_INTERRUPT,
                     message: options.reason ?? `job [${jobId}] interrupted`,
                     stack: options.stack ?? '',
@@ -1042,9 +1033,32 @@ class PostgresStoreService extends __1.StoreService {
                 });
                 const payload = { [errKey]: amount.toString() };
                 const hashData = this.serializer.package(payload, symbolNames);
-                const errSymbol = Object.keys(hashData)[0];
-                await this.kvsql().hset(jobKey, { [errSymbol]: err });
+                errSymbol = Object.keys(hashData)[0];
+            }
+            //single transaction: status decrement + optional error write + escalation cancel.
+            //WHERE guard on the escalation UPDATE prevents double-cancel;
+            //hincrbyfloat is the atomic idempotency proof checked post-commit.
+            const txn = this.kvsql(this.transact());
+            txn.hincrbyfloat(jobKey, ':', amount);
+            if (errSymbol && err) {
+                txn.hset(jobKey, { [errSymbol]: err });
             }
+            txn.addCommand(`UPDATE public.hmsh_escalations
+         SET status = 'cancelled', updated_at = NOW()
+         WHERE workflow_id = $1
+           AND app_id = $2
+           AND status = 'pending'
+         RETURNING *`, [jobId, this.appId], 'array', (rows) => rows);
+            const results = await txn.exec();
+            //results[0] = new status after hincrbyfloat — the atomic idempotency guard
+            const newStatus = results[0];
+            if (newStatus <= amount) {
+                throw new Error(`Job ${jobId} already completed`);
+            }
+            //fire the callback with any escalation rows cancelled in this same transaction;
+            //no second query, no second transaction
+            const cancelledEntries = (results[results.length - 1] || []);
+            options.onEscalationsCancelled?.(cancelledEntries);
         }
         catch (e) {
             if (!options.suppress) {
@@ -1324,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.

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

@@ -130,7 +130,10 @@ type JobInterruptOptions = {
      */
     throw?: boolean;
     /**
-     * interrupt child/descendant jobs
+     * Reserved for future use: interrupt child/descendant jobs.
+     * This flag is parsed and threaded through the engine call chain
+     * but is **not yet implemented** — child workflows are not interrupted
+     * when this is set. Do not rely on it.
      * @default false
      */
     descend?: boolean;
@@ -154,6 +157,13 @@ type JobInterruptOptions = {
      * Optional stack trace
      */
     stack?: string;
+    /**
+     * Fires synchronously inside `store.interrupt()` after the single
+     * transaction that decrements the job semaphore AND cancels pending
+     * escalations commits. Only used by `WorkflowHandleService.terminate()`
+     * to emit local events without a second transaction or a separate query.
+     */
+    onEscalationsCancelled?: (entries: any[]) => void;
 };
 /**
  * format when publishing job meta/data on the wire when it completes

package/package.json

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