Files
james.maesandClaude Fable 5.2 58051e7b99
maven / build (push) Successful in 11m29s
build / maven (push) Successful in 11m29s
fix(renderer): scene 2 core: the findings of the independent review
1. A length too long for any stock is a named refusal. Length.parse
   narrowed the micrometres to an int before it applied the 2 m limit, so
   "84600in" or "99999in" threw ArithmeticException: the opaque
   RENDER_FAILED, and an error instead of a REFUSED answer when collecting.
   The limit is now compared in long before narrowing, so it is
   SCENE_INVALID at the pointer of the length.

2. The printable area holds a box of its own size at every resolution. It
   was floor(far edge) less ceil(near margin), which can be one dot smaller
   than a box of the stated printable width: 100 mm stock with 3 mm margins
   and a 94 mm box fitted at 203 and 600 dpi and was refused at 300. It is
   now floor((W - L - R) x dpi) by floor((H - T - B) x dpi), the rounding of
   a box size, starting at ceil(L x dpi), ceil(T x dpi), moved back one dot
   where it would otherwise pass the page edge. New golden case `margins`
   with fractional-dot margins; the three existing goldens at 600 dpi are
   regenerated (the area grew by one dot each way; 203 and 300 unchanged).

3. The version 2 mutation campaign accepts only a Refusal (the package's
   own invariants are IllegalArgumentExceptions too) and renders about one
   input in four, reading the label back and comparing with validation. It
   found nothing at 20000 or 100000 iterations for either seed.

4. A refused answer carries no label bytes: with COLLECT and an error the
   answer had base64 of a label with elements missing. Scene2.render answers
   no label for a refused scene and the answer has no document fields. This
   changes the wire contract of section B.1 of the design, which records it.

5. One scene may paint sixteen times its printable area, an overlap counted
   each time, counted before any ink and in validation too. The element
   that would pass it is SCENE_INVALID with measured.paintedPercent against
   limit.paintedPercent 1600. 1000 fills of a 64 million dot canvas were
   8 GB of byte writes; the worst scene is now 128 MB.

6. The README states what changed in the version 1 answer envelope in
   0.2.0 (diagnostics on every answer; SCENE_INVALID with detail where
   unreadable JSON and a missing or unknown schema were RENDER_FAILED) and
   what the bridge must handle. The version 1 ZPL bytes are unchanged.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 10:59:20 -06:00
..

Isolated document renderer

This standalone Java CLI renders user-authored PDF layouts and typed ZPL label scenes. It has no QQQ classes, database access, storage credentials, HTTP service, or script broker. The application authorizes and supplies exact retained asset bytes and prepared JSON context. User templates must run in a separately qualified disposable sandbox; never add this renderer to the application JVM as an in-process fallback.

mvnw.cmd -B verify builds the CLI, runs Checkstyle and fixture tests, and copies runtime JARs into target/lib. target/qbit-document-renderer-0.1.0-SNAPSHOT.jar is the entry point. Java compilation targets 21 with selected warnings as errors. The container entry requires Java 21.0.13 and QQQ_RENDERER_MODE=container; the environment marker is only an accidental-use guard. It does not establish isolation. No renderer image or runtime is qualified yet; see qualification.json.

Source build

The PDF output dependency is a separately built, narrowly patched OpenHTML module under com.kingsrook.thirdparty:openhtmltopdf-pdfbox:<family revision> (upstream 1.1.105 + QQQ patch p1). Build it from the retained source into an isolated Maven repository before a local renderer build; use that same repository with -Dmaven.repo.local=.... See the source build instructions. Use clean verify when changing this dependency so target/lib cannot retain the old output-module JAR. Docker builds the source and runs its fifteen vendor regressions before compiling the renderer. Existing sealed image evidence does not qualify this new dependency; the exact-image background corpus must pass.

Protocol

One UTF-8 JSON object followed by a newline enters stdin, and one JSON response followed by a newline exits stdout. No worker connection is reused. The host must enforce deadline, cgroup limits, input/output bounds, cancellation, container ownership and durable cleanup. The request is limited to 16 MiB before parsing; duplicate keys, trailing JSON, overlong strings and excessive nesting are rejected.

{
  "protocol": "qbit-document-renderer/1",
  "requestId": "generation-attempt-id",
  "operation": "RENDER",
  "format": "PDF",
  "source": "<h1>${title}</h1>",
  "stock": {
    "widthMicrons": 101600, "heightMicrons": 152400,
    "topMicrons": 5000, "rightMicrons": 5000,
    "bottomMicrons": 5000, "leftMicrons": 5000, "dpi": 203
  },
  "context": { "title": "Packing slip" },
  "assets": [],
  "maximumBytes": 20971520
}

operation is RENDER, VALIDATE, or CATALOG. A catalog request needs only protocol, requestId and operation and returns versioned barcode IDs and typed option metadata. VALIDATE compiles PDF template syntax or checks the ZPL scene structure plus asset identity. It does not evaluate arbitrary context, certify future layout fit, or promise that every source option will render with every record. Production publication should also render representative fixtures inside the qualified boundary.

A successful render returns protocol, requestId, outcome: "OK", rendererVersion: "qqq-renderer-0.2.0", catalogVersion: "qqq-barcodes-9", mediaType, base64, SHA-256, decoded byte length, pageCount and diagnostics (a list, empty except for a version 2 scene). Validation returns no document bytes. Errors return outcome: "ERROR", code: "RENDER_FAILED"; no source/context or exception stack is included. A version 2 scene refusal returns its own code and one diagnostic as detail (see "ZPL scene 2").

Renderer 0.2.0 adds, all optional: "targetDpi" (203, 300 or 600; the resolution a version 2 scene is rendered at, by default the stock's dpi; a version 1 scene with a target other than its stock's dpi is refused as TARGET_REQUIRES_SCENE_2) and "diagnostics": "COLLECT" (keep every element's refusal instead of stopping at the first; the outcome is then REFUSED when there is at least one, and the answer carries the diagnostics and no document: no mediaType, base64, sha256, length or pageCount, so a host that looks for base64 without reading the outcome finds nothing to print). The operations INSPECT_ASSET and UPGRADE_SCENE are routed and answer UNSUPPORTED_OPERATION until their packages exist. A host bridge that accepts only qqq-renderer-0.1.0 does not accept these answers: upgrade the host library before the image. The host must independently check request identity, response shape, decoded size/hash, format policy, successful process termination and container removal. Worker-reported metadata is untrusted. An external parent must not persist raw stderr containing dependency diagnostics.

Compatibility of version 1 answers. The ZPL bytes of a version 1 scene are unchanged; the corpus in src/test/resources/compat-v1 holds them byte for byte. The answer envelope around them changed in two ways in 0.2.0, for a request a 0.1.0 host already sends. Every OK answer gains diagnostics: []: six fields for VALIDATE and eleven for RENDER, where there were five and ten. And a ZPL source that is not readable JSON, has no schema or has an unknown schema now answers code: "SCENE_INVALID" with a detail diagnostic (pointer "", or /schema), where 0.1.0 answered the opaque RENDER_FAILED. Every other version 1 refusal keeps its code. Nothing in a released host depended on RENDER_FAILED for those three cases: it is not a GenerationPorts.FailureCode, so bridges/renderer rejects such an answer as WORKER_ERROR_REJECTED, exactly as it rejects every 0.2.0 answer today (it accepts only qqq-renderer-0.1.0 and the exact 0.1.0 field counts). The bridge that accepts 0.2.0 must take the extra diagnostics field, detail on an error, the REFUSED outcome, and SCENE_INVALID and the other diagnostic codes as failure codes.

PDF authoring

PDF sources use FreeMarker 2.3.35 with enforced HTML autoescaping. Plain JSON objects, lists and scalars are the root model. Includes have no loader content, locale lookup is disabled, Java bean wrapping/API access and class construction are disabled. These are defense-in-depth settings; FreeMarker is not a hostile-code sandbox. Complex record/API logic belongs in the separate published TypeScript context script.

Layouts support the OpenHTMLtoPDF paged CSS model: physical stock sizes, margins, tables, repeating headers/footers, page breaks, absolute positioning, borders, images and retained TrueType fonts. This is a CSS 2.1-oriented print renderer, not a browser; flex/grid, JavaScript, SVG, OpenType/CFF fonts, interactive forms and active links are not supported. Every output page must match the stock's dimensions. Images and fonts are resolved exclusively from this invocation's manifest; unknown resources fail the job. CSS does not gain filesystem or network URL access.

<style>
  body { font-family: UserFont; font-size: 10pt; }
  table { width: 100%; border-collapse: collapse; }
  td { border: 1px solid #ccc; padding: 4mm; }
</style>
<h1>Order ${order.id}</h1>
<img src="asset:logo">
<table>
<#list items as item>
  <tr><td>${item.name}</td><td>${item.quantity}</td></tr>
</#list>
</table>
<qqq-barcode type="code128" value="${order.id}" scale="2" quiet="12"></qqq-barcode>

Barcode elements must be explicitly closed and empty; self-closing custom HTML tags can absorb following content and are rejected when that happens. Their dimensions are set from bitmap pixels and stock DPI, preserving integer module scale at the selected print resolution. Authors can position them but should not apply CSS transforms that distort bars. Optional options is a JSON object encoded as an HTML attribute, for example options='{"mode":"MICRO"}' for PDF417. Human-readable captions are ordinary author-controlled text.

Assets contain name, sha256, mediaType, and base64. Names are local identifiers, not paths. Allowed media are PNG, JPEG and TrueType (font/ttf). Fonts also require fontFamily and optionally fontWeight (100–900) and fontStyle (normal/italic). The host obtains bytes through authorized retained-file APIs, checks the pinned file version/hash, and supplies them offline. Font usage rights remain part of asset intake. Raw SVG, external fonts and image URLs are rejected.

ZPL authoring

ZPL sources are JSON scenes with schema qqq-zpl-scene/1, not raw ZPL templates. There is no raw-command escape hatch. Coordinates and sizes are integer printer dots, and stock DPI is 203, 300 or 600.

{
  "schema": "qqq-zpl-scene/1",
  "elements": [
    {"type":"text","x":20,"y":20,"width":12,"height":24,"valuePath":"/order/id"},
    {"type":"box","x":20,"y":60,"width":500,"height":2,"thickness":2},
    {"type":"image","x":20,"y":90,"asset":"logo"},
    {"type":"barcode","x":20,"y":150,"symbology":"qr","scale":4,"quiet":4,"value":"SHIPMENT-17"}
  ]
}

Text/barcodes require exactly one literal value or JSON Pointer valuePath; only scalar values are accepted. Barcode options is the same typed object as PDF. Boxes provide outlines or lines. Images print at their supplied pixel dimensions; preprocess retained assets to the intended printer resolution. Existing text uses the printer's font 0 with explicit width/height. The additive rasterText element renders dynamic record text using one exact retained TrueType face, without installing fonts on the printer or host:

{"type":"rasterText","x":20,"y":250,"fontAsset":"headingItalic","fontSize":32,"width":500,"height":120,"valuePath":"/record/customerName","align":"left","rotation":0,"threshold":128}

The fontAsset must name a supplied font/ttf asset. Choose the actual regular/bold/italic asset; this path does not synthesize a face or search installed fonts. All size and position units are integer printer dots. fontSize is 1–999. width and height are the unrotated layout box, each 1–4096 and at most 4,000,000 pixels together. rotation is clockwise 0, 90, 180 or 270; x/y locate the rotated box's top-left, and the complete final box must fit the stock. align is left, center or right; its default is left. Optional lineHeight is the baseline interval in dots (1–4096); omission uses the font's rounded-up line metrics. Small explicit intervals can intentionally overlap lines. Text automatically wraps using Java's supported shaping/bidirectional layout and the chosen physical face. Explicit LF starts a new line; other control characters and unpaired surrogates are rejected. There is no universal script/locale guarantee: missing glyphs are refused, and representative language/font fixtures remain required.

Text is limited to 1,024 UTF-8 bytes and 128 laid-out lines per element. Empty text yields a white box even at 1×1; spaces and explicit blank lines consume line metrics and must fit. Logical advance, line descent and actual shaped ink/pixel bounds are checked before drawing; overflow is an error, never truncation. Black antialiased glyphs on white are binarized using threshold (1–254, default128) before the existing graphic writer; no color commands are added. See the rasterText schema. Unknown properties on this element fail closed to catch misspelled layout controls.

Before any text font/raster allocation, the scene is bounded to 64 rasterText elements and 16,000,000 total unrotated raster pixels. Rendering additionally resolves all dynamic values and checks their combined 16 KiB UTF-8 limit before any such allocation. VALIDATE checks static layout/assets and literal text but cannot certify dynamic values, glyph coverage or future fit; render representative record fixtures before publication. Decoded fonts are cached only within one invocation. The new path requires a renderer image containing this implementation; sealed catalog4 image evidence predates it and does not qualify the addition.

Only ^XA, ^XZ, ^PW, ^LL, ^LH, ^CI28, ^FO, ^A0N, ^FH_, ^FD, ^FS, ^GB and ^GFA are generated. Text is fully hex-encoded UTF-8, so ^, ~ and _ in record values cannot become new commands. Barcode/image raster fields use fixed uppercase hex and split below the 99,999-byte field limit. Placement uses overflow-safe bounds checks. No stored formats, downloads, network commands, persistent settings, cuts or resets are emitted. The printing boundary still needs independent output grammar enforcement because a compromised worker must not be trusted to report safe printer bytes.

ZPL scene 2

A source with schema qqq-zpl-scene/2 is a layout in physical units that renders at 203, 300 or 600 dpi. The worker chooses the code path from schema alone: version 1 is unchanged and frozen, and any other source is refused as SCENE_INVALID. The schema is schema/zpl-scene-2.schema.json; the design is docs/design/LABEL-LAYOUT-FONTS-PREVIEW.md.

{
  "schema": "qqq-zpl-scene/2",
  "design": { "width": "4in", "height": "1in" },
  "elements": [
    { "id": "frame", "type": "box", "thickness": "0.5pt" },
    { "id": "panel", "type": "group", "anchor": "center", "width": "50%", "height": "60%", "children": [
      { "id": "mark", "type": "box", "anchor": "bottom-right", "x": "1mm", "y": "1mm", "width": "6mm", "height": "3mm", "fill": true } ] },
    { "id": "rule", "type": "box", "anchor": "bottom-center", "y": "2mm", "width": "80%", "height": "0.2mm", "thickness": "0.2mm" }
  ],
  "overrides": [ { "when": { "dpi": [203] }, "set": { "frame": { "thickness": "1dot" } } } ]
}
  • Lengths are strings of a number (up to three decimals) and a unit: mm, in, pt (1/72 in), % (of the container's width for x and width, of its height for y and height) and dot. The most a length may be is 2 m (2000mm, 78.74in, 5669.292pt), 32000dot or 100%; anything longer, up to the largest number the syntax can write, is SCENE_INVALID at its pointer. A physical length becomes whole micrometres, then dots at the render target: a position to the nearest dot, a box width or height rounded down, a thickness to the nearest dot and never less than one. A dot length outside an override raises the warning DEVICE_UNIT_USED.
  • Coordinates start at the top left of the printable area, the stock less its margins. In dots the printable area is floor((width - left - right) x dpi) wide and floor((height - top - bottom) x dpi) high, which is how a box size is rounded, and it starts at ceil(left x dpi), ceil(top x dpi), moved back by one dot where it would otherwise pass the page edge. So a box of exactly the printable width and height fits at 203, 300 and 600 dpi alike. No ink is ever a whole dot inside a margin; the right and bottom edges may pass theirs by a fraction of a dot (less than 0.125 mm at 203 dpi). design states the stock the layout was drawn for; the request's stock must match it within 0.5 mm on each side (STOCK_MISMATCH).
  • Every element has a unique id ([A-Za-z][A-Za-z0-9_-]{0,31}), a type, an anchor (one of nine points, default top-left: the same point of the box is placed on that point of its container), x and y (distances inward from the anchored edge; on a centred axis a shift that may be negative), width and height (omitted: the rest of the container), and align and valign (where content sits in the box).
  • box has thickness and optional fill; a line is a box whose width or height is its thickness. group has children, placed relative to its box; groups nest four deep. A scene holds at most 1000 elements, and its elements may paint at most sixteen times its printable area in all, an overlap counted each time: a filled box counts its area, an outline its four bars, a group nothing. The element that would pass that is refused as SCENE_INVALID at its pointer, with its box and measured.paintedPercent against limit.paintedPercent of 1600. A real label paints less than twice its area; the limit holds the worst scene to sixteen fills of the canvas where 1000 were possible.
  • text, barcode and image are parsed and placed by renderer 0.2.0 and then refused as RENDERER_TOO_OLD, with the box they would have had, until their packages are in the renderer.
  • overrides replace properties of declared elements at the listed resolutions and are the only place a scene may depend on resolution. They are checked for all three resolutions whatever the request's target. samples are accepted and ignored by rendering.
  • Output. The whole label is composed on one 1-bit canvas and emitted as uncompressed ^GFA fields: rows are cut into bands wherever eight or more blank rows separate ink, each band is trimmed to its inked columns, and a band is continued in a further field at 99,999 bytes. Only ^XA, ^PW, ^LL, ^LH, ^CI28, ^FO, ^GFA, ^FS and ^XZ are emitted.
  • Diagnostics. A refusal is one diagnostic: code, severity, the element id, the element's box in dots from the top left of the printable area, and measured and limit as named integers. SCENE_INVALID also carries pointer, the JSON pointer of the offending place. A diagnostic names only an id the scene declares and points only through schema property names, array indexes and declared ids, so no record value, sample or unknown property name can leave the worker in one. A stock the printer language cannot address stays the opaque RENDER_FAILED, as for version 1.
{ "code": "ELEMENT_OUTSIDE_PRINTABLE_AREA", "severity": "ERROR", "element": "mark", "box": [719, 0, 79, 39],
  "measured": { "bottomDots": 39, "leftDots": 719, "rightDots": 798, "topDots": 0 },
  "limit": { "bottomDots": 155, "leftDots": 0, "rightDots": 764, "topDots": 0 } }

Limits

Sources: 262,144 characters. Context: depth 16, 10,000 nodes, 65,536 characters per string, 262,144 aggregate text characters. Stock: 1 mm–2 m, valid margins, 72–1200 DPI (ZPL additionally bounds width to 9,999 dots and height to 32,000). Assets: 100 entries, 2 MiB each, 8 MiB aggregate; image dimensions ≤4096 and ≤4 million pixels. Expanded HTML: 2 million characters and 20,000 elements. PDF pages: 1–500, checked after rendering. Output: caller limit, hard maximum 100 MiB; normal host default is 20 MiB. ZPL: 1,000 elements; a version 2 scene paints at most 16 times its printable area. Barcodes: 4,000-character payload, scale 1–16, bounded quiet zones, ≤4 million pixels.

The PDF engine and font/image decoders can consume resources before post-render limits fire. A qualified container's independent CPU/memory/PID/wall limits remain mandatory for both validation and rendering. These ceilings are not performance guarantees; load testing and font/locale/large-batch qualification remain outstanding.

Barcode coverage

Catalog qqq-barcodes-9 offers 71 stable IDs: the 47 concrete OkapiBarcode 0.5.7 encoder families plus Han Xin, rMQR, DotCode and Ultracode through the pinned Zint 2.16.0 provider, and the attributed Code 93i and Co-op 2 of 5 encoders. This is a finite explicit catalog, not a claim to encode every standard. See BARCODES.md and the CATALOG response for modes and typed options; physical fitting (BARCODE-FIT.md) covers 13 default-option profiles and every other ID reports fit unsupported. Every family has a pinned upstream codeword/pattern vector and raster test; common variants also have independent ZXing decoding. A 4×6 PDF QR fixture is decoded after rasterization at 203 DPI.

This coverage means all encoder families in the pinned library, not every symbology ever invented or every possible library option. Physical verification on actual printers/scanners, carrier/GS1 application rules, grading and every mode/option combination remain separate qualification work. No equivalence substitution occurs for unsupported IDs.