modwire 9.1.0__tar.gz → 9.2.0__tar.gz

{modwire-9.1.0 → modwire-9.2.0}/.dev/modwire.egg-info/SOURCES.txt

@@ -119,6 +119,8 @@ src/modwire/cli/cache/models/__init__.py
 src/modwire/cli/cache/models/cache_entry.py
 src/modwire/cli/cache/models/cache_key.py
 src/modwire/cli/cache/models/cache_options.py
+src/modwire/cli/cache/models/cache_outcome.py
+src/modwire/cli/cache/models/cached_result.py
 src/modwire/cli/cache/models/extraction_snapshot.py
 src/modwire/cli/cache/models/source_entry.py
 src/modwire/cli/cache/models/source_inventory.py

{modwire-9.1.0 → modwire-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modwire
-Version: 9.1.0
+Version: 9.2.0
 Summary: Code extraction, architecture analysis and the Modwire CLI.
 Author: Tomasz Szpak
 License-Expression: MIT
@@ -52,6 +52,10 @@ Analyze a code map with a validated architecture configuration.
 
 Analyze a code map, reusing reports for an exact map and configuration identity.
 
+### `analyze_cached_with_diagnostics`
+
+Analyze a code map and report the public outcome of report-cache reuse.
+
 ### `discover`
 
 Discover supported source languages beneath a root using the caller's scan policy.
@@ -72,10 +76,18 @@ Extract source files and return a queryable code map.
 
 Return a code map with content-addressed source and complete-manifest reuse.
 
+### `generate_map_cached_with_diagnostics`
+
+Return a code map and public outcomes for extraction and complete-map reuse.
+
 ### `generate_queryable_map_cached`
 
 Return a queryable code map with content-addressed persistent reuse.
 
+### `generate_queryable_map_cached_with_diagnostics`
+
+Return a queryable code map and public outcomes for every applicable cache stage.
+
 ### `clear_cache`
 
 Clear only the Modwire-owned directory for one cache namespace.
@@ -100,6 +112,26 @@ Run the native extractor transport for one supported language.
 
 Run the Modwire command line interface and return its process status.
 
+## `CacheStage`
+
+Public stages reported by cached Modwire operations.
+
+## `CacheOutcome`
+
+Content-safe lifecycle counts for one stage of a cached operation.
+
+Extraction counts describe current source records. Code-map and report counts
+describe one entry. Invalidated entries are also misses. Diagnostics include
+the configured namespace but never cache keys, source identities, or content.
+
+## `CachedResult`
+
+A cached operation value together with one outcome per applicable stage.
+
+### `outcome`
+
+Return the outcome for one applicable cache stage.
+
 ## `CacheOptions`
 
 Generic persistent-cache settings supplied by a caller.

{modwire-9.1.0 → modwire-9.2.0}/README.md

@@ -24,6 +24,10 @@ Analyze a code map with a validated architecture configuration.
 
 Analyze a code map, reusing reports for an exact map and configuration identity.
 
+### `analyze_cached_with_diagnostics`
+
+Analyze a code map and report the public outcome of report-cache reuse.
+
 ### `discover`
 
 Discover supported source languages beneath a root using the caller's scan policy.
@@ -44,10 +48,18 @@ Extract source files and return a queryable code map.
 
 Return a code map with content-addressed source and complete-manifest reuse.
 
+### `generate_map_cached_with_diagnostics`
+
+Return a code map and public outcomes for extraction and complete-map reuse.
+
 ### `generate_queryable_map_cached`
 
 Return a queryable code map with content-addressed persistent reuse.
 
+### `generate_queryable_map_cached_with_diagnostics`
+
+Return a queryable code map and public outcomes for every applicable cache stage.
+
 ### `clear_cache`
 
 Clear only the Modwire-owned directory for one cache namespace.
@@ -72,6 +84,26 @@ Run the native extractor transport for one supported language.
 
 Run the Modwire command line interface and return its process status.
 
+## `CacheStage`
+
+Public stages reported by cached Modwire operations.
+
+## `CacheOutcome`
+
+Content-safe lifecycle counts for one stage of a cached operation.
+
+Extraction counts describe current source records. Code-map and report counts
+describe one entry. Invalidated entries are also misses. Diagnostics include
+the configured namespace but never cache keys, source identities, or content.
+
+## `CachedResult`
+
+A cached operation value together with one outcome per applicable stage.
+
+### `outcome`
+
+Return the outcome for one applicable cache stage.
+
 ## `CacheOptions`
 
 Generic persistent-cache settings supplied by a caller.

{modwire-9.1.0 → modwire-9.2.0}/src/modwire/application.py

@@ -11,13 +11,24 @@ from .architecture.facade import ArchitectureFacade
 from .architecture.report.models.report_catalog import ReportCatalog
 from .architecture.report.models.report_node import ReportNode
 from .cli.cache.models.cache_options import CacheOptions
+from .cli.cache.models.cache_outcome import CacheOutcome, CacheStage
+from .cli.cache.models.cached_result import CachedResult
 from .cli.facade import CliFacade
 from .cli.pipeline.models.scan_policy import ScanPolicy
 from .extraction.facade import ExtractionFacade
 from .shared.code.models.code_map import CodeMap
 from .shared.code.models.queryable_code_map import QueryableCodeMap
 
-__all__ = ["CacheOptions", "CodeMap", "ModwireApplication", "QueryableCodeMap", "ScanPolicy"]
+__all__ = [
+    "CacheOptions",
+    "CacheOutcome",
+    "CacheStage",
+    "CachedResult",
+    "CodeMap",
+    "ModwireApplication",
+    "QueryableCodeMap",
+    "ScanPolicy",
+]
 
 
 @dataclass(frozen=True)
@@ -62,12 +73,20 @@ class ModwireApplication:
     ) -> tuple[ReportNode, ...]:
         """Analyze a code map, reusing reports for an exact map and configuration identity."""
 
+        return self.analyze_cached_with_diagnostics(code_map, config, options).value
+
+    def analyze_cached_with_diagnostics(
+        self, code_map: QueryableCodeMap, config: ArchitectureConfig, options: CacheOptions
+    ) -> CachedResult[tuple[ReportNode, ...]]:
+        """Analyze a code map and report the public outcome of report-cache reuse."""
+
         cached = self.cli.cached_reports(code_map.code_map, config, options)
-        if cached is not None:
-            return cached
+        if cached.value is not None:
+            return CachedResult(value=cached.value, outcomes=cached.outcomes)
         reports = self.architecture.analyze(code_map, config)
         self.cli.store_reports(code_map.code_map, config, reports, options)
-        return reports
+        outcome = cached.outcome(CacheStage.REPORTS).model_copy(update={"computed": 1, "stored": 1})
+        return CachedResult(value=reports, outcomes=(outcome,))
 
     def discover(self, root: str, policy: ScanPolicy) -> tuple[str, ...]:
         """Discover supported source languages beneath a root using the caller's scan policy."""
@@ -97,21 +116,39 @@ class ModwireApplication:
     def generate_map_cached(self, language: str, root: str, policy: ScanPolicy, options: CacheOptions) -> CodeMap:
         """Return a code map with content-addressed source and complete-manifest reuse."""
 
+        return self.generate_map_cached_with_diagnostics(language, root, policy, options).value
+
+    def generate_map_cached_with_diagnostics(
+        self, language: str, root: str, policy: ScanPolicy, options: CacheOptions
+    ) -> CachedResult[CodeMap]:
+        """Return a code map and public outcomes for extraction and complete-map reuse."""
+
         request = self.extraction.request(language, str(root))
         snapshot = self.cli.extract_cached(request, policy, options)
-        cached = self.cli.cached_code_map(snapshot, options)
-        if cached is not None:
-            return cached
-        code_map = self.extraction.generate_map(language, snapshot.extraction)
-        self.cli.store_code_map(snapshot, code_map, options)
-        return code_map
+        cached = self.cli.cached_code_map(snapshot.value, options)
+        outcome = cached.outcome(CacheStage.CODE_MAP)
+        if cached.value is not None:
+            code_map = cached.value
+        else:
+            code_map = self.extraction.generate_map(language, snapshot.value.extraction)
+            self.cli.store_code_map(snapshot.value, code_map, options)
+            outcome = outcome.model_copy(update={"computed": 1, "stored": 1})
+        return CachedResult(value=code_map, outcomes=(*snapshot.outcomes, outcome))
 
     def generate_queryable_map_cached(
         self, language: str, root: str, policy: ScanPolicy, options: CacheOptions
     ) -> QueryableCodeMap:
         """Return a queryable code map with content-addressed persistent reuse."""
 
-        return QueryableCodeMap(code_map=self.generate_map_cached(language, root, policy, options))
+        return self.generate_queryable_map_cached_with_diagnostics(language, root, policy, options).value
+
+    def generate_queryable_map_cached_with_diagnostics(
+        self, language: str, root: str, policy: ScanPolicy, options: CacheOptions
+    ) -> CachedResult[QueryableCodeMap]:
+        """Return a queryable code map and public outcomes for every applicable cache stage."""
+
+        cached = self.generate_map_cached_with_diagnostics(language, root, policy, options)
+        return CachedResult(value=QueryableCodeMap(code_map=cached.value), outcomes=cached.outcomes)
 
     def clear_cache(self, options: CacheOptions) -> None:
         """Clear only the Modwire-owned directory for one cache namespace."""
@@ -131,7 +168,9 @@ class ModwireApplication:
     def generate_documentation(self, readme: str, check: bool) -> int:
         """Generate this README from the published interface docstrings, or check that it is current."""
 
-        return self.cli.generate_documentation(str(readme), (type(self), CacheOptions, ScanPolicy), check)
+        return self.cli.generate_documentation(
+            str(readme), (type(self), CacheStage, CacheOutcome, CachedResult, CacheOptions, ScanPolicy), check
+        )
 
     def run_extractor(self, language: str) -> int:
         """Run the native extractor transport for one supported language."""

{modwire-9.1.0 → modwire-9.2.0}/src/modwire/cli/cache/application.py

@@ -18,11 +18,19 @@ from ..pipeline.models.scan_policy import ScanPolicy
 from .domain import CacheStorage
 from .models.cache_key import CacheKey
 from .models.cache_options import CacheOptions
+from .models.cache_outcome import CacheOutcome, CacheStage
+from .models.cached_result import CachedResult
 from .models.extraction_snapshot import ExtractionSnapshot
 from .services.cache_codec import CacheCodec
 from .services.cache_identity import CacheIdentity
 
 
+@dataclass(frozen=True)
+class _CacheRead:
+    value: object | None
+    invalidated: bool
+
+
 @injectable
 @dataclass(frozen=True)
 class CacheApplication:
@@ -40,21 +48,26 @@ class CacheApplication:
 
     def extract_cached(
         self, request: ExtractionRequest, policy: ScanPolicy, options: CacheOptions
-    ) -> ExtractionSnapshot:
+    ) -> CachedResult[ExtractionSnapshot]:
         inventory = self.reader.inventory(request, policy)
         keys = {entry.source_id: self.identity.source(request, policy, entry) for entry in inventory.entries}
         files: dict[FileId, SourceFile] = {}
         misses: list[FileId] = []
+        hits = 0
+        invalidated = 0
         for entry in inventory.entries:
             key = keys[entry.source_id]
-            value = self._read(options, key)
+            cached = self._read(options, key)
             try:
-                source_file = SourceFile.model_validate(value)
+                source_file = SourceFile.model_validate(cached.value)
                 if source_file.file_id != entry.source_id:
                     raise ValueError("Cached source identity does not match its key.")
                 files[entry.source_id] = source_file
+                hits += 1
             except (TypeError, ValueError, ValidationError):
-                self.storage.delete(options, key)
+                if cached.value is not None and not cached.invalidated:
+                    self.storage.delete(options, key)
+                invalidated += int(cached.invalidated or cached.value is not None)
                 misses.append(entry.source_id)
 
         if misses or not inventory.entries:
@@ -98,16 +111,38 @@ class CacheApplication:
             },
         )
         self.prune(options)
-        return ExtractionSnapshot(extraction=extraction, manifest=manifest)
+        return CachedResult(
+            value=ExtractionSnapshot(extraction=extraction, manifest=manifest),
+            outcomes=(
+                CacheOutcome(
+                    stage=CacheStage.EXTRACTION,
+                    namespace=options.namespace,
+                    hits=hits,
+                    misses=len(misses),
+                    invalidated=invalidated,
+                    computed=len(misses),
+                    stored=len(misses),
+                ),
+            ),
+        )
 
-    def code_map(self, snapshot: ExtractionSnapshot, options: CacheOptions) -> CodeMap | None:
+    def code_map(self, snapshot: ExtractionSnapshot, options: CacheOptions) -> CachedResult[CodeMap | None]:
         key = self.identity.code_map("", snapshot.manifest)
-        value = self._read(options, key)
+        cached = self._read(options, key)
         try:
-            return CodeMap.model_validate(value)
+            value = CodeMap.model_validate(cached.value)
+            outcome = CacheOutcome(stage=CacheStage.CODE_MAP, namespace=options.namespace, hits=1)
         except (TypeError, ValueError, ValidationError):
-            self.storage.delete(options, key)
-            return None
+            if cached.value is not None and not cached.invalidated:
+                self.storage.delete(options, key)
+            value = None
+            outcome = CacheOutcome(
+                stage=CacheStage.CODE_MAP,
+                namespace=options.namespace,
+                misses=1,
+                invalidated=int(cached.invalidated or cached.value is not None),
+            )
+        return CachedResult[CodeMap | None](value=value, outcomes=(outcome,))
 
     def store_code_map(self, snapshot: ExtractionSnapshot, code_map: CodeMap, options: CacheOptions) -> None:
         self._write(options, self.identity.code_map("", snapshot.manifest), code_map.model_dump(mode="json"))
@@ -115,17 +150,28 @@ class CacheApplication:
 
     def reports(
         self, code_map: CodeMap, config: ArchitectureConfig, options: CacheOptions
-    ) -> tuple[ReportNode, ...] | None:
+    ) -> CachedResult[tuple[ReportNode, ...] | None]:
         key = self.identity.reports(code_map, config)
-        value = self._read(options, key)
+        cached = self._read(options, key)
+        cached_value: object | None = cached.value
+        invalidated = cached.invalidated or cached_value is not None
         try:
-            if not isinstance(value, list):
+            if not isinstance(cached_value, list):
                 raise ValueError("Cached reports must be a list.")
-            reports = tuple(self._report(item) for item in cast(list[object], value))
-            return tuple(sorted(reports, key=lambda item: (item.metadata.order, item.metadata.id)))
+            reports = tuple(self._report(item) for item in cast(list[object], cached_value))
+            value = tuple(sorted(reports, key=lambda item: (item.metadata.order, item.metadata.id)))
+            outcome = CacheOutcome(stage=CacheStage.REPORTS, namespace=options.namespace, hits=1)
         except (AttributeError, ImportError, KeyError, TypeError, ValueError, ValidationError):
-            self.storage.delete(options, key)
-            return None
+            if cached_value is not None and not cached.invalidated:
+                self.storage.delete(options, key)
+            value = None
+            outcome = CacheOutcome(
+                stage=CacheStage.REPORTS,
+                namespace=options.namespace,
+                misses=1,
+                invalidated=int(invalidated),
+            )
+        return CachedResult[tuple[ReportNode, ...] | None](value=value, outcomes=(outcome,))
 
     def store_reports(
         self,
@@ -156,14 +202,15 @@ class CacheApplication:
             self.storage.delete(options, entry.key)
             total -= entry.size
 
-    def _read(self, options: CacheOptions, key: CacheKey) -> object | None:
+    def _read(self, options: CacheOptions, key: CacheKey) -> _CacheRead:
         payload = self.storage.read(options, key)
         if payload is None:
-            return None
+            return _CacheRead(value=None, invalidated=False)
         value = self.codec.decode(key, payload)
         if value is None:
             self.storage.delete(options, key)
-        return value
+            return _CacheRead(value=None, invalidated=True)
+        return _CacheRead(value=value, invalidated=False)
 
     def _write(self, options: CacheOptions, key: CacheKey, value: object) -> None:
         self.storage.write(options, key, self.codec.encode(key, value))

modwire-9.2.0/src/modwire/cli/cache/models/cache_outcome.py

@@ -0,0 +1,44 @@
+from enum import StrEnum
+
+from pydantic import field_validator
+
+from ....shared.values.models.value_model import ValueModel
+
+
+class CacheStage(StrEnum):
+    """Public stages reported by cached Modwire operations."""
+
+    EXTRACTION = "extraction"
+    CODE_MAP = "code-map"
+    REPORTS = "reports"
+
+
+class CacheOutcome(ValueModel):
+    """Content-safe lifecycle counts for one stage of a cached operation.
+
+    Extraction counts describe current source records. Code-map and report counts
+    describe one entry. Invalidated entries are also misses. Diagnostics include
+    the configured namespace but never cache keys, source identities, or content.
+    """
+
+    stage: CacheStage
+    namespace: str
+    hits: int = 0
+    misses: int = 0
+    invalidated: int = 0
+    computed: int = 0
+    stored: int = 0
+
+    @field_validator("namespace")
+    @classmethod
+    def _non_empty_namespace(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Cache outcome namespace must not be empty.")
+        return value
+
+    @field_validator("hits", "misses", "invalidated", "computed", "stored")
+    @classmethod
+    def _non_negative_count(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("Cache outcome counts must not be negative.")
+        return value

modwire-9.2.0/src/modwire/cli/cache/models/cached_result.py

@@ -0,0 +1,29 @@
+from pydantic import field_validator
+
+from ....shared.values.models.value_model import ValueModel
+from .cache_outcome import CacheOutcome, CacheStage
+
+
+class CachedResult[Result](ValueModel):
+    """A cached operation value together with one outcome per applicable stage."""
+
+    value: Result
+    outcomes: tuple[CacheOutcome, ...]
+
+    @field_validator("outcomes")
+    @classmethod
+    def _unique_non_empty_stages(cls, value: tuple[CacheOutcome, ...]) -> tuple[CacheOutcome, ...]:
+        if not value:
+            raise ValueError("A cached result requires at least one cache outcome.")
+        stages = tuple(outcome.stage for outcome in value)
+        if len(stages) != len(set(stages)):
+            raise ValueError("A cached result must contain at most one outcome per stage.")
+        return value
+
+    def outcome(self, stage: CacheStage) -> CacheOutcome:
+        """Return the outcome for one applicable cache stage."""
+
+        for outcome in self.outcomes:
+            if outcome.stage == stage:
+                return outcome
+        raise LookupError(f"Cache stage is not applicable to this result: {stage}")

{modwire-9.1.0 → modwire-9.2.0}/src/modwire/cli/facade.py

@@ -14,6 +14,7 @@ from ..shared.code.models.queryable_code_map import QueryableCodeMap
 from ..shared.code.models.source_extraction import SourceExtraction
 from .cache.application import CacheApplication
 from .cache.models.cache_options import CacheOptions
+from .cache.models.cached_result import CachedResult
 from .cache.models.extraction_snapshot import ExtractionSnapshot
 from .documentation.application import DocumentationApplication
 from .initialization.application import InitializationApplication
@@ -53,10 +54,10 @@ class CliFacade:
 
     def extract_cached(
         self, request: ExtractionRequest, policy: ScanPolicy, options: CacheOptions
-    ) -> ExtractionSnapshot:
+    ) -> CachedResult[ExtractionSnapshot]:
         return self.cache.extract_cached(request, policy, options)
 
-    def cached_code_map(self, snapshot: ExtractionSnapshot, options: CacheOptions) -> CodeMap | None:
+    def cached_code_map(self, snapshot: ExtractionSnapshot, options: CacheOptions) -> CachedResult[CodeMap | None]:
         return self.cache.code_map(snapshot, options)
 
     def store_code_map(self, snapshot: ExtractionSnapshot, code_map: CodeMap, options: CacheOptions) -> None:
@@ -64,7 +65,7 @@ class CliFacade:
 
     def cached_reports(
         self, code_map: CodeMap, config: ArchitectureConfig, options: CacheOptions
-    ) -> tuple[ReportNode, ...] | None:
+    ) -> CachedResult[tuple[ReportNode, ...] | None]:
         return self.cache.reports(code_map, config, options)
 
     def store_reports(
@@ -127,13 +128,13 @@ class CliFacade:
             extraction = self.extract(extraction_request, policy)
             code_map = self.extraction.generate_queryable_map(request.language, extraction)
             return self.render(self.architecture.analyze(code_map, config), request.summary)
-        snapshot = self.extract_cached(extraction_request, policy, cache_options)
-        cached_code_map = self.cached_code_map(snapshot, cache_options)
+        snapshot = self.extract_cached(extraction_request, policy, cache_options).value
+        cached_code_map = self.cached_code_map(snapshot, cache_options).value
         if cached_code_map is None:
             cached_code_map = self.extraction.generate_map(request.language, snapshot.extraction)
             self.store_code_map(snapshot, cached_code_map, cache_options)
         code_map = QueryableCodeMap(code_map=cached_code_map)
-        reports = self.cached_reports(cached_code_map, config, cache_options)
+        reports = self.cached_reports(cached_code_map, config, cache_options).value
         if reports is None:
             reports = self.architecture.analyze(code_map, config)
             self.store_reports(cached_code_map, config, reports, cache_options)

{modwire-9.1.0 → modwire-9.2.0}/tests/application/test_07_cache.py

@@ -1,11 +1,98 @@
 from concurrent.futures import ThreadPoolExecutor
 
-from modwire.application import CacheOptions
+from modwire.application import CacheOptions, CacheStage
 
 from .base_test import ApplicationTestCase
 
 
 class TestPersistentCache(ApplicationTestCase):
+    def test_public_map_diagnostics_distinguish_cold_and_warm_cache_stages(self) -> None:
+        root = self.project({"src/example.py": "def example_function():\n    return 1\n"})
+        options = self.cache_options("example-diagnostics")
+
+        cold = self.application.generate_map_cached_with_diagnostics("python", root, self.scan_policy(), options)
+        warm = self.application.generate_map_cached_with_diagnostics("python", root, self.scan_policy(), options)
+
+        assert cold.value == warm.value
+        assert cold.outcome(CacheStage.EXTRACTION).to_dict() == {
+            "stage": "extraction",
+            "namespace": "example-diagnostics",
+            "hits": 0,
+            "misses": 1,
+            "invalidated": 0,
+            "computed": 1,
+            "stored": 1,
+        }
+        assert cold.outcome(CacheStage.CODE_MAP).to_dict() == {
+            "stage": "code-map",
+            "namespace": "example-diagnostics",
+            "hits": 0,
+            "misses": 1,
+            "invalidated": 0,
+            "computed": 1,
+            "stored": 1,
+        }
+        assert warm.outcome(CacheStage.EXTRACTION).hits == 1
+        assert warm.outcome(CacheStage.EXTRACTION).misses == 0
+        assert warm.outcome(CacheStage.CODE_MAP).hits == 1
+        assert warm.outcome(CacheStage.CODE_MAP).misses == 0
+
+    def test_public_map_diagnostics_report_partial_source_reuse(self) -> None:
+        root = self.project(
+            {
+                "src/example_first.py": "def example_first():\n    return 1\n",
+                "src/example_second.py": "def example_second():\n    return 2\n",
+            }
+        )
+        options = self.cache_options("example-partial-diagnostics")
+        self.application.generate_map_cached_with_diagnostics("python", root, self.scan_policy(), options)
+        (root / "src/example_second.py").write_text("def example_changed():\n    return 2\n", encoding="utf-8")
+
+        changed = self.application.generate_map_cached_with_diagnostics("python", root, self.scan_policy(), options)
+
+        extraction = changed.outcome(CacheStage.EXTRACTION)
+        code_map = changed.outcome(CacheStage.CODE_MAP)
+        assert (extraction.hits, extraction.misses, extraction.computed, extraction.stored) == (1, 1, 1, 1)
+        assert extraction.invalidated == 0
+        assert (code_map.hits, code_map.misses, code_map.computed, code_map.stored) == (0, 1, 1, 1)
+
+    def test_public_map_diagnostics_report_invalidated_entries(self) -> None:
+        root = self.project({"src/example.py": "class ExampleValue:\n    pass\n"})
+        options = self.cache_options("example-invalidated-diagnostics")
+        expected = self.application.generate_map_cached_with_diagnostics("python", root, self.scan_policy(), options)
+        for path in (self.workspace / "cache").rglob("*.cache"):
+            path.write_bytes(b"not-a-cache-entry")
+
+        recovered = self.application.generate_map_cached_with_diagnostics("python", root, self.scan_policy(), options)
+
+        assert recovered.value == expected.value
+        assert recovered.outcome(CacheStage.EXTRACTION).invalidated == 1
+        assert recovered.outcome(CacheStage.EXTRACTION).misses == 1
+        assert recovered.outcome(CacheStage.CODE_MAP).invalidated == 1
+        assert recovered.outcome(CacheStage.CODE_MAP).misses == 1
+
+    def test_public_report_diagnostics_distinguish_cold_and_warm_results(self) -> None:
+        root = self.project({"src/example.py": "def example_function():\n    return 1\n"})
+        options = self.cache_options("example-report-diagnostics")
+        code_map = self.application.generate_queryable_map_cached("python", root, self.scan_policy(), options)
+        config = self.example_configuration()
+
+        cold = self.application.analyze_cached_with_diagnostics(code_map, config, options)
+        warm = self.application.analyze_cached_with_diagnostics(code_map, config, options)
+
+        assert cold.value == warm.value
+        assert cold.outcome(CacheStage.REPORTS).to_dict() == {
+            "stage": "reports",
+            "namespace": "example-report-diagnostics",
+            "hits": 0,
+            "misses": 1,
+            "invalidated": 0,
+            "computed": 1,
+            "stored": 1,
+        }
+        assert warm.outcome(CacheStage.REPORTS).hits == 1
+        assert warm.outcome(CacheStage.REPORTS).misses == 0
+
     def test_warm_code_map_matches_the_uncached_public_result(self) -> None:
         root = self.project({"src/example.py": "def example_function():\n    return 1\n"})
         options = self.cache_options("example-warm")