@plurnk/plurnk-schedule

Scheduled messages for Plurnk workers, on RFC 5545 recurrence rules. A rule delivers its message to a worker at each occurrence, as an ordinary message from schedule://<alias>; the worker's live loop takes it, or a new loop starts. Workers manage their own rules through the schedule family (discover, add, list, enable, disable, remove); the operator can seed rules from the environment.

Configure

Put overrides in the shell or $XDG_CONFIG_HOME/plurnk/.env:

TZ=America/New_York
PLURNK_SCHEDULE_heartbeat={"rule":"FREQ=HOURLY","target":"worker://plurnkbot","prompt":"Check for new messages and report."}

• TZ is the zone rules are read in and the time is told in. The package defaults it to UTC; the shell overrides; a workspace overrides through the env family.
• PLURNK_SCHEDULE_<alias> is one definition as JSON: rule, target (worker://<name>) and prompt. A service rule may be unbounded; a rule a worker adds carries COUNT or UNTIL. Without a DTSTART a service rule starts when the daemon starts: FREQ=HOURLY is a check-in at start and every hour after; BYHOUR, BYMINUTE and BYSECOND pin a time of day instead.
• Declared rules start enabled. Set PLURNK_SCHEDULE_heartbeat_ENABLED=0 to disable that rule, or PLURNK_SCHEDULE_ENABLED=0 to change the family default. Aliases are lowercase; use _ for - in environment names.

Behaviour

• No packet carries a clock; a worker reads the time through discover.
• One armed occurrence per rule. A late fire delivers once and skips what it missed.
• Timers outlive a workspace's residency and re-arm at daemon start from the persisted family state.
• A delivery that fails, because the target worker is gone, lists the rule unavailable with its Problem; enable retries.
• An occurrence arrives as a message and runs its own loop on the target worker; no WAIT holds a loop for it.

SPEC.md is the specification; docs/schedule.md is the model-facing teaching beneath the generated runtime document.