rogue_macros/

lib.rs

//! # runtime‑macros
//!
//! Procedural macros used by the **runtime** project to generate RPC stubs, strongly‑typed
//! message‑handlers, and boilerplate for object references at **compile‑time**.  
//! They contain **no runtime logic** – their sole purpose is to expand user‑written async
//! functions and `impl` blocks into the code required for inter‑runtime communication.
//!
//! ## What it generates
//! * A [`MessageHandler`] implementation that the runtime can dispatch.
//! * `Input` and `Output` structs that implement [`TypeInfo`] for binary serialization.
//! * A tiny, ergonomic forwarding stub that performs the actual RPC call.
//!
//! The generated pieces are completely hidden from the end‑user, giving them a clean API while
//! retaining full type‑safety over the wire.
//!
//! ## Usage
//! Put async functions or methods inside an `rpc! { ... }` block:
//! ```rust,ignore
//! rpc! {
//!     async fn add(a: i32, b: i32) -> i32 {
//!         a + b
//!     }
//! }
//! ```.
use heck::ToPascalCase;
use proc_macro::TokenStream;
use proc_macro_error::proc_macro_error;
use proc_macro2::{Ident, Span, TokenStream as TokenStream2};
use quote::{ToTokens, quote};
use syn::{
    Attribute, Item, ItemStruct, Result,
    fold::Fold,
    parse::{Parse, ParseStream},
    parse_macro_input,
};

/// Returns `true` if the attribute list contains `#[local]`.
fn has_local_attr(attrs: &[Attribute]) -> bool {
    attrs.iter().any(|a| a.path().is_ident("local"))
}

/// Removes all `#[local]` attributes from the list in‑place.
fn remove_local_attr(attrs: &mut Vec<Attribute>) {
    attrs.retain(|a| !a.path().is_ident("local"));
}

/// Generate the body of an RPC‑forwarding stub.
///
/// The returned `TokenStream2` is the method body that:
/// 1. Builds the `args` input struct.
/// 2. Calls `ctx.runtime.call::<Handler>(target_id, args).await`.
/// 3. Emits tracing spans and converts errors into a `pending` future.
fn build_rpc_call_body(
    input_ident: &Ident,
    handler_ident: &Ident,
    fld_inits: &[TokenStream2],
    target_expr: TokenStream2,
    rpc_name: TokenStream2,
    ret_ty: TokenStream2,
) -> TokenStream2 {
    quote! {
        let ctx = rogue_runtime::CONTEXT.get();
        let args = #input_ident { #(#fld_inits),* };
        let target_id = #target_expr;
        rogue_runtime::tracing::trace!(rpc = #rpc_name, target = %target_id, "calling");
        let ret = match ctx.runtime.call::<#handler_ident>(target_id.clone(), args).await {
            Ok(output) => output.0,
            Err(e) => {
                rogue_runtime::tracing::error!(rpc = #rpc_name, target = %target_id, error = %e.to_string(), "failed");
                let _ = ctx.error_tx.send(e).await;
                return ::std::future::pending::<#ret_ty>().await;
            }
        };
        rogue_runtime::tracing::trace!(rpc = #rpc_name, target = %target_id, "done");
        ret
    }
}

/// Helper that produces the boiler‑plate `TypeInfo` implementation for a
/// given identifier, eliminating the repetition of the `type_name` and
/// `type_id` methods throughout the macro code.
fn gen_type_info_impl(ident: &Ident) -> TokenStream2 {
    quote! {
        impl rogue_runtime::TypeInfo for #ident {
            fn type_name() -> &'static str { stringify!(#ident) }
            fn type_id() -> rogue_runtime::TypeId {
                <rogue_runtime::sha2::Sha256 as rogue_runtime::sha2::Digest>::digest(Self::type_name()).into()
            }
        }
    }
}

/// Recursively search a type for any occurrence of `Self`.
fn type_contains_self(ty: &syn::Type) -> bool {
    use syn::visit::Visit;
    struct Finder {
        found: bool,
    }
    impl<'ast> Visit<'ast> for Finder {
        fn visit_type_path(&mut self, tp: &'ast syn::TypePath) {
            if tp.qself.is_none()
                && tp.path.segments.len() == 1
                && tp.path.segments[0].ident == "Self"
            {
                self.found = true;
            }
            syn::visit::visit_type_path(self, tp);
        }
    }
    let mut finder = Finder { found: false };
    Finder::visit_type(&mut finder, ty);
    finder.found
}

/* -------- mini-AST: just “a list of items inside the block” -------- */

/// Minimal wrapper around a sequence of Rust items that appear inside an
/// `rpc! { ... }` block. The parser simply collects everything until the end
/// of the block so the macro can iterate over the items later on.
struct RpcBlock {
    items: Vec<Item>,
}

impl Parse for RpcBlock {
    fn parse(input: ParseStream) -> Result<Self> {
        let mut items = Vec::new();
        while !input.is_empty() {
            items.push(input.parse()?);
        }
        Ok(Self { items })
    }
}

/* -------- the procedural macro -------- */

/// Generates the glue code that turns a user‑written async function or method
/// into a fully‑fledged RPC endpoint understood by the runtime.
///
/// The returned [`TokenStream2`] contains:
/// * A [`MessageHandler`] implementation that owns the actual async `handle`
///   logic and is registered through `inventory`.
/// * Typed `Input` and `Output` structs that carry the arguments and return
///   value across the wire and implement [`TypeInfo`].
/// * (When required) an ergonomic forwarding stub that clients call instead
///   of the original function, which performs the RPC under the hood.
///
/// # Parameters
/// * `fn_ident` – Identifier of the original async function/method.
/// * `impl_ident_opt` – `Some` with the containing struct’s ident for
///   methods, or `None` for free functions.
/// * `inputs` – Punctuated list of the function’s parameters.
/// * `output` – The declared return type.
fn generate_message_handler(
    fn_ident: &Ident,
    impl_ident_opt: Option<&Ident>,
    inputs: &syn::punctuated::Punctuated<syn::FnArg, syn::token::Comma>,
    output: &syn::ReturnType,
) -> TokenStream2 {
    // strip `_impl` suffix and convert to PascalCase
    let pascal = fn_ident
        .to_string()
        .trim_end_matches("_impl")
        .to_pascal_case();

    // If this comes from an `impl` block, include the (trimmed) struct name as prefix
    let struct_prefix = if let Some(impl_ident) = impl_ident_opt {
        let mut s = impl_ident.to_string();
        // our macro renames structs to `<Orig>Impl`; strip the suffix for readability
        if s.ends_with("Impl") {
            s.truncate(s.len() - 4);
        }
        s
    } else {
        String::new()
    };

    // original (alias) struct name – e.g. "Calculator" – used for `Self` returns
    let alias_ident = if !struct_prefix.is_empty() {
        Ident::new(&struct_prefix, fn_ident.span())
    } else {
        // dummy ident; won’t be used for free functions
        Ident::new("_Unused", fn_ident.span())
    };

    let handler_ident = Ident::new(
        &format!("{}{}Handler", struct_prefix, pascal),
        fn_ident.span(),
    );
    let input_ident = Ident::new(
        &format!("{}{}Input", struct_prefix, pascal),
        fn_ident.span(),
    );
    let output_ident = Ident::new(
        &format!("{}{}Output", struct_prefix, pascal),
        fn_ident.span(),
    );

    // Pre‑compute `TypeInfo` implementations via the helper to avoid repeating
    // the same quoted code three times.
    let handler_ti = gen_type_info_impl(&handler_ident);
    let input_ti = gen_type_info_impl(&input_ident);
    let output_ti = gen_type_info_impl(&output_ident);

    // ----- build input‑struct fields & argument list -------------------------
    let mut arg_fields: Vec<TokenStream2> = Vec::new();
    let mut arg_names: Vec<Ident> = Vec::new();
    let mut has_receiver = false;
    let mut consumes_self = false;
    let mut is_mut_receiver = false;

    for arg in inputs {
        match arg {
            syn::FnArg::Receiver(recv) => {
                has_receiver = true;
                if recv.reference.is_none() {
                    consumes_self = true; // by-value `self`
                } else if recv.mutability.is_some() {
                    is_mut_receiver = true; // `&mut self`
                }
            }
            syn::FnArg::Typed(pat_ty) => {
                if let syn::Pat::Ident(pat_ident) = &*pat_ty.pat {
                    let nm = &pat_ident.ident;
                    let ty = &pat_ty.ty;
                    arg_fields.push(quote! { #nm: #ty });
                    arg_names.push(nm.clone());
                }
            }
        }
    }

    // Choose RwLock access mode for &self / &mut self
    let lock_method = if is_mut_receiver {
        quote! { write }
    } else {
        quote! { read }
    };

    // prepend instance id for &self methods
    if has_receiver {
        arg_fields.insert(0, quote! { __instance_id: rogue_runtime::InstanceId });
    }

    // When there are no arguments the repetition expands to nothing, so we no
    // longer need a special‑case branch.
    let input_struct_fields = quote! { #(pub #arg_fields,)* };

    // Helper that replaces every `Self` in a type with the generated alias
    struct ReplaceSelf<'a> {
        alias: &'a Ident,
    }

    impl<'a> Fold for ReplaceSelf<'a> {
        fn fold_type_path(&mut self, mut tp: syn::TypePath) -> syn::TypePath {
            if tp.qself.is_none()
                && tp.path.segments.len() == 1
                && tp.path.segments[0].ident == "Self"
            {
                tp.path.segments[0].ident = self.alias.clone();
            }
            // continue walking so nested generics are handled, too
            syn::fold::fold_type_path(self, tp)
        }
    }

    let (ret_ty, needs_auto_register) = match output {
        syn::ReturnType::Type(_, ty) => {
            // Replace every occurrence of `Self` inside the type with the alias
            let mut replacer = ReplaceSelf {
                alias: &alias_ident,
            };
            let new_ty = replacer.fold_type((**ty).clone());

            let needs_auto_register = type_contains_self(&**ty);

            (quote! { #new_ty }, needs_auto_register)
        }
        syn::ReturnType::Default => (quote! { () }, false),
    };

    // Build the expressions we will actually pass to the wrapped function —
    // they must reference the fields on `data`, e.g. `data.n`
    let arg_values: Vec<TokenStream2> = arg_names.iter().map(|nm| quote! { data.#nm }).collect();
    // body of MessageHandler::handle -----------------------------------------
    let call_site = if has_receiver {
        let impl_ident = impl_ident_opt.expect("impl ident required for method with receiver");
        if consumes_self {
            if needs_auto_register {
                quote! {
                    let ctx = rogue_runtime::CONTEXT.get();
                    match ctx.runtime.take_instance::<#impl_ident>(data.__instance_id).await {
                        Some(instance) => {
                            let res = instance.#fn_ident(#(#arg_values),*).await;
                            let res = res.register_instance(&ctx.runtime).await;
                            Ok(#output_ident(res))
                        }
                        None => Err("instance not found".into()),
                    }
                }
            } else {
                quote! {
                    let ctx = rogue_runtime::CONTEXT.get();
                    match ctx.runtime.take_instance::<#impl_ident>(data.__instance_id).await {
                        Some(instance) => {
                            let res = instance.#fn_ident(#(#arg_values),*).await;
                            Ok(#output_ident(res))
                        }
                        None => Err("instance not found".into()),
                    }
                }
            }
        } else if needs_auto_register {
            quote! {
                let ctx = rogue_runtime::CONTEXT.get();
                match ctx.runtime.get_instance::<#impl_ident>(data.__instance_id).await {
                    Ok(instance) => {
                        let res = instance.#lock_method().await.#fn_ident(#(#arg_values),*).await;
                        let res = res.register_instance(&ctx.runtime).await;
                        Ok(#output_ident(res))
                    }
                    Err(e) => Err(e),
                }
            }
        } else {
            quote! {
                let ctx = rogue_runtime::CONTEXT.get();
                match ctx.runtime.get_instance::<#impl_ident>(data.__instance_id).await {
                    Ok(instance) => {
                        let res = instance.#lock_method().await.#fn_ident(#(#arg_values),*).await;
                        Ok(#output_ident(res))
                    }
                    Err(e) => Err(e),
                }
            }
        }
    } else if let Some(impl_ident) = impl_ident_opt {
        if needs_auto_register {
            quote! {
                let ctx = rogue_runtime::CONTEXT.get();
                let res = #impl_ident::#fn_ident(#(#arg_values),*).await;
                let res = res.register_instance(&ctx.runtime).await;
                Ok(#output_ident(res))
            }
        } else {
            quote! {
                let res = #impl_ident::#fn_ident(#(#arg_values),*).await;
                Ok(#output_ident(res))
            }
        }
    } else {
        // free async function
        quote! {
            let res = #fn_ident(#(#arg_values),*).await;
            Ok(#output_ident(res))
        }
    };

    // final token stream -----------------------------------------------------
    quote! {
        struct #handler_ident;

        #handler_ti

        #[derive(rogue_runtime::serde::Deserialize, rogue_runtime::serde::Serialize)]
        struct #input_ident { #input_struct_fields }

        #input_ti

        #[allow(non_camel_case_types)]
        #[derive(rogue_runtime::serde::Deserialize, rogue_runtime::serde::Serialize)]
        struct #output_ident(#ret_ty);

        #output_ti

        impl rogue_runtime::InventoryItemProvider for #handler_ident {
            fn type_info() -> rogue_runtime::InventoryItem {
                rogue_runtime::InventoryItem::Function(rogue_runtime::InventoryFunctionItem::new(stringify!(#handler_ident).to_string()))
            }
        }

        #[rogue_runtime::async_trait]
        impl rogue_runtime::MessageHandler for #handler_ident {
            type Input  = #input_ident;
            type Output = #output_ident;

            async fn handle(data: Self::Input) -> std::result::Result<Self::Output, String> {
                #call_site
            }
        }

        rogue_runtime::inventory::submit! {
            rogue_runtime::HandlerRegistration {
                register: |rt: rogue_runtime::Runtime| {
                    Box::pin(async move {
                        rt.register_handler::<#handler_ident>().await
                    })
                },
            }
        }
    }
}

/// Procedural macro `rpc!` – transforms async functions and methods into
/// remote‑callable RPC endpoints.
///
/// The macro walks every item inside the supplied block:
/// * Async functions/methods become RPC handlers plus forwarding stubs.
/// * Structs are renamed and wrapped in `ObjectRef` type aliases.
/// * Impl blocks are duplicated into trait definitions so both concrete
///   instances and their `ObjectRef` stubs implement the same API.
///
/// Items annotated with `#[local]` are passed through unchanged, allowing
/// authors to mix local utilities and remote calls within the same block.
///
/// See the crate‑level docs for a full usage example.
#[proc_macro_error]
#[proc_macro]
pub fn rpc(input: TokenStream) -> TokenStream {
    let RpcBlock { items } = parse_macro_input!(input as RpcBlock);

    /* ---------- first pass: gather struct renames ---------- */
    use std::collections::HashMap;

    // map OriginalName -> GeneratedNameImpl
    let mut struct_map: HashMap<String, Ident> = HashMap::new();
    for item in &items {
        if let Item::Struct(ItemStruct { ident, .. }) = item {
            let impl_ident = Ident::new(&format!("{}Impl", ident), ident.span());
            struct_map.insert(ident.to_string(), impl_ident);
        }
    }

    /* containers for emitted tokens */
    let mut emitted: Vec<TokenStream2> = Vec::new();
    let mut extra: Vec<TokenStream2> = Vec::new(); // generated extras (type alias, traits …)

    /* ---------- second pass: transform items ---------- */
    for mut item in items {
        match &mut item {
            /* ---- free functions --------------------------------------------------------- */
            Item::Fn(f) => {
                let local = has_local_attr(&f.attrs);
                if local {
                    let mut func = f.clone();
                    remove_local_attr(&mut func.attrs);
                    emitted.push(func.into_token_stream());
                    continue;
                }
                if f.sig.asyncness.is_some() {
                    // rename original to foo_impl
                    let orig_ident = f.sig.ident.clone();
                    let orig_vis = f.vis.clone();
                    let impl_ident = Ident::new(&format!("{}_impl", orig_ident), orig_ident.span());

                    // change the original function’s ident & visibility
                    f.sig.ident = impl_ident.clone();
                    f.vis = syn::Visibility::Inherited;

                    // ---- generate the MessageHandler BEFORE we move `item` ----------
                    let handler_ts =
                        generate_message_handler(&f.sig.ident, None, &f.sig.inputs, &f.sig.output);

                    // --- build a forwarding stub that performs an RPC call ------------------
                    let mut stub_sig = f.sig.clone();
                    stub_sig.ident = orig_ident.clone();

                    /* -------- collect argument idents & build Input struct init ------------ */
                    let mut fld_inits: Vec<TokenStream2> = Vec::new();
                    for arg in &stub_sig.inputs {
                        if let syn::FnArg::Typed(pt) = arg {
                            if let syn::Pat::Ident(pat_ident) = &*pt.pat {
                                let nm = &pat_ident.ident;
                                fld_inits.push(quote! { #nm: #nm });
                            }
                        }
                    }

                    /* -------- Handler/Input idents ---------------------------------------- */
                    let pascal = orig_ident.to_string().to_pascal_case();
                    let handler_ident =
                        Ident::new(&format!("{}Handler", pascal), Span::call_site());
                    let input_ident = Ident::new(&format!("{}Input", pascal), Span::call_site());

                    /* -------- return type tokens ----------------------------------------- */
                    let ret_ty_tokens: TokenStream2 = match &stub_sig.output {
                        syn::ReturnType::Type(_, ty) => quote! { #ty },
                        syn::ReturnType::Default => quote! { () },
                    };

                    /* -------- build stub body -------------------------------------------- */
                    let rpc_name = quote! { stringify!(#orig_ident) };
                    let body_stmts = build_rpc_call_body(
                        &input_ident,
                        &handler_ident,
                        &fld_inits,
                        quote! { ctx.target_id.clone() },
                        rpc_name,
                        quote! { #ret_ty_tokens },
                    );

                    let stub_fn = quote! {
                        #orig_vis #stub_sig {
                            #body_stmts
                        }
                    };

                    emitted.push(item.into_token_stream());
                    emitted.push(stub_fn);
                    extra.push(handler_ts);
                } else {
                    emitted.push(item.into_token_stream());
                }
            }

            /* ---- structs --------------------------------------------------------------- */
            Item::Struct(strct) => {
                let orig_ident = strct.ident.clone();
                let orig_vis = strct.vis.clone();
                let impl_ident = struct_map.get(&orig_ident.to_string()).unwrap().clone();
                strct.ident = impl_ident.clone(); // rename struct inside original item
                emitted.push(item.into_token_stream());

                // type alias
                let alias = quote! {
                    #orig_vis type #orig_ident = rogue_runtime::ObjectRef<#impl_ident>;
                };
                extra.push(alias);
            }

            /* ---- impl blocks ----------------------------------------------------------- */
            Item::Impl(imp) => {
                // does this impl target one of our renamed structs?
                let self_ty_ident_opt = match &*imp.self_ty {
                    syn::Type::Path(p) => p.path.get_ident().cloned(),
                    _ => None,
                };
                // If the whole impl is marked #[local], just rename the target type (if needed)
                // and pass it through without generating RPC wrappers.
                let impl_is_local = has_local_attr(&imp.attrs);
                if impl_is_local {
                    remove_local_attr(&mut imp.attrs);
                    if let Some(self_ident) = self_ty_ident_opt.clone() {
                        if let Some(impl_ident) = struct_map.get(&self_ident.to_string()) {
                            let new_ty: syn::Type = syn::parse_quote!(#impl_ident);
                            imp.self_ty = Box::new(new_ty);
                        }
                    }
                    emitted.push(item.into_token_stream());
                    continue;
                }
                if let Some(self_ident) = self_ty_ident_opt {
                    if let Some(impl_ident) = struct_map.get(&self_ident.to_string()) {
                        /* rename target type in the impl */
                        let new_ty: syn::Type = syn::parse_quote!(#impl_ident);
                        imp.self_ty = Box::new(new_ty);

                        /* buckets for methods */
                        let mut rpc_methods: Vec<syn::ImplItem> = Vec::new();
                        let mut keep_methods: Vec<syn::ImplItem> = Vec::new();

                        // Is this `impl SomeTrait for Type` ?
                        let is_trait_impl = imp.trait_.is_some();

                        for mut itm in std::mem::take(&mut imp.items) {
                            if let syn::ImplItem::Fn(ref mut m) = itm {
                                let async_ = m.sig.asyncness.is_some();
                                let local = has_local_attr(&m.attrs);
                                if async_ && !local {
                                    remove_local_attr(&mut m.attrs);

                                    // clone for RPC handler generation
                                    rpc_methods.push(itm.clone());

                                    // keep original method bodies *only* for trait impls so
                                    // server‑side logic is still present
                                    if is_trait_impl {
                                        keep_methods.push(itm);
                                    }
                                    // for inherent impls we strip the method here – it will
                                    // re‑appear inside the generated `impl <Trait> for Type`
                                } else {
                                    remove_local_attr(&mut m.attrs);
                                    keep_methods.push(itm);
                                }
                            } else {
                                keep_methods.push(itm);
                            }
                        }
                        imp.items = keep_methods;

                        /* ensure async‑trait on impl <Trait> for <Type> */
                        if is_trait_impl {
                            let has_async_trait_attr = imp.attrs.iter().any(|a| {
                                a.path()
                                    .segments
                                    .last()
                                    .map(|s| s.ident == "async_trait")
                                    .unwrap_or(false)
                            });
                            if !has_async_trait_attr {
                                imp.attrs
                                    .insert(0, syn::parse_quote!(#[rogue_runtime::async_trait]));
                            }
                        }

                        /* generate trait or stub‑only impls when we collected async RPC methods */
                        if !rpc_methods.is_empty() {
                            let mut trait_items: Vec<TokenStream2> = Vec::new();
                            let mut impl_items: Vec<TokenStream2> = Vec::new();
                            let mut stub_items: Vec<TokenStream2> = Vec::new();

                            for itm in &rpc_methods {
                                if let syn::ImplItem::Fn(m) = itm {
                                    /* ------------- signature for generated trait (inherent impls) --------- */
                                    let mut sig_trait = m.sig.clone();

                                    let mut needs_auto_register = false;
                                    if let syn::ReturnType::Type(_, ty) = &sig_trait.output {
                                        if type_contains_self(&**ty) {
                                            needs_auto_register = true;
                                        }
                                    }
                                    if needs_auto_register {
                                        sig_trait.generics.make_where_clause();
                                        sig_trait
                                            .generics
                                            .where_clause
                                            .as_mut()
                                            .unwrap()
                                            .predicates
                                            .push(syn::parse_quote!(Self: rogue_runtime::AutoRegister + Sized));
                                    }

                                    trait_items.push(quote! { #sig_trait ; });

                                    /* ------------- keep original method (for Impl type) ------------------- */
                                    let mut m_impl = m.clone();
                                    m_impl.vis = syn::Visibility::Inherited;
                                    impl_items.push(m_impl.into_token_stream());

                                    /* ------------- build ObjectRef stub method ---------------------------- */
                                    let sig_stub = m.sig.clone();

                                    let mut fld_inits = Vec::<TokenStream2>::new();
                                    let mut has_receiver = false;
                                    for arg in &m.sig.inputs {
                                        match arg {
                                            syn::FnArg::Receiver(_) => {
                                                has_receiver = true;
                                            }
                                            syn::FnArg::Typed(pt) => {
                                                if let syn::Pat::Ident(pat_ident) = &*pt.pat {
                                                    let nm = &pat_ident.ident;
                                                    fld_inits.push(quote! { #nm: #nm });
                                                }
                                            }
                                        }
                                    }
                                    if has_receiver {
                                        fld_inits.insert(0, quote! { __instance_id: *self.id() });
                                    }

                                    let pascal = m.sig.ident.to_string().to_pascal_case();
                                    let struct_prefix = self_ident.to_string();
                                    let handler_ident = Ident::new(
                                        &format!("{}{}Handler", struct_prefix, pascal),
                                        Span::call_site(),
                                    );
                                    let input_ident = Ident::new(
                                        &format!("{}{}Input", struct_prefix, pascal),
                                        Span::call_site(),
                                    );

                                    let ret_ty_tokens: TokenStream2 = match &m.sig.output {
                                        syn::ReturnType::Type(_, ty) => quote! { #ty },
                                        syn::ReturnType::Default => quote! { () },
                                    };

                                    let target_expr = if has_receiver {
                                        quote! { self.runtime_id() }
                                    } else {
                                        quote! { ctx.target_id.clone() }
                                    };

                                    let rpc_name = quote! { concat!(stringify!(#struct_prefix), "::", stringify!(#pascal)) };
                                    let body_stmts = build_rpc_call_body(
                                        &input_ident,
                                        &handler_ident,
                                        &fld_inits,
                                        quote! { #target_expr },
                                        rpc_name,
                                        quote! { #ret_ty_tokens },
                                    );

                                    stub_items.push(quote! {
                                        #sig_stub {
                                            #body_stmts
                                        }
                                    });

                                    /* ------------- server‑side handler generation ------------------------- */
                                    let handler_ts = generate_message_handler(
                                        &m.sig.ident,
                                        Some(&impl_ident),
                                        &m.sig.inputs,
                                        &m.sig.output,
                                    );
                                    extra.push(handler_ts);
                                }
                            }

                            let stub_ty: syn::Type =
                                syn::parse_quote!(rogue_runtime::ObjectRef<#impl_ident>);

                            if let Some((_, trait_path, _)) = &imp.trait_ {
                                /* ------ user wrote `impl SomeTrait for Type` --------------------------- */
                                let trait_block = quote! {
                                    #[rogue_runtime::async_trait]
                                    impl #trait_path for #stub_ty {
                                        #(#stub_items)*
                                    }
                                };
                                extra.push(trait_block);
                            } else {
                                /* ------ inherent impl: synthesise a new trait -------------------------- */
                                let trait_ident =
                                    Ident::new(&format!("{}Trait", self_ident), Span::call_site());

                                let trait_block = quote! {
                                    #[rogue_runtime::async_trait]
                                    pub trait #trait_ident {
                                        #(#trait_items)*
                                    }

                                    #[rogue_runtime::async_trait]
                                    impl #trait_ident for #impl_ident {
                                        #(#impl_items)*
                                    }

                                    #[rogue_runtime::async_trait]
                                    impl #trait_ident for #stub_ty {
                                        #(#stub_items)*
                                    }
                                };
                                extra.push(trait_block);
                            }
                        }

                        emitted.push(item.into_token_stream());
                    } else {
                        // impl for unrelated type, pass through
                        emitted.push(item.into_token_stream());
                    }
                } else {
                    emitted.push(item.into_token_stream());
                }
            }

            /* ---- traits --------------------------------------------------------------- */
            Item::Trait(trt) => {
                // prepend #[rogue_runtime::async_trait] unless already present
                let has_async_trait = trt.attrs.iter().any(|a| {
                    a.path()
                        .segments
                        .last()
                        .map(|s| s.ident == "async_trait")
                        .unwrap_or(false)
                });
                if !has_async_trait {
                    trt.attrs
                        .insert(0, syn::parse_quote!(#[rogue_runtime::async_trait]));
                }
                emitted.push(item.into_token_stream());
            }
            /* ---- everything else: pass through ---------------------------------------- */
            _ => emitted.push(item.into_token_stream()),
        }
    }

    /* ---------- final output ---------- */
    emitted.extend(extra);

    quote! { #(#emitted)* }.into()
}