StackStorm Sensor Event Detection Design Prompt

You are a senior automation engineer who has debugged a StackStorm sensor that re-emitted every event after a restart and triggered a flood of duplicate actions.

I will provide:
- The event source the sensor watches (API poll, queue, webhook, log) and its semantics
- How the source identifies events (IDs, cursors, timestamps) and whether it supports acks
- The trigger schema the sensor emits and the rules that consume it
- Restart frequency and what "missed an event" costs

Your job:

1. **Detection mechanism** — choose poll vs. push for [EVENT_SOURCE] and define the sensor's `poll_interval` or listener, reading only events newer than the last processed cursor.
2. **Cursor/state persistence** — use the sensor datastore to persist the last-seen cursor so a restart resumes from the right place instead of replaying or skipping.
3. **Dedup before dispatch** — track recently emitted event IDs so a source that re-delivers (or an overlapping poll window) does not dispatch the same trigger twice.
4. **Missed-event recovery** — on startup, reconcile against the source from the persisted cursor to catch events that arrived while the sensor was down.
5. **Trigger payload hygiene** — emit a minimal, stable trigger schema with a unique event key so downstream rules can themselves dedupe and stay idempotent.
6. **Failure handling** — handle source errors with backoff, and ensure a sensor crash mid-emit doesn't advance the cursor past an undispatched event.

Output as: the sensor class skeleton, a state/cursor schema, a dedup strategy, and a restart-recovery test plan.

Test restart behavior explicitly — stop the sensor mid-stream, restart it, and assert no duplicate and no missed triggers — before deploying; sensors fail at the boundaries (startup, restart, source hiccups), not on the steady-state happy path.

Why this prompt works

A StackStorm sensor sits at the boundary between the messy outside world and your clean rule engine, and that boundary is where event-driven automation actually breaks. The steady-state happy path — an event arrives, the sensor emits a trigger, a rule fires — is the easy 90%. The prompt deliberately concentrates on the failure boundaries: startup, restart, and source hiccups. The signature StackStorm sensor bug is re-emitting every event after a restart because the sensor began reading from the beginning of the stream, flooding rules with duplicate actions. By requiring a persisted cursor and reconciliation on startup, the prompt forces the design to resume from the right place instead of replaying or skipping.

The ordering of cursor persistence relative to dispatch is the subtle, decisive detail. Advance the cursor before the trigger is dispatched and a crash in between skips an event permanently. Re-emit on restart without dedup and you double-fire. The prompt threads this needle by requiring the cursor to advance only after successful dispatch, plus a recently-seen-ID set to absorb the overlap that polling windows and at-least-once sources inevitably produce. This acknowledges the honest reality that a sensor often can’t guarantee exactly-once on its own — so it must hand downstream rules a stable unique event key and let them be idempotent too.

The required restart-recovery test plan is what proves the design rather than asserting it. The model can produce a sensor skeleton and a plausible dedup story quickly, but the only convincing evidence is stopping the sensor mid-stream, restarting it, and confirming zero duplicates and zero misses. That test exercises exactly the boundary where these sensors fail, which is precisely the boundary that never shows up in a quick happy-path demo.