winlog 0.1.0

data/ext/winlog/winlog.cpp

@@ -0,0 +1,788 @@
+/*
+ * winlog — structured, registration-free ETW TraceLogging emit for Ruby.
+ *
+ * The suite's FIRST C++ extension, by necessity: a runtime-dynamic
+ * log(level, event, **fields) API cannot use TraceLoggingProvider.h (which
+ * needs compile-time-constant provider/event/field names). Microsoft's
+ * supported answer for runtime-dynamic events is TraceLoggingDynamic.h, which
+ * is C++-only (templates + std::vector). It is vendored verbatim into
+ * ext/winlog/TraceLoggingDynamic.h, MIT-licensed (c) Microsoft Corporation,
+ * from microsoft/tracelogging (etw/cpp/traceloggingdynamic). The header is a
+ * point-in-time copy (see plans/research/tracelogging.md §1/§12 for provenance:
+ * the same file built and ran in the research spike on this machine).
+ *
+ * ----------------------------------------------------------------------------
+ * C++ / rb_raise HYGIENE (the lithos discipline, adapted — see §3.6 of the
+ * spec). Invariants, in order of precedence:
+ *   1. No C++ exception ever crosses into Ruby frames. Every region that runs
+ *      tld / std::vector code is wrapped try { ... } catch (...) and converted
+ *      to rb_raise from a frame that holds no live C++ object.
+ *   2. No rb_raise longjmp ever crosses a frame holding a live C++ object. The
+ *      tld::Event is heap-allocated (new), owned by the _write frame as a raw
+ *      pointer, and delete'd on EVERY exit path before any raise. No
+ *      stack-scoped C++ objects with destructors live in any frame a longjmp
+ *      can cross.
+ *   3. All argument coercion / validation happens up front, before the
+ *      tld::Event exists.
+ *
+ * GVL STRATEGY — every call HOLDS the GVL (documented deviation, spec §3.5).
+ * Nothing in winlog blocks on the kernel:
+ *   | call                                   | GVL  | why                       |
+ *   | EventRegister + EventSetInformation    | hold | µs-scale; MUST serialize  |
+ *   |   (via tld::Provider ctor)             |      |   vs unregister; GVL=lock |
+ *   | EventWriteTransfer (tld::Event::Write) | hold | non-blocking buffer copy  |
+ *   | EventUnregister (close / GC free)      | hold | same as register          |
+ *   | EventActivityIdControl(CREATE_ID)      | hold | trivial                   |
+ * Consequence: no ubf, no OVERLAPPED, no cancellation logic anywhere.
+ *
+ * INCLUDE-ORDER TRAP (mswin, research §2): <ruby.h> MUST precede <windows.h>.
+ * ruby/win32.h pulls <winsock2.h>; a bare <windows.h> first pulls <winsock.h>
+ * -> C2375 redefinition storm. Never name an identifier IN/OUT. mkmf already
+ * injects -D_WIN32_WINNT=_WIN32_WINNT_WIN8 (verified) — do not redefine it.
+ *
+ * E15 (DLL-unload crash hazard) / E16 (fork): not reachable on MRI. MRI never
+ * FreeLibrary's an extension .so before process exit, winlog has no DllMain,
+ * and every other path unregisters first (explicit close, GC free hook). fork
+ * does not exist on mswin. Nothing to implement (spec §5 E15/E16).
+ */
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <evntprov.h>
+
+#include <vector>
+#include "TraceLoggingDynamic.h"
+
+#include <limits.h>
+#include <string.h>
+
+typedef tld::Event<std::vector<BYTE> > DynEvent;
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mWinlog;
+static VALUE cProvider;
+static VALUE eError;    /* Winlog::Error  < StandardError */
+static VALUE eClosed;   /* Winlog::Closed < Winlog::Error */
+
+/* Reserved keyword bits 48..63 (Microsoft-defined). Mirrors the Ruby constant
+ * Winlog::KEYWORD_RESERVED_MASK (spec §2.1 / E3). */
+#define WINLOG_KEYWORD_RESERVED_MASK 0xFFFF000000000000ULL
+
+/* ---------------------------------------------------------- native struct */
+
+typedef struct {
+    tld::Provider *prov;   /* heap; owns REGHANDLE + provider metadata blob */
+    int closed;
+} provider_t;
+
+static void
+provider_free(void *p)
+{
+    provider_t *pt = (provider_t *)p;
+    /* The tld::Provider destructor calls EventUnregister and HeapFree's the
+     * metadata blob. Finalizer is a safety net, never the API (spec §3.4):
+     * explicit idempotent close + Winlog.open's block form exist. */
+    if (pt->prov) {
+        delete pt->prov;
+        pt->prov = NULL;
+    }
+    xfree(pt);
+}
+
+static size_t
+provider_memsize(const void *p)
+{
+    const provider_t *pt = (const provider_t *)p;
+    /* Safe even after a failed registration: InitFail frees the real blob and
+     * points m_pbMetadata at the static 3-byte NullMetadata, so
+     * GetMetadataSize() returns 3 (not a dangling read). */
+    return sizeof(provider_t) +
+           (pt->prov ? (size_t)pt->prov->GetMetadataSize() : 0);
+}
+
+static const rb_data_type_t provider_type = {
+    "Winlog::Provider",
+    { 0, provider_free, provider_memsize, },   /* no dmark: no VALUEs in struct */
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+provider_alloc(VALUE klass)
+{
+    provider_t *pt;
+    VALUE obj = TypedData_Make_Struct(klass, provider_t, &provider_type, pt);
+    pt->prov = NULL;    /* a GC'd never-initialized object is safe to free */
+    pt->closed = 0;
+    return obj;
+}
+
+/* Raw getter (close/closed?/inspect must work on closed objects). */
+static provider_t *
+provider_get(VALUE self)
+{
+    provider_t *pt;
+    TypedData_Get_Struct(self, provider_t, &provider_type, pt);
+    return pt;
+}
+
+/* Live getter: raises Winlog::Closed on a closed or never-registered object
+ * (E19/E20). An .allocate'd instance has prov == NULL -> Closed, never a crash. */
+static provider_t *
+provider_live(VALUE self)
+{
+    provider_t *pt = provider_get(self);
+    if (pt->prov == NULL || pt->closed)
+        rb_raise(eClosed, "winlog: provider is closed");
+    return pt;
+}
+
+/* ------------------------------------------------------------- GUID format */
+
+/* GUID -> 36-char lowercase hyphenated UTF-8 String. */
+static VALUE
+guid_to_rb(GUID const &g)
+{
+    char buf[40];
+    snprintf(buf, sizeof buf,
+             "%08lx-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x",
+             (unsigned long)g.Data1, g.Data2, g.Data3,
+             g.Data4[0], g.Data4[1], g.Data4[2], g.Data4[3],
+             g.Data4[4], g.Data4[5], g.Data4[6], g.Data4[7]);
+    return rb_utf8_str_new_cstr(buf);
+}
+
+/* Parse a strict 36-char lowercase-or-uppercase hyphenated GUID String into a
+ * GUID. Returns 1 on success, 0 on any deviation from the canonical form
+ * (E29: braced {...}, hyphenless, wrong length all rejected). Case-insensitive
+ * per the spec ("activity: 36-char hyphenated GUID String (case-insensitive)").
+ * Pure C parsing — no Ruby allocation, safe to call before any C++ object. */
+static int
+parse_guid(VALUE str, GUID *out)
+{
+    const char *s;
+    long len;
+    int i;
+    unsigned int b[16];        /* the 16 data bytes, in display order */
+    static const int hyphen_at[4] = { 8, 13, 18, 23 };
+    int bi = 0;
+
+    Check_Type(str, T_STRING);
+    s = RSTRING_PTR(str);
+    len = RSTRING_LEN(str);
+    if (len != 36)
+        return 0;
+
+    for (i = 0; i < 36; i++) {
+        char c = s[i];
+        if (i == hyphen_at[0] || i == hyphen_at[1] ||
+            i == hyphen_at[2] || i == hyphen_at[3]) {
+            if (c != '-') return 0;
+            continue;
+        }
+        if (!((c >= '0' && c <= '9') ||
+              (c >= 'a' && c <= 'f') ||
+              (c >= 'A' && c <= 'F')))
+            return 0;
+    }
+
+    /* Re-scan, packing hex pairs into 16 bytes (display byte order). */
+    {
+        int pos = 0;
+        while (pos < 36 && bi < 16) {
+            if (s[pos] == '-') { pos++; continue; }
+            {
+                char pair[3];
+                pair[0] = s[pos];
+                pair[1] = s[pos + 1];
+                pair[2] = 0;
+                b[bi++] = (unsigned int)strtoul(pair, NULL, 16);
+                pos += 2;
+            }
+        }
+        if (bi != 16)
+            return 0;
+    }
+
+    /* Display order is big-endian for Data1/2/3; assemble accordingly. */
+    out->Data1 = ((DWORD)b[0] << 24) | ((DWORD)b[1] << 16) |
+                 ((DWORD)b[2] << 8)  | (DWORD)b[3];
+    out->Data2 = (WORD)(((unsigned)b[4] << 8) | (unsigned)b[5]);
+    out->Data3 = (WORD)(((unsigned)b[6] << 8) | (unsigned)b[7]);
+    for (i = 0; i < 8; i++)
+        out->Data4[i] = (BYTE)b[8 + i];
+    return 1;
+}
+
+/* ------------------------------------------------- field name / event name */
+
+/* Transcode a String to UTF-8 with String#encode semantics (the strict path):
+ *  - already UTF-8: returned as-is (the caller checks coderange/NUL).
+ *  - other encoding: rb_str_encode, which RAISES Ruby's own
+ *    Encoding::UndefinedConversionError on a byte with no UTF-8 mapping (E22) —
+ *    unlike rb_str_export_to_enc, which silently substitutes. This matches the
+ *    spec's "bytes with no UTF-8 mapping raise Encoding::UndefinedConversionError".
+ * Raises from a clean frame (no C++ object live). */
+static VALUE
+transcode_utf8(VALUE str)
+{
+    rb_encoding *u8 = rb_utf8_encoding();
+    if (rb_enc_get(str) == u8)
+        return str;
+    return rb_str_encode(str, rb_enc_from_encoding(u8), 0, Qnil);
+}
+
+/* Coerce a Symbol/String name to a UTF-8 String, validating: non-empty, no
+ * embedded NUL (ETW requirement, E6), no broken UTF-8 coderange (E22). Raises
+ * ArgumentError/TypeError from a clean frame (no C++ object live). +what+ is
+ * "event name" or a field name for the message. Returns the (possibly new)
+ * UTF-8 String VALUE; the caller must keep it referenced while using its ptr. */
+static VALUE
+coerce_name_utf8(VALUE v, const char *what)
+{
+    VALUE str;
+
+    if (SYMBOL_P(v)) {
+        str = rb_sym2str(v);   /* already UTF-8 */
+    } else if (RB_TYPE_P(v, T_STRING)) {
+        str = v;
+    } else {
+        rb_raise(rb_eTypeError, "winlog: %s must be a String or Symbol, got %" PRIsVALUE,
+                 what, rb_obj_class(v));
+    }
+
+    str = transcode_utf8(str);
+
+    if (RSTRING_LEN(str) == 0)
+        rb_raise(rb_eArgError, "winlog: %s must not be empty", what);
+    if (rb_enc_str_coderange(str) == ENC_CODERANGE_BROKEN)
+        rb_raise(rb_eArgError, "winlog: %s is not valid UTF-8", what);
+    if (memchr(RSTRING_PTR(str), '\0', RSTRING_LEN(str)) != NULL)
+        rb_raise(rb_eArgError, "winlog: %s must not contain a NUL byte", what);
+
+    return str;
+}
+
+/* =================================================================
+ * Field building (the hot path). add_field_i runs under rb_hash_foreach,
+ * itself under rb_protect, with the tld::Event owned on the heap OUTSIDE this
+ * frame. add_field_i MAY rb_raise directly (TypeError/ArgumentError/RangeError
+ * with the field name): the longjmp unwinds through rb_hash_foreach
+ * (longjmp-safe) and is caught by rb_protect, crossing NO frame that holds a
+ * live C++ object. Every tld:: call here is individually try/catch(...)-wrapped
+ * so std::bad_alloc never unwinds through rb_hash_foreach's bookkeeping.
+ * =================================================================*/
+
+struct build_ctx {
+    DynEvent *ev;
+    int oom;            /* set if any tld:: call threw (std::bad_alloc etc.) */
+};
+
+/* GC-compaction rule (spec §3.6): do every Ruby-side op (Symbol->String,
+ * transcode) FIRST, then take RSTRING_PTR and immediately copy into the event.
+ * The tld Add* calls are pure C++ (no Ruby allocation between pointer fetch and
+ * copy), GVL held throughout, so no concurrent GC moves the buffer.
+ *
+ * COMPACTION PITFALL (do not reintroduce): RSTRING_PTR(fname_str) must be taken
+ * only AFTER each branch's LAST Ruby allocation, never once at the top. In the
+ * text branch transcode_utf8(val) calls rb_str_encode, a Ruby allocation that
+ * can trigger GC compaction and relocate fname_str's character buffer; a fname
+ * pointer captured before it would be stale when AddString does strlen+memcpy.
+ * So fname is fetched immediately before the AddField/AddString pair in every
+ * branch, with no Ruby allocation in between. RB_GC_GUARD pins fname_str against
+ * collection; the late fetch handles movement. */
+static int
+add_field_i(VALUE key, VALUE val, VALUE arg)
+{
+    struct build_ctx *ctx = (struct build_ctx *)arg;
+    DynEvent *ev = ctx->ev;
+    VALUE fname_str = coerce_name_utf8(key, "field name");
+    const char *fname;   /* fetched late, per-branch — see header note */
+
+    switch (TYPE(val)) {
+    case T_STRING: {
+        if (rb_enc_get_index(val) == rb_ascii8bit_encindex()) {
+            /* BINARY -> TypeBinary (UINT16-counted). E7: > 65535 bytes. */
+            long n = RSTRING_LEN(val);
+            if (n > 0xFFFF) {
+                fname = RSTRING_PTR(fname_str);
+                rb_raise(rb_eArgError,
+                         "winlog: binary field %s is %ld bytes (max 65535)",
+                         fname, n);
+            }
+            /* No Ruby allocation past this point in this branch. */
+            fname = RSTRING_PTR(fname_str);
+            try {
+                ev->AddField(fname, tld::TypeBinary);
+                ev->AddBinary(RSTRING_PTR(val), (UINT16)n);
+            } catch (...) { ctx->oom = 1; return ST_STOP; }
+        } else {
+            /* text -> TypeUtf8String (NUL-terminated). Transcode + validate
+             * (E6 embedded NUL would silently truncate; E22 broken UTF-8;
+             * unmappable bytes raise Encoding::UndefinedConversionError).
+             * transcode_utf8 may allocate (rb_str_encode) and move fname_str,
+             * so fname is fetched only AFTER it. */
+            VALUE utf8 = transcode_utf8(val);
+            if (rb_enc_str_coderange(utf8) == ENC_CODERANGE_BROKEN) {
+                fname = RSTRING_PTR(fname_str);
+                rb_raise(rb_eArgError,
+                         "winlog: text field %s is not valid UTF-8", fname);
+            }
+            if (memchr(RSTRING_PTR(utf8), '\0', RSTRING_LEN(utf8)) != NULL) {
+                fname = RSTRING_PTR(fname_str);
+                rb_raise(rb_eArgError,
+                         "winlog: text field %s contains a NUL byte "
+                         "(use a binary string for raw bytes)", fname);
+            }
+            {
+                /* fname and cstr fetched back-to-back, no allocation between
+                 * here and the Add* copy. */
+                fname = RSTRING_PTR(fname_str);
+                const char *cstr = RSTRING_PTR(utf8);
+                try {
+                    ev->AddField(fname, tld::TypeUtf8String);
+                    ev->AddString(cstr);
+                } catch (...) { ctx->oom = 1; return ST_STOP; }
+                RB_GC_GUARD(utf8);
+            }
+        }
+        break;
+    }
+    case T_FIXNUM:
+    case T_BIGNUM: {
+        INT64 v = (INT64)NUM2LL(val);   /* RangeError outside INT64 (E9) */
+        fname = RSTRING_PTR(fname_str);
+        try {
+            ev->AddField(fname, tld::TypeInt64);
+            ev->AddValue(v);
+        } catch (...) { ctx->oom = 1; return ST_STOP; }
+        break;
+    }
+    case T_FLOAT: {
+        double v = NUM2DBL(val);
+        fname = RSTRING_PTR(fname_str);
+        try {
+            ev->AddField(fname, tld::TypeDouble);
+            ev->AddValue(v);
+        } catch (...) { ctx->oom = 1; return ST_STOP; }
+        break;
+    }
+    case T_TRUE:
+    case T_FALSE: {
+        INT32 v = (val == Qtrue) ? 1 : 0;
+        fname = RSTRING_PTR(fname_str);
+        try {
+            ev->AddField(fname, tld::TypeBool32);
+            ev->AddValue(v);
+        } catch (...) { ctx->oom = 1; return ST_STOP; }
+        break;
+    }
+    default:
+        fname = RSTRING_PTR(fname_str);
+        rb_raise(rb_eTypeError,
+                 "winlog: unsupported value type for field %s "
+                 "(String, Integer, Float, true, or false; "
+                 "nil and others are rejected)", fname);
+    }
+
+    RB_GC_GUARD(fname_str);
+    return ST_CONTINUE;
+}
+
+struct foreach_args {
+    VALUE fields;
+    struct build_ctx *ctx;
+};
+
+static VALUE
+build_fields_protected(VALUE a)
+{
+    struct foreach_args *fa = (struct foreach_args *)a;
+    rb_hash_foreach(fa->fields, add_field_i, (VALUE)fa->ctx);
+    return Qnil;
+}
+
+/* Core build + write. UNGATED. Returns the HRESULT as an Integer. Validation of
+ * the event name and control args happens BEFORE the heap event exists; field
+ * values are validated inside add_field_i (only reached here, i.e. only when
+ * the caller decided to build). The tld::Event is heap-owned by THIS frame and
+ * delete'd on every exit path before any raise (hygiene invariant 2). */
+static VALUE
+do_write(provider_t *pt, VALUE event, VALUE fields,
+         ULONGLONG keyword, UCHAR level, UCHAR opcode,
+         GUID *pActivity, GUID *pRelated)
+{
+    VALUE ev_name = coerce_name_utf8(event, "event name");
+    const char *name = RSTRING_PTR(ev_name);
+    DynEvent *ev = NULL;
+    HRESULT hr;
+    int state = 0;
+    struct build_ctx ctx;
+    struct foreach_args fa;
+
+    /* Construct the heap event. The ctor builds metadata via std::vector and
+     * can throw std::bad_alloc; nothing is leaked on throw (ctor cleanup). */
+    try {
+        ev = new DynEvent(name, level, keyword,
+                          0 /*tags*/, opcode, 0 /*task*/,
+                          pActivity, pRelated);
+    } catch (...) {
+        ev = NULL;
+    }
+    RB_GC_GUARD(ev_name);   /* keep name alive across the ctor */
+    if (ev == NULL)
+        rb_raise(rb_eNoMemError, "winlog: out of memory building event");
+
+    ctx.ev = ev;
+    ctx.oom = 0;
+    fa.fields = fields;
+    fa.ctx = &ctx;
+
+    if (!NIL_P(fields))
+        rb_protect(build_fields_protected, (VALUE)&fa, &state);
+
+    if (state) { delete ev; rb_jump_tag(state); }          /* re-raise clean */
+    if (ctx.oom) {
+        delete ev;
+        rb_raise(rb_eNoMemError, "winlog: out of memory building event");
+    }
+
+    try {
+        hr = ev->Write(*pt->prov);
+    } catch (...) {
+        delete ev;
+        rb_raise(rb_eNoMemError, "winlog: out of memory writing event");
+    }
+
+    delete ev;
+    return INT2NUM((int)hr);
+}
+
+/* --------------------------------------------------- control-arg helpers */
+
+/* level: Symbol already mapped to Integer by the Ruby layer; here we accept an
+ * Integer 1..255 (E5: 0 rejected). Raises ArgumentError from a clean frame. */
+static UCHAR
+level_to_uchar(VALUE vlevel)
+{
+    long lv = NUM2LONG(vlevel);
+    if (lv < 1 || lv > 255)
+        rb_raise(rb_eArgError,
+                 "winlog: level must be 1..255 (got %ld); 0 is not a valid "
+                 "ETW level", lv);
+    return (UCHAR)lv;
+}
+
+/* keyword: Integer 0..0x0000_FFFF_FFFF_FFFF. Reserved bits 48..63 -> ArgError
+ * (E3). Negative -> ArgError. Non-Integer is rejected by NUM2ULL/Check before. */
+static ULONGLONG
+keyword_to_ull(VALUE vkw)
+{
+    /* Reject negatives explicitly: NUM2ULL would wrap them. */
+    if (RB_TYPE_P(vkw, T_FIXNUM) || RB_TYPE_P(vkw, T_BIGNUM)) {
+        if (rb_funcall(vkw, rb_intern("<"), 1, INT2FIX(0)) == Qtrue)
+            rb_raise(rb_eArgError, "winlog: keyword must not be negative");
+    } else {
+        rb_raise(rb_eTypeError, "winlog: keyword must be an Integer");
+    }
+    {
+        ULONGLONG kw = (ULONGLONG)NUM2ULL(vkw);
+        if (kw & WINLOG_KEYWORD_RESERVED_MASK)
+            rb_raise(rb_eArgError,
+                     "winlog: keyword bits 48..63 are reserved by Microsoft "
+                     "(mask 0x%016llX)", (unsigned long long)WINLOG_KEYWORD_RESERVED_MASK);
+        return kw;
+    }
+}
+
+/* opcode: Integer 0..255 (Ruby layer maps Symbols to Integers first). */
+static UCHAR
+opcode_to_uchar(VALUE vop)
+{
+    long op = NUM2LONG(vop);
+    if (op < 0 || op > 255)
+        rb_raise(rb_eArgError, "winlog: opcode must be 0..255 (got %ld)", op);
+    return (UCHAR)op;
+}
+
+/* =================================================================
+ * Winlog::Provider — C methods
+ * =================================================================*/
+
+/* Provider#_register(name) — construct + register the tld::Provider. Called by
+ * Ruby initialize AFTER name validation. Double-init guard (lithos pattern):
+ * raise Winlog::Error if already registered or closed (T11). Never raises on
+ * EventRegister failure: the tld handle is a benign no-op (E11). */
+static VALUE
+provider_register(VALUE self, VALUE name)
+{
+    provider_t *pt = provider_get(self);
+    const char *cname;
+
+    if (pt->prov != NULL || pt->closed)
+        rb_raise(eError, "winlog: provider already registered");
+
+    /* name is a validated printable-ASCII String from the Ruby layer; a strict
+     * subset of UTF-8, safe for the char* (UTF-8) tld ctor. NUL-terminate via
+     * StringValueCStr (raises ArgumentError on an embedded NUL — defense in
+     * depth; the Ruby validator already forbids it). */
+    cname = StringValueCStr(name);
+
+    try {
+        pt->prov = new tld::Provider(cname);
+    } catch (...) {
+        pt->prov = NULL;
+    }
+    if (pt->prov == NULL)
+        rb_raise(rb_eNoMemError, "winlog: out of memory registering provider");
+
+    return self;
+}
+
+/* Provider#_write(level, event, fields, keyword, opcode, act_or_nil, rel_or_nil)
+ * UNGATED build+write, returns HRESULT Integer. Test/benchmark plumbing only
+ * (spec §3.3): EventWriteTransfer returns S_OK with no listener, so the full
+ * build path is exercisable without an elevated session. */
+static VALUE
+provider_write(VALUE self, VALUE vlevel, VALUE event, VALUE fields,
+               VALUE vkeyword, VALUE vopcode, VALUE vact, VALUE vrel)
+{
+    provider_t *pt = provider_live(self);
+    UCHAR level = level_to_uchar(vlevel);
+    ULONGLONG keyword = keyword_to_ull(vkeyword);
+    UCHAR opcode = opcode_to_uchar(vopcode);
+    GUID act, rel;
+    GUID *pAct = NULL, *pRel = NULL;
+
+    if (!NIL_P(fields))
+        Check_Type(fields, T_HASH);
+
+    /* related: without activity: is meaningless (E18). The Ruby layer also
+     * guards this, but keep the C contract self-standing. */
+    if (!NIL_P(vrel) && NIL_P(vact))
+        rb_raise(rb_eArgError,
+                 "winlog: related activity given without an activity id");
+
+    if (!NIL_P(vact)) {
+        if (!parse_guid(vact, &act))
+            rb_raise(rb_eArgError,
+                     "winlog: activity must be a 36-char hyphenated GUID string");
+        pAct = &act;
+    }
+    if (!NIL_P(vrel)) {
+        if (!parse_guid(vrel, &rel))
+            rb_raise(rb_eArgError,
+                     "winlog: related must be a 36-char hyphenated GUID string");
+        pRel = &rel;
+    }
+
+    return do_write(pt, event, fields, keyword, level, opcode, pAct, pRel);
+}
+
+/* Provider#_log(level, event, fields) — the full gated public path. Extracts
+ * control kwargs from +fields+ (rb_hash_lookup2 with a Qundef sentinel: cheap,
+ * no allocation, not iteration), validates them ALWAYS (E1), gates on
+ * IsEnabled(level, keyword), and only then builds+writes. The disabled return
+ * (Qfalse) happens BEFORE any field value is read (E1/E2 asymmetry). */
+static VALUE
+provider_log(VALUE self, VALUE vlevel, VALUE event, VALUE fields)
+{
+    provider_t *pt = provider_live(self);
+    UCHAR level = level_to_uchar(vlevel);   /* always validated */
+    VALUE vkw, vop, vact, vrel;
+    ULONGLONG keyword;
+    UCHAR opcode;
+    GUID act, rel;
+    GUID *pAct = NULL, *pRel = NULL;
+    VALUE hr;
+
+    Check_Type(fields, T_HASH);
+
+    /* Extract reserved control kwargs by exact Symbol key. String keys with the
+     * same text are NEVER control args (E21) — they stay as fields. */
+    vkw  = rb_hash_lookup2(fields, ID2SYM(rb_intern("keyword")),  Qundef);
+    vop  = rb_hash_lookup2(fields, ID2SYM(rb_intern("opcode")),   Qundef);
+    vact = rb_hash_lookup2(fields, ID2SYM(rb_intern("activity")), Qundef);
+    vrel = rb_hash_lookup2(fields, ID2SYM(rb_intern("related")),  Qundef);
+
+    keyword = (vkw == Qundef) ? 0ULL : keyword_to_ull(vkw);   /* always validated */
+
+    if (vop == Qundef) {
+        opcode = 0;
+    } else {
+        opcode = opcode_to_uchar(vop);    /* Ruby layer maps Symbols first */
+    }
+
+    /* related: without activity: -> ArgumentError, even disabled (E18, E1). */
+    if (vrel != Qundef && (vact == Qundef || NIL_P(vact)))
+        rb_raise(rb_eArgError,
+                 "winlog: related activity given without an activity id");
+
+    if (vact != Qundef && !NIL_P(vact)) {
+        if (!parse_guid(vact, &act))
+            rb_raise(rb_eArgError,
+                     "winlog: activity must be a 36-char hyphenated GUID string");
+        pAct = &act;
+    }
+    if (vrel != Qundef && !NIL_P(vrel)) {
+        if (!parse_guid(vrel, &rel))
+            rb_raise(rb_eArgError,
+                     "winlog: related must be a 36-char hyphenated GUID string");
+        pRel = &rel;
+    }
+
+    /* Validate the event name on EVERY call (E1/E6), enabled or not. This both
+     * matches the documented "control args always validated" contract and
+     * coerces from a clean frame before any C++ object exists. */
+    (void)coerce_name_utf8(event, "event name");
+
+    /* The gate. No system call; reads in-process enable state (E1, ~0.4 ns). */
+    if (!pt->prov->IsEnabled(level, keyword))
+        return Qfalse;
+
+    /* Enabled: build + write. Strip the control kwargs out so they are not
+     * emitted as fields. dup so we never mutate the caller's hash. */
+    {
+        VALUE eff = fields;
+        if (vkw != Qundef || vop != Qundef || vact != Qundef || vrel != Qundef) {
+            eff = rb_hash_dup(fields);
+            if (vkw  != Qundef) rb_hash_delete(eff, ID2SYM(rb_intern("keyword")));
+            if (vop  != Qundef) rb_hash_delete(eff, ID2SYM(rb_intern("opcode")));
+            if (vact != Qundef) rb_hash_delete(eff, ID2SYM(rb_intern("activity")));
+            if (vrel != Qundef) rb_hash_delete(eff, ID2SYM(rb_intern("related")));
+        }
+        hr = do_write(pt, event, eff, keyword, level, opcode, pAct, pRel);
+    }
+
+    /* hr success (S_OK == 0) -> true; any ETW drop -> false (never raise, E8). */
+    return (NUM2INT(hr) == 0) ? Qtrue : Qfalse;
+}
+
+/* Provider#_enabled(level_or_nil, keyword) — IsEnabled bridge. level nil means
+ * "enabled at any level" (uses IsEnabled() / level 0xFF probe semantics). */
+static VALUE
+provider_enabled(VALUE self, VALUE vlevel, VALUE vkeyword)
+{
+    provider_t *pt = provider_live(self);
+    ULONGLONG keyword = keyword_to_ull(vkeyword);
+
+    if (NIL_P(vlevel)) {
+        /* "any level": enabled at all, with the keyword filter applied. Level 1
+         * (most restrictive that any session enabling implies) — but tld's
+         * IsEnabled(level,keyword) checks level < m_levelPlus1, so to mean "any
+         * level enabled" we probe with level 1 (a session enabling at any level
+         * L >= 1 sets m_levelPlus1 >= 2, so 1 < m_levelPlus1 holds). Combined
+         * with the keyword check this is the documented "enabled at any level"
+         * gate. */
+        UCHAR level = 1;
+        return pt->prov->IsEnabled(level, keyword) ? Qtrue : Qfalse;
+    } else {
+        UCHAR level = level_to_uchar(vlevel);
+        return pt->prov->IsEnabled(level, keyword) ? Qtrue : Qfalse;
+    }
+}
+
+/* Provider#guid -> 36-char lowercase hyphenated String (from tld Provider::Id,
+ * authoritative; equals Winlog.guid_for(name)). Set before Init runs, untouched
+ * by registration failure (E11). Raises Winlog::Closed after close. */
+static VALUE
+provider_guid(VALUE self)
+{
+    provider_t *pt = provider_live(self);
+    return guid_to_rb(pt->prov->Id());
+}
+
+/* Provider#registered? -> true if EventRegister succeeded (E11). */
+static VALUE
+provider_registered_p(VALUE self)
+{
+    provider_t *pt = provider_live(self);
+    return SUCCEEDED(pt->prov->InitializationResult()) ? Qtrue : Qfalse;
+}
+
+/* Provider#registration_result -> raw HRESULT Integer; 0 on success. */
+static VALUE
+provider_registration_result(VALUE self)
+{
+    provider_t *pt = provider_live(self);
+    return INT2NUM((int)pt->prov->InitializationResult());
+}
+
+/* Provider#close -> nil. Idempotent (E20). Unregister + free the native
+ * provider now; safe to call again, on a never-registered object, etc. */
+static VALUE
+provider_close(VALUE self)
+{
+    provider_t *pt = provider_get(self);
+    if (pt->prov) {
+        delete pt->prov;     /* tld dtor: EventUnregister + HeapFree metadata */
+        pt->prov = NULL;
+    }
+    pt->closed = 1;
+    return Qnil;
+}
+
+/* Provider#closed? -> true/false. */
+static VALUE
+provider_closed_p(VALUE self)
+{
+    provider_t *pt = provider_get(self);
+    return (pt->prov == NULL || pt->closed) ? Qtrue : Qfalse;
+}
+
+/* =================================================================
+ * Module function: Winlog.new_activity_id
+ * =================================================================*/
+
+/* Winlog.new_activity_id -> 36-char lowercase hyphenated GUID String. Wraps
+ * EventActivityIdControl(CREATE_ID), which only GENERATES an id and never reads
+ * or writes the calling thread's implicit activity id (E17 fiber-safety).
+ * Raises Winlog::Error only if the OS call fails (practically never). */
+static VALUE
+winlog_new_activity_id(VALUE self)
+{
+    GUID g;
+    ULONG status;
+
+    memset(&g, 0, sizeof g);
+    status = EventActivityIdControl(EVENT_ACTIVITY_CTRL_CREATE_ID, &g);
+    if (status != ERROR_SUCCESS)
+        rb_raise(eError,
+                 "winlog: EventActivityIdControl(CREATE_ID) failed (error %lu)",
+                 (unsigned long)status);
+    return guid_to_rb(g);
+}
+
+/* ----------------------------------------------------------------- Init ---- */
+
+extern "C" void
+Init_winlog(void)
+{
+    mWinlog = rb_define_module("Winlog");
+
+    eError  = rb_define_class_under(mWinlog, "Error", rb_eStandardError);
+    eClosed = rb_define_class_under(mWinlog, "Closed", eError);
+
+    cProvider = rb_define_class_under(mWinlog, "Provider", rb_cObject);
+    rb_define_alloc_func(cProvider, provider_alloc);
+
+    /* Private C bridges (underscore convention; hidden by the Ruby layer's
+     * `private`). The validated, keyword-aware public API lives in lib. */
+    rb_define_private_method(cProvider, "_register", RUBY_METHOD_FUNC(provider_register), 1);
+    rb_define_private_method(cProvider, "_log",      RUBY_METHOD_FUNC(provider_log), 3);
+    rb_define_private_method(cProvider, "_write",    RUBY_METHOD_FUNC(provider_write), 7);
+    rb_define_private_method(cProvider, "_enabled",  RUBY_METHOD_FUNC(provider_enabled), 2);
+
+    /* Public read-only / simple methods exposed directly (spec §3.3). */
+    rb_define_method(cProvider, "guid",                RUBY_METHOD_FUNC(provider_guid), 0);
+    rb_define_method(cProvider, "registered?",         RUBY_METHOD_FUNC(provider_registered_p), 0);
+    rb_define_method(cProvider, "registration_result", RUBY_METHOD_FUNC(provider_registration_result), 0);
+    rb_define_method(cProvider, "close",               RUBY_METHOD_FUNC(provider_close), 0);
+    rb_define_method(cProvider, "closed?",             RUBY_METHOD_FUNC(provider_closed_p), 0);
+
+    rb_define_singleton_method(mWinlog, "new_activity_id",
+                               RUBY_METHOD_FUNC(winlog_new_activity_id), 0);
+}