qbit-document-generation/renderer/BARCODE-FIT.md

Worker barcode fitting and scanner fidelity

Catalog qqq-barcodes-9, fit profile qqq-barcode-fit/1. This is a new source candidate; the current deployed catalog-8 image is unchanged. Matching bridge, full source gate and exact new-image qualification are required before adoption.

Finite capability

Fit is supported for the default encoder profiles of code128, code39, code93, itf, gs1-128, qr, ean13, ean8, upca, upce, datamatrix, pdf417 and aztec. Both PDF and ZPL use actual encoder rasters. The other 58 catalog IDs explicitly advertise fit.supported=false. This does not redefine the wider barcode requirement as completed.

Options must be absent or {}; binary payloads, structured append, color, ECI and option-dependent geometry are not fit-qualified. Existing explicit non-fit APIs retain their capabilities. Canonical gs1-128 accepts the existing explicit GS1 syntax; scanner GS1 modes are deliberately not inferred from ordinary text or a family name.

The worker encodes at module scale 1, including the requested quiet zones once. It floors microns * stock.dpi / 25400 to obtain the inside box in dots, chooses the greatest integer scale 1..16 within both box axes and existing 4096-axis/four-million-pixel budgets, then encodes again at that scale. It checks exact proportional dimensions. It never stretches a bitmap or crops quiet zones. Default linear bar height is preserved proportionally; arbitrary bar-height or dot-family scaling is outside this first profile. Too small means even scale 1 does not fit.

quiet is modules on each side: 4..64 for QR/Data Matrix/PDF417/Aztec, 10..64 for the other fit profiles. Box dimensions are positive integer microns within the immutable stock's printable area. PDF uses that same stock DPI for image-to-point conversion; it is not hardcoded to 300 DPI. ZPL supports 203/300/600 DPI and also checks the positioned box against printable margins, with inward edge rounding. In PDF, the layout still determines image position; authors must place the fitted image within their page layout. A fit box does not authorize arbitrary CSS offsets or certify final physical device behavior.

Scanner contract for Echo

The trusted scanner-facing service must verify the original scan and configured decoder profile before selecting these renderer inputs. Client-supplied strings are not scanner configuration attestation. Preserve original decoded text, raw bytes/encoding where supplied, exact EMDK label, AIM identifier/modifier, GS1 mode and the identity/version of the trusted decoder configuration in the owning application's record. Pass only the verified compatible profile below. Do not strip separators, leading zeros, prefix/suffix, check digits or FNC indicators to make a value fit.

The renderer accepts exact labels below, optionally prefixed with LABEL-TYPE-. Case, type and AIM modifier must match. Initial scanner payloads are unmodified printable ASCII. The trusted scanner profile must disable transformations, injected prefix/suffix, Code39 full-ASCII expansion/check-digit removal, I2of5 check-digit removal, UPC/EAN conversion and supplemental combination. A scanner that cannot establish those settings is unsupported by this profile.

EMDK label	Renderer type	Required AIM	Additional payload requirement
CODE128	code128	]C0	No FNC interpretation or GS1
CODE39	code39	]A0	Basic uppercase alphabet, no start/stop *
CODE93	code93	]G0	Printable ASCII
I2OF5	itf	]I0	Even number of decimal digits, leading zeros retained
QRCODE	qr	]Q1	Plain mode, no ECI/FNC1
DATAMATRIX	datamatrix	]d1	Plain mode, no ECI/FNC1
PDF417	pdf417	]L0	Plain mode, no ECI/GS1
AZTEC	aztec	]z0	Plain mode, no ECI/GS1
EAN13	ean13	]E0	All 13 digits, including valid check digit
EAN8	ean8	]E4	All 8 digits, including valid check digit
UPCA	upca	]E0	All 12 digits, including valid check digit
UPCE0	upce	]E0	Number system 0, all 8 digits including check digit

EAN/UPC check digits are validated with the existing encoder before extracting its required data-digit argument. The stored scan value remains unchanged; independently decoded output must match the complete original. Wrong or missing checksum is a refusal. UPC-E number system 1, GS1 aliases (including EAN128), GS1 QR/Data Matrix, other AIM modifiers, Unicode/invalid bytes, control separators, and FNC escape-looking text are unsupported scanner inputs, not substituted symbols.

Primary label/API references: Zebra ScanDataCollection and Zebra ScanData. Zebra distinguishes raw data from the UTF-8 string accessor; neither accessor proves the decoder's configuration. The finite AIM matrix above is additionally checked against actual Okapi 0.5.7 output decoded independently by ZXing 3.5.4, including exact application text and reported symbology identifier. This caught EAN-8's ]E4 distinction. This is software known-answer evidence, not device/AIM certification or proof that an arbitrary scanner supplied trustworthy metadata.

Existing scene entry points

PDF FreeMarker/HTML (dynamic values are escaped by the existing template engine):

<qqq-barcode type="${barcode.type}" value="${barcode.value}"
  scannerSymbology="${barcode.label}" aimIdentifier="${barcode.aim}"
  fit="box" widthMicrons="90000" heightMicrons="50000" quiet="10"></qqq-barcode>

Omit both scanner attributes for canonical, explicitly authored renderer data. scale cannot be combined with fit. PDF type was already dynamic; this introduces no host or Android encoder.

ZPL JSON scene uses a template-owned finite type allowlist:

{"schema":"qqq-zpl-scene/1","elements":[{
  "type":"barcode","symbologyPath":"/barcode/type",
  "allowedSymbologies":["code128","qr","ean13"],
  "valuePath":"/barcode/value","scannerSymbologyPath":"/barcode/label",
  "aimIdentifierPath":"/barcode/aim","x":0,"y":0,"quiet":10,
  "fit":{"widthMicrons":90000,"heightMicrons":50000}
}]}

Static symbology remains supported. Dynamic type requires fit and an allowlist; missing, non-string or unlisted values refuse. Scanner paths are optional as a pair. For canonical GS1 use explicit gs1-128, its existing validated syntax, and no plain-scanner wrapper.

Worker geometry operation

The existing isolated one-request protocol additionally accepts FIT_BARCODE with format, the normal exact stock, and barcode containing exactly symbology, value, quiet, widthMicrons, heightMicrons; optional scanner mode adds exactly scannerSymbology and aimIdentifier. It returns fit with profile, scale, quietModules, minimumWidthDots/minimumHeightDots and widthDots/heightDots. This exposes geometry only, no image or user payload. No host rendering library or new web route is introduced; ordinary Generation consumes embedded fit via its existing render port.

The worker error envelope exposes only a fixed allowlist of fit/scanner refusal codes, including BARCODE_FIT_TOO_SMALL, BARCODE_FIT_UNSUPPORTED, BARCODE_FIT_BOX_OUTSIDE_STOCK and SCANNER_BARCODE_PROFILE_UNSUPPORTED; unknown encoder errors remain RENDER_FAILED. Errors bind protocol, request ID, renderer version and catalog9. The paired bridge accepts exactly that six-field shape and maps only the closed GenerationPorts.FailureCode enum to GenerationPorts.RenderException; malformed, unknown or wrong-version errors stay generic. No arbitrary worker message, cause or source data is forwarded. The new foundation/bridge source cohort still requires its coordinated gate. Successful documents retain the same digest, media, size, stock and ZPL grammar verification.

Evidence and remaining gates

Latest full renderer clean verify passes 164 tests, zero failures/errors/skips and Checkstyle zero (qbit-scripting/target/renderer-barcode-fit-edge-full-verification.log, terminal74912). The preceding162-test gate remains historical in renderer-barcode-fit-full-fixed-verification.log. Fourteen fit tests include independent decodes of all 13 canonical profiles and all 12 scanner profiles, QR 29-by-29 natural geometry, entry-point scanner checks, safe error vocabulary, and 78 exact PDF/ZPL paths at three DPIs. New direct cases cover fractional-dot margins at first/last valid positions and one-dot-outside refusals, axis4096 and area4M binding limits, and standalone measurement's matching ZPL stock limits. PDF checks cover embedded pixels/interpolation/physical size; ZPL checks cover each bounded graphic strip's position, declared sizes, every pixel and white padding. Earlier fixture failures (PDF_417 enum spelling, EAN-8 AIM expectation, single-strip assumption for a correctly split large ZPL raster) remain in separate logs. Production was not weakened to satisfy them.

The prior bridge test gate passed 28 tests and Checkstyle zero (renderer-barcode-fit-bridge-tests.log, terminal53691), against cached foundation SHA256 30059991C0A1D652A88C00D51EBD9D0B8A8CB0688EA9A987E104D01D0D79C7D0. It proved exact forwarding, packaged contract and rejection of catalog8. The subsequent typed-error delta adds two tests (expected30), including all12 codes in render/validate and malformed/unknown refusal, and awaits the new foundation source-reactor gate. No host encoding was added. Clean/package was blocked by an existing Windows-locked bridge JAR and remains a separate adoption gate; no consumer was stopped and no installed artifact replaced.

The existing final-image launcher now calls BarcodeFitImageQualification.verify(); its class and existing UltracodeImageQualification inspector must accompany the exact trusted native fixture snapshot. Independent review, new bridge packaging and exact image corpus remain pending. No physical printing, scanner acceptance, performance SLA, hostile-workload isolation or production deployment is claimed.