@zucker-framework/rule-engine 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,839 @@
+import { OnModuleDestroy, Logger } from '@nestjs/common';
+import { TopicEventBus } from '@zucker-framework/event';
+
+interface Term {
+    column: string;
+    termType: string;
+    value: unknown;
+    /** 嵌套条件组（对齐 jetlinks Term 嵌套） */
+    terms?: Term[];
+    /** 嵌套组的连接类型 */
+    termsType?: 'and' | 'or';
+}
+interface TermCondition {
+    terms: Term[];
+    type: 'and' | 'or';
+}
+declare class TermsEvaluator {
+    /**
+     * 注册自定义操作符 — 对齐 jetlinks 可扩展的 TermType
+     */
+    registerOperator(name: string, fn: (fieldValue: unknown, termValue: unknown) => boolean): void;
+    /**
+     * 获取已注册的所有操作符名称
+     */
+    getOperatorNames(): string[];
+    evaluate(data: Record<string, unknown>, condition: TermCondition): boolean;
+    private evaluateTerms;
+}
+
+interface ExpressionCondition {
+    expression: string;
+}
+/**
+ * ExpressionEvaluator — simple expression evaluation for rule-engine conditions.
+ *
+ * SECURITY NOTE: Node.js `vm` module is NOT a secure sandbox. It provides
+ * isolation from the host global scope but a determined attacker can escape.
+ * This evaluator is intended ONLY for trusted / admin-authored expressions,
+ * NOT for arbitrary user input from untrusted sources. Additional hardening
+ * (Object.freeze, timeout, arguments restriction) reduces the attack surface
+ * but does not eliminate all escape vectors.
+ */
+declare class ExpressionEvaluator {
+    /** Default timeout in milliseconds for expression evaluation */
+    private static readonly EVAL_TIMEOUT_MS;
+    evaluate(data: Record<string, unknown>, condition: ExpressionCondition): boolean;
+}
+
+/**
+ * Shake-limit (debounce / throttle) support for rule branches.
+ * Mirrors jetlinks ShakeLimit — prevents rapid re-triggering.
+ */
+interface ShakeLimitConfig {
+    /** Whether shake limiting is enabled. */
+    enabled: boolean;
+    /** Time window in milliseconds. */
+    time: number;
+    /** Maximum number of triggers allowed within the time window. */
+    threshold: number;
+    /** Alarm on drop — fire error event when messages are dropped. */
+    alarmFirst?: boolean;
+}
+interface ShakeLimitResult<T> {
+    /** The element that passed the shake limit. */
+    element: T;
+    /** Total number of triggers within the current window. */
+    times: number;
+}
+/**
+ * Creates a shake-limit filter that suppresses rapid invocations.
+ * Returns a function that decides whether to allow the current invocation.
+ *
+ * When alarmFirst is true, the first event that meets the threshold fires
+ * immediately. When false (default), only events within the threshold pass.
+ * This mirrors jetlinks ShakeLimit.transfer() semantics.
+ */
+declare function createShakeLimit(config: ShakeLimitConfig): {
+    tryAcquire: () => boolean;
+    reset: () => void;
+    getCurrentCount: () => number;
+};
+
+/**
+ * Branch condition evaluator — mirrors jetlinks SceneConditionAction.
+ *
+ * Supports if/else-if/else branching with:
+ * - Term-based conditions (field comparisons)
+ * - Expression-based conditions (JS expressions)
+ * - executeAnyway flag (always-run branches, like 'also' in addition to if/else)
+ * - Shake-limit (debounce) per branch
+ * - Parallel or serial action groups within each branch
+ */
+interface BranchActionGroup {
+    /** Whether actions in this group execute in parallel. */
+    parallel: boolean;
+    /** Action definitions to execute. */
+    actions: BranchAction[];
+}
+interface BranchAction {
+    /** Action type identifier. */
+    type: string;
+    /** Action-specific configuration. */
+    config: Record<string, unknown>;
+}
+interface BranchCondition {
+    /** Condition type: 'terms' or 'expression'. */
+    type: 'terms' | 'expression';
+    /** Condition configuration. */
+    config: TermCondition | ExpressionCondition;
+}
+interface Branch {
+    /** Unique branch identifier. */
+    id?: string;
+    /** Conditions to evaluate — if empty, acts as 'else'. */
+    when: BranchCondition[];
+    /** Action groups to execute when conditions are met. */
+    then: BranchActionGroup[];
+    /** Whether to execute this branch regardless of previous matches (default: false). */
+    executeAnyway?: boolean;
+    /** Optional shake-limit (debounce) configuration for this branch. */
+    shakeLimit?: ShakeLimitConfig;
+}
+interface BranchEvaluationResult {
+    /** Index of the matched branch (or -1 if none matched). */
+    branchIndex: number;
+    /** Branch id if specified. */
+    branchId?: string;
+    /** Whether the branch conditions were met. */
+    matched: boolean;
+    /** Action groups to execute. */
+    actionGroups: BranchActionGroup[];
+}
+declare class BranchEvaluator {
+    private readonly logger;
+    private readonly termsEvaluator;
+    private readonly expressionEvaluator;
+    private readonly shakeLimitMap;
+    /**
+     * Evaluate branches against data.
+     * Implements if/else-if/else semantics with executeAnyway support.
+     *
+     * Returns all branches that should fire (respecting executeAnyway and
+     * if/else-if ordering).
+     */
+    evaluate(branches: Branch[], data: Record<string, unknown>): BranchEvaluationResult[];
+    private evaluateConditions;
+    /** Reset all shake limiters. */
+    resetShakeLimits(): void;
+}
+
+/**
+ * Rule instance lifecycle states — mirrors jetlinks RuleInstanceState.
+ */
+declare enum RuleInstanceState {
+    /** Rule is started and actively processing. */
+    STARTED = "started",
+    /** Rule is disabled / stopped. */
+    DISABLED = "disabled",
+    /** Rule is paused (can be resumed without re-init). */
+    PAUSED = "paused"
+}
+
+/** Types of conditions that can be evaluated in a rule. */
+declare enum RuleConditionType {
+    TERMS = "TERMS",
+    EXPRESSION = "EXPRESSION"
+}
+declare enum RuleTriggerType {
+    EVENT = "EVENT",
+    TIMER = "TIMER",
+    MANUAL = "MANUAL"
+}
+declare enum RuleActionType {
+    NOTIFY = "NOTIFY",
+    HTTP = "HTTP",
+    SCRIPT = "SCRIPT",
+    DELAY = "DELAY",
+    DATA_MAPPING = "DATA_MAPPING"
+}
+interface RuleCondition {
+    type: RuleConditionType;
+    config: Record<string, unknown>;
+}
+interface RuleAction {
+    type: string;
+    config: Record<string, unknown>;
+    /** Output filter conditions — for serial execution, data must pass to continue. */
+    terms?: TermCondition;
+}
+interface RuleTrigger {
+    type: RuleTriggerType;
+    config: Record<string, unknown>;
+}
+/** Complete definition of a rule including its triggers, conditions, and actions. */
+interface RuleDefinition {
+    id: string;
+    name: string;
+    triggers: RuleTrigger[];
+    conditions: RuleCondition[];
+    /** Top-level actions (flat execution). */
+    actions: RuleAction[];
+    /** Conditional branches with action groups (when/then). */
+    branches?: Branch[];
+    /** Whether top-level actions run in parallel (default: false = serial). */
+    parallel?: boolean;
+    enabled: boolean;
+}
+/** Core service for registering, evaluating, and executing rules with event/timer triggers. */
+declare class RuleEngineService implements OnModuleDestroy {
+    private readonly eventBus?;
+    private readonly logger;
+    private activeRules;
+    private termsEvaluator;
+    private expressionEvaluator;
+    private notifyAction;
+    private httpAction;
+    private scriptAction;
+    private delayAction;
+    private dataMappingAction;
+    /** Strategy map for action execution — replaces switch/case in executeAction. */
+    private readonly actionHandlers;
+    constructor(eventBus?: TopicEventBus | undefined);
+    onModuleDestroy(): void;
+    startRule(definition: RuleDefinition): Promise<void>;
+    stopRule(id: string): Promise<void>;
+    pauseRule(id: string): Promise<void>;
+    resumeRule(id: string): Promise<void>;
+    stopAll(): void;
+    executeRule(definition: RuleDefinition, data: Record<string, unknown>): Promise<void>;
+    /** Execute branch conditions and their associated action groups. */
+    private executeBranches;
+    /** Execute an action group (parallel or serial). */
+    private executeActionGroup;
+    /** Execute actions in parallel. */
+    private executeActionsParallel;
+    /** Execute actions serially, passing output from one to the next. */
+    private executeActionsSerial;
+    private executeAction;
+    /** Set up a single trigger (event or timer) for a rule. */
+    private setupTrigger;
+    /** Evaluate all conditions for a rule — returns true if all pass. */
+    private evaluateConditions;
+    /** Evaluate a single condition by type. */
+    private evaluateSingleCondition;
+    getActiveRules(): RuleDefinition[];
+    isRuleActive(id: string): boolean;
+    getRuleState(id: string): RuleInstanceState | undefined;
+}
+
+interface NotifyActionConfig {
+    notifyType: string;
+    templateId?: string;
+    recipients: string[];
+    title?: string;
+    message?: string;
+    /** 变量映射（对齐 jetlinks 通知模板变量绑定） */
+    variables?: Record<string, string>;
+}
+/**
+ * 通知事件结构 — 通过事件总线发布
+ */
+interface NotifyEvent {
+    type: string;
+    templateId?: string;
+    recipients: string[];
+    title?: string;
+    message?: string;
+    data: Record<string, unknown>;
+    /** 解析后的变量值 */
+    resolvedVariables?: Record<string, unknown>;
+}
+/**
+ * 通知发送函数类型 — 由外部注入实现
+ */
+type NotifySender = (event: NotifyEvent) => Promise<void>;
+/**
+ * 通知动作执行器 — 对齐 jetlinks NotifyTaskExecutorProvider
+ *
+ * 增强：
+ * - 支持变量解析（从 data 中提取模板变量）
+ * - 支持外部注入通知发送器
+ */
+declare class NotifyAction {
+    private readonly logger;
+    private sender?;
+    /**
+     * 设置通知发送器（由模块初始化时注入）
+     */
+    setSender(sender: NotifySender): void;
+    execute(config: NotifyActionConfig, data: Record<string, unknown>): Promise<void>;
+    /**
+     * 验证通知配置
+     */
+    validate(config: NotifyActionConfig): void;
+    /**
+     * 解析变量路径 — 对齐 jetlinks VariableSource 解析
+     */
+    private resolveVariable;
+    private interpolate;
+}
+
+interface HttpActionConfig {
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout?: number;
+    /** 重试次数（默认 0 不重试） */
+    retryCount?: number;
+    /** 重试间隔（毫秒，默认 1000） */
+    retryDelay?: number;
+}
+/**
+ * HTTP 动作执行器 — 对齐 jetlinks 的数据推送能力
+ *
+ * 增强：
+ * - 支持重试机制
+ * - 模板表达式支持（在 URL、headers、body 中使用 ${variable}）
+ * - 响应规范化
+ */
+declare class HttpAction {
+    private readonly logger;
+    execute(config: HttpActionConfig, data: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 验证配置有效性
+     */
+    validate(config: HttpActionConfig): void;
+    private doRequest;
+    /**
+     * 模板插值 — 对齐 jetlinks TemplateParser / applyValueExpression
+     * 支持 ${key} 和嵌套路径 ${a.b.c}
+     */
+    private interpolate;
+    private getNestedValue;
+    private delay;
+}
+
+interface ScriptActionConfig {
+    script: string;
+    /** 脚本语言（目前仅支持 js） — 对齐 jetlinks ScriptTaskExecutorProvider.Config.lang */
+    lang?: string;
+    timeout?: number;
+}
+/**
+ * 脚本动作执行器 — 对齐 jetlinks ScriptTaskExecutorProvider
+ *
+ * 增强：
+ * - 支持 handler 模式（脚本中定义 onMessage 回调）
+ * - 对脚本返回值进行规范化处理
+ */
+declare class ScriptAction {
+    private readonly logger;
+    execute(config: ScriptActionConfig, data: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 验证脚本配置 — 对齐 jetlinks executor validate()
+     */
+    validate(config: ScriptActionConfig): void;
+    /**
+     * 规范化脚本返回值 — 对齐 jetlinks convertToJavaType
+     * 确保返回的是可序列化的纯对象
+     */
+    private normalizeResult;
+}
+
+/**
+ * Delay action — mirrors jetlinks DelayTaskExecutorProvider.
+ *
+ * Supports multiple pause types:
+ * - fixed delay
+ * - random delay
+ * - upstream-specified delay (delayv)
+ * - rate limiting
+ */
+type DelayPauseType = 'delay' | 'delayv' | 'random' | 'rate';
+type DelayTimeUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours';
+interface DelayActionConfig {
+    /** Type of delay behaviour. */
+    pauseType: DelayPauseType;
+    /** Fixed delay amount (for 'delay' type). */
+    timeout?: number;
+    /** Unit for timeout. */
+    timeoutUnits?: DelayTimeUnit;
+    /** Random delay lower bound (for 'random' type). */
+    randomFirst?: number;
+    /** Random delay upper bound (for 'random' type). */
+    randomLast?: number;
+    /** Unit for random delay. */
+    randomUnits?: DelayTimeUnit;
+    /** Rate limit: max events per window (for 'rate' type). */
+    rate?: number;
+    /** Rate window size. */
+    nbRateUnits?: number;
+    /** Rate window unit. */
+    rateUnits?: DelayTimeUnit;
+}
+declare class DelayAction {
+    private readonly logger;
+    /**
+     * Execute the delay according to the configured pause type.
+     * For 'delayv', the delay duration comes from `data.delay` (string parseable as ms).
+     * Returns the data after the delay completes.
+     */
+    execute(config: DelayActionConfig, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private calculateDelay;
+}
+
+/**
+ * Data-mapping action — mirrors jetlinks DataMappingTaskExecutorProvider.
+ *
+ * Transforms data by mapping source fields to target fields with optional
+ * type conversion, supporting expression-based source references.
+ */
+interface DataMapping {
+    /** Target field name in output. */
+    target: string;
+    /** Source field name or expression (supports ${expr} interpolation). */
+    source: string;
+    /** Optional type coercion: 'string' | 'number' | 'boolean' | 'integer' | 'decimal'. */
+    type?: string;
+}
+interface DataMappingActionConfig {
+    /** Field mappings. */
+    mappings: DataMapping[];
+    /** Whether to keep all source data and merge mappings on top. */
+    keepSourceData?: boolean;
+}
+declare class DataMappingAction {
+    private readonly logger;
+    execute(config: DataMappingActionConfig, data: Record<string, unknown>): Record<string, unknown>;
+    private doMapping;
+    private resolveSource;
+    private getNestedValue;
+}
+
+interface EventTriggerConfig {
+    topic: string;
+}
+declare class EventTrigger {
+    private readonly logger;
+    private subscription?;
+    start(config: EventTriggerConfig, eventBus: TopicEventBus, handler: (payload: unknown) => void | Promise<void>): void;
+    stop(): void;
+    isRunning(): boolean;
+}
+
+interface TimerTriggerConfig {
+    cron: string;
+    timezone?: string;
+    /** 执行次数限制（0 = 无限） */
+    maxTimes?: number;
+}
+/**
+ * 定时触发器 — 对齐 jetlinks TimerTaskExecutor
+ * 增加执行次数追踪和验证
+ */
+declare class TimerTrigger {
+    private readonly logger;
+    private intervalId?;
+    private running;
+    private executionCount;
+    private lastExecutionTime?;
+    private config?;
+    start(config: TimerTriggerConfig, handler: () => void | Promise<void>): void;
+    stop(): void;
+    isRunning(): boolean;
+    /** 获取已执行次数 — 对齐 jetlinks TimerTaskExecutor 中的 times 传递 */
+    getExecutionCount(): number;
+    /** 获取最后执行时间 */
+    getLastExecutionTime(): Date | undefined;
+    /**
+     * 重新加载配置 — 对齐 jetlinks TimerTaskExecutor.reload()
+     */
+    reload(config: TimerTriggerConfig, handler: () => void | Promise<void>): void;
+    /**
+     * 验证配置 — 对齐 jetlinks TimerTaskExecutor.validate()
+     */
+    validate(config?: TimerTriggerConfig): void;
+    private parseCronToInterval;
+}
+
+/**
+ * RuleData wraps data flowing through the rule engine graph,
+ * carrying context headers alongside the payload — mirrors
+ * jetlinks RuleData / RuleDataHelper.
+ */
+interface RuleDataHeaders {
+    /** Originating rule instance id */
+    ruleId?: string;
+    /** Node that produced this data */
+    nodeId?: string;
+    /** Arbitrary context passed between nodes */
+    [key: string]: unknown;
+}
+declare class RuleData {
+    readonly id: string;
+    private _data;
+    private readonly _headers;
+    private readonly _contextMap;
+    constructor(data: unknown, headers?: RuleDataHeaders);
+    static of(data: unknown): RuleData;
+    /** Create a new RuleData sharing headers but replacing the payload. */
+    newData(data: unknown): RuleData;
+    getData(): unknown;
+    setData(data: unknown): void;
+    getHeader(key: string): unknown;
+    setHeader(key: string, value: unknown): void;
+    getHeaders(): Readonly<RuleDataHeaders>;
+    /** Record current data into headers under `key` (used for serial chaining). */
+    recordToHeader(key: string): void;
+    /** Get a context map entry. */
+    getContextEntry(key: string): unknown;
+    /** Set a context map entry — mirrors jetlinks RuleDataHelper.setContextData(). */
+    setContextEntry(key: string, value: unknown): void;
+    /** Retrieve the full context map (plain object view of data).
+     *  Merges data + headers + contextMap — aligned with jetlinks RuleDataHelper.toContextMap(). */
+    toContextMap(): Record<string, unknown>;
+    private static _counter;
+    private static generateId;
+}
+
+/**
+ * Mirrors jetlinks ExecutionContext — provides input/output channels,
+ * logging, error handling, and event firing for a TaskExecutor.
+ */
+interface ExecutionContext {
+    /** The logger scoped to this execution context. */
+    getLogger(): Logger;
+    /** Create a new RuleData wrapping the given payload, inheriting context. */
+    newRuleData(data: unknown): RuleData;
+    /** Input channel — receives data from upstream nodes. */
+    getInput(): InputChannel;
+    /** Output channel — sends data to downstream nodes. */
+    getOutput(): OutputChannel;
+    /** Fire a named event (e.g. 'result', 'error', 'complete'). */
+    fireEvent(event: string, data: RuleData): Promise<void>;
+    /** Report an error that occurred during execution. */
+    onError(error: Error, data: RuleData | null): Promise<void>;
+    /** Job / node configuration. */
+    getJob(): JobContext;
+}
+interface InputChannel {
+    /** Subscribe to incoming data. Returns an unsubscribe function. */
+    accept(handler: (data: RuleData) => void | Promise<void>): () => void;
+}
+interface OutputChannel {
+    /** Write data to downstream nodes. */
+    write(data: RuleData): Promise<void>;
+}
+interface JobContext {
+    /** The executor type identifier. */
+    getExecutor(): string;
+    /** Node-level configuration map. */
+    getConfiguration(): Record<string, unknown>;
+    /** Get a specific rule-level configuration value. */
+    getRuleConfiguration(key: string): unknown | undefined;
+    /** The node ID this job belongs to. */
+    getNodeId(): string;
+    /** The rule instance ID. */
+    getRuleId(): string;
+}
+
+/**
+ * Rule engine constants — mirrors jetlinks RuleConstants.
+ */
+declare const RuleConstants: {
+    readonly Event: {
+        readonly result: "result";
+        readonly error: "error";
+        readonly complete: "complete";
+    };
+};
+/**
+ * Extended execution context for task executors — adds rule-engine specific
+ * methods like data creation and event firing on top of the base ExecutionContext.
+ *
+ * Mirrors the combined capabilities of jetlinks ExecutionContext + RuleDataHelper.
+ */
+interface TaskExecutionContext {
+    /** The logger scoped to this execution context. */
+    getLogger(): Logger;
+    /** Node-level configuration map. */
+    getConfiguration(): Record<string, unknown>;
+    /** Create a new RuleData from an existing one with new payload data. */
+    newRuleDataFrom(source: RuleData, data: unknown): RuleData;
+    /** Fire a named event (e.g. 'result', 'error', 'complete'). */
+    fireEvent(event: string, data: RuleData): Promise<void>;
+    /** Report an error that occurred during execution. */
+    onError(error: Error, data: RuleData | null): Promise<void>;
+}
+/**
+ * TaskExecutor lifecycle — mirrors jetlinks AbstractTaskExecutor.
+ *
+ * Lifecycle: create -> init -> start -> (pause / reload / shutdown)
+ */
+declare enum TaskState {
+    IDLE = "idle",
+    RUNNING = "running",
+    PAUSED = "paused",
+    SHUTDOWN = "shutdown"
+}
+interface TaskExecutor {
+    /** Human-readable name of this executor instance. */
+    getName(): string;
+    /** Current lifecycle state. */
+    getState(): TaskState;
+    /** Initialise from configuration (called once after creation). */
+    init(): Promise<void> | void;
+    /** Start (or resume) execution. */
+    start(): Promise<void> | void;
+    /** Pause execution without releasing resources. */
+    pause(): Promise<void> | void;
+    /** Reload configuration and restart. */
+    reload(): Promise<void> | void;
+    /** Permanently shut down and release all resources. */
+    shutdown(): Promise<void> | void;
+    /** Validate configuration before starting. Throws on invalid config. */
+    validate(): void;
+}
+/**
+ * Factory that creates TaskExecutor instances for a given executor type.
+ * Mirrors jetlinks TaskExecutorProvider.
+ */
+interface TaskExecutorProvider {
+    /** The executor identifier (e.g. 'timer', 'delay', 'script'). */
+    getExecutor(): string;
+    /** Create a new TaskExecutor for the given execution context. */
+    createTask(context: ExecutionContext): Promise<TaskExecutor>;
+}
+/**
+ * Base class providing common lifecycle management for TaskExecutors.
+ */
+declare abstract class AbstractTaskExecutor implements TaskExecutor {
+    protected readonly context: ExecutionContext;
+    protected state: TaskState;
+    protected disposables: Array<() => void>;
+    constructor(context: ExecutionContext);
+    abstract getName(): string;
+    getState(): TaskState;
+    init(): Promise<void>;
+    start(): Promise<void>;
+    protected abstract doStart(): Promise<(() => void) | void> | (() => void) | void;
+    pause(): Promise<void>;
+    reload(): Promise<void>;
+    shutdown(): Promise<void>;
+    validate(): void;
+    /** Register a cleanup function to be called on shutdown. */
+    protected addDisposable(fn: () => void): void;
+}
+
+/**
+ * 任务执行器注册表 — 对齐 jetlinks @Component 自动注册的 TaskExecutorProvider 集合
+ * 在 NestJS 中通过 DI 手动注册 provider
+ */
+declare class TaskExecutorRegistry {
+    private readonly logger;
+    private readonly providers;
+    /**
+     * 注册任务执行器提供者
+     */
+    register(provider: TaskExecutorProvider): void;
+    /**
+     * 注销任务执行器提供者
+     */
+    unregister(executorType: string): void;
+    /**
+     * 根据执行器类型创建任务
+     */
+    createTask(executorType: string, context: ExecutionContext): Promise<TaskExecutor>;
+    /**
+     * 获取所有已注册的执行器类型
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * 检查是否存在指定类型的执行器
+     */
+    hasProvider(executorType: string): boolean;
+}
+
+/**
+ * Graph-based rule model — mirrors jetlinks RuleModel / RuleNodeModel / RuleLink.
+ *
+ * A RuleModel is a directed acyclic graph (DAG) of RuleNodeModels connected
+ * by RuleLinks. Each node has an executor type and configuration; links
+ * may carry conditions that gate data flow.
+ */
+interface ConditionSpec {
+    type: string;
+    configuration: Record<string, unknown>;
+}
+/**
+ * A directed edge between two nodes in the rule graph.
+ */
+interface RuleLink {
+    /** Unique link id. */
+    id: string;
+    /** Source node id. */
+    source: string;
+    /** Target node id. */
+    target: string;
+    /** Link type (e.g. 'output', 'error'). */
+    type: string;
+    /** Optional condition that must evaluate to true for data to flow. */
+    condition?: ConditionSpec;
+}
+/**
+ * A single node in the rule graph.
+ */
+interface RuleNodeModel {
+    /** Unique node id within the model. */
+    id: string;
+    /** Human-readable node name. */
+    name: string;
+    /** Executor type identifier (e.g. 'timer', 'delay', 'script', 'notify'). */
+    executor: string;
+    /** Executor-specific configuration. */
+    configuration: Record<string, unknown>;
+    /** Input link descriptors (populated by the engine). */
+    inputs?: RuleLink[];
+    /** Output link descriptors (populated by the engine). */
+    outputs?: RuleLink[];
+}
+type ExecutionMode = 'parallel' | 'serial';
+/**
+ * The complete rule model — a DAG of nodes and links.
+ */
+declare class RuleModel {
+    id: string;
+    name: string;
+    type: string;
+    /** All nodes in the graph. */
+    readonly nodes: RuleNodeModel[];
+    /** All links in the graph. */
+    readonly links: RuleLink[];
+    /** Default execution mode for action groups. */
+    executionMode: ExecutionMode;
+    constructor(id: string, name: string, type?: string);
+    /** Add a node to the model. */
+    addNode(node: RuleNodeModel): void;
+    /** Create a link between two nodes and add it to the model. Returns the link. */
+    link(source: RuleNodeModel, target: RuleNodeModel, type?: string): RuleLink;
+    /** Find a node by id. */
+    getNode(id: string): RuleNodeModel | undefined;
+    /** Remove a node and all its connected links — mirrors jetlinks RuleModel management. */
+    removeNode(nodeId: string): boolean;
+    /** Remove a specific link by id. */
+    removeLink(linkId: string): boolean;
+    /** Get all downstream node ids from a given node. */
+    getDownstream(nodeId: string): string[];
+    /** Get all upstream node ids from a given node. */
+    getUpstream(nodeId: string): string[];
+    /** Get topologically sorted node ids (for serial execution ordering). */
+    topologicalSort(): string[];
+    /** Validate the model (no cycles, all link targets exist). */
+    validate(): string[];
+}
+
+/**
+ * 规则版本管理。
+ */
+interface RuleVersion {
+    ruleId: string;
+    version: number;
+    definition: RuleDefinition;
+    createdAt: number;
+    createdBy?: string;
+    changeLog?: string;
+    /** 是否为当前活跃版本 */
+    active: boolean;
+}
+declare class RuleVersionManager {
+    private readonly logger;
+    private readonly versions;
+    /** 保存规则新版本 */
+    saveVersion(ruleId: string, definition: RuleDefinition, options?: {
+        createdBy?: string;
+        changeLog?: string;
+    }): RuleVersion;
+    /** 获取规则的所有历史版本 */
+    getVersions(ruleId: string): RuleVersion[];
+    /** 获取规则的当前活跃版本 */
+    getActiveVersion(ruleId: string): RuleVersion | undefined;
+    /** 获取指定版本 */
+    getVersion(ruleId: string, version: number): RuleVersion | undefined;
+    /** 回滚到指定版本 */
+    rollback(ruleId: string, targetVersion: number): RuleVersion | undefined;
+    /** 比较两个版本的差异 */
+    diff(ruleId: string, v1: number, v2: number): {
+        added: string[];
+        removed: string[];
+        modified: string[];
+    } | undefined;
+}
+/**
+ * 规则测试框架 — 验证规则定义的正确性。
+ */
+interface RuleTestCase {
+    name: string;
+    /** 输入数据 */
+    input: Record<string, unknown>;
+    /** 期望的输出/结果 */
+    expected: {
+        /** 期望触发的 action 名称列表 */
+        triggeredActions?: string[];
+        /** 期望的条件评估结果 */
+        conditionResult?: boolean;
+        /** 期望的输出数据 */
+        output?: Record<string, unknown>;
+    };
+}
+interface RuleTestResult {
+    testCase: string;
+    passed: boolean;
+    actual: Record<string, unknown>;
+    expected: Record<string, unknown>;
+    error?: string;
+    duration: number;
+}
+declare class RuleTestRunner {
+    private readonly logger;
+    /** 运行单个测试用例 */
+    runTest(definition: RuleDefinition, testCase: RuleTestCase, executor: {
+        execute: (input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    }): Promise<RuleTestResult>;
+    /** 运行多个测试用例 */
+    runTests(definition: RuleDefinition, testCases: RuleTestCase[], executor: {
+        execute: (input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    }): Promise<{
+        results: RuleTestResult[];
+        passed: number;
+        failed: number;
+        total: number;
+    }>;
+    private compareResults;
+}
+
+declare class ZuckerRuleEngineModule {
+}
+
+export { AbstractTaskExecutor, type Branch, type BranchAction, type BranchActionGroup, type BranchCondition, type BranchEvaluationResult, BranchEvaluator, type ConditionSpec, type DataMapping, DataMappingAction, type DataMappingActionConfig, DelayAction, type DelayActionConfig, type DelayPauseType, type DelayTimeUnit, EventTrigger, type EventTriggerConfig, type ExecutionContext, type ExecutionMode, type ExpressionCondition, ExpressionEvaluator, HttpAction, type HttpActionConfig, type InputChannel, type JobContext, NotifyAction, type NotifyActionConfig, type NotifyEvent, type NotifySender, type OutputChannel, type RuleAction, RuleActionType, type RuleCondition, RuleConditionType, RuleConstants, RuleData, type RuleDataHeaders, type RuleDefinition, RuleEngineService, RuleInstanceState, type RuleLink, RuleModel, type RuleNodeModel, type RuleTestCase, type RuleTestResult, RuleTestRunner, type RuleTrigger, RuleTriggerType, type RuleVersion, RuleVersionManager, ScriptAction, type ScriptActionConfig, type ShakeLimitConfig, type ShakeLimitResult, type TaskExecutionContext, type TaskExecutor, type TaskExecutorProvider, TaskExecutorRegistry, TaskState, type Term, type TermCondition, TermsEvaluator, TimerTrigger, type TimerTriggerConfig, ZuckerRuleEngineModule, createShakeLimit };