Background jobs and queueing

Core includes a BatchJobActor and message queue abstractions for queued actor commands. Treat this as a separate background path from the selected atomic command transaction and external effect intent protocol.

Queue contract

IMessageQueueProvider supplies a client for a named queue. BatchJobActor places a batch job on that queue, uses a timer and reminder to wake processing, and tracks dequeue attempts against the job's retry limit. The configured queue provider determines persistence, visibility, and failure behavior.

InMemoryMessageQueueProvider is process-local and is appropriate for tests or local evaluation. It does not give a durable, multi-silo queue. A serving deployment must choose a provider with the retention and retry semantics it needs and prove the worker lifecycle under process loss.

Retry boundaries

A retry can repeat a command or provider call after an uncertain outcome. Use stable operation IDs and the selected route's exact completion evidence for business commands. For external effects, the provider must enforce durable idempotency and return terminal receipts for known outcomes. Queue attempt count alone is not an exactly-once guarantee.

Use BatchJobActor only after reviewing its queue provider and error handling for your deployment.

Example: Add a queued item

A queue provider supplies a named typed client. The example only shows enqueueing; production durability and worker behavior come from the configured provider.

public static async Task Enqueue(IMessageQueueProvider queues) =>
    await queues.GetClient<string>("notifications").Add("hello", TimeSpan.FromDays(1));