Background work
Decide when product work needs a queue, worker, or scheduled execution model.
Background work decision
The v1 buyer product has no generic worker, queue, scheduler, or durable job system. This is a deliberate support and security boundary, not an unfinished Cloudflare example.
The historical Cloudflare/Gemini document processor was removed because it had no Better Auth authorization handoff, application-owned job state, replay/idempotency contract, cost limit, complete failure recovery, zero-key local path, or end-to-end deployment proof.
What exists
- synchronous Bun/Hono request handling with a 30-second application timeout;
- transactional Postgres writes;
- signed provider webhooks processed synchronously;
- best-effort post-commit billing notification dispatch;
- deployment/platform operations outside the application, such as Postgres backups.
An unawaited notification promise is not durable background infrastructure. It is explicitly non-critical and can be lost if the process exits.
What does not exist
- a queue client or broker;
- worker deployment/package;
- job, attempt, retry, or dead-letter tables;
- a shared worker JWT/secret;
- scheduled application cleanup;
- durable AI processing;
- a queue dashboard or operational purge/replay path.
Do not restore removed code from Git history or describe provider-side asynchronous APIs as an application job system.
Decision matrix
| Job requirement | v1 decision |
|---|---|
| bounded work required to form the HTTP response | perform synchronously with timeout/idempotency |
| optional notification after committed state | best effort only; document possible loss |
| can be deferred without breaking validated buyer outcome | defer or remove from v1 |
| long-running/retryable/costly work required for user outcome | unsupported until product-specific design proof |
| repeated validated job across real products | investigate the smallest durable executor |
The word “AI,” “cron,” or “background” in a PRD is not sufficient evidence for infrastructure.
Re-entry bar
A product-specific executor may be investigated only after a real job defines:
- Better Auth-to-executor authorization with purpose, audience, owner/subject, short expiry or server-side claim, and replay behavior;
- application-owned job identity and persisted state machine;
- idempotency key and duplicate-provider-effect handling;
- bounded attempts, retry/backoff, terminal failure, dead letter, and user-visible recovery;
- input type/size, concurrency, provider spend, and abuse limits;
- retention, deletion, cleanup, and product-data ownership;
- zero-key local disabled/fake behavior;
- deployment owner, health/readiness, logs/metrics/alerts, rollback, and incident procedure;
- one complete deployed smoke from authenticated request through terminal success/failure;
- measured support and infrastructure cost that the validated outcome justifies.
Write a new ADR before implementation. One approved job does not justify selling a generic queue.
Security constraints
- Never pass a Better Auth cookie or long-lived universal secret to an executor.
- Never use a provider task ID as application ownership.
- Persist authorization and intended state before external work.
- Never put customer payloads, credentials, or signed URLs into queue names or evidence.
- Required work cannot rely on an in-memory map, timer, or unawaited promise.
- Cleanup must be bounded, observable, retryable, and owner-safe.
- A queue purge is destructive incident action, not routine recovery.
Buyer response to a background-work PRD
Consult the optional Decide background work playbook. The valid outcomes are:
- supported synchronous work;
- defer/re-scope;
- unsupported in v1;
- approved product-specific design investigation.
For the first three outcomes, do not add dependencies, environment variables, deployments, or commercial claims. For an approved investigation, the ADR and evidence above precede code.
The authoritative removal decision is docs/decisions/0001-exclude-background-worker-from-v1.md.