How Dormouse thinks
Four nouns, one pipeline, and a rule about what gets to count as having happened.
Everything Dormouse knows is one of four things.
| Noun | The question it answers |
|---|---|
| Target | What is being watched: a URL, the fields to extract from it, how often to check, and the noise policy that judges what it finds. |
| Check | Did a scheduled attempt happen: every attempt is recorded, whether it found a change, found nothing, came back not modified, or failed outright. |
| Observation | What the page actually said: the extracted values from one successful check, tied to a content-addressed snapshot of the raw bytes. |
| Change | What moved between two observations: a field-level difference, judged meaningful or not by the policy engine. |
The separation matters. A check can exist with no observation (the fetch failed), and an observation can exist with no change (the page held still). Both are recorded, because both are evidence: a failed check is a coverage fact, and a still page is the answer "we looked, nothing moved."
Fetch, extract, diff, judge, deliver, record.
Fetch retrieves the page politely: conditional requests so unchanged pages cost nothing, retries with backoff, per-host pacing, and a guard that refuses to connect to private or internal addresses so a watched URL can never be turned into a probe of your own network.
Extract reduces the page to the fields the target declared, or to line-aware page text when no fields are declared. Diff compares the new observation against the baseline, entity-aware for lists. Judge applies the deterministic noise policy and issues the verdict: meaningful, or not.
Deliver routes meaningful changes to your channels with deduplication and cooldowns. An optional annotator adds a severity, a topic, and a one-sentence summary after the fact, off the hot path: classification never decides what counts as a change. Record writes the whole cycle into the chained trail.
A byte moved is not the same as something happened.
Pages breathe: rotating banners, cache tokens, reordered rows, cosmetic rewording. A watcher that reports all of it trains you to ignore it, and an ignored watcher is worse than none. Dormouse separates what changed from whether it matters, and only the second ever interrupts you.
The rules that produce the verdict are deterministic and inspectable, and they are the subject of volume three.
Nothing counts as seen until everything is saved.
A monitoring tool has one unforgivable failure: advancing its baseline without keeping the changes it saw, so the next comparison silently starts from the new state and the event vanishes without a trace. Dormouse is built so that failure cannot happen.
Diffing and judging run before anything persists, and the observation commits together with its judged changes in a single transaction. If the process is interrupted mid-cycle, the whole cycle simply never happened: the baseline stands, and the next check sees the change again. A failed check never advances the baseline, so an outage is followed by a comparison against the last state you actually saw.