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.

Enqueue and wait

RunAndWaitAsync enqueues, waits for the terminal outcome, and hands back the typed result: request-response over durable execution, for the places where fire-and-forget isn't an answer.

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 operators can pause a schedule (with an auto-resume time if they want one), resume it, or fire it immediately with trigger-now, all without touching the cadence.

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 enqueue the email job twice. It deduplicates the job row, not the side effect: execution stays at-least-once, which is what durable steps and idempotency keys are for.

Retries with typed backoff

Retry count and backoff are explicit, typed policy on the job, not folklore in a catch block. Attempts are counted on the job row, and at the default audit level each one is recorded as start and finish events, 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 progress

SetProgressAsync writes typed progress into a reserved checkpoint slot: a long import can say "43,000 of 90,000", and the dashboard, the API, and plain SQL all read the same 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. An ExclusiveKey bounces the losing job back to the queue so no worker waits on it; RunWithLockAsync waits inside the running handler instead, for the small critical section that wants it. Exclusion rides the lease, and admission order is unspecified: exclusive, unordered work.

Job results

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

Handler-directed outcomes

A handler can end its own run deliberately: reschedule itself to a chosen instant, fail with a stated reason, cancel, or pause for an operator. The outcome is policy stated in code, not an exception dressed up as control flow.

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 stored 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. The restart runs whatever the row holds now, so if an operator amended the input first, the amendment is what runs.

Job repair, beyond restart

Reschedule a job to run now or at a chosen instant, amend its stored input (bounded metadata records that you did), or purge it outright: the repair verbs operators actually reach for, durable and audited like everything else.

Failure alerts

Failures raise alert rows by default: query, route, and resolve them like everything else, on-failure visibility without bolting on a separate alerting pipeline. An outage is one open incident per job and reason that re-notifies on the reminder interval (daily by default) until it resolves, not a row per failure. Per-definition profiles can quiet a job down to terminal failures only, or to nothing.

Outbox quarantine

The sys.outbox relay deduplicates as it admits staged work, and what cannot be admitted lands in a quarantine you can read, requeue, or discard: from code, the dashboard, or HTTP, with the decision recorded.

Visibility & operations

SQL-visible state, documented

Jobs, 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, open alerts. The model is documented column by column - 15 entities with their keys, indexes, and checks - and the full provisioning SQL for all three providers ships in the repo, so you can read the schema before you adopt it. Attempt-by-attempt history rides the event ledger, as complete as the definition's audit level.

Append-only event ledger

Every job carries an append-only timeline of what happened to it - executions started and finished, retries, suspensions, signals, operator actions, completion - as queryable rows. The audit level chooses how much of it each definition writes: the full timeline at Audit, failures only or nothing at all where churn matters more than history.

Notes & manual alerts

ctx.NoteAsync appends handler-authored evidence to the job's timeline even where audit is turned down; ctx.AlertAsync opens an alert the handler decided is worth an operator's attention. Both are rows, like everything else.

Built-in metrics

An Acta meter emits executions, durations, claims, steps, live executing jobs, lock contention, and alert activity through System.Diagnostics.Metrics: OpenTelemetry picks it up with one line, no Acta-specific exporter.

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 an eligible persisted job - one this host's manifest knows and no worker is running right now - 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. Over HTTP and the dashboard they are off by default, so remote exposure is a decision, not an accident. The in-binary CLI ships enabled - it already implies shell access to the host - and DisableCli() turns it off where even that is too much.

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 enqueues at the commit boundary; jobs already admitted keep running, and children they spawn inherit the tenant with them. Namespaces carry the same operator lifecycle: list, suspend, resume, and version-checked metadata updates. 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.

Execution profiles

Buffered, Direct, and Bulk choose the throughput-durability trade explicitly, per worker. Bulk group-commits completions and is meant for safely re-runnable work; the docs state exactly what each profile relaxes.

Source-generated dispatch, NativeAOT

Handlers are dispatched through generated code (no reflection on the hot path). NativeAOT is exercised, not asserted: every shipped package declares AOT compatibility and the bundled lab app publishes under NativeAOT as a gated test. 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.

Contract-drift guard

Worker startup compares each job's input and output contracts against what the ledger recorded, and warns or refuses - your choice - before a mismatched payload meets a live queue.

Payload codecs

JSON, text, and bytes ship built in; the serializer registry is pluggable per job, with worked MessagePack and gzip examples in the concepts.

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.

Published baselines

The benchmark matrix and its methodology ship in the repo, with dated results on documented hardware: one worker at 32 concurrent executors on the conservative Buffered profile measured 3,855 end-to-end jobs/s on PostgreSQL and 3,087 on SQL Server (2026-07-31 baseline, 32 logical cores, NVMe). Regression evidence and rough sizing, not capacity promises: re-run it on yours.

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.

Live policy overrides

Priority, retries, backoff, timeout, deadline, retention, audit, and alerting can be overridden per definition on a running system, guarded by expected-version checks: tune a hot job without a deploy.

Durable named settings

Global, namespace, and definition-scoped settings live in the ledger next to the work: compare-and-swap writes, audited changes, new names without a migration. Configuration your operators can see.

Execution timeouts & deadlines

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

Batch enqueue

EnqueueBatchAsync 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. Tags reach past jobs: tenants, namespaces, definitions, schedules, workers, alerts, and events all take them.

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 (1 MiB default; oversized writes are refused, not truncated). Big artifacts belong in blob storage with the job carrying a reference - URI, checksum, size, content type - a pattern the concepts show worked end to end. The cap is Acta's; the blob store and the verification stay yours.