qbit-document-generation/renderer/ZINT-QUALIFICATION.md

Catalog v4 publication profiles — 2026-10-31 03:55 CDT

88 tests, zero failures/errors/skips and Checkstyle pass in publication-profile-verification.log. ISSN and modern ISMN add checked profiles using the existing Okapi EAN13 carrier; the native executable, patchset, Docker inputs and process boundary are unchanged. Independent ZXing decoding covers four agency/derived/synthetic cases at scales 1/3/8; every case also passes exact PDF embedded-image and ZPL raster equality, with quiet-zone and original-checksum refusal checks. The shared final-image driver adds eight publication format paths and two invalid identifier cases. Exact catalog v4 image execution is pending. The first failed fixture gate is retained separately: the GS1 web example has an invalid original ISSN check digit; strict validation was kept and fixture provenance corrected explicitly. No production or physical scan claim follows.

The optional renderer bridge passes 23 tests and Checkstyle at 03:56:07 (bridges/renderer/publication-profile-verification.log), without installation. Local renderer JAR SHA-256: 384ADC154DF837475EA91F02FE6A16F8FEA04504655E6048A24DAD939755B561. The final-image input bundle must also include the new barcodes/publication-vectors.json resource; the driver class remains com.kingsrook.qbits.renderer.ZintImageQualification.

Catalog v3's actual image gate is sealed at qbit-documents/artifacts/renderer-catalog3-20261031-0342: 85 Linux tests, 45 native reference renders / 15 families, 30 general + 4 numeric + 6 semantic format paths, 9 additional refusals; p50/p95/max 6/66/132ms under one CPU. That historical artifact remains unchanged.

Historical v3 source gate

Catalog v3 six-family extension — current source snapshot

The current source gate passes 85 tests, zero failures/errors/skips and Checkstyle (zint-six-source-verification.log, 2026-10-31 03:36:15). The native patchset remains exactly zint-2.16.0-qqq-p1; no C source, build inputs, native options or runtime dependency changed for the additional six IDs. Catalog v3 exposes 66 IDs. Its exact-image gate subsequently passed and is sealed at qbit-documents/artifacts/renderer-catalog3-20261031-0342.

The qualification launcher now contains 15 pinned upstream family vectors at three scales (45 renders), 30 general PDF/ZPL pixel paths, the six numeric DotCode codeword cases and their four format paths, four UTF-8 cases, plus six additional semantic format paths for leading/trailing-zero Flattermarken, tracker-only DAFT and DX half-frame input. It also checks all FIM letters and nine new family/refusal cases. Full-area track and module-origin sampling prevents silent cropping. The 020/T patterns are explicitly locally derived semantic fixtures, not mislabelled upstream grids. Native backend height defaults are used; these tests do not establish carrier approval or physical print grading.

The sealed nine-family p1 candidate is historical evidence in qbit-documents/artifacts/renderer-zint-p1-20261031-0326. That exact image passed all 27 original vectors, 6 numeric DotCode cases, 4 UTF-8 cases, 22 PDF/ZPL paths; p50/p95/max were 7/79/133ms under one CPU. Its 48-request baseline passed at 97 PDF/min and 180 ZPL/min at concurrency4 for the recorded fixtures, not an SLA. The sealed artifact is unchanged; a later catalog's support claim requires its own exact image and the expanded driver.

Historical first-tranche procedure

Nine additional barcode IDs: qualification procedure

Source gate: zint-source-verification.log, 2026-10-31 03:01, 82 tests passed, zero failures/errors/skips, Checkstyle clean. The ordinary source gate includes 12 new host-independent tests; it does not run the native Zint executable.

The patched zint-2.16.0-qqq-p1 image and provider are pending qualification. No support claim should be inferred from a catalog registration or executable-presence flag.

Build the current Dockerfile using explicit approved immutable BUILD_IMAGE and JAVA_IMAGE arguments. Root owns that privileged image build and vulnerability review. The archive hash is checked before compilation; package/compiler/CMake versions, linkage and executable hash are retained with full corresponding source. The Java source gate also runs during the Maven build stage. The build applies only hash-checked, exact-preimage/postimage patches described in vendor/PATCHES.md; the original and applied source plus all patch/license records accompany it.

After building, mount only the compiled trusted test classes/resources from renderer/target/test-classes read-only at /qualification. Run the exact image digest with network disabled, a read-only root, non-root uid 65532, dropped capabilities, no-new-privileges, pids 64, memory 512 MiB, one CPU, and a bounded tmpfs at /tmp; override its entry point to:

java -Xmx256m -XX:ActiveProcessorCount=1 -Djava.awt.headless=true
  -Dpdfbox.fontcache=/tmp
  -cp /renderer/renderer.jar:/renderer/lib/*:/qualification
  com.kingsrook.qbits.renderer.ZintImageQualification

The launcher has no JUnit dependency and takes no user-controlled arguments. It uses public fixture payloads only. It compares all nine upstream full-module vectors at 2, 4, 8 pixels per module (27 reference renders), exercises each through both PDF and ZPL (extracting and comparing each embedded image/graphic pixel), checks four nondefault-Unicode payloads with explicit UTF-8 ECI, and rejects representative invalid postal/checksum/GS1 payloads, and prints aggregate latency only. DotCode center samples match the reference matrix and a corner test distinguishes native circular dots from scaled squares. Mailmark's three track states are sampled separately. The 27-run baseline gates p95 at ≤1000 ms and maximum at ≤2000 ms; retain actual p50/p95/max and CPU/image details. Those small-fixture timings are not a production throughput promise. Renderer startup, PDF layout and container scheduling have separate measurements/budgets.

Archive the command, image digest, stdout, exit code and build provenance. If any vector/geometry fails, diagnose it before changing expected values; the fixture files must retain their upstream source identity. This trusted-fixture run does not establish hostile-input containment. Existing runsc/runtime/operator qualification, kill/reaper tests and production storage/printing gates remain.

Runtime limits remain independent of the fixture driver: fixed executable and allowlisted argv, UTF-8 stdin ≤16000 bytes, each subprocess ≤2 s plus 250 ms kill wait, stdout ≤524350 bytes, no collected stderr, monochrome BMP checks before allocation, dimensions ≤4096 and area ≤4 million pixels. The parent sandbox's whole-document deadline/resource limits cover cumulative work and native allocation. No per-barcode deadline resets or subprocess limits imply unbounded document execution is allowed.

Patchset p1 regression delta

The exact-image launcher additionally checks six trusted verbose codeword cases: plain DotCode 00 and 12 at default, 13 and 200 columns. Expected non-GS1 prefix 107 is mandatory; the expected payload word is 0 or 12, and padding is 106. 00 expectations are from reviewed upstream commit evidence; 12 is explicitly a locally derived regression. The API does not expose verbose mode. Both payloads also render normally and take four additional PDF/ZPL exact-pixel paths. The first unmodified image's 27-vector/18-format/4-Unicode pass and p50=4ms, p95=68ms/max134ms are historical only; repeat all gates on the patched image.