modwire 9.2.1__tar.gz → 9.2.3__tar.gz

{modwire-9.2.1 → modwire-9.2.3}/.dev/modwire.egg-info/SOURCES.txt

@@ -120,10 +120,11 @@ 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/cache_plan.py
+src/modwire/cli/cache/models/cache_stage.py
+src/modwire/cli/cache/models/cache_storage_state.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/models/source_cache_entry.py
 src/modwire/cli/cache/services/__init__.py
 src/modwire/cli/cache/services/cache_codec.py
 src/modwire/cli/cache/services/cache_identity.py
@@ -148,6 +149,8 @@ src/modwire/cli/pipeline/models/extractor_command_input.py
 src/modwire/cli/pipeline/models/extractor_source_input.py
 src/modwire/cli/pipeline/models/report_pipeline_context.py
 src/modwire/cli/pipeline/models/scan_policy.py
+src/modwire/cli/pipeline/models/source_entry.py
+src/modwire/cli/pipeline/models/source_inventory.py
 src/modwire/cli/pipeline/services/__init__.py
 src/modwire/cli/pipeline/services/batch_source_reader.py
 src/modwire/cli/pipeline/services/callables_insight.py
@@ -256,6 +259,7 @@ src/modwire/shared/code/models/source_signature.py
 src/modwire/shared/code/models/source_symbol.py
 src/modwire/shared/code/models/source_type.py
 src/modwire/shared/code/models/source_value.py
+src/modwire/shared/code/models/source_value_scope.py
 src/modwire/shared/code/models/types.py
 src/modwire/shared/code/services/__init__.py
 src/modwire/shared/code/services/glob_path_matcher.py
@@ -288,6 +292,9 @@ tests/architecture/map/__init__.py
 tests/architecture/map/test_02_patterns.py
 tests/architecture/report/__init__.py
 tests/architecture/report/test_02_invariants.py
+tests/architecture/report_benchmark/__init__.py
+tests/architecture/report_benchmark/benchmark_process_timeout.py
+tests/architecture/report_benchmark/run.py
 tests/architecture/shape/__init__.py
 tests/architecture/shape/base_test.py
 tests/architecture/shape/test_01_limits.py

{modwire-9.2.1 → modwire-9.2.3}/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 cache-benchmark 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 report-benchmark scan-benchmark scan-benchmark-fixture test type-check
 
 format:
 	uv run ruff format src tests scripts
@@ -37,6 +37,9 @@ scan-benchmark:
 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)"
 
+report-benchmark:
+	uv run python -m tests.architecture.report_benchmark.run --root "$(REPORT_BENCHMARK_ROOT)" --language "$(REPORT_BENCHMARK_LANGUAGE)" --cache-directory "$(REPORT_BENCHMARK_CACHE)" --cache-namespace "$(REPORT_BENCHMARK_NAMESPACE)"
+
 docs-check:
 	uv run python scripts/generate_docs.py --check
 

{modwire-9.2.1 → modwire-9.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modwire
-Version: 9.2.1
+Version: 9.2.3
 Summary: Code extraction, architecture analysis and the Modwire CLI.
 Author: Tomasz Szpak
 License-Expression: MIT
@@ -120,9 +120,11 @@ Public stages reported by cached Modwire operations.
 
 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.
+Extraction counts describe current source records. An exact code-map hit
+reports its digest-backed manifest sources as extraction hits without loading
+individual source payloads. 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`
 

{modwire-9.2.1 → modwire-9.2.3}/README.md

@@ -92,9 +92,11 @@ Public stages reported by cached Modwire operations.
 
 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.
+Extraction counts describe current source records. An exact code-map hit
+reports its digest-backed manifest sources as extraction hits without loading
+individual source payloads. 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`
 

{modwire-9.2.1 → modwire-9.2.3}/docs/target-language-ownership.md

@@ -16,16 +16,17 @@ Shared code, dependency resolution, architecture analysis, traversal, consumer v
 orchestration must not contain supported-language tables, runtime commands, extension tables, or language-selection
 branches. Callers select a registered extractor explicitly.
 
-## Shared contract version 2
+## Shared contract version 3
 
-The class-level `CodeMap.schema_version` is `2` while the existing serialized envelope remains stable. Callable kinds
-are `function`, `instance_method`, `type_method`, `static_method`,
+The class-level `CodeMap.schema_version` is `3`. Every runtime `SourceValue` declares a language-neutral `module`,
+`local`, or `member` scope. Extractors distinguish variable assignments from constants and keep type aliases and export
+metadata out of runtime values. Callable kinds are `function`, `instance_method`, `type_method`, `static_method`,
 `constructor`, `callable_value`, and `anonymous`. Parameter kinds are `positional`, `variadic_positional`,
 `named_only`, and `variadic_named`.
 
-Version 1 serialized maps used extractor-specific callable and parameter vocabulary. They are not accepted as version
-2 values. Regenerate them from their source with the same registered extractor; persistent reuse does not yet exist,
-so there is no cache migration or silent compatibility alias.
+Version 1 serialized maps used extractor-specific callable and parameter vocabulary, while version 2 values have no
+explicit value scope. Neither is accepted as version 3. Regenerate them from source with the same registered extractor;
+the cache identity includes the code-map schema and invalidates older maps instead of migrating them silently.
 
 ## Adding an extractor
 

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/application.py

@@ -11,7 +11,8 @@ 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.cache_outcome import CacheOutcome
+from .cli.cache.models.cache_stage import CacheStage
 from .cli.cache.models.cached_result import CachedResult
 from .cli.facade import CliFacade
 from .cli.pipeline.models.scan_policy import ScanPolicy
@@ -82,9 +83,11 @@ class ModwireApplication:
 
         cached = self.cli.cached_reports(code_map.code_map, config, options)
         if cached.value is not None:
+            self.cli.maintain_cache(options)
             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)
+        self.cli.maintain_cache(options)
         outcome = cached.outcome(CacheStage.REPORTS).model_copy(update={"computed": 1, "stored": 1})
         return CachedResult(value=reports, outcomes=(outcome,))
 
@@ -124,16 +127,27 @@ class ModwireApplication:
         """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)
+        plan = self.cli.prepare_cache(request, policy)
+        cached = self.cli.cached_code_map(plan, options)
         outcome = cached.outcome(CacheStage.CODE_MAP)
         if cached.value is not None:
             code_map = cached.value
+            extraction_outcomes = (
+                CacheOutcome(
+                    stage=CacheStage.EXTRACTION,
+                    namespace=options.namespace,
+                    hits=len(plan.sources),
+                ),
+            )
         else:
-            code_map = self.extraction.generate_map(language, snapshot.value.extraction)
-            self.cli.store_code_map(snapshot.value, code_map, options)
+            sources = self.cli.cached_sources(request, plan, options)
+            self.cli.maintain_manifest(plan, options)
+            code_map = self.extraction.generate_map(language, sources.value)
+            self.cli.store_code_map(plan, code_map, options)
             outcome = outcome.model_copy(update={"computed": 1, "stored": 1})
-        return CachedResult(value=code_map, outcomes=(*snapshot.outcomes, outcome))
+            extraction_outcomes = sources.outcomes
+        self.cli.maintain_cache(options)
+        return CachedResult(value=code_map, outcomes=(*extraction_outcomes, outcome))
 
     def generate_queryable_map_cached(
         self, language: str, root: str, policy: ScanPolicy, options: CacheOptions

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/architecture/config/models/shape_rules.py

@@ -9,6 +9,7 @@ class ShapeRules(ConfigurationValue):
     max_types_per_file: int = Field(default=-1, ge=-1)
     max_abstract_classes_per_file: int = Field(default=-1, ge=-1)
     max_functions_per_file: int = Field(default=0, ge=-1)
+    max_variables_per_file: int = Field(default=0, ge=-1)
     max_methods_per_class: int = Field(default=-1, ge=-1)
     max_declared_args: int = Field(default=-1, ge=-1)
     max_function_lines: int = Field(default=-1, ge=-1)

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/architecture/shape/services/file_resolver.py

@@ -2,6 +2,8 @@ from dataclasses import dataclass
 
 from wireup import injectable
 
+from ....shared.code.models.identity import FileId
+from ....shared.code.models.source_value_scope import SourceValueScope
 from ...config.models.shape_rules import ShapeRules
 from ..domain import BaseShapeResolver, ShapeResolverInterface
 from ..models.shape_realm_architecture_map import ShapeRealmArchitectureMap
@@ -23,12 +25,16 @@ class FileResolver(ShapeResolverInterface, BaseShapeResolver):
         violations: list[ShapeViolation | None] = []
         code_map = architecture_map.code_map
         for source_id in self.realm_source_ids(architecture_map):
+            source_result = code_map.source_file(FileId(source_id))
+            if source_result is None:
+                raise RuntimeError(f"Shape realm references missing source: {source_id}")
+            source_file = source_result.file
             violations.extend(
                 [
                     self.limit_violation(
                         source_id=source_id,
                         rule_name="max_classes_per_file",
-                        actual=code_map.classes().where_equal(lambda result: result.source_id, source_id).count(),
+                        actual=len(source_file.classes),
                         limit=config.max_classes_per_file,
                         symbol_kind="file",
                         symbol_name="",
@@ -36,7 +42,7 @@ class FileResolver(ShapeResolverInterface, BaseShapeResolver):
                     self.limit_violation(
                         source_id=source_id,
                         rule_name="max_interfaces_per_file",
-                        actual=code_map.interfaces().where_equal(lambda result: result.source_id, source_id).count(),
+                        actual=len(source_file.interfaces),
                         limit=config.max_interfaces_per_file,
                         symbol_kind="file",
                         symbol_name="",
@@ -44,7 +50,7 @@ class FileResolver(ShapeResolverInterface, BaseShapeResolver):
                     self.limit_violation(
                         source_id=source_id,
                         rule_name="max_types_per_file",
-                        actual=code_map.types().where_equal(lambda result: result.source_id, source_id).count(),
+                        actual=len(source_file.types),
                         limit=config.max_types_per_file,
                         symbol_kind="file",
                         symbol_name="",
@@ -52,9 +58,7 @@ class FileResolver(ShapeResolverInterface, BaseShapeResolver):
                     self.limit_violation(
                         source_id=source_id,
                         rule_name="max_abstract_classes_per_file",
-                        actual=code_map.abstract_classes()
-                        .where_equal(lambda result: result.source_id, source_id)
-                        .count(),
+                        actual=len(source_file.abstract_classes),
                         limit=config.max_abstract_classes_per_file,
                         symbol_kind="file",
                         symbol_name="",
@@ -62,11 +66,22 @@ class FileResolver(ShapeResolverInterface, BaseShapeResolver):
                     self.limit_violation(
                         source_id=source_id,
                         rule_name="max_functions_per_file",
-                        actual=code_map.functions().where_equal(lambda result: result.source_id, source_id).count(),
+                        actual=len(source_file.functions),
                         limit=config.max_functions_per_file,
                         symbol_kind="file",
                         symbol_name="",
                     ),
+                    self.limit_violation(
+                        source_id=source_id,
+                        rule_name="max_variables_per_file",
+                        actual=sum(
+                            value.scope == SourceValueScope.MODULE and value.declaration_kind == "assignment"
+                            for value in source_file.values
+                        ),
+                        limit=config.max_variables_per_file,
+                        symbol_kind="file",
+                        symbol_name="",
+                    ),
                 ]
             )
         return tuple(violation for violation in violations if violation is not None)

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/cli/cache/application.py

@@ -18,19 +18,15 @@ 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.cache_outcome import CacheOutcome
+from .models.cache_plan import CachePlan
+from .models.cache_stage import CacheStage
 from .models.cached_result import CachedResult
-from .models.extraction_snapshot import ExtractionSnapshot
+from .models.source_cache_entry import SourceCacheEntry
 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:
@@ -46,41 +42,58 @@ class CacheApplication:
         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]:
+    def prepare(self, request: ExtractionRequest, policy: ScanPolicy) -> CachePlan:
         inventory = self.reader.inventory(request, policy)
-        keys = {entry.source_id: self.identity.source(request, policy, entry) for entry in inventory.entries}
+        sources = tuple(
+            SourceCacheEntry(entry=entry, key=self.identity.source(request, policy, entry))
+            for entry in inventory.entries
+        )
+        return CachePlan(
+            inventory=inventory,
+            sources=sources,
+            manifest=self.identity.manifest(request, policy, sources),
+        )
+
+    def sources(
+        self, request: ExtractionRequest, plan: CachePlan, options: CacheOptions
+    ) -> CachedResult[SourceExtraction]:
+        payloads = self.storage.read_many(options, tuple(source.key for source in plan.sources))
         files: dict[FileId, SourceFile] = {}
         misses: list[FileId] = []
+        invalid_keys: list[CacheKey] = []
         hits = 0
         invalidated = 0
-        for entry in inventory.entries:
-            key = keys[entry.source_id]
-            cached = self._read(options, key)
+        sources_by_id = {source.entry.source_id: source for source in plan.sources}
+        for source, payload in zip(plan.sources, payloads, strict=True):
+            cached_value = self.codec.decode(source.key, payload) if payload is not None else None
+            cached_invalidated = payload is not None and cached_value is None
             try:
-                source_file = SourceFile.model_validate(cached.value)
-                if source_file.file_id != entry.source_id:
+                source_file = SourceFile.model_validate(cached_value)
+                if source_file.file_id != source.entry.source_id:
                     raise ValueError("Cached source identity does not match its key.")
-                files[entry.source_id] = source_file
+                files[source.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 payload is not None:
+                    invalid_keys.append(source.key)
+                invalidated += int(cached_invalidated or cached_value is not None)
+                misses.append(source.entry.source_id)
+        self.storage.delete_many(options, tuple(invalid_keys))
 
-        if misses or not inventory.entries:
+        if misses or not plan.inventory.entries:
             self.reader.ensure_available(request.runtime)
-        extracted = self.reader.extract_entries(request, inventory, tuple(misses))
+        extracted = self.reader.extract_entries(request, plan.inventory, tuple(misses))
+        writes: list[tuple[CacheKey, bytes]] = []
         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"))
+            source = sources_by_id[source_id]
+            writes.append((source.key, self.codec.encode(source.key, source_file.model_dump(mode="json"))))
+        self.storage.write_many(options, tuple(writes))
 
-        ordered_files = {entry.source_id: files[entry.source_id] for entry in inventory.entries}
+        ordered_files = {source.entry.source_id: files[source.entry.source_id] for source in plan.sources}
         modules: dict[ModuleId, FileId] = {}
         for file_id, source_file in ordered_files.items():
             existing = modules.get(source_file.module_id)
@@ -91,28 +104,12 @@ class CacheApplication:
         extraction = SourceExtraction(
             files=ordered_files,
             modules=modules,
-            files_found=inventory.files_found,
-            files_excluded=inventory.files_excluded,
-            directories_pruned=inventory.directories_pruned,
+            files_found=plan.inventory.files_found,
+            files_excluded=plan.inventory.files_excluded,
+            directories_pruned=plan.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),
+            value=extraction,
             outcomes=(
                 CacheOutcome(
                     stage=CacheStage.EXTRACTION,
@@ -126,35 +123,40 @@ class CacheApplication:
             ),
         )
 
-    def code_map(self, snapshot: ExtractionSnapshot, options: CacheOptions) -> CachedResult[CodeMap | None]:
-        key = self.identity.code_map("", snapshot.manifest)
-        cached = self._read(options, key)
+    def maintain_manifest(self, plan: CachePlan, options: CacheOptions) -> bool:
+        expected = plan.manifest_value()
+        payload = self.storage.read(options, plan.manifest)
+        if payload is not None and self.codec.decode(plan.manifest, payload) == expected:
+            return False
+        return self._write(options, plan.manifest, expected)
+
+    def code_map(self, plan: CachePlan, options: CacheOptions) -> CachedResult[CodeMap | None]:
+        key = self.identity.code_map("", plan.manifest)
+        cached_value, cached_invalidated = self._read(options, key)
         try:
-            value = CodeMap.model_validate(cached.value)
+            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:
+            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),
+                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 store_code_map(self, plan: CachePlan, code_map: CodeMap, options: CacheOptions) -> None:
+        self._write(options, self.identity.code_map("", plan.manifest), code_map.model_dump(mode="json"))
 
     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
+        cached_value, cached_invalidated = self._read(options, key)
+        invalidated = cached_invalidated or cached_value is not None
         try:
             if not isinstance(cached_value, list):
                 raise ValueError("Cached reports must be a list.")
@@ -162,7 +164,7 @@ class CacheApplication:
             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:
+            if cached_value is not None and not cached_invalidated:
                 self.storage.delete(options, key)
             value = None
             outcome = CacheOutcome(
@@ -188,32 +190,25 @@ class CacheApplication:
             for report in reports
         ]
         self._write(options, self.identity.reports(code_map, config), value)
-        self.prune(options)
+
+    def maintain(self, options: CacheOptions) -> bool:
+        return self.storage.enforce_capacity(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:
+    def _read(self, options: CacheOptions, key: CacheKey) -> tuple[object | None, bool]:
         payload = self.storage.read(options, key)
         if payload is None:
-            return _CacheRead(value=None, invalidated=False)
+            return None, 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)
+            return None, True
+        return value, False
 
-    def _write(self, options: CacheOptions, key: CacheKey, value: object) -> None:
-        self.storage.write(options, key, self.codec.encode(key, value))
+    def _write(self, options: CacheOptions, key: CacheKey, value: object) -> bool:
+        return self.storage.write(options, key, self.codec.encode(key, value))
 
     def _report(self, value: object) -> ReportNode:
         if not isinstance(value, dict):

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/cli/cache/domain.py

@@ -1,6 +1,5 @@
 from abc import ABC, abstractmethod
 
-from .models.cache_entry import CacheEntry
 from .models.cache_key import CacheKey
 from .models.cache_options import CacheOptions
 
@@ -11,17 +10,29 @@ class CacheStorage(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def write(self, options: CacheOptions, key: CacheKey, payload: bytes) -> None:
+    def read_many(self, options: CacheOptions, keys: tuple[CacheKey, ...]) -> tuple[bytes | None, ...]:
         raise NotImplementedError
 
     @abstractmethod
-    def entries(self, options: CacheOptions) -> tuple[CacheEntry, ...]:
+    def write(self, options: CacheOptions, key: CacheKey, payload: bytes) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def write_many(self, options: CacheOptions, payloads: tuple[tuple[CacheKey, bytes], ...]) -> tuple[CacheKey, ...]:
         raise NotImplementedError
 
     @abstractmethod
     def delete(self, options: CacheOptions, key: CacheKey) -> None:
         raise NotImplementedError
 
+    @abstractmethod
+    def delete_many(self, options: CacheOptions, keys: tuple[CacheKey, ...]) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def enforce_capacity(self, options: CacheOptions) -> bool:
+        raise NotImplementedError
+
     @abstractmethod
     def clear(self, options: CacheOptions) -> None:
         raise NotImplementedError

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/cli/cache/models/cache_outcome.py

@@ -1,24 +1,17 @@
-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"
+from .cache_stage import CacheStage
 
 
 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.
+    Extraction counts describe current source records. An exact code-map hit
+    reports its digest-backed manifest sources as extraction hits without loading
+    individual source payloads. 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

modwire-9.2.3/src/modwire/cli/cache/models/cache_plan.py

@@ -0,0 +1,22 @@
+from ....shared.values.models.value_model import ValueModel
+from ...pipeline.models.source_inventory import SourceInventory
+from .cache_key import CacheKey
+from .source_cache_entry import SourceCacheEntry
+
+
+class CachePlan(ValueModel):
+    inventory: SourceInventory
+    sources: tuple[SourceCacheEntry, ...]
+    manifest: CacheKey
+
+    def manifest_value(self) -> dict[str, object]:
+        return {
+            "sources": [
+                {
+                    "relative_path": source.entry.relative_path,
+                    "content_digest": source.entry.content_digest,
+                    "source_key": source.key.digest,
+                }
+                for source in sorted(self.sources, key=lambda item: item.entry.relative_path)
+            ]
+        }

modwire-9.2.3/src/modwire/cli/cache/models/cache_stage.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+
+class CacheStage(StrEnum):
+    """Public stages reported by cached Modwire operations."""
+
+    EXTRACTION = "extraction"
+    CODE_MAP = "code-map"
+    REPORTS = "reports"

modwire-9.2.3/src/modwire/cli/cache/models/cache_storage_state.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ....shared.values.models.value_model import ValueModel
+
+
+class CacheStorageState(ValueModel):
+    schema_version: Literal[1] = 1
+    total_bytes: int = Field(ge=0)
+    entry_count: int = Field(ge=0)

{modwire-9.2.1 → modwire-9.2.3}/src/modwire/cli/cache/models/cached_result.py

@@ -1,7 +1,8 @@
 from pydantic import field_validator
 
 from ....shared.values.models.value_model import ValueModel
-from .cache_outcome import CacheOutcome, CacheStage
+from .cache_outcome import CacheOutcome
+from .cache_stage import CacheStage
 
 
 class CachedResult[Result](ValueModel):

modwire-9.2.3/src/modwire/cli/cache/models/source_cache_entry.py

@@ -0,0 +1,8 @@
+from ....shared.values.models.value_model import ValueModel
+from ...pipeline.models.source_entry import SourceEntry
+from .cache_key import CacheKey
+
+
+class SourceCacheEntry(ValueModel):
+    entry: SourceEntry
+    key: CacheKey