build(renderer): build the engine and service images from a released version

Both Dockerfiles copied 0.1.0-SNAPSHOT jars that the reactor no longer produces (version is ${revision}), so neither built a released version. They now resolve the released qbit-document-renderer and qqq-remote-renderer-transport (and their runtime libraries) at an exact, required RENDERER_VERSION / TRANSPORT_VERSION from the QRun-IO Gitea Maven registry and Maven Central, refusing SNAPSHOT and local (*forge*) versions. The reviewed hardening is unchanged: digest-pinned BUILD_IMAGE/JAVA_IMAGE, non-root 65532, read-only-root friendly, Zint built from vendor/. The reactor build context is no longer needed. Adds IMAGE-PUBLISH.md (repeatable build/scan/publish steps and the 1.0.0 pins) and image-pins.sh (prints the gg-forge-cd classpath and SHA256 pins from a published image). Images for 1.0.0 were built, smoke-tested over mTLS and published to GHCR under gg-engineering by hand; no workflow publishes images. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Bump version to 1.2.0-SNAPSHOT [skip ci]
2026-11-08 20:07:14 -06:00 · 2026-11-07 19:19:02 +00:00 · 2026-11-07 19:07:22 +00:00 · 2026-11-07 18:59:59 +00:00 · 2026-11-07 18:59:01 +00:00 · 2026-11-06 23:35:57 +00:00
20 changed files with 307 additions and 45 deletions
@@ -3,5 +3,5 @@ on:
  push:
 jobs:
  maven:
-    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@main
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@v1
    secrets: inherit
@@ -1,6 +1,6 @@
 # QBit Document Generation

-> **Paused, unreleased work in progress — 2026-11-04.** Implementation has stopped apart from the scoped definition-rename addition of 2026-11-06 (see [status](docs/RELEASE-STATUS.md)). This is a source checkpoint, not a production-ready release or a complete installable package set.
+> **Version 1.0.** Published to the KOF22 Gitea Maven registry (`com.kingsrook.qbits`). Requires QQQ Core `4.1.0-RC.22`; the bridges need Record Files `0.1.0-RC.1` and Scripting `1.0.0`. See [status](docs/RELEASE-STATUS.md).

 Start with [current status and build prerequisites](docs/RELEASE-STATUS.md) and [known issues](docs/KNOWN-ISSUES.md). These documents supersede older release-readiness statements below.

@@ -4,9 +4,9 @@
   <parent><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-generation-reactor</artifactId><version>${revision}</version><relativePath>../../pom.xml</relativePath></parent>
   <groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-generation-printing</artifactId><version>${revision}</version>
   <name>Document Generation Printing Bridge</name>
-   <properties><qqq.version>4.1.0-RC.21</qqq.version><!-- Owner-supplied sibling QBit coordinates (not yet published): set to the released version --><qbit-record-files.version>0.1.0-SNAPSHOT</qbit-record-files.version><maven.compiler.release>21</maven.compiler.release><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+   <properties><qqq.version>4.1.0-RC.26</qqq.version><!-- Released sibling QBit coordinates from the Gitea Maven registry --><qbit-record-files.version>0.4.0-RC.1</qbit-record-files.version><maven.compiler.release>21</maven.compiler.release><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      <!-- Released Printing 1.0.0: RetainedPrintFacade.Acceptance carries title/optionsJson and PrintingService enforces options.mediaProfile id+revision. -->
-      <qbit-printing.version>1.0.0</qbit-printing.version><enforcer.skip>true</enforcer.skip></properties>
+      <qbit-printing.version>1.2.0-RC.1</qbit-printing.version><enforcer.skip>true</enforcer.skip></properties>
   <dependencyManagement><dependencies><dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-bom-pom</artifactId><version>${qqq.version}</version><type>pom</type><scope>import</scope></dependency>
      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-core</artifactId><version>${qqq.version}</version></dependency>
      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId><version>${qqq.version}</version></dependency>
@@ -4,7 +4,7 @@
   <parent><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-generation-reactor</artifactId><version>${revision}</version><relativePath>../../pom.xml</relativePath></parent>
   <groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-generation-record-files</artifactId><version>${revision}</version>
   <name>Document Generation Record Files Bridge</name>
-   <properties><qqq.version>4.1.0-RC.21</qqq.version><!-- Owner-supplied sibling QBit coordinates (not yet published): set to the released version --><qbit-record-files.version>0.1.0-SNAPSHOT</qbit-record-files.version><maven.compiler.release>21</maven.compiler.release><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>true</enforcer.skip></properties>
+   <properties><qqq.version>4.1.0-RC.26</qqq.version><!-- Released sibling QBit coordinates from the Gitea Maven registry --><qbit-record-files.version>0.4.0-RC.1</qbit-record-files.version><maven.compiler.release>21</maven.compiler.release><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>true</enforcer.skip></properties>
   <dependencyManagement><dependencies><dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-bom-pom</artifactId><version>${qqq.version}</version><type>pom</type><scope>import</scope></dependency>
      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-core</artifactId><version>${qqq.version}</version></dependency>
      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId><version>${qqq.version}</version></dependency>
@@ -1,9 +1,22 @@
-# Build only on an operator-approved, immutable existing renderer image.
-# This file does not build/download the engine or confer isolation qualification.
+# Build only on an operator-approved, immutable existing renderer image (RENDERER_IMAGE, the engine image from
+# renderer/Dockerfile). This file does not build the engine or confer isolation qualification.
+# The service is the RELEASED transport artifact, resolved at the exact TRANSPORT_VERSION from the QRun-IO Gitea Maven
+# registry and Maven Central (no SNAPSHOT, no local build, no default). BUILD_IMAGE must be an immutable digest.
+#   docker build --build-arg BUILD_IMAGE=... --build-arg RENDERER_IMAGE=... --build-arg TRANSPORT_VERSION=1.0.0 bridges/remote-renderer/
+ARG BUILD_IMAGE
 ARG RENDERER_IMAGE
+FROM ${BUILD_IMAGE} AS release
+ARG TRANSPORT_VERSION
+WORKDIR /release
+COPY release-image/pom.xml ./pom.xml
+RUN test -n "${TRANSPORT_VERSION}" && case "${TRANSPORT_VERSION}" in *SNAPSHOT*|*forge*) echo "TRANSPORT_VERSION must be a released version" >&2; exit 1;; esac \
+    && mvn -B -Dtransport.version="${TRANSPORT_VERSION}" -Dmaven.repo.local=/release/.m2 package \
+    && mv "target/lib/qqq-remote-renderer-transport-${TRANSPORT_VERSION}.jar" target/service.jar \
+    && test -f target/service.jar && ls target/lib
+
 FROM ${RENDERER_IMAGE}
-COPY transport/target/qqq-remote-renderer-transport-0.1.0-SNAPSHOT.jar /remote/service.jar
-COPY transport/target/lib/ /remote/lib/
+COPY --from=release /release/target/service.jar /remote/service.jar
+COPY --from=release /release/target/lib/ /remote/lib/
 COPY LICENSE NOTICE /usr/share/doc/qqq-remote-renderer/
 USER 65532:65532
 EXPOSE 18445
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Image-assembly project, not a published module. It resolves the RELEASED remote renderer transport service and its runtime
+     libraries from the QRun-IO Gitea Maven registry (and Maven Central) at one exact version, so the service image
+     carries release bytes and not a local build. transport.version has no default: pass -Dtransport.version=<released>. -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+   <groupId>com.kingsrook.qbits</groupId><artifactId>qqq-remote-renderer-image</artifactId><version>0</version><packaging>pom</packaging>
+   <repositories>
+      <repository><id>central</id><url>https://repo.maven.apache.org/maven2</url><snapshots><enabled>false</enabled></snapshots></repository>
+      <repository><id>qrun-io</id><url>https://git.kof22.com/api/packages/QRun-IO/maven</url><snapshots><enabled>false</enabled></snapshots><releases><checksumPolicy>fail</checksumPolicy></releases></repository>
+   </repositories>
+   <dependencies>
+      <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qqq-remote-renderer-transport</artifactId><version>${transport.version}</version></dependency>
+   </dependencies>
+   <build><plugins>
+      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-dependency-plugin</artifactId><version>3.9.0</version>
+         <executions><execution><id>release-libraries</id><phase>package</phase><goals><goal>copy-dependencies</goal></goals>
+            <configuration><includeScope>runtime</includeScope><outputDirectory>${project.build.directory}/lib</outputDirectory></configuration>
+         </execution></executions></plugin>
+   </plugins></build>
+</project>
@@ -5,7 +5,7 @@
   <groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-generation-scripting</artifactId><version>${revision}</version>
   <name>Document Generation Scripting Bridge</name>
   <licenses><license><name>GNU Affero General Public License v3.0</name><url>https://www.gnu.org/licenses/agpl-3.0-standalone.html</url><distribution>repo</distribution></license></licenses>
-   <properties><qqq.version>4.1.0-RC.21</qqq.version><!-- Owner-supplied sibling QBit coordinates (not yet published): set to the released version --><qbit-scripting.version>0.1.0-SNAPSHOT</qbit-scripting.version><maven.compiler.release>21</maven.compiler.release><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>true</enforcer.skip></properties>
+   <properties><qqq.version>4.1.0-RC.26</qqq.version><!-- Released sibling QBit coordinates from the Gitea Maven registry --><qbit-scripting.version>1.1.0-RC.3</qbit-scripting.version><maven.compiler.release>21</maven.compiler.release><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>true</enforcer.skip></properties>
   <dependencyManagement><dependencies>
      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-core</artifactId><version>${qqq.version}</version></dependency>
      <dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-backend-module-rdbms</artifactId><version>${qqq.version}</version></dependency>
@@ -1,10 +1,6 @@
-# Known issues and unfinished work
+# Known issues

-Updated: 2026-11-04. These are unresolved items, not a plan currently being executed.
-
- Renderer verification has **3 failing tests out of 174**: `BarcodeDeclaredCapabilityTest.barHeightIsAdvertisedAcceptedAndEffectiveTogether`, `gs1DatabarBarHeightDependsOnMode`, and `unsupportedOptionIsAClosedWorkerCode`. The imported main implementation and capability tests disagree; do not hide this by skipping tests or advertising unsupported options.
- The Record Files and Scripting bridge dependencies, including their `tests` classifier artifacts, are not available as a completed public release cohort. The complete root reactor is not release-qualified.
- Earlier foundation runs hit local socket exhaustion/PostgreSQL connection resets. The final 225-test run passed; the transport failures remain a reproducibility concern.
- Renderer image deployment, hostile-template containment, production capacity and physical barcode/printing acceptance are not established by the Maven tests. Source-first templates are implemented; a visual designer is outside this version.
+- Renderer image deployment, hostile-template containment, production capacity and physical barcode and printing acceptance are not established by the Maven tests. Source-first templates are implemented; a visual designer is outside this version.
+- Barcode `barHeight` is accepted only where it changes the output. The sixteen fixed-geometry encoders (matrix symbols and postal four-state codes) neither advertise nor accept it and refuse it with `UNSUPPORTED_BARCODE_OPTION`, as does GS1 DataBar in stacked mode.
 - Native Zint and patched OpenHTML retain their own licenses and corresponding source. The checked-in archives and hash files must ship with the relevant distribution.
- Some historical design/verification notes describe earlier private builds. This status and this issue list supersede their release claims.
+- Some historical design and verification notes describe earlier private builds; this status and this issue list supersede their release claims.
@@ -1,6 +1,6 @@
 # Document Generation — current status

-Updated: 2026-11-06. **Unreleased work in progress; not a production 1.0 release.** The 2026-11-04 stop was lifted only for the definition-rename change below; no other implementation is in progress.
+**Version 1.0**, built and published by the shared `ci-workflows` Maven pipeline to the KOF22 Gitea Maven registry (`com.kingsrook.qbits`). `mvn deploy` runs every module's tests once. Depends on QQQ Core `4.1.0-RC.22`, Record Files `0.1.0-RC.1` and Scripting `1.0.0`.

 ## Purpose

@@ -20,6 +20,4 @@ Foundation: 225 tests passed with zero failures/errors/skips, Checkstyle clean a

 ## Source and release state

-The starting source was extracted from Website-Backend commit b6fb23825a87412397dec703b9617148ae7eb601, then adapted for standalone packaging. This repository preserves the resulting source and existing licenses. It does not declare a published artifact cohort, completed deployment or complete acceptance.
-
-See [known issues](KNOWN-ISSUES.md) and the README for the existing API and integration documentation. No further implementation, tests, releases or deployment should be started without explicit user instruction; the definition rename was added under such an instruction so a published release can replace GG Forge's local `0.1.0-forge.ee782b7d6ea8-rename1` pin. The outstanding dependency order is Core, Collaboration, Scripting/Record Files, then the integrated Generation bridges and matching UI.
+The starting source was extracted from Website-Backend commit b6fb23825a87412397dec703b9617148ae7eb601, then adapted for standalone packaging; existing licenses are preserved. See [known issues](KNOWN-ISSUES.md) and the README for the API and integration documentation.
@@ -7,7 +7,7 @@
   <version>${revision}</version>
   <name>QBit Document Generation</name>
   <description>User-defined document templates and generation coordination for QQQ</description>
-   <properties><qqq.version>4.1.0-RC.21</qqq.version><maven.compiler.source>21</maven.compiler.source><maven.compiler.target>21</maven.compiler.target><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>false</enforcer.skip></properties>
+   <properties><qqq.version>4.1.0-RC.26</qqq.version><maven.compiler.source>21</maven.compiler.source><maven.compiler.target>21</maven.compiler.target><maven.compiler.proc>none</maven.compiler.proc><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>false</enforcer.skip></properties>
   <licenses><license><name>Apache License, Version 2.0</name><url>https://www.apache.org/licenses/LICENSE-2.0</url><distribution>repo</distribution></license></licenses>
   <dependencyManagement><dependencies><dependency><groupId>com.kingsrook.qqq</groupId><artifactId>qqq-bom-pom</artifactId><version>${qqq.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
   <dependencies>
@@ -5,7 +5,7 @@
        no -Drevision, so a module that declared its own revision would stay at the SNAPSHOT. The root takes qbit-build-parent 2.1.1 (the version foundation already used);
        modules that had no parent now inherit its defaults and this Apache-2.0 license (the vendored OpenHTML module keeps its explicit LGPL-2.1+; bridges/scripting keeps
        its previously inherited AGPL-3.0 explicitly). Each module still keeps its own dependency boundary and builds on its own through its relative parent. -->
-   <parent><groupId>com.kingsrook</groupId><artifactId>qbit-build-parent</artifactId><version>2.1.1</version><relativePath/></parent>
+   <parent><groupId>com.kingsrook</groupId><artifactId>qbit-build-parent</artifactId><version>2.2.1</version><relativePath/></parent>
   <groupId>com.kingsrook.qbits</groupId>
   <artifactId>qbit-document-generation-reactor</artifactId>
   <version>${revision}</version>
@@ -14,7 +14,7 @@
   <url>https://github.com/Kingsrook/qbit-bom</url>
   <scm><connection>scm:git:https://github.com/Kingsrook/qbit-bom.git</connection><developerConnection>scm:git:ssh://git@github.com/Kingsrook/qbit-bom.git</developerConnection><url>https://github.com/Kingsrook/qbit-bom</url><tag>HEAD</tag></scm>
   <licenses><license><name>Apache License, Version 2.0</name><url>https://www.apache.org/licenses/LICENSE-2.0</url><distribution>repo</distribution></license></licenses>
-   <properties><revision>0.1.0-SNAPSHOT</revision><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>true</enforcer.skip></properties>
+   <properties><revision>1.2.0-SNAPSHOT</revision><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><enforcer.skip>true</enforcer.skip><qqq.version>4.1.0-RC.26</qqq.version></properties>
   <!-- Every module of the repository, so one release builds and publishes every GAV. Maven orders the reactor by dependency (the patched OpenHTML
        module before the renderer; foundation before the bridges). Build a subset with -pl <module> -am. -->
   <modules>
@@ -10,18 +10,18 @@ COPY Dockerfile ./
 RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ libc6-dev make cmake patch \
    && sh ./build-zint.sh

-# The renderer's version comes from its parent, the repository reactor POM (../pom.xml). Build from this directory with that file as a named BuildKit context:
-#   docker build --build-context reactor=<repository root> ...   (the reactor POM is copied to /pom.xml, where ../pom.xml resolves for /renderer/pom.xml)
-FROM ${BUILD_IMAGE} AS build
-COPY --from=reactor pom.xml /pom.xml
-WORKDIR /renderer
-COPY vendor/openhtml-1.1.105-qqq-p1 ./vendor/openhtml-1.1.105-qqq-p1
-RUN sh ./vendor/openhtml-1.1.105-qqq-p1/build-openhtml.sh /renderer/openhtml-build /renderer/.m2
-COPY pom.xml ./
-COPY LICENSE NOTICE ./
-COPY checkstyle ./checkstyle
-COPY src ./src
-RUN mvn -B -Dmaven.repo.local=/renderer/.m2 verify
+# The engine and its libraries are the RELEASED artifacts, resolved at the exact RENDERER_VERSION from the QRun-IO
+# Gitea Maven registry and Maven Central (Maven checks each registry checksum). No SNAPSHOT, no local build and no
+# local-cache coordinate: the version is a required build argument with no default.
+#   docker build --build-arg BUILD_IMAGE=... --build-arg JAVA_IMAGE=... --build-arg RENDERER_VERSION=1.0.0 renderer/
+FROM ${BUILD_IMAGE} AS release
+ARG RENDERER_VERSION
+WORKDIR /release
+COPY release-image/pom.xml ./pom.xml
+RUN test -n "${RENDERER_VERSION}" && case "${RENDERER_VERSION}" in *SNAPSHOT*|*forge*) echo "RENDERER_VERSION must be a released version" >&2; exit 1;; esac \
+    && mvn -B -Drenderer.version="${RENDERER_VERSION}" -Dmaven.repo.local=/release/.m2 package \
+    && mv "target/lib/qbit-document-renderer-${RENDERER_VERSION}.jar" target/renderer.jar \
+    && test -f target/renderer.jar && ls target/lib

 FROM ${JAVA_IMAGE}
 # Reviewed runtime family: Temurin 21.0.13+9 on Ubuntu noble. The approved digest
@@ -37,8 +37,9 @@ RUN . /etc/os-release \
 WORKDIR /renderer
 COPY --from=zint-build /zint-build/build/frontend/zint /usr/local/bin/zint
 COPY --from=zint-build /zint-build/corresponding-source /usr/share/doc/qqq-zint
-COPY --from=build /renderer/openhtml-build/corresponding-source /usr/share/doc/qqq-openhtml
-COPY --from=build /renderer/target/qbit-document-renderer-0.1.0-SNAPSHOT.jar ./renderer.jar
-COPY --from=build /renderer/target/lib ./lib
+# LGPL corresponding source for the vendored OpenHTML module that the released openhtmltopdf-pdfbox jar was built from.
+COPY vendor/openhtml-1.1.105-qqq-p1 /usr/share/doc/qqq-openhtml
+COPY --from=release /release/target/renderer.jar ./renderer.jar
+COPY --from=release /release/target/lib ./lib
 USER 65532:65532
 ENTRYPOINT ["java", "-Xmx256m", "-XX:ActiveProcessorCount=1", "-Djava.awt.headless=true", "-Dpdfbox.fontcache=/tmp", "-jar", "/renderer/renderer.jar"]
@@ -0,0 +1,120 @@
+# Renderer container images: build from a released version and publish
+
+Two images, built in this order. Both are built from **released** Maven artifacts (QRun-IO Gitea registry
+`https://git.kof22.com/api/packages/QRun-IO/maven` and Maven Central); there is no SNAPSHOT, local-cache or reactor
+input. The version is a required build argument with no default, and the Dockerfiles refuse a `SNAPSHOT` or `forge`
+version.
+
+| Image | Dockerfile (context) | Version argument | Contents |
+|---|---|---|---|
+| `ghcr.io/gg-engineering/qqq-document-renderer` | `renderer/Dockerfile` (`renderer/`) | `RENDERER_VERSION` (`qbit-document-renderer`) | engine, its libraries, patched Zint built from `renderer/vendor`, Temurin runtime |
+| `ghcr.io/gg-engineering/qqq-remote-renderer` | `bridges/remote-renderer/Dockerfile` (`bridges/remote-renderer/`) | `TRANSPORT_VERSION` (`qqq-remote-renderer-transport`), `RENDERER_IMAGE` | the mTLS service, on top of the engine image |
+
+The service image is the one Forge deploys. The adapter (`qbit-document-generation-remote-renderer`) is a client-side
+library and is not in either image.
+
+## Version choice
+
+`1.0.0` is the released, non-RC version and the one `gg-forge` pins for the document-generation family. `1.1.0-RC.1`
+contains the same `renderer/` and `bridges/remote-renderer/` sources as `1.0.0` (only POM/CI alignment differs), so it
+adds nothing for the renderer and is a release candidate. Build the version the host library pins.
+
+## Reviewed base images
+
+`BUILD_IMAGE` and `JAVA_IMAGE` must be immutable digests. `JAVA_IMAGE` is the reviewed runtime in `DEPLOYMENT.md`.
+`BUILD_IMAGE` only resolves artifacts; no layer of it reaches the final image.
+
+```sh
+BUILD_IMAGE=maven@sha256:99e61abcff91a9b1333463bd8451fb18495d6eba9250ac66a338b518f8278320   # maven:3.9-eclipse-temurin-21
+JAVA_IMAGE=eclipse-temurin@sha256:db724162e4ff5f71fa0a2815026314d9e5e0e9a139f49be1d4717e6930e93341  # 21.0.13_9-jre-noble (amd64)
+VERSION=1.0.0
+```
+
+## Build, smoke, push
+
+Disable BuildKit provenance and SBOM attestations so each tag is a single OCI image manifest (the digest the chart pins).
+
+```sh
+docker build --provenance=false --sbom=false --build-arg BUILD_IMAGE=$BUILD_IMAGE --build-arg JAVA_IMAGE=$JAVA_IMAGE   --build-arg RENDERER_VERSION=$VERSION -t qqq-document-renderer:$VERSION renderer
+docker build --provenance=false --sbom=false --build-arg BUILD_IMAGE=$BUILD_IMAGE --build-arg RENDERER_IMAGE=qqq-document-renderer:$VERSION   --build-arg TRANSPORT_VERSION=$VERSION -t qqq-remote-renderer:$VERSION bridges/remote-renderer
+
+# Optional scan of the final image
+docker save qqq-remote-renderer:$VERSION -o svc.tar
+docker run --rm -v "$PWD/svc.tar:/svc.tar:ro" aquasec/trivy:latest image --input /svc.tar --severity HIGH,CRITICAL --scanners vuln
+
+# Publish (docker must be logged in to ghcr.io with a token that has write:packages)
+for n in qqq-document-renderer qqq-remote-renderer; do
+  docker tag $n:$VERSION ghcr.io/gg-engineering/$n:$VERSION
+  docker push ghcr.io/gg-engineering/$n:$VERSION      # prints the manifest digest
+done
+```
+
+New GHCR packages are private. Package access is per package and is managed in the GitHub UI (Package settings,
+Manage access); the REST API cannot grant it. The credential behind `ghcr-pull-secret` must be able to read both packages.
+
+## Pins for gg-forge-cd
+
+`sh renderer/image-pins.sh ghcr.io/gg-engineering/qqq-remote-renderer@sha256:<manifest digest>` pulls the published
+image and prints the `echoRenderer.*` image, classpath and file-hash pins from the image itself. `imageId` is
+`docker image inspect --format '{{.Id}}'`; with the containerd image store this equals the manifest digest, otherwise
+it is the config digest. Whatever value is chosen must be the same on Forge and the service.
+
+Values for `1.0.0` as published (the java, zint and patchset hashes match the 2026-11-05 local qualification; the
+engine JAR and the OpenHTML JAR differ because they are the released artifacts):
+
+```yaml
+echoRenderer:
+  image:
+    repository: ghcr.io/gg-engineering/qqq-remote-renderer
+    digest: sha256:4152a4253e543068bedfd438775ed5327807bdddf679bc5a8e6eab26855e09ea
+  imageId: sha256:4152a4253e543068bedfd438775ed5327807bdddf679bc5a8e6eab26855e09ea
+  classpath:
+    - /renderer/renderer.jar
+    - /renderer/lib/commons-logging-1.4.0.jar
+    - /renderer/lib/fontbox-3.0.8.jar
+    - /renderer/lib/freemarker-2.3.35.jar
+    - /renderer/lib/graphics2d-3.0.1.jar
+    - /renderer/lib/jackson-annotations-2.22.jar
+    - /renderer/lib/jackson-core-2.22.4.jar
+    - /renderer/lib/jackson-databind-2.22.4.jar
+    - /renderer/lib/jsoup-1.23.2.jar
+    - /renderer/lib/okapibarcode-0.5.7.jar
+    - /renderer/lib/openhtmltopdf-core-1.1.105.jar
+    - /renderer/lib/openhtmltopdf-pdfbox-1.0.0.jar
+    - /renderer/lib/pdfbox-3.0.8.jar
+    - /renderer/lib/pdfbox-io-3.0.8.jar
+    - /renderer/lib/slf4j-api-2.0.17.jar
+    - /renderer/lib/slf4j-nop-2.0.17.jar
+    - /renderer/lib/xmpbox-3.0.8.jar
+  fileHashes:
+    /opt/java/openjdk/bin/java: 7afc28801f744050aeba646b20e7314265279f76f9d0273b21a2b66411e1bf6d
+    /renderer/renderer.jar: 0061e1bce631e468b0d7d08735bb764ba2b6d85260c79c144beabad7ffbc19db
+    /usr/local/bin/zint: ea8dc40c917abd7e8ccc824ef0adafed245a2425abbdfac6a30faeb8e4642233
+    /usr/share/doc/qqq-zint/patchset-id.txt: a287946580d5eeb8691ac1d98d6a7f50bf22dcc5dc0ef039d7033e76e15c52d2
+    /renderer/lib/commons-logging-1.4.0.jar: d175dbd751dd782a63bde28c7a039520e971f25e84b79c19b8435edc3603e0dc
+    /renderer/lib/fontbox-3.0.8.jar: a1915c24e3edbe0ecec93896dfbf6d41427810b663ade97bd4e8bae86ec3fdab
+    /renderer/lib/freemarker-2.3.35.jar: 0fac87dddd78f1223139e8ef88e819c7f483c0a3835cdf5982ad5e4576d1d896
+    /renderer/lib/graphics2d-3.0.1.jar: 4849aaa6f536d75dea1b835a71086702216787036f42716adfad438c6e7928c0
+    /renderer/lib/jackson-annotations-2.22.jar: 21ddb598807d3a51a876704eb979d9296e1c6a6f47ab1826ff88c6d6a127a2d0
+    /renderer/lib/jackson-core-2.22.4.jar: 2d30c375cddea9657a1e1ef97547a2694b663b355facb4de53a097782b312d1a
+    /renderer/lib/jackson-databind-2.22.4.jar: d4cbf8947087f305869826801913abdc50735a1fab2074a1993e7bc67ca974a3
+    /renderer/lib/jsoup-1.23.2.jar: e9d8c856856680427f096d156f02a414289985c930998fcb519ce5be39b42003
+    /renderer/lib/okapibarcode-0.5.7.jar: f33b7d17b7040aa1d9c23b1f3bb274e492b786c340b02d9557bcc027ac874355
+    /renderer/lib/openhtmltopdf-core-1.1.105.jar: d5951a8407c3be41108698066e6d67cf952e526be39d4e49b0b9fbcee761de7d
+    /renderer/lib/openhtmltopdf-pdfbox-1.0.0.jar: ec2865bfa45513e63adaa1a3c6387eb6bbd481e6b23f4d68a33cfedfc753cfe8
+    /renderer/lib/pdfbox-3.0.8.jar: 97647cfbde61ebcfc06b4cf8c9b0ffcaaee073396eceb4a7f6836a9b9128903c
+    /renderer/lib/pdfbox-io-3.0.8.jar: 36a0e04001010b4c764857817412b96339930b19755e728959805cc0352061b2
+    /renderer/lib/slf4j-api-2.0.17.jar: 7b751d952061954d5abfed7181c1f645d336091b679891591d63329c622eb832
+    /renderer/lib/slf4j-nop-2.0.17.jar: 3716f83649ec66161a2edefd4f49df34d1dd1c51cdcf941996c6987260f0a829
+    /renderer/lib/xmpbox-3.0.8.jar: f044d2e316e57714a0adf272ad8abf4a863b8978fd17dc5b86dcfa8135469b10
+```
+
+Not covered by these pins: `identity.*`, `certificateNamespaces`, TLS identities, and chart switches.
+
+## What was and was not verified (1.0.0 build)
+
+* Verified: `renderer` (174) and transport (19) tests and Checkstyle pass on this source (same sources as the `v1.0.0` tag);
+  both images build; the service image runs read-only, non-root, all capabilities dropped, and served CATALOG, PDF
+  (Code128, GS1-128, Zint DotCode) and ZPL renders over a real mutual-TLS handshake with ephemeral certificates.
+* Not verified: no cluster run, no handshake against Forge, no gVisor or hostile-input qualification (the service is
+  `TRUSTED_LAB` only), no byte-for-byte rebuild of the OpenHTML jar from `vendor/`.
@@ -0,0 +1,25 @@
+#!/bin/sh
+# Print the gg-forge-cd echoRenderer.* pins (non-secret) for a PUBLISHED service image, read from the image itself:
+#   sh renderer/image-pins.sh ghcr.io/gg-engineering/qqq-remote-renderer@sha256:<manifest digest>
+# The classpath is /renderer/renderer.jar followed by /renderer/lib/*.jar in byte order; hashes are SHA256 of the files in the image.
+set -eu
+image=${1:?image reference by digest required}
+case "$image" in *@sha256:*) ;; *) echo 'Reference the image by @sha256: digest' >&2; exit 2;; esac
+repository=${image%@*}
+digest=${image#*@}
+docker pull "$image" >/dev/null
+image_id=$(docker image inspect "$image" --format '{{.Id}}')
+echo "echoRenderer:"
+echo "  image:"
+echo "    repository: $repository"
+echo "    digest: $digest"
+echo "  imageId: $image_id"
+docker run --rm --pull never --network none --user 65532:65532 --entrypoint sh "$image" -c '
+  set -eu
+  echo "  classpath:"
+  echo "    - /renderer/renderer.jar"
+  for f in $(LC_ALL=C ls /renderer/lib/*.jar); do echo "    - $f"; done
+  echo "  fileHashes:"
+  for f in /opt/java/openjdk/bin/java /renderer/renderer.jar /usr/local/bin/zint /usr/share/doc/qqq-zint/patchset-id.txt $(LC_ALL=C ls /renderer/lib/*.jar); do
+    printf "    %s: %s\n" "$f" "$(sha256sum "$f" | cut -d" " -f1)"
+  done'
@@ -32,7 +32,7 @@
         </execution></executions>
      </plugin>
      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.14.1</version><configuration><showWarnings>true</showWarnings><failOnWarning>true</failOnWarning><compilerArgs><arg>-XDcompilePolicy=simple</arg><arg>--should-stop=ifError=FLOW</arg><arg>-XDaddTypeAnnotationsToSymbol=true</arg><arg>-Xplugin:ErrorProne -Xep:UnnecessaryParentheses:OFF -Xep:NotJavadoc:OFF</arg><arg>-Xlint:all</arg><arg>-Werror</arg></compilerArgs><annotationProcessorPaths><path><groupId>com.google.errorprone</groupId><artifactId>error_prone_core</artifactId><version>2.49.0</version></path></annotationProcessorPaths></configuration></plugin>
-      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.4</version><configuration><dependenciesToScan combine.self="override"/><systemPropertyVariables><java.awt.headless>true</java.awt.headless><pdfbox.fontcache>${project.build.directory}</pdfbox.fontcache></systemPropertyVariables></configuration></plugin>
+      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.4</version><configuration><dependenciesToScan combine.self="override"/><systemPropertyVariables><kof22.provider.version>${revision}</kof22.provider.version><java.awt.headless>true</java.awt.headless><pdfbox.fontcache>${project.build.directory}</pdfbox.fontcache></systemPropertyVariables></configuration></plugin>
      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-dependency-plugin</artifactId><version>3.9.0</version><executions><execution><id>runtime-libraries</id><phase>package</phase><goals><goal>copy-dependencies</goal></goals><configuration><includeScope>runtime</includeScope><outputDirectory>${project.build.directory}/lib</outputDirectory></configuration></execution></executions></plugin>
      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-jar-plugin</artifactId><version>3.4.2</version><configuration><archive><manifest><mainClass>com.kingsrook.qbits.renderer.RendererMain</mainClass><addClasspath>true</addClasspath><classpathPrefix>lib/</classpathPrefix></manifest></archive></configuration></plugin>
      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-checkstyle-plugin</artifactId><version>3.3.1</version><dependencies><dependency><groupId>com.puppycrawl.tools</groupId><artifactId>checkstyle</artifactId><version>10.12.6</version></dependency></dependencies><configuration><configLocation>${project.basedir}/checkstyle/config.xml</configLocation><propertyExpansion>checkstyle.reactor.root=${project.basedir}</propertyExpansion><includeTestSourceDirectory>true</includeTestSourceDirectory><consoleOutput>true</consoleOutput><violationSeverity>warning</violationSeverity><failOnViolation>true</failOnViolation></configuration><executions><execution><phase>validate</phase><goals><goal>check</goal></goals></execution></executions></plugin>
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Image-assembly project, not a published module. It resolves the RELEASED renderer engine and its runtime
+     libraries from the QRun-IO Gitea Maven registry (and Maven Central) at one exact version, so the renderer image
+     carries release bytes and not a local build. renderer.version has no default: pass -Drenderer.version=<released>. -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
+   <groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-renderer-image</artifactId><version>0</version><packaging>pom</packaging>
+   <repositories>
+      <repository><id>central</id><url>https://repo.maven.apache.org/maven2</url><snapshots><enabled>false</enabled></snapshots></repository>
+      <repository><id>qrun-io</id><url>https://git.kof22.com/api/packages/QRun-IO/maven</url><snapshots><enabled>false</enabled></snapshots><releases><checksumPolicy>fail</checksumPolicy></releases></repository>
+   </repositories>
+   <dependencies>
+      <dependency><groupId>com.kingsrook.qbits</groupId><artifactId>qbit-document-renderer</artifactId><version>${renderer.version}</version></dependency>
+   </dependencies>
+   <build><plugins>
+      <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-dependency-plugin</artifactId><version>3.9.0</version>
+         <executions><execution><id>release-libraries</id><phase>package</phase><goals><goal>copy-dependencies</goal></goals>
+            <configuration><includeScope>runtime</includeScope><outputDirectory>${project.build.directory}/lib</outputDirectory></configuration>
+         </execution></executions></plugin>
+   </plugins></build>
+</project>
@@ -51,6 +51,15 @@ public final class BarcodeCatalog
 {
   private static final Map<String, Supplier<Symbol>> FACTORIES = factories();

+   /*******************************************************************************
+    ** Encoders whose geometry is fixed by their specification (matrix symbols and
+    ** postal four-state codes): barHeight changes nothing for them, so it is
+    ** neither advertised nor accepted. BarcodeDeclaredCapabilityTest proves this
+    ** set is exactly the encoders on which barHeight has no effect.
+    *******************************************************************************/
+   private static final java.util.Set<String> FIXED_GEOMETRY = java.util.Set.of("australia-post", "aztec", "aztec-rune", "code-one", "code16k",
+      "code49", "datamatrix", "grid-matrix", "japan-post", "kix", "maxicode", "micro-qr", "qr", "royal-mail", "swiss-qr", "upn-qr");
+

   /*******************************************************************************
    ** Utility class.
@@ -142,7 +151,14 @@ public final class BarcodeCatalog
      {
         Symbol symbol = FACTORIES.get(id).get();
         Map<String, Object> options = new LinkedHashMap<>();
-         options.put("barHeight", Map.of("type", "integer", "minimum", 1, "maximum", 1000));
+         if("gs1-databar".equals(id))
+         {
+            options.put("barHeight", Map.of("type", "integer", "minimum", 1, "maximum", 1000, "notWithMode", "STACKED"));
+         }
+         else if(!FIXED_GEOMETRY.contains(id))
+         {
+            options.put("barHeight", Map.of("type", "integer", "minimum", 1, "maximum", 1000));
+         }
         if(symbol instanceof Coop2Of5)
         {
            options.put("checkDigit", Map.of("type", "string", "values", List.of("NONE", "ADD", "VALIDATE"), "default", "NONE"));
@@ -380,6 +396,10 @@ public final class BarcodeCatalog
      }
      Symbol symbol = factory.get();
      structuredAppend(type, symbol, options);
+      if(options.has("barHeight") && (FIXED_GEOMETRY.contains(type) || ("gs1-databar".equals(type) && options.has("mode") && "STACKED".equals(options.get("mode").asText()))))
+      {
+         throw new IllegalArgumentException("UNSUPPORTED_BARCODE_OPTION");
+      }
      for(Map.Entry<String, JsonNode> field : options.properties())
      {
         if(List.of("qr", "datamatrix", "aztec").contains(type) && field.getKey().startsWith("structuredAppend"))
@@ -96,6 +96,36 @@ public final class PdfRenderer
   public static void validate(RenderInput input) throws Exception
   {
      template(input.source);
+      for(Element element : Jsoup.parse(input.source).select("qqq-barcode"))
+      {
+         refuseUnsupportedOptions(element.attr("type"), element.attr("options"));
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Literal barcode options are checked against the catalog before any data
+    ** exists, so an option the encoder cannot honour is refused at validation as
+    ** its own closed code. Templated type or options are checked when rendered,
+    ** and any other problem is left for the render to report.
+    *******************************************************************************/
+   private static void refuseUnsupportedOptions(String type, String options)
+   {
+      if(options.isBlank() || type.contains("${") || type.contains("<#") || options.contains("${") || options.contains("<#"))
+      {
+         return;
+      }
+      try
+      {
+         BarcodeCatalog.create(type, Wire.JSON.readTree(options));
+      }
+      catch(Exception exception)
+      {
+         if(exception instanceof IllegalArgumentException refusal && "UNSUPPORTED_BARCODE_OPTION".equals(refusal.getMessage()))
+         {
+            throw refusal;
+         }
+      }
   }


@@ -103,7 +103,8 @@ public final class RendererMain
         "BARCODE_FIT_TOO_SMALL", "BARCODE_FIT_UNSUPPORTED", "BARCODE_FIT_BOX_OUTSIDE_STOCK",
         "BARCODE_FIT_GEOMETRY_MISMATCH", "INVALID_BARCODE_FIT_PROFILE", "INVALID_BARCODE_FIT_REQUEST",
         "BARCODE_SYMBOLOGY_NOT_ALLOWED", "SYMBOLOGY_ALLOWLIST_REQUIRED", "SCANNER_BARCODE_PROFILE_UNSUPPORTED",
-         "SCANNER_BARCODE_PAYLOAD_UNSUPPORTED", "SCANNER_BARCODE_CHECKSUM_REQUIRED", "SCANNER_BARCODE_CHECKSUM_MISMATCH").contains(message))
+         "SCANNER_BARCODE_PAYLOAD_UNSUPPORTED", "SCANNER_BARCODE_CHECKSUM_REQUIRED", "SCANNER_BARCODE_CHECKSUM_MISMATCH",
+         "UNSUPPORTED_BARCODE_OPTION").contains(message))
      {
         return (message);
      }
@@ -84,16 +84,32 @@ public final class BackgroundImageQualification
         cases += 2;
      }
      return (Map.of("cases", cases, "surfaces", List.of("element", "pseudo", "page"), "exactRgbAlphaAndDimensions", true,
-         "bothAliasPaintOrders", true, "provider", "com.kingsrook.thirdparty:openhtmltopdf-pdfbox:1.1.105-qqq-p1",
+         "bothAliasPaintOrders", true, "provider", "com.kingsrook.thirdparty:openhtmltopdf-pdfbox:" + providerVersion(),
         "qualification", "trusted-product-fixtures-only"));
   }

+   /***************************************************************************
+    ** The patched OpenHTML provider is published at the family version of this
+    ** reactor, which surefire passes in; there is no second literal to keep in sync.
+    ***************************************************************************/
+   private static String providerVersion()
+   {
+      String version = System.getProperty("kof22.provider.version");
+      if(version == null || version.isBlank())
+      {
+         throw new IllegalArgumentException("PDF_PROVIDER_VERSION_PROPERTY_MISSING");
+      }
+      return (version);
+   }
+
+
+
   /***************************************************************************
    ** One provider class must come from the private patched GAV, with unchanged official companion versions.
    ***************************************************************************/
   static void verifyProvider() throws Exception
   {
-      verifyArtifact(com.openhtmltopdf.pdfboxout.PdfBoxFastOutputDevice.class, "com.kingsrook.thirdparty", "openhtmltopdf-pdfbox", "1.1.105-qqq-p1");
+      verifyArtifact(com.openhtmltopdf.pdfboxout.PdfBoxFastOutputDevice.class, "com.kingsrook.thirdparty", "openhtmltopdf-pdfbox", providerVersion());
      verifyArtifact(com.openhtmltopdf.css.parser.CSSParser.class, "io.github.openhtmltopdf", "openhtmltopdf-core", "1.1.105");
      verifyArtifact(org.apache.pdfbox.pdmodel.PDDocument.class, "org.apache.pdfbox", "pdfbox", "3.0.8");
   }