oficina / calendar Public

reminders: make the platform's wake carry work with it

A reminder for a 14:00 meeting arrived at 14:47, and the instance was
awake for almost all of the 57 minutes it was late. Hibernation was not
the cause; the wake was.

`carlos logs` for 2026-09-04 shows the shape of it:

    13:57:08 instance stopping  →  13:57:38 instance woke
    14:13:08 instance stopping  →  14:13:38 instance woke
    14:29:08 instance stopping  →  14:29:38 instance woke
    14:45:08 instance stopping  →  14:45:38 instance woke

Awake fifteen and a half minutes, asleep thirty seconds, over and over,
sending nothing. The activator was doing its job perfectly: it asked
/api/next-due before hibernating, recorded the answer, and woke the
process at it. But a wake IS only a process start. No request arrives
with it, and the drain had no boot entrance — so the woken instance did
nothing, idled out, hibernated, answered the same still-overdue instant,
and was woken again. The 6h declared schedule was hours away. The mail
finally went when somebody loaded a page.

The design said three entrances — boot, tick, request. Two were built.
It also specified the one-shot timer that makes the wake arrive as a
POST rather than as a bare exec, and that was never written at all:
`grep ScheduleAt` across this repo returned nothing.

Four fixes, each with a test that fails without it, and each mutation
tested — the guard was broken on purpose and the named test watched to
fail before it was believed.

1. App.DrainAtBoot, called from main before Serve. The entrance the
   spec named and nobody built. Synchronous: the agent binds the socket
   before spawning us, so a request arriving mid-drain waits, and the
   pass is bounded by drainDeadline.

2. A one-shot platform timer, upserted by name, so the wake arrives as
   a POST to /jobs/reminders. Named `reminder-next`, NOT `reminders` as
   the design document proposed: `carlos schedule set` already declares
   a recurring schedule of that name on this app, one-shot timers share
   the namespace, and ScheduleAt answers ErrDeclaredSchedule for a
   declared name. The obvious name would have been refused on every
   call — silently, since a refusal is a log line we move on from. Held
   as swappable package vars so a test can watch what the app asks for
   without standing up a control socket.

3. NextDueAt now answers with work this instance CAN DO. It returned
   MIN(due_at) over every unfired row, including rows a drain had
   claimed and failed to send — which are deliberately unclaimable for
   the five-minute lease. So an undeliverable address left next_due
   permanently in the past and reproduced the whole wake/sleep loop on
   its own: wake, claim nothing, idle fifteen minutes, hibernate, wake.
   A claimed row now answers when its lease expires.

4. The rearm goes in the signed-in middleware, after the handler, not
   one call per writer. Every write to the reminder queue happens inside
   a request in that group — create, edit, add or remove a reminder,
   exclude an occurrence, delete — so one call covers all of them and no
   future writer has to remember. It costs an indexed MIN and a
   comparison; nothing reaches the control socket unless the answer
   moved. The tick route is outside that group and rearms for itself.

AGENTS.md and the design doc are corrected in the same commit, per this
file's own rule. The design's item 1 said `NextDue` "wakes the process
for it" and stopped there — the gap in the sentence is the gap that got
built, so it now says all three parts out loud.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0155Ae1Q1aR51HX97nmBovG6