feat(core,storage): schema for FeatureSet resolver v2 (forward-compat)

Adds the storage surface for project-oriented FeatureSet selection. Behaviour
is unchanged at runtime; nothing reads the new columns yet. This lets later
commits plug in the resolver under a shadow-mode flag with zero risk to the
existing per-client grants path.

Migration 002 (forward-compatible additive only):
  * inbound_clients.pinned_feature_set_id   — chosen at approval time
  * inbound_clients.pinned_space_id          — backfilled from locked_space_id
  * spaces.active_feature_set_id             — backfilled from each space's
    existing Default FS so day-one resolver behaviour matches today
  * workspace_bindings table                 — (space_id, workspace_root) -> fs_id

Core:
  * Space.active_feature_set_id
  * Client.pinned_space_id + pinned_feature_set_id
  * new WorkspaceBinding entity + normalize_workspace_root +
    longest_prefix_match helpers (with Windows drive-letter folding,
    file:// scheme stripping, percent-decode, trailing-separator trim)
  * SpaceRepository::set_active_feature_set
  * InboundMcpClientRepository::set_pin
  * new WorkspaceBindingRepository trait (CRUD + find_longest_prefix_match)

Storage:
  * SqliteSpaceRepository + SqliteInboundMcpClientRepository round-trip
    the new columns
  * SqliteWorkspaceBindingRepository + test that longest-prefix matching
    picks the deepest binding when multiple candidates share prefixes

Old per-client grants (client_grants table, Client.grants field,
ConnectionMode enum, grant_feature_set/revoke_feature_set/etc.) remain
in place untouched — they'll be removed once the resolver flips out of
shadow mode.

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

Author: its-mash

Cargo.lock

@@ -51,9 +51,28 @@ pub struct Client {
     pub connection_mode: ConnectionMode,
 
     /// FeatureSet grants per Space: space_id -> [feature_set_ids]
+    ///
+    /// Legacy field — superseded by `pinned_feature_set_id` + WorkspaceBinding.
+    /// Kept while the FeatureSetResolver runs in shadow mode.
     #[serde(default)]
     pub grants: HashMap<Uuid, Vec<Uuid>>,
 
+    /// Space this access key belongs to (chosen at approval time).
+    ///
+    /// Replaces the `Locked` variant of `ConnectionMode`. `None` means
+    /// "follow the active Space" for legacy clients that haven't been
+    /// migrated yet; new approvals always populate this.
+    #[serde(default)]
+    pub pinned_space_id: Option<Uuid>,
+
+    /// FeatureSet this access key is pinned to (chosen at approval time).
+    ///
+    /// When `Some`, the resolver uses this FS directly. When `None`, the
+    /// resolver falls through to workspace-root binding and then the
+    /// Space's active FS.
+    #[serde(default)]
+    pub pinned_feature_set_id: Option<Uuid>,
+
     /// Access key for authentication (local only, never synced)
     #[serde(skip)]
     pub access_key: Option<String>,
@@ -78,6 +97,8 @@ impl Client {
             client_type: client_type.into(),
             connection_mode: ConnectionMode::default(),
             grants: HashMap::new(),
+            pinned_space_id: None,
+            pinned_feature_set_id: None,
             access_key: None,
             created_at: now,
             updated_at: now,

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

@@ -16,6 +16,7 @@ mod server;
 mod server_feature;
 mod server_log;
 mod space;
+mod workspace_binding;
 
 // Export event types first (ConnectionStatus is defined here)
 pub use event::{ConnectionStatus, DiscoveredCapabilities, DomainEvent, DomainEventEnvelope};
@@ -31,3 +32,4 @@ pub use server::*;
 pub use server_feature::*;
 pub use server_log::*;
 pub use space::*;
+pub use workspace_binding::{longest_prefix_match, normalize_workspace_root, WorkspaceBinding};

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

@@ -27,6 +27,13 @@ pub struct Space {
     /// Sort order for display
     pub sort_order: i32,
 
+    /// Active FeatureSet id — the default FS applied to every client in this
+    /// Space when neither an access-key pin nor a workspace-root binding matches.
+    ///
+    /// `None` means "deny by default" — routing returns an empty toolset.
+    #[serde(default)]
+    pub active_feature_set_id: Option<Uuid>,
+
     /// Creation timestamp
     pub created_at: DateTime<Utc>,
 
@@ -45,6 +52,7 @@ impl Space {
             description: None,
             is_default: false,
             sort_order: 0,
+            active_feature_set_id: None,
             created_at: now,
             updated_at: now,
         }

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

@@ -0,0 +1,226 @@
+//! WorkspaceBinding entity — maps a workspace root on disk to a FeatureSet.
+//!
+//! Bindings are the middle tier of FeatureSet resolution:
+//! pinned_feature_set_id (on Client) > WorkspaceBinding > Space.active_feature_set_id.
+//!
+//! When a connected client declares MCP `roots` capability, the gateway calls
+//! `roots/list` and matches each reported `file://` root against the bindings
+//! for the client's Space using longest-prefix-wins.
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+/// A binding between a normalized workspace root path and a FeatureSet.
+///
+/// Uniqueness is `(space_id, workspace_root)` — the same on-disk directory
+/// can bind different FeatureSets in different Spaces.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct WorkspaceBinding {
+    /// Unique identifier
+    pub id: Uuid,
+
+    /// Space this binding belongs to
+    pub space_id: Uuid,
+
+    /// Normalized absolute path.
+    ///
+    /// Normalization rules (applied before insert/compare):
+    ///   * resolve symlinks / junctions (`std::fs::canonicalize`)
+    ///   * Windows: lowercase drive letter, use backslashes
+    ///   * strip trailing path separator
+    ///   * drop the `file://` scheme if the caller provided a URI
+    pub workspace_root: String,
+
+    /// FeatureSet to apply when this binding matches
+    pub feature_set_id: Uuid,
+
+    /// Creation timestamp
+    pub created_at: DateTime<Utc>,
+
+    /// Last update timestamp
+    pub updated_at: DateTime<Utc>,
+}
+
+impl WorkspaceBinding {
+    /// Create a new binding. Caller is responsible for passing an already-normalized path.
+    pub fn new(space_id: Uuid, workspace_root: impl Into<String>, feature_set_id: Uuid) -> Self {
+        let now = Utc::now();
+        Self {
+            id: Uuid::new_v4(),
+            space_id,
+            workspace_root: workspace_root.into(),
+            feature_set_id,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+/// Normalize an absolute filesystem path or `file://` URI into the canonical
+/// form used for binding comparisons.
+///
+/// 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 {
+    // 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://") {
+        // A leading triple-slash (file:///abs) leaves us with "/abs".
+        // A double-slash host form (file://localhost/abs) leaves us with
+        // "localhost/abs" — drop the host component before the first slash.
+        match rest.find('/') {
+            Some(0) => rest.to_string(),
+            Some(n) => rest[n..].to_string(),
+            None => rest.to_string(),
+        }
+    } else {
+        input.to_string()
+    };
+
+    // URL-decode percent-escapes (e.g. %20 -> space) — MCP roots are URIs.
+    let decoded = urlencoding::decode(&without_scheme)
+        .map(|s| s.into_owned())
+        .unwrap_or(without_scheme);
+
+    // On Windows, "file:///D:/foo" decodes to "/D:/foo" — strip the leading
+    // slash so callers see "D:\foo"-style paths before case folding.
+    #[cfg(windows)]
+    let stripped = {
+        let trimmed = decoded
+            .strip_prefix('/')
+            .filter(|rest| {
+                let bytes = rest.as_bytes();
+                bytes.len() >= 2 && bytes[0].is_ascii_alphabetic() && bytes[1] == b':'
+            })
+            .unwrap_or(&decoded);
+        trimmed.replace('/', "\\")
+    };
+    #[cfg(not(windows))]
+    let stripped = decoded;
+
+    // Lowercase the drive letter on Windows so "D:\" and "d:\" compare equal.
+    #[cfg(windows)]
+    let cased = {
+        let mut chars: Vec<char> = stripped.chars().collect();
+        if chars.len() >= 2 && chars[0].is_ascii_alphabetic() && chars[1] == ':' {
+            chars[0] = chars[0].to_ascii_lowercase();
+        }
+        chars.into_iter().collect::<String>()
+    };
+    #[cfg(not(windows))]
+    let cased = stripped;
+
+    // Strip trailing path separators (but keep a root like "/" or "d:\").
+    let sep: &[char] = if cfg!(windows) { &['\\', '/'] } else { &['/'] };
+    let trimmed = cased.trim_end_matches(sep);
+
+    // Preserve root — if the trim removed everything, keep one separator.
+    if trimmed.is_empty() {
+        if cfg!(windows) {
+            "\\".to_string()
+        } else {
+            "/".to_string()
+        }
+    } else if cfg!(windows) && trimmed.ends_with(':') {
+        // "d:" → "d:\"
+        format!("{}\\", trimmed)
+    } else {
+        trimmed.to_string()
+    }
+}
+
+/// Returns the `workspace_root` in `candidates` whose path is the longest
+/// prefix of `query`. Used by the resolver to pick which binding wins when
+/// a client reports multiple roots.
+///
+/// Both `query` and every candidate MUST be already normalized via
+/// [`normalize_workspace_root`] — this function does not re-normalize.
+pub fn longest_prefix_match<'a, I>(query: &str, candidates: I) -> Option<&'a str>
+where
+    I: IntoIterator<Item = &'a str>,
+{
+    let mut best: Option<&'a str> = None;
+    for candidate in candidates {
+        // Match only at a path-component boundary so "/workspaces/foo" does
+        // not match a binding for "/workspaces/foo-bar".
+        let matches = query == candidate
+            || (query.starts_with(candidate)
+                && query
+                    .as_bytes()
+                    .get(candidate.len())
+                    .is_some_and(|b| *b == b'/' || (cfg!(windows) && *b == b'\\')));
+        if matches && best.map(|b| candidate.len() > b.len()).unwrap_or(true) {
+            best = Some(candidate);
+        }
+    }
+    best
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_normalize_file_uri_unix() {
+        let n = normalize_workspace_root("file:///home/user/proj");
+        #[cfg(not(windows))]
+        assert_eq!(n, "/home/user/proj");
+        #[cfg(windows)]
+        assert_eq!(n, "\\home\\user\\proj");
+    }
+
+    #[test]
+    fn test_normalize_trailing_sep() {
+        let sep = if cfg!(windows) { "\\" } else { "/" };
+        let input = format!("/foo/bar{sep}");
+        let n = normalize_workspace_root(&input);
+        assert!(!n.ends_with(sep) || n.len() <= 3, "got {n}");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn test_normalize_windows_drive_letter_case_insensitive() {
+        assert_eq!(
+            normalize_workspace_root("D:\\Projects\\Foo"),
+            normalize_workspace_root("d:\\Projects\\Foo")
+        );
+        assert_eq!(normalize_workspace_root("D:"), "d:\\");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn test_normalize_windows_file_uri() {
+        assert_eq!(
+            normalize_workspace_root("file:///D:/Projects/Foo"),
+            "d:\\Projects\\Foo"
+        );
+    }
+
+    #[test]
+    fn test_percent_decoded() {
+        let n = normalize_workspace_root("file:///home/user/my%20project");
+        assert!(n.ends_with("my project"));
+    }
+
+    #[test]
+    fn test_longest_prefix_match_exact() {
+        let bindings = ["/a", "/a/b", "/a/b/c"];
+        assert_eq!(longest_prefix_match("/a/b/c", bindings), Some("/a/b/c"));
+        assert_eq!(longest_prefix_match("/a/b/c/d", bindings), Some("/a/b/c"));
+        assert_eq!(longest_prefix_match("/a/b", bindings), Some("/a/b"));
+    }
+
+    #[test]
+    fn test_longest_prefix_no_false_partial() {
+        // "/a/b-extra" must NOT match binding "/a/b".
+        let bindings = ["/a/b"];
+        assert_eq!(longest_prefix_match("/a/b-extra", bindings), None);
+    }
+
+    #[test]
+    fn test_longest_prefix_empty_candidates() {
+        let bindings: [&str; 0] = [];
+        assert_eq!(longest_prefix_match("/a", bindings), None);
+    }
+}

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

@@ -8,7 +8,7 @@ use uuid::Uuid;
 
 use crate::domain::{
     Client, Credential, CredentialType, FeatureSet, FeatureSetMember, InstalledServer, MemberMode,
-    OutboundOAuthRegistration, ServerFeature, Space,
+    OutboundOAuthRegistration, ServerFeature, Space, WorkspaceBinding,
 };
 
 /// Result type for repository operations
@@ -37,6 +37,16 @@ pub trait SpaceRepository: Send + Sync {
 
     /// Set a space as default
     async fn set_default(&self, id: &Uuid) -> RepoResult<()>;
+
+    /// Set (or clear, with `None`) the active FeatureSet for a Space.
+    ///
+    /// The active FS is the fallback applied when a connected client has
+    /// no pinned FS and no matching workspace binding.
+    async fn set_active_feature_set(
+        &self,
+        id: &Uuid,
+        feature_set_id: Option<&Uuid>,
+    ) -> RepoResult<()>;
 }
 
 /// InstalledServer repository trait
@@ -266,6 +276,55 @@ pub trait InboundMcpClientRepository: Send + Sync {
 
     /// Check if client has any grants for a space
     async fn has_grants_for_space(&self, client_id: &Uuid, space_id: &str) -> RepoResult<bool>;
+
+    /// Set the pinned Space + optional pinned FeatureSet for a client.
+    ///
+    /// This is the new (FeatureSet Resolver V2) path: each client row is an
+    /// independent approval bound to one Space. `pinned_feature_set_id = None`
+    /// means the client follows workspace-binding / space-active FS.
+    async fn set_pin(
+        &self,
+        client_id: &Uuid,
+        pinned_space_id: &Uuid,
+        pinned_feature_set_id: Option<&Uuid>,
+    ) -> RepoResult<()>;
+}
+
+/// Workspace binding repository trait
+///
+/// Bindings map normalized filesystem paths to FeatureSets on a per-Space basis.
+/// Matching is longest-prefix-wins; callers are expected to pass
+/// already-normalized paths (see [`crate::domain::normalize_workspace_root`]).
+#[async_trait]
+pub trait WorkspaceBindingRepository: Send + Sync {
+    /// List every binding across all Spaces.
+    async fn list(&self) -> RepoResult<Vec<WorkspaceBinding>>;
+
+    /// List bindings for a specific Space.
+    async fn list_for_space(&self, space_id: &Uuid) -> RepoResult<Vec<WorkspaceBinding>>;
+
+    /// Fetch a binding by id.
+    async fn get(&self, id: &Uuid) -> RepoResult<Option<WorkspaceBinding>>;
+
+    /// Insert a new binding. Fails on `(space_id, workspace_root)` conflict.
+    async fn create(&self, binding: &WorkspaceBinding) -> RepoResult<()>;
+
+    /// Update an existing binding (e.g., point to a different FS).
+    async fn update(&self, binding: &WorkspaceBinding) -> RepoResult<()>;
+
+    /// Delete a binding by id.
+    async fn delete(&self, id: &Uuid) -> RepoResult<()>;
+
+    /// Resolve which FeatureSet applies for a set of candidate workspace roots.
+    ///
+    /// Every candidate MUST already be normalized. Returns the binding whose
+    /// `workspace_root` is the longest prefix of any candidate, or `None`
+    /// when no binding matches.
+    async fn find_longest_prefix_match(
+        &self,
+        space_id: &Uuid,
+        candidate_roots: &[String],
+    ) -> RepoResult<Option<WorkspaceBinding>>;
 }
 
 /// Credential repository trait (local-only, never synced)