feat(call): introduce StreamingHandler, HandlerKind, ResponseStream + INVALID_OPERATION_TYPE (ADR-049)

Add the foundational types for ADR-049 streaming handlers:
- StreamingHandler, ResponseStream type aliases and HandlerKind enum
  (Once | Stream) in registration.rs, with make_streaming_handler() helper
- CallError::invalid_operation_type() in wire.rs (sixth protocol code,
  retryable: false)
- HandlerRegistration.handler flipped from Handler to HandlerKind;
  HandlerRegistration::new() now takes HandlerKind
- OperationRegistryBuilder absorbs wrapping: with_local/with_leaf/
  with_leaf_provenance wrap raw Handler in HandlerKind::Once for
  Query/Mutation; new with_local_streaming/with_leaf_streaming take a
  StreamingHandler and wrap in HandlerKind::Stream for Subscription.
  Builder validates kind matches spec.op_type (mismatch = startup error)
- OperationRegistry::register() returns Result<(), String> with a clear
  mismatch message; all call sites updated to handle the Result
- invoke() matches on HandlerKind: Once -> existing path; Stream ->
  INVALID_OPERATION_TYPE error envelope (guards against silent
  truncation; invoke_streaming() added in a downstream task)
- OverlayOperationEnv::invoke_with_policy matches on HandlerKind:
  Once -> dispatch; Stream -> INVALID_OPERATION_TYPE (composition is
  request/response-only)
- Migrated every HandlerRegistration::new() construction site (~95)
  to wrap raw Handler in HandlerKind::Once(handler); the builder sites
  are handled by the builder-absorbs-wrapping change
- Updated two websocket subscription tests that relied on Subscription
  ops dispatching via invoke() to expect INVALID_OPERATION_TYPE
- Added unit tests for invoke/register validation and
  make_streaming_handler

crates/alknet-call/src/protocol/adapter.rs

@@ -166,7 +166,9 @@ mod tests {
     };
     use crate::registry::context::{AbortPolicy, OperationContext, ScopedPeerEnv};
     use crate::registry::env::OperationEnv;
-    use crate::registry::registration::{make_handler, HandlerRegistration, OperationProvenance};
+    use crate::registry::registration::{
+        make_handler, HandlerKind, HandlerRegistration, OperationProvenance,
+    };
     use crate::registry::spec::{AccessControl, OperationSpec, OperationType, Visibility};
     use alknet_core::auth::AuthToken;
     use alknet_core::types::Capabilities;
@@ -245,22 +247,24 @@ mod tests {
         handler: crate::registry::registration::Handler,
     ) -> Arc<OperationRegistry> {
         let mut registry = OperationRegistry::new();
-        registry.register(HandlerRegistration::new(
-            OperationSpec::new(
-                name,
-                OperationType::Query,
-                visibility,
-                serde_json::json!({}),
-                serde_json::json!({}),
-                vec![],
-                acl,
-            ),
-            handler,
-            OperationProvenance::Local,
-            None,
-            None,
-            Capabilities::new(),
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                OperationSpec::new(
+                    name,
+                    OperationType::Query,
+                    visibility,
+                    serde_json::json!({}),
+                    serde_json::json!({}),
+                    vec![],
+                    acl,
+                ),
+                HandlerKind::Once(handler),
+                OperationProvenance::Local,
+                None,
+                None,
+                Capabilities::new(),
+            ))
+            .unwrap();
         Arc::new(registry)
     }
 
@@ -421,14 +425,16 @@ mod tests {
         let mut registry = OperationRegistry::new();
         let scoped = ScopedPeerEnv::new(["fs/readFile"]);
         let caps = Capabilities::new().with_api_key("google", "k".to_string());
-        registry.register(HandlerRegistration::new(
-            external_spec("agent/run", AccessControl::default()),
-            echo_handler(),
-            OperationProvenance::Local,
-            None,
-            Some(scoped.clone()),
-            caps.clone(),
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                external_spec("agent/run", AccessControl::default()),
+                HandlerKind::Once(echo_handler()),
+                OperationProvenance::Local,
+                None,
+                Some(scoped.clone()),
+                caps.clone(),
+            ))
+            .unwrap();
         let registry = Arc::new(registry);
         let provider: Arc<dyn IdentityProvider> = Arc::new(StaticIdentityProvider::new());
         let adapter = CallAdapter::new(registry, provider);
@@ -543,7 +549,7 @@ mod tests {
                 vec![],
                 AccessControl::default(),
             ),
-            echo_handler(),
+            HandlerKind::Once(echo_handler()),
             OperationProvenance::FromCall,
             None,
             None,
@@ -610,7 +616,7 @@ mod tests {
                 vec![],
                 AccessControl::default(),
             ),
-            echo_handler(),
+            HandlerKind::Once(echo_handler()),
             OperationProvenance::FromCall,
             None,
             None,

crates/alknet-call/src/protocol/connection.rs

@@ -26,7 +26,7 @@ use super::wire::{
 use crate::protocol::wire::ResponseEnvelope;
 use crate::registry::context::{generate_request_id, AbortPolicy, OperationContext, ScopedPeerEnv};
 use crate::registry::env::OperationEnv;
-use crate::registry::registration::{Handler, HandlerRegistration};
+use crate::registry::registration::{HandlerKind, HandlerRegistration};
 use crate::registry::spec::AccessResult;
 
 const DEFAULT_CALL_TIMEOUT: Duration = Duration::from_secs(30);
@@ -307,7 +307,7 @@ impl OperationEnv for OverlayOperationEnv {
             return ResponseEnvelope::not_found(parent.request_id.clone(), &name);
         }
 
-        let handler: Handler;
+        let handler: HandlerKind;
         let composition_authority;
         let scoped_env;
         let access_control;
@@ -316,7 +316,7 @@ impl OperationEnv for OverlayOperationEnv {
             let Some(registration) = overlay.get(&name) else {
                 return ResponseEnvelope::not_found(parent.request_id.clone(), &name);
             };
-            handler = Arc::clone(&registration.handler);
+            handler = registration.handler.clone();
             composition_authority = registration.composition_authority.clone();
             scoped_env = registration
                 .scoped_env
@@ -355,7 +355,15 @@ impl OperationEnv for OverlayOperationEnv {
             internal: true,
         };
 
-        handler(input, context).await
+        match handler {
+            HandlerKind::Once(h) => h(input, context).await,
+            HandlerKind::Stream(_) => ResponseEnvelope::error(
+                parent.request_id.clone(),
+                CallError::invalid_operation_type(
+                    "OperationEnv::invoke() called on a Subscription op; composition is request/response-only",
+                ),
+            ),
+        }
     }
 
     fn contains(&self, name: &str) -> bool {
@@ -421,7 +429,7 @@ impl Stream for SubscriptionStream {
 mod tests {
     use super::*;
     use crate::registry::context::CompositionAuthority;
-    use crate::registry::registration::{make_handler, OperationProvenance};
+    use crate::registry::registration::{make_handler, Handler, HandlerKind, OperationProvenance};
     use crate::registry::spec::{AccessControl, OperationSpec, OperationType, Visibility};
     use alknet_core::types::{Capabilities, MockConnection};
     use std::collections::HashMap;
@@ -476,7 +484,7 @@ mod tests {
     fn imported_registration(name: &str) -> HandlerRegistration {
         HandlerRegistration::new(
             external_spec(name),
-            echo_handler(),
+            HandlerKind::Once(echo_handler()),
             OperationProvenance::FromCall,
             None,
             None,
@@ -608,7 +616,7 @@ mod tests {
         });
         conn.register_imported(HandlerRegistration::new(
             external_spec("worker/exec"),
-            inspect_handler,
+            HandlerKind::Once(inspect_handler),
             OperationProvenance::FromCall,
             None,
             None,
@@ -631,7 +639,9 @@ mod tests {
     fn connection_accessor_returns_underlying_connection() {
         let conn = CallConnection::new(stub_connection());
         assert_eq!(
-            conn.connection().expect("quic connection present").remote_alpn(),
+            conn.connection()
+                .expect("quic connection present")
+                .remote_alpn(),
             b"alknet/call"
         );
     }
@@ -960,4 +970,39 @@ mod tests {
         assert!(conn.connection().is_some(), "QUIC connection present");
         assert!(conn.identity().is_none(), "no identity set yet");
     }
+
+    #[tokio::test]
+    async fn overlay_env_invoke_on_stream_kind_returns_invalid_operation_type() {
+        use crate::registry::registration::make_streaming_handler;
+        let conn = CallConnection::new(stub_connection());
+        let streaming_handler = make_streaming_handler(|input, ctx| {
+            futures::stream::iter(vec![ResponseEnvelope::ok(ctx.request_id, input)])
+        });
+        conn.register_imported(HandlerRegistration::new(
+            OperationSpec::new(
+                "events/stream",
+                OperationType::Subscription,
+                Visibility::External,
+                serde_json::json!({}),
+                serde_json::json!({}),
+                vec![],
+                AccessControl::default(),
+            ),
+            HandlerKind::Stream(streaming_handler),
+            OperationProvenance::FromCall,
+            None,
+            None,
+            Capabilities::new(),
+        ));
+        let env = conn.overlay_env();
+        let scoped = ScopedPeerEnv::new(["events/stream"]);
+        let ctx = root_context("root-stream", scoped, env.clone());
+        let response = env
+            .invoke("events", "stream", serde_json::json!({}), &ctx)
+            .await;
+        match response.result {
+            Err(e) => assert_eq!(e.code, "INVALID_OPERATION_TYPE"),
+            other => panic!("expected INVALID_OPERATION_TYPE, got {other:?}"),
+        }
+    }
 }

crates/alknet-call/src/protocol/dispatch.rs

@@ -326,7 +326,9 @@ impl Clone for Dispatcher {
 mod tests {
     use super::*;
     use crate::protocol::wire::EVENT_RESPONDED;
-    use crate::registry::registration::{make_handler, HandlerRegistration, OperationProvenance};
+    use crate::registry::registration::{
+        make_handler, HandlerKind, HandlerRegistration, OperationProvenance,
+    };
     use crate::registry::spec::{AccessControl, OperationSpec, OperationType, Visibility};
     use alknet_core::auth::{AuthToken, Identity, IdentityProvider};
     use alknet_core::types::{Capabilities, MockConnection};
@@ -412,24 +414,26 @@ mod tests {
 
     fn registry_with(name: &str, visibility: Visibility, acl: AccessControl) -> OperationRegistry {
         let mut registry = OperationRegistry::new();
-        registry.register(HandlerRegistration::new(
-            OperationSpec::new(
-                name,
-                OperationType::Query,
-                visibility,
-                serde_json::json!({}),
-                serde_json::json!({}),
-                vec![],
-                acl,
-            ),
-            make_handler(|input, context| async move {
-                ResponseEnvelope::ok(context.request_id, input)
-            }),
-            OperationProvenance::Local,
-            None,
-            None,
-            Capabilities::new(),
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                OperationSpec::new(
+                    name,
+                    OperationType::Query,
+                    visibility,
+                    serde_json::json!({}),
+                    serde_json::json!({}),
+                    vec![],
+                    acl,
+                ),
+                HandlerKind::Once(make_handler(|input, context| async move {
+                    ResponseEnvelope::ok(context.request_id, input)
+                })),
+                OperationProvenance::Local,
+                None,
+                None,
+                Capabilities::new(),
+            ))
+            .unwrap();
         registry
     }
 
@@ -451,14 +455,16 @@ mod tests {
                 serde_json::json!({ "has_google": has_google }),
             )
         });
-        registry.register(HandlerRegistration::new(
-            external_spec("admin/run", AccessControl::default()),
-            handler,
-            OperationProvenance::Local,
-            None,
-            None,
-            caps,
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                external_spec("admin/run", AccessControl::default()),
+                HandlerKind::Once(handler),
+                OperationProvenance::Local,
+                None,
+                None,
+                caps,
+            ))
+            .unwrap();
         let registry = Arc::new(registry);
         let provider: Arc<dyn IdentityProvider> = Arc::new(StaticIdentityProvider::new());
         let dp = Dispatcher::new(registry, provider);
@@ -486,20 +492,22 @@ mod tests {
                 serde_json::json!({ "has_google": has_google }),
             )
         });
-        registry.register(HandlerRegistration::new(
-            external_spec(
-                "admin/run",
-                AccessControl {
-                    required_scopes: vec!["admin".to_string()],
-                    ..Default::default()
-                },
-            ),
-            handler,
-            OperationProvenance::Local,
-            None,
-            None,
-            caps,
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                external_spec(
+                    "admin/run",
+                    AccessControl {
+                        required_scopes: vec!["admin".to_string()],
+                        ..Default::default()
+                    },
+                ),
+                HandlerKind::Once(handler),
+                OperationProvenance::Local,
+                None,
+                None,
+                caps,
+            ))
+            .unwrap();
         let registry = Arc::new(registry);
         let provider: Arc<dyn IdentityProvider> = Arc::new(
             StaticIdentityProvider::new()
@@ -609,14 +617,16 @@ mod tests {
                 serde_json::json!({ "forwarded_for_id": forwarded_id }),
             )
         });
-        registry.register(HandlerRegistration::new(
-            external_spec("fs/readFile", AccessControl::default()),
-            handler,
-            OperationProvenance::Local,
-            None,
-            None,
-            Capabilities::new(),
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                external_spec("fs/readFile", AccessControl::default()),
+                HandlerKind::Once(handler),
+                OperationProvenance::Local,
+                None,
+                None,
+                Capabilities::new(),
+            ))
+            .unwrap();
         let registry = Arc::new(registry);
         let provider: Arc<dyn IdentityProvider> = Arc::new(StaticIdentityProvider::new());
         let dp = Dispatcher::new(registry, provider);
@@ -648,14 +658,16 @@ mod tests {
                 serde_json::json!({ "present": present }),
             )
         });
-        registry.register(HandlerRegistration::new(
-            external_spec("fs/readFile", AccessControl::default()),
-            handler,
-            OperationProvenance::Local,
-            None,
-            None,
-            Capabilities::new(),
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                external_spec("fs/readFile", AccessControl::default()),
+                HandlerKind::Once(handler),
+                OperationProvenance::Local,
+                None,
+                None,
+                Capabilities::new(),
+            ))
+            .unwrap();
         let registry = Arc::new(registry);
         let provider: Arc<dyn IdentityProvider> = Arc::new(StaticIdentityProvider::new());
         let dp = Dispatcher::new(registry, provider);
@@ -736,14 +748,16 @@ mod tests {
                 serde_json::json!({ "peer_ids": peer_ids }),
             )
         });
-        registry.register(HandlerRegistration::new(
-            external_spec("fs/readFile", AccessControl::default()),
-            handler,
-            OperationProvenance::Local,
-            None,
-            None,
-            Capabilities::new(),
-        ));
+        registry
+            .register(HandlerRegistration::new(
+                external_spec("fs/readFile", AccessControl::default()),
+                HandlerKind::Once(handler),
+                OperationProvenance::Local,
+                None,
+                None,
+                Capabilities::new(),
+            ))
+            .unwrap();
         let registry = Arc::new(registry);
         let provider: Arc<dyn IdentityProvider> = Arc::new(StaticIdentityProvider::new());
         let dp = Dispatcher::new(registry, provider);
@@ -795,7 +809,11 @@ mod tests {
         let child_id = "ws-abort-child".to_string();
         {
             let mut pending = conn.pending().lock();
-            pending.register_call(parent_id.clone(), Instant::now() + Duration::from_secs(30), None);
+            pending.register_call(
+                parent_id.clone(),
+                Instant::now() + Duration::from_secs(30),
+                None,
+            );
             pending.register_call(
                 child_id.clone(),
                 Instant::now() + Duration::from_secs(30),
@@ -844,11 +862,16 @@ mod tests {
             "input": { "v": 42 },
         });
         let request_id = "ws-roundtrip-1".to_string();
-        let response = dp.dispatch_requested(&conn, request_id.clone(), payload).await;
+        let response = dp
+            .dispatch_requested(&conn, request_id.clone(), payload)
+            .await;
         assert!(response.result.is_ok());
         let envelope: EventEnvelope = response.into();
         assert_eq!(envelope.r#type, EVENT_RESPONDED);
         assert_eq!(envelope.id, "ws-roundtrip-1");
-        assert_eq!(envelope.payload.get("output"), Some(&serde_json::json!({ "v": 42 })));
+        assert_eq!(
+            envelope.payload.get("output"),
+            Some(&serde_json::json!({ "v": 42 }))
+        );
     }
 }

crates/alknet-call/src/protocol/wire.rs

@@ -105,6 +105,10 @@ impl CallError {
     pub fn timeout(message: impl Into<String>) -> Self {
         Self::new("TIMEOUT", message, true)
     }
+
+    pub fn invalid_operation_type(message: impl Into<String>) -> Self {
+        Self::new("INVALID_OPERATION_TYPE", message, false)
+    }
 }
 
 impl Eq for CallError {}