Acta.: the durable work ledger for .NET

Jobs & scheduling

Fire-and-forget jobs

Mark a method with [Job("name")] and call EnqueueAsync(input). Enqueue is typed, dispatch is source-generated from your project manifest, and the job name is the durable, operator-facing contract. The host that enqueues can also execute: no separate worker process to deploy unless you want one.

Delayed jobs

Enqueue with a not-before time. The job is durable, SQL-visible state from the moment of enqueue and is dispatched when due: surviving any restarts in between.

Recurring schedules

[JobSchedule] with an interval (5m) or cron expression. One stable slot job carries moving schedule cursors instead of creating a job row per firing. Missed windows are visible and handled by explicit misfire policy, and schedules can be paused and resumed by operators.

Deduplication keys

Enqueue with a caller-supplied key and a duplicate enqueue is refused instead of creating a second job: resubmitting the same form doesn't send the same email twice.

Retries with typed backoff

Retry count and backoff are explicit, typed policy on the job, not folklore in a catch block. Every attempt is recorded, so "how many times did this run and when" is a query.

Atomic enqueue with your data

Enqueue on the transaction you already opened, so the job and the business write commit or roll back together in the same database. When the job belongs to a different database, stage the handoff in your own transaction with AddToActaOutboxAsync and the built-in sys.outbox relay moves it into the ledger, deduplicating and quarantining as it goes. Neither is a universal exactly-once guarantee: the guide states exactly what each one buys.

Durable execution

Durable steps

Wrap work in a named durable step. The outcome is recorded in the database; when the handler re-enters after a crash, retry, or suspend, a completed step returns its stored result. External side effects still need idempotency because a process can die after the effect but before its outcome is recorded. Checkpoints, not replay: no determinism rules on your code.

At-most-once steps · AtMostOnce()

For side effects where a duplicate is worse than an ambiguous interruption. If the process dies after Acta records the start, the body is not invoked again; it may have run zero or one times, and the handler must reconcile deliberately.

Checkpoint slots

Save intermediate values mid-handler and read them back after a crash or restart: resume long work where it left off, with the evidence in a row.

Durable sleep

Sleep for minutes or days without occupying a worker thread. The job leaves the worker, the timer is durable state, and the job is re-dispatched when it fires: surviving deploys in between.

Signals

A job can suspend until a named signal arrives: a webhook, an approval, another job finishing. Deliver the signal from anywhere: code, CLI, or dashboard. No worker is held while waiting.

Child jobs, fan-out / fan-in

Spawn jobs from a handler; parent lineage is recorded, so a batch that fans out into a thousand items stays traceable, and the parent can wait on the children's results.

Exclusive keys & locks

Serialize work that shares a key (one settlement run per account at a time) without blocking workers on unrelated jobs.

Job results

Return a value from a handler and fetch it later by job reference: the result is durable state like everything else.

Failure & recovery

Worker leases & heartbeats

A claimed job carries a lease held by a live, heartbeating worker. Kill the process: the lease lapses on its own. You can watch it happen in the workers table.

Leaderless recovery

Any surviving worker reclaims lapsed jobs and retries them. There is no coordinator, no leader election, no recovery service to run: recovery is itself ordinary durable work.

Explain

Ask any job why it is in its current state and what happens next. The answer comes from its recorded rows, not from log archaeology.

Restart with original input

A job that failed a month ago is still a row, with its input. Restart it as-is: no re-constructing the payload from logs.

Failure alerts

Failures raise alert rows you can query, route, and resolve like everything else: on-failure visibility without bolting on a separate alerting pipeline.

Visibility & operations

SQL-visible state

Jobs, attempts, leases, events, schedules, checkpoints, workers, and alerts are ordinary rows, with curated operator views (acta.jobs_view and friends) for the common questions: backlog, stuck jobs, worker liveness, pending alerts.

Append-only event ledger

Every job carries a complete, append-only timeline of what happened to it (enqueued, claimed, retried, signaled, completed) as queryable rows.

Embedded dashboard & JSON API

Acta.AspNetCore serves an operational dashboard and query API from inside your app. Local-only by default, no login system to configure, and every mutating verb is disabled until you explicitly enable it.

Embedded CLI · including jobs debug

Every host binary is also the admin tool. jobs debug claims any persisted job and steps through its real handler under your debugger: reproduce a production failure with a breakpoint, not printf.

Operator verbs, opt-in

Pause, resume, cancel, restart, signal: explicit controls for humans running the system, off by default so exposure is a decision, not an accident.

Namespaces & tenants

Two questions, one job row. A namespace answers who owns and runs the work: routing, team-ownership metadata, and the peer workers that drain it. A tenant answers who the work is about: registered once by an opaque business key, resolved at enqueue, inherited by child jobs, carried into the event timeline, and readable beside every job in acta.jobs_view. Definitions can require or forbid tenant scope, and suspending a tenant rejects new work at the enqueue commit boundary without touching jobs already admitted. A tenant is an audit, query, and runtime dimension, not a security or database-isolation boundary.

Engineering

Three SQL providers

Acta.Postgres, Acta.SqlServer, Acta.Sqlite: one reference is enough, and all three share the same schema shape and operational model. Develop against an embedded SQLite file; ship the same code against your server.

Source-generated dispatch, NativeAOT

Handlers are dispatched through generated code (no reflection on the hot path) and the runtime supports NativeAOT. One SQL round-trip per state change.

Deterministic test host

Acta.Testing drives the real runtime one tick at a time: no sleeps, no polling, no flaky waits. Real-database job tests run in tens of milliseconds.

Payload codecs

JSON by default; MessagePack, gzip, or scalar payloads per job when size or speed matters.

Redis as a bell, only

Optional Acta.Redis wakes idle workers faster. It is never a source of truth: lose Redis and you degrade to polling, not to data loss.

Anvil · the failure lab

The bundled load-and-failure laboratory: enqueue a million jobs, kill real worker processes mid-flight, and watch leases lapse and recovery reclaim the work, on your machine.

Policy & operations

Priorities & reprioritization

Claim priority is per-definition policy, and operators can change it in place on a live job with ReprioritizeAsync, no cancel-and-re-enqueue dance.

Execution timeouts & deadlines

Per-definition execution timeout, plus whole-job deadlines in two honesties: a Strict deadline terminates the job; an Advisory one sets ctx.IsOverdue so the handler can degrade gracefully.

Batch enqueue

EnqueueBatch alongside single enqueue for high-volume producers, one round-trip for many jobs.

Tags & correlation keys

Attach searchable tags and a caller-supplied correlation key to any job, so operators can find work by what it means to the business, not just by id.

Time-zone schedules

Recurring schedules run in a named time zone. Operators preview upcoming instants and override expression or zone with expected-version checks.

Alert routing

Definitions route alerts to named channels; startup validation of that routing is a policy you choose. Off, Warn, or Fail.

Audit levels & retention

Audit level and retention are per-definition contract values; terminal job rows purge on schedule while events remain the audit ledger.

Large payloads, by reference

Inline payloads are capped (256 KB default; oversized writes are refused, not truncated). Big artifacts live in blob storage; the job carries a verified reference. URI, checksum, size, content type.