Repository navigation
Closed
Labels
mailbox-phase-1Mailbox foundations and protocol decisionsMailbox foundations and protocol decisionsmailboxesSigned pass-by-value mailbox programSigned pass-by-value mailbox programresearchResearch, assessment, or design-exploration workResearch, assessment, or design-exploration work
Description
Parent: #4622
Outcome
Record the durable architecture and threat-model decisions for MVM mailboxes before protocol or runtime implementation begins. The ADR must preserve pass-by-value isolation, host-blind payloads, bounded work, and standalone mvm operation.
Repository ownership decision
- Place canonical mailbox identifiers, addresses, message kinds, envelopes, delivery outcomes, and receipts in a new
mvm-contract::protocol::mailboxmodule. - Keep the contract DTO surface
no_std + alloccompatible and free of transport, storage, coordinator, and cryptographic-I/O implementations. - Place signing, encryption, verification, local queueing, leasing, deduplication, and durability in MVM runtime crates selected by the ADR.
- Keep organization, fleet, node, instance, placement generation, route hints, and coordinator RBAC types in
mvmdwrappers. - Preserve the acyclic dependency direction:
mvmddepends onmvm-contract;mvmnever depends onmvmd-types. - Treat the existing
mvmd-types/src/mailbox.rsandmvmd-coremailbox/crypto code as prototype evidence to audit and migrate, not a contract to copy unchanged.
Decisions to record
callwaits for a correlated reply until its deadline; timeout does not prove that the remote handler did not execute.casthas no application reply and returns after local validation and admission; a full or unauthorized local mailbox is rejected synchronously.- An accepted message is never silently discarded. Any intentionally lossy operation has a distinct
best_effort_castcontract. - Delivery is at-least-once with stable message IDs and receiver deduplication, not general exactly-once delivery.
- Ordering is scoped per sender/mailbox stream; no global total order is implied.
- Workload root/control and user/control mailboxes are durable by default; explicitly transient child mailboxes are ephemeral by default.
- Process identity, mailbox identity, boot identity, execution epoch, and transport identity are separate concepts.
- Ordinary hosts and relays may route ciphertext and bounded metadata but cannot read payloads, forge senders, or mint acceptance receipts.
- Backpressure, expiry, partitions, restart, late replies, poison messages, dead letters, links, monitors, and signed failure observations have bounded semantics.
Acceptance criteria
- A reviewed ADR in
mvmdefines the identities, trust boundaries, delivery and ordering guarantees, durability classes, and failure model. - The ADR defines
call,cast, optionalbest_effort_cast, cancellation, timeout ambiguity, late replies, and full-mailbox behavior. - The ADR defines links, monitors, supervision observations, restart epochs, and the limits of distributed failure detection.
- The ADR identifies which metadata remains visible in the host-blind profile and which claims require confidential-computing hardware.
- The ADR assigns stable interfaces to
mvmand treatsmvmd, Iroh, relays, and future overlays as replaceable components. - The ADR includes a type-by-type ownership matrix for the existing
mvmdmailbox types and identifies the MVM runtime crate responsible for each non-DTO behavior. - The ADR states where mailbox plaintext may exist in each assurance tier and forbids ordinary
mvmdcoordinator processes from decrypting host-blind production payloads. - The ADR defines compatibility handling for existing
mvmdAPI clients and persisted mailbox records, including the evidence required to declare the old format disposable. - Program: signed pass-by-value mailboxes for workload, host, and user messaging #4622 links the accepted ADR and reflects every decision above.
Metadata
Metadata
Assignees
Labels
mailbox-phase-1Mailbox foundations and protocol decisionsMailbox foundations and protocol decisionsmailboxesSigned pass-by-value mailbox programSigned pass-by-value mailbox programresearchResearch, assessment, or design-exploration workResearch, assessment, or design-exploration work
Activity
auser commentedon Oct 26, 2026
Done by #4691: ADR-057 defines the identities, trust boundaries, delivery and ordering, durability, failure model, call/cast semantics, supervision and restart epochs, host-blind metadata limits, and the stable mvm-owned interfaces. Linking ADR-057 from #4622's body is a tracker edit left to the program owner.