@hotmeshio/hotmesh 0.22.2 → 0.22.4

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.2",
+    "version": "0.22.4",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -88,6 +88,8 @@
         "test:unit": "vitest run tests/unit",
         "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

@@ -4,6 +4,11 @@ import { EscalationClientService } from '../escalations/client';
 /**
  * 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 +19,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

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
@@ -286,9 +298,9 @@ class ClientService {
             },
         };
         this.connection = config.connection;
-        // Inject our getHotMeshClient so the escalation client shares the same engine pool.
         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

@@ -478,6 +478,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 +517,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
      */

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

@@ -1,15 +1,22 @@
 import { HotMesh } from '../hotmesh';
+import { EventsConfig } from '../../types/system_events';
 import { Connection } from '../../types/durable';
-import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams } from '../../types/hmsh_escalations';
-type GetHotMeshFn = (topic: string | null, namespace?: string) => Promise<HotMesh>;
+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>;
 export interface EscalationClientConfig {
     /** Postgres connection options — used when creating a standalone EscalationClient. */
     connection?: Connection;
     /**
      * Inject a pre-existing `getHotMeshClient` function (e.g. from Durable.Client).
-     * When provided, the client reuses the caller's engine pool — no second connection.
+     * 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,16 +55,27 @@ export interface EscalationClientConfig {
  */
 export declare class EscalationClientService {
     private readonly _engine;
-    private readonly _connection?;
+    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;
     /**
      * Returns all escalation rows matching the given filters. Each row includes
      * a computed `available` field (true = claimable). Supports `sortBy`,
-     * `sortOrder`, and multi-role `roles[]` filter.
+     * `sortOrder`, `orderBy[]`, and multi-role `roles[]` filter.
      */
     list(params?: ListEscalationsParams): Promise<EscalationEntry[]>;
     /**
@@ -84,12 +102,14 @@ export declare class EscalationClientService {
     /**
      * Atomically claims an escalation by UUID. Implicit model: `status` stays
      * `'pending'`; claim is expressed via `assigned_to` + `assigned_until`.
+     * Returns `isExtension: true` when the same assignee re-claims a row they already hold.
      */
     claim(params: ClaimEscalationParams): Promise<ClaimEscalationResult>;
     /**
      * Atomically claims the highest-priority pending escalation whose `metadata`
-     * contains the given key/value. Returns `isExtension: true` when the same
-     * assignee re-claims a row they already hold (extends the expiry).
+     * contains the given key/value. Optionally merges `metadata` into the claimed row
+     * in the same atomic UPDATE. Returns `isExtension: true` when the same assignee
+     * re-claims a row they already hold (extends the expiry).
      */
     claimByMetadata(params: ClaimByMetadataParams): Promise<ClaimByMetadataResult>;
     /** Releases a claimed escalation, returning it to available status. */
@@ -105,14 +125,17 @@ export declare class EscalationClientService {
      */
     cancel(id: string, namespace?: string): Promise<CancelEscalationResult>;
     /**
-     * Signal-first resolve: marks the escalation resolved **and** delivers the
-     * signal to the waiting workflow in a single held transaction. If signal
-     * delivery fails, the transaction rolls back — `committed: false`.
+     * Resolves a pending escalation by UUID. Uses an explicit Postgres transaction
+     * with FOR UPDATE + WHERE guard: only one concurrent caller can commit the
+     * status change; the committed resolved row with its `signal_key` is the
+     * 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.
      */
     resolve(params: ResolveEscalationParams, namespace?: string): Promise<ResolveEscalationResult>;
     /**
      * Resolves the highest-priority matching escalation by metadata filter,
-     * then delivers its signal.
+     * then delivers its signal. Same transaction + WHERE guard semantics as `resolve()`.
      */
     resolveByMetadata(params: ResolveByMetadataParams, namespace?: string): Promise<ResolveEscalationResult>;
     /**
@@ -125,6 +148,40 @@ export declare class EscalationClientService {
      * from `assigned_until`. Kept for API compatibility.
      */
     releaseExpired(namespace?: string): Promise<number>;
+    /**
+     * Bulk-claims up to `ids.length` pending escalations in one statement.
+     * Returns `{ claimed, skipped }` — skipped rows are either already claimed
+     * by another assignee or non-existent. Implicit-claim semantics apply.
+     */
+    claimMany(params: ClaimManyParams): Promise<{
+        claimed: number;
+        skipped: number;
+    }>;
+    /**
+     * Bulk-reassigns pending escalations to a new role, clearing any current claim.
+     * Returns the count of rows updated.
+     */
+    escalateManyToRole(params: EscalateManyToRoleParams): Promise<number>;
+    /**
+     * Bulk-updates priority for pending escalations. Returns the count of rows updated.
+     */
+    updateManyPriority(params: UpdateManyPriorityParams): Promise<number>;
+    /**
+     * 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.
+     */
+    resolveMany(params: ResolveManyParams): Promise<EscalationEntry[]>;
+    /**
+     * Returns dashboard-ready escalation counts. `period` controls the window
+     * used for `created` and `resolved` counts (default `'24h'`). When `roles`
+     * is an empty array, all counts are zero (RBAC guard).
+     */
+    stats(params?: StatsEscalationsParams): Promise<EscalationStats>;
+    /**
+     * Returns the sorted list of distinct `type` values in the escalations table.
+     * Useful for populating filter dropdowns.
+     */
+    listDistinctTypes(namespace?: string): Promise<string[]>;
     static shutdown(): Promise<void>;
 }
-export {};

package/build/services/escalations/client.js

@@ -44,16 +44,51 @@ 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) {
-            this._connection = config.connection;
             this._engine = this._makeEngineFactory(config.connection);
         }
         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) => {
@@ -114,7 +149,7 @@ class EscalationClientService {
     /**
      * Returns all escalation rows matching the given filters. Each row includes
      * a computed `available` field (true = claimable). Supports `sortBy`,
-     * `sortOrder`, and multi-role `roles[]` filter.
+     * `sortOrder`, `orderBy[]`, and multi-role `roles[]` filter.
      */
     async list(params) {
         const hm = await this._engine(null, params?.namespace);
@@ -144,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.
@@ -162,24 +200,35 @@ class EscalationClientService {
     /**
      * Atomically claims an escalation by UUID. Implicit model: `status` stays
      * `'pending'`; claim is expressed via `assigned_to` + `assigned_until`.
+     * Returns `isExtension: true` when the same assignee re-claims a row they already hold.
      */
     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`
-     * contains the given key/value. Returns `isExtension: true` when the same
-     * assignee re-claims a row they already hold (extends the expiry).
+     * contains the given key/value. Optionally merges `metadata` into the claimed row
+     * in the same atomic UPDATE. Returns `isExtension: true` when the same assignee
+     * re-claims a row they already hold (extends the expiry).
      */
     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
@@ -187,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
@@ -195,17 +247,24 @@ 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;
     }
     /**
-     * Signal-first resolve: marks the escalation resolved **and** delivers the
-     * signal to the waiting workflow in a single held transaction. If signal
-     * delivery fails, the transaction rolls back — `committed: false`.
+     * Resolves a pending escalation by UUID. Uses an explicit Postgres transaction
+     * with FOR UPDATE + WHERE guard: only one concurrent caller can commit the
+     * status change; the committed resolved row with its `signal_key` is the
+     * 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.
      */
     async resolve(params, namespace) {
         const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
         const hm = await this._engine(null, ns);
-        const dbResult = await hm.engine.store.resolveEscalation({ id: params.id, resolverPayload: params.resolverPayload });
+        const store = hm.engine.store;
+        const dbResult = await store.resolveEscalation({ id: params.id, resolverPayload: params.resolverPayload });
         if (!dbResult.ok)
             return dbResult;
         if (dbResult.signalKey) {
@@ -214,16 +273,18 @@ class EscalationClientService {
                 data: params.resolverPayload ?? {},
             });
         }
-        return { ok: true };
+        this._emit('resolved', dbResult.entry);
+        return { ok: true, entry: dbResult.entry };
     }
     /**
      * Resolves the highest-priority matching escalation by metadata filter,
-     * then delivers its signal.
+     * then delivers its signal. Same transaction + WHERE guard semantics as `resolve()`.
      */
     async resolveByMetadata(params, namespace) {
         const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
         const hm = await this._engine(null, ns);
-        const dbResult = await hm.engine.store.resolveEscalationByMetadata({ key: params.key, value: params.value, resolverPayload: params.resolverPayload, roles: params.roles });
+        const store = hm.engine.store;
+        const dbResult = await store.resolveEscalationByMetadata({ key: params.key, value: params.value, resolverPayload: params.resolverPayload, roles: params.roles });
         if (!dbResult.ok)
             return dbResult;
         if (dbResult.signalKey) {
@@ -232,7 +293,8 @@ class EscalationClientService {
                 data: params.resolverPayload ?? {},
             });
         }
-        return { ok: true };
+        this._emit('resolved', dbResult.entry);
+        return { ok: true, entry: dbResult.entry };
     }
     /**
      * Full-fidelity migration: inserts an escalation row preserving the original
@@ -251,6 +313,62 @@ class EscalationClientService {
         const hm = await this._engine(null, namespace);
         return hm.engine.store.releaseExpiredEscalations(namespace);
     }
+    // ─── Bulk operations ────────────────────────────────────────────────────────
+    /**
+     * Bulk-claims up to `ids.length` pending escalations in one statement.
+     * Returns `{ claimed, skipped }` — skipped rows are either already claimed
+     * by another assignee or non-existent. Implicit-claim semantics apply.
+     */
+    async claimMany(params) {
+        const hm = await this._engine(null, params.namespace);
+        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.
+     * Returns the count of rows updated.
+     */
+    async escalateManyToRole(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.escalateManyEscalationsToRole(params);
+    }
+    /**
+     * Bulk-updates priority for pending escalations. Returns the count of rows updated.
+     */
+    async updateManyPriority(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.updateManyEscalationsPriority(params);
+    }
+    /**
+     * 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.
+     */
+    async resolveMany(params) {
+        const hm = await this._engine(null, params.namespace);
+        const entries = await hm.engine.store.resolveManyEscalations(params);
+        this._emitMany('resolved', entries);
+        return entries;
+    }
+    // ─── Aggregates ─────────────────────────────────────────────────────────────
+    /**
+     * Returns dashboard-ready escalation counts. `period` controls the window
+     * used for `created` and `resolved` counts (default `'24h'`). When `roles`
+     * is an empty array, all counts are zero (RBAC guard).
+     */
+    async stats(params) {
+        const hm = await this._engine(null, params?.namespace);
+        return hm.engine.store.escalationStats(params ?? {});
+    }
+    /**
+     * Returns the sorted list of distinct `type` values in the escalations table.
+     * Useful for populating filter dropdowns.
+     */
+    async listDistinctTypes(namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.listDistinctEscalationTypes(namespace);
+    }
     static async shutdown() {
         for (const [_, instance] of EscalationClientService.instances) {
             (await instance).stop();

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.
      */