@hotmeshio/hotmesh 0.22.1 → 0.22.3

package/build/services/escalations/client.js

@@ -0,0 +1,320 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EscalationClientService = void 0;
+const enums_1 = require("../../modules/enums");
+const utils_1 = require("../../modules/utils");
+const hotmesh_1 = require("../hotmesh");
+const types_1 = require("../../types");
+const factory_1 = require("../durable/schemas/factory");
+/**
+ * Standalone client for the `public.hmsh_escalations` signal-pause surface.
+ *
+ * Requires NO dependency on `services/durable/`. Any HotMesh consumer — AI
+ * agent, YAML DAG worker, REST API — can interact with the escalation queue
+ * directly with just a Postgres connection.
+ *
+ * Signal delivery (for `resolve()` / `resolveByMetadata()`) uses HotMesh's
+ * `engine.signal()` internally. The engine is initialised lazily on first use
+ * and cached for the lifetime of the process.
+ *
+ * @example
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Escalations.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // Claim the next available approval for the 'manager' role
+ * const result = await client.claimByMetadata({
+ *   key: 'orderId', value: 'order-123',
+ *   assignee: 'alice@company.com',
+ *   roles: ['manager'],
+ * });
+ *
+ * if (result.ok) {
+ *   await client.resolve({ id: result.entry.id, resolverPayload: { approved: true } });
+ * }
+ * ```
+ */
+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._engine = this._makeEngineFactory(config.connection);
+        }
+        else {
+            throw new Error('EscalationClient requires either `connection` or `getHotMeshClient`');
+        }
+    }
+    _makeEngineFactory(connection) {
+        return async (topic, namespace) => {
+            const optionsHash = this._hashConnection(connection);
+            const targetNS = namespace ?? factory_1.APP_ID;
+            const key = `esc:${optionsHash}.${targetNS}`;
+            if (EscalationClientService.instances.has(key)) {
+                return await EscalationClientService.instances.get(key);
+            }
+            const pending = hotmesh_1.HotMesh.init({
+                appId: targetNS,
+                taskQueue: topic ?? undefined,
+                logLevel: enums_1.HMSH_LOGLEVEL,
+                engine: { connection },
+            });
+            EscalationClientService.instances.set(key, pending);
+            return await pending;
+        };
+    }
+    _hashConnection(connection) {
+        if ('options' in connection) {
+            return (0, utils_1.hashOptions)(connection.options);
+        }
+        const parts = [];
+        for (const p in connection) {
+            if (connection[p]?.options) {
+                parts.push((0, utils_1.hashOptions)(connection[p].options));
+            }
+        }
+        return parts.join('');
+    }
+    // ─── Signal delivery ───────────────────────────────────────────────────────
+    async _deliverEscalationSignal(ns, topic, signalPayload) {
+        if (topic) {
+            try {
+                const tc = await this._engine(topic, ns);
+                await tc.engine.signal(topic, signalPayload, types_1.StreamStatus.SUCCESS, 200);
+                return true;
+            }
+            catch { /* topic not currently registered — fall through */ }
+        }
+        let delivered = false;
+        try {
+            const sc = await this._engine(`${ns}.wfs.signal`, ns);
+            await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
+            delivered = true;
+        }
+        catch { }
+        try {
+            const wc = await this._engine(`${ns}.wfs.wait`, ns);
+            await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200);
+            delivered = true;
+        }
+        catch { }
+        return delivered;
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────────
+    /**
+     * Returns all escalation rows matching the given filters. Each row includes
+     * a computed `available` field (true = claimable). Supports `sortBy`,
+     * `sortOrder`, `orderBy[]`, and multi-role `roles[]` filter.
+     */
+    async list(params) {
+        const hm = await this._engine(null, params?.namespace);
+        return hm.engine.store.listEscalations(params ?? {});
+    }
+    /**
+     * Returns the count of escalation rows matching the given filters.
+     * Uses the same filter parameters as `list()`.
+     */
+    async count(params) {
+        const hm = await this._engine(null, params?.namespace);
+        return hm.engine.store.countEscalations(params ?? {});
+    }
+    /** Returns a single escalation row by UUID. Returns `null` if not found. */
+    async get(id, namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.getEscalation(id, namespace);
+    }
+    /** Looks up an escalation by `signal_key` — the value passed to `condition()`. */
+    async getBySignalKey(signalKey, namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.getEscalationBySignalKey(signalKey, namespace);
+    }
+    /**
+     * Creates a standalone escalation row with `signal_key = null`.
+     * Useful for external task tracking that doesn't need to resume a workflow.
+     */
+    async create(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.createEscalation(params);
+    }
+    /**
+     * Patches an existing escalation row. `metadata` is merged, not replaced.
+     * Signal routing fields can be enriched after creation.
+     */
+    async update(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.updateEscalation(params);
+    }
+    /** Appends milestone entries to the escalation's audit trail. */
+    async appendMilestones(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.appendEscalationMilestones(params);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Atomically claims the highest-priority pending escalation whose `metadata`
+     * 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);
+    }
+    /** 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);
+    }
+    /**
+     * Reassigns the escalation to a different role, clearing any current claim
+     * and resetting status to `'pending'`.
+     */
+    async escalateToRole(params) {
+        const hm = await this._engine(null, params.namespace);
+        return hm.engine.store.escalateEscalationToRole(params);
+    }
+    /**
+     * Cancels a pending escalation without delivering a signal. Terminal rows
+     * return `already-terminal`.
+     */
+    async cancel(id, namespace) {
+        const hm = await this._engine(null, namespace);
+        return hm.engine.store.cancelEscalation(id, namespace);
+    }
+    /**
+     * 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 store = hm.engine.store;
+        const dbResult = await store.resolveEscalation({ id: params.id, resolverPayload: params.resolverPayload });
+        if (!dbResult.ok)
+            return dbResult;
+        if (dbResult.signalKey) {
+            await this._deliverEscalationSignal(ns, dbResult.topic, {
+                id: dbResult.signalKey,
+                data: params.resolverPayload ?? {},
+            });
+        }
+        return { ok: true, entry: dbResult.entry };
+    }
+    /**
+     * Resolves the highest-priority matching escalation by metadata filter,
+     * 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 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) {
+            await this._deliverEscalationSignal(ns, dbResult.topic, {
+                id: dbResult.signalKey,
+                data: params.resolverPayload ?? {},
+            });
+        }
+        return { ok: true, entry: dbResult.entry };
+    }
+    /**
+     * Full-fidelity migration: inserts an escalation row preserving the original
+     * UUID and lifecycle state. Returns `null` on duplicate (idempotent).
+     */
+    async migrate(params, namespace) {
+        const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+        const hm = await this._engine(null, ns);
+        return hm.engine.store.createEscalationForMigration(params);
+    }
+    /**
+     * No-op in the implicit claim model — availability is computed at query time
+     * from `assigned_until`. Kept for API compatibility.
+     */
+    async releaseExpired(namespace) {
+        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);
+        return hm.engine.store.claimManyEscalations(params);
+    }
+    /**
+     * 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);
+        return hm.engine.store.resolveManyEscalations(params);
+    }
+    // ─── 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();
+        }
+        EscalationClientService.instances.clear();
+    }
+}
+EscalationClientService.instances = new Map();
+exports.EscalationClientService = EscalationClientService;

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

@@ -0,0 +1,66 @@
+import { guid, uuid } from '../../modules/utils';
+import { EscalationClientService } from './client';
+/**
+ * Escalation queue — the canonical signal-pause surface for HotMesh workflows.
+ *
+ * `public.hmsh_escalations` is a global Postgres table written by both the
+ * YAML DAG hook activity and `Durable.workflow.condition()`. Any consumer
+ * can interact with the queue using just a Postgres connection — no Durable
+ * dependency required.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Escalations.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // List all available approvals for the 'manager' role
+ * const pending = await client.list({ role: 'manager', available: true });
+ *
+ * // Claim one atomically
+ * const result = await client.claimByMetadata({
+ *   key: 'orderId', value: 'order-123',
+ *   assignee: 'alice@company.com',
+ *   roles: ['manager', 'senior-manager'],
+ * });
+ *
+ * // Resolve and resume the waiting workflow in one round-trip
+ * if (result.ok) {
+ *   await client.resolve({ id: result.entry.id, resolverPayload: { approved: true } });
+ * }
+ * ```
+ */
+declare class EscalationsClass {
+    /** @private */
+    constructor();
+    /**
+     * Creates an escalation queue client. Pass a `connection` for standalone
+     * use, or inject a `getHotMeshClient` function to share an existing
+     * engine pool (e.g. from a `Durable.Client`).
+     */
+    static Client: typeof EscalationClientService;
+    /**
+     * Generate a compact HotMesh identifier (not RFC 4122).
+     * Use `Escalations.uuid()` for DB primary keys.
+     */
+    static guid: typeof guid;
+    /**
+     * Generate a standard RFC 4122 v4 UUID — required for the `id` field
+     * when calling `client.migrate()` or any direct UUID column insert.
+     */
+    static uuid: typeof uuid;
+    /**
+     * Gracefully stop all escalation engine instances.
+     * Call from your process signal handlers (`SIGTERM`, `SIGINT`).
+     */
+    static shutdown(): Promise<void>;
+}
+export { EscalationsClass as Escalations };
+export { EscalationClientService };

package/build/services/escalations/index.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EscalationClientService = exports.Escalations = void 0;
+const utils_1 = require("../../modules/utils");
+const client_1 = require("./client");
+Object.defineProperty(exports, "EscalationClientService", { enumerable: true, get: function () { return client_1.EscalationClientService; } });
+/**
+ * Escalation queue — the canonical signal-pause surface for HotMesh workflows.
+ *
+ * `public.hmsh_escalations` is a global Postgres table written by both the
+ * YAML DAG hook activity and `Durable.workflow.condition()`. Any consumer
+ * can interact with the queue using just a Postgres connection — no Durable
+ * dependency required.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { Escalations } from '@hotmeshio/hotmesh';
+ * import { Client as Postgres } from 'pg';
+ *
+ * const client = new Escalations.Client({
+ *   connection: {
+ *     class: Postgres,
+ *     options: { connectionString: 'postgresql://usr:pwd@localhost:5432/db' },
+ *   },
+ * });
+ *
+ * // List all available approvals for the 'manager' role
+ * const pending = await client.list({ role: 'manager', available: true });
+ *
+ * // Claim one atomically
+ * const result = await client.claimByMetadata({
+ *   key: 'orderId', value: 'order-123',
+ *   assignee: 'alice@company.com',
+ *   roles: ['manager', 'senior-manager'],
+ * });
+ *
+ * // Resolve and resume the waiting workflow in one round-trip
+ * if (result.ok) {
+ *   await client.resolve({ id: result.entry.id, resolverPayload: { approved: true } });
+ * }
+ * ```
+ */
+class EscalationsClass {
+    /** @private */
+    constructor() { }
+    /**
+     * Gracefully stop all escalation engine instances.
+     * Call from your process signal handlers (`SIGTERM`, `SIGINT`).
+     */
+    static async shutdown() {
+        await client_1.EscalationClientService.shutdown();
+    }
+}
+exports.Escalations = EscalationsClass;
+/**
+ * Creates an escalation queue client. Pass a `connection` for standalone
+ * use, or inject a `getHotMeshClient` function to share an existing
+ * engine pool (e.g. from a `Durable.Client`).
+ */
+EscalationsClass.Client = client_1.EscalationClientService;
+/**
+ * Generate a compact HotMesh identifier (not RFC 4122).
+ * Use `Escalations.uuid()` for DB primary keys.
+ */
+EscalationsClass.guid = utils_1.guid;
+/**
+ * Generate a standard RFC 4122 v4 UUID — required for the `id` field
+ * when calling `client.migrate()` or any direct UUID column insert.
+ */
+EscalationsClass.uuid = utils_1.uuid;

package/build/services/store/providers/postgres/kvtables.js

@@ -166,6 +166,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 +392,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 +419,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':