feat(scheduling): declare recurring work with #[Scheduled]

[mikield]

Work that is not a reply to anything — sweeping rows that have run their course, expiring caches, polling a service with no gateway event of its own — had no home in the framework. Every bot reaches for Loop::get()->addPeriodicTimer() inside a plugin's boot() and then writes the same three safeguards, or more often does not write them.

#[Scheduled(everySeconds: 10)]
final readonly class SweepTemporaryMessages
{
    public function __construct(private TempMessages $messages) {}

    public function __invoke(): void
    {
        $this->messages->sweep();
    }
}

Discovered like a command or a listener, built by the container, put on the loop before the gateway opens.

Why this is not just sugar over addPeriodicTimer

A timer is less forgiving than an event listener — it fires again whether or not the last turn finished or threw, forever:

• A task that throws is logged and keeps its place. Otherwise the exception travels into the event loop; the usual result is a cancelled timer and nothing ever swept again — silently, because the bot carries on answering commands and looks healthy.
• A task is never started alongside itself. A turn still running when the next is due is skipped, and the skip logged. Without that, a task slower than its own interval makes every following turn slower until nothing else gets a look in.
• Each turn runs in a fiber, so a task may await the REST API exactly as a command handler does. This mirrors EventDispatcher.

Deliberate choices worth arguing with

• The first turn comes after the interval, not at boot. A scheduled task is a repeating chore; one-off startup work (reconciling against what changed while the bot was down) belongs in a plugin's boot() where its ordering against everything else is visible. I left out an immediately: flag rather than guess.
• A zero interval is refused at discovery, since it asks the loop to run the task as fast as it can and starves the gateway heartbeat.
• start() takes the loop as an argument rather than reaching for Loop::get() itself, so the tests drive a StreamSelectLoop they own and the overlap and containment behaviour is exercised for real rather than mocked.

Adds a reference page and a guide; composer docs output is committed.

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 0.10.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀