Communication Surfaces

R2Kernel subsystem interfaces describe communication intent. Subsystem code uses the same contract whether both subsystems run on one host or the deployment places them on different hosts.

The runtime owns transport realization, route selection, and host-boundary policy. Those implementation choices are not part of the subsystem contract.

Semantic Surfaces

Surface	Use
Event	observations, state, telemetry, and fanout streams
Control	periodic commands with validity, deadline, and overrun semantics
Procedure	bounded request and response
Operation	long-running work with progress, cancellation, result, and terminal state

An API contract fixes the endpoint kind. A Procedure cannot substitute for a Control endpoint, and an Event publisher cannot be used as a request/response provider.

Host Boundary

The deployment may place a valid binding on one host or across multiple hosts. That placement changes latency, availability, and timing acceptance, but it does not change the declared API contract.

flowchart LR A["Subsystem A"] -->|"declared interface"| R["R2Kernel runtime"] R -->|"local or federated route"| B["Subsystem B"]

For a local route, the runtime selects a host-local data path. For a federated route, host control services establish the accepted remote path. Subsystems do not open ad hoc remote control listeners or encode host topology into application logic.

The runtime reports whether a provider route is available. A consumer with a declared binding remains WaitingTarget until its selected provider can be resolved.

Event

Event is the observation and fanout surface.

publishers publish one declared Event endpoint
subscribers bind to that endpoint
one publisher may have multiple subscribers
delivery status and timing are observable through runtime status
Event is not a reliable substitute for command acknowledgement

Event payloads remain domain messages. Acquisition, publication, and reception times are carried by the public runtime envelope when required.

Control

Control is a point-to-point periodic command surface. Its contract may declare:

expected period
validity and deadline behavior
late handling
priority
request and response message types

A required Control binding selects one provider. Use an explicit higher-level mirror or fanout subsystem when one command must be applied to multiple targets.

Procedure And Operation

Procedure is intended for bounded calls such as configuration, status queries, or discrete actions.

Operation is intended for work that outlives one request. It exposes start, progress, state, cancellation, and terminal result according to its API contract. Operation progress does not create a new public interface for every invocation.

Browser And External Clients

Browsers and outside-runtime tools use the Host Control API rather than native subsystem transport.

/api/v1/ws/events observes declared Event endpoints
/api/v1/ws/control invokes supported Procedure and Operation endpoints
REST routes provide host status, configuration, package, and lifecycle APIs

This facade is an integration boundary. It does not expose synchronized Control execution or native transport ownership to browser code.

Practical Rule

subsystem authors declare semantic interfaces
deployment authors select instances and bindings
the runtime owns route realization
operators validate availability, timing, and health through runtime status
external clients use the documented Host Control API