winreg 0.1.0

data/ext/winreg/winreg.c

@@ -0,0 +1,909 @@
+/*
+ * winreg — typed Windows registry access for Ruby: exact wire formats,
+ * least-privilege opens, WOW64 views as a first-class option, and change
+ * notification (RegNotifyChangeKeyValue) that cooperates with a fiber
+ * scheduler.
+ *
+ * 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. Every HKEY/HANDLE lives in a TypedData wrapper whose free hook
+ * closes it, so a forgotten #close never leaks a handle. The ONLY blocking
+ * call in the gem is Watch#_wait's WaitForMultipleObjects, which releases the
+ * GVL via rb_nogvl(..., RB_NOGVL_INTR_FAIL) with an unblock function that
+ * sets a private stop event. Registry data/metadata calls are local,
+ * microsecond-scale hive operations and run with the GVL held — which also
+ * makes ALL key_t/watch_t state mutation GVL-serialized and race-free by
+ * construction.
+ *
+ * Watch close/wait protocol invariants (spec §3.6 / R6 — do not weaken):
+ *   1. ALL watch_t state mutation happens under the GVL; the GVL-released
+ *      region only READS the two handle values.
+ *   2. EVERY wake path re-checks `closed` before anything else (WFMO reports
+ *      the lowest-index signaled handle, so a notify wake / timeout /
+ *      WAIT_FAILED can mask a cross-thread #close that ran while off-GVL).
+ *   3. Interrupts are delivered ONLY at explicit rb_thread_check_ints()
+ *      points (rb_nogvl + RB_NOGVL_INTR_FAIL, never plain
+ *      rb_thread_call_without_gvl) — so the rearm always happens before a
+ *      pending Thread#kill / Timeout fires, and `waiting` can never wedge.
+ *
+ * include <ruby.h> before the Windows headers; never name a variable IN/OUT.
+ * Links advapi32 (registry APIs); kernel32 (events, waits, expansion) is
+ * linked by default.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+#include <limits.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mWinreg;
+static VALUE cKey, cWatch;
+static VALUE eError, eOSError, eNotFound, eAccessDenied, eKeyDeleted,
+             eTypeMismatch, eMalformedValue, eClosed;
+
+/* ------------------------------------------------------------ small helpers */
+
+/* UTF-8 (any-encoding, exported) Ruby String -> freshly xmalloc'd
+ * NUL-terminated UTF-16. Caller xfrees; never held across a raise.
+ * MB_ERR_INVALID_CHARS so invalid UTF-8 raises rather than silently mapping
+ * to U+FFFD (names must round-trip exactly). */
+static WCHAR *
+to_wide(VALUE str)
+{
+    int len, n;
+    WCHAR *w;
+    str = rb_str_export_to_enc(StringValue(str), rb_utf8_encoding());
+    len = (int)RSTRING_LEN(str);
+    if (len == 0) {
+        w = (WCHAR *)xmalloc(sizeof(WCHAR));
+        w[0] = 0;
+        return w;
+    }
+    n = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, RSTRING_PTR(str), len, NULL, 0);
+    if (n <= 0) rb_raise(eError, "winreg: invalid UTF-8 in name");
+    w = (WCHAR *)xmalloc(sizeof(WCHAR) * ((size_t)n + 1));
+    MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, RSTRING_PTR(str), len, w, n);
+    w[n] = 0;
+    return w;
+}
+
+/* Same conversion, but the UTF-16 lives inside a Ruby String (BINARY), so it
+ * is GC-owned and safe to hold across later Ruby allocations / raises (used
+ * by the probe-fill read loop and the expansion helper, where rb_str_new /
+ * rb_str_resize interleave with uses of the name). Take RSTRING_PTR fresh
+ * after every Ruby allocation (GC compaction rule). */
+static VALUE
+to_wide_val(VALUE str)
+{
+    int len, n;
+    VALUE w;
+    str = rb_str_export_to_enc(StringValue(str), rb_utf8_encoding());
+    len = (int)RSTRING_LEN(str);
+    if (len == 0) {
+        w = rb_str_new(NULL, sizeof(WCHAR));
+        memset(RSTRING_PTR(w), 0, sizeof(WCHAR));
+        return w;
+    }
+    n = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, RSTRING_PTR(str), len, NULL, 0);
+    if (n <= 0) rb_raise(eError, "winreg: invalid UTF-8 in name");
+    w = rb_str_new(NULL, (long)(((size_t)n + 1) * sizeof(WCHAR)));
+    MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS, RSTRING_PTR(str), len,
+                        (WCHAR *)RSTRING_PTR(w), n);
+    ((WCHAR *)RSTRING_PTR(w))[n] = 0;
+    return w;
+}
+
+/* UTF-16 -> UTF-8 Ruby String, LENIENT: default flags map lone surrogates to
+ * U+FFFD by design (lenient-names policy, spec E4/E14) so enumeration never
+ * aborts on one hostile name. wlen in WCHARs (excluding any NUL). */
+static VALUE
+wide_to_utf8(const WCHAR *w, int wlen)
+{
+    int n;
+    VALUE s;
+    if (wlen <= 0) return rb_utf8_str_new("", 0);
+    n = WideCharToMultiByte(CP_UTF8, 0, w, wlen, NULL, 0, NULL, NULL);
+    if (n <= 0) rb_raise(eError, "winreg: cannot convert UTF-16 name to UTF-8");
+    s = rb_str_new(NULL, n);
+    WideCharToMultiByte(CP_UTF8, 0, w, wlen, RSTRING_PTR(s), n, NULL, NULL);
+    rb_enc_associate(s, rb_utf8_encoding());
+    return s;
+}
+
+/* Build + raise a winreg error carrying @code. The code must be captured by
+ * the caller immediately at the failing call site (registry APIs return it as
+ * their LSTATUS result; GetLastError is NOT used for them). */
+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) {
+        /* trim trailing CR/LF/period, then copy to a stack buffer */
+        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;
+    }
+    /* Release the OS buffer BEFORE any Ruby allocation, so an OOM longjmp from
+     * rb_sprintf / rb_exc_new_str cannot leak it. */
+    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 a Win32 / LSTATUS code to the winreg subclass and raise. ERROR_MORE_DATA
+ * and ERROR_NO_MORE_ITEMS are flow control at every call site, never raised. */
+static void
+raise_lstatus(const char *api, LONG rc)
+{
+    VALUE klass = eOSError;
+    switch (rc) {
+        case ERROR_FILE_NOT_FOUND: klass = eNotFound;     break; /* 2    */
+        case ERROR_ACCESS_DENIED:  klass = eAccessDenied; break; /* 5    */
+        case ERROR_KEY_DELETED:    klass = eKeyDeleted;   break; /* 1018 */
+        default: break;
+    }
+    raise_code(klass, api, (DWORD)rc);
+}
+
+/* GetLastError-reporting APIs (events, waits, expansion) use the same map. */
+static void
+raise_gle(const char *api, DWORD code)
+{
+    raise_lstatus(api, (LONG)code);
+}
+
+/* Length of a Ruby String as a DWORD, guarding the 4 GiB ceiling. */
+static DWORD
+dword_len(VALUE str)
+{
+    long n;
+    StringValue(str);
+    n = RSTRING_LEN(str);
+    if ((unsigned long long)n > 0xFFFFFFFFull)
+        rb_raise(rb_eArgError, "winreg: data too large (> 4 GiB)");
+    return (DWORD)n;
+}
+
+/* Predefined-root Integer (0x80000000..0x80000005) -> HKEY. winreg.h defines
+ * these sign-extended through LONG ((HKEY)(ULONG_PTR)((LONG)0x80000001)), so
+ * we must replicate the sign extension on 64-bit. */
+static HKEY
+root_hkey(VALUE v)
+{
+    return (HKEY)(ULONG_PTR)(LONG_PTR)(LONG)(DWORD)NUM2ULONG(v);
+}
+
+#define WOW64_VIEW_MASK (KEY_WOW64_64KEY | KEY_WOW64_32KEY) /* 0x300 */
+
+/* =====================================================================
+ * Winreg::Key
+ * ===================================================================== */
+
+typedef struct {
+    HKEY  h;          /* sentinel: NULL */
+    DWORD view_sam;   /* 0, KEY_WOW64_64KEY, or KEY_WOW64_32KEY; re-applied to children */
+    int   created;    /* REG_CREATED_NEW_KEY disposition */
+    int   predefined; /* bare-root Key wrapping a predefined pseudo-handle:
+                         #close and the free hook skip RegCloseKey */
+    int   closed;
+} key_t;
+
+static void
+key_free(void *p)
+{
+    key_t *k = (key_t *)p;
+    /* Safety net, never the API. Never RegCloseKey a predefined pseudo-handle. */
+    if (k->h && !k->predefined) RegCloseKey(k->h);
+    xfree(k);
+}
+
+static const rb_data_type_t key_type = {
+    "Winreg::Key", { 0, key_free, 0, }, 0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+key_alloc(VALUE klass)
+{
+    key_t *k;
+    VALUE obj = TypedData_Make_Struct(klass, key_t, &key_type, k);
+    k->h = NULL;
+    k->view_sam = 0;
+    k->created = 0;
+    k->predefined = 0;
+    k->closed = 1; /* closed until _open/_create succeeds: .allocate abuse is inert */
+    return obj;
+}
+
+static key_t *
+key_get(VALUE self)
+{
+    key_t *k;
+    TypedData_Get_Struct(self, key_t, &key_type, k);
+    return k;
+}
+
+static key_t *
+key_live(VALUE self)
+{
+    key_t *k = key_get(self);
+    if (k->closed || !k->h) rb_raise(eClosed, "winreg: key is closed");
+    return k;
+}
+
+/* Key._open(root, subpath_or_nil, sam) — private singleton. A nil subpath is
+ * a bare root: per the documented RegOpenKeyExW behavior a NULL lpSubKey on a
+ * predefined key returns the SAME process-global pseudo-handle, so no OS call
+ * is made; the Key wraps the predefined handle value with `predefined` set
+ * and #close / the free hook skip RegCloseKey. */
+static VALUE
+key_s_open(VALUE klass, VALUE vroot, VALUE vsub, VALUE vsam)
+{
+    VALUE obj = key_alloc(cKey);
+    key_t *k = key_get(obj);
+    HKEY root = root_hkey(vroot);
+    DWORD sam = (DWORD)NUM2ULONG(vsam);
+    HKEY h = NULL;
+    LONG rc;
+    WCHAR *w;
+
+    k->view_sam = sam & WOW64_VIEW_MASK;
+    if (NIL_P(vsub)) {
+        k->h = root;
+        k->predefined = 1;
+        k->closed = 0;
+        return obj;
+    }
+    w = to_wide(vsub);
+    rc = RegOpenKeyExW(root, w, 0, sam, &h);
+    xfree(w);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegOpenKeyExW", rc);
+    k->h = h;
+    k->closed = 0;
+    return obj;
+}
+
+/* Key._create(root, subpath, sam) — private singleton. Creates all missing
+ * intermediate keys; NULL SECURITY_ATTRIBUTES inherits the parent SD. */
+static VALUE
+key_s_create(VALUE klass, VALUE vroot, VALUE vsub, VALUE vsam)
+{
+    VALUE obj = key_alloc(cKey);
+    key_t *k = key_get(obj);
+    HKEY root = root_hkey(vroot);
+    DWORD sam = (DWORD)NUM2ULONG(vsam);
+    HKEY h = NULL;
+    DWORD disp = 0;
+    LONG rc;
+    WCHAR *w;
+
+    k->view_sam = sam & WOW64_VIEW_MASK;
+    w = to_wide(vsub);
+    rc = RegCreateKeyExW(root, w, 0, NULL, REG_OPTION_NON_VOLATILE, sam, NULL, &h, &disp);
+    xfree(w);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegCreateKeyExW", rc);
+    k->h = h;
+    k->created = (disp == REG_CREATED_NEW_KEY) ? 1 : 0;
+    k->closed = 0;
+    return obj;
+}
+
+/* Key#_open_child(subpath, sam) — handle-relative open. The parent's WOW64
+ * view is OR'd in here, so children can never escape it (spec E14). */
+static VALUE
+key_open_child(VALUE self, VALUE vsub, VALUE vsam)
+{
+    key_t *k = key_live(self);
+    VALUE obj = key_alloc(cKey); /* wrapper first: no handle live across OOM */
+    key_t *child = key_get(obj);
+    DWORD sam = (DWORD)NUM2ULONG(vsam) | k->view_sam;
+    HKEY h = NULL;
+    LONG rc;
+    WCHAR *w;
+
+    w = to_wide(vsub);
+    rc = RegOpenKeyExW(k->h, w, 0, sam, &h);
+    xfree(w);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegOpenKeyExW", rc);
+    child->h = h;
+    child->view_sam = k->view_sam;
+    child->closed = 0;
+    return obj;
+}
+
+/* Key#_create_child(subpath, sam) — handle-relative create, view inherited. */
+static VALUE
+key_create_child(VALUE self, VALUE vsub, VALUE vsam)
+{
+    key_t *k = key_live(self);
+    VALUE obj = key_alloc(cKey);
+    key_t *child = key_get(obj);
+    DWORD sam = (DWORD)NUM2ULONG(vsam) | k->view_sam;
+    HKEY h = NULL;
+    DWORD disp = 0;
+    LONG rc;
+    WCHAR *w;
+
+    w = to_wide(vsub);
+    rc = RegCreateKeyExW(k->h, w, 0, NULL, REG_OPTION_NON_VOLATILE, sam, NULL, &h, &disp);
+    xfree(w);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegCreateKeyExW", rc);
+    child->h = h;
+    child->view_sam = k->view_sam;
+    child->created = (disp == REG_CREATED_NEW_KEY) ? 1 : 0;
+    child->closed = 0;
+    return obj;
+}
+
+/* Key#_read_raw(name_or_nil) -> [type_int, bytes (BINARY)].
+ * RegQueryValueExW probe + fill, looped on ERROR_MORE_DATA (TOCTOU growth,
+ * spec E12) with cb re-initialized each pass. The destination buffer IS a
+ * Ruby string; pointers are taken after the last Ruby allocation. The name is
+ * held in a Ruby-owned UTF-16 string so nothing leaks across a raise. */
+static VALUE
+key_read_raw(VALUE self, VALUE name)
+{
+    key_t *k = key_live(self);
+    VALUE wname = Qnil;
+    VALUE buf;
+    const WCHAR *pw;
+    DWORD type = 0, cb = 0;
+    LONG rc;
+
+    if (!NIL_P(name)) wname = to_wide_val(name);
+
+    /* size probe */
+    pw = NIL_P(wname) ? NULL : (const WCHAR *)RSTRING_PTR(wname);
+    rc = RegQueryValueExW(k->h, pw, NULL, &type, NULL, &cb);
+    if (rc != ERROR_SUCCESS && rc != ERROR_MORE_DATA)
+        raise_lstatus("RegQueryValueExW", rc);
+
+    buf = rb_str_new(NULL, (long)cb);
+    for (;;) {
+        DWORD cb2 = cb;
+        /* re-take both pointers after any Ruby allocation (GC compaction) */
+        pw = NIL_P(wname) ? NULL : (const WCHAR *)RSTRING_PTR(wname);
+        rc = RegQueryValueExW(k->h, pw, NULL, &type, (LPBYTE)RSTRING_PTR(buf), &cb2);
+        if (rc == ERROR_SUCCESS) { cb = cb2; break; }
+        if (rc == ERROR_MORE_DATA) { cb = cb2; rb_str_resize(buf, (long)cb); continue; }
+        raise_lstatus("RegQueryValueExW", rc);
+    }
+    rb_str_set_len(buf, (long)cb);
+    rb_enc_associate(buf, rb_ascii8bit_encoding());
+    RB_GC_GUARD(wname);
+    return rb_assoc_new(ULONG2NUM(type), buf);
+}
+
+/* Key#_value_p(name_or_nil) -> true/false. Pure size probe; error 2 = false. */
+static VALUE
+key_value_p(VALUE self, VALUE name)
+{
+    key_t *k = key_live(self);
+    WCHAR *wname = NIL_P(name) ? NULL : to_wide(name);
+    DWORD type = 0, cb = 0;
+    LONG rc = RegQueryValueExW(k->h, wname, NULL, &type, NULL, &cb);
+    if (wname) xfree(wname);
+    if (rc == ERROR_SUCCESS || rc == ERROR_MORE_DATA) return Qtrue;
+    if (rc == ERROR_FILE_NOT_FOUND) return Qfalse;
+    raise_lstatus("RegQueryValueExW", rc);
+    UNREACHABLE_RETURN(Qnil);
+}
+
+/* Key#_write_raw(name_or_nil, type_tag, bytes) — RegSetValueExW. cb includes
+ * any terminators: the Ruby layer's serializers build the exact byte image. */
+static VALUE
+key_write_raw(VALUE self, VALUE name, VALUE vtype, VALUE bytes)
+{
+    key_t *k = key_live(self);
+    DWORD cb = dword_len(bytes); /* coercion + 4 GiB guard up front */
+    DWORD type = (DWORD)NUM2ULONG(vtype);
+    WCHAR *wname = NIL_P(name) ? NULL : to_wide(name);
+    LONG rc;
+
+    /* data pointer taken inline, after the last possible Ruby/GC allocation */
+    rc = RegSetValueExW(k->h, wname, 0, type,
+                        cb ? (const BYTE *)RSTRING_PTR(bytes) : NULL, cb);
+    if (wname) xfree(wname);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegSetValueExW", rc);
+    return Qnil;
+}
+
+/* Key#_delete_value(name_or_nil) — RegDeleteValueW. */
+static VALUE
+key_delete_value(VALUE self, VALUE name)
+{
+    key_t *k = key_live(self);
+    WCHAR *wname = NIL_P(name) ? NULL : to_wide(name);
+    LONG rc = RegDeleteValueW(k->h, wname);
+    if (wname) xfree(wname);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegDeleteValueW", rc);
+    return Qnil;
+}
+
+/* Key#_delete_key(name) — RegDeleteKeyExW, the view-aware form (plain
+ * RegDeleteKeyW cannot carry the WOW64 view). Non-recursive only; the
+ * recursive walk lives in Ruby over these raise-safe primitives. */
+static VALUE
+key_delete_key(VALUE self, VALUE name)
+{
+    key_t *k = key_live(self);
+    WCHAR *wname = to_wide(name);
+    LONG rc = RegDeleteKeyExW(k->h, wname, k->view_sam, 0);
+    xfree(wname);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegDeleteKeyExW", rc);
+    return Qnil;
+}
+
+/* Key#_enum_value(index) -> [name, type_int, bytes] or nil (end).
+ * Name + type + data in ONE RegEnumValueW call — no name-then-query TOCTOU.
+ * Name buffer is 16,384 WCHARs (value names go to 16,383 chars — spec E13)
+ * via ALLOCV, which is GC-owned and therefore safe across raises. */
+#define VALUE_NAME_CCH 16384
+static VALUE
+key_enum_value(VALUE self, VALUE vidx)
+{
+    key_t *k = key_live(self);
+    DWORD idx = (DWORD)NUM2ULONG(vidx);
+    VALUE vnb;
+    WCHAR *namebuf = ALLOCV_N(WCHAR, vnb, VALUE_NAME_CCH);
+    VALUE data = rb_str_new(NULL, 256);
+    VALUE name, out;
+    DWORD cch, cb, type = 0;
+    LONG rc;
+
+    for (;;) {
+        cch = VALUE_NAME_CCH;             /* chars incl. NUL in, excl. NUL out */
+        cb = (DWORD)RSTRING_LEN(data);    /* re-initialized each pass (E12) */
+        rc = RegEnumValueW(k->h, idx, namebuf, &cch, NULL, &type,
+                           (LPBYTE)RSTRING_PTR(data), &cb);
+        if (rc == ERROR_SUCCESS) break;
+        if (rc == ERROR_NO_MORE_ITEMS) { ALLOCV_END(vnb); return Qnil; }
+        if (rc == ERROR_MORE_DATA) { rb_str_resize(data, (long)cb); continue; }
+        ALLOCV_END(vnb);
+        raise_lstatus("RegEnumValueW", rc);
+    }
+    name = wide_to_utf8(namebuf, (int)cch); /* lenient: U+FFFD, never aborts */
+    ALLOCV_END(vnb);
+    rb_str_set_len(data, (long)cb);
+    rb_enc_associate(data, rb_ascii8bit_encoding());
+    out = rb_ary_new_from_args(3, name, ULONG2NUM(type), data);
+    return out;
+}
+
+/* Key#_enum_key(index) -> name or nil (end). Key names cap at 255 chars. */
+static VALUE
+key_enum_key(VALUE self, VALUE vidx)
+{
+    key_t *k = key_live(self);
+    DWORD idx = (DWORD)NUM2ULONG(vidx);
+    WCHAR namebuf[512];
+    DWORD cch = 512;
+    LONG rc = RegEnumKeyExW(k->h, idx, namebuf, &cch, NULL, NULL, NULL, NULL);
+    if (rc == ERROR_NO_MORE_ITEMS) return Qnil;
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegEnumKeyExW", rc);
+    return wide_to_utf8(namebuf, (int)cch);
+}
+
+/* Key#_query_info -> [subkeys, max_subkey_chars, values, max_name_chars,
+ *                     max_data_bytes, last_write_filetime_int] */
+static VALUE
+key_query_info(VALUE self)
+{
+    key_t *k = key_live(self);
+    DWORD subkeys = 0, maxsub = 0, values = 0, maxname = 0, maxdata = 0;
+    FILETIME ft;
+    ULONGLONG t;
+    LONG rc;
+
+    ft.dwLowDateTime = 0;
+    ft.dwHighDateTime = 0;
+    rc = RegQueryInfoKeyW(k->h, NULL, NULL, NULL, &subkeys, &maxsub, NULL,
+                          &values, &maxname, &maxdata, NULL, &ft);
+    if (rc != ERROR_SUCCESS) raise_lstatus("RegQueryInfoKeyW", rc);
+    t = ((ULONGLONG)ft.dwHighDateTime << 32) | (ULONGLONG)ft.dwLowDateTime;
+    return rb_ary_new_from_args(6, ULONG2NUM(subkeys), ULONG2NUM(maxsub),
+                                ULONG2NUM(values), ULONG2NUM(maxname),
+                                ULONG2NUM(maxdata), ULL2NUM(t));
+}
+
+static VALUE
+key_close(VALUE self)
+{
+    key_t *k = key_get(self);
+    if (!k->closed) {
+        /* bare roots: flag flip only — never RegCloseKey a pseudo-handle */
+        if (k->h && !k->predefined) RegCloseKey(k->h);
+        k->h = NULL;
+        k->closed = 1;
+    }
+    return Qnil;
+}
+
+static VALUE key_closed_p(VALUE self)  { return key_get(self)->closed ? Qtrue : Qfalse; }
+static VALUE key_created_p(VALUE self) { return key_get(self)->created ? Qtrue : Qfalse; }
+
+/* =====================================================================
+ * Winreg::Watch — RegNotifyChangeKeyValue
+ * ===================================================================== */
+
+typedef struct {
+    HKEY   hkey;          /* private KEY_NOTIFY|view handle, owned */
+    HANDLE notify_event;  /* auto-reset, unnamed (research §6.6: verified) */
+    HANDLE stop_event;    /* manual-reset, unnamed: ubf + #close wakeup */
+    DWORD  filter;        /* includes REG_NOTIFY_THREAD_AGNOSTIC, frozen at construction */
+    BOOL   subtree;
+    int    predefined;    /* hkey is a predefined pseudo-handle (bare-root watch) */
+    int    waiting;       /* a _wait is in flight (single-waiter guard) */
+    int    finished;      /* :deleted delivered; handles already torn down */
+    int    closed;
+} watch_t;
+
+static void
+watch_teardown(watch_t *w)
+{
+    if (w->hkey) {
+        if (!w->predefined) RegCloseKey(w->hkey);
+        w->hkey = NULL;
+    }
+    if (w->notify_event) { CloseHandle(w->notify_event); w->notify_event = NULL; }
+    if (w->stop_event)   { CloseHandle(w->stop_event);   w->stop_event = NULL; }
+}
+
+static void
+watch_free(void *p)
+{
+    watch_t *w = (watch_t *)p;
+    /* Safety net. A waiter keeps the object reachable (receiver on its
+     * stack), so this can never run concurrently with a wait. */
+    watch_teardown(w);
+    xfree(w);
+}
+
+static const rb_data_type_t watch_type = {
+    "Winreg::Watch", { 0, watch_free, 0, }, 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->hkey = NULL;
+    w->notify_event = NULL;
+    w->stop_event = NULL;
+    w->filter = 0;
+    w->subtree = FALSE;
+    w->predefined = 0;
+    w->waiting = 0;
+    w->finished = 0;
+    w->closed = 1; /* closed until _new succeeds */
+    return obj;
+}
+
+static watch_t *
+watch_get(VALUE self)
+{
+    watch_t *w;
+    TypedData_Get_Struct(self, watch_t, &watch_type, w);
+    return w;
+}
+
+/* REG_NOTIFY_THREAD_AGNOSTIC (Win8+, gem targets Win10+): unconditional —
+ * registrations must survive ephemeral Ruby threads (run_blocking workers). */
+#ifndef REG_NOTIFY_THREAD_AGNOSTIC
+#define REG_NOTIFY_THREAD_AGNOSTIC 0x10000000L
+#endif
+
+/* Watch._new(root, subpath_or_nil, view_sam, subtree, filter) — private
+ * singleton. Opens its OWN handle (KEY_NOTIFY | view) by path, creates the
+ * two private events, and arms the first registration so changes between
+ * construction and the first #wait are caught. Any failure: capture code,
+ * close what was opened, raise. */
+static VALUE
+watch_s_new(VALUE klass, VALUE vroot, VALUE vsub, VALUE vview, VALUE vsubtree, VALUE vfilter)
+{
+    VALUE obj = watch_alloc(cWatch);
+    watch_t *w = watch_get(obj);
+    HKEY root = root_hkey(vroot);
+    DWORD view = (DWORD)NUM2ULONG(vview);
+    DWORD filter = (DWORD)NUM2ULONG(vfilter) | REG_NOTIFY_THREAD_AGNOSTIC;
+    BOOL subtree = RTEST(vsubtree) ? TRUE : FALSE;
+    HKEY h = NULL;
+    LONG rc;
+    DWORD gle;
+
+    if (NIL_P(vsub)) {
+        /* bare root: the predefined pseudo-handle itself carries KEY_NOTIFY */
+        h = root;
+        w->predefined = 1;
+    } else {
+        WCHAR *ws = to_wide(vsub);
+        rc = RegOpenKeyExW(root, ws, 0, KEY_NOTIFY | view, &h);
+        xfree(ws);
+        if (rc != ERROR_SUCCESS) raise_lstatus("RegOpenKeyExW", rc);
+    }
+    w->hkey = h; /* owned from here: free hook / teardown closes it */
+
+    w->notify_event = CreateEventW(NULL, FALSE, FALSE, NULL); /* auto-reset */
+    if (!w->notify_event) {
+        gle = GetLastError();
+        watch_teardown(w);
+        raise_gle("CreateEvent", gle);
+    }
+    w->stop_event = CreateEventW(NULL, TRUE, FALSE, NULL); /* manual-reset */
+    if (!w->stop_event) {
+        gle = GetLastError();
+        watch_teardown(w);
+        raise_gle("CreateEvent", gle);
+    }
+    rc = RegNotifyChangeKeyValue(w->hkey, subtree, filter, w->notify_event, TRUE);
+    if (rc != ERROR_SUCCESS) {
+        watch_teardown(w);
+        raise_lstatus("RegNotifyChangeKeyValue", rc);
+    }
+    w->filter = filter;
+    w->subtree = subtree;
+    w->closed = 0;
+    return obj;
+}
+
+/* --- the GVL-released wait ------------------------------------------------ */
+
+typedef struct {
+    HANDLE handles[2]; /* {notify, stop} */
+    DWORD ms;
+    DWORD result;
+    DWORD gle;
+} wfmo_arg_t;
+
+static void *
+wfmo_fn(void *p)
+{
+    wfmo_arg_t *a = (wfmo_arg_t *)p;
+    a->result = WaitForMultipleObjects(2, a->handles, FALSE, a->ms);
+    if (a->result == WAIT_FAILED) a->gle = GetLastError(); /* capture before GVL */
+    return NULL;
+}
+
+static void
+wfmo_ubf(void *p)
+{
+    wfmo_arg_t *a = (wfmo_arg_t *)p;
+    SetEvent(a->handles[1]); /* stop event: cancel-capable without polling */
+}
+
+/* Watch#_wait(ms) -> :changed / :deleted / nil(timeout). Implements spec §3.6
+ * exactly — see the banner invariants. ms < 0 = INFINITE. */
+static VALUE
+watch_wait(VALUE self, VALUE vms)
+{
+    watch_t *w = watch_get(self);
+    long ms_in = NUM2LONG(vms);
+    int infinite = (ms_in < 0);
+    ULONGLONG deadline = 0;
+
+    /* step 2: entry checks (GVL held) */
+    if (w->closed) rb_raise(eClosed, "winreg: watch is closed");
+    if (w->waiting) rb_raise(eError, "winreg: Watch#wait is single-waiter");
+    w->waiting = 1;
+    /* consume a stale ubf signal from a previous interrupted wait — safe: a
+     * concurrent close cannot run while we hold the GVL, and once released,
+     * close SETS the event after setting `closed`, which step 4a re-checks. */
+    ResetEvent(w->stop_event);
+    /* the absolute deadline is computed ONCE; re-waits measure remaining time
+     * against it, so spurious wakes cannot silently extend the timeout */
+    if (!infinite) deadline = GetTickCount64() + (ULONGLONG)ms_in;
+
+    for (;;) {
+        wfmo_arg_t a;
+        if (infinite) {
+            a.ms = INFINITE;
+        } else {
+            ULONGLONG now = GetTickCount64();
+            a.ms = (now >= deadline) ? 0 : (DWORD)(deadline - now);
+        }
+        a.handles[0] = w->notify_event;
+        a.handles[1] = w->stop_event;
+        /* If a pending interrupt makes rb_nogvl skip the call entirely
+         * (RB_NOGVL_INTR_FAIL fails fast), this sentinel routes us to the
+         * stop path (4c), whose rb_thread_check_ints delivers it cleanly. */
+        a.result = WAIT_OBJECT_0 + 1;
+        a.gle = 0;
+
+        /* step 3: the only GVL-released region in the gem. RB_NOGVL_INTR_FAIL
+         * is load-bearing: nothing raises on return; pending interrupts fire
+         * only at the explicit rb_thread_check_ints() points below, where the
+         * watch state is consistent (rearm-before-interrupt-delivery). */
+        rb_nogvl(wfmo_fn, &a, wfmo_ubf, &a, RB_NOGVL_INTR_FAIL);
+
+        /* step 4a: unconditional closed check, FIRST — before branching on
+         * the wait result. WFMO reports the lowest-index signaled handle, so
+         * any wake can mask a cross-thread #close that ran while off-GVL. */
+        if (w->closed) {
+            watch_teardown(w); /* the deferred teardown #close left to us */
+            w->waiting = 0;
+            rb_raise(eClosed, "winreg: watch is closed");
+        }
+
+        if (a.result == WAIT_OBJECT_0) {
+            /* 4b: notify — rearm BEFORE delivering (same frozen params: the
+             * same-handle param trap is structurally impossible). */
+            LONG rc = RegNotifyChangeKeyValue(w->hkey, w->subtree, w->filter,
+                                              w->notify_event, TRUE);
+            if (rc == ERROR_SUCCESS) {
+                w->waiting = 0;
+                /* a pending kill/timeout raises HERE, with the registration
+                 * already rearmed and the same Watch reusable — only the
+                 * coalesced :changed is dropped (stateless delivery). */
+                rb_thread_check_ints();
+                return ID2SYM(rb_intern("changed"));
+            }
+            if (rc == ERROR_KEY_DELETED) {
+                w->finished = 1;
+                w->closed = 1;
+                watch_teardown(w);
+                w->waiting = 0;
+                return ID2SYM(rb_intern("deleted"));
+            }
+            w->closed = 1;
+            watch_teardown(w);
+            w->waiting = 0;
+            raise_lstatus("RegNotifyChangeKeyValue", rc);
+        }
+        else if (a.result == WAIT_OBJECT_0 + 1) {
+            /* 4c: stop event, not closed (per 4a): the ubf fired for a
+             * pending interrupt (or rb_nogvl failed fast on one). */
+            w->waiting = 0;
+            rb_thread_check_ints(); /* delivers Thread#kill / Timeout; the
+                                     * registration stays armed, nothing leaks */
+            /* spurious return: re-validate the step-2 entry conditions */
+            if (w->closed) rb_raise(eClosed, "winreg: watch is closed");
+            if (w->waiting) rb_raise(eError, "winreg: Watch#wait is single-waiter");
+            if (!infinite && GetTickCount64() >= deadline) return Qnil;
+            w->waiting = 1;
+            ResetEvent(w->stop_event);
+            continue;
+        }
+        else if (a.result == WAIT_TIMEOUT) {
+            /* 4d: registration remains armed */
+            w->waiting = 0;
+            return Qnil;
+        }
+        else {
+            /* 4e: WAIT_FAILED (code captured inside the no-GVL fn) */
+            DWORD g = a.gle;
+            w->waiting = 0;
+            raise_gle("WaitForMultipleObjects", g);
+        }
+    }
+}
+
+/* Watch#close — step 5. Idempotent; unblocks a concurrent #wait (which then
+ * raises Closed in the waiting thread). Handles MUST NOT be closed while
+ * another thread waits on them: if `waiting`, the teardown is deferred to the
+ * waiter's next wake (step 4a, which every wake path executes). `waiting` is
+ * only ever cleared with the GVL held, so waiting == 0 guarantees no thread
+ * is blocked on the handles. */
+static VALUE
+watch_close(VALUE self)
+{
+    watch_t *w = watch_get(self);
+    if (w->closed) return Qnil;
+    w->closed = 1;
+    if (w->waiting) {
+        SetEvent(w->stop_event);
+        return Qnil;
+    }
+    watch_teardown(w);
+    return Qnil;
+}
+
+static VALUE watch_closed_p(VALUE self) { return watch_get(self)->closed ? Qtrue : Qfalse; }
+
+/* =====================================================================
+ * Winreg._expand — ExpandEnvironmentStringsW
+ * ===================================================================== */
+
+static VALUE
+wr_expand(VALUE mod, VALUE str)
+{
+    VALUE wsrc = to_wide_val(str); /* Ruby-owned: raise-safe across allocs */
+    VALUE wout, out;
+    DWORD n, r;
+
+    /* size probe: returned size is in WCHARs and includes the NUL */
+    n = ExpandEnvironmentStringsW((const WCHAR *)RSTRING_PTR(wsrc), NULL, 0);
+    if (n == 0) raise_gle("ExpandEnvironmentStrings", GetLastError());
+    wout = rb_str_new(NULL, (long)n * (long)sizeof(WCHAR));
+    for (;;) {
+        /* re-take both pointers after any Ruby allocation */
+        r = ExpandEnvironmentStringsW((const WCHAR *)RSTRING_PTR(wsrc),
+                                      (WCHAR *)RSTRING_PTR(wout), n);
+        if (r == 0) raise_gle("ExpandEnvironmentStrings", GetLastError());
+        if (r <= n) { n = r; break; }
+        n = r; /* grew between calls (env mutated): resize and retry */
+        rb_str_resize(wout, (long)n * (long)sizeof(WCHAR));
+    }
+    /* n includes the terminating NUL; exclude it from the result */
+    out = wide_to_utf8((const WCHAR *)RSTRING_PTR(wout), (int)(n - 1));
+    RB_GC_GUARD(wsrc);
+    RB_GC_GUARD(wout);
+    return out;
+}
+
+/* ----------------------------------------------------------------- Init --- */
+
+void
+Init_winreg(void)
+{
+    mWinreg = rb_define_module("Winreg");
+
+    eError          = rb_define_class_under(mWinreg, "Error", rb_eStandardError);
+    eOSError        = rb_define_class_under(mWinreg, "OSError", eError);
+    eNotFound       = rb_define_class_under(mWinreg, "NotFound", eOSError);
+    eAccessDenied   = rb_define_class_under(mWinreg, "AccessDenied", eOSError);
+    eKeyDeleted     = rb_define_class_under(mWinreg, "KeyDeleted", eOSError);
+    eTypeMismatch   = rb_define_class_under(mWinreg, "TypeMismatch", eError);
+    eMalformedValue = rb_define_class_under(mWinreg, "MalformedValue", eError);
+    eClosed         = rb_define_class_under(mWinreg, "Closed", eError);
+
+    /* ---- predefined root handle values (verified, winreg.h) ----
+     * Public-but-undocumented plumbing for the Ruby layer's path parser.
+     * HKEY_PERFORMANCE_DATA (0x80000004) is deliberately not defined. */
+    rb_define_const(mWinreg, "HKEY_CLASSES_ROOT",   ULONG2NUM(0x80000000UL));
+    rb_define_const(mWinreg, "HKEY_CURRENT_USER",   ULONG2NUM(0x80000001UL));
+    rb_define_const(mWinreg, "HKEY_LOCAL_MACHINE",  ULONG2NUM(0x80000002UL));
+    rb_define_const(mWinreg, "HKEY_USERS",          ULONG2NUM(0x80000003UL));
+    rb_define_const(mWinreg, "HKEY_CURRENT_CONFIG", ULONG2NUM(0x80000005UL));
+
+    /* Key: no public .new — instances come only from Winreg.open/create and
+     * Key#open/create. The allocator exists so a GC'd never-initialized Key
+     * is inert (closed sentinel). */
+    cKey = rb_define_class_under(mWinreg, "Key", rb_cObject);
+    rb_define_alloc_func(cKey, key_alloc);
+    rb_undef_method(rb_singleton_class(cKey), "new");
+    rb_define_singleton_method(cKey, "_open", key_s_open, 3);
+    rb_define_singleton_method(cKey, "_create", key_s_create, 3);
+    rb_define_private_method(cKey, "_open_child", key_open_child, 2);
+    rb_define_private_method(cKey, "_create_child", key_create_child, 2);
+    rb_define_private_method(cKey, "_read_raw", key_read_raw, 1);
+    rb_define_private_method(cKey, "_value_p", key_value_p, 1);
+    rb_define_private_method(cKey, "_write_raw", key_write_raw, 3);
+    rb_define_private_method(cKey, "_delete_value", key_delete_value, 1);
+    rb_define_private_method(cKey, "_delete_key", key_delete_key, 1);
+    rb_define_private_method(cKey, "_enum_value", key_enum_value, 1);
+    rb_define_private_method(cKey, "_enum_key", key_enum_key, 1);
+    rb_define_private_method(cKey, "_query_info", key_query_info, 0);
+    rb_define_method(cKey, "close", key_close, 0);
+    rb_define_method(cKey, "closed?", key_closed_p, 0);
+    rb_define_method(cKey, "created?", key_created_p, 0);
+
+    /* Watch: constructed only via Key#watch. */
+    cWatch = rb_define_class_under(mWinreg, "Watch", rb_cObject);
+    rb_define_alloc_func(cWatch, watch_alloc);
+    rb_undef_method(rb_singleton_class(cWatch), "new");
+    rb_define_singleton_method(cWatch, "_new", watch_s_new, 5);
+    rb_define_private_method(cWatch, "_wait", watch_wait, 1);
+    rb_define_method(cWatch, "close", watch_close, 0);
+    rb_define_method(cWatch, "closed?", watch_closed_p, 0);
+
+    rb_define_module_function(mWinreg, "_expand", wr_expand, 1);
+}