@hotmeshio/long-tail 0.4.24 → 0.5.0

package/build/lib/db/schemas/011_escalation_index_audit.sql

@@ -0,0 +1,50 @@
+-- ─── lt_escalations index audit ────────────────────────────────────────────
+--
+-- Motivation (hotmesh 0.20.0, PR perf/claim-path-hotspots):
+--   Each stream/queue row pays index maintenance on every INSERT and on every
+--   non-HOT UPDATE that touches an indexed column. The HITL claim path is
+--   UPDATE-heavy (claim/resolve/release touch status, assigned_to,
+--   assigned_until, claimed_at, priority, metadata, role — nearly all indexed),
+--   so every claim is a non-HOT update that maintains all 18 btree indexes plus
+--   the metadata GIN. 0.20.0 cut redundant stream-table indexes for exactly this
+--   reason; this migration applies the same discipline to lt_escalations.
+--
+-- Scope: only drop indexes that are PROVABLY redundant — a strict leading-prefix
+--   subset of another index whose partial predicate is no stricter. Anything that
+--   merely "looks" duplicative is left in place and flagged below for EXPLAIN-driven
+--   review against production data, not dropped speculatively.
+
+-- 1. idx_lt_escalations_role_type (role, status, type, created_at DESC)
+--    is an exact leading prefix of
+--    idx_lt_escalations_role_subtype (role, status, type, subtype, created_at DESC).
+--    Every query the former can serve (equality/range on role,status,type and the
+--    created_at ordering) is served by the latter scanning the same prefix.
+DROP INDEX IF EXISTS idx_lt_escalations_role_type;
+
+-- 2. idx_lt_escalations_origin_id (origin_id) WHERE origin_id IS NOT NULL
+--    is fully covered by idx_lt_escalations_origin (origin_id, created_at DESC):
+--    `origin_id = $1` implies `origin_id IS NOT NULL`, origin_id leads the composite,
+--    and the composite additionally serves the `ORDER BY created_at DESC` used by
+--    GET_ESCALATIONS_BY_ORIGIN_ID. The partial index adds no reachable plan.
+DROP INDEX IF EXISTS idx_lt_escalations_origin_id;
+
+-- ── Review candidates (NOT dropped — verify with EXPLAIN on production volume) ──
+--
+-- These overlap but are not provably redundant. Confirm with EXPLAIN (ANALYZE,
+-- BUFFERS) on representative data before removing any of them:
+--
+--   idx_lt_escalations_available (status, role, assigned_until, created_at DESC)
+--     vs idx_lt_escalations_available_v2 (role, priority, created_at DESC)
+--        WHERE status = 'pending'
+--     The "_v2" naming implies intent to supersede v1, but v1 is full-table and
+--     v1 alone positions assigned_until for the available-pool predicate. Confirm
+--     which (if either) the listAvailableEscalations plan actually uses.
+--
+--   idx_lt_escalations_status (status, created_at DESC)
+--     Partially overlaps status-leading composites, but is the only index that
+--     serves `status = $1 ORDER BY created_at DESC` index-ordered for non-pending
+--     statuses. Keep unless EXPLAIN shows it unused.
+--
+--   idx_lt_escalations_priority_desc (priority DESC, created_at DESC)
+--     Backs the user-selectable `sort_by=priority` dashboard sort (SORTABLE_COLUMNS).
+--     Keep while that sort is exposed.

package/build/services/escalation/sql.d.ts

@@ -26,7 +26,7 @@ export declare const FIND_BY_METADATA = "SELECT *, COUNT(*) OVER() AS _total\nFR
  * $1 = metadata filter (jsonb), $2 = userId, $3 = durationMinutes,
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT *,\n  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist\nFROM updated";
+export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS MATERIALIZED (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT *,\n  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist\nFROM updated";
 /**
  * Atomic resolve by metadata with signal guard.
  *
@@ -39,4 +39,4 @@ export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS (\n  SELECT id,
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS (\n  SELECT *\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE lt_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE lt_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";

package/build/services/escalation/sql.js

@@ -148,7 +148,7 @@ LIMIT $3 OFFSET $4`;
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
 exports.CLAIM_BY_METADATA_GUARDED = `\
-WITH target AS (
+WITH target AS MATERIALIZED (
   SELECT id, assigned_to
   FROM lt_escalations
   WHERE metadata @> $1::jsonb
@@ -188,7 +188,7 @@ FROM updated`;
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
 exports.RESOLVE_BY_METADATA_ATOMIC = `\
-WITH target AS (
+WITH target AS MATERIALIZED (
   SELECT *
   FROM lt_escalations
   WHERE metadata @> $1::jsonb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.4.24",
+  "version": "0.5.0",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -70,7 +70,7 @@
     "@anthropic-ai/sdk": "^0.92.0",
     "@aws-sdk/client-s3": "^3.1017.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@hotmeshio/hotmesh": "^0.19.5",
+    "@hotmeshio/hotmesh": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",