Add bounded core/html fallback evidence (#838)

Add deterministic fallback reason taxonomy and bounded source/output evidence for transformer diagnostics.\n\nAI assistance: openai/gpt-5.6-sol via OpenCode was used to design, implement, test, and review the diagnostics. Chris Huber reviewed and remains responsible for the change.

Author: chubes4

php-transformer/src/ArtifactCompiler/ArtifactCompiler.php

@@ -6,6 +6,7 @@
 use Automattic\BlocksEngine\PhpTransformer\AssetAnalysis\CssUrlRewriter;
 use Automattic\BlocksEngine\PhpTransformer\AssetAnalysis\ReferenceAnalyzer;
 use Automattic\BlocksEngine\PhpTransformer\Contract\ConversionReportProjection;
+use Automattic\BlocksEngine\PhpTransformer\Contract\CoreHtmlFallbackEvidence;
 use Automattic\BlocksEngine\PhpTransformer\Contract\TransformerResult;
 use Automattic\BlocksEngine\PhpTransformer\FormatBridge\FormatBridge;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\HtmlTransformer;
@@ -172,12 +173,14 @@ public function compile(array $artifact): TransformerResult
         $allFallbacks = $entryBlocks['fallbacks'];
         $allGeneratedBlocks = $entryBlocks['generated_blocks'];
         $allGutenbergGaps = $entryBlocks['gutenberg_gaps'];
+        $coreHtmlFallbackEvidence = array($entryBlocks['core_html_fallback_evidence']);
         foreach ( $compiledHtmlDocuments as $sourcePath => $compiledHtmlDocument ) {
             $authorStylesheetProjections = array_merge($authorStylesheetProjections, $compiledHtmlDocument['author_stylesheet_projections'] ?? array());
             $allDiagnostics = array_merge($allDiagnostics, $this->entryTransformDiagnostics($compiledHtmlDocument['diagnostics'] ?? array(), (string) $sourcePath));
             $allFallbacks = array_merge($allFallbacks, $compiledHtmlDocument['fallbacks'] ?? array());
             $allGeneratedBlocks = array_merge($allGeneratedBlocks, $compiledHtmlDocument['generated_blocks'] ?? array());
             $allGutenbergGaps = array_merge($allGutenbergGaps, $compiledHtmlDocument['gutenberg_gaps'] ?? array());
+            $coreHtmlFallbackEvidence[] = $compiledHtmlDocument['core_html_fallback_evidence'] ?? array();
         }
         $allGutenbergGaps = $this->dedupeRows($allGutenbergGaps);
         $normalized['runtime_declarations'] = $this->runtimeDeclarationsFromFallbacks($normalized['runtime_declarations'], $allFallbacks, $entryPath, $normalized['files']);
@@ -207,6 +210,7 @@ public function compile(array $artifact): TransformerResult
             $serializedBlocks = (string) $documents['documents'][0]['block_markup'];
         }
         $sourceReports = array(
+            'core_html_fallback_evidence' => CoreHtmlFallbackEvidence::merge($coreHtmlFallbackEvidence),
             'artifact' => array(
                 'schema'          => self::INPUT_SCHEMA,
                 'original_schema' => is_string($artifact['schema'] ?? null) ? $artifact['schema'] : '',
@@ -676,7 +680,7 @@ public function compileFragment(string $content, string $source = 'fragment', st
 
     /**
      * @param array<int, array<string, mixed>> $files
-     * @return array{blocks: array<int, array<string, mixed>>, serialized_blocks: string, diagnostics: array<int, array<string, mixed>>, fallbacks: array<int, array<string, mixed>>, assets: array<int, array<string, mixed>>, runtime_islands: array<int, array<string, mixed>>, generated_blocks: array<int, array<string, mixed>>, gutenberg_gaps: array<int, array<string, mixed>>, interaction_candidates: array<int, array<string, mixed>>, superseded_selectors: array<int, string>, author_stylesheet_projections: array<int, array<string, mixed>>, shell_artifacts: array<int, array<string, mixed>>}
+     * @return array{blocks: array<int, array<string, mixed>>, serialized_blocks: string, diagnostics: array<int, array<string, mixed>>, fallbacks: array<int, array<string, mixed>>, assets: array<int, array<string, mixed>>, runtime_islands: array<int, array<string, mixed>>, generated_blocks: array<int, array<string, mixed>>, gutenberg_gaps: array<int, array<string, mixed>>, interaction_candidates: array<int, array<string, mixed>>, superseded_selectors: array<int, string>, author_stylesheet_projections: array<int, array<string, mixed>>, shell_artifacts: array<int, array<string, mixed>>, core_html_fallback_evidence: array<string, mixed>}
      */
     private function compileEntryBlocks(string $html, string $entryPath, array $files, string $generatedBlockNamespace = ''): array
     {
@@ -695,12 +699,13 @@ private function compileEntryBlocks(string $html, string $entryPath, array $file
             'superseded_selectors' => $result['superseded_selectors'],
             'author_stylesheet_projections' => $result['author_stylesheet_projections'],
             'shell_artifacts' => $result['shell_artifacts'],
+            'core_html_fallback_evidence' => $result['core_html_fallback_evidence'],
         );
     }
 
     /**
      * @param array<int, array<string, mixed>> $files
-     * @return array{blocks: array<int, array<string, mixed>>, serialized_blocks: string, diagnostics: array<int, array<string, mixed>>, fallbacks: array<int, array<string, mixed>>, assets: array<int, array<string, mixed>>, runtime_islands: array<int, array<string, mixed>>, generated_blocks: array<int, array<string, mixed>>, gutenberg_gaps: array<int, array<string, mixed>>, interaction_candidates: array<int, array<string, mixed>>, superseded_selectors: array<int, string>, author_stylesheet_projections: array<int, array<string, mixed>>, shell_artifacts: array<int, array<string, mixed>>}
+     * @return array{blocks: array<int, array<string, mixed>>, serialized_blocks: string, diagnostics: array<int, array<string, mixed>>, fallbacks: array<int, array<string, mixed>>, assets: array<int, array<string, mixed>>, runtime_islands: array<int, array<string, mixed>>, generated_blocks: array<int, array<string, mixed>>, gutenberg_gaps: array<int, array<string, mixed>>, interaction_candidates: array<int, array<string, mixed>>, superseded_selectors: array<int, string>, author_stylesheet_projections: array<int, array<string, mixed>>, shell_artifacts: array<int, array<string, mixed>>, core_html_fallback_evidence: array<string, mixed>}
      */
     private function compileHtmlDocumentBlocks(string $html, string $sourcePath, array $files, string $sourceScope, string $generatedBlockNamespace = '', bool $extractGlobalShell = false): array
     {
@@ -718,6 +723,7 @@ private function compileHtmlDocumentBlocks(string $html, string $sourcePath, arr
                 'superseded_selectors' => array(),
                 'author_stylesheet_projections' => array(),
                 'shell_artifacts' => array(),
+                'core_html_fallback_evidence' => CoreHtmlFallbackEvidence::fromBlocks(array(), array(), array()),
             );
         }
 
@@ -735,6 +741,7 @@ private function compileHtmlDocumentBlocks(string $html, string $sourcePath, arr
                 'superseded_selectors' => array(),
                 'author_stylesheet_projections' => array(),
                 'shell_artifacts' => array(),
+                'core_html_fallback_evidence' => CoreHtmlFallbackEvidence::fromBlocks(array(), array(), array()),
             );
         }
 
@@ -758,6 +765,7 @@ private function compileHtmlDocumentBlocks(string $html, string $sourcePath, arr
             'serialized_blocks' => (string) ($result['serialized_blocks'] ?? ''),
             'diagnostics'       => is_array($result['diagnostics'] ?? null) ? $result['diagnostics'] : array(),
             'fallbacks'         => is_array($result['fallbacks'] ?? null) ? $result['fallbacks'] : array(),
+            'core_html_fallback_evidence' => is_array($result['source_reports']['html']['core_html_fallback_evidence'] ?? null) ? $result['source_reports']['html']['core_html_fallback_evidence'] : CoreHtmlFallbackEvidence::fromBlocks(array(), array(), array()),
             'assets'            => is_array($result['assets'] ?? null) ? $result['assets'] : array(),
             'runtime_islands'   => $this->runtimeIslandsWithMaterializedInlineScripts(
                 is_array($result['source_reports']['runtime_islands'] ?? null) ? $result['source_reports']['runtime_islands'] : array(),

php-transformer/src/Contract/ConversionReportProjection.php

@@ -30,6 +30,7 @@ public static function fromResultParts(string $sourceFormat, array $blocks, arra
             'selector_summary'      => self::selectorSummary($sourceReports, $fallbacks),
             'conversion_classification_summary' => self::conversionClassificationSummary($sourceReports, $fallbacks),
             'fallback_diagnostics'  => self::fallbackDiagnostics($fallbacks),
+            'core_html_fallback_evidence' => self::coreHtmlFallbackEvidence($sourceReports),
             'asset_refs'            => self::assetReferences($blocks, $sourceReports),
             'navigation_candidates' => self::navigationCandidates($blocks, $sourceReports),
             'semantic_parity'       => self::semanticParity($sourceReports),
@@ -458,6 +459,14 @@ private static function sourceProvenance(array $sourceReports): array
         return is_array($html['source_provenance'] ?? null) ? $html['source_provenance'] : array();
     }
 
+    /** @param array<string, mixed> $sourceReports @return array<string, mixed> */
+    private static function coreHtmlFallbackEvidence(array $sourceReports): array
+    {
+        $html = is_array($sourceReports['html'] ?? null) ? $sourceReports['html'] : array();
+        $evidence = $sourceReports['core_html_fallback_evidence'] ?? ($html['core_html_fallback_evidence'] ?? array());
+        return is_array($evidence) ? $evidence : array();
+    }
+
     /**
      * @param array<string, mixed> $sourceReports
      * @return array<int, array<string, mixed>>

php-transformer/src/Contract/CoreHtmlFallbackEvidence.php

@@ -0,0 +1,114 @@
+<?php
+declare(strict_types=1);
+
+namespace Automattic\BlocksEngine\PhpTransformer\Contract;
+
+/** Bounded, payload-safe evidence for raw HTML escape-hatch emissions. */
+final class CoreHtmlFallbackEvidence
+{
+    public const SCHEMA = 'blocks-engine/core-html-fallback-evidence/v1';
+    private const MAX_EMISSIONS = 100;
+    private const MAX_SNIPPET_BYTES = 320;
+
+    /**
+     * @param array<int, array<string, mixed>> $blocks
+     * @param array<int, array<string, mixed>> $fallbacks
+     * @param array<int, array<string, mixed>> $sourceProvenance
+     * @return array<string, mixed>
+     */
+    public static function fromBlocks(array $blocks, array $fallbacks, array $sourceProvenance): array
+    {
+        $fallbacksBySelector = array();
+        foreach ($fallbacks as $fallback) {
+            if (is_array($fallback) && is_string($fallback['selector'] ?? null)) {
+                $fallbacksBySelector[$fallback['selector']][] = $fallback;
+            }
+        }
+
+        $emissions = array();
+        self::collect($blocks, 'blocks', $sourceProvenance, $fallbacksBySelector, $emissions);
+        $total = count($emissions);
+        $truncated = $total > self::MAX_EMISSIONS;
+
+        return array(
+            'schema' => self::SCHEMA,
+            'taxonomy' => array(
+                'schema' => 'blocks-engine/core-html-fallback-reason-taxonomy/v1',
+                'reasons' => array('unsupported_element', 'unsupported_attribute', 'unsupported_style', 'runtime_semantics', 'block_grammar', 'sanitization'),
+            ),
+            'emissions' => array_slice($emissions, 0, self::MAX_EMISSIONS),
+            'totals' => array('emissions' => $total, 'reported' => min($total, self::MAX_EMISSIONS), 'omitted' => max(0, $total - self::MAX_EMISSIONS), 'truncated' => $truncated),
+        );
+    }
+
+    /** @param array<int, array<string, mixed>> $evidence @return array<string, mixed> */
+    public static function merge(array $evidence): array
+    {
+        $emissions = array();
+        foreach ($evidence as $entry) foreach (is_array($entry['emissions'] ?? null) ? $entry['emissions'] : array() as $emission) if (is_array($emission)) $emissions[] = $emission;
+        usort($emissions, static fn (array $a, array $b): int => strcmp((string) ($a['source_path'] ?? '') . "\0" . (string) ($a['block_path'] ?? ''), (string) ($b['source_path'] ?? '') . "\0" . (string) ($b['block_path'] ?? '')));
+        $total = array_sum(array_map(static fn (array $entry): int => (int) ($entry['totals']['emissions'] ?? 0), $evidence));
+        $reported = min(count($emissions), self::MAX_EMISSIONS);
+
+        return array(
+            'schema' => self::SCHEMA,
+            'taxonomy' => array('schema' => 'blocks-engine/core-html-fallback-reason-taxonomy/v1', 'reasons' => array('unsupported_element', 'unsupported_attribute', 'unsupported_style', 'runtime_semantics', 'block_grammar', 'sanitization')),
+            'emissions' => array_slice($emissions, 0, self::MAX_EMISSIONS),
+            'totals' => array('emissions' => $total, 'reported' => $reported, 'omitted' => max(0, $total - $reported), 'truncated' => $total > $reported),
+        );
+    }
+
+    /** @param array<int, array<string, mixed>> $blocks @param array<int, array<string, mixed>> $provenance @param array<string, array<int, array<string, mixed>>> $fallbacks @param array<int, array<string, mixed>> $emissions */
+    private static function collect(array $blocks, string $path, array $provenance, array $fallbacks, array &$emissions): void
+    {
+        foreach ($blocks as $index => $block) {
+            if (!is_array($block)) continue;
+            $blockPath = $path . '.' . $index;
+            if ('core/html' === ($block['blockName'] ?? null)) {
+                $source = self::sourceForPath($provenance, $blockPath);
+                $fallback = $fallbacks[(string) ($source['selector'] ?? '')][0] ?? array();
+                $fragment = (string) ($source['source_fragment'] ?? '');
+                $content = (string) ($block['attrs']['content'] ?? '');
+                $emissions[] = array(
+                    'reason' => self::reason($fallback, $source),
+                    'source_path' => (string) ($fallback['source'] ?? $source['source_path'] ?? ''),
+                    'source_selector' => (string) ($source['selector'] ?? $fallback['selector'] ?? ''),
+                    'block_path' => $blockPath,
+                    'source_subtree' => array('digest' => (string) ($source['source_digest'] ?? hash('sha256', $fragment)), 'bytes' => (int) ($source['source_bytes'] ?? strlen($fragment)), 'snippet' => self::structuralSnippet($fragment), 'truncated' => strlen($fragment) > self::MAX_SNIPPET_BYTES),
+                    'emitted' => array('block_digest' => hash('sha256', json_encode($block, JSON_UNESCAPED_SLASHES) ?: ''), 'content_digest' => hash('sha256', $content), 'content_bytes' => strlen($content)),
+                );
+            }
+            if (is_array($block['innerBlocks'] ?? null)) self::collect($block['innerBlocks'], $blockPath . '.innerBlocks', $provenance, $fallbacks, $emissions);
+        }
+    }
+
+    /** @param array<int, array<string, mixed>> $provenance @return array<string, mixed> */
+    private static function sourceForPath(array $provenance, string $blockPath): array
+    {
+        foreach ($provenance as $entry) if (is_array($entry) && $blockPath === ($entry['block_path'] ?? null)) return $entry;
+        return array();
+    }
+
+    /** @param array<string, mixed> $fallback @param array<string, mixed> $source */
+    private static function reason(array $fallback, array $source): string
+    {
+        $code = (string) ($fallback['diagnostic_code'] ?? '');
+        $reason = (string) ($fallback['reason'] ?? '');
+        if ('html_unsupported_element' === $code || 'unsupported_element' === $reason) return 'unsupported_element';
+        if (str_contains($reason, 'runtime') || str_contains($code, 'runtime') || 'html_script_fallback' === $code) return 'runtime_semantics';
+        if (str_contains($reason, 'unsafe') || 'svg' === ($source['tag'] ?? null)) return 'sanitization';
+        return 'block_grammar';
+    }
+
+    private static function structuralSnippet(string $html): string
+    {
+        preg_match_all('/<\/?[a-zA-Z][^>]*>/', $html, $matches);
+        $tokens = array_map(static function (string $tag): string {
+            if (str_starts_with($tag, '</')) return '</' . strtolower(trim($tag, '</> ')) . '>';
+            preg_match('/^<\s*([a-zA-Z][\w:-]*)/', $tag, $name);
+            preg_match_all('/\s+([:\w-]+)(?:\s*=\s*(?:"[^"]*"|\'[^\']*\'|[^\s>]+))?/', $tag, $attrs);
+            return '<' . strtolower($name[1] ?? 'unknown') . (empty($attrs[1]) ? '' : ' ' . implode(' ', array_map('strtolower', $attrs[1]))) . '>';
+        }, $matches[0] ?? array());
+        return substr(implode('', $tokens), 0, self::MAX_SNIPPET_BYTES);
+    }
+}

php-transformer/src/HtmlToBlocks/HtmlTransformer.php

@@ -4,6 +4,7 @@
 namespace Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks;
 
 use Automattic\BlocksEngine\PhpTransformer\Contract\ConversionReportProjection;
+use Automattic\BlocksEngine\PhpTransformer\Contract\CoreHtmlFallbackEvidence;
 use Automattic\BlocksEngine\PhpTransformer\Contract\TransformationOptions;
 use Automattic\BlocksEngine\PhpTransformer\Contract\TransformerResult;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Classification\FormControlClassifier;
@@ -809,6 +810,7 @@ public function transform(string $html, array $options = array()): TransformerRe
                 'gutenberg_incompatibilities' => $this->gutenbergIncompatibilities,
                 'author_layout_topology' => $authorLayoutTopologyFindings,
                 'source_provenance'    => $sourceProvenance,
+                'core_html_fallback_evidence' => CoreHtmlFallbackEvidence::fromBlocks($blocks, $fallbacks, $sourceProvenance),
                 'structure_signals'    => $this->structureProvenance,
                 'script_metadata'      => $this->scriptMetadata,
                 'runtime_islands'      => $this->runtimeIslands,
@@ -3435,7 +3437,7 @@ private function createBlock(string $name, array $attrs = array(), array $innerB
         if ( $sourceElement instanceof DOMElement && in_array($name, array( 'core/paragraph', 'core/heading' ), true) && $this->richTextRequiresHtmlFallbackWithoutNativeSvgImageObjects((string) ($attrs['content'] ?? '')) ) {
             $attrs['content'] = $this->stripDecorativeSvgFromRichText((string) ($attrs['content'] ?? ''));
             if ( $this->richTextRequiresHtmlFallbackWithoutNativeSvgImageObjects((string) ($attrs['content'] ?? '')) ) {
-                return $this->blockFactory->create('core/html', array( 'content' => $this->safeFallbackHtml($sourceElement) ));
+                return $this->createBlock('core/html', array( 'content' => $this->safeFallbackHtml($sourceElement) ), array(), $sourceElement);
             }
         }
 
@@ -4992,12 +4994,16 @@ private function resolveSourceProvenancePaths(array &$blocks, string $path, arra
      */
     private function sourceProvenanceEntry(string $blockName, DOMElement $element): array
     {
+        $sourceHtml = $this->safeFallbackHtml($element);
         return array_merge(array(
             'block_name'        => $blockName,
             'tag'               => strtolower($element->tagName),
             'selector'          => $this->elementSelector($element),
             'source_attributes' => $this->safeSourceAttributes($element),
             'source_fragment'   => $this->safeSourceFragment($element),
+            'source_digest'     => hash('sha256', $sourceHtml),
+            'source_bytes'      => strlen($sourceHtml),
+            'source_path'       => $this->fallbackProvenance['source'] ?? '',
             'context'           => $this->sourceContext($element),
         ), $this->sourceConversionMetadata($blockName, $element));
     }