@hotmeshio/hotmesh 0.22.2 → 0.22.4

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);
@@ -166,6 +178,145 @@ const KVTables = (context) => ({
         ON ${jobsTable} (key) WHERE is_live;
       `);
         }
+        // v0.22.0: origin_id, parent_id on per-app jobs table (workflow lineage).
+        // ADD COLUMN IF NOT EXISTS on a nullable column with no DEFAULT is catalog-only
+        // in PG11+ — no table rewrite, brief AccessExclusiveLock only.
+        await client.query(`
+      ALTER TABLE ${jobsTable} ADD COLUMN IF NOT EXISTS origin_id TEXT;
+    `);
+        await client.query(`
+      ALTER TABLE ${jobsTable} ADD COLUMN IF NOT EXISTS parent_id TEXT;
+    `);
+        // Partial indexes — only cover the opt-in rows so build is near-instant.
+        const { rows: originIdxRows } = await client.query(`SELECT 1 FROM pg_indexes WHERE indexname = $1 AND schemaname = $2 LIMIT 1`, [`idx_${schemaName}_jobs_origin`, schemaName]);
+        if (originIdxRows.length === 0) {
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_${schemaName}_jobs_origin
+          ON ${jobsTable}(origin_id) WHERE origin_id IS NOT NULL;
+      `);
+        }
+        const { rows: parentIdxRows } = await client.query(`SELECT 1 FROM pg_indexes WHERE indexname = $1 AND schemaname = $2 LIMIT 1`, [`idx_${schemaName}_jobs_parent`, schemaName]);
+        if (parentIdxRows.length === 0) {
+            await client.query(`
+        CREATE INDEX IF NOT EXISTS idx_${schemaName}_jobs_parent
+          ON ${jobsTable}(parent_id) WHERE parent_id IS NOT NULL;
+      `);
+        }
+        // ─── v0.22.0+: public.hmsh_escalations global table migrations ───────────
+        // Use the fixed advisory XACT lock so concurrent deployments of DIFFERENT
+        // appIds (each holding their own per-appId session lock) don't race on the
+        // shared public table DDL. Transaction-level lock auto-releases on commit/rollback.
+        await client.query('BEGIN');
+        await client.query('SELECT pg_advisory_xact_lock($1)', [0x484D5348]);
+        // v0.22.0: create hmsh_escalations if missing (upgrade from pre-0.22.x).
+        // Column list matches createTables() exactly; task_id is NOT here because
+        // the ADD COLUMN below is the canonical way to add it to both fresh and
+        // existing tables in a single idempotent statement.
+        await client.query(`
+      CREATE TABLE IF NOT EXISTS public.hmsh_escalations (
+        id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        namespace        TEXT NOT NULL,
+        app_id           TEXT NOT NULL,
+        signal_key       TEXT,
+        topic            TEXT,
+        workflow_id      TEXT,
+        task_queue       TEXT,
+        workflow_type    TEXT,
+        type             TEXT,
+        subtype          TEXT,
+        entity           TEXT,
+        description      TEXT,
+        role             TEXT,
+        status           TEXT NOT NULL DEFAULT 'pending',
+        priority         INT  NOT NULL DEFAULT 5,
+        assigned_to      TEXT,
+        assigned_until   TIMESTAMPTZ,
+        claimed_at       TIMESTAMPTZ,
+        claim_expires_at TIMESTAMPTZ,
+        resolved_at      TIMESTAMPTZ,
+        escalation_payload JSONB,
+        resolver_payload   JSONB,
+        envelope           JSONB,
+        metadata           JSONB,
+        origin_id          TEXT,
+        parent_id          TEXT,
+        initiated_by       TEXT,
+        created_by         TEXT,
+        milestones         JSONB NOT NULL DEFAULT '[]',
+        trace_id           TEXT,
+        span_id            TEXT,
+        expires_at         TIMESTAMPTZ,
+        created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+    `);
+        // v0.22.3: task_id column — catalog-only ADD COLUMN (nullable TEXT, no DEFAULT,
+        // no table rewrite). IF NOT EXISTS makes this idempotent across all upgrade paths.
+        await client.query(`
+      ALTER TABLE public.hmsh_escalations ADD COLUMN IF NOT EXISTS task_id TEXT;
+    `);
+        // Ensure signal_key unique index exists.
+        await client.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_hmsh_esc_signal_key
+        ON public.hmsh_escalations(namespace, app_id, signal_key)
+        WHERE signal_key IS NOT NULL;
+    `);
+        // v0.22.0: idx_hmsh_esc_available — predicate must be status='pending'.
+        // Fresh 0.22.0 installs may have this with the correct predicate already;
+        // ensure it exists.
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_available
+        ON public.hmsh_escalations(namespace, app_id, role, priority ASC, created_at ASC)
+        WHERE status = 'pending';
+    `);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_available_expiry
+        ON public.hmsh_escalations(namespace, app_id, role, assigned_until, created_at DESC);
+    `);
+        // v0.22.2: idx_hmsh_esc_assigned predicate changed from status='claimed' to
+        // status='pending' to match the implicit claim model. If the old predicate
+        // is present, drop and recreate so claimEscalation / list queries use it.
+        const { rows: assignedDefRows } = await client.query(`
+      SELECT indexdef FROM pg_indexes WHERE indexname = 'idx_hmsh_esc_assigned' LIMIT 1
+    `);
+        if (assignedDefRows.length > 0 &&
+            assignedDefRows[0].indexdef.includes("status = 'claimed'")) {
+            await client.query(`DROP INDEX IF EXISTS idx_hmsh_esc_assigned;`);
+        }
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_assigned
+        ON public.hmsh_escalations(assigned_to, assigned_until, created_at DESC)
+        WHERE status = 'pending' AND assigned_to IS NOT NULL;
+    `);
+        // v0.22.2: claim_expiry sweeper index is obsolete (releaseExpiredEscalations
+        // is a no-op in the implicit-claim model — availability is query-time computed).
+        await client.query(`DROP INDEX IF EXISTS idx_hmsh_esc_claim_expiry;`);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_entity
+        ON public.hmsh_escalations(namespace, app_id, entity, created_at DESC)
+        WHERE entity IS NOT NULL;
+    `);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_workflow
+        ON public.hmsh_escalations(workflow_id)
+        WHERE workflow_id IS NOT NULL;
+    `);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_origin
+        ON public.hmsh_escalations(origin_id)
+        WHERE origin_id IS NOT NULL;
+    `);
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_metadata
+        ON public.hmsh_escalations USING GIN(metadata jsonb_path_ops);
+    `);
+        // v0.22.3: task_id partial index.
+        await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_hmsh_esc_task
+        ON public.hmsh_escalations(task_id)
+        WHERE task_id IS NOT NULL;
+    `);
+        await client.query('COMMIT');
     },
     async createTables(client, appName) {
         try {
@@ -253,16 +404,15 @@ const KVTables = (context) => ({
               CREATE INDEX IF NOT EXISTS idx_hmsh_esc_available_expiry
                 ON public.hmsh_escalations(namespace, app_id, role, assigned_until, created_at DESC);
             `);
+                        // idx_hmsh_esc_assigned: implicit-claim model uses status='pending', not 'claimed'
+                        await client.query(`DROP INDEX IF EXISTS idx_hmsh_esc_assigned;`);
                         await client.query(`
               CREATE INDEX IF NOT EXISTS idx_hmsh_esc_assigned
                 ON public.hmsh_escalations(assigned_to, assigned_until, created_at DESC)
-                WHERE status = 'claimed' AND assigned_to IS NOT NULL;
-            `);
-                        await client.query(`
-              CREATE INDEX IF NOT EXISTS idx_hmsh_esc_claim_expiry
-                ON public.hmsh_escalations(claim_expires_at)
-                WHERE status = 'claimed';
+                WHERE status = 'pending' AND assigned_to IS NOT NULL;
             `);
+                        // idx_hmsh_esc_claim_expiry: no longer used (releaseExpiredEscalations is a no-op)
+                        await client.query(`DROP INDEX IF EXISTS idx_hmsh_esc_claim_expiry;`);
                         await client.query(`
               CREATE INDEX IF NOT EXISTS idx_hmsh_esc_entity
                 ON public.hmsh_escalations(namespace, app_id, entity, created_at DESC)
@@ -281,6 +431,15 @@ const KVTables = (context) => ({
                         await client.query(`
               CREATE INDEX IF NOT EXISTS idx_hmsh_esc_metadata
                 ON public.hmsh_escalations USING GIN(metadata jsonb_path_ops);
+            `);
+                        // task_id: nullable passthrough column for downstream compat (no FK)
+                        await client.query(`
+              ALTER TABLE public.hmsh_escalations ADD COLUMN IF NOT EXISTS task_id TEXT;
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_hmsh_esc_task
+                ON public.hmsh_escalations(task_id)
+                WHERE task_id IS NOT NULL;
             `);
                         break;
                     case 'relational_connection':

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>;
@@ -246,6 +248,7 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     createEscalationForMigration(params: import('../../../../types/hmsh_escalations').MigrateEscalationParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     getEscalation(id: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     getEscalationBySignalKey(signalKey: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
+    private _escalationFilterConditions;
     listEscalations(params?: import('../../../../types/hmsh_escalations').ListEscalationsParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry[]>;
     countEscalations(params?: import('../../../../types/hmsh_escalations').ListEscalationsParams): Promise<number>;
     claimEscalation(params: import('../../../../types/hmsh_escalations').ClaimEscalationParams): Promise<import('../../../../types/hmsh_escalations').ClaimEscalationResult>;
@@ -259,26 +262,19 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
         signalKey?: string | null;
         topic?: string | null;
     }>;
-    /**
-     * Queues the escalation UPDATE into an existing transaction without executing it.
-     * Used by client.ts resolve() to commit the status change atomically with signal delivery.
-     */
-    queueResolveEscalation(params: {
-        id: string;
-        namespace?: string;
-        resolverPayload?: Record<string, unknown>;
-    }, transaction: {
-        addCommand: (sql: string, params: any[], returnType: string) => any;
-    }): void;
-    /**
-     * Finds the highest-priority pending or claimed escalation matching the given metadata filter.
-     * Used by client.ts resolveByMetadata() to get routing info before building the atomic transaction.
-     */
-    findEscalationByMetadata(key: string, value: string, roles: string[] | null, namespace?: string): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     cancelEscalation(id: string, namespace?: string): Promise<import('../../../../types/hmsh_escalations').CancelEscalationResult>;
     escalateEscalationToRole(params: import('../../../../types/hmsh_escalations').EscalateToRoleParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry | null>;
     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<{
+        entries: import('../../../../types/hmsh_escalations').EscalationEntry[];
+        skipped: number;
+    }>;
+    escalateManyEscalationsToRole(params: import('../../../../types/hmsh_escalations').EscalateManyToRoleParams): Promise<number>;
+    updateManyEscalationsPriority(params: import('../../../../types/hmsh_escalations').UpdateManyPriorityParams): Promise<number>;
+    resolveManyEscalations(params: import('../../../../types/hmsh_escalations').ResolveManyParams): Promise<import('../../../../types/hmsh_escalations').EscalationEntry[]>;
+    escalationStats(params?: import('../../../../types/hmsh_escalations').StatsEscalationsParams): Promise<import('../../../../types/hmsh_escalations').EscalationStats>;
+    listDistinctEscalationTypes(namespace?: string): Promise<string[]>;
     releaseExpiredEscalations(_namespace?: string): Promise<number>;
 }
 export { PostgresStoreService };