modwire 9.0.0__tar.gz → 9.1.0__tar.gz

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

@@ -112,6 +112,20 @@ src/modwire/architecture/shape/services/signature_resolver.py
 src/modwire/architecture/shape/services/symbol_resolver.py
 src/modwire/cli/__init__.py
 src/modwire/cli/facade.py
+src/modwire/cli/cache/__init__.py
+src/modwire/cli/cache/application.py
+src/modwire/cli/cache/domain.py
+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/extraction_snapshot.py
+src/modwire/cli/cache/models/source_entry.py
+src/modwire/cli/cache/models/source_inventory.py
+src/modwire/cli/cache/services/__init__.py
+src/modwire/cli/cache/services/cache_codec.py
+src/modwire/cli/cache/services/cache_identity.py
+src/modwire/cli/cache/services/filesystem_cache_storage.py
 src/modwire/cli/documentation/__init__.py
 src/modwire/cli/documentation/application.py
 src/modwire/cli/documentation/services/__init__.py
@@ -253,6 +267,7 @@ tests/application/__init__.py
 tests/application/base_test.py
 tests/application/test_01_attacks.py
 tests/application/test_06_happy_path.py
+tests/application/test_07_cache.py
 tests/architecture/__init__.py
 tests/architecture/base_test.py
 tests/architecture/boundaries/__init__.py
@@ -301,6 +316,8 @@ tests/extraction/big_projects/projects.json
 tests/extraction/big_projects/resolution_results.json
 tests/extraction/big_projects/results.json
 tests/extraction/big_projects/run.py
+tests/extraction/cache_benchmark/__init__.py
+tests/extraction/cache_benchmark/run.py
 tests/extraction/dependency/__init__.py
 tests/extraction/dependency/test_02_invariants.py
 tests/extraction/extractors/__init__.py

{modwire-9.0.0 → modwire-9.1.0}/Makefile

@@ -7,7 +7,7 @@ PROJECT_ROOT := $(CURDIR)
 export PYTHONPYCACHEPREFIX := $(PROJECT_ROOT)/$(DEV_DIR)/cache/python
 export UV_CACHE_DIR := $(PROJECT_ROOT)/$(DEV_DIR)/cache/uv
 
-.PHONY: big-projects build ci docs docs-check extractor-check format format-check host-check lint package-check scan-benchmark scan-benchmark-fixture test type-check
+.PHONY: big-projects build cache-benchmark ci docs docs-check extractor-check format format-check host-check lint package-check scan-benchmark scan-benchmark-fixture test type-check
 
 format:
 	uv run ruff format src tests scripts
@@ -34,6 +34,9 @@ scan-benchmark-fixture:
 scan-benchmark:
 	uv run python -m tests.extraction.scan_benchmark.run --root .dev/benchmarks/scan-project --language "$(SCAN_BENCHMARK_LANGUAGE)" --excluded-pattern 'example_excluded/**'
 
+cache-benchmark:
+	uv run python -m tests.extraction.cache_benchmark.run --root "$(CACHE_BENCHMARK_ROOT)" --language "$(CACHE_BENCHMARK_LANGUAGE)" --cache-directory .dev/benchmarks/cache --incremental-source "$(CACHE_BENCHMARK_SOURCE)" --replacement-source "$(CACHE_BENCHMARK_REPLACEMENT)"
+
 docs-check:
 	uv run python scripts/generate_docs.py --check
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modwire
-Version: 9.0.0
+Version: 9.1.0
 Summary: Code extraction, architecture analysis and the Modwire CLI.
 Author: Tomasz Szpak
 License-Expression: MIT
@@ -48,6 +48,10 @@ Return the available architecture reports.
 
 Analyze a code map with a validated architecture configuration.
 
+### `analyze_cached`
+
+Analyze a code map, reusing reports for an exact map and configuration identity.
+
 ### `discover`
 
 Discover supported source languages beneath a root using the caller's scan policy.
@@ -64,6 +68,18 @@ descendants are deliberately unobserved and are not included in file counts.
 
 Extract source files and return a queryable code map.
 
+### `generate_map_cached`
+
+Return a code map with content-addressed source and complete-manifest reuse.
+
+### `generate_queryable_map_cached`
+
+Return a queryable code map with content-addressed persistent reuse.
+
+### `clear_cache`
+
+Clear only the Modwire-owned directory for one cache namespace.
+
 ### `load_configuration`
 
 Load and validate an architecture configuration from a directory.
@@ -84,6 +100,10 @@ Run the native extractor transport for one supported language.
 
 Run the Modwire command line interface and return its process status.
 
+## `CacheOptions`
+
+Generic persistent-cache settings supplied by a caller.
+
 ## `ScanPolicy`
 
 Caller-owned filesystem traversal policy with explicit exclusions and opt-in symlink following.

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

@@ -20,6 +20,10 @@ Return the available architecture reports.
 
 Analyze a code map with a validated architecture configuration.
 
+### `analyze_cached`
+
+Analyze a code map, reusing reports for an exact map and configuration identity.
+
 ### `discover`
 
 Discover supported source languages beneath a root using the caller's scan policy.
@@ -36,6 +40,18 @@ descendants are deliberately unobserved and are not included in file counts.
 
 Extract source files and return a queryable code map.
 
+### `generate_map_cached`
+
+Return a code map with content-addressed source and complete-manifest reuse.
+
+### `generate_queryable_map_cached`
+
+Return a queryable code map with content-addressed persistent reuse.
+
+### `clear_cache`
+
+Clear only the Modwire-owned directory for one cache namespace.
+
 ### `load_configuration`
 
 Load and validate an architecture configuration from a directory.
@@ -56,6 +72,10 @@ Run the native extractor transport for one supported language.
 
 Run the Modwire command line interface and return its process status.
 
+## `CacheOptions`
+
+Generic persistent-cache settings supplied by a caller.
+
 ## `ScanPolicy`
 
 Caller-owned filesystem traversal policy with explicit exclusions and opt-in symlink following.

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

@@ -10,13 +10,14 @@ from .architecture.config.models.architecture_config import ArchitectureConfig
 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.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__ = ["CodeMap", "ModwireApplication", "QueryableCodeMap", "ScanPolicy"]
+__all__ = ["CacheOptions", "CodeMap", "ModwireApplication", "QueryableCodeMap", "ScanPolicy"]
 
 
 @dataclass(frozen=True)
@@ -56,6 +57,18 @@ class ModwireApplication:
 
         return self.architecture.analyze(code_map, config)
 
+    def analyze_cached(
+        self, code_map: QueryableCodeMap, config: ArchitectureConfig, options: CacheOptions
+    ) -> tuple[ReportNode, ...]:
+        """Analyze a code map, reusing reports for an exact map and configuration identity."""
+
+        cached = self.cli.cached_reports(code_map.code_map, config, options)
+        if cached is not None:
+            return cached
+        reports = self.architecture.analyze(code_map, config)
+        self.cli.store_reports(code_map.code_map, config, reports, options)
+        return reports
+
     def discover(self, root: str, policy: ScanPolicy) -> tuple[str, ...]:
         """Discover supported source languages beneath a root using the caller's scan policy."""
 
@@ -81,6 +94,30 @@ class ModwireApplication:
 
         return QueryableCodeMap(code_map=self.generate_map(language, root, policy))
 
+    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."""
+
+        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
+
+    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))
+
+    def clear_cache(self, options: CacheOptions) -> None:
+        """Clear only the Modwire-owned directory for one cache namespace."""
+
+        self.cli.clear_cache(options)
+
     def load_configuration(self, dot_dir: str) -> ArchitectureConfig:
         """Load and validate an architecture configuration from a directory."""
 
@@ -94,7 +131,7 @@ 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), ScanPolicy), check)
+        return self.cli.generate_documentation(str(readme), (type(self), CacheOptions, ScanPolicy), check)
 
     def run_extractor(self, language: str) -> int:
         """Run the native extractor transport for one supported language."""

modwire-9.1.0/src/modwire/cli/cache/application.py

@@ -0,0 +1,183 @@
+import importlib
+from dataclasses import dataclass
+from typing import Any, cast
+
+from pydantic import BaseModel, ValidationError
+from wireup import injectable
+
+from ...architecture.config.models.architecture_config import ArchitectureConfig
+from ...architecture.report.models.report_node import ReportNode
+from ...extraction.extractors.models.extraction_request import ExtractionRequest
+from ...shared.code.models.code_map import CodeMap
+from ...shared.code.models.duplicate_identity_error import DuplicateIdentityError
+from ...shared.code.models.identity import FileId, ModuleId
+from ...shared.code.models.source_extraction import SourceExtraction
+from ...shared.code.models.source_file import SourceFile
+from ..pipeline.domain import SourceReader
+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.extraction_snapshot import ExtractionSnapshot
+from .services.cache_codec import CacheCodec
+from .services.cache_identity import CacheIdentity
+
+
+@injectable
+@dataclass(frozen=True)
+class CacheApplication:
+    reader: SourceReader
+    storage: CacheStorage
+    identity: CacheIdentity
+    codec: CacheCodec
+
+    def has_source_files(self, request: ExtractionRequest, policy: ScanPolicy) -> bool:
+        return self.reader.has_source_files(request, policy)
+
+    def extract(self, request: ExtractionRequest, policy: ScanPolicy) -> SourceExtraction:
+        self.reader.ensure_available(request.runtime)
+        return self.reader.extract_source(request, policy)
+
+    def extract_cached(
+        self, request: ExtractionRequest, policy: ScanPolicy, options: CacheOptions
+    ) -> 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] = []
+        for entry in inventory.entries:
+            key = keys[entry.source_id]
+            value = self._read(options, key)
+            try:
+                source_file = SourceFile.model_validate(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
+            except (TypeError, ValueError, ValidationError):
+                self.storage.delete(options, key)
+                misses.append(entry.source_id)
+
+        if misses or not inventory.entries:
+            self.reader.ensure_available(request.runtime)
+        extracted = self.reader.extract_entries(request, inventory, tuple(misses))
+        for source_id in misses:
+            source_file = extracted.get(source_id)
+            if source_file is None:
+                raise RuntimeError(f"Extractor omitted a requested source file: {source_id}")
+            files[source_id] = source_file
+            self._write(options, keys[source_id], source_file.model_dump(mode="json"))
+
+        ordered_files = {entry.source_id: files[entry.source_id] for entry in inventory.entries}
+        modules: dict[ModuleId, FileId] = {}
+        for file_id, source_file in ordered_files.items():
+            existing = modules.get(source_file.module_id)
+            if existing is not None:
+                raise DuplicateIdentityError("module", source_file.module_id, existing, file_id)
+            modules[source_file.module_id] = file_id
+
+        extraction = SourceExtraction(
+            files=ordered_files,
+            modules=modules,
+            files_found=inventory.files_found,
+            files_excluded=inventory.files_excluded,
+            directories_pruned=inventory.directories_pruned,
+        )
+        manifest = self.identity.manifest(request, policy, inventory.entries)
+        self._write(
+            options,
+            manifest,
+            {
+                "sources": [
+                    {
+                        "relative_path": entry.relative_path,
+                        "content_digest": entry.content_digest,
+                        "source_key": keys[entry.source_id].digest,
+                    }
+                    for entry in inventory.entries
+                ]
+            },
+        )
+        self.prune(options)
+        return ExtractionSnapshot(extraction=extraction, manifest=manifest)
+
+    def code_map(self, snapshot: ExtractionSnapshot, options: CacheOptions) -> CodeMap | None:
+        key = self.identity.code_map("", snapshot.manifest)
+        value = self._read(options, key)
+        try:
+            return CodeMap.model_validate(value)
+        except (TypeError, ValueError, ValidationError):
+            self.storage.delete(options, key)
+            return None
+
+    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"))
+        self.prune(options)
+
+    def reports(
+        self, code_map: CodeMap, config: ArchitectureConfig, options: CacheOptions
+    ) -> tuple[ReportNode, ...] | None:
+        key = self.identity.reports(code_map, config)
+        value = self._read(options, key)
+        try:
+            if not isinstance(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)))
+        except (AttributeError, ImportError, KeyError, TypeError, ValueError, ValidationError):
+            self.storage.delete(options, key)
+            return None
+
+    def store_reports(
+        self,
+        code_map: CodeMap,
+        config: ArchitectureConfig,
+        reports: tuple[ReportNode, ...],
+        options: CacheOptions,
+    ) -> None:
+        value = [
+            {
+                "model": f"{type(report).__module__}.{type(report).__qualname__}",
+                "payload": report.model_dump(mode="json", exclude_computed_fields=True),
+            }
+            for report in reports
+        ]
+        self._write(options, self.identity.reports(code_map, config), value)
+        self.prune(options)
+
+    def clear(self, options: CacheOptions) -> None:
+        self.storage.clear(options)
+
+    def prune(self, options: CacheOptions) -> None:
+        entries = self.storage.entries(options)
+        total = sum(entry.size for entry in entries)
+        for entry in sorted(entries, key=lambda item: (item.last_access_ns, item.key.kind, item.key.digest)):
+            if total <= options.max_bytes:
+                break
+            self.storage.delete(options, entry.key)
+            total -= entry.size
+
+    def _read(self, options: CacheOptions, key: CacheKey) -> object | None:
+        payload = self.storage.read(options, key)
+        if payload is None:
+            return None
+        value = self.codec.decode(key, payload)
+        if value is None:
+            self.storage.delete(options, key)
+        return value
+
+    def _write(self, options: CacheOptions, key: CacheKey, value: object) -> None:
+        self.storage.write(options, key, self.codec.encode(key, value))
+
+    def _report(self, value: object) -> ReportNode:
+        if not isinstance(value, dict):
+            raise ValueError("Cached report entry must be an object.")
+        entry = cast(dict[str, object], value)
+        model_name = entry["model"]
+        payload = entry["payload"]
+        if not isinstance(model_name, str) or not model_name.startswith("modwire.architecture."):
+            raise ValueError("Cached report model is outside the architecture package.")
+        module_name, _, class_name = model_name.rpartition(".")
+        model: Any = getattr(importlib.import_module(module_name), class_name)
+        if not isinstance(model, type) or not issubclass(model, BaseModel) or not issubclass(model, ReportNode):
+            raise ValueError("Cached report model is not a report node.")
+        return model.model_validate(payload)

modwire-9.1.0/src/modwire/cli/cache/domain.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+
+from .models.cache_entry import CacheEntry
+from .models.cache_key import CacheKey
+from .models.cache_options import CacheOptions
+
+
+class CacheStorage(ABC):
+    @abstractmethod
+    def read(self, options: CacheOptions, key: CacheKey) -> bytes | None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def write(self, options: CacheOptions, key: CacheKey, payload: bytes) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def entries(self, options: CacheOptions) -> tuple[CacheEntry, ...]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, options: CacheOptions, key: CacheKey) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def clear(self, options: CacheOptions) -> None:
+        raise NotImplementedError

modwire-9.1.0/src/modwire/cli/cache/models/cache_entry.py

@@ -0,0 +1,8 @@
+from ....shared.values.models.value_model import ValueModel
+from .cache_key import CacheKey
+
+
+class CacheEntry(ValueModel):
+    key: CacheKey
+    size: int
+    last_access_ns: int

modwire-9.1.0/src/modwire/cli/cache/models/cache_key.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+from ....shared.values.models.value_model import ValueModel
+
+type CacheKind = Literal["source", "manifest", "code-map", "reports"]
+
+
+class CacheKey(ValueModel):
+    schema_version: Literal[1] = 1
+    kind: CacheKind
+    digest: str

modwire-9.1.0/src/modwire/cli/cache/models/cache_options.py

@@ -0,0 +1,25 @@
+from pydantic import field_validator
+
+from ....shared.values.models.value_model import ValueModel
+
+
+class CacheOptions(ValueModel):
+    """Generic persistent-cache settings supplied by a caller."""
+
+    directory: str
+    namespace: str
+    max_bytes: int
+
+    @field_validator("directory", "namespace")
+    @classmethod
+    def _non_empty(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Cache directory and namespace must not be empty.")
+        return value
+
+    @field_validator("max_bytes")
+    @classmethod
+    def _positive_size(cls, value: int) -> int:
+        if value < 1:
+            raise ValueError("Cache max_bytes must be at least one.")
+        return value

modwire-9.1.0/src/modwire/cli/cache/models/extraction_snapshot.py

@@ -0,0 +1,8 @@
+from ....shared.code.models.source_extraction import SourceExtraction
+from ....shared.values.models.value_model import ValueModel
+from .cache_key import CacheKey
+
+
+class ExtractionSnapshot(ValueModel):
+    extraction: SourceExtraction
+    manifest: CacheKey

modwire-9.1.0/src/modwire/cli/cache/models/source_entry.py

@@ -0,0 +1,9 @@
+from ....shared.code.models.identity import FileId
+from ....shared.values.models.value_model import ValueModel
+
+
+class SourceEntry(ValueModel):
+    source_id: FileId
+    relative_path: str
+    content_digest: str
+    path: str

modwire-9.1.0/src/modwire/cli/cache/models/source_inventory.py

@@ -0,0 +1,9 @@
+from ....shared.values.models.value_model import ValueModel
+from .source_entry import SourceEntry
+
+
+class SourceInventory(ValueModel):
+    entries: tuple[SourceEntry, ...]
+    files_found: int
+    files_excluded: int
+    directories_pruned: int

modwire-9.1.0/src/modwire/cli/cache/services/cache_codec.py

@@ -0,0 +1,40 @@
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, cast
+
+from wireup import injectable
+
+from ..models.cache_key import CacheKey
+
+
+@injectable
+@dataclass(frozen=True)
+class CacheCodec:
+    def encode(self, key: CacheKey, value: object) -> bytes:
+        payload = json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode()
+        envelope = {
+            "schema_version": key.schema_version,
+            "key": key.model_dump(mode="json"),
+            "payload_digest": hashlib.sha256(payload).hexdigest(),
+            "payload": value,
+        }
+        return json.dumps(envelope, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode()
+
+    def decode(self, key: CacheKey, payload: bytes) -> object | None:
+        try:
+            parsed: Any = json.loads(payload)
+            if not isinstance(parsed, dict):
+                return None
+            envelope = cast(dict[str, object], parsed)
+            if envelope.get("schema_version") != key.schema_version:
+                return None
+            if envelope.get("key") != key.model_dump(mode="json"):
+                return None
+            value = envelope["payload"]
+            serialized = json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode()
+            if envelope.get("payload_digest") != hashlib.sha256(serialized).hexdigest():
+                return None
+            return value
+        except (KeyError, TypeError, ValueError, UnicodeDecodeError):
+            return None

modwire-9.1.0/src/modwire/cli/cache/services/cache_identity.py

@@ -0,0 +1,106 @@
+import hashlib
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import metadata, resources
+from typing import Any, ClassVar
+
+from wireup import injectable
+
+from ....architecture.config.models.architecture_config import ArchitectureConfig
+from ....extraction.extractors.models.extraction_request import ExtractionRequest
+from ....shared.code.models.code_map import CodeMap
+from ...cache.models.cache_key import CacheKey, CacheKind
+from ...cache.models.source_entry import SourceEntry
+from ...pipeline.models.scan_policy import ScanPolicy
+
+
+@injectable
+@dataclass(frozen=True)
+class CacheIdentity:
+    SOURCE_VERSION: ClassVar[int] = 1
+    MANIFEST_VERSION: ClassVar[int] = 1
+    CODE_MAP_VERSION: ClassVar[int] = 1
+    REPORT_VERSION: ClassVar[int] = 1
+
+    def source(self, request: ExtractionRequest, policy: ScanPolicy, entry: SourceEntry) -> CacheKey:
+        return self._key(
+            "source",
+            {
+                "version": self.SOURCE_VERSION,
+                "package": self._package_version(),
+                "runtime": self._runtime_identity(request),
+                "scan_policy": policy.model_dump(mode="json"),
+                "relative_path": entry.relative_path,
+                "source_id": entry.source_id,
+                "content_digest": entry.content_digest,
+            },
+        )
+
+    def manifest(self, request: ExtractionRequest, policy: ScanPolicy, entries: tuple[SourceEntry, ...]) -> CacheKey:
+        sources = tuple(
+            {
+                "relative_path": entry.relative_path,
+                "content_digest": entry.content_digest,
+                "source_key": self.source(request, policy, entry).digest,
+            }
+            for entry in sorted(entries, key=lambda item: item.relative_path)
+        )
+        return self._key(
+            "manifest",
+            {
+                "version": self.MANIFEST_VERSION,
+                "package": self._package_version(),
+                "runtime": self._runtime_identity(request),
+                "scan_policy": policy.model_dump(mode="json"),
+                "sources": sources,
+            },
+        )
+
+    def code_map(self, language: str, manifest: CacheKey) -> CacheKey:
+        return self._key(
+            "code-map",
+            {
+                "version": self.CODE_MAP_VERSION,
+                "package": self._package_version(),
+                "code_map_schema": CodeMap.schema_version,
+                "language": language,
+                "manifest": manifest.model_dump(mode="json"),
+            },
+        )
+
+    def reports(self, code_map: CodeMap, config: ArchitectureConfig) -> CacheKey:
+        return self._key(
+            "reports",
+            {
+                "version": self.REPORT_VERSION,
+                "package": self._package_version(),
+                "code_map": code_map.model_dump(mode="json"),
+                "configuration": config.model_dump(mode="json"),
+            },
+        )
+
+    def _runtime_identity(self, request: ExtractionRequest) -> dict[str, object]:
+        runtime = request.runtime
+        return {
+            "runtime": runtime.model_dump(mode="json"),
+            "batch": request.batch_config.model_dump(mode="json"),
+            "resource_digest": self._resource_digest(runtime.resource.package, runtime.resource.path),
+        }
+
+    @lru_cache(maxsize=32)
+    def _resource_digest(self, package: str, path: str) -> str:
+        resource = resources.files(package).joinpath(path)
+        return hashlib.sha256(resource.read_bytes()).hexdigest()
+
+    @lru_cache(maxsize=1)
+    def _package_version(self) -> str:
+        try:
+            return metadata.version("modwire")
+        except metadata.PackageNotFoundError:
+            return "0+unknown"
+
+    def _key(self, kind: CacheKind, value: object) -> CacheKey:
+        payload: Any = value
+        serialized = json.dumps(payload, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode()
+        return CacheKey(kind=kind, digest=hashlib.sha256(serialized).hexdigest())