Rust Specification

Introduction

This document specifies implementation details for the Rust implementation of roam. These details are NOT required for implementations in other languages — Swift, TypeScript, etc. get their types and method identities from code generated by the Rust proto crate.

Method Identity

Every method has a unique 64-bit identifier computed from its service name, method name, and signature.

method_id = blake3(kebab(ServiceName) + "." + kebab(methodName) + sig_bytes)[0..8]

This means:

• Renaming a service or method changes the ID (breaking change)
• Changing the signature changes the ID (breaking change)
• Case variations normalize to the same ID (loadTemplate = load_template)

Signature Hash

The sig_bytes used in method identity is a BLAKE3 hash of the method's structural signature. This is computed at compile time by the #[roam::service] macro using facet type introspection.

The canonical representation encodes the method signature as a tuple (see r[signature.method] below). Each type within is encoded recursively:

Primitive Types

Container Types

Note: These are wire-format types, not Rust types. Vec, VecDeque, and LinkedList all encode as List. HashMap and BTreeMap both encode as Map.

Struct Types

0x30 + varint(field_count) + (field_name + field_type)*

Note: The struct's name is NOT included — only field names and types. This allows renaming types without breaking compatibility.

Enum Types

0x31 + varint(variant_count) + (variant_name + variant_payload)*

Variants MUST be encoded in declaration order.

Method Signature Encoding

0x25 + varint(arg_count) + encode(arg1) + ... + encode(argN) + encode(return_type)

This structure ensures unambiguous parsing — without the argument count, fn add(a: i32, b: i32) -> i64 would have the same bytes as fn foo(a: i32, b: i32, c: i64) (which returns unit).

Example

For a method:

async fn add(&self, a: i32, b: i32) -> i64;

The canonical bytes would be:

0x25          // Tuple tag (method signature)
0x02          // 2 arguments
0x09          // a: i32
0x09          // b: i32
0x0A          // return: i64

BLAKE3 hash of these bytes gives sig_bytes.

Introspection Types

The Diagnostic service uses these types for introspection and debugging. Type information uses facet::Shape directly rather than a parallel type system.

struct ServiceDetail {
    name: Cow<'static, str>,
    methods: Vec<MethodDetail>,
    doc: Option<Cow<'static, str>>,
}

struct MethodDetail {
    service_name: Cow<'static, str>,
    method_name: Cow<'static, str>,
    args: Vec<ArgDetail>,
    return_type: &'static Shape,  // facet Shape, not TypeDetail
    doc: Option<Cow<'static, str>>,
}

struct ArgDetail {
    name: Cow<'static, str>,
    ty: &'static Shape,  // facet Shape
}

struct ServiceSummary {
    name: Cow<'static, str>,
    method_count: u32,
    doc: Option<Cow<'static, str>>,
}

struct MethodSummary {
    name: Cow<'static, str>,
    method_id: u64,
    doc: Option<Cow<'static, str>>,
}

enum MismatchExplanation {
    /// Service doesn't exist
    UnknownService { closest: Option<Cow<'static, str>> },
    /// Service exists but method doesn't
    UnknownMethod { service: Cow<'static, str>, closest: Option<Cow<'static, str>> },
    /// Method exists but signature differs
    SignatureMismatch { 
        service: Cow<'static, str>,
        method: Cow<'static, str>,
        expected: MethodDetail,
    },
}

Using Shape for Type Introspection

Instead of a custom TypeDetail enum, roam uses facet::Shape directly. Use facet_core to inspect shapes:

• shape.def reveals if it's a struct, enum, list, option, etc.
• shape.type_params gives generic parameters
• shape.scalar_type() returns the scalar type for primitives
• roam_schema::classify_shape() provides high-level classification for codegen

Helper functions in roam_schema:

• is_tx(shape) / is_rx(shape) — check for streaming types
• is_stream(shape) — check for any streaming type
• contains_stream(shape) — recursively check for streams
• is_bytes(shape) — check for Vec<u8> or &[u8]

Usage

When Diagnostic.explain_mismatch returns SignatureMismatch, the client can diff its local MethodDetail against the expected field to show exactly where the types diverge:

Method `TemplateHost.load_template` signature mismatch:
  arg `context_id`: expected ContextId { id: u64 }
                        got ContextId { id: u32 }
                                           ^^^

Wire Type Mappings

Certain roam types have special wire representations that differ from their Rust representation.

// Method signature:
async fn process(&self, input: Stream<Chunk>) -> Stream<Result>;

// Wire encoding of arguments: just the stream ID
// payload = postcard::to_vec(&(input_stream_id: u64))?;

// Wire encoding of response: just the stream ID
// payload = postcard::to_vec(&Result::<u64, RoamError<Infallible>>::Ok(output_stream_id))?;

#[derive(Facet)]
pub enum RoamError<E> {
    User(E),         // discriminant 0
    UnknownMethod,   // discriminant 1
    InvalidPayload,  // discriminant 2
    Cancelled,       // discriminant 3
}

async fn get_user(&self, id: UserId) -> Result<User, UserError>;

async fn get_user(&self, id: UserId) -> Result<User, RoamError<UserError>>;

match client.get_user(id).await {
    Ok(user) => { /* success */ }
    Err(RoamError::User(e)) => { /* application error: e */ }
    Err(RoamError::UnknownMethod) => { /* protocol version mismatch? */ }
    Err(RoamError::Cancelled) => { /* we or they cancelled */ }
    // ...
}