@hotmeshio/hotmesh 0.22.2 → 0.22.4

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

@@ -54,6 +54,8 @@ export interface EscalationEntry {
     trace_id: string | null;
     span_id: string | null;
     expires_at: Date | null;
+    /** Nullable passthrough column — populated when downstream needs task-level context. */
+    task_id: string | null;
     created_at: Date;
     updated_at: Date;
     /** Computed by list(): true when the row is claimable (no active assignee or expired claim). */
@@ -68,6 +70,7 @@ export interface EscalationEntry {
 export type ClaimEscalationResult = {
     ok: true;
     entry: EscalationEntry;
+    isExtension: boolean;
 } | {
     ok: false;
     reason: 'not-found' | 'conflict';
@@ -89,18 +92,21 @@ export type ClaimByMetadataResult = {
 };
 export type ResolveEscalationResult = {
     ok: true;
+    entry: EscalationEntry;
 } | {
     ok: false;
     reason: 'not-found' | 'already-resolved' | 'already-cancelled';
 };
 export type ReleaseEscalationResult = {
     ok: true;
+    entry: EscalationEntry;
 } | {
     ok: false;
     reason: 'not-found' | 'wrong-assignee';
 };
 export type CancelEscalationResult = {
     ok: true;
+    entry: EscalationEntry;
 } | {
     ok: false;
     reason: 'not-found' | 'already-terminal';
@@ -119,11 +125,51 @@ export interface ListEscalationsParams {
     originId?: string;
     /** When true, returns only rows without an active claim. When false, returns only actively claimed rows. */
     available?: boolean;
+    /** Exact priority match. */
+    priority?: number;
+    /** JSONB containment filter — rows whose `metadata` contains all provided keys/values. */
+    metadata?: Record<string, unknown>;
+    /** Filter by a set of UUIDs. */
+    ids?: string[];
+    /** Filter by `task_id` column. */
+    taskId?: string;
     sortBy?: 'created_at' | 'priority' | 'updated_at';
     sortOrder?: 'asc' | 'desc';
+    /**
+     * Multi-column sort. When provided, supersedes `sortBy`/`sortOrder`.
+     * Columns are applied left to right.
+     */
+    orderBy?: Array<{
+        column: 'priority' | 'created_at' | 'updated_at' | 'resolved_at' | 'role' | 'type';
+        direction: 'asc' | 'desc';
+    }>;
     limit?: number;
     offset?: number;
 }
+export interface StatsEscalationsParams {
+    namespace?: string;
+    /** RBAC scope — when an empty array is provided, all counts are zero. */
+    roles?: string[];
+    /** Counting window for created/resolved. Default: '24h'. */
+    period?: '1h' | '24h' | '7d' | '30d';
+}
+export interface EscalationStats {
+    pending: number;
+    claimed: number;
+    created: number;
+    resolved: number;
+    by_role: Array<{
+        role: string;
+        pending: number;
+        claimed: number;
+    }>;
+    by_type: Array<{
+        type: string;
+        pending: number;
+        claimed: number;
+        resolved: number;
+    }>;
+}
 export interface CreateEscalationParams {
     namespace?: string;
     appId?: string;
@@ -144,6 +190,7 @@ export interface CreateEscalationParams {
     createdBy?: string;
     traceId?: string;
     spanId?: string;
+    taskId?: string;
     escalationPayload?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     envelope?: Record<string, unknown>;
@@ -161,6 +208,7 @@ export interface UpdateEscalationParams {
     description?: string;
     priority?: number;
     role?: string;
+    taskId?: string;
     /** Merged into existing metadata (keys overwritten, others preserved) */
     metadata?: Record<string, unknown>;
     /** Replaces existing envelope */
@@ -195,6 +243,8 @@ export interface ClaimByMetadataParams {
     assignee?: string;
     durationMinutes?: number;
     roles?: string[];
+    /** Merged (not replaced) into the claimed row's metadata in the same atomic UPDATE. */
+    metadata?: Record<string, unknown>;
 }
 export interface ReleaseEscalationParams {
     id: string;
@@ -219,6 +269,27 @@ export interface EscalateToRoleParams {
     targetRole: string;
     namespace?: string;
 }
+export interface ClaimManyParams {
+    ids: string[];
+    namespace?: string;
+    assignee: string;
+    durationMinutes?: number;
+}
+export interface EscalateManyToRoleParams {
+    ids: string[];
+    namespace?: string;
+    targetRole: string;
+}
+export interface UpdateManyPriorityParams {
+    ids: string[];
+    namespace?: string;
+    priority: number;
+}
+export interface ResolveManyParams {
+    ids: string[];
+    namespace?: string;
+    resolverPayload?: Record<string, unknown>;
+}
 /**
  * Full-fidelity migration params. Extends `CreateEscalationParams` with:
  * - `id` (required) — preserves the original UUID; no auto-generation

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.2",
+  "version": "0.22.4",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -86,9 +86,10 @@
     "test:trigger": "vitest run tests/unit/services/activities/trigger.test.ts",
     "test:virtual": "vitest run tests/virtual",
     "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"