From a7e7a7b42f4f9aa28f7f3525c32377a142addd06 Mon Sep 17 00:00:00 2001
From: Jhin Lee <jhin.lee@unity3d.com>
Date: Mon, 7 Sep 2026 16:06:21 -0400
Subject: [PATCH 1/3] fix: validate metadata-only release readiness evidence

---
 AGENTS.md                                     |   4 +
 doc/high_risk_pre_merge_readiness.md          |  49 +-
 .../tooling/high_risk_readiness_test.dart     | 469 ++++++++++++++++++
 tool/testing/classify_high_risk_changes.dart  |   1 +
 tool/testing/high_risk_readiness.dart         | 132 ++++-
 .../high_risk_readiness_evidence.schema.json  |  10 +-
 tool/testing/release_metadata_readiness.dart  | 282 +++++++++++
 tool/testing/test_matrix.dart                 |  13 +
 8 files changed, 953 insertions(+), 7 deletions(-)
 create mode 100644 tool/testing/release_metadata_readiness.dart

diff --git a/AGENTS.md b/AGENTS.md
index 34a24c1d..8491e942 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -334,6 +334,10 @@ require issue-specific positive and negative tests that fail if the relevant
 branch is deleted, bypassed, or miswired.
 Record zero known PR-caused P1 regressions and zero unresolved review threads
 in the PR's high-risk block and evidence payload.
+For core-patch release metadata only, use the bounded
+`release-metadata-verification` evidence route described in
+`doc/high_risk_pre_merge_readiness.md`. It checks exact Git blobs and existing
+release tests; do not fabricate changed tests or reclassify the PR as standard.
 
 Structured-output changes must cover compiled grammar acceptance and rejection,
 schema-directed scalar and container reconstruction, partial-streaming
diff --git a/doc/high_risk_pre_merge_readiness.md b/doc/high_risk_pre_merge_readiness.md
index 03385372..29ac5c56 100644
--- a/doc/high_risk_pre_merge_readiness.md
+++ b/doc/high_risk_pre_merge_readiness.md
@@ -43,7 +43,7 @@ The contract fails closed against:
 3. duplicate JSON keys, unknown fields, wrong scalar/container types, and
    caller-declared decisions;
 4. caller-forged changed-file lists;
-5. deleted, renamed-old, unchanged, absolute, traversal, wildcard, non-test, or
+5. deleted, renamed-old, unauthorized unchanged, absolute, traversal, wildcard, non-test, or
    phantom evidence paths;
 6. boolean-only structured-output attestations without named production tests;
 7. PR-authored workflow or evidence execution;
@@ -93,7 +93,52 @@ source and destination paths are both classified. Every cited test must:
 
 This intentionally rejects unchanged tests as issue-specific proof. Existing
 coverage can still inform a human audit, but it cannot satisfy the changed
-production-test evidence field.
+production-test evidence field except through the bounded release route below.
+
+### Core-patch release metadata evidence
+
+A release-only PR remains **high-risk / artifactConsumer**. It can additionally
+declare the `release-metadata-verification` matrix row, with this exact command
+and a `pass` result (never `notApplicable`):
+
+```bash
+dart run tool/testing/verify_release_docs_versions.dart --release-prep && dart test -p vm -j 1 test/unit/tooling/verify_release_docs_companion_pins_test.dart
+```
+
+For this route, `affected_test_paths` must name exactly that existing test.
+The independent audit and both matrix rows remain required and are bound to
+the exact head and base. This records an existing release regression suite,
+not a fabricated newly changed test. The evaluator does not execute candidate
+scripts and cannot authenticate a claimed test run; the independent reviewer
+must inspect the exact-head command/log evidence.
+
+Eligibility comes from literal Git blobs and the complete rename-aware diff,
+not a `metadata_only` flag or a caller-provided inventory:
+
+- `pubspec.yaml` changes only its canonical stable version to the next patch;
+  every other byte, including dependencies, SDK, hooks and overrides, is fixed.
+- Both current changelogs and the four maintained installation README/docs
+  pages are modified. Historical numbered changelog sections, runtime identity
+  strings, embedded MDX/HTML fragments, frontmatter and already-prepared
+  companion constraints remain unchanged; current core snippets name the new
+  patch. Narrative release prose still needs independent review.
+- The only optional path is `example/chat_app/pubspec.lock`, changing only the
+  matching local `llamadart` version. Path, source, inventory, hashes, SDK and
+  all other bytes remain identical. Pub must generate the lock normally.
+- All changed paths are existing non-executable regular files; additions,
+  deletions, copies, renames and mode changes are excluded.
+- The existing release verifier and named regression test are unchanged
+  regular blobs at both revisions.
+
+The exact allowlist lives in `tool/testing/release_metadata_readiness.dart`.
+Companion version changes, runtime pins, generated bindings, hooks, SwiftPM,
+workflows, security/review policy, other docs/MDX and production changes cannot
+use this exception. Broader release changes use the ordinary changed-test
+contract instead of expanding this route implicitly.
+
+An internally consistent release evaluation still returns
+`unverifiedPrerequisites` (exit 2), never operational readiness. External
+authentication/publication/ruleset boundaries below are unchanged.
 
 ### Independent audit
 
diff --git a/test/unit/tooling/high_risk_readiness_test.dart b/test/unit/tooling/high_risk_readiness_test.dart
index 8f770cda..fe555ce2 100644
--- a/test/unit/tooling/high_risk_readiness_test.dart
+++ b/test/unit/tooling/high_risk_readiness_test.dart
@@ -8,6 +8,7 @@ import 'package:test/test.dart';
 
 import '../../../tool/testing/classify_high_risk_changes.dart';
 import '../../../tool/testing/high_risk_readiness.dart';
+import '../../../tool/testing/release_metadata_readiness.dart';
 
 const baseSha = '1111111111111111111111111111111111111111';
 const headSha = '2222222222222222222222222222222222222222';
@@ -30,6 +31,7 @@ class FakeRepositoryState implements RepositoryStateReader {
     this.commitsExist = true,
     this.baseIsAncestor = true,
     this.pathProbeThrows = false,
+    this.files = const {},
   }) : existingPaths =
            existingPaths ??
            changes
@@ -42,8 +44,16 @@ class FakeRepositoryState implements RepositoryStateReader {
   final bool commitsExist;
   final bool baseIsAncestor;
   final bool pathProbeThrows;
+  final Map<String, Map<String, ReadinessFile>> files;
   var repositoryCallCount = 0;
 
+  @override
+  Future<ReadinessFile?> fileAt(
+    String sha,
+    String path, {
+    String? workingDirectory,
+  }) async => files[sha]?[path];
+
   @override
   Future<bool> commitExists(String sha, {String? workingDirectory}) async {
     repositoryCallCount++;
@@ -160,6 +170,69 @@ Map<String, dynamic> backendEvidence() {
   return evidence;
 }
 
+Map<String, dynamic> metadataEvidence() {
+  final evidence = backendEvidence();
+  evidence['surfaces'] = ['artifactConsumer'];
+  (evidence['required_matrix_row_ids'] as List).add(releaseMetadataRow);
+  (evidence['matrix_row_evidence'] as Map)[releaseMetadataRow] = {
+    'row_id': releaseMetadataRow,
+    'result': 'pass',
+    'command': releaseMetadataCommand,
+    'evidence_notes':
+        'Strict verifier and existing companion-pin tests passed on exact head.',
+  };
+  evidence['affected_test_paths'] = [releaseMetadataTest];
+  return evidence;
+}
+
+Map<String, Map<String, ReadinessFile>> metadataFiles() {
+  ReadinessFile file(String text) => (mode: '100644', contents: text);
+  final base = <String, ReadinessFile>{
+    'pubspec.yaml': file(
+      'name: llamadart\nversion: 0.8.22\ndependencies:\n  yaml: ^3.1.3\n',
+    ),
+    for (final path in releaseMetadataDocs)
+      path: file(
+        path.contains('CHANGELOG') || path.contains('recent-releases')
+            ? '# Changes\n\n## Unreleased\n\n* Update.\n\n## 0.8.22\n\n* History.\n'
+            : '# Install\n\n```yaml\ndependencies:\n  llamadart: ^0.8.22\n```\n',
+      ),
+    releaseMetadataLock: file(
+      'packages:\n  llamadart:\n    dependency: "direct main"\n    description:\n      path: "../.."\n      relative: true\n    source: path\n    version: "0.8.22"\nsdks:\n  dart: ">=3.13.0 <4.0.0"\n',
+    ),
+    releaseMetadataVerifier: file('// maintained verifier\n'),
+    releaseMetadataTest: file(
+      '// existing negative companion pin regressions\n',
+    ),
+  };
+  final head = Map<String, ReadinessFile>.from(base);
+  for (final path in releaseMetadataPaths) {
+    final old = base[path]!;
+    head[path] = file(
+      path.contains('CHANGELOG') || path.contains('recent-releases')
+          ? old.contents.replaceFirst('## Unreleased', '## 0.8.23')
+          : old.contents.replaceAll('0.8.22', '0.8.23'),
+    );
+  }
+  return {baseSha: base, headSha: head};
+}
+
+Future<HighRiskReadinessResult> evaluateMetadata({
+  Map<String, dynamic>? evidence,
+  Map<String, Map<String, ReadinessFile>>? files,
+  List<RepositoryChange>? changes,
+}) => HighRiskReadinessEvaluator(
+  repositoryState: FakeRepositoryState(
+    changes:
+        changes ??
+        [
+          for (final path in releaseMetadataPaths)
+            RepositoryChange(path: path, kind: RepositoryChangeKind.modified),
+        ],
+    files: files ?? metadataFiles(),
+  ),
+).evaluate(evidence: evidence ?? metadataEvidence(), context: context);
+
 Map<String, dynamic> standardEvidence() {
   final evidence = backendEvidence();
   evidence['classification'] = 'standard';
@@ -262,6 +335,401 @@ void mutateIdentityToOtherValidValues(Map<String, dynamic> evidence) {
 }
 
 void main() {
+  group('bounded metadata-only release evidence', () {
+    test(
+      'real Git blobs authorize only the committed metadata candidate',
+      () async {
+        final repo = Directory.systemTemp.createTempSync(
+          'release-metadata-git-',
+        );
+        addTearDown(() => repo.deleteSync(recursive: true));
+        String git(List<String> args) {
+          final result = Process.runSync(
+            'git',
+            args,
+            workingDirectory: repo.path,
+          );
+          expect(result.exitCode, 0, reason: '${result.stderr}');
+          return (result.stdout as String).trim();
+        }
+
+        git(['init', '--quiet']);
+        git(['config', 'user.name', 'Metadata test']);
+        git(['config', 'user.email', 'metadata@example.invalid']);
+        git(['config', 'core.autocrlf', 'false']);
+        final files = metadataFiles();
+        void write(Map<String, ReadinessFile> tree) {
+          for (final entry in tree.entries) {
+            File('${repo.path}/${entry.key}')
+              ..parent.createSync(recursive: true)
+              ..writeAsStringSync(entry.value.contents);
+          }
+        }
+
+        write(files[baseSha]!);
+        git(['add', '.']);
+        git(['commit', '--quiet', '-m', 'base']);
+        final base = git(['rev-parse', 'HEAD']);
+        write(files[headSha]!);
+        git(['add', '.']);
+        git(['commit', '--quiet', '-m', 'release']);
+        final head = git(['rev-parse', 'HEAD']);
+        final evidence = metadataEvidence()
+          ..['expected_pr_head_sha'] = head
+          ..['current_base_sha'] = base;
+        evidence['independent_audit']['audit_head_sha'] = head;
+        evidence['independent_audit']['audit_base_sha'] = base;
+        Future<HighRiskReadinessResult> evaluate(
+          String candidate,
+          Map<String, dynamic> input,
+        ) => const HighRiskReadinessEvaluator().evaluate(
+          evidence: input,
+          context: PullRequestContext(
+            repository: context.repository,
+            prNumber: context.prNumber,
+            headSha: candidate,
+            baseSha: base,
+            author: context.author,
+          ),
+          workingDirectory: repo.path,
+        );
+        // Mutable working-tree content cannot substitute for committed blobs.
+        File('${repo.path}/README.md').writeAsStringSync('{unsafe()}');
+        expect(
+          (await evaluate(head, evidence)).decision,
+          ReadinessDecision.unverifiedPrerequisites,
+        );
+        git(['add', 'README.md']);
+        git(['commit', '--quiet', '-m', 'unsafe MDX']);
+        final unsafe = git(['rev-parse', 'HEAD']);
+        expectFailure(
+          await evaluate(unsafe, evidence),
+          ReadinessFailureClassification.headMismatch,
+        );
+        evidence['expected_pr_head_sha'] = unsafe;
+        evidence['independent_audit']['audit_head_sha'] = unsafe;
+        expectFailure(
+          await evaluate(unsafe, evidence),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+      },
+    );
+    test(
+      'documented grammar and repeated existing runtime identity are inert',
+      () async {
+        final files = metadataFiles();
+        for (final sha in [baseSha, headSha]) {
+          final old = files[sha]!['README.md']!;
+          files[sha]!['README.md'] = (
+            mode: old.mode,
+            contents: '${old.contents}\nNative v0.4.0.\n',
+          );
+        }
+        final candidate = files[headSha]!['README.md']!;
+        files[headSha]!['README.md'] = (
+          mode: candidate.mode,
+          contents:
+              '${candidate.contents}\nKnown v0.4.0 limitation: `root ::= "a"{2000}`.\n',
+        );
+        expect(
+          (await evaluateMetadata(files: files)).decision,
+          ReadinessDecision.unverifiedPrerequisites,
+        );
+      },
+    );
+    test(
+      'fence and inline context cannot convert existing fragments to MDX',
+      () async {
+        for (final snippet in [
+          '{dangerous()}',
+          'export const bad = 1;',
+          '<script src="bad"/>',
+        ]) {
+          for (final fence in ['```', '````', '~~~', '`']) {
+            final files = metadataFiles();
+            final before = files[baseSha]!['README.md']!;
+            final after = files[headSha]!['README.md']!;
+            final inert = fence.length == 1
+                ? '$fence$snippet$fence'
+                : '$fence\n$snippet\n$fence';
+            files[baseSha]!['README.md'] = (
+              mode: before.mode,
+              contents: '${before.contents}\n$inert\n',
+            );
+            files[headSha]!['README.md'] = (
+              mode: after.mode,
+              contents: '${after.contents}\n$snippet\n',
+            );
+            expectFailure(
+              await evaluateMetadata(files: files),
+              ReadinessFailureClassification.invalidReleaseMetadata,
+            );
+          }
+        }
+      },
+    );
+    test('Docusaurus executable fences and unclosed fences reject', () async {
+      for (final snippet in [
+        '```mdx-code-block\n{dangerous()}\n```',
+        '````mdx-code-block\n{dangerous()}\n````',
+        '```js\n{dangerous()}',
+      ]) {
+        final files = metadataFiles();
+        final old = files[headSha]!['README.md']!;
+        files[headSha]!['README.md'] = (
+          mode: old.mode,
+          contents: '${old.contents}\n$snippet\n',
+        );
+        expectFailure(
+          await evaluateMetadata(files: files),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+      }
+    });
+    test(
+      'existing release proof remains high risk and externally unverified',
+      () async {
+        final result = await evaluateMetadata();
+        expect(result.decision, ReadinessDecision.unverifiedPrerequisites);
+        expect(
+          result.failureClassification,
+          ReadinessFailureClassification.externalPrerequisitesUnavailable,
+        );
+        expect(result.isReady, isFalse);
+        expect(result.toJson()['classification'], 'high-risk');
+      },
+    );
+
+    for (final path in [
+      'lib/src/backends/native.dart',
+      'hook/build.dart',
+      'scripts/fetch_webgpu_bridge_assets.sh',
+      'packages/llamadart_llama_cpp_flutter/darwin/llamadart_llama_cpp_flutter/Package.swift',
+      '.github/workflows/release_on_prep_merge.yml',
+      'tool/testing/high_risk_readiness.dart',
+      'AGENTS.md',
+      'website/versioned_docs/version-0.8.22/intro.md',
+      'website/docs/new.mdx',
+      'packages/llamadart_llama_cpp_flutter/pubspec.yaml',
+    ]) {
+      test('mixed $path cannot claim release exception', () async {
+        final changes = [
+          for (final name in releaseMetadataPaths)
+            RepositoryChange(path: name, kind: RepositoryChangeKind.modified),
+          RepositoryChange(path: path, kind: RepositoryChangeKind.modified),
+        ];
+        final evidence = metadataEvidence();
+        evidence['surfaces'] = assessHighRiskFiles(
+          changes.map((c) => c.path),
+        ).surfaces.map((s) => s.name).toList();
+        expect(
+          (await evaluateMetadata(
+            evidence: evidence,
+            changes: changes,
+          )).decision,
+          ReadinessDecision.rejected,
+        );
+      });
+    }
+
+    for (final mutation in <String, String Function(String)>{
+      'dependency': (s) => s.replaceFirst('yaml: ^3.1.3', 'yaml: ^9.0.0'),
+      'SDK': (s) =>
+          '$s'
+          'environment:\n  sdk: ^9.0.0\n',
+      'override': (s) =>
+          '$s'
+          'dependency_overrides:\n  yaml: any\n',
+      'native pin': (s) =>
+          '$s'
+          'hooks:\n  user_defines:\n    llamadart_native_tag: v9.0.0\n',
+      'duplicate version': (s) =>
+          '$s'
+          'version: 0.8.23\n',
+      'rollback': (s) => s.replaceFirst('0.8.23', '0.8.21'),
+      'minor jump': (s) => s.replaceFirst('0.8.23', '0.9.0'),
+      'leading zero': (s) => s.replaceFirst('0.8.23', '0.8.023'),
+    }.entries) {
+      test(
+        'pubspec ${mutation.key} rejects even claimed verifier PASS',
+        () async {
+          final files = metadataFiles();
+          files[headSha]!['pubspec.yaml'] = (
+            mode: '100644',
+            contents: mutation.value(files[headSha]!['pubspec.yaml']!.contents),
+          );
+          expectFailure(
+            await evaluateMetadata(files: files),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        },
+      );
+    }
+
+    for (final mutation in <String, String Function(String)>{
+      'source': (s) => s.replaceFirst('source: path', 'source: hosted'),
+      'path': (s) => s.replaceFirst('../..', '../evil'),
+      'SDK': (s) => s.replaceFirst('3.13.0', '3.14.0'),
+      'extra package': (s) =>
+          s.replaceFirst('sdks:', '  evil:\n    version: "1.0.0"\nsdks:'),
+      'wrong version': (s) => s.replaceFirst('0.8.23', '0.8.24'),
+      'hash': (s) =>
+          s.replaceFirst('source: path', 'sha256: evil\n    source: path'),
+    }.entries) {
+      test('lock ${mutation.key} rejects', () async {
+        final files = metadataFiles();
+        files[headSha]![releaseMetadataLock] = (
+          mode: '100644',
+          contents: mutation.value(
+            files[headSha]![releaseMetadataLock]!.contents,
+          ),
+        );
+        expectFailure(
+          await evaluateMetadata(files: files),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+      });
+    }
+
+    for (final path in [
+      releaseMetadataVerifier,
+      releaseMetadataTest,
+      'pubspec.yaml',
+    ]) {
+      for (final mode in ['120000', '100755']) {
+        test('$path mode $mode rejects', () async {
+          final files = metadataFiles();
+          files[headSha]![path] = (
+            mode: mode,
+            contents: files[headSha]![path]!.contents,
+          );
+          expectFailure(
+            await evaluateMetadata(files: files),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        });
+      }
+    }
+    test('modified or missing existing verifier/test rejects', () async {
+      for (final path in [releaseMetadataVerifier, releaseMetadataTest]) {
+        final files = metadataFiles();
+        files[headSha]![path] = (mode: '100644', contents: '// fake pass\n');
+        expectFailure(
+          await evaluateMetadata(files: files),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+        files[headSha]!.remove(path);
+        expectFailure(
+          await evaluateMetadata(files: files),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+      }
+    });
+    test(
+      'changed history, stale snippets and executable docs reject',
+      () async {
+        for (final source in [
+          '# Install\n  llamadart: ^0.8.22\n',
+          '# Install\n  llamadart: ^0.8.23\n{dangerous()}\n',
+          '# Install\n  llamadart: ^0.8.23\n<script src="evil"/>\n',
+          '# Install\n  llamadart: ^0.8.23\nexport const x = 1;\n',
+          '# Install\n  llamadart: ^0.8.23\nNew runtime v9.0.0\n',
+        ]) {
+          final files = metadataFiles();
+          files[headSha]!['README.md'] = (mode: '100644', contents: source);
+          expectFailure(
+            await evaluateMetadata(files: files),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        }
+        final files = metadataFiles();
+        files[headSha]!['CHANGELOG.md'] = (
+          mode: '100644',
+          contents: files[headSha]!['CHANGELOG.md']!.contents.replaceFirst(
+            'History.',
+            'Rewrite.',
+          ),
+        );
+        expectFailure(
+          await evaluateMetadata(files: files),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+      },
+    );
+    test(
+      'renames/additions/removals cannot be disguised as metadata',
+      () async {
+        for (final kind in [
+          RepositoryChangeKind.added,
+          RepositoryChangeKind.deleted,
+          RepositoryChangeKind.renamed,
+          RepositoryChangeKind.typeChanged,
+        ]) {
+          final changes = [
+            for (final path in releaseMetadataPaths)
+              RepositoryChange(
+                path: path,
+                kind: path == 'README.md'
+                    ? kind
+                    : RepositoryChangeKind.modified,
+                previousPath:
+                    path == 'README.md' && kind == RepositoryChangeKind.renamed
+                    ? 'old.md'
+                    : null,
+              ),
+          ];
+          expectFailure(
+            await evaluateMetadata(changes: changes),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        }
+      },
+    );
+    test(
+      'wrong command, nonpassing row and invented test cannot authorize',
+      () async {
+        final command = metadataEvidence();
+        command['matrix_row_evidence'][releaseMetadataRow]['command'] =
+            'echo pass';
+        expectFailure(
+          await evaluateMetadata(evidence: command),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+        final failed = metadataEvidence();
+        failed['matrix_row_evidence'][releaseMetadataRow]['result'] =
+            'notApplicable';
+        expectFailure(
+          await evaluateMetadata(evidence: failed),
+          ReadinessFailureClassification.matrixRowFailed,
+        );
+        final path = metadataEvidence()
+          ..['affected_test_paths'] = [backendTest];
+        expectFailure(
+          await evaluateMetadata(evidence: path),
+          ReadinessFailureClassification.invalidReleaseMetadata,
+        );
+      },
+    );
+    test(
+      'stale audits, selfapproval, P1s and unresolved threads stay blocked',
+      () async {
+        for (final entry in <String, Object>{
+          'audit_head_sha': otherSha,
+          'audit_base_sha': otherSha,
+          'auditor_identity': context.author,
+          'known_pr_caused_p1_regressions': 1,
+          'unresolved_review_threads': 1,
+        }.entries) {
+          final evidence = metadataEvidence();
+          evidence['independent_audit'][entry.key] = entry.value;
+          expect(
+            (await evaluateMetadata(evidence: evidence)).decision,
+            ReadinessDecision.rejected,
+          );
+        }
+      },
+    );
+  });
   group('strict JSON and schema shape', () {
     test('rejects duplicate root, nested, and escaped-equivalent keys', () {
       expect(
@@ -1093,6 +1561,7 @@ void main() {
       const matrixRows = <String>[
         'high-risk-exact-head-independent-qa',
         'structured-output-adversarial',
+        'release-metadata-verification',
       ];
       expect(
         (schema['properties']
diff --git a/tool/testing/classify_high_risk_changes.dart b/tool/testing/classify_high_risk_changes.dart
index c53c0501..6552a091 100644
--- a/tool/testing/classify_high_risk_changes.dart
+++ b/tool/testing/classify_high_risk_changes.dart
@@ -165,6 +165,7 @@ bool _isRegressionPolicy(String path) {
       path == 'tool/testing/test_matrix.dart' ||
       path == 'tool/testing/classify_high_risk_changes.dart' ||
       path == 'tool/testing/high_risk_readiness.dart' ||
+      path == 'tool/testing/release_metadata_readiness.dart' ||
       path == 'tool/testing/high_risk_readiness_evidence.schema.json' ||
       path == 'test/unit/tooling/test_matrix_test.dart' ||
       path == 'test/unit/tooling/classify_high_risk_changes_test.dart' ||
diff --git a/tool/testing/high_risk_readiness.dart b/tool/testing/high_risk_readiness.dart
index 180cd272..fc93751a 100644
--- a/tool/testing/high_risk_readiness.dart
+++ b/tool/testing/high_risk_readiness.dart
@@ -4,6 +4,7 @@ import 'dart:convert';
 import 'dart:io';
 
 import 'classify_high_risk_changes.dart';
+import 'release_metadata_readiness.dart';
 
 /// Overall decision reached by the repository-local evaluator.
 enum ReadinessDecision {
@@ -37,6 +38,7 @@ enum ReadinessFailureClassification {
   unchangedEvidencePath,
   deletedEvidencePath,
   renamedEvidencePath,
+  invalidReleaseMetadata,
   externalPrerequisitesUnavailable,
   gitExecutionError,
   invalidInput,
@@ -111,6 +113,12 @@ abstract interface class RepositoryStateReader {
     String path, {
     String? workingDirectory,
   });
+
+  Future<ReadinessFile?> fileAt(
+    String sha,
+    String path, {
+    String? workingDirectory,
+  });
 }
 
 /// Function signature for non-shell Git command execution.
@@ -137,6 +145,38 @@ class GitRepositoryStateReader implements RepositoryStateReader {
 
   final GitRunner gitRunner;
 
+  @override
+  Future<ReadinessFile?> fileAt(
+    String sha,
+    String path, {
+    String? workingDirectory,
+  }) async {
+    final tree = await gitRunner(<String>[
+      'ls-tree',
+      '-z',
+      '--full-tree',
+      sha,
+      '--',
+      ':(top,literal)$path',
+    ], workingDirectory: workingDirectory);
+    if (tree.exitCode != 0 || tree.stdout is! String) {
+      throw StateError('Could not read literal Git tree entry.');
+    }
+    final entry = RegExp(
+      r'^(100644|100755) blob ([0-9a-f]{40})\t([^\u0000]+)\u0000$',
+    ).firstMatch(tree.stdout as String);
+    if (entry == null || entry.group(3) != path) return null;
+    final blob = await gitRunner(<String>[
+      'cat-file',
+      'blob',
+      entry.group(2)!,
+    ], workingDirectory: workingDirectory);
+    if (blob.exitCode != 0 || blob.stdout is! String) {
+      throw StateError('Could not read exact Git blob.');
+    }
+    return (mode: entry.group(1)!, contents: blob.stdout as String);
+  }
+
   @override
   Future<bool> commitExists(String sha, {String? workingDirectory}) async {
     final result = await gitRunner(<String>[
@@ -531,6 +571,7 @@ class HighRiskReadinessEvaluator {
   static const _knownMatrixRows = <String>{
     'high-risk-exact-head-independent-qa',
     'structured-output-adversarial',
+    releaseMetadataRow,
   };
   static const _structuredKeys = <String>{'coverage', 'families'};
   static const _coverageAxes = <String>{
@@ -732,6 +773,9 @@ class HighRiskReadinessEvaluator {
     const baselineRow = 'high-risk-exact-head-independent-qa';
     const structuredRow = 'structured-output-adversarial';
     final requiredRows = <String>{baselineRow};
+    final metadataClaim = (evidence['required_matrix_row_ids'] as List<dynamic>)
+        .contains(releaseMetadataRow);
+    if (metadataClaim) requiredRows.add(releaseMetadataRow);
     if (actualSurfaces.contains(HighRiskSurface.structuredOutput.name)) {
       requiredRows.add(structuredRow);
     }
@@ -833,14 +877,98 @@ class HighRiskReadinessEvaluator {
     };
     final affectedPaths = (evidence['affected_test_paths'] as List<dynamic>)
         .cast<String>();
-    if (affectedPaths.isEmpty) {
+    if (metadataClaim) {
+      if (actualSurfaces.length != 1 ||
+          !actualSurfaces.contains(HighRiskSurface.artifactConsumer.name) ||
+          affectedPaths.length != 1 ||
+          affectedPaths.single != releaseMetadataTest ||
+          (matrixEvidence[releaseMetadataRow]
+                  as Map<String, dynamic>)['command'] !=
+              releaseMetadataCommand) {
+        return reject(
+          ReadinessFailureClassification.invalidReleaseMetadata,
+          'Metadata release evidence requires only artifactConsumer, the fixed '
+          'existing release test and its exact strict-verifier/test command.',
+          changedFiles: changedFiles,
+        );
+      }
+      try {
+        final files = <String, ReadinessFilePair>{};
+        for (final change in changedFiles) {
+          if (change.kind != RepositoryChangeKind.modified ||
+              !releaseMetadataPaths.contains(change.path)) {
+            return reject(
+              ReadinessFailureClassification.invalidReleaseMetadata,
+              'Metadata releases cannot add, remove, rename or change paths '
+              'outside the fixed release inventory.',
+              changedFiles: changedFiles,
+            );
+          }
+          final base = await repositoryState.fileAt(
+            context.baseSha,
+            change.path,
+            workingDirectory: workingDirectory,
+          );
+          final head = await repositoryState.fileAt(
+            context.headSha,
+            change.path,
+            workingDirectory: workingDirectory,
+          );
+          if (base == null || head == null) {
+            return reject(
+              ReadinessFailureClassification.invalidReleaseMetadata,
+              'Metadata release paths must be regular files at both revisions.',
+              changedFiles: changedFiles,
+            );
+          }
+          files[change.path] = (base: base, head: head);
+        }
+        final metadataError = validateReleaseMetadata(files);
+        if (metadataError != null) {
+          return reject(
+            ReadinessFailureClassification.invalidReleaseMetadata,
+            metadataError,
+            changedFiles: changedFiles,
+          );
+        }
+        for (final path in [releaseMetadataVerifier, releaseMetadataTest]) {
+          final base = await repositoryState.fileAt(
+            context.baseSha,
+            path,
+            workingDirectory: workingDirectory,
+          );
+          final head = await repositoryState.fileAt(
+            context.headSha,
+            path,
+            workingDirectory: workingDirectory,
+          );
+          if (base == null ||
+              head == null ||
+              base != head ||
+              base.mode != '100644') {
+            return reject(
+              ReadinessFailureClassification.invalidReleaseMetadata,
+              'Existing release verifier and test must be unchanged regular '
+              'blobs at the exact base and head.',
+              changedFiles: changedFiles,
+            );
+          }
+        }
+      } on Object {
+        return reject(
+          ReadinessFailureClassification.gitExecutionError,
+          'Could not verify exact release metadata blobs.',
+          changedFiles: changedFiles,
+        );
+      }
+    } else if (affectedPaths.isEmpty) {
       return reject(
         ReadinessFailureClassification.missingTestPath,
         'High-risk evidence must cite at least one changed production test.',
         changedFiles: changedFiles,
       );
     }
-    for (final path in affectedPaths) {
+    for (final path in metadataClaim ? const <String>[] : affectedPaths) {
       late final (ReadinessFailureClassification, String)? pathFailure;
       try {
         pathFailure = await _validateEvidencePath(
diff --git a/tool/testing/high_risk_readiness_evidence.schema.json b/tool/testing/high_risk_readiness_evidence.schema.json
index 4f8d3e4d..77f9e54f 100644
--- a/tool/testing/high_risk_readiness_evidence.schema.json
+++ b/tool/testing/high_risk_readiness_evidence.schema.json
@@ -63,7 +63,8 @@
       "items": {
         "enum": [
           "high-risk-exact-head-independent-qa",
-          "structured-output-adversarial"
+          "structured-output-adversarial",
+          "release-metadata-verification"
         ]
       }
     },
@@ -72,7 +73,8 @@
       "propertyNames": {
         "enum": [
           "high-risk-exact-head-independent-qa",
-          "structured-output-adversarial"
+          "structured-output-adversarial",
+          "release-metadata-verification"
         ]
       },
       "additionalProperties": { "$ref": "#/$defs/matrixRow" }
@@ -123,7 +125,8 @@
         "row_id": {
           "enum": [
             "high-risk-exact-head-independent-qa",
-            "structured-output-adversarial"
+            "structured-output-adversarial",
+            "release-metadata-verification"
           ]
         },
         "result": { "enum": ["pass", "fail", "notApplicable"] },
@@ -317,6 +320,7 @@
             "unchangedEvidencePath",
             "deletedEvidencePath",
             "renamedEvidencePath",
+            "invalidReleaseMetadata",
             "externalPrerequisitesUnavailable",
             "gitExecutionError",
             "invalidInput"
diff --git a/tool/testing/release_metadata_readiness.dart b/tool/testing/release_metadata_readiness.dart
new file mode 100644
index 00000000..86313d49
--- /dev/null
+++ b/tool/testing/release_metadata_readiness.dart
@@ -0,0 +1,282 @@
+import 'package:yaml/yaml.dart';
+
+/// Fixed existing evidence for a core patch release with unchanged runtime pins.
+const releaseMetadataRow = 'release-metadata-verification';
+const releaseMetadataTest =
+    'test/unit/tooling/verify_release_docs_companion_pins_test.dart';
+const releaseMetadataVerifier =
+    'tool/testing/verify_release_docs_versions.dart';
+const releaseMetadataCommand =
+    'dart run tool/testing/verify_release_docs_versions.dart --release-prep && '
+    'dart test -p vm -j 1 $releaseMetadataTest';
+
+/// Only current release documentation, not policy or versioned/MDX documents.
+const releaseMetadataDocs = <String>{
+  'CHANGELOG.md',
+  'README.md',
+  'website/docs/changelog/recent-releases.md',
+  'website/docs/getting-started/installation.md',
+  'packages/llamadart_llama_cpp_flutter/README.md',
+  'packages/llamadart_litert_lm_flutter/README.md',
+};
+const releaseMetadataLock = 'example/chat_app/pubspec.lock';
+const releaseMetadataPaths = <String>{
+  'pubspec.yaml',
+  releaseMetadataLock,
+  ...releaseMetadataDocs,
+};
+
+/// A literal Git blob and its mode; no candidate code is executed.
+typedef ReadinessFile = ({String mode, String contents});
+typedef ReadinessFilePair = ({ReadinessFile base, ReadinessFile head});
+
+/// Validates a deliberately narrow core-only patch release transformation.
+///
+/// Companion version bumps, new files, pin updates and broader release work
+/// remain on the ordinary changed-production-test route. All pairs must come
+/// from the evaluator's exact Git base/head, never from the evidence JSON.
+String? validateReleaseMetadata(Map<String, ReadinessFilePair> files) {
+  if (!files.keys.toSet().containsAll({
+        'pubspec.yaml',
+        ...releaseMetadataDocs,
+      }) ||
+      files.keys.any((path) => !releaseMetadataPaths.contains(path))) {
+    return 'Metadata release requires core pubspec and both current changelogs; '
+        'only the fixed release metadata paths are allowed.';
+  }
+  for (final entry in files.entries) {
+    if (entry.value.base.mode != '100644' ||
+        entry.value.head.mode != '100644') {
+      return 'Metadata release requires unchanged non-executable regular-file '
+          'modes: ${entry.key}.';
+    }
+  }
+  final pubspec = files['pubspec.yaml']!;
+  final oldVersion = _packageVersion(pubspec.base.contents);
+  final newVersion = _packageVersion(pubspec.head.contents);
+  if (oldVersion == null || newVersion == null) {
+    return 'Core pubspec must contain one canonical stable version scalar.';
+  }
+  final oldParts = oldVersion.split('.').map(int.parse).toList();
+  final newParts = newVersion.split('.').map(int.parse).toList();
+  if (oldParts[0] != newParts[0] ||
+      oldParts[1] != newParts[1] ||
+      oldParts[2] + 1 != newParts[2] ||
+      pubspec.base.contents.replaceFirst(
+            'version: $oldVersion\n',
+            'version: $newVersion\n',
+          ) !=
+          pubspec.head.contents) {
+    return 'Only the next core patch version scalar may change in pubspec; '
+        'dependencies, SDK, hooks, overrides and other bytes must stay identical.';
+  }
+
+  final lock = files[releaseMetadataLock];
+  if (lock != null && !_validLock(lock, oldVersion, newVersion)) {
+    return 'Generated chat lock may change only the matching local llamadart '
+        'version; package inventory, paths, hashes and SDK must stay identical.';
+  }
+  for (final path in releaseMetadataDocs) {
+    final pair = files[path];
+    if (pair == null) continue;
+    // Markdown in Docusaurus may contain executable MDX. Preserve its complete
+    // syntax-bearing fragments and import/export lines rather than exempt it.
+    final baseActive = _activeFragments(pair.base.contents);
+    final headActive = _activeFragments(pair.head.contents);
+    if (baseActive == null ||
+        headActive == null ||
+        baseActive != headActive ||
+        _frontMatter(pair.base.contents) != _frontMatter(pair.head.contents) ||
+        _runtimeIdentities(pair.base.contents) !=
+            _runtimeIdentities(pair.head.contents)) {
+      return 'Release documentation cannot change embedded MDX/HTML syntax: '
+          '$path.';
+    }
+    if (path.endsWith('README.md') || path.endsWith('installation.md')) {
+      final dependencies = RegExp(
+        r'^\s+llamadart:\s+\^([^\s#]+)',
+        multiLine: true,
+      ).allMatches(pair.head.contents).toList();
+      if (dependencies.isEmpty ||
+          dependencies.any((match) => match.group(1) != newVersion) ||
+          _companionConstraints(pair.base.contents) !=
+              _companionConstraints(pair.head.contents)) {
+        return 'Current installation snippets must use the new core patch '
+            'and preserve already-prepared companion constraints: $path.';
+      }
+    }
+    if (path == 'CHANGELOG.md' ||
+        path == 'website/docs/changelog/recent-releases.md') {
+      final historical = RegExp(
+        r'^## [0-9]+\.[0-9]+\.[0-9]+\s*$',
+        multiLine: true,
+      ).firstMatch(pair.base.contents);
+      if (historical == null ||
+          !pair.head.contents.endsWith(
+            pair.base.contents.substring(historical.start),
+          ) ||
+          RegExp(
+                '^## ${RegExp.escape(newVersion)}\$',
+                multiLine: true,
+              ).allMatches(pair.head.contents).length !=
+              1 ||
+          RegExp(
+            r'^## Unreleased\s*$',
+            multiLine: true,
+          ).hasMatch(pair.head.contents)) {
+        return 'Release changelogs must name the new patch and preserve all '
+            'historical numbered sections: $path.';
+      }
+    }
+  }
+  return null;
+}
+
+String? _packageVersion(String source) {
+  try {
+    final parsed = loadYaml(source);
+    final matches = RegExp(
+      r'^version: (0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$',
+      multiLine: true,
+    ).allMatches(source).toList();
+    if (parsed is! YamlMap ||
+        parsed['name'] != 'llamadart' ||
+        matches.length != 1) {
+      return null;
+    }
+    final version = matches.single.group(0)!.substring('version: '.length);
+    return parsed['version'] == version ? version : null;
+  } on YamlException {
+    return null;
+  }
+}
+
+bool _validLock(ReadinessFilePair pair, String oldVersion, String newVersion) {
+  try {
+    for (final source in [pair.base.contents, pair.head.contents]) {
+      final parsed = loadYaml(source);
+      if (parsed is! YamlMap) return false;
+      final packages = parsed['packages'];
+      if (packages is! YamlMap) return false;
+      final core = packages['llamadart'];
+      if (core is! YamlMap || core['source'] != 'path') return false;
+      final description = core['description'];
+      if (description is! YamlMap ||
+          description['path'] != '../..' ||
+          description['relative'] != true) {
+        return false;
+      }
+    }
+    final block = RegExp(
+      r'^  llamadart:\n(?:    [^\n]*\n|      [^\n]*\n)*',
+      multiLine: true,
+    ).allMatches(pair.base.contents).toList();
+    if (block.length != 1) return false;
+    final oldLine = '    version: "$oldVersion"\n';
+    final oldBlock = block.single.group(0)!;
+    if (oldLine.allMatches(oldBlock).length != 1) return false;
+    final newBlock = oldBlock.replaceFirst(
+      oldLine,
+      '    version: "$newVersion"\n',
+    );
+    return pair.base.contents.replaceRange(
+          block.single.start,
+          block.single.end,
+          newBlock,
+        ) ==
+        pair.head.contents;
+  } on YamlException {
+    return false;
+  }
+}
+
+String? _activeFragments(String source) {
+  final prose = StringBuffer();
+  String? fence;
+  for (final line in source.split('\n')) {
+    final marker = RegExp(r'^ {0,3}(`{3,}|~{3,})(.*)$').firstMatch(line);
+    if (fence != null) {
+      if (marker != null &&
+          marker.group(1)![0] == fence[0] &&
+          marker.group(1)!.length >= fence.length &&
+          marker.group(2)!.trim().isEmpty) {
+        fence = null;
+      }
+      continue;
+    }
+    if (marker != null) {
+      if ((marker.group(1)![0] == '`' && marker.group(2)!.contains('`')) ||
+          marker.group(2)!.toLowerCase().contains('mdx-code-block')) {
+        return null;
+      }
+      fence = marker.group(1)!;
+      continue;
+    }
+    // Mask only matching inline backtick runs. Unmatched or escaped delimiters
+    // never hide syntax. This keeps fenced/inline-to-active changes observable.
+    var offset = 0;
+    while (offset < line.length) {
+      if (line[offset] != '`') {
+        prose.write(line[offset++]);
+        continue;
+      }
+      var slashes = 0;
+      for (var index = offset - 1; index >= 0 && line[index] == r'\'; index--) {
+        slashes++;
+      }
+      var end = offset;
+      while (end < line.length && line[end] == '`') {
+        end++;
+      }
+      final delimiter = line.substring(offset, end);
+      int? closing;
+      if (slashes.isEven) {
+        var candidate = end;
+        while ((candidate = line.indexOf('`', candidate)) >= 0) {
+          var after = candidate;
+          while (after < line.length && line[after] == '`') {
+            after++;
+          }
+          if (after - candidate == delimiter.length) {
+            closing = after;
+            break;
+          }
+          candidate = after;
+        }
+      }
+      if (closing == null) {
+        prose.write(delimiter);
+        offset = end;
+      } else {
+        prose.write(' ');
+        offset = closing;
+      }
+    }
+    prose.writeln();
+  }
+  if (fence != null) return null;
+  return RegExp(
+    r'<[^>]*>|\{[^}]*\}|^\s*(?:import|export)\b[^\n]*',
+    multiLine: true,
+  ).allMatches(prose.toString()).map((match) => match.group(0)).join('\n');
+}
+
+String _frontMatter(String source) =>
+    RegExp(r'^---\n[\s\S]*?\n---\n').firstMatch(source)?.group(0) ?? '';
+
+String _runtimeIdentities(String source) {
+  final identities = RegExp(
+    r'\bv[0-9]+\.[0-9]+\.[0-9]+(?:[-.][A-Za-z0-9]+)*\b|'
+    r'\bb[0-9]+(?:[-.][A-Za-z0-9]+)*\b|\b[0-9a-f]{40,64}\b',
+  ).allMatches(source).map((match) => match.group(0)!).toSet().toList()..sort();
+  return identities.join('\n');
+}
+
+String _companionConstraints(String source) =>
+    RegExp(
+          r'^\s+(llamadart_(?:llama_cpp|litert_lm)_flutter):\s+\^([^\s#]+)',
+          multiLine: true,
+        )
+        .allMatches(source)
+        .map((match) => '${match.group(1)}:${match.group(2)}')
+        .join('\n');
diff --git a/tool/testing/test_matrix.dart b/tool/testing/test_matrix.dart
index 66e47ba1..cf0572f2 100644
--- a/tool/testing/test_matrix.dart
+++ b/tool/testing/test_matrix.dart
@@ -92,6 +92,19 @@ const List<TestMatrixRow> testMatrixRows = <TestMatrixRow>[
         'probe, artifact consumer, release automation, or regression-policy '
         'changes. Required before mark-ready, not after merge.',
   ),
+  TestMatrixRow(
+    id: 'release-metadata-verification',
+    tier: 'high-risk',
+    mode: 'local exact-head release evidence',
+    covers:
+        'bounded core-patch metadata diff and unchanged release regression suite',
+    command:
+        'dart run tool/testing/verify_release_docs_versions.dart --release-prep && '
+        'dart test -p vm -j 1 test/unit/tooling/verify_release_docs_companion_pins_test.dart',
+    useWhen:
+        'Only the evaluator-verified core-patch metadata release route; '
+        'never a substitute for changed tests on production or policy changes.',
+  ),
   TestMatrixRow(
     id: 'structured-output-adversarial',
     tier: 'high-risk',

From 74b6502a6e6bbc52e99f4f2a10ede388886aa163 Mon Sep 17 00:00:00 2001
From: Jhin Lee <jhin.lee@unity3d.com>
Date: Mon, 7 Sep 2026 16:16:49 -0400
Subject: [PATCH 2/3] fix: reject active release documentation contexts

---
 doc/high_risk_pre_merge_readiness.md          | 11 ++--
 .../classify_high_risk_changes_test.dart      | 10 ++++
 .../tooling/high_risk_readiness_test.dart     | 54 +++++++++++++++++++
 tool/testing/release_metadata_readiness.dart  | 39 ++++++++------
 4 files changed, 95 insertions(+), 19 deletions(-)

diff --git a/doc/high_risk_pre_merge_readiness.md b/doc/high_risk_pre_merge_readiness.md
index 29ac5c56..22979472 100644
--- a/doc/high_risk_pre_merge_readiness.md
+++ b/doc/high_risk_pre_merge_readiness.md
@@ -119,10 +119,13 @@ not a `metadata_only` flag or a caller-provided inventory:
   every other byte, including dependencies, SDK, hooks and overrides, is fixed.
 - Both current changelogs and the four maintained installation README/docs
   pages are modified. Historical numbered changelog sections, runtime identity
-  strings, embedded MDX/HTML fragments, frontmatter and already-prepared
-  companion constraints remain unchanged; current core snippets name the new
-  patch. Narrative release prose still needs independent review.
-- The only optional path is `example/chat_app/pubspec.lock`, changing only the
+  identities, frontmatter and already-prepared companion constraints remain
+  unchanged; current core snippets name the new patch. Mutable release prose
+  must be inactive Markdown with no MDX expressions/imports/exports or HTML
+  outside inert code examples. Executable `mdx-code-block` fences are rejected.
+  Historical changelog tails are excluded from that syntax check only after
+  proving byte equality. Narrative prose still needs independent review.
+- The generated `example/chat_app/pubspec.lock` must change only the
   matching local `llamadart` version. Path, source, inventory, hashes, SDK and
   all other bytes remain identical. Pub must generate the lock normally.
 - All changed paths are existing non-executable regular files; additions,
diff --git a/test/unit/tooling/classify_high_risk_changes_test.dart b/test/unit/tooling/classify_high_risk_changes_test.dart
index fe670eae..dfb2bbe6 100644
--- a/test/unit/tooling/classify_high_risk_changes_test.dart
+++ b/test/unit/tooling/classify_high_risk_changes_test.dart
@@ -77,6 +77,7 @@ void main() {
         'doc/pr_branch_writer_inventory.md',
         'doc/high_risk_pre_merge_readiness.md',
         'tool/testing/high_risk_readiness.dart',
+        'tool/testing/release_metadata_readiness.dart',
         'tool/testing/high_risk_readiness_evidence.schema.json',
         'test/unit/tooling/high_risk_readiness_test.dart',
       ]);
@@ -102,6 +103,15 @@ void main() {
       );
     });
 
+    test('release metadata validator alone remains regression-policy risk', () {
+      expect(
+        assessHighRiskFiles([
+          'tool/testing/release_metadata_readiness.dart',
+        ]).surfaces,
+        {HighRiskSurface.regressionPolicy},
+      );
+    });
+
     test('normalizes blank input and prints deterministic surfaces', () {
       final assessment = assessHighRiskFiles([
         '',
diff --git a/test/unit/tooling/high_risk_readiness_test.dart b/test/unit/tooling/high_risk_readiness_test.dart
index fe555ce2..2e030c5b 100644
--- a/test/unit/tooling/high_risk_readiness_test.dart
+++ b/test/unit/tooling/high_risk_readiness_test.dart
@@ -336,6 +336,60 @@ void mutateIdentityToOtherValidValues(Map<String, dynamic> evidence) {
 
 void main() {
   group('bounded metadata-only release evidence', () {
+    test(
+      'existing active JSX template attributes and script bodies cannot use exception',
+      () async {
+        for (final pair in [
+          (
+            before: '<div title={`safe`} />',
+            after: r'<div title={`${dangerous()}`} />',
+          ),
+          (
+            before: '<script>safe()</script>',
+            after: '<script>dangerous()</script>',
+          ),
+          (
+            before: '<style>body{color:red}</style>',
+            after: '<style>body{display:none}</style>',
+          ),
+        ]) {
+          final files = metadataFiles();
+          final base = files[baseSha]!['README.md']!;
+          final head = files[headSha]!['README.md']!;
+          files[baseSha]!['README.md'] = (
+            mode: base.mode,
+            contents: '${base.contents}\n${pair.before}\n',
+          );
+          files[headSha]!['README.md'] = (
+            mode: head.mode,
+            contents: '${head.contents}\n${pair.after}\n',
+          );
+          expectFailure(
+            await evaluateMetadata(files: files),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        }
+      },
+    );
+    test(
+      'omitting a required lock or current document cannot hide stale metadata',
+      () async {
+        for (final omitted in releaseMetadataPaths) {
+          final changes = [
+            for (final path in releaseMetadataPaths)
+              if (path != omitted)
+                RepositoryChange(
+                  path: path,
+                  kind: RepositoryChangeKind.modified,
+                ),
+          ];
+          expectFailure(
+            await evaluateMetadata(changes: changes),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        }
+      },
+    );
     test(
       'real Git blobs authorize only the committed metadata candidate',
       () async {
diff --git a/tool/testing/release_metadata_readiness.dart b/tool/testing/release_metadata_readiness.dart
index 86313d49..49ff0a1d 100644
--- a/tool/testing/release_metadata_readiness.dart
+++ b/tool/testing/release_metadata_readiness.dart
@@ -38,11 +38,12 @@ typedef ReadinessFilePair = ({ReadinessFile base, ReadinessFile head});
 String? validateReleaseMetadata(Map<String, ReadinessFilePair> files) {
   if (!files.keys.toSet().containsAll({
         'pubspec.yaml',
+        releaseMetadataLock,
         ...releaseMetadataDocs,
       }) ||
       files.keys.any((path) => !releaseMetadataPaths.contains(path))) {
-    return 'Metadata release requires core pubspec and both current changelogs; '
-        'only the fixed release metadata paths are allowed.';
+    return 'Metadata release requires the complete fixed core pubspec, generated '
+        'chat lock and current release-document inventory.';
   }
   for (final entry in files.entries) {
     if (entry.value.base.mode != '100644' ||
@@ -79,19 +80,8 @@ String? validateReleaseMetadata(Map<String, ReadinessFilePair> files) {
   for (final path in releaseMetadataDocs) {
     final pair = files[path];
     if (pair == null) continue;
-    // Markdown in Docusaurus may contain executable MDX. Preserve its complete
-    // syntax-bearing fragments and import/export lines rather than exempt it.
-    final baseActive = _activeFragments(pair.base.contents);
-    final headActive = _activeFragments(pair.head.contents);
-    if (baseActive == null ||
-        headActive == null ||
-        baseActive != headActive ||
-        _frontMatter(pair.base.contents) != _frontMatter(pair.head.contents) ||
-        _runtimeIdentities(pair.base.contents) !=
-            _runtimeIdentities(pair.head.contents)) {
-      return 'Release documentation cannot change embedded MDX/HTML syntax: '
-          '$path.';
-    }
+    var baseProse = pair.base.contents;
+    var headProse = pair.head.contents;
     if (path.endsWith('README.md') || path.endsWith('installation.md')) {
       final dependencies = RegExp(
         r'^\s+llamadart:\s+\^([^\s#]+)',
@@ -127,6 +117,25 @@ String? validateReleaseMetadata(Map<String, ReadinessFilePair> files) {
         return 'Release changelogs must name the new patch and preserve all '
             'historical numbered sections: $path.';
       }
+      // Historical bytes are already immutable. Do not reinterpret their old
+      // Markdown with a new parser; inspect only the mutable release prefix.
+      final historyLength = pair.base.contents.length - historical.start;
+      baseProse = pair.base.contents.substring(0, historical.start);
+      headProse = pair.head.contents.substring(
+        0,
+        pair.head.contents.length - historyLength,
+      );
+    }
+    // This exception is for Markdown prose/code examples, not active MDX.
+    // Deny active contexts altogether: fragment equality cannot establish JS
+    // equivalence (template literal attributes or script bodies can change).
+    if (_activeFragments(baseProse) != '' ||
+        _activeFragments(headProse) != '' ||
+        _frontMatter(pair.base.contents) != _frontMatter(pair.head.contents) ||
+        _runtimeIdentities(pair.base.contents) !=
+            _runtimeIdentities(pair.head.contents)) {
+      return 'Metadata release docs require inactive Markdown, unchanged '
+          'frontmatter and unchanged runtime identities: $path.';
     }
   }
   return null;

From a8bb6ff318d2ef028b81f549cd1aefe7929abf07 Mon Sep 17 00:00:00 2001
From: Jhin Lee <jhin.lee@unity3d.com>
Date: Mon, 7 Sep 2026 16:18:33 -0400
Subject: [PATCH 3/3] test: guard release section transitions

---
 .../tooling/high_risk_readiness_test.dart     | 20 +++++++++++++++++++
 tool/testing/release_metadata_readiness.dart  | 16 +++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/test/unit/tooling/high_risk_readiness_test.dart b/test/unit/tooling/high_risk_readiness_test.dart
index 2e030c5b..489df22f 100644
--- a/test/unit/tooling/high_risk_readiness_test.dart
+++ b/test/unit/tooling/high_risk_readiness_test.dart
@@ -336,6 +336,26 @@ void mutateIdentityToOtherValidValues(Map<String, dynamic> evidence) {
 
 void main() {
   group('bounded metadata-only release evidence', () {
+    test(
+      'new release prefix cannot duplicate or invent historical sections',
+      () async {
+        for (final heading in ['## 0.8.22', '## 9.0.0', '## Migration']) {
+          final files = metadataFiles();
+          final old = files[headSha]!['CHANGELOG.md']!;
+          files[headSha]!['CHANGELOG.md'] = (
+            mode: old.mode,
+            contents: old.contents.replaceFirst(
+              '* Update.',
+              '* Update.\n\n$heading\n\n* Duplicate.',
+            ),
+          );
+          expectFailure(
+            await evaluateMetadata(files: files),
+            ReadinessFailureClassification.invalidReleaseMetadata,
+          );
+        }
+      },
+    );
     test(
       'existing active JSX template attributes and script bodies cannot use exception',
       () async {
diff --git a/tool/testing/release_metadata_readiness.dart b/tool/testing/release_metadata_readiness.dart
index 49ff0a1d..061913db 100644
--- a/tool/testing/release_metadata_readiness.dart
+++ b/tool/testing/release_metadata_readiness.dart
@@ -125,6 +125,22 @@ String? validateReleaseMetadata(Map<String, ReadinessFilePair> files) {
         0,
         pair.head.contents.length - historyLength,
       );
+      final headings = RegExp(r'^## ([^\n]+)$', multiLine: true);
+      final before = headings
+          .allMatches(baseProse)
+          .map((m) => m.group(1))
+          .toList();
+      final after = headings
+          .allMatches(headProse)
+          .map((m) => m.group(1))
+          .toList();
+      if (before.length != 1 ||
+          before.single != 'Unreleased' ||
+          after.length != 1 ||
+          after.single != newVersion) {
+        return 'Metadata release must replace only the Unreleased section '
+            'heading with the next core patch: $path.';
+      }
     }
     // This exception is for Markdown prose/code examples, not active MDX.
     // Deny active contexts altogether: fragment equality cannot establish JS