orchestrata_ultimate.core.protocols.session

Reference › orchestrata_ultimate › core › protocols › session

The layer-0 seam for session persistence. SessionManagerProtocol is a runtime_checkable protocol that describes exactly the surface of the context and goal store that lower-layer consumers need. The concrete store, session.context.ContextFileManager (SPEC-023), sits at layer 4, so a layer-3 consumer such as the product-manager volk and its GoalRegistry would break the layer rule by importing it. They depend on this protocol instead, and the concrete store is injected at construction and satisfies it structurally. Its payload types live in the session models at layer 4 and cannot be named here, so they appear as Any. The product-manager volk modules goal_registry and volk import it.

At a glance

Class diagram

Dependency diagram

API

Classes

SessionManagerProtocol (protocol)

Bases: Protocol · Decorators: runtime_checkable · Line 23

Minimal context-store contract required by lower-layer consumers.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/protocols/session.py

"""Session context-store protocol — the layer-0 seam for session persistence.

``session.context.ContextFileManager`` (layer 4) is the canonical
context/goal store (SPEC-023), but consumers in lower layers (e.g. the PM
volk's ``GoalRegistry`` at layer 3) may not import it without an upward
layer violation. This protocol captures exactly the surface those consumers
need, so they can depend on the layer-0 contract while the layer-4 concrete
is injected at construction time.

The payload types (``ContextData``/``ProjectState``) live in
``session.models`` at layer 4 and therefore cannot be named here — naming
them, even under ``TYPE_CHECKING``, would itself be an upward static edge
from layer 0. They appear as ``Any``; structural conformance is provided by
``ContextFileManager``, whose ``read()`` returns ``ContextData`` and whose
``update_state()`` returns ``ProjectState``.
"""

from pathlib import Path
from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class SessionManagerProtocol(Protocol):
    """Minimal context-store contract required by lower-layer consumers.

    Satisfied structurally by
    ``orchestrata_ultimate.session.context.ContextFileManager``.
    """

    json_path: Path
    """Path to the canonical ``context.json`` document."""

    def read(self) -> Any:
        """Read the current context document (a ``ContextData``)."""
        ...

    def write(self, ctx: Any) -> None:
        """Persist a context document (a ``ContextData``)."""
        ...

    def update_state(self, **kwargs: Any) -> Any:
        """Update fields on the current ``ProjectState``; returns it."""
        ...