Wire transparency flattening into standards-convert (#167)

[mberrys]

Summary

Issue #167 ("Add PDF/X and PDF/A conversion, not only validation") turns out to already have substantial, working, registered Core scaffolding: standards-convert (LoopLibCore/sources/pdfstandardconversion.{h,cpp}) already converts to PDF/X-1a:2001, PDF/X-3:2002, PDF/X-4, and PDF/A-2b, produces a pre-conversion change report, is fail-closed, requires an independent validator before committing, and is already exposed identically through PdfTool's repair command and PageMaster's export job.

One concrete, verifiable gap remained: PDF/X-1a and PDF/X-3 forbid live transparency, and the issue explicitly calls flattening out as "a hard prerequisite for X-1a" — but standards-convert never called the existing PDFTransparencyFlattener operation (#164, already used as a separate PageMaster pipeline stage). Live transparency was therefore an unconditional, unfixable blocker in standards-convert even though Core already had a working flatten path.

This PR wires the two together, mirroring the existing RGB→CMYK integration in the same file exactly:

• PDFStandardConversionSettings::flattenTransparency (new; default-on for X-1a/X-3, matching the existing normalizeColor default pattern; opt-in for X-4/PDF-A, which permit live transparency).
• pdfx.transparency.allowed becomes a fixable preflight blocker only when flattening is requested/defaulted-on — fixtures with no live transparency are unaffected, since that rule already reports Passed when transparencyObjects == 0 (verified by reading preflightengine.cpp; the existing unconvertiblePdfxHasNoMarker test uses an empty-page fixture with zero transparency objects, so its blocker comes from elsewhere and is untouched by this change).
• The flatten runs before the output-intent/page-box rewrite in apply(), and its report is surfaced verbatim under a new transparency_flatten report field — a real, reported content change, never a silent approximation (matching the issue's "not an opaque generative editing system" boundary).
• New flatten_transparency operation parameter, available identically from PdfTool (repair --operation standards-convert --param flatten_transparency=...) and PageMaster's export job, since both already share the one Core implementation.

Also corrected two stale documentation claims found while investigating:

• docs/STANDARD_CONVERSION.md said an Editor adapter could land "after the 0.1.1 GUI gate." That gate is already complete; docs/LOOP_SHELL_CONTRACT.md is explicit that product GUI work instead remains gated by the still-closed S21 canvas / S22 Quick admission contracts, so this doc now points there instead of implying a stale timeline.
• docs/REPO_MAP.md's LoopEditorPlugins/ module does not exist in the current Qt-Quick-based tree (the app moved to LoopEditor/ + LoopLibInteraction/ + LoopLibQuick/). Noted in the new doc text so a future Editor adapter isn't scoped to a directory that no longer exists.

Why not more of #167?

• Editor integration ("identical semantics across Editor, PdfTool, and PageMaster") is explicitly out of scope right now: docs/loop-shell.json's plugin surface policy retires all 12 legacy Editor plugins from install (scripts/verify-plugin-surface-policies.py), and LOOP_SHELL_CONTRACT.md states product GUI work is gated behind S21/S22 admission contracts that are not yet open. Building GUI surface now would contradict current repo policy.
• PDF/X-3 and PDF/X-4 fixture-level test coverage (issue [Prepress] Add PDF/X and PDF/A conversion, not only validation #167's own "fixture set per target" test-strategy bullet) is genuinely missing — only PDF/A-2b and PDF/X-1a have apply()-level oracle tests today — but issue [0.2.1] Institutionalize independent standards and renderer validation #241 ("Institutionalize independent standards and renderer validation") explicitly owns "conversion fixtures... PDF/X-4 before broader variants" as its own scope, and issue [Prepress] Add PDF/X and PDF/A conversion, not only validation #167's own Aug 11 status comment already delegates independent-validation fixture work to [0.2.1] Institutionalize independent standards and renderer validation #241.
• Font embedding/subsetting remains detection-only (no repair operation exists) and stays a hard blocker, as documented — building that is a separate, much larger undertaking (issue Implement font embedding/subsetting with license and substitution safeguards #82 covered detection, not remediation).

Verification

No Qt/CMake toolchain is available in this sandbox, so I could not build or run UnitTestsStandardOracle / UnitTestsConversionOracle / UnitTestsRepairOperation locally. What I could run and did run, all passing:

• clang-format --dry-run --Werror on every touched file.
• python scripts/ci/check_source_integrity.py
• python scripts/generate-architecture-catalogs.py --check
• python scripts/agent/generate-adapters.py (adapters already current)
• python scripts/agent/check-change.py --base origin/dev: changelog, source_integrity, architecture_catalog, policy_adapters, and format:<every file I touched> all report pass. The build:*/focused_tests checks report fail only because no build directory exists in this environment — that's an environment limitation, not a result from this diff. I traced the exact API shapes (PDFTransparencyFlattener::apply/hasLiveTransparency, PDFTransparencyFlattenSettings, the CMake target list) by reading the source directly and mirrored an already-compiling, already-tested sibling code path line-for-line, but this PR's first real compile/test signal will be CI.

I'll watch this PR and fix anything CI turns up.

Test plan

• CI build (LoopLibCore and dependents) is green.
• UnitTestsStandardOracle, UnitTestsConversionOracle, UnitTestsRepairOperation pass unchanged (no regression to the existing unconvertible/oracle fixtures).
• scripts/agent/check-change.py --base origin/dev reports pass in CI where a real build directory exists.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JgoNmy614kqRiTBjiSjRJU

---

Generated by Claude Code

[mberrys]

CI on the first push failed 3 checks (source_integrity, policy, agent-fast / build), none caused by this PR's diff:

• test_repository_contract_passes failed identically in source_integrity and policy on 5 pre-existing "legacy product token" findings in files this PR never touches. I confirmed these files are byte-identical to origin/dev's own tip, so this already fails on dev.
• agent-fast / build failed because a workflow step's working-directory: loupe doesn't exist (checkout path is loop) — same pre-rebrand leftover, also already on dev.

A fix for exactly this already exists in open PR #518 (bundled there with unrelated 0.2.1 milestone doc changes), so I ported just the CI-relevant hunks here rather than duplicating the diagnosis or waiting on that PR to merge: .github/workflows/reusable-linux.yml/reusable-windows.yml (working-directory: loupe → loop) and the three loupe-processing-budget-exhaustion-corpus → loop-processing-budget-exhaustion-corpus schema-kind occurrences (UnitTests/testdata/budget-exhaustion/manifest.json, UnitTests/tst_budgetexhaustiontest.cpp, scripts/budget_exhaustion/generate_corpus.py). This topic branch was also 14 commits behind dev and didn't have these files yet, so I merged origin/dev in first (clean, no conflicts).

Verified locally: generate_corpus.py --check, test_check_loop_identity.py, the full scripts/ci/test_*.py suite (223 tests), check_source_integrity.py, check_supply_chain_pins.py, verify-loop-shell-contract.py, generate-architecture-catalogs.py --check, and clang-format all pass. Pushed as c3d610d; watching for the next CI run.

---

Generated by Claude Code

[mberrys]

Good news buried in that failure: agent-fast / build actually got far enough this time to run a real build, and it confirms the core change — build:LoopLibCore, build:UnitTestsConversionOracle, build:UnitTestsStandardOracle, and focused_tests (the ctest run) all reported pass. No regressions to the existing oracle/fixture tests, and the new transparency-flattening code compiles cleanly.

The only failure was one pre-existing clang-format violation in LoopLibCore/sources/pdftextlayoutgenerator.h (a single stray blank line, introduced by commit 6c628b4 already on this branch before this PR's work — not in this PR's diff, and not present on dev). Fixed in dcebaed (mechanical, whitespace-only). Watching for the next CI run.

---

Generated by Claude Code

[mberrys]

All 12 checks are green on dcebaed (CI/agent-fast build, source_integrity, policy, architecture-docs, fuzz, CodeQL ×3, Supply Chain Policy ×2). No merge conflicts, no open review threads. This PR is ready for human review — still in draft since I opened it; happy to mark ready or keep it draft, whichever the maintainer prefers.

---

Generated by Claude Code