Automattic / Automattic/blocks-engine

Separate PHP block-compilation outputs from diagnostic reports

Open
#1,360 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.