@n8n/scheduler 0.2.3 → 0.3.0

package/README.md

@@ -1,28 +1,65 @@
 # @n8n/scheduler
 
-A durable, distributed scheduling service for n8n. It schedules recurring and
-one-off work and dispatches each due occurrence to a handler, coordinating through
-the database so every main instance participates and no occurrence is lost across a
-restart or failover. Scheduling (deciding that something is due) is decoupled from
-execution (running it), and dispatch is effectively-once.
-
-It is a general scheduling primitive, not tied to one feature: each occurrence is
-routed to a handler by a `task_type` key. The Schedule Trigger node is its first
-consumer; poll triggers, system tasks and waiting executions are intended to follow,
-replacing today's in-memory, leader-only scheduling. All of it sits behind
-`N8N_SCHEDULER_ENABLED` (default off) while the legacy engine stays in place for
-rollback.
-
-## Scope
-
-- **Coordination** (the core): assign each due occurrence to a single main via
-  claim, lease and fencing, recover work whose owner has died, and dispatch it
-  across the cluster.
-- **Recurrence**: turn a cron, interval or one-off schedule definition into its next
-  occurrence, with correct timezone and DST handling.
+Durable, multi-main scheduling for n8n. Upcoming work is recorded in storage
+before it runs, then claimed, fired and recovered under leases and epoch
+fencing, so each occurrence executes once across the cluster and survives
+restarts and failovers. Occurrences are dispatched to handlers by `taskType`;
+the Schedule Trigger node is the first consumer. Everything sits behind
+`N8N_SCHEDULER_ENABLED` (default off) while the legacy engine stays in place.
+
+## Surface
+
+The package is pure logic, with no DI and no database. It exposes exactly two
+things (plus the types their signatures reach):
+
+- **`Scheduler`**: `registerTaskHandler` plus one accessor per pass
+  (`materialize`, `execute`, `reap`, `prune`, `stop`). The host drives each
+  pass on its own cadence.
+- **`createScheduler(deps)`**: composes the internal algorithms (materializer,
+  executor, reaper, retention) into a `Scheduler`.
+
+The host binds `deps`: a task store and a transaction runner (the `@n8n/db`
+repositories satisfy the store contracts structurally, so no adapters are
+needed), optional per-pass tuning, and an `onEvent` sink for described
+incidents. In n8n that host is the cli's `DurableScheduler`
+(`packages/cli/src/scheduling/`), which wires DI, config and instance identity,
+and routes events to the logger.
+
+## Schedule kinds
+
+A scheduled job says *when* something should run. There are four kinds:
+
+| Kind | Meaning | Example |
+|---|---|---|
+| `cron` | Fires at fixed clock times, written as a cron expression. | `0 0 9 * * 1` = every Monday at 09:00 |
+| `interval` | Fires every N seconds of elapsed time. | every 3600s = once an hour |
+| `one_off` | Fires once, at a single instant, then never again. | fire at 2026-01-01 00:00 |
+| `recurring_cron` | A cron *anchor* thinned by an "every N periods" gate, for cadences plain cron cannot express. | every 3 weeks on Monday |
+
+### Why `recurring_cron`?
+
+Plain cron can say "every Monday", but not "every *third* Monday".
+`recurring_cron` builds that from two parts:
+
+- an **anchor**: a normal cron that lists candidate dates (often too many),
+- a **gate**: keeps a candidate only once at least `recurrenceSize` periods of
+  `recurrenceUnit` (`hours` / `days` / `weeks` / `months`) have passed since the
+  last kept fire.
+
+"Every 3 weeks on Monday" = anchor "every Monday" + gate "1 per 3 weeks":
+
+```
+Anchor (every Monday):  M   M   M   M   M   M   M
+Gate (1 per 3 weeks):   ✓   ✗   ✗   ✓   ✗   ✗   ✓
+Fires:                  M           M           M
+```
+
+The gate looks only at the previous fire, with no stored counter. So any
+instance in the cluster can compute the next run, and a restart never loses the
+cadence.
 
 ## Status
 
-Early foundation. Today the package ships the domain types, the schedule math and an
-initial storage adapter; the coordination engine (sweep, executor, reaper) lands in
-later milestones.
+Early foundation. The algorithms, schedule math and composition surface are in
+place; the driver that runs the passes on their cadences in the main process
+lands in later milestones.