@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/rules/engine.js

@@ -0,0 +1,757 @@
+/**
+ * Rules engine runtime — orchestrates trigger subscription, matcher
+ * pipeline, throttle gate, and action executor.
+ *
+ * v0.2 PoC scope:
+ *   - Loads an `automation` block from a policy file.
+ *   - Subscribes to a single MQTT client; routes every shadow message
+ *     through `matchesMqttTrigger` → `evaluateConditions` → throttle →
+ *     `executeRuleAction`.
+ *   - Cron + webhook triggers are **recognised but not wired** — they
+ *     surface in the static lint as `unsupported` so users know the
+ *     feature is pending (E1/E2 fill it in without a schema change).
+ *   - Exposes `start()`, `stop()`, `getStats()` for the rules run
+ *     subcommand.
+ *
+ * Not responsible for: loading the policy file, validating it, talking
+ * to the SwitchBot REST API (that's `executeCommand`), or writing
+ * audit lines (that's each module's local responsibility).
+ */
+import { randomUUID } from 'node:crypto';
+import { fetchDeviceStatus } from '../lib/devices.js';
+import { isDestructiveCommand } from './destructive.js';
+import { classifyMqttPayload, evaluateConditions, matchesMqttTrigger, } from './matcher.js';
+import { ThrottleGate, parseMaxPerMs } from './throttle.js';
+import { executeRuleAction, parseRuleCommand } from './action.js';
+import { CronScheduler } from './cron-scheduler.js';
+import { WebhookListener, DEFAULT_WEBHOOK_PORT } from './webhook-listener.js';
+import { isCronTrigger, isMqttTrigger, isWebhookTrigger, } from './types.js';
+import { Cron } from 'croner';
+import { writeAudit } from '../utils/audit.js';
+export function lintRules(automation) {
+    const rules = automation?.rules ?? [];
+    const entries = [];
+    let unsupportedCount = 0;
+    const seenNames = new Set();
+    for (const r of rules) {
+        const issues = [];
+        if (seenNames.has(r.name)) {
+            issues.push({ rule: r.name, severity: 'error', code: 'duplicate-name', message: `Duplicate rule name "${r.name}".` });
+        }
+        seenNames.add(r.name);
+        // Trigger support — cron + webhook are both wired in E1/E2. The
+        // only remaining unsupported source would be an unknown string.
+        if (r.when.source !== 'mqtt' && r.when.source !== 'cron' && r.when.source !== 'webhook') {
+            issues.push({
+                rule: r.name,
+                severity: 'warning',
+                code: 'trigger-unsupported',
+                message: `Trigger source "${r.when.source}" is not recognised by this build.`,
+            });
+            unsupportedCount++;
+        }
+        // Cron expression validity (cron trigger is now active in E1).
+        if (r.when.source === 'cron') {
+            try {
+                // eslint-disable-next-line no-new
+                new Cron(r.when.schedule, { paused: true });
+            }
+            catch (err) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-cron',
+                    message: `cron schedule "${r.when.schedule}" is not parseable: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        // Webhook path sanity — must start with "/" and carry at least one
+        // non-slash character. Keeps common typos out of production.
+        if (r.when.source === 'webhook') {
+            const p = r.when.path;
+            if (typeof p !== 'string' || !p.startsWith('/') || p.length < 2) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-webhook-path',
+                    message: `webhook path "${String(p)}" must start with "/" and contain at least one character.`,
+                });
+            }
+        }
+        // Destructive guard
+        for (let i = 0; i < r.then.length; i++) {
+            if (isDestructiveCommand(r.then[i].command)) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'destructive-action',
+                    message: `then[${i}] uses a destructive verb — the engine will refuse to run this rule.`,
+                });
+            }
+        }
+        // Throttle expression
+        if (r.throttle) {
+            try {
+                parseMaxPerMs(r.throttle.max_per);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-throttle',
+                    message: `throttle.max_per "${r.throttle.max_per}" is not a valid duration.`,
+                });
+            }
+            if (r.throttle.dedupe_window) {
+                try {
+                    parseMaxPerMs(r.throttle.dedupe_window);
+                }
+                catch {
+                    issues.push({
+                        rule: r.name,
+                        severity: 'error',
+                        code: 'invalid-dedupe-window',
+                        message: `throttle.dedupe_window "${r.throttle.dedupe_window}" is not a valid duration.`,
+                    });
+                }
+            }
+        }
+        // cooldown field validation
+        if (r.cooldown) {
+            try {
+                parseMaxPerMs(r.cooldown);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-cooldown',
+                    message: `cooldown "${r.cooldown}" is not a valid duration (expected e.g. "10m", "1h").`,
+                });
+            }
+            if (r.throttle?.max_per) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'warning',
+                    code: 'cooldown-throttle-overlap',
+                    message: `Both "cooldown" and "throttle.max_per" are set. "cooldown" takes precedence.`,
+                });
+            }
+        }
+        // requires_stable_for field validation
+        if (r.requires_stable_for) {
+            try {
+                parseMaxPerMs(r.requires_stable_for);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-requires-stable-for',
+                    message: `requires_stable_for "${r.requires_stable_for}" is not a valid duration.`,
+                });
+            }
+        }
+        // hysteresis field validation
+        if (r.hysteresis) {
+            try {
+                parseMaxPerMs(r.hysteresis);
+            }
+            catch {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-hysteresis',
+                    message: `hysteresis "${r.hysteresis}" is not a valid duration (expected e.g. "10m", "1h").`,
+                });
+            }
+            if (r.requires_stable_for) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'warning',
+                    code: 'hysteresis-requires-stable-overlap',
+                    message: `Both "hysteresis" and "requires_stable_for" are set. "hysteresis" takes precedence.`,
+                });
+            }
+        }
+        // maxFiringsPerHour field validation
+        if (r.maxFiringsPerHour !== undefined) {
+            if (!Number.isInteger(r.maxFiringsPerHour) || r.maxFiringsPerHour < 1) {
+                issues.push({
+                    rule: r.name,
+                    severity: 'error',
+                    code: 'invalid-maxFiringsPerHour',
+                    message: `maxFiringsPerHour must be a positive integer (got ${r.maxFiringsPerHour}).`,
+                });
+            }
+        }
+        const enabled = r.enabled !== false;
+        const hasError = issues.some((i) => i.severity === 'error');
+        const hasUnsupported = issues.some((i) => i.code === 'trigger-unsupported');
+        const status = !enabled
+            ? 'disabled'
+            : hasError
+                ? 'error'
+                : hasUnsupported
+                    ? 'unsupported'
+                    : 'ok';
+        entries.push({ name: r.name, enabled, status, issues });
+    }
+    return {
+        rules: entries,
+        valid: entries.every((e) => e.status !== 'error'),
+        unsupportedCount,
+    };
+}
+export class RulesEngine {
+    opts;
+    rules;
+    aliases;
+    throttle = new ThrottleGate();
+    /** hysteresis / requires_stable_for: tracks when each (rule::device) trigger was first seen. */
+    hysteresisFirstSeen = new Map();
+    unsubscribeMessage = null;
+    unsubscribeState = null;
+    cronScheduler = null;
+    webhookListener = null;
+    started = false;
+    stopped = false;
+    /**
+     * Sequential dispatch queue. Two MQTT messages arriving in the same
+     * tick would otherwise race inside the throttle check — each sees an
+     * empty lastFireAt map because neither has recorded yet. Serialising
+     * keeps the semantics of `max_per` honest.
+     */
+    pendingChain = Promise.resolve();
+    stats = {
+        started: false,
+        rulesLoaded: 0,
+        rulesActive: 0,
+        eventsProcessed: 0,
+        fires: 0,
+        dryFires: 0,
+        throttled: 0,
+        conditionsFailed: 0,
+    };
+    constructor(opts) {
+        this.opts = opts;
+        this.rules = (opts.automation?.rules ?? []).filter((r) => r.enabled !== false);
+        this.aliases = opts.aliases ?? {};
+        this.stats.rulesLoaded = opts.automation?.rules?.length ?? 0;
+        this.stats.rulesActive = this.rules.length;
+    }
+    getStats() {
+        return { ...this.stats, started: this.started && !this.stopped };
+    }
+    getRules() {
+        return this.rules;
+    }
+    /**
+     * Subscribes to MQTT and begins the pipeline. Throws if the policy
+     * block is missing `enabled: true` or if lint finds errors (e.g.
+     * destructive command in a rule action).
+     */
+    async start() {
+        if (this.opts.automation?.enabled !== true) {
+            throw new Error('automation.enabled is not true — engine start refused.');
+        }
+        const lint = lintRules(this.opts.automation);
+        if (!lint.valid) {
+            const errors = lint.rules.flatMap((r) => r.issues.filter((i) => i.severity === 'error'));
+            throw new Error(`Rule lint failed: ${errors.map((e) => `${e.rule}:${e.code}`).join(', ')}`);
+        }
+        if (this.rules.some((r) => isMqttTrigger(r.when))) {
+            const topic = this.opts.mqttCredential.topics.status;
+            this.opts.mqttClient.subscribe(topic);
+            this.unsubscribeMessage = this.opts.mqttClient.onMessage((_topic, payload) => {
+                this.enqueue(() => this.onMqttMessage(payload));
+            });
+        }
+        // Cron triggers. We start the scheduler only when at least one cron
+        // rule is active — no need to stand up timers otherwise.
+        const cronRules = this.rules.filter((r) => isCronTrigger(r.when));
+        if (cronRules.length > 0) {
+            this.cronScheduler = new CronScheduler({
+                dispatch: (rule, event) => this.enqueue(() => this.onCronFire(rule, event)),
+            });
+            for (const r of cronRules)
+                this.cronScheduler.register(r);
+            this.cronScheduler.start();
+        }
+        // Webhook triggers. Only bind the HTTP port when at least one rule
+        // needs it — standing up the listener unconditionally would force
+        // every user into an open port they didn't ask for.
+        const webhookRules = this.rules.filter((r) => isWebhookTrigger(r.when));
+        if (webhookRules.length > 0) {
+            if (!this.opts.webhookToken) {
+                throw new Error('webhook rules require a bearer token — pass RulesEngineOptions.webhookToken.');
+            }
+            this.webhookListener = new WebhookListener({
+                rules: webhookRules,
+                bearerToken: this.opts.webhookToken,
+                host: this.opts.webhookHost,
+                port: this.opts.webhookPort ?? DEFAULT_WEBHOOK_PORT,
+                dispatch: (rule, event) => this.enqueue(() => this.onWebhookFire(rule, event)),
+            });
+            await this.webhookListener.start();
+        }
+        this.unsubscribeState = this.opts.mqttClient.onStateChange((state) => {
+            if (state === 'failed' && !this.stopped) {
+                // Propagate to caller via stats; the rules run command decides
+                // whether to exit. No internal restart — we rely on supervisors.
+                this.started = false;
+            }
+        });
+        this.started = true;
+        this.stats.started = true;
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.started = false;
+        this.unsubscribeMessage?.();
+        this.unsubscribeState?.();
+        this.unsubscribeMessage = null;
+        this.unsubscribeState = null;
+        if (this.cronScheduler) {
+            this.cronScheduler.stop();
+            this.cronScheduler = null;
+        }
+        if (this.webhookListener) {
+            await this.webhookListener.stop();
+            this.webhookListener = null;
+        }
+    }
+    /**
+     * Hot-reload the running engine with a fresh automation block and
+     * alias map — typically triggered by SIGHUP or by the `rules reload`
+     * subcommand writing the reload sentinel file.
+     *
+     * Semantics:
+     *   - Rejects (and keeps the old ruleset) when the new automation is
+     *     disabled or fails lint. The engine never silently degrades.
+     *   - Diffs cron registrations by `rule.name` + `schedule`: unchanged
+     *     entries keep their armed timer, changed/removed entries are
+     *     unregistered, new entries are registered and armed.
+     *   - Hands the fresh webhook rule list to the live listener (keeps
+     *     the bound port / open connections). If the reload removes every
+     *     webhook rule the listener is torn down; if it adds the first
+     *     webhook rule we refuse — spinning up a new listener mid-run
+     *     would silently change the security surface.
+     *   - `ThrottleGate` state is retained for surviving rule names and
+     *     dropped for removed ones. A rule that was throttled before the
+     *     reload stays throttled after it (same name = same window), but
+     *     a renamed rule resets.
+     */
+    async reload(nextAutomation, nextAliases = {}) {
+        if (!this.started || this.stopped) {
+            return { changed: false, errors: ['engine not running'], warnings: [] };
+        }
+        if (nextAutomation?.enabled !== true) {
+            return {
+                changed: false,
+                errors: ['automation.enabled is not true in the new policy — refusing to reload'],
+                warnings: [],
+            };
+        }
+        const lint = lintRules(nextAutomation);
+        if (!lint.valid) {
+            const errs = lint.rules.flatMap((r) => r.issues.filter((i) => i.severity === 'error').map((i) => `${i.rule}:${i.code}`));
+            return { changed: false, errors: errs, warnings: [] };
+        }
+        const warnings = [];
+        const nextActive = (nextAutomation.rules ?? []).filter((r) => r.enabled !== false);
+        const nextByName = new Map(nextActive.map((r) => [r.name, r]));
+        const oldByName = new Map(this.rules.map((r) => [r.name, r]));
+        // Cron diff
+        if (this.cronScheduler) {
+            for (const [name, oldRule] of oldByName) {
+                if (!isCronTrigger(oldRule.when))
+                    continue;
+                const next = nextByName.get(name);
+                const same = next &&
+                    isCronTrigger(next.when) &&
+                    next.when.schedule === oldRule.when.schedule;
+                if (!same)
+                    this.cronScheduler.unregister(name);
+            }
+            for (const [name, newRule] of nextByName) {
+                if (!isCronTrigger(newRule.when))
+                    continue;
+                if (this.cronScheduler.hasRegistered(name))
+                    continue;
+                this.cronScheduler.register(newRule);
+            }
+        }
+        else {
+            // No scheduler yet but now we have cron rules — stand one up.
+            const cronRules = nextActive.filter((r) => isCronTrigger(r.when));
+            if (cronRules.length > 0) {
+                this.cronScheduler = new CronScheduler({
+                    dispatch: (rule, event) => this.enqueue(() => this.onCronFire(rule, event)),
+                });
+                for (const r of cronRules)
+                    this.cronScheduler.register(r);
+                this.cronScheduler.start();
+            }
+        }
+        // Webhook diff — keep the listener alive if possible.
+        const newWebhookRules = nextActive.filter((r) => isWebhookTrigger(r.when));
+        if (this.webhookListener) {
+            if (newWebhookRules.length === 0) {
+                await this.webhookListener.stop();
+                this.webhookListener = null;
+            }
+            else {
+                this.webhookListener.updateRules(newWebhookRules);
+            }
+        }
+        else if (newWebhookRules.length > 0) {
+            warnings.push('webhook rules added via reload — full restart required for the listener to bind. Skipping activation.');
+        }
+        // Swap ruleset + aliases atomically relative to the next event.
+        this.rules = nextActive;
+        this.aliases = nextAliases;
+        this.stats.rulesLoaded = nextAutomation.rules?.length ?? 0;
+        this.stats.rulesActive = nextActive.length;
+        this.throttle.retainOnly(new Set(nextByName.keys()));
+        return { changed: true, errors: [], warnings };
+    }
+    /**
+     * Expose the MQTT pipeline for direct invocation from tests — feeds a
+     * synthetic payload through the same matcher/throttle/action chain.
+     */
+    async ingestMqttForTest(payload) {
+        await this.enqueue(() => this.onMqttMessage(payload, { preParsed: true }));
+    }
+    /**
+     * Dispatch a pre-built EngineEvent through all matching MQTT rules.
+     * Used by tests that need full control over the event timestamp (e.g.
+     * hysteresis tests that advance time manually).
+     */
+    async ingestEventForTest(event) {
+        for (const rule of this.rules) {
+            if (!isMqttTrigger(rule.when))
+                continue;
+            const resolvedFilter = rule.when.device
+                ? this.aliases[rule.when.device] ?? rule.when.device
+                : undefined;
+            if (!matchesMqttTrigger(rule.when, event, resolvedFilter))
+                continue;
+            this.stats.eventsProcessed++;
+            await this.enqueue(() => this.dispatchRule(rule, event));
+        }
+    }
+    /**
+     * Fire a cron rule directly without needing the scheduler/timers.
+     * Used by tests that want to exercise the dispatch pipeline without
+     * depending on fake timers or croner's internals.
+     */
+    async ingestCronForTest(rule, when = new Date()) {
+        if (!isCronTrigger(rule.when)) {
+            throw new Error(`ingestCronForTest: rule "${rule.name}" is not a cron trigger`);
+        }
+        const event = {
+            source: 'cron',
+            event: rule.when.schedule,
+            t: when,
+            payload: { schedule: rule.when.schedule },
+        };
+        await this.enqueue(() => this.onCronFire(rule, event));
+    }
+    /**
+     * Fire a webhook rule directly without standing up the HTTP listener.
+     */
+    async ingestWebhookForTest(rule, body = '', when = new Date()) {
+        if (!isWebhookTrigger(rule.when)) {
+            throw new Error(`ingestWebhookForTest: rule "${rule.name}" is not a webhook trigger`);
+        }
+        const event = {
+            source: 'webhook',
+            event: rule.when.path,
+            t: when,
+            payload: { path: rule.when.path, body },
+        };
+        await this.enqueue(() => this.onWebhookFire(rule, event));
+    }
+    /** Returns the bound webhook port when the listener is active. */
+    getWebhookPort() {
+        return this.webhookListener?.getPort() ?? null;
+    }
+    /** Read-only peek at cron schedule state — for `rules list` extras. */
+    getCronSchedule(ruleName) {
+        return this.cronScheduler?.getScheduledFor(ruleName) ?? null;
+    }
+    /** Test helper — resolves after all queued dispatches complete. */
+    async drainForTest() {
+        await this.pendingChain;
+    }
+    /**
+     * Append a task to the dispatch queue; callers get back a promise that
+     * resolves when their task finishes (errors are swallowed — we never
+     * want the queue itself to die because one rule threw). Returning a
+     * promise lets awaited callsites (ingestMqttForTest) observe completion.
+     */
+    enqueue(task) {
+        const next = this.pendingChain.then(() => task().catch(() => undefined));
+        this.pendingChain = next;
+        return next;
+    }
+    async onMqttMessage(payload, opts = {}) {
+        if (this.stopped || !this.started)
+            return;
+        let parsed;
+        if (opts.preParsed) {
+            parsed = payload;
+        }
+        else {
+            try {
+                parsed = JSON.parse(payload.toString('utf-8'));
+            }
+            catch {
+                return;
+            }
+        }
+        this.stats.eventsProcessed++;
+        const classified = classifyMqttPayload(parsed);
+        const now = new Date();
+        const event = {
+            source: 'mqtt',
+            event: classified.event,
+            deviceId: classified.deviceId,
+            t: now,
+            payload: parsed,
+        };
+        for (const rule of this.rules) {
+            if (!isMqttTrigger(rule.when))
+                continue;
+            const resolvedFilter = rule.when.device
+                ? this.aliases[rule.when.device] ?? rule.when.device
+                : undefined;
+            if (!matchesMqttTrigger(rule.when, event, resolvedFilter))
+                continue;
+            await this.dispatchRule(rule, event);
+            if (this.opts.maxFirings !== undefined && this.stats.eventsProcessed >= 0 && this.firesTotal() >= this.opts.maxFirings) {
+                await this.stop();
+                return;
+            }
+        }
+    }
+    async onCronFire(rule, event) {
+        if (this.stopped || !this.started)
+            return;
+        this.stats.eventsProcessed++;
+        await this.dispatchRule(rule, event);
+        if (this.opts.maxFirings !== undefined && this.firesTotal() >= this.opts.maxFirings) {
+            await this.stop();
+        }
+    }
+    async onWebhookFire(rule, event) {
+        if (this.stopped || !this.started)
+            return;
+        this.stats.eventsProcessed++;
+        await this.dispatchRule(rule, event);
+        if (this.opts.maxFirings !== undefined && this.firesTotal() >= this.opts.maxFirings) {
+            await this.stop();
+        }
+    }
+    firesTotal() {
+        return this.stats.fires + this.stats.dryFires;
+    }
+    async dispatchRule(rule, event) {
+        const fireId = randomUUID();
+        // Per-tick status cache: one pipeline run through dispatchRule, one
+        // cache. Multiple device_state conditions on the same deviceId share
+        // a single round trip; subsequent pipeline runs see fresh status.
+        const statusCache = new Map();
+        const baseFetcher = this.opts.statusFetcher ??
+            ((id) => fetchDeviceStatus(id, this.opts.httpClient));
+        const fetchStatus = (deviceId) => {
+            const existing = statusCache.get(deviceId);
+            if (existing)
+                return existing;
+            const p = baseFetcher(deviceId);
+            statusCache.set(deviceId, p);
+            return p;
+        };
+        const cond = await evaluateConditions(rule.conditions, event.t, {
+            aliases: this.aliases,
+            fetchStatus,
+        });
+        if (!cond.matched) {
+            // If conditions are not met, the trigger is no longer "continuously stable" —
+            // reset the hysteresis clock so intermittent satisfaction never accumulates.
+            const hasHysteresis = rule.hysteresis ?? rule.requires_stable_for;
+            if (hasHysteresis) {
+                const hysteresisKey = `${rule.name}::${event.deviceId ?? ''}`;
+                this.hysteresisFirstSeen.delete(hysteresisKey);
+            }
+            if (cond.unsupported.length > 0) {
+                writeAudit({
+                    t: event.t.toISOString(),
+                    kind: 'rule-fire',
+                    deviceId: event.deviceId ?? 'unknown',
+                    command: rule.then[0]?.command ?? '',
+                    parameter: null,
+                    commandType: 'command',
+                    dryRun: true,
+                    result: 'error',
+                    error: `condition-unsupported:${cond.unsupported.map((u) => u.keyword).join(',')}`,
+                    rule: {
+                        name: rule.name,
+                        triggerSource: rule.when.source,
+                        matchedDevice: event.deviceId,
+                        fireId,
+                        reason: cond.unsupported.map((u) => u.hint).join(' | '),
+                    },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'unsupported', deviceId: event.deviceId, reason: cond.unsupported.map((u) => u.keyword).join(',') });
+                return;
+            }
+            this.stats.conditionsFailed++;
+            this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'conditions-failed', deviceId: event.deviceId, reason: cond.failures.join('; ') });
+            return;
+        }
+        // cooldown takes precedence over throttle.max_per when both are set.
+        const effectiveMaxPerMs = rule.cooldown
+            ? parseMaxPerMs(rule.cooldown)
+            : rule.throttle ? parseMaxPerMs(rule.throttle.max_per) : null;
+        const dedupeWindowMs = rule.throttle?.dedupe_window ? parseMaxPerMs(rule.throttle.dedupe_window) : null;
+        const throttleKey = event.deviceId;
+        const check = this.throttle.check(rule.name, effectiveMaxPerMs, event.t.getTime(), throttleKey, dedupeWindowMs);
+        if (!check.allowed) {
+            this.stats.throttled++;
+            writeAudit({
+                t: event.t.toISOString(),
+                kind: 'rule-throttled',
+                deviceId: event.deviceId ?? 'unknown',
+                command: rule.then[0]?.command ?? '',
+                parameter: null,
+                commandType: 'command',
+                dryRun: true,
+                result: 'ok',
+                rule: {
+                    name: rule.name,
+                    triggerSource: rule.when.source,
+                    matchedDevice: event.deviceId,
+                    fireId,
+                    reason: check.nextAllowedAt
+                        ? `${check.dedupedBy ?? 'throttled'} — next allowed at ${new Date(check.nextAllowedAt).toISOString()}`
+                        : check.dedupedBy ?? 'throttled',
+                },
+            });
+            this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId });
+            return;
+        }
+        // hysteresis / requires_stable_for: require the trigger to have been continuously
+        // observed for the specified duration before firing.
+        const hysteresisMs = rule.hysteresis
+            ? parseMaxPerMs(rule.hysteresis)
+            : rule.requires_stable_for ? parseMaxPerMs(rule.requires_stable_for) : null;
+        if (hysteresisMs !== null) {
+            const hysteresisKey = `${rule.name}::${event.deviceId ?? ''}`;
+            const firstSeen = this.hysteresisFirstSeen.get(hysteresisKey);
+            const now = event.t.getTime();
+            if (firstSeen === undefined) {
+                this.hysteresisFirstSeen.set(hysteresisKey, now);
+                writeAudit({
+                    t: event.t.toISOString(), kind: 'rule-throttled',
+                    deviceId: event.deviceId ?? 'unknown', command: rule.then[0]?.command ?? '',
+                    parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                    rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `hysteresis — first observation, waiting ${hysteresisMs}ms for stability` },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'hysteresis-first-seen' });
+                return;
+            }
+            if (now - firstSeen < hysteresisMs) {
+                writeAudit({
+                    t: event.t.toISOString(), kind: 'rule-throttled',
+                    deviceId: event.deviceId ?? 'unknown', command: rule.then[0]?.command ?? '',
+                    parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                    rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `hysteresis — stable for ${now - firstSeen}ms of required ${hysteresisMs}ms` },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'hysteresis-not-stable' });
+                return;
+            }
+            // Stable long enough — clear so the next trigger starts fresh.
+            this.hysteresisFirstSeen.delete(hysteresisKey);
+        }
+        // maxFiringsPerHour: count-based rate cap over a rolling 1-hour window.
+        if (rule.maxFiringsPerHour !== undefined) {
+            const countCheck = this.throttle.checkMaxFirings(rule.name, rule.maxFiringsPerHour, 3_600_000, event.t.getTime(), event.deviceId);
+            if (!countCheck.allowed) {
+                this.stats.throttled++;
+                writeAudit({
+                    t: event.t.toISOString(), kind: 'rule-throttled',
+                    deviceId: event.deviceId ?? 'unknown', command: rule.then[0]?.command ?? '',
+                    parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                    rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `maxFiringsPerHour — ${countCheck.count}/${countCheck.max} in last hour` },
+                });
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'maxFiringsPerHour' });
+                return;
+            }
+        }
+        // suppressIfAlreadyDesired: skip if device's live state already matches the command outcome.
+        if (rule.suppressIfAlreadyDesired) {
+            const firstAction = rule.then[0];
+            const parsed = firstAction ? parseRuleCommand(firstAction.command) : null;
+            const verb = parsed?.verb ?? firstAction?.command;
+            if ((verb === 'turnOn' || verb === 'turnOff') && (firstAction?.device || event.deviceId)) {
+                const targetId = firstAction?.device ? (this.aliases[firstAction.device] ?? firstAction.device) : event.deviceId;
+                try {
+                    const deviceStatus = await fetchStatus(targetId);
+                    const powerState = deviceStatus['powerState'];
+                    if ((verb === 'turnOn' && powerState === 'on') || (verb === 'turnOff' && powerState === 'off')) {
+                        writeAudit({
+                            t: event.t.toISOString(), kind: 'rule-throttled',
+                            deviceId: targetId, command: verb ?? '',
+                            parameter: null, commandType: 'command', dryRun: true, result: 'ok',
+                            rule: { name: rule.name, triggerSource: rule.when.source, matchedDevice: event.deviceId, fireId, reason: `suppressIfAlreadyDesired — powerState already "${powerState}"` },
+                        });
+                        this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'throttled', deviceId: event.deviceId, reason: 'already-desired' });
+                        return;
+                    }
+                }
+                catch {
+                    // best-effort — if status fetch fails, proceed with the action
+                }
+            }
+        }
+        let fired = false;
+        let allDry = true;
+        for (const action of rule.then) {
+            const result = await executeRuleAction(action, {
+                rule,
+                fireId,
+                aliases: this.aliases,
+                httpClient: this.opts.httpClient,
+                globalDryRun: this.opts.globalDryRun,
+                skipApiCall: this.opts.skipApiCall,
+            });
+            if (result.blocked) {
+                this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'blocked', deviceId: result.deviceId, reason: result.error });
+                if ((action.on_error ?? 'continue') === 'stop')
+                    break;
+                continue;
+            }
+            if (!result.dryRun)
+                allDry = false;
+            if (result.ok)
+                fired = true;
+            if (!result.ok && (action.on_error ?? 'continue') === 'stop')
+                break;
+        }
+        if (fired) {
+            if (allDry)
+                this.stats.dryFires++;
+            else
+                this.stats.fires++;
+            this.throttle.record(rule.name, event.t.getTime(), throttleKey);
+            if (rule.maxFiringsPerHour !== undefined) {
+                this.throttle.recordFire(rule.name, event.t.getTime(), throttleKey);
+            }
+            this.opts.onFire?.({ ruleName: rule.name, fireId, status: allDry ? 'dry' : 'fired', deviceId: event.deviceId });
+        }
+    }
+}