@photostructure/fs-metadata 1.0.1 → 1.2.0

package/src/darwin/system_volume.h

@@ -0,0 +1,156 @@
+// src/darwin/system_volume.h
+//
+// Shared macOS system volume detection.
+//
+// Detection uses two signals combined:
+//   1. MNT_SNAPSHOT (statfs f_flags) — catches sealed APFS system snapshots
+//      ("/" and /System/Volumes/Recovery on macOS Catalina+).
+//   2. MNT_DONTBROWSE + APFS volume role — catches infrastructure volumes
+//      under /System/Volumes/* that are hidden from Finder. The "Data" role
+//      is excluded because /System/Volumes/Data is the primary user data
+//      volume (photos, documents, application data).
+//
+// Formula: MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")
+//
+// This is future-proof: new Apple infrastructure roles with MNT_DONTBROWSE
+// are auto-detected without maintaining a whitelist.
+//
+// Non-APFS MNT_DONTBROWSE mounts (e.g., devfs at /dev) fall through to
+// TypeScript fstype/path heuristics.
+//
+// See doc/system-volume-detection.md for the full rationale.
+// See: mount(2), sys/mount.h, IOKit/IOKitLib.h
+
+#pragma once
+
+#include "../common/debug_log.h"
+#include "raii_utils.h"
+#include <DiskArbitration/DiskArbitration.h>
+#include <IOKit/IOKitLib.h>
+#include <string>
+#include <sys/mount.h>
+
+namespace FSMeta {
+
+// Result of APFS volume role detection + system volume classification.
+struct VolumeRoleResult {
+  bool isSystemVolume = false;
+  std::string role; // e.g., "System", "Data", "VM", "" if unknown
+};
+
+// Extract the APFS volume role string via IOKit for a given DiskArbitration
+// disk ref. For snapshots (e.g., disk3s7s1), walks one parent up in the
+// IOService plane to find the parent volume's role.
+// Returns the first role string found, or "" if no role can be determined.
+inline std::string GetApfsVolumeRole(DADiskRef disk) {
+  if (!disk) {
+    return "";
+  }
+
+  IOObjectGuard media(DADiskCopyIOMedia(disk));
+  if (!media.isValid()) {
+    DEBUG_LOG("[GetApfsVolumeRole] Failed to get IOMedia");
+    return "";
+  }
+
+  // Check the volume's own Role property first
+  CFReleaser<CFArrayRef> role(
+      static_cast<CFArrayRef>(IORegistryEntryCreateCFProperty(
+          media.get(), CFSTR("Role"), kCFAllocatorDefault, 0)));
+
+  // If no Role on this entry, try the parent (handles snapshot → volume case:
+  // disk3s7s1 (snapshot) → disk3s7 (volume with System role))
+  IOObjectGuard parent;
+  if (!role.isValid()) {
+    io_registry_entry_t parentRef = 0;
+    kern_return_t kr =
+        IORegistryEntryGetParentEntry(media.get(), kIOServicePlane, &parentRef);
+    if (kr == KERN_SUCCESS) {
+      parent = IOObjectGuard(parentRef);
+      role.reset(static_cast<CFArrayRef>(IORegistryEntryCreateCFProperty(
+          parent.get(), CFSTR("Role"), kCFAllocatorDefault, 0)));
+    }
+  }
+
+  std::string result;
+  if (role.isValid() && CFGetTypeID(role.get()) == CFArrayGetTypeID()) {
+    CFIndex count = CFArrayGetCount(role.get());
+    if (count > 0) {
+      CFStringRef roleStr =
+          static_cast<CFStringRef>(CFArrayGetValueAtIndex(role.get(), 0));
+      if (roleStr && CFGetTypeID(roleStr) == CFStringGetTypeID()) {
+        char buf[64];
+        if (CFStringGetCString(roleStr, buf, sizeof(buf),
+                               kCFStringEncodingUTF8)) {
+          DEBUG_LOG("[GetApfsVolumeRole] Role: %s", buf);
+          result = buf;
+        }
+      }
+    }
+  }
+
+  // IOObjectGuard destructors automatically release media and parent
+  return result;
+}
+
+// Classify a macOS volume as system or user using mount flags and APFS role.
+//
+// Detection formula:
+//   MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")
+//
+// - MNT_SNAPSHOT alone catches sealed APFS system snapshots (/ and Recovery)
+// - MNT_DONTBROWSE combined with an APFS role catches infrastructure volumes
+//   (VM, Preboot, Update, Hardware, xART, etc.) while excluding the Data
+//   volume which contains user files
+// - Non-APFS MNT_DONTBROWSE mounts (devfs, NFS with nobrowse) are left for
+//   TypeScript heuristics
+inline VolumeRoleResult ClassifyMacVolume(const char *bsdDeviceName,
+                                          uint32_t f_flags,
+                                          DASessionRef session) {
+  VolumeRoleResult result;
+
+  // Layer 1: MNT_SNAPSHOT alone → system (sealed APFS snapshot)
+  if (f_flags & MNT_SNAPSHOT) {
+    result.isSystemVolume = true;
+  }
+
+  // Layer 2: APFS role via IOKit (if DA session available)
+  if (session && bsdDeviceName) {
+    // Strip "/dev/" prefix if present
+    const char *bsdName = bsdDeviceName;
+    if (strncmp(bsdName, "/dev/", 5) == 0) {
+      bsdName += 5;
+    }
+
+    CFReleaser<DADiskRef> disk(
+        DADiskCreateFromBSDName(kCFAllocatorDefault, session, bsdName));
+    if (disk.isValid()) {
+      result.role = GetApfsVolumeRole(disk.get());
+
+      // MNT_DONTBROWSE + known APFS role that isn't Data → system
+      if (!result.role.empty() && result.role != "Data" &&
+          (f_flags & MNT_DONTBROWSE)) {
+        result.isSystemVolume = true;
+      }
+    } else {
+      DEBUG_LOG("[ClassifyMacVolume] Failed to create disk ref for %s",
+                bsdName);
+    }
+  }
+
+  DEBUG_LOG("[ClassifyMacVolume] %s -> role=%s, isSystem=%s",
+            bsdDeviceName ? bsdDeviceName : "(null)", result.role.c_str(),
+            result.isSystemVolume ? "true" : "false");
+
+  return result;
+}
+
+// Lightweight fallback using only statfs f_flags (no DA/IOKit needed).
+// MNT_SNAPSHOT catches sealed APFS system snapshots ("/" and Recovery).
+inline VolumeRoleResult ClassifyMacVolumeByFlags(uint32_t f_flags) {
+  VolumeRoleResult result;
+  result.isSystemVolume = (f_flags & MNT_SNAPSHOT) != 0;
+  return result;
+}
+
+} // namespace FSMeta

package/src/darwin/volume_metadata.cpp

@@ -5,8 +5,10 @@
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
 #include "../common/volume_utils.h"
+#include "./da_mutex.h"
 #include "./fs_meta.h"
 #include "./raii_utils.h"
+#include "./system_volume.h"
 
 #include <CoreFoundation/CoreFoundation.h>
 #include <DiskArbitration/DiskArbitration.h>
@@ -22,8 +24,8 @@
 
 namespace FSMeta {
 
-// Global mutex for DiskArbitration operations
-static std::mutex g_diskArbitrationMutex;
+// Global mutex for DiskArbitration operations (declared in da_mutex.h)
+std::mutex g_diskArbitrationMutex;
 
 // Helper function to convert CFString to std::string
 static std::string CFStringToString(CFStringRef cfString) {
@@ -109,6 +111,7 @@ public:
 
 private:
   VolumeMetadataOptions options_;
+  uint32_t f_flags_ = 0;
 
   bool GetBasicVolumeInfo() {
     DEBUG_LOG("[GetVolumeMetadataWorker] Getting basic volume info for: %s",
@@ -186,6 +189,12 @@ private:
     metadata.fstype = fs.f_fstypename;
     metadata.mountFrom = fs.f_mntfromname;
     metadata.mountName = fs.f_mntonname;
+    metadata.isReadOnly = (fs.f_flags & MNT_RDONLY) != 0;
+    // Store flags for ClassifyMacVolume in GetDiskArbitrationInfoSafe()
+    f_flags_ = fs.f_flags;
+    // Preliminary flag-only check; upgraded by ClassifyMacVolume
+    auto flagResult = ClassifyMacVolumeByFlags(fs.f_flags);
+    metadata.isSystemVolume = flagResult.isSystemVolume;
     metadata.status = "ready";
 
     DEBUG_LOG("[GetVolumeMetadataWorker] Volume info - size: %.0f, available: "
@@ -243,6 +252,13 @@ private:
     session.scheduleOnQueue(da_queue);
 
     try {
+      // Classify volume using mount flags + APFS role
+      auto classification = ClassifyMacVolume(metadata.mountFrom.c_str(),
+                                              f_flags_, session.get());
+      metadata.isSystemVolume =
+          metadata.isSystemVolume || classification.isSystemVolume;
+      metadata.volumeRole = classification.role;
+
       CFReleaser<DADiskRef> disk(DADiskCreateFromBSDName(
           kCFAllocatorDefault, session.get(), metadata.mountFrom.c_str()));
 

package/src/darwin/volume_mount_points.cpp

@@ -2,8 +2,10 @@
 #include "../common/volume_mount_points.h"
 #include "../common/debug_log.h"
 #include "../common/error_utils.h"
+#include "./da_mutex.h"
 #include "./fs_meta.h"
 #include "./raii_utils.h"
+#include "./system_volume.h"
 #include <chrono>
 #include <future>
 #include <sys/mount.h>
@@ -48,27 +50,56 @@ public:
         }
       }
 
+      // Classify all mount points under the DA mutex, then release the
+      // lock before launching async accessibility checks. This serializes
+      // DiskArbitration + IOKit operations with getVolumeMetadata workers.
+      std::vector<MountPoint> allMountPoints;
+      {
+        std::lock_guard<std::mutex> lock(g_diskArbitrationMutex);
+
+        DASessionRAII session(DASessionCreate(kCFAllocatorDefault));
+        if (session.isValid()) {
+          static dispatch_queue_t da_queue = dispatch_queue_create(
+              "com.photostructure.fs-metadata.mountpoints",
+              DISPATCH_QUEUE_SERIAL);
+          session.scheduleOnQueue(da_queue);
+        }
+
+        for (int j = 0; j < count; j++) {
+          MountPoint mp;
+          mp.mountPoint = mntbuf.get()[j].f_mntonname;
+          mp.fstype = mntbuf.get()[j].f_fstypename;
+          mp.isReadOnly = (mntbuf.get()[j].f_flags & MNT_RDONLY) != 0;
+
+          auto classification =
+              session.isValid()
+                  ? ClassifyMacVolume(mntbuf.get()[j].f_mntfromname,
+                                      mntbuf.get()[j].f_flags, session.get())
+                  : ClassifyMacVolumeByFlags(mntbuf.get()[j].f_flags);
+          mp.isSystemVolume = classification.isSystemVolume;
+          mp.volumeRole = classification.role;
+          mp.error = "";
+          allMountPoints.push_back(std::move(mp));
+        }
+        // DA session RAII unschedules and releases here under the lock
+      }
+
       // Process mount points in batches to limit concurrent threads
       const size_t maxConcurrentChecks = 4; // Limit concurrent access checks
 
-      for (size_t i = 0; i < static_cast<size_t>(count);
-           i += maxConcurrentChecks) {
+      for (size_t i = 0; i < allMountPoints.size(); i += maxConcurrentChecks) {
         std::vector<std::future<std::pair<std::string, bool>>> futures;
-        std::vector<MountPoint> batchMountPoints;
+        std::vector<MountPoint *> batchPtrs;
 
-        // Create batch of mount points and launch their checks
+        // Launch async accessibility checks (no DA operations here)
         for (size_t j = i;
-             j < static_cast<size_t>(count) && j < i + maxConcurrentChecks;
-             j++) {
-          MountPoint mp;
-          mp.mountPoint = mntbuf.get()[j].f_mntonname;
-          mp.fstype = mntbuf.get()[j].f_fstypename;
-          mp.error = ""; // Initialize error field
+             j < allMountPoints.size() && j < i + maxConcurrentChecks; j++) {
+          auto &mp = allMountPoints[j];
 
           DEBUG_LOG("[GetVolumeMountPointsWorker] Checking mount point: %s",
                     mp.mountPoint.c_str());
 
-          batchMountPoints.push_back(mp);
+          batchPtrs.push_back(&mp);
 
           // Launch async check
           futures.push_back(
@@ -86,7 +117,7 @@ public:
 
         // Process results for this batch
         for (size_t k = 0; k < futures.size(); k++) {
-          auto &mp = batchMountPoints[k];
+          auto &mp = *batchPtrs[k];
           try {
             auto status =
                 futures[k].wait_for(std::chrono::milliseconds(timeoutMs_));
@@ -131,10 +162,11 @@ public:
             mp.error = std::string("Mount point check failed: ") + e.what();
             DEBUG_LOG("[GetVolumeMountPointsWorker] Exception: %s", e.what());
           }
-
-          mountPoints_.push_back(std::move(mp));
         }
       }
+
+      // Move all classified + accessibility-checked mount points to results
+      mountPoints_ = std::move(allMountPoints);
     } catch (const std::exception &e) {
       SetError(std::string("Failed to process mount points: ") + e.what());
       DEBUG_LOG("[GetVolumeMountPointsWorker] Exception: %s", e.what());

package/src/index.ts

@@ -12,6 +12,7 @@ import {
   isHiddenRecursiveImpl,
   setHiddenImpl,
 } from "./hidden";
+import { getMountPointForPathImpl } from "./mount_point_for_path";
 import {
   getTimeoutMsDefault,
   IncludeSystemVolumesDefault,
@@ -34,6 +35,7 @@ import type { VolumeHealthStatus } from "./volume_health_status";
 import { VolumeHealthStatuses } from "./volume_health_status";
 import {
   getAllVolumeMetadataImpl,
+  getVolumeMetadataForPathImpl,
   getVolumeMetadataImpl,
 } from "./volume_metadata";
 import type { GetVolumeMountPointOptions } from "./volume_mount_points";
@@ -108,6 +110,53 @@ export function getVolumeMetadata(
   );
 }
 
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional filesystem operation settings
+ */
+export function getVolumeMetadataForPath(
+  pathname: string,
+  opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>,
+): Promise<VolumeMetadata> {
+  return getVolumeMetadataForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn,
+  );
+}
+
+/**
+ * Get the mount point path for an arbitrary file or directory path.
+ *
+ * This is a lightweight alternative to {@link getVolumeMetadataForPath} when
+ * you only need the mount point string. On macOS it uses a single fstatfs()
+ * call (no DiskArbitration, IOKit, or space calculations). On Linux/Windows
+ * it uses device ID matching against the mount table.
+ *
+ * Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional settings (timeoutMs, linuxMountTablePaths)
+ * @returns The mount point path (e.g., "/", "/System/Volumes/Data", "C:\\")
+ */
+export function getMountPointForPath(
+  pathname: string,
+  opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>,
+): Promise<string> {
+  return getMountPointForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn,
+  );
+}
+
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.

package/src/linux/mtab.ts

@@ -45,6 +45,10 @@ export interface MountEntry {
   fs_passno: number | undefined;
 }
 
+function isReadOnlyMount(fs_mntops: string | undefined): boolean {
+  return fs_mntops?.split(",").includes("ro") ?? false;
+}
+
 export function mountEntryToMountPoint(
   entry: MountEntry,
 ): MountPoint | undefined {
@@ -55,6 +59,7 @@ export function mountEntryToMountPoint(
     : {
         mountPoint,
         fstype,
+        isReadOnly: isReadOnlyMount(entry.fs_mntops),
       };
 }
 
@@ -77,6 +82,7 @@ export function mountEntryToPartialVolumeMetadata(
     fstype: entry.fs_vfstype,
     mountFrom: entry.fs_spec,
     isSystemVolume: isSystemVolume(entry.fs_file, entry.fs_vfstype, options),
+    isReadOnly: isReadOnlyMount(entry.fs_mntops),
     remote: false, // < default to false, but it may be overridden by extractRemoteInfo
     ...extractRemoteInfo(entry.fs_spec, networkFsTypes),
   };

package/src/mount_point_for_path.ts

@@ -0,0 +1,54 @@
+// src/mount_point_for_path.ts
+
+import { realpath } from "node:fs/promises";
+import { dirname } from "node:path";
+import { withTimeout } from "./async";
+import { debug } from "./debuglog";
+import { statAsync } from "./fs";
+import { isMacOS } from "./platform";
+import { isBlank, isNotBlank } from "./string";
+import type { NativeBindingsFn } from "./types/native_bindings";
+import type { Options } from "./types/options";
+import { findMountPointByDeviceId } from "./volume_metadata";
+
+export async function getMountPointForPathImpl(
+  pathname: string,
+  opts: Options,
+  nativeFn: NativeBindingsFn,
+): Promise<string> {
+  if (isBlank(pathname)) {
+    throw new TypeError("Invalid pathname: got " + JSON.stringify(pathname));
+  }
+
+  // realpath() resolves POSIX symlinks. APFS firmlinks are NOT resolved by
+  // realpath(), but fstatfs() follows them — handled below on macOS.
+  const resolved = await realpath(pathname);
+
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : dirname(resolved);
+
+  if (isMacOS) {
+    // Use the lightweight native getMountPoint which only does fstatfs —
+    // no DiskArbitration, IOKit, or space calculations.
+    const native = await nativeFn();
+    if (native.getMountPoint) {
+      debug("[getMountPointForPath] using native getMountPoint for %s", dir);
+      const p = native.getMountPoint(dir);
+      const mountPoint = await withTimeout({
+        desc: "getMountPoint()",
+        timeoutMs: opts.timeoutMs,
+        promise: p,
+      });
+      if (isNotBlank(mountPoint)) {
+        debug("[getMountPointForPath] resolved to %s", mountPoint);
+        return mountPoint;
+      }
+    }
+    // Fallback: should not happen on macOS, but defensive
+    throw new Error("getMountPoint native function unavailable");
+  }
+
+  // Linux/Windows: device ID matching + path prefix tiebreaker
+  debug("[getMountPointForPath] using device matching for %s", resolved);
+  return findMountPointByDeviceId(resolved, resolvedStat, opts, nativeFn);
+}

package/src/options.ts

@@ -83,23 +83,13 @@ export const SystemPathPatternsDefault = [
   "/mnt/wslg/versions.txt",
   "/usr/lib/wsl/drivers",
 
-  // macOS system paths:
-  "/private/var/vm", // macOS swap
-  "/System/Volumes/Hardware",
-  "/System/Volumes/iSCPreboot",
-  "/System/Volumes/Preboot",
-  "/System/Volumes/Recovery",
-  "/System/Volumes/Reserved",
-  "/System/Volumes/Update",
-  "/System/Volumes/VM",
-  "/System/Volumes/xarts",
-
-  // macOS per-volume metadata (Spotlight, FSEvents, versioning, Trash):
-  // https://eclecticlight.co/2021/01/28/spotlight-on-search-how-spotlight-works/
-  "**/.DocumentRevisions-V100",
-  "**/.fseventsd",
-  "**/.Spotlight-V100",
-  "**/.Trashes",
+  // macOS system volumes are detected natively via APFS volume roles
+  // (IOKit IOMedia "Role" property) with MNT_SNAPSHOT as a fallback.
+  // No path patterns needed. See src/darwin/system_volume.h.
+  //
+  // /private/var/vm is the macOS swap directory (not a mount point on most
+  // systems, but included for completeness if it appears as one).
+  "/private/var/vm",
 ] as const;
 
 /**

package/src/path.ts

@@ -1,6 +1,6 @@
 // src/path.ts
 
-import { dirname, resolve } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 import { isWindows } from "./platform";
 import { isBlank } from "./string";
 
@@ -70,3 +70,18 @@ export function isRootDirectory(path: string): boolean {
   const n = normalizePath(path);
   return n == null ? false : isWindows ? dirname(n) === n : n === "/";
 }
+
+/**
+ * @return true if `ancestor` is the same path as `descendant`, or is a parent
+ * directory of `descendant`. Both paths should be normalized/resolved.
+ */
+export function isAncestorOrSelf(
+  ancestor: string,
+  descendant: string,
+): boolean {
+  if (ancestor === descendant) return true;
+  // Root dirs already end with sep (e.g. "/" or "C:\"); others need sep
+  // appended to avoid "/home" matching "/homeother".
+  const prefix = isRootDirectory(ancestor) ? ancestor : ancestor + sep;
+  return descendant.startsWith(prefix);
+}

package/src/system_volume.ts

@@ -60,13 +60,9 @@ export function assignSystemVolume(
 ) {
   const result = isSystemVolume(mp.mountPoint, mp.fstype, config);
 
-  if (isWindows) {
-    // native code actually knows the system drive and has more in-depth
-    // metadata information that we trust more than these heuristics
-    mp.isSystemVolume ??= result;
-  } else {
-    // macOS and Linux don't have a concept of an explicit "system drive" like
-    // Windows--always trust our heuristics
-    mp.isSystemVolume = result;
-  }
+  // Native code may have already marked this as a system volume (e.g.,
+  // Windows system drive detection, macOS MNT_SNAPSHOT for the sealed
+  // APFS system snapshot at /). Never downgrade a native true — only
+  // upgrade via path/fstype heuristics.
+  mp.isSystemVolume = mp.isSystemVolume || result;
 }

package/src/test-utils/assert.ts

@@ -46,6 +46,10 @@ export function assertMetadata(metadata: VolumeMetadata | undefined) {
       expect(metadata.uuid).toMatch(/^[0-9a-z-]{8,}$/i);
     }
 
+    if (metadata.isReadOnly !== undefined) {
+      expect(typeof metadata.isReadOnly).toBe("boolean");
+    }
+
     if (metadata.remote !== undefined) {
       expect(typeof metadata.remote).toBe("boolean");
 

package/src/types/mount_point.ts

@@ -39,12 +39,39 @@ export interface MountPoint {
    * Indicates if this volume is primarily for system use (e.g., swap, snap
    * loopbacks, EFI boot, or only system directories).
    *
-   * Note: This is a best-effort classification and is not 100% accurate.
+   * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+   * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+   * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+   * is **not** a system volume — it holds all user data, accessed via firmlinks.
    *
    * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
    */
   isSystemVolume?: boolean;
 
+  /**
+   * The APFS volume role, if available. Only present on macOS for APFS volumes.
+   *
+   * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+   * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+   *
+   * Used for system volume detection: volumes with a non-`"Data"` role and
+   * `MNT_DONTBROWSE` are classified as system volumes.
+   *
+   * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+   */
+  volumeRole?: string;
+
+  /**
+   * Whether the volume is mounted read-only.
+   *
+   * Examples of read-only volumes include the macOS APFS system snapshot at
+   * `/`, mounted ISO images, and write-protected media.
+   *
+   * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+   * consumers should avoid using it for persistent identification.
+   */
+  isReadOnly?: boolean;
+
   /**
    * If there are non-critical errors while extracting metadata, those errors
    * may be added to this field.

package/src/types/native_bindings.ts

@@ -54,6 +54,13 @@ export interface NativeBindings {
    * subsequent parsing and extraction logic.
    */
   getVolumeMetadata(options: GetVolumeMetadataOptions): Promise<VolumeMetadata>;
+
+  /**
+   * macOS only: lightweight mount point lookup using fstatfs().
+   * Returns the f_mntonname for the given directory path without fetching
+   * full volume metadata (no DiskArbitration, no IOKit, no space calculation).
+   */
+  getMountPoint?(path: string): Promise<string>;
 }
 
 export type GetVolumeMetadataOptions = {