Skip to content

Define mailbox peer overlay and transport interfaces #4632

Closed

Description

@auser

Parent: #4622

Depends on #4627.

Outcome

Define separate mailbox overlay and byte-transport interfaces so logical MVM identity, route selection, and authorization remain independent from Iroh, HeatNet/UOR, QUIC, relays, and IP addressing.

The interfaces carry canonical mvm-contract::protocol::mailbox envelopes or bounded encoded bytes. They do not expose mvmd-types as protocol authority; mvmd route hints and placement records adapt into the overlay interface at the fleet boundary.

Scope

  • PeerOverlay-equivalent behavior for resolving a stable mailbox or MVM identity to authorized route candidates.
  • PeerTransport-equivalent behavior for authenticated connection establishment, bounded reliable streams, path classification, cancellation, and shutdown.
  • An explicit boundary marker that routes any TUN/L3 or packet/frame implementation back to Research: evaluate per-VM vsock NIC adapters for vnet/HeatNet and SpiralCore #4607; this mailbox issue does not define or implement a virtual NIC.
  • Rotatable transport bindings certified for an MVM identity, tenant, assurance tier, policy epoch, and validity window.
  • In-memory implementations for deterministic protocol, partition, reconnection, and failure tests.

Acceptance criteria

  • Mailbox protocol code depends on stable overlay/transport interfaces rather than concrete Iroh or HeatNet types.
  • MVM, mailbox, execution, and transport identities cannot be accidentally substituted for one another.
  • Authorization is enforced above the transport; successful connection establishment is not sufficient authority to deliver a message.
  • Direct, relayed, reconnecting, partitioned, refused, and shutting-down paths have deterministic conformance tests.
  • The interfaces expose bounded backpressure and cancellation without requiring a repository-wide async-runtime change.
  • Prior mvmd AgentTransport work is documented as related implementation experience, not imported as a runtime dependency.
  • The interface cannot be used to smuggle arbitrary packet forwarding into the mailbox authority or bypass Research: evaluate per-VM vsock NIC adapters for vnet/HeatNet and SpiralCore #4607's virtual-NIC decision.
  • A conformance adapter demonstrates that optional mvmd routing metadata can select a path without changing, decrypting, or re-signing the canonical envelope.

Activity

  1. added
    enhancementNew feature or request
    mailboxesSigned pass-by-value mailbox program
    mailbox-phase-1Mailbox foundations and protocol decisions
    on Oct 22, 2026
  2. reopened this on Oct 26, 2026
  3. auser commented on Oct 26, 2026

    @auser
    CollaboratorAuthor

    Delivered by #4698. Checked against main: the PeerOverlay/PeerTransport traits and AuthorizedMailboxFrame are in crates/mvm-core/src/mailbox/transport.rs; distinct identity newtypes; authorization is above the transport (authenticated_connection_is_not_mailbox_authority); direct, relay, reconnect, partition, refusal and shutdown cases have deterministic tests in transport/tests.rs; bounded ChannelLimits plus a CancellationToken with no async runtime; AgentTransport is recorded in ADR-057; there is no packet or TUN API; and MvmdRouteHint selects a route without re-signing the envelope. Verified by reading code and test names, not by re-running the suite.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmailbox-phase-1Mailbox foundations and protocol decisionsmailboxesSigned pass-by-value mailbox program

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions