Deliver an event enum with the queue overflow as its own case

The stream's element is now the enum InotifyEvent, and the struct that
describes a change to a watched item is FileSystemEvent. A queue
overflow was an event with descriptor -1 and an empty path that every
consumer had to know about; as a case, the compiler makes them handle
it. The enum is also where failed watches of a growing tree will be
reported, since no call site can catch them.

Sources/Inotify/Inotify.docc/Inotify.md

@@ -4,14 +4,19 @@ Monitor filesystem events on Linux using modern Swift concurrency.
 
 ## Overview
 
-The Inotify library wraps the Linux [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) API in a Swift-native interface built around actors and async sequences. You create an ``Inotify/Inotify`` actor, add watches for the paths you care about, and iterate over the ``Inotify/Inotify/events`` property to receive ``InotifyEvent`` values as they occur.
+The Inotify library wraps the Linux [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) API in a Swift-native interface built around actors and async sequences. You create an ``Inotify/Inotify`` actor, add watches for the paths you care about, and iterate over the ``Inotify/Inotify/events`` property to receive ``InotifyEvent`` values as they occur. Most of them carry a ``FileSystemEvent`` describing a change to a watched item; the others tell you when the instance cannot deliver every change, such as after a kernel queue overflow.
 
 ```swift
 let inotify = try Inotify()
 try inotify.addWatch(path: "/tmp/inbox", mask: [.create, .modify])
 
 for await event in await inotify.events {
-    print("\(event.mask) at \(event.path)")
+    switch event {
+    case .fileSystem(let change):
+        print("\(change.mask) at \(change.path)")
+    case .queueOverflow:
+        print("events were dropped, rescan")
+    }
 }
 ```
 
@@ -30,6 +35,7 @@ All public types conform to `Sendable`, so they can be safely passed across conc
 
 - ``Inotify/Inotify``
 - ``InotifyEvent``
+- ``FileSystemEvent``
 - ``InotifyEventMask``
 
 ### Articles

Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md

@@ -31,7 +31,7 @@ let descriptors = try await inotify.addWatchWithAutomaticSubtreeWatching(
 )
 ```
 
-Internally this listens for `CREATE` and `MOVED_TO` events carrying the ``InotifyEventMask/isDir`` flag and installs new watches with the same mask on the subdirectory and its subtree whenever one appears. Items that already exist inside such a subdirectory are reported with ``InotifyEvent/synthesized`` set to `true`, since the kernel never produces events for them; a synthesized event may duplicate a kernel event for the same item.
+Internally this listens for `CREATE` and `MOVED_TO` events carrying the ``InotifyEventMask/isDir`` flag and installs new watches with the same mask on the subdirectory and its subtree whenever one appears. Items that already exist inside such a subdirectory are reported with ``FileSystemEvent/synthesized`` set to `true`, since the kernel never produces events for them; a synthesized event may duplicate a kernel event for the same item.
 
 When a directory is moved out of the watched tree, the watches on it and on its subdirectories are removed, so no events are reported under the stale path.