API Reference Belay v#2.0.0

A standalone, agent-native durable job engine on Postgres (or in-memory for tests). No Oban, no Ecto — Postgrex, Jason, and telemetry only.

Insert a group of jobs and run a callback when the whole group has finished — thin, transparent sugar over Belay.Workflow.

Injectable time source. Everything time-dependent in the engine (backoff, lease expiry, rate windows, await deadlines, cron slots) reads through this, so tests advance a Belay.Clock.Sim instead of sleeping.

A settable, advanceable clock for deterministic tests.

Real time.

The cross-language value envelope for step values and job results (SCHEMA.md, "Value encoding").

The resolved runtime configuration of a Belay instance.

Minimal five-field cron expressions: minute hour day-of-month month day-of-week.

Runtime cron management, persisted in the database, fired leaderlessly by every node with per-slot dedup — change schedules without deploys.

Execution context passed to Belay.Worker.run/1. Carries the job and everything the step/signal/budget APIs need. replay?: true marks a Belay.Replay dry run: memoized reads succeed, side effects are inert, and anything unrecorded halts with a precise report.

An embedded web dashboard with zero dependencies — no Phoenix, no Plug, no JS build. One child spec

Raised at insert time when a job's input fails its worker's input_schema.

Insert-time input validation, declared on the worker

The durable job record.

A Model Context Protocol server over stdio, so AI assistants (Claude Code, Cursor, or your own agents) can inspect and operate a Belay installation

Move an Oban installation's pending work into Belay.

Wake-up delivery for low-latency dispatch.

The always-on notifier: registry pokes on this node, :pg fan-out to clustered BEAM nodes. Configured as :local.

The opt-in pg_notify accelerator (configured as :postgres): wake-ups ride the database itself for fleets that share Postgres without an Erlang cluster. See Belay.Notifier for semantics and caveats.

Runtime queue management, persisted in the database and applied by every node — no leader, no deploy.

Time-travel debugging: re-run a job's code against its recorded journal.

The storage contract: coarse, semantic, individually-atomic operations.

In-memory storage: a single serialized GenServer, deterministic given call order. The reference implementation for engine semantics and the substrate for simulation tests. Not durable — for tests and ephemeral dev only.

Postgres storage over Postgrex — no Ecto. Claims use FOR UPDATE SKIP LOCKED; workflow settlement and parent notification happen inside the acking transaction; uniqueness is enforced by partial unique indexes; the clock is always a query parameter, never now().

Telemetry events emitted by Belay

Synchronous, deterministic execution for tests: drain/3 claims and runs ready jobs in the calling process until the queue is empty, following workflow releases as they happen.

Transactional enqueue: insert jobs inside your database transaction, so a job exists if and only if the business write committed.

Define a durable worker.

Jobs composed with directed acyclic dependencies.

Serve the Belay MCP server over stdio against a Postgres database

Create or update Belay's tables (idempotent)

Move pending Oban work into Belay, safely.