feat(gateway): Phase 1 — resolver deny by default (Unbound)

Autonomous decisions:
- Removed default_fallback() instead of keeping it dead; all three call sites now use unbound().
- Kept feature_set_repo on FeatureSetResolverService for constructor API stability (no longer read at resolve time).

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

crates/mcpmux-gateway/src/services/feature_set_resolver.rs

@@ -1,65 +1,63 @@
 //! FeatureSet Resolver Service.
 //!
-//! Capability-branched resolution. The branch point is the MCP `roots`
-//! capability declared by the client at `initialize`:
+//! Binding-canonical resolution. The resolver answers one question: *which
+//! [`WorkspaceBinding`](mcpmux_core::WorkspaceBinding) (if any) matches the
+//! signals this caller presents?* Signals are ranked; none are mandatory:
 //!
 //! ```text
 //! resolve(session_id, client_id):
-//!     // Tier 1 — roots-capable session with reported roots
+//!     // Signal 1 — reported root (deprecated MCP primitive, SEP-2577)
 //!     if session reported roots AND a binding matches:
 //!         return (binding.space_id, [binding.feature_set_id], WorkspaceBinding)
 //!
-//!     // Tier 1b — roots-capable, roots reported, but no binding yet
+//!     // Tier 1b — roots reported, no binding matched
 //!     if session reported roots AND no binding matched:
-//!         return (default_space, [starter_fs], SpaceDefault)   // unmapped folder
-//!         // (also emits WorkspaceNeedsBinding upstream so the user can still map)
+//!         return (scoped_space, [], Unbound)   // deny by default
+//!         // (upstream emits WorkspaceNeedsBinding so the user can bind)
 //!
 //!     // Tier 1c — declared `roots` but they haven't arrived yet
 //!     if session declared `roots` AND none yet in registry:
 //!         if within the pending-roots grace window:
 //!             return ([], default_space, PendingRoots)   // wait for the root
 //!         else:
-//!             return (default_space, [starter_fs], SpaceDefault)   // gave up waiting
+//!             return (default_space, [], Unbound)   // gave up waiting
 //!
-//!     // Tier 2 — rootless-by-design (Claude.ai web, ChatGPT, …)
+//!     // Signal 2 — client identity (rootless-by-design: Claude.ai web, …)
 //!     if client has grants in the default space:
 //!         return (default_space, grants, ClientGrant)
 //!
 //!     // Tier 3 — no roots, no grants
-//!     return (default_space, [starter_fs], SpaceDefault)
+//!     return (default_space, [], Unbound)
 //! ```
 //!
-//! # Default fallback (the "every folder needs mapping" fix)
+//! Signal 3 (machine) scopes binding lookup: client machine → local machine
+//! → global. A path bound only on another machine does not match here.
 //!
-//! When nothing more specific resolves — an unmapped folder (Tier 1b), a
-//! rootless client with no grants, or a roots-capable client that never
-//! reported a folder (Tier 1c after the grace window) — the resolver falls
-//! back to the **default Space's Starter FeatureSet** instead of denying.
-//! That makes folders work out of the box: a freshly-opened project gets the
-//! Starter tools immediately, and the user only *needs* an explicit
-//! [`WorkspaceBinding`](mcpmux_core::WorkspaceBinding) when they want a folder
-//! to see something *other* than the default. The Starter FS's membership is
-//! the control surface: edit it to change what every unmapped folder sees, or
-//! empty it to grant nothing by default. (The Starter is builtin and can't be
-//! deleted, so the fallback always has a target.)
+//! ## Deny by default
 //!
-//! ## Grace window — avoid "default then mapped" flips
+//! When no binding matches — an unmapped folder (Tier 1b), a rootless client
+//! with no grants, or a roots-capable client that never reported a folder
+//! (Tier 1c after the grace window) — the resolver returns
+//! [`ResolutionSource::Unbound`] with empty `feature_set_ids`. Callers get
+//! zero backend tools until they have an explicit binding (or a client grant
+//! for rootless clients). Meta management tools are appended unconditionally
+//! by the request handler.
+//!
+//! ## Grace window — avoid "empty then mapped" flips
 //!
 //! A roots-capable client that's *about* to report a folder must resolve
-//! straight to that folder's binding (or the default-for-unmapped), never
-//! flash the default tools first and then flip. So while a session has
-//! declared (or might declare) `roots` and none have arrived yet, the
-//! resolver holds at `PendingRoots` (empty) for a short grace window rather
-//! than defaulting immediately. Only once the window lapses with no root in
-//! sight does it settle on `SpaceDefault`, so a misbehaving client that never
-//! reports isn't stranded on meta-tools forever. A roots-capable session
-//! **never** falls through to another client's grants — after the grace it
-//! goes straight to the Space default, preserving per-session isolation.
+//! straight to that folder's binding (or `Unbound`), never flash tools first
+//! and then flip. So while a session has declared (or might declare) `roots`
+//! and none have arrived yet, the resolver holds at `PendingRoots` (empty) for
+//! a short grace window. Only once the window lapses with no root in sight
+//! does it settle on `Unbound`. A roots-capable session **never** falls
+//! through to another client's grants — after the grace it goes straight to
+//! `Unbound`, preserving per-session isolation.
 //!
-//! The caller's client identity is used **only** for the rootless fallback —
-//! every roots-capable session routes via its own reported roots, regardless
-//! of which OAuth client opened it. This is what makes "two VS Code windows
-//! sharing one OAuth identity" route independently.
+//! The caller's client identity is used **only** for the rootless Tier-2 grant
+//! lookup — every roots-capable session routes via its own reported roots,
+//! regardless of which OAuth client opened it. This is what makes "two VS Code
+//! windows sharing one OAuth identity" route independently.
 //!
 //! # Trust model (deliberate design decision)
 //!
@@ -126,17 +124,18 @@ pub enum ResolutionSource {
     /// Rootless-by-design client. The space-default's per-client
     /// `client_grants` were applied.
     ClientGrant,
-    /// Fell back to the default Space's Starter FeatureSet because nothing
-    /// more specific resolved — an unmapped folder, a rootless client with
-    /// no grants, or a roots-capable client that never reported a folder.
-    /// For the unmapped-folder subcase the upstream caller still emits
-    /// `WorkspaceNeedsBinding` so the user can attach an explicit mapping.
+    /// No binding matched; deny by default (empty `feature_set_ids`). Carries
+    /// `space_id` for base-dir context and the bind CTA. Upstream emits
+    /// `WorkspaceNeedsBinding` for unmapped folders.
+    Unbound,
+    /// Deprecated — no longer produced by the resolver. Retained for serde
+    /// compatibility (e.g. `set_workspace_root` responses that may still
+    /// carry this value from older gateway versions).
+    #[doc(hidden)]
     SpaceDefault,
     /// No FeatureSet resolved at all. Defensive: reached only when there's no
     /// default Space, or — degenerately — the default Space somehow has no
-    /// Starter FeatureSet. The Starter is builtin and seeded with every Space,
-    /// so this is normally unreachable; to grant nothing by default the user
-    /// empties the Starter (still `SpaceDefault`, just with no members).
+    /// Starter FeatureSet.
     Deny,
 }
 
@@ -300,41 +299,15 @@ impl FeatureSetResolverService {
         self
     }
 
-    /// Fall back to `space_id`'s Starter FeatureSet. `space_id` is the global
-    /// default Space for rootless sessions, or a base-dir-scoped Space for an
-    /// unmapped folder under that Space's base directory. Returns
-    /// [`ResolutionSource::SpaceDefault`] when a Starter exists (the normal
-    /// path — it's builtin and seeded per Space), or, defensively,
-    /// [`ResolutionSource::Deny`] in the degenerate case where the Space has no
-    /// Starter.
-    async fn default_fallback(&self, space_id: Uuid) -> Result<ResolvedFeatureSet> {
-        if let Some(fs) = self
-            .feature_set_repo
-            .get_starter_for_space(&space_id.to_string())
-            .await?
-        {
-            debug!(
-                %space_id,
-                feature_set_id = %fs.id,
-                "[FeatureSetResolver] resolved via SpaceDefault (Starter fallback)",
-            );
-            return Ok(ResolvedFeatureSet {
-                feature_set_ids: vec![fs.id],
-                space_id: Some(space_id),
-                source: ResolutionSource::SpaceDefault,
-                collision_client_id: None,
-            });
-        }
-        debug!(
-            %space_id,
-            "[FeatureSetResolver] no Starter FeatureSet in Space — deny",
-        );
-        Ok(ResolvedFeatureSet {
+    /// Deny by default: no binding matched. Carries `space_id` for base-dir
+    /// context and the bind CTA; `feature_set_ids` is empty.
+    fn unbound(&self, space_id: Uuid) -> ResolvedFeatureSet {
+        ResolvedFeatureSet {
             feature_set_ids: vec![],
             space_id: Some(space_id),
-            source: ResolutionSource::Deny,
+            source: ResolutionSource::Unbound,
             collision_client_id: None,
-        })
+        }
     }
 
     /// Borrow the session-roots registry. The notifier uses this to GC
@@ -419,24 +392,21 @@ impl FeatureSetResolverService {
                         collision_client_id: None,
                     });
                 }
-                // Tier 1b: had roots, no binding. The folder is unmapped, so
-                // fall back to a Starter FS — the folder works immediately
-                // instead of getting nothing. Scope it to the Space whose base
+                // Tier 1b: had roots, no binding. The folder is unmapped —
+                // deny by default. Scope `space_id` to the Space whose base
                 // directory claims the root (longest-prefix), if any; otherwise
-                // the global default Space. Upstream still emits
-                // WorkspaceNeedsBinding (it prompts on SpaceDefault too) so the
-                // user can attach an explicit mapping for something other than
-                // the default.
+                // the global default Space. Upstream emits WorkspaceNeedsBinding
+                // so the user can attach an explicit binding.
                 let target_space = self
                     .space_for_roots(&reported_roots)
                     .await?
                     .unwrap_or(default_space_id);
                 debug!(
                     %target_space,
                     scoped_by_base_dir = target_space != default_space_id,
-                    "[FeatureSetResolver] roots reported but no binding matched — SpaceDefault",
+                    "[FeatureSetResolver] roots reported but no binding matched — Unbound",
                 );
-                return self.default_fallback(target_space).await;
+                return Ok(self.unbound(target_space));
             }
 
             // Tier 1c: client declared `roots` but none have ARRIVED yet
@@ -472,17 +442,16 @@ impl FeatureSetResolverService {
                         collision_client_id: None,
                     });
                 }
-                // Grace lapsed with no root in sight — settle on the Space
-                // default rather than stranding the client on meta-tools
-                // forever. Go STRAIGHT to the default (not via Tier-2 grants):
-                // a roots-capable session must never pick up another client's
-                // grants (per-session isolation invariant).
+                // Grace lapsed with no root in sight — deny by default. Go
+                // STRAIGHT to Unbound (not via Tier-2 grants): a roots-capable
+                // session must never pick up another client's grants
+                // (per-session isolation invariant).
                 debug!(
                     session_id = %sid,
                     capability = ?roots_capable_known,
-                    "[FeatureSetResolver] pending-roots grace lapsed, no root reported — SpaceDefault",
+                    "[FeatureSetResolver] pending-roots grace lapsed, no root reported — Unbound",
                 );
-                return self.default_fallback(default_space_id).await;
+                return Ok(self.unbound(default_space_id));
             }
         }
 
@@ -516,16 +485,14 @@ impl FeatureSetResolverService {
             }
         }
 
-        // Tier 3 — no roots, no grants. Fall back to the Space default so a
-        // bare client still gets the Starter tools instead of nothing. The
-        // mcpmux_* meta tools are appended unconditionally by the request
-        // handler regardless, so the LLM can always self-bind / ask the user
-        // for a grant from here.
+        // Tier 3 — no roots, no grants. Deny by default. The mcpmux_* meta
+        // tools are appended unconditionally by the request handler regardless,
+        // so the LLM can always self-bind / ask the user for a grant from here.
         debug!(
             space_id = %default_space_id,
             ?client_id,
-            "[FeatureSetResolver] no roots + no grants — SpaceDefault",
+            "[FeatureSetResolver] no roots + no grants — Unbound",
         );
-        self.default_fallback(default_space_id).await
+        Ok(self.unbound(default_space_id))
     }
 }

tests/rust/tests/integration/effective_features.rs

@@ -269,16 +269,14 @@ async fn empty_mapping_yields_zero_effective_tools() {
     assert!(ctx.effective_tools("sess").await.is_empty());
 }
 
-/// A reported root with no mapping falls back to the default Space's Starter
-/// FS (the "every folder needs mapping" fix) → it sees exactly the Starter's
-/// tools, not nothing. We drop one tool into the Starter and confirm the
-/// unmapped session resolves to `SpaceDefault` and sees precisely that tool.
+/// A reported root with no mapping resolves to `Unbound` (deny by default) —
+/// zero backend tools regardless of Starter FS membership.
 #[tokio::test(flavor = "multi_thread")]
-async fn unbound_session_falls_back_to_starter_fs() {
+async fn unbound_session_returns_no_tools() {
     let ctx = Ctx::new().await;
 
-    // Put one tool in the default Space's Starter FS so the fallback is
-    // observable (the seeded Starter is otherwise empty).
+    // Put one tool in the default Space's Starter FS — unbound sessions must
+    // NOT see it (Starter is no longer the silent fallback).
     let starter = ctx
         .fs_repo
         .get_starter_for_space(&ctx.space_id_str)
@@ -299,19 +297,13 @@ async fn unbound_session_falls_back_to_starter_fs() {
     ctx.session_roots.set_roots_capable("sess", true);
 
     let resolved = ctx.resolver.resolve(Some("sess"), None).await.unwrap();
-    assert_eq!(resolved.source, ResolutionSource::SpaceDefault);
-    assert_eq!(resolved.feature_set_ids, vec![starter.id]);
-    assert_eq!(
-        ctx.effective_tools("sess").await,
-        vec!["create_issue".to_string()],
-    );
+    assert_eq!(resolved.source, ResolutionSource::Unbound);
+    assert!(resolved.feature_set_ids.is_empty());
+    assert!(ctx.effective_tools("sess").await.is_empty());
 }
 
-/// The "grant nothing by default" off-switch: the Starter is builtin and can't
-/// be deleted, but an operator can EMPTY it. An empty Starter still resolves
-/// (source `SpaceDefault`), but yields zero effective tools — so unmapped
-/// folders see nothing until they're either bound or the Starter is populated.
-/// The seeded Starter starts empty, which is exactly this state.
+/// Unbound sessions get zero effective tools even when the Starter FS is
+/// populated — deny by default is independent of Starter membership.
 #[tokio::test(flavor = "multi_thread")]
 async fn empty_starter_grants_nothing_to_unbound_session() {
     let ctx = Ctx::new().await;
@@ -341,9 +333,8 @@ async fn empty_starter_grants_nothing_to_unbound_session() {
     ctx.session_roots.set_roots_capable("sess", true);
 
     let resolved = ctx.resolver.resolve(Some("sess"), None).await.unwrap();
-    assert_eq!(resolved.source, ResolutionSource::SpaceDefault);
-    assert_eq!(resolved.feature_set_ids, vec![starter.id]);
-    // Resolves to the Starter, but it grants nothing.
+    assert_eq!(resolved.source, ResolutionSource::Unbound);
+    assert!(resolved.feature_set_ids.is_empty());
     assert!(ctx.effective_tools("sess").await.is_empty());
 }