@hotmeshio/long-tail 0.4.18 → 0.4.20

package/README.md

@@ -62,8 +62,6 @@ Dashboard at [http://localhost:3000](http://localhost:3000). The [boilerplate](h
 
 ## The pattern
 
-Most systems start with a durable workflow and stop there. Long Tail keeps going.
-
 **Step 1 — Author a durable workflow.** Your function checkpoints to Postgres. It can sleep, branch, call child workflows, wait for signals. Standard durable execution.
 
 **Step 2 — Certify it.** Promotion to certified adds interceptor guarantees: failures escalate instead of throwing, escalation chains route through RBAC-scoped roles, and every error is either handled or surfaced. It cannot silently fail.

package/build/api/auth-sso.d.ts

@@ -0,0 +1,12 @@
+import type { Request } from 'express';
+import type { LTApiResult } from '../types/sdk';
+/**
+ * Exchange host authentication for a Long Tail JWT.
+ *
+ * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * the user in `lt_users`, and returns a signed JWT the dashboard can
+ * store for subsequent API calls.
+ *
+ * No request body required — the host's cookies/headers carry the auth.
+ */
+export declare function exchangeSSO(req: Request): Promise<LTApiResult>;

package/build/api/auth-sso.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeSSO = exchangeSSO;
+const sso_1 = require("../modules/sso");
+const sso_provision_1 = require("../services/user/sso-provision");
+const auth_1 = require("../modules/auth");
+/**
+ * Exchange host authentication for a Long Tail JWT.
+ *
+ * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * the user in `lt_users`, and returns a signed JWT the dashboard can
+ * store for subsequent API calls.
+ *
+ * No request body required — the host's cookies/headers carry the auth.
+ */
+async function exchangeSSO(req) {
+    try {
+        const ssoConfig = (0, sso_1.getSSOConfig)();
+        if (!ssoConfig) {
+            return { status: 404, error: 'SSO not configured' };
+        }
+        const identity = await ssoConfig.resolve(req);
+        if (!identity) {
+            return { status: 401, error: 'Host authentication required' };
+        }
+        const provisioned = await (0, sso_provision_1.ssoProvision)(identity, ssoConfig);
+        const highestType = provisioned.roles.some((r) => r.type === 'superadmin')
+            ? 'superadmin'
+            : provisioned.roles.some((r) => r.type === 'admin')
+                ? 'admin'
+                : 'member';
+        const token = (0, auth_1.signToken)({
+            userId: provisioned.userId,
+            role: highestType,
+            roles: provisioned.roles,
+            sso: true,
+        }, '24h');
+        return {
+            status: 200,
+            data: {
+                token,
+                user: {
+                    id: provisioned.userId,
+                    external_id: identity.externalId,
+                    display_name: identity.displayName || identity.externalId,
+                    roles: provisioned.roles,
+                },
+            },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/escalations/bulk.js

@@ -141,8 +141,8 @@ async function bulkAssign(input, auth) {
         if (!perm.allowed)
             return perm;
         // Non-superadmin: target user must hold each escalation's role
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const roles = await escalationService.getEscalationRoles(ids);
             for (const role of roles) {
                 const targetHasRole = await userService.hasRole(targetUserId, role);

package/build/api/escalations/claim.js

@@ -37,7 +37,7 @@ exports.claimEscalation = claimEscalation;
 exports.releaseEscalation = releaseEscalation;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
-const publish_1 = require("../../lib/events/publish");
+const helpers_1 = require("./helpers");
 /**
  * Claim a pending escalation for the authenticated user.
  *
@@ -57,8 +57,8 @@ async function claimEscalation(input, auth) {
         if (!escalation) {
             return { status: 404, error: 'Escalation not found' };
         }
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, escalation.role);
             if (!userHasRole) {
                 return {
@@ -94,16 +94,6 @@ async function releaseEscalation(input, auth) {
         if (!result) {
             return { status: 409, error: 'Escalation not found or not claimed by you' };
         }
-        (0, publish_1.publishEscalationEvent)({
-            type: 'escalation.released',
-            source: 'api',
-            workflowId: result.workflow_id || '',
-            workflowName: result.workflow_type || '',
-            taskQueue: result.task_queue || '',
-            escalationId: input.id,
-            status: 'released',
-            data: { released_by: auth.userId },
-        });
         return { status: 200, data: { escalation: result } };
     }
     catch (err) {

package/build/api/escalations/create.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
+const helpers_1 = require("./helpers");
 // ── Create ────────────────────────────────────────────────────────────────
 /**
  * Create a standalone escalation (not tied to a workflow).
@@ -65,8 +66,8 @@ async function createEscalation(input, auth) {
             return { status: 400, error: 'role is required' };
         }
         // RBAC: caller must hold the target role or be superadmin
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, role);
             if (!userHasRole) {
                 return { status: 403, error: `You must hold the "${role}" role or be a superadmin to create escalations for it` };

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

@@ -1,3 +1,4 @@
+export { hasGlobalEscalationAccess } from '../../services/user';
 export declare function getVisibleRoles(userId: string): Promise<string[] | undefined>;
 export declare function validateIds(ids: unknown): ids is string[];
 export declare function checkBulkPermission(userId: string, ids: string[]): Promise<{

package/build/api/escalations/helpers.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasGlobalEscalationAccess = void 0;
 exports.getVisibleRoles = getVisibleRoles;
 exports.validateIds = validateIds;
 exports.checkBulkPermission = checkBulkPermission;
@@ -42,9 +43,11 @@ const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const publish_1 = require("../../lib/events/publish");
 // ── Private helpers ────────────────────────────────────────────────────────
+// Re-export from service layer for use by escalation API modules
+var user_1 = require("../../services/user");
+Object.defineProperty(exports, "hasGlobalEscalationAccess", { enumerable: true, get: function () { return user_1.hasGlobalEscalationAccess; } });
 async function getVisibleRoles(userId) {
-    const isSuperAdminUser = await userService.isSuperAdmin(userId);
-    if (isSuperAdminUser)
+    if (await userService.hasGlobalEscalationAccess(userId))
         return undefined;
     const userRoles = await userService.getUserRoles(userId);
     return userRoles.map((r) => r.role);
@@ -53,15 +56,15 @@ function validateIds(ids) {
     return Array.isArray(ids) && ids.length > 0;
 }
 async function checkBulkPermission(userId, ids) {
-    const isSuperAdminUser = await userService.isSuperAdmin(userId);
-    if (isSuperAdminUser)
+    if (await userService.hasGlobalEscalationAccess(userId))
         return { allowed: true };
     const roles = await escalationService.getEscalationRoles(ids);
-    for (const role of roles) {
-        const canManage = await userService.isGroupAdmin(userId, role);
-        if (!canManage) {
-            return { allowed: false, status: 403, error: `Insufficient permissions for role "${role}"` };
-        }
+    if (!roles.length)
+        return { allowed: true };
+    // Single batched query instead of N+1 loop
+    const canManageAll = await userService.hasRolesAsAdmin(userId, roles);
+    if (!canManageAll) {
+        return { allowed: false, status: 403, error: 'Insufficient permissions for one or more escalation roles' };
     }
     return { allowed: true };
 }

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

@@ -24,6 +24,7 @@ export declare function listEscalations(input: {
     type?: string;
     subtype?: string;
     assigned_to?: string;
+    claimed?: boolean;
     priority?: number;
     limit?: number;
     offset?: number;

package/build/api/escalations/list.js

@@ -71,6 +71,7 @@ async function listEscalations(input, auth) {
             type: input.type,
             subtype: input.subtype,
             assigned_to: input.assigned_to,
+            claimed: input.claimed,
             priority: input.priority,
             limit: input.limit,
             offset: input.offset,

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

@@ -2,13 +2,8 @@ import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /**
  * Find escalations by a metadata key-value pair.
  *
- * Uses JSONB containment (`@>`) backed by a GIN index.
- * Results are RBAC-scoped to the caller's visible roles.
- *
- * @param input.key — metadata field name (e.g. `"orderId"`)
- * @param input.value — metadata field value (e.g. `"order-123"`)
- * @param input.status — optional status filter (e.g. `"pending"`)
- * @returns `{ status: 200, data: { escalations, total } }`
+ * Single query with window function for count. Results are
+ * RBAC-scoped to the caller's visible roles.
  */
 export declare function findByMetadata(input: {
     key: string;
@@ -20,15 +15,9 @@ export declare function findByMetadata(input: {
 /**
  * Claim an escalation by metadata key-value pair.
  *
- * Finds one available (pending + unassigned/expired) escalation matching
- * the metadata and claims it atomically. Optionally resolves an assignee
- * from an external_id.
- *
- * @param input.key — metadata field name
- * @param input.value — metadata field value
- * @param input.durationMinutes — claim duration (default 30)
- * @param input.assignee — optional external_id of the user to claim as
- * @returns `{ status: 200, data: { escalation, isExtension } }`
+ * Single atomic query. RBAC is enforced in the SQL WHERE clause —
+ * if the caller doesn't have an allowed role, zero rows match and
+ * the claim never happens. No pre-flight find, no TOCTOU.
  */
 export declare function claimByMetadata(input: {
     key: string;
@@ -40,14 +29,8 @@ export declare function claimByMetadata(input: {
 /**
  * Resolve an escalation by metadata key-value pair.
  *
- * Finds the pending escalation, auto-claims if unclaimed, then delegates
- * to the standard resolve logic (supports all 5 resolution paths).
- *
- * @param input.key — metadata field name
- * @param input.value — metadata field value
- * @param input.resolverPayload — resolution data for the workflow
- * @param input.assignee — optional external_id of the resolving user
- * @returns result from the standard resolve endpoint
+ * Single atomic CTE: find + claim + resolve in one query.
+ * RBAC is enforced in the SQL WHERE clause.
  */
 export declare function resolveByMetadata(input: {
     key: string;

package/build/api/escalations/metadata.js

@@ -42,13 +42,8 @@ const helpers_1 = require("./helpers");
 /**
  * Find escalations by a metadata key-value pair.
  *
- * Uses JSONB containment (`@>`) backed by a GIN index.
- * Results are RBAC-scoped to the caller's visible roles.
- *
- * @param input.key — metadata field name (e.g. `"orderId"`)
- * @param input.value — metadata field value (e.g. `"order-123"`)
- * @param input.status — optional status filter (e.g. `"pending"`)
- * @returns `{ status: 200, data: { escalations, total } }`
+ * Single query with window function for count. Results are
+ * RBAC-scoped to the caller's visible roles.
  */
 async function findByMetadata(input, auth) {
     try {
@@ -72,15 +67,9 @@ async function findByMetadata(input, auth) {
 /**
  * Claim an escalation by metadata key-value pair.
  *
- * Finds one available (pending + unassigned/expired) escalation matching
- * the metadata and claims it atomically. Optionally resolves an assignee
- * from an external_id.
- *
- * @param input.key — metadata field name
- * @param input.value — metadata field value
- * @param input.durationMinutes — claim duration (default 30)
- * @param input.assignee — optional external_id of the user to claim as
- * @returns `{ status: 200, data: { escalation, isExtension } }`
+ * Single atomic query. RBAC is enforced in the SQL WHERE clause —
+ * if the caller doesn't have an allowed role, zero rows match and
+ * the claim never happens. No pre-flight find, no TOCTOU.
  */
 async function claimByMetadata(input, auth) {
     try {
@@ -91,25 +80,17 @@ async function claimByMetadata(input, auth) {
         if ('error' in resolved)
             return resolved.error;
         const claimUserId = resolved.userId;
-        // RBAC: find the candidate to check role membership before atomic claim
-        const candidates = await escalationService.findByMetadata(input.key, input.value, 'pending', 1, 0);
-        if (candidates.escalations.length === 0) {
+        // Resolve allowed roles: null = global access (no filter), string[] = scoped
+        const allowedRoles = await resolveAllowedRoles(auth.userId);
+        const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes, input.metadata, allowedRoles);
+        if (!result) {
+            // No rows matched. Check if candidates existed (role mismatch vs no match).
             return { status: 404, error: 'No pending escalation found for this metadata' };
         }
-        const candidate = candidates.escalations[0];
-        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdmin) {
-            const userHasRole = await userService.hasRole(claimUserId, candidate.role);
-            if (!userHasRole) {
-                return { status: 403, error: `User must have the "${candidate.role}" role to claim this escalation` };
-            }
+        if (result.candidatesExist > 0 && !result.escalation) {
+            return { status: 403, error: 'Escalation exists but your roles do not permit claiming it' };
         }
-        const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes, input.metadata);
-        if (!result) {
-            return { status: 409, error: 'Escalation not available for claim' };
-        }
-        // Event published by service layer (services/escalation/crud.ts)
-        return { status: 200, data: result };
+        return { status: 200, data: { escalation: result.escalation, isExtension: result.isExtension } };
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -118,14 +99,8 @@ async function claimByMetadata(input, auth) {
 /**
  * Resolve an escalation by metadata key-value pair.
  *
- * Finds the pending escalation, auto-claims if unclaimed, then delegates
- * to the standard resolve logic (supports all 5 resolution paths).
- *
- * @param input.key — metadata field name
- * @param input.value — metadata field value
- * @param input.resolverPayload — resolution data for the workflow
- * @param input.assignee — optional external_id of the resolving user
- * @returns result from the standard resolve endpoint
+ * Single atomic CTE: find + claim + resolve in one query.
+ * RBAC is enforced in the SQL WHERE clause.
  */
 async function resolveByMetadata(input, auth) {
     try {
@@ -135,38 +110,29 @@ async function resolveByMetadata(input, auth) {
         if (!input.resolverPayload) {
             return { status: 400, error: 'resolverPayload is required' };
         }
-        const candidates = await escalationService.findByMetadata(input.key, input.value, 'pending', 1, 0);
-        if (candidates.escalations.length === 0) {
-            return { status: 404, error: 'No pending escalation found for this metadata' };
-        }
-        const escalation = candidates.escalations[0];
         const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
         if ('error' in resolved)
             return resolved.error;
         const resolveUserId = resolved.userId;
-        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdmin) {
-            const userHasRole = await userService.hasRole(resolveUserId, escalation.role);
-            if (!userHasRole) {
-                return { status: 403, error: `User must have the "${escalation.role}" role` };
-            }
-        }
-        // Merge additional metadata if provided
-        if (input.metadata && Object.keys(input.metadata).length > 0) {
-            await escalationService.updateEscalationMetadata(escalation.id, input.metadata);
-        }
-        // Auto-claim if unclaimed or expired
-        const isClaimed = escalation.assigned_to &&
-            escalation.assigned_until &&
-            new Date(escalation.assigned_until) > new Date();
-        if (!isClaimed) {
-            await escalationService.claimEscalation(escalation.id, resolveUserId, 5);
+        const allowedRoles = await resolveAllowedRoles(auth.userId);
+        const escalation = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, allowedRoles);
+        if (!escalation) {
+            return { status: 404, error: 'No pending escalation found for this metadata, or insufficient role permissions' };
         }
-        // Delegate to the full resolve logic (handles all 5 resolution paths)
-        const { resolveEscalation } = await Promise.resolve().then(() => __importStar(require('./resolve')));
-        return resolveEscalation({ id: escalation.id, resolverPayload: input.resolverPayload }, auth);
+        return { status: 200, data: { escalation } };
     }
     catch (err) {
         return { status: 500, error: err.message };
     }
 }
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Resolve the set of roles the caller is allowed to act on.
+ * Returns null for global access (superadmin/admin), or string[] for scoped users.
+ */
+async function resolveAllowedRoles(userId) {
+    if (await userService.hasGlobalEscalationAccess(userId))
+        return null;
+    const userRoles = await userService.getUserRoles(userId);
+    return userRoles.map(r => r.role);
+}

package/build/api/escalations/single.js

@@ -39,6 +39,7 @@ exports.escalateToRole = escalateToRole;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const roleService = __importStar(require("../../services/role"));
+const helpers_1 = require("./helpers");
 // ── Single-escalation routes ───────────────────────────────────────────────
 /**
  * Get a single escalation by ID.
@@ -55,8 +56,8 @@ async function getEscalation(input, auth) {
         if (!escalation) {
             return { status: 404, error: 'Escalation not found' };
         }
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, escalation.role);
             if (!userHasRole) {
                 return { status: 403, error: 'Not authorized to view this escalation' };

package/build/api/settings.js

@@ -7,6 +7,7 @@ const nats_1 = require("../lib/events/nats");
 const socketio_1 = require("../lib/events/socketio");
 const nats_ws_proxy_1 = require("../lib/events/nats-ws-proxy");
 const config_1 = require("../modules/config");
+const sso_1 = require("../modules/sso");
 const defaults_1 = require("../modules/defaults");
 const llm_1 = require("../services/llm");
 /**
@@ -60,6 +61,10 @@ async function getSettings(req) {
                     transport,
                     natsWsUrl: natsAdapter ? resolveNatsWsUrl(natsAdapter, req) : null,
                 },
+                auth: {
+                    sso: (0, sso_1.isSSOEnabled)(),
+                    ssoLogoutUrl: (0, sso_1.getSSOConfig)()?.logoutUrl ?? null,
+                },
                 ai: {
                     enabled: (0, llm_1.hasLLMApiKey)(),
                 },

package/build/api/topics.d.ts

@@ -20,8 +20,17 @@ export declare function updateTopic(input: {
 export declare function deleteTopic(input: {
     topic: string;
 }): Promise<LTApiResult>;
+/**
+ * Validate that a subject is a valid variant of a topic pattern.
+ * Each `*` in the pattern matches exactly one literal segment in the subject.
+ * Each `>` in the pattern matches one or more trailing segments.
+ * Literal segments must match exactly.
+ */
+export declare function isValidVariant(pattern: string, subject: string): boolean;
 export declare function publishTopic(input: {
     topic: string;
+    subject?: string;
+    eventId?: string;
     data: Record<string, any>;
     source?: string;
 }): Promise<LTApiResult>;

package/build/api/topics.js

@@ -38,6 +38,7 @@ exports.getTopic = getTopic;
 exports.createTopic = createTopic;
 exports.updateTopic = updateTopic;
 exports.deleteTopic = deleteTopic;
+exports.isValidVariant = isValidVariant;
 exports.publishTopic = publishTopic;
 const topicService = __importStar(require("../services/topics"));
 const events_1 = require("../lib/events");
@@ -104,10 +105,38 @@ async function deleteTopic(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Validate that a subject is a valid variant of a topic pattern.
+ * Each `*` in the pattern matches exactly one literal segment in the subject.
+ * Each `>` in the pattern matches one or more trailing segments.
+ * Literal segments must match exactly.
+ */
+function isValidVariant(pattern, subject) {
+    const patternParts = pattern.split('.');
+    const subjectParts = subject.split('.');
+    let pi = 0;
+    let si = 0;
+    while (pi < patternParts.length && si < subjectParts.length) {
+        const pp = patternParts[pi];
+        if (pp === '>')
+            return true; // match-rest: everything from here is valid
+        if (pp !== '*' && pp !== subjectParts[si])
+            return false;
+        pi++;
+        si++;
+    }
+    return pi === patternParts.length && si === subjectParts.length;
+}
 async function publishTopic(input) {
     try {
+        const publishSubject = input.subject || input.topic;
+        // Validate subject is a valid variant of the topic pattern
+        if (input.subject && !isValidVariant(input.topic, input.subject)) {
+            return { status: 400, error: `Subject "${input.subject}" does not match topic pattern "${input.topic}"` };
+        }
         const event = {
-            type: input.topic,
+            id: input.eventId,
+            type: publishSubject,
             source: input.source || 'dashboard',
             workflowId: '',
             workflowName: '',
@@ -116,7 +145,7 @@ async function publishTopic(input) {
             timestamp: new Date().toISOString(),
         };
         await events_1.eventRegistry.publish(event);
-        return { status: 200, data: { published: true, topic: input.topic, timestamp: event.timestamp } };
+        return { status: 200, data: { published: true, topic: publishSubject, timestamp: event.timestamp } };
     }
     catch (err) {
         return { status: 500, error: err.message };

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

@@ -12,6 +12,7 @@ declare class LTEventRegistry {
     connect(): Promise<void>;
     /**
      * Publish an event to all registered adapters.
+     * Auto-assigns an idempotent event ID if not provided.
      * Best-effort: individual adapter failures are logged, not thrown.
      */
     publish(event: LTEvent): Promise<void>;

package/build/lib/events/index.js

@@ -24,11 +24,15 @@ class LTEventRegistry {
     }
     /**
      * Publish an event to all registered adapters.
+     * Auto-assigns an idempotent event ID if not provided.
      * Best-effort: individual adapter failures are logged, not thrown.
      */
     async publish(event) {
         if (!this.adapters.length)
             return;
+        if (!event.id) {
+            event.id = `evt-${Date.now()}-${Math.random().toString(16).slice(2, 6)}`;
+        }
         await Promise.allSettled(this.adapters.map((a) => a.publish(event).catch((err) => {
             logger_1.loggerRegistry.error(`[lt-events] adapter publish failed: ${err?.message}`);
         })));

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

@@ -15,7 +15,8 @@ export declare function publishMilestoneEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish a task lifecycle event (created, started, completed, escalated, failed).
+ * Publish a task lifecycle event.
+ * Subject: system.task.{taskId}.{action}
  */
 export declare function publishTaskEvent(params: {
     type: 'task.created' | 'task.started' | 'task.completed' | 'task.escalated' | 'task.failed';
@@ -30,7 +31,8 @@ export declare function publishTaskEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish an escalation lifecycle event (created, resolved).
+ * Publish an escalation lifecycle event.
+ * Subject: system.escalation.{escalationId}.{action}
  */
 export declare function publishEscalationEvent(params: {
     type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released';
@@ -46,7 +48,7 @@ export declare function publishEscalationEvent(params: {
 }): Promise<void>;
 /**
  * Publish an activity lifecycle event for YAML workflow steps.
- * Lightweight — no payload data, just progress signals.
+ * Subject: system.activity.{workflowId}.{activityName}.{action}
  */
 export declare function publishActivityEvent(params: {
     type: 'activity.started' | 'activity.completed' | 'activity.failed';
@@ -57,9 +59,8 @@ export declare function publishActivityEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish a knowledge lifecycle event (stored, deleted).
- * Lightweight — no workflow context required since knowledge writes
- * happen both inside and outside workflows.
+ * Publish a knowledge lifecycle event.
+ * Subject: system.knowledge.{domain}.{action}
  */
 export declare function publishKnowledgeEvent(params: {
     type: 'knowledge.stored' | 'knowledge.deleted';
@@ -67,8 +68,8 @@ export declare function publishKnowledgeEvent(params: {
     key: string;
 }): Promise<void>;
 /**
- * Publish a file storage event (stored, deleted).
- * Includes rich metadata: path, name, extension, mime type, size.
+ * Publish a file storage event.
+ * Subject: system.file.{action}
  */
 export declare function publishFileEvent(params: {
     type: 'file.stored' | 'file.deleted';
@@ -78,6 +79,7 @@ export declare function publishFileEvent(params: {
 }): Promise<void>;
 /**
  * Publish an agent lifecycle event.
+ * Subject: system.agent.{agentName}.{action}
  */
 export declare function publishAgentEvent(params: {
     type: 'agent.started' | 'agent.completed' | 'agent.failed' | 'agent.status_changed';
@@ -87,7 +89,8 @@ export declare function publishAgentEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish a workflow lifecycle event (started, completed, failed).
+ * Publish a workflow lifecycle event.
+ * Subject: system.workflow.{workflowId}.{action}
  */
 export declare function publishWorkflowEvent(params: {
     type: 'workflow.started' | 'workflow.completed' | 'workflow.failed';