qbit-document-generation/renderer/PERFORMANCE.md

# Renderer baseline

Measured on October 30, 2026 using Java 21.0.12.1, Windows 11, 48 reported logical processors and a 512 MiB Java heap. These are trusted synthetic fixture measurements of the rendering engine in one process. They are **not production throughput**, a sandbox qualification, a peak workload commitment or authorization to reuse a worker across untrusted requests.

Each scenario warms four times, then renders 256 documents sequentially and another 256 with four threads. Each task validates its input; every PDF is reopened with PDFBox and each ZPL result has framing, size and barcode raster checks. Render latency excludes output verification; wall throughput includes it. The workload is small, the sample is finite, and the machine was shared with other build work. These results are an initial baseline, not a service-level objective.

| Trusted fixture | Threads | Documents/second | p50 render ms | p95 render ms |
| --- | ---: | ---: | ---: | ---: |
| Letter packing slip, 20 table rows and Code128 | 1 | 54.1 | 17.8 | 23.7 |
| Letter packing slip, 20 table rows and Code128 | 4 | 148.1 | 24.5 | 42.1 |
| 4 × 6 inch PDF shipping label with QR | 1 | 84.6 | 11.3 | 15.4 |
| 4 × 6 inch PDF shipping label with QR | 4 | 217.8 | 17.8 | 24.0 |
| 4 × 6 inch ZPL text and QR raster, 203 DPI | 1 | 1164.2 | 0.8 | 1.1 |
| 4 × 6 inch ZPL text and QR raster, 203 DPI | 4 | 1269.3 | 2.4 | 7.9 |

The first packing-slip render in the fresh Java process took **1485.6 ms** before warmup. This excludes Java process startup. Later scenarios share initialized libraries, so their first-render timings are not independent cold-start measurements. The production boundary uses disposable isolated invocations; warmed multi-render numbers therefore cannot be used to size the production service. Actual worker startup and termination may dominate small documents.

Reproduce from this directory, after the normal renderer build has populated `target/lib`:

```powershell
.\mvnw.cmd test-compile
java '-Xmx512m' '-Djava.awt.headless=true' '-Dpdfbox.fontcache=target' -cp 'target/test-classes;target/classes;target/lib/*' com.kingsrook.qbits.renderer.RendererBaseline 256
```

The explicitly invoked test-source main is not part of the renderer runtime artifact or normal test execution. It accepts 8–500 measured documents per scenario/parallelism and uses only embedded trusted fixtures. Evidence and sample PDFs/ZPL are written under `target/performance-baseline/`; `results.json` includes timestamp, exact sample hashes, environment, counts and latency definitions. A committed copy of this measurement is in `benchmarks/2026-10-30-engine-baseline.json`.

Release qualification must measure cold isolated invocations, cancellation and reaper recovery, memory/process/file limits, TypeScript context loading, authorized asset reads, strict audit, retained storage, durable batch scheduling and printer handoff. Include long tables, large authorized images/fonts, barcode density, mixed tenants, concurrent failure/retry, queue saturation and restart recovery. Establish an explicit target with the host capacity and workload rather than extrapolating from this engine baseline.