@hotmeshio/hotmesh 0.22.3 → 0.22.5

package/build/index.d.ts

@@ -22,3 +22,4 @@ import { Escalations } from './services/escalations';
 export { Connector, //factory
 ConnectorNATS, ConnectorPostgres, HotMesh, HotMeshConfig, Virtual, Durable, Escalations, DBA, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
 export * as Types from './types';
+export type { EventsConfig, SystemEvent } from './types/system_events';

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.22.3",
+    "version": "0.22.5",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -89,6 +89,7 @@
         "prove": "docker compose exec hotmesh npx vitest run tests/durable 2>&1 | tee /tmp/hmsh-durable.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-durable.txt | tail -5",
         "prove:escalations": "docker compose exec hotmesh npx vitest run tests/durable/escalations/postgres.test.ts 2>&1 | tee /tmp/hmsh-escalations.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-escalations.txt | tail -5",
         "prove:migrations": "docker compose exec hotmesh npx vitest run tests/durable/migrations/postgres.test.ts 2>&1 | tee /tmp/hmsh-migrations.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-migrations.txt | tail -5",
+        "prove:events": "docker compose exec hotmesh npx vitest run tests/durable/events/postgres.test.ts 2>&1 | tee /tmp/hmsh-events.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-events.txt | tail -5",
         "prove:functional": "docker compose exec hotmesh npx vitest run tests/functional 2>&1 | tee /tmp/hmsh-functional.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-functional.txt | tail -5",
         "prove:all": "docker compose exec hotmesh npx vitest run tests/ 2>&1 | tee /tmp/hmsh-all.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-all.txt | tail -5",
         "prove:file": "f() { docker compose exec hotmesh npx vitest run \"$@\" 2>&1 | tee /tmp/hmsh-file.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-file.txt | tail -5; }; f"

package/build/services/activities/hook.js

@@ -347,8 +347,10 @@ class Hook extends activity_1.Activity {
         //enqueue escalation INSERT inside the Leg1 transaction so it is
         //written atomically with the job state checkpoint — one committed
         //unit, crash-safe, no separate recovery path needed.
-        await this.addEscalationToTransaction(transaction);
-        await transaction.exec();
+        const escalationSignalKey = await this.addEscalationToTransaction(transaction);
+        // exec() returns one result per queued command; the escalation INSERT
+        // (with RETURNING *) is the last command — its row is results[last].
+        const execResults = await transaction.exec();
         telemetry.mapActivityAttributes();
         //register the web hook signal AFTER the transaction commits.
         //this eliminates the FORBIDDEN window: the hook signal is never
@@ -360,13 +362,39 @@ class Hook extends activity_1.Activity {
         if (pending) {
             await this.redeliverPendingSignal(pending);
         }
+        // Post-commit: fire the escalation.created event using the row returned
+        // directly from the RETURNING * clause — no extra SELECT.
+        if (escalationSignalKey) {
+            const store = this.store;
+            if (store.eventsPublish) {
+                const row = execResults[execResults.length - 1];
+                if (row?.id) {
+                    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}:created:${updatedAt}`,
+                        type: `system.escalation.${row.id}.created`,
+                        ts,
+                        namespace: row.namespace ?? this.engine.namespace ?? this.engine.appId,
+                        app_id: row.app_id ?? this.engine.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(() => { });
+                }
+            }
+        }
     }
     async addEscalationToTransaction(transaction) {
         if (!this.config.escalation || !this.config.hook?.topic)
-            return;
+            return null;
         const store = this.store;
         if (typeof store.addEscalationToTransaction !== 'function')
-            return;
+            return null;
         const escalationConfig = this.config.escalation;
         const jid = this.context.metadata.jid;
         const appId = this.engine.appId;
@@ -408,7 +436,7 @@ class Hook extends activity_1.Activity {
         // the factory waiter runs for a condition() call that had no queueConfig.
         if (params.role == null && params.type == null &&
             params.priority == null && params.metadata == null)
-            return;
+            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);
@@ -423,6 +451,7 @@ class Hook extends activity_1.Activity {
             workflowId: jid,
             ...params,
         }, transaction);
+        return signalKey;
     }
     /**
      * Re-publishes a pending signal as a WEBHOOK stream message so the

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

@@ -1,9 +1,15 @@
 import { HotMesh } from '../hotmesh';
 import { ClientConfig, ClientWorkflow, Connection, WorkflowOptions } from '../../types/durable';
 import { EscalationClientService } from '../escalations/client';
+import { EventsConfig } from '../../types/system_events';
 /**
  * Workflow client. Starts workflows, sends signals, and reads results.
  *
+ * Pass `config.events` to receive system-event notifications from all
+ * escalation operations performed through this client. Events fire
+ * post-commit, from this process only — no fanout to other containers.
+ * See `EventsConfig` and `SystemEvent` in `types/system_events` for the full ontology.
+ *
  * @example
  * ```typescript
  * import { Durable } from '@hotmeshio/hotmesh';
@@ -14,6 +20,13 @@ import { EscalationClientService } from '../escalations/client';
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
  *   },
+ *   // optional — wire lifecycle events
+ *   events: {
+ *     publish: (event) => {
+ *       // event.type follows system.escalation.{id}.{verb}
+ *       myEventBus.emit(event.type, event.data);
+ *     },
+ *   },
  * });
  *
  * // Start a workflow and await its result
@@ -41,6 +54,10 @@ export declare class ClientService {
      * @private
      */
     options: WorkflowOptions;
+    /**
+     * @private
+     */
+    events?: EventsConfig;
     /**
      * @private
      */

package/build/services/durable/client.js

@@ -14,6 +14,11 @@ const factory_1 = require("./schemas/factory");
 /**
  * Workflow client. Starts workflows, sends signals, and reads results.
  *
+ * Pass `config.events` to receive system-event notifications from all
+ * escalation operations performed through this client. Events fire
+ * post-commit, from this process only — no fanout to other containers.
+ * See `EventsConfig` and `SystemEvent` in `types/system_events` for the full ontology.
+ *
  * @example
  * ```typescript
  * import { Durable } from '@hotmeshio/hotmesh';
@@ -24,6 +29,13 @@ const factory_1 = require("./schemas/factory");
  *     class: Postgres,
  *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
  *   },
+ *   // optional — wire lifecycle events
+ *   events: {
+ *     publish: (event) => {
+ *       // event.type follows system.escalation.{id}.{verb}
+ *       myEventBus.emit(event.type, event.data);
+ *     },
+ *   },
  * });
  *
  * // Start a workflow and await its result
@@ -73,6 +85,7 @@ class ClientService {
                     readonly,
                     connection: this.connection,
                 },
+                events: this.events,
             });
             //synchronously cache the promise (before awaiting)
             ClientService.instances.set(connectionNS, hotMeshClient);
@@ -286,9 +299,10 @@ class ClientService {
             },
         };
         this.connection = config.connection;
-        // Inject our getHotMeshClient so the escalation client shares the same engine pool.
+        this.events = config.events;
         this.escalations = new client_1.EscalationClientService({
             getHotMeshClient: this.getHotMeshClient.bind(this),
+            events: config.events,
         });
     }
     hashOptions() {

package/build/services/durable/worker.d.ts

@@ -104,6 +104,12 @@ export declare class WorkerService {
      * @private
      */
     activityRunner: HotMesh;
+    /** @private — retained from create() config for stop() lifecycle event */
+    _eventsPublish?: (event: import('../../types/system_events').SystemEvent) => void | Promise<void>;
+    /** @private */
+    _eventsTaskQueue?: string;
+    /** @private */
+    _eventsAppId?: string;
     /**
      * @private
      */
@@ -268,6 +274,10 @@ export declare class WorkerService {
      * Run the connected worker; no-op (unnecessary to call)
      */
     run(): Promise<void>;
+    /**
+     * Stops the worker's HotMesh instances and fires `system.worker.{taskQueue}.stopped`.
+     */
+    stop(): void;
     /**
      * @private
      */

package/build/services/durable/worker.js

@@ -309,6 +309,7 @@ class WorkerService {
             appId: targetNamespace,
             engine: { connection: config.connection },
             workers: [workerEntry],
+            events: config.events,
         });
         WorkerService.instances.set(targetTopic, hotMeshWorker);
         return hotMeshWorker;
@@ -478,6 +479,21 @@ class WorkerService {
         worker.workflowRunner = await worker.initWorkflowWorker(config, taskQueue, workflowFunctionName, workflowTopic, workflowFunction);
         search_1.Search.configureSearchIndex(worker.workflowRunner, config.search);
         await WorkerService.activateWorkflow(worker.workflowRunner);
+        // Fire system.worker.{taskQueue}.started post-init (best-effort).
+        if (config.events?.publish) {
+            worker._eventsPublish = config.events.publish;
+            worker._eventsTaskQueue = taskQueue;
+            worker._eventsAppId = targetNamespace;
+            const ts = new Date().toISOString();
+            void Promise.resolve(config.events.publish({
+                event_id: `${taskQueue}:started:${ts}`,
+                type: `system.worker.${taskQueue}.started`,
+                ts,
+                namespace: targetNamespace,
+                app_id: targetNamespace,
+                data: { taskQueue, appId: targetNamespace },
+            })).catch(() => { });
+        }
         return worker;
     }
     /**
@@ -502,6 +518,24 @@ class WorkerService {
     async run() {
         this.workflowRunner.engine.logger.info('durable-worker-running');
     }
+    /**
+     * Stops the worker's HotMesh instances and fires `system.worker.{taskQueue}.stopped`.
+     */
+    stop() {
+        this.workflowRunner?.stop();
+        this.activityRunner?.stop();
+        if (this._eventsPublish && this._eventsTaskQueue) {
+            const ts = new Date().toISOString();
+            void Promise.resolve(this._eventsPublish({
+                event_id: `${this._eventsTaskQueue}:stopped:${ts}`,
+                type: `system.worker.${this._eventsTaskQueue}.stopped`,
+                ts,
+                namespace: this._eventsAppId ?? '',
+                app_id: this._eventsAppId ?? '',
+                data: { taskQueue: this._eventsTaskQueue, appId: this._eventsAppId },
+            })).catch(() => { });
+        }
+    }
     /**
      * @private
      */
@@ -531,6 +565,7 @@ class WorkerService {
             appId: targetNamespace,
             engine: { connection: providerConfig },
             workers: [workerEntry],
+            events: config.events,
         });
         WorkerService.instances.set(targetTopic, hotMeshWorker);
         return hotMeshWorker;
@@ -660,6 +695,7 @@ class WorkerService {
             appId: config.namespace ?? factory_1.APP_ID,
             engine: { connection: providerConfig },
             workers: [workerEntry],
+            events: config.events,
         });
         WorkerService.instances.set(targetTopic, hotMeshWorker);
         return hotMeshWorker;

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

@@ -1,4 +1,5 @@
 import { HotMesh } from '../hotmesh';
+import { EventsConfig } from '../../types/system_events';
 import { Connection } from '../../types/durable';
 import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, StatsEscalationsParams, EscalationStats, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, ClaimManyParams, EscalateManyToRoleParams, UpdateManyPriorityParams, ResolveManyParams } from '../../types/hmsh_escalations';
 export type GetHotMeshFn = (topic: string | null, namespace?: string) => Promise<HotMesh>;
@@ -10,6 +11,12 @@ export interface EscalationClientConfig {
      * When provided, the client reuses the caller's engine pool — no extra connections.
      */
     getHotMeshClient?: GetHotMeshFn;
+    /**
+     * Optional system-event sink. When set, this client calls `events.publish`
+     * post-commit for every escalation lifecycle transition it performs.
+     * Fire-and-forget; a publish error never fails the committed operation.
+     */
+    events?: EventsConfig;
 }
 /**
  * Standalone client for the `public.hmsh_escalations` signal-pause surface.
@@ -48,8 +55,20 @@ export interface EscalationClientConfig {
  */
 export declare class EscalationClientService {
     private readonly _engine;
+    private readonly _events?;
     static instances: Map<string, HotMesh | Promise<HotMesh>>;
     constructor(config?: EscalationClientConfig);
+    /**
+     * Fires the configured `events.publish` hook post-commit.
+     * Detached (not awaited); a publish error never fails the caller.
+     * @private
+     */
+    private _emit;
+    /**
+     * Fires per-row events for bulk operations. Skipped rows are not emitted.
+     * @private
+     */
+    private _emitMany;
     private _makeEngineFactory;
     private _hashConnection;
     private _deliverEscalationSignal;

package/build/services/escalations/client.js

@@ -44,7 +44,6 @@ const factory_1 = require("../durable/schemas/factory");
 class EscalationClientService {
     constructor(config = {}) {
         if (config.getHotMeshClient) {
-            // Reuse a caller-supplied engine factory (e.g. Durable.Client) — no extra connections.
             this._engine = config.getHotMeshClient;
         }
         else if (config.connection) {
@@ -53,6 +52,43 @@ class EscalationClientService {
         else {
             throw new Error('EscalationClient requires either `connection` or `getHotMeshClient`');
         }
+        this._events = config.events;
+    }
+    /**
+     * Fires the configured `events.publish` hook post-commit.
+     * Detached (not awaited); a publish error never fails the caller.
+     * @private
+     */
+    _emit(verb, entry) {
+        if (!this._events?.publish)
+            return;
+        const ts = new Date().toISOString();
+        const updatedAt = entry.updated_at
+            ? (0, utils_1.formatISODate)(entry.updated_at)
+            : ts;
+        const event = {
+            event_id: `${entry.id}:${verb}:${updatedAt}`,
+            type: `system.escalation.${entry.id}.${verb}`,
+            ts,
+            namespace: entry.namespace ?? '',
+            app_id: entry.app_id ?? '',
+            workflow_id: entry.workflow_id ?? undefined,
+            topic: entry.topic ?? undefined,
+            origin_id: entry.origin_id ?? undefined,
+            parent_id: entry.parent_id ?? undefined,
+            trace_id: entry.trace_id ?? undefined,
+            span_id: entry.span_id ?? undefined,
+            data: entry,
+        };
+        void Promise.resolve(this._events.publish(event)).catch(() => { });
+    }
+    /**
+     * Fires per-row events for bulk operations. Skipped rows are not emitted.
+     * @private
+     */
+    _emitMany(verb, entries) {
+        for (const entry of entries)
+            this._emit(verb, entry);
     }
     _makeEngineFactory(connection) {
         return async (topic, namespace) => {
@@ -143,7 +179,10 @@ class EscalationClientService {
      */
     async create(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.createEscalation(params);
+        const entry = await hm.engine.store.createEscalation(params);
+        if (entry)
+            this._emit('created', entry);
+        return entry;
     }
     /**
      * Patches an existing escalation row. `metadata` is merged, not replaced.
@@ -165,7 +204,10 @@ class EscalationClientService {
      */
     async claim(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.claimEscalation(params);
+        const result = await hm.engine.store.claimEscalation(params);
+        if (result.ok === true)
+            this._emit('claimed', result.entry);
+        return result;
     }
     /**
      * Atomically claims the highest-priority pending escalation whose `metadata`
@@ -175,12 +217,18 @@ class EscalationClientService {
      */
     async claimByMetadata(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.claimEscalationByMetadata(params);
+        const result = await hm.engine.store.claimEscalationByMetadata(params);
+        if (result.ok === true)
+            this._emit('claimed', result.entry);
+        return result;
     }
     /** Releases a claimed escalation, returning it to available status. */
     async release(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.releaseEscalation(params);
+        const result = await hm.engine.store.releaseEscalation(params);
+        if (result.ok === true)
+            this._emit('released', result.entry);
+        return result;
     }
     /**
      * Reassigns the escalation to a different role, clearing any current claim
@@ -188,7 +236,10 @@ class EscalationClientService {
      */
     async escalateToRole(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.escalateEscalationToRole(params);
+        const entry = await hm.engine.store.escalateEscalationToRole(params);
+        if (entry)
+            this._emit('reassigned', entry);
+        return entry;
     }
     /**
      * Cancels a pending escalation without delivering a signal. Terminal rows
@@ -196,7 +247,10 @@ class EscalationClientService {
      */
     async cancel(id, namespace) {
         const hm = await this._engine(null, namespace);
-        return hm.engine.store.cancelEscalation(id, namespace);
+        const result = await hm.engine.store.cancelEscalation(id, namespace);
+        if (result.ok === true)
+            this._emit('cancelled', result.entry);
+        return result;
     }
     /**
      * Resolves a pending escalation by UUID. Uses an explicit Postgres transaction
@@ -219,6 +273,7 @@ class EscalationClientService {
                 data: params.resolverPayload ?? {},
             });
         }
+        this._emit('resolved', dbResult.entry);
         return { ok: true, entry: dbResult.entry };
     }
     /**
@@ -238,6 +293,7 @@ class EscalationClientService {
                 data: params.resolverPayload ?? {},
             });
         }
+        this._emit('resolved', dbResult.entry);
         return { ok: true, entry: dbResult.entry };
     }
     /**
@@ -265,7 +321,9 @@ class EscalationClientService {
      */
     async claimMany(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.claimManyEscalations(params);
+        const { entries, skipped } = await hm.engine.store.claimManyEscalations(params);
+        this._emitMany('claimed', entries);
+        return { claimed: entries.length, skipped };
     }
     /**
      * Bulk-reassigns pending escalations to a new role, clearing any current claim.
@@ -289,7 +347,9 @@ class EscalationClientService {
      */
     async resolveMany(params) {
         const hm = await this._engine(null, params.namespace);
-        return hm.engine.store.resolveManyEscalations(params);
+        const entries = await hm.engine.store.resolveManyEscalations(params);
+        this._emitMany('resolved', entries);
+        return entries;
     }
     // ─── Aggregates ─────────────────────────────────────────────────────────────
     /**

package/build/services/hotmesh/index.d.ts

@@ -124,6 +124,8 @@ declare class HotMesh {
      */
     workers: WorkerService[];
     logger: ILogger;
+    /** @private — retained from init config for stop() lifecycle event */
+    private _eventsPublish?;
     static disconnecting: boolean;
     /**
      * @private
@@ -144,6 +146,13 @@ declare class HotMesh {
      * functions that consume messages from Postgres streams — they can
      * run on the same process or on entirely separate servers.
      *
+     * Pass `config.events` to receive lifecycle events from this engine:
+     * - `system.engine.{appId}.started` — fires when init completes.
+     * - `system.engine.{appId}.deployed` — fires after schema deploy.
+     * - `system.engine.{appId}.stopped` — fires when `stop()` is called.
+     * - `system.escalation.{id}.created` — fires from the hook Leg1 path
+     *   (YAML `escalation:` block) when the escalation row commits.
+     *
      * @param config - Engine connection, worker definitions, app ID, and options.
      * @returns A running HotMesh instance joined to the quorum.
      */

package/build/services/hotmesh/index.js

@@ -170,6 +170,13 @@ class HotMesh {
      * functions that consume messages from Postgres streams — they can
      * run on the same process or on entirely separate servers.
      *
+     * Pass `config.events` to receive lifecycle events from this engine:
+     * - `system.engine.{appId}.started` — fires when init completes.
+     * - `system.engine.{appId}.deployed` — fires after schema deploy.
+     * - `system.engine.{appId}.stopped` — fires when `stop()` is called.
+     * - `system.escalation.{id}.created` — fires from the hook Leg1 path
+     *   (YAML `escalation:` block) when the escalation row commits.
+     *
      * @param config - Engine connection, worker definitions, app ID, and options.
      * @returns A running HotMesh instance joined to the quorum.
      */
@@ -196,6 +203,24 @@ class HotMesh {
             });
         }
         await Init.doWork(instance, config, instance.logger);
+        // Thread events.publish to the store (used by the hook Leg1 path and deploy).
+        if (config.events?.publish && instance.engine?.store) {
+            instance.engine.store.eventsPublish = config.events.publish;
+        }
+        // Retain for stop() lifecycle event.
+        if (config.events?.publish) {
+            instance._eventsPublish = config.events.publish;
+            const ts = new Date().toISOString();
+            const event = {
+                event_id: `${config.appId}:started:${ts}`,
+                type: `system.engine.${config.appId}.started`,
+                ts,
+                namespace: instance.namespace,
+                app_id: config.appId,
+                data: { appId: config.appId, guid: instance.guid },
+            };
+            void Promise.resolve(config.events.publish(event)).catch(() => { });
+        }
         return instance;
     }
     /**
@@ -489,6 +514,18 @@ class HotMesh {
         this.workers?.forEach((worker) => {
             worker.stop();
         });
+        if (this._eventsPublish) {
+            const ts = new Date().toISOString();
+            const event = {
+                event_id: `${this.appId}:stopped:${ts}`,
+                type: `system.engine.${this.appId}.stopped`,
+                ts,
+                namespace: this.namespace,
+                app_id: this.appId,
+                data: { appId: this.appId, guid: this.guid },
+            };
+            void Promise.resolve(this._eventsPublish(event)).catch(() => { });
+        }
     }
     /**
      * @private

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

@@ -71,6 +71,18 @@ const KVTables = (context) => ({
                 await client.release();
             }
         }
+        // Fire system.engine.{appId}.deployed post-deploy (best-effort).
+        if (context.eventsPublish) {
+            const ts = new Date().toISOString();
+            void Promise.resolve(context.eventsPublish({
+                event_id: `${appName}:deployed:${ts}`,
+                type: `system.engine.${appName}.deployed`,
+                ts,
+                namespace: appName,
+                app_id: appName,
+                data: { appId: appName },
+            })).catch(() => { });
+        }
     },
     getAdvisoryLockId(appName) {
         return this.hashStringToInt(appName);

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

@@ -19,6 +19,8 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     pgClient: PostgresClientType;
     kvTables: ReturnType<typeof KVTables>;
     isScout: boolean;
+    /** Set by HotMesh.init() when `events.publish` is configured. Used by hook.ts Leg1 path. */
+    eventsPublish?: (event: import('../../../../types/system_events').SystemEvent) => void | Promise<void>;
     transact(): ProviderTransaction;
     constructor(storeClient: ProviderClient);
     init(namespace: string, appId: string, logger: ILogger, guid?: string, role?: string): Promise<HotMeshApps>;
@@ -265,7 +267,7 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     updateEscalation(params: import('../../../../types/hmsh_escalations').UpdateEscalationParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     appendEscalationMilestones(params: import('../../../../types/hmsh_escalations').AppendMilestonesParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     claimManyEscalations(params: import('../../../../types/hmsh_escalations').ClaimManyParams): Promise<{
-        claimed: number;
+        entries: import('../../../../types/hmsh_escalations').EscalationEntry[];
         skipped: number;
     }>;
     escalateManyEscalationsToRole(params: import('../../../../types/hmsh_escalations').EscalateManyToRoleParams): Promise<number>;

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

@@ -1439,7 +1439,7 @@ class PostgresStoreService extends __1.StoreService {
      * idempotent re-runs after a crash.
      */
     addEscalationToTransaction(params, transaction) {
-        transaction.addCommand(this._escalationInsertSql, this._escalationInsertParams(params), 'void');
+        transaction.addCommand(this._escalationInsertSql + ' RETURNING *', this._escalationInsertParams(params), 'object');
     }
     /**
      * Full-fidelity INSERT for data migration. Preserves the original `id` (UUID),
@@ -1827,22 +1827,24 @@ class PostgresStoreService extends __1.StoreService {
         FROM target
         WHERE public.hmsh_escalations.id = target.id
           AND target.status = 'pending'
-        RETURNING public.hmsh_escalations.id
+        RETURNING public.hmsh_escalations.*
       )
       SELECT t.id, t.status AS prior_status,
         CASE
           WHEN c.id IS NOT NULL THEN 'cancelled'
           WHEN t.id IS NULL     THEN 'not-found'
           ELSE 'already-terminal'
-        END AS outcome
+        END AS outcome,
+        row_to_json(c.*) AS entry_json
       FROM (SELECT * FROM target) t
-      FULL OUTER JOIN (SELECT id FROM cancelled) c ON c.id = t.id
+      FULL OUTER JOIN (SELECT * FROM cancelled) c ON c.id = t.id
     `, namespace ? [id, namespace] : [id]);
         if (!result.rows[0] || result.rows[0].outcome === 'not-found')
             return { ok: false, reason: 'not-found' };
         if (result.rows[0].outcome === 'already-terminal')
             return { ok: false, reason: 'already-terminal' };
-        return { ok: true };
+        const entry = result.rows[0].entry_json;
+        return { ok: true, entry };
     }
     async escalateEscalationToRole(params) {
         const { id, targetRole, namespace } = params;
@@ -1947,9 +1949,10 @@ class PostgresStoreService extends __1.StoreService {
        WHERE id = ANY($3::uuid[])
          ${namespace ? 'AND namespace = $4' : ''}
          AND status = 'pending'
-         AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $1)`, namespace ? [assignee, durationMinutes, ids, namespace] : [assignee, durationMinutes, ids]);
-        const claimed = result.rowCount ?? 0;
-        return { claimed, skipped: ids.length - claimed };
+         AND (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW() OR assigned_to = $1)
+       RETURNING *`, namespace ? [assignee, durationMinutes, ids, namespace] : [assignee, durationMinutes, ids]);
+        const entries = result.rows;
+        return { entries, skipped: ids.length - entries.length };
     }
     async escalateManyEscalationsToRole(params) {
         const { ids, namespace, targetRole } = params;

package/build/types/durable.d.ts

@@ -395,6 +395,12 @@ type WorkflowDataType = {
 type Connection = ProviderConfig | ProvidersConfig;
 type ClientConfig = {
     connection: Connection;
+    /**
+     * Optional system-event sink. When set, `client.escalations.*` operations
+     * call `events.publish` post-commit from the invoking process. Wires the
+     * same hook as `HotMeshConfig.events` for direct-client callers.
+     */
+    events?: import('./system_events').EventsConfig;
 };
 type Registry = {
     [key: string]: Function;
@@ -442,6 +448,11 @@ type WorkerConfig = {
         user: string;
         password: string;
     };
+    /**
+     * Optional system-event sink. When set, the worker fires `events.publish`
+     * on `system.worker.{taskQueue}.started` and `system.worker.{taskQueue}.stopped`.
+     */
+    events?: import('./system_events').EventsConfig;
 };
 type FindWhereQuery = {
     field: string;

package/build/types/hmsh_escalations.d.ts

@@ -106,6 +106,7 @@ export type ReleaseEscalationResult = {
 };
 export type CancelEscalationResult = {
     ok: true;
+    entry: EscalationEntry;
 } | {
     ok: false;
     reason: 'not-found' | 'already-terminal';

package/build/types/hotmesh.d.ts

@@ -309,6 +309,23 @@ type HotMeshConfig = {
     taskQueue?: string;
     engine?: HotMeshEngine;
     workers?: HotMeshWorker[];
+    /**
+     * Optional system-event sink. When provided, the engine calls
+     * `events.publish` post-commit for each durable transition it performs
+     * (escalation lifecycle, engine start/stop, deploy). Fire-and-forget.
+     *
+     * @example
+     * ```typescript
+     * const hotMesh = await HotMesh.init({
+     *   appId: 'myapp',
+     *   engine: { connection: { class: Postgres, options: { ... } } },
+     *   events: {
+     *     publish: (e) => nats.publish(e.type, JSON.stringify(e)),
+     *   },
+     * });
+     * ```
+     */
+    events?: import('./system_events').EventsConfig;
 };
 type HotMeshGraph = {
     /**

package/build/types/index.d.ts

@@ -26,3 +26,4 @@ export { context, Context, Counter, Meter, metrics, propagation, SpanContext, Sp
 export { WorkListTaskType } from './task';
 export { TransitionMatch, TransitionRule, Transitions } from './transition';
 export { ConditionQueueConfig, EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, } from './hmsh_escalations';
+export { EscalationVerb, EngineVerb, WorkerVerb, SystemEvent, EventsConfig } from './system_events';

package/build/types/system_events.d.ts

@@ -0,0 +1,178 @@
+/**
+ * System-event emission surface for HotMesh lifecycle transitions.
+ *
+ * The performing actor — the one engine/SDK call that commits a durable
+ * transition — fires `EventsConfig.publish` exactly once, inline,
+ * post-commit. The hook is fire-and-forget; the SDK never awaits it.
+ *
+ * ## Ontology
+ *
+ * Every event has a canonical `type` string and a `data` payload.
+ * Consumers pattern-match on `type` and cherry-pick fields from `data`.
+ *
+ * ### Escalation lifecycle  (`system.escalation.{id}.{verb}`)
+ *
+ * | verb        | trigger                                                  | `data` shape        |
+ * |-------------|----------------------------------------------------------|---------------------|
+ * | `created`   | `client.create()` or hook Leg1 INSERT                    | full `EscalationEntry` row |
+ * | `claimed`   | `client.claim()` / `client.claimByMetadata()`            | full `EscalationEntry` row |
+ * | `released`  | `client.release()`                                       | full `EscalationEntry` row |
+ * | `reassigned`| `client.escalateToRole()` / role change                  | full `EscalationEntry` row |
+ * | `resolved`  | `client.resolve()` / `client.resolveByMetadata()`        | full `EscalationEntry` row |
+ * | `cancelled` | `client.cancel()`                                        | full `EscalationEntry` row |
+ *
+ * ### Engine lifecycle  (`system.engine.{appId}.{verb}`)
+ *
+ * | verb       | trigger                          | `data` shape                     |
+ * |------------|----------------------------------|----------------------------------|
+ * | `started`  | `HotMesh.init()` completes       | `{ appId: string, guid: string }` |
+ * | `stopped`  | `hotMesh.stop()` called          | `{ appId: string, guid: string }` |
+ * | `deployed` | `kvTables.deploy()` completes    | `{ appId: string }`              |
+ *
+ * ### Worker lifecycle  (`system.worker.{taskQueue}.{verb}`)
+ *
+ * | verb       | trigger                          | `data` shape                                 |
+ * |------------|----------------------------------|----------------------------------------------|
+ * | `started`  | `Durable.Worker.create()` ready  | `{ taskQueue: string, appId: string }`       |
+ * | `stopped`  | `worker.stop()` called           | `{ taskQueue: string, appId: string }`       |
+ *
+ * ## Registration — three construction sites
+ *
+ * **Site 1 — YAML DAG / hook Leg1 (escalation `created` + engine events):**
+ * ```typescript
+ * import { HotMesh } from '@hotmeshio/hotmesh';
+ * const hm = await HotMesh.init({
+ *   appId: 'myapp',
+ *   engine: { connection },
+ *   events: { publish: (e) => bus.emit(e.type, e) },
+ * });
+ * ```
+ *
+ * **Site 2 — Standalone `EscalationClientService` (all 6 verbs):**
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * const client = new Escalations.Client({
+ *   connection,
+ *   events: { publish: (e) => bus.emit(e.type, e) },
+ * });
+ * ```
+ *
+ * **Site 3 — `Durable.Client` (all 6 verbs via `.escalations`):**
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * const client = new Durable.Client({
+ *   connection,
+ *   events: { publish: (e) => bus.emit(e.type, e) },
+ * });
+ * // client.escalations.* operations now emit lifecycle events
+ * ```
+ *
+ * ## Event ID format
+ *
+ * `event_id` is collision-proof across recurrences:
+ * - Escalation: `${id}:${verb}:${updated_at_iso}` — claim→release→reclaim
+ *   produces distinct IDs because `updated_at` changes on each transition.
+ * - Engine / worker: `${app_id_or_queue}:${verb}:${ts}`.
+ *
+ * ## Fire-and-forget contract
+ *
+ * The SDK wraps every `publish` call in
+ * `void Promise.resolve(publish(event)).catch(() => {})`.
+ * A slow or throwing `publish` implementation never blocks or fails the
+ * committed operation. Use an in-process buffer or async queue if you need
+ * back-pressure.
+ *
+ * @example
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Durable.Client({
+ *   connection: { class: Postgres, options: { connectionString: process.env.DATABASE_URL } },
+ *   events: {
+ *     publish: (event) => {
+ *       if (event.type.endsWith('.created')) {
+ *         // new escalation — route to the right team
+ *         dispatch(event.data as EscalationEntry);
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+/** Verbs for escalation lifecycle transitions. */
+export type EscalationVerb = 'created' | 'claimed' | 'released' | 'reassigned' | 'resolved' | 'cancelled';
+/** Verbs for engine lifecycle transitions. */
+export type EngineVerb = 'started' | 'stopped' | 'deployed';
+/** Verbs for worker lifecycle transitions. */
+export type WorkerVerb = 'started' | 'stopped';
+/**
+ * Canonical lifecycle event emitted by the SDK post-commit.
+ *
+ * `event_id` is stable across replays:
+ *   - Escalation transitions: `${id}:${verb}:${updated_at_iso}` — unique
+ *     per transition; a re-claim after release gets a new `updated_at`.
+ *   - Engine / worker events: `${app_id}:${verb}:${ts}`.
+ *
+ * `data` carries the full committed row (escalation entry) or lifecycle
+ * metadata (engine/worker). Consumers cherry-pick what they need; nothing
+ * is pre-projected so the shape is future-proof.
+ */
+export interface SystemEvent {
+    /** Stable, unique ID per durable transition. */
+    event_id: string;
+    /**
+     * Canonical topic string.
+     *
+     * | Class       | Pattern                               |
+     * |-------------|---------------------------------------|
+     * | escalation  | `system.escalation.{id}.{verb}`       |
+     * | engine      | `system.engine.{appId}.{verb}`        |
+     * | worker      | `system.worker.{taskQueue}.{verb}`    |
+     */
+    type: string;
+    /** ISO timestamp at emit time (wall-clock, post-commit). */
+    ts: string;
+    namespace: string;
+    app_id: string;
+    workflow_id?: string;
+    topic?: string;
+    origin_id?: string;
+    parent_id?: string;
+    trace_id?: string;
+    span_id?: string;
+    /**
+     * Full committed row for escalation events; lifecycle metadata for
+     * engine/worker events. Long-tail and hike-mono each cherry-pick fields
+     * for their own event shape.
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * System-event sink configuration. Attach to `HotMeshConfig.events`,
+ * `EscalationClientConfig.events`, or `ClientConfig.events` to receive
+ * lifecycle events from the SDK.
+ *
+ * The SDK calls `publish` after each durable transition commits, from the
+ * single actor that performed the commit. In a multi-container fleet every
+ * container's SDK calls its own `publish` hook — and only for the work it
+ * performed — so exactly one container's `publish` fires per real event.
+ *
+ * @example
+ * ```typescript
+ * const events: EventsConfig = {
+ *   publish: (event) => {
+ *     // map SystemEvent → your LTEvent shape and hand to NATS/Socket.IO
+ *     eventRegistry.publish(mapToLTEvent(event));
+ *   },
+ * };
+ * ```
+ */
+export interface EventsConfig {
+    /**
+     * Called post-commit by the performing actor. Fire-and-forget — the SDK
+     * does not await the return value; a thrown/rejected promise is silently
+     * swallowed so the committed call is never failed by a publish error.
+     */
+    publish: (event: SystemEvent) => void | Promise<void>;
+}

package/build/types/system_events.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * System-event emission surface for HotMesh lifecycle transitions.
+ *
+ * The performing actor — the one engine/SDK call that commits a durable
+ * transition — fires `EventsConfig.publish` exactly once, inline,
+ * post-commit. The hook is fire-and-forget; the SDK never awaits it.
+ *
+ * ## Ontology
+ *
+ * Every event has a canonical `type` string and a `data` payload.
+ * Consumers pattern-match on `type` and cherry-pick fields from `data`.
+ *
+ * ### Escalation lifecycle  (`system.escalation.{id}.{verb}`)
+ *
+ * | verb        | trigger                                                  | `data` shape        |
+ * |-------------|----------------------------------------------------------|---------------------|
+ * | `created`   | `client.create()` or hook Leg1 INSERT                    | full `EscalationEntry` row |
+ * | `claimed`   | `client.claim()` / `client.claimByMetadata()`            | full `EscalationEntry` row |
+ * | `released`  | `client.release()`                                       | full `EscalationEntry` row |
+ * | `reassigned`| `client.escalateToRole()` / role change                  | full `EscalationEntry` row |
+ * | `resolved`  | `client.resolve()` / `client.resolveByMetadata()`        | full `EscalationEntry` row |
+ * | `cancelled` | `client.cancel()`                                        | full `EscalationEntry` row |
+ *
+ * ### Engine lifecycle  (`system.engine.{appId}.{verb}`)
+ *
+ * | verb       | trigger                          | `data` shape                     |
+ * |------------|----------------------------------|----------------------------------|
+ * | `started`  | `HotMesh.init()` completes       | `{ appId: string, guid: string }` |
+ * | `stopped`  | `hotMesh.stop()` called          | `{ appId: string, guid: string }` |
+ * | `deployed` | `kvTables.deploy()` completes    | `{ appId: string }`              |
+ *
+ * ### Worker lifecycle  (`system.worker.{taskQueue}.{verb}`)
+ *
+ * | verb       | trigger                          | `data` shape                                 |
+ * |------------|----------------------------------|----------------------------------------------|
+ * | `started`  | `Durable.Worker.create()` ready  | `{ taskQueue: string, appId: string }`       |
+ * | `stopped`  | `worker.stop()` called           | `{ taskQueue: string, appId: string }`       |
+ *
+ * ## Registration — three construction sites
+ *
+ * **Site 1 — YAML DAG / hook Leg1 (escalation `created` + engine events):**
+ * ```typescript
+ * import { HotMesh } from '@hotmeshio/hotmesh';
+ * const hm = await HotMesh.init({
+ *   appId: 'myapp',
+ *   engine: { connection },
+ *   events: { publish: (e) => bus.emit(e.type, e) },
+ * });
+ * ```
+ *
+ * **Site 2 — Standalone `EscalationClientService` (all 6 verbs):**
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * const client = new Escalations.Client({
+ *   connection,
+ *   events: { publish: (e) => bus.emit(e.type, e) },
+ * });
+ * ```
+ *
+ * **Site 3 — `Durable.Client` (all 6 verbs via `.escalations`):**
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * const client = new Durable.Client({
+ *   connection,
+ *   events: { publish: (e) => bus.emit(e.type, e) },
+ * });
+ * // client.escalations.* operations now emit lifecycle events
+ * ```
+ *
+ * ## Event ID format
+ *
+ * `event_id` is collision-proof across recurrences:
+ * - Escalation: `${id}:${verb}:${updated_at_iso}` — claim→release→reclaim
+ *   produces distinct IDs because `updated_at` changes on each transition.
+ * - Engine / worker: `${app_id_or_queue}:${verb}:${ts}`.
+ *
+ * ## Fire-and-forget contract
+ *
+ * The SDK wraps every `publish` call in
+ * `void Promise.resolve(publish(event)).catch(() => {})`.
+ * A slow or throwing `publish` implementation never blocks or fails the
+ * committed operation. Use an in-process buffer or async queue if you need
+ * back-pressure.
+ *
+ * @example
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Durable.Client({
+ *   connection: { class: Postgres, options: { connectionString: process.env.DATABASE_URL } },
+ *   events: {
+ *     publish: (event) => {
+ *       if (event.type.endsWith('.created')) {
+ *         // new escalation — route to the right team
+ *         dispatch(event.data as EscalationEntry);
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/index.ts

@@ -52,3 +52,4 @@ export {
 };
 
 export * as Types from './types';
+export type { EventsConfig, SystemEvent } from './types/system_events';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.22.3",
+  "version": "0.22.5",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -89,6 +89,7 @@
     "prove": "docker compose exec hotmesh npx vitest run tests/durable 2>&1 | tee /tmp/hmsh-durable.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-durable.txt | tail -5",
     "prove:escalations": "docker compose exec hotmesh npx vitest run tests/durable/escalations/postgres.test.ts 2>&1 | tee /tmp/hmsh-escalations.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-escalations.txt | tail -5",
     "prove:migrations": "docker compose exec hotmesh npx vitest run tests/durable/migrations/postgres.test.ts 2>&1 | tee /tmp/hmsh-migrations.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-migrations.txt | tail -5",
+    "prove:events": "docker compose exec hotmesh npx vitest run tests/durable/events/postgres.test.ts 2>&1 | tee /tmp/hmsh-events.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-events.txt | tail -5",
     "prove:functional": "docker compose exec hotmesh npx vitest run tests/functional 2>&1 | tee /tmp/hmsh-functional.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-functional.txt | tail -5",
     "prove:all": "docker compose exec hotmesh npx vitest run tests/ 2>&1 | tee /tmp/hmsh-all.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-all.txt | tail -5",
     "prove:file": "f() { docker compose exec hotmesh npx vitest run \"$@\" 2>&1 | tee /tmp/hmsh-file.txt && grep -E 'FAIL|Tests |Files ' /tmp/hmsh-file.txt | tail -5; }; f"