Loading the Markdown.This is the page an agent receives: the same how-to as plain Markdown, at this page's address with .md added.
learn acta
Try
Every answer is a short how-to: the handler, the call that starts it, the command that runs it, and the lines it must print. The code is lifted from programs in the Acta repository, and each page says how its program is checked. Each page is also plain Markdown, so your coding agent learns from the page you read.
which one when
the how-tos, section by section
Define a job, start it, and read back what it did. Start at the top.
[Job] method, one enqueue, and a worker that runs itWaitAsync<T> follows the job to its end and hands the result back, typedGetAsync answers a snapshot of the job: its ref, its name and namespace, its status, and when it was createdTryGetResultAsync<T> finds nothing before Succeeded; GetResultAsync<T> returns the result you expectEvery way to start work: now, later, once only, by name, or many at a time.
EnqueueAsync takes the input alone: its type names the job, so there is no name string to get wrongEnqueueJobRequest names the namespace and the job as strings, for a caller that does not have the job's types[Job] methods. Each is a job of its own, with its own generated callScheduleAsync(input, delay) stores the job now and makes it due after the delay. No process has to stay alive until thenScheduleAsync(input, runAt) starts a job then, SleepUntilAsync pauses a handler until then, and RescheduleUntilAsync runs the handler again thenDeduplicationKey.PerTimeBucket here, with PerHour and PerDay as its fixed sizesEnqueueAsync takes your open transaction, so the order row and the job that fulfils it commit together, or neither existsJobLookup.ByDeduplicationKey finds a job by the key it was enqueued with, when you did not keep its refEnqueueAsync returns as soon as the job is stored; CallAsync enqueues, waits, and returns the job's outcomeEnqueueJobsAsync writes a whole list of jobs in one round trip to the database and answers their outcomes in request orderscalar-v1 and json-gzip, and runs the same echo job through eachLabRecurring work as one permanent job: by cron, by interval, in a time zone, or from a calendar.
[Schedule] with a cron makes one permanent job that fires on that cadence, with nothing to enqueueTimeZoneId fires at the same local hour all year: 0 8 * * * in Europe/Berlin is 08:00 in Berlin, in summer and in winter10s, runs a job at a fixed gap, where a timer loop in a hosted service would otherwise stand[Schedule] attributes on one job share one permanent job, and schedules that come due together fire it onceLabMisfireStrategy on the schedule makes it. Three schedules miss the same stretch while paused: Skip, the default, passes over them and fires only a latest one less than a minute overdue, CatchUpOnce runs one firing that covers them all, and CatchUpAll runs every one in orderLaboperations.Schedules pauses a schedule from outside the handler, for good or until an instant, and resumes itoperations.Calendars. A schedule binds it by name, and a later publication retimes every schedule bound to it in one transaction while workers runScheduledDelivery = PerOccurrence makes each occurrence a root job of its own, with its own ref, retries, result, and retention. MaxOutstanding bounds how many may be unfinished at onceIdle. FiringFailurePolicy says what happens to its schedules then: Continue, the default, fires the next occurrence as usual, and Pause pauses them, with the reason, until an operator resumes themResetStateAsync as the firing's last line clears them, so the next one starts blankOne job that keeps calling a service and remembers how far it got.
RescheduleAsync ends the execution and runs the handler again after a delay, without counting as a failure or spending a retrySteps and variables record what a handler finished, so a retry or a restart carries on instead of starting over.
GetOrSetVariableAsync, shown across a retry in 203, a handler can check for a variable, delete it, read it with a default, and store a raw JobPayloadcatch on EndsJob compensates before the failure ends the jobSetProgressAsync stores how far the job has come as the checkpoint sys.progress, which the dashboard lists while the job runsA waiting job is a row. No worker and no process stays busy while it waits.
CallAsync answers a JobOutcome: whether the wait timed out, whether the job failed, and the value when it succeededFan out, join the results, and decide what a failed child means.
CallChildAsync starts another job as a child, waits for it without holding a worker, and returns its outcome, whose ValueOrThrow() is the resultMapAsync starts one child job per item of a list, waits for them all, and hands back each item's result for the parent to mergeEnqueueChildAsync with WaitChildrenAsync for a few named children, and MapAsync for one child per item of a list{map}/{key} for a child that a map started. List the parent's children and pick the one that carries the item's keyFailed list of the wait or the map, and ThrowIfAnyFailed is how the parent chooses to fail with itIJobs and enqueues many independent jobs, each with a stable deduplication key. Nothing links them to the handler's job and nothing waits for them (compare 212's MapAsync)Retries, backoff, timeouts, deadlines, and ending a job on purpose.
MaxAttempts on the job is its retry budget. When the last attempt fails, the job ends as FailedBackoff on the job sets how the wait between retries grows: 1s..8s x2 exact starts at one second, doubles with each failure, and stops growing at eightFailAsync ends the job as Failed at once, whatever its retry budget. A thrown exception would be retriedCancelAsync in a handler ends the job as Cancelled: terminal, not a failure, so no retry and no alert followPauseAsync in a handler parks the job as Paused until someone resumes itExecutionTimeout caps one attempt: when the time is up, the handler's CancellationToken trips and the cut spends an attemptCancellationToken and passes it to everything it awaits, so a cancel, a timeout, or a shutdown that outlasts the host's grace period ends it promptlyDeadline is the whole job's budget, measured from its creation. Under the default, strict behaviour an overdue job is cancelled before its handler runsDeadlineBehavior = Advisory an overdue job still runs. The handler reads IsOverdue and chooses a reduced pathKeep jobs that touch the same thing from running over each other.
RunWithLockAsync holds a named lock around a piece of work, so jobs that name the same lock take turnsConcurrencyKey on the enqueue lets one job at a time run for that key. ConcurrencyLimit on the job gives a key several slots, and RateLimit meters how often attempts are admittedLabRead what happened, find jobs, and cancel, pause, resume, or restart them.
jobs info, events, explain, and the control verbs for any job, read from the same databaseLabMapActa serves the dashboard and its JSON API from your own app. Its controls are off until you turn them onLabIJobs reads one job for a page of your own: its status, a value the handler keeps for the screen, and a sentence that says why the job is where it isListEventsAsync with LineageRoot reads the timeline of a job and of every child it startedoperations.Ledger lists jobs with filters, pages through them by cursor, counts them, and answers the health counters an operator's screen opens withCancelAsync on a job's handle cancels it from outside its handler. Any process that holds an IJobs can do it, and a running handler's CancellationToken tripsIJobs.PauseAsync and ResumeAsync pause and resume a job from outside its handler. Each answers whether it was applied or rejected, and its reason lands on the job's timelineRestartAsync runs a finished job again under the same identity. The failure budget is reset, the history is appended to, steps that succeeded are not run again, and the bare lines of the handler areLabMapActaApi mounts the operator API without the dashboard. Its controls are off until EnableControls is set, answer local requests only by default, and a control request has to confirm itselfRequirePermissions has every route of the HTTP API check the host's policy named for its permission: read, enqueue, control, or admin. A caller with no credential gets 401, and one that lacks the permission gets 403 naming itTenantName on the enqueue records which tenant a job is for. Its children inherit the tenant, the job list filters by it, and an enqueue for an unknown or a suspended tenant is refusedLabCorrelationKey set on the enqueue travels with the job and with every child it starts. It is on the job row, in each handler's log scope, and a filter of the job listIJobPipelineBehavior wraps every handler call, the way middleware wraps a requestEventRecording on the job decides which events it writes. Audit, the default, records every event. Failures records the failed and orphaned attempts, the success that recovers from a failure, what an enabled alert profile reads, a caller's controls of the job, and a schedule's pauses and manual triggersAlerts raised by failures or by your own code, routed where your team looks.
AlertAsync in the handler. AlertProfile on the job says when, and repeats of the same job's failure count up on one alert rather than opening new onesAlertAsync in a handler raises an alert for the people who operate the system, and operations.Alerts reads it backAddAlertChannel declares where alerts go, under a name of your choice, and an alert names the channel it is forAlertFailureThreshold, and the final failure when the retry budget is spentThe real runtime on a throwaway database, driven one tick at a time.
Acta.Testing runs the real runtime on a real database with no background loop: RunOnceAsync decides when a job executes, so a test drives one attempt at a time. Run it with dotnet test learn/800-testing/801-testing-jobsRunOnceAsync drives exactly one attempt, so the suspend on a signal and the resume after its raise are two explicit ticks, and the test asserts that the step before the wait ran once across the replay. Run it with dotnet test learn/800-testing/802-testing-durable-jobsdotnet test learn/800-testing/804-continuous-synchronization-testsSplit the API from the worker, add workers, and tune them.
Reference<TManifest>() lets a process enqueue a namespace's jobs by type without running a worker for it. Run<TManifest>() is the process that executes themRun starts a worker for one namespace. Two of them in one process share the process and the database, and never each other's jobsJsonSerializerContext given to UseJsonPayloads serializes payloads with no runtime reflection, and JobPayload.Json(value, typeInfo) builds a raw payload the same way. The program runs on the JIT: it shows the registration an AOT publish needs, and the publish itself is proven by the repository's own gateUseRedisWakeup announces each enqueue over Redis, so a worker in another process starts the job within milliseconds instead of at its next pollMaxConcurrentExecutors caps how many jobs one worker runs at once, and SafetyPollInterval bounds how long an idle worker sleeps between looks at the databaseLooking for a how-to that is not here? Tell us what you were trying to do, and it becomes the next one.
for coding agents
An agent does not need this page's design. It needs the smallest working example of the task, the rules that go with it, and a way to tell that it worked.
Add .md to a how-to's address and it answers as plain text: the same steps, code, rules and checks. Switch any page to "an agent" to see it.
/learn/index.md names every how-to by task, section by section, each with one line on what it teaches.
A how-to names the lines its program must print. The release check reads the same lines, so the page and the code cannot drift apart.
Read https://useacta.net/llms.txt, then https://useacta.net/learn/index.md. Pick the how-tos that match this task and read each one as Markdown: [describe the task]. Build it, run it once, and show me its job ref and its jobs explain output.Read https://useacta.net/learn/index.md and take me through the short tour, one how-to at a time. After each one that has a check question, ask me the question before you show the answer.keep going
Loading the Markdown.This is the page an agent receives: the same how-to as plain Markdown, at this page's address with .md added.