behavior_macros/

lib.rs

//! `behavior-macros` — proc-macros for the behavior algebra.
//!
//! `#[behavior]` wires a fully declared inherent user-message fold and may
//! generate its nominal send and closed birth products.

use proc_macro::TokenStream;
use proc_macro_crate::{FoundCrate, crate_name};
use proc_macro2::{Span, TokenStream as TokenStream2};
use quote::{format_ident, quote};
use syn::parse::{Parse, ParseStream};
use syn::visit::Visit;
use syn::{
    Data, DeriveInput, Error, Fields, FnArg, GenericArgument, GenericParam, Generics, Ident,
    ImplItem, ItemImpl, PathArguments, Result, ReturnType, Token, Type, Visibility, braced,
    parse_macro_input, parse_quote,
};

fn crate_path(found: FoundCrate) -> TokenStream2 {
    match found {
        FoundCrate::Itself => quote!(crate),
        FoundCrate::Name(name) => {
            // Cargo package keys and library target names differ for each
            // Bombay crate. Explicit dependency renames remain unchanged.
            let name = match name.as_str() {
                "bombay_behavior" => "behavior",
                "bombay_behavior_actors" => "behavior_actors",
                "bombay_rs" => "bombay",
                _ => &name,
            };
            let name = syn::Ident::new(&name, Span::call_site());
            quote!(::#name)
        }
    }
}

fn behavior_crate() -> Result<TokenStream2> {
    if std::env::var("CARGO_PKG_NAME").as_deref() == Ok("bombay-behavior") {
        // This package deliberately exposes the library target as `behavior`,
        // not Cargo's normalized package name `bombay_behavior`. The same path
        // works in its unit, integration, and rustdoc crates.
        return Ok(quote!(::behavior));
    }
    if std::env::var("CARGO_PKG_NAME").as_deref() == Ok("bombay-rs") {
        // `FoundCrate::Itself` identifies a package, but `crate` identifies
        // the target currently being compiled. The facade's library target is
        // `bombay`; sibling binaries and examples therefore reach its exports
        // through `::bombay`, not through their own `crate` root.
        // The facade's existing self alias also resolves in its rustdoc crate.
        return Ok(quote!(::bombay::behavior));
    }
    if let Ok(found) = crate_name("bombay-behavior") {
        return Ok(crate_path(found));
    }
    if let Ok(found) = crate_name("bombay-rs") {
        let bombay = crate_path(found);
        return Ok(quote!(#bombay::behavior));
    }
    Err(Error::new(
        Span::call_site(),
        "could not resolve `bombay-behavior` directly or through `bombay-rs`",
    ))
}

fn actors_crate() -> Result<TokenStream2> {
    if std::env::var("CARGO_PKG_NAME").as_deref() == Ok("bombay-behavior-actors") {
        return if std::env::var("CARGO_CRATE_NAME").as_deref() == Ok("behavior_actors") {
            Ok(quote!(crate))
        } else {
            Ok(quote!(::behavior_actors))
        };
    }
    if std::env::var("CARGO_PKG_NAME").as_deref() == Ok("bombay-rs") {
        return Ok(quote!(::bombay));
    }
    // The Bombay facade owns the Actors catalogue its expansion sites compile
    // against. A consumer may carry both the facade and a direct foundational
    // actors dependency, and the two resolve to different revisions whenever
    // the facade pins its own: generated paths must then agree with the
    // facade-path imports the consumer actually writes (`bombay::pool`), so
    // the facade wins. The foundational crate remains the fallback when no
    // facade is present.
    if let Ok(found) = crate_name("bombay-rs") {
        return Ok(crate_path(found));
    }
    if let Ok(found) = crate_name("bombay-behavior-actors") {
        return Ok(crate_path(found));
    }
    Err(Error::new(
        Span::call_site(),
        "could not resolve `bombay-behavior-actors` through `bombay-rs` or directly",
    ))
}

#[cfg(test)]
mod crate_resolution_tests {
    use super::*;

    #[test]
    fn package_library_names_and_explicit_renames_resolve_distinctly() {
        assert_eq!(
            crate_path(FoundCrate::Name("bombay_rs".to_owned())).to_string(),
            ":: bombay"
        );
        assert_eq!(
            crate_path(FoundCrate::Name("bombay_behavior".to_owned())).to_string(),
            ":: behavior"
        );
        assert_eq!(
            crate_path(FoundCrate::Name("bombay_behavior_actors".to_owned())).to_string(),
            ":: behavior_actors"
        );
        assert_eq!(
            crate_path(FoundCrate::Name("runtime".to_owned())).to_string(),
            ":: runtime"
        );
    }
}

struct NamedField {
    name: Ident,
    ty: Type,
}

struct NamedProduct {
    fields: Vec<NamedField>,
}

#[allow(
    clippy::large_enum_variant,
    reason = "boxing syn::Type would add lint-driven indirection to compile-time parser state"
)]
enum SendsSpec {
    Existing(Type),
    Generated {
        product: NamedProduct,
        visibility: Visibility,
    },
}

#[allow(
    clippy::large_enum_variant,
    reason = "boxing syn::Type would add lint-driven indirection to compile-time parser state"
)]
enum BirthsSpec {
    Existing(Type),
    Generated(NamedProduct),
}

#[derive(Clone, Copy)]
enum CreationSettlementDisposition {
    ReturnToCreator,
    RetainForRetirement,
}

fn parse_product(input: ParseStream) -> Result<NamedProduct> {
    let content;
    braced!(content in input);
    let mut fields = Vec::new();
    let mut names = std::collections::BTreeSet::new();
    while !content.is_empty() {
        let name: Ident = content.parse()?;
        if !names.insert(name.to_string()) {
            return Err(Error::new_spanned(name, "duplicate product lane"));
        }
        content.parse::<Token![:]>()?;
        fields.push(NamedField {
            name,
            ty: content.parse()?,
        });
        if content.peek(Token![,]) {
            content.parse::<Token![,]>()?;
        } else if !content.is_empty() {
            return Err(content.error("expected `,` between product lanes"));
        }
    }
    if fields.is_empty() {
        return Err(input.error("empty products must be omitted"));
    }
    Ok(NamedProduct { fields })
}

struct BehaviorArgs {
    addr: Type,
    message: Type,
    sends: Option<SendsSpec>,
    births: Option<BirthsSpec>,
    creation_settlements: Option<CreationSettlementDisposition>,
    error: Option<Type>,
}

struct PoolWorkerArgs {
    addr: Type,
    result: Type,
}

impl Parse for PoolWorkerArgs {
    fn parse(input: ParseStream) -> Result<Self> {
        let mut addr = None;
        let mut result = None;
        while !input.is_empty() {
            let key: Ident = input.parse()?;
            input.parse::<Token![=]>()?;
            match key.to_string().as_str() {
                "addr" if addr.is_none() => addr = Some(input.parse()?),
                "result" if result.is_none() => result = Some(input.parse()?),
                "addr" | "result" => {
                    return Err(Error::new_spanned(key, "duplicate pool worker argument"));
                }
                _ => return Err(Error::new_spanned(key, "unknown pool worker argument")),
            }
            if input.peek(Token![,]) {
                input.parse::<Token![,]>()?;
            } else if !input.is_empty() {
                return Err(input.error("expected `,` between pool worker arguments"));
            }
        }
        Ok(Self {
            addr: addr.ok_or_else(|| input.error("missing `addr`"))?,
            result: result.ok_or_else(|| input.error("missing `result`"))?,
        })
    }
}

impl Parse for BehaviorArgs {
    fn parse(input: ParseStream) -> Result<Self> {
        let mut addr = None;
        let mut message = None;
        let mut sends = None;
        let mut births = None;
        let mut creation_settlements = None;
        let mut error = None;
        while !input.is_empty() {
            let key: Ident = input.parse()?;
            input.parse::<Token![=]>()?;
            match key.to_string().as_str() {
                "addr" if addr.is_none() => addr = Some(input.parse()?),
                "message" if message.is_none() => message = Some(input.parse()?),
                "sends" if sends.is_none() => {
                    let visibility: Visibility = input.parse()?;
                    sends = Some(if input.peek(syn::token::Brace) {
                        SendsSpec::Generated {
                            product: parse_product(input)?,
                            visibility,
                        }
                    } else if matches!(visibility, Visibility::Inherited) {
                        SendsSpec::Existing(input.parse()?)
                    } else {
                        return Err(input.error("send-product visibility requires named lanes"));
                    });
                }
                "births" if births.is_none() => {
                    births = Some(if input.peek(syn::token::Brace) {
                        BirthsSpec::Generated(parse_product(input)?)
                    } else {
                        BirthsSpec::Existing(input.parse()?)
                    });
                }
                "creation_settlements" if creation_settlements.is_none() => {
                    let disposition: Ident = input.parse()?;
                    creation_settlements = Some(match disposition.to_string().as_str() {
                        "return_to_creator" => CreationSettlementDisposition::ReturnToCreator,
                        "retain_for_retirement" => {
                            CreationSettlementDisposition::RetainForRetirement
                        }
                        _ => {
                            return Err(Error::new_spanned(
                                disposition,
                                "creation settlements must `return_to_creator` or `retain_for_retirement`",
                            ));
                        }
                    });
                }
                "error" if error.is_none() => error = Some(input.parse()?),
                "addr" | "message" | "sends" | "births" | "creation_settlements" | "error" => {
                    return Err(Error::new_spanned(key, "duplicate behavior argument"));
                }
                _ => return Err(Error::new_spanned(key, "unknown behavior argument")),
            }
            if input.peek(Token![,]) {
                input.parse::<Token![,]>()?;
            } else if !input.is_empty() {
                return Err(input.error("expected `,` between behavior arguments"));
            }
        }
        match (&births, creation_settlements) {
            (Some(BirthsSpec::Generated(_)), None) => {
                return Err(input.error(
                    "birth-owning behaviors must declare `creation_settlements = return_to_creator` or `creation_settlements = retain_for_retirement`",
                ));
            }
            (None, Some(_)) => {
                return Err(input.error("`creation_settlements` requires a `births` declaration"));
            }
            (Some(_), Some(_)) | (Some(_), None) | (None, None) => {}
        }
        Ok(Self {
            addr: addr.ok_or_else(|| input.error("missing `addr`"))?,
            message: message.ok_or_else(|| input.error("missing `message`"))?,
            sends,
            births,
            creation_settlements,
            error,
        })
    }
}

fn validate_receiver(method: &syn::ImplItemFn) -> Result<()> {
    let Some(FnArg::Receiver(receiver)) = method.sig.inputs.first() else {
        return Err(Error::new_spanned(
            &method.sig,
            "behavior methods must begin with &mut self",
        ));
    };
    if !matches!(receiver.kind, syn::ReceiverKind::Reference(_, _, Some(_))) {
        return Err(Error::new_spanned(
            receiver,
            "behavior methods must begin with &mut self",
        ));
    }
    if method.sig.constness.is_some()
        || method.sig.asyncness.is_some()
        || matches!(method.sig.safety, syn::Safety::Unsafe(_))
        || !method.sig.generics.params.is_empty()
    {
        return Err(Error::new_spanned(
            &method.sig,
            "behavior methods must be synchronous, safe, and non-generic",
        ));
    }
    if matches!(method.sig.output, ReturnType::Default) {
        return Err(Error::new_spanned(
            &method.sig,
            "behavior methods must declare their complete Actions result type",
        ));
    }
    Ok(())
}

fn validate_pool_worker_output(output: &ReturnType) -> Result<()> {
    let ReturnType::Type(_, output) = output else {
        return Err(Error::new_spanned(
            output,
            "pool worker transition must return WorkerActed<Self>",
        ));
    };
    let Type::Path(output) = output.as_ref() else {
        return Err(Error::new_spanned(
            output,
            "pool worker transition must return WorkerActed<Self>",
        ));
    };
    if output.qself.is_some() || output.path.segments.len() != 1 {
        return Err(Error::new_spanned(
            output,
            "pool worker transition must return WorkerActed<Self>",
        ));
    }
    let segment = output
        .path
        .segments
        .first()
        .ok_or_else(|| Error::new_spanned(output, "missing pool worker return type"))?;
    let PathArguments::AngleBracketed(arguments) = &segment.arguments else {
        return Err(Error::new_spanned(
            output,
            "pool worker transition must return WorkerActed<Self>",
        ));
    };
    let mut arguments = arguments.args.iter();
    let Some(GenericArgument::Type(Type::Path(self_type))) = arguments.next() else {
        return Err(Error::new_spanned(
            output,
            "pool worker transition must return WorkerActed<Self>",
        ));
    };
    let self_segment = self_type.path.segments.first();
    if segment.ident != "WorkerActed"
        || arguments.next().is_some()
        || self_type.qself.is_some()
        || self_type.path.segments.len() != 1
        || !matches!(self_segment, Some(segment) if segment.ident == "Self" && matches!(segment.arguments, PathArguments::None))
    {
        return Err(Error::new_spanned(
            output,
            "pool worker transition must return WorkerActed<Self>",
        ));
    }
    Ok(())
}

fn pool_worker_assignment(method: &syn::ImplItemFn) -> Result<Type> {
    let Some(FnArg::Receiver(receiver)) = method.sig.inputs.first() else {
        return Err(Error::new_spanned(
            &method.sig,
            "pool worker transition must begin with &mut self",
        ));
    };
    if !matches!(receiver.kind, syn::ReceiverKind::Reference(_, _, Some(_))) {
        return Err(Error::new_spanned(
            receiver,
            "pool worker transition must begin with &mut self",
        ));
    }
    if method.sig.constness.is_some()
        || method.sig.asyncness.is_some()
        || matches!(method.sig.safety, syn::Safety::Unsafe(_))
        || method.sig.abi.is_some()
        || method.sig.variadic.is_some()
        || !method.sig.generics.params.is_empty()
    {
        return Err(Error::new_spanned(
            &method.sig,
            "pool worker transition must be synchronous, safe, and non-generic",
        ));
    }
    if method.sig.inputs.len() != 2 {
        return Err(Error::new_spanned(
            &method.sig,
            "pool worker transition must accept exactly &mut self and one Assignment<Job>",
        ));
    }
    validate_pool_worker_output(&method.sig.output)?;

    let Some(FnArg::Typed(assignment)) = method.sig.inputs.iter().nth(1) else {
        return Err(Error::new_spanned(
            &method.sig,
            "pool worker transition must accept one Assignment<Job>",
        ));
    };
    let Type::Path(assignment_path) = assignment.ty.as_ref() else {
        return Err(Error::new_spanned(
            &assignment.ty,
            "pool worker transition input must be Assignment<Job>",
        ));
    };
    let Some(segment) = assignment_path.path.segments.last() else {
        return Err(Error::new_spanned(
            &assignment.ty,
            "pool worker transition input must be Assignment<Job>",
        ));
    };
    let PathArguments::AngleBracketed(arguments) = &segment.arguments else {
        return Err(Error::new_spanned(
            &assignment.ty,
            "pool worker transition input must be Assignment<Job>",
        ));
    };
    let mut arguments = arguments.args.iter();
    if segment.ident != "Assignment"
        || !matches!(arguments.next(), Some(GenericArgument::Type(_)))
        || arguments.next().is_some()
    {
        return Err(Error::new_spanned(
            &assignment.ty,
            "pool worker transition input must be Assignment<Job>",
        ));
    }
    Ok(assignment.ty.as_ref().clone())
}

fn pascal_name(field: &Ident) -> String {
    field
        .to_string()
        .split('_')
        .filter(|part| !part.is_empty())
        .map(|part| {
            let mut chars = part.chars();
            chars.next().map_or_else(String::new, |first| {
                first.to_uppercase().chain(chars).collect()
            })
        })
        .collect::<String>()
}

fn lane_name(product: &Ident, field: &Ident) -> Ident {
    let lane = pascal_name(field);
    format_ident!("{}{}", product, lane)
}

#[derive(Default)]
struct GenericUses {
    identifiers: std::collections::BTreeSet<String>,
    lifetimes: std::collections::BTreeSet<String>,
}

impl GenericUses {
    // Raw and ordinary spellings name the same Rust identifier. Also avoid
    // references: a new parameter must not capture an authored type alias.
    fn fresh(&mut self, preferred: &str) -> Ident {
        let mut name = preferred.to_owned();
        while self.identifiers.contains(&name) || self.identifiers.contains(&format!("r#{name}")) {
            name.push('_');
        }
        self.identifiers.insert(name.clone());
        Ident::new(&name, Span::mixed_site())
    }
}

impl<'ast> Visit<'ast> for GenericUses {
    fn visit_ident(&mut self, ident: &'ast Ident) {
        self.identifiers.insert(ident.to_string());
    }

    fn visit_lifetime(&mut self, lifetime: &'ast syn::Lifetime) {
        self.lifetimes.insert(lifetime.ident.to_string());
    }
}

fn product_generics(item: &ItemImpl, fields: &[NamedField]) -> Generics {
    let mut uses = GenericUses::default();
    for field in fields {
        uses.visit_type(&field.ty);
    }
    let mut generics = item.generics.clone();
    generics.params = generics
        .params
        .into_iter()
        .filter(|parameter| match parameter {
            GenericParam::Lifetime(parameter) => uses
                .lifetimes
                .contains(&parameter.lifetime.ident.to_string()),
            GenericParam::Type(parameter) => {
                uses.identifiers.contains(&parameter.ident.to_string())
            }
            GenericParam::Const(parameter) => {
                uses.identifiers.contains(&parameter.ident.to_string())
            }
        })
        .collect();
    generics.where_clause = None;
    generics
}

fn named_send_interpretation(
    loans: &[&Ident],
    field_types: &[&Type],
    interpreter: &Ident,
    root_event: &Ident,
    path: &Ident,
    behavior: &TokenStream2,
) -> TokenStream2 {
    let turns = loans.iter().zip(field_types).enumerate().map(|(index, (loan, field_ty))| {
        let current_loan = loans.iter().enumerate().map(|(position, retained)| {
            if position == index { quote!(#retained) } else { quote!(_) }
        }).collect::<Vec<_>>();
        let remaining_loans = loans.iter().enumerate().map(|(position, retained)| {
            if position >= index { quote!(#retained) } else { quote!(_) }
        }).collect::<Vec<_>>();
        let later_loans = &loans[index + 1..];
        let later_types = &field_types[index + 1..];
        quote! {
            // Only the guaranteed-Send child future crosses this await.
            // Its input/reply owners and every sibling remain in parent progress.
            {
                let ::core::option::Option::Some(#behavior::InterpretationProgress::Interpreting(custody)) = progress else { return; };
                let (#(#current_loan,)*) = custody;
                <#field_ty as #behavior::InterpretSends<#interpreter, #root_event, #path>>::interpret(#loan, interpreter)
            }.await;
            // All direct child loans below are synchronous and end before
            // constructing the next child producer.
            {
                let ::core::option::Option::Some(#behavior::InterpretationProgress::Interpreting(custody)) = progress else { return; };
                let (#(#remaining_loans,)*) = custody;
                <#field_ty as #behavior::SendSettlements>::finish_interpretation(#loan);
                match #loan {
                    ::core::option::Option::Some(#behavior::InterpretationProgress::Completed(#behavior::Interpretation::Complete(_))) => {},
                    ::core::option::Option::Some(#behavior::InterpretationProgress::Completed(#behavior::Interpretation::Corrupt(_))) => {
                        #(<#later_types as #behavior::SendSettlements>::unattempted(#later_loans);)*
                        <Self as #behavior::SendSettlements>::finish_interpretation(progress);
                        return;
                    }
                    _ => return,
                }
            }
        }
    }).collect::<Vec<_>>();
    quote! {
        <Self as #behavior::SendSettlements>::prepare_interpretation(progress);
        #(#turns)*
        <Self as #behavior::SendSettlements>::finish_interpretation(progress);
    }
}

fn source_product_custody(
    settlements: &[TokenStream2],
    custody: &[TokenStream2],
    behavior: &TokenStream2,
) -> (TokenStream2, TokenStream2) {
    settlements.iter().zip(custody).rev().fold((quote!(#behavior::NoSends), quote!(#behavior::NoSends)), |(later_settlements, later_custody), (earlier_settlements, earlier_custody)| (
        quote!((#earlier_settlements, #later_settlements)),
        quote!((::core::option::Option<#behavior::SourceProgress<#earlier_settlements, #earlier_custody>>, ::core::option::Option<#behavior::SourceProgress<#later_settlements, #later_custody>>)),
    ))
}

fn named_settlement_contract(
    name: &Ident,
    settlement_type: &TokenStream2,
    generics: &Generics,
    fields: &[&Ident],
    field_types: &[Type],
    behavior: &TokenStream2,
) -> TokenStream2 {
    let mut uses = GenericUses::default();
    uses.visit_generics(generics);
    uses.visit_ident(name);
    for field_ty in field_types {
        uses.visit_type(field_ty);
    }
    let settlement_host = uses.fresh("__BombaySettlementHost");
    let settlement_event = uses.fresh("__BombaySettlementEvent");
    let mut classification_generics = generics.clone();
    let mut custody_generics = generics.clone();
    custody_generics.params.push(parse_quote!(#settlement_host));
    custody_generics
        .params
        .push(parse_quote!(#settlement_event));
    custody_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#settlement_host: ::core::marker::Send));
    let mut combined_status = quote!(#behavior::SettlementStatus::Accepted);
    for (field, field_ty) in fields.iter().zip(field_types) {
        classification_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(#field_ty: #behavior::ClassifySettlement));
        custody_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(
                #field_ty: #behavior::SourceSettlementCustody<
                    #settlement_host,
                    #settlement_event,
                > + ::core::marker::Send
            ));
        combined_status = quote! {
            (#combined_status).combine(
                #behavior::ClassifySettlement::settlement_status(&self.#field)
            )
        };
    }
    let (classification_impl, _, classification_where) = classification_generics.split_for_impl();
    let (custody_impl, _, custody_where) = custody_generics.split_for_impl();
    let source_settlements = field_types.iter().map(|ty| quote!(#ty)).collect::<Vec<_>>();
    let source_custody = field_types.iter().map(|ty| quote!(<#ty as #behavior::SourceSettlementCustody<#settlement_host, #settlement_event>>::Custody)).collect::<Vec<_>>();
    let (source_product, source_owner) =
        source_product_custody(&source_settlements, &source_custody, behavior);
    let source_input = fields.iter().rev().fold(
        quote!(#behavior::NoSends),
        |later, field| quote!((original.#field, #later)),
    );
    let source_output = fields
        .iter()
        .rev()
        .fold(quote!(_), |later, field| quote!((#field, #later)));

    quote! {
        impl #classification_impl #behavior::ClassifySettlement
            for #settlement_type #classification_where
        {
            fn settlement_status(&self) -> #behavior::SettlementStatus {
                #combined_status
            }
        }

        impl #custody_impl #behavior::SourceSettlementCustody<#settlement_host, #settlement_event> for #settlement_type #custody_where {
            type Custody = #source_owner;
            fn prepare_source(progress: &mut ::core::option::Option<#behavior::SourceProgress<Self, Self::Custody>>) {
                let original = match progress.take() {
                    ::core::option::Option::Some(#behavior::SourceProgress::Original(original)) => original,
                    retained => { *progress = retained; return; }
                };
                // The concrete Core tuple prepare only decomposes; it calls no child method.
                let mut product = ::core::option::Option::Some(#behavior::SourceProgress::Original(#source_input));
                <#source_product as #behavior::SourceSettlementCustody<#settlement_host, #settlement_event>>::prepare_source(&mut product);
                *progress = match product {
                    ::core::option::Option::Some(#behavior::SourceProgress::Original(#source_output)) => ::core::option::Option::Some(#behavior::SourceProgress::Original(#name { #(#fields,)* })),
                    ::core::option::Option::Some(#behavior::SourceProgress::Offering(custody)) => ::core::option::Option::Some(#behavior::SourceProgress::Offering(custody)),
                    ::core::option::Option::Some(#behavior::SourceProgress::Completed(reply)) => ::core::option::Option::Some(#behavior::SourceProgress::Completed(reply.map(|#source_output| #name { #(#fields,)* }))),
                    ::core::option::Option::None => ::core::option::Option::None,
                };
            }
            fn offer_next_to_source(custody: &mut Self::Custody, host: &mut #settlement_host) -> impl ::core::future::Future<Output = ()> + ::core::marker::Send {
                <#source_product as #behavior::SourceSettlementCustody<#settlement_host, #settlement_event>>::offer_next_to_source(custody, host)
            }
            fn finish_source(progress: &mut ::core::option::Option<#behavior::SourceProgress<Self, Self::Custody>>) {
                let custody = match progress.take() {
                    ::core::option::Option::Some(#behavior::SourceProgress::Offering(custody)) => custody,
                    retained => { *progress = retained; return; }
                };
                let mut product = ::core::option::Option::Some(#behavior::SourceProgress::Offering(custody));
                <#source_product as #behavior::SourceSettlementCustody<#settlement_host, #settlement_event>>::finish_source(&mut product);
                *progress = match product {
                    ::core::option::Option::Some(#behavior::SourceProgress::Original(#source_output)) => ::core::option::Option::Some(#behavior::SourceProgress::Original(#name { #(#fields,)* })),
                    ::core::option::Option::Some(#behavior::SourceProgress::Offering(custody)) => ::core::option::Option::Some(#behavior::SourceProgress::Offering(custody)),
                    ::core::option::Option::Some(#behavior::SourceProgress::Completed(reply)) => ::core::option::Option::Some(#behavior::SourceProgress::Completed(reply.map(|#source_output| #name { #(#fields,)* }))),
                    ::core::option::Option::None => ::core::option::Option::None,
                };
            }
        }

    }
}

#[allow(
    clippy::too_many_lines,
    reason = "the ordered send-product traits share one named-lane equation"
)]
fn named_send_contract(
    name: &Ident,
    generics: &Generics,
    fields: &[&Ident],
    field_types: &[&Type],
    settlement_type: &TokenStream2,
    settlement_name: &Ident,
    behavior: &TokenStream2,
) -> TokenStream2 {
    let mut uses = GenericUses::default();
    uses.visit_generics(generics);
    uses.visit_ident(name);
    for field_ty in field_types {
        uses.visit_type(field_ty);
    }
    let event = uses.fresh("__BombayEvent");
    let interpreter = uses.fresh("__BombayInterpreter");
    let root_event = uses.fresh("__BombayRootEvent");
    let path = uses.fresh("__BombayPath");
    let (_, type_generics, _) = generics.split_for_impl();
    let mut effects_generics = generics.clone();
    let mut logical_generics = generics.clone();
    let mut settlement_generics = generics.clone();
    let mut lawful_generics = generics.clone();
    lawful_generics.params.push(parse_quote!(#event));
    let mut interpretation_generics = generics.clone();
    interpretation_generics
        .params
        .push(parse_quote!(#interpreter));
    interpretation_generics
        .params
        .push(parse_quote!(#root_event));
    interpretation_generics.params.push(parse_quote!(#path));
    interpretation_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#interpreter: ::core::marker::Send));
    interpretation_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#name #type_generics: ::core::marker::Send));
    let mut logical_protocols = quote!(#behavior::NoBirthProtocols);
    for field_ty in field_types {
        effects_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(#field_ty: #behavior::SendEffects));
        logical_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(#field_ty: #behavior::LogicalDeliveryProtocols));
        settlement_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(#field_ty: #behavior::SendSettlements));
        lawful_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(#field_ty: #behavior::SendsFor<#event>));
        interpretation_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(
                #field_ty: #behavior::InterpretSends<
                    #interpreter,
                    #root_event,
                    #path,
                >
            ));
        logical_protocols = quote!(
            <#logical_protocols as #behavior::BirthProtocolProduct>::Append<
                <#field_ty as #behavior::LogicalDeliveryProtocols>::Protocols
            >
        );
    }
    interpretation_generics.make_where_clause().predicates.push(parse_quote!(
        <#name #type_generics as #behavior::SendSettlements>::InterpretationCustody: ::core::marker::Send
    ));
    let (effects_impl, _, effects_where) = effects_generics.split_for_impl();
    let (logical_impl, _, logical_where) = logical_generics.split_for_impl();
    let (settlement_impl, _, settlement_where) = settlement_generics.split_for_impl();
    let (lawful_impl, _, lawful_where) = lawful_generics.split_for_impl();
    let (interpretation_impl, _, interpretation_where) = interpretation_generics.split_for_impl();
    let interpretation_loans = fields
        .iter()
        .map(|field| {
            let field_name = field.to_string();
            format_ident!(
                "__bombay_{}_interpretation",
                field_name.trim_start_matches("r#"),
                span = Span::mixed_site()
            )
        })
        .collect::<Vec<_>>();
    let loan_fields = interpretation_loans.iter().collect::<Vec<_>>();
    let remaining_interpretations =
        Ident::new("__bombay_remaining_interpretations", Span::mixed_site());
    let interpretation = named_send_interpretation(
        &loan_fields,
        field_types,
        &interpreter,
        &root_event,
        &path,
        behavior,
    );
    let source_settlements = field_types
        .iter()
        .map(|ty| quote!(<#ty as #behavior::SendSettlements>::Settlements))
        .collect::<Vec<_>>();
    let source_custody = field_types
        .iter()
        .map(|ty| quote!(<#ty as #behavior::SendSettlements>::SourceCustody))
        .collect::<Vec<_>>();
    let (_, source_owner) = source_product_custody(&source_settlements, &source_custody, behavior);
    let interpretation_custody = field_types
        .iter()
        .map(|ty| {
            quote!(
                ::core::option::Option<#behavior::InterpretationProgress<
                    #ty,
                    <#ty as #behavior::SendSettlements>::InterpretationCustody,
                    <#ty as #behavior::SendSettlements>::Settlements,
                >>
            )
        })
        .collect::<Vec<_>>();
    let completed_controls = fields.iter().map(|_| quote!(::core::option::Option::Some(#behavior::InterpretationProgress::Completed(_)))).collect::<Vec<_>>();
    let completed_fields = loan_fields
        .iter()
        .rev()
        .fold(quote!(()), |later, field| quote!((#field,#later)));
    let mut combine = quote!(#behavior::Interpretation::Complete(()));
    // This pure structural fold invokes no field/user method and crosses no await.
    for field in loan_fields.iter().rev() {
        combine = quote! {
            match (#field,#combine) {
                (#behavior::Interpretation::Complete(#field),#behavior::Interpretation::Complete(#remaining_interpretations)) => #behavior::Interpretation::Complete((#field,#remaining_interpretations)),
                (#behavior::Interpretation::Complete(#field) | #behavior::Interpretation::Corrupt(#field), #behavior::Interpretation::Corrupt(#remaining_interpretations)) |
                (#behavior::Interpretation::Corrupt(#field),#behavior::Interpretation::Complete(#remaining_interpretations)) => #behavior::Interpretation::Corrupt((#field,#remaining_interpretations)),
            }
        };
    }

    quote! {
        impl #effects_impl #behavior::SendEffects for #name #type_generics #effects_where {
            fn empty() -> Self {
                Self {
                    #(#fields: <#field_types as #behavior::SendEffects>::empty(),)*
                }
            }

            fn append(&mut self, other: Self) {
                #(
                    <#field_types as #behavior::SendEffects>::append(
                        &mut self.#fields,
                        other.#fields,
                    );
                )*
            }
        }

        impl #logical_impl #behavior::LogicalDeliveryProtocols
            for #name #type_generics #logical_where
        {
            type Protocols = #logical_protocols;
        }

        impl #lawful_impl #behavior::SendsFor<#event>
            for #name #type_generics #lawful_where
        {}

        impl #settlement_impl #behavior::SendSettlements
            for #name #type_generics #settlement_where
        {
            type Settlements = #settlement_type;
            type SourceCustody = #source_owner;
            type InterpretationCustody = (#(#interpretation_custody,)*);

            fn prepare_interpretation(progress: &mut ::core::option::Option<#behavior::InterpretationProgress<Self,Self::InterpretationCustody,Self::Settlements>>) {
                match progress.take() {
                    ::core::option::Option::Some(#behavior::InterpretationProgress::Original(original)) => {
                        *progress = ::core::option::Option::Some(#behavior::InterpretationProgress::Interpreting((
                            #(::core::option::Option::Some(#behavior::InterpretationProgress::Original(original.#fields)),)*
                        )));
                    }
                    retained => *progress = retained,
                }
            }
            fn finish_interpretation(progress: &mut ::core::option::Option<#behavior::InterpretationProgress<Self,Self::InterpretationCustody,Self::Settlements>>) {
                let ::core::option::Option::Some(#behavior::InterpretationProgress::Interpreting(custody)) = progress else { return; };
                let (#(#loan_fields,)*) = custody;
                if !matches!((#(&*#loan_fields,)*), (#(#completed_controls,)*)) { return; }
                match progress.take() {
                    ::core::option::Option::Some(#behavior::InterpretationProgress::Interpreting((
                        #(::core::option::Option::Some(#behavior::InterpretationProgress::Completed(#loan_fields)),)*
                    ))) => {
                        let completed = #combine;
                        *progress = ::core::option::Option::Some(#behavior::InterpretationProgress::Completed(match completed {
                            #behavior::Interpretation::Complete(#completed_fields) => #behavior::Interpretation::Complete(#settlement_name { #(#fields: #loan_fields,)* }),
                            #behavior::Interpretation::Corrupt(#completed_fields) => #behavior::Interpretation::Corrupt(#settlement_name { #(#fields: #loan_fields,)* }),
                        }));
                    }
                    retained => *progress = retained,
                }
            }
            fn unattempted(progress: &mut ::core::option::Option<#behavior::InterpretationProgress<Self,Self::InterpretationCustody,Self::Settlements>>) {
                <Self as #behavior::SendSettlements>::prepare_interpretation(progress);
                if let ::core::option::Option::Some(#behavior::InterpretationProgress::Interpreting(custody)) = progress {
                    let (#(#loan_fields,)*) = custody;
                    #(<#field_types as #behavior::SendSettlements>::unattempted(#loan_fields);)*
                }
                <Self as #behavior::SendSettlements>::finish_interpretation(progress);
            }
        }

        impl #interpretation_impl
            #behavior::InterpretSends<
                #interpreter,
                #root_event,
                #path,
            > for #name #type_generics #interpretation_where
        {
            fn interpret(
                progress: &mut ::core::option::Option<#behavior::InterpretationProgress<Self,Self::InterpretationCustody,Self::Settlements>>,
                interpreter: &mut #interpreter,
            ) -> impl ::core::future::Future<Output=()> + ::core::marker::Send {
                async move {
                    #interpretation
                }
            }
        }
    }
}

#[allow(
    clippy::too_many_lines,
    reason = "each generated contract is one facet of the same named send product"
)]
fn derive_send_product_contract(input: DeriveInput) -> Result<TokenStream2> {
    let behavior = behavior_crate()?;
    let mut uses = GenericUses::default();
    uses.visit_derive_input(&input);
    let send_input = uses.fresh("__BombayInput");
    let send_path = uses.fresh("__BombaySendPath");
    let name = input.ident;
    let generics = input.generics;
    let Data::Struct(data) = input.data else {
        return Err(Error::new_spanned(
            name,
            "send products must be named structs",
        ));
    };
    let Fields::Named(fields) = data.fields else {
        return Err(Error::new_spanned(
            name,
            "send products need named effect lanes",
        ));
    };
    if fields.named.is_empty() {
        return Err(Error::new_spanned(
            name,
            "empty send products must be omitted",
        ));
    }
    let mut parameters = Vec::new();
    for parameter in &generics.params {
        let GenericParam::Type(parameter) = parameter else {
            return Err(Error::new_spanned(
                parameter,
                "generic send products use only lane type parameters",
            ));
        };
        parameters.push(&parameter.ident);
    }
    let mut field_names = Vec::new();
    let mut field_types = Vec::new();
    for field in &fields.named {
        let Some(field_name) = field.ident.as_ref() else {
            return Err(Error::new_spanned(field, "send lanes must be named"));
        };
        let Type::Path(path) = &field.ty else {
            return Err(Error::new_spanned(
                &field.ty,
                "each send lane must be one product type parameter",
            ));
        };
        let Some(segment) = path.path.get_ident() else {
            return Err(Error::new_spanned(
                &field.ty,
                "each send lane must be one product type parameter",
            ));
        };
        if path.qself.is_some() || !parameters.iter().any(|parameter| *parameter == segment) {
            return Err(Error::new_spanned(
                &field.ty,
                "each send lane must be one product type parameter",
            ));
        }
        field_names.push(field_name);
        field_types.push(&field.ty);
    }
    let (_, type_generics, _) = generics.split_for_impl();
    let settled_parameters = parameters
        .iter()
        .map(|parameter| quote!(<#parameter as #behavior::SendSettlements>::Settlements));
    let settlement_type = quote!(#name<#(#settled_parameters),*>);
    let send_contract = named_send_contract(
        &name,
        &generics,
        &field_names,
        &field_types,
        &settlement_type,
        &name,
        &behavior,
    );
    let settled_fields = field_types
        .iter()
        .map(|field_ty| (*field_ty).clone())
        .collect::<Vec<_>>();
    let settlement_owner = quote!(#name #type_generics);
    let settlement_contract = named_settlement_contract(
        &name,
        &settlement_owner,
        &generics,
        &field_names,
        &settled_fields,
        &behavior,
    );
    let send_inputs =
        field_names
            .iter()
            .zip(&field_types)
            .enumerate()
            .map(|(index, (field, field_ty))| {
                let mut insertion_generics = generics.clone();
                insertion_generics.params.push(parse_quote!(#send_input));
                insertion_generics.params.push(parse_quote!(#send_path));
                insertion_generics
                    .make_where_clause()
                    .predicates
                    .push(parse_quote!(
                        #field_ty: #behavior::SendInput<#send_input, #send_path>
                    ));
                let (insertion_impl, _, insertion_where) = insertion_generics.split_for_impl();
                // Disjoint existing witnesses identify a field without changing the
                // field's own semantic lane or choosing between duplicate inputs.
                let path = (0..index).fold(
                    quote!((#behavior::Own, #send_path)),
                    |path, _| quote!(#behavior::Inside<#path>),
                );
                quote! {
                    impl #insertion_impl #behavior::SendInput<#send_input, #path>
                        for #name #type_generics #insertion_where
                    {
                        fn emit(&mut self, input: #send_input) {
                            <#field_ty as #behavior::SendInput<
                                #send_input,
                                #send_path,
                            >>::emit(&mut self.#field, input);
                        }
                    }
                }
            });
    Ok(quote!(#send_contract #settlement_contract #(#send_inputs)*))
}

/// Derive the ordered send and settlement contracts for a named generic
/// product whose fields are its lane type parameters.
///
/// Each field also forwards its existing typed SendInput capability. Unique
/// inputs infer their lane through nested products and wrappers; duplicate
/// capabilities remain ambiguous. Insertion moves one original input into one
/// lane, retaining all other fields and their ordering. Nominal actor products
/// keep their separately generated semantic lane contracts. Caller parameter
/// names, including raw identifiers, need no reserved implementation prefix;
/// generated private parameters avoid declarations and referenced type names.
#[proc_macro_derive(SendProduct)]
pub fn derive_send_product(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    derive_send_product_contract(input)
        .unwrap_or_else(Error::into_compile_error)
        .into()
}

#[allow(
    clippy::too_many_lines,
    reason = "the generated nominal product keeps every structural trait implementation adjacent"
)]
fn generate_sends(
    product: Option<SendsSpec>,
    actor: &Ident,
    item: &ItemImpl,
    behavior: &TokenStream2,
) -> (TokenStream2, TokenStream2) {
    let (product, visibility) = match product {
        None => return (quote!(#behavior::NoSends), quote!()),
        Some(SendsSpec::Existing(ty)) => return (quote!(#ty), quote!()),
        Some(SendsSpec::Generated {
            product,
            visibility,
        }) => (product, visibility),
    };
    let mut uses = GenericUses::default();
    uses.visit_item_impl(item);
    for field in &product.fields {
        uses.visit_type(&field.ty);
    }
    let send_input = uses.fresh("__BombayInput");
    let address = uses.fresh("__BombayAddress");
    let phase = uses.fresh("__BombayPh");
    let birth = uses.fresh("__BombayBirth");
    let name = format_ident!("{}Sends", actor);
    let settlements_name = format_ident!("{}Settlements", actor);
    let field_names: Vec<_> = product.fields.iter().map(|field| &field.name).collect();
    let field_types: Vec<_> = product.fields.iter().map(|field| &field.ty).collect();
    let lane_names: Vec<_> = field_names
        .iter()
        .map(|field| lane_name(&name, field))
        .collect();
    let actions_name = format_ident!("{}Actions", actor);
    let action_methods: Vec<_> = field_names
        .iter()
        .map(|field| {
            let field = field.to_string();
            format_ident!("send_{}", field.trim_start_matches("r#"))
        })
        .collect();
    let product_generics = product_generics(item, &product.fields);
    let (_, type_generics, _) = product_generics.split_for_impl();
    let generics = &product_generics;
    let actor_type = &item.self_ty;
    let mut action_trait_generics = product_generics.clone();
    action_trait_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#actor_type: ::core::marker::Sized));

    let action_trait_methods =
        action_methods
            .iter()
            .zip(lane_names.iter())
            .map(|(method, lane)| {
                quote! {
                    /// Append one value to this generated semantic send lane.
                    #[must_use]
                    fn #method<#send_input>(self, input: #send_input) -> Self
                    where
                        Self: #behavior::AppendSend<#send_input, #lane>;
                }
            });

    let action_impl_methods = action_methods
        .iter()
        .zip(lane_names.iter())
        .map(|(method, lane)| {
            quote! {
                fn #method<#send_input>(self, input: #send_input) -> Self
                where
                    Self: #behavior::AppendSend<#send_input, #lane>,
                {
                    <Self as #behavior::AppendSend<#send_input, #lane>>::append_send(
                        self,
                        input,
                    )
                }
            }
        });

    let mut actions_impl_generics = product_generics.clone();
    actions_impl_generics.params.push(parse_quote!(#address));
    actions_impl_generics.params.push(parse_quote!(#phase));
    actions_impl_generics.params.push(parse_quote!(#birth));
    actions_impl_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#address: #behavior::Address));
    actions_impl_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#birth: #behavior::BirthMode));
    actions_impl_generics
        .make_where_clause()
        .predicates
        .push(parse_quote!(#actor_type: ::core::marker::Sized));
    let (actions_impl_generics, _, actions_where_clause) = actions_impl_generics.split_for_impl();

    let send_impls = lane_names
        .iter()
        .zip(field_names.iter())
        .zip(field_types.iter())
        .map(|((lane, field), field_ty)| {
            let mut generics = product_generics.clone();
            generics.params.push(parse_quote!(#send_input));
            generics.make_where_clause().predicates.push(parse_quote!(
                #field_ty: #behavior::SendInput<#send_input, #behavior::Own>
            ));
            let (impl_generics, _, where_clause) = generics.split_for_impl();
            quote! {
                impl #impl_generics #behavior::SendInput<#send_input, #lane>
                    for #name #type_generics #where_clause
                {
                    fn emit(&mut self, input: #send_input) {
                        <#field_ty as #behavior::SendInput<
                            #send_input,
                            #behavior::Own,
                        >>::emit(&mut self.#field, input);
                    }
                }
            }
        });

    let mut settlement_generics = product_generics.clone();
    for field_ty in &field_types {
        settlement_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(#field_ty: #behavior::SendSettlements));
    }
    let (settlement_impl_generics, settlement_type_generics, settlement_where_clause) =
        settlement_generics.split_for_impl();
    let settlement_type = quote!(#settlements_name #settlement_type_generics);
    let send_contract = named_send_contract(
        &name,
        &product_generics,
        &field_names,
        &field_types,
        &settlement_type,
        &settlements_name,
        behavior,
    );
    let settled_fields = field_types
        .iter()
        .map(|field_ty| parse_quote!(<#field_ty as #behavior::SendSettlements>::Settlements))
        .collect::<Vec<Type>>();
    let settlement_contract = named_settlement_contract(
        &settlements_name,
        &settlement_type,
        &settlement_generics,
        &field_names,
        &settled_fields,
        behavior,
    );

    let items = quote! {
        #(#visibility enum #lane_names {})*

        #visibility struct #name #generics {
            #(pub #field_names: #field_types,)*
        }

        #visibility struct #settlements_name #settlement_impl_generics #settlement_where_clause {
            #(
                pub #field_names: <#field_types as #behavior::SendSettlements>::Settlements,
            )*
        }

        #settlement_contract

        /// Fluent, statically routed send-lane methods for this behavior's
        /// generated action product.
        #visibility trait #actions_name #action_trait_generics: ::core::marker::Sized {
            #(#action_trait_methods)*
        }

        impl #actions_impl_generics #actions_name #type_generics
            for #behavior::Actions<
                #address,
                #phase,
                #name #type_generics,
                #birth,
            >
            #actions_where_clause
        {
            #(#action_impl_methods)*
        }

        #send_contract

        #(#send_impls)*
    };
    (quote!(#name #type_generics), items)
}

fn generate_births(
    product: Option<BirthsSpec>,
    disposition: Option<CreationSettlementDisposition>,
    actor: &Ident,
    _addr: &Type,
    item: &ItemImpl,
    behavior: &TokenStream2,
) -> (TokenStream2, TokenStream2) {
    let product = match product {
        None => return (quote!(#behavior::NoBirths), quote!()),
        Some(BirthsSpec::Existing(ty)) => {
            if disposition.is_none() {
                return (quote!(#ty), quote!());
            }
            let child = quote!(<#ty as #behavior::BirthMode>::Child);
            let birth = match disposition {
                Some(CreationSettlementDisposition::ReturnToCreator) => {
                    quote!(#behavior::Births<#child>)
                }
                Some(CreationSettlementDisposition::RetainForRetirement) => {
                    quote!(#behavior::RetirementBirths<#child>)
                }
                None => unreachable!("a no-birth declaration has no settlement disposition"),
            };
            return (birth, quote!());
        }
        Some(BirthsSpec::Generated(product)) => product,
    };
    let name = format_ident!("{}Children", actor);
    let roles_name = format_ident!("{}Child", actor);
    let role_names = product
        .fields
        .iter()
        .map(|field| lane_name(&name, &field.name))
        .collect::<Vec<_>>();
    let role_values = product
        .fields
        .iter()
        .map(|field| format_ident!("{}", pascal_name(&field.name)))
        .collect::<Vec<_>>();
    let declared_child_types = product
        .fields
        .iter()
        .map(|field| &field.ty)
        .collect::<Vec<_>>();
    let role_positions = (0..product.fields.len())
        .map(|index| {
            (0..(product.fields.len() - index - 1)).fold(
                quote!(#behavior::ChildHead),
                |position, _| quote!(#behavior::ChildTail<#position>),
            )
        })
        .collect::<Vec<_>>();
    let product_generics = product_generics(item, &product.fields);
    let (_, type_generics, _) = product_generics.split_for_impl();
    let generics = &product_generics;
    let parent = &item.self_ty;
    let (parent_impl_generics, _, parent_where_clause) = item.generics.split_for_impl();
    let choice = match declared_child_types.as_slice() {
        [child] => quote!(#child),
        children => children.iter().fold(
            quote!(#behavior::Never),
            |tail, child| quote!(#behavior::ChildChoice<#child, #tail>),
        ),
    };
    let birth = match disposition {
        Some(CreationSettlementDisposition::ReturnToCreator) => {
            quote!(#behavior::Births<#name #type_generics>)
        }
        Some(CreationSettlementDisposition::RetainForRetirement) => {
            quote!(#behavior::RetirementBirths<#name #type_generics>)
        }
        None => unreachable!("a generated birth product has an explicit settlement disposition"),
    };
    (
        birth,
        quote! {
            pub type #name #generics = #choice;

            #(
                #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
                pub struct #role_names;

                impl #parent_impl_generics #behavior::ChildRole<#parent> for #role_names
                    #parent_where_clause
                {
                    type Child = #declared_child_types;
                    type Position = #role_positions;
                }

                impl #parent_impl_generics #behavior::ChildOccurrence<#parent> for #role_names
                    #parent_where_clause
                {
                    type Resolution = #behavior::DeclaredChildOccurrence;
                }
            )*

            pub struct #roles_name;

            #[allow(
                non_upper_case_globals,
                reason = "generated role values retain the application-authored field spelling"
            )]
            impl #roles_name {
                #(pub const #role_values: #role_names = #role_names;)*
            }

        },
    )
}

/// Generate the mechanical `Behavior` implementation for a normal inherent
/// impl containing `receive(&mut self, from, message)` and, optionally,
/// `init(&mut self)`. Omitting `init` selects the behavior algebra's empty
/// initialization transition. The original impl and methods are preserved
/// unchanged. Generated send contracts preserve caller parameter and referenced
/// type names; public product and lane names remain derived from the actor.
///
#[proc_macro_attribute]
#[allow(
    clippy::too_many_lines,
    reason = "validation and the one coherent Behavior expansion remain in one entry point"
)]
pub fn behavior(args: TokenStream, item: TokenStream) -> TokenStream {
    let args = parse_macro_input!(args as BehaviorArgs);
    let item = parse_macro_input!(item as ItemImpl);

    if item.trait_.is_some() {
        return Error::new_spanned(
            &item,
            "#[behavior] applies to an inherent impl, not a trait impl",
        )
        .to_compile_error()
        .into();
    }

    let init = item.items.iter().find_map(|item| match item {
        ImplItem::Fn(method) if method.sig.ident == "init" => Some(method),
        _ => None,
    });
    let receive = item.items.iter().find_map(|item| match item {
        ImplItem::Fn(method) if method.sig.ident == "receive" => Some(method),
        _ => None,
    });
    let creations_settled = item.items.iter().find_map(|item| match item {
        ImplItem::Fn(method) if method.sig.ident == "creations_settled" => Some(method),
        _ => None,
    });
    let Some(receive) = receive else {
        return Error::new_spanned(
            &item.self_ty,
            "#[behavior] requires a receive(&mut self, from, message) method",
        )
        .to_compile_error()
        .into();
    };
    if let Err(error) = init
        .map_or(Ok(()), validate_receiver)
        .and_then(|()| validate_receiver(receive))
    {
        return error.to_compile_error().into();
    }
    if let Some(init) = init
        && init.sig.inputs.len() != 1
    {
        return Error::new_spanned(&init.sig, "init must accept exactly &mut self")
            .to_compile_error()
            .into();
    }
    if receive.sig.inputs.len() != 3 {
        return Error::new_spanned(
            &receive.sig,
            "receive must accept exactly &mut self, from, and message",
        )
        .to_compile_error()
        .into();
    }
    match (args.creation_settlements, creations_settled) {
        (Some(CreationSettlementDisposition::ReturnToCreator), Some(method)) => {
            if let Err(error) = validate_receiver(method) {
                return error.to_compile_error().into();
            }
            if method.sig.inputs.len() != 2 {
                return Error::new_spanned(
                    &method.sig,
                    "creations_settled must accept exactly &mut self and one CreationsSettled value",
                )
                .to_compile_error()
                .into();
            }
        }
        (Some(CreationSettlementDisposition::ReturnToCreator), None) => {
            return Error::new_spanned(
                &item.self_ty,
                "`creation_settlements = return_to_creator` requires a creations_settled transition",
            )
            .to_compile_error()
            .into();
        }
        (Some(CreationSettlementDisposition::RetainForRetirement), Some(method)) => {
            return Error::new_spanned(
                &method.sig,
                "retirement-owned creation settlements do not enter a creations_settled transition",
            )
            .to_compile_error()
            .into();
        }
        (Some(CreationSettlementDisposition::RetainForRetirement), None) | (None, None) => {}
        (None, Some(_)) => {}
    }

    let BehaviorArgs {
        addr,
        message,
        sends,
        births,
        creation_settlements,
        error,
    } = args;
    let self_ty = &item.self_ty;
    let Type::Path(self_path) = self_ty.as_ref() else {
        return Error::new_spanned(self_ty, "#[behavior] requires a nominal actor type")
            .to_compile_error()
            .into();
    };
    let Some(self_name) = self_path.path.segments.last().map(|segment| &segment.ident) else {
        return Error::new_spanned(self_ty, "#[behavior] requires a nominal actor type")
            .to_compile_error()
            .into();
    };
    let (impl_generics, _, where_clause) = item.generics.split_for_impl();
    let behavior = match behavior_crate() {
        Ok(behavior) => behavior,
        Err(error) => return error.to_compile_error().into(),
    };
    let error = error.map_or_else(|| quote!(#behavior::Never), |error| quote!(#error));
    let initialize = init.map_or_else(
        || quote!(::core::result::Result::Ok(#behavior::Actions::cont())),
        |_| quote!(<#self_ty>::init(self)),
    );

    let mut behavior_generics = item.generics.clone();
    if let (Some(BirthsSpec::Existing(mode)), None) = (&births, creation_settlements) {
        behavior_generics
            .make_where_clause()
            .predicates
            .push(parse_quote!(
                #mode: #behavior::BirthMode<Child = #behavior::Never>
            ));
    }
    let (behavior_impl_generics, _, behavior_where_clause) = behavior_generics.split_for_impl();
    let (sends_ty, sends_items) = generate_sends(sends, self_name, &item, &behavior);
    let (births_ty, births_items) = generate_births(
        births,
        creation_settlements,
        self_name,
        &addr,
        &item,
        &behavior,
    );
    let (event_ty, transition) = match creation_settlements {
        Some(CreationSettlementDisposition::ReturnToCreator) => {
            let child = quote!(<#births_ty as #behavior::BirthMode>::Child);
            (
                quote!(#behavior::CreationEvent<#addr, #child, #message>),
                quote! {
                    match event {
                        #behavior::CreationEvent::Settlements(settlements) => {
                            <#self_ty>::creations_settled(self, settlements)
                        }
                        #behavior::CreationEvent::User(event) => {
                            <#self_ty>::receive(self, event.from, event.message)
                        }
                    }
                },
            )
        }
        Some(CreationSettlementDisposition::RetainForRetirement) | None => (
            quote!(#behavior::User<#addr, #message>),
            quote!(<#self_ty>::receive(self, event.from, event.message)),
        ),
    };

    quote! {
        #sends_items
        #births_items
        #item

        impl #impl_generics #behavior::Protocol for #self_ty #where_clause {
            type Addr = #addr;
            type Msg = #message;
        }

        impl #behavior_impl_generics #behavior::Behavior for #self_ty #behavior_where_clause {
            type Protocol = Self;
            type Event = #event_ty;
            type Sends = #sends_ty;
            type Ph = #behavior::Never;
            type Error = #error;
            type Birth = #births_ty;

            fn init(
                &mut self,
                _: #behavior::InitializationTurn,
            ) -> #behavior::BehaviorActed<Self> {
                #initialize
            }

            fn transition(
                &mut self,
                _: #behavior::ActiveTurn,
                event: Self::Event,
            ) -> #behavior::BehaviorActed<Self> {
                #transition
            }
        }

        impl #impl_generics #behavior::BehaviorBase for #self_ty #where_clause {
            type Base = Self;

            fn base(&self) -> &Self {
                self
            }
        }
    }
    .into()
}

/// Derive one pool worker's ordinary actor protocol and behavior from its
/// assignment transition.
///
/// This attribute owns syntax only. The generated send product is the existing
/// typed parent request carrying the opaque completion produced by
/// `Assignment::complete`; assignment authority and delivery remain owned by
/// the Behavior Actors pool protocol and the runtime interpreter.
#[proc_macro_attribute]
pub fn pool_worker(args: TokenStream, item: TokenStream) -> TokenStream {
    let PoolWorkerArgs { addr, result } = parse_macro_input!(args as PoolWorkerArgs);
    let mut item = parse_macro_input!(item as ItemImpl);

    if item.trait_.is_some() {
        return Error::new_spanned(
            &item,
            "#[pool_worker] applies to an inherent impl, not a trait impl",
        )
        .to_compile_error()
        .into();
    }

    let self_ty = item.self_ty.clone();
    if !matches!(self_ty.as_ref(), Type::Path(path) if path.qself.is_none()) {
        return Error::new_spanned(&self_ty, "#[pool_worker] requires a nominal worker type")
            .to_compile_error()
            .into();
    }

    let actors = match actors_crate() {
        Ok(actors) => actors,
        Err(error) => return error.to_compile_error().into(),
    };
    let behavior = match behavior_crate() {
        Ok(behavior) => behavior,
        Err(error) => return error.to_compile_error().into(),
    };
    let assignment = {
        let mut transitions = item.items.iter_mut().filter_map(|item| match item {
            ImplItem::Fn(method) if method.sig.ident == "transition" => Some(method),
            _ => None,
        });
        let Some(transition) = transitions.next() else {
            return Error::new_spanned(
                &self_ty,
                "#[pool_worker] requires transition(&mut self, Assignment<Job>)",
            )
            .to_compile_error()
            .into();
        };
        if let Some(duplicate) = transitions.next() {
            return Error::new_spanned(
                &duplicate.sig,
                "#[pool_worker] accepts exactly one transition method",
            )
            .to_compile_error()
            .into();
        }
        let assignment = match pool_worker_assignment(transition) {
            Ok(assignment) => assignment,
            Err(error) => return error.to_compile_error().into(),
        };
        transition.sig.output = parse_quote!(-> #behavior::BehaviorActed<Self>);
        assignment
    };
    let (impl_generics, _, where_clause) = item.generics.split_for_impl();

    quote! {
        #item

        impl #impl_generics #behavior::Protocol for #self_ty #where_clause {
            type Addr = #addr;
            type Msg = #assignment;
        }

        impl #impl_generics #behavior::Behavior for #self_ty #where_clause {
            type Protocol = Self;
            type Event = #behavior::User<#addr, #assignment>;
            type Sends = #behavior::InterpreterRequests<
                #behavior::ReportToParent<#actors::pool::Completion<#result>>
            >;
            type Ph = #behavior::Never;
            type Error = #behavior::Never;
            type Birth = #behavior::NoBirths;

            fn transition(
                &mut self,
                _: #behavior::ActiveTurn,
                event: Self::Event,
            ) -> #behavior::BehaviorActed<Self> {
                <#self_ty>::transition(self, event.message)
            }
        }

        impl #impl_generics #behavior::BehaviorBase for #self_ty #where_clause {
            type Base = Self;

            fn base(&self) -> &Self {
                self
            }
        }
    }
    .into()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn permutations(values: &mut [&str], at: usize, output: &mut Vec<String>) {
        if at == values.len() {
            output.push(values.join(", "));
            return;
        }
        for index in at..values.len() {
            values.swap(at, index);
            permutations(values, at + 1, output);
            values.swap(at, index);
        }
    }

    #[test]
    fn every_argument_order_parses() {
        let mut declarations = [
            "addr = u64",
            "message = String",
            "sends = { first: Vec<u8>, second: Vec<u16> }",
            "births = { first: u8, second: u16 }",
            "creation_settlements = retain_for_retirement",
            "error = String",
        ];
        let mut cases = Vec::new();
        permutations(&mut declarations, 0, &mut cases);
        assert_eq!(cases.len(), 720);
        for case in cases {
            syn::parse_str::<BehaviorArgs>(&case)
                .unwrap_or_else(|error| panic!("failed to parse `{case}`: {error}"));
        }
    }

    #[test]
    fn capability_omission_and_trailing_comma_parse() {
        syn::parse_str::<BehaviorArgs>("message = (), addr = u8,")
            .expect("only required protocol declarations are sufficient");
        for declaration in ["NoBirths", "behavior::NoBirths", "EmptyBirths"] {
            syn::parse_str::<BehaviorArgs>(&format!(
                "message = (), addr = u8, births = {declaration}"
            ))
            .unwrap_or_else(|error| panic!("explicit no-birth declaration did not parse: {error}"));
        }
    }

    #[test]
    fn invalid_declaration_states_are_rejected() {
        for case in [
            "message = ()",
            "addr = u8",
            "addr = u8, message = (), addr = u16",
            "addr = u8, message = (), unknown = u8",
            "addr = u8, message = (), sends = {}",
            "addr = u8, message = (), births = {}",
            "addr = u8, message = (), births = {}, creation_settlements = retain_for_retirement",
            "addr = u8, message = (), sends = { same: Vec<u8>, same: Vec<u8> }",
            "addr = u8, message = (), births = { same: u8, same: u16 }, creation_settlements = retain_for_retirement",
            "addr = u8, message = (), creation_settlements = retain_for_retirement",
            "addr = u8, message = (), births = { child: u8 }, creation_settlements = discard",
            "addr = u8, message = (), births = { child: u8 }, creation_settlements = retain_for_retirement, creation_settlements = return_to_creator",
        ] {
            assert!(
                syn::parse_str::<BehaviorArgs>(case).is_err(),
                "invalid declaration parsed: `{case}`"
            );
        }
    }

    #[test]
    fn pool_worker_arguments_require_one_address_and_result() {
        for valid in [
            "addr = u64, result = String",
            "result = String, addr = u64,",
        ] {
            syn::parse_str::<PoolWorkerArgs>(valid)
                .unwrap_or_else(|error| panic!("failed to parse `{valid}`: {error}"));
        }
        for invalid in [
            "addr = u64",
            "result = String",
            "addr = u64, result = String, addr = u32",
            "addr = u64, result = String, result = u8",
            "addr = u64, result = String, message = u8",
        ] {
            assert!(
                syn::parse_str::<PoolWorkerArgs>(invalid).is_err(),
                "invalid pool worker arguments parsed: `{invalid}`"
            );
        }
    }

    #[test]
    fn pool_worker_transition_requires_the_domain_source_shape() {
        let valid: ItemImpl = syn::parse_str(
            "impl Worker { fn transition(&mut self, assignment: Assignment<Job>) \
             -> WorkerActed<Self> { result() } }",
        )
        .expect("valid inherent worker declaration parses");
        let method = valid
            .items
            .iter()
            .find_map(|item| match item {
                ImplItem::Fn(method) => Some(method),
                _ => None,
            })
            .expect("fixture declares one method");
        let assignment = pool_worker_assignment(method)
            .unwrap_or_else(|error| panic!("valid worker transition rejected: {error}"));
        assert_eq!(quote!(#assignment).to_string(), "Assignment < Job >");

        for invalid in [
            "impl Worker { fn transition(self, assignment: Assignment<Job>) -> WorkerActed<Self> { result() } }",
            "impl Worker { async fn transition(&mut self, assignment: Assignment<Job>) -> WorkerActed<Self> { result() } }",
            "impl Worker { fn transition(&mut self, job: Job) -> WorkerActed<Self> { result() } }",
            "impl Worker { fn transition(&mut self, assignment: Assignment<Job>) -> WorkerActed<Job> { result() } }",
            "impl Worker { fn transition(&mut self, assignment: Assignment<Job>) -> Result<(), ()> { result() } }",
        ] {
            let declaration: ItemImpl = syn::parse_str(invalid)
                .unwrap_or_else(|error| panic!("invalid fixture did not parse: {error}"));
            let method = declaration
                .items
                .iter()
                .find_map(|item| match item {
                    ImplItem::Fn(method) => Some(method),
                    _ => None,
                })
                .expect("fixture declares one method");
            assert!(
                pool_worker_assignment(method).is_err(),
                "invalid pool worker transition was accepted: `{invalid}`"
            );
        }
    }
}