openframe-core 3.7.0__tar.gz → 3.8.0__tar.gz

{openframe_core-3.7.0 → openframe_core-3.8.0}/.github/CHANGELOG.md

@@ -11,6 +11,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v3.8.0 — 2026-10-17
+
+### Added — `SessionHandler`/`Session`/`CloseReason` (ADR-008)
+
+A new driving-side contract for long-lived connections (WebSocket, SSE),
+sibling to `UseCase`/`CommandHandler`/`QueryHandler` (ADR-006). Built to
+unblock `openframe-protocol`'s session-transport work, which found the
+design spec's own `SessionHandler` sketch had zero code anywhere and left
+one concrete question unresolved: how a handler sends events *out*.
+
+- `openframe.core.inbound.Session[TOut]` — `@runtime_checkable Protocol`,
+  `context: RequestContext` (built once per session, not once per event)
+  plus `send(event)`/`close(reason)`. Push-based, not a pull-based
+  `AsyncIterator` return value — see ADR-008 for the full reasoning.
+- `openframe.core.inbound.SessionHandler[TIn, TOut]` —
+  `on_open(session)`/`on_event(session, event)`/`on_close(session, reason)`.
+  `on_open` doubles as accept/reject: raising rejects, flowing through the
+  same `categorize`/`build_envelope` path (`openframe-protocol-base`)
+  every other inbound contract's failures already use.
+- `openframe.core.inbound.CloseReason` — closed `Enum`:
+  `COMPLETED`/`CLIENT_DISCONNECT`/`SERVER_SHUTDOWN`/`ERROR`.
+- `openframe.core.testing.SessionHandlerContractTests` and
+  `openframe.core.testing.InMemorySession` — same fixture-based subclass
+  pattern as the three existing inbound contract-test classes/fakes.
+- Deliberately built directly in `openframe-core`, not incubated in
+  `openframe-protocol-base` first per the design spec's own stated
+  rule-of-three gate — documented as an explicit, conscious exception in
+  ADR-008, not a precedent for skipping that discipline generally.
+- Purely additive — no existing contract changed. 445 tests passing (see
+  `tests/test_inbound.py`/`test_inbound_contracts.py` for the new
+  `SessionHandler`/`Session`/`InMemorySession` coverage).
+
+---
+
 ## v3.7.0 — 2026-10-11
 
 ### Added

{openframe_core-3.7.0 → openframe_core-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-core
-Version: 3.7.0
+Version: 3.8.0
 Summary: OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-core
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-core/

openframe_core-3.8.0/docs/technical/architecture/adrs/adr-008-session-handler.md

@@ -0,0 +1,113 @@
+# ADR-008 — `SessionHandler`: a driving-side contract for long-lived connections
+
+**Status:** Accepted — v3.8.0
+**Extends:** [ADR-006 — Unified Port + Lifecycle Contract](adr-006-unified-port-lifecycle.md)'s
+`openframe.core.inbound` module (`UseCase`, `CommandHandler`, `QueryHandler`, `RequestContext`).
+
+---
+
+## Context
+
+`openframe-protocol` builds two request/response transports (`-http`, `-grpc`) on
+`openframe.core.inbound`'s existing contracts: one input in, one output out, done. Neither shape
+fits a long-lived connection — WebSocket (bidirectional) or Server-Sent Events (unidirectional,
+server→client) — where a handler may receive zero or many inbound events and send zero or many
+outbound events over the connection's lifetime.
+
+`openframe-protocol`'s own design spec sketches a `SessionHandler[TEvent]` contract
+(`on_open`/`on_event`/`on_close`) as the intended fix, with an explicit rule: incubate it in
+`openframe-protocol-base` first, and only promote it to `openframe-core` once three independent
+session transports have proven the shape against the same conformance suite — the same
+rule-of-three discipline this repo already applies to `Capability` and `ErrorCategory` additions.
+
+That sketch has zero lines of code anywhere, in either repo, and the design spec itself flags one
+concrete unresolved question as a blocker: **how does a handler actually send events to the
+client?** `on_open`/`on_event`/`on_close` describe the inbound (driving) half of the contract only
+— receiving events and lifecycle notifications — but say nothing about the outbound half.
+
+## Decision
+
+**Build `SessionHandler` directly in `openframe.core.inbound`, not incubated in
+`openframe-protocol-base` first** — a deliberate deviation from the stated rule-of-three gate (see
+"Why skip incubation" below) — alongside a new `Session[TOut]` contract that resolves the
+unanswered outbound-events question.
+
+- **`Session[TOut]`** (`openframe/core/inbound/session.py`) — `@runtime_checkable Protocol`,
+  carries `context: RequestContext` (built once per session, not once per event — a session has
+  one correlation id for its whole lifetime) plus two methods:
+  - `async def send(self, event: TOut) -> None` — push one outbound event.
+  - `async def close(self, reason: CloseReason = CloseReason.COMPLETED) -> None` — end the
+    session. Idempotent.
+
+  **Push-based, not a pull-based `AsyncIterator[TOut]` return value.** A handler can call
+  `session.send()` from inside `on_event` (responding to an inbound message) *or* from a
+  background task it spawns at `on_open` (e.g. forwarding events from an unrelated source — a
+  Kafka consumer — into an already-open connection). A generator return value can't express the
+  latter without the handler building its own internal queue anyway, at which point that queue
+  *is* a `Session` object in a different shape — so `Session` names the thing directly instead of
+  leaving every handler to reinvent it.
+
+- **`SessionHandler[TIn, TOut]`** (same module) — `@runtime_checkable Protocol` with three methods:
+  - `async def on_open(self, session: Session[TOut]) -> None` — accept (return normally) or reject
+    (raise) a new session. A raised exception flows through
+    `openframe.protocol.base.errors.categorize`/`build_envelope` — the exact same mapping path
+    every other inbound contract's failures already use — rather than a second return-value
+    channel a caller would need a separate check for.
+  - `async def on_event(self, session: Session[TOut], event: TIn) -> None` — called once per
+    inbound event, in arrival order. **Never called at all** for a one-directional transport (SSE,
+    which has no client→server events) — a valid, expected lifecycle, not a contract violation.
+  - `async def on_close(self, session: Session[TOut], reason: CloseReason) -> None` — called
+    exactly once, however the session ended.
+
+- **`CloseReason`** (same module) — closed `Enum`: `COMPLETED`, `CLIENT_DISCONNECT`,
+  `SERVER_SHUTDOWN`, `ERROR`. Every session transport maps its own disconnect/shutdown signal onto
+  one of these four, mirroring how `ErrorCategory` gives every transport one shared vocabulary for
+  errors instead of each inventing its own.
+
+- **Testing**: `SessionHandlerContractTests` (`testing/contracts/inbound.py`, alongside the
+  existing three inbound contract-test classes) and `InMemorySession`
+  (`testing/fakes/inbound.py`, alongside `EchoUseCase`/`SpyCommandHandler`/`SpyQueryHandler`) —
+  same fixture-based subclass pattern, same zero-pytest-at-module-level discipline.
+
+### Why skip incubation in `-base`
+
+The rule-of-three gate exists to de-risk a contract shape against real, demonstrated need before
+it lands in the platform kernel. The one genuine open question that gate would have surfaced —
+how outbound events are sent — is resolved by this decision itself (the `Session` push model
+above), reasoned from first principles against both a one-directional transport (SSE) and a
+bidirectional one (WebSocket) rather than discovered incrementally across three separate builds.
+Incubating a second time in `-base` before any transport exists to prove it against would add a
+layer of indirection with no remaining uncertainty left to burn down. This is recorded here as an
+explicit, conscious exception — not a precedent for skipping the rule-of-three discipline
+generally; `Capability`/`ErrorCategory`-style additions should still default to it.
+
+## Consequences
+
+- **`openframe.core.inbound.__init__`** exports `SessionHandler`, `Session`, `CloseReason`
+  alongside the existing `UseCase`, `CommandHandler`, `QueryHandler`, `RequestContext`.
+- **No change to any existing contract.** `UseCase`/`CommandHandler`/`QueryHandler`/
+  `RequestContext` are untouched — this is a pure addition.
+- **`openframe-protocol-base` gains transport-neutral session plumbing next** (a `run_session`
+  loop helper and a `SessionConformanceTests` suite), reusing `build_request_context` and
+  `categorize`/`build_envelope` as-is — both already generic enough for a session's single
+  per-connection context and in-band error events, confirmed during design research, not assumed.
+- **SSE is the first transport to implement `SessionHandler`**, as a new module inside
+  `openframe-protocol-http` (per that repo's own design spec placement decision) rather than a new
+  package — chosen because it is one-directional (`on_event` never fires), the lower-risk half of
+  the contract to prove first. WebSocket (bidirectional, its own package-boundary question) is
+  explicitly out of scope for this ADR.
+- **Version bump: `3.7.0` → `3.8.0`** — additive, non-breaking minor version.
+
+## Alternatives considered
+
+- **Pull-based `AsyncIterator[TOut]` return value from `on_open`.** Rejected: maps cleanly onto
+  SSE alone, but can't express a handler pushing an event from outside its own generator's loop
+  (an external task, or `on_event` triggering an unprompted send) without the handler building an
+  internal queue regardless — see "Decision" above.
+- **Model session rejection as a return value** (e.g. `on_open` returns `bool`) instead of raising.
+  Rejected: every other inbound contract in this module signals failure by raising, and a second,
+  bespoke "did it accept" channel here would mean `SessionHandler` is the only inbound contract a
+  caller can't route through the shared `categorize`/`build_envelope` error path uniformly.
+- **Incubate in `openframe-protocol-base` first, per the design spec's own stated rule.**
+  Rejected for this specific contract — see "Why skip incubation" above. Not a general reversal of
+  the rule-of-three discipline for future additions.

{openframe_core-3.7.0 → openframe_core-3.8.0}/docs/technical/architecture/system-architecture.md

@@ -11,7 +11,7 @@ As of v3.1.0, `ports/` unifies what were previously two separate
 modules: `openframe.core.contracts` (the port/lifecycle primitives) and
 `openframe.core.ports` (the outbound protocols, now internally organised
 under `ports/outbound/`). See
-[ADR-006's v3.1.0 addendum](adrs/adr-006-unified-port-lifecycle.md#addendum--contracts-merged-into-ports-outbound-sub-module-introduced-v310)
+[ADR-006's v3.1.0 addendum](adrs/adr-006-unified-port-lifecycle.md#addendum-contracts-merged-into-ports-outbound-sub-module-introduced-v310)
 for the full rationale.
 
 ---

{openframe_core-3.7.0 → openframe_core-3.8.0}/docs/technical/overview/roadmap.md

@@ -41,11 +41,106 @@ Lower-priority items:
 
 ### openframe-adapters
 
-- `openframe-adapters-db-postgres` — first adapter, reference implementation
-- `openframe-adapters-db-redis` — key-value, pub/sub, semantic cache
-- `openframe-adapters-db-mongo` — document store for AI Research Vault Phase 1
-- `openframe-adapters-queue-kafka` — producer + consumer, unlocks event-driven template
-- Remaining 11 adapters in parallel once the pattern is validated
+Done since this was last updated:
+
+- ~~`openframe-adapters-db-postgres` — first adapter, reference implementation~~
+- ~~`openframe-adapters-db-redis` — key-value, pub/sub, semantic cache~~
+- ~~`openframe-adapters-db-mongo` — document store for AI Research Vault Phase 1~~
+- ~~`openframe-adapters-queue-kafka` — producer + consumer, unlocks event-driven template~~
+- ~~Remaining 11 adapters in parallel once the pattern is validated~~ —
+  built in checklist-driven waves (see `openframe-adapters`' own
+  `.github/CHANGELOG.md`): queue (nats, rabbitmq), relational
+  (cockroachdb, mysql, mariadb, oracle), key-value/columnar (dynamodb,
+  cassandra), time-series (influxdb), vector (qdrant, milvus, chromadb),
+  graph (falkordb). 17 real packages total. FAISS remains explicitly
+  descoped — no native id→metadata store, doesn't fit
+  `BaseVectorStore`'s id-addressable design.
+- ~~`BaseVectorStore[T]` / `BaseGraphStore[T]`~~ — both shipped in this
+  repo (v3.5.0 / v3.6.0), each extending `BaseRepository[T]` directly
+  plus exactly one new method, rather than as disjoint sibling ports.
+  See [ADR-006](../architecture/adrs/adr-006-unified-port-lifecycle.md)
+  for the port-design philosophy both followed.
+
+Next capabilities under consideration — each is a candidate NEW
+top-level capability, not an extension of an existing adapter package.
+**Every adapter in this ecosystem depends only on `openframe-core` plus
+its own driver library, never on a sibling `openframe-adapters-*`
+package** (e.g. `openframe-adapters-db-falkordb` depends on `redis-py`
+directly, not on `openframe-adapters-db-redis`, even though FalkorDB is
+Redis-based under the hood) — this constraint applies to every item
+below too, most pointedly the Redis-backed ones:
+
+- **Object storage** (`BaseObjectStore` — already named in the v3.1.0
+  entry further down this same file) — S3, GCS, Azure Blob, MinIO. Strongest fit for the existing
+  extend-`BaseRepository`-plus-one-method pattern; put/get/delete/list
+  by key is arguably more naturally CRUD-shaped than graph nodes were.
+  **Superseded twice, history kept for continuity.** Pass 1 of this
+  entry proposed an outbound FTP/SFTP client adapter here under
+  `Capability.STORAGE` (server half → `openframe-protocol`, client half
+  → here). Pass 2 (`openframe-protocol` draft 7) moved both halves of
+  FTP into `openframe-protocol-ftp` together, removing it as a
+  candidate here entirely. **Pass 3 (`openframe-protocol` draft 8,
+  current)** reverses pass 2: the boundary is now "by peer, not by
+  protocol" — FTP's *server* half (accepting uploads from unknown
+  callers) stays in `openframe-protocol-ftp`, but the *client* half
+  (connecting to one specific named third-party FTP server) is a
+  third-party-peer integration and belongs back here, in
+  `openframe-adapters`, as originally thought. Its exact `Capability`
+  fit is explicitly **not yet decided** (draft 8's own open decision
+  D11 — `STORAGE` is a candidate, not settled) — don't treat the old
+  pass-1 `STORAGE` placement as confirmed; it's a plausible answer to
+  an open question, not a closed one. Same reopened status applies to
+  RTMP push and RTSP pull (D11 again — none of the eleven existing
+  `Capability` members fits either yet) and to a raw SMTP relay
+  (tentatively `NOTIFICATION`, same not-yet-added caveat as below).
+- **Full-text/structured search** — Elasticsearch, OpenSearch. Reuses
+  `Capability.SEARCH` (already shared with vector/graph stores); own
+  query shape (term/boolean queries, not vector similarity or Cypher).
+- **Secrets management** (`BaseSecretsProvider` — also pre-named) —
+  Vault, AWS/GCP/Azure secret managers. Not CRUD-shaped — versioned key
+  lookups need their own port design, not a `BaseRepository` extension.
+- **Feature flags** (`BaseFeatureFlagProvider` — also pre-named) —
+  LaunchDarkly, Unleash, GrowthBook. Not CRUD-shaped — boolean/variant
+  evaluation.
+- **Distributed locking** — own Redis/etcd/Zookeeper client (never the
+  `openframe-adapters-db-redis` package itself). `acquire`/`release`/
+  `extend` is close to CRUD-shaped but isn't quite it.
+- **Notifications** (email/SMS/push, plus Slack/webhook alerts and
+  PagerDuty/Opsgenie-style paging) — SES, SendGrid, Twilio, FCM, Slack
+  incoming webhooks, PagerDuty. Shaped like `BaseProducer`
+  (fire-and-forget/ack), not `BaseRepository`. Intended new taxonomy
+  member: `Capability.NOTIFICATION` — named now, not added to the enum
+  yet (see below). The role this covers is distinct from this repo's
+  existing logging/OTel-metrics signals: those are machine-consumed
+  telemetry (dashboards, alerting pipelines that process metrics);
+  `NOTIFICATION` covers reaching an actual human or external system
+  directly (an email landing in an inbox, a page firing, a Slack
+  message posting) — a different capability, not a backend for the
+  telemetry this repo already has. Candidate justification, following
+  the same bar `Capability.SEARCH` met (shared by multiple genuinely
+  analogous backends, not invented for one): email, SMS, push, and
+  chat/paging providers are all the same operational role — deliver a
+  message to an end-human/device via an external provider — which is
+  why this is a stronger fit than forcing it onto the existing `QUEUE`
+  member (which specifically describes message *brokers* with
+  consumer-side subscribe/ack semantics; SES/SendGrid/Slack have none
+  of that).
+  - **Do not add `Capability.NOTIFICATION` to the enum speculatively.**
+    Per this repo's own closed-taxonomy discipline (ADR-006;
+    `Capability.TRANSPORT` was not repurposed for inbound transport
+    servers in the `openframe-protocol` design review for the same
+    reason) — add the member only once a real adapter (email, SMS,
+    push, or paging) is actually being built, not ahead of one. This
+    bullet records the intended name and justification so that moment
+    doesn't have to re-derive either from scratch.
+- **Identity/auth verification** — Auth0, Okta, Keycloak token
+  introspection or user lookup.
+- **Rate limiting** — same Redis-driver-directly caveat as locking.
+
+Deliberately out of scope for now: workflow orchestration (Temporal/
+Camunda — too large a port surface for one method), schema registries
+(Kafka-ecosystem-specific, niche), payment processing (too
+domain-specific for generic infra adapters).
 
 ### openframe-suite
 
@@ -65,7 +160,7 @@ Lower-priority items:
 - `ApplicationBootstrap.registry` — new read-only property exposing the underlying `PluginRegistry`.
 - `PluginRegistry(default_init_timeout=...)` / `register(..., init_timeout=...)` (mirrored on `ApplicationBootstrap`) — bound how long `initialize_all()` waits for a port's `initialize()`. Both default to `None` (no timeout) — fully backward-compatible.
 - Fixed: `TracingProxy`'s `asyncio.iscoroutinefunction` deprecation; `AmbiguousCapabilityError` now mirrors `capability`/`matches` into `context`.
-- Full changelog: [`.github/CHANGELOG.md`](../../../.github/CHANGELOG.md#v330--2026-09-28).
+- Full changelog: [`.github/CHANGELOG.md`](https://github.com/Furious-Meteors/openframe-core/blob/production/.github/CHANGELOG.md#v330--2026-09-28).
 
 ---
 

{openframe_core-3.7.0 → openframe_core-3.8.0}/mkdocs.yml

@@ -156,6 +156,7 @@ nav:
         - ADR-004 Pydantic Settings: technical/architecture/adrs/adr-004-pydantic.md
         - ADR-005 Middleware Telemetry: technical/architecture/adrs/adr-005-middleware.md
         - ADR-006 Unified Port Lifecycle: technical/architecture/adrs/adr-006-unified-port-lifecycle.md
+        - ADR-007 Schema Contracts: technical/architecture/adrs/adr-007-schema-contracts.md
       - Capability Taxonomy: technical/architecture/capability-taxonomy.md
       - Error Taxonomy: technical/architecture/error-taxonomy.md
       - Design Decisions: technical/architecture/design-decisions.md

{openframe_core-3.7.0 → openframe_core-3.8.0}/openframe/core/inbound/__init__.py

@@ -11,6 +11,11 @@ routes, message-handler entrypoints, CLI commands).
 - :class:`~openframe.core.inbound.usecase.UseCase` — general driving contract.
 - :class:`~openframe.core.inbound.command.CommandHandler` — write-side CQRS specialisation.
 - :class:`~openframe.core.inbound.query.QueryHandler` — read-side CQRS specialisation.
+- :class:`~openframe.core.inbound.session.SessionHandler` — long-lived-connection
+  specialisation (ADR-008) for transports where a handler may receive zero or
+  many inbound events and send zero or many outbound events over time
+  (WebSocket, SSE), via a push-based :class:`~openframe.core.inbound.session.Session`
+  handle.
 - :class:`~openframe.core.inbound.context.RequestContext` — correlation id
   + optional identity, constructed by inbound adapters and passed into
   ``execute()``.
@@ -22,11 +27,15 @@ from __future__ import annotations
 from openframe.core.inbound.command import CommandHandler
 from openframe.core.inbound.context import RequestContext
 from openframe.core.inbound.query import QueryHandler
+from openframe.core.inbound.session import CloseReason, Session, SessionHandler
 from openframe.core.inbound.usecase import UseCase
 
 __all__ = [
     "UseCase",
     "CommandHandler",
     "QueryHandler",
+    "SessionHandler",
+    "Session",
+    "CloseReason",
     "RequestContext",
 ]

openframe_core-3.8.0/openframe/core/inbound/session.py

@@ -0,0 +1,180 @@
+"""
+openframe/core/inbound/session.py
+====================================
+SessionHandler — the long-lived-connection driving-side contract
+(ADR-008), sibling to :class:`~openframe.core.inbound.usecase.UseCase`.
+
+``UseCase``/``CommandHandler``/``QueryHandler`` (ADR-006) model one-shot
+request/response exchanges: one input in, one output out, done. They do
+not fit a long-lived connection (WebSocket, SSE) where a handler may
+receive zero or many inbound events and send zero or many outbound
+events over its lifetime. ``SessionHandler`` is that shape.
+
+``Session[TOut]`` is deliberately **push-based**, not a pull-based
+``AsyncIterator`` return value: ``send()``/``close()`` are available from
+inside ``on_open``, ``on_event``, or a background task the handler spawns
+at ``on_open`` — e.g. forwarding events from an unrelated source (a Kafka
+consumer) into an already-open connection, something a generator can't
+express without building an internal queue anyway, at which point the
+queue *is* a ``Session`` in disguise.
+
+``on_open`` doubles as the accept/reject point — raising rejects the
+session, flowing through the exact same
+``openframe.protocol.base.errors.categorize``/``build_envelope`` path
+every other inbound contract's failures already do, rather than a
+second return-value channel a caller would need a separate check for.
+
+``RequestContext`` is built once per session (at connection/handshake
+time), not once per event — a session has one correlation id for its
+whole lifetime. This matches ``build_request_context``'s own precondition
+(headers are only available once, at handshake time) for every transport
+this contract is meant to serve.
+
+Dependency order:
+    inbound/context  → ports/context
+    inbound/session  → inbound/context
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Protocol, TypeVar, runtime_checkable
+
+from openframe.core.inbound.context import RequestContext
+
+__all__ = ["CloseReason", "Session", "SessionHandler"]
+
+TIn = TypeVar("TIn")
+TOut = TypeVar("TOut")
+
+
+class CloseReason(Enum):
+    """
+    Why a session ended.
+
+    Closed, transport-neutral set — every `openframe-protocol-*` session
+    transport maps its own disconnect/shutdown signal onto one of these
+    four values rather than inventing its own vocabulary.
+    """
+
+    COMPLETED = "completed"
+    """The handler or transport ended the session normally."""
+
+    CLIENT_DISCONNECT = "client_disconnect"
+    """The remote end disconnected (socket closed, stream aborted)."""
+
+    SERVER_SHUTDOWN = "server_shutdown"
+    """The server is shutting down and is closing open sessions."""
+
+    ERROR = "error"
+    """An unhandled exception from `on_open`/`on_event` ended the session."""
+
+
+@runtime_checkable
+class Session(Protocol[TOut]):
+    """
+    Handle a :class:`SessionHandler` uses to push events to the remote end
+    and to end the session.
+
+    Adapters satisfy this protocol structurally — no inheritance needed.
+    A concrete implementation (e.g. an SSE or WebSocket session) adapts
+    its own wire format in :meth:`send`; the handler never sees that
+    format.
+
+    Type parameter:
+        TOut: The event type this session sends to the remote end.
+
+    Attributes:
+        context: The session's `RequestContext`, built once at
+                 connection/handshake time and stable for the session's
+                 entire lifetime.
+    """
+
+    context: RequestContext
+
+    async def send(self, event: TOut) -> None:
+        """
+        Send one event to the remote end.
+
+        Raises:
+            Implementation-defined if called after :meth:`close` — a
+            session that has already closed cannot send further events.
+        """
+        ...
+
+    async def close(self, reason: CloseReason = CloseReason.COMPLETED) -> None:
+        """
+        End the session.
+
+        Idempotent — calling :meth:`close` more than once has no
+        additional effect beyond the first call.
+
+        Args:
+            reason: Why the session is ending. Defaults to
+                    `CloseReason.COMPLETED` — the handler-initiated,
+                    successful end of the session.
+        """
+        ...
+
+
+@runtime_checkable
+class SessionHandler(Protocol[TIn, TOut]):
+    """
+    Long-lived-connection driving-side contract.
+
+    Adapters satisfy this protocol structurally — no inheritance needed.
+    Any class with matching async `on_open`/`on_event`/`on_close` methods
+    satisfies `SessionHandler`.
+
+    Type parameters:
+        TIn:  The inbound event type this handler receives via `on_event`.
+        TOut: The outbound event type this handler sends via
+              `session.send()`.
+
+    Runtime check::
+
+        isinstance(handler, SessionHandler)          # ✓ works
+        isinstance(handler, SessionHandler[str, int]) # ✗ raises TypeError
+    """
+
+    async def on_open(self, session: Session[TOut]) -> None:
+        """
+        Called once when the session opens.
+
+        Returning normally accepts the session. Raising rejects it — the
+        exception flows through the same
+        `openframe.protocol.base.errors.categorize`/`build_envelope` path
+        every other inbound contract's failures do, so a reject looks
+        like any other mapped error to the caller, not a special case.
+
+        Args:
+            session: The newly opened session. `session.context` carries
+                     this session's `RequestContext`, stable for its
+                     whole lifetime.
+        """
+        ...
+
+    async def on_event(self, session: Session[TOut], event: TIn) -> None:
+        """
+        Called once per inbound event, in arrival order.
+
+        Never called at all for a one-directional transport (e.g. SSE,
+        which has no client-to-server events) — this is a valid, expected
+        lifecycle for such a handler, not a violation of the contract.
+
+        Args:
+            session: The open session this event arrived on.
+            event:   The inbound event.
+        """
+        ...
+
+    async def on_close(self, session: Session[TOut], reason: CloseReason) -> None:
+        """
+        Called exactly once when the session ends, however it ended —
+        normal completion, client disconnect, server shutdown, or an
+        unhandled error from `on_open`/`on_event`.
+
+        Args:
+            session: The now-closed session.
+            reason:  Why the session ended.
+        """
+        ...

{openframe_core-3.7.0 → openframe_core-3.8.0}/openframe/core/testing/__init__.py

@@ -29,6 +29,11 @@ Quick reference::
 
     use_case = EchoUseCase(response={"id": "1"})
     assert isinstance(use_case, UseCase)
+
+    from openframe.core.testing import InMemorySession, SessionHandlerContractTests
+
+    session = InMemorySession(context=RequestContext(correlation_id="t1"))
+    await my_session_handler.on_open(session)
 """
 from __future__ import annotations
 
@@ -37,6 +42,7 @@ from openframe.core.testing.contracts.graph_store import GraphStoreContractTests
 from openframe.core.testing.contracts.inbound import (
     CommandHandlerContractTests,
     QueryHandlerContractTests,
+    SessionHandlerContractTests,
     UseCaseContractTests,
 )
 from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
@@ -52,6 +58,7 @@ from openframe.core.testing.fakes.consumer import FakeConsumer
 from openframe.core.testing.fakes.graph_store import InMemoryGraphStore
 from openframe.core.testing.fakes.inbound import (
     EchoUseCase,
+    InMemorySession,
     SpyCommandHandler,
     SpyQueryHandler,
 )
@@ -68,6 +75,7 @@ __all__ = [
     "EchoUseCase",
     "SpyCommandHandler",
     "SpyQueryHandler",
+    "InMemorySession",
     "LifecycleContractTests",
     "PortContractTests",
     "RepositoryContractTests",
@@ -78,6 +86,7 @@ __all__ = [
     "UseCaseContractTests",
     "CommandHandlerContractTests",
     "QueryHandlerContractTests",
+    "SessionHandlerContractTests",
     "RemoteCommandClientContractTests",
     "RemoteQueryClientContractTests",
 ]

{openframe_core-3.7.0 → openframe_core-3.8.0}/openframe/core/testing/contracts/__init__.py

@@ -15,10 +15,11 @@ adding traverse-specific assertions — mirroring how ``BaseGraphStore``
 extends ``BaseRepository``.
 
 Inbound: ``UseCaseContractTests``, ``CommandHandlerContractTests``,
-``QueryHandlerContractTests`` mirror the outbound contract classes for
-the driving side of the hexagon. They do not build on any shared base
-class — ``UseCase``/``CommandHandler``/``QueryHandler`` do not extend
-``BasePort``.
+``QueryHandlerContractTests``, ``SessionHandlerContractTests`` mirror the
+outbound contract classes for the driving side of the hexagon. They do
+not build on any shared base class —
+``UseCase``/``CommandHandler``/``QueryHandler``/``SessionHandler`` do not
+extend ``BasePort``.
 
 No top-level pytest import — all modules here can be imported without
 pytest installed.
@@ -32,6 +33,7 @@ from openframe.core.testing.contracts.graph_store import GraphStoreContractTests
 from openframe.core.testing.contracts.inbound import (
     CommandHandlerContractTests,
     QueryHandlerContractTests,
+    SessionHandlerContractTests,
     UseCaseContractTests,
 )
 from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
@@ -55,6 +57,7 @@ __all__ = [
     "UseCaseContractTests",
     "CommandHandlerContractTests",
     "QueryHandlerContractTests",
+    "SessionHandlerContractTests",
     "RemoteCommandClientContractTests",
     "RemoteQueryClientContractTests",
 ]