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

generic_ml_cache_core/application/port/inbound/probe_command.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ProbeCommand."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from generic_ml_cache_core.application.domain.service.cacheability import is_call_uncacheable
+
+
+@dataclass(frozen=True)
+class ProbeCommand:
+    """The input to the probe use case: the key-determining inputs only.
+
+    A probe is a read-only forecast, so it carries no run policy (no cache mode,
+    no persist/record flags, no system prompt). It exposes the same keyed fields a
+    run does, so both derive the same key from the shared builder.
+    """
+
+    client: str
+    model: str
+    effort: str
+    context: str
+    prompt: str
+    input_file_paths: List[str] = field(default_factory=list)
+    allow_paths: List[str] = field(default_factory=list)
+    scan_trust: bool = False
+    client_args: List[str] = field(default_factory=list)
+    grants: List[str] = field(default_factory=list)
+
+    @property
+    def is_uncacheable(self) -> bool:
+        return is_call_uncacheable(self.allow_paths, self.scan_trust)

generic_ml_cache_core/application/port/inbound/probe_use_case.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ProbeUseCase (inbound port)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_cache_core.application.domain.model.probe.probe_report import ProbeReport
+from generic_ml_cache_core.application.port.inbound.probe_command import ProbeCommand
+
+
+class ProbeUseCase(ABC):
+    """Inbound port for the read-only cache probe — a forecast of what a run would
+    do, with no side effects (no client launch, no store, no journal event)."""
+
+    @abstractmethod
+    def execute(self, command: ProbeCommand) -> ProbeReport:
+        """Forecast the verdict for ``command`` without running or recording."""

generic_ml_cache_core/application/port/inbound/run_api_execution_command.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunApiExecutionCommand."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from generic_ml_cache_core.application.domain.model.run.cache_mode import CacheMode
+from generic_ml_cache_core.application.domain.model.run.message import Message
+
+
+@dataclass(frozen=True)
+class RunApiExecutionCommand:
+    """The input to the API use case.
+
+    The caller builds the full message list (there is no local client to read
+    files or scan folders), so there are no input-file, allow-path, grant, or
+    scan-trust fields. An API call is always cacheable.
+
+    Note (future): ``persist_output = False`` will be incompatible with async
+    execution — an async call must store its output so the caller can retrieve it
+    by id later. Async is not built yet, so nothing enforces it here.
+    """
+
+    provider: str
+    model: str
+    messages: List[Message] = field(default_factory=list)
+    cache_mode: CacheMode = CacheMode.CACHE
+    persist_output: bool = True
+    record_on_error: bool = False
+
+    def should_persist(self, succeeded: bool) -> bool:
+        """Whether this command's policy stores an output for a run that ended
+        with ``succeeded``: never without ``persist_output``; a failure only with
+        ``record_on_error``."""
+        if not self.persist_output:
+            return False
+        return succeeded or self.record_on_error

generic_ml_cache_core/application/port/inbound/run_api_execution_use_case.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunApiExecutionUseCase (inbound port)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+from generic_ml_cache_core.application.port.inbound.run_api_execution_command import (
+    RunApiExecutionCommand,
+)
+
+
+class RunApiExecutionUseCase(ABC):
+    """Inbound port for record-or-replay of a direct ML provider API call."""
+
+    @abstractmethod
+    def execute(self, command: RunApiExecutionCommand) -> MlExecution:
+        """Resolve the API command and return the resulting execution."""

generic_ml_cache_core/application/port/inbound/run_managed_local_execution_command.py

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunManagedLocalExecutionCommand."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from generic_ml_cache_core.application.domain.model.run.cache_mode import CacheMode
+from generic_ml_cache_core.application.domain.service.cacheability import is_call_uncacheable
+
+
+@dataclass(frozen=True)
+class RunManagedLocalExecutionCommand:
+    """The input to the managed-local use case: raw user intent only.
+
+    It carries file *paths* and raw text, never fingerprints — the use case
+    reads the files and computes the fingerprints. The use case builds the
+    CallIdentity from this command; the command never builds it itself.
+    """
+
+    client: str
+    model: str
+    effort: str
+    context: str
+    prompt: str
+    user_system_prompt: Optional[str] = None
+    input_file_paths: List[str] = field(default_factory=list)
+    allow_paths: List[str] = field(default_factory=list)
+    scan_trust: bool = False
+    client_args: List[str] = field(default_factory=list)
+    grants: List[str] = field(default_factory=list)
+    cache_mode: CacheMode = CacheMode.CACHE
+    persist_output: bool = True
+    record_on_error: bool = False
+
+    @property
+    def is_uncacheable(self) -> bool:
+        return is_call_uncacheable(self.allow_paths, self.scan_trust)
+
+    def should_persist(self, succeeded: bool) -> bool:
+        """Whether this command's policy stores an output for a run that ended
+        with ``succeeded``: never without ``persist_output``; a failure only with
+        ``record_on_error``."""
+        if not self.persist_output:
+            return False
+        return succeeded or self.record_on_error

generic_ml_cache_core/application/port/inbound/run_managed_local_execution_use_case.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunManagedLocalExecutionUseCase (inbound port)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+from generic_ml_cache_core.application.port.inbound.run_managed_local_execution_command import (
+    RunManagedLocalExecutionCommand,
+)
+
+
+class RunManagedLocalExecutionUseCase(ABC):
+    """Inbound port for record-or-replay of a fully managed local client call.
+
+    The driving adapter (CLI, daemon, library consumer) depends on this contract
+    and never on the implementation. The composition root wires the concrete
+    service in.
+    """
+
+    @abstractmethod
+    def execute(self, command: RunManagedLocalExecutionCommand) -> MlExecution:
+        """Resolve the command and return the resulting execution."""

generic_ml_cache_core/application/port/inbound/run_passthrough_execution_command.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunPassthroughExecutionCommand."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from generic_ml_cache_core.application.domain.model.run.cache_mode import CacheMode
+
+
+@dataclass(frozen=True)
+class RunPassthroughExecutionCommand:
+    """The input to the passthrough use case.
+
+    Everything after the client name is opaque: ``native_args`` is forwarded to
+    the client verbatim and enters the key as-is (by fingerprint). A passthrough
+    is always cacheable (it declares no scan folders), so there is no allow-path
+    or scan-trust here.
+    """
+
+    client: str
+    native_args: List[str] = field(default_factory=list)
+    cache_mode: CacheMode = CacheMode.CACHE
+    persist_output: bool = True
+    record_on_error: bool = False
+
+    def should_persist(self, succeeded: bool) -> bool:
+        """Whether this command's policy stores an output for a run that ended
+        with ``succeeded``: never without ``persist_output``; a failure only with
+        ``record_on_error``."""
+        if not self.persist_output:
+            return False
+        return succeeded or self.record_on_error

generic_ml_cache_core/application/port/inbound/run_passthrough_execution_use_case.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""RunPassthroughExecutionUseCase (inbound port)."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from generic_ml_cache_core.application.domain.model.execution.ml_execution import MlExecution
+from generic_ml_cache_core.application.port.inbound.run_passthrough_execution_command import (
+    RunPassthroughExecutionCommand,
+)
+
+
+class RunPassthroughExecutionUseCase(ABC):
+    """Inbound port for record-or-replay of a passthrough (alias) client call."""
+
+    @abstractmethod
+    def execute(self, command: RunPassthroughExecutionCommand) -> MlExecution:
+        """Resolve the passthrough command and return the resulting execution."""

generic_ml_cache_core/application/port/out/__init__.py

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

generic_ml_cache_core/application/port/out/api_client_port.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ApiClientPort."""
+
+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
+from generic_ml_cache_core.application.domain.model.run.message import Message
+
+
+class ApiClientPort(ABC):
+    """Outbound port for calling an ML provider API directly.
+
+    Distinct from the local runner ports: there is no subprocess, no filesystem,
+    and no grants — the caller has already built the full message list. The
+    adapter returns a raw ClientRunResult with the response text as stdout, an
+    empty file list, and the provider-reported token usage when available.
+    """
+
+    @abstractmethod
+    def run(self, provider: str, model: str, messages: List[Message]) -> ClientRunResult:
+        """Call ``provider``'s ``model`` with ``messages`` and return the raw
+        result. Raises on an unrecoverable transport failure."""

generic_ml_cache_core/application/port/out/base.py

@@ -0,0 +1,272 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Client adapters: how to launch one agentic CLI and read its output.
+
+An adapter is the *only* place that knows a specific CLI's flags. Everything
+else in the cache works in terms of the neutral quartet
+``(model, effort, prompt, context)`` plus a system prompt.
+
+The v0.0.1 adapters below encode each CLI's own launch conventions (Claude
+``--effort``; Codex ``model_reasoning_effort``; Cursor bakes effort into the
+model id). Flags can drift, so every adapter:
+
+* accepts an explicit ``executable`` override (the *executable seam*), and
+* keeps launch wiring small and obvious so it is cheap to correct.
+
+Adapters never decide caching policy and never read the caller's ambient files.
+"""
+
+from __future__ import annotations
+
+import shutil
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import ClassVar, List, Optional, Sequence
+
+from generic_ml_cache_core.application.domain.model.model_info import ModelInfo as ModelInfo
+from generic_ml_cache_core.application.domain.model.parsed_output import ParsedOutput
+from generic_ml_cache_core.common.errors import ClientNotFound
+
+
+class ClientAdapter(ABC):
+    """Translate the neutral request into a concrete subprocess invocation."""
+
+    #: short client name used in stored records and on the CLI (e.g. "claude")
+    name: ClassVar[str]
+    #: default executable looked up on PATH when no override is given
+    default_executable: ClassVar[str]
+
+    def resolve_executable(self, override: Optional[str]) -> str:
+        """Return an absolute path to the executable, honoring the seam."""
+        candidate = override or self.default_executable
+        # An explicit path (contains a separator) is used verbatim if it exists.
+        if any(sep in candidate for sep in ("/", "\\")):
+            p = Path(candidate)
+            if p.exists():
+                return str(p)
+            raise ClientNotFound(f"executable not found at {candidate!r}")
+        found = shutil.which(candidate)
+        if not found:
+            raise ClientNotFound(
+                f"could not find {candidate!r} on PATH; pass --executable to override"
+            )
+        return found
+
+    def version_argv(self, executable: str) -> List[str]:
+        """Argv that prints the client's version. Default: ``<exe> --version``.
+
+        Override only if a client uses a different flag. Advisory: used by the
+        ``doctor`` command for discovery; it never affects caching.
+        """
+        return [executable, "--version"]
+
+    def models_argv(self, executable: str) -> Optional[List[str]]:
+        """Argv that makes the client list the models it can use, or ``None``.
+
+        Return ``None`` when the client has no scriptable way to enumerate its
+        models -- discovery then reports "not supported" for this client rather
+        than inventing or substituting a list. When non-``None``, the output is
+        relayed through :meth:`parse_model_list`. Because the client is the one
+        already authenticated, a relayed list reflects what *that account* can
+        actually reach. Advisory: never selects, restricts, or gates a run.
+        """
+        return None
+
+    def parse_model_list(self, stdout: str) -> List[ModelInfo]:
+        """Structure the client's raw model-list output into ``ModelInfo``.
+
+        Only called when :meth:`models_argv` returns a command; override the two
+        together. Keep parsing to plain structuring of what the client printed.
+        """
+        raise NotImplementedError
+
+    def prepare(self, run_dir: Path, context: str, prompt: str, system_prompt: str) -> None:
+        """Write any input files the client needs into its isolated folder.
+
+        Called *before* the pre-run snapshot, so anything written here is part of
+        the baseline and is therefore not mistaken for client output. Default:
+        no-op (the client receives everything via argv/stdin).
+        """
+
+    @abstractmethod
+    def build_argv(
+        self,
+        executable: str,
+        run_dir: Path,
+        model: str,
+        effort: str,
+        context: str,
+        prompt: str,
+        system_prompt: str,
+        client_args: List[str],
+        grants: Sequence[str] = (),
+    ) -> List[str]:
+        """Return the full argv to launch the client in ``run_dir``.
+
+        ``client_args`` are passthrough arguments the caller wants appended to the
+        launch verbatim -- the cache never interprets them. The adapter places
+        them as late as its CLI allows while they are still read as flags: at the
+        very end for clients whose prompt arrives on stdin, but **before the
+        trailing prompt positional** for a client that takes the prompt in argv
+        (otherwise they would be swallowed as prompt text rather than applied).
+
+        ``grants`` are declared capabilities to *open* for this run (e.g. ``"net"``
+        for network access). The adapter opens the matching door via
+        :meth:`grant_setup` (a config-file mechanism) when granted. Grants enable;
+        they never restrict (see ``docs/reference/grants.md``).
+        """
+
+    def stdin_payload(self, context: str, prompt: str, system_prompt: str) -> Optional[str]:
+        """Optional text to feed on stdin. Default: nothing."""
+        return None
+
+    def parse_output(self, stdout: str) -> ParsedOutput:
+        """Lift the clean answer text and the usage envelope out of the client's
+        raw stdout.
+
+        The cache runs each client in its **structured (JSON) output mode** so it
+        can read usage -- which means raw stdout is no longer the bare answer but a
+        JSON object (or JSON-lines stream) with the answer as one field and the
+        token counts beside it. The adapter is the only place that knows its own
+        client's structure, so it does the extraction here: it returns the answer
+        text (which the cache then hands the caller on stdout, exactly as a plain
+        client would) and the normalized :class:`~..usage.Usage` it read.
+
+        Default: the client was *not* run in a structured mode, so stdout already
+        *is* the answer and there is no usage to read. Adapters that switch their
+        client to JSON override this.
+
+        An override MUST degrade rather than raise: if the output cannot be parsed
+        (an unexpected shape, a truncated stream), return ``ParsedOutput(stdout,
+        None)`` so a parsing surprise never breaks the core call -- the caller
+        still gets the client's output, just without a usage envelope.
+        """
+        return ParsedOutput(text=stdout, usage=None)
+
+    def read_access_argv(self, paths: List[str]) -> List[str]:
+        """Extra argv granting the client read access to ``paths`` (directories).
+
+        Default: none -- the client relies on the soft prime-directive door only.
+        Adapters with a real per-client read mechanism override this (Claude:
+        ``--add-dir``). Codex and Cursor have one too but it is heterogeneous and
+        currently unverified, so they stay on the directive until adapter
+        hardening verifies them against the live CLIs.
+        """
+        return []
+
+    def write_access_argv(self, run_dir: Path) -> List[str]:
+        """Extra argv opening the client's WRITE/TRUST door for its own ``run_dir``.
+
+        Headless clients refuse to write by default: they pause on a permission
+        prompt, or decline a workspace they have not been told to trust. Without
+        this the client only *narrates* the file it was asked to produce, the
+        before/after diff captures nothing, and a file-producing call records an
+        empty ``response.files`` -- the v0.0.5 record-path bug this fixes.
+
+        The run folder is the client's own isolated, ephemeral sandbox, so writing
+        into it is the normal case and the grant is **on by default**. It is scoped
+        to that folder: reads *outside* it are unaffected and remain gated by the
+        prime directive and :meth:`read_access_argv`. Unlike ``read_access_argv``
+        (appended after :meth:`build_argv`), each adapter splices this into
+        ``build_argv`` itself, because some CLIs take the prompt as a trailing
+        positional and reject flags placed after it.
+
+        Default: none. The per-client flags below are verified against the live
+        CLIs (see ``docs/client-mapping.md``); adapter hardening keeps them small
+        and correctable should a CLI change.
+        """
+        return []
+
+    #: capabilities the cache can OPEN via the uniform config-file mechanism.
+    GRANTS: ClassVar[tuple] = ("net", "read", "write", "shell", "web-search")
+
+    def grant_setup(self, run_dir: Path, config_home: Path, grants: Sequence[str]) -> dict:
+        """Render this client's own config file into ``config_home`` so the file --
+        not a flag -- enables the granted capabilities, and return the environment
+        the run needs (the client's config-home variable pointed at ``config_home``,
+        e.g. ``{"CODEX_HOME": ...}``), seeding any credentials the relocated home
+        needs along the way.
+
+        This is the uniform door (v0.0.16): every client is driven the same way --
+        a private config home, its home variable pointed at it, the settings file
+        written inside. Writing into the run folder is always on (the client cannot
+        produce output otherwise); the named grants open capability *beyond* that.
+        Grants ENABLE, never restrict (``docs/reference/grants.md``); where a client has no
+        file-level way to *close* a capability, that is a documented limit, not a
+        door this method tries to shut.
+
+        ``config_home`` is separate from ``run_dir``, so nothing written here is
+        ever mistaken for client output or captured into a stored record. Default: no
+        config home, empty env (adapters override).
+        """
+        return {}
+
+    def grant_argv(self, grants: Sequence[str]) -> List[str]:
+        """Operational flags a client FORCES for a grant its config file cannot
+        express -- not a capability door, a transport necessity (Cursor's external
+        network egress is ignored in its sandbox file headless, so ``net`` still
+        needs ``--force``). Default: none.
+        """
+        return []
+
+    def stream_event(self, raw_line: str) -> Optional[dict]:
+        """Map ONE raw stdout line of this client's streaming output into a small
+        normalized progress event, e.g. ``{"kind": "thinking"}`` or
+        ``{"kind": "tool", "name": "web_search"}`` -- or ``None`` to ignore the
+        line. Used only to feed the opt-in live stream (``--stream``; see
+        ``stream.py``); it never affects what is recorded. Default: ignore every
+        line (a client whose stream we do not normalize still shows the cache's own
+        ``run.start`` / ``run.end`` events).
+        """
+        return None
+
+
+def final_result_object(stdout: str):
+    """Return the client's final result object, whether its output arrived as a
+    single JSON object (``--output-format json``) or as the last ``type:result``
+    line of an NDJSON stream (``--output-format stream-json``).
+
+    Claude and Cursor emit *the same* result object in both forms, so the recorded
+    answer and usage are identical either way -- this is what lets the live stream
+    switch the client to streaming mode without changing the stored record. Returns
+    ``None`` if nothing parseable is present (the adapter then degrades to raw
+    stdout with no usage).
+    """
+    import json
+
+    text = stdout.strip()
+    if not text:
+        return None
+    # Single object (today's --output-format json): parses whole, in one shot.
+    try:
+        doc = json.loads(text)
+        if isinstance(doc, dict):
+            return doc
+    except (json.JSONDecodeError, ValueError):
+        pass  # not a single object -> it is an NDJSON stream; scan for the result
+    last = None
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if isinstance(event, dict) and event.get("type") == "result":
+            last = event
+    return last
+
+
+def ensure_trailing_newline(text: str) -> str:
+    """Append a newline to a client's answer when it lacks one.
+
+    A client's structured (JSON) ``result`` carries the bare answer text, without
+    the trailing newline a real CLI prints when it shows that answer. Without this
+    the replayed answer butts against the next shell prompt, and a piped capture
+    (``gmlcache run ... > file``) lacks the conventional final newline. Normalizing
+    here -- at the adapter boundary -- keeps record and replay byte-identical (the
+    recorded form simply includes the newline). Empty text is left untouched."""
+    if text and not text.endswith("\n"):
+        return text + "\n"
+    return text

generic_ml_cache_core/application/port/out/blob_store_port.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""BlobStorePort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class BlobStorePort(ABC):
+    """Outbound port for storing and retrieving opaque execution output bytes.
+
+    The store is intentionally dumb: it translates a key to its own address and
+    reads/writes bytes. It never parses a payload, never computes a key, and
+    never interprets content. This is what makes it swappable (filesystem, S3,
+    in-memory) without touching the core.
+
+    The key is always produced by CallIdentity.generate_key().
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> Optional[bytes]:
+        """Return the stored bytes for ``key``, or None if not present."""
+
+    @abstractmethod
+    def put(self, key: str, output: bytes) -> None:
+        """Persist ``output`` under ``key``, overwriting any prior value."""
+
+    @abstractmethod
+    def remove(self, key: str) -> None:
+        """Delete the bytes stored under ``key``; a no-op if nothing is stored.
+
+        Removal is driven by a reference-counted prune (a blob is content-
+        addressed and may be shared by many executions), so a caller removes a
+        key only after confirming no execution still references it.
+        """

generic_ml_cache_core/application/port/out/client_runner_port.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ClientRunnerPort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+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
+
+
+class ClientRunnerPort(ABC):
+    """Outbound port for launching a local ML client and capturing its output.
+
+    The adapter is the only place that knows a specific client's CLI flags,
+    isolation mechanism, and output format. The core names only this contract.
+    The runner returns a raw ``ClientRunResult`` — it never hashes, never
+    computes a key, never stores; turning the result into stored artifacts is
+    the use case's job.
+    """
+
+    @abstractmethod
+    def run(self, client_run_request: ClientRunRequest) -> ClientRunResult:
+        """Launch the client described by ``client_run_request`` and return its
+        raw captured result. Raises on unrecoverable launch failure."""

generic_ml_cache_core/application/port/out/clock_port.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""ClockPort."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+
+class ClockPort(ABC):
+    """Outbound port for reading the current time.
+
+    Time is ambient I/O, so the core never calls ``datetime.now()`` directly —
+    it reads the clock through this port. The composition root injects a real
+    clock; a test injects a fixed one. This keeps the engine deterministic and
+    free of hidden wall-clock dependencies.
+    """
+
+    @abstractmethod
+    def now(self) -> datetime:
+        """Return the current instant as a timezone-aware UTC datetime."""