DDR-0035: Session Owner Replacement and Authoritative Event Gating

Status
  Approved

Context
  ADR-0104 establishes that Session singularity is an ownership and lifecycle invariant, not a
  singleton pattern. This DDR defines the concrete implementation rules the Session owner must
  follow to enforce that invariant safely and predictably.

  The “owner” is the component responsible for creating, holding, and replacing Session instances
  (e.g., Client object, ConnectionManager, or Home Assistant integration layer).

Problem
  When reconnects, failures, or configuration changes occur, multiple Session objects may exist
  transiently. Without explicit rules, this can lead to:
    - Events emitted from a stale (superseded) Session
    - Races during reconnect
    - Ambiguous authority over shared application state

Decision
  The Session owner MUST enforce the following rules:

  1. Single Authoritative Session Reference
     - The owner maintains exactly one reference to the “current” (authoritative) Session.
     - All application-facing event handling MUST be sourced from this reference only.

  2. Atomic Replacement
     - Replacing a Session MUST be an atomic operation from the owner’s perspective:
         a) Create new Session instance
         b) Register event sinks / callbacks against the new Session
         c) Swap the authoritative Session reference
         d) Initiate close/cancel of the old Session
     - At no point may two Sessions be considered authoritative simultaneously.

  3. Authoritative Event Gating
     - The owner MUST gate inbound events by Session identity.
     - Events originating from any Session that is not the current authoritative Session MUST be
       ignored or discarded.
     - Session objects MUST NOT attempt to self-police authority via global state.

  4. Explicit Retirement
     - When a Session is superseded, the owner MUST explicitly close or cancel it.
     - Closing a Session is idempotent and MUST NOT affect the new Session.

  5. No Global State
     - The owner MUST NOT rely on global variables or module-level singletons to track session
       authority.
     - Authority is always determined by the owner’s current Session reference.

Rationale
  - Makes session replacement explicit and observable.
  - Prevents stale or duplicate events during reconnects.
  - Keeps Session implementation simple and responsibility-limited (DDR-0034).
  - Ensures deterministic behavior under failure, reconnect, and test scenarios.

Consequences
  Positive
    - Clear, testable ownership semantics.
    - Safe reconnect behavior without race conditions.
    - Enables concurrent “old” and “new” Session objects during transition without ambiguity.

  Tradeoffs
    - Slightly more bookkeeping in the owner.
    - Requires discipline in event routing and reference swapping.

Implementation Notes (Non-normative)
  - Owners typically implement replacement with:
      - a private “current_session” attribute
      - a small helper method such as _replace_session(new_session)
  - Tests should assert that:
      - events from retired Sessions are ignored
      - only the current Session drives state updates

Related Records
  - ADR-0104: Session Singularity Is an Ownership Constraint, Not a Singleton Pattern
  - DDR-0034: Session Responsibility Boundaries
