# Connection Runtime

The connection runtime is shared by web and mobile. It owns connectivity,
authentication, retries, transport lifetime, cached environment data, and
environment-scoped operations.

Web and mobile mount this runtime once at the application root. There is no
legacy connection owner or supported mixed mode.

## Ownership

Each registered environment has one scoped Effect `Context` containing focused
services:

- `EnvironmentSupervisor` owns desired state, retry scheduling, and the active
  session scope.
- `ConnectionBroker` prepares credentials and endpoints for primary, bearer,
  relay, and SSH targets.
- `RpcSessionFactory` performs one transport attempt. It does not retry.
- `EnvironmentRpc` exposes the active session without leaking the transport.
- `EnvironmentProjectCommands` and `EnvironmentThreadCommands` construct
  orchestration commands, IDs, and timestamps.
- `EnvironmentShell` and `EnvironmentThreads` own live subscriptions and cached
  snapshots.

`EnvironmentServicesFactory` assembles that context, and `EnvironmentRegistry`
owns its scope. There is no aggregate environment runtime facade. React
components do not create connections, transports, retry loops, or RPC clients.

## Connection State

The supervisor is the only retry owner.

1. A persisted or platform registration marks an environment as desired.
2. If the device is offline, the supervisor releases the active session and
   waits without consuming retry attempts.
3. When online, the supervisor asks the broker for one prepared connection and
   asks the session factory for one RPC session.
4. Transient failures retry forever with exponential backoff capped at 16
   seconds.
5. Connectivity changes, application activation, credential changes, and
   explicit user retry interrupt the current wait and trigger a fresh attempt.
6. Authentication or configuration failures remain blocked until an external
   wakeup changes the relevant input.
7. An involuntary session close keeps the registration and cache, then retries.
8. Explicit removal closes the session and deletes the registration,
   credentials, shell cache, and thread cache.

The UI derives `available`, `offline`, `connecting`, `reconnecting`,
`connected`, and `error` from supervisor state plus explicit data-sync state.
It does not infer connection health from cached data or the existence of a
transport object. An environment becomes `connected` after the socket opens and
the initial config RPC succeeds, proving that the server is responsive. Shell
and thread synchronization are independent data states. A healthy RPC
transport with a failed shell subscription is shown as connected with a
synchronization error, not as a reconnect that is not actually scheduled.

## Data Boundary

Finite requests, durable subscriptions, and commands are separate APIs:

- Query atoms revalidate when the RPC generation changes.
- Subscription atoms switch to replacement sessions.
- Expected subscription failures update domain sync state and wait for a
  replacement session; they do not take down a healthy transport.
- Mutations resolve the current environment runtime at execution time.
- Shell and thread snapshots are available while offline.
- A connected transport may have `empty`, `cached`, `synchronizing`, `live`, or
  failed shell and thread data independently.
- Cached shell and thread projections are never allowed to overwrite newer live
  data during a fast reconnect.
- Domain atom factories route effects through the environment registry and
  resolve the current scoped service at execution time.
- Web and mobile own their Atom runtimes, React hooks, and feature composition.

The Promise bridge exists only at the React/Atom boundary. Runtime and business
logic remain Effect-native.

## Platform Layers

Web and mobile provide:

- network status and network-change streams;
- application lifecycle wakeups;
- cloud session credentials;
- device identity;
- platform registrations;
- persistent catalog, credential, shell, and thread stores;
- HTTP, crypto, and telemetry layers.

Platform layers adapt operating-system capabilities. They do not implement
connection policy.

## Source Boundaries

The public package subpaths mirror the runtime layers:

- `connection/core` contains state, catalog, retry policy, and connectivity.
- `connection/transport` contains brokerage, authorization, attempts, and RPC
  sessions.
- `connection/platform` declares capabilities and persistence contracts.
- `connection/services` contains environment-scoped data services.
- `connection/application` assembles registries, discovery, and startup.
- `connection/atoms` adapts shared services to application-owned Atom runtimes.
- `connection/presentation` contains pure UI projections.

Other reusable state lives in domain subpaths such as `shell`, `threads`,
`terminal`, and `vcs`. Applications must import explicit package subpaths; the
package intentionally has no root export.

## Application Boundary

The application root mounts the shared connection application layer, creates
its own Atom runtime, and selects the domain atom factories required by that
platform. Web and mobile may expose different hooks and features without
changing connection ownership.

Application code must not construct `WsTransport`, RPC clients, retry loops, or
raw orchestration commands. Persistence paths belong to the platform
registration and cache stores, with explicit migration or invalidation policy.

## Verification

Core state-machine tests use `@effect/vitest` and deterministic service layers.
Required coverage includes:

- offline startup and online wakeup;
- forever retry with the 16-second cap;
- explicit retry interrupting backoff;
- authentication wakeups;
- involuntary close and reconnect;
- explicit removal clearing all owned state;
- relay token reuse and refresh;
- progressive relay discovery;
- shell and thread cache hydration;
- durable subscriptions switching sessions;
- command metadata and idempotent queued-command metadata.