@switchbot/openapi-cli 3.0.0 → 3.1.0

package/dist/policy/schema/v0.2.json

@@ -130,10 +130,39 @@
               "type": "string",
               "pattern": "^\\d+[smh]$",
               "description": "Minimum spacing between fires, e.g. \"10m\". Later triggers inside the window are suppressed and audited."
+            },
+            "dedupe_window": {
+              "type": "string",
+              "pattern": "^\\d+[smh]$",
+              "description": "Deduplicate identical events arriving within this window after the last fire. Complements max_per: use when rapid sensor bursts should collapse into one action."
             }
           },
           "required": ["max_per"]
         },
+        "cooldown": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Shorthand cooldown — minimum pause after a rule fires before it can fire again. Equivalent to throttle.max_per but at rule level. Takes precedence over throttle.max_per when both are set."
+        },
+        "requires_stable_for": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Hysteresis guard — the triggering device state must remain stable (unchanged) for this duration before the rule fires. Prevents action storms from transient sensor flicker. Validated at lint; enforcement is best-effort in the engine."
+        },
+        "hysteresis": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Alias for requires_stable_for with clearer semantics. Takes precedence when both are set. The triggering state must be continuously observed for this duration before the rule fires."
+        },
+        "maxFiringsPerHour": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of times this rule may fire in any rolling 60-minute window. Applied after cooldown/throttle checks. Useful as an absolute safety cap for high-frequency MQTT triggers."
+        },
+        "suppressIfAlreadyDesired": {
+          "type": "boolean",
+          "description": "When true, skip the rule's actions if the target device's last-known cached state already matches the expected outcome of the command (e.g. skip turnOn if powerState is already 'on'). Best-effort: requires a warm device cache."
+        },
         "dry_run": {
           "type": "boolean",
           "default": true,

package/dist/rules/conflict-analyzer.js

@@ -0,0 +1,203 @@
+/**
+ * Static conflict analysis for automation rules.
+ *
+ * Detects patterns that are technically valid but likely to cause
+ * operational problems:
+ *
+ *   1. Opposing-action pairs — same device, opposite commands (e.g.
+ *      turnOn / turnOff), triggered by the same source within a short
+ *      window and with no throttle on either rule.
+ *
+ *   2. High-frequency MQTT rules without throttle — rules that listen
+ *      on `device.shadow` (catch-all) with no throttle can fire on
+ *      every shadow push (up to once per second) and exhaust the daily
+ *      API quota quickly.
+ *
+ *   3. Potentially-destructive action without quiet-hours protection —
+ *      a rule that targets a destructive verb is technically blocked by
+ *      the engine, but we can still flag it early so users don't get a
+ *      surprise at runtime.
+ *
+ * Results are designed to be consumed by `rules doctor --json` and
+ * by CI pipelines. Each finding carries a `severity` so callers can
+ * decide how to gate on them.
+ */
+import { isTimeBetween, isAllCondition, isAnyCondition, isNotCondition } from './types.js';
+import { parseMaxPerMs } from './throttle.js';
+import { isDestructiveCommand } from './destructive.js';
+/** Known opposing command pairs (order-independent). */
+const OPPOSING_PAIRS = [
+    ['turnOn', 'turnOff'],
+    ['lock', 'unlock'],
+    ['open', 'close'],
+    ['openDoor', 'closeDoor'],
+    ['openCurtain', 'closeCurtain'],
+    ['turnOn', 'standby'],
+    ['brightnessUp', 'brightnessDown'],
+    ['volumeUp', 'volumeDown'],
+    ['fanSpeedUp', 'fanSpeedDown'],
+];
+function commandsAreOpposing(a, b) {
+    for (const [x, y] of OPPOSING_PAIRS) {
+        if ((a === x && b === y) || (a === y && b === x))
+            return true;
+    }
+    return false;
+}
+function extractDeviceFromAction(action) {
+    return action.device ?? null;
+}
+function extractCommandVerb(command) {
+    // command strings are like "devices command <id> turnOn" — extract last token
+    const parts = command.trim().split(/\s+/);
+    return parts[parts.length - 1] ?? command;
+}
+function effectiveCooldownMs(rule) {
+    if (rule.cooldown) {
+        try {
+            return parseMaxPerMs(rule.cooldown);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (rule.throttle?.max_per) {
+        try {
+            return parseMaxPerMs(rule.throttle.max_per);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function hasTimeBetweenGuard(conditions) {
+    if (!conditions)
+        return false;
+    for (const c of conditions) {
+        if (isTimeBetween(c))
+            return true;
+        if (isAllCondition(c) && hasTimeBetweenGuard(c.all))
+            return true;
+        if (isAnyCondition(c) && hasTimeBetweenGuard(c.any))
+            return true;
+        if (isNotCondition(c) && hasTimeBetweenGuard([c.not]))
+            return true;
+    }
+    return false;
+}
+export function analyzeConflicts(rules, quietHours) {
+    const findings = [];
+    const active = rules.filter((r) => r.enabled !== false);
+    // 1. Opposing-action pairs on the same device
+    for (let i = 0; i < active.length; i++) {
+        for (let j = i + 1; j < active.length; j++) {
+            const a = active[i];
+            const b = active[j];
+            // Only flag when they share the same trigger source (otherwise they
+            // can't race each other in normal operation).
+            if (a.when.source !== b.when.source)
+                continue;
+            const cooldownA = effectiveCooldownMs(a);
+            const cooldownB = effectiveCooldownMs(b);
+            // If both rules have meaningful cooldowns (≥ 5 minutes), the risk is
+            // low — skip.
+            const bothThrottled = cooldownA !== null && cooldownA >= 5 * 60_000 &&
+                cooldownB !== null && cooldownB >= 5 * 60_000;
+            if (bothThrottled)
+                continue;
+            for (const actionA of a.then) {
+                for (const actionB of b.then) {
+                    const deviceA = extractDeviceFromAction(actionA);
+                    const deviceB = extractDeviceFromAction(actionB);
+                    // Skip if devices can't be compared.
+                    if (!deviceA || !deviceB || deviceA !== deviceB)
+                        continue;
+                    const verbA = extractCommandVerb(actionA.command);
+                    const verbB = extractCommandVerb(actionB.command);
+                    if (commandsAreOpposing(verbA, verbB)) {
+                        const noThrottle = cooldownA === null || cooldownB === null;
+                        findings.push({
+                            severity: noThrottle ? 'warning' : 'info',
+                            code: 'opposing-actions',
+                            message: `Rules "${a.name}" and "${b.name}" issue opposing commands (${verbA} / ${verbB}) on device "${deviceA}" via the same trigger source.`,
+                            rules: [a.name, b.name],
+                            hint: noThrottle
+                                ? 'Add a "cooldown" or "throttle.max_per" to both rules to prevent rapid state oscillation.'
+                                : undefined,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // 2. High-frequency MQTT catch-all rules without throttle
+    for (const rule of active) {
+        if (rule.when.source !== 'mqtt')
+            continue;
+        const event = rule.when.event;
+        const isHighFreq = event === 'device.shadow' || event === '*';
+        if (!isHighFreq)
+            continue;
+        const cooldown = effectiveCooldownMs(rule);
+        if (cooldown === null) {
+            findings.push({
+                severity: 'warning',
+                code: 'high-frequency-no-throttle',
+                message: `Rule "${rule.name}" listens on "${event}" (high-frequency catch-all) with no throttle/cooldown. This can rapidly exhaust the daily API quota.`,
+                rules: [rule.name],
+                hint: 'Add "cooldown: 1m" or "throttle: { max_per: 1m }" to rate-limit this rule.',
+            });
+        }
+        else if (cooldown < 30_000) {
+            findings.push({
+                severity: 'info',
+                code: 'high-frequency-low-throttle',
+                message: `Rule "${rule.name}" listens on "${event}" with a throttle under 30 s. Consider increasing to at least 1 m to protect API quota.`,
+                rules: [rule.name],
+            });
+        }
+    }
+    // 3. Destructive actions in rules (engine blocks these at runtime, but
+    //    surface early with clear guidance).
+    for (const rule of active) {
+        for (let i = 0; i < rule.then.length; i++) {
+            const verb = extractCommandVerb(rule.then[i].command);
+            if (isDestructiveCommand(verb)) {
+                findings.push({
+                    severity: 'error',
+                    code: 'destructive-action-in-rule',
+                    message: `Rule "${rule.name}" then[${i}] contains destructive command "${verb}". The engine blocks this at runtime.`,
+                    rules: [rule.name],
+                    hint: 'Remove the destructive command or replace it with a non-destructive alternative.',
+                });
+            }
+        }
+    }
+    // 4. Event-driven rules with no time_between guard when quiet_hours is defined.
+    //    Cron rules fire on an explicit schedule so their overlap with quiet hours
+    //    requires schedule analysis — flag those separately when needed.
+    if (quietHours?.start && quietHours?.end) {
+        for (const rule of active) {
+            if (rule.when.source === 'cron')
+                continue;
+            if (!hasTimeBetweenGuard(rule.conditions)) {
+                findings.push({
+                    severity: 'warning',
+                    code: 'no-quiet-hours-guard',
+                    message: `Rule "${rule.name}" (${rule.when.source} trigger) has no time_between condition and may fire during quiet hours (${quietHours.start}–${quietHours.end}).`,
+                    rules: [rule.name],
+                    hint: `Add a conditions entry "{ time_between: ['${quietHours.end}', '${quietHours.start}'] }" to block this rule during quiet hours.`,
+                });
+            }
+        }
+    }
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return {
+        findings,
+        counts,
+        clean: counts.error === 0,
+    };
+}

package/dist/rules/engine.js

@@ -22,7 +22,7 @@ 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 } from './action.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';
@@ -102,6 +102,88 @@ export function lintRules(automation) {
                     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');
@@ -126,6 +208,8 @@ export class RulesEngine {
     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;
@@ -341,6 +425,24 @@ export class RulesEngine {
     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
@@ -478,6 +580,13 @@ export class RulesEngine {
             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(),
@@ -504,9 +613,13 @@ export class RulesEngine {
             this.opts.onFire?.({ ruleName: rule.name, fireId, status: 'conditions-failed', deviceId: event.deviceId, reason: cond.failures.join('; ') });
             return;
         }
-        const windowMs = rule.throttle ? parseMaxPerMs(rule.throttle.max_per) : null;
+        // 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, windowMs, event.t.getTime(), throttleKey);
+        const check = this.throttle.check(rule.name, effectiveMaxPerMs, event.t.getTime(), throttleKey, dedupeWindowMs);
         if (!check.allowed) {
             this.stats.throttled++;
             writeAudit({
@@ -524,13 +637,87 @@ export class RulesEngine {
                     matchedDevice: event.deviceId,
                     fireId,
                     reason: check.nextAllowedAt
-                        ? `throttled — next allowed at ${new Date(check.nextAllowedAt).toISOString()}`
-                        : 'throttled',
+                        ? `${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) {
@@ -561,6 +748,9 @@ export class RulesEngine {
             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 });
         }
     }

package/dist/rules/throttle.js

@@ -4,6 +4,8 @@
  * Semantics:
  *   - `max_per: "10m"` → a rule may fire at most once every 10 minutes
  *     per (rule, deviceId) pair.
+ *   - `dedupe_window: "5s"` → suppress fires whose key already fired
+ *     within the window (collapses rapid sensor bursts into one action).
  *   - Fires that would violate the window are **suppressed** (not
  *     queued) and surface as `{ allowed: false, reason: 'throttled' }`.
  *   - When a rule has no `throttle` block, `ThrottleGate.check` returns
@@ -26,6 +28,8 @@ export function parseMaxPerMs(expr) {
 }
 export class ThrottleGate {
     lastFireAt = new Map();
+    /** Sliding-window fire-time log for count-based maxFiringsPerHour. */
+    fireTimes = new Map();
     keyOf(ruleName, deviceId) {
         return deviceId ? `${ruleName}::${deviceId}` : ruleName;
     }
@@ -34,21 +38,45 @@ export class ThrottleGate {
      * actually runs so that dry-run / throttled paths don't bump the
      * window.
      */
-    check(ruleName, windowMs, now, deviceId) {
-        if (windowMs === null || windowMs <= 0)
-            return { allowed: true };
+    check(ruleName, windowMs, now, deviceId, dedupeWindowMs) {
         const key = this.keyOf(ruleName, deviceId);
         const last = this.lastFireAt.get(key);
+        // dedupe_window check: suppress if last fire was within this (typically smaller) window
+        if (dedupeWindowMs !== null && dedupeWindowMs !== undefined && dedupeWindowMs > 0) {
+            if (last !== undefined) {
+                const dedupeEnd = last + dedupeWindowMs;
+                if (now < dedupeEnd) {
+                    return { allowed: false, lastFiredAt: last, nextAllowedAt: dedupeEnd, dedupedBy: 'dedupe_window' };
+                }
+            }
+        }
+        // max_per / cooldown check
+        if (windowMs === null || windowMs <= 0)
+            return { allowed: true, lastFiredAt: last };
         if (last === undefined)
             return { allowed: true };
         const earliest = last + windowMs;
         if (now >= earliest)
             return { allowed: true, lastFiredAt: last };
-        return { allowed: false, lastFiredAt: last, nextAllowedAt: earliest };
+        return { allowed: false, lastFiredAt: last, nextAllowedAt: earliest, dedupedBy: windowMs > 0 ? 'max_per' : undefined };
     }
     record(ruleName, now, deviceId) {
         this.lastFireAt.set(this.keyOf(ruleName, deviceId), now);
     }
+    /** Count-based check: has the rule fired >= maxCount times in the last windowMs? */
+    checkMaxFirings(ruleName, maxCount, windowMs, now, deviceId) {
+        const key = this.keyOf(ruleName, deviceId);
+        const times = (this.fireTimes.get(key) ?? []).filter((t) => now - t < windowMs);
+        this.fireTimes.set(key, times);
+        return { allowed: times.length < maxCount, count: times.length, max: maxCount };
+    }
+    /** Record a count-based fire (call alongside record()). */
+    recordFire(ruleName, now, deviceId) {
+        const key = this.keyOf(ruleName, deviceId);
+        const times = this.fireTimes.get(key) ?? [];
+        times.push(now);
+        this.fireTimes.set(key, times);
+    }
     /** Drop everything — used by engine.reload when a rule is removed. */
     forget(ruleName) {
         const prefix = `${ruleName}::`;
@@ -56,6 +84,10 @@ export class ThrottleGate {
             if (k === ruleName || k.startsWith(prefix))
                 this.lastFireAt.delete(k);
         }
+        for (const k of this.fireTimes.keys()) {
+            if (k === ruleName || k.startsWith(prefix))
+                this.fireTimes.delete(k);
+        }
     }
     /**
      * Drop every window whose rule name isn't in the given set — used by
@@ -70,6 +102,12 @@ export class ThrottleGate {
             if (!ruleNames.has(ruleName))
                 this.lastFireAt.delete(k);
         }
+        for (const k of this.fireTimes.keys()) {
+            const sep = k.indexOf('::');
+            const ruleName = sep === -1 ? k : k.slice(0, sep);
+            if (!ruleNames.has(ruleName))
+                this.fireTimes.delete(k);
+        }
     }
     /** Test helper — exposes the underlying size. */
     size() {