fix(acms): align SkeletonCompressorService.compress() with SkeletonCompressor protocol

- Updated SkeletonCompressorService.compress() to accept
  (fragments: tuple[ContextFragment, ...], skeleton_budget: int)
  -> tuple[ContextFragment, ...], matching the SkeletonCompressor protocol
- Removed skeleton_ratio and CompressionResult from the public API
- Added @runtime_checkable to SkeletonCompressor protocol in acms_service.py
- Added structural subtype assertion at module level to prevent future
  protocol drift
- Rewrote all Behave feature scenarios and step definitions to use
  skeleton_budget
- Updated benchmarks and robot helpers to use absolute token budgets
- Removed CompressionResult export from services __init__.py and
  vulture_whitelist.py
- The depth_breadth_projection.py call site already correctly computed
  and passed skeleton_budget

ISSUES CLOSED: #2925

benchmarks/skeleton_compressor_bench.py

@@ -1,8 +1,13 @@
 """ASV benchmarks for skeleton compressor overhead.
 
-Measures the time to compress context fragments at various ratios
+Measures the time to compress context fragments at various budgets
 and fragment counts.  The benchmark covers the hot path that runs
 during subplan context inheritance.
+
+The caller is responsible for converting a skeleton_ratio to an
+absolute skeleton_budget before invoking compress().  These benchmarks
+use representative absolute token budgets derived from typical ratios
+applied to the fragment set sizes.
 """
 
 from __future__ import annotations
@@ -33,9 +38,9 @@ from cleveragents.domain.models.core.context_fragment import (  # noqa: E402
 _SKEL_PROV = FragmentProvenance(resource_uri="bench-skeleton://default")
 
 
-def _build_fragments(count: int, tokens_each: int = 100) -> list[ContextFragment]:
+def _build_fragments(count: int, tokens_each: int = 100) -> tuple[ContextFragment, ...]:
     """Generate *count* fragments for benchmarking."""
-    return [
+    return tuple(
         ContextFragment(
             fragment_id=f"bench-{i:05d}",
             uko_node=f"bench-skeleton://file/{i}",
@@ -48,60 +53,60 @@ def _build_fragments(count: int, tokens_each: int = 100) -> list[ContextFragment
             ),
         )
         for i in range(count)
-    ]
+    )
 
 
 class SkeletonCompressorSmallSuite:
-    """Benchmark compression of a small fragment set (10 fragments)."""
+    """Benchmark compression of a small fragment set (10 fragments, 1000 tokens)."""
 
     def setup(self) -> None:
         self._svc = SkeletonCompressorService()
-        self._fragments = _build_fragments(10)
+        self._fragments = _build_fragments(10)  # 1000 total tokens
 
-    def time_compress_ratio_0(self) -> None:
-        """No compression (pass-through)."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.0)
+    def time_compress_budget_full(self) -> None:
+        """No compression (pass-through) — budget equals total tokens."""
+        self._svc.compress(self._fragments, 1000)
 
-    def time_compress_ratio_03(self) -> None:
-        """Default ratio compression."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.3)
+    def time_compress_budget_70pct(self) -> None:
+        """Default-ratio-equivalent compression (budget = 70% of total)."""
+        self._svc.compress(self._fragments, 700)
 
-    def time_compress_ratio_05(self) -> None:
-        """Moderate compression."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.5)
+    def time_compress_budget_50pct(self) -> None:
+        """Moderate compression (budget = 50% of total)."""
+        self._svc.compress(self._fragments, 500)
 
-    def time_compress_ratio_1(self) -> None:
-        """Maximum compression."""
-        self._svc.compress(self._fragments, skeleton_ratio=1.0)
+    def time_compress_budget_zero(self) -> None:
+        """Maximum compression — empty result."""
+        self._svc.compress(self._fragments, 0)
 
 
 class SkeletonCompressorMediumSuite:
-    """Benchmark compression of a medium fragment set (100 fragments)."""
+    """Benchmark compression of a medium fragment set (100 fragments, 10000 tokens)."""
 
     def setup(self) -> None:
         self._svc = SkeletonCompressorService()
-        self._fragments = _build_fragments(100)
+        self._fragments = _build_fragments(100)  # 10000 total tokens
 
-    def time_compress_ratio_03(self) -> None:
-        """Default ratio compression."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.3)
+    def time_compress_budget_70pct(self) -> None:
+        """Default-ratio-equivalent compression."""
+        self._svc.compress(self._fragments, 7000)
 
-    def time_compress_ratio_05(self) -> None:
+    def time_compress_budget_50pct(self) -> None:
         """Moderate compression."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.5)
+        self._svc.compress(self._fragments, 5000)
 
 
 class SkeletonCompressorLargeSuite:
-    """Benchmark compression of a large fragment set (1000 fragments)."""
+    """Benchmark compression of a large fragment set (1000 fragments, 100000 tokens)."""
 
     def setup(self) -> None:
         self._svc = SkeletonCompressorService()
-        self._fragments = _build_fragments(1000)
+        self._fragments = _build_fragments(1000)  # 100000 total tokens
 
-    def time_compress_ratio_05(self) -> None:
+    def time_compress_budget_50pct(self) -> None:
         """Moderate compression over 1000 fragments."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.5)
+        self._svc.compress(self._fragments, 50000)
 
-    def time_compress_ratio_08(self) -> None:
+    def time_compress_budget_20pct(self) -> None:
         """Heavy compression over 1000 fragments."""
-        self._svc.compress(self._fragments, skeleton_ratio=0.8)
+        self._svc.compress(self._fragments, 20000)