@hotmeshio/hotmesh 0.21.1 → 0.22.1

package/build/types/activity.d.ts

@@ -14,6 +14,8 @@ interface BaseActivity {
     settings?: Record<string, any>;
     job?: Record<string, any>;
     hook?: Record<string, any>;
+    /** When present on a hook activity, writes a row to public.hmsh_escalations at suspension time. Values may use `@pipe` expressions resolved against the current job context. */
+    escalation?: Record<string, any>;
     telemetry?: Record<string, any>;
     emit?: boolean;
     sleep?: number;

package/build/types/hmsh_escalations.d.ts

@@ -0,0 +1,240 @@
+export interface ConditionQueueConfig {
+    role?: string;
+    type?: string;
+    subtype?: string;
+    entity?: string;
+    priority?: number;
+    description?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    originId?: string;
+    parentId?: string;
+    initiatedBy?: string;
+    traceId?: string;
+    spanId?: string;
+    /** GIN-indexed; put claim/filter keys here */
+    metadata?: Record<string, unknown>;
+    /** Unindexed display/form context for resolver UIs */
+    envelope?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+export interface EscalationEntry {
+    id: string;
+    namespace: string;
+    app_id: string;
+    /** Job ID / Durable signalId; NULL for standalone (no-signal) escalations */
+    signal_key: string | null;
+    /** Hook topic for signal delivery */
+    topic: string | null;
+    workflow_id: string | null;
+    task_queue: string | null;
+    workflow_type: string | null;
+    type: string | null;
+    subtype: string | null;
+    entity: string | null;
+    description: string | null;
+    role: string | null;
+    status: 'pending' | 'claimed' | 'resolved' | 'cancelled' | 'expired';
+    priority: number;
+    assigned_to: string | null;
+    assigned_until: Date | null;
+    claimed_at: Date | null;
+    claim_expires_at: Date | null;
+    resolved_at: Date | null;
+    escalation_payload: Record<string, unknown> | null;
+    resolver_payload: Record<string, unknown> | null;
+    envelope: Record<string, unknown> | null;
+    metadata: Record<string, unknown> | null;
+    origin_id: string | null;
+    parent_id: string | null;
+    initiated_by: string | null;
+    created_by: string | null;
+    milestones: unknown[];
+    trace_id: string | null;
+    span_id: string | null;
+    expires_at: Date | null;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Result of `claim()` — identifies whether failure was due to the row not
+ * existing (`not-found`) or existing but locked / in a non-claimable state
+ * (`conflict`). Distinguishing these lets callers decide whether to retry or
+ * surface an error to the user.
+ */
+export type ClaimEscalationResult = {
+    ok: true;
+    entry: EscalationEntry;
+} | {
+    ok: false;
+    reason: 'not-found' | 'conflict';
+};
+/**
+ * Result of `claimByMetadata()`. Includes `candidatesExist` — the total
+ * count of rows matching the metadata filter regardless of claimability — so
+ * callers can distinguish "nothing matching at all" from "found candidates but
+ * all are locked or in-progress".
+ */
+export type ClaimByMetadataResult = {
+    ok: true;
+    entry: EscalationEntry;
+    candidatesExist: number;
+} | {
+    ok: false;
+    reason: 'not-found' | 'conflict';
+    candidatesExist: number;
+};
+export type ResolveEscalationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-found' | 'already-resolved' | 'already-cancelled' | 'signal-failed';
+};
+export type ReleaseEscalationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-found' | 'wrong-assignee';
+};
+export type CancelEscalationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not-found' | 'already-terminal';
+};
+export interface ListEscalationsParams {
+    namespace?: string;
+    role?: string;
+    type?: string;
+    subtype?: string;
+    entity?: string;
+    status?: string;
+    assignedTo?: string;
+    workflowId?: string;
+    originId?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CreateEscalationParams {
+    namespace?: string;
+    appId?: string;
+    signalKey?: string;
+    topic?: string;
+    workflowId?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    type?: string;
+    subtype?: string;
+    entity?: string;
+    description?: string;
+    role?: string;
+    priority?: number;
+    originId?: string;
+    parentId?: string;
+    initiatedBy?: string;
+    createdBy?: string;
+    traceId?: string;
+    spanId?: string;
+    escalationPayload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    envelope?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+/**
+ * Fields that can be patched on an existing escalation. All fields are
+ * optional — only provided fields are written. Signal routing fields
+ * (`signalKey`, `topic`, `workflowId`, `taskQueue`, `workflowType`) support
+ * the legacy two-step pattern where routing context is enriched after creation.
+ */
+export interface UpdateEscalationParams {
+    id: string;
+    namespace?: string;
+    description?: string;
+    priority?: number;
+    role?: string;
+    /** Merged into existing metadata (keys overwritten, others preserved) */
+    metadata?: Record<string, unknown>;
+    /** Replaces existing envelope */
+    envelope?: Record<string, unknown>;
+    /** Signal routing enrichment — equivalent to long-tail's enrichEscalationRouting */
+    signalKey?: string;
+    topic?: string;
+    workflowId?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    expiresAt?: Date;
+}
+export interface AppendMilestonesParams {
+    id: string;
+    namespace?: string;
+    milestones: Array<{
+        name: string;
+        value: unknown;
+        [key: string]: unknown;
+    }>;
+}
+export interface ClaimEscalationParams {
+    id: string;
+    namespace?: string;
+    assignee?: string;
+    durationMinutes?: number;
+}
+export interface ClaimByMetadataParams {
+    key: string;
+    value: unknown;
+    namespace?: string;
+    assignee?: string;
+    durationMinutes?: number;
+    roles?: string[];
+}
+export interface ReleaseEscalationParams {
+    id: string;
+    namespace?: string;
+    /** When provided, the release is rejected with `wrong-assignee` if the current assignee differs */
+    assignee?: string;
+}
+export interface ResolveEscalationParams {
+    id: string;
+    namespace?: string;
+    resolverPayload?: Record<string, unknown>;
+}
+export interface ResolveByMetadataParams {
+    key: string;
+    value: unknown;
+    namespace?: string;
+    resolverPayload?: Record<string, unknown>;
+    roles?: string[];
+}
+export interface EscalateToRoleParams {
+    id: string;
+    targetRole: string;
+    namespace?: string;
+}
+/**
+ * Full-fidelity migration params. Extends `CreateEscalationParams` with:
+ * - `id` (required) — preserves the original UUID; no auto-generation
+ * - lifecycle state fields (`status`, `assignedTo`, `claimExpiresAt`, …) — carry over
+ *   the exact state of the migrated row so in-flight escalations land correctly
+ * - `createdAt` / `updatedAt` — preserve original timestamps
+ *
+ * The underlying INSERT uses `ON CONFLICT (id) DO NOTHING`, so calling
+ * `migrate()` multiple times with the same ID is safe — subsequent calls
+ * return `null` without touching the existing row.
+ */
+export interface MigrateEscalationParams extends CreateEscalationParams {
+    /** Required — preserve the original UUID from the source table. */
+    id: string;
+    status?: 'pending' | 'claimed' | 'resolved' | 'cancelled' | 'expired';
+    assignedTo?: string;
+    claimExpiresAt?: Date;
+    claimedAt?: Date;
+    resolvedAt?: Date;
+    resolverPayload?: Record<string, unknown>;
+    milestones?: Array<{
+        name: string;
+        value: unknown;
+        [key: string]: unknown;
+    }>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/build/types/index.d.ts

@@ -25,4 +25,4 @@ export { ReclaimedMessageType, RetryPolicy, RouterConfig, StreamCode, StreamConf
 export { context, Context, Counter, Meter, metrics, propagation, SpanContext, Span, SpanStatus, SpanStatusCode, SpanKind, trace, Tracer, ValueType, } from './telemetry';
 export { WorkListTaskType } from './task';
 export { TransitionMatch, TransitionRule, Transitions } from './transition';
-export { ClaimSignalByMetadataParams, ClaimSignalParams, ClaimSignalResult, ConditionQueueConfig, EnqueueSignalParams, ListSignalsParams, ReleaseSignalResult, ResolveSignalByMetadataParams, ResolveSignalParams, ResolveSignalResult, SignalQueueEntry, } from './signal';
+export { ConditionQueueConfig, EscalationEntry, ClaimEscalationResult, ClaimByMetadataResult, ReleaseEscalationResult, ResolveEscalationResult, CancelEscalationResult, ListEscalationsParams, CreateEscalationParams, UpdateEscalationParams, AppendMilestonesParams, ClaimEscalationParams, ClaimByMetadataParams, ReleaseEscalationParams, ResolveEscalationParams, ResolveByMetadataParams, EscalateToRoleParams, MigrateEscalationParams, } from './hmsh_escalations';

package/build/types/provider.d.ts

@@ -101,6 +101,8 @@ export interface HSetOptions {
     nx?: boolean;
     ex?: number;
     entity?: string;
+    originId?: string;
+    parentId?: string;
 }
 export interface ZAddOptions {
     nx?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.21.1",
+  "version": "0.22.1",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -50,6 +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: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",
@@ -84,7 +85,13 @@
     "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/types/signal.d.ts

@@ -1,147 +0,0 @@
-/**
- * Represents a queued signal record in the hotmesh_signals table.
- * Created atomically with workflow suspension when condition() is called
- * with a queue configuration.
- */
-export interface SignalQueueEntry {
-    id: string;
-    namespace: string;
-    appId: string;
-    signalKey: string;
-    workflowId: string;
-    jobId?: string;
-    topic?: string;
-    status: 'pending' | 'claimed' | 'resolved' | 'expired' | 'released';
-    role?: string;
-    type?: string;
-    subtype?: string;
-    priority: number;
-    description?: string;
-    taskQueue?: string;
-    workflowType?: string;
-    assignedTo?: string;
-    claimedAt?: Date;
-    claimExpiresAt?: Date;
-    resolvedAt?: Date;
-    resolverPayload?: Record<string, unknown>;
-    envelope?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-    expiresAt?: Date;
-    createdAt: Date;
-    updatedAt: Date;
-}
-/**
- * Optional queue configuration passed to condition() to create a
- * richly-typed, indexed, claimable signal record alongside workflow suspension.
- *
- * metadata is GIN-indexed and used for claimByMetadata / resolveByMetadata queries.
- * envelope is unindexed and intended for display context (form schemas, etc.).
- */
-export interface ConditionQueueConfig {
-    role?: string;
-    type?: string;
-    subtype?: string;
-    priority?: number;
-    description?: string;
-    taskQueue?: string;
-    workflowType?: string;
-    assignedTo?: string;
-    metadata?: Record<string, unknown>;
-    envelope?: Record<string, unknown>;
-    durationMinutes?: number;
-}
-export interface EnqueueSignalParams {
-    namespace: string;
-    appId: string;
-    signalKey: string;
-    workflowId: string;
-    jobId?: string;
-    topic?: string;
-    role?: string;
-    type?: string;
-    subtype?: string;
-    priority?: number;
-    description?: string;
-    taskQueue?: string;
-    workflowType?: string;
-    assignedTo?: string;
-    metadata?: Record<string, unknown>;
-    envelope?: Record<string, unknown>;
-    expiresAt?: Date;
-}
-export interface ClaimSignalParams {
-    id: string;
-    assignee?: string;
-    durationMinutes?: number;
-}
-export interface ClaimSignalByMetadataParams {
-    key: string;
-    value: unknown;
-    assignee?: string;
-    durationMinutes?: number;
-}
-export interface ResolveSignalParams {
-    id: string;
-    resolverPayload?: Record<string, unknown>;
-}
-export interface ResolveSignalByMetadataParams {
-    key: string;
-    value: unknown;
-    resolverPayload?: Record<string, unknown>;
-}
-export interface ListSignalsParams {
-    status?: 'pending' | 'claimed' | 'resolved' | 'expired' | 'released';
-    role?: string;
-    taskQueue?: string;
-    limit?: number;
-    offset?: number;
-}
-/**
- * Result of a claim operation (by ID or by metadata).
- *
- * - ok: true  → signal was claimed; entry contains the full record
- * - ok: false, reason: 'not-found'  → no signal exists for the given id/metadata
- * - ok: false, reason: 'conflict'   → signal exists but was already claimed concurrently
- */
-export type ClaimSignalResult = {
-    ok: true;
-    entry: SignalQueueEntry;
-} | {
-    ok: false;
-    reason: 'not-found' | 'conflict';
-};
-/**
- * Result of a resolve operation (by ID or by metadata).
- *
- * - ok: true  → signal marked resolved and workflow signal delivered
- * - ok: false, reason: 'not-found'       → no pending/claimed signal found
- * - ok: false, reason: 'already-resolved' → signal exists but was already resolved (id-based only)
- * - ok: false, reason: 'signal-failed'    → DB record updated but workflow signal delivery failed;
- *                                            signalKey is provided so callers can retry delivery
- */
-export type ResolveSignalResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: 'not-found';
-} | {
-    ok: false;
-    reason: 'already-resolved';
-} | {
-    ok: false;
-    reason: 'signal-failed';
-    signalKey: string;
-};
-/**
- * Result of a release operation.
- *
- * - ok: true  → signal returned to pending
- * - ok: false, reason: 'not-found'    → no signal exists for this id
- * - ok: false, reason: 'wrong-status' → signal exists but is not in 'claimed' status
- */
-export type ReleaseSignalResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: 'not-found' | 'wrong-status';
-};