The watcher engine

The engine is the part of Watcher that actually watches: the loop that runs for one watch, decides whether anything happened, and delivers the result. Every trigger — a cron job, a button in the app, an API call — ends up in the same loop.

This section documents it at operational depth: precise enough to predict its behaviour and debug it, without requiring you to read the source. If you do want the source, Internals is the bridge.

Why it exists

Polling a page by hand does not scale, keyword matching produces false alarms, and asking a language model alone produces confident fiction. The engine exists to wrap a model in checks that do not depend on the model being right:

• it only judges content it has not judged before,
• it demands a quote it can find in the page,
• it grades the source that quote came from,
• it asks a second, different model about every trigger,
• and it remembers what it already told you.

What it is responsible for

1. Redelivering alerts that previously failed to send.
2. Collecting from every source, tolerating individual failures.
3. Reducing to genuinely new content.
4. Asking the evaluator for a verdict, with recent history as context.
5. Validating the verdict’s evidence against what was collected.
6. Deciding an alert tier.
7. Suppressing duplicates, exactly and semantically.
8. Delivering on every configured channel.
9. Persisting what it learned.

What it is not responsible for

Note

Scheduling belongs to the entrypoints, run history to the layer above the loop, model retries to the evaluator and the key pool, and message formatting to the notifiers. The loop orchestrates; it does no I/O of its own.

Read in this order

How it worksOne run, stage by stage, with the early exits named.

TriggersThe four things that can start a run.

Decision rulesExactly when an alert fires, and at which tier.

Run outcomesAll ten outcomes: meaning, stored state, and what to do.

Failures and retriesWhat happens when a source, a model or a channel breaks.

What Watcher remembersState between runs, and the consequences you will actually notice.

InternalsModules, ports and the concurrency model.