Automattic / Automattic/blocks-engine
Separate PHP block-compilation outputs from diagnostic reports
- Dominant language
- PHP
- Stars
- 14
- Forks
- 2
- Avg merge
- 2h 10m
- Merged PRs (30d)
- 561
Description
## Problem
The PHP result surface mixes required block-compilation outputs with diagnostic evidence under `source_reports`. `ArtifactCompiler::compileHtmlDocumentBlocks()` reads generated companion definitions, runtime islands, stylesheet/script projections, responsive contracts, shared-shell block data and provenance from that map. These are operational inputs, not disposable reports.
The earlier claim that consumers do not depend on the report surface was incomplete: it overlooked the PHP transformer-to-artifact-compiler boundary. Dropping those fields would lose capabilities. The result-composition extraction in #1600 is now merged, providing a seam to correct ownership.
## Current Bite
- Give required block-compilation data one explicit owning result surface at the `HtmlTransformer` to `ArtifactCompiler` boundary.
- Have artifact compilation read operational data directly from that surface rather than from diagnostic projections.
- Compose the shipped reporting envelope from the same authoritative outputs, preserving its existing keys, ordering and behavior.
- Keep blocks, generated companion definitions/assets, runtime/style requirements, fallbacks and provenance intact. Classify policy/quality inputs by their actual use; data required to enforce acceptance is not optional merely because its current name contains report.
- Keep the change focused on source-to-block compilation. SSI output strategies and generic non-block fragment extraction are outside Blocks Engine scope.
An optional reduced-evidence mode is a follow-up after this boundary is proven. This slice should not introduce a lossy reporting flag or another generic framework.
## Acceptance
- Every corpus fixture retains identical serialized-block hashes, with zero new exceptions.
- Representative default `TransformerResult` envelopes remain equal, excluding only documented volatile duration metrics.
- Real artifact compilations retain equivalent companion payloads, generated assets, required runtime/style declarations, fallback/provenance data and WordPress block site plans.
- Coverage exercises companion blocks and authored runtime/styles, not only plain paragraphs or implementation-shape assertions.
- Existing canonical, parity, WordPress integration and packaging gates pass on supported environments; any environment-specific baseline failures are documented with direct comparisons.
- Operational consumers no longer reconstruct required outputs from `source_reports`; any remaining report reads are explicitly diagnostic or policy aggregation.
## Follow-Up
Once operational outputs and required policy outcomes are independent of optional reporting, introduce an explicit evidence option with the current full surface as the default. Preserve all required compilation capabilities and make uncomputed evidence explicit rather than claiming acceptance without proof.
## Historical Measurement
At historical trunk `f8e12d04`, instrumentation across the nine enterprise-B2B fixture pages attributed about 528ms of 7,037ms (7.5%) to the in-band evidence surface, dominated by semantic parity. These are historical measurements, not a current performance claim. This work is primarily an ownership/layering correction; throughput remains separate (#1044).
## AI Assistance
The original instrumentation and issue were prepared by Claude Sonnet 4.6 via Claude Code. GPT-6 Astra via OpenCode inspected current producer/consumer source, identified the operational dependency and prior lossy-mode risk, and revised this scope under Chris Huber’s direction. The implementation is being delegated to OpenAI GPT-5.6 Terra via direct OpenCode execution.
Contributor guide
Research direction
Start at the HtmlTransformer-to-ArtifactCompiler boundary, especially ArtifactCompiler::compileHtmlDocumentBlocks(), and trace which operational data currently comes from source_reports. Compare corpus fixture serialized-block hashes and default TransformerResult envelopes, then run the canonical, parity, WordPress integration, and packaging gates. Done means operational consumers use the owning result surface while reporting keys, ordering, behavior, assets, runtime/style declarations, fallbacks, provenance, and site plans remain equivalent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, wordpress
- Domain
- backend, backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100