0.2.1 Release Candidate | Promotion

[mberrys]

[0.2.1] Operator Completion, Product Surface & Trust Leftovers

Promotes unstable → stable for the 0.2.1 milestone (GitHub milestone 17) — the patch on the 0.2.0 line that closes the operator, product-surface and trust leftovers before governed-correction work starts in 0.3.0.

Scope: 0.2.0.1-alpha (86ee1b5b) → d2e9ce9f — 105 non-merge commits.
Canonical milestone text: docs/github-milestones/0.2.1.md.

Riding this promotion from PR #517, whose fragment is changes/0.2.2.md after that branch name: #144 (async interactive-thread boundary) and #146 (interaction-trace contract evaluator).

Added

• Loop UI design system ([0.2.1] Define and implement the Loupe UI design system #194) — pdfquick::tokens (LoopLibQuick/sources/looptokens.{h,cpp}): 4-px spacing scale and a semantic ColorRole set resolved per LoopTheme (Dark/Light/HighContrast), plus non-color cues so a status never reads by hue alone. resolveStateVisual() (loopstatevisual.{h,cpp}) is the one canonical finding/check presentation, and it holds the two invariants [0.2.1] Define and implement the Loupe UI design system #194 is actually about: an incomplete check and an actively waived finding never render as a pass. docs/LOOP_DESIGN_SYSTEM.md carries the token table with WCAG contrast figures and the current adoption state; UnitTestsLoopStateVisual is table-driven over severities, check statuses, waive decisions and out-of-schema inputs.
• Preflight as a first-class Editor workflow ([0.2.1] Expose the existing preflight engine as a first-class Loupe GUI workflow #195) — PreflightPane is now a state/run/cancel/export surface with profile selection and typed variables; the document badge renders Core's verdict through the canonical state kinds; the exported report is pinned against PdfTool preflight by a parity suite; UnitTestsPreflightInteraction is registered and revived, restoring the sidecar contract coverage the retired plugin suite held.
• Application shell and information architecture ([0.2.0] Build the Loupe application shell and information architecture #193) — typed seven-workspace model with a contextual inspector dock, operator toolbar, manifest-driven menus, always-visible document / production / preflight status, and interaction-to-inspector dispatch for all selection kinds, with workspace, menu-policy and inspector-dispatch tests. Compare stays a disabled rail entry pending a product decision; Production Preview, Pages/Production and Fix keep placeholder pane content ([shell] Enabled workspaces render placeholder panes and the Select/Hand controls dispatch nothing #560).
• Prepress Inspector ([0.2.0] Build a Prepress Inspector docked to preflight findings #127) — report-backed InspectorPane plus pdfinteraction::InspectorModel, rendering only facts a finding's evidence already carries (so the report and the Inspector cannot disagree), with navigate-to-finding and corrective-operation request signals on selection.
• Finding → canvas navigation and contextual inspection ([0.2.1] Connect preflight findings to canvas navigation and contextual inspection #196) — per-check targeting capability (page / object / overlay / inspection mode) with an honest fallback that navigates to the page, says object targeting is unavailable and changes nothing else; zoom-to-finding, revision-aware canvas invalidation, overlay-click and keyboard prev/next navigation, covered by UnitTestsFindingNavigation and shell/inspector tests.
• GUI and end-to-end coverage for the operator loop ([0.2.0] Add GUI and end-to-end automated test coverage for the operator loop #170) — UnitTestsProductOperatorLoop drives the Quick shell offscreen end to end; canvas-parity and Quick accessibility-smoke coverage; the smoke compiles the same QML the product ships, enforced by a byte-parity guard over the LoopEditor/qml mirrors.
• Async interactive-thread boundary and interaction-trace contract ([0.8.0] Enforce async boundaries for preflight, OCR, AI, and file I/O #144, [0.8.0] Automate interaction-performance regression traces #146) — pdf::PDFBlockingThreadGuard refuses to run a blocking service on the registered interactive (canvas) thread, and PDFJobKind identifies async work in job traces; pdfinteraction::evaluateTraceContracts() names the first contract a trace run violated and the phase responsible.
• Release gates for the search budget and the independent-validation oracle ([0.3.0] Institutionalize independent standards and renderer validation #241) — scripts/ci/check_search_budget_gate.py and scripts/ci/check_independent_validation_gate.py, wired into ci.yml source_integrity and into check-change.py.

Changed

• One verdict reducer on every surface ([0.2.1] Canonical preflight verdict reducer shared by every surface #234) — pdf::reducePreflightVerdict() is the single Core verdict (Pass / Fail / Incomplete / Error) consumed by Editor copy, PageMaster gate messages, Action List postflight steps and the certificate-issuance gate; budget exhaustion with zero findings is Incomplete (exit 8), never PASS. A whole-tree guard fails the build if any GUI source derives a pass or severity of its own.
• Standards conversion now flattens live transparency ([Prepress] Add PDF/X and PDF/A conversion, not only validation #167, Standard-conversion PDF/X profile was rejected by PreflightEngine, so no PDF/X rule ever ran (fixed by PR #554) #556, PDFRgbToCmykFixup cannot convert RGB image XObjects, so PDF/X-1a conversion fails whenever content is rasterized #555) — standards-convert flattens before CMYK normalization, honours an explicit flatten opt-out, and skips flattening entirely when the document has no live transparency, so an already-opaque vector document is never replaced by full-page rasters; the flatten is reported verbatim under a new transparency_flatten report field, and the new flatten_transparency operation parameter is available identically from PdfTool repair and PageMaster export. The PDF/X profile now carries the checks PreflightEngine requires, so PDF/X rules actually run.
• Incremental write contract ([0.2.1] RC | Preflight & GUI Foundation  #554 review) — PDFDocumentWriter keeps its exported four-argument writeIncremental overloads (as forwarding overloads, default argument removed so a four-argument call stays unambiguous) and publishes IncrementalWriteOutcome only after a successful commit.
• Editor presentation and lifecycle — the findings model carries the verdict's waived findings instead of presenting them as blocking errors; EditorHost clears its interactive-thread registration on teardown; the verdict operator summary is translatable and is assigned before its notify signal fires.
• OCR sidecar language schema accepts the case the service normalizes; check-change.py resolves clang-tidy by name instead of hardcoding clang-tidy-18.

Fixed

• **_{_{}} Start a fresh processing budget for each search** #520 — searchDocumentText() allocates an operation-scoped PDFProcessingBudget, so an idle session's elapsed-timer exhaustion no longer throws through Quick search; exhaustion surfaces as complete=false / budgetExceeded=true, with UnitTestsDocumentSearch regression coverage.
• Standard-conversion PDF/X profile was rejected by PreflightEngine, so no PDF/X rule ever ran (fixed by PR #554) #556 — the standard-conversion PDF/X profile was missing the checks PreflightEngine requires, so preview() reported no blockers for any PDF/X target and every PDF/X conversion failed at postflight.
• PDFRgbToCmykFixup cannot convert RGB image XObjects, so PDF/X-1a conversion fails whenever content is rasterized #555 — PDFRgbToCmykFixup converts supported RGB image samples through the CMS into CMYK ICCBased XObjects, so PDF/X-1a conversion no longer fails whenever content is rasterized.
• Hostile-input hardening (merged with fix: act on the post-0.2.0 exhaustive review findings #519/[0.2.1] RC | Preflight & GUI Foundation  #554) — unterminated CMap range operators fail closed with a deliberate diagnostic; sampled functions whose Domain/Encode are not 2 × m are rejected and their allocation bounded by the stream; tiling-pattern paint is bounded by a hard tile ceiling; the unfiltered inline-image row length is rounded once; xref entry count and the dense object table it implies are bounded; the JBIG2 referred-segment count is bounded before reserving; output-intent profile decoding is charged and the inline-image probe bounded; finished job closures are released and retained job history is bounded.
• Suites that could not fail (UnitTests/tst_preflightinteraction.cpp is not registered in any CMake target, so its PreflightController/FindingsModel slots never run #557, [preflight] UnitTestsPreflightVerdict::operatorSummaryIsCurrentWhenTheStateSignalFires fails on dev #562, A QSKIP lets the corpus and stress suites pass having compared nothing #563) — UnitTests/tst_preflightinteraction.cpp is registered in a CMake target and revived; the verdict operator-summary slot no longer depends on a signal that fired before assignment; the corpus and stress suites fail closed when a required fixture is absent instead of QSKIP-ing past the comparison, and the parity corpus fixture is now a hard failure rather than a skip.
• Quick build and verdict presentation ([quick] LoopLibQuick does not compile on dev: canvastraceoverlay.cpp uses QJsonArray without including it #561, [0.2.1] RC | Preflight & GUI Foundation  #554) — canvastraceoverlay.cpp includes the QJson headers it uses; Core's fail verdict maps to the Error treatment so preflight kinds stay distinct; a cancelled or failed run reports its terminal state instead of leaving the pane.
• Preflight corpus fixtures (fix: generate missing preflight corpus fixtures for dev CI #570) — added the transparency, ai-art and thin-parts-fill fixtures, unpended the malformed-not-pdf and overprint-multiply manifest rows, gave the overprint corpus pages real bleed and pinned the eleven rows that now pass.

Security

• PDFLogScrubber redacts all-alphabetic bearer credentials.
• Bounded allocation and retention on hostile input (see Fixed) closes the memory/DoS class reached by the processing-budget corpus work.
• Fixed the Semgrep and urllib findings and hardened the CI workflows (Improve CI workflow and address security findings #553).

Internal

• Architecture truth for the 0.2.1 gate ([0.2.1] Make ADRs and architecture docs a trustworthy source #235) — every ADR carries status and Last-verified metadata, docs/adr/README.md is a new index, generated catalogs are regenerated, the source-of-truth hierarchy is cross-linked in docs/architecture-source-of-truth.md, and docs/REPO_MAP.md and AGENTS.md no longer carry stale repository/default-branch claims. AGENTS.md additionally gains the internal-logic contract and the anti-slop review pass (docs(agent-policy): add the internal-logic contract and an anti-slop review pass #568).
• 0.2.1 canon — docs/github-milestones/0.2.1.md plus manifest and living-sequence updates across the milestone docs (docs: consolidate 0.2.1 GitHub milestone with leftover-work plan #518).
• Policy and proof registrations — UnitTestsBlockingThreadGuard and the budget-exhaustion suite mapped into agent-policy.json, the GUI preflight-truth and QML mirror-parity guards added to check-change.py, and check-change.py resolving clang-tidy by name.
• Docs hygiene — docs/v1-operator-acceptance.md and the readiness evidence repointed at code that exists, and the legacy product-name token removed from the design-system docs.

Closes

Closes #127
Closes #170
Closes #193
Closes #194
Closes #195
Closes #196
Closes #234
Closes #235
Closes #520
Closes #555
Closes #556
Closes #557
Closes #561
Closes #562
Closes #563
Closes #236

#236 (DocumentContext revision authority) closed on this milestone and already shipped in 0.2.0.1-alpha; its keyword here is documentary. Every other reference above is a dev/unstable landing whose issue is still open because closing keywords only take effect on the default branch — merging this PR into stable is what closes them.

Not closed by this promotion (deliberately, work continues):

Refs #241
Refs #125
Refs #163
Refs #559
Refs #560
Refs #569

#241 ships its release gates here, but the institutionalized acceptance criteria — the renderer-differential lane recording measurements rather than screenshots, and documented corpus licensing — are not in this patch. #263 (SBOM and signed provenance) is not planned for 0.2.1 and continues at 0.8.0-S07.

Verification

• CI, Documentation truth, Supply Chain Policy and CodeQL are green on unstable at d2e9ce9f.
• The RC into unstable ([0.2.1] RC | Preflight & GUI Foundation  #554) was green on agent-fast / build, policy, source_integrity, architecture-docs, fuzz and semgrep-cloud-platform/scan, plus package_script_tests on both runners.

Breaking changes

None. No public contract, schema version or persistence format changes: the export additions, the interaction-trace contract and the flatten_transparency parameter are additive, and the four-argument writeIncremental overloads are preserved.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}