Skip to main content

hyprstream_rpc_derive/codegen/
handler.rs

1//! Handler trait, dispatch function, and response serializer generation.
2
3use proc_macro2::TokenStream;
4use quote::{format_ident, quote};
5
6use crate::resolve::ResolvedSchema;
7use crate::schema::types::*;
8use crate::util::*;
9
10/// Parse the `$scope`/`$capability` value into the action name for auth dispatch.
11///
12/// The value is a `ScopeAction` enumerant (e.g. "write", "query", "manage") — the
13/// unified action vocabulary (S3, #547). Returns `None` only for a `$scopeExempt`
14/// method (empty scope), which generates no authorize() gate.
15fn parse_scope_for_auth(scope: &str) -> Option<&str> {
16    if scope.is_empty() {
17        None
18    } else {
19        Some(scope)
20    }
21}
22
23/// Check if a request variant is a streaming redirect (response type == StreamInfo).
24///
25/// Streaming variants return `(StreamInfo, Continuation)` from handler
26/// methods instead of the `ResponseVariant` enum. The dispatch function serializes
27/// the StreamInfo into the appropriate response variant and wraps the
28/// continuation in `Some()` for post-REP execution.
29///
30/// For top-level dispatch, response variants are named `{requestName}Result`.
31/// For scoped dispatch, response variants match the request variant name directly.
32fn is_streaming_variant(req_variant: &UnionVariant, response_variants: &[UnionVariant]) -> bool {
33    let response_name = format!("{}Result", req_variant.name);
34    response_variants
35        .iter()
36        .any(|rv| rv.name == response_name && rv.type_name == "StreamInfo")
37}
38
39/// Check if a request variant is streaming within a scoped context.
40///
41/// In scoped contexts, the response variant name matches the request variant name directly
42/// (not `{name}Result`).
43fn is_scoped_streaming_variant(
44    req_variant: &UnionVariant,
45    response_variants: &[UnionVariant],
46) -> bool {
47    response_variants
48        .iter()
49        .any(|rv| rv.name == req_variant.name && rv.type_name == "StreamInfo")
50}
51
52/// Get the response variant name for a streaming request variant.
53fn streaming_response_variant_name(req_variant: &UnionVariant) -> String {
54    format!("{}Result", req_variant.name)
55}
56
57/// Generate handler trait + dispatch function + response serializer.
58///
59/// When scoped clients are present, also generates per-scope handler traits,
60/// dispatch functions, and response serializers. The main handler trait becomes
61/// a super-trait requiring all scope handler traits.
62pub fn generate_handler(
63    service_name: &str,
64    resolved: &ResolvedSchema,
65    scope_handlers: bool,
66) -> TokenStream {
67    let pascal = to_pascal_case(service_name);
68    let capnp_mod = format_ident!("{}_capnp", service_name);
69
70    // Only generate scope sub-traits when opt-in via scope_handlers flag.
71    // Always pass full scoped_clients for variant recognition (scoped variants
72    // get raw-bytes handlers when scope_handlers is false).
73    let scope_traits = if scope_handlers {
74        generate_scope_handler_traits(&resolved.raw.scoped_clients, resolved)
75    } else {
76        TokenStream::new()
77    };
78
79    let scope_serializers = if scope_handlers {
80        generate_scope_response_serializers(
81            &pascal,
82            &capnp_mod,
83            &resolved.raw.scoped_clients,
84            resolved,
85        )
86    } else {
87        TokenStream::new()
88    };
89
90    let scope_dispatchers = if scope_handlers {
91        generate_scope_dispatch_fns(&pascal, &capnp_mod, &resolved.raw.scoped_clients, resolved)
92    } else {
93        TokenStream::new()
94    };
95
96    let handler_trait = generate_handler_trait(
97        &pascal,
98        &resolved.raw.request_variants,
99        &resolved.raw.response_variants,
100        &resolved.raw.scoped_clients,
101        resolved,
102        scope_handlers,
103    );
104
105    let dispatch_fn = generate_dispatch_fn(
106        &pascal,
107        &capnp_mod,
108        &resolved.raw.request_variants,
109        &resolved.raw.response_variants,
110        &resolved.raw.scoped_clients,
111        resolved,
112        scope_handlers,
113    );
114
115    let serializer = generate_response_serializer(
116        &pascal,
117        &capnp_mod,
118        &resolved.raw.response_variants,
119        resolved,
120    );
121
122    // The ONE bounded signed-body decoder (v16 §5.2): decodes the request
123    // exactly once and derives the full nested method leaf path. Services wire
124    // it through `RequestService::decode_request_body`; the same decoded body
125    // then feeds generated policy, the dispatch MAC PEP, and dispatch below.
126    let body_decoder = super::leaf::generate_body_decoder(service_name, resolved);
127
128    // The method-policy inventory rows (v16 §6.1) — same tree walk as the
129    // decoder, submitted to the process-wide inventory for startup install.
130    let policy_rows = super::leaf::generate_method_policy_rows(service_name, resolved);
131
132    quote! {
133        #scope_traits
134        #scope_serializers
135        #scope_dispatchers
136        #handler_trait
137        #dispatch_fn
138        #serializer
139        #body_decoder
140        #policy_rows
141    }
142}
143
144// ─────────────────────────────────────────────────────────────────────────────
145// Handler Trait
146// ─────────────────────────────────────────────────────────────────────────────
147
148fn generate_handler_trait(
149    pascal: &str,
150    request_variants: &[UnionVariant],
151    response_variants: &[UnionVariant],
152    scoped_clients: &[ScopedClient],
153    resolved: &ResolvedSchema,
154    scope_handlers: bool,
155) -> TokenStream {
156    let trait_name = format_ident!("{}Handler", pascal);
157    let response_type = format_ident!("{}ResponseVariant", pascal);
158    let doc = format!("Generated handler trait for the {pascal} service.");
159    let scoped_names: Vec<&str> = scoped_clients
160        .iter()
161        .map(|sc| sc.factory_name.as_str())
162        .collect();
163
164    if scope_handlers {
165        // Default authorize() method — services override to enforce policy.
166        let authorize_method = quote! {
167            /// Authorize an operation on a resource. Override to enforce policy.
168            ///
169            /// Called by generated dispatch functions before handler methods. Every
170            /// method carries a mandatory `$scope`/`$capability` annotation (S3, #547)
171            /// except explicit `$scopeExempt` methods, which are not gated here.
172            /// Default: deny all. Services MUST override to enable access.
173            async fn authorize(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, resource: &str, operation: &str) -> anyhow::Result<()> {
174                let _ = (ctx, resource, operation);
175                anyhow::bail!("Authorization not implemented for this service")
176            }
177
178            /// Check if a specific resource+operation is authorized (non-failing).
179            ///
180            /// Useful for filtering list results per-resource.
181            /// Default delegates to `authorize().is_ok()`.
182            async fn is_resource_authorized(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, resource: &str, operation: &str) -> bool {
183                self.authorize(ctx, resource, operation).await.is_ok()
184            }
185        };
186
187        // New pattern: scope sub-traits handle inner dispatch.
188        // Check if ALL variants are scoped → pure super-trait with no methods.
189        let all_scoped = !scoped_clients.is_empty()
190            && request_variants.iter().all(|v| {
191                scoped_names.contains(&v.name.as_str()) || is_union_only_struct_variant(v, resolved)
192            });
193
194        if all_scoped {
195            let scope_bounds: Vec<TokenStream> = scoped_clients
196                .iter()
197                .map(|sc| {
198                    let scope_trait = format_ident!("{}Handler", to_pascal_case(&sc.factory_name));
199                    quote! { #scope_trait }
200                })
201                .collect();
202
203            return quote! {
204                #[doc = #doc]
205                #[async_trait::async_trait(?Send)]
206                pub trait #trait_name: #(#scope_bounds)+* {
207                    #authorize_method
208                }
209            };
210        }
211
212        // Mixed: non-scoped methods + scope sub-trait bounds
213        let methods: Vec<TokenStream> = request_variants
214            .iter()
215            .filter(|v| !scoped_names.contains(&v.name.as_str()))
216            .map(|v| {
217                let method_name = format_ident!("handle_{}", resolved.name(&v.name).snake);
218
219                if is_union_only_struct_variant(v, resolved) {
220                    let doc_str = format!("Handle `{}` request (raw bytes for inner dispatch).", v.name);
221                    return quote! {
222                        #[doc = #doc_str]
223                        async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64, body: &hyprstream_rpc::service::DecodedRequestBody) -> anyhow::Result<Vec<u8>>;
224                    };
225                }
226
227                let params = handler_method_params(v, resolved);
228
229                // Streaming variants (response == StreamInfo) return a tuple with mandatory continuation.
230                // The continuation is spawned by RequestLoop AFTER the REP is sent.
231                if is_streaming_variant(v, response_variants) {
232                    let doc_str = format!("Handle `{}` streaming request. Returns (StreamInfo, mandatory continuation).", v.name);
233                    return quote! {
234                        #[doc = #doc_str]
235                        async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64 #(, #params)*) -> anyhow::Result<(StreamInfo, hyprstream_rpc::service::Continuation)>;
236                    };
237                }
238
239                let doc_str = format!("Handle `{}` request.", v.name);
240
241                quote! {
242                    #[doc = #doc_str]
243                    async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64 #(, #params)*) -> anyhow::Result<#response_type>;
244                }
245            })
246            .collect();
247
248        let scope_bounds: Vec<TokenStream> = scoped_clients
249            .iter()
250            .map(|sc| {
251                let scope_trait = format_ident!("{}Handler", to_pascal_case(&sc.factory_name));
252                quote! { #scope_trait }
253            })
254            .collect();
255
256        quote! {
257            #[doc = #doc]
258            #[async_trait::async_trait(?Send)]
259            pub trait #trait_name: #(#scope_bounds)+* {
260                #authorize_method
261                #(#methods)*
262            }
263        }
264    } else {
265        // Old pattern: scoped variants get raw-bytes handler methods.
266        let methods: Vec<TokenStream> = request_variants
267            .iter()
268            .map(|v| {
269                let method_name = format_ident!("handle_{}", resolved.name(&v.name).snake);
270
271                // Scoped or union-only struct → raw bytes passthrough
272                if scoped_names.contains(&v.name.as_str()) || is_union_only_struct_variant(v, resolved) {
273                    let doc_str = format!("Handle `{}` request (raw bytes for inner dispatch).", v.name);
274                    return quote! {
275                        #[doc = #doc_str]
276                        async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64, body: &hyprstream_rpc::service::DecodedRequestBody) -> anyhow::Result<Vec<u8>>;
277                    };
278                }
279
280                let params = handler_method_params(v, resolved);
281
282                // Streaming variants (response == StreamInfo) return a tuple with mandatory continuation.
283                if is_streaming_variant(v, response_variants) {
284                    let doc_str = format!("Handle `{}` streaming request. Returns (StreamInfo, mandatory continuation).", v.name);
285                    return quote! {
286                        #[doc = #doc_str]
287                        async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64 #(, #params)*) -> anyhow::Result<(StreamInfo, hyprstream_rpc::service::Continuation)>;
288                    };
289                }
290
291                let doc_str = format!("Handle `{}` request.", v.name);
292
293                quote! {
294                    #[doc = #doc_str]
295                    async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64 #(, #params)*) -> anyhow::Result<#response_type>;
296                }
297            })
298            .collect();
299
300        quote! {
301            #[doc = #doc]
302            #[async_trait::async_trait(?Send)]
303            pub trait #trait_name {
304                #(#methods)*
305            }
306        }
307    }
308}
309
310fn handler_method_params(v: &UnionVariant, resolved: &ResolvedSchema) -> Vec<TokenStream> {
311    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
312    match ct {
313        CapnpType::Void => vec![],
314        CapnpType::Text => vec![quote! { value: &str }],
315        CapnpType::Data => vec![quote! { data: &[u8] }],
316        _ if ct.is_numeric() => {
317            let ty = rust_type_tokens(&ct.rust_owned_type());
318            vec![quote! { value: #ty }]
319        }
320        CapnpType::Struct(ref name) => {
321            if let Some(sdef) = resolved.find_struct(name) {
322                // Union-only struct (e.g., scope structs like RuntimeRequest):
323                // handler needs the decoded body to dispatch the inner union
324                if sdef.is_pure_union() {
325                    return vec![quote! { body: &hyprstream_rpc::service::DecodedRequestBody }];
326                }
327                // Option 2: Accept whole struct instead of individual fields
328                let struct_name = format_ident!("{}", name);
329                vec![quote! { data: &#struct_name }]
330            } else {
331                vec![quote! { data: &[u8] }]
332            }
333        }
334        _ => vec![quote! { data: &[u8] }],
335    }
336}
337
338/// Check if a union variant's type is a union-only struct (has a union, no regular fields).
339/// These act like scoped clients: raw bytes in, raw bytes out.
340fn is_union_only_struct_variant(v: &UnionVariant, resolved: &ResolvedSchema) -> bool {
341    if let CapnpType::Struct(ref name) = resolved.resolve_type(&v.type_name).capnp_type {
342        if let Some(sdef) = resolved.find_struct(name) {
343            return sdef.is_pure_union();
344        }
345    }
346    false
347}
348
349// ─────────────────────────────────────────────────────────────────────────────
350// Dispatch Function
351// ─────────────────────────────────────────────────────────────────────────────
352
353fn generate_dispatch_fn(
354    pascal: &str,
355    capnp_mod: &syn::Ident,
356    request_variants: &[UnionVariant],
357    response_variants: &[UnionVariant],
358    scoped_clients: &[ScopedClient],
359    resolved: &ResolvedSchema,
360    scope_handlers: bool,
361) -> TokenStream {
362    let fn_name = format_ident!("dispatch_{}", to_snake_case(pascal));
363    let trait_name = format_ident!("{}Handler", pascal);
364    let req_snake = format_ident!("{}", to_snake_case(&format!("{pascal}Request")));
365    let doc =
366        format!("Dispatch a {pascal} request: deserialize, call handler, serialize response.");
367    let scoped_names: Vec<&str> = scoped_clients
368        .iter()
369        .map(|sc| sc.factory_name.as_str())
370        .collect();
371    let method_discriminator_arms: Vec<TokenStream> = request_variants
372        .iter()
373        .enumerate()
374        .map(|(index, variant)| {
375            let variant_pascal = resolved.name(&variant.name).pascal_ident.clone();
376            let discriminator = resolved
377                .raw
378                .request_struct
379                .as_ref()
380                .and_then(|request| {
381                    request
382                        .union_fields()
383                        .find(|field| field.name == variant.name)
384                })
385                .map(|field| field.discriminant_value)
386                .unwrap_or_else(|| u16::try_from(index).unwrap_or(u16::MAX));
387            quote! { Which::#variant_pascal(_) => #discriminator, }
388        })
389        .collect();
390
391    let match_arms: Vec<TokenStream> = request_variants
392        .iter()
393        .map(|v| {
394            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
395            let handler_method = format_ident!("handle_{}", resolved.name(&v.name).snake);
396
397            // Scoped clients handling depends on scope_handlers flag
398            if scoped_names.contains(&v.name.as_str()) {
399                if scope_handlers {
400                    // New pattern: delegate to generated scope dispatch function
401                    let scope_dispatch_fn = format_ident!("dispatch_{}", resolved.name(&v.name).snake);
402                    return quote! {
403                        Which::#variant_pascal(_) => {
404                            drop(req);
405                            return #scope_dispatch_fn(handler, ctx, request_id, body).await;
406                        }
407                    };
408                } else {
409                    // Old pattern: pass raw bytes to handler method
410                    return quote! {
411                        Which::#variant_pascal(_) => {
412                            return Ok((handler.#handler_method(ctx, request_id, body).await?, None));
413                        }
414                    };
415                }
416            }
417
418            // Union-only struct variants (non-scoped): pass raw bytes, return directly
419            if is_union_only_struct_variant(v, resolved) {
420                let call = if scope_handlers {
421                    quote! { #trait_name::#handler_method(handler, ctx, request_id, body).await }
422                } else {
423                    quote! { handler.#handler_method(ctx, request_id, body).await }
424                };
425                return quote! {
426                    Which::#variant_pascal(_) => {
427                        return Ok((#call?, None));
428                    }
429                };
430            }
431
432            let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
433
434            // Generate auth check if scope_handlers is enabled and variant has a scope annotation.
435            // Resource is constructed as "{service}" for Void, "{service}:{value}" for Text.
436            let service_name_lower = to_snake_case(pascal);
437            let auth_check = if scope_handlers {
438                parse_scope_for_auth(&v.scope)
439                    .map(|action| (action.to_owned(), service_name_lower.clone()))
440            } else {
441                None
442            };
443
444            // When scope_handlers is enabled, use UFCS to disambiguate non-scoped
445            // methods from scope sub-trait methods with the same name (e.g.,
446            // ModelHandler::handle_load vs PeftHandler::handle_load).
447            macro_rules! call_handler {
448                ($($args:tt)*) => {
449                    if scope_handlers {
450                        quote! { #trait_name::#handler_method(handler, ctx, request_id, $($args)*).await }
451                    } else {
452                        quote! { handler.#handler_method(ctx, request_id, $($args)*).await }
453                    }
454                };
455                () => {
456                    if scope_handlers {
457                        quote! { #trait_name::#handler_method(handler, ctx, request_id).await }
458                    } else {
459                        quote! { handler.#handler_method(ctx, request_id).await }
460                    }
461                };
462            }
463
464            // ── Streaming variants (response == StreamInfo) ──
465            // Handler returns (StreamInfo, Continuation).
466            // Dispatch wraps StreamInfo into the response variant, serializes,
467            // and wraps continuation in Some() for post-REP execution.
468            if is_streaming_variant(v, response_variants) {
469                let resp_variant_name = streaming_response_variant_name(v);
470                let resp_variant_pascal = format_ident!("{}", to_pascal_case(&resp_variant_name));
471                let response_type = format_ident!("{}ResponseVariant", pascal);
472
473                // Generate auth error return for streaming variants
474                let streaming_auth_stmt = if let Some((ref action, ref service)) = auth_check {
475                    let err_response_type = format_ident!("{}ResponseVariant", pascal);
476                    let variant_str = variant_pascal.to_string();
477                    quote! {
478                        let __audit_resource = format!("{}:{}", #service, #variant_str);
479                        let __authz = #trait_name::authorize(handler, ctx, &__audit_resource, #action).await;
480                        ctx.audit_authz(&__audit_resource, #action, __authz.is_ok());
481                        if let Err(e) = __authz {
482                            let err_variant = #err_response_type::Error(ErrorInfo {
483                                message: e.to_string(),
484                                code: "UNAUTHORIZED".to_string(),
485                                details: String::new(),
486                            });
487                            return Ok((serialize_response(request_id, &err_variant)?, None));
488                        }
489                    }
490                } else { TokenStream::new() };
491
492                return match ct {
493                    CapnpType::Void => {
494                        let call = call_handler!();
495                        quote! {
496                            Which::#variant_pascal(()) => {
497                                #streaming_auth_stmt
498                                let (stream_info, continuation) = #call?;
499                                let guarded = hyprstream_rpc::streaming::StreamGuard::wrap(continuation);
500                                let variant = #response_type::#resp_variant_pascal(stream_info);
501                                return Ok((serialize_response(request_id, &variant)?, Some(guarded)));
502                            }
503                        }
504                    },
505                    CapnpType::Struct(ref name) => {
506                        if let Some(sdef) = resolved.find_struct(name) {
507                            if sdef.is_pure_union() {
508                                let call = call_handler!(body);
509                                quote! {
510                                    Which::#variant_pascal(_) => {
511                                        return Ok((#call?, None));
512                                    }
513                                }
514                            } else {
515                                let call = if scope_handlers {
516                                    quote! { #trait_name::#handler_method(handler, ctx, request_id, &data).await }
517                                } else {
518                                    quote! { handler.#handler_method(ctx, request_id, &data).await }
519                                };
520
521                                quote! {
522                                    Which::#variant_pascal(v) => {
523                                        let v = v?;
524                                        let data = hyprstream_rpc::capnp::FromCapnp::read_from(v)?;
525                                        #streaming_auth_stmt
526                                        let (stream_info, continuation) = #call?;
527                                        let guarded = hyprstream_rpc::streaming::StreamGuard::wrap(continuation);
528                                        let variant = #response_type::#resp_variant_pascal(stream_info);
529                                        return Ok((serialize_response(request_id, &variant)?, Some(guarded)));
530                                    }
531                                }
532                            }
533                        } else {
534                            let name_str = v.name.clone();
535                            quote! { Which::#variant_pascal(_) => { anyhow::bail!("Unhandled variant: {}", #name_str); } }
536                        }
537                    },
538                    _ => {
539                        // Streaming with simple types (Text, numeric) — unlikely but handle gracefully
540                        let name_str = v.name.clone();
541                        quote! { Which::#variant_pascal(_) => { anyhow::bail!("Unsupported streaming variant type: {}", #name_str); } }
542                    }
543                };
544            }
545
546            match ct {
547                CapnpType::Void => {
548                    let call = call_handler!();
549                    if let Some((ref action, ref service)) = auth_check {
550                        // Void: resource = "{service}:{VariantName}"
551                        let variant_str = variant_pascal.to_string();
552                        quote! {
553                            Which::#variant_pascal(()) => {
554                                let __audit_resource = format!("{}:{}", #service, #variant_str);
555                                let __authz = #trait_name::authorize(handler, ctx, &__audit_resource, #action).await;
556                                ctx.audit_authz(&__audit_resource, #action, __authz.is_ok());
557                                __authz?;
558                                #call
559                            }
560                        }
561                    } else {
562                        quote! {
563                            Which::#variant_pascal(()) => #call,
564                        }
565                    }
566                },
567                CapnpType::Text => {
568                    if let Some((ref action, ref service)) = auth_check {
569                        // Text: resource = "{service}:{value}"
570                        let call = if scope_handlers {
571                            quote! { #trait_name::#handler_method(handler, ctx, request_id, v).await }
572                        } else {
573                            quote! { handler.#handler_method(ctx, request_id, v).await }
574                        };
575                        quote! {
576                            Which::#variant_pascal(val) => {
577                                let v = val?.to_str()?;
578                                let __audit_resource = format!("{}:{}", #service, v);
579                                let __authz = #trait_name::authorize(handler, ctx, &__audit_resource, #action).await;
580                                ctx.audit_authz(&__audit_resource, #action, __authz.is_ok());
581                                __authz?;
582                                #call
583                            }
584                        }
585                    } else {
586                        let call = if scope_handlers {
587                            quote! { #trait_name::#handler_method(handler, ctx, request_id, v?.to_str()?).await }
588                        } else {
589                            quote! { handler.#handler_method(ctx, request_id, v?.to_str()?).await }
590                        };
591                        quote! {
592                            Which::#variant_pascal(v) => #call,
593                        }
594                    }
595                },
596                CapnpType::Data => {
597                    let call = if scope_handlers {
598                        quote! { #trait_name::#handler_method(handler, ctx, request_id, v?).await }
599                    } else {
600                        quote! { handler.#handler_method(ctx, request_id, v?).await }
601                    };
602                    if let Some((ref action, ref service)) = auth_check {
603                        let variant_str = variant_pascal.to_string();
604                        quote! {
605                            Which::#variant_pascal(v) => {
606                                let __audit_resource = format!("{}:{}", #service, #variant_str);
607                                let __authz = #trait_name::authorize(handler, ctx, &__audit_resource, #action).await;
608                                ctx.audit_authz(&__audit_resource, #action, __authz.is_ok());
609                                __authz?;
610                                #call
611                            }
612                        }
613                    } else {
614                        quote! {
615                            Which::#variant_pascal(v) => #call,
616                        }
617                    }
618                },
619                _ if ct.is_numeric() => {
620                    let call = if scope_handlers {
621                        quote! { #trait_name::#handler_method(handler, ctx, request_id, v).await }
622                    } else {
623                        quote! { handler.#handler_method(ctx, request_id, v).await }
624                    };
625                    if let Some((ref action, ref service)) = auth_check {
626                        let variant_str = variant_pascal.to_string();
627                        quote! {
628                            Which::#variant_pascal(v) => {
629                                let __audit_resource = format!("{}:{}", #service, #variant_str);
630                                let __authz = #trait_name::authorize(handler, ctx, &__audit_resource, #action).await;
631                                ctx.audit_authz(&__audit_resource, #action, __authz.is_ok());
632                                __authz?;
633                                #call
634                            }
635                        }
636                    } else {
637                        quote! {
638                            Which::#variant_pascal(v) => #call,
639                        }
640                    }
641                },
642                CapnpType::Struct(ref name) => {
643                    if let Some(sdef) = resolved.find_struct(name) {
644                        // Union-only struct (e.g., scope structs): pass the decoded body
645                        if sdef.is_pure_union() {
646                            let call = if scope_handlers {
647                                quote! { #trait_name::#handler_method(handler, ctx, request_id, body).await }
648                            } else {
649                                quote! { handler.#handler_method(ctx, request_id, body).await }
650                            };
651                            return quote! {
652                                Which::#variant_pascal(v) => {
653                                    let _v = v?;
654                                    #call
655                                }
656                            };
657                        }
658
659                        // Option 2: Extract whole struct and pass by reference
660                        let call = if scope_handlers {
661                            quote! { #trait_name::#handler_method(handler, ctx, request_id, &data).await }
662                        } else {
663                            quote! { handler.#handler_method(ctx, request_id, &data).await }
664                        };
665
666                        let auth_stmt = if let Some((ref action, ref service)) = auth_check {
667                            // Struct: resource = "{service}:{VariantName}"
668                            // e.g. authorize(ctx, "policy:resolveServiceKey", "query")
669                            let variant_str = variant_pascal.to_string();
670                            quote! {
671                                let __audit_resource = format!("{}:{}", #service, #variant_str);
672                                let __authz = #trait_name::authorize(handler, ctx, &__audit_resource, #action).await;
673                                ctx.audit_authz(&__audit_resource, #action, __authz.is_ok());
674                                __authz?;
675                            }
676                        } else {
677                            TokenStream::new()
678                        };
679
680                        quote! {
681                            Which::#variant_pascal(v) => {
682                                let v = v?;
683                                let data = hyprstream_rpc::capnp::FromCapnp::read_from(v)?;
684                                #auth_stmt
685                                #call
686                            }
687                        }
688                    } else {
689                        let name_str = v.name.clone();
690                        quote! {
691                            Which::#variant_pascal(_) => {
692                                anyhow::bail!("Unhandled variant: {}", #name_str);
693                            }
694                        }
695                    }
696                }
697                _ => {
698                    let name_str = v.name.clone();
699                    quote! {
700                        Which::#variant_pascal(_) => {
701                            anyhow::bail!("Unhandled variant: {}", #name_str);
702                        }
703                    }
704                }
705            }
706        })
707        .collect();
708
709    // Two-phase dispatch for Send safety:
710    // When all variants are scoped and delegate, extract variant discriminant first,
711    // drop readers, then dispatch on discriminant.
712    let all_delegated = scope_handlers
713        && request_variants.iter().all(|v| {
714            scoped_names.contains(&v.name.as_str()) || is_union_only_struct_variant(v, resolved)
715        });
716
717    let dispatch_body = if all_delegated {
718        // All variants delegate to scope dispatch - use two-phase pattern
719        // Extract discriminant to avoid holding Which across awaits
720        let discriminant_arms: Vec<TokenStream> = request_variants
721            .iter()
722            .map(|v| {
723                let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
724                let disc = syn::Index::from(
725                    request_variants
726                        .iter()
727                        .position(|rv| rv.name == v.name)
728                        .unwrap_or(0),
729                );
730                quote! {
731                    Which::#variant_pascal(_) => #disc,
732                }
733            })
734            .collect();
735
736        let dispatch_arms: Vec<TokenStream> = request_variants.iter().enumerate().map(|(idx, v)| {
737            let disc = syn::Index::from(idx);
738            if scoped_names.contains(&v.name.as_str()) {
739                let scope_dispatch_fn = format_ident!("dispatch_{}", resolved.name(&v.name).snake);
740                quote! {
741                    #disc => return #scope_dispatch_fn(handler, ctx, request_id, body).await,
742                }
743            } else if is_union_only_struct_variant(v, resolved) {
744                let handler_method = format_ident!("handle_{}", resolved.name(&v.name).snake);
745                quote! {
746                    #disc => return Ok((#trait_name::#handler_method(handler, ctx, request_id, body).await?, None)),
747                }
748            } else {
749                quote! {
750                    #disc => return anyhow::bail!("Unexpected variant"),
751                }
752            }
753        }).collect();
754
755        quote! {
756            // Phase 1: Extract discriminant (no await, Reader in scope)
757            let disc = match req.which()? {
758                #(#discriminant_arms)*
759                #[allow(unreachable_patterns)]
760                _ => anyhow::bail!("Unknown request variant (not in schema)"),
761            };
762            // Root reader borrow dropped here; the decoded message lives in `body`.
763            drop(req);
764
765            // Phase 2: Dispatch on discriminant (safe to await)
766            match disc {
767                #(#dispatch_arms)*
768                _ => unreachable!("Discriminant out of range"),
769            }
770        }
771    } else {
772        let response_type = format_ident!("{}ResponseVariant", pascal);
773        quote! {
774            let result = match req.which()? {
775                #(#match_arms)*
776                #[allow(unreachable_patterns)]
777                _ => anyhow::bail!("Unknown request variant (not in schema)"),
778            };
779            // Convert errors (auth failures, handler errors) to Error response variant
780            let result = match result {
781                Ok(v) => v,
782                Err(e) => #response_type::Error(ErrorInfo {
783                    message: e.to_string(),
784                    code: "UNAUTHORIZED".to_string(),
785                    details: String::new(),
786                }),
787            };
788            Ok((serialize_response(request_id, &result)?, None))
789        }
790    };
791
792    quote! {
793        #[doc = #doc]
794        pub async fn #fn_name<H: #trait_name>(handler: &H, ctx: &hyprstream_rpc::service::EnvelopeContext, body: &hyprstream_rpc::service::DecodedRequestBody) -> anyhow::Result<(Vec<u8>, Option<hyprstream_rpc::service::Continuation>)> {
795            use #capnp_mod::#req_snake::Which;
796            // Read the typed request from the ONE decoded message (v16 §5.2):
797            // pointer traversal over the body whose derived leaf the policy
798            // and MAC gates already consumed — never a second decode of the
799            // signed bytes.
800            let req = body.root::<#capnp_mod::#req_snake::Reader>()?;
801            let request_id = req.get_id();
802            let __decoded_method_discriminator = match req.which()? {
803                #(#method_discriminator_arms)*
804                #[allow(unreachable_patterns)]
805                _ => anyhow::bail!("Unknown request variant (not in schema)"),
806            };
807            ctx.ensure_browser_method(__decoded_method_discriminator)?;
808            #dispatch_body
809        }
810    }
811}
812
813// ─────────────────────────────────────────────────────────────────────────────
814// Response Serializer
815// ─────────────────────────────────────────────────────────────────────────────
816
817fn generate_response_serializer(
818    pascal: &str,
819    capnp_mod: &syn::Ident,
820    response_variants: &[UnionVariant],
821    resolved: &ResolvedSchema,
822) -> TokenStream {
823    let response_type = format_ident!("{}ResponseVariant", pascal);
824    let resp_snake = format_ident!("{}", to_snake_case(&format!("{pascal}Response")));
825    let doc = format!("Serialize a {pascal}ResponseVariant to Cap'n Proto bytes.");
826
827    let match_arms: Vec<TokenStream> = response_variants
828        .iter()
829        .map(|v| generate_serializer_arm(pascal, v, resolved))
830        .collect();
831
832    quote! {
833        #[doc = #doc]
834        pub fn serialize_response(request_id: u64, variant: &#response_type) -> anyhow::Result<Vec<u8>> {
835            hyprstream_rpc::serialize_message(|msg| {
836                let mut resp = msg.init_root::<#capnp_mod::#resp_snake::Builder>();
837                resp.set_request_id(request_id);
838                match variant {
839                    #(#match_arms)*
840                }
841            })
842        }
843    }
844}
845
846fn generate_serializer_arm(
847    pascal: &str,
848    v: &UnionVariant,
849    resolved: &ResolvedSchema,
850) -> TokenStream {
851    let response_type = format_ident!("{}ResponseVariant", pascal);
852    let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
853    let v_snake = &resolved.name(&v.name).snake;
854    let setter_name = format_ident!("set_{}", v_snake);
855    let init_name = format_ident!("init_{}", v_snake);
856
857    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
858    match ct {
859        CapnpType::Void => quote! {
860            #response_type::#variant_pascal => {
861                resp.#setter_name(());
862            }
863        },
864        CapnpType::Text | CapnpType::Data => quote! {
865            #response_type::#variant_pascal(v) => {
866                resp.#setter_name(v);
867            }
868        },
869        _ if ct.is_numeric() => quote! {
870            #response_type::#variant_pascal(v) => {
871                resp.#setter_name(*v);
872            }
873        },
874        CapnpType::Struct(ref name) => {
875            if resolved.is_struct(name) {
876                quote! {
877                    #response_type::#variant_pascal(ref v) => {
878                        let mut inner = resp.#init_name();
879                        <_ as hyprstream_rpc::ToCapnp>::write_to(v, &mut inner);
880                    }
881                }
882            } else {
883                quote! {
884                    #response_type::#variant_pascal(_) => {
885                        // Unknown struct type
886                    }
887                }
888            }
889        }
890        CapnpType::ListStruct(ref inner) => {
891            if resolved.is_struct(inner) {
892                quote! {
893                    #response_type::#variant_pascal(ref v) => {
894                        let mut list = resp.#init_name(v.len() as u32);
895                        for (i, item) in v.iter().enumerate() {
896                            let mut builder = list.reborrow().get(i as u32);
897                            <_ as hyprstream_rpc::ToCapnp>::write_to(item, &mut builder);
898                        }
899                    }
900                }
901            } else {
902                quote! {
903                    #response_type::#variant_pascal(_) => {
904                        // Unknown list struct type
905                    }
906                }
907            }
908        }
909        CapnpType::ListText | CapnpType::ListData => quote! {
910            #response_type::#variant_pascal(ref v) => {
911                let mut list = resp.#init_name(v.len() as u32);
912                for (i, item) in v.iter().enumerate() {
913                    list.set(i as u32, item);
914                }
915            }
916        },
917        CapnpType::ListPrimitive(_) => quote! {
918            #response_type::#variant_pascal(ref v) => {
919                let mut list = resp.#init_name(v.len() as u32);
920                for (i, item) in v.iter().enumerate() {
921                    list.set(i as u32, *item);
922                }
923            }
924        },
925        _ => quote! {
926            #response_type::#variant_pascal(..) => {
927                // Unhandled type
928            }
929        },
930    }
931}
932
933// ─────────────────────────────────────────────────────────────────────────────
934// Scope Handler Traits (per-scope typed dispatch)
935// ─────────────────────────────────────────────────────────────────────────────
936
937/// Generate scope handler traits for all scoped clients (recursively).
938fn generate_scope_handler_traits(
939    scoped_clients: &[ScopedClient],
940    resolved: &ResolvedSchema,
941) -> TokenStream {
942    let mut tokens = TokenStream::new();
943    for sc in scoped_clients {
944        walk_scope_handler_traits(&mut tokens, sc, &[], resolved);
945    }
946    tokens
947}
948
949/// Recursively walk the scope tree generating handler traits (deepest first).
950fn walk_scope_handler_traits(
951    tokens: &mut TokenStream,
952    sc: &ScopedClient,
953    ancestors: &[&ScopedClient],
954    resolved: &ResolvedSchema,
955) {
956    // Generate nested traits FIRST (so super-trait bounds resolve)
957    let mut next_ancestors: Vec<&ScopedClient> = ancestors.to_vec();
958    next_ancestors.push(sc);
959    for nc in &sc.nested_clients {
960        walk_scope_handler_traits(tokens, nc, &next_ancestors, resolved);
961    }
962
963    // Then generate this level's trait
964    if ancestors.is_empty() {
965        tokens.extend(generate_scope_handler_trait(sc, resolved));
966    } else {
967        tokens.extend(generate_nested_scope_handler_trait(sc, ancestors, resolved));
968    }
969}
970
971/// Generate a single scope handler trait (e.g., `RepoHandler`).
972///
973/// If the scope has nested clients, the trait requires those nested handler traits
974/// as super-traits instead of raw-bytes passthrough methods.
975fn generate_scope_handler_trait(sc: &ScopedClient, resolved: &ResolvedSchema) -> TokenStream {
976    let trait_name = format_ident!("{}Handler", to_pascal_case(&sc.factory_name));
977    let doc = format!("Generated handler trait for the {} scope.", sc.factory_name);
978
979    // Build scope field params (e.g., `model_ref: &str`, `repo_id: &str`)
980    let scope_field_params: Vec<TokenStream> = sc
981        .scope_fields
982        .iter()
983        .map(|f| {
984            let name = resolved.name(&f.name).snake_ident.clone();
985            let ty = rust_type_tokens(&resolved.resolve_type(&f.type_name).rust_param);
986            quote! { #name: #ty }
987        })
988        .collect();
989
990    let methods: Vec<TokenStream> = sc.inner_request_variants.iter()
991        .filter(|v| v.name != "error")
992        .map(|v| {
993            let method_name = format_ident!("handle_{}", resolved.name(&v.name).snake);
994            let params = scope_handler_method_params(v, resolved);
995            let return_type = scope_handler_return_type(v, &sc.inner_response_variants, resolved);
996            let doc_str = if v.description.is_empty() {
997                format!("Handle `{}` request.", v.name)
998            } else {
999                v.description.clone()
1000            };
1001            quote! {
1002                #[doc = #doc_str]
1003                async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64 #(, #scope_field_params)* #(, #params)*) -> anyhow::Result<#return_type>;
1004            }
1005        })
1006        .collect();
1007
1008    if sc.nested_clients.is_empty() {
1009        // No nested clients — simple trait
1010        quote! {
1011            #[doc = #doc]
1012            #[async_trait::async_trait(?Send)]
1013            pub trait #trait_name {
1014                #(#methods)*
1015            }
1016        }
1017    } else {
1018        // Has nested clients — add super-trait bounds
1019        let nested_bounds: Vec<TokenStream> = sc
1020            .nested_clients
1021            .iter()
1022            .map(|nc| {
1023                let nested_trait = format_ident!("{}Handler", to_pascal_case(&nc.factory_name));
1024                quote! { #nested_trait }
1025            })
1026            .collect();
1027
1028        quote! {
1029            #[doc = #doc]
1030            #[async_trait::async_trait(?Send)]
1031            pub trait #trait_name: #(#nested_bounds)+* {
1032                #(#methods)*
1033            }
1034        }
1035    }
1036}
1037
1038/// Generate a nested scope handler trait (e.g., `WorktreeHandler`, `CtlHandler`).
1039///
1040/// Nested scope handler methods receive ALL ancestor scope fields AND own scope fields.
1041/// `ancestors` contains all scopes above this one (e.g., for CtlHandler: [RepoScope, WorktreeScope]).
1042fn generate_nested_scope_handler_trait(
1043    nc: &ScopedClient,
1044    ancestors: &[&ScopedClient],
1045    resolved: &ResolvedSchema,
1046) -> TokenStream {
1047    let trait_name = format_ident!("{}Handler", to_pascal_case(&nc.factory_name));
1048    let doc = format!(
1049        "Generated handler trait for the nested {} scope.",
1050        nc.factory_name
1051    );
1052
1053    // All ancestor scope field params (e.g., `repo_id: &str, name: &str`)
1054    let ancestor_scope_field_params: Vec<TokenStream> = ancestors
1055        .iter()
1056        .flat_map(|a| &a.scope_fields)
1057        .map(|f| {
1058            let name = resolved.name(&f.name).snake_ident.clone();
1059            let ty = rust_type_tokens(&resolved.resolve_type(&f.type_name).rust_param);
1060            quote! { #name: #ty }
1061        })
1062        .collect();
1063
1064    // Own scope field params (e.g., `fid: u32`)
1065    let own_scope_field_params: Vec<TokenStream> = nc
1066        .scope_fields
1067        .iter()
1068        .map(|f| {
1069            let name = resolved.name(&f.name).snake_ident.clone();
1070            let ty = rust_type_tokens(&resolved.resolve_type(&f.type_name).rust_param);
1071            quote! { #name: #ty }
1072        })
1073        .collect();
1074
1075    let methods: Vec<TokenStream> = nc.inner_request_variants.iter()
1076        .filter(|v| v.name != "error")
1077        .map(|v| {
1078            let method_name = format_ident!("handle_{}", resolved.name(&v.name).snake);
1079            let params = scope_handler_method_params(v, resolved);
1080            let return_type = scope_handler_return_type(v, &nc.inner_response_variants, resolved);
1081            let doc_str = if v.description.is_empty() {
1082                format!("Handle `{}` request.", v.name)
1083            } else {
1084                v.description.clone()
1085            };
1086            quote! {
1087                #[doc = #doc_str]
1088                async fn #method_name(&self, ctx: &hyprstream_rpc::service::EnvelopeContext, request_id: u64 #(, #ancestor_scope_field_params)* #(, #own_scope_field_params)* #(, #params)*) -> anyhow::Result<#return_type>;
1089            }
1090        })
1091        .collect();
1092
1093    // If this nested scope itself has nested clients, add super-trait bounds
1094    if nc.nested_clients.is_empty() {
1095        quote! {
1096            #[doc = #doc]
1097            #[async_trait::async_trait(?Send)]
1098            pub trait #trait_name {
1099                #(#methods)*
1100            }
1101        }
1102    } else {
1103        let nested_bounds: Vec<TokenStream> = nc
1104            .nested_clients
1105            .iter()
1106            .map(|inner_nc| {
1107                let nested_trait =
1108                    format_ident!("{}Handler", to_pascal_case(&inner_nc.factory_name));
1109                quote! { #nested_trait }
1110            })
1111            .collect();
1112
1113        quote! {
1114            #[doc = #doc]
1115            #[async_trait::async_trait(?Send)]
1116            pub trait #trait_name: #(#nested_bounds)+* {
1117                #(#methods)*
1118            }
1119        }
1120    }
1121}
1122
1123/// Generate method params for scope handler traits.
1124///
1125/// Unlike `handler_method_params` which expands struct fields into individual params,
1126/// this passes complex structs as a single `&StructNameData` parameter for ergonomics.
1127/// Simple types (Text, Void, Bool, numerics) and small request structs (≤2 fields)
1128/// still expand into individual params.
1129fn scope_handler_method_params(v: &UnionVariant, resolved: &ResolvedSchema) -> Vec<TokenStream> {
1130    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
1131    match ct {
1132        CapnpType::Void => vec![],
1133        CapnpType::Text => vec![quote! { value: &str }],
1134        CapnpType::Data => vec![quote! { data: &[u8] }],
1135        _ if ct.is_numeric() => {
1136            let ty = rust_type_tokens(&ct.rust_owned_type());
1137            vec![quote! { value: #ty }]
1138        }
1139        CapnpType::Struct(ref name) => {
1140            if let Some(sdef) = resolved.find_struct(name) {
1141                if sdef.is_pure_union() {
1142                    return vec![quote! { body: &hyprstream_rpc::service::DecodedRequestBody }];
1143                }
1144                // Option 2: Accept whole struct instead of individual fields
1145                // (Consistent with handler_method_params for maintainability)
1146                let struct_name = format_ident!("{}", name);
1147                vec![quote! { data: &#struct_name }]
1148            } else {
1149                vec![quote! { data: &[u8] }]
1150            }
1151        }
1152        _ => vec![quote! { data: &[u8] }],
1153    }
1154}
1155
1156/// Determine the Rust return type for a scope handler method.
1157///
1158/// Matches request variant name → response variant name (same name, scoped convention)
1159/// and converts the response variant's type to a Rust owned type.
1160///
1161/// Streaming variants (response == StreamInfo) return `(StreamInfo, Continuation)`
1162/// — the continuation is mandatory, not optional.
1163fn scope_handler_return_type(
1164    request_variant: &UnionVariant,
1165    response_variants: &[UnionVariant],
1166    resolved: &ResolvedSchema,
1167) -> TokenStream {
1168    if let Some(resp_v) = response_variants
1169        .iter()
1170        .find(|v| v.name == request_variant.name)
1171    {
1172        if resp_v.type_name == "StreamInfo" {
1173            // Streaming: return tuple with mandatory continuation
1174            return quote! { (StreamInfo, hyprstream_rpc::service::Continuation) };
1175        }
1176        let rt = resolved.resolve_type(&resp_v.type_name);
1177        rust_type_tokens(&rt.rust_owned)
1178    } else {
1179        quote! { () }
1180    }
1181}
1182
1183// ─────────────────────────────────────────────────────────────────────────────
1184// Scope Dispatch Functions
1185// ─────────────────────────────────────────────────────────────────────────────
1186
1187/// Generate scope dispatch functions for all scoped clients (recursively).
1188fn generate_scope_dispatch_fns(
1189    pascal: &str,
1190    capnp_mod: &syn::Ident,
1191    scoped_clients: &[ScopedClient],
1192    resolved: &ResolvedSchema,
1193) -> TokenStream {
1194    let mut tokens = TokenStream::new();
1195    for sc in scoped_clients {
1196        walk_scope_dispatch_fns(&mut tokens, pascal, capnp_mod, sc, &[], resolved);
1197    }
1198    tokens
1199}
1200
1201/// Recursively walk the scope tree generating dispatch functions (deepest first).
1202fn walk_scope_dispatch_fns(
1203    tokens: &mut TokenStream,
1204    pascal: &str,
1205    capnp_mod: &syn::Ident,
1206    sc: &ScopedClient,
1207    ancestors: &[&ScopedClient],
1208    resolved: &ResolvedSchema,
1209) {
1210    // Generate nested dispatch functions FIRST
1211    let mut next_ancestors: Vec<&ScopedClient> = ancestors.to_vec();
1212    next_ancestors.push(sc);
1213    for nc in &sc.nested_clients {
1214        walk_scope_dispatch_fns(tokens, pascal, capnp_mod, nc, &next_ancestors, resolved);
1215    }
1216
1217    // Then generate this level's dispatch function
1218    if ancestors.is_empty() {
1219        tokens.extend(generate_scope_dispatch_fn(pascal, capnp_mod, sc, resolved));
1220    } else {
1221        tokens.extend(generate_nested_scope_dispatch_fn(
1222            pascal, capnp_mod, ancestors, sc, resolved,
1223        ));
1224    }
1225}
1226
1227/// Generate a single scope dispatch function (e.g., `dispatch_runtime()`).
1228///
1229/// The trait bound uses the **parent** handler trait (e.g., `RegistryHandler`)
1230/// rather than the scope sub-trait (e.g., `RepoHandler`). This allows the
1231/// dispatch function to call `MainHandler::authorize()` for auth enforcement
1232/// while still accessing scope handler methods via the super-trait bound.
1233fn generate_scope_dispatch_fn(
1234    pascal: &str,
1235    capnp_mod: &syn::Ident,
1236    sc: &ScopedClient,
1237    resolved: &ResolvedSchema,
1238) -> TokenStream {
1239    let fn_name = format_ident!("dispatch_{}", to_snake_case(&sc.factory_name));
1240    // Use the parent (main) handler trait as the bound so we can call authorize()
1241    let parent_trait = format_ident!("{}Handler", pascal);
1242    let serializer_fn = format_ident!("serialize_{}_response", to_snake_case(&sc.factory_name));
1243    let doc = format!(
1244        "Dispatch a {} scope request: extract params, call async handler (two-phase for Send safety).",
1245        sc.factory_name
1246    );
1247
1248    // Build scope field idents
1249    let scope_field_idents: Vec<syn::Ident> = sc
1250        .scope_fields
1251        .iter()
1252        .map(|f| resolved.name(&f.name).snake_ident.clone())
1253        .collect();
1254
1255    let scope_trait = format_ident!("{}Handler", to_pascal_case(&sc.factory_name));
1256    let service_name_lower = to_snake_case(pascal);
1257
1258    // Generate helper types and phases
1259    let variant_tag_enum = generate_scope_variant_tag_enum(sc, resolved);
1260    let params_enum = generate_scope_params_enum(sc, resolved);
1261    let extraction_phase = generate_scope_extraction_phase(pascal, capnp_mod, sc, resolved);
1262    let dispatch_phase = generate_scope_dispatch_phase(
1263        sc,
1264        resolved,
1265        &scope_field_idents,
1266        &parent_trait,
1267        &scope_trait,
1268        &service_name_lower,
1269        &serializer_fn,
1270    );
1271
1272    quote! {
1273        #[doc = #doc]
1274        pub async fn #fn_name<H: #parent_trait>(
1275            handler: &H,
1276            ctx: &hyprstream_rpc::service::EnvelopeContext,
1277            request_id: u64,
1278            body: &hyprstream_rpc::service::DecodedRequestBody,
1279        ) -> anyhow::Result<(Vec<u8>, Option<hyprstream_rpc::service::Continuation>)> {
1280            // Phase 1: Extract all Cap'n Proto data to owned types
1281            #variant_tag_enum
1282            #params_enum
1283
1284            #extraction_phase
1285
1286            // Destructure scope fields tuple
1287            let (#(#scope_field_idents,)*) = scope_fields;
1288
1289            // Phase 2: Dispatch to async handlers (no Readers held)
1290            #dispatch_phase
1291        }
1292    }
1293}
1294
1295/// Generate a nested scope dispatch function (e.g., `dispatch_worktree()`, `dispatch_ctl()`).
1296///
1297/// This handles N-level dispatch: receives raw bytes from the parent scope dispatch,
1298/// re-reads the outer request, navigates outer → ancestor[0] → ... → nested scope,
1299/// extracts all ancestor + own scope fields, then dispatches the nested inner union.
1300///
1301/// `ancestors` contains all scopes above this one (e.g., for ctl: [repo, worktree]).
1302fn generate_nested_scope_dispatch_fn(
1303    pascal: &str,
1304    capnp_mod: &syn::Ident,
1305    ancestors: &[&ScopedClient],
1306    nc: &ScopedClient,
1307    resolved: &ResolvedSchema,
1308) -> TokenStream {
1309    let fn_name = format_ident!("dispatch_{}", to_snake_case(&nc.factory_name));
1310    let parent_trait = format_ident!("{}Handler", pascal);
1311    let nested_trait = format_ident!("{}Handler", to_pascal_case(&nc.factory_name));
1312    let serializer_fn = format_ident!("serialize_{}_response", to_snake_case(&nc.factory_name));
1313    let depth = ancestors.len() + 1; // +1 for the nested scope itself
1314    let doc = format!(
1315        "Dispatch a nested {} scope request: {}-level extraction, async handler (two-phase for Send safety).",
1316        nc.factory_name, depth + 1 // +1 for outer request
1317    );
1318
1319    // All ancestor scope field idents (for dispatch phase)
1320    let all_ancestor_scope_idents: Vec<syn::Ident> = ancestors
1321        .iter()
1322        .flat_map(|a| &a.scope_fields)
1323        .map(|f| resolved.name(&f.name).snake_ident.clone())
1324        .collect();
1325
1326    let nested_scope_idents: Vec<syn::Ident> = nc
1327        .scope_fields
1328        .iter()
1329        .map(|f| resolved.name(&f.name).snake_ident.clone())
1330        .collect();
1331
1332    let service_name_lower = to_snake_case(pascal);
1333
1334    // The dispatch function receives all ancestor scope fields from its parent dispatch function
1335    let all_ancestor_scope_params: Vec<TokenStream> = ancestors
1336        .iter()
1337        .flat_map(|a| &a.scope_fields)
1338        .map(|f| {
1339            let name = resolved.name(&f.name).snake_ident.clone();
1340            let ty = rust_type_tokens(&resolved.resolve_type(&f.type_name).rust_param);
1341            quote! { #name: #ty }
1342        })
1343        .collect();
1344
1345    // Generate helper types and phases
1346    let variant_tag_enum = generate_scope_variant_tag_enum(nc, resolved);
1347    let params_enum = generate_scope_params_enum(nc, resolved);
1348    let extraction_phase =
1349        generate_nested_scope_extraction_phase(pascal, capnp_mod, ancestors, nc, resolved);
1350    let dispatch_phase = generate_nested_scope_dispatch_phase(
1351        nc,
1352        resolved,
1353        &all_ancestor_scope_idents,
1354        &nested_scope_idents,
1355        &parent_trait,
1356        &nested_trait,
1357        &service_name_lower,
1358        &serializer_fn,
1359    );
1360
1361    quote! {
1362        #[doc = #doc]
1363        pub async fn #fn_name<H: #parent_trait>(
1364            handler: &H,
1365            ctx: &hyprstream_rpc::service::EnvelopeContext,
1366            request_id: u64,
1367            #(#all_ancestor_scope_params,)*
1368            body: &hyprstream_rpc::service::DecodedRequestBody,
1369        ) -> anyhow::Result<(Vec<u8>, Option<hyprstream_rpc::service::Continuation>)> {
1370            // Phase 1: Extract all Cap'n Proto data to owned types
1371            #variant_tag_enum
1372            #params_enum
1373
1374            #extraction_phase
1375
1376            // Destructure nested scope fields tuple
1377            let (#(#nested_scope_idents,)*) = nested_scope_fields;
1378
1379            // Phase 2: Dispatch to async handlers (no Readers held)
1380            #dispatch_phase
1381        }
1382    }
1383}
1384
1385// ─────────────────────────────────────────────────────────────────────────────
1386// Scope Response Serializers
1387// ─────────────────────────────────────────────────────────────────────────────
1388
1389/// Generate scope response serializers for all scoped clients (recursively).
1390fn generate_scope_response_serializers(
1391    pascal: &str,
1392    capnp_mod: &syn::Ident,
1393    scoped_clients: &[ScopedClient],
1394    resolved: &ResolvedSchema,
1395) -> TokenStream {
1396    let mut tokens = TokenStream::new();
1397    for sc in scoped_clients {
1398        walk_scope_response_serializers(&mut tokens, pascal, capnp_mod, sc, &[], resolved);
1399    }
1400    tokens
1401}
1402
1403/// Recursively walk the scope tree generating response serializers (deepest first).
1404fn walk_scope_response_serializers(
1405    tokens: &mut TokenStream,
1406    pascal: &str,
1407    capnp_mod: &syn::Ident,
1408    sc: &ScopedClient,
1409    ancestors: &[&ScopedClient],
1410    resolved: &ResolvedSchema,
1411) {
1412    // Generate nested serializers FIRST
1413    let mut next_ancestors: Vec<&ScopedClient> = ancestors.to_vec();
1414    next_ancestors.push(sc);
1415    for nc in &sc.nested_clients {
1416        walk_scope_response_serializers(tokens, pascal, capnp_mod, nc, &next_ancestors, resolved);
1417    }
1418
1419    // Then generate this level's serializer
1420    if ancestors.is_empty() {
1421        tokens.extend(generate_scope_response_serializer(
1422            pascal, capnp_mod, sc, resolved,
1423        ));
1424    } else {
1425        tokens.extend(generate_nested_scope_response_serializer(
1426            pascal, capnp_mod, ancestors, sc, resolved,
1427        ));
1428    }
1429}
1430
1431/// Generate a single scope response serializer (e.g., `serialize_runtime_response()`).
1432fn generate_scope_response_serializer(
1433    pascal: &str,
1434    capnp_mod: &syn::Ident,
1435    sc: &ScopedClient,
1436    resolved: &ResolvedSchema,
1437) -> TokenStream {
1438    let fn_name = format_ident!("serialize_{}_response", to_snake_case(&sc.factory_name));
1439    let response_type = format_ident!("{}ResponseVariant", sc.client_name);
1440    let resp_snake = format_ident!("{}", to_snake_case(&format!("{pascal}Response")));
1441    let scope_result_init = format_ident!(
1442        "init_{}",
1443        to_snake_case(&format!("{}Result", sc.factory_name))
1444    );
1445    let doc = format!(
1446        "Serialize a {} scope response variant to Cap'n Proto bytes.",
1447        sc.factory_name
1448    );
1449
1450    let match_arms: Vec<TokenStream> = sc
1451        .inner_response_variants
1452        .iter()
1453        .map(|v| generate_scope_serializer_arm(&response_type, v, resolved))
1454        .collect();
1455
1456    quote! {
1457        #[doc = #doc]
1458        fn #fn_name(request_id: u64, variant: &#response_type) -> anyhow::Result<Vec<u8>> {
1459            hyprstream_rpc::serialize_message(|msg| {
1460                let mut resp = msg.init_root::<#capnp_mod::#resp_snake::Builder>();
1461                resp.set_request_id(request_id);
1462                let mut inner = resp.#scope_result_init();
1463                match variant {
1464                    #(#match_arms)*
1465                }
1466            })
1467        }
1468    }
1469}
1470
1471/// Generate a single serializer match arm for a scope response variant.
1472fn generate_scope_serializer_arm(
1473    response_type: &syn::Ident,
1474    v: &UnionVariant,
1475    resolved: &ResolvedSchema,
1476) -> TokenStream {
1477    let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1478    let v_snake = &resolved.name(&v.name).snake;
1479    let setter_name = format_ident!("set_{}", v_snake);
1480    let init_name = format_ident!("init_{}", v_snake);
1481
1482    let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
1483    match ct {
1484        CapnpType::Void => quote! {
1485            #response_type::#variant_pascal => {
1486                inner.#setter_name(());
1487            }
1488        },
1489        CapnpType::Text | CapnpType::Data => quote! {
1490            #response_type::#variant_pascal(v) => {
1491                inner.#setter_name(v);
1492            }
1493        },
1494        _ if ct.is_numeric() => quote! {
1495            #response_type::#variant_pascal(v) => {
1496                inner.#setter_name(*v);
1497            }
1498        },
1499        CapnpType::Struct(ref name) => {
1500            if resolved.is_struct(name) {
1501                quote! {
1502                    #response_type::#variant_pascal(ref v) => {
1503                        let mut s = inner.#init_name();
1504                        <_ as hyprstream_rpc::ToCapnp>::write_to(v, &mut s);
1505                    }
1506                }
1507            } else {
1508                quote! {
1509                    #response_type::#variant_pascal(_) => {}
1510                }
1511            }
1512        }
1513        CapnpType::ListStruct(ref inner_name) => {
1514            if resolved.is_struct(inner_name) {
1515                quote! {
1516                    #response_type::#variant_pascal(ref items) => {
1517                        let mut list = inner.#init_name(items.len() as u32);
1518                        for (i, item) in items.iter().enumerate() {
1519                            <_ as hyprstream_rpc::ToCapnp>::write_to(item, &mut list.reborrow().get(i as u32));
1520                        }
1521                    }
1522                }
1523            } else {
1524                quote! {
1525                    #response_type::#variant_pascal(_) => {}
1526                }
1527            }
1528        }
1529        CapnpType::ListText | CapnpType::ListData => quote! {
1530            #response_type::#variant_pascal(ref items) => {
1531                let mut list = inner.#init_name(items.len() as u32);
1532                for (i, item) in items.iter().enumerate() {
1533                    list.set(i as u32, item);
1534                }
1535            }
1536        },
1537        CapnpType::ListPrimitive(_) => quote! {
1538            #response_type::#variant_pascal(ref items) => {
1539                let mut list = inner.#init_name(items.len() as u32);
1540                for (i, item) in items.iter().enumerate() {
1541                    list.set(i as u32, *item);
1542                }
1543            }
1544        },
1545        _ => quote! {
1546            #response_type::#variant_pascal(..) => {}
1547        },
1548    }
1549}
1550
1551/// Generate a nested scope response serializer (e.g., `serialize_worktree_response()`,
1552/// `serialize_ctl_response()`).
1553///
1554/// Wraps N+1 levels: outer response → ancestor[0]_result → ... → nc_result → variant.
1555/// `ancestors` contains all scopes above this one.
1556fn generate_nested_scope_response_serializer(
1557    pascal: &str,
1558    capnp_mod: &syn::Ident,
1559    ancestors: &[&ScopedClient],
1560    nc: &ScopedClient,
1561    resolved: &ResolvedSchema,
1562) -> TokenStream {
1563    let fn_name = format_ident!("serialize_{}_response", to_snake_case(&nc.factory_name));
1564    let response_type = format_ident!("{}ResponseVariant", nc.client_name);
1565    let resp_snake = format_ident!("{}", to_snake_case(&format!("{pascal}Response")));
1566    let depth = ancestors.len() + 1;
1567    let doc = format!(
1568        "Serialize a nested {} scope response variant to Cap'n Proto bytes ({}-level wrap).",
1569        nc.factory_name,
1570        depth + 1 // +1 for outer response
1571    );
1572
1573    let match_arms: Vec<TokenStream> = nc
1574        .inner_response_variants
1575        .iter()
1576        .map(|v| generate_scope_serializer_arm(&response_type, v, resolved))
1577        .collect();
1578
1579    // Build the chain of init_ calls: resp.init_ancestor[0]_result().init_ancestor[1]_result()...init_nc_result()
1580    // All ancestors + nc itself form the full chain of scopes to wrap
1581    let full_chain: Vec<&ScopedClient> = ancestors
1582        .iter()
1583        .copied()
1584        .chain(std::iter::once(nc))
1585        .collect();
1586
1587    // Generate the init chain as sequential let bindings
1588    let mut init_stmts = Vec::new();
1589    for (i, scope) in full_chain.iter().enumerate() {
1590        let init_fn = format_ident!(
1591            "init_{}",
1592            to_snake_case(&format!("{}Result", scope.factory_name))
1593        );
1594        if i == 0 {
1595            // First level: init from resp
1596            init_stmts.push(quote! { let __lvl = resp.#init_fn(); });
1597        } else if i == full_chain.len() - 1 {
1598            // Last level: bind to `inner` (mutable)
1599            init_stmts.push(quote! { let mut inner = __lvl.#init_fn(); });
1600        } else {
1601            // Intermediate levels: chain through __lvl
1602            init_stmts.push(quote! { let __lvl = __lvl.#init_fn(); });
1603        }
1604    }
1605
1606    quote! {
1607        #[doc = #doc]
1608        fn #fn_name(request_id: u64, variant: &#response_type) -> anyhow::Result<Vec<u8>> {
1609            hyprstream_rpc::serialize_message(|msg| {
1610                let mut resp = msg.init_root::<#capnp_mod::#resp_snake::Builder>();
1611                resp.set_request_id(request_id);
1612                #(#init_stmts)*
1613                match variant {
1614                    #(#match_arms)*
1615                }
1616            })
1617        }
1618    }
1619}
1620
1621// ═══════════════════════════════════════════════════════════════════════════
1622// Two-Phase Scoped Dispatch Helpers
1623// ═══════════════════════════════════════════════════════════════════════════
1624
1625/// Generate a variant tag enum for scoped dispatch two-phase pattern.
1626///
1627/// This enum contains just the variant identifiers (no data), making it Copy
1628/// and safe to hold across await points. Used in Phase 2 to match and dispatch.
1629fn generate_scope_variant_tag_enum(sc: &ScopedClient, resolved: &ResolvedSchema) -> TokenStream {
1630    let enum_name = format_ident!("{}VariantTag", to_pascal_case(&sc.factory_name));
1631    let variants: Vec<TokenStream> = sc
1632        .inner_request_variants
1633        .iter()
1634        .filter(|v| v.name != "error")
1635        .map(|v| {
1636            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1637            quote! { #variant_pascal }
1638        })
1639        .collect();
1640
1641    let nested_variants: Vec<TokenStream> = sc
1642        .nested_clients
1643        .iter()
1644        .map(|nc| {
1645            let variant_pascal = format_ident!("{}", to_pascal_case(&nc.factory_name));
1646            quote! { #variant_pascal }
1647        })
1648        .collect();
1649
1650    quote! {
1651        #[derive(Debug, Copy, Clone)]
1652        enum #enum_name {
1653            #(#variants,)*
1654            #(#nested_variants,)*
1655        }
1656    }
1657}
1658
1659/// Generate parameter enums for scoped dispatch.
1660///
1661/// Creates an enum variant for each request variant, holding the extracted owned data.
1662fn generate_scope_params_enum(sc: &ScopedClient, resolved: &ResolvedSchema) -> TokenStream {
1663    let enum_name = format_ident!("{}Params", to_pascal_case(&sc.factory_name));
1664
1665    let variants: Vec<TokenStream> = sc
1666        .inner_request_variants
1667        .iter()
1668        .filter(|v| v.name != "error")
1669        .map(|v| {
1670            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1671            let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
1672
1673            match ct {
1674                CapnpType::Void => quote! { #variant_pascal },
1675                CapnpType::Text => quote! { #variant_pascal(String) },
1676                CapnpType::Data => quote! { #variant_pascal(Vec<u8>) },
1677                CapnpType::Bool => quote! { #variant_pascal(bool) },
1678                _ if ct.is_numeric() => {
1679                    let rust_type = rust_type_tokens(&ct.rust_param_type());
1680                    quote! { #variant_pascal(#rust_type) }
1681                }
1682                CapnpType::Struct(ref name) => {
1683                    if let Some(sdef) = resolved.find_struct(name) {
1684                        if sdef.is_pure_union() {
1685                            quote! { #variant_pascal }
1686                        } else {
1687                            let struct_ident = format_ident!("{}", name);
1688                            quote! { #variant_pascal(#struct_ident) }
1689                        }
1690                    } else {
1691                        quote! { #variant_pascal }
1692                    }
1693                }
1694                _ => quote! { #variant_pascal },
1695            }
1696        })
1697        .collect();
1698
1699    let nested_variants: Vec<TokenStream> = sc
1700        .nested_clients
1701        .iter()
1702        .map(|nc| {
1703            let variant_pascal = format_ident!("{}", to_pascal_case(&nc.factory_name));
1704            quote! { #variant_pascal }
1705        })
1706        .collect();
1707
1708    quote! {
1709        enum #enum_name {
1710            #(#variants,)*
1711            #(#nested_variants,)*
1712        }
1713    }
1714}
1715
1716/// Generate the extraction phase for scoped dispatch (Phase 1).
1717///
1718/// Returns TokenStream for a block that:
1719/// 1. Reads Cap'n Proto message
1720/// 2. Navigates to scope
1721/// 3. Extracts scope fields
1722/// 4. Matches on inner variants and extracts all params to owned types
1723/// 5. Returns (variant_tag, scope_fields, params)
1724fn generate_scope_extraction_phase(
1725    pascal: &str,
1726    capnp_mod: &syn::Ident,
1727    sc: &ScopedClient,
1728    resolved: &ResolvedSchema,
1729) -> TokenStream {
1730    let outer_req_snake = format_ident!("{}", to_snake_case(&format!("{pascal}Request")));
1731    let scope_variant_pascal = format_ident!("{}", to_pascal_case(&sc.factory_name));
1732    let base_name = sc.client_name.trim_end_matches("Client");
1733    let inner_req_mod = format_ident!("{}_request", to_capnp_module_name(base_name));
1734    let bail_msg = format!("expected {} scope in request", sc.factory_name);
1735    let tag_enum = format_ident!("{}VariantTag", to_pascal_case(&sc.factory_name));
1736    let params_enum = format_ident!("{}Params", to_pascal_case(&sc.factory_name));
1737
1738    // Scope field idents
1739    let scope_field_idents: Vec<syn::Ident> = sc
1740        .scope_fields
1741        .iter()
1742        .map(|f| resolved.name(&f.name).snake_ident.clone())
1743        .collect();
1744
1745    // Extraction arms for each variant
1746    let extraction_arms: Vec<TokenStream> = sc.inner_request_variants.iter()
1747        .filter(|v| v.name != "error")
1748        .map(|v| {
1749            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1750            let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
1751
1752            match ct {
1753                CapnpType::Void => {
1754                    quote! {
1755                        Which::#variant_pascal(()) => {
1756                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal)
1757                        }
1758                    }
1759                },
1760                CapnpType::Text => {
1761                    quote! {
1762                        Which::#variant_pascal(v) => {
1763                            let v = v?.to_string()?;
1764                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(v))
1765                        }
1766                    }
1767                },
1768                CapnpType::Data => {
1769                    quote! {
1770                        Which::#variant_pascal(v) => {
1771                            let v = v?.to_vec();
1772                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(v))
1773                        }
1774                    }
1775                },
1776                _ if ct.is_numeric() => {
1777                    quote! {
1778                        Which::#variant_pascal(v) => {
1779                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(v))
1780                        }
1781                    }
1782                },
1783                CapnpType::Struct(ref name) => {
1784                    if let Some(sdef) = resolved.find_struct(name) {
1785                        if sdef.is_pure_union() {
1786                            quote! {
1787                                Which::#variant_pascal(_) => {
1788                                    (#tag_enum::#variant_pascal, #params_enum::#variant_pascal)
1789                                }
1790                            }
1791                        } else {
1792                            // Extract struct fields to owned types
1793                            quote! {
1794                                Which::#variant_pascal(v) => {
1795                                    let v = v?;
1796                                    let data = hyprstream_rpc::capnp::FromCapnp::read_from(v)?;
1797                                    (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(data))
1798                                }
1799                            }
1800                        }
1801                    } else {
1802                        quote! {
1803                            Which::#variant_pascal(_) => {
1804                                anyhow::bail!("Struct not found in schema");
1805                            }
1806                        }
1807                    }
1808                },
1809                _ => {
1810                    quote! {
1811                        Which::#variant_pascal(_) => {
1812                            anyhow::bail!("Unsupported variant type");
1813                        }
1814                    }
1815                }
1816            }
1817        })
1818        .collect();
1819
1820    // Nested client extraction arms
1821    let nested_extraction_arms: Vec<TokenStream> = sc
1822        .nested_clients
1823        .iter()
1824        .map(|nc| {
1825            let variant_pascal = format_ident!("{}", to_pascal_case(&nc.factory_name));
1826            quote! {
1827                Which::#variant_pascal(_) => {
1828                    (#tag_enum::#variant_pascal, #params_enum::#variant_pascal)
1829                }
1830            }
1831        })
1832        .collect();
1833
1834    // Scope field extractions
1835    let scope_field_extractions: Vec<TokenStream> = sc
1836        .scope_fields
1837        .iter()
1838        .map(|f| {
1839            let name = resolved.name(&f.name).snake_ident.clone();
1840            let getter = format_ident!("get_{}", resolved.name(&f.name).snake);
1841            let ct = resolved.resolve_type(&f.type_name).capnp_type.clone();
1842            match ct {
1843                CapnpType::Text => quote! {
1844                    let #name = inner.#getter()?.to_string()?;
1845                },
1846                _ if ct.is_numeric() => quote! { let #name = inner.#getter(); },
1847                _ => quote! {
1848                    let #name = inner.#getter()?.to_string()?;
1849                },
1850            }
1851        })
1852        .collect();
1853
1854    quote! {
1855        let (variant_tag, scope_fields, params) = {
1856            // Navigate the ONE decoded message (v16 §5.2) — no re-decode.
1857            let req = body.root::<#capnp_mod::#outer_req_snake::Reader>()?;
1858
1859            let inner = match req.which()? {
1860                #capnp_mod::#outer_req_snake::Which::#scope_variant_pascal(r) => r?,
1861                _ => anyhow::bail!(#bail_msg),
1862            };
1863
1864            #(#scope_field_extractions)*
1865
1866            use #capnp_mod::#inner_req_mod::Which;
1867            let (tag, params) = match inner.which()? {
1868                #(#extraction_arms)*
1869                #(#nested_extraction_arms)*
1870                #[allow(unreachable_patterns)]
1871                _ => anyhow::bail!("Unknown request variant"),
1872            };
1873
1874            (tag, (#(#scope_field_idents,)*), params)
1875        };
1876    }
1877}
1878
1879/// Generate the dispatch phase for scoped dispatch (Phase 2).
1880///
1881/// Returns TokenStream for matching on the variant tag and calling async handlers.
1882/// No Cap'n Proto Readers are held here, only owned types.
1883fn generate_scope_dispatch_phase(
1884    sc: &ScopedClient,
1885    resolved: &ResolvedSchema,
1886    scope_field_idents: &[syn::Ident],
1887    parent_trait: &syn::Ident,
1888    scope_trait: &syn::Ident,
1889    service_name: &str,
1890    serializer_fn: &syn::Ident,
1891) -> TokenStream {
1892    let tag_enum = format_ident!("{}VariantTag", to_pascal_case(&sc.factory_name));
1893    let params_enum = format_ident!("{}Params", to_pascal_case(&sc.factory_name));
1894    let response_type = format_ident!("{}ResponseVariant", sc.client_name);
1895
1896    // Build scope field arg expressions: pass by-ref for Text/Data (String/Vec<u8>),
1897    // by-value for numeric types. This matches the handler trait param types.
1898    let scope_field_args: Vec<TokenStream> = sc
1899        .scope_fields
1900        .iter()
1901        .zip(scope_field_idents.iter())
1902        .map(|(f, ident)| {
1903            if resolved.resolve_type(&f.type_name).is_by_ref {
1904                quote! { &#ident }
1905            } else {
1906                quote! { #ident }
1907            }
1908        })
1909        .collect();
1910
1911    let dispatch_arms: Vec<TokenStream> = sc.inner_request_variants.iter()
1912        .filter(|v| v.name != "error")
1913        .map(|v| {
1914            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1915            let handler_method = format_ident!("handle_{}", resolved.name(&v.name).snake);
1916            let resp_variant_pascal = resolved.name(&v.name).pascal_ident.clone();
1917
1918            // Generate auth check if variant has a scope annotation.
1919            // Returns Error(ErrorInfo) on auth failure instead of propagating via ?.
1920            let auth_stmt = if let Some(action) = parse_scope_for_auth(&v.scope) {
1921                let action_str = action.to_owned();
1922                let svc = service_name.to_owned();
1923                let resource_expr = if let Some(first_scope_field) = scope_field_idents.first() {
1924                    quote! { format!("{}:{}", #svc, #first_scope_field) }
1925                } else {
1926                    quote! { (#svc).to_string() }
1927                };
1928                quote! {
1929                    let __audit_resource = #resource_expr;
1930                    let __authz = #parent_trait::authorize(handler, ctx, &__audit_resource, #action_str).await;
1931                    ctx.audit_authz(&__audit_resource, #action_str, __authz.is_ok());
1932                    if let Err(e) = __authz {
1933                        let err_variant = #response_type::Error(ErrorInfo {
1934                            message: e.to_string(),
1935                            code: "UNAUTHORIZED".to_string(),
1936                            details: String::new(),
1937                        });
1938                        return Ok((#serializer_fn(request_id, &err_variant)?, None));
1939                    }
1940                }
1941            } else {
1942                TokenStream::new()
1943            };
1944
1945            // Check if streaming
1946            let is_streaming = is_scoped_streaming_variant(v, &sc.inner_response_variants);
1947
1948            // Check if response is void
1949            let resp_variant = sc.inner_response_variants.iter().find(|rv| rv.name == v.name);
1950            let resp_type_is_void = resp_variant.map(|rv| rv.type_name == "Void").unwrap_or(false);
1951
1952            let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
1953
1954            if is_streaming {
1955                // Streaming variant
1956                match ct {
1957                    CapnpType::Void => {
1958                        quote! {
1959                            #tag_enum::#variant_pascal => {
1960                                let #params_enum::#variant_pascal = params else { unreachable!() };
1961                                #auth_stmt
1962                                let (stream_info, continuation) = #scope_trait::#handler_method(handler, ctx, request_id, #(#scope_field_args,)*).await?;
1963                                let variant = #response_type::#resp_variant_pascal(stream_info);
1964                                return Ok((#serializer_fn(request_id, &variant)?, Some(continuation)));
1965                            }
1966                        }
1967                    },
1968                    _ => {
1969                        quote! {
1970                            #tag_enum::#variant_pascal => {
1971                                let #params_enum::#variant_pascal(data) = params else { unreachable!() };
1972                                #auth_stmt
1973                                let (stream_info, continuation) = #scope_trait::#handler_method(handler, ctx, request_id, #(#scope_field_args,)* &data).await?;
1974                                let variant = #response_type::#resp_variant_pascal(stream_info);
1975                                return Ok((#serializer_fn(request_id, &variant)?, Some(continuation)));
1976                            }
1977                        }
1978                    }
1979                }
1980            } else {
1981                // Non-streaming variant
1982                let ok_wrap = if resp_type_is_void {
1983                    quote! { Ok(()) => #response_type::#resp_variant_pascal }
1984                } else {
1985                    quote! { Ok(data) => #response_type::#resp_variant_pascal(data) }
1986                };
1987
1988                let err_wrap = quote! {
1989                    Err(e) => #response_type::Error(ErrorInfo {
1990                        message: e.to_string(),
1991                        code: "INTERNAL".to_string(),
1992                        details: String::new(),
1993                    })
1994                };
1995
1996                match ct {
1997                    CapnpType::Void => {
1998                        quote! {
1999                            #tag_enum::#variant_pascal => {
2000                                let #params_enum::#variant_pascal = params else { unreachable!() };
2001                                #auth_stmt
2002                                match #scope_trait::#handler_method(handler, ctx, request_id, #(#scope_field_args,)*).await {
2003                                    #ok_wrap,
2004                                    #err_wrap,
2005                                }
2006                            }
2007                        }
2008                    },
2009                    CapnpType::Text | CapnpType::Data => {
2010                        quote! {
2011                            #tag_enum::#variant_pascal => {
2012                                let #params_enum::#variant_pascal(v) = params else { unreachable!() };
2013                                #auth_stmt
2014                                match #scope_trait::#handler_method(handler, ctx, request_id, #(#scope_field_args,)* &v).await {
2015                                    #ok_wrap,
2016                                    #err_wrap,
2017                                }
2018                            }
2019                        }
2020                    },
2021                    _ if ct.is_numeric() => {
2022                        quote! {
2023                            #tag_enum::#variant_pascal => {
2024                                let #params_enum::#variant_pascal(v) = params else { unreachable!() };
2025                                #auth_stmt
2026                                match #scope_trait::#handler_method(handler, ctx, request_id, #(#scope_field_args,)* v).await {
2027                                    #ok_wrap,
2028                                    #err_wrap,
2029                                }
2030                            }
2031                        }
2032                    },
2033                    CapnpType::Struct(_) => {
2034                        quote! {
2035                            #tag_enum::#variant_pascal => {
2036                                let #params_enum::#variant_pascal(data) = params else { unreachable!() };
2037                                #auth_stmt
2038                                match #scope_trait::#handler_method(handler, ctx, request_id, #(#scope_field_args,)* &data).await {
2039                                    #ok_wrap,
2040                                    #err_wrap,
2041                                }
2042                            }
2043                        }
2044                    },
2045                    _ => {
2046                        quote! {
2047                            #tag_enum::#variant_pascal => {
2048                                anyhow::bail!("Unsupported variant type in dispatch");
2049                            }
2050                        }
2051                    }
2052                }
2053            }
2054        })
2055        .collect();
2056
2057    // Nested client dispatch arms
2058    let nested_dispatch_arms: Vec<TokenStream> = sc.nested_clients.iter().map(|nc| {
2059        let variant_pascal = format_ident!("{}", to_pascal_case(&nc.factory_name));
2060        let nested_dispatch_fn = format_ident!("dispatch_{}", to_snake_case(&nc.factory_name));
2061        quote! {
2062            #tag_enum::#variant_pascal => {
2063                return #nested_dispatch_fn(handler, ctx, request_id, #(#scope_field_args,)* body).await;
2064            }
2065        }
2066    }).collect();
2067
2068    quote! {
2069        use #tag_enum::*;
2070        let result = match variant_tag {
2071            #(#dispatch_arms)*
2072            #(#nested_dispatch_arms)*
2073        };
2074
2075        Ok((#serializer_fn(request_id, &result)?, None))
2076    }
2077}
2078
2079/// Generate extraction phase for nested scope dispatch (N-level).
2080///
2081/// Navigates outer → ancestor[0] → ancestor[1] → ... → nc, extracts nc's scope fields
2082/// and inner union variant. `ancestors` contains all scopes above nc.
2083fn generate_nested_scope_extraction_phase(
2084    pascal: &str,
2085    capnp_mod: &syn::Ident,
2086    ancestors: &[&ScopedClient],
2087    nc: &ScopedClient,
2088    resolved: &ResolvedSchema,
2089) -> TokenStream {
2090    let outer_req_snake = format_ident!("{}", to_snake_case(&format!("{pascal}Request")));
2091
2092    let tag_enum = format_ident!("{}VariantTag", to_pascal_case(&nc.factory_name));
2093    let params_enum = format_ident!("{}Params", to_pascal_case(&nc.factory_name));
2094
2095    // Nested scope field idents
2096    let nested_scope_idents: Vec<syn::Ident> = nc
2097        .scope_fields
2098        .iter()
2099        .map(|f| resolved.name(&f.name).snake_ident.clone())
2100        .collect();
2101
2102    // Build the navigation chain: outer → ancestor[0] → ancestor[1] → ... → nc
2103    // The full chain of scopes to navigate through (ancestors + nc)
2104    let full_chain: Vec<&ScopedClient> = ancestors
2105        .iter()
2106        .copied()
2107        .chain(std::iter::once(nc))
2108        .collect();
2109
2110    // Generate navigation statements to drill down to nc's inner request
2111    let mut nav_stmts = Vec::new();
2112
2113    for (i, scope) in full_chain.iter().enumerate() {
2114        let variant_pascal = format_ident!("{}", to_pascal_case(&scope.factory_name));
2115
2116        if i == 0 {
2117            // First level: navigate from outer request
2118            let bail_msg = format!("expected {} scope in request", scope.factory_name);
2119            nav_stmts.push(quote! {
2120                let __nav = match req.which()? {
2121                    #capnp_mod::#outer_req_snake::Which::#variant_pascal(r) => r?,
2122                    _ => anyhow::bail!(#bail_msg),
2123                };
2124            });
2125        } else if i < full_chain.len() - 1 {
2126            // Intermediate levels: navigate through parent's inner union
2127            let prev = full_chain[i - 1];
2128            let prev_base = prev.client_name.trim_end_matches("Client");
2129            let prev_req_mod = format_ident!("{}_request", to_capnp_module_name(prev_base));
2130            let which_alias = format_ident!("__NavW{}", i);
2131            let bail_msg = format!(
2132                "expected {} scope in {} request",
2133                scope.factory_name, prev.factory_name
2134            );
2135            nav_stmts.push(quote! {
2136                use #capnp_mod::#prev_req_mod::Which as #which_alias;
2137                let __nav = match __nav.which()? {
2138                    #which_alias::#variant_pascal(r) => r?,
2139                    _ => anyhow::bail!(#bail_msg),
2140                };
2141            });
2142        } else {
2143            // Last level (nc): navigate to nc's inner request
2144            let prev = full_chain[i - 1];
2145            let prev_base = prev.client_name.trim_end_matches("Client");
2146            let prev_req_mod = format_ident!("{}_request", to_capnp_module_name(prev_base));
2147            let which_alias = format_ident!("__NavW{}", i);
2148            let bail_msg = format!(
2149                "expected {} scope in {} request",
2150                scope.factory_name, prev.factory_name
2151            );
2152            nav_stmts.push(quote! {
2153                use #capnp_mod::#prev_req_mod::Which as #which_alias;
2154                let nested_inner = match __nav.which()? {
2155                    #which_alias::#variant_pascal(r) => r?,
2156                    _ => anyhow::bail!(#bail_msg),
2157                };
2158            });
2159        }
2160    }
2161
2162    // Nested scope field extractions from nested_inner
2163    let nested_scope_extractions: Vec<TokenStream> = nc
2164        .scope_fields
2165        .iter()
2166        .map(|f| {
2167            let name = resolved.name(&f.name).snake_ident.clone();
2168            let getter = format_ident!("get_{}", resolved.name(&f.name).snake);
2169            let ct = resolved.resolve_type(&f.type_name).capnp_type.clone();
2170            match ct {
2171                CapnpType::Text => quote! {
2172                    let #name = nested_inner.#getter()?.to_string()?;
2173                },
2174                _ if ct.is_numeric() => quote! { let #name = nested_inner.#getter(); },
2175                _ => quote! {
2176                    let #name = nested_inner.#getter()?.to_string()?;
2177                },
2178            }
2179        })
2180        .collect();
2181
2182    // nc's inner request module for variant extraction
2183    let nested_base_name = nc.client_name.trim_end_matches("Client");
2184    let nested_inner_req_mod = format_ident!("{}_request", to_capnp_module_name(nested_base_name));
2185
2186    // Extraction arms for each nested variant
2187    let extraction_arms: Vec<TokenStream> = nc.inner_request_variants.iter()
2188        .filter(|v| v.name != "error")
2189        .map(|v| {
2190            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
2191            let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
2192
2193            match ct {
2194                CapnpType::Void => {
2195                    quote! {
2196                        Which::#variant_pascal(()) => {
2197                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal)
2198                        }
2199                    }
2200                },
2201                CapnpType::Text => {
2202                    quote! {
2203                        Which::#variant_pascal(v) => {
2204                            let v = v?.to_string()?;
2205                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(v))
2206                        }
2207                    }
2208                },
2209                CapnpType::Data => {
2210                    quote! {
2211                        Which::#variant_pascal(v) => {
2212                            let v = v?.to_vec();
2213                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(v))
2214                        }
2215                    }
2216                },
2217                _ if ct.is_numeric() => {
2218                    quote! {
2219                        Which::#variant_pascal(v) => {
2220                            (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(v))
2221                        }
2222                    }
2223                },
2224                CapnpType::Struct(ref name) => {
2225                    if let Some(sdef) = resolved.find_struct(name) {
2226                        if sdef.is_pure_union() {
2227                            quote! {
2228                                Which::#variant_pascal(_) => {
2229                                    (#tag_enum::#variant_pascal, #params_enum::#variant_pascal)
2230                                }
2231                            }
2232                        } else {
2233                            quote! {
2234                                Which::#variant_pascal(v) => {
2235                                    let v = v?;
2236                                    let data = hyprstream_rpc::capnp::FromCapnp::read_from(v)?;
2237                                    (#tag_enum::#variant_pascal, #params_enum::#variant_pascal(data))
2238                                }
2239                            }
2240                        }
2241                    } else {
2242                        quote! {
2243                            Which::#variant_pascal(_) => {
2244                                anyhow::bail!("Struct not found in schema");
2245                            }
2246                        }
2247                    }
2248                },
2249                _ => {
2250                    quote! {
2251                        Which::#variant_pascal(_) => {
2252                            anyhow::bail!("Unsupported variant type");
2253                        }
2254                    }
2255                }
2256            }
2257        })
2258        .collect();
2259
2260    // Nested extraction arms for nc's own nested clients (if any)
2261    let nested_extraction_arms: Vec<TokenStream> = nc
2262        .nested_clients
2263        .iter()
2264        .map(|inner_nc| {
2265            let variant_pascal = format_ident!("{}", to_pascal_case(&inner_nc.factory_name));
2266            quote! {
2267                Which::#variant_pascal(_) => {
2268                    (#tag_enum::#variant_pascal, #params_enum::#variant_pascal)
2269                }
2270            }
2271        })
2272        .collect();
2273
2274    quote! {
2275        let (variant_tag, nested_scope_fields, params) = {
2276            // Navigate the ONE decoded message (v16 §5.2) — no re-decode.
2277            let req = body.root::<#capnp_mod::#outer_req_snake::Reader>()?;
2278
2279            // Navigate through ancestor scopes to reach nc
2280            #(#nav_stmts)*
2281
2282            // Extract nested scope fields
2283            #(#nested_scope_extractions)*
2284
2285            // Dispatch the nested inner union
2286            use #capnp_mod::#nested_inner_req_mod::Which;
2287            let (tag, params) = match nested_inner.which()? {
2288                #(#extraction_arms)*
2289                #(#nested_extraction_arms)*
2290                #[allow(unreachable_patterns)]
2291                _ => anyhow::bail!("Unknown request variant"),
2292            };
2293
2294            (tag, (#(#nested_scope_idents,)*), params)
2295        };
2296    }
2297}
2298
2299/// Generate dispatch phase for nested scope dispatch.
2300///
2301/// `ancestor_scope_idents` contains ALL ancestor scope field idents (flattened).
2302#[allow(clippy::too_many_arguments)]
2303fn generate_nested_scope_dispatch_phase(
2304    nc: &ScopedClient,
2305    resolved: &ResolvedSchema,
2306    ancestor_scope_idents: &[syn::Ident],
2307    nested_scope_idents: &[syn::Ident],
2308    parent_trait: &syn::Ident,
2309    nested_trait: &syn::Ident,
2310    service_name: &str,
2311    serializer_fn: &syn::Ident,
2312) -> TokenStream {
2313    let tag_enum = format_ident!("{}VariantTag", to_pascal_case(&nc.factory_name));
2314    let params_enum = format_ident!("{}Params", to_pascal_case(&nc.factory_name));
2315    let response_type = format_ident!("{}ResponseVariant", nc.client_name);
2316
2317    // Ancestor scope fields are already by-ref (function params have &str type),
2318    // so pass them as-is. Nested scope fields are extracted as owned String,
2319    // so pass by-ref for Text/Data, by-value for numeric.
2320    let parent_scope_args: Vec<TokenStream> = ancestor_scope_idents
2321        .iter()
2322        .map(|ident| {
2323            quote! { #ident }
2324        })
2325        .collect();
2326
2327    let nested_scope_args: Vec<TokenStream> = nc
2328        .scope_fields
2329        .iter()
2330        .zip(nested_scope_idents.iter())
2331        .map(|(f, ident)| {
2332            if resolved.resolve_type(&f.type_name).is_by_ref {
2333                quote! { &#ident }
2334            } else {
2335                quote! { #ident }
2336            }
2337        })
2338        .collect();
2339
2340    let dispatch_arms: Vec<TokenStream> = nc.inner_request_variants.iter()
2341        .filter(|v| v.name != "error")
2342        .map(|v| {
2343            let variant_pascal = resolved.name(&v.name).pascal_ident.clone();
2344            let handler_method = format_ident!("handle_{}", resolved.name(&v.name).snake);
2345            let resp_variant_pascal = resolved.name(&v.name).pascal_ident.clone();
2346
2347            // Generate auth check — returns Error(ErrorInfo) on failure instead of propagating via ?
2348            let auth_stmt = if let Some(action) = parse_scope_for_auth(&v.scope) {
2349                let action_str = action.to_owned();
2350                let svc = service_name.to_owned();
2351                let resource_expr = if let Some(first_parent_field) = ancestor_scope_idents.first() {
2352                    quote! { format!("{}:{}", #svc, #first_parent_field) }
2353                } else {
2354                    quote! { (#svc).to_string() }
2355                };
2356                quote! {
2357                    let __audit_resource = #resource_expr;
2358                    let __authz = #parent_trait::authorize(handler, ctx, &__audit_resource, #action_str).await;
2359                    ctx.audit_authz(&__audit_resource, #action_str, __authz.is_ok());
2360                    if let Err(e) = __authz {
2361                        let err_variant = #response_type::Error(ErrorInfo {
2362                            message: e.to_string(),
2363                            code: "UNAUTHORIZED".to_string(),
2364                            details: String::new(),
2365                        });
2366                        return Ok((#serializer_fn(request_id, &err_variant)?, None));
2367                    }
2368                }
2369            } else {
2370                TokenStream::new()
2371            };
2372
2373            // Check if streaming
2374            let is_streaming = is_scoped_streaming_variant(v, &nc.inner_response_variants);
2375
2376            // Check if response is void
2377            let resp_variant = nc.inner_response_variants.iter().find(|rv| rv.name == v.name);
2378            let resp_type_is_void = resp_variant.map(|rv| rv.type_name == "Void").unwrap_or(false);
2379
2380            let ct = resolved.resolve_type(&v.type_name).capnp_type.clone();
2381
2382            if is_streaming {
2383                match ct {
2384                    CapnpType::Void => {
2385                        quote! {
2386                            #tag_enum::#variant_pascal => {
2387                                let #params_enum::#variant_pascal = params else { unreachable!() };
2388                                #auth_stmt
2389                                let (stream_info, continuation) = #nested_trait::#handler_method(
2390                                    handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)*
2391                                ).await?;
2392                                let variant = #response_type::#resp_variant_pascal(stream_info);
2393                                return Ok((#serializer_fn(request_id, &variant)?, Some(continuation)));
2394                            }
2395                        }
2396                    },
2397                    _ => {
2398                        quote! {
2399                            #tag_enum::#variant_pascal => {
2400                                let #params_enum::#variant_pascal(data) = params else { unreachable!() };
2401                                #auth_stmt
2402                                let (stream_info, continuation) = #nested_trait::#handler_method(
2403                                    handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)* &data
2404                                ).await?;
2405                                let variant = #response_type::#resp_variant_pascal(stream_info);
2406                                return Ok((#serializer_fn(request_id, &variant)?, Some(continuation)));
2407                            }
2408                        }
2409                    }
2410                }
2411            } else {
2412                let ok_wrap = if resp_type_is_void {
2413                    quote! { Ok(()) => #response_type::#resp_variant_pascal }
2414                } else {
2415                    quote! { Ok(data) => #response_type::#resp_variant_pascal(data) }
2416                };
2417
2418                let err_wrap = quote! {
2419                    Err(e) => #response_type::Error(ErrorInfo {
2420                        message: e.to_string(),
2421                        code: "INTERNAL".to_string(),
2422                        details: String::new(),
2423                    })
2424                };
2425
2426                match ct {
2427                    CapnpType::Void => {
2428                        quote! {
2429                            #tag_enum::#variant_pascal => {
2430                                let #params_enum::#variant_pascal = params else { unreachable!() };
2431                                #auth_stmt
2432                                match #nested_trait::#handler_method(
2433                                    handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)*
2434                                ).await {
2435                                    #ok_wrap,
2436                                    #err_wrap,
2437                                }
2438                            }
2439                        }
2440                    },
2441                    CapnpType::Text | CapnpType::Data => {
2442                        quote! {
2443                            #tag_enum::#variant_pascal => {
2444                                let #params_enum::#variant_pascal(v) = params else { unreachable!() };
2445                                #auth_stmt
2446                                match #nested_trait::#handler_method(
2447                                    handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)* &v
2448                                ).await {
2449                                    #ok_wrap,
2450                                    #err_wrap,
2451                                }
2452                            }
2453                        }
2454                    },
2455                    _ if ct.is_numeric() => {
2456                        quote! {
2457                            #tag_enum::#variant_pascal => {
2458                                let #params_enum::#variant_pascal(v) = params else { unreachable!() };
2459                                #auth_stmt
2460                                match #nested_trait::#handler_method(
2461                                    handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)* v
2462                                ).await {
2463                                    #ok_wrap,
2464                                    #err_wrap,
2465                                }
2466                            }
2467                        }
2468                    },
2469                    CapnpType::Struct(_) => {
2470                        quote! {
2471                            #tag_enum::#variant_pascal => {
2472                                let #params_enum::#variant_pascal(data) = params else { unreachable!() };
2473                                #auth_stmt
2474                                match #nested_trait::#handler_method(
2475                                    handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)* &data
2476                                ).await {
2477                                    #ok_wrap,
2478                                    #err_wrap,
2479                                }
2480                            }
2481                        }
2482                    },
2483                    _ => {
2484                        quote! {
2485                            #tag_enum::#variant_pascal => {
2486                                anyhow::bail!("Unsupported variant type in dispatch");
2487                            }
2488                        }
2489                    }
2490                }
2491            }
2492        })
2493        .collect();
2494
2495    // Nested client dispatch arms: delegate to nc's own nested dispatch functions
2496    let nested_dispatch_arms: Vec<TokenStream> = nc.nested_clients.iter().map(|inner_nc| {
2497        let variant_pascal = format_ident!("{}", to_pascal_case(&inner_nc.factory_name));
2498        let nested_dispatch_fn = format_ident!("dispatch_{}", to_snake_case(&inner_nc.factory_name));
2499        // Pass all ancestor scope args + nc's own scope args
2500        quote! {
2501            #tag_enum::#variant_pascal => {
2502                return #nested_dispatch_fn(handler, ctx, request_id, #(#parent_scope_args,)* #(#nested_scope_args,)* body).await;
2503            }
2504        }
2505    }).collect();
2506
2507    quote! {
2508        use #tag_enum::*;
2509        let result = match variant_tag {
2510            #(#dispatch_arms)*
2511            #(#nested_dispatch_arms)*
2512        };
2513
2514        Ok((#serializer_fn(request_id, &result)?, None))
2515    }
2516}
2517#[cfg(test)]
2518#[allow(clippy::expect_used)]
2519mod browser_method_dispatch_tests {
2520    use super::generate_dispatch_fn;
2521    use crate::resolve::ResolvedSchema;
2522    use crate::schema::types::{ParsedSchema, UnionVariant};
2523
2524    fn variant(name: &str) -> UnionVariant {
2525        UnionVariant {
2526            name: name.to_owned(),
2527            type_name: "Void".to_owned(),
2528            description: String::new(),
2529            scope: "query".to_owned(),
2530            scope_exempt: false,
2531            cli_hidden: false,
2532            doc_example: String::new(),
2533            vfs_path: String::new(),
2534            vfs_kind: String::new(),
2535            vfs_bulk: false,
2536            vfs_hidden: false,
2537            vfs_mac: String::new(),
2538            dispatch_mac: String::new(),
2539            dispatch_public: String::new(),
2540            mutation_semantics: String::new(),
2541            dispatch_mac_present: false,
2542            dispatch_public_present: false,
2543            mutation_semantics_present: false,
2544        }
2545    }
2546
2547    #[test]
2548    fn generated_dispatch_independently_checks_decoded_method_before_handler() {
2549        let schema = ParsedSchema {
2550            request_variants: vec![variant("status"), variant("load")],
2551            response_variants: vec![],
2552            structs: vec![],
2553            scoped_clients: vec![],
2554            enums: vec![],
2555            request_struct: None,
2556            response_struct: None,
2557        };
2558        let resolved = ResolvedSchema::from(&schema);
2559        let generated = generate_dispatch_fn(
2560            "Model",
2561            &syn::parse_quote!(model_capnp),
2562            &schema.request_variants,
2563            &[],
2564            &[],
2565            &resolved,
2566            false,
2567        )
2568        .to_string();
2569
2570        let decode = generated
2571            .find("match req . which")
2572            .expect("generated dispatch must independently decode the request union");
2573        let compare = generated
2574            .find("ctx . ensure_browser_method")
2575            .expect("generated dispatch must compare the sealed browser commitment");
2576        let handler = generated
2577            .find("handler . handle_status")
2578            .expect("fixture must contain an application handler call");
2579        assert!(decode < compare, "method must be decoded before comparison");
2580        assert!(
2581            compare < handler,
2582            "mismatch must reject before the application handler"
2583        );
2584        assert!(
2585            generated.contains("Status (_) => 0u16") && generated.contains("Load (_) => 1u16"),
2586            "generated comparison must use schema union discriminators: {generated}"
2587        );
2588    }
2589}