feat(gateway): FeatureSetResolver v2 + SessionRootsRegistry (shadow mode)

Introduces the runtime surface for the FeatureSet resolver v2.
Decisions are computed and logged on every initialize but NOT yet
enforced — the existing AuthorizationService::get_client_grants path
remains authoritative until a follow-up commit flips the switch.

New services:
  * SessionRootsRegistry  — DashMap keyed by mcp-session-id, stores
    already-normalized workspace roots reported by the peer.
  * FeatureSetResolverService — resolves one of:
        Pin              (client.pinned_feature_set_id)
        WorkspaceBinding (longest-prefix match against session roots)
        SpaceActive      (space.active_feature_set_id fallback)
        Deny             (no pin / no binding / no active FS)

Gateway wiring:
  * GatewayDependencies gains inbound_mcp_client_repo +
    workspace_binding_repo, both wired to the SQLite repos so no DI
    boilerplate is required at call sites.
  * ServiceContainer exposes feature_set_resolver + session_roots.
  * McpMuxGatewayHandler::on_initialized now:
      - when the peer declared `roots` capability, spawns a task to call
        peer.list_roots(), normalizes + stores the URIs in the registry,
        then emits a shadow-mode log of the resolver's decision.
      - when no roots are declared, resolves immediately against
        pin / space-active so the shadow log still fires.
    Peer is cloned via Arc so notifications continue to be delivered.

Normalization fix: normalize_workspace_root("") now returns "" so
SessionRootsRegistry::set can filter out empty inputs without needing
to know the target OS's root sentinel.

Shadow-mode log format (grep-friendly):
  [FeatureSetResolver][shadow] resolved
      client_id=… session_id=… feature_set_id=… source={Pin|WorkspaceBinding|SpaceActive|Deny}

Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>

Author: its-mash

crates/mcpmux-core/src/domain/workspace_binding.rs

@@ -63,6 +63,12 @@ impl WorkspaceBinding {
 /// This is the single source of truth for path comparisons — always route
 /// through here before calling any repository method that takes `workspace_root`.
 pub fn normalize_workspace_root(input: &str) -> String {
+    // Empty in → empty out: callers filter on this to drop garbage roots
+    // without needing to know about "/" vs "\" filesystem conventions.
+    if input.is_empty() {
+        return String::new();
+    }
+
     // Strip file:// scheme if present; tolerate both "file:///abs/path" and
     // "file://host/abs/path" (we don't use host, it's always localhost).
     let without_scheme = if let Some(rest) = input.strip_prefix("file://") {

crates/mcpmux-gateway/src/mcp/handler.rs

@@ -12,7 +12,7 @@ use rmcp::{
 use std::sync::Arc;
 use tracing::{debug, info, warn};
 
-use super::context::{extract_oauth_context, OAuthContext};
+use super::context::{extract_oauth_context, extract_session_id, OAuthContext};
 use crate::consumers::MCPNotifier;
 use crate::server::ServiceContainer;
 
@@ -81,6 +81,36 @@ impl McpMuxGatewayHandler {
         }
     }
 
+    /// Shadow-mode log for the new FeatureSet resolver.
+    ///
+    /// Does not affect routing; prints the resolver's decision so operators
+    /// can compare against the legacy `get_client_grants` path before we
+    /// flip the switch.
+    async fn shadow_log_resolution(
+        resolver: &crate::services::FeatureSetResolverService,
+        client_id: &uuid::Uuid,
+        session_id: Option<&str>,
+    ) {
+        match resolver.resolve(client_id, session_id).await {
+            Ok(resolved) => {
+                info!(
+                    %client_id,
+                    session_id = session_id.unwrap_or("<none>"),
+                    feature_set_id = resolved.feature_set_id.map(|u| u.to_string()).unwrap_or_else(|| "<deny>".into()),
+                    source = ?resolved.source,
+                    "[FeatureSetResolver][shadow] resolved",
+                );
+            }
+            Err(e) => {
+                warn!(
+                    %client_id,
+                    error = %e,
+                    "[FeatureSetResolver][shadow] resolve failed",
+                );
+            }
+        }
+    }
+
     /// Build InitializeResult with negotiated protocol version
     fn build_initialize_result(&self, protocol_version: ProtocolVersion) -> InitializeResult {
         let info = self.get_info();
@@ -158,7 +188,7 @@ impl ServerHandler for McpMuxGatewayHandler {
         // Register peer with MCPNotifier for list_changed notification delivery
         let peer = std::sync::Arc::new(context.peer);
         self.notification_bridge
-            .register_peer(oauth_ctx.client_id.clone(), peer);
+            .register_peer(oauth_ctx.client_id.clone(), peer.clone());
 
         // Mark the client stream as active immediately - RMCP's session transport
         // handles SSE streaming and message caching internally
@@ -170,6 +200,64 @@ impl ServerHandler for McpMuxGatewayHandler {
             .prime_hashes_for_space(oauth_ctx.space_id)
             .await;
 
+        // Resolver v2 (shadow mode): if the peer advertised the `roots`
+        // capability, fetch its reported workspace roots and stash them in the
+        // session registry. We then run the resolver and log its decision —
+        // the legacy grants path is still authoritative for routing.
+        if let Some(session_id) = extract_session_id(&context.extensions) {
+            let declares_roots = peer
+                .peer_info()
+                .map(|info| info.capabilities.roots.is_some())
+                .unwrap_or(false);
+            if declares_roots {
+                let peer_for_roots = peer.clone();
+                let session_roots = self.services.session_roots.clone();
+                let resolver = self.services.feature_set_resolver.clone();
+                let client_id_str = oauth_ctx.client_id.clone();
+                let session_id_for_task = session_id.clone();
+                tokio::spawn(async move {
+                    match peer_for_roots.list_roots().await {
+                        Ok(result) => {
+                            let uris: Vec<String> =
+                                result.roots.iter().map(|r| r.uri.to_string()).collect();
+                            session_roots
+                                .set(&session_id_for_task, uris.iter().map(|s| s.as_str()));
+                            debug!(
+                                client_id = %client_id_str,
+                                session_id = %session_id_for_task,
+                                roots = ?uris,
+                                "[FeatureSetResolver] fetched MCP roots",
+                            );
+                            if let Ok(client_uuid) = uuid::Uuid::parse_str(&client_id_str) {
+                                Self::shadow_log_resolution(
+                                    &resolver,
+                                    &client_uuid,
+                                    Some(&session_id_for_task),
+                                )
+                                .await;
+                            }
+                        }
+                        Err(e) => {
+                            debug!(
+                                client_id = %client_id_str,
+                                session_id = %session_id_for_task,
+                                error = %e,
+                                "[FeatureSetResolver] peer.list_roots() failed — falling back to Space active FS",
+                            );
+                        }
+                    }
+                });
+            } else if let Ok(client_uuid) = uuid::Uuid::parse_str(&oauth_ctx.client_id) {
+                // No roots declared — resolve immediately against pin / space active FS.
+                Self::shadow_log_resolution(
+                    &self.services.feature_set_resolver,
+                    &client_uuid,
+                    Some(&session_id),
+                )
+                .await;
+            }
+        }
+
         info!(
             client_id = %oauth_ctx.client_id,
             space_id = %oauth_ctx.space_id,

crates/mcpmux-gateway/src/server/dependencies.rs

@@ -9,8 +9,9 @@ use std::sync::Arc;
 use crate::services::ClientMetadataService;
 use mcpmux_core::{
     AppSettingsRepository, CimdMetadataFetcher, CredentialRepository, FeatureSetRepository,
-    InstalledServerRepository, OutboundOAuthRepository, ServerDiscoveryService,
-    ServerFeatureRepository, ServerLogManager, SpaceRepository,
+    InboundMcpClientRepository, InstalledServerRepository, OutboundOAuthRepository,
+    ServerDiscoveryService, ServerFeatureRepository, ServerLogManager, SpaceRepository,
+    WorkspaceBindingRepository,
 };
 use mcpmux_storage::{Database, InboundClientRepository};
 use tokio::sync::Mutex;
@@ -29,6 +30,13 @@ pub struct GatewayDependencies {
     pub feature_set_repo: Arc<dyn FeatureSetRepository>,
     pub space_repo: Arc<dyn SpaceRepository>,
     pub inbound_client_repo: Arc<InboundClientRepository>,
+    /// Trait-based MCP client repository (for Client entity CRUD + pin setters).
+    ///
+    /// Used by the FeatureSet resolver v2 — separate from `inbound_client_repo`
+    /// (which is the concrete OAuth-flow-focused repo).
+    pub inbound_mcp_client_repo: Arc<dyn InboundMcpClientRepository>,
+    /// Workspace -> FeatureSet bindings for resolver v2.
+    pub workspace_binding_repo: Arc<dyn WorkspaceBindingRepository>,
 
     // Services (Business Layer)
     pub server_discovery: Arc<ServerDiscoveryService>,
@@ -66,6 +74,15 @@ impl GatewayDependencies {
         jwt_secret: Option<zeroize::Zeroizing<[u8; mcpmux_storage::JWT_SECRET_SIZE]>>,
         state_dir: Option<PathBuf>,
     ) -> Self {
+        // Resolver v2 repositories — always SQLite-backed; no-op at runtime
+        // until the resolver flag flips out of shadow mode.
+        let inbound_mcp_client_repo: Arc<dyn InboundMcpClientRepository> = Arc::new(
+            mcpmux_storage::SqliteInboundMcpClientRepository::new(database.clone()),
+        );
+        let workspace_binding_repo: Arc<dyn WorkspaceBindingRepository> = Arc::new(
+            mcpmux_storage::SqliteWorkspaceBindingRepository::new(database.clone()),
+        );
+
         Self {
             installed_server_repo,
             credential_repo,
@@ -74,6 +91,8 @@ impl GatewayDependencies {
             feature_set_repo,
             space_repo,
             inbound_client_repo,
+            inbound_mcp_client_repo,
+            workspace_binding_repo,
             server_discovery,
             log_manager,
             cimd_fetcher,
@@ -214,6 +233,14 @@ impl DependenciesBuilder {
             ))
         });
 
+        // Resolver v2 repositories — always SQLite-backed for now.
+        let inbound_mcp_client_repo: Arc<dyn InboundMcpClientRepository> = Arc::new(
+            mcpmux_storage::SqliteInboundMcpClientRepository::new(database.clone()),
+        );
+        let workspace_binding_repo: Arc<dyn WorkspaceBindingRepository> = Arc::new(
+            mcpmux_storage::SqliteWorkspaceBindingRepository::new(database.clone()),
+        );
+
         Ok(GatewayDependencies {
             installed_server_repo: self
                 .installed_server_repo
@@ -228,6 +255,8 @@ impl DependenciesBuilder {
                 .ok_or("feature_set_repo is required")?,
             space_repo,
             inbound_client_repo,
+            inbound_mcp_client_repo,
+            workspace_binding_repo,
             server_discovery: self
                 .server_discovery
                 .ok_or("server_discovery is required")?,

crates/mcpmux-gateway/src/server/service_container.rs

@@ -7,8 +7,8 @@ use std::sync::Arc;
 
 use crate::pool::{PoolServices, ServerManager, ServiceFactory};
 use crate::services::{
-    AuthorizationService, ClientMetadataService, GrantService, PrefixCacheService,
-    SpaceResolverService,
+    AuthorizationService, ClientMetadataService, FeatureSetResolverService, GrantService,
+    PrefixCacheService, SessionRootsRegistry, SpaceResolverService,
 };
 use mcpmux_core::DomainEvent;
 
@@ -33,6 +33,15 @@ pub struct ServiceContainer {
     /// Authorization service for checking client permissions (SRP)
     pub authorization_service: Arc<AuthorizationService>,
 
+    /// FeatureSet resolver v2 (pin > workspace > space-active).
+    ///
+    /// Runs in shadow mode alongside `authorization_service` — its decision
+    /// is logged on every request but not yet enforced.
+    pub feature_set_resolver: Arc<FeatureSetResolverService>,
+
+    /// Registry of per-session workspace roots (populated from MCP `roots/list`).
+    pub session_roots: Arc<SessionRootsRegistry>,
+
     /// Space resolver for determining client's active space (SRP)
     pub space_resolver_service: Arc<SpaceResolverService>,
 
@@ -91,6 +100,15 @@ impl ServiceContainer {
             deps.feature_set_repo.clone(),
         ));
 
+        // Resolver v2 — runs in shadow mode alongside AuthorizationService.
+        let session_roots = SessionRootsRegistry::new();
+        let feature_set_resolver = Arc::new(FeatureSetResolverService::new(
+            deps.inbound_mcp_client_repo.clone(),
+            deps.space_repo.clone(),
+            deps.workspace_binding_repo.clone(),
+            session_roots.clone(),
+        ));
+
         // Create space resolver service (DIP: inject repository dependencies)
         let space_resolver_service = Arc::new(SpaceResolverService::new(
             deps.inbound_client_repo.clone(),
@@ -113,6 +131,8 @@ impl ServiceContainer {
             server_manager,
             startup_orchestrator,
             authorization_service,
+            feature_set_resolver,
+            session_roots,
             space_resolver_service,
             prefix_cache_service,
             client_metadata_service,