refactor: rename handler chain terminology to connection builder

- Rename Conductor::into_handler_chain() to into_connection_builder()
- Rename JrConnectionBuilder::with_handler_chain() to with_connection_builder()
- Rename test file jsonrpc_handler_chain.rs to jsonrpc_connection_builder.rs
- Update docs and comments throughout to use 'connection builder' and
  'registered handlers' instead of 'handler chain'

Author: nikomatsakis

md/trace-viewer.md

@@ -226,7 +226,7 @@ sacp-conductor agent --trace ./trace.jsons "proxy1" "proxy2" "agent"
 ```rust
 Conductor::new(name, components, mcp_bridge_mode)
     .trace_to("./trace.jsons")
-    .into_handler_chain()
+    .into_connection_builder()
     // ...
 ```
 

md/transport-architecture.md

@@ -65,12 +65,12 @@ Responsibilities:
 #### Incoming Protocol Actor
 ```
 Input:  mpsc::UnboundedReceiver<jsonrpcmsg::Message>
-Output: Routes to reply_actor or handler chain
+Output: Routes to reply_actor or registered handlers
 ```
 
 Responsibilities:
 - Route responses to reply_actor (matches by ID)
-- Route requests/notifications to handler chain
+- Route requests/notifications to registered handlers
 - Convert `jsonrpcmsg::Request` to `UntypedMessage` for handlers
 
 #### Reply Actor
@@ -149,7 +149,7 @@ Transport Incoming Actor
     |
 Incoming Protocol Actor
     | - Route responses → reply_actor
-    | - Route requests → handler chain
+    | - Route requests → registered handlers
     v
 Handler or Reply Actor
 ```
@@ -269,7 +269,7 @@ Benefits:
 The refactored API separates handler setup from transport selection:
 
 ```rust
-// Build handler chain
+// Build connection with handlers
 let connection = JrConnection::new()
     .name("my-component")
     .on_receive_request(|req: InitializeRequest, cx| {

skills/sacp-v2-migration/skill.md

@@ -1,6 +1,6 @@
 ---
 name: sacp-v2-migration
-description: Migrate Rust code from sacp v1.x to v2.0 role-based API. Use when upgrading sacp dependencies, fixing JrHandlerChain errors, or when code references MessageAndCx or old connection patterns.
+description: Migrate Rust code from sacp v1.x to v2.0 role-based API. Use when upgrading sacp dependencies, fixing JrConnectionBuilder errors, or when code references MessageAndCx or old connection patterns.
 ---
 
 # SACP v2 Migration
@@ -9,7 +9,7 @@ description: Migrate Rust code from sacp v1.x to v2.0 role-based API. Use when u
 
 Apply these transformations when migrating from sacp v1.x to v2.0:
 
-### 1. Replace JrHandlerChain with role builder
+### 1. Replace JrHandlerChain with role-based connection builder
 
 ```rust
 // Before

src/sacp-conductor/src/conductor.rs

@@ -191,7 +191,7 @@ impl Conductor {
         self
     }
 
-    pub fn into_handler_chain(self) -> JrConnectionBuilder<ConductorMessageHandler> {
+    pub fn into_connection_builder(self) -> JrConnectionBuilder<ConductorMessageHandler> {
         let (mut conductor_tx, mut conductor_rx) = mpsc::channel(128 /* chosen arbitrarily */);
 
         let mut state = ConductorHandlerState {
@@ -228,13 +228,13 @@ impl Conductor {
     ///
     /// This is equivalent to:
     /// ```ignore
-    /// conductor.into_handler_chain()
+    /// conductor.into_connection_builder()
     ///     .connect_to(transport)
     ///     .serve()
     ///     .await
     /// ```
     pub async fn run(self, transport: impl Component + 'static) -> Result<(), sacp::Error> {
-        self.into_handler_chain()
+        self.into_connection_builder()
             .connect_to(transport)?
             .serve()
             .await

src/sacp-conductor/src/lib.rs

@@ -288,7 +288,7 @@ impl ConductorArgs {
                 }
 
                 conductor
-                    .into_handler_chain()
+                    .into_connection_builder()
                     .connect_to(stdio)?
                     .serve()
                     .await

src/sacp-tee/src/lib.rs

@@ -205,7 +205,7 @@ impl Component for Tee {
             }
         });
 
-        // Create the handler chain
+        // Create the connection
         ProxyToConductor::builder()
             .name("sacp-tee")
             .with_handler(TeeHandler::new(log_tx))

src/sacp/src/component.rs

@@ -66,7 +66,7 @@ use crate::Channel;
 ///
 /// impl Component for MyProxy {
 ///     async fn serve(self, client: impl Component) -> Result<(), sacp::Error> {
-///         // Set up handler chain that forwards to client
+///         // Set up connection that forwards to client
 ///         sacp::UntypedRole::builder()
 ///             .name("my-proxy")
 ///             .on_receive_request(async |req: MyRequest, cx| {
@@ -97,7 +97,7 @@ use crate::Channel;
 pub trait Component: Send + 'static {
     /// Serve this component by forwarding to a client component.
     ///
-    /// Most components implement this method to set up their handler chain and
+    /// Most components implement this method to set up their connection and
     /// forward messages to the provided client.
     ///
     /// # Arguments

src/sacp/src/jsonrpc.rs

@@ -189,7 +189,7 @@ pub trait JrMessageHandler {
         cx: JrConnectionCx<Self::Role>,
     ) -> Result<Handled<MessageCx>, crate::Error>;
 
-    /// Returns a debug description of the handler chain for diagnostics
+    /// Returns a debug description of the registered handlers for diagnostics.
     fn describe_chain(&self) -> impl std::fmt::Debug;
 }
 
@@ -213,7 +213,7 @@ pub trait JrMessageHandlerSend: Send {
         cx: JrConnectionCx<Self::Role>,
     ) -> impl Future<Output = Result<Handled<MessageCx>, crate::Error>> + Send;
 
-    /// Describe this handler chain.
+    /// Returns a debug description of the registered handlers for diagnostics.
     fn describe_chain(&self) -> impl std::fmt::Debug;
 }
 
@@ -554,7 +554,7 @@ impl<Role: JrRole> JrConnectionBuilder<NullHandler<Role>> {
 }
 
 impl<H: JrMessageHandler> JrConnectionBuilder<H> {
-    /// Create a new handler chain with the given handler and roles.
+    /// Create a new connection builder with the given handler.
     pub fn new_with(handler: H) -> Self {
         Self {
             name: Default::default(),
@@ -573,29 +573,29 @@ impl<H: JrMessageHandler> JrConnectionBuilder<H> {
 
     /// Returns a reference to the remote role.
 
-    /// Add a new [`JrMessageHandler`] to the chain.
+    /// Merge another [`JrConnectionBuilder`] into this one.
     ///
     /// Prefer [`Self::on_receive_request`] or [`Self::on_receive_notification`].
     /// This is a low-level method that is not intended for general use.
-    pub fn with_handler_chain<H1>(
+    pub fn with_connection_builder<H1>(
         mut self,
-        handler_chain: JrConnectionBuilder<H1>,
+        other: JrConnectionBuilder<H1>,
     ) -> JrConnectionBuilder<ChainedHandler<H, NamedHandler<H1>>>
     where
         H1: JrMessageHandler<Role = H::Role>,
     {
         self.pending_tasks.extend(
-            handler_chain
+            other
                 .pending_tasks
                 .into_iter()
-                .map(|t| t.named(handler_chain.name.clone())),
+                .map(|t| t.named(other.name.clone())),
         );
 
         JrConnectionBuilder {
             name: self.name,
             handler: ChainedHandler::new(
                 self.handler,
-                NamedHandler::new(handler_chain.name, handler_chain.handler),
+                NamedHandler::new(other.name, other.handler),
             ),
             pending_tasks: self.pending_tasks,
         }
@@ -968,10 +968,10 @@ impl<H: JrMessageHandler> JrConnectionBuilder<H> {
         })
     }
 
-    /// Apply the handler chain to a single message.
+    /// Apply the registered handlers to a single message.
     ///
-    /// This method processes one message through the entire handler chain, attempting to
-    /// match it against each registered handler in order. This is useful when implementing
+    /// This method processes one message through all registered handlers, attempting to
+    /// match it against each handler in order. This is useful when implementing
     /// custom message handling logic or when you need fine-grained control over message
     /// processing.
     ///
@@ -992,7 +992,7 @@ impl<H: JrMessageHandler> JrConnectionBuilder<H> {
     ///
     /// # Example: Borrow Checker Challenges
     ///
-    /// When building a handler chain with `async {}` blocks (non-move), you might encounter
+    /// When building a connection with `async {}` blocks (non-move), you might encounter
     /// borrow checker errors if multiple handlers need access to the same mutable state:
     ///
     /// ```compile_fail
@@ -1333,7 +1333,7 @@ pub enum Handled<T> {
 /// Trait for converting handler return values into [`Handled`].
 ///
 /// This trait allows handlers to return either `()` (which becomes `Handled::Yes`)
-/// or an explicit `Handled<T>` value for more control over handler chain propagation.
+/// or an explicit `Handled<T>` value for more control over handler propagation.
 pub trait IntoHandled<T> {
     /// Convert this value into a `Handled<T>`.
     fn into_handled(self) -> Handled<T>;
@@ -1718,7 +1718,7 @@ impl<Role: JrRole> JrConnectionCx<Role> {
     ///
     /// Dynamic message handlers are called first for every incoming message.
     ///
-    /// If they decline to handle the message, then the message is passed to the regular handler chain.
+    /// If they decline to handle the message, then the message is passed to the regular registered handlers.
     ///
     /// The handler will stay registered until the [`DynamicHandlerRegistration`] is dropped.
     pub fn add_dynamic_handler(
@@ -2858,7 +2858,7 @@ where
 ///     tokio::io::stdin().compat(),
 /// );
 ///
-/// // Use as a component in a handler chain
+/// // Use as a component in a connection
 /// sacp::role::UntypedRole::builder()
 ///     .name("my-client")
 ///     .serve(component)

src/sacp/src/jsonrpc/incoming_actor.rs

@@ -21,7 +21,7 @@ use super::Handled;
 ///
 /// This actor handles JSON-RPC protocol semantics:
 /// - Routes responses to reply_actor (for request/response correlation)
-/// - Routes requests/notifications to handler chain
+/// - Routes requests/notifications to registered handlers
 /// - Converts jsonrpcmsg::Request to UntypedMessage for handlers
 ///
 /// This is the protocol layer - it has no knowledge of how messages arrived.

src/sacp/src/mcp_server/mod.rs

@@ -17,7 +17,7 @@
 //! let registry = McpServiceRegistry::new()
 //!     .with_mcp_server("my-server", server)?;
 //!
-//! // Use the registry in your handler chain
+//! // Use the registry in your connection
 //! UntypedRole::builder()
 //!     .with_handler(registry)
 //!     .serve(connection)