winreg 0.1.0

data/lib/winreg.rb

@@ -0,0 +1,795 @@
+# frozen_string_literal: true
+
+require "winreg/version"
+require "winreg/winreg" # native extension: Key/Watch classes + errors + HKEY_* roots
+
+# winreg — typed Windows registry access for Ruby: exact wire formats,
+# least-privilege opens, WOW64 views as a first-class option, and change
+# notification that cooperates with a fiber scheduler.
+#
+#   Winreg.open('HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion') do |k|
+#     k.string("ProductName")             # => "Windows 10 ..."
+#     k.read("CurrentMajorVersionNumber") # => [:dword, 10]
+#   end
+#
+#   Winreg.create('HKCU\Software\Vendor\App') do |k|
+#     k.write_multi_string("Plugins", %w[alpha beta]) # correct double-NUL wire format
+#     k.watch(filter: :values) { |event| break if event == :deleted }
+#   end
+module Winreg
+  # Registry type tags (verified, winnt.h) — Symbol <-> tag map.
+  TYPES = {
+    none: 0, sz: 1, expand_sz: 2, binary: 3, dword: 4,
+    dword_be: 5, link: 6, multi_sz: 7, qword: 11
+  }.freeze
+
+  TYPE_NAMES = TYPES.invert.freeze
+  private_constant :TYPE_NAMES
+
+  # ---- Win32 flag values (verified, winnt.h) ------------------------------
+  KEY_QUERY_VALUE  = 0x0001
+  KEY_NOTIFY       = 0x0010
+  KEY_READ         = 0x20019 # STANDARD_RIGHTS_READ | QUERY_VALUE | ENUMERATE_SUB_KEYS | NOTIFY
+  KEY_WRITE        = 0x20006 # STANDARD_RIGHTS_WRITE | SET_VALUE | CREATE_SUB_KEY
+  KEY_WOW64_64KEY  = 0x0100
+  KEY_WOW64_32KEY  = 0x0200
+  REG_NOTIFY_CHANGE_NAME       = 0x1
+  REG_NOTIFY_CHANGE_ATTRIBUTES = 0x2
+  REG_NOTIFY_CHANGE_LAST_SET   = 0x4
+  REG_NOTIFY_CHANGE_SECURITY   = 0x8
+
+  # Root tokens (case-insensitive, short and long forms) -> predefined handle.
+  ROOTS = {
+    "HKCR" => HKEY_CLASSES_ROOT,   "HKEY_CLASSES_ROOT"   => HKEY_CLASSES_ROOT,
+    "HKCU" => HKEY_CURRENT_USER,   "HKEY_CURRENT_USER"   => HKEY_CURRENT_USER,
+    "HKLM" => HKEY_LOCAL_MACHINE,  "HKEY_LOCAL_MACHINE"  => HKEY_LOCAL_MACHINE,
+    "HKU"  => HKEY_USERS,          "HKEY_USERS"          => HKEY_USERS,
+    "HKCC" => HKEY_CURRENT_CONFIG, "HKEY_CURRENT_CONFIG" => HKEY_CURRENT_CONFIG
+  }.freeze
+  private_constant :ROOTS
+
+  ROOT_NAMES = {
+    HKEY_CLASSES_ROOT   => "HKEY_CLASSES_ROOT",
+    HKEY_CURRENT_USER   => "HKEY_CURRENT_USER",
+    HKEY_LOCAL_MACHINE  => "HKEY_LOCAL_MACHINE",
+    HKEY_USERS          => "HKEY_USERS",
+    HKEY_CURRENT_CONFIG => "HKEY_CURRENT_CONFIG"
+  }.freeze
+  private_constant :ROOT_NAMES
+
+  # FILETIME epoch (1601-01-01) offset from the Unix epoch, in 100ns ticks.
+  FILETIME_EPOCH_DELTA = 116_444_736_000_000_000
+  private_constant :FILETIME_EPOCH_DELTA
+
+  # A Windows API failure carries the originating error code (the LSTATUS /
+  # Win32 code), set on the exception in C.
+  class OSError
+    def code
+      @code
+    end
+  end
+
+  module_function
+
+  # Run a blocking native call cooperatively. Under a Fiber scheduler (e.g.
+  # winloop) the call is offloaded to a worker Thread so the calling fiber
+  # parks (Thread#value routes through the scheduler) and the event loop keeps
+  # serving other fibers; with no scheduler it runs inline (the C call already
+  # releases the GVL). On fiber unwind the worker is killed+joined so it can't
+  # leak. Registry watch registrations are REG_NOTIFY_THREAD_AGNOSTIC, so the
+  # ephemeral workers are sound (a registration does not die with its thread).
+  #
+  # Caveat: a fiber unwound (e.g. Timeout) after the worker observed :changed
+  # but before value delivery loses that one delivery — harmless here, because
+  # :changed is stateless ("go look") and the registration stays armed.
+  def run_blocking
+    sched = Fiber.scheduler
+    return yield unless sched
+
+    worker = Thread.new do
+      Thread.current.report_on_exception = false
+      yield
+    end
+    begin
+      worker.value
+    ensure
+      if worker.alive?
+        worker.kill
+        worker.join
+      end
+    end
+  end
+
+  # Seconds (nil = infinite) -> milliseconds for the C layer (-1 = INFINITE).
+  # Never collapse a tiny-but-positive wait into a non-blocking poll.
+  def ms_for(timeout)
+    return -1 if timeout.nil?
+
+    t = Float(timeout)
+    raise ArgumentError, "timeout must be non-negative, got #{timeout.inspect}" if t.negative?
+
+    ms = (t * 1000).round
+    ms.zero? && t.positive? ? 1 : ms
+  end
+
+  # Open an existing key. access: :read (default) | :read_write | Integer raw
+  # samDesired (must not contain the WOW64 view bits — the view comes from
+  # view:). view: :default | :v64 | :v32. Yields the Key (ensure-closed) if a
+  # block is given, returning the block's value.
+  def open(path, access: :read, view: :default)
+    root, sub = parse_path(path)
+    sam = access_mask(access) | view_mask(view)
+    k = Key.send(:_open, root, sub, sam)
+    k.send(:_init_meta, root, sub, view)
+    return k unless block_given?
+
+    begin
+      yield k
+    ensure
+      k.close
+    end
+  end
+
+  # Open-or-create a key (creates all missing intermediate keys). Default
+  # access is :read_write — you create keys to write to them. The security
+  # descriptor is inherited from the parent (NULL SECURITY_ATTRIBUTES).
+  def create(path, access: :read_write, view: :default)
+    root, sub = parse_path(path)
+    sam = access_mask(access) | view_mask(view)
+    k = sub.nil? ? Key.send(:_open, root, nil, sam) : Key.send(:_create, root, sub, sam)
+    k.send(:_init_meta, root, sub, view)
+    return k unless block_given?
+
+    begin
+      yield k
+    ensure
+      k.close
+    end
+  end
+
+  # Expand %VAR% references using ExpandEnvironmentStringsW (NOT a Ruby gsub
+  # over ENV — semantics differ: unknown vars stay literal, exactly as the OS
+  # defines). Input/output UTF-8 String.
+  def expand_string(str)
+    _expand(str)
+  end
+
+  private_class_method :_expand
+
+  # "<ROOT>\sub\key" -> [root_handle_value, subpath_or_nil]. Backslash is the
+  # ONLY separator; forward slash is a legal key-name character and is never
+  # translated. One trailing backslash is stripped.
+  def parse_path(path)
+    s = String(path)
+    if s.start_with?("\\\\")
+      raise ArgumentError, "winreg: remote registry is not supported"
+    end
+
+    s = s[0..-2] if s.end_with?("\\")
+    tok, rest = s.split("\\", 2)
+    root = ROOTS[tok.to_s.upcase]
+    unless root
+      raise ArgumentError,
+            "winreg: unknown registry root #{tok.inspect} (accepted: HKCR, HKCU, HKLM, HKU, " \
+            "HKCC or their long HKEY_* forms)"
+    end
+    rest = nil if rest && rest.empty?
+    [root, rest]
+  end
+  private_class_method :parse_path
+
+  def access_mask(access)
+    case access
+    when :read       then KEY_READ
+    when :read_write then KEY_READ | KEY_WRITE
+    when Integer
+      if (access & (KEY_WOW64_64KEY | KEY_WOW64_32KEY)) != 0
+        raise ArgumentError,
+              "winreg: raw access mask must not contain the WOW64 view bits (0x300); " \
+              "pass view: :v64 / :v32 instead"
+      end
+      access
+    else
+      raise ArgumentError, "winreg: access must be :read, :read_write or an Integer mask, " \
+                           "got #{access.inspect}"
+    end
+  end
+  private_class_method :access_mask
+
+  def view_mask(view)
+    case view
+    when :default then 0
+    when :v64     then KEY_WOW64_64KEY
+    when :v32     then KEY_WOW64_32KEY
+    else raise ArgumentError, "winreg: view must be :default, :v64 or :v32, got #{view.inspect}"
+    end
+  end
+  private_class_method :view_mask
+
+  def filter_mask(filter)
+    syms = filter.is_a?(Array) ? filter : [filter]
+    raise ArgumentError, "winreg: watch filter must not be empty" if syms.empty?
+
+    syms.reduce(0) do |mask, sym|
+      mask | case sym
+             when :values     then REG_NOTIFY_CHANGE_LAST_SET
+             when :keys       then REG_NOTIFY_CHANGE_NAME
+             when :attributes then REG_NOTIFY_CHANGE_ATTRIBUTES
+             when :security   then REG_NOTIFY_CHANGE_SECURITY
+             when :default    then REG_NOTIFY_CHANGE_NAME | REG_NOTIFY_CHANGE_LAST_SET
+             when :all
+               REG_NOTIFY_CHANGE_NAME | REG_NOTIFY_CHANGE_ATTRIBUTES |
+                 REG_NOTIFY_CHANGE_LAST_SET | REG_NOTIFY_CHANGE_SECURITY
+             else
+               raise ArgumentError, "winreg: unknown watch filter #{sym.inspect} (accepted: " \
+                                    ":values, :keys, :attributes, :security, :default, :all)"
+             end
+    end
+  end
+  private_class_method :filter_mask
+
+  # An open registry key. Instances come only from Winreg.open/.create and
+  # Key#open/#create (no public .new). All methods raise Winreg::Closed on a
+  # closed key except close/closed?/path/view/created?/inspect.
+  class Key
+    # The C constructors are plumbing; the validated keyword API above is the
+    # only way in (phylax's private-bridge discipline).
+    private_class_method :_open, :_create
+
+    # RegQueryInfoKeyW snapshot. last_write_time is a Time with full 100ns
+    # FILETIME precision (Rational arithmetic).
+    Info = Struct.new(:subkey_count, :value_count, :max_subkey_name_len,
+                      :max_value_name_len, :max_value_data_bytes, :last_write_time)
+
+    # Canonical full path, long-form root ("HKEY_CURRENT_USER\\Software\\X").
+    attr_reader :path
+
+    # :default | :v64 | :v32
+    attr_reader :view
+
+    def inspect
+      closed? ? "#<Winreg::Key (closed)>" : "#<Winreg::Key #{@path} view=#{@view.inspect}>"
+    end
+
+    # ---- reading ----------------------------------------------------------
+
+    # Generic typed read -> [type, value]. type is a Symbol from Winreg::TYPES
+    # (or the raw Integer tag for types outside the table). Strings are
+    # returned UNEXPANDED with at most one trailing NUL stripped; :multi_sz as
+    # Array<String>; integers range-decoded; :binary/:none/:link/unknown as
+    # raw BINARY bytes.
+    def read(name)
+      t, bytes = _read_raw(norm_name(name))
+      [Winreg.send(:type_symbol, t), Winreg.send(:decode_value, t, bytes)]
+    end
+
+    # Like #read, but nil when the value does not exist.
+    def read?(name)
+      read(name)
+    rescue Winreg::NotFound
+      nil
+    end
+
+    # REG_SZ or REG_EXPAND_SZ -> String (UTF-8), unexpanded unless expand:
+    # true (ExpandEnvironmentStringsW on the result, whatever the type).
+    def string(name, expand: false)
+      bytes = typed_bytes(name, [TYPES[:sz], TYPES[:expand_sz]], "REG_SZ/REG_EXPAND_SZ")
+      s = Winreg.send(:decode_string, bytes)
+      expand ? Winreg.expand_string(s) : s
+    end
+
+    # nil for a MISSING value (TypeMismatch still raises — a wrong type is a
+    # bug, not an absence). Same pattern for the other ? readers.
+    def string?(name, expand: false)
+      string(name, expand: expand)
+    rescue Winreg::NotFound
+      nil
+    end
+
+    def dword(name)
+      Winreg.send(:decode_int, typed_bytes(name, [TYPES[:dword]], "REG_DWORD"), 4, false, :dword)
+    end
+
+    def dword?(name)
+      dword(name)
+    rescue Winreg::NotFound
+      nil
+    end
+
+    def qword(name)
+      Winreg.send(:decode_int, typed_bytes(name, [TYPES[:qword]], "REG_QWORD"), 8, false, :qword)
+    end
+
+    def qword?(name)
+      qword(name)
+    rescue Winreg::NotFound
+      nil
+    end
+
+    def multi_string(name)
+      Winreg.send(:decode_multi, typed_bytes(name, [TYPES[:multi_sz]], "REG_MULTI_SZ"))
+    end
+
+    def multi_string?(name)
+      multi_string(name)
+    rescue Winreg::NotFound
+      nil
+    end
+
+    def binary(name)
+      typed_bytes(name, [TYPES[:binary]], "REG_BINARY")
+    end
+
+    def binary?(name)
+      binary(name)
+    rescue Winreg::NotFound
+      nil
+    end
+
+    # Raw escape hatch: NEVER decodes, never raises MalformedValue.
+    # -> [Integer type_tag, String bytes (Encoding::BINARY)]
+    def raw(name)
+      _read_raw(norm_name(name))
+    end
+
+    # ---- writing ----------------------------------------------------------
+
+    # All writers return nil and require access: :read_write (else the OS
+    # raises AccessDenied). The gem owns serialization, so the wire format is
+    # correct by construction (double-NUL REG_MULTI_SZ, cb incl. terminators).
+
+    def write_string(name, str)
+      _write_raw(norm_name(name), TYPES[:sz], Winreg.send(:encode_sz, str))
+      nil
+    end
+
+    def write_expand_string(name, str)
+      _write_raw(norm_name(name), TYPES[:expand_sz], Winreg.send(:encode_sz, str))
+      nil
+    end
+
+    def write_multi_string(name, ary)
+      _write_raw(norm_name(name), TYPES[:multi_sz], Winreg.send(:encode_multi, ary))
+      nil
+    end
+
+    def write_dword(name, int)
+      v = Winreg.send(:int_in_range, int, 0xFFFF_FFFF, "REG_DWORD")
+      _write_raw(norm_name(name), TYPES[:dword], [v].pack("V"))
+      nil
+    end
+
+    def write_qword(name, int)
+      v = Winreg.send(:int_in_range, int, 0xFFFF_FFFF_FFFF_FFFF, "REG_QWORD")
+      _write_raw(norm_name(name), TYPES[:qword], [v].pack("Q<"))
+      nil
+    end
+
+    def write_binary(name, bytes)
+      Winreg.send(:string_arg, bytes, "binary data")
+      _write_raw(norm_name(name), TYPES[:binary], bytes)
+      nil
+    end
+
+    # Generic typed write — symmetric with #read; validates identically to the
+    # typed writers (it dispatches to them). :dword_be packs 4 bytes BE; :none
+    # expects bytes; :link raises (links are read-surface only in v1); a raw
+    # Integer tag goes through #write_raw.
+    def write(name, type, value)
+      case type
+      when :sz         then write_string(name, value)
+      when :expand_sz  then write_expand_string(name, value)
+      when :multi_sz   then write_multi_string(name, value)
+      when :dword      then write_dword(name, value)
+      when :qword      then write_qword(name, value)
+      when :dword_be
+        v = Winreg.send(:int_in_range, value, 0xFFFF_FFFF, "REG_DWORD_BIG_ENDIAN")
+        _write_raw(norm_name(name), TYPES[:dword_be], [v].pack("N"))
+      when :binary     then write_binary(name, value)
+      when :none
+        Winreg.send(:string_arg, value, ":none data")
+        _write_raw(norm_name(name), TYPES[:none], value)
+      when :link
+        raise ArgumentError, "winreg: :link values are read-surface only (v1); " \
+                             "registry symlink creation is out of scope"
+      when Integer     then write_raw(name, type, value)
+      else
+        raise ArgumentError, "winreg: unknown registry type #{type.inspect}"
+      end
+      nil
+    end
+
+    # Raw escape hatch, symmetric with #raw: exact bytes under an arbitrary
+    # type tag. No validation beyond bytes being a String + the 4 GiB guard.
+    def write_raw(name, type_tag, bytes)
+      raise TypeError, "winreg: type tag must be an Integer, got #{type_tag.inspect}" unless type_tag.is_a?(Integer)
+
+      Winreg.send(:string_arg, bytes, "raw data")
+      _write_raw(norm_name(name), type_tag, bytes)
+      nil
+    end
+
+    # Delete a value (nil/"" addresses the default value). NotFound if absent.
+    def delete_value(name)
+      _delete_value(norm_name(name))
+      nil
+    end
+
+    # ---- existence probes --------------------------------------------------
+
+    # RegQueryValueExW size probe; error 2 -> false.
+    def value?(name)
+      _value_p(norm_name(name))
+    end
+
+    # NotFound -> false; ACCESS_DENIED -> true (the key exists, you may not
+    # open it); anything else raises. View-consistent (probe carries the view).
+    def key?(name)
+      probe = _open_child(subpath_arg(name), Winreg::KEY_QUERY_VALUE)
+      probe.close
+      true
+    rescue Winreg::NotFound
+      false
+    rescue Winreg::AccessDenied
+      true
+    end
+
+    # ---- subkeys -----------------------------------------------------------
+
+    # Child open. Relative path, backslashes allowed ("A\\B"). The parent's
+    # WOW64 view is inherited automatically and CANNOT be overridden (the API
+    # encoding of the view-consistency rule). Block form ensure-closes.
+    def open(subpath, access: :read)
+      sam = Winreg.send(:access_mask, access)
+      k = _open_child(subpath_arg(subpath), sam)
+      k.send(:_init_meta, @root, child_subpath(subpath), @view)
+      return k unless block_given?
+
+      begin
+        yield k
+      ensure
+        k.close
+      end
+    end
+
+    # Child open-or-create, same view rules.
+    def create(subpath, access: :read_write)
+      sam = Winreg.send(:access_mask, access)
+      k = _create_child(subpath_arg(subpath), sam)
+      k.send(:_init_meta, @root, child_subpath(subpath), @view)
+      return k unless block_given?
+
+      begin
+        yield k
+      ensure
+        k.close
+      end
+    end
+
+    # Delete the named child subkey (handle-relative; the view is applied via
+    # RegDeleteKeyExW samDesired). Non-recursive delete of a key that still
+    # has subkeys fails with an OSError; recursive: true performs a deepest-
+    # first walk in Ruby over the raise-safe primitives (interruptible; NOT
+    # atomic — same as RegDeleteTreeW), with the view applied to every open.
+    def delete_key(name, recursive: false)
+      n = subpath_arg(name)
+      if recursive
+        _delete_tree(n)
+      else
+        begin
+          _delete_key(n)
+        rescue Winreg::AccessDenied => e
+          err = Winreg::AccessDenied.new("#{e.message} (key may have subkeys; use recursive: true)")
+          err.instance_variable_set(:@code, e.code)
+          raise err
+        end
+      end
+      nil
+    end
+
+    # ---- enumeration / metadata ---------------------------------------------
+
+    # Yields (name, type, value) decoded exactly as #read. Live, snapshot-less,
+    # kernel order arbitrary; concurrent mutation may skip or repeat entries.
+    # A value whose DATA is malformed raises MalformedValue mid-iteration —
+    # use #value_names + #raw for forensic robustness.
+    def each_value
+      return enum_for(:each_value) unless block_given?
+
+      i = 0
+      while (entry = _enum_value(i))
+        name, t, bytes = entry
+        yield name, Winreg.send(:type_symbol, t), Winreg.send(:decode_value, t, bytes)
+        i += 1
+      end
+      self
+    end
+
+    # Yields each subkey name.
+    def each_key
+      return enum_for(:each_key) unless block_given?
+
+      i = 0
+      while (name = _enum_key(i))
+        yield name
+        i += 1
+      end
+      self
+    end
+
+    # Value names only — never decodes data, so hostile values can't abort it.
+    def value_names
+      out = []
+      i = 0
+      while (entry = _enum_value(i))
+        out << entry[0]
+        i += 1
+      end
+      out
+    end
+
+    def key_names
+      out = []
+      each_key { |n| out << n }
+      out
+    end
+
+    def info
+      a = _query_info
+      t = Time.at((a[5] - Winreg.send(:filetime_epoch_delta)) / 10_000_000r)
+      Info.new(a[0], a[2], a[1], a[3], a[4], t).freeze
+    end
+
+    # ---- watching ------------------------------------------------------------
+
+    # Without a block: an armed Winreg::Watch (changes between construction
+    # and the first #wait are caught). With a block: loops, yielding :changed
+    # per coalesced change; yields :deleted once and returns if the watched
+    # key is deleted; the Watch is ensure-closed. The Watch opens its OWN
+    # private KEY_NOTIFY|view handle from this key's path — closing this Key
+    # afterwards does not disturb it.
+    def watch(subtree: false, filter: :default)
+      raise Winreg::Closed, "winreg: key is closed" if closed?
+
+      mask = Winreg.send(:filter_mask, filter)
+      vsam = Winreg.send(:view_mask, @view || :default)
+      w = Watch.send(:_new, @root, @subpath, vsam, subtree ? true : false, mask)
+      return w unless block_given?
+
+      begin
+        loop do
+          event = w.wait
+          yield event
+          break if event == :deleted
+        end
+        nil
+      ensure
+        w.close
+      end
+    end
+
+    private
+
+    # Set by the Ruby layer right after _open/_create — ivars, not native-
+    # struct VALUEs, so the rb_data_type_t needs no dmark.
+    def _init_meta(root, subpath, view)
+      @root = root
+      @subpath = subpath
+      @view = view
+      root_name = Winreg.send(:root_name, root)
+      @path = subpath ? "#{root_name}\\#{subpath}" : root_name
+      self
+    end
+
+    # Value names: String, or nil/"" for the key's default (unnamed) value
+    # ("" normalized to nil; C passes NULL).
+    def norm_name(name)
+      return nil if name.nil?
+      raise TypeError, "winreg: value name must be a String or nil, got #{name.inspect}" unless name.is_a?(String)
+
+      name.empty? ? nil : name
+    end
+
+    # Subkey names/paths must be real Strings (nil has no meaning here).
+    def subpath_arg(name)
+      raise TypeError, "winreg: subkey name must be a String, got #{name.inspect}" unless name.is_a?(String)
+      raise ArgumentError, "winreg: subkey name must not be empty" if name.empty?
+
+      name
+    end
+
+    def child_subpath(subpath)
+      @subpath ? "#{@subpath}\\#{subpath}" : subpath.dup
+    end
+
+    # Strict typed read: bytes if the stored tag is in +allowed+, else
+    # TypeMismatch naming expected vs actual.
+    def typed_bytes(name, allowed, expected_desc)
+      t, bytes = _read_raw(norm_name(name))
+      unless allowed.include?(t)
+        actual = Winreg.send(:type_symbol, t)
+        expected = allowed.map { |tag| Winreg.send(:type_symbol, tag).inspect }.join(" or ")
+        raise Winreg::TypeMismatch,
+              "winreg: value #{name.inspect} has type #{actual.inspect}, expected #{expected} " \
+              "(#{expected_desc})"
+      end
+      bytes
+    end
+
+    # Deepest-first recursive delete: always enumerate index 0 (children shift
+    # down as they are deleted); every child open is ensure-closed; interrupts
+    # are delivered between primitive calls (no C frame holds a child HKEY
+    # across a potential raise).
+    def _delete_tree(name)
+      child = _open_child(name, Winreg::KEY_READ)
+      begin
+        while (sub = child.send(:_enum_key, 0))
+          child.send(:_delete_tree, sub)
+        end
+      ensure
+        child.close
+      end
+      _delete_key(name)
+    end
+  end
+
+  # A change-notification registration (constructed only via Key#watch).
+  # Armed at construction and re-armed before every delivery, so no final
+  # state is ever missed; deliveries coalesce (:changed means ">= 1 matching
+  # change since the previous delivery") and carry no payload.
+  class Watch
+    private_class_method :_new
+
+    # -> :changed (rearmed; ready to wait again)
+    #    :deleted (watched key was deleted; the watch auto-closes)
+    #    nil      (timeout elapsed; registration still armed)
+    # timeout in seconds (nil = infinite). Cooperates with a fiber scheduler
+    # via Winreg.run_blocking; standalone it releases the GVL and is
+    # interruptible. Raises Closed if closed (incl. closed by another thread
+    # mid-wait); Winreg::Error if another wait is already in flight
+    # (single-waiter); OSError on a rearm failure other than ERROR_KEY_DELETED.
+    def wait(timeout: nil)
+      ms = Winreg.ms_for(timeout)
+      Winreg.run_blocking { _wait(ms) }
+    end
+  end
+
+  # ---- internal codecs (validation + exact wire formats) -------------------
+  # These are module-private: the public surface is Key's typed methods.
+
+  def type_symbol(tag)
+    TYPE_NAMES[tag] || tag
+  end
+  private_class_method :type_symbol
+
+  def root_name(root)
+    ROOT_NAMES[root]
+  end
+  private_class_method :root_name
+
+  def filetime_epoch_delta
+    FILETIME_EPOCH_DELTA
+  end
+  private_class_method :filetime_epoch_delta
+
+  def decode_value(tag, bytes)
+    case tag
+    when TYPES[:sz], TYPES[:expand_sz] then decode_string(bytes)
+    when TYPES[:multi_sz]              then decode_multi(bytes)
+    when TYPES[:dword]                 then decode_int(bytes, 4, false, :dword)
+    when TYPES[:dword_be]              then decode_int(bytes, 4, true, :dword_be)
+    when TYPES[:qword]                 then decode_int(bytes, 8, false, :qword)
+    else bytes # :binary, :none, :link, unknown tags: raw BINARY bytes
+    end
+  end
+  private_class_method :decode_value
+
+  # E1: returned bytes are ground truth; strip AT MOST one trailing UTF-16 NUL
+  # code unit (never an unconditional chop — unterminated values round-trip).
+  # E2/E3: odd byte counts and invalid UTF-16 raise MalformedValue.
+  def decode_string(bytes)
+    if bytes.bytesize.odd?
+      raise MalformedValue,
+            "winreg: string value has an odd byte count (#{bytes.bytesize})"
+    end
+    b = bytes
+    b = b.byteslice(0, b.bytesize - 2) if b.bytesize >= 2 && b.getbyte(-1).zero? && b.getbyte(-2).zero?
+    utf16le_to_utf8(b)
+  end
+  private_class_method :decode_string
+
+  # E6: tolerate missing final terminator, 0-byte data, and excess
+  # terminators — decode the whole buffer, split on NUL, stop at the first
+  # empty element (an empty string terminates the list by definition).
+  def decode_multi(bytes)
+    if bytes.bytesize.odd?
+      raise MalformedValue,
+            "winreg: REG_MULTI_SZ value has an odd byte count (#{bytes.bytesize})"
+    end
+    return [] if bytes.empty?
+
+    out = []
+    utf16le_to_utf8(bytes).split("\0", -1).each do |part|
+      break if part.empty?
+
+      out << part
+    end
+    out
+  end
+  private_class_method :decode_multi
+
+  def decode_int(bytes, size, big_endian, type)
+    unless bytes.bytesize == size
+      raise MalformedValue,
+            "winreg: #{type.inspect} value has #{bytes.bytesize} bytes (expected #{size})"
+    end
+    if size == 4
+      bytes.unpack1(big_endian ? "N" : "V")
+    else
+      bytes.unpack1("Q<")
+    end
+  end
+  private_class_method :decode_int
+
+  def utf16le_to_utf8(bytes)
+    bytes.dup.force_encoding(Encoding::UTF_16LE).encode(Encoding::UTF_8)
+  rescue EncodingError => e
+    raise MalformedValue, "winreg: string value is not valid UTF-16LE (#{e.message})"
+  end
+  private_class_method :utf16le_to_utf8
+
+  # Writers: NUL/empty-element validation BEFORE encoding; Encoding::*Error
+  # surfaces as ArgumentError (with cause).
+  def encode_sz(str)
+    string_arg(str, "string data")
+    raise ArgumentError, "winreg: string data must not contain an embedded NUL" if str.include?("\0")
+
+    utf8_to_utf16le(str) + "\0\0".b
+  end
+  private_class_method :encode_sz
+
+  def encode_multi(ary)
+    raise TypeError, "winreg: multi_string takes an Array of Strings, got #{ary.inspect}" unless ary.is_a?(Array)
+
+    ary.each do |el|
+      unless el.is_a?(String)
+        raise ArgumentError, "winreg: multi_string elements must be Strings, got #{el.inspect}"
+      end
+      if el.empty?
+        raise ArgumentError, "winreg: multi_string elements must not be empty " \
+                             "(an empty element terminates the list)"
+      end
+      if el.include?("\0")
+        raise ArgumentError, "winreg: multi_string elements must not contain an embedded NUL"
+      end
+    end
+    return "\0\0".b if ary.empty? # the 2-byte empty list
+
+    ary.map { |el| utf8_to_utf16le(el) + "\0\0".b }.join + "\0\0".b
+  end
+  private_class_method :encode_multi
+
+  def utf8_to_utf16le(str)
+    str.encode(Encoding::UTF_16LE).force_encoding(Encoding::BINARY)
+  rescue EncodingError
+    raise ArgumentError, "winreg: string data cannot be encoded as UTF-16"
+  end
+  private_class_method :utf8_to_utf16le
+
+  def int_in_range(value, max, what)
+    raise TypeError, "winreg: #{what} value must be an Integer, got #{value.inspect}" unless value.is_a?(Integer)
+    unless value >= 0 && value <= max
+      raise RangeError, "winreg: #{what} must be in 0..#{max} (got #{value}); " \
+                        "registry integers are unsigned"
+    end
+    value
+  end
+  private_class_method :int_in_range
+
+  def string_arg(value, what)
+    raise TypeError, "winreg: #{what} must be a String, got #{value.inspect}" unless value.is_a?(String)
+
+    value
+  end
+  private_class_method :string_arg
+end