kuilt-core/us.tractat.kuilt.core.fabric/Mesh

Mesh

A Seam over a fully-connected N-peer mesh of point-to-point Connections, with support for admitting links that arrive after construction.

Obtain one from meshSeam. Beyond the Seam contract it adds addLink for dynamic peer-join, and it is a PrincipalRoster: host-verified principals attached to admitted connections (via us.tractat.kuilt.core.withPrincipal) are observable per peer, maintained atomically with the link set.

Properties

attestedPrincipals

abstract val attestedPrincipals: StateFlow<Map<PeerId, Principal>>

Host-verified principals of currently-linked peers, keyed by the PeerId each was verified against at admission. Peers with no attestation are absent. An entry is removed when its peer's link drops; the map empties when the seam tears down.

capability

open val capability: StateFlow<TransportCapability>

Live capability of the fabric carrying this session — its role(s) and whether it is usable right now. Updates as radios, permissions, and network paths change.

incoming

abstract val incoming: Flow<Swatch>

Frames received from peers, in send order, delivered to a single collector. Cold/single-collection semantics: collect once per Seam; fan-out consumers wrap with shareIn. A second concurrent collector is unsupported and will race.

maxPayloadBytes

open val maxPayloadBytes: Int?

The largest payload a single broadcast or sendTo may carry, or null when this seam cannot tell.

peers

abstract val peers: StateFlow<Set<PeerId>>

Live set of peers currently connected. Includes selfId.

plies

open val plies: StateFlow<Map<PlyId, SeamState>>

Per-ply lifecycle breakdown. Single-ply fabrics report a one-entry map keyed by PlyId.Sole. Invariant: state.value equals the rollup of plies.value.values under "any ply Woven ⇒ Woven".

selfId

abstract val selfId: PeerId

This peer's own identifier.

state

abstract val state: StateFlow<SeamState>

The fabric's lifecycle as observed by this peer.

Functions

addLink

abstract suspend fun addLink(conn: Connection)

Admit a Connection to a peer that dialed in after construction.

broadcast

abstract suspend fun broadcast(payload: ByteArray)

Send to all other peers. Suspends until accepted by the local transport.

abstract suspend fun close(reason: CloseReason = CloseReason.Normal)

Disconnect from the session. Idempotent.

raceCollapse

suspend fun <T> Seam.raceCollapse(abortWhen: (Set<PeerId>) -> Boolean = { it.size < 2 }, body: suspend () -> T): T

Run body but abort it with a SeamCollapsedException the instant this Seam collapses mid-operation — either the fabric latches SeamState.Torn (transport tear) OR the live peer set satisfies abortWhen (membership drain). Whichever of body, the tear, or the drain resolves first wins; the losers are cancelled.

sendTo

abstract suspend fun sendTo(peer: PeerId, payload: ByteArray)

Send to one peer. Suspends until accepted by the local transport.