Channel Semantics

Why this exists

AdaOS must not start from transport choices such as WebSocket, WebRTC, HTTP/2, or WebTransport. It must start from the semantics that each logical flow requires.

This document fixes the target model for channel semantics before transport refactors.

Design rules

A transport is an implementation detail.
A logical channel must declare its delivery semantics explicitly.
Reliability is applied only where the message class requires it.
Ordering, replay, buffering, and backpressure policy are channel properties, not side effects of a socket library.
At any moment in time, each logical stream has one authority path unless multipath is explicitly designed.

Message taxonomy

AdaOS traffic is split into message classes, not only subject prefixes.

Command

Use for imperative actions that change state.

Examples:

lifecycle transitions
update orchestration
route decisions
integration actions with side effects

Required fields:

message_id
channel_id
authority
issued_at
ttl_ms

Semantics:

usually acknowledged
may require idempotency
replay depends on command subtype

Request

Use for point-to-point ask/answer interactions.

Examples:

fetch hub release state
resolve route
request snapshot

Semantics:

correlated with request_id
timeout-bound
retries allowed only if request is idempotent

Response

Use for replies to a request.

Semantics:

correlated to a single request
usually non-replayable after request timeout
may be dropped if requester no longer owns the session

StateReport

Use for durable reports of local state.

Examples:

hub lifecycle status
core update progress
integration backlog status

Semantics:

last-write-wins or versioned
replayable within a bounded window
duplicate-safe by design

Event

Use for observable domain facts that may fan out.

Examples:

subnet.draining
scenarios.synced
integration notifications

Semantics:

not always acknowledged
may be durable or ephemeral depending on subtype
fanout policy must be declared

SyncUpdate

Use for replicated state deltas such as Yjs document updates.

Semantics:

replayable within a bounded window
persistence policy defined by the sync engine
transport must not reinterpret the payload

Presence

Use for liveness and ephemeral membership hints.

Examples:

online/offline hints
awareness state
cursor hints

Semantics:

explicitly ephemeral
drop allowed
no durable replay

RouteFrame

Use for proxied request or stream frames crossing a relay boundary.

Examples:

browser -> hub HTTP proxy frame
root route tunnel messages

Semantics:

may be ordered per logical stream
backpressure-sensitive
replayability depends on the wrapped logical flow, not on the frame itself

MediaFrame

Use for audio/video or other latency-sensitive stream chunks.

Semantics:

usually non-durable
loss-tolerant
congestion-aware
never shares critical reliability assumptions with control traffic

Semantic channel types

AdaOS transport abstraction should be built around these channel types.

CommandChannel

Properties:

ordered per command stream
acknowledged
idempotency required for retryable commands
optional bounded replay

EventChannel

Properties:

fanout-capable
may be durable or ephemeral
ordering only where consumers require it

SyncChannel

Properties:

versioned or cursor-based
replayable within bounded window
snapshot + diff capable

PresenceChannel

Properties:

best-effort
non-durable
drop allowed under pressure

RouteChannel

Properties:

stream-oriented
relay-aware
explicit buffering and backpressure policy

MediaChannel

Properties:

latency-first
usually unordered or partially ordered
transport-specific congestion handling

Delivery classes

Each message type must also declare a delivery class.

Class A: Must Not Lose

Examples:

lifecycle transitions
update orchestration
critical task state transitions
durable integration actions

Requirements:

durable outbox
ack
bounded replay
dedupe
idempotency or exactly-once effect guard

Class B: Nice To Replay

Examples:

state reports
non-critical event history
bounded route recovery metadata

Requirements:

bounded retention
replay window
duplicate-safe consumers preferred

Class C: Drop Allowed

Examples:

presence
awareness
transient UI hints
media frames

Requirements:

no durable queue
no replay guarantee
backpressure may drop

Channel contract checklist

Every new logical channel in AdaOS must answer these questions:

Which message taxonomy class does it carry?
Who is the authority for that channel?
Is the channel durable or ephemeral?
Is replay required, optional, or forbidden?
Is ordering required?
What is the ack model?
What is the max backlog?
What happens in degraded mode?
What happens on reconnect?
What path owns the stream after failover?

What this means for current AdaOS

hub <-> root control traffic must be modeled as CommandChannel, StateReport, and selected EventChannel flows.
route.to_hub.* and route.to_browser.* are RouteChannel traffic, not generic control traffic.
Yjs document replication is SyncChannel.
browser awareness is PresenceChannel.
audio/video is MediaChannel.

This classification is the prerequisite for transport hardening and sidecar adoption.