@hotmeshio/long-tail 0.10.7 → 0.10.9

package/build/api/escalations/bulk.js

@@ -166,7 +166,7 @@ async function bulkAssign(input, auth) {
             }
             const result = await escalationService.bulkAssignEscalationsByQuery({ role: query.role, facets: query.facets }, targetUserId, durationMinutes ?? 30);
             if (result.assigned > 0)
-                (0, helpers_1.publishBulkClaimEvents)(result.ids, targetUserId);
+                (0, helpers_1.publishBulkClaimEvents)(result.ids, targetUserId, query.role);
             return { status: 200, data: { assigned: result.assigned, skipped: 0 } };
         }
         if (!(0, helpers_1.validateIds)(ids)) {
@@ -215,7 +215,13 @@ async function bulkEscalate(input, auth) {
         const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
         if (!perm.allowed)
             return perm;
+        // Departing roles are read before the move so each reassignment can
+        // publish under BOTH queues — the one the row leaves and the one it
+        // joins (same contract as the single escalate path).
+        const beforeRows = await escalationService.getEscalationScopeRows(ids);
         const updated = await escalationService.bulkEscalateToRole(ids, targetRole);
+        if (updated > 0)
+            (0, helpers_1.publishBulkReassignEvents)(beforeRows, targetRole);
         return { status: 200, data: { updated } };
     }
     catch (err) {

package/build/api/escalations/helpers.d.ts

@@ -141,4 +141,13 @@ export declare function resolveAssignee(assignee: string | undefined, auth: {
  * Only adds the role if `provisionIfAbsent` declares it and caller has authority.
  */
 export declare function ensureRoleMembership(userId: string, requiredRole: string, callerUserId: string, provisionIfAbsent?: ProvisionIfAbsent): Promise<boolean>;
-export declare function publishBulkClaimEvents(ids: string[], assignedTo: string): void;
+/**
+ * Publish `reassigned` for a bulk role move: every row publishes under its
+ * departing role AND the target role, so subscribers scoped to either queue
+ * observe the move. Rows already in the target role publish once.
+ */
+export declare function publishBulkReassignEvents(beforeRows: Array<{
+    id: string;
+    role: string;
+}>, targetRole: string): void;
+export declare function publishBulkClaimEvents(ids: string[], assignedTo: string, knownRole?: string): void;

package/build/api/escalations/helpers.js

@@ -44,6 +44,7 @@ exports.assertQueueManageAccess = assertQueueManageAccess;
 exports.checkBulkPermission = checkBulkPermission;
 exports.resolveAssignee = resolveAssignee;
 exports.ensureRoleMembership = ensureRoleMembership;
+exports.publishBulkReassignEvents = publishBulkReassignEvents;
 exports.publishBulkClaimEvents = publishBulkClaimEvents;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
@@ -254,17 +255,56 @@ async function ensureRoleMembership(userId, requiredRole, callerUserId, provisio
     catch { /* already has it */ }
     return true;
 }
-function publishBulkClaimEvents(ids, assignedTo) {
-    for (const id of ids) {
-        (0, publish_1.publishEscalationEvent)({
-            type: 'escalation.claimed',
-            source: 'api',
-            workflowId: '',
-            workflowName: '',
-            taskQueue: '',
-            escalationId: id,
-            status: 'claimed',
-            data: { assigned_to: assignedTo, bulk: true },
-        });
+/**
+ * Publish `reassigned` for a bulk role move: every row publishes under its
+ * departing role AND the target role, so subscribers scoped to either queue
+ * observe the move. Rows already in the target role publish once.
+ */
+function publishBulkReassignEvents(beforeRows, targetRole) {
+    for (const row of beforeRows) {
+        const roles = row.role && row.role !== targetRole ? [row.role, targetRole] : [targetRole];
+        for (const role of roles) {
+            (0, publish_1.publishEscalationEvent)({
+                type: 'escalation.reassigned',
+                source: 'api',
+                workflowId: '',
+                workflowName: '',
+                taskQueue: '',
+                escalationId: row.id,
+                role,
+                status: 'pending',
+                data: { from_role: row.role, to_role: targetRole, bulk: true },
+            });
+        }
     }
 }
+function publishBulkClaimEvents(ids, assignedTo, knownRole) {
+    // The claimed subject carries each row's role token. Query-form callers
+    // already know the single role; id-form callers resolve roles with one
+    // indexed read. Fire-and-forget, like every event publish.
+    void (async () => {
+        const roleById = new Map();
+        if (knownRole) {
+            for (const id of ids)
+                roleById.set(id, knownRole);
+        }
+        else {
+            const rows = await escalationService.getEscalationScopeRows(ids);
+            for (const row of rows)
+                roleById.set(row.id, row.role);
+        }
+        for (const id of ids) {
+            (0, publish_1.publishEscalationEvent)({
+                type: 'escalation.claimed',
+                source: 'api',
+                workflowId: '',
+                workflowName: '',
+                taskQueue: '',
+                escalationId: id,
+                role: roleById.get(id) ?? '',
+                status: 'claimed',
+                data: { assigned_to: assignedTo, bulk: true },
+            });
+        }
+    })().catch(() => { });
+}

package/build/lib/events/matching.d.ts

@@ -10,4 +10,14 @@
  * - `app.epic.apis.createorder.error` matches `app.epic.>`
  * - `app.epic.apis.createorder.error` does NOT match `app.vendor.>`
  */
+/**
+ * Make a value safe to embed as ONE token of a dot-delimited subject.
+ *
+ * Dots would splinter the token into extra subject levels; `*`, `>`, spaces,
+ * and other non-token characters would corrupt pattern matching (and are
+ * illegal in NATS subjects). Each run of unsafe characters collapses to a
+ * single `-`. An empty or missing value yields `none` so the subject always
+ * keeps its arity.
+ */
+export declare function sanitizeSubjectToken(value: string | null | undefined): string;
 export declare function subjectMatchesPattern(subject: string, pattern: string): boolean;

package/build/lib/events/matching.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeSubjectToken = sanitizeSubjectToken;
 exports.subjectMatchesPattern = subjectMatchesPattern;
 /**
  * Match a dot-delimited subject against a pattern with NATS-style wildcards.
@@ -13,6 +14,19 @@ exports.subjectMatchesPattern = subjectMatchesPattern;
  * - `app.epic.apis.createorder.error` matches `app.epic.>`
  * - `app.epic.apis.createorder.error` does NOT match `app.vendor.>`
  */
+/**
+ * Make a value safe to embed as ONE token of a dot-delimited subject.
+ *
+ * Dots would splinter the token into extra subject levels; `*`, `>`, spaces,
+ * and other non-token characters would corrupt pattern matching (and are
+ * illegal in NATS subjects). Each run of unsafe characters collapses to a
+ * single `-`. An empty or missing value yields `none` so the subject always
+ * keeps its arity.
+ */
+function sanitizeSubjectToken(value) {
+    const cleaned = (value ?? '').replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned || 'none';
+}
 function subjectMatchesPattern(subject, pattern) {
     if (pattern === '*')
         return true;

package/build/lib/events/publish.d.ts

@@ -32,16 +32,22 @@ export declare function publishTaskEvent(params: {
 }): Promise<void>;
 /**
  * Publish an escalation lifecycle event.
- * Subject: system.escalation.{escalationId}.{action}
+ * Subject: system.escalation.{role}.{escalationId}.{action}
+ *
+ * The role token makes the queue the organizing level of the hierarchy:
+ * subscribers scope to one role (`system.escalation.{role}.>`), one verb
+ * across roles (`system.escalation.*.*.created`), or one item regardless of
+ * role hops (`system.escalation.*.{id}.>`).
  */
 export declare function publishEscalationEvent(params: {
-    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'escalation.cancelled';
+    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'escalation.cancelled' | 'escalation.reassigned';
     source: string;
     workflowId: string;
     workflowName: string;
     taskQueue: string;
     taskId?: string;
     escalationId: string;
+    role: string;
     originId?: string;
     status: string;
     data?: Record<string, any>;

package/build/lib/events/publish.js

@@ -9,6 +9,7 @@ exports.publishFileEvent = publishFileEvent;
 exports.publishAgentEvent = publishAgentEvent;
 exports.publishWorkflowEvent = publishWorkflowEvent;
 const index_1 = require("./index");
+const matching_1 = require("./matching");
 const logger_1 = require("../logger");
 /**
  * Fire-and-forget publish helper. Swallows errors (best-effort).
@@ -62,13 +63,19 @@ function publishTaskEvent(params) {
 }
 /**
  * Publish an escalation lifecycle event.
- * Subject: system.escalation.{escalationId}.{action}
+ * Subject: system.escalation.{role}.{escalationId}.{action}
+ *
+ * The role token makes the queue the organizing level of the hierarchy:
+ * subscribers scope to one role (`system.escalation.{role}.>`), one verb
+ * across roles (`system.escalation.*.*.created`), or one item regardless of
+ * role hops (`system.escalation.*.{id}.>`).
  */
 function publishEscalationEvent(params) {
     const action = params.type.split('.')[1];
     return fireAndForget({
-        type: `system.escalation.${params.escalationId}.${action}`,
+        type: `system.escalation.${(0, matching_1.sanitizeSubjectToken)(params.role)}.${params.escalationId}.${action}`,
         source: params.source,
+        role: params.role,
         workflowId: params.workflowId,
         workflowName: params.workflowName,
         taskQueue: params.taskQueue,

package/build/lib/events/socketio.d.ts

@@ -8,8 +8,14 @@ export type SocketIOAuthenticator = (token: string) => boolean | Promise<boolean
 /**
  * Socket.IO event adapter for browser clients.
  *
- * Publishes LTEvent payloads to all connected Socket.IO clients
- * on channels following the pattern: `lt.events.{event.type}`
+ * Publishes LTEvent payloads to connected Socket.IO clients on channels
+ * following the pattern: `lt.events.{event.type}`.
+ *
+ * Delivery is scoped per socket: a client registers NATS-style subject
+ * patterns with `lt.subscribe` / `lt.unsubscribe` messages and receives only
+ * matching events — the server filters, the wire carries only what the page
+ * asked for. A socket that never registers a pattern receives every event
+ * (the broadcast contract external consumers may rely on).
  *
  * The HTTP server must be attached via `attachServer()` before
  * `connect()` is called. The startup flow handles this automatically

package/build/lib/events/socketio.js

@@ -3,11 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SocketIOEventAdapter = void 0;
 const socket_io_1 = require("socket.io");
 const logger_1 = require("../logger");
+const matching_1 = require("./matching");
 /**
  * Socket.IO event adapter for browser clients.
  *
- * Publishes LTEvent payloads to all connected Socket.IO clients
- * on channels following the pattern: `lt.events.{event.type}`
+ * Publishes LTEvent payloads to connected Socket.IO clients on channels
+ * following the pattern: `lt.events.{event.type}`.
+ *
+ * Delivery is scoped per socket: a client registers NATS-style subject
+ * patterns with `lt.subscribe` / `lt.unsubscribe` messages and receives only
+ * matching events — the server filters, the wire carries only what the page
+ * asked for. A socket that never registers a pattern receives every event
+ * (the broadcast contract external consumers may rely on).
  *
  * The HTTP server must be attached via `attachServer()` before
  * `connect()` is called. The startup flow handles this automatically
@@ -75,6 +82,19 @@ class SocketIOEventAdapter {
         }
         this.io.on('connection', (socket) => {
             logger_1.loggerRegistry.info(`[lt-events:socketio] client connected (${socket.id})`);
+            // Per-socket subject-pattern scope. Registering the first pattern
+            // switches the socket from broadcast to scoped delivery.
+            const patterns = new Set();
+            socket.data.ltPatterns = patterns;
+            socket.on('lt.subscribe', (pattern) => {
+                if (typeof pattern === 'string' && pattern.length > 0 && pattern.length <= 256) {
+                    patterns.add(pattern);
+                }
+            });
+            socket.on('lt.unsubscribe', (pattern) => {
+                if (typeof pattern === 'string')
+                    patterns.delete(pattern);
+            });
             socket.on('disconnect', () => {
                 logger_1.loggerRegistry.debug(`[lt-events:socketio] client disconnected (${socket.id})`);
             });
@@ -85,7 +105,20 @@ class SocketIOEventAdapter {
         if (!this.io)
             return;
         const channel = `lt.events.${event.type}`;
-        this.io.emit(channel, event);
+        for (const socket of this.io.of('/').sockets.values()) {
+            const patterns = socket.data.ltPatterns;
+            if (!patterns || patterns.size === 0) {
+                // Legacy scope: a socket with no registered patterns gets everything.
+                socket.emit(channel, event);
+                continue;
+            }
+            for (const pattern of patterns) {
+                if ((0, matching_1.subjectMatchesPattern)(channel, pattern)) {
+                    socket.emit(channel, event);
+                    break;
+                }
+            }
+        }
     }
     async disconnect() {
         if (this.io) {

package/build/lib/events/system-events.js

@@ -4,6 +4,7 @@ exports.systemEventsConfig = void 0;
 exports.mapSystemEvent = mapSystemEvent;
 exports.onSystemEvent = onSystemEvent;
 const index_1 = require("./index");
+const matching_1 = require("./matching");
 /** Verb → long-tail event status, matching the manual publishEscalationEvent convention. */
 const ESCALATION_STATUS_BY_VERB = {
     created: 'pending',
@@ -27,9 +28,16 @@ function mapSystemEvent(event) {
     if (domain === 'escalation') {
         const row = (event.data ?? {});
         const verb = segments[3] ?? '';
+        // The SDK forms `system.escalation.{id}.{verb}`; long-tail's canonical
+        // subject carries the role as the organizing token. The committed row
+        // rides in `data`, so the role is lifted from it and the subject is
+        // rewritten to `system.escalation.{role}.{id}.{verb}` — the same shape
+        // publishEscalationEvent produces for the service-mediated path.
+        const role = row.role || undefined;
         return {
-            type: event.type,
+            type: `system.escalation.${(0, matching_1.sanitizeSubjectToken)(role)}.${segments[2]}.${verb}`,
             source: 'sdk',
+            role,
             workflowId: row.workflow_id || event.workflow_id || undefined,
             workflowName: row.workflow_type || undefined,
             taskQueue: row.task_queue || undefined,

package/build/services/escalation/crud.js

@@ -74,6 +74,7 @@ async function createEscalation(input) {
         workflowName: escalation.workflow_type || '',
         taskQueue: escalation.task_queue || '',
         escalationId: escalation.id,
+        role: escalation.role,
         status: 'pending',
         data: { type: input.type, role: input.role },
     });
@@ -97,6 +98,7 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
         workflowName: escalation.workflow_type || '',
         taskQueue: escalation.task_queue || '',
         escalationId: escalation.id,
+        role: escalation.role,
         status: 'claimed',
         data: { assigned_to: userId },
     });
@@ -137,6 +139,7 @@ async function resolveEscalation(id, resolverPayload, metadata, assertClaim, res
         workflowName: escalation.workflow_type || '',
         taskQueue: escalation.task_queue || '',
         escalationId: escalation.id,
+        role: escalation.role,
         status: 'resolved',
         data: {},
     });
@@ -170,6 +173,7 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
             workflowName: escalation.workflow_type || '',
             taskQueue: escalation.task_queue || '',
             escalationId: escalation.id,
+            role: escalation.role,
             status: 'resolved',
             data: {},
         });
@@ -209,6 +213,7 @@ async function resolveEscalationsAllOrNone(items, metadata, assertAssignee, reso
             workflowName: escalation.workflow_type || '',
             taskQueue: escalation.task_queue || '',
             escalationId: escalation.id,
+            role: escalation.role,
             status: 'resolved',
             data: {},
         });
@@ -276,6 +281,7 @@ async function cancelEscalation(id) {
         workflowName: cancelled.workflow_type || '',
         taskQueue: cancelled.task_queue || '',
         escalationId: cancelled.id,
+        role: cancelled.role,
         status: 'cancelled',
         data: { reason: 'workflow_terminated' },
     });
@@ -335,6 +341,7 @@ async function releaseEscalation(id, userId) {
         workflowName: released.workflow_type || '',
         taskQueue: released.task_queue || '',
         escalationId: released.id,
+        role: released.role,
         status: 'released',
         data: { released_by: userId },
     });
@@ -358,8 +365,36 @@ async function releaseExpiredClaims() {
  */
 async function escalateToRole(id, targetRole) {
     const client = await (0, client_1.escalations)();
+    // The departing role is read before the move: the returned entry already
+    // carries the target role, and role-scoped subscribers of the OLD queue
+    // must see the item leave just as the new queue sees it arrive.
+    const before = await client.get(id);
+    const fromRole = before?.role ?? null;
     const entry = await client.escalateToRole({ id, targetRole });
-    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
+    if (!entry)
+        return null;
+    const escalation = (0, map_1.toEscalationRecord)(entry);
+    // One reassignment, two subjects: the same event publishes under the
+    // departing role and the arriving role, so a subscriber scoped to either
+    // queue observes the move. `data` names both ends for consumers that
+    // only see one side.
+    const rolesToNotify = fromRole && fromRole !== escalation.role
+        ? [fromRole, escalation.role]
+        : [escalation.role];
+    for (const role of rolesToNotify) {
+        publishEscalationChange({
+            type: 'escalation.reassigned',
+            source: 'service',
+            workflowId: escalation.workflow_id || '',
+            workflowName: escalation.workflow_type || '',
+            taskQueue: escalation.task_queue || '',
+            escalationId: escalation.id,
+            role,
+            status: 'pending',
+            data: { from_role: fromRole, to_role: escalation.role },
+        });
+    }
+    return escalation;
 }
 async function getEscalation(id) {
     const client = await (0, client_1.escalations)();
@@ -402,7 +437,7 @@ async function cancelEscalationsByWorkflowId(workflowId) {
         SET status = 'cancelled', updated_at = NOW()
       WHERE workflow_id = $1
         AND status = 'pending'
-      RETURNING id, workflow_id, workflow_type, task_queue`, [workflowId]);
+      RETURNING id, workflow_id, workflow_type, task_queue, role`, [workflowId]);
     for (const row of rows) {
         publishEscalationChange({
             type: 'escalation.cancelled',
@@ -411,6 +446,7 @@ async function cancelEscalationsByWorkflowId(workflowId) {
             workflowName: row.workflow_type || '',
             taskQueue: row.task_queue || '',
             escalationId: row.id,
+            role: row.role || '',
             status: 'cancelled',
             data: { reason: 'workflow_terminated' },
         });
@@ -498,6 +534,7 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
         workflowName: escalation.workflow_type || '',
         taskQueue: escalation.task_queue || '',
         escalationId: escalation.id,
+        role: escalation.role,
         status: 'claimed',
         data: { assigned_to: userId },
     });
@@ -556,6 +593,7 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
             workflowName: escalation.workflow_type || '',
             taskQueue: escalation.task_queue || '',
             escalationId: escalation.id,
+            role: escalation.role,
             status: 'resolved',
             data: { resolved_by: userId },
         });

package/build/services/orchestrator/condition.d.ts

@@ -21,7 +21,7 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * written inside this workflow's Leg1 checkpoint (one commit, crash-safe — no
  * separate create activity, no enrich). `signal_key` is the signal id, so the
  * dashboard resolve endpoint (Path 0), `resolveEscalationBySignalKey`, and any
- * webhook resume the SAME job in place. `system.escalation.{id}.created` fires
+ * webhook resume the SAME job in place. `system.escalation.{role}.{id}.created` fires
  * from the engine automatically.
  *
  * ```typescript

package/build/services/orchestrator/condition.js

@@ -60,7 +60,7 @@ function toEngineConfig(escalation) {
  * written inside this workflow's Leg1 checkpoint (one commit, crash-safe — no
  * separate create activity, no enrich). `signal_key` is the signal id, so the
  * dashboard resolve endpoint (Path 0), `resolveEscalationBySignalKey`, and any
- * webhook resume the SAME job in place. `system.escalation.{id}.created` fires
+ * webhook resume the SAME job in place. `system.escalation.{role}.{id}.created` fires
  * from the engine automatically.
  *
  * ```typescript

package/build/services/topics/system-topics.d.ts

@@ -1,8 +1,4 @@
 import type { LTTopicConfig } from '../../types';
-/**
- * Seed all 22 built-in system topics into the catalog.
- * Called once at startup after migrations.
- */
 export declare function seedSystemTopics(): Promise<void>;
 /**
  * Seed user-declared topics from startConfig.topics[].

package/build/services/topics/system-topics.js

@@ -12,6 +12,7 @@ const WORKFLOW_CONTEXT_PROPS = {
     originId: { type: 'string', description: 'Root process lineage ID' },
 };
 const STATUS_FIELD = { type: 'string', description: 'Status after this event' };
+const ROLE_FIELD = { type: 'string', description: 'Escalation role (the queue) — also the third subject token' };
 function objectSchema(properties) {
     return { type: 'object', properties };
 }
@@ -83,37 +84,64 @@ const SYSTEM_TOPICS = [
         example_payload: { workflowId: 'wf-abc', workflowName: 'processOrder', status: 'failed' },
         tags: ['lifecycle', 'error'],
     },
-    // Escalation lifecycle
+    // Escalation lifecycle — subjects are `system.escalation.{role}.{id}.{verb}`.
+    // The role token is the organizing level: subscribe to one queue with
+    // `system.escalation.{role}.>`, one verb across queues with
+    // `system.escalation.*.*.{verb}`, or one item with `system.escalation.*.{id}.>`.
     {
-        topic: 'system.escalation.*.created',
+        topic: 'system.escalation.*.*.created',
         description: 'An escalation has been created.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
-        example_payload: { escalationId: 'esc-001', status: 'pending', workflowName: 'processOrder' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'pending', workflowName: 'processOrder' },
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'system.escalation.*.resolved',
+        topic: 'system.escalation.*.*.resolved',
         description: 'An escalation has been resolved.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
-        example_payload: { escalationId: 'esc-001', status: 'resolved', workflowName: 'processOrder' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'resolved', workflowName: 'processOrder' },
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'system.escalation.*.claimed',
+        topic: 'system.escalation.*.*.claimed',
         description: 'An escalation has been claimed.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
-        example_payload: { escalationId: 'esc-001', status: 'claimed' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'claimed' },
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'system.escalation.*.released',
+        topic: 'system.escalation.*.*.released',
         description: 'An escalation has been returned to the queue.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
-        example_payload: { escalationId: 'esc-001', status: 'pending' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'pending' },
+        tags: ['lifecycle', 'hitl'],
+    },
+    {
+        topic: 'system.escalation.*.*.cancelled',
+        description: 'An escalation has been cancelled.',
+        category: 'escalation',
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'cancelled' },
+        tags: ['lifecycle', 'hitl'],
+    },
+    {
+        topic: 'system.escalation.*.*.reassigned',
+        description: 'An escalation has moved to a different role. Publishes under both the departing and arriving role.',
+        category: 'escalation',
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object', description: 'from_role and to_role' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-manager', status: 'pending', data: { from_role: 'order-review', to_role: 'order-manager' } },
+        tags: ['lifecycle', 'hitl'],
+    },
+    {
+        topic: 'system.escalation.*.*.expired',
+        description: 'A waiting escalation hit its SLA timeout and the engine transitioned it.',
+        category: 'escalation',
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'expired' },
         tags: ['lifecycle', 'hitl'],
     },
     // Activity lifecycle
@@ -247,9 +275,18 @@ function inferCategory(topic) {
     return topic.split('.')[0];
 }
 /**
- * Seed all 22 built-in system topics into the catalog.
+ * Seed the built-in system topics into the catalog.
  * Called once at startup after migrations.
  */
+// Catalog names no longer published. Escalation subjects carry the role token
+// (`system.escalation.{role}.{id}.{verb}`), so the roleless names are retired
+// from the catalog at seed time.
+const RETIRED_TOPICS = [
+    'system.escalation.*.created',
+    'system.escalation.*.resolved',
+    'system.escalation.*.claimed',
+    'system.escalation.*.released',
+];
 async function seedSystemTopics() {
     for (const def of SYSTEM_TOPICS) {
         try {
@@ -268,6 +305,12 @@ async function seedSystemTopics() {
             logger_1.loggerRegistry.warn(`[long-tail] topic seed failed for ${def.topic}: ${err.message}`);
         }
     }
+    for (const retired of RETIRED_TOPICS) {
+        try {
+            await (0, index_1.deleteTopic)(retired);
+        }
+        catch { /* absent on a fresh catalog */ }
+    }
 }
 /**
  * Seed user-declared topics from startConfig.topics[].

package/build/types/events.d.ts

@@ -4,16 +4,21 @@ import type { LTMilestone } from './task';
  *
  * System events use structured subjects with embedded resource IDs:
  *   `system.workflow.{workflowId}.completed`
- *   `system.escalation.{escalationId}.claimed`
+ *   `system.escalation.{role}.{escalationId}.claimed`
  *   `system.activity.{workflowId}.{activityName}.failed`
  *
+ * Escalation subjects carry the role as the organizing token — the queue is
+ * the unit of subscription. Scope to a role (`system.escalation.{role}.>`),
+ * a verb across roles (`system.escalation.*.*.created`), or one item across
+ * role hops (`system.escalation.*.{id}.>`).
+ *
  * On the wire (NATS): `lt.events.system.workflow.abc123.completed`
  * Dashboard subscribes: `lt.events.system.>` for all system events,
  * or `lt.events.system.workflow.abc123.>` for a specific workflow.
  *
  * The `*` segments in these patterns are replaced with actual IDs at publish time.
  */
-export type LTSystemEventPattern = `system.task.${string}.created` | `system.task.${string}.started` | `system.task.${string}.completed` | `system.task.${string}.escalated` | `system.task.${string}.failed` | `system.escalation.${string}.created` | `system.escalation.${string}.resolved` | `system.escalation.${string}.claimed` | `system.escalation.${string}.released` | `system.workflow.${string}.started` | `system.workflow.${string}.completed` | `system.workflow.${string}.failed` | `system.activity.${string}.${string}.started` | `system.activity.${string}.${string}.completed` | `system.activity.${string}.${string}.failed` | `system.knowledge.${string}.stored` | `system.knowledge.${string}.deleted` | 'system.file.stored' | 'system.file.deleted' | `system.agent.${string}.started` | `system.agent.${string}.completed` | `system.agent.${string}.failed` | `system.agent.${string}.status_changed` | `system.agent.${string}.triggers_changed` | `system.milestone.${string}`;
+export type LTSystemEventPattern = `system.task.${string}.created` | `system.task.${string}.started` | `system.task.${string}.completed` | `system.task.${string}.escalated` | `system.task.${string}.failed` | `system.escalation.${string}.${string}.created` | `system.escalation.${string}.${string}.resolved` | `system.escalation.${string}.${string}.claimed` | `system.escalation.${string}.${string}.released` | `system.escalation.${string}.${string}.cancelled` | `system.escalation.${string}.${string}.reassigned` | `system.escalation.${string}.${string}.expired` | `system.workflow.${string}.started` | `system.workflow.${string}.completed` | `system.workflow.${string}.failed` | `system.activity.${string}.${string}.started` | `system.activity.${string}.${string}.completed` | `system.activity.${string}.${string}.failed` | `system.knowledge.${string}.stored` | `system.knowledge.${string}.deleted` | 'system.file.stored' | 'system.file.deleted' | `system.agent.${string}.started` | `system.agent.${string}.completed` | `system.agent.${string}.failed` | `system.agent.${string}.status_changed` | `system.agent.${string}.triggers_changed` | `system.milestone.${string}`;
 /** @deprecated Use LTSystemEventPattern for system events. Kept for backward compat. */
 export type LTEventType = LTSystemEventPattern;
 /**
@@ -63,6 +68,8 @@ export interface LTEvent extends LTEventBase {
     taskId?: string;
     /** Escalation ID — present on escalation events. */
     escalationId?: string;
+    /** Escalation role (the queue) — present on escalation events. */
+    role?: string;
     /** Root process lineage — present on workflow/task/escalation events. */
     originId?: string;
     /** Lifecycle status. Vocabulary is per-family (see the family interfaces). */
@@ -91,9 +98,10 @@ export interface LTTaskEvent extends LTEventBase, LTWorkflowContext {
     status: string;
     milestones?: LTMilestone[];
 }
-/** `system.escalation.{escalationId}.{created|resolved|claimed|released}`. status ∈ pending|claimed|released|resolved|cancelled. */
+/** `system.escalation.{role}.{escalationId}.{created|resolved|claimed|released|cancelled|reassigned|expired}`. status ∈ pending|claimed|released|resolved|cancelled|expired. */
 export interface LTEscalationEvent extends LTEventBase, LTWorkflowContext {
     escalationId: string;
+    role: string;
     status: string;
 }
 /** `system.activity.{workflowId}.{activityName}.{started|completed|failed}`. */