Add background work without bootstrap side effects

Candidate lease/module APIs have not been adopted by this KB. Use returned authority, dedicated queues and controlled drain/restart. See atomic handoff and module guards.

Steps

Select an explicitly supported queue/scheduler adapter and register application job handlers. Run workers/schedulers from their documented operator entry points, never by starting processes while composing a web request.

validated use case → transactional outbox when needed
                  → queue adapter → registered job handler
                  → explicit completion/retry/failure policy

Read Queue and scheduler and CLI operations for supplied commands and ownership. Copied neutral migration/console examples in this app are not active KB capabilities.

Verify

Test the job in isolation, then verify lease/retry/idempotency boundaries on disposable state. An unknown external side effect is not proof that a retry is safe.

Candidate ownership and recovery contract

For 0.2.0-rc.1 direct store consumers, QueueStore::claim() returns jobs whose workerId() is a fresh opaque claim token. OutboxStore::claim() returns messages whose reservationOwner() is the corresponding token. Use the returned authority for heartbeat/completion/failure or terminal transitions, never the process label passed into claim(). An expired or lost lease cannot authorize completion.

QueueWorker/OutboxDispatcher own their documented transitions; prefer those mechanisms over hand-written loops. Stop intake, drain or reconcile the old workers, then start compatible replacements when changing ownership semantics or advisory-lock names. Do not run incompatible old/new workers together. Hold UNKNOWN external effects for evidence-led reconciliation; arbitrary exceptions or expired sends are not definitely-safe retry results.

Real isolated SQL/process/signal drills are supplied evidence, not installed supervisors, HA or exactly-once delivery. The opt-in database webhook handoff now has scoped local MySQL proof for INT-09/10. It requires one injected connection for receipt/outbox changes, its optional schema, private payload storage and explicit queue/processor composition. The legacy split receiver is not made atomic by installing the candidate. See atomic webhook adoption, qualification profile and maintenance. No worker is activated in the KB.

For optional jobs, adopt ModuleQueueWorker and an application-owned closed module-to-dedicated-queue mapping. Reject disabled or unavailable modules before claiming work; do not construct their providers during bootstrap. ModuleCommand, ModuleScheduleTask and guarded services also need explicit wiring. A module snapshot does not hot-reload inside a long-running worker. See module activation for guards, drain/restart and permission boundaries. These are candidate recipes, not active KB workers.

Editorial provenance

Source: resources/guides/background-work.md. Source SHA-256: 5bc057716adc62fd002262828c1192219e55e5e8e4a1d4b950b917a7dd501d4a.

Knowledge-base application source; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.