Concepts: Overview

Wakeplane is a scheduling control plane, not a thin cron wrapper. Understanding its model makes the API, policies, and durability guarantees predictable.

The Problem

Cron expresses cadence. It does not:

• record that a run was due
• track whether it succeeded, failed, or was skipped
• handle missed runs across restarts
• enforce concurrency limits or timeouts
• retry on failure
• preserve an audit trail of what ran and what happened

Wakeplane is the layer above cron. It decides what is due, records each occurrence as a durable database row, dispatches typed execution, and keeps an append-only ledger of what happened.

Core Components

Planner

The planner loop ticks at a configurable interval (default: every 5 seconds). On each tick it:

1. Loads all enabled, non-paused schedules.
2. Computes the next occurrence for any schedule where next_run_at is in the past.
3. Materializes a Run record in the database with status pending.
4. Updates next_run_at on the schedule.

The planner does not execute work. It only materializes the intent.

Dispatcher

The dispatcher loop ticks at a configurable interval (default: every 2 seconds). On each tick it:

1. Queries for pending runs that are ready to dispatch, respecting overlap and concurrency policy.
2. Claims each eligible run by transitioning it from pending to claimed and inserting a worker lease.
3. Starts execution in a goroutine.
4. Renews the worker lease at half the TTL until execution finishes.
5. Records the result as succeeded, failed, cancelled, or dead_lettered.

The dispatcher recovers stale state from the previous process on startup. Runs that were claimed or running when the process died are recovered via lease expiry and moved back to pending or marked failed for retry.

Occurrence Key

Every run has an occurrence_key that encodes its identity.

Scheduled occurrences use:

{schedule_id}:{nominal_time_rfc3339}

Manual triggers use manual:{run_id} instead. A retry is a new run record with the same occurrence key and an incremented attempt number.

Receipt And Dead Letter

Receipts are execution artifacts attached to a run. Dead letters capture exhausted failures that will not be retried automatically.

What Wakeplane Is Not

• It is not a DAG orchestrator.
• It is not a distributed job queue.
• It is not Temporal or Airflow.
• It is not a workflow IDE or no-code tool.

Current Scope

Wakeplane v0.2.0-beta.1 has no authentication, no RBAC, no UI, and no distributed coordination. See Security for binding guidance.