winwatch 0.1.0

data/ext/winwatch/winwatch.c

@@ -0,0 +1,883 @@
+/*
+ * winwatch — a ReadDirectoryChangesW directory watcher for Ruby.
+ *
+ * PURE C (no C++), so rb_raise/longjmp is the normal, safe error mechanism —
+ * the same discipline as winipc/winloop, and the opposite of the lithos /EHsc
+ * hazard. The directory handle, its OVERLAPPED, manual-reset event and the
+ * completion buffer live in a TypedData wrapper whose free hook tears them down,
+ * so a forgotten #close never leaks a HANDLE or a buffer. The one blocking call
+ * (WaitForSingleObject on the overlapped event) releases the GVL with a real
+ * per-op cancel unblock function (CancelIoEx on THIS op), so other Ruby threads
+ * run and Thread#kill / Ctrl-C / Timeout break an INFINITE wait.
+ *
+ * The watcher thread (the no-GVL wait) touches ONLY plain C state — never the
+ * Ruby C-API. Everything that allocates Ruby objects (the batch String, the
+ * parsed Event array, path joins) happens with the GVL held, after the wait has
+ * returned. The OVERLAPPED/buffer are only ever freed when no op is in flight
+ * (a reaped completion, or a cancel followed by a settling GetOverlappedResult).
+ *
+ * The kernel mirror buffer is sized at the FIRST ReadDirectoryChangesW and kept
+ * for the handle's lifetime; it accumulates changes between our calls, so the
+ * pull design is lossless across take() gaps (overflow becomes :rescan, never a
+ * silent drop). See plans/research/rdcw.md and plans/winwatch-spec.md.
+ *
+ * Links kernel32 only (linked by default): CreateFileW / ReadDirectoryChangesW /
+ * CancelIoEx / WaitForSingleObject / GetOverlappedResult / GetLongPathNameW.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+#include <stdlib.h>
+#include <string.h>
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mWinwatch;
+static VALUE cWatcher;
+static VALUE eError, eOSError, eNotFound, eAccessDenied, eUnsupported,
+             eNotADirectory, eClosed;
+
+/* FILE_ACTION_* values (winnt.h) — re-stated for clarity (rdcw §3). */
+#ifndef FILE_ACTION_ADDED
+# define FILE_ACTION_ADDED            0x00000001
+# define FILE_ACTION_REMOVED          0x00000002
+# define FILE_ACTION_MODIFIED         0x00000003
+# define FILE_ACTION_RENAMED_OLD_NAME 0x00000004
+# define FILE_ACTION_RENAMED_NEW_NAME 0x00000005
+#endif
+
+/* ------------------------------------------------------------ small helpers */
+
+/* Build + raise a winwatch error carrying @code (the Win32 error). The code
+ * must be captured by the caller immediately after the failing syscall, and any
+ * OS allocation released BEFORE this is called (so an OOM longjmp from
+ * rb_sprintf / rb_exc_new_str cannot leak it). Verbatim winipc raise_code. */
+static void
+raise_code(VALUE klass, const char *api, DWORD code)
+{
+    VALUE exc, msg;
+    WCHAR *buf = NULL;
+    char detail[512];
+    DWORD n;
+
+    detail[0] = 0;
+    n = FormatMessageW(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM |
+                       FORMAT_MESSAGE_IGNORE_INSERTS, NULL, code,
+                       MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPWSTR)&buf, 0, NULL);
+    if (n && buf) {
+        while (n && (buf[n - 1] == L'\r' || buf[n - 1] == L'\n' || buf[n - 1] == L'.'))
+            buf[--n] = 0;
+        WideCharToMultiByte(CP_UTF8, 0, buf, -1, detail, (int)sizeof(detail), NULL, NULL);
+        detail[sizeof(detail) - 1] = 0;
+    }
+    if (buf) LocalFree(buf);
+
+    if (detail[0])
+        msg = rb_sprintf("%s: %s (error %lu)", api, detail, (unsigned long)code);
+    else
+        msg = rb_sprintf("%s failed (error %lu)", api, (unsigned long)code);
+    exc = rb_exc_new_str(klass, msg);
+    rb_iv_set(exc, "@code", ULONG2NUM(code));
+    rb_exc_raise(exc);
+}
+
+/* Map an open-time / first-arm Win32 error to the right winwatch subclass and
+ * raise (§3.7 / §5.0 open-time mapping). */
+static void
+raise_gle(const char *api, DWORD code)
+{
+    VALUE klass = eOSError;
+    switch (code) {
+        case ERROR_FILE_NOT_FOUND:  /* 2 */
+        case ERROR_PATH_NOT_FOUND:  /* 3 */  klass = eNotFound;     break;
+        case ERROR_ACCESS_DENIED:   /* 5 */  klass = eAccessDenied; break;
+        case ERROR_INVALID_FUNCTION:/* 1 */  klass = eUnsupported;  break;
+        default: break;
+    }
+    raise_code(klass, api, code);
+}
+
+/* =====================================================================
+ * Watcher — Winwatch::Watcher
+ * ===================================================================== */
+
+typedef struct {
+    HANDLE dir;            /* CreateFileW directory handle; INVALID_HANDLE_VALUE sentinel */
+    HANDLE ev;             /* manual-reset event = ov.hEvent (standalone; NULL in :winloop) */
+    OVERLAPPED ov;         /* the single in-flight RDCW (standalone mode)                  */
+    unsigned char *buf;    /* malloc'd completion buffer, buf_len bytes (standalone mode)  */
+    DWORD buf_len;
+    DWORD filter;          /* dwNotifyFilter, precomputed in Ruby                          */
+    BOOL  recursive;
+    int   external;        /* 1 = :winloop mode (no ev/buf/ov of our own)                  */
+    int   armed;           /* an RDCW we issued on &ov is in flight (standalone)           */
+    int   in_take;         /* threads inside _take's wait path; touched only with the GVL  */
+                           /* held (inc before release, dec after reacquire), so close     */
+                           /* reads it race-free — deferred teardown (§3.5 rule 3)         */
+    int   closed;
+    /* interrupt-race stash (§5.12): a completed batch drained during an interrupt */
+    unsigned char *stash;  DWORD stash_len; DWORD stash_code;
+} watch_t;
+
+/* Free buf/stash and zero the pointers (idempotent). */
+static void
+watch_free_bufs(watch_t *w)
+{
+    if (w->buf)   { free(w->buf);   w->buf = NULL; }
+    if (w->stash) { free(w->stash); w->stash = NULL; }
+    w->stash_len = 0;
+    w->stash_code = 0;
+}
+
+/* The teardown tail: settle a cancelled op, close handles, free buffers.
+ * Runs from close (when no taker is mid-wait), from the last leaver of _take,
+ * and from the GC free hook. Idempotent and tolerant of never-initialized
+ * sentinels. NO Ruby C-API here (it also runs in the free hook). */
+static void
+watch_teardown(watch_t *w)
+{
+    /* Settle a cancelled/in-flight op before freeing its OVERLAPPED + buffer:
+     * completions for cancelled ops still arrive and freeing early is
+     * use-after-free (rdcw §13). Prompt by construction: a cancel was already
+     * issued (close/free path) or the op completed normally. Standalone only —
+     * in :winloop mode winloop owns the OVERLAPPED/buffer (wlx §3.4 rule 1). */
+    if (!w->external && w->armed && w->dir != INVALID_HANDLE_VALUE) {
+        DWORD n = 0;
+        GetOverlappedResult(w->dir, &w->ov, &n, TRUE);
+        w->armed = 0;
+    }
+    if (w->ev)  { CloseHandle(w->ev);  w->ev = NULL; }
+    if (w->dir != INVALID_HANDLE_VALUE) { CloseHandle(w->dir); w->dir = INVALID_HANDLE_VALUE; }
+    watch_free_bufs(w);
+}
+
+static void
+watch_dfree(void *p)
+{
+    watch_t *w = (watch_t *)p;
+    /* GC implies no thread is inside _take. Run the identical teardown the API
+     * uses (cancel already issued by close, or cancel now if still armed). */
+    if (!w->external && w->armed && w->dir != INVALID_HANDLE_VALUE)
+        CancelIoEx(w->dir, &w->ov);
+    watch_teardown(w);
+    xfree(w);
+}
+
+static size_t
+watch_dsize(const void *p)
+{
+    const watch_t *w = (const watch_t *)p;
+    return sizeof(watch_t) + (size_t)w->buf_len + (size_t)w->stash_len;
+}
+
+static const rb_data_type_t watch_type = {
+    "Winwatch::Watcher",
+    { 0, watch_dfree, watch_dsize, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+watch_alloc(VALUE klass)
+{
+    watch_t *w;
+    VALUE obj = TypedData_Make_Struct(klass, watch_t, &watch_type, w);
+    w->dir = INVALID_HANDLE_VALUE;
+    w->ev = NULL;
+    memset(&w->ov, 0, sizeof(w->ov));
+    w->buf = NULL;
+    w->buf_len = 0;
+    w->filter = 0;
+    w->recursive = FALSE;
+    w->external = 0;
+    w->armed = 0;
+    w->in_take = 0;
+    w->closed = 0;
+    w->stash = NULL;
+    w->stash_len = 0;
+    w->stash_code = 0;
+    return obj;
+}
+
+/* Raw getter (used by closed?/close — must work on closed objects). */
+static watch_t *
+watch_get(VALUE self)
+{
+    watch_t *w;
+    TypedData_Get_Struct(self, watch_t, &watch_type, w);
+    return w;
+}
+
+/* Live getter — raises Winwatch::Closed when closed. */
+static watch_t *
+watch_live(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    if (w->closed || w->dir == INVALID_HANDLE_VALUE)
+        rb_raise(eClosed, "winwatch: watcher is closed");
+    return w;
+}
+
+/* --- UTF-8 path -> extended-length wide path ready for CreateFileW ---------
+ *
+ * Flips '/'->'\\' and prepends \\?\ (or \\?\UNC\ for \\server\share), so long
+ * roots survive (rdcw §2). Returns a freshly malloc'd NUL-terminated WCHAR*;
+ * caller frees with free(). Raises on invalid UTF-8 (no OS state held yet). */
+static WCHAR *
+to_ext_wide(VALUE str)
+{
+    int len, n, i;
+    WCHAR *raw, *out;
+    size_t prefix, total;
+    const WCHAR *pfx;
+    int is_unc;
+
+    StringValue(str);
+    len = (int)RSTRING_LEN(str);
+    if (len == 0) rb_raise(rb_eArgError, "winwatch: path must not be empty");
+
+    n = MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, NULL, 0);
+    if (n <= 0) rb_raise(eError, "winwatch: invalid UTF-8 in path");
+    raw = (WCHAR *)malloc(sizeof(WCHAR) * ((size_t)n + 1));
+    if (!raw) rb_raise(rb_eNoMemError, "winwatch: out of memory");
+    MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, raw, n);
+    raw[n] = 0;
+
+    /* normalize separators to backslash */
+    for (i = 0; i < n; i++) if (raw[i] == L'/') raw[i] = L'\\';
+
+    /* UNC if it starts with two backslashes (\\server\share). */
+    is_unc = (n >= 2 && raw[0] == L'\\' && raw[1] == L'\\');
+    if (is_unc) { pfx = L"\\\\?\\UNC\\"; prefix = 8; }
+    else        { pfx = L"\\\\?\\";      prefix = 4; }
+
+    /* For UNC we skip the leading "\\" of the raw path (the prefix supplies it). */
+    {
+        int skip = is_unc ? 2 : 0;
+        size_t body = (size_t)(n - skip);
+        total = prefix + body + 1;
+        out = (WCHAR *)malloc(sizeof(WCHAR) * total);
+        if (!out) { free(raw); rb_raise(rb_eNoMemError, "winwatch: out of memory"); }
+        memcpy(out, pfx, prefix * sizeof(WCHAR));
+        memcpy(out + prefix, raw + skip, body * sizeof(WCHAR));
+        out[prefix + body] = 0;
+    }
+    free(raw);
+    return out;
+}
+
+/* Issue one ReadDirectoryChangesW on &w->ov. GVL held; the call only queues.
+ * Returns 0 on success (op queued), else GetLastError, captured immediately. */
+static DWORD
+watch_arm(watch_t *w)
+{
+    BOOL ok;
+    DWORD gle;
+
+    ResetEvent(w->ev);
+    memset(&w->ov, 0, sizeof(w->ov));
+    w->ov.hEvent = w->ev;
+    ok = ReadDirectoryChangesW(w->dir, w->buf, w->buf_len, w->recursive,
+                               w->filter, NULL, &w->ov, NULL);
+    if (ok) { w->armed = 1; return 0; }
+    gle = GetLastError();
+    /* FALSE + ERROR_IO_PENDING still queues the op (defensive; not expected for
+     * RDCW, which returns TRUE on a successful queue). */
+    if (gle == ERROR_IO_PENDING) { w->armed = 1; return 0; }
+    w->armed = 0;
+    return gle;
+}
+
+/*
+ * Watcher._open(abs_path_utf8, filter_dword, recursive_bool, buffer_size, external_bool)
+ *   -> Watcher.
+ * external_bool=true (:winloop mode) skips event/buffer creation and the first
+ * arm (the pump issues against winloop-owned memory). Captures GetLastError
+ * immediately, frees the wide path, then raises (the handle is stored into the
+ * struct before anything that can raise, so the free hook owns it).
+ */
+static VALUE
+watch_open(VALUE klass, VALUE vpath, VALUE vfilter, VALUE vrec, VALUE vbuf, VALUE vext)
+{
+    VALUE obj = watch_alloc(cWatcher);
+    watch_t *w = watch_get(obj);
+    WCHAR *wpath;
+    DWORD bufsz = NUM2ULONG(vbuf);
+    DWORD gle;
+    BY_HANDLE_FILE_INFORMATION fi;
+
+    /* Range-assert again in C (§5.18). Round up to a DWORD multiple of 4. */
+    if (bufsz < 4096 || bufsz > 65536)
+        rb_raise(rb_eArgError, "winwatch: buffer_size out of range");
+    bufsz = (bufsz + 3u) & ~3u;
+
+    w->filter    = NUM2ULONG(vfilter);
+    w->recursive = RTEST(vrec) ? TRUE : FALSE;
+    w->external  = RTEST(vext) ? 1 : 0;
+    w->buf_len   = bufsz;
+
+    wpath = to_ext_wide(vpath); /* malloc'd; freed below before any raise */
+
+    /* Share-all (READ|WRITE|DELETE) is load-bearing (§5.6): omitting
+     * FILE_SHARE_DELETE blocks delete/rename of the root for other processes. */
+    w->dir = CreateFileW(wpath, FILE_LIST_DIRECTORY,
+                         FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+                         NULL, OPEN_EXISTING,
+                         FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OVERLAPPED, NULL);
+    gle = GetLastError();
+    free(wpath);
+    if (w->dir == INVALID_HANDLE_VALUE)
+        raise_gle("CreateFile", gle); /* 2/3 NotFound, 5 AccessDenied, else OSError */
+
+    /* It must be a directory (misuse, not OS). */
+    if (!GetFileInformationByHandle(w->dir, &fi)) {
+        gle = GetLastError();
+        raise_gle("GetFileInformationByHandle", gle);
+    }
+    if (!(fi.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY))
+        rb_raise(eNotADirectory, "winwatch: not a directory");
+
+    if (!w->external) {
+        w->ev = CreateEventW(NULL, TRUE, FALSE, NULL); /* manual-reset */
+        if (!w->ev) raise_gle("CreateEvent", GetLastError());
+        w->buf = (unsigned char *)malloc(w->buf_len);
+        if (!w->buf) rb_raise(rb_eNoMemError, "winwatch: out of memory");
+
+        /* First arm in the constructor: coverage starts before watch() returns
+         * (rdcw §4/§14 re-arm discipline). A sync failure maps per §5.0. */
+        gle = watch_arm(w);
+        if (gle != 0)
+            raise_gle("ReadDirectoryChangesW", gle); /* 1 Unsupported, 2/3 NotFound, 5 AccessDenied */
+    }
+    return obj;
+}
+
+/* Watcher#_arm -> Integer (0 = queued, else GetLastError). standalone only. */
+static VALUE
+watch_m_arm(VALUE self)
+{
+    watch_t *w = watch_live(self);
+    return ULONG2NUM(watch_arm(w));
+}
+
+/* --- GVL-released overlapped wait, cancelable via CancelIoEx (winipc) ------ */
+
+typedef struct {
+    watch_t *w;
+    DWORD ms;
+    DWORD wait;
+    DWORD gle;
+} take_wait_t;
+
+static void *
+take_wait_fn(void *p)
+{
+    take_wait_t *t = (take_wait_t *)p;
+    t->wait = WaitForSingleObject(t->w->ev, t->ms);
+    if (t->wait == WAIT_FAILED) t->gle = GetLastError(); /* capture before GVL */
+    return NULL;
+}
+
+static void
+take_wait_ubf(void *p)
+{
+    take_wait_t *t = (take_wait_t *)p;
+    /* Cancel THIS specific op (winipc per-op cancel) so Thread#kill / Ctrl-C /
+     * Timeout break an INFINITE wait. No-op when closed: close already
+     * cancelled and may have torn down; nothing left to cancel and the dir
+     * handle must not be touched (it could be closed/recycled). */
+    if (!t->w->closed && t->w->dir != INVALID_HANDLE_VALUE)
+        CancelIoEx(t->w->dir, &t->w->ov);
+}
+
+/*
+ * Watcher#_take(ms) -> nil | [data(String|nil), code(Int), rearm_code(Int)].
+ * standalone only.
+ *   - nil               : timeout (no completion within ms)
+ *   - [data, code, rc]  : a completion (code = Win32 code, rc = re-arm result)
+ *     data is a binary String (the raw batch) when bytes>0, else nil.
+ *   - returns the symbol :closed via a distinct shape: we return Qnil only on
+ *     timeout, and raise nothing here for close — the Ruby layer detects close
+ *     by re-checking closed? after _take returns nil... To keep it unambiguous
+ *     we instead signal close by returning the Ruby symbol :closed.
+ */
+static VALUE
+watch_take(VALUE self, VALUE vms)
+{
+    watch_t *w = watch_live(self);
+    /* Widen the conversion to 64-bit so a large-but-legitimate finite timeout
+     * (ms > LONG_MAX on LLP64 where C long is 32-bit) does NOT raise RangeError
+     * — the public API documents timeout: as non-negative Numeric seconds that
+     * waits, and RangeError is not in the Raises list (§2.5). Negative => INFINITE
+     * (the nil/forever spelling). Any value past the WaitForSingleObject finite
+     * domain (0..0xFFFFFFFE; 0xFFFFFFFF is the INFINITE sentinel) clamps to the
+     * max finite wait 0xFFFFFFFE (~49.7 days) rather than accidentally meaning
+     * INFINITE. */
+    long long ms_in = NUM2LL(vms);
+    DWORD ms;
+    take_wait_t t;
+    DWORD bytes = 0, code = 0, rearm = 0;
+    VALUE data = Qnil;
+    BOOL got;
+
+    if (ms_in < 0)
+        ms = INFINITE;
+    else if (ms_in > 0xFFFFFFFELL)
+        ms = 0xFFFFFFFEu; /* clamp to the max finite WaitForSingleObject wait */
+    else
+        ms = (DWORD)ms_in;
+
+    /* Serve a stashed batch first (interrupt-race losslessness, §5.12). */
+    if (w->stash) {
+        VALUE out;
+        if (w->stash_len > 0) {
+            data = rb_str_new((const char *)w->stash, (long)w->stash_len);
+            rb_enc_associate(data, rb_ascii8bit_encoding());
+        }
+        code = w->stash_code;
+        free(w->stash);
+        w->stash = NULL;
+        w->stash_len = 0;
+        w->stash_code = 0;
+        out = rb_ary_new_capa(3);
+        rb_ary_push(out, data);
+        rb_ary_push(out, ULONG2NUM(code));
+        rb_ary_push(out, ULONG2NUM(0)); /* re-arm already done when we stashed */
+        return out;
+    }
+
+    /* If no op is armed (e.g. a prior re-arm failed and Ruby asked us to wait),
+     * try to re-arm right here and report the result as the rearm code, so a
+     * successful re-arm restores the watch and a real failure is classified
+     * (never an unarmed op that returns [nil,995,0] forever — the busy-livelock
+     * fixed here). On a successful re-arm we still report a synthetic abort with
+     * rearm==0 (no event, op re-armed, keep waiting); on a failed re-arm we
+     * report the synthetic abort WITH the live rearm code so classify can turn a
+     * permanent failure into a terminal :gone (or :rescan for 1022). */
+    if (!w->armed) {
+        DWORD rc = watch_arm(w);
+        VALUE out = rb_ary_new_capa(3);
+        rb_ary_push(out, Qnil);
+        rb_ary_push(out, ULONG2NUM(ERROR_OPERATION_ABORTED));
+        rb_ary_push(out, ULONG2NUM(rc));
+        return out;
+    }
+
+    t.w = w; t.ms = ms; t.wait = WAIT_FAILED; t.gle = 0;
+
+    w->in_take++;                       /* under the GVL, before release (§3.5 rule 3) */
+    rb_thread_call_without_gvl(take_wait_fn, &t, take_wait_ubf, &t);
+    w->in_take--;                       /* under the GVL, after reacquire */
+
+    /* Closed-first check on every GVL reacquisition (§3.4). A concurrent close
+     * ran: touch no dir/ov/buf. If we are the last leaver, perform the deferred
+     * teardown tail (§3.5 rule 3). The Ruby layer raises Winwatch::Closed. */
+    if (w->closed) {
+        if (w->in_take == 0)
+            watch_teardown(w);
+        return ID2SYM(rb_intern("closed"));
+    }
+
+    if (t.wait == WAIT_TIMEOUT) {
+        /* No completion within ms. But an interrupt (Thread#kill / Timeout)
+         * may be pending — its ubf fired CancelIoEx, which can complete the op
+         * with abort (or a real batch that lost the race). Settle the op into
+         * the stash, re-arm, then deliver the interrupt. If no interrupt is
+         * pending, the (abort) result is discarded and we return nil. */
+        if (!w->armed) return Qnil; /* defensive */
+        /* Probe without blocking: did the op complete (cancel or data)? */
+        got = GetOverlappedResult(w->dir, &w->ov, &bytes, FALSE);
+        if (!got && GetLastError() == ERROR_IO_INCOMPLETE)
+            return Qnil; /* genuinely still pending — a real timeout */
+        /* fall through to settle+stash below */
+    } else if (t.wait != WAIT_OBJECT_0) {
+        /* WAIT_FAILED (rare): drain so the op is settled, then report. */
+        DWORD n = 0;
+        CancelIoEx(w->dir, &w->ov);
+        GetOverlappedResult(w->dir, &w->ov, &n, TRUE);
+        w->armed = 0;
+        rearm = watch_arm(w);
+        {
+            VALUE out = rb_ary_new_capa(3);
+            rb_ary_push(out, Qnil);
+            rb_ary_push(out, ULONG2NUM(t.gle ? t.gle : ERROR_OPERATION_ABORTED));
+            rb_ary_push(out, ULONG2NUM(rearm));
+            return out;
+        }
+    } else {
+        /* Signaled: reap the completion (bWait=FALSE, already signaled). */
+        got = GetOverlappedResult(w->dir, &w->ov, &bytes, FALSE);
+    }
+
+    /* Settle the reaped op into local code/data. */
+    w->armed = 0;
+    if (got) {
+        code = 0;
+        if (bytes > 0) {
+            data = rb_str_new((const char *)w->buf, (long)bytes);
+            rb_enc_associate(data, rb_ascii8bit_encoding());
+        }
+    } else {
+        code = GetLastError(); /* e.g. 995 (aborted by our cancel), 5, 1022, ... */
+    }
+
+    /* Re-arm BEFORE returning to Ruby for parsing (rdcw §14), minimizing the
+     * no-op-outstanding window. */
+    rearm = watch_arm(w);
+
+    /* Interrupt-stash discipline (§5.12): copy the settled batch into the
+     * struct, then deliver any pending interrupt. If Thread#kill / Timeout is
+     * pending, rb_thread_check_ints() raises here — the batch is safely stashed
+     * and the NEXT take returns it (lossless). If nothing is pending we pull the
+     * stash back out and return it normally. The raise crosses no live kernel
+     * ownership: the op is already re-armed (or recorded un-armed). */
+    if (data != Qnil || code != 0) {
+        long dlen = (data == Qnil) ? 0 : RSTRING_LEN(data);
+        /* No prior stash here (we returned early at the top if one existed). */
+        if (dlen > 0) {
+            w->stash = (unsigned char *)malloc((size_t)dlen);
+            if (w->stash) {
+                memcpy(w->stash, RSTRING_PTR(data), (size_t)dlen);
+                w->stash_len = (DWORD)dlen;
+            } else {
+                w->stash_len = 0;
+            }
+        } else {
+            w->stash = NULL;
+            w->stash_len = 0;
+        }
+        w->stash_code = code;
+
+        rb_thread_check_ints(); /* may raise (Thread#kill / Timeout) — batch stashed */
+
+        /* No interrupt: hand the stash back to this caller. */
+        {
+            VALUE out;
+            VALUE sdata = Qnil;
+            if (w->stash_len > 0) {
+                sdata = rb_str_new((const char *)w->stash, (long)w->stash_len);
+                rb_enc_associate(sdata, rb_ascii8bit_encoding());
+            }
+            code = w->stash_code;
+            if (w->stash) { free(w->stash); w->stash = NULL; }
+            w->stash_len = 0;
+            w->stash_code = 0;
+            out = rb_ary_new_capa(3);
+            rb_ary_push(out, sdata);
+            rb_ary_push(out, ULONG2NUM(code));
+            rb_ary_push(out, ULONG2NUM(rearm));
+            return out;
+        }
+    }
+
+    /* data==nil AND code==0: a zero-byte successful completion = kernel buffer
+     * overflow (the success spelling, §5.1). The op is re-armed; deliver any
+     * pending interrupt, then return [nil, 0, rearm] so Ruby classifies it as
+     * :rescan. (Overflow already means "re-enumerate the tree", so the small
+     * chance of an interrupt dropping this one rescan signal is harmless — the
+     * re-armed op re-signals if still overflowing.) */
+    rb_thread_check_ints();
+    {
+        VALUE out = rb_ary_new_capa(3);
+        rb_ary_push(out, Qnil);
+        rb_ary_push(out, ULONG2NUM(code));
+        rb_ary_push(out, ULONG2NUM(rearm));
+        return out;
+    }
+}
+
+/* Watcher#_issue(ov_addr, buf_addr, len) -> Integer (0 = queued, else GLE).
+ * :winloop only; calls RDCW with winloop's OVERLAPPED/buffer addresses. */
+static VALUE
+watch_issue(VALUE self, VALUE vov, VALUE vbuf, VALUE vlen)
+{
+    watch_t *w = watch_get(self);
+    OVERLAPPED *ov = (OVERLAPPED *)(uintptr_t)NUM2ULL(vov);
+    void *buf = (void *)(uintptr_t)NUM2ULL(vbuf);
+    DWORD len = NUM2ULONG(vlen);
+    BOOL ok;
+    DWORD gle;
+
+    if (w->dir == INVALID_HANDLE_VALUE)
+        return ULONG2NUM(ERROR_OPERATION_ABORTED);
+
+    ok = ReadDirectoryChangesW(w->dir, buf, len, w->recursive, w->filter,
+                               NULL, ov, NULL);
+    if (ok) return ULONG2NUM(0);
+    gle = GetLastError();
+    if (gle == ERROR_IO_PENDING) return ULONG2NUM(0);
+    return ULONG2NUM(gle);
+}
+
+/* Watcher#_cancel — CancelIoEx(dir, NULL); safe from any thread; idempotent. */
+static VALUE
+watch_cancel(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    if (w->dir != INVALID_HANDLE_VALUE)
+        CancelIoEx(w->dir, NULL);
+    return Qnil;
+}
+
+/* Watcher#_mark_closed — set the closed flag (under the issue lock in Ruby for
+ * :winloop; standalone close uses _close which sets it directly). Returns the
+ * in_take count so the Ruby/close path could observe it if needed. */
+static VALUE
+watch_mark_closed(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    w->closed = 1;
+    return INT2NUM(w->in_take);
+}
+
+/* Watcher#_close_handle — settle + CloseHandle(s); idempotent; both modes.
+ * Only performs the teardown tail if no thread is inside _take (the in_take
+ * counter, §3.5 rule 3); otherwise the last leaver does it. */
+static VALUE
+watch_close_handle(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    if (w->in_take == 0)
+        watch_teardown(w);
+    return Qnil;
+}
+
+/*
+ * Watcher#_close_standalone — the full standalone close sequence (§3.5 rule 3):
+ * mark closed -> CancelIoEx(dir, &ov) -> deferred teardown tail iff in_take==0.
+ * The cancel wakes any blocked _take (which re-checks closed first and returns
+ * the :closed indication; the last leaver performs the tail).
+ */
+static VALUE
+watch_close_standalone(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    if (w->closed) return Qnil; /* idempotent */
+    w->closed = 1;
+    if (w->dir != INVALID_HANDLE_VALUE && w->armed)
+        CancelIoEx(w->dir, &w->ov);
+    if (w->in_take == 0)
+        watch_teardown(w);
+    /* else: the last leaver of _take runs the tail on its way out. */
+    return Qnil;
+}
+
+/* Watcher#closed? — raw getter; works on closed objects. */
+static VALUE
+watch_closed_p(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    return (w->closed || w->dir == INVALID_HANDLE_VALUE) ? Qtrue : Qfalse;
+}
+
+/* Watcher#in_take — diagnostic (used by the deferred-teardown stress test). */
+static VALUE
+watch_in_take(VALUE self)
+{
+    return INT2NUM(watch_get(self)->in_take);
+}
+
+/* Watcher#external? — :winloop mode flag (set at _open). */
+static VALUE
+watch_external_p(VALUE self)
+{
+    return watch_get(self)->external ? Qtrue : Qfalse;
+}
+
+/* Watcher#_handle_value -> Integer (the directory HANDLE, for sched.op_associate
+ * in :winloop mode). winwatch's struct stays the single owner of the handle. */
+static VALUE
+watch_handle_value(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    return ULL2NUM((unsigned long long)(uintptr_t)w->dir);
+}
+
+/* =====================================================================
+ * Record parsing — Winwatch._parse
+ * ===================================================================== */
+
+/*
+ * Winwatch._parse(data) -> [[action_int, name_utf8], ...]
+ *
+ * Walks the FILE_NOTIFY_INFORMATION NextEntryOffset chain defensively (§5.13):
+ * every offset must be DWORD-aligned and strictly within the batch, every
+ * FileNameLength must be in bounds, names are NOT NUL-terminated (length in
+ * bytes in FileNameLength). A malformed chain stops the walk; the already-valid
+ * records are returned plus one synthesized [-1, ""] sentinel (the Ruby layer
+ * turns it into a :rescan, because we can no longer trust the batch). Unknown
+ * Action values are skipped with an rb_warn under $VERBOSE. Zero-length names
+ * are skipped. All arithmetic uses 64-bit locals before comparison against the
+ * byte count (no DWORD wraparound, §5.18). No OS state is held at all.
+ */
+#define WINWATCH_ACTION_RESCAN (-1)  /* synthetic: malformed chain -> :rescan */
+
+static VALUE
+winwatch_parse(VALUE mod, VALUE data)
+{
+    const unsigned char *base;
+    unsigned long long total, off;
+    int truncated = 0;
+    VALUE out = rb_ary_new();
+
+    StringValue(data);
+    base = (const unsigned char *)RSTRING_PTR(data);
+    total = (unsigned long long)RSTRING_LEN(data);
+
+    off = 0;
+    while (off < total) {
+        const FILE_NOTIFY_INFORMATION *fni;
+        unsigned long long next, name_bytes, name_off, rec_end;
+        DWORD action;
+
+        /* Offset must be DWORD-aligned and leave room for the fixed header
+         * (NextEntryOffset + Action + FileNameLength = 12 bytes). */
+        if ((off & 3u) != 0)   { truncated = 1; break; }
+        if (off + 12 > total)  { truncated = 1; break; }
+
+        fni        = (const FILE_NOTIFY_INFORMATION *)(base + off);
+        action     = fni->Action;
+        name_bytes = (unsigned long long)fni->FileNameLength;
+        next       = (unsigned long long)fni->NextEntryOffset;
+
+        /* The name lives at off + offsetof(FileName) for name_bytes bytes. */
+        name_off = off + (unsigned long long)FIELD_OFFSET(FILE_NOTIFY_INFORMATION, FileName);
+        rec_end  = name_off + name_bytes;
+        if (rec_end > total || (name_bytes & 1u) != 0) { truncated = 1; break; }
+
+        if (name_bytes > 0) {
+            const WCHAR *wname = (const WCHAR *)(base + name_off);
+            int wlen = (int)(name_bytes / 2);
+            int u8n = WideCharToMultiByte(CP_UTF8, 0, wname, wlen, NULL, 0, NULL, NULL);
+            if (u8n > 0) {
+                switch (action) {
+                    case FILE_ACTION_ADDED:
+                    case FILE_ACTION_REMOVED:
+                    case FILE_ACTION_MODIFIED:
+                    case FILE_ACTION_RENAMED_OLD_NAME:
+                    case FILE_ACTION_RENAMED_NEW_NAME: {
+                        VALUE name = rb_utf8_str_new(NULL, u8n);
+                        VALUE rec;
+                        WideCharToMultiByte(CP_UTF8, 0, wname, wlen,
+                                            RSTRING_PTR(name), u8n, NULL, NULL);
+                        rec = rb_ary_new_capa(2);
+                        rb_ary_push(rec, UINT2NUM(action));
+                        rb_ary_push(rec, name);
+                        rb_ary_push(out, rec);
+                        break;
+                    }
+                    default:
+                        if (RTEST(ruby_verbose))
+                            rb_warn("winwatch: unknown FILE_ACTION %lu skipped",
+                                    (unsigned long)action);
+                        break;
+                }
+            }
+            /* u8n<=0: a name that won't convert — skip it, keep walking. */
+        }
+        /* name_bytes==0: zero-length name, skip. */
+
+        if (next == 0) break;                            /* end of chain (clean) */
+        if ((next & 3u) != 0)  { truncated = 1; break; } /* offset must be aligned */
+        if (next < (rec_end - off)) { truncated = 1; break; } /* overlaps this record */
+        if (off + next <= off) { truncated = 1; break; } /* no forward progress / wrap */
+        off += next;
+    }
+
+    /* Walk stopped on a malformed chain: synthesize a :rescan sentinel so the
+     * Ruby layer can no longer trust the batch to be complete (§5.13). */
+    if (truncated) {
+        VALUE rec = rb_ary_new_capa(2);
+        rb_ary_push(rec, INT2NUM(WINWATCH_ACTION_RESCAN));
+        rb_ary_push(rec, rb_utf8_str_new("", 0));
+        rb_ary_push(out, rec);
+    }
+    return out;
+}
+
+/* =====================================================================
+ * GetLongPathNameW bridge — Winwatch._long_path
+ * ===================================================================== */
+
+/*
+ * Winwatch._long_path(abs_utf8) -> String | nil
+ *
+ * Best-effort 8.3 -> long-name normalization via GetLongPathNameW (rdcw §9).
+ * Returns nil on ANY failure (file gone, FS without short names, conversion
+ * error) — never raises. Input is an absolute UTF-8 path (the joined path).
+ * GVL held; usually no round-trip (may touch the FS on SMB), per-tilde only.
+ */
+static VALUE
+winwatch_long_path(VALUE mod, VALUE vpath)
+{
+    int len, n;
+    WCHAR *wpath, *wout;
+    DWORD got, cap;
+    VALUE out;
+
+    StringValue(vpath);
+    len = (int)RSTRING_LEN(vpath);
+    if (len == 0) return Qnil;
+    n = MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(vpath), len, NULL, 0);
+    if (n <= 0) return Qnil;
+    wpath = (WCHAR *)malloc(sizeof(WCHAR) * ((size_t)n + 1));
+    if (!wpath) return Qnil;
+    MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(vpath), len, wpath, n);
+    wpath[n] = 0;
+
+    got = GetLongPathNameW(wpath, NULL, 0);
+    if (got == 0) { free(wpath); return Qnil; }
+    cap = got;
+    wout = (WCHAR *)malloc(sizeof(WCHAR) * (size_t)cap);
+    if (!wout) { free(wpath); return Qnil; }
+    got = GetLongPathNameW(wpath, wout, cap);
+    free(wpath);
+    if (got == 0 || got >= cap) { free(wout); return Qnil; }
+
+    {
+        int u8n = WideCharToMultiByte(CP_UTF8, 0, wout, (int)got, NULL, 0, NULL, NULL);
+        if (u8n <= 0) { free(wout); return Qnil; }
+        out = rb_utf8_str_new(NULL, u8n);
+        WideCharToMultiByte(CP_UTF8, 0, wout, (int)got, RSTRING_PTR(out), u8n, NULL, NULL);
+    }
+    free(wout);
+    return out;
+}
+
+/* ----------------------------------------------------------------- Init --- */
+
+void
+Init_winwatch(void)
+{
+    mWinwatch = rb_define_module("Winwatch");
+
+    eError         = rb_define_class_under(mWinwatch, "Error", rb_eStandardError);
+    eOSError       = rb_define_class_under(mWinwatch, "OSError", eError);
+    eNotFound      = rb_define_class_under(mWinwatch, "NotFound", eOSError);
+    eAccessDenied  = rb_define_class_under(mWinwatch, "AccessDenied", eOSError);
+    eUnsupported   = rb_define_class_under(mWinwatch, "Unsupported", eOSError);
+    eNotADirectory = rb_define_class_under(mWinwatch, "NotADirectory", eError);
+    eClosed        = rb_define_class_under(mWinwatch, "Closed", eError);
+
+    cWatcher = rb_define_class_under(mWinwatch, "Watcher", rb_cObject);
+    rb_define_alloc_func(cWatcher, watch_alloc);
+    rb_define_singleton_method(cWatcher, "_open", watch_open, 5);
+    rb_define_method(cWatcher, "_arm", watch_m_arm, 0);
+    rb_define_method(cWatcher, "_take", watch_take, 1);
+    rb_define_method(cWatcher, "_issue", watch_issue, 3);
+    rb_define_method(cWatcher, "_cancel", watch_cancel, 0);
+    rb_define_method(cWatcher, "_mark_closed", watch_mark_closed, 0);
+    rb_define_method(cWatcher, "_close_handle", watch_close_handle, 0);
+    rb_define_method(cWatcher, "_close_standalone", watch_close_standalone, 0);
+    rb_define_method(cWatcher, "closed?", watch_closed_p, 0);
+    rb_define_method(cWatcher, "_in_take", watch_in_take, 0);
+    rb_define_method(cWatcher, "_external?", watch_external_p, 0);
+    rb_define_method(cWatcher, "_handle_value", watch_handle_value, 0);
+
+    rb_define_singleton_method(mWinwatch, "_parse", winwatch_parse, 1);
+    rb_define_singleton_method(mWinwatch, "_long_path", winwatch_long_path, 1);
+}