Wire contract

contract/asyncapi.yaml is the normative source for messages, required fields, connection rules, and the command registry. The generated page is a projection for reading; edit the YAML, not the projection.

Connection sequence

sequenceDiagram participant G as Classic Mac guest participant H as macOS host G->>H: TCP connect G->>H: hello (identity, revision, capabilities) alt compatible revision H-->>G: hello.accept loop while connected G->>H: ping H-->>G: pong H->>G: request G-->>H: result or refusal end G-->>H: bye else incompatible revision H-->>G: hello.refuse H--xG: close end

Text equivalent: the guest dials, identifies itself and its contract revision, and waits for acceptance. Only then may either side exchange application messages. Heartbeats keep the session observable. A graceful side sends bye; incompatible revisions are refused before normal traffic.

Frame and lane rules

An eight-byte header identifies channel, flags, transfer, and payload length. JSON control frames and raw bulk frames are multiplexed. Control words queue and retry; bulk data is recoverable and may be abandoned only at a frame boundary. One transfer owns the bulk lane at a time.

File transfer

sequenceDiagram participant S as Sender participant R as Receiver S->>R: file.offer or file.request R-->>S: accept or refuse loop framed bulk data S->>R: bulk frame R-->>S: file.progress (advisory) end S->>R: file.end R-->>S: receiver result

Text equivalent: the initiator proposes one transfer, the receiver accepts or refuses, bulk frames follow, and only receiver-originated progress proves bytes arrived. Completion is receiver-owned; a sender's socket acceptance is not delivery evidence.

Compatibility rule

Fields are additive unless a revision explicitly changes meaning. Unknown enum values are not consent. Every local $ref must resolve, every behavior change begins in the contract, and both receiving directions must retain the same meaning.

Mirror invalidation

mirror.invalidate is an optional symmetric notification, not a command and not authoritative state. It identifies one session and the newest known overall and per-domain generations, with quality and loss information. The receiver coalesces refresh work, repairs gap or unknown quality, and keeps cadence polling as the fallback. A hint can make a read happen sooner; only a coherent reread can publish the new state.

sequenceDiagram participant G as Guest state owner participant H as Host projection G->>H: mirror.invalidate (session, generations, quality) H->>H: coalesce and admit refresh H->>G: bounded scene and domain reads G-->>H: authoritative generation-tagged state H->>H: publish only a coherent current set

Text equivalent: the guest hints that one or more generations changed; the host coalesces and schedules bounded reads, receives authoritative tagged state, and publishes only when the generation set is coherent and current.