Replace panic with error returns in macOS kqueue backend for unsupported features

[Copilot]

The kqueue backend panicked when using event types or config flags unsupported by macOS (peer_hangup, error, hangup events; wake_up, exclusive flags), making cross-platform code fragile.

Changes

Error Handling

• Modified filter_to_mask() and flags_to_mask() to return Result types instead of panicking
• Unsupported features now return descriptive errors: error("kqueue does not support 'peer_hangup' event type")

Testing

• Added 3 macOS-specific tests validating error behavior for unsupported event types and config flags
• Added multi-fd test for macOS
• Improved test documentation with function-level comments

Documentation

• Created README.md with platform support matrix and usage guidelines
• Created EXAMPLES.md demonstrating cross-platform error handling patterns
• Added module-level documentation to both backends

Example

// Before: would panic on macOS
notifier.add(fd, .peer_hangup)!

// After: returns error on macOS, allowing graceful handling
notifier.add(fd, .peer_hangup) or {
    eprintln('peer_hangup not supported: ${err}')
    // Fall back to supported features
    notifier.add(fd, .read)!
}

All existing tests pass. No breaking changes to public API.

Original prompt

Improve the tests and make vlib/os/notify fully supported on macOS.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.