Request for maintainer guidance before contributing fs-watcher (domain rules, sources, scaffolding)

[RavenLiao]

Hi maintainers,

I’d like to contribute the roadmap fs-watcher item, but before proposing implementation details, I want to align with your domain-level expectations.

Could you guide me on the following?

1. Trusted information sources

• Which official docs/specs should be treated as primary references per platform?
• Are there existing projects/references you consider good quality for behavior comparison?

2. Product/domain rules

• What are the most important behavior guarantees for Nucleus users?
• What are explicit non-goals for v1 (to avoid overbuilding)?

3. Contribution rules

• Any design principles, review standards, or acceptance rules specific to native modules?
• Any compatibility policy I should follow (platform support, edge cases, long-term maintenance)?

4. Scaffolding expectations

• Do you prefer a standard module scaffold/template for new native features?
• Is there a preferred baseline for tests, benchmarks, examples, and docs structure?

5. Suggested first milestone

• What is the smallest useful contribution you’d like to see first (so I can start with the right scope)?

I’m asking because my own software also involves this domain, and I’d like to contribute in a way that fits your architecture and maintenance style from day one.

Thanks for your guidance.

[RavenLiao]

@kdroidFilter

[kdroidFilter]

Hi, and thanks a lot for your interest in the project!

Let me try to answer point by point:

1) Sources and references

As a general rule, I prefer dynamic libraries to be written in C for Linux, C or C++ for Windows, and Objective-C for macOS — these languages produce the smallest binaries. That said, the rule isn't absolute: for Nucleus v2.0, which introduces a new backend, I'm relying on the Tao backend in Rust. So the rule is rather: if it's simple enough to implement, I prefer a rewrite in C/C++/Objective-C; otherwise, Rust is acceptable provided there's already a mature ecosystem.

I haven't really looked into fs-watcher yet, but at first glance I'd start by studying the [notify](https://crates.io/crates/notify) crate — it does exactly what we need and is battle-tested. If a native rewrite turns out to be too complex, I'll just add a JNI layer on top of this crate.

2) Important contribution rule

As you can see in the other modules, every bridge must use JNI — no JNA, no FFM.

3) Testing

When automated e2e tests are feasible, they're obviously preferred. But for most Nucleus modules, writing this kind of test would be extremely complex. I'd rather add a tab in the demo app. Nucleus separates its modules in a very modular way, so once we've verified that something works, there's no real reason for a change in another module to affect it. When updating code, you do need to check the behavior on Windows, macOS, and Linux — sorry, it's still very manual for now!

4) First milestone

I'd suggest a JNI binding of the notify crate, with an addition to the basic example. That'll let us validate the approach before going further.

Feel free to ask if you have any other questions!

[RavenLiao]

Thanks, that direction makes sense to me. I did some research around the watcher API shape and the existing native integration pattern in Nucleus, and I think the public API can stay fairly small while still leaving room for the native backend to use richer platform details internally.

My current API proposal would look roughly like this:

import java.nio.file.Path
import java.time.Duration
import kotlinx.coroutines.flow.Flow

data class FsWatchSource(
    val root: Path,
    val recursive: Boolean,
    // Optional user-facing label for logs, UI, or grouping.
    // Keep this as String instead of Any? to avoid the watcher strongly retaining arbitrary user objects.
    val name: String? = null,
)

sealed interface FsWatchEvent {
    // Identifies which watch registration produced this event.
    // Null means the backend can only say that the whole watcher is no longer fully trustworthy.
    val source: FsWatchSource?

    // This should be part of the first public model because native watchers can lose,
    // merge, or coalesce events. When true, callers should rescan the relevant source.
    val needsRescan: Boolean

    data class Created(
        val path: Path,
        override val source: FsWatchSource? = null,
        val isDirectory: Boolean? = null,
        override val needsRescan: Boolean = false,
    ) : FsWatchEvent

    data class Modified(
        val path: Path,
        override val source: FsWatchSource? = null,
        val isDirectory: Boolean? = null,
        override val needsRescan: Boolean = false,
    ) : FsWatchEvent

    data class Removed(
        val path: Path,
        override val source: FsWatchSource? = null,
        val isDirectory: Boolean? = null,
        override val needsRescan: Boolean = false,
    ) : FsWatchEvent

    data class Moved(
        val from: Path,
        val to: Path,
        override val source: FsWatchSource? = null,
        val isDirectory: Boolean? = null,
        override val needsRescan: Boolean = false,
    ) : FsWatchEvent

    data class Accessed(
        val path: Path,
        override val source: FsWatchSource? = null,
        val isDirectory: Boolean? = null,
        override val needsRescan: Boolean = false,
    ) : FsWatchEvent

    data class Overflow(
        override val source: FsWatchSource? = null,
        override val needsRescan: Boolean = true,
    ) : FsWatchEvent

    data class Other(
        val paths: List<Path> = emptyList(),
        override val source: FsWatchSource? = null,
        val isDirectory: Boolean? = null,
        override val needsRescan: Boolean = false,
    ) : FsWatchEvent
}

sealed interface FsWatchBackendStrategy {
    // Default strategy: use the recommended native watcher backend for the current platform.
    data object Auto : FsWatchBackendStrategy

    // Useful when users prefer a hard failure instead of silently falling back to polling.
    data object NativeOnly : FsWatchBackendStrategy

    // Polling is slower, but more conservative for network filesystems, WSL, containers,
    // or special mount points.
    data class Polling(
        val interval: Duration = Duration.ofSeconds(2),
        val compareContents: Boolean = false,
    ) : FsWatchBackendStrategy
}

data class FsWatcherConfig(
    // Default false avoids unexpectedly expanding recursive watches through symlinks.
    // It also reduces symlink-cycle, duplicate-event, and unclear-root-semantics issues.
    // Users who explicitly want to watch symlink targets can opt in.
    val followSymlinks: Boolean = false,
    val backend: FsWatchBackendStrategy = FsWatchBackendStrategy.Auto,
)

data class FsWatchError(
    val message: String,
    val source: FsWatchSource? = null,
    val recoverable: Boolean = false,
    val cause: Throwable? = null,
)

class FsWatchException(
    message: String,
    cause: Throwable? = null,
) : RuntimeException(message, cause)

interface FsWatchRegistration : AutoCloseable {
    val source: FsWatchSource
    val active: Boolean

    // Close only this watched root.
    override fun close()
}

interface FsWatcher : AutoCloseable {
    val registrations: Set<FsWatchSource>

    // File system events produced by this watcher.
    val events: Flow<FsWatchEvent>

    // Asynchronous backend errors, separate from synchronous watch(...) failures.
    val errors: Flow<FsWatchError>

    // Return a registration instead of Boolean so callers get a clear lifecycle handle.
    // Registration failure should throw FsWatchException with a useful message/cause.
    fun watch(
        path: Path,
        recursive: Boolean = true,
        name: String? = null,
    ): FsWatchRegistration

    // Close the whole watcher and all active registrations.
    override fun close()
}

object FsWatchers {
    fun create(
        config: FsWatcherConfig = FsWatcherConfig(),
    ): FsWatcher

    fun isSupported(config: FsWatcherConfig = FsWatcherConfig()): Boolean
}

For event semantics, I would keep the first version conservative:

• Created, Modified, Removed, and Overflow would be the stable core events.
• Moved should only be emitted when the backend can reliably pair source and target. Callers should still tolerate the same operation being reported as Removed + Created, especially on platforms or filesystems where rename pairing is not reliable.
• Accessed should be documented as best-effort. If we want an even smaller v1 surface, it can also be postponed.
• isDirectory should stay nullable because not every backend/event can provide that hint reliably.
• source = null means the watcher-level state is no longer fully trustworthy, so callers should rescan all current registrations.
• Path semantics should be explicitly documented: source.root should stay stable, displayable, and comparable, and event paths should use the same path style as much as possible. Symlink resolution should follow followSymlinks; normalization should not silently turn every path into toRealPath().
• With followSymlinks = false by default, recursive watches stay more conservative. The tradeoff is that symlink targets are not watched automatically unless users opt in, but it avoids accidentally leaving the original root, duplicate watches/events, symlink cycles, and unclear source semantics.

For the implementation, I would follow the native integration pattern already proven by decorated-window-tao: Kotlin public API plus an internal bridge, a Rust cdylib exporting JNI symbols, native binaries packaged as JAR resources, and GraalVM metadata.

I do not think fs-watcher needs to copy Tao's internal business structure. It can stay much smaller and only keep the pieces needed for watcher lifecycle, registrations, event mapping, and callback dispatch:

Kotlin public API
  -> Kotlin internal NativeFsWatcherBridge
  -> Rust cdylib
  -> notify

Internally, nativeWatch(...) can return a registrationId. Kotlin can keep a registrationId -> FsWatchSource map, while Rust callbacks only pass compact internal data:

handle
registrationId
eventKind
path
secondaryPath
needsRescan
isDirectory

Then the Kotlin bridge maps that into the public FsWatchEvent model and pushes it into the events / errors flows. This keeps both native handles and notify event structures out of the user-facing API.

For the first basic example/demo milestone, I would keep it small but useful for cross-platform validation:

• choose a directory
• toggle recursive watching
• choose backend strategy
• optional source name
• start / stop
• event log showing source, event type, path, and needsRescan
• native library load status

The first manual validation pass could cover:

• create
• modify
• remove
• rename/move
• recursive child events
• close stops callbacks
• native backend load failure reports a useful error

Implementation-wise, I would split this into small PRs:

1. Add the fs-watcher module skeleton and native build skeleton.
2. Add the minimal JNI bridge: load / create / close.
3. Integrate notify and implement watch / registration / callback.
4. Add the public Kotlin API and basic event mapping.
5. Add the basic example/demo validation for Windows, macOS, and Linux.
6. Finish CI artifacts, GraalVM metadata, docs, and troubleshooting.

Before starting implementation, the main things I would like to confirm are:

• Is this API direction acceptable, especially FsWatchRegistration, FsWatchSource, and Flow<FsWatchEvent>?
• Are the v1 tradeoffs around Moved, Accessed, Polling(...), and followSymlinks = false reasonable?
• Is it OK to follow the decorated-window-tao native integration style and use the basic example/demo as the first validation milestone?