generic-ml-cache-core 0.2.0__py3-none-any.whl

generic_ml_cache_core/application/port/out/execution_repository_port.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ExecutionRepositoryPort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+
+
+class ExecutionRepositoryPort(ABC):
+    """Outbound port for the structured execution record — the "database".
+
+    It stores and returns *dehydrated* executions (structure + artifact
+    references, no bytes); the use case hydrates output from the blob store.
+    Executions are append-only: a call identity (one key) accumulates many
+    executions over time, each one a real client call.
+    """
+
+    @abstractmethod
+    def find_current(self, execution_key: str) -> Optional[MlExecution]:
+        """Return the current cached answer for ``execution_key`` — the success
+        that is still authoritative (state SUCCESS, not superseded, output
+        persisted) — or None if there is no servable execution."""
+
+    @abstractmethod
+    def find_all(self, execution_key: str) -> List[MlExecution]:
+        """Return every execution recorded for ``execution_key``, in the order
+        they were saved (current, stale, and failed alike). Empty if none.
+
+        This is the append-only history: its length is the number of real client
+        calls made for this identity."""
+
+    @abstractmethod
+    def save(self, execution: MlExecution) -> None:
+        """Append a new execution. If it is a servable success, atomically
+        supersede the prior current execution for the same key — the supersession
+        happens here, where atomicity belongs, never in the caller."""

generic_ml_cache_core/application/port/out/file_fingerprint_port.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""FileFingerprintPort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class FileFingerprintPort(ABC):
+    """Outbound port for fingerprinting a declared input file at the edge.
+
+    The adapter reads the file and applies the imported core rule, returning
+    ONLY the checksum. The file content never crosses back into the use case
+    or the domain — the engine fingerprints a file without ever holding its
+    content. The rule is owned by the core (common/checksum), never by the
+    adapter, so two adapters can never derive different keys for the same file.
+    """
+
+    @abstractmethod
+    def fingerprint(self, path: str) -> str:
+        """Return the content fingerprint of the file at ``path``.
+
+        Raises if the path does not point to a readable regular file.
+        """

generic_ml_cache_core/application/port/out/metrics_port.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""MetricsPort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict, Optional
+
+
+class MetricsPort(ABC):
+    """Outbound port for the call journal: append events, query projections.
+
+    Non-load-bearing by contract: record_event must never raise, because
+    observability must never break an execution. Implementations swallow
+    their own errors at the adapter level.
+
+    Events are the source of truth. hit_counts_by_key, event_counts, and
+    last_access are projections over the journal, not stored truths.
+    """
+
+    @abstractmethod
+    def record_event(
+        self,
+        event: str,
+        *,
+        execution_key: Optional[str],
+        client: str,
+        model: str,
+        effort: str,
+    ) -> None:
+        """Append one journal event. Must never raise."""
+
+    @abstractmethod
+    def hit_counts_by_key(self) -> Dict[str, int]:
+        """Return {execution_key: hit_count} across all HIT events.
+
+        An empty dict is the correct response when no data is available.
+        """
+
+    @abstractmethod
+    def event_counts(self) -> Dict[str, int]:
+        """Return {event_name: count} across all recorded events.
+
+        An empty dict is the correct response when no data is available.
+        """
+
+    @abstractmethod
+    def last_access(self) -> Dict[str, float]:
+        """Return {execution_key: epoch_seconds} of the latest event per key.
+
+        Used for LRU eviction ordering. An empty dict is the correct response
+        when no data is available.
+        """

generic_ml_cache_core/application/port/out/passthrough_runner_port.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""PassthroughRunnerPort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+
+
+class PassthroughRunnerPort(ABC):
+    """Outbound port for a passthrough (alias) client launch.
+
+    Distinct from the managed ClientRunnerPort: the args are opaque (gmlcache
+    forwards the native tail verbatim), there is no isolated folder and no file
+    capture, and the client runs where the caller invoked it. The returned
+    ClientRunResult therefore carries stdout/stderr/exit but an empty file list.
+    """
+
+    @abstractmethod
+    def run(self, client: str, native_args: List[str]) -> ClientRunResult:
+        """Launch ``client`` with the verbatim ``native_args`` and return the raw
+        result. Raises on unrecoverable launch failure."""

generic_ml_cache_core/application/usecase/__init__.py

@@ -0,0 +1 @@
+"""Hexagonal layer package."""

generic_ml_cache_core/application/usecase/cached_ml_execution_service.py

@@ -0,0 +1,198 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""CachedMlExecutionService: the shared record-or-replay orchestration."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import replace
+from typing import List, Optional, Protocol, Tuple
+
+from generic_ml_cache_core.application.domain.model.execution.artifact import Artifact, ArtifactType
+from generic_ml_cache_core.application.domain.model.run.cache_mode import CacheMode
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+from generic_ml_cache_core.application.port.out.blob_store_port import BlobStorePort
+from generic_ml_cache_core.application.port.out.execution_repository_port import (
+    ExecutionRepositoryPort,
+)
+from generic_ml_cache_core.application.port.out.metrics_port import MetricsPort
+from generic_ml_cache_core.application.usecase import journal_events
+from generic_ml_cache_core.common.checksum import file_content_fingerprint
+from generic_ml_cache_core.common.errors import ArtifactBlobMissing, CacheMiss
+
+_TEXT_ENCODING = "utf-8"
+
+
+class CacheableExecutionCommand(Protocol):
+    """What the shared flow needs of any execution command: a cache mode and a
+    persistence policy. The kind-specific fields are read through hooks."""
+
+    cache_mode: CacheMode
+
+    def should_persist(self, succeeded: bool) -> bool: ...
+
+
+class CachedMlExecutionService(ABC):
+    """The record-or-replay flow shared by every kind of cached ML execution.
+
+    It owns the cache resolution (offline/cache/refresh), content-addressed
+    artifact storage, hydration on a hit, and journaling. Each concrete kind
+    supplies only what differs through the hooks below — how to build its
+    identity, how to run its client, its kind, and (optionally) whether a given
+    command is cacheable. This is where "what happens in what order" lives; the
+    kind-specific I/O lives in the subclass.
+    """
+
+    def __init__(
+        self, blob_store: BlobStorePort, repository: ExecutionRepositoryPort, metrics: MetricsPort
+    ) -> None:
+        self._blob_store = blob_store
+        self._repository = repository
+        self._metrics = metrics
+
+    def execute(self, command: CacheableExecutionCommand) -> MlExecution:
+        call_identity = self._build_identity(command)
+        execution_key = call_identity.generate_key()
+
+        if self._is_uncacheable(command):
+            return self._run_uncacheable(command, call_identity, execution_key)
+
+        if command.cache_mode is CacheMode.OFFLINE:
+            return self._serve_offline(command, execution_key)
+
+        if command.cache_mode is CacheMode.CACHE:
+            current_execution = self._repository.find_current(execution_key)
+            if current_execution is not None:
+                return self._serve_hit(command, execution_key, current_execution)
+
+        return self._run_fresh(command, call_identity, execution_key, allow_store=True)
+
+    # -- kind-specific hooks ----------------------------------------------
+
+    @abstractmethod
+    def _build_identity(self, command: CacheableExecutionCommand) -> CallIdentity:
+        """Build the call identity (and thus the key) for this command."""
+
+    @abstractmethod
+    def _run_client(self, command: CacheableExecutionCommand) -> ClientRunResult:
+        """Run the client for this command and return its raw result."""
+
+    @abstractmethod
+    def _execution_kind(self) -> ExecutionKind:
+        """The kind every execution this service produces is tagged with."""
+
+    @abstractmethod
+    def _journal_fields(self, command: CacheableExecutionCommand) -> Tuple[str, str, str]:
+        """The (client, model, effort) a journal event records for this command;
+        a kind without a model/effort returns empty strings for them."""
+
+    def _is_uncacheable(self, command: CacheableExecutionCommand) -> bool:
+        """Whether this command cannot be cached. Default: always cacheable."""
+        return False
+
+    # -- resolution paths -------------------------------------------------
+
+    def _serve_offline(self, command: CacheableExecutionCommand, execution_key: str) -> MlExecution:
+        current_execution = self._repository.find_current(execution_key)
+        if current_execution is None:
+            self._record_event(journal_events.MISS, execution_key, command)
+            raise CacheMiss(f"offline miss: no stored execution for key {execution_key}")
+        return self._serve_hit(command, execution_key, current_execution)
+
+    def _serve_hit(
+        self, command: CacheableExecutionCommand, execution_key: str, current_execution: MlExecution
+    ) -> MlExecution:
+        hydrated_execution = self._hydrate(current_execution)
+        self._record_event(journal_events.HIT, execution_key, command)
+        return hydrated_execution
+
+    def _run_uncacheable(
+        self, command: CacheableExecutionCommand, call_identity: CallIdentity, execution_key: str
+    ) -> MlExecution:
+        if command.cache_mode is CacheMode.OFFLINE:
+            self._record_event(journal_events.MISS, execution_key, command)
+            raise CacheMiss("offline: this call is not cacheable, so it cannot be served offline")
+        return self._run_fresh(command, call_identity, execution_key, allow_store=False)
+
+    def _run_fresh(
+        self,
+        command: CacheableExecutionCommand,
+        call_identity: CallIdentity,
+        execution_key: str,
+        allow_store: bool,
+    ) -> MlExecution:
+        client_run_result = self._run_client(command)
+        should_store = allow_store and command.should_persist(client_run_result.succeeded)
+        artifacts = self._build_artifacts(client_run_result, store=should_store)
+        execution = MlExecution(
+            call_identity=call_identity,
+            execution_state=client_run_result.outcome(),
+            execution_kind=self._execution_kind(),
+            output_persisted=should_store,
+            artifacts=artifacts,
+            token_usage=client_run_result.token_usage,
+            failure=client_run_result.failure(),
+        )
+        if should_store:
+            self._repository.save(execution)
+            self._record_event(journal_events.RECORD, execution_key, command)
+        else:
+            self._record_event(journal_events.RUN, execution_key, command)
+        return execution
+
+    # -- artifacts --------------------------------------------------------
+
+    def _build_artifacts(self, client_run_result: ClientRunResult, store: bool) -> List[Artifact]:
+        artifacts = [
+            self._store_artifact(
+                ArtifactType.STDOUT, None, client_run_result.stdout.encode(_TEXT_ENCODING), store
+            ),
+            self._store_artifact(
+                ArtifactType.STDERR, None, client_run_result.stderr.encode(_TEXT_ENCODING), store
+            ),
+        ]
+        for generated_file in client_run_result.files:
+            artifacts.append(
+                self._store_artifact(
+                    ArtifactType.OUTPUT_FILE, generated_file.name, generated_file.content, store
+                )
+            )
+        return artifacts
+
+    def _store_artifact(
+        self,
+        artifact_type: ArtifactType,
+        artifact_name: Optional[str],
+        content_bytes: bytes,
+        store: bool,
+    ) -> Artifact:
+        blob_key = file_content_fingerprint(content_bytes)
+        if store:
+            self._blob_store.put(blob_key, content_bytes)
+        return Artifact.from_content(artifact_type, blob_key, content_bytes, name=artifact_name)
+
+    def _hydrate(self, execution: MlExecution) -> MlExecution:
+        hydrated_artifacts = [self._hydrate_artifact(artifact) for artifact in execution.artifacts]
+        return replace(execution, artifacts=hydrated_artifacts)
+
+    def _hydrate_artifact(self, artifact: Artifact) -> Artifact:
+        content_bytes = self._blob_store.get(artifact.blob_key)
+        if content_bytes is None:
+            raise ArtifactBlobMissing(
+                f"blob {artifact.blob_key} for a {artifact.artifact_type.value} "
+                "artifact is missing from the blob store"
+            )
+        return replace(artifact, content=content_bytes)
+
+    # -- journal ----------------------------------------------------------
+
+    def _record_event(
+        self, event: str, execution_key: str, command: CacheableExecutionCommand
+    ) -> None:
+        client, model, effort = self._journal_fields(command)
+        self._metrics.record_event(
+            event, execution_key=execution_key, client=client, model=model, effort=effort
+        )

generic_ml_cache_core/application/usecase/call_identity_building.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Shared construction of a CallIdentity from a command's keyed inputs.
+
+A probe and a run must derive byte-for-byte the same key, so the fingerprinting
+and assembly live here, once, and both services call it. The Protocol is the
+function's parameter type and stays beside it (one cohesive unit).
+"""
+
+from __future__ import annotations
+
+from typing import List, Protocol
+
+from generic_ml_cache_core.application.domain.model.identity.managed_call_identity import (
+    ManagedCallIdentity,
+)
+from generic_ml_cache_core.application.port.out.file_fingerprint_port import FileFingerprintPort
+from generic_ml_cache_core.common.checksum import fingerprint_arguments, text_checksum
+
+
+class KeyedCallInputs(Protocol):
+    """The raw, key-determining fields any command must expose to be keyed.
+
+    Allow-paths and scan-trust are *not* here — they decide cacheability, not the
+    key (see ``domain/service/cacheability.py``).
+    """
+
+    client: str
+    model: str
+    effort: str
+    context: str
+    prompt: str
+    input_file_paths: List[str]
+    client_args: List[str]
+    grants: List[str]
+
+
+def build_call_identity(
+    file_fingerprint: FileFingerprintPort, keyed_inputs: KeyedCallInputs
+) -> ManagedCallIdentity:
+    """Fingerprint the keyed inputs (files at the edge, text in place) and assemble
+    the managed identity. The file content never enters the engine — only
+    checksums."""
+    input_file_fingerprints = {
+        input_file_path: file_fingerprint.fingerprint(input_file_path)
+        for input_file_path in keyed_inputs.input_file_paths
+    }
+    client_args_fingerprint = (
+        fingerprint_arguments(keyed_inputs.client_args) if keyed_inputs.client_args else None
+    )
+    return ManagedCallIdentity(
+        client=keyed_inputs.client,
+        model=keyed_inputs.model,
+        effort=keyed_inputs.effort,
+        context_fingerprint=text_checksum(keyed_inputs.context),
+        prompt_fingerprint=text_checksum(keyed_inputs.prompt),
+        input_file_fingerprints=input_file_fingerprints,
+        client_args_fingerprint=client_args_fingerprint,
+        grants=frozenset(keyed_inputs.grants),
+    )

generic_ml_cache_core/application/usecase/journal_events.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Journal event names recorded through the MetricsPort.
+
+The shared vocabulary every use case logs against. Caching and metrics are
+independent concerns: every resolution emits exactly one event, including the
+ones that store nothing — so even a non-cached run is surfaced.
+"""
+
+from __future__ import annotations
+
+#: served from an existing stored execution (a replay)
+HIT = "hit"
+#: a fresh real call was made and stored
+RECORD = "record"
+#: wanted the cache but found nothing servable (an offline miss)
+MISS = "miss"
+#: a fresh real call ran but was not stored (uncacheable, or a non-persisted/failed run)
+RUN = "run"

generic_ml_cache_core/application/usecase/probe_service.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ProbeService."""
+
+from __future__ import annotations
+
+from generic_ml_cache_core.application.domain.model.probe.probe_report import ProbeReport
+from generic_ml_cache_core.application.domain.model.probe.probe_status import ProbeStatus
+from generic_ml_cache_core.application.port.inbound.probe_command import ProbeCommand
+from generic_ml_cache_core.application.port.inbound.probe_use_case import ProbeUseCase
+from generic_ml_cache_core.application.port.out.execution_repository_port import (
+    ExecutionRepositoryPort,
+)
+from generic_ml_cache_core.application.port.out.file_fingerprint_port import FileFingerprintPort
+from generic_ml_cache_core.application.usecase.call_identity_building import build_call_identity
+
+
+class ProbeService(ProbeUseCase):
+    """Forecast whether a call is cached, without running or recording anything.
+
+    It reuses the shared key-building and cacheability rule, so the verdict and the
+    key are byte-for-byte what a run would derive — a probe and a run can never
+    disagree. It launches no client, writes no blob, and records no journal event.
+    """
+
+    def __init__(
+        self, file_fingerprint: FileFingerprintPort, repository: ExecutionRepositoryPort
+    ) -> None:
+        self._file_fingerprint = file_fingerprint
+        self._repository = repository
+
+    def execute(self, command: ProbeCommand) -> ProbeReport:
+        call_identity = build_call_identity(self._file_fingerprint, command)
+        execution_key = call_identity.generate_key()
+
+        if command.is_uncacheable:
+            return ProbeReport(status=ProbeStatus.NON_CACHEABLE, execution_key=execution_key)
+
+        current_execution = self._repository.find_current(execution_key)
+        if current_execution is None:
+            return ProbeReport(status=ProbeStatus.MISS, execution_key=execution_key)
+        return ProbeReport(
+            status=ProbeStatus.HIT, execution_key=execution_key, execution=current_execution
+        )

generic_ml_cache_core/application/usecase/run_api_execution_service.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunApiExecutionService."""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+from generic_ml_cache_core.application.domain.model.identity.api_call_identity import (
+    ApiCallIdentity,
+)
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.domain.service.message_fingerprinting import (
+    fingerprint_messages,
+)
+from generic_ml_cache_core.application.port.inbound.run_api_execution_command import (
+    RunApiExecutionCommand,
+)
+from generic_ml_cache_core.application.port.inbound.run_api_execution_use_case import (
+    RunApiExecutionUseCase,
+)
+from generic_ml_cache_core.application.port.out.api_client_port import ApiClientPort
+from generic_ml_cache_core.application.port.out.blob_store_port import BlobStorePort
+from generic_ml_cache_core.application.port.out.execution_repository_port import (
+    ExecutionRepositoryPort,
+)
+from generic_ml_cache_core.application.port.out.metrics_port import MetricsPort
+from generic_ml_cache_core.application.usecase.cached_ml_execution_service import (
+    CachedMlExecutionService,
+)
+
+
+class RunApiExecutionService(CachedMlExecutionService, RunApiExecutionUseCase):
+    """Record-or-replay a direct ML provider API call.
+
+    Implements the inbound port over the shared cached-execution flow, supplying
+    the API specifics: the identity is the provider, model, and a fingerprint of
+    the message list; the call goes through the API client port (no subprocess,
+    no files); and executions are tagged API. An API call is always cacheable.
+    """
+
+    def __init__(
+        self,
+        api_client: ApiClientPort,
+        blob_store: BlobStorePort,
+        repository: ExecutionRepositoryPort,
+        metrics: MetricsPort,
+    ) -> None:
+        super().__init__(blob_store, repository, metrics)
+        self._api_client = api_client
+
+    def _build_identity(self, command: RunApiExecutionCommand) -> CallIdentity:
+        return ApiCallIdentity(
+            provider=command.provider,
+            model=command.model,
+            messages_fingerprint=fingerprint_messages(command.messages),
+        )
+
+    def _run_client(self, command: RunApiExecutionCommand) -> ClientRunResult:
+        return self._api_client.run(command.provider, command.model, command.messages)
+
+    def _execution_kind(self) -> ExecutionKind:
+        return ExecutionKind.API
+
+    def _journal_fields(self, command: RunApiExecutionCommand) -> Tuple[str, str, str]:
+        # The provider plays the role of "client" in the journal; no effort concept.
+        return command.provider, command.model, ""

generic_ml_cache_core/application/usecase/run_managed_local_execution_service.py

@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunManagedLocalExecutionService."""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+from generic_ml_cache_core.application.domain.model.identity.call_identity import CallIdentity
+from generic_ml_cache_core.application.domain.model.run.client_run_request import ClientRunRequest
+from generic_ml_cache_core.application.domain.model.run.client_run_result import ClientRunResult
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.port.inbound.run_managed_local_execution_command import (
+    RunManagedLocalExecutionCommand,
+)
+from generic_ml_cache_core.application.port.inbound.run_managed_local_execution_use_case import (
+    RunManagedLocalExecutionUseCase,
+)
+from generic_ml_cache_core.application.port.out.blob_store_port import BlobStorePort
+from generic_ml_cache_core.application.port.out.client_runner_port import ClientRunnerPort
+from generic_ml_cache_core.application.port.out.execution_repository_port import (
+    ExecutionRepositoryPort,
+)
+from generic_ml_cache_core.application.port.out.file_fingerprint_port import FileFingerprintPort
+from generic_ml_cache_core.application.port.out.metrics_port import MetricsPort
+from generic_ml_cache_core.application.usecase.cached_ml_execution_service import (
+    CachedMlExecutionService,
+)
+from generic_ml_cache_core.application.usecase.call_identity_building import build_call_identity
+
+
+class RunManagedLocalExecutionService(CachedMlExecutionService, RunManagedLocalExecutionUseCase):
+    """Record-or-replay a fully managed local ML client call.
+
+    Implements the inbound port over the shared cached-execution flow, supplying
+    the managed specifics: fingerprint inputs to build the identity, launch the
+    client in an isolated folder via the client runner, tag executions
+    LOCAL_MANAGED, and treat allow-path folders as non-cacheable (unless
+    scan-trust).
+    """
+
+    def __init__(
+        self,
+        file_fingerprint: FileFingerprintPort,
+        client_runner: ClientRunnerPort,
+        blob_store: BlobStorePort,
+        repository: ExecutionRepositoryPort,
+        metrics: MetricsPort,
+    ) -> None:
+        super().__init__(blob_store, repository, metrics)
+        self._file_fingerprint = file_fingerprint
+        self._client_runner = client_runner
+
+    def _build_identity(self, command: RunManagedLocalExecutionCommand) -> CallIdentity:
+        return build_call_identity(self._file_fingerprint, command)
+
+    def _run_client(self, command: RunManagedLocalExecutionCommand) -> ClientRunResult:
+        return self._client_runner.run(self._build_client_run_request(command))
+
+    def _execution_kind(self) -> ExecutionKind:
+        return ExecutionKind.LOCAL_MANAGED
+
+    def _journal_fields(self, command: RunManagedLocalExecutionCommand) -> Tuple[str, str, str]:
+        return command.client, command.model, command.effort
+
+    def _is_uncacheable(self, command: RunManagedLocalExecutionCommand) -> bool:
+        return command.is_uncacheable
+
+    @staticmethod
+    def _build_client_run_request(command: RunManagedLocalExecutionCommand) -> ClientRunRequest:
+        # The one allowed self-less method (AGENTS §6): the inbound-command ->
+        # outbound-port-DTO boundary mapping, which is the use case's own job.
+        return ClientRunRequest(
+            client=command.client,
+            model=command.model,
+            effort=command.effort,
+            context=command.context,
+            prompt=command.prompt,
+            user_system_prompt=command.user_system_prompt,
+            input_file_paths=command.input_file_paths,
+            allow_paths=command.allow_paths,
+            client_args=command.client_args,
+            grants=frozenset(command.grants),
+        )