nvent 0.4.4 → 0.5.0

package/dist/runtime/events/utils/stallDetector.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Flow Stall Detection System
+ *
+ * Detects and marks flows that have been in "running" state for too long without activity.
+ * Uses a hybrid approach:
+ * 1. Lazy detection: Check stall status when flows are queried (zero overhead)
+ * 2. Periodic cleanup: Background job that checks all running flows periodically (safety net)
+ *
+ * A flow is considered "stalled" when:
+ * - Status is "running"
+ * - No activity (step events) for longer than STALL_TIMEOUT
+ * - lastActivityAt timestamp is older than threshold
+ */
+import type { StoreAdapter } from '../../adapters/interfaces/store.js';
+export interface StallDetectorConfig {
+    /**
+     * Time in milliseconds after which a running flow without activity is considered stalled
+     * @default 1800000 (30 minutes)
+     */
+    stallTimeout?: number;
+    /**
+     * Interval in milliseconds for periodic stall checks
+     * @default 900000 (15 minutes)
+     */
+    checkInterval?: number;
+    /**
+     * Enable periodic background checks
+     * Set to false to use only lazy detection
+     * @default true
+     */
+    enablePeriodicCheck?: boolean;
+}
+export type FlowStatus = 'running' | 'completed' | 'failed' | 'canceled' | 'stalled';
+export interface FlowActivity {
+    runId: string;
+    flowName: string;
+    status: FlowStatus;
+    startedAt: number;
+    lastActivityAt: number;
+    metadata?: any;
+}
+export declare class FlowStallDetector {
+    private store;
+    private config;
+    private logger;
+    private schedulerJobId?;
+    private started;
+    constructor(store: StoreAdapter, config?: StallDetectorConfig);
+    /**
+     * Start the periodic stall detector
+     * Should be called once per instance after adapters are initialized
+     * Runs startup recovery to clean up flows from previous server instances
+     */
+    start(): Promise<void>;
+    /**
+     * Get the configuration for scheduling
+     * Returns config needed by flowWiring to register the scheduler job
+     */
+    getScheduleConfig(): {
+        enabled: boolean;
+        interval: number;
+        stallTimeout: number;
+    };
+    /**
+     * Set the scheduler job ID (called from flowWiring after scheduling)
+     */
+    setSchedulerJobId(jobId: string): void;
+    /**
+     * Stop the periodic stall detector
+     */
+    stop(): Promise<void>;
+    /**
+     * Get stall timeout for a specific flow
+     * Uses flow-specific timeout from analyzed metadata, falls back to global config
+     */
+    private getFlowStallTimeout;
+    /**
+     * Update activity timestamp for a flow
+     * Should be called on every step event (started, completed, failed, retry)
+     */
+    updateActivity(flowName: string, runId: string): Promise<void>;
+    /**
+     * Check if a specific flow is stalled (lazy detection)
+     * Returns true if the flow should be marked as stalled
+     * v0.5: Await-aware - uses flow-specific timeout and skips awaiting flows
+     */
+    isStalled(flowName: string, runId: string): Promise<boolean>;
+    /**
+     * Mark a flow as stalled
+     * Emits a flow.stalled event and updates the flow status
+     */
+    markAsStalled(flowName: string, runId: string, reason?: string): Promise<void>;
+    /**
+     * Check all running flows and mark stalled ones
+     * This is called by the periodic background job
+     *
+     * Note: This method requires knowledge of which flows exist.
+     * For now, we'll need to pass flow names to check, or iterate known flows from registry.
+     */
+    checkFlowsForStalls(flowNames: string[]): Promise<void>;
+    /**
+     * Run startup recovery to clean up flows left in running state from previous server instance
+     * This marks all running flows as stalled since their in-memory state is lost
+     * Also validates and cleans up flow stats index
+     */
+    private runStartupRecovery;
+    /**
+     * Validate flow stats index and remove entries for non-existent flows
+     * Also corrects running/awaiting counts based on actual scanned data
+     *
+     * NOTE: We only validate running/awaiting counts because:
+     * - They are small snapshot values (usually < 100)
+     * - We already scanned all flows during startup recovery
+     * - Discrepancies indicate actual bugs (flows stuck in wrong state)
+     *
+     * We do NOT validate total/success/failure/cancel because:
+     * - These are cumulative counters that can be millions in production
+     * - Validation would require full table scan (prohibitively expensive)
+     * - Minor discrepancies don't affect runtime behavior
+     */
+    private validateFlowStats;
+    /**
+     * Internal method for periodic checks
+     * Gets flow names from registry and checks them
+     */
+    private checkAllRunningFlows;
+    /**
+     * Get stall detector statistics
+     */
+    getStats(): {
+        enabled: boolean;
+        periodicCheckEnabled: boolean;
+        stallTimeout: number;
+        checkInterval: number;
+    };
+}
+/**
+ * Create and configure a flow stall detector
+ */
+export declare function createStallDetector(store: StoreAdapter, config?: StallDetectorConfig): FlowStallDetector;

package/dist/runtime/events/utils/stallDetector.js

@@ -0,0 +1,436 @@
+import { useNventLogger, useStreamTopics, $useAnalyzedFlows, useScheduler } from "#imports";
+const DEFAULT_STALL_TIMEOUT = 30 * 60 * 1e3;
+const DEFAULT_CHECK_INTERVAL = 15 * 60 * 1e3;
+export class FlowStallDetector {
+  store;
+  config;
+  logger = useNventLogger("stall-detector");
+  schedulerJobId;
+  started = false;
+  constructor(store, config = {}) {
+    this.store = store;
+    this.config = {
+      stallTimeout: config.stallTimeout ?? DEFAULT_STALL_TIMEOUT,
+      checkInterval: config.checkInterval ?? DEFAULT_CHECK_INTERVAL,
+      enablePeriodicCheck: config.enablePeriodicCheck ?? true
+    };
+  }
+  /**
+   * Start the periodic stall detector
+   * Should be called once per instance after adapters are initialized
+   * Runs startup recovery to clean up flows from previous server instances
+   */
+  async start() {
+    if (this.started) {
+      this.logger.warn("Stall detector already started");
+      return;
+    }
+    this.started = true;
+    await this.runStartupRecovery();
+    this.logger.info(`Stall detector started - periodicCheck: ${this.config.enablePeriodicCheck}, stallTimeout: ${this.config.stallTimeout / 1e3}s, checkInterval: ${this.config.checkInterval / 1e3}s`);
+  }
+  /**
+   * Get the configuration for scheduling
+   * Returns config needed by flowWiring to register the scheduler job
+   */
+  getScheduleConfig() {
+    return {
+      enabled: this.config.enablePeriodicCheck,
+      interval: this.config.checkInterval,
+      stallTimeout: this.config.stallTimeout
+    };
+  }
+  /**
+   * Set the scheduler job ID (called from flowWiring after scheduling)
+   */
+  setSchedulerJobId(jobId) {
+    this.schedulerJobId = jobId;
+  }
+  /**
+   * Stop the periodic stall detector
+   */
+  async stop() {
+    if (this.schedulerJobId) {
+      try {
+        const scheduler = useScheduler();
+        await scheduler.unschedule(this.schedulerJobId);
+        this.schedulerJobId = void 0;
+        this.logger.info("Stopped periodic stall detector");
+      } catch (error) {
+        this.logger.error(`Failed to stop stall detector: ${error.message}`);
+      }
+    }
+    this.started = false;
+  }
+  /**
+   * Get stall timeout for a specific flow
+   * Uses flow-specific timeout from analyzed metadata, falls back to global config
+   */
+  async getFlowStallTimeout(flowName) {
+    try {
+      const analyzedFlows = $useAnalyzedFlows();
+      const flowMeta = analyzedFlows.find((f) => f.id === flowName);
+      if (flowMeta?.stallTimeout) {
+        this.logger.debug(`Using flow-specific stall timeout for '${flowName}': ${flowMeta.stallTimeout / 1e3}s`);
+        return flowMeta.stallTimeout;
+      }
+    } catch (error) {
+      this.logger.warn(`Failed to get flow-specific stall timeout for '${flowName}': ${error.message}`);
+    }
+    return this.config.stallTimeout;
+  }
+  /**
+   * Update activity timestamp for a flow
+   * Should be called on every step event (started, completed, failed, retry)
+   */
+  async updateActivity(flowName, runId) {
+    const { StoreSubjects } = useStreamTopics();
+    const indexKey = StoreSubjects.flowRunIndex(flowName);
+    try {
+      if (!this.store.index.update) {
+        this.logger.warn("Store does not support indexUpdate, cannot update activity");
+        return;
+      }
+      await this.store.index.update(indexKey, runId, {
+        lastActivityAt: Date.now()
+      });
+    } catch (error) {
+      this.logger.warn(`Failed to update flow activity for '${flowName}' runId '${runId}': ${error.message}`);
+    }
+  }
+  /**
+   * Check if a specific flow is stalled (lazy detection)
+   * Returns true if the flow should be marked as stalled
+   * v0.5: Await-aware - uses flow-specific timeout and skips awaiting flows
+   */
+  async isStalled(flowName, runId) {
+    const { StoreSubjects } = useStreamTopics();
+    const indexKey = StoreSubjects.flowRunIndex(flowName);
+    try {
+      if (!this.store.index.get) return false;
+      const flowEntry = await this.store.index.get(indexKey, runId);
+      if (!flowEntry?.metadata) return false;
+      if (flowEntry.metadata.status !== "running") return false;
+      const awaitingSteps = flowEntry.metadata.awaitingSteps || {};
+      const hasActiveAwaits = Object.keys(awaitingSteps).length > 0;
+      if (hasActiveAwaits) {
+        this.logger.debug(`Flow '${flowName}' runId '${runId}' has active awaits [${Object.keys(awaitingSteps).join(", ")}], skipping stall check`);
+        return false;
+      }
+      const stallTimeout = await this.getFlowStallTimeout(flowName);
+      const lastActivity = flowEntry.metadata.lastActivityAt || flowEntry.metadata.startedAt || 0;
+      const timeSinceActivity = Date.now() - lastActivity;
+      if (timeSinceActivity > stallTimeout) {
+        this.logger.info(`Flow detected as stalled (lazy check) - '${flowName}' runId '${runId}': ${Math.round(timeSinceActivity / 1e3)}s since activity (timeout: ${stallTimeout / 1e3}s)`);
+        return true;
+      }
+      return false;
+    } catch (error) {
+      this.logger.warn(`Failed to check if flow is stalled for '${flowName}' runId '${runId}': ${error.message}`);
+      return false;
+    }
+  }
+  /**
+   * Mark a flow as stalled
+   * Emits a flow.stalled event and updates the flow status
+   */
+  async markAsStalled(flowName, runId, reason = "No activity timeout") {
+    const { StoreSubjects } = useStreamTopics();
+    const indexKey = StoreSubjects.flowRunIndex(flowName);
+    try {
+      if (!this.store.index.get) {
+        this.logger.warn("Store does not support indexGet, cannot mark as stalled");
+        return;
+      }
+      const flowEntry = await this.store.index.get(indexKey, runId);
+      if (!flowEntry?.metadata) return;
+      const previousStatus = flowEntry.metadata.status;
+      if (previousStatus !== "running" && previousStatus !== "awaiting") return;
+      if (this.store.index.update) {
+        await this.store.index.update(indexKey, runId, {
+          status: "stalled",
+          previousStatus,
+          // Track what state it was in before stalling
+          stalledAt: Date.now(),
+          stallReason: reason
+        });
+      }
+      const streamName = StoreSubjects.flowRun(runId);
+      await this.store.stream.append(streamName, {
+        type: "flow.stalled",
+        runId,
+        flowName,
+        data: {
+          reason,
+          previousStatus
+          // Include previous status so stats handler knows which counter to decrement
+        }
+      });
+      this.logger.info(`Marked flow as stalled - '${flowName}' runId '${runId}': ${reason}`);
+    } catch (error) {
+      this.logger.error(`Failed to mark flow as stalled for '${flowName}' runId '${runId}': ${error.message}`);
+    }
+  }
+  /**
+   * Check all running flows and mark stalled ones
+   * This is called by the periodic background job
+   *
+   * Note: This method requires knowledge of which flows exist.
+   * For now, we'll need to pass flow names to check, or iterate known flows from registry.
+   */
+  async checkFlowsForStalls(flowNames) {
+    this.logger.info(`Running periodic stall check for ${flowNames.length} flows`);
+    try {
+      if (!this.store.index.get || !this.store.index.read) {
+        this.logger.warn("Store does not support required index operations");
+        return;
+      }
+      const { StoreSubjects } = useStreamTopics();
+      let checkedCount = 0;
+      let stalledCount = 0;
+      for (const flowName of flowNames) {
+        const indexKey = StoreSubjects.flowRunIndex(flowName);
+        const flowStallTimeout = await this.getFlowStallTimeout(flowName);
+        const entries = await this.store.index.read(indexKey, { limit: 1e3 });
+        for (const entry of entries) {
+          if (!entry.metadata) continue;
+          checkedCount++;
+          if (entry.metadata.status !== "running" && entry.metadata.status !== "awaiting") continue;
+          const awaitingSteps = entry.metadata.awaitingSteps || {};
+          const awaitingStepNames = Object.keys(awaitingSteps);
+          if (awaitingStepNames.length > 0) {
+            let hasOverdueAwaits = false;
+            let hasLegacyAwait = false;
+            for (const stepName of awaitingStepNames) {
+              const awaitState = awaitingSteps[stepName];
+              if (awaitState?.status === "awaiting") {
+                if (!awaitState.timeoutAt) {
+                  hasLegacyAwait = true;
+                } else if (Date.now() > awaitState.timeoutAt) {
+                  hasOverdueAwaits = true;
+                  break;
+                }
+              }
+            }
+            if (hasOverdueAwaits) {
+              await this.markAsStalled(flowName, entry.id, "Await pattern timed out");
+              stalledCount++;
+              continue;
+            }
+            if (hasLegacyAwait) {
+              this.logger.debug(`Skipping flow with legacy await (no timeout) - '${flowName}' runId '${entry.id}'`);
+            }
+            continue;
+          }
+          const lastActivity = entry.metadata.lastActivityAt || entry.metadata.startedAt || 0;
+          const timeSinceActivity = Date.now() - lastActivity;
+          if (timeSinceActivity > flowStallTimeout) {
+            await this.markAsStalled(flowName, entry.id, "Periodic check detected no activity");
+            stalledCount++;
+          }
+        }
+      }
+      this.logger.info(`Periodic stall check completed - checked: ${checkedCount}, stalled: ${stalledCount}`);
+    } catch (error) {
+      this.logger.error("Failed to run periodic stall check", {
+        error: error.message
+      });
+    }
+  }
+  /**
+   * Run startup recovery to clean up flows left in running state from previous server instance
+   * This marks all running flows as stalled since their in-memory state is lost
+   * Also validates and cleans up flow stats index
+   */
+  async runStartupRecovery() {
+    this.logger.info("Running startup recovery to check for orphaned flows and validate stats");
+    try {
+      if (!this.store.index.get || !this.store.index.read) {
+        this.logger.warn("Store does not support required index operations");
+        return;
+      }
+      const analyzedFlows = $useAnalyzedFlows();
+      const flowNames = analyzedFlows.map((f) => f.id).filter(Boolean);
+      this.logger.info(`Starting flow recovery check for ${flowNames.length} registered flows: [${flowNames.join(", ")}]`);
+      if (flowNames.length === 0) {
+        this.logger.debug("No flows registered, skipping startup recovery");
+        return;
+      }
+      const { StoreSubjects } = useStreamTopics();
+      let recoveredCount = 0;
+      const actualCounts = {};
+      for (const flowName of flowNames) {
+        actualCounts[flowName] = { running: 0, awaiting: 0 };
+        const indexKey = StoreSubjects.flowRunIndex(flowName);
+        this.logger.debug(`Reading flow run index for '${flowName}': ${indexKey}`);
+        const entries = await this.store.index.read(indexKey, { limit: 1e3 });
+        const statusCounts = {};
+        for (const entry of entries) {
+          if (!entry.metadata) {
+            this.logger.debug(`Skipping entry without metadata - '${flowName}' runId '${entry.id}'`);
+            continue;
+          }
+          const status = entry.metadata.status || "unknown";
+          statusCounts[status] = (statusCounts[status] || 0) + 1;
+          if (status === "running") {
+            actualCounts[flowName].running++;
+          } else if (status === "awaiting") {
+            actualCounts[flowName].awaiting++;
+          }
+          if (entry.metadata.status === "running" || entry.metadata.status === "awaiting") {
+            const awaitingSteps = entry.metadata.awaitingSteps || {};
+            const awaitingStepNames = Object.keys(awaitingSteps);
+            this.logger.info(`Found flow in ${entry.metadata.status} state - '${flowName}' runId '${entry.id}' with ${awaitingStepNames.length} awaiting steps`);
+            this.logger.debug(`Flow '${flowName}' runId '${entry.id}' status: ${entry.metadata.status}, awaitingSteps: ${awaitingStepNames.length}`);
+            if (awaitingStepNames.length > 0) {
+              let hasActiveValidAwaits = false;
+              let hasOverdueAwaits = false;
+              for (const stepName of awaitingStepNames) {
+                const awaitState = awaitingSteps[stepName];
+                this.logger.info(`Checking await state for '${flowName}' runId '${entry.id}' step '${stepName}': status=${awaitState?.status}, timeoutAt=${awaitState?.timeoutAt}, resolveAt=${awaitState?.resolveAt}`);
+                if (awaitState?.status === "awaiting") {
+                  const timeoutAt = awaitState.timeoutAt || awaitState.resolveAt;
+                  if (!timeoutAt) {
+                    hasActiveValidAwaits = true;
+                    this.logger.warn(`Found await without timeout (legacy data) - '${flowName}' runId '${entry.id}' step '${stepName}' - treating as valid (timeout tracking was added later)`);
+                  } else if (Date.now() > timeoutAt) {
+                    hasOverdueAwaits = true;
+                    this.logger.warn(`Found overdue await pattern - '${flowName}' runId '${entry.id}' step '${stepName}': timeoutAt=${new Date(timeoutAt).toISOString()}, overdueBy=${Math.round((Date.now() - timeoutAt) / 1e3)}s`);
+                  } else {
+                    hasActiveValidAwaits = true;
+                    this.logger.debug(`Found active valid await - '${flowName}' runId '${entry.id}' step '${stepName}': remaining=${Math.round((timeoutAt - Date.now()) / 1e3)}s`);
+                  }
+                }
+              }
+              if (hasOverdueAwaits) {
+                this.logger.info(`Marking flow as stalled (overdue awaits) - '${flowName}' runId '${entry.id}'`);
+                await this.markAsStalled(flowName, entry.id, "Await pattern resolution failed or expired");
+                recoveredCount++;
+                continue;
+              }
+              if (hasActiveValidAwaits) {
+                if (entry.metadata.status === "running") {
+                  if (this.store.index.update) {
+                    await this.store.index.update(indexKey, entry.id, {
+                      status: "awaiting"
+                    });
+                    this.logger.info(`Updated flow status to awaiting (has active awaits) - '${flowName}' runId '${entry.id}' steps: [${awaitingStepNames.join(", ")}]`);
+                  }
+                } else {
+                  this.logger.debug(`Flow already has awaiting status - '${flowName}' runId '${entry.id}'`);
+                }
+                continue;
+              }
+            }
+            this.logger.info(`Marking flow as stalled (no active awaits) - '${flowName}' runId '${entry.id}'`);
+            await this.markAsStalled(flowName, entry.id, "Server restart - flow state lost");
+            recoveredCount++;
+          }
+        }
+        const statusSummary = Object.entries(statusCounts).map(([status, count]) => `${status}:${count}`).join(", ");
+        this.logger.info(`Flow recovery summary for '${flowName}' - total: ${entries.length}, statuses: {${statusSummary}}`);
+      }
+      await this.validateFlowStats(flowNames, actualCounts);
+      if (recoveredCount > 0) {
+        this.logger.info(`Startup recovery completed - marked ${recoveredCount} orphaned flow(s) as stalled`);
+      } else {
+        this.logger.debug("Startup recovery completed - no orphaned flows found");
+      }
+    } catch (error) {
+      this.logger.error(`Failed to run startup recovery: ${error.message}`);
+    }
+  }
+  /**
+   * Validate flow stats index and remove entries for non-existent flows
+   * Also corrects running/awaiting counts based on actual scanned data
+   *
+   * NOTE: We only validate running/awaiting counts because:
+   * - They are small snapshot values (usually < 100)
+   * - We already scanned all flows during startup recovery
+   * - Discrepancies indicate actual bugs (flows stuck in wrong state)
+   *
+   * We do NOT validate total/success/failure/cancel because:
+   * - These are cumulative counters that can be millions in production
+   * - Validation would require full table scan (prohibitively expensive)
+   * - Minor discrepancies don't affect runtime behavior
+   */
+  async validateFlowStats(validFlowNames, actualCounts) {
+    this.logger.debug("Validating flow stats index");
+    try {
+      if (!this.store.index.read || !this.store.index.delete || !this.store.index.update) {
+        this.logger.debug("Store does not support stats validation operations");
+        return;
+      }
+      const { StoreSubjects } = useStreamTopics();
+      const statsIndexKey = StoreSubjects.flowIndex();
+      const statsEntries = await this.store.index.read(statsIndexKey, { limit: 1e4 });
+      let removedCount = 0;
+      let correctedCount = 0;
+      for (const entry of statsEntries) {
+        const flowName = entry.id;
+        if (!validFlowNames.includes(flowName)) {
+          this.logger.info(`Removing stats for non-existent flow '${flowName}'`);
+          await this.store.index.delete(statsIndexKey, flowName);
+          removedCount++;
+          continue;
+        }
+        if (!entry.metadata?.stats) {
+          this.logger.warn(`Flow stats entry missing stats object for '${flowName}'`);
+          continue;
+        }
+        const stats = entry.metadata.stats;
+        const actual = actualCounts[flowName] || { running: 0, awaiting: 0 };
+        const runningMismatch = stats.running !== actual.running;
+        const awaitingMismatch = stats.awaiting !== actual.awaiting;
+        if (runningMismatch || awaitingMismatch) {
+          this.logger.warn(`Flow stats mismatch detected for '${flowName}' - stored: running=${stats.running} awaiting=${stats.awaiting}, actual: running=${actual.running} awaiting=${actual.awaiting} - correcting`);
+          await this.store.index.update(statsIndexKey, flowName, {
+            stats: {
+              running: actual.running,
+              awaiting: actual.awaiting
+            }
+          });
+          correctedCount++;
+        }
+      }
+      if (removedCount > 0 || correctedCount > 0) {
+        this.logger.info(`Flow stats validation completed - removed ${removedCount} orphaned stats, corrected ${correctedCount} running/awaiting counts`);
+      } else {
+        this.logger.debug("Flow stats validation completed - all stats accurate");
+      }
+    } catch (error) {
+      this.logger.error(`Failed to validate flow stats: ${error.message}`);
+    }
+  }
+  /**
+   * Internal method for periodic checks
+   * Gets flow names from registry and checks them
+   */
+  async checkAllRunningFlows() {
+    try {
+      const analyzedFlows = $useAnalyzedFlows();
+      const flowNames = analyzedFlows.map((f) => f.id).filter(Boolean);
+      if (flowNames.length === 0) {
+        this.logger.debug("No flows registered, skipping stall check");
+        return;
+      }
+      await this.checkFlowsForStalls(flowNames);
+    } catch (error) {
+      this.logger.error(`Failed to run periodic stall check: ${error.message}`);
+    }
+  }
+  /**
+   * Get stall detector statistics
+   */
+  getStats() {
+    return {
+      enabled: this.started,
+      periodicCheckEnabled: this.config.enablePeriodicCheck,
+      stallTimeout: this.config.stallTimeout,
+      checkInterval: this.config.checkInterval
+    };
+  }
+}
+export function createStallDetector(store, config) {
+  return new FlowStallDetector(store, config);
+}

package/dist/runtime/events/utils/triggerRuntime.d.ts

@@ -0,0 +1,58 @@
+import type { TriggerEntry, TriggerSubscription } from '../../../registry/types.js';
+import type { StoreAdapter } from '../../adapters/interfaces/store.js';
+/**
+ * Centralized trigger runtime management
+ * Handles runtime state, payload storage/resolution, and state manipulation
+ *
+ * This class is the single source of truth for trigger runtime state,
+ * used by both useTrigger (public API) and triggerWiring (event orchestration)
+ */
+export declare class TriggerRuntime {
+    private state;
+    private store;
+    private logger;
+    constructor(store: StoreAdapter, logger: any);
+    get initialized(): boolean;
+    setInitialized(value: boolean): void;
+    hasTrigger(name: string): boolean;
+    getTrigger(name: string): TriggerEntry | undefined;
+    getAllTriggers(options?: {
+        sortBy?: 'registeredAt' | 'lastActivityAt' | 'name';
+        order?: 'asc' | 'desc';
+        limit?: number;
+        offset?: number;
+    }): TriggerEntry[];
+    getSubscribedFlows(trigger: string): string[];
+    getFlowTriggers(flow: string): string[];
+    getSubscription(trigger: string, flow: string): TriggerSubscription | undefined;
+    getAllSubscriptions(): TriggerSubscription[];
+    getRuntimeStats(): {
+        triggerCount: number;
+        subscriptionCount: number;
+        flowCount: number;
+        initialized: boolean;
+    };
+    addTrigger(name: string, entry: TriggerEntry): void;
+    removeTrigger(name: string): void;
+    addSubscription(triggerName: string, flowName: string, subscription: TriggerSubscription): void;
+    removeSubscription(triggerName: string, flowName: string): void;
+    /**
+     * Extract a minimal summary from payload for debugging
+     * Keeps only small, identifying fields
+     */
+    private extractSummary;
+    /**
+     * Store large payload in KV store and return reference
+     * Returns either the original data (if small) or a reference object
+     */
+    handleLargePayload(triggerName: string, data: any, threshold: number): Promise<any>;
+    /**
+     * Resolve payload reference if needed
+     * Returns the full payload from KV store, or falls back to summary if expired
+     */
+    resolvePayload(data: any): Promise<any>;
+}
+/**
+ * Get or create the singleton TriggerRuntime instance
+ */
+export declare function getTriggerRuntime(store: StoreAdapter, logger: any): TriggerRuntime;