To explain it a different way... why do we need an isSameEntry() method? Why can't we just compare two FileSystemHandle objects directly?
Well, a handle mostly just represents a path on disk (which we never want to expose to a site). The API has a number of ways (drag & drop, file picker, file handling, re-hydration from IndexedDB) to acquire a handle. Two handles acquired from different contexts (possibly at various times, across browsing sessions) may represent the same path and should be considered equal. Only the browser knows where this file actually lives on disk, so only it can determine equality.
We essentially have the same problem here. We can create a unique ID using crypto.randomUUID(), but if we want it to represent the idea of a path on disk and not just a one-way mapping to an arbitrary FileSystemHandle object, we need the browser's help (or to call isSameEntry() on an unbounded number of handles (yikes)).
To make this a bit more concrete, let's consider an example from the Storing a representation of a handle in the database of your choice
use case described in the explainer. Say you're a site which allows users to maintain a digital database of their baseball cards
. The user selects an image file of the card. You generate an ID using crypto.randomUUID() which represents the file to use as a key in your database alongside all the card's information. You can access the handle using this key with a constant-time lookup in IndexedDB.
A week later, the user logs back on and selects a file from the picker. Is this card already in the database? Your only way to find out is to enumerate all handles you have access to (which could be thousands and thousands of cards) and call isSameEntry() on each of them. The ID you generated is useless until you find the handle in IndexedDB (i.e. handle -> database is potentially a prohibitively expensive operation).
The getUniqueId() method addresses this by answering the "have I seen this handle before" question in constant time.