What's new in FSKit

public struct FSDataCacheError : CustomNSError, Hashable, Error {

    public init(_nsError: NSError)

    public static var errorDomain: String { get }

    /// Error codes specific to data cache operations.
    @available(macOS 27.0, *)
    public enum Code : Int, @unchecked Sendable, Equatable {

        /// Error codes specific to data cache operations.
        public typealias _ErrorType = FSDataCacheError

        /// The requested cache mode and coherency type combination is invalid.
        case errorInvalidCacheModeCoherency = 4510

        /// The cache transition is not allowed.
        ///
        /// This error occurs when attempting an invalid transition, such as using an upgrade
        /// method for a downgrade operation, or vice versa.
        case errorInvalidCacheTransition = 4511

        /// Failed to flush dirty cached data to storage.
        case errorCacheFlushFailed = 4512

        /// Failed to invalidate (clear) cached data.
        case errorCacheInvalidationFailed = 4513

        /// A conflicting cache operation is in progress.
        ///
        /// This error occurs when multiple cache operations on the same item conflict,
        /// such as attempting to change cache mode while I/O is active.
        case errorCacheOperationConflict = 4514
    }

    /// The requested cache mode and coherency type combination is invalid.
    public static var errorInvalidCacheModeCoherency: FSDataCacheError.Code { get }

    /// The cache transition is not allowed.
    ///
    /// This error occurs when attempting an invalid transition, such as using an upgrade
    /// method for a downgrade operation, or vice versa.
    public static var errorInvalidCacheTransition: FSDataCacheError.Code { get }

    /// Failed to flush dirty cached data to storage.
    public static var errorCacheFlushFailed: FSDataCacheError.Code { get }

    /// Failed to invalidate (clear) cached data.
    public static var errorCacheInvalidationFailed: FSDataCacheError.Code { get }

    /// A conflicting cache operation is in progress.
    ///
    /// This error occurs when multiple cache operations on the same item conflict,
    /// such as attempting to change cache mode while I/O is active.
    public static var errorCacheOperationConflict: FSDataCacheError.Code { get }
}

public enum Code : Int, @unchecked Sendable, Equatable {

    /// Error codes specific to data cache operations.
    public typealias _ErrorType = FSDataCacheError

    /// The requested cache mode and coherency type combination is invalid.
    case errorInvalidCacheModeCoherency = 4510

    /// The cache transition is not allowed.
    ///
    /// This error occurs when attempting an invalid transition, such as using an upgrade
    /// method for a downgrade operation, or vice versa.
    case errorInvalidCacheTransition = 4511

    /// Failed to flush dirty cached data to storage.
    case errorCacheFlushFailed = 4512

    /// Failed to invalidate (clear) cached data.
    case errorCacheInvalidationFailed = 4513

    /// A conflicting cache operation is in progress.
    ///
    /// This error occurs when multiple cache operations on the same item conflict,
    /// such as attempting to change cache mode while I/O is active.
    case errorCacheOperationConflict = 4514
}

public protocol AccessCheckHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var isAccessCheckInhibited: Bool { get }

    /// Checks whether the file system allows access to the given item.
    ///
    /// - Parameters:
    ///   - theItem: The item for which to check access.
    ///   - access: A mask indicating a set of access types for which to check.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If the access check succeeds, pass an instance of ``FSCheckAccessResult`` containing a Boolean value to indicate whether the file system grants access, along with a `nil` error. If the access check fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCheckAccessResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func checkAccess(to theItem: FSItem, requestedAccess access: FSVolume.AccessMask, context: FSContext, replyHandler reply: @escaping @Sendable (FSCheckAccessResult?, (any Error)?) -> Void)

    /// Checks whether the file system allows access to the given item.
    ///
    /// - Parameters:
    ///   - theItem: The item for which to check access.
    ///   - access: A mask indicating a set of access types for which to check.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If the access check succeeds, pass an instance of ``FSCheckAccessResult`` containing a Boolean value to indicate whether the file system grants access, along with a `nil` error. If the access check fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCheckAccessResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func checkAccess(to theItem: FSItem, requestedAccess access: FSVolume.AccessMask, context: FSContext) async throws -> FSCheckAccessResult
}

public protocol DataCacheHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    @available(macOS 27.0, *)
    optional var isDataCacheInhibited: Bool { get }

    /// Opens an item with cache mode negotiation.
    ///
    /// FSKit calls this method when a file is opened, providing the requested cache mode.
    /// Module implementation should determine what level of caching it can support for this item,
    /// considering factors such as server lease availability, file locking state, or other coherency requirements.
    ///
    /// The granted coherency type must be compatible with the requested cache mode, as defined
    /// by the cache mode to coherency type mappings documented in this protocol. If the module grants
    /// a coherency type that exceeds the cache mode's permissions, the kernel will use downgraded valid coherency type.
    ///
    /// - Parameters:
    ///   - item: The item to open.
    ///   - modes: The open modes (read, write, etc.).
    ///   - cacheMode: The requested cache mode indicating what data can be cached.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If opening succeeds, pass an instance of ``FSOpenItemResult`` containing the granted ``FSKernelCacheCoherencyType``, along with a `nil` error. If opening fails, pass the relevant error as the second parameter; FSKit ignores the ``FSOpenItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    @available(macOS 27.0, *)
    func open(_ item: FSItem, modes: FSVolume.OpenModes, cacheMode: FSVolume.DataCacheMode, context: FSContext, replyHandler reply: @escaping @Sendable (FSOpenItemResult?, (any Error)?) -> Void)

    /// Opens an item with cache mode negotiation.
    ///
    /// FSKit calls this method when a file is opened, providing the requested cache mode.
    /// Module implementation should determine what level of caching it can support for this item,
    /// considering factors such as server lease availability, file locking state, or other coherency requirements.
    ///
    /// The granted coherency type must be compatible with the requested cache mode, as defined
    /// by the cache mode to coherency type mappings documented in this protocol. If the module grants
    /// a coherency type that exceeds the cache mode's permissions, the kernel will use downgraded valid coherency type.
    ///
    /// - Parameters:
    ///   - item: The item to open.
    ///   - modes: The open modes (read, write, etc.).
    ///   - cacheMode: The requested cache mode indicating what data can be cached.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If opening succeeds, pass an instance of ``FSOpenItemResult`` containing the granted ``FSKernelCacheCoherencyType``, along with a `nil` error. If opening fails, pass the relevant error as the second parameter; FSKit ignores the ``FSOpenItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    @available(macOS 27.0, *)
    func open(_ item: FSItem, modes: FSVolume.OpenModes, cacheMode: FSVolume.DataCacheMode, context: FSContext) async throws -> FSOpenItemResult

    /// Closes an item and releases associated cache resources.
    ///
    /// FSKit calls this method when a file is being fully closed and all caching for the item
    /// has been finalized by the kernel.
    ///
    /// This method is called once per item when all references are released and the kernel
    /// has completed its cache management. The module should perform any necessary cleanup
    /// operations for the item.
    ///
    /// Note: This method has no error return because the OS considers the file closed regardless
    /// of whether the module encounters any issues during cleanup.
    ///
    /// - Parameters:
    ///   - item: The item to close.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to call when the close operation completes.
    @available(macOS 27.0, *)
    func close(_ item: FSItem, context: FSContext, replyHandler reply: @escaping @Sendable () -> Void)

    /// Closes an item and releases associated cache resources.
    ///
    /// FSKit calls this method when a file is being fully closed and all caching for the item
    /// has been finalized by the kernel.
    ///
    /// This method is called once per item when all references are released and the kernel
    /// has completed its cache management. The module should perform any necessary cleanup
    /// operations for the item.
    ///
    /// Note: This method has no error return because the OS considers the file closed regardless
    /// of whether the module encounters any issues during cleanup.
    ///
    /// - Parameters:
    ///   - item: The item to close.

Truncated.

public enum DataCacheMode : Int, @unchecked Sendable {

    /// No active caching.
    case none = 0

    /// Read access with caching enabled.
    case readWithCache = 1

    /// Read-write access with caching enabled.
    case readWriteWithCache = 2
}

public protocol Handler : FSVolume.PathConfOperations {

    var supportedVolumeCapabilities: FSVolume.SupportedCapabilities { get }

    /// A property that provides up-to-date statistics of the volume.
    var volumeStatistics: FSStatFSResult { get }

    /// A property that allows the file system to use open-unlink emulation.
    ///
    /// _Open-unlink_ functionality refers to a file system's ability to support an open file being fully unlinked from the file system namespace.
    /// If a file system doesn't support this functionality, FSKit can emulate it instead; this is called "open-unlink emulation".
    ///
    /// Implement this property to return `true` (Swift) or `YES` (Objective-C) to allow FSKit to perform open-unlink emulation.
    /// If you don't implement this property at all, FSKit doesn't perform open-unlink emulation for this volume.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var enableOpenUnlinkEmulation: Bool { get }

    /// A property that allows the file system to request for specific mount options from FSKit.
    ///
    /// FSKit reads this value after the volume replies to the ``mount(options:replyHandler:)`` call.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var requestedMountOptions: FSVolume.MountOptions { get }

    /// Activates the volume using the specified options.
    ///
    /// When FSKit calls this method, allocate any in-memory state required to represent the file system.
    /// Also allocate an ``FSItem`` for the root directory of the file system, and pass it to the reply block.
    /// FSKit caches this root item for the lifetime of the volume, and uses it as a starting point for all file look-ups.
    ///
    /// Volume activation occurs prior to any call to mount the volume.
    ///
    /// - Parameters:
    ///   - options: Options to apply to the activation. These can include security-scoped file paths. There are no defined options currently.
    ///   - reply: A block or closure to indicate success or failure. If activation succeeds, pass an instance of ``FSActivateResult`` containing the root ``FSItem``, along with a `nil` error. If activation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSActivateResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func activate(options: FSTaskOptions, replyHandler reply: @escaping @Sendable (FSActivateResult?, (any Error)?) -> Void)

    /// Activates the volume using the specified options.
    ///
    /// When FSKit calls this method, allocate any in-memory state required to represent the file system.
    /// Also allocate an ``FSItem`` for the root directory of the file system, and pass it to the reply block.
    /// FSKit caches this root item for the lifetime of the volume, and uses it as a starting point for all file look-ups.
    ///
    /// Volume activation occurs prior to any call to mount the volume.
    ///
    /// - Parameters:
    ///   - options: Options to apply to the activation. These can include security-scoped file paths. There are no defined options currently.
    ///   - reply: A block or closure to indicate success or failure. If activation succeeds, pass an instance of ``FSActivateResult`` containing the root ``FSItem``, along with a `nil` error. If activation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSActivateResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func activate(options: FSTaskOptions) async throws -> FSActivateResult

    /// Tears down a previously initialized volume instance.
    ///
    /// Set up your implementation to release any resources allocated for the volume instance.
    /// By the time you receive this callback, FSKit has already performed a reclaim call to release all other file nodes associated with this file system instance.
    ///
    /// Avoid performing any I/O in this method.
    /// Prior to calling this method, FSKit has already issued a sync call to perform any
    /// cleanup-related I/O.
    ///
    /// FSKit unmounts any mounted volume with a call to ``unmount(replyHandler:)`` prior to the deactivate callback.
    ///
    /// - Parameters:
    ///   - options: Options to apply to the deactivation.
    ///   - reply: A block or closure to indicate success or failure. If activation fails, pass an error as the one parameter to the reply handler. If activation succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
    func deactivate(options: FSDeactivateOptions = [], replyHandler reply: @escaping @Sendable ((any Error)?) -> Void)

    /// Tears down a previously initialized volume instance.
    ///
    /// Set up your implementation to release any resources allocated for the volume instance.
    /// By the time you receive this callback, FSKit has already performed a reclaim call to release all other file nodes associated with this file system instance.
    ///
    /// Avoid performing any I/O in this method.
    /// Prior to calling this method, FSKit has already issued a sync call to perform any
    /// cleanup-related I/O.
    ///
    /// FSKit unmounts any mounted volume with a call to ``unmount(replyHandler:)`` prior to the deactivate callback.
    ///
    /// - Parameters:
    ///   - options: Options to apply to the deactivation.

Truncated.

public protocol ItemDeactivationHandler : NSObjectProtocol {

    /// A property that tells FSKit to which types of items the deactivation applies, if any.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    var itemDeactivationPolicy: FSVolume.ItemDeactivationOptions { get }

    /// Notifies the file system that the kernel is no longer making immediate use of the given item.
    ///
    /// This method gives a file system a chance to release resources associated with an item.
    /// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Handler/reclaimItem(_:replyHandler:)``.
    /// This method is the equivalent of VFS's `VNOP_INACTIVE`.
    ///
    /// FSKit restricts calls to this method based on the current value of ``FSVolume/ItemDeactivation/itemDeactivationPolicy``.
    ///
    /// - Parameters:
    ///   - item: The item to deactivate.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If deactivation succeeds, pass an instance of ``FSDeactivateItemResult`` containing the volume's updated free space, along with a `nil` error. If deactivation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSDeactivateItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func deactivateItem(_ item: FSItem, context: FSContext, replyHandler reply: @escaping @Sendable (FSDeactivateItemResult?, (any Error)?) -> Void)

    /// Notifies the file system that the kernel is no longer making immediate use of the given item.
    ///
    /// This method gives a file system a chance to release resources associated with an item.
    /// However, this method prescribes no specific action; it's acceptable to defer all reclamation until ``FSVolume/Handler/reclaimItem(_:replyHandler:)``.
    /// This method is the equivalent of VFS's `VNOP_INACTIVE`.
    ///
    /// FSKit restricts calls to this method based on the current value of ``FSVolume/ItemDeactivation/itemDeactivationPolicy``.
    ///
    /// - Parameters:
    ///   - item: The item to deactivate.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If deactivation succeeds, pass an instance of ``FSDeactivateItemResult`` containing the volume's updated free space, along with a `nil` error. If deactivation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSDeactivateItemResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func deactivateItem(_ item: FSItem, context: FSContext) async throws -> FSDeactivateItemResult
}

public enum KernelCacheCoherencyAction : Int, @unchecked Sendable {

    /// Flush dirty data from cache to storage (preserves cache contents).
    case push = 0

    /// Flush dirty data to storage and invalidate (clear) the cache.
    case pushInvalidate = 1

    /// Invalidate (clear) cache, discarding any dirty data without writing to storage.
    case invalidate = 2

    /// Update coherency mode while keeping cache valid (no push/invalidate required).
    case update = 3

    /// Invalidate all caches, revoke all access to the item, and trigger vnode reclamation.
    ///
    /// This action should be used when the module determines that an item no longer exists or
    /// should no longer be accessible. Common scenarios include:
    /// - The item was deleted by another client (detected via server notification)
    /// - The module received a server callback indicating the file is gone
    case revoke = 4
}

public enum KernelCacheCoherencyType : Int, @unchecked Sendable {

    /// No caching - all I/O goes directly to storage.
    case noCache = 0

    /// Cache only reads, writes bypass cache and go directly to storage.
    case readCache = 1

    /// Write-through caching: writes update both cache and storage synchronously.
    case writeThrough = 2

    /// Write-back caching: writes update cache only, deferred write to storage.
    case writeBack = 3
}

public protocol KernelOffloadedIOHandler : NSObjectProtocol {

    /// Maps a file's disk space into extents, allowing the kernel to perform I/O with that space.
    ///
    /// FSKit calls this method when the kernel needs to get a mapping of logical-to-physical offsets of the file's data.
    /// This call may occur as part of an I/O operation on the file, or just to get the mapping as part of an `fcntl(F_LOG2PHYS)` system call.
    /// In the case of an I/O operation on the file, `operationID` has a nonzero value; a future call to ``completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)`` uses the same `operationID` to indicate which operation it completes.
    /// In the case of an `fcntl(F_LOG2PHYS)` system call, the `operationID` parameter is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
    /// In both cases the kernel retains the mapping, and it may perform I/O to this range (or a part of it) at any time.
    ///
    /// If satisfying a blockmap request requires more extents than `packer` can handle, FSKit makes additional calls to this method with the same operation ID to collect the remainder.
    ///
    /// - Parameters:
    ///   - file: The file for which to map disk space.
    ///   - offset: The starting logical offset of the range to be mapped (in bytes).
    ///   - length: The length of the range to be mapped (in bytes).
    ///   - flags: Flags that affect the behavior of the blockmap operation.
    ///   - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) indicates the beginning of an I/O operation. A value of `0` or ``FSOperationID/unspecified`` indicates the kernel maps the file without performing I/O. In this case, FSKit doesn't perform a corresponding call to ``completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)``.
    ///   - packer: An extent packer you use to pack the requested range of the file's allocated disk space. FSKit sends all of the packed extents to the kernel when it invokes `reply`.
    ///   - reply: A block or closure to indicate success or failure. If mapping succeeds, pass an instance of ``FSBlockmapResult`` containing the volume's updated free space, along with a `nil` error. If mapping fails, pass the relevant error as the second parameter; FSKit ignores the ``FSBlockmapResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func blockmapFile(_ file: FSItem, offset: off_t, length: Int, flags: FSBlockmapFlags, operationID: FSOperationID, packer: FSExtentPacker, replyHandler reply: @escaping @Sendable (FSBlockmapResult?, (any Error)?) -> Void)

    /// Maps a file's disk space into extents, allowing the kernel to perform I/O with that space.
    ///
    /// FSKit calls this method when the kernel needs to get a mapping of logical-to-physical offsets of the file's data.
    /// This call may occur as part of an I/O operation on the file, or just to get the mapping as part of an `fcntl(F_LOG2PHYS)` system call.
    /// In the case of an I/O operation on the file, `operationID` has a nonzero value; a future call to ``completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)`` uses the same `operationID` to indicate which operation it completes.
    /// In the case of an `fcntl(F_LOG2PHYS)` system call, the `operationID` parameter is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
    /// In both cases the kernel retains the mapping, and it may perform I/O to this range (or a part of it) at any time.
    ///
    /// If satisfying a blockmap request requires more extents than `packer` can handle, FSKit makes additional calls to this method with the same operation ID to collect the remainder.
    ///
    /// - Parameters:
    ///   - file: The file for which to map disk space.
    ///   - offset: The starting logical offset of the range to be mapped (in bytes).
    ///   - length: The length of the range to be mapped (in bytes).
    ///   - flags: Flags that affect the behavior of the blockmap operation.
    ///   - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) indicates the beginning of an I/O operation. A value of `0` or ``FSOperationID/unspecified`` indicates the kernel maps the file without performing I/O. In this case, FSKit doesn't perform a corresponding call to ``completeIO(for:offset:length:status:flags:operationID:providing:replyHandler:)``.
    ///   - packer: An extent packer you use to pack the requested range of the file's allocated disk space. FSKit sends all of the packed extents to the kernel when it invokes `reply`.
    ///   - reply: A block or closure to indicate success or failure. If mapping succeeds, pass an instance of ``FSBlockmapResult`` containing the volume's updated free space, along with a `nil` error. If mapping fails, pass the relevant error as the second parameter; FSKit ignores the ``FSBlockmapResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func blockmapFile(_ file: FSItem, offset: off_t, length: Int, flags: FSBlockmapFlags, operationID: FSOperationID, packer: FSExtentPacker) async throws -> FSBlockmapResult

    /// Completes an I/O operation for a given file.
    ///
    /// Implement this method by updating a file's metadata, such as its size and modification time.
    ///
    /// FSKit may call this method without an earlier call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
    /// In this case, the `operationID` is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
    ///
    /// - Parameters:
    ///   - file: The file for which the I/O operation completed.
    ///   - offset: The starting logical offset at which I/O started.
    ///   - length: The length of the I/O range (in bytes).
    ///   - status: Any error that occurred during the operation. If no error occurred, this parameter is `nil`.
    ///   - flags: Flags that affect the behavior of the complete I/O operation.
    ///   - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) corresponds to a previous call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)`` with the same `operationID`.
    ///   - attributes: The desired set of attributes to provide with the reply.
    ///   - reply: A block or closure to indicate success or failure. If completing I/O succeeds, pass an instance of ``FSCompleteIOResult`` containing the updated ``FSItemAttributes`` of the file, along with a `nil` error. If completing I/O fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCompleteIOResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func completeIO(for file: FSItem, offset: off_t, length: Int, status: any Error, flags: FSCompleteIOFlags, operationID: FSOperationID, replyHandler reply: @escaping @Sendable (FSCompleteIOResult?, (any Error)?) -> Void)

    /// Completes an I/O operation for a given file.
    ///
    /// Implement this method by updating a file's metadata, such as its size and modification time.
    ///
    /// FSKit may call this method without an earlier call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)``.
    /// In this case, the `operationID` is `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift).
    ///
    /// - Parameters:
    ///   - file: The file for which the I/O operation completed.
    ///   - offset: The starting logical offset at which I/O started.
    ///   - length: The length of the I/O range (in bytes).
    ///   - status: Any error that occurred during the operation. If no error occurred, this parameter is `nil`.
    ///   - flags: Flags that affect the behavior of the complete I/O operation.
    ///   - operationID: A unique identifier of the blockmap call. Any value other than `0` (Objective-C) or ``FSOperationID/unspecified`` (Swift) corresponds to a previous call to ``blockmapFile(_:offset:length:flags:operationID:packer:replyHandler:)`` with the same `operationID`.
    ///   - attributes: The desired set of attributes to provide with the reply.
    ///   - reply: A block or closure to indicate success or failure. If completing I/O succeeds, pass an instance of ``FSCompleteIOResult`` containing the updated ``FSItemAttributes`` of the file, along with a `nil` error. If completing I/O fails, pass the relevant error as the second parameter; FSKit ignores the ``FSCompleteIOResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func completeIO(for file: FSItem, offset: off_t, length: Int, status: any Error, flags: FSCompleteIOFlags, operationID: FSOperationID) async throws -> FSCompleteIOResult

    /// Creates a new file item and map its disk space.
    ///

Truncated.

public protocol OpenCloseHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var isOpenCloseInhibited: Bool { get }

    /// Opens a file for access.
    ///
    /// - Parameters:
    ///   - item: The item to open.
    ///   - modes: The set of mode flags to open the item with.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If opening fails, pass an error as the one parameter to the reply handler. If opening succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
    func openItem(_ item: FSItem, modes: FSVolume.OpenModes, context: FSContext, replyHandler reply: @escaping @Sendable ((any Error)?) -> Void)

    /// Opens a file for access.
    ///
    /// - Parameters:
    ///   - item: The item to open.
    ///   - modes: The set of mode flags to open the item with.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If opening fails, pass an error as the one parameter to the reply handler. If opening succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
    func openItem(_ item: FSItem, modes: FSVolume.OpenModes, context: FSContext) async throws

    /// Closes a file from further access.
    ///
    /// - Parameters:
    ///   - item: The item to close.
    ///   - modes: The set of mode flags to keep after this close.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If closing fails, pass an error as the one parameter to the reply handler. If closing succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
    func closeItem(_ item: FSItem, modes: FSVolume.OpenModes, context: FSContext, replyHandler reply: @escaping @Sendable ((any Error)?) -> Void)

    /// Closes a file from further access.
    ///
    /// - Parameters:
    ///   - item: The item to close.
    ///   - modes: The set of mode flags to keep after this close.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If closing fails, pass an error as the one parameter to the reply handler. If closing succeeds, pass `nil`. For an `async` Swift implementation, there's no reply handler; simply throw an error or return normally.
    func closeItem(_ item: FSItem, modes: FSVolume.OpenModes, context: FSContext) async throws
}

public protocol PreallocateHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var isPreallocateInhibited: Bool { get }

    /// Preallocates disk space for the given item.
    ///
    /// - Parameters:
    ///   - item: The item for which to preallocate space.
    ///   - offset: The offset from which to allocate.
    ///   - length: The length of the space in bytes.
    ///   - flags: Flags that affect the preallocation behavior.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If preallocation succeeds, pass an instance of ``FSPreallocateResult`` containing the amount of bytes allocated, the updated ``FSItemAttributes`` of the file and the volume's updated free space, along with a `nil` error. If preallocation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSPreallocateResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func preallocateSpace(for item: FSItem, at offset: off_t, length: Int, flags: FSVolume.PreallocateFlags, context: FSContext, replyHandler reply: @escaping @Sendable (FSPreallocateResult?, (any Error)?) -> Void)

    /// Preallocates disk space for the given item.
    ///
    /// - Parameters:
    ///   - item: The item for which to preallocate space.
    ///   - offset: The offset from which to allocate.
    ///   - length: The length of the space in bytes.
    ///   - flags: Flags that affect the preallocation behavior.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If preallocation succeeds, pass an instance of ``FSPreallocateResult`` containing the amount of bytes allocated, the updated ``FSItemAttributes`` of the file and the volume's updated free space, along with a `nil` error. If preallocation fails, pass the relevant error as the second parameter; FSKit ignores the ``FSPreallocateResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func preallocateSpace(for item: FSItem, at offset: off_t, length: Int, flags: FSVolume.PreallocateFlags, context: FSContext) async throws -> FSPreallocateResult
}

public protocol ReadWriteHandler : NSObjectProtocol {

    /// Reads the contents of the given file item.
    ///
    /// If the number of bytes requested exceeds the number of bytes available before the end of the file, then the call copies only those bytes to `buffer`.
    /// If `offset` points past the last valid byte of the file, don't reply with an error but set `actuallyRead` to `0`.
    ///
    /// - Parameters:
    ///   - item: The item from which to read. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
    ///   - offset: The offset in the file from which to start reading.
    ///   - length: The number of bytes to read.
    ///   - buffer: A buffer to receive the bytes read from the file.
    ///   - reply: A block or closure to indicate success or failure. If reading succeeds, pass an instance of ``FSReadFileResult`` containing the number of bytes read and the updated ``FSItemAttributes`` of the file, along with a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores the ``FSReadFileResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func read(from item: FSItem, at offset: off_t, length: Int, into buffer: FSMutableFileDataBuffer, replyHandler reply: @escaping @Sendable (FSReadFileResult?, (any Error)?) -> Void)

    /// Reads the contents of the given file item.
    ///
    /// If the number of bytes requested exceeds the number of bytes available before the end of the file, then the call copies only those bytes to `buffer`.
    /// If `offset` points past the last valid byte of the file, don't reply with an error but set `actuallyRead` to `0`.
    ///
    /// - Parameters:
    ///   - item: The item from which to read. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
    ///   - offset: The offset in the file from which to start reading.
    ///   - length: The number of bytes to read.
    ///   - buffer: A buffer to receive the bytes read from the file.
    ///   - reply: A block or closure to indicate success or failure. If reading succeeds, pass an instance of ``FSReadFileResult`` containing the number of bytes read and the updated ``FSItemAttributes`` of the file, along with a `nil` error. If reading fails, pass the relevant error as the second parameter; FSKit ignores the ``FSReadFileResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func read(from item: FSItem, at offset: off_t, length: Int, into buffer: FSMutableFileDataBuffer) async throws -> FSReadFileResult

    /// Writes contents to the given file item.
    ///
    /// FSKit expects this routine to allocate space in the file system to extend the file as necessary.
    ///
    /// If the volume experiences an out-of-space condition, reply with an error of domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and code `ENOSPC`.
    ///
    /// - Parameters:
    ///   - contents: A buffer containing the data to write to the file.
    ///   - item: The item to which to write. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
    ///   - offset: The offset in the file from which to start writing.
    ///   - reply: A block or closure to indicate success or failure. If writing succeeds, pass an instance of ``FSWriteFileResult`` containing the number of bytes written, the updated ``FSItemAttributes`` of the file, and the volume's updated free space, along with a `nil` error. If writing fails, pass the relevant error as the second parameter; FSKit ignores the ``FSWriteFileResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func write(contents: Data, to item: FSItem, at offset: off_t, replyHandler reply: @escaping @Sendable (FSWriteFileResult?, (any Error)?) -> Void)

    /// Writes contents to the given file item.
    ///
    /// FSKit expects this routine to allocate space in the file system to extend the file as necessary.
    ///
    /// If the volume experiences an out-of-space condition, reply with an error of domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain> and code `ENOSPC`.
    ///
    /// - Parameters:
    ///   - contents: A buffer containing the data to write to the file.
    ///   - item: The item to which to write. FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
    ///   - offset: The offset in the file from which to start writing.
    ///   - reply: A block or closure to indicate success or failure. If writing succeeds, pass an instance of ``FSWriteFileResult`` containing the number of bytes written, the updated ``FSItemAttributes`` of the file, and the volume's updated free space, along with a `nil` error. If writing fails, pass the relevant error as the second parameter; FSKit ignores the ``FSWriteFileResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func write(contents: Data, to item: FSItem, at offset: off_t) async throws -> FSWriteFileResult
}

public protocol RenameHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var isVolumeRenameInhibited: Bool { get }

    /// Sets a new name for the volume.
    ///
    /// - Parameters:
    ///   - name: The new volume name.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If renaming succeeds, pass an instance of ``FSVolumeRenameResult`` containing the ``FSFileName`` of the new volume name, along with a `nil` error. If renaming fails, pass the relevant error as the second parameter; FSKit ignores the ``FSVolumeRenameResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func setVolumeName(_ name: FSFileName, context: FSContext, replyHandler reply: @escaping @Sendable (FSVolumeRenameResult?, (any Error)?) -> Void)

    /// Sets a new name for the volume.
    ///
    /// - Parameters:
    ///   - name: The new volume name.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If renaming succeeds, pass an instance of ``FSVolumeRenameResult`` containing the ``FSFileName`` of the new volume name, along with a `nil` error. If renaming fails, pass the relevant error as the second parameter; FSKit ignores the ``FSVolumeRenameResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func setVolumeName(_ name: FSFileName, context: FSContext) async throws -> FSVolumeRenameResult
}

public enum SeekRegion : UInt, @unchecked Sendable {

    /// Seek the next hole region.
    ///
    /// When there are no more hole regions past the supplied `offset`,
    /// the current file size (end-of-file offset) should be returned.
    case hole = 1

    /// Seek the next data region.
    ///
    /// When there are no more data regions past the supplied `offset`,
    /// an error code `ENXIO` should be returned.
    case data = 2
}

public protocol SeekRegionHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var isSeekRegionInhibited: Bool { get }

    /// Find the next offset of hole or data region greater than or equal to the
    /// supplied offset
    ///
    /// - Parameters:
    ///   - item: The item for which to seek.
    ///   - offset: The offset from which to seek.
    ///   - region: The region to seek.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If seek succeeds, pass an instance of ``FSSeekRegionResult`` containing the offset of the requested region greater than or equal to the supplied offset, along with a `nil` error. If seek fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSeekRegionResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func seek(within item: FSItem, from offset: off_t, region: FSVolume.SeekRegion, context: FSContext, replyHandler reply: @escaping @Sendable (FSSeekRegionResult?, (any Error)?) -> Void)

    /// Find the next offset of hole or data region greater than or equal to the
    /// supplied offset
    ///
    /// - Parameters:
    ///   - item: The item for which to seek.
    ///   - offset: The offset from which to seek.
    ///   - region: The region to seek.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If seek succeeds, pass an instance of ``FSSeekRegionResult`` containing the offset of the requested region greater than or equal to the supplied offset, along with a `nil` error. If seek fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSeekRegionResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func seek(within item: FSItem, from offset: off_t, region: FSVolume.SeekRegion, context: FSContext) async throws -> FSSeekRegionResult
}

public protocol XattrHandler : NSObjectProtocol {

    /// A Boolean value that instructs FSKit not to call this protocol's methods, even if the volume conforms to it.
    ///
    /// FSKit reads this value after the file system replies to the `loadResource` message.
    /// Changing the returned value during the runtime of the volume has no effect.
    optional var xattrOperationsInhibited: Bool { get }

    /// Returns an array that specifies the extended attribute names the given item supports.
    ///
    /// If `item` supports no extended attributes, this method returns `nil`.
    ///
    /// Only implement this method if your volume works with "limited" extended attributes.
    /// For purposes of this protocol, "limited" support means the volume doesn't support extended attributes generally, but uses these APIs to expose specific file system data.
    ///
    /// > Note: If a file system implements this method, FSKit assumes limited support for extended attributes exists. In this mode, FSkit only calls this protocol's methods for the extended attribute names this method returns.
    ///
    /// - Parameter item: The item for which to get information.
    optional func supportedXattrNames(for item: FSItem) -> [FSFileName]

    /// Gets the specified extended attribute of the given item.
    ///
    /// - Parameters:
    ///   - name: The extended attribute name.
    ///   - item: The item for which to get the extended attribute.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If getting the attribute succeeds, pass an instance of ``FSGetXattrResult`` containing the extended attribute data, along with a `nil` error. If getting the attribute fails, pass the relevant error as the second parameter; FSKit ignores the ``FSGetXattrResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func getXattr(named name: FSFileName, of item: FSItem, context: FSContext, replyHandler reply: @escaping @Sendable (FSGetXattrResult?, (any Error)?) -> Void)

    /// Gets the specified extended attribute of the given item.
    ///
    /// - Parameters:
    ///   - name: The extended attribute name.
    ///   - item: The item for which to get the extended attribute.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If getting the attribute succeeds, pass an instance of ``FSGetXattrResult`` containing the extended attribute data, along with a `nil` error. If getting the attribute fails, pass the relevant error as the second parameter; FSKit ignores the ``FSGetXattrResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func xattr(named name: FSFileName, of item: FSItem, context: FSContext) async throws -> FSGetXattrResult

    /// Sets the specified extended attribute data on the given item.
    ///
    /// - Parameters:
    ///   - name: The extended attribute name.
    ///   - value: The extended attribute value to set. This can't be `nil`, unless the policy is ``FSVolume/SetXattrPolicy/delete``.
    ///   - item: The item on which to set the extended attribute.
    ///   - policy: The policy to apply when setting the attribute. See ``FSSetXattrPolicy`` for possible values.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If setting the attribute succeeds, pass an instance of ``FSSetXattrResult`` containing the volume's updated free space, along with a `nil` error. If setting the attribute fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSetXattrResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func setXattr(named name: FSFileName, to value: Data?, on item: FSItem, policy: FSVolume.SetXattrPolicy, context: FSContext, replyHandler reply: @escaping @Sendable (FSSetXattrResult?, (any Error)?) -> Void)

    /// Sets the specified extended attribute data on the given item.
    ///
    /// - Parameters:
    ///   - name: The extended attribute name.
    ///   - value: The extended attribute value to set. This can't be `nil`, unless the policy is ``FSVolume/SetXattrPolicy/delete``.
    ///   - item: The item on which to set the extended attribute.
    ///   - policy: The policy to apply when setting the attribute. See ``FSSetXattrPolicy`` for possible values.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If setting the attribute succeeds, pass an instance of ``FSSetXattrResult`` containing the volume's updated free space, along with a `nil` error. If setting the attribute fails, pass the relevant error as the second parameter; FSKit ignores the ``FSSetXattrResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func setXattr(named name: FSFileName, to value: Data?, on item: FSItem, policy: FSVolume.SetXattrPolicy, context: FSContext) async throws -> FSSetXattrResult

    /// Gets the list of extended attributes currently set on the given item.
    ///
    /// - Parameters:
    ///   - item: The item from which to get extended attributes.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If getting the list of extended attributes succeeds, pass an instance of ``FSListXattrsResult`` containing the xattrs as an array of ``FSFileName`` instances, along with a `nil` error. If getting the attributes fails, pass the relevant error as the second parameter; FSKit ignores the ``FSListXattrsResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func listXattrs(of item: FSItem, context: FSContext, replyHandler reply: @escaping @Sendable (FSListXattrsResult?, (any Error)?) -> Void)

    /// Gets the list of extended attributes currently set on the given item.
    ///
    /// - Parameters:
    ///   - item: The item from which to get extended attributes.
    ///   - context: An object that enables context-aware file system decisions throughout the operation.
    ///   - reply: A block or closure to indicate success or failure. If getting the list of extended attributes succeeds, pass an instance of ``FSListXattrsResult`` containing the xattrs as an array of ``FSFileName`` instances, along with a `nil` error. If getting the attributes fails, pass the relevant error as the second parameter; FSKit ignores the ``FSListXattrsResult`` instance in this case. For an `async` Swift implementation, there's no reply handler; simply return the result instance or throw an error.
    func xattrs(of item: FSItem, context: FSContext) async throws -> FSListXattrsResult
}