james.maesandClaude Fable 5.2 589b6d41ee
maven / build (push) Successful in 10m28s
build / maven (push) Successful in 10m28s
fix(renderer): scene 2 text after independent review: a proof that never cuts, a bounded shrink search, named refusals
The proof of `maxLength`
- The proof never cuts. With `overflow: truncate` the proof was given a cut
  block, which counts as fitting, so a bound element whose box held ten
  characters validated clean with `maxLength: 40` and every long value was cut
  at print. The proof now runs with cutting off. When it fails, an element
  that did not ask for cutting is refused as before; one that did still
  validates, since cutting is what its author chose, with the warning
  FIT_NOT_PROVEN at every validation carrying `measured.provenCharacters`,
  the longest length proven to fit whole (found by halving: fewer characters
  never fit worse), against `limit.characters`. No new code: FIT_NOT_PROVEN
  already means that the fit of a bound value is not proven.
- A bound element with `maxLength` is judged for legibility, when validated,
  at the size the proof shrank to (the floor when it fails and the element
  cuts), not at its stated size.

The shrink search
- The size chosen is still exactly the one a search of every quarter-point
  step gives, but that search is no longer made. A count that errs only
  toward yes says whether a size could hold the text: lines filled at any
  character, each held to a width no real line can be under, and a block to
  its lines' ascent, pitches and descent. It never refuses a size that fits
  and, once it allows a size, allows every smaller one, so the largest size it
  allows is found by halving and only the steps from there are laid out. When
  one line at the floor is higher than the box nothing is searched, and a cut
  tries no line count the box is too low for.
- 1024 characters at 600 dpi from 1000 pt to 1 pt took 180 to 250 ms a fit and
  now takes under 1 ms: at most 21 555 characters visited where the search of
  every size visits 15.6 million.
- A text is fitted once: what `check` composed is what `paint` draws.
- The text of one scene may take 64 million steps (a character visited while
  fitting is one, a character to be drawn 16, a glyph the scene draws for the
  first time at a size 4096, since the runtime rasterises it once). The
  element that passes it, and every text after it, is SCENE_INVALID at the
  element with `textWorkSteps`, as the painted-area limit is. The count is
  integer arithmetic: the same on every machine, and the same validated or
  rendered. A thousand of the worst elements validate in well under a second.

Ink outside the measure
- TEXT_INK_OUTSIDE_MEASURE was an IllegalStateException thrown while
  painting, which failed the whole render after part of the text was on the
  label. The dots of a text are now gathered first and reach the label only
  when none strayed; otherwise the one element is refused as
  TEXT_DOES_NOT_FIT with `glyphsOutsideMeasure` and `dotsOutsideMeasure`. A
  literal is held to the glyph bounds when the scene is validated.
- The bound is tested at 1, 2, 300 and 1000 pt as well as from 5 to 72 pt, for
  every character of every face at the three resolutions; nothing strays.

Schema and vocabulary
- `fit` declares `maxLines`, `shrinkTo` and `overflow` under `properties` with
  `additionalProperties: false`. The three names are in the renderer's and the
  host bridge's pointer vocabularies, and a wrong member is reported at the
  member (`/elements/3/fit/maxLines`, or in the override that states `fit`).
- A bound number is printed as the schema says: plain decimal digits, no
  exponent, no fraction that is only zeros (`1.0E10` prints `10000000000`,
  `2.50` prints `2.5`). A number that is not finite is VALUE_MISSING.

Tests
- The widest-advance check covers every character a face draws, inked or not
  (a no-break space advances the pen), so a font update cannot break the proof
  unseen.
- Property: `fit` equals the search of every size, block for block, over 3600
  generated texts, boxes, sizes, floors and line counts.
- The goldens are unchanged. A README beside them records the JDK builds and the
  FreeType each ships.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 14:58:53 -06:00

QBit Document Generation

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.

Start with current status and build prerequisites and known issues. These documents supersede older release-readiness statements below.

foundation/ owns metadata, revisions, requests and audit contracts. renderer/ contains rendering and vendored corresponding source. bridges/ contains optional integrations. The root Maven reactor lists all modules.

Java 21 implementation of user-defined document metadata and generation coordination. Built against public QQQ 4.1.0-RC.21. This is a development snapshot, not a qualified production 1.0 renderer.

The QBit owns document types, stock, table bindings, template drafts, immutable published revisions, named asset-version references, batch pins and generation requests. It does not own retained file bytes, a scripting engine, a printer queue, or a generic workflow framework.

Implemented

  • Native, visible document_generation_* tables. Direct writes are denied; validated Java services own changes. Draft HTML/PDF and ZPL fields carry QQQ CODE_EDITOR metadata.
  • User-defined types, table/output bindings and exact physical stock in micrometres, margins and DPI. Source and manifest sizes are bounded.
  • Separate draft saves and publication. Publication requires isolated source validation, plus published-script validation when a context script is configured. Revisions copy stock and pin immutable asset/script identities.
  • Authorized single-record and bounded synchronous batch generation. Batch revision and selection hashes persist across repeated calls, and partial failures remain explicit.
  • Matching durable retained-file receipts and strict audit callbacks before success or printing. Request tables contain receipt/provenance fields, never document bytes or context bodies.
  • Reprint through current retained-version authorization, without rerendering. Queue acceptance is reported as QUEUED, never as physical printing.
  • Stable request keys prevent blind duplicate execution. Incomplete work requires reconciliation; this implementation does not claim exactly-once processing.
  • Native definition/source editing, display-name renames for types, stock and templates, immutable retained previews and optimistic draft/publication forms in a Document Generation workspace. See authoring.
  • Durable generation-owned queue/items, independent strict audit, bounded admission/cursors and conservative recovery. Native source record/batch/status/download/reprint processes call the same services. See queue.
  • Explicit opt-in adapter to existing core Jobs with cooperative checkpoints; no additional scheduler. See Jobs for verification state and host requirements.

Host integration

Install metadata with DocumentGenerationQBitProducer.withQBitConfig(config).produce(instance). Configure a backend through DocumentGenerationQBitConfig.withBackendName(...). Registration never runs DDL automatically. Apply DocumentGenerationSchema.mysqlScript(config) through host migration tooling for native MySQL 8.4. postgresScript(config) generates the same tables for the native QQQ PostgreSQL 17 backend (and the file-H2 fixture); the PostgreSQL publication, audit and queue suites pass against postgres:17 with QQQ 4.1.0-RC.21 (see Verification), but, as with MySQL, that does not qualify a production deployment. See MySQL qualification for required current engine/settings, metadata mappings and deployment boundaries.

Use DocumentDefinitionService for types, stock, bindings, assets, drafts and publication. Use DocumentGenerationService.generate, generateBatch and reprint for operational work. Permissions are separate document-generation.view, .configure, .publish, .generate and .print; each generation/print additionally enforces current source-record access.

The host supplies these typed contracts from GenerationPorts:

Port Required behavior
ContextExecution Validate a published immutable build and run it in the shared isolated scripting service; broker QQQ access under the initiating actor.
IsolatedRenderer Authorize assets, validate sources and render in a qualified isolated worker. Enforce time/memory/network/input limits and output/ZPL policies before returning.
RetainedOutputIntake Idempotently retain exact bytes plus source association, return matching hash/length and a committed receipt; reauthorize immutable versions for reprint.
PrintDispatch Reauthorize retained version and destination and submit idempotently to existing printing; return a queue job ID.
Audit Independently commit deduplicated generation/print outcomes before returning; throw on failure. This is not core's best-effort AuditAction.
AssetSelection Search and resolve currently authorized, released immutable image/font versions; obtain hash/media/length from the owner, never from a browser claim.

Every default provider fails closed. No adapter calls the trusted in-process rendering proof. Template source is never evaluated by this QBit's JVM code. Optional bridges/scripting, bridges/renderer and bridges/record-files artifacts implement public integration boundaries without dependency cycles. The renderer bridge has a fail-closed production constructor (runsc, pinned digest) and, for trusted local development only, an explicit cold Java transport (TrustedLocalDockerExchange) and an optional warm single-use pool; both are non-production, never automatic fallbacks, and documented in bridges/renderer. The supported durable storage is native MySQL 8.4, native PostgreSQL 17 and synchronous file H2. The host worker/renderer configuration is operator-owned and unqualified until a deployment supplies matching external evidence. Printing integration and the latest owner download extension are tracked separately. A callback alone does not establish production durability or isolation: its implementation and deployment must meet the contract and pass integration tests.

Context contains bounded immutable JSON-like data, including the authorized selected record. A script may add context objects but cannot replace that reserved original record. Credentials, QQQ sessions, raw host objects and lazy entities are rejected. Source-record permissions are checked before context preparation, before rendering, before intake and before printing. Asset access is rechecked by the isolated renderer adapter, and retained-version access by retained/printing adapters.

Known boundaries before release

Native table/record processes and source-editor forms are implemented through standard QQQ metadata. Results include record navigation and download/preview metadata consumed by generic frontend components. Authenticated delivery requires verified bytes and a completed owner receipt before preview. There is no visual designer. Final integrated browser workflow acceptance, a qualified worker deployment, production storage/restore and printing integration remain release work. Service-only fields cannot be edited through unrestricted generic CRUD. Domain actions use validated services.

The original generateBatch API remains synchronous; GenerationQueue provides separate durable queued selections. Native publication locks and compares the draft fingerprint after isolated validation, then commits the immutable revision and active pointer atomically. Publication rejects ambient and split-backend transactions; memory is a volatile test fixture only. Request states and external side effects do not share one transaction. Generation rejects ambient caller transactions. Known retained versions can be reconciled without rerendering. Unknown intake outcomes and abandoned invocations require owner evidence and a trusted termination provider; they are never automatically recycled into untouched work.

The definition permission model is application-wide: configuration grants cover all definitions. Requests require source access; batches are visible only to their initiating actor. Counts and aggregates on request/batch tables are denied because post-query parent filtering cannot make those totals safe. Private queue context/lease fields cannot be queried, sorted, joined or used as unique keys through enforced native actions. Per-tenant template authoring scopes and efficient SQL-level parent filtering need explicit qualification. Explicit retained-owner authority supports archived exact-version history and operational access; without that port the live-source policy remains. See retained authority.

Production gates still include volume/retained-storage restore; isolated compiler/renderer containment; physical barcode/printer acceptance; user-defined filename/output options; complete host browser workflows; and dependency/license checks. Standalone renderer catalog 9 offers 71 explicit barcode IDs (finite, not universal; see renderer/BARCODES.md). Its trusted warm-engine benchmark is documented in renderer/PERFORMANCE.md and does not establish sandbox/end-to-end capacity. Strict ledger/queue durability accepts synchronous file-H2 and explicitly qualified native MySQL 8.4 and PostgreSQL 17; unsupported backends and metadata/settings drift fail closed.

Modules

Directory Artifact Notes
foundation com.kingsrook.qbits:qbit-document-generation Metadata, services, ports and schema. Depends on QQQ core only (RDBMS optional).
renderer/vendor/openhtml-1.1.105-qqq-p1 com.kingsrook.thirdparty:openhtmltopdf-pdfbox:<family revision> (upstream 1.1.105 + QQQ patch p1) LGPL-2.1-or-later patched OpenHTML (one file differs from upstream 1.1.105), built from the tracked source with its notices; the renderer depends on it.
renderer com.kingsrook.qbits:qbit-document-renderer Standalone isolated renderer CLI/image source; no QQQ dependency.
bridges/renderer qbit-document-generation-renderer IsolatedRenderer port implementation for the renderer.
bridges/remote-renderer remote-renderer-parent -> qqq-remote-renderer-transport, qbit-document-generation-remote-renderer Remote renderer service and adapter.
bridges/record-files, bridges/printing, bridges/scripting qbit-document-generation-record-files, -printing, -scripting Bridges to sibling QBits (Record Files, released Printing 1.0.0, Scripting).

The root pom.xml is an aggregator only and lists every module, so one build produces every GAV. Each module keeps its own dependency boundary. Build a subset with ./mvnw -pl <module> -am install (for example -pl renderer -am builds the patched OpenHTML module first); a module also builds alone with mvn -f <module>/pom.xml install once its dependencies are installed. All modules share one ${revision} (default 0.1.0-SNAPSHOT; releases set -Drevision=<version>), and flatten-maven-plugin publishes self-contained POMs.

Verification

Run ./mvnw verify (.\mvnw.cmd verify on Windows) at the repository root. The foundation's tests include disposable MySQL 8.4 and PostgreSQL suites started with Testcontainers, so Docker access is required. They verify publication concurrency/commit/rollback, physical pooled-connection restoration, mapping/settings drift refusal, bounded lock contention, current-authorized context selection and immutable pins, audit/receipt failures, restart and incomplete results. They do not qualify production storage, hostile workers or physical printer output.

The build enforces Checkstyle plus 85% instruction/90% class coverage in the foundation, and holds the renderer (94% instructions, 91% lines) and its bridge (85% instructions, 82% lines) to their measured baselines; the new packages and classes named in each pom.xml must reach 100% line coverage. Bounded mutation campaigns over the scene parser and the host printer gate run in the test phase; see docs/security/fuzzing.md. The published qbit-build-parent POMs leave ${revision} in their own version, which causes a Maven parent-resolution warning despite a successful build. That upstream publication issue remains open; it is neither suppressed nor patched.

Maven publication

Library POMs are flattened (ossrh mode) so an installed POM carries resolved versions and needs no -Drevision. Dependencies on the sibling QBits are properties (qbit-record-files.version, qbit-scripting.version, qbit-printing.version) so the owners' released versions can be set in one place.

Corresponding source and licenses

renderer/vendor carries the hash-pinned corresponding-source archives next to their patches and build scripts: zint-2.16.0.tar.gz (GPL/BSD/MIT notices in LICENSE.zint, MIT-ZINGL.txt) and openhtml-1.1.105-qqq-p1/openhtmltopdf-pdfbox-1.1.105-qqq-p1-complete-source.zip (LGPL-2.1-or-later). inputs.sha256 files pin them; openhtml-1.1.105-qqq-p1/verify-module-source.sh proves the Maven module's pom.xml and src/ are byte-identical to the archive. Release artifacts and images must ship these notices and sources, not just a URL.

S
Description
No description provided
Readme
8.7 MiB
0 Stars 2 Watchers 0 Forks
Languages
Zimpl 54.2%
Java 45.7%