fix(components): honor unified release manifests in reports (#408)

* fix(components): honor unified release manifests in reports

Co-authored-by: Codex <codex@openai.com>

* fix(components): normalize manifest fallback errors

Co-authored-by: Codex <codex@openai.com>

---------

Co-authored-by: Codex <codex@openai.com>

Author: solomonneas

src/brigade/component_install.py

@@ -52,6 +52,14 @@ class ComponentInstallError(RuntimeError):
     """Raised when a component install step fails verification."""
 
 
+class ExactReleaseManifestError(RuntimeError):
+    """Raised when matching update state cannot provide a verified manifest."""
+
+    def __init__(self, message: str, manifest_path: Path) -> None:
+        super().__init__(message)
+        self.manifest_path = manifest_path
+
+
 _SETUP_ACTIONS: tuple[str, ...] = ("verify-cache", "download", "materialize", "smoke")
 
 
@@ -91,6 +99,51 @@ def resolve_roots(
     )
 
 
+def uses_bundled_compatibility_manifest() -> bool:
+    """Return whether automatic manifest selection starts at the bundled fallback."""
+    bundled_path = templates.template_root() / "components" / "manifest-v1.json"
+    return component_manifest.manifest_path() == bundled_path
+
+
+def load_verified_exact_release_manifest(
+    roots: SetupRoots,
+) -> tuple[component_manifest.ComponentManifest, Path] | None:
+    """Read the current release manifest recorded in update state without mutating it."""
+    from brigade import update_cmd
+
+    state_path = Path(component_paths.update_state_path(roots.data_root))
+    state = update_cmd.load_update_state(state_path)
+    if state is None or state.component_tag != f"v{brigade.__version__}":
+        return None
+
+    cached = Path(component_paths.verified_manifest_path(roots.cache_root, state.component_manifest_sha256))
+    if not cached.is_file():
+        raise ExactReleaseManifestError("cached exact-release manifest is missing", cached)
+    try:
+        cached_bytes = cached.read_bytes()
+    except OSError as exc:
+        raise ExactReleaseManifestError(f"cached exact-release manifest cannot be read: {exc}", cached) from exc
+    if hashlib.sha256(cached_bytes).hexdigest() != state.component_manifest_sha256:
+        raise ExactReleaseManifestError("cached exact-release manifest digest does not match update state", cached)
+
+    release = update_cmd.ResolvedRelease(
+        state.component_release_id,
+        state.component_tag,
+        brigade.__version__,
+        state.component_target_commit,
+        state.component_manifest_url,
+        len(cached_bytes),
+        state.component_manifest_sha256,
+        cached_bytes,
+    )
+    try:
+        return update_cmd.validate_release_manifest_bytes(release), cached
+    except update_cmd.UpdateError as exc:
+        raise ExactReleaseManifestError(str(exc), cached) from exc
+    except ValueError as exc:
+        raise ExactReleaseManifestError(f"cached exact-release manifest is invalid: {exc}", cached) from exc
+
+
 def build_setup_plan(
     manifest: component_manifest.ComponentManifest,
     *,
@@ -707,42 +760,25 @@ def _load_setup_manifest(
     if manifest_source != "auto":
         raise ComponentInstallError("manifest source must be auto or standalone")
 
-    bundled_path = templates.template_root() / "components" / "manifest-v1.json"
-    if component_manifest.manifest_path() != bundled_path:
+    if not uses_bundled_compatibility_manifest():
         return component_manifest.load(), None
 
     from brigade import update_cmd
 
     roots = resolve_roots(env=env)
     try:
         if offline:
-            state_path = Path(component_paths.update_state_path(roots.data_root))
-            state = update_cmd.load_update_state(state_path)
-            if state is not None and state.component_tag == f"v{brigade.__version__}":
-                cached = Path(component_paths.verified_manifest_path(roots.cache_root, state.component_manifest_sha256))
-                if cached.is_file():
-                    cached_bytes = cached.read_bytes()
-                    if hashlib.sha256(cached_bytes).hexdigest() != state.component_manifest_sha256:
-                        raise ComponentInstallError("cached exact-release manifest digest does not match update state")
-                    release = update_cmd.ResolvedRelease(
-                        state.component_release_id,
-                        state.component_tag,
-                        brigade.__version__,
-                        state.component_target_commit,
-                        state.component_manifest_url,
-                        len(cached_bytes),
-                        state.component_manifest_sha256,
-                        cached_bytes,
-                    )
-                    return update_cmd.validate_release_manifest_bytes(release), None
+            cached_manifest = load_verified_exact_release_manifest(roots)
+            if cached_manifest is not None:
+                return cached_manifest[0], None
             raise ComponentInstallError("offline setup requires a verified exact-release manifest cache")
 
         release = update_cmd.resolve_release(update_cmd._DefaultHttp(), latest=False, tag=f"v{brigade.__version__}")
         update_cmd._cache_manifest(
             update_cmd.UpdatePaths(Path(roots.data_root), Path(roots.cache_root), Path("unused")), release
         )
         return update_cmd.validate_release_manifest_bytes(release), release
-    except update_cmd.UpdateError as exc:
+    except (update_cmd.UpdateError, ExactReleaseManifestError, ValueError) as exc:
         raise ComponentInstallError(f"exact release manifest setup failed: {exc}") from exc
 
 

src/brigade/component_report.py

@@ -75,32 +75,63 @@ def inspect_components(
 ) -> ComponentReport:
     """Inspect managed native components without mutating user data."""
     environment = dict(env if env is not None else os.environ)
-    manifest_source = manifest_path or component_manifest.manifest_path()
     manifest_unknown: tuple[str, ...] = ()
     manifest_schema_version: int | None = None
     manifest_revision: str | None = None
     manifest_brigade_version: str | None = None
+    roots: component_install.SetupRoots | None = None
+    environment_error: str | None = None
+    try:
+        roots = component_install.resolve_roots(env=environment, system=system)
+    except ValueError as exc:
+        environment_error = str(exc)
+
+    state_path = Path(
+        component_paths.installed_state_path(roots.data_root if roots is not None else _UNAVAILABLE_DATA_ROOT)
+    )
+    installed_state, state_file_status = _read_installed_state(state_path) if roots is not None else (None, "missing")
+
+    manifest_source = manifest_path or component_manifest.manifest_path()
     manifest: component_manifest.ComponentManifest | None = None
     try:
-        manifest = component_manifest.load(manifest_path) if manifest_path is not None else component_manifest.load()
+        if manifest_path is not None:
+            manifest = component_manifest.load(manifest_path)
+        elif roots is not None and component_install.uses_bundled_compatibility_manifest():
+            exact_release_manifest = component_install.load_verified_exact_release_manifest(roots)
+            if exact_release_manifest is None:
+                manifest = component_manifest.load()
+            else:
+                manifest, manifest_source = exact_release_manifest
+                if installed_state is not None and not _installed_state_matches_manifest(installed_state, manifest):
+                    manifest = component_manifest.load()
+                    manifest_source = component_manifest.manifest_path()
+        else:
+            manifest = component_manifest.load()
+    except component_install.ExactReleaseManifestError as exc:
+        return _environment_blocked_report(
+            manifest_source=exc.manifest_path,
+            platform_error=str(exc),
+            manifest=None,
+            roots=roots,
+            state_path=state_path,
+            installed_state=installed_state,
+            state_file_status=state_file_status,
+        )
     except ValueError as exc:
         return _environment_blocked_report(
             manifest_source=manifest_source,
             platform_error=str(exc),
             manifest=None,
+            roots=roots,
+            state_path=state_path,
+            installed_state=installed_state,
+            state_file_status=state_file_status,
         )
     manifest_schema_version = manifest.schema_version
     manifest_revision = manifest.manifest_revision
     manifest_brigade_version = manifest.brigade_version
     manifest_unknown = manifest.unknown_component_diagnostics
 
-    roots: component_install.SetupRoots | None = None
-    environment_error: str | None = None
-    try:
-        roots = component_install.resolve_roots(env=environment, system=system)
-    except ValueError as exc:
-        environment_error = str(exc)
-
     platform: str | None = None
     platform_error: str | None = environment_error
     if environment_error is None:
@@ -115,11 +146,12 @@ def inspect_components(
             platform_error=platform_error or "component environment is unavailable",
             manifest=manifest,
             manifest_unknown_diagnostics=manifest_unknown,
+            roots=roots,
+            state_path=state_path,
+            installed_state=installed_state,
+            state_file_status=state_file_status,
         )
 
-    state_path = Path(component_paths.installed_state_path(roots.data_root))
-    installed_state, state_file_status = _read_installed_state(state_path)
-
     inspections: list[ComponentInspection] = []
     for component_id in component_manifest.KNOWN_COMPONENT_IDS:
         inspections.append(
@@ -160,9 +192,14 @@ def _environment_blocked_report(
     platform_error: str,
     manifest: component_manifest.ComponentManifest | None,
     manifest_unknown_diagnostics: tuple[str, ...] = (),
+    roots: component_install.SetupRoots | None = None,
+    state_path: Path | None = None,
+    installed_state: component_state.InstalledState | None = None,
+    state_file_status: STATE_FILE_STATUS = "missing",
 ) -> ComponentReport:
     """Return a read-only unsupported report when roots or manifest cannot be resolved."""
-    state_path = Path(component_paths.installed_state_path(_UNAVAILABLE_DATA_ROOT))
+    report_state_path = state_path or Path(component_paths.installed_state_path(_UNAVAILABLE_DATA_ROOT))
+    data_root = roots.data_root if roots is not None else _UNAVAILABLE_DATA_ROOT
     components = tuple(
         ComponentInspection(
             component_id=component_id,
@@ -171,16 +208,36 @@ def _environment_blocked_report(
             expected_component_revision=(
                 manifest.components[component_id].component_revision if manifest is not None else None
             ),
-            installed_component_revision=None,
+            installed_component_revision=(
+                installed_state.components[component_id].component_revision
+                if installed_state is not None and component_id in installed_state.components
+                else None
+            ),
             expected_asset_name=None,
             expected_byte_size=None,
             expected_sha256=None,
-            installed_asset_name=None,
-            installed_byte_size=None,
-            installed_sha256=None,
-            recorded_executable=None,
+            installed_asset_name=(
+                installed_state.components[component_id].asset_name
+                if installed_state is not None and component_id in installed_state.components
+                else None
+            ),
+            installed_byte_size=(
+                installed_state.components[component_id].byte_size
+                if installed_state is not None and component_id in installed_state.components
+                else None
+            ),
+            installed_sha256=(
+                installed_state.components[component_id].sha256
+                if installed_state is not None and component_id in installed_state.components
+                else None
+            ),
+            recorded_executable=(
+                installed_state.components[component_id].executable
+                if installed_state is not None and component_id in installed_state.components
+                else None
+            ),
             managed_executable_path=component_paths.managed_executable_path(
-                _UNAVAILABLE_DATA_ROOT,
+                data_root,
                 component_id,
             ),
             actual_byte_size=None,
@@ -198,16 +255,46 @@ def _environment_blocked_report(
         platform=None,
         platform_error=platform_error,
         state_schema_version=component_state.SCHEMA_VERSION,
-        installed_state_path=str(state_path),
-        state_file_status="missing",
-        installed_manifest_revision=None,
-        installed_brigade_version=None,
-        installed_platform=None,
+        installed_state_path=str(report_state_path),
+        state_file_status=state_file_status,
+        installed_manifest_revision=installed_state.manifest_revision if installed_state else None,
+        installed_brigade_version=installed_state.brigade_version if installed_state else None,
+        installed_platform=installed_state.platform if installed_state else None,
         manifest_unknown_diagnostics=manifest_unknown_diagnostics,
         components=components,
     )
 
 
+def _installed_state_matches_manifest(
+    installed_state: component_state.InstalledState,
+    manifest: component_manifest.ComponentManifest,
+) -> bool:
+    """Return whether installed components use the manifest's exact recorded coordinates."""
+    if (
+        installed_state.manifest_revision != manifest.manifest_revision
+        or installed_state.brigade_version != manifest.brigade_version
+    ):
+        return False
+    for component_id in component_manifest.KNOWN_COMPONENT_IDS:
+        installed = installed_state.components.get(component_id)
+        if installed is None:
+            return False
+        component = manifest.components[component_id]
+        try:
+            asset = component_manifest.resolve_asset(manifest, component_id, installed_state.platform)
+        except ValueError:
+            return False
+        if (
+            installed.component_revision != component.component_revision
+            or installed.asset_name != asset.asset_name
+            or installed.byte_size != asset.byte_size
+            or installed.sha256 != asset.sha256
+            or installed.download_url != asset.download_url
+        ):
+            return False
+    return True
+
+
 def doctor_checks(
     *,
     env: Mapping[str, str] | None = None,

src/brigade/localio.py

@@ -37,7 +37,7 @@ def read_json_dict(path: Path) -> dict[str, Any] | None:
     """Read a JSON object from path; return None when missing, invalid, or not a dict."""
     try:
         payload = json.loads(path.read_text())
-    except (OSError, json.JSONDecodeError):
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
         return None
     return payload if isinstance(payload, dict) else None
 

tests/test_component_install.py

@@ -810,6 +810,24 @@ def test_setup_auto_offline_translates_rejected_cached_manifest_update_errors(tm
     assert "Traceback" not in err
 
 
+def test_setup_auto_online_translates_invalid_release_manifest(tmp_path, monkeypatch):
+    env, _release = _prepare_auto_release_setup(tmp_path, monkeypatch)
+    monkeypatch.setattr(
+        update_cmd,
+        "validate_release_manifest_bytes",
+        lambda _release: (_ for _ in ()).throw(ValueError("release manifest is invalid")),
+    )
+
+    with pytest.raises(ComponentInstallError, match="exact release manifest setup failed: release manifest is invalid"):
+        component_install._load_setup_manifest(
+            manifest_path=None,
+            manifest_source="auto",
+            offline=False,
+            opener=FakeOpener({}),
+            env=env,
+        )
+
+
 def test_setup_auto_online_translates_manifest_cache_collisions(tmp_path, monkeypatch, capsys):
     env, release = _prepare_auto_release_setup(tmp_path, monkeypatch)
     roots = resolve_roots(env=env, system="linux")