Refactor compiler/materializer boundary around one canonical WordPress site plan

[chubes4]

Problem

Blocks Engine and Static Site Importer have stabilized enough that their current compatibility layers are now a larger source of risk than the underlying transformations.

The compiler currently projects one result through several overlapping representations:

TransformerResult
  -> source_reports.compiled_site
  -> source_reports.materialization_plan
  -> MaterializationView
  -> SSI compiled envelope
  -> SSI artifacts/site projection

This duplicates schema interpretation, path and asset handling, diagnostics, and fallback behavior across repositories. It also leaves compiler behavior in SSI, including late HTML-to-block conversion, shell decomposition, SVG promotion, CSS/path rewriting, raw-HTML commerce inference, and source-specific orchestration.

Current complexity signals on trunk/main:

• php-transformer/src/HtmlToBlocks/HtmlTransformer.php: 8,005 lines.
• php-transformer/src/ArtifactCompiler/ArtifactCompiler.php: 3,087 lines.
• SSI includes/: 25,377 lines.
• SSI transformer adapter: 1,060 lines, primarily contract reshaping and compatibility probing.
• SSI theme generator: 3,241 lines spanning compilation, planning, validation, mutation, reconciliation, and reporting.

Goal

Establish one generic, versioned compiler-to-materializer contract and migrate SSI to consume it directly.

source adapters
  -> WebsiteArtifact
  -> Blocks Engine
  -> WordPressSitePlan
  -> SSI
  -> MaterializationReceipt

The target should reduce concepts and code paths rather than introduce a general pipeline framework.

Contract ownership

Blocks Engine

Owns:

• Website artifact normalization.
• HTML/CSS/source semantic analysis.
• Native block lowering and serialized block markup.
• Routes, navigation, template parts, theme files, and canonical asset references.
• Compiler diagnostics, provenance, dependencies, and quality signals.
• The canonical WordPressSitePlan schema and validator.

Static Site Importer

Owns:

• Plan schema validation and WordPress preflight.
• Safe WordPress page, theme, template-part, asset, and extension writes.
• Reconciliation of previously generated resources.
• Provenance attached to materialized WordPress resources.
• A canonical MaterializationReceipt describing writes, skips, failures, and resulting WordPress IDs.

Source and product adapters

Own:

• Figma decoding and scenegraph adaptation.
• URL crawling and archive ingestion.
• Product-specific bundle translation.
• Commerce inference policy.
• Codebox/Playground preview and validation orchestration.
• WordPress-to-static reverse export.

Proposed durable contracts

blocks-engine/website-artifact/v2

Generic source files, entrypoints, metadata, and provenance.

blocks-engine/wordpress-site-plan/v1

One authoritative WordPress-shaped plan containing:

• pages with stable source identity, target identity, and final serialized block markup.
• template_parts and templates with complete write payloads.
• theme_files and assets with canonical safe target paths, content encoding, media type, hash, and load metadata.
• dependencies and generic entity intents without product-specific inference.
• diagnostics, provenance, and source identity.
• Reconciliation identities required by SSI.

This replaces compiled_site, the current materialization_plan, MaterializationView, and SSI's private compiled-envelope projection as the compiler/materializer boundary.

static-site-importer/materialization-receipt/v1

Records applied and skipped operations, WordPress IDs, generated files, provenance, reconciliation results, partial failure state, and diagnostics.

Implementation phases

1. Add canonical plan fixtures and deterministic schema validation in Blocks Engine.
2. Project current compiler output into WordPressSitePlan without changing generated behavior.
3. Add a plan-only SSI materialization entrypoint and receipt contract.
4. Route existing artifact imports through compile-to-plan then plan materialization.
5. Delete SSI transformer-result reshaping and late HTML transformation.
6. Move remaining semantic transformations from SSI into Blocks Engine, guarded by solved-fixture evidence.
7. Move Figma, URL, commerce, preview/runtime orchestration, and reverse export behind source/product adapters.
8. Remove superseded representations after all in-repository consumers migrate.
9. Decompose large compiler classes into explicit parse, analyze, classify, lower, style, serialize, and diagnose responsibilities only where the extracted responsibility is independently testable.

Acceptance criteria

• SSI's core materializer accepts one canonical WordPressSitePlan and does not inspect TransformerResult, compiled_site, or MaterializationView.
• Every page entering SSI contains final serialized block markup; SSI performs no HTML-to-block fallback.
• Asset and path normalization have one canonical implementation per boundary.
• Plan validation fails before WordPress or filesystem mutation.
• Materialization returns a versioned receipt that distinguishes complete, rejected, and partial application.
• Existing solved fixtures retain their block validity, fallback, asset, route, editor, runtime, and visual evidence.
• Source-specific and product-specific adapters depend on the generic contracts; generic Blocks Engine and SSI code contain no product orchestration.
• Superseded compatibility projections are deleted once concrete consumers migrate.

Migration policy

This refactor changes extension-facing paths and public machine-readable contracts. Before deleting an existing schema or hook, inventory external consumers and document the migration. Compatibility adapters should exist only for confirmed external consumers or persisted artifacts, with an explicit removal condition.

Non-goals

• Rewriting stable transformation algorithms during the initial contract migration.
• Introducing a generic pass/plugin framework before concrete extracted responsibilities require one.
• Combining Blocks Engine and SSI into one package.
• Moving WordPress mutation into Blocks Engine.

Evidence baseline

Use the existing solved-fixture corpus and SSI fixture matrix as the behavioral baseline. Contract tests alone are insufficient: the migration must preserve the resulting editable WordPress site, generated theme assets, editor validity, runtime behavior, and visual evidence.