Background jobs
and workflows that survive restarts.

[Job("send-welcome-email")]
public Task Send(WelcomeEmail email, CancellationToken ct) =>
    mail.SendWelcomeAsync(email.To, email.Name, ct);

// From a controller, a handler, anywhere in the app:
await jobs.EnqueueAsync(new WelcomeEmail(user.Email, user.Name));

SELECT job_status, failure_count, next_run_at_utc
FROM acta.jobs_view
WHERE definition_name = 'send-welcome-email';

[Job("process-order")]
public async Task Process(Order order, JobContext ctx, CancellationToken ct)
{
    var booking = await ctx.RunStepAsync("book-shipment",
        c => shipping.BookAsync(order.Id, $"booking:{order.Id}", c), ct);

    if (!booking.Confirmed)
    {
        await ctx.FailAsync("Shipment booking was rejected", ct);
        return;
    }

    var charge = await ctx.RunStepAsync("charge-card",
        c => payments.ChargeConfirmedAsync(order, $"payment:{order.Id}", c), ct);

    var invoice = await ctx.RunStepAsync("issue-invoice",
        c => invoices.IssueAsync(order.Id, booking.Id, charge.Id,
            $"invoice:{order.Id}", c), ct);

    await ctx.RunStepAsync("send-receipt",
        c => mail.ReceiptAsync(invoice.Id, $"receipt:{invoice.Id}", c), ct);
}

[Job("sync-orders")]
[Schedule("every-5s", "PT5S")]
public async Task Sync(JobContext ctx, CancellationToken ct)
{
    var watermark = await ctx.GetVariableOrDefaultAsync("watermark", 0L, ct);
    var changes = await shop.ChangesAfterAsync(watermark, 40, ct);
    if (changes.Count == 0) return;   // up to date until the next firing
    await store.ApplyAsync(changes, ct);   // an upsert: a replay lands once
    await ctx.SetVariableAsync("watermark", changes[^1].ChangeId, ct);
}

[Job("publish-manuscript")]
public async Task Publish(
    Manuscript manuscript, JobContext ctx, CancellationToken ct)
{
    var proofId = await ctx.GetOrSetVariableAsync(
        "proof-id", Guid.NewGuid, ct);

    var prepared = await ctx.ParallelAsync("prepare", p => p
        .Child("pdf", new BuildProofPdf(manuscript.RevisionKey, proofId))
        .Child("references", new CheckReferences(manuscript.RevisionKey)),
        ct);

    prepared.ThrowIfAnyFailed();

    await ctx.RunStepAsync("request-review",
        c => proofs.RequestReviewAsync(proofId, c), ct);

    foreach (var role in new[] { "author", "editor" })
    {
        var approval = await ctx.WaitSignalAsync<ProofApproval>(
            $"{role}-approval", TimeSpan.FromDays(14), ct);

        if (approval is not { Approved: true } || approval.ProofId != proofId)
        {
            await ctx.CancelAsync("This proof was not approved", ct);
            return;
        }
    }

    await ctx.RunStepAsync("publish",
        c => proofs.PublishAsync(proofId, c), ct);
}