feat: scene 2 foundations: version 1 compatibility corpus, coverage and fuzz gates, preview ports (P0, P13, P6a) #13

Merged

james.maes merged 3 commits from feat/scene2-foundations into develop 2026-11-12 15:15:18 +00:00

Conversation 0 Commits 3 Files Changed 110

+5255 -5

james.maes commented 2026-11-11 23:36:07 +00:00

Owner

Copy link

Copy source

Three foundation packages of the label layout work plan (design: docs/design/LABEL-LAYOUT-FONTS-PREVIEW.md on docs/label-layout-preview-design, draft PR 12), as one pull request with one commit each: P0 version 1 compatibility corpus, P13 coverage gates and fuzz scaffolding, P6a ports and registration hooks. No label prints differently and no host adapter changes.

P0. Version 1 compatibility corpus (commit 1)

Added, tests and resources only:

• renderer/src/test/resources/compat-v1/: 42 render requests (cases/), the exact ZPL the released renderer returned for each (zpl/), SHA256SUMS, one synthetic image and a README with provenance and rules.
• renderer/.../ZplSceneOneCompatibilityTest: renders every case and fails on the first differing byte (the new bytes are left in target/compat-v1-actual); checks the manifest names exactly the cases; checks the corpus uses every element type, every property version 1 reads and all three resolutions.
• bridges/renderer/.../ZplSceneOneCompatibilityTest: every stored output has its manifest hash and passes the unchanged ZplOutputPolicy for its stock.

Coverage of the corpus: the four shapes Forge publishes at 203 and 300 dpi (plain, scanner fidelity, compact GS1-128 with fit, quiet and font 0 text, and the centred GS1-128 document with rasterText and fontAsset, whose barcode carries the align key version 1 ignores); the README.md and BARCODE-FIT.md examples verbatim; one scene per element and option at 203, 300 and 600 dpi, including all 13 fit-qualified symbologies. All values are synthetic.

Reviewer, please look at:

• Provenance. The bytes come from tag v1.1.0-RC.2 (commit e9ffba48), not from this branch: the test and cases/ were copied into a checkout of the tag and run with no stored outputs. The same test then passed against the tag on Temurin 21.0.12 on Windows and on Temurin 21.0.9 in the CI image (maven:3.9.11-eclipse-temurin-21), so the rasterText pixels do not depend on either. git diff v1.1.0-RC.2 origin/develop -- renderer/src is empty.
• What is not in it. payloadEncoding: BASE64 and the Zint-backed symbologies need the native Zint provider, which exists only in the renderer image.
• One copy. The design lists resources/compat-v1/ under both modules. The bridge test reads the renderer's directory in place instead, so the two cannot drift.

P13. Coverage gates and fuzz scaffolding (commit 2)

Added:

• JaCoCo 0.8.15 on renderer and bridges/renderer (prepare-agent, report, check at verify), with a bundle rule at the measured baseline and 100% line rules for the code the design adds later: packages com.kingsrook.qbits.renderer.scene2 and below, and classes AssetInspector (renderer) and ZplRaster (bridge). The rules match nothing until those exist, so P1 and P5 do not edit these poms.
• foundation/pom.xml: the existing 85% instruction and 90% class bundle rule is untouched; one added rule holds the new foundation classes the design names to 100% lines.
• MutationCampaign in each module's test tree: a seeded, bounded mutation harness (no clock, fixed seeds, replay by seed and iteration), and MutationCampaignTest with the harness's own tests and one property per module that runs in the normal test phase.
• docs/security/fuzzing.md: targets, properties, limits, seeds and the replay command. README.md: one sentence on the gates.

Baselines (instructions / lines):

Module	Gate	This head, Windows	CI image (Linux)	develop before this PR
renderer	94% / 91%	94.11% / 91.44%	94.08% / 91.38%	93.43% / 90.51%
bridges/renderer	85% / 82%	85.77% / 82.75%	85.61% / 82.64%	85.10% / 82.05%
foundation	85% instructions, 90% classes (unchanged)	93.46% / 92.12%	93.46% / 92.12%	93.19% / 91.82%

The gates are the head's measurement rounded down to a whole percent; the corpus tests of commit 1 are what raised the two modules above develop. The CI image run was the same sources before the gate values were written and with the campaigns at 4000 iterations (now 20000).

Reviewer, please look at:

• The gates fail when they should. Each was proved with a deliberate miss, then reverted:
  • an untested class in com.kingsrook.qbits.renderer.scene2: Rule violated for package com.kingsrook.qbits.renderer.scene2: lines covered ratio is 0.00, but expected minimum is 1.00
  • an untested AssetInspector: Rule violated for class com.kingsrook.qbits.renderer.AssetInspector: lines covered ratio is 0.00, but expected minimum is 1.00
  • the same untested code against the renderer baseline: Rule violated for bundle qbit-document-renderer: instructions covered ratio is 0.93, but expected minimum is 0.94 and lines covered ratio is 0.90, but expected minimum is 0.91
  • an untested ZplRaster: Rule violated for class com.kingsrook.qbits.documentgeneration.renderer.ZplRaster: lines covered ratio is 0.00, but expected minimum is 1.00
  • an untested method added to GenerationPreviewWidget: Rule violated for class com.kingsrook.qbits.documentgeneration.GenerationPreviewWidget: lines covered ratio is 0.00, but expected minimum is 1.00
  • the harness itself: MutationCampaignTest.aCrashAndAnUnsafeAcceptanceAreFindingsThatReplay feeds it a target that crashes and one that accepts what it should refuse, and requires both to be reported.
• The baseline margins are thin by design. The renderer instruction gate is 15 instructions under the measurement. The bridge line gate is 6 to 7 lines under it; bridge coverage moved by one line between two runs (WarmRendererPool, timing) and differs by one line between Windows and Linux (BoundedProcess).
• No skip switch. The checks are bound to verify with no property to turn them off.
• The properties are not crash-only. The scene parser campaign checks, with a second parser, that whatever version 1 accepts is a version 1 scene of known elements; the printer gate campaign checks that whatever the gate accepts holds only the renderer's command set. Both must reach acceptance and refusal. The gate campaign's first run showed a refusal type the property had not declared (CharacterCodingException for field text that is not UTF-8); it is a refusal, not a defect, and is now named.
• Not done here. K22-TEST-25 also asks for docs/security/assurance.json and a weekly long campaign. The design names only fuzzing.md; both gaps are recorded in its review record. The long campaign (100000 iterations, both seeds, both targets) was run by hand and passed.

P6a. Ports and registration hooks (commit 3)

Added in GenerationPorts: Diagnostic (with Severity), PreviewRequest, PreviewPage, Preview, 15 version 2 FailureCode values, RenderException(FailureCode, Diagnostic), IsolatedRenderer.preview as a default that refuses, and Integer targetDpi on RenderRequest with the seven-argument constructor kept. Five new classes that do nothing yet, each already called from its registration point: GenerationPreviewProcesses, GenerationAssetProcesses, GenerationUpgradeProcesses and GenerationAssetTables from the producer, GenerationPreviewWidget.section(table) from GenerationTables.

Tests: GenerationPortsContractTest (record validation, default refusals, existing constructors and an adapter written before the port) and GenerationRegistrationHooksTest (the producer registers exactly the 13 tables, 28 processes, 11 possible value sources, no widgets and four template sections it did before; the lists were captured from the untouched tag).

Reviewer, please look at:

• Nothing breaks an existing host adapter. preview is a default method; RenderRequest and RenderException keep their constructors; the bridge and the service still call the seven-argument form and ignore targetDpi until P5 and P7.
• Diagnostics cannot hold free text. code is checked against a closed vocabulary by severity (an error is a FailureCode name; warnings and information are the fixed names of design section 8.1), element is the author-id grammar, box is four integers, and measured and limit are at most eight integers under identifier names.
• Where the design and the code disagreed (the code won):
  1. The design puts the new FailureCode values in P6a and lists no bridge file. But IsolatedRendererBridge maps any FailureCode name a 0.1.0 worker sends to a typed refusal, and BridgeTest pins the count at 13. Growing the enum alone would have let a 0.1.0 worker name version 2 refusals. The bridge now keeps the 13 released codes as the set a 0.1.0 worker may name, and BridgeTest asserts the other 15 stay generic. P5 replaces this with its version rule.
  2. Design 8.1 says SCENE_INVALID carries the JSON pointer of the offending property, but the diagnostic shape it gives has no field for one, and a pointer is text. Diagnostic follows the shape. P1 needs a decision (a bounded pointer grammar field, or the element id only).
  3. The design gives no components for PreviewRequest and PreviewPage. They are (actorId, format, revision, context, targetDpi, maximumBytes) and (png, widthDots, heightDots); Preview is exactly the six components of section 6.3. A page must start with the PNG signature, and a preview with an error diagnostic cannot say printable.
  4. targetDpi is validated in the record (absent, 203, 300 or 600), because P7's file list does not include GenerationPorts.

Build

./mvnw -B -ntp -T1C verify at the repository root (the CI command, mvn -T1C verify), on the head of this branch, with every gate: BUILD SUCCESS on c6aa0bf (Temurin 21.0.12, Windows, Docker for Testcontainers). 650 tests, 0 failures, 0 errors, 0 skipped: foundation 254, renderer 222, bridges/renderer 98, remote-renderer transport 19, record-files 19, printing 16, OpenHTML 15, scripting 7. Checkstyle clean in every module, Error Prone and -Werror clean, and all three coverage checks met. The build used a settings file with the QRun-IO registry profile, as the CI settings do.

The same command also passed in the CI image (maven:3.9.11-eclipse-temurin-21, Temurin 21.0.9, MySQL and PostgreSQL through Testcontainers) on these sources before the gate values were written: 650 tests, BUILD SUCCESS.

🤖 Generated with Claude Code

Three foundation packages of the label layout work plan (design: `docs/design/LABEL-LAYOUT-FONTS-PREVIEW.md` on `docs/label-layout-preview-design`, draft PR 12), as one pull request with one commit each: **P0** version 1 compatibility corpus, **P13** coverage gates and fuzz scaffolding, **P6a** ports and registration hooks. No label prints differently and no host adapter changes. ## P0. Version 1 compatibility corpus (commit 1) Added, tests and resources only: - `renderer/src/test/resources/compat-v1/`: 42 render requests (`cases/`), the exact ZPL the released renderer returned for each (`zpl/`), `SHA256SUMS`, one synthetic image and a README with provenance and rules. - `renderer/.../ZplSceneOneCompatibilityTest`: renders every case and fails on the first differing byte (the new bytes are left in `target/compat-v1-actual`); checks the manifest names exactly the cases; checks the corpus uses every element type, every property version 1 reads and all three resolutions. - `bridges/renderer/.../ZplSceneOneCompatibilityTest`: every stored output has its manifest hash and passes the unchanged `ZplOutputPolicy` for its stock. Coverage of the corpus: the four shapes Forge publishes at 203 and 300 dpi (plain, scanner fidelity, compact GS1-128 with `fit`, `quiet` and font 0 `text`, and the centred GS1-128 document with `rasterText` and `fontAsset`, whose barcode carries the `align` key version 1 ignores); the `README.md` and `BARCODE-FIT.md` examples verbatim; one scene per element and option at 203, 300 and 600 dpi, including all 13 fit-qualified symbologies. All values are synthetic. Reviewer, please look at: - **Provenance.** The bytes come from tag `v1.1.0-RC.2` (commit `e9ffba48`), not from this branch: the test and `cases/` were copied into a checkout of the tag and run with no stored outputs. The same test then passed against the tag on Temurin 21.0.12 on Windows and on Temurin 21.0.9 in the CI image (`maven:3.9.11-eclipse-temurin-21`), so the `rasterText` pixels do not depend on either. `git diff v1.1.0-RC.2 origin/develop -- renderer/src` is empty. - **What is not in it.** `payloadEncoding: BASE64` and the Zint-backed symbologies need the native Zint provider, which exists only in the renderer image. - **One copy.** The design lists `resources/compat-v1/` under both modules. The bridge test reads the renderer's directory in place instead, so the two cannot drift. ## P13. Coverage gates and fuzz scaffolding (commit 2) Added: - JaCoCo 0.8.15 on `renderer` and `bridges/renderer` (`prepare-agent`, `report`, `check` at `verify`), with a bundle rule at the measured baseline and 100% line rules for the code the design adds later: packages `com.kingsrook.qbits.renderer.scene2` and below, and classes `AssetInspector` (renderer) and `ZplRaster` (bridge). The rules match nothing until those exist, so P1 and P5 do not edit these poms. - `foundation/pom.xml`: the existing 85% instruction and 90% class bundle rule is untouched; one added rule holds the new foundation classes the design names to 100% lines. - `MutationCampaign` in each module's test tree: a seeded, bounded mutation harness (no clock, fixed seeds, replay by seed and iteration), and `MutationCampaignTest` with the harness's own tests and one property per module that runs in the normal test phase. - `docs/security/fuzzing.md`: targets, properties, limits, seeds and the replay command. `README.md`: one sentence on the gates. Baselines (instructions / lines): | Module | Gate | This head, Windows | CI image (Linux) | `develop` before this PR | |---|---|---|---|---| | `renderer` | 94% / 91% | 94.11% / 91.44% | 94.08% / 91.38% | 93.43% / 90.51% | | `bridges/renderer` | 85% / 82% | 85.77% / 82.75% | 85.61% / 82.64% | 85.10% / 82.05% | | `foundation` | 85% instructions, 90% classes (unchanged) | 93.46% / 92.12% | 93.46% / 92.12% | 93.19% / 91.82% | The gates are the head's measurement rounded down to a whole percent; the corpus tests of commit 1 are what raised the two modules above `develop`. The CI image run was the same sources before the gate values were written and with the campaigns at 4000 iterations (now 20000). Reviewer, please look at: - **The gates fail when they should.** Each was proved with a deliberate miss, then reverted: - an untested class in `com.kingsrook.qbits.renderer.scene2`: `Rule violated for package com.kingsrook.qbits.renderer.scene2: lines covered ratio is 0.00, but expected minimum is 1.00` - an untested `AssetInspector`: `Rule violated for class com.kingsrook.qbits.renderer.AssetInspector: lines covered ratio is 0.00, but expected minimum is 1.00` - the same untested code against the renderer baseline: `Rule violated for bundle qbit-document-renderer: instructions covered ratio is 0.93, but expected minimum is 0.94` and `lines covered ratio is 0.90, but expected minimum is 0.91` - an untested `ZplRaster`: `Rule violated for class com.kingsrook.qbits.documentgeneration.renderer.ZplRaster: lines covered ratio is 0.00, but expected minimum is 1.00` - an untested method added to `GenerationPreviewWidget`: `Rule violated for class com.kingsrook.qbits.documentgeneration.GenerationPreviewWidget: lines covered ratio is 0.00, but expected minimum is 1.00` - the harness itself: `MutationCampaignTest.aCrashAndAnUnsafeAcceptanceAreFindingsThatReplay` feeds it a target that crashes and one that accepts what it should refuse, and requires both to be reported. - **The baseline margins are thin by design.** The renderer instruction gate is 15 instructions under the measurement. The bridge line gate is 6 to 7 lines under it; bridge coverage moved by one line between two runs (`WarmRendererPool`, timing) and differs by one line between Windows and Linux (`BoundedProcess`). - **No skip switch.** The checks are bound to `verify` with no property to turn them off. - **The properties are not crash-only.** The scene parser campaign checks, with a second parser, that whatever version 1 accepts is a version 1 scene of known elements; the printer gate campaign checks that whatever the gate accepts holds only the renderer's command set. Both must reach acceptance and refusal. The gate campaign's first run showed a refusal type the property had not declared (`CharacterCodingException` for field text that is not UTF-8); it is a refusal, not a defect, and is now named. - **Not done here.** K22-TEST-25 also asks for `docs/security/assurance.json` and a weekly long campaign. The design names only `fuzzing.md`; both gaps are recorded in its review record. The long campaign (100000 iterations, both seeds, both targets) was run by hand and passed. ## P6a. Ports and registration hooks (commit 3) Added in `GenerationPorts`: `Diagnostic` (with `Severity`), `PreviewRequest`, `PreviewPage`, `Preview`, 15 version 2 `FailureCode` values, `RenderException(FailureCode, Diagnostic)`, `IsolatedRenderer.preview` as a default that refuses, and `Integer targetDpi` on `RenderRequest` with the seven-argument constructor kept. Five new classes that do nothing yet, each already called from its registration point: `GenerationPreviewProcesses`, `GenerationAssetProcesses`, `GenerationUpgradeProcesses` and `GenerationAssetTables` from the producer, `GenerationPreviewWidget.section(table)` from `GenerationTables`. Tests: `GenerationPortsContractTest` (record validation, default refusals, existing constructors and an adapter written before the port) and `GenerationRegistrationHooksTest` (the producer registers exactly the 13 tables, 28 processes, 11 possible value sources, no widgets and four template sections it did before; the lists were captured from the untouched tag). Reviewer, please look at: - **Nothing breaks an existing host adapter.** `preview` is a default method; `RenderRequest` and `RenderException` keep their constructors; the bridge and the service still call the seven-argument form and ignore `targetDpi` until P5 and P7. - **Diagnostics cannot hold free text.** `code` is checked against a closed vocabulary by severity (an error is a `FailureCode` name; warnings and information are the fixed names of design section 8.1), `element` is the author-id grammar, `box` is four integers, and `measured` and `limit` are at most eight integers under identifier names. - **Where the design and the code disagreed (the code won):** 1. The design puts the new `FailureCode` values in P6a and lists no bridge file. But `IsolatedRendererBridge` maps any `FailureCode` name a 0.1.0 worker sends to a typed refusal, and `BridgeTest` pins the count at 13. Growing the enum alone would have let a 0.1.0 worker name version 2 refusals. The bridge now keeps the 13 released codes as the set a 0.1.0 worker may name, and `BridgeTest` asserts the other 15 stay generic. P5 replaces this with its version rule. 2. Design 8.1 says `SCENE_INVALID` carries the JSON pointer of the offending property, but the diagnostic shape it gives has no field for one, and a pointer is text. `Diagnostic` follows the shape. P1 needs a decision (a bounded pointer grammar field, or the element id only). 3. The design gives no components for `PreviewRequest` and `PreviewPage`. They are `(actorId, format, revision, context, targetDpi, maximumBytes)` and `(png, widthDots, heightDots)`; `Preview` is exactly the six components of section 6.3. A page must start with the PNG signature, and a preview with an error diagnostic cannot say `printable`. 4. `targetDpi` is validated in the record (absent, 203, 300 or 600), because P7's file list does not include `GenerationPorts`. ## Build `./mvnw -B -ntp -T1C verify` at the repository root (the CI command, `mvn -T1C verify`), on the head of this branch, with every gate: **BUILD SUCCESS** on `c6aa0bf` (Temurin 21.0.12, Windows, Docker for Testcontainers). 650 tests, 0 failures, 0 errors, 0 skipped: foundation 254, renderer 222, bridges/renderer 98, remote-renderer transport 19, record-files 19, printing 16, OpenHTML 15, scripting 7. Checkstyle clean in every module, Error Prone and `-Werror` clean, and all three coverage checks met. The build used a settings file with the QRun-IO registry profile, as the CI settings do. The same command also passed in the CI image (`maven:3.9.11-eclipse-temurin-21`, Temurin 21.0.9, MySQL and PostgreSQL through Testcontainers) on these sources before the gate values were written: 650 tests, BUILD SUCCESS. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james.maes added 3 commits 2026-11-11 23:36:07 +00:00

test(renderer): version 1 scene compatibility corpus from v1.1.0-RC.2 (P0) ... ea776391ca

Version 1 scenes (qqq-zpl-scene/1) are frozen. This adds 42 render requests
and the exact ZPL the released renderer returned for each, so later work can
prove that labels already printing are untouched.

- renderer/src/test/resources/compat-v1: cases, stored ZPL, SHA256SUMS and a
  README with provenance and rules. The bytes were produced by the source of
  tag v1.1.0-RC.2 (e9ffba48), not by this branch, and the same test passed
  against the tag on Temurin 21.0.12 (Windows) and 21.0.9 (the CI image).
- renderer ZplSceneOneCompatibilityTest: fails on the first differing byte,
  on a manifest that does not name exactly the cases, and on a corpus that
  misses a version 1 element type, property or resolution.
- bridges/renderer ZplSceneOneCompatibilityTest: every stored output has its
  manifest hash and passes the unchanged ZplOutputPolicy. It reads the
  renderer's directory in place, so there is one copy of the corpus.

Covered: the four shapes Forge publishes at 203 and 300 dpi (GS1-128 with
fit and quiet, text in font 0, rasterText with fontAsset), the README and
BARCODE-FIT.md examples, and one scene per element and option at 203, 300
and 600 dpi. All values are synthetic.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

build(coverage): gate renderer and bridge coverage at baseline; seeded mutation campaigns (P13) ... 3ba676106f

Coverage gates:
- renderer and bridges/renderer gain JaCoCo (prepare-agent, report, check at
  verify) with a bundle rule at the measured baseline, rounded down: renderer
  94% instructions and 91% lines, bridge 85% instructions and 82% lines.
- New code is held to 100% line coverage from its first commit: packages
  com.kingsrook.qbits.renderer.scene2 and below, AssetInspector, ZplRaster,
  and the new foundation classes the label layout design names. The rules
  match nothing until those exist, so later packages do not edit these poms.
- The foundation's 85% instruction and 90% class rule is unchanged.

Fuzz scaffolding:
- MutationCampaign in each module's test tree: a seeded, bounded mutation
  harness with no clock and no unseeded randomness; a finding replays from
  its seed and iteration.
- One campaign per module in the normal test phase: what the version 1 scene
  parser accepts is a version 1 scene (checked by a second parser), and what
  the host printer gate accepts holds only the renderer's command set.
- docs/security/fuzzing.md: targets, properties, limits, seeds and replay.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

feat(foundation): preview, diagnostic and render target ports with registration hooks (P6a) ... c6aa0bf6b0

The contracts the preview, bridge and render target packages plug into. No
label prints differently and no existing host adapter changes.

GenerationPorts:
- Diagnostic (with Severity): a code from a closed vocabulary, an author
  element id, a box and named integers. It has no field that holds free text.
- PreviewRequest, PreviewPage and Preview, and IsolatedRenderer.preview as a
  default that refuses, so an adapter written before it compiles unchanged.
- 15 version 2 FailureCode values after the 13 released ones, and
  RenderException(FailureCode, Diagnostic) beside the existing constructor.
- Integer targetDpi on RenderRequest (absent, 203, 300 or 600); the
  seven-argument constructor is kept and nothing reads the value yet.

Registration points, each an empty class that is already called:
GenerationPreviewProcesses, GenerationAssetProcesses,
GenerationUpgradeProcesses and GenerationAssetTables from the producer, and
GenerationPreviewWidget.section(table) from GenerationTables.

Bridge: IsolatedRendererBridge maps any FailureCode name from a 0.1.0 worker
to a typed refusal, so growing the enum alone would have widened what such a
worker can name. The 13 released codes are now the set a 0.1.0 worker may
name; BridgeTest asserts the other 15 stay generic.

Tests: record validation, default refusals, source compatibility of the
existing constructors, and that the producer registers exactly the tables,
processes, choices, widgets and template sections it did before (the lists
were captured from the untouched v1.1.0-RC.2 tag).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

james.maes merged commit fda9ad0de6 into develop 2026-11-12 15:15:18 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

forge-recovery (Forge Recovery) james.maes (James Maes)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qbit-document-generation#13