qbit-document-generation/docs/JOBS.md

# Optional background jobs

Install and configure QQQ's existing durable Jobs kernel and Document Generation, then call `GenerationJobs.register(instance)` before instance enrichment/validation. This registers `document_generation_drain_queue` and the generation queue's **Run queued documents in background** action. `GenerationJobs.launch(queueId)` is the corresponding Java entry point. A disabled kernel refuses launch. This QBit starts no threads, creates no second scheduler and writes no Jobs tables directly.

The kernel launches under the current signed-in actor and restores its current authorized session through its existing JobSessions machinery. Its access-token/channel restrictions apply. The generation queue independently checks actor ownership, source permissions, client-channel and credential ceilings, global admission, pinned revision and per-record lease before effects. The runner currently uses the native queue defaults: one active invocation and a300-second lease; a queue store already configured with another policy refuses that mismatch. Launch requests themselves are not deduplicated; duplicate jobs share the same domain queue and cannot reclaim completed or uncertain items.

One backend step processes at most `maximumBatch` untouched items, checks cooperative pause/cancel/drain/lease state between items and before rendering, retention and printing, and examines at most20 pages of50 results. A cancellation that arrives during a bounded external call takes effect at the next boundary; it cannot undo a previously issued capability or accepted print job. Any uncertain attempted item remains RECONCILIATION_REQUIRED. Untouched items remain available for a later authorized drain. Partial failures/cancellations make the job fail visibly instead of claiming the whole batch succeeded. Per-record details remain in the generation queue.

The process declares Jobs idempotency NONE. Host failure therefore requires review through the existing kernel; this is not an exactly-once claim for external systems. A separate trusted termination verifier remains required before releasing an abandoned generation admission reservation. Kernel lease expiry alone is not proof that a renderer, intake or print request stopped. Known retained versions can be reconciled; unknown owner intake still cannot be automatically declared absent.

Generation ITEM state PRINT_QUEUED is terminal for generation. It is deliberately distinct from an untouched ITEM QUEUED, while its corresponding generation REQUEST remains QUEUED for accepted print dispatch. Neither state attests that paper was printed.

Verification distinguishes fixed trusted fixtures from deployment qualification. Tests exercise actual public core launch persistence without starting a job runtime, real file-H2 generation transactions, actor/source denial, repeated drains, print-terminal behavior and cancellation after rendering/before intake. The application must separately qualify the configured core job host, reauthentication module, production database/volume, isolated workers, cancellation latency and aggregate resource capacity. No production runtime or worker was deployed by these tests.