@ap3x/cadence

A standalone scheduler for cron, interval and one-shot jobs, with pluggable storage and retry policies. The bundled file store persists schedules and attempts for a single engine process; it does not guarantee exactly-once external effects.

Part of AP3X — a TypeScript multi-agent framework.

Run from source

Follow the repository's source quick start to install locked dependencies and build all workspaces, including cadence. That local install/build/help path has been exercised; published-artifact installation qualification remains open.

What's inside

• Schedules — cron expressions, fixed intervals, and one-shot timers.
• Occurrence claims — bundled stores use in-memory claim markers to exclude competing claims within one process. Schedule advancement is distinct from attempt persistence and execution.
• File-backed state and retries — the file store reloads persisted schedules and attempts; stale running attempts are reclaimed and routed through the retry policy. The memory store does not survive process restart.
• Overlap + misfire policies — choose what happens when an occurrence comes due while the previous attempt is still running (allow, queue, skip_if_running), and what to do with occurrences missed while the engine was down.
• Pluggable stores — in-memory and file-backed stores ship with the package, behind a store interface with a conformance suite.
• Injectable clock — no wall-clock reads in core, so schedules are testable deterministically.

Concurrency scope

The bundled stores hold their claim in process memory and rely on JavaScript's run-to-completion as the critical section. Run one engine process per store directory — multi-process exclusion is out of scope for the in-memory and file stores.

The Store interface specifies claim/advance consistency requirements for alternative adapters. No PostgreSQL adapter ships here, and satisfying those methods alone would not make an external action part of the same transaction.

Crash and effect semantics

A crash after claiming but before persisted slot advancement releases the transient claim, so the occurrence may be claimed again after restart. The engine advances a slot before opening its execution attempt: a crash in that window can leave an advanced schedule without an attempt record for recovery. Persisted running attempts can be retried, including when an external effect completed but its successful result was not recorded. Those retries may repeat the effect.

Consumers must handle effect idempotency and reconciliation separately. Current stores and engine behavior do not establish loss-free delivery across every crash point, multi-process recovery, or exactly-once remote actions. See the durability architecture for the current boundary and proposed qualification work.

Depends on no other @ap3x package.

Documentation

See the AP3X repository for architecture notes, the full package map, and examples.

License

MIT