modwire 9.0.0__tar.gz → 9.2.0__tar.gz

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

@@ -112,6 +112,22 @@ 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/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
+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 +269,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 +318,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.2.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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modwire
-Version: 9.0.0
+Version: 9.2.0
 Summary: Code extraction, architecture analysis and the Modwire CLI.
 Author: Tomasz Szpak
 License-Expression: MIT
@@ -48,6 +48,14 @@ 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.
+
+### `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.
@@ -64,6 +72,26 @@ 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_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.
+
 ### `load_configuration`
 
 Load and validate an architecture configuration from a directory.
@@ -84,6 +112,30 @@ 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.
+
 ## `ScanPolicy`
 
 Caller-owned filesystem traversal policy with explicit exclusions and opt-in symlink following.

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

@@ -20,6 +20,14 @@ 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.
+
+### `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.
@@ -36,6 +44,26 @@ 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_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.
+
 ### `load_configuration`
 
 Load and validate an architecture configuration from a directory.
@@ -56,6 +84,30 @@ 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.
+
 ## `ScanPolicy`
 
 Caller-owned filesystem traversal policy with explicit exclusions and opt-in symlink following.

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

@@ -10,13 +10,25 @@ 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.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__ = ["CodeMap", "ModwireApplication", "QueryableCodeMap", "ScanPolicy"]
+__all__ = [
+    "CacheOptions",
+    "CacheOutcome",
+    "CacheStage",
+    "CachedResult",
+    "CodeMap",
+    "ModwireApplication",
+    "QueryableCodeMap",
+    "ScanPolicy",
+]
 
 
 @dataclass(frozen=True)
@@ -56,6 +68,26 @@ 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."""
+
+        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.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)
+        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."""
 
@@ -81,6 +113,48 @@ 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."""
+
+        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.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 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."""
+
+        self.cli.clear_cache(options)
+
     def load_configuration(self, dot_dir: str) -> ArchitectureConfig:
         """Load and validate an architecture configuration from a directory."""
 
@@ -94,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), 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.2.0/src/modwire/cli/cache/application.py

@@ -0,0 +1,230 @@
+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.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:
+    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
+    ) -> 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]
+            cached = self._read(options, key)
+            try:
+                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):
+                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:
+            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 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) -> CachedResult[CodeMap | None]:
+        key = self.identity.code_map("", snapshot.manifest)
+        cached = self._read(options, key)
+        try:
+            value = CodeMap.model_validate(cached.value)
+            outcome = CacheOutcome(stage=CacheStage.CODE_MAP, namespace=options.namespace, hits=1)
+        except (TypeError, ValueError, ValidationError):
+            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"))
+        self.prune(options)
+
+    def reports(
+        self, code_map: CodeMap, config: ArchitectureConfig, options: CacheOptions
+    ) -> CachedResult[tuple[ReportNode, ...] | None]:
+        key = self.identity.reports(code_map, config)
+        cached = self._read(options, key)
+        cached_value: object | None = cached.value
+        invalidated = cached.invalidated or cached_value is not None
+        try:
+            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], 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):
+            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,
+        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) -> _CacheRead:
+        payload = self.storage.read(options, key)
+        if payload is None:
+            return _CacheRead(value=None, invalidated=False)
+        value = self.codec.decode(key, payload)
+        if value is None:
+            self.storage.delete(options, key)
+            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))
+
+    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.2.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.2.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.2.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.2.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.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