@hotmeshio/hotmesh 0.22.0 → 0.22.2

package/build/index.d.ts

@@ -18,6 +18,7 @@ import * as KeyStore from './modules/key';
 import { ConnectorService as Connector } from './services/connector/factory';
 import { PostgresConnection as ConnectorPostgres } from './services/connector/providers/postgres';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
+import { Escalations } from './services/escalations';
 export { Connector, //factory
-ConnectorNATS, ConnectorPostgres, HotMesh, HotMeshConfig, Virtual, Durable, DBA, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
+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';

package/build/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.DBA = exports.Durable = exports.Virtual = exports.HotMesh = exports.ConnectorPostgres = exports.ConnectorNATS = exports.Connector = void 0;
+exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.DBA = exports.Escalations = exports.Durable = exports.Virtual = exports.HotMesh = exports.ConnectorPostgres = exports.ConnectorNATS = exports.Connector = void 0;
 const hotmesh_1 = require("./services/hotmesh");
 Object.defineProperty(exports, "HotMesh", { enumerable: true, get: function () { return hotmesh_1.HotMesh; } });
 const virtual_1 = require("./services/virtual");
@@ -62,4 +62,6 @@ const postgres_1 = require("./services/connector/providers/postgres");
 Object.defineProperty(exports, "ConnectorPostgres", { enumerable: true, get: function () { return postgres_1.PostgresConnection; } });
 const nats_1 = require("./services/connector/providers/nats");
 Object.defineProperty(exports, "ConnectorNATS", { enumerable: true, get: function () { return nats_1.NatsConnection; } });
+const escalations_1 = require("./services/escalations");
+Object.defineProperty(exports, "Escalations", { enumerable: true, get: function () { return escalations_1.Escalations; } });
 exports.Types = __importStar(require("./types"));

package/build/modules/utils.d.ts

@@ -13,6 +13,8 @@ export declare function getSystemHealth(): Promise<SystemHealth>;
 export declare function deepCopy<T>(obj: T): T;
 export declare function deterministicRandom(seed: number): number;
 export declare function guid(size?: number): string;
+/** Returns a standard RFC 4122 v4 UUID (e.g. for use as a DB primary key). */
+export declare function uuid(): string;
 export declare function sleepFor(ms: number): Promise<void>;
 export declare function sleepImmediate(): Promise<void>;
 export declare function XSleepFor(ms: number): {

package/build/modules/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.arrayToHash = exports.isStreamMessage = exports.parseStreamMessage = exports.normalizeRetryPolicy = exports.s = exports.isValidCron = exports.restoreHierarchy = exports.getValueByPath = exports.getIndexedHash = exports.getSymVal = exports.getSymKey = exports.formatISODate = exports.getTimeSeries = exports.getSubscriptionTopic = exports.findSubscriptionForTrigger = exports.findTopKey = exports.matchesStatus = exports.matchesStatusCode = exports.polyfill = exports.identifyProvider = exports.XSleepFor = exports.sleepImmediate = exports.sleepFor = exports.guid = exports.deterministicRandom = exports.deepCopy = exports.getSystemHealth = exports.hashOptions = void 0;
+exports.arrayToHash = exports.isStreamMessage = exports.parseStreamMessage = exports.normalizeRetryPolicy = exports.s = exports.isValidCron = exports.restoreHierarchy = exports.getValueByPath = exports.getIndexedHash = exports.getSymVal = exports.getSymKey = exports.formatISODate = exports.getTimeSeries = exports.getSubscriptionTopic = exports.findSubscriptionForTrigger = exports.findTopKey = exports.matchesStatus = exports.matchesStatusCode = exports.polyfill = exports.identifyProvider = exports.XSleepFor = exports.sleepImmediate = exports.sleepFor = exports.uuid = exports.guid = exports.deterministicRandom = exports.deepCopy = exports.getSystemHealth = exports.hashOptions = void 0;
 const os_1 = __importDefault(require("os"));
 const crypto_1 = require("crypto");
 const cron_parser_1 = require("cron-parser");
@@ -47,6 +47,11 @@ function guid(size = enums_1.HMSH_GUID_SIZE) {
     return `H` + (0, nanoid_1.nanoid)(size);
 }
 exports.guid = guid;
+/** Returns a standard RFC 4122 v4 UUID (e.g. for use as a DB primary key). */
+function uuid() {
+    return (0, crypto_1.randomUUID)();
+}
+exports.uuid = uuid;
 async function sleepFor(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.22.0",
+    "version": "0.22.2",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -50,7 +50,7 @@
         "test:durable:signal": "vitest run tests/durable/signal/postgres.test.ts",
         "test:durable:readonly": "docker compose --profile readonly up -d --build && docker compose exec hotmesh-readonly npx vitest run --config tests/durable/readonly/vitest.config.mts",
         "test:durable:unknown": "vitest run tests/durable/unknown/postgres.test.ts",
-        "test:durable:esclations": "HMSH_LOGLEVEL=info vitest run tests/durable/escalations",
+        "test:durable:escalations": "HMSH_LOGLEVEL=info vitest run tests/durable/escalations",
         "test:durable:exporter": "HMSH_LOGLEVEL=info vitest run tests/durable/exporter",
         "test:durable:exporter:debug": "EXPORT_DEBUG=1 HMSH_LOGLEVEL=error vitest run tests/durable/basic/postgres.test.ts",
         "test:durable:codec": "vitest run tests/durable/codec/postgres.test.ts",
@@ -85,7 +85,12 @@
         "test:sub:nats": "vitest run tests/functional/sub/providers/nats/nats.test.ts",
         "test:trigger": "vitest run tests/unit/services/activities/trigger.test.ts",
         "test:virtual": "vitest run tests/virtual",
-        "test:unit": "vitest run tests/unit"
+        "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: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"
     },
     "keywords": [
         "Invisible Infrastructure",

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

@@ -1,6 +1,6 @@
 import { HotMesh } from '../hotmesh';
 import { ClientConfig, ClientWorkflow, Connection, WorkflowOptions } from '../../types/durable';
-import { EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams } from '../../types/hmsh_escalations';
+import { EscalationClientService } from '../escalations/client';
 /**
  * Workflow client. Starts workflows, sends signals, and reads results.
  *
@@ -49,6 +49,13 @@ export declare class ClientService {
      * @private
      */
     static instances: Map<string, HotMesh | Promise<HotMesh>>;
+    /**
+     * Escalation queue operations — a thin proxy to `Escalations.Client` that
+     * reuses this Durable.Client's engine pool. Calling
+     * `client.escalations.list(...)` is identical to creating a separate
+     * `new Escalations.Client({ connection })` — just more convenient.
+     */
+    escalations: EscalationClientService;
     /**
      * @private
      */
@@ -97,243 +104,6 @@ export declare class ClientService {
      * @private
      */
     activateWorkflow(hotMesh: HotMesh, appId?: string, version?: string): Promise<void>;
-    /**
-     * Escalation queue operations over `public.hmsh_escalations` — a global
-     * table that surfaces workflow signal pauses as role-based, claimable,
-     * searchable queue items.
-     *
-     * When a YAML `hook` activity suspends with an `escalation:` block, or
-     * `Durable.workflow.condition(signalId, config)` fires, **one row is
-     * written atomically** with the workflow checkpoint — no enrichment step,
-     * no secondary round-trip. Every connected app shares the same table;
-     * rows are namespaced by `namespace` + `app_id`.
-     *
-     * **Status lifecycle:**
-     * ```
-     * pending → claimed → resolved
-     *         ↘ cancelled      (any non-terminal state)
-     *         ↗ pending        (via release or releaseExpired)
-     * ```
-     *
-     * **Typical human-in-the-loop flow:**
-     * ```typescript
-     * // 1. Workflow pauses and writes the escalation row automatically
-     * const decision = await Durable.workflow.condition('manager-approval', {
-     *   role: 'manager',
-     *   type: 'order-approval',
-     *   priority: 2,
-     *   metadata: { orderId },
-     * });
-     *
-     * // 2. Dashboard lists pending approvals for this role
-     * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
-     *
-     * // 3. Reviewer claims it (sets assigned_to + expiry)
-     * await client.escalations.claim({ id: item.id, assignee: 'alice@company.com' });
-     *
-     * // 4. Resolve atomically marks it resolved AND delivers the signal
-     * await client.escalations.resolve({
-     *   id: item.id,
-     *   resolverPayload: { approved: true },
-     * });
-     * // workflow resumes with { approved: true }
-     * ```
-     */
-    escalations: {
-        /**
-         * Returns all escalation rows matching the given filters.
-         *
-         * @example
-         * ```typescript
-         * // All pending approvals for the manager role
-         * const items = await client.escalations.list({ role: 'manager', status: 'pending' });
-         *
-         * // By workflow ID
-         * const items = await client.escalations.list({ workflowId: 'order-123' });
-         * ```
-         */
-        list: (params?: ListEscalationsParams) => Promise<EscalationEntry[]>;
-        /**
-         * Returns a single escalation row by its UUID primary key.
-         * Returns `null` if not found.
-         */
-        get: (id: string, namespace?: string) => Promise<EscalationEntry | null>;
-        /**
-         * Looks up an escalation row by its `signal_key` — the value that was
-         * passed to `condition()` or stored in the hook activity's collation rule.
-         * This is the same key used to deliver the signal via `hotMesh.signal()`.
-         *
-         * @example
-         * ```typescript
-         * const item = await client.escalations.getBySignalKey('manager-approval');
-         * ```
-         */
-        getBySignalKey: (signalKey: string, namespace?: string) => Promise<EscalationEntry | null>;
-        /**
-         * Creates a standalone escalation row that is **not** backed by a signal.
-         * `signal_key` is `null`. Useful for external task tracking that doesn't
-         * need to resume a workflow (e.g., audit tasks, out-of-band approvals).
-         *
-         * @example
-         * ```typescript
-         * const entry = await client.escalations.create({
-         *   role: 'support',
-         *   type: 'data-correction',
-         *   description: 'Fix the customer address',
-         *   metadata: { customerId: 'cust-42' },
-         * });
-         * ```
-         */
-        create: (params: CreateEscalationParams) => Promise<EscalationEntry>;
-        /**
-         * Patches an existing escalation row. All fields are optional — only
-         * provided fields are written. `metadata` is **merged**, not replaced.
-         *
-         * Signal routing fields (`signalKey`, `topic`, `workflowId`, …) can be
-         * enriched after the row is created — useful when the row is created
-         * before the workflow starts and routing context is not yet known.
-         *
-         * @example
-         * ```typescript
-         * await client.escalations.update({
-         *   id: item.id,
-         *   description: 'Updated description',
-         *   metadata: { extraKey: 'value' },  // merged into existing metadata
-         * });
-         * ```
-         */
-        update: (params: UpdateEscalationParams) => Promise<EscalationEntry | null>;
-        /**
-         * Appends one or more milestone entries to the escalation's
-         * `milestones` audit trail array. Milestones are append-only; they
-         * record events like state transitions, reviewer notes, or external
-         * system callbacks.
-         *
-         * @example
-         * ```typescript
-         * await client.escalations.appendMilestones({
-         *   id: item.id,
-         *   milestones: [{ at: new Date().toISOString(), by: 'alice', note: 'Reviewed' }],
-         * });
-         * ```
-         */
-        appendMilestones: (params: AppendMilestonesParams) => Promise<EscalationEntry | null>;
-        /**
-         * Atomically claims an escalation row by UUID. Sets `assigned_to`,
-         * `claimed_at`, and `claim_expires_at`. Returns `conflict` if another
-         * actor already holds the claim.
-         *
-         * @example
-         * ```typescript
-         * const result = await client.escalations.claim({
-         *   id: item.id,
-         *   assignee: 'alice@company.com',
-         *   durationMinutes: 30,
-         * });
-         * if (!result.ok) console.warn('Already claimed by someone else');
-         * ```
-         */
-        claim: (params: ClaimEscalationParams) => Promise<ClaimEscalationResult>;
-        /**
-         * Atomically claims the highest-priority pending escalation whose
-         * `metadata` contains the given key/value pair. Uses
-         * `FOR UPDATE SKIP LOCKED` so concurrent callers never double-claim.
-         *
-         * Returns `candidatesExist` to distinguish two cases:
-         * - `not-found, candidatesExist: 0` — no rows matched the metadata filter
-         * - `conflict, candidatesExist: N` — matching rows exist but all are claimed
-         *
-         * @example
-         * ```typescript
-         * const result = await client.escalations.claimByMetadata({
-         *   key: 'region',
-         *   value: 'west',
-         *   assignee: 'bob@company.com',
-         *   roles: ['manager'],
-         * });
-         * if (result.ok) console.log('Claimed:', result.entry.id);
-         * ```
-         */
-        claimByMetadata: (params: ClaimByMetadataParams) => Promise<ClaimByMetadataResult>;
-        /**
-         * Releases a claimed escalation, returning it to `pending` status and
-         * clearing `assigned_to` and `claim_expires_at`. The row is immediately
-         * available for other actors to claim.
-         *
-         * @example
-         * ```typescript
-         * await client.escalations.release({ id: item.id });
-         * ```
-         */
-        release: (params: ReleaseEscalationParams) => Promise<ReleaseEscalationResult>;
-        /**
-         * Reassigns the escalation to a different role, clearing any current
-         * claim and returning status to `pending`. Use when an escalation must
-         * be handled by a different team or tier.
-         *
-         * @example
-         * ```typescript
-         * await client.escalations.escalateToRole({ id: item.id, role: 'senior-manager' });
-         * ```
-         */
-        escalateToRole: (params: EscalateToRoleParams) => Promise<EscalationEntry | null>;
-        /**
-         * Terminates the escalation without delivering a signal. Rows in
-         * `pending` or `claimed` state move to `cancelled`. Terminal rows
-         * (`resolved`, `cancelled`) return `already-terminal`.
-         *
-         * @example
-         * ```typescript
-         * await client.escalations.cancel(item.id);
-         * ```
-         */
-        cancel: (id: string, namespace?: string) => Promise<CancelEscalationResult>;
-        /**
-         * Atomically marks the escalation `resolved` **and** delivers the
-         * signal to the waiting workflow — one round-trip, no separate
-         * `signal()` call required. If `signal_key` is null (standalone
-         * escalation), only the row is updated.
-         *
-         * @example
-         * ```typescript
-         * const result = await client.escalations.resolve({
-         *   id: item.id,
-         *   resolverPayload: { approved: true, note: 'LGTM' },
-         * });
-         * if (!result.ok) console.error(result.reason); // 'not-found' | 'already-resolved' | 'signal-failed'
-         * // workflow resumes with { approved: true, note: 'LGTM' }
-         * ```
-         */
-        resolve: (params: ResolveEscalationParams, namespace?: string) => Promise<ResolveEscalationResult>;
-        /**
-         * Resolves the highest-priority matching escalation by metadata filter,
-         * then delivers its signal. Identical semantics to `resolve()` but
-         * selects the target row by metadata key/value instead of UUID.
-         *
-         * @example
-         * ```typescript
-         * await client.escalations.resolveByMetadata({
-         *   key: 'orderId',
-         *   value: 'order-123',
-         *   resolverPayload: { approved: true },
-         * });
-         * ```
-         */
-        resolveByMetadata: (params: ResolveByMetadataParams, namespace?: string) => Promise<ResolveEscalationResult>;
-        /**
-         * Releases all claimed escalations whose `claim_expires_at` has lapsed,
-         * returning them to `pending` so they can be claimed again. Returns the
-         * number of rows released. Call periodically from a maintenance job or
-         * cron to prevent stale claims from blocking the queue.
-         *
-         * @example
-         * ```typescript
-         * const released = await client.escalations.releaseExpired();
-         * console.log(`Released ${released} expired claims`);
-         * ```
-         */
-        releaseExpired: (namespace?: string) => Promise<number>;
-    };
     /**
      * @private
      */