FEATURES

Coordination.

Exactly-once tool calls, durable work distribution, persisted scheduling, and multi-subscriber delivery — the primitives that make retries and workers safe.

Idempotent tool executions

Actae never executes tools — your code does. What Actae provides is the coordination layer that makes the call idempotent: a durable ledger with claims, leases, fencing tokens, and stored results.

  1. Your worker claims an execution (stable operation key + parameter fingerprint).
  2. The claim is exclusive: a concurrent claim with the same key fails loudly instead of double-running.
  3. Your worker runs the tool, then completes it — the result is stored and a retry of the same operation key returns the stored result instead of re-running.
  4. Long-running tools send heartbeats; a lost lease lets another worker pick up the claim (fencing tokens prevent stale completions).
  • Retrying with the same operation_id returns the original event — no duplicates, no side-effect replay.
  • Reusing an operation key with different parameters is a loud conflict, not a silent overwrite.
  • Failure paths are explicit: fail records the error, cancel releases the claim.

The retry that is safe

A network timeout after a payment call is ambiguous. With Actae, the retry claims the same operation key: if the first attempt actually succeeded, you get the stored result; if it didn't, you own the claim and run it once. The ambiguity is resolved by the ledger, not by hope.

Consumer groups

Consumer groups turn a channel into a durable work queue with at-least-once semantics: members claim events under leases, ack them, and the server tracks per-consumer offsets. Crash recovery is built in — a consumer that dies loses its lease and its in-flight range is reclaimed.

  • Lease-based claims with heartbeat renewal; a stale member is fenced out.
  • Per-consumer offsets persisted server-side; a re-joining member resumes from its last ack.
  • No group-level watermark: each consumer is accountable for its own range.

Keep the work channel clean

A group claims everything on its channel. Acking past a crashed consumer's in-flight range skips it permanently. The reference pattern is two channels: a work channel for claims and a separate audit channel for the events you want to keep.

Wake-ups

Persisted, scheduled events: ask Actae to publish an event at a future time (or after a delay) and it does — durably. Wake-ups survive restarts, fire once, and are one-off by design. Cancel them before they fire; an already-fired wake-up refuses cancellation loudly.

Fan-out delivery

Any number of subscribers can follow a channel. Delivery is batched, ordered, and cursor-tracked per subscriber — each subscriber catches up from its own cursor without affecting the others. This is what makes dashboards, audit consumers, and experiment monitors share one event stream safely.