# Relay Runtime Contract

## Contract Metadata

```json
{
  "subsystem_id": "relay-runtime",
  "lane": "L7",
  "contract_file": "docs/release-control/v6/internal/subsystems/relay-runtime.md",
  "status_file": "docs/release-control/v6/internal/status.json",
  "registry_file": "docs/release-control/v6/internal/subsystems/registry.json",
  "dependency_subsystem_ids": []
}
```

## Purpose

Own the desktop and mobile relay runtimes, their persisted relay state
boundaries, the server-owned mobile relay capability boundary, and the
canonical reconnect, encryption, protocol, proxy, and relay-trust behavior
for Pulse instance bridging.

## Canonical Files

1. `internal/relay/client.go`
2. `internal/relay/protocol.go`
3. `internal/config/persistence_relay.go`
4. `internal/api/relay_mobile_capability.go`
5. `pulse-mobile:src/relay/client.ts`
6. `pulse-mobile:src/relay/protocol.ts`
7. `pulse-mobile:src/relay/proxy.ts`
8. `pulse-mobile:src/relay/encryption.ts`

## Shared Boundaries

1. `internal/api/relay_mobile_capability.go` shared with `api-contracts`: the backend-owned Pulse Mobile relay capability inventory is both a relay runtime boundary and a canonical API payload contract surface.

## Extension Points

1. Add or change desktop relay reconnect, registration, drain, proxy-stream, or encrypted channel behavior through `internal/relay/`
2. Add or change relay control payload schemas, including mobile-visible push notification metadata, through `internal/relay/protocol.go`
3. Add or change persisted relay enablement, server URL, or reconnect-safe default loading through `internal/config/persistence_relay.go`
   `LoadRelayConfig` must apply environment-variable overrides
   (`PULSE_RELAY_ENABLED`, `PULSE_RELAY_SERVER`) on top of the file-loaded
   or default-fallback `relay.Config` via `relay.ApplyEnvOverrides`. The
   env overrides must distinguish unset / empty / unparseable values
   (file or default wins) from explicit `true`/`false`/valid-URL values
   (env wins), and must reject invalid `PULSE_RELAY_SERVER` URLs through
   the canonical `validateRelayServerURL` check rather than silently
   accepting a malformed override. Saving the resulting `relay.Config`
   from the UI is allowed to persist the env-effective state to disk;
   the override is not stripped before save.
4. Add or change the backend-owned mobile relay capability inventory and compatibility scope mapping through `internal/api/relay_mobile_capability.go`
5. Add or change mobile relay reconnect, drain, channel, encryption, proxy, or identity behavior through `pulse-mobile:src/relay/`
6. Keep desktop and mobile relay changes aligned with the governed server relay surfaces represented by the L7 lane evidence

## Forbidden Paths

1. Reintroducing relay client trust or TLS handling through ad hoc dialer configuration outside the canonical relay client
2. Letting encrypted DATA frames race ahead of nonce-order guarantees by deferring inbound decrypt work to background goroutines
3. Treating a missing persisted relay config file as a hard failure instead of falling back to the canonical disabled default

## Completion Obligations

1. Update this contract when new desktop relay runtime or persistence entry points become canonical
2. Keep relay desktop runtime changes tied to explicit proof in
   `internal/relay/client_test.go` and `internal/relay/encryption_test.go`
3. Keep persisted relay config loading tied to explicit proof in `internal/config/persistence_relay_test.go`
4. Keep backend-owned mobile capability inventory changes tied to explicit proof in `internal/api/relay_mobile_capability_test.go`
5. Keep mobile relay runtime changes tied to explicit proof in `pulse-mobile:src/relay/__tests__/`

## Current State

The relay lane had been carrying real desktop and mobile runtime behavior
without fully explicit subsystem ownership even though L7 already treats relay
readiness as a governed release lane. This contract makes both relay-runtime
boundaries explicit.
The canonical relay runtime now includes local CA-bundle trust via
`SSL_CERT_FILE`, so self-hosted relay deployments can use a private CA without
forking the dial path or disabling TLS verification globally.
Inbound DATA handling is also part of this boundary: encrypted relay frames
must be decrypted before they are handed to background stream handlers so the
channel nonce guard stays monotonic and relay arrival order cannot trip false
replay failures under concurrency.
Relay channel key derivation is part of that same encryption boundary. The
X25519 shared secret may not feed the generic nil-salt HKDF form: desktop
relay runtime must domain-separate the channel KDF with the relay-owned salt
`pulse-relay-e2e-channel-v1` together with the existing directional info
strings before deriving AES-GCM keys.
Relay status truthfulness is part of the same contract. If the client is in a
governed reconnect or license-pause window, `ClientStatus.reconnect_in` must
reflect that delay instead of silently presenting a disconnected state with no
retry timing.
Relay push notification identity is part of this same owned contract. The
canonical `PUSH_NOTIFICATION` payload must carry the authoritative
`instance_id` when the desktop relay client serializes it so multi-pairing
mobile routing and repair flows cannot reinterpret a queued approval or
finding against whichever instance happens to be active later.
The relay HTTP proxy boundary is also part of this owned surface. Relay DATA
requests must normalize outer method/path whitespace before building the local
Pulse API request so trivial spacing drift does not cause a valid proxied
operation to fail at the desktop boundary. The same normalization rule applies
to allowlisted proxy header names, so safe headers like `Content-Type` are not
silently stripped just because the upstream frame wrapped them in outer
whitespace. That same proxy boundary also owns per-channel abuse control: one
relay channel may not consume an unbounded share of the local HTTP proxy, so
desktop relay runtime must enforce a channel-local request budget and fail
excess DATA frames with owned proxy backpressure instead of letting one
channel starve the rest of the connection.
Persisted relay config loading is part of the same owned surface. A missing
`relay.enc` file must fall back cleanly to the canonical disabled default so a
fresh v6 install or a partially migrated instance does not fail closed just
because relay settings have never been saved.
That same persistence boundary also owns relay client secrets at rest:
`relay.enc` may only accept plaintext relay config as migration input. Once
the runtime can read legacy plaintext relay settings, it must rewrite
canonical encrypted storage immediately on load instead of leaving
`instance_secret` or the relay identity private key on disk as a normal
runtime path.
The mobile relay runtime is part of the same owned surface: reconnect drain
failover hints are one-shot recovery instructions, not permanent relay URL
overrides, so a successful failover reconnect must return future reconnects to
the instance's canonical relay URL unless the server sends a fresh drain hint.
The server-owned mobile relay capability boundary is part of that same owned
surface too. The dedicated `relay:mobile:access` credential may only reach the
explicit runtime route inventory in `internal/api/relay_mobile_capability.go`,
and expanding that inventory is governed L7 work rather than a router-local
compatibility tweak.
The route that mints that dedicated credential is also part of the paid Relay
boundary. `POST /api/security/tokens/relay-mobile` lives in the shared
auth/security router, but it must require the paid `relay` entitlement before
creating a `relay:mobile:access` token so Community installs cannot bypass
Relay/mobile gating through direct API calls.